Add Elysia server foundation with health and stats endpoints

Phase 1 of Forest server mode implementation:
- Extract core business logic into src/core/ (health, stats)
- Add Bun + Elysia server with REST API (src/server/)
- Implement /api/v1/health and /api/v1/stats endpoints
- Add 'forest serve' CLI command
- Include auto-generated Swagger/OpenAPI docs at /swagger
- Refactor CLI commands to use shared core modules

Server runs at http://localhost:3000 with CORS and consistent JSON response envelopes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bwl

bun.lock

@@ -9,6 +9,7 @@
     "build": "tsc",
     "lint": "tsc --noEmit",
     "dev": "ts-node src/index.ts",
+    "dev:server": "bun run src/server/index.ts",
     "start": "node dist/index.js"
   },
   "keywords": [
@@ -20,8 +21,11 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@elysiajs/cors": "^1.1.1",
+    "@elysiajs/swagger": "^1.1.5",
     "@xenova/transformers": "^2.17.2",
     "clerc": "^0.44.0",
+    "elysia": "^1.1.22",
     "graphology": "^0.25.1",
     "sql.js": "^1.11.0"
   },

package.json

@@ -1,7 +1,4 @@
-import fs from 'fs';
-import path from 'path';
-
-import { getEmbeddingProvider, embeddingsEnabled } from '../../lib/embeddings';
+import { getHealthReport, isHealthy, HealthCheck } from '../../core/health';
 import { handleError } from '../shared/utils';
 
 type ClercModule = typeof import('clerc');
@@ -10,8 +7,6 @@ type HealthFlags = {
   json?: boolean;
 };
 
-const DEFAULT_DB_PATH = 'forest.db';
-
 export function createHealthCommand(clerc: ClercModule) {
   return clerc.defineCommand(
     {
@@ -34,32 +29,8 @@ export function createHealthCommand(clerc: ClercModule) {
   );
 }
 
-type HealthCheck = {
-  status: 'ok' | 'warning' | 'error';
-  message: string;
-};
-
-type HealthReport = {
-  database: HealthCheck & { path?: string; sizeBytes?: number };
-  embeddingProvider: HealthCheck & { provider?: string };
-  openaiKey?: HealthCheck;
-  localTransformer?: HealthCheck;
-};
-
 async function runHealth(flags: HealthFlags) {
-  const report: HealthReport = {
-    database: await checkDatabase(),
-    embeddingProvider: await checkEmbeddingProvider(),
-  };
-
-  const provider = getEmbeddingProvider();
-  if (provider === 'openai') {
-    report.openaiKey = checkOpenAIKey();
-  }
-
-  if (provider === 'local') {
-    report.localTransformer = await checkLocalTransformer();
-  }
+  const report = await getHealthReport();
 
   if (flags.json) {
     console.log(JSON.stringify(report, null, 2));
@@ -95,14 +66,7 @@ async function runHealth(flags: HealthFlags) {
     console.log('');
   }
 
-  const allOk = [
-    report.database.status === 'ok',
-    report.embeddingProvider.status === 'ok',
-    !report.openaiKey || report.openaiKey.status === 'ok',
-    !report.localTransformer || report.localTransformer.status === 'ok',
-  ].every(Boolean);
-
-  if (allOk) {
+  if (isHealthy(report)) {
     console.log('✔ All systems operational');
   } else {
     console.log('⚠ Some checks failed. Review the output above.');
@@ -114,155 +78,3 @@ function printCheck(label: string, check: HealthCheck) {
   const icon = check.status === 'ok' ? '✔' : check.status === 'warning' ? '⚠' : '✖';
   console.log(`${icon} ${label}: ${check.message}`);
 }
-
-async function checkDatabase(): Promise<HealthCheck & { path?: string; sizeBytes?: number }> {
-  const dbPath = process.env.FOREST_DB_PATH ?? DEFAULT_DB_PATH;
-  const resolvedPath = path.resolve(dbPath);
-
-  if (!fs.existsSync(resolvedPath)) {
-    return {
-      status: 'warning',
-      message: 'Database file does not exist yet (will be created on first capture)',
-      path: resolvedPath,
-    };
-  }
-
-  try {
-    const stats = fs.statSync(resolvedPath);
-    if (!stats.isFile()) {
-      return {
-        status: 'error',
-        message: 'Database path exists but is not a file',
-        path: resolvedPath,
-      };
-    }
-
-    // Try to read the first few bytes to verify it's accessible
-    const fd = fs.openSync(resolvedPath, 'r');
-    const buffer = Buffer.alloc(16);
-    fs.readSync(fd, buffer, 0, 16, 0);
-    fs.closeSync(fd);
-
-    // Check if it looks like a SQLite file (magic: "SQLite format 3\0")
-    const magic = buffer.toString('utf-8', 0, 15);
-    if (!magic.startsWith('SQLite format 3')) {
-      return {
-        status: 'warning',
-        message: 'File exists but may not be a valid SQLite database',
-        path: resolvedPath,
-        sizeBytes: stats.size,
-      };
-    }
-
-    return {
-      status: 'ok',
-      message: 'Database file is accessible and valid',
-      path: resolvedPath,
-      sizeBytes: stats.size,
-    };
-  } catch (error) {
-    return {
-      status: 'error',
-      message: `Cannot access database file: ${error instanceof Error ? error.message : String(error)}`,
-      path: resolvedPath,
-    };
-  }
-}
-
-async function checkEmbeddingProvider(): Promise<HealthCheck & { provider?: string }> {
-  const provider = getEmbeddingProvider();
-  const enabled = embeddingsEnabled();
-
-  if (!enabled) {
-    return {
-      status: 'warning',
-      message: 'Embeddings are disabled (pure lexical scoring)',
-      provider,
-    };
-  }
-
-  if (provider === 'mock') {
-    return {
-      status: 'warning',
-      message: 'Using mock embeddings (deterministic, non-semantic)',
-      provider,
-    };
-  }
-
-  if (provider === 'openai') {
-    return {
-      status: 'ok',
-      message: 'Using OpenAI embeddings',
-      provider,
-    };
-  }
-
-  if (provider === 'local') {
-    return {
-      status: 'ok',
-      message: 'Using local transformer embeddings',
-      provider,
-    };
-  }
-
-  return {
-    status: 'ok',
-    message: `Provider: ${provider}`,
-    provider,
-  };
-}
-
-function checkOpenAIKey(): HealthCheck {
-  const apiKey = process.env.OPENAI_API_KEY;
-
-  if (!apiKey) {
-    return {
-      status: 'error',
-      message: 'OPENAI_API_KEY is not set (required for OpenAI provider)',
-    };
-  }
-
-  if (apiKey.trim().length === 0) {
-    return {
-      status: 'error',
-      message: 'OPENAI_API_KEY is empty',
-    };
-  }
-
-  if (!apiKey.startsWith('sk-')) {
-    return {
-      status: 'warning',
-      message: 'OPENAI_API_KEY format looks unusual (expected to start with "sk-")',
-    };
-  }
-
-  return {
-    status: 'ok',
-    message: 'OPENAI_API_KEY is set and format looks valid',
-  };
-}
-
-async function checkLocalTransformer(): Promise<HealthCheck> {
-  try {
-    // Try to import the transformers module
-    const mod = await import('@xenova/transformers');
-    if (!mod || typeof mod.pipeline !== 'function') {
-      return {
-        status: 'error',
-        message: '@xenova/transformers is installed but pipeline function not found',
-      };
-    }
-
-    // We don't actually load the model here to avoid startup delay,
-    // but we verify the package is available
-    return {
-      status: 'ok',
-      message: '@xenova/transformers is installed and available',
-    };
-  } catch (error) {
-    return {
-      status: 'error',
-      message: `@xenova/transformers is not available: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-}

src/cli/commands/health.ts

@@ -0,0 +1,58 @@
+import { handleError } from '../shared/utils';
+
+type ClercModule = typeof import('clerc');
+
+type ServeFlags = {
+  port?: number;
+  host?: string;
+};
+
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOST = 'localhost';
+
+export function createServeCommand(clerc: ClercModule) {
+  return clerc.defineCommand(
+    {
+      name: 'serve',
+      description: 'Start Forest API server (requires Bun runtime)',
+      flags: {
+        port: {
+          type: Number,
+          description: 'Port to listen on',
+          default: DEFAULT_PORT,
+        },
+        host: {
+          type: String,
+          description: 'Host to bind to',
+          default: DEFAULT_HOST,
+        },
+      },
+    },
+    async ({ flags }) => {
+      try {
+        await runServe(flags as ServeFlags);
+      } catch (error) {
+        handleError(error);
+      }
+    },
+  );
+}
+
+async function runServe(flags: ServeFlags) {
+  // Check if running under Bun
+  if (typeof Bun === 'undefined') {
+    console.error('❌ Error: forest serve requires Bun runtime');
+    console.error('');
+    console.error('To start the Forest server:');
+    console.error('  1. Install Bun: https://bun.sh');
+    console.error('  2. Run: bun run src/server/index.ts');
+    console.error('  Or use: npm run dev:server');
+    process.exit(1);
+  }
+
+  const port = flags.port ?? DEFAULT_PORT;
+
+  // Dynamically import the server (only works with Bun)
+  const { startServer } = await import('../../server/index.js');
+  await startServer({ port });
+}