@norskvideo/ctl-test-harness 0.1.16 → 0.1.18

package/demo/spec.d.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import type { SourceAsset } from "../source-pump.js";
+/** Where a URL is rooted. `studio` is the instance's published Studio port,
+ *  `proxy` the daemon's oauth2 proxy (`{id}` expands to the instance id),
+ *  `control` the product's control plane (the dev backend), `url` verbatim. */
+export type DemoUrl = {
+    studio: string;
+} | {
+    proxy: string;
+} | {
+    control: string;
+} | {
+    url: string;
+};
+/** How a source finds the port it dials: the manifest parameter or label of
+ *  the ingest the template allocated, or — only for a product that really uses
+ *  the conventional SRT port — the number itself (checked at launch). */
+export type DemoIngest = {
+    param: string;
+} | {
+    label: string;
+} | {
+    port: number;
+};
+export interface DemoSource {
+    /** Source identity within the instance (container name + management key). */
+    name: string;
+    /** Default `{ preset: "camera1" }`. */
+    asset?: SourceAsset;
+    ingest: DemoIngest;
+    streamId?: string;
+}
+export interface DemoContext {
+    action: "up" | "check";
+    product: string;
+    instanceId: string;
+    daemonPort: number;
+    storeDir: string;
+    /** Resolve a spec URL against this run's ports. */
+    url(ref: DemoUrl): string;
+    cli(argv: string[], opts?: {
+        output?: "json" | "yaml";
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    log(line: string): void;
+}
+export type DemoReady = {
+    http: DemoUrl;
+    status?: number;
+    bodyIncludes?: string;
+    timeoutMs?: number;
+} | {
+    custom: (ctx: DemoContext) => Promise<boolean>;
+    label?: string;
+    timeoutMs?: number;
+};
+export interface DemoOpen {
+    name: string;
+    url: DemoUrl;
+    /** A regex applied to the fetched body; the first match is printed instead
+     *  of the URL (a CMAF state document's m3u8, say). */
+    pick?: string;
+}
+export type DemoTemplate = {
+    name: string;
+} | {
+    build: {
+        /** Default `<product>-demo`. */
+        name?: string;
+        /** Template inputs: a JSON file path relative to the repo root, or the object itself. */
+        input: string | Record<string, unknown>;
+    };
+};
+export interface DemoSpec {
+    /** Manifest name, e.g. "norsk-playout". The registration must report it. */
+    product: string;
+    /** Started with PORT=<driver-chosen> in the environment; the driver polls
+     *  `readyPath` (default `/manifest.json`, what `product add` fetches). */
+    dev: {
+        command: string[];
+        readyPath?: string;
+    };
+    /** The built product image for `--mode image` (05-demo s7 step 2). */
+    image?: string;
+    /** Default: the manifest's first default template. */
+    template?: DemoTemplate;
+    launch?: {
+        hardware?: "nvidia" | "none";
+        params?: Record<string, string | number>;
+        /** `up` only; `check` launches without it (05-demo s5 playout). */
+        workingDirectory?: string;
+    };
+    /** Paths `up` needs on the host, each with the command that makes it. */
+    prerequisites?: Array<{
+        path: string;
+        hint: string;
+    }>;
+    sources?: DemoSource[];
+    /** Gates polled in order once the instance runs and the sources pump — so a
+     *  gate may demand what only a source produces (composing, analysing). */
+    ready?: DemoReady[];
+    /** Runs once every gate holds. */
+    after?: (ctx: DemoContext) => Promise<void>;
+    open?: DemoOpen[];
+    /** The standalone tier's live-source links, for `--mode standalone`. Paths
+     *  are relative to the repo root. */
+    standalone?: {
+        links?: Record<string, string>;
+        dashboards?: string;
+        params?: Record<string, string | number>;
+    };
+}
+export declare const DemoSpecSchema: z.ZodType<DemoSpec>;
+/** Format zod's issue list as one line per problem, path first. A union's
+ *  failure would otherwise arrive as every branch's complaint; the rule the
+ *  spec author needs (a `mediaFile` needs a `fallback`) is named explicitly. */
+export declare function formatSpecIssues(error: z.ZodError): string;
+export declare function defineDemo(spec: DemoSpec): DemoSpec;

package/demo/spec.js

@@ -0,0 +1,146 @@
+// The demo spec (fleet review 05-demo s4): one `tests/demo.spec.ts` per product
+// repo, TypeScript because the ready/after hooks are code and component ids
+// live in code. The driver (run.ts) owns everything the spec does not state —
+// the daemon, its store and ports, the dev backend's port, the instance's
+// ingest ports (resolved from `instance describe`, never restated here).
+//
+// The static rules live in zod so a malformed spec fails at `defineDemo`, with
+// a path, before a daemon exists. Runtime rules (a restated port that is not
+// the conventional one, a template the manifest does not publish) live in
+// run.ts because they need the daemon's answer.
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+const fn = () => z.custom((v) => typeof v === "function", { message: "expected a function" });
+const Url = z.union([
+    z.strictObject({ studio: z.string().min(1) }),
+    z.strictObject({ proxy: z.string().min(1) }),
+    z.strictObject({ control: z.string().min(1) }),
+    z.strictObject({ url: z.string().min(1) }),
+]);
+const Builtin = z.union([
+    z.strictObject({ preset: z.string().min(1) }),
+    z.strictObject({ generate: z.enum(["bars", "testsrc"]) }),
+]);
+const Asset = z.union([
+    Builtin,
+    z.strictObject({
+        mediaFile: z.string().min(1),
+        fallback: Builtin,
+    }),
+]);
+const Ingest = z.union([
+    z.strictObject({ param: z.string().min(1) }),
+    z.strictObject({ label: z.string().min(1) }),
+    z.strictObject({ port: z.int().positive() }),
+]);
+const Params = z.record(z.string(), z.union([z.string(), z.number()]));
+const relativePath = z
+    .string()
+    .min(1)
+    .refine((p) => !isAbsolute(p) && !p.startsWith("~"), { message: "must be a relative path inside the repo" });
+export const DemoSpecSchema = z
+    .strictObject({
+    product: z.string().min(1),
+    dev: z.strictObject({
+        command: z.array(z.string().min(1)).min(1),
+        readyPath: z.string().startsWith("/").optional(),
+    }),
+    image: z.string().min(1).optional(),
+    template: z
+        .union([
+        z.strictObject({ name: z.string().min(1) }),
+        z.strictObject({
+            build: z.strictObject({
+                name: z.string().min(1).optional(),
+                input: z.union([z.string().min(1), z.record(z.string(), z.unknown())]),
+            }),
+        }),
+    ])
+        .optional(),
+    launch: z
+        .strictObject({
+        hardware: z.enum(["nvidia", "none"]).optional(),
+        params: Params.optional(),
+        workingDirectory: z.string().min(1).optional(),
+    })
+        .optional(),
+    prerequisites: z.array(z.strictObject({ path: z.string().min(1), hint: z.string().min(1) })).optional(),
+    sources: z
+        .array(z.strictObject({
+        name: z.string().min(1),
+        asset: Asset.optional(),
+        ingest: Ingest,
+        streamId: z.string().min(1).optional(),
+    }))
+        .optional(),
+    ready: z
+        .array(z.union([
+        z.strictObject({
+            http: Url,
+            status: z.int().optional(),
+            bodyIncludes: z.string().optional(),
+            timeoutMs: z.int().positive().optional(),
+        }),
+        z.strictObject({
+            custom: fn(),
+            label: z.string().optional(),
+            timeoutMs: z.int().positive().optional(),
+        }),
+    ]))
+        .optional(),
+    after: fn().optional(),
+    open: z.array(z.strictObject({ name: z.string().min(1), url: Url, pick: z.string().optional() })).optional(),
+    standalone: z
+        .strictObject({
+        links: z.record(z.string().min(1), relativePath).optional(),
+        dashboards: relativePath.optional(),
+        params: Params.optional(),
+    })
+        .optional(),
+})
+    .superRefine((spec, ctx) => {
+    const seen = new Set();
+    (spec.sources ?? []).forEach((s, i) => {
+        if (seen.has(s.name)) {
+            ctx.addIssue({ code: "custom", path: ["sources", i, "name"], message: `duplicate source name '${s.name}'` });
+        }
+        seen.add(s.name);
+    });
+});
+/** Format zod's issue list as one line per problem, path first. A union's
+ *  failure would otherwise arrive as every branch's complaint; the rule the
+ *  spec author needs (a `mediaFile` needs a `fallback`) is named explicitly. */
+export function formatSpecIssues(error) {
+    const lines = [];
+    for (const issue of error.issues) {
+        const path = issue.path
+            .map((p) => (typeof p === "number" ? `[${p}]` : `.${String(p)}`))
+            .join("")
+            .replace(/^\./, "");
+        const message = issue.code === "invalid_union" ? unionHint(issue.path.map(String)) : issue.message;
+        lines.push(`${path || "<root>"}: ${message}`);
+    }
+    return lines.join("\n");
+}
+function unionHint(path) {
+    const leaf = path.at(-1);
+    if (leaf === "asset") {
+        return "expected { preset }, { generate: 'bars' | 'testsrc' } or { mediaFile, fallback: <preset|generate> } — a mediaFile always needs a fallback";
+    }
+    if (leaf === "ingest")
+        return "expected { param }, { label } or { port } naming the ingest this source dials";
+    if (leaf === "template")
+        return "expected { name } or { build: { input } }";
+    if (leaf === "url" || leaf === "http")
+        return "expected { studio }, { proxy }, { control } or { url }";
+    return "no branch matched";
+}
+export function defineDemo(spec) {
+    const parsed = DemoSpecSchema.safeParse(spec);
+    if (!parsed.success) {
+        throw new Error(`invalid demo spec:\n${formatSpecIssues(parsed.error)}`);
+    }
+    // Return the caller's object: the hooks are identities the tests compare by
+    // reference, and zod's copy would drop nothing but is a copy all the same.
+    return spec;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-test-harness",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "exports": {
     ".": {
@@ -42,12 +42,20 @@
     "./smoke": {
       "types": "./smoke.d.ts",
       "default": "./smoke.js"
+    },
+    "./demo": {
+      "types": "./demo/index.d.ts",
+      "default": "./demo/index.js"
     }
   },
   "main": "./index.js",
   "types": "./index.d.ts",
+  "bin": {
+    "ctl-demo": "./demo/cli.js"
+  },
   "dependencies": {
-    "@norskvideo/ctl-sdk": "^0.1.0"
+    "@norskvideo/ctl-sdk": "^0.1.0",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@norskvideo/norsk-studio": "*",

package/smoke.d.ts

@@ -34,7 +34,14 @@ export interface SmokeContext {
     }): Promise<CliResult>;
     fetchStudio(path: string): Promise<Response>;
 }
-export type SmokeObservation = {
+/** Set on any observation that holds with or without a source — a resilient
+ *  switch that keeps a ladder fed from a slate, a control surface that is up
+ *  regardless — so it runs the satisfied phase only. `components` is
+ *  structural by nature and needs no flag. */
+interface Structural {
+    structural?: boolean;
+}
+export type SmokeObservation = Structural & ({
     kind: "components";
     ids: string[];
 } | {
@@ -60,7 +67,7 @@ export type SmokeObservation = {
     kind: "custom";
     label: string;
     satisfied: (ctx: SmokeContext) => Promise<boolean>;
-};
+});
 export interface SmokeSpec {
     product: {
         /** Manifest name, e.g. "norsk-probe". The registration must report it. */
@@ -142,8 +149,10 @@ export interface SmokePorts extends BaseHarnessPorts {
 export declare function smokePorts(slug: string, overrides?: Partial<SmokePorts>): SmokePorts;
 export declare const defaultSmokeDeps: SmokeDeps;
 /** Whether an observation depends on a source being pumped. Structural ones
- *  run the satisfied phase only. */
+ *  (`components`, or anything the spec marks `structural`) run the satisfied
+ *  phase only. */
 export declare function sourceDependent(o: SmokeObservation): boolean;
 /** One sample of an observation — the predicate the three phases poll. */
 export declare function observationSatisfied(o: SmokeObservation, ctx: SmokeContext, readers: SmokeReaders): Promise<boolean>;
 export declare function runProductSmoke(slug: string, spec: SmokeSpec, deps?: SmokeDeps): Promise<void>;
+export {};

package/smoke.js

@@ -100,9 +100,10 @@ function describeObservation(o) {
     }
 }
 /** Whether an observation depends on a source being pumped. Structural ones
- *  run the satisfied phase only. */
+ *  (`components`, or anything the spec marks `structural`) run the satisfied
+ *  phase only. */
 export function sourceDependent(o) {
-    return o.kind !== "components";
+    return o.kind !== "components" && o.structural !== true;
 }
 /** One sample of an observation — the predicate the three phases poll. */
 export async function observationSatisfied(o, ctx, readers) {