foundry-design 0.2.0-beta.2 → 0.2.0-beta.20

package/dist/installer.js

@@ -1,11 +1,17 @@
 import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
 import { accessSync } from 'node:fs';
 import { access, mkdir, readFile, readdir, rm, rmdir, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { detectPlatform } from './project.js';
+import { promisify } from 'node:util';
+import { detectPlatform, normalizeTargetUrl } from './project.js';
+import { FOUNDRY_MCP_PACKAGE_SPEC, FOUNDRY_VERSION } from './release.js';
 const START = '>>> Foundry Design Control';
 const END = '<<< Foundry Design Control';
+const GENERATOR_VERSION = FOUNDRY_VERSION;
+const TRANSACTION_FILE = 'setup-transaction.json';
+const execFileAsync = promisify(execFile);
 const DEFAULT_SKILL_ROOT = fileURLToPath(new URL('./skill/foundry-design-control/', import.meta.url));
 async function exists(path) {
     try {
@@ -27,6 +33,156 @@ async function readText(path) {
 function digest(content) {
     return createHash('sha256').update(content).digest('hex');
 }
+const LEGACY_NEXT_LOADER_DIGESTS = new Set([
+    'ec45810b798224907a947c3bf9e01e5e342b64f506c910a35f08fdc0399aac0e',
+    '8a5757b906c3db7b720cb5a61c4b4dd189bf1f61cb299cf31e107d277b75b4b3',
+]);
+function transactionPath(root) {
+    return join(root, '.foundry', TRANSACTION_FILE);
+}
+async function snapshotFiles(paths) {
+    return Promise.all([...new Set(paths)].map(async (path) => ({
+        path,
+        content: await readFile(path)
+            .then((value) => value.toString('base64'))
+            .catch(() => null),
+    })));
+}
+async function restoreSnapshots(root, snapshots) {
+    for (const snapshot of snapshots) {
+        if (snapshot.content == null) {
+            await rm(snapshot.path, { force: true }).catch(() => undefined);
+            continue;
+        }
+        await mkdir(dirname(snapshot.path), { recursive: true });
+        await writeFile(snapshot.path, Buffer.from(snapshot.content, 'base64'));
+    }
+    const directories = [...new Set(snapshots.map((snapshot) => dirname(snapshot.path)))]
+        .filter((path) => path.startsWith(root) && path !== root)
+        .sort((left, right) => right.length - left.length);
+    for (const directory of directories)
+        await rmdir(directory).catch(() => undefined);
+}
+async function recoverInterruptedSetup(root) {
+    const path = transactionPath(root);
+    const journal = await readFile(path, 'utf8')
+        .then((value) => JSON.parse(value))
+        .catch(() => undefined);
+    if (!journal?.snapshots?.length || journal.root !== root)
+        return;
+    await restoreSnapshots(root, journal.snapshots);
+    await rm(path, { force: true });
+    await rmdir(dirname(path)).catch(() => undefined);
+}
+async function writeTransaction(root, snapshots) {
+    const path = transactionPath(root);
+    await mkdir(dirname(path), { recursive: true });
+    const journal = { version: 1, root, snapshots };
+    await writeFile(path, `${JSON.stringify(journal, null, 2)}\n`);
+}
+async function validationCommands(root) {
+    const pkg = await packageJson(root);
+    const manager = packageManager(root);
+    const commands = [];
+    if (pkg.scripts?.typecheck) {
+        commands.push({
+            name: 'typecheck',
+            command: manager.command,
+            args: manager.runArgs('typecheck'),
+        });
+    }
+    else if (existsSync(join(root, 'node_modules', '.bin', 'tsc'))) {
+        commands.push({
+            name: 'typecheck',
+            command: join(root, 'node_modules', '.bin', 'tsc'),
+            args: ['--noEmit', '--pretty', 'false'],
+        });
+    }
+    if (pkg.scripts?.lint) {
+        commands.push({ name: 'lint', command: manager.command, args: manager.runArgs('lint') });
+    }
+    else if (existsSync(join(root, 'node_modules', '.bin', 'eslint'))) {
+        commands.push({
+            name: 'lint',
+            command: join(root, 'node_modules', '.bin', 'eslint'),
+            args: ['.'],
+        });
+    }
+    return commands;
+}
+async function runValidationCommand(root, check) {
+    try {
+        const result = await execFileAsync(check.command, check.args, {
+            cwd: root,
+            env: { ...process.env, CI: '1', NO_COLOR: '1' },
+            timeout: 180_000,
+            maxBuffer: 8_000_000,
+        });
+        return { exitCode: 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}` };
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === 'ENOENT') {
+            return { exitCode: 127, output: failure.message ?? 'Command unavailable', unavailable: true };
+        }
+        return {
+            exitCode: typeof failure.code === 'number' ? failure.code : 1,
+            output: `${failure.stdout ?? ''}${failure.stderr ?? ''}${failure.message ?? ''}`,
+        };
+    }
+}
+function introducedManagedDiagnostic(root, before, after, paths) {
+    if (before.exitCode === 0 && after.exitCode !== 0)
+        return true;
+    if (after.exitCode === 0 || before.output === after.output)
+        return false;
+    return paths.some((path) => {
+        const relativePath = slash(relative(root, path));
+        return after.output.includes(relativePath) && !before.output.includes(relativePath);
+    });
+}
+async function validateInstalledProject(root, checks, baseline, changed) {
+    if (!checks.length) {
+        return [
+            { name: 'typecheck', status: 'skipped', message: 'No project validation command found.' },
+            { name: 'lint', status: 'skipped', message: 'No project validation command found.' },
+        ];
+    }
+    const results = [];
+    for (const check of checks) {
+        const before = baseline.get(check.name);
+        const after = await runValidationCommand(root, check);
+        const command = [check.command, ...check.args].join(' ');
+        if (after.unavailable) {
+            results.push({
+                name: check.name,
+                status: 'skipped',
+                command,
+                message: 'The project command is not available in this environment.',
+            });
+            continue;
+        }
+        if (introducedManagedDiagnostic(root, before, after, changed)) {
+            const detail = after.output.trim().split('\n').slice(-12).join('\n');
+            throw new Error(`Foundry setup introduced a ${check.name} failure.\n${detail || `Command failed: ${command}`}`);
+        }
+        results.push({
+            name: check.name,
+            status: after.exitCode === 0 ? 'passed' : 'pre-existing-failure',
+            command,
+            ...(after.exitCode === 0
+                ? {}
+                : {
+                    message: 'The project had existing failures and Foundry added no managed-file diagnostic.',
+                }),
+        });
+    }
+    for (const name of ['typecheck', 'lint']) {
+        if (!results.some((result) => result.name === name))
+            results.push({ name, status: 'skipped', message: `No ${name} command found.` });
+    }
+    return results;
+}
 function slash(path) {
     return path.replaceAll('\\', '/');
 }
@@ -88,7 +244,16 @@ function defaultTarget(framework) {
         return 'http://127.0.0.1:3000';
     return undefined;
 }
-async function detectAgents(root) {
+async function detectAgents(root, environment = process.env) {
+    const active = [];
+    if (environment.CODEX_THREAD_ID || environment.CODEX_CI || environment.CODEX_HOME)
+        active.push('codex');
+    if (environment.CLAUDECODE || environment.CLAUDE_CODE_SESSION_ID)
+        active.push('claude');
+    if (environment.CURSOR_TRACE_ID || environment.CURSOR_AGENT)
+        active.push('cursor');
+    if (active.length)
+        return [...new Set(active)];
     const detected = [];
     if (await exists(join(root, '.cursor')))
         detected.push('cursor');
@@ -139,7 +304,7 @@ export async function createSetupPlan(rootInput, options = {}) {
     const root = resolve(rootInput);
     const platform = await detectPlatform(root);
     const framework = platform === 'web' ? await detectWebFramework(root) : undefined;
-    const agents = options.agents ?? (await detectAgents(root));
+    const agents = options.agents ?? (await detectAgents(root, options.environment));
     const integration = await integrationFile(root, framework);
     const skillDirectories = agents.map((agent) => skillDirectory(root, agent));
     const files = [
@@ -172,7 +337,7 @@ export async function createSetupPlan(rootInput, options = {}) {
         agents,
         files: [...new Set(files)],
         integrationFile: integration,
-        targetUrl: options.targetUrl ?? defaultTarget(framework),
+        targetUrl: normalizeTargetUrl(options.targetUrl ?? defaultTarget(framework)),
         devCommand: await detectDevCommand(root),
         skillDirectories,
     };
@@ -205,6 +370,23 @@ async function writeGenerated(path, content) {
     await writeFile(path, content);
     return { path, sha256: digest(content) };
 }
+async function writeOwnedGenerated(path, content, ownedFiles, allowLegacyLoader = false, preserveModified = false, preserved = []) {
+    const existing = await readFile(path, 'utf8').catch(() => undefined);
+    if (existing != null && existing !== content) {
+        const currentDigest = digest(existing);
+        const ownedDigest = ownedFiles.get(path);
+        const ownedAndUnchanged = ownedDigest === currentDigest;
+        const knownLoader = allowLegacyLoader && LEGACY_NEXT_LOADER_DIGESTS.has(currentDigest);
+        if (!ownedAndUnchanged && !knownLoader) {
+            if (preserveModified) {
+                preserved.push(path);
+                return ownedDigest ? { path, sha256: ownedDigest } : undefined;
+            }
+            throw new Error(`Foundry preserved your edited generated file at ${path}.`);
+        }
+    }
+    return writeGenerated(path, content);
+}
 async function readSkill(sourceRoot) {
     if (!(await exists(join(sourceRoot, 'SKILL.md')))) {
         throw new Error(`Foundry skill bundle is missing from ${sourceRoot}`);
@@ -224,25 +406,39 @@ async function readSkill(sourceRoot) {
     await visit(sourceRoot);
     return files;
 }
-async function validateSkillTarget(files, targetRoot, ownedFiles) {
+async function validateSkillTarget(files, targetRoot, ownedFiles, preserveModified = false, preserved = []) {
     for (const file of files) {
         const targetPath = join(targetRoot, file.path);
         const existing = await readFile(targetPath).catch(() => undefined);
         if (existing && !ownedFiles.has(targetPath) && !existing.equals(file.content)) {
+            if (preserveModified) {
+                preserved.push(targetPath);
+                continue;
+            }
             throw new Error(`A Foundry skill already exists at ${targetRoot}. Move or remove it before setup.`);
         }
         const ownedDigest = ownedFiles.get(targetPath);
         if (existing && ownedDigest && digest(existing.toString()) !== ownedDigest) {
+            if (preserveModified) {
+                preserved.push(targetPath);
+                continue;
+            }
             throw new Error(`Foundry preserved your edited skill at ${targetRoot}. Move it before updating setup.`);
         }
     }
 }
-async function copySkill(skillFiles, targetRoot) {
+async function copySkill(skillFiles, targetRoot, ownedFiles = new Map(), preserved = new Set()) {
     const managedFiles = [];
     const directories = new Set();
     directories.add(targetRoot);
     for (const file of skillFiles) {
         const targetPath = join(targetRoot, file.path);
+        if (preserved.has(targetPath)) {
+            const ownedDigest = ownedFiles.get(targetPath);
+            if (ownedDigest)
+                managedFiles.push({ path: targetPath, sha256: ownedDigest });
+            continue;
+        }
         const directory = dirname(targetPath);
         directories.add(directory);
         await mkdir(directory, { recursive: true });
@@ -257,19 +453,18 @@ export async function installFoundryDesignControl(): Promise<void> {
   if (typeof window === 'undefined') return;
   const query = new URLSearchParams(window.location.search);
   if (!query.has('__foundry_session')) return;
-  const module = await import(/* @vite-ignore */ '${runtimeUrl}/adapter.js');
-  module.installFoundryInspector();
+  const adapter = await import(/* @vite-ignore */ '${runtimeUrl}/adapter.js');
+  adapter.installFoundryInspector();
 }
 `;
 }
-async function configureWebIntegration(plan, generated, managedBlocks) {
+async function configureWebIntegration(plan, generated, managedBlocks, ownedFiles, runtimeUrl, preserveModified = false, preserved = []) {
     const entry = plan.integrationFile;
     if (!entry)
         return undefined;
     if (plan.framework === 'next') {
         const appRoot = dirname(entry);
         const loader = join(appRoot, 'foundry-loader.tsx');
-        const runtimeUrl = 'http://127.0.0.1:4387';
         const loaderContent = `'use client';
 
 import { useEffect } from 'react';
@@ -278,14 +473,19 @@ export function FoundryLoader(): null {
   useEffect(() => {
     const query = new URLSearchParams(window.location.search);
     if (!query.has('__foundry_session')) return;
-    void import(/* webpackIgnore: true */ '${runtimeUrl}/adapter.js').then((module) =>
-      module.installFoundryInspector(),
-    );
+    if (document.querySelector('script[data-foundry-bootstrap]')) return;
+    const script = document.createElement('script');
+    script.type = 'module';
+    script.src = '${runtimeUrl}/adapter-bootstrap.js';
+    script.dataset.foundryBootstrap = 'true';
+    document.head.append(script);
   }, []);
   return null;
 }
 `;
-        generated.push(await writeGenerated(loader, loaderContent));
+        const generatedLoader = await writeOwnedGenerated(loader, loaderContent, ownedFiles, true, preserveModified, preserved);
+        if (generatedLoader)
+            generated.push(generatedLoader);
         const original = await readText(entry);
         if (!original.includes('FoundryLoader')) {
             const withImport = `import { FoundryLoader } from './foundry-loader';\n${original}`;
@@ -307,7 +507,7 @@ export function FoundryLoader(): null {
         const script = managedBlock(`<script type="module">
   const query = new URLSearchParams(location.search);
   if (query.has('__foundry_session')) {
-    const module = await import('http://127.0.0.1:4387/adapter.js');
+    const module = await import('${runtimeUrl}/adapter.js');
     module.installFoundryInspector();
   }
 </script>`, 'html');
@@ -343,7 +543,7 @@ function mcpServer(packageRoot) {
     }
     return {
         command: 'npx',
-        args: ['-y', 'foundry-design-mcp-server@beta'],
+        args: ['-y', '--prefer-online', FOUNDRY_MCP_PACKAGE_SPEC],
         env: { FOUNDRY_DESIGN_RUNTIME_URL: 'http://127.0.0.1:4387' },
     };
 }
@@ -372,106 +572,355 @@ async function configureJson(path, packageRoot) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, `${JSON.stringify(current, null, 2)}\n`);
 }
+async function ensureMcpServersShape(path) {
+    const content = await readFile(path, 'utf8').catch(() => '');
+    if (!content)
+        return;
+    let current;
+    try {
+        current = JSON.parse(content);
+    }
+    catch {
+        return;
+    }
+    if (!current || typeof current !== 'object' || Array.isArray(current))
+        return;
+    const config = current;
+    if (config.mcpServers === undefined) {
+        config.mcpServers = {};
+        await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+    }
+}
+export async function installAgentIntegration(rootInput, agent, packageRoot) {
+    const root = resolve(rootInput);
+    if (agent === 'codex') {
+        const path = join(root, '.codex', 'config.toml');
+        await configureCodex(path, packageRoot);
+        return path;
+    }
+    const path = agent === 'cursor' ? join(root, '.cursor', 'mcp.json') : join(root, '.mcp.json');
+    await configureJson(path, packageRoot);
+    return path;
+}
+/** Install one reusable user-level connection without placing MCP config in every project. */
+export async function installHostAgentIntegration(homeInput, agent, options = {}) {
+    const home = resolve(homeInput);
+    const agentRoot = agent === 'codex'
+        ? join(home, '.codex')
+        : agent === 'cursor'
+            ? join(home, '.cursor')
+            : join(home, '.claude');
+    const configFile = agent === 'codex'
+        ? join(agentRoot, 'config.toml')
+        : agent === 'cursor'
+            ? join(agentRoot, 'mcp.json')
+            : join(home, '.claude.json');
+    const skillDirectory = join(agentRoot, 'skills', 'foundry-design-control');
+    if (agent === 'codex')
+        await configureCodex(configFile, options.packageRoot);
+    else
+        await configureJson(configFile, options.packageRoot);
+    if (agent === 'claude') {
+        // Some Claude hosts validate ~/.mcp.json before loading ~/.claude.json. A bare
+        // object is valid JSON but fails that schema and can prevent every user MCP
+        // server from loading, including Foundry.
+        await ensureMcpServersShape(join(home, '.mcp.json'));
+    }
+    const skillFiles = await readSkill(resolve(options.skillRoot ?? DEFAULT_SKILL_ROOT));
+    const manifestFile = join(skillDirectory, '.foundry-install.json');
+    const manifest = await readFile(manifestFile, 'utf8')
+        .then((content) => JSON.parse(content))
+        .catch(() => undefined);
+    const ownedFiles = new Map((manifest?.generatedFiles ?? []).map((file) => [file.path, file.sha256]));
+    const preserved = [];
+    await validateSkillTarget(skillFiles, skillDirectory, ownedFiles, true, preserved);
+    const copied = await copySkill(skillFiles, skillDirectory, ownedFiles, new Set(preserved));
+    await writeFile(manifestFile, `${JSON.stringify({
+        version: 1,
+        generatorVersion: GENERATOR_VERSION,
+        generatedFiles: copied.files,
+        updatedAt: new Date().toISOString(),
+    }, null, 2)}\n`);
+    return { configFile, skillDirectory, preserved };
+}
+/** Remove only Foundry-owned user-level configuration and skill files. */
+export async function uninstallHostAgentIntegration(homeInput, agent) {
+    const home = resolve(homeInput);
+    const agentRoot = agent === 'codex'
+        ? join(home, '.codex')
+        : agent === 'cursor'
+            ? join(home, '.cursor')
+            : join(home, '.claude');
+    const configFile = agent === 'codex'
+        ? join(agentRoot, 'config.toml')
+        : agent === 'cursor'
+            ? join(agentRoot, 'mcp.json')
+            : join(home, '.claude.json');
+    const skillDirectory = join(agentRoot, 'skills', 'foundry-design-control');
+    const manifestFile = join(skillDirectory, '.foundry-install.json');
+    const manifest = await readFile(manifestFile, 'utf8')
+        .then((content) => JSON.parse(content))
+        .catch(() => undefined);
+    const removed = [];
+    const preserved = [];
+    if (agent === 'codex') {
+        const original = await readText(configFile);
+        if (original.includes(START)) {
+            await writeFile(configFile, stripManagedBlock(original));
+            removed.push(configFile);
+        }
+    }
+    else {
+        const original = await readText(configFile);
+        if (original.includes('foundry-design-control')) {
+            await removeJsonServer(configFile);
+            removed.push(configFile);
+        }
+    }
+    for (const file of manifest?.generatedFiles ?? []) {
+        const content = await readText(file.path);
+        if (!content)
+            continue;
+        if (digest(content) !== file.sha256) {
+            preserved.push(file.path);
+            continue;
+        }
+        await rm(file.path);
+        removed.push(file.path);
+    }
+    await rm(manifestFile, { force: true });
+    removed.push(manifestFile);
+    const directories = [
+        join(skillDirectory, 'references'),
+        join(skillDirectory, 'scripts'),
+        skillDirectory,
+    ];
+    for (const directory of directories)
+        await rmdir(directory).catch(() => undefined);
+    return { configFile, removed: [...new Set(removed)], preserved };
+}
+export async function createUpdatePlan(rootInput, options = {}) {
+    const root = resolve(rootInput);
+    const manifest = await readFile(join(root, '.foundry', 'install-manifest.json'), 'utf8')
+        .then((content) => JSON.parse(content))
+        .catch(() => undefined);
+    if (!manifest)
+        throw new Error(`Foundry is not installed in ${root}. Run setup first.`);
+    const config = await readFile(join(root, '.foundry', 'foundry.config.json'), 'utf8')
+        .then((content) => JSON.parse(content))
+        .catch(() => undefined);
+    return createSetupPlan(root, {
+        ...options,
+        // Beta.14 makes the reusable host bridge the default. Passing agents
+        // explicitly remains the opt-in escape hatch for project-scoped installs.
+        agents: options.agents ?? [],
+        targetUrl: options.targetUrl ?? config?.targetUrl,
+        update: true,
+    });
+}
+export async function updateProject(rootInput, options = {}) {
+    const root = resolve(rootInput);
+    const plan = await createUpdatePlan(root, options);
+    const config = await readFile(join(root, '.foundry', 'foundry.config.json'), 'utf8')
+        .then((content) => JSON.parse(content))
+        .catch(() => undefined);
+    return setupProject(rootInput, {
+        ...options,
+        agents: plan.agents,
+        targetUrl: plan.targetUrl,
+        runtimeUrl: options.runtimeUrl ?? config?.runtimeUrl,
+        update: true,
+    });
+}
 export async function setupProject(rootInput, options = {}) {
-    const plan = await createSetupPlan(rootInput, options);
+    const root = resolve(rootInput);
+    await recoverInterruptedSetup(root);
+    const plan = await createSetupPlan(root, options);
     const runtimeUrl = options.runtimeUrl ?? 'http://127.0.0.1:4387';
     const generated = [];
     const managedBlocks = [];
     const jsonConfigs = [];
     const skillDirectories = [];
     const changed = [];
+    const preserved = [];
+    const preserveModified = options.update === true;
     const previousManifest = await readFile(join(plan.root, '.foundry', 'install-manifest.json'), 'utf8')
         .then((content) => JSON.parse(content))
         .catch(() => undefined);
+    const hasLegacyProjectAgentIntegration = Boolean(previousManifest &&
+        ((previousManifest.agents ?? []).length ||
+            (previousManifest.jsonConfigs ?? []).length ||
+            previousManifest.skillDirectories?.length ||
+            (previousManifest.managedBlocks ?? []).some((path) => path.endsWith(join('.codex', 'config.toml')))));
+    if (options.update && !previousManifest) {
+        throw new Error(`Foundry is not installed in ${plan.root}. Run setup first.`);
+    }
     const ownedFiles = new Map((previousManifest?.generatedFiles ?? []).map((file) => [file.path, file.sha256]));
     const skillFiles = plan.skillDirectories.length
         ? await readSkill(resolve(options.skillRoot ?? DEFAULT_SKILL_ROOT))
         : [];
     for (const directory of plan.skillDirectories) {
-        await validateSkillTarget(skillFiles, directory, ownedFiles);
-    }
-    const config = {
-        version: 2,
-        platform: plan.platform,
-        ...(plan.framework ? { framework: plan.framework } : {}),
-        runtimeUrl,
-        ...(plan.targetUrl ? { targetUrl: plan.targetUrl } : {}),
-        ...(plan.devCommand ? { devCommand: plan.devCommand } : {}),
-        instrumented: plan.platform !== 'web' || Boolean(plan.integrationFile),
-        design: {
-            componentRoots: ['src', 'app', 'components'],
-            exclude: ['node_modules', 'dist', 'build', '.next', 'coverage'],
-            viewports: [
-                { id: 'mobile', label: 'Mobile', width: 390, height: 844 },
-                { id: 'tablet', label: 'Tablet', width: 768, height: 1024 },
-                { id: 'desktop', label: 'Desktop', width: 1440, height: 900 },
-            ],
-            themes: [
-                { id: 'light', label: 'Light', attribute: 'data-theme', value: 'light' },
-                { id: 'dark', label: 'Dark', attribute: 'data-theme', value: 'dark' },
-            ],
-        },
-    };
-    const configFile = join(plan.root, '.foundry', 'foundry.config.json');
-    generated.push(await writeGenerated(configFile, `${JSON.stringify(config, null, 2)}\n`));
-    changed.push(configFile);
-    if (plan.platform === 'web') {
-        const adapter = join(plan.root, '.foundry', 'web-adapter.ts');
-        generated.push(await writeGenerated(adapter, adapterSource(runtimeUrl)));
-        changed.push(adapter);
-        const integration = await configureWebIntegration(plan, generated, managedBlocks);
-        if (integration)
-            changed.push(integration);
-    }
-    else {
-        const setup = join(plan.root, '.foundry', `${plan.platform}-setup.md`);
-        const content = plan.platform === 'swiftui'
-            ? '# Foundry SwiftUI setup\n\nAdd FoundryDesignControl only to DEBUG builds and mark meaningful views with `.foundryInspectable`.\n'
-            : '# Foundry React Native setup\n\nCreate the debug adapter and register semantic targets using `measureInWindow`.\n';
-        generated.push(await writeGenerated(setup, content));
-        changed.push(setup);
-    }
-    const gitignore = join(plan.root, '.gitignore');
-    await setManagedBlock(gitignore, managedBlock('.foundry/sessions/', 'hash'));
-    managedBlocks.push(gitignore);
-    changed.push(gitignore);
-    if (plan.agents.includes('codex')) {
-        const path = join(plan.root, '.codex', 'config.toml');
-        await configureCodex(path, options.packageRoot);
-        managedBlocks.push(path);
-        changed.push(path);
-    }
-    if (plan.agents.includes('cursor')) {
-        const path = join(plan.root, '.cursor', 'mcp.json');
-        await configureJson(path, options.packageRoot);
-        jsonConfigs.push(path);
-        changed.push(path);
-    }
-    if (plan.agents.includes('claude')) {
-        const path = join(plan.root, '.mcp.json');
-        await configureJson(path, options.packageRoot);
-        jsonConfigs.push(path);
-        changed.push(path);
+        await validateSkillTarget(skillFiles, directory, ownedFiles, preserveModified, preserved);
+    }
+    const transactionFiles = [
+        ...plan.files.filter((path) => !plan.skillDirectories.includes(path)),
+        ...plan.skillDirectories.flatMap((directory) => skillFiles.map((file) => join(directory, file.path))),
+        ...(plan.agents.length === 0 && hasLegacyProjectAgentIntegration
+            ? [
+                ...(previousManifest?.managedBlocks ?? []).filter((path) => path.endsWith(join('.codex', 'config.toml'))),
+                ...(previousManifest?.jsonConfigs ?? []),
+                ...(previousManifest?.generatedFiles ?? [])
+                    .filter((file) => (previousManifest?.skillDirectories ?? []).some((directory) => file.path === directory || file.path.startsWith(`${directory}/`)))
+                    .map((file) => file.path),
+            ]
+            : []),
+    ];
+    const snapshots = await snapshotFiles(transactionFiles);
+    const checks = await validationCommands(plan.root);
+    const baseline = new Map();
+    for (const check of checks)
+        baseline.set(check.name, await runValidationCommand(plan.root, check));
+    await writeTransaction(plan.root, snapshots);
+    try {
+        const config = {
+            version: 2,
+            platform: plan.platform,
+            ...(plan.framework ? { framework: plan.framework } : {}),
+            runtimeUrl,
+            ...(plan.targetUrl ? { targetUrl: plan.targetUrl } : {}),
+            ...(plan.devCommand ? { devCommand: plan.devCommand } : {}),
+            instrumented: plan.platform !== 'web' || Boolean(plan.integrationFile),
+            mode: plan.platform === 'web' && !plan.integrationFile ? 'basic' : 'precision',
+            connection: { mode: plan.agents.length ? 'project' : 'global' },
+            design: {
+                componentRoots: ['src', 'app', 'components'],
+                exclude: ['node_modules', 'dist', 'build', '.next', 'coverage'],
+                viewports: [
+                    { id: 'mobile', label: 'Mobile', width: 390, height: 844 },
+                    { id: 'tablet', label: 'Tablet', width: 768, height: 1024 },
+                    { id: 'desktop', label: 'Desktop', width: 1440, height: 900 },
+                ],
+                themes: [
+                    { id: 'light', label: 'Light', attribute: 'data-theme', value: 'light' },
+                    { id: 'dark', label: 'Dark', attribute: 'data-theme', value: 'dark' },
+                ],
+            },
+        };
+        const configFile = join(plan.root, '.foundry', 'foundry.config.json');
+        const generatedConfig = await writeOwnedGenerated(configFile, `${JSON.stringify(config, null, 2)}\n`, ownedFiles, false, preserveModified, preserved);
+        if (generatedConfig)
+            generated.push(generatedConfig);
+        if (!preserved.includes(configFile))
+            changed.push(configFile);
+        if (plan.platform === 'web') {
+            const adapter = join(plan.root, '.foundry', 'web-adapter.ts');
+            const generatedAdapter = await writeOwnedGenerated(adapter, adapterSource(runtimeUrl), ownedFiles, false, preserveModified, preserved);
+            if (generatedAdapter)
+                generated.push(generatedAdapter);
+            if (!preserved.includes(adapter))
+                changed.push(adapter);
+            const integration = await configureWebIntegration(plan, generated, managedBlocks, ownedFiles, runtimeUrl, preserveModified, preserved);
+            if (integration)
+                changed.push(integration);
+        }
+        else {
+            const setup = join(plan.root, '.foundry', `${plan.platform}-setup.md`);
+            const content = plan.platform === 'swiftui'
+                ? '# Foundry SwiftUI setup\n\nAdd FoundryDesignControl only to DEBUG builds and mark meaningful views with `.foundryInspectable`.\n'
+                : '# Foundry React Native setup\n\nCreate the debug adapter and register semantic targets using `measureInWindow`.\n';
+            const generatedSetup = await writeOwnedGenerated(setup, content, ownedFiles, false, preserveModified, preserved);
+            if (generatedSetup)
+                generated.push(generatedSetup);
+            if (!preserved.includes(setup))
+                changed.push(setup);
+        }
+        const gitignore = join(plan.root, '.gitignore');
+        await setManagedBlock(gitignore, managedBlock('.foundry/sessions/', 'hash'));
+        managedBlocks.push(gitignore);
+        changed.push(gitignore);
+        if (plan.agents.includes('codex')) {
+            const path = join(plan.root, '.codex', 'config.toml');
+            await configureCodex(path, options.packageRoot);
+            managedBlocks.push(path);
+            changed.push(path);
+        }
+        if (plan.agents.includes('cursor')) {
+            const path = join(plan.root, '.cursor', 'mcp.json');
+            await configureJson(path, options.packageRoot);
+            jsonConfigs.push(path);
+            changed.push(path);
+        }
+        if (plan.agents.includes('claude')) {
+            const path = join(plan.root, '.mcp.json');
+            await configureJson(path, options.packageRoot);
+            jsonConfigs.push(path);
+            changed.push(path);
+        }
+        for (const directory of plan.skillDirectories) {
+            const copied = await copySkill(skillFiles, directory, ownedFiles, new Set(preserved));
+            generated.push(...copied.files);
+            skillDirectories.push(...copied.directories);
+            changed.push(directory);
+        }
+        if (plan.agents.length === 0 && previousManifest && hasLegacyProjectAgentIntegration) {
+            const legacySkillDirectories = previousManifest.skillDirectories ?? [];
+            for (const path of (previousManifest.managedBlocks ?? []).filter((candidate) => candidate.endsWith(join('.codex', 'config.toml')))) {
+                const original = await readText(path);
+                if (!original)
+                    continue;
+                await writeFile(path, stripManagedBlock(original));
+                changed.push(path);
+            }
+            for (const path of previousManifest.jsonConfigs ?? []) {
+                await removeJsonServer(path);
+                changed.push(path);
+            }
+            for (const file of previousManifest.generatedFiles.filter((candidate) => legacySkillDirectories.some((directory) => candidate.path === directory || candidate.path.startsWith(`${directory}/`)))) {
+                const content = await readText(file.path);
+                if (!content)
+                    continue;
+                if (digest(content) !== file.sha256) {
+                    preserved.push(file.path);
+                    continue;
+                }
+                await rm(file.path);
+                changed.push(file.path);
+            }
+            for (const directory of [...legacySkillDirectories].sort((left, right) => right.length - left.length)) {
+                await rmdir(directory).catch(() => undefined);
+            }
+        }
+        const validation = await validateInstalledProject(plan.root, checks, baseline, changed);
+        const manifest = {
+            version: 3,
+            connectionMode: plan.agents.length ? 'project' : 'global',
+            agents: plan.agents,
+            generatedFiles: generated,
+            managedBlocks,
+            jsonConfigs,
+            skillDirectories: [...new Set(skillDirectories)],
+            installedAt: previousManifest?.installedAt ?? new Date().toISOString(),
+            ...(options.update ? { updatedAt: new Date().toISOString() } : {}),
+            generatorVersion: GENERATOR_VERSION,
+            validation,
+        };
+        const manifestFile = join(plan.root, '.foundry', 'install-manifest.json');
+        await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+        changed.push(manifestFile);
+        await rm(transactionPath(plan.root), { force: true });
+        return {
+            ...plan,
+            changed: [...new Set(changed)],
+            preserved: [...new Set(preserved)],
+            validation,
+        };
     }
-    for (const directory of plan.skillDirectories) {
-        const copied = await copySkill(skillFiles, directory);
-        generated.push(...copied.files);
-        skillDirectories.push(...copied.directories);
-        changed.push(directory);
+    catch (error) {
+        await restoreSnapshots(plan.root, snapshots);
+        await rm(transactionPath(plan.root), { force: true });
+        await rmdir(join(plan.root, '.foundry')).catch(() => undefined);
+        throw error;
     }
-    const manifest = {
-        version: 1,
-        agents: plan.agents,
-        generatedFiles: generated,
-        managedBlocks,
-        jsonConfigs,
-        skillDirectories: [...new Set(skillDirectories)],
-        installedAt: new Date().toISOString(),
-    };
-    const manifestFile = join(plan.root, '.foundry', 'install-manifest.json');
-    await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
-    changed.push(manifestFile);
-    return { ...plan, changed: [...new Set(changed)] };
 }
 async function removeJsonServer(path) {
     try {
@@ -479,8 +928,10 @@ async function removeJsonServer(path) {
         if (!current.mcpServers?.['foundry-design-control'])
             return;
         delete current.mcpServers['foundry-design-control'];
+        // Keep the required object even when Foundry was its only entry. Claude and
+        // some other hosts reject a bare object and may skip every user MCP server.
         if (Object.keys(current.mcpServers).length === 0)
-            delete current.mcpServers;
+            current.mcpServers = {};
         await writeFile(path, `${JSON.stringify(current, null, 2)}\n`);
     }
     catch {