create-feltdb 0.4.0 → 0.4.1

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/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.1\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.1');
         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/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.1';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/package.json

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