@norskvideo/ctl-dev-kit 0.1.80 → 0.1.82

package/conventions/docs.md

@@ -138,16 +138,46 @@ single-sourced here and drift-gated:
   image as the proof. No upload, no write permission on the repo, no token. A
   turnkey (`norsk-ctl-turnkey-*`) carries this and nothing else: its
   documentation reaches exactly one customer, inside the image they already run.
-- **`publish-docs.yml` — public.** The same build, then `manual.html` is
-  published as the asset of the moving `docs-latest` GitHub Release
-  (`https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html`)
-  for norsk-ctl's docs site to fetch and mount at `/products/<slug>/`. Versioned
-  bundle assets behind a `latest` pointer, and ingestion of `pages/*.md` into the
-  site, come with the public-plane work. **Only a repo GitHub calls
-  `norsk-ctl-product-*` may carry it.** `check:drift` refuses it anywhere else,
+- **`publish-docs.yml` — public.** The same build, then three things on one
+  moving `docs-latest` GitHub Release:
+  - `manual.html`, clobbered each night — what norsk-ctl's docs site fetches and
+    mounts at `/products/<slug>/`
+    (`https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html`).
+  - `bundle-<version>.tar.gz`, the whole bundle, named by the product commit it
+    was built from, plus `latest.json` naming the current one. Versioned assets
+    on ONE release rather than a release per commit: a release per commit would
+    leave hundreds of prereleases on the repo, and a single clobbered asset would
+    leave nothing to roll back to. Only the pointer moves, so a rollback is a
+    pointer edit and the site never reads an asset being overwritten underneath
+    it. `BUNDLE_KEEP` older bundles are pruned, never the one the pointer names.
+  - a `product-docs-published` `repository_dispatch` to `id3as/norsk-ctl`, so the
+    public site rebuilds rather than waiting for its own cron. The payload
+    carries the repo, not a product key — norsk-ctl resolves the key through
+    ci-workflows' registry, so a new product needs no new mapping.
+
+  **Only a repo GitHub calls `norsk-ctl-product-*` may carry it.** `check:drift` refuses it anywhere else,
   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/conventions/publish-docs.yml

@@ -177,3 +177,64 @@ jobs:
             gh release upload docs-latest "$RUNNER_TEMP/manual.html" --clobber
             echo "published -> docs-latest/manual.html"
           '
+
+      # The docs BUNDLE, versioned, behind a moving pointer on the SAME release
+      # (fleet review 03 s3.5 slice 6). `manual.html` above is unchanged -- it is
+      # what today's ctl docs site mounts at /products/<key>/ -- and this is what
+      # the public plane ingests as pages.
+      #
+      # Versioned assets on one release, not a release per commit: a release per
+      # commit would leave hundreds of prereleases on each product repo, and a
+      # single clobbered asset would leave nothing to roll back to. Only
+      # latest.json moves, so a rollback is a pointer edit and the ctl site never
+      # reads an asset being overwritten underneath it.
+      #
+      # Bun.resolveSync rather than a node_modules path: it honours the package's
+      # exports map, so this works whether ctl-dev-kit is the published package or
+      # a workspace link (scripts/set-ctl-source.ts local mode).
+      - name: Publish the versioned docs bundle and move the pointer
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # How many bundles to keep on the release, the current one included.
+          BUNDLE_KEEP: "5"
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bundle="docs/generated/bundle"
+            [ -s "$bundle/bundle.json" ] || { echo "::error::no docs bundle at $bundle/bundle.json"; exit 1; }
+            rel="$(bun -e "console.log(Bun.resolveSync(\"@norskvideo/ctl-dev-kit/doc-guide/docs-release\", process.cwd()))")"
+            version="$(bun "$rel" version "$GITHUB_SHA")"
+            asset="$(bun "$rel" asset "$version")"
+            tar -czf "$RUNNER_TEMP/$asset" -C "$bundle" .
+            gh release upload docs-latest "$RUNNER_TEMP/$asset" --clobber
+            bun "$rel" pointer --version "$version" --sha "$GITHUB_SHA" \
+              --run-id "$GITHUB_RUN_ID" --built-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$RUNNER_TEMP/latest.json"
+            gh release upload docs-latest "$RUNNER_TEMP/latest.json" --clobber
+            gh release view docs-latest --json assets \
+              --jq "[.assets[] | {name: .name, createdAt: .createdAt}]" \
+              | bun "$rel" prune "$BUNDLE_KEEP" "$asset" \
+              | while read -r old; do
+                  echo "pruning $old"
+                  gh release delete-asset docs-latest "$old" --yes
+                done
+            echo "published -> docs-latest/$asset, pointer moved"
+          '
+
+      # Wake the public docs site rather than making it wait for its own cron.
+      # CI_DISPATCH_TOKEN, not GITHUB_TOKEN: repository_dispatch to ANOTHER repo
+      # needs Contents: write there, and the built-in token is scoped to this one.
+      # The payload carries the repo, not a product key: norsk-ctl resolves the
+      # key through ci-workflows' registry, so a new product needs no new mapping
+      # here. Not wrapped in nix -- plain curl, and the quoting stays readable.
+      - name: Tell norsk-ctl a new bundle is published
+        env:
+          DISPATCH_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
+        run: |
+          set -euo pipefail
+          body="$(printf '{"event_type":"product-docs-published","client_payload":{"repo":"%s"}}' "$GITHUB_REPOSITORY")"
+          code="$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: Bearer $DISPATCH_TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/id3as/norsk-ctl/dispatches" -d "$body")"
+          [ "$code" = "204" ] || { echo "::error::docs-published dispatch to norsk-ctl failed (HTTP $code)"; exit 1; }
+          echo "dispatched product-docs-published -> id3as/norsk-ctl"

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/doc-guide/docs-release.d.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+/**
+ * How a product publishes its docs bundle for the public plane to fetch
+ * (fleet review 03 s3.5 slice 6, product half). Used by
+ * conventions/publish-docs.yml, which every public product repo copies
+ * verbatim.
+ *
+ * Versioned assets behind a moving pointer, all on the ONE `docs-latest`
+ * release. A release per commit would leave hundreds of prereleases on each
+ * product repo; a single clobbered asset would leave nothing to roll back to.
+ * Only the pointer moves, so a rollback is a pointer edit and the ctl site
+ * never reads an asset being overwritten underneath it.
+ *
+ * `manual.html` stays on the same release, clobbered as before: it is what the
+ * current ctl fetcher mounts at /products/<key>/, and it keeps working
+ * unchanged while the bundle ingestion is built.
+ */
+export interface BundlePointer {
+    /** Short product commit — the bundle's identity. */
+    version: string;
+    /** The release asset holding that bundle. */
+    asset: string;
+    /** Full product commit the bundle was built from. */
+    sha: string;
+    runId?: string;
+    builtAt: string;
+}
+export declare const DOCS_RELEASE_TAG = "docs-latest";
+export declare const POINTER_ASSET = "latest.json";
+export declare function bundleVersion(sha: string): string;
+export declare function bundleAssetName(version: string): string;
+export declare function pointerJson(p: BundlePointer): string;
+export declare function parsePointer(json: string): BundlePointer;
+/** Which versioned bundles to delete, newest `keep` kept. Only ever names
+ *  `bundle-<version>.tar.gz` assets — `manual.html` and the pointer are the
+ *  release's fixtures — and never the one the pointer currently names, which
+ *  would leave the site fetching a 404. */
+export declare function assetsToPrune(assets: readonly {
+    name: string;
+    createdAt: string;
+}[], keep: number, current: string): string[];

package/doc-guide/docs-release.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env bun
+/**
+ * How a product publishes its docs bundle for the public plane to fetch
+ * (fleet review 03 s3.5 slice 6, product half). Used by
+ * conventions/publish-docs.yml, which every public product repo copies
+ * verbatim.
+ *
+ * Versioned assets behind a moving pointer, all on the ONE `docs-latest`
+ * release. A release per commit would leave hundreds of prereleases on each
+ * product repo; a single clobbered asset would leave nothing to roll back to.
+ * Only the pointer moves, so a rollback is a pointer edit and the ctl site
+ * never reads an asset being overwritten underneath it.
+ *
+ * `manual.html` stays on the same release, clobbered as before: it is what the
+ * current ctl fetcher mounts at /products/<key>/, and it keeps working
+ * unchanged while the bundle ingestion is built.
+ */
+export const DOCS_RELEASE_TAG = "docs-latest";
+export const POINTER_ASSET = "latest.json";
+const VERSION_LENGTH = 12;
+const BUNDLE_ASSET_RE = /^bundle-[0-9a-f]{12}\.tar\.gz$/;
+export function bundleVersion(sha) {
+    return sha.slice(0, VERSION_LENGTH);
+}
+export function bundleAssetName(version) {
+    return `bundle-${version}.tar.gz`;
+}
+export function pointerJson(p) {
+    return `${JSON.stringify(p, null, 2)}\n`;
+}
+export function parsePointer(json) {
+    const parsed = JSON.parse(json);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw new Error("docs pointer: expected an object");
+    const p = parsed;
+    for (const field of ["version", "asset", "sha", "builtAt"])
+        if (typeof p[field] !== "string")
+            throw new Error(`docs pointer: missing ${field}`);
+    return {
+        version: p.version,
+        asset: p.asset,
+        sha: p.sha,
+        builtAt: p.builtAt,
+        ...(p.runId === undefined ? {} : { runId: p.runId }),
+    };
+}
+/** Which versioned bundles to delete, newest `keep` kept. Only ever names
+ *  `bundle-<version>.tar.gz` assets — `manual.html` and the pointer are the
+ *  release's fixtures — and never the one the pointer currently names, which
+ *  would leave the site fetching a 404. */
+export function assetsToPrune(assets, keep, current) {
+    const bundles = assets
+        .filter((a) => BUNDLE_ASSET_RE.test(a.name) && a.name !== current)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    // The current bundle is always kept and counts towards `keep`, so only
+    // `keep - 1` of the older ones survive.
+    return bundles
+        .slice(Math.max(0, keep - 1))
+        .map((a) => a.name)
+        .sort();
+}
+if (import.meta.main) {
+    const argv = process.argv.slice(2);
+    const [cmd, a, b] = argv;
+    const flag = (name) => {
+        const i = argv.indexOf(`--${name}`);
+        return i === -1 ? undefined : argv[i + 1];
+    };
+    if (cmd === "version" && a) {
+        console.log(bundleVersion(a));
+    }
+    else if (cmd === "asset" && a) {
+        console.log(bundleAssetName(a));
+    }
+    else if (cmd === "pointer") {
+        const version = flag("version");
+        const sha = flag("sha");
+        const builtAt = flag("built-at");
+        if (!version || !sha || !builtAt) {
+            console.error("docs-release pointer: --version, --sha and --built-at are required");
+            process.exit(2);
+        }
+        const runId = flag("run-id");
+        process.stdout.write(pointerJson({
+            version,
+            asset: bundleAssetName(version),
+            sha,
+            builtAt,
+            ...(runId ? { runId } : {}),
+        }));
+    }
+    else if (cmd === "prune" && a && b) {
+        const chunks = [];
+        for await (const c of process.stdin)
+            chunks.push(c);
+        const assets = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        for (const name of assetsToPrune(assets, Number(a), b))
+            console.log(name);
+    }
+    else {
+        console.error("usage: docs-release.ts version <sha> | asset <version> | pointer --version <v> --sha <sha> [--run-id <id>] --built-at <iso> | prune <keep> <currentAsset>");
+        process.exit(2);
+    }
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",
     "./doc-guide": "./doc-guide/doc-guide.js",
     "./doc-guide/build-manual": "./doc-guide/build-manual.js",
     "./doc-guide/bundle": "./doc-guide/bundle.js",
+    "./doc-guide/docs-release": "./doc-guide/docs-release.js",
     "./doc-guide/guides-config": "./doc-guide/guides-config.js",
     "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.js",
     "./doc-guide/live-browser": "./doc-guide/live-browser.js",