@cosmicdrift/kumiko-framework 0.233.0 → 0.235.0

package/src/pipeline/__tests__/event-dispatcher-start-from.integration.test.ts

@@ -0,0 +1,176 @@
+// EventConsumer.startFrom — opt-in cursor seed on FIRST registration
+// (fw#2482/1). Mounting a NEW consumer into an app whose event log is
+// already populated must not replay history and fire every side-effect
+// step retroactively.
+//
+// setupTestStack's own dispatcher pre-registers every consumer eagerly at
+// stack construction time (test-stack.ts: "Pre-register consumer state
+// rows..."), before any test body can seed historical events — so it can't
+// reproduce "mount into an already-running app" the way this fix needs.
+// This test instead builds its own EventDispatcher via createEventDispatcher()
+// against a plain createTestDb(), and only calls ensureRegistered() AFTER
+// historical events already exist — the same order a real deploy of a new
+// event-triggered workflow hits in production.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DbTx } from "../../db/connection";
+import { insertOne } from "../../db/query";
+import type { AppContext } from "../../engine/types";
+import { eventsTable } from "../../event-store";
+import { createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createEventConsumerStateTable } from "../event-consumer-state";
+import { createEventDispatcher, type EventConsumer, getConsumerState } from "../event-dispatcher";
+import { fetchPendingEvents } from "../event-dispatcher-delivery";
+
+const admin = TestUsers.admin;
+let testDb: TestDb;
+let historicalEventCount = 0;
+
+function stubContext(): AppContext {
+  return {
+    db: {} as unknown as AppContext["db"],
+    redis: {} as unknown as AppContext["redis"],
+    registry: {} as unknown as AppContext["registry"],
+  } as AppContext;
+}
+
+async function appendHistoricalEvent(type: string): Promise<void> {
+  await insertOne(testDb.db, eventsTable, {
+    aggregateId: crypto.randomUUID(),
+    aggregateType: "start-from-test-source",
+    tenantId: admin.tenantId,
+    version: 1,
+    type,
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: admin.id },
+    createdBy: admin.id,
+  });
+  historicalEventCount += 1;
+}
+
+beforeAll(async () => {
+  // createTestDb() already materializes kumiko_events (see stack/db.ts).
+  testDb = await createTestDb();
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("EventConsumer.startFrom", () => {
+  test("'now' seeds the cursor at MAX(events.id) on first registration and skips the historical log", async () => {
+    await appendHistoricalEvent("start-from-test.one");
+    await appendHistoricalEvent("start-from-test.two");
+    await appendHistoricalEvent("start-from-test.three");
+    const headAtMount = BigInt(historicalEventCount);
+
+    const captured: string[] = [];
+    const consumer: EventConsumer = {
+      name: "test:consumer:mounted-now",
+      startFrom: "now",
+      handler: async (event) => {
+        captured.push(event.type);
+      },
+    };
+
+    // Mirrors mounting a new event-triggered workflow into a production app
+    // that already has a populated event log: the dispatcher (and its
+    // consumer) is only constructed AFTER the historical events above exist.
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await dispatcher.ensureRegistered();
+
+    const state = await getConsumerState(testDb.db, consumer.name);
+    expect(state?.lastProcessedEventId).toBe(headAtMount);
+    expect(state?.status).toBe("idle");
+
+    const result = await dispatcher.runOnce();
+    expect(result.byConsumer[consumer.name]).toEqual({ processed: 0, failed: 0 });
+    expect(captured).toHaveLength(0);
+
+    // Not just "not delivered" — proves the id > cursor contract directly:
+    // no historical row is even fetched on the first pass.
+    await testDb.db.begin(async (tx: DbTx) => {
+      const pending = await fetchPendingEvents(tx, headAtMount, 100);
+      expect(pending).toHaveLength(0);
+    });
+  });
+
+  test("without startFrom (default 'beginning') a freshly-registered consumer replays the full historical log", async () => {
+    await appendHistoricalEvent("start-from-test.four");
+    await appendHistoricalEvent("start-from-test.five");
+    const expectedReplayCount = historicalEventCount;
+
+    const captured: string[] = [];
+    const consumer: EventConsumer = {
+      name: "test:consumer:mounted-beginning",
+      handler: async (event) => {
+        captured.push(event.type);
+      },
+    };
+
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await dispatcher.ensureRegistered();
+
+    const stateBefore = await getConsumerState(testDb.db, consumer.name);
+    expect(stateBefore?.lastProcessedEventId).toBe(0n);
+
+    const result = await dispatcher.runOnce();
+    expect(result.byConsumer[consumer.name]).toEqual({ processed: expectedReplayCount, failed: 0 });
+    expect(captured).toEqual([
+      "start-from-test.one",
+      "start-from-test.two",
+      "start-from-test.three",
+      "start-from-test.four",
+      "start-from-test.five",
+    ]);
+  });
+
+  test("re-registering an already-registered consumer never clobbers an advanced cursor", async () => {
+    const consumer: EventConsumer = {
+      name: "test:consumer:advanced-then-remounted",
+      startFrom: "now",
+      handler: async () => {},
+    };
+
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await dispatcher.ensureRegistered();
+    const seeded = await getConsumerState(testDb.db, consumer.name);
+    expect(seeded?.lastProcessedEventId).toBe(BigInt(historicalEventCount));
+
+    await appendHistoricalEvent("start-from-test.six");
+    await dispatcher.runOnce();
+    const advanced = await getConsumerState(testDb.db, consumer.name);
+    expect(advanced?.lastProcessedEventId).toBe(BigInt(historicalEventCount));
+
+    // A new historical event exists again, not yet consumed by this consumer.
+    await appendHistoricalEvent("start-from-test.seven");
+
+    // A second dispatcher instance for the SAME consumer name simulates a
+    // process restart re-running the boot-time pre-registration — the row
+    // already exists, so ON CONFLICT DO NOTHING must leave its advanced
+    // cursor untouched, not reseed it at the new (higher) MAX(events.id).
+    const redeployedDispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await redeployedDispatcher.ensureRegistered();
+
+    const afterRedeploy = await getConsumerState(testDb.db, consumer.name);
+    expect(afterRedeploy?.lastProcessedEventId).toBe(advanced?.lastProcessedEventId);
+  });
+});

package/src/pipeline/event-dispatcher-delivery.ts

@@ -155,7 +155,7 @@ export async function preRegisterConsumers(
 ): Promise<void> {
   for (const consumer of consumers) {
     const instanceId = consumerInstanceId(consumer, dispatcherInstanceId);
-    await insertConsumerIfAbsent(db, consumer.name, instanceId);
+    await insertConsumerIfAbsent(db, consumer.name, instanceId, consumer.startFrom);
   }
 }
 

package/src/pipeline/event-dispatcher.ts

@@ -94,6 +94,12 @@ export type EventConsumer = {
   //                   respect to shared storage (no DB writes), otherwise
   //                   each instance duplicates the effect.
   readonly delivery?: "shared" | "per-instance";
+  // Where the consumer's cursor starts on its FIRST registration. Default
+  // "beginning" replays the full log. "now" seeds the cursor at the current
+  // MAX(events.id) so mounting the consumer into an existing app does not
+  // retroactively fire side effects for historical events. Only affects the
+  // first registration — an existing cursor row is never clobbered.
+  readonly startFrom?: "beginning" | "now";
 };
 
 // Result of a dispatcher pass (runOnce / doPass). Shared across the public

package/src/scripts/codemod/unprocessable-error-details-reason.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+// `UnprocessableOpts.details` was tightened (fw#2460) to `& { readonly reason?:
+// never }` — `reason` is owned exclusively by the ctor's first positional
+// argument, which already folds it into `details` internally
+// (`{ ...opts?.details, reason }`). Any consumer that ALSO puts `reason`
+// inside its `details` object literal now fails with TS2322. This codemod
+// removes that redundant `reason` property; the value is never lost, it was
+// already duplicated from the positional argument.
+//
+// Usage: bun scripts/codemod/unprocessable-error-details-reason.ts <targetDir> [--dry-run]
+
+import { type Dirent, readdirSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import {
+  type Identifier,
+  Node,
+  type ObjectLiteralExpression,
+  Project,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build"]);
+const KUMIKO_MODULE_RE = /^@cosmicdrift\/kumiko-/;
+
+function findTargetFiles(rootDir: string): string[] {
+  // Walk the tree and skip excluded dirs while descending — filtering the
+  // absolute path after a full scan silently no-ops when the repo root
+  // itself contains "/build/" or "/node_modules/" (fw#2289).
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // skip: unreadable directory during walk — treat as empty.
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (EXCLUDE_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+        walk(join(dir, ent.name));
+        continue;
+      }
+      if (ent.isFile() && /\.(ts|tsx)$/.test(ent.name)) {
+        files.push(join(dir, ent.name));
+      }
+    }
+  };
+  walk(rootDir);
+  return files.sort();
+}
+
+type ImportedBinding = { readonly importedName: string; readonly moduleSpecifier: string };
+
+/** Local-name -> where it's imported from, for every named value import in the file. */
+function collectImportedNames(sourceFile: SourceFile): Map<string, ImportedBinding> {
+  const bindings = new Map<string, ImportedBinding>();
+  for (const imp of sourceFile.getImportDeclarations()) {
+    if (imp.isTypeOnly()) continue;
+    const moduleSpecifier = imp.getModuleSpecifierValue();
+    for (const spec of imp.getNamedImports()) {
+      if (spec.isTypeOnly()) continue;
+      const importedName = spec.getName();
+      const localName = spec.getAliasNode()?.getText() ?? importedName;
+      bindings.set(localName, { importedName, moduleSpecifier });
+    }
+  }
+  return bindings;
+}
+
+type DetailsResolution =
+  | { readonly kind: "object-literal"; readonly literal: ObjectLiteralExpression }
+  | { readonly kind: "unresolvable"; readonly note: string }
+  | { readonly kind: "absent" };
+
+/** Resolves `opts.details` to a statically-inspectable object literal, or explains why it can't be. */
+function resolveDetailsProperty(optsLiteral: ObjectLiteralExpression): DetailsResolution {
+  const prop = optsLiteral.getProperty("details");
+  if (!prop) return { kind: "absent" };
+
+  if (Node.isShorthandPropertyAssignment(prop)) {
+    return { kind: "unresolvable", note: "details is a shorthand property (a variable)" };
+  }
+  if (!Node.isPropertyAssignment(prop)) {
+    return { kind: "unresolvable", note: "details is not a plain property assignment" };
+  }
+  if (Node.isComputedPropertyName(prop.getNameNode())) {
+    return { kind: "unresolvable", note: "details key is computed" };
+  }
+  const init = prop.getInitializer();
+  if (!init) return { kind: "unresolvable", note: "details has no initializer" };
+  if (Node.isObjectLiteralExpression(init)) return { kind: "object-literal", literal: init };
+
+  const note = Node.isIdentifier(init)
+    ? `details is a variable ("${init.getText()}")`
+    : Node.isCallExpression(init)
+      ? "details is a call-expression result"
+      : Node.isConditionalExpression(init)
+        ? "details is a conditional expression"
+        : `details is not a statically-analyzable object literal (${init.getKindName()})`;
+  return { kind: "unresolvable", note };
+}
+
+/** True if removing this shorthand-bound identifier would leave its declaration with no other use. */
+function wouldLeaveUnusedVariable(nameNode: Identifier): boolean {
+  try {
+    const refs = nameNode.findReferencesAsNodes();
+    const others = refs.filter((r) => r !== nameNode);
+    return others.length === 0;
+  } catch {
+    // Can't verify — treat as unsafe rather than guess.
+    return true;
+  }
+}
+
+type RemovalResult =
+  | { readonly kind: "removed" }
+  | { readonly kind: "absent" }
+  | { readonly kind: "skip"; readonly note: string };
+
+/** Removes the `reason` property from a `details` object literal, in place. */
+function removeReasonProperty(detailsLiteral: ObjectLiteralExpression): RemovalResult {
+  const properties = detailsLiteral.getProperties();
+  if (properties.some((p) => Node.isSpreadAssignment(p))) {
+    return {
+      kind: "skip",
+      note: "details object literal contains a spread — not statically decidable",
+    };
+  }
+
+  for (const prop of properties) {
+    if (Node.isPropertyAssignment(prop)) {
+      const nameNode = prop.getNameNode();
+      if (Node.isComputedPropertyName(nameNode)) {
+        const expr = nameNode.getExpression();
+        if (Node.isStringLiteral(expr) && expr.getLiteralText() === "reason") {
+          return { kind: "skip", note: "reason key is computed — not safe to remove mechanically" };
+        }
+        continue;
+      }
+      const propName = Node.isIdentifier(nameNode)
+        ? nameNode.getText()
+        : Node.isStringLiteral(nameNode)
+          ? nameNode.getLiteralText()
+          : undefined;
+      if (propName === "reason") {
+        prop.remove();
+        return { kind: "removed" };
+      }
+      continue;
+    }
+    if (Node.isShorthandPropertyAssignment(prop) && prop.getName() === "reason") {
+      if (wouldLeaveUnusedVariable(prop.getNameNode())) {
+        return {
+          kind: "skip",
+          note: "reason is a shorthand property; removing it would leave the bound variable unused",
+        };
+      }
+      prop.remove();
+      return { kind: "removed" };
+    }
+  }
+  return { kind: "absent" };
+}
+
+type CallOutcome = "changed" | "skipped" | "not-a-match";
+
+function processNewExpression(args: readonly Node[], report: (note: string) => void): CallOutcome {
+  const optsArg = args[1];
+  if (!optsArg) return "not-a-match";
+
+  if (!Node.isObjectLiteralExpression(optsArg)) {
+    report(
+      "second argument (opts) is not a statically-analyzable object literal — cannot verify details.reason",
+    );
+    return "skipped";
+  }
+
+  const detailsRes = resolveDetailsProperty(optsArg);
+  if (detailsRes.kind === "absent") return "not-a-match";
+  if (detailsRes.kind === "unresolvable") {
+    report(detailsRes.note);
+    return "skipped";
+  }
+
+  const removal = removeReasonProperty(detailsRes.literal);
+  if (removal.kind === "absent") return "not-a-match";
+  if (removal.kind === "skip") {
+    report(removal.note);
+    return "skipped";
+  }
+  return "changed";
+}
+
+type SkipEntry = { readonly file: string; readonly line: number; readonly note: string };
+
+/** Migrates one file in place. Returns how many `reason` properties were removed. */
+function migrateFile(sourceFile: SourceFile, skips: SkipEntry[]): number {
+  const importedNames = collectImportedNames(sourceFile);
+  let removedCount = 0;
+
+  for (const newExpr of sourceFile.getDescendantsOfKind(SyntaxKind.NewExpression)) {
+    const callee = newExpr.getExpression();
+    if (!Node.isIdentifier(callee)) continue;
+    const localName = callee.getText();
+
+    const binding = importedNames.get(localName);
+    const isFrameworkUnprocessableError = binding?.importedName === "UnprocessableError";
+
+    if (!isFrameworkUnprocessableError) {
+      if (localName !== "UnprocessableError") continue;
+      const note = binding
+        ? `UnprocessableError is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`
+        : "UnprocessableError has no @cosmicdrift/kumiko-* import in this file (likely a locally defined class)";
+      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
+      continue;
+    }
+    if (!KUMIKO_MODULE_RE.test(binding.moduleSpecifier)) {
+      skips.push({
+        file: sourceFile.getFilePath(),
+        line: newExpr.getStartLineNumber(),
+        note: `UnprocessableError is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`,
+      });
+      continue;
+    }
+
+    const outcome = processNewExpression(newExpr.getArguments(), (note) => {
+      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
+    });
+    if (outcome === "changed") removedCount++;
+  }
+
+  return removedCount;
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const dryRun = process.argv.includes("--dry-run");
+  const rootDir = resolve(positional[0] ?? process.cwd());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  let removedTotal = 0;
+  const skips: SkipEntry[] = [];
+
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const removed = migrateFile(sourceFile, skips);
+    if (removed === 0) continue;
+
+    touchedFiles++;
+    removedTotal += removed;
+    if (!dryRun) sourceFile.saveSync();
+  }
+
+  console.log(`\nScanned ${files.length} files under ${rootDir}${dryRun ? " (dry-run)" : ""}.`);
+  console.log(
+    `Touched ${touchedFiles} files, removed ${removedTotal} redundant "reason" propert(y/ies).`,
+  );
+  console.log(`Skipped ${skips.length} site(s):`);
+  for (const s of skips) {
+    console.log(`  ${relative(rootDir, s.file)}:${s.line} — ${s.note}`);
+  }
+  console.log();
+}
+
+await main();

package/src/testing/e2e-generator.ts

@@ -112,6 +112,9 @@ export function generateE2ESpec(
     // pro Field geschrieben, ohne CRUD-Zustand zu generieren wäre der
     // Spec wertlos. Branding/SMTP/etc. sind Author-spezifisch.
     if (screen.type === "configEdit") continue;
+    // secretsEdit: dito — writes go through secrets:write:set with
+    // plaintext values the generator has no author-defined test data for.
+    if (screen.type === "secretsEdit") continue;
     // projectionList: query-getrieben, Author-spezifische Projection —
     // kein generischer CRUD-Spec ableitbar (wie actionForm/configEdit).
     if (screen.type === "projectionList") continue;

package/src/ui-types/index.ts

@@ -52,7 +52,7 @@ export type {
   TextFieldDef,
 } from "../engine/types/fields";
 export type { AccessRule } from "../engine/types/handlers";
-export type { NavDefinition, NavIconKey } from "../engine/types/nav";
+export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav";
 export type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -93,6 +93,8 @@ export type {
   ScreenFilter,
   ScreenFilterOp,
   ScreenSlots,
+  SecretsEditScreenDefinition,
+  SecretsEditSection,
   ToolbarAction,
 } from "../engine/types/screen";
 export type { TargetRef } from "../engine/types/target-ref";