@norskvideo/ctl-test-harness 0.1.79 → 0.1.81

package/demo/cli.d.ts

@@ -2,7 +2,7 @@
 import { type DevLoopOptions, type DevLoopResult } from "./dev-loop.js";
 import { type DemoUi, type PaneLayout } from "./panes.js";
 import { type DemoRunOptions, type DemoRunResult, demoPorts } from "./run.js";
-import type { DemoDaemonPolicy, DemoMode, DemoSpec } from "./spec.js";
+import type { DemoDaemonPolicy, DemoMode, DemoPortPolicy, DemoSpec } from "./spec.js";
 export interface DemoArgs {
     /** `dev-loop <action>`: the standalone tier's verbs. */
     devLoop: boolean;
@@ -17,6 +17,8 @@ export interface DemoArgs {
     ui?: DemoUi;
     /** Default: PUBLIC_HOST in the environment. */
     publicHost?: string;
+    /** `up`/`check`: absent is `assigned`. */
+    ports?: DemoPortPolicy;
 }
 export declare function parseDemoArgs(argv: string[]): DemoArgs;
 export interface ResolvedSpecView {

package/demo/cli.js

@@ -30,7 +30,7 @@ import { runDemo } from "./harness.js";
 import { demoPaneList, devLoopPaneList, launchLayout, renderLayout, standaloneDirs, } from "./panes.js";
 import { demoDown, demoPorts, demoSlug, runExportCheck } from "./run.js";
 const USAGE = `usage: demo <up|check|down|spec|ui> [--mode dev|image|standalone] [--daemon private|reuse] [--export-only] [--json]
-            [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]
+            [--ports assigned|band] [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]
        demo dev-loop <up|refresh|down|ui> [--ui zellij|tmux|none] [--public-host <host>] [--spec <path>]
 
   up                                  launch, print the URLs, hold (Ctrl-C tears down)
@@ -54,6 +54,10 @@ const USAGE = `usage: demo <up|check|down|spec|ui> [--mode dev|image|standalone]
   --daemon reuse                      your listening daemon and real store; the driver deletes the instance,
                                       removes the template and product, then adds again (stored templates
                                       are immutable by name)
+  --ports assigned                    up/check: the daemon and proxy take ports the system assigns, so two runs
+                                      never collide (default)
+  --ports band                        up/check: the product's fixed band instead, so the proxy URL (and a
+                                      browser's secure-origin exception for it) survives a relaunch
   --ui zellij|tmux|none               the multiplexer (\`none\` prints the pane commands); zellij unless said
   --public-host <host>                the name other machines reach this box by: every URL, the daemon's
                                       publicHost, Studio's MoQ preview (default: PUBLIC_HOST)
@@ -127,12 +131,22 @@ export function parseDemoArgs(argv) {
             case "--public-host":
                 args.publicHost = value();
                 break;
+            case "--ports": {
+                const p = value();
+                if (p !== "assigned" && p !== "band")
+                    throw new Error(`unknown ports '${p}'\n${USAGE}`);
+                args.ports = p;
+                break;
+            }
             default:
                 throw new Error(`unknown flag '${flag}'\n${USAGE}`);
         }
     }
     if (args.ui !== undefined && args.action !== "ui")
         throw new Error("--ui belongs to ui (or dev-loop ui)");
+    if (args.ports !== undefined && (devLoop || (args.action !== "up" && args.action !== "check"))) {
+        throw new Error("--ports belongs to up and check");
+    }
     if (devLoop && (args.mode !== undefined || args.daemon !== "private" || args.exportOnly || args.json)) {
         throw new Error("dev-loop takes only --ui, --public-host and --spec (no --mode, --daemon, --export-only or --json): it is always the source tier on a private daemon");
     }
@@ -290,6 +304,7 @@ export async function demoMain(argv, io) {
                     daemon: args.daemon,
                     cwd: io.cwd,
                     ...publicHost,
+                    ...(args.ports !== undefined ? { ports: args.ports } : {}),
                     ...(io.abort ? { abort: io.abort } : {}),
                 });
                 return 0;

package/demo/harness.d.ts

@@ -115,6 +115,8 @@ export declare class ProductHarness {
      *  daemon, the dev backend and the store. Throws if the store outlives the
      *  root-container nuke: a leak a runner would otherwise accumulate. */
     teardown(): Promise<void>;
+    private instancePortsIssued;
+    private nextInstancePort;
     private nextStudioHostPort;
 }
 /** The demo: a ProductHarness set up, run, held (`up`) or not (`check`), torn down. */

package/demo/harness.js

@@ -23,6 +23,12 @@ const STUDIO_HOST_PORT_PARAM = "STUDIO_HOST_PORT";
 /** Launches after the first take studio host ports above the proxy's, inside
  *  the band and below `instancePortBase`: six of them. */
 const EXTRA_STUDIO_PORTS = 6;
+/** Allocated-port params come from `instancePortBase` to the band's end: ten. */
+const INSTANCE_PORTS = 10;
+/** A template's allocated host port: a `*_PORT` param defaulting to `auto`,
+ *  which ctl resolves to the first free port from the template's PREFERRED
+ *  one (probe's MOQ_PORT: 4443). */
+const isAllocatedPortParam = (name, dflt) => dflt === "auto" && /_PORT$/.test(name);
 export class ProductHarness {
     spec;
     slug;
@@ -135,6 +141,24 @@ export class ProductHarness {
         else if (!internalOnly) {
             launchArgv.push("--host-ports", `${studioHostPort}:${STUDIO_INTERNAL_PORT}@studio`);
         }
+        // Allocated ports get a port from this run's band, not ctl's `auto`. Auto
+        // is "the first free port from the template's preferred one", and on a
+        // shared docker host every daemon prefers the same one: on 2026-10-08
+        // probe's guide gate lost MOQ_PORT's 4443 between ctl's free-port check
+        // and container start ("host port 4443 was taken between validation and
+        // container start") -- to another instance falling back to its own MoQ
+        // listener, or to the node MoQ relay, which publishes 4443 itself. The
+        // band is per product and below the ephemeral range (port-bands.test.ts),
+        // so nothing else on the host reaches for these. An internal-only launch
+        // publishes no host port at all, so `auto` is harmless there and stays.
+        if (!internalOnly) {
+            for (const [name, dflt] of declared) {
+                if (name === STUDIO_HOST_PORT_PARAM || specParams[name] !== undefined)
+                    continue;
+                if (isAllocatedPortParam(name, dflt))
+                    params.push(`${name}=${this.nextInstancePort(name)}`);
+            }
+        }
         for (const p of params)
             launchArgv.push("--param", p);
         const hardware = overrides.hardware ?? spec.launch?.hardware;
@@ -260,6 +284,14 @@ export class ProductHarness {
             throw new Error(`store ${s.storeDir} still present after the root-container nuke`);
         }
     }
+    instancePortsIssued = 0;
+    nextInstancePort(param) {
+        const n = this.instancePortsIssued++;
+        if (n >= INSTANCE_PORTS) {
+            throw new Error(`${param}: the band holds ${INSTANCE_PORTS} allocated instance ports and this run has used them all -- pass params.${param}`);
+        }
+        return this.ports.instancePortBase + n;
+    }
     nextStudioHostPort() {
         const n = this.launchedIds.length;
         if (n === 0)
@@ -368,8 +400,9 @@ export async function runDemo(spec, opts, deps = defaultDemoDeps(opts.cwd)) {
         ...(opts.daemonPort !== undefined ? { daemonPort: opts.daemonPort } : {}),
         ...(opts.timeouts !== undefined ? { timeouts: opts.timeouts } : {}),
         ...(opts.publicHost !== undefined ? { publicHost: opts.publicHost } : {}),
-        // The driver owns every port of this run, so none can be left behind.
-        ephemeralPorts: true,
+        // The driver owns every port of this run, so none can be left behind;
+        // `band` trades that for URLs that survive a relaunch.
+        ephemeralPorts: opts.ports !== "band",
     });
     if (opts.action === "up") {
         await refuseIfUp(spec, h.session, deps);

package/demo/index.d.ts

@@ -9,5 +9,5 @@ export type { DemoPane, DemoPaneOptions, DemoUi, DevLoopPaneOptions, PaneLayout,
 export { DEV_LOOP_SOURCES, DEV_LOOP_STAMP, demoPaneList, devLoopPaneList, launchLayout, paneArgv, paneCommandLine, paneShellLine, renderLayout, shellQuote, standaloneDirs, } from "./panes.js";
 export type { CliResult, CliStep, DemoDeps, DemoPorts, DemoRunOptions, DemoRunResult, DemoState, DemoStateKind, DemoStateStore, DemoTimeouts, ExportCheckOptions, IngestPortRow, PinMismatch, ProcessHandle, TemplateParams, } from "./run.js";
 export { checkTemplatePins, defaultDemoDeps, demoDown, demoPorts, demoSlug, expandHome, exportStandaloneWorkdir, fileStateStore, findBrokenSymlinks, killGroup, resolveIngestPort, runExportCheck, } from "./run.js";
-export type { DemoContext, DemoDaemonPolicy, DemoExtra, DemoIngest, DemoLaunchContext, DemoMode, DemoOpen, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
+export type { DemoContext, DemoDaemonPolicy, DemoExtra, DemoIngest, DemoLaunchContext, DemoMode, DemoOpen, DemoPortPolicy, DemoReady, DemoSource, DemoSpec, DemoTemplate, DemoUrl, } from "./spec.js";
 export { DemoSpecSchema, defineDemo, formatSpecIssues } from "./spec.js";

package/demo/run.d.ts

@@ -3,7 +3,7 @@ import { ensureRunnerOnNetwork } from "../container-net.js";
 import { type DaemonProcess, type RunningDaemon, type StartDaemonOptions } from "../daemon.js";
 import { type BaseHarnessPorts } from "../harness-config.js";
 import { type SourceHandle, type SrtPumpTarget } from "../source-pump.js";
-import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoSpec, DemoTemplate } from "./spec.js";
+import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoPortPolicy, DemoSpec, DemoTemplate } from "./spec.js";
 export interface CliResult {
     stdout: string;
     stderr: string;
@@ -127,6 +127,8 @@ export interface DemoRunOptions {
     /** The hostname other machines reach this box by: every printed URL uses
      *  it, and a private daemon is initialised with it as its publicHost. */
     publicHost?: string;
+    /** Default assigned. */
+    ports?: DemoPortPolicy;
 }
 export interface DemoRunResult {
     instanceId: string;

package/demo/spec.d.ts

@@ -37,6 +37,9 @@ export type DemoMode = "dev" | "image";
  *  `check` always uses), or `reuse` the developer's listening daemon and its
  *  real store — where `product add` refuses an existing name and stored
  *  templates are immutable, so the driver deletes/removes/re-adds first. */
+/** Whether a run's daemon and proxy take system-assigned ports, or the
+ *  product's fixed band (stable URLs across relaunches, for development). */
+export type DemoPortPolicy = "assigned" | "band";
 export type DemoDaemonPolicy = "private" | "reuse";
 /** What `beforeLaunch` sees: the template is stored, nothing is launched. */
 export interface DemoLaunchContext {

package/package.json

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