@norskvideo/ctl-sdk 0.1.0

package/license-v2.js

@@ -0,0 +1,205 @@
+import crypto from "node:crypto";
+/**
+ * Norsk Licensing V2 (per-product licenses).
+ *
+ * A V2 license file is a detached-signature envelope
+ * `{format, payload: base64, signature: base64}` where the signature is
+ * RSASSA-PKCS1-v1.5/SHA-256 by the Norsk root key over the exact payload
+ * bytes. The payload grants a list of per-product entitlements
+ * (product name + imageRef + versionConstraint + expiry).
+ *
+ * Anything that is NOT a V2 envelope — today's V1 license JSON, the
+ * "aws"/"gcp" marketplace sentinels, license archives — classifies as
+ * `legacy`. Classification is not acceptance: registration rejects `legacy`
+ * (see `notV2EnvelopeMessage`), while other readers — the CI expiry
+ * classifier, for one — still legitimately read V1 files. The kind survives
+ * precisely so "not an envelope at all" stays distinguishable from "envelope
+ * that failed verification"; the two send an operator to different remedies.
+ *
+ * One trust anchor is embedded: the production root key. A license may
+ * self-declare `nonProduction: true` (still production-signed) which warrants a
+ * "not for production" warning — it is not a separate trust anchor.
+ */
+export const LICENSE_V2_FORMAT = "norsk-license-v2";
+/**
+ * Wording for a readable file that is not a V2 envelope. Split rather than
+ * frozen because each door that rejects one needs its own middle clause while
+ * the diagnosis and the remedy must not drift between them: `add` says "at
+ * registration" (which also tells the operator their existing registrations
+ * still launch), renewal will say something else.
+ *
+ * Leads with "not a V2 envelope" deliberately — the same message fires for a
+ * path typo pointing at an HTML page or a truncated download, and those must
+ * not be misdiagnosed as "you have a V1 license".
+ */
+export function notV2EnvelopeMessage(doorClause) {
+    return `this file is not a V2 license envelope (${doorClause}) — contact Norsk support for a reissued license`;
+}
+const PROD_ROOT_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA02CiAbYusGEEH+tmyD7l
+7su7nrIaU5HozRgMHUDpGGm6qkIstp5pItMop1s0hPYdXTArgCHhdqh77uuj5szv
+9AmH/hb0amvI+OQmsaVRFRM/YgFlwICDlMP1JLiLZP4RcOrSRwW0m8qY5/KiOqZQ
+GG2KcOftzILklGYSxqAXxQu1UpAUZIRpZCuJ5wP3zQw7JASvLU0k4lO7yG2tcbLE
+GpFw4c1naB0X16QxjC6lTFIYzJqIfJFWRERiJXekJidd27TZUWlFpXSxrgs15glk
+0/c61JwraAEAOOrWXY+NXhS4SLoZdsFZOsCtSGyrmx9mMK8Jttr5MgwHuQRCMUL+
+lFlOPPYYqaGGWbpnirSVKmUhxz//U0AC+abI8OSXsgAMqIB6qMCp/204feIdDjXb
+XJWxIF4wpPVTNurMZI0Rk0SYTKYpJPRuIdvSmquzOzRVhOzk36wgVNSivTDqAeGu
++4Jvb7yz87dv0hr4Fgp/OyYJ6bPRgg2c5sLGsOtlmn1XGC/hVYKQMRz/jq7l+so1
+dq3LLYQUwcg+ykVPCBUr1J+dA/pq5iwp8xDRPzNFOUPmWBFLVhB4GxXhhs1NToBM
+iytt46G/OmI2uxfkesdj+WnYURWjyUNVe/DZpfxqz3hXv0Q6dM8cJoRY5ye5c8eA
+BAx1vUsggiexa49aSFttEKECAwEAAQ==
+-----END PUBLIC KEY-----`;
+export function parseLicenseContents(contents) {
+    let envelope;
+    try {
+        envelope = JSON.parse(contents);
+    }
+    catch {
+        return { kind: "legacy" };
+    }
+    if (typeof envelope !== "object" || envelope === null || envelope.format !== LICENSE_V2_FORMAT) {
+        return { kind: "legacy" };
+    }
+    const { payload, signature } = envelope;
+    if (typeof payload !== "string" || typeof signature !== "string") {
+        return { kind: "invalid-v2", reason: "malformed envelope" };
+    }
+    const payloadBytes = Buffer.from(payload, "base64");
+    const signatureBytes = Buffer.from(signature, "base64");
+    if (!crypto.verify("sha256", payloadBytes, PROD_ROOT_PUBLIC_KEY_PEM, signatureBytes)) {
+        return { kind: "invalid-v2", reason: "license signature is invalid" };
+    }
+    let license;
+    try {
+        license = JSON.parse(payloadBytes.toString("utf-8"));
+    }
+    catch {
+        return { kind: "invalid-v2", reason: "license payload is not valid JSON" };
+    }
+    if (license.version !== 2 || !Array.isArray(license.products)) {
+        return { kind: "invalid-v2", reason: "license payload is not a V2 license" };
+    }
+    return { kind: "v2", license };
+}
+/** How a product entry's image resolves, for previewing before an add. The
+ *  licence carries a repo + versionConstraint but no tag: an exact version or
+ *  sha256 digest is fixed (not editable); a caret range / * / no constraint
+ *  defaults to `latest` and the tag is free to edit (a caret still has to stay
+ *  in band, enforced at add time). */
+export function describeProductImage(entry) {
+    const c = entry.versionConstraint;
+    if (c?.startsWith("sha256:"))
+        return { image: `${entry.imageRef}@${c}`, tag: c, editable: false };
+    if (c && c !== "*" && !c.startsWith("^"))
+        return { image: `${entry.imageRef}:${c}`, tag: c, editable: false };
+    return { image: `${entry.imageRef}:latest`, tag: "latest", editable: true };
+}
+/** Split `repo[:tag][@digest]`; a ':' only separates the tag when it appears
+ *  after the last '/' (registry hosts can carry ports). */
+export function parseImageRef(ref) {
+    const at = ref.indexOf("@");
+    const digest = at === -1 ? undefined : ref.slice(at + 1);
+    const repoAndTag = at === -1 ? ref : ref.slice(0, at);
+    const colon = repoAndTag.lastIndexOf(":");
+    if (colon > repoAndTag.lastIndexOf("/")) {
+        return { repo: repoAndTag.slice(0, colon), tag: repoAndTag.slice(colon + 1), digest };
+    }
+    return { repo: repoAndTag, digest };
+}
+function parseVersion(s) {
+    const segments = s.split(".");
+    // strict integer segments only; anything else (e.g. "1.2.3-beta") fails closed
+    if (segments.length === 0 || segments.some((p) => !/^\d+$/.test(p)))
+        return undefined;
+    return segments.map((p) => Number.parseInt(p, 10));
+}
+/** Same semantics as the engine's matcher: `*` (or absent) accepts any tag;
+ *  `sha256:...` pins the digest; `^x[.y[.z]]` is a caret semver range over
+ *  the tag; anything else is an exact tag match. Unparseable tags against a
+ *  semver constraint fail closed. */
+export function imageRefMatches(entry, presented) {
+    const parsed = parseImageRef(presented);
+    if (parsed.repo !== entry.imageRef)
+        return false;
+    const constraint = entry.versionConstraint ?? "*";
+    if (constraint === "*")
+        return true;
+    if (constraint.startsWith("sha256:"))
+        return parsed.digest === constraint;
+    if (constraint.startsWith("^")) {
+        if (parsed.tag === undefined)
+            return false;
+        const range = parseVersion(constraint.slice(1));
+        const tag = parseVersion(parsed.tag.replace(/^v/, ""));
+        if (!range || !tag)
+            return false;
+        const pad = (v) => [v[0] ?? 0, v[1] ?? 0, v[2] ?? 0];
+        const [tMaj, tMin, tPat] = pad(tag);
+        const [rMaj, rMin, rPat] = pad(range);
+        if (tMaj !== rMaj)
+            return false;
+        if (tMin !== rMin)
+            return tMin > rMin;
+        return tPat >= rPat;
+    }
+    return parsed.tag === constraint;
+}
+/** Does this V2 license entitle `productName`, optionally pinned to the
+ *  container image being registered? */
+export function checkProductEntitlement(parsed, productName, imageRef, now = new Date()) {
+    const { license } = parsed;
+    const warnings = [];
+    if (license.nonProduction === true) {
+        warnings.push("license is marked NON-PRODUCTION — not valid for production deployments");
+    }
+    // License-level expiry gates the whole license, exactly as the engine
+    // rejects an expired license at boot — a future per-entry expiry must not
+    // mask a past license-level expiry.
+    const licenseExpiry = parseExpiry(license.expiry);
+    if (licenseExpiry === "invalid") {
+        return { ok: false, reason: `license has an unparseable expiry '${license.expiry}'` };
+    }
+    if (licenseExpiry !== undefined && licenseExpiry.getTime() <= now.getTime()) {
+        return { ok: false, reason: `license expired at ${license.expiry}` };
+    }
+    const candidates = license.products.filter((p) => p.product === productName);
+    if (candidates.length === 0) {
+        const listed = license.products.map((p) => p.product).join(", ") || "none";
+        return { ok: false, reason: `license has no entry for product '${productName}' (licensed products: ${listed})` };
+    }
+    // A license may carry several entries for one product (e.g. a renewal beside
+    // an old entry). Accept if ANY entry authorises this image and is unexpired;
+    // surface the first entry's reason only when none do.
+    const checkEntry = (entry) => {
+        const entryExpiry = parseExpiry(entry.expiresAt);
+        if (entryExpiry === "invalid") {
+            return { ok: false, reason: `license entry for '${productName}' has an unparseable expiry '${entry.expiresAt}'` };
+        }
+        if (entryExpiry !== undefined && entryExpiry.getTime() <= now.getTime()) {
+            return { ok: false, reason: `license entry for '${productName}' expired at ${entry.expiresAt}` };
+        }
+        if (imageRef !== undefined && !imageRefMatches(entry, imageRef)) {
+            return {
+                ok: false,
+                reason: `image '${imageRef}' does not satisfy the licensed imageRef '${entry.imageRef}'` +
+                    ` (versionConstraint: ${entry.versionConstraint ?? "*"})`,
+            };
+        }
+        return { ok: true };
+    };
+    const accepted = candidates.find((e) => checkEntry(e).ok);
+    if (accepted) {
+        return { ok: true, entry: accepted, warnings };
+    }
+    // None matched — report the first candidate's specific failure.
+    const firstFailure = checkEntry(candidates[0]);
+    return { ok: false, reason: firstFailure.ok ? "no matching entry" : firstFailure.reason };
+}
+/** Parse an ISO expiry: `undefined` for absent, `"invalid"` for unparseable
+ *  (callers fail closed), else the Date. */
+function parseExpiry(value) {
+    if (value === undefined)
+        return undefined;
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? "invalid" : d;
+}

package/manifest-fetch.d.ts

@@ -0,0 +1,29 @@
+import { type Manifest } from "./manifest-schema.js";
+import type { ProductSpec } from "./product-types.js";
+/**
+ * Fast liveness probe for a registered product. A dev-mode product is
+ * externally owned, so the only way to know it's actually up is to ask it.
+ * GETs `/manifest.json` with a short timeout; any non-2xx, network error, or
+ * timeout reads as "not running". Deliberately cheap (single request, 3s cap)
+ * because it runs on the product-list render path.
+ */
+export declare function isDevUrlAlive(baseUrl: string): Promise<boolean>;
+export declare function specBaseUrl(spec: ProductSpec, port?: number): string;
+export declare function fetchManifest(baseUrl: string): Promise<Manifest>;
+export declare function waitForReady(baseUrl: string): Promise<void>;
+/**
+ * Probe the product's configScreenUrl after registration. Two hard
+ * rejections:
+ *   - CONFIG_SCREEN_UNREACHABLE: non-2xx after one redirect hop. Catches
+ *     typo'd URLs and manifests that lie about what's exposed.
+ *   - CONFIG_SCREEN_DEV_SERVER: response body has vite-dev fingerprints
+ *     (`/@vite/client`, `src="/src/...`). Iframed product UIs need the
+ *     built bundle — vite-dev paths are absolute on the product's origin
+ *     and resolve against the *runner's* origin once iframed, so the
+ *     wrong scripts load. Operators should register the backend port
+ *     that serves the production build.
+ *
+ * Soft warnings (future) would return via the unused return-value slot
+ * here. For now both detections are hard fails.
+ */
+export declare function probeConfigScreen(baseUrl: string, configScreenUrl: string): Promise<void>;

package/manifest-fetch.js

@@ -0,0 +1,100 @@
+import { ManifestSchema } from "./manifest-schema.js";
+import { ProductError } from "./product-error.js";
+const READINESS_TIMEOUT_MS = 60_000;
+const READINESS_INTERVAL_MS = 250;
+const LIVENESS_TIMEOUT_MS = 3_000;
+/**
+ * Fast liveness probe for a registered product. A dev-mode product is
+ * externally owned, so the only way to know it's actually up is to ask it.
+ * GETs `/manifest.json` with a short timeout; any non-2xx, network error, or
+ * timeout reads as "not running". Deliberately cheap (single request, 3s cap)
+ * because it runs on the product-list render path.
+ */
+export async function isDevUrlAlive(baseUrl) {
+    try {
+        const r = await fetch(`${baseUrl}/manifest.json`, { signal: AbortSignal.timeout(LIVENESS_TIMEOUT_MS) });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export function specBaseUrl(spec, port) {
+    if (spec.kind === "dev")
+        return spec.url.replace(/\/$/, "");
+    if (port === undefined)
+        throw new Error("container spec requires port");
+    return `http://127.0.0.1:${port}`;
+}
+export async function fetchManifest(baseUrl) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/manifest.json`);
+    }
+    catch (e) {
+        throw new ProductError("MANIFEST_FETCH_FAILED", `manifest fetch failed: ${String(e)}`);
+    }
+    if (!response.ok) {
+        throw new ProductError("MANIFEST_FETCH_FAILED", `manifest.json returned ${response.status}`);
+    }
+    const json = await response.json().catch(() => null);
+    const parsed = ManifestSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new ProductError("MANIFEST_INVALID", `manifest validation failed: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+export async function waitForReady(baseUrl) {
+    const deadline = Date.now() + READINESS_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            const r = await fetch(`${baseUrl}/manifest.json`);
+            if (r.ok)
+                return;
+        }
+        catch {
+            // not ready yet
+        }
+        await new Promise((resolve) => setTimeout(resolve, READINESS_INTERVAL_MS));
+    }
+    throw new ProductError("READINESS_TIMEOUT", `product did not become ready within ${READINESS_TIMEOUT_MS}ms`);
+}
+/**
+ * Probe the product's configScreenUrl after registration. Two hard
+ * rejections:
+ *   - CONFIG_SCREEN_UNREACHABLE: non-2xx after one redirect hop. Catches
+ *     typo'd URLs and manifests that lie about what's exposed.
+ *   - CONFIG_SCREEN_DEV_SERVER: response body has vite-dev fingerprints
+ *     (`/@vite/client`, `src="/src/...`). Iframed product UIs need the
+ *     built bundle — vite-dev paths are absolute on the product's origin
+ *     and resolve against the *runner's* origin once iframed, so the
+ *     wrong scripts load. Operators should register the backend port
+ *     that serves the production build.
+ *
+ * Soft warnings (future) would return via the unused return-value slot
+ * here. For now both detections are hard fails.
+ */
+export async function probeConfigScreen(baseUrl, configScreenUrl) {
+    const path = configScreenUrl.startsWith("/") ? configScreenUrl : `/${configScreenUrl}`;
+    const url = `${baseUrl}${path}`;
+    let response;
+    try {
+        response = await fetch(url, { redirect: "follow" });
+    }
+    catch (e) {
+        throw new ProductError("CONFIG_SCREEN_UNREACHABLE", `configScreenUrl '${path}' at ${baseUrl} unreachable: ${String(e)}`);
+    }
+    if (!response.ok) {
+        throw new ProductError("CONFIG_SCREEN_UNREACHABLE", `configScreenUrl '${path}' returned ${response.status}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.toLowerCase().includes("text/html")) {
+        const body = await response.text().catch(() => "");
+        if (body.includes("/@vite/client") || /\bsrc="\/src\//.test(body)) {
+            throw new ProductError("CONFIG_SCREEN_DEV_SERVER", `configScreenUrl '${path}' at ${baseUrl} appears to be served by a ` +
+                `vite dev server. Iframed product UIs need the built bundle — ` +
+                `register the backend port that serves the production build, not ` +
+                `the vite dev port.`);
+        }
+    }
+}

package/manifest-router.d.ts

@@ -0,0 +1,11 @@
+import { Router } from "express";
+import type { Manifest } from "./manifest-schema.js";
+/**
+ * Serves a product's manifest at `GET /manifest.json`, relative to wherever the
+ * router is mounted.
+ *
+ * Unlike `createOpenapiRouter`, the manifest is NOT cached: the forked
+ * per-product code rebuilt it on every request, and this preserves that
+ * behaviour. Building a manifest is cheap, so per-request cost is negligible.
+ */
+export declare function createManifestRouter(buildManifest: () => Manifest): Router;

package/manifest-router.js

@@ -0,0 +1,16 @@
+import { Router } from "express";
+/**
+ * Serves a product's manifest at `GET /manifest.json`, relative to wherever the
+ * router is mounted.
+ *
+ * Unlike `createOpenapiRouter`, the manifest is NOT cached: the forked
+ * per-product code rebuilt it on every request, and this preserves that
+ * behaviour. Building a manifest is cheap, so per-request cost is negligible.
+ */
+export function createManifestRouter(buildManifest) {
+    const router = Router();
+    router.get("/manifest.json", (_req, res) => {
+        res.json(buildManifest());
+    });
+    return router;
+}

package/manifest-schema.d.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+/** Per-entry shape inside `defaultProductTemplates`. The runner fetches each URL
+ *  (resolved relative to the product's base) at registration time and
+ *  stores the returned product-template tar under `name`. Lets a product ship
+ *  pre-canned product templates so operators get a launchable instance without
+ *  visiting the configure screen — "add product, run it". */
+declare const DefaultProductTemplateSchema: z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+export type DefaultProductTemplate = z.infer<typeof DefaultProductTemplateSchema>;
+export declare const ManifestSchema: z.ZodObject<{
+    manifestSchemaVersion: z.ZodLiteral<1>;
+    name: z.ZodString;
+    version: z.ZodString;
+    minRunnerVersion: z.ZodOptional<z.ZodString>;
+    api: z.ZodObject<{
+        basePath: z.ZodString;
+        proxyPaths: z.ZodArray<z.ZodString>;
+        openapiFragmentPath: z.ZodString;
+        mcpPath: z.ZodOptional<z.ZodString>;
+        healthCheckPath: z.ZodDefault<z.ZodString>;
+        productMcpPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    ui: z.ZodObject<{
+        configScreenUrl: z.ZodString;
+        instanceConfigScreenUrl: z.ZodOptional<z.ZodString>;
+        sidebarEntries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            icon: z.ZodOptional<z.ZodString>;
+            route: z.ZodString;
+        }, z.core.$strip>>>;
+        dashboardWidgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strip>>>;
+        productTemplateActions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            configScreenUrl: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    cli: z.ZodObject<{
+        subcommandTree: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            flags: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                required: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodOptional<z.ZodEnum<{
+                    string: "string";
+                    number: "number";
+                    boolean: "boolean";
+                }>>;
+            }, z.core.$strip>>>;
+            subcommands: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                flags: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    description: z.ZodString;
+                    required: z.ZodOptional<z.ZodBoolean>;
+                    type: z.ZodOptional<z.ZodEnum<{
+                        string: "string";
+                        number: "number";
+                        boolean: "boolean";
+                    }>>;
+                }, z.core.$strip>>>;
+                request: z.ZodOptional<z.ZodObject<{
+                    method: z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                        PUT: "PUT";
+                        DELETE: "DELETE";
+                    }>;
+                    path: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+            request: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<{
+                    GET: "GET";
+                    POST: "POST";
+                    PUT: "PUT";
+                    DELETE: "DELETE";
+                }>;
+                path: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    targets: z.ZodArray<z.ZodEnum<{
+        "norsk-ctl": "norsk-ctl";
+        "docker-compose": "docker-compose";
+    }>>;
+    components: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>>;
+    runtime: z.ZodDefault<z.ZodObject<{
+        sharedWorkingDirectory: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    defaultProductTemplates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>>;
+    export: z.ZodOptional<z.ZodObject<{
+        include: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+export {};

package/manifest-schema.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+const TargetSchema = z.enum(["norsk-ctl", "docker-compose"]);
+const SidebarEntrySchema = z.object({
+    label: z.string(),
+    icon: z.string().optional(),
+    route: z.string(),
+});
+const DashboardWidgetSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    url: z.string(),
+});
+/** A product-specific entry point for building a particular kind of product
+ *  template (e.g. Studio's "Add dev template" / "Add examples"). The runner
+ *  renders one button per action on the product's hub; clicking opens the build
+ *  form at the action's `configScreenUrl`, so the product owns what each one
+ *  configures. */
+const ProductTemplateActionSchema = z.object({
+    label: z.string(),
+    configScreenUrl: z.string().meta({
+        description: "Config screen URL (on the product's HTTP surface) opened to build this kind of product template.",
+    }),
+});
+const ComponentDescSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+    description: z.string(),
+});
+const CliFlagSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    required: z.boolean().optional(),
+    type: z.enum(["string", "number", "boolean"]).optional(),
+});
+/** 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
+ *  product proxy resolves the rest), mapping flags to a JSON body for
+ *  POST/PUT or a query string for GET/DELETE. Absent on grouping commands
+ *  that only namespace subcommands. */
+const CliRequestSchema = z.object({
+    method: z.enum(["GET", "POST", "PUT", "DELETE"]),
+    path: z.string().meta({
+        description: "Instance-relative path on the product's HTTP surface (e.g. /api/plugins/create). The runner prefixes /products/<name>.",
+    }),
+});
+const CliLeafSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    flags: z.array(CliFlagSchema).default([]),
+    request: CliRequestSchema.optional(),
+});
+const CliCommandSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    flags: z.array(CliFlagSchema).default([]),
+    subcommands: z.array(CliLeafSchema).default([]),
+    request: CliRequestSchema.optional(),
+});
+/** Runtime hints from the product manifest. Drives launch-time validation
+ *  on instances launched from a product template — e.g. whether two instances
+ *  may share a working directory. Optional in v1 manifests; defaults are safe. */
+const RuntimeHintsSchema = z
+    .object({
+    sharedWorkingDirectory: z.boolean().default(false),
+})
+    .default({ sharedWorkingDirectory: false });
+/** Per-entry shape inside `defaultProductTemplates`. The runner fetches each URL
+ *  (resolved relative to the product's base) at registration time and
+ *  stores the returned product-template tar under `name`. Lets a product ship
+ *  pre-canned product templates so operators get a launchable instance without
+ *  visiting the configure screen — "add product, run it". */
+const DefaultProductTemplateSchema = z.object({
+    name: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]{0,62}$/, "product template name must be lowercase letters, digits, hyphens; 1-63 chars"),
+    url: z.string().meta({
+        description: "Path on the product's HTTP surface that returns the product-template tar. Resolved against the product's base URL — relative paths only (no scheme/host).",
+    }),
+});
+/** Save-as-product-template file selection. When the runner exports a running
+ *  instance's working directory into a new product template, it packs only files
+ *  matching `include` and not matching `exclude` (glob patterns, relative to the
+ *  working directory). Lets a product keep the built assets worth sharing
+ *  (workflow, compiled dashboards/components) and drop dev cruft (recordings,
+ *  node_modules) without the runner knowing the product's layout. */
+const ExportSchema = z.object({
+    include: z.array(z.string()).default([]),
+    exclude: z.array(z.string()).default([]),
+});
+export const ManifestSchema = z.object({
+    manifestSchemaVersion: z.literal(1),
+    name: z.string(),
+    version: z.string(),
+    minRunnerVersion: z.string().optional(),
+    api: z.object({
+        basePath: z.string(),
+        proxyPaths: z.array(z.string()),
+        openapiFragmentPath: z.string(),
+        mcpPath: z.string().optional().meta({
+            description: "Instance-relative path on the product's HTTP surface where it serves its MCP endpoint. Lets the proxy discover the MCP from product registration. Omit for products without an MCP.",
+        }),
+        healthCheckPath: z.string().default("/healthz").meta({
+            description: "Path on the product's HTTP surface the runner polls for liveness. The daemon's health monitor GETs it on an interval and auto-restarts the container after repeated failures. Defaults to /healthz, which the SDK product scaffold serves.",
+        }),
+        productMcpPath: z.string().optional().meta({
+            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(),
+        // 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
+        // auto-generated parameter form, or 204/404 to fall back to that form. Lets
+        // a product present a per-template launch UI (e.g. probe's wall layout
+        // designer) only where it applies, leaving other templates on the default
+        // form.
+        instanceConfigScreenUrl: z.string().optional().meta({
+            description: "Optional URL (on the product's HTTP surface) of a rich instance-launch config screen. Probed per product template: 200 = iframe it, 204/404 = use the default parameter form.",
+        }),
+        sidebarEntries: z.array(SidebarEntrySchema).default([]),
+        dashboardWidgets: z.array(DashboardWidgetSchema).default([]),
+        productTemplateActions: z.array(ProductTemplateActionSchema).default([]),
+    }),
+    cli: z.object({
+        subcommandTree: z.array(CliCommandSchema).default([]),
+    }),
+    targets: z.array(TargetSchema),
+    components: z.array(ComponentDescSchema).default([]),
+    runtime: RuntimeHintsSchema,
+    defaultProductTemplates: z.array(DefaultProductTemplateSchema).default([]).meta({
+        description: "Product templates the runner auto-fetches at product-registration time. Each entry is GET'd against the product's base URL and stored under its `name` via the runner's product-template store. Lets a product offer 'zero-config' launch paths — operators add the product and immediately have a launchable product template without visiting configure.",
+    }),
+    export: ExportSchema.optional(),
+});

package/manifest-seed.d.ts

@@ -0,0 +1,28 @@
+import { type Result } from "@norskvideo/ctl-foundation";
+import { z } from "zod";
+export declare const SourceSchema: z.ZodEnum<{
+    inherited: "inherited";
+    "nightly-baseline": "nightly-baseline";
+}>;
+export type Source = z.infer<typeof SourceSchema>;
+export declare const ChannelEntrySchema: z.ZodObject<{
+    media: z.ZodString;
+    studio: z.ZodString;
+    source: z.ZodEnum<{
+        inherited: "inherited";
+        "nightly-baseline": "nightly-baseline";
+    }>;
+    ratifiedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ChannelEntry = z.infer<typeof ChannelEntrySchema>;
+export declare const SeedSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    media: z.ZodString;
+    studio: z.ZodString;
+    source: z.ZodEnum<{
+        inherited: "inherited";
+        "nightly-baseline": "nightly-baseline";
+    }>;
+    ratifiedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type ManifestSeed = z.infer<typeof SeedSchema>;
+export declare function parseManifestSeed(raw: unknown): Result<ManifestSeed, string>;