@norskvideo/ctl-dev-kit 0.2.4 → 0.2.5

package/conventions/zod-singleton.ts

@@ -19,10 +19,10 @@
 // The invariant: the resolved graph carries exactly ONE zod 4 version. Nested
 // zod 3.x (a dev-only tool npm/bun isolates) is tolerated and only noted. Any
 // second distinct 4.x — the split — fails, and the fix is a single-version pin
-// in the root package.json `overrides`, matching the zod your @norskvideo/ctl-*
-// packages resolve (4.4.3 today). Do NOT pin products DOWN to satisfy norsk-ctl:
-// its 4.4.3 exists for an MCP-SDK typecheck that products do not perform — pin
-// UP to the version the rest of the tree wants and let ctl's copy dedupe onto it.
+// in the root package.json `overrides`, matching the exact zod the @norskvideo/ctl-*
+// packages depend on (create-product emits it as PRODUCT_ZOD). That is 4.4.3:
+// @modelcontextprotocol/sdk does not work with 4.5 whatever its range says, so
+// do not pin products up past it.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -89,8 +89,20 @@ export function checkZodSingleton(repoRoot: string): ZodSingletonResult {
   } else {
     const lock = parseBunLock(readFileSync(lockPath, "utf8"));
     const versions = new Map<string, string[]>(); // version -> the lock keys carrying it
+    const ctlZod = new Map<string, string[]>(); // exact zod a ctl-* package declares -> those packages
     for (const [key, entry] of Object.entries(lock.packages ?? {})) {
       const id = Array.isArray(entry) ? String(entry[0] ?? "") : "";
+      if (id.startsWith("@norskvideo/ctl-")) {
+        const meta = (Array.isArray(entry) ? entry[2] : undefined) as
+          | { dependencies?: Record<string, string> }
+          | undefined;
+        const declared = meta?.dependencies?.zod;
+        if (declared !== undefined && /^\d/.test(declared)) {
+          const pkgs = ctlZod.get(declared) ?? [];
+          pkgs.push(id.slice(0, id.lastIndexOf("@")));
+          ctlZod.set(declared, pkgs);
+        }
+      }
       if (!id.startsWith("zod@")) continue;
       const version = id.slice("zod@".length);
       const keys = versions.get(version) ?? [];
@@ -108,11 +120,22 @@ export function checkZodSingleton(repoRoot: string): ZodSingletonResult {
       errors.push(`bun.lock: unexpected zod ${v} (${keys.join(", ")}) — only zod 4 is permitted`);
     }
 
+    // The ctl-* packages pin zod exactly (4.4.3: @modelcontextprotocol/sdk does not
+    // work with 4.5 whatever its range says). A product's one zod must be that one.
+    const required = ctlZod.size === 1 ? [...ctlZod.keys()][0] : undefined;
+    if (ctlZod.size > 1) {
+      const detail = [...ctlZod].map(([v, pkgs]) => `    zod ${v}: ${pkgs.join(", ")}`).join("\n");
+      errors.push(
+        `bun.lock: the @norskvideo/ctl-* packages disagree on their zod —\n${detail}\n  Align their versions.`,
+      );
+    }
+
     if (v4.length === 0) {
       errors.push("bun.lock: no zod 4 resolved — expected exactly one");
     } else if (v4.length > 1) {
       const detail = v4.map(([v, keys]) => `    zod@${v}: ${keys.join(", ")}`).join("\n");
-      const suggested = v4.at(-1)?.[0];
+      const suggested =
+        required ?? v4.find(([, keys]) => keys.some((k) => k.startsWith("@norskvideo/ctl-")))?.[0] ?? v4.at(-1)?.[0];
       errors.push(
         `bun.lock: the zod graph is SPLIT across ${v4.length} versions —\n${detail}\n` +
           `  A schema crossing this boundary (e.g. ManifestSchema from @norskvideo/ctl-sdk\n` +
@@ -120,6 +143,12 @@ export function checkZodSingleton(repoRoot: string): ZodSingletonResult {
           `  package.json overrides — e.g. "overrides": { "zod": "${suggested}" } — matching\n` +
           `  the zod your @norskvideo/ctl-* packages resolve, then re-run bun install.`,
       );
+    } else if (required !== undefined && v4[0]?.[0] !== required) {
+      errors.push(
+        `bun.lock: zod resolves to ${v4[0]?.[0]}, but the @norskvideo/ctl-* packages pin ${required}.\n` +
+          `  Set "overrides": { "zod": "${required}" } in the root package.json and declare\n` +
+          `  zod ${required} in each workspace, then re-run bun install.`,
+      );
     }
   }
 

package/create-product/create-product.ts

@@ -126,6 +126,14 @@ const DEFAULT_MEDIA_IMAGE = `norskvideo/norsk:${devKitPin(devKitPackageJson, "@n
 const DEFAULT_STUDIO_IMAGE = "norskvideo/norsk-studio:1.29.0-2026-09-10-dcf40e7c";
 const DEFAULT_STUDIO_LIB = devKitPin(devKitPackageJson, "@norskvideo/norsk-studio");
 
+/** The one zod 4 a generated product resolves: pinned in its root `overrides`
+ *  and declared by every workspace that uses zod. Derived from the dev-kit's own
+ *  pin, the same exact version the published ctl-* packages depend on, so the
+ *  product's tree dedupes onto it instead of splitting beside a newer zod and
+ *  failing conventions/zod-singleton.ts on day one. It is held at 4.4.3 because
+ *  @modelcontextprotocol/sdk does not work with 4.5 despite its declared range. */
+export const PRODUCT_ZOD = devKitPin(devKitPackageJson, "zod");
+
 const bareTag = (ref: string) => ref.slice(ref.lastIndexOf(":") + 1);
 
 export function resolveFeatures(opts: CreateProductOptions): Set<ProductFeature> {

package/create-product/features/components.ts

@@ -12,7 +12,7 @@
 // (ours, and it emits the schema key verbatim rather than PascalCasing it);
 // copy-yamls is funke's, the only one carrying the external-globals plugin
 // that keeps react out of the browser bundle.
-import type { GeneratedFile, ShapeContext } from "../create-product.ts";
+import { type GeneratedFile, PRODUCT_ZOD, type ShapeContext } from "../create-product.ts";
 import { VIEWS_INFO_IMPORTS, VIEWS_INFO_RUNTIME } from "./views.ts";
 
 // The identifier the placeholder registers under, referenced from three
@@ -45,7 +45,7 @@ function packageJson(ctx: ShapeContext): string {
       dependencies: {
         "@norskvideo/ctl-oas-to-ts": "^0.1.0",
         react: "^19.0.0",
-        zod: "^4.3.6",
+        zod: PRODUCT_ZOD,
       },
       devDependencies: {
         "@norskvideo/norsk-sdk": ctx.pins.mediaLib,

package/create-product/turnkey.ts

@@ -13,7 +13,13 @@
 // from the schema package, addComponent/stubbedLibrary with a THROWING
 // validate(), INVARIANTS + parity + byte-snapshot + studio-load wired into
 // test:unit, and an image smoke tier.
-import { type GeneratedFile, type ShapeContext, type ShapeModule, studioPackage } from "./create-product.ts";
+import {
+  type GeneratedFile,
+  PRODUCT_ZOD,
+  type ShapeContext,
+  type ShapeModule,
+  studioPackage,
+} from "./create-product.ts";
 import { DOCS_SITE_GITIGNORE, DOCS_SITE_SCRIPTS, docsSiteFiles } from "./docs-site.ts";
 import {
   COMPONENTS_GITIGNORE,
@@ -361,6 +367,7 @@ function rootPackageJson(ctx: ShapeContext): string {
         ...optionalStudioPins(ctx),
         "@norskvideo/norsk-studio-builder": studioLib,
         "@norskvideo/norsk-studio-built-ins": studioLib,
+        zod: PRODUCT_ZOD,
       },
     },
     null,
@@ -430,7 +437,7 @@ function sharedPackageJson(ctx: ShapeContext): string {
         "@norskvideo/norsk-studio-builder": studioLib,
         "@norskvideo/norsk-studio-built-ins": studioLib,
         yaml: "^2.8.0",
-        zod: "^4.3.6",
+        zod: PRODUCT_ZOD,
       },
       devDependencies: {
         "@norskvideo/ctl-foundation": "^0.1.0",
@@ -1319,7 +1326,7 @@ function backendPackageJson(ctx: ShapeContext): string {
         "@norskvideo/norsk-studio-builder": ctx.pins.studioLib,
         cors: "^2.8.5",
         express: "^5.0.1",
-        zod: "^4.3.6",
+        zod: PRODUCT_ZOD,
       },
       devDependencies: {
         "@types/bun": "latest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",