@norskvideo/ctl-sdk 0.1.0

package/product-service.js

@@ -0,0 +1,340 @@
+import { readFile } from "node:fs/promises";
+import { logger } from "@norskvideo/ctl-foundation";
+import { validateDevUrl } from "./dev-url.js";
+import { dockerRename, dockerRm, dockerRun, productContainerName } from "./docker-runner.js";
+import { resolveLicenseFile } from "./license-registration.js";
+import { checkProductEntitlement, notV2EnvelopeMessage, parseLicenseContents } from "./license-v2.js";
+import { fetchManifest, isDevUrlAlive, probeConfigScreen, specBaseUrl, waitForReady } from "./manifest-fetch.js";
+import { ProductError } from "./product-error.js";
+/** GET a product-template tar from a product. `url` is whatever the manifest
+ *  declared; we treat it as a path on the product's HTTP surface and
+ *  resolve against the product's base URL. Returns the raw tar bytes,
+ *  or throws ProductError on any non-2xx / network failure. */
+async function fetchProductTemplateBytes(baseUrl, url) {
+    const full = `${baseUrl.replace(/\/$/, "")}/${url.replace(/^\//, "")}`;
+    let response;
+    try {
+        response = await fetch(full);
+    }
+    catch (e) {
+        throw new ProductError("PRODUCT_TEMPLATE_FETCH_FAILED", `fetch ${full} threw: ${String(e)}`);
+    }
+    if (!response.ok) {
+        throw new ProductError("PRODUCT_TEMPLATE_FETCH_FAILED", `${full} returned ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+const defaultContainerOps = {
+    run: dockerRun,
+    remove: dockerRm,
+    rename: dockerRename,
+    waitForReady,
+};
+export class ProductService {
+    store;
+    allocatePort;
+    importProductTemplateBytes;
+    stageLicense;
+    isDevUrlAlive;
+    containerOps;
+    constructor(opts) {
+        this.store = opts.store;
+        this.allocatePort = opts.allocatePort;
+        this.importProductTemplateBytes = opts.importProductTemplateBytes;
+        this.stageLicense = opts.stageLicense;
+        this.isDevUrlAlive = opts.isDevUrlAlive ?? isDevUrlAlive;
+        this.containerOps = opts.containerOps ?? defaultContainerOps;
+    }
+    list() {
+        return this.store.read();
+    }
+    /** Whether the product is actually up. Container-mode: we started it, so a
+     *  tracked containerId means running. Dev-mode: externally owned, so probe
+     *  the dev URL — registered no longer implies running. */
+    async isRunning(reg) {
+        if (reg.spec.kind === "container")
+            return reg.containerId !== undefined;
+        return this.isDevUrlAlive(specBaseUrl(reg.spec));
+    }
+    async add(spec, opts = {}) {
+        const existing = this.store.read();
+        let baseUrl;
+        let port;
+        let containerId;
+        if (spec.kind === "dev") {
+            validateDevUrl(spec.url);
+            baseUrl = specBaseUrl(spec);
+        }
+        else {
+            const portMap = {};
+            for (const p of existing)
+                if (p.port !== undefined)
+                    portMap[p.name] = { port: p.port };
+            const allocated = this.allocatePort(portMap);
+            if (allocated === null) {
+                throw new ProductError("PORT_EXHAUSTED", `no free port available for new product`);
+            }
+            port = allocated;
+            logger.info(`Starting product container: ${spec.image} on host port ${port}`);
+            containerId = await dockerRun(spec.image, port);
+            baseUrl = specBaseUrl(spec, port);
+        }
+        try {
+            await waitForReady(baseUrl);
+        }
+        catch (e) {
+            if (containerId)
+                await dockerRm(containerId);
+            throw e;
+        }
+        const manifest = await fetchManifest(baseUrl).catch(async (e) => {
+            if (containerId)
+                await dockerRm(containerId);
+            throw e;
+        });
+        if (existing.some((p) => p.name === manifest.name)) {
+            if (containerId)
+                await dockerRm(containerId);
+            throw new ProductError("NAME_CONFLICT", `product '${manifest.name}' already registered`);
+        }
+        const warnings = [];
+        // Licensing V2: a per-product license file must actually entitle this
+        // product (name + image ref/version + expiry, root signature). Anything
+        // that isn't a V2 envelope — a V1 license, marketplace sentinel, or
+        // archive — is rejected here rather than left to the engine, where a
+        // container refusing to boot is the worst place to discover it.
+        // Stage first, so everything below — validation and the recorded path —
+        // refers to the copy the daemon owns rather than the operator's argument.
+        let licenseFile = opts.license?.mode === "byol" ? opts.license.file : undefined;
+        if (opts.license?.mode === "byol") {
+            const resolved = resolveLicenseFile(opts.license.file, this.stageLicense);
+            licenseFile = resolved.file;
+            if (resolved.fatal) {
+                if (containerId)
+                    await dockerRm(containerId);
+                throw new ProductError("LICENSE_INVALID", resolved.fatal);
+            }
+            if (resolved.warning)
+                warnings.push(resolved.warning);
+        }
+        if (opts.license?.mode === "byol") {
+            // Read is best-effort: the license file lives wherever the operator put
+            // it, and the daemon runs unprivileged — a file readable by docker (root,
+            // which mounts it as a compose secret at launch) but not by us must NOT
+            // block registration, or we'd regress an install shape that works today.
+            // Bytes we cannot read cannot be classified as V1 or V2, so an
+            // unreadable file registers unvalidated behind a loud warning and the
+            // engine has the last word — the one remaining route by which non-V2
+            // bytes can reach a registration.
+            let contents;
+            try {
+                contents = await readFile(licenseFile, "utf-8");
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                warnings.push(`could not read license file '${licenseFile}' (${msg}); it was not validated at registration — if it is a V1 license the engine will reject it at launch; contact Norsk support for a reissued license`);
+            }
+            const parsed = contents !== undefined ? parseLicenseContents(contents) : undefined;
+            if (parsed?.kind === "invalid-v2") {
+                if (containerId)
+                    await dockerRm(containerId);
+                throw new ProductError("LICENSE_INVALID", parsed.reason);
+            }
+            if (parsed?.kind === "legacy") {
+                if (containerId)
+                    await dockerRm(containerId);
+                throw new ProductError("LICENSE_INVALID", notV2EnvelopeMessage("V1 licenses are no longer accepted at registration"));
+            }
+            if (parsed?.kind === "v2") {
+                const check = checkProductEntitlement(parsed, manifest.name, spec.kind === "container" ? spec.image : undefined);
+                if (!check.ok) {
+                    if (containerId)
+                        await dockerRm(containerId);
+                    throw new ProductError("LICENSE_INVALID", check.reason);
+                }
+                warnings.push(...check.warnings);
+            }
+        }
+        // Now that the manifest name is known and unique, give the container a
+        // stable, human-readable name (replacing docker's random alias). Tracked
+        // by id, so a rename failure is harmless — hence best-effort.
+        if (containerId)
+            await dockerRename(containerId, productContainerName(manifest.name));
+        // Sanity-probe the config screen so we catch (a) URLs that don't
+        // serve anything at the manifest-declared path, and (b) the common
+        // "registered the vite dev port" mistake — both are hard rejections
+        // because iframed product UIs need the built bundle to function.
+        if (manifest.ui?.configScreenUrl) {
+            try {
+                await probeConfigScreen(baseUrl, manifest.ui.configScreenUrl);
+            }
+            catch (e) {
+                if (containerId)
+                    await dockerRm(containerId);
+                throw e;
+            }
+        }
+        const registration = {
+            name: manifest.name,
+            spec,
+            addedAt: new Date().toISOString(),
+            manifest,
+            ...(port !== undefined ? { port } : {}),
+            ...(containerId !== undefined ? { containerId } : {}),
+            ...(opts.license !== undefined
+                ? {
+                    license: opts.license.mode === "byol" && licenseFile !== undefined
+                        ? { ...opts.license, file: licenseFile }
+                        : opts.license,
+                }
+                : {}),
+        };
+        await this.store.update((products) => [...products, registration]);
+        logger.info(`Product '${manifest.name}' registered (${spec.kind})`);
+        // defaultProductTemplates: fetch each declared URL relative to the
+        // product's base and hand the bytes to the host's product-template store.
+        // Failures here are downgraded to warnings rather than rolling back
+        // the registration — the product itself is healthy; a flaky default
+        // product template just means the operator visits configure as usual.
+        // Hosts that don't accept product templates (no importProductTemplateBytes
+        // callback) silently skip the whole block.
+        if (manifest.defaultProductTemplates.length > 0 && this.importProductTemplateBytes) {
+            for (const entry of manifest.defaultProductTemplates) {
+                try {
+                    const bytes = await fetchProductTemplateBytes(baseUrl, entry.url);
+                    await this.importProductTemplateBytes({
+                        name: entry.name,
+                        bytes,
+                        source: { kind: "product-default", productName: manifest.name, url: entry.url },
+                    });
+                    logger.info(`Product '${manifest.name}': stored default product template '${entry.name}' from ${entry.url}`);
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    const warning = `default product template '${entry.name}' from ${entry.url} failed: ${msg}`;
+                    warnings.push(warning);
+                    logger.warn(`[product:${manifest.name}] ${warning}`);
+                }
+            }
+        }
+        for (const w of warnings)
+            logger.warn(`[product:${manifest.name}] ${w}`);
+        return { registration, warnings };
+    }
+    async remove(name) {
+        const existing = this.store.read();
+        const target = existing.find((p) => p.name === name);
+        if (!target)
+            throw new ProductError("NOT_FOUND", `product '${name}' not registered`);
+        if (target.containerId)
+            await dockerRm(target.containerId);
+        await this.store.update((products) => products.filter((p) => p.name !== name));
+        logger.info(`Product '${name}' removed`);
+    }
+    async reload(name) {
+        const existing = this.store.read();
+        const target = existing.find((p) => p.name === name);
+        if (!target)
+            throw new ProductError("NOT_FOUND", `product '${name}' not registered`);
+        const baseUrl = specBaseUrl(target.spec, target.port);
+        const manifest = await fetchManifest(baseUrl);
+        if (manifest.name !== target.name) {
+            throw new ProductError("NAME_CONFLICT", `manifest now reports name '${manifest.name}', was '${target.name}' — use remove + add`);
+        }
+        const next = { ...target, manifest };
+        await this.store.update((products) => products.map((p) => (p.name === name ? next : p)));
+        logger.info(`Product '${name}' manifest reloaded`);
+        return next;
+    }
+    /** Stop every running container-kind product and clear its tracked
+     *  containerId (model B: the daemon owns container lifecycle, so it reaps
+     *  the control planes it started). Dev-kind products are externally owned —
+     *  left alone. Clearing the id keeps the persisted store honest: a stale id
+     *  left behind would make isRunning() point at a container `--rm` reaped.
+     *  Best-effort per product — a failing `docker rm` is logged, never thrown,
+     *  so one stubborn container can't block a clean shutdown. */
+    async stopAll() {
+        const toStop = this.store.read().filter((p) => p.spec.kind === "container" && p.containerId !== undefined);
+        if (toStop.length === 0)
+            return;
+        const stopped = new Set();
+        await Promise.all(toStop.map(async (reg) => {
+            try {
+                await this.containerOps.remove(reg.containerId);
+            }
+            catch (e) {
+                logger.warn(`Product '${reg.name}': failed to stop container — ${e instanceof Error ? e.message : String(e)}`);
+            }
+            stopped.add(reg.name);
+        }));
+        await this.store.update((products) => products.map((p) => (stopped.has(p.name) ? withContainerId(p, undefined) : p)));
+    }
+    /** Relaunch every container-kind product recorded in the store, refreshing
+     *  its containerId (model B: called once at daemon boot to re-create the
+     *  control planes stopped on the previous shutdown). Dev-kind products are
+     *  externally owned — skipped. Best-effort per product: one that fails to
+     *  come up is logged and left with its containerId cleared, so isRunning()
+     *  reports it down rather than pointing at a container that never started. */
+    async restoreAll() {
+        const toRestore = this.store.read().filter((p) => p.spec.kind === "container");
+        if (toRestore.length === 0)
+            return;
+        const restored = new Map();
+        await Promise.all(toRestore.map(async (reg) => {
+            if (reg.spec.kind !== "container" || reg.port === undefined) {
+                logger.warn(`Product '${reg.name}': cannot restore container without a recorded port — skipping`);
+                restored.set(reg.name, undefined);
+                return;
+            }
+            try {
+                const containerId = await this.containerOps.run(reg.spec.image, reg.port);
+                await this.containerOps.waitForReady(specBaseUrl(reg.spec, reg.port));
+                await this.containerOps.rename(containerId, productContainerName(reg.name));
+                restored.set(reg.name, containerId);
+                logger.info(`Product '${reg.name}' container restored on host port ${reg.port}`);
+            }
+            catch (e) {
+                restored.set(reg.name, undefined);
+                logger.warn(`Product '${reg.name}': failed to restore — ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }));
+        await this.store.update((products) => products.map((p) => (restored.has(p.name) ? withContainerId(p, restored.get(p.name)) : p)));
+    }
+    /** Stop (if still present) and relaunch a single container-kind product,
+     *  recording the fresh containerId. Used by the health monitor to recover a
+     *  product that has failed its liveness probe. Unlike restoreAll this is not
+     *  best-effort: a relaunch that never comes ready rejects, so the monitor
+     *  can count the failed attempt and eventually give up. The new id is
+     *  persisted before the readiness wait, so even a timed-out restart leaves a
+     *  tracked container the next restart can reap rather than orphan. */
+    async restart(name) {
+        const target = this.store.read().find((p) => p.name === name);
+        if (!target)
+            throw new ProductError("NOT_FOUND", `product '${name}' not registered`);
+        if (target.spec.kind !== "container") {
+            throw new ProductError("NOT_RESTARTABLE", `product '${name}' is dev-mode (externally owned) — cannot restart`);
+        }
+        if (target.port === undefined) {
+            throw new ProductError("NOT_RESTARTABLE", `product '${name}' has no recorded port — cannot restart`);
+        }
+        if (target.containerId) {
+            try {
+                await this.containerOps.remove(target.containerId);
+            }
+            catch {
+                // Already gone (crashed / --rm reaped) — nothing to stop.
+            }
+        }
+        const containerId = await this.containerOps.run(target.spec.image, target.port);
+        await this.store.update((products) => products.map((p) => (p.name === name ? withContainerId(p, containerId) : p)));
+        await this.containerOps.waitForReady(specBaseUrl(target.spec, target.port));
+        await this.containerOps.rename(containerId, productContainerName(name));
+        logger.info(`Product '${name}' container restarted on host port ${target.port}`);
+    }
+}
+/** Return a copy of `reg` with containerId set (or removed when undefined),
+ *  preserving the "omit the key entirely" shape the store round-trips. */
+function withContainerId(reg, containerId) {
+    const { containerId: _drop, ...rest } = reg;
+    return containerId === undefined ? rest : { ...rest, containerId };
+}

package/product-template-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error class for product-template lifecycle issues. Codes cover both the
+ * "store + extract" path (used by ctl's ProductTemplateService — extraction,
+ * manifest parsing, in-use guarding) and the simpler "store raw bytes"
+ * 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);
+}

package/product-template-error.js

@@ -0,0 +1,14 @@
+/**
+ * Error class for product-template lifecycle issues. Codes cover both the
+ * "store + extract" path (used by ctl's ProductTemplateService — extraction,
+ * manifest parsing, in-use guarding) and the simpler "store raw bytes"
+ * path (used by mgr — name validation + bytes persistence).
+ */
+export class ProductTemplateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ProductTemplateError";
+    }
+}

package/product-template-materials.d.ts

@@ -0,0 +1,17 @@
+import { type LoadedFile } from "@norskvideo/ctl-foundation";
+/** Compiled Studio components, in the shape buildProductTemplateMaterials expects. */
+export declare function loadCompiledComponents(root: string): LoadedFile[];
+/**
+ * Dashboard files, keyed by workflow name.
+ *
+ * Each `<workflowName>/` under `root` is packed under that name. Where the
+ * workflow has a `dist/`, only its contents are packed (flattened under the
+ * workflow name), so a dashboard built from sources ships its built artefact
+ * and nothing else. Otherwise the directory is packed wholesale, which is what
+ * a pre-built dashboard wants.
+ *
+ * The runner mounts the result at `<studioDocumentDir>/<workflowName>/dashboards/`
+ * inside the studio container, where Studio's `findDashboardDir(workflowName)`
+ * finds it and serves it at `/dashboard/<workflowName>/`.
+ */
+export declare function loadDashboardFiles(root: string): LoadedFile[];

package/product-template-materials.js

@@ -0,0 +1,51 @@
+// Disk readers for the two directory trees that go into a product-template tar.
+//
+// Every product had its own copy of these. The component reader was identical
+// in all of them; the dashboard reader had forked, and the version reconciled
+// here is the one that packs `dist/` when a workflow has been built from
+// sources — without it a source-based dashboard drags its `src/` and its
+// `node_modules/` into the tar.
+//
+// The root path stays with the product: only it knows where its components and
+// dashboards live.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { walkFiles } from "@norskvideo/ctl-foundation";
+// Studio scans the mounted `components/` directory in the product-template tar,
+// and only runtime artifacts are useful at load time, so declarations and
+// source maps are filtered out to keep the tar lean.
+const SKIP_SUFFIXES = [".d.ts", ".js.map"];
+/** Compiled Studio components, in the shape buildProductTemplateMaterials expects. */
+export function loadCompiledComponents(root) {
+    return walkFiles(root, { skipSuffixes: SKIP_SUFFIXES });
+}
+/**
+ * Dashboard files, keyed by workflow name.
+ *
+ * Each `<workflowName>/` under `root` is packed under that name. Where the
+ * workflow has a `dist/`, only its contents are packed (flattened under the
+ * workflow name), so a dashboard built from sources ships its built artefact
+ * and nothing else. Otherwise the directory is packed wholesale, which is what
+ * a pre-built dashboard wants.
+ *
+ * The runner mounts the result at `<studioDocumentDir>/<workflowName>/dashboards/`
+ * inside the studio container, where Studio's `findDashboardDir(workflowName)`
+ * finds it and serves it at `/dashboard/<workflowName>/`.
+ */
+export function loadDashboardFiles(root) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(root)) {
+        const workflowDir = path.join(root, entry);
+        // Loose files at the root belong to no workflow and have nowhere to go.
+        if (!statSync(workflowDir).isDirectory())
+            continue;
+        const distDir = path.join(workflowDir, "dist");
+        const sourceDir = existsSync(distDir) && statSync(distDir).isDirectory() ? distDir : workflowDir;
+        for (const file of walkFiles(sourceDir)) {
+            out.push({ path: path.join(entry, file.path), content: file.content });
+        }
+    }
+    return out;
+}

package/product-template-parsing.d.ts

@@ -0,0 +1,14 @@
+import type { ProductTemplateRecord } from "./product-template-record.js";
+export declare class ProductTemplatesParseError extends Error {
+    constructor(path: string, reason: string);
+}
+export interface ProductTemplatesFile {
+    productTemplates: ProductTemplateRecord[];
+}
+/**
+ * Validate raw product-templates.yaml contents into ProductTemplateRecord[].
+ * Pure: no file IO — callers parse the YAML themselves (typically via
+ * Bun.YAML). Tolerant of legacy entries: missing `source` and missing `sha256`
+ * are accepted; the caller can rebuild them later if needed.
+ */
+export declare function parseProductTemplatesFile(raw: unknown, path: string): ProductTemplatesFile;

package/product-template-parsing.js

@@ -0,0 +1,66 @@
+import { ProductTemplateManifestSchema } from "@norskvideo/ctl-product-template-schema";
+export class ProductTemplatesParseError extends Error {
+    constructor(path, reason) {
+        super(`Failed to parse ${path}: ${reason}`);
+        this.name = "ProductTemplatesParseError";
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null;
+}
+/**
+ * Validate raw product-templates.yaml contents into ProductTemplateRecord[].
+ * Pure: no file IO — callers parse the YAML themselves (typically via
+ * Bun.YAML). Tolerant of legacy entries: missing `source` and missing `sha256`
+ * are accepted; the caller can rebuild them later if needed.
+ */
+export function parseProductTemplatesFile(raw, path) {
+    if (raw === null || raw === undefined)
+        return { productTemplates: [] };
+    if (!isRecord(raw))
+        throw new ProductTemplatesParseError(path, "file is not a YAML object");
+    const productTemplates = raw["product-templates"];
+    if (productTemplates === undefined)
+        return { productTemplates: [] };
+    if (!Array.isArray(productTemplates))
+        throw new ProductTemplatesParseError(path, "'product-templates' must be an array");
+    const validated = [];
+    for (let i = 0; i < productTemplates.length; i++) {
+        const where = `product-templates[${i}]`;
+        const entry = productTemplates[i];
+        if (!isRecord(entry))
+            throw new ProductTemplatesParseError(path, `${where} is not an object`);
+        if (typeof entry.name !== "string")
+            throw new ProductTemplatesParseError(path, `${where}.name must be a string`);
+        if (typeof entry.createdAt !== "string")
+            throw new ProductTemplatesParseError(path, `${where}.createdAt must be a string`);
+        const manifestParse = ProductTemplateManifestSchema.safeParse(entry.manifest);
+        if (!manifestParse.success) {
+            throw new ProductTemplatesParseError(path, `${where}.manifest is invalid: ${manifestParse.error.message}`);
+        }
+        const parameters = Array.isArray(entry.parameters) ? entry.parameters : [];
+        const rec = {
+            name: entry.name,
+            manifest: manifestParse.data,
+            parameters,
+            createdAt: entry.createdAt,
+        };
+        if (typeof entry.sha256 === "string")
+            rec.sha256 = entry.sha256;
+        if (isRecord(entry.source)) {
+            if (entry.source.kind === "import" && typeof entry.source.fromFile === "string") {
+                rec.source = { kind: "import", fromFile: entry.source.fromFile };
+            }
+            else if (entry.source.kind === "build" && typeof entry.source.productName === "string") {
+                rec.source = { kind: "build", productName: entry.source.productName };
+            }
+            else if (entry.source.kind === "product-default" &&
+                typeof entry.source.productName === "string" &&
+                typeof entry.source.url === "string") {
+                rec.source = { kind: "product-default", productName: entry.source.productName, url: entry.source.url };
+            }
+        }
+        validated.push(rec);
+    }
+    return { productTemplates: validated };
+}

package/product-template-record.d.ts

@@ -0,0 +1,45 @@
+import type { ProductTemplateManifest, ProductTemplateParameter } from "@norskvideo/ctl-product-template-schema";
+/**
+ * How a stored product template got here.
+ *
+ *   `import`          — operator-supplied tar file (CLI / API).
+ *   `build`           — generated by calling a registered product's
+ *                       /api/product-template endpoint with iframe form values.
+ *   `product-default` — auto-fetched at product-registration time from
+ *                       a URL the product's manifest declared under
+ *                       `defaultProductTemplates[]`. No user input — the
+ *                       product picks the form values itself.
+ *   `export`          — packed by the runner from a running instance's
+ *                       working directory ("save as product template").
+ */
+export type ProductTemplateSource = {
+    kind: "import";
+    fromFile: string;
+} | {
+    kind: "build";
+    productName: string;
+} | {
+    kind: "product-default";
+    productName: string;
+    url: string;
+} | {
+    kind: "export";
+    productName: string;
+    fromInstance: string;
+};
+/**
+ * Persisted product-template metadata. Stored as one entry per product template
+ * in the consumer's product-templates.yaml. The tar bytes themselves live
+ * alongside (extracted on ctl's side, raw on mgr's side) — see each app's
+ * product-templates/store.ts for the on-disk layout.
+ */
+export interface ProductTemplateRecord {
+    name: string;
+    manifest: ProductTemplateManifest;
+    parameters: ProductTemplateParameter[];
+    createdAt: string;
+    source?: ProductTemplateSource;
+    /** Lowercase hex SHA-256 of the source tar bytes. Optional for
+     *  historic records that predate the field. */
+    sha256?: string;
+}

package/product-template-record.js

@@ -0,0 +1 @@
+export {};

package/product-types.d.ts

@@ -0,0 +1,31 @@
+import type { Manifest } from "./manifest-schema.js";
+export type ProductSpec = {
+    kind: "container";
+    image: string;
+} | {
+    kind: "dev";
+    url: string;
+};
+/** Per-product license (issue #313): supplied at add-product time (or seeded
+ *  from the host's global license setting), resolved at instance launch in
+ *  preference to any daemon-wide default. */
+export type ProductLicense = {
+    mode: "byol";
+    file: string;
+} | {
+    mode: "marketplace";
+    provider: string;
+};
+export interface ProductRegistration {
+    name: string;
+    spec: ProductSpec;
+    addedAt: string;
+    manifest: Manifest;
+    /** Host port (container mode only — dev mode reuses the dev URL's port). */
+    port?: number;
+    /** Docker container ID (container mode only). */
+    containerId?: string;
+    /** Absent on registrations that predate per-product licenses — launches
+     *  fall back to the host's global license setting. */
+    license?: ProductLicense;
+}

package/product-types.js

@@ -0,0 +1 @@
+export {};

package/proxy-middleware.d.ts

@@ -0,0 +1,7 @@
+import type { Response as ExpressResponse, NextFunction, Request } from "express";
+import type { ProductRegistration } from "./product-types.js";
+interface ProductRegistry {
+    list(): ProductRegistration[];
+}
+export declare function createProductProxyMiddleware(svc: ProductRegistry): (req: Request, res: ExpressResponse, next: NextFunction) => Promise<void>;
+export {};