@feltdb/core 0.7.4 → 0.8.0

package/dist/cli/commands.js

@@ -8,16 +8,19 @@ import net from 'net';
 import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
 import { randomBytes } from 'crypto';
-import { createFeltDB, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
+import { createInterface } from 'node:readline/promises';
+import { createFeltDB, createModuleImplementationProposal, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, listFeltDBModules, parseFlowSpec, planFlowSpecMigration, renderProposalDiagnostic, resolveFeltDBModule, resolveModuleIntent, 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 { applyFlowProposalAtomic, assertProposalSourcePlan, describeProposal, loadLocalDevelopmentContract, repositoryContext, reviewFlowProposal, syncGeneratedSource } from './source-sync.js';
 import { configureAiModel, generateConfiguredFlowProposal, publicAiModelConfiguration } from './ai-model-config.js';
 import { proposalService } from './proposal-client.js';
+import { resolveManagedAuthorityEnvironment } from './managed-environment.js';
+import { readManagedProjectState } from './managed-project.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -87,6 +90,9 @@ export async function handleCommand(command, args) {
             return handleAi(args);
         case 'proposals':
             return handleProposals(args);
+        case 'module':
+        case 'modules':
+            return handleModules(args);
         case 'sync':
             return handleSourceSync(args);
         case 'help':
@@ -94,6 +100,24 @@ export async function handleCommand(command, args) {
             return handleHelp();
     }
 }
+function handleModules(args) {
+    const action = args[0] || 'list';
+    if (action === 'list') {
+        for (const module of listFeltDBModules())
+            console.log(`${module.id}\t${module.version}\t${module.compatibility.join(', ')}`);
+        return;
+    }
+    if (action === 'inspect' && args[1]) {
+        const flowPath = path.resolve('feltdb.flow');
+        const spec = args.includes('--application') && fs.existsSync(flowPath) ? parseFlowSpec(fs.readFileSync(flowPath, 'utf8')) : undefined;
+        const declaration = spec?.modules?.find(value => value.name === args[1]);
+        const module = resolveFeltDBModule(declaration ?? { name: args[1], provider: args.find((value, index) => index > 1 && !value.startsWith('--')) || 'stripe-compatible' });
+        const usage = spec?.collections.flatMap(collection => collection.fields.filter(field => field.type.startsWith(`ref ${module.id}.`)).map(field => `${collection.name}.${field.name} -> ${field.type.slice(4)}`)) ?? [];
+        console.log(JSON.stringify({ ...module, application_usage: usage }, null, 2));
+        return;
+    }
+    throw new Error('Usage: feltdb module [list|inspect <id> [provider]]');
+}
 function proposalFile(args) {
     const value = args.find(argument => !argument.startsWith('--') && !['review', 'apply'].includes(argument));
     if (!value)
@@ -103,12 +127,18 @@ function proposalFile(args) {
 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'))
+    if (args.includes('--no-build'))
+        return;
+    const verification = ['typecheck', 'test', 'build'].filter(name => projectPackage.scripts?.[name]);
+    if (!verification.length)
         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`);
+    for (const name of verification) {
+        const checked = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', name], { cwd: process.cwd(), stdio: 'inherit' });
+        if (checked.status !== 0)
+            throw new Error(`APPLICATION_VALIDATION_FAILED: ${name} exited ${checked.status ?? 'without a status'}; repository restored and proposal remains approved`);
+        console.log(`✓ ${name} passed`);
+    }
 }
 async function handleAi(args) {
     loadProjectEnvironment();
@@ -141,6 +171,44 @@ async function handleAi(args) {
         return handleStudio(args, studioUrl => console.log(`Ask FeltDB: ${studioUrl}`));
     }
     const action = args[0];
+    if (action === 'proposals')
+        return handleProposals(['list', ...args.slice(1)]);
+    if (action === 'proposal') {
+        const id = args[1];
+        if (!id)
+            throw new Error('Usage: feltdb ai proposal <id> [--history]');
+        return handleProposals(['get', id, ...args.slice(2)]);
+    }
+    if (action === 'approve') {
+        const id = args[1];
+        if (!id)
+            throw new Error('Usage: feltdb ai approve <id> [--yes]');
+        const client = proposalService();
+        const proposal = await client.get(id);
+        const readiness = await client.status(id);
+        if (proposal.status !== 'previewed')
+            throw new Error(`Cannot approve Proposal ${id}. Current status: ${proposal.status}. A current preview is required.`);
+        if (readiness.blockers.length)
+            throw new Error(`Cannot approve Proposal ${id}. ${readiness.blockers.join(', ')}. Regenerate the Proposal before approval.`);
+        if (!proposal.preview_id)
+            throw new Error(`Cannot approve Proposal ${id}. Preview is missing.`);
+        await client.getPreview(proposal.preview_id);
+        console.log(renderProposalDiagnostic(proposal, { readiness }).join('\n'));
+        console.log('Repository source will NOT be modified by approval.');
+        let approved = args.includes('--yes');
+        if (!approved && process.stdin.isTTY) {
+            const prompt = createInterface({ input: process.stdin, output: process.stdout });
+            approved = /^y(?:es)?$/i.test(await prompt.question('Approve this proposal? [y/N] '));
+            prompt.close();
+        }
+        if (!approved) {
+            console.log('Approval cancelled.');
+            return;
+        }
+        const value = await client.approve(id, 'cli-developer', args.includes('--approve-authorization'));
+        console.log(`✓ Proposal ${value.id} approved`);
+        return;
+    }
     if (action === 'context') {
         const context = await loadLocalDevelopmentContract();
         console.log(JSON.stringify({ snapshot: context.snapshot, flowHash: context.flowHash }, null, 2));
@@ -166,7 +234,7 @@ async function handleAi(args) {
             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}`);
+            throw new Error(`Cannot apply Proposal ${stored.id}. Current status: ${stored.status}. Approval is required. Run: feltdb ai approve ${stored.id}`);
         if (!stored && !args.includes('--approve'))
             throw new Error('Explicit approval is required: rerun with --approve');
         const current = await loadLocalDevelopmentContract();
@@ -177,12 +245,26 @@ async function handleAi(args) {
         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 applyFlowProposalAtomic({ ...proposal, baseContractHash: current.snapshot.contract_hash, baseFlowHash: current.flowHash, proposedFlow: current.source }, process.cwd(), {
+                approveAuthorization: true, replaceGenerated: args.includes('--replace-generated'), verify: () => validateRepositoryBuild(args),
+            });
             await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
             console.log(`✓ Reconciled and marked ${stored.id} applied`);
             return;
         }
+        if (stored) {
+            const client = proposalService();
+            const readiness = await client.status(stored.id);
+            if (readiness.blockers.length)
+                throw new Error(`Cannot apply Proposal ${stored.id}. Proposal is stale: ${readiness.blockers.join(', ')}. Proposal contract: ${stored.base_contract_hash}. Current contract: ${readiness.current_contract_hash}. Regenerate the Proposal before applying.`);
+            if (!stored.preview_id)
+                throw new Error(`Cannot apply Proposal ${stored.id}. A current preview is required.`);
+            await client.getPreview(stored.preview_id);
+            assertProposalSourcePlan(stored.source_plan);
+            const repository = await repositoryContext(process.cwd(), stored.source_plan.files.map(value => value.path));
+            if (repository.dirty.length && !args.includes('--allow-dirty'))
+                throw new Error(`Cannot apply Proposal ${stored.id}. Repository conflict: ${repository.dirty.join(', ')}. Resolve the conflict and retry.`);
+        }
         const reviewOnly = await reviewFlowProposal(proposal);
         console.log(`\n${proposal.summary || 'FeltDB change proposal'}`);
         for (const line of describeProposal(reviewOnly))
@@ -192,20 +274,67 @@ async function handleAi(args) {
             console.log('✓ Preview complete. No files, flow, contract, or published state were changed.');
             return;
         }
-        const review = await applyFlowProposal(proposal, process.cwd(), {
+        let confirmed = args.includes('--yes');
+        if (!confirmed && process.stdin.isTTY) {
+            const prompt = createInterface({ input: process.stdin, output: process.stdout });
+            confirmed = /^y(?:es)?$/i.test(await prompt.question(`Apply ${stored?.id || 'this proposal'} to repository source? [y/N] `));
+            prompt.close();
+        }
+        if (!confirmed)
+            throw new Error('Apply cancelled. Re-run with --yes for non-interactive application.');
+        const review = await applyFlowProposalAtomic(proposal, process.cwd(), {
             allowDirty: args.includes('--allow-dirty'),
             approveAuthorization: args.includes('--approve-authorization'),
             replaceGenerated: args.includes('--replace-generated'),
+            verify: () => validateRepositoryBuild(args),
         });
         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>]');
+    const developerIntent = args.filter(value => !value.startsWith('--')).join(' ').trim();
+    if (developerIntent) {
+        const resolved = resolveModuleIntent(developerIntent);
+        if (resolved) {
+            console.log('Understanding application...');
+            const current = await loadLocalDevelopmentContract();
+            console.log('✓ Application contract loaded');
+            const proposal = await createModuleImplementationProposal({ intent: developerIntent, snapshot: current.snapshot, currentFlow: current.source });
+            console.log(`✓ ${proposal.implementation?.module.name} ${proposal.implementation?.module.version} resolved`);
+            console.log(`✓ Billing owner: ${proposal.implementation?.owner}`);
+            const review = await reviewFlowProposal(proposal);
+            if (proposal.implementation?.alreadyInstalled) {
+                console.log(`${proposal.implementation.module.name} is already installed.`);
+                const missing = [...review.diff.added, ...review.diff.changed];
+                if (!missing.length) {
+                    console.log('Current implementation is complete. No proposal created.');
+                    return;
+                }
+                console.log('Missing:');
+                for (const value of missing)
+                    console.log(`  ${value}`);
+                console.log('Creating a completion proposal.');
+            }
+            console.log('Generating implementation proposal...');
+            const client = proposalService();
+            const parent = (await client.list({ status: 'applied', limit: 100 })).proposals.find(value => value.metadata?.module === resolved.module);
+            let stored = await client.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,
+                proposal_version: 1, contract_diff: [], source_plan: { files: [] },
+                summary: proposal.summary, warnings: proposal.warnings, actor: 'cli-developer', parent_proposal_id: parent?.id, metadata: { created_from: 'module-intent', module: resolved.module, module_version: resolved.version } });
+            await client.validate(stored.id, 'feltdb-validator', review.proposedContract.manifest);
+            const preview = await client.preview(stored.id, 'cli-developer');
+            stored = preview.proposal;
+            const readiness = await client.status(stored.id);
+            console.log(renderProposalDiagnostic(stored, { readiness, preview: preview }).join('\n'));
+            console.log(`Use:\n  feltdb ai proposal ${stored.id}`);
+            return;
+        }
+    }
+    throw new Error('Usage: feltdb ai ["implement <module>"|context|proposals|proposal <id>|approve <id>|review <proposal.json>|apply <id>]');
 }
 async function handleProposals(args) {
     loadProjectEnvironment();
@@ -213,9 +342,18 @@ async function handleProposals(args) {
     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}`);
+        const option = (name) => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+        const result = await client.list({ status: option('--status'), environment: option('--environment'), limit: option('--limit') ? Number(option('--limit')) : undefined, cursor: option('--cursor') });
+        if (args.includes('--json')) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const { proposals } = result;
+        console.log('PROPOSALS');
+        for (const value of proposals)
+            console.log(`${value.id}\t${value.status.toUpperCase()}\t${value.summary}\t${value.created_at}`);
+        if (result.pagination?.nextCursor)
+            console.log(`Next: --cursor ${result.pagination.nextCursor}`);
         if (!proposals.length)
             console.log('No proposals.');
         return;
@@ -223,7 +361,14 @@ async function handleProposals(args) {
     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));
+        const proposal = await client.get(id);
+        const [readiness, history] = await Promise.all([client.status(id), client.history(id)]);
+        const preview = proposal.preview_id ? await client.getPreview(proposal.preview_id).catch(() => undefined) : undefined;
+        const result = { proposal, readiness, preview, history: history.events };
+        if (args.includes('--json'))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.log(renderProposalDiagnostic(proposal, { readiness, history: history.events, preview: preview }).join('\n'));
         return;
     }
     if (action === 'diff') {
@@ -233,7 +378,7 @@ async function handleProposals(args) {
         return;
     }
     if (action === 'approve' || action === 'reject') {
-        const value = await client.transition(id, action === 'approve' ? 'approved' : 'rejected', 'local-developer', false, args.includes('--approve-authorization'));
+        const value = action === 'approve' ? await client.approve(id, 'local-developer', args.includes('--approve-authorization')) : await client.reject(id, 'local-developer');
         console.log(`✓ ${value.id} ${value.status}`);
         return;
     }
@@ -617,9 +762,11 @@ For more info, visit: https://github.com/rkendel1/feltdb
 }
 async function handleConnect(args) {
     loadProjectEnvironment();
+    const managed = readManagedProjectState();
     const projectFile = path.resolve('feltdb.config.json');
     const project = fs.existsSync(projectFile) ? JSON.parse(fs.readFileSync(projectFile, 'utf8')) : {};
     const url = (args[0]
+        || managed.url
         || process.env.VITE_FELTDB_MANAGED_URL
         || process.env.VITE_FELTDB_URL
         || project.server?.url
@@ -634,8 +781,8 @@ async function handleConnect(args) {
     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}` }
+            headers: process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY
+                ? { Authorization: `Bearer ${process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY}` }
                 : {},
             signal: controller.signal,
         });
@@ -658,14 +805,14 @@ async function handleConnect(args) {
     fs.writeFileSync(connFile, JSON.stringify({
         url,
         connected: new Date().toISOString(),
-        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',
+        authenticated: Boolean(process.env.FELTDB_TOKEN || process.env.VITE_FELTDB_API_KEY),
+        namespace: managed.namespace || project.namespace || 'default',
         runtime: project.runtime || 'self-hosted',
     }, null, 2));
     console.log('✅ Connected to FeltDB\n');
     console.log('Endpoint:     ' + url);
-    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(`Namespace:    ${managed.namespace || project.namespace || 'default'}`);
+    console.log(`Authenticated: ${process.env.FELTDB_TOKEN || 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');
@@ -780,7 +927,7 @@ async function handleWorkspaceConnect(args) {
     console.log('   (when @feltdb/client workspace APIs are available)\n');
 }
 async function handleDev(args) {
-    var _a, _b, _c;
+    var _a;
     const projectDir = process.cwd();
     if (args.includes('--help')) {
         console.log('Usage: feltdb dev [--app-url URL] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
@@ -833,14 +980,10 @@ async function handleDev(args) {
         ? { ...configDefaults, ...JSON.parse(fs.readFileSync(configPath, 'utf-8')) }
         : configDefaults;
     if (config.runtime === 'managed') {
-        (_a = process.env).VITE_FELTDB_URL || (_a.VITE_FELTDB_URL = process.env.VITE_FELTDB_MANAGED_URL);
-        (_b = process.env).VITE_FELTDB_API_KEY || (_b.VITE_FELTDB_API_KEY = process.env.VITE_FELTDB_MANAGED_API_KEY);
-    }
-    if (config.runtime === 'managed' && (!process.env.VITE_FELTDB_URL || !process.env.VITE_FELTDB_API_KEY)) {
-        throw new Error('Managed runtime requires VITE_FELTDB_MANAGED_URL and VITE_FELTDB_MANAGED_API_KEY in .env.local. Re-run managed setup or add your managed connection.');
+        resolveManagedAuthorityEnvironment(process.env);
     }
     const runtimeNamespace = config.runtime === 'managed'
-        ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
+        ? readManagedProjectState(projectDir).namespace || config.namespace
         : config.namespace;
     const applicationLifecycle = resolveApplicationLifecycle(config);
     // Application URL precedence:
@@ -929,7 +1072,7 @@ async function handleDev(args) {
         if (compose.status !== 0)
             throw new Error(`docker compose failed with status ${compose.status ?? 'unknown'}`);
         selfHostedStarted = true;
-        (_c = process.env).VITE_FELTDB_URL || (_c.VITE_FELTDB_URL = 'http://127.0.0.1:7700');
+        (_a = process.env).VITE_FELTDB_URL || (_a.VITE_FELTDB_URL = 'http://127.0.0.1:7700');
     }
     if (!process.env.VITE_FELTDB_URL) {
         const authorityPort = Number(args.includes('--authority-port') ? args[args.indexOf('--authority-port') + 1] || '7700' : '7700');
@@ -1403,10 +1546,11 @@ async function handleStudio(args, onReady) {
     loadProjectEnvironment();
     const projectConfigPath = path.resolve('feltdb.config.json');
     const projectConfig = fs.existsSync(projectConfigPath) ? JSON.parse(fs.readFileSync(projectConfigPath, 'utf8')) : {};
+    const managedProject = readManagedProjectState();
     const projectIsManaged = projectConfig.runtime === 'managed';
     const connectUrl = args.includes('--connect')
         ? args[args.indexOf('--connect') + 1]
-        : projectIsManaged ? process.env.VITE_FELTDB_MANAGED_URL : undefined;
+        : projectIsManaged ? process.env.VITE_FELTDB_MANAGED_URL || managedProject.url : undefined;
     const port = args.includes('--port')
         ? args[args.indexOf('--port') + 1] || '7701'
         : '7701';
@@ -1416,10 +1560,16 @@ async function handleStudio(args, onReady) {
     const open = !args.includes('--no-open');
     const namespace = args.includes('--namespace')
         ? args[args.indexOf('--namespace') + 1] || 'default'
-        : projectIsManaged ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || projectConfig.namespace || 'default' : 'default';
+        : projectIsManaged ? managedProject.namespace || projectConfig.namespace || 'default' : 'default';
     const runtime = args.includes('--runtime')
         ? args[args.indexOf('--runtime') + 1] || 'browser'
         : projectIsManaged ? 'managed' : connectUrl ? 'remote' : 'browser';
+    const applicationId = args.includes('--application')
+        ? args[args.indexOf('--application') + 1] || ''
+        : process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managedProject.applicationId || '';
+    const environment = args.includes('--environment')
+        ? args[args.indexOf('--environment') + 1] || 'production'
+        : managedProject.environment || 'production';
     const appUrl = args.includes('--app-url')
         ? args[args.indexOf('--app-url') + 1]
         : undefined;
@@ -1465,14 +1615,14 @@ async function handleStudio(args, onReady) {
             response.setHeader('Cache-Control', 'no-store');
             response.setHeader('Pragma', 'no-cache');
             const managedPublish = runtime === 'managed' ? {
-                url: process.env.VITE_FELTDB_MANAGED_URL || connectUrl || '',
-                namespace: process.env.VITE_FELTDB_MANAGED_NAMESPACE || namespace,
-                tenantId: process.env.VITE_FELTDB_MANAGED_TENANT_ID || '',
-                applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || '',
-                environment: process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || 'production',
+                url: connectUrl || managedProject.url || '',
+                namespace: managedProject.namespace || namespace,
+                tenantId: managedProject.tenantId || '',
+                applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managedProject.applicationId || '',
+                environment: managedProject.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, sourceSync: { enabled: true, webllmEnabled, previewOnly, token: studioMutationToken, aiModel: publicAiModelConfiguration() } }));
+            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '', managedPublish, session, sourceSync: { enabled: true, webllmEnabled, previewOnly, token: studioMutationToken, aiModel: publicAiModelConfiguration() } }));
             return;
         }
         if (pathname === '/_feltdb/contract') {
@@ -1484,12 +1634,12 @@ async function handleStudio(args, onReady) {
                     ? 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;
+                const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managedProject.applicationId || 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');
+                        endpoint.searchParams.set('environment', managedProject.environment || lastPublished?.environment || 'production');
                         const headers = {};
                         const credential = process.env.FELTDB_MANAGED_CONTROL_API_KEY || process.env.VITE_FELTDB_API_KEY;
                         if (credential)
@@ -1514,6 +1664,29 @@ async function handleStudio(args, onReady) {
             }
             return;
         }
+        if (pathname === '/_feltdb/repository-readiness' && request.method === 'GET') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            try {
+                const proposalId = new URL(request.url || '/', 'http://localhost').searchParams.get('proposal');
+                if (!proposalId)
+                    throw new Error('proposal is required');
+                const proposal = await proposalClient.get(proposalId);
+                assertProposalSourcePlan(proposal.source_plan);
+                const local = await loadLocalDevelopmentContract();
+                const repository = await repositoryContext(process.cwd(), proposal.source_plan.files.map(value => value.path));
+                const contractMatches = local.snapshot.contract_hash === proposal.base_contract_hash;
+                const flowMatches = local.flowHash === proposal.base_flow_hash;
+                response.end(JSON.stringify({ ready: contractMatches && flowMatches && repository.dirty.length === 0,
+                    contractMatches, flowMatches, gitClean: repository.dirty.length === 0, conflicts: repository.dirty,
+                    branch: repository.branch, commit: repository.commit }));
+            }
+            catch (error) {
+                response.statusCode = 409;
+                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');
@@ -1578,6 +1751,7 @@ async function handleStudio(args, onReady) {
                         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,
+                            proposal_version: 1, contract_diff: [], source_plan: { files: [] },
                             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;
@@ -1715,6 +1889,9 @@ async function handleStudio(args, onReady) {
     const parameters = new URLSearchParams({ namespace, runtime });
     if (connectUrl)
         parameters.set('connect', connectUrl);
+    if (applicationId)
+        parameters.set('application_id', applicationId);
+    parameters.set('environment', environment);
     if (appUrl)
         parameters.set('app', appUrl);
     if (session.workspaceId)
@@ -1751,9 +1928,14 @@ Commands:
   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 proposals          List bounded proposals [--status/--environment/--json]
+  ai proposal <id>      Show canonical proposal, readiness, preview, and history
+  ai approve <id>       Approve a current preview [--yes]
   ai review <file>      Validate and review a WebLLM flow proposal
-  ai apply <id>         Apply an approved proposal and synchronize source
+  ai apply <id>         Atomically apply an approved proposal [--yes]
   proposals             List durable FeltDB application proposals
+  module list           List deterministic FeltDB modules
+  module inspect <id>   Inspect a resolved module semantic contract
   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
@@ -1776,6 +1958,7 @@ Commands:
 Studio:
   feltdb studio                              Launch local Studio
   feltdb studio --connect <url>              Connect to remote instance
+    --application <id> --environment <name>  Select one application environment
   feltdb studio --port 7701 --no-open        Start on port 7701 without opening browser
 
 Server Options:

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { getClient } from './api-client.js';
 import { loadFeltDBConfig, createDefaultConfig, validateModel, } from './config.js';
-const VERSION = '0.7.4';
+const VERSION = '0.8.0';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/cli/managed-environment.js

@@ -0,0 +1,6 @@
+export function resolveManagedAuthorityEnvironment(environment) {
+    environment.VITE_FELTDB_URL || (environment.VITE_FELTDB_URL = environment.VITE_FELTDB_MANAGED_URL);
+    if (!environment.VITE_FELTDB_URL) {
+        throw new Error('Managed runtime requires VITE_FELTDB_MANAGED_URL in .env.local. Re-run managed setup or add your managed connection.');
+    }
+}

package/dist/cli/managed-project.js

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function readManagedProjectState(cwd = process.cwd()) {
+    const file = path.join(cwd, '.feltdb', 'managed.json');
+    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+}

package/dist/cli/proposal-client.js

@@ -9,10 +9,11 @@ export function developmentProposalConnection(cwd = process.cwd()) {
         throw new Error('No running FeltDB proposal service. Start feltdb dev.');
     const config = fs.existsSync(path.join(cwd, 'feltdb.config.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, 'feltdb.config.json'), 'utf8')) : {};
     const published = fs.existsSync(path.join(cwd, '.feltdb', 'last-published.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, '.feltdb', 'last-published.json'), 'utf8')) : {};
+    const managed = fs.existsSync(path.join(cwd, '.feltdb', 'managed.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, '.feltdb', 'managed.json'), 'utf8')) : {};
     const flowApplication = fs.existsSync(path.join(cwd, 'feltdb.flow')) ? parseFlowSpec(fs.readFileSync(path.join(cwd, 'feltdb.flow'), 'utf8')).app : undefined;
     return { endpoint: endpoint.replace(/\/$/, ''), proposalAuthorityToken: stored?.proposalAuthorityToken,
-        applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || published.applicationId || config.applicationId || flowApplication,
-        environment: process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || published.environment || 'local' };
+        applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managed.applicationId || published.applicationId || config.applicationId || flowApplication,
+        environment: managed.environment || published.environment || 'local' };
 }
 export class ProposalServiceClient {
     constructor(connection, token = process.env.FELTDB_MANAGED_CONTROL_API_KEY || '') {
@@ -38,11 +39,19 @@ export class ProposalServiceClient {
     }
     actor(input = {}) { return { application_id: this.connection.applicationId, environment: this.connection.environment, ...input }; }
     create(input) { return this.request('/v1/proposals', { method: 'POST', body: JSON.stringify(input) }); }
-    list() { return this.request(this.scoped('/v1/proposals')); }
+    list(filters = {}) { const query = new URLSearchParams(); if (this.connection.applicationId)
+        query.set('application_id', this.connection.applicationId); query.set('environment', filters.environment || this.connection.environment || 'local'); if (filters.status)
+        query.set('status', filters.status); if (filters.limit)
+        query.set('limit', String(filters.limit)); if (filters.cursor)
+        query.set('cursor', filters.cursor); return this.request(`/v1/proposals?${query}`); }
     get(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}`)); }
     history(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/history`)); }
+    status(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/status`)); }
     validate(id, actor = 'local-developer', proposedManifest) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/validate`, { method: 'POST', body: JSON.stringify(this.actor({ actor, proposed_manifest: proposedManifest })) }); }
     preview(id, actor = 'local-developer') { return this.request(`/v1/proposals/${encodeURIComponent(id)}/preview`, { method: 'POST', body: JSON.stringify(this.actor({ actor })) }); }
+    getPreview(id) { return this.request(this.scoped(`/v1/previews/${encodeURIComponent(id)}`)); }
+    approve(id, actor = 'local-developer', approveAuthorization = false) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/approve`, { method: 'POST', body: JSON.stringify(this.actor({ actor, approve_authorization: approveAuthorization })) }); }
+    reject(id, actor = 'local-developer', reason) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/reject`, { method: 'POST', body: JSON.stringify(this.actor({ actor, reason })) }); }
     transition(id, status, actor = 'local-developer', repositoryAuthority = false, approveAuthorization = false) {
         return this.request(`/v1/proposals/${encodeURIComponent(id)}/status`, { method: 'PATCH', headers: repositoryAuthority && this.connection.proposalAuthorityToken
                 ? { 'FeltDB-Proposal-Authority': this.connection.proposalAuthorityToken, 'FeltDB-Repository-Apply': '1' } : {}, body: JSON.stringify(this.actor({ status, actor, approve_authorization: approveAuthorization })) });

package/dist/cli/publish-engine.js

@@ -25,12 +25,14 @@ export function discoverPublishConfiguration(cwd = process.cwd(), environmentOve
         throw new Error('feltdb.config.json is required for publish');
     const project = JSON.parse(fs.readFileSync(configFile, 'utf8'));
     const file = loadEnv(path.join(cwd, '.env.local'));
+    const managedFile = path.join(cwd, '.feltdb', 'managed.json');
+    const managed = fs.existsSync(managedFile) ? JSON.parse(fs.readFileSync(managedFile, 'utf8')) : {};
     const value = (name) => process.env[name] || file[name];
     const configuration = {
-        url: value('VITE_FELTDB_MANAGED_URL'), token: value('FELTDB_MANAGED_CONTROL_API_KEY'),
-        tenantId: value('VITE_FELTDB_MANAGED_TENANT_ID'), applicationId: value('VITE_FELTDB_MANAGED_APPLICATION_ID'),
-        namespace: value('VITE_FELTDB_MANAGED_NAMESPACE') || project.namespace,
-        environment: environmentOverride || value('VITE_FELTDB_MANAGED_ENVIRONMENT') || 'production',
+        url: value('VITE_FELTDB_MANAGED_URL') || managed.url, token: value('FELTDB_MANAGED_CONTROL_API_KEY'),
+        tenantId: managed.tenantId || value('VITE_FELTDB_MANAGED_TENANT_ID'), applicationId: value('VITE_FELTDB_MANAGED_APPLICATION_ID') || managed.applicationId,
+        namespace: managed.namespace || value('VITE_FELTDB_MANAGED_NAMESPACE') || project.namespace,
+        environment: environmentOverride || managed.environment || value('VITE_FELTDB_MANAGED_ENVIRONMENT') || 'production',
     };
     const missing = Object.entries(configuration).filter(([, value]) => !value).map(([name]) => name);
     if (missing.length)
@@ -75,6 +77,7 @@ export function buildPublishBundle(cwd, configuration) {
         'feltdb.agent_hash': contractHash(manifest.agents),
         'feltdb.capability_hash': contractHash(manifest.capabilities),
         'feltdb.contract_hash': contractHash({ dsl_version: spec.version, manifest }),
+        'feltdb.flow_hash': `sha256:${sha256(flowSource.replace(/\r\n/g, '\n'))}`,
         'feltdb.artifact_hash': artifactHash,
         'feltdb.namespace': configuration.namespace,
     };