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

package/dist/index.js

@@ -1,17 +1,23 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { access, appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { renderChangePrompt } from 'foundry-design-protocol';
-import { FoundryRuntime, SessionStore } from 'foundry-design-runtime';
-import { createSetupPlan, setupProject, uninstallProject, } from './installer.js';
-import { addSessionParams, detectPlatform } from './project.js';
+import { homedir } from 'node:os';
+import { renderChangePrompt, } from 'foundry-design-protocol';
+import { FoundryRuntime, SessionStore, renderDeliveryMarkdown, } from 'foundry-design-runtime';
+import { createSetupPlan, createUpdatePlan, installHostAgentIntegration, installAgentIntegration, setupProject, updateProject, uninstallProject, uninstallHostAgentIntegration, } from './installer.js';
+import { addSessionParams, detectPlatform, normalizeTargetUrl, resolveProjectRoot, } from './project.js';
 import { indexProjectDesign } from './indexer.js';
+import { startBasicPreviewProxy } from './proxy.js';
+import { FOUNDRY_VERSION, releasePreflight } from './release.js';
+import { collectDoctorReport } from './doctor.js';
+import { CompanionStore } from './companion.js';
+import { DeliveryExportConflictError, renderPortableDeliveryJson, writeRepositoryDeliveryExport, } from './delivery-export.js';
 const args = process.argv.slice(2);
-const command = args[0] ?? 'help';
+const command = args[0]?.startsWith('-') ? 'launch' : (args[0] ?? 'launch');
 const runtimeRepository = resolve(fileURLToPath(new URL('../../../', import.meta.url)));
 function flag(name) {
     const index = args.indexOf(name);
@@ -20,24 +26,43 @@ function flag(name) {
 function has(name) {
     return args.includes(name);
 }
-function projectRoot() {
-    return resolve(process.env.INIT_CWD ?? process.cwd(), flag('--project') ?? '.');
+async function projectRoot(options = {}) {
+    const specified = flag('--project');
+    const start = resolve(process.env.INIT_CWD ?? process.cwd(), specified ?? '.');
+    return resolveProjectRoot(start, {
+        explicit: Boolean(specified),
+        allowUninitialized: options.allowUninitialized,
+    });
 }
 function printHelp() {
     console.log(`Foundry Design Control
 
 Usage:
-  foundry-design setup [--project PATH] [--agent codex,cursor,claude] [--url URL] [--yes]
+  foundry-design [--project PATH] [--url URL] [--yes] [--no-start]
+  foundry-design setup [--project PATH] [--agent codex,cursor,claude] [--project-agent] [--url URL] [--yes]
+  foundry-design update [--project PATH] [--agent codex,cursor,claude] [--yes]
+  foundry-design install [--agent codex,cursor,claude] [--yes]
+  foundry-design connect [--project PATH] [--url URL] [--yes]
+  foundry-design disconnect [--project PATH] [--yes]
+  foundry-design reset [--project PATH] [--agent codex,cursor,claude] [--url URL] [--yes]
+  foundry-design companion [--json]
   foundry-design init <web|swiftui|react-native> [--project PATH]
-  foundry-design start [--project PATH] [--url URL] [--platform PLATFORM] [--no-open] [--no-dev]
-  foundry-design doctor [--project PATH]
+  foundry-design start [--project PATH] [--url URL] [--platform PLATFORM] [--new] [--no-open] [--no-dev]
+  foundry-design doctor [--project PATH] [--repair] [--json]
+  foundry-design status [--project PATH] [--json]
   foundry-design index [--project PATH] [--output FILE]
-  foundry-design uninstall [--project PATH] [--yes]
+  foundry-design uninstall [--project PATH] [--global] [--agent codex,cursor,claude] [--yes]
   foundry-design export <SESSION_ID> [--format json|prompt|full] [--output FILE]
-  foundry-design install-agent <cursor|claude|codex> [--project PATH]
+  foundry-design delivery export <DELIVERY_ID> --format repo|markdown|json --output PATH [--yes]
+  foundry-design install-agent <cursor|claude|codex> [--project-agent --project PATH]
 
 Foundry is local-only and never edits product source from inspector controls.`);
 }
+async function pathExists(path) {
+    return access(path)
+        .then(() => true)
+        .catch(() => false);
+}
 async function gitOutput(root, gitArgs) {
     return new Promise((resolveRevision) => {
         const child = spawn('git', gitArgs, {
@@ -70,6 +95,126 @@ async function revision(root) {
     }
     return `${head}-dirty-${hash.digest('hex').slice(0, 12)}`;
 }
+function safeSourcePath(root, input) {
+    const candidate = isAbsolute(input) ? relative(root, input) : input;
+    const normalized = candidate.replaceAll('\\', '/').replace(/^\.\//, '');
+    const absolute = resolve(root, normalized);
+    const fromRoot = relative(root, absolute).replaceAll('\\', '/');
+    if (!normalized || fromRoot.startsWith('../') || isAbsolute(fromRoot)) {
+        throw new Error(`Source path is outside the project root: ${input}`);
+    }
+    return fromRoot;
+}
+async function sourceFileSnapshot(root, path, locations = []) {
+    const safePath = safeSourcePath(root, path);
+    const content = await readFile(resolve(root, safePath)).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    const sourceLines = content?.toString('utf8').split(/\r?\n/) ?? [];
+    return {
+        path: safePath,
+        exists: content !== null,
+        sha256: content === null ? null : createHash('sha256').update(content).digest('hex'),
+        lineAnchors: content === null
+            ? []
+            : [
+                ...new Map(locations
+                    .filter((location) => location.line &&
+                    Number.isInteger(location.line) &&
+                    location.line > 0 &&
+                    location.line <= sourceLines.length &&
+                    (!location.symbol || sourceLines[location.line - 1].includes(location.symbol)))
+                    .map((location) => [
+                    JSON.stringify([location.line, location.symbol]),
+                    {
+                        line: location.line,
+                        endLine: location.line,
+                        symbol: location.symbol,
+                        sha256: createHash('sha256')
+                            .update(sourceLines[location.line - 1])
+                            .digest('hex'),
+                    },
+                ])).values(),
+            ].sort((left, right) => left.line - right.line),
+    };
+}
+function parseChangedRanges(path, diff) {
+    const ranges = [];
+    for (const line of diff.split('\n')) {
+        const match = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (!match)
+            continue;
+        ranges.push({
+            path,
+            oldStart: Number(match[1]),
+            oldLines: match[2] === undefined ? 1 : Number(match[2]),
+            newStart: Number(match[3]),
+            newLines: match[4] === undefined ? 1 : Number(match[4]),
+        });
+    }
+    return ranges;
+}
+async function gitChangedRanges(root, tracked, untracked) {
+    const ranges = [];
+    for (const path of tracked) {
+        const diff = (await gitOutput(root, ['diff', '--no-ext-diff', '--unified=0', 'HEAD', '--', path])) ?? '';
+        ranges.push(...parseChangedRanges(path, diff));
+    }
+    for (const path of untracked) {
+        const content = await readFile(resolve(root, path), 'utf8').catch(() => '');
+        ranges.push({
+            path,
+            oldStart: 0,
+            oldLines: 0,
+            newStart: 1,
+            newLines: content.split(/\r?\n/).length,
+        });
+    }
+    return ranges;
+}
+async function projectSourceState(root, sourcePaths, sourceLocations = []) {
+    const headRevision = await gitOutput(root, ['rev-parse', 'HEAD']);
+    if (!headRevision) {
+        const mappedPaths = [...new Set(sourcePaths.map((path) => safeSourcePath(root, path)))].sort();
+        if (!mappedPaths.length) {
+            return {
+                supported: false,
+                revision: null,
+                reason: 'No source-backed paths are available for filesystem verification.',
+            };
+        }
+        const files = await Promise.all(mappedPaths.map((path) => sourceFileSnapshot(root, path, sourceLocations.filter((location) => safeSourcePath(root, location.path) === path))));
+        const fallbackRevision = createHash('sha256').update(JSON.stringify(files)).digest('hex');
+        return {
+            supported: true,
+            scope: 'mapped-files',
+            revision: `mapped-${fallbackRevision}`,
+            files,
+        };
+    }
+    const currentRevision = (await revision(root)) ?? headRevision;
+    const tracked = (await gitOutput(root, ['diff', '--name-only', 'HEAD']))?.split('\n').filter(Boolean) ?? [];
+    const untracked = (await gitOutput(root, ['ls-files', '--others', '--exclude-standard']))
+        ?.split('\n')
+        .filter(Boolean) ?? [];
+    const paths = [
+        ...new Set([...tracked, ...untracked, ...sourcePaths]
+            .map((file) => safeSourcePath(root, file))
+            .filter(Boolean)),
+    ].sort();
+    const files = await Promise.all(paths.map((path) => sourceFileSnapshot(root, path, sourceLocations.filter((location) => safeSourcePath(root, location.path) === path))));
+    const changedRanges = await gitChangedRanges(root, tracked.map((path) => safeSourcePath(root, path)), untracked.map((path) => safeSourcePath(root, path)));
+    return {
+        supported: true,
+        scope: 'git',
+        revision: currentRevision,
+        headRevision,
+        files,
+        changedRanges,
+    };
+}
 async function openUrl(url) {
     const executable = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
     const childArgs = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
@@ -105,18 +250,29 @@ function requestedAgents() {
         throw new Error(`Unsupported agent: ${invalid.join(', ')}`);
     return [...new Set(agents)];
 }
+async function sharedAgents(root, additional = []) {
+    const installed = await new CompanionStore(homedir()).read();
+    const detected = (await createSetupPlan(root)).agents;
+    return [...new Set([...installed.agents, ...additional, ...detected])];
+}
 async function setup() {
-    const root = projectRoot();
+    console.log(`${releasePreflight('set up this project')}\n`);
+    const root = await projectRoot();
+    const requested = requestedAgents();
+    const projectAgentSetup = has('--project-agent');
+    const hostAgents = requested ?? (await sharedAgents(root));
     const options = {
-        agents: requestedAgents(),
-        targetUrl: flag('--url'),
+        agents: projectAgentSetup ? hostAgents : [],
+        targetUrl: normalizeTargetUrl(flag('--url')),
         packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
     };
     const plan = await createSetupPlan(root, options);
     console.log(`Foundry setup\n\nProject: ${root}\nPlatform: ${plan.platform}`);
     if (plan.framework)
         console.log(`Framework: ${plan.framework}`);
-    console.log(`Agent integration: ${plan.agents.length ? plan.agents.join(', ') : 'plugin-provided'}`);
+    console.log(`Agent integration: ${projectAgentSetup
+        ? `${plan.agents.join(', ')} (project-scoped compatibility mode)`
+        : `${hostAgents.join(', ')} (shared across projects)`}`);
     console.log('\nFiles Foundry will manage:');
     for (const path of plan.files)
         console.log(`  ${path}`);
@@ -128,22 +284,90 @@ async function setup() {
         return;
     }
     const result = await setupProject(root, options);
+    if (!projectAgentSetup) {
+        for (const agent of hostAgents) {
+            await installHostAgentIntegration(homedir(), agent, {
+                packageRoot: options.packageRoot,
+            });
+        }
+        await new CompanionStore(homedir()).recordInstallation(hostAgents);
+        await new CompanionStore(homedir()).registerProject(root, result.targetUrl);
+    }
     console.log(`\n✓ Foundry configured ${result.changed.length} files.`);
+    for (const check of result.validation) {
+        const marker = check.status === 'passed' ? '✓' : check.status === 'skipped' ? '–' : '!';
+        console.log(`${marker} ${check.name}: ${check.status.replaceAll('-', ' ')}`);
+    }
     if (result.skillDirectories.length) {
         console.log(`✓ Installed the Foundry skill for ${result.agents.join(', ')}.`);
     }
+    if (!projectAgentSetup && hostAgents.length) {
+        console.log(`✓ Installed the shared Foundry connection for ${hostAgents.join(', ')}.`);
+    }
     if (result.targetUrl)
         console.log(`✓ Preview URL: ${result.targetUrl}`);
     if (result.devCommand)
         console.log(`✓ Development command: ${result.devCommand.command} ${result.devCommand.args.join(' ')}`);
-    console.log('\nRestart your coding agent, then ask: "Start Foundry for this project."');
-    console.log('You can also run: foundry-design start');
+    console.log('\nSetup complete. One coding-agent restart is required so it can load Foundry.');
+    console.log(`1. Restart ${!projectAgentSetup && hostAgents.length
+        ? hostAgents.join(', ')
+        : result.agents.length
+            ? result.agents.join(', ')
+            : 'your coding agent'}.`);
+    console.log('2. Reopen this exact project folder.');
+    console.log('3. Ask: "Start Foundry for this project and keep listening for Apply with agent requests."');
+    console.log('\nAfter that, the browser will confirm when the agent is ready.');
+}
+async function update() {
+    console.log(`${releasePreflight('update this project')}\n`);
+    const root = await projectRoot();
+    const requested = requestedAgents();
+    const projectAgentSetup = has('--project-agent');
+    const hostAgents = requested ?? (await sharedAgents(root));
+    const options = {
+        agents: projectAgentSetup ? hostAgents : [],
+        packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+    };
+    const plan = await createUpdatePlan(root, options);
+    console.log(`Foundry update\n\nProject: ${root}`);
+    console.log(`Agent integration: ${projectAgentSetup
+        ? `${plan.agents.join(', ')} (project-scoped compatibility mode)`
+        : `${hostAgents.join(', ')} (shared across projects)`}`);
+    console.log('\nFoundry will refresh these managed paths:');
+    for (const path of plan.files)
+        console.log(`  ${path}`);
+    console.log('\nFiles changed since Foundry installed them will be preserved.');
+    if (!(await confirm('\nContinue with this update?'))) {
+        console.log('Update cancelled.');
+        return;
+    }
+    const result = await updateProject(root, options);
+    if (!projectAgentSetup) {
+        for (const agent of hostAgents)
+            await installHostAgentIntegration(homedir(), agent, {
+                packageRoot: options.packageRoot,
+            });
+        await new CompanionStore(homedir()).recordInstallation(hostAgents);
+        await new CompanionStore(homedir()).registerProject(root, result.targetUrl);
+    }
+    console.log(`\n✓ Foundry refreshed ${result.changed.length} managed paths.`);
+    if (result.preserved.length) {
+        console.log('Preserved files containing user changes:');
+        for (const path of result.preserved)
+            console.log(`  ${path}`);
+    }
+    for (const check of result.validation) {
+        const marker = check.status === 'passed' ? '✓' : check.status === 'skipped' ? '–' : '!';
+        console.log(`${marker} ${check.name}: ${check.status.replaceAll('-', ' ')}`);
+    }
+    console.log('\nThe project now uses the shared Foundry agent connection.');
 }
 async function initProject() {
+    console.log(`${releasePreflight('initialize this project')}\n`);
     const platform = (args[1] ?? 'web');
     if (!['web', 'swiftui', 'react-native'].includes(platform))
         throw new Error(`Unsupported platform: ${platform}`);
-    const root = projectRoot();
+    const root = await projectRoot({ allowUninitialized: true });
     const configRoot = join(root, '.foundry');
     await mkdir(configRoot, { recursive: true });
     await writeFile(join(configRoot, 'foundry.config.json'), `${JSON.stringify({
@@ -184,7 +408,7 @@ async function initProject() {
         console.log('Import and call .foundry/web-adapter.ts once from your development-only client entry.');
 }
 async function start() {
-    const root = projectRoot();
+    const root = await projectRoot();
     let config;
     try {
         config = JSON.parse(await readFile(join(root, '.foundry', 'foundry.config.json'), 'utf8'));
@@ -195,10 +419,8 @@ async function start() {
     const platform = flag('--platform') ??
         config?.platform ??
         (await detectPlatform(root));
-    const targetUrl = flag('--url') ?? config?.targetUrl;
-    if (platform === 'web' && config && !config.instrumented) {
-        throw new Error('Foundry setup is incomplete. Connect .foundry/web-adapter.ts to a development-only client entry, then set instrumented to true.');
-    }
+    const targetUrl = normalizeTargetUrl(flag('--url') ?? config?.targetUrl);
+    let basicPreview;
     let developmentServer;
     if (platform === 'web' &&
         targetUrl &&
@@ -224,54 +446,105 @@ async function start() {
         }
     }
     const projectRevision = await revision(root);
+    const configuredViewports = config?.design?.viewports ?? [];
+    const initialViewport = configuredViewports.find((viewport) => viewport.id.toLowerCase() === 'desktop' || viewport.label.toLowerCase() === 'desktop') ??
+        [...configuredViewports].sort((left, right) => right.width - left.width)[0] ?? {
+        width: 1440,
+        height: 900,
+    };
     const context = {
         projectRoot: root,
         revision: projectRevision,
         platform,
         targetUrl,
+        previewOrigin: targetUrl ? new URL(targetUrl).origin : undefined,
         targetName: basename(root),
+        viewport: { width: initialViewport.width, height: initialViewport.height ?? 900 },
         theme: 'system',
         breakpoint: 'current',
         state: 'current',
     };
     const store = new SessionStore();
-    const session = await store.create(context);
+    const resumable = has('--new')
+        ? undefined
+        : (await store.list()).find((candidate) => candidate.changeSet.context.projectRoot === root &&
+            candidate.changeSet.context.revision === projectRevision &&
+            candidate.changeSet.context.targetUrl === targetUrl);
+    const session = resumable
+        ? await store.read(resumable.changeSet.sessionId)
+        : await store.create(context);
     if (platform === 'web') {
         const graph = await indexProjectDesign(root, config, projectRevision);
         await store.setDesignGraph(session.changeSet.sessionId, graph);
         console.log(`Indexed ${graph.tokens.length} tokens, ${graph.components.length} components, and ${graph.breakpoints.length} viewports.`);
     }
-    const runtime = new FoundryRuntime({ store });
+    const runtime = new FoundryRuntime({
+        store,
+        resolveProjectRevision: async ({ projectRoot: revisionRoot, sourcePaths, sourceLocations }) => projectSourceState(revisionRoot, sourcePaths, sourceLocations),
+        reindexProjectDesign: async ({ projectRoot: graphRoot }) => {
+            const currentConfig = await readFile(join(graphRoot, '.foundry', 'foundry.config.json'), 'utf8')
+                .then((content) => JSON.parse(content))
+                .catch(() => undefined);
+            return indexProjectDesign(graphRoot, currentConfig, await revision(graphRoot));
+        },
+    });
+    let ownsRuntime = false;
     try {
         await runtime.start();
+        ownsRuntime = true;
     }
     catch (error) {
         if (error.code !== 'EADDRINUSE')
             throw error;
-        developmentServer?.kill('SIGTERM');
-        console.error('Port 4387 is already in use. Stop the existing Foundry runtime before starting another session.');
-        process.exitCode = 1;
-        return;
+        const healthy = await fetch('http://127.0.0.1:4387/v1/health')
+            .then((response) => response.ok)
+            .catch(() => false);
+        if (!healthy)
+            throw new Error('Port 4387 is in use by another process. Stop it and run Foundry again.');
+        console.log('Using the existing local Foundry runtime.');
     }
     const reviewUrl = `http://127.0.0.1:4387/?session=${encodeURIComponent(session.changeSet.sessionId)}&token=${encodeURIComponent(session.token)}`;
+    if (platform === 'web' && targetUrl && config && !config.instrumented) {
+        basicPreview = await startBasicPreviewProxy(targetUrl, config.runtimeUrl);
+        console.log('Basic mode: Foundry is attached without changing the project entry point.');
+        console.log('Run setup again after adding a supported client entry to enable exact source mapping.');
+    }
+    if (platform === 'web' && targetUrl) {
+        await store.setPreviewOrigin(session.changeSet.sessionId, new URL(basicPreview?.url ?? targetUrl).origin);
+    }
+    const previewCapability = platform === 'web' && targetUrl ? randomBytes(32).toString('base64url') : undefined;
+    if (previewCapability) {
+        await store.setPreviewCapability(session.changeSet.sessionId, previewCapability);
+    }
     const productUrl = targetUrl && platform === 'web'
-        ? addSessionParams(targetUrl, session.changeSet.sessionId, session.token)
+        ? addSessionParams(basicPreview?.url ?? targetUrl, session.changeSet.sessionId, session.token, previewCapability)
+        : reviewUrl;
+    const workspaceUrl = platform === 'web' && targetUrl
+        ? `${reviewUrl}&preview=${encodeURIComponent(productUrl)}`
         : reviewUrl;
     console.log(`Foundry session ${session.changeSet.sessionId}`);
+    if (resumable)
+        console.log('Resumed the most recent session for this project revision.');
     console.log(`Platform: ${platform}`);
-    console.log(`Inspector: ${reviewUrl}`);
+    console.log(`Workspace: ${workspaceUrl}`);
     if (targetUrl && platform === 'web')
-        console.log(`Instrumented preview: ${productUrl}`);
+        console.log(`${basicPreview ? 'Basic' : 'Precision'} preview: ${productUrl}`);
     if (platform === 'web') {
         console.log('\nFirst edit:');
         console.log('  1. Option-click an element. Shift-click to add more.');
         console.log('  2. Drag a blue handle or use the inspector for exact values.');
         console.log('  3. Review the semantic mapping, then Apply with agent.');
+        console.log('\nAgent handoff:');
+        console.log('  Keep this process running while you design.');
+        console.log('  Foundry will show “Agent is ready” only while a coding agent is listening.');
+        console.log('  If it is not ready, ask the agent: “Keep listening for Apply with agent requests.”');
     }
     if (!has('--no-open'))
-        await openUrl(productUrl);
+        await openUrl(workspaceUrl);
     const shutdown = async () => {
-        await runtime.stop();
+        if (ownsRuntime)
+            await runtime.stop();
+        await basicPreview?.stop();
         developmentServer?.kill('SIGTERM');
         process.exit(0);
     };
@@ -280,7 +553,7 @@ async function start() {
     await new Promise(() => { });
 }
 async function indexDesign() {
-    const root = projectRoot();
+    const root = await projectRoot();
     const config = await readFile(join(root, '.foundry', 'foundry.config.json'), 'utf8')
         .then((content) => JSON.parse(content))
         .catch(() => undefined);
@@ -295,7 +568,33 @@ async function indexDesign() {
         console.log(content);
 }
 async function uninstall() {
-    const root = projectRoot();
+    if (has('--global')) {
+        const installed = await new CompanionStore(homedir()).read();
+        const agents = requestedAgents() ?? installed.agents;
+        if (!agents.length) {
+            console.log('No shared Foundry agent connection is registered.');
+            return;
+        }
+        if (!(await confirm(`Remove the shared Foundry connection for ${agents.join(', ')}?`))) {
+            console.log('Uninstall cancelled.');
+            return;
+        }
+        const preserved = [];
+        for (const agent of agents) {
+            const result = await uninstallHostAgentIntegration(homedir(), agent);
+            preserved.push(...result.preserved);
+        }
+        await new CompanionStore(homedir()).removeInstallation(agents);
+        console.log(`Removed the shared Foundry connection for ${agents.join(', ')}.`);
+        if (preserved.length) {
+            console.log('Preserved customized skill files:');
+            for (const path of preserved)
+                console.log(`  ${path}`);
+        }
+        return;
+    }
+    console.log(`${releasePreflight('remove managed project integration')}\n`);
+    const root = await projectRoot();
     if (!(await confirm(`Remove Foundry-managed project integration from ${root}?`))) {
         console.log('Uninstall cancelled.');
         return;
@@ -308,68 +607,108 @@ async function uninstall() {
             console.log(`  ${path}`);
     }
 }
+async function disconnect() {
+    const root = await projectRoot();
+    if (!(await confirm(`Disconnect ${root} from Foundry's recent projects?`))) {
+        console.log('Disconnect cancelled.');
+        return;
+    }
+    await new CompanionStore(homedir()).unregisterProject(root);
+    console.log(`Disconnected ${root}. The project adapter remains installed and can reconnect later.`);
+}
 async function doctor() {
-    const root = projectRoot();
-    const platform = await detectPlatform(root);
-    const configPath = join(root, '.foundry', 'foundry.config.json');
-    let config;
-    try {
-        config = JSON.parse(await readFile(configPath, 'utf8'));
+    const root = await projectRoot();
+    const report = await collectDoctorReport(root);
+    if (has('--json'))
+        console.log(JSON.stringify(report, null, 2));
+    else {
+        for (const check of report.checks) {
+            const marker = check.status === 'passed' ? '✓' : check.status === 'warning' ? '△' : '○';
+            console.log(`${marker} ${check.label}: ${check.detail}`);
+        }
+        console.log(report.ready
+            ? '\nFoundry is ready and an agent is actively listening.'
+            : '\nFoundry is not yet ready for Apply with agent. Configuration and a live listener are separate checks.');
+    }
+    if (has('--repair')) {
+        console.log(`\n${releasePreflight('repair this project and agent connection')}\n`);
+        const installed = report.checks.find((check) => check.id === 'integration')?.status !== 'failed';
+        const configuredAgents = installed ? (await createUpdatePlan(root)).agents : [];
+        const hostAgents = await sharedAgents(root, configuredAgents);
+        const result = installed
+            ? await updateProject(root, {
+                agents: [],
+                targetUrl: normalizeTargetUrl(flag('--url')),
+            })
+            : await setupProject(root, {
+                agents: [],
+                targetUrl: normalizeTargetUrl(flag('--url')),
+            });
+        for (const agent of hostAgents)
+            await installHostAgentIntegration(homedir(), agent, {
+                packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+            });
+        await new CompanionStore(homedir()).recordInstallation(hostAgents);
+        await new CompanionStore(homedir()).registerProject(root, result.targetUrl);
+        console.log(`✓ Repaired ${result.changed.length} managed paths and the shared ${hostAgents.join(', ')} connection.`);
+        const repaired = await collectDoctorReport(root);
+        const requiredAfterRepair = new Set([
+            'config',
+            'project-connection',
+            'integration',
+            'agent-configured',
+            'agent-config-valid',
+            'agent-version',
+        ]);
+        const remaining = repaired.checks.filter((check) => requiredAfterRepair.has(check.id) && check.status === 'failed');
+        if (remaining.length) {
+            throw new Error(`Repair is incomplete: ${remaining.map((check) => check.label).join(', ')}`);
+        }
+        console.log('✓ Project and agent configuration now use the same Foundry release.');
+        if (repaired.checks.find((check) => check.id === 'agent-listening')?.status !== 'passed') {
+            console.log('△ Restart the active coding agent once to activate its listener.');
+        }
+    }
+    else if (report.checks.some((check) => check.status === 'failed')) {
+        console.log('Run: foundry-design doctor --repair');
     }
-    catch {
-        /* Report setup as missing below. */
-    }
-    const agentFiles = [
-        join(root, '.codex', 'config.toml'),
-        join(root, '.cursor', 'mcp.json'),
-        join(root, '.mcp.json'),
-    ];
-    const configuredAgents = [];
-    for (const path of agentFiles) {
-        if ((await readFile(path, 'utf8').catch(() => '')).includes('foundry-design-control'))
-            configuredAgents.push(path);
-    }
-    const pluginProvided = await readFile(join(root, '.foundry', 'install-manifest.json'), 'utf8')
-        .then((content) => {
-        const manifest = JSON.parse(content);
-        return Array.isArray(manifest.agents) && manifest.agents.length === 0;
-    })
-        .catch(() => false);
-    const checks = [
-        ['Project', root, true],
-        ['Detected platform', platform, true],
-        ['Foundry config', configPath, Boolean(config)],
-        [
-            'Instrumentation',
-            config?.instrumented ? `${config.framework ?? config.platform}` : 'integration pending',
-            Boolean(config?.instrumented),
-        ],
-        [
-            'Agent connection',
-            configuredAgents.length
-                ? configuredAgents.join(', ')
-                : pluginProvided
-                    ? 'plugin-provided'
-                    : 'not configured',
-            configuredAgents.length > 0 || pluginProvided,
-        ],
-        [
-            'Project preview',
-            config?.targetUrl ?? 'not configured',
-            config?.targetUrl ? await urlAvailable(config.targetUrl) : platform !== 'web',
-        ],
-        [
-            'Runtime health',
-            'http://127.0.0.1:4387/v1/health',
-            await fetch('http://127.0.0.1:4387/v1/health')
-                .then((response) => response.ok)
-                .catch(() => false),
-        ],
-    ];
-    for (const [label, value, passed] of checks)
-        console.log(`${passed ? '✓' : '○'} ${label}: ${value}`);
-    if (!config)
-        console.log('Run: foundry-design setup');
+}
+async function launch() {
+    console.log(`${releasePreflight('install, update, and start Foundry')}\n`);
+    const root = await projectRoot();
+    const manifest = join(root, '.foundry', 'install-manifest.json');
+    const installed = await pathExists(manifest);
+    const configuredAgents = installed ? (await createUpdatePlan(root)).agents : [];
+    const hostAgents = await sharedAgents(root, configuredAgents);
+    console.log(`Foundry\n\nProject: ${root}`);
+    console.log(`${installed ? 'Refreshing' : 'Preparing'} the project and shared ${hostAgents.join(', ')} connection.`);
+    if (!(await confirm('Continue?'))) {
+        console.log('Foundry cancelled.');
+        return;
+    }
+    const result = installed
+        ? await updateProject(root, {
+            agents: [],
+            targetUrl: normalizeTargetUrl(flag('--url')),
+        })
+        : await setupProject(root, {
+            agents: [],
+            targetUrl: normalizeTargetUrl(flag('--url')),
+        });
+    for (const agent of hostAgents)
+        await installHostAgentIntegration(homedir(), agent, {
+            packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+        });
+    await new CompanionStore(homedir()).recordInstallation(hostAgents);
+    await new CompanionStore(homedir()).registerProject(root, result.targetUrl);
+    console.log(`✓ ${installed ? 'Updated' : 'Installed'} and validated Foundry.`);
+    for (const check of result.validation)
+        console.log(`${check.status === 'passed' ? '✓' : check.status === 'skipped' ? '–' : '!'} ${check.name}: ${check.status.replaceAll('-', ' ')}`);
+    if (!installed)
+        console.log(`\nRestart ${hostAgents.join(', ')} once to load the shared connection. The visual session will open now and queued batches will wait safely until it reconnects.`);
+    if (has('--no-start'))
+        return;
+    await start();
 }
 async function exportSession() {
     const id = args[1];
@@ -395,45 +734,163 @@ async function exportSession() {
     else
         console.log(content);
 }
+async function exportDelivery() {
+    if (args[1] !== 'export')
+        throw new Error('delivery requires the export subcommand');
+    const recordId = args[2];
+    if (!recordId)
+        throw new Error('delivery export requires a delivery record id');
+    const output = flag('--output');
+    if (!output)
+        throw new Error('delivery export requires --output PATH');
+    const format = flag('--format') ?? 'repo';
+    if (!['repo', 'markdown', 'json'].includes(format)) {
+        throw new Error('delivery export format must be repo, markdown, or json');
+    }
+    const store = new SessionStore();
+    const summary = (await store.list()).find((session) => session.deliveryRecords.some((record) => record.id === recordId));
+    if (!summary)
+        throw new Error(`Unknown delivery record: ${recordId}`);
+    const session = await store.read(summary.changeSet.sessionId);
+    const record = session.deliveryRecords.find((candidate) => candidate.id === recordId);
+    if (format === 'repo') {
+        if (!(await confirm(`Export ${record.title} into ${resolve(output)}?`))) {
+            console.log('Delivery export cancelled.');
+            return;
+        }
+        let manifest;
+        try {
+            manifest = await writeRepositoryDeliveryExport(output, session, record);
+        }
+        catch (error) {
+            if (error instanceof DeliveryExportConflictError && error.documentationPageIds.length) {
+                await store.markDocumentationConflicted(session.changeSet.sessionId, error.documentationPageIds);
+            }
+            throw error;
+        }
+        await store.recordDocumentationExports(session.changeSet.sessionId, manifest.documentationPages);
+        console.log(`Exported ${manifest.files.length} managed delivery files to ${resolve(output)}.`);
+        console.log('Foundry preserved the project root changelog and will refuse to overwrite edited generated docs.');
+        return;
+    }
+    const content = format === 'markdown'
+        ? renderDeliveryMarkdown(record, session.changeSet.context.projectRoot)
+        : renderPortableDeliveryJson(record, session.changeSet.context.projectRoot);
+    await mkdir(dirname(resolve(output)), { recursive: true });
+    await writeFile(resolve(output), `${content}\n`);
+    console.log(`Exported ${format} delivery record to ${resolve(output)}.`);
+}
 async function installAgent() {
+    console.log(`${releasePreflight('install the coding-agent connection')}\n`);
     const agent = args[1];
     if (!agent || !['cursor', 'claude', 'codex'].includes(agent))
         throw new Error('install-agent requires cursor, claude, or codex');
-    const root = projectRoot();
-    const server = {
-        command: 'npx',
-        args: ['-y', 'foundry-design-mcp-server@beta'],
-        env: { FOUNDRY_DESIGN_RUNTIME_URL: 'http://127.0.0.1:4387' },
-    };
-    if (agent === 'codex') {
-        const directory = join(root, '.codex');
-        await mkdir(directory, { recursive: true });
-        const file = join(directory, 'foundry-mcp.toml');
-        await writeFile(file, `# Merge this project-scoped server into your Codex MCP configuration.\n[mcp_servers.foundry-design-control]\ncommand = "npx"\nargs = ["-y", "foundry-design-mcp-server@beta"]\n[mcp_servers.foundry-design-control.env]\nFOUNDRY_DESIGN_RUNTIME_URL = "http://127.0.0.1:4387"\n`);
-        console.log(`Wrote Codex MCP snippet: ${file}`);
+    if (!has('--project-agent')) {
+        const result = await installHostAgentIntegration(homedir(), agent, {
+            packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+        });
+        console.log(`Installed the shared Foundry connection for ${agent}.`);
+        console.log(`MCP configuration: ${result.configFile}`);
+        console.log(`Skill: ${result.skillDirectory}`);
+        if (result.preserved.length) {
+            console.log('Preserved customized skill files:');
+            for (const path of result.preserved)
+                console.log(`  ${path}`);
+        }
+        await new CompanionStore(homedir()).recordInstallation([agent]);
+        console.log(`Restart ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'} once. Future projects connect with "npx foundry-design" without another MCP install.`);
         return;
     }
-    const file = agent === 'cursor' ? join(root, '.cursor', 'mcp.json') : join(root, '.mcp.json');
-    await mkdir(dirname(file), { recursive: true });
-    let current = {};
-    try {
-        current = JSON.parse(await readFile(file, 'utf8'));
+    const root = await projectRoot();
+    const file = await installAgentIntegration(root, agent, has('--local-mcp') ? runtimeRepository : undefined);
+    console.log(`Installed Foundry MCP configuration for ${agent}: ${file}`);
+    console.log(`Restart ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'} before starting a Foundry apply session.`);
+}
+async function installHost() {
+    console.log(`${releasePreflight('install Foundry for your coding agents')}\n`);
+    const agents = requestedAgents() ?? ['codex', 'cursor', 'claude'];
+    if (!(await confirm(`Install the shared Foundry connection for ${agents.join(', ')}?`))) {
+        console.log('Installation cancelled.');
+        return;
     }
-    catch {
-        /* Create a new project config. */
+    for (const agent of agents) {
+        const result = await installHostAgentIntegration(homedir(), agent, {
+            packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+        });
+        console.log(`✓ ${agent}: ${result.configFile}`);
+    }
+    await new CompanionStore(homedir()).recordInstallation(agents);
+    console.log('\nFoundry is installed once for these agents. Restart each selected agent once.');
+    console.log('Then open any project and run: npx foundry-design');
+}
+async function reset() {
+    console.log(`${releasePreflight('reset managed project and agent integration')}\n`);
+    const root = await projectRoot();
+    const installed = await pathExists(join(root, '.foundry', 'install-manifest.json'));
+    const configuredAgents = installed ? (await createUpdatePlan(root)).agents : [];
+    const requested = requestedAgents();
+    const hostAgents = requested ?? (await sharedAgents(root, configuredAgents));
+    if (!(await confirm(`Reset Foundry-managed integration for ${root}?`))) {
+        console.log('Reset cancelled.');
+        return;
+    }
+    const options = {
+        agents: [],
+        targetUrl: normalizeTargetUrl(flag('--url')),
+        packageRoot: has('--local-mcp') ? runtimeRepository : undefined,
+    };
+    const result = installed ? await updateProject(root, options) : await setupProject(root, options);
+    for (const agent of hostAgents)
+        await installHostAgentIntegration(homedir(), agent, options);
+    await new CompanionStore(homedir()).recordInstallation(hostAgents);
+    await new CompanionStore(homedir()).registerProject(root, result.targetUrl);
+    console.log(`✓ Reset ${result.changed.length} managed paths and ${hostAgents.join(', ')} shared connections.`);
+    if (result.preserved.length) {
+        console.log('Preserved customized files:');
+        for (const path of result.preserved)
+            console.log(`  ${path}`);
+    }
+    console.log('Restart the active coding agent once, reopen this project, then run npx foundry-design.');
+}
+async function companion() {
+    const state = await new CompanionStore(homedir()).read();
+    if (has('--json')) {
+        console.log(JSON.stringify(state, null, 2));
+        return;
+    }
+    console.log(`Foundry ${state.foundryVersion}`);
+    console.log(`Installed agents: ${state.agents.join(', ') || 'none'}`);
+    console.log(`Recent projects: ${state.projects.length}`);
+    for (const project of state.projects.slice(0, 5)) {
+        console.log(`  ${project.root}${project.targetUrl ? ` · ${project.targetUrl}` : ''}`);
     }
-    current.mcpServers = { ...current.mcpServers, 'foundry-design-control': server };
-    await writeFile(file, `${JSON.stringify(current, null, 2)}\n`);
-    console.log(`Installed Foundry MCP configuration for ${agent}: ${file}`);
 }
 try {
-    if (command === 'setup')
+    if (has('--version') || command === 'version')
+        console.log(FOUNDRY_VERSION);
+    else if (has('--help') || command === 'help')
+        printHelp();
+    else if (command === 'launch')
+        await launch();
+    else if (command === 'setup')
         await setup();
+    else if (command === 'update')
+        await update();
+    else if (command === 'install')
+        await installHost();
+    else if (command === 'connect')
+        await launch();
+    else if (command === 'disconnect')
+        await disconnect();
+    else if (command === 'reset')
+        await reset();
+    else if (command === 'companion')
+        await companion();
     else if (command === 'init')
         await initProject();
     else if (command === 'start')
         await start();
-    else if (command === 'doctor')
+    else if (command === 'doctor' || command === 'status')
         await doctor();
     else if (command === 'index')
         await indexDesign();
@@ -441,6 +898,8 @@ try {
         await uninstall();
     else if (command === 'export')
         await exportSession();
+    else if (command === 'delivery')
+        await exportDelivery();
     else if (command === 'install-agent')
         await installAgent();
     else