octocode-cli 1.2.8 → 1.2.10

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

@@ -1,175 +1,37 @@
 /**
- * Server Init Script
+ * Server Init Script — Detached Daemon Launcher
  *
- * 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
+ * 1. Checks if server is already running (health check)
+ * 2. If running → prints "ok" and exits
+ * 3. If not → starts server as **detached** process, waits for health, prints "ok", exits
  *
- * 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
+ * Lifecycle: The server runs as an independent daemon (detached, unref'd).
+ * No client owns the server — it self-terminates after 30 minutes of idle.
+ * Every invocation of this script exits after confirming the server is healthy.
  *
  * 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 PORT = parseInt(process.env.OCTOCODE_RESEARCH_PORT || process.env.OCTOCODE_PORT || '1987', 10);
+const HOST = process.env.OCTOCODE_RESEARCH_HOST || 'localhost';
+const HEALTH_URL = `http://${HOST}:${PORT}/health`;
 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)
+// Health Check
 // =============================================================================
 
 async function checkHealth(): Promise<HealthResponse | null> {
@@ -184,7 +46,6 @@ async function checkHealth(): Promise<HealthResponse | 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}`);
     }
@@ -193,7 +54,7 @@ async function checkHealth(): Promise<HealthResponse | null> {
 }
 
 // =============================================================================
-// Server Start (Improved with error handling)
+// Server Start — detached daemon (survives parent exit)
 // =============================================================================
 
 function startServer(): Promise<void> {
@@ -202,21 +63,20 @@ function startServer(): Promise<void> {
     const serverScript = join(scriptDir, 'server.js');
 
     const child = spawn('node', [serverScript], {
-      detached: true,
       stdio: 'ignore',
       cwd: scriptDir,
+      detached: true,
     });
 
-    // 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
+    child.unref();
+
     setTimeout(() => {
-      child.unref();
-      console.log(`[server-init] Started server process (pid: ${child.pid})`);
+      console.log(`[server-init] Spawned detached server process (pid: ${child.pid})`);
       resolve();
     }, 100);
   });
@@ -242,7 +102,6 @@ async function waitForReady(): Promise<boolean> {
     }
 
     await new Promise((resolve) => setTimeout(resolve, pollInterval));
-    // Gradual backoff up to 2s
     pollInterval = Math.min(pollInterval * 1.5, 2000);
   }
 
@@ -254,19 +113,15 @@ async function waitForReady(): Promise<boolean> {
 // =============================================================================
 
 async function main(): Promise<void> {
-  // ==========================================================================
-  // FAST PATH: Check if server is already running (no lock needed)
-  // ==========================================================================
+  // Fast path: server already running → exit immediately
   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) {
@@ -278,86 +133,24 @@ async function main(): Promise<void> {
     }
   }
 
-  // ==========================================================================
-  // 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);
-    }
-  }
+  // Server not running — start it (detached)
+  console.log('[server-init] Server not running, starting detached daemon...');
 
   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();
+    await startServer();
+  } catch {
+    console.error('[server-init] ERROR: Failed to spawn server process');
     process.exit(1);
   }
-}
 
-// Cleanup on exit
-process.on('SIGINT', () => {
-  releaseLock();
-  process.exit(130);
-});
+  const ready = await waitForReady();
+  if (!ready) {
+    console.error('[server-init] ERROR: Server failed to start within timeout');
+    process.exit(1);
+  }
 
-process.on('SIGTERM', () => {
-  releaseLock();
-  process.exit(143);
-});
+  console.log('ok');
+  process.exit(0);
+}
 
 main();

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

@@ -1,5 +1,8 @@
 import express, { type Express, type Request, type Response, type NextFunction } from 'express';
 import type { Server } from 'http';
+import { writeFileSync, unlinkSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
 import { toolsRoutes } from './routes/tools.js';
 import { promptsRoutes } from './routes/prompts.js';
 import { errorHandler } from './middleware/errorHandler.js';
@@ -12,6 +15,8 @@ import { agentLog, successLog, errorLog, dimLog, warnLog } from './utils/colors.
 import { fireAndForgetWithTimeout } from './utils/asyncTimeout.js';
 import { errorQueue } from './utils/errorQueue.js';
 
+declare const __PACKAGE_VERSION__: string;
+
 const HOST = process.env.OCTOCODE_RESEARCH_HOST || 'localhost';
 
 const getPort = (raw?: string): number => {
@@ -31,7 +36,7 @@ const getPort = (raw?: string): number => {
   return port;
 };
 
-const PORT = getPort(process.env.OCTOCODE_RESEARCH_PORT);
+const PORT = getPort(process.env.OCTOCODE_RESEARCH_PORT || process.env.OCTOCODE_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
@@ -41,6 +46,27 @@ let lastRequestTime: number = Date.now();
 let idleCheckInterval: NodeJS.Timeout | null = null;
 let isShuttingDown = false;
 
+// PID file for daemon lifecycle management
+const OCTOCODE_DIR = process.env.OCTOCODE_HOME || join(homedir(), '.octocode');
+export const PID_FILE = join(OCTOCODE_DIR, `research-server-${PORT}.pid`);
+
+function writePidFile(): void {
+  try {
+    mkdirSync(OCTOCODE_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(PID_FILE, String(process.pid), { mode: 0o600 });
+  } catch {
+    // Non-fatal — server works without PID file
+  }
+}
+
+function removePidFile(): void {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+    // Already removed or never written
+  }
+}
+
 /**
  * Check if server has been idle and should restart
  */
@@ -52,7 +78,6 @@ function checkIdleRestart(): void {
     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`));
   }
 }
@@ -110,9 +135,10 @@ export async function createServer(): Promise<Express> {
       status: initialized ? 'ok' : 'initializing',
       host: HOST,
       port: PORT,
-      version: '2.2.0',
+      version: __PACKAGE_VERSION__,
       uptime: Math.floor(process.uptime()),
-      processManager: 'pm2',
+      processManager: 'self (detached daemon)',
+      pid: process.pid,
       // Idle tracking info
       idle: {
         currentMs: idleTimeMs,
@@ -150,11 +176,13 @@ export async function createServer(): Promise<Express> {
         code: 'NOT_FOUND',
         availableRoutes: [
           'GET  /health',
+          'GET  /tools/initContext',
           'GET  /tools/list',
+          'GET  /tools/info',
           'GET  /tools/info/:toolName',
+          'GET  /tools/metadata',
           'GET  /tools/schemas',
           'GET  /tools/system',
-          'GET  /tools/initContext',
           'POST /tools/call/:toolName',
           'GET  /prompts/list',
           'GET  /prompts/info/:promptName',
@@ -170,11 +198,11 @@ export async function createServer(): Promise<Express> {
 }
 
 /**
- * Graceful shutdown handler for PM2
- * PM2 sends SIGINT, we clean up and exit (PM2 handles restart)
+ * Graceful shutdown handler.
+ * Triggered by SIGTERM, SIGINT, or idle timeout. Cleans up all resources
+ * including PID file, circuit breakers, and HTTP connections.
  */
 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;
@@ -183,25 +211,27 @@ function gracefulShutdown(signal: string): void {
 
   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;
+  const FORCE_EXIT_TIMEOUT_MS = 30 * 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
+  // 1. Remove PID file immediately
+  removePidFile();
+
+  // 2. Stop idle check interval
   stopIdleCheck();
 
-  // 2. Stop circuit cleanup interval
+  // 3. Stop circuit cleanup interval
   stopCircuitCleanup();
   console.log(successLog('✅ Circuit cleanup interval stopped'));
 
-  // 3. Clear circuit breakers
+  // 4. Clear circuit breakers
   clearAllCircuits();
   console.log(successLog('✅ Circuit breakers cleared'));
   
-  // 4. Close HTTP server (waits for connections to drain)
+  // 5. Close HTTP server (waits for connections to drain)
   if (server) {
     console.log(dimLog('⏳ Waiting for connections to drain...'));
     server.close((err) => {
@@ -210,7 +240,7 @@ function gracefulShutdown(signal: string): void {
         process.exit(1);
       }
       console.log(successLog('✅ HTTP server closed'));
-      process.exit(0); // PM2 handles restart
+      process.exit(0);
     });
   } else {
     process.exit(0);
@@ -223,7 +253,8 @@ export async function startServer(): Promise<void> {
   await new Promise<void>((resolve) => {
     const httpServer = app.listen(PORT, HOST, () => {
       server = httpServer;
-      console.log(agentLog(`🔍 Octocode Research Server running on http://${HOST}:${PORT}`));
+      writePidFile();
+      console.log(agentLog(`🔍 Octocode Research Server running on http://${HOST}:${PORT} (pid: ${process.pid})`));
       console.log(dimLog(`⏳ initializing context...`));
       
       // Start background initialization (Warm Start)
@@ -244,18 +275,14 @@ export async function startServer(): Promise<void> {
           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              - All tools with details`));
           console.log(dimLog(`  GET  /tools/info/:toolName    - Tool schema (BEFORE calling)`));
+          console.log(dimLog(`  GET  /tools/metadata          - Raw MCP metadata`));
           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(),
@@ -272,7 +299,7 @@ export async function startServer(): Promise<void> {
   });
 }
 
-// Signal handlers - PM2 sends SIGINT for graceful shutdown
+// Signal handlers — server is a detached daemon, handles its own signals
 process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
 process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 

package/skills/octocode-research/src/types/errorGuards.ts

@@ -8,40 +8,20 @@
  */
 
 // =============================================================================
-// Error Interfaces
+// Internal Interfaces & Guards
 // =============================================================================
 
-/**
- * Error with HTTP status code (e.g., from API responses)
- */
-export interface ErrorWithStatus {
+interface ErrorWithStatus {
   status: number;
   message?: string;
 }
 
-/**
- * Error with error code (e.g., Node.js system errors)
- */
-export interface ErrorWithCode {
+interface ErrorWithCode {
   code: string;
   message?: string;
 }
 
-/**
- * Error with headers (e.g., rate limit responses)
- */
-export interface ErrorWithHeaders {
-  headers: Record<string, string>;
-}
-
-// =============================================================================
-// Type Guards
-// =============================================================================
-
-/**
- * Check if error has a status property (number)
- */
-export function isErrorWithStatus(err: unknown): err is ErrorWithStatus {
+function isErrorWithStatus(err: unknown): err is ErrorWithStatus {
   return (
     err !== null &&
     typeof err === 'object' &&
@@ -50,10 +30,7 @@ export function isErrorWithStatus(err: unknown): err is ErrorWithStatus {
   );
 }
 
-/**
- * Check if error has a code property (string)
- */
-export function isErrorWithCode(err: unknown): err is ErrorWithCode {
+function isErrorWithCode(err: unknown): err is ErrorWithCode {
   return (
     err !== null &&
     typeof err === 'object' &&
@@ -62,10 +39,7 @@ export function isErrorWithCode(err: unknown): err is ErrorWithCode {
   );
 }
 
-/**
- * Check if error has a message property (string)
- */
-export function hasMessage(err: unknown): err is { message: string } {
+function hasMessage(err: unknown): err is { message: string } {
   return (
     err !== null &&
     typeof err === 'object' &&
@@ -74,77 +48,32 @@ export function hasMessage(err: unknown): err is { message: string } {
   );
 }
 
-/**
- * Check if error has headers property (object)
- */
-export function hasHeaders(err: unknown): err is ErrorWithHeaders {
-  return (
-    err !== null &&
-    typeof err === 'object' &&
-    'headers' in err &&
-    typeof (err as { headers: unknown }).headers === 'object' &&
-    (err as ErrorWithHeaders).headers !== null
-  );
-}
-
 // =============================================================================
-// Safe Property Accessors
+// Public API
 // =============================================================================
 
-/**
- * Safely get status from error (undefined if not present)
- */
 export function getErrorStatus(err: unknown): number | undefined {
   return isErrorWithStatus(err) ? err.status : undefined;
 }
 
-/**
- * Safely get code from error (undefined if not present)
- */
-export function getErrorCode(err: unknown): string | undefined {
+function getErrorCode(err: unknown): string | undefined {
   return isErrorWithCode(err) ? err.code : undefined;
 }
 
-/**
- * Safely get message from error (undefined if not present)
- */
-export function getErrorMessage(err: unknown): string | undefined {
+function getErrorMessage(err: unknown): string | undefined {
   return hasMessage(err) ? err.message : undefined;
 }
 
-/**
- * Safely get header value from error (undefined if not present)
- */
-export function getErrorHeader(err: unknown, header: string): string | undefined {
-  if (hasHeaders(err)) {
-    return err.headers[header];
-  }
-  return undefined;
-}
-
-// =============================================================================
-// Composite Checks
-// =============================================================================
-
-/**
- * Check if error status is in a given list
- */
 export function hasStatusIn(err: unknown, statuses: readonly number[]): boolean {
   const status = getErrorStatus(err);
   return status !== undefined && statuses.includes(status);
 }
 
-/**
- * Check if error code is in a given list
- */
 export function hasCodeIn(err: unknown, codes: readonly string[]): boolean {
   const code = getErrorCode(err);
   return code !== undefined && codes.includes(code);
 }
 
-/**
- * Check if error message matches any pattern
- */
 export function messageMatches(err: unknown, patterns: readonly RegExp[]): boolean {
   const message = getErrorMessage(err);
   return message !== undefined && patterns.some((p) => p.test(message));