@norskvideo/ctl-product-template-schema 0.1.0

package/index.d.ts

@@ -0,0 +1,221 @@
+import { z } from "zod";
+export declare const ProductTemplateTargetSchema: z.ZodEnum<{
+    "docker-compose": "docker-compose";
+}>;
+export type ProductTemplateTarget = z.infer<typeof ProductTemplateTargetSchema>;
+export declare const PRODUCT_TEMPLATE_ADVANCED_NETWORK_MODES: readonly ["docker", "hybrid"];
+export declare const ProductTemplateAdvancedSchema: z.ZodObject<{
+    networkMode: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodEnum<{
+            docker: "docker";
+            hybrid: "hybrid";
+        }>>;
+    }, z.core.$strip>>;
+    containerUser: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    publicHost: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    hostPorts: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ProductTemplateAllocatedPortSchema: z.ZodObject<{
+    param: z.ZodString;
+    protocol: z.ZodEnum<{
+        tcp: "tcp";
+        udp: "udp";
+    }>;
+    service: z.ZodOptional<z.ZodString>;
+    preferred: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProductTemplateAllocatedPort = z.infer<typeof ProductTemplateAllocatedPortSchema>;
+export declare const ProductTemplateManifestSchema: z.ZodObject<{
+    productTemplateSchemaVersion: z.ZodLiteral<1>;
+    productName: z.ZodString;
+    productVersion: z.ZodString;
+    target: z.ZodEnum<{
+        "docker-compose": "docker-compose";
+    }>;
+    generatedAt: z.ZodString;
+    ui: z.ZodOptional<z.ZodObject<{
+        runtimeScreenUrl: z.ZodString;
+        runtimeScreenLabel: z.ZodOptional<z.ZodString>;
+        runtimeScreenService: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    debug: z.ZodOptional<z.ZodObject<{
+        studio: z.ZodOptional<z.ZodBoolean>;
+        visualiser: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    proxy: z.ZodOptional<z.ZodObject<{
+        expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
+    advanced: z.ZodOptional<z.ZodObject<{
+        networkMode: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodEnum<{
+                docker: "docker";
+                hybrid: "hybrid";
+            }>>;
+        }, z.core.$strip>>;
+        containerUser: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        publicHost: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        hostPorts: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    allocatedPorts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        param: z.ZodString;
+        protocol: z.ZodEnum<{
+            tcp: "tcp";
+            udp: "udp";
+        }>;
+        service: z.ZodOptional<z.ZodString>;
+        preferred: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProductTemplateManifest = z.infer<typeof ProductTemplateManifestSchema>;
+export declare const STANDARD_ADVANCED_OVERRIDES: {
+    readonly containerUser: {};
+    readonly publicHost: {};
+};
+export declare const ProductTemplateParameterSchema: z.ZodObject<{
+    name: z.ZodString;
+    purpose: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        int: "int";
+        enum: "enum";
+    }>>;
+    default: z.ZodOptional<z.ZodString>;
+    secret: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProductTemplateParameter = z.infer<typeof ProductTemplateParameterSchema>;
+export declare const ParametersFileSchema: z.ZodObject<{
+    parameters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        purpose: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            int: "int";
+            enum: "enum";
+        }>>;
+        default: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ParametersFile = z.infer<typeof ParametersFileSchema>;
+declare const ProductTemplateFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
+}, z.core.$strip>;
+export type ProductTemplateFile = z.infer<typeof ProductTemplateFileSchema>;
+export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
+    manifest: z.ZodObject<{
+        productTemplateSchemaVersion: z.ZodLiteral<1>;
+        productName: z.ZodString;
+        productVersion: z.ZodString;
+        target: z.ZodEnum<{
+            "docker-compose": "docker-compose";
+        }>;
+        generatedAt: z.ZodString;
+        ui: z.ZodOptional<z.ZodObject<{
+            runtimeScreenUrl: z.ZodString;
+            runtimeScreenLabel: z.ZodOptional<z.ZodString>;
+            runtimeScreenService: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        debug: z.ZodOptional<z.ZodObject<{
+            studio: z.ZodOptional<z.ZodBoolean>;
+            visualiser: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        proxy: z.ZodOptional<z.ZodObject<{
+            expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
+        advanced: z.ZodOptional<z.ZodObject<{
+            networkMode: z.ZodOptional<z.ZodObject<{
+                default: z.ZodOptional<z.ZodEnum<{
+                    docker: "docker";
+                    hybrid: "hybrid";
+                }>>;
+            }, z.core.$strip>>;
+            containerUser: z.ZodOptional<z.ZodObject<{
+                default: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            publicHost: z.ZodOptional<z.ZodObject<{
+                default: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            hostPorts: z.ZodOptional<z.ZodObject<{
+                default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        allocatedPorts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            param: z.ZodString;
+            protocol: z.ZodEnum<{
+                tcp: "tcp";
+                udp: "udp";
+            }>;
+            service: z.ZodOptional<z.ZodString>;
+            preferred: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    composeYaml: z.ZodString;
+    parameters: z.ZodOptional<z.ZodObject<{
+        parameters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            purpose: z.ZodString;
+            type: z.ZodDefault<z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                int: "int";
+                enum: "enum";
+            }>>;
+            default: z.ZodOptional<z.ZodString>;
+            secret: z.ZodOptional<z.ZodBoolean>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    workflow: z.ZodOptional<z.ZodString>;
+    components: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
+    }, z.core.$strip>>>;
+    dashboards: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
+    }, z.core.$strip>>>;
+    assets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
+    }, z.core.$strip>>>;
+    workdirSeed: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProductTemplateMaterials = z.infer<typeof ProductTemplateMaterialsSchema>;
+export {};

package/index.js

@@ -0,0 +1,218 @@
+import { z } from "zod";
+// ProductTemplate format v1. A product template is a tar file at the wire; the schemas
+// below describe its parts before packing and how the runner validates
+// the unpacked tar.
+//
+// Producers (norsk-probe and future products) build a `ProductTemplateMaterials`
+// in-memory bundle and hand it to the tar packer. The runner validates the
+// unpacked manifest.json against `ProductTemplateManifestSchema` and the
+// unpacked parameters.yaml against `ParametersFileSchema`.
+//
+// Canonical docs:
+//   packages/norsk-ctl/docs/product-template-format.md           (wire format)
+//   packages/norsk-ctl/docs/_planning/product-template-working-directory.md
+//                                                        (runtime mount contract)
+export const ProductTemplateTargetSchema = z
+    .enum(["docker-compose"])
+    .meta({ description: "Runner target. Currently always docker-compose; future targets (e.g. k8s) will extend." });
+// `ui` and `proxy` are product-template-level (not product-level) because the user's
+// config choices in the configure iframe can change which services end up in
+// the compose stack — and therefore which paths need a UI surface or a proxy
+// allowlist entry. Both are optional: product templates whose compose stack has no
+// HTTP service to expose simply omit them.
+const ProductTemplateUiSchema = z.object({
+    runtimeScreenUrl: z.string().meta({
+        description: "Path (relative to the proxied instance root) for the per-instance dashboard. Runner builds <runnerHost>/instance/<id><runtimeScreenUrl>. Must also appear in proxy.expose[].",
+    }),
+    runtimeScreenLabel: z
+        .string()
+        .optional()
+        .meta({ description: "Friendly button label. Default `Open <productName>`." }),
+    runtimeScreenService: z.string().optional().meta({
+        description: "Compose service that hosts the runtime screen. Omit for the conventional `studio`; a product that serves its dashboard from a different service names it here so the runner routes the catch-all there.",
+    }),
+});
+// Per-instance Debug menu toggles. The runner always offers raw Studio +
+// Visualiser debug surfaces for an instance; a product opts a link out when
+// its primary runtime screen already *is* that surface (e.g. Studio's main
+// "Open" button is Studio itself — showing a second "Open Studio" under Debug
+// is redundant). Each flag defaults to true (shown) when omitted.
+const ProductTemplateDebugSchema = z.object({
+    studio: z.boolean().optional().meta({ description: "Show the Debug menu's 'Open Studio' link. Default true." }),
+    visualiser: z
+        .boolean()
+        .optional()
+        .meta({ description: "Show the Debug menu's 'Open Visualiser' link. Default true." }),
+});
+const ProductTemplateProxySchema = z.object({
+    expose: z.array(z.string()).default([]).meta({
+        description: "Paths (or globs) the runner's nginx routes through to this instance. Anything not in the list returns 404 from the proxy. Glob-shaped strings (`/static/*`) are accepted as hints — current implementation treats the whole set as a signal to mount a catch-all on the instance root; per-path filtering can come later.",
+    }),
+});
+// product-template-schema cannot import @norsk-ctl/shared (dependency direction), so
+// this is a literal copy of the runner's network-mode enum. The runner's
+// OpenAPI ProductTemplateAdvanced shape is generated from this zod (see
+// backend/scripts/gen-product-template-oas.ts), so the two can't drift — but the
+// runner's own ProductNetworkMode launch enum is still hand-authored; extend
+// both if a new mode ever lands.
+export const PRODUCT_TEMPLATE_ADVANCED_NETWORK_MODES = ["docker", "hybrid"];
+// Per-key opt-in map of settings-backed runner knobs the operator may
+// override per instance. Key presence puts the knob on the launch form;
+// `default` pre-fills it (otherwise the runner's daemon-wide default
+// applies). UI gating only for now — the launch API accepts the full launch
+// config regardless of declarations. Per-key objects (not a key list)
+// because opting in and supplying a default are independent choices.
+export const ProductTemplateAdvancedSchema = z
+    .object({
+    networkMode: z.object({ default: z.enum(PRODUCT_TEMPLATE_ADVANCED_NETWORK_MODES).optional() }).optional(),
+    containerUser: z.object({ default: z.string().optional() }).optional(),
+    publicHost: z.object({ default: z.string().optional() }).optional(),
+    // Managed host-port bindings. `default` is `SPEC` / `SPEC@service` tokens
+    // (e.g. "5001/udp", "9000:1935@my-sidecar"; service omitted = media) —
+    // a suggestion the operator can change per instance, since a host port is
+    // exclusive and a second instance needs a different one. Hard pinning is
+    // a future product-template-pins concern, not this knob.
+    hostPorts: z.object({ default: z.array(z.string()).optional() }).optional(),
+})
+    .meta({ id: "ProductTemplateAdvanced", outputId: "ProductTemplateAdvanced" });
+// A host-port binding whose value rides a product-template parameter, opted in per
+// launch by that parameter's value: absent/blank keeps the port CLOSED,
+// "auto" allocates a free (port, protocol) starting at `preferred`, a number
+// uses that port. A product template that wants the port open by default gives the
+// parameter a default of "auto" (or a number); one that can't know whether
+// the feature is wanted (e.g. MoQ preview) declares no default. When opened,
+// the runner publishes the chosen port as a managed host binding AND exposes
+// the number to compose interpolation under `param`, so the in-container
+// listener, the published binding and any advertised URL all agree. Relaunch
+// re-supplies the recorded number, so an opened instance keeps its port.
+// Distinct from `advanced.hostPorts` (operator-typed extra bindings with no
+// parameter linkage).
+export const ProductTemplateAllocatedPortSchema = z
+    .object({
+    param: z.string().regex(/^[A-Z][A-Z0-9_]*$/, "env var name; uppercase, digits, underscores"),
+    protocol: z.enum(["tcp", "udp"]),
+    service: z.string().optional().meta({ description: "Compose service the binding targets; omitted = media" }),
+    preferred: z.number().int().min(1).max(65535).meta({ description: "Allocation starts here and walks upward" }),
+    label: z.string().optional().meta({ description: "Human label, e.g. 'MoQ preview (WebTransport)'" }),
+})
+    .meta({ id: "ProductTemplateAllocatedPort", outputId: "ProductTemplateAllocatedPort" });
+export const ProductTemplateManifestSchema = z
+    .object({
+    productTemplateSchemaVersion: z.literal(1),
+    productName: z.string(),
+    productVersion: z.string(),
+    target: ProductTemplateTargetSchema,
+    generatedAt: z
+        .string()
+        .meta({ description: "ISO-8601 timestamp at product-template generation time", example: "2026-05-07T12:00:00Z" }),
+    ui: ProductTemplateUiSchema.optional(),
+    debug: ProductTemplateDebugSchema.optional().meta({
+        description: "Per-instance Debug menu toggles. Each of `studio`/`visualiser` defaults to shown; set false to hide a redundant link (e.g. Studio hides its own 'Open Studio').",
+    }),
+    proxy: ProductTemplateProxySchema.optional(),
+    requiresWorkingDirectory: z.boolean().optional().meta({
+        description: "When true, the operator must choose a working directory at launch (a dev product template they own and keep), rather than getting the auto-assigned per-instance default. The runner's launch UI makes the working-directory field mandatory.",
+    }),
+    advanced: ProductTemplateAdvancedSchema.optional().meta({
+        description: "Settings-backed runner knobs the operator may override per instance. Key presence opts the knob into the launch form; `default` pre-fills it (else the runner's daemon-wide default applies).",
+    }),
+    allocatedPorts: z.array(ProductTemplateAllocatedPortSchema).optional().meta({
+        description: "Host-port bindings whose value rides a product-template parameter. Opt-in per launch via the param value: absent = closed, 'auto' = allocate a free port from `preferred`, number = use it. When opened the port is published as a managed host binding and surfaced to the containers via compose interpolation.",
+    }),
+})
+    .meta({ id: "ProductTemplateManifest", outputId: "ProductTemplateManifest" });
+// Container user and external URL are runner knobs every product wants
+// overridable per instance — the runner only holds their default values.
+// Spread this into a manifest's `advanced` (adding product-specific keys
+// like networkMode on top) instead of hand-rolling the declarations:
+//   advanced: { ...STANDARD_ADVANCED_OVERRIDES, networkMode: {} }
+// Still an explicit opt-in: a product that must withhold a knob simply
+// doesn't spread it.
+export const STANDARD_ADVANCED_OVERRIDES = {
+    containerUser: {},
+    publicHost: {},
+};
+export const ProductTemplateParameterSchema = z
+    .object({
+    name: z.string().regex(/^[A-Z][A-Z0-9_]*$/, "env var name; uppercase, digits, underscores"),
+    purpose: z.string(),
+    type: z.enum(["string", "int", "number", "boolean", "enum"]).default("string"),
+    default: z.string().optional().meta({ description: "Stringified default (even for numeric/boolean/enum types)" }),
+    secret: z.boolean().optional(),
+    /** Mandatory input. Only bites when there is no `default` to fall back
+     *  on — the runner/composer blocks launch on an empty required value. */
+    required: z.boolean().optional(),
+    /** Inclusive bounds for `int`/`number` parameters. */
+    min: z.number().optional(),
+    max: z.number().optional(),
+    /** Allowed values for `enum` parameters (rendered as a dropdown). */
+    values: z.array(z.string()).optional(),
+})
+    .superRefine((p, ctx) => {
+    if (p.type === "enum" && (!p.values || p.values.length === 0)) {
+        ctx.addIssue({ code: "custom", path: ["values"], message: "enum parameters require a non-empty `values` list" });
+    }
+    if (p.type !== "enum" && p.values !== undefined) {
+        ctx.addIssue({ code: "custom", path: ["values"], message: "`values` is only valid for enum parameters" });
+    }
+    if (p.min !== undefined && p.max !== undefined && p.min > p.max) {
+        ctx.addIssue({ code: "custom", path: ["min"], message: "`min` must be <= `max`" });
+    }
+    if ((p.min !== undefined || p.max !== undefined) && p.type !== "int" && p.type !== "number") {
+        ctx.addIssue({ code: "custom", path: ["min"], message: "`min`/`max` are only valid for int/number parameters" });
+    }
+})
+    .meta({ id: "ProductTemplateParameter", outputId: "ProductTemplateParameter" });
+// Wire shape of the optional parameters.yaml file inside a product-template tar.
+// `parameters` defaults to [] so products with no override surface can omit
+// the file entirely (or ship it empty) and the runner's safeParse still
+// returns a valid empty-list value.
+export const ParametersFileSchema = z
+    .object({
+    parameters: z.array(ProductTemplateParameterSchema).default([]),
+})
+    .meta({ id: "ParametersFile" });
+const ProductTemplateFileSchema = z.object({
+    path: z.string().meta({ description: "Relative path under the parent directory in the tar" }),
+    // `Uint8Array` is the canonical shape — binary-safe for media/graphics
+    // assets in workdir-seed/ etc. String accepted for the text-emitting
+    // producer call sites (probe's compose.yml render, manifest JSON,
+    // etc.) so callers don't have to TextEncoder by hand. The tar packer
+    // accepts both via the same union.
+    content: z.union([z.string(), z.instanceof(Uint8Array)]),
+});
+// In-memory bundle the producer builds; the tar packer turns this into bytes.
+//
+// `workflow`, `components` and `dashboards` are known top-level paths in the
+// v1 tar format. The runner detects studio in the compose stack and mounts
+// all three into the studio container automatically — products don't need
+// to declare the mounts.
+//
+//   workflow.yml         → /data/studio-save-files/workflow.yml (RO)
+//   components/<name>/   → /usr/src/app/plugins/<name>/         (RO)
+//   dashboards/<name>/   → /data/studio-save-files/<name>/dashboards/ (RO)
+//
+// `assets` is free-form; the rule is "if it earns a role, it earns a known
+// path" (workflow.yml was the first instance of this — promoted out of
+// `assets/`).
+export const ProductTemplateMaterialsSchema = z
+    .object({
+    manifest: ProductTemplateManifestSchema,
+    composeYaml: z.string(),
+    parameters: ParametersFileSchema.optional(),
+    workflow: z.string().optional().meta({ description: "Studio workflow YAML — packed at tar root as workflow.yml" }),
+    components: z.array(ProductTemplateFileSchema).default([]).meta({
+        description: "Compiled studio components — packed under components/ in the tar",
+    }),
+    dashboards: z.array(ProductTemplateFileSchema).default([]).meta({
+        description: "Per-workflow dashboard assets — packed under dashboards/<workflowName>/. Runner mounts each into /data/studio-save-files/<workflowName>/dashboards/ so Studio serves them at /dashboard/<workflowName>/.",
+    }),
+    assets: z
+        .array(ProductTemplateFileSchema)
+        .default([])
+        .meta({ description: "Free-form product files — packed under assets/ in the tar" }),
+    workdirSeed: z.array(ProductTemplateFileSchema).default([]).meta({
+        description: "Files copied recursively into the launch workdir at launch time. Packed under workdir-seed/ in the tar. Existing files in the launch workdir win on conflict (the seed only fills gaps), so re-launches and operator-edits-in-place are non-destructive. Lets a product template ship a 'starter pack' of demo workflows / dashboards / components that the runtime sees in /data on first launch.",
+    }),
+})
+    .meta({ id: "ProductTemplateMaterials" });

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@norskvideo/ctl-product-template-schema",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./params": {
+      "types": "./params.d.ts",
+      "default": "./params.js"
+    }
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/params.d.ts

@@ -0,0 +1,20 @@
+import type { ProductTemplateParameter } from "./index.js";
+/** The subset of a parameter these helpers reason about. `type` is optional
+ *  (a missing type is treated as `string`) so callers holding a looser shape
+ *  than the parsed schema can use these directly. */
+export type ParamSpec = {
+    type?: ProductTemplateParameter["type"];
+    required?: boolean;
+    default?: string;
+    min?: number;
+    max?: number;
+    values?: string[];
+};
+/** A required parameter only blocks launch when it has no `default` to fall
+ *  back on — supplying a default is itself a way of satisfying it. */
+export declare function isParamRequired(p: Pick<ProductTemplateParameter, "required" | "default">): boolean;
+/** Validate an operator's raw (string) input for a parameter. Returns an
+ *  error message, or `undefined` when the value is acceptable — including an
+ *  empty value for a non-required parameter (the default / runner fills it).
+ *  Boolean/number/enum values arrive as strings from form inputs. */
+export declare function validateParamValue(p: ParamSpec, raw: string): string | undefined;

package/params.js

@@ -0,0 +1,42 @@
+// Pure, dependency-free helpers for product-template parameter input — shared by
+// every surface that lets an operator fill parameters (norsk-mgr's
+// ProductionComposer, norsk-ctl's ProductTemplateLaunchForm). Kept out of
+// index.ts so importers don't pull zod into a browser bundle; the only
+// dependency is the `ProductTemplateParameter` *type*.
+/** A required parameter only blocks launch when it has no `default` to fall
+ *  back on — supplying a default is itself a way of satisfying it. */
+export function isParamRequired(p) {
+    return p.required === true && p.default === undefined;
+}
+/** Validate an operator's raw (string) input for a parameter. Returns an
+ *  error message, or `undefined` when the value is acceptable — including an
+ *  empty value for a non-required parameter (the default / runner fills it).
+ *  Boolean/number/enum values arrive as strings from form inputs. */
+export function validateParamValue(p, raw) {
+    const v = raw.trim();
+    if (v === "")
+        return isParamRequired(p) ? "required" : undefined;
+    switch (p.type) {
+        case "int":
+            if (!/^-?\d+$/.test(v))
+                return "must be a whole number";
+            return rangeError(p, Number(v));
+        case "number":
+            if (!Number.isFinite(Number(v)))
+                return "must be a number";
+            return rangeError(p, Number(v));
+        case "boolean":
+            return /^(true|false)$/i.test(v) ? undefined : "must be true or false";
+        case "enum":
+            return p.values && !p.values.includes(v) ? `must be one of: ${p.values.join(", ")}` : undefined;
+        default:
+            return undefined; // string — anything goes
+    }
+}
+function rangeError(p, n) {
+    if (p.min !== undefined && n < p.min)
+        return `must be >= ${p.min}`;
+    if (p.max !== undefined && n > p.max)
+        return `must be <= ${p.max}`;
+    return undefined;
+}