@norskvideo/ctl-dev-kit 0.1.81 → 0.1.82

package/conventions/docs.md

@@ -138,13 +138,24 @@ 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).
 

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/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.81",
+  "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",