@norskvideo/ctl-test-harness 0.1.16 → 0.1.18

package/demo/run.js

@@ -0,0 +1,650 @@
+// The demo driver (fleet review 05-demo s4, s7 step 1): runs a DemoSpec on a
+// PRIVATE daemon — a makeStoreDir store on a banded port, exactly as the
+// product harnesses and the smoke tier do — registers the product from source
+// (`--mode dev`: the dev backend on a driver-chosen port, `product add
+// --dev-url`), launches the template, resolves every source's ingest port from
+// the instance, pumps, gates on `ready` while the sources run, runs `after`,
+// prints `open`, then either holds (`up`, released by Ctrl-C or `demo down`)
+// or tears down and exits (`check`, what CI runs). Teardown is a full
+// `shutdown` (instances, the proxy containers the private daemon created,
+// the daemon) because a demo runs on a developer's box, not a throwaway runner.
+//
+// Every side effect sits behind DemoDeps so the sequencing is unit-tested with
+// fakes; defaultDemoDeps wires the real harness. Argv, not Command: this
+// package does not depend on @norskvideo/ctl-commands (smoke.ts, daemon.ts).
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } 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 { makeStoreDir } from "../temp-dir.js";
+const DEMO_PORT_BASE = 35000;
+const DEMO_BAND_WIDTH = 20;
+const DEMO_BANDS = 50;
+const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
+const NUKE_IMAGE = "alpine:3";
+const DEFAULT_DEV_READY_PATH = "/manifest.json";
+/** Per-slug port band above the smoke tier's (33000-34000), so a demo and a
+ *  smoke run of the same product never meet. */
+export function demoPorts(slug, overrides = {}) {
+    const daemonPort = DEMO_PORT_BASE + hashSlot(`demo:${slug}`, DEMO_BANDS) * DEMO_BAND_WIDTH;
+    return {
+        daemonPort,
+        backendPort: daemonPort + 1,
+        studioHostPort: daemonPort + 2,
+        proxyPort: daemonPort + 3,
+        instancePortBase: daemonPort + 10,
+        ...overrides,
+    };
+}
+export function demoSlug(product) {
+    return product.replace(/^norsk-/, "").replace(/[^a-z0-9-]/gi, "-") || "product";
+}
+export function expandHome(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+const NO_PARAMS = { declared: new Map(), overrides: {} };
+function effectiveParam(t, name) {
+    return t.overrides[name] ?? t.declared.get(name);
+}
+function asPort(value) {
+    const n = Number(value);
+    return value !== undefined && value !== "" && Number.isInteger(n) && n > 0 && n < 65536 ? n : undefined;
+}
+function describeIngest(rows, t) {
+    const offered = rows.length === 0
+        ? "the instance offers no ingest ports"
+        : `the instance offers: ${rows
+            .map((r) => {
+            const by = r.param ? `param ${r.param}` : r.label ? `label ${r.label}` : r.origin;
+            return `${r.port}/${r.proto} (${by})`;
+        })
+            .join(", ")}`;
+    const numeric = [...t.declared.keys()]
+        .filter((name) => asPort(effectiveParam(t, name)) !== undefined)
+        .map((name) => `${name}=${effectiveParam(t, name)}`);
+    return numeric.length ? `${offered}; template parameters: ${numeric.join(", ")}` : offered;
+}
+/** Ports come from the instance and its template, not the spec (05-demo s4).
+ *  A `param` is first an allocated port the instance reports, else an
+ *  ordinary template parameter whose effective value (the spec's override,
+ *  else the template default) is the container port — the `${P}:${P}/udp`
+ *  idiom every product's SRT ingest uses. A bare number is accepted only when
+ *  no parameter carries it and the instance offers it as the conventional
+ *  default, so the demo follows the template when the template moves. */
+export function resolveIngestPort(ingest, rows, t = NO_PARAMS) {
+    if ("param" in ingest) {
+        const row = rows.find((r) => r.param === ingest.param);
+        if (row)
+            return row.port;
+        if (t.declared.has(ingest.param)) {
+            const value = effectiveParam(t, ingest.param);
+            const port = asPort(value);
+            if (port === undefined)
+                throw new Error(`param '${ingest.param}' is '${String(value)}', not a port`);
+            return port;
+        }
+        throw new Error(`no ingest port for param '${ingest.param}'; ${describeIngest(rows, t)}`);
+    }
+    if ("label" in ingest) {
+        const row = rows.find((r) => r.label === ingest.label);
+        if (!row)
+            throw new Error(`no ingest port labelled '${ingest.label}'; ${describeIngest(rows, t)}`);
+        return row.port;
+    }
+    const byParam = [...t.declared.keys()].find((name) => asPort(effectiveParam(t, name)) === ingest.port);
+    if (byParam !== undefined) {
+        throw new Error(`restated port ${ingest.port}: it is the template's parameter ${byParam} — name it as ingest: { param: "${byParam}" } so the demo follows the template`);
+    }
+    const row = rows.find((r) => r.port === ingest.port);
+    if (!row)
+        throw new Error(`no listener on port ${ingest.port}; ${describeIngest(rows, t)}`);
+    if (row.origin !== "default") {
+        const name = row.param ? `param: "${row.param}"` : row.label ? `label: "${row.label}"` : null;
+        throw new Error(`restated port ${ingest.port}: the template ${row.origin === "allocated" ? "allocated" : "bound"} it${name ? ` — name it as ingest: { ${name} } so the demo follows the template` : ""}`);
+    }
+    return row.port;
+}
+function parseJson(r, what) {
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        throw new Error(`${what}: not JSON: ${r.stdout.slice(0, 200)}`);
+    }
+}
+function walkSymlinks(dir, out) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const full = join(dir, name);
+        const st = lstatSync(full);
+        if (st.isSymbolicLink()) {
+            const target = readlinkSync(full);
+            const abs = isAbsolute(target) ? target : resolve(dirname(full), target);
+            if (!existsSync(abs))
+                out.push(`${full} -> ${target}`);
+        }
+        else if (st.isDirectory()) {
+            walkSymlinks(full, out);
+        }
+    }
+}
+export function findBrokenSymlinks(dir) {
+    const out = [];
+    walkSymlinks(dir, out);
+    return out;
+}
+/** `<cwd>/test-temp/demo/<product>.json` — beside the store dirs, inside the
+ *  consumer's repo, where `down` from another shell can find it. */
+export function fileStateStore(cwd) {
+    const dir = join(cwd, "test-temp", "demo");
+    const path = (product) => join(dir, `${product}.json`);
+    return {
+        read: (product) => {
+            try {
+                return JSON.parse(readFileSync(path(product), "utf8"));
+            }
+            catch {
+                return null;
+            }
+        },
+        write: (state) => {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(path(state.product), `${JSON.stringify(state, null, 2)}\n`);
+        },
+        remove: (product) => rmSync(path(product), { force: true }),
+    };
+}
+export function defaultDemoDeps(cwd) {
+    return {
+        licenseFile: () => requireLicenseFile({ missing: "throw" }),
+        storeDir: (slug) => makeStoreDir(`norsk-demo-${slug}-`),
+        writeFile: (path, contents) => writeFileSync(path, contents),
+        fileExists: (path) => existsSync(path),
+        startDaemon,
+        daemonAnswers: async (port) => {
+            try {
+                const r = await fetch(`http://localhost:${port}/api/ready`, { signal: AbortSignal.timeout(1000) });
+                return r.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+        cli: (storeDir, argv) => runCli(storeDir, ...argv),
+        startProcess: (command, opts) => {
+            const [cmd, ...args] = command;
+            const proc = spawn(cmd, args, { cwd: opts.cwd, stdio: "inherit", env: { ...process.env, ...opts.env } });
+            const exited = new Promise((res) => proc.once("exit", (code) => res(code)));
+            return {
+                pid: proc.pid,
+                kill: () => {
+                    try {
+                        proc.kill("SIGTERM");
+                    }
+                    catch { }
+                },
+                exited,
+            };
+        },
+        fetch: (url, init) => fetch(url, { signal: AbortSignal.timeout(5000), ...init }),
+        startSources: startSrtSources,
+        stopSources: async (handles) => {
+            for (const h of handles)
+                await h.stop();
+        },
+        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)}`,
+            ]);
+        },
+        storeExists: (storeDir) => existsSync(storeDir),
+        ensureNetwork: () => ensureRunnerOnNetwork(),
+        supportsNoPublish: ctlSupportsNoPublish,
+        containerUser: runnerContainerUser,
+        brokenSymlinks: findBrokenSymlinks,
+        state: fileStateStore(cwd),
+        hold: (abort) => new Promise((res) => {
+            if (abort?.aborted)
+                return res();
+            abort?.addEventListener("abort", () => res(), { once: true });
+            if (!abort) {
+                const release = () => res();
+                process.once("SIGINT", release);
+                process.once("SIGTERM", release);
+            }
+        }),
+        killPid: (pid) => {
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { }
+        },
+        log: (line) => console.log(`[demo] ${line}`),
+    };
+}
+/** The pieces of a run that both `runDemo` and `runExportCheck` share: the
+ *  private daemon on its band, the dev backend on the driver's port, the
+ *  registration, and the template (built or chosen). */
+class DemoSession {
+    spec;
+    slug;
+    cwd;
+    deps;
+    ports;
+    storeDir;
+    daemon = null;
+    dev = null;
+    timeouts;
+    constructor(spec, slug, cwd, deps, timeouts) {
+        this.spec = spec;
+        this.slug = slug;
+        this.cwd = cwd;
+        this.deps = deps;
+        this.ports = demoPorts(slug);
+        this.storeDir = deps.storeDir(slug);
+        this.timeouts = {
+            devReadyMs: timeouts?.devReadyMs ?? 120_000,
+            healthyMs: timeouts?.healthyMs ?? 180_000,
+            readyMs: timeouts?.readyMs ?? 180_000,
+        };
+    }
+    get devUrl() {
+        return `http://localhost:${this.ports.backendPort}`;
+    }
+    cli = async (argv, opts = {}) => this.deps.cli(this.storeDir, [
+        "--port",
+        String(this.ports.daemonPort),
+        ...argv,
+        ...(opts.output ? ["-o", opts.output] : []),
+    ]);
+    cliOk = async (argv, opts = {}) => {
+        const r = await this.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;
+    };
+    async startDaemon() {
+        await this.cliOk([
+            "init",
+            "--network-mode",
+            "docker",
+            "--working-directory",
+            join(this.storeDir, "norsk-runtime"),
+            "--proxy-port",
+            String(this.ports.proxyPort),
+            "--no-http-redirect",
+            "--no-start-server",
+        ]);
+        const started = this.deps.startDaemon(this.storeDir, { port: this.ports.daemonPort, seedConfig: false });
+        this.daemon = started.daemon;
+        await started.ready;
+        if (netReachMode() === "direct" && this.deps.ensureNetwork() === "failed") {
+            throw new Error("could not join the runner to norsk-net for direct reach");
+        }
+    }
+    async startDev() {
+        this.dev = this.deps.startProcess(this.spec.dev.command, {
+            cwd: this.cwd,
+            env: { PORT: String(this.ports.backendPort) },
+        });
+        const url = `${this.devUrl}${this.spec.dev.readyPath ?? DEFAULT_DEV_READY_PATH}`;
+        await pollUntil(async () => {
+            const r = await this.deps.fetch(url);
+            return r.ok;
+        }, { timeoutMs: this.timeouts.devReadyMs, intervalMs: 1000, label: `dev backend did not answer at ${url}` });
+    }
+    async register(opts) {
+        const argv = ["product", "add", "--dev-url", this.devUrl];
+        if (opts.licence)
+            argv.push("--license-file", this.deps.licenseFile());
+        const added = parseJson(await this.cliOk(argv, { output: "json" }), "product add");
+        if (added.name !== this.spec.product) {
+            throw new Error(`product add registered '${added.name}', expected '${this.spec.product}'`);
+        }
+    }
+    /** The template to launch: built from the spec's input, or a name the
+     *  product publishes (its first default when the spec names none). */
+    async resolveTemplate() {
+        const t = this.spec.template;
+        if (t && "build" in t) {
+            const name = t.build.name ?? `${this.spec.product}-demo`;
+            let inputPath;
+            if (typeof t.build.input === "string") {
+                inputPath = resolve(this.cwd, expandHome(t.build.input));
+                if (!this.deps.fileExists(inputPath))
+                    throw new Error(`template input not found: ${inputPath}`);
+            }
+            else {
+                inputPath = join(this.storeDir, `demo-${name}-input.json`);
+                this.deps.writeFile(inputPath, JSON.stringify(t.build.input));
+            }
+            await this.cliOk(["template", "build", name, "--product", this.spec.product, "--input", inputPath, "--replace"]);
+            return name;
+        }
+        const listed = parseJson(await this.cliOk(["template", "list"], { output: "json" }), "template list");
+        const published = (listed.productTemplates ?? []).filter((x) => x.source?.productName === this.spec.product);
+        const names = published.map((x) => x.name);
+        if (t) {
+            if (!names.includes(t.name)) {
+                throw new Error(`template '${t.name}' is not one ${this.spec.product} publishes; it publishes: ${names.join(", ") || "(none)"}`);
+            }
+            return t.name;
+        }
+        const first = names[0];
+        if (!first)
+            throw new Error(`${this.spec.product} publishes no default template; name one with template: { build }`);
+        return first;
+    }
+    /** name -> stringified default, from `template show`. */
+    async declaredParams(templateName) {
+        const shown = await this.cli(["template", "show", templateName], { output: "json" });
+        if (shown.exitCode !== 0)
+            return new Map();
+        const parameters = parseJson(shown, "template show").parameters ?? [];
+        return new Map(parameters.map((p) => [p.name, p.default]));
+    }
+    async waitRunning(instanceId) {
+        await pollUntil(async () => {
+            const r = await this.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: this.timeouts.healthyMs, intervalMs: 1000, label: `instance ${instanceId} never reported running` });
+    }
+    async ingestPorts(instanceId) {
+        const r = await this.cliOk(["instance", "describe", instanceId], { output: "json" });
+        return parseJson(r, "instance describe").ingestPorts ?? [];
+    }
+    gateTimeout(ms) {
+        return ms ?? this.timeouts.readyMs;
+    }
+    /** Tear down in reverse: sources, instance, daemon (with its proxy), dev backend, store. */
+    async teardown(opts) {
+        if (opts.handles.length)
+            await this.deps.stopSources(opts.handles).catch(() => { });
+        try {
+            await this.deps.cleanup({
+                deleteInstance: (id) => this.cli(["instance", "delete", id, "--purge"]),
+                stopDaemon: () => this.cli(["shutdown"]),
+                instances: opts.instances,
+                daemon: this.daemon,
+                storeDir: this.storeDir,
+                containers: opts.instances.flatMap((id) => [`norsk-inst-${id}-studio`, `norsk-inst-${id}-media`]),
+            });
+        }
+        catch (e) {
+            this.deps.log(`cleanup could not remove the store itself (${e instanceof Error ? e.message : String(e)}); nuking as root`);
+        }
+        this.dev?.kill();
+        this.deps.nukeStoreAsRoot(this.storeDir);
+    }
+}
+function urlResolver(o) {
+    const host = process.env.NORSK_TEST_HOST ?? "localhost";
+    const mode = netReachMode();
+    return (ref) => {
+        if ("url" in ref)
+            return ref.url;
+        if ("control" in ref)
+            return `http://localhost:${o.ports.backendPort}${ref.control}`;
+        if ("proxy" in ref)
+            return `https://${host}:${o.ports.proxyPort}${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}'` : ""}`;
+}
+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;
+}
+export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
+    const slug = opts.slug ?? demoSlug(spec.product);
+    const instanceId = `demo-${slug}`;
+    if (opts.action === "up") {
+        const prev = deps.state.read(spec.product);
+        if (prev) {
+            if (await deps.daemonAnswers(prev.daemonPort)) {
+                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 answers there)`);
+            deps.state.remove(spec.product);
+        }
+        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}`);
+        }
+    }
+    const s = new DemoSession(spec, slug, opts.cwd, deps, opts.timeouts);
+    let launched = false;
+    let handles = [];
+    let recorded = false;
+    let result;
+    let journeyError;
+    try {
+        await s.startDaemon();
+        await s.startDev();
+        await s.register({ licence: true });
+        const templateName = await s.resolveTemplate();
+        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 = {
+            action: opts.action,
+            product: spec.product,
+            instanceId,
+            daemonPort: s.ports.daemonPort,
+            storeDir: s.storeDir,
+            url: urlResolver({ instanceId, ports: s.ports, studioHostPort }),
+            cli: s.cli,
+            fetch: deps.fetch,
+            log: deps.log,
+        };
+        // 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) {
+            handles = await deps.startSources({ daemonPort: s.ports.daemonPort, instanceId, targets });
+            deps.log(`sources: ${targets.map((t) => `${t.name} -> :${t.port}`).join(", ")}`);
+        }
+        for (const gate of spec.ready ?? []) {
+            const name = gateName(gate, ctx);
+            await pollUntil(() => gateHolds(gate, ctx), {
+                timeoutMs: s.gateTimeout(gate.timeoutMs),
+                intervalMs: 1000,
+                label: `ready gate never held: ${name}`,
+            });
+            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,
+                ...(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 (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
+ *  preflight still wants a Docker socket, but nothing is launched. This is the
+ *  path that rotted (05-demo s1) and it is cheap enough to gate every push. */
+export async function runExportCheck(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
+    const slug = opts.slug ?? demoSlug(spec.product);
+    const s = new DemoSession(spec, slug, opts.cwd, deps, opts.timeouts);
+    const exportDir = join(s.storeDir, "export");
+    let journeyError;
+    try {
+        await s.startDaemon();
+        await s.startDev();
+        await s.register({ licence: false });
+        const templateName = await s.resolveTemplate();
+        const argv = ["template", "export-workdir", templateName, "--to", exportDir];
+        for (const [k, v] of Object.entries(spec.standalone?.params ?? {}))
+            argv.push("--param", `${k}=${v}`);
+        for (const [pkg, path] of Object.entries(spec.standalone?.links ?? {})) {
+            argv.push("--link-component", `${pkg}=${resolve(opts.cwd, path)}`);
+        }
+        if (spec.standalone?.dashboards)
+            argv.push("--link-dashboards", resolve(opts.cwd, spec.standalone.dashboards));
+        await s.cliOk(argv);
+        const broken = deps.brokenSymlinks(exportDir);
+        if (broken.length) {
+            throw new Error(`exported workdir has ${broken.length} broken symlink(s):\n  ${broken.join("\n  ")}`);
+        }
+        deps.log(`export ok: ${templateName} -> ${exportDir}, every symlink resolves`);
+    }
+    catch (e) {
+        journeyError = e;
+    }
+    await s.teardown({ instances: [], handles: [] });
+    if (journeyError !== undefined)
+        throw journeyError;
+    return { exportDir };
+}
+/** `demo down`: tear down the run `up` recorded, from any shell. */
+export async function demoDown(product, deps = defaultDemoDeps(process.cwd())) {
+    const state = deps.state.read(product);
+    if (!state) {
+        deps.log(`nothing recorded as up for ${product}`);
+        return;
+    }
+    const cli = (argv) => deps.cli(state.storeDir, ["--port", String(state.daemonPort), ...argv]);
+    try {
+        await deps.cleanup({
+            deleteInstance: (id) => cli(["instance", "delete", id, "--purge"]),
+            stopDaemon: () => cli(["shutdown"]),
+            instances: state.instanceId ? [state.instanceId] : [],
+            daemon: null,
+            storeDir: state.storeDir,
+            containers: state.instanceId
+                ? [`norsk-inst-${state.instanceId}-studio`, `norsk-inst-${state.instanceId}-media`]
+                : [],
+        });
+    }
+    catch (e) {
+        deps.log(`cleanup: ${e instanceof Error ? e.message : String(e)}; nuking the store as root`);
+    }
+    if (state.devPid !== undefined)
+        deps.killPid?.(state.devPid);
+    deps.nukeStoreAsRoot(state.storeDir);
+    deps.state.remove(product);
+    deps.log(`${product} demo torn down`);
+}