@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/daemon/middleware/project-context.ts

@@ -0,0 +1,126 @@
+/**
+ * Project Context Middleware for Multi-Directory Daemon
+ *
+ * Extracts X-Kspec-Dir header and attaches ProjectContext to request state.
+ * Implements path validation and automatic project registration.
+ *
+ * AC: @multi-directory-daemon ac-1, ac-2, ac-3, ac-4, ac-5, ac-6, ac-7, ac-8, ac-8b, ac-8c, ac-20b
+ */
+
+import type { Elysia } from 'elysia';
+import { ProjectContextManager, type ProjectContext } from '../project-context';
+import type { PubSubManager } from '../websocket/pubsub';
+
+export interface ProjectContextMiddlewareOptions {
+  /**
+   * Optional startup project path (daemon's cwd at boot if it has .kspec/)
+   */
+  startupProject?: string;
+  /**
+   * PubSubManager for broadcasting file changes
+   */
+  pubsub?: PubSubManager;
+}
+
+/**
+ * Creates project context middleware plugin for Elysia.
+ *
+ * Extracts X-Kspec-Dir header, validates path, registers/retrieves project,
+ * and attaches ProjectContext to request state.
+ *
+ * Returns both the manager (for external access) and the middleware function.
+ */
+export function projectContextMiddleware(options: ProjectContextMiddlewareOptions = {}) {
+  const manager = new ProjectContextManager(options.startupProject, options.pubsub);
+
+  // Register startup project if provided
+  // Note: Watcher will be started later after full initialization
+  if (options.startupProject) {
+    try {
+      manager.registerProject(options.startupProject, true);
+    } catch (error) {
+      console.warn(`[daemon] Failed to register startup project: ${error}`);
+    }
+  }
+
+  const middleware = (app: Elysia) =>
+    app
+      // Store manager in app state for WebSocket access
+      .state('projectManager', manager)
+      .derive(async ({ request, set }) => {
+        try {
+          // AC: @multi-directory-daemon ac-1 - Extract X-Kspec-Dir header
+          const projectPath = request.headers.get('X-Kspec-Dir') || undefined;
+
+          let projectContext: ProjectContext;
+
+          if (projectPath) {
+            // AC: @multi-directory-daemon ac-1, ac-4, ac-5, ac-6, ac-7, ac-8, ac-8b, ac-8c
+            // Try to get existing or register new project
+            try {
+              projectContext = manager.getProject(projectPath);
+            } catch (err) {
+              // Not registered - try to register (ac-4: auto-register)
+              projectContext = manager.registerProject(projectPath);
+              // Start watcher asynchronously (don't block request)
+              void manager.startWatcher(projectPath).catch((watcherError) => {
+                console.error(`[daemon] Failed to start watcher for ${projectPath}:`, watcherError);
+              });
+            }
+          } else {
+            // AC: @multi-directory-daemon ac-2, ac-3, ac-20b
+            // No header - use default project
+            projectContext = manager.getProject();
+          }
+
+          return { projectContext };
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+
+          // AC: @multi-directory-daemon ac-3, ac-20b
+          if (
+            message.includes('No default project configured') ||
+            message.includes('Default project no longer valid')
+          ) {
+            set.status = 400;
+            return { error: message };
+          }
+
+          // AC: @multi-directory-daemon ac-5
+          if (message.includes('Invalid kspec project')) {
+            set.status = 400;
+            return { error: message };
+          }
+
+          // AC: @multi-directory-daemon ac-6
+          if (message.includes('Path must be absolute')) {
+            set.status = 400;
+            return { error: 'Path must be absolute' };
+          }
+
+          // AC: @multi-directory-daemon ac-7
+          if (message.includes('Path must not contain parent traversal')) {
+            set.status = 400;
+            return { error: 'Path must not contain parent traversal' };
+          }
+
+          // AC: @multi-directory-daemon ac-8b - permission denied
+          if (message.includes('Permission denied')) {
+            set.status = 403;
+            return { error: message };
+          }
+
+          // AC: @multi-directory-daemon ac-19 - OS resource limits
+          if (message.includes('Unable to watch project - resource limit reached')) {
+            set.status = 503;
+            return { error: message };
+          }
+
+          // Other errors
+          set.status = 500;
+          return { error: 'Internal server error' };
+        }
+      });
+
+  return { manager, middleware };
+}

package/dist/daemon/pid.ts

@@ -0,0 +1,179 @@
+/**
+ * PID File Management
+ *
+ * Manages daemon process PID and port files for lifecycle control.
+ * Uses global config directory (~/.config/kspec/) instead of per-project .kspec/
+ * AC: @multi-directory-daemon ac-9, ac-9b, ac-9c, ac-10, ac-11, ac-13
+ */
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, openSync, closeSync, constants } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export class PidFileManager {
+  private configDir: string;
+  private pidFilePath: string;
+  private portFilePath: string;
+
+  constructor(configDir: string = join(homedir(), '.config', 'kspec')) {
+    this.configDir = configDir;
+    this.pidFilePath = join(configDir, 'daemon.pid');
+    this.portFilePath = join(configDir, 'daemon.port');
+  }
+
+  /**
+   * AC: @multi-directory-daemon ac-9b
+   * Creates config directory with mode 0755 if it doesn't exist
+   */
+  private ensureConfigDir(): void {
+    if (!existsSync(this.configDir)) {
+      mkdirSync(this.configDir, { recursive: true, mode: 0o755 });
+    }
+  }
+
+  /**
+   * AC: @multi-directory-daemon ac-9, ac-10b
+   * Writes current process PID to ~/.config/kspec/daemon.pid
+   * Creates parent directory if it doesn't exist.
+   * Uses exclusive file creation flag to prevent concurrent daemon starts.
+   */
+  writePid(): void {
+    this.ensureConfigDir();
+
+    // AC: @multi-directory-daemon ac-10b
+    // Use O_CREAT | O_EXCL flags for atomic file creation
+    // This prevents race conditions between concurrent daemon starts
+    try {
+      const fd = openSync(this.pidFilePath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o644);
+      try {
+        writeFileSync(fd, process.pid.toString(), 'utf-8');
+      } finally {
+        closeSync(fd);
+      }
+    } catch (err: unknown) {
+      if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'EEXIST') {
+        // File already exists - check if daemon is actually running
+        if (this.isDaemonRunning()) {
+          throw new Error('Daemon already running');
+        }
+        // Stale PID file - remove it and retry
+        this.remove();
+        const fd = openSync(this.pidFilePath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o644);
+        try {
+          writeFileSync(fd, process.pid.toString(), 'utf-8');
+        } finally {
+          closeSync(fd);
+        }
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * AC: @multi-directory-daemon ac-9
+   * Writes daemon port to ~/.config/kspec/daemon.port
+   * Creates parent directory if it doesn't exist.
+   */
+  writePort(port: number): void {
+    this.ensureConfigDir();
+    writeFileSync(this.portFilePath, port.toString(), 'utf-8');
+  }
+
+  /**
+   * Reads PID from ~/.config/kspec/daemon.pid
+   * Returns null if file doesn't exist or is invalid
+   */
+  readPid(): number | null {
+    if (!existsSync(this.pidFilePath)) {
+      return null;
+    }
+
+    try {
+      const content = readFileSync(this.pidFilePath, 'utf-8').trim();
+      const pid = parseInt(content, 10);
+      return isNaN(pid) ? null : pid;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * AC: @multi-directory-daemon ac-9c, ac-13
+   * Reads port from ~/.config/kspec/daemon.port
+   * Throws error if file doesn't exist or contains invalid port
+   */
+  readPort(): number {
+    if (!existsSync(this.portFilePath)) {
+      throw new Error('Invalid daemon port file');
+    }
+
+    try {
+      const content = readFileSync(this.portFilePath, 'utf-8').trim();
+      const port = parseInt(content, 10);
+
+      // AC: @multi-directory-daemon ac-9c - validate port content
+      if (isNaN(port) || port < 1 || port > 65535) {
+        throw new Error('Invalid daemon port file');
+      }
+
+      return port;
+    } catch (err) {
+      throw new Error('Invalid daemon port file');
+    }
+  }
+
+  /**
+   * AC: @multi-directory-daemon ac-11
+   * Removes both PID and port files during graceful shutdown
+   */
+  remove(): void {
+    if (existsSync(this.pidFilePath)) {
+      unlinkSync(this.pidFilePath);
+    }
+    if (existsSync(this.portFilePath)) {
+      unlinkSync(this.portFilePath);
+    }
+  }
+
+  /**
+   * Checks if a process with given PID is running
+   */
+  isProcessRunning(pid: number): boolean {
+    try {
+      // Sending signal 0 checks if process exists without actually sending a signal
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * AC: @multi-directory-daemon ac-10
+   * Checks if daemon is currently running based on PID file
+   */
+  isDaemonRunning(): boolean {
+    const pid = this.readPid();
+    if (pid === null) {
+      return false;
+    }
+    return this.isProcessRunning(pid);
+  }
+
+  /**
+   * Backwards compatibility: read() method maps to readPid()
+   * @deprecated Use readPid() instead
+   */
+  read(): number | null {
+    return this.readPid();
+  }
+
+  /**
+   * Backwards compatibility: write() method maps to writePid()
+   * @deprecated Use writePid() instead
+   */
+  write(): void {
+    this.writePid();
+  }
+}

package/dist/daemon/project-context.ts

@@ -0,0 +1,343 @@
+/**
+ * ProjectContextManager - Multi-project daemon support
+ *
+ * Manages project registration, caching, path validation, and context management
+ * for multi-directory daemon architecture.
+ *
+ * AC: @multi-directory-daemon ac-1 through ac-20b
+ */
+
+import { existsSync } from 'fs';
+import { isAbsolute, join, normalize, relative } from 'path';
+import { KspecWatcher } from './watcher';
+import type { PubSubManager } from './websocket/pubsub';
+
+export interface ProjectContext {
+  path: string;
+  registeredAt: Date;
+  watcherActive: boolean;
+}
+
+/**
+ * Manages multiple kspec project contexts for the daemon server.
+ *
+ * Key responsibilities:
+ * - Project registration and caching
+ * - Path validation and normalization
+ * - Default project handling
+ * - Project lifecycle management
+ * - Per-project file watcher management
+ */
+export class ProjectContextManager {
+  private projects: Map<string, ProjectContext> = new Map();
+  private watchers: Map<string, KspecWatcher> = new Map();
+  private defaultProjectPath: string | null = null;
+  private pubsub: PubSubManager | null = null;
+
+  constructor(defaultProjectPath?: string, pubsub?: PubSubManager) {
+    if (defaultProjectPath) {
+      this.defaultProjectPath = defaultProjectPath;
+    }
+    if (pubsub) {
+      this.pubsub = pubsub;
+    }
+  }
+
+  /**
+   * Set the PubSubManager for broadcasting file changes.
+   * Must be called before starting watchers.
+   *
+   * @param pubsub - PubSubManager instance
+   */
+  setPubSub(pubsub: PubSubManager): void {
+    this.pubsub = pubsub;
+  }
+
+  /**
+   * Start a file watcher for a project.
+   *
+   * AC: @multi-directory-daemon ac-17, ac-19
+   *
+   * @param projectPath - Absolute path to project root
+   * @throws Error if watcher creation fails (e.g., OS resource limits)
+   */
+  async startWatcher(projectPath: string): Promise<void> {
+    const normalizedPath = this.normalizePath(projectPath);
+
+    // AC: @multi-directory-daemon ac-16 - Don't create duplicate watchers
+    if (this.watchers.has(normalizedPath)) {
+      return; // Watcher already running
+    }
+
+    const kspecDir = join(normalizedPath, '.kspec');
+
+    try {
+      // AC: @multi-directory-daemon ac-17, ac-18 - Create watcher with project-scoped broadcasts
+      const watcher = new KspecWatcher({
+        kspecDir,
+        onFileChange: (file, content) => {
+          // AC: @multi-directory-daemon ac-17 - File changes trigger events scoped to project
+          if (this.pubsub) {
+            const relativePath = relative(kspecDir, file);
+            this.pubsub.broadcast('files:updates', 'file_changed', {
+              ref: relativePath,
+              action: 'modified'
+            }, normalizedPath);
+          }
+        },
+        onError: (error, file) => {
+          // Broadcast error event scoped to project
+          if (this.pubsub) {
+            const relativePath = file ? relative(kspecDir, file) : undefined;
+            this.pubsub.broadcast('files:errors', 'file_error', {
+              ref: relativePath,
+              error: error.message
+            }, normalizedPath);
+          }
+        }
+      });
+
+      await watcher.start();
+      this.watchers.set(normalizedPath, watcher);
+
+      // Update context
+      const context = this.projects.get(normalizedPath);
+      if (context) {
+        context.watcherActive = true;
+      }
+    } catch (error: unknown) {
+      // AC: @multi-directory-daemon ac-19 - Handle OS limits (EMFILE/ENFILE)
+      const code = error instanceof Error && 'code' in error ? (error as NodeJS.ErrnoException).code : undefined;
+      if (code === 'EMFILE' || code === 'ENFILE') {
+        throw new Error('Unable to watch project - resource limit reached');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Stop a file watcher for a project.
+   *
+   * AC: @multi-directory-daemon ac-20, ac-11b
+   *
+   * @param projectPath - Absolute path to project root
+   */
+  async stopWatcher(projectPath: string): Promise<void> {
+    const normalizedPath = this.normalizePath(projectPath);
+    const watcher = this.watchers.get(normalizedPath);
+
+    if (watcher) {
+      await watcher.stop();
+      this.watchers.delete(normalizedPath);
+
+      // Update context
+      const context = this.projects.get(normalizedPath);
+      if (context) {
+        context.watcherActive = false;
+      }
+    }
+  }
+
+  /**
+   * Stop all file watchers.
+   *
+   * AC: @multi-directory-daemon ac-11b - Shutdown stops all watchers
+   */
+  async stopAllWatchers(): Promise<void> {
+    const stopPromises = Array.from(this.watchers.keys()).map(path =>
+      this.stopWatcher(path)
+    );
+    await Promise.all(stopPromises);
+  }
+
+  /**
+   * Register a project for multi-directory daemon support.
+   *
+   * AC: @multi-directory-daemon ac-4, ac-5, ac-6, ac-7, ac-8, ac-8c
+   *
+   * Note: This method is synchronous. Start watchers separately via startWatcher().
+   *
+   * @param projectPath - Absolute path to project root directory
+   * @param isDefault - Whether this project should be the default
+   * @returns Registered project context
+   * @throws Error if path validation fails or .kspec/ not found
+   */
+  registerProject(projectPath: string, isDefault = false): ProjectContext {
+    // AC: @multi-directory-daemon ac-6 - reject relative paths
+    if (!this.isAbsolutePath(projectPath)) {
+      throw new Error('Path must be absolute');
+    }
+
+    // AC: @multi-directory-daemon ac-7 - reject parent traversal
+    if (projectPath.includes('..')) {
+      throw new Error('Path must not contain parent traversal');
+    }
+
+    // AC: @multi-directory-daemon ac-8 - normalize path (but don't resolve symlinks)
+    const normalizedPath = this.normalizePath(projectPath);
+
+    // AC: @multi-directory-daemon ac-5 - validate .kspec/ exists
+    const kspecDir = join(normalizedPath, '.kspec');
+    if (!existsSync(kspecDir)) {
+      throw new Error(`Invalid kspec project - .kspec/ not found at ${normalizedPath}`);
+    }
+
+    // AC: @multi-directory-daemon ac-16 - check if already registered (avoid duplicates)
+    if (this.projects.has(normalizedPath)) {
+      const existing = this.projects.get(normalizedPath)!;
+      if (isDefault) {
+        this.defaultProjectPath = normalizedPath;
+      }
+      return existing;
+    }
+
+    // AC: @multi-directory-daemon ac-4 - auto-register and cache
+    const context: ProjectContext = {
+      path: normalizedPath,
+      registeredAt: new Date(),
+      watcherActive: false, // Set to true when watcher is started
+    };
+
+    this.projects.set(normalizedPath, context);
+
+    if (isDefault) {
+      this.defaultProjectPath = normalizedPath;
+    }
+
+    return context;
+  }
+
+  /**
+   * Get a project by path, or use default project if no path provided.
+   *
+   * AC: @multi-directory-daemon ac-1, ac-2, ac-3, ac-20b
+   *
+   * @param projectPath - Optional absolute path to project
+   * @returns Project context
+   * @throws Error if project not registered, no default, or default invalid
+   */
+  getProject(projectPath?: string): ProjectContext {
+    // AC: @multi-directory-daemon ac-1 - use provided path
+    if (projectPath) {
+      const normalizedPath = this.normalizePath(projectPath);
+      const context = this.projects.get(normalizedPath);
+      if (!context) {
+        throw new Error(`Project not registered: ${normalizedPath}`);
+      }
+      return context;
+    }
+
+    // AC: @multi-directory-daemon ac-2, ac-3 - use default or error
+    if (!this.defaultProjectPath) {
+      throw new Error('No default project configured. Specify X-Kspec-Dir header.');
+    }
+
+    // AC: @multi-directory-daemon ac-20b - check if default project still valid
+    const kspecDir = join(this.defaultProjectPath, '.kspec');
+    if (!existsSync(kspecDir)) {
+      throw new Error('Default project no longer valid. Specify X-Kspec-Dir header.');
+    }
+
+    const context = this.projects.get(this.defaultProjectPath);
+    if (!context) {
+      throw new Error('Default project not registered');
+    }
+
+    return context;
+  }
+
+  /**
+   * Set the default project explicitly.
+   *
+   * AC: @multi-directory-daemon ac-2
+   *
+   * @param projectPath - Absolute path to project
+   * @throws Error if project not registered
+   */
+  setDefaultProject(projectPath: string): void {
+    const normalizedPath = this.normalizePath(projectPath);
+    if (!this.projects.has(normalizedPath)) {
+      throw new Error('Project must be registered before setting as default');
+    }
+    this.defaultProjectPath = normalizedPath;
+  }
+
+  /**
+   * Check if a project is registered.
+   *
+   * @param projectPath - Absolute path to project
+   * @returns True if project is registered
+   */
+  hasProject(projectPath: string): boolean {
+    const normalizedPath = this.normalizePath(projectPath);
+    return this.projects.has(normalizedPath);
+  }
+
+  /**
+   * Unregister a project and stop its watcher.
+   *
+   * AC: @multi-directory-daemon ac-20
+   *
+   * @param projectPath - Absolute path to project
+   */
+  unregisterProject(projectPath: string): void {
+    const normalizedPath = this.normalizePath(projectPath);
+
+    // AC: @multi-directory-daemon ac-20 - Stop watcher when unregistering (async, fire-and-forget)
+    void this.stopWatcher(normalizedPath);
+
+    this.projects.delete(normalizedPath);
+
+    if (this.defaultProjectPath === normalizedPath) {
+      this.defaultProjectPath = null;
+    }
+  }
+
+  /**
+   * List all registered projects.
+   *
+   * AC: @multi-directory-daemon ac-14, ac-15
+   *
+   * @returns Array of registered project contexts
+   */
+  listProjects(): ProjectContext[] {
+    return Array.from(this.projects.values());
+  }
+
+  /**
+   * Normalize path without resolving symlinks.
+   *
+   * AC: @multi-directory-daemon ac-8, ac-8c
+   *
+   * Normalizes the path by:
+   * - Resolving "." segments
+   * - Removing trailing slashes
+   * - Normalizing multiple slashes
+   * - NOT resolving symlinks (symlinked paths treated as separate projects)
+   *
+   * @param projectPath - Path to normalize
+   * @returns Normalized path
+   */
+  private normalizePath(projectPath: string): string {
+    // Remove trailing slashes and resolve "." segments
+    // But do NOT resolve symlinks (no realpath/fs.realpathSync)
+    let normalized = normalize(projectPath);
+
+    // Remove trailing slash (normalize doesn't always do this)
+    if (normalized !== '/' && normalized.endsWith('/')) {
+      normalized = normalized.slice(0, -1);
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Check if path is absolute.
+   *
+   * @param projectPath - Path to check
+   * @returns True if path is absolute
+   */
+  private isAbsolutePath(projectPath: string): boolean {
+    return isAbsolute(projectPath);
+  }
+}