octocode-cli 1.5.0 → 1.5.3

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

@@ -1,27 +1,14 @@
-/**
- * Type guard utilities for consistent runtime type checking.
- * Use these instead of inline typeof checks across routes.
- *
- * @module types/guards
- */
 
-/**
- * Check if value is an array (of any type)
- */
 export function isArray(value: unknown): value is unknown[] {
   return Array.isArray(value);
 }
 
-/**
- * Check if value is a non-null object
- */
+
 export function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/**
- * Check if object has a specific property
- */
+
 export function hasProperty<K extends string>(
   obj: unknown,
   key: K
@@ -29,9 +16,7 @@ export function hasProperty<K extends string>(
   return typeof obj === 'object' && obj !== null && key in obj;
 }
 
-/**
- * Check if object has a string property
- */
+
 export function hasStringProperty<K extends string>(
   obj: unknown,
   key: K
@@ -39,9 +24,7 @@ export function hasStringProperty<K extends string>(
   return hasProperty(obj, key) && typeof obj[key] === 'string';
 }
 
-/**
- * Check if object has a number property
- */
+
 export function hasNumberProperty<K extends string>(
   obj: unknown,
   key: K
@@ -49,9 +32,7 @@ export function hasNumberProperty<K extends string>(
   return hasProperty(obj, key) && typeof obj[key] === 'number';
 }
 
-/**
- * Check if object has a boolean property
- */
+
 export function hasBooleanProperty<K extends string>(
   obj: unknown,
   key: K
@@ -59,9 +40,7 @@ export function hasBooleanProperty<K extends string>(
   return hasProperty(obj, key) && typeof obj[key] === 'boolean';
 }
 
-/**
- * Check if object has an array property
- */
+
 export function hasArrayProperty<K extends string>(
   obj: unknown,
   key: K

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

@@ -1,7 +1,3 @@
-/**
- * MCP Protocol utilities for /tools endpoints
- */
-
 interface JsonSchemaProperty {
   type: string;
   description?: string;
@@ -26,10 +22,7 @@ interface JsonSchema {
   additionalProperties?: boolean;
 }
 
-/**
- * Transform description-based schema to JSON Schema format.
- * Fallback transformer when full JSON schemas are not available.
- */
+
 export function transformToJsonSchema(
   schemaDescriptions: Record<string, string>,
   toolName: string

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

@@ -1,14 +1,5 @@
-/**
- * Response types for MCP tool results.
- *
- * @module types/responses
- */
-
 import { hasProperty, hasArrayProperty } from './guards.js';
 
-// =============================================================================
-// File and Search Types
-// =============================================================================
 
 export interface FileMatch {
   path: string;
@@ -37,9 +28,6 @@ export interface PaginationInfo {
   nextCursor?: string;
 }
 
-// =============================================================================
-// Internal helpers
-// =============================================================================
 
 function isFileMatch(obj: unknown): obj is FileMatch {
   return (
@@ -56,9 +44,6 @@ function hasValidPagination(obj: unknown): obj is { pagination: PaginationInfo }
   return typeof p === 'object' && p !== null;
 }
 
-// =============================================================================
-// Public extractors
-// =============================================================================
 
 export function extractFiles(data: unknown): FileMatch[] {
   if (!hasArrayProperty(data, 'files')) return [];

package/skills/octocode-research/src/utils/asyncTimeout.ts

@@ -1,45 +1,8 @@
 import { errorQueue } from './errorQueue.js';
 
-/**
- * Timeout wrapper for fire-and-forget async operations.
- *
- * Prevents unbounded async operations from hanging indefinitely.
- * Uses Promise.race with AbortController for clean cancellation.
- *
- * @module utils/asyncTimeout
- */
 
-/**
- * Default timeout for fire-and-forget operations (5 seconds).
- * Tuned for logging/telemetry operations that should complete quickly.
- */
 const DEFAULT_TIMEOUT_MS = 5000;
 
-/**
- * Execute an async operation with timeout protection.
- *
- * Fire-and-forget pattern with built-in timeout to prevent:
- * - Memory leaks from unresolved promises
- * - Resource exhaustion from hanging operations
- * - Cascading failures from slow logging/telemetry
- *
- * @param operation - Async operation to execute
- * @param timeoutMs - Maximum time to wait (default: 5000ms)
- * @param context - Context string for error logging
- *
- * @example
- * ```typescript
- * // Instead of:
- * logSessionError(tool, code).catch(err => errorQueue.push(err, 'logSessionError'));
- *
- * // Use:
- * fireAndForgetWithTimeout(
- *   () => logSessionError(tool, code),
- *   5000,
- *   'logSessionError'
- * );
- * ```
- */
 export function fireAndForgetWithTimeout(
   operation: () => Promise<unknown>,
   timeoutMs = DEFAULT_TIMEOUT_MS,
@@ -48,21 +11,17 @@ export function fireAndForgetWithTimeout(
   const controller = new AbortController();
   const { signal } = controller;
 
-  // Create timeout promise
   const timeoutPromise = new Promise<never>((_, reject) => {
     const timeoutId = setTimeout(() => {
       controller.abort();
       reject(new Error(`Operation timed out after ${timeoutMs}ms`));
     }, timeoutMs);
 
-    // Clean up timeout if operation completes first
     signal.addEventListener('abort', () => clearTimeout(timeoutId), { once: true });
   });
 
-  // Race operation against timeout
   Promise.race([operation(), timeoutPromise])
     .catch((err: unknown) => {
-      // Log to error queue - never throw from fire-and-forget
       errorQueue.push(
         err instanceof Error ? err : new Error(String(err)),
         context
@@ -70,27 +29,6 @@ export function fireAndForgetWithTimeout(
     });
 }
 
-/**
- * Execute an async operation with timeout and return result.
- *
- * Unlike fireAndForgetWithTimeout, this returns the result or throws on timeout.
- * Use for operations where you need the result but want timeout protection.
- *
- * @param operation - Async operation to execute
- * @param timeoutMs - Maximum time to wait
- * @param context - Context string for timeout error message
- * @returns Promise resolving to operation result
- * @throws Error if operation times out
- *
- * @example
- * ```typescript
- * const result = await withTimeout(
- *   () => fetchData(),
- *   3000,
- *   'fetchData'
- * );
- * ```
- */
 export async function withTimeout<T>(
   operation: () => Promise<T>,
   timeoutMs: number,
@@ -111,6 +49,6 @@ export async function withTimeout<T>(
   try {
     return await Promise.race([operation(), timeoutPromise]);
   } finally {
-    controller.abort(); // Clean up if operation completed
+    controller.abort();
   }
 }

package/skills/octocode-research/src/utils/circuitBreaker.ts

@@ -1,25 +1,14 @@
 import { agentLog, warnLog, successLog, errorLog } from './colors.js';
 import { logRateLimit } from '../index.js';
 import { fireAndForgetWithTimeout } from './asyncTimeout.js';
-/**
- * Circuit breaker pattern for LSP and external services.
- *
- * Prevents cascading failures by temporarily stopping calls to failing services.
- *
- * @module utils/circuitBreaker
- */
-
-/**
- * Circuit breaker states
- */
+
+
 type CircuitState = 'closed' | 'open' | 'half-open';
 
-/**
- * Memory management constants
- */
-const MAX_CIRCUITS = 100; // Maximum number of circuits to prevent unbounded growth
-const CIRCUIT_TTL_MS = 3600000; // 1 hour TTL for stale circuits
-const CLEANUP_INTERVAL_MS = 600000; // 10 minutes between cleanup runs
+
+const MAX_CIRCUITS = 100;
+const CIRCUIT_TTL_MS = 3600000;
+const CLEANUP_INTERVAL_MS = 600000;
 
 interface CircuitRecord {
   failures: number;
@@ -27,55 +16,37 @@ interface CircuitRecord {
   lastFailure: number;
   lastAttempt: number;
   state: CircuitState;
-  createdAt: number; // Timestamp when circuit was created
+  createdAt: number;
 }
 
-/**
- * Circuit breaker configuration
- */
+
 export interface CircuitBreakerConfig {
-  /** Number of failures before opening circuit */
+  
   failureThreshold: number;
-  /** Number of successes in half-open to close circuit */
+  
   successThreshold: number;
-  /** Time in ms before attempting half-open */
+  
   resetTimeoutMs: number;
 }
 
-/**
- * Default circuit breaker configuration.
- * Tuned for balance between fault tolerance and quick recovery.
- */
+
 const DEFAULT_CONFIG: CircuitBreakerConfig = {
-  // 3 failures: Quick to detect persistent issues,
-  // but tolerant of occasional transient errors.
   failureThreshold: 3,
 
-  // 2 successes: Requires service to prove stability
-  // before fully resuming (prevents flapping).
   successThreshold: 2,
 
-  // 30s timeout: Allows services time to recover from
-  // rate limits or temporary outages before retrying.
   resetTimeoutMs: 30000,
 };
 
-/**
- * Circuit breaker registry
- */
+
 const circuits = new Map<string, CircuitRecord>();
 const configs = new Map<string, CircuitBreakerConfig>();
 
-/**
- * Get or create circuit breaker for a named service.
- * Enforces MAX_CIRCUITS limit by cleaning up stale circuits when limit is reached.
- */
+
 function getCircuit(name: string): CircuitRecord {
   if (!circuits.has(name)) {
-    // Enforce circuit limit by cleaning up stale circuits
     if (circuits.size >= MAX_CIRCUITS) {
       cleanupStaleCircuits();
-      // If still at limit after cleanup, remove oldest circuit
       if (circuits.size >= MAX_CIRCUITS) {
         const oldestKey = findOldestCircuit();
         if (oldestKey) {
@@ -98,9 +69,7 @@ function getCircuit(name: string): CircuitRecord {
   return circuits.get(name)!;
 }
 
-/**
- * Find the oldest circuit by lastAttempt time
- */
+
 function findOldestCircuit(): string | null {
   let oldest: string | null = null;
   let oldestTime = Infinity;
@@ -115,16 +84,12 @@ function findOldestCircuit(): string | null {
   return oldest;
 }
 
-/**
- * Get configuration for a circuit
- */
+
 function getConfig(name: string): CircuitBreakerConfig {
   return configs.get(name) || DEFAULT_CONFIG;
 }
 
-/**
- * Configure a specific circuit breaker
- */
+
 export function configureCircuit(
   name: string,
   config: Partial<CircuitBreakerConfig>
@@ -132,24 +97,6 @@ export function configureCircuit(
   configs.set(name, { ...DEFAULT_CONFIG, ...config });
 }
 
-/**
- * Execute operation with circuit breaker protection.
- *
- * @param name - Circuit breaker name (e.g., 'lsp', 'github')
- * @param operation - Async operation to execute
- * @param fallback - Optional fallback when circuit is open
- * @returns Operation result or fallback
- * @throws CircuitOpenError if circuit is open and no fallback provided
- *
- * @example
- * ```typescript
- * const result = await withCircuitBreaker(
- *   'lsp',
- *   () => lspGotoDefinition({ queries }),
- *   () => ({ fallback: true, locations: [] })
- * );
- * ```
- */
 export async function withCircuitBreaker<T>(
   name: string,
   operation: () => Promise<T>,
@@ -159,17 +106,13 @@ export async function withCircuitBreaker<T>(
   const config = getConfig(name);
   const now = Date.now();
 
-  // Update last attempt time
   circuit.lastAttempt = now;
 
-  // Check circuit state
   if (circuit.state === 'open') {
-    // Check if we should try half-open
     if (now - circuit.lastFailure > config.resetTimeoutMs) {
       circuit.state = 'half-open';
       console.log(warnLog(`🟡 Circuit ${name} entering half-open state`));
     } else {
-      // Circuit is open - use fallback or throw
       console.log(
         `🔴 Circuit ${name} is OPEN - ${Math.ceil((circuit.lastFailure + config.resetTimeoutMs - now) / 1000)}s until retry`
       );
@@ -183,7 +126,6 @@ export async function withCircuitBreaker<T>(
   try {
     const result = await operation();
 
-    // Success - handle state transition
     if (circuit.state === 'half-open') {
       circuit.successes++;
       if (circuit.successes >= config.successThreshold) {
@@ -193,22 +135,18 @@ export async function withCircuitBreaker<T>(
         console.log(successLog(`🟢 Circuit ${name} CLOSED after recovery`));
       }
     } else {
-      // Reset failures on success in closed state
       circuit.failures = 0;
     }
 
     return result;
   } catch (error) {
-    // Failure - handle state transition
     circuit.failures++;
     circuit.lastFailure = now;
     circuit.successes = 0;
 
     if (circuit.state === 'half-open') {
-      // Failed in half-open - back to open
       circuit.state = 'open';
       console.log(errorLog(`🔴 Circuit ${name} back to OPEN after half-open failure`));
-      // Log rate limit/circuit open event to session telemetry
       fireAndForgetWithTimeout(
         () => logRateLimit({
           limit_type: 'secondary',
@@ -220,12 +158,10 @@ export async function withCircuitBreaker<T>(
         'logRateLimit'
       );
     } else if (circuit.failures >= config.failureThreshold) {
-      // Too many failures - open circuit
       circuit.state = 'open';
       console.log(
         `🔴 Circuit ${name} OPENED after ${circuit.failures} failures`
       );
-      // Log rate limit/circuit open event to session telemetry
       fireAndForgetWithTimeout(
         () => logRateLimit({
           limit_type: 'secondary',
@@ -242,9 +178,7 @@ export async function withCircuitBreaker<T>(
   }
 }
 
-/**
- * Get current state of a circuit breaker
- */
+
 export function getCircuitState(name: string): {
   state: CircuitState;
   failures: number;
@@ -260,9 +194,7 @@ export function getCircuitState(name: string): {
   };
 }
 
-/**
- * Reset a circuit breaker to closed state
- */
+
 export function resetCircuit(name: string): void {
   const circuit = getCircuit(name);
   circuit.state = 'closed';
@@ -272,9 +204,7 @@ export function resetCircuit(name: string): void {
   console.log(agentLog(`🔄 Circuit ${name} manually reset to CLOSED`));
 }
 
-/**
- * Get all circuit states (for health endpoint)
- */
+
 export function getAllCircuitStates(): Record<
   string,
   { state: CircuitState; failures: number; isHealthy: boolean }
@@ -295,9 +225,7 @@ export function getAllCircuitStates(): Record<
   return states;
 }
 
-/**
- * Error thrown when circuit is open
- */
+
 export class CircuitOpenError extends Error {
   readonly circuitName: string;
   readonly retryAfterMs: number;
@@ -310,107 +238,71 @@ export class CircuitOpenError extends Error {
   }
 }
 
-// =============================================================================
-// Pre-configured circuits (per-tool granularity)
-// =============================================================================
 
-// -----------------------------------------------------------------------------
-// GitHub circuits - split by API endpoint (different rate limits)
-// -----------------------------------------------------------------------------
-
-// GitHub Search API - aggressive rate limiting (30 req/min)
 configureCircuit('github:search', {
-  failureThreshold: 2,     // 2 failures = likely rate limited
-  successThreshold: 1,     // Single success proves API recovered
-  resetTimeoutMs: 60000,   // 60s: Give search rate limits time to reset
+  failureThreshold: 2,
+  successThreshold: 1,
+  resetTimeoutMs: 60000,
 });
 
-// GitHub Content API - higher limits, separate quota
 configureCircuit('github:content', {
-  failureThreshold: 3,     // 3 failures = more tolerant
+  failureThreshold: 3,
   successThreshold: 1,
-  resetTimeoutMs: 30000,   // 30s: Content API recovers faster
+  resetTimeoutMs: 30000,
 });
 
-// GitHub PR API - separate quota from search
 configureCircuit('github:pulls', {
-  failureThreshold: 2,     // 2 failures = likely rate limited
+  failureThreshold: 2,
   successThreshold: 1,
-  resetTimeoutMs: 60000,   // 60s: PR API has similar limits to search
+  resetTimeoutMs: 60000,
 });
 
-// Legacy fallback for any uncategorized github tools
 configureCircuit('github', {
   failureThreshold: 2,
   successThreshold: 1,
   resetTimeoutMs: 60000,
 });
 
-// -----------------------------------------------------------------------------
-// LSP circuits - split by operation weight
-// -----------------------------------------------------------------------------
-
-// LSP Navigation (definition, references) - fast, single lookup
 configureCircuit('lsp:navigation', {
-  failureThreshold: 3,     // 3 failures = likely LSP issue
-  successThreshold: 1,     // Single success proves LSP recovered
-  resetTimeoutMs: 10000,   // 10s: Quick recovery expected
+  failureThreshold: 3,
+  successThreshold: 1,
+  resetTimeoutMs: 10000,
 });
 
-// LSP Call Hierarchy - heavier recursive operation
 configureCircuit('lsp:hierarchy', {
-  failureThreshold: 2,     // 2 failures = operation too heavy or LSP struggling
+  failureThreshold: 2,
   successThreshold: 1,
-  resetTimeoutMs: 15000,   // 15s: Slightly longer for heavy ops
+  resetTimeoutMs: 15000,
 });
 
-// Legacy fallback
 configureCircuit('lsp', {
   failureThreshold: 3,
   successThreshold: 1,
   resetTimeoutMs: 10000,
 });
 
-// -----------------------------------------------------------------------------
-// Local circuits - unified (same failure mode: filesystem)
-// -----------------------------------------------------------------------------
-
 configureCircuit('local', {
-  failureThreshold: 5,     // 5 failures = likely persistent issue
-  successThreshold: 1,     // Single success proves local ops recovered
-  resetTimeoutMs: 5000,    // 5s: Local ops should recover quickly
+  failureThreshold: 5,
+  successThreshold: 1,
+  resetTimeoutMs: 5000,
 });
 
-// -----------------------------------------------------------------------------
-// Package circuits - unified (npm/PyPI)
-// -----------------------------------------------------------------------------
-
 configureCircuit('package', {
-  failureThreshold: 3,     // 3 failures = likely rate limited or down
-  successThreshold: 1,     // Single success proves API recovered
-  resetTimeoutMs: 45000,   // 45s: Slightly faster than GitHub
+  failureThreshold: 3,
+  successThreshold: 1,
+  resetTimeoutMs: 45000,
 });
 
-// =============================================================================
-// Automatic Cleanup (Memory Leak Prevention)
-// =============================================================================
 
-/**
- * Cleanup interval reference (for graceful shutdown)
- */
 let cleanupIntervalId: ReturnType<typeof setInterval> | null = null;
 
-/**
- * Remove stale circuits that haven't been used recently.
- * A circuit is stale if it hasn't been attempted in CIRCUIT_TTL_MS.
- */
+
 function cleanupStaleCircuits(): void {
   const now = Date.now();
   const staleCutoff = now - CIRCUIT_TTL_MS;
   let removedCount = 0;
 
   for (const [name, circuit] of circuits) {
-    // Don't remove circuits that are currently open (still tracking failure)
     if (circuit.state !== 'open' && circuit.lastAttempt < staleCutoff) {
       circuits.delete(name);
       configs.delete(name);
@@ -423,27 +315,20 @@ function cleanupStaleCircuits(): void {
   }
 }
 
-/**
- * Start the periodic cleanup interval.
- * Called automatically on module load.
- */
+
 function startPeriodicCleanup(): void {
-  if (cleanupIntervalId) return; // Already running
+  if (cleanupIntervalId) return;
 
   cleanupIntervalId = setInterval(() => {
     cleanupStaleCircuits();
   }, CLEANUP_INTERVAL_MS);
 
-  // Unref the interval so it doesn't prevent process exit
   if (cleanupIntervalId.unref) {
     cleanupIntervalId.unref();
   }
 }
 
-/**
- * Stop the periodic cleanup interval.
- * Call during graceful shutdown.
- */
+
 export function stopCircuitCleanup(): void {
   if (cleanupIntervalId) {
     clearInterval(cleanupIntervalId);
@@ -451,17 +336,9 @@ export function stopCircuitCleanup(): void {
   }
 }
 
-// Start periodic cleanup on module load
 startPeriodicCleanup();
 
-// =============================================================================
-// Manual Cleanup Functions
-// =============================================================================
 
-/**
- * Clear all circuit breakers.
- * Use for testing cleanup or server shutdown.
- */
 export function clearAllCircuits(): void {
   const count = circuits.size;
   circuits.clear();

package/skills/octocode-research/src/utils/colors.ts

@@ -1,33 +1,19 @@
-/**
- * ANSI color codes for terminal output
- * 
- * Color scheme:
- * - AGENT (purple): Server/agent messages, startup, shutdown
- * - RESULT (blue): Tool output, skill results
- */
-
 const colors = {
-  // Reset
   reset: '\x1b[0m',
   
-  // Agent messages - Purple/Magenta
   agent: '\x1b[35m',
   agentBright: '\x1b[95m',
   
-  // Results/Tool output - Blue
   result: '\x1b[34m',
   resultBright: '\x1b[94m',
   
-  // Status colors
-  success: '\x1b[32m',  // Green
-  error: '\x1b[31m',    // Red
-  warn: '\x1b[33m',     // Yellow
+  success: '\x1b[32m',
+  error: '\x1b[31m',
+  warn: '\x1b[33m',
   
-  // Dim for secondary info
   dim: '\x1b[2m',
 };
 
-// Helper functions for consistent formatting
 export function agentLog(message: string): string {
   return `${colors.agentBright}${message}${colors.reset}`;
 }