@cosmicdrift/kumiko-framework 0.211.0 → 0.213.0

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/stack/test-stack.ts

@@ -153,6 +153,11 @@ export type TestStackOptions = {
     consumerLane?: JobRunIn;
     queueNamePrefix?: string;
   };
+  /** Override the event dispatcher's polling-timer interval. Default 50ms.
+   *  Tests that assert LISTEN/NOTIFY wake-up latency need this pushed far
+   *  out (e.g. 60_000) so the polling timer can't land inside the
+   *  assertion window and mask a dead subscription — see E.4 (#2042). */
+  eventDispatcherPollIntervalMs?: number;
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -379,7 +384,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       // plumbs through the LISTEN wake-up for tests that want to measure
       // post-commit latency (Sprint E.4).
       eventDispatcher: {
-        pollIntervalMs: 50,
+        pollIntervalMs: options.eventDispatcherPollIntervalMs ?? 50,
         pgClient: testDb.client as PgClient | undefined,
         systemConsumers: {
           sse: enabledHooks.includes("sse"),

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,
   };
 }

package/src/upgrade-cli.ts

@@ -0,0 +1,445 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { getFlag, getStringFlag, parseArgs } from "./arg-parser";
+import {
+  type ChangelogEntry,
+  compareVersions,
+  filterEntriesAfter,
+  parseFeatureChangelog,
+  sortEntries,
+} from "./engine";
+import { ensureTemporalPolyfill } from "./time";
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const CODEMOD_SUBDIR = "scripts/codemod";
+
+export type UpgradeCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+function readPackageVersion(cwd: string, pkgName: string, repoLocalPath: string): string | null {
+  // Walk up from cwd to find node_modules/@cosmicdrift/<pkgName>/package.json
+  // (handles bun workspace hoisting where packages live in parent node_modules)
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    const nmPath = join(dir, `node_modules/@cosmicdrift/${pkgName}/package.json`);
+    if (existsSync(nmPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(nmPath, "utf-8"));
+        return pkg.version ?? null;
+      } catch {
+        return null;
+      }
+    }
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fallback: repo-local package root
+  const repoPath = join(cwd, repoLocalPath);
+  if (existsSync(repoPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(repoPath, "utf-8"));
+      return pkg.version ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// Changelog entries come from @cosmicdrift/kumiko-bundled-features (see
+// findFeaturesDirs); comparing against the framework version instead
+// compares unrelated packages once the two stop being versioned in lockstep.
+function readCurrentVersion(cwd: string): string | null {
+  return (
+    readPackageVersion(cwd, "kumiko-bundled-features", "packages/bundled-features/package.json") ??
+    readPackageVersion(cwd, "kumiko-framework", "packages/framework/package.json")
+  );
+}
+
+function readChangelogFile(filePath: string): ChangelogEntry[] {
+  if (!existsSync(filePath)) return [];
+  try {
+    return [...(parseFeatureChangelog(readFileSync(filePath, "utf-8"), filePath)?.entries ?? [])];
+  } catch {
+    // Skip malformed files
+    return [];
+  }
+}
+
+function collectChangelogs(featuresDir: string): ChangelogEntry[] {
+  if (!existsSync(featuresDir)) return [];
+
+  const entries: ChangelogEntry[] = [];
+  const features = readdirSync(featuresDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  for (const name of features) {
+    // Layout is detected per-package, not guessed from a naming convention:
+    // enterprise packages keep changes.json under src/, framework's
+    // bundled-features keep it flat. A name-prefix heuristic (e.g. "ai-*")
+    // silently drops packages that don't match it (fw#1605).
+    const srcLayout = join(featuresDir, name, "src", "changes.json");
+    const flatLayout = join(featuresDir, name, "changes.json");
+    const changelogPath = existsSync(srcLayout) ? srcLayout : flatLayout;
+
+    entries.push(...readChangelogFile(changelogPath));
+  }
+
+  return entries;
+}
+
+// Framework core changes belong to no feature — they live in a single
+// changes.json next to the framework sources.
+export function findCoreChangelogFile(cwd: string): string | null {
+  const repoPath = join(cwd, "packages/framework/src/changes.json");
+  if (existsSync(repoPath)) return repoPath;
+
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    const nmPath = join(dir, "node_modules/@cosmicdrift/kumiko-framework/src/changes.json");
+    if (existsSync(nmPath)) return nmPath;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+export function findFeaturesDirs(cwd: string): string[] {
+  const dirs: string[] = [];
+
+  // Framework repo: packages/bundled-features/src
+  const fwDir = join(cwd, "packages/bundled-features/src");
+  if (existsSync(fwDir)) dirs.push(fwDir);
+
+  // Enterprise repo: packages/<name>/src/changes.json or packages/<name>/changes.json.
+  // Detected by presence of changes.json, not a package-name prefix — a
+  // prefix heuristic silently stops matching once packages are renamed or a
+  // differently-named package is added (fw#1605). Skipped inside the
+  // framework repo itself (packages/framework present): its own
+  // packages/framework/src/changes.json is the core changelog (already
+  // collected via findCoreChangelogFile), not a feature package, and would
+  // otherwise get double-counted as one here.
+  const isFrameworkRepo = existsSync(join(cwd, "packages/framework"));
+  const entDir = join(cwd, "packages");
+  if (!isFrameworkRepo && existsSync(entDir)) {
+    const hasEntPkgs = readdirSync(entDir, { withFileTypes: true }).some(
+      (d) =>
+        d.isDirectory() &&
+        (existsSync(join(entDir, d.name, "changes.json")) ||
+          existsSync(join(entDir, d.name, "src", "changes.json"))),
+    );
+    if (hasEntPkgs) dirs.push(entDir);
+  }
+
+  // App repos: walk up to find bundled-features in hoisted node_modules.
+  // Skipped inside the framework repo — the workspace symlink points back at
+  // the dir already collected above and would duplicate every entry.
+  if (dirs.includes(fwDir)) return dirs;
+
+  let dir = cwd;
+  for (let i = 0; i < 10; i++) {
+    const nmDir = join(dir, "node_modules/@cosmicdrift/kumiko-bundled-features/src");
+    if (existsSync(nmDir)) {
+      dirs.push(nmDir);
+      break;
+    }
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return dirs;
+}
+
+// Resolves a changes.json `codemod` field to an absolute script path,
+// refusing anything that would escape scripts/codemod/ (path traversal,
+// absolute paths, symlinks pointing outward) or that isn't a real .ts file.
+export function resolveCodemodScript(
+  repoRoot: string,
+  codemodField: string | undefined,
+): string | null {
+  if (!codemodField) return null;
+  if (codemodField.includes("\0") || codemodField.startsWith("/") || !codemodField.endsWith(".ts"))
+    return null;
+
+  const scriptsRoot = join(repoRoot, CODEMOD_SUBDIR);
+  const resolved = join(repoRoot, codemodField);
+  const rel = relative(scriptsRoot, resolved);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  if (!existsSync(resolved)) return null;
+
+  try {
+    const realResolved = realpathSync(resolved);
+    const realScriptsRoot = realpathSync(scriptsRoot);
+    const realRel = relative(realScriptsRoot, realResolved);
+    if (realRel.startsWith("..") || isAbsolute(realRel)) return null;
+  } catch {
+    return null;
+  }
+
+  return resolved;
+}
+
+type CodemodRunResult = { readonly ok: boolean; readonly output: string };
+
+// Array-form argv only — never a shell string. The script itself decides
+// what to touch inside targetDir; this just invokes it as a subprocess.
+async function runCodemodScript(
+  scriptPath: string,
+  targetDir: string,
+  repoRoot: string,
+  dryRun: boolean,
+): Promise<CodemodRunResult> {
+  const cmd = ["bun", scriptPath, targetDir, ...(dryRun ? ["--dry-run"] : [])];
+  const proc = Bun.spawn({ cmd, cwd: repoRoot, stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { ok: exitCode === 0, output: `${stdout}${stderr}`.trim() };
+}
+
+function hasCodemod(e: ChangelogEntry): e is ChangelogEntry & { codemod: string } {
+  return typeof e.codemod === "string" && e.codemod.length > 0;
+}
+
+type UpgradeMarkerCodemod = {
+  readonly version: string;
+  readonly codemod: string;
+  readonly title: string;
+};
+type UpgradeMarker = {
+  readonly version: string;
+  readonly appliedAt: string;
+  readonly codemods: readonly UpgradeMarkerCodemod[];
+};
+
+function writeUpgradeMarker(targetDir: string, marker: UpgradeMarker): void {
+  const dir = join(targetDir, ".kumiko");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "upgrade-state.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
+}
+
+// Runs every pending breaking entry's codemod, oldest version first (so a
+// later codemod can assume an earlier one already ran). Stops on the first
+// failure — no partial marker. Writes the marker whenever dryRun is false —
+// even with zero pending entries, so an already-current app still gets a
+// bootstrap marker recording its installed version (fw#2299).
+async function applyCodemods(
+  out: UpgradeCliOut,
+  pending: readonly ChangelogEntry[],
+  repoRoot: string,
+  targetDir: string,
+  dryRun: boolean,
+  currentVersion: string,
+): Promise<number> {
+  if (pending.length === 0) {
+    out.log("  ✓ Nothing new since your version.");
+    if (!dryRun) {
+      writeUpgradeMarker(targetDir, {
+        version: currentVersion,
+        appliedAt: Temporal.Now.instant().toString(),
+        codemods: [],
+      });
+      out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+    }
+    return 0;
+  }
+
+  const breaking = pending.filter((e) => e.type === "breaking");
+  const codemodEntries = breaking
+    .filter(hasCodemod)
+    .sort((a, b) => compareVersions(a.version, b.version));
+  const manualEntries = breaking.filter((e) => !e.codemod);
+
+  for (const e of manualEntries) {
+    out.log(`  ⚠ ${e.version} · ${e.title} — no codemod, manual migration required`);
+  }
+
+  if (codemodEntries.length === 0) {
+    out.log(
+      breaking.length > 0
+        ? "  No automatable codemods among the pending breaking changes."
+        : "  ✓ No breaking changes pending.",
+    );
+    return 0;
+  }
+
+  const ran: UpgradeMarkerCodemod[] = [];
+  for (const e of codemodEntries) {
+    const scriptPath = resolveCodemodScript(repoRoot, e.codemod);
+    if (!scriptPath) {
+      out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
+      return 1;
+    }
+
+    out.log(`  → ${e.version} · running ${e.codemod}${dryRun ? " (dry-run)" : ""}`);
+    const result = await runCodemodScript(scriptPath, targetDir, repoRoot, dryRun);
+    if (result.output) out.log(result.output);
+    if (!result.ok) {
+      out.err(`  ✗ ${e.version} · ${e.codemod} failed`);
+      return 1;
+    }
+    ran.push({ version: e.version, codemod: e.codemod, title: e.title });
+  }
+
+  if (dryRun) {
+    out.log(`  ✓ Dry-run: ${ran.length} codemod(s) would run. Nothing written.`);
+    return 0;
+  }
+
+  const latestVersion = pending.reduce(
+    (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
+    pending[0]!.version,
+  );
+  writeUpgradeMarker(targetDir, {
+    version: latestVersion,
+    appliedAt: Temporal.Now.instant().toString(),
+    codemods: ran,
+  });
+  out.log(
+    `  ✓ Applied ${ran.length} codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`,
+  );
+  return 0;
+}
+
+// kumiko-lint-ignore complexity-budget CLI orchestration moved from bin/commands/upgrade.ts — same branching surface, shared by kumiko upgrade + published kumiko-upgrade bin
+export async function runUpgradeCli(
+  argv: readonly string[],
+  cwd: string,
+  out: UpgradeCliOut,
+  options?: { readonly repoRoot?: string },
+): Promise<number> {
+  // Standalone CLI entry, not booted via runProdApp/runDevApp — Temporal needs an explicit polyfill here.
+  await ensureTemporalPolyfill();
+  const repoRoot = options?.repoRoot ?? cwd;
+  const args = parseArgs(argv);
+  const jsonMode = getFlag(args, "json");
+  const verbose = getFlag(args, "verbose");
+  const fromFlag = getStringFlag(args, "from");
+
+  const currentVersion = fromFlag ?? readCurrentVersion(cwd);
+  if (!currentVersion) {
+    out.err("");
+    out.err("  Could not detect Kumiko version.");
+    out.err("  Run from an app directory with node_modules, or use --from <version>.");
+    out.err("");
+    return 1;
+  }
+
+  if (!SEMVER_RE.test(currentVersion)) {
+    out.err("");
+    out.err(`  Invalid version format: "${currentVersion}" — expected x.y.z`);
+    out.err("");
+    return 1;
+  }
+
+  const featuresDirs = findFeaturesDirs(cwd);
+  const coreChangelogFile = findCoreChangelogFile(cwd);
+  if (featuresDirs.length === 0 && !coreChangelogFile) {
+    out.err("");
+    out.err("  Could not find bundled-features directory.");
+    out.err("  Run from framework/enterprise repo or an app with node_modules.");
+    out.err("");
+    return 1;
+  }
+
+  const allEntries: ChangelogEntry[] = [];
+  for (const dir of featuresDirs) {
+    allEntries.push(...collectChangelogs(dir));
+  }
+  if (coreChangelogFile) {
+    allEntries.push(...readChangelogFile(coreChangelogFile));
+  }
+  const pending = sortEntries(filterEntriesAfter(allEntries, currentVersion));
+
+  if (getFlag(args, "apply")) {
+    const dirFlag = getStringFlag(args, "dir");
+    const targetDir = dirFlag ? resolve(dirFlag) : cwd;
+    const dryRun = getFlag(args, "dry-run");
+    out.log("");
+    const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, currentVersion);
+    out.log("");
+    return code;
+  }
+
+  if (jsonMode) {
+    out.log(JSON.stringify({ currentVersion, pending }, null, 2));
+    return 0;
+  }
+
+  const breaking = pending.filter((e) => e.type === "breaking");
+  const improvements = pending.filter((e) => e.type === "improvement");
+  const fixes = pending.filter((e) => e.type === "fix");
+
+  out.log("");
+  out.log(`  Upgrade: ${currentVersion} → latest`);
+  out.log("");
+
+  if (pending.length === 0) {
+    out.log("  ✓ Nothing new since your version.");
+    out.log("");
+    return 0;
+  }
+
+  if (breaking.length > 0) {
+    out.log(`  ⚠ BREAKING (${breaking.length})`);
+    out.log("");
+    for (const e of breaking) {
+      out.log(`    ${e.version} · ${e.title}`);
+      if (verbose && e.detail) {
+        out.log(`      ${e.detail}`);
+      }
+      if (e.migration) {
+        out.log(`      → Migration: ${e.migration}`);
+      }
+      out.log("");
+    }
+  }
+
+  if (improvements.length > 0) {
+    out.log(`  ✓ IMPROVEMENTS (${improvements.length})`);
+    out.log("");
+    for (const e of improvements) {
+      out.log(`    ${e.version} · ${e.title}`);
+      if (verbose && e.detail) {
+        out.log(`      ${e.detail}`);
+      }
+    }
+    out.log("");
+  }
+
+  if (fixes.length > 0) {
+    out.log(`  ✓ FIXES (${fixes.length})`);
+    out.log("");
+    for (const e of fixes) {
+      out.log(`    ${e.version} · ${e.title}`);
+      if (verbose && e.detail) {
+        out.log(`      ${e.detail}`);
+      }
+    }
+    out.log("");
+  }
+
+  if (breaking.length > 0) {
+    out.log("  ⚠ Review breaking changes above before upgrading.");
+    out.log("  Run with --verbose for full migration details.");
+    out.log("");
+  }
+
+  return 0;
+}