@norskvideo/ctl-dev-kit 0.1.13 → 0.1.15

package/create-product/canon.ts

@@ -0,0 +1,52 @@
+// The generator's canonical inputs are THE SAME FILES the drift gate checks
+// (conventions/* + build/*), resolved package-relative exactly like
+// check-drift.ts's CLI entry — there is no second copy that can drift. A
+// generated repo therefore passes the gate by construction: byte-verbatim
+// files are emitted byte-verbatim, and the per-repo fill-ins live only where
+// the gate already masks or leaves structure free (the workflows' `product:`
+// line, the root tsconfig include list, the .gitignore tail, the wrapper
+// around the build-image bootstrap, the seed's pins).
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const conventionsDir = join(import.meta.dir, "..", "conventions");
+const buildDir = join(import.meta.dir, "..", "build");
+
+export interface Canon {
+  core: string;
+  flake: string;
+  flakeLock: string;
+  upgradeLatest: string;
+  checks: string;
+  biome: string;
+  tsconfigBase: string;
+  dprint: string;
+  buildImageBootstrap: string;
+  gitignoreCore: string;
+  invariantsTemplate: string;
+}
+
+export function loadCanon(): Canon {
+  return {
+    core: readFileSync(join(conventionsDir, "CLAUDE.core.md"), "utf8"),
+    flake: readFileSync(join(buildDir, "flake.nix"), "utf8"),
+    flakeLock: readFileSync(join(buildDir, "flake.lock"), "utf8"),
+    upgradeLatest: readFileSync(join(conventionsDir, "upgrade-latest.yml"), "utf8"),
+    checks: readFileSync(join(conventionsDir, "checks.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"),
+    buildImageBootstrap: readFileSync(join(buildDir, "build-image.bootstrap.sh"), "utf8"),
+    gitignoreCore: readFileSync(join(conventionsDir, "gitignore.core"), "utf8"),
+    invariantsTemplate: readFileSync(join(import.meta.dir, "..", "testing", "INVARIANTS.template.md"), "utf8"),
+  };
+}
+
+export function loadAsset(name: string): string {
+  return readFileSync(join(import.meta.dir, "assets", name), "utf8");
+}
+
+/** The `product:` value in the shared workflows — the one line the drift gate
+ *  masks. The dashboard key drops the `norsk-` prefix by fleet convention
+ *  (norsk-reuters reports as `reuters`). */
+export const PRODUCT_SENTINEL = "__PRODUCT__";

package/create-product/cli.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+// `bunx @norskvideo/ctl-dev-kit create-product ...` — a bin rather than a repo
+// script because the generator's whole use case is an EMPTY directory: there
+// is no node_modules to run a script from yet. The dev-kit ships TS verbatim,
+// so the bin runs under bun (the fleet's only runtime).
+import { existsSync, readdirSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { createProduct, type ProductShape } from "./create-product.ts";
+
+const USAGE = `Usage:
+  ctl-dev-kit create-product --name <name> [options] <dir>
+
+Options:
+  --shape <shape>       Repo shape (default: backend-turnkey; the only shape yet)
+  --name <name>         Product name, e.g. norsk-acme (lowercase, digits, hyphens)
+  --port <port>         Local-dev backend port (default: 4323; container is always 4321)
+  --media-image <ref>   Full media image ref (repo:tag); norsk-sdk npm pin = its tag
+  --studio-image <ref>  Full studio image ref (repo:tag)
+  --studio-lib <ver>    norsk-studio* npm pin (default: the studio image's tag)
+`;
+
+function fail(message: string): never {
+  console.error(message);
+  console.error(USAGE);
+  process.exit(1);
+}
+
+export function main(argv: string[]): void {
+  const [command, ...rest] = argv;
+  if (command !== "create-product") {
+    fail(`unknown command ${JSON.stringify(command ?? "")} — the only command is create-product.`);
+  }
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      shape: { type: "string", default: "backend-turnkey" },
+      name: { type: "string" },
+      port: { type: "string" },
+      "media-image": { type: "string" },
+      "studio-image": { type: "string" },
+      "studio-lib": { type: "string" },
+    },
+  });
+  const dir = positionals[0];
+  if (!dir) fail("missing <dir>.");
+  if (!values.name) fail("missing --name.");
+  if (values.shape !== "backend-turnkey") {
+    fail(
+      `unknown shape ${JSON.stringify(values.shape)} — shapes: backend-turnkey (turnkey and product are follow-ups).`,
+    );
+  }
+  if (existsSync(dir) && readdirSync(dir).length > 0) {
+    fail(`${dir} exists and is not empty — refusing to overwrite.`);
+  }
+  const devPort = values.port === undefined ? undefined : Number(values.port);
+  if (devPort !== undefined && (!Number.isInteger(devPort) || devPort < 1 || devPort > 65535)) {
+    fail(`--port must be an integer in 1..65535, got ${JSON.stringify(values.port)}.`);
+  }
+
+  const { files } = createProduct({
+    dir,
+    name: values.name,
+    shape: values.shape as ProductShape,
+    devPort,
+    mediaImage: values["media-image"],
+    studioImage: values["studio-image"],
+    studioLib: values["studio-lib"],
+  });
+
+  console.log(`Generated ${files.length} files into ${dir} (shape: ${values.shape}).
+
+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 check:drift && 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.
+`);
+}
+
+if (import.meta.main) {
+  main(process.argv.slice(2));
+}

package/create-product/create-product.ts

@@ -0,0 +1,178 @@
+// `ctl-dev-kit create-product` — renders a new product repo from the dev-kit's
+// canonical bytes (see canon.ts). Two layers per shape:
+//
+//   - the CONVENTION layer (this file): every file the drift gate checks,
+//     identical across shapes, with the per-repo fill-ins placed exactly where
+//     the gate masks or leaves structure free;
+//   - the SHAPE layer (backend-turnkey.ts, ...): the source skeleton — package
+//     manifests, manifest/composer/materials modules, the five test tiers.
+//
+// New shapes (full turnkey, full product) slot in as additional ShapeModule
+// implementations; the convention layer is shared verbatim.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { backendTurnkey } from "./backend-turnkey.ts";
+import { type Canon, loadAsset, loadCanon, PRODUCT_SENTINEL } from "./canon.ts";
+
+export type ProductShape = "backend-turnkey";
+
+export interface CreateProductOptions {
+  dir: string;
+  name: string;
+  shape: ProductShape;
+  /** Local-dev backend port (the container always listens on 4321). */
+  devPort?: number;
+  /** Full media image ref (repo:tag). The npm norsk-sdk pin is the same
+   *  version string — media npm + image are built from one commit. */
+  mediaImage?: string;
+  /** Full studio image ref (repo:tag). */
+  studioImage?: string;
+  /** norsk-studio* npm pin; defaults to the studio image's bare tag (they
+   *  coincide when the published image matches the npm nightly). */
+  studioLib?: string;
+}
+
+export interface GeneratedFile {
+  path: string;
+  content: string;
+  executable?: boolean;
+}
+
+export interface ShapeContext {
+  name: string;
+  /** Workspace scope, `@<name>`. */
+  scope: string;
+  /** `product:` value for the shared workflows — `name` minus the `norsk-` prefix. */
+  dashboardKey: string;
+  devPort: number;
+  pins: { mediaImage: string; studioImage: string; studioLib: string; mediaLib: string };
+  canon: Canon;
+}
+
+export interface ShapeModule {
+  files(ctx: ShapeContext): GeneratedFile[];
+  claudeHead(ctx: ShapeContext): string;
+  claudeTail(ctx: ShapeContext): string;
+  rootTsconfigInclude: string[];
+}
+
+const SHAPES: Record<ProductShape, ShapeModule> = {
+  "backend-turnkey": backendTurnkey,
+};
+
+// Same known-good coherent set the monorepo's own test-harness pins. A fresh
+// repo's first upgrade-latest.yml run advances every one of these in lockstep.
+const DEFAULT_MEDIA_IMAGE = "norskvideo/norsk:1.0.402-2026-07-20-71aab79d";
+const DEFAULT_STUDIO_IMAGE = "norskvideo/norsk-studio:1.27.0-2026-07-21-fdea1794";
+
+const bareTag = (ref: string) => ref.slice(ref.lastIndexOf(":") + 1);
+
+export function shapeContext(opts: CreateProductOptions): ShapeContext {
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(opts.name)) {
+    throw new Error(
+      `invalid product name ${JSON.stringify(opts.name)} — lowercase letters, digits, hyphens; 1-63 chars (it names the container image, npm scope, and manifest).`,
+    );
+  }
+  const mediaImage = opts.mediaImage ?? DEFAULT_MEDIA_IMAGE;
+  const studioImage = opts.studioImage ?? DEFAULT_STUDIO_IMAGE;
+  return {
+    name: opts.name,
+    scope: `@${opts.name}`,
+    dashboardKey: opts.name.replace(/^norsk-/, ""),
+    devPort: opts.devPort ?? 4323,
+    pins: {
+      mediaImage,
+      studioImage,
+      studioLib: opts.studioLib ?? bareTag(studioImage),
+      mediaLib: bareTag(mediaImage),
+    },
+    canon: loadCanon(),
+  };
+}
+
+function conventionFiles(ctx: ShapeContext, shape: ShapeModule): GeneratedFile[] {
+  const { canon } = ctx;
+  const fillProduct = (workflow: string) => workflow.replaceAll(PRODUCT_SENTINEL, ctx.dashboardKey);
+  return [
+    { path: "CLAUDE.md", content: `${shape.claudeHead(ctx)}\n${canon.core}\n${shape.claudeTail(ctx)}` },
+    { path: "flake.nix", content: canon.flake },
+    { path: "flake.lock", content: canon.flakeLock },
+    { path: "biome.json", content: canon.biome },
+    { path: "tsconfig.base.json", content: canon.tsconfigBase },
+    { path: "dprint.json", content: canon.dprint },
+    {
+      path: "tsconfig.json",
+      content: `${JSON.stringify({ extends: "./tsconfig.base.json", include: shape.rootTsconfigInclude }, null, 2)}\n`,
+    },
+    {
+      path: ".gitignore",
+      content: `${canon.gitignoreCore}\n# Repo-specific entries go below (the block above is drift-gated verbatim).\n`,
+    },
+    { path: ".github/workflows/checks.yml", content: fillProduct(canon.checks) },
+    { path: ".github/workflows/upgrade-latest.yml", content: fillProduct(canon.upgradeLatest) },
+    { path: ".github/actions/ci-status-dispatch/action.yml", content: loadAsset("ci-status-dispatch.yml") },
+    { path: "manifest.seed.json", content: seedJson(ctx) },
+    { path: "deployment/build-image.sh", content: buildImageWrapper(ctx), executable: true },
+  ];
+}
+
+function seedJson(ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      latest: {
+        media: ctx.pins.mediaImage,
+        studio: ctx.pins.studioImage,
+        source: "nightly-baseline",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function buildImageWrapper(ctx: ShapeContext): string {
+  // The gate requires the find_dev_kit function verbatim and a `source` of a
+  // dev-kit build/ script; the surrounding wrapper (tag, port) is per-product.
+  const canonBootstrap = ctx.canon.buildImageBootstrap;
+  const fnStart = canonBootstrap.indexOf("find_dev_kit() {");
+  if (fnStart === -1) throw new Error("canonical build-image.bootstrap.sh is missing find_dev_kit()");
+  const fn = canonBootstrap.slice(fnStart);
+  return `#!/usr/bin/env bash
+# Thin wrapper — all build logic lives in the shared bundle-image driver,
+# single-sourced in @norskvideo/ctl-dev-kit (build/build-bundle-image.sh). This
+# repo carries no copy of the build machinery; only the bootstrap below is a
+# forced (drift-gated) copy.
+set -euo pipefail
+
+product_dir="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+
+${fn}dev_kit="$(find_dev_kit "\${product_dir}")"
+
+export PRODUCT_DIR="\${product_dir}"
+export IMAGE_TAG="\${IMAGE_TAG:-${ctx.name}:dev}"
+# MUST be 4321: the runner's docker-runner hardcodes the container-internal
+# port and publishes 127.0.0.1:<hostPort>:4321 for every product. The dev port
+# in backend/src/index.ts only applies outside the container (PORT overrides it
+# here).
+export PRODUCT_PORT=4321
+# shellcheck source=/dev/null
+source "\${dev_kit}/build/build-bundle-image.sh"
+`;
+}
+
+export function planProduct(opts: CreateProductOptions): GeneratedFile[] {
+  const shape = SHAPES[opts.shape];
+  if (!shape) throw new Error(`unknown shape ${JSON.stringify(opts.shape)}`);
+  const ctx = shapeContext(opts);
+  return [...conventionFiles(ctx, shape), ...shape.files(ctx)];
+}
+
+export function createProduct(opts: CreateProductOptions): { files: string[] } {
+  const plan = planProduct(opts);
+  for (const file of plan) {
+    const path = join(opts.dir, file.path);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, file.content, { mode: file.executable ? 0o755 : 0o644 });
+  }
+  return { files: plan.map((f) => f.path) };
+}

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "exports": {
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./testing/invariants": "./testing/invariants.ts",
+    "./testing/byte-snapshot": "./testing/byte-snapshot.ts",
+    "./create-product": "./create-product/create-product.ts"
+  },
+  "bin": {
+    "ctl-dev-kit": "./create-product/cli.ts"
+  },
+  "dependencies": {
+    "@norskvideo/ctl-sdk": "^0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/testing/INVARIANTS.template.md

@@ -0,0 +1,49 @@
+# Workflow invariants
+
+<!-- Template from @norskvideo/ctl-dev-kit testing/INVARIANTS.template.md.
+Copy to the product repo root as INVARIANTS.md, replace the example rows with
+this product's real invariants, and add the parity-guard test below. -->
+
+The load-bearing rules this product's composed workflow must never break. Each
+has a stable ID (`INV-<AREA>-<NNN>`; never renumber, never reuse a retired ID)
+and at least one test that cites the ID verbatim — the parity guard fails CI
+when a row has no citing test or a test cites an unknown ID. When a code
+comment carries one of these rules, cite the ID there too instead of restating
+the rule.
+
+| ID           | Invariant                                                                                                  | Guarded by                 |
+| ------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------- |
+| INV-SCTE-001 | The SCTE-35 side-car subscribes the programme audio only (reference clock) — it never sits in the AV path  | `components.test.ts`       |
+| INV-AD-002   | Scheduled ad insertions are emitted only onto pushed destinations, never the local pull                    | `components.test.ts`       |
+| INV-ENC-003  | Every ladder rung carries an `nvidia` encode block only — no software/quadra fallback rung                 | `components.test.ts`       |
+| INV-GPU-004  | No raw in-memory video reaches an NVIDIA surface without a videoCompose upload (engine segfault otherwise) | `compose-workflow.test.ts` |
+| INV-LL-005   | The low-latency rung feeds WHEP only — it never reaches the HLS ladder                                     | `compose-workflow.test.ts` |
+
+The rows above are worked examples (funke-pegasus's real invariants); delete
+them when seeding a new product.
+
+## Parity guard
+
+Copy into `tests/unit/invariants-parity.test.ts`:
+
+```ts
+import { expect, test } from "bun:test";
+import { join } from "node:path";
+import { invariantParityFromDisk } from "@norskvideo/ctl-dev-kit/testing/invariants";
+
+const root = join(import.meta.dir, "..", "..");
+
+test("every invariant has a citing test and every cited ID is tabled", () => {
+  const report = invariantParityFromDisk({
+    invariantsPath: join(root, "INVARIANTS.md"),
+    testDirs: [join(root, "shared"), join(root, "tests")],
+  });
+  expect(report.problems).toEqual([]);
+});
+```
+
+Point `testDirs` at every tree whose `*.test.ts` files guard invariants. A
+runtime-only invariant the emitted graph can't show (e.g. a timing guarantee)
+still gets a table row — declare its ID in the guard's `untestableIds` option;
+the guard rejects unknown entries and flags the marker as stale once a test
+does cite the ID.

package/testing/byte-snapshot.ts

@@ -0,0 +1,43 @@
+// Byte-snapshot harness for product wire formats: assert an emitted artifact
+// (workflow YAML, manifest JSON, compose file) matches a committed fixture
+// byte-for-byte, so unintended emission changes show up as a reviewable diff.
+// Refresh deliberately: UPDATE_SNAPSHOTS=1 bun test <suite> rewrites fixtures;
+// commit the diff with the change that caused it. Framework-free (plain throw),
+// so it works under bun:test, vitest, or bare scripts alike.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+const UPDATE_HINT = "run UPDATE_SNAPSHOTS=1 bun test to (re)write it, then commit the fixture";
+
+function updating(): boolean {
+  const v = process.env.UPDATE_SNAPSHOTS;
+  return v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+
+function firstDiffLine(actual: string, expected: string): string {
+  const a = actual.split("\n");
+  const e = expected.split("\n");
+  for (let i = 0; i < Math.max(a.length, e.length); i++) {
+    if (a[i] !== e[i]) {
+      return `line ${i + 1}: snapshot ${JSON.stringify(e[i] ?? "<missing>")}, actual ${JSON.stringify(a[i] ?? "<missing>")}`;
+    }
+  }
+  return "content differs";
+}
+
+export function expectByteSnapshot(actual: string, fixturePath: string): void {
+  if (updating()) {
+    mkdirSync(dirname(fixturePath), { recursive: true });
+    writeFileSync(fixturePath, actual);
+    return;
+  }
+  if (!existsSync(fixturePath)) {
+    throw new Error(`no committed snapshot at ${fixturePath} — ${UPDATE_HINT}.`);
+  }
+  const expected = readFileSync(fixturePath, "utf8");
+  if (actual !== expected) {
+    throw new Error(
+      `emitted bytes differ from the committed snapshot ${fixturePath} (${firstDiffLine(actual, expected)}). If the change is intended, ${UPDATE_HINT}.`,
+    );
+  }
+}

package/testing/invariants.ts

@@ -0,0 +1,117 @@
+// Layer 3 scaffold: a product's load-bearing invariants live in a rules table
+// (INVARIANTS.md, stable IDs) instead of scattered comments, and a parity guard
+// keeps table and tests in lockstep — every invariant is referenced by at least
+// one test, and no test invents an ID the table doesn't define. See
+// INVARIANTS.template.md for the table format and the copy-paste guard test.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// IDs are INV-<AREA>-<NNN>: greppable, stable under renumbering-free growth,
+// and specific enough that a bare prose mention can't collide by accident.
+const ID = /INV-[A-Z0-9]+-\d{3}/;
+const ID_TOKEN = new RegExp(`\\b${ID.source}\\b`, "g");
+const TABLE_ROW = new RegExp(`^\\|\\s*(${ID.source})\\s*\\|\\s*(.*?)\\s*\\|`);
+
+export interface Invariant {
+  id: string;
+  rule: string;
+  line: number;
+}
+
+export function parseInvariants(markdown: string): Invariant[] {
+  const invariants: Invariant[] = [];
+  markdown.split("\n").forEach((text, i) => {
+    const row = text.match(TABLE_ROW);
+    if (row?.[1] !== undefined && row[2] !== undefined) {
+      invariants.push({ id: row[1], rule: row[2], line: i + 1 });
+    }
+  });
+  return invariants;
+}
+
+export interface ParityReport {
+  ok: boolean;
+  problems: string[];
+}
+
+export interface ParityOptions {
+  // Runtime-only invariants no emitted-graph test can show (e.g. a timing
+  // guarantee). Still parity-checked: each must exist in the table, and a
+  // citing test appearing later flags the marker as stale.
+  untestableIds?: string[];
+}
+
+export function invariantParity(
+  markdown: string,
+  testSources: Record<string, string>,
+  opts: ParityOptions = {},
+): ParityReport {
+  const problems: string[] = [];
+  const invariants = parseInvariants(markdown);
+  const untestable = new Set(opts.untestableIds ?? []);
+
+  if (invariants.length === 0) {
+    problems.push("no invariants parsed — rows must look like `| INV-AREA-001 | rule text | guarded-by |`.");
+  }
+
+  const seen = new Set<string>();
+  for (const inv of invariants) {
+    if (seen.has(inv.id)) problems.push(`duplicate invariant ID ${inv.id} (line ${inv.line}).`);
+    seen.add(inv.id);
+  }
+
+  const referenced = new Set<string>();
+  for (const [file, source] of Object.entries(testSources)) {
+    for (const token of source.match(ID_TOKEN) ?? []) {
+      referenced.add(token);
+      if (invariants.length > 0 && !seen.has(token)) {
+        problems.push(`${file} references ${token}, which is not in the invariants table — add the row or fix the ID.`);
+      }
+    }
+  }
+
+  for (const inv of invariants) {
+    if (referenced.has(inv.id) && untestable.has(inv.id)) {
+      problems.push(
+        `invariant ${inv.id} is declared untestable but a test cites it — remove the stale untestableIds entry.`,
+      );
+    }
+    if (!referenced.has(inv.id) && !untestable.has(inv.id)) {
+      problems.push(
+        `invariant ${inv.id} (${inv.rule}) has no referencing test — cite its ID in the test that guards it, or declare it in untestableIds.`,
+      );
+    }
+  }
+
+  for (const id of untestable) {
+    if (!invariants.some((inv) => inv.id === id)) {
+      problems.push(
+        `untestableIds declares ${id}, which is not in the invariants table — add the row or drop the entry.`,
+      );
+    }
+  }
+
+  return { ok: problems.length === 0, problems };
+}
+
+function collectTestFiles(dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      if (entry !== "node_modules") collectTestFiles(path, out);
+    } else if (/\.test\.tsx?$/.test(entry)) {
+      out.push(path);
+    }
+  }
+}
+
+export function invariantParityFromDisk(
+  opts: { invariantsPath: string; testDirs: string[] } & ParityOptions,
+): ParityReport {
+  const markdown = readFileSync(opts.invariantsPath, "utf8");
+  const files: string[] = [];
+  for (const dir of opts.testDirs) collectTestFiles(dir, files);
+  const sources: Record<string, string> = {};
+  for (const file of files) sources[file] = readFileSync(file, "utf8");
+  return invariantParity(markdown, sources, { untestableIds: opts.untestableIds });
+}