@mozole/cli 1.3.2 → 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 writeFile(file, contents);
+        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",
@@ -70,56 +76,53 @@ async function exists(file) {
     }
 }
 async function atomicJson(file, value) {
+    await mkdir(path.dirname(file), { recursive: true });
     const temporary = `${file}.${process.pid}.tmp`;
     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 writeFile(file, `${block.trim()}\n`, "utf8");
-        return true;
-    }
-    const current = await readFile(file, "utf8");
-    if (current.includes(begin))
-        return false;
-    await writeFile(file, `${current.trimEnd()}\n\n${block.trim()}\n`, "utf8");
-    return true;
-}
-async function ensureGitignore(root) {
+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/",
+        "deploy/",
         ".mozole/logs/",
         ".mozole/qa/",
-        ".mozole/state/",
-        ".mozole/telemetry.json",
-        ".cce/",
+        ...(optimized ? [".mozole/state/", ".mozole/telemetry.json", ".cce/"] : []),
     ];
     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 writeFile(file, `${current.trimEnd()}${current.trim() ? "\n\n" : ""}# Mozole local state\n${missing.join("\n")}\n`, "utf8");
+    await writeFiles(root, {
+        ".gitignore": `${current.trimEnd()}${missing.length ? `${current.trim() ? "\n\n" : ""}# Mozole local files\n${missing.join("\n")}` : ""}\n`,
+    }, true);
 }
-async function ensureBiomeConfig(root, defaultTemplate) {
+async function ensureBiomeConfig(root, defaultTemplate, optimized = true) {
     const file = path.join(root, "biome.json");
     const requiredIgnores = [
         "!build",
         "!dist",
+        "!deploy",
         "!.react-router",
         "!node_modules",
         "!coverage",
         "!.mozole",
-        "!.cce",
+        ...(optimized ? ["!.cce"] : []),
         "!public",
         "!assets",
         "!qa-screenshots",
@@ -132,7 +135,22 @@ async function ensureBiomeConfig(root, defaultTemplate) {
         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],
@@ -146,33 +164,13 @@ async function ensureBiomeConfig(root, defaultTemplate) {
                 }
             }
         }
-        else if (Array.isArray(config.files.ignore)) {
-            const cleanPatterns = [
-                "build",
-                "dist",
-                ".react-router",
-                "node_modules",
-                "coverage",
-                ".mozole",
-                ".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) {
@@ -185,16 +183,28 @@ async function validateJsonObject(file) {
 }
 async function mergeHookConfig(file, template, backupFile) {
     const currentText = await readFile(file, "utf8");
-    if (currentText.includes("mozole governor hook"))
-        return;
     const current = JSON.parse(currentText);
     const desired = JSON.parse(template);
     const hooks = current.hooks && typeof current.hooks === "object"
         ? current.hooks
         : {};
     current.hooks = hooks;
-    const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    hooks.PreToolUse = [...existing, ...desired.hooks.PreToolUse];
+    for (const [event, groups] of Object.entries(desired.hooks)) {
+        const existing = Array.isArray(hooks[event])
+            ? hooks[event]
+            : [];
+        const preserved = existing.flatMap((group) => {
+            if (!Array.isArray(group.hooks))
+                return [group];
+            const remaining = group.hooks.filter((handler) => !JSON.stringify(handler).includes("mozole governor hook"));
+            return remaining.length || !group.hooks.length
+                ? [{ ...group, hooks: remaining }]
+                : [];
+        });
+        hooks[event] = [...preserved, ...groups];
+    }
+    if (JSON.stringify(current) === JSON.stringify(JSON.parse(currentText)))
+        return;
     await mkdir(path.dirname(backupFile), { recursive: true });
     await copyFile(file, backupFile);
     await atomicJson(file, current);
@@ -205,6 +215,8 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
         return 2;
     }
     const root = path.resolve(cwd, input);
+    if (!options.cceInstall)
+        return adoptPlain(root, output, options);
     const packagePath = path.join(root, "package.json");
     const progress = new TaskProgress({
         total: 5,
@@ -218,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);
@@ -232,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);
+        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);
@@ -247,27 +261,68 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
                     throw new Error(`Existing .mozole/project.json is invalid: ${error instanceof Error ? error.message : String(error)}`);
                 }
             })()
-            : projectConfig(name);
+            : 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;
-        if (config.governor.enabled) {
-            config.governor.mode = "enforce";
-            config.governor.hooks = { codex: true, claude: true };
-        }
+        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,
+            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 cceRequired = process.env.MOZOLE_SKIP_CCE !== "1" && config.cce?.enabled;
         const cce = cceRequired
             ? await requireCceRuntime(root, controller.signal)
             : 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",
@@ -287,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"] ??
@@ -305,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) {
@@ -324,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"),
@@ -352,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,
@@ -378,19 +451,9 @@ 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) {
+        if (cceRequired && !config.cce?.initialized) {
             progress.logVerbose("Initializing CCE for adopted project");
             const initialized = await initializeCce(root, controller.signal, cce);
             if (initialized?.exitCode !== 0) {
@@ -409,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) {
@@ -417,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) {
@@ -433,4 +497,319 @@ export async function adoptCommand(input, cwd, output = console, options = {}) {
         process.removeListener("SIGTERM", abort);
     }
 }
+/** Plain adoption never probes or installs agent runtimes. Existing user integrations are preserved. */
+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 };
+        if (!deps.react || (!deps.vite && !deps["@react-router/dev"]))
+            throw new Error("Expected a React project using Vite or React Router Framework Mode.");
+        const name = pkg.name ?? path.basename(root);
+        const configPath = path.join(root, ".mozole", "project.json");
+        const config = (await exists(configPath))
+            ? await readConfig(root)
+            : projectConfig(name);
+        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 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
+                ? {
+                    "scripts/check-php.mjs": required(templates, "scripts/check-php.mjs"),
+                    "scripts/deploy.mjs": required(templates, "scripts/deploy.mjs"),
+                }
+                : {}),
+        };
+        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"),
+            format: required(generated.scripts, "format"),
+            typecheck: "tsc --noEmit",
+            "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",
+            "qa",
+            "qa:force",
+            "qa:interactive",
+            "qa:visual",
+        ])
+            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);
+        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)
+            delete next.dependencies["@mozole/cli"];
+        for (const key of [
+            "@biomejs/biome",
+            "@testing-library/jest-dom",
+            "@testing-library/react",
+            "@testing-library/user-event",
+            "@vitejs/plugin-react",
+            "jsdom",
+            "typescript",
+            "vitest",
+            "playwright",
+        ])
+            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);
+            await atomicJson(packagePath, next);
+        }
+        await writeFiles(root, files);
+        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);
+        await ensureGitignore(root, false);
+        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"
+                    ? []
+                    : [["exec", "--", "playwright", "install", "chromium"]]),
+            ]) {
+                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");
+            }
+        }
+        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) {
+        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) {
+    const value = values[key];
+    if (value === undefined)
+        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