@norskvideo/ctl-product-template-schema 0.1.54 → 0.1.56

package/index.d.ts

@@ -4,6 +4,11 @@ export declare const ProductTemplateTargetSchema: z.ZodEnum<{
 }>;
 export type ProductTemplateTarget = z.infer<typeof ProductTemplateTargetSchema>;
 export declare const RESERVED_INSTANCE_ROUTE_SEGMENTS: readonly ["studio", "media", "visualiser", "uvis", "status", "metrics"];
+/** How a template's runtimes appear on fleet dashboards (RFC 0006 §4.1). */
+export declare const ProductTemplateDashboardSchema: z.ZodObject<{
+    kind: z.ZodString;
+    previews: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export declare const PRODUCT_TEMPLATE_ADVANCED_NETWORK_MODES: readonly ["docker", "hybrid"];
 export declare const ProductTemplateAdvancedSchema: z.ZodObject<{
     networkMode: z.ZodOptional<z.ZodObject<{
@@ -200,6 +205,14 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
             websocket: z.ZodOptional<z.ZodBoolean>;
             auth: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
+        operations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            openapi: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    dashboard: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        previews: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     allowWorkflowUploads: z.ZodOptional<z.ZodBoolean>;
     isStudio: z.ZodOptional<z.ZodBoolean>;
@@ -464,6 +477,14 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
                 websocket: z.ZodOptional<z.ZodBoolean>;
                 auth: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
+            operations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                openapi: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        dashboard: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodString;
+            previews: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         allowWorkflowUploads: z.ZodOptional<z.ZodBoolean>;
         isStudio: z.ZodOptional<z.ZodBoolean>;
@@ -674,6 +695,10 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
         path: z.ZodString;
         content: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
     }, z.core.$strip>>>;
+    openapi: z.ZodOptional<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>>]>;

package/index.js

@@ -87,6 +87,36 @@ const ProductTemplateRouteSchema = z.object({
         description: "Whether the route sits behind the runner's oauth2 auth_request. Omit for the default `true`. Set false only for a surface that must be reachable unauthenticated, as the media route is.",
     }),
 });
+// The operations a template serves, each described by an OpenAPI document it
+// carries under openapi/ (RFC 0006 §4.1, norsk-ctl task 123). Keyed by the
+// instance path the document describes, so it covers the runtime-screen
+// catch-all as well as declared routes. An operation is reachable from a
+// dashboard only when marked `x-norsk-dashboard: true`, and needs the
+// platform rung its `x-norsk-role` names on the runtime.
+const SAFE_SEGMENTS = (value) => !value.split("/").some((s) => s === ".." || s === ".");
+const ProductTemplateOperationsSchema = z.object({
+    path: z
+        .string()
+        .regex(/^\/[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*$/, "an absolute path under the instance, no trailing slash")
+        .refine(SAFE_SEGMENTS, { message: "no . or .. segments" })
+        .meta({
+        description: "The path under /instance/<id>/ the document's paths are relative to, e.g. /live/api/probe-api.",
+    }),
+    openapi: z
+        .string()
+        .regex(/^openapi\/[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*\.(ya?ml|json)$/, "a YAML or JSON file under openapi/")
+        .refine(SAFE_SEGMENTS, { message: "no . or .. segments" })
+        .meta({ description: "The OpenAPI 3 document in the template tar, e.g. openapi/probe-api.yaml." }),
+});
+/** How a template's runtimes appear on fleet dashboards (RFC 0006 §4.1). */
+export const ProductTemplateDashboardSchema = z.object({
+    kind: z.string().min(1).meta({
+        description: "The discovery kind a runtime of this template announces itself as, e.g. norsk-probe.monitor.",
+    }),
+    previews: z.array(z.string().min(1)).optional().meta({
+        description: "The roles of the MoQ previews it offers, e.g. main.",
+    }),
+});
 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.",
@@ -94,6 +124,9 @@ const ProductTemplateProxySchema = z.object({
     routes: z.array(ProductTemplateRouteSchema).optional().meta({
         description: "Extra named services to route under the instance root, beside the runtime-screen catch-all. Additive and optional: a template that omits it routes exactly as before, so an older runner ignoring the field still launches the product.",
     }),
+    operations: z.array(ProductTemplateOperationsSchema).optional().meta({
+        description: "The operations this template's runtimes serve, each set described by an OpenAPI document in the tar; the ones marked x-norsk-dashboard are what fleet dashboards may call, each decided per user by the platform. Additive: a runner that predates it ignores it.",
+    }),
 });
 // product-template-schema cannot import @norsk-ctl/shared (dependency direction), so
 // this is a literal copy of the runner's network-mode enum — and the runner
@@ -207,7 +240,7 @@ export const ProductTemplateSideloadSchema = z
 export const ProductTemplateHostTlsSchema = z
     .object({
     services: z.array(z.string().min(1)).min(1).meta({
-        description: "Compose services that get the host certificate. Each must be a service in the template's own compose.yml. The runner mounts the certificate and key read-only at /etc/norsk-host-tls (cert.pem, key.pem) and sets NORSK_HOST_TLS_DIR=/etc/norsk-host-tls and NORSK_HOST_TLS_TRUSTED=true|false (true when the certificate is a real, browser-trusted one; false when the host's is self-signed). A host with no certificate mounts nothing and sets neither variable; the launch still goes ahead.",
+        description: "Compose services that get the host certificate. Each must be a service in the template's own compose.yml. The runner mounts the certificate and key read-only at /etc/norsk-host-tls (cert.pem, key.pem) and sets NORSK_HOST_TLS_DIR=/etc/norsk-host-tls. A host with no certificate mounts nothing and sets no variable; the launch still goes ahead.",
     }),
 })
     .meta({ id: "ProductTemplateHostTls", outputId: "ProductTemplateHostTls" });
@@ -222,7 +255,7 @@ export const ProductTemplateHostTlsSchema = z
 export const ProductTemplateWorkdirSchema = z
     .object({
     services: z.array(z.string().min(1)).min(1).meta({
-        description: "Compose services that get the instance working directory, read-write at /data -- the same directory, at the same path, that media and studio have -- with NORSK_WORKDIR=/data. Each must be a service in the template's own compose.yml. It survives relaunch, restart and runner upgrade; only `instance delete --purge` removes it.",
+        description: "Compose services that get the instance working directory, read-write at /data -- the same directory, at the same path, that media and studio have. Each must be a service in the template's own compose.yml. It survives relaunch, restart and runner upgrade; only `instance delete --purge` removes it.",
     }),
 })
     .meta({ id: "ProductTemplateWorkdir", outputId: "ProductTemplateWorkdir" });
@@ -368,6 +401,9 @@ export const ProductTemplateManifestSchema = z
         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(),
+    dashboard: ProductTemplateDashboardSchema.optional().meta({
+        description: "How this template's runtimes appear on fleet dashboards: the kind they announce, and their previews. Absent = not on dashboards.",
+    }),
     allowWorkflowUploads: z.boolean().optional().meta({
         description: "Whether the operator may upload workflow documents for this product. They land in the working directory's studio-save-files/, where Studio lists them for the operator to open — so this is for Norsk Studio itself (the editor), not for appliances built on it: an appliance (probe, playout) generates its one workflow from its config screen and has nothing to select. Absent = false. Assets are governed separately by `supportsCustomAssets`.",
     }),
@@ -525,6 +561,9 @@ export const ProductTemplateMaterialsSchema = z
         .array(ProductTemplateFileSchema)
         .default([])
         .meta({ description: "Free-form product files — packed under assets/ in the tar" }),
+    openapi: z.array(ProductTemplateFileSchema).optional().meta({
+        description: "The OpenAPI documents proxy.operations names, packed under openapi/ in the tar. Optional so materials built before it still typecheck.",
+    }),
     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.",
     }),

package/pack.js

@@ -33,6 +33,9 @@ export function productTemplateTarEntries(materials) {
     for (const a of materials.assets) {
         entries.push({ name: `assets/${a.path}`, content: a.content });
     }
+    for (const o of materials.openapi ?? []) {
+        entries.push({ name: `openapi/${o.path}`, content: o.content });
+    }
     for (const s of materials.workdirSeed) {
         entries.push({ name: `workdir-seed/${s.path}`, content: s.content });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "type": "module",
   "exports": {
     ".": {