@feltdb/core 0.6.8 → 0.6.10

package/dist/cli/application.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
+import net from 'net';
 import path from 'path';
-import { spawn } from 'child_process';
 const FRAMEWORKS = [
     { name: 'Next.js', packages: ['next'], pattern: /(?:^|\s)next(?:\s+dev)?(?:\s|$)/ },
     { name: 'Astro', packages: ['astro'], pattern: /(?:^|\s)astro(?:\s+dev)?(?:\s|$)/ },
@@ -21,107 +21,74 @@ function packageManagerAt(root, declared) {
         return 'bun';
     return 'npm';
 }
-function configuredPort(script = '') {
+function scriptPort(script = '') {
     const match = script.match(/(?:^|\s)(?:PORT=|--port(?:=|\s+)|-p\s+)(\d{1,5})(?:\s|$)/i);
     if (!match)
         return undefined;
     const port = Number(match[1]);
     return port > 0 && port <= 65535 ? port : undefined;
 }
+function readJson(file, malformedMessage) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${malformedMessage} (${error.message})`);
+    }
+}
+/** Read application metadata only. This function never starts an application. */
 export function detectApplication(root) {
     const packageFile = path.join(root, 'package.json');
-    let manifest = {};
-    if (fs.existsSync(packageFile)) {
-        try {
-            manifest = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
-        }
-        catch (error) {
-            throw new Error(`Cannot detect application: malformed package.json (${error.message})`);
-        }
-    }
-    const manager = packageManagerAt(root, typeof manifest.packageManager === 'string' ? manifest.packageManager : undefined);
+    const manifest = fs.existsSync(packageFile) ? readJson(packageFile, 'Cannot inspect application: malformed package.json') : {};
     const script = typeof manifest.scripts?.dev === 'string' ? manifest.scripts.dev.trim() : undefined;
     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 invokesFeltDb = !!script && /(?:^|\s)feltdb\s+dev(?:\s|$)/.test(script);
-    if (script && !invokesFeltDb) {
-        const executable = process.platform === 'win32' ? `${manager}.cmd` : manager;
-        return {
-            packageManager: manager,
-            framework: framework?.name || 'Custom',
-            devScript: script,
-            command: executable,
-            args: manager === 'npm' || manager === 'bun' ? ['run', 'dev'] : ['dev'],
-            configuredPort: configuredPort(script),
-        };
-    }
-    // Projects generated by FeltDB historically use `feltdb dev` as their script.
-    // Keep their Vite application working without recursively spawning this CLI.
-    if (framework?.name === 'Vite' || fs.existsSync(path.join(root, 'index.html'))) {
-        const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-        return { packageManager: manager, framework: 'Vite', devScript: script, command: executable, args: ['exec', '--', 'vite'] };
-    }
-    throw new Error('Cannot determine how to start the application. Add a package.json dev script or pass --app-url.');
+    const feltConfigFile = path.join(root, 'feltdb.config.json');
+    const feltConfig = fs.existsSync(feltConfigFile) ? readJson(feltConfigFile, 'Cannot inspect application: malformed feltdb.config.json') : {};
+    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'),
+        devScript: script,
+        configuredPort: scriptPort(script),
+        configuredUrl,
+    };
 }
-const URL_PATTERN = /https?:\/\/(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::\d{1,5})?(?:\/[^\s\x1b]*)?/gi;
-export function applicationUrls(output) {
-    const plain = output.replace(/\x1b\[[0-?]*[ -\/]*[@-~]/g, '');
-    return [...plain.matchAll(URL_PATTERN)].map(match => match[0].replace(/[),.;]+$/, ''));
+export function applicationUrlCandidate(project, environment = process.env) {
+    if (environment.FELTDB_APP_URL)
+        return environment.FELTDB_APP_URL;
+    if (project.configuredUrl)
+        return project.configuredUrl;
+    if (project.configuredPort)
+        return `http://127.0.0.1:${project.configuredPort}`;
+    return undefined;
 }
-export function startApplication(project, root, options = {}) {
-    const env = { ...process.env };
-    if (options.appPort)
-        env.PORT = String(options.appPort);
-    const args = [...project.args];
-    // This is only the legacy Vite fallback, never an override of an existing script.
-    if (project.framework === 'Vite' && !project.devScript?.replace(/\s+/g, ' ').match(/^(?:npm run )?vite/)) {
-        args.push('--host', '127.0.0.1');
-        if (options.appPort)
-            args.push('--port', String(options.appPort));
+export function applicationIsRunning(url, timeoutMs = 750) {
+    let parsed;
+    try {
+        parsed = new URL(url);
     }
-    if (options.appPort && project.devScript) {
-        const flag = project.framework === 'Next.js' ? '-p' : '--port';
-        if (['Vite', 'Next.js', 'Astro', 'Nuxt', 'SvelteKit', 'Remix'].includes(project.framework)) {
-            if (project.packageManager === 'npm')
-                args.push('--');
-            args.push(flag, String(options.appPort));
-        }
+    catch {
+        return Promise.resolve(false);
     }
-    const child = spawn(project.command, args, { cwd: root, env, stdio: ['inherit', 'pipe', 'pipe'] });
-    const url = new Promise((resolve, reject) => {
-        let settled = false;
-        const finish = (value) => { if (!settled) {
-            settled = true;
-            clearTimeout(timer);
-            resolve(value);
-        } };
-        const inspect = (chunk) => {
-            const text = chunk.toString();
-            process.stdout.write(text);
-            const found = applicationUrls(text);
-            if (found.length)
-                finish(found[0]);
-        };
-        child.stdout?.on('data', inspect);
-        child.stderr?.on('data', inspect);
-        child.once('error', error => { if (!settled) {
-            settled = true;
-            clearTimeout(timer);
-            reject(error);
-        } });
-        child.once('exit', code => { if (!settled) {
-            settled = true;
-            clearTimeout(timer);
-            reject(new Error(`Application exited before reporting its URL (status ${code ?? 'unknown'})`));
-        } });
-        const timer = setTimeout(() => {
-            if (!settled) {
-                settled = true;
-                reject(new Error('Unable to determine application URL from dev-server output. Pass --app-url or --app-port.'));
-            }
-        }, options.startupTimeoutMs ?? 30000);
-        if (options.appPort)
-            finish(`http://127.0.0.1:${options.appPort}`);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return Promise.resolve(false);
+    const port = Number(parsed.port || (parsed.protocol === 'https:' ? 443 : 80));
+    return new Promise(resolve => {
+        const socket = net.createConnection({ host: parsed.hostname, port });
+        const done = (running) => { socket.destroy(); resolve(running); };
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
     });
-    return { child, url };
+}
+/** Discover only a deterministically configured, already-running application. */
+export async function discoverApplicationUrl(root) {
+    const project = detectApplication(root);
+    const candidate = applicationUrlCandidate(project);
+    if (!candidate)
+        return { project };
+    return { project, url: await applicationIsRunning(candidate) ? candidate : undefined };
 }

package/dist/cli/commands.js

@@ -7,9 +7,9 @@ import http from 'http';
 import net from 'net';
 import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
-import { createFeltDB, diffFlowSpec, formatFlowSpec, 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 { detectApplication, startApplication } from './application.js';
+import { detectApplication, discoverApplicationUrl } from './application.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -55,6 +55,8 @@ export async function handleCommand(command, args) {
             return handleWorkspace(args);
         case 'dev':
             return handleDev(args);
+        case 'investigations':
+            return handleInvestigations(args);
         case 'build':
             return handleBuild(args);
         case 'check':
@@ -76,6 +78,92 @@ export async function handleCommand(command, args) {
             return handleHelp();
     }
 }
+/**
+ * Inspect the durable investigation store.
+ *
+ * The evidence chain is only useful if a developer can get back to it after
+ * the browser is closed, so it is queryable from the command line.
+ */
+function handleInvestigations(args) {
+    if (args.includes('--help')) {
+        console.log('Usage: feltdb investigations [<investigation-id>] [--json]\n');
+        console.log('List durable runtime investigations, or show one in full.\n');
+        console.log('Options:');
+        console.log('  --json    Emit machine-readable JSON');
+        return;
+    }
+    const store = new InvestigationLifecycleManager(process.cwd());
+    const json = args.includes('--json');
+    const id = args.find(value => !value.startsWith('--'));
+    if (id) {
+        const investigation = store.loadInvestigation(id);
+        if (!investigation)
+            throw new Error(`Investigation not found: ${id}`);
+        if (json) {
+            console.log(JSON.stringify(investigation, null, 2));
+            return;
+        }
+        const observation = investigation.originalObservation;
+        console.log(`\nInvestigation ${investigation.id}`);
+        console.log(`  Workspace:    ${investigation.workspaceId}`);
+        console.log(`  Investigation ${investigation.investigationState}`);
+        console.log(`  Remediation:  ${investigation.remediationState}`);
+        console.log(`  Verification: ${investigation.verificationState}\n`);
+        if (observation) {
+            console.log('Observation');
+            console.log(`  ${observation.method} ${observation.url} -> HTTP ${observation.status}`);
+            console.log(`  ${observation.browser || 'unknown'} / ${observation.runtime || 'unknown'}`
+                + `${observation.durationMs !== undefined ? ` / ${observation.durationMs}ms` : ''}\n`);
+        }
+        if (investigation.evidence?.length) {
+            console.log('Evidence (observed by the runtime)');
+            for (const item of investigation.evidence)
+                console.log(`  [${item.kind}] ${item.statement}`);
+            console.log();
+        }
+        if (investigation.finding) {
+            console.log('Finding (FeltDB analysis, not an observation)');
+            console.log(`  ${investigation.finding.statement}`);
+            console.log(`  confidence: ${investigation.finding.confidence}\n`);
+        }
+        if (investigation.remediation?.changeIdentity) {
+            console.log('Remediation');
+            console.log(`  ${investigation.remediation.changeKind}: ${investigation.remediation.changeIdentity}`);
+            if (investigation.remediation.changedPaths.length) {
+                console.log(`  changed: ${investigation.remediation.changedPaths.join(', ')}`);
+            }
+            console.log();
+        }
+        if (investigation.verificationAttempt) {
+            const attempt = investigation.verificationAttempt;
+            console.log('Verification');
+            console.log(`  ${attempt.result}: ${attempt.summary}`);
+            console.log(`  ${attempt.originalStatus} -> ${attempt.observedStatus ?? 'no matching observation'}\n`);
+        }
+        return;
+    }
+    const investigations = store.listInvestigations();
+    if (json) {
+        console.log(JSON.stringify(investigations, null, 2));
+        return;
+    }
+    if (investigations.length === 0) {
+        console.log('\nNo investigations recorded.');
+        console.log('Run "feltdb dev", exercise the application, and a runtime defect will open one.\n');
+        return;
+    }
+    console.log(`\n${investigations.length} investigation${investigations.length === 1 ? '' : 's'}\n`);
+    for (const investigation of investigations) {
+        const observation = investigation.originalObservation;
+        const summary = observation
+            ? `${observation.method} ${observation.url} -> ${observation.status}`
+            : investigation.observationId;
+        console.log(`  ${investigation.id}  ${investigation.verificationState.padEnd(12)} ${summary}`);
+    }
+    const metrics = store.metrics();
+    console.log(`\n  ${metrics.observations} observations, ${metrics.evidenceRecords} evidence records, `
+        + `${metrics.serializedBytes} bytes, loaded in ${metrics.loadMilliseconds}ms\n`);
+}
 function flowFile(args) {
     const candidate = args.find(value => !value.startsWith('--')) || 'feltdb.flow';
     return path.resolve(candidate);
@@ -414,37 +502,29 @@ async function handleWorkspaceConnect(args) {
     console.log('   This feature will be implemented in the next phase');
     console.log('   (when @feltdb/client workspace APIs are available)\n');
 }
-function runLocalVite(args, waitForExit) {
-    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const child = spawn(executable, ['exec', '--', 'vite', ...args], {
-        cwd: process.cwd(),
-        stdio: 'inherit',
-        env: process.env,
-    });
-    if (!waitForExit)
-        return child;
-    return new Promise((resolve, reject) => {
-        child.once('error', reject);
-        child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Vite exited with status ${code ?? 'unknown'}`)));
-    });
-}
 async function handleDev(args) {
     var _a, _b, _c;
+    const projectDir = process.cwd();
     if (args.includes('--help')) {
-        console.log('Usage: feltdb dev [--app-url URL | --app-port PORT] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('Usage: feltdb dev [--app-url URL] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('\nOptions:');
+        console.log('  --app-url <url>           Application URL (e.g., http://127.0.0.1:3000)');
+        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('  --no-open                 Do not open Studio in browser');
         return;
     }
     loadProjectEnvironment();
     console.log('🚀 Starting FeltDB development server...\n');
-    const projectDir = process.cwd();
-    const configPath = path.join(projectDir, 'feltdb.config.json');
     // .feltdb/ is reserved local runtime state. Protect it before discovery,
     // initialization, the authority, or pairing can persist anything there.
+    // This runs after `--help` returns, so asking for help never writes anything.
     ensureWorkspaceGitIgnored(projectDir);
+    const configPath = path.join(projectDir, 'feltdb.config.json');
     // Initialize workspace if needed
     let workspace = discoverWorkspace(projectDir);
     if (!workspace) {
-        // Get project name from package.json
         const packageJsonPath = path.join(projectDir, 'package.json');
         let projectId = path.basename(projectDir);
         if (fs.existsSync(packageJsonPath)) {
@@ -460,6 +540,8 @@ async function handleDev(args) {
         console.log(`✨ Initialized Development Workspace`);
         console.log(`   Workspace ID: ${workspace.workspaceId}\n`);
     }
+    // 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');
@@ -478,11 +560,10 @@ async function handleDev(args) {
             runtime: 'browser',
             storage: 'indexeddb',
             distributed: true,
-            agents: { enabled: false },
-            capabilities: { search: true },
+            applicationUrl: null,
         };
         fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n');
-        console.log(`✨ Created feltdb.config.json with default configuration\n`);
+        console.log(`✨ Created feltdb.config.json\n`);
     }
     const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
     if (config.runtime === 'managed') {
@@ -495,10 +576,59 @@ async function handleDev(args) {
     const runtimeNamespace = config.runtime === 'managed'
         ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
         : config.namespace;
+    // Application URL precedence:
+    // 1. --app-url (highest priority)
+    // 2. feltdb.config.json applicationUrl
+    // 3. Deterministically discovered running application
+    // 4. No application (lowest priority - allowed)
+    const hasAppUrlArg = args.includes('--app-url');
+    const appUrlArgument = hasAppUrlArg ? args[args.indexOf('--app-url') + 1] : undefined;
+    if (hasAppUrlArg && !appUrlArgument)
+        throw new Error('--app-url requires a URL');
+    if (appUrlArgument) {
+        try {
+            const parsed = new URL(appUrlArgument);
+            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+                throw new Error('unsupported protocol');
+        }
+        catch {
+            throw new Error(`Invalid --app-url: ${appUrlArgument}`);
+        }
+    }
+    let appUrl;
+    let detectedApplication;
+    // Priority 1: --app-url takes highest priority
+    if (appUrlArgument) {
+        appUrl = appUrlArgument;
+        try {
+            detectedApplication = detectApplication(projectDir);
+        }
+        catch {
+            detectedApplication = { packageManager: 'npm', framework: 'External' };
+        }
+    }
+    else {
+        // Priority 2: Check feltdb.config.json applicationUrl
+        if (config.applicationUrl) {
+            appUrl = config.applicationUrl;
+            try {
+                detectedApplication = detectApplication(projectDir);
+            }
+            catch {
+                detectedApplication = { packageManager: 'npm', framework: 'External' };
+            }
+        }
+        else {
+            // Priority 3: Try to discover an existing running application
+            const discovered = await discoverApplicationUrl(projectDir);
+            detectedApplication = discovered.project;
+            appUrl = discovered.url;
+        }
+    }
     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))
-        console.log(`Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.`);
+        console.log(`⚠ Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.\n`);
     process.env.STUDIO_PORT = studioPort;
     let selfHostedStarted = false;
     let localAuthority = null;
@@ -549,91 +679,69 @@ async function handleDev(args) {
         pairingDiscoveryServer = await startPairingDiscoveryServer(token, discoveryPort);
         pairingToken = token.token;
     }
-    const hasAppUrl = args.includes('--app-url');
-    const appUrlArgument = hasAppUrl ? args[args.indexOf('--app-url') + 1] : undefined;
-    if (hasAppUrl && !appUrlArgument)
-        throw new Error('--app-url requires a URL');
-    const hasAppPort = args.includes('--app-port') || args.includes('--port');
-    const appPortValue = args.includes('--app-port')
-        ? args[args.indexOf('--app-port') + 1]
-        : args.includes('--port') ? args[args.indexOf('--port') + 1] : undefined;
-    if (!hasAppUrl && hasAppPort && !appPortValue)
-        throw new Error('--app-port requires a port');
-    const appPort = appPortValue ? Number(appPortValue) : undefined;
-    if (appUrlArgument) {
-        try {
-            const parsed = new URL(appUrlArgument);
-            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
-                throw new Error('unsupported protocol');
-        }
-        catch {
-            throw new Error(`Invalid --app-url: ${appUrlArgument}`);
-        }
-    }
-    if (!hasAppUrl && appPortValue && (!Number.isInteger(appPort) || appPort < 1 || appPort > 65535))
-        throw new Error(`Invalid --app-port: ${appPortValue}`);
-    const application = appUrlArgument ? undefined : detectApplication(projectDir);
-    const runningApplication = application ? startApplication(application, projectDir, { appPort }) : undefined;
-    let appUrl;
-    try {
-        appUrl = appUrlArgument || await runningApplication.url;
+    // Output startup information
+    console.log('✨ Development Workspace');
+    if (workspace) {
+        console.log(`   Workspace ID: ${workspace.workspaceId}`);
     }
-    catch (error) {
-        runningApplication?.child.kill('SIGTERM');
-        pairingDiscoveryServer?.close();
-        await localAuthority?.close();
-        stopSelfHosted();
-        throw error;
+    console.log();
+    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();
     console.log('FeltDB Dev Server');
-    console.log(`  Authority: ${process.env.VITE_FELTDB_URL}`);
-    console.log(`  Studio:    http://127.0.0.1:${studioPort}`);
-    console.log(`  Pairing:   http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
-    console.log('Application');
-    console.log(`  Framework: ${application?.framework || 'External'}`);
-    console.log(`  Dev command: ${application ? [application.command.replace(/\.cmd$/, ''), ...application.args].join(' ') : '(already running)'}`);
-    console.log(`  URL:       ${appUrl}`);
-    console.log(`  Namespace: ${config.namespace}`);
-    console.log(`  Runtime:   ${config.runtime}`);
-    console.log(`  Storage:   ${config.storage}`);
+    console.log(`  Namespace:   ${config.namespace}`);
+    console.log(`  Runtime:     ${config.runtime}`);
+    console.log(`  Storage:     ${config.storage}`);
     console.log(`  Distributed: ${config.distributed}`);
-    if (workspace) {
-        console.log(`  Workspace: ${workspace.workspaceId}\n`);
-        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(`  Clients can use this code to auto-discover the workspace`);
-        }
-    }
     console.log();
-    const open = !args.includes('--no-open');
-    console.log(`Application: ${appUrl}`);
-    console.log(`Studio:      http://127.0.0.1:${studioPort}\n`);
-    let shuttingDown = false;
-    const stopApplication = () => { if (runningApplication && !runningApplication.child.killed)
-        runningApplication.child.kill('SIGTERM'); };
-    const stopAll = () => { shuttingDown = true; stopApplication(); pairingDiscoveryServer?.close(); void localAuthority?.close(); stopSelfHosted(); };
-    // In an inherited terminal Ctrl-C can reach Vite before this parent process.
-    // Never leave Studio (or its port) running after the application exits.
-    runningApplication?.child.once('exit', code => {
-        if (shuttingDown)
-            return;
-        stopSelfHosted();
-        process.exit(code ?? 0);
-    });
+    if (appUrl) {
+        console.log(`Application: ${appUrl}`);
+        console.log(`Authority: ${process.env.VITE_FELTDB_URL}`);
+        console.log();
+        console.log(`Using existing application at ${appUrl}`);
+        console.log(`app=${encodeURIComponent(appUrl)}\n`);
+    }
+    else {
+        console.log('❌ No application URL is configured.\n');
+        console.log('Start your application, then run:\n');
+        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();
+    }
+    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',
-        '--app-url', appUrl,
+        ...(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']),
     ]);
 }
+function runLocalVite(args, waitForExit) {
+    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(executable, ['exec', '--', 'vite', ...args], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (!waitForExit)
+        return child;
+    return new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Vite exited with status ${code ?? 'unknown'}`)));
+    });
+}
 async function handleBuild(args) {
     console.log('🔨 Building FeltDB application...\n');
     const configPath = path.join(process.cwd(), 'feltdb.config.json');
@@ -904,11 +1012,13 @@ async function handleStudio(args) {
     const require = createRequire(import.meta.url);
     const packageFile = require.resolve('@feltdb/core/package.json');
     const root = path.join(path.dirname(packageFile), 'dist', 'studio-app');
+    if (!fs.existsSync(path.join(root, 'index.html'))) {
+        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));
-    if (!fs.existsSync(path.join(root, 'index.html')))
-        throw new Error('Studio application artifact is missing; reinstall @feltdb/core');
     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 pathname = decodeURIComponent(new URL(request.url || '/', 'http://localhost').pathname);
@@ -971,6 +1081,7 @@ Commands:
   connect              Connect to remote FeltDB
   status               Show connection status
   dev                  Start development server
+  investigations       List or show durable runtime investigations
   build                Build FeltDB application
   check                Validate configuration
   inspect              Inspect runtime state

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