@cosmicdrift/kumiko-framework 0.247.0 → 0.248.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.247.0",
+  "version": "0.248.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.247.0",
+    "@cosmicdrift/kumiko-types": "0.248.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.247.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.248.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/nav.test.ts

@@ -359,6 +359,91 @@ describe("validateBoot — nav validation", () => {
   });
 });
 
+// fw#2750: createAction + actions[] entries carry the same screen-XOR-target
+// polymorphism as the node itself — the validator must reject the same
+// classes of mistake for actions that it already rejects for nodes.
+describe("validateBoot — nav action validation (fw#2750)", () => {
+  test("createAction with neither screen nor target fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.nav({
+        id: "catalog",
+        label: "x",
+        createAction: { icon: "plus", label: "New" },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/createAction.*must set exactly one/);
+  });
+
+  test("createAction with both screen and target fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+      r.nav({
+        id: "catalog",
+        label: "x",
+        createAction: {
+          icon: "plus",
+          label: "New",
+          screen: "shop:screen:products",
+          target: { featureId: "shop", action: "create" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/createAction.*must set exactly one/);
+  });
+
+  test("actions[] entry referencing an unregistered screen fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.nav({
+        id: "catalog",
+        label: "x",
+        actions: [{ icon: "edit", label: "Edit", screen: "shop:screen:does-not-exist" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /actions\[0\] references screen "shop:screen:does-not-exist"/,
+    );
+  });
+
+  test("createAction with a target-only action still passes boot (regression)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.nav({
+        id: "catalog",
+        label: "x",
+        createAction: {
+          icon: "plus",
+          label: "New",
+          target: { featureId: "shop", action: "create" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("createAction with a screen-only action referencing a registered screen passes boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+      r.nav({
+        id: "catalog",
+        label: "x",
+        createAction: { icon: "plus", label: "New", screen: "shop:screen:products" },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});
+
 describe("nav access inversion warning (fw#2640)", () => {
   test("leaf role-gate disjoint from its parent section's → warns but boot still succeeds", () => {
     const warnSpy = spyOn(console, "warn").mockImplementation(() => {});

package/src/engine/boot-validator/nav.ts

@@ -63,6 +63,42 @@ export function validateNavs(
         }
       }
     }
+    if (navDef.createAction !== undefined) {
+      validateTreeAction(feature.name, navId, "createAction", navDef.createAction, allScreenQns);
+    }
+    for (const [i, action] of (navDef.actions ?? []).entries()) {
+      validateTreeAction(feature.name, navId, `actions[${i}]`, action, allScreenQns);
+    }
+  }
+}
+
+// A TreeAction (createAction or an actions[] entry) navigates via `screen`
+// XOR dispatches via `target` — same polymorphism as the node's own
+// `screen`/`target`. Without this check an action with neither is a
+// Hover-Icon that does nothing; one with both is ambiguous about which
+// click-mode wins.
+function validateTreeAction(
+  featureName: string,
+  navId: string,
+  actionPath: string,
+  action: { readonly screen?: string; readonly target?: unknown },
+  allScreenQns: ReadonlySet<string>,
+): void {
+  const { screen, target } = action;
+  const hasScreen = screen !== undefined;
+  const hasTarget = target !== undefined;
+  if (hasScreen === hasTarget) {
+    throw new Error(
+      `[Feature ${featureName}] Nav entry "${navId}" ${actionPath} must set exactly one of ` +
+        `"screen"/"target" (${hasScreen ? "both are set" : "neither is set"}).`,
+    );
+  }
+  if (screen !== undefined && !allScreenQns.has(screen)) {
+    throw new Error(
+      `[Feature ${featureName}] Nav entry "${navId}" ${actionPath} references screen ` +
+        `"${screen}" which is not registered. Expected a qualified name of the form ` +
+        `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
+    );
   }
 }