@norskvideo/ctl-dev-kit 0.1.58 → 0.1.60

package/create-product/backend-turnkey.ts

@@ -125,10 +125,13 @@ function rootPackageJson(ctx: ShapeContext): string {
         "test:image": "bun test tests/image/",
         "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-drift.ts",
         "docs:check": "bun run node_modules/@norskvideo/ctl-dev-kit/docs/path-existence.ts",
+        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/known-limitations.md`,
+        "docs:handover": "bash scripts/docs-handover.sh",
+        "docs:handover:check": "bash scripts/docs-handover.sh --check",
         "sync:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/sync-drift.ts",
         typecheck: "bunx tsc --noEmit -p shared && bunx tsc --noEmit -p backend && bunx tsc --noEmit -p .",
         build: "bun run lint && bun run typecheck && bun run build:no-lint",
-        "build:no-lint": "bun run build:shared && bun run build:backend",
+        "build:no-lint": "bun run build:shared && bun run build:backend && bun run docs:manual",
         "build:shared": "bun run --cwd shared build",
         "build:backend": "bun run --cwd backend build",
         "build:image": "bash deployment/build-image.sh",
@@ -336,9 +339,10 @@ const MANIFEST_TS = `import { type Manifest, type ManifestInput, ManifestSchema
 import { PRODUCT_NAME, PRODUCT_VERSION } from "./version.ts";
 
 // Producer-side ManifestInput: everything the schema defaults stays omitted
-// (ui/cli/components/runtime), so this declares only what the product has. A
+// (cli/components/runtime), so this declares only what the product has. A
 // backend-only turnkey has no configure UI — configScreenUrl is optional and
-// omitted, so the runner skips its registration probe (no placeholder HTML).
+// omitted, so the runner skips its registration probe (no placeholder HTML);
+// its one ui entry is the documentation the image serves at /docs.
 // Parsing at build time keeps the served manifest the READER shape with the
 // defaults filled in.
 export function buildManifest(): Manifest {
@@ -355,6 +359,7 @@ export function buildManifest(): Manifest {
     targets: ["docker-compose"],
     // Keep in lockstep with STARTER_CONFIGS in backend/src/routes/product-template.ts.
     defaultProductTemplates: [{ name: "default", url: "/api/product-template/default" }],
+    ui: { sidebarEntries: [{ label: "Documentation", route: "/docs/" }] },
   };
   return ManifestSchema.parse(manifest);
 }
@@ -965,6 +970,7 @@ console.log(\`${ctx.name} listening on :\${port}\`);
 function backendServerTs(ctx: ShapeContext): string {
   return `import type { Server } from "node:http";
 import { buildStudioLibrary } from "${ctx.scope}/shared/workflow";
+import { docsBundleDir, serveDocs } from "@norskvideo/ctl-sdk";
 import cors from "cors";
 import express from "express";
 import { manifestRouter } from "./routes/manifest.ts";
@@ -987,6 +993,9 @@ export async function startServer(port: number): Promise<Server> {
   app.use(manifestRouter);
   app.use("/api", openapiRouter);
   app.use("/api", makeProductTemplateRouter(library));
+  // The docs bundle (\`bun run docs:manual\`, baked into the image as docs/),
+  // served at /docs; a no-op until it has been built.
+  serveDocs(app, docsBundleDir(import.meta.dir));
 
   return await new Promise<Server>((resolve, reject) => {
     const server = app.listen(port, () => resolve(server));
@@ -1451,6 +1460,144 @@ function exampleInputJson(_ctx: ShapeContext): string {
   )}\n`;
 }
 
+// ---- The canonical doc set (fleet review 02 s9, backend-only turnkey) ------
+// README (developer), docs/README (the index), docs/handover (the customer's
+// deployment document: prose around a block norsk-ctl generates), docs/known-
+// limitations (operator). Prose only: a turnkey's bundle is built from these
+// files by docs:manual, which the image build runs, so the image serves them.
+// Bundle-internal file names are written without backticks on purpose: the
+// path-existence lint would look for them in the repo.
+
+function readmeMd(ctx: ShapeContext): string {
+  return `# ${ctx.name}
+
+A Norsk product for norsk-ctl: a backend-only turnkey. The control plane is a
+small service the daemon runs (the manifest, the product-template build, the
+documentation); the media path is a Norsk Studio workflow the product composes.
+
+## Layout
+
+- \`shared/\` — the product's config schema, workflow composer and manifest.
+- \`backend/\` — the control-plane service (manifest, product-template build, docs).
+- \`examples/\` — starter configs; \`examples/default/input.json\` is the default template.
+- \`tests/\` — unit, image and demo tiers; \`tests/demo.spec.ts\` is the customer journey.
+- \`docs/\` — reader-facing documents; \`docs/README.md\` is the index.
+- \`deployment/\` — the image build wrapper and the iterate loop.
+
+## Dev loop
+
+Everything runs inside the dev shell (\`nix develop .#dev\`), which carries bun,
+norsk-ctl and the pinned Norsk SDK:
+
+- \`bun install\`, then \`bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck\`.
+- \`bun run demo\` — the customer journey on a private daemon.
+- \`bun run build:image\` — the product image (\`deployment/build-image.sh\`).
+
+## Documentation
+
+\`bun run docs:manual\` builds the docs bundle from \`docs/handover.md\` and
+\`docs/known-limitations.md\`; the image build runs it, so every image serves
+them at /docs (linked from the product's page in norsk-ctl). \`bun run
+docs:handover\` regenerates the handover's generated block from a daemon that
+has this product added; CI runs its \`--check\`.
+
+\`CLAUDE.md\` has the conventions and the traps.
+`;
+}
+
+function docsReadmeMd(ctx: ShapeContext): string {
+  return `# ${ctx.name} documentation
+
+Reader-facing documents live at this level and ship inside the product image,
+served at /docs at the version that is running.
+
+| Document                     | Audience                                  | What it is                                                                                          |
+| ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| \`docs/handover.md\`          | the platform team deploying this product  | Deploying from the exported bundle without norsk-ctl: every mount, environment and injected setting |
+| \`docs/known-limitations.md\` | operators                                 | What the product does not do yet, with the consequence and the workaround                          |
+
+\`bun run docs:manual\` builds the bundle from these files. The tables in the
+handover are generated by norsk-ctl (\`bun run docs:handover\`) — regenerate
+them, never edit them.
+`;
+}
+
+function handoverMd(ctx: ShapeContext): string {
+  return `# Deploying ${ctx.name} without norsk-ctl
+
+What the platform team receives, and how to run it. The tables in the
+generated block below come from norsk-ctl's own rendering of this product's
+default template (\`bun run docs:handover\`), so they are the launch truth of
+the version this document ships with. Regenerate them; never edit them.
+
+## What you receive
+
+A portable bundle exported by norsk-ctl: compose.yml (the flat compose, every
+path relative), HANDOVER.md (the same tables as below), the working-directory
+seed, the product-template content the services mount, and a licence
+placeholder to replace with a production licence before the first start.
+
+<!-- BEGIN generated: norsk-ctl instance export-template default --format handover -->
+_Not generated yet. Run \`bun run docs:handover\` against a daemon that has this product added._
+<!-- END generated -->
+
+## Verifying a deployment
+
+- The control plane answers on its port: GET /healthz returns ok.
+- The media engine is licensed: its log names the licence's product entry, not a placeholder.
+- The default template's outputs are reachable from where the audience is.
+
+## Not in this artefact
+
+Anything norsk-ctl-specific: the daemon, product registration, the instance
+proxy and its authentication, templates-as-storage. The bundle is the launch
+truth of one product template and needs none of them.
+`;
+}
+
+const KNOWN_LIMITATIONS_MD = `# Known limitations
+
+What this product does not do yet, or does with a caveat an operator must know
+before relying on it. One entry per limitation: the consequence and the
+workaround, not the roadmap.
+
+## Ingest
+
+- _None recorded yet._
+
+## Output
+
+- _None recorded yet._
+
+## Operations
+
+- _None recorded yet._
+`;
+
+const DOCS_HANDOVER_SH = `#!/usr/bin/env bash
+# Fill (or, with --check, verify) the generated block of docs/handover.md from
+# norsk-ctl's own rendering of this product's stored template: every mount,
+# environment and launch-injected setting, as the runner would launch it.
+# Needs a daemon that has this product added (the demo or integration tier
+# leaves one); TEMPLATE names the stored template (default: the manifest's).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+template="\${TEMPLATE:-default}"
+out="$(mktemp -d)/bundle"
+norsk-ctl instance export-template "$template" --to "$out" --format handover |
+  bun run node_modules/@norskvideo/ctl-dev-kit/docs/splice-generated.ts docs/handover.md "$@"
+`;
+
+const REGEN_MANUAL_SH = `#!/usr/bin/env bash
+# Regenerate this product's docs bundle. A prose-only turnkey has no doc-guide
+# tiers: the bundle is built from the hand-written documents under docs/ by
+# \`bun run docs:manual\`. The embedded docs workflow (build-docs.yml) calls
+# this; the image build runs docs:manual itself.
+set -euo pipefail
+cd "$(dirname "$0")/../.."
+bun run docs:manual
+`;
+
 export const backendTurnkey: ShapeModule = {
   claudeHead,
   claudeTail,
@@ -1463,6 +1610,13 @@ export const backendTurnkey: ShapeModule = {
       { path: "examples/default/input.json", content: exampleInputJson(ctx) },
       { path: "deployment/iterate.sh", content: iterateSh(ctx), executable: true },
       { path: "scripts/demo", content: ctx.canon.demoShim, executable: true },
+      { path: "README.md", content: readmeMd(ctx) },
+      { path: "docs/README.md", content: docsReadmeMd(ctx) },
+      { path: "docs/handover.md", content: handoverMd(ctx) },
+      { path: "docs/known-limitations.md", content: KNOWN_LIMITATIONS_MD },
+      { path: ".github/workflows/build-docs.yml", content: ctx.canon.buildDocs },
+      { path: "scripts/doc-guide/regen-manual.sh", content: REGEN_MANUAL_SH, executable: true },
+      { path: "scripts/docs-handover.sh", content: DOCS_HANDOVER_SH, executable: true },
       { path: "tests/demo.spec.ts", content: demoSpecTs(ctx) },
       { path: "tests/unit/demo-spec.test.ts", content: DEMO_SPEC_TEST_TS },
       { path: "shared/package.json", content: sharedPackageJson(ctx) },

package/create-product/canon.ts

@@ -24,6 +24,8 @@ export interface Canon {
   dprint: string;
   buildImageBootstrap: string;
   buildImage: string;
+  /** conventions/build-docs.yml — the embedded docs workflow a turnkey carries. */
+  buildDocs: string;
   gitignoreCore: string;
   invariantsTemplate: string;
   /** conventions/demo.sh, emitted as scripts/demo. */
@@ -38,6 +40,7 @@ export function loadCanon(): Canon {
     upgradeLatest: readFileSync(join(conventionsDir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(conventionsDir, "sync-dev-kit.yml"), "utf8"),
     checks: readFileSync(join(conventionsDir, "checks.yml"), "utf8"),
+    buildDocs: readFileSync(join(conventionsDir, "build-docs.yml"), "utf8"),
     biome: readFileSync(join(conventionsDir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(conventionsDir, "tsconfig.base.json"), "utf8"),
     dprint: readFileSync(join(conventionsDir, "dprint.base.jsonc"), "utf8"),

package/create-product/cli.ts

@@ -73,6 +73,7 @@ export function main(argv: string[]): void {
 Next steps (also in the generated CLAUDE.md):
   1. cd ${dir} && git init && bun install
   2. UPDATE_SNAPSHOTS=1 bun run test:unit   # bake the byte-snapshot fixtures, commit them
+  3. bun run docs:handover                # once a daemon has this product added: fills docs/handover.md from the launch truth
   3. bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck
   4. Replace the starter graph in shared/src/workflow/ with the real one,
      keeping INVARIANTS.md and its rules tests in step.

package/doc-guide/prose-bundle.d.ts

@@ -0,0 +1,15 @@
+import { type ManualDocument, type ManualLink, type ManualSpec } from "./build-manual.js";
+export interface ProseFile {
+    file: string;
+    markdown: string;
+}
+/** A markdown file as a manual document: its id from the file name, its title
+ *  from the H1 (which then leaves the body — the page renders its own). */
+export declare function proseDocument(file: string, markdown: string): ManualDocument;
+export interface ProseSpecOptions {
+    brand: string;
+    title: string;
+    lead?: string;
+    links?: ManualLink[];
+}
+export declare function proseSpec(opts: ProseSpecOptions, files: ProseFile[]): ManualSpec;

package/doc-guide/prose-bundle.js

@@ -0,0 +1,86 @@
+// A docs bundle from hand-written markdown alone: no doc-guide tiers, no
+// captures, no per-repo TypeScript driver. A turnkey (a handover document, a
+// known-limitations page) names its files in one package.json script and gets
+// the same bundle a product's illustrated manual becomes — served at /docs by
+// the image, baked in by the image build.
+//
+//   bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js \
+//     --brand "Acme" --title "Acme — Documentation" \
+//     --link "norsk.video=https://norsk.video/" \
+//     --out docs/generated/bundle docs/handover.md docs/known-limitations.md
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { provenanceFromEnv } from "./build-manual.js";
+import { buildBundle } from "./bundle.js";
+/** A markdown file as a manual document: its id from the file name, its title
+ *  from the H1 (which then leaves the body — the page renders its own). */
+export function proseDocument(file, markdown) {
+    const id = basename(file)
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-");
+    const h1 = markdown.match(/^# (.+)\r?\n/);
+    const title = h1 ? h1[1].trim() : id;
+    const body = h1 ? markdown.slice(h1[0].length).replace(/^\n+/, "") : markdown;
+    return { id, nav: title, title, markdown: body };
+}
+export function proseSpec(opts, files) {
+    return {
+        brand: opts.brand,
+        title: opts.title,
+        overview: {
+            headline: opts.title,
+            lead: opts.lead ?? "The documentation shipped with this product, at the version you are running.",
+            byExampleIntro: "",
+        },
+        functionality: [],
+        examples: [],
+        documents: files.map((f) => proseDocument(f.file, f.markdown)),
+        links: opts.links ?? [],
+    };
+}
+function parseArgs(argv) {
+    const opts = { brand: "", title: "", links: [] };
+    let out = "docs/generated/bundle";
+    const files = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const value = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`${a} needs a value`);
+            return v;
+        };
+        if (a === "--brand")
+            opts.brand = value();
+        else if (a === "--title")
+            opts.title = value();
+        else if (a === "--lead")
+            opts.lead = value();
+        else if (a === "--out")
+            out = value();
+        else if (a === "--link") {
+            const v = value();
+            const eq = v.indexOf("=");
+            if (eq <= 0)
+                throw new Error(`--link wants label=href, got ${JSON.stringify(v)}`);
+            opts.links?.push({ label: v.slice(0, eq), href: v.slice(eq + 1) });
+        }
+        else if (a.startsWith("--"))
+            throw new Error(`unknown option ${a}`);
+        else
+            files.push(a);
+    }
+    if (!opts.brand || !opts.title)
+        throw new Error("--brand and --title are required");
+    if (files.length === 0)
+        throw new Error("name at least one markdown file");
+    return { opts, out, files };
+}
+if (import.meta.main) {
+    const { opts, out, files } = parseArgs(process.argv.slice(2));
+    const spec = proseSpec(opts, files.map((file) => ({ file, markdown: readFileSync(file, "utf8") })));
+    const outDir = resolve(out);
+    const result = buildBundle(spec, { docsRoot: process.cwd(), outDir, provenance: provenanceFromEnv() });
+    console.log(`wrote ${outDir} (${files.length} documents, ${result.manifest.pages.length} pages)`);
+}

package/docs/splice-generated.ts

@@ -0,0 +1,75 @@
+// Replace the generated block of a hand-written markdown document with what a
+// tool printed, touching nothing outside the markers. The block is delimited by
+//
+//   <!-- BEGIN generated: <what produced it> -->
+//   ...
+//   <!-- END generated -->
+//
+// on their own lines. The prose around it is the author's; the block is
+// regenerated (a turnkey's handover tables come from `norsk-ctl instance
+// export-template --format handover`), and `--check` is the CI snapshot: a
+// document whose block would change is stale, and the diff is the review.
+//
+//   <tool that prints the block> | bun run node_modules/@norskvideo/ctl-dev-kit/docs/splice-generated.ts docs/handover.md [--check]
+import { readFileSync, writeFileSync } from "node:fs";
+
+export const BEGIN_MARKER = "<!-- BEGIN generated";
+export const END_MARKER = "<!-- END generated -->";
+
+export type SpliceResult =
+  | { status: "ok"; value: { next: string; changed: boolean } }
+  | { status: "error"; error: string };
+
+export function spliceGenerated(current: string, generated: string): SpliceResult {
+  const lines = current.split("\n");
+  const begins = lines.flatMap((l, i) => (l.startsWith(BEGIN_MARKER) && l.trimEnd().endsWith("-->") ? [i] : []));
+  const ends = lines.flatMap((l, i) => (l.trim() === END_MARKER ? [i] : []));
+  if (begins.length === 0 || ends.length === 0) {
+    return {
+      status: "error",
+      error: `no generated block: expected a line starting "${BEGIN_MARKER}" and a line "${END_MARKER}"`,
+    };
+  }
+  if (begins.length > 1 || ends.length > 1) {
+    return { status: "error", error: "more than one generated block; exactly one is spliced" };
+  }
+  const [begin] = begins;
+  const [end] = ends;
+  if (end < begin) return { status: "error", error: `"${END_MARKER}" precedes the BEGIN marker` };
+  const body = generated.replace(/^\n+/, "").replace(/\s+$/, "");
+  const next = [...lines.slice(0, begin + 1), body, ...lines.slice(end)].join("\n");
+  return { status: "ok", value: { next, changed: next !== current } };
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const check = args.includes("--check");
+  const file = args.find((a) => !a.startsWith("--"));
+  if (!file) {
+    console.error("usage: <generator> | splice-generated.ts <file> [--check]");
+    process.exit(2);
+  }
+  const generated = await Bun.stdin.text();
+  const result = spliceGenerated(readFileSync(file, "utf8"), generated);
+  if (result.status === "error") {
+    console.error(`splice-generated: ${file}: ${result.error}`);
+    process.exit(2);
+  }
+  const { next, changed } = result.value;
+  if (check) {
+    if (changed) {
+      console.error(
+        `splice-generated: ${file} is stale — its generated block differs from what the generator prints now`,
+      );
+      process.exit(1);
+    }
+    console.log(`splice-generated: ${file} is current`);
+    process.exit(0);
+  }
+  if (changed) {
+    writeFileSync(file, next);
+    console.log(`splice-generated: updated ${file}`);
+  } else {
+    console.log(`splice-generated: ${file} unchanged`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -8,9 +8,11 @@
     "./testing/byte-snapshot": "./testing/byte-snapshot.ts",
     "./create-product": "./create-product/create-product.ts",
     "./docs/path-existence": "./docs/path-existence.ts",
+    "./docs/splice-generated": "./docs/splice-generated.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/prose-bundle": "./doc-guide/prose-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"