@norskvideo/ctl-sdk 0.1.0 → 0.1.2

package/components/ProductTemplateBuildForm.js

@@ -31,16 +31,22 @@ export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose
     // caller can hand it off to its launch flow without waiting for a refetch),
     // null on failure.
     const saveProductTemplate = async () => {
-        if (!iframeRef.current) {
-            toast.error("Configuration not ready");
-            return null;
-        }
-        const result = await iframeRef.current.submit();
-        if (!result.ok) {
-            toast.error(result.error ?? "Configuration submission failed");
-            return null;
+        // No config screen declared: there is nothing to collect, so the build
+        // request carries empty form values rather than requiring an iframe.
+        let formValues = {};
+        if (configScreenUrl) {
+            if (!iframeRef.current) {
+                toast.error("Configuration not ready");
+                return null;
+            }
+            const result = await iframeRef.current.submit();
+            if (!result.ok) {
+                toast.error(result.error ?? "Configuration submission failed");
+                return null;
+            }
+            formValues = result.formValues;
         }
-        const outcome = await onSubmit({ productName, productTemplateName, formValues: result.formValues });
+        const outcome = await onSubmit({ productName, productTemplateName, formValues });
         if (!outcome.ok) {
             toast.error(`Save product template failed: ${outcome.error}`);
             return null;

package/frontend-spec.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ways a frontend's `index.css` drifts from deferring to the shared base. Empty
+ * means compliant. Each string is human-readable for a test failure message.
+ */
+export declare function stylingViolations(indexCss: string): string[];
+/** The sdk's vendored fonts directory, located relative to this module so it
+ *  resolves whether the sdk is a workspace sibling or an installed dependency —
+ *  the product no longer has to guess a `packages/sdk` monorepo path. */
+export declare function sharedFontsDir(): string;
+/**
+ * Whether a Vite dev server's `server.fs.allow` reaches the shared fonts. base.css
+ * lives outside a product's own Vite root, so without an allow entry covering it
+ * the dev server 403s the sibling font and the browser silently falls back to a
+ * system font (the guide-screenshot mismatch). True iff some allow base is an
+ * ancestor of the fonts dir. Allow bases that don't resolve are ignored.
+ */
+export declare function fsAllowCoversFonts(allow: readonly string[]): boolean;

package/frontend-spec.js

@@ -0,0 +1,53 @@
+// The shared styling-deference contract for product frontends: an app states no
+// styling opinion of its own beyond embed-specific rules — font, theme tokens and
+// resets all come from @norskvideo/ctl-sdk/base.css, whose @font-face url()s
+// resolve to the fonts vendored here. Three products carried a byte-identical
+// theme.test.ts asserting this; the judgment (what counts as drift, where the
+// shared fonts live) is centralised here so a fourth product can't fork it. The
+// vitest wrapper stays in each product's own theme.test.ts — it reads that
+// product's index.css and resolves that product's vite config — but delegates
+// every assertion to these pure helpers.
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const BASE_IMPORT = /@import\s+["']@norskvideo\/ctl-sdk\/base\.css["']/;
+/**
+ * Ways a frontend's `index.css` drifts from deferring to the shared base. Empty
+ * means compliant. Each string is human-readable for a test failure message.
+ */
+export function stylingViolations(indexCss) {
+    const out = [];
+    if (!BASE_IMPORT.test(indexCss))
+        out.push("does not @import @norskvideo/ctl-sdk/base.css");
+    if (/@font-face/.test(indexCss))
+        out.push("declares a local @font-face (fonts belong to the shared base)");
+    if (/--font-sans/.test(indexCss))
+        out.push("declares a local --font-sans (font tokens belong to the shared base)");
+    if (/fonts\.(googleapis|gstatic)\.com/.test(indexCss))
+        out.push("pulls a font from a CDN instead of the shared base");
+    return out;
+}
+/** The sdk's vendored fonts directory, located relative to this module so it
+ *  resolves whether the sdk is a workspace sibling or an installed dependency —
+ *  the product no longer has to guess a `packages/sdk` monorepo path. */
+export function sharedFontsDir() {
+    return realpathSync(join(dirname(fileURLToPath(import.meta.url)), "fonts"));
+}
+/**
+ * Whether a Vite dev server's `server.fs.allow` reaches the shared fonts. base.css
+ * lives outside a product's own Vite root, so without an allow entry covering it
+ * the dev server 403s the sibling font and the browser silently falls back to a
+ * system font (the guide-screenshot mismatch). True iff some allow base is an
+ * ancestor of the fonts dir. Allow bases that don't resolve are ignored.
+ */
+export function fsAllowCoversFonts(allow) {
+    const fonts = sharedFontsDir();
+    return allow.some((base) => {
+        try {
+            return fonts.startsWith(realpathSync(base));
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/manifest-schema.d.ts

@@ -22,8 +22,8 @@ export declare const ManifestSchema: z.ZodObject<{
         healthCheckPath: z.ZodDefault<z.ZodString>;
         productMcpPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    ui: z.ZodObject<{
-        configScreenUrl: z.ZodString;
+    ui: z.ZodDefault<z.ZodObject<{
+        configScreenUrl: z.ZodOptional<z.ZodString>;
         instanceConfigScreenUrl: z.ZodOptional<z.ZodString>;
         sidebarEntries: z.ZodDefault<z.ZodArray<z.ZodObject<{
             label: z.ZodString;
@@ -39,8 +39,8 @@ export declare const ManifestSchema: z.ZodObject<{
             label: z.ZodString;
             configScreenUrl: z.ZodString;
         }, z.core.$strip>>>;
-    }, z.core.$strip>;
-    cli: z.ZodObject<{
+    }, z.core.$strip>>;
+    cli: z.ZodDefault<z.ZodObject<{
         subcommandTree: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
@@ -53,6 +53,7 @@ export declare const ManifestSchema: z.ZodObject<{
                     number: "number";
                     boolean: "boolean";
                 }>>;
+                choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>>;
             subcommands: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -66,6 +67,7 @@ export declare const ManifestSchema: z.ZodObject<{
                         number: "number";
                         boolean: "boolean";
                     }>>;
+                    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 }, z.core.$strip>>>;
                 request: z.ZodOptional<z.ZodObject<{
                     method: z.ZodEnum<{
@@ -87,7 +89,7 @@ export declare const ManifestSchema: z.ZodObject<{
                 path: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     targets: z.ZodArray<z.ZodEnum<{
         "norsk-ctl": "norsk-ctl";
         "docker-compose": "docker-compose";
@@ -110,4 +112,9 @@ export declare const ManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Manifest = z.infer<typeof ManifestSchema>;
+/** Producer-facing shape: everything the reader defaults is optional, so a
+ *  product's buildManifest() sends only what it actually declares instead of
+ *  `sidebarEntries: []`-style boilerplate. The parsed {@link Manifest} keeps
+ *  those fields present, so runner code needs no null-guards. */
+export type ManifestInput = z.input<typeof ManifestSchema>;
 export {};

package/manifest-schema.js

@@ -31,6 +31,9 @@ const CliFlagSchema = z.object({
     description: z.string(),
     required: z.boolean().optional(),
     type: z.enum(["string", "number", "boolean"]).optional(),
+    choices: z.array(z.string()).optional().meta({
+        description: "Allowed values for the flag. The runner's CLI rejects anything else and lists them in help output. Omit for free-form flags.",
+    }),
 });
 /** How a CLI leaf forwards to the product's HTTP surface. The runner registers
  *  a yargs command that issues `method` against `/products/<name><path>` (the
@@ -106,8 +109,11 @@ export const ManifestSchema = z.object({
             description: "Path on the product control-plane's HTTP surface where it serves an always-on, instance-independent MCP endpoint (e.g. plugin scaffolding). Proxied as `<product>_<tool>`. Distinct from the per-instance `mcpPath`. Omit for products without one.",
         }),
     }),
-    ui: z.object({
-        configScreenUrl: z.string(),
+    ui: z
+        .object({
+        configScreenUrl: z.string().optional().meta({
+            description: "URL (on the product's HTTP surface) of the configure screen the runner iframes to build product templates. Omit for backend-only products with no configure UI — the runner skips its registration probe and the UI offers a config-free build path instead of an iframe.",
+        }),
         // Optional rich instance-launch config screen. When present, the runner's
         // launch flow probes it (a GET carrying product-template context); the
         // product returns 200 to have the runner iframe it in place of the
@@ -121,10 +127,13 @@ export const ManifestSchema = z.object({
         sidebarEntries: z.array(SidebarEntrySchema).default([]),
         dashboardWidgets: z.array(DashboardWidgetSchema).default([]),
         productTemplateActions: z.array(ProductTemplateActionSchema).default([]),
-    }),
-    cli: z.object({
+    })
+        .default({ sidebarEntries: [], dashboardWidgets: [], productTemplateActions: [] }),
+    cli: z
+        .object({
         subcommandTree: z.array(CliCommandSchema).default([]),
-    }),
+    })
+        .default({ subcommandTree: [] }),
     targets: z.array(TargetSchema),
     components: z.array(ComponentDescSchema).default([]),
     runtime: RuntimeHintsSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +15,10 @@
       "types": "./components/index.d.ts",
       "default": "./components/index.js"
     },
+    "./frontend-spec": {
+      "types": "./frontend-spec.d.ts",
+      "default": "./frontend-spec.js"
+    },
     "./manifest-seed": {
       "types": "./manifest-seed.d.ts",
       "default": "./manifest-seed.js"

package/product-template-error.d.ts

@@ -5,6 +5,6 @@
  * path (used by mgr — name validation + bytes persistence).
  */
 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";
-    constructor(code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE", message: string);
+    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);
 }

package/workflow.d.ts

@@ -39,6 +39,14 @@ export declare const VIDEO_ONLY: SubscriptionStreams;
 export declare const AUDIO_ONLY: SubscriptionStreams;
 export declare const FIRST_VIDEO: SubscriptionStreams;
 export declare const FIRST_AUDIO: SubscriptionStreams;
+export type ComponentAdder<Handle> = {
+    addNode(identifier: string, config: never): Handle;
+};
+export declare function addComponent<Handle, C extends object>(builder: ComponentAdder<Handle>, component: WorkflowComponent<C>): Handle;
+export type DocumentSource = {
+    toDocument(): unknown;
+};
+export declare function toWorkflowDoc<D extends WorkflowDoc = WorkflowDoc>(builder: DocumentSource): D;
 export type SyntheticNodeInfo = {
     identifier: string;
     subscription: {
@@ -57,4 +65,36 @@ export type SyntheticNodeInfo = {
         };
     };
 };
+export type ComponentStubMedia = "video" | "audio" | "subtitle" | "ancillary" | "playlist";
+export type ComponentStubSpec = {
+    identifier: string;
+    accepts?: ComponentStubMedia[];
+    produces?: ComponentStubMedia[] | "passthrough";
+    acceptsTransient?: boolean;
+    validateConfig?: (config: Record<string, unknown>) => string[] | undefined;
+};
+type StubMediaFlags = {
+    [M in ComponentStubMedia]?: true;
+};
+export type StubNodeInfo = {
+    identifier: string;
+    subscription: {
+        accepts?: {
+            type: "simple-stream";
+            acceptsTransient: boolean;
+        } & StubMediaFlags;
+        produces?: ({
+            type: "simple-stream";
+        } & StubMediaFlags) | {
+            type: "dynamic-streams";
+            streams: <S>(cfg: unknown, inputStreams: S) => S;
+        };
+    };
+    validateConfig?: (config: Record<string, unknown>) => string[] | undefined;
+};
+export declare function stubNodeInfo<T = StubNodeInfo>(spec: ComponentStubSpec): T;
+export declare function stubbedLibrary<Info = StubNodeInfo>(find: (identifier: string) => Info | undefined, stubs: ComponentStubSpec[]): {
+    find(identifier: string): Info | undefined;
+};
 export declare function syntheticInfo<T = SyntheticNodeInfo>(identifier: string): T;
+export {};

package/workflow.js

@@ -26,6 +26,76 @@ export const FIRST_AUDIO = {
     type: "take-first-stream",
     filter: [{ media: "audio" }],
 };
+// Typed `addNode` boundary: adds a factory-built component to a WorkflowBuilder
+// with the factory's config typing intact, so composers need no `config as
+// never` at the add boundary. Subscriptions are NOT applied — wiring goes
+// through the builder's connect()/pick* helpers, exactly as every product's
+// local add() helper behaved. The single cast below is the one audited erasure:
+// the builder's `BaseConfig` constraint wants an index signature that interface-
+// declared product configs may lack, while the real gates stay intact — the
+// factory return type checks the config shape at construction, and
+// builder.validate() runs each node's real validateConfig at compose time.
+export function addComponent(builder, component) {
+    return builder.addNode(component.type, component.config);
+}
+// Typed `toDocument` boundary: the builder returns its all-optional YamlDocument
+// shape, which products immediately re-assert as their WorkflowDoc (previously
+// via `as unknown as WorkflowDoc` at every call site). Sound by construction:
+// the builder always emits a components array, and each entry carries the
+// type/config/subscriptions the composer added. Pass a product-extended doc
+// type (e.g. probe's signed document) as `D` when the product adds fields.
+export function toWorkflowDoc(builder) {
+    return builder.toDocument();
+}
+function mediaFlags(media) {
+    return Object.fromEntries(media.map((m) => [m, true]));
+}
+// A builder NodeInfo from a metadata-only stub declaration. Unlike
+// syntheticInfo's accept-anything fallback, the resulting info carries the
+// component's REAL media contract, so edges into and out of the stub
+// stream-validate like any built-in (only its config stays unvalidated unless
+// the spec supplies validateConfig).
+export function stubNodeInfo(spec) {
+    const accepts = spec.accepts
+        ? {
+            accepts: {
+                type: "simple-stream",
+                ...mediaFlags(spec.accepts),
+                acceptsTransient: spec.acceptsTransient ?? true,
+            },
+        }
+        : {};
+    const produces = spec.produces === "passthrough"
+        ? {
+            produces: {
+                type: "dynamic-streams",
+                streams: (_cfg, inputStreams) => inputStreams,
+            },
+        }
+        : spec.produces && spec.produces.length > 0
+            ? { produces: { type: "simple-stream", ...mediaFlags(spec.produces) } }
+            : {};
+    return {
+        identifier: spec.identifier,
+        subscription: { ...accepts, ...produces },
+        ...(spec.validateConfig ? { validateConfig: spec.validateConfig } : {}),
+    };
+}
+// A ComponentLibrary that resolves the real library first and declared stubs
+// second — and, crucially, NOTHING else: an identifier that is neither real nor
+// declared stays unresolved, so the builder's addNode throws on it instead of
+// silently composing against a permissive synthetic. This is what lets
+// builder.validate() be a throwing gate fleet-wide — every node is either a
+// real NodeInfo or an explicitly declared stub, and a typo fails the compose.
+export function stubbedLibrary(find, stubs) {
+    const stubInfos = new Map();
+    for (const spec of stubs) {
+        if (stubInfos.has(spec.identifier))
+            throw new Error(`duplicate component stub: ${spec.identifier}`);
+        stubInfos.set(spec.identifier, stubNodeInfo(spec));
+    }
+    return { find: (identifier) => find(identifier) ?? stubInfos.get(identifier) };
+}
 // A permissive builder NodeInfo for an identifier the real component library
 // does not know (a product's own component, or an alpha/custom node that lives
 // only in the running studio image). It accepts any media and PASSES INPUT