@norskvideo/ctl-dev-kit 0.1.13 → 0.1.14

package/create-product/backend-turnkey.ts

@@ -0,0 +1,1389 @@
+// The backend-only turnkey shape (reuters-shaped): shared/ + backend/ + tests/,
+// no frontend, dashboards, or components workspace. Smallest product surface —
+// one composed workflow served as a product-template tar from an express
+// backend. The skeleton ships the post-review state as defaults: seed through
+// parseManifestSeed, ManifestInput with no boilerplate, packProductTemplate
+// from the schema package, addComponent/stubbedLibrary with a THROWING
+// validate(), INVARIANTS + parity + byte-snapshot + studio-load wired into
+// test:unit, and an image smoke tier.
+import type { GeneratedFile, ShapeContext, ShapeModule } from "./create-product.ts";
+
+function claudeHead(ctx: ShapeContext): string {
+  return `# Working in this repo (${ctx.name})
+
+This is a **standalone product repo** generated by \`ctl-dev-kit create-product\`
+(shape: backend-turnkey). It builds a backend-only product container image and
+launches through the **released** norsk-ctl daemon — it needs no norsk-ctl
+source checkout. This file is conventions + gotchas; the fenced block below is
+the drift-gated shared core.
+`;
+}
+
+function claudeTail(ctx: ShapeContext): string {
+  return `## Getting norsk-ctl + the dev loop
+
+\`norsk-ctl\` (the daemon/CLI) is **not** an npm dep — it's the released binary,
+pinned in \`flake.nix\` and put on PATH by the nix shell:
+
+- \`nix develop\` -> build tools + the pinned \`norsk-ctl\` (\`.#dev\` is an alias).
+- \`nix develop .#build\` -> lean shell, no ctl — what CI uses.
+
+**Inner loop:** \`bun run dev\` (backend on :${ctx.devPort}), then
+\`norsk-ctl product add --dev-url http://localhost:${ctx.devPort}\` registers the
+running backend as a dev product.
+
+**Outer loop (real image):** \`bun run build:image\` builds the container via the
+shared dev-kit bundle driver (\`deployment/build-image.sh\`, tag \`${ctx.name}\`,
+container port 4321), then re-add it into the daemon —
+\`deployment/iterate.sh\` scripts the remove/re-add dance.
+
+## First run after generation
+
+1. \`bun install\`
+2. \`UPDATE_SNAPSHOTS=1 bun run test:unit\` — bakes the byte-snapshot fixtures
+   under \`tests/unit/__snapshots__/\` (the generator cannot compose without the
+   Studio packages installed). Commit them; from then on any emission change is
+   a reviewable fixture diff.
+3. \`bun run check:drift && bun run test:unit && bun run typecheck\`
+
+## Version pins
+
+Media + Studio container tags derive from **\`manifest.seed.json\`** (the
+machine-writable source of truth — RFC 0001 Workstream C) via
+\`shared/src/version.ts\`, which validates the seed through the SDK's
+\`parseManifestSeed\` at module load. \`version.test.ts\` fails if the seed and
+the \`norsk-sdk\`/\`norsk-studio*\` npm pins in \`shared/package.json\` drift
+apart — the shared \`upgrade-latest.yml\` bumps them all in lockstep nightly.
+
+## The stored-template trap
+
+The daemon launches instances from a **stored** product-template snapshot
+fetched once at \`product add\`, and refuses to overwrite one by name.
+Rebuilding the image does NOT reach launched instances or new launches until
+you refresh the stored template (\`norsk-ctl template refresh <name>\`, or the
+full delete/remove/re-add dance in \`deployment/iterate.sh\`). Verify the
+refreshed \`~/.norsk-ctl/product-templates/<name>/compose.yml\` carries the pins
+\`manifest.seed.json\` declares.
+
+## Build / test — the five layers
+
+- **Layer 1 — typed factories** (\`shared/src/workflow/components.ts\`): configs
+  \`import type\`d from each built-in's \`_gen/types\`; drift from Studio's
+  schema is a \`bun run typecheck\` failure.
+- **Layer 2 — \`builder.validate()\`**: the composer throws on any issue. Never
+  demote it to a warning; declare out-of-library components in
+  \`COMPONENT_STUBS\` (SDK \`stubbedLibrary\`) instead.
+- **Layer 3 — INVARIANTS.md + rules tests**: stable \`INV-*\` IDs, one row per
+  load-bearing invariant, parity-guarded (\`tests/unit/invariants-parity.test.ts\`)
+  so table and tests cannot drift apart.
+- **Layer 4 — studio-load round-trip** (\`tests/unit/loads-in-studio.test.ts\`):
+  emitted YAML through Studio's real \`document.load()\`.
+- **Layer 5 — integration**: not scaffolded. Decide + record here whether this
+  product carries one (unattended nightly bumps need it; see the dev-kit's
+  \`conventions/integration-testing.md\`).
+
+Byte-snapshots (\`tests/unit/workflow-snapshot.test.ts\`) pin the emitted wire
+bytes; \`UPDATE_SNAPSHOTS=1\` refreshes deliberately.
+
+- \`bun run test\` / \`test:unit\` — shared/backend units + tests/unit scaffolds.
+- \`bun run test:image\` — image smoke test (needs Docker + \`bun run build:image\`):
+  runs the built container and asserts the surface \`product add\` probes.
+- \`bun run check:drift\` — the shared-conventions gate; CI runs it plus
+  lint/typecheck/test:unit via the drift-gated \`checks.yml\`.
+`;
+}
+
+function rootPackageJson(ctx: ShapeContext): string {
+  const { studioLib, mediaLib } = ctx.pins;
+  return `${JSON.stringify(
+    {
+      name: ctx.name,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      workspaces: ["shared", "backend", "tests"],
+      scripts: {
+        clean: "bun run --cwd shared clean",
+        format: "biome format --write .",
+        lint: "biome check .",
+        "lint:fix": "biome check --write .",
+        test: "bun run test:unit",
+        "test:unit": "bun test shared/src/ backend/src/ tests/unit/",
+        "test:image": "bun test tests/image/",
+        "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-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:shared": "bun run --cwd shared build",
+        "build:backend": "bun run --cwd backend build",
+        "build:image": "bash deployment/build-image.sh",
+        dev: "bun run --cwd backend dev",
+        start: "bun run --cwd backend start",
+        iterate: "bash deployment/iterate.sh",
+      },
+      devDependencies: {
+        "@biomejs/biome": "2.5.5",
+        "@norskvideo/ctl-dev-kit": "^0.1.10",
+        "@types/bun": "latest",
+        "@types/node": "^22.10.0",
+        typescript: "^5.7.2",
+      },
+      packageManager: "bun@1.3.13",
+      overrides: {
+        ws: "^8.20.1",
+        "shell-quote": "^1.9.0",
+        "fast-xml-parser": "^5.10.1",
+        "fast-uri": "^3.1.4",
+        "@norskvideo/norsk-api": mediaLib,
+        "@norskvideo/norsk-sdk": mediaLib,
+        "@norskvideo/norsk-studio": studioLib,
+        "@norskvideo/norsk-studio-builder": studioLib,
+        "@norskvideo/norsk-studio-built-ins": studioLib,
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function invariantsMd(ctx: ShapeContext): string {
+  return `# Workflow invariants
+
+<!-- Format from @norskvideo/ctl-dev-kit testing/INVARIANTS.template.md. -->
+
+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
+(\`tests/unit/invariants-parity.test.ts\`) 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-GRAPH-001   | The ingest matches the configured transport (srt-listener/srt-caller) and port             | \`compose-workflow.test.ts\` |
+| INV-GRAPH-002   | The egest dials the configured destination and subscribes to the ingest's video + audio    | \`compose-workflow.test.ts\` |
+| INV-GRAPH-003   | The preview taps ingest video only — it never sits in the egest path                       | \`compose-workflow.test.ts\` |
+| INV-COMPOSE-001 | validate() is a throwing gate: an identifier that is neither real nor stubbed fails compose | \`compose-workflow.test.ts\` |
+
+Seeded by \`ctl-dev-kit create-product\` for the ${ctx.name} starter graph —
+replace/extend the rows as the real workflow takes shape.
+`;
+}
+
+function sharedPackageJson(ctx: ShapeContext): string {
+  const { studioLib, mediaLib } = ctx.pins;
+  return `${JSON.stringify(
+    {
+      name: `${ctx.scope}/shared`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      exports: {
+        ".": "./src/index.ts",
+        "./manifest": "./src/manifest.ts",
+        "./product-template": "./src/product-template.ts",
+        "./schemas": "./src/schemas/index.ts",
+        "./workflow": "./src/workflow/index.ts",
+      },
+      scripts: {
+        build:
+          "bun build src/index.ts --outdir dist --target=bun --external @norskvideo/norsk-studio --external @norskvideo/norsk-studio-builder --external @norskvideo/norsk-studio-built-ins",
+        clean: "rm -rf dist",
+        test: "bun test src/",
+        typecheck: "bunx tsc --noEmit",
+      },
+      dependencies: {
+        "@norskvideo/ctl-product-template-schema": "^0.1.0",
+        "@norskvideo/ctl-sdk": "^0.1.1",
+        "@norskvideo/norsk-sdk": mediaLib,
+        "@norskvideo/norsk-studio": studioLib,
+        "@norskvideo/norsk-studio-builder": studioLib,
+        "@norskvideo/norsk-studio-built-ins": studioLib,
+        yaml: "^2.8.0",
+        zod: "^4.3.6",
+      },
+      devDependencies: {
+        "@norskvideo/ctl-foundation": "^0.1.0",
+        "@types/bun": "latest",
+        "@types/node": "^22.10.0",
+        typescript: "^5.7.2",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+const WORKSPACE_TSCONFIG = `{
+  "extends": "../tsconfig.base.json",
+  "include": ["src/**/*"]
+}
+`;
+
+function versionTs(ctx: ShapeContext): string {
+  return `import { parseManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
+import rawSeed from "../../manifest.seed.json" with { type: "json" };
+
+export const PRODUCT_NAME = "${ctx.name}";
+export const PRODUCT_VERSION = "0.0.1";
+
+// Validate at module load so an invalid seed fails loudly at startup (and in
+// every test run) rather than rendering a compose from garbage. The SDK's
+// SeedSchema is strict; never import the JSON raw.
+const seedResult = parseManifestSeed(rawSeed);
+if (seedResult.status !== "ok") {
+  throw new Error(\`manifest.seed.json is invalid: \${seedResult.error}\`);
+}
+const latest = seedResult.value.latest;
+if (latest === undefined) {
+  throw new Error("manifest.seed.json has no 'latest' channel");
+}
+
+const bareTag = (ref: string) => ref.slice(ref.lastIndexOf(":") + 1);
+const repoOf = (ref: string) => ref.slice(0, ref.lastIndexOf(":"));
+
+// Media-engine + Studio control-plane images, derived from manifest.seed.json
+// (the machine-writable source of truth — RFC 0001 Workstream C). Kept in step
+// with the norsk-sdk / norsk-studio-* npm pins in shared/package.json;
+// version.test.ts fails if the tags and the npm pins drift apart.
+//
+// Overridable via env as a FULL ref (repo:tag) on the PRODUCT BACKEND process,
+// which renders the product-template compose. Guard \`process\` for the
+// browser: this module is re-exported from the shared index.
+const env = typeof process !== "undefined" ? process.env : ({} as Record<string, string | undefined>);
+
+export const MEDIA_IMAGE = env.MEDIA_IMAGE ?? latest.media;
+export const MEDIA_IMAGE_REPO = repoOf(MEDIA_IMAGE);
+export const MEDIA_IMAGE_TAG = bareTag(MEDIA_IMAGE);
+
+export const STUDIO_IMAGE = env.STUDIO_IMAGE ?? latest.studio;
+export const STUDIO_IMAGE_REPO = repoOf(STUDIO_IMAGE);
+export const STUDIO_IMAGE_TAG = bareTag(STUDIO_IMAGE);
+`;
+}
+
+function versionTestTs(ctx: ShapeContext): string {
+  return `import { describe, expect, it } from "bun:test";
+import pkg from "../package.json" with { type: "json" };
+import {
+  MEDIA_IMAGE,
+  MEDIA_IMAGE_REPO,
+  MEDIA_IMAGE_TAG,
+  PRODUCT_NAME,
+  STUDIO_IMAGE,
+  STUDIO_IMAGE_REPO,
+  STUDIO_IMAGE_TAG,
+} from "./version.ts";
+
+const studioNpmPin = pkg.dependencies["@norskvideo/norsk-studio"];
+// Media engine + its SDK are built from the same commit, so the image tag and
+// the norsk-sdk npm pin share one version string — guard the coupling.
+const mediaNpmPin = pkg.dependencies["@norskvideo/norsk-sdk"];
+
+it("product identifies as ${ctx.name}", () => {
+  expect(PRODUCT_NAME).toBe("${ctx.name}");
+});
+
+describe("npm pins stay coupled to the seed", () => {
+  it("media image matches the @norskvideo/norsk-sdk npm pin (same-commit family)", () => {
+    expect(MEDIA_IMAGE_TAG).toBe(mediaNpmPin);
+  });
+
+  // The studio npm/image SHA split is INTENTIONAL when it happens: Norsk builds
+  // the studio npm packages and the studio Docker image from different commits,
+  // so the image rides the newest published Docker Hub tag on the same
+  // major.minor.patch line as the npm nightly (exactly how the shared
+  // upgrade-latest.yml advances the pair).
+  it("studio image stays on the npm pin's major.minor.patch line", () => {
+    expect(STUDIO_IMAGE_TAG.split("-")[0]).toBe(studioNpmPin.split("-")[0]);
+  });
+
+  it("keeps the norsk-studio-* npm pins in step with each other", () => {
+    expect(pkg.dependencies["@norskvideo/norsk-studio-builder"]).toBe(studioNpmPin);
+    expect(pkg.dependencies["@norskvideo/norsk-studio-built-ins"]).toBe(studioNpmPin);
+  });
+});
+
+// The repo/tag split stays consistent with the full ref — the RFC 0001 §5
+// invariant that keeps every product speaking the same MEDIA_*/STUDIO_* shape.
+it("repo and tag recombine to the full image ref", () => {
+  expect(\`\${MEDIA_IMAGE_REPO}:\${MEDIA_IMAGE_TAG}\`).toBe(MEDIA_IMAGE);
+  expect(\`\${STUDIO_IMAGE_REPO}:\${STUDIO_IMAGE_TAG}\`).toBe(STUDIO_IMAGE);
+});
+`;
+}
+
+const MANIFEST_TS = `import { type Manifest, type ManifestInput, ManifestSchema } from "@norskvideo/ctl-sdk/browser";
+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
+// backend-only turnkey has no configure UI — configScreenUrl is optional and
+// omitted, so the runner skips its registration probe (no placeholder HTML).
+// Parsing at build time keeps the served manifest the READER shape with the
+// defaults filled in.
+export function buildManifest(): Manifest {
+  const manifest: ManifestInput = {
+    manifestSchemaVersion: 1,
+    name: PRODUCT_NAME,
+    version: PRODUCT_VERSION,
+    minRunnerVersion: "0.1.0",
+    api: {
+      basePath: "/api",
+      proxyPaths: ["/api/*"],
+      openapiFragmentPath: "/api/openapi.yaml",
+    },
+    targets: ["docker-compose"],
+    // Keep in lockstep with STARTER_CONFIGS in backend/src/routes/product-template.ts.
+    defaultProductTemplates: [{ name: "default", url: "/api/product-template/default" }],
+  };
+  return ManifestSchema.parse(manifest);
+}
+`;
+
+const MANIFEST_TEST_TS = `import { describe, expect, it } from "bun:test";
+import { ManifestSchema } from "@norskvideo/ctl-sdk/browser";
+import { buildManifest } from "./manifest.ts";
+
+describe("manifest", () => {
+  it("round-trips through ManifestSchema", () => {
+    expect(ManifestSchema.safeParse(buildManifest()).success).toBe(true);
+  });
+
+  it("omits the configure UI (backend-only: the runner skips its probe)", () => {
+    expect(buildManifest().ui.configScreenUrl).toBeUndefined();
+  });
+});
+`;
+
+const SCHEMAS_INDEX_TS = `export * from "./config.ts";
+`;
+
+const CONFIG_TS = `import { z } from "zod";
+
+// The product's launch-time config: one SRT ingest passed through to one SRT
+// egest with a monitoring preview — the starter graph. Grow it field-by-field
+// as the product takes shape, ADDITIVELY (RFC 0001): never repurpose or remove
+// a required field once released.
+export const ProductConfigSchema = z
+  .object({
+    input: z
+      .object({
+        transport: z.enum(["srt-listener", "srt-caller"]).default("srt-listener"),
+        // srt-caller only: the remote host this ingest dials out to.
+        host: z.string().optional(),
+        port: z.number().int().min(1).max(65535).default(5001),
+        streamId: z.string().default("input"),
+      })
+      // prefault, not default: the fallback is input-shaped ({} with the inner
+      // defaults filling in), which zod v4's .default() no longer accepts.
+      .prefault({}),
+    output: z.object({
+      host: z.string(),
+      port: z.number().int().min(1).max(65535),
+    }),
+  })
+  .strict();
+
+export type ProductConfig = z.infer<typeof ProductConfigSchema>;
+`;
+
+const CONFIG_TEST_TS = `import { describe, expect, it } from "bun:test";
+import example from "../../../examples/default/input.json" with { type: "json" };
+import { ProductConfigSchema } from "./config.ts";
+
+describe("ProductConfigSchema", () => {
+  it("accepts the shipped starter example", () => {
+    expect(ProductConfigSchema.safeParse(example).success).toBe(true);
+  });
+
+  it("rejects an unknown field (strict — catch typos at the edge)", () => {
+    const parsed = ProductConfigSchema.safeParse({ output: { host: "h", port: 1 }, extra: true });
+    expect(parsed.success).toBe(false);
+  });
+});
+`;
+
+const IDS_TS = `// Stable component ids — part of the workflow contract: they appear in the
+// emitted YAML and are cited by INVARIANTS.md rules, so never rename without
+// coordinating every consumer.
+export const INGEST_ID = "ingest";
+export const EGEST_ID = "egest";
+export const PREVIEW_ID = "preview";
+`;
+
+const COMPONENTS_TS = `// Typed factories for the Studio components the starter graph wires up.
+// Config types come from each built-in's OpenAPI-generated _gen/types, so
+// drift between what we emit and Studio's real schema surfaces as a TS error
+// at compile time (Layer 1). Subscriptions are NOT set here — the builder
+// derives them via connect()/pick*(); the factories only shape config.
+import type { WorkflowComponent } from "@norskvideo/ctl-sdk/workflow";
+import type { components as SrtCallerInputSchemas } from "@norskvideo/norsk-studio-built-ins/lib/input.srt-caller/_gen/types";
+import type { components as SrtListenerInputSchemas } from "@norskvideo/norsk-studio-built-ins/lib/input.srt-listener/_gen/types";
+import type { components as PreviewOutputSchemas } from "@norskvideo/norsk-studio-built-ins/lib/output.preview/_gen/types";
+import type { components as SrtCallerOutputSchemas } from "@norskvideo/norsk-studio-built-ins/lib/output.srt-caller/_gen/types";
+
+type SrtListenerInputConfig = SrtListenerInputSchemas["schemas"]["Config"];
+type SrtCallerInputConfig = SrtCallerInputSchemas["schemas"]["Config"];
+type SrtCallerOutputConfig = SrtCallerOutputSchemas["schemas"]["Config"];
+type PreviewConfig = PreviewOutputSchemas["schemas"]["Config"];
+
+export type IngestSrtListenerArgs = { id: string; port: number; streamId: string; displayName: string };
+
+export function ingestSrtListener(args: IngestSrtListenerArgs): WorkflowComponent<SrtListenerInputConfig> {
+  return {
+    type: "input.srt-listener",
+    config: {
+      port: args.port,
+      host: "0.0.0.0",
+      socketOptions: {},
+      sourceNames: "permissive",
+      streamIds: [args.streamId],
+      burstProtection: true,
+      initialState: "enabled",
+      decodeOutputs: { decode: false },
+      id: args.id,
+      displayName: args.displayName,
+    },
+    subscriptions: [],
+  };
+}
+
+export type IngestSrtCallerArgs = { id: string; host: string; port: number; streamId: string; displayName: string };
+
+export function ingestSrtCaller(args: IngestSrtCallerArgs): WorkflowComponent<SrtCallerInputConfig> {
+  return {
+    type: "input.srt-caller",
+    config: {
+      port: args.port,
+      host: args.host,
+      enabled: true,
+      socketOptions: {},
+      streamId: args.streamId,
+      id: args.id,
+      displayName: args.displayName,
+    },
+    subscriptions: [],
+  };
+}
+
+export type EgestSrtCallerArgs = { id: string; host: string; port: number; displayName: string };
+
+export function egestSrtCaller(args: EgestSrtCallerArgs): WorkflowComponent<SrtCallerOutputConfig> {
+  return {
+    type: "output.srt-caller",
+    config: {
+      displayName: args.displayName,
+      destinations: [{ host: args.host, port: args.port }],
+      jitterBuffer: {},
+      avDelayMs: 50,
+      subtitles: { kind: "cta708" },
+      socketOptions: {},
+      tsEncoder: { kind: "standard" },
+      id: args.id,
+    },
+    subscriptions: [],
+  };
+}
+
+export type PreviewArgs = { id: string; displayName: string };
+
+export function preview(args: PreviewArgs): WorkflowComponent<PreviewConfig> {
+  return {
+    type: "output.preview",
+    config: {
+      displayName: args.displayName,
+      previewMode: "image",
+      showPreview: true,
+      jitterBuffer: {},
+      id: args.id,
+    },
+    subscriptions: [],
+  };
+}
+`;
+
+const STUDIO_LIBRARY_TS = `// Build the composer's ComponentLibrary: Studio's REAL NodeInfos first, this
+// product's declared stubs second, and nothing else — so builder.validate()
+// stays a THROWING gate (a typo'd identifier fails the compose instead of
+// silently resolving to a permissive synthetic).
+//
+// NodeInfos are resolved STATICALLY via the built-ins' getNodeInfo aggregator
+// rather than a RuntimeSystem + registerAll: registerAll does an fs.readdir of
+// the package's lib/ AT RUNTIME, and \`bun build --target=bun\` bakes in the
+// host path, which does not exist inside the product image. The static path
+// pulls each component's design-time info module only and survives bundling.
+import { callableDefault } from "@norskvideo/ctl-sdk";
+import { type ComponentStubSpec, stubbedLibrary } from "@norskvideo/ctl-sdk/workflow";
+import { RegistrationConsts } from "@norskvideo/norsk-studio/lib/extension/client-types";
+import type { ComponentLibrary, NodeInfoForBuilder } from "@norskvideo/norsk-studio-builder";
+import getNodeInfoImport from "@norskvideo/norsk-studio-built-ins/lib/info";
+
+// TS-compiled-to-CJS with __esModule + exports.default; how that surfaces to
+// an ESM importer depends on who bundled it. callableDefault tolerates every
+// interop shape.
+const getNodeInfo = callableDefault<(consts: unknown, identifier: string) => unknown>(
+  getNodeInfoImport,
+  "@norskvideo/norsk-studio-built-ins/lib/info",
+);
+
+// Components not in the npm library (this product's own, or alpha/custom nodes
+// that live only in the studio image) are declared here as metadata-only stubs
+// — precise media contracts, no browser code, no _gen/types needed. See
+// ComponentStubSpec in @norskvideo/ctl-sdk/workflow.
+export const COMPONENT_STUBS: ComponentStubSpec[] = [];
+
+export async function buildStudioLibrary(): Promise<ComponentLibrary> {
+  return stubbedLibrary<NodeInfoForBuilder>(
+    (identifier) => getNodeInfo(RegistrationConsts, identifier) as NodeInfoForBuilder | undefined,
+    COMPONENT_STUBS,
+  );
+}
+`;
+
+const COMPOSE_WORKFLOW_TS = `// The production composer: source-first, left-to-right, every connect narrowed
+// through a pick* helper so filters resolve against real availableStreams().
+// addComponent keeps the factories' typing at the addNode boundary — no
+// \`config as never\`.
+import { addComponent, toWorkflowDoc, type WorkflowDoc } from "@norskvideo/ctl-sdk/workflow";
+import { autoLayout, type ComponentLibrary, pickAll, WorkflowBuilder } from "@norskvideo/norsk-studio-builder";
+import type { ProductConfig } from "../schemas/config.ts";
+import { egestSrtCaller, ingestSrtCaller, ingestSrtListener, preview } from "./components.ts";
+import { EGEST_ID, INGEST_ID, PREVIEW_ID } from "./ids.ts";
+
+export function composeWorkflow(config: ProductConfig, library: ComponentLibrary): WorkflowDoc {
+  const builder = new WorkflowBuilder(library);
+
+  // addComponent per branch: each factory keeps its own config typing at the
+  // addNode boundary (a union would erase it).
+  const ingest =
+    config.input.transport === "srt-caller"
+      ? addComponent(
+          builder,
+          ingestSrtCaller({
+            id: INGEST_ID,
+            host: config.input.host ?? "127.0.0.1",
+            port: config.input.port,
+            streamId: config.input.streamId,
+            displayName: "Ingest",
+          }),
+        )
+      : addComponent(
+          builder,
+          ingestSrtListener({
+            id: INGEST_ID,
+            port: config.input.port,
+            streamId: config.input.streamId,
+            displayName: "Ingest",
+          }),
+        );
+
+  const egest = addComponent(
+    builder,
+    egestSrtCaller({ id: EGEST_ID, host: config.output.host, port: config.output.port, displayName: "Egest" }),
+  );
+  const monitor = addComponent(builder, preview({ id: PREVIEW_ID, displayName: "Preview" }));
+
+  pickAll(builder.connect(ingest, egest), ["video", "audio"]);
+  pickAll(builder.connect(ingest, monitor), ["video"]);
+
+  // Layer 2 is a THROWING gate (INV-COMPOSE-001). Never demote this to a
+  // warning — declare out-of-library components in COMPONENT_STUBS instead.
+  const issues = builder.validate();
+  if (issues.length > 0) {
+    const formatted = issues.map((i) => \`  - \${i.nodeId ?? "<doc>"}: \${i.message}\`).join("\\n");
+    throw new Error(\`WorkflowBuilder.validate() returned issues:\\n\${formatted}\`);
+  }
+
+  const doc = toWorkflowDoc(builder);
+  doc.__layout = autoLayout(doc);
+  return doc;
+}
+`;
+
+const COMPOSE_WORKFLOW_TEST_TS = `// Layer 3: the INVARIANTS.md rules table in executable form. Each rule cites
+// its INV-* ID verbatim; tests/unit/invariants-parity.test.ts fails the suite
+// if table and tests drift apart. The matrix exercises every composer branch.
+import { beforeAll, describe, expect, test } from "bun:test";
+import type { WorkflowComponent, WorkflowDoc } from "@norskvideo/ctl-sdk/workflow";
+import type { ComponentLibrary } from "@norskvideo/norsk-studio-builder";
+import { type ProductConfig, ProductConfigSchema } from "../schemas/config.ts";
+import { composeWorkflow } from "./compose-workflow.ts";
+import { EGEST_ID, INGEST_ID, PREVIEW_ID } from "./ids.ts";
+import { buildStudioLibrary } from "./studio-library.ts";
+
+const MATRIX: [string, ProductConfig][] = [
+  ["listener", ProductConfigSchema.parse({ input: {}, output: { host: "203.0.113.10", port: 8001 } })],
+  [
+    "caller",
+    ProductConfigSchema.parse({
+      input: { transport: "srt-caller", host: "203.0.113.9", port: 7001 },
+      output: { host: "203.0.113.10", port: 8001 },
+    }),
+  ],
+];
+
+let library: ComponentLibrary;
+const docs = new Map<string, WorkflowDoc>();
+
+beforeAll(async () => {
+  library = await buildStudioLibrary();
+  for (const [name, config] of MATRIX) docs.set(name, composeWorkflow(config, library));
+});
+
+function findById(doc: WorkflowDoc, id: string): WorkflowComponent {
+  const found = doc.components.find((c) => (c.config as { id?: string }).id === id);
+  if (!found) throw new Error(\`no component with id \${id}\`);
+  return found;
+}
+
+function subscribedMedia(component: WorkflowComponent, source: string): string[] {
+  return component.subscriptions
+    .filter((s) => s.source === source)
+    .flatMap((s) => s.streams.filter.map((f) => f.media));
+}
+
+describe.each(MATRIX)("composed graph (%s)", (name) => {
+  test("INV-GRAPH-001: ingest matches the configured transport and port", () => {
+    const config = MATRIX.find(([n]) => n === name)?.[1] as ProductConfig;
+    const ingest = findById(docs.get(name) as WorkflowDoc, INGEST_ID);
+    const expectedType = config.input.transport === "srt-caller" ? "input.srt-caller" : "input.srt-listener";
+    expect(ingest.type).toBe(expectedType);
+    expect((ingest.config as { port?: number }).port).toBe(config.input.port);
+  });
+
+  test("INV-GRAPH-002: egest dials the configured destination with ingest AV", () => {
+    const config = MATRIX.find(([n]) => n === name)?.[1] as ProductConfig;
+    const egest = findById(docs.get(name) as WorkflowDoc, EGEST_ID);
+    expect((egest.config as { destinations?: { host: string; port: number }[] }).destinations).toEqual([
+      { host: config.output.host, port: config.output.port },
+    ]);
+    const media = subscribedMedia(egest, INGEST_ID);
+    expect(media).toContain("video");
+    expect(media).toContain("audio");
+  });
+
+  test("INV-GRAPH-003: preview taps ingest video only", () => {
+    const monitor = findById(docs.get(name) as WorkflowDoc, PREVIEW_ID);
+    expect(subscribedMedia(monitor, INGEST_ID)).toEqual(["video"]);
+  });
+});
+
+test("INV-COMPOSE-001: an identifier that is neither real nor stubbed fails the compose", () => {
+  const emptyLibrary: ComponentLibrary = { find: () => undefined };
+  const [, config] = MATRIX[0] as [string, ProductConfig];
+  expect(() => composeWorkflow(config, emptyLibrary)).toThrow();
+});
+`;
+
+const WORKFLOW_INDEX_TS = `export * from "./components.ts";
+export * from "./compose-workflow.ts";
+export * from "./ids.ts";
+export * from "./studio-library.ts";
+`;
+
+const SHARED_INDEX_TS = `export * from "./manifest.ts";
+export * from "./product-template.ts";
+export * from "./schemas/index.ts";
+export * from "./version.ts";
+export * from "./workflow/index.ts";
+`;
+
+function productTemplateTs(ctx: ShapeContext): string {
+  return `// Product-template materials: the manifest/compose/parameters/workflow set the
+// runner stores at \`product add\`. Packing to tar is single-sourced in
+// @norskvideo/ctl-product-template-schema/pack — this repo carries no copy of
+// the wire format.
+import {
+  type ProductTemplateManifest,
+  type ProductTemplateMaterials,
+  type ProductTemplateParameter,
+  STANDARD_ADVANCED_OVERRIDES,
+} from "@norskvideo/ctl-product-template-schema";
+import type { ComponentLibrary } from "@norskvideo/norsk-studio-builder";
+import { stringify as yamlStringify } from "yaml";
+import type { ProductConfig } from "./schemas/config.ts";
+import { MEDIA_IMAGE, PRODUCT_NAME, PRODUCT_VERSION, STUDIO_IMAGE } from "./version.ts";
+import { composeWorkflow } from "./workflow/compose-workflow.ts";
+
+export type BuildOpts = {
+  // The builder's component library, built once at process startup via
+  // buildStudioLibrary(). Required — the production composer is the builder.
+  library?: ComponentLibrary;
+  generatedAt?: Date;
+};
+
+const STUDIO_DEFAULT_HOST_PORT = 18000;
+
+export function buildProductTemplateMaterials(config: ProductConfig, opts: BuildOpts = {}): ProductTemplateMaterials {
+  if (!opts.library) {
+    throw new Error(
+      "buildProductTemplateMaterials: ComponentLibrary required (call buildStudioLibrary() once at startup)",
+    );
+  }
+  const generatedAt = opts.generatedAt ?? new Date();
+  const manifest: ProductTemplateManifest = {
+    productTemplateSchemaVersion: 1,
+    productName: PRODUCT_NAME,
+    productVersion: PRODUCT_VERSION,
+    target: "docker-compose",
+    generatedAt: generatedAt.toISOString(),
+    proxy: {
+      // Permissive starter set: exposes Studio's own UI/API through the oauth2
+      // proxy. Narrow as the product grows a surface of its own.
+      expose: ["/", "/static/*", "/api/*", "/live/api/*", "/ws", "/ws/*"],
+    },
+    advanced: { ...STANDARD_ADVANCED_OVERRIDES },
+  };
+
+  return {
+    manifest,
+    composeYaml: renderCompose(config),
+    parameters: { parameters: renderParameters(config) },
+    workflow: yamlStringify(composeWorkflow(config, opts.library), { aliasDuplicateObjects: false }),
+    components: [],
+    dashboards: [],
+    assets: [],
+    workdirSeed: [],
+  };
+}
+
+// docker-compose for the studio + media pair. The reserved \`studio\` +
+// \`media\` service names let the runner's override generator target them
+// (workflow.yml mount, license env/file mount, etc).
+export function renderCompose(config: ProductConfig): string {
+  const studioEnv: Record<string, string> = {
+    NORSK_HOST: "media",
+    // Studio declares this product to the engine at the V2 licence handshake;
+    // without it Studio falls back to its baked default and the instance would
+    // demand a Studio entitlement rather than its own.
+    NORSK_PRODUCT_NAME: PRODUCT_NAME,
+    NODE_CONFIG: JSON.stringify({ server: { library: ["@norskvideo/norsk-studio-built-ins"] } }),
+  };
+
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: docker-compose variable reference, not a TS template literal
+  const studioPorts: string[] = ["\${STUDIO_HOST_PORT}:8000"];
+  const mediaPorts: string[] = [];
+  // SRT-listener ingests bind inside the media engine and must be published as
+  // UDP (without /udp docker publishes TCP and the host can't reach Norsk's
+  // listener). srt-caller ingests dial out — no published port.
+  if (config.input.transport === "srt-listener") {
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: docker-compose variable reference, not a TS template literal
+    mediaPorts.push("\${INGEST_PORT}:\${INGEST_PORT}/udp");
+  }
+
+  const compose = {
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: docker-compose variable reference, not a TS template literal
+    name: "\${INSTANCE_NAME}",
+    services: {
+      studio: {
+        image: STUDIO_IMAGE,
+        environment: studioEnv,
+        ports: studioPorts,
+        restart: "unless-stopped",
+      },
+      media: {
+        image: MEDIA_IMAGE,
+        ...(mediaPorts.length > 0 ? { ports: mediaPorts } : {}),
+        restart: "unless-stopped",
+      },
+    },
+  };
+  return yamlStringify(compose, { aliasDuplicateObjects: false, lineWidth: 0 });
+}
+
+function renderParameters(config: ProductConfig): ProductTemplateParameter[] {
+  const params: ProductTemplateParameter[] = [
+    {
+      name: "INSTANCE_NAME",
+      purpose: "Compose project label for this instance",
+      type: "string",
+      default: "${ctx.dashboardKey}",
+    },
+    {
+      name: "STUDIO_HOST_PORT",
+      purpose: "Port on the host where Studio's web UI is exposed",
+      type: "number",
+      default: String(STUDIO_DEFAULT_HOST_PORT),
+    },
+  ];
+  if (config.input.transport === "srt-listener") {
+    params.push({
+      name: "INGEST_PORT",
+      purpose: "Host UDP port to bind for the SRT ingest",
+      type: "number",
+      default: String(config.input.port),
+    });
+  }
+  return params;
+}
+`;
+}
+
+const PRODUCT_TEMPLATE_TEST_TS = `// Tar round-trip: pack real materials, unpack, validate what came out against
+// the schema package — proves the wire format end to end without a daemon.
+import { beforeAll, describe, expect, it } from "bun:test";
+import { listTarNames, unpackTar } from "@norskvideo/ctl-foundation";
+import {
+  ParametersFileSchema,
+  ProductTemplateManifestSchema,
+  ProductTemplateMaterialsSchema,
+} from "@norskvideo/ctl-product-template-schema";
+import { packProductTemplate } from "@norskvideo/ctl-product-template-schema/pack";
+import type { ComponentLibrary } from "@norskvideo/norsk-studio-builder";
+import { parse as yamlParse } from "yaml";
+import example from "../../examples/default/input.json" with { type: "json" };
+import { buildProductTemplateMaterials } from "./product-template.ts";
+import { ProductConfigSchema } from "./schemas/config.ts";
+import { buildStudioLibrary } from "./workflow/studio-library.ts";
+
+let library: ComponentLibrary;
+
+beforeAll(async () => {
+  library = await buildStudioLibrary();
+});
+
+describe("product-template materials", () => {
+  it("validate against ProductTemplateMaterialsSchema", () => {
+    const materials = buildProductTemplateMaterials(ProductConfigSchema.parse(example), { library });
+    expect(ProductTemplateMaterialsSchema.safeParse(materials).success).toBe(true);
+  });
+
+  it("pack to a tar whose entries round-trip through the schema package", () => {
+    const materials = buildProductTemplateMaterials(ProductConfigSchema.parse(example), { library });
+    const tar = packProductTemplate(materials);
+
+    const names = listTarNames(tar);
+    expect(names.status).toBe("ok");
+    if (names.status !== "ok") return;
+    expect(names.value).toEqual(
+      expect.arrayContaining(["manifest.json", "compose.yml", "workflow.yml", "parameters.yaml"]),
+    );
+
+    const entries = unpackTar(tar);
+    expect(entries.status).toBe("ok");
+    if (entries.status !== "ok") return;
+    const decode = (name: string) => {
+      const entry = entries.value.find((e) => e.name === name);
+      if (!entry) throw new Error(\`missing tar entry \${name}\`);
+      return new TextDecoder().decode(entry.content);
+    };
+    expect(ProductTemplateManifestSchema.safeParse(JSON.parse(decode("manifest.json"))).success).toBe(true);
+    expect(ParametersFileSchema.safeParse(yamlParse(decode("parameters.yaml"))).success).toBe(true);
+    expect(decode("compose.yml")).toContain("studio:");
+  });
+});
+`;
+
+function backendPackageJson(ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      name: `${ctx.scope}/backend`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      exports: { ".": "./src/index.ts" },
+      scripts: {
+        dev: "bun run --watch src/index.ts",
+        build: "bun build src/index.ts --outdir dist --target=bun",
+        clean: "rm -rf dist",
+        start: "bun run src/index.ts",
+        test: "bun test src/",
+        typecheck: "bunx tsc --noEmit",
+      },
+      dependencies: {
+        [`${ctx.scope}/shared`]: "workspace:*",
+        "@norskvideo/ctl-product-template-schema": "^0.1.0",
+        "@norskvideo/ctl-sdk": "^0.1.1",
+        "@norskvideo/norsk-studio-builder": ctx.pins.studioLib,
+        cors: "^2.8.5",
+        express: "^5.0.1",
+        zod: "^4.3.6",
+      },
+      devDependencies: {
+        "@types/bun": "latest",
+        "@types/cors": "^2.8.17",
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.10.0",
+        typescript: "^5.7.2",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function backendIndexTs(ctx: ShapeContext): string {
+  return `import { startServer } from "./server.ts";
+
+// ${ctx.devPort} is the LOCAL-DEV default only; inside the container the
+// bundle driver sets PORT=4321 (the port the runner hardcodes).
+const port = Number(process.env.PORT ?? ${ctx.devPort});
+await startServer(port);
+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 cors from "cors";
+import express from "express";
+import { manifestRouter } from "./routes/manifest.ts";
+import { openapiRouter } from "./routes/openapi.ts";
+import { makeProductTemplateRouter } from "./routes/product-template.ts";
+
+export async function startServer(port: number): Promise<Server> {
+  // Built once at startup: Studio's real NodeInfos + this product's declared
+  // stubs. Passed into the product-template route so every build reuses it.
+  const library = await buildStudioLibrary();
+
+  const app = express();
+  app.use(cors());
+  app.use(express.json({ limit: "1mb" }));
+
+  app.get("/healthz", (_req, res) => {
+    res.status(200).send("ok");
+  });
+
+  app.use(manifestRouter);
+  app.use("/api", openapiRouter);
+  app.use("/api", makeProductTemplateRouter(library));
+
+  return await new Promise<Server>((resolve, reject) => {
+    const server = app.listen(port, () => resolve(server));
+    server.on("error", (err) => reject(err));
+  });
+}
+`;
+}
+
+function backendServerTestTs(ctx: ShapeContext): string {
+  return `// The daemon hard-rejects a registration whose manifest-declared paths don't
+// answer (waitForReady probes api.healthCheckPath; defaultProductTemplates are
+// GET at product-add time). Assert here that every declared path is actually
+// served — a mismatch otherwise only surfaces as "product did not become
+// ready" at \`product add\` time, never in a local run.
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import type { Server } from "node:http";
+import { buildManifest } from "${ctx.scope}/shared/manifest";
+import { startServer } from "./server.ts";
+
+let server: Server;
+let baseUrl: string;
+
+beforeAll(async () => {
+  server = await startServer(0);
+  const address = server.address();
+  if (address === null || typeof address === "string") throw new Error("expected a TCP address");
+  baseUrl = \`http://127.0.0.1:\${address.port}\`;
+});
+
+afterAll(() => {
+  server.close();
+});
+
+describe("manifest-declared paths are actually served", () => {
+  it("serves api.healthCheckPath", async () => {
+    const res = await fetch(\`\${baseUrl}\${buildManifest().api.healthCheckPath}\`);
+    expect(res.status).toBe(200);
+  });
+
+  it("serves the manifest itself at /manifest.json", async () => {
+    const res = await fetch(\`\${baseUrl}/manifest.json\`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { name?: string };
+    expect(body.name).toBe(buildManifest().name);
+  });
+
+  it("serves api.openapiFragmentPath", async () => {
+    const res = await fetch(\`\${baseUrl}\${buildManifest().api.openapiFragmentPath}\`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("openapi:");
+  });
+
+  it("serves every defaultProductTemplates url as a tar", async () => {
+    for (const template of buildManifest().defaultProductTemplates) {
+      const res = await fetch(\`\${baseUrl}\${template.url}\`);
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("x-tar");
+    }
+  });
+});
+`;
+}
+
+function routesManifestTs(ctx: ShapeContext): string {
+  return `import { buildManifest } from "${ctx.scope}/shared/manifest";
+import { createManifestRouter } from "@norskvideo/ctl-sdk";
+
+export const manifestRouter = createManifestRouter(buildManifest);
+`;
+}
+
+function routesOpenapiTs(ctx: ShapeContext): string {
+  return `import { PRODUCT_VERSION } from "${ctx.scope}/shared";
+import { createOpenapiRouter } from "@norskvideo/ctl-sdk";
+
+// Minimal OpenAPI fragment — the manifest points the runner at
+// /api/openapi.yaml. Expand (or generate from zod) as the API grows.
+const buildOpenApiYaml = (): string => \`openapi: 3.0.3
+info:
+  title: ${ctx.name}
+  version: "\${PRODUCT_VERSION}"
+paths:
+  /api/product-template:
+    post:
+      summary: Build a product-template tar from a ProductConfig
+      responses:
+        "200":
+          description: product-template tar
+          content:
+            application/x-tar: {}
+        "400":
+          description: invalid config
+  /api/product-template/{slug}:
+    get:
+      summary: Build a product-template tar from a named starter config
+      parameters:
+        - name: slug
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: product-template tar
+          content:
+            application/x-tar: {}
+        "404":
+          description: unknown slug
+\`;
+
+export const openapiRouter = createOpenapiRouter(buildOpenApiYaml);
+`;
+}
+
+function routesProductTemplateTs(ctx: ShapeContext): string {
+  return `import { buildProductTemplateMaterials } from "${ctx.scope}/shared/product-template";
+import { ProductConfigSchema } from "${ctx.scope}/shared/schemas";
+import { packProductTemplate } from "@norskvideo/ctl-product-template-schema/pack";
+import type { ComponentLibrary } from "@norskvideo/norsk-studio-builder";
+import { Router } from "express";
+import defaultExample from "../../../examples/default/input.json" with { type: "json" };
+
+// Starter configs, mirrored in manifest.ts's defaultProductTemplates[]. JSON
+// imported at module load so the bundler inlines it — the deployed container
+// doesn't ship the examples/ source tree. Keep the two in lockstep.
+const STARTER_CONFIGS: Record<string, unknown> = {
+  default: defaultExample,
+};
+
+export function makeProductTemplateRouter(library: ComponentLibrary): Router {
+  const router = Router();
+
+  const sendTemplate = (res: Parameters<Parameters<Router["get"]>[1]>[1], raw: unknown, filename: string) => {
+    const parsed = ProductConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+      res.status(400).json({ error: "invalid config", issues: parsed.error.issues });
+      return;
+    }
+    try {
+      const materials = buildProductTemplateMaterials(parsed.data, { library });
+      const tar = packProductTemplate(materials);
+      res
+        .status(200)
+        .type("application/x-tar")
+        .setHeader("Content-Disposition", \`attachment; filename="\${filename}"\`)
+        .send(Buffer.from(tar));
+    } catch (err) {
+      res.status(500).json({
+        error: "product-template generation failed",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  };
+
+  // POST /api/product-template — build a tar from an arbitrary ProductConfig.
+  router.post("/product-template", (req, res) => {
+    sendTemplate(res, req.body, "${ctx.name}.tar");
+  });
+
+  // GET /api/product-template/<slug> — the runner GETs these at product-add
+  // time per manifest.defaultProductTemplates.
+  router.get("/product-template/:slug", (req, res) => {
+    const raw = STARTER_CONFIGS[req.params.slug];
+    if (!raw) {
+      res.status(404).json({ error: "unknown product-template slug", slug: req.params.slug });
+      return;
+    }
+    sendTemplate(res, raw, \`\${req.params.slug}.tar\`);
+  });
+
+  return router;
+}
+`;
+}
+
+function testsPackageJson(ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      name: `${ctx.scope}/tests`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      devDependencies: {
+        "@norskvideo/ctl-dev-kit": "^0.1.10",
+        "@norskvideo/ctl-test-harness": "^0.1.3",
+        "@types/bun": "latest",
+        "@types/node": "^22.10.0",
+        typescript: "^5.7.2",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+const INVARIANTS_PARITY_TEST_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, "backend"), join(root, "tests")],
+  });
+  expect(report.problems).toEqual([]);
+});
+`;
+
+const WORKFLOW_SNAPSHOT_TEST_TS = `// Byte-snapshots of the emitted wire formats for the starter config: any
+// emission change must come with a reviewable fixture diff. First run:
+// UPDATE_SNAPSHOTS=1 bun run test:unit bakes the fixtures — commit them.
+import { beforeAll, test } from "bun:test";
+import { join } from "node:path";
+import { expectByteSnapshot } from "@norskvideo/ctl-dev-kit/testing/byte-snapshot";
+import type { ProductTemplateMaterials } from "@norskvideo/ctl-product-template-schema";
+import example from "../../examples/default/input.json" with { type: "json" };
+import { buildProductTemplateMaterials } from "../../shared/src/product-template.ts";
+import { ProductConfigSchema } from "../../shared/src/schemas/config.ts";
+import { buildStudioLibrary } from "../../shared/src/workflow/studio-library.ts";
+
+const fixture = (name: string) => join(import.meta.dir, "__snapshots__", name);
+
+let materials: ProductTemplateMaterials;
+
+beforeAll(async () => {
+  materials = buildProductTemplateMaterials(ProductConfigSchema.parse(example), {
+    library: await buildStudioLibrary(),
+    // Snapshots must be byte-stable; only the manifest carries generatedAt and
+    // it is not snapshotted.
+    generatedAt: new Date(0),
+  });
+});
+
+test("workflow.yml emission is byte-stable", () => {
+  expectByteSnapshot(materials.workflow ?? "", fixture("default.workflow.yml"));
+});
+
+test("compose.yml emission is byte-stable", () => {
+  expectByteSnapshot(materials.composeYaml, fixture("default.compose.yml"));
+});
+`;
+
+const LOADS_IN_STUDIO_TEST_TS = `// Layer 4: the emitted YAML through Studio's REAL document.load(), so every
+// built-in's zod schema validates what the composer actually emits. Stubs
+// cover COMPONENT_STUBS identifiers (no schema to validate against).
+import { expect, test } from "bun:test";
+import { assertLoadsInStudio } from "@norskvideo/ctl-test-harness/studio-load";
+import example from "../../examples/default/input.json" with { type: "json" };
+import { buildProductTemplateMaterials } from "../../shared/src/product-template.ts";
+import { ProductConfigSchema } from "../../shared/src/schemas/config.ts";
+import { buildStudioLibrary, COMPONENT_STUBS } from "../../shared/src/workflow/studio-library.ts";
+
+test("starter workflow round-trips through Studio document.load()", async () => {
+  const materials = buildProductTemplateMaterials(ProductConfigSchema.parse(example), {
+    library: await buildStudioLibrary(),
+  });
+  const compiled = await assertLoadsInStudio(materials.workflow ?? "", {
+    stubs: COMPONENT_STUBS.map((s) => s.identifier),
+  });
+  expect(compiled.errors).toEqual([]);
+});
+`;
+
+function imageSmokeTestTs(ctx: ShapeContext): string {
+  return `// Image-tier smoke test for the packaged product container. Docker-only (no
+// daemon, no licence): docker run the built image on a loopback port,
+// mirroring the runner's -p 127.0.0.1:<hostPort>:4321, and curl the surface
+// \`product add\` probes. This is the tier that catches bundling constraints
+// (e.g. a runtime fs.readdir surviving \`bun build --target=bun\`) that unit
+// tests and a host \`bun run start\` cannot see.
+//
+// Run \`bun run build:image\` first; then \`bun run test:image\`.
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+
+const IMAGE_TAG = process.env.IMAGE_TAG ?? "${ctx.name}:dev";
+
+function imageExists(tag: string): boolean {
+  return spawnSync("docker", ["image", "inspect", tag], { stdio: "ignore" }).status === 0;
+}
+
+async function waitForHealthz(url: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const r = await fetch(url, { signal: AbortSignal.timeout(1000) });
+      if (r.ok) return;
+    } catch {}
+    await Bun.sleep(500);
+  }
+  throw new Error(\`container \${url} never became healthy within \${timeoutMs}ms\`);
+}
+
+describe("${ctx.name} image: container surface", () => {
+  test("built image serves /healthz, the manifest, and the starter template tar", async () => {
+    expect(imageExists(IMAGE_TAG), \`image \${IMAGE_TAG} not found — run: bun run build:image\`).toBe(true);
+
+    const hostPort = 24329;
+    const run = spawnSync("docker", ["run", "-d", "--rm", "-p", \`127.0.0.1:\${hostPort}:4321\`, IMAGE_TAG], {
+      encoding: "utf-8",
+    });
+    expect(run.status, \`docker run failed: \${run.stderr}\`).toBe(0);
+    const containerId = run.stdout.trim();
+
+    try {
+      const base = \`http://127.0.0.1:\${hostPort}\`;
+      await waitForHealthz(\`\${base}/healthz\`, 30_000);
+
+      const manRes = await fetch(\`\${base}/manifest.json\`);
+      expect(manRes.status).toBe(200);
+      const manifest = (await manRes.json()) as { name?: string };
+      expect(manifest.name).toBe("${ctx.name}");
+
+      const tarRes = await fetch(\`\${base}/api/product-template/default\`);
+      expect(tarRes.status).toBe(200);
+      expect(tarRes.headers.get("content-type")).toContain("x-tar");
+      const tar = Buffer.from(await tarRes.arrayBuffer());
+      // ustar magic at offset 257 of the first header block.
+      expect(tar.subarray(257, 262).toString("ascii")).toBe("ustar");
+      const tarText = tar.toString("latin1");
+      for (const entry of ["manifest.json", "compose.yml", "workflow.yml", "parameters.yaml"]) {
+        expect(tarText).toContain(entry);
+      }
+    } finally {
+      spawnSync("docker", ["rm", "-f", containerId], { stdio: "ignore" });
+    }
+  }, 120_000);
+});
+`;
+}
+
+function iterateSh(ctx: ShapeContext): string {
+  return `#!/usr/bin/env bash
+# Iterate loop: rebuild the image and push it through the daemon — the
+# stored-template trap (see CLAUDE.md) means NONE of this happens implicitly.
+# Modeled on funke-pegasus's deployment/iterate.sh (the fleet reference); grow
+# the TODOs into real probes as the product takes shape.
+set -euo pipefail
+
+product="${ctx.name}"
+template="default"
+image="\${IMAGE_TAG:-${ctx.name}:dev}"
+
+echo "==> build image \${image}"
+bun run build:image
+
+# Refresh the stored template in place if the daemon supports it; otherwise
+# fall back to the full remove/re-add dance.
+if norsk-ctl template refresh "\${template}" 2>/dev/null; then
+  echo "==> stored template refreshed"
+else
+  echo "==> template refresh unavailable — full remove/re-add"
+  # TODO: delete instances first: norsk-ctl instance delete <id> --purge
+  norsk-ctl template remove "\${template}" || true
+  norsk-ctl product remove "\${product}" || true
+  norsk-ctl product add --image "\${image}" \${NORSK_LICENSE_FILE:+--license-file "\${NORSK_LICENSE_FILE}"}
+fi
+
+# Verify the refresh landed — never assume (a stale stored template debugs
+# like a code bug).
+echo "==> stored template pins:"
+grep "image:" "\${HOME}/.norsk-ctl/product-templates/\${template}/compose.yml"
+
+# TODO: launch an instance, pump a source, and assert output — funke's
+# iterate.sh pumps SRT and asserts playable HLS; do the equivalent here.
+echo "==> done (launch + probe steps are TODO)"
+`;
+}
+
+const DOCKERIGNORE = `node_modules
+**/node_modules
+dist
+backend/dist
+shared/dist
+.git
+.github
+*.md
+`;
+
+function exampleInputJson(_ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      input: { transport: "srt-listener", port: 5001, streamId: "input" },
+      output: { host: "127.0.0.1", port: 6000 },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+export const backendTurnkey: ShapeModule = {
+  claudeHead,
+  claudeTail,
+  rootTsconfigInclude: ["tests/**/*"],
+  files(ctx: ShapeContext): GeneratedFile[] {
+    return [
+      { path: "package.json", content: rootPackageJson(ctx) },
+      { path: "INVARIANTS.md", content: invariantsMd(ctx) },
+      { path: ".dockerignore", content: DOCKERIGNORE },
+      { path: "examples/default/input.json", content: exampleInputJson(ctx) },
+      { path: "deployment/iterate.sh", content: iterateSh(ctx), executable: true },
+      { path: "shared/package.json", content: sharedPackageJson(ctx) },
+      { path: "shared/tsconfig.json", content: WORKSPACE_TSCONFIG },
+      { path: "shared/src/index.ts", content: SHARED_INDEX_TS },
+      { path: "shared/src/version.ts", content: versionTs(ctx) },
+      { path: "shared/src/version.test.ts", content: versionTestTs(ctx) },
+      { path: "shared/src/manifest.ts", content: MANIFEST_TS },
+      { path: "shared/src/manifest.test.ts", content: MANIFEST_TEST_TS },
+      { path: "shared/src/schemas/index.ts", content: SCHEMAS_INDEX_TS },
+      { path: "shared/src/schemas/config.ts", content: CONFIG_TS },
+      { path: "shared/src/schemas/config.test.ts", content: CONFIG_TEST_TS },
+      { path: "shared/src/product-template.ts", content: productTemplateTs(ctx) },
+      { path: "shared/src/product-template.test.ts", content: PRODUCT_TEMPLATE_TEST_TS },
+      { path: "shared/src/workflow/index.ts", content: WORKFLOW_INDEX_TS },
+      { path: "shared/src/workflow/ids.ts", content: IDS_TS },
+      { path: "shared/src/workflow/components.ts", content: COMPONENTS_TS },
+      { path: "shared/src/workflow/studio-library.ts", content: STUDIO_LIBRARY_TS },
+      { path: "shared/src/workflow/compose-workflow.ts", content: COMPOSE_WORKFLOW_TS },
+      { path: "shared/src/workflow/compose-workflow.test.ts", content: COMPOSE_WORKFLOW_TEST_TS },
+      { path: "backend/package.json", content: backendPackageJson(ctx) },
+      { path: "backend/tsconfig.json", content: WORKSPACE_TSCONFIG },
+      { path: "backend/src/index.ts", content: backendIndexTs(ctx) },
+      { path: "backend/src/server.ts", content: backendServerTs(ctx) },
+      { path: "backend/src/server.test.ts", content: backendServerTestTs(ctx) },
+      { path: "backend/src/routes/manifest.ts", content: routesManifestTs(ctx) },
+      { path: "backend/src/routes/openapi.ts", content: routesOpenapiTs(ctx) },
+      { path: "backend/src/routes/product-template.ts", content: routesProductTemplateTs(ctx) },
+      { path: "tests/package.json", content: testsPackageJson(ctx) },
+      { path: "tests/unit/invariants-parity.test.ts", content: INVARIANTS_PARITY_TEST_TS },
+      { path: "tests/unit/workflow-snapshot.test.ts", content: WORKFLOW_SNAPSHOT_TEST_TS },
+      { path: "tests/unit/loads-in-studio.test.ts", content: LOADS_IN_STUDIO_TEST_TS },
+      { path: "tests/image/image-smoke.test.ts", content: imageSmokeTestTs(ctx) },
+    ];
+  },
+};