@cosmicdrift/kumiko-framework 0.171.0 → 0.171.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.171.0",
+  "version": "0.171.2",
   "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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.171.0",
+    "@cosmicdrift/kumiko-types": "0.171.2",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.171.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.171.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -200,6 +200,25 @@ CREATE TABLE IF NOT EXISTS "read_widgets_v2" ("id" uuid PRIMARY KEY);
     expect(cap.err.join("\n")).toContain("read_widgets");
   });
 
+  test("migration creates a table with no snapshot entry → unexpected-table hint points at r.storeTable, not hand-fix", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    writeFileSync(
+      join(appCwd, "kumiko/migrations/0002_raw.sql"),
+      `-- hand-written table outside the entity system, never registered via r.storeTable
+CREATE TABLE IF NOT EXISTS "marketing_waitlist" ("id" uuid PRIMARY KEY);
+`,
+    );
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    const err = cap.err.join("\n");
+    expect(err).toContain("marketing_waitlist");
+    expect(err).toContain("Fix (unexpected-table)");
+    expect(err).toContain("r.storeTable");
+    expect(err).not.toContain("Fix (missing-table/column-drift)");
+  });
+
   test("no FEATURES export → validateBoot skipped (drift still checked)", async () => {
     writeSchemaFile(appCwd, "read_widgets");
     await runSchemaCli(["generate", "init"], appCwd, captureOut().out);

package/src/engine/__tests__/schema-builder.test.ts

@@ -419,6 +419,36 @@ describe("buildInsertSchema", () => {
     const schema = buildInsertSchema(entity);
     expect(schema.safeParse({ locale: "" }).success).toBe(false);
   });
+
+  // #1702: same ""-problem as #1674, but for a select WITH a default —
+  // an untouched <select> sends "" and the default only kicks in for
+  // undefined. "" maps to the default (a defaulted field is never unset).
+  test("optional select with default accepts empty string and falls back to the default", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en", "fr"] as const, default: "de" }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBe("de");
+    }
+  });
+
+  test("optional select with default still validates a real value", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en"] as const, default: "de" }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ locale: "en" }).success).toBe(true);
+    expect(schema.safeParse({ locale: "xx" }).success).toBe(false);
+  });
 });
 
 // --- Update schema (all partial) ---
@@ -489,4 +519,24 @@ describe("buildUpdateSchema", () => {
       expect(Object.hasOwn(result.data, "locale")).toBe(false);
     }
   });
+
+  // Update schemas strip defaults deliberately (buildUpdateSchema never
+  // applies them — omitting a field must leave it untouched). So "" maps
+  // to the same explicit clear-to-null as the no-default case; only the
+  // insert path falls back to the default (#1702).
+  test("optional select with default on update: empty string is a clear-to-null, not the default", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en"] as const, default: "de" }),
+      },
+    });
+
+    const schema = buildUpdateSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBeNull();
+    }
+  });
 });

package/src/engine/boot-validator/__tests__/access-roles.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import type { FeatureDefinition } from "../../types";
+import { warnOnUniqueAccessRoles } from "../access-roles";
+
+function fakeFeature(overrides: Partial<FeatureDefinition> & { name: string }): FeatureDefinition {
+  return {
+    writeHandlers: {},
+    queryHandlers: {},
+    streamHandlers: {},
+    ...overrides,
+  } as unknown as FeatureDefinition;
+}
+
+describe("warnOnUniqueAccessRoles", () => {
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn");
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("warns when a role is used by exactly one handler", () => {
+    const features = [
+      fakeFeature({
+        name: "users",
+        writeHandlers: {
+          "create-user": { name: "create-user", access: { roles: ["Admin"] } },
+        } as unknown as FeatureDefinition["writeHandlers"],
+      }),
+    ];
+
+    warnOnUniqueAccessRoles(features);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain("Admin");
+    expect(msg).toContain("users:write:create-user");
+  });
+
+  test("does NOT warn when the same role is used by two different handlers", () => {
+    const features = [
+      fakeFeature({
+        name: "users",
+        writeHandlers: {
+          "create-user": { name: "create-user", access: { roles: ["Admin"] } },
+        } as unknown as FeatureDefinition["writeHandlers"],
+      }),
+      fakeFeature({
+        name: "billing",
+        queryHandlers: {
+          "list-invoices": { name: "list-invoices", access: { roles: ["Admin"] } },
+        } as unknown as FeatureDefinition["queryHandlers"],
+      }),
+    ];
+
+    warnOnUniqueAccessRoles(features);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("does NOT warn for built-in roles 'all' or 'system' even when used by one handler", () => {
+    const features = [
+      fakeFeature({
+        name: "misc",
+        writeHandlers: {
+          "open-endpoint": { name: "open-endpoint", access: { roles: ["all"] } },
+        } as unknown as FeatureDefinition["writeHandlers"],
+      }),
+      fakeFeature({
+        name: "admin-tools",
+        streamHandlers: {
+          "audit-log": { name: "audit-log", access: { roles: ["system"] } },
+        } as unknown as FeatureDefinition["streamHandlers"],
+      }),
+    ];
+
+    warnOnUniqueAccessRoles(features);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/src/engine/boot-validator/access-roles.ts

@@ -0,0 +1,43 @@
+import type { FeatureDefinition } from "../types";
+
+const BUILTIN_ROLES = new Set(["all", "system"]);
+
+export function warnOnUniqueAccessRoles(features: readonly FeatureDefinition[]): void {
+  // role → set of distinct handler identifiers using it
+  const roleHandlers = new Map<string, Set<string>>();
+
+  for (const f of features) {
+    const handlerGroups = [
+      { type: "write", defs: f.writeHandlers },
+      { type: "query", defs: f.queryHandlers },
+      { type: "stream", defs: f.streamHandlers },
+    ] as const;
+
+    for (const { type, defs } of handlerGroups) {
+      for (const [handlerName, def] of Object.entries(defs)) {
+        if (!def.access || !("roles" in def.access)) continue;
+        const identifier = `${f.name}:${type}:${handlerName}`;
+        for (const role of def.access.roles) {
+          let handlers = roleHandlers.get(role);
+          if (!handlers) {
+            handlers = new Set();
+            roleHandlers.set(role, handlers);
+          }
+          handlers.add(identifier);
+        }
+      }
+    }
+  }
+
+  for (const [role, handlers] of roleHandlers) {
+    if (BUILTIN_ROLES.has(role)) continue;
+    if (handlers.size !== 1) continue;
+    const [identifier] = handlers;
+    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+    console.warn(
+      `[kumiko:boot] Access role "${role}" is only used by one handler (${identifier}). ` +
+        `This is often a typo — the role is unknown to every other handler in the boot scan. ` +
+        `If this is intentional, ignore this warning.`,
+    );
+  }
+}

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

@@ -1,6 +1,7 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
+import { warnOnUniqueAccessRoles } from "./access-roles";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
 import { validateFeatureBootChecks } from "./boot-check";
@@ -212,4 +213,5 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   validateConfigReads(features, allConfigKeys);
   warnOnToggleableDependencies(features, featureMap);
+  warnOnUniqueAccessRoles(features);
 }

package/src/engine/schema-builder.ts

@@ -81,7 +81,14 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       const [first, ...rest] = field.options;
       if (!first) return z.string();
       const enumSchema = z.enum([first, ...rest]);
-      if (field.default !== undefined) return enumSchema.default(field.default);
+      if (field.default !== undefined)
+        // Untouched <select> sends "" too; with a default that maps to the
+        // default (same semantics as undefined) instead of the invalid-value
+        // rejection from #1702. A field with a default is never "unset".
+        return z.preprocess(
+          (value) => (value === "" ? field.default : value),
+          enumSchema.default(field.default),
+        );
       if (field.required) return enumSchema;
       // Optional select without a default: an untouched HTML <select> submits
       // "" for its placeholder option. Treat that as "unset" (null) instead of

package/src/schema-cli.ts

@@ -287,9 +287,22 @@ export async function runSchemaCli(
             for (const m of mismatches) {
               out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
             }
-            out.err(
-              "    Fix: a migration file's body doesn't match what it (or the snapshot) claims — hand-fix the file, or ship a corrective migration if it's already applied in prod.",
-            );
+            if (mismatches.some((m) => m.kind === "unexpected-table")) {
+              out.err(
+                "    Fix (unexpected-table): register the raw/hand-written table via `table()` " +
+                  "(or `defineUnmanagedTable()`) from `@cosmicdrift/kumiko-framework/db`, then " +
+                  "`r.storeTable(meta, { reason: ... })` inside a feature — this adds it to " +
+                  "ENTITY_METAS and the snapshot without going through r.entity(). See the " +
+                  "bundled `jobs` feature's job-run-log store table for the pattern.",
+              );
+            }
+            if (mismatches.some((m) => m.kind !== "unexpected-table")) {
+              out.err(
+                "    Fix (missing-table/column-drift): a migration file's body doesn't match " +
+                  "what it (or the snapshot) claims — hand-fix the file, or ship a corrective " +
+                  "migration if it's already applied in prod.",
+              );
+            }
           }
         } catch (e) {
           // replayMigrationsDir fail-loud's on a table-DDL statement it can't