octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-research/src/server-init.ts

@@ -0,0 +1,363 @@
+/**
+ * Server Init Script
+ *
+ * Handles server initialization with mutex lock:
+ * 1. Acquires atomic lock to prevent concurrent startups
+ * 2. Checks if server is running (health check)
+ * 3. Starts server if not running
+ * 4. Waits for status "ok"
+ * 5. Outputs "ok" on success
+ *
+ * Improvements:
+ * - Atomic lock using O_CREAT | O_EXCL | O_WRONLY (no race condition)
+ * - Exponential backoff retry for lock acquisition
+ * - Environment variable configuration
+ * - Spawn error handling
+ * - Better health check error logging
+ *
+ * Usage: npm run server-init
+ * Exit codes: 0 = success, 1 = error
+ */
+
+import { spawn } from 'child_process';
+import {
+  existsSync,
+  mkdirSync,
+  unlinkSync,
+  readFileSync,
+  constants,
+  openSync,
+  writeSync,
+  closeSync,
+  statSync,
+} from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// =============================================================================
+// Configuration (Environment Variables)
+// =============================================================================
+
+const PORT = parseInt(process.env.OCTOCODE_PORT || '1987', 10);
+const HEALTH_URL = `http://localhost:${PORT}/health`;
+const LOCK_DIR = join(homedir(), '.octocode');
+const LOCK_FILE = join(LOCK_DIR, 'server-init.lock');
+const LOCK_TIMEOUT_MS = parseInt(process.env.OCTOCODE_LOCK_TIMEOUT || '60000', 10);
+const MAX_WAIT_MS = parseInt(process.env.OCTOCODE_INIT_TIMEOUT || '30000', 10);
+const POLL_INTERVAL_MS = parseInt(process.env.OCTOCODE_POLL_INTERVAL || '500', 10);
+
+interface LockData {
+  pid: number;
+  timestamp: number;
+}
+
+interface HealthResponse {
+  status: 'ok' | 'initializing' | string;
+}
+
+// =============================================================================
+// Atomic Mutex Lock (Based on Snyk pattern - O_EXCL for atomic creation)
+// =============================================================================
+
+function ensureLockDir(): void {
+  if (!existsSync(LOCK_DIR)) {
+    mkdirSync(LOCK_DIR, { recursive: true });
+  }
+}
+
+function isLockStale(lockPath: string): boolean {
+  if (!existsSync(lockPath)) return true;
+
+  try {
+    const content = readFileSync(lockPath, 'utf-8');
+    if (content && content.trim().length > 0) {
+      const data: LockData = JSON.parse(content);
+
+      // Check timestamp
+      if (Date.now() - data.timestamp > LOCK_TIMEOUT_MS) {
+        return true;
+      }
+
+      // Check if process exists
+      try {
+        process.kill(data.pid, 0);
+        return false; // Process exists, lock is valid
+      } catch {
+        return true; // Process doesn't exist
+      }
+    }
+  } catch {
+    // Fall back to mtime check
+  }
+
+  // Fallback: check file modification time
+  try {
+    const stats = statSync(lockPath);
+    return Date.now() - stats.mtimeMs > LOCK_TIMEOUT_MS;
+  } catch {
+    return true;
+  }
+}
+
+function safeUnlink(filePath: string): void {
+  try {
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+async function acquireLock(): Promise<boolean> {
+  ensureLockDir();
+
+  // Only retry for stale lock removal race condition, not for valid locks
+  const STALE_RETRY_LIMIT = 3;
+
+  for (let attempt = 0; attempt < STALE_RETRY_LIMIT; attempt++) {
+    try {
+      // Atomic create - fails with EEXIST if file exists
+      const fd = openSync(LOCK_FILE, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+
+      const lockData: LockData = {
+        pid: process.pid,
+        timestamp: Date.now(),
+      };
+
+      writeSync(fd, JSON.stringify(lockData));
+      closeSync(fd);
+      return true;
+    } catch (err: unknown) {
+      const nodeErr = err as NodeJS.ErrnoException;
+
+      if (nodeErr.code === 'EEXIST') {
+        // Lock exists - check if stale
+        if (isLockStale(LOCK_FILE)) {
+          safeUnlink(LOCK_FILE);
+          // Small delay to avoid tight loop on stale lock race
+          await new Promise((r) => setTimeout(r, 50));
+          continue; // Retry after removing stale lock
+        }
+
+        // Lock is VALID - another process is starting server
+        // Don't retry, let caller fall back to waiting for server
+        return false;
+      } else {
+        // Unexpected error
+        console.error(`[server-init] Lock error: ${nodeErr.message}`);
+        return false;
+      }
+    }
+  }
+
+  return false; // Failed after stale lock retries
+}
+
+function releaseLock(): void {
+  try {
+    if (existsSync(LOCK_FILE)) {
+      const data: LockData = JSON.parse(readFileSync(LOCK_FILE, 'utf-8'));
+      // Only release if we own the lock
+      if (data.pid === process.pid) {
+        unlinkSync(LOCK_FILE);
+      }
+    }
+  } catch {
+    // Ignore errors during cleanup
+  }
+}
+
+// =============================================================================
+// Health Check (Improved error handling)
+// =============================================================================
+
+async function checkHealth(): Promise<HealthResponse | null> {
+  try {
+    const response = await fetch(HEALTH_URL, {
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return (await response.json()) as HealthResponse;
+  } catch (error: unknown) {
+    // Only log unexpected errors, not connection refused (expected when server down)
+    if (error instanceof Error && !error.message.includes('ECONNREFUSED')) {
+      console.error(`[server-init] Health check error: ${error.message}`);
+    }
+    return null;
+  }
+}
+
+// =============================================================================
+// Server Start (Improved with error handling)
+// =============================================================================
+
+function startServer(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const scriptDir = new URL('.', import.meta.url).pathname;
+    const serverScript = join(scriptDir, 'server.js');
+
+    const child = spawn('node', [serverScript], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: scriptDir,
+    });
+
+    // Handle spawn errors (e.g., ENOENT if node not found)
+    child.on('error', (err) => {
+      console.error(`[server-init] Failed to start server: ${err.message}`);
+      reject(err);
+    });
+
+    // Give a small window for immediate spawn errors
+    setTimeout(() => {
+      child.unref();
+      console.log(`[server-init] Started server process (pid: ${child.pid})`);
+      resolve();
+    }, 100);
+  });
+}
+
+// =============================================================================
+// Wait for Ready (with exponential backoff)
+// =============================================================================
+
+async function waitForReady(): Promise<boolean> {
+  const startTime = Date.now();
+  let pollInterval = POLL_INTERVAL_MS;
+
+  while (Date.now() - startTime < MAX_WAIT_MS) {
+    const health = await checkHealth();
+
+    if (health?.status === 'ok') {
+      return true;
+    }
+
+    if (health?.status === 'initializing') {
+      console.log('[server-init] Server initializing...');
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    // Gradual backoff up to 2s
+    pollInterval = Math.min(pollInterval * 1.5, 2000);
+  }
+
+  return false;
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main(): Promise<void> {
+  // ==========================================================================
+  // FAST PATH: Check if server is already running (no lock needed)
+  // ==========================================================================
+  const initialHealth = await checkHealth();
+
+  if (initialHealth?.status === 'ok') {
+    // Server is running - immediate success, no lock needed
+    console.log('ok');
+    process.exit(0);
+  }
+
+  if (initialHealth?.status === 'initializing') {
+    // Server is starting - just wait for it, no lock needed
+    console.log('[server-init] Server is initializing, waiting...');
+    const ready = await waitForReady();
+    if (ready) {
+      console.log('ok');
+      process.exit(0);
+    } else {
+      console.error('[server-init] ERROR: Server stuck in initializing state');
+      process.exit(1);
+    }
+  }
+
+  // ==========================================================================
+  // SLOW PATH: Server not running - need lock to start it
+  // ==========================================================================
+  const lockAcquired = await acquireLock();
+
+  if (!lockAcquired) {
+    // Another process is starting the server - wait for it
+    console.log('[server-init] Another process is starting server, waiting...');
+    const ready = await waitForReady();
+    if (ready) {
+      console.log('ok');
+      process.exit(0);
+    } else {
+      console.error('[server-init] ERROR: Timeout waiting for server');
+      process.exit(1);
+    }
+  }
+
+  try {
+    // Double-check health after acquiring lock (another process may have started it)
+    const health = await checkHealth();
+
+    if (health?.status === 'ok') {
+      console.log('ok');
+      releaseLock();
+      process.exit(0);
+    }
+
+    if (health?.status === 'initializing') {
+      console.log('[server-init] Server is initializing, waiting...');
+      const ready = await waitForReady();
+      if (ready) {
+        console.log('ok');
+        releaseLock();
+        process.exit(0);
+      } else {
+        console.error('[server-init] ERROR: Server stuck in initializing state');
+        releaseLock();
+        process.exit(1);
+      }
+    }
+
+    // Server not running - start it
+    console.log('[server-init] Server not running, starting...');
+
+    try {
+      await startServer();
+    } catch {
+      console.error('[server-init] ERROR: Failed to spawn server process');
+      releaseLock();
+      process.exit(1);
+    }
+
+    // Wait for server to be ready
+    const ready = await waitForReady();
+    if (ready) {
+      console.log('ok');
+      releaseLock();
+      process.exit(0);
+    } else {
+      console.error('[server-init] ERROR: Server failed to start within timeout');
+      releaseLock();
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('[server-init] ERROR:', error instanceof Error ? error.message : error);
+    releaseLock();
+    process.exit(1);
+  }
+}
+
+// Cleanup on exit
+process.on('SIGINT', () => {
+  releaseLock();
+  process.exit(130);
+});
+
+process.on('SIGTERM', () => {
+  releaseLock();
+  process.exit(143);
+});
+
+main();

package/skills/octocode-research/src/server.ts

@@ -0,0 +1,285 @@
+import express, { type Express, type Request, type Response, type NextFunction } from 'express';
+import type { Server } from 'http';
+import { toolsRoutes } from './routes/tools.js';
+import { promptsRoutes } from './routes/prompts.js';
+import { errorHandler } from './middleware/errorHandler.js';
+import { requestLogger } from './middleware/logger.js';
+import { initializeProviders, initializeSession, logSessionInit } from './index.js';
+import { initializeMcpContent, isMcpInitialized } from './mcpCache.js';
+import { getLogsPath, initializeLogger } from './utils/logger.js';
+import { getAllCircuitStates, clearAllCircuits, stopCircuitCleanup } from './utils/circuitBreaker.js';
+import { agentLog, successLog, errorLog, dimLog, warnLog } from './utils/colors.js';
+import { fireAndForgetWithTimeout } from './utils/asyncTimeout.js';
+import { errorQueue } from './utils/errorQueue.js';
+
+const HOST = process.env.OCTOCODE_RESEARCH_HOST || 'localhost';
+
+const getPort = (raw?: string): number => {
+  const DEFAULT_PORT = 1987;
+  if (!raw) return DEFAULT_PORT;
+
+  const port = Number(raw);
+
+  // Strictly allow only the non-privileged, user-registered range
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error(
+      `Invalid OCTOCODE_RESEARCH_PORT: "${raw}". ` +
+      `Please provide an integer between 1024 and 65535.`
+    );
+  }
+
+  return port;
+};
+
+const PORT = getPort(process.env.OCTOCODE_RESEARCH_PORT);
+
+const MAX_IDLE_TIME_MS = 30 * 60 * 1000;  // 30 minutes idle before restart
+const IDLE_CHECK_INTERVAL_MS = 120 * 1000; // Check every 2 minute
+
+let server: Server | null = null;
+let lastRequestTime: number = Date.now();
+let idleCheckInterval: NodeJS.Timeout | null = null;
+let isShuttingDown = false;
+
+/**
+ * Check if server has been idle and should restart
+ */
+function checkIdleRestart(): void {
+  const idleTime = Date.now() - lastRequestTime;
+  const idleSeconds = Math.floor(idleTime / 1000);
+  
+  if (idleTime > MAX_IDLE_TIME_MS) {
+    console.log(warnLog(`⚠️ Server idle for ${idleSeconds}s (>${MAX_IDLE_TIME_MS / 1000}s). Initiating restart...`));
+    gracefulShutdown('IDLE_TIMEOUT');
+  } else if (idleTime > MAX_IDLE_TIME_MS / 2) {
+    // Log warning at 50% threshold (30 minutes)
+    console.log(dimLog(`⏰ Idle: ${idleSeconds}s / ${MAX_IDLE_TIME_MS / 1000}s`));
+  }
+}
+
+/**
+ * Start periodic idle checking
+ */
+function startIdleCheck(): void {
+  if (idleCheckInterval) return;
+  
+  idleCheckInterval = setInterval(checkIdleRestart, IDLE_CHECK_INTERVAL_MS);
+  
+  // Unref so it doesn't prevent process exit
+  idleCheckInterval.unref();
+  
+  console.log(dimLog(`⏱️ Idle check started (${IDLE_CHECK_INTERVAL_MS / 1000}s interval, ${MAX_IDLE_TIME_MS / 1000}s threshold)`));
+}
+
+/**
+ * Stop idle checking
+ */
+function stopIdleCheck(): void {
+  if (idleCheckInterval) {
+    clearInterval(idleCheckInterval);
+    idleCheckInterval = null;
+    console.log(successLog('✅ Idle check interval stopped'));
+  }
+}
+
+export async function createServer(): Promise<Express> {
+  // Initialize logger first (sync for startup, async after)
+  initializeLogger();
+  
+  // Initialize session for telemetry tracking
+  initializeSession();
+
+  const app = express();
+  app.use(express.json());
+  
+  // Track activity for idle restart
+  app.use((_req: Request, _res: Response, next: NextFunction) => {
+    lastRequestTime = Date.now();
+    next();
+  });
+
+  app.use(requestLogger);
+  
+  app.get('/health', (_req: Request, res: Response) => {
+    const memoryUsage = process.memoryUsage();
+    const recentErrors = errorQueue.getRecent(5);
+    const initialized = isMcpInitialized();
+    const idleTimeMs = Date.now() - lastRequestTime;
+
+    res.json({
+      status: initialized ? 'ok' : 'initializing',
+      host: HOST,
+      port: PORT,
+      version: '2.2.0',
+      uptime: Math.floor(process.uptime()),
+      processManager: 'pm2',
+      // Idle tracking info
+      idle: {
+        currentMs: idleTimeMs,
+        thresholdMs: MAX_IDLE_TIME_MS,
+        checkIntervalMs: IDLE_CHECK_INTERVAL_MS,
+        percentToRestart: Math.round((idleTimeMs / MAX_IDLE_TIME_MS) * 100),
+      },
+      memory: {
+        heapUsed: Math.round(memoryUsage.heapUsed / 1024 / 1024),
+        heapTotal: Math.round(memoryUsage.heapTotal / 1024 / 1024),
+        rss: Math.round(memoryUsage.rss / 1024 / 1024),
+      },
+      circuits: getAllCircuitStates(),
+      errors: {
+        queueSize: errorQueue.size,
+        recentErrors: recentErrors.map((e) => ({
+          timestamp: e.timestamp.toISOString(),
+          context: e.context,
+          message: e.error.message,
+        })),
+      },
+    });
+  });
+  
+  // All tool execution via /tools/call/:toolName (readiness check applied in route files)
+  app.use('/tools', toolsRoutes);
+  app.use('/prompts', promptsRoutes);
+
+  // 404 handler for undefined routes
+  app.use((_req: Request, res: Response) => {
+    res.status(404).json({
+      success: false,
+      error: {
+        message: 'Route not found',
+        code: 'NOT_FOUND',
+        availableRoutes: [
+          'GET  /health',
+          'GET  /tools/list',
+          'GET  /tools/info/:toolName',
+          'GET  /tools/schemas',
+          'GET  /tools/system',
+          'GET  /tools/initContext',
+          'POST /tools/call/:toolName',
+          'GET  /prompts/list',
+          'GET  /prompts/info/:promptName',
+        ],
+        hint: 'All tools are called via POST /tools/call/{toolName}',
+      },
+    });
+  });
+
+  app.use(errorHandler);
+  
+  return app;
+}
+
+/**
+ * Graceful shutdown handler for PM2
+ * PM2 sends SIGINT, we clean up and exit (PM2 handles restart)
+ */
+function gracefulShutdown(signal: string): void {
+  // Prevent double-shutdown (e.g., SIGINT + SIGTERM in quick succession)
+  if (isShuttingDown) {
+    console.log(dimLog(`Already shutting down, ignoring ${signal}`));
+    return;
+  }
+  isShuttingDown = true;
+
+  console.log(agentLog(`\n🛑 Received ${signal}. Starting graceful shutdown...`));
+
+  // Force exit safety net (PM2 kill_timeout is 120s, we exit at 110s)
+  const FORCE_EXIT_TIMEOUT_MS = 110 * 1000;
+  setTimeout(() => {
+    console.log(warnLog('⚠️ Force exiting due to drain timeout'));
+    process.exit(1);
+  }, FORCE_EXIT_TIMEOUT_MS).unref();
+
+  // 1. Stop idle check interval first
+  stopIdleCheck();
+
+  // 2. Stop circuit cleanup interval
+  stopCircuitCleanup();
+  console.log(successLog('✅ Circuit cleanup interval stopped'));
+
+  // 3. Clear circuit breakers
+  clearAllCircuits();
+  console.log(successLog('✅ Circuit breakers cleared'));
+  
+  // 4. Close HTTP server (waits for connections to drain)
+  if (server) {
+    console.log(dimLog('⏳ Waiting for connections to drain...'));
+    server.close((err) => {
+      if (err) {
+        console.error(errorLog('❌ Error closing server:'), err);
+        process.exit(1);
+      }
+      console.log(successLog('✅ HTTP server closed'));
+      process.exit(0); // PM2 handles restart
+    });
+  } else {
+    process.exit(0);
+  }
+}
+
+export async function startServer(): Promise<void> {
+  const app = await createServer();
+  
+  await new Promise<void>((resolve) => {
+    const httpServer = app.listen(PORT, HOST, () => {
+      server = httpServer;
+      console.log(agentLog(`🔍 Octocode Research Server running on http://${HOST}:${PORT}`));
+      console.log(dimLog(`⏳ initializing context...`));
+      
+      // Start background initialization (Warm Start)
+      initializeMcpContent()
+        .then(() => initializeProviders())
+        .then(() => {
+          console.log(successLog('✅ Context initialized - Server Ready'));
+          
+          // Reset idle timer after init (prevents early timeout)
+          lastRequestTime = Date.now();
+          
+          // Start idle check after initialization
+          startIdleCheck();
+          
+          console.log(agentLog(`📁 Logs: ${getLogsPath()}`));
+          console.log(agentLog(`\nRoutes:`));
+          console.log(dimLog(`  GET  /health                  - Server health`));
+          console.log(dimLog(`  GET  /tools/initContext       - System prompt + schemas (LOAD FIRST)`));
+          console.log(dimLog(`  GET  /tools/system            - System prompt only`));
+          console.log(dimLog(`  GET  /tools/list              - List all tools`));
+          console.log(dimLog(`  GET  /tools/info/:toolName    - Tool schema (BEFORE calling)`));
+          console.log(dimLog(`  GET  /tools/schemas           - All tools schemas`));
+          console.log(dimLog(`  POST /tools/call/:toolName    - Execute tool`));
+          console.log(dimLog(`  GET  /prompts/list            - List prompts`));
+          console.log(dimLog(`  GET  /prompts/info/:name      - Get prompt content`));
+
+          // Signal PM2 that we're ready
+          if (process.send) {
+            process.send('ready');
+            console.log(dimLog('📡 PM2 ready signal sent'));
+          }
+
+          // Log session initialization after server is ready
+          fireAndForgetWithTimeout(
+            () => logSessionInit(),
+            5000,
+            'logSessionInit'
+          );
+        })
+        .catch((err) => {
+          console.error(errorLog('❌ Initialization failed:'), err);
+        });
+
+      resolve();
+    });
+  });
+}
+
+// Signal handlers - PM2 sends SIGINT for graceful shutdown
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  startServer().catch((err) => {
+    console.error(errorLog('❌ Failed to start server:'), err);
+    process.exit(1);
+  });
+}