@feltdb/core 0.6.5 → 0.6.7

package/dist/cli/application.js

@@ -0,0 +1,127 @@
+import fs from 'fs';
+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|$)/ },
+    { name: 'Nuxt', packages: ['nuxt'], pattern: /(?:^|\s)(?:nuxi|nuxt)(?:\s+dev)?(?:\s|$)/ },
+    { name: 'SvelteKit', packages: ['@sveltejs/kit'], pattern: /(?:^|\s)svelte-kit(?:\s+dev)?(?:\s|$)/ },
+    { name: 'Remix', packages: ['@remix-run/dev'], pattern: /(?:^|\s)remix(?:\s+vite:dev)?(?:\s|$)/ },
+    { name: 'Vite', packages: ['vite'], pattern: /(?:^|\s)vite(?:\s|$)/ },
+];
+function packageManagerAt(root, declared) {
+    const declaredName = declared?.split('@')[0];
+    if (declaredName === 'npm' || declaredName === 'pnpm' || declaredName === 'yarn' || declaredName === 'bun')
+        return declaredName;
+    if (fs.existsSync(path.join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(root, 'yarn.lock')))
+        return 'yarn';
+    if (fs.existsSync(path.join(root, 'bun.lock')) || fs.existsSync(path.join(root, 'bun.lockb')))
+        return 'bun';
+    return 'npm';
+}
+function configuredPort(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;
+}
+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 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 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 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));
+    }
+    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));
+        }
+    }
+    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}`);
+    });
+    return { child, url };
+}

package/dist/cli/commands.js

@@ -8,7 +8,8 @@ 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 { discoverWorkspace, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
+import { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
+import { detectApplication, startApplication } from './application.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -430,13 +431,16 @@ function runLocalVite(args, waitForExit) {
 async function handleDev(args) {
     var _a, _b, _c;
     if (args.includes('--help')) {
-        console.log('Usage: feltdb dev [--port 5173] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('Usage: feltdb dev [--app-url URL | --app-port PORT] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
         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.
+    ensureWorkspaceGitIgnored(projectDir);
     // Initialize workspace if needed
     let workspace = discoverWorkspace(projectDir);
     if (!workspace) {
@@ -452,7 +456,7 @@ async function handleDev(args) {
                 // Use default projectId if package.json parsing fails
             }
         }
-        workspace = initializeWorkspace(projectDir, projectId);
+        workspace = initializeWorkspace(projectDir, projectId, { gitProtection: false });
         console.log(`✨ Initialized Development Workspace`);
         console.log(`   Workspace ID: ${workspace.workspaceId}\n`);
     }
@@ -491,15 +495,10 @@ async function handleDev(args) {
     const runtimeNamespace = config.runtime === 'managed'
         ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
         : config.namespace;
-    const requestedAppPort = Number(args.includes('--port') ? args[args.indexOf('--port') + 1] || '5173' : '5173');
     const requestedStudioPort = Number(args.includes('--studio-port') ? args[args.indexOf('--studio-port') + 1] || '7701' : '7701');
-    const appPort = String(await availablePort(requestedAppPort));
     const studioPort = String(await availablePort(requestedStudioPort));
-    if (appPort !== String(requestedAppPort))
-        console.log(`Port ${requestedAppPort} is busy; using ${appPort} for the application.`);
     if (studioPort !== String(requestedStudioPort))
         console.log(`Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.`);
-    process.env.APP_PORT = appPort;
     process.env.STUDIO_PORT = studioPort;
     let selfHostedStarted = false;
     let localAuthority = null;
@@ -550,11 +549,53 @@ 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;
+    }
+    catch (error) {
+        runningApplication?.child.kill('SIGTERM');
+        pairingDiscoveryServer?.close();
+        await localAuthority?.close();
+        stopSelfHosted();
+        throw error;
+    }
     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(`  Runtime:   ${config.runtime}`);
+    console.log(`  Storage:   ${config.storage}`);
     console.log(`  Distributed: ${config.distributed}`);
     if (workspace) {
         console.log(`  Workspace: ${workspace.workspaceId}\n`);
@@ -567,17 +608,15 @@ async function handleDev(args) {
     }
     console.log();
     const open = !args.includes('--no-open');
-    console.log(`Application: http://127.0.0.1:${appPort}`);
+    console.log(`Application: ${appUrl}`);
     console.log(`Studio:      http://127.0.0.1:${studioPort}\n`);
-    const viteArgs = ['--host', '127.0.0.1', '--port', appPort, '--strictPort', ...(open ? ['--open'] : [])];
-    const vite = runLocalVite(viteArgs, false);
     let shuttingDown = false;
-    const stopVite = () => { if (!vite.killed)
-        vite.kill('SIGTERM'); };
-    const stopAll = () => { shuttingDown = true; stopVite(); pairingDiscoveryServer?.close(); void localAuthority?.close(); stopSelfHosted(); };
+    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.
-    vite.once('exit', code => {
+    runningApplication?.child.once('exit', code => {
         if (shuttingDown)
             return;
         stopSelfHosted();
@@ -590,7 +629,7 @@ async function handleDev(args) {
         '--port', studioPort,
         '--namespace', runtimeNamespace || 'default',
         '--runtime', config.runtime || 'browser',
-        '--app-url', `http://127.0.0.1:${appPort}`,
+        '--app-url', appUrl,
         ...((config.runtime === 'self-hosted' || config.runtime === 'managed') && process.env.VITE_FELTDB_URL ? ['--connect', process.env.VITE_FELTDB_URL] : []),
         ...(open ? [] : ['--no-open']),
     ]);

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

package/dist/cli/workspace-integration.js

@@ -11,6 +11,37 @@ import fs from 'fs';
 import path from 'path';
 import { randomBytes } from 'crypto';
 import http from 'http';
+import { spawnSync } from 'child_process';
+const FELTDB_IGNORE_PATTERN = /^\/?\.feltdb\/?$/;
+/**
+ * Reserve .feltdb/ for local FeltDB runtime state before any state is written.
+ * This only updates ignore configuration; it never changes Git's index/history.
+ */
+export function ensureWorkspaceGitIgnored(projectDir) {
+    const ignorePath = path.join(projectDir, '.gitignore');
+    const existing = fs.existsSync(ignorePath) ? fs.readFileSync(ignorePath, 'utf8') : '';
+    const ignored = existing.split(/\r?\n/).some(line => FELTDB_IGNORE_PATTERN.test(line.trim()));
+    let added = false;
+    if (!ignored) {
+        const newline = existing.includes('\r\n') ? '\r\n' : '\n';
+        const separator = existing.length > 0 && !existing.endsWith('\n') && !existing.endsWith('\r') ? newline : '';
+        fs.writeFileSync(ignorePath, `${existing}${separator}.feltdb/${newline}`);
+        added = true;
+    }
+    const trackedCheck = spawnSync('git', ['-C', projectDir, 'ls-files', '--', '.feltdb'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const tracked = trackedCheck.status === 0 && trackedCheck.stdout.trim().length > 0;
+    if (tracked) {
+        console.warn('⚠ FeltDB runtime state is already tracked by Git.');
+        console.warn('  .feltdb/ contains local runtime state and should not be committed.');
+        console.warn('  Add .feltdb/ to .gitignore and remove the existing files from Git');
+        console.warn('  tracking before pushing.');
+        console.warn('  FeltDB will not modify Git history automatically.');
+    }
+    return { added, tracked };
+}
 export function startPairingDiscoveryServer(token, port = 7799, host = '127.0.0.1') {
     const authorityEndpoint = token.authorityEndpoint || token.endpoint;
     if (!token.workspaceId || !authorityEndpoint || !token.namespace) {
@@ -123,7 +154,9 @@ export function generateWorkspaceId(projectId) {
  * Initialize development workspace for a project
  * Creates .feltdb/workspace.json with workspace discovery information.
  */
-export function initializeWorkspace(projectDir, projectId) {
+export function initializeWorkspace(projectDir, projectId, options = {}) {
+    if (options.gitProtection !== false)
+        ensureWorkspaceGitIgnored(projectDir);
     const feltdbDir = path.join(projectDir, '.feltdb');
     // Ensure .feltdb directory exists
     if (!fs.existsSync(feltdbDir)) {

package/dist/create/create.js

@@ -1506,8 +1506,7 @@ build/
 .env.*.local
 *.log
 .DS_Store
-.feltdb/keys.json
-.feltdb/connection.json
+.feltdb/
 `;
     fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignore);
     // Create README

package/dist/create/docker-compose-generator.js

@@ -190,8 +190,7 @@ build
 .env.*.local
 .DS_Store
 *.log
-.feltdb/keys.json
-.feltdb/connection.json
+.feltdb
 .nextc
 .next
 coverage

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.6.5';
+export const FELTDB_PACKAGE_VERSION = '0.6.7';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/create/workspace-initialization.js

@@ -20,7 +20,7 @@ export function generateWorkspaceId(projectId) {
  * Initialize development workspace for a new project
  *
  * Creates .feltdb/workspace.json with the workspace discovery information.
- * This file is committed to the repository and used by all development tools
+ * This file remains local and is used by all development tools
  * (CLI, IDE, agents, browser extensions) to discover and connect to the
  * same workspace.
  */
@@ -43,25 +43,18 @@ export function initializeWorkspace(projectDir, projectId) {
     return discovery;
 }
 /**
- * Create .gitignore entry for workspace runtime files
- *
- * The .feltdb/workspace.json is committed (pairing identity).
- * But runtime files like pairing tokens should not be committed.
+ * Reserve the entire FeltDB runtime directory in .gitignore.
  */
 export function appendWorkspaceGitignore(projectDir) {
     const gitignorePath = path.join(projectDir, '.gitignore');
-    const workspaceGitignoreEntries = [
-        '',
-        '# FeltDB Development Workspace',
-        '.feltdb/pairing.json',
-        '.feltdb/state.json',
-        '.feltdb/*.log',
-        '',
-    ].join('\n');
+    const entryExists = (contents) => contents.split(/\r?\n/)
+        .some(line => /^\/?\.feltdb\/?$/.test(line.trim()));
     if (fs.existsSync(gitignorePath)) {
         const existing = fs.readFileSync(gitignorePath, 'utf-8');
-        if (!existing.includes('.feltdb/pairing.json')) {
-            fs.appendFileSync(gitignorePath, workspaceGitignoreEntries);
+        if (!entryExists(existing)) {
+            const newline = existing.includes('\r\n') ? '\r\n' : '\n';
+            const separator = existing.length && !existing.endsWith('\n') && !existing.endsWith('\r') ? newline : '';
+            fs.appendFileSync(gitignorePath, `${separator}.feltdb/${newline}`);
         }
     }
     else {
@@ -70,7 +63,8 @@ export function appendWorkspaceGitignore(projectDir) {
             'dist/',
             'build/',
             '.env.local',
-            workspaceGitignoreEntries,
+            '.feltdb/',
+            '',
         ].join('\n');
         fs.writeFileSync(gitignorePath, content);
     }

package/dist/workspace/workspace-connection.js

@@ -407,13 +407,38 @@ class HttpWorkspaceTransport {
     }
     subscribe(workspaceId, handler) {
         let stopped = false;
+        let delivering = false;
+        let deliveryPending = false;
         const subscribedAt = Date.now();
+        const deliver = async () => {
+            if (stopped)
+                return;
+            if (delivering) {
+                deliveryPending = true;
+                return;
+            }
+            delivering = true;
+            try {
+                await this.deliverEvents(workspaceId, subscribedAt, handler);
+            }
+            finally {
+                delivering = false;
+                if (deliveryPending) {
+                    deliveryPending = false;
+                    void deliver();
+                }
+            }
+        };
         const unsubscribe = this.db.subscribe_changes(collection => {
             if (collection !== EVENT_COLLECTION || stopped)
                 return;
-            void this.deliverEvents(workspaceId, subscribedAt, handler);
+            void deliver();
         });
-        return () => { stopped = true; unsubscribe(); };
+        // The event log is authoritative. Reconcile immediately and periodically so
+        // an event cannot be stranded in the small window before SSE is established.
+        void deliver();
+        const reconciliation = setInterval(() => void deliver(), 250);
+        return () => { stopped = true; clearInterval(reconciliation); unsubscribe(); };
     }
     async appendEvent(input, type, value) {
         const event = { id: generateEventId(), ...input, type, value, timestamp: Date.now() };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feltdb/core",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "FeltDB Core - Application-facing database with Browser, Local, and Server runtimes. Durable state, reactive APIs.",
   "license": "MIT",
   "type": "module",