@cosmicdrift/kumiko-framework 0.275.0 → 0.277.0

package/package.json

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

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.277.0",
+    "type": "improvement",
+    "title": "Changesets are the single source for upgrade changelog entries",
+    "detail": "The release step folds structured Changeset metadata into changes.json with the actual published version."
+  },
+  {
+    "version": "0.276.0",
+    "type": "improvement",
+    "title": "entityEdit and actionForm screens accept `slots.titleAction`, rendered on the right of the form title.",
+    "detail": "`ScreenSlots.titleAction` mounts an `extensionSectionComponents` entry in the form title row (same props as `slots.header`: screenId, entityName, entityId, values). `FormProps.titleAction` carries it to the primitives; the web `DefaultForm` renders it right-aligned next to title and subtitle in `<testId>-title-action`, in both the card and the chromeless layout. Native primitives may ignore it.",
+    "migration": "No action required — purely additive."
+  },
   {
     "version": "0.275.0",
     "type": "breaking",
@@ -6,6 +19,13 @@
     "detail": "Job handlers no longer receive the unfiltered boot `DbConnection` as `ctx.db`. `JobContext.db` is now a `TenantDb` in \"tenant\" mode, bound to the job's resolved tenant (`_tenantId`, `payload.tenantId`, or `SYSTEM_TENANT_ID` for tenant-less cron jobs). Reads see that tenant plus `SYSTEM_TENANT_ID` reference rows, and writes are scoped to it. `JobDefinition` gains `escapeHatch?: { reason }`: it grants `ctx.db.unsafeRaw(reason)` for that job and reports an `\"unsafe-raw\"` escape-hatch audit event through `_escapeHatchAuditSink` (deduplicated like handler grants). Without it, `ctx.db.unsafeRaw` throws `AccessDeniedError`. `r.systemScope()` features keep `ctx.systemDb` unchanged. `r.job` throws at registration for an `escapeHatch` with an empty reason. Framework `soft-delete` cleanup jobs run on the tenant-filtered `TenantDb` without a grant. Bundled cross-tenant jobs now declare `escapeHatch`: auth-mfa reencrypt, sessions cleanup, form-draft cleanup, secrets rotate, files-tenant-data sweep-orphaned-derivatives, data-retention retention-cleanup, inbound-mail-retention, tenant-lifecycle run-tenant-destruction, and user-data-rights run-export-jobs/run-forget-cleanup. The systemScope features config, jobs and workflow-runner use `ctx.systemDb.unsafeRaw`. The exported `rotateJob` (secrets) and `sweepOrphanedDerivativesJob` (files-tenant-data) take the raw `DbConnection` as a third argument.",
     "migration": "Jobs that only read and write their own tenant through `ctx.db` method calls or `selectMany/fetchOne/insertOne/updateMany/deleteMany(ctx.db, ...)` need no change. A job that treated `ctx.db` as a `DbConnection` (casts, `asRawClient`, `countWhere`, `upsert*`, `incrementCounter`, `createTenantDb(ctx.db, ...)`, `runProjectionsForEvent(..., ctx.db)`, or `\"raw\" in db ? db.raw : db`) must declare the grant and fetch the runner explicitly. Use `r.job({ name, trigger, escapeHatch: { reason: \"<why>\" }, handler: async (payload, ctx) => work(ctx.db.unsafeRaw(\"<why>\")) })`; keep the `unsafeRaw` call inside the inline `handler` next to `escapeHatch` so `guard-escape-hatch-declared` recognizes the declaration. `r.systemScope()` features use `ctx.systemDb.unsafeRaw(reason)` instead. WARNING: a job that is not migrated but passes a foreign `where.tenantId` through `ctx.db` does not fail; the filter silently narrows it to the job's own tenant (`SYSTEM_TENANT_ID` for tenant-less cron jobs), so cross-tenant sweeps silently read nothing. Audit every cross-tenant job. Hand-built `JobContext` objects in tests need `db: createTenantDb(conn, tenantId)` (plus `systemDb` for systemScope jobs). Direct callers of `rotateJob`/`sweepOrphanedDerivativesJob` pass the raw connection as the third argument."
   },
+  {
+    "version": "0.274.0",
+    "type": "improvement",
+    "title": "A money field can declare `currency: { kind: \"tenant\" }` to source its currency from the tenant-settings config key.",
+    "detail": "`createMoneyField` accepts an optional `currency: MoneyCurrencySource` — a discriminated union (exported from `@cosmicdrift/kumiko-framework/engine/types`), currently only `{ kind: \"tenant\" }`, left room for #2839's later `literal`/`field` variants. The declaration reaches the client app schema (`buildAppSchema`'s field projection). In an entityEdit form (create and update), a rendered money field that declares `{ kind: \"tenant\" }` reads the tenant's currency via the existing `config:query:values` query (key `tenant-settings:config:currency`) instead of `entity.defaultCurrency ?? \"EUR\"`: an empty value's initial amount and currency come from the tenant's setting, and the form waits for that query rather than momentarily showing/submitting `EUR` while it is in flight. A field's already-stored value always keeps its own currency, unaffected by the declaration. A field without the declaration is unchanged.",
+    "migration": "No action required — purely additive; a money field without `currency` declared keeps today's `entity.defaultCurrency ?? \"EUR\"` behavior."
+  },
   {
     "version": "0.274.0",
     "type": "breaking",

package/src/engine/__tests__/build-app-schema.test.ts

@@ -622,6 +622,28 @@ describe("buildAppSchema", () => {
     expect("defaultCurrency" in app.features[0]!.entities["thing"]!).toBe(false);
   });
 
+  test("money field's `currency: { kind: 'tenant' }` declaration survives the projection (fw#2933)", () => {
+    const entity = {
+      defaultCurrency: "USD",
+      fields: {
+        price: { type: "money", currency: { kind: "tenant" } },
+        cost: { type: "money" },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const projected = app.features[0]!.entities["thing"] as unknown as {
+      fields: Record<string, Record<string, unknown>>;
+    };
+
+    expect(projected.fields["price"]?.["currency"]).toEqual({ kind: "tenant" });
+    expect(projected.fields["cost"]?.["currency"]).toBeUndefined();
+    expect(JSON.parse(JSON.stringify(projected))).toEqual(projected);
+  });
+
   test("text format, timestamp locatedBy, file accept/maxSize, image variants and decimal scale survive the projection", () => {
     // Regression: all of these are read by the edit view-model (password
     // masking, wall-clock input, upload constraints, preview variant, derived

package/src/engine/__tests__/changeset-changes.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { parseChangesetChanges } from "../changeset-changes";
+
+describe("parseChangesetChanges", () => {
+  test("parses a structured change and derives detail from the body", () => {
+    const changes = parseChangesetChanges(
+      `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\nAdds the new upgrade flow.\n\nMore detail.\n\n<!-- kumiko-changes\nfeature: framework\ntype: improvement\ntitle: Adds the new upgrade flow\n-->`,
+      ".changeset/upgrade-flow.md",
+    );
+
+    expect(changes).toEqual([
+      {
+        feature: "framework",
+        type: "improvement",
+        title: "Adds the new upgrade flow",
+        detail: "More detail.",
+        source: ".changeset/upgrade-flow.md",
+      },
+    ]);
+  });
+
+  test("parses multiple blocks with multiline migration", () => {
+    const changes = parseChangesetChanges(
+      `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: breaking\ntitle: Removes the old flow\nmigration: |\n  Replace the old call.\n  Then run the migration.\n-->\n\n<!-- kumiko-changes\nfeature: sessions\ntype: fix\ntitle: Fixes session cleanup\n-->`,
+      ".changeset/two-features.md",
+    );
+
+    expect(changes.map(({ feature, type, migration }) => ({ feature, type, migration }))).toEqual([
+      {
+        feature: "framework",
+        type: "breaking",
+        migration: "Replace the old call.\nThen run the migration.",
+      },
+      { feature: "sessions", type: "fix", migration: undefined },
+    ]);
+  });
+
+  test("rejects a breaking change without migration", () => {
+    expect(() =>
+      parseChangesetChanges(
+        `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: breaking\ntitle: Removes the old flow\n-->`,
+        ".changeset/breaking.md",
+      ),
+    ).toThrow('breaking change "Removes the old flow" missing migration field');
+  });
+
+  test("rejects an unknown type", () => {
+    expect(() =>
+      parseChangesetChanges(
+        `---\n"@cosmicdrift/kumiko-framework": patch\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: feature\ntitle: Invalid\n-->`,
+        ".changeset/invalid.md",
+      ),
+    ).toThrow("type must be breaking, improvement, or fix");
+  });
+});

package/src/engine/build-app-schema.ts

@@ -497,6 +497,11 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
     out["variants"] = def["variants"];
   // decimal, incl. embedded sub-fields: rounding of derived embedded-list cells.
   if (typeof def["scale"] === "number") out["scale"] = def["scale"];
+  // money: declared currency source (MoneyCurrencySource, fw#2933) — without
+  // it the renderer can't tell a "currency: { kind: 'tenant' }" field apart
+  // from an undeclared one and always falls back to entity.defaultCurrency.
+  if (isPlainObject(def["currency"]) && isJsonSafeValue(def["currency"]))
+    out["currency"] = def["currency"];
   // embedded lists: row-count bounds, computed cells, totals row, and the
   // sibling-money-field totals check (fw#2497).
   if (typeof def["minItems"] === "number") out["minItems"] = def["minItems"];

package/src/engine/changeset-changes.ts

@@ -0,0 +1,104 @@
+import { type ChangelogType, validateChangelog } from "./feature-changelog";
+
+export type PendingChange = {
+  readonly feature: string;
+  readonly type: ChangelogType;
+  readonly title: string;
+  readonly detail?: string;
+  readonly migration?: string;
+  readonly codemod?: string;
+  readonly source: string;
+};
+
+const BLOCK_RE = /<!--\s*kumiko-changes\s*\n([\s\S]*?)\n\s*-->/g;
+const TYPE_VALUES = new Set<ChangelogType>(["breaking", "improvement", "fix"]);
+const KEY_RE = /^(feature|type|title|detail|migration|codemod):(?:\s(.*))?$/;
+
+function requiredField(fields: ReadonlyMap<string, string>, field: string, source: string): string {
+  const value = fields.get(field)?.trim();
+  if (!value) throw new Error(`${source}: kumiko-changes ${field} is required`);
+  return value;
+}
+
+function parseBlock(raw: string, source: string): ReadonlyMap<string, string> {
+  const fields = new Map<string, string>();
+  const lines = raw.split("\n");
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "") continue;
+    const match = KEY_RE.exec(line.trim());
+    if (!match) throw new Error(`${source}: invalid kumiko-changes line "${line.trim()}"`);
+
+    const key = match[1];
+    if (!key) throw new Error(`${source}: invalid kumiko-changes field`);
+    if (fields.has(key)) throw new Error(`${source}: duplicate kumiko-changes field "${key}"`);
+    const value = match[2];
+    if (value === "|") {
+      const continuation: string[] = [];
+      while (index + 1 < lines.length && (lines[index + 1]?.startsWith("  ") ?? false)) {
+        index++;
+        const continuationLine = lines[index];
+        if (continuationLine) continuation.push(continuationLine.slice(2));
+      }
+      fields.set(key, continuation.join("\n").trim());
+      continue;
+    }
+    fields.set(key, value ?? "");
+  }
+
+  return fields;
+}
+
+function proseWithoutMetadata(markdown: string): string[] {
+  const withoutFrontmatter = markdown.replace(/^\s*---\n[\s\S]*?\n---\s*/, "");
+  return withoutFrontmatter
+    .replace(BLOCK_RE, "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+}
+
+/** Parse structured upgrade metadata embedded in a Changeset body. */
+export function parseChangesetChanges(markdown: string, source: string): readonly PendingChange[] {
+  const changes: PendingChange[] = [];
+  const prose = proseWithoutMetadata(markdown);
+  BLOCK_RE.lastIndex = 0;
+  let match = BLOCK_RE.exec(markdown);
+  while (match !== null) {
+    const block = match[1];
+    if (!block) throw new Error(`${source}: empty kumiko-changes block`);
+    const fields = parseBlock(block, source);
+    const feature = requiredField(fields, "feature", source);
+    const rawType = requiredField(fields, "type", source);
+    if (!TYPE_VALUES.has(rawType as ChangelogType)) {
+      throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
+    }
+    const title = fields.get("title")?.trim() || prose[0];
+    if (!title) throw new Error(`${source}: kumiko-changes title is required`);
+
+    const detail =
+      fields.get("detail")?.trim() ||
+      prose
+        .slice(prose.length > 0 ? 1 : 0)
+        .join("\n")
+        .trim();
+    const migration = fields.get("migration")?.trim();
+    const codemod = fields.get("codemod")?.trim();
+    const change: PendingChange = {
+      feature,
+      type: rawType as ChangelogType,
+      title,
+      ...(detail ? { detail } : {}),
+      ...(migration ? { migration } : {}),
+      ...(codemod ? { codemod } : {}),
+      source,
+    };
+    const validation = validateChangelog({ version: "0.0.0", ...change });
+    if (validation.length > 0) throw new Error(`${source}: ${validation.join("; ")}`);
+    changes.push(change);
+    match = BLOCK_RE.exec(markdown);
+  }
+
+  return changes;
+}

package/src/engine/constants.ts

@@ -97,6 +97,15 @@ export type { ConcurrencyMode };
 const _concurrencyModeExhaustive: Record<ConcurrencyMode, unknown> = ConcurrencyModes;
 void _concurrencyModeExhaustive;
 
+// --- Money Currency Sources ---
+// Canonical definition lives in kumiko-types/fields (client-safe, next to
+// MoneyCurrencySource) so renderer code can import it without pulling in
+// runtime-only engine code (fw#2937). Re-exported here for server callers
+// already importing framework/engine (bundled-features/src/tenant-settings/
+// constants.ts TenantSettingsConfig.currency reuses this same constant, so
+// the two stay in sync by construction).
+export { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-types/fields";
+
 // --- SSE Channels ---
 
 export function tenantChannel(tenantId: TenantId): string {

package/src/engine/index.ts

@@ -24,6 +24,7 @@ export {
   SETTINGS_HUB_WORKSPACE,
 } from "./build-config-feature-schema";
 export { buildTarget } from "./build-target";
+export { type PendingChange, parseChangesetChanges } from "./changeset-changes";
 export {
   access,
   createSeed,
@@ -44,6 +45,7 @@ export {
   OnDeleteStrategies,
   SystemHookNames,
   SystemHookPriorities,
+  TENANT_CURRENCY_CONFIG_KEY,
   tenantChannel,
 } from "./constants";
 export type { App, AppConfig } from "./create-app";

package/src/engine/types/index.ts

@@ -119,6 +119,7 @@ export type {
   LocatedTimestampFieldDef,
   LongTextFieldDef,
   LongTextFindability,
+  MoneyCurrencySource,
   MoneyFieldDef,
   MultiSelectFieldDef,
   NumberFieldDef,

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -13,6 +13,9 @@ const ALLOWED_FILES = new Set([
   "packages/bundled-features/src/tenant/seeding.ts",
   "packages/bundled-features/src/tier-engine/feature.ts",
   "packages/framework/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts",
+  // Fixtures of the AST guard that enforces this same restriction.
+  "packages/guards/src/__tests__/guard-fires.test.ts",
+  "packages/guards/src/__tests__/guard-restricted-symbols.test.ts",
 ]);
 
 const REPO_ROOT = `${import.meta.dir}/../../../../..`;