@norskvideo/ctl-dev-kit 0.1.80 → 0.1.81

package/conventions/docs.md

@@ -148,6 +148,25 @@ single-sourced here and drift-gated:
   refuses a repo carrying both, and refuses the public variant when it cannot
   tell the repo's name (`GITHUB_REPOSITORY` in CI, the origin remote locally).
 
+### Per-page visibility
+
+Every page in `bundle.json` carries a `visibility`, `public` or `possession`,
+defaulting to the bundle's own (`buildBundle(spec, { visibility })`, itself
+`public`). The public fetcher stages only the public pages; the image serves all
+of them either way, so `possession` means "reaches customers only inside the
+image they already run".
+
+**No page is special-cased — mark `possession` only when you mean it.** In
+particular `known-limitations` is not the page to hide: a candid limitations
+page is a trust asset for a public product, and hiding the honest page is an odd
+signal to an evaluator.
+
+This is not what protects a turnkey, and must not be read as if it were. Turnkey
+privacy is a repo/bundle-level guarantee — the `^norsk-ctl-product-` repo-name
+rule, the registry's `docsVisibility`, the per-repo workflow variant, and the
+fetcher's own gate. A turnkey's whole bundle never reaches the public plane
+whatever its pages say.
+
 Either way the image serves the bundle at `/docs` (SDK `serveDocs`), reached
 through the daemon at `/products/<name>/docs/` behind its auth guard and linked
 from the product's hub via `ui.sidebarEntries`. That is the sole channel for a

package/doc-guide/build-manual.d.ts

@@ -4,6 +4,13 @@ export type Step = {
     head: string;
     desc: string;
 };
+/** Where a page may be read. `public` reaches the public docs site; `possession`
+ *  reaches customers only inside the image they already run. PUBLIC is the
+ *  default and no page is special-cased -- a candid limitations page is a trust
+ *  asset, and hiding the honest page is an odd signal to an evaluator (fleet
+ *  review 03 open question 3). Turnkey privacy is a repo/bundle-level
+ *  guarantee, never this field. */
+export type PageVisibility = "public" | "possession";
 export type ManualPage = {
     id: string;
     nav: string;
@@ -14,6 +21,8 @@ export type ManualPage = {
     steps: Step[];
     links: string[];
     thin?: boolean;
+    /** Overrides the bundle's visibility for this page alone. */
+    visibility?: PageVisibility;
 };
 export interface ManualOverview {
     /** The overview <h1>. */
@@ -50,6 +59,8 @@ export interface ManualDocument {
     nav: string;
     title: string;
     markdown: string;
+    /** Overrides the bundle's visibility for this page alone. */
+    visibility?: PageVisibility;
 }
 export interface ManualSpec {
     /** Sidebar wordmark + document brand. */

package/doc-guide/bundle.d.ts

@@ -1,5 +1,6 @@
-import { type BuildManualResult, type ManualLink, type ManualSpec, type Provenance } from "./build-manual.js";
-export declare const BUNDLE_SCHEMA_VERSION = 1;
+import { type BuildManualResult, type ManualLink, type ManualSpec, type PageVisibility, type Provenance } from "./build-manual.js";
+export type { PageVisibility };
+export declare const BUNDLE_SCHEMA_VERSION = 2;
 export interface BundlePageEntry {
     id: string;
     nav: string;
@@ -7,11 +8,15 @@ export interface BundlePageEntry {
     kind: "overview" | "fn" | "ex" | "doc";
     /** Relative to the bundle directory. */
     file: string;
+    /** Resolved: the page's own value, else the bundle's. */
+    visibility: PageVisibility;
 }
 export interface BundleManifest {
     schemaVersion: number;
     brand: string;
     title: string;
+    /** The default every page inherits when it declares none. */
+    visibility: PageVisibility;
     provenance: Provenance;
     links: ManualLink[];
     pages: BundlePageEntry[];
@@ -29,9 +34,16 @@ export interface BuildBundleOptions {
     /** Where the bundle is written; created if absent. */
     outDir: string;
     provenance?: Provenance;
+    /** Default visibility for every page that declares none. Public: turnkey
+     *  privacy is enforced at the repo and bundle level, not page by page. */
+    visibility?: PageVisibility;
 }
 export interface BuildBundleResult extends BuildManualResult {
     manifest: BundleManifest;
     outDir: string;
 }
 export declare function buildBundle(spec: ManualSpec, opts: BuildBundleOptions): BuildBundleResult;
+/** What the public fetcher may stage. A page entry from a version-1 bundle
+ *  carries no visibility at all; that reads as `public`, so an older bundle
+ *  stages exactly as it did before this field existed. */
+export declare function publicPages(manifest: BundleManifest): BundlePageEntry[];

package/doc-guide/bundle.js

@@ -13,10 +13,14 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { buildManual, } from "./build-manual.js";
-export const BUNDLE_SCHEMA_VERSION = 1;
+// 2: every page entry carries a `visibility`, and the manifest carries the
+// bundle's own. A version-1 bundle has neither; `publicPages` reads an absent
+// value as `public`, so an old bundle stages exactly as it did before.
+export const BUNDLE_SCHEMA_VERSION = 2;
 const yamlString = (s) => JSON.stringify(s);
 export function buildBundle(spec, opts) {
     const { docsRoot, outDir } = opts;
+    const visibility = opts.visibility ?? "public";
     const provenance = { builtAt: new Date().toISOString(), ...opts.provenance };
     mkdirSync(join(outDir, "pages"), { recursive: true });
     const manual = buildManual(spec, {
@@ -78,9 +82,23 @@ export function buildBundle(spec, opts) {
     ].join("\n");
     const documentMarkdown = (d) => ["---", `title: ${yamlString(d.title)}`, `nav: ${yamlString(d.nav)}`, "kind: doc", "---", "", d.markdown].join("\n");
     const pages = [
-        { id: "overview", nav: "Overview", title: ov.headline, kind: "overview", file: "pages/overview.md" },
-        ...all.map((p) => ({ id: p.id, nav: p.nav, title: p.title, kind: p.kind, file: `pages/${p.id}.md` })),
-        ...docs.map((d) => ({ id: d.id, nav: d.nav, title: d.title, kind: "doc", file: `pages/${d.id}.md` })),
+        { id: "overview", nav: "Overview", title: ov.headline, kind: "overview", file: "pages/overview.md", visibility },
+        ...all.map((p) => ({
+            id: p.id,
+            nav: p.nav,
+            title: p.title,
+            kind: p.kind,
+            file: `pages/${p.id}.md`,
+            visibility: p.visibility ?? visibility,
+        })),
+        ...docs.map((d) => ({
+            id: d.id,
+            nav: d.nav,
+            title: d.title,
+            kind: "doc",
+            file: `pages/${d.id}.md`,
+            visibility: d.visibility ?? visibility,
+        })),
     ];
     writeFileSync(join(outDir, "pages/overview.md"), overviewMarkdown);
     for (const p of all)
@@ -94,6 +112,7 @@ export function buildBundle(spec, opts) {
         schemaVersion: BUNDLE_SCHEMA_VERSION,
         brand: spec.brand,
         title: spec.title,
+        visibility,
         provenance,
         links: spec.links ?? [],
         pages,
@@ -103,3 +122,9 @@ export function buildBundle(spec, opts) {
     writeFileSync(join(outDir, "bundle.json"), `${JSON.stringify(manifest, null, 2)}\n`);
     return { ...manual, manifest, outDir };
 }
+/** What the public fetcher may stage. A page entry from a version-1 bundle
+ *  carries no visibility at all; that reads as `public`, so an older bundle
+ *  stages exactly as it did before this field existed. */
+export function publicPages(manifest) {
+    return manifest.pages.filter((p) => (p.visibility ?? "public") === "public");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.80",
+  "version": "0.1.81",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",