create-feltdb 0.2.0

package/README.md

@@ -0,0 +1,70 @@
+# create-feltdb
+
+Interactive CLI tool to scaffold new FeltDB applications.
+
+## Installation
+
+```bash
+npm install -g create-feltdb
+```
+
+## Usage
+
+Create a new project:
+
+```bash
+npx create-feltdb my-app
+```
+
+Or use the installed command:
+
+```bash
+create-feltdb my-app
+```
+
+### Options
+
+- `--yes` or `-y` - Skip interactive prompts and use defaults
+
+## What Gets Generated
+
+```
+my-app/
+├── feltdb/
+│   ├── capabilities/
+│   ├── workflows/
+│   ├── agents/
+│   └── schema/
+├── src/
+│   ├── App.tsx
+│   ├── feltdb.ts
+│   └── index.ts
+├── public/
+│   └── index.html
+├── feltdb.config.json
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Quick Start
+
+After running `create-feltdb`:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+## Default Configuration
+
+The generated project uses:
+- **Runtime**: Browser
+- **Storage**: OPFS (with IndexedDB fallback)
+- **Distributed**: Enabled by default
+- **Capabilities**: Search enabled, Vector disabled
+
+## License
+
+MIT

package/bin/create-feltdb.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+await import('../dist/cli.js');

package/dist/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * create-feltdb
+ *
+ * Interactive CLI for creating new FeltDB applications
+ */
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+import { createProject } from './create.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function parseArgs(args) {
+    const options = {
+        runtime: 'browser',
+        framework: 'react',
+        distributed: true,
+        agents: true,
+        capabilities: 'search',
+    };
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--runtime':
+                options.runtime = args[++i];
+                break;
+            case '--framework':
+                options.framework = args[++i];
+                break;
+            case '--no-distributed':
+                options.distributed = false;
+                break;
+            case '--no-agents':
+                options.agents = false;
+                break;
+            case '--capabilities':
+                options.capabilities = args[++i];
+                break;
+        }
+    }
+    return options;
+}
+async function select(message, choices, initialValue) {
+    let selected = Math.max(0, choices.findIndex(choice => choice.value === initialValue));
+    const input = process.stdin;
+    const output = process.stdout;
+    const wasRaw = input.isRaw;
+    readline.emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    const render = (moveUp) => {
+        if (moveUp)
+            output.write(`\x1b[${choices.length}A`);
+        for (let index = 0; index < choices.length; index++) {
+            const choice = choices[index];
+            const active = index === selected;
+            const detail = choice.description ? ` \x1b[2m— ${choice.description}\x1b[22m` : '';
+            output.write(`\x1b[2K\r  ${active ? '\x1b[36m❯' : ' '} ${choice.label}${active ? '\x1b[0m' : ''}${detail}\n`);
+        }
+    };
+    output.write(`${message}\n`);
+    render(false);
+    return new Promise(resolve => {
+        const finish = () => {
+            input.off('keypress', onKeypress);
+            input.setRawMode(Boolean(wasRaw));
+            input.pause();
+            resolve(choices[selected].value);
+        };
+        const onKeypress = (_value, key) => {
+            if (key.ctrl && key.name === 'c') {
+                output.write('\n');
+                input.setRawMode(Boolean(wasRaw));
+                process.exit(130);
+            }
+            if (key.name === 'up')
+                selected = (selected - 1 + choices.length) % choices.length;
+            else if (key.name === 'down')
+                selected = (selected + 1) % choices.length;
+            else if (key.name === 'return' || key.name === 'enter')
+                return finish();
+            else
+                return;
+            render(true);
+        };
+        input.on('keypress', onKeypress);
+    });
+}
+async function promptForOptions(defaults) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return defaults;
+    console.log('Configure your application. Use ↑/↓ to move and Enter to select.\n');
+    const yesNo = [
+        { label: 'Yes', value: true },
+        { label: 'No', value: false },
+    ];
+    return {
+        runtime: await select('Where should FeltDB run?', [
+            { label: 'Browser', value: 'browser', description: 'local-first with durable browser storage' },
+            { label: 'Node.js', value: 'node', description: 'application server or worker' },
+            { label: 'Self-hosted', value: 'self-hosted', description: 'dedicated FeltDB server' },
+        ], defaults.runtime),
+        framework: await select('Choose an application framework:', [
+            { label: 'React', value: 'react' },
+            { label: 'Vanilla TypeScript', value: 'vanilla' },
+        ], defaults.framework),
+        distributed: await select('Enable distributed operation?', yesNo, defaults.distributed),
+        agents: await select('Include an autonomous agent example?', yesNo, defaults.agents),
+        capabilities: await select('Choose starter capabilities:', [
+            { label: 'Search', value: 'search' },
+            { label: 'Vector search', value: 'vector' },
+            { label: 'Search + vector search', value: 'search,vector' },
+        ], defaults.capabilities),
+    };
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const projectName = args[0] || 'feltdb-app';
+    const shouldAutoYes = args.includes('--yes') || args.includes('-y');
+    let options = parseArgs(args);
+    console.log('\n✨ Creating FeltDB Application\n');
+    if (!shouldAutoYes) {
+        options = await promptForOptions(options);
+        console.log('\nConfiguration:');
+        console.log(`  Runtime:       ${options.runtime}`);
+        console.log(`  Framework:     ${options.framework}`);
+        console.log(`  Distributed:   ${options.distributed ? 'yes' : 'no'}`);
+        console.log(`  Agents:        ${options.agents ? 'yes' : 'no'}`);
+        console.log(`  Capabilities:  ${options.capabilities}\n`);
+    }
+    try {
+        await createProject({
+            projectName,
+            autoYes: shouldAutoYes,
+            templatesDir: path.join(__dirname, '../templates'),
+            runtime: options.runtime,
+            framework: options.framework,
+            distributed: options.distributed,
+            agents: options.agents,
+            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`);
+        }
+        else {
+            console.log(`  npm run dev`);
+        }
+        console.log('');
+    }
+    catch (error) {
+        console.error('❌ Failed to create project:', error);
+        process.exit(1);
+    }
+}
+main();

package/dist/create.js

@@ -0,0 +1,573 @@
+/**
+ * Project creation logic
+ */
+import fs from 'fs';
+import path from 'path';
+import { feltdbPackageRange } from './package-versions.js';
+export async function createProject(options) {
+    const { projectName, templatesDir } = options;
+    const projectDir = path.resolve(process.cwd(), projectName);
+    const applicationName = path.basename(projectDir);
+    // Create project directory
+    if (!fs.existsSync(projectDir)) {
+        fs.mkdirSync(projectDir, { recursive: true });
+    }
+    // Create feltdb directory structure
+    const feltdbDir = path.join(projectDir, 'feltdb');
+    const srcDir = path.join(projectDir, 'src');
+    const publicDir = path.join(projectDir, 'public');
+    const feltdbConfigDir = path.join(projectDir, '.feltdb');
+    fs.mkdirSync(path.join(feltdbDir, 'capabilities'), { recursive: true });
+    fs.mkdirSync(path.join(feltdbDir, 'workflows'), { recursive: true });
+    fs.mkdirSync(path.join(feltdbDir, 'agents'), { recursive: true });
+    fs.mkdirSync(path.join(feltdbDir, 'schema'), { recursive: true });
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(publicDir, { recursive: true });
+    fs.mkdirSync(feltdbConfigDir, { recursive: true });
+    const runtime = options.runtime || 'browser';
+    const framework = options.framework || 'react';
+    const distributed = options.distributed !== false;
+    const hasAgents = options.agents !== false;
+    const capabilities = options.capabilities || 'search';
+    // Create package.json
+    const packageJson = {
+        name: applicationName,
+        version: '0.1.0',
+        description: `A FeltDB application`,
+        main: 'src/index.ts',
+        type: 'module',
+        scripts: {
+            dev: 'feltdb dev',
+            build: 'feltdb build',
+            test: 'node --test',
+            feltdb: 'feltdb',
+            'feltdb:server': 'feltdb server',
+            'feltdb:connect': 'feltdb connect http://localhost:7700',
+            'feltdb:status': 'feltdb status',
+            'feltdb:studio': 'feltdb studio',
+            'feltdb:validate': 'feltdb validate',
+            'feltdb:diff': 'feltdb diff',
+            'feltdb:deploy': 'feltdb deploy',
+        },
+        dependencies: {
+            '@feltdb/core': feltdbPackageRange,
+        },
+        devDependencies: {
+            '@feltdb/cli': feltdbPackageRange,
+            typescript: '^5.0.0',
+            '@types/node': '^20.0.0',
+            vite: '^8.2.1',
+        },
+    };
+    if (framework === 'react') {
+        packageJson.dependencies['@feltdb/react'] = feltdbPackageRange;
+        packageJson.dependencies['react'] = '^18.0.0';
+        packageJson.dependencies['react-dom'] = '^18.0.0';
+        packageJson.devDependencies['@types/react'] = '^18.0.0';
+        packageJson.devDependencies['@types/react-dom'] = '^18.0.0';
+    }
+    fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+    // Create feltdb.config.json
+    const feltdbConfig = {
+        namespace: applicationName,
+        runtime,
+        storage: runtime === 'browser' ? 'opfs' : 'durable',
+        distributed,
+        agents: {
+            enabled: hasAgents,
+        },
+        capabilities: {},
+    };
+    if (capabilities.includes('search')) {
+        feltdbConfig.capabilities.search = true;
+    }
+    if (capabilities.includes('vector')) {
+        feltdbConfig.capabilities['vector-search'] = true;
+    }
+    fs.writeFileSync(path.join(projectDir, 'feltdb.config.json'), JSON.stringify(feltdbConfig, null, 2));
+    const appName = applicationName.replace(/[^A-Za-z0-9_]/g, '_').replace(/^[^A-Za-z_]/, 'App_');
+    const flowSpec = `app ${appName} {
+  collection Document {
+    title: text
+    content: text
+    createdAt: datetime
+    index search using fulltext(content)
+  }
+
+  collection Report {
+    title: text
+    content: text
+    document: ref Document
+  }
+
+  capability Research {
+    read Document
+    write Report
+  }
+
+  agent Researcher {
+    capability Research
+    workflow ResearchDocument
+  }
+
+  workflow ResearchDocument(document: Document) {
+    step search {
+      input document.content
+    }
+    step identity {
+      input search.output
+    }
+  }
+
+  trigger on Document.created {
+    workflow ResearchDocument(document)
+  }
+
+  policy Document {
+    read: authenticated
+    write: authenticated
+  }
+}
+`;
+    fs.writeFileSync(path.join(projectDir, 'feltdb.flow'), flowSpec);
+    // Create tsconfig.json
+    const tsconfig = {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'ESNext',
+            lib: ['ES2020', 'DOM'],
+            declaration: true,
+            outDir: './dist',
+            rootDir: './src',
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+            moduleResolution: 'node',
+        },
+        include: ['src/**/*'],
+        exclude: ['node_modules'],
+    };
+    if (framework === 'react') {
+        tsconfig.compilerOptions.jsx = 'react-jsx';
+    }
+    fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
+    // Create main application files
+    const feltdbTs = `import { createFeltDB } from '@feltdb/core';
+
+export const db = createFeltDB({
+  namespace: '${applicationName}',
+  memory: true, // Development-only; configure \`server\` for durable customer data.
+});
+
+// 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
+    if (hasAgents) {
+        const agentTs = `import { db } from '../feltdb';
+
+/**
+ * Researcher Agent
+ * 
+ * This agent demonstrates distributed agent execution
+ * across peers in the FeltDB fabric.
+ */
+export const researcher = db.defineAgent({
+  name: 'researcher',
+  description: 'Search and analyze documents across the fabric',
+  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'
+      }
+    };
+  }
+});
+`;
+        fs.writeFileSync(path.join(feltdbDir, 'agents', 'researcher.ts'), agentTs);
+    }
+    // Create capabilities index
+    const capabilitiesTs = `/**
+ * Capabilities
+ * 
+ * Define capabilities that can be executed by agents
+ * across distributed peers
+ */
+
+export const capabilities = {
+  'document-read': {
+    enabled: true,
+    scope: ['documents:read'],
+  },
+  'vector-search': {
+    enabled: ${capabilities.includes('vector')},
+    scope: ['documents:read', 'capabilities:execute'],
+  },
+  'report-write': {
+    enabled: true,
+    scope: ['reports:write'],
+  },
+};
+`;
+    fs.writeFileSync(path.join(feltdbDir, 'capabilities', 'index.ts'), capabilitiesTs);
+    // Create main application file based on framework
+    if (framework === 'react') {
+        const appTsx = `import React, { useState, useEffect } from 'react';
+import { db, documents } from './feltdb';
+
+export function App() {
+  const [docs, setDocs] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const loadDocs = async () => {
+      try {
+        const allDocs = await documents.find({});
+        setDocs(allDocs);
+      } catch (err) {
+        console.error('Error loading documents:', err);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadDocs();
+  }, []);
+
+  const handleAddDocument = async () => {
+    try {
+      await documents.insert({
+        title: 'New Document',
+        content: 'Enter content here',
+        createdAt: new Date(),
+      });
+      // Reload documents
+      const allDocs = await documents.find({});
+      setDocs(allDocs);
+    } catch (err) {
+      console.error('Error adding document:', err);
+    }
+  };
+
+  return (
+    <div className="app">
+      <header>
+        <h1>🌊 FeltDB Research App</h1>
+        <p>Distributed document management with agents and capabilities</p>
+      </header>
+
+      <main>
+        <section className="stats">
+          <div className="stat">
+            <span className="label">Documents:</span>
+            <span className="value">{docs.length}</span>
+          </div>
+          <div className="stat">
+            <span className="label">Runtime:</span>
+            <span className="value">${runtime}</span>
+          </div>
+          <div className="stat">
+            <span className="label">Distributed:</span>
+            <span className="value">${distributed ? '✓' : '✗'}</span>
+          </div>
+        </section>
+
+        <section className="documents">
+          <h2>Documents</h2>
+          {loading ? (
+            <p>Loading...</p>
+          ) : docs.length === 0 ? (
+            <p>No documents yet</p>
+          ) : (
+            <ul>
+              {docs.map((doc: any) => (
+                <li key={doc.id}>
+                  <h3>{doc.title}</h3>
+                  <p>{doc.content}</p>
+                </li>
+              ))}
+            </ul>
+          )}
+          <button onClick={handleAddDocument}>Add Document</button>
+        </section>
+      </main>
+
+      <style>{\`
+        body {
+          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
+          margin: 0;
+          padding: 0;
+          background: #f5f5f5;
+        }
+
+        .app {
+          max-width: 1200px;
+          margin: 0 auto;
+          padding: 20px;
+        }
+
+        header {
+          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+          color: white;
+          padding: 30px;
+          border-radius: 8px;
+          margin-bottom: 30px;
+        }
+
+        header h1 {
+          margin: 0 0 10px 0;
+          font-size: 28px;
+        }
+
+        header p {
+          margin: 0;
+          opacity: 0.9;
+        }
+
+        main {
+          background: white;
+          padding: 20px;
+          border-radius: 8px;
+          box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+        }
+
+        .stats {
+          display: grid;
+          grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+          gap: 20px;
+          margin-bottom: 30px;
+        }
+
+        .stat {
+          padding: 15px;
+          background: #f9f9f9;
+          border-radius: 4px;
+          border-left: 3px solid #667eea;
+        }
+
+        .stat .label {
+          display: block;
+          color: #666;
+          font-size: 12px;
+          text-transform: uppercase;
+          margin-bottom: 5px;
+        }
+
+        .stat .value {
+          display: block;
+          font-size: 24px;
+          font-weight: bold;
+          color: #333;
+        }
+
+        .documents h2 {
+          margin-top: 0;
+        }
+
+        .documents ul {
+          list-style: none;
+          padding: 0;
+          margin: 0 0 20px 0;
+        }
+
+        .documents li {
+          padding: 15px;
+          background: #f9f9f9;
+          border-radius: 4px;
+          margin-bottom: 10px;
+        }
+
+        .documents h3 {
+          margin: 0 0 10px 0;
+          color: #333;
+        }
+
+        .documents p {
+          margin: 0;
+          color: #666;
+          font-size: 14px;
+        }
+
+        button {
+          background: #667eea;
+          color: white;
+          border: none;
+          padding: 10px 20px;
+          border-radius: 4px;
+          cursor: pointer;
+          font-size: 14px;
+          font-weight: 500;
+        }
+
+        button:hover {
+          background: #5568d3;
+        }
+      \`}</style>
+    </div>
+  );
+}
+`;
+        fs.writeFileSync(path.join(srcDir, 'App.tsx'), appTsx);
+        const indexTsx = `import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { App } from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root')!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+`;
+        fs.writeFileSync(path.join(srcDir, 'index.tsx'), indexTsx);
+    }
+    else {
+        // Create vanilla JS app
+        const indexJs = `import { db, documents } from './feltdb';
+
+async function main() {
+  console.log('🌊 FeltDB Research App');
+  console.log('Runtime: ${runtime}');
+  console.log('Distributed: ${distributed}');
+}
+
+main().catch(console.error);
+`;
+        fs.writeFileSync(path.join(srcDir, 'index.js'), indexJs);
+    }
+    // Create index.html
+    const indexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${applicationName}</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/index${framework === 'react' ? '.tsx' : '.js'}"></script>
+</body>
+</html>
+`;
+    fs.writeFileSync(path.join(projectDir, 'index.html'), indexHtml);
+    // Create .env.example
+    const envExample = `# FeltDB Configuration
+FELTDB_API_KEY=
+FELTDB_URL=http://localhost:7700
+NODE_ENV=development
+`;
+    fs.writeFileSync(path.join(projectDir, '.env.example'), envExample);
+    // Create .gitignore
+    const gitignore = `node_modules/
+dist/
+build/
+.env
+.env.local
+.env.*.local
+*.log
+.DS_Store
+.feltdb/keys.json
+.feltdb/connection.json
+`;
+    fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignore);
+    // Create README
+    const readme = `# ${applicationName}
+
+A FeltDB distributed application with agents and capabilities.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+${applicationName}/
+├── feltdb/
+│   ├── agents/            # Agent definitions
+│   ├── capabilities/      # Capability implementations
+│   ├── workflows/         # Workflow definitions
+│   └── schema/            # Data schemas
+├── src/
+│   ├── App.${framework === 'react' ? 'tsx' : 'js'}
+│   ├── feltdb.ts
+│   └── index.${framework === 'react' ? 'tsx' : 'js'}
+├── public/
+├── index.html
+├── .feltdb/               # Local FeltDB configuration
+├── feltdb.config.json
+├── .env.example
+├── package.json
+├── tsconfig.json
+└── README.md
+\`\`\`
+
+## Configuration
+
+Configuration is in \`feltdb.config.json\`:
+- \`runtime\`: ${runtime} (browser|node|self-hosted)
+- \`storage\`: ${runtime === 'browser' ? 'opfs' : 'durable'}
+- \`distributed\`: ${distributed}
+- \`agents.enabled\`: ${hasAgents}
+- \`capabilities\`: ${capabilities}
+
+## Development
+
+### Start Development Server
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### Build for Production
+\`\`\`bash
+npm run build
+\`\`\`
+
+### Connect to Remote Server
+\`\`\`bash
+feltdb connect http://localhost:7700
+\`\`\`
+
+### Create API Key
+\`\`\`bash
+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'}
+
+## Capabilities
+
+${capabilities}
+
+## Learn More
+
+Visit [FeltDB Documentation](https://github.com/rkendel1/feltdb) to learn more.
+`;
+    fs.writeFileSync(path.join(projectDir, 'README.md'), readme);
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+/**
+ * create-feltdb - Main exports
+ */
+export * from './create';

package/dist/package-versions.js

@@ -0,0 +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.2.0';
+export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-feltdb",
+  "version": "0.2.0",
+  "description": "Create a new FeltDB application with one command",
+  "license": "MIT",
+  "bin": {
+    "create-feltdb": "bin/create-feltdb.js"
+  },
+  "main": "dist/index.js",
+  "type": "module",
+  "files": [
+    "dist/",
+    "bin/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "dev": "node dist/cli.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rkendel1/feltdb.git",
+    "directory": "tools/create-feltdb"
+  },
+  "keywords": [
+    "feltdb",
+    "database",
+    "scaffold",
+    "template",
+    "cli"
+  ]
+}