@feltdb/core 0.6.10 → 0.6.12

package/dist/cli/application-lifecycle.js

@@ -0,0 +1,112 @@
+import path from 'path';
+import { spawn } from 'child_process';
+import { applicationIsRunning } from './application.js';
+export function resolveApplicationLifecycle(config) {
+    const lifecycle = config.application?.lifecycle;
+    if (lifecycle === undefined)
+        return 'attached';
+    if (lifecycle !== 'managed' && lifecycle !== 'attached') {
+        throw new Error(`Invalid application.lifecycle "${lifecycle}"; expected managed or attached`);
+    }
+    return lifecycle;
+}
+function commandTokens(source) {
+    const tokens = [];
+    let token = '';
+    let quote = '';
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (quote) {
+            if (character === quote)
+                quote = '';
+            else if (character === '\\' && quote === '"' && index + 1 < source.length)
+                token += source[++index];
+            else
+                token += character;
+        }
+        else if (character === '"' || character === "'")
+            quote = character;
+        else if (/\s/.test(character)) {
+            if (token) {
+                tokens.push(token);
+                token = '';
+            }
+        }
+        else
+            token += character;
+    }
+    if (quote)
+        throw new Error(`Cannot run managed application command with an unclosed quote: ${source}`);
+    if (token)
+        tokens.push(token);
+    return tokens;
+}
+export function resolveManagedApplicationCommand(project) {
+    const source = project.devScript?.trim();
+    if (!source)
+        throw new Error('Managed application lifecycle requires package.json.scripts.dev');
+    const tokens = commandTokens(source);
+    const environment = {};
+    while (tokens[0] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0])) {
+        const assignment = tokens.shift();
+        const separator = assignment.indexOf('=');
+        environment[assignment.slice(0, separator)] = assignment.slice(separator + 1);
+    }
+    const executable = tokens.shift();
+    if (!executable)
+        throw new Error(`Managed application command is empty: ${source}`);
+    if (executable === 'feltdb' || (executable === 'npm' && tokens[0] === 'run')) {
+        throw new Error(`Refusing recursive managed application command: ${source}`);
+    }
+    if (/[|&;<>`]/.test(source)) {
+        throw new Error(`Managed application command must be directly executable without shell operators: ${source}`);
+    }
+    return { source, executable, args: tokens, environment };
+}
+export function startManagedApplication(options) {
+    const command = resolveManagedApplicationCommand(options.project);
+    const localBin = path.join(options.projectDir, 'node_modules', '.bin');
+    const inherited = options.environment ?? process.env;
+    const child = spawn(command.executable, command.args, {
+        cwd: options.projectDir,
+        stdio: 'inherit',
+        shell: false,
+        env: {
+            ...inherited,
+            ...command.environment,
+            PATH: `${localBin}${path.delimiter}${inherited.PATH || ''}`,
+        },
+    });
+    const exited = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (code, signal) => resolve({ code, signal }));
+    });
+    return {
+        command: command.source,
+        child,
+        exited,
+        async stop() {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill('SIGTERM');
+            await Promise.race([exited.catch(() => undefined), new Promise(resolve => setTimeout(resolve, 2000))]);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL');
+        },
+    };
+}
+export async function waitForManagedApplication(options) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < options.timeoutMs) {
+        if (await applicationIsRunning(options.expectedUrl, Math.min(500, options.timeoutMs)))
+            return;
+        const exit = await Promise.race([
+            options.application.exited,
+            new Promise(resolve => setTimeout(() => resolve(null), 100)),
+        ]);
+        if (exit) {
+            throw new Error(`Managed application exited before readiness (command: ${options.application.command}; expected URL: ${options.expectedUrl}; workspace: ${options.workspaceId}; project: ${options.projectDir}; exit: ${exit.code ?? exit.signal})`);
+        }
+    }
+    throw new Error(`Managed application readiness timed out after ${options.timeoutMs}ms (command: ${options.application.command}; expected URL: ${options.expectedUrl}; workspace: ${options.workspaceId}; project: ${options.projectDir})`);
+}

package/dist/cli/application.js

@@ -44,12 +44,22 @@ export function detectApplication(root) {
     const dependencies = { ...manifest.dependencies, ...manifest.devDependencies };
     const framework = FRAMEWORKS.find(candidate => candidate.packages.some(name => name in dependencies) || (script ? candidate.pattern.test(script) : false));
     const feltConfigFile = path.join(root, 'feltdb.config.json');
+    const flowFile = path.join(root, 'feltdb.flow');
     const feltConfig = fs.existsSync(feltConfigFile) ? readJson(feltConfigFile, 'Cannot inspect application: malformed feltdb.config.json') : {};
+    const feltDBSignals = [];
+    if ('@feltdb/core' in dependencies)
+        feltDBSignals.push('dependency');
+    if (fs.existsSync(feltConfigFile))
+        feltDBSignals.push('config');
+    if (fs.existsSync(flowFile))
+        feltDBSignals.push('flow');
     const configuredUrl = typeof feltConfig.appUrl === 'string' ? feltConfig.appUrl
         : typeof feltConfig.applicationUrl === 'string' ? feltConfig.applicationUrl : undefined;
     return {
         packageManager: packageManagerAt(root, typeof manifest.packageManager === 'string' ? manifest.packageManager : undefined),
         framework: framework?.name || (script ? 'Custom' : 'Unknown'),
+        feltDBEnabled: feltDBSignals.length > 0,
+        feltDBSignals,
         devScript: script,
         configuredPort: scriptPort(script),
         configuredUrl,

package/dist/cli/commands.js

@@ -7,9 +7,12 @@ import http from 'http';
 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 { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
-import { detectApplication, discoverApplicationUrl } from './application.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';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -512,6 +515,7 @@ async function handleDev(args) {
         console.log('  --studio-port <port>      FeltDB Studio port (default: 7701)');
         console.log('  --authority-port <port>   Authority port (default: 7700)');
         console.log('  --discovery-port <port>   Pairing discovery port (default: 7799)');
+        console.log('  --application-timeout <ms> Managed application readiness timeout (default: 15000)');
         console.log('  --no-open                 Do not open Studio in browser');
         return;
     }
@@ -542,30 +546,18 @@ async function handleDev(args) {
     }
     // Investigation lifecycle manager will be initialized when needed
     // const investigationManager = new InvestigationLifecycleManager(projectDir);
-    // Create feltdb.config.json if it doesn't exist
-    if (!fs.existsSync(configPath)) {
-        const packageJsonPath = path.join(projectDir, 'package.json');
-        let namespace = path.basename(projectDir);
-        if (fs.existsSync(packageJsonPath)) {
-            try {
-                const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-                namespace = packageJson.name || namespace;
-            }
-            catch {
-                // Use default namespace if package.json parsing fails
-            }
-        }
-        const defaultConfig = {
-            namespace,
-            runtime: 'browser',
-            storage: 'indexeddb',
-            distributed: true,
-            applicationUrl: null,
-        };
-        fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n');
-        console.log(`✨ Created feltdb.config.json\n`);
-    }
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    // Existing applications may attach without adopting generated FeltDB source.
+    // Missing developer-owned config is resolved in memory and never written.
+    const configDefaults = {
+        namespace: workspace.projectId,
+        runtime: 'browser',
+        storage: 'indexeddb',
+        distributed: true,
+        applicationUrl: null,
+    };
+    const config = fs.existsSync(configPath)
+        ? { ...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);
@@ -576,6 +568,7 @@ async function handleDev(args) {
     const runtimeNamespace = config.runtime === 'managed'
         ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
         : config.namespace;
+    const applicationLifecycle = resolveApplicationLifecycle(config);
     // Application URL precedence:
     // 1. --app-url (highest priority)
     // 2. feltdb.config.json applicationUrl
@@ -604,7 +597,7 @@ async function handleDev(args) {
             detectedApplication = detectApplication(projectDir);
         }
         catch {
-            detectedApplication = { packageManager: 'npm', framework: 'External' };
+            detectedApplication = { packageManager: 'npm', framework: 'External', feltDBEnabled: false, feltDBSignals: [] };
         }
     }
     else {
@@ -615,16 +608,25 @@ async function handleDev(args) {
                 detectedApplication = detectApplication(projectDir);
             }
             catch {
-                detectedApplication = { packageManager: 'npm', framework: 'External' };
+                detectedApplication = { packageManager: 'npm', framework: 'External', feltDBEnabled: false, feltDBSignals: [] };
             }
         }
         else {
             // Priority 3: Try to discover an existing running application
-            const discovered = await discoverApplicationUrl(projectDir);
-            detectedApplication = discovered.project;
-            appUrl = discovered.url;
+            if (applicationLifecycle === 'managed') {
+                detectedApplication = detectApplication(projectDir);
+                appUrl = applicationUrlCandidate(detectedApplication);
+            }
+            else {
+                const discovered = await discoverApplicationUrl(projectDir);
+                detectedApplication = discovered.project;
+                appUrl = discovered.url;
+            }
         }
     }
+    if (detectedApplication?.feltDBEnabled) {
+        console.log(`Attaching existing FeltDB application (${detectedApplication.feltDBSignals.join(', ')})\n`);
+    }
     const requestedStudioPort = Number(args.includes('--studio-port') ? args[args.indexOf('--studio-port') + 1] || '7701' : '7701');
     const studioPort = String(await availablePort(requestedStudioPort));
     if (studioPort !== String(requestedStudioPort))
@@ -632,6 +634,8 @@ async function handleDev(args) {
     process.env.STUDIO_PORT = studioPort;
     let selfHostedStarted = false;
     let localAuthority = null;
+    let managedApplication = null;
+    let developmentSession = null;
     const stopSelfHosted = () => {
         if (selfHostedStarted) {
             spawnSync('docker', ['compose', 'stop', 'feltdb'], { cwd: process.cwd(), stdio: 'ignore' });
@@ -661,23 +665,102 @@ async function handleDev(args) {
         });
         process.env.VITE_FELTDB_URL = localAuthority.endpoint;
     }
+    const authorityUrl = process.env.VITE_FELTDB_URL;
+    if (!authorityUrl)
+        throw new Error('Development session authority URL was not resolved');
+    const discoveryPort = Number(args.includes('--discovery-port') ? args[args.indexOf('--discovery-port') + 1] || '7799' : '7799');
+    developmentSession = createDevelopmentSession({
+        sessionId: `dev_${randomBytes(16).toString('hex')}`,
+        workspaceId: workspace.workspaceId,
+        projectId: workspace.projectId,
+        namespace: runtimeNamespace || config.namespace,
+        runtime: config.runtime,
+        storage: config.storage,
+        lifecycle: applicationLifecycle,
+        authorityUrl,
+        studioUrl: `http://127.0.0.1:${studioPort}`,
+        pairingUrl: `http://127.0.0.1:${discoveryPort}`,
+        applicationUrl: appUrl,
+    });
+    transitionDevelopmentSession(developmentSession, 'STARTING');
     // Generate pairing token for the workspace
     // This enables browsers and IDEs to discover and connect to the workspace
     let pairingToken = null;
     let pairingDiscoveryServer = null;
-    if (workspace) {
-        const token = generatePairingToken();
-        token.workspaceId = workspace.workspaceId;
-        token.endpoint = process.env.VITE_FELTDB_URL;
-        token.authorityEndpoint = token.endpoint;
-        token.namespace = runtimeNamespace || config.namespace;
-        if (!token.endpoint) {
-            throw new Error('Development Workspace pairing requires a FeltDB authority endpoint');
+    try {
+        if (workspace) {
+            const token = generatePairingToken();
+            token.workspaceId = developmentSession.workspaceId;
+            token.endpoint = developmentSession.authorityUrl;
+            token.authorityEndpoint = token.endpoint;
+            token.namespace = developmentSession.namespace;
+            if (!token.endpoint) {
+                throw new Error('Development Workspace pairing requires a FeltDB authority endpoint');
+            }
+            persistPairingToken(process.cwd(), token);
+            pairingDiscoveryServer = await startPairingDiscoveryServer(token, discoveryPort, '127.0.0.1', {
+                sessionId: developmentSession.sessionId,
+                workspaceId: developmentSession.workspaceId,
+                namespace: developmentSession.namespace,
+                runtime: developmentSession.runtime,
+                authorityUrl: developmentSession.authorityUrl,
+                applicationUrl: developmentSession.applicationUrl,
+            });
+            const pairingAddress = pairingDiscoveryServer.address();
+            developmentSession.pairingUrl = `http://127.0.0.1:${pairingAddress.port}`;
+            pairingToken = token.token;
+        }
+    }
+    catch (error) {
+        transitionDevelopmentSession(developmentSession, 'FAILED');
+        await localAuthority?.close();
+        stopSelfHosted();
+        throw error;
+    }
+    let stopping = null;
+    const stopAll = () => stopping ?? (stopping = (async () => {
+        if (developmentSession && developmentSession.state !== 'STOPPING' && developmentSession.state !== 'STOPPED') {
+            transitionDevelopmentSession(developmentSession, 'STOPPING');
+        }
+        await managedApplication?.stop();
+        if (pairingDiscoveryServer?.listening) {
+            await new Promise(resolve => pairingDiscoveryServer.close(() => resolve()));
+        }
+        await localAuthority?.close();
+        stopSelfHosted();
+        if (developmentSession?.state === 'STOPPING')
+            transitionDevelopmentSession(developmentSession, 'STOPPED');
+    })());
+    process.once('exit', () => { void stopAll(); });
+    process.once('SIGINT', async () => { await stopAll(); process.exit(130); });
+    process.once('SIGTERM', async () => { await stopAll(); process.exit(143); });
+    if (applicationLifecycle === 'managed') {
+        try {
+            if (!detectedApplication)
+                detectedApplication = detectApplication(projectDir);
+            if (!appUrl) {
+                throw new Error(`Managed application lifecycle requires an expected application URL from --app-url, feltdb.config.json applicationUrl, FELTDB_APP_URL, or an explicit port in package.json.scripts.dev (workspace: ${workspace.workspaceId}; project: ${projectDir})`);
+            }
+            const timeoutArgument = args.includes('--application-timeout')
+                ? args[args.indexOf('--application-timeout') + 1]
+                : undefined;
+            const applicationTimeoutMs = timeoutArgument === undefined ? 15000 : Number(timeoutArgument);
+            if (!Number.isFinite(applicationTimeoutMs) || applicationTimeoutMs <= 0)
+                throw new Error('--application-timeout must be a positive number of milliseconds');
+            managedApplication = startManagedApplication({
+                projectDir,
+                project: detectedApplication,
+                environment: { ...process.env, ...developmentSessionEnvironment(developmentSession) },
+            });
+            console.log(`Starting managed application: ${managedApplication.command}`);
+            await waitForManagedApplication({ application: managedApplication, expectedUrl: appUrl, timeoutMs: applicationTimeoutMs, workspaceId: workspace.workspaceId, projectDir });
+            console.log(`Managed application ready: ${appUrl}\n`);
+        }
+        catch (error) {
+            transitionDevelopmentSession(developmentSession, 'FAILED');
+            await stopAll();
+            throw error;
         }
-        persistPairingToken(process.cwd(), token);
-        const discoveryPort = Number(args.includes('--discovery-port') ? args[args.indexOf('--discovery-port') + 1] || '7799' : '7799');
-        pairingDiscoveryServer = await startPairingDiscoveryServer(token, discoveryPort);
-        pairingToken = token.token;
     }
     // Output startup information
     console.log('✨ Development Workspace');
@@ -688,18 +771,19 @@ async function handleDev(args) {
     console.log('🔗 Development Workspace');
     if (pairingToken) {
         console.log(`   Pairing Code: ${pairingToken}`);
-        console.log(`   Pairing discovery: http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
+        console.log(`   Pairing discovery: ${developmentSession.pairingUrl}`);
     }
     console.log();
     console.log('FeltDB Dev Server');
-    console.log(`  Namespace:   ${config.namespace}`);
-    console.log(`  Runtime:     ${config.runtime}`);
-    console.log(`  Storage:     ${config.storage}`);
+    console.log(`  Namespace:   ${developmentSession.namespace}`);
+    console.log(`  Runtime:     ${developmentSession.runtime}`);
+    console.log(`  Storage:     ${developmentSession.storage}`);
     console.log(`  Distributed: ${config.distributed}`);
+    console.log(`  Application: ${applicationLifecycle}`);
     console.log();
     if (appUrl) {
         console.log(`Application: ${appUrl}`);
-        console.log(`Authority: ${process.env.VITE_FELTDB_URL}`);
+        console.log(`Authority: ${developmentSession.authorityUrl}`);
         console.log();
         console.log(`Using existing application at ${appUrl}`);
         console.log(`app=${encodeURIComponent(appUrl)}\n`);
@@ -710,23 +794,41 @@ async function handleDev(args) {
         console.log('  feltdb dev --app-url http://127.0.0.1:<port>\n');
         console.log('Or set applicationUrl in feltdb.config.json\n');
         console.log('FeltDB workspace is ready at:');
-        console.log('Authority: ' + process.env.VITE_FELTDB_URL);
-        console.log('Studio:    http://127.0.0.1:' + studioPort);
+        console.log('Authority: ' + developmentSession.authorityUrl);
+        console.log('Studio:    ' + developmentSession.studioUrl);
         console.log();
     }
-    const stopAll = () => { pairingDiscoveryServer?.close(); void localAuthority?.close(); stopSelfHosted(); };
-    process.once('exit', stopAll);
-    process.once('SIGINT', () => { stopAll(); process.exit(130); });
-    process.once('SIGTERM', () => { stopAll(); process.exit(143); });
     const open = !args.includes('--no-open');
-    await handleStudio([
-        '--port', studioPort,
-        '--namespace', runtimeNamespace || 'default',
-        '--runtime', config.runtime || 'browser',
-        ...(appUrl ? ['--app-url', appUrl] : []),
-        ...((config.runtime === 'self-hosted' || config.runtime === 'managed') && process.env.VITE_FELTDB_URL ? ['--connect', process.env.VITE_FELTDB_URL] : []),
-        ...(open ? [] : ['--no-open']),
-    ]);
+    try {
+        const studio = handleStudio([
+            '--port', studioPort,
+            '--namespace', developmentSession.namespace,
+            '--runtime', developmentSession.runtime,
+            '--workspace-id', developmentSession.workspaceId,
+            '--session-id', developmentSession.sessionId,
+            '--project-id', developmentSession.projectId,
+            '--authority-url', developmentSession.authorityUrl,
+            '--pairing-url', developmentSession.pairingUrl,
+            '--lifecycle', developmentSession.lifecycle,
+            ...(developmentSession.applicationUrl ? ['--app-url', developmentSession.applicationUrl] : []),
+            ...((developmentSession.runtime === 'self-hosted' || developmentSession.runtime === 'managed') ? ['--connect', developmentSession.authorityUrl] : []),
+            ...(open ? [] : ['--no-open']),
+        ], () => {
+            transitionDevelopmentSession(developmentSession, 'READY');
+            console.log(`\n${developmentSessionSummary(developmentSession)}\n`);
+            transitionDevelopmentSession(developmentSession, 'RUNNING');
+        });
+        if (managedApplication) {
+            await Promise.race([studio, managedApplication.exited.then(exit => {
+                    throw new Error(`Managed application stopped during the development session (command: ${managedApplication.command}; exit: ${exit.code ?? exit.signal})`);
+                })]);
+        }
+        else
+            await studio;
+    }
+    finally {
+        await stopAll();
+    }
 }
 function runLocalVite(args, waitForExit) {
     const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
@@ -982,7 +1084,7 @@ async function handleDoctor() {
     }
     console.log('\n✅ System healthy\n');
 }
-async function handleStudio(args) {
+async function handleStudio(args, onReady) {
     const connectUrl = args.includes('--connect')
         ? args[args.indexOf('--connect') + 1]
         : undefined;
@@ -1002,6 +1104,19 @@ async function handleStudio(args) {
     const appUrl = args.includes('--app-url')
         ? args[args.indexOf('--app-url') + 1]
         : undefined;
+    const sessionValue = (name) => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+    const session = {
+        sessionId: sessionValue('--session-id'),
+        workspaceId: sessionValue('--workspace-id'),
+        projectId: sessionValue('--project-id'),
+        authorityUrl: sessionValue('--authority-url'),
+        pairingUrl: sessionValue('--pairing-url'),
+        lifecycle: sessionValue('--lifecycle'),
+        namespace,
+        runtime,
+        applicationUrl: appUrl,
+        bridgeUrl: sessionValue('--pairing-url'),
+    };
     if (connectUrl) {
         console.log(`Connecting to: ${connectUrl}`);
         console.log(`Remote Studio: http://localhost:${port}\n`);
@@ -1020,13 +1135,13 @@ async function handleStudio(args) {
         .map(value => path.resolve(process.cwd(), value))
         .find((value, index, values) => values.indexOf(value) === index && fs.existsSync(value));
     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((request, response) => {
+    const server = http.createServer(async (request, response) => {
         const pathname = decodeURIComponent(new URL(request.url || '/', 'http://localhost').pathname);
         if (pathname === '/_feltdb/config') {
             response.setHeader('Content-Type', 'application/json; charset=utf-8');
             response.setHeader('Cache-Control', 'no-store');
             response.setHeader('Pragma', 'no-cache');
-            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '' }));
+            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '', session }));
             return;
         }
         if (pathname === '/_feltdb/project') {
@@ -1040,6 +1155,52 @@ async function handleStudio(args) {
             response.end(JSON.stringify({ namespace, filename: path.basename(projectFlow), source: fs.readFileSync(projectFlow, 'utf8') }));
             return;
         }
+        if (pathname === '/_feltdb/runtime') {
+            if (!session.bridgeUrl || !session.sessionId) {
+                response.statusCode = 404;
+                response.end('No development session');
+                return;
+            }
+            try {
+                const upstream = await fetch(`${session.bridgeUrl}/api/v1/development/runtimes?sessionId=${encodeURIComponent(session.sessionId)}`);
+                response.statusCode = upstream.status;
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                response.setHeader('Cache-Control', 'no-store');
+                response.end(await upstream.text());
+            }
+            catch (error) {
+                response.statusCode = 503;
+                response.end(JSON.stringify({ error: String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/observations') {
+            if (!session.bridgeUrl || !session.sessionId) {
+                response.statusCode = 404;
+                response.end('No development session');
+                return;
+            }
+            const query = new URL(request.url || '/', 'http://localhost').searchParams;
+            const runtimeInstanceId = query.get('runtimeInstanceId');
+            if (!runtimeInstanceId) {
+                response.statusCode = 400;
+                response.end('runtimeInstanceId is required');
+                return;
+            }
+            const parameters = new URLSearchParams({ sessionId: session.sessionId, limit: query.get('limit') || '100', cursor: query.get('cursor') || '0' });
+            try {
+                const upstream = await fetch(`${session.bridgeUrl}/api/v1/development/runtime/${encodeURIComponent(runtimeInstanceId)}/observations?${parameters}`);
+                response.statusCode = upstream.status;
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                response.setHeader('Cache-Control', 'no-store');
+                response.end(await upstream.text());
+            }
+            catch (error) {
+                response.statusCode = 503;
+                response.end(JSON.stringify({ error: String(error) }));
+            }
+            return;
+        }
         const requested = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
         const candidate = path.resolve(root, requested);
         const file = candidate.startsWith(`${path.resolve(root)}${path.sep}`) && fs.existsSync(candidate) && fs.statSync(candidate).isFile() ? candidate : path.join(root, 'index.html');
@@ -1053,9 +1214,18 @@ async function handleStudio(args) {
         parameters.set('connect', connectUrl);
     if (appUrl)
         parameters.set('app', appUrl);
+    if (session.workspaceId)
+        parameters.set('workspace', session.workspaceId);
+    if (session.sessionId)
+        parameters.set('session', session.sessionId);
+    if (session.authorityUrl)
+        parameters.set('authority', session.authorityUrl);
+    if (session.pairingUrl)
+        parameters.set('pairing', session.pairingUrl);
     const query = `?${parameters.toString()}`;
     const studioUrl = `http://127.0.0.1:${port}/${query}`;
     console.log(`FeltDB Studio ready at ${studioUrl}`);
+    onReady?.();
     console.log('Use Ctrl+C to stop the server.');
     if (open) {
         const command = process.platform === 'darwin' ? ['open', studioUrl] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', studioUrl] : ['xdg-open', studioUrl];

package/dist/cli/development-session.js

@@ -0,0 +1,54 @@
+const TRANSITIONS = {
+    CREATING: ['STARTING', 'FAILED'],
+    STARTING: ['READY', 'STOPPING', 'FAILED'],
+    READY: ['RUNNING', 'STOPPING', 'FAILED'],
+    RUNNING: ['STOPPING', 'FAILED'],
+    STOPPING: ['STOPPED'],
+    STOPPED: [],
+    FAILED: ['STOPPING', 'STOPPED'],
+};
+export function createDevelopmentSession(input) {
+    for (const key of ['sessionId', 'workspaceId', 'projectId', 'namespace', 'runtime', 'storage', 'authorityUrl', 'studioUrl', 'pairingUrl']) {
+        if (!input[key])
+            throw new Error(`Cannot create development session without ${key}`);
+    }
+    return { ...input, state: 'CREATING' };
+}
+export function transitionDevelopmentSession(session, state) {
+    if (session.state === state)
+        return;
+    if (!TRANSITIONS[session.state].includes(state))
+        throw new Error(`Invalid development session transition ${session.state} -> ${state}`);
+    session.state = state;
+}
+export function developmentSessionEnvironment(session) {
+    return {
+        FELTDB_WORKSPACE_ID: session.workspaceId,
+        FELTDB_DEV_SESSION_ID: session.sessionId,
+        FELTDB_DEV_BRIDGE_URL: session.pairingUrl,
+        FELTDB_RUNTIME: session.runtime,
+        FELTDB_AUTHORITY_URL: session.authorityUrl,
+        FELTDB_APPLICATION_URL: session.applicationUrl,
+        FELTDB_WORKSPACE_ENDPOINT: session.authorityUrl,
+        FELTDB_NAMESPACE: session.namespace,
+        VITE_FELTDB_WORKSPACE_ID: session.workspaceId,
+        VITE_FELTDB_DEV_SESSION_ID: session.sessionId,
+        VITE_FELTDB_DEV_BRIDGE_URL: session.pairingUrl,
+        VITE_FELTDB_RUNTIME: session.runtime,
+        VITE_FELTDB_AUTHORITY_URL: session.authorityUrl,
+        VITE_FELTDB_APPLICATION_URL: session.applicationUrl,
+        VITE_FELTDB_WORKSPACE_ENDPOINT: session.authorityUrl,
+        VITE_FELTDB_NAMESPACE: session.namespace,
+    };
+}
+export function developmentSessionSummary(session) {
+    const rows = [
+        ['Session', session.sessionId], ['Workspace', session.workspaceId], ['Project', session.projectId], ['Namespace', session.namespace],
+        ['Runtime', session.runtime], ['Storage', session.storage], ['Lifecycle', session.lifecycle],
+        ['Application', session.applicationUrl], ['Authority', session.authorityUrl],
+        ['Studio', session.studioUrl], ['Pairing', session.pairingUrl],
+    ].filter((row) => Boolean(row[1]));
+    return ['FeltDB Development Session', ...rows.map(([label, value]) => `${label.padEnd(12)} ${value}`),
+        '✓ Authority', '✓ Pairing', '✓ Studio', ...(session.applicationUrl ? ['✓ Application'] : []),
+        'FeltDB development environment ready.'].join('\n');
+}

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.6.10';
+const VERSION = '0.6.12';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,