Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/web/contents/addons/updates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ The owner-facing **Add-ons** page can install, enable/disable, update, roll back
Owner authentication and same-origin checks apply to every mutation. A concurrent change requires refreshing the page rather than overwriting another update. A revoked or stale release cannot be reactivated or rolled back.

<Callout kind="warning" title="Current milestone boundaries">
Enabled, reviewed v1 Markdown content can be opened at the site's dedicated `/docs/addons/<publisher.addon>/` route (or `/addons/<id>/` when the docs base is root). Add-on pages do not yet join the public docs sidebar and search index. Executable add-ons, privileged permissions, secrets, React components and automatic background update checks remain future milestones. Legacy v1 content is never compiled as untrusted MDX.
Enabled, reviewed v1 Markdown content can be opened at the site's dedicated `/docs/addons/<publisher.addon>/` route (or `/addons/<id>/` when the docs base is root). Fresh Account Mode installations now include enabled and still-approved Markdown pages in their public docs sidebar and search index. Pages are excluded when disabled, revoked, corrupted or no longer covered by a fresh signed registry. Already-installed sites need an explicit generated-file refresh to receive the updated navigation adapter; authored MDX must not be overwritten. Executable add-ons, privileged permissions, secrets, React components and automatic background update checks remain future milestones. Legacy v1 content is never compiled as untrusted MDX.
</Callout>

For details see [Account Mode marketplace](/addons/marketplace) and [runtime API](/addons/api).
17 changes: 17 additions & 0 deletions packages/nextguide/lib/account-addon-index-template.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
/** Account Mode only: augment generated navigation/search with approved Markdown. */
const TAIL = "\n/** Per-request cache: one signed catalog fetch for sidebar and search. */\nconst getInstalledAddonPages = cache(async () => {\n try {\n return await createAccountAddonManager({ project: process.cwd() }).publicPages()\n } catch {\n // No unsigned/stale fallback; keep core docs usable if registry is offline.\n return []\n }\n})\nexport async function getSidebar() {\n const [baseSections, verifiedPages] = await Promise.all([\n getBaseSidebar(), getInstalledAddonPages(),\n ])\n if (!verifiedPages.length) return baseSections\n const ids = [...new Set(verifiedPages.map(page => page.id))]\n const addonItems = ids.map(id => {\n const pages = verifiedPages.filter(page => page.id === id)\n const path = prefix + \"/addons/\" + encodeURIComponent(id)\n return {\n title: pages[0].group,\n href: path + \"/\",\n nav: true, props: {},\n items: pages.map(page => ({\n title: page.title,\n href: path + \"/\" + (page.slug ? page.slug.split(\"/\").map(encodeURIComponent).join(\"/\") + \"/\" : \"\"),\n nav: true, props: {}, items: [],\n })),\n }\n })\n return [...baseSections, section(\"Add-ons\", \"#addons\", addonItems)]\n}\nexport async function getSearchIndex() {\n const [baseEntries, verifiedPages] = await Promise.all([\n getBaseSearchIndex(), getInstalledAddonPages(),\n ])\n return [...baseEntries, ...verifiedPages.map(page => ({\n href: prefix + \"/addons/\" + encodeURIComponent(page.id) + \"/\" +\n (page.slug ? page.slug.split(\"/\").map(encodeURIComponent).join(\"/\") + \"/\" : \"\"),\n title: page.title,\n section: \"Add-ons\",\n group: page.group,\n keywords: page.markdown,\n }))]\n}\n"
const IMPORTS = "\nimport { cache } from \"react\"\nimport { createAccountAddonManager } from \"nextguide/extensions/site-manager\""
export function accountAddonNavigationLibSource(original) {
if (typeof original !== "string" ||
!original.includes('import { createDocs } from "nextguide/mdx"') ||
!original.includes("export async function getSidebar() {") ||
!original.includes("export async function getSearchIndex() {")) {
throw Error("Generated NextGuide docs library cannot be extended safely")
}
return original
.replace('import { createDocs } from "nextguide/mdx"',
'import { createDocs } from "nextguide/mdx"' + IMPORTS)
.replace("export async function getSidebar() {", "async function getBaseSidebar() {")
.replace("export async function getSearchIndex() {", "async function getBaseSearchIndex() {") +
"\n" + TAIL
}
5 changes: 5 additions & 0 deletions packages/nextguide/lib/account-starter.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { accountFile, createBootstrap } from "./account-auth.mjs"
import { applyPlan, planDeveloperProject } from "./init.mjs"
import { fullStudioRouteSource } from "./account-studio-template.mjs"
import { accountAddonDocsRouteSource } from "./account-addon-page-template.mjs"
import { accountAddonNavigationLibSource } from "./account-addon-index-template.mjs"
import { installMonacoAssets } from "./monaco-assets.mjs"

const PAGE = `// Generated by NextGuide CLI. Edit freely; NextGuide never overwrites these files.
Expand Down Expand Up @@ -214,6 +215,10 @@ export function initAccount(projectDirectory, inspection, options = {}) {
const config = JSON.parse(plan.files["nextguide.config.json"])
config.mode = "account"
plan.files["nextguide.config.json"] = JSON.stringify(config, null, 2) + "\n"
// Only Account Mode extends the public sidebar/search with signed v1 add-ons.
const libRoot = plan.router.folder.startsWith("src/") ? "src/" : ""
const docsLib = libRoot + "lib/nextguide." + (plan.typed ? "ts" : "js")
plan.files[docsLib] = accountAddonNavigationLibSource(plan.files[docsLib])
const extra = accountStarterFiles(plan.router.folder, plan.typed, plan.basePath)
Object.assign(plan.files, extra)
// Account Mode must never statically cache its sidebar, page index, site title
Expand Down
1 change: 1 addition & 0 deletions packages/nextguide/lib/extension-site-manager.d.mts
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ export declare function createAccountAddonManager(options?: {
expectedRevision: number
consent: true
}): {revision: number; removed: string; privateDataPreserved: true}
publicPages(): Promise<Array<{id: string; version: string; slug: string; title: string; group: string; markdown: string}>>
readEnabled(input: {id: string}): Promise<null | {
id: string
version: string
Expand Down
40 changes: 40 additions & 0 deletions packages/nextguide/lib/extension-site-manager.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,46 @@ export function createAccountAddonManager({
requireConsent(consent)
return store.uninstall({id,expectedRevision})
},
/**
* Public Account Mode docs index. Only enabled v1 Markdown from fresh,
* active, signature-verified releases is returned. One signed catalog
* fetch is shared for all installed add-ons; no unsigned/stale fallback.
* Navigation/search consumers MUST NOT compile this content as MDX.
*/
async publicPages() {
const enabled=store.list().addons.filter(x=>x.enabled)
if (!enabled.length) return []
const {envelope}=await signed()
const pages=[]
for (const addon of enabled) {
// A single revoked or corrupt entry must never leak stale content.
// Keep unrelated verified add-ons discoverable.
try {
const verified=store.readEnabled({
id:addon.id,envelope,pinnedPublicKeyPem
})
if (!verified) continue
const root=verified.manifest.entrypoints.content+"/"
for (const page of verified.pages) {
if (!page.path.startsWith(root)) continue
const name=page.path.slice(root.length,-3)
if (!name || name.length>180) continue
const label=name==="index" ? verified.manifest.name :
name.split("/").at(-1).replace(/[-_]/g," ")
pages.push({
id:addon.id,version:verified.version,
slug:name==="index" ? "" : name,
title:label,group:verified.manifest.name,
markdown:page.markdown.slice(0,3500),
})
}
} catch {
// Already enabled but no longer approved, malformed or missing:
// exclude from public search/navigation until owner resolves it.
}
}
return pages.slice(0,500)
},
/** Privileged API for a future safe Markdown-only public page adapter. */
async readEnabled({id}={}) {
if (typeof id!=="string" || !ID.test(id)) reject("INVALID_REQUEST","Invalid add-on ID")
Expand Down
7 changes: 7 additions & 0 deletions packages/nextguide/test/account-init.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,13 @@ test("App Router Account Mode scaffolds protected routes and owner token without
assert.match(source, /next\/font\/google/, route + " should self-host Inter")
assert.match(source, /--ng-preview-inter/, route + " should supply the Account Mode font variable")
}
const docsSource = readFileSync(join(project, "src/lib/nextguide.ts"), "utf8")
assert.match(docsSource, /getInstalledAddonPages/)
assert.match(docsSource, /createAccountAddonManager/)
assert.match(docsSource, /async function getBaseSidebar/)
assert.match(docsSource, /async function getBaseSearchIndex/)
assert.match(docsSource, /section\("Add-ons", "#addons"/)
assert.match(docsSource, /section: "Add-ons"/)
assert.ok(existsSync(join(project, "src/app/admin/page.tsx")))
const addOnRoute = readFileSync(join(project,
"src/app/docs/addons/[id]/[[...page]]/page.tsx"), "utf8")
Expand Down
23 changes: 22 additions & 1 deletion packages/nextguide/test/extension-site-manager.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ test("owner catalog includes exact compatibility and durable installed state",as
const enabled=await f.manager.toggle({id:"acme.docs",enabled:true,expectedRevision:1})
assert.equal(enabled.addon.enabled,true)
const approved=await f.manager.readEnabled({id:"acme.docs"})
assert.match(approved.pages[0].markdown,/Welcome 1\.0\.0/)
assert.ok(approved.pages[0].markdown.includes("Welcome 1.0.0"))
const disabled=await f.manager.toggle({id:"acme.docs",enabled:false,expectedRevision:2})
assert.equal(disabled.addon.enabled,false)
assert.equal(await f.manager.readEnabled({id:"acme.docs"}),null)
Expand Down Expand Up @@ -194,3 +194,24 @@ test("stale signed metadata, incompatible alpha versions and revoked releases ar
assert.equal(revoked.network.calls.length,0)
}finally{revoked.cleanup()}
})

test("public navigation includes only explicitly enabled signed Markdown pages",async()=>{
const a=versioned("1.0.0")
const f=fixture({signedReleases:signed([a.release]),artifacts:[a]})
try {
assert.deepEqual(await f.manager.publicPages(),[])
assert.equal(f.network.calls.length,0,"disabled add-ons do not need registry requests")
await f.manager.install({id:"acme.docs",version:"1.0.0",expectedRevision:0,consent:true})
assert.deepEqual(await f.manager.publicPages(),[])
await f.manager.toggle({id:"acme.docs",enabled:true,expectedRevision:1})
const pages=await f.manager.publicPages()
assert.equal(pages.length,1)
assert.deepEqual(Object.keys(pages[0]).sort(),["group","id","markdown","slug","title","version"])
assert.equal(pages[0].id,"acme.docs")
assert.equal(pages[0].title,"Docs Extension")
assert.equal(pages[0].slug,"")
assert.ok(pages[0].markdown.includes("Welcome 1.0.0"))
await f.manager.toggle({id:"acme.docs",enabled:false,expectedRevision:2})
assert.deepEqual(await f.manager.publicPages(),[])
} finally { f.cleanup() }
})
Loading