@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

package/dist/upgrade-cli.js

@@ -446,7 +446,7 @@ function writePartialMarker(out, targetDir, pending, manualEntries, failedVersio
     });
     out.err(`  ⚠ ${ran.length} codemod(s) already applied; wrote marker at ${version} so a re-run resumes at the failed one.`);
 }
-// Runs every pending breaking entry's codemod, oldest version first (so a
+// Runs every pending entry's codemod, oldest version first (so a
 // later codemod can assume an earlier one already ran). Stops on the first
 // failure; codemods that already ran are kept in a partial marker. Writes the
 // marker whenever dryRun is false —
@@ -474,7 +474,9 @@ markerVersion, previous) {
         return 0;
     }
     const breaking = pending.filter((e) => e.type === "breaking");
-    const codemodEntries = breaking
+    // A codemod is worth running whatever the entry's type: an improvement that
+    // moves a module ships one too, and skipping it leaves the deprecated path in place.
+    const codemodEntries = pending
         .filter(hasCodemod)
         .sort((a, b) => compareVersions(a.version, b.version));
     const manualEntries = breaking.filter(needsManualMigration);
@@ -485,7 +487,7 @@ markerVersion, previous) {
     }
     if (codemodEntries.length === 0) {
         out.log(breaking.length > 0
-            ? "  No automatable codemods among the pending breaking changes."
+            ? "  No automatable codemods among the pending changes."
             : "  ✓ No breaking changes pending.");
         if (!dryRun) {
             const carried = carryOverManual(previous, manualEntries.map(toMarkerManual));
@@ -636,7 +638,7 @@ kumiko-upgrade --resolve <id|version>[,<id|version>...] --reason "<text>" [--not
   --dir <path>       target directory to check/apply against (default: cwd)
   --json             machine-readable output
   --verbose          include full migration details for each pending entry
-  --apply            run codemods for pending breaking changes and write the upgrade marker
+  --apply            run codemods for pending changes and write the upgrade marker
                      (one run moves the marker to the installed version; manual migrations stay listed as open)
   --resolve <refs>   mark open manual migrations as done; ref = full id or a version with exactly one open entry
   --reason <text>    required with --resolve, max 500 characters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.367.0",
+  "version": "0.369.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>",
@@ -27,7 +27,10 @@
     "runtime": "runtime",
     "bunOnlyExports": [
       "./engine/codemod",
-      "./testing"
+      "./stack",
+      "./testing",
+      "./testing/e2e-generator",
+      "./testing/real-providers"
     ]
   },
   "exports": {
@@ -64,8 +67,8 @@
       "default": "./dist/errors/index.js"
     },
     "./bun-db": {
-      "types": "./dist/bun-db/index.d.ts",
-      "default": "./dist/bun-db/index.js"
+      "types": "./dist/db/bun-db-deprecated.d.ts",
+      "default": "./dist/db/bun-db-deprecated.js"
     },
     "./db": {
       "types": "./dist/db/index.d.ts",
@@ -191,6 +194,14 @@
       "types": "./dist/api/request-context.d.ts",
       "default": "./dist/api/request-context.js"
     },
+    "./internal/stack-support": {
+      "types": "./dist/internal/stack-support.d.ts",
+      "default": "./dist/internal/stack-support.js"
+    },
+    "./internal/testing": {
+      "types": "./dist/internal/testing.d.ts",
+      "default": "./dist/internal/testing.js"
+    },
     "./testing/e2e-generator": {
       "types": "./dist/testing/e2e-generator.d.ts",
       "default": "./dist/testing/e2e-generator.js"
@@ -210,8 +221,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.367.0",
-    "@cosmicdrift/kumiko-types": "0.367.0",
+    "@cosmicdrift/kumiko-http": "0.369.0",
+    "@cosmicdrift/kumiko-types": "0.369.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,10 +238,19 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.367.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.369.0",
+    "@cosmicdrift/kumiko-testing": "0.369.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },
+  "peerDependencies": {
+    "@cosmicdrift/kumiko-testing": ">=0.366.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cosmicdrift/kumiko-testing": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",
@@ -268,8 +288,8 @@
         "default": "./dist/errors/index.js"
       },
       "./bun-db": {
-        "types": "./dist/bun-db/index.d.ts",
-        "default": "./dist/bun-db/index.js"
+        "types": "./dist/db/bun-db-deprecated.d.ts",
+        "default": "./dist/db/bun-db-deprecated.js"
       },
       "./db": {
         "types": "./dist/db/index.d.ts",
@@ -395,6 +415,14 @@
         "types": "./dist/api/request-context.d.ts",
         "default": "./dist/api/request-context.js"
       },
+      "./internal/stack-support": {
+        "types": "./dist/internal/stack-support.d.ts",
+        "default": "./dist/internal/stack-support.js"
+      },
+      "./internal/testing": {
+        "types": "./dist/internal/testing.d.ts",
+        "default": "./dist/internal/testing.js"
+      },
       "./testing/e2e-generator": {
         "types": "./dist/testing/e2e-generator.d.ts",
         "default": "./dist/testing/e2e-generator.js"

package/src/changes.json

@@ -1,4 +1,68 @@
 [
+  {
+    "version": "0.369.0",
+    "type": "fix",
+    "title": "kumiko-upgrade --apply runs codemods of improvement entries too",
+    "detail": "The apply step only ran codemods attached to breaking entries. The 0.368.0 entry that moves the test stack to kumiko-testing is an improvement with a codemod (testing-move), so `bun kumiko-upgrade --apply` skipped it and left the deprecated framework paths in place. Every pending entry with a codemod now runs, in version order; manual-migration reporting is unchanged. Apps whose marker is already at 0.368.0 no longer see that entry as pending, so they run `bun kumiko-upgrade --apply --from 0.367.0` once, or the codemod directly: `bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/testing-move.ts . --write`."
+  },
+  {
+    "version": "0.368.0",
+    "type": "fix",
+    "title": "Append version conflicts carry currentVersion and no longer poison the transaction",
+    "detail": "append() inserts with ON CONFLICT (tenant_id, aggregate_id, version) DO NOTHING and reads the stream version in the still-intact transaction. VersionConflictError gets an optional currentVersion, and custom writes (ctx.appendEvent, stream.append, appendEventInTenantDb) now answer 409 with the winner's version instead of -1, so a client can rebase. A missing predecessor reports the real stream version too.\n\nBehaviour change: a lost append race no longer raises a unique violation, so the outer transaction is not aborted (25P02). A handler that catches the VersionConflictError keeps writing and commits. Idempotency-key collisions still throw IdempotentAppendConflictError. Relies on READ COMMITTED, the Postgres default."
+  },
+  {
+    "version": "0.368.0",
+    "type": "breaking",
+    "title": "createDbConnection({ url, ... }) is the only connection factory, query helpers move from /bun-db to /db",
+    "detail": "postgres-js is the only DB driver. createDbConnection takes one options object, is synchronous and accepts the new options ssl and onNotice. The Bun.SQL provider, createConnection, createPgConnection and DB_PROVIDER are removed. The query helpers (selectMany, insertOne, transaction, asRawClient, ...) keep their API and are now exported from @cosmicdrift/kumiko-framework/db. The `tx` handed to the transaction() callback is typed as DbTx (the postgres-js transaction handle it always was at runtime) instead of the Bun.SQL instance type; a helper that takes `db: DbConnection` and receives that tx needs `DbRunner` or `DbTx`.\n\nThe positional form createDbConnection(url, options) and the @cosmicdrift/kumiko-framework/bun-db subpath keep working as deprecated aliases and are removed in the first release after 2026-10-29.\n\nold -> new:\n  createConnection(url, options) (async) -> createDbConnection({ url, ...options }) (sync)\n  createPgConnection(url, options) -> createDbConnection({ url, ...options })\n  createDbConnection(url, options) -> createDbConnection({ url, ...options }) (positional form is deprecated)\n  @cosmicdrift/kumiko-framework/bun-db -> @cosmicdrift/kumiko-framework/db (deprecated alias until the first release after 2026-10-29)\n\nRemoved without replacement: createBunDbConnection, bunDbConnectionOptionsFromEnv, the BunDbConnection, BunDbTx, BunDbRunner and BunDbConnectionOptions types, DbPoolHandle (use DbConnectionHandle), the PgListenClient re-export from /bun-db (import it from @cosmicdrift/kumiko-types/db-connection) and the DB_PROVIDER environment variable.",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites bun-db imports to /db, createDbConnection(url, options) and createConnection/createPgConnection calls to the object form, and reports leftovers (removed Bun.SQL exports, DB_PROVIDER) with file and line. Remove DB_PROVIDER from your env files.",
+    "codemod": "scripts/codemod/db-factory.ts"
+  },
+  {
+    "version": "0.368.0",
+    "type": "breaking",
+    "title": "Bundled feature constants become create*Feature() factories",
+    "detail": "Every bundled feature that was mounted as a constant (tagsFeature, ledgerFeature, authFoundationFeature, ...) now has a create<Name>Feature() factory exported from the same subpath, and apps mount `createTagsFeature()` instead of `tagsFeature`. Factories of features without options take no arguments; the ones that already had options keep them. Two calls of a factory give interchangeable instances, so mounting the same feature from two stacks does not trip the \"mounted twice as distinct instances\" check.\n\nThe old constants keep working as deprecated aliases and are removed in the first release after 2026-10-29.\n\nold -> new:\n  tagsFeature -> createTagsFeature()\n  ledgerFeature -> createLedgerFeature()\n  authFoundationFeature -> createAuthFoundationFeature()\n  fooBarFeature -> createFooBarFeature() (same rule for every bundled feature constant)\n  typeof tagsFeature -> ReturnType<typeof createTagsFeature>",
+    "migration": "Run `bun kumiko-upgrade --apply`. It renames the imports and replaces every use with the factory call. It reports aliased imports, re-exports, namespace access, dynamic imports and files that compare a feature by identity with file and line; handle those by hand (one factory call per mount, or keep one shared instance).",
+    "codemod": "scripts/codemod/feature-factory.ts"
+  },
+  {
+    "version": "0.368.0",
+    "type": "fix",
+    "title": "List filters can no longer probe secret, encrypted or personal fields",
+    "detail": "A `filter`/`filters` entry on a field with `find: \"secret\"`, `encrypted: true` or a personal-data annotation made hit count and `totalCount` a value oracle (a prefix oracle for legacy plaintext rows before the backfill). The list handler now answers 400 `validation_error` with a field issue `field_not_filterable` (path `filter.<field>`). The one exception is `op: \"eq\"` with a string on a personal field with `find: \"exact\"` or `\"fuzzy\"`, which matches through the blind index. A sort on such a field falls back to id order instead of failing. Unknown fields are still dropped and fields without read access still match nothing; both checks run first.\n\nThe entityList boot validator rejects a screen `filter` the handler would reject.\n\nBehaviour change: clients that filter on such a field (or send `in`, range or `ne` on a blind-indexed one) now get a 4xx instead of an empty or matching result."
+  },
+  {
+    "version": "0.368.0",
+    "type": "improvement",
+    "title": "whenAbsent \"self\" keys ownerless personal fields on the record instead of the tenant",
+    "detail": "A personal field with a nullable owner can now declare `personal: { of: \"ownerId\", whenAbsent: \"self\" }` (entity fields and `defineEvent` piiFields). While the owner is empty, the value is encrypted under `record:<entity>:<id>`, the same subject as `personal: \"self\"` on events and `personal: { of: \"id\" }` on entities. `forget-subject` on that record then erases the value, its blind index and its search document; with `\"tenant\"` the value stayed readable until the tenant was destroyed. A row can mix subjects: the ciphertext names its key inline, so owner-keyed, tenant-keyed and record-keyed fields decrypt side by side.\n\nThe boot validator accepts \"self\" next to \"tenant\" and rejects it on `idType: \"serial\"` entities, because a forget-subject request needs a UUID record id. Owner transitions behave as for \"tenant\": when an update assigns an owner (absent to X) the value moves from the record key to the user key; the created event stays record-keyed. The data-retention hardDelete also erases the record key of an ownerless \"self\" row; a row with an owner keeps its owner key.",
+    "migration": "Switching an existing field from `whenAbsent: \"tenant\"` to `\"self\"` changes only new writes. Events and rows written earlier stay tenant-keyed (still readable) until the PII event backfill re-keys them. The backfill fingerprint is bumped (`owner-rekey-v2`), so the boot-time backfill runs one more full pass: tenant-keyed values of rows without an owner move under their record key, tenant-keyed values of rows with an owner still move under that owner. The pass rewrites event payloads in place through the existing backfill path and queues the affected projections for rebuild. Apps that run the backfill manually call `backfillEventPiiEncryption` with `resolveOwnerFromProjection: true, rekeyTenantKeyedOwnerFields: true`, then rebuild the projections. Values of a record forgotten earlier become `[[erased]]`. The re-key covers entity lifecycle events only: custom `defineEvent` piiFields that switch from `whenAbsent: \"tenant\"` to `\"self\"` keep their old events tenant-keyed.\n\nOld events are never reinterpreted at read time: an old created event of a row that got an owner later keeps its record key until a forget of that record, which erases it, while the later owner-keyed copies stay readable."
+  },
+  {
+    "version": "0.368.0",
+    "type": "breaking",
+    "title": "createTenantDb({ db, tenantId, ... }) takes one options object",
+    "detail": "createTenantDb takes one CreateTenantDbOptions object ({ db, tenantId, mode?, tracer?, meter?, signal?, grants? }); mode still defaults to \"tenant\". The positional form createTenantDb(db, tenantId, mode, tracer, meter, signal, grants) keeps working as a deprecated overload and is removed in the first release after 2026-10-29.\n\nold -> new:\n  createTenantDb(db, tenantId) -> createTenantDb({ db, tenantId })\n  createTenantDb(db, tenantId, \"system\", tracer, meter, signal, grants) -> createTenantDb({ db, tenantId, mode: \"system\", tracer, meter, signal, grants })",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites positional calls (literal undefined arguments are dropped) and reports spread arguments, calls with more than seven arguments and uses of createTenantDb as a value (callback, .bind/.call/.apply) with file and line.",
+    "codemod": "scripts/codemod/tenant-db-options.ts"
+  },
+  {
+    "version": "0.368.0",
+    "type": "breaking",
+    "title": "HandlerContext and AppContext no longer expose _userId and _handlerType",
+    "detail": "The dispatcher no longer sets _userId and _handlerType on the context of write handlers, query handlers and hooks. The caller identity is ctx.user.id. requireSecretsContext reads ctx._userId first and falls back to ctx.user.id, so passing a handler context to it keeps the same audit identity. Provider contexts (FileProviderContext, MailTransportContext, InboundMailContext) keep their own _userId. JobContext._userId is unchanged.",
+    "migration": "Replace ctx._userId with ctx.user.id in write/query handlers and hooks. Known sites: one file each in money-horse, offlot-app, phronexsis and kumiko-enterprise. _handlerType had no readers."
+  },
+  {
+    "version": "0.368.0",
+    "type": "improvement",
+    "title": "Test stack and helpers moved to kumiko-testing, old framework paths are deprecated",
+    "detail": "Everything a test needs now lives in @cosmicdrift/kumiko-testing. Its core (stack, helpers, preload, bunfig, integration-runner) depends only on kumiko-framework and kumiko-types; bundled-features and dev-server are optional peers used by the root entry and /e2e. Install kumiko-testing as a dev dependency where tests import it.\n\nThe old framework paths re-export the new ones and are removed in the first release after 2026-10-29. Production symbols that tests also use stay in the framework.\n\nold -> new:\n  @cosmicdrift/kumiko-framework/stack -> @cosmicdrift/kumiko-testing/stack\n  TestUsers, testTenantId, testUserId, createTestUser from /stack -> @cosmicdrift/kumiko-framework/seeding\n  @cosmicdrift/kumiko-framework/testing -> @cosmicdrift/kumiko-testing/helpers\n  bridgeStub from /testing and /testing/handler-context -> @cosmicdrift/kumiko-framework/engine\n  @cosmicdrift/kumiko-framework/testing/real-providers -> @cosmicdrift/kumiko-testing/helpers/real-providers\n  @cosmicdrift/kumiko-framework/testing/e2e-generator -> @cosmicdrift/kumiko-testing/helpers/e2e-generator",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites imports from the old paths and splits mixed imports by target. Add @cosmicdrift/kumiko-testing to devDependencies where it is missing.",
+    "codemod": "scripts/codemod/testing-move.ts"
+  },
   {
     "version": "0.367.0",
     "type": "fix",

package/src/scripts/codemod/README.md

@@ -57,3 +57,46 @@ Runs automatically via `bun kumiko-upgrade --apply`. Without a mode flag it writ
 formats the changed files with the Biome binary found in `node_modules/.bin` (`--no-format`
 skips that). `--dry-run` only reports; `--check` reports and exits 1 while any rewritable
 or manual site is left.
+
+## db-factory.ts
+
+Moves consumers to the single DB connection factory and the relocated query helpers.
+`@cosmicdrift/kumiko-framework/bun-db` imports (including `import type`, `export … from` and
+`import("…")` types) are repointed to `@cosmicdrift/kumiko-framework/db`, merged into an existing
+`/db` import of the same kind. `createDbConnection(url, options)` becomes
+`createDbConnection({ url, ...options })`; `createConnection`/`createPgConnection` from the
+framework become `createDbConnection` in the object form, and the now-pointless `await` is dropped.
+Idempotent. Local functions named `createConnection` are left alone.
+
+Reported as `manual` instead of guessed at: imports of `createBunDbConnection`,
+`bunDbConnectionOptionsFromEnv`, `BunDbConnection`, `BunDbTx`, `BunDbRunner`,
+`BunDbConnectionOptions` and `DbPoolHandle` (removed without replacement), uses of `DB_PROVIDER`,
+and `createConnection` results that are not awaited directly.
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/db-factory.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs automatically via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then formats the
+changed files with Biome. `--check` exits 1 while any rewritable or manual site is left.
+
+## tenant-db-options.ts
+
+Moves `createTenantDb(db, tenantId, mode, tracer, meter, signal, grants)` to the options object
+`createTenantDb({ db, tenantId, mode, tracer, meter, signal, grants })`. A call is only touched when
+the callee resolves (import, aliased import, namespace import or `await import(…)` destructuring) to
+the framework export; a local function with the same name is left alone. Arguments that are the
+identifier of the same name become shorthand, literal `undefined` arguments after `tenantId` are
+dropped, an explicit `mode` is kept, comments between the arguments are preserved. Idempotent —
+calls already passing one object literal are left alone.
+
+Reported as `manual` instead of guessed at: spread arguments, more than seven arguments, a single
+argument that is not an object literal, and `createTenantDb` used as a value (callback, assignment,
+`.bind`/`.call`/`.apply`).
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/tenant-db-options.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs automatically via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then formats the
+changed files with Biome. `--check` exits 1 while any rewritable or manual site is left.

package/src/scripts/codemod/codemod-support.ts

@@ -0,0 +1,276 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { type ImportDeclaration, type ImportSpecifier, Node, type SourceFile } from "ts-morph";
+import { collectSourceFiles } from "./collect-source-files.js";
+
+export interface CodemodSite {
+  readonly file: string;
+  readonly line: number;
+  readonly description: string;
+}
+
+export interface CodemodResult {
+  readonly output: string;
+  readonly rewrites: CodemodSite[];
+  readonly manual: CodemodSite[];
+}
+
+export type SiteLists = { rewrites: CodemodSite[]; manual: CodemodSite[] };
+
+export const SCRIPT_EXTENSION = /\.(js|ts|tsx)$/;
+
+// A relative specifier below `<root><marker>...` is a module of that package's own source tree.
+export function sourceRelativeModule(
+  specifier: string,
+  filePath: string,
+  sourceMarker: string,
+): { readonly root: string; readonly module: string; readonly extension: string } | undefined {
+  if (!specifier.startsWith(".")) return undefined;
+  const resolved = resolve(dirname(filePath), specifier);
+  const extension = SCRIPT_EXTENSION.exec(resolved)?.[0] ?? "";
+  const stripped = resolved.slice(0, resolved.length - extension.length);
+  const markerIndex = stripped.lastIndexOf(sourceMarker);
+  if (markerIndex === -1) return undefined;
+  return {
+    root: stripped.slice(0, markerIndex + sourceMarker.length),
+    module: stripped.slice(markerIndex + sourceMarker.length),
+    extension,
+  };
+}
+
+export function relativeSpecifier(
+  fromFile: string,
+  root: string,
+  module: string,
+  extension: string,
+): string {
+  const path = relative(dirname(fromFile), join(root, module)).split("\\").join("/");
+  return `${path.startsWith(".") ? path : `./${path}`}${extension}`;
+}
+
+export function isPlainNamedImport(declaration: Node): boolean {
+  return (
+    Node.isImportDeclaration(declaration) &&
+    declaration.getNamespaceImport() === undefined &&
+    declaration.getDefaultImport() === undefined
+  );
+}
+
+export function hasImportBinding(sourceFile: SourceFile, localName: string): boolean {
+  return sourceFile
+    .getImportDeclarations()
+    .some(
+      (declaration) =>
+        declaration.getDefaultImport()?.getText() === localName ||
+        declaration.getNamespaceImport()?.getText() === localName ||
+        declaration
+          .getNamedImports()
+          .some((named) => (named.getAliasNode()?.getText() ?? named.getName()) === localName),
+    );
+}
+
+// remove() would drop leading comments with the declaration (e.g. a file-level lint marker that
+// has to stay attached to the next statement), so only the declaration's own line goes.
+function removeDeclarationLine(
+  sourceFile: SourceFile,
+  declaration: { getStart(): number; getEnd(): number },
+): void {
+  const text = sourceFile.getFullText();
+  const end = declaration.getEnd();
+  const lineEnd = text[end] === "\n" ? end + 1 : end;
+  sourceFile.replaceWithText(text.slice(0, declaration.getStart()) + text.slice(lineEnd));
+}
+
+export function removeNamedImport(
+  sourceFile: SourceFile,
+  declaration: ImportDeclaration,
+  named: ImportSpecifier,
+): void {
+  if (declaration.getNamedImports().length > 1) {
+    named.remove();
+  } else {
+    removeDeclarationLine(sourceFile, declaration);
+  }
+}
+
+export function ensureNamedImport(
+  sourceFile: SourceFile,
+  specifier: string,
+  name: string,
+  isTypeOnly: boolean,
+): void {
+  const declarations = sourceFile.getImportDeclarations();
+  const target = declarations.find(
+    (declaration) =>
+      declaration.getModuleSpecifierValue() === specifier &&
+      declaration.isTypeOnly() === isTypeOnly &&
+      isPlainNamedImport(declaration) &&
+      declaration.getNamedImports().length > 0,
+  );
+  if (target === undefined) {
+    sourceFile.insertImportDeclaration(declarations.length, {
+      moduleSpecifier: specifier,
+      namedImports: [name],
+      isTypeOnly,
+    });
+  } else if (
+    !target.getNamedImports().some((named) => named.getName() === name && !named.getAliasNode())
+  ) {
+    target.addNamedImport(name);
+  }
+}
+
+function findBiomeBinary(startDir: string): string | undefined {
+  let dir = resolve(startDir);
+  for (;;) {
+    const candidate = join(dir, "node_modules", ".bin", "biome");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+const FORMAT_BATCH_SIZE = 50;
+
+async function formatWithBiome(
+  codemodName: string,
+  files: readonly string[],
+  cwd: string,
+): Promise<void> {
+  const biome = findBiomeBinary(cwd);
+  if (biome === undefined) {
+    console.log(
+      `[${codemodName}] biome not found in node_modules/.bin — format and sort imports of the changed files yourself`,
+    );
+    // skip: formatting is a convenience, the rewrite itself is already on disk
+    return;
+  }
+  for (let i = 0; i < files.length; i += FORMAT_BATCH_SIZE) {
+    const batch = files.slice(i, i + FORMAT_BATCH_SIZE);
+    const proc = Bun.spawn({
+      cmd: [
+        biome,
+        "check",
+        "--write",
+        "--linter-enabled=false",
+        "--no-errors-on-unmatched",
+        ...batch,
+      ],
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stderr, exitCode] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+    if (exitCode !== 0) {
+      console.log(
+        `[${codemodName}] biome exited ${exitCode}; run it on the changed files yourself\n${stderr.trim()}`,
+      );
+    }
+  }
+}
+
+type Mode = "write" | "dry-run" | "check";
+
+interface CliOptions {
+  readonly mode: Mode;
+  readonly format: boolean;
+  readonly paths: string[];
+}
+
+class CliError extends Error {}
+
+function parseArgs(argv: readonly string[]): CliOptions {
+  let mode: Mode | undefined;
+  let format = true;
+  const paths: string[] = [];
+  const setMode = (next: Mode): void => {
+    if (mode !== undefined && mode !== next) {
+      throw new CliError("--check, --dry-run and --write are mutually exclusive");
+    }
+    mode = next;
+  };
+  for (const arg of argv) {
+    if (arg === "--check") setMode("check");
+    else if (arg === "--dry-run") setMode("dry-run");
+    else if (arg === "--write") setMode("write");
+    else if (arg === "--no-format") format = false;
+    else if (arg.startsWith("--")) throw new CliError(`unknown flag: ${arg}`);
+    else paths.push(arg);
+  }
+  if (paths.length === 0) throw new CliError("at least one target directory is required");
+  return { mode: mode ?? "write", format, paths };
+}
+
+function isMigratableFile(name: string): boolean {
+  return /\.(ts|tsx)$/.test(name) && !name.endsWith(".d.ts");
+}
+
+function displayPath(file: string): string {
+  const fromCwd = relative(process.cwd(), file);
+  return fromCwd.startsWith("..") ? file : fromCwd;
+}
+
+export interface CodemodCliConfig {
+  readonly name: string;
+  readonly transform: (source: string, filePath: string) => CodemodResult;
+  readonly isSkippedPath: (file: string) => boolean;
+}
+
+function parseArgsOrExit(codemodName: string, argv: readonly string[]): CliOptions {
+  try {
+    return parseArgs(argv);
+  } catch (err) {
+    if (err instanceof CliError) {
+      console.error(`[${codemodName}] ${err.message}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+}
+
+function transformFiles(
+  config: CodemodCliConfig,
+  files: readonly string[],
+  mode: Mode,
+): { rewrites: CodemodSite[]; manual: CodemodSite[]; changedFiles: string[] } {
+  const rewrites: CodemodSite[] = [];
+  const manual: CodemodSite[] = [];
+  const changedFiles: string[] = [];
+  for (const file of files) {
+    const before = readFileSync(file, "utf8");
+    const result = config.transform(before, file);
+    const shown = displayPath(file);
+    for (const site of result.rewrites)
+      console.log(`${shown}:${site.line}  rewritten  ${site.description}`);
+    for (const site of result.manual)
+      console.log(`${shown}:${site.line}  manual  ${site.description}`);
+    rewrites.push(...result.rewrites);
+    manual.push(...result.manual);
+    if (mode === "write" && result.output !== before) {
+      writeFileSync(file, result.output);
+      changedFiles.push(file);
+    }
+  }
+  return { rewrites, manual, changedFiles };
+}
+
+// Without a mode flag it writes (kumiko-upgrade --apply calls it that way). --check exits 1
+// while any rewritable or manual site is left; --dry-run only reports.
+export async function runCodemodCli(
+  config: CodemodCliConfig,
+  argv: readonly string[],
+): Promise<void> {
+  const options = parseArgsOrExit(config.name, argv);
+  const files = collectSourceFiles(options.paths, { isMigratableFile }).filter(
+    (file) => !(file.includes("/__tests__/fixtures/") || config.isSkippedPath(file)),
+  );
+  const { rewrites, manual, changedFiles } = transformFiles(config, files, options.mode);
+  console.log(
+    `\n[${config.name}] ${options.mode === "write" ? "rewritten" : "rewritable"}: ${rewrites.length} site(s) in ${new Set(rewrites.map((site) => site.file)).size} file(s); manual: ${manual.length}`,
+  );
+  if (options.mode === "write" && options.format && changedFiles.length > 0) {
+    await formatWithBiome(config.name, changedFiles, resolve(options.paths[0] ?? "."));
+  }
+  process.exit(options.mode === "check" && rewrites.length + manual.length > 0 ? 1 : 0);
+}