@norskvideo/ctl-test-harness 0.1.4 → 0.1.6

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "exports": {
     "./daemon": {
@@ -18,6 +18,25 @@
     "./harness-config": {
       "types": "./harness-config.d.ts",
       "default": "./harness-config.js"
+    },
+    "./studio-load": {
+      "types": "./studio-load.d.ts",
+      "default": "./studio-load.js"
+    }
+  },
+  "dependencies": {
+    "@norskvideo/ctl-sdk": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@norskvideo/norsk-studio": "*",
+    "@norskvideo/norsk-studio-built-ins": "*"
+  },
+  "peerDependenciesMeta": {
+    "@norskvideo/norsk-studio": {
+      "optional": true
+    },
+    "@norskvideo/norsk-studio-built-ins": {
+      "optional": true
     }
   },
   "publishConfig": {

package/studio-load.d.ts

@@ -0,0 +1,11 @@
+import { load } from "@norskvideo/norsk-studio/lib/runtime/document";
+import { RuntimeSystem } from "@norskvideo/norsk-studio/lib/runtime/system";
+export type CompiledDocument = ReturnType<typeof load>;
+export interface StudioLoadOptions {
+    stubs?: string[];
+    register?: (runtime: RuntimeSystem) => void | Promise<void>;
+    filename?: string;
+    loadOptions?: Parameters<typeof load>[3];
+}
+export declare function loadsInStudio(yamlText: string, opts?: StudioLoadOptions): Promise<CompiledDocument>;
+export declare function assertLoadsInStudio(yamlText: string, opts?: StudioLoadOptions): Promise<CompiledDocument>;

package/studio-load.js

@@ -0,0 +1,70 @@
+// The cheap Layer 4 tier, packaged: run an emitted workflow YAML through
+// Studio's REAL document.load() so every built-ins component's zod schema
+// validates what the composer actually emits — not just the local factory
+// typing. Synchronous validation path only; no Norsk media engine, no Docker.
+//
+// This generalises probe's _util/studio-load.ts (11 scenarios) so no product
+// has to re-derive the fiddly parts:
+//   - built-ins registerAll sits at .default.default when bundled and .default
+//     when externalised; callableDefault tolerates both.
+//   - document.load() records "Unknown node type" and STOPS at the first
+//     component it can't resolve, so one custom component would mask every
+//     error after it. Out-of-library components (a product's own, or alpha
+//     ones absent from @norskvideo/norsk-studio-built-ins) are stub-registered
+//     via `stubs` — permissive, config not validated (there is no schema to
+//     validate against), passing input streams through so downstream built-ins
+//     still resolve subscriptions.
+//
+// Lives in ctl-test-harness (not dev-kit: it needs the norsk-studio packages,
+// which are optional peers here — the products that use it already pin them;
+// dev-kit stays dependency-lean).
+import { callableDefault } from "@norskvideo/ctl-sdk";
+import { load } from "@norskvideo/norsk-studio/lib/runtime/document";
+import { RuntimeSystem } from "@norskvideo/norsk-studio/lib/runtime/system";
+import * as builtInsModule from "@norskvideo/norsk-studio-built-ins";
+const registerAll = callableDefault(builtInsModule, "@norskvideo/norsk-studio-built-ins");
+function registerStub(runtime, identifier) {
+    const info = {
+        identifier,
+        name: identifier,
+        category: "Output",
+        // load() reads info.configForm.global (global-config map) and iterates
+        // info.configForm.form (per-field config patching); an empty non-global
+        // form is all a stub needs.
+        configForm: { global: false, form: {} },
+        subscription: {
+            accepts: {
+                type: "simple-stream",
+                video: true,
+                audio: true,
+                subtitle: true,
+                ancillary: true,
+                playlist: true,
+                acceptsTransient: true,
+            },
+            produces: { type: "dynamic-streams", streams: (_cfg, inputs) => inputs },
+        },
+    };
+    const definition = {
+        create: async () => { },
+        schemas: async () => ({ config: { type: "object", additionalProperties: true } }),
+    };
+    runtime.registerComponent(definition, info, "", undefined, "studio-load-stubs");
+}
+export async function loadsInStudio(yamlText, opts = {}) {
+    const runtime = new RuntimeSystem();
+    await registerAll(runtime);
+    for (const id of opts.stubs ?? [])
+        registerStub(runtime, id);
+    await opts.register?.(runtime);
+    return load(opts.filename ?? "workflow.yml", runtime, yamlText, { resolveConfig: true, ...opts.loadOptions });
+}
+// Throwing form for tests: one assertion per scenario, every load error listed.
+export async function assertLoadsInStudio(yamlText, opts = {}) {
+    const compiled = await loadsInStudio(yamlText, opts);
+    if (compiled.errors.length > 0) {
+        const listed = compiled.errors.map((e, i) => `  [${i}] ${e.message}`).join("\n");
+        throw new Error(`${opts.filename ?? "workflow.yml"} failed Studio document.load():\n${listed}`);
+    }
+    return compiled;
+}