@norskvideo/ctl-product-template-schema 0.1.2 → 0.1.4

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     ".": {
@@ -14,6 +14,10 @@
     "./params": {
       "types": "./params.d.ts",
       "default": "./params.js"
+    },
+    "./read": {
+      "types": "./read.d.ts",
+      "default": "./read.js"
     }
   },
   "main": "./index.js",

package/read.d.ts

@@ -0,0 +1,33 @@
+import type { ProductTemplateParameter } from "./index.js";
+import { type ProductTemplateManifest } from "./index.js";
+/**
+ * Error taxonomy for product-template lifecycle issues. Codes cover both the
+ * "store + extract" path (ctl's ProductTemplateService — extraction, manifest
+ * parsing, in-use guarding) and the simpler "store raw bytes" path (mgr —
+ * name validation + bytes persistence). Lives with the contract it reports
+ * on; @norskvideo/ctl-sdk re-exports it for existing importers.
+ */
+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" | "PRODUCT_MISMATCH";
+    constructor(code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE" | "PRODUCT_MISMATCH", message: string);
+}
+/**
+ * Where the template's root members come from — the seam between the shared
+ * contract and each runner's read mechanics. Two real adapters: ctl reads an
+ * extracted directory; mgr streams single members with `tar -xOf`.
+ * Returns null for an absent member.
+ */
+export interface TarSource {
+    readMember(name: string): Promise<string | null> | string | null;
+}
+export interface ProductTemplateContents {
+    manifest: ProductTemplateManifest;
+    /** `[]` when the template ships no parameters.yaml. */
+    parameters: ProductTemplateParameter[];
+    /** Whether compose.yml exists at the root. Enforcement is caller policy. */
+    hasCompose: boolean;
+}
+/** Validate a product template's members. Throws ProductTemplateError with
+ *  the canonical taxonomy; forward compatibility (RFC 0001) rides on the
+ *  schemas' strip-unknown behaviour, pinned in this package's tests. */
+export declare function readProductTemplate(source: TarSource): Promise<ProductTemplateContents>;

package/read.js

@@ -0,0 +1,67 @@
+// The reading half of the ctl↔product tar contract: which members a product
+// template carries, in what order they are validated, and what error each
+// failure maps to. Both runners re-implemented this (ctl over an extracted
+// dir, mgr over streamed tar members) with byte-identical error strings —
+// the contract now lives beside the schemas it validates, and the read
+// mechanics stay with the callers as TarSource adapters.
+//
+// Policy stays with the callers too: ctl's import refuses a compose-less tar,
+// mgr (which stores raw bytes for relay) does not — so compose presence is a
+// reported fact here, not a verdict.
+import { ParametersFileSchema, ProductTemplateManifestSchema } from "./index.js";
+/**
+ * Error taxonomy for product-template lifecycle issues. Codes cover both the
+ * "store + extract" path (ctl's ProductTemplateService — extraction, manifest
+ * parsing, in-use guarding) and the simpler "store raw bytes" path (mgr —
+ * name validation + bytes persistence). Lives with the contract it reports
+ * on; @norskvideo/ctl-sdk re-exports it for existing importers.
+ */
+export class ProductTemplateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ProductTemplateError";
+    }
+}
+/** Validate a product template's members. Throws ProductTemplateError with
+ *  the canonical taxonomy; forward compatibility (RFC 0001) rides on the
+ *  schemas' strip-unknown behaviour, pinned in this package's tests. */
+export async function readProductTemplate(source) {
+    const manifestText = await source.readMember("manifest.json");
+    if (manifestText === null) {
+        throw new ProductTemplateError("MANIFEST_MISSING", "product template tar must contain manifest.json at the root");
+    }
+    let manifestRaw;
+    try {
+        manifestRaw = JSON.parse(manifestText);
+    }
+    catch (e) {
+        throw new ProductTemplateError("MANIFEST_INVALID", `manifest.json is not valid JSON: ${String(e)}`);
+    }
+    const manifestParsed = ProductTemplateManifestSchema.safeParse(manifestRaw);
+    if (!manifestParsed.success) {
+        throw new ProductTemplateError("MANIFEST_INVALID", `manifest.json failed schema validation: ${manifestParsed.error.message}`);
+    }
+    let parameters = [];
+    const parametersText = await source.readMember("parameters.yaml");
+    if (parametersText !== null) {
+        let parametersRaw;
+        try {
+            parametersRaw = Bun.YAML.parse(parametersText);
+        }
+        catch (e) {
+            throw new ProductTemplateError("PARAMETERS_INVALID", `parameters.yaml is not valid YAML: ${String(e)}`);
+        }
+        const parametersParsed = ParametersFileSchema.safeParse(parametersRaw);
+        if (!parametersParsed.success) {
+            throw new ProductTemplateError("PARAMETERS_INVALID", `parameters.yaml failed schema validation: ${parametersParsed.error.message}`);
+        }
+        parameters = parametersParsed.data.parameters;
+    }
+    return {
+        manifest: manifestParsed.data,
+        parameters,
+        hasCompose: (await source.readMember("compose.yml")) !== null,
+    };
+}