@nifrajs/cli 4.0.0 → 5.0.0

package/dist/migrate-layout.js

@@ -8,19 +8,30 @@
  *   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, renameSync, rmSync, writeFileSync, } from "node:fs";
-import { dirname, extname, join, posix, relative, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+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 } from "@nifrajs/web/zones";
+import { BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE, retiredRootFiles } from "./app-files.js";
 import { codeUnitOrder } from "./internal/code-unit-order.js";
+import { createKindProbe, hasWebConfig } from "./internal/nifra-project.js";
+import { createSpecifierResolver } from "./internal/project-specifiers.js";
 import { importTypeScript } from "./internal/typescript-import.js";
 import { missingOutputSchemas } from "./rules/data-guard.js";
 /** Exports only the server or the build reads: `@nifrajs/web`'s route-pair contract. */
@@ -44,8 +55,27 @@ const LEGACY_SERVER = /\.server(\.(?:[cm]?[jt]sx?|svelte|vue|mdx))$/;
 const RETIRED_SPECIFIERS = {
     "@nifrajs/web/server-only": "@nifrajs/web/backend-only",
 };
+/** Scripts and config that name app files by path: scanned for paths that moved, never rewritten. */
+const TOOLING_FILE = /(?:\.(?:json|jsonc|ya?ml|toml|sh|bash|zsh|ps1)|(?:^|\/)(?:Dockerfile|Makefile|Procfile))$/;
+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 = 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$/;
 const toPosix = (path) => path.replaceAll("\\", "/");
 /** Every first-party file under `root`, app-relative and posix. */
 function listFiles(root) {
@@ -73,15 +103,34 @@ function bindingNames(ts, name, into) {
                 bindingNames(ts, element.name, into);
 }
 const hasModifier = (ts, node, kind) => (ts.canHaveModifiers(node) ? (ts.getModifiers(node) ?? []) : []).some((m) => m.kind === kind);
-/** 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, node) {
+/**
+ * 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, source) {
+    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) => 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, node, jsx) {
     const value = new Set();
     const type = new Set();
     const visit = (current, inType) => {
+        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;
@@ -111,6 +160,7 @@ function references(ts, node) {
     return { value, type };
 }
 function describeStatements(ts, sf) {
+    const jsx = jsxBindings(ts, sf.text);
     return sf.statements.map((node) => {
         const declares = new Set();
         const exports = new Map();
@@ -164,7 +214,7 @@ function describeStatements(ts, sf) {
         }
         const refs = ts.isImportDeclaration(node)
             ? { value: new Set(), type: new Set() }
-            : references(ts, node);
+            : references(ts, node, jsx);
         for (const name of declares) {
             refs.value.delete(name);
             refs.type.delete(name);
@@ -201,8 +251,10 @@ function filterImport(ts, sf, node, keep) {
         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, node) => node.getText(sf).endsWith(";") ? ";" : "";
 /** Rebuild `export { a, b as c }` keeping only the exported names `keep` accepts. */
 function filterExportList(ts, sf, node, keep) {
     const clause = node.exportClause;
@@ -213,7 +265,7 @@ function filterExportList(ts, sf, node, keep) {
         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) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const joinStatements = (texts) => {
@@ -368,7 +420,8 @@ export function splitRouteSource(ts, source, fileName, backendSpecifier) {
     }
     // After the other imports: the nearest relative path sorts last.
     if (typeImports.size > 0) {
-        frontendTexts.splice(afterImports, 0, `\nimport type { ${[...typeImports].sort().join(", ")} } from "${backendSpecifier}"`);
+        const semi = statements.some((info) => terminatorOf(sf, info.node) !== "") ? ";" : "";
+        frontendTexts.splice(afterImports, 0, `\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.
     const pragmas = (ts.getLeadingCommentRanges(source, 0) ?? [])
@@ -402,7 +455,7 @@ export function middlewareSource(ts, source, fileName) {
     // 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)) {
@@ -419,7 +472,8 @@ export function middlewareSource(ts, source, fileName) {
             }
             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`;
             }
         }
     }
@@ -467,6 +521,16 @@ function scriptBlocks(source) {
     }
     return blocks;
 }
+/** The path argument of `mock.module("./x", ...)` or a vitest/jest twin, when it is a literal. */
+function mockedSpecifier(ts, node) {
+    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, file, text) {
     if (/\.(?:svelte|vue)$/.test(file)) {
         return scriptBlocks(text).flatMap((block) => importsOf(ts, "block.ts", text.slice(block.start, block.end)));
@@ -516,6 +580,10 @@ function importsOf(ts, file, text) {
             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)) {
@@ -547,6 +615,107 @@ function resolveIn(files, from, specifier) {
     }
     return candidates.find((candidate) => files.has(candidate));
 }
+/** Where `text` spells, inside quotes, an import specifier that resolves among `files`: [start, end). */
+function liveSpecifierSpans(ts, file, text, files) {
+    const spans = [];
+    for (const { specifier } of importsOf(ts, file, text)) {
+        if (resolveIn(files, file, specifier) === undefined)
+            continue;
+        for (const quote of ['"', "'", "`"]) {
+            const quoted = `${quote}${specifier}${quote}`;
+            for (let at = text.indexOf(quoted); at !== -1; at = text.indexOf(quoted, at + 1))
+                spans.push([at + 1, at + 1 + specifier.length]);
+        }
+    }
+    return spans;
+}
+const OWN_DIR = new Set(["import.meta.dir", "import.meta.dirname", "__dirname"]);
+/**
+ * Re-point the paths a module moving from `from` to `to` builds from its own location, so each still
+ * reaches what it did: `join(import.meta.dir, "..", "x")` (or `resolve`), `import.meta.dir + "/../x"`,
+ * `` `${__dirname}/../x` `` and `new URL("../x", import.meta.url)`, each with literal segments. `locate`
+ * maps an app-relative target to where it ends up. Returns the new text and the first use of the
+ * module's location it could not follow.
+ */
+function rebaseOwnPaths(ts, from, to, text, locate) {
+    const sf = ts.createSourceFile(to, text, ts.ScriptTarget.Latest, true, to.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const edits = [];
+    const followed = [];
+    const isOwnDir = (node) => node !== undefined && OWN_DIR.has(node.getText(sf));
+    const isLiteral = (node) => node !== undefined && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node));
+    const quoted = (node, value) => {
+        const quote = node.getText(sf)[0] ?? '"';
+        return `${quote}${value}${quote}`;
+    };
+    // The path `relative` names from the module's old folder, named from its new folder.
+    const rebased = (relative) => {
+        const target = locate(posix.normalize(posix.join(posix.dirname(from), relative)));
+        const next = posix.relative(posix.dirname(to), target) || ".";
+        return relative.endsWith("/") && next !== "." ? `${next}/` : next;
+    };
+    const follow = (anchor, start, end, replacement) => {
+        followed.push([anchor.getStart(sf), anchor.getEnd()]);
+        if (text.slice(start, end) !== replacement)
+            edits.push({ start, end, text: replacement });
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node)) {
+            const [dir, ...parts] = node.arguments;
+            const callee = node.expression.getText(sf);
+            const first = parts[0];
+            const last = parts[parts.length - 1];
+            if (isOwnDir(dir) &&
+                /(?:^|\.)(?:join|resolve)$/.test(callee) &&
+                first !== undefined &&
+                last !== undefined &&
+                parts.every(isLiteral) &&
+                !(callee.endsWith("resolve") && parts.some((part) => part.text.startsWith("/")))) {
+                const next = rebased(posix.join(...parts.map((part) => part.text)));
+                const segments = parts.length === 1 ? [next] : next.split("/").filter((s) => s !== "");
+                const replacement = segments.map((segment) => quoted(first, segment)).join(", ");
+                follow(dir, first.getStart(sf), last.getEnd(), replacement);
+                return;
+            }
+        }
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind === ts.SyntaxKind.PlusToken &&
+            isOwnDir(node.left) &&
+            isLiteral(node.right) &&
+            node.right.text.startsWith("/")) {
+            const next = rebased(node.right.text.slice(1) || ".");
+            follow(node.left, node.right.getStart(sf), node.right.getEnd(), quoted(node.right, `/${next}`));
+            return;
+        }
+        if (ts.isTemplateExpression(node) && node.head.text === "" && node.templateSpans.length === 1) {
+            const span = node.templateSpans[0];
+            if (span !== undefined && isOwnDir(span.expression) && span.literal.text.startsWith("/")) {
+                const next = rebased(span.literal.text.slice(1) || ".");
+                const replacement = `\`\${${span.expression.getText(sf)}}/${next}\``;
+                follow(span.expression, node.getStart(sf), node.getEnd(), replacement);
+                return;
+            }
+        }
+        if (ts.isNewExpression(node) &&
+            node.expression.getText(sf) === "URL" &&
+            node.arguments?.length === 2 &&
+            node.arguments[1]?.getText(sf) === "import.meta.url") {
+            const path = node.arguments[0];
+            if (isLiteral(path) && !/^(?:\/|[a-z][a-z\d+.-]*:)/i.test(path.text)) {
+                const next = rebased(path.text);
+                const replacement = quoted(path, next.startsWith("..") ? next : `./${next}`);
+                follow(node.arguments[1], path.getStart(sf), path.getEnd(), replacement);
+                return;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    const unfollowed = [...text.matchAll(new RegExp(SELF_LOCATION.source, "g"))].find((match) => !followed.some(([start, end]) => start <= match.index && match.index < end))?.[0];
+    let next = text;
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+        next = next.slice(0, edit.start) + edit.text + next.slice(edit.end);
+    return { text: next, unfollowed };
+}
 /** Rewrite one relative specifier from `from`'s new location to `target`'s new location, keeping the
  * author's style: extension kept when written, dropped when not, `/index` collapsed when it was. */
 function respecify(original, oldTarget, newFrom, newTarget) {
@@ -578,6 +747,125 @@ function rebase(specifier, from, newFrom) {
     const rel = posix.relative(posix.dirname(newFrom), target);
     return rel.startsWith(".") ? rel : `./${rel}`;
 }
+/** `specifier` re-pointed from a split route to its backend half, in the author's extension style. */
+function backendSpecifier(specifier, route, backend, from) {
+    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, file, text, splitOf) {
+    const redirects = [];
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const edits = [];
+    const issues = [];
+    const mentioned = (split, pattern) => [...split.moved].filter((name) => pattern(escapeRegExp(name)).test(text)).sort();
+    const quoted = (names) => names.map((name) => `"${name}"`).join(", ");
+    const visit = (node) => {
+        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 = named.elements;
+            const isMoved = (el) => 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) => ` from ${quote}${specifier}${quote}${attributes}${terminatorOf(sf, node)}`;
+            const keyword = ts.isImportDeclaration(node)
+                ? `import ${clause?.isTypeOnly ? "type " : ""}`
+                : `export ${node.isTypeOnly ? "type " : ""}`;
+            const list = (names) => `{ ${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) {
+    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 = 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, file, text, rewrite) {
     const replace = (code, offset, out, kind) => {
         const sf = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true, kind);
@@ -598,6 +886,8 @@ function rewriteImports(ts, file, text, rewrite) {
                 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) {
@@ -697,20 +987,138 @@ function renameRetiredTypes(ts, file, text) {
 // ---------------------------------------------------------------------------------------------------
 // The migration
 // ---------------------------------------------------------------------------------------------------
-const ROOT_MOVES = {
-    "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) => !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"];
+/**
+ * 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, file, text) {
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const bare = (node) => {
+        let current = node;
+        while (current !== undefined &&
+            (ts.isAsExpression(current) ||
+                ts.isSatisfiesExpression(current) ||
+                ts.isParenthesizedExpression(current)))
+            current = current.expression;
+        return current;
+    };
+    const out = [];
+    const literal = (field, role, node) => {
+        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) => {
+    const parts = specifier.split("/");
+    return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? "");
+};
+const isRootScript = (file, rootMoves) => !file.includes("/") && SOURCE_FILE.test(file) && rootMoves[file] === undefined;
 const isTestFile = (file) => /(?:^|\/)(?: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, rootMoves) => 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, rootMoves) {
+    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) {
+    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, options = {}) {
     const ts = options.typescript ?? (await importTypeScript());
     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 = 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) => configured.some((folder) => file === folder || file.startsWith(`${folder}/`));
     const original = new Map();
     const everyFile = listFiles(root);
     for (const file of everyFile) {
@@ -726,7 +1134,7 @@ export async function migrateLayout(appRoot, options = {}) {
     // 1-2. Route halves and middleware.
     const backendHalves = new Map();
     for (const [file, text] of original) {
-        if (!file.startsWith("routes/") || file.includes(".backend."))
+        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");
@@ -776,14 +1184,101 @@ export async function migrateLayout(appRoot, options = {}) {
         next.set(file, existing === undefined ? text : mergeModules(ts, existing, text));
     }
     // 3-4. Zoning by runtime reachability, on the post-split graph.
-    for (const [from, to] of Object.entries(ROOT_MOVES))
+    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, specifier) => {
+        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, specifier) => resolveIn(known, file, specifier) ?? viaAlias(file, specifier);
+    const ownName = (() => {
+        try {
+            const name = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name;
+            return typeof name === "string" ? name : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const installed = new Map();
+    /** 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) => {
+        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();
+    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, file, resolve) => (specifier) => {
+        const route = resolve(specifier);
+        const split = route === undefined ? undefined : splitRoutes.get(route);
+        if (route === undefined || split === undefined)
+            return undefined;
+        const inBase = (path) => 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();
+    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();
-    for (const [file, text] of next) {
+    for (const [file, text] of api ? [] : next) {
         const refs = [];
+        const reported = new Set();
         for (const ref of importsOf(ts, file, text)) {
             if (ref.specifier === "@nifrajs/web/plugins/vite-server-only") {
                 issues.push({
@@ -791,18 +1286,43 @@ export async function migrateLayout(appRoot, options = {}) {
                     reason: "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 reach = (roots) => {
+    // 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) => 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.filter((f) => !browserEntries.has(f)));
+    const reach = (roots, stopAt) => {
         const seen = new Set();
         const queue = [...roots];
         while (queue.length > 0) {
@@ -810,25 +1330,31 @@ export async function migrateLayout(appRoot, options = {}) {
             if (seen.has(file))
                 continue;
             seen.add(file);
+            if (stopAt?.has(file))
+                continue;
             for (const edge of edges.get(file) ?? [])
                 if (!edge.typeOnly)
                     queue.push(edge.target);
         }
         return seen;
     };
-    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."));
-    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);
+    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));
+    const appServer = reach(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("/");
@@ -844,11 +1370,12 @@ export async function migrateLayout(appRoot, options = {}) {
         }
     }
     const zoneOf = (file) => 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;
@@ -859,7 +1386,16 @@ export async function migrateLayout(appRoot, options = {}) {
         }
         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();
     for (const [from, to] of moveMap) {
@@ -886,37 +1422,181 @@ export async function migrateLayout(appRoot, options = {}) {
     const newPath = (file) => moveMap.get(file) ?? file;
     const final = new Map();
     const rewritten = [];
+    const unspelled = new Set();
+    /** An alias for a target that moves, through the same alias, or an issue when none covers it. */
+    const respellAlias = (file, specifier, target) => {
+        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)
+        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 = [];
+        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]
+        .map(([from, to]) => ({ from, to }))
+        .sort((a, b) => codeUnitOrder(a.from, b.from));
+    // A moved module's paths from its own location now start from its new folder: re-point the ones it
+    // spells out, and report the first one it cannot follow.
+    const unfollowed = new Map();
+    for (const { from, to } of moves) {
+        const text = final.get(to);
+        if (text === undefined || !SELF_LOCATION.test(text))
+            continue;
+        if (!/\.[cm]?[jt]sx?$/.test(to)) {
+            unfollowed.set(to, SELF_LOCATION.exec(text)?.[0] ?? "");
+            continue;
+        }
+        const result = rebaseOwnPaths(ts, from, to, text, (target) => known.has(target) ? newPath(target) : target);
+        final.set(to, result.text);
+        if (result.unfollowed !== undefined)
+            unfollowed.set(to, result.unfollowed);
+    }
     // A path in a string or comment is not an import, so nothing above rewrote it: a build script that
-    // writes `data/x.json` would keep writing to the old place.
-    for (const [file, text] of final) {
+    // writes `data/x.json` would keep writing to the old place, and so would a deploy script or
+    // `package.json` beside the code.
+    const settled = new Set([...known].map(newPath));
+    const scanned = [...final];
+    for (const file of everyFile) {
+        if (!original.has(file) &&
+            TOOLING_FILE.test(file) &&
+            statSync(join(root, file)).size <= 256_000)
+            scanned.push([newPath(file), readFileSync(join(root, file), "utf8")]);
+    }
+    for (const [file, text] of scanned) {
+        let live;
         for (const [from, to] of moveMap) {
             // `shared/lib/x.ts` contains `lib/x.ts`; that is the new path, not a stale one.
             const newPrefix = to.endsWith(from) ? to.slice(0, to.length - from.length) : undefined;
             const stale = [
                 ...text.matchAll(new RegExp(`(?<![\\w.-])${escapeRegExp(from)}(?![\\w])`, "g")),
-            ].some((match) => newPrefix === undefined || !text.slice(0, match.index).endsWith(newPrefix));
+            ].some((match) => {
+                if (newPrefix !== undefined && text.slice(0, match.index).endsWith(newPrefix))
+                    return false;
+                // An import that resolves after the moves is current, even when it still reads like the old
+                // path: `./x.json` from a module that moved together with `x.json`.
+                live ??= liveSpecifierSpans(ts, file, text, settled);
+                const end = match.index + from.length;
+                return !live.some(([start, stop]) => start <= match.index && end <= stop);
+            });
             if (stale)
                 issues.push({ file, reason: `mentions "${from}" by path; it moved to "${to}"` });
         }
     }
+    // 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, specifier) => 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();
+    for (const move of moves) {
+        const own = unfollowed.get(move.to);
+        if (own !== undefined) {
+            issues.push({
+                file: move.to,
+                reason: `builds a path from its own location (${own}) that the migration could not re-point, and it moved from "${move.from}"; check that path by hand`,
+            });
+        }
+        const dir = posix.dirname(move.from);
+        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) {
+        const staying = files.filter((f) => posix.dirname(f) === dir && !moveMap.has(f) && !isTestFile(f) && !f.endsWith(".d.ts"));
+        const first = group[0];
+        if (staying.length === 0 || first === undefined)
+            continue;
+        const others = group.length === 1 ? "" : ` with ${group.length - 1} other file(s)`;
+        const left = staying.length === 1
+            ? `"${staying[0]}" stays`
+            : `${staying.length} files such as "${staying[0]}" stay`;
+        issues.push({
+            file: first.from,
+            reason: `moves to "${first.to}"${others} but ${left} in ${dir}/; code or tooling that lists ${dir}/ no longer finds what moved - move the folder together by hand`,
+        });
+    }
     // The server refuses data a loader or action returns without an output schema; only the author
     // knows which fields the browser may see.
     for (const [file, text] of final) {
@@ -925,14 +1605,43 @@ export async function migrateLayout(appRoot, options = {}) {
         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`,
             });
         }
     }
-    const moves = [...moveMap]
-        .map(([from, to]) => ({ from, to }))
-        .sort((a, b) => codeUnitOrder(a.from, b.from));
+    // Tooling that lists folders or globs, not files: the import rewrite above never sees it.
+    const tooling = [];
+    const toolingWrites = new Map();
+    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;
@@ -940,43 +1649,221 @@ export async function migrateLayout(appRoot, options = {}) {
             mkdirSync(dirname(path), { recursive: true });
             writeFileSync(path, text);
         }
+        const vacated = [];
         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) {
-    const prune = (dir) => {
-        let empty = true;
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) {
-                empty = false;
-                continue;
-            }
-            const full = join(dir, entry.name);
-            if (entry.isDirectory() ? !prune(full) : true)
-                empty = false;
+/** The app's `"nifra": { "zones": ... }`, so folders it already zones are left where they are. */
+function appZones(root) {
+    const manifest = join(root, "package.json");
+    if (!existsSync(manifest))
+        return {};
+    let parsed;
+    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, file) {
+    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, root, moves) {
+    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 = [];
+    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,
+            };
         }
-        if (empty && dir !== root)
-            rmSync(dir, { recursive: true, force: true });
-        return empty;
+    }
+    const insert = trailing !== null ? ` ${quoted.join(", ")},` : `, ${quoted.join(", ")}`;
+    return { text: `${text.slice(0, at)}${insert}${text.slice(at)}`, added };
+}
+const jsonProperty = (ts, object, key) => object.properties.find((property) => 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, text, object, entry) {
+    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, root) {
+    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, text, moves) {
+    const globs = [];
+    const source = ts.createSourceFile("tailwind.config.ts", text, ts.ScriptTarget.Latest, true);
+    const visit = (node) => {
+        if (ts.isStringLiteralLike(node) && /[*/]/.test(node.text) && !node.text.startsWith("!"))
+            globs.push(node.text.replace(/^\.\//, ""));
+        ts.forEachChild(node, visit);
     };
-    prune(root);
+    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) {
+    let exitCode = 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, vacated) {
+    const dirs = new Set();
+    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);
+        }
+    }
 }
 //# sourceMappingURL=migrate-layout.js.map