@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/engine/provider-plugin-context.js

@@ -1,28 +0,0 @@
-export function providerPluginContextFromHandler(ctx) {
-    return {
-        db: ctx.db,
-        dbOutsideTransaction: ctx.dbOutsideTransaction,
-        systemDb: ctx.systemDb,
-        registry: ctx.registry,
-        user: ctx.user,
-        log: ctx.log,
-        triggeredBy: ctx.triggeredBy,
-        config: ctx.config,
-        secrets: ctx.secrets,
-    };
-}
-// Jobs have no request user: the job's system user is the acting identity, and no
-// outside-transaction handle exists because jobs never run inside the handler's tx.
-export function providerPluginContextFromJob(ctx) {
-    return {
-        db: ctx.db,
-        dbOutsideTransaction: undefined,
-        systemDb: ctx.systemDb,
-        registry: ctx.registry,
-        user: ctx.systemUser,
-        log: ctx.log,
-        triggeredBy: ctx.triggeredBy,
-        config: ctx.config,
-        secrets: ctx.secrets,
-    };
-}

package/dist/engine/resolve-config-or-param.d.ts

@@ -1,18 +0,0 @@
-import type { ConfigAccessor, ConfigKeyHandle, ConfigKeyType, ConfigValue } from "./types/config.ts";
-import type { Registry } from "./types/index.ts";
-type ResolveCtx = {
-    readonly config: ConfigAccessor;
-    readonly registry: Registry;
-};
-export type ClampInfo = {
-    readonly key: string;
-    readonly original: number;
-    readonly clamped: number;
-    readonly min?: number;
-    readonly max?: number;
-};
-export type ResolveOptions = {
-    readonly onClamp?: (info: ClampInfo) => void;
-};
-export declare function resolveConfigOrParam<T extends ConfigKeyType>(ctx: ResolveCtx, handle: ConfigKeyHandle<T>, paramValue: unknown, options?: ResolveOptions): Promise<ConfigValue<T> | undefined>;
-export {};

package/dist/engine/resolve-config-or-param.js

@@ -1,76 +0,0 @@
-export async function resolveConfigOrParam(ctx, handle, paramValue, options) {
-    if (paramValue === undefined || paramValue === null || paramValue === "") {
-        return ctx.config(handle);
-    }
-    const keyDef = ctx.registry.getConfigKey(handle.name);
-    // skip: key isn't in the registry — unlikely because the caller holds a
-    // typed handle, but defence-in-depth for hand-built handles.
-    if (!keyDef)
-        return ctx.config(handle);
-    // Explicit opt-in required. A config key without `allowPerRequest: true`
-    // on its declaration cannot be overridden via a query-param, even if the
-    // route-handler forwards one. This is a deny-by-default policy: without
-    // it, a future feature-dev could accidentally route a sensitive key
-    // (rate-limits, quotas) through a public query-param without noticing.
-    if (!keyDef.allowPerRequest) {
-        throw new Error(`resolveConfigOrParam: per-request override not enabled for config key "${handle.name}". Set allowPerRequest: true on the declaration to opt in — or drop the paramValue if the route-handler forwards it by mistake.`);
-    }
-    switch (keyDef.type) {
-        case "number": {
-            const parsed = typeof paramValue === "number" ? paramValue : Number(paramValue);
-            if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
-                return ctx.config(handle);
-            }
-            const clamped = clampToBounds(parsed, keyDef.bounds);
-            // Fire onClamp only when the value actually moved. No bounds + within
-            // bounds = silent; crossing a bound = audit event.
-            if (clamped !== parsed && options?.onClamp) {
-                const info = {
-                    key: handle.name,
-                    original: parsed,
-                    clamped,
-                    ...(keyDef.bounds?.min !== undefined && { min: keyDef.bounds.min }),
-                    ...(keyDef.bounds?.max !== undefined && { max: keyDef.bounds.max }),
-                };
-                options.onClamp(info);
-            }
-            return clamped; // @cast-boundary engine-bridge
-        }
-        case "boolean": {
-            if (typeof paramValue === "boolean")
-                return paramValue; // @cast-boundary engine-bridge
-            const str = String(paramValue).toLowerCase();
-            return (str === "true" || str === "1"); // @cast-boundary engine-bridge
-        }
-        case "text": {
-            // Hard-reject any attempt to override a text key via query-param.
-            // See the module-level comment for why this is strict. App-devs
-            // that see this error should either (a) remove the paramValue from
-            // their route — the config value still flows through ctx.config —
-            // or (b) build their own sanitised parser outside this helper.
-            throw new Error(`resolveConfigOrParam: per-request override is not allowed for type="text" config key "${handle.name}" — query-params would bypass sanitisation. Remove the paramValue or build a feature-specific sanitiser.`);
-        }
-        case "select": {
-            const str = String(paramValue);
-            if (keyDef.options?.includes(str))
-                return str; // @cast-boundary engine-bridge
-            // Invalid option → fall back to the configured value rather than 400.
-            // The caller is signalling intent; we honour the constraint instead.
-            return ctx.config(handle);
-        }
-        default: {
-            const _exhaustive = keyDef.type;
-            throw new Error(`resolveConfigOrParam: unhandled config key type "${_exhaustive}"`);
-        }
-    }
-}
-function clampToBounds(value, bounds) {
-    if (!bounds)
-        return value;
-    let v = value;
-    if (bounds.min !== undefined && v < bounds.min)
-        v = bounds.min;
-    if (bounds.max !== undefined && v > bounds.max)
-        v = bounds.max;
-    return v;
-}

package/src/scripts/codemod/README.md

@@ -1,187 +0,0 @@
-# consumer-facing codemods
-
-This directory holds the codemod scripts `kumiko upgrade --apply` runs for
-consumers of `@cosmicdrift/kumiko-framework`. It ships as part of the
-published package (under `src/`), unlike `scripts/codemod/` at the repo
-root, which is internal bun-cutover tooling for this repo's own migration
-and never gets published.
-
-`crypto-shredding-testing-move.ts` rewrites the moved
-`resetPiiSubjectKmsForTests` import path; it's wired into
-`packages/bundled-features/src/crypto-shredding/changes.json`'s `codemod`
-field and runs automatically via `kumiko upgrade --apply`.
-
-## pii-personal-migration.ts
-
-Migrates `create*Field(...)` calls from the old flag-based PII API (`pii`,
-`userOwned`, `tenantOwned`, `subjectRef`, `allowPlaintext`, `lookupable`,
-`searchable`, `sensitive`) to the author-facing `personal`/`find` API
-(kumiko-framework#2250). Idempotent — safe to re-run against already
-migrated code (no-ops on fields carrying `personal`).
-
-`createTenantConfig`/`createUserConfig`/etc. are out of scope by
-construction (name doesn't match `create*Field`).
-
-```bash
-bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/pii-personal-migration.ts <targetDir> [--dry-run]
-```
-
-Anything it can't map mechanically (two subject flags on one field,
-`sensitive` + `lookupable`/`searchable` together, `piiEncrypted` on an
-entity field, a raw object literal with subject flags outside a
-`create*Field(...)` call) is reported with file:line instead of guessed
-at — fix those by hand. The report also lists every field that newly
-gains `lookupable` (searchable-only fields resolving to `find: "fuzzy"`)
-— each of those needs a `_bidx` column migration, which this script does
-not write.
-
-## object-form.ts
-
-Rewrites the positional registrar calls `r.writeHandler(name, schema, handler, options)`,
-`r.queryHandler(…)`, `r.entity(name, definition, { table })`, `r.requires("a", "b")` and
-`r.hook(type, target, fn, options?)` to their object form, and
-`registerEntityCrud(r, name, entity, options?)` to `r.crud(name, entity, options?)`
-(the now-unused import is removed). Idempotent — object-form calls are left alone.
-
-A call is only touched when its receiver is provably a feature registrar: a parameter of
-the `defineFeature(name, (r) => …)` callback, or a binding typed `FeatureRegistrar`.
-Anything else (`sessions.requires("x")`, `foo.entity(…)`) stays untouched. A call on an
-untyped `r`/`registrar` it cannot resolve, a spread argument, too few arguments or
-`entity` options other than `{ table }` are reported as `manual` instead of guessed at.
-
-```bash
-bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/object-form.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 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.
-
-## import-extensions
-
-Relative imports name the TypeScript source file: `./foo.js` becomes `./foo.ts`, `./Comp.jsx`
-becomes `./Comp.tsx`. Covers `import`, `export ... from`, `import type`, `import()` and
-`mock.module`. A specifier is rewritten only when the target exists with the new extension next to
-the importer; otherwise it is reported as `manual` and left alone.
-
-The tsconfig that compiles the code needs `allowImportingTsExtensions` and
-`rewriteRelativeImportExtensions` (TypeScript 5.7 or newer) first.
-
-```bash
-bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/import-extensions.ts <dir> [--check | --dry-run | --write] [--no-format]
-```
-
-Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes. `--check` exits 1 while any
-rewritable or manual site is left. The `import-extensions` guard (`kumiko check guards`) reports
-sites that are still on `.js`.
-
-## remove-engine-payload-casts.ts
-
-`executor.detail()` and `executor.list()` from `createEntityExecutor` / `createEventStoreExecutor`
-return the entity's own row type (`EntityRow<E>`), so `row["f"] as T`, `row as T` and
-`(await executor.detail(…)) as unknown as T` are usually redundant. The codemod removes such a cast,
-and its `@cast-boundary` marker comment when no other cast stays in the statement, only when the
-operand derives from an executor read (directly, through `rows[0]`, property access, `??` or a
-single-assignment variable) and the type checker says its type is assignable to the cast target. A
-file is left untouched if removing the casts would add type errors to it.
-
-It type-checks against the tsconfig at or above each file, so run it with the new framework version
-installed. Reported as `manual` and left alone: casts the row type does not satisfy (for example a
-nullable column cast to a non-null type, or `rows[0]` under `noUncheckedIndexedAccess`), and files
-without a tsconfig. A call site that still needs a narrower type than the row gives keeps its cast.
-
-```bash
-bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/remove-engine-payload-casts.ts <dir> [--check | --dry-run | --write] [--no-format]
-```
-
-Runs 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-merge.ts
-
-Packages folded into another package stay as re-export shims for one wave. The codemod rewrites
-imports, re-exports, `import("…")` and `mock.module` specifiers (including subpaths) of the old
-package to the new one, and in `package.json` replaces the old dependency with the target package
-(same version range, same block, skipped when the block already lists it). The moves are the rows
-of `PACKAGE_MERGE_MAPPINGS`: `@cosmicdrift/kumiko-http` to `@cosmicdrift/kumiko-framework/http`,
-`@cosmicdrift/kumiko-repo-manifest` to `@cosmicdrift/kumiko-guards/repo-manifest`,
-`@cosmicdrift/kumiko-headless` to `@cosmicdrift/kumiko-renderer/headless` (subpaths keep their name),
-`@cosmicdrift/kumiko-dispatcher-live` to `@cosmicdrift/kumiko-renderer/live`,
-`@cosmicdrift/kumiko-renderer-web` to `@cosmicdrift/kumiko-renderer/web` (so
-`@import "@cosmicdrift/kumiko-renderer-web/styles.css"` becomes
-`@import "@cosmicdrift/kumiko-renderer/web/styles.css"`).
-
-`.css` files are covered too: the specifier of `@import`, `@plugin` and `@config` is rewritten like
-an import. A `@source` path into `node_modules/<old package>/…` has no mechanical target and is
-reported as manual.
-
-```bash
-bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/package-merge.ts <dir> [--check | --dry-run | --write] [--no-format]
-```
-
-Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes. `--check` exits 1 while any
-site is left. Run your package manager's install afterwards to refresh the lockfile.
-
-## feature-layout.ts
-
-Applies the feature layout rule "the runtime of a file follows from its path": everything
-under `src/features/<feature>/web/` is client code, the rest of the feature is server or
-isomorphic. Every file that carries a runtime-client marker outside `web/` moves to
-`<feature>/web/` (sub-structure kept), the relative imports, re-exports, `import()` calls and
-`mock.module` strings that point at it or out of it are rewritten, `package.json` export
-targets follow, and the marker is dropped. A marker the path already implies (client in
-`web/`, test in `__tests__/`) is only removed. Idempotent.
-
-```bash
-bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/feature-layout.ts <dir> [--check | --dry-run | --write] [--no-format]
-```
-
-Features are found as `src/features/<feature>/` and `bundled-features/src/<feature>/` below
-`<dir>`; `--feature-dir <dir>` names a directory that is itself one feature and
-`--features-root <dir>` one whose children are features. A target that already exists in
-`web/` and a marker no path rule covers (for example `dev` outside `dev/`) are reported as
-`manual` and left alone. `--check` exits 1 while anything is left.

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

@@ -1,334 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-import {
-  type ImportDeclaration,
-  type ImportSpecifier,
-  Node,
-  type SourceFile,
-  SyntaxKind,
-} from "ts-morph";
-import { collectSourceFiles } from "./collect-source-files.ts";
-
-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}`;
-}
-
-function stringLiteralOf(node: Node | undefined): Node | undefined {
-  return node !== undefined && Node.isStringLiteral(node) ? node : undefined;
-}
-
-export interface TextEdit {
-  readonly start: number;
-  readonly end: number;
-  readonly text: string;
-}
-
-export function applyEdits(source: string, edits: readonly TextEdit[]): string {
-  let output = source;
-  for (const edit of [...edits].sort((x, y) => y.start - x.start)) {
-    output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
-  }
-  return output;
-}
-
-export function moduleSpecifierLiterals(sourceFile: SourceFile): Node[] {
-  const literals: Node[] = [];
-  for (const declaration of [
-    ...sourceFile.getImportDeclarations(),
-    ...sourceFile.getExportDeclarations(),
-  ]) {
-    const literal = declaration.getModuleSpecifier();
-    if (literal !== undefined) literals.push(literal);
-  }
-  for (const importType of sourceFile.getDescendantsOfKind(SyntaxKind.ImportType)) {
-    const argument = importType.getArgument();
-    if (Node.isLiteralTypeNode(argument)) literals.push(argument.getLiteral());
-  }
-  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const callee = call.getExpression();
-    const isModuleLoad =
-      callee.getKind() === SyntaxKind.ImportKeyword || callee.getText() === "mock.module";
-    const literal = stringLiteralOf(call.getArguments()[0]);
-    if (isModuleLoad && literal !== undefined) literals.push(literal);
-  }
-  return literals;
-}
-
-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;
-
-export 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 isSourceFileName(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;
-  // Exact file names (e.g. package.json) handed to transform next to the .ts/.tsx sources.
-  readonly extraFileNames?: readonly string[];
-  // File extensions (e.g. ".css") handed to transform next to the .ts/.tsx sources.
-  readonly extraExtensions?: readonly string[];
-}
-
-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: (name) =>
-      isSourceFileName(name) ||
-      (config.extraFileNames?.includes(name) ?? false) ||
-      (config.extraExtensions?.some((extension) => name.endsWith(extension)) ?? false),
-  }).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.filter((file) => isSourceFileName(file)),
-      resolve(options.paths[0] ?? "."),
-    );
-  }
-  process.exit(options.mode === "check" && rewrites.length + manual.length > 0 ? 1 : 0);
-}