@norskvideo/ctl-test-harness 0.1.0

package/cli-command.d.ts

@@ -0,0 +1 @@
+export declare const cliCommand: string[];

package/cli-command.js

@@ -0,0 +1,45 @@
+// Resolve the command prefix used to spawn the norsk-ctl CLI, in priority order:
+//
+//   1. NORSK_CTL_BINARY=/path/to/norsk-ctl-<os>-<cpu>  — an explicit compiled
+//      binary, or "auto" to pick the platform binary under <cwd>/dist.
+//   2. The in-workspace CLI source, if this harness sits beside a norsk-ctl
+//      package (monorepo dev + in-repo product tests) — run via `bun run`.
+//   3. `norsk-ctl` on PATH — the fallback for a consumer of the published
+//      harness that has the CLI installed (the split-repo case).
+//
+// Spread into spawn args: [...cliCommand, "serve"].
+import { existsSync } from "node:fs";
+import { arch, platform } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+function platformBinaryName() {
+    const os = platform() === "darwin" ? "darwin" : "linux";
+    const cpu = arch() === "arm64" ? "arm64" : "x64";
+    return `norsk-ctl-${os}-${cpu}`;
+}
+function resolveBinary() {
+    const env = process.env.NORSK_CTL_BINARY;
+    if (!env)
+        return null;
+    const candidate = env === "auto" ? resolve(process.cwd(), "dist", platformBinaryName()) : resolve(env);
+    if (!existsSync(candidate)) {
+        throw new Error(`NORSK_CTL_BINARY not found: ${candidate}`);
+    }
+    return candidate;
+}
+function resolveWorkspaceSource() {
+    // packages/test-harness/{src,dist} -> packages/norsk-ctl/cli/src/index.ts.
+    const source = resolve(here, "../../norsk-ctl/cli/src/index.ts");
+    return existsSync(source) ? source : null;
+}
+function resolveCliCommand() {
+    const binary = resolveBinary();
+    if (binary)
+        return [binary];
+    const source = resolveWorkspaceSource();
+    if (source)
+        return ["bun", "run", source];
+    return ["norsk-ctl"];
+}
+export const cliCommand = resolveCliCommand();

package/daemon.d.ts

@@ -0,0 +1,47 @@
+import { pollUntil } from "./poll.js";
+import { makeStoreDir, makeTempDir, TEST_TMP_BASE } from "./temp-dir.js";
+export declare const HEALTH_TIMEOUT_MS = 120000;
+export { makeStoreDir, makeTempDir, pollUntil, TEST_TMP_BASE };
+export declare function requireLicenseFile(): string;
+export declare function runCli(storeDir: string, ...args: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+export declare function isPortFree(port: number): Promise<boolean>;
+export declare function killProcessOnPort(port: number): void;
+export declare function startDaemon(storeDir: string, options?: {
+    port?: number;
+    env?: Record<string, string>;
+}): {
+    daemon: ReturnType<typeof Bun.spawn>;
+    ready: Promise<void>;
+};
+/**
+ * Tear down a daemon-based test: delete instances, stop proxy, stop daemon, kill
+ * process, rm store. The teardown actions are injected as pre-bound thunks
+ * (`deleteInstance`/`stopProxy`/`stopDaemon`) — the caller binds them to
+ * norsk-ctl's typed CLI, so no command type leaks into this package.
+ */
+export declare function cleanupDaemon(opts: {
+    deleteInstance: (id: string) => Promise<unknown>;
+    stopProxy: () => Promise<unknown>;
+    stopDaemon: () => Promise<unknown>;
+    instances?: string[];
+    proxy?: boolean;
+    daemon: ReturnType<typeof Bun.spawn> | null;
+    storeDir: string;
+    containers: string[];
+}): Promise<void>;
+/** Tear down a direct-API test: stop proxy, remove instances, rm temp dir. */
+export declare function cleanupDirect(opts: {
+    proxy?: {
+        stop(): Promise<unknown>;
+    };
+    instances?: {
+        remove(id: string): Promise<unknown>;
+    };
+    instanceIds?: string[];
+    tempDir?: string;
+    containers: string[];
+}): Promise<void>;

package/daemon.js

@@ -0,0 +1,168 @@
+// Daemon-lifecycle helpers for the product integration harnesses. Self-contained
+// so the package publishes cleanly: it spawns the norsk-ctl CLI by command prefix
+// (see cli-command.ts) and drives teardown through an injected command runner,
+// carrying no dependency on norsk-ctl's generated typed `commands` builder.
+import { spawnSync } from "node:child_process";
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { cliCommand } from "./cli-command.js";
+import { pollUntil } from "./poll.js";
+import { makeStoreDir, makeTempDir, TEST_TMP_BASE } from "./temp-dir.js";
+process.env.NORSK_CTL_NO_MEDIA_DOWNLOAD = "1";
+export const HEALTH_TIMEOUT_MS = 120_000;
+export { makeStoreDir, makeTempDir, pollUntil, TEST_TMP_BASE };
+function splitLines(text) {
+    return text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+export function requireLicenseFile() {
+    const licenseFile = process.env.NORSK_LICENSE_FILE;
+    // Some tests call this at module-load (in describe()/test() bodies); others
+    // call it at execution time. A throw at module-load gets wrapped by bun's
+    // "Unhandled error between tests" reporter and produces a cascade of red
+    // alongside genuinely-unrelated failures. Instead, print one clean message
+    // and exit so the suite stops the moment we hit a license-needing test.
+    if (!licenseFile || !existsSync(licenseFile)) {
+        const reason = !licenseFile
+            ? "NORSK_LICENSE_FILE env var is not set."
+            : `License file not found at ${licenseFile} (from NORSK_LICENSE_FILE).`;
+        console.error(`\nIntegration tests require a Norsk license:\n  ${reason}\n\n  NORSK_LICENSE_FILE=/path/to/license.json bun run test:integration\n`);
+        process.exit(1);
+    }
+    return licenseFile;
+}
+export async function runCli(storeDir, ...args) {
+    const proc = Bun.spawn([...cliCommand, ...args], {
+        stdout: "pipe",
+        stderr: "pipe",
+        env: { ...process.env, NORSK_CTL_STORE_DIR: storeDir },
+    });
+    const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+    const exitCode = await proc.exited;
+    return { stdout, stderr, exitCode };
+}
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const srv = createServer();
+        srv.once("error", () => resolve(false));
+        srv.listen(port, () => srv.close(() => resolve(true)));
+    });
+}
+export function killProcessOnPort(port) {
+    try {
+        const result = spawnSync("lsof", ["-ti", `:${port}`], { encoding: "utf-8" });
+        const pids = splitLines(result.stdout ?? "");
+        for (const pid of pids) {
+            try {
+                process.kill(Number(pid), "SIGKILL");
+            }
+            catch { }
+        }
+    }
+    catch { }
+}
+export function startDaemon(storeDir, options) {
+    const port = options?.port ?? 8333;
+    killProcessOnPort(port);
+    // Root the instance working directory under the store dir (itself under
+    // TEST_TMP_BASE) rather than the daemon default ~/norsk-runtime. The launcher
+    // bind-mounts the workdir as /data and then mounts the stored template's
+    // workflow.yml (which lives under the store dir) *inside* it — Docker Desktop
+    // rejects a nested bind mount whose inner source resolves to a different host
+    // share-root than the outer, so both mounts must share the TEST_TMP_BASE root.
+    // With NORSK_CTL_STORE_DIR set, config.yaml is read from <storeDir>/config.yaml.
+    // networkMode is the one required config.yaml field — omitting it makes the
+    // whole file fail to parse (ConfigParseError), silently dropping the workdir
+    // override. Seed both.
+    const configPath = join(storeDir, "config.yaml");
+    if (!existsSync(configPath)) {
+        writeFileSync(configPath, `networkMode: docker\ndefaultWorkingDirectory: ${JSON.stringify(join(storeDir, "norsk-runtime"))}\n`);
+    }
+    const daemon = Bun.spawn([...cliCommand, "serve"], {
+        stdout: "inherit",
+        stderr: "inherit",
+        env: { ...process.env, NORSK_CTL_STORE_DIR: storeDir, NORSK_CTL_PORT: String(port), ...options?.env },
+    });
+    const ready = pollUntil(async () => {
+        const res = await fetch(`http://localhost:${port}/api/ready`, { signal: AbortSignal.timeout(1000) });
+        return res.ok;
+    }, { timeoutMs: 10_000, intervalMs: 500, label: "Daemon did not become ready" });
+    return { daemon, ready };
+}
+function runningContainers(names) {
+    const result = spawnSync("docker", ["ps", "--format", "{{.Names}}"], { encoding: "utf-8" });
+    if (result.status !== 0)
+        return [];
+    const running = splitLines(result.stdout);
+    return names.filter((n) => running.includes(n));
+}
+async function awaitContainerShutdown(containers) {
+    await pollUntil(async () => runningContainers(containers).length === 0, {
+        timeoutMs: 10_000,
+        intervalMs: 1000,
+        label: "Containers did not stop",
+    });
+    const still = runningContainers(containers);
+    if (still.length)
+        throw new Error(`Containers still running after cleanup: ${still.join(", ")}`);
+}
+/**
+ * Tear down a daemon-based test: delete instances, stop proxy, stop daemon, kill
+ * process, rm store. The teardown actions are injected as pre-bound thunks
+ * (`deleteInstance`/`stopProxy`/`stopDaemon`) — the caller binds them to
+ * norsk-ctl's typed CLI, so no command type leaks into this package.
+ */
+export async function cleanupDaemon(opts) {
+    for (const id of opts.instances ?? []) {
+        try {
+            await opts.deleteInstance(id);
+        }
+        catch (e) {
+            console.error(`cleanup: delete ${id} failed: ${e}`);
+        }
+    }
+    if (opts.proxy)
+        try {
+            await opts.stopProxy();
+        }
+        catch (e) {
+            console.error(`cleanup: proxy stop failed: ${e}`);
+        }
+    try {
+        await opts.stopDaemon();
+    }
+    catch (e) {
+        console.error(`cleanup: daemon stop failed: ${e}`);
+    }
+    if (opts.daemon) {
+        opts.daemon.kill();
+        // Escalate to SIGKILL after 3s if process hasn't exited
+        const race = Promise.race([opts.daemon.exited, Bun.sleep(3000).then(() => "timeout")]);
+        if ((await race) === "timeout") {
+            opts.daemon.kill(9);
+            await Promise.race([opts.daemon.exited, Bun.sleep(2000)]);
+        }
+    }
+    await awaitContainerShutdown(opts.containers);
+    rmSync(opts.storeDir, { recursive: true, force: true });
+}
+/** Tear down a direct-API test: stop proxy, remove instances, rm temp dir. */
+export async function cleanupDirect(opts) {
+    if (opts.proxy)
+        try {
+            await opts.proxy.stop();
+        }
+        catch { }
+    for (const id of opts.instanceIds ?? []) {
+        try {
+            await opts.instances?.remove(id);
+        }
+        catch { }
+    }
+    await awaitContainerShutdown(opts.containers);
+    if (opts.tempDir)
+        rmSync(opts.tempDir, { recursive: true, force: true });
+}

package/harness-config.d.ts

@@ -0,0 +1,18 @@
+/** Deterministic rolling hash of a slug, unsigned 32-bit. Identical inputs
+ *  always map to the same value so a test slug lands in the same port band on
+ *  every run. */
+export declare function slugHash(slug: string): number;
+/** The per-slug slot each product's `allocatePorts` bands off — `slugHash(slug)
+ *  % mod`. Products pick their own `mod` (playout/commentary 50, funke 40) so
+ *  their bands stay disjoint. */
+export declare function hashSlot(slug: string, mod: number): number;
+/** Fields every product harness allocates. Each product extends this with its
+ *  own ingest/egress ports (playout `ingestPort`/`egressPortBase`, funke
+ *  `primaryPort`/`backupPort`, …) — those know the product's config schema and
+ *  stay in each product's local `HarnessPorts`. */
+export interface BaseHarnessPorts {
+    daemonPort: number;
+    backendPort: number;
+    studioHostPort: number;
+    instancePortBase: number;
+}

package/harness-config.js

@@ -0,0 +1,28 @@
+// Pure port-allocation seam shared across the product integration harnesses.
+//
+// The class-of-bug this whole tier guards against is a mis-mapped ingest port:
+// the launched product template's SRT listener binds one port while the pumped
+// source dials another, so every matrix row silently times out on
+// `connectedStreams.length === 0`. Keeping the hash + slot math pure lets a unit
+// test catch a mis-allocation before any container starts.
+//
+// `slugHash` is byte-identical to the copies previously inlined in each
+// product's harness-config.ts / harness.ts; `hashSlot` names the `% mod` step
+// each product's `allocatePorts` performs before banding. The per-product port
+// bands + `remapConfigPorts` stay local (they know each config schema), but they
+// build on this seam.
+/** Deterministic rolling hash of a slug, unsigned 32-bit. Identical inputs
+ *  always map to the same value so a test slug lands in the same port band on
+ *  every run. */
+export function slugHash(slug) {
+    let h = 0;
+    for (let i = 0; i < slug.length; i++)
+        h = (h * 31 + slug.charCodeAt(i)) >>> 0;
+    return h;
+}
+/** The per-slug slot each product's `allocatePorts` bands off — `slugHash(slug)
+ *  % mod`. Products pick their own `mod` (playout/commentary 50, funke 40) so
+ *  their bands stay disjoint. */
+export function hashSlot(slug, mod) {
+    return slugHash(slug) % mod;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@norskvideo/ctl-test-harness",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    "./daemon": {
+      "types": "./daemon.d.ts",
+      "default": "./daemon.js"
+    },
+    "./source-pump": {
+      "types": "./source-pump.d.ts",
+      "default": "./source-pump.js"
+    },
+    "./studio-state": {
+      "types": "./studio-state.d.ts",
+      "default": "./studio-state.js"
+    },
+    "./harness-config": {
+      "types": "./harness-config.d.ts",
+      "default": "./harness-config.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/poll.d.ts

@@ -0,0 +1,5 @@
+export declare function pollUntil(fn: () => Promise<boolean>, opts: {
+    timeoutMs: number;
+    intervalMs?: number;
+    label?: string;
+}): Promise<void>;

package/poll.js

@@ -0,0 +1,23 @@
+const DEFAULT_INTERVAL_MS = 500;
+export async function pollUntil(fn, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            if (await fn())
+                return;
+        }
+        catch (e) {
+            lastError = e;
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+    // Surface the last thrown error so the timeout message points at the real
+    // cause instead of a tautological "predicate never returned true".
+    const base = opts.label
+        ? `${opts.label} (${opts.timeoutMs / 1000}s)`
+        : `pollUntil timed out after ${opts.timeoutMs / 1000}s`;
+    const suffix = lastError instanceof Error ? `; last error: ${lastError.message}` : "";
+    throw new Error(`${base}${suffix}`);
+}

package/source-pump.d.ts

@@ -0,0 +1,34 @@
+export interface SourceHandle {
+    name: string;
+    stop(): Promise<void>;
+}
+export declare function startCameraSource(opts: {
+    daemonPort: number;
+    instanceId: string;
+    preset?: string;
+    port: number;
+    streamId?: string;
+    /** Override the source identity (container name + management key).
+     *  Default: preset name. Required when the same preset must run multiple
+     *  times within an instance. */
+    name?: string;
+    timeoutMs?: number;
+}): Promise<SourceHandle>;
+export interface SrtPumpTarget {
+    port: number;
+    /** Source identity within the instance. Must be unique per instance. */
+    name: string;
+    /** Sent as the SRT `streamid` query param. When targeting a specific
+     *  listener that filters by streamid, pass the expected id here. */
+    streamId?: string;
+    /** Preset to source from. Defaults to camera1; pick camera2 (or rotate)
+     *  when you want visually distinct streams. */
+    preset?: string;
+}
+export declare function startSrtSources(opts: {
+    daemonPort: number;
+    instanceId: string;
+    targets: readonly SrtPumpTarget[];
+    timeoutMs?: number;
+}): Promise<SourceHandle[]>;
+export declare function stopAll(handles: readonly SourceHandle[]): Promise<void>;

package/source-pump.js

@@ -0,0 +1,68 @@
+// Thin wrapper over the daemon's SourceService (`POST /api/sources`).
+// Spawns a daemon-managed `linuxserver/ffmpeg` sidecar that loops a preset
+// MP4/TS over SRT into the target instance's media container.
+//
+// Polls `/api/sources?instanceId=<id>` for `running` (avoids the SSE-client
+// boilerplate). The daemon's stopAll(instanceId) sweep catches anything the
+// test forgets to release on its own.
+//
+// `name` overrides the source identity (container name + management key) so
+// multiple sources on the same preset can co-exist within one instance. See
+// `startSrtSources` for the multi-port fan-out helper that uses it.
+import { pollUntil } from "./daemon.js";
+export async function startCameraSource(opts) {
+    const preset = opts.preset ?? "camera1";
+    const name = opts.name ?? preset;
+    const body = { instanceId: opts.instanceId, preset, port: opts.port };
+    if (opts.streamId !== undefined)
+        body.streamId = opts.streamId;
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    const startRes = await fetch(`http://localhost:${opts.daemonPort}/api/sources`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!startRes.ok) {
+        throw new Error(`POST /api/sources failed (${startRes.status}): ${await startRes.text()}`);
+    }
+    await pollUntil(async () => {
+        const r = await fetch(`http://localhost:${opts.daemonPort}/api/sources?instanceId=${encodeURIComponent(opts.instanceId)}`, { signal: AbortSignal.timeout(5000) });
+        if (!r.ok)
+            return false;
+        // GET /api/sources returns a bare array of SampleSource — not { sources: [...] }.
+        const data = (await r.json());
+        const src = data.find((s) => s.name === name);
+        return src?.status === "running" || src?.status === "healthy";
+    }, {
+        timeoutMs: opts.timeoutMs ?? 120_000,
+        intervalMs: 1000,
+        label: `source ${name} for ${opts.instanceId} did not reach running`,
+    });
+    return {
+        name,
+        async stop() {
+            await fetch(`http://localhost:${opts.daemonPort}/api/sources/${encodeURIComponent(opts.instanceId)}/${encodeURIComponent(name)}`, { method: "DELETE", signal: AbortSignal.timeout(10_000) }).catch(() => { });
+        },
+    };
+}
+export async function startSrtSources(opts) {
+    const handles = [];
+    for (const target of opts.targets) {
+        const handle = await startCameraSource({
+            daemonPort: opts.daemonPort,
+            instanceId: opts.instanceId,
+            name: target.name,
+            port: target.port,
+            ...(target.preset !== undefined ? { preset: target.preset } : {}),
+            ...(target.streamId !== undefined ? { streamId: target.streamId } : {}),
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+        handles.push(handle);
+    }
+    return handles;
+}
+export async function stopAll(handles) {
+    await Promise.all(handles.map((h) => h.stop()));
+}

package/studio-state.d.ts

@@ -0,0 +1,101 @@
+export interface ComponentSummary {
+    componentId: string;
+    componentType: string;
+    capabilities?: Record<string, unknown>;
+}
+export interface ComponentsResponse {
+    components: ComponentSummary[];
+    totalComponents: number;
+}
+export declare function fetchComponents(studioHostPort: number): Promise<ComponentsResponse | null>;
+export declare function fetchComponentState(studioHostPort: number, componentId: string): Promise<unknown | null>;
+/** SRT-listener state shape — see
+ *  ~/src/norsk-studio/workspaces/built-ins/src/input.srt-listener/types.source.yaml:192-235.
+ *  Required fields per the YAML schema; harness asserts on the first two. */
+export interface SrtListenerState {
+    connectedStreams: string[];
+    connectedAt: Record<string, number>;
+    disabledStreams?: string[];
+    metrics?: unknown;
+    names?: string[];
+    recentRejections?: unknown[];
+}
+export declare function isSrtListenerState(value: unknown): value is SrtListenerState;
+/** One entry in OutputStreamResult — the streams a component is currently
+ *  producing. Empirically observed shape from /live/api/<id>/streams/mappings:
+ *  {
+ *    output: { media, displayName, sourceName, programNumber, streamId, renditionName },
+ *    metadata: { case: "video"|"audio", value: { ... } },
+ *    preview_url?: string,
+ *    preview_jpeg?: string,
+ *  }
+ *  `output.sourceName` is the stream's name, propagated through the wire
+ *  graph — for an input.srt-listener it is the configured sourceName. Sink
+ *  components (output.srt-listener, output.autoCmaf) typically don't produce
+ *  output streams and therefore return an empty array. */
+export interface StreamMappingEntry {
+    output: {
+        media?: string;
+        displayName?: string;
+        sourceName?: string;
+        renditionName?: string;
+        programNumber?: number;
+        streamId?: number;
+        [k: string]: unknown;
+    };
+    metadata?: unknown;
+    preview_url?: string;
+    preview_jpeg?: string;
+    [k: string]: unknown;
+}
+export declare function fetchStreamMappings(studioHostPort: number, componentId: string): Promise<StreamMappingEntry[] | null>;
+export declare function fetchStreamSources(studioHostPort: number, componentId: string): Promise<unknown | null>;
+export declare function fetchStreamUnmapped(studioHostPort: number, componentId: string): Promise<unknown | null>;
+export declare function fetchStreamFill(studioHostPort: number, componentId: string): Promise<unknown | null>;
+export interface AssertStreamOutputOpts {
+    studioHostPort: number;
+    componentId: string;
+    media: "video" | "audio" | "playlist";
+    /** Optional — pin the stream's name. For input.srt-listener it is the
+     *  configured sourceName; re-encoders that preserve the source name keep the
+     *  same value. Some processors drop the source name on their output, so omit
+     *  this filter when asserting downstream of them. */
+    expectedSourceName?: string;
+    /** Optional filter — pin a specific encoded rendition (e.g. "h264_1280x720"). */
+    renditionName?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+export declare function assertStreamOutput(opts: AssertStreamOutputOpts): Promise<void>;
+/** Polls Studio's per-component state for an SRT-listener until at least one
+ *  stream is reported as connected with a non-zero connectedAt timestamp. */
+export declare function assertSrtConnected(opts: {
+    studioHostPort: number;
+    componentId: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<void>;
+export interface CmafMultiVariantState {
+    url?: string;
+    enabled?: boolean;
+}
+/** Fetches the multivariant m3u8 URL from state, then GETs it. Fails if the URL
+ *  never appears within the timeout OR the body does not contain a reference to
+ *  every expected rendition label. Rendition labels are the child playlists'
+ *  filenames — Studio's autoCmaf lists each rendition as a
+ *  `#EXT-X-STREAM-INF ... URI="<rendition>/norsk.m3u8"` (video) or a
+ *  `#EXT-X-MEDIA:TYPE=AUDIO ... URI="<rendition>/norsk.m3u8"` line. The caller
+ *  passes the set of expected labels; the body must reference every one. */
+export declare function assertMultivariantHasRenditions(opts: {
+    studioHostPort: number;
+    componentId: string;
+    expectedRenditionLabels: readonly string[];
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<void>;
+export declare function assertNoUnmapped(opts: {
+    studioHostPort: number;
+    componentId: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<void>;

package/studio-state.js

@@ -0,0 +1,218 @@
+// Studio runtime-state fetchers, hit directly on the product-template-published
+// STUDIO_HOST_PORT (the product template publishes `deployment.studioHostPort`
+// on the studio service). No proxy/auth required — host-published port bypasses
+// nginx and oauth2-proxy entirely.
+//
+// Two endpoints power the topology + ingest assertions:
+//   GET /live/api/components            — topology: which component ids exist
+//   GET /live/api/<componentId>/state   — per-component runtime state
+//
+// 503 ("Workflow is not running yet") is normal during boot; both helpers
+// return null in that case so the caller's pollUntil keeps polling.
+//
+// This is the product-agnostic head shared by the playout & commentary
+// integration tiers (funke's file was a strict subset of the first two
+// fetchers). Extracted verbatim from the playout copy — the canonical text.
+// Commentary's WHIP-driver tail (RemoteCommentary*, discoverCommentaryWhipUrls,
+// assertCommentaryChannelOccupied) stays local to commentary.
+export async function fetchComponents(studioHostPort) {
+    const r = await fetch(`http://localhost:${studioHostPort}/live/api/components`, {
+        signal: AbortSignal.timeout(5000),
+    });
+    if (r.status === 503)
+        return null;
+    if (!r.ok)
+        throw new Error(`GET /live/api/components -> ${r.status}: ${await r.text()}`);
+    return (await r.json());
+}
+export async function fetchComponentState(studioHostPort, componentId) {
+    const r = await fetch(`http://localhost:${studioHostPort}/live/api/${encodeURIComponent(componentId)}/state`, {
+        signal: AbortSignal.timeout(5000),
+    });
+    if (r.status === 503 || r.status === 404)
+        return null;
+    if (!r.ok)
+        throw new Error(`GET /live/api/${componentId}/state -> ${r.status}: ${await r.text()}`);
+    return await r.json();
+}
+export function isSrtListenerState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return Array.isArray(v.connectedStreams) && typeof v.connectedAt === "object" && v.connectedAt !== null;
+}
+async function fetchComponentStreamRoute(studioHostPort, componentId, route) {
+    const r = await fetch(`http://localhost:${studioHostPort}/live/api/${encodeURIComponent(componentId)}/streams/${route}`, { signal: AbortSignal.timeout(5000) });
+    if (r.status === 503 || r.status === 404)
+        return null;
+    if (!r.ok)
+        throw new Error(`GET /live/api/${componentId}/streams/${route} -> ${r.status}: ${await r.text()}`);
+    return await r.json();
+}
+export async function fetchStreamMappings(studioHostPort, componentId) {
+    const data = await fetchComponentStreamRoute(studioHostPort, componentId, "mappings");
+    if (data === null)
+        return null;
+    if (Array.isArray(data))
+        return data;
+    // Studio wraps the result; tolerate either { mappings: [...] } or { streams: [...] }
+    const obj = data;
+    for (const key of ["mappings", "streams", "result"]) {
+        if (Array.isArray(obj[key]))
+            return obj[key];
+    }
+    return null;
+}
+export async function fetchStreamSources(studioHostPort, componentId) {
+    return fetchComponentStreamRoute(studioHostPort, componentId, "sources");
+}
+export async function fetchStreamUnmapped(studioHostPort, componentId) {
+    return fetchComponentStreamRoute(studioHostPort, componentId, "unmapped");
+}
+export async function fetchStreamFill(studioHostPort, componentId) {
+    return fetchComponentStreamRoute(studioHostPort, componentId, "fill");
+}
+// ── Data-flow assertion helpers ─────────────────────────────────────────────
+// Poll-until-true wrappers around fetchStreamMappings + fetchStreamUnmapped so
+// per-template tests can assert "component S is producing an output stream
+// with media=X, sourceName=Y" without restating the polling boilerplate.
+//
+// Studio's /streams/mappings exposes OUTPUT-stream metadata, not subscription
+// edges — the visible signal is `output.sourceName` (the stream's name as it
+// propagates through the graph). For an input.srt-listener that is the
+// configured sourceName; downstream encoders that preserve the stream name
+// (re-encode without rename) keep the same value.
+//
+// The timeout error includes the last-seen mappings payload so a failure tells
+// the reader what Studio was actually serving.
+import { pollUntil } from "./daemon.js";
+export async function assertStreamOutput(opts) {
+    let lastSeen = null;
+    const matches = (m) => {
+        if (m.output?.media !== opts.media)
+            return false;
+        if (opts.expectedSourceName !== undefined && m.output?.sourceName !== opts.expectedSourceName)
+            return false;
+        if (opts.renditionName !== undefined && m.output?.renditionName !== opts.renditionName)
+            return false;
+        return true;
+    };
+    try {
+        await pollUntil(async () => {
+            lastSeen = await fetchStreamMappings(opts.studioHostPort, opts.componentId);
+            if (!lastSeen)
+                return false;
+            return lastSeen.some(matches);
+        }, {
+            timeoutMs: opts.timeoutMs ?? 60_000,
+            intervalMs: opts.intervalMs ?? 1000,
+            label: opts.componentId,
+        });
+    }
+    catch (e) {
+        const filterTail = [
+            opts.expectedSourceName !== undefined ? `sourceName="${opts.expectedSourceName}"` : null,
+            opts.renditionName !== undefined ? `rendition="${opts.renditionName}"` : null,
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const tail = filterTail ? ` (${filterTail})` : "";
+        throw new Error(`assertStreamOutput: ${opts.componentId} has no ${opts.media} output${tail}. Last mappings: ${JSON.stringify(lastSeen)}`, { cause: e });
+    }
+}
+/** Polls Studio's per-component state for an SRT-listener until at least one
+ *  stream is reported as connected with a non-zero connectedAt timestamp. */
+export async function assertSrtConnected(opts) {
+    let lastSeen = null;
+    try {
+        await pollUntil(async () => {
+            lastSeen = await fetchComponentState(opts.studioHostPort, opts.componentId);
+            if (!isSrtListenerState(lastSeen))
+                return false;
+            if (lastSeen.connectedStreams.length < 1)
+                return false;
+            return Object.values(lastSeen.connectedAt).some((t) => typeof t === "number" && t > 0);
+        }, {
+            timeoutMs: opts.timeoutMs ?? 60_000,
+            intervalMs: opts.intervalMs ?? 1000,
+            label: opts.componentId,
+        });
+    }
+    catch (e) {
+        throw new Error(`assertSrtConnected: ${opts.componentId} never reported a connected stream. Last state: ${JSON.stringify(lastSeen)}`, { cause: e });
+    }
+}
+/** Fetches the multivariant m3u8 URL from state, then GETs it. Fails if the URL
+ *  never appears within the timeout OR the body does not contain a reference to
+ *  every expected rendition label. Rendition labels are the child playlists'
+ *  filenames — Studio's autoCmaf lists each rendition as a
+ *  `#EXT-X-STREAM-INF ... URI="<rendition>/norsk.m3u8"` (video) or a
+ *  `#EXT-X-MEDIA:TYPE=AUDIO ... URI="<rendition>/norsk.m3u8"` line. The caller
+ *  passes the set of expected labels; the body must reference every one. */
+export async function assertMultivariantHasRenditions(opts) {
+    let lastState = null;
+    let lastBody = null;
+    let lastFetchStatus = null;
+    const missingLabels = (body) => opts.expectedRenditionLabels.filter((label) => !body.includes(label));
+    try {
+        await pollUntil(async () => {
+            const state = (await fetchComponentState(opts.studioHostPort, opts.componentId));
+            lastState = state;
+            if (!state?.url)
+                return false;
+            try {
+                const r = await fetch(state.url, { signal: AbortSignal.timeout(5000) });
+                lastFetchStatus = r.status;
+                if (!r.ok)
+                    return false;
+                lastBody = await r.text();
+            }
+            catch (e) {
+                lastFetchStatus = e instanceof Error ? e.message : String(e);
+                return false;
+            }
+            return missingLabels(lastBody).length === 0;
+        }, {
+            timeoutMs: opts.timeoutMs ?? 90_000,
+            intervalMs: opts.intervalMs ?? 2000,
+            label: `${opts.componentId}.m3u8`,
+        });
+    }
+    catch (e) {
+        // lastBody is mutated inside the pollUntil closure, so control-flow analysis
+        // narrows it back to its `null` initializer here. Re-widen for the dump.
+        const body = lastBody;
+        const missing = body ? missingLabels(body) : opts.expectedRenditionLabels.slice();
+        throw new Error(`assertMultivariantHasRenditions: ${opts.componentId} m3u8 did not list every rendition. Missing: ${JSON.stringify(missing)}. Last state: ${JSON.stringify(lastState)}. Last fetch: ${JSON.stringify(lastFetchStatus)}. Last body: ${body ? body.slice(0, 800) : "<none>"}.`, { cause: e });
+    }
+}
+export async function assertNoUnmapped(opts) {
+    let lastSeen = null;
+    const isEmpty = (value) => {
+        if (value === null)
+            return false;
+        if (Array.isArray(value))
+            return value.length === 0;
+        if (typeof value === "object") {
+            const obj = value;
+            for (const key of ["unmapped", "streams", "result"]) {
+                if (Array.isArray(obj[key]))
+                    return obj[key].length === 0;
+            }
+        }
+        return false;
+    };
+    try {
+        await pollUntil(async () => {
+            lastSeen = await fetchStreamUnmapped(opts.studioHostPort, opts.componentId);
+            return isEmpty(lastSeen);
+        }, {
+            timeoutMs: opts.timeoutMs ?? 30_000,
+            intervalMs: opts.intervalMs ?? 1000,
+            label: opts.componentId,
+        });
+    }
+    catch (e) {
+        throw new Error(`assertNoUnmapped: ${opts.componentId} still has unmapped streams. Last payload: ${JSON.stringify(lastSeen)}`, { cause: e });
+    }
+}

package/temp-dir.d.ts

@@ -0,0 +1,6 @@
+/** Create a uniquely-named temp dir under an explicit base. */
+export declare function makeTempDirUnder(base: string, prefix: string): string;
+export declare const TEST_TMP_BASE: string;
+/** Create a uniquely-named temp dir under the consumer-local test base. */
+export declare function makeTempDir(prefix?: string): string;
+export declare function makeStoreDir(prefix?: string): string;

package/temp-dir.js

@@ -0,0 +1,51 @@
+// Temp-dir helper for tests that bind-mount a dir into a container. As a shared
+// package it cannot anchor to one repo's tree, so the base is the CONSUMER's:
+// NORSK_CTL_TEST_TMP if set, else `<cwd>/test-temp`. Every test tier runs with
+// cwd at its own package root, so each consumer's dirs land in its own repo.
+//
+// Why NOT os.tmpdir(): OrbStack does NOT forward host->guest filesystem
+// (inotify) events for /tmp / /private/tmp — only for the normally-shared macOS
+// filesystem (the repo, $HOME, etc.). oauth2-proxy's htpasswd watcher and other
+// reload paths depend on those events — under /tmp the watcher never fires and
+// every proxy login 401s, which looks exactly like a code bug. Docker Desktop
+// forwards /tmp events too, which is why that env never surfaced it.
+// Native-Linux Docker is unaffected (real kernel inotify). A repo-local
+// `test-temp/` is on the shared filesystem so events forward.
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** Create a uniquely-named temp dir under an explicit base. */
+export function makeTempDirUnder(base, prefix) {
+    mkdirSync(base, { recursive: true });
+    pruneStaleTempDirs(base);
+    return mkdtempSync(join(base, prefix));
+}
+export const TEST_TMP_BASE = process.env.NORSK_CTL_TEST_TMP ?? join(process.cwd(), "test-temp");
+// Best-effort cleanup of dirs orphaned by a crashed run whose teardown never got
+// to rm them (a repo-local base isn't OS-reclaimed like /tmp, so prune here).
+// The 1h cutoff never races a live run — no test runs near that long — so this
+// can't delete a sibling run's active dir.
+function pruneStaleTempDirs(base) {
+    try {
+        const cutoff = Date.now() - 60 * 60 * 1000;
+        for (const name of readdirSync(base)) {
+            const p = join(base, name);
+            try {
+                if (statSync(p).mtimeMs < cutoff)
+                    rmSync(p, { recursive: true, force: true });
+            }
+            catch {
+                // ignore — racing teardown of a sibling run, or a transient stat error
+            }
+        }
+    }
+    catch {
+        // base doesn't exist yet — nothing to prune
+    }
+}
+/** Create a uniquely-named temp dir under the consumer-local test base. */
+export function makeTempDir(prefix = "norsk-ctl-") {
+    return makeTempDirUnder(TEST_TMP_BASE, prefix);
+}
+export function makeStoreDir(prefix = "norsk-ctl-test-") {
+    return makeTempDir(prefix);
+}