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

package/index.d.ts

@@ -38,6 +38,10 @@ export declare const ProductTemplateAllocatedPortSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProductTemplateAllocatedPort = z.infer<typeof ProductTemplateAllocatedPortSchema>;
+export declare const ProductTemplateSideloadSchema: z.ZodObject<{
+    gpuInference: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ProductTemplateSideload = z.infer<typeof ProductTemplateSideloadSchema>;
 export declare const ProductTemplateManifestSchema: z.ZodObject<{
     productTemplateSchemaVersion: z.ZodLiteral<1>;
     productName: z.ZodString;
@@ -64,6 +68,9 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
         expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
+    sideload: z.ZodOptional<z.ZodObject<{
+        gpuInference: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     advanced: z.ZodOptional<z.ZodObject<{
         networkMode: z.ZodOptional<z.ZodObject<{
             default: z.ZodOptional<z.ZodEnum<{
@@ -173,6 +180,9 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
             expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
+        sideload: z.ZodOptional<z.ZodObject<{
+            gpuInference: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
         advanced: z.ZodOptional<z.ZodObject<{
             networkMode: z.ZodOptional<z.ZodObject<{
                 default: z.ZodOptional<z.ZodEnum<{

package/index.js

@@ -109,6 +109,18 @@ export const ProductTemplateAllocatedPortSchema = z
     label: z.string().optional().meta({ description: "Human label, e.g. 'MoQ preview (WebTransport)'" }),
 })
     .meta({ id: "ProductTemplateAllocatedPort", outputId: "ProductTemplateAllocatedPort" });
+// CUDA sideload bundle needs (docker/SIDELOAD.md). Only `gpuInference` is
+// declared: `gpu-video` (NVENC/NVDEC) follows the GPU reservation automatically,
+// so it needs no declaration. The runner mounts the matching bundle only when
+// the image is slimmed AND the GPU is reserved; otherwise this is inert (a stock
+// image needs no bundle; inference without a bundle falls back to CPU).
+export const ProductTemplateSideloadSchema = z
+    .object({
+    gpuInference: z.boolean().optional().meta({
+        description: "Deployment uses GPU-accelerated inference (ONNX NR-IQA/detection/VAD, GPU whisper). When the GPU is reserved on the host the runner mounts the gpu-inference CUDA bundle; otherwise inference falls back to CPU. gpu-video (NVENC/NVDEC) follows the GPU reservation automatically and needs no declaration.",
+    }),
+})
+    .meta({ id: "ProductTemplateSideload", outputId: "ProductTemplateSideload" });
 export const ProductTemplateManifestSchema = z
     .object({
     productTemplateSchemaVersion: z.literal(1),
@@ -126,6 +138,9 @@ export const ProductTemplateManifestSchema = z
     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.",
     }),
+    sideload: ProductTemplateSideloadSchema.optional().meta({
+        description: "CUDA sideload bundle needs. Only gpu-inference is declared (gpu-video follows the GPU reservation automatically). The runner mounts the matching bundle when the image is slimmed and the GPU is reserved.",
+    }),
     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).",
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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,
+    };
+}