diff --git a/apps/web/contents/addons/updates.mdx b/apps/web/contents/addons/updates.mdx index 55a1cb6..e8eb82c 100644 --- a/apps/web/contents/addons/updates.mdx +++ b/apps/web/contents/addons/updates.mdx @@ -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. -Enabled, reviewed v1 Markdown content can be opened at the site's dedicated `/docs/addons//` route (or `/addons//` 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//` route (or `/addons//` 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. For details see [Account Mode marketplace](/addons/marketplace) and [runtime API](/addons/api). diff --git a/packages/nextguide/lib/account-addon-index-template.mjs b/packages/nextguide/lib/account-addon-index-template.mjs new file mode 100644 index 0000000..11d1802 --- /dev/null +++ b/packages/nextguide/lib/account-addon-index-template.mjs @@ -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 +} diff --git a/packages/nextguide/lib/account-starter.mjs b/packages/nextguide/lib/account-starter.mjs index 9c070bf..671b78b 100644 --- a/packages/nextguide/lib/account-starter.mjs +++ b/packages/nextguide/lib/account-starter.mjs @@ -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. @@ -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 diff --git a/packages/nextguide/lib/extension-site-manager.d.mts b/packages/nextguide/lib/extension-site-manager.d.mts index f32b9c6..65ce181 100644 --- a/packages/nextguide/lib/extension-site-manager.d.mts +++ b/packages/nextguide/lib/extension-site-manager.d.mts @@ -56,6 +56,7 @@ export declare function createAccountAddonManager(options?: { expectedRevision: number consent: true }): {revision: number; removed: string; privateDataPreserved: true} + publicPages(): Promise> readEnabled(input: {id: string}): Promisex.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") diff --git a/packages/nextguide/test/account-init.test.mjs b/packages/nextguide/test/account-init.test.mjs index e8bfe91..258d97b 100644 --- a/packages/nextguide/test/account-init.test.mjs +++ b/packages/nextguide/test/account-init.test.mjs @@ -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") diff --git a/packages/nextguide/test/extension-site-manager.test.mjs b/packages/nextguide/test/extension-site-manager.test.mjs index 83d8159..545d1c4 100644 --- a/packages/nextguide/test/extension-site-manager.test.mjs +++ b/packages/nextguide/test/extension-site-manager.test.mjs @@ -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) @@ -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() } +})