create-feltdb 0.4.0 → 0.4.2

package/README.md

@@ -2,29 +2,33 @@
 
 Interactive CLI tool to scaffold new FeltDB applications.
 
-## Installation
-
-```bash
-npm install -g create-feltdb
-```
-
 ## Usage
 
-Create a new project:
+One command scaffolds, installs, and starts the application, Studio, and local
+WebLLM agent (no global installation required):
 
 ```bash
-npx create-feltdb my-app
+npx --yes create-feltdb@latest my-app
 ```
 
-Or use the installed command:
+Use the interactive menu, or accept its defaults non-interactively:
 
 ```bash
-create-feltdb my-app
+npx --yes create-feltdb@latest my-app --yes
 ```
 
 ### Options
 
-- `--yes` or `-y` - Skip interactive prompts and use defaults
+- `--runtime <browser|node|self-hosted>`
+- `--framework <react|vanilla>`
+- `--no-distributed`
+- `--no-agents`
+- `--capabilities <search|vector|search,vector>`
+- `--no-install` — generate without installing dependencies
+- `--no-start` — do not start services after generation
+- `--yes` or `-y` — skip the interactive menu and use defaults
+- `--help` or `-h`
+- `--version`
 
 ## What Gets Generated
 
@@ -47,16 +51,16 @@ my-app/
 └── README.md
 ```
 
-## Quick Start
-
-After running `create-feltdb`:
+## Run It Again
 
 ```bash
 cd my-app
-npm install
 npm run dev
 ```
 
+This starts the app and Studio together. Self-hosted projects also start the
+version-matched FeltDB server container and therefore require Docker.
+
 ## Default Configuration
 
 The generated project uses:
@@ -64,6 +68,8 @@ The generated project uses:
 - **Storage**: OPFS (with IndexedDB fallback)
 - **Distributed**: Enabled by default
 - **Capabilities**: Search enabled, Vector disabled
+- **AI**: Private WebLLM agent enabled; model loads lazily in the browser
+- **Studio**: Installed and served alongside the application
 
 ## License
 

package/dist/application-identity.js

@@ -0,0 +1,132 @@
+/**
+ * Application identity management
+ *
+ * Handles:
+ * - FELTDB_APP_NAME: Human-readable application name
+ * - FELTDB_APP_ID: UUID-based stable identifier
+ * - FELTDB_VERSION: Semantic versioning
+ * - Version matching between components
+ */
+import crypto from 'crypto';
+/**
+ * Generate a stable UUID from application name
+ * Ensures same name always produces same ID
+ */
+export function generateAppId(appName) {
+    const hash = crypto
+        .createHash('sha256')
+        .update(appName)
+        .digest('hex');
+    // Convert to UUID v5-like format
+    const uuid = [
+        hash.substring(0, 8),
+        hash.substring(8, 12),
+        '5' + hash.substring(13, 16),
+        ((parseInt(hash.substring(16, 18), 16) & 0x3f) | 0x80).toString(16).padStart(2, '0') +
+            hash.substring(18, 20),
+        hash.substring(20, 32),
+    ].join('-');
+    return uuid;
+}
+/**
+ * Sanitize application name for use in identifiers
+ */
+export function sanitizeAppName(name) {
+    return (name
+        // Replace spaces with hyphens
+        .replace(/\s+/g, '-')
+        // Remove non-alphanumeric except hyphens
+        .replace(/[^a-z0-9-]/gi, '')
+        // Remove leading/trailing hyphens
+        .replace(/^-+|-+$/g, '')
+        // Limit to 50 chars
+        .substring(0, 50)
+        .toLowerCase());
+}
+/**
+ * Get current FeltDB version from package.json
+ */
+export function getCurrentFeltDBVersion() {
+    // This would be replaced at build time with the actual version
+    return '0.4.2';
+}
+/**
+ * Create application identity manifest
+ */
+export function createApplicationIdentity(appName, feltdbVersion) {
+    const version = feltdbVersion || getCurrentFeltDBVersion();
+    const sanitized = sanitizeAppName(appName);
+    const appId = generateAppId(sanitized);
+    return {
+        name: sanitized,
+        id: appId,
+        version,
+        createdAt: new Date().toISOString(),
+        components: {
+            app: version,
+            feltdb: version,
+            studio: version,
+        },
+    };
+}
+/**
+ * Generate version manifest for Docker image metadata
+ */
+export function generateVersionLabels(identity) {
+    return {
+        'app.feltdb/app-name': identity.name,
+        'app.feltdb/app-id': identity.id,
+        'app.feltdb/version': identity.version,
+        'app.feltdb/created': identity.createdAt,
+        'app.feltdb/component.app': identity.components.app,
+        'app.feltdb/component.feltdb': identity.components.feltdb,
+        'app.feltdb/component.studio': identity.components.studio,
+    };
+}
+/**
+ * Validate version compatibility
+ */
+export function validateVersionCompatibility(appVersion, feltdbVersion, studioVersion) {
+    const warnings = [];
+    // All components should be same major.minor version for safety
+    const extractMajorMinor = (v) => v.split('.').slice(0, 2).join('.');
+    const appMajorMinor = extractMajorMinor(appVersion);
+    const feltdbMajorMinor = extractMajorMinor(feltdbVersion);
+    const studioMajorMinor = extractMajorMinor(studioVersion);
+    if (appMajorMinor !== feltdbMajorMinor) {
+        warnings.push(`App version ${appVersion} differs from FeltDB ${feltdbVersion}`);
+    }
+    if (feltdbMajorMinor !== studioMajorMinor) {
+        warnings.push(`FeltDB version ${feltdbVersion} differs from Studio ${studioVersion}`);
+    }
+    return {
+        compatible: warnings.length === 0,
+        warnings,
+    };
+}
+/**
+ * Generate .feltdb/identity.json manifest
+ */
+export function generateIdentityManifest(identity) {
+    return JSON.stringify(identity, null, 2);
+}
+/**
+ * Generate environment file with version information
+ */
+export function generateVersionEnv(identity) {
+    return `# Application Identity
+# Generated at: ${identity.createdAt}
+
+FELTDB_APP_NAME=${identity.name}
+FELTDB_APP_ID=${identity.id}
+FELTDB_VERSION=${identity.version}
+
+# Component Versions
+FELTDB_APP_VERSION=${identity.components.app}
+FELTDB_CORE_VERSION=${identity.components.feltdb}
+FELTDB_STUDIO_VERSION=${identity.components.studio}
+
+# Build Info
+FELTDB_BUILT_AT=${new Date().toISOString()}
+`;
+}

package/dist/cli-scripts-generator.js

@@ -0,0 +1,211 @@
+/**
+ * CLI lifecycle scripts for FeltDB applications
+ *
+ * Generates scripts for common operations:
+ * - feltdb:up - Start services
+ * - feltdb:down - Stop services
+ * - feltdb:logs - View logs
+ * - feltdb:status - Check health
+ * - feltdb:reset - Reset data
+ * - feltdb:ps - List running services
+ */
+export function generateUpScript() {
+    return `#!/bin/bash
+
+# Start FeltDB application stack
+# Usage: npm run feltdb:up
+
+set -e
+
+echo "🚀 Starting FeltDB application..."
+
+# Load environment
+if [ -f .env.local ]; then
+  export \$(cat .env.local | grep -v '^#' | xargs)
+fi
+
+# Build and start containers
+docker-compose up -d
+
+echo "⏳ Waiting for services to be healthy..."
+
+# Wait for FeltDB
+TIMEOUT=60
+ELAPSED=0
+while [ \$ELAPSED -lt \$TIMEOUT ]; do
+  if curl -s -f http://localhost:7700/health > /dev/null 2>&1; then
+    STATE=\$(curl -s http://localhost:7700/health | grep -o '"state":"[^"]*' | cut -d'"' -f4)
+    if [ "\$STATE" = "ready" ] || [ "\$STATE" = "recovering" ]; then
+      echo "✅ FeltDB is \$STATE"
+      break
+    fi
+  fi
+  sleep 2
+  ELAPSED=\$((ELAPSED + 2))
+done
+
+# Wait for application
+ELAPSED=0
+while [ \$ELAPSED -lt \$TIMEOUT ]; do
+  if curl -s -f http://localhost:3000/health > /dev/null 2>&1; then
+    echo "✅ Application is ready"
+    break
+  fi
+  sleep 2
+  ELAPSED=\$((ELAPSED + 2))
+done
+
+echo ""
+echo "✨ FeltDB stack is running!"
+echo ""
+echo "Services:"
+echo "  FeltDB:  http://localhost:7700"
+echo "  App:     http://localhost:3000"
+echo "  Studio:  http://localhost:8000"
+echo ""
+echo "Next: npm run feltdb:logs"
+`;
+}
+export function generateDownScript() {
+    return `#!/bin/bash
+
+# Stop FeltDB application stack
+# Usage: npm run feltdb:down
+
+echo "🛑 Stopping FeltDB application..."
+
+docker-compose down
+
+echo "✅ Services stopped"
+`;
+}
+export function generateLogsScript() {
+    return `#!/bin/bash
+
+# View logs from FeltDB stack
+# Usage: npm run feltdb:logs [service]
+#        npm run feltdb:logs feltdb
+#        npm run feltdb:logs app
+#        npm run feltdb:logs studio
+
+SERVICE=\$1
+
+if [ -z "\$SERVICE" ]; then
+  echo "📋 Logs from all services (Ctrl+C to exit):"
+  docker-compose logs -f
+else
+  echo "📋 Logs from \$SERVICE (Ctrl+C to exit):"
+  docker-compose logs -f \$SERVICE
+fi
+`;
+}
+export function generateStatusScript() {
+    return `#!/bin/bash
+
+# Check health and status of FeltDB stack
+# Usage: npm run feltdb:status
+
+echo "🔍 FeltDB Application Status"
+echo ""
+
+# Docker Compose status
+echo "Containers:"
+docker-compose ps
+
+echo ""
+
+# FeltDB health
+echo "FeltDB Health:"
+if RESPONSE=\$(curl -s -m 5 http://localhost:7700/health 2>/dev/null); then
+  STATE=\$(echo \$RESPONSE | grep -o '"state":"[^"]*' | cut -d'"' -f4)
+  VERSION=\$(echo \$RESPONSE | grep -o '"version":"[^"]*' | cut -d'"' -f4)
+  echo "  State:   \$STATE"
+  echo "  Version: \$VERSION"
+else
+  echo "  ❌ No response"
+fi
+
+# Application health
+echo ""
+echo "Application Health:"
+if RESPONSE=\$(curl -s -m 5 http://localhost:3000/health 2>/dev/null); then
+  echo "  ✅ Responding"
+else
+  echo "  ❌ No response"
+fi
+
+echo ""
+echo "Log tail: npm run feltdb:logs"
+`;
+}
+export function generateResetScript() {
+    return `#!/bin/bash
+
+# Reset FeltDB data (WARNING: destructive)
+# Usage: npm run feltdb:reset
+
+echo "⚠️  This will delete all FeltDB data!"
+read -p "Are you sure? (type 'yes' to confirm): " CONFIRM
+
+if [ "\$CONFIRM" != "yes" ]; then
+  echo "Cancelled."
+  exit 1
+fi
+
+echo "🧹 Resetting FeltDB data..."
+
+# Stop containers
+docker-compose down
+
+# Remove volumes
+docker volume rm \$(docker volume ls -q | grep feltdb_data) 2>/dev/null || true
+
+# Restart
+echo "🚀 Restarting services..."
+docker-compose up -d
+
+echo "✅ Data reset complete"
+`;
+}
+export function generatePsScript() {
+    return `#!/bin/bash
+
+# List running FeltDB services
+# Usage: npm run feltdb:ps
+
+docker-compose ps
+`;
+}
+export function generatePackageJsonScripts(runtime) {
+    const scripts = {
+        'feltdb:up': 'bash scripts/feltdb-up.sh',
+        'feltdb:down': 'bash scripts/feltdb-down.sh',
+        'feltdb:logs': 'bash scripts/feltdb-logs.sh',
+        'feltdb:status': 'bash scripts/feltdb-status.sh',
+        'feltdb:reset': 'bash scripts/feltdb-reset.sh',
+        'feltdb:ps': 'bash scripts/feltdb-ps.sh',
+    };
+    if (runtime === 'browser') {
+        // Browser doesn't need container scripts
+        return {
+            dev: 'vite',
+            build: 'tsc && vite build',
+        };
+    }
+    if (runtime === 'node') {
+        return {
+            dev: 'tsx src/index.ts',
+            build: 'tsc',
+            start: 'node dist/index.js',
+            ...scripts,
+        };
+    }
+    if (runtime === 'self-hosted') {
+        return {
+            dev: 'docker-compose up -d --build',
+            build: 'docker-compose build',
+            ...scripts,
+        };
+    }
+    return scripts;
+}

package/dist/cli.js

@@ -7,6 +7,7 @@
 import path from 'path';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
+import { spawn } from 'child_process';
 import { createProject } from './create.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function parseArgs(args) {
@@ -38,6 +39,15 @@ function parseArgs(args) {
     }
     return options;
 }
+function run(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('exit', code => code === 0
+            ? resolve()
+            : reject(new Error(`${command} exited with status ${code ?? 'unknown'}`)));
+    });
+}
 async function select(message, choices, initialValue) {
     let selected = Math.max(0, choices.findIndex(choice => choice.value === initialValue));
     const input = process.stdin;
@@ -114,11 +124,11 @@ async function promptForOptions(defaults) {
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || args.includes('-h')) {
-        console.log(`create-feltdb 0.4.0\n\nUsage: create-feltdb [project-name] [options]\n\nOptions:\n  --runtime <browser|node|self-hosted>\n  --framework <react|vanilla>\n  --no-distributed\n  --no-agents\n  --capabilities <list>\n  -y, --yes\n  -h, --help\n  --version`);
+        console.log(`create-feltdb 0.4.2\n\nUsage: create-feltdb [project-name] [options]\n\nOptions:\n  --runtime <browser|node|self-hosted>\n  --framework <react|vanilla>\n  --no-distributed\n  --no-agents\n  --capabilities <list>\n  --no-install\n  --no-start\n  -y, --yes\n  -h, --help\n  --version`);
         return;
     }
     if (args.includes('--version')) {
-        console.log('0.4.0');
+        console.log('0.4.2');
         return;
     }
     // Find project name (first non-flag argument)
@@ -135,6 +145,8 @@ async function main() {
         }
     }
     const shouldAutoYes = args.includes('--yes') || args.includes('-y');
+    const shouldInstall = !args.includes('--no-install');
+    const shouldStart = !args.includes('--no-start');
     let options = parseArgs(args);
     console.log('\n✨ Creating FeltDB Application\n');
     if (!shouldAutoYes) {
@@ -158,16 +170,28 @@ async function main() {
             capabilities: options.capabilities,
         });
         console.log('\n✅ FeltDB application created successfully!\n');
-        console.log(`Next steps:`);
-        console.log(`  cd ${projectName}`);
-        console.log(`  npm install`);
-        if (options.runtime === 'self-hosted') {
-            console.log(`  feltdb server --data ./data`);
+        const projectDir = path.resolve(process.cwd(), projectName);
+        const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        if (shouldInstall) {
+            console.log('📦 Installing application, Studio, and local AI dependencies...\n');
+            await run(npm, ['install'], projectDir);
+        }
+        if (shouldStart) {
+            if (!shouldInstall) {
+                console.log(`Start after installing dependencies:\n  cd ${projectName}\n  npm install\n  npm run dev\n`);
+            }
+            else {
+                console.log('\n🚀 Starting the application and FeltDB Studio...\n');
+                await run(npm, ['run', 'dev'], projectDir);
+            }
         }
         else {
-            console.log(`  npm run dev`);
+            console.log('Project is ready. Start everything with:');
+            console.log(`  cd ${projectName}`);
+            if (!shouldInstall)
+                console.log('  npm install');
+            console.log('  npm run dev');
         }
-        console.log('');
     }
     catch (error) {
         console.error('❌ Failed to create project:', error);

package/dist/create.js

@@ -54,6 +54,7 @@ export async function createProject(options) {
         },
         devDependencies: {
             '@feltdb/cli': feltdbPackageRange,
+            '@feltdb/studio': feltdbPackageRange,
             typescript: '^5.0.0',
             '@types/node': '^20.0.0',
             vite: '^8.2.1',
@@ -66,6 +67,9 @@ export async function createProject(options) {
         packageJson.devDependencies['@types/react'] = '^18.0.0';
         packageJson.devDependencies['@types/react-dom'] = '^18.0.0';
     }
+    if (hasAgents) {
+        packageJson.dependencies['@feltdb/webllm'] = feltdbPackageRange;
+    }
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2));
     // Create feltdb.config.json
     const feltdbConfig = {
@@ -153,52 +157,62 @@ export async function createProject(options) {
     }
     fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
     // Create main application files
+    const runtimeOptions = runtime === 'browser'
+        ? "{ namespace: '" + applicationName + "', browser: true }"
+        : runtime === 'self-hosted'
+            ? "{ namespace: '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
+            : "{ namespace: '" + applicationName + "', memory: true }";
     const feltdbTs = `import { createFeltDB } from '@feltdb/core';
 
-export const db = createFeltDB({
-  namespace: '${applicationName}',
-  memory: true, // Development-only; configure \`server\` for durable customer data.
-});
+export const db = createFeltDB(${runtimeOptions});
 
 // Collections
 export const documents = db.collection('documents');
 export const reports = db.collection('reports');
 `;
     fs.writeFileSync(path.join(srcDir, 'feltdb.ts'), feltdbTs);
-    // Create a sample agent if enabled
+    // Create a real local-inference agent for browser projects.
     if (hasAgents) {
-        const agentTs = `import { db } from '../feltdb';
+        const agentTs = `import { WebLLMProvider } from '@feltdb/webllm';
+import { db, reports } from '../../src/feltdb';
 
 /**
- * Researcher Agent
- * 
- * This agent demonstrates distributed agent execution
- * across peers in the FeltDB fabric.
+ * Researcher metadata is registered in FeltDB; inference runs privately in
+ * the browser through WebLLM and its worker.
  */
 export const researcher = db.defineAgent({
   name: 'researcher',
-  description: 'Search and analyze documents across the fabric',
+  version: 1,
+  description: 'Analyze documents with private, on-device inference',
   capabilities: [
     'document-read',
-    'vector-search',
     'report-write'
   ],
-  async run(options: any) {
-    console.log('🤖 Researcher agent starting...');
-    console.log('Goal:', options.goal);
-    console.log('Inputs:', options.inputs);
-    
-    // The agent will execute capabilities across peers
-    // Results are automatically acquired from remote locations
-    
-    return {
-      status: 'complete',
-      results: {
-        message: 'Research completed successfully'
-      }
-    };
-  }
+  goals: ['Summarize documents without sending prompts off-device'],
+  constraints: { maxIterations: 1 },
 });
+
+let provider: WebLLMProvider | undefined;
+
+export async function runResearcher(
+  prompt: string,
+  onProgress?: (message: string) => void,
+) {
+  provider ??= new WebLLMProvider({
+    onProgress: ({ progress, text }) =>
+      onProgress?.(\`${'${Math.round(progress * 100)}'}% ${'${text}'}\`),
+  });
+  const content = await provider.generate([
+    { role: 'system', content: 'You are a concise research assistant. Keep all reasoning local.' },
+    { role: 'user', content: prompt },
+  ]);
+  await reports.insert({
+    title: prompt.slice(0, 80) || 'Local research',
+    content,
+    createdAt: new Date(),
+  });
+  return content;
+}
 `;
         fs.writeFileSync(path.join(feltdbDir, 'agents', 'researcher.ts'), agentTs);
     }
@@ -228,12 +242,51 @@ export const capabilities = {
     fs.writeFileSync(path.join(feltdbDir, 'capabilities', 'index.ts'), capabilitiesTs);
     // Create main application file based on framework
     if (framework === 'react') {
+        const agentImport = hasAgents
+            ? "import { runResearcher } from '../feltdb/agents/researcher';"
+            : '';
+        const agentState = hasAgents
+            ? `  const [prompt, setPrompt] = useState('Summarize why local-first applications are useful.');
+  const [answer, setAnswer] = useState('');
+  const [modelStatus, setModelStatus] = useState('Model not loaded');
+  const [generating, setGenerating] = useState(false);`
+            : '';
+        const agentHandler = hasAgents
+            ? `
+  const handleResearch = async () => {
+    setGenerating(true);
+    setAnswer('');
+    try {
+      setAnswer(await runResearcher(prompt, setModelStatus));
+      setModelStatus('Ready — inference stayed in this browser');
+    } catch (error) {
+      setModelStatus(error instanceof Error ? error.message : String(error));
+    } finally {
+      setGenerating(false);
+    }
+  };
+`
+            : '';
+        const agentMarkup = hasAgents
+            ? `
+        <section className="researcher">
+          <h2>Private WebLLM Researcher</h2>
+          <p>{modelStatus}</p>
+          <textarea value={prompt} onChange={event => setPrompt(event.target.value)} rows={4} />
+          <button onClick={handleResearch} disabled={generating || !prompt.trim()}>
+            {generating ? 'Running locally…' : 'Run researcher'}
+          </button>
+          {answer && <article><h3>Result</h3><p>{answer}</p></article>}
+        </section>`
+            : '';
         const appTsx = `import React, { useState, useEffect } from 'react';
 import { db, documents } from './feltdb';
+${agentImport}
 
 export function App() {
   const [docs, setDocs] = useState<any[]>([]);
   const [loading, setLoading] = useState(true);
+${agentState}
 
   useEffect(() => {
     const loadDocs = async () => {
@@ -264,6 +317,7 @@ export function App() {
       console.error('Error adding document:', err);
     }
   };
+${agentHandler}
 
   return (
     <div className="app">
@@ -306,6 +360,7 @@ export function App() {
           )}
           <button onClick={handleAddDocument}>Add Document</button>
         </section>
+${agentMarkup}
       </main>
 
       <style>{\`
@@ -418,6 +473,20 @@ export function App() {
         button:hover {
           background: #5568d3;
         }
+
+        textarea {
+          box-sizing: border-box;
+          display: block;
+          margin: 12px 0;
+          padding: 10px;
+          width: 100%;
+        }
+
+        .researcher {
+          border-top: 1px solid #eee;
+          margin-top: 30px;
+          padding-top: 20px;
+        }
       \`}</style>
     </div>
   );
@@ -468,8 +537,10 @@ main().catch(console.error);
     fs.writeFileSync(path.join(projectDir, 'index.html'), indexHtml);
     // Create .env.example
     const envExample = `# FeltDB Configuration
-FELTDB_API_KEY=
-FELTDB_URL=http://localhost:7700
+VITE_FELTDB_API_KEY=
+VITE_FELTDB_URL=http://localhost:7700
+# Override the versioned self-hosted container when needed:
+FELTDB_IMAGE=
 NODE_ENV=development
 `;
     fs.writeFileSync(path.join(projectDir, '.env.example'), envExample);
@@ -554,12 +625,9 @@ feltdb keys create --name development --scope '*'
 
 ## Agents
 
-${hasAgents ? `The \`researcher\` agent demonstrates distributed execution:
-- Resolves document references
-- Discovers capabilities across peers
-- Executes on compatible peers
-- Creates workflows
-- Publishes results` : 'No agents configured'}
+${hasAgents ? `The \`researcher\` agent runs real private inference with
+\`@feltdb/webllm\`. The model downloads on first use, runs in a Web Worker, and
+caches its artifacts in the browser. Generated reports are stored in FeltDB.` : 'No agents configured'}
 
 ## Capabilities
 

package/dist/docker-compose-generator.js

@@ -0,0 +1,258 @@
+/**
+ * Docker Compose generator for self-hosted FeltDB deployments
+ *
+ * Generates:
+ * - docker-compose.yml with three services (FeltDB, App, Studio)
+ * - Dockerfile for application container
+ * - .dockerignore for optimized builds
+ * - Environment configuration
+ */
+export function generateDockerCompose(config) {
+    return `version: '3.9'
+
+services:
+  feltdb:
+    image: rkendel1/feltdb:latest
+    container_name: \${COMPOSE_PROJECT_NAME}-feltdb
+    environment:
+      FELTDB_APP_NAME: \${FELTDB_APP_NAME:-${config.appName}}
+      FELTDB_APP_ID: \${FELTDB_APP_ID:-${config.appId}}
+      FELTDB_VERSION: \${FELTDB_VERSION:-${config.version}}
+      FELTDB_PEERS: \${FELTDB_PEERS:-}
+      FELTDB_REPLICATION_PORT: ${config.replicationPort}
+      NODE_ENV: \${NODE_ENV:-production}
+    ports:
+      - "\${FELTDB_API_PORT:-${config.port}}:7700"
+      - "\${FELTDB_REPLICATION_PORT:-${config.replicationPort}}:${config.replicationPort}"
+    volumes:
+      - feltdb_data:/data
+      - ./feltdb.flow:/app/feltdb.flow:ro
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7700/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    restart: unless-stopped
+    networks:
+      - feltdb_network
+    labels:
+      app.feltdb/component: "database"
+      app.feltdb/version: "${config.version}"
+
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        NODE_ENV: production
+    container_name: \${COMPOSE_PROJECT_NAME}-app
+    environment:
+      FELTDB_API_URL: http://feltdb:7700
+      FELTDB_APP_NAME: \${FELTDB_APP_NAME:-${config.appName}}
+      NODE_ENV: \${NODE_ENV:-production}
+    ports:
+      - "\${APP_PORT:-3000}:3000"
+    depends_on:
+      feltdb:
+        condition: service_healthy
+    volumes:
+      - ./src:/app/src
+      - app_node_modules:/app/node_modules
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    restart: unless-stopped
+    networks:
+      - feltdb_network
+    labels:
+      app.feltdb/component: "application"
+      app.feltdb/version: "${config.version}"
+
+  studio:
+    image: rkendel1/feltdb-studio:latest
+    container_name: \${COMPOSE_PROJECT_NAME}-studio
+    environment:
+      FELTDB_API_URL: http://feltdb:7700
+      APP_URL: http://app:3000
+    ports:
+      - "\${STUDIO_PORT:-${config.studioPort}}:8000"
+    depends_on:
+      - feltdb
+      - app
+    networks:
+      - feltdb_network
+    labels:
+      app.feltdb/component: "studio"
+
+networks:
+  feltdb_network:
+    driver: bridge
+    labels:
+      app.feltdb/network: "internal"
+
+volumes:
+  feltdb_data:
+    driver: local
+    labels:
+      app.feltdb/data: "durable-operations-log"
+  app_node_modules:
+    driver: local
+`;
+}
+export function generateDockerfile(config, framework) {
+    const buildCommand = framework === 'react' ? 'npm run build' : 'npm run build';
+    return `# FeltDB Application Container
+# Multi-stage build for optimized production image
+
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci --only=production && npm cache clean --force
+
+# Copy source
+COPY . .
+
+# Build application
+RUN ${buildCommand}
+
+# Final stage
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Install health check utility
+RUN apk add --no-cache curl
+
+# Copy built application
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/feltdb.flow ./feltdb.flow
+
+# Create data directory for Node runtime
+RUN mkdir -p /data && chmod 755 /data
+
+# Non-root user for security
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nodejs -u 1001
+USER nodejs
+
+# Health check
+HEALTHCHECK --interval=10s --timeout=5s --retries=3 --start-period=30s \\
+  CMD curl -f http://localhost:3000/health || exit 1
+
+# Startup
+ENV NODE_ENV=production
+EXPOSE 3000
+
+CMD ["node", "dist/index.js"]
+`;
+}
+export function generateDockerIgnore() {
+    return `node_modules
+npm-debug.log
+dist
+build
+.git
+.gitignore
+.env
+.env.local
+.env.*.local
+.DS_Store
+*.log
+.feltdb/keys.json
+.feltdb/connection.json
+.nextc
+.next
+coverage
+.nyc_output
+.cache
+.turbo
+`;
+}
+export function generateDotEnvLocal(config) {
+    return `# Docker Compose Environment
+# Generated by create-feltdb for \${config.appName}
+
+COMPOSE_PROJECT_NAME=${config.appName.toLowerCase().replace(/[^a-z0-9]/g, '-')}
+
+# FeltDB Configuration
+FELTDB_APP_NAME=${config.appName}
+FELTDB_APP_ID=${config.appId}
+FELTDB_VERSION=${config.version}
+FELTDB_API_PORT=${config.port}
+FELTDB_REPLICATION_PORT=${config.replicationPort}
+FELTDB_PEERS=
+
+# Application Configuration
+APP_PORT=3000
+FELTDB_API_URL=http://feltdb:7700
+
+# Studio Configuration
+STUDIO_PORT=${config.studioPort}
+
+# Runtime
+NODE_ENV=production
+`;
+}
+export function generateHealthCheckScript() {
+    return `#!/bin/bash
+
+# Multi-service health check orchestration
+# Ensures all services are ready before marking deployment as healthy
+
+set -e
+
+TIMEOUT=60
+ELAPSED=0
+INTERVAL=2
+
+echo "[Health Check] Starting orchestration check (timeout: \${TIMEOUT}s)"
+
+# Wait for FeltDB
+echo "[Health Check] Checking FeltDB service..."
+while [ \$ELAPSED -lt \$TIMEOUT ]; do
+  if curl -s -f http://feltdb:7700/health > /dev/null 2>&1; then
+    STATE=\$(curl -s http://feltdb:7700/health | grep -o '"state":"[^"]*' | cut -d'"' -f4)
+    if [ "\$STATE" = "ready" ] || [ "\$STATE" = "recovering" ]; then
+      echo "[Health Check] FeltDB is \$STATE"
+      break
+    fi
+  fi
+  sleep \$INTERVAL
+  ELAPSED=\$((ELAPSED + INTERVAL))
+done
+
+if [ \$ELAPSED -ge \$TIMEOUT ]; then
+  echo "[Health Check] FAILED: FeltDB did not respond within timeout"
+  exit 1
+fi
+
+# Wait for application
+echo "[Health Check] Checking application service..."
+ELAPSED=0
+while [ \$ELAPSED -lt \$TIMEOUT ]; do
+  if curl -s -f http://app:3000/health > /dev/null 2>&1; then
+    echo "[Health Check] Application is ready"
+    break
+  fi
+  sleep \$INTERVAL
+  ELAPSED=\$((ELAPSED + INTERVAL))
+done
+
+if [ \$ELAPSED -ge \$TIMEOUT ]; then
+  echo "[Health Check] FAILED: Application did not respond within timeout"
+  exit 1
+fi
+
+echo "[Health Check] All services healthy - deployment ready"
+exit 0
+`;
+}

package/dist/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.4.0';
+export const FELTDB_PACKAGE_VERSION = '0.4.2';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/runtime-templates.js

@@ -0,0 +1,272 @@
+/**
+ * Runtime-specific templates and configuration
+ *
+ * Generates runtime-appropriate file structure and configuration
+ * for Browser, Node, and Self-hosted deployment modes.
+ */
+export function generateBrowserRuntime(config) {
+    return {
+        feltdbInit: `import { createFeltDB } from '@feltdb/core';
+
+/**
+ * Browser Runtime
+ *
+ * Local-first FeltDB with durable IndexedDB storage.
+ * No server required. Full offline capability.
+ *
+ * AppID: ${config.appId}
+ */
+export const db = createFeltDB({
+  namespace: '${config.appName}',
+  runtime: 'browser',
+  storage: {
+    type: 'indexeddb',
+    durable: true,
+  },
+  ${config.distributed ? `
+  replication: {
+    enabled: false, // Browser cannot initiate replication
+  },` : ''}
+  health: {
+    onStateChange: (state: 'starting' | 'recovering' | 'ready' | 'failed') => {
+      console.log(\`[FeltDB Health] Browser state changed: \${state}\`);
+      window.dispatchEvent(new CustomEvent('feltdb:health', { detail: { state } }));
+    },
+  },
+});
+
+// Collections
+export const documents = db.collection('documents');
+export const reports = db.collection('reports');
+`,
+        envExample: `# Browser Runtime
+# No environment configuration needed.
+# Data persists locally in IndexedDB.
+NODE_ENV=development
+`,
+    };
+}
+export function generateNodeRuntime(config) {
+    return {
+        feltdbInit: `import { createFeltDB } from '@feltdb/core';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Node Runtime
+ *
+ * Server-side FeltDB with durable file-based storage.
+ * Can participate in distributed replication.
+ * Persistent operation log to /data directory.
+ *
+ * AppID: ${config.appId}
+ */
+
+const dataDir = process.env.FELTDB_DATA_DIR || path.join(__dirname, '..', 'data');
+if (!fs.existsSync(dataDir)) {
+  fs.mkdirSync(dataDir, { recursive: true });
+}
+
+export const db = createFeltDB({
+  namespace: '${config.appName}',
+  runtime: 'node',
+  storage: {
+    type: 'file',
+    path: dataDir,
+    durable: true,
+    fsync: true,
+  },
+  ${config.distributed ? `
+  replication: {
+    enabled: true,
+    port: parseInt(process.env.FELTDB_REPLICATION_PORT || '9000'),
+  },` : ''}
+  health: {
+    onStateChange: (state: 'starting' | 'recovering' | 'ready' | 'failed') => {
+      console.log(\`[FeltDB Health] Node state changed: \${state}\`);
+      // Emit to monitoring system
+      process.emit('feltdb:health', { state, timestamp: Date.now() });
+    },
+  },
+});
+
+// Collections
+export const documents = db.collection('documents');
+export const reports = db.collection('reports');
+
+// Startup hook
+export async function startup() {
+  console.log(\`[FeltDB] Starting Node runtime\`);
+  console.log(\`[FeltDB] App: ${config.appName} (${config.appId})\`);
+  console.log(\`[FeltDB] Version: ${config.version}\`);
+  console.log(\`[FeltDB] Data directory: \${dataDir}\`);
+  ${config.distributed ? `console.log(\`[FeltDB] Replication enabled on port \${process.env.FELTDB_REPLICATION_PORT || 9000}\`);` : ''}
+  await db.ready();
+  console.log(\`[FeltDB] Ready\`);
+}
+`,
+        envExample: `# Node Runtime
+FELTDB_DATA_DIR=./data
+FELTDB_REPLICATION_PORT=9000
+NODE_ENV=development
+`,
+        startupScript: `#!/usr/bin/env node
+
+/**
+ * Node runtime startup orchestration
+ */
+
+import { db, startup } from './feltdb.js';
+
+async function main() {
+  try {
+    await startup();
+
+    // Start HTTP server for API
+    const { createServer } = await import('./server.js');
+    const server = createServer(db);
+    const port = process.env.FELTDB_API_PORT || 7700;
+    server.listen(port, () => {
+      console.log(\`[HTTP] API server listening on port \${port}\`);
+    });
+  } catch (err) {
+    console.error('[FeltDB] Startup failed:', err);
+    process.exit(1);
+  }
+}
+
+main();
+`,
+    };
+}
+export function generateSelfHostedRuntime(config) {
+    return {
+        feltdbInit: `import { createFeltDB } from '@feltdb/core';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Self-hosted Runtime
+ *
+ * Containerized FeltDB with Docker Compose orchestration.
+ * Durable file-based storage with persistent volumes.
+ * Full replication topology with multi-node support.
+ *
+ * AppID: ${config.appId}
+ * Version: ${config.version}
+ */
+
+const dataDir = process.env.FELTDB_DATA_DIR || '/data';
+if (!fs.existsSync(dataDir)) {
+  fs.mkdirSync(dataDir, { recursive: true });
+}
+
+export const db = createFeltDB({
+  namespace: '${config.appName}',
+  runtime: 'self-hosted',
+  storage: {
+    type: 'file',
+    path: dataDir,
+    durable: true,
+    fsync: true,
+  },
+  replication: {
+    enabled: true,
+    port: 9000,
+    peers: (process.env.FELTDB_PEERS || '').split(',').filter(Boolean),
+  },
+  health: {
+    onStateChange: (state: 'starting' | 'recovering' | 'ready' | 'failed') => {
+      console.log(\`[\${new Date().toISOString()}] [FeltDB] \${state.toUpperCase()}\`);
+      // Structured logging for container orchestration
+      process.emit('feltdb:health', { state, timestamp: Date.now() });
+    },
+  },
+});
+
+// Collections
+export const documents = db.collection('documents');
+export const reports = db.collection('reports');
+
+// Startup with health check loop
+export async function startup() {
+  console.log(\`[\${new Date().toISOString()}] [FeltDB] Container starting\`);
+  console.log(\`[FeltDB] App: ${config.appName} (${config.appId})\`);
+  console.log(\`[FeltDB] Version: ${config.version}\`);
+  console.log(\`[FeltDB] Runtime: self-hosted\`);
+  console.log(\`[FeltDB] Data directory: \${dataDir}\`);
+
+  await db.ready();
+  console.log(\`[\${new Date().toISOString()}] [FeltDB] READY\`);
+}
+`,
+        envExample: `# Self-hosted Docker Runtime
+FELTDB_DATA_DIR=/data
+FELTDB_APP_NAME=${config.appName}
+FELTDB_APP_ID=${config.appId}
+FELTDB_VERSION=${config.version}
+FELTDB_REPLICATION_PORT=9000
+FELTDB_PEERS=
+NODE_ENV=production
+`,
+        healthCheck: `#!/bin/sh
+
+# Health check for Docker container
+# Verifies FeltDB is responding and not in RECOVERING state
+
+HEALTH_URL="http://localhost:7700/health"
+TIMEOUT=5
+
+# Query health endpoint
+RESPONSE=\$(curl -s -m \${TIMEOUT} \${HEALTH_URL} 2>/dev/null)
+
+if [ -z "\$RESPONSE" ]; then
+  echo "UNHEALTHY: No response from health endpoint"
+  exit 1
+fi
+
+STATE=\$(echo \$RESPONSE | grep -o '"state":"[^"]*' | cut -d'"' -f4)
+
+case "\$STATE" in
+  ready)
+    echo "HEALTHY: State is ready"
+    exit 0
+    ;;
+  recovering)
+    echo "STARTING: Recovering from disk"
+    exit 0
+    ;;
+  starting)
+    echo "STARTING: Initializing"
+    exit 0
+    ;;
+  failed)
+    echo "UNHEALTHY: State is failed"
+    exit 1
+    ;;
+  *)
+    echo "UNKNOWN: State is \$STATE"
+    exit 2
+    ;;
+esac
+`,
+    };
+}
+export function getTemplate(config) {
+    switch (config.runtime) {
+        case 'browser':
+            return generateBrowserRuntime(config);
+        case 'node':
+            return generateNodeRuntime(config);
+        case 'self-hosted':
+            return generateSelfHostedRuntime(config);
+        default:
+            throw new Error(`Unknown runtime: ${config.runtime}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-feltdb",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Create a new FeltDB application with one command",
   "license": "MIT",
   "bin": {