@cosmicdrift/kumiko-framework 0.247.0 → 0.249.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.247.0",
+  "version": "0.249.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.249.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.249.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/__tests__/screen-helpers.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { evalFieldCondition } from "../screen-helpers";
+import type { FieldCondition } from "../types/screen";
+
+describe("evalFieldCondition()", () => {
+  test("boolean forms pass through unchanged", () => {
+    expect(evalFieldCondition(true, {})).toBe(true);
+    expect(evalFieldCondition(false, {})).toBe(false);
+  });
+
+  test("eq matches when the field equals the given value", () => {
+    const cond: FieldCondition = { field: "status", eq: "active" };
+    expect(evalFieldCondition(cond, { status: "active" })).toBe(true);
+    expect(evalFieldCondition(cond, { status: "archived" })).toBe(false);
+  });
+
+  test("ne matches when the field differs from the given value", () => {
+    const cond: FieldCondition = { field: "status", ne: "archived" };
+    expect(evalFieldCondition(cond, { status: "active" })).toBe(true);
+    expect(evalFieldCondition(cond, { status: "archived" })).toBe(false);
+  });
+
+  test("in matches when the field is one of the given values", () => {
+    const cond: FieldCondition = { field: "status", in: ["draft", "active"] };
+    expect(evalFieldCondition(cond, { status: "active" })).toBe(true);
+    expect(evalFieldCondition(cond, { status: "archived" })).toBe(false);
+  });
+
+  test("notIn matches when the field is none of the given values", () => {
+    const cond: FieldCondition = { field: "status", notIn: ["draft", "archived"] };
+    expect(evalFieldCondition(cond, { status: "active" })).toBe(true);
+    expect(evalFieldCondition(cond, { status: "draft" })).toBe(false);
+  });
+
+  test("empty in is always false", () => {
+    const cond: FieldCondition = { field: "status", in: [] };
+    expect(evalFieldCondition(cond, { status: "active" })).toBe(false);
+    expect(evalFieldCondition(cond, {})).toBe(false);
+  });
+
+  test("empty notIn is always true", () => {
+    const cond: FieldCondition = { field: "status", notIn: [] };
+    expect(evalFieldCondition(cond, { status: "active" })).toBe(true);
+    expect(evalFieldCondition(cond, {})).toBe(true);
+  });
+
+  test("a missing field is undefined — in false, notIn true", () => {
+    const values: Record<string, unknown> = {};
+    expect(evalFieldCondition({ field: "status", in: ["active"] }, values)).toBe(false);
+    expect(evalFieldCondition({ field: "status", notIn: ["active"] }, values)).toBe(true);
+  });
+});

package/src/engine/boot-validator/action-wiring.ts

@@ -21,9 +21,10 @@ function throwIfFunction(value: unknown, message: string): void {
 // rowActions/toolbarActions carry row-context extractors (payload/params),
 // static visibility conditions and navigate entityId — all declarative-DSL-
 // only fields (RowFieldExtractor's `{ pick }`/`{ map }`, FieldCondition's
-// `{ field, eq }`/`{ field, ne }`, plain strings). A function literal here
-// does not type-check against these structural DSL types — it only reaches
-// here via a leaked `any`/`as any`, which this runtime check backstops.
+// `{ field, eq }`/`{ field, ne }`/`{ field, in }`/`{ field, notIn }`, plain
+// strings). A function literal here does not type-check against these
+// structural DSL types — it only reaches here via a leaked `any`/`as any`,
+// which this runtime check backstops.
 const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"] as const;
 
 function validateActionNoFunctions(
@@ -38,7 +39,7 @@ function validateActionNoFunctions(
       record[field],
       `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${action.id}" ${field} ` +
         `is a function — ${FUNCTION_DROPPED_HINT} Use the declarative DSL ({ pick }, { map }, ` +
-        `"fieldName", { field, eq }) instead.`,
+        `"fieldName", { field, eq }/{ field, in }) instead.`,
     );
   }
 }
@@ -78,7 +79,7 @@ function validateEditFieldNoFunctions(
       record[key],
       `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
         `${key} is a function — ${FUNCTION_DROPPED_HINT} Use a FieldCondition ` +
-        `(boolean or { field, eq }/{ field, ne }) instead.`,
+        `(boolean or { field, eq }/{ field, ne }/{ field, in }/{ field, notIn }) instead.`,
     );
   }
   throwIfFunction(

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.`,
+    );
   }
 }
 

package/src/engine/screen-helpers.ts

@@ -56,6 +56,8 @@ export function evalFieldCondition(cond: FieldCondition, values: Record<string,
   if (typeof cond === "boolean") return cond;
   const val = values[cond.field];
   if ("eq" in cond) return val === cond.eq;
+  if ("in" in cond) return cond.in.includes(val);
+  if ("notIn" in cond) return !cond.notIn.includes(val);
   return val !== cond.ne;
 }