@cosmicdrift/kumiko-framework 0.236.1 → 0.237.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.236.1",
+  "version": "0.237.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.236.1",
+    "@cosmicdrift/kumiko-types": "0.237.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.236.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.237.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli.integration.test.ts

@@ -54,11 +54,13 @@ describe("runSchemaCli — no-DB paths", () => {
     expect(cap.err).toHaveLength(0);
   });
 
-  test("unknown subcommand falls through to usage", async () => {
+  test("unknown subcommand exits 1 and reports it on stderr", async () => {
     const cap = captureOut();
-    const code = await runSchemaCli(["lolwut"], appCwd, cap.out);
-    expect(code).toBe(0);
-    expect(cap.log.join("\n")).toContain("Subcommands:");
+    const code = await runSchemaCli(["cutover"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain('Unbekanntes Subcommand: "cutover"');
+    expect(cap.err.join("\n")).toContain("generate | validate | apply | baseline | status");
+    expect(cap.log).toHaveLength(0);
   });
 
   test("generate without name exits 1 with neutral usage wording", async () => {

package/src/engine/__tests__/entity-handlers.test.ts

@@ -16,7 +16,7 @@ import {
 import { createEntity, createTextField } from "../factories";
 // Barrel import, not "../entity-handlers": covers that entityListSchema is
 // actually re-exported through engine/index.ts.
-import { entityListSchema } from "../index";
+import { entityListSchema, resolveAgentExposure } from "../index";
 import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
@@ -367,4 +367,56 @@ describe("registerEntityCrud", () => {
     expect(Object.keys(entities)).toEqual(["note"]);
     expect(writes.map((w) => w.name)).toEqual(["note:create"]);
   });
+  test("descriptions: per-verb text lands on that verb only, and drives agent exposure", () => {
+    const { r, writes, queries } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity, {
+      descriptions: {
+        create: "Files a new note.",
+        list: "Lists notes newest first.",
+      },
+    });
+
+    const create = writes.find((w) => w.name === "note:create");
+    const update = writes.find((w) => w.name === "note:update");
+    const list = queries.find((q) => q.name === "note:list");
+    const detail = queries.find((q) => q.name === "note:detail");
+    if (!create || !update || !list || !detail) throw new Error("CRUD handlers missing");
+
+    expect(create.description).toBe("Files a new note.");
+    expect(list.description).toBe("Lists notes newest first.");
+    expect(update.description).toBeUndefined();
+    expect(detail.description).toBeUndefined();
+
+    // Fail-closed exposure is why the slot exists: only the described verbs
+    // reach the agent manifest.
+    expect(resolveAgentExposure(create, "write").expose).toBe(true);
+    expect(resolveAgentExposure(list, "query").expose).toBe(true);
+    expect(resolveAgentExposure(update, "write").expose).toBe(false);
+    expect(resolveAgentExposure(detail, "query").expose).toBe(false);
+  });
+
+  test("descriptions: per-verb entry wins over the write/read fallback", () => {
+    const { r, writes } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity, {
+      write: { description: "Shared write text." },
+      descriptions: { create: "Files a new note." },
+      verbs: { list: false, detail: false },
+    });
+
+    expect(writes.find((w) => w.name === "note:create")?.description).toBe("Files a new note.");
+    expect(writes.find((w) => w.name === "note:update")?.description).toBe("Shared write text.");
+  });
+
+  test("agent hints on the per-handler options raise the resolved risk", () => {
+    const del = defineEntityDeleteHandler("note", noteEntity, {
+      description: "Deletes a note permanently.",
+      agent: { risk: "high" },
+    });
+    const create = defineEntityCreateHandler("note", noteEntity, {
+      description: "Files a new note.",
+    });
+
+    expect(resolveAgentExposure(del, "write").risk).toBe("high");
+    expect(resolveAgentExposure(create, "write").risk).toBe("mid");
+  });
 });

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

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
 import { validateBoot as validateBootRaw } from "../boot-validator";
 import { defineFeature } from "../define-feature";
@@ -358,3 +358,55 @@ describe("validateBoot — nav validation", () => {
     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(() => {});
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "section", label: "s", access: { roles: ["Manager"] } });
+      r.nav({
+        id: "leaf",
+        label: "l",
+        parent: "shop:nav:section",
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Nav entry "shop:nav:leaf" requires roles [Admin]'),
+    );
+    warnSpy.mockRestore();
+  });
+
+  test("leaf role-gate overlapping its parent's → no warning", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "section", label: "s", access: { roles: ["Manager", "Admin"] } });
+      r.nav({
+        id: "leaf",
+        label: "l",
+        parent: "shop:nav:section",
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Nav entry"));
+    warnSpy.mockRestore();
+  });
+
+  test("parent open to everyone (unset access) → a role-gated leaf never warns", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "section", label: "s" });
+      r.nav({
+        id: "leaf",
+        label: "l",
+        parent: "shop:nav:section",
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Nav entry"));
+    warnSpy.mockRestore();
+  });
+});

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

@@ -42,6 +42,7 @@ import {
   collectWriteHandlerQns,
   validateNavCycles,
   validateNavs,
+  warnOnNavAccessInversion,
 } from "./nav";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
@@ -215,6 +216,7 @@ export function validateBoot(
   }
 
   validateNavCycles(allNavQns);
+  warnOnNavAccessInversion(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);

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

@@ -3,7 +3,7 @@
 // here since this is a structural move, not a semantic reorg).
 
 import { qualifyEntityName } from "../qualified-name";
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import type { AccessRule, FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
 
 export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
   const set = new Set<string>();
@@ -99,6 +99,41 @@ export function validateNavCycles(
   }
 }
 
+// undefined access or `{ openToAll: true }` both mean "visible to everyone"
+// — neither has a role-set an inversion check could compare against.
+function navViewerRoles(access: AccessRule | undefined): readonly string[] | undefined {
+  if (access === undefined || "openToAll" in access) return undefined;
+  return access.roles;
+}
+
+// fw#2640: warn (never throw — this is a real UX bug, not a broken ref)
+// when a nav leaf's role gate is disjoint from its parent section's — no
+// user who can see the section could ever see this child, so the section
+// renders with zero visible children for every user who reaches it.
+// Only fires when BOTH sides declare an explicit, non-empty role list:
+// an unset/openToAll side is visible to everyone, so it can't invert.
+export function warnOnNavAccessInversion(
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+): void {
+  for (const [qn, navDef] of allNavQns) {
+    if (navDef.parent === undefined) continue;
+    const parentDef = allNavQns.get(navDef.parent);
+    if (parentDef === undefined) continue; // dangling parent ref — validateNavs already throws for this
+    const parentRoles = navViewerRoles(parentDef.access);
+    const leafRoles = navViewerRoles(navDef.access);
+    if (parentRoles === undefined || leafRoles === undefined) continue;
+    if (parentRoles.length === 0) continue; // parent already visible to nobody — a different problem
+    if (leafRoles.some((role) => parentRoles.includes(role))) continue;
+    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+    console.warn(
+      `[kumiko:boot] Nav entry "${qn}" requires roles [${leafRoles.join(", ")}] but its parent ` +
+        `"${navDef.parent}" only allows [${parentRoles.join(", ")}] — no user who can see the ` +
+        `parent section could ever see this entry. If this is intentional, ignore this warning; ` +
+        `otherwise align the role sets.`,
+    );
+  }
+}
+
 // Roles we recognise at boot time. The framework has no explicit
 // role-registry (r.defineRoles is a type helper only), so we synthesise
 // one from every handler-access rule plus the "all"/"system" built-ins.

package/src/engine/define-handler.ts

@@ -78,6 +78,8 @@ export function defineWriteHandler<
     name: def.name,
     schema: def.schema,
     ...(def.access && { access: def.access }),
+    ...(def.description !== undefined && { description: def.description }),
+    ...(def.agent && { agent: def.agent }),
     ...(def.unsafeSkipTransitionGuard && {
       unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
     }),

package/src/engine/entity-handlers.ts

@@ -172,7 +172,7 @@ function parseHandlerName<TVerb extends string>(
 export function defineEntityWriteHandler(
   name: string,
   entity: EntityDefinition,
-  options?: { access?: AccessRule },
+  options?: EntityHandlerOptions,
 ): WriteHandlerDef {
   const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
   if (verb === "restore" && !entity.softDelete) {
@@ -253,6 +253,8 @@ export function defineEntityWriteHandler(
     schema,
     handler,
     ...(options?.access && { access: options.access }),
+    ...(options?.description !== undefined && { description: options.description }),
+    ...(options?.agent !== undefined && { agent: options.agent }),
   };
 }
 
@@ -282,7 +284,7 @@ function augmentDerivedFields(
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
-  options?: { access?: AccessRule; crossTenant?: boolean },
+  options?: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
 
@@ -367,6 +369,8 @@ export function defineEntityQueryHandler(
     schema,
     handler,
     ...(options?.access && { access: options.access }),
+    ...(options?.description !== undefined && { description: options.description }),
+    ...(options?.agent !== undefined && { agent: options.agent }),
     // The "list" verb's executor.list() always returns { rows, nextCursor,
     // total? } (see the handler body above) — brand it so the definition
     // site documents the PagedRows contract without needing
@@ -533,10 +537,12 @@ export function registerEntityCrud(
   const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
     ...writeOpts,
     access: options?.verbAccess?.[verb] ?? writeOpts?.access,
+    description: options?.descriptions?.[verb] ?? writeOpts?.description,
   });
   const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
     ...readOpts,
     access: options?.verbAccess?.[verb] ?? readOpts?.access,
+    description: options?.descriptions?.[verb] ?? readOpts?.description,
   });
 
   if (verbs.create) {

package/src/engine/factories.ts

@@ -439,6 +439,7 @@ export function createImagesField(
 export function createEntity<F>(def: {
   readonly table?: string;
   readonly fields: F;
+  readonly description?: string;
   readonly softDelete?: boolean;
   /** Event stream lives on SYSTEM_TENANT_ID (tenant-independent aggregate, e.g.
    *  user) instead of the creator's tenant. See EntityDefinition.systemStream. */

package/src/schema-cli.ts

@@ -447,6 +447,15 @@ export async function runSchemaCli(
     }
 
     default: {
+      // No subcommand (`kumiko schema`) is a help request → usage + exit 0.
+      // An unrecognized one (typo, e.g. `schema cutover`) must fail loud —
+      // silently exiting 0 here let a deploy's migrate step print help and
+      // move on without ever running a migration.
+      if (sub !== undefined) {
+        out.err(`  Unbekanntes Subcommand: "${sub}"`);
+        out.err("  Erlaubt: generate | validate | apply | baseline | status");
+        return 1;
+      }
       out.log("");
       out.log("  Subcommands:");
       out.log("    generate <name>   Schreibe neue Migration aus EntityTableMeta-Diff");