@cosmicdrift/kumiko-framework 0.378.0 → 0.380.0

package/src/changes.json

@@ -1,4 +1,121 @@
 [
+  {
+    "version": "0.380.0",
+    "type": "breaking",
+    "title": "Writes compile only for Writable tables or capable runners",
+    "detail": "The negative ExecutorOnly brand is replaced by positive brands. table(), defineUnmanagedTable and deriveEntityTableMeta with source \"unmanaged\" return Writable tables; buildEntityTable and r.projection tables do not. insertOne, updateMany, deleteMany, the upsert and counter helpers and the TenantDb and db.global() write methods accept a Writable table, or any table when the runner is an ExecutorManagedRunner or ExecutorManagedTenantDb. Widening a table to SchemaTable or EntityTableMeta drops the brand, so erased tables no longer compile. Projection apply functions receive tx as ExecutorManagedRunner. The runtime lock is unchanged.",
+    "migration": "Apply functions that annotate `tx` as `DbRunner`, inline or standalone, type it as `ExecutorManagedRunner` (or drop the annotation / annotate the function with SingleStreamApplyFn/MultiStreamApplyFn). Own write helpers take `WritableTable` for direct-write tables, or `ExecutorManagedRunner` / `ExecutorManagedTenantDb` when they write event-fed tables from an apply, rebuild or tenant-destroy context, instead of `SchemaTable`/`EntityTableMeta`. Tables annotated as `SchemaTable` lose the `Writable` brand; drop the annotation or add `& Writable`. Tenant-destroy hooks keep using the db they receive. Affects kumiko-enterprise, solon, money-horse, kumiko-studio, publicstatus."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "PII backfill encrypts jsonb object and array fields",
+    "detail": "runPiiEventBackfill and backfillEventPiiEncryption now retro-encrypt plaintext jsonb objects and arrays of personal fields and personal jsonb scalars, and createPiiBackfillStateTable bootstraps under an advisory lock so concurrent first boots no longer skip the ALTER. Completed backfill states rerun once because the transform version changed."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "applyEntityEvent is exported from the db barrel, extension sources accept auto-verbs",
+    "detail": "applyEntityEvent can be used by extendEntityProjection apply handlers to project stored entity events of a foreign aggregate type. validateProjectionApplyKeys accepts the entity auto-verbs for an extension source that is not a registered entity."
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "SSE entity signals follow the read access of the connection",
+    "detail": "A signed-in connection receives an entity signal only when a query reading that entity lets one of its roles in (SseRouteOptions.entityReadAccess, built by collectEntityReadAccess). Entities without a reading query no longer go on the channel. When the reading access depends on a row or owner filter, the signal goes out without id and version, so a client refetches its query instead of learning which row changed.",
+    "migration": "Apps that rely on a signal for an entity no query exposes to the user must add a query for that entity with a matching access rule. Custom buildServer callers that build SseRouteOptions themselves must pass entityReadAccess."
+  },
+  {
+    "version": "0.379.0",
+    "type": "fix",
+    "title": "Cause details only with NODE_ENV development or test",
+    "detail": "internal_error responses and write error infos carry the cause snapshot (name, message, stack) only when NODE_ENV is explicitly development or test. A missing or misspelled NODE_ENV no longer exposes stack traces, paths or upstream URLs. kumiko-dev starts the server with NODE_ENV=development when none is set, so local dev keeps the details; a dev script that runs the server directly (bun --watch bin/server.ts) must set NODE_ENV=development itself to see them."
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "Global IP rate-limit middleware default matches runProdApp",
+    "detail": "globalIpRateLimit defaults to 600 requests per 60 seconds (was 1000). DEFAULT_GLOBAL_RATE_LIMIT is exported from the api barrel and shared with server-runtime. authEndpointRateLimit keeps its default of 5 per 60 seconds.",
+    "migration": "Apps that use globalIpRateLimit directly and relied on 1000 pass limit explicitly. runProdApp users see no change."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Boot warning when /metrics is off in production",
+    "detail": "buildServer logs a warning in production when no metrics option is set, which happens when PROMETHEUS_METRICS_TOKEN is unset."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Package ships its event-store table catalog",
+    "detail": "kumiko-es-tables.json is included in the published files; no runtime change."
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "Direct writes on event-fed tables throw at runtime",
+    "detail": "buildEntityTable and r.projection mark their tables. insertOne, updateMany, deleteMany, the upsert and counter helpers, ctx.db write methods and db.global() writes throw AccessDeniedError on a marked table unless the runner carries the framework write capability. The executor, projection apply, rebuild, unsafeProjectionDelete, tenant-destroy hooks and deleteRowsWithoutReplayableStream hold it; ctx.db.unsafeRaw() never does. Retention deletes only rows whose stream is gone or archived. The cascade delete hook, the soft-delete purge jobs and seedReferenceData now write through the executor, so their effect survives a rebuild; cascade children are written as the system user, and softDelete children are soft-deleted instead of hard-deleted. The direct-entity-writes guard has no exceptions left.",
+    "migration": "Write event-fed rows through the executor (r.crud, ctx.write, createEventStoreExecutor). Projection apply functions must use the db they receive. Test seeds and teardown use seedRow, seedRows, updateRows, deleteRows and clearTables from kumiko-testing instead of hand-written wipe helpers. Do not pass ctx.db.unsafeRaw() to code that deletes event-fed rows; pass ctx.db inside a tenant-destroy hook. Retention code calls deleteRowsWithoutReplayableStream after pruning or archiving the events. seedReferenceData takes the registry instead of a table map. Affects kumiko-enterprise, kumiko-studio and solon."
+  },
+  {
+    "version": "0.379.0",
+    "type": "fix",
+    "title": "Tests pin the money units of form derivations",
+    "detail": "form-derivations tests now cover realistic money values (1234,56 EUR plus 234,57 EUR, 0,10 plus 0,20) and minor-unit list cells; no behaviour change.",
+    "migration": "None."
+  },
+  {
+    "version": "0.379.0",
+    "type": "fix",
+    "title": "A slow SSE client no longer buffers without bound",
+    "detail": "The SSE route tracks the writes a client has not consumed. A client whose queued frames make no progress for SSE_STALLED_CLIENT_TIMEOUT_MS (one heartbeat interval), or that queues SSE_MAX_PENDING_WRITES_PER_CLIENT frames, is aborted and unregistered; it reconnects and resyncs. A large broadcast batch does not drop a client that keeps reading, and one failing client no longer stops the broadcast to the others. SseRouteOptions.now makes the clock injectable."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Deprecations name their removal release",
+    "detail": "The three @deprecated APIs without a target release (the minor-units money accessor and the landingPath props of the invite and signup screens) now say they are removed in 0.390.0."
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "buildEntityTableMeta and observabilityOptions removed",
+    "detail": "buildEntityTableMeta was a deprecated alias of deriveEntityTableMeta. The deprecated observabilityOptions option of the entrypoint and the prod and worker runners is gone as well, it had no effect since the HTTP route label no longer carries a query string.",
+    "migration": "Rename buildEntityTableMeta to deriveEntityTableMeta (same signature). Delete observabilityOptions from the entrypoint and runner options, nothing replaces it."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "readDatabaseNow(db) in framework/db",
+    "detail": "Typed read of the Postgres clock for a TenantDb without unsafeRaw. Inside a transaction now() is the transaction start, so repeated reads agree."
+  },
+  {
+    "version": "0.379.0",
+    "type": "fix",
+    "title": "SaveContext.event no longer reaches JSON responses",
+    "detail": "The event echoed on the SaveContext of create, update and restore is non-enumerable, so a handler returning the save result no longer leaks event data (PII) in its response; hooks and projections still read it by property."
+  },
+  {
+    "version": "0.379.0",
+    "type": "fix",
+    "title": "Dashboard navigate params may bind a record",
+    "detail": "The boot validator accepts navigate params on a dashboard row action that has a record binding (record.param) but no filter; it still rejects params when the dashboard reads no filter, time range or record binding."
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "Re-export shim packages removed",
+    "detail": "The shims headless, dispatcher-live, renderer-web, http and repo-manifest are gone. Their code lives in kumiko-renderer (/headless, /live, /web), kumiko-framework (/http) and kumiko-guards (/repo-manifest).",
+    "migration": "Run bun kumiko-upgrade --apply, or bun kumiko codemod package-merge . --write. It rewrites the imports and package.json dependencies of all five shims to their target packages.",
+    "codemod": "scripts/codemod/package-merge.ts"
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "TenantDb.databaseNow",
+    "detail": "TenantDb has a databaseNow() method returning Postgres now(); custom TenantDb implementations must add it.",
+    "migration": "Add databaseNow(): Promise<Date> to hand-built TenantDb objects and mocks, returning the Postgres now()."
+  },
   {
     "version": "0.378.0",
     "type": "improvement",

package/src/scripts/codemod/README.md

@@ -165,3 +165,23 @@ bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/package-merge
 
 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

@@ -180,7 +180,7 @@ function findBiomeBinary(startDir: string): string | undefined {
 
 const FORMAT_BATCH_SIZE = 50;
 
-async function formatWithBiome(
+export async function formatWithBiome(
   codemodName: string,
   files: readonly string[],
   cwd: string,

package/src/scripts/codemod/feature-layout.ts

@@ -0,0 +1,416 @@
+#!/usr/bin/env bun
+// feature-layout — the runtime of a feature file follows from its path: <feature>/web/** is client
+// code, everything else is server or isomorphic. This moves every file marked as runtime client of a
+// feature that lies outside web/ into <feature>/web/ (sub-structure kept), rewrites each relative
+// import / re-export / import() / mock.module that points at it or out of it, rewrites package.json
+// export targets, and drops the marker. A marker the path already implies (client in web/, test in
+// __tests__/, dev in dev/, tooling in scripts/) is only removed. A target that already exists, or a
+// marker no path rule covers, is reported as manual and left alone.
+//
+// Features are found as src/features/<feature>/ and bundled-features/src/<feature>/ below the target
+// directories; --feature-dir <dir> names a directory that is itself one feature, --features-root <dir>
+// a directory whose children are features.
+//
+// Usage:
+//   bun scripts/codemod/feature-layout.ts <targetDir...> [--feature-dir <dir>] [--features-root <dir>]
+//     [--check | --dry-run | --write] [--no-format]
+// Without a mode flag it writes (kumiko-upgrade --apply calls it that way). --check exits 1 while
+// any move, marker or manual site is left; --dry-run only reports.
+
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { Node, Project } from "ts-morph";
+import {
+  applyEdits,
+  type CodemodSite,
+  formatWithBiome,
+  moduleSpecifierLiterals,
+  SCRIPT_EXTENSION,
+  type TextEdit,
+} from "./codemod-support.ts";
+import { collectSourceFiles } from "./collect-source-files.ts";
+
+const MARKER_HEAD_LINES = 8;
+const MARKER_LINE = /^\s*\/\/\s*@runtime(?:\s+(\w+))?\s*$/;
+const WEB_DIR = "web";
+const IMPLICIT_FEATURE_PATTERNS: readonly RegExp[] = [
+  /^(.*\/src\/features\/[^/]+)\/(.+)$/,
+  /^(.*\/bundled-features\/src\/[^/]+)\/(.+)$/,
+];
+const TEST_PATH = /(?:^|\/)__tests__\/|\.(?:test|integration|e2e|spec)\.[tj]sx?$/;
+
+export interface FeatureLayoutOptions {
+  readonly featureDirs?: readonly string[];
+  readonly featuresRoots?: readonly string[];
+}
+
+export interface FeatureLayoutMove {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface FeatureLayoutResult {
+  // New content per final path (moved files under their new path).
+  readonly writes: ReadonlyMap<string, string>;
+  // Old paths that no longer exist after the moves.
+  readonly removals: readonly string[];
+  readonly moves: readonly FeatureLayoutMove[];
+  readonly markersRemoved: readonly string[];
+  readonly importRewrites: readonly CodemodSite[];
+  readonly manual: readonly CodemodSite[];
+}
+
+interface Marker {
+  readonly line: number;
+  readonly kind: string | undefined;
+}
+
+function findMarker(source: string): Marker | undefined {
+  const lines = source.split("\n", MARKER_HEAD_LINES);
+  for (const [index, text] of lines.entries()) {
+    const match = MARKER_LINE.exec(text);
+    if (match) return { line: index, kind: match[1] };
+  }
+  return undefined;
+}
+
+function removeMarkerLine(source: string, line: number): string {
+  const lines = source.split("\n");
+  lines.splice(line, 1);
+  if (line === 0 && lines[0] === "") lines.shift();
+  return lines.join("\n");
+}
+
+function splitFeaturePath(
+  file: string,
+  options: FeatureLayoutOptions,
+): { readonly featureDir: string; readonly rel: string } | undefined {
+  for (const dir of options.featureDirs ?? []) {
+    if (file.startsWith(`${dir}/`)) return { featureDir: dir, rel: file.slice(dir.length + 1) };
+  }
+  for (const root of options.featuresRoots ?? []) {
+    if (!file.startsWith(`${root}/`)) continue;
+    const [feature, ...rest] = file.slice(root.length + 1).split("/");
+    if (feature !== undefined && rest.length > 0) {
+      return { featureDir: `${root}/${feature}`, rel: rest.join("/") };
+    }
+  }
+  for (const pattern of IMPLICIT_FEATURE_PATTERNS) {
+    const match = pattern.exec(file);
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      return { featureDir: match[1], rel: match[2] };
+    }
+  }
+  return undefined;
+}
+
+function pathImpliedKind(rel: string): string | undefined {
+  if (TEST_PATH.test(rel)) return "test";
+  if (rel === WEB_DIR || rel.startsWith(`${WEB_DIR}/`) || /^web\.tsx?$/.test(rel)) return "client";
+  if (rel.startsWith("dev/")) return "dev";
+  if (rel.startsWith("scripts/")) return "tooling";
+  return undefined;
+}
+
+function stripScriptExtension(file: string): { readonly base: string; readonly extension: string } {
+  const extension = SCRIPT_EXTENSION.exec(file)?.[0] ?? "";
+  return { base: file.slice(0, file.length - extension.length), extension };
+}
+
+function movedTargetOf(
+  absoluteSpecifier: string,
+  moved: ReadonlyMap<string, string>,
+): string | undefined {
+  const { base, extension } = stripScriptExtension(absoluteSpecifier);
+  const candidates =
+    extension === ".js" || extension === ".ts" || extension === ".tsx" || extension === ""
+      ? [absoluteSpecifier, `${base}.ts`, `${base}.tsx`]
+      : [absoluteSpecifier];
+  for (const candidate of candidates) {
+    if (moved.has(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function relativeSpecifierFrom(fromDir: string, target: string): string {
+  const path = relative(fromDir, target).split("\\").join("/");
+  return path.startsWith(".") ? path : `./${path}`;
+}
+
+function rewrittenSpecifier(
+  specifier: string,
+  oldFile: string,
+  newFile: string,
+  moved: ReadonlyMap<string, string>,
+): string | undefined {
+  if (!specifier.startsWith(".")) return undefined;
+  const absolute = resolve(dirname(oldFile), specifier);
+  const oldTarget = movedTargetOf(absolute, moved);
+  if (oldTarget === undefined && oldFile === newFile) return undefined;
+  const newTarget = oldTarget === undefined ? absolute : moved.get(oldTarget);
+  if (newTarget === undefined) return undefined;
+  let next: string;
+  if (oldTarget === undefined) {
+    next = relativeSpecifierFrom(dirname(newFile), newTarget);
+    if (specifier.endsWith("/")) next = `${next}/`;
+  } else {
+    const { extension } = stripScriptExtension(absolute);
+    const { base } = stripScriptExtension(newTarget);
+    const isDirectoryImport = extension === "" && base.endsWith("/index");
+    const target = isDirectoryImport ? base.slice(0, -"/index".length) : `${base}${extension}`;
+    next = relativeSpecifierFrom(dirname(newFile), target);
+  }
+  return next === specifier ? undefined : next;
+}
+
+function rewriteSpecifiers(
+  source: string,
+  oldFile: string,
+  newFile: string,
+  moved: ReadonlyMap<string, string>,
+  sites: CodemodSite[],
+): string {
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  const sourceFile = project.createSourceFile(oldFile, source);
+  const edits: TextEdit[] = [];
+  for (const literal of moduleSpecifierLiterals(sourceFile)) {
+    if (!Node.isStringLiteral(literal)) continue;
+    const current = literal.getLiteralValue();
+    const next = rewrittenSpecifier(current, oldFile, newFile, moved);
+    if (next === undefined) continue;
+    sites.push({
+      file: oldFile,
+      line: literal.getStartLineNumber(),
+      description: `${current} -> ${next}`,
+    });
+    edits.push({ start: literal.getStart() + 1, end: literal.getEnd() - 1, text: next });
+  }
+  return applyEdits(source, edits);
+}
+
+// package.json export targets: "./src/<rel>.ts" and the publishConfig mirror "./dist/<rel>.js|.d.ts".
+function rewritePackageJson(
+  source: string,
+  packageJsonPath: string,
+  moved: ReadonlyMap<string, string>,
+  sites: CodemodSite[],
+): string {
+  const packageDir = dirname(packageJsonPath);
+  return source.replace(/"(\.\/(?:src|dist)\/[^"]+)"/g, (whole, target: string) => {
+    const isDist = target.startsWith("./dist/");
+    const sourceTarget = isDist
+      ? target.replace("./dist/", "./src/").replace(/(?:\.d\.ts|\.js)$/, "")
+      : target;
+    const { base } = stripScriptExtension(resolve(packageDir, sourceTarget));
+    const candidates = isDist ? [`${base}.ts`, `${base}.tsx`] : [resolve(packageDir, sourceTarget)];
+    const oldFile = candidates.find((candidate) => moved.has(candidate));
+    const newFile = oldFile === undefined ? undefined : moved.get(oldFile);
+    if (newFile === undefined) return whole;
+    const newRel = relative(packageDir, newFile).split("\\").join("/");
+    const next = isDist
+      ? target.replace(/^\.\/dist\/.*?(\.d\.ts|\.js)$/, (_all, ext: string) => {
+          return `./dist/${newRel.slice("src/".length).replace(/\.tsx?$/, "")}${ext}`;
+        })
+      : `./${newRel}`;
+    sites.push({
+      file: packageJsonPath,
+      line: source.slice(0, source.indexOf(whole)).split("\n").length,
+      description: `${target} -> ${next}`,
+    });
+    return `"${next}"`;
+  });
+}
+
+type MarkerAction =
+  | { readonly action: "strip" }
+  | { readonly action: "move"; readonly target: string }
+  | { readonly action: "manual"; readonly description: string };
+
+function actionForMarker(
+  marker: Marker,
+  location: { readonly featureDir: string; readonly rel: string },
+  isTaken: (target: string) => boolean,
+): MarkerAction {
+  if (marker.kind === undefined) {
+    return { action: "manual", description: "bare @runtime marker without a kind" };
+  }
+  const implied = pathImpliedKind(location.rel);
+  if (marker.kind === implied || (marker.kind === "client" && implied !== undefined)) {
+    return { action: "strip" };
+  }
+  if (marker.kind !== "client") {
+    return { action: "manual", description: `@runtime ${marker.kind} has no path rule here` };
+  }
+  const target = join(location.featureDir, WEB_DIR, location.rel);
+  return isTaken(target)
+    ? { action: "manual", description: `cannot move to ${WEB_DIR}/${location.rel}: target exists` }
+    : { action: "move", target };
+}
+
+function buildWrites(
+  files: ReadonlyMap<string, string>,
+  stripped: ReadonlyMap<string, string>,
+  moved: ReadonlyMap<string, string>,
+  importRewrites: CodemodSite[],
+): Map<string, string> {
+  const writes = new Map<string, string>();
+  const basenames = [...moved.keys()].map((file) => stripScriptExtension(baseName(file)).base);
+  for (const [file, original] of files) {
+    const content = stripped.get(file) ?? original;
+    const newFile = moved.get(file) ?? file;
+    if (file.endsWith("package.json")) {
+      const next =
+        moved.size > 0 ? rewritePackageJson(content, file, moved, importRewrites) : content;
+      if (next !== original) writes.set(file, next);
+      continue;
+    }
+    const mentionsMoved = moved.has(file) || basenames.some((name) => content.includes(name));
+    const next = mentionsMoved
+      ? rewriteSpecifiers(content, file, newFile, moved, importRewrites)
+      : content;
+    if (next !== original || newFile !== file) writes.set(newFile, next);
+  }
+  return writes;
+}
+
+export function applyFeatureLayout(
+  files: ReadonlyMap<string, string>,
+  options: FeatureLayoutOptions = {},
+): FeatureLayoutResult {
+  const manual: CodemodSite[] = [];
+  const markersRemoved: string[] = [];
+  const stripped = new Map<string, string>();
+  const moved = new Map<string, string>();
+  const claimedTargets = new Set<string>();
+  const isTaken = (target: string): boolean => files.has(target) || claimedTargets.has(target);
+
+  for (const [file, source] of files) {
+    const location = splitFeaturePath(file, options);
+    const marker = location === undefined ? undefined : findMarker(source);
+    if (location === undefined || marker === undefined) continue;
+    const decision = actionForMarker(marker, location, isTaken);
+    if (decision.action === "manual") {
+      manual.push({ file, line: marker.line + 1, description: decision.description });
+      continue;
+    }
+    if (decision.action === "move") {
+      claimedTargets.add(decision.target);
+      moved.set(file, decision.target);
+    }
+    stripped.set(file, removeMarkerLine(source, marker.line));
+    markersRemoved.push(file);
+  }
+
+  const importRewrites: CodemodSite[] = [];
+  const writes = buildWrites(files, stripped, moved, importRewrites);
+
+  return {
+    writes,
+    removals: [...moved.keys()],
+    moves: [...moved].map(([from, to]) => ({ from, to })),
+    markersRemoved,
+    importRewrites,
+    manual,
+  };
+}
+
+function baseName(file: string): string {
+  return file.slice(file.lastIndexOf("/") + 1);
+}
+
+type Mode = "write" | "dry-run" | "check";
+
+interface CliOptions extends FeatureLayoutOptions {
+  readonly mode: Mode;
+  readonly format: boolean;
+  readonly paths: readonly string[];
+}
+
+function parseArgs(argv: readonly string[]): CliOptions {
+  let mode: Mode = "write";
+  let format = true;
+  const paths: string[] = [];
+  const featureDirs: string[] = [];
+  const featuresRoots: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] ?? "";
+    if (arg === "--check") mode = "check";
+    else if (arg === "--dry-run") mode = "dry-run";
+    else if (arg === "--write") mode = "write";
+    else if (arg === "--no-format") format = false;
+    else if (arg === "--feature-dir" || arg === "--features-root") {
+      const value = argv[++i];
+      if (value === undefined) throw new Error(`${arg} needs a directory`);
+      (arg === "--feature-dir" ? featureDirs : featuresRoots).push(resolve(value));
+    } else if (arg.startsWith("--")) throw new Error(`unknown flag: ${arg}`);
+    else paths.push(arg);
+  }
+  if (paths.length === 0) throw new Error("at least one target directory is required");
+  return { mode, format, paths, featureDirs, featuresRoots };
+}
+
+function readTargetFiles(paths: readonly string[]): Map<string, string> {
+  const files = new Map<string, string>();
+  const names = collectSourceFiles(paths, {
+    isMigratableFile: (name) => /\.(ts|tsx)$/.test(name) && !name.endsWith(".d.ts"),
+  });
+  const packageJsons = collectSourceFiles(paths, {
+    isMigratableFile: (name) => name === "package.json",
+  });
+  for (const file of [...names, ...packageJsons]) {
+    if (file.includes("/__tests__/fixtures/")) continue;
+    if (statSync(file).isFile()) files.set(file, readFileSync(file, "utf8"));
+  }
+  return files;
+}
+
+function display(file: string): string {
+  const fromCwd = relative(process.cwd(), file);
+  return fromCwd.startsWith("..") ? file : fromCwd;
+}
+
+function writeResult(result: FeatureLayoutResult): void {
+  for (const old of result.removals) rmSync(old);
+  for (const [file, content] of result.writes) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
+  }
+}
+
+async function main(argv: readonly string[]): Promise<void> {
+  let options: CliOptions;
+  try {
+    options = parseArgs(argv);
+  } catch (err) {
+    console.error(`[feature-layout] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(2);
+  }
+  const files = readTargetFiles(options.paths);
+  const result = applyFeatureLayout(files, options);
+  for (const move of result.moves) {
+    console.log(`${display(move.from)}  moved  -> ${display(move.to)}`);
+  }
+  for (const file of result.markersRemoved) console.log(`${display(file)}  marker removed`);
+  for (const site of result.manual) {
+    console.log(`${display(site.file)}:${site.line}  manual  ${site.description}`);
+  }
+  console.log(
+    `\n[feature-layout] ${options.mode === "write" ? "moved" : "movable"}: ${result.moves.length} file(s); markers: ${result.markersRemoved.length}; import sites: ${result.importRewrites.length}; manual: ${result.manual.length}`,
+  );
+  if (options.mode === "write") {
+    writeResult(result);
+    if (options.format) {
+      const changed = [...result.writes.keys()].filter((file) => /\.(ts|tsx)$/.test(file));
+      if (changed.length > 0)
+        await formatWithBiome("feature-layout", changed, resolve(options.paths[0] ?? "."));
+    }
+  }
+  const pending = result.markersRemoved.length + result.manual.length;
+  process.exit(options.mode === "check" && pending > 0 ? 1 : 0);
+}
+
+if (import.meta.main) await main(process.argv.slice(2));

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

@@ -42,17 +42,6 @@ export const PACKAGE_MERGE_MAPPINGS: readonly PackageMergeMapping[] = [
 const DEPENDENCY_BLOCKS = ["dependencies", "devDependencies", "peerDependencies"] as const;
 
 const SKIPPED_PATH_SUFFIXES: readonly string[] = [
-  "packages/http/src/index.ts",
-  "packages/repo-manifest/src/index.ts",
-  "packages/repo-manifest/src/app-ports/index.ts",
-  "packages/headless/src/index.ts",
-  "packages/headless/src/apex/index.ts",
-  "packages/headless/src/dispatcher/index.ts",
-  "packages/headless/src/locale-routing/index.ts",
-  "packages/dispatcher-live/src/index.ts",
-  "packages/renderer-web/src/index.ts",
-  "packages/renderer-web/src/theme-plugin.ts",
-  "packages/renderer-web/src/styles.css",
   "packages/framework/src/scripts/codemod/package-merge.ts",
   "packages/framework/src/__tests__/package-merge-codemod.test.ts",
 ];