@mozole/cli 1.4.0 → 1.4.1

package/dist/commands/adopt.js

@@ -1,4 +1,4 @@
-import { access, copyFile, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { access, copyFile, lstat, mkdir, mkdtemp, readdir, readFile, rename, rm, rmdir, writeFile, } from "node:fs/promises";
 import path from "node:path";
 import { readConfig } from "../config/project.js";
 import { cceCommand, initializeCce, requireCceRuntime, } from "../context/cce.js";
@@ -6,6 +6,9 @@ import { assertAntigravityMcpMergeable, cceMcpServer, configureAntigravityMcp, m
 import { npmExecutable } from "../platform/executable.js";
 import { run } from "../platform/process.js";
 import { TaskProgress } from "../progress.js";
+import { canonicalPlan, safeRead, } from "../scaffold/adoption.js";
+import { detectRoutes } from "../scaffold/routes.js";
+import { basicAgentGuide } from "../scaffold/standalone.js";
 import { projectConfig, projectTemplates } from "../scaffold/templates.js";
 import { writeFiles } from "../scaffold/write.js";
 import { TOOLCHAIN } from "../version.js";
@@ -28,7 +31,9 @@ async function restoreFiles(snapshots) {
             continue;
         }
         await mkdir(path.dirname(file), { recursive: true });
-        await writeFiles(path.dirname(file), { [path.basename(file)]: contents.toString("utf8") }, true);
+        const temporary = `${file}.${process.pid}.tmp`;
+        await writeFile(temporary, contents);
+        await rename(temporary, file);
     }
 }
 function adoptionMutationFiles(root) {
@@ -40,6 +45,7 @@ function adoptionMutationFiles(root) {
         ".gitignore",
         "AGENTS.md",
         "CLAUDE.md",
+        "docs/design/README.md",
         ".mcp.json",
         ".context-engine.yaml",
         "vitest.config.ts",
@@ -75,39 +81,21 @@ async function atomicJson(file, value) {
     await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
     await rename(temporary, file);
 }
-export function detectRoutes(source) {
-    const routes = ["/"];
-    for (const match of source.matchAll(/route\(\s*["']([^"']+)["']/g))
-        routes.push(`/${match[1]}`.replaceAll("//", "/"));
-    return [...new Set(routes)];
-}
-async function ensureAgentBlock(file, block) {
-    const begin = "<!-- mozole:begin -->";
-    if (!(await exists(file))) {
-        await writeFiles(path.dirname(file), { [path.basename(file)]: `${block.trim()}\n` }, true);
-        return true;
-    }
-    const current = await readFile(file, "utf8");
-    if (current.includes(begin)) {
-        const end = "<!-- mozole:end -->";
-        const start = current.indexOf(begin);
-        const finish = current.indexOf(end, start);
-        if (finish < 0)
-            throw new Error(`Unclosed Mozole instruction block in ${file}`);
-        const next = current.slice(0, start) +
-            block.trim() +
-            current.slice(finish + end.length);
-        if (next === current)
-            return false;
-        await writeFiles(path.dirname(file), { [path.basename(file)]: next }, true);
-        return true;
-    }
-    await writeFiles(path.dirname(file), { [path.basename(file)]: `${current.trimEnd()}\n\n${block.trim()}\n` }, true);
-    return true;
-}
+export { detectRoutes } from "../scaffold/routes.js";
 async function ensureGitignore(root, optimized = true) {
     const file = path.join(root, ".gitignore");
-    const current = (await exists(file)) ? await readFile(file, "utf8") : "";
+    const original = (await exists(file)) ? await readFile(file, "utf8") : "";
+    const current = optimized
+        ? original
+        : original
+            .split(/\r?\n/)
+            .filter((line) => ![
+            ".cce/",
+            "/.cce/",
+            ".mozole/state/",
+            ".mozole/telemetry.json",
+        ].includes(line.trim()))
+            .join("\n");
     const required = [
         "dist/",
         "build/",
@@ -118,10 +106,10 @@ async function ensureGitignore(root, optimized = true) {
     ];
     const existing = new Set(current.split(/\r?\n/).map((line) => line.trim()));
     const missing = required.filter((line) => !existing.has(line));
-    if (!missing.length)
+    if (!missing.length && current === original)
         return;
     await writeFiles(root, {
-        ".gitignore": `${current.trimEnd()}${current.trim() ? "\n\n" : ""}# Mozole local files\n${missing.join("\n")}\n`,
+        ".gitignore": `${current.trimEnd()}${missing.length ? `${current.trim() ? "\n\n" : ""}# Mozole local files\n${missing.join("\n")}` : ""}\n`,
     }, true);
 }
 async function ensureBiomeConfig(root, defaultTemplate, optimized = true) {
@@ -147,7 +135,22 @@ async function ensureBiomeConfig(root, defaultTemplate, optimized = true) {
         const content = await readFile(file, "utf8");
         const config = JSON.parse(content);
         if (!config || typeof config !== "object")
-            return;
+            throw new Error("biome.json must contain an object");
+        config.$schema = JSON.parse(defaultTemplate).$schema;
+        if (Array.isArray(config.files?.ignore)) {
+            config.files.includes = [
+                ...(config.files.includes ?? ["**"]),
+                ...config.files.ignore.map((pattern) => pattern.startsWith("!") ? pattern : `!${pattern}`),
+            ];
+            delete config.files.ignore;
+        }
+        if (!optimized && Array.isArray(config.files?.includes))
+            config.files.includes = config.files.includes.filter((pattern) => ![
+                "!.cce",
+                "!.cce/**",
+                "!.mozole/state",
+                "!.mozole/telemetry.json",
+            ].includes(pattern));
         if (!config.files || typeof config.files !== "object") {
             config.files = {
                 includes: ["**", ...requiredIgnores],
@@ -161,34 +164,13 @@ async function ensureBiomeConfig(root, defaultTemplate, optimized = true) {
                 }
             }
         }
-        else if (Array.isArray(config.files.ignore)) {
-            const cleanPatterns = [
-                "build",
-                "dist",
-                "deploy",
-                ".react-router",
-                "node_modules",
-                "coverage",
-                ".mozole",
-                ...(optimized ? [".cce"] : []),
-                "public",
-                "assets",
-                "qa-screenshots",
-            ];
-            const existing = new Set(config.files.ignore);
-            for (const pattern of cleanPatterns) {
-                if (!existing.has(pattern) && !existing.has(`!${pattern}`)) {
-                    config.files.ignore.push(pattern);
-                }
-            }
-        }
         else {
             config.files.includes = ["**", ...requiredIgnores];
         }
         await atomicJson(file, config);
     }
-    catch {
-        // If parsing fails, preserve existing file
+    catch (error) {
+        throw new Error(`Cannot migrate biome.json: ${String(error)}`);
     }
 }
 async function validateJsonObject(file) {
@@ -234,7 +216,7 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
     }
     const root = path.resolve(cwd, input);
     if (!options.cceInstall)
-        return adoptPlain(root, output);
+        return adoptPlain(root, output, options);
     const packagePath = path.join(root, "package.json");
     const progress = new TaskProgress({
         total: 5,
@@ -248,9 +230,11 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
     process.once("SIGINT", abort);
     process.once("SIGTERM", abort);
     let snapshots;
+    let movedDirectories = [];
     try {
         progress.step("Analyzing project structure and package metadata");
         progress.logVerbose(`Reading package.json from ${packagePath}`);
+        await validateManagedPaths(root);
         const original = await readFile(packagePath, "utf8");
         const packageJson = JSON.parse(original);
         await assertAntigravityMcpMergeable(root);
@@ -262,7 +246,7 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
             (!allDependencies.vite && !allDependencies["@react-router/dev"]))
             throw new Error("Expected a React project using Vite or React Router Framework Mode.");
         const name = packageJson.name ?? path.basename(root);
-        const templates = projectTemplates(name, { scaffold: false });
+        let templates = projectTemplates(name, { scaffold: false });
         const codexHooksPath = path.join(root, ".codex", "hooks.json");
         const claudeSettingsPath = path.join(root, ".claude", "settings.json");
         const hadCodexHooks = await validateJsonObject(codexHooksPath);
@@ -278,18 +262,41 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
                 }
             })()
             : projectConfig(name, { scaffold: false });
+        const wasManaged = await exists(configPath);
+        if (!config.backend && (await exists(path.join(root, "api/index.php"))))
+            config.backend = projectConfig(name, { backend: true }).backend;
+        templates = projectTemplates(name, {
+            scaffold: false,
+            backend: Boolean(config.backend),
+        });
+        adaptFrameworkGuide(templates, Boolean(allDependencies["@react-router/dev"]));
+        const migration = await canonicalPlan(root, templates, true, wasManaged, name, knownGuides(name));
         config.name = name;
+        for (const key of Object.keys(config))
+            if (![
+                "schemaVersion",
+                "name",
+                "mode",
+                "framework",
+                "routes",
+                "backend",
+                "qa",
+                "cce",
+                "governor",
+                "telemetry",
+                "verifiers",
+            ].includes(key))
+                delete config[key];
         const optimized = projectConfig(name, { scaffold: false });
         config.mode = "optimized";
         if (!optimized.cce || !optimized.governor || !optimized.telemetry)
             throw new Error("Missing optimized defaults");
-        config.cce ??= optimized.cce;
-        config.governor ??= optimized.governor;
-        config.telemetry ??= optimized.telemetry;
-        if (config.governor?.enabled) {
-            config.governor.mode = "enforce";
-            config.governor.hooks = { codex: true, claude: true };
-        }
+        config.cce = {
+            ...optimized.cce,
+            initialized: config.cce?.initialized ?? false,
+        };
+        config.governor = optimized.governor;
+        config.telemetry = optimized.telemetry;
         progress.step("Verifying CCE runtime availability");
         const cceRequired = process.env.MOZOLE_SKIP_CCE !== "1" && config.cce?.enabled;
         const cce = cceRequired
@@ -297,14 +304,25 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
             : await cceCommand();
         const cceLauncher = cce?.prefix.length ? "uvx" : "cce";
         progress.logVerbose(`CCE runtime: launcher=${cceLauncher}`);
-        snapshots = await snapshotFiles(adoptionMutationFiles(root));
+        snapshots = await snapshotFiles([
+            ...new Set([
+                ...adoptionMutationFiles(root),
+                ...Object.keys(migration.writes).map((f) => path.join(root, f)),
+                ...migration.removes.map((f) => path.join(root, f)),
+            ]),
+        ]);
         const routeSourcePath = path.join(root, "app", "routes.ts");
         if (await exists(routeSourcePath))
             config.routes = detectRoutes(await readFile(routeSourcePath, "utf8"));
         const desiredScripts = {
             lint: "biome check .",
             format: "biome format --write .",
-            typecheck: packageJson.scripts?.typecheck ?? "tsc --noEmit",
+            typecheck: !packageJson.scripts?.typecheck ||
+                packageJson.scripts.typecheck === "tsc --noEmit"
+                ? allDependencies["@react-router/dev"]
+                    ? "react-router typegen && tsc --noEmit"
+                    : "tsc --noEmit"
+                : packageJson.scripts.typecheck,
             "test:run": packageJson.scripts?.["test:run"] ?? "vitest run",
             verify: "mozole verify",
             "verify:force": "mozole verify --force",
@@ -324,6 +342,10 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
             "qa:interactive": "mozole qa --interactive",
             "qa:visual": "mozole qa --visual",
         };
+        next.scripts.typecheck = desiredScripts.typecheck;
+        if (config.backend)
+            for (const key of ["check:php", "build:deploy", "dev:api"])
+                next.scripts[key] = JSON.parse(required(templates, "package.json")).scripts[key];
         next.devDependencies = {
             "@mozole/cli": process.env.MOZOLE_CLI_SPEC ?? TOOLCHAIN.mozoleCli,
             "@playwright/test": packageJson.devDependencies?.["@playwright/test"] ??
@@ -342,6 +364,21 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
             vitest: packageJson.devDependencies?.vitest ?? TOOLCHAIN.vitest,
             ...packageJson.devDependencies,
         };
+        const generatedPackage = JSON.parse(required(templates, "package.json"));
+        for (const key of [
+            "@mozole/cli",
+            "@biomejs/biome",
+            "@testing-library/jest-dom",
+            "@testing-library/react",
+            "@testing-library/user-event",
+            "@vitejs/plugin-react",
+            "jsdom",
+            "typescript",
+            "vitest",
+        ])
+            next.devDependencies[key] = required(generatedPackage.devDependencies, key);
+        if (next.dependencies)
+            delete next.dependencies["@mozole/cli"];
         const nextText = `${JSON.stringify(next, null, 2)}\n`;
         const packageChanged = nextText !== original;
         if (packageChanged) {
@@ -361,6 +398,7 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
         await atomicJson(configPath, config);
         await writeFiles(root, {
             ".mozole/toolchain.json": template(".mozole/toolchain.json"),
+            "docs/design/README.md": template("docs/design/README.md"),
             ".context-engine.yaml": template(".context-engine.yaml"),
             "vitest.config.ts": template("vitest.config.ts"),
             "tests/setup.ts": template("tests/setup.ts"),
@@ -389,12 +427,10 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
             await mergeHookConfig(codexHooksPath, template(".codex/hooks.json"), path.join(backupDir, "codex-hooks.json.before-adopt"));
         if (hadClaudeSettings)
             await mergeHookConfig(claudeSettingsPath, template(".claude/settings.json"), path.join(backupDir, "claude-settings.json.before-adopt"));
-        const block = "<!-- mozole:begin -->\n## Mandatory Mozole CCE contract\n\nRepository reads are forbidden by default. Allowed retrieval order: (1) CCE `context_search`; (2) additional CCE search, `expand_chunk`, or `related_context`; (3) bounded line-range read only when CCE output is insufficient; (4) full-file read only after explicit escalation. Editing a file is NOT sufficient justification for reading it in full. If CCE is unavailable, stop and report the blocker instead of falling back to repository reads. Routine browser validation uses screenshot-free `mozole qa`; visual QA requires an explicit user request or confirmed deterministic failure. Stop after requested work, `mozole verify`, and relevant routine QA pass.\n<!-- mozole:end -->";
-        await ensureAgentBlock(path.join(root, "AGENTS.md"), block);
-        await ensureAgentBlock(path.join(root, "CLAUDE.md"), `<!-- mozole:begin -->\n@AGENTS.md\n\n## Claude Code CCE contract\n\nRepository reads are forbidden by default. Use \`context_search\`, then additional CCE retrieval. Read may use a bounded line range only when CCE is insufficient; a full-file Read requires explicit escalation. Editing is not justification. If CCE is unavailable, report the blocker; do not fall back.\n<!-- mozole:end -->`);
         await ensureGitignore(root);
+        movedDirectories = await applyCanonicalPlan(root, migration, snapshots);
         progress.step("Installing missing dependencies & toolchain packages");
-        if (packageChanged && process.env.MOZOLE_SKIP_INSTALL !== "1") {
+        if (process.env.MOZOLE_SKIP_INSTALL !== "1") {
             progress.logVerbose("Running npm install for adopted project");
             const installed = await run(npmExecutable(), ["install", "--no-fund", "--no-audit"], {
                 cwd: root,
@@ -415,16 +451,6 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
                 if (browser.exitCode !== 0)
                     throw new Error("Chromium installation failed; package.json backup is in .mozole/backups/.");
             }
-            try {
-                progress.logVerbose("Formatting adopted project with Biome");
-                await run(npmExecutable(), ["run", "format"], {
-                    cwd: root,
-                    timeoutMs: 60_000,
-                    signal: controller.signal,
-                    logFile: path.join(root, ".mozole", "logs", "biome-format.log"),
-                });
-            }
-            catch { }
         }
         progress.step("Initializing CCE index and project configuration");
         if (cceRequired && !config.cce?.initialized) {
@@ -446,7 +472,7 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
         if (controller.signal.aborted)
             throw new Error("Adoption cancelled.");
         progress.done(`Adopted ${name}`);
-        output.log(`ADOPT PASS\n\n${root}\nApplication code preserved.${packageChanged ? "\npackage.json backup: .mozole/backups/package.json.before-adopt" : "\nAlready up to date."}`);
+        output.log(`ADOPT PASS\n\n${root}\nApplication code preserved.${migrationSummary(migration)}`);
         return 0;
     }
     catch (error) {
@@ -454,6 +480,7 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
         let rollbackFailure;
         if (snapshots)
             try {
+                await restoreDirectories(movedDirectories);
                 await restoreFiles(snapshots);
             }
             catch (rollbackError) {
@@ -471,9 +498,23 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
     }
 }
 /** Plain adoption never probes or installs agent runtimes. Existing user integrations are preserved. */
-async function adoptPlain(root, output) {
+async function adoptPlain(root, output, options) {
     let snapshots;
+    let movedDirectories = [];
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    const progress = new TaskProgress({
+        total: 3,
+        title: "Adopt",
+        output,
+        verbose: options.verbose,
+        onUpdate: options.onProgress,
+    });
     try {
+        progress.step("Inspecting project and planning canonical migration");
+        await validateManagedPaths(root);
         const packagePath = path.join(root, "package.json");
         const pkg = JSON.parse(await readFile(packagePath, "utf8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
@@ -484,26 +525,45 @@ async function adoptPlain(root, output) {
         const config = (await exists(configPath))
             ? await readConfig(root)
             : projectConfig(name);
-        if (config.cce?.enabled || config.governor?.enabled)
-            throw new Error("This project already has explicitly enabled integrations. Use --cce-install to update them; plain adoption will not silently remove existing integrations.");
+        const wasManaged = await exists(configPath);
+        if (!config.backend && (await exists(path.join(root, "api/index.php"))))
+            config.backend = projectConfig(name, { backend: true }).backend;
         delete config.cce;
         delete config.governor;
         delete config.telemetry;
         config.mode = "scaffold";
         config.name = name;
+        for (const key of Object.keys(config))
+            if (![
+                "schemaVersion",
+                "name",
+                "mode",
+                "framework",
+                "routes",
+                "backend",
+                "qa",
+                "cce",
+                "governor",
+                "telemetry",
+                "verifiers",
+            ].includes(key))
+                delete config[key];
         const templates = projectTemplates(name, {
             backend: Boolean(config.backend?.enabled),
         });
+        adaptFrameworkGuide(templates, Boolean(deps["@react-router/dev"]));
+        const migration = await canonicalPlan(root, templates, false, wasManaged, name, knownGuides(name));
         const generated = JSON.parse(templates["package.json"] ?? "{}");
         const routeFile = path.join(root, "app", "routes.ts");
         if (await exists(routeFile))
             config.routes = detectRoutes(await readFile(routeFile, "utf8"));
-        else
+        else if (!wasManaged)
             config.routes = ["/"];
         const files = {
             ".mozole/project.json": `${JSON.stringify(config, null, 2)}\n`,
             ".mozole/toolchain.json": required(templates, ".mozole/toolchain.json"),
             "scripts/qa.mjs": required(templates, "scripts/qa.mjs"),
+            "docs/design/README.md": required(templates, "docs/design/README.md"),
             "vitest.config.ts": required(templates, "vitest.config.ts"),
             "tests/setup.ts": required(templates, "tests/setup.ts"),
             ...(config.backend?.enabled
@@ -516,9 +576,12 @@ async function adoptPlain(root, output) {
         snapshots = await snapshotFiles([
             ...new Set([
                 ...adoptionMutationFiles(root),
+                ...Object.keys(migration.writes).map((file) => path.join(root, file)),
+                ...migration.removes.map((file) => path.join(root, file)),
                 ...Object.keys(files).map((file) => path.join(root, file)),
             ]),
         ]);
+        progress.step("Updating project scripts and managed files");
         const next = structuredClone(pkg);
         next.scripts = {
             lint: required(generated.scripts, "lint"),
@@ -527,6 +590,10 @@ async function adoptPlain(root, output) {
             "test:run": "vitest run",
             ...pkg.scripts,
         };
+        if (!pkg.scripts?.typecheck || pkg.scripts.typecheck === "tsc --noEmit")
+            next.scripts.typecheck = deps["@react-router/dev"]
+                ? "react-router typegen && tsc --noEmit"
+                : "tsc --noEmit";
         for (const key of [
             "verify",
             "verify:force",
@@ -538,7 +605,11 @@ async function adoptPlain(root, output) {
             next.scripts[key] = required(generated.scripts, key);
         if (config.backend?.enabled)
             for (const key of ["check:php", "build:deploy", "dev:api"])
-                next.scripts[key] ??= required(generated.scripts, key);
+                next.scripts[key] = required(generated.scripts, key);
+        for (const [key, command] of Object.entries(next.scripts)) {
+            if (/^(?:npx(?: --no-install)? )?mozole\s/.test(command))
+                delete next.scripts[key];
+        }
         next.devDependencies = { ...pkg.devDependencies };
         delete next.devDependencies["@mozole/cli"];
         if (next.dependencies)
@@ -554,7 +625,7 @@ async function adoptPlain(root, output) {
             "vitest",
             "playwright",
         ])
-            next.devDependencies[key] ??= required(generated.devDependencies, key);
+            next.devDependencies[key] = required(generated.devDependencies, key);
         const changed = JSON.stringify(next) !== JSON.stringify(pkg);
         if (changed) {
             await atomicJson(path.join(root, ".mozole", "backups", "package.json.before-adopt"), pkg);
@@ -564,13 +635,10 @@ async function adoptPlain(root, output) {
         await atomicJson(configPath, config);
         await atomicJson(path.join(root, ".mozole/toolchain.json"), JSON.parse(required(templates, ".mozole/toolchain.json")));
         await ensureBiomeConfig(root, required(templates, "biome.json"), false);
-        let guide = required(templates, "AGENTS.md").trim();
-        if (!deps["@react-router/dev"])
-            guide = guide.replace("React Router and Vite source is in `app/`; routes are declared in `app/routes.ts`. Production HTML and assets are in `build/client/`.", "This is an existing React + Vite project. Preserve its source layout and routing conventions. The project's build script defines production output.");
-        await ensureAgentBlock(path.join(root, "AGENTS.md"), `<!-- mozole:begin -->\n${guide}\n<!-- mozole:end -->`);
-        await ensureAgentBlock(path.join(root, "CLAUDE.md"), "<!-- mozole:begin -->\n@AGENTS.md\n<!-- mozole:end -->");
         await ensureGitignore(root, false);
-        if (changed && process.env.MOZOLE_SKIP_INSTALL !== "1") {
+        movedDirectories = await applyCanonicalPlan(root, migration, snapshots);
+        progress.step("Synchronizing installed dependencies and finalizing migration");
+        if (process.env.MOZOLE_SKIP_INSTALL !== "1") {
             for (const args of [
                 ["install", "--no-fund", "--no-audit"],
                 ...(process.env.MOZOLE_SKIP_BROWSER === "1"
@@ -580,20 +648,35 @@ async function adoptPlain(root, output) {
                 const result = await run(npmExecutable(), args, {
                     cwd: root,
                     timeoutMs: 600_000,
+                    signal: controller.signal,
                     logFile: path.join(root, ".mozole", "logs", "adopt-install.log"),
                 });
                 if (result.exitCode !== 0)
                     throw new Error("Dependency setup failed. See .mozole/logs/adopt-install.log");
             }
         }
-        output.log(`ADOPT PASS\n\n${root}\nApplication code preserved.`);
+        controller.signal.throwIfAborted();
+        progress.done();
+        output.log(`ADOPT PASS\n\n${root}\nCurrent scaffold system installed. Application code preserved.${migrationSummary(migration)}`);
         return 0;
     }
     catch (error) {
-        if (snapshots)
-            await restoreFiles(snapshots);
-        output.error(`ADOPT FAIL\n\n${error instanceof Error ? error.message : String(error)}\nManaged project files restored.`);
-        return 1;
+        progress.done();
+        let rollbackFailure = "";
+        try {
+            await restoreDirectories(movedDirectories);
+            if (snapshots)
+                await restoreFiles(snapshots);
+        }
+        catch (failure) {
+            rollbackFailure = `\nRollback failed: ${String(failure)}`;
+        }
+        output.error(`ADOPT FAIL\n\n${error instanceof Error ? error.message : String(error)}${rollbackFailure || "\nManaged project files restored."}\nIf installation started, rerun npm install to reconcile node_modules.`);
+        return controller.signal.aborted ? 130 : 1;
+    }
+    finally {
+        process.removeListener("SIGINT", abort);
+        process.removeListener("SIGTERM", abort);
     }
 }
 function required(values, key) {
@@ -602,4 +685,131 @@ function required(values, key) {
         throw new Error(`Missing template value: ${key}`);
     return value;
 }
+function knownGuides(name) {
+    const known = { "AGENTS.md": [], "CLAUDE.md": [] };
+    for (const scaffold of [true, false])
+        for (const backend of [true, false]) {
+            const files = projectTemplates(name, { scaffold, backend });
+            for (const file of Object.keys(known))
+                known[file]?.push(required(files, file));
+        }
+    for (const backend of [true, false])
+        known["AGENTS.md"]?.push(basicAgentGuide(backend).split("## Design implementation guardrails")[0] ?? "");
+    return known;
+}
+function adaptFrameworkGuide(templates, reactRouter) {
+    if (reactRouter)
+        return;
+    const replacement = "This is an existing React + Vite project. Preserve its source layout and routing conventions. The project's build script defines production output.";
+    templates["AGENTS.md"] = required(templates, "AGENTS.md")
+        .replace("React Router and Vite source is in `app/`; routes are declared in `app/routes.ts`. Production HTML and assets are in `build/client/`.", replacement)
+        .replace("React Router Framework Mode lives in `app/`; routes are in `app/routes.ts`; static output is `build/client/`.", replacement);
+    templates["docs/architecture.md"] = `# Architecture\n\n${replacement}\n`;
+}
+async function validateManagedPaths(root) {
+    for (const absolute of adoptionMutationFiles(root))
+        await safeRead(root, path.relative(root, absolute).replaceAll("\\", "/"));
+    for (const relative of [
+        ".codex/config.toml",
+        "scripts/qa.mjs",
+        "scripts/verify-extra.mjs",
+        "scripts/check-php.mjs",
+        "scripts/deploy.mjs",
+        "api/index.php",
+        "api/config.php",
+        ".htaccess",
+        "docs/architecture.md",
+        "docs/backend-php.md",
+        "docs/design-tokens.md",
+        ".mozole/telemetry.json",
+    ])
+        await safeRead(root, relative);
+    for (const relative of [".cce", ".mozole/state"]) {
+        try {
+            if ((await lstat(path.join(root, relative))).isSymbolicLink())
+                throw new Error(`Cannot adopt symlinked managed path: ${relative}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+async function restoreDirectories(moved) {
+    for (const { from, to } of [...moved].reverse()) {
+        await mkdir(path.dirname(from), { recursive: true });
+        await rm(from, { recursive: true, force: true });
+        await rename(to, from);
+    }
+}
+async function applyCanonicalPlan(root, plan, snapshots) {
+    const moved = [];
+    let backup;
+    async function backupDirectory() {
+        if (!backup) {
+            const parent = path.join(root, ".mozole/backups");
+            await mkdir(parent, { recursive: true });
+            backup = await mkdtemp(path.join(parent, "adopt-"));
+            plan.backup = backup;
+        }
+        return backup;
+    }
+    try {
+        for (const snapshot of snapshots) {
+            if (!snapshot.contents ||
+                snapshot.file.includes(`${path.sep}backups${path.sep}`))
+                continue;
+            const relative = path.relative(root, snapshot.file).replaceAll("\\", "/");
+            const desired = plan.removes.includes(relative)
+                ? undefined
+                : (plan.writes[relative] ?? (await safeRead(root, relative)));
+            if (desired !== undefined &&
+                snapshot.contents.equals(Buffer.from(desired)))
+                continue;
+            const file = path.join(await backupDirectory(), relative);
+            await mkdir(path.dirname(file), { recursive: true });
+            const temporary = `${file}.${process.pid}.tmp`;
+            await writeFile(temporary, snapshot.contents);
+            await rename(temporary, file);
+        }
+        await writeFiles(root, plan.writes, true);
+        for (const relative of plan.removes)
+            await rm(path.join(root, relative), { force: true });
+        for (const relative of plan.directories) {
+            const from = path.join(root, relative);
+            if (!(await exists(from)))
+                continue;
+            const to = path.join(await backupDirectory(), relative);
+            await mkdir(path.dirname(to), { recursive: true });
+            await rename(from, to);
+            moved.push({ from, to });
+        }
+        // Remove only empty integration directories; user-owned files prevent removal.
+        for (const relative of [
+            ".agents/workflows",
+            ".agents/rules",
+            ".agents",
+            ".codex",
+            ".claude",
+        ]) {
+            const directory = path.join(root, relative);
+            try {
+                if (!(await readdir(directory)).length)
+                    await rmdir(directory);
+            }
+            catch (error) {
+                if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? ""))
+                    throw error;
+            }
+        }
+        return moved;
+    }
+    catch (error) {
+        await restoreDirectories(moved);
+        throw error;
+    }
+}
+function migrationSummary(plan) {
+    return `${plan.backup ? `\nMigration backup: ${plan.backup}` : ""}${plan.notes.length ? `\n${plan.notes.join("\n")}` : ""}`;
+}
 //# sourceMappingURL=adopt.js.map