@cosmicdrift/kumiko-framework 0.212.0 → 0.213.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.212.0",
+  "version": "0.213.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>",
@@ -194,7 +194,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.212.0",
+    "@cosmicdrift/kumiko-types": "0.213.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -210,7 +210,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.212.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.213.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -69,6 +69,51 @@ describe("runSchemaCli — no-DB paths", () => {
     expect(cap.err.join("\n")).not.toContain("kumiko-schema");
   });
 
+  test("generate --help prints usage, exits 0, writes no migration (framework#2191)", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "--help"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Usage: schema generate <name>");
+    expect(cap.err).toHaveLength(0);
+    expect(existsSync(join(appCwd, "kumiko/migrations"))).toBe(false);
+  });
+
+  test("generate -h prints usage, exits 0, writes no migration", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "-h"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Usage: schema generate <name>");
+    expect(existsSync(join(appCwd, "kumiko/migrations"))).toBe(false);
+  });
+
+  test("generate name starting with -- is rejected, exits 1, writes no migration", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "--evil"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain('Invalid migration name "--evil"');
+    expect(existsSync(join(appCwd, "kumiko/migrations"))).toBe(false);
+  });
+
+  test("generate name with path separators is rejected (path traversal)", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "../../evil"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("Invalid migration name");
+    expect(existsSync(join(appCwd, "kumiko/migrations"))).toBe(false);
+  });
+
+  test("generate with a hyphenated name still works", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "add-user-table"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(existsSync(join(appCwd, "kumiko/migrations/0001_add-user-table.sql"))).toBe(true);
+  });
+
   test("generate with missing schema.ts exits 1", async () => {
     const cap = captureOut();
     const code = await runSchemaCli(["generate", "init"], appCwd, cap.out);

package/src/api/__tests__/request-locale.integration.test.ts

@@ -0,0 +1,96 @@
+// Regression guard for the request-locale wiring: X-Locale header (or, when
+// absent, Accept-Language) must reach ctx.locale on real HTTP calls — the
+// AsyncLocalStorage plumbing in request-id-middleware.ts / dispatch-shared.ts
+// can't be exercised via createTestDispatcher, which skips the HTTP layer
+// entirely.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { LOCALE_HEADER_NAME } from "../api-constants";
+
+const localeProbe = defineFeature("locale-probe", (r) => {
+  r.writeHandler(
+    "read-locale",
+    z.object({}),
+    async (_event, ctx) => ({ isSuccess: true, data: { locale: ctx.locale } }),
+    { access: { openToAll: true } },
+  );
+});
+
+async function readLocale(stack: TestStack, headers: Record<string, string>): Promise<string> {
+  const res = await stack.http.writeWithHeaders(
+    "locale-probe:write:read-locale",
+    {},
+    createTestUser({ id: 1 }),
+    headers,
+  );
+  const body = (await res.json()) as { data: { locale: string } };
+  return body.data.locale;
+}
+
+describe("ctx.locale resolution over real HTTP", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [localeProbe] });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("X-Locale header wins", async () => {
+    const locale = await readLocale(stack, { [LOCALE_HEADER_NAME]: "de-AT" });
+    expect(locale).toBe("de-AT");
+  });
+
+  test("falls back to Accept-Language when X-Locale is absent", async () => {
+    const locale = await readLocale(stack, { "accept-language": "fr-FR,fr;q=0.9,en;q=0.8" });
+    expect(locale).toBe("fr-FR");
+  });
+
+  test("Accept-Language with only invalid tags falls back to the boot default", async () => {
+    const locale = await readLocale(stack, { "accept-language": "*, ;q=0.1" });
+    expect(locale).toBe("en");
+  });
+
+  test("a malformed/manipulated X-Locale header is rejected, not passed through", async () => {
+    const locale = await readLocale(stack, {
+      [LOCALE_HEADER_NAME]: "<script>alert(1)</script>",
+    });
+    expect(locale).toBe("en");
+  });
+
+  test("an invalid X-Locale header falls through to a valid Accept-Language instead of the default", async () => {
+    const locale = await readLocale(stack, {
+      [LOCALE_HEADER_NAME]: "not-a-real-locale-tag-way-too-long-to-be-valid",
+      "accept-language": "es-ES",
+    });
+    expect(locale).toBe("es-ES");
+  });
+});
+
+describe("ctx.locale falls back to the app's boot-configured defaultLocale", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [localeProbe],
+      extraContext: { defaultLocale: "ja" },
+    });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("no header signal at all uses the app's defaultLocale, not the hardcoded default", async () => {
+    const locale = await readLocale(stack, {});
+    expect(locale).toBe("ja");
+  });
+});

package/src/api/api-constants.ts

@@ -118,4 +118,11 @@ export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([
 export const TENANT_HEADER_NAME = "X-Tenant";
 export const TENANT_COOKIE_NAME = "kumiko_tenant";
 
+// Client-declared active UI locale (BCP-47). Read once per request in
+// request-id-middleware.ts, before auth, so it reaches public routes
+// (e.g. signup-request) too. Falls back to Accept-Language, then the app's
+// boot-configured defaultLocale, when absent or malformed — see
+// request-locale.ts and dispatch-shared.ts's ctx.locale resolution.
+export const LOCALE_HEADER_NAME = "X-Locale";
+
 export type Route = (typeof Routes)[keyof typeof Routes];

package/src/api/request-context.ts

@@ -33,6 +33,11 @@ export type RequestContextData = {
   // Raw User-Agent header — audit trails (download tokens, GDPR export
   // access) want it alongside `ip`. Undefined for non-HTTP entry points.
   readonly userAgent?: string;
+  // Client-declared active UI locale (BCP-47), resolved once from
+  // X-Locale / Accept-Language by requestIdMiddleware — see
+  // request-locale.ts. Undefined when neither header carried a valid tag;
+  // callers fall back further (dispatch-shared.ts's ctx.locale chain).
+  readonly locale?: string;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();

package/src/api/request-id-middleware.ts

@@ -1,4 +1,6 @@
 import type { Context, Next } from "hono";
+import { resolveHeaderLocale } from "../i18n/request-locale";
+import { LOCALE_HEADER_NAME } from "./api-constants";
 import { type RequestContextData, requestContext } from "./request-context";
 
 const REQUEST_ID_HEADER = "X-Request-ID";
@@ -45,6 +47,13 @@ export function buildRequestContextData(c: Context): RequestContextData {
   const xff = c.req.header("x-forwarded-for");
   const ip = xff?.split(",")[0]?.trim();
   const userAgent = c.req.header("user-agent");
+  // Runs before auth-middleware, so this reaches public routes too (e.g.
+  // signup-request) — that's the whole point: the active UI locale must
+  // survive to anonymous callers, not just authenticated ones.
+  const locale = resolveHeaderLocale({
+    headerLocale: c.req.header(LOCALE_HEADER_NAME),
+    acceptLanguage: c.req.header("accept-language"),
+  });
 
   return {
     requestId,
@@ -52,6 +61,7 @@ export function buildRequestContextData(c: Context): RequestContextData {
     ...(signal ? { signal } : {}),
     ...(ip && ip.length > 0 ? { ip } : {}),
     ...(userAgent !== undefined ? { userAgent } : {}),
+    ...(locale !== undefined ? { locale } : {}),
   };
 }
 

package/src/bun-db/index.ts

@@ -28,6 +28,7 @@ export {
   selectMany,
   transaction,
   type UpsertOnConflictOptions,
+  unsafeReadRetrying,
   updateMany,
   upsertByPk,
   upsertOnConflict,

package/src/bun-db/query.ts

@@ -685,7 +685,10 @@ function isClosedConnectionError(err: unknown): boolean {
   );
 }
 
-async function unsafeRead<TRow>(
+// Exported so raw-SQL query modules outside bun-db (e.g. bundled-features'
+// db/queries/*.ts) can opt into the same #1163 retry instead of calling
+// asRawClient(db).unsafe(...) directly and losing it.
+export async function unsafeReadRetrying<TRow>(
   db: AnyDb,
   sqlText: string,
   params: readonly unknown[],
@@ -736,7 +739,7 @@ export async function selectMany<TRow = any>(
     }
     sqlText += ` LIMIT ${options.limit}`;
   }
-  const raw = (await unsafeRead(db, sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeReadRetrying(db, sqlText, values)) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -970,7 +973,7 @@ export async function countWhere(
     sqlText += ` WHERE ${w.sqlText}`;
     values = w.values;
   }
-  const rows = (await unsafeRead(db, sqlText, values)) as readonly { count: number }[];
+  const rows = (await unsafeReadRetrying(db, sqlText, values)) as readonly { count: number }[];
   return rows[0]?.count ?? 0;
 }
 

package/src/i18n/index.ts

@@ -1,6 +1,12 @@
 import type { Registry, TranslationKeys } from "../engine/types";
 
 export { hasMailTranslations, mailT, registerMailTranslations } from "./mail-registry";
+export {
+  DEFAULT_LOCALE,
+  isValidLocaleTag,
+  pickAcceptLanguage,
+  resolveHeaderLocale,
+} from "./request-locale";
 
 export type I18nOptions = {
   defaultLocale: string;

package/src/i18n/request-locale.ts

@@ -0,0 +1,63 @@
+// Request-scoped locale resolution — the language counterpart to ctx.tz
+// (time/tz-context.ts). Unlike TzContext there's no closed catalog to
+// validate against here: mail-registry.ts is a dynamic, per-package
+// registry that locale packages (kumiko-locale-de, ...) populate at import
+// time, so "known locale" isn't a fixed enum. Validation checks
+// well-formedness instead — a header is user input either way.
+
+export const DEFAULT_LOCALE = "en";
+
+// Loose BCP-47: 2-3 letter primary subtag, then 1-8 more alphanumeric
+// subtags separated by "-" (region/script/variant/extension). Rejects
+// control characters, oversized values, and header-injection shapes
+// without implementing a full RFC 5646 parser.
+const LOCALE_TAG_RE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/;
+const MAX_LOCALE_TAG_LENGTH = 35;
+
+export function isValidLocaleTag(value: string): boolean {
+  return value.length <= MAX_LOCALE_TAG_LENGTH && LOCALE_TAG_RE.test(value);
+}
+
+type AcceptLanguageCandidate = { readonly tag: string; readonly q: number; readonly index: number };
+
+/**
+ * Picks the best well-formed tag from an Accept-Language header (RFC 9110
+ * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
+ * breaks ties), and returns the first tag that passes isValidLocaleTag.
+ * Tags with q=0 (explicitly excluded) are dropped entirely.
+ */
+export function pickAcceptLanguage(header: string | undefined): string | undefined {
+  if (header === undefined || header.length === 0) return undefined;
+
+  const candidates: AcceptLanguageCandidate[] = header
+    .split(",")
+    .map((part, index): AcceptLanguageCandidate | undefined => {
+      const [tagRaw, ...params] = part.trim().split(";");
+      const tag = tagRaw?.trim();
+      if (tag === undefined || tag.length === 0 || !isValidLocaleTag(tag)) return undefined;
+      const qParam = params.find((p) => p.trim().startsWith("q="));
+      const parsedQ = qParam !== undefined ? Number(qParam.trim().slice(2)) : 1;
+      const q = Number.isFinite(parsedQ) ? parsedQ : 0;
+      return { tag, q, index };
+    })
+    .filter((c): c is AcceptLanguageCandidate => c !== undefined && c.q > 0)
+    .sort((a, b) => b.q - a.q || a.index - b.index);
+
+  return candidates[0]?.tag;
+}
+
+/**
+ * Request-layer resolution: an explicit, validated X-Locale header wins;
+ * otherwise the best Accept-Language tag; otherwise undefined — no signal
+ * from this request, callers fall back further (the app's boot-configured
+ * defaultLocale, then DEFAULT_LOCALE — see dispatch-shared.ts).
+ */
+export function resolveHeaderLocale(options: {
+  readonly headerLocale?: string;
+  readonly acceptLanguage?: string;
+}): string | undefined {
+  if (options.headerLocale !== undefined && isValidLocaleTag(options.headerLocale)) {
+    return options.headerLocale;
+  }
+  return pickAcceptLanguage(options.acceptLanguage);
+}

package/src/pipeline/__tests__/distributed-lock.integration.test.ts

@@ -64,4 +64,35 @@ describe("distributed lock", () => {
     const token = await lock.acquire("test-lock-5");
     expect(token).not.toBeNull();
   });
+
+  test("renew extends the TTL for the owning token", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token = await lock.acquire("test-lock-6", { ttlSeconds: 1 });
+    if (!token) throw new Error("expected token");
+
+    const renewed = await lock.renew("test-lock-6", token, 5);
+    expect(renewed).toBe(true);
+
+    // Past the original 1s TTL, but renew pushed it out to 5s — still held.
+    await new Promise((r) => setTimeout(r, 1200));
+    expect(await lock.acquire("test-lock-6")).toBeNull();
+  });
+
+  test("renew with wrong token fails and does not extend the TTL", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    await lock.acquire("test-lock-7", { ttlSeconds: 1 });
+
+    const renewed = await lock.renew("test-lock-7", "wrong-token", 5);
+    expect(renewed).toBe(false);
+
+    // The original 1s TTL still applies — the wrong-token renew didn't touch it.
+    await new Promise((r) => setTimeout(r, 1100));
+    expect(await lock.acquire("test-lock-7")).not.toBeNull();
+  });
+
+  test("renew on an expired/absent key fails", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const renewed = await lock.renew("test-lock-8-never-acquired", "some-token", 5);
+    expect(renewed).toBe(false);
+  });
 });

package/src/pipeline/dispatch-shared.ts

@@ -51,6 +51,7 @@ import {
 } from "../event-store/snapshot";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster";
 import { createFileContext } from "../files/file-handle";
+import { DEFAULT_LOCALE } from "../i18n/request-locale";
 import {
   createMetricsHandle,
   createNoopMetricsHandle,
@@ -620,6 +621,12 @@ export async function buildHandlerContext(
     ...(safeUserTz !== undefined && { user: safeUserTz }),
   });
 
+  // ctx.locale — request-layer signal (X-Locale header → Accept-Language,
+  // resolved once at the HTTP boundary by request-id-middleware.ts) wins;
+  // falls back to the app's boot-configured defaultLocale, then
+  // DEFAULT_LOCALE. Mirrors ctx.tz's Request → Boot-Default chain above.
+  const locale = reqCtx?.locale ?? context.defaultLocale ?? DEFAULT_LOCALE;
+
   return {
     ...context,
     registry,
@@ -647,6 +654,7 @@ export async function buildHandlerContext(
     metrics,
     metricsFor,
     tz,
+    locale,
     // Cancellation signal flows from the HTTP middleware via
     // requestContext. Conditional spread so non-HTTP entry-points
     // (jobs, dispatcher MSP-applies) don't get a phantom signal that

package/src/pipeline/distributed-lock.ts

@@ -5,6 +5,11 @@ import { RedisKeys } from "./redis-keys";
 export type DistributedLock = {
   acquire(key: string, options?: { ttlSeconds?: number }): Promise<string | null>;
   release(key: string, token: string): Promise<boolean>;
+  /** Extends the TTL of a lock this caller still holds (token matches).
+   *  Returns false when the token doesn't match — expired and re-claimed
+   *  by someone else, or never held — the caller must treat that as
+   *  "no longer the owner" and stop renewing, not retry. */
+  renew(key: string, token: string, ttlSeconds: number): Promise<boolean>;
 };
 
 export function createDistributedLock(
@@ -20,6 +25,16 @@ export function createDistributedLock(
     end
   `;
 
+  // Lua script for atomic check-and-extend — same ownership check as release,
+  // but resets the TTL instead of deleting the key.
+  const renewScript = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("expire", KEYS[1], ARGV[2])
+    else
+      return 0
+    end
+  `;
+
   return {
     async acquire(key, options = {}) {
       const ttl = options.ttlSeconds ?? 30;
@@ -33,5 +48,16 @@ export function createDistributedLock(
       const result = (await redis.eval(releaseScript, 1, `${prefix}${key}`, token)) as number; // @cast-boundary db-operator
       return result === 1;
     },
+
+    async renew(key, token, ttlSeconds) {
+      const result = (await redis.eval(
+        renewScript,
+        1,
+        `${prefix}${key}`,
+        token,
+        String(ttlSeconds),
+      )) as number; // @cast-boundary db-operator
+      return result === 1;
+    },
   };
 }

package/src/schema-cli.ts

@@ -143,10 +143,21 @@ export async function runSchemaCli(
   switch (sub) {
     case "generate": {
       const name = argv[1];
+      if (name === "--help" || name === "-h") {
+        out.log("  Usage: schema generate <name>");
+        return 0;
+      }
       if (!name) {
         out.err("  Usage: schema generate <name>");
         return 1;
       }
+      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) — this
+      // allowlist blocks flag-like names and path traversal (`../../x`).
+      if (name.startsWith("-") || !/^[A-Za-z0-9_-]+$/.test(name)) {
+        out.err(`  Invalid migration name "${name}" — use letters, digits, "-", "_" only.`);
+        out.err("  Usage: schema generate <name>");
+        return 1;
+      }
       if (!existsSync(schemaFile)) {
         out.err(`  ${schemaFile} fehlt.`);
         out.err("  App-Convention: kumiko/schema.ts mit");

package/src/testing/handler-context.ts

@@ -1,10 +1,10 @@
 // @runtime runtime
 //
-// bridgeStub liefert eine HandlerContext-Shape mit throw-on-use Bridge-Methods
-// (ctx.query/write/loadAggregate/...). Wird von Test-Code UND Production-
-// Services genutzt (delivery-service nutzt es um cross-feature notify-Calls
-// ohne echten Dispatcher zu fahren). Daher runtime-Klassifizierung trotz
-// Wohnsitz unter `testing/` — keine vitest-Imports, keine Test-Side-Effects.
+// bridgeStub hands back a HandlerContext shape with throw-on-use bridge
+// methods (ctx.query/write/loadAggregate/...). Used by both test code AND
+// production services (delivery-service uses it to run cross-feature notify
+// calls without a real dispatcher). Hence the runtime classification despite
+// living under `testing/` — no vitest imports, no test side-effects.
 import type {
   AppendEventArgs,
   FetchForWritingArgs,
@@ -12,6 +12,7 @@ import type {
   SessionUser,
   WriteResult,
 } from "../engine/types";
+import { DEFAULT_LOCALE } from "../i18n/request-locale";
 import { createNoopMetricsHandle, getFallbackTracer } from "../observability";
 import { createTzContext } from "../time";
 
@@ -61,13 +62,14 @@ export function bridgeStub(opts?: {
   | "metricsFor"
   | "tracer"
   | "tz"
+  | "locale"
   | "user"
 > {
-  // ctx.user ist Convenience-Alias zu event.user (siehe HandlerContext-
-  // Doku). Caller-Code erwartet das Feld; bridgeStub liefert es als
-  // Stub mit den Anonymous-Default-Werten wenn kein User explizit
-  // übergeben wird. Test-Code mit Identity-Bezug übergibt seinen
-  // SessionUser hier und bekommt ihn am ctx zurück.
+  // ctx.user is a convenience alias for event.user (see HandlerContext
+  // docs). Caller code expects the field; bridgeStub hands back a stub with
+  // anonymous default values when no user is passed explicitly. Test code
+  // that cares about identity passes its own SessionUser here and gets it
+  // back on ctx.
   const stubUser: SessionUser = opts?.user ?? {
     id: "00000000-0000-0000-0000-000000000000",
     tenantId: "00000000-0000-0000-0000-000000000000" as SessionUser["tenantId"], // @cast-boundary engine-bridge
@@ -122,8 +124,11 @@ export function bridgeStub(opts?: {
     metrics: createNoopMetricsHandle(),
     metricsFor: () => createNoopMetricsHandle(),
     tracer: noopTracer,
-    // Echter TzContext, kein notAvailable — Test-Code nutzt ctx.tz häufig
-    // ohne dass es ein "Bridge"-Konzept ist. Default UTC.
+    // Real TzContext, not notAvailable — test code uses ctx.tz routinely,
+    // it isn't a "bridge" concept. Defaults to UTC.
     tz: createTzContext(),
+    // Same reasoning as tz above — ctx.locale is always-present, not a
+    // bridge method. Defaults to DEFAULT_LOCALE.
+    locale: DEFAULT_LOCALE,
   };
 }