@norskvideo/ctl-sdk 0.1.1 → 0.1.3

package/browser.d.ts

@@ -1,3 +1,4 @@
+export * from "./iframe-protocol.js";
 export * from "./manifest-schema.js";
 export * from "./parsing.js";
 export * from "./product-error.js";

package/browser.js

@@ -1,6 +1,7 @@
 // Browser-safe surface: types, schemas, parsers, validators.
 // Anything with Node-only deps (fs, child_process, express) lives in the
 // default entry only.
+export * from "./iframe-protocol.js";
 export * from "./manifest-schema.js";
 export * from "./parsing.js";
 export * from "./product-error.js";

package/components/ProductIframe.d.ts

@@ -1,10 +1,5 @@
-export type SubmitResult = {
-    ok: true;
-    formValues: Record<string, unknown>;
-} | {
-    ok: false;
-    error?: string;
-};
+import { type SubmitResult } from "../iframe-protocol.js";
+export type { SubmitResult };
 export type ProductIframeHandle = {
     submit: () => Promise<SubmitResult>;
 };

package/components/ProductIframe.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
-const PROTOCOL_VERSION = 1;
+import { IFRAME_PROTOCOL_VERSION, parseChildMessage, } from "../iframe-protocol.js";
 const SUBMIT_TIMEOUT_MS = 30_000;
 function resolveSrc(productName, configScreenUrl) {
     const path = configScreenUrl.startsWith("/") ? configScreenUrl : `/${configScreenUrl}`;
@@ -27,13 +27,14 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
         const onMessage = (event) => {
             if (event.source !== iframeRef.current?.contentWindow)
                 return;
-            const data = event.data;
-            if (!data || typeof data !== "object")
+            const msg = parseChildMessage(event.data);
+            if (!msg)
                 return;
-            if (data.v !== PROTOCOL_VERSION)
-                return;
-            const payload = data.payload ?? {};
-            switch (data.type) {
+            // Payload fields stay runtime-checked despite the typed union: the wire
+            // is a product we don't control, and legacy shapes (option-a
+            // submit-result) predate it.
+            const payload = (msg.payload ?? {});
+            switch (msg.type) {
                 case "ready":
                 case "resize":
                     if (typeof payload.height === "number" && payload.height > 0)
@@ -88,16 +89,19 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
     const launchContextRef = useRef(launchContext);
     launchContextRef.current = launchContext;
     const sendInit = useCallback(() => {
-        iframeRef.current?.contentWindow?.postMessage({
-            v: PROTOCOL_VERSION,
+        const init = {
+            v: IFRAME_PROTOCOL_VERSION,
             type: "init",
             payload: {
                 instanceContext: { basename },
                 theme: "dark",
                 locale: "en",
+                // The prop is a verbatim-forwarded record by design; the protocol
+                // types the keys the products read.
                 ...(launchContextRef.current ? { launchContext: launchContextRef.current } : {}),
             },
-        }, "*");
+        };
+        iframeRef.current?.contentWindow?.postMessage(init, "*");
     }, [basename]);
     useImperativeHandle(ref, () => ({
         submit: () => new Promise((resolve) => {
@@ -106,7 +110,8 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
                 return;
             }
             submitResolverRef.current = resolve;
-            iframeRef.current.contentWindow.postMessage({ v: PROTOCOL_VERSION, type: "submit", payload: {} }, "*");
+            const submit = { v: IFRAME_PROTOCOL_VERSION, type: "submit", payload: {} };
+            iframeRef.current.contentWindow.postMessage(submit, "*");
             setTimeout(() => {
                 if (submitResolverRef.current === resolve) {
                     submitResolverRef.current = null;

package/components/ProductTemplateBuildForm.js

@@ -31,16 +31,22 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
     // caller can hand it off to its launch flow without waiting for a refetch),
     // null on failure.
     const saveProductTemplate = async () => {
-        if (!iframeRef.current) {
-            toast.error("Configuration not ready");
-            return null;
-        }
-        const result = await iframeRef.current.submit();
-        if (!result.ok) {
-            toast.error(result.error ?? "Configuration submission failed");
-            return null;
+        // No config screen declared: there is nothing to collect, so the build
+        // request carries empty form values rather than requiring an iframe.
+        let formValues = {};
+        if (configScreenUrl) {
+            if (!iframeRef.current) {
+                toast.error("Configuration not ready");
+                return null;
+            }
+            const result = await iframeRef.current.submit();
+            if (!result.ok) {
+                toast.error(result.error ?? "Configuration submission failed");
+                return null;
+            }
+            formValues = result.formValues;
         }
-        const outcome = await onSubmit({ productName, productTemplateName, formValues: result.formValues });
+        const outcome = await onSubmit({ productName, productTemplateName, formValues });
         if (!outcome.ok) {
             toast.error(`Save product template failed: ${outcome.error}`);
             return null;

package/http-proxy.d.ts

@@ -0,0 +1,34 @@
+import type { Request, RequestHandler, Response } from "express";
+export declare const HOP_BY_HOP_HEADERS: ReadonlySet<string>;
+/** Forwardable copy of an incoming request's headers: hop-by-hop, host and
+ *  content-length stripped (fetch derives the latter two from the target URL
+ *  and the buffered body). */
+export declare function buildForwardHeaders(req: Request): Headers;
+/** Buffer the request body (small JSON control messages — buffering is robust
+ *  across the fetch duplex-body edge cases). GET/HEAD and empty bodies yield
+ *  undefined. */
+export declare function readRequestBody(req: Request): Promise<Uint8Array | undefined>;
+export type ForwardResponseOptions = {
+    /** Transform response header values before relaying (e.g. re-prefix a
+     *  root-absolute redirect Location). Return the value to send. */
+    rewriteHeader?: (key: string, value: string) => string;
+    /** Observe mid-stream body failures (the response is ended regardless). */
+    onStreamError?: (err: unknown) => void;
+};
+/** Relay an upstream fetch Response: status, headers (hop-by-hop plus
+ *  content-length/content-encoding stripped — fetch already decompressed the
+ *  body), then the streamed body. */
+export declare function forwardUpstreamResponse(res: Response, upstream: globalThis.Response, opts?: ForwardResponseOptions): Promise<void>;
+export type ProxyHttpOptions = ForwardResponseOptions & {
+    /** Abort the upstream fetch (headers AND body) after this long. Defaults to
+     *  30s; pass 0 for no timeout (long-lived streams). */
+    timeoutMs?: number;
+};
+/** Proxy one HTTP request to `targetUrl`, streaming the response body back.
+ *  Never throws into express: an unreachable/booting upstream surfaces as a
+ *  502 the caller retries. */
+export declare function proxyHttp(req: Request, res: Response, targetUrl: string, opts?: ProxyHttpOptions): Promise<void>;
+/** Express handler proxying whatever path it is mounted on to
+ *  `resolveBase(req) + req.originalUrl` (so /live/api/<id>/x reaches
+ *  <studio>/live/api/<id>/x). */
+export declare function makeHttpProxy(resolveBase: (req: Request) => string, opts?: ProxyHttpOptions): RequestHandler;

package/http-proxy.js

@@ -0,0 +1,131 @@
+// Dependency-free fetch-based reverse-proxy core, shared by the runner's
+// product proxy (proxy-middleware.ts) and by instance-side product backends
+// fronting a launched Studio (lifted from funke's live-proxy.ts).
+//
+// Zero new dependency is deliberate: `bun build --target=bun` can mis-bundle a
+// fat CJS proxy dep, only caught in the image. A hand-rolled proxy bundles
+// trivially. WebSocket upgrades are OUT of scope: bun's node:http "upgrade"
+// socket is not writable back to the client, so an in-process WS relay cannot
+// forward the 101 — bridge upstream WS feeds by consuming them as a client and
+// re-emitting same-origin SSE instead (see sse.ts).
+import { Readable } from "node:stream";
+// RFC 7230 §6.1 hop-by-hop headers, which must not travel end-to-end. Includes
+// both "trailer" (the actual header) and "trailers" (the TE value, present in
+// one of the copies this replaces) so neither survives in either direction.
+export const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+]);
+// fetch decompresses upstream bodies and sets host/content-length itself, so
+// the originals must not be relayed alongside the transformed message.
+const REQUEST_ONLY_STRIP = new Set(["host", "content-length"]);
+const RESPONSE_ONLY_STRIP = new Set(["content-length", "content-encoding"]);
+/** Forwardable copy of an incoming request's headers: hop-by-hop, host and
+ *  content-length stripped (fetch derives the latter two from the target URL
+ *  and the buffered body). */
+export function buildForwardHeaders(req) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        const lower = key.toLowerCase();
+        if (HOP_BY_HOP_HEADERS.has(lower) || REQUEST_ONLY_STRIP.has(lower))
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                headers.append(key, v);
+        }
+        else if (value !== undefined) {
+            headers.set(key, value);
+        }
+    }
+    return headers;
+}
+/** Buffer the request body (small JSON control messages — buffering is robust
+ *  across the fetch duplex-body edge cases). GET/HEAD and empty bodies yield
+ *  undefined. */
+export function readRequestBody(req) {
+    const method = req.method.toUpperCase();
+    if (method === "GET" || method === "HEAD")
+        return Promise.resolve(undefined);
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            const buf = Buffer.concat(chunks);
+            resolve(buf.byteLength > 0 ? new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) : undefined);
+        });
+        req.on("error", reject);
+    });
+}
+/** Relay an upstream fetch Response: status, headers (hop-by-hop plus
+ *  content-length/content-encoding stripped — fetch already decompressed the
+ *  body), then the streamed body. */
+export async function forwardUpstreamResponse(res, upstream, opts = {}) {
+    res.status(upstream.status);
+    upstream.headers.forEach((value, key) => {
+        const lower = key.toLowerCase();
+        if (HOP_BY_HOP_HEADERS.has(lower) || RESPONSE_ONLY_STRIP.has(lower))
+            return;
+        res.setHeader(key, opts.rewriteHeader ? opts.rewriteHeader(lower, value) : value);
+    });
+    if (!upstream.body) {
+        res.end();
+        return;
+    }
+    const nodeStream = Readable.fromWeb(upstream.body);
+    await new Promise((resolve) => {
+        nodeStream.on("error", (err) => {
+            opts.onStreamError?.(err);
+            if (!res.headersSent)
+                res.status(502);
+            res.end();
+            resolve();
+        });
+        res.on("close", resolve);
+        nodeStream.pipe(res);
+    });
+}
+const DEFAULT_PROXY_TIMEOUT_MS = 30_000;
+/** Proxy one HTTP request to `targetUrl`, streaming the response body back.
+ *  Never throws into express: an unreachable/booting upstream surfaces as a
+ *  502 the caller retries. */
+export async function proxyHttp(req, res, targetUrl, opts = {}) {
+    const headers = buildForwardHeaders(req);
+    const body = await readRequestBody(req);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_PROXY_TIMEOUT_MS;
+    let upstream;
+    try {
+        upstream = await fetch(targetUrl, {
+            method: req.method.toUpperCase(),
+            headers,
+            body: body,
+            redirect: "manual",
+            ...(timeoutMs > 0 ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
+        });
+    }
+    catch (err) {
+        if (!res.headersSent) {
+            res.status(502).json({ error: "bad gateway", message: err instanceof Error ? err.message : String(err) });
+        }
+        else {
+            res.end();
+        }
+        return;
+    }
+    await forwardUpstreamResponse(res, upstream, opts);
+}
+/** Express handler proxying whatever path it is mounted on to
+ *  `resolveBase(req) + req.originalUrl` (so /live/api/<id>/x reaches
+ *  <studio>/live/api/<id>/x). */
+export function makeHttpProxy(resolveBase, opts = {}) {
+    return (req, res) => {
+        const target = resolveBase(req).replace(/\/+$/, "") + req.originalUrl;
+        void proxyHttp(req, res, target, opts);
+    };
+}

package/iframe-protocol.d.ts

@@ -0,0 +1,112 @@
+export declare const IFRAME_PROTOCOL_VERSION = 1;
+export type IframeTheme = "light" | "dark";
+export type InstanceContext = {
+    /** Path prefix where the product is mounted on the runner's origin (e.g.
+     *  `/products/norsk-probe`) — feed it to the product router's basename. */
+    basename?: string;
+};
+/** Present only for the instance-launch config screen: the product template
+ *  being launched (name + parameters), so the screen can prefill. */
+export type LaunchContext = {
+    productTemplateName?: string;
+    parameters?: {
+        name: string;
+        default?: string;
+    }[];
+};
+/** The iframe reports the form values it captured; the runner POSTs them to
+ *  the product's /api/product-template to get the tar. formValues is
+ *  product-specific. */
+export type SubmitResult = {
+    ok: true;
+    formValues: Record<string, unknown>;
+} | {
+    ok: false;
+    error?: string;
+};
+export type IframeChildMessage = {
+    v: 1;
+    type: "ready";
+    payload: {
+        height: number;
+    };
+} | {
+    v: 1;
+    type: "resize";
+    payload: {
+        height: number;
+    };
+} | {
+    v: 1;
+    type: "validity";
+    payload: {
+        valid: boolean;
+        errors?: string[];
+    };
+} | {
+    v: 1;
+    type: "suggest-name";
+    payload: {
+        name: string;
+    };
+} | {
+    v: 1;
+    type: "dirty";
+    payload: {
+        dirty: boolean;
+    };
+} | {
+    v: 1;
+    type: "submit-result";
+    payload: SubmitResult;
+} | {
+    v: 1;
+    type: "request-cancel";
+    payload: Record<string, never>;
+};
+export type IframeParentMessage = {
+    v: 1;
+    type: "init";
+    payload: {
+        instanceContext?: InstanceContext;
+        theme?: IframeTheme;
+        locale?: string;
+        launchContext?: LaunchContext;
+    };
+} | {
+    v: 1;
+    type: "submit";
+    payload: Record<string, never>;
+} | {
+    v: 1;
+    type: "cancel";
+    payload: Record<string, never>;
+} | {
+    v: 1;
+    type: "theme-change";
+    payload: {
+        theme: IframeTheme;
+    };
+};
+export declare function parseParentMessage(data: unknown): IframeParentMessage | null;
+export declare function parseChildMessage(data: unknown): IframeChildMessage | null;
+export type IframeWindowLike = {
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    };
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    document: {
+        body: {
+            scrollHeight: number;
+        };
+    };
+};
+export declare const isEmbedded: (win?: IframeWindowLike) => boolean;
+export declare const sendToParent: (msg: IframeChildMessage, win?: IframeWindowLike) => void;
+export declare const onParentMessage: (handler: (msg: IframeParentMessage) => void, win?: IframeWindowLike) => (() => void);
+export declare const reportHeight: (win?: IframeWindowLike) => void;

package/iframe-protocol.js

@@ -0,0 +1,44 @@
+// The runner<->product iframe postMessage contract (v1), single-sourced for
+// BOTH sides: the runner's ProductIframe component builds IframeParentMessage
+// values, and a product's config screen imports the child-side helpers below
+// instead of hand-copying them from the iframe-integration doc.
+//
+// Standalone usage (product opened outside the runner): window.parent ===
+// window, so every send becomes a no-op.
+export const IFRAME_PROTOCOL_VERSION = 1;
+// Envelope guard shared by both directions: any v1 object with a string type
+// passes (matching the product copies' onParentMessage filter); per-field
+// payload validation stays with the consumer, which knows its own defaults.
+function isEnvelope(data) {
+    return (data !== null &&
+        typeof data === "object" &&
+        data.v === IFRAME_PROTOCOL_VERSION &&
+        typeof data.type === "string");
+}
+export function parseParentMessage(data) {
+    return isEnvelope(data) ? data : null;
+}
+export function parseChildMessage(data) {
+    return isEnvelope(data) ? data : null;
+}
+// globalThis, not window: node-side consumers (dev-kit, backend) pull this
+// module in via the browser barrel and typecheck without the DOM lib.
+const realWindow = () => globalThis.window;
+export const isEmbedded = (win = realWindow()) => win.parent !== win;
+export const sendToParent = (msg, win = realWindow()) => {
+    if (!isEmbedded(win))
+        return;
+    win.parent.postMessage(msg, "*");
+};
+export const onParentMessage = (handler, win = realWindow()) => {
+    const listener = (event) => {
+        const msg = parseParentMessage(event.data);
+        if (msg)
+            handler(msg);
+    };
+    win.addEventListener("message", listener);
+    return () => win.removeEventListener("message", listener);
+};
+export const reportHeight = (win = realWindow()) => {
+    sendToParent({ v: 1, type: "resize", payload: { height: win.document.body.scrollHeight } }, win);
+};

package/index.d.ts

@@ -3,6 +3,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
@@ -13,3 +14,5 @@ export * from "./product-health-monitor.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
+export * from "./route-error.js";
+export * from "./sse.js";

package/index.js

@@ -5,6 +5,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
@@ -15,3 +16,5 @@ export * from "./product-health-monitor.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
+export * from "./route-error.js";
+export * from "./sse.js";

package/manifest-schema.d.ts

@@ -22,8 +22,8 @@ export declare const ManifestSchema: z.ZodObject<{
         healthCheckPath: z.ZodDefault<z.ZodString>;
         productMcpPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    ui: z.ZodObject<{
-        configScreenUrl: z.ZodString;
+    ui: z.ZodDefault<z.ZodObject<{
+        configScreenUrl: z.ZodOptional<z.ZodString>;
         instanceConfigScreenUrl: z.ZodOptional<z.ZodString>;
         sidebarEntries: z.ZodDefault<z.ZodArray<z.ZodObject<{
             label: z.ZodString;
@@ -39,8 +39,8 @@ export declare const ManifestSchema: z.ZodObject<{
             label: z.ZodString;
             configScreenUrl: z.ZodString;
         }, z.core.$strip>>>;
-    }, z.core.$strip>;
-    cli: z.ZodObject<{
+    }, z.core.$strip>>;
+    cli: z.ZodDefault<z.ZodObject<{
         subcommandTree: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -53,6 +53,7 @@ export declare const ManifestSchema: z.ZodObject<{
                     number: "number";
                     boolean: "boolean";
                 }>>;
+                choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>>;
             subcommands: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -66,6 +67,7 @@ export declare const ManifestSchema: z.ZodObject<{
                         number: "number";
                         boolean: "boolean";
                     }>>;
+                    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 }, z.core.$strip>>>;
                 request: z.ZodOptional<z.ZodObject<{
                     method: z.ZodEnum<{
@@ -87,7 +89,7 @@ export declare const ManifestSchema: z.ZodObject<{
                 path: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     targets: z.ZodArray<z.ZodEnum<{
         "norsk-ctl": "norsk-ctl";
         "docker-compose": "docker-compose";
@@ -110,4 +112,9 @@ export declare const ManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Manifest = z.infer<typeof ManifestSchema>;
+/** Producer-facing shape: everything the reader defaults is optional, so a
+ *  product's buildManifest() sends only what it actually declares instead of
+ *  `sidebarEntries: []`-style boilerplate. The parsed {@link Manifest} keeps
+ *  those fields present, so runner code needs no null-guards. */
+export type ManifestInput = z.input<typeof ManifestSchema>;
 export {};

package/manifest-schema.js

@@ -31,6 +31,9 @@ const CliFlagSchema = z.object({
     description: z.string(),
     required: z.boolean().optional(),
     type: z.enum(["string", "number", "boolean"]).optional(),
+    choices: z.array(z.string()).optional().meta({
+        description: "Allowed values for the flag. The runner's CLI rejects anything else and lists them in help output. Omit for free-form flags.",
+    }),
 });
 /** How a CLI leaf forwards to the product's HTTP surface. The runner registers
  *  a yargs command that issues `method` against `/products/<name><path>` (the
@@ -106,8 +109,11 @@ export const ManifestSchema = z.object({
             description: "Path on the product control-plane's HTTP surface where it serves an always-on, instance-independent MCP endpoint (e.g. plugin scaffolding). Proxied as `<product>_<tool>`. Distinct from the per-instance `mcpPath`. Omit for products without one.",
         }),
     }),
-    ui: z.object({
-        configScreenUrl: z.string(),
+    ui: z
+        .object({
+        configScreenUrl: z.string().optional().meta({
+            description: "URL (on the product's HTTP surface) of the configure screen the runner iframes to build product templates. Omit for backend-only products with no configure UI — the runner skips its registration probe and the UI offers a config-free build path instead of an iframe.",
+        }),
         // Optional rich instance-launch config screen. When present, the runner's
         // launch flow probes it (a GET carrying product-template context); the
         // product returns 200 to have the runner iframe it in place of the
@@ -121,10 +127,13 @@ export const ManifestSchema = z.object({
         sidebarEntries: z.array(SidebarEntrySchema).default([]),
         dashboardWidgets: z.array(DashboardWidgetSchema).default([]),
         productTemplateActions: z.array(ProductTemplateActionSchema).default([]),
-    }),
-    cli: z.object({
+    })
+        .default({ sidebarEntries: [], dashboardWidgets: [], productTemplateActions: [] }),
+    cli: z
+        .object({
         subcommandTree: z.array(CliCommandSchema).default([]),
-    }),
+    })
+        .default({ subcommandTree: [] }),
     targets: z.array(TargetSchema),
     components: z.array(ComponentDescSchema).default([]),
     runtime: RuntimeHintsSchema,

package/manifest-seed.d.ts

@@ -26,3 +26,5 @@ export declare const SeedSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, z.core.$strict>>;
 export type ManifestSeed = z.infer<typeof SeedSchema>;
 export declare function parseManifestSeed(raw: unknown): Result<ManifestSeed, string>;
+export declare const bareTag: (ref: string) => string;
+export declare const repoOf: (ref: string) => string;

package/manifest-seed.js

@@ -38,3 +38,8 @@ export function parseManifestSeed(raw) {
     const parsed = SeedSchema.safeParse(raw);
     return parsed.success ? ok(parsed.data) : err(z.prettifyError(parsed.error));
 }
+// The seed carries FULL repo:tag refs; every product's version.ts splits them
+// into the uniform MEDIA_*/STUDIO_* vocabulary (RFC 0001 §5). Split on the
+// LAST colon so registry:port refs keep the port on the repo side.
+export const bareTag = (ref) => ref.slice(ref.lastIndexOf(":") + 1);
+export const repoOf = (ref) => ref.slice(0, ref.lastIndexOf(":"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "exports": {
     ".": {

package/product-template-error.d.ts

@@ -5,6 +5,6 @@
  * path (used by mgr — name validation + bytes persistence).
  */
 export declare class ProductTemplateError extends Error {
-    code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE";
-    constructor(code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE", message: string);
+    code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE" | "PRODUCT_MISMATCH";
+    constructor(code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE" | "PRODUCT_MISMATCH", message: string);
 }

package/proxy-middleware.js

@@ -1,48 +1,11 @@
 import { logger } from "@norskvideo/ctl-foundation";
-const HOP_BY_HOP = new Set([
-    "connection",
-    "keep-alive",
-    "proxy-authenticate",
-    "proxy-authorization",
-    "te",
-    "trailers",
-    "transfer-encoding",
-    "upgrade",
-    "host",
-    "content-length",
-]);
+import { buildForwardHeaders, forwardUpstreamResponse, readRequestBody } from "./http-proxy.js";
 function targetBaseUrl(reg) {
     if (reg.spec.kind === "container") {
         return reg.port !== undefined ? `http://127.0.0.1:${reg.port}` : null;
     }
     return reg.spec.url.replace(/\/$/, "");
 }
-function buildOutgoingHeaders(req) {
-    const out = {};
-    for (const [key, value] of Object.entries(req.headers)) {
-        if (HOP_BY_HOP.has(key.toLowerCase()))
-            continue;
-        if (value === undefined)
-            continue;
-        out[key] = Array.isArray(value) ? value.join(", ") : value;
-    }
-    return out;
-}
-async function readRequestBody(req) {
-    if (req.method === "GET" || req.method === "HEAD")
-        return undefined;
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
-        req.on("end", () => {
-            if (!chunks.length)
-                return resolve(undefined);
-            const buf = Buffer.concat(chunks);
-            resolve(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
-        });
-        req.on("error", reject);
-    });
-}
 export function createProductProxyMiddleware(svc) {
     return async (req, res, next) => {
         const name = req.params.name;
@@ -60,7 +23,7 @@ export function createProductProxyMiddleware(svc) {
             return;
         }
         const targetUrl = `${base}${req.url}`;
-        const headers = buildOutgoingHeaders(req);
+        const headers = buildForwardHeaders(req);
         const body = await readRequestBody(req);
         let upstream;
         try {
@@ -76,37 +39,13 @@ export function createProductProxyMiddleware(svc) {
             res.status(502).json({ status: "error", message: `upstream fetch failed: ${String(e)}` });
             return;
         }
-        res.status(upstream.status);
         const productPrefix = `/products/${encodeURIComponent(name)}`;
-        upstream.headers.forEach((value, key) => {
-            const lower = key.toLowerCase();
-            if (HOP_BY_HOP.has(lower))
-                return;
+        await forwardUpstreamResponse(res, upstream, {
             // Rewrite root-absolute redirect Locations so 3xx responses don't
             // escape the product prefix and land on the runner SPA. Relative
             // (non-/-prefixed) and full-URL Locations pass through unchanged.
-            if (lower === "location" && value.startsWith("/") && !value.startsWith("//")) {
-                res.setHeader(key, `${productPrefix}${value}`);
-                return;
-            }
-            res.setHeader(key, value);
+            rewriteHeader: (key, value) => key === "location" && value.startsWith("/") && !value.startsWith("//") ? `${productPrefix}${value}` : value,
+            onStreamError: (e) => logger.warn(`Proxy stream from ${targetUrl} broke: ${String(e)}`),
         });
-        if (!upstream.body) {
-            res.end();
-            return;
-        }
-        const reader = upstream.body.getReader();
-        try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                res.write(value);
-            }
-        }
-        catch (e) {
-            logger.warn(`Proxy stream from ${targetUrl} broke: ${String(e)}`);
-        }
-        res.end();
     };
 }

package/route-error.d.ts

@@ -0,0 +1,12 @@
+import type { Response } from "express";
+export type RouteErrorClassification = {
+    status: number;
+    error: string;
+};
+export type RouteErrorClassifier = (err: unknown) => RouteErrorClassification | undefined;
+export declare function sendRouteError(res: Response, err: unknown, fallbackError: string, classify?: RouteErrorClassifier): void;
+/** Run a route body, mapping any throw or rejection to the error shape above.
+ *  `fallbackError` is the route's stable failure label (e.g.
+ *  "product-template generation failed"); `classify` upgrades known error
+ *  classes to their own status + label (e.g. a seed error to a 400). */
+export declare function guardRoute(res: Response, fallbackError: string, fn: () => void | Promise<void>, classify?: RouteErrorClassifier): void;

package/route-error.js

@@ -0,0 +1,26 @@
+export function sendRouteError(res, err, fallbackError, classify) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    const classified = classify?.(err);
+    res.status(classified?.status ?? 500).json({
+        error: classified?.error ?? fallbackError,
+        message: err instanceof Error ? err.message : String(err),
+    });
+}
+/** Run a route body, mapping any throw or rejection to the error shape above.
+ *  `fallbackError` is the route's stable failure label (e.g.
+ *  "product-template generation failed"); `classify` upgrades known error
+ *  classes to their own status + label (e.g. a seed error to a 400). */
+export function guardRoute(res, fallbackError, fn, classify) {
+    try {
+        const out = fn();
+        if (out instanceof Promise) {
+            out.catch((err) => sendRouteError(res, err, fallbackError, classify));
+        }
+    }
+    catch (err) {
+        sendRouteError(res, err, fallbackError, classify);
+    }
+}

package/sse.d.ts

@@ -0,0 +1,12 @@
+import type { Request, RequestHandler } from "express";
+export type PollingSseOptions<T> = {
+    /** Produce one snapshot for one client tick. Receives the request so the
+     *  upstream can be addressed per-request (e.g. ?studioBase=). A throw or
+     *  rejection is swallowed; the next tick retries. */
+    snapshot: (req: Request) => T | Promise<T>;
+    /** Time between frames. Defaults to 1s (funke's STREAM_INTERVAL_MS). */
+    intervalMs?: number;
+};
+/** SSE feed: emit a `data: <json>` frame immediately, then every intervalMs
+ *  until the client disconnects. */
+export declare function createPollingSseHandler<T>(opts: PollingSseOptions<T>): RequestHandler;

package/sse.js

@@ -0,0 +1,42 @@
+// Polling Server-Sent-Events bridge, lifted from funke's /api/metrics/stream.
+//
+// Why SSE and not a proxied WebSocket: bun's node:http "upgrade" socket is not
+// writable back to the client, so neither a hand-rolled raw-socket bridge nor
+// http-proxy's .ws() can forward the 101 in-process. A product backend that
+// needs an upstream WS feed (e.g. Studio's /live/firehose) therefore consumes
+// it as a CLIENT and re-emits snapshots same-origin over SSE — a plain
+// long-lived GET that also rides existing /api/* reverse-proxy locations with
+// no Upgrade handshake and no new dependency.
+/** SSE feed: emit a `data: <json>` frame immediately, then every intervalMs
+ *  until the client disconnects. */
+export function createPollingSseHandler(opts) {
+    const intervalMs = opts.intervalMs ?? 1000;
+    return (req, res) => {
+        res.set({
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+        });
+        res.flushHeaders?.();
+        let closed = false;
+        const tick = async () => {
+            if (closed)
+                return;
+            try {
+                const value = await opts.snapshot(req);
+                if (!closed)
+                    res.write(`data: ${JSON.stringify(value)}\n\n`);
+            }
+            catch {
+                // Transient upstream failures are swallowed; the next tick retries.
+            }
+        };
+        void tick();
+        const timer = setInterval(() => void tick(), intervalMs);
+        req.on("close", () => {
+            closed = true;
+            clearInterval(timer);
+            res.end();
+        });
+    };
+}

package/workflow.d.ts

@@ -39,6 +39,14 @@ export declare const VIDEO_ONLY: SubscriptionStreams;
 export declare const AUDIO_ONLY: SubscriptionStreams;
 export declare const FIRST_VIDEO: SubscriptionStreams;
 export declare const FIRST_AUDIO: SubscriptionStreams;
+export type ComponentAdder<Handle> = {
+    addNode(identifier: string, config: never): Handle;
+};
+export declare function addComponent<Handle, C extends object>(builder: ComponentAdder<Handle>, component: WorkflowComponent<C>): Handle;
+export type DocumentSource = {
+    toDocument(): unknown;
+};
+export declare function toWorkflowDoc<D extends WorkflowDoc = WorkflowDoc>(builder: DocumentSource): D;
 export type SyntheticNodeInfo = {
     identifier: string;
     subscription: {
@@ -57,4 +65,36 @@ export type SyntheticNodeInfo = {
         };
     };
 };
+export type ComponentStubMedia = "video" | "audio" | "subtitle" | "ancillary" | "playlist";
+export type ComponentStubSpec = {
+    identifier: string;
+    accepts?: ComponentStubMedia[];
+    produces?: ComponentStubMedia[] | "passthrough";
+    acceptsTransient?: boolean;
+    validateConfig?: (config: Record<string, unknown>) => string[] | undefined;
+};
+type StubMediaFlags = {
+    [M in ComponentStubMedia]?: true;
+};
+export type StubNodeInfo = {
+    identifier: string;
+    subscription: {
+        accepts?: {
+            type: "simple-stream";
+            acceptsTransient: boolean;
+        } & StubMediaFlags;
+        produces?: ({
+            type: "simple-stream";
+        } & StubMediaFlags) | {
+            type: "dynamic-streams";
+            streams: <S>(cfg: unknown, inputStreams: S) => S;
+        };
+    };
+    validateConfig?: (config: Record<string, unknown>) => string[] | undefined;
+};
+export declare function stubNodeInfo<T = StubNodeInfo>(spec: ComponentStubSpec): T;
+export declare function stubbedLibrary<Info = StubNodeInfo>(find: (identifier: string) => Info | undefined, stubs: ComponentStubSpec[]): {
+    find(identifier: string): Info | undefined;
+};
 export declare function syntheticInfo<T = SyntheticNodeInfo>(identifier: string): T;
+export {};

package/workflow.js

@@ -26,6 +26,76 @@ export const FIRST_AUDIO = {
     type: "take-first-stream",
     filter: [{ media: "audio" }],
 };
+// Typed `addNode` boundary: adds a factory-built component to a WorkflowBuilder
+// with the factory's config typing intact, so composers need no `config as
+// never` at the add boundary. Subscriptions are NOT applied — wiring goes
+// through the builder's connect()/pick* helpers, exactly as every product's
+// local add() helper behaved. The single cast below is the one audited erasure:
+// the builder's `BaseConfig` constraint wants an index signature that interface-
+// declared product configs may lack, while the real gates stay intact — the
+// factory return type checks the config shape at construction, and
+// builder.validate() runs each node's real validateConfig at compose time.
+export function addComponent(builder, component) {
+    return builder.addNode(component.type, component.config);
+}
+// Typed `toDocument` boundary: the builder returns its all-optional YamlDocument
+// shape, which products immediately re-assert as their WorkflowDoc (previously
+// via `as unknown as WorkflowDoc` at every call site). Sound by construction:
+// the builder always emits a components array, and each entry carries the
+// type/config/subscriptions the composer added. Pass a product-extended doc
+// type (e.g. probe's signed document) as `D` when the product adds fields.
+export function toWorkflowDoc(builder) {
+    return builder.toDocument();
+}
+function mediaFlags(media) {
+    return Object.fromEntries(media.map((m) => [m, true]));
+}
+// A builder NodeInfo from a metadata-only stub declaration. Unlike
+// syntheticInfo's accept-anything fallback, the resulting info carries the
+// component's REAL media contract, so edges into and out of the stub
+// stream-validate like any built-in (only its config stays unvalidated unless
+// the spec supplies validateConfig).
+export function stubNodeInfo(spec) {
+    const accepts = spec.accepts
+        ? {
+            accepts: {
+                type: "simple-stream",
+                ...mediaFlags(spec.accepts),
+                acceptsTransient: spec.acceptsTransient ?? true,
+            },
+        }
+        : {};
+    const produces = spec.produces === "passthrough"
+        ? {
+            produces: {
+                type: "dynamic-streams",
+                streams: (_cfg, inputStreams) => inputStreams,
+            },
+        }
+        : spec.produces && spec.produces.length > 0
+            ? { produces: { type: "simple-stream", ...mediaFlags(spec.produces) } }
+            : {};
+    return {
+        identifier: spec.identifier,
+        subscription: { ...accepts, ...produces },
+        ...(spec.validateConfig ? { validateConfig: spec.validateConfig } : {}),
+    };
+}
+// A ComponentLibrary that resolves the real library first and declared stubs
+// second — and, crucially, NOTHING else: an identifier that is neither real nor
+// declared stays unresolved, so the builder's addNode throws on it instead of
+// silently composing against a permissive synthetic. This is what lets
+// builder.validate() be a throwing gate fleet-wide — every node is either a
+// real NodeInfo or an explicitly declared stub, and a typo fails the compose.
+export function stubbedLibrary(find, stubs) {
+    const stubInfos = new Map();
+    for (const spec of stubs) {
+        if (stubInfos.has(spec.identifier))
+            throw new Error(`duplicate component stub: ${spec.identifier}`);
+        stubInfos.set(spec.identifier, stubNodeInfo(spec));
+    }
+    return { find: (identifier) => find(identifier) ?? stubInfos.get(identifier) };
+}
 // A permissive builder NodeInfo for an identifier the real component library
 // does not know (a product's own component, or an alpha/custom node that lives
 // only in the running studio image). It accepts any media and PASSES INPUT