@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/daemon/server.ts

@@ -0,0 +1,408 @@
+/**
+ * Kspec Daemon Server
+ *
+ * Elysia.js HTTP server with WebSocket support for real-time kspec state updates.
+ * Implements localhost-only security, file watching, and graceful shutdown.
+ */
+
+import { Elysia } from 'elysia';
+import { cors } from '@elysiajs/cors';
+import { staticPlugin } from '@elysiajs/static';
+import { ulid } from 'ulidx';
+import { existsSync } from 'fs';
+import { PubSubManager } from './websocket/pubsub';
+import { HeartbeatManager } from './websocket/heartbeat';
+import { WebSocketHandler } from './websocket/handler';
+import type { ConnectionData, ConnectedEvent } from './websocket/types';
+import { PidFileManager } from './pid';
+import { projectContextMiddleware } from './middleware/project-context';
+import { createTasksRoutes } from './routes/tasks';
+import { createItemsRoutes } from './routes/items';
+import { createInboxRoutes } from './routes/inbox';
+import { createMetaRoutes } from './routes/meta';
+import { createValidationRoutes } from './routes/validation';
+import { createProjectsRoutes } from './routes/projects';
+import { createTriageRoutes } from './routes/triage';
+import { join } from 'path';
+
+export interface ServerOptions {
+  port: number;
+  isDaemon: boolean;
+  kspecDir?: string; // Path to .kspec directory (default: .kspec in cwd)
+  webUiDir?: string; // Path to web UI build directory (default: auto-detect)
+}
+
+/**
+ * Resolves the path to the web UI build directory.
+ * Tries multiple locations in order:
+ * 1. Explicit webUiDir option
+ * 2. WEB_UI_DIR environment variable
+ * 3. packages/web-ui/build in current working directory (monorepo dev)
+ * 4. web-ui/build in current working directory
+ */
+function resolveWebUiPath(webUiDir?: string): string | null {
+  // 1. Explicit option
+  if (webUiDir && existsSync(webUiDir)) {
+    return webUiDir;
+  }
+
+  // 2. Environment variable
+  const envPath = process.env.WEB_UI_DIR;
+  if (envPath && existsSync(envPath)) {
+    return envPath;
+  }
+
+  // 3. Monorepo development: packages/web-ui/build from cwd
+  // The daemon is spawned with cwd set to project root
+  const monorepoPath = join(process.cwd(), 'packages', 'web-ui', 'build');
+  if (existsSync(monorepoPath)) {
+    return monorepoPath;
+  }
+
+  // 4. Alternate location: web-ui/build in cwd
+  const altPath = join(process.cwd(), 'web-ui', 'build');
+  if (existsSync(altPath)) {
+    return altPath;
+  }
+
+  return null;
+}
+
+// WebSocket pub/sub and heartbeat managers
+let pubsubManager: PubSubManager;
+let heartbeatManager: HeartbeatManager;
+let wsHandler: WebSocketHandler;
+let projectManager: import('./project-context').ProjectContextManager | undefined;
+
+/**
+ * Middleware to enforce localhost-only connections.
+ * AC-3: Reject non-localhost connections with 403 Forbidden
+ */
+function localhostOnly() {
+  return (context: { request: Request }) => {
+    const host = context.request.headers.get('host');
+    if (!host) {
+      return new Response(JSON.stringify({
+        error: 'Forbidden',
+        message: 'This server only accepts connections from localhost'
+      }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+
+    // Extract hostname, handling IPv6 brackets
+    let hostname: string;
+    if (host.startsWith('[')) {
+      // IPv6 with brackets: [::1]:3456 -> ::1
+      const closeBracket = host.indexOf(']');
+      hostname = closeBracket > 0 ? host.substring(1, closeBracket) : host;
+    } else {
+      // IPv4 or hostname: localhost:3456 -> localhost
+      hostname = host.split(':')[0];
+    }
+
+    // Allow localhost, 127.0.0.1, and ::1
+    const isLocalhost =
+      hostname === 'localhost' ||
+      hostname === '127.0.0.1' ||
+      hostname === '::1';
+
+    if (!isLocalhost) {
+      return new Response(JSON.stringify({
+        error: 'Forbidden',
+        message: 'This server only accepts connections from localhost'
+      }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+  };
+}
+
+/**
+ * Creates and configures the Elysia server instance.
+ *
+ * AC Coverage:
+ * - ac-1: Server starts on configurable port (default 3456)
+ * - ac-2: Binds to localhost only (127.0.0.1 and ::1)
+ * - ac-3: Rejects non-localhost connections with 403
+ * - ac-15: Uses plugin pattern for middleware
+ */
+export async function createServer(options: ServerOptions) {
+  const { port, isDaemon, kspecDir = join(process.cwd(), '.kspec'), webUiDir } = options;
+
+  // Determine startup project path (project root, not .kspec/)
+  // AC: @multi-directory-daemon ac-2 - daemon uses startup directory as default project
+  const startupProjectPath = kspecDir.endsWith('.kspec')
+    ? kspecDir.slice(0, -('.kspec'.length + 1)) // Remove '/.kspec'
+    : kspecDir;
+
+  // Import ProjectContextManager (needed for WebSocket binding)
+  const { ProjectContextManager } = await import('./project-context');
+
+  // AC: @daemon-server ac-17 - Resolve web UI path for static file serving
+  const resolvedWebUiPath = resolveWebUiPath(webUiDir);
+  if (resolvedWebUiPath) {
+    console.log(`[daemon] Web UI assets found at: ${resolvedWebUiPath}`);
+  } else {
+    console.log('[daemon] Web UI assets not found - UI will not be served');
+    console.log('[daemon] Build the web UI with: cd packages/web-ui && npm run build');
+  }
+
+  // Initialize PID file manager (uses global ~/.config/kspec/)
+  const pidManager = new PidFileManager();
+
+  // AC: @multi-directory-daemon ac-9 - Write PID and port files in daemon mode
+  if (isDaemon) {
+    pidManager.writePid();
+    pidManager.writePort(port);
+    console.log(`[daemon] PID file written: ${process.pid}`);
+    console.log(`[daemon] Port file written: ${port}`);
+  }
+
+  // Initialize WebSocket managers
+  pubsubManager = new PubSubManager();
+  heartbeatManager = new HeartbeatManager();
+  wsHandler = new WebSocketHandler(pubsubManager);
+
+  // WeakMap to store project path during WebSocket upgrade
+  const wsProjectPaths = new Map<string, string>();
+
+  const app = new Elysia()
+    // AC-15: Plugin pattern for middleware
+    // AC: @api-contract ac-1 - Allow CORS from dev server on localhost:5173
+    .use(cors({
+      origin: ['http://localhost:5173', 'http://127.0.0.1:5173'], // Dev server origins
+      credentials: true,
+      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
+    }))
+
+    // AC-3: Enforce localhost-only connections
+    .onRequest(localhostOnly());
+
+  // AC: @multi-directory-daemon ac-1, ac-2, ac-3 - Project context middleware
+  const { manager: projectContextManager, middleware: projectMiddleware } = projectContextMiddleware({
+    startupProject: startupProjectPath,
+    pubsub: pubsubManager
+  });
+
+  // Store manager globally for shutdown
+  projectManager = projectContextManager;
+
+  app.use(projectMiddleware)
+
+    // AC-11: Health check endpoint
+    .get('/api/health', () => ({
+      status: 'ok',
+      uptime: process.uptime(),
+      connections: pubsubManager.getConnectionCount(),
+      version: '0.1.0'
+    }))
+
+    // AC: @api-contract ac-2 through ac-7 - Task API endpoints
+    // AC: @multi-directory-daemon ac-24 - Routes use projectContext from middleware
+    .use(createTasksRoutes({ pubsub: pubsubManager }))
+
+    // AC: @api-contract ac-8 through ac-11 - Spec Item API endpoints
+    .use(createItemsRoutes())
+
+    // AC: @api-contract ac-12 through ac-14 - Inbox API endpoints
+    .use(createInboxRoutes({ pubsub: pubsubManager }))
+
+    // AC: @api-contract ac-15 through ac-18 - Meta API endpoints
+    .use(createMetaRoutes())
+
+    // AC: @triage-daemon-api ac-1 through ac-9 - Triage API endpoints
+    .use(createTriageRoutes({ pubsub: pubsubManager }))
+
+    // AC: @api-contract ac-19 through ac-21 - Validation and search endpoints
+    .use(createValidationRoutes())
+
+    // AC: @multi-directory-daemon ac-28, ac-29, ac-30 - Projects management endpoints
+    .use(createProjectsRoutes({ projectManager: projectContextManager }))
+
+    // AC-4: WebSocket endpoint for real-time updates
+    .ws<ConnectionData>('/ws', {
+      beforeHandle({ request, store }) {
+        // AC: @multi-directory-daemon ac-21, ac-22, ac-23, ac-34 - Extract and validate project binding
+        // AC: @multi-directory-daemon ac-34 - Browser WebSocket API doesn't support custom headers,
+        // so we also accept project path as query parameter
+        const url = new URL(request.url, `http://${request.headers.get('host')}`);
+        const projectPath = request.headers.get('X-Kspec-Dir')
+                        || url.searchParams.get('project')
+                        || undefined;
+        const requestId = ulid(); // Temporary ID to correlate upgrade with open
+
+        try {
+          const manager = (store as Record<string, unknown>).projectManager as import('./project-context').ProjectContextManager | undefined;
+          if (!manager) {
+            // Fallback: project manager not initialized yet
+            wsProjectPaths.set(requestId, startupProjectPath);
+            return { wsRequestId: requestId };
+          }
+
+          let projectContext;
+          if (projectPath) {
+            // Explicit project specified
+            try {
+              projectContext = manager.getProject(projectPath);
+            } catch {
+              // AC: @multi-directory-daemon ac-4 - auto-register
+              projectContext = manager.registerProject(projectPath);
+            }
+          } else {
+            // AC: @multi-directory-daemon ac-22, ac-23 - Use default or reject
+            try {
+              projectContext = manager.getProject();
+            } catch (err: unknown) {
+              // AC: @multi-directory-daemon ac-23 - Reject when no default
+              if (err instanceof Error && err.message.includes('No default project configured')) {
+                throw new Error('No project specified');
+              }
+              throw err;
+            }
+          }
+
+          // Store resolved path for open() handler
+          wsProjectPaths.set(requestId, projectContext.path);
+          return { wsRequestId: requestId };
+        } catch (err: unknown) {
+          console.error(`[daemon] WebSocket connection rejected: ${err instanceof Error ? err.message : String(err)}`);
+          throw err;
+        }
+      },
+      open(ws) {
+        // AC: @api-contract ac-25, @trait-websocket-protocol ac-1
+        const sessionId = ulid();
+
+        // AC: @multi-directory-daemon ac-21 - Get bound project path
+        // Fallback to startup project if not found (shouldn't happen)
+        const requestId = (ws.data as ConnectionData & { wsRequestId?: string }).wsRequestId;
+        const projectPath = requestId ? wsProjectPaths.get(requestId) || startupProjectPath : startupProjectPath;
+
+        // Clean up temporary mapping
+        if (requestId) {
+          wsProjectPaths.delete(requestId);
+        }
+
+        ws.data = {
+          sessionId,
+          topics: new Set<string>(),
+          seq: 0,
+          lastPing: undefined,
+          lastPong: Date.now(),
+          projectPath // AC: @multi-directory-daemon ac-21 - immutable binding
+        };
+
+        pubsubManager.addConnection(sessionId, ws);
+        console.log(`[daemon] WebSocket client connected: ${sessionId} bound to ${projectPath} (${pubsubManager.getConnectionCount()} total)`);
+
+        // Send connected event with session_id
+        const connectedEvent: ConnectedEvent = {
+          event: 'connected',
+          data: {
+            session_id: sessionId
+          }
+        };
+        ws.send(JSON.stringify(connectedEvent));
+      },
+      message(ws, message) {
+        // AC: @api-contract ac-26, ac-27
+        wsHandler.handleMessage(ws, message);
+      },
+      pong(ws) {
+        // AC: @trait-websocket-protocol ac-5
+        heartbeatManager.recordPong(ws);
+      },
+      close(ws, code, reason) {
+        pubsubManager.removeConnection(ws.data.sessionId);
+        console.log(`[daemon] WebSocket client disconnected: ${ws.data.sessionId} (code: ${code}, reason: ${reason})`);
+      }
+    });
+
+  // AC: @daemon-server ac-17 - Serve web UI static assets
+  // Added after API routes so API routes take precedence
+  if (resolvedWebUiPath) {
+    const indexHtmlPath = join(resolvedWebUiPath, 'index.html');
+
+    // Serve static files from web UI build directory
+    app.use(await staticPlugin({
+      assets: resolvedWebUiPath,
+      prefix: '/',
+      noCache: process.env.NODE_ENV === 'development', // Disable cache in dev
+    }));
+
+    // SPA fallback routes for client-side routing
+    // These catch paths like /tasks, /items, /inbox that don't have static files
+    const spaRoutes = ['/tasks', '/tasks/*', '/items', '/items/*', '/inbox', '/observations', '/triage'];
+    for (const route of spaRoutes) {
+      app.get(route, () => Bun.file(indexHtmlPath));
+    }
+
+    console.log('[daemon] Web UI static file serving enabled');
+  }
+
+  // AC-1, AC-2: Start server on localhost only
+  // Using 'localhost' hostname allows Bun/OS to bind to both 127.0.0.1 and ::1
+  app.listen({
+    port,
+    hostname: 'localhost', // Resolves to both IPv4 and IPv6 loopback
+  });
+
+  console.log(`[daemon] Server listening on http://localhost:${port} (IPv4: 127.0.0.1, IPv6: ::1)`);
+  console.log(`[daemon] WebSocket available at ws://localhost:${port}/ws`);
+
+  // AC: @multi-directory-daemon ac-17 - Start file watcher for startup project
+  if (startupProjectPath) {
+    try {
+      await projectContextManager.startWatcher(startupProjectPath);
+      console.log(`[daemon] File watcher started for startup project: ${startupProjectPath}`);
+    } catch (error) {
+      console.error('[daemon] Failed to start file watcher for startup project:', error);
+    }
+  }
+
+  // AC: @daemon-server ac-13, ac-14 - Start heartbeat monitoring
+  heartbeatManager.start(pubsubManager.getAllConnections());
+
+  // AC-12: Graceful shutdown on SIGTERM/SIGINT
+  const shutdown = async (signal: string) => {
+    console.log(`[daemon] Received ${signal}, shutting down gracefully...`);
+
+    try {
+      // Stop heartbeat monitoring
+      heartbeatManager.stop();
+
+      // AC: @multi-directory-daemon ac-11b - Stop all file watchers
+      await projectContextManager.stopAllWatchers();
+      console.log('[daemon] All file watchers stopped');
+
+      // Close all WebSocket connections with code 1000 (clean close)
+      // AC: @trait-websocket-protocol ac-7
+      for (const [sessionId, ws] of pubsubManager.getAllConnections()) {
+        ws.close(1000, 'Server shutting down');
+      }
+
+      // Stop the server
+      await app.server?.stop();
+
+      // AC: @daemon-server ac-10 - Remove PID file on shutdown
+      if (isDaemon) {
+        pidManager.remove();
+        console.log('[daemon] PID file removed');
+      }
+
+      console.log('[daemon] Server stopped successfully');
+      process.exit(0);
+    } catch (error) {
+      console.error('[daemon] Error during shutdown:', error);
+      process.exit(1);
+    }
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  return app;
+}

package/dist/daemon/watcher.ts

@@ -0,0 +1,195 @@
+/**
+ * File watcher for .kspec directory
+ *
+ * AC Coverage:
+ * - ac-4: Watch .kspec/*.yaml files and broadcast changes
+ * - ac-5: Debounce rapid changes (500ms)
+ * - ac-6: Handle YAML parse errors gracefully
+ * - ac-7: Recovery with exponential backoff for directory access errors
+ * - ac-8: Fallback to Chokidar if Bun fs.watch fails
+ */
+
+import { watch, type FSWatcher } from 'fs';
+import { readFile } from 'fs/promises';
+import { parse as parseYaml } from 'yaml';
+import chokidar, { type FSWatcher as ChokidarWatcher } from 'chokidar';
+import { join } from 'path';
+
+export interface WatcherOptions {
+  kspecDir: string;
+  onFileChange: (file: string, content: string) => void;
+  onError: (error: Error, file?: string) => void;
+}
+
+export interface WatcherEvent {
+  type: 'change' | 'error';
+  file: string;
+  content?: string;
+  error?: string;
+}
+
+/**
+ * File watcher with debouncing and error handling
+ */
+export class KspecWatcher {
+  private watcher: FSWatcher | ChokidarWatcher | null = null;
+  private debounceTimers = new Map<string, NodeJS.Timeout>();
+  private debounceMs = 500;
+  private usingChokidar = false;
+  private retryCount = 0;
+  private maxRetries = 5;
+  private baseBackoffMs = 1000;
+
+  constructor(private options: WatcherOptions) {}
+
+  /**
+   * AC-4, AC-8: Start watching .kspec directory (with Chokidar fallback)
+   */
+  async start(): Promise<void> {
+    try {
+      // Try Bun's native fs.watch first
+      await this.startBunWatcher();
+    } catch (error) {
+      console.warn('[watcher] Bun fs.watch failed, falling back to Chokidar', error);
+      // AC-8: Fallback to Chokidar
+      this.usingChokidar = true;
+      await this.startChokidarWatcher();
+    }
+  }
+
+  /**
+   * Start Bun's native file watcher
+   */
+  private async startBunWatcher(): Promise<void> {
+    this.watcher = watch(
+      this.options.kspecDir,
+      { recursive: true },
+      (eventType, filename) => {
+        if (!filename || !filename.endsWith('.yaml')) return;
+
+        const fullPath = join(this.options.kspecDir, filename);
+        this.handleFileChange(fullPath);
+      }
+    );
+
+    console.log('[watcher] Watching .kspec directory with Bun fs.watch');
+  }
+
+  /**
+   * AC-8: Start Chokidar watcher as fallback
+   */
+  private async startChokidarWatcher(): Promise<void> {
+    this.watcher = chokidar.watch(join(this.options.kspecDir, '**/*.yaml'), {
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 100,
+        pollInterval: 50
+      }
+    });
+
+    (this.watcher as ChokidarWatcher).on('change', (path: string) => {
+      this.handleFileChange(path);
+    });
+
+    (this.watcher as ChokidarWatcher).on('error', (err: unknown) => {
+      // AC-7: Recovery with exponential backoff
+      this.handleWatcherError(err instanceof Error ? err : new Error(String(err)));
+    });
+
+    console.log('[watcher] Watching .kspec directory with Chokidar');
+  }
+
+  /**
+   * AC-5: Debounce file changes (500ms)
+   */
+  private handleFileChange(filePath: string): void {
+    // Clear existing timer for this file
+    const existingTimer = this.debounceTimers.get(filePath);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+
+    // Set new debounced timer
+    const timer = setTimeout(async () => {
+      this.debounceTimers.delete(filePath);
+      await this.processFileChange(filePath);
+    }, this.debounceMs);
+
+    this.debounceTimers.set(filePath, timer);
+  }
+
+  /**
+   * AC-4, AC-6: Process file change and broadcast to clients
+   */
+  private async processFileChange(filePath: string): Promise<void> {
+    try {
+      const content = await readFile(filePath, 'utf-8');
+
+      // AC-6: Validate YAML before broadcasting
+      try {
+        parseYaml(content);
+        this.options.onFileChange(filePath, content);
+        this.retryCount = 0; // Reset retry count on success
+      } catch (parseError) {
+        // AC-6: Log parse error and broadcast error event
+        const error = new Error(`YAML parse error in ${filePath}: ${parseError}`);
+        console.error('[watcher]', error.message);
+        this.options.onError(error, filePath);
+      }
+    } catch (error) {
+      // AC-7: Handle file read errors (directory inaccessible, etc.)
+      console.error('[watcher] Error reading file:', error);
+      this.handleWatcherError(error as Error);
+    }
+  }
+
+  /**
+   * AC-7: Handle watcher errors with exponential backoff
+   */
+  private async handleWatcherError(error: Error): Promise<void> {
+    this.options.onError(error);
+
+    if (this.retryCount >= this.maxRetries) {
+      console.error('[watcher] Max retries reached, giving up');
+      return;
+    }
+
+    this.retryCount++;
+    const backoffMs = this.baseBackoffMs * Math.pow(2, this.retryCount - 1);
+
+    console.log(`[watcher] Attempting recovery in ${backoffMs}ms (attempt ${this.retryCount}/${this.maxRetries})`);
+
+    setTimeout(async () => {
+      try {
+        await this.stop();
+        await this.start();
+        console.log('[watcher] Recovery successful');
+      } catch (retryError) {
+        console.error('[watcher] Recovery failed:', retryError);
+        // Will retry again if under max retries
+        this.handleWatcherError(retryError as Error);
+      }
+    }, backoffMs);
+  }
+
+  /**
+   * Stop watching
+   */
+  async stop(): Promise<void> {
+    // Clear all debounce timers
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+
+    // Close watcher
+    if (this.watcher) {
+      if (this.usingChokidar) {
+        await (this.watcher as ChokidarWatcher).close();
+      } else {
+        (this.watcher as FSWatcher).close();
+      }
+      this.watcher = null;
+    }
+  }
+}