@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/scripts/codemod/migrate-open-to-all.ts

@@ -0,0 +1,249 @@
+#!/usr/bin/env bun
+// migrate-open-to-all — rewrites deprecated `openToAll: true` to the required
+// `{ reason }` form in test files, and reports every remaining non-test site
+// for a human to pick a reason (fw#2858).
+//
+// Usage:
+//   bun scripts/codemod/migrate-open-to-all.ts [--dry-run] [--test-reason "<text>"] <path...>
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  Node,
+  type ObjectLiteralExpression,
+  Project,
+  type PropertyAssignment,
+  SyntaxKind,
+} from "ts-morph";
+
+const DEFAULT_TEST_REASON = "test handler callable by any signed-in test user";
+
+export interface Rewrite {
+  readonly file: string;
+  readonly line: number;
+  readonly before: string;
+  readonly after: string;
+}
+
+export interface ManualSite {
+  readonly file: string;
+  readonly line: number;
+  readonly handlerName?: string;
+  readonly description?: string;
+}
+
+export interface MigrateOpenToAllResult {
+  readonly output: string;
+  readonly rewrites: Rewrite[];
+  readonly manual: ManualSite[];
+}
+
+export interface MigrateOpenToAllOptions {
+  readonly testReason: string;
+}
+
+function isTestFile(fileName: string): boolean {
+  return /(^|\/)__tests__\//.test(fileName) || /\.test\.(ts|tsx)$/.test(fileName);
+}
+
+function isOpenToAllTrueAssignment(node: Node): node is PropertyAssignment {
+  if (!Node.isPropertyAssignment(node)) return false;
+  if (node.getName() !== "openToAll") return false;
+  return node.getInitializer()?.getKind() === SyntaxKind.TrueKeyword;
+}
+
+function readStringLiteralProperty(obj: ObjectLiteralExpression, name: string): string | undefined {
+  const prop = obj.getProperty(name);
+  if (!prop || !Node.isPropertyAssignment(prop)) return undefined;
+  const init = prop.getInitializer();
+  return init && Node.isStringLiteral(init) ? init.getLiteralValue() : undefined;
+}
+
+function enclosingObjectLiterals(node: Node): ObjectLiteralExpression[] {
+  const result: ObjectLiteralExpression[] = [];
+  let current: Node | undefined = node.getParent();
+  while (current) {
+    if (Node.isObjectLiteralExpression(current)) result.push(current);
+    current = current.getParent();
+  }
+  return result;
+}
+
+// Best-effort human-triage hint (not the rewrite's source of truth): derive a handler name/description from the enclosing object literal, or the enclosing call's first string-literal argument for the positional form.
+function deriveHandlerContext(assignment: PropertyAssignment): {
+  readonly handlerName?: string;
+  readonly description?: string;
+} {
+  let handlerName: string | undefined;
+  let description: string | undefined;
+  for (const obj of enclosingObjectLiterals(assignment)) {
+    if (handlerName === undefined) handlerName = readStringLiteralProperty(obj, "name");
+    if (description === undefined) description = readStringLiteralProperty(obj, "description");
+    if (handlerName !== undefined && description !== undefined) break;
+  }
+  if (handlerName === undefined) {
+    const call = assignment.getFirstAncestorByKind(SyntaxKind.CallExpression);
+    const firstArg = call?.getArguments()[0];
+    if (firstArg && Node.isStringLiteral(firstArg)) handlerName = firstArg.getLiteralValue();
+  }
+  return {
+    ...(handlerName !== undefined && { handlerName }),
+    ...(description !== undefined && { description }),
+  };
+}
+
+export function migrateOpenToAllSource(
+  source: string,
+  fileName: string,
+  opts: MigrateOpenToAllOptions,
+): MigrateOpenToAllResult {
+  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+  const sourceFile = project.createSourceFile(fileName, source);
+  const testFile = isTestFile(fileName);
+
+  const targets = sourceFile
+    .getDescendantsOfKind(SyntaxKind.PropertyAssignment)
+    .filter(isOpenToAllTrueAssignment);
+
+  const rewrites: Rewrite[] = [];
+  const manual: ManualSite[] = [];
+
+  for (const assignment of targets) {
+    if (assignment.wasForgotten()) continue;
+    const line = assignment.getStartLineNumber();
+
+    if (testFile) {
+      const before = assignment.getText();
+      const after = `openToAll: { reason: ${JSON.stringify(opts.testReason)} }`;
+      assignment.replaceWithText(after);
+      rewrites.push({ file: fileName, line, before, after });
+      continue;
+    }
+
+    manual.push({ file: fileName, line, ...deriveHandlerContext(assignment) });
+  }
+
+  return { output: sourceFile.getFullText(), rewrites, manual };
+}
+
+class CliError extends Error {}
+
+interface CliOptions {
+  readonly dryRun: boolean;
+  readonly testReason: string;
+  readonly paths: string[];
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let dryRun = false;
+  let testReason = DEFAULT_TEST_REASON;
+  const paths: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg) break;
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--test-reason") {
+      const value = argv[++i];
+      if (!value) throw new CliError("--test-reason requires a value");
+      testReason = value;
+      continue;
+    }
+    if (arg.startsWith("--")) throw new CliError(`unknown flag: ${arg}`);
+    paths.push(arg);
+  }
+
+  if (paths.length === 0) throw new CliError("at least one path is required");
+  return { dryRun, testReason, paths };
+}
+
+function isMigratableFile(name: string): boolean {
+  return /\.(ts|tsx)$/.test(name);
+}
+
+function walkDir(dir: string, out: string[]): void {
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules") continue;
+    const full = join(dir, name);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      walkDir(full, out);
+      continue;
+    }
+    if (isMigratableFile(name)) out.push(full);
+  }
+}
+
+function collectFiles(paths: string[]): string[] {
+  const files: string[] = [];
+  for (const p of paths) {
+    const abs = resolve(p);
+    const stat = statSync(abs);
+    if (stat.isDirectory()) walkDir(abs, files);
+    else if (isMigratableFile(abs)) files.push(abs);
+  }
+  return files;
+}
+
+async function main(): Promise<void> {
+  let options: CliOptions;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof CliError) {
+      console.error(`[migrate-open-to-all] ${err.message}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  const files = collectFiles(options.paths);
+  const allManual: ManualSite[] = [];
+  let filesChanged = 0;
+  let totalRewrites = 0;
+
+  for (const file of files) {
+    const before = readFileSync(file, "utf8");
+    if (!before.includes("openToAll")) continue;
+    const result = migrateOpenToAllSource(before, file, { testReason: options.testReason });
+    allManual.push(...result.manual);
+
+    if (result.rewrites.length === 0) continue;
+    filesChanged += 1;
+    totalRewrites += result.rewrites.length;
+
+    if (options.dryRun) {
+      console.log(`\n=== ${file} (${result.rewrites.length} rewrite(s)) ===`);
+      for (const r of result.rewrites) {
+        console.log(`${file}:${r.line}`);
+        console.log(`- ${r.before}`);
+        console.log(`+ ${r.after}`);
+      }
+    } else {
+      writeFileSync(file, result.output);
+    }
+  }
+
+  console.log(
+    `\n[migrate-open-to-all] ${options.dryRun ? "would change" : "changed"} ${filesChanged} file(s); ` +
+      `rewrites: ${totalRewrites}`,
+  );
+
+  if (allManual.length > 0) {
+    console.log(`\n[migrate-open-to-all] manual review needed (${allManual.length}):`);
+    for (const m of allManual) {
+      console.log(
+        `${m.file}:${m.line}  ${m.handlerName ?? "<unknown>"}  ${m.description ?? "<no description>"}`,
+      );
+    }
+  }
+
+  process.exit(0);
+}
+
+if (import.meta.main) {
+  await main();
+}

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

@@ -54,7 +54,7 @@ declare const aSecret: Secret<string>;
 defineQueryHandler({
   name: "t:query:leak",
   schema,
-  access: { openToAll: true },
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   handler: async () => ({ apiKey: aSecret }),
 });
 
@@ -65,7 +65,7 @@ function genericResponseHandler<K extends string>(kind: K) {
   return defineQueryHandler({
     name: "t:query:generic",
     schema,
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     handler: async () => ({ kind, ok: true }) as { kind: K; ok: boolean },
   });
 }
@@ -83,7 +83,7 @@ declare const leakingUnion: { ok: true } | { apiKey: Secret<string> };
 defineQueryHandler({
   name: "t:query:union-leak",
   schema,
-  access: { openToAll: true },
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   handler: async () => leakingUnion,
 });
 
@@ -91,7 +91,7 @@ declare const cleanUnion: { ok: true } | { id: string };
 defineQueryHandler({
   name: "t:query:union-clean",
   schema,
-  access: { openToAll: true },
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   handler: async () => cleanUnion,
 });
 
@@ -100,7 +100,7 @@ describe("R6 ContainsSecret", () => {
     const def = defineQueryHandler({
       name: "t:query:clean",
       schema,
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async () => ({ ok: true, value: createSecret("x").reveal() }),
     });
     expect(def.name).toBe("t:query:clean");

package/src/stack/__tests__/request-helper.integration.test.ts

@@ -20,7 +20,7 @@ const pingFeature = defineFeature("reqhelp", (r) => {
       isSuccess: true as const,
       data: { note: event.payload.note, userId: event.user.id },
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -28,7 +28,7 @@ const pingFeature = defineFeature("reqhelp", (r) => {
     z.object({}),
     async () =>
       writeFailure(new UnprocessableError("reqhelp-boom", { i18nKey: "errors.unprocessable" })),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.queryHandler(
@@ -40,7 +40,7 @@ const pingFeature = defineFeature("reqhelp", (r) => {
       }
       return { id: query.payload.id, ok: true };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/stack/__tests__/setup-test-stack-jobs.integration.test.ts

@@ -29,7 +29,7 @@ const manualDispatchFeature = defineFeature("manualdispatch", (r) => {
       await jobRunner.dispatch("manualdispatch:job:record", { note: event.payload.note });
       return { isSuccess: true as const, data: { id: 1, note: event.payload.note } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload) => {
     jobRuns.push({ name: "manualdispatch:job:record", payload });

package/src/testing/__tests__/e2e-generator.test.ts

@@ -34,7 +34,11 @@ function createTasksFeature() {
   return defineFeature("tasks", (r) => {
     r.systemScope();
     r.entity("task", taskEntity);
-    r.writeHandler(defineEntityCreateHandler("task", taskEntity, { access: { openToAll: true } }));
+    r.writeHandler(
+      defineEntityCreateHandler("task", taskEntity, {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      }),
+    );
     r.screen({
       id: "task-list",
       type: "entityList",
@@ -105,7 +109,11 @@ describe("generateE2ESpec", () => {
     const feature = defineFeature("events", (r) => {
       r.systemScope();
       r.entity("event", entity);
-      r.writeHandler(defineEntityCreateHandler("event", entity, { access: { openToAll: true } }));
+      r.writeHandler(
+        defineEntityCreateHandler("event", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
       r.screen({
         id: "event-edit",
         type: "entityEdit",
@@ -165,7 +173,9 @@ describe("generateE2ESpec", () => {
       r.systemScope();
       r.entity("task", taskEntity);
       r.writeHandler(
-        defineEntityCreateHandler("task", taskEntity, { access: { openToAll: true } }),
+        defineEntityCreateHandler("task", taskEntity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
       );
       r.screen({
         id: "edit",
@@ -201,7 +211,9 @@ describe("generateE2ESpec", () => {
       r.systemScope();
       r.entity("contact", contactEntity);
       r.writeHandler(
-        defineEntityCreateHandler("contact", contactEntity, { access: { openToAll: true } }),
+        defineEntityCreateHandler("contact", contactEntity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
       );
       r.screen({
         id: "list",
@@ -225,7 +237,9 @@ describe("generateE2ESpec", () => {
       r.systemScope();
       r.entity("task", taskEntity);
       r.writeHandler(
-        defineEntityCreateHandler("task", taskEntity, { access: { openToAll: true } }),
+        defineEntityCreateHandler("task", taskEntity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
       );
       r.screen({ id: "list", type: "entityList", entity: "task", columns: ["title"] });
       r.screen({

package/src/ui-types/index.ts

@@ -27,12 +27,14 @@ export type { ParsedRefTarget } from "../engine/parse-ref-target";
 export { parseRefTarget } from "../engine/parse-ref-target";
 export {
   evalFieldCondition,
+  explicitListScreenId,
   isExtensionEditSection,
   isFieldsEditSection,
   isFormatSpec,
   isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
+  resolveNavParentScreen,
 } from "../engine/screen-helpers";
 // Entity + field types. EntityDefinition is the canonical shape that
 // view-model builders iterate; FieldDefinition is the per-field union
@@ -99,6 +101,7 @@ export type {
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
+  RelatedListToolbarAction,
   RowAction,
   RowActionDrawer,
   RowActionNavigate,

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { generateId } from "../ids";
+import { generateDeterministicId, generateId } from "../ids";
 
 // generateId is the row/stream/correlation ID source. The callers rely on
 // it being a UUIDv7 (time-sortable → dense B-Tree indexes), not a v4 — a
@@ -22,3 +22,31 @@ describe("generateId", () => {
     expect(new Set(ids).size).toBe(ids.length);
   });
 });
+
+describe("generateDeterministicId", () => {
+  test("returns a well-formed lowercase UUID", () => {
+    expect(generateDeterministicId("ledger:schedule", "contract-1")).toMatch(UUID_RX);
+  });
+
+  test("is UUID version 5 (content-addressed, not v7)", () => {
+    expect(generateDeterministicId("ledger:schedule", "contract-1")[14]).toBe("5");
+  });
+
+  test("is deterministic: same namespace + key always yields the same id", () => {
+    const a = generateDeterministicId("ledger:schedule", "contract-1");
+    const b = generateDeterministicId("ledger:schedule", "contract-1");
+    expect(a).toBe(b);
+  });
+
+  test("differs when the key changes", () => {
+    const a = generateDeterministicId("ledger:schedule", "contract-1");
+    const b = generateDeterministicId("ledger:schedule", "contract-2");
+    expect(a).not.toBe(b);
+  });
+
+  test("differs when the namespace changes for the same key", () => {
+    const a = generateDeterministicId("ledger:schedule", "contract-1");
+    const b = generateDeterministicId("ledger:transaction", "contract-1");
+    expect(a).not.toBe(b);
+  });
+});

package/src/utils/ids.ts

@@ -1,4 +1,4 @@
-import { v7 } from "uuid";
+import { v5, v7 } from "uuid";
 
 // Non-secret identifiers for DB rows, event streams, correlation/request
 // IDs, SSE connections, distributed locks. UUIDv7: first 48 bits are a
@@ -15,3 +15,12 @@ import { v7 } from "uuid";
 export function generateId(): string {
   return v7();
 }
+
+// Derived from a DNS name (RFC 4122 §4.3) so the namespace is reproducible, not a hand-picked constant.
+const DETERMINISTIC_ID_NAMESPACE = v5("kumiko.rocks", v5.DNS);
+
+// Same (namespace, key) → same id, so a redelivered event hits the same row. Ids are
+// unique per table, not per tenant: fold the tenant id into `key` or tenants collide.
+export function generateDeterministicId(namespace: string, key: string): string {
+  return v5(`${namespace}:${key}`, DETERMINISTIC_ID_NAMESPACE);
+}

package/src/utils/index.ts

@@ -2,7 +2,7 @@ export { assertUnreachable } from "./assert";
 export { toSnakeCase } from "./case";
 export { compareByCodepoint } from "./compare";
 export { readPositiveIntEnv } from "./env-parse";
-export { generateId } from "./ids";
+export { generateDeterministicId, generateId } from "./ids";
 export { isPlainObject } from "./is-plain-object";
 export { parseStringArrayJson } from "./parse-string-array-json";
 export { parseJsonOrThrow, parseJsonSafe, stringifyJson } from "./safe-json";