@kynetic-ai/spec 0.1.2 → 0.3.0

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;
+    }
+  }
+}

package/dist/daemon/websocket/handler.ts

@@ -0,0 +1,138 @@
+/**
+ * WebSocket message handler
+ *
+ * AC coverage:
+ * - ac-26 (@api-contract): Command format
+ * - ac-27 (@api-contract): Ack response
+ * - ac-28 (@api-contract): Subscribe to topics
+ * - ac-30 (@api-contract): Malformed command error
+ */
+
+import type { ServerWebSocket } from 'bun';
+import type { WebSocketCommand, CommandAck, ConnectionData } from './types';
+import type { PubSubManager } from './pubsub';
+
+export class WebSocketHandler {
+  constructor(private pubsub: PubSubManager) {}
+
+  /**
+   * Handle incoming WebSocket command
+   * AC: @api-contract ac-26, ac-27, ac-28, ac-30
+   */
+  handleMessage(ws: ServerWebSocket<ConnectionData>, rawMessage: string | Buffer) {
+    let command: WebSocketCommand;
+
+    try {
+      // Parse command
+      const messageStr = typeof rawMessage === 'string' ? rawMessage : rawMessage.toString();
+      command = JSON.parse(messageStr);
+
+      // Validate command structure
+      if (!command.action) {
+        // AC: @api-contract ac-30
+        this.sendAck(ws, undefined, false, 'validation_error', 'Missing action field');
+        return;
+      }
+    } catch (error) {
+      // AC: @api-contract ac-30
+      this.sendAck(ws, undefined, false, 'validation_error', 'Invalid JSON');
+      return;
+    }
+
+    // Process command
+    try {
+      switch (command.action) {
+        case 'subscribe':
+          this.handleSubscribe(ws, command);
+          break;
+
+        case 'unsubscribe':
+          this.handleUnsubscribe(ws, command);
+          break;
+
+        case 'ping':
+          this.handlePing(ws, command);
+          break;
+
+        default:
+          // AC: @api-contract ac-30
+          this.sendAck(ws, command.request_id, false, 'unknown_action', `Unknown action: ${command.action}`);
+      }
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : 'Internal error';
+      this.sendAck(ws, command.request_id, false, 'error', errorMsg);
+    }
+  }
+
+  /**
+   * Handle subscribe command
+   * AC: @api-contract ac-28
+   */
+  private handleSubscribe(ws: ServerWebSocket<ConnectionData>, command: WebSocketCommand) {
+    const topics = command.payload?.topics;
+
+    if (!topics || !Array.isArray(topics) || topics.length === 0) {
+      this.sendAck(ws, command.request_id, false, 'validation_error', 'Missing or invalid topics array');
+      return;
+    }
+
+    const success = this.pubsub.subscribe(ws.data.sessionId, topics);
+
+    if (success) {
+      this.sendAck(ws, command.request_id, true);
+      console.log(`[ws] ${ws.data.sessionId} subscribed to: ${topics.join(', ')}`);
+    } else {
+      this.sendAck(ws, command.request_id, false, 'not_found', 'Session not found');
+    }
+  }
+
+  /**
+   * Handle unsubscribe command
+   */
+  private handleUnsubscribe(ws: ServerWebSocket<ConnectionData>, command: WebSocketCommand) {
+    const topics = command.payload?.topics;
+
+    if (!topics || !Array.isArray(topics) || topics.length === 0) {
+      this.sendAck(ws, command.request_id, false, 'validation_error', 'Missing or invalid topics array');
+      return;
+    }
+
+    const success = this.pubsub.unsubscribe(ws.data.sessionId, topics);
+
+    if (success) {
+      this.sendAck(ws, command.request_id, true);
+      console.log(`[ws] ${ws.data.sessionId} unsubscribed from: ${topics.join(', ')}`);
+    } else {
+      this.sendAck(ws, command.request_id, false, 'not_found', 'Session not found');
+    }
+  }
+
+  /**
+   * Handle ping command (application-level ping, not WebSocket frame)
+   */
+  private handlePing(ws: ServerWebSocket<ConnectionData>, command: WebSocketCommand) {
+    this.sendAck(ws, command.request_id, true);
+  }
+
+  /**
+   * Send ack response
+   * AC: @api-contract ac-27
+   */
+  private sendAck(
+    ws: ServerWebSocket<ConnectionData>,
+    request_id: string | undefined,
+    success: boolean,
+    error?: string,
+    details?: string
+  ) {
+    const ack: CommandAck = {
+      ack: true,
+      request_id,
+      success,
+      error,
+      details
+    };
+
+    ws.send(JSON.stringify(ack));
+  }
+}

package/dist/daemon/websocket/heartbeat.ts

@@ -0,0 +1,71 @@
+/**
+ * WebSocket heartbeat (ping/pong) management
+ *
+ * AC coverage:
+ * - ac-13 (@daemon-server): Heartbeat ping every 30s
+ * - ac-14 (@daemon-server): Timeout close after 90s without pong
+ * - ac-4 (@trait-websocket-protocol): Send ping after 30s inactivity
+ * - ac-5 (@trait-websocket-protocol): Close after 90s without pong
+ * - ac-7 (@trait-websocket-protocol): Close code 1001 for timeout
+ */
+
+import type { ServerWebSocket } from 'bun';
+import type { ConnectionData } from './types';
+
+export class HeartbeatManager {
+  private pingInterval?: NodeJS.Timeout;
+  private readonly PING_INTERVAL = 30_000; // 30 seconds
+  private readonly PONG_TIMEOUT = 90_000; // 90 seconds
+
+  /**
+   * Start heartbeat monitoring for all connections
+   * AC: @daemon-server ac-13, @trait-websocket-protocol ac-4
+   */
+  start(connections: Map<string, ServerWebSocket<ConnectionData>>) {
+    this.pingInterval = setInterval(() => {
+      const now = Date.now();
+
+      for (const [sessionId, ws] of connections) {
+        // Check if pong timeout exceeded
+        if (ws.data.lastPing && !ws.data.lastPong) {
+          const timeSincePing = now - ws.data.lastPing;
+
+          // AC: @daemon-server ac-14, @trait-websocket-protocol ac-5, ac-7
+          if (timeSincePing > this.PONG_TIMEOUT) {
+            console.warn(`[heartbeat] Closing ${sessionId} - no pong for ${timeSincePing}ms`);
+            ws.close(1001, 'Ping timeout'); // AC: @trait-websocket-protocol ac-7
+            continue;
+          }
+        }
+
+        // Send ping if no recent activity
+        const lastActivity = ws.data.lastPong ?? ws.data.lastPing ?? 0;
+        const timeSinceActivity = now - lastActivity;
+
+        if (timeSinceActivity >= this.PING_INTERVAL) {
+          ws.data.lastPing = now;
+          ws.data.lastPong = undefined; // Reset pong until received
+          ws.ping();
+          console.debug(`[heartbeat] Sent ping to ${sessionId}`);
+        }
+      }
+    }, this.PING_INTERVAL);
+  }
+
+  /**
+   * Stop heartbeat monitoring
+   */
+  stop() {
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = undefined;
+    }
+  }
+
+  /**
+   * Record pong received from connection
+   */
+  recordPong(ws: ServerWebSocket<ConnectionData>) {
+    ws.data.lastPong = Date.now();
+  }
+}

package/dist/daemon/websocket/pubsub.ts

@@ -0,0 +1,125 @@
+/**
+ * Topic-based pub/sub system for WebSocket connections
+ *
+ * AC coverage:
+ * - ac-28 (@api-contract): Subscribe to topics
+ * - ac-29 (@api-contract): Event format with seq
+ * - ac-32 (@api-contract): Backpressure handling
+ * - ac-2 (@trait-websocket-protocol): Subscribe command tracking
+ * - ac-3 (@trait-websocket-protocol): Broadcast event format
+ * - ac-6 (@trait-websocket-protocol): Backpressure pause
+ */
+
+import type { ServerWebSocket } from 'bun';
+import { ulid } from 'ulidx';
+import type { BroadcastEvent, ConnectionData } from './types';
+
+export class PubSubManager {
+  private connections = new Map<string, ServerWebSocket<ConnectionData>>();
+
+  /**
+   * Register a new WebSocket connection
+   * AC: @trait-websocket-protocol ac-1
+   */
+  addConnection(sessionId: string, ws: ServerWebSocket<ConnectionData>) {
+    this.connections.set(sessionId, ws);
+  }
+
+  /**
+   * Remove a WebSocket connection
+   */
+  removeConnection(sessionId: string) {
+    this.connections.delete(sessionId);
+  }
+
+  /**
+   * Subscribe a connection to topics
+   * AC: @api-contract ac-28, @trait-websocket-protocol ac-2
+   */
+  subscribe(sessionId: string, topics: string[]): boolean {
+    const ws = this.connections.get(sessionId);
+    if (!ws) {
+      return false;
+    }
+
+    for (const topic of topics) {
+      ws.data.topics.add(topic);
+    }
+
+    return true;
+  }
+
+  /**
+   * Unsubscribe a connection from topics
+   */
+  unsubscribe(sessionId: string, topics: string[]): boolean {
+    const ws = this.connections.get(sessionId);
+    if (!ws) {
+      return false;
+    }
+
+    for (const topic of topics) {
+      ws.data.topics.delete(topic);
+    }
+
+    return true;
+  }
+
+  /**
+   * Broadcast event to all connections subscribed to a topic
+   * AC: @api-contract ac-29, @trait-websocket-protocol ac-3, ac-6
+   * AC: @multi-directory-daemon ac-18, ac-21 - Filter by project binding
+   */
+  broadcast(topic: string, event: string, data: Record<string, unknown>, projectPath?: string) {
+    for (const [sessionId, ws] of this.connections) {
+      // AC: @multi-directory-daemon ac-18 - Only send to connections bound to same project
+      if (projectPath && ws.data.projectPath !== projectPath) {
+        continue;
+      }
+
+      // Only send to connections subscribed to this topic
+      if (!ws.data.topics.has(topic)) {
+        continue;
+      }
+
+      // AC: @trait-websocket-protocol ac-6 - Check backpressure
+      // Bun's ServerWebSocket doesn't have bufferedAmount, so we use getBufferedAmount()
+      const buffered = ws.getBufferedAmount?.() ?? 0;
+      const MAX_BUFFER = 1024 * 1024; // 1MB threshold
+
+      if (buffered > MAX_BUFFER) {
+        console.warn(`[pubsub] Skipping broadcast to ${sessionId} - backpressure (${buffered} bytes buffered)`);
+        continue;
+      }
+
+      // Increment sequence number for this connection
+      ws.data.seq++;
+
+      // AC: @api-contract ac-29, @trait-websocket-protocol ac-3
+      const message: BroadcastEvent = {
+        msg_id: ulid(),
+        seq: ws.data.seq,
+        timestamp: new Date().toISOString(),
+        topic,
+        event,
+        data
+      };
+
+      ws.send(JSON.stringify(message));
+    }
+  }
+
+  /**
+   * Get all connections (for heartbeat checks)
+   */
+  getAllConnections(): Map<string, ServerWebSocket<ConnectionData>> {
+    return this.connections;
+  }
+
+  /**
+   * Get connection count
+   */
+  getConnectionCount(): number {
+    return this.connections.size;
+  }
+}

package/dist/daemon/websocket/types.ts

@@ -0,0 +1,66 @@
+/**
+ * WebSocket Protocol Types
+ *
+ * AC coverage:
+ * - ac-25 (@api-contract): Connected event with session_id
+ * - ac-26 (@api-contract): Command format
+ * - ac-27 (@api-contract): Ack response format
+ * - ac-28 (@api-contract): Subscribe to topics
+ * - ac-29 (@api-contract): Event format with seq
+ * - ac-1 (@trait-websocket-protocol): Connection ID and connected event
+ * - ac-2 (@trait-websocket-protocol): Subscribe command tracking
+ * - ac-3 (@trait-websocket-protocol): Broadcast event format
+ */
+
+import type { ServerWebSocket } from 'bun';
+
+// AC: @api-contract ac-26
+export interface WebSocketCommand {
+  action: 'subscribe' | 'unsubscribe' | 'ping';
+  request_id?: string;
+  payload?: {
+    topics?: string[];
+  };
+}
+
+// AC: @api-contract ac-27
+export interface CommandAck {
+  ack: boolean;
+  request_id?: string;
+  success: boolean;
+  error?: string;
+  details?: string;
+}
+
+// AC: @api-contract ac-25, @trait-websocket-protocol ac-1
+export interface ConnectedEvent {
+  event: 'connected';
+  data: {
+    session_id: string;
+  };
+}
+
+// AC: @api-contract ac-29, @trait-websocket-protocol ac-3
+export interface BroadcastEvent {
+  msg_id: string;
+  seq: number;
+  timestamp: string;
+  topic: string;
+  event: string;
+  data: Record<string, unknown>;
+}
+
+// Internal connection metadata
+export interface ConnectionData {
+  sessionId: string;
+  topics: Set<string>;
+  lastPing?: number;
+  lastPong?: number;
+  seq: number; // Per-connection sequence number
+  projectPath: string; // AC: @multi-directory-daemon ac-21 - bound project path
+}
+
+export interface WebSocketContext {
+  ws: ServerWebSocket<ConnectionData>;
+  connections: Map<string, ServerWebSocket<ConnectionData>>;
+}

package/dist/export/html.d.ts

@@ -0,0 +1,19 @@
+/**
+ * HTML Export Module
+ *
+ * Generates self-contained HTML files with embedded JSON and SPA loader.
+ * AC: @gh-pages-export ac-6
+ */
+import type { KspecSnapshot } from "./types.js";
+/**
+ * Generate a self-contained HTML file with embedded JSON snapshot.
+ *
+ * The HTML includes:
+ * - Embedded JSON data in a script tag
+ * - Redirect to hosted SPA (or minimal inline viewer)
+ * - Fallback for viewing raw data
+ *
+ * AC: @gh-pages-export ac-6
+ */
+export declare function generateHtmlExport(snapshot: KspecSnapshot): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/export/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/export/html.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAmNlE"}