@norskvideo/ctl-test-harness 0.1.24 → 0.1.25

package/demo/cli.js

@@ -25,8 +25,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // under bun only: the spec is TypeScript and so is every product's dev shell.
 import { resolve } from "node:path";
 import { devLoopDown, runDevLoop } from "./dev-loop.js";
+import { runDemo } from "./harness.js";
 import { demoPaneList, devLoopPaneList, launchLayout, renderLayout, standaloneDirs, } from "./panes.js";
-import { demoDown, demoPorts, demoSlug, runDemo, runExportCheck, } from "./run.js";
+import { demoDown, demoPorts, demoSlug, runExportCheck } from "./run.js";
 const USAGE = `usage: demo <up|check|down|spec|ui> [--mode dev|image|standalone] [--daemon private|reuse] [--export-only] [--json]
             [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]
        demo dev-loop <up|refresh|down|ui> [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]

package/demo/harness.d.ts

@@ -0,0 +1,108 @@
+import { type StudioTarget } from "../container-net.js";
+import type { SourceHandle } from "../source-pump.js";
+import { type CliStep, type DemoDeps, type DemoPorts, type DemoRunOptions, type DemoRunResult, DemoSession, type DemoTimeouts, type IngestPortRow } from "./run.js";
+import type { DemoContext, DemoDaemonPolicy, DemoIngest, DemoMode, DemoReady, DemoSpec, DemoTemplate } from "./spec.js";
+export interface ProductHarnessOptions {
+    /** The product repo root: dev command cwd, relative inputs, manifest.seed.json. */
+    cwd: string;
+    /** Default: the product name without its `norsk-` prefix. */
+    slug?: string;
+    /** Default: the spec's `mode`, else `dev`. */
+    mode?: DemoMode;
+    /** Default private. */
+    daemon?: DemoDaemonPolicy;
+    daemonPort?: number;
+    timeouts?: DemoTimeouts;
+    publicHost?: string;
+    deps?: DemoDeps;
+    /** What the spec's hooks see as `ctx.action`: `check` (the default — a
+     *  fixture, CI) or `up` (the held demo, where `launch.workingDirectory` applies). */
+    action?: "up" | "check";
+    /** Private daemon: init the proxy with a basic-auth user (a browser signs
+     *  in) instead of `--proxy-auth none`. */
+    proxy?: {
+        user: string;
+        password: string;
+    };
+    /** Private daemon: extra environment for the daemon process (a doc guide
+     *  names its own proxy container so a run cannot adopt the developer's). */
+    daemonEnv?: Record<string, string>;
+    /** Containers teardown must also wait out — an overridden proxy's pair. */
+    extraContainers?: string[];
+}
+export interface LaunchOverrides {
+    /** Default `demo-<slug>`. */
+    instanceId?: string;
+    /** Default: the spec's template (the product's first default when it names none). */
+    template?: DemoTemplate;
+    /** Merged over the spec's `launch.params`. */
+    params?: Record<string, string | number>;
+    hardware?: "nvidia" | "none";
+    workingDirectory?: string;
+}
+/** An instance `launch()` brought to running: its resolved ports and URLs,
+ *  and the spec's sources and gates, on demand. */
+export interface LaunchedInstance {
+    readonly instanceId: string;
+    readonly templateName: string;
+    readonly studioHostPort: number;
+    readonly ctx: DemoContext;
+    /** The daemon's `ingestPorts` rows for this instance (`instance describe`). */
+    readonly ingestPorts: IngestPortRow[];
+    /** A port the way the spec names one: resolved from the instance, never restated. */
+    ingestPort(ingest: DemoIngest): number;
+    /** The reach studio-state's fetchers take. */
+    studioTarget(): StudioTarget;
+    /** Pump the spec's sources (all, or the named subset) at this instance.
+     *  The handles are stopped at teardown; stop one early via its `stop()`. */
+    startSources(names?: readonly string[]): Promise<SourceHandle[]>;
+    /** Poll the spec's `ready` gates (or the given ones) in order. */
+    awaitReady(gates?: readonly DemoReady[]): Promise<void>;
+}
+export declare class ProductHarness {
+    readonly spec: DemoSpec;
+    readonly slug: string;
+    readonly session: DemoSession;
+    readonly action: "up" | "check";
+    /** Every instance `launch()` brought to running, in order. */
+    readonly instances: LaunchedInstance[];
+    /** Every instance id a launch named, running or not: what teardown deletes. */
+    private readonly launchedIds;
+    private handles;
+    private readonly deps;
+    constructor(spec: DemoSpec, opts: ProductHarnessOptions);
+    /** Every CLI step this fixture ran, as a reader would type it, with its output. */
+    get transcript(): readonly CliStep[];
+    get ports(): DemoPorts;
+    get storeDir(): string;
+    get mode(): DemoMode;
+    get policy(): DemoDaemonPolicy;
+    /** The demo's instance id: what `launch()` uses when not told otherwise. */
+    get defaultInstanceId(): string;
+    cli: (argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }) => Promise<import("./run.js").CliResult>;
+    cliOk: (argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }) => Promise<import("./run.js").CliResult>;
+    /** The daemon (private on its band, or the developer's), the dev backend
+     *  on the driver's port, and the registration. Nothing is launched. */
+    setup(): Promise<void>;
+    /** Store a template now — built from an input, or checked against what the
+     *  product publishes — for a launch by `{ name }` later. What a product
+     *  harness's buildAndImport does before its launchScenario. */
+    storeTemplate(template: DemoTemplate): Promise<string>;
+    /** Store and launch a template, wait until the instance reports running,
+     *  and resolve what a test needs from it. Extras start and `beforeLaunch`
+     *  runs before each launch, exactly as the demo does for its one. */
+    launch(overrides?: LaunchOverrides): Promise<LaunchedInstance>;
+    /** The demo journey on the fixture: launch, pump, gate, `after`, `open`. */
+    run(): Promise<DemoRunResult>;
+    /** Sources, every instance a launch named, then — private only — the
+     *  daemon, the dev backend and the store. Throws if the store outlives the
+     *  root-container nuke: a leak a runner would otherwise accumulate. */
+    teardown(): Promise<void>;
+    private nextStudioHostPort;
+}
+/** The demo: a ProductHarness set up, run, held (`up`) or not (`check`), torn down. */
+export declare function runDemo(spec: DemoSpec, opts: DemoRunOptions, deps?: DemoDeps): Promise<DemoRunResult>;

package/demo/harness.js

@@ -0,0 +1,386 @@
+// ProductHarness (05-demo s6 last paragraph, s7 step 6): the integration
+// fixture built from the demo spec. A product's `harness.ts` used to hand-roll
+// the same skeleton the demo driver runs — store, daemon, dev backend,
+// registration, template, launch, wait-for-running, teardown — five times
+// across the fleet, each copy drifting (container naming, root-owned-store
+// cleanup, ports). Here the skeleton is one class the spec constructs:
+// `setup()` brings the daemon and the registration up, `launch()` puts an
+// instance on it (the spec's template, or an override — a matrix test builds
+// its own), `run()` is the demo journey on top of that, and `runDemo` is
+// `setup → run → hold → teardown` — so the demo and the test fixture cannot
+// rot apart: they are the same code path.
+//
+// What stays in a product's harness.ts: its probes (a probe-api status, a
+// program SRT listener, an HLS ladder), its config-schema port remap for a
+// built template, and whatever sidecar its output points at.
+import { netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom } from "../container-net.js";
+import { pollUntil } from "../poll.js";
+import { DemoGateFailure } from "./gates.js";
+import { DemoSession, defaultDemoDeps, demoSlug, expandHome, resolveIngestPort, } from "./run.js";
+const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
+/** Launches after the first take studio host ports above the proxy's, inside
+ *  the band and below `instancePortBase`: six of them. */
+const EXTRA_STUDIO_PORTS = 6;
+export class ProductHarness {
+    spec;
+    slug;
+    session;
+    action;
+    /** Every instance `launch()` brought to running, in order. */
+    instances = [];
+    /** Every instance id a launch named, running or not: what teardown deletes. */
+    launchedIds = [];
+    handles = [];
+    deps;
+    constructor(spec, opts) {
+        const mode = opts.mode ?? spec.mode ?? "dev";
+        if (mode === "image" && !spec.image) {
+            throw new Error(`--mode image needs the spec's \`image\` (the built product image) — ${spec.product} declares none`);
+        }
+        this.spec = spec;
+        this.slug = opts.slug ?? demoSlug(spec.product);
+        this.action = opts.action ?? "check";
+        this.deps = opts.deps ?? defaultDemoDeps(opts.cwd);
+        this.session = new DemoSession(spec, this.slug, opts.cwd, this.deps, {
+            mode,
+            daemon: opts.daemon ?? "private",
+            ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
+            ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+            ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
+            ...(opts.proxy !== undefined ? { proxy: opts.proxy } : {}),
+            ...(opts.daemonEnv !== undefined ? { daemonEnv: opts.daemonEnv } : {}),
+            ...(opts.extraContainers !== undefined ? { extraContainers: opts.extraContainers } : {}),
+        });
+    }
+    /** Every CLI step this fixture ran, as a reader would type it, with its output. */
+    get transcript() {
+        return this.session.transcript;
+    }
+    get ports() {
+        return this.session.ports;
+    }
+    get storeDir() {
+        return this.session.storeDir;
+    }
+    get mode() {
+        return this.session.mode;
+    }
+    get policy() {
+        return this.session.policy;
+    }
+    /** The demo's instance id: what `launch()` uses when not told otherwise. */
+    get defaultInstanceId() {
+        return `demo-${this.slug}`;
+    }
+    cli = (argv, opts) => this.session.cli(argv, opts);
+    cliOk = (argv, opts) => this.session.cliOk(argv, opts);
+    /** The daemon (private on its band, or the developer's), the dev backend
+     *  on the driver's port, and the registration. Nothing is launched. */
+    async setup() {
+        const s = this.session;
+        await s.attachDaemon();
+        if (s.mode === "dev")
+            await s.startDev();
+        if (s.policy === "reuse")
+            await s.resetRegistration(this.defaultInstanceId);
+        await s.register({ licence: true });
+    }
+    /** Store a template now — built from an input, or checked against what the
+     *  product publishes — for a launch by `{ name }` later. What a product
+     *  harness's buildAndImport does before its launchScenario. */
+    async storeTemplate(template) {
+        return this.session.resolveTemplate(template);
+    }
+    /** Store and launch a template, wait until the instance reports running,
+     *  and resolve what a test needs from it. Extras start and `beforeLaunch`
+     *  runs before each launch, exactly as the demo does for its one. */
+    async launch(overrides = {}) {
+        const { spec, session: s, deps } = this;
+        const instanceId = overrides.instanceId ?? this.defaultInstanceId;
+        const templateName = await s.resolveTemplate(overrides.template ?? spec.template);
+        await s.pinGuard(templateName);
+        const launchCtx = {
+            action: this.action,
+            mode: s.mode,
+            daemon: s.policy,
+            product: spec.product,
+            instanceId,
+            daemonPort: s.ports.daemonPort,
+            storeDir: s.storeDir,
+            templateName,
+            templateDir: s.templateDir(templateName),
+            cli: s.cli,
+            log: deps.log,
+        };
+        s.startExtras(instanceId);
+        if (spec.beforeLaunch)
+            await spec.beforeLaunch(launchCtx);
+        const declared = await s.declaredParams(templateName);
+        const specParams = { ...(spec.launch?.params ?? {}), ...(overrides.params ?? {}) };
+        const studioHostPort = specParams[STUDIO_HOST_PORT_PARAM] !== undefined
+            ? Number(specParams[STUDIO_HOST_PORT_PARAM])
+            : this.nextStudioHostPort();
+        const params = [`INSTANCE_NAME=${instanceId}`, ...Object.entries(specParams).map(([k, v]) => `${k}=${v}`)];
+        const launchArgv = ["instance", "launch-template", instanceId, "--template", templateName];
+        const internalOnly = netReachMode() === "direct" && (await deps.supportsNoPublish());
+        if (declared.has(STUDIO_HOST_PORT_PARAM)) {
+            if (specParams[STUDIO_HOST_PORT_PARAM] === undefined)
+                params.push(`${STUDIO_HOST_PORT_PARAM}=${studioHostPort}`);
+        }
+        else if (!internalOnly) {
+            launchArgv.push("--host-ports", `${studioHostPort}:${STUDIO_INTERNAL_PORT}@studio`);
+        }
+        for (const p of params)
+            launchArgv.push("--param", p);
+        const hardware = overrides.hardware ?? spec.launch?.hardware;
+        if (hardware)
+            launchArgv.push("--hardware", hardware);
+        const workingDirectory = overrides.workingDirectory ?? spec.launch?.workingDirectory;
+        if (this.action === "up" && workingDirectory) {
+            launchArgv.push("--working-directory", expandHome(workingDirectory));
+        }
+        const user = deps.containerUser();
+        if (user)
+            launchArgv.push("--container-user", user);
+        if (internalOnly)
+            launchArgv.push("--internal-only");
+        if (!this.launchedIds.includes(instanceId))
+            this.launchedIds.push(instanceId);
+        await s.cliOk(launchArgv);
+        await s.waitRunning(instanceId);
+        const rows = await s.ingestPorts(instanceId);
+        const templateParams = { declared, overrides: specParams };
+        const ctx = {
+            ...launchCtx,
+            url: urlResolver({ instanceId, ports: s.ports, studioHostPort, proxyBase: s.proxyBase, host: s.host }),
+            fetch: deps.fetch,
+        };
+        const instance = {
+            instanceId,
+            templateName,
+            studioHostPort,
+            ctx,
+            ingestPorts: rows,
+            ingestPort: (ingest) => resolveIngestPort(ingest, rows, templateParams),
+            studioTarget: () => ({ instanceId, studioHostPort }),
+            startSources: async (names) => {
+                const chosen = (spec.sources ?? []).filter((src) => !names || names.includes(src.name));
+                const missing = (names ?? []).filter((n) => !chosen.some((src) => src.name === n));
+                if (missing.length)
+                    throw new Error(`no source named ${missing.join(", ")} in the spec`);
+                const targets = chosen.map((src) => ({
+                    port: resolveIngestPort(src.ingest, rows, templateParams),
+                    name: src.name,
+                    asset: src.asset ?? { preset: "camera1" },
+                    ...(src.streamId !== undefined ? { streamId: src.streamId } : {}),
+                }));
+                if (!targets.length)
+                    return [];
+                const secret = s.proxySecret();
+                const handles = await deps.startSources({
+                    daemonPort: s.ports.daemonPort,
+                    instanceId,
+                    targets,
+                    ...(secret !== undefined ? { proxySecret: secret } : {}),
+                });
+                this.handles.push(...handles);
+                deps.log(`sources: ${targets.map((t) => `${t.name} -> :${t.port}`).join(", ")}`);
+                return handles;
+            },
+            awaitReady: async (gates = spec.ready ?? []) => {
+                for (const gate of gates) {
+                    const name = await awaitGate(gate, ctx, s.gateTimeout(gate.timeoutMs));
+                    deps.log(`ready: ${name}`);
+                }
+            },
+        };
+        this.instances.push(instance);
+        return instance;
+    }
+    /** The demo journey on the fixture: launch, pump, gate, `after`, `open`. */
+    async run() {
+        const { spec, session: s, deps } = this;
+        const inst = await this.launch();
+        // Sources first: a gate such as "the switcher is composing" or "the probe
+        // is analysing" can only hold with something on the wire.
+        if (spec.sources?.length)
+            await inst.startSources();
+        await inst.awaitReady();
+        if (spec.after)
+            await spec.after(inst.ctx);
+        const open = await resolveOpen(spec, inst.ctx);
+        const width = Math.max(0, ...open.map((o) => o.name.length));
+        deps.log(`${spec.product} demo is ${this.action === "up" ? "UP" : "up (check)"} — instance ${inst.instanceId}`);
+        for (const o of open)
+            deps.log(`  ${o.name.padEnd(width)}  ${o.value}`);
+        return { instanceId: inst.instanceId, daemonPort: s.ports.daemonPort, storeDir: s.storeDir, open };
+    }
+    /** Sources, every instance a launch named, then — private only — the
+     *  daemon, the dev backend and the store. Throws if the store outlives the
+     *  root-container nuke: a leak a runner would otherwise accumulate. */
+    async teardown() {
+        const s = this.session;
+        const handles = this.handles;
+        this.handles = [];
+        await s.teardown({ instances: [...this.launchedIds], handles });
+        if (s.policy === "private" && this.deps.storeExists(s.storeDir)) {
+            throw new Error(`store ${s.storeDir} still present after the root-container nuke`);
+        }
+    }
+    nextStudioHostPort() {
+        const n = this.launchedIds.length;
+        if (n === 0)
+            return this.ports.studioHostPort;
+        if (n > EXTRA_STUDIO_PORTS) {
+            throw new Error(`launch ${n + 1}: the band holds ${EXTRA_STUDIO_PORTS + 1} studio host ports — pass params.${STUDIO_HOST_PORT_PARAM}`);
+        }
+        return this.ports.proxyPort + n;
+    }
+}
+function urlResolver(o) {
+    const host = o.host;
+    const mode = netReachMode();
+    return (ref) => {
+        if ("url" in ref)
+            return ref.url;
+        if ("control" in ref)
+            return `http://${host}:${o.ports.backendPort}${ref.control}`;
+        if ("proxy" in ref)
+            return `${o.proxyBase}${ref.proxy.replaceAll("{id}", o.instanceId)}`;
+        return `${studioBaseFrom({ instanceId: o.instanceId, studioHostPort: o.studioHostPort }, host, mode)}${ref.studio}`;
+    };
+}
+async function gateHolds(gate, ctx) {
+    if ("custom" in gate)
+        return gate.custom(ctx);
+    const r = await ctx.fetch(ctx.url(gate.http));
+    if (r.status !== (gate.status ?? 200))
+        return false;
+    if (gate.bodyIncludes === undefined)
+        return true;
+    return (await r.text()).includes(gate.bodyIncludes);
+}
+function gateName(gate, ctx) {
+    if ("custom" in gate)
+        return gate.label ?? "custom gate";
+    return `${ctx.url(gate.http)} -> ${gate.status ?? 200}${gate.bodyIncludes ? ` containing '${gate.bodyIncludes}'` : ""}`;
+}
+/** Poll a gate until it holds — or stop at once when it declares its failure
+ *  final (DemoGateFailure), which pollUntil would otherwise keep retrying. */
+async function awaitGate(gate, ctx, timeoutMs) {
+    const name = gateName(gate, ctx);
+    let fatal;
+    await pollUntil(async () => {
+        try {
+            return await gateHolds(gate, ctx);
+        }
+        catch (e) {
+            if (e instanceof DemoGateFailure) {
+                fatal = e;
+                return true;
+            }
+            throw e;
+        }
+    }, { timeoutMs, intervalMs: 1000, label: `ready gate never held: ${name}` });
+    if (fatal)
+        throw new Error(`ready gate failed: ${name}: ${fatal.message}`);
+    return name;
+}
+async function resolveOpen(spec, ctx) {
+    const out = [];
+    for (const o of spec.open ?? []) {
+        const url = ctx.url(o.url);
+        if (!o.pick) {
+            out.push({ name: o.name, value: url });
+            continue;
+        }
+        try {
+            const body = await (await ctx.fetch(url)).text();
+            const m = body.match(new RegExp(o.pick));
+            out.push({ name: o.name, value: m ? m[0] : `<no match for /${o.pick}/ at ${url}>` });
+        }
+        catch (e) {
+            out.push({ name: o.name, value: `<unavailable: ${e instanceof Error ? e.message : String(e)}>` });
+        }
+    }
+    return out;
+}
+/** `up` refuses to run beside a live earlier run of the same demo. Private:
+ *  its daemon still answers. Reuse: the daemon always answers, so the record
+ *  is live only while its instance still exists. A dead record is forgotten. */
+async function refuseIfUp(spec, s, deps) {
+    const prev = deps.state.read(spec.product);
+    if (!prev)
+        return;
+    const answers = await deps.daemonAnswers(prev.daemonPort);
+    const live = prev.daemon === "reuse"
+        ? answers && prev.instanceId !== undefined && (await s.instanceListed(prev.instanceId))
+        : answers;
+    if (live) {
+        throw new Error(`demo '${spec.product}' is already up (daemon :${prev.daemonPort}, store ${prev.storeDir}) — run \`demo down\` first`);
+    }
+    deps.log(`forgetting a stale record of a run on :${prev.daemonPort} (nothing of it is left)`);
+    deps.state.remove(spec.product);
+}
+/** The demo: a ProductHarness set up, run, held (`up`) or not (`check`), torn down. */
+export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
+    const policy = opts.daemon ?? "private";
+    const h = new ProductHarness(spec, {
+        cwd: opts.cwd,
+        mode: opts.mode,
+        daemon: policy,
+        deps,
+        action: opts.action,
+        ...(opts.slug !== undefined ? { slug: opts.slug } : {}),
+        ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
+        ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+        ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
+    });
+    if (opts.action === "up") {
+        await refuseIfUp(spec, h.session, deps);
+        for (const p of spec.prerequisites ?? []) {
+            const path = expandHome(p.path);
+            if (!deps.fileExists(path))
+                throw new Error(`prerequisite missing: ${path}\n  make it with: ${p.hint}`);
+        }
+    }
+    let recorded = false;
+    let result;
+    let journeyError;
+    try {
+        await h.setup();
+        result = await h.run();
+        if (opts.action === "up") {
+            const s = h.session;
+            deps.state.write({
+                product: spec.product,
+                storeDir: s.storeDir,
+                daemonPort: s.ports.daemonPort,
+                instanceId: result.instanceId,
+                daemon: policy,
+                ...(s.extras.length ? { extras: [...s.extras] } : {}),
+                ...(s.dev?.pid !== undefined ? { devPid: s.dev.pid } : {}),
+            });
+            recorded = true;
+            deps.log("holding — Ctrl-C (or `demo down` from another shell) tears down");
+            await deps.hold(opts.abort);
+        }
+    }
+    catch (e) {
+        journeyError = e;
+    }
+    let teardownError;
+    try {
+        await h.teardown();
+    }
+    catch (e) {
+        teardownError = e;
+    }
+    if (recorded)
+        deps.state.remove(spec.product);
+    if (journeyError !== undefined)
+        throw journeyError;
+    if (teardownError !== undefined)
+        throw teardownError;
+    return result;
+}

package/demo/index.d.ts

@@ -3,9 +3,11 @@ export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./c
 export type { DevLoopOptions, DevLoopResult, StandaloneSource } from "./dev-loop.js";
 export { devLoopDown, pumpScript, runDevLoop } from "./dev-loop.js";
 export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.js";
+export type { LaunchedInstance, LaunchOverrides, ProductHarnessOptions } from "./harness.js";
+export { ProductHarness, runDemo } from "./harness.js";
 export type { DemoPane, DemoPaneOptions, DemoUi, DevLoopPaneOptions, PaneLayout, StandaloneDirs } from "./panes.js";
 export { DEV_LOOP_SOURCES, DEV_LOOP_STAMP, demoPaneList, devLoopPaneList, launchLayout, paneArgv, paneCommandLine, paneShellLine, renderLayout, shellQuote, standaloneDirs, } from "./panes.js";
-export type { CliResult, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateKind, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
-export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export type { CliResult, CliStep, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateKind, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
+export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runExportCheck, } from "./run.js";
 export type { DemoContext, DemoDaemonPolicy, DemoExtra, DemoIngest, DemoLaunchContext, DemoMode, DemoOpen, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/index.js

@@ -1,6 +1,7 @@
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
 export { devLoopDown, pumpScript, runDevLoop } from "./dev-loop.js";
 export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.js";
+export { ProductHarness, runDemo } from "./harness.js";
 export { DEV_LOOP_SOURCES, DEV_LOOP_STAMP, demoPaneList, devLoopPaneList, launchLayout, paneArgv, paneCommandLine, paneShellLine, renderLayout, shellQuote, standaloneDirs, } from "./panes.js";
-export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runExportCheck, } from "./run.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/run.d.ts

@@ -188,6 +188,15 @@ export declare function fileStateStore(cwd: string): DemoStateStore;
  *  own), falling back to the pid alone if it is not a group leader. */
 export declare function killGroup(pid: number): void;
 export declare function defaultDemoDeps(cwd: string): DemoDeps;
+/** A CLI step as it ran: the argv a reader would type (no daemon port, no
+ *  output format) and what it printed — what a doc guide renders verbatim
+ *  instead of hand-typing (and drifting from) the command. */
+export interface CliStep {
+    argv: string[];
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
 export interface SessionOptions {
     mode: DemoMode;
     daemon: DemoDaemonPolicy;
@@ -196,6 +205,17 @@ export interface SessionOptions {
     publicHost?: string;
     /** Private: attach to an existing private store (a recorded run) instead of making one. */
     storeDir?: string;
+    /** Private: init the proxy with a basic-auth user (a browser signs in)
+     *  instead of `--proxy-auth none`. */
+    proxy?: {
+        user: string;
+        password: string;
+    };
+    /** Private: extra environment for the daemon process (a doc guide names its
+     *  own proxy container so a run cannot adopt the developer's). */
+    daemonEnv?: Record<string, string>;
+    /** Containers teardown must also wait out — an overridden proxy's pair. */
+    extraContainers?: string[];
 }
 /** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
  *  share: the daemon (private on its band, or the developer's), the dev
@@ -218,7 +238,12 @@ export declare class DemoSession {
     daemon: DaemonProcess | null;
     dev: ProcessHandle | null;
     extras: string[];
+    /** Every CLI call this session made, in order. */
+    readonly transcript: CliStep[];
     private readonly timeouts;
+    private readonly proxyAuth;
+    private readonly daemonEnv;
+    private readonly extraContainers;
     constructor(spec: DemoSpec, slug: string, cwd: string, deps: DemoDeps, opts: SessionOptions);
     get devUrl(): string;
     templateDir(name: string): string;
@@ -266,7 +291,6 @@ export declare class DemoSession {
         handles: SourceHandle[];
     }): Promise<void>;
 }
-export declare function runDemo(spec: DemoSpec, opts: DemoRunOptions, deps?: DemoDeps): Promise<DemoRunResult>;
 export interface ExportCheckOptions {
     cwd: string;
     slug?: string;

package/demo/run.js

@@ -29,20 +29,18 @@ import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSy
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { parseManifestSeed, repoOf } from "@norskvideo/ctl-sdk/manifest-seed";
-import { DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, netReachMode, STUDIO_INTERNAL_PORT, studioBaseFrom, } from "../container-net.js";
+import { DOCKER_NETWORK_NAME, ensureRunnerOnNetwork, netReachMode } 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 { makeStoreDir } from "../temp-dir.js";
-import { DemoGateFailure } from "./gates.js";
 const DEMO_PORT_BASE = 35000;
 const DEMO_BAND_WIDTH = 20;
 const DEMO_BANDS = 50;
 const DEFAULT_DAEMON_PORT = 8333;
 const DEFAULT_PROXY_PORT = 443;
-const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
 const NUKE_IMAGE = "alpine:3";
 const DEFAULT_DEV_READY_PATH = "/manifest.json";
 const SEED_FILE = "manifest.seed.json";
@@ -348,7 +346,12 @@ export class DemoSession {
     daemon = null;
     dev = null;
     extras = [];
+    /** Every CLI call this session made, in order. */
+    transcript = [];
     timeouts;
+    proxyAuth;
+    daemonEnv;
+    extraContainers;
     constructor(spec, slug, cwd, deps, opts) {
         this.spec = spec;
         this.slug = slug;
@@ -373,6 +376,9 @@ export class DemoSession {
             // speaks plain http (seen live: https:// gave 000, http:// served the page).
             this.proxyBase = `http://${host}:${this.ports.proxyPort}`;
         }
+        this.proxyAuth = opts.proxy;
+        this.daemonEnv = opts.daemonEnv ?? {};
+        this.extraContainers = opts.extraContainers ?? [];
         this.timeouts = {
             devReadyMs: opts.timeouts?.devReadyMs ?? 120_000,
             healthyMs: opts.timeouts?.healthyMs ?? 180_000,
@@ -391,12 +397,16 @@ export class DemoSession {
             return undefined;
         return this.deps.readFile(join(this.storeDir, PROXY_SECRET_FILE))?.trim() || undefined;
     }
-    cli = async (argv, opts = {}) => this.deps.cli(this.storeDir, [
-        "--port",
-        String(this.ports.daemonPort),
-        ...argv,
-        ...(opts.output ? ["-o", opts.output] : []),
-    ]);
+    cli = async (argv, opts = {}) => {
+        const r = await this.deps.cli(this.storeDir, [
+            "--port",
+            String(this.ports.daemonPort),
+            ...argv,
+            ...(opts.output ? ["-o", opts.output] : []),
+        ]);
+        this.transcript.push({ argv: [...argv], stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode });
+        return r;
+    };
     cliOk = async (argv, opts = {}) => {
         const r = await this.cli(argv, opts);
         if (r.exitCode !== 0) {
@@ -425,13 +435,22 @@ export class DemoSession {
             // /instance/<id>/... routes (the visualiser a gate reads, the `open`
             // URLs) must answer without a session: with oauth on, the compose gate
             // read the sign-in page as "0 frames" for 180s (playout CI, 2026-08-29).
-            "--proxy-auth",
-            "none",
+            // A doc guide that shows the sign-in asks for a user instead.
+            ...(this.proxyAuth
+                ? ["--proxy-user", this.proxyAuth.user, "--proxy-password", this.proxyAuth.password]
+                : ["--proxy-auth", "none"]),
             "--no-http-redirect",
             "--no-start-server",
             ...(this.publicHost ? ["--public-host", this.publicHost] : []),
         ]);
-        const started = this.deps.startDaemon(this.storeDir, { port: this.ports.daemonPort, seedConfig: false });
+        // The instance ports the daemon allocates come from this band too, so two
+        // products' fixtures on one box never share one (what every product
+        // harness passed by hand).
+        const started = this.deps.startDaemon(this.storeDir, {
+            port: this.ports.daemonPort,
+            seedConfig: false,
+            env: { NORSK_CTL_INSTANCE_PORT_BASE: String(this.ports.instancePortBase), ...this.daemonEnv },
+        });
         this.daemon = started.daemon;
         await started.ready;
         if (netReachMode() === "direct" && this.deps.ensureNetwork() === "failed") {
@@ -634,7 +653,7 @@ export class DemoSession {
                 instances: opts.instances,
                 daemon: this.daemon,
                 storeDir: this.storeDir,
-                containers: opts.instances.flatMap(instanceContainerNames),
+                containers: [...opts.instances.flatMap(instanceContainerNames), ...this.extraContainers],
             });
         }
         catch (e) {
@@ -645,238 +664,6 @@ export class DemoSession {
         this.deps.nukeStoreAsRoot(this.storeDir);
     }
 }
-function urlResolver(o) {
-    const host = o.host;
-    const mode = netReachMode();
-    return (ref) => {
-        if ("url" in ref)
-            return ref.url;
-        if ("control" in ref)
-            return `http://${host}:${o.ports.backendPort}${ref.control}`;
-        if ("proxy" in ref)
-            return `${o.proxyBase}${ref.proxy.replaceAll("{id}", o.instanceId)}`;
-        return `${studioBaseFrom({ instanceId: o.instanceId, studioHostPort: o.studioHostPort }, host, mode)}${ref.studio}`;
-    };
-}
-async function gateHolds(gate, ctx) {
-    if ("custom" in gate)
-        return gate.custom(ctx);
-    const r = await ctx.fetch(ctx.url(gate.http));
-    if (r.status !== (gate.status ?? 200))
-        return false;
-    if (gate.bodyIncludes === undefined)
-        return true;
-    return (await r.text()).includes(gate.bodyIncludes);
-}
-function gateName(gate, ctx) {
-    if ("custom" in gate)
-        return gate.label ?? "custom gate";
-    return `${ctx.url(gate.http)} -> ${gate.status ?? 200}${gate.bodyIncludes ? ` containing '${gate.bodyIncludes}'` : ""}`;
-}
-/** Poll a gate until it holds — or stop at once when it declares its failure
- *  final (DemoGateFailure), which pollUntil would otherwise keep retrying. */
-async function awaitGate(gate, ctx, timeoutMs) {
-    const name = gateName(gate, ctx);
-    let fatal;
-    await pollUntil(async () => {
-        try {
-            return await gateHolds(gate, ctx);
-        }
-        catch (e) {
-            if (e instanceof DemoGateFailure) {
-                fatal = e;
-                return true;
-            }
-            throw e;
-        }
-    }, { timeoutMs, intervalMs: 1000, label: `ready gate never held: ${name}` });
-    if (fatal)
-        throw new Error(`ready gate failed: ${name}: ${fatal.message}`);
-    return name;
-}
-async function resolveOpen(spec, ctx) {
-    const out = [];
-    for (const o of spec.open ?? []) {
-        const url = ctx.url(o.url);
-        if (!o.pick) {
-            out.push({ name: o.name, value: url });
-            continue;
-        }
-        try {
-            const body = await (await ctx.fetch(url)).text();
-            const m = body.match(new RegExp(o.pick));
-            out.push({ name: o.name, value: m ? m[0] : `<no match for /${o.pick}/ at ${url}>` });
-        }
-        catch (e) {
-            out.push({ name: o.name, value: `<unavailable: ${e instanceof Error ? e.message : String(e)}>` });
-        }
-    }
-    return out;
-}
-/** `up` refuses to run beside a live earlier run of the same demo. Private:
- *  its daemon still answers. Reuse: the daemon always answers, so the record
- *  is live only while its instance still exists. A dead record is forgotten. */
-async function refuseIfUp(spec, s, deps) {
-    const prev = deps.state.read(spec.product);
-    if (!prev)
-        return;
-    const answers = await deps.daemonAnswers(prev.daemonPort);
-    const live = prev.daemon === "reuse"
-        ? answers && prev.instanceId !== undefined && (await s.instanceListed(prev.instanceId))
-        : answers;
-    if (live) {
-        throw new Error(`demo '${spec.product}' is already up (daemon :${prev.daemonPort}, store ${prev.storeDir}) — run \`demo down\` first`);
-    }
-    deps.log(`forgetting a stale record of a run on :${prev.daemonPort} (nothing of it is left)`);
-    deps.state.remove(spec.product);
-}
-export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
-    const slug = opts.slug ?? demoSlug(spec.product);
-    const instanceId = `demo-${slug}`;
-    const policy = opts.daemon ?? "private";
-    if (opts.mode === "image" && !spec.image) {
-        throw new Error(`--mode image needs the spec's \`image\` (the built product image) — ${spec.product} declares none`);
-    }
-    const s = new DemoSession(spec, slug, opts.cwd, deps, {
-        mode: opts.mode,
-        daemon: policy,
-        ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
-        ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
-        ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
-    });
-    if (opts.action === "up") {
-        await refuseIfUp(spec, s, deps);
-        for (const p of spec.prerequisites ?? []) {
-            const path = expandHome(p.path);
-            if (!deps.fileExists(path))
-                throw new Error(`prerequisite missing: ${path}\n  make it with: ${p.hint}`);
-        }
-    }
-    let launched = false;
-    let handles = [];
-    let recorded = false;
-    let result;
-    let journeyError;
-    try {
-        await s.attachDaemon();
-        if (opts.mode === "dev")
-            await s.startDev();
-        if (policy === "reuse")
-            await s.resetRegistration(instanceId);
-        await s.register({ licence: true });
-        const templateName = await s.resolveTemplate();
-        await s.pinGuard(templateName);
-        const launchCtx = {
-            action: opts.action,
-            mode: opts.mode,
-            daemon: policy,
-            product: spec.product,
-            instanceId,
-            daemonPort: s.ports.daemonPort,
-            storeDir: s.storeDir,
-            templateName,
-            templateDir: s.templateDir(templateName),
-            cli: s.cli,
-            log: deps.log,
-        };
-        s.startExtras(instanceId);
-        if (spec.beforeLaunch)
-            await spec.beforeLaunch(launchCtx);
-        const declared = await s.declaredParams(templateName);
-        const specParams = spec.launch?.params ?? {};
-        const studioHostPort = specParams[STUDIO_HOST_PORT_PARAM] !== undefined
-            ? Number(specParams[STUDIO_HOST_PORT_PARAM])
-            : s.ports.studioHostPort;
-        const params = [`INSTANCE_NAME=${instanceId}`, ...Object.entries(specParams).map(([k, v]) => `${k}=${v}`)];
-        const launchArgv = ["instance", "launch-template", instanceId, "--template", templateName];
-        const internalOnly = netReachMode() === "direct" && (await deps.supportsNoPublish());
-        if (declared.has(STUDIO_HOST_PORT_PARAM)) {
-            if (specParams[STUDIO_HOST_PORT_PARAM] === undefined)
-                params.push(`${STUDIO_HOST_PORT_PARAM}=${studioHostPort}`);
-        }
-        else if (!internalOnly) {
-            launchArgv.push("--host-ports", `${studioHostPort}:${STUDIO_INTERNAL_PORT}@studio`);
-        }
-        for (const p of params)
-            launchArgv.push("--param", p);
-        if (spec.launch?.hardware)
-            launchArgv.push("--hardware", spec.launch.hardware);
-        if (opts.action === "up" && spec.launch?.workingDirectory) {
-            launchArgv.push("--working-directory", expandHome(spec.launch.workingDirectory));
-        }
-        const user = deps.containerUser();
-        if (user)
-            launchArgv.push("--container-user", user);
-        if (internalOnly)
-            launchArgv.push("--internal-only");
-        launched = true;
-        await s.cliOk(launchArgv);
-        await s.waitRunning(instanceId);
-        const rows = await s.ingestPorts(instanceId);
-        const templateParams = { declared, overrides: specParams };
-        const targets = (spec.sources ?? []).map((src) => ({
-            port: resolveIngestPort(src.ingest, rows, templateParams),
-            name: src.name,
-            asset: src.asset ?? { preset: "camera1" },
-            ...(src.streamId !== undefined ? { streamId: src.streamId } : {}),
-        }));
-        const ctx = {
-            ...launchCtx,
-            url: urlResolver({ instanceId, ports: s.ports, studioHostPort, proxyBase: s.proxyBase, host: s.host }),
-            fetch: deps.fetch,
-        };
-        // Sources first: a gate such as "the switcher is composing" or "the probe
-        // is analysing" can only hold with something on the wire.
-        if (targets.length) {
-            const secret = s.proxySecret();
-            handles = await deps.startSources({
-                daemonPort: s.ports.daemonPort,
-                instanceId,
-                targets,
-                ...(secret !== undefined ? { proxySecret: secret } : {}),
-            });
-            deps.log(`sources: ${targets.map((t) => `${t.name} -> :${t.port}`).join(", ")}`);
-        }
-        for (const gate of spec.ready ?? []) {
-            const name = await awaitGate(gate, ctx, s.gateTimeout(gate.timeoutMs));
-            deps.log(`ready: ${name}`);
-        }
-        if (spec.after)
-            await spec.after(ctx);
-        const open = await resolveOpen(spec, ctx);
-        const width = Math.max(0, ...open.map((o) => o.name.length));
-        deps.log(`${spec.product} demo is ${opts.action === "up" ? "UP" : "up (check)"} — instance ${instanceId}`);
-        for (const o of open)
-            deps.log(`  ${o.name.padEnd(width)}  ${o.value}`);
-        result = { instanceId, daemonPort: s.ports.daemonPort, storeDir: s.storeDir, open };
-        if (opts.action === "up") {
-            deps.state.write({
-                product: spec.product,
-                storeDir: s.storeDir,
-                daemonPort: s.ports.daemonPort,
-                instanceId,
-                daemon: policy,
-                ...(s.extras.length ? { extras: [...s.extras] } : {}),
-                ...(s.dev?.pid !== undefined ? { devPid: s.dev.pid } : {}),
-            });
-            recorded = true;
-            deps.log("holding — Ctrl-C (or `demo down` from another shell) tears down");
-            await deps.hold(opts.abort);
-        }
-    }
-    catch (e) {
-        journeyError = e;
-    }
-    await s.teardown({ instances: launched ? [instanceId] : [], handles });
-    if (recorded)
-        deps.state.remove(spec.product);
-    if (journeyError !== undefined)
-        throw journeyError;
-    if (policy === "private" && deps.storeExists(s.storeDir)) {
-        throw new Error(`store ${s.storeDir} still present after the root-container nuke`);
-    }
-    return result;
-}
 /** `demo check --mode standalone --export-only` (05-demo s4): build the
  *  template, export the standalone workdir with the spec's live-source links,
  *  assert every symlink resolves. No instance, no licence — the daemon's own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "type": "module",
   "exports": {
     ".": {