@nifrajs/cli 4.0.2 → 5.0.0

package/src/migrate-layout.ts

@@ -8,29 +8,42 @@
  *   2. folds each `_middleware.ts` into its directory's `_layout.backend.ts` as `middleware`;
  *   3. moves `backend.ts` to `backend/app.ts` and `framework.ts` to `backend/framework.ts`;
  *   4. moves each `x.server.ts` under `backend/` without the retired suffix, and zones every other module
- *      by who imports it at runtime: only route frontends -> `frontend/`, only the server side ->
- *      `backend/`, both -> `shared/`;
- *   5. rewrites every relative import in the app to the new locations, `@nifrajs/web/server-only` to
- *      `@nifrajs/web/backend-only`, and `ServerOnly` to `BackendOnly`.
+ *      by who imports it at runtime: only route frontends and the `clientModule` -> `frontend/`, only
+ *      the server side -> `backend/`, both -> `shared/`. Imports through tsconfig `paths`/`baseUrl` and
+ *      package.json `imports` count as the bundler reads them;
+ *   5. rewrites every import in the app to the new locations (test-runner mocks included), an alias
+ *      through the same alias, the config's `clientModule` and `componentPipeline.entries` paths,
+ *      `@nifrajs/web/server-only` to `@nifrajs/web/backend-only`, and `ServerOnly` to `BackendOnly`;
+ *   6. adds the zone folders moved TypeScript lands in to tsconfig `include`, and `.nifra/` to
+ *      `.gitignore`.
+ *
+ * Data files (JSON, YAML, CSV, ...) and folders the app zones in package.json stay where they are.
  *
  * It is a dry run unless `write` is set, and it reports what it could not decide (a frontend that uses
- * a moved name at runtime, a helper both halves need, a loader with no output schema) instead of
- * guessing.
+ * a moved name at runtime, a helper both halves need, a loader with no output schema, an alias no
+ * target covers after a move, a specifier that names nothing) instead of guessing.
  */
 import {
   existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
+  rmdirSync,
   rmSync,
   statSync,
   writeFileSync,
 } from "node:fs"
-import { dirname, extname, join, posix, relative, resolve } from "node:path"
+import { builtinModules } from "node:module"
+import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path"
 import { BACKEND_ROUTE_EXPORTS } from "@nifrajs/web/route-manifest"
+import { parseZoneConfig, type ZoneConfig } from "@nifrajs/web/zones"
 import type * as TS from "typescript"
+import { BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE, retiredRootFiles } from "./app-files.ts"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { createKindProbe, hasWebConfig } from "./internal/nifra-project.ts"
+import { createSpecifierResolver } from "./internal/project-specifiers.ts"
 import { importTypeScript } from "./internal/typescript-import.ts"
 import { missingOutputSchemas } from "./rules/data-guard.ts"
 
@@ -62,6 +75,22 @@ const TOOLING_FILE =
 const SELF_LOCATION = /\bimport\.meta\.(?:dirname|dir|filename|url)\b|\b__(?:dirname|filename)\b/
 const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage", ".git", ".vite", "public"])
 const ZONE_DIRS = new Set(["frontend", "backend", "shared", "routes", "public"])
+/** Data other tools may read by path too; reported, never moved. Images and fonts still move. */
+const DATA_FILE = /\.(?:json|jsonc|json5|ndjson|ya?ml|toml|csv|tsv|txt|xml|sql)$/
+/** Test-runner calls that name a module by path, as an import does. */
+const MOCK_CALLS: ReadonlySet<string> = new Set([
+  "mock.module",
+  "vi.mock",
+  "vi.doMock",
+  "vi.importActual",
+  "vi.importMock",
+  "jest.mock",
+  "jest.doMock",
+  "jest.requireActual",
+  "jest.requireMock",
+  "jest.unstable_mockModule",
+])
+const TAILWIND_CONFIG = /^tailwind\.config\.[cm]?[jt]s$/
 
 export interface LayoutMigrationIssue {
   readonly file: string
@@ -71,6 +100,8 @@ export interface LayoutMigrationIssue {
 export interface LayoutMigrationResult {
   readonly ok: boolean
   readonly write: boolean
+  /** `"api"` for an app that serves no pages: only its backend entry moves, nothing is split or zoned. */
+  readonly mode: "web" | "api"
   /** Route files whose backend exports moved, and where they went. */
   readonly splits: ReadonlyArray<{
     readonly file: string
@@ -81,6 +112,8 @@ export interface LayoutMigrationResult {
   readonly moves: ReadonlyArray<{ readonly from: string; readonly to: string }>
   /** Files whose imports were rewritten (and were not otherwise created). */
   readonly rewritten: readonly string[]
+  /** Tooling config the migration updated so it still covers what moved. */
+  readonly tooling: ReadonlyArray<{ readonly file: string; readonly change: string }>
   readonly issues: readonly LayoutMigrationIssue[]
 }
 
@@ -145,14 +178,42 @@ const hasModifier = (ts: typeof TS, node: TS.Node, kind: TS.SyntaxKind): boolean
 
 /** Identifiers a statement reads, split into value and type positions. Over-approximates on purpose:
  * an extra name only keeps a declaration in a half that did not need it. */
-function references(ts: typeof TS, node: TS.Node): { value: Set<string>; type: Set<string> } {
+interface JsxBindings {
+  readonly element: readonly string[]
+  readonly fragment: readonly string[]
+}
+
+/**
+ * The bindings classic JSX compiles to calls of, which no identifier in the source names: the roots
+ * of the `@jsx`/`@jsxFrag` pragmas, else TypeScript's default `React`. A file that names its own
+ * `@jsxImportSource` imports the runtime itself.
+ */
+function jsxBindings(ts: typeof TS, source: string): JsxBindings {
+  const comments = (ts.getLeadingCommentRanges(source, 0) ?? [])
+    .map(({ pos, end }) => source.slice(pos, end))
+    .join("\n")
+  if (/@jsxImportSource\s/.test(comments)) return { element: [], fragment: [] }
+  const root = (pragma: string): string | undefined =>
+    new RegExp(`@${pragma}\\s+([A-Za-z_$][\\w$]*)`).exec(comments)?.[1]
+  const element = root("jsx") ?? "React"
+  return { element: [element], fragment: [root("jsxFrag") ?? element] }
+}
+
+function references(
+  ts: typeof TS,
+  node: TS.Node,
+  jsx: JsxBindings,
+): { value: Set<string>; type: Set<string> } {
   const value = new Set<string>()
   const type = new Set<string>()
   const visit = (current: TS.Node, inType: boolean): void => {
+    if (ts.isJsxOpeningElement(current) || ts.isJsxSelfClosingElement(current))
+      for (const name of jsx.element) value.add(name)
+    else if (ts.isJsxFragment(current)) for (const name of jsx.fragment) value.add(name)
     const typed =
       inType ||
       ts.isTypeNode(current) ||
-      // @nifra-gate-reviewed: `token` is the heritage clause's syntax kind, not a credential.
+      // nifra-expect NF-S002: `token` is the heritage clause's syntax kind, not a credential.
       (ts.isHeritageClause(current) && current.token === ts.SyntaxKind.ImplementsKeyword)
     if (ts.isIdentifier(current)) {
       const parent = current.parent
@@ -182,6 +243,7 @@ function references(ts: typeof TS, node: TS.Node): { value: Set<string>; type: S
 }
 
 function describeStatements(ts: typeof TS, sf: TS.SourceFile): StatementInfo[] {
+  const jsx = jsxBindings(ts, sf.text)
   return sf.statements.map((node) => {
     const declares = new Set<string>()
     const exports = new Map<string, string[]>()
@@ -232,7 +294,7 @@ function describeStatements(ts: typeof TS, sf: TS.SourceFile): StatementInfo[] {
     }
     const refs = ts.isImportDeclaration(node)
       ? { value: new Set<string>(), type: new Set<string>() }
-      : references(ts, node)
+      : references(ts, node, jsx)
     for (const name of declares) {
       refs.value.delete(name)
       refs.type.delete(name)
@@ -271,9 +333,13 @@ function filterImport(
   if (parts.length === 0) return undefined
   const typeOnly = clause.isTypeOnly ? "type " : ""
   const leading = node.getFullText(sf).slice(0, node.getStart(sf) - node.getFullStart())
-  return `${leading}import ${typeOnly}${parts.join(", ")} from ${spec}${attributes}`
+  return `${leading}import ${typeOnly}${parts.join(", ")} from ${spec}${attributes}${terminatorOf(sf, node)}`
 }
 
+/** The `;` a statement was written with, so a rebuilt one keeps the file's style. */
+const terminatorOf = (sf: TS.SourceFile, node: TS.Node): string =>
+  node.getText(sf).endsWith(";") ? ";" : ""
+
 /** Rebuild `export { a, b as c }` keeping only the exported names `keep` accepts. */
 function filterExportList(
   ts: typeof TS,
@@ -287,7 +353,7 @@ function filterExportList(
   if (kept.length === 0) return undefined
   const from = node.moduleSpecifier ? ` from ${node.moduleSpecifier.getText(sf)}` : ""
   const leading = node.getFullText(sf).slice(0, node.getStart(sf) - node.getFullStart())
-  return `${leading}export ${node.isTypeOnly ? "type " : ""}{ ${kept.join(", ")} }${from}`
+  return `${leading}export ${node.isTypeOnly ? "type " : ""}{ ${kept.join(", ")} }${from}${terminatorOf(sf, node)}`
 }
 
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
@@ -453,10 +519,11 @@ export function splitRouteSource(
   }
   // After the other imports: the nearest relative path sorts last.
   if (typeImports.size > 0) {
+    const semi = statements.some((info) => terminatorOf(sf, info.node) !== "") ? ";" : ""
     frontendTexts.splice(
       afterImports,
       0,
-      `\nimport type { ${[...typeImports].sort().join(", ")} } from "${backendSpecifier}"`,
+      `\nimport type { ${[...typeImports].sort().join(", ")} } from "${backendSpecifier}"${semi}`,
     )
   }
   // A JSX pragma counts only in the file's leading comments, and the backend half has no JSX.
@@ -497,7 +564,7 @@ export function middlewareSource(ts: typeof TS, source: string, fileName: string
   // Edit from the end so earlier offsets stay valid.
   for (const node of [...sf.statements].reverse()) {
     if (ts.isExportAssignment(node) && !node.isExportEquals) {
-      out = `${out.slice(0, node.getStart(sf))}export const middleware = ${node.expression.getText(sf)}${out.slice(node.getEnd())}`
+      out = `${out.slice(0, node.getStart(sf))}export const middleware = ${node.expression.getText(sf)}${terminatorOf(sf, node)}${out.slice(node.getEnd())}`
     } else if (
       ts.isFunctionDeclaration(node) &&
       hasModifier(ts, node, ts.SyntaxKind.DefaultKeyword)
@@ -515,7 +582,8 @@ export function middlewareSource(ts: typeof TS, source: string, fileName: string
         out = `${out.slice(0, first.getStart(sf))}export${text}${out.slice(node.getEnd())}`
       } else {
         out = `${out.slice(0, first.getStart(sf))}${out.slice(last.getEnd()).replace(/^\s+/, "")}`
-        out = `${out.trimEnd()}\nexport { ${node.name.text} as middleware }\n`
+        const semi = sf.statements.some((s) => terminatorOf(sf, s) !== "") ? ";" : ""
+        out = `${out.trimEnd()}\nexport { ${node.name.text} as middleware }${semi}\n`
       }
     }
   }
@@ -579,6 +647,16 @@ interface ImportRef {
   readonly typeOnly: boolean
 }
 
+/** The path argument of `mock.module("./x", ...)` or a vitest/jest twin, when it is a literal. */
+function mockedSpecifier(ts: typeof TS, node: TS.CallExpression): TS.StringLiteralLike | undefined {
+  const callee = node.expression
+  if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression))
+    return undefined
+  if (!MOCK_CALLS.has(`${callee.expression.text}.${callee.name.text}`)) return undefined
+  const arg = node.arguments[0]
+  return arg !== undefined && ts.isStringLiteralLike(arg) ? arg : undefined
+}
+
 function importsOf(ts: typeof TS, file: string, text: string): ImportRef[] {
   if (/\.(?:svelte|vue)$/.test(file)) {
     return scriptBlocks(text).flatMap((block) =>
@@ -635,6 +713,9 @@ function importsOf(ts: typeof TS, file: string, text: string): ImportRef[] {
       const isRequire = ts.isIdentifier(node.expression) && node.expression.text === "require"
       if ((isImport || isRequire) && arg !== undefined && ts.isStringLiteralLike(arg))
         refs.push({ specifier: arg.text, typeOnly: false })
+      // A test's mock names the module without loading it into the app: no runtime edge.
+      const mocked = mockedSpecifier(ts, node)
+      if (mocked !== undefined) refs.push({ specifier: mocked.text, typeOnly: true })
     } else if (
       ts.isImportEqualsDeclaration(node) &&
       ts.isExternalModuleReference(node.moduleReference)
@@ -846,6 +927,164 @@ function rebase(specifier: string, from: string, newFrom: string): string | unde
   return rel.startsWith(".") ? rel : `./${rel}`
 }
 
+/** A split route as an importer sees it: the names that left it, and how this importer spells the
+ * backend half they went to (`undefined` when an alias cannot name it). */
+interface SplitTarget {
+  readonly backend: string
+  readonly moved: ReadonlySet<string>
+  readonly specifier: string | undefined
+}
+
+/** `specifier` re-pointed from a split route to its backend half, in the author's extension style. */
+function backendSpecifier(specifier: string, route: string, backend: string, from: string): string {
+  const query = /[?#].*$/.exec(specifier)?.[0] ?? ""
+  const written = extname(specifier.slice(0, specifier.length - query.length))
+  const stem = backend.slice(0, -extname(backend).length)
+  const target =
+    written === ""
+      ? stem
+      : written === extname(route)
+        ? backend
+        : `${stem}${written === ".jsx" ? ".js" : written}`
+  const rel = posix.relative(posix.dirname(from), target)
+  return (rel.startsWith(".") ? rel : `./${rel}`) + query
+}
+
+/**
+ * Point an importer's named imports of a split route's moved exports (`loader`, `action`, ...) at the
+ * backend half, splitting a statement that also names what stayed. What cannot be rewritten (a
+ * namespace or dynamic import that reads a moved name, `export *`, an alias with no target there) is
+ * returned as an issue.
+ */
+function redirectMovedImports(
+  ts: typeof TS,
+  file: string,
+  text: string,
+  splitOf: (specifier: string) => SplitTarget | undefined,
+): {
+  readonly text: string
+  readonly issues: readonly string[]
+  readonly redirects: ReadonlyArray<{ names: string[]; from: string; to: string }>
+} {
+  const redirects: Array<{ names: string[]; from: string; to: string }> = []
+  const sf = ts.createSourceFile(
+    file,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  )
+  const edits: Array<{ start: number; end: number; text: string }> = []
+  const issues: string[] = []
+  const mentioned = (split: SplitTarget, pattern: (name: string) => RegExp): string[] =>
+    [...split.moved].filter((name) => pattern(escapeRegExp(name)).test(text)).sort()
+  const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(", ")
+  const visit = (node: TS.Node): void => {
+    if (
+      (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+      node.moduleSpecifier !== undefined &&
+      ts.isStringLiteral(node.moduleSpecifier)
+    ) {
+      const from = node.moduleSpecifier.text
+      const split = splitOf(from)
+      if (split === undefined) return
+      const clause = ts.isImportDeclaration(node) ? node.importClause : undefined
+      const named = ts.isImportDeclaration(node) ? clause?.namedBindings : node.exportClause
+      if (named !== undefined && (ts.isNamespaceImport(named) || ts.isNamespaceExport(named))) {
+        const reads = mentioned(split, (name) => new RegExp(`\\b${named.name.text}\\.${name}\\b`))
+        if (reads.length > 0)
+          issues.push(
+            `reads ${quoted(reads)} through a namespace import of "${from}", but they moved to "${split.backend}"; import them from there by hand`,
+          )
+        return
+      }
+      if (named === undefined) {
+        if (ts.isExportDeclaration(node))
+          issues.push(
+            `re-exports everything from "${from}", but ${quoted([...split.moved].sort())} moved to "${split.backend}"; re-export them from there by hand`,
+          )
+        return
+      }
+      const elements: readonly (TS.ImportSpecifier | TS.ExportSpecifier)[] = named.elements
+      const isMoved = (el: TS.ImportSpecifier | TS.ExportSpecifier): boolean =>
+        split.moved.has((el.propertyName ?? el.name).text)
+      const moved = elements.filter(isMoved)
+      if (moved.length === 0) return
+      if (split.specifier === undefined) {
+        issues.push(
+          `imports ${quoted(moved.map((el) => (el.propertyName ?? el.name).text))} from "${from}", but they moved to "${split.backend}" and no target of that alias covers it; point the import there by hand`,
+        )
+        return
+      }
+      redirects.push({
+        names: moved.map((el) => (el.propertyName ?? el.name).text),
+        from,
+        to: split.specifier,
+      })
+      const kept = elements.filter((el) => !isMoved(el)).map((el) => el.getText(sf))
+      const quote = node.moduleSpecifier.getText(sf)[0] ?? '"'
+      const attributes = node.attributes ? ` ${node.attributes.getText(sf)}` : ""
+      const tail = (specifier: string): string =>
+        ` from ${quote}${specifier}${quote}${attributes}${terminatorOf(sf, node)}`
+      const keyword = ts.isImportDeclaration(node)
+        ? `import ${clause?.isTypeOnly ? "type " : ""}`
+        : `export ${node.isTypeOnly ? "type " : ""}`
+      const list = (names: readonly string[]): string => `{ ${names.join(", ")} }`
+      const backend = `${keyword}${list(moved.map((el) => el.getText(sf)))}${tail(split.specifier)}`
+      const stays = [
+        ...(clause?.name === undefined ? [] : [clause.name.text]),
+        ...(kept.length === 0 ? [] : [list(kept)]),
+      ]
+      edits.push({
+        start: node.getStart(sf),
+        end: node.getEnd(),
+        text:
+          stays.length === 0 ? backend : `${keyword}${stays.join(", ")}${tail(from)}\n${backend}`,
+      })
+      return
+    }
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+      node.arguments[0] !== undefined &&
+      ts.isStringLiteralLike(node.arguments[0])
+    ) {
+      const from = node.arguments[0].text
+      const split = splitOf(from)
+      const reads =
+        split === undefined ? [] : mentioned(split, (name) => new RegExp(`\\b${name}\\b`))
+      if (split !== undefined && reads.length > 0)
+        issues.push(
+          `loads "${from}" with import() and mentions ${quoted(reads)}, which moved to "${split.backend}"; load the backend half for them by hand`,
+        )
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  let out = text
+  for (const edit of edits.sort((a, b) => b.start - a.start))
+    out = out.slice(0, edit.start) + edit.text + out.slice(edit.end)
+  return { text: out, issues, redirects }
+}
+
+/** The package folder an app without its own package.json sits in (`--dir src`), at most two levels
+ * up and never a workspace root, so the scan beside it stays inside one package. */
+function enclosingPackage(root: string): string | undefined {
+  if (existsSync(join(root, "package.json"))) return undefined
+  for (const dir of [dirname(root), dirname(dirname(root))]) {
+    const manifest = join(dir, "package.json")
+    if (dir === root || !existsSync(manifest)) continue
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(manifest, "utf8"))
+      const workspace = typeof parsed === "object" && parsed !== null && "workspaces" in parsed
+      return workspace ? undefined : dir
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
 function rewriteImports(
   ts: typeof TS,
   file: string,
@@ -880,7 +1119,7 @@ function rewriteImports(
       ) {
         const arg = node.arguments[0]
         if (arg !== undefined && ts.isStringLiteralLike(arg)) literal = arg
-      }
+      } else if (ts.isCallExpression(node)) literal = mockedSpecifier(ts, node)
       if (literal !== undefined) {
         const next = rewrite(literal.text)
         if (next !== undefined && next !== literal.text) {
@@ -976,16 +1215,153 @@ function renameRetiredTypes(ts: typeof TS, file: string, text: string): string {
 // The migration
 // ---------------------------------------------------------------------------------------------------
 
-const ROOT_MOVES: Readonly<Record<string, string>> = {
-  "backend.ts": "backend/app.ts",
-  "framework.ts": "backend/framework.ts",
-}
 /** Root files that stay where they are: the CLI's config, and scripts no build loads. */
-const isRootScript = (file: string): boolean =>
-  !file.includes("/") && SOURCE_FILE.test(file) && ROOT_MOVES[file] === undefined
+/** The config files the loader reads, old layout included; a path field may live in any of them. */
+const CONFIG_FILES = ["nifra.config.ts", "framework.ts", "backend/framework.ts"]
+
+interface ConfigEntry {
+  /** `clientModule`, or `componentPipeline.entries.<name>`. */
+  readonly field: string
+  readonly role: "frontend" | "backend"
+  readonly value: string
+  /** The literal's text, quotes excluded: [start, end). */
+  readonly start: number
+  readonly end: number
+}
+
+/**
+ * The module paths a config exports as string literals: `clientModule` and the component pipeline's
+ * `entries`. The browser loads `clientModule` and `entries.client`; `ssr` and `rsc` run on the server.
+ */
+function configEntries(ts: typeof TS, file: string, text: string): ConfigEntry[] {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  const bare = (node: TS.Expression | undefined): TS.Expression | undefined => {
+    let current = node
+    while (
+      current !== undefined &&
+      (ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isParenthesizedExpression(current))
+    )
+      current = current.expression
+    return current
+  }
+  const out: ConfigEntry[] = []
+  const literal = (field: string, role: ConfigEntry["role"], node: TS.Expression | undefined) => {
+    const value = bare(node)
+    if (value === undefined || !ts.isStringLiteralLike(value)) return
+    out.push({
+      field,
+      role,
+      value: value.text,
+      start: value.getStart(sf) + 1,
+      end: value.getEnd() - 1,
+    })
+  }
+  for (const statement of sf.statements) {
+    if (
+      !ts.isVariableStatement(statement) ||
+      !hasModifier(ts, statement, ts.SyntaxKind.ExportKeyword)
+    )
+      continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name)) continue
+      if (declaration.name.text === "clientModule")
+        literal("clientModule", "frontend", declaration.initializer)
+      if (declaration.name.text !== "componentPipeline") continue
+      const pipeline = bare(declaration.initializer)
+      if (pipeline === undefined || !ts.isObjectLiteralExpression(pipeline)) continue
+      for (const property of pipeline.properties) {
+        if (!ts.isPropertyAssignment(property) || property.name.getText(sf) !== "entries") continue
+        const entries = bare(property.initializer)
+        if (entries === undefined || !ts.isObjectLiteralExpression(entries)) continue
+        for (const entry of entries.properties) {
+          if (!ts.isPropertyAssignment(entry)) continue
+          const name = entry.name.getText(sf).replace(/^["']|["']$/g, "")
+          if (name === "client" || name === "ssr" || name === "rsc")
+            literal(
+              `componentPipeline.entries.${name}`,
+              name === "client" ? "frontend" : "backend",
+              entry.initializer,
+            )
+        }
+      }
+    }
+  }
+  return out
+}
+
+/** The package an import names: `@scope/pkg` or `pkg`, without a subpath. */
+const packageName = (specifier: string): string => {
+  const parts = specifier.split("/")
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? "")
+}
+
+const isRootScript = (file: string, rootMoves: Readonly<Record<string, string>>): boolean =>
+  !file.includes("/") && SOURCE_FILE.test(file) && rootMoves[file] === undefined
 const isTestFile = (file: string): boolean =>
   /(?:^|\/)(?:test|tests|__tests__)\//.test(file) || /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(file)
 
+/** The web config an app has, old root `framework.ts` included, or `undefined`. */
+const webConfigFile = (
+  root: string,
+  rootMoves: Readonly<Record<string, string>>,
+): string | undefined =>
+  rootMoves["framework.ts"] !== undefined
+    ? "framework.ts"
+    : existsSync(join(root, FRAMEWORK_FILE))
+      ? FRAMEWORK_FILE
+      : hasWebConfig(root, ".")
+        ? CONFIG_FILE
+        : undefined
+
+/**
+ * `"api"` when the app declares `"nifra": { "kind": "api" }`, or has no web config, no `routes/` and a
+ * backend; `"web"` when it has `routes/`. Web config without `routes/` could be either, so it throws.
+ */
+function layoutMode(root: string, rootMoves: Readonly<Record<string, string>>): "web" | "api" {
+  const declared = createKindProbe(root)(root)
+  if (declared.invalid !== undefined) throw new Error(declared.invalid)
+  const config = webConfigFile(root, rootMoves)
+  if (declared.kind === "api") {
+    if (config === undefined) return "api"
+    throw new Error(
+      `[nifra] ${declared.manifest} declares "nifra": { "kind": "api" }, but ${root} has web config (${config}); remove "kind" to migrate it as a web app, or remove the web config`,
+    )
+  }
+  if (existsSync(join(root, "routes"))) return "web"
+  const nested = nestedAppHint(root)
+  if (config !== undefined) {
+    throw new Error(
+      `[nifra] no routes/ directory in ${root}, but it has web config (${config}). A web app is file-routed under routes/; if this one serves no pages, remove the web config and declare "nifra": { "kind": "api" } in package.json${nested}`,
+    )
+  }
+  if (declared.kind === "web") throw new Error(`[nifra] no routes/ directory in ${root}${nested}`)
+  if (rootMoves["backend.ts"] === undefined && !existsSync(join(root, BACKEND_APP_FILE))) {
+    throw new Error(
+      `[nifra] ${root} has no routes/, no web config and no backend (a backend.ts that exports \`backend\`, or ${BACKEND_APP_FILE}); there is nothing to migrate${nested}`,
+    )
+  }
+  return "api"
+}
+
+/** An app one folder down (`src/routes/`): the `--dir` that migrates it, as a sentence to append. */
+function nestedAppHint(root: string): string {
+  const found = readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        !entry.name.startsWith(".") &&
+        !SKIP_DIRS.has(entry.name) &&
+        existsSync(join(root, entry.name, "routes")),
+    )
+    .map((entry) => entry.name)
+    .sort(codeUnitOrder)
+  const first = found[0]
+  if (first === undefined) return ""
+  return `. ${found.map((name) => `${name}/routes/`).join(", ")} exists: run \`nifra migrate layout --dir ${first}\` to migrate the app there`
+}
+
 export async function migrateLayout(
   appRoot: string,
   options: LayoutMigrationOptions = {},
@@ -994,7 +1370,15 @@ export async function migrateLayout(
   if (ts === undefined)
     throw new Error("[nifra] `nifra migrate layout` needs TypeScript: bun add -d typescript")
   const root = resolve(appRoot)
-  if (!existsSync(join(root, "routes"))) throw new Error(`[nifra] no routes/ directory in ${root}`)
+  // Only a root file that exports what the old layout read moves; any other backend.ts is a module.
+  const rootMoves: Readonly<Record<string, string>> = Object.fromEntries(retiredRootFiles(root))
+  const mode = layoutMode(root, rootMoves)
+  // An API-only app has no browser: nothing to split, and every file is server code where it is.
+  const api = mode === "api"
+  const zones = appZones(root)
+  const configured = [...(zones.backend ?? []), ...(zones.frontend ?? []), ...(zones.shared ?? [])]
+  const inConfiguredFolder = (file: string): boolean =>
+    configured.some((folder) => file === folder || file.startsWith(`${folder}/`))
   const original: Files = new Map()
   const everyFile = listFiles(root)
   for (const file of everyFile) {
@@ -1011,7 +1395,7 @@ export async function migrateLayout(
   // 1-2. Route halves and middleware.
   const backendHalves = new Map<string, string>()
   for (const [file, text] of original) {
-    if (!file.startsWith("routes/") || file.includes(".backend.")) continue
+    if (api || !file.startsWith("routes/") || file.includes(".backend.")) continue
     if (/(?:^|\/)_middleware\.[cm]?[jt]sx?$/.test(file)) {
       const target = posix.join(posix.dirname(file), "_layout.backend.ts")
       backendHalves.set(
@@ -1066,12 +1450,98 @@ export async function migrateLayout(
   }
 
   // 3-4. Zoning by runtime reachability, on the post-split graph.
-  for (const [from, to] of Object.entries(ROOT_MOVES)) if (next.has(from)) moveMap.set(from, to)
+  for (const [from, to] of Object.entries(rootMoves)) if (next.has(from)) moveMap.set(from, to)
   // Assets (images, fonts) resolve too, so they move with the modules that import them.
   const known = new Set([...next.keys(), ...everyFile])
+  const resolver = createSpecifierResolver()
+  const realRoot = (() => {
+    try {
+      return realpathSync(root)
+    } catch {
+      return root
+    }
+  })()
+  /** A non-relative specifier the app's tsconfig `paths`/`baseUrl` or package.json `imports` maps to
+   * one of its files, read from disk as the bundler reads it. */
+  const viaAlias = (file: string, specifier: string): string | undefined => {
+    if (specifier.startsWith(".") || isAbsolute(specifier)) return undefined
+    const found = resolver(join(root, file), specifier)
+    if (found === undefined) return undefined
+    const rel = toPosix(relative(realRoot, found))
+    return rel.startsWith("../") || isAbsolute(rel) || !known.has(rel) ? undefined : rel
+  }
+  const resolveAny = (file: string, specifier: string): string | undefined =>
+    resolveIn(known, file, specifier) ?? viaAlias(file, specifier)
+  const ownName = (() => {
+    try {
+      const name: unknown = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name
+      return typeof name === "string" ? name : undefined
+    } catch {
+      return undefined
+    }
+  })()
+  const installed = new Map<string, boolean>()
+  /** Whether a bare specifier names something outside the app that exists: a built-in, a URL or a
+   * scheme the bundler owns, the app's own package name, or a package installed at or above it. */
+  const external = (specifier: string): boolean => {
+    if (/^[a-z][a-z\d+.-]*:/i.test(specifier) || specifier === "bun") return true
+    const name = packageName(specifier.replace(/[?#].*$/, ""))
+    if (builtinModules.includes(name) || name === ownName) return true
+    let found = installed.get(name)
+    if (found === undefined) {
+      const types = `@types/${name.startsWith("@") ? name.slice(1).replace("/", "__") : name}`
+      found = false
+      for (let dir = root; ; dir = dirname(dir)) {
+        if (
+          existsSync(join(dir, "node_modules", name)) ||
+          existsSync(join(dir, "node_modules", types))
+        ) {
+          found = true
+          break
+        }
+        if (dirname(dir) === dir) break
+      }
+      installed.set(name, found)
+    }
+    return found
+  }
+  // A test (or any module) that imports `loader` from a page would import a name the page no longer
+  // exports: it reads it from the backend half instead.
+  const splitRoutes = new Map<string, { backend: string; moved: ReadonlySet<string> }>()
+  for (const split of splits)
+    if (next.has(split.file)) splitRoutes.set(split.file, { ...split, moved: new Set(split.moved) })
+  /** `base` is where `file` is relative to: the app root, or the package folder around it. */
+  const splitTarget =
+    (base: string, file: string, resolve: (specifier: string) => string | undefined) =>
+    (specifier: string): SplitTarget | undefined => {
+      const route = resolve(specifier)
+      const split = route === undefined ? undefined : splitRoutes.get(route)
+      if (route === undefined || split === undefined) return undefined
+      const inBase = (path: string): string => toPosix(relative(base, join(root, path)))
+      const respelled = specifier.startsWith(".")
+        ? backendSpecifier(specifier, inBase(route), inBase(split.backend), file)
+        : resolver.respell(join(base, file), specifier, join(root, split.backend))
+      return { backend: split.backend, moved: split.moved, specifier: respelled }
+    }
+  const redirectedFiles = new Set<string>()
+  for (const [file, text] of splitRoutes.size === 0 ? [] : next) {
+    if (splitRoutes.has(file) || !/\.[cm]?[jt]sx?$/.test(file)) continue
+    const redirected = redirectMovedImports(
+      ts,
+      file,
+      text,
+      splitTarget(root, file, (specifier) => resolveAny(file, specifier)),
+    )
+    if (redirected.text !== text) {
+      next.set(file, redirected.text)
+      redirectedFiles.add(file)
+    }
+    for (const reason of redirected.issues) issues.push({ file, reason })
+  }
   const edges = new Map<string, Array<{ target: string; typeOnly: boolean }>>()
-  for (const [file, text] of next) {
+  for (const [file, text] of api ? [] : next) {
     const refs: Array<{ target: string; typeOnly: boolean }> = []
+    const reported = new Set<string>()
     for (const ref of importsOf(ts, file, text)) {
       if (ref.specifier === "@nifrajs/web/plugins/vite-server-only") {
         issues.push({
@@ -1080,23 +1550,52 @@ export async function migrateLayout(
             "imports the retired @nifrajs/web/plugins/vite-server-only; remove it: nifra's Vite builds and dev server enforce the zones themselves (a hand-built Vite config uses viteLeakGuard from @nifrajs/web/plugins/vite-leak-guard)",
         })
       }
-      const target = resolveIn(known, file, ref.specifier)
+      const target = resolveAny(file, ref.specifier)
       if (target !== undefined) refs.push({ target, typeOnly: ref.typeOnly })
-      else if (/^[@~]\//.test(ref.specifier))
+      else if (
+        !ref.specifier.startsWith(".") &&
+        !isAbsolute(ref.specifier) &&
+        RETIRED_SPECIFIERS[ref.specifier] === undefined &&
+        resolver(join(root, file), ref.specifier) === undefined &&
+        !external(ref.specifier) &&
+        !reported.has(ref.specifier)
+      ) {
+        reported.add(ref.specifier)
         issues.push({
           file,
-          reason: `the path alias "${ref.specifier}" is left as written; point it at the new location by hand`,
+          reason: `"${ref.specifier}" names no installed package and no file through the app's tsconfig paths or package.json imports, so the migration cannot tell where it belongs; check it by hand`,
         })
+      }
     }
     edges.set(file, refs)
   }
-  const files = [...new Set([...next.keys(), ...everyFile.filter((f) => !original.has(f))])]
-  const frontendRoots = files.filter(
-    (f) => f.startsWith("routes/") && ROUTE_FILE.test(f) && !f.includes(".backend."),
+  // The config's module paths are entries too: the browser loads `clientModule`.
+  const entries = CONFIG_FILES.filter((file) => next.has(file)).flatMap((file) =>
+    configEntries(ts, file, next.get(file) ?? "").map((entry) => ({
+      ...entry,
+      file,
+      // Relative to the app root, as the loader reads it, whichever config file holds it.
+      target: resolveAny("nifra.config.ts", entry.value),
+    })),
   )
+  const entryTargets = (role: ConfigEntry["role"]): Set<string> =>
+    new Set(
+      entries.flatMap((entry) =>
+        entry.role === role && entry.target !== undefined ? [entry.target] : [],
+      ),
+    )
+  const browserEntries = entryTargets("frontend")
+  const serverEntries = entryTargets("backend")
+  const files = [...new Set([...next.keys(), ...everyFile.filter((f) => !original.has(f))])]
+  const frontendRoots = [
+    ...files.filter(
+      (f) => f.startsWith("routes/") && ROUTE_FILE.test(f) && !f.includes(".backend."),
+    ),
+    ...browserEntries,
+  ]
   // A route page the server imports - a generated `server-manifest.ts` imports them all - is rendered
   // there, not run as server code, so the server's walk stops at it: what only pages use stays frontend.
-  const pages = new Set(frontendRoots)
+  const pages = new Set(frontendRoots.filter((f) => !browserEntries.has(f)))
   const reach = (roots: readonly string[], stopAt?: ReadonlySet<string>): Set<string> => {
     const seen = new Set<string>()
     const queue = [...roots]
@@ -1109,23 +1608,31 @@ export async function migrateLayout(
     }
     return seen
   }
-  const backendRoots = files.filter(
-    (f) =>
-      (f.startsWith("routes/") && f.includes(".backend.")) ||
-      f.startsWith("backend/") ||
-      ROOT_MOVES[f] !== undefined ||
-      (isRootScript(f) && f !== "nifra.config.ts" && !isTestFile(f)),
-  )
+  const backendRoots = [
+    ...files.filter(
+      (f) =>
+        (f.startsWith("routes/") && f.includes(".backend.")) ||
+        f.startsWith("backend/") ||
+        rootMoves[f] !== undefined ||
+        (isRootScript(f, rootMoves) &&
+          f !== "nifra.config.ts" &&
+          !isTestFile(f) &&
+          !browserEntries.has(f)),
+    ),
+    ...serverEntries,
+  ]
   const browser = reach(frontendRoots)
   const server = reach(backendRoots, pages)
   // What the app's own server modules reach, without the root scripts: a root file in here is a module
   // the app imports, not an entry, so it moves into a zone.
   const appServer = reach(
-    backendRoots.filter((f) => f.includes("/") || ROOT_MOVES[f] !== undefined),
+    backendRoots.filter(
+      (f) => f.includes("/") || rootMoves[f] !== undefined || serverEntries.has(f),
+    ),
     pages,
   )
   // A `.server` module ran empty in the browser, so only server code used it: it moves under backend/.
-  for (const file of files) {
+  for (const file of api ? [] : files) {
     if (!LEGACY_SERVER.test(file) || isTestFile(file)) continue
     const parts = file.replace(LEGACY_SERVER, "$1").split("/")
     if (parts.length > 1 && ZONE_DIRS.has(parts[0] ?? "")) parts.shift()
@@ -1140,12 +1647,13 @@ export async function migrateLayout(
   }
   const zoneOf = (file: string): "frontend" | "backend" | "shared" =>
     browser.has(file) && server.has(file) ? "shared" : browser.has(file) ? "frontend" : "backend"
-  for (const file of files) {
+  for (const file of api ? [] : files) {
     if (
       moveMap.has(file) ||
       isTestFile(file) ||
       file.endsWith(".d.ts") ||
-      file === "nifra.config.ts"
+      file === "nifra.config.ts" ||
+      inConfiguredFolder(file)
     )
       continue
     if (/\.(?:frontend|backend|shared|fn)\.[cm]?[jt]sx?$/.test(file)) continue
@@ -1153,7 +1661,16 @@ export async function migrateLayout(
     if (file.includes("/")) {
       if (ZONE_DIRS.has(top) || (!browser.has(file) && !server.has(file))) continue
     } else if (!browser.has(file) && !appServer.has(file)) continue
-    moveMap.set(file, `${zoneOf(file)}/${file}`)
+    const zone = zoneOf(file)
+    if (DATA_FILE.test(file)) {
+      const folder = file.includes("/") ? posix.dirname(file) : undefined
+      issues.push({
+        file,
+        reason: `is data ${zone === "shared" ? "both sides import" : `${zone} code imports`}, and a build only loads files in a zone; it stays here because other tools may read it by path. Move it to "${zone}/${file}" by hand, or ${folder === undefined ? "into a folder listed" : `list "${folder}"`} under "nifra": { "zones": { "${zone}": [...] } } in package.json`,
+      })
+      continue
+    }
+    moveMap.set(file, `${zone}/${file}`)
   }
   const claimed = new Map<string, string>()
   for (const [from, to] of moveMap) {
@@ -1181,19 +1698,60 @@ export async function migrateLayout(
   const newPath = (file: string): string => moveMap.get(file) ?? file
   const final: Files = new Map()
   const rewritten: string[] = []
+  const unspelled = new Set<string>()
+  /** An alias for a target that moves, through the same alias, or an issue when none covers it. */
+  const respellAlias = (file: string, specifier: string, target: string): string | undefined => {
+    if (newPath(target) === target) return undefined
+    const respelled = resolver.respell(join(root, file), specifier, join(root, newPath(target)))
+    if (respelled === undefined && !unspelled.has(`${file}\0${specifier}`)) {
+      unspelled.add(`${file}\0${specifier}`)
+      issues.push({
+        file,
+        reason: `the path alias "${specifier}" names "${target}", which moves to "${newPath(target)}", and no target of that alias covers the new location; point it there by hand`,
+      })
+    }
+    return respelled
+  }
   for (const [file, text] of next) {
     const imports = rewriteImports(ts, file, text, (specifier) => {
       const retired = RETIRED_SPECIFIERS[specifier]
       if (retired !== undefined) return retired
-      const target = resolveIn(known, file, specifier)
+      const target = resolveAny(file, specifier)
       // Outside the app (or a skipped dir): the target stays put, so only a moved importer re-bases it.
       if (target === undefined) return rebase(specifier, file, newPath(file))
+      if (!specifier.startsWith(".")) return respellAlias(file, specifier, target)
       if (newPath(target) === target && newPath(file) === file) return undefined
       return respecify(specifier, target, newPath(file), newPath(target))
     })
     const updated = renameRetiredTypes(ts, file, imports)
     final.set(newPath(file), updated)
-    if (updated !== text && !moveMap.has(file) && original.get(file) === text) rewritten.push(file)
+    if (
+      !moveMap.has(file) &&
+      (redirectedFiles.has(file) || (updated !== text && original.get(file) === text))
+    )
+      rewritten.push(file)
+  }
+
+  // A config path names its module from the app root, so it follows the module, never the config file.
+  for (const configFile of CONFIG_FILES) {
+    const at = newPath(configFile)
+    const text = final.get(at)
+    if (text === undefined || !next.has(configFile)) continue
+    const edits: Array<{ start: number; end: number; text: string }> = []
+    for (const entry of configEntries(ts, at, text)) {
+      const target = resolveAny("nifra.config.ts", entry.value)
+      if (target === undefined || newPath(target) === target) continue
+      const value = entry.value.startsWith(".")
+        ? respecify(entry.value, target, "nifra.config.ts", newPath(target))
+        : respellAlias(configFile, entry.value, target)
+      if (value !== undefined) edits.push({ start: entry.start, end: entry.end, text: value })
+    }
+    if (edits.length === 0) continue
+    let updated = text
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+      updated = updated.slice(0, edit.start) + edit.text + updated.slice(edit.end)
+    final.set(at, updated)
+    if (!moveMap.has(configFile) && !rewritten.includes(configFile)) rewritten.push(configFile)
   }
 
   const moves = [...moveMap]
@@ -1249,6 +1807,44 @@ export async function migrateLayout(
     }
   }
 
+  // Code beside an app one folder down (a package's test/ when the app is its src/) is not the
+  // migration's to edit, so each import there that stops resolving to what it named is reported.
+  const pkg = enclosingPackage(root)
+  if (pkg !== undefined) {
+    const prefix = toPosix(relative(pkg, root))
+    const inApp = new Set([...known].map((file) => `${prefix}/${file}`))
+    const appPath = (file: string, specifier: string): string | undefined =>
+      resolveIn(inApp, file, specifier)?.slice(prefix.length + 1)
+    const outside = ` - it is outside ${prefix}/, so the migration does not rewrite it`
+    for (const file of listFiles(pkg)) {
+      if (file.startsWith(`${prefix}/`) || !/\.[cm]?[jt]sx?$/.test(file)) continue
+      const text = readFileSync(join(pkg, file), "utf8")
+      const at = toPosix(relative(root, join(pkg, file)))
+      for (const { specifier } of importsOf(ts, file, text)) {
+        const target = appPath(file, specifier)
+        const to = target === undefined ? undefined : moveMap.get(target)
+        if (to !== undefined)
+          issues.push({
+            file: at,
+            reason: `imports "${specifier}", which moves to "${to}"${outside}`,
+          })
+      }
+      const redirected = redirectMovedImports(
+        ts,
+        file,
+        text,
+        splitTarget(pkg, file, (specifier) => appPath(file, specifier)),
+      )
+      for (const { names, from, to } of redirected.redirects) {
+        issues.push({
+          file: at,
+          reason: `imports ${names.map((name) => `"${name}"`).join(", ")} from "${from}"; import it from "${to}"${outside}`,
+        })
+      }
+      for (const reason of redirected.issues) issues.push({ file: at, reason })
+    }
+  }
+
   // Paths a module finds at run time are not imports either: one built from the module's own location
   // now starts from its new folder, and a folder listed at run time loses whatever moved out of it.
   const leaving = new Map<string, Array<{ from: string; to: string }>>()
@@ -1261,7 +1857,8 @@ export async function migrateLayout(
       })
     }
     const dir = posix.dirname(move.from)
-    if (dir === "." || ZONE_DIRS.has(dir.split("/")[0] ?? "")) continue
+    if (dir === "." || ZONE_DIRS.has(dir.split("/")[0] ?? "") || inConfiguredFolder(move.from))
+      continue
     leaving.set(dir, [...(leaving.get(dir) ?? []), move])
   }
   for (const [dir, group] of leaving) {
@@ -1288,51 +1885,276 @@ export async function migrateLayout(
     for (const { name, schema } of missingOutputSchemas(text)) {
       issues.push({
         file,
-        reason: `exports ${name === "action" ? "an" : "a"} ${name} but no ${schema}, so data it returns fails the request. Declare what the browser may see: export const ${schema} = t.object({ ... })`,
+        reason: `exports ${name === "action" ? "an" : "a"} ${name} but no ${schema}, so data it returns fails the request. Declare what the browser may see: export const ${schema} = t.object({ ... }), or run \`nifra schemas --write\` after the migration to draft it from the ${name}'s return type`,
       })
     }
   }
 
+  // Tooling that lists folders or globs, not files: the import rewrite above never sees it.
+  const tooling: Array<{ file: string; change: string }> = []
+  const toolingWrites = new Map<string, string>()
+  const tsconfig = coverMovedFiles(ts, root, moves)
+  if (tsconfig?.issue !== undefined) issues.push({ file: "tsconfig.json", reason: tsconfig.issue })
+  if (tsconfig?.text !== undefined) {
+    toolingWrites.set("tsconfig.json", tsconfig.text)
+    tooling.push({ file: "tsconfig.json", change: `include += ${tsconfig.added.join(", ")}` })
+  }
+  for (const file of everyFile) {
+    if (!TAILWIND_CONFIG.test(file)) continue
+    const reason = staleContentGlobs(ts, readFileSync(join(root, file), "utf8"), moves)
+    if (reason !== undefined) issues.push({ file, reason })
+  }
+  const gitignore = ignoreNifraState(root)
+  if (gitignore !== undefined) {
+    toolingWrites.set(".gitignore", gitignore)
+    tooling.push({ file: ".gitignore", change: "ignore .nifra/ (dev and build state)" })
+  }
+  // `nifra check` reads the declaration statically; without it, a later routes/ or config would zone the app.
+  const kind = api && createKindProbe(root)(root).kind === undefined ? declareApiKind(ts, root) : {}
+  if (kind.issue !== undefined) issues.push({ file: "package.json", reason: kind.issue })
+  if (kind.text !== undefined) {
+    toolingWrites.set("package.json", kind.text)
+    tooling.push({ file: "package.json", change: '"nifra": { "kind": "api" }' })
+  }
+
   if (options.write === true) {
+    for (const [file, text] of toolingWrites) writeFileSync(join(root, file), text)
     for (const [file, text] of final) {
       if (original.get(file) === text) continue
       const path = join(root, file)
       mkdirSync(dirname(path), { recursive: true })
       writeFileSync(path, text)
     }
+    const vacated: string[] = []
     for (const file of original.keys()) {
-      if (!final.has(file)) rmSync(join(root, file), { force: true })
+      if (final.has(file)) continue
+      rmSync(join(root, file), { force: true })
+      vacated.push(file)
     }
     for (const { from, to } of moves) {
       if (original.has(from) || !existsSync(join(root, from))) continue
       mkdirSync(dirname(join(root, to)), { recursive: true })
       renameSync(join(root, from), join(root, to))
+      vacated.push(from)
     }
-    pruneEmptyDirs(root)
+    pruneVacatedDirs(root, vacated)
   }
   return {
     ok: issues.length === 0,
     write: options.write === true,
+    mode,
     splits: splits.sort((a, b) => codeUnitOrder(a.file, b.file)),
     moves,
     rewritten: rewritten.sort(),
+    tooling,
     issues,
   }
 }
 
-function pruneEmptyDirs(root: string): void {
-  const prune = (dir: string): boolean => {
-    let empty = true
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) {
-        empty = false
-        continue
+/** The app's `"nifra": { "zones": ... }`, so folders it already zones are left where they are. */
+function appZones(root: string): ZoneConfig {
+  const manifest = join(root, "package.json")
+  if (!existsSync(manifest)) return {}
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(manifest, "utf8"))
+  } catch {
+    return {}
+  }
+  const nifra =
+    typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "nifra") : undefined
+  const zones =
+    typeof nifra === "object" && nifra !== null ? Reflect.get(nifra, "zones") : undefined
+  return zones === undefined ? {} : parseZoneConfig(zones, manifest)
+}
+
+/** Whether a tsconfig `include` entry takes in `file` (app-relative), the way tsc reads it. */
+function includes(pattern: string, file: string): boolean {
+  let spec = pattern.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/+$/, "")
+  if (spec === "" || spec === ".") return true
+  if (!/[*?]/.test(spec)) return file === spec || file.startsWith(`${spec}/`)
+  if (spec.endsWith("**")) spec = `${spec}/*`
+  else if (!/[*?.][^/]*$/.test(spec.slice(spec.lastIndexOf("/") + 1))) spec = `${spec}/**/*`
+  return new Bun.Glob(spec).match(file)
+}
+
+/**
+ * Add each zone folder that receives moved TypeScript to tsconfig `include`, editing only that array
+ * so comments and layout survive. A tsconfig without `include` (or with only `extends`) is left
+ * alone: tsc's default, or the base config, decides, and `nifra check` reports any folder left out.
+ */
+function coverMovedFiles(
+  ts: typeof TS,
+  root: string,
+  moves: ReadonlyArray<{ readonly from: string; readonly to: string }>,
+): { text?: string; added: string[]; issue?: string } | undefined {
+  const path = join(root, "tsconfig.json")
+  if (!existsSync(path)) return undefined
+  const text = readFileSync(path, "utf8")
+  const source = ts.parseJsonText(path, text)
+  const top = source.statements[0]?.expression
+  if (top === undefined || !ts.isObjectLiteralExpression(top))
+    return { added: [], issue: "is not a JSON object; add the zone folders to its include by hand" }
+  const include = jsonProperty(ts, top, "include")
+  if (include === undefined) return undefined
+  const array = include.initializer
+  if (!ts.isArrayLiteralExpression(array))
+    return { added: [], issue: '"include" is not an array; add the zone folders to it by hand' }
+  const patterns = array.elements.filter(ts.isStringLiteral).map((element) => element.text)
+  const added: string[] = []
+  for (const { to } of moves) {
+    if (!/\.(?:[cm]?ts|tsx)$/.test(to) || /\.d\.[cm]?ts$/.test(to)) continue
+    const folder = to.split("/")[0] ?? to
+    if (added.includes(folder) || patterns.some((pattern) => includes(pattern, to))) continue
+    added.push(folder)
+  }
+  if (added.length === 0) return undefined
+  added.sort(codeUnitOrder)
+  const quoted = added.map((folder) => JSON.stringify(folder))
+  const last = array.elements[array.elements.length - 1]
+  if (last === undefined) {
+    const at = array.getStart(source) + 1
+    return { text: `${text.slice(0, at)}${quoted.join(", ")}${text.slice(at)}`, added }
+  }
+  let at = last.end
+  const trailing = /^\s*,/.exec(text.slice(at))
+  if (trailing !== null) at += trailing[0].length
+  // A multi-line array gets one entry per line at the last element's indent, below any comment that
+  // closes the last element's line; anything else gets them inline.
+  if (text.slice(array.getStart(source), last.getStart(source)).includes("\n")) {
+    const lineStart = text.lastIndexOf("\n", last.getStart(source)) + 1
+    const indent = text.slice(lineStart, last.getStart(source)).match(/^\s*/)?.[0] ?? ""
+    const newline = text.indexOf("\n", at)
+    const eol = newline === -1 ? text.length : newline
+    if (/^\s*(?:\/\/.*|\/\*.*\*\/\s*)?$/.test(text.slice(at, eol))) {
+      const head =
+        trailing !== null
+          ? text.slice(0, eol)
+          : `${text.slice(0, last.end)},${text.slice(last.end, eol)}`
+      const entries = quoted.join(`,\n${indent}`)
+      return {
+        text: `${head}\n${indent}${entries}${trailing !== null ? "," : ""}${text.slice(eol)}`,
+        added,
       }
-      const full = join(dir, entry.name)
-      if (entry.isDirectory() ? !prune(full) : true) empty = false
     }
-    if (empty && dir !== root) rmSync(dir, { recursive: true, force: true })
-    return empty
   }
-  prune(root)
+  const insert = trailing !== null ? ` ${quoted.join(", ")},` : `, ${quoted.join(", ")}`
+  return { text: `${text.slice(0, at)}${insert}${text.slice(at)}`, added }
+}
+
+const jsonProperty = (
+  ts: typeof TS,
+  object: TS.ObjectLiteralExpression,
+  key: string,
+): TS.PropertyAssignment | undefined =>
+  object.properties.find(
+    (property): property is TS.PropertyAssignment =>
+      ts.isPropertyAssignment(property) &&
+      ts.isStringLiteral(property.name) &&
+      property.name.text === key,
+  )
+
+/** `text` with `entry` as the last property of `object`, on its own line when the object spans lines. */
+function insertProperty(
+  source: TS.JsonSourceFile,
+  text: string,
+  object: TS.ObjectLiteralExpression,
+  entry: string,
+): string {
+  const open = object.getStart(source)
+  const last = object.properties[object.properties.length - 1]
+  if (last === undefined) return `${text.slice(0, open)}{ ${entry} }${text.slice(object.end)}`
+  const start = last.getStart(source)
+  if (!text.slice(open, start).includes("\n")) {
+    return `${text.slice(0, last.end)}, ${entry}${text.slice(last.end)}`
+  }
+  const indent = /^[ \t]*/.exec(text.slice(text.lastIndexOf("\n", start) + 1, start))?.[0] ?? ""
+  return `${text.slice(0, last.end)},\n${indent}${entry}${text.slice(last.end)}`
+}
+
+/** The app's package.json with `"nifra": { "kind": "api" }` added, editing only where it goes. */
+function declareApiKind(ts: typeof TS, root: string): { text?: string; issue?: string } {
+  const path = join(root, "package.json")
+  if (!existsSync(path)) {
+    return {
+      issue:
+        'there is none in the app; declare "nifra": { "kind": "api" } in the package.json that governs it',
+    }
+  }
+  const text = readFileSync(path, "utf8")
+  const source = ts.parseJsonText(path, text)
+  const top = source.statements[0]?.expression
+  if (top === undefined || !ts.isObjectLiteralExpression(top))
+    return { issue: 'is not a JSON object; add "nifra": { "kind": "api" } to it by hand' }
+  const nifra = jsonProperty(ts, top, "nifra")
+  if (nifra === undefined) {
+    return { text: insertProperty(source, text, top, '"nifra": { "kind": "api" }') }
+  }
+  if (!ts.isObjectLiteralExpression(nifra.initializer))
+    return { issue: '"nifra" is not an object; add "kind": "api" to it by hand' }
+  return { text: insertProperty(source, text, nifra.initializer, '"kind": "api"') }
+}
+
+/** Tailwind `content` globs that matched a moved file at its old path and match nothing at its new one. */
+function staleContentGlobs(
+  ts: typeof TS,
+  text: string,
+  moves: ReadonlyArray<{ readonly from: string; readonly to: string }>,
+): string | undefined {
+  const globs: string[] = []
+  const source = ts.createSourceFile("tailwind.config.ts", text, ts.ScriptTarget.Latest, true)
+  const visit = (node: TS.Node): void => {
+    if (ts.isStringLiteralLike(node) && /[*/]/.test(node.text) && !node.text.startsWith("!"))
+      globs.push(node.text.replace(/^\.\//, ""))
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  const matchers = globs.map((glob) => ({ glob, matcher: new Bun.Glob(glob) }))
+  const lost = moves.filter(
+    ({ from, to }) =>
+      matchers.some(({ matcher }) => matcher.match(from)) &&
+      !matchers.some(({ matcher }) => matcher.match(to)),
+  )
+  const first = lost[0]
+  if (first === undefined) return undefined
+  const folders = [...new Set(lost.map(({ to }) => to.split("/")[0] ?? to))].sort(codeUnitOrder)
+  return `its content globs matched ${lost.length} file(s) that move, but none of their new paths (such as "${first.from}" -> "${first.to}"), so Tailwind would stop seeing their classes. Add globs for ${folders.map((folder) => `"./${folder}/**/*"`).join(", ")} (with the extensions you use)`
+}
+
+/**
+ * `.nifra/` holds generated types, dev state and the dev server's launch token; none of it belongs in
+ * git. The new `.gitignore` text when it is not ignored yet, else `undefined`.
+ */
+function ignoreNifraState(root: string): string | undefined {
+  let exitCode: number | null = null
+  try {
+    exitCode = Bun.spawnSync(["git", "check-ignore", "-q", ".nifra/types"], {
+      cwd: root,
+      stdout: "ignore",
+      stderr: "ignore",
+    }).exitCode
+  } catch {
+    // No git installed: the same as no checkout.
+  }
+  if (exitCode === 0) return undefined
+  const path = join(root, ".gitignore")
+  const current = existsSync(path) ? readFileSync(path, "utf8") : ""
+  // Outside a git checkout `check-ignore` cannot answer; the app's own file decides.
+  if (exitCode !== 1 && /^\/?\.nifra(?:\/|\*|\/\*\*)?\s*$/m.test(current)) return undefined
+  const separator = current === "" || current.endsWith("\n") ? "" : "\n"
+  return `${current}${separator}.nifra/\n`
+}
+
+/** Remove each directory the run emptied, then each parent that leaves empty. A directory that was
+ * empty before the run is the app's own, not the migration's to remove. */
+function pruneVacatedDirs(root: string, vacated: Iterable<string>): void {
+  const dirs = new Set<string>()
+  for (const file of vacated) dirs.add(dirname(join(root, file)))
+  // Deepest first, so a parent is judged after its emptied children are gone.
+  for (const start of [...dirs].sort((a, b) => b.length - a.length)) {
+    for (let dir = start; dir !== root && dir.startsWith(`${root}${sep}`); dir = dirname(dir)) {
+      if (!existsSync(dir) || readdirSync(dir).length > 0) break
+      rmdirSync(dir)
+    }
+  }
 }