@norskvideo/ctl-sdk 0.1.15 → 0.1.16

package/components/ProductIframe.d.ts

@@ -21,6 +21,15 @@ export declare const ProductIframe: import("react").ForwardRefExoticComponent<{
      * don't emit it leave the field's default behaviour unchanged.
      */
     onSuggestName?: (name: string) => void;
+    /**
+     * Fires when the iframe emits a `requirements` postMessage — the product's
+     * suggested placement requirements for the template being configured, which
+     * it may recompute as the operator changes the config. The raw payload is
+     * forwarded (kept schema-agnostic here); the parent validates + pre-fills its
+     * requirements editor. Products that don't emit it leave the editor at its
+     * static/blank default.
+     */
+    onRequirements?: (requirements: unknown) => void;
     /**
      * Optional product-template/launch context forwarded verbatim in the `init`
      * payload (as `launchContext`). Used by the instance-launch config screen

package/components/ProductIframe.js

@@ -6,7 +6,7 @@ function resolveSrc(productName, configScreenUrl) {
     const path = configScreenUrl.startsWith("/") ? configScreenUrl : `/${configScreenUrl}`;
     return `/products/${encodeURIComponent(productName)}${path}`;
 }
-export const ProductIframe = forwardRef(function ProductIframe({ productName, configScreenUrl, onValidityChange, onSuggestName, launchContext }, ref) {
+export const ProductIframe = forwardRef(function ProductIframe({ productName, configScreenUrl, onValidityChange, onSuggestName, onRequirements, launchContext }, ref) {
     const iframeRef = useRef(null);
     const [height, setHeight] = useState(420);
     const [valid, setValid] = useState(true);
@@ -22,6 +22,10 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
     useEffect(() => {
         onSuggestNameRef.current = onSuggestName;
     }, [onSuggestName]);
+    const onRequirementsRef = useRef(onRequirements);
+    useEffect(() => {
+        onRequirementsRef.current = onRequirements;
+    }, [onRequirements]);
     const src = resolveSrc(productName, configScreenUrl);
     useEffect(() => {
         const onMessage = (event) => {
@@ -53,6 +57,12 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
                         onSuggestNameRef.current?.(payload.name);
                     break;
                 }
+                case "requirements": {
+                    // Forward the raw suggestion; the parent validates against the schema.
+                    if ("requirements" in payload)
+                        onRequirementsRef.current?.(payload.requirements);
+                    break;
+                }
                 case "submit-result": {
                     const resolve = submitResolverRef.current;
                     submitResolverRef.current = null;

package/components/ProductTemplateBuildForm.d.ts

@@ -14,6 +14,12 @@
 export type ProductTemplateBuildRequest = {
     productName: string;
     productTemplateName: string;
+    /** Config-screen values, forwarded verbatim to the product's build
+     *  endpoint. May additionally carry `$advancedDefaults` — create-time
+     *  custom defaults from the Custom defaults disclosure, in the
+     *  ProductTemplateAdvanced per-knob `{ default }` shape — which a
+     *  dev-kit-generated product splits off before its strict config parse
+     *  and bakes into the manifest's `advanced` block. */
     formValues: Record<string, unknown>;
 };
 export type ProductTemplateBuildOutcome<TProductTemplate> = {
@@ -23,10 +29,13 @@ export type ProductTemplateBuildOutcome<TProductTemplate> = {
     ok: false;
     error: string;
 };
-export declare function ProductTemplateBuildForm<TProductTemplate>({ productName, configScreenUrl, onClose, onSubmit, onSaved, onSavedAndLaunch, }: {
+export declare function ProductTemplateBuildForm<TProductTemplate>({ productName, configScreenUrl, onClose, onSubmit, onSaved, onSavedAndLaunch, onRequirements, }: {
     productName: string;
     configScreenUrl: string | null;
     onClose: () => void;
+    /** Forwarded from the config-screen iframe: the product's suggested placement
+     *  requirements (raw payload; the consumer validates). Optional. */
+    onRequirements?: (requirements: unknown) => void;
     /**
      * Persists the product template. Implementation owns the wire protocol —
      * runner stores on disk; manager submits to manager-daemon. Returns the

package/components/ProductTemplateBuildForm.js

@@ -1,11 +1,40 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { X } from "lucide-react";
+import { ChevronDown, ChevronRight, X } from "lucide-react";
 import { useRef, useState } from "react";
 import toast from "react-hot-toast";
 import { validateInstanceId } from "../validate.js";
 import { ProductIframe } from "./ProductIframe.js";
 import { useUIPrimitives } from "./ui-primitives.js";
-export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose, onSubmit, onSaved, onSavedAndLaunch, }) {
+const emptyAdvancedDefaults = {
+    networkMode: "",
+    hostPorts: "",
+    containerUser: "",
+    shmSize: "",
+    openFileLimit: "",
+};
+/** Assemble the disclosure's draft into the ProductTemplateAdvanced per-knob
+ *  `{ default }` shape. Only set fields attach; undefined when untouched, so
+ *  the build request stays byte-identical for authors who ignore it. */
+function assembleAdvancedDefaults(d) {
+    const out = {};
+    if (d.networkMode)
+        out.networkMode = { default: d.networkMode };
+    const ports = d.hostPorts
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (ports.length > 0)
+        out.hostPorts = { default: ports };
+    if (d.containerUser.trim())
+        out.containerUser = { default: d.containerUser.trim() };
+    if (d.shmSize.trim())
+        out.shmSize = { default: d.shmSize.trim() };
+    const limit = Number(d.openFileLimit);
+    if (d.openFileLimit.trim() && Number.isInteger(limit))
+        out.openFileLimit = { default: limit };
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose, onSubmit, onSaved, onSavedAndLaunch, onRequirements, }) {
     const { Button, Input, Label } = useUIPrimitives();
     const [productTemplateName, setProductTemplateName] = useState("");
     // The iframe can suggest a name derived from its current choices (#317).
@@ -19,6 +48,9 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
     // products that don't care about validation aren't required to emit).
     const [iframeValid, setIframeValid] = useState(true);
     const iframeRef = useRef(null);
+    const [defaultsOpen, setDefaultsOpen] = useState(false);
+    const [advancedDraft, setAdvancedDraft] = useState(emptyAdvancedDefaults);
+    const patchDraft = (patch) => setAdvancedDraft((d) => ({ ...d, ...patch }));
     const handleSuggestName = (name) => {
         setSuggestedName(name);
         if (!nameTouched)
@@ -46,6 +78,9 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
             }
             formValues = result.formValues;
         }
+        const advanced = assembleAdvancedDefaults(advancedDraft);
+        if (advanced)
+            formValues = { ...formValues, $advancedDefaults: advanced };
         const outcome = await onSubmit({ productName, productTemplateName, formValues });
         if (!outcome.ok) {
             toast.error(`Save product template failed: ${outcome.error}`);
@@ -83,5 +118,5 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
     return (_jsxs("div", { className: "mb-6 rounded-lg border border-zinc-700 bg-zinc-900 p-4", children: [_jsxs("div", { className: "flex items-center justify-between mb-4", children: [_jsxs("div", { children: [_jsxs("h4", { className: "text-sm font-semibold text-zinc-100", children: ["Create ", productName, " product template"] }), _jsx("p", { className: "text-xs text-zinc-500 mt-0.5", children: "Saves a reusable product template. Launch instances from it later." })] }), _jsx("button", { type: "button", onClick: onClose, className: "text-zinc-500 hover:text-zinc-300", children: _jsx(X, { size: 14 }) })] }), _jsxs("form", { onSubmit: handleSave, className: "space-y-4", children: [_jsxs("div", { children: [_jsx(Label, { children: "Product template name *" }), _jsx(Input, { value: productTemplateName, onChange: (e) => {
                                     setNameTouched(true);
                                     setProductTemplateName(e.target.value);
-                                }, placeholder: suggestedName || `e.g. ${productName}-prod`, required: true }), productTemplateNameError ? (_jsx("p", { className: "text-xs text-red-400 mt-1", children: productTemplateNameError })) : (_jsx("p", { className: "text-xs text-zinc-500 mt-1", children: "Lowercase letters, numbers, and hyphens only. Used to launch instances later." }))] }), configScreenUrl ? (_jsx(ProductIframe, { ref: iframeRef, productName: productName, configScreenUrl: configScreenUrl, onValidityChange: (v) => setIframeValid(v), onSuggestName: handleSuggestName })) : (_jsxs("p", { className: "text-xs text-zinc-500", children: ["Product manifest does not declare ", _jsx("code", { children: "ui.configScreenUrl" }), " \u2014 nothing to configure."] })), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "button", variant: "primary", disabled: !canSubmit, onClick: handleSaveAndLaunch, children: submitting ? "Working…" : "Save & Launch…" }), _jsx(Button, { type: "submit", variant: "default", disabled: !canSubmit, children: "Save" }), _jsx(Button, { type: "button", variant: "ghost", onClick: onClose, children: "Cancel" })] })] })] }));
+                                }, placeholder: suggestedName || `e.g. ${productName}-prod`, required: true }), productTemplateNameError ? (_jsx("p", { className: "text-xs text-red-400 mt-1", children: productTemplateNameError })) : (_jsx("p", { className: "text-xs text-zinc-500 mt-1", children: "Lowercase letters, numbers, and hyphens only. Used to launch instances later." }))] }), configScreenUrl ? (_jsx(ProductIframe, { ref: iframeRef, productName: productName, configScreenUrl: configScreenUrl, onValidityChange: (v) => setIframeValid(v), onSuggestName: handleSuggestName, ...(onRequirements ? { onRequirements } : {}) })) : (_jsxs("p", { className: "text-xs text-zinc-500", children: ["Product manifest does not declare ", _jsx("code", { children: "ui.configScreenUrl" }), " \u2014 nothing to configure."] })), _jsxs("div", { children: [_jsxs("button", { type: "button", onClick: () => setDefaultsOpen((v) => !v), className: "flex items-center gap-1.5 text-[10px] font-semibold uppercase tracking-widest text-zinc-500 hover:text-zinc-300", children: [defaultsOpen ? _jsx(ChevronDown, { size: 12 }) : _jsx(ChevronRight, { size: 12 }), "Custom defaults"] }), defaultsOpen && (_jsxs("div", { className: "mt-2", children: [_jsx("p", { className: "text-xs text-zinc-500 mb-2", children: "Launch-form defaults baked into this template's manifest. Operators can still override them per instance." }), _jsxs("div", { className: "flex flex-wrap gap-3", children: [_jsxs("div", { children: [_jsx(Label, { children: "Network mode" }), _jsxs("select", { "aria-label": "Network mode", value: advancedDraft.networkMode, onChange: (e) => patchDraft({ networkMode: e.target.value }), className: "block rounded border border-zinc-700 bg-zinc-900 px-3 py-1.5 text-sm text-zinc-100", children: [_jsx("option", { value: "", children: "product default" }), _jsx("option", { value: "docker", children: "docker" }), _jsx("option", { value: "hybrid", children: "hybrid" })] })] }), _jsxs("div", { className: "min-w-[14rem] flex-1", children: [_jsx(Label, { children: "Host ports" }), _jsx(Input, { "aria-label": "Host ports", placeholder: "e.g. 1935, 5001/udp, 9000:80@svc", value: advancedDraft.hostPorts, onChange: (e) => patchDraft({ hostPorts: e.target.value }) })] }), _jsxs("div", { children: [_jsx(Label, { children: "Container user" }), _jsx(Input, { "aria-label": "Container user", placeholder: "uid:gid", value: advancedDraft.containerUser, onChange: (e) => patchDraft({ containerUser: e.target.value }), className: "w-28" })] }), _jsxs("div", { children: [_jsx(Label, { children: "Shared memory size" }), _jsx(Input, { "aria-label": "Shared memory size", placeholder: "e.g. 8gb", value: advancedDraft.shmSize, onChange: (e) => patchDraft({ shmSize: e.target.value }), className: "w-24" })] }), _jsxs("div", { children: [_jsx(Label, { children: "Open file limit" }), _jsx(Input, { "aria-label": "Open file limit", type: "number", min: 1024, max: 1048576, placeholder: "runner default", value: advancedDraft.openFileLimit, onChange: (e) => patchDraft({ openFileLimit: e.target.value }), className: "w-32" })] })] })] }))] }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "button", variant: "primary", disabled: !canSubmit, onClick: handleSaveAndLaunch, children: submitting ? "Working…" : "Save & Launch…" }), _jsx(Button, { type: "submit", variant: "default", disabled: !canSubmit, children: "Save" }), _jsx(Button, { type: "button", variant: "ghost", onClick: onClose, children: "Cancel" })] })] })] }));
 }

package/iframe-protocol.d.ts

@@ -49,6 +49,12 @@ export type IframeChildMessage = {
     payload: {
         name: string;
     };
+} | {
+    v: 1;
+    type: "requirements";
+    payload: {
+        requirements: unknown;
+    };
 } | {
     v: 1;
     type: "dirty";

package/manifest-schema.d.ts

@@ -91,8 +91,8 @@ export declare const ManifestSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     targets: z.ZodArray<z.ZodEnum<{
-        "norsk-ctl": "norsk-ctl";
         "docker-compose": "docker-compose";
+        "norsk-ctl": "norsk-ctl";
     }>>;
     components: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -102,6 +102,55 @@ export declare const ManifestSchema: z.ZodObject<{
     runtime: z.ZodDefault<z.ZodObject<{
         sharedWorkingDirectory: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    requirements: z.ZodOptional<z.ZodObject<{
+        capacity: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        cores: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        gpu: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodObject<{
+                capacity: z.ZodOptional<z.ZodNumber>;
+                model: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                count: z.ZodOptional<z.ZodNumber>;
+                attributeMatches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        hostPorts: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                default: "default";
+                fixed: "fixed";
+                required: "required";
+            }>;
+            value: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     defaultProductTemplates: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         url: z.ZodString;

package/manifest-schema.js

@@ -1,3 +1,4 @@
+import { ProductTemplateRequirementsSchema } from "@norskvideo/ctl-product-template-schema";
 import { z } from "zod";
 const TargetSchema = z.enum(["norsk-ctl", "docker-compose"]);
 const SidebarEntrySchema = z.object({
@@ -137,6 +138,9 @@ export const ManifestSchema = z.object({
     targets: z.array(TargetSchema),
     components: z.array(ComponentDescSchema).default([]),
     runtime: RuntimeHintsSchema,
+    requirements: ProductTemplateRequirementsSchema.optional().meta({
+        description: "Optional default placement requirements the product suggests (requirements-authoring.md). Same fixed/default/required shape as a product template's manifest — norsk-mgr pre-fills the template + instance requirements editors from it, and the operator can edit. Omit if the product expresses no requirements (the editors default to blank). Products may also refine these live via the config-screen iframe.",
+    }),
     defaultProductTemplates: z.array(DefaultProductTemplateSchema).default([]).meta({
         description: "Product templates the runner auto-fetches at product-registration time. Each entry is GET'd against the product's base URL and stored under its `name` via the runner's product-template store. Lets a product offer 'zero-config' launch paths — operators add the product and immediately have a launchable product template without visiting configure.",
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "type": "module",
   "exports": {
     ".": {

package/product-template-parsing.js

@@ -47,6 +47,12 @@ export function parseProductTemplatesFile(raw, path) {
         };
         if (typeof entry.sha256 === "string")
             rec.sha256 = entry.sha256;
+        if (isRecord(entry.launchDefaults))
+            rec.launchDefaults = entry.launchDefaults;
+        if (Array.isArray(entry.suggestedSecurityGroups) &&
+            entry.suggestedSecurityGroups.every((l) => typeof l === "string")) {
+            rec.suggestedSecurityGroups = entry.suggestedSecurityGroups;
+        }
         if (isRecord(entry.source)) {
             if (entry.source.kind === "import" && typeof entry.source.fromFile === "string") {
                 rec.source = { kind: "import", fromFile: entry.source.fromFile };

package/product-template-record.d.ts

@@ -42,4 +42,17 @@ export interface ProductTemplateRecord {
     /** Lowercase hex SHA-256 of the source tar bytes. Optional for
      *  historic records that predate the field. */
     sha256?: string;
+    /** Template-author launch defaults — the fusion tier between the
+     *  manifest's advanced defaults and operator intent
+     *  (placement-requirements.md §7). Shape is norsk-ctl's
+     *  ProductTemplateLaunchConfig; validated by the store's writer and
+     *  authoritatively by the worker at launch. Rides launches as
+     *  template_launch_defaults_json. */
+    launchDefaults?: Record<string, unknown>;
+    /** Template-author security-group suggestions, by discovery-tag LABEL
+     *  (portable across deployments; ids are not). The launch UI pre-ticks
+     *  discovered groups whose label matches — a suggestion the operator
+     *  can untick, never a pin, and never a wire field of its own: the
+     *  confirmed selection rides the job as extraSecurityGroups ids. */
+    suggestedSecurityGroups?: string[];
 }