@norskvideo/ctl-test-harness 0.1.20 → 0.1.22

package/demo/dev-loop.js

@@ -0,0 +1,205 @@
+// The full standalone tier (05-demo s7 step 3): probe's `refresh-standalone`
+// and the sequencing half of `probe-demo-zellij`, for every product. The
+// engine and Studio run from their checkouts (the `dev-loop ui` panes); this
+// driver owns the rest — a private daemon, the dev backend on the driver's
+// port, the template built from source, the workdir exported with the
+// live-source links, the pump script resolved from the template's ports, and
+// the stamp the Studio pane waits for. `up` holds so `refresh` can re-export
+// against the same daemon and backend; `down` tears them down and leaves the
+// developer's workdir where it is.
+import { join } from "node:path";
+import { DEFAULT_STANDALONE_STUDIO_PORT, DEV_LOOP_SOURCES, DEV_LOOP_STAMP, standaloneDirs, } from "./panes.js";
+import { DemoSession, defaultDemoDeps, demoSlug, exportStandaloneWorkdir, resolveIngestPort, } from "./run.js";
+/** The daemon's built-in presets and where it caches them (norsk-ctl
+ *  backend/src/docker/constants.ts: SOURCE_PRESETS, S3_MEDIA_BASE); the
+ *  standalone tier pumps from the same files with the host's ffmpeg. */
+const SAMPLE_MEDIA_BASE = "https://s3.eu-west-1.amazonaws.com/norsk.video/media-examples/data";
+const SAMPLE_MEDIA_FILES = { camera1: "action.mp4", camera2: "wildlife.ts" };
+const SAMPLE_MEDIA_DIR = "$HOME/.norsk-ctl/sample-media";
+function generated(pattern) {
+    const video = pattern === "bars" ? "smptebars=size=1280x720:rate=25" : "testsrc=size=1280x720:rate=25";
+    return `ffmpeg -hide_banner -loglevel warning -re -f lavfi -i "${video}" -f lavfi -i "sine=frequency=440:sample_rate=48000" -c:v libx264 -preset veryfast -tune zerolatency -g 50 -c:a aac`;
+}
+function pumpLines(asset, target) {
+    if ("mediaFile" in asset) {
+        return [
+            `ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "${asset.mediaFile}" -c copy -f mpegts "${target}" &`,
+        ];
+    }
+    if ("generate" in asset)
+        return [`${generated(asset.generate)} -f mpegts "${target}" &`];
+    const file = SAMPLE_MEDIA_FILES[asset.preset];
+    if (!file)
+        throw new Error(`unknown preset '${asset.preset}'; the daemon's presets are ${Object.keys(SAMPLE_MEDIA_FILES).join(", ")}`);
+    return [
+        `f="${SAMPLE_MEDIA_DIR}/${file}"; [ -f "$f" ] || curl -fL --create-dirs -o "$f" "${SAMPLE_MEDIA_BASE}/${file}"`,
+        `ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "$f" -c copy -f mpegts "${target}" &`,
+    ];
+}
+/** The pump script the sources pane runs on Enter: every source in
+ *  parallel with the host's ffmpeg, into the from-source engine. A preset is
+ *  fetched into the daemon's sample-media cache if it is not there yet; a
+ *  mediaFile that is absent on this box pumps its fallback. */
+export function pumpScript(sources, fileExists) {
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# written by dev-loop up: the demo's sources, pumped from this box into the from-source engine",
+        "set -uo pipefail",
+    ];
+    for (const s of sources) {
+        const target = `srt://127.0.0.1:${s.port}?streamid=${s.streamId}`;
+        const asset = "mediaFile" in s.asset && !fileExists(s.asset.mediaFile) ? s.asset.fallback : s.asset;
+        const via = "mediaFile" in s.asset && !fileExists(s.asset.mediaFile) ? ` (${s.asset.mediaFile} is not on this box)` : "";
+        lines.push("", `# ${s.name}: ${JSON.stringify(asset)} -> ${target}${via}`, ...pumpLines(asset, target));
+    }
+    lines.push("", "wait");
+    return `${lines.join("\n")}\n`;
+}
+function standalonePort(ingest, t) {
+    if ("label" in ingest) {
+        throw new Error(`ingest label '${ingest.label}' — the standalone tier has no instance to resolve a label against; name the template parameter (ingest: { param })`);
+    }
+    if ("port" in ingest)
+        return ingest.port;
+    return resolveIngestPort(ingest, [], t);
+}
+/** The standalone tier's template: its own when the spec gives one, else the demo's. */
+function loopTemplate(spec) {
+    return spec.standalone?.template ?? spec.template;
+}
+function studioPortOf(envText) {
+    const m = /^export PORT='?(\d+)/m.exec(envText ?? "");
+    return m ? Number(m[1]) : DEFAULT_STANDALONE_STUDIO_PORT;
+}
+/** Build (or reload) the template, export the workdir, write the pump script
+ *  and finally the stamp — the order the panes rely on. */
+async function exportLoop(s, templateName, workdir, refresh) {
+    const { spec, deps } = s;
+    deps.removeFile(join(workdir, DEV_LOOP_STAMP));
+    if (refresh) {
+        const t = loopTemplate(spec);
+        if (t && "build" in t)
+            await s.resolveTemplate(t);
+        else
+            await s.cliOk(["product", "reload", spec.product]);
+    }
+    await exportStandaloneWorkdir(s, templateName, workdir);
+    const declared = await s.declaredParams(templateName);
+    const t = { declared, overrides: spec.standalone?.params ?? {} };
+    const sources = (spec.sources ?? []).map((src) => {
+        const asset = src.asset ?? { preset: "camera1" };
+        return { name: src.name, port: standalonePort(src.ingest, t), streamId: src.streamId ?? src.name, asset };
+    });
+    deps.writeFile(join(workdir, DEV_LOOP_SOURCES), pumpScript(sources, deps.fileExists));
+    deps.writeFile(join(workdir, DEV_LOOP_STAMP), `${new Date().toISOString()}\n`);
+    return studioPortOf(deps.readFile(join(workdir, "env")));
+}
+function describeLoop(s, dirs, studioPort) {
+    const { spec } = s;
+    const url = `http://${s.host}:${studioPort}`;
+    return [
+        `${spec.product} standalone workdir exported to ${dirs.workdir} (template from the dev backend on :${s.ports.backendPort})`,
+        `  engine   cd ${dirs.norskDir} && nix develop --command make media-shell`,
+        `  studio   cd ${dirs.studioDir} && (. ${dirs.workdir}/env && npm run server-dev)   -> ${url}`,
+        `  sources  bash ${join(dirs.workdir, DEV_LOOP_SOURCES)}   (into the engine, when the workflow is running)`,
+        `  after a shared/ edit: restart this (the dev backend does not watch shared/); a dashboard edit needs only a browser refresh`,
+    ];
+}
+async function refuseIfUp(spec, deps) {
+    const prev = deps.state.read(spec.product, "dev-loop");
+    if (!prev)
+        return;
+    if (await deps.daemonAnswers(prev.daemonPort)) {
+        throw new Error(`dev-loop '${spec.product}' is already up (daemon :${prev.daemonPort}, workdir ${prev.workdir}) — \`dev-loop refresh\` re-exports it, \`dev-loop down\` ends it`);
+    }
+    deps.log(`forgetting a stale dev-loop record of a run on :${prev.daemonPort} (nothing of it is left)`);
+    deps.state.remove(spec.product, "dev-loop");
+}
+export async function runDevLoop(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
+    const slug = opts.slug ?? demoSlug(spec.product);
+    const dirs = opts.dirs ?? standaloneDirs(spec, slug);
+    const common = {
+        mode: "dev",
+        daemon: "private",
+        ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
+        ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
+    };
+    if (opts.action === "refresh") {
+        const state = deps.state.read(spec.product, "dev-loop");
+        if (!state || !(await deps.daemonAnswers(state.daemonPort)) || !state.templateName) {
+            throw new Error(`dev-loop '${spec.product}' is not up — run \`dev-loop up\` first (it holds; refresh from another pane)`);
+        }
+        const s = new DemoSession(spec, slug, opts.cwd, deps, { ...common, storeDir: state.storeDir });
+        const workdir = state.workdir ?? dirs.workdir;
+        const studioPort = await exportLoop(s, state.templateName, workdir, true);
+        for (const line of describeLoop(s, { ...dirs, workdir }, studioPort))
+            deps.log(line);
+        deps.log("refreshed — reload the workflow in Studio");
+        return { workdir, studioUrl: `http://${s.host}:${studioPort}` };
+    }
+    await refuseIfUp(spec, deps);
+    const s = new DemoSession(spec, slug, opts.cwd, deps, common);
+    let recorded = false;
+    let result;
+    let journeyError;
+    try {
+        await s.attachDaemon();
+        await s.startDev();
+        await s.register({ licence: false });
+        const templateName = await s.resolveTemplate(loopTemplate(spec));
+        const studioPort = await exportLoop(s, templateName, dirs.workdir, false);
+        for (const line of describeLoop(s, dirs, studioPort))
+            deps.log(line);
+        result = { workdir: dirs.workdir, studioUrl: `http://${s.host}:${studioPort}` };
+        const state = {
+            product: spec.product,
+            kind: "dev-loop",
+            storeDir: s.storeDir,
+            daemonPort: s.ports.daemonPort,
+            workdir: dirs.workdir,
+            templateName,
+            ...(s.dev?.pid !== undefined ? { devPid: s.dev.pid } : {}),
+        };
+        deps.state.write(state);
+        recorded = true;
+        deps.log("holding — Ctrl-C (or `dev-loop down` from another shell) ends it; `dev-loop refresh` re-exports");
+        await deps.hold(opts.abort);
+    }
+    catch (e) {
+        journeyError = e;
+    }
+    await s.teardown({ instances: [], handles: [] });
+    if (recorded)
+        deps.state.remove(spec.product, "dev-loop");
+    if (journeyError !== undefined)
+        throw journeyError;
+    return result;
+}
+/** `dev-loop down`: end the recorded run from any shell. The workdir stays —
+ *  it is the developer's, and Studio may still be looking at it. */
+export async function devLoopDown(product, deps = defaultDemoDeps(process.cwd())) {
+    const state = deps.state.read(product, "dev-loop");
+    if (!state) {
+        deps.log(`nothing recorded as up for the ${product} dev-loop`);
+        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: [],
+            daemon: null,
+            storeDir: state.storeDir,
+            containers: [],
+        });
+    }
+    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, "dev-loop");
+    deps.log(`${product} dev-loop torn down (the workdir ${state.workdir ?? ""} is untouched)`);
+}

package/demo/gates.d.ts

@@ -0,0 +1,22 @@
+import { type LogPattern, type SpawnLike } from "../container-logs.js";
+import type { DemoReady } from "./spec.js";
+/** Thrown by a gate whose failure is final: the driver stops polling and the
+ *  run fails with this message, teardown included. */
+export declare class DemoGateFailure extends Error {
+    constructor(message: string);
+}
+/** No forbidden line in any container of the instance (`Segmentation fault`,
+ *  say — funke's iterate.sh:156). Holds on clean logs; a hit fails the run at
+ *  once, naming the container and the line. */
+export declare function logsCleanGate(opts: {
+    forbid: readonly LogPattern[];
+    tail?: number;
+    spawn?: SpawnLike;
+}): DemoReady;
+/** The compositor's mediaIn is climbing (playout's ensure-sources.sh gate),
+ *  read through the daemon proxy's visualiser route for this instance. */
+export declare function composeAdvancingGate(opts?: {
+    node?: string;
+    settleMs?: number;
+    timeoutMs?: number;
+}): DemoReady;

package/demo/gates.js

@@ -0,0 +1,56 @@
+// Ready gates a spec composes rather than writes (05-demo s5): the lifted
+// probes as `{ custom, label }` entries for `ready: [...]`. A gate returns
+// false to be polled again; it throws DemoGateFailure to stop the run at once
+// — a segfault is not going to un-happen by waiting.
+import { composeAdvancing, DEFAULT_COMPOSE_NODE } from "../compose-advancing.js";
+import { containerLogsClean } from "../container-logs.js";
+/** Thrown by a gate whose failure is final: the driver stops polling and the
+ *  run fails with this message, teardown included. */
+export class DemoGateFailure extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DemoGateFailure";
+    }
+}
+/** No forbidden line in any container of the instance (`Segmentation fault`,
+ *  say — funke's iterate.sh:156). Holds on clean logs; a hit fails the run at
+ *  once, naming the container and the line. */
+export function logsCleanGate(opts) {
+    const label = `container logs clean of ${opts.forbid.map(String).join(", ")}`;
+    return {
+        label,
+        custom: async (ctx) => {
+            const r = containerLogsClean({
+                instanceId: ctx.instanceId,
+                forbid: opts.forbid,
+                ...(opts.tail !== undefined ? { tail: opts.tail } : {}),
+                ...(opts.spawn !== undefined ? { spawn: opts.spawn } : {}),
+            });
+            if (r.clean)
+                return true;
+            const lines = r.hits.map((h) => `  ${h.container}: ${h.line}`).join("\n");
+            throw new DemoGateFailure(`forbidden line(s) in the instance's container logs:\n${lines}`);
+        },
+    };
+}
+/** The compositor's mediaIn is climbing (playout's ensure-sources.sh gate),
+ *  read through the daemon proxy's visualiser route for this instance. */
+export function composeAdvancingGate(opts = {}) {
+    const node = opts.node ?? DEFAULT_COMPOSE_NODE;
+    return {
+        label: `${node} advancing`,
+        ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        custom: async (ctx) => {
+            const base = ctx.url({ proxy: "/instance/{id}/visualiser" });
+            const r = await composeAdvancing({
+                fetch: ctx.fetch,
+                base,
+                node,
+                ...(opts.settleMs !== undefined ? { settleMs: opts.settleMs } : {}),
+            });
+            if (!r.advancing)
+                ctx.log(`${node} not advancing yet (${r.before} -> ${r.after})`);
+            return r.advancing;
+        },
+    };
+}

package/demo/index.d.ts

@@ -1,6 +1,11 @@
 export type { DemoArgs, DemoCliIo, ResolvedSpecView } from "./cli.js";
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
-export type { CliResult, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, ProcessHandle, TemplateParams, } from "./run.js";
-export { defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
-export type { DemoContext, DemoIngest, DemoOpen, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
+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 { 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 { 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,3 +1,6 @@
 export { defaultDemoCliIo, demoMain, parseDemoArgs, resolvedSpecView } from "./cli.js";
-export { defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runDemo, runExportCheck, } from "./run.js";
+export { devLoopDown, pumpScript, runDevLoop } from "./dev-loop.js";
+export { composeAdvancingGate, DemoGateFailure, logsCleanGate } from "./gates.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 { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/panes.d.ts

@@ -0,0 +1,81 @@
+import type { DemoDaemonPolicy, DemoMode, DemoSpec } from "./spec.js";
+export type DemoUi = "zellij" | "tmux" | "none";
+export interface DemoPane {
+    name: string;
+    /** Directory the pane starts in. */
+    cwd: string;
+    /** One shell line. `run`: a long-running process; `gate`: waits for
+     *  something, then acts; `shell`: an interactive shell (command ignored).
+     *  Every kind lands in a shell when its command exits, so a pane is never a
+     *  dead box. */
+    kind: "run" | "gate" | "shell";
+    command: string;
+    /** The flake ref whose dev shell the command runs under (`.#dev`, `.`). */
+    flake?: string;
+}
+export interface PaneLayout {
+    session: string;
+    tab: string;
+    panes: DemoPane[];
+}
+/** The stamp `dev-loop up` touches once the workdir is exported (the Studio
+ *  pane waits for it) and the pump script it writes (the sources pane runs
+ *  it on Enter). Both live in the workdir so a re-export replaces them. */
+export declare const DEV_LOOP_STAMP = ".dev-loop-exported";
+export declare const DEV_LOOP_SOURCES = ".dev-loop-sources";
+export declare const DEFAULT_STANDALONE_STUDIO_PORT = 8000;
+export declare const INSTANCE_LABEL = "norsk-ctl.instance";
+export declare const MEDIA_ROLE_LABEL = "norsk-ctl.role=media";
+/** POSIX single-quoting: safe for any bytes but a NUL. */
+export declare function shellQuote(s: string): string;
+/** The bash line a pane runs, before any nix wrapping. */
+export declare function paneShellLine(pane: DemoPane): string;
+/** The pane's process: `nix develop <flake> --command bash -c <line>` when
+ *  the pane names a flake, else bash alone. */
+export declare function paneArgv(pane: DemoPane): string[];
+/** `paneArgv` as one shell-quoted line (tmux, none). */
+export declare function paneCommandLine(pane: DemoPane): string;
+export interface DemoPaneOptions {
+    cwd: string;
+    slug: string;
+    mode: DemoMode;
+    daemon: DemoDaemonPolicy;
+    publicHost?: string;
+    /** The product's dev shell; `.#dev` is what every product flake names. */
+    flake?: string;
+}
+/** `demo ui`: the gate pane holds `demo up`, a logs pane follows the
+ *  instance's media container (found by label, so both container naming
+ *  schemes work), and a shell in the product's dev shell. */
+export declare function demoPaneList(_spec: DemoSpec, o: DemoPaneOptions): DemoPane[];
+export interface StandaloneDirs {
+    norskDir: string;
+    studioDir: string;
+    workdir: string;
+}
+/** Where the engine, Studio and the exported workdir live: the environment
+ *  (NORSK_DIR, STUDIO_DIR, TO — this developer's box), else the spec (the
+ *  repo's convention), else `~/dev/norsk`, `~/dev/norsk-studio`,
+ *  `~/dev/<slug>-standalone` (what probe-demo-zellij assumed). */
+export declare function standaloneDirs(spec: DemoSpec, slug: string, env?: Record<string, string | undefined>): StandaloneDirs;
+export interface DevLoopPaneOptions extends StandaloneDirs {
+    cwd: string;
+    slug: string;
+    publicHost?: string;
+    flake?: string;
+    /** The exported workdir's Studio port (export-workdir's default). */
+    studioPort?: number;
+}
+/** `dev-loop ui`: the engine and Studio from their checkouts, the gate pane
+ *  holding `dev-loop up`, the sources pane running the driver's resolved pump
+ *  script on Enter, and a shell. Studio waits for the export stamp, sources
+ *  the exported env, and — with a public host — advertises the MoQ preview
+ *  there and drops the localhost-only cert Studio would otherwise reuse on
+ *  remaining validity alone (probe-demo-zellij:142-149). */
+export declare function devLoopPaneList(_spec: DemoSpec, o: DevLoopPaneOptions): DemoPane[];
+export declare function renderLayout(layout: PaneLayout, ui: DemoUi): string;
+/** Open the rendered layout: zellij's client blocks until detach and the
+ *  session is deleted after it (a trailing line, not a trap: the panes'
+ *  processes get SIGHUP, which the driver's hold treats as a release); tmux's
+ *  script attaches and returns on detach; none prints. */
+export declare function launchLayout(ui: DemoUi, rendered: string, layout: PaneLayout): number;

package/demo/panes.js

@@ -0,0 +1,236 @@
+// The multiplexer front-end (05-demo s4 "front-end 2", s7 step 3). The pane
+// list is the contract; zellij (a kdl layout), tmux (a script) and none (the
+// commands, to paste) are renderers of it. Every pane runs `nix develop
+// <flake> --command ...` so the launcher itself never needs a nix shell —
+// which dissolves the awk-vs-bun problem probe-demo-zellij documented.
+//
+// Ordering never lives here: the gate pane runs `demo up` / `dev-loop up`,
+// and the driver sequences everything. The other panes only wait for what the
+// driver leaves on disk (the export stamp, the resolved pump script).
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** The stamp `dev-loop up` touches once the workdir is exported (the Studio
+ *  pane waits for it) and the pump script it writes (the sources pane runs
+ *  it on Enter). Both live in the workdir so a re-export replaces them. */
+export const DEV_LOOP_STAMP = ".dev-loop-exported";
+export const DEV_LOOP_SOURCES = ".dev-loop-sources";
+export const DEFAULT_STANDALONE_STUDIO_PORT = 8000;
+export const INSTANCE_LABEL = "norsk-ctl.instance";
+export const MEDIA_ROLE_LABEL = "norsk-ctl.role=media";
+/** POSIX single-quoting: safe for any bytes but a NUL. */
+export function shellQuote(s) {
+    return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+/** The bash line a pane runs, before any nix wrapping. */
+export function paneShellLine(pane) {
+    const shell = `exec \${SHELL:-bash}`;
+    return pane.kind === "shell" ? shell : `${pane.command}; ${shell}`;
+}
+/** The pane's process: `nix develop <flake> --command bash -c <line>` when
+ *  the pane names a flake, else bash alone. */
+export function paneArgv(pane) {
+    const line = paneShellLine(pane);
+    return pane.flake ? ["nix", "develop", pane.flake, "--command", "bash", "-c", line] : ["bash", "-c", line];
+}
+/** `paneArgv` as one shell-quoted line (tmux, none). */
+export function paneCommandLine(pane) {
+    return paneArgv(pane)
+        .map((a) => (/^[A-Za-z0-9_./#=:-]+$/.test(a) ? a : shellQuote(a)))
+        .join(" ");
+}
+const DEV_FLAKE = ".#dev";
+/** `demo ui`: the gate pane holds `demo up`, a logs pane follows the
+ *  instance's media container (found by label, so both container naming
+ *  schemes work), and a shell in the product's dev shell. */
+export function demoPaneList(_spec, o) {
+    const flake = o.flake ?? DEV_FLAKE;
+    const instanceId = `demo-${o.slug}`;
+    const up = ["bun run demo -- up", "--mode", o.mode];
+    if (o.daemon === "reuse")
+        up.push("--daemon", "reuse");
+    if (o.publicHost)
+        up.push("--public-host", o.publicHost);
+    const find = `docker ps -q -f label=${INSTANCE_LABEL}=${instanceId} -f label=${MEDIA_ROLE_LABEL}`;
+    return [
+        { name: "demo", kind: "gate", cwd: o.cwd, flake, command: up.join(" ") },
+        {
+            name: "logs",
+            kind: "gate",
+            cwd: o.cwd,
+            command: `echo "waiting for instance ${instanceId} ..."; until [ -n "$(${find})" ]; do sleep 1; done; docker logs -f "$(${find})"`,
+        },
+        { name: "shell", kind: "shell", cwd: o.cwd, flake, command: "" },
+    ];
+}
+function expandWith(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return join(home, path.slice(2));
+    return path;
+}
+/** Where the engine, Studio and the exported workdir live: the environment
+ *  (NORSK_DIR, STUDIO_DIR, TO — this developer's box), else the spec (the
+ *  repo's convention), else `~/dev/norsk`, `~/dev/norsk-studio`,
+ *  `~/dev/<slug>-standalone` (what probe-demo-zellij assumed). */
+export function standaloneDirs(spec, slug, env = process.env) {
+    const home = env.HOME ?? "~";
+    const pick = (envKey, fromSpec, fallback) => expandWith(env[envKey] || fromSpec || fallback, home);
+    return {
+        norskDir: pick("NORSK_DIR", spec.standalone?.norskDir, "~/dev/norsk"),
+        studioDir: pick("STUDIO_DIR", spec.standalone?.studioDir, "~/dev/norsk-studio"),
+        workdir: pick("TO", spec.standalone?.workdir, `~/dev/${slug}-standalone`),
+    };
+}
+/** `dev-loop ui`: the engine and Studio from their checkouts, the gate pane
+ *  holding `dev-loop up`, the sources pane running the driver's resolved pump
+ *  script on Enter, and a shell. Studio waits for the export stamp, sources
+ *  the exported env, and — with a public host — advertises the MoQ preview
+ *  there and drops the localhost-only cert Studio would otherwise reuse on
+ *  remaining validity alone (probe-demo-zellij:142-149). */
+export function devLoopPaneList(_spec, o) {
+    const flake = o.flake ?? DEV_FLAKE;
+    const studioPort = o.studioPort ?? DEFAULT_STANDALONE_STUDIO_PORT;
+    const stamp = join(o.workdir, DEV_LOOP_STAMP);
+    const sources = join(o.workdir, DEV_LOOP_SOURCES);
+    const up = ["bun run dev-loop -- up"];
+    if (o.publicHost)
+        up.push("--public-host", o.publicHost);
+    const wait = `until [ -f ${stamp} ]; do sleep 1; done`;
+    const studio = [`echo "waiting for ${o.workdir} to be exported ..."`, wait, `. ${o.workdir}/env`];
+    if (o.publicHost) {
+        studio.push(`export PUBLIC_URL_PREFIX=http://${o.publicHost}:${studioPort}`, `rm -rf ${o.workdir}/data/moq-certs`, `echo "MoQ preview advertised as http://${o.publicHost}:${studioPort}; cert regenerating to cover ${o.publicHost}"`);
+    }
+    studio.push("npm run server-dev");
+    return [
+        { name: "norsk", kind: "run", cwd: o.norskDir, flake: ".", command: "make media-shell" },
+        { name: "dev-loop", kind: "gate", cwd: o.cwd, flake, command: up.join(" ") },
+        { name: "studio", kind: "gate", cwd: o.studioDir, flake: ".", command: studio.join("; ") },
+        {
+            name: "sources",
+            kind: "gate",
+            cwd: o.cwd,
+            flake,
+            command: `${wait}; cat ${sources}; echo "press Enter to start the sources"; read -r; bash ${sources}`,
+        },
+        { name: "shell", kind: "shell", cwd: o.cwd, flake, command: "" },
+    ];
+}
+function kdlString(s) {
+    return `"${s.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function kdlPane(pane, indent) {
+    const [command, ...args] = paneArgv(pane);
+    return [
+        `${indent}pane name=${kdlString(pane.name)} cwd=${kdlString(pane.cwd)} command=${kdlString(command)} {`,
+        `${indent}    args ${args.map(kdlString).join(" ")}`,
+        `${indent}}`,
+    ].join("\n");
+}
+/** Two columns, the first half of the list on the left — as probe's layout
+ *  did (things that run on the left, things that wait on the right). The tab
+ *  and status bars are declared so the keybinding help is always present. */
+function renderZellij(layout) {
+    const half = Math.ceil(layout.panes.length / 2);
+    const column = (panes) => [
+        `            pane split_direction="horizontal" {`,
+        ...panes.map((p) => kdlPane(p, "                ")),
+        "            }",
+    ].join("\n");
+    return `${[
+        "// rendered by ctl-demo --ui zellij; the pane list is the contract, this file is a view of it",
+        "layout {",
+        "    default_tab_template {",
+        "        pane size=1 borderless=true {",
+        '            plugin location="zellij:tab-bar"',
+        "        }",
+        "        children",
+        "        pane size=2 borderless=true {",
+        '            plugin location="zellij:status-bar"',
+        "        }",
+        "    }",
+        `    tab name=${kdlString(layout.tab)} {`,
+        `        pane split_direction="vertical" {`,
+        column(layout.panes.slice(0, half)),
+        column(layout.panes.slice(half)),
+        "        }",
+        "    }",
+        "}",
+    ].join("\n")}\n`;
+}
+function renderTmux(layout) {
+    const s = shellQuote(layout.session);
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# rendered by ctl-demo --ui tmux; the pane list is the contract, this file is a view of it",
+        "set -euo pipefail",
+        "export NIXPKGS_ALLOW_INSECURE=1 NIXPKGS_ALLOW_UNFREE=1",
+        `s=${s}`,
+        `tmux kill-session -t "$s" 2>/dev/null || true`,
+    ];
+    layout.panes.forEach((pane, i) => {
+        const line = shellQuote(paneCommandLine(pane));
+        if (i === 0) {
+            lines.push(`tmux new-session -d -s "$s" -n ${shellQuote(layout.tab)} -c ${shellQuote(pane.cwd)} ${line}`);
+        }
+        else {
+            lines.push(`tmux split-window -t "$s:0" -c ${shellQuote(pane.cwd)} ${line}`);
+        }
+        lines.push(`tmux select-pane -t "$s:0.${i}" -T ${shellQuote(pane.name)}`);
+    });
+    lines.push(`tmux set-option -t "$s" pane-border-status top`, `tmux select-layout -t "$s:0" tiled`, `tmux select-pane -t "$s:0.0"`, `tmux attach -t "$s"`);
+    return `${lines.join("\n")}\n`;
+}
+function renderNone(layout) {
+    const out = [
+        `# ${layout.session}: one shell per block, in this order (rendered by ctl-demo --ui none)`,
+        "export NIXPKGS_ALLOW_INSECURE=1 NIXPKGS_ALLOW_UNFREE=1",
+    ];
+    for (const pane of layout.panes) {
+        out.push("", `# ${pane.name}`, `cd ${shellQuote(pane.cwd)}`, paneCommandLine(pane));
+    }
+    return `${out.join("\n")}\n`;
+}
+export function renderLayout(layout, ui) {
+    switch (ui) {
+        case "zellij":
+            return renderZellij(layout);
+        case "tmux":
+            return renderTmux(layout);
+        case "none":
+            return renderNone(layout);
+    }
+}
+/** Open the rendered layout: zellij's client blocks until detach and the
+ *  session is deleted after it (a trailing line, not a trap: the panes'
+ *  processes get SIGHUP, which the driver's hold treats as a release); tmux's
+ *  script attaches and returns on detach; none prints. */
+export function launchLayout(ui, rendered, layout) {
+    if (ui === "none") {
+        process.stdout.write(rendered);
+        return 0;
+    }
+    const dir = mkdtempSync(join(tmpdir(), "ctl-demo-ui-"));
+    const env = { ...process.env, NIXPKGS_ALLOW_INSECURE: "1", NIXPKGS_ALLOW_UNFREE: "1" };
+    try {
+        if (ui === "tmux") {
+            const script = join(dir, `${layout.session}.tmux.sh`);
+            writeFileSync(script, rendered);
+            return spawnSync("bash", [script], { stdio: "inherit", env }).status ?? 1;
+        }
+        const kdl = join(dir, `${layout.session}.kdl`);
+        writeFileSync(kdl, rendered);
+        spawnSync("zellij", ["delete-session", "--force", layout.session], { stdio: "ignore" });
+        const r = spawnSync("zellij", ["--new-session-with-layout", kdl, "--session", layout.session], {
+            stdio: "inherit",
+            env,
+        });
+        spawnSync("zellij", ["delete-session", "--force", layout.session], { stdio: "ignore" });
+        return r.status ?? 1;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}