@cosmicdrift/kumiko-framework 0.105.2 → 0.109.0

package/src/schema-cli.ts

@@ -44,17 +44,28 @@ export type SchemaCliOut = {
 
 const SNAPSHOT_FILENAME = ".snapshot.json";
 
-async function loadEntityMetasFromApp(
-  schemaFile: string,
-): Promise<Parameters<typeof renderTablesDdl>[0]> {
+type SchemaMod = {
+  readonly entityMetas: Parameters<typeof renderTablesDdl>[0];
+  readonly features?: unknown;
+};
+
+// Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
+// both need ENTITY_METAS (and validate additionally wants FEATURES); this is
+// the one place that enforces "ENTITY_METAS must be an array" so the two
+// commands can't drift on the check or its wording. Throws — callers that
+// want a graceful exit code (validate) catch it themselves.
+async function loadSchemaModFromApp(schemaFile: string): Promise<SchemaMod> {
   // bun imports TS directly — no spawn needed.
-  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown };
+  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown; FEATURES?: unknown };
   if (!Array.isArray(mod.ENTITY_METAS)) {
     throw new Error(
       `Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
     );
   }
-  return mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+  return {
+    entityMetas: mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0],
+    features: mod.FEATURES,
+  };
 }
 
 function nextSequenceNumber(migrationsDir: string): number {
@@ -132,7 +143,7 @@ export async function runSchemaCli(
         out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
         return 1;
       }
-      const metas = await loadEntityMetasFromApp(schemaFile);
+      const { entityMetas: metas } = await loadSchemaModFromApp(schemaFile);
       const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
       const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       const result = generateMigration({
@@ -191,20 +202,18 @@ export async function runSchemaCli(
         out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
         return 1;
       }
-      const mod = (await import(schemaFile)) as {
-        ENTITY_METAS?: unknown;
-        FEATURES?: unknown;
-      };
-      if (!Array.isArray(mod.ENTITY_METAS)) {
-        out.err(
-          `  Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
-        );
+      let schemaMod: SchemaMod;
+      try {
+        schemaMod = await loadSchemaModFromApp(schemaFile);
+      } catch (e) {
+        out.err(`  ${e instanceof Error ? e.message : String(e)}`);
         return 1;
       }
+      const mod = { FEATURES: schemaMod.features };
       let ok = true;
 
       // 1. Schema drift — compute the diff, never write.
-      const metas = mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+      const metas = schemaMod.entityMetas;
       const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
       const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       const drift = generateMigration({

package/src/secrets/__tests__/contains-secret.test.ts

@@ -32,6 +32,18 @@ export type _R6TypeAssertions = [
   // the backstop. This is what keeps generic-over-response handlers compiling.
   Expect<Equal<ContainsSecret<unknown>, false>>,
   Expect<Equal<ContainsSecret<never>, false>>,
+  // 556/3: ContainsSecret<A | B> distributes over the union (naked type
+  // param) to `ContainsSecret<A> | ContainsSecret<B>` = `boolean`, not the
+  // literal `true` — pinned here so a future change to this predicate can't
+  // silently regress it. The actual leak-guard in define-handler.ts compares
+  // via `true extends ContainsSecret<TData>` (556/1) instead of `ContainsSecret<
+  // TData> extends true`, which is fail-closed for `boolean` either way.
+  Expect<Equal<ContainsSecret<{ ok: true } | { s: Secret<string> }>, boolean>>,
+  // 556/2: Map/Set are explicit SafeLeaf members now — pins that the runtime
+  // guard's "walk Map/Set entries separately" intent is mirrored, not an
+  // accidental compile-time blind spot.
+  Expect<Equal<ContainsSecret<Map<string, Secret<string>>>, false>>,
+  Expect<Equal<ContainsSecret<Set<Secret<string>>>, false>>,
 ];
 
 const schema = z.object({ q: z.string() });
@@ -57,6 +69,28 @@ function genericResponseHandler<K extends string>(kind: K) {
 }
 void genericResponseHandler;
 
+// 556/1: ContainsSecret<A | B> distributes over the union (naked type param
+// in the condition) to `ContainsSecret<A> | ContainsSecret<B>` = `boolean`,
+// not the literal `true` — a check written as `ContainsSecret<TData> extends
+// true` silently passes a union with a leak hidden in ONE branch. Both
+// assertions below must hold: the guard rejects the leaking union AND still
+// accepts the clean one, proving the fix (membership form on the phantom
+// param) is fail-closed for unions, not just for a bare Secret<>.
+declare const leakingUnion: { ok: true } | { apiKey: Secret<string> };
+// @ts-expect-error — R6: a Secret<> hidden in one union branch must still leak-guard
+defineQueryHandler({
+  name: "t:query:union-leak",
+  schema,
+  handler: async () => leakingUnion,
+});
+
+declare const cleanUnion: { ok: true } | { id: string };
+defineQueryHandler({
+  name: "t:query:union-clean",
+  schema,
+  handler: async () => cleanUnion,
+});
+
 describe("R6 ContainsSecret", () => {
   test("a clean query handler still builds — the guard param is invisible", () => {
     const def = defineQueryHandler({

package/src/secrets/types.ts

@@ -56,6 +56,11 @@ type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
 // Opaque built-in leaves a response legitimately carries; never recurse into
 // them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
+// Map/Set (556/2): `keyof Map<K,V>` yields method names, not V, so these
+// already fell through to `false` via the object-mapped-type branch — listed
+// explicitly here so the compile-time treatment matches leak-guard.ts's
+// runtime `instanceof Map`/`instanceof Set` branch (walk entries separately)
+// instead of looking like an oversight.
 type SafeLeaf =
   | Date
   | RegExp
@@ -66,7 +71,9 @@ type SafeLeaf =
   | Temporal.PlainTime
   | Temporal.PlainYearMonth
   | Temporal.PlainMonthDay
-  | Temporal.Duration;
+  | Temporal.Duration
+  | Map<unknown, unknown>
+  | Set<unknown>;
 
 export type ContainsSecret<T> = [T] extends [never]
   ? false

package/src/testing/db-cleanup.ts

@@ -32,7 +32,10 @@ function resolveClearableTable(table: ClearableTable): unknown {
 /** Delete all rows from each table (order preserved — FK-sensitive callers order explicitly). */
 export async function clearTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
   for (const table of tables) {
-    await deleteMany(db, resolveClearableTable(table), {});
+    // Test-teardown truncate: resolveClearableTable returns `unknown` (string
+    // name or table object). The brand-strip cast is the sanctioned bypass —
+    // clearing a managed projection between tests is not a production write.
+    await deleteMany(db, resolveClearableTable(table) as EntityTableMeta, {});
   }
 }
 

package/src/testing/index.ts

@@ -31,6 +31,7 @@ export {
   createRecordingProvider,
   type RecordingProvider,
 } from "./observability-recorder";
+export { deleteRows, seedRow, seedRows, updateRows } from "./seed";
 export {
   sharedItemEntity,
   sharedItemTable,

package/src/testing/seed.ts

@@ -0,0 +1,50 @@
+// Test-only ES-bypass: seed / mutate a managed projection directly, skipping
+// the event log. Production code CANNOT do this — the write helpers reject a
+// branded EntityTable at compile time (#742). Tests seed read-model state to
+// arrange a scenario without driving the full event path; a projection rebuild
+// is not part of the test lifecycle, so eventless writes are safe here. The
+// `as EntityTableMeta` strips the executor-only brand at this single sanctioned
+// seam — the signatures mirror the query helpers so a call-site migration is a
+// plain identifier rename.
+
+import {
+  type AnyDb,
+  deleteMany,
+  insertMany,
+  insertOne,
+  updateMany,
+  type WhereObject,
+} from "../bun-db/query";
+import type { EntityTableMeta } from "../db/entity-table-meta";
+import type { EntityTable } from "../db/table-builder";
+
+type SeedTable = EntityTable | EntityTableMeta;
+
+export function seedRow<TRow = unknown>(
+  db: AnyDb,
+  table: SeedTable,
+  values: Record<string, unknown>,
+): Promise<TRow | undefined> {
+  return insertOne<TRow>(db, table as EntityTableMeta, values);
+}
+
+export function seedRows<TRow = unknown>(
+  db: AnyDb,
+  table: SeedTable,
+  rows: ReadonlyArray<Record<string, unknown>>,
+): Promise<readonly TRow[]> {
+  return insertMany<TRow>(db, table as EntityTableMeta, rows);
+}
+
+export function updateRows<TRow = unknown>(
+  db: AnyDb,
+  table: SeedTable,
+  set: Record<string, unknown>,
+  where: WhereObject,
+): Promise<readonly TRow[]> {
+  return updateMany<TRow>(db, table as EntityTableMeta, set, where);
+}
+
+export function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<void> {
+  return deleteMany(db, table as EntityTableMeta, where);
+}

package/src/time/__tests__/boot-tz-warning.test.ts

@@ -9,6 +9,13 @@ describe("warnIfNonUtcServerTimeZone", () => {
     expect(messages).toHaveLength(0);
   });
 
+  test.each(["GMT", "Etc/UTC"])("warnt nicht bei UTC-äquivalenter Zone %s", (zone) => {
+    const messages: string[] = [];
+    const warned = warnIfNonUtcServerTimeZone(zone, (m) => messages.push(m));
+    expect(warned).toBe(false);
+    expect(messages).toHaveLength(0);
+  });
+
   test("warnt bei nicht-UTC Zone, nennt Zone + UTC-Hinweis", () => {
     const messages: string[] = [];
     const warned = warnIfNonUtcServerTimeZone("Europe/Berlin", (m) => messages.push(m));

package/src/time/__tests__/geo-tz.test.ts

@@ -55,11 +55,17 @@ describe("ctx.tz — GeoTzProvider seam", () => {
   test("fromAddress wirft wenn der Provider kein fromAddress hat (offline lat/lng)", async () => {
     const provider: GeoTzProvider = { fromCoordinates: () => "UTC" };
     const tz = createTzContext({ geoTz: provider });
-    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/fromAddress/);
+    // Regression (680/2): this message must say the PROVIDER lacks
+    // fromAddress, not the misleading "no provider configured" message.
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(
+      /GeoTzProvider that implements fromAddress/,
+    );
   });
 
-  test("fromAddress wirft ohne Provider", async () => {
+  test("fromAddress wirft ohne Provider — eigene Message, nicht die Provider-ohne-fromAddress-Message", async () => {
     const tz = createTzContext();
-    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/GeoTzProvider/);
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(
+      /requires a GeoTzProvider — inject one/,
+    );
   });
 });

package/src/time/__tests__/iana.test.ts

@@ -25,6 +25,15 @@ describe("isValidIanaTimeZone", () => {
     expect(isValidIanaTimeZone(value)).toBe(false);
   });
 
+  // Intl.supportedValuesOf("timeZone") listet nur kanonische Namen — gültige
+  // IANA-Aliase fehlen darin, obwohl Intl.DateTimeFormat/Temporal/ctx.tz.parse
+  // sie klaglos akzeptieren. Ein valider Alias darf hier nicht als "invalid"
+  // rejected werden (stiller Breaking-Change für Consumer, die Alias-Zonen
+  // speichern).
+  test.each(["US/Pacific", "GMT", "Etc/UTC"])("akzeptiert gültigen IANA-Alias %s", (zone) => {
+    expect(isValidIanaTimeZone(zone)).toBe(true);
+  });
+
   test("liefert über mehrere Aufrufe konsistent (lazy Set gecacht)", () => {
     expect(isValidIanaTimeZone("Europe/Berlin")).toBe(true);
     expect(isValidIanaTimeZone("Europe/Berlin")).toBe(true);

package/src/time/boot-tz-warning.ts

@@ -17,7 +17,11 @@ export function warnIfNonUtcServerTimeZone(
   // biome-ignore lint/suspicious/noConsole: boot-time warning, no logger wired this early
   warn: (message: string) => void = console.warn,
 ): boolean {
-  if (resolvedTimeZone === "UTC") return false;
+  // GMT and Etc/UTC are UTC-equivalent (no offset, no DST) — TZ=GMT is a
+  // legitimate way to pin a process to UTC and must not trip this warning.
+  if (resolvedTimeZone === "UTC" || resolvedTimeZone === "GMT" || resolvedTimeZone === "Etc/UTC") {
+    return false;
+  }
   warn(
     `[kumiko] Server time zone is "${resolvedTimeZone}" — the framework assumes UTC. ` +
       "Set TZ=UTC for the server process to avoid time-zone-dependent bugs.",

package/src/time/iana.ts

@@ -1,17 +1,19 @@
-// IANA-Zonenname-Validierung gegen die Runtime-eigene Zonenliste
-// (Intl.supportedValuesOf). Das Set wird lazy einmal gebaut — der Aufbau ist
-// der teure Teil (~400 kanonische Zonen), das Lookup danach O(1).
-
-let supportedZones: ReadonlySet<string> | undefined;
-
-function ianaZoneSet(): ReadonlySet<string> {
-  if (supportedZones === undefined) {
-    supportedZones = new Set(Intl.supportedValuesOf("timeZone"));
-  }
-  return supportedZones;
-}
-
-/** True wenn `value` ein gültiger kanonischer IANA-Zonenname ist (z.B. "Europe/Berlin", "UTC"). */
+// IANA-Zonenname-Validierung. Intl.supportedValuesOf("timeZone") liefert nur
+// KANONISCHE Namen — gültige Aliase wie "US/Pacific", "GMT", "Etc/UTC" fehlen
+// darin, obwohl Intl.DateTimeFormat, Temporal und ctx.tz.parse sie alle
+// klaglos akzeptieren. Intl.DateTimeFormat selbst ist aber case-INSENSITIVE
+// ("europe/berlin" resolved klaglos zu "Europe/Berlin") — ein reines
+// try/catch würde also Tippfehler in der Groß-/Kleinschreibung durchlassen.
+// Der exakte Vergleich mit resolvedOptions().timeZone schließt das: ein
+// gültiger kanonischer Name ODER Alias resolved IMMER zu sich selbst
+// (empirisch verifiziert für US/Pacific, GMT, Etc/UTC), ein falsch-gecasteter
+// String resolved zur kanonischen Form und matcht damit nicht mehr exakt.
 export function isValidIanaTimeZone(value: string): boolean {
-  return ianaZoneSet().has(value);
+  try {
+    return (
+      new Intl.DateTimeFormat(undefined, { timeZone: value }).resolvedOptions().timeZone === value
+    );
+  } catch {
+    return false;
+  }
 }

package/src/time/tz-context.ts

@@ -115,7 +115,12 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
       return geoTz.fromCoordinates(coords);
     },
     fromAddress: async (address) => {
-      if (geoTz?.fromAddress === undefined) {
+      if (geoTz === undefined) {
+        throw new Error(
+          "ctx.tz.fromAddress requires a GeoTzProvider — inject one via the app context (e.g. buildServer({ context: { geoTzProvider } }) or runProdApp({ extraContext: { geoTzProvider } })) or install a provider package.",
+        );
+      }
+      if (geoTz.fromAddress === undefined) {
         throw new Error(
           "ctx.tz.fromAddress requires a GeoTzProvider that implements fromAddress (geocoding). Offline lat/lng providers only support fromCoordinates.",
         );

package/src/utils/__tests__/serialization.test.ts

@@ -21,4 +21,10 @@ describe("parseRoles", () => {
     expect(parseRoles(42)).toEqual([]);
     expect(parseRoles({ roles: ["Admin"] })).toEqual([]);
   });
+
+  test("filters out non-string entries instead of returning a type-lying array (517/1)", () => {
+    expect(parseRoles([42, "Admin", true, null])).toEqual(["Admin"]);
+    expect(parseRoles("[42, true]")).toEqual([]);
+    expect(parseRoles('[42, "Admin"]')).toEqual(["Admin"]);
+  });
 });

package/src/utils/serialization.ts

@@ -1,7 +1,14 @@
 import { parseJsonSafe } from "./safe-json";
 
+function toStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((e): e is string => typeof e === "string") : [];
+}
+
 export function parseRoles(raw: unknown): string[] {
-  if (typeof raw === "string") return parseJsonSafe<string[]>(raw, []);
-  if (Array.isArray(raw)) return raw;
-  return [];
+  // parseJsonSafe<string[]> is a cast, not a runtime check — `'[42, true]'`
+  // would otherwise come back as `[42, true]` typed as string[]. Filter to
+  // actual strings on both the parsed-JSON path and the already-an-array
+  // path, so a non-string entry never survives as a "role".
+  if (typeof raw === "string") return toStringArray(parseJsonSafe<unknown>(raw, []));
+  return toStringArray(raw);
 }