@feltdb/core 0.4.4 → 0.4.6

package/dist/create/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/create/index.js

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

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

package/dist/create/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/dist/index-backend.js

@@ -11,7 +11,7 @@ async function loadWasm() {
     try {
         // Try to import WASM module
         // @ts-ignore - WASM module is optional and built separately
-        const wasmModule = await import('@feltdb/wasm');
+        const wasmModule = await import('./wasm/feltdb_wasm.js');
         wasmIndexModule = wasmModule;
         wasmAvailable = true;
         return wasmModule;

package/dist/migrate/analyzer/index.d.ts

@@ -0,0 +1,2 @@
+import type { Analysis } from '../types/index.js';
+export declare function analyze(sourceRoot: string, schemaFile: string): Promise<Analysis>;

package/dist/migrate/analyzer/index.js

@@ -0,0 +1,34 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { hash, json } from '../util.js';
+const CODE = /\.(?:[cm]?[jt]sx?|sql|prisma|py|rb|go)$/;
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'target', '.feltdb']);
+async function files(root, dir = root, out = []) { for (const n of await readdir(dir)) {
+    if (SKIP.has(n))
+        continue;
+    const p = join(dir, n), s = await stat(p);
+    if (s.isDirectory())
+        await files(root, p, out);
+    else if (CODE.test(n))
+        out.push(p);
+} return out.sort(); }
+export async function analyze(sourceRoot, schemaFile) {
+    const raw = await json(schemaFile);
+    const entities = (raw.entities ?? raw.tables ?? []).map(e => ({ ...e, kind: e.kind ?? 'table' })).sort((a, b) => a.name.localeCompare(b.name));
+    if (!entities.length)
+        throw new Error('Schema contains no entities');
+    const names = new Set(entities.map(e => e.name)), findings = [];
+    for (const file of await files(sourceRoot)) {
+        const text = await readFile(file, 'utf8');
+        for (const [i, line] of text.split(/\r?\n/).entries()) {
+            const hit = [...names].filter(n => line.includes(n));
+            if (!hit.length)
+                continue;
+            const kind = /\b(SELECT|INSERT|UPDATE|DELETE|JOIN)\b/i.test(line) ? 'sql' : /fetch\(|axios|useQuery|poll|subscribe/i.test(line) ? 'consumer' : 'reference';
+            findings.push({ file: relative(sourceRoot, file), line: i + 1, kind, value: line.trim().slice(0, 300), entities: hit });
+        }
+    }
+    const dependencies = entities.flatMap(e => (e.foreignKeys ?? []).map(f => ({ from: e.name, to: f.referencedTable }))).sort((a, b) => `${a.from}:${a.to}`.localeCompare(`${b.from}:${b.to}`));
+    const core = { version: 1, sourceRoot, entities, findings, dependencies };
+    return { ...core, generatedAt: new Date().toISOString(), schemaHash: hash({ entities, dependencies }) };
+}

package/dist/migrate/benchmark/index.d.ts

@@ -0,0 +1,13 @@
+export interface BenchmarkWorkload {
+    name: string;
+    iterations?: number;
+    run(): Promise<void>;
+}
+export interface BenchmarkResult {
+    name: string;
+    iterations: number;
+    totalMs: number;
+    meanMs: number;
+    operationsPerSecond: number;
+}
+export declare function benchmark(workloads: BenchmarkWorkload[]): Promise<BenchmarkResult[]>;

package/dist/migrate/benchmark/index.js

@@ -0,0 +1,8 @@
+import { performance } from 'node:perf_hooks';
+export async function benchmark(workloads) { const results = []; for (const w of workloads) {
+    const iterations = w.iterations ?? 100, start = performance.now();
+    for (let i = 0; i < iterations; i++)
+        await w.run();
+    const totalMs = performance.now() - start;
+    results.push({ name: w.name, iterations, totalMs, meanMs: totalMs / iterations, operationsPerSecond: iterations / (totalMs / 1000) });
+} return results; }

package/dist/migrate/capability-gate/index.d.ts

@@ -0,0 +1,3 @@
+import type { Capabilities } from '../types/index.js';
+export declare const REQUIRED: string[];
+export declare function gate(capabilities: Capabilities, required?: string[]): void;

package/dist/migrate/capability-gate/index.js

@@ -0,0 +1,3 @@
+export const REQUIRED = ['atomicTransactions', 'immutableHistory', 'deterministicOrdering', 'durablePersistence', 'indexedQueries', 'tenantIsolation', 'idempotentWrites', 'concurrencySafety', 'reconstruction', 'versionConflicts', 'canonicalStateRefresh', 'stateHistorySeparation', 'uiStateContract'];
+export function gate(capabilities, required = REQUIRED) { const missing = required.filter(x => capabilities[x] !== true); if (missing.length)
+    throw new Error(`Missing FeltDB platform capabilities: ${missing.join(', ')}`); }

package/dist/migrate/classifier/index.d.ts

@@ -0,0 +1,3 @@
+import type { Analysis, Classification, ClassificationResult } from '../types/index.js';
+export declare function classify(a: Analysis, threshold?: number, overrides?: Record<string, Classification>, blobLimit?: number): ClassificationResult;
+export declare function approve(result: ClassificationResult): ClassificationResult;

package/dist/migrate/classifier/index.js

@@ -0,0 +1,53 @@
+import { hash } from '../util.js';
+const secret = /(password|secret|token|credential|private_key|certificate|api_key)/i, blob = /(bytea|blob|binary|image|wasm|archive)/i;
+export function classify(a, threshold = .8, overrides = {}, blobLimit = 262144) {
+    const entities = a.entities.map(e => {
+        let classification, confidence = .72, reasons = [];
+        const cols = e.columns;
+        if (overrides[e.name]) {
+            classification = overrides[e.name];
+            confidence = 1;
+            reasons = ['configuration override'];
+        }
+        else if (cols.some(c => secret.test(c.name))) {
+            classification = 'SECRET_REFERENCE';
+            confidence = .98;
+            reasons = ['security-sensitive column'];
+        }
+        else if (cols.some(c => blob.test(c.type) || blob.test(c.name) || (c.sizeBytes ?? 0) > blobLimit)) {
+            classification = 'BLOB_REFERENCE';
+            confidence = .95;
+            reasons = ['binary or large payload'];
+        }
+        else if ((e.foreignKeys?.length ?? 0) >= 2 && cols.filter(c => c.primaryKey).length >= 2) {
+            classification = 'RELATIONSHIP';
+            confidence = .9;
+            reasons = ['junction-table shape'];
+        }
+        else if (/(_events?|_history|_audit|_logs?)$/i.test(e.name)) {
+            classification = 'HISTORY';
+            confidence = .92;
+            reasons = ['event/history naming', 'timestamp ordering likely'];
+        }
+        else if (e.kind === 'view') {
+            classification = 'MATERIALIZED';
+            confidence = .9;
+            reasons = ['database view'];
+        }
+        else if (/(_cache|_jobs?|_locks?|_sessions?)$/i.test(e.name)) {
+            classification = 'OPERATIONAL';
+            confidence = .82;
+            reasons = ['operational naming'];
+        }
+        else {
+            classification = 'STATE';
+            confidence = .78;
+            reasons = ['mutable entity shape'];
+        }
+        return { entity: e.name, classification, confidence, reasons, requiresApproval: confidence < threshold };
+    });
+    const payload = { version: 1, threshold, entities };
+    return { ...payload, classificationHash: hash(payload), approved: false };
+}
+export function approve(result) { if (result.entities.some(e => e.requiresApproval))
+    throw new Error('Low-confidence classifications require explicit overrides before approval'); return { ...result, approved: true }; }

package/dist/migrate/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};