octocode-cli 1.5.1 → 1.5.3

package/skills/octocode-research/src/routes/tools.ts

@@ -1,23 +1,8 @@
-/**
- * Tools Info Routes - Expose tool metadata via HTTP
- *
- * Routes:
- *   GET  /tools/list            - List all tools (concise)
- *   GET  /tools/info            - List all tools with details
- *   GET  /tools/info/:toolName  - Get specific tool info
- *   POST /tools/call/:toolName  - Execute a tool directly (simplified!)
- *
- * Query params:
- *   schema=true  - Include schema information
- *   hints=true   - Include hints information
- */
-
 import { Router, type Request, type Response, type NextFunction } from 'express';
 import { getMcpContent } from '../mcpCache.js';
 import { transformToJsonSchema } from '../types/mcp.js';
-import { z } from 'zod/v4';
+import { z } from 'zod';
 
-// Import Zod schemas from octocode-mcp (source of truth)
 import {
   GitHubCodeSearchQuerySchema,
   GitHubViewRepoStructureQuerySchema,
@@ -62,7 +47,6 @@ import { checkReadiness } from '../middleware/readiness.js';
 
 export const toolsRoutes = Router();
 
-// Apply readiness check middleware to all tools routes
 toolsRoutes.use(checkReadiness);
 
 declare const __PACKAGE_VERSION__: string;
@@ -73,27 +57,20 @@ interface ToolsInfoQuery {
   hints?: string;
 }
 
-// ============================================================================
-// Zod Schema Registry - Maps tool names to their Zod schemas (source of truth)
-// ============================================================================
 
 const TOOL_ZOD_SCHEMAS: Record<string, z.ZodType> = {
-  // GitHub tools
   githubSearchCode: GitHubCodeSearchQuerySchema,
   githubGetFileContent: FileContentQuerySchema,
   githubViewRepoStructure: GitHubViewRepoStructureQuerySchema,
   githubSearchRepositories: GitHubReposSearchSingleQuerySchema,
   githubSearchPullRequests: GitHubPullRequestSearchQuerySchema,
-  // Local tools
   localSearchCode: RipgrepQuerySchema,
   localGetFileContent: FetchContentQuerySchema,
   localFindFiles: FindFilesQuerySchema,
   localViewStructure: ViewStructureQuerySchema,
-  // LSP tools
   lspGotoDefinition: LSPGotoDefinitionQuerySchema,
   lspFindReferences: LSPFindReferencesQuerySchema,
   lspCallHierarchy: LSPCallHierarchyQuerySchema,
-  // Package tools
   packageSearch: PackageSearchQuerySchema,
 };
 
@@ -110,12 +87,7 @@ function getToolJsonSchema(toolName: string): Record<string, unknown> | null {
   return zodSchema ? toJsonSchema(zodSchema) : null;
 }
 
-/**
- * GET /tools/list - Static list of all tools (concise discovery)
- *
- * Returns static JSON with tool names and short descriptions.
- * Use /tools/info/:toolName to get full description + schema BEFORE calling a tool.
- */
+
 toolsRoutes.get('/list', (_req: Request, res: Response) => {
   res.json({
     success: true,
@@ -140,9 +112,7 @@ toolsRoutes.get('/list', (_req: Request, res: Response) => {
   });
 });
 
-/**
- * GET /tools/info - Get info about all available tools
- */
+
 toolsRoutes.get('/info', async (
   req: Request,
   res: Response,
@@ -198,21 +168,6 @@ toolsRoutes.get('/info', async (
   }
 });
 
-/**
- * GET /tools/info/:toolName - Get full info for a specific tool (call before using!)
- *
- * Returns complete description, JSON schema, and hints for a tool.
- * ALWAYS call this before using a tool to understand its parameters.
- *
- * @example
- * GET /tools/info/localSearchCode
- *
- * Response includes:
- * - name: Tool name
- * - description: Full description with usage details
- * - schema: Complete JSON schema with all parameters
- * - hints: Success/empty result hints
- */
 toolsRoutes.get('/info/:toolName', async (
   req: Request,
   res: Response,
@@ -223,8 +178,8 @@ toolsRoutes.get('/info/:toolName', async (
 
     const { toolName } = req.params;
     const query = req.query as ToolsInfoQuery;
-    const includeSchema = query.schema !== 'false';  // Default true for specific tool
-    const includeHints = query.hints !== 'false';    // Default true for specific tool
+    const includeSchema = query.schema !== 'false';
+    const includeHints = query.hints !== 'false';
 
     const tool = content.tools[toolName];
 
@@ -248,15 +203,13 @@ toolsRoutes.get('/info/:toolName', async (
     };
 
     if (includeSchema) {
-      // Try to get the actual Zod schema (source of truth with correct types and required fields)
       const zodJsonSchema = getToolJsonSchema(toolName);
       if (zodJsonSchema) {
         result.inputSchema = zodJsonSchema;
-        result._schemaSource = 'zod'; // Indicates this is from the authoritative Zod schema
+        result._schemaSource = 'zod';
       } else {
-        // Fallback to metadata-based schema (less accurate)
         result.inputSchema = transformToJsonSchema(tool.schema, tool.name);
-        result._schemaSource = 'metadata'; // Indicates this is a fallback
+        result._schemaSource = 'metadata';
       }
     }
 
@@ -277,9 +230,7 @@ toolsRoutes.get('/info/:toolName', async (
   }
 });
 
-/**
- * GET /tools/metadata - Get raw complete metadata (advanced)
- */
+
 toolsRoutes.get('/metadata', async (
   _req: Request,
   res: Response,
@@ -303,28 +254,6 @@ toolsRoutes.get('/metadata', async (
   }
 });
 
-/**
- * GET /tools/schemas - Get all tools with their complete JSON schemas
- *
- * Returns all tool names with their full JSON schemas (from Zod).
- * Useful for bulk schema retrieval without calling /info/:toolName for each.
- *
- * @example
- * GET /tools/schemas
- *
- * Response:
- * {
- *   "success": true,
- *   "data": {
- *     "totalTools": 13,
- *     "schemas": {
- *       "localSearchCode": { "type": "object", "properties": {...} },
- *       "githubSearchCode": { "type": "object", "properties": {...} },
- *       ...
- *     }
- *   }
- * }
- */
 toolsRoutes.get('/schemas', async (
   _req: Request,
   res: Response,
@@ -354,21 +283,6 @@ toolsRoutes.get('/schemas', async (
   }
 });
 
-/**
- * GET /tools/system - Get the FULL system instructions
- *
- * Returns the complete system prompt that should be loaded into context FIRST.
- * This defines the agent's behavior, methodology, and best practices.
- *
- * @example
- * GET /tools/system
- *
- * Response:
- * {
- *   "instructions": "## Expert Code Forensics Agent...",
- *   "_meta": { "charCount": 5432, "version": "2.2.0" }
- * }
- */
 toolsRoutes.get('/system', async (
   _req: Request,
   res: Response,
@@ -391,25 +305,6 @@ toolsRoutes.get('/system', async (
   }
 });
 
-/**
- * GET /tools/initContext - Combined system prompt and all tool schemas
- *
- * Combines /tools/system + /tools/schemas in one call for faster init.
- * Returns:
- * - system_prompt: Full instructions
- * - tools_schema: All tool JSON schemas from Zod
- *
- * @example
- * GET /tools/initContext
- *
- * Response:
- * {
- *   "success": true,
- *   "system_prompt": "## Expert Code Forensics Agent...",
- *   "tools_schema": { "localSearchCode": {...}, ... },
- *   "_meta": { "promptCharCount": 5432, "toolsCount": 13, "version": "2.2.0" }
- * }
- */
 toolsRoutes.get('/initContext', async (
   _req: Request,
   res: Response,
@@ -418,7 +313,6 @@ toolsRoutes.get('/initContext', async (
   try {
     const content = getMcpContent();
 
-    // Build schemas (same as /tools/schemas)
     const schemas: Record<string, Record<string, unknown>> = {};
     for (const toolName of Object.keys(TOOL_ZOD_SCHEMAS)) {
       const schema = getToolJsonSchema(toolName);
@@ -440,16 +334,10 @@ toolsRoutes.get('/initContext', async (
   }
 });
 
-// ============================================================================
-// Tool Registry - Maps tool names to functions and resilience wrappers
-// ============================================================================
 
 type ResilienceFn = <T>(fn: () => Promise<T>, toolName: string) => Promise<T>;
 
-/**
- * Tool registry entry for dynamic dispatch.
- * Tool functions are dispatched by name at runtime; Zod schemas validate inputs.
- */
+
 interface ToolEntry {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   fn: (params: any) => Promise<any>;
@@ -458,54 +346,43 @@ interface ToolEntry {
 }
 
 const TOOL_REGISTRY: Record<string, ToolEntry> = {
-  // GitHub tools
   githubSearchCode: { fn: githubSearchCode, resilience: withGitHubResilience, category: 'github' },
   githubGetFileContent: { fn: githubGetFileContent, resilience: withGitHubResilience, category: 'github' },
   githubViewRepoStructure: { fn: githubViewRepoStructure, resilience: withGitHubResilience, category: 'github' },
   githubSearchRepositories: { fn: githubSearchRepositories, resilience: withGitHubResilience, category: 'github' },
   githubSearchPullRequests: { fn: githubSearchPullRequests, resilience: withGitHubResilience, category: 'github' },
 
-  // Local tools
   localSearchCode: { fn: localSearchCode, resilience: withLocalResilience, category: 'local' },
   localGetFileContent: { fn: localGetFileContent, resilience: withLocalResilience, category: 'local' },
   localFindFiles: { fn: localFindFiles, resilience: withLocalResilience, category: 'local' },
   localViewStructure: { fn: localViewStructure, resilience: withLocalResilience, category: 'local' },
 
-  // LSP tools
   lspGotoDefinition: { fn: lspGotoDefinition, resilience: withLspResilience, category: 'lsp' },
   lspFindReferences: { fn: lspFindReferences, resilience: withLspResilience, category: 'lsp' },
   lspCallHierarchy: { fn: lspCallHierarchy, resilience: withLspResilience, category: 'lsp' },
 
-  // Package tools
   packageSearch: { fn: packageSearch, resilience: withPackageResilience, category: 'package' },
 };
 
-/**
- * Extract repository identifiers from query parameters for session logging
- */
+
 function extractReposFromQueries(queries: unknown[]): string[] {
   const repos: string[] = [];
   for (const query of queries) {
     const q = query as Record<string, unknown>;
-    // GitHub repos: owner/repo format
     if (q.owner && q.repo) {
       repos.push(`${q.owner}/${q.repo}`);
     }
-    // Local paths
     if (q.path && typeof q.path === 'string') {
       repos.push(q.path);
     }
-    // LSP uris
     if (q.uri && typeof q.uri === 'string') {
       repos.push(q.uri);
     }
   }
-  return [...new Set(repos)]; // Deduplicate
+  return [...new Set(repos)];
 }
 
-/**
- * Extract research parameters from the first query for logging
- */
+
 function extractResearchParams(queries: unknown[]): {
   mainResearchGoal?: string;
   researchGoal?: string;
@@ -520,48 +397,15 @@ function extractResearchParams(queries: unknown[]): {
   };
 }
 
-/**
- * POST /tools/call/:toolName - Execute a tool directly with JSON body
- *
- * This is the SIMPLIFIED way to call tools. Instead of URL-encoded query params,
- * just POST a JSON body with your queries array.
- *
- * @example
- * POST /tools/call/localSearchCode
- * Content-Type: application/json
- *
- * {
- *   "queries": [{
- *     "mainResearchGoal": "Find authentication handlers",
- *     "researchGoal": "Locate auth middleware",
- *     "reasoning": "Understanding auth flow",
- *     "pattern": "authenticate",
- *     "path": "/Users/me/project",
- *     "type": "ts"
- *   }]
- * }
- *
- * Response:
- * {
- *   "tool": "localSearchCode",
- *   "success": true,
- *   "data": { ... parsed tool response ... },
- *   "hints": ["Use lineHint for LSP tools", ...]
- * }
- */
 toolsRoutes.post('/call/:toolName', async (
   req: Request,
   res: Response,
   next: NextFunction
 ) => {
-  // Set up AbortController for client disconnection handling
-  // NOTE: req.on('close') fires when request body is consumed, not client disconnect
-  // Use res.on('close') + socket.destroyed to detect actual client disconnection
   const abortController = new AbortController();
   let isAborted = false;
 
   res.on('close', () => {
-    // Only abort if client disconnected before we finished responding
     if (!res.writableEnded && req.socket?.destroyed) {
       isAborted = true;
       abortController.abort();
@@ -571,7 +415,6 @@ toolsRoutes.post('/call/:toolName', async (
   try {
     const { toolName } = req.params;
 
-    // Validate tool exists
     const toolEntry = TOOL_REGISTRY[toolName];
     if (!toolEntry) {
       const availableTools = Object.keys(TOOL_REGISTRY);
@@ -588,7 +431,6 @@ toolsRoutes.post('/call/:toolName', async (
       return;
     }
 
-    // Validate request body using schema
     const validation = validateToolCallBody(req.body);
     if (!validation.success) {
       res.status(400).json({
@@ -602,19 +444,15 @@ toolsRoutes.post('/call/:toolName', async (
 
     const { queries } = validation.data!;
 
-    // Check if request was aborted before execution
     if (isAborted) return;
 
-    // Execute tool with resilience (includes timeout + circuit breaker + retry)
     const rawResult = await toolEntry.resilience(
       () => toolEntry.fn({ queries }),
       toolName
     );
 
-    // Check if request was aborted after execution
     if (isAborted) return;
 
-    // Log tool call for session telemetry
     const repos = extractReposFromQueries(queries);
     const researchParams = extractResearchParams(queries);
     fireAndForgetWithTimeout(
@@ -631,7 +469,6 @@ toolsRoutes.post('/call/:toolName', async (
 
     const mcpResponse = rawResult as { content: Array<{ type: string; text: string }> };
 
-    // For multiple queries, return bulk response format
     if (queries.length > 1) {
       const bulkParsed = parseToolResponseBulk(mcpResponse);
 
@@ -647,7 +484,6 @@ toolsRoutes.post('/call/:toolName', async (
       return;
     }
 
-    // Single query - use existing response format for backward compatibility
     const parsed = parseToolResponse(mcpResponse);
 
     res.status(parsed.isError ? 500 : 200).json({
@@ -658,7 +494,6 @@ toolsRoutes.post('/call/:toolName', async (
       research: parsed.research,
     });
   } catch (error) {
-    // Skip error handling if request was aborted
     if (isAborted) return;
     next(error);
   }

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

@@ -1,24 +1,6 @@
-/**
- * Server Init Script — Detached Daemon Launcher
- *
- * 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
- *
- * 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 { join } from 'path';
 
-// =============================================================================
-// Configuration (Environment Variables)
-// =============================================================================
 
 const PORT = parseInt(process.env.OCTOCODE_RESEARCH_PORT || process.env.OCTOCODE_PORT || '1987', 10);
 const HOST = process.env.OCTOCODE_RESEARCH_HOST || 'localhost';
@@ -30,9 +12,6 @@ interface HealthResponse {
   status: 'ok' | 'initializing' | string;
 }
 
-// =============================================================================
-// Health Check
-// =============================================================================
 
 async function checkHealth(): Promise<HealthResponse | null> {
   try {
@@ -53,9 +32,6 @@ async function checkHealth(): Promise<HealthResponse | null> {
   }
 }
 
-// =============================================================================
-// Server Start — detached daemon (survives parent exit)
-// =============================================================================
 
 function startServer(): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -82,9 +58,6 @@ function startServer(): Promise<void> {
   });
 }
 
-// =============================================================================
-// Wait for Ready (with exponential backoff)
-// =============================================================================
 
 async function waitForReady(): Promise<boolean> {
   const startTime = Date.now();
@@ -108,12 +81,8 @@ async function waitForReady(): Promise<boolean> {
   return false;
 }
 
-// =============================================================================
-// Main
-// =============================================================================
 
 async function main(): Promise<void> {
-  // Fast path: server already running → exit immediately
   const initialHealth = await checkHealth();
 
   if (initialHealth?.status === 'ok') {
@@ -133,7 +102,6 @@ async function main(): Promise<void> {
     }
   }
 
-  // Server not running — start it (detached)
   console.log('[server-init] Server not running, starting detached daemon...');
 
   try {

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

@@ -25,7 +25,6 @@ const getPort = (raw?: string): number => {
 
   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}". ` +
@@ -38,15 +37,14 @@ const getPort = (raw?: string): number => {
 
 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
+const MAX_IDLE_TIME_MS = 30 * 60 * 1000;
+const IDLE_CHECK_INTERVAL_MS = 120 * 1000;
 
 let server: Server | null = null;
 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`);
 
@@ -55,7 +53,7 @@ function writePidFile(): void {
     mkdirSync(OCTOCODE_DIR, { recursive: true, mode: 0o700 });
     writeFileSync(PID_FILE, String(process.pid), { mode: 0o600 });
   } catch {
-    // Non-fatal — server works without PID file
+    void 0;
   }
 }
 
@@ -63,13 +61,11 @@ function removePidFile(): void {
   try {
     unlinkSync(PID_FILE);
   } catch {
-    // Already removed or never written
+    void 0;
   }
 }
 
-/**
- * Check if server has been idle and should restart
- */
+
 function checkIdleRestart(): void {
   const idleTime = Date.now() - lastRequestTime;
   const idleSeconds = Math.floor(idleTime / 1000);
@@ -82,23 +78,18 @@ function checkIdleRestart(): void {
   }
 }
 
-/**
- * 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);
@@ -108,16 +99,13 @@ function stopIdleCheck(): void {
 }
 
 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();
@@ -139,7 +127,6 @@ export async function createServer(): Promise<Express> {
       uptime: Math.floor(process.uptime()),
       processManager: 'self (detached daemon)',
       pid: process.pid,
-      // Idle tracking info
       idle: {
         currentMs: idleTimeMs,
         thresholdMs: MAX_IDLE_TIME_MS,
@@ -163,11 +150,9 @@ export async function createServer(): Promise<Express> {
     });
   });
   
-  // 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,
@@ -197,11 +182,7 @@ export async function createServer(): Promise<Express> {
   return app;
 }
 
-/**
- * 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 {
   if (isShuttingDown) {
     console.log(dimLog(`Already shutting down, ignoring ${signal}`));
@@ -217,21 +198,16 @@ function gracefulShutdown(signal: string): void {
     process.exit(1);
   }, FORCE_EXIT_TIMEOUT_MS).unref();
 
-  // 1. Remove PID file immediately
   removePidFile();
 
-  // 2. Stop idle check interval
   stopIdleCheck();
 
-  // 3. Stop circuit cleanup interval
   stopCircuitCleanup();
   console.log(successLog('✅ Circuit cleanup interval stopped'));
 
-  // 4. Clear circuit breakers
   clearAllCircuits();
   console.log(successLog('✅ Circuit breakers cleared'));
   
-  // 5. Close HTTP server (waits for connections to drain)
   if (server) {
     console.log(dimLog('⏳ Waiting for connections to drain...'));
     server.close((err) => {
@@ -257,16 +233,13 @@ export async function startServer(): Promise<void> {
       console.log(agentLog(`🔍 Octocode Research Server running on http://${HOST}:${PORT} (pid: ${process.pid})`));
       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()}`));
@@ -283,7 +256,6 @@ export async function startServer(): Promise<void> {
           console.log(dimLog(`  GET  /prompts/list            - List prompts`));
           console.log(dimLog(`  GET  /prompts/info/:name      - Get prompt content`));
 
-          // Log session initialization after server is ready
           fireAndForgetWithTimeout(
             () => logSessionInit(),
             5000,
@@ -299,7 +271,6 @@ export async function startServer(): Promise<void> {
   });
 }
 
-// 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

@@ -1,15 +1,3 @@
-/**
- * Type guards for safe error handling.
- *
- * Replaces unsafe type coercion (err as { status?: number }) with
- * proper runtime type checking for better type safety.
- *
- * @module types/errorGuards
- */
-
-// =============================================================================
-// Internal Interfaces & Guards
-// =============================================================================
 
 interface ErrorWithStatus {
   status: number;
@@ -48,9 +36,6 @@ function hasMessage(err: unknown): err is { message: string } {
   );
 }
 
-// =============================================================================
-// Public API
-// =============================================================================
 
 export function getErrorStatus(err: unknown): number | undefined {
   return isErrorWithStatus(err) ? err.status : undefined;