@norskvideo/ctl-test-harness 0.1.5 → 0.1.7

package/daemon.d.ts

@@ -3,7 +3,9 @@ import { makeStoreDir, makeTempDir, TEST_TMP_BASE } from "./temp-dir.js";
 export declare const HEALTH_TIMEOUT_MS = 120000;
 export declare const DAEMON_READY_TIMEOUT_MS = 60000;
 export { makeStoreDir, makeTempDir, pollUntil, TEST_TMP_BASE };
-export declare function requireLicenseFile(): string;
+export declare function requireLicenseFile(opts?: {
+    missing?: "exit" | "throw";
+}): string;
 export declare function runCli(storeDir: string, ...args: string[]): Promise<{
     stdout: string;
     stderr: string;
@@ -11,11 +13,28 @@ export declare function runCli(storeDir: string, ...args: string[]): Promise<{
 }>;
 export declare function isPortFree(port: number): Promise<boolean>;
 export declare function killProcessOnPort(port: number): void;
-export declare function startDaemon(storeDir: string, options?: {
+/** The daemon handle callers hold: enough to kill it and await its exit,
+ *  without tying the interface to one runtime's spawn return type. */
+export interface DaemonProcess {
+    pid: number | undefined;
+    kill(signal?: number | NodeJS.Signals): void;
+    /** Resolves with the exit code once the process exits. */
+    exited: Promise<number | null>;
+}
+export interface StartDaemonOptions {
     port?: number;
     env?: Record<string, string>;
-}): {
-    daemon: ReturnType<typeof Bun.spawn>;
+    /** Spawn in its own process group so a caller can group-kill the whole
+     *  `bun run` tree (the doc-guide teardown). Default false. */
+    detached?: boolean;
+    /** Seed <storeDir>/config.yaml with networkMode + a store-rooted working
+     *  directory (see below). Guides drive `init` themselves and must start
+     *  from a virgin store, so they turn this off. Default true. */
+    seedConfig?: boolean;
+    readyTimeoutMs?: number;
+}
+export declare function startDaemon(storeDir: string, options?: StartDaemonOptions): {
+    daemon: DaemonProcess;
     ready: Promise<void>;
 };
 /**
@@ -30,7 +49,7 @@ export declare function cleanupDaemon(opts: {
     stopDaemon: () => Promise<unknown>;
     instances?: string[];
     proxy?: boolean;
-    daemon: ReturnType<typeof Bun.spawn> | null;
+    daemon: DaemonProcess | null;
     storeDir: string;
     containers: string[];
 }): Promise<void>;

package/daemon.js

@@ -1,15 +1,19 @@
-// Daemon-lifecycle helpers for the product integration harnesses. Self-contained
-// so the package publishes cleanly: it spawns the norsk-ctl CLI by command prefix
-// (see cli-command.ts) and drives teardown through an injected command runner,
-// carrying no dependency on norsk-ctl's generated typed `commands` builder.
-import { spawnSync } from "node:child_process";
+// Daemon-lifecycle helpers for the product integration harnesses and the doc
+// guides. Self-contained so the package publishes cleanly: it spawns the
+// norsk-ctl CLI by command prefix (see cli-command.ts) and drives teardown
+// through an injected command runner, carrying no dependency on norsk-ctl's
+// generated typed `commands` builder.
+//
+// Runtime-portable on purpose: everything here uses node:child_process, which
+// works under bun AND under Playwright's Node workers — so the doc-guide tier
+// consumes these same bodies instead of keeping a third fork.
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
 import { cliCommand } from "./cli-command.js";
 import { pollUntil } from "./poll.js";
 import { makeStoreDir, makeTempDir, TEST_TMP_BASE } from "./temp-dir.js";
-process.env.NORSK_CTL_NO_MEDIA_DOWNLOAD = "1";
 export const HEALTH_TIMEOUT_MS = 120_000;
 // The daemon's readiness probe (/api/ready) cannot answer until `serve` has
 // brought up its oauth2-proxy + nginx sidecar CONTAINERS — /api/* redirects
@@ -21,37 +25,49 @@ export const HEALTH_TIMEOUT_MS = 120_000;
 // genuinely slow.
 export const DAEMON_READY_TIMEOUT_MS = 60_000;
 export { makeStoreDir, makeTempDir, pollUntil, TEST_TMP_BASE };
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function splitLines(text) {
     return text
         .split("\n")
         .map((l) => l.trim())
         .filter(Boolean);
 }
-export function requireLicenseFile() {
+export function requireLicenseFile(opts = {}) {
     const licenseFile = process.env.NORSK_LICENSE_FILE;
-    // Some tests call this at module-load (in describe()/test() bodies); others
-    // call it at execution time. A throw at module-load gets wrapped by bun's
-    // "Unhandled error between tests" reporter and produces a cascade of red
-    // alongside genuinely-unrelated failures. Instead, print one clean message
-    // and exit so the suite stops the moment we hit a license-needing test.
     if (!licenseFile || !existsSync(licenseFile)) {
         const reason = !licenseFile
             ? "NORSK_LICENSE_FILE env var is not set."
             : `License file not found at ${licenseFile} (from NORSK_LICENSE_FILE).`;
+        // Playwright workers ("throw") want a per-test failure. Under bun ("exit",
+        // the default) some tests call this at module-load, and a throw there gets
+        // wrapped by bun's "Unhandled error between tests" reporter into a cascade
+        // of red alongside genuinely-unrelated failures — print one clean message
+        // and stop the suite instead.
+        if (opts.missing === "throw")
+            throw new Error(reason);
         console.error(`\nIntegration tests require a Norsk license:\n  ${reason}\n\n  NORSK_LICENSE_FILE=/path/to/license.json bun run test:integration\n`);
         process.exit(1);
     }
     return licenseFile;
 }
 export async function runCli(storeDir, ...args) {
-    const proc = Bun.spawn([...cliCommand, ...args], {
-        stdout: "pipe",
-        stderr: "pipe",
-        env: { ...process.env, NORSK_CTL_STORE_DIR: storeDir },
+    return new Promise((res) => {
+        const [cmd, ...cmdArgs] = cliCommand;
+        const proc = spawn(cmd, [...cmdArgs, ...args], {
+            env: { ...process.env, NORSK_CTL_STORE_DIR: storeDir },
+        });
+        const stdout = [];
+        const stderr = [];
+        proc.stdout.on("data", (d) => stdout.push(d));
+        proc.stderr.on("data", (d) => stderr.push(d));
+        proc.on("close", (code) => {
+            res({
+                stdout: Buffer.concat(stdout).toString(),
+                stderr: Buffer.concat(stderr).toString(),
+                exitCode: code ?? 1,
+            });
+        });
     });
-    const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
-    const exitCode = await proc.exited;
-    return { stdout, stderr, exitCode };
 }
 export function isPortFree(port) {
     return new Promise((resolve) => {
@@ -73,33 +89,53 @@ export function killProcessOnPort(port) {
     }
     catch { }
 }
+function daemonHandle(proc) {
+    const exited = new Promise((resolve) => proc.once("exit", (code) => resolve(code)));
+    return {
+        pid: proc.pid,
+        kill: (signal) => {
+            try {
+                proc.kill(signal);
+            }
+            catch { }
+        },
+        exited,
+    };
+}
 export function startDaemon(storeDir, options) {
     const port = options?.port ?? 8333;
     killProcessOnPort(port);
-    // Root the instance working directory under the store dir (itself under
-    // TEST_TMP_BASE) rather than the daemon default ~/norsk-runtime. The launcher
-    // bind-mounts the workdir as /data and then mounts the stored template's
-    // workflow.yml (which lives under the store dir) *inside* it — Docker Desktop
-    // rejects a nested bind mount whose inner source resolves to a different host
-    // share-root than the outer, so both mounts must share the TEST_TMP_BASE root.
-    // With NORSK_CTL_STORE_DIR set, config.yaml is read from <storeDir>/config.yaml.
-    // networkMode is the one required config.yaml field — omitting it makes the
-    // whole file fail to parse (ConfigParseError), silently dropping the workdir
-    // override. Seed both.
-    const configPath = join(storeDir, "config.yaml");
-    if (!existsSync(configPath)) {
-        writeFileSync(configPath, `networkMode: docker\ndefaultWorkingDirectory: ${JSON.stringify(join(storeDir, "norsk-runtime"))}\n`);
+    if (options?.seedConfig !== false) {
+        // Root the instance working directory under the store dir (itself under
+        // TEST_TMP_BASE) rather than the daemon default ~/norsk-runtime. The launcher
+        // bind-mounts the workdir as /data and then mounts the stored template's
+        // workflow.yml (which lives under the store dir) *inside* it — Docker Desktop
+        // rejects a nested bind mount whose inner source resolves to a different host
+        // share-root than the outer, so both mounts must share the TEST_TMP_BASE root.
+        // With NORSK_CTL_STORE_DIR set, config.yaml is read from <storeDir>/config.yaml.
+        // networkMode is the one required config.yaml field — omitting it makes the
+        // whole file fail to parse (ConfigParseError), silently dropping the workdir
+        // override. Seed both.
+        const configPath = join(storeDir, "config.yaml");
+        if (!existsSync(configPath)) {
+            writeFileSync(configPath, `networkMode: docker\ndefaultWorkingDirectory: ${JSON.stringify(join(storeDir, "norsk-runtime"))}\n`);
+        }
     }
-    const daemon = Bun.spawn([...cliCommand, "serve"], {
-        stdout: "inherit",
-        stderr: "inherit",
+    const [cmd, ...cmdArgs] = cliCommand;
+    const proc = spawn(cmd, [...cmdArgs, "serve"], {
+        stdio: "inherit",
+        detached: options?.detached === true,
         env: { ...process.env, NORSK_CTL_STORE_DIR: storeDir, NORSK_CTL_PORT: String(port), ...options?.env },
     });
     const ready = pollUntil(async () => {
         const res = await fetch(`http://localhost:${port}/api/ready`, { signal: AbortSignal.timeout(1000) });
         return res.ok;
-    }, { timeoutMs: DAEMON_READY_TIMEOUT_MS, intervalMs: 500, label: "Daemon did not become ready" });
-    return { daemon, ready };
+    }, {
+        timeoutMs: options?.readyTimeoutMs ?? DAEMON_READY_TIMEOUT_MS,
+        intervalMs: 500,
+        label: "Daemon did not become ready",
+    });
+    return { daemon: daemonHandle(proc), ready };
 }
 function runningContainers(names) {
     const result = spawnSync("docker", ["ps", "--format", "{{.Names}}"], { encoding: "utf-8" });
@@ -149,10 +185,10 @@ export async function cleanupDaemon(opts) {
     if (opts.daemon) {
         opts.daemon.kill();
         // Escalate to SIGKILL after 3s if process hasn't exited
-        const race = Promise.race([opts.daemon.exited, Bun.sleep(3000).then(() => "timeout")]);
+        const race = Promise.race([opts.daemon.exited, sleep(3000).then(() => "timeout")]);
         if ((await race) === "timeout") {
             opts.daemon.kill(9);
-            await Promise.race([opts.daemon.exited, Bun.sleep(2000)]);
+            await Promise.race([opts.daemon.exited, sleep(2000)]);
         }
     }
     await awaitContainerShutdown(opts.containers);

package/launch.d.ts

@@ -0,0 +1,14 @@
+/** The `uid:gid` the current process runs as, for docker `--container-user`, or
+ *  undefined where POSIX uids don't exist (e.g. Windows, or Docker Desktop's VM
+ *  which maps bind-mount ownership itself and needs no explicit spec). */
+export declare function runnerContainerUser(): string | undefined;
+/** Default a launch's `containerUser` to the runner's uid:gid so bind-mounted
+ *  writes are user-owned, not root. An explicit containerUser always wins, and a
+ *  platform without POSIX uids is left untouched (returns opts unchanged). The
+ *  intersection parameter lets T absorb the caller's own launch-opts shape
+ *  without constraining it, so any launch options object passes through typed. */
+export declare function withContainerUser<T>(opts: T & {
+    containerUser?: string;
+}): T & {
+    containerUser?: string;
+};

package/launch.js

@@ -0,0 +1,32 @@
+// A launched product instance bind-mounts host dirs into the Studio + media
+// containers, which run as root by default -- so every file the container writes
+// under the working directory lands root-owned on the host. On a CI runner the
+// non-root user then cannot remove them, and the next checkout's `git clean`
+// EACCESes on the leftover tree (worst on a shared runner pool, where an
+// innocent sibling workflow inherits the mess). Launching the container as the
+// runner's own uid:gid keeps those writes user-owned, so cleanup stays clean.
+//
+// This is the prevention half; @norskvideo/ctl-test-harness/daemon's
+// cleanupDaemon is the tolerance half (root-nuke on teardown). Pairing the two
+// is the harness's whole "launch clean, tear down clean" story.
+/** The `uid:gid` the current process runs as, for docker `--container-user`, or
+ *  undefined where POSIX uids don't exist (e.g. Windows, or Docker Desktop's VM
+ *  which maps bind-mount ownership itself and needs no explicit spec). */
+export function runnerContainerUser() {
+    const getuid = process.getuid?.bind(process);
+    const getgid = process.getgid?.bind(process);
+    if (!getuid || !getgid)
+        return undefined;
+    return `${getuid()}:${getgid()}`;
+}
+/** Default a launch's `containerUser` to the runner's uid:gid so bind-mounted
+ *  writes are user-owned, not root. An explicit containerUser always wins, and a
+ *  platform without POSIX uids is left untouched (returns opts unchanged). The
+ *  intersection parameter lets T absorb the caller's own launch-opts shape
+ *  without constraining it, so any launch options object passes through typed. */
+export function withContainerUser(opts) {
+    if (opts.containerUser !== undefined)
+        return opts;
+    const user = runnerContainerUser();
+    return user === undefined ? opts : { ...opts, containerUser: user };
+}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "exports": {
     "./daemon": {
       "types": "./daemon.d.ts",
       "default": "./daemon.js"
     },
+    "./launch": {
+      "types": "./launch.d.ts",
+      "default": "./launch.js"
+    },
     "./source-pump": {
       "types": "./source-pump.d.ts",
       "default": "./source-pump.js"