@norskvideo/ctl-product-template-schema 0.1.1 → 0.1.3

package/index.d.ts

@@ -50,6 +50,11 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         runtimeScreenUrl: z.ZodString;
         runtimeScreenLabel: z.ZodOptional<z.ZodString>;
         runtimeScreenService: z.ZodOptional<z.ZodString>;
+        runtimeScreenReadyWhen: z.ZodOptional<z.ZodEnum<{
+            running: "running";
+            healthy: "healthy";
+            never: "never";
+        }>>;
     }, z.core.$strip>>;
     debug: z.ZodOptional<z.ZodObject<{
         studio: z.ZodOptional<z.ZodBoolean>;
@@ -154,6 +159,11 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             runtimeScreenUrl: z.ZodString;
             runtimeScreenLabel: z.ZodOptional<z.ZodString>;
             runtimeScreenService: z.ZodOptional<z.ZodString>;
+            runtimeScreenReadyWhen: z.ZodOptional<z.ZodEnum<{
+                running: "running";
+                healthy: "healthy";
+                never: "never";
+            }>>;
         }, z.core.$strip>>;
         debug: z.ZodOptional<z.ZodObject<{
             studio: z.ZodOptional<z.ZodBoolean>;

package/index.js

@@ -31,6 +31,9 @@ const ProductTemplateUiSchema = z.object({
     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.",
     }),
+    runtimeScreenReadyWhen: z.enum(["running", "healthy", "never"]).optional().meta({
+        description: "When the runner may offer the runtime-screen link, judged on `runtimeScreenService`'s own container state. Omit for the default `running` — the link goes live as soon as the service is up, which is the only state a service without a healthcheck ever reaches. `healthy` holds it back until the service's healthcheck passes, for a product whose screen 404s or misbehaves before it is fully warm. `never` suppresses the link entirely.",
+    }),
 });
 // Per-instance Debug menu toggles. The runner always offers raw Studio +
 // Visualiser debug surfaces for an instance; a product opts a link out when
@@ -127,7 +130,7 @@ export const ProductTemplateManifestSchema = z
         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.",
+        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. Alongside the per-param scalars the runner sets NORSK_ALLOCATED_PORTS: a JSON object keyed by param, each value {port, protocol, service?}, describing every opened port ('{}' when none opted in; unset when nothing is declared) — so a product needing the allocation as data maps one var instead of folding scalars into JSON via interpolation.",
     }),
 })
     .meta({ id: "ProductTemplateManifest", outputId: "ProductTemplateManifest" });
@@ -191,7 +194,8 @@ const ProductTemplateFileSchema = z.object({
     // 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.
+// In-memory bundle the producer builds; packProductTemplate (the `./pack`
+// subpath) turns this into tar bytes at the paths below.
 //
 // `workflow`, `components` and `dashboards` are known top-level paths in the
 // v1 tar format. The runner detects studio in the compose stack and mounts

package/pack.d.ts

@@ -0,0 +1,8 @@
+import { type TarEntry } from "@norskvideo/ctl-foundation/browser";
+import type { ProductTemplateMaterials } from "./index.js";
+export declare function productTemplateTarEntries(materials: ProductTemplateMaterials): TarEntry[];
+/** `mtime` stamps every tar entry's header with a fixed modification time.
+ *  Pass it (alongside a fixed manifest `generatedAt`) for a reproducible
+ *  build — without it packTar defaults each entry to the wall clock, so the
+ *  bytes differ run to run. */
+export declare function packProductTemplate(materials: ProductTemplateMaterials, mtime?: Date): Uint8Array;

package/pack.js

@@ -0,0 +1,48 @@
+// The producer half of the product-template wire format: materials -> tar
+// entries -> tar bytes, at the v1 paths documented on
+// ProductTemplateMaterialsSchema in index.ts. Every product repo used to carry
+// its own copy of this layout and the copies drifted (several silently dropped
+// workdir-seed/); this is the single source. The runner consumes the same
+// paths on the reader side (manifest.json / parameters.yaml / compose.yml
+// validation, workflow.yml + components/ + dashboards/ mounts, workdir-seed/
+// launch copy), so layout changes here are contract changes — additive only.
+//
+// Browser-safe: foundation's packTar and the yaml stringifier are both pure.
+import { packTar } from "@norskvideo/ctl-foundation/browser";
+import { stringify as yamlStringify } from "yaml";
+export function productTemplateTarEntries(materials) {
+    const entries = [
+        { name: "manifest.json", content: `${JSON.stringify(materials.manifest, null, 2)}\n` },
+        { name: "compose.yml", content: materials.composeYaml },
+    ];
+    if (materials.workflow !== undefined) {
+        entries.push({ name: "workflow.yml", content: materials.workflow });
+    }
+    if (materials.parameters) {
+        entries.push({
+            name: "parameters.yaml",
+            content: yamlStringify(materials.parameters, { aliasDuplicateObjects: false }),
+        });
+    }
+    for (const c of materials.components) {
+        entries.push({ name: `components/${c.path}`, content: c.content });
+    }
+    for (const d of materials.dashboards) {
+        entries.push({ name: `dashboards/${d.path}`, content: d.content });
+    }
+    for (const a of materials.assets) {
+        entries.push({ name: `assets/${a.path}`, content: a.content });
+    }
+    for (const s of materials.workdirSeed) {
+        entries.push({ name: `workdir-seed/${s.path}`, content: s.content });
+    }
+    return entries;
+}
+/** `mtime` stamps every tar entry's header with a fixed modification time.
+ *  Pass it (alongside a fixed manifest `generatedAt`) for a reproducible
+ *  build — without it packTar defaults each entry to the wall clock, so the
+ *  bytes differ run to run. */
+export function packProductTemplate(materials, mtime) {
+    const entries = productTemplateTarEntries(materials);
+    return packTar(mtime ? entries.map((e) => ({ ...e, mtime })) : entries);
+}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
     },
+    "./pack": {
+      "types": "./pack.d.ts",
+      "default": "./pack.js"
+    },
     "./params": {
       "types": "./params.d.ts",
       "default": "./params.js"
@@ -15,6 +19,8 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "dependencies": {
+    "@norskvideo/ctl-foundation": "^0.1.0",
+    "yaml": "^2.8.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {