@cosmicdrift/kumiko-framework 0.276.0 → 0.278.0

package/package.json

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

package/src/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.278.0",
+    "type": "fix",
+    "title": "Fix urlPrefillFields allowlist missing relatedList toolbarActions",
+    "detail": "A screen reached only through a relatedList toolbar action never received its mapped id, so its hidden required field stayed empty and the declared redirect never ran."
+  },
+  {
+    "version": "0.278.0",
+    "type": "improvement",
+    "title": "TenantDb gains a count(table, where?) method for a tenant-scoped COUNT(*) (fw#2854).",
+    "detail": "`TenantDb.count(table, where?)` returns a tenant-scoped row count with the same tenant semantics as `selectMany`: \"tenant\" mode counts the caller's own tenant plus `SYSTEM_TENANT_ID` reference rows, a caller-supplied `where.tenantId` may only narrow that scope, and \"system\" mode counts unfiltered. Lets app/feature code compute stock-caps (`count(*) WHERE tenant_id = …`) without an `unsafeRaw`/`escapeHatch` detour. A hand-built `TenantDb` object literal (test fakes, mocks) must add a `count` method to keep satisfying the `TenantDb` type — `db.global()` is unaffected, `count` is only on the tenant-scoped surface.",
+    "migration": "No action required for existing `TenantDb` consumers — purely additive. Any hand-built object literal typed as `TenantDb` (not built via `createTenantDb`) needs a `count(table, where?)` method added; `bunCountWhere`/`countWhere` from `@cosmicdrift/kumiko-framework/db` implements the same query shape if you need equivalent logic outside a `TenantDb`."
+  },
+  {
+    "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",

package/src/db/__tests__/tenant-db-count.integration.test.ts

@@ -0,0 +1,92 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { createEntity, createTextField } from "../../engine";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import type { TableColumns } from "../dialect";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const entity = createEntity({
+  table: "tenant_db_count_items",
+  fields: {
+    name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+});
+
+const table: TableColumns = buildEntityTable("tenantDbCountItem", entity);
+
+let testDb: TestDb;
+const tenantA = TestUsers.admin; // tenantId: 1
+const tenantB = TestUsers.otherTenant; // tenantId: 2
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, entity, "tenantDbCountItem");
+
+  const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+  const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+
+  await tdbA.insertOne(table, { name: "A1" });
+  await tdbA.insertOne(table, { name: "A2" });
+  await tdbA.insertOne(table, { name: "A3" });
+  await tdbB.insertOne(table, { name: "B1" });
+
+  await seedRow(testDb.db, table, {
+    name: "Reference",
+    tenantId: "00000000-0000-4000-8000-000000000000",
+    version: 1,
+    insertedAt: Temporal.Now.instant(),
+  });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("TenantDb.count() — tenant mode", () => {
+  test("B's count returns only B's own rows plus the reference row, never A's rows", async () => {
+    const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+    const count = await tdbB.count(table);
+    expect(count).toBe(2); // B1 + Reference
+  });
+
+  test("A's count returns only A's own rows plus the reference row", async () => {
+    const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+    const count = await tdbA.count(table);
+    expect(count).toBe(4); // A1, A2, A3 + Reference
+  });
+
+  test("where filter narrows the count", async () => {
+    const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+    const count = await tdbA.count(table, { name: "A1" });
+    expect(count).toBe(1);
+  });
+
+  test("B's where: { tenantId: tenantA } cannot widen scope — falls back to B's own scope", async () => {
+    const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+    const count = await tdbB.count(table, { tenantId: tenantA.tenantId });
+    // The requested tenantId isn't in B's allowed set [B, SYSTEM], so it falls
+    // back to B's full enforced scope rather than widening to A.
+    expect(count).toBe(2); // B1 + Reference
+  });
+
+  test("where: { tenantId: B } excludes the reference row", async () => {
+    const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+    const count = await tdbB.count(table, { tenantId: tenantB.tenantId });
+    expect(count).toBe(1); // B1 only
+  });
+
+  test("count matches selectMany(...).length for the same scope", async () => {
+    const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+    const [count, rows] = await Promise.all([tdbA.count(table), tdbA.selectMany(table)]);
+    expect(count).toBe(rows.length);
+  });
+});
+
+describe("TenantDb.count() — system mode", () => {
+  test("counts all rows across every tenant, unfiltered", async () => {
+    const systemDb = createTenantDb(testDb.db, tenantA.tenantId, "system");
+    const count = await systemDb.count(table);
+    expect(count).toBe(5); // A1, A2, A3, B1, Reference
+  });
+});

package/src/db/tenant-db.ts

@@ -15,6 +15,7 @@ import {
 import {
   asEntityTableMeta,
   asRawClient,
+  countWhere as bunCountWhere,
   deleteMany as bunDeleteMany,
   fetchOne as bunFetchOne,
   insertOne as bunInsertOne,
@@ -453,6 +454,11 @@ export function createTenantDb(
       return withDbSpan("select", table, async () => bunFetchOne<T>(db, table, filter));
     },
 
+    count(table: Table | EntityTableMeta, where?: WhereObject): Promise<number> {
+      const filter = readWhere(table, where);
+      return withDbSpan("select", table, async () => bunCountWhere(db, table, filter));
+    },
+
     insertOne<T = Record<string, unknown>>(
       table: Table,
       values: Record<string, unknown>,

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

@@ -70,7 +70,31 @@ const leasesFeature = defineFeature("leases", (r) => {
     id: "lease-detail",
     type: "projectionDetail",
     query: "leases:query:lease:detail",
-    layout: { sections: [] },
+    layout: {
+      sections: [
+        {
+          kind: "relatedList",
+          title: "Items",
+          query: "leases:query:lease:items",
+          columns: ["name"],
+          toolbarActions: [
+            {
+              kind: "navigate",
+              id: "quick-note",
+              label: "Quick note",
+              screen: "item-toolbar-note",
+              params: { map: { leaseId: "id" } },
+            },
+            {
+              kind: "navigate",
+              id: "silent-add",
+              label: "Silent add",
+              screen: "item-toolbar-silent",
+            },
+          ],
+        },
+      ],
+    },
     metrics: [
       {
         field: "openItems",
@@ -85,6 +109,18 @@ const leasesFeature = defineFeature("leases", (r) => {
     entity: "item",
     layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
   });
+  r.screen({
+    id: "item-toolbar-note",
+    type: "entityEdit",
+    entity: "item",
+    layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
+  });
+  r.screen({
+    id: "item-toolbar-silent",
+    type: "entityEdit",
+    entity: "item",
+    layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
+  });
   r.screen({
     id: "record-payment",
     type: "actionForm",
@@ -150,4 +186,12 @@ describe("buildAppSchema — urlPrefillFields derived from navigate params", ()
   test("non-form screens carry no urlPrefillFields", () => {
     expect(urlPrefillFieldsOf("leases", "lease-list")).toBeUndefined();
   });
+
+  test("a relatedList toolbarAction's params.map target gets the mapped field", () => {
+    expect(urlPrefillFieldsOf("leases", "item-toolbar-note")).toEqual(["leaseId"]);
+  });
+
+  test("a relatedList toolbarAction without params contributes no fields — the allowlist stays an allowlist", () => {
+    expect(urlPrefillFieldsOf("leases", "item-toolbar-silent")).toEqual([]);
+  });
 });

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/boot-validator/url-prefill-fields.ts

@@ -52,6 +52,9 @@ function projectionDetailNavigateActions(
     ...screen.layout.sections.flatMap((section) =>
       section.kind === "relatedList" ? scopeActions(section.rowActions, undefined) : [],
     ),
+    ...screen.layout.sections.flatMap((section) =>
+      section.kind === "relatedList" ? scopeActions(section.toolbarActions, undefined) : [],
+    ),
     ...(screen.metrics ?? []).flatMap((metric) =>
       typeof metric === "string" || metric.navigate === undefined
         ? []

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/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,

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}/../../../../..`;