@feltdb/core 0.7.3 → 0.7.4

package/dist/cli/commands.js

@@ -8,12 +8,16 @@ import net from 'net';
 import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
 import { randomBytes } from 'crypto';
-import { createFeltDB, diffFlowSpec, emptyFlowSpec, formatFlowSpec, InvestigationLifecycleManager, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
+import { createFeltDB, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
 import { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
 import { applicationUrlCandidate, detectApplication, discoverApplicationUrl } from './application.js';
 import { resolveApplicationLifecycle, startManagedApplication, waitForManagedApplication } from './application-lifecycle.js';
 import { createDevelopmentSession, developmentSessionEnvironment, developmentSessionSummary, transitionDevelopmentSession } from './development-session.js';
 import { openApplication, openStudio } from './browser-opening.js';
+import { publishApplication } from './publish-engine.js';
+import { applyFlowProposal, describeProposal, loadLocalDevelopmentContract, reviewFlowProposal, syncGeneratedSource } from './source-sync.js';
+import { configureAiModel, generateConfiguredFlowProposal, publicAiModelConfiguration } from './ai-model-config.js';
+import { proposalService } from './proposal-client.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -79,11 +83,177 @@ export async function handleCommand(command, args) {
             return handleFlowDeploy(args);
         case 'publish':
             return handleManagedPublish(args);
+        case 'ai':
+            return handleAi(args);
+        case 'proposals':
+            return handleProposals(args);
+        case 'sync':
+            return handleSourceSync(args);
         case 'help':
         default:
             return handleHelp();
     }
 }
+function proposalFile(args) {
+    const value = args.find(argument => !argument.startsWith('--') && !['review', 'apply'].includes(argument));
+    if (!value)
+        throw new Error('A proposal JSON file is required');
+    return path.resolve(value);
+}
+function validateRepositoryBuild(args) {
+    const packagePath = path.resolve('package.json');
+    const projectPackage = fs.existsSync(packagePath) ? JSON.parse(fs.readFileSync(packagePath, 'utf8')) : {};
+    if (!projectPackage.scripts?.build || args.includes('--no-build'))
+        return;
+    console.log('Validating the updated application before recording applied status…');
+    const built = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', 'build'], { cwd: process.cwd(), stdio: 'inherit' });
+    if (built.status !== 0)
+        throw new Error(`APPLICATION_VALIDATION_FAILED: build exited ${built.status ?? 'without a status'}; proposal remains approved for recovery`);
+}
+async function handleAi(args) {
+    loadProjectEnvironment();
+    if (args[0] === 'model') {
+        const action = args[1] || 'show';
+        if (action === 'show') {
+            const model = publicAiModelConfiguration();
+            console.log(`Provider: ${model.provider}\nModel: ${model.model}\nLocation: ${model.local ? 'local browser (private)' : model.baseUrl}\nCredential: ${model.credentialConfigured ? 'configured securely' : 'not configured'}`);
+            return;
+        }
+        if (action === 'set') {
+            const option = (name) => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+            const provider = (option('--provider') || 'local-webllm');
+            if (!['local-webllm', 'openai-compatible'].includes(provider))
+                throw new Error('Provider must be local-webllm or openai-compatible');
+            const modelName = option('--model');
+            if (!modelName)
+                throw new Error('--model is required');
+            const apiKey = args.includes('--api-key-stdin') ? fs.readFileSync(0, 'utf8').trim() : process.env.FELTDB_AI_API_KEY;
+            const configured = configureAiModel({ provider, model: modelName, baseUrl: option('--base-url'), apiKey: apiKey || undefined,
+                credentialRequired: !args.includes('--no-credential') });
+            console.log(`✓ AI model configured: ${configured.provider} / ${configured.model}`);
+            console.log(provider === 'openai-compatible' ? 'Credential is stored in the operating-system vault; Studio receives only provider metadata.' : 'Inference and prompts stay in the browser.');
+            return;
+        }
+        throw new Error('Usage: feltdb ai model [show|set --provider <local-webllm|openai-compatible> --model <id> [--base-url <url>] [--api-key-stdin|--no-credential]]');
+    }
+    if (!args.length || args.every(argument => ['--dry-run', '--preview', '--ephemeral', '--no-open'].includes(argument))) {
+        console.log('Opening the local Ask FeltDB experience. Generation stays in your browser via WebGPU.');
+        return handleStudio(args, studioUrl => console.log(`Ask FeltDB: ${studioUrl}`));
+    }
+    const action = args[0];
+    if (action === 'context') {
+        const context = await loadLocalDevelopmentContract();
+        console.log(JSON.stringify({ snapshot: context.snapshot, flowHash: context.flowHash }, null, 2));
+        return;
+    }
+    if (action === 'review') {
+        const input = JSON.parse(fs.readFileSync(proposalFile(args.slice(1)), 'utf8'));
+        const proposal = input;
+        const review = await reviewFlowProposal(proposal);
+        console.log(`\n${proposal.summary || 'FeltDB change proposal'}`);
+        for (const line of describeProposal(review))
+            console.log(`  ${line}`);
+        if (!describeProposal(review).length)
+            console.log('  No contract changes.');
+        return;
+    }
+    if (action === 'apply') {
+        const target = args.slice(1).find(value => !value.startsWith('--'));
+        if (!target)
+            throw new Error('A proposal id or JSON file is required');
+        const stored = target.startsWith('p_') ? await proposalService().get(target) : undefined;
+        const proposal = stored ? { baseContractHash: stored.base_contract_hash, baseFlowHash: stored.base_flow_hash,
+            proposedFlow: stored.proposed_flow, summary: stored.summary, changes: stored.contract_diff, warnings: stored.warnings }
+            : JSON.parse(fs.readFileSync(path.resolve(target), 'utf8'));
+        if (stored && stored.status !== 'approved')
+            throw new Error(`Proposal must be approved before apply; current status is ${stored.status}`);
+        if (!stored && !args.includes('--approve'))
+            throw new Error('Explicit approval is required: rerun with --approve');
+        const current = await loadLocalDevelopmentContract();
+        if (stored && (stored.application_id !== current.snapshot.application.application_id || stored.environment !== current.snapshot.application.environment)) {
+            throw new Error(`PROPOSAL_SCOPE_MISMATCH: ${stored.application_id}/${stored.environment} cannot apply to ${current.snapshot.application.application_id}/${current.snapshot.application.environment}`);
+        }
+        const alreadyWritten = stored && await import('@feltdb/core').then(module => module.flowSourceHash(stored.proposed_flow)) === current.flowHash;
+        if (alreadyWritten) {
+            console.log('Detected an approved proposal whose flow is already present; reconciling the interrupted application.');
+            const recoveredReview = await reviewFlowProposal({ ...proposal, baseContractHash: current.snapshot.contract_hash, baseFlowHash: current.flowHash });
+            syncGeneratedSource(recoveredReview, process.cwd(), { replace: args.includes('--replace-generated') });
+            validateRepositoryBuild(args);
+            await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
+            console.log(`✓ Reconciled and marked ${stored.id} applied`);
+            return;
+        }
+        const reviewOnly = await reviewFlowProposal(proposal);
+        console.log(`\n${proposal.summary || 'FeltDB change proposal'}`);
+        for (const line of describeProposal(reviewOnly))
+            console.log(`  ${line}`);
+        console.log(`  Source impact: feltdb.flow, src/feltdb/generated-contract.ts`);
+        if (args.includes('--dry-run') || args.includes('--preview')) {
+            console.log('✓ Preview complete. No files, flow, contract, or published state were changed.');
+            return;
+        }
+        const review = await applyFlowProposal(proposal, process.cwd(), {
+            allowDirty: args.includes('--allow-dirty'),
+            approveAuthorization: args.includes('--approve-authorization'),
+            replaceGenerated: args.includes('--replace-generated'),
+        });
+        console.log(`✓ Applied validated flow proposal (${review.proposedContract.hashes.application})`);
+        for (const file of review.written)
+            console.log(`  ${file}`);
+        validateRepositoryBuild(args);
+        if (stored)
+            await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
+        return;
+    }
+    throw new Error('Usage: feltdb ai [context|review <proposal.json>|apply <proposal.json>]');
+}
+async function handleProposals(args) {
+    loadProjectEnvironment();
+    const client = proposalService();
+    const action = args[0] || 'list';
+    const id = args[1];
+    if (action === 'list') {
+        const { proposals } = await client.list();
+        for (const value of proposals.sort((a, b) => String(b.created_at).localeCompare(String(a.created_at))))
+            console.log(`${value.id}\t${value.status}\t${value.summary}`);
+        if (!proposals.length)
+            console.log('No proposals.');
+        return;
+    }
+    if (!id)
+        throw new Error(`feltdb proposals ${action} requires a proposal id`);
+    if (action === 'get') {
+        console.log(JSON.stringify({ proposal: await client.get(id), history: (await client.history(id)).events }, null, 2));
+        return;
+    }
+    if (action === 'diff') {
+        const value = await client.get(id);
+        console.log(value.contract_diff.join('\n'));
+        console.log(JSON.stringify(value.source_plan, null, 2));
+        return;
+    }
+    if (action === 'approve' || action === 'reject') {
+        const value = await client.transition(id, action === 'approve' ? 'approved' : 'rejected', 'local-developer', false, args.includes('--approve-authorization'));
+        console.log(`✓ ${value.id} ${value.status}`);
+        return;
+    }
+    throw new Error('Usage: feltdb proposals [list|get|diff|approve|reject] [id]');
+}
+async function handleSourceSync(args) {
+    loadProjectEnvironment();
+    const context = await loadLocalDevelopmentContract();
+    const proposal = {
+        baseContractHash: context.snapshot.contract_hash,
+        baseFlowHash: context.flowHash,
+        proposedFlow: context.source,
+        summary: 'Synchronize generated source with feltdb.flow',
+        changes: [], warnings: [],
+    };
+    const review = await reviewFlowProposal(proposal);
+    const result = syncGeneratedSource(review, process.cwd(), { replace: args.includes('--replace-generated') });
+    for (const file of result.written)
+        console.log(`✓ Synchronized ${file}`);
+}
 /**
  * Inspect the durable investigation store.
  *
@@ -234,83 +404,29 @@ async function handleFlowDeploy(args) {
     }
 }
 async function handleManagedPublish(args) {
-    loadProjectEnvironment();
-    const configPath = path.resolve('feltdb.config.json');
-    if (!fs.existsSync(configPath))
-        throw new Error('feltdb.config.json is required for publish');
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    if (config.runtime !== 'managed')
-        throw new Error('feltdb publish requires a managed runtime in feltdb.config.json');
-    const url = process.env.VITE_FELTDB_MANAGED_URL;
-    const token = process.env.VITE_FELTDB_MANAGED_API_KEY;
-    const tenantId = process.env.VITE_FELTDB_MANAGED_TENANT_ID;
-    const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID;
-    const namespace = process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace;
-    const environment = process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || 'production';
-    const missing = [
-        ['VITE_FELTDB_MANAGED_URL', url],
-        ['VITE_FELTDB_MANAGED_API_KEY', token],
-        ['VITE_FELTDB_MANAGED_TENANT_ID', tenantId],
-        ['VITE_FELTDB_MANAGED_APPLICATION_ID', applicationId],
-        ['VITE_FELTDB_MANAGED_NAMESPACE', namespace],
-    ].filter(([, value]) => !value).map(([name]) => name);
-    if (missing.length)
-        throw new Error(`Managed publish configuration is incomplete in .env.local: ${missing.join(', ')}`);
-    const file = flowFile(args);
-    const spec = readFlowSpec(file);
-    const diagnostics = validateFlowSpec(spec).filter(value => value.severity === 'error');
-    if (diagnostics.length)
-        throw new Error(diagnostics.map(value => value.message).join('; '));
-    console.log('FeltDB Publish');
-    console.log(`Application: ${spec.app}`);
-    console.log(`Environment: ${environment}`);
-    console.log(`Namespace:   ${namespace}`);
-    console.log(`API:         ${url}`);
-    console.log('✓ Configuration loaded');
-    if (!args.includes('--no-build')) {
-        const manifestPath = path.resolve('package.json');
-        if (!fs.existsSync(manifestPath))
-            throw new Error('package.json is required to build the application');
-        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-        if (!manifest.scripts?.build)
-            throw new Error('package.json must define a build script for managed publish');
-        const build = spawnSync('npm', ['run', 'build'], { cwd: process.cwd(), stdio: 'inherit' });
-        if (build.error)
-            throw build.error;
-        if (build.status !== 0)
-            throw new Error(`Application build failed with exit code ${build.status}`);
-    }
-    console.log('✓ Build completed');
-    console.log('✓ Application validated');
-    const remote = createFeltDB({ namespace, server: { url: url, token: token } });
-    try {
-        const current = await remote.collection('_flow_apps').get(spec.app);
-        const migration = planFlowSpecMigration(current?.spec ?? emptyFlowSpec(spec.app), spec);
-        const destructive = migration.filter(value => value.safety === 'destructive');
-        if (destructive.length && !args.includes('--allow-destructive')) {
-            throw new Error(`Publish contains destructive changes (${destructive.map(value => value.target).join(', ')}); review them and rerun with --allow-destructive`);
+    const valueAfter = (flag) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
+    const confirm = async (question) => {
+        if (!process.stdin.isTTY)
+            return false;
+        const readline = await import('node:readline/promises');
+        const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return !/^(n|no)$/i.test((await prompt.question(`${question} [Y/n] `)).trim());
         }
-        const result = await remote.deployFlowSpec(spec, current?.version ?? 0, args.includes('--allow-destructive'));
-        const publishState = {
-            tenantId,
-            applicationId,
-            namespace,
-            environment,
-            deploymentId: `${applicationId}:${environment}:${result.version}`,
-            version: result.version,
-            publishedAt: new Date().toISOString(),
-        };
-        fs.mkdirSync(path.resolve('.feltdb'), { recursive: true });
-        fs.writeFileSync(path.resolve('.feltdb/last-published.json'), `${JSON.stringify(publishState, null, 2)}\n`, { mode: 0o600 });
-        fs.writeFileSync(path.resolve('.feltdb/last-deployed.flow'), formatFlowSpec(spec));
-        console.log('✓ Published');
-        console.log(`Deployment: ${publishState.deploymentId}`);
-        console.log(`Version:    ${result.version}`);
-        console.log('Your app is live.');
-    }
-    finally {
-        await remote.close();
-    }
+        finally {
+            prompt.close();
+        }
+    };
+    await publishApplication({
+        environment: valueAfter('--environment'),
+        message: valueAfter('--message'),
+        dryRun: args.includes('--dry-run'),
+        status: args.includes('--status'),
+        yes: args.includes('--yes'),
+        approveDestructive: args.includes('--approve-destructive-changes') || args.includes('--allow-destructive'),
+        noBuild: args.includes('--no-build'),
+        confirm,
+    });
 }
 async function handleServer(args) {
     const require = createRequire(import.meta.url);
@@ -500,17 +616,39 @@ For more info, visit: https://github.com/rkendel1/feltdb
 `);
 }
 async function handleConnect(args) {
-    const url = args[0];
-    if (!url) {
-        console.error('❌ URL required');
-        console.error('Usage: feltdb connect <url>\n');
-        process.exit(1);
-    }
+    loadProjectEnvironment();
+    const projectFile = path.resolve('feltdb.config.json');
+    const project = fs.existsSync(projectFile) ? JSON.parse(fs.readFileSync(projectFile, 'utf8')) : {};
+    const url = (args[0]
+        || process.env.VITE_FELTDB_MANAGED_URL
+        || process.env.VITE_FELTDB_URL
+        || project.server?.url
+        || (project.runtime === 'browser' ? '' : 'http://localhost:7700')).replace(/\/$/, '');
+    if (!url)
+        throw new Error('This project uses the embedded browser runtime; there is no server endpoint to connect to. Run npm run dev.');
     console.log('🔗 Connecting to FeltDB Server\n');
     console.log(`URL: ${url}`);
-    console.log('Discovering node...');
-    console.log('Checking capabilities...');
     console.log('Verifying connection...\n');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    let health;
+    try {
+        const response = await fetch(`${url}/health`, {
+            headers: process.env.VITE_FELTDB_MANAGED_API_KEY || process.env.VITE_FELTDB_API_KEY
+                ? { Authorization: `Bearer ${process.env.VITE_FELTDB_MANAGED_API_KEY || process.env.VITE_FELTDB_API_KEY}` }
+                : {},
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        health = await response.json();
+    }
+    catch (error) {
+        throw new Error(`FeltDB is not running at ${url}. Start it with npm run feltdb:studio (or the project's configured runtime command). ${error instanceof Error ? error.message : error}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
     // Store connection info
     const configDir = path.join(process.cwd(), '.feltdb');
     if (!fs.existsSync(configDir)) {
@@ -520,15 +658,16 @@ async function handleConnect(args) {
     fs.writeFileSync(connFile, JSON.stringify({
         url,
         connected: new Date().toISOString(),
-        authenticated: false,
+        authenticated: Boolean(process.env.VITE_FELTDB_MANAGED_API_KEY || process.env.VITE_FELTDB_API_KEY),
+        namespace: project.namespace || process.env.VITE_FELTDB_MANAGED_NAMESPACE || 'default',
+        runtime: project.runtime || 'self-hosted',
     }, null, 2));
     console.log('✅ Connected to FeltDB\n');
     console.log('Endpoint:     ' + url);
-    console.log('Namespace:    default');
-    console.log('Authenticated: no');
-    console.log('Runtime:      self-hosted');
-    console.log('Peers:        0');
-    console.log('Health:       ✓\n');
+    console.log(`Namespace:    ${project.namespace || process.env.VITE_FELTDB_MANAGED_NAMESPACE || 'default'}`);
+    console.log(`Authenticated: ${process.env.VITE_FELTDB_MANAGED_API_KEY || process.env.VITE_FELTDB_API_KEY ? 'yes' : 'no'}`);
+    console.log(`Runtime:      ${project.runtime || 'self-hosted'}`);
+    console.log(`Health:       ${health.status || 'healthy'}\n`);
     console.log('Use: feltdb status  (to check connection)\n');
 }
 async function handleExplain(args) {
@@ -561,20 +700,39 @@ async function handleStatus() {
         console.log('Fabric:        Enabled');
         console.log('Authentication: Development');
         console.log('Health:        ✓\n');
+        await displayContractStatus();
         return;
     }
     const connection = JSON.parse(fs.readFileSync(connFile, 'utf-8'));
     console.log('Connected to Server\n');
     console.log(`Endpoint:     ${connection.url}`);
-    console.log('Namespace:    default');
+    console.log(`Namespace:    ${connection.namespace || 'default'}`);
     console.log(`Authenticated: ${connection.authenticated ? 'yes' : 'no'}`);
-    console.log('Runtime:      self-hosted');
-    console.log('Storage:      durable');
-    console.log('Peers:        3');
-    console.log('Capabilities: 8');
-    console.log('Agents:       2');
-    console.log('Workflows:    5');
-    console.log('Health:       ✓\n');
+    console.log(`Runtime:      ${connection.runtime || 'self-hosted'}`);
+    try {
+        const response = await fetch(`${String(connection.url).replace(/\/$/, '')}/health`, { signal: AbortSignal.timeout(5000) });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const health = await response.json();
+        console.log(`Health:       ${health.status || 'healthy'}\n`);
+    }
+    catch {
+        console.log('Health:       unavailable');
+        console.log('Start the configured runtime and run feltdb connect again.\n');
+    }
+    await displayContractStatus();
+}
+async function displayContractStatus() {
+    if (!fs.existsSync(path.resolve('feltdb.flow')))
+        return;
+    loadProjectEnvironment();
+    const current = await loadLocalDevelopmentContract();
+    const publishedFile = path.resolve('.feltdb/last-published.json');
+    const published = fs.existsSync(publishedFile) ? JSON.parse(fs.readFileSync(publishedFile, 'utf8')) : undefined;
+    console.log('Application contract');
+    console.log(`Source:        ${current.snapshot.contract_hash}`);
+    console.log(`Published:     ${published?.contractHash || 'unknown'}`);
+    console.log(`Drift:         ${!published?.contractHash ? 'unknown' : published.contractHash === current.snapshot.contract_hash ? 'synchronized' : 'source differs from published'}\n`);
 }
 async function handleWorkspace(args) {
     const subcommand = args[0] || 'status';
@@ -776,10 +934,16 @@ async function handleDev(args) {
     if (!process.env.VITE_FELTDB_URL) {
         const authorityPort = Number(args.includes('--authority-port') ? args[args.indexOf('--authority-port') + 1] || '7700' : '7700');
         localAuthority = await startLocalDevelopmentAuthority({
-            dataDir: path.join(projectDir, '.feltdb', 'authority'),
+            dataDir: path.join(projectDir, '.feltdb-data', 'authority'),
             port: authorityPort,
+            proposalContext: () => loadLocalDevelopmentContract(projectDir),
         });
         process.env.VITE_FELTDB_URL = localAuthority.endpoint;
+        const connectionsPath = path.join(projectDir, '.feltdb', 'connections.json');
+        const connections = fs.existsSync(connectionsPath) ? JSON.parse(fs.readFileSync(connectionsPath, 'utf8')) : {};
+        fs.writeFileSync(connectionsPath, `${JSON.stringify({ ...connections, developmentAuthority: {
+                endpoint: localAuthority.endpoint, proposalAuthorityToken: localAuthority.proposalAuthorityToken,
+            } }, null, 2)}\n`, { mode: 0o600 });
     }
     const authorityUrl = process.env.VITE_FELTDB_URL;
     if (!authorityUrl)
@@ -1286,9 +1450,13 @@ async function handleStudio(args, onReady) {
         console.log('⚠️  Studio application artifacts not found.');
         return;
     }
-    const projectFlow = ['feltdb.flow', ...fs.readdirSync(process.cwd()).filter(value => value.endsWith('.flow'))]
-        .map(value => path.resolve(process.cwd(), value))
-        .find((value, index, values) => values.indexOf(value) === index && fs.existsSync(value));
+    const canonicalFlow = path.resolve(process.cwd(), 'feltdb.flow');
+    const projectFlow = fs.existsSync(canonicalFlow) ? canonicalFlow : undefined;
+    const studioMutationToken = randomBytes(24).toString('hex');
+    const projectPackage = fs.existsSync(path.resolve('package.json')) ? JSON.parse(fs.readFileSync(path.resolve('package.json'), 'utf8')) : {};
+    const webllmEnabled = Boolean(projectPackage.dependencies?.['@feltdb/webllm'] || projectPackage.devDependencies?.['@feltdb/webllm']);
+    const previewOnly = args.includes('--ephemeral');
+    const proposalClient = proposalService(process.cwd(), session.authorityUrl);
     const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.json': 'application/json' };
     const server = http.createServer(async (request, response) => {
         const pathname = decodeURIComponent(new URL(request.url || '/', 'http://localhost').pathname);
@@ -1299,12 +1467,184 @@ async function handleStudio(args, onReady) {
             const managedPublish = runtime === 'managed' ? {
                 url: process.env.VITE_FELTDB_MANAGED_URL || connectUrl || '',
                 namespace: process.env.VITE_FELTDB_MANAGED_NAMESPACE || namespace,
-                token: process.env.VITE_FELTDB_MANAGED_API_KEY || process.env.VITE_FELTDB_API_KEY || '',
                 tenantId: process.env.VITE_FELTDB_MANAGED_TENANT_ID || '',
                 applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || '',
                 environment: process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || 'production',
+                publishEndpoint: '/_feltdb/publish',
             } : undefined;
-            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || process.env.VITE_FELTDB_MANAGED_API_KEY || '' : '', managedPublish, session }));
+            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || process.env.VITE_FELTDB_MANAGED_API_KEY || '' : '', managedPublish, session, sourceSync: { enabled: true, webllmEnabled, previewOnly, token: studioMutationToken, aiModel: publicAiModelConfiguration() } }));
+            return;
+        }
+        if (pathname === '/_feltdb/contract') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                const current = await loadLocalDevelopmentContract();
+                const lastPublished = fs.existsSync(path.resolve('.feltdb/last-published.json'))
+                    ? JSON.parse(fs.readFileSync(path.resolve('.feltdb/last-published.json'), 'utf8')) : undefined;
+                let runningContract;
+                let runningSnapshot;
+                const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || lastPublished?.applicationId;
+                if (connectUrl && applicationId) {
+                    try {
+                        const endpoint = new URL('/v1/application', connectUrl);
+                        endpoint.searchParams.set('application_id', applicationId);
+                        endpoint.searchParams.set('environment', process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || lastPublished?.environment || 'production');
+                        const headers = {};
+                        const credential = process.env.FELTDB_MANAGED_CONTROL_API_KEY || process.env.VITE_FELTDB_API_KEY;
+                        if (credential)
+                            headers.authorization = `Bearer ${credential}`;
+                        const discovered = await fetch(endpoint, { headers });
+                        if (discovered.ok) {
+                            const application = await discovered.json();
+                            runningSnapshot = application.snapshot;
+                            runningContract = runningSnapshot?.contract_hash ?? application.contract_hash;
+                        }
+                    }
+                    catch { /* Drift remains explicitly unknown while the runtime is unavailable. */ }
+                }
+                const knownContracts = [current.snapshot.contract_hash, runningContract, lastPublished?.contractHash].filter(Boolean);
+                response.end(JSON.stringify({ snapshot: runningSnapshot ?? current.snapshot, flowHash: current.flowHash, source: current.source,
+                    drift: { source: current.snapshot.contract_hash, running: runningContract, published: lastPublished?.contractHash,
+                        synchronized: new Set(knownContracts).size <= 1 } }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/proposals/list' && request.method === 'GET') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                response.end(JSON.stringify(await proposalClient.list()));
+            }
+            catch (error) {
+                response.statusCode = 503;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        const proposalDetail = pathname.match(/^\/_feltdb\/proposals\/(p_[A-Za-z0-9]+)$/);
+        if (proposalDetail && request.method === 'GET') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                response.end(JSON.stringify({ proposal: await proposalClient.get(proposalDetail[1]), history: (await proposalClient.history(proposalDetail[1])).events }));
+            }
+            catch (error) {
+                response.statusCode = 404;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Studio proposes and previews. CLI applies to the repository. FeltDB validates
+        // and stores the proposal as application state. Human approves. Nothing else writes source.
+        if (pathname === '/_feltdb/proposals' || pathname === '/_feltdb/proposals/approve' || pathname === '/_feltdb/proposals/reject') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.method !== 'POST') {
+                response.statusCode = 405;
+                response.end(JSON.stringify({ error: 'POST required' }));
+                return;
+            }
+            if (request.headers['x-feltdb-studio-token'] !== studioMutationToken) {
+                response.statusCode = 403;
+                response.end(JSON.stringify({ error: 'Invalid Studio source-sync token' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {};
+                if (pathname.endsWith('/approve') || pathname.endsWith('/reject')) {
+                    if (previewOnly)
+                        throw new Error('Preview-only sessions cannot approve or reject persisted proposals');
+                    if (input.confirm !== true)
+                        throw new Error('Explicit proposal confirmation is required');
+                    const proposal = await proposalClient.transition(String(input.proposalId || ''), pathname.endsWith('/approve') ? 'approved' : 'rejected', 'studio-developer', false, input.approveAuthorization === true);
+                    response.end(JSON.stringify({ status: proposal.status, proposalId: proposal.id,
+                        command: proposal.status === 'approved' ? `feltdb ai apply ${proposal.id}` : undefined }));
+                }
+                else {
+                    const proposal = input.proposal;
+                    const review = await reviewFlowProposal(proposal);
+                    const changes = describeProposal(review);
+                    let stored;
+                    if (!previewOnly) {
+                        const current = await loadLocalDevelopmentContract();
+                        stored = await proposalClient.create({ application_id: current.snapshot.application.application_id,
+                            environment: current.snapshot.application.environment, base_contract_hash: proposal.baseContractHash,
+                            base_flow_hash: proposal.baseFlowHash, proposed_flow: proposal.proposedFlow, summary: proposal.summary,
+                            warnings: proposal.warnings, actor: 'studio-developer', metadata: { model: publicAiModelConfiguration().model, created_from: 'studio' } });
+                        await proposalClient.validate(stored.id, 'feltdb-validator', review.proposedContract.manifest);
+                        stored = (await proposalClient.preview(stored.id, 'studio-developer')).proposal;
+                    }
+                    response.end(JSON.stringify({ status: 'previewed', proposalId: stored?.id ?? 'ephemeral', changes,
+                        sourcePlan: stored?.source_plan.files.map(value => value.path) ?? ['feltdb.flow', 'src/feltdb/generated-contract.ts'], previewOnly,
+                        authorizationChanges: review.authorizationChanges, migration: review.migration,
+                        contractHash: review.proposedContract.hashes.application }));
+                }
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/ai/generate') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.method !== 'POST') {
+                response.statusCode = 405;
+                response.end(JSON.stringify({ error: 'POST required' }));
+                return;
+            }
+            if (request.headers['x-feltdb-studio-token'] !== studioMutationToken) {
+                response.statusCode = 403;
+                response.end(JSON.stringify({ error: 'Invalid Studio token' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                if (!input.intent?.trim())
+                    throw new Error('An AI change request is required');
+                const current = await loadLocalDevelopmentContract();
+                const proposal = await generateConfiguredFlowProposal({ intent: input.intent, snapshot: current.snapshot, currentFlow: current.source });
+                response.end(JSON.stringify({ proposal }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/publish') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.method !== 'POST') {
+                response.statusCode = 405;
+                response.end(JSON.stringify({ error: 'POST required' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {};
+                const messages = [];
+                const result = await publishApplication({ dryRun: Boolean(input.dryRun), status: Boolean(input.status), yes: true, noBuild: true, environment: input.environment, approveDestructive: Boolean(input.approveDestructive), message: input.message, log: message => messages.push(message) });
+                response.end(JSON.stringify({ status: result.status, messages, version: result.revision?.revision_number, validation: result.validation, changes: result.diff?.changes, securityChanges: result.diff?.security_changes }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
             return;
         }
         if (pathname === '/_feltdb/project') {
@@ -1406,6 +1746,19 @@ Commands:
   diff [file]           Diff FlowSpec against the last deployed model
   deploy [file]         Validate, version, and deploy FlowSpec
   publish [file]        Build and publish/update a managed application
+  ai                    Open the canonical interactive local-AI workflow
+  ai --dry-run          Open an ephemeral preview-only AI session
+  ai model show         Show the selected local or user-provided model
+  ai model set          Select WebLLM or an OpenAI-compatible model
+  ai context            Show the secret-free contract grounding snapshot
+  ai review <file>      Validate and review a WebLLM flow proposal
+  ai apply <id>         Apply an approved proposal and synchronize source
+  proposals             List durable FeltDB application proposals
+  proposals get <id>    Show a proposal and its lifecycle history
+  proposals diff <id>   Show contract and structured source impact
+  proposals approve <id> Approve a previewed proposal
+  proposals reject <id> Reject a proposed/validated/previewed proposal
+  sync                  Regenerate owned source from feltdb.flow
   studio               Launch FeltDB Studio (developer interface)
   server               Start self-hosted FeltDB server
   keys                 Manage API keys
@@ -1444,6 +1797,13 @@ Connection:
   doctor      Check system health
   help        Show this help message
 
+Publish:
+  feltdb publish --dry-run                  Validate and preview without activation
+  feltdb publish --yes                      Publish to the configured environment
+  feltdb publish --status                   Compare local and active cloud versions
+  feltdb publish --environment staging      Override the configured environment
+  feltdb publish --approve-destructive-changes --yes
+
 Inspect Sub-commands:
   feltdb inspect              Show runtime overview
   feltdb inspect peers        Show connected peers
@@ -1467,6 +1827,7 @@ Examples:
   feltdb status
   feltdb dev
   feltdb build
+  feltdb publish --dry-run
   feltdb check
   feltdb inspect
   feltdb inspect peers