@norskvideo/ctl-dev-kit 0.1.54 → 0.1.56

package/build/Dockerfile.bundle

@@ -50,6 +50,11 @@ COPY dashboards /usr/src/dashboards
 COPY components/lib /usr/src/components/lib
 # Optional product-template assets (funke's slate/black PNGs). Empty otherwise.
 COPY assets /usr/src/assets
+# The docs bundle (docs/generated/bundle/ on the host), served by the product
+# at /docs. Beside backend/ and frontend/ so server.ts reaches it the same way
+# it reaches frontend/dist (../../docs from the bundle dir). Empty when the
+# product built none.
+COPY docs ./docs
 ENV PORT=${PRODUCT_PORT}
 EXPOSE ${PRODUCT_PORT}
 CMD ["/usr/local/bin/bun", "run", "backend/dist/index.js"]

package/build/build-bundle-image.sh

@@ -23,6 +23,7 @@
 #   components/lib             the components workspace's build output
 #   native/                    native addon(s) (probe's signer) -> beside bundle
 #   assets/                    product-template assets (funke's PNGs)
+#   docs/generated/bundle/     the docs bundle (doc-guide buildBundle) -> docs/
 #   scripts/runtime-images.ts  -> emits the norsk-ctl.runtime-images label
 #
 # Only backend/dist is required. A product with no frontend/dashboard/components
@@ -51,7 +52,7 @@ trap 'rm -rf "${stage}"' EXIT
 
 echo "==> staging artifacts"
 mkdir -p "${stage}/backend" "${stage}/frontend/dist" "${stage}/components/lib" \
-  "${stage}/dashboards" "${stage}/native" "${stage}/assets"
+  "${stage}/dashboards" "${stage}/native" "${stage}/assets" "${stage}/docs"
 # The backend bundle is the one non-negotiable payload — every bundle product has
 # one, so a missing dist is a broken build, not an absent workspace.
 cp -R "${PRODUCT_DIR}/backend/dist" "${stage}/backend/dist"
@@ -87,6 +88,12 @@ if [ -d "${PRODUCT_DIR}/assets" ]; then
   cp -R "${PRODUCT_DIR}/assets/." "${stage}/assets/"
 fi
 
+# The docs bundle (optional): ONLY the built bundle, never the hand-written
+# docs/ tree beside it (planning notes, customer folders).
+if [ -d "${PRODUCT_DIR}/docs/generated/bundle" ]; then
+  cp -R "${PRODUCT_DIR}/docs/generated/bundle/." "${stage}/docs/"
+fi
+
 # Runtime images the default templates launch, stamped on as a label so a
 # golden-image bake can warm them with `docker inspect` + `docker pull` alone —
 # no daemon, no license. Derived from the rendered compose (scripts/runtime-images.ts),

package/conventions/check-drift.ts

@@ -264,7 +264,11 @@ export function demoProblems(repoRoot: string, canonicalShim: string): string[]
   const problems: string[] = [];
   const hasSpec = existsSync(join(repoRoot, DEMO_SPEC));
   const shimPath = join(repoRoot, DEMO_SHIM);
-  if (existsSync(shimPath)) {
+  if (existsSync(shimPath) && statSync(shimPath).isDirectory()) {
+    problems.push(
+      `${DEMO_SHIM} is a directory; the convention puts the executable shim at that path — move the directory (scripts/demo-tools, say) and re-run sync-drift to write the shim.`,
+    );
+  } else if (existsSync(shimPath)) {
     const actual = readFileSync(shimPath, "utf8");
     if (actual !== canonicalShim) {
       problems.push(

package/conventions/docs.md

@@ -95,9 +95,22 @@ they do not copy it:
   docsRoot, … })`, the Playwright config for the fixture/frontend tiers, carrying
   the CI defaults (bind+probe `127.0.0.1`, 120s webServer timeout, piped output).
 - `@norskvideo/ctl-dev-kit/doc-guide/build-manual` — `buildManual(spec, {
-  docsRoot })`, the generic assembler. The product supplies ONLY the page content
-  (`ManualSpec`: brand, overview, functionality[], examples[]); layout, CSS and
-  routing live in the assembler so every product's manual looks the same.
+  docsRoot, provenance })`, the generic assembler. The product supplies ONLY the
+  page content (`ManualSpec`: brand, overview, functionality[], examples[], and
+  `links` — the way out: the product's page on norsk.video, a contact); layout,
+  CSS and routing live in the assembler so every product's manual looks the
+  same. Every export ends in a provenance footer (build time, source sha, CI
+  run id — `provenanceFromEnv()` reads them from a GitHub Actions run).
+- `@norskvideo/ctl-dev-kit/doc-guide/bundle` — `buildBundle(spec, { docsRoot,
+  outDir, provenance })`, the docs bundle: `bundle.json` + `pages/<id>.md` +
+  `captures/` + the derived `manual.html`/`manual-linked.html`, in one
+  directory. Write it to `docs/generated/bundle/`: the image build stages that
+  directory as the image's `docs/` and the backend serves it at `/docs` with
+  the SDK's `serveDocs(app, docsBundleDir(import.meta.dir))` — one line in
+  `server.ts`, a no-op when there is no bundle. Declare the nav entry in the
+  manifest: `ui.sidebarEntries: [{ label: "Documentation", route: "/docs/" }]`;
+  ctl links it under `/products/<name>/`. An older ctl simply does not link it
+  (additive: nothing about launch changes).
 - `@norskvideo/ctl-dev-kit/doc-guide/{instance-proxy,live-browser}` — engine-tier
   support (serve the baked dashboard under its advertised instance prefix; launch
   the nix chromium for a live capture).

package/conventions/sync-drift.ts

@@ -18,7 +18,7 @@
 // cannot mechanically converge (e.g. a workflow with no product key to preserve)
 // is left for check-drift to flag, and a convention that genuinely breaks the
 // product surfaces as a red lint/typecheck/test — not as a silent bad copy.
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import {
   BEGIN,
@@ -203,6 +203,12 @@ function syncDemoShim(repoRoot: string, canonical: string, r: SyncReport): void
   const rel = "scripts/demo";
   const path = join(repoRoot, rel);
   if (!existsSync(join(repoRoot, "tests/demo.spec.ts")) && !existsSync(path)) return;
+  // A product's own tooling may already live at scripts/demo/ (playout did):
+  // never write over it; the gate names it and says where the shim goes.
+  if (existsSync(path) && statSync(path).isDirectory()) {
+    r.skipped.push(`${rel} (a directory; move it, the shim goes here)`);
+    return;
+  }
   mkdirSync(dirname(path), { recursive: true });
   writeIfChanged(path, canonical, rel, r.written);
   chmodSync(path, 0o755);

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

@@ -34,6 +34,13 @@ export interface ManualOverview {
     /** The small print under the right column heading. */
     byExampleIntro: string;
 }
+/** A way out of the manual: the product's marketing page, the platform docs,
+ *  a contact. Rendered in the footer of every export. Hash links are the only
+ *  navigation otherwise, so a manual without these is a cul-de-sac. */
+export interface ManualLink {
+    label: string;
+    href: string;
+}
 export interface ManualSpec {
     /** Sidebar wordmark + document brand. */
     brand: string;
@@ -42,7 +49,27 @@ export interface ManualSpec {
     overview: ManualOverview;
     functionality: ManualPage[];
     examples: ManualPage[];
+    /** Outbound links for the footer. Optional, but every published manual should
+     *  carry at least one. */
+    links?: ManualLink[];
+}
+/** Where a build came from, stamped into the footer so two copies of "the
+ *  manual" can be told apart without hashing them. `builtAt` defaults to now;
+ *  the rest is whatever the build knows (CI knows all of it, see
+ *  {@link provenanceFromEnv}). */
+export interface Provenance {
+    /** Source commit the captures and copy were built from. */
+    sha?: string;
+    /** The CI run that built it, when there was one. */
+    runId?: string;
+    /** ISO-8601. */
+    builtAt?: string;
+    /** The product version, when the build knows it. */
+    version?: string;
 }
+/** Provenance as a GitHub Actions run sees it (GITHUB_SHA / GITHUB_RUN_ID), or
+ *  as much of it as a local build has. */
+export declare function provenanceFromEnv(env?: NodeJS.ProcessEnv): Provenance;
 export interface BuildManualResult {
     /** Artifact-ready fragment (no doctype/head/body). */
     indexHtml: string;
@@ -55,6 +82,9 @@ export interface BuildManualResult {
     standaloneAssetHtml?: string;
     /** `<slug>/<file>` of every referenced capture not found on disk. */
     missing: string[];
+    /** `<slug>/<file>` -> the sidecar href it was written to. Only when `assets`
+     *  is set; what a bundle's markdown pages reference captures by. */
+    sidecarHrefs?: Record<string, string>;
 }
 /** Where to write de-inlined captures for the standalone manual. `dir` is the
  *  filesystem directory; `href` (default "images") is the relative URL prefix
@@ -63,7 +93,9 @@ export interface ManualAssets {
     dir: string;
     href?: string;
 }
-export declare function buildManual(spec: ManualSpec, opts: {
+export interface BuildManualOptions {
     docsRoot: string;
     assets?: ManualAssets;
-}): BuildManualResult;
+    provenance?: Provenance;
+}
+export declare function buildManual(spec: ManualSpec, opts: BuildManualOptions): BuildManualResult;

package/doc-guide/build-manual.js

@@ -26,6 +26,16 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+/** Provenance as a GitHub Actions run sees it (GITHUB_SHA / GITHUB_RUN_ID), or
+ *  as much of it as a local build has. */
+export function provenanceFromEnv(env = process.env) {
+    const p = { builtAt: new Date().toISOString() };
+    if (env.GITHUB_SHA)
+        p.sha = env.GITHUB_SHA;
+    if (env.GITHUB_RUN_ID)
+        p.runId = env.GITHUB_RUN_ID;
+    return p;
+}
 const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 /** Resize a captured PNG to <=1100px wide JPEG. A missing capture becomes a
  *  labelled placeholder so the manual still builds, and is recorded in `missing`. */
@@ -63,8 +73,22 @@ function fileUri(a, file, assets) {
     writeFileSync(join(assets.dir, name), a.kind === "svg" ? Buffer.from(a.text) : a.bytes);
     return `${assets.href ?? "images"}/${name}`;
 }
+/** The footer every export carries: provenance first, then the way out. */
+function footerHtml(spec, provenance) {
+    const facts = [];
+    if (provenance.version)
+        facts.push(`version ${esc(provenance.version)}`);
+    facts.push(`built ${esc(provenance.builtAt ?? new Date().toISOString())}`);
+    if (provenance.sha)
+        facts.push(`source <span class="mono">${esc(provenance.sha)}</span>`);
+    if (provenance.runId)
+        facts.push(`run <span class="mono">${esc(provenance.runId)}</span>`);
+    const links = (spec.links ?? []).map((l) => `<a href="${esc(l.href)}">${esc(l.label)}</a>`).join("");
+    return `<footer class="prov"><div class="facts">${esc(spec.brand)} &middot; ${facts.join(" &middot; ")}</div>${links ? `<div class="out">${links}</div>` : ""}</footer>`;
+}
 export function buildManual(spec, opts) {
     const { docsRoot, assets } = opts;
+    const provenance = { builtAt: new Date().toISOString(), ...opts.provenance };
     const missing = [];
     // Each shot is loaded (resized) at most once, then rendered inline for the
     // fragment and — when `assets` is set — as a sidecar file for the standalone.
@@ -79,7 +103,12 @@ export function buildManual(spec, opts) {
         return a;
     };
     const inline = (slug, file) => inlineUri(load(slug, file));
-    const external = (slug, file) => fileUri(load(slug, file), file, assets);
+    const sidecarHrefs = {};
+    const external = (slug, file) => {
+        const href = fileUri(load(slug, file), file, assets);
+        sidecarHrefs[`${slug}/${file}`] = href;
+        return href;
+    };
     const FN = spec.functionality;
     const EX = spec.examples;
     const ALL = [...FN, ...EX];
@@ -124,8 +153,7 @@ export function buildManual(spec, opts) {
   <a href="#overview" data-nav class="ovlink">Overview</a>
   <div class="ngroup"><div class="ghead">Functionality</div>${FN.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>
   <div class="ngroup"><div class="ghead">Examples <span class="ct">${EX.length}</span></div>${EX.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>`;
-        const html = `<title>${esc(spec.title)}</title>
-<style>
+        const html = `<style>
 :root{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;--faint:#5f6a79;
   --line:#212a36;--accent:#54d6cf;--measure:64ch}
 @media (prefers-color-scheme:light){:root{--bg:#f5f7f9;--bg2:#eef1f4;--surf:#fff;--ink:#0f1620;
@@ -185,6 +213,10 @@ main{min-width:0;padding:0 clamp(20px,5vw,72px)}
 .linklist{display:flex;flex-direction:column;gap:2px}
 .linklist a{text-decoration:none;color:var(--dim);font-size:14px;padding:5px 0}
 .linklist a:hover{color:var(--accent)}
+.prov{margin:0 0 48px;padding-top:18px;border-top:1px solid var(--line);font-size:12px;color:var(--faint);display:flex;flex-wrap:wrap;gap:8px 24px;justify-content:space-between}
+.prov .out{display:flex;flex-wrap:wrap;gap:14px}
+.prov a{color:var(--dim);text-decoration:none}
+.prov a:hover{color:var(--accent)}
 @media (max-width:880px){.wrap{grid-template-columns:1fr}
   aside{position:static;height:auto;border-right:none;border-bottom:1px solid var(--line)}
   .twocol{grid-template-columns:1fr}}
@@ -195,6 +227,7 @@ main{min-width:0;padding:0 clamp(20px,5vw,72px)}
 <main>
 ${overview}
 ${ALL.map(pageHtml).join("\n")}
+${footerHtml(spec, provenance)}
 </main>
 </div>
 
@@ -223,12 +256,17 @@ ${ALL.map(pageHtml).join("\n")}
 ${body}
 </body>
 </html>`;
+    // The Artifact tool supplies the head, so the fragment carries its own
+    // <title>; the standalone wraps the BODY alone, so the title appears once.
+    const fragment = (body) => `<title>${esc(spec.title)}</title>\n${body}`;
     // Fragment and standalone are both inlined (Artifact CSP; publishable on its
     // own). Sidecars are an EXTRA output, never a substitution.
-    const indexHtml = render(inline);
-    const standaloneHtml = document(indexHtml);
+    const body = render(inline);
+    const indexHtml = fragment(body);
+    const standaloneHtml = document(body);
     if (!assets)
         return { indexHtml, standaloneHtml, missing };
     mkdirSync(assets.dir, { recursive: true });
-    return { indexHtml, standaloneHtml, standaloneAssetHtml: document(render(external)), missing };
+    const standaloneAssetHtml = document(render(external));
+    return { indexHtml, standaloneHtml, standaloneAssetHtml, missing, sidecarHrefs };
 }

package/doc-guide/bundle.d.ts

@@ -0,0 +1,37 @@
+import { type BuildManualResult, type ManualLink, type ManualSpec, type Provenance } from "./build-manual.js";
+export declare const BUNDLE_SCHEMA_VERSION = 1;
+export interface BundlePageEntry {
+    id: string;
+    nav: string;
+    title: string;
+    kind: "overview" | "fn" | "ex";
+    /** Relative to the bundle directory. */
+    file: string;
+}
+export interface BundleManifest {
+    schemaVersion: number;
+    brand: string;
+    title: string;
+    provenance: Provenance;
+    links: ManualLink[];
+    pages: BundlePageEntry[];
+    /** Derived single-page exports, relative to the bundle directory. */
+    exports: {
+        manual: string;
+        manualLinked: string;
+    };
+    /** `<slug>/<file>` of every referenced capture that was not on disk — a
+     *  bundle with gaps is still a bundle, but a consumer can see them. */
+    missing: string[];
+}
+export interface BuildBundleOptions {
+    docsRoot: string;
+    /** Where the bundle is written; created if absent. */
+    outDir: string;
+    provenance?: Provenance;
+}
+export interface BuildBundleResult extends BuildManualResult {
+    manifest: BundleManifest;
+    outDir: string;
+}
+export declare function buildBundle(spec: ManualSpec, opts: BuildBundleOptions): BuildBundleResult;

package/doc-guide/bundle.js

@@ -0,0 +1,97 @@
+// The docs bundle: what a product's docs build produces, and the unit every
+// downstream consumer reads (ADR-0012). A directory holding
+//
+//   bundle.json          this manifest — identity, provenance, the page list
+//   pages/<id>.md        one markdown page per manual page, captures by path
+//   captures/<file>      every referenced capture, resized (or a labelled gap)
+//   manual.html          derived: the self-contained single-page export
+//   manual-linked.html   derived: the same page referencing captures/
+//
+// The product image bakes this directory in and serves it at /docs; the public
+// plane ingests pages/*.md. `ManualSpec` stays the authoring input — the
+// bundle is that spec promoted to a contract, with the captures alongside.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildManual, } from "./build-manual.js";
+export const BUNDLE_SCHEMA_VERSION = 1;
+const yamlString = (s) => JSON.stringify(s);
+export function buildBundle(spec, opts) {
+    const { docsRoot, outDir } = opts;
+    const provenance = { builtAt: new Date().toISOString(), ...opts.provenance };
+    mkdirSync(join(outDir, "pages"), { recursive: true });
+    const manual = buildManual(spec, {
+        docsRoot,
+        provenance,
+        assets: { dir: join(outDir, "captures"), href: "captures" },
+    });
+    const hrefs = manual.sidecarHrefs ?? {};
+    // Pages live one level down, so a capture href is reached via `../`.
+    const captureRef = (slug, file) => `../${hrefs[`${slug}/${file}`]}`;
+    const all = [...spec.functionality, ...spec.examples];
+    const byId = new Map(all.map((p) => [p.id, p]));
+    const pageLink = (id) => {
+        const t = byId.get(id);
+        return t ? `[${t.nav}](${id}.md)` : "";
+    };
+    const pageMarkdown = (p) => {
+        const head = [
+            "---",
+            `title: ${yamlString(p.title)}`,
+            `nav: ${yamlString(p.nav)}`,
+            `kind: ${p.kind}`,
+            ...(p.tag ? [`tag: ${yamlString(p.tag)}`] : []),
+            "---",
+        ];
+        const steps = p.steps.map((s, i) => `### ${String(i + 1).padStart(2, "0")} ${s.head}\n\n${s.desc}\n\n![${s.head}](${captureRef(s.slug, s.file)})`);
+        const links = p.links.map(pageLink).filter(Boolean);
+        const related = links.length ? [`${p.kind === "fn" ? "Seen in" : "Uses"}: ${links.join(", ")}`] : [];
+        return [...head, "", p.intro, "", ...steps.flatMap((s) => [s, ""]), ...related].join("\n").trimEnd().concat("\n");
+    };
+    const ov = spec.overview;
+    const overviewMarkdown = [
+        "---",
+        `title: ${yamlString(ov.headline)}`,
+        `nav: "Overview"`,
+        "kind: overview",
+        "---",
+        "",
+        ov.lead,
+        "",
+        `![${ov.hero.alt}](${captureRef(ov.hero.slug, ov.hero.file)})`,
+        "",
+        `_${ov.hero.caption}_`,
+        "",
+        `## ${ov.byFunctionHeading ?? "By function"}`,
+        "",
+        ...spec.functionality.map((p) => `- ${pageLink(p.id)}`),
+        "",
+        `## ${ov.byExampleHeading ?? "By example"}`,
+        "",
+        ov.byExampleIntro,
+        "",
+        ...spec.examples.map((p) => `- ${pageLink(p.id)}`),
+        "",
+    ].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` })),
+    ];
+    writeFileSync(join(outDir, "pages/overview.md"), overviewMarkdown);
+    for (const p of all)
+        writeFileSync(join(outDir, `pages/${p.id}.md`), pageMarkdown(p));
+    const exports = { manual: "manual.html", manualLinked: "manual-linked.html" };
+    writeFileSync(join(outDir, exports.manual), manual.standaloneHtml);
+    writeFileSync(join(outDir, exports.manualLinked), manual.standaloneAssetHtml ?? manual.standaloneHtml);
+    const manifest = {
+        schemaVersion: BUNDLE_SCHEMA_VERSION,
+        brand: spec.brand,
+        title: spec.title,
+        provenance,
+        links: spec.links ?? [],
+        pages,
+        exports,
+        missing: manual.missing,
+    };
+    writeFileSync(join(outDir, "bundle.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { ...manual, manifest, outDir };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -10,6 +10,7 @@
     "./docs/path-existence": "./docs/path-existence.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/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"