@norskvideo/ctl-test-harness 0.1.20 → 0.1.22

package/demo/run.d.ts

@@ -1,8 +1,9 @@
+import { type ManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
 import { ensureRunnerOnNetwork } from "../container-net.js";
 import { type DaemonProcess, type StartDaemonOptions } from "../daemon.js";
 import { type BaseHarnessPorts } from "../harness-config.js";
 import { type SourceHandle, type SrtPumpTarget } from "../source-pump.js";
-import type { DemoIngest, DemoSpec } from "./spec.js";
+import type { DemoDaemonPolicy, DemoIngest, DemoMode, DemoSpec, DemoTemplate } from "./spec.js";
 export interface CliResult {
     stdout: string;
     stderr: string;
@@ -16,20 +17,38 @@ export interface ProcessHandle {
 /** What `up` records so `down` (or a refused second `up`) can find the run. */
 export interface DemoState {
     product: string;
+    /** Absent on a demo's record; `dev-loop` on the standalone tier's, which
+     *  lives beside it under its own file so the two never mistake each other. */
+    kind?: DemoStateKind;
     storeDir: string;
     daemonPort: number;
     instanceId?: string;
     devPid?: number;
+    /** Absent on records from before the policy existed: private. */
+    daemon?: DemoDaemonPolicy;
+    /** Extra containers `up` started, for `down` to remove. */
+    extras?: string[];
+    /** dev-loop: the exported workdir and the template it exported, for `refresh`. */
+    workdir?: string;
+    templateName?: string;
 }
+export type DemoStateKind = "demo" | "dev-loop";
 export interface DemoStateStore {
-    read(product: string): DemoState | null;
+    read(product: string, kind?: DemoStateKind): DemoState | null;
     write(state: DemoState): void;
-    remove(product: string): void;
+    remove(product: string, kind?: DemoStateKind): void;
 }
 export interface DemoDeps {
     licenseFile(): string;
     storeDir(slug: string): string;
+    /** The developer's real store, for `--daemon reuse`. */
+    realStoreDir(): string;
     writeFile(path: string, contents: string): void;
+    /** Remove a file if present (the dev-loop's export stamp). */
+    removeFile(path: string): void;
+    /** File contents, or null when unreadable (compose.yml, manifest.seed.json,
+     *  config.yaml, proxy-secret). */
+    readFile(path: string): string | null;
     fileExists(path: string): boolean;
     startDaemon(storeDir: string, options: StartDaemonOptions): {
         daemon: DaemonProcess;
@@ -42,11 +61,14 @@ export interface DemoDeps {
         cwd: string;
         env: Record<string, string>;
     }): ProcessHandle;
+    /** One `docker <argv>` invocation: extras, and the reuse policy's control-plane container sweep. */
+    docker(argv: string[]): CliResult;
     fetch(url: string, init?: RequestInit): Promise<Response>;
     startSources(opts: {
         daemonPort: number;
         instanceId: string;
         targets: readonly SrtPumpTarget[];
+        proxySecret?: string;
         timeoutMs?: number;
     }): Promise<SourceHandle[]>;
     stopSources(handles: SourceHandle[]): Promise<void>;
@@ -83,14 +105,21 @@ export interface DemoTimeouts {
 }
 export interface DemoRunOptions {
     action: "up" | "check";
-    mode: "dev";
-    /** The product repo root: dev command cwd, relative inputs and links. */
+    mode: DemoMode;
+    /** Default private. */
+    daemon?: DemoDaemonPolicy;
+    /** `reuse`: the daemon's port (default NORSK_CTL_PORT, else 8333). */
+    daemonPort?: number;
+    /** The product repo root: dev command cwd, relative inputs and links, manifest.seed.json. */
     cwd: string;
     /** Default: the product name without its `norsk-` prefix. */
     slug?: string;
     /** Releases an `up` hold. */
     abort?: AbortSignal;
     timeouts?: DemoTimeouts;
+    /** 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;
 }
 export interface DemoRunResult {
     instanceId: string;
@@ -134,6 +163,23 @@ export interface TemplateParams {
  *  no parameter carries it and the instance offers it as the conventional
  *  default, so the demo follows the template when the template moves. */
 export declare function resolveIngestPort(ingest: DemoIngest, rows: IngestPortRow[], t?: TemplateParams): number;
+/** A stored template's `image:` ref that disagrees with the product's seed. */
+export interface PinMismatch {
+    repo: string;
+    stored: string;
+    seed: string;
+}
+/** Image pins are read, never typed (05-demo s4): for every repo the seed's
+ *  `latest` names (studio, media), the stored compose must pin the same ref.
+ *  A repo the compose does not name is not a mismatch — the guard is about a
+ *  stale snapshot, not template completeness. */
+export declare function checkTemplatePins(composeText: string, seed: ManifestSeed): PinMismatch[];
+/** The two config.yaml scalars the proxy URL needs; a regex, not a YAML
+ *  parser, because that is all the driver reads from a store it does not own. */
+export declare function parseProxyConfig(configText: string | null): {
+    scheme: "http" | "https";
+    port: number;
+};
 export declare function findBrokenSymlinks(dir: string): string[];
 /** `<cwd>/test-temp/demo/<product>.json` — beside the store dirs, inside the
  *  consumer's repo, where `down` from another shell can find it. */
@@ -142,6 +188,84 @@ export declare function fileStateStore(cwd: string): DemoStateStore;
  *  own), falling back to the pid alone if it is not a group leader. */
 export declare function killGroup(pid: number): void;
 export declare function defaultDemoDeps(cwd: string): DemoDeps;
+export interface SessionOptions {
+    mode: DemoMode;
+    daemon: DemoDaemonPolicy;
+    daemonPort?: number;
+    timeouts?: DemoTimeouts;
+    publicHost?: string;
+    /** Private: attach to an existing private store (a recorded run) instead of making one. */
+    storeDir?: string;
+}
+/** The pieces of a run that `runDemo`, `runExportCheck` and the dev-loop
+ *  share: the daemon (private on its band, or the developer's), the dev
+ *  backend on the driver's port, the registration, and the template (built
+ *  or chosen). */
+export declare class DemoSession {
+    readonly spec: DemoSpec;
+    readonly slug: string;
+    readonly cwd: string;
+    readonly deps: DemoDeps;
+    readonly mode: DemoMode;
+    readonly policy: DemoDaemonPolicy;
+    readonly ports: DemoPorts;
+    readonly storeDir: string;
+    /** The host every printed URL names. */
+    readonly host: string;
+    readonly publicHost: string | undefined;
+    /** Scheme + authority of the daemon's proxy, for `proxy` URLs. */
+    readonly proxyBase: string;
+    daemon: DaemonProcess | null;
+    dev: ProcessHandle | null;
+    extras: string[];
+    private readonly timeouts;
+    constructor(spec: DemoSpec, slug: string, cwd: string, deps: DemoDeps, opts: SessionOptions);
+    get devUrl(): string;
+    templateDir(name: string): string;
+    /** What the real daemon's proxy demands on `/api/*`; absent on a private daemon. */
+    proxySecret(): string | undefined;
+    cli: (argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }) => Promise<CliResult>;
+    cliOk: (argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }) => Promise<CliResult>;
+    /** Private: init a virgin store and start a daemon on the band. Reuse: the
+     *  developer's daemon must already answer. */
+    attachDaemon(): Promise<void>;
+    startDev(): Promise<void>;
+    /** The reuse policy's mandatory sequence: `product add` refuses an existing
+     *  name and stored templates are immutable, so the instance, every template
+     *  the product publishes (plus the spec's built one), the product and its
+     *  control-plane container all go first. Each step tolerates absence. */
+    resetRegistration(instanceId: string): Promise<void>;
+    register(opts: {
+        licence: boolean;
+    }): Promise<void>;
+    /** The template to launch: built from the spec's input, or a name the
+     *  product publishes (its first default when the spec names none). */
+    resolveTemplate(t?: DemoTemplate | undefined): Promise<string>;
+    /** Funke's iterate.sh pin guard for every product: the stored compose must
+     *  pin what manifest.seed.json declares. Image mode, and any reuse — a
+     *  private dev-mode daemon renders the template fresh from source, so there
+     *  is nothing stale to catch there. */
+    pinGuard(templateName: string): Promise<void>;
+    /** name -> stringified default, from `template show`. */
+    declaredParams(templateName: string): Promise<Map<string, string | undefined>>;
+    startExtras(instanceId: string): void;
+    stopExtras(): void;
+    waitRunning(instanceId: string): Promise<void>;
+    instanceListed(instanceId: string): Promise<boolean>;
+    ingestPorts(instanceId: string): Promise<IngestPortRow[]>;
+    gateTimeout(ms: number | undefined): number;
+    /** Tear down in reverse: sources, instance, then — private only — the
+     *  daemon (with its proxy), the dev backend, the store. Reuse leaves the
+     *  developer's daemon, store and registration as they are. */
+    teardown(opts: {
+        instances: string[];
+        handles: SourceHandle[];
+    }): Promise<void>;
+}
 export declare function runDemo(spec: DemoSpec, opts: DemoRunOptions, deps?: DemoDeps): Promise<DemoRunResult>;
 export interface ExportCheckOptions {
     cwd: string;
@@ -156,5 +280,8 @@ export interface ExportCheckOptions {
 export declare function runExportCheck(spec: DemoSpec, opts: ExportCheckOptions, deps?: DemoDeps): Promise<{
     exportDir: string;
 }>;
+/** `template export-workdir` with the spec's live-source links and params,
+ *  then the check that rotted (05-demo s1): every symlink resolves. */
+export declare function exportStandaloneWorkdir(s: DemoSession, templateName: string, to: string): Promise<void>;
 /** `demo down`: tear down the run `up` recorded, from any shell. */
 export declare function demoDown(product: string, deps?: DemoDeps): Promise<void>;