@norskvideo/ctl-dev-kit 0.1.81 → 0.1.83

package/conventions/docs.md

@@ -82,6 +82,17 @@ Per-step treatments (`CaptureTreatment`, from the doc-guide library):
   component renders, not on incidental structure.
 - **`spotlight`** — the whole screen with one region lit and everything else
   dimmed, for "look here, in context."
+- **`livePicture`** — a live video tile the shot must not be taken without.
+  Studio's shared MoQ player (`norsk-studio-built-ins/lib/shared/moq-player`)
+  stamps `data-moq-phase` on the container it mounts into: `connecting`, then
+  `live` on the first decoded frame, or `error` with the reason in
+  `data-moq-error`. The player mounts at the moment the source connects, which
+  is also when a guide's "it's running" assertion passes — so a capture taken
+  then is of a spinner, and a sleep only hides a preview that is broken. Name
+  the tile here, or call `awaitLivePicture(page, selector)` before the capture
+  (the verify run skips captures, so an explicit wait is also the assertion);
+  either way a tile that never shows a picture fails the guide, naming the
+  phase it was stuck in and the player's own error.
 
 ## The toolchain
 
@@ -138,13 +149,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/doc-guide.d.ts

@@ -26,13 +26,42 @@ export interface UiFixture {
 export declare function docsRoot(): string;
 /** Per-step screenshot treatment. `crop` shoots one component at its own bounds;
  *  `spotlight` keeps the whole screen for context but dims everything except the
- *  named region and outlines it. Omit both for a plain full-page capture. */
+ *  named region and outlines it. Omit both for a plain full-page capture.
+ *  `livePicture` names a MoQ video tile the shot must not be taken without —
+ *  see `awaitLivePicture`. */
 export interface CaptureTreatment {
     crop?: string;
     spotlight?: string;
     /** Slack in px around a spotlight region before the dimming starts. */
     pad?: number;
+    /** A live video tile (Studio's shared MoQ player's container) that has to be
+     *  showing a picture before the capture is taken. */
+    livePicture?: string;
+    /** How long `livePicture` may take to arrive. Default 60s: a WebTransport
+     *  session plus a catalog plus a keyframe, on a cold encoder. */
+    livePictureTimeoutMs?: number;
 }
+/** The attributes Studio's shared MoQ player (norsk-studio-built-ins
+ *  `lib/shared/moq-player`) stamps on the container it mounts into. `live`
+ *  means the first video frame has decoded — not that the transport is up or
+ *  the catalog arrived, both of which can hold for seconds with nothing on
+ *  screen, which is exactly what a capture taken on a clock shows. */
+export declare const MOQ_PHASE_ATTR = "data-moq-phase";
+export declare const MOQ_ERROR_ATTR = "data-moq-error";
+export type MoqPhase = "connecting" | "live" | "error";
+/** The failure a guide sees when a tile never shows a picture: the tile, the
+ *  phase it was stuck in and, for an error, the player's own reason — so a
+ *  broken preview reads as what it is rather than as a timeout. Pure, so the
+ *  wording is pinned without a browser. */
+export declare function livePictureFailure(selector: string, phase: string | null, error: string | null, timeoutMs: number): string;
+/** Block until the tile at `selector` reports a decoded frame, or fail saying
+ *  why it did not. This is the wait a guide puts between "the source connected"
+ *  and the capture: the player mounts at that moment, and a screenshot taken
+ *  then is of a spinner. A wall-clock sleep would hide a broken preview; this
+ *  turns it into a named failure. */
+export declare function awaitLivePicture(page: Page, selector: string, opts?: {
+    timeoutMs?: number;
+}): Promise<void>;
 /** Produce the screenshot bytes for a capture, applying its treatment. Split out
  *  from `DocGuide.capture` (which also gates on DOCS_GENERATE and writes the file)
  *  so the treatment geometry is testable on its own. */

package/doc-guide/doc-guide.js

@@ -10,6 +10,44 @@ export function docsRoot() {
         return isAbsolute(override) ? override : resolve(process.cwd(), override);
     return resolve(process.cwd(), "docs/generated");
 }
+/** The attributes Studio's shared MoQ player (norsk-studio-built-ins
+ *  `lib/shared/moq-player`) stamps on the container it mounts into. `live`
+ *  means the first video frame has decoded — not that the transport is up or
+ *  the catalog arrived, both of which can hold for seconds with nothing on
+ *  screen, which is exactly what a capture taken on a clock shows. */
+export const MOQ_PHASE_ATTR = "data-moq-phase";
+export const MOQ_ERROR_ATTR = "data-moq-error";
+const LIVE_PICTURE_TIMEOUT_MS = 60_000;
+/** The failure a guide sees when a tile never shows a picture: the tile, the
+ *  phase it was stuck in and, for an error, the player's own reason — so a
+ *  broken preview reads as what it is rather than as a timeout. Pure, so the
+ *  wording is pinned without a browser. */
+export function livePictureFailure(selector, phase, error, timeoutMs) {
+    const state = phase === null
+        ? "not stamped — is a player mounted there?"
+        : phase === "error" && error
+            ? `error: ${error}`
+            : phase;
+    return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${state})`;
+}
+/** Block until the tile at `selector` reports a decoded frame, or fail saying
+ *  why it did not. This is the wait a guide puts between "the source connected"
+ *  and the capture: the player mounts at that moment, and a screenshot taken
+ *  then is of a spinner. A wall-clock sleep would hide a broken preview; this
+ *  turns it into a named failure. */
+export async function awaitLivePicture(page, selector, opts) {
+    const timeoutMs = opts?.timeoutMs ?? LIVE_PICTURE_TIMEOUT_MS;
+    try {
+        await page.waitForFunction(({ selector, attr }) => document.querySelector(selector)?.getAttribute(attr) === "live", { selector, attr: MOQ_PHASE_ATTR }, { timeout: timeoutMs });
+    }
+    catch {
+        const [phase, error] = await page.evaluate(({ selector, phaseAttr, errorAttr }) => {
+            const el = document.querySelector(selector);
+            return [el?.getAttribute(phaseAttr) ?? null, el?.getAttribute(errorAttr) ?? null];
+        }, { selector, phaseAttr: MOQ_PHASE_ATTR, errorAttr: MOQ_ERROR_ATTR });
+        throw new Error(livePictureFailure(selector, phase, error, timeoutMs));
+    }
+}
 const SPOTLIGHT_ID = "docguide-spotlight";
 /** Dim the page except the target region, drawn as one fixed box whose oversized
  *  box-shadow does the dimming — appended to <body> so no ancestor `overflow`
@@ -45,6 +83,8 @@ async function spotlightOff(page) {
  *  from `DocGuide.capture` (which also gates on DOCS_GENERATE and writes the file)
  *  so the treatment geometry is testable on its own. */
 export async function screenshotFor(page, treat) {
+    if (treat?.livePicture)
+        await awaitLivePicture(page, treat.livePicture, { timeoutMs: treat.livePictureTimeoutMs });
     // Wait for web fonts, else the snapshot catches a fallback font mid-swap.
     await page.evaluate(() => document.fonts.ready);
     if (treat?.crop)

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.83",
   "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",