@norskvideo/ctl-test-harness 0.1.13 → 0.1.15

package/image-surface.d.ts

@@ -0,0 +1,45 @@
+export declare const DEFAULT_TEMPLATE_TAR_ENTRIES: string[];
+type RunResult = {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+type Runner = (cmd: string, args: string[]) => RunResult;
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export interface ImageSurfaceExpect {
+    /** Always polled to 200; the trimmed body is compared when `body` is given. */
+    healthz?: {
+        body?: string;
+    };
+    manifest?: {
+        name: string;
+    };
+    /** URL path of the template tar, e.g. `/api/product-template/default/funke-live`.
+     *  `entries` default to the four template files; each must be a substring of
+     *  some entry name, so a `dashboards/` prefix matches the directory entry. */
+    templateTar?: {
+        path: string;
+        entries?: string[];
+    };
+}
+export interface ImageSurfaceResult {
+    manifest?: unknown;
+    tarEntries?: string[];
+}
+export interface AssertImageSurfaceOptions {
+    image: string;
+    /** Host port to publish on 127.0.0.1. Default: a free ephemeral port. */
+    port?: number;
+    containerPort?: number;
+    expect: ImageSurfaceExpect;
+    healthTimeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Test seams. */
+    run?: Runner;
+    fetch?: FetchLike;
+}
+/** Entry names from a ustar stream: walk the 512-byte headers, skipping each
+ *  body. Throws when the first block carries no ustar magic. */
+export declare function tarEntryNames(tar: Uint8Array): string[];
+export declare function assertImageSurface(opts: AssertImageSurfaceOptions): Promise<ImageSurfaceResult>;
+export {};

package/image-surface.js

@@ -0,0 +1,117 @@
+// The FAST half of a product's image tier: `docker run` the built control-plane
+// image loopback-published (mirroring docker-runner's `-p 127.0.0.1:<host>:4321`)
+// and check the HTTP surface `product add` probes — /healthz, /manifest.json
+// and a product-template tar. Docker only: no daemon, no licence. Catches the
+// bundling and asset-layout regressions (a flat layout silently drops
+// dashboards/ + components/ + assets/ from the tar) in seconds, before any
+// launch. The docker runner and fetch are injectable so the logic is tested
+// without a container.
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { pollUntil } from "./poll.js";
+const DEFAULT_CONTAINER_PORT = 4321;
+const DEFAULT_HEALTH_TIMEOUT_MS = 30_000;
+export const DEFAULT_TEMPLATE_TAR_ENTRIES = ["manifest.json", "compose.yml", "workflow.yml", "parameters.yaml"];
+const defaultRunner = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf-8" });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+/** Entry names from a ustar stream: walk the 512-byte headers, skipping each
+ *  body. Throws when the first block carries no ustar magic. */
+export function tarEntryNames(tar) {
+    const ascii = (from, len) => {
+        const slice = tar.subarray(from, from + len);
+        const end = slice.indexOf(0);
+        return new TextDecoder("latin1").decode(end === -1 ? slice : slice.subarray(0, end));
+    };
+    if (tar.byteLength < 512 || ascii(257, 5) !== "ustar") {
+        throw new Error("not a ustar tar: missing magic at offset 257 of the first header block");
+    }
+    const names = [];
+    let offset = 0;
+    while (offset + 512 <= tar.byteLength) {
+        const name = ascii(offset, 100);
+        if (name === "")
+            break;
+        const prefix = ascii(offset + 345, 155);
+        names.push(prefix ? `${prefix}/${name}` : name);
+        const size = Number.parseInt(ascii(offset + 124, 12).trim() || "0", 8);
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    return names;
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const address = srv.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+export async function assertImageSurface(opts) {
+    const run = opts.run ?? defaultRunner;
+    const fetchImpl = opts.fetch ?? ((url, init) => fetch(url, init));
+    if (run("docker", ["image", "inspect", opts.image]).status !== 0) {
+        throw new Error(`image ${opts.image} not found — run: bun run build:image`);
+    }
+    const port = opts.port ?? (await freePort());
+    const containerPort = opts.containerPort ?? DEFAULT_CONTAINER_PORT;
+    const started = run("docker", ["run", "-d", "--rm", "-p", `127.0.0.1:${port}:${containerPort}`, opts.image]);
+    if (started.status !== 0)
+        throw new Error(`docker run ${opts.image} failed: ${started.stderr}`);
+    const containerId = started.stdout.trim();
+    const base = `http://127.0.0.1:${port}`;
+    try {
+        let healthBody = "";
+        await pollUntil(async () => {
+            const r = await fetchImpl(`${base}/healthz`, { signal: AbortSignal.timeout(1000) });
+            if (!r.ok)
+                return false;
+            healthBody = (await r.text()).trim();
+            return true;
+        }, {
+            timeoutMs: opts.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS,
+            intervalMs: opts.pollIntervalMs ?? 500,
+            label: `container ${base}/healthz never became healthy`,
+        });
+        const expectedHealth = opts.expect.healthz?.body;
+        if (expectedHealth !== undefined && healthBody !== expectedHealth) {
+            throw new Error(`/healthz body was "${healthBody}", expected "${expectedHealth}"`);
+        }
+        const result = {};
+        if (opts.expect.manifest) {
+            const r = await fetchImpl(`${base}/manifest.json`);
+            if (r.status !== 200)
+                throw new Error(`/manifest.json returned ${r.status}`);
+            const manifest = (await r.json());
+            if (manifest.name !== opts.expect.manifest.name) {
+                throw new Error(`manifest name was ${JSON.stringify(manifest.name)}, expected "${opts.expect.manifest.name}"`);
+            }
+            result.manifest = manifest;
+        }
+        if (opts.expect.templateTar) {
+            const path = opts.expect.templateTar.path.startsWith("/")
+                ? opts.expect.templateTar.path
+                : `/${opts.expect.templateTar.path}`;
+            const r = await fetchImpl(`${base}${path}`);
+            if (r.status !== 200)
+                throw new Error(`${path} returned ${r.status}`);
+            const contentType = r.headers.get("content-type") ?? "";
+            if (!contentType.includes("x-tar"))
+                throw new Error(`${path} content-type was "${contentType}", expected x-tar`);
+            const entries = tarEntryNames(new Uint8Array(await r.arrayBuffer()));
+            const missing = (opts.expect.templateTar.entries ?? DEFAULT_TEMPLATE_TAR_ENTRIES).filter((wanted) => !entries.some((e) => e.includes(wanted)));
+            if (missing.length) {
+                throw new Error(`${path} tar is missing ${missing.join(", ")}; entries: ${entries.join(", ")}`);
+            }
+            result.tarEntries = entries;
+        }
+        return result;
+    }
+    finally {
+        run("docker", ["rm", "-f", containerId]);
+    }
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export type { AssertImageSurfaceOptions, ImageSurfaceExpect, ImageSurfaceResult } from "./image-surface.js";
+export { assertImageSurface, DEFAULT_TEMPLATE_TAR_ENTRIES, tarEntryNames } from "./image-surface.js";
+export { pollUntil } from "./poll.js";
+export { makeStoreDir, makeTempDir, makeTempDirUnder, TEST_TMP_BASE } from "./temp-dir.js";

package/index.js

@@ -0,0 +1,6 @@
+// Package root: the runtime-agnostic helpers every tier reaches for, without
+// going through `./daemon` (which drags in the CLI spawner). The subpath
+// exports stay the primary surface; this is the short way to the primitives.
+export { assertImageSurface, DEFAULT_TEMPLATE_TAR_ENTRIES, tarEntryNames } from "./image-surface.js";
+export { pollUntil } from "./poll.js";
+export { makeStoreDir, makeTempDir, makeTempDirUnder, TEST_TMP_BASE } from "./temp-dir.js";

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
     "./daemon": {
       "types": "./daemon.d.ts",
       "default": "./daemon.js"
     },
+    "./image-surface": {
+      "types": "./image-surface.d.ts",
+      "default": "./image-surface.js"
+    },
     "./launch": {
       "types": "./launch.d.ts",
       "default": "./launch.js"
@@ -30,8 +38,14 @@
     "./container-net": {
       "types": "./container-net.d.ts",
       "default": "./container-net.js"
+    },
+    "./smoke": {
+      "types": "./smoke.d.ts",
+      "default": "./smoke.js"
     }
   },
+  "main": "./index.js",
+  "types": "./index.d.ts",
   "dependencies": {
     "@norskvideo/ctl-sdk": "^0.1.0"
   },

package/smoke.d.ts

@@ -0,0 +1,147 @@
+import { ensureRunnerOnNetwork, type StudioTarget } from "./container-net.js";
+import { type DaemonProcess, type StartDaemonOptions } from "./daemon.js";
+import { type BaseHarnessPorts } from "./harness-config.js";
+import { type SourceHandle, type SrtPumpTarget } from "./source-pump.js";
+import { type ComponentsResponse, type StreamMappingEntry } from "./studio-state.js";
+export type SmokeRegistration = {
+    image: string;
+} | {
+    /** The dev backend's URL; a function receives the banded backend port. */
+    devUrl: string | ((backendPort: number) => string);
+    /** Start the dev backend on the banded port; awaited before `product add`. */
+    start(backendPort: number): Promise<void>;
+};
+export type SmokeTemplate = {
+    name: string;
+} | {
+    /** Name for the built template (`template build <build> --product … --input …`). */
+    build: string;
+    input: Record<string, unknown>;
+};
+export interface CliResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface SmokeContext {
+    daemonPort: number;
+    instanceId: string;
+    storeDir: string;
+    /** Resolved via netReachMode(): published port, or `<id>-studio-1:8000` in direct mode. */
+    studio: StudioTarget;
+    cli(argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }): Promise<CliResult>;
+    fetchStudio(path: string): Promise<Response>;
+}
+export type SmokeObservation = {
+    kind: "components";
+    ids: string[];
+} | {
+    kind: "srt-connected";
+    componentId: string;
+} | {
+    kind: "stream-output";
+    componentId: string;
+    media: "video" | "audio" | "playlist";
+    renditionName?: string;
+} | {
+    kind: "multivariant";
+    componentId: string;
+    expectedRenditionLabels: string[];
+    /** mediaDirectUrl for proxy-less harnesses; default applyTestHost. */
+    resolveFetchUrl?: (advertised: string) => string;
+} | {
+    kind: "http";
+    url: (ctx: SmokeContext) => string;
+    status?: number;
+    bodyIncludes?: string;
+} | {
+    kind: "custom";
+    label: string;
+    satisfied: (ctx: SmokeContext) => Promise<boolean>;
+};
+export interface SmokeSpec {
+    product: {
+        /** Manifest name, e.g. "norsk-probe". The registration must report it. */
+        name: string;
+        /** Chosen by the caller from the environment: SMOKE_IMAGE_TAG set -> image
+         *  (main / candidate / nightly); unset -> devUrl (PRs, local loop). */
+        register: SmokeRegistration;
+        /** Default: requireLicenseFile(). */
+        licenseFile?: string;
+    };
+    template: SmokeTemplate;
+    /** Extra `--param NAME=value`. INSTANCE_NAME is always passed; STUDIO_HOST_PORT
+     *  when the template declares it (else the port is pinned with --host-ports). */
+    params?: string[];
+    hardware?: "nvidia" | "none";
+    networkMode?: "docker";
+    /** `port` is the container-internal listener port. May be empty. */
+    sources: SrtPumpTarget[];
+    /** Evaluated in order; see the phase rule above. */
+    observe: SmokeObservation[];
+    timeouts?: {
+        healthyMs?: number;
+        observeMs?: number;
+        clearedMs?: number;
+    };
+    /** Override the banded ports (see smokePorts). */
+    ports?: Partial<SmokePorts>;
+}
+/** What the observation kinds read. Injected so the phase rule is tested
+ *  without Studio; defaults are studio-state's fetchers. */
+export interface SmokeReaders {
+    components(studio: StudioTarget): Promise<ComponentsResponse | null>;
+    componentState(studio: StudioTarget, componentId: string): Promise<unknown | null>;
+    streamMappings(studio: StudioTarget, componentId: string): Promise<StreamMappingEntry[] | null>;
+    fetch(url: string): Promise<Response>;
+}
+export interface SmokeDeps {
+    licenseFile(): string;
+    storeDir(slug: string): string;
+    writeFile(path: string, contents: string): void;
+    startDaemon(storeDir: string, options: StartDaemonOptions): {
+        daemon: DaemonProcess;
+        ready: Promise<void>;
+    };
+    cli(storeDir: string, argv: string[]): Promise<CliResult>;
+    startSources(opts: {
+        daemonPort: number;
+        instanceId: string;
+        targets: readonly SrtPumpTarget[];
+        timeoutMs?: number;
+    }): Promise<SourceHandle[]>;
+    stopSources(handles: SourceHandle[]): Promise<void>;
+    readers: SmokeReaders;
+    cleanup(opts: {
+        deleteInstance: (id: string) => Promise<unknown>;
+        stopDaemon: () => Promise<unknown>;
+        instances: string[];
+        daemon: DaemonProcess | null;
+        storeDir: string;
+        containers: string[];
+    }): Promise<void>;
+    /** Docker leaves root-owned bind-mount targets under the store; a non-root
+     *  runner cannot rm them, so they go from a throwaway root container. */
+    nukeStoreAsRoot(storeDir: string): void;
+    ensureNetwork(): ReturnType<typeof ensureRunnerOnNetwork>;
+    supportsNoPublish(): Promise<boolean>;
+    containerUser(): string | undefined;
+    log(line: string): void;
+}
+/** Per-slug port band, above the product integration harnesses' own bands:
+ *  daemon, dev backend, published Studio port and an instance base, twenty
+ *  apart per slug. */
+export interface SmokePorts extends BaseHarnessPorts {
+    /** The daemon's oauth2 proxy; banded so co-located runs never meet on :9443. */
+    proxyPort: number;
+}
+export declare function smokePorts(slug: string, overrides?: Partial<SmokePorts>): SmokePorts;
+export declare const defaultSmokeDeps: SmokeDeps;
+/** Whether an observation depends on a source being pumped. Structural ones
+ *  run the satisfied phase only. */
+export declare function sourceDependent(o: SmokeObservation): boolean;
+/** One sample of an observation — the predicate the three phases poll. */
+export declare function observationSatisfied(o: SmokeObservation, ctx: SmokeContext, readers: SmokeReaders): Promise<boolean>;
+export declare function runProductSmoke(slug: string, spec: SmokeSpec, deps?: SmokeDeps): Promise<void>;

package/smoke.js

@@ -0,0 +1,335 @@
+// The `smoke` tier (fleet review 04b s7.2, 04a s4.3): one parametrised journey
+// every product satisfies — launch from the stored template, accept the source
+// the manifest advertises, produce the observable it advertises. A product's
+// tests/smoke.spec.ts is ten to twenty lines of SmokeSpec; the runner owns the
+// daemon, the registration, the launch, the source pump, the three-phase
+// evaluation and the teardown.
+//
+// The three phases are the incident's lesson (04a s0: Studio reported healthy
+// while nothing listened). Every source-dependent observation must be FALSE
+// before any source exists (a latched or stubbed observable cannot pass), TRUE
+// while the pump runs, and FALSE again after stopAll (the observable is
+// watching, not latched). `components` is structural — the graph exists with
+// or without a source — so it runs the satisfied phase only.
+//
+// Every side effect sits behind SmokeDeps so the sequencing is unit-tested with
+// fakes; the defaults wire to the real harness (daemon, source-pump,
+// studio-state, container-net). Argv, not Command: @norskvideo/ctl-commands is
+// not a dependency of this package (daemon.ts's cleanupDaemon has the same
+// rule); a product wanting typed commands bridges with toArgv in its own spec.
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "./container-net.js";
+import { cleanupDaemon, requireLicenseFile, runCli, startDaemon, } from "./daemon.js";
+import { hashSlot } from "./harness-config.js";
+import { ctlSupportsNoPublish, runnerContainerUser } from "./launch.js";
+import { pollUntil } from "./poll.js";
+import { startSrtSources } from "./source-pump.js";
+import { applyTestHost, fetchComponentState, fetchComponents, fetchStreamMappings, isSrtListenerState, } from "./studio-state.js";
+import { makeStoreDir } from "./temp-dir.js";
+const SMOKE_PORT_BASE = 33000;
+const SMOKE_BAND_WIDTH = 20;
+const SMOKE_BANDS = 50;
+const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
+const NUKE_IMAGE = "alpine:3";
+export function smokePorts(slug, overrides = {}) {
+    const daemonPort = SMOKE_PORT_BASE + hashSlot(`smoke:${slug}`, SMOKE_BANDS) * SMOKE_BAND_WIDTH;
+    return {
+        daemonPort,
+        backendPort: daemonPort + 1,
+        studioHostPort: daemonPort + 2,
+        proxyPort: daemonPort + 3,
+        instancePortBase: daemonPort + 10,
+        ...overrides,
+    };
+}
+export const defaultSmokeDeps = {
+    licenseFile: () => requireLicenseFile({ missing: "throw" }),
+    storeDir: (slug) => makeStoreDir(`norsk-smoke-${slug}-`),
+    writeFile: (path, contents) => writeFileSync(path, contents),
+    startDaemon,
+    cli: (storeDir, argv) => runCli(storeDir, ...argv),
+    startSources: startSrtSources,
+    stopSources: async (handles) => {
+        for (const h of handles)
+            await h.stop();
+    },
+    readers: {
+        components: fetchComponents,
+        componentState: fetchComponentState,
+        streamMappings: fetchStreamMappings,
+        fetch: (url) => fetch(url, { signal: AbortSignal.timeout(5000) }),
+    },
+    cleanup: (opts) => cleanupDaemon({ ...opts, stopProxy: async () => { }, proxy: false }),
+    nukeStoreAsRoot: (storeDir) => {
+        spawnSync("docker", [
+            "run",
+            "--rm",
+            "--user",
+            "0:0",
+            "-v",
+            `${dirname(storeDir)}:/base`,
+            "--entrypoint",
+            "sh",
+            NUKE_IMAGE,
+            "-c",
+            `rm -rf /base/${basename(storeDir)}`,
+        ]);
+    },
+    ensureNetwork: () => ensureRunnerOnNetwork(),
+    supportsNoPublish: ctlSupportsNoPublish,
+    containerUser: runnerContainerUser,
+    log: (line) => console.log(`[smoke] ${line}`),
+};
+function describeObservation(o) {
+    switch (o.kind) {
+        case "components":
+            return `components ${o.ids.join(",")}`;
+        case "srt-connected":
+            return `srt-connected ${o.componentId}`;
+        case "stream-output":
+            return `stream-output ${o.componentId} ${o.media}${o.renditionName ? ` ${o.renditionName}` : ""}`;
+        case "multivariant":
+            return `multivariant ${o.componentId} [${o.expectedRenditionLabels.join(",")}]`;
+        case "http":
+            return "http";
+        case "custom":
+            return `custom ${o.label}`;
+    }
+}
+/** Whether an observation depends on a source being pumped. Structural ones
+ *  run the satisfied phase only. */
+export function sourceDependent(o) {
+    return o.kind !== "components";
+}
+/** One sample of an observation — the predicate the three phases poll. */
+export async function observationSatisfied(o, ctx, readers) {
+    switch (o.kind) {
+        case "components": {
+            const r = await readers.components(ctx.studio);
+            if (!r)
+                return false;
+            const ids = new Set(r.components.map((c) => c.componentId));
+            return o.ids.every((id) => ids.has(id));
+        }
+        case "srt-connected": {
+            const state = await readers.componentState(ctx.studio, o.componentId);
+            if (!isSrtListenerState(state) || state.connectedStreams.length < 1)
+                return false;
+            return Object.values(state.connectedAt).some((t) => typeof t === "number" && t > 0);
+        }
+        case "stream-output": {
+            const mappings = await readers.streamMappings(ctx.studio, o.componentId);
+            return (mappings ?? []).some((m) => m.output?.media === o.media && (o.renditionName === undefined || m.output?.renditionName === o.renditionName));
+        }
+        case "multivariant": {
+            const state = (await readers.componentState(ctx.studio, o.componentId));
+            if (!state?.url)
+                return false;
+            const r = await readers.fetch((o.resolveFetchUrl ?? applyTestHost)(state.url));
+            if (!r.ok)
+                return false;
+            const body = await r.text();
+            return o.expectedRenditionLabels.every((label) => body.includes(label));
+        }
+        case "http": {
+            const r = await readers.fetch(o.url(ctx));
+            if (r.status !== (o.status ?? 200))
+                return false;
+            if (o.bodyIncludes === undefined)
+                return true;
+            return (await r.text()).includes(o.bodyIncludes);
+        }
+        case "custom":
+            return o.satisfied(ctx);
+    }
+}
+function parseJson(r, what) {
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        throw new Error(`${what}: not JSON: ${r.stdout.slice(0, 200)}`);
+    }
+}
+export async function runProductSmoke(slug, spec, deps = defaultSmokeDeps) {
+    const ports = smokePorts(slug, spec.ports);
+    const storeDir = deps.storeDir(slug);
+    const instanceId = `smoke-${slug}`;
+    const timeouts = {
+        healthyMs: spec.timeouts?.healthyMs ?? 180_000,
+        observeMs: spec.timeouts?.observeMs ?? 120_000,
+        clearedMs: spec.timeouts?.clearedMs ?? 60_000,
+    };
+    const mode = netReachMode();
+    const studio = { instanceId, studioHostPort: ports.studioHostPort };
+    const cli = async (argv, opts = {}) => {
+        const full = ["--port", String(ports.daemonPort), ...argv, ...(opts.output ? ["-o", opts.output] : [])];
+        return deps.cli(storeDir, full);
+    };
+    const cliOk = async (argv, opts = {}) => {
+        const r = await cli(argv, opts);
+        if (r.exitCode !== 0) {
+            throw new Error(`norsk-ctl ${argv.join(" ")} failed (exit ${r.exitCode}):\n${r.stderr || r.stdout}`);
+        }
+        return r;
+    };
+    const ctx = {
+        daemonPort: ports.daemonPort,
+        instanceId,
+        storeDir,
+        studio,
+        cli,
+        fetchStudio: (path) => deps.readers.fetch(`${studioBaseFrom(studio, process.env.NORSK_TEST_HOST ?? "localhost", mode)}${path}`),
+    };
+    let daemon = null;
+    let launched = false;
+    let handles = [];
+    try {
+        // The same zero point as the guides: `init` on a virgin store, not a seeded
+        // config.yaml. No http redirect (port 80 needs root) and a banded proxy port
+        // (the default :9443 would meet a co-located integration run).
+        await cliOk([
+            "init",
+            "--network-mode",
+            spec.networkMode ?? "docker",
+            "--working-directory",
+            join(storeDir, "norsk-runtime"),
+            "--proxy-port",
+            String(ports.proxyPort),
+            "--no-http-redirect",
+            "--no-start-server",
+        ]);
+        const started = deps.startDaemon(storeDir, { port: ports.daemonPort, seedConfig: false });
+        daemon = started.daemon;
+        await started.ready;
+        if (mode === "direct" && deps.ensureNetwork() === "failed") {
+            throw new Error("could not join the runner to norsk-net for direct reach");
+        }
+        // Register.
+        const licenseFile = spec.product.licenseFile ?? deps.licenseFile();
+        let addArgv;
+        if ("image" in spec.product.register) {
+            addArgv = ["product", "add", "--image", spec.product.register.image];
+        }
+        else {
+            const reg = spec.product.register;
+            await reg.start(ports.backendPort);
+            const url = typeof reg.devUrl === "function" ? reg.devUrl(ports.backendPort) : reg.devUrl;
+            addArgv = ["product", "add", "--dev-url", url];
+        }
+        const added = parseJson(await cliOk([...addArgv, "--license-file", licenseFile], { output: "json" }), "product add");
+        if (added.name !== spec.product.name) {
+            throw new Error(`product add registered '${added.name}', expected '${spec.product.name}'`);
+        }
+        // Template.
+        let templateName;
+        if ("name" in spec.template) {
+            templateName = spec.template.name;
+        }
+        else {
+            const inputPath = join(storeDir, `smoke-${spec.template.build}-input.json`);
+            deps.writeFile(inputPath, JSON.stringify(spec.template.input));
+            await cliOk([
+                "template",
+                "build",
+                spec.template.build,
+                "--product",
+                spec.product.name,
+                "--input",
+                inputPath,
+                "--replace",
+            ]);
+            templateName = spec.template.build;
+        }
+        // Launch. The published Studio port is a template parameter where the
+        // template declares one (the generator's shape); otherwise it is pinned
+        // with a host-port binding on the studio service. In direct mode with an
+        // internal-only launch the target dials the service name instead.
+        const shown = await cli(["template", "show", templateName], { output: "json" });
+        const declared = new Set(shown.exitCode === 0
+            ? (parseJson(shown, "template show").parameters ?? []).map((p) => p.name)
+            : []);
+        const params = [`INSTANCE_NAME=${instanceId}`, ...(spec.params ?? [])];
+        const launchArgv = ["instance", "launch-template", instanceId, "--template", templateName];
+        const internalOnly = mode === "direct" && (await deps.supportsNoPublish());
+        if (declared.has(STUDIO_HOST_PORT_PARAM))
+            params.push(`${STUDIO_HOST_PORT_PARAM}=${ports.studioHostPort}`);
+        else if (!internalOnly)
+            launchArgv.push("--host-ports", `${ports.studioHostPort}:${STUDIO_INTERNAL_PORT}@studio`);
+        for (const p of params)
+            launchArgv.push("--param", p);
+        if (spec.hardware)
+            launchArgv.push("--hardware", spec.hardware);
+        if (spec.networkMode)
+            launchArgv.push("--network-mode", spec.networkMode);
+        const user = deps.containerUser();
+        if (user)
+            launchArgv.push("--container-user", user);
+        if (internalOnly)
+            launchArgv.push("--internal-only");
+        launched = true;
+        await cliOk(launchArgv);
+        await pollUntil(async () => {
+            const r = await cli(["instance", "list"], { output: "json" });
+            if (r.exitCode !== 0)
+                return false;
+            const inst = parseJson(r, "instance list").instances?.find((i) => i.id === instanceId);
+            return inst?.status === "running" || inst?.status === "healthy";
+        }, { timeoutMs: timeouts.healthyMs, intervalMs: 1000, label: `instance ${instanceId} never reported running` });
+        // Phases.
+        const vacuous = spec.sources.length === 0;
+        if (vacuous) {
+            deps.log(`${slug}: no sources declared — the not-yet and cleared phases are vacuous; observations run once`);
+        }
+        const phased = spec.observe.filter((o) => sourceDependent(o) && !vacuous);
+        for (const o of phased) {
+            if (await observationSatisfied(o, ctx, deps.readers)) {
+                throw new Error(`${describeObservation(o)} was already satisfied before any source existed — a latched or stubbed observable cannot prove ingest`);
+            }
+        }
+        deps.log(`${slug}: not-yet phase passed for ${phased.length} observation(s)`);
+        if (!vacuous) {
+            handles = await deps.startSources({
+                daemonPort: ports.daemonPort,
+                instanceId,
+                targets: spec.sources,
+                timeoutMs: timeouts.observeMs,
+            });
+        }
+        for (const o of spec.observe) {
+            await pollUntil(() => observationSatisfied(o, ctx, deps.readers), {
+                timeoutMs: timeouts.observeMs,
+                intervalMs: 1000,
+                label: `${describeObservation(o)} never satisfied${vacuous ? "" : " while the sources pumped"}`,
+            });
+        }
+        deps.log(`${slug}: satisfied phase passed for ${spec.observe.length} observation(s)`);
+        if (!vacuous) {
+            await deps.stopSources(handles);
+            handles = [];
+            for (const o of phased) {
+                await pollUntil(async () => !(await observationSatisfied(o, ctx, deps.readers)), {
+                    timeoutMs: timeouts.clearedMs,
+                    intervalMs: 1000,
+                    label: `${describeObservation(o)} still satisfied after stopAll — the observable is latched, not watching`,
+                });
+            }
+            deps.log(`${slug}: cleared phase passed for ${phased.length} observation(s)`);
+        }
+    }
+    finally {
+        if (handles.length)
+            await deps.stopSources(handles).catch(() => { });
+        await deps.cleanup({
+            deleteInstance: (id) => cli(["instance", "delete", id, "--purge"]),
+            stopDaemon: () => cli(["shutdown", "--daemon-only"]),
+            instances: launched ? [instanceId] : [],
+            daemon,
+            storeDir,
+            containers: [`norsk-inst-${instanceId}-studio`, `norsk-inst-${instanceId}-media`],
+        });
+        deps.nukeStoreAsRoot(storeDir);
+    }
+}

package/source-pump.d.ts

@@ -2,18 +2,51 @@ export interface SourceHandle {
     name: string;
     stop(): Promise<void>;
 }
-export declare function startCameraSource(opts: {
+/** The daemon's generated-source kinds (`generate` on POST /api/sources). */
+export type GeneratedPattern = "bars" | "testsrc";
+/** An asset the daemon can stream without a file on the harness host. */
+export type BuiltinSourceAsset = {
+    preset: string;
+} | {
+    generate: GeneratedPattern;
+};
+/** What a source streams. `mediaFile` is a path on the daemon's host; because
+ *  a harness cannot assume the file is checked out (a customer capture, a
+ *  large fixture), the fallback is REQUIRED and is used when the file is
+ *  absent, so the spec runs anywhere and only the picture differs. */
+export type SourceAsset = BuiltinSourceAsset | {
+    mediaFile: string;
+    fallback: BuiltinSourceAsset;
+};
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Mirrors the daemon's default source name (shared/src/source-name.ts) so a
+ *  caller can predict the identity it will poll and stop by. The harness
+ *  always SENDS the name it derived, so the two cannot drift. */
+export declare function defaultSourceName(asset: SourceAsset): string;
+export interface StartCameraSourceOptions {
     daemonPort: number;
     instanceId: string;
+    /** Today's shorthand for `asset: { preset }`. Mutually exclusive with `asset`. */
     preset?: string;
+    asset?: SourceAsset;
     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. */
+     *  Default: the preset / pattern name, or the media file's cleaned stem
+     *  (kept even when the fallback is used, so the handle is stable). Required
+     *  when the same asset must run multiple times within an instance. */
     name?: string;
+    /** Sent as `x-norsk-proxy`; needed when the daemon sits behind the oauth2
+     *  proxy, which 307s `/api/*` without it. The daemon writes it to
+     *  `<stateDir>/proxy-secret` (`<storeDir>/proxy-secret` under
+     *  NORSK_CTL_STORE_DIR). */
+    proxySecret?: string;
     timeoutMs?: number;
-}): Promise<SourceHandle>;
+    /** Test seams. */
+    fetch?: FetchLike;
+    fileExists?: (path: string) => boolean;
+}
+export declare function startCameraSource(opts: StartCameraSourceOptions): Promise<SourceHandle>;
 export interface SrtPumpTarget {
     port: number;
     /** Source identity within the instance. Must be unique per instance. */
@@ -22,13 +55,17 @@ export interface SrtPumpTarget {
      *  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. */
+     *  when you want visually distinct streams. Shorthand for `asset`. */
     preset?: string;
+    asset?: SourceAsset;
 }
 export declare function startSrtSources(opts: {
     daemonPort: number;
     instanceId: string;
     targets: readonly SrtPumpTarget[];
+    proxySecret?: string;
     timeoutMs?: number;
+    fetch?: FetchLike;
+    fileExists?: (path: string) => boolean;
 }): Promise<SourceHandle[]>;
 export declare function stopAll(handles: readonly SourceHandle[]): Promise<void>;

package/source-pump.js

@@ -1,26 +1,61 @@
 // 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.
+// Spawns a daemon-managed `linuxserver/ffmpeg` sidecar that loops an asset
+// (a preset MP4/TS, a generated pattern, or a host media file) 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
+// multiple sources on the same asset can co-exist within one instance. See
 // `startSrtSources` for the multi-port fan-out helper that uses it.
-import { pollUntil } from "./daemon.js";
+import { existsSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { pollUntil } from "./poll.js";
+/** Mirrors the daemon's default source name (shared/src/source-name.ts) so a
+ *  caller can predict the identity it will poll and stop by. The harness
+ *  always SENDS the name it derived, so the two cannot drift. */
+export function defaultSourceName(asset) {
+    if ("preset" in asset)
+        return asset.preset;
+    if ("generate" in asset)
+        return asset.generate;
+    const stem = basename(asset.mediaFile, extname(asset.mediaFile));
+    const cleaned = stem
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "source";
+}
+function assetFields(asset, fileExists) {
+    if ("mediaFile" in asset) {
+        if (fileExists(asset.mediaFile))
+            return { mediaFile: asset.mediaFile };
+        return assetFields(asset.fallback, fileExists);
+    }
+    return { ...asset };
+}
 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.preset !== undefined && opts.asset !== undefined) {
+        throw new Error("startCameraSource: pass either `preset` or `asset`, not both");
+    }
+    const asset = opts.asset ?? { preset: opts.preset ?? "camera1" };
+    const name = opts.name ?? defaultSourceName(asset);
+    const fetchImpl = opts.fetch ?? ((url, init) => fetch(url, init));
+    const headers = opts.proxySecret ? { "x-norsk-proxy": opts.proxySecret } : {};
+    const base = `http://localhost:${opts.daemonPort}`;
+    const body = {
+        instanceId: opts.instanceId,
+        ...assetFields(asset, opts.fileExists ?? existsSync),
+        port: opts.port,
+        name,
+    };
     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`, {
+    const startRes = await fetchImpl(`${base}/api/sources`, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: { ...headers, "Content-Type": "application/json" },
         body: JSON.stringify(body),
         signal: AbortSignal.timeout(10_000),
     });
@@ -28,7 +63,10 @@ export async function startCameraSource(opts) {
         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) });
+        const r = await fetchImpl(`${base}/api/sources?instanceId=${encodeURIComponent(opts.instanceId)}`, {
+            headers,
+            signal: AbortSignal.timeout(5000),
+        });
         if (!r.ok)
             return false;
         // GET /api/sources returns a bare array of SampleSource — not { sources: [...] }.
@@ -43,7 +81,11 @@ export async function startCameraSource(opts) {
     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(() => { });
+            await fetchImpl(`${base}/api/sources/${encodeURIComponent(opts.instanceId)}/${encodeURIComponent(name)}`, {
+                method: "DELETE",
+                headers,
+                signal: AbortSignal.timeout(10_000),
+            }).catch(() => { });
         },
     };
 }
@@ -56,8 +98,12 @@ export async function startSrtSources(opts) {
             name: target.name,
             port: target.port,
             ...(target.preset !== undefined ? { preset: target.preset } : {}),
+            ...(target.asset !== undefined ? { asset: target.asset } : {}),
             ...(target.streamId !== undefined ? { streamId: target.streamId } : {}),
+            ...(opts.proxySecret !== undefined ? { proxySecret: opts.proxySecret } : {}),
             ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+            ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
+            ...(opts.fileExists !== undefined ? { fileExists: opts.fileExists } : {}),
         });
         handles.push(handle);
     }