@norskvideo/ctl-dev-kit 0.1.96 → 0.1.98

package/build/flake.lock

@@ -16,9 +16,26 @@
         "type": "github"
       }
     },
+    "nixpkgs-biome": {
+      "locked": {
+        "lastModified": 1785602060,
+        "narHash": "sha256-z7D96eESRM4CPV/XtwpwFn8IDdfLAmxz6lVWrGYXvR4=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "a5cbcfe954791221bfffe2307f7d1a1bf61a871e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "a5cbcfe954791221bfffe2307f7d1a1bf61a871e",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-biome": "nixpkgs-biome"
       }
     }
   },

package/build/flake.nix

@@ -36,13 +36,13 @@
 
       # --- norsk-ctl channel pin -------------------------------------------
       # The released daemon, one build per platform. Bump these together.
-      ctlVersion = "0.1.0-2026-07-29-a968793";
+      ctlVersion = "0.1.0-2026-09-15-81bbde8";
       ctlBase = "https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl";
       ctlAsset = {
-        "x86_64-linux"   = { plat = "linux-x64";    hash = "sha256-F2F1iX4V10mB4n72qIMknHoCohOeiLCLB20BQJtuGU4="; };
-        "aarch64-linux"  = { plat = "linux-arm64";  hash = "sha256-Qnc8xsAm2r1XWAWIBYWPcUKn/Q+Xxs9kdwLq1fubb6M="; };
-        "aarch64-darwin" = { plat = "darwin-arm64"; hash = "sha256-u7kAbgpmAVgpPXBgsEDiVGzLxwfZZDoZgqw2j9NwQeg="; };
-        "x86_64-darwin"  = { plat = "darwin-x64";   hash = "sha256-cTgyuZD/W/6dVXTd1/17KIbks3FmBVOOntqoMoJwZ7s="; };
+        "x86_64-linux"   = { plat = "linux-x64";    hash = "sha256-6Zm1iLs29o89tav+TEDfLLdq2E+blku7DSxZVAqEwF0="; };
+        "aarch64-linux"  = { plat = "linux-arm64";  hash = "sha256-ziH0YFLc8j7+xuYWArCU1JzWgq3NsFvfq67FqjlxdI8="; };
+        "aarch64-darwin" = { plat = "darwin-arm64"; hash = "sha256-A6uDgurkpYTwIdd7KwLv9oFNOLbGcoMgGLRW9SLuscw="; };
+        "x86_64-darwin"  = { plat = "darwin-x64";   hash = "sha256-GzlT0Rg9t8sAG6e7Deu+DzSbfSxcr+WpVmyOgit2Q4g="; };
       };
 
       mkCtl = system:

package/create-product/cli.ts

@@ -5,18 +5,36 @@
 // so the bin runs under bun (the fleet's only runtime).
 import { existsSync, readdirSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { createProduct, type ProductShape } from "./create-product.ts";
+import { createProduct, type ProductFeature, type ProductShape, type StudioLibrary } from "./create-product.ts";
+
+const SHAPES: ProductShape[] = ["backend-turnkey", "turnkey"];
 
 const USAGE = `Usage:
   ctl-dev-kit create-product --name <name> [options] <dir>
 
 Options:
-  --shape <shape>       Repo shape (default: backend-turnkey; the only shape yet)
+  --shape <shape>       Repo shape — a preset over the features below (default: backend-turnkey)
+                          backend-turnkey  no features (reuters-shaped)
+                          turnkey          components,views,frontend (oracle-shaped)
+  --with <f,...>        Add features on top of the shape's preset
+  --without <f,...>     Drop features from the shape's preset
+                          components  custom Studio nodes packed into the template tar
+                          views       operator screen inside Studio's workflow view (needs components)
+                          dashboard   operator screen as a standalone SPA (needs components)
+                          frontend    the configure screen ctl iframes
   --name <name>         Product name, e.g. norsk-acme (lowercase, digits, hyphens)
   --port <port>         Local-dev backend port (default: 4323; container is always 4321)
   --media-image <ref>   Full media image ref (repo:tag); norsk-sdk npm pin = its tag
   --studio-image <ref>  Full studio image ref (repo:tag)
   --studio-lib <ver>    norsk-studio* npm pin (default: the studio image's tag)
+  --studio-libs <l,...> Studio component libraries beyond built-ins the workflow uses: alpha, beta
+                          (e.g. alpha for processor.reasoning) — pinned, typed, and loaded by Studio
+
+Examples:
+  ctl-dev-kit create-product --name norsk-acme ./acme                        # backend only
+  ctl-dev-kit create-product --name norsk-acme --shape turnkey ./acme        # + component views
+  ctl-dev-kit create-product --name norsk-acme --shape turnkey \\
+      --with dashboard --without views ./acme                                # + a dashboard SPA instead
 `;
 
 function fail(message: string): never {
@@ -35,20 +53,21 @@ export function main(argv: string[]): void {
     allowPositionals: true,
     options: {
       shape: { type: "string", default: "backend-turnkey" },
+      with: { type: "string" },
+      without: { type: "string" },
       name: { type: "string" },
       port: { type: "string" },
       "media-image": { type: "string" },
       "studio-image": { type: "string" },
       "studio-lib": { type: "string" },
+      "studio-libs": { type: "string" },
     },
   });
   const dir = positionals[0];
   if (!dir) fail("missing <dir>.");
   if (!values.name) fail("missing --name.");
-  if (values.shape !== "backend-turnkey") {
-    fail(
-      `unknown shape ${JSON.stringify(values.shape)} — shapes: backend-turnkey (turnkey and product are follow-ups).`,
-    );
+  if (!SHAPES.includes(values.shape as ProductShape)) {
+    fail(`unknown shape ${JSON.stringify(values.shape)} — shapes: ${SHAPES.join(", ")}.`);
   }
   if (existsSync(dir) && readdirSync(dir).length > 0) {
     fail(`${dir} exists and is not empty — refusing to overwrite.`);
@@ -58,25 +77,46 @@ export function main(argv: string[]): void {
     fail(`--port must be an integer in 1..65535, got ${JSON.stringify(values.port)}.`);
   }
 
-  const { files } = createProduct({
-    dir,
-    name: values.name,
-    shape: values.shape as ProductShape,
-    devPort,
-    mediaImage: values["media-image"],
-    studioImage: values["studio-image"],
-    studioLib: values["studio-lib"],
-  });
+  // Comma-separated so one flag carries a set; the resolver validates the names.
+  const csvList = <T extends string>(raw: string | undefined): T[] | undefined =>
+    raw === undefined
+      ? undefined
+      : (raw
+          .split(",")
+          .map((f) => f.trim())
+          .filter(Boolean) as T[]);
+
+  // The resolver throws on a name, feature or combination it cannot honour;
+  // the operator asked for something impossible, not hit a bug, so report the
+  // reason and the usage rather than a stack trace.
+  let files: string[];
+  try {
+    ({ files } = createProduct({
+      dir,
+      name: values.name,
+      shape: values.shape as ProductShape,
+      withFeatures: csvList<ProductFeature>(values.with),
+      withoutFeatures: csvList<ProductFeature>(values.without),
+      devPort,
+      mediaImage: values["media-image"],
+      studioImage: values["studio-image"],
+      studioLib: values["studio-lib"],
+      studioLibs: csvList<StudioLibrary>(values["studio-libs"]),
+    }));
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
 
   console.log(`Generated ${files.length} files into ${dir} (shape: ${values.shape}).
 
-Next steps (also in the generated CLAUDE.md):
-  1. cd ${dir} && git init && bun install
-  2. UPDATE_SNAPSHOTS=1 bun run test:unit   # bake the byte-snapshot fixtures, commit them
-  3. bun run docs:handover                # once a daemon has this product added: fills docs/handover.md from the launch truth
-  3. bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck
-  4. Replace the starter graph in shared/src/workflow/ with the real one,
+Next steps (also in the generated CLAUDE.md and README):
+  1. cd ${dir} && nix develop                # the dev shell: pinned bun, biome and norsk-ctl
+  2. git init && bun install
+  3. UPDATE_SNAPSHOTS=1 bun run test:unit   # bake the byte-snapshot fixtures, commit them
+  4. bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck && bun run lint
+  5. Replace the starter graph in shared/src/workflow/ with the real one,
      keeping INVARIANTS.md and its rules tests in step.
+  6. bun run docs:handover                  # once a daemon has this product added: fills docs/handover.md from the launch truth
 `);
 }
 

package/create-product/create-product.ts

@@ -4,17 +4,39 @@
 //   - the CONVENTION layer (this file): every file the drift gate checks,
 //     identical across shapes, with the per-repo fill-ins placed exactly where
 //     the gate masks or leaves structure free;
-//   - the SHAPE layer (backend-turnkey.ts, ...): the source skeleton — package
-//     manifests, manifest/composer/materials modules, the five test tiers.
+//   - the SHAPE layer (turnkey.ts + features/): the source skeleton — package
+//     manifests, manifest/composer/materials modules, the five test tiers —
+//     with the optional workspaces (components, operator screen, configure
+//     screen) added by FEATURE, not by a second copy of the skeleton.
 //
-// New shapes (full turnkey, full product) slot in as additional ShapeModule
-// implementations; the convention layer is shared verbatim.
+// The convention layer is shared verbatim across every shape.
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { backendTurnkey } from "./backend-turnkey.ts";
 import { type Canon, loadAsset, loadCanon, PRODUCT_SENTINEL } from "./canon.ts";
+import { turnkey } from "./turnkey.ts";
 
-export type ProductShape = "backend-turnkey";
+// A SHAPE is a preset over FEATURES, not a separate skeleton — the four
+// product repos in the fleet are not a ladder (reuters: none; oracle:
+// components + views; funke/probe: components + dashboard + frontend), so
+// naming every combination would multiply shapes without adding anything.
+export type ProductShape = "backend-turnkey" | "turnkey";
+
+// - components  the components/ workspace: custom Studio nodes packed into the
+//               product-template tar (all three UI surfaces need one).
+// - views       the operator screen AS component summary/fullscreen React
+//               rendered inside Studio's own workflow view (oracle).
+// - dashboard   the operator screen as a standalone SPA built into
+//               dashboards/<workflow>/ and served by Studio (funke, probe).
+// - frontend    the product-level configure screen ctl iframes at
+//               ui.configScreenUrl (funke, probe).
+export type ProductFeature = "components" | "views" | "dashboard" | "frontend";
+
+const ALL_FEATURES: readonly ProductFeature[] = ["components", "views", "dashboard", "frontend"];
+
+const SHAPE_FEATURES: Record<ProductShape, readonly ProductFeature[]> = {
+  "backend-turnkey": [],
+  turnkey: ["components", "views", "frontend"],
+};
 
 export interface CreateProductOptions {
   dir: string;
@@ -27,11 +49,23 @@ export interface CreateProductOptions {
   mediaImage?: string;
   /** Full studio image ref (repo:tag). */
   studioImage?: string;
-  /** norsk-studio* npm pin; defaults to the studio image's bare tag (they
-   *  coincide when the published image matches the npm nightly). */
+  /** norsk-studio* npm pin; defaults to `studioImage`'s bare tag when one is
+   *  given, else to the default lib pin. */
   studioLib?: string;
+  /** Features to add on top of the shape's preset (`--with`). */
+  withFeatures?: ProductFeature[];
+  /** Features to drop from the shape's preset (`--without`). */
+  withoutFeatures?: ProductFeature[];
+  /** Studio component libraries beyond built-ins the workflow uses (`--studio-libs`). */
+  studioLibs?: StudioLibrary[];
 }
 
+export const STUDIO_LIBRARIES = ["alpha", "beta"] as const;
+export type StudioLibrary = (typeof STUDIO_LIBRARIES)[number];
+
+/** `@norskvideo/norsk-studio-<lib>` — the npm package and the Studio server.library entry. */
+export const studioPackage = (lib: StudioLibrary): string => `@norskvideo/norsk-studio-${lib}`;
+
 export interface GeneratedFile {
   path: string;
   content: string;
@@ -47,6 +81,8 @@ export interface ShapeContext {
   devPort: number;
   pins: { mediaImage: string; studioImage: string; studioLib: string; mediaLib: string };
   canon: Canon;
+  features: ReadonlySet<ProductFeature>;
+  studioLibs: StudioLibrary[];
 }
 
 export interface ShapeModule {
@@ -54,25 +90,69 @@ export interface ShapeModule {
   claudeHead(ctx: ShapeContext): string;
   claudeTail(ctx: ShapeContext): string;
   rootTsconfigInclude: string[];
+  /** Everything below the drift-gated core block in .gitignore — the build
+   *  output each enabled feature's workspace produces. */
+  gitignoreTail(ctx: ShapeContext): string;
 }
 
+// One skeleton, both shapes: the difference between them is entirely in ctx.features.
 const SHAPES: Record<ProductShape, ShapeModule> = {
-  "backend-turnkey": backendTurnkey,
+  "backend-turnkey": turnkey,
+  turnkey,
 };
 
-// Same known-good coherent set the monorepo's own test-harness pins. A fresh
+// Same known-good coherent set the dev-kit's own package.json pins. A fresh
 // repo's first upgrade-latest.yml run advances every one of these in lockstep.
-const DEFAULT_MEDIA_IMAGE = "norskvideo/norsk:1.0.402-2026-07-20-71aab79d";
-const DEFAULT_STUDIO_IMAGE = "norskvideo/norsk-studio:1.27.0-2026-07-21-fdea1794";
+const DEFAULT_MEDIA_IMAGE = "norskvideo/norsk:1.2.1-2026-09-15-a41445b4";
+const DEFAULT_STUDIO_IMAGE = "norskvideo/norsk-studio:1.29.0-2026-09-10-dcf40e7c";
+// Studio's npm packages and image ship from different commits, so the default
+// lib pin can't be derived from the default image's tag.
+const DEFAULT_STUDIO_LIB = "1.29.0-2026-09-10-b21d9013";
 
 const bareTag = (ref: string) => ref.slice(ref.lastIndexOf(":") + 1);
 
+export function resolveFeatures(opts: CreateProductOptions): Set<ProductFeature> {
+  const known = (names: ProductFeature[] | undefined, flag: string): ProductFeature[] => {
+    for (const name of names ?? []) {
+      if (!ALL_FEATURES.includes(name)) {
+        throw new Error(`unknown feature ${JSON.stringify(name)} in ${flag} — features: ${ALL_FEATURES.join(", ")}.`);
+      }
+    }
+    return names ?? [];
+  };
+  const features = new Set<ProductFeature>(SHAPE_FEATURES[opts.shape] ?? []);
+  for (const name of known(opts.withoutFeatures, "--without")) features.delete(name);
+  for (const name of known(opts.withFeatures, "--with")) features.add(name);
+
+  // The template manifest's runtimeScreenUrl names ONE screen (/studio/ for
+  // views, /dashboard/<workflow>/ for the SPA), so a seed carrying both would
+  // ship one the operator can never reach.
+  if (features.has("views") && features.has("dashboard")) {
+    throw new Error(
+      "features 'views' and 'dashboard' are two answers to the same question (where the operator screen lives) — pick one.",
+    );
+  }
+  // Both operator screens read a component's state: views render inside the
+  // component itself, the SPA talks to it over /live/api/<id>/*.
+  const screen = features.has("views") ? "views" : features.has("dashboard") ? "dashboard" : undefined;
+  if (screen && !features.has("components")) {
+    throw new Error(
+      `feature ${JSON.stringify(screen)} needs 'components' — the operator screen reads a component's state.`,
+    );
+  }
+  return features;
+}
+
 export function shapeContext(opts: CreateProductOptions): ShapeContext {
   if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(opts.name)) {
     throw new Error(
       `invalid product name ${JSON.stringify(opts.name)} — lowercase letters, digits, hyphens; 1-63 chars (it names the container image, npm scope, and manifest).`,
     );
   }
+  const unknownLibs = (opts.studioLibs ?? []).filter((lib) => !STUDIO_LIBRARIES.includes(lib));
+  if (unknownLibs.length > 0) {
+    throw new Error(`unknown studio libs ${unknownLibs.join(", ")} — known: ${STUDIO_LIBRARIES.join(", ")}.`);
+  }
   const mediaImage = opts.mediaImage ?? DEFAULT_MEDIA_IMAGE;
   const studioImage = opts.studioImage ?? DEFAULT_STUDIO_IMAGE;
   return {
@@ -83,10 +163,12 @@ export function shapeContext(opts: CreateProductOptions): ShapeContext {
     pins: {
       mediaImage,
       studioImage,
-      studioLib: opts.studioLib ?? bareTag(studioImage),
+      studioLib: opts.studioLib ?? (opts.studioImage ? bareTag(studioImage) : DEFAULT_STUDIO_LIB),
       mediaLib: bareTag(mediaImage),
     },
     canon: loadCanon(),
+    features: resolveFeatures(opts),
+    studioLibs: STUDIO_LIBRARIES.filter((lib) => opts.studioLibs?.includes(lib)),
   };
 }
 
@@ -101,13 +183,16 @@ function conventionFiles(ctx: ShapeContext, shape: ShapeModule): GeneratedFile[]
     { path: "tsconfig.base.json", content: canon.tsconfigBase },
     { path: "dprint.json", content: canon.dprint },
     {
+      // Hand-rolled rather than JSON.stringify'd: biome keeps a short array on
+      // one line, and a generated repo has to be lint-clean on its first run.
       path: "tsconfig.json",
-      content: `${JSON.stringify({ extends: "./tsconfig.base.json", include: shape.rootTsconfigInclude }, null, 2)}\n`,
-    },
-    {
-      path: ".gitignore",
-      content: `${canon.gitignoreCore}\n# Repo-specific entries go below (the block above is drift-gated verbatim).\n`,
+      content: `{
+  "extends": "./tsconfig.base.json",
+  "include": [${shape.rootTsconfigInclude.map((entry) => JSON.stringify(entry)).join(", ")}]
+}
+`,
     },
+    { path: ".gitignore", content: `${canon.gitignoreCore}\n${shape.gitignoreTail(ctx)}` },
     { path: ".github/workflows/checks.yml", content: fillProduct(canon.checks) },
     { path: ".github/workflows/upgrade-latest.yml", content: fillProduct(canon.upgradeLatest) },
     { path: ".github/workflows/sync-dev-kit.yml", content: fillProduct(canon.syncDevKit) },