octocode-cli 1.2.6 → 1.2.7

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

@@ -0,0 +1,100 @@
+/**
+ * Response utilities for route handlers.
+ * Provides type-safe extractors and helpers for processing MCP responses.
+ *
+ * @module utils/responseFactory
+ */
+
+import type { FileMatch, PaginationInfo } from '../types/responses.js';
+import { extractFiles, extractPagination, extractTotalMatches } from '../types/responses.js';
+import { isObject, hasProperty, isArray, hasStringProperty, hasNumberProperty } from '../types/guards.js';
+
+// =============================================================================
+// Common Extractors (Type-Safe)
+// =============================================================================
+
+/**
+ * Extract file matches from search results with proper typing
+ */
+export function extractFileMatches(data: unknown): FileMatch[] {
+  return extractFiles(data);
+}
+
+/**
+ * Extract pagination info with proper typing
+ */
+export function extractPaginationInfo(data: unknown): PaginationInfo | undefined {
+  return extractPagination(data);
+}
+
+/**
+ * Extract total match count with proper typing
+ */
+export function extractMatchCount(data: unknown): number {
+  return extractTotalMatches(data);
+}
+
+/**
+ * Safely extract string property
+ */
+export function safeString(obj: unknown, key: string, fallback = ''): string {
+  if (hasStringProperty(obj, key)) {
+    return obj[key];
+  }
+  return fallback;
+}
+
+/**
+ * Safely extract number property
+ */
+export function safeNumber(obj: unknown, key: string, fallback = 0): number {
+  if (hasNumberProperty(obj, key)) {
+    return obj[key];
+  }
+  return fallback;
+}
+
+/**
+ * Safely extract array property
+ */
+export function safeArray<T>(obj: unknown, key: string): T[] {
+  if (isObject(obj) && hasProperty(obj, key) && isArray(obj[key])) {
+    return obj[key] as T[];
+  }
+  return [];
+}
+
+/**
+ * Extract match locations from a file result
+ */
+export function extractMatchLocations(matches: unknown[]): Array<{
+  line: number;
+  column?: number;
+  value?: string;
+  byteOffset?: number;
+  charOffset?: number;
+}> {
+  return matches.map((m) => {
+    if (!isObject(m)) return { line: 0 };
+    return {
+      line: safeNumber(m, 'line', 0),
+      column: hasNumberProperty(m, 'column') ? m.column : undefined,
+      value: hasStringProperty(m, 'value') ? m.value.trim() : undefined,
+      byteOffset: hasNumberProperty(m, 'byteOffset') ? m.byteOffset : undefined,
+      charOffset: hasNumberProperty(m, 'charOffset') ? m.charOffset : undefined,
+    };
+  });
+}
+
+/**
+ * Transform pagination from MCP format to skill format
+ */
+export function transformPagination(pagination: unknown): { page: number; total: number; hasMore: boolean } | undefined {
+  if (!isObject(pagination)) return undefined;
+  
+  const currentPage = safeNumber(pagination, 'currentPage', 1);
+  const totalPages = safeNumber(pagination, 'totalPages', 1);
+  const hasMore = hasProperty(pagination, 'hasMore') && pagination.hasMore === true;
+  
+  return { page: currentPage, total: totalPages, hasMore };
+}

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

@@ -0,0 +1,272 @@
+/**
+ * Parse MCP tool responses to extract structured data
+ *
+ * MCP tools return responses in this format:
+ * {
+ *   content: [{ type: 'text', text: yamlString }],
+ *   structuredContent?: object,  // Not always present
+ *   isError: boolean
+ * }
+ *
+ * The YAML contains:
+ * - instructions: string
+ * - results: [{ id, status, data, mainResearchGoal, researchGoal, reasoning }]
+ * - hasResultsStatusHints / emptyStatusHints / errorStatusHints: string[]
+ *
+ * This utility extracts data AND preserves the valuable MCP hints.
+ */
+
+import yaml from 'js-yaml';
+
+interface McpToolResponse {
+  content?: Array<{ type: string; text?: string }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+}
+
+/**
+ * Research context from the MCP response
+ */
+export interface ResearchContext {
+  mainResearchGoal?: string;
+  researchGoal?: string;
+  reasoning?: string;
+}
+
+/**
+ * Single result item from bulk response
+ */
+export interface BulkResultItem {
+  id: number;
+  status: 'hasResults' | 'empty' | 'error';
+  data: Record<string, unknown>;
+  research: ResearchContext;
+}
+
+/**
+ * Parsed response with data, hints, and research context
+ */
+export interface ParsedResponse {
+  data: Record<string, unknown>;
+  isError: boolean;
+  /** MCP workflow hints - critical for agent guidance */
+  hints: string[];
+  /** Research context preserved from the query */
+  research: ResearchContext;
+  /** Raw status from MCP (hasResults, empty, error) */
+  status: 'hasResults' | 'empty' | 'error' | 'unknown';
+}
+
+/**
+ * Parsed bulk response with all results
+ */
+export interface ParsedBulkResponse {
+  /** All results from bulk query */
+  results: BulkResultItem[];
+  /** Categorized hints by status */
+  hints: {
+    hasResults: string[];
+    empty: string[];
+    error: string[];
+  };
+  /** Bulk operation instructions */
+  instructions: string;
+  /** True if all queries failed */
+  isError: boolean;
+  /** Count of results by status */
+  counts: {
+    total: number;
+    hasResults: number;
+    empty: number;
+    error: number;
+  };
+}
+
+/**
+ * Extract structured data from an MCP tool response
+ *
+ * Priority:
+ * 1. Use structuredContent if available (direct object access)
+ * 2. Parse YAML from content[0].text and extract results[0].data
+ *
+ * Also extracts:
+ * - MCP hints (hasResultsStatusHints, emptyStatusHints, errorStatusHints)
+ * - Research context (mainResearchGoal, researchGoal, reasoning)
+ */
+export function parseToolResponse(response: McpToolResponse): ParsedResponse {
+  const emptyResult: ParsedResponse = {
+    data: {},
+    isError: true,
+    hints: [],
+    research: {},
+    status: 'unknown',
+  };
+
+  // Option 1: structuredContent is available (preferred for data, but no hints)
+  if (response.structuredContent && typeof response.structuredContent === 'object') {
+    return {
+      data: response.structuredContent,
+      isError: Boolean(response.isError),
+      hints: [], // structuredContent doesn't include hints
+      research: {},
+      status: 'unknown',
+    };
+  }
+
+  // Option 2: Parse YAML from content text (includes hints!)
+  if (response.content && response.content[0]?.text) {
+    try {
+      const parsed = yaml.load(response.content[0].text) as Record<string, unknown>;
+
+      // Extract hints based on status
+      let hints: string[] = [];
+      if (Array.isArray(parsed.hasResultsStatusHints)) {
+        hints = parsed.hasResultsStatusHints as string[];
+      } else if (Array.isArray(parsed.emptyStatusHints)) {
+        hints = parsed.emptyStatusHints as string[];
+      } else if (Array.isArray(parsed.errorStatusHints)) {
+        hints = parsed.errorStatusHints as string[];
+      }
+
+      // Extract data from results[0].data (bulk response format)
+      if (parsed && Array.isArray(parsed.results) && parsed.results.length > 0) {
+        const firstResult = parsed.results[0] as Record<string, unknown>;
+        const resultStatus = String(firstResult.status || 'unknown');
+
+        // Extract research context
+        const research: ResearchContext = {
+          mainResearchGoal: typeof firstResult.mainResearchGoal === 'string'
+            ? firstResult.mainResearchGoal : undefined,
+          researchGoal: typeof firstResult.researchGoal === 'string'
+            ? firstResult.researchGoal : undefined,
+          reasoning: typeof firstResult.reasoning === 'string'
+            ? firstResult.reasoning : undefined,
+        };
+
+        if (firstResult.data && typeof firstResult.data === 'object') {
+          return {
+            data: firstResult.data as Record<string, unknown>,
+            isError: resultStatus === 'error',
+            hints,
+            research,
+            status: resultStatus as ParsedResponse['status'],
+          };
+        }
+      }
+
+      // Fallback: return parsed object directly
+      return {
+        data: parsed || {},
+        isError: Boolean(response.isError),
+        hints,
+        research: {},
+        status: 'unknown',
+      };
+    } catch {
+      // YAML parsing failed, return empty
+      return emptyResult;
+    }
+  }
+
+  // No data found
+  return emptyResult;
+}
+
+/**
+ * Convenience function to get data field with type safety
+ */
+export function getDataField<T>(
+  response: McpToolResponse,
+  field: string,
+  defaultValue: T
+): T {
+  const { data } = parseToolResponse(response);
+  const value = data[field];
+  return value !== undefined ? (value as T) : defaultValue;
+}
+
+/**
+ * Parse ALL results from a bulk MCP tool response.
+ * Use this when handling multiple queries to get all results.
+ *
+ * @param response - Raw MCP tool response
+ * @returns ParsedBulkResponse with all results and categorized hints
+ */
+export function parseToolResponseBulk(response: McpToolResponse): ParsedBulkResponse {
+  const emptyResult: ParsedBulkResponse = {
+    results: [],
+    hints: { hasResults: [], empty: [], error: [] },
+    instructions: '',
+    isError: true,
+    counts: { total: 0, hasResults: 0, empty: 0, error: 0 },
+  };
+
+  // Parse YAML from content text
+  if (!response.content || !response.content[0]?.text) {
+    return emptyResult;
+  }
+
+  try {
+    const parsed = yaml.load(response.content[0].text) as Record<string, unknown>;
+
+    if (!parsed || !Array.isArray(parsed.results)) {
+      return emptyResult;
+    }
+
+    // Extract all results
+    const results: BulkResultItem[] = [];
+    let hasResultsCount = 0;
+    let emptyCount = 0;
+    let errorCount = 0;
+
+    for (const result of parsed.results) {
+      if (!result || typeof result !== 'object') continue;
+
+      const r = result as Record<string, unknown>;
+      const status = String(r.status || 'unknown') as BulkResultItem['status'];
+
+      if (status === 'hasResults') hasResultsCount++;
+      else if (status === 'empty') emptyCount++;
+      else if (status === 'error') errorCount++;
+
+      results.push({
+        id: typeof r.id === 'number' ? r.id : results.length + 1,
+        status,
+        data: (r.data && typeof r.data === 'object' ? r.data : {}) as Record<string, unknown>,
+        research: {
+          mainResearchGoal: typeof r.mainResearchGoal === 'string' ? r.mainResearchGoal : undefined,
+          researchGoal: typeof r.researchGoal === 'string' ? r.researchGoal : undefined,
+          reasoning: typeof r.reasoning === 'string' ? r.reasoning : undefined,
+        },
+      });
+    }
+
+    // Extract categorized hints
+    const hints = {
+      hasResults: Array.isArray(parsed.hasResultsStatusHints)
+        ? (parsed.hasResultsStatusHints as string[])
+        : [],
+      empty: Array.isArray(parsed.emptyStatusHints)
+        ? (parsed.emptyStatusHints as string[])
+        : [],
+      error: Array.isArray(parsed.errorStatusHints)
+        ? (parsed.errorStatusHints as string[])
+        : [],
+    };
+
+    return {
+      results,
+      hints,
+      instructions: typeof parsed.instructions === 'string' ? parsed.instructions : '',
+      isError: errorCount === results.length && results.length > 0,
+      counts: {
+        total: results.length,
+        hasResults: hasResultsCount,
+        empty: emptyCount,
+        error: errorCount,
+      },
+    };
+  } catch {
+    return emptyResult;
+  }
+}

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

@@ -0,0 +1,280 @@
+/**
+ * Retry utilities with exponential backoff for resilient tool calls.
+ *
+ * @module utils/retry
+ */
+
+import {
+  getErrorStatus,
+  getErrorHeader,
+  hasStatusIn,
+  hasCodeIn,
+  messageMatches,
+} from '../types/errorGuards.js';
+
+export interface RetryConfig {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+  retryOn: (error: unknown) => boolean;
+}
+
+/**
+ * Pre-configured retry strategies for different tool categories
+ */
+export const RETRY_CONFIGS = {
+  /**
+   * LSP tools - may need warm-up time
+   */
+  lsp: {
+    maxAttempts: 3,
+    initialDelayMs: 500,
+    maxDelayMs: 5000,
+    backoffMultiplier: 2,
+    retryOn: (err: unknown) =>
+      isLspNotReady(err) || isTimeout(err) || isConnectionRefused(err),
+  },
+
+  /**
+   * GitHub API - rate limits and server errors
+   */
+  github: {
+    maxAttempts: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 3,
+    retryOn: (err: unknown) =>
+      isRateLimited(err) || isServerError(err) || isTimeout(err),
+  },
+
+  /**
+   * Package APIs (npm/PyPI) - similar to GitHub
+   */
+  package: {
+    maxAttempts: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 15000,
+    backoffMultiplier: 2,
+    retryOn: (err: unknown) =>
+      isRateLimited(err) || isServerError(err) || isTimeout(err),
+  },
+
+  /**
+   * Local file operations - quick retries
+   */
+  local: {
+    maxAttempts: 2,
+    initialDelayMs: 100,
+    maxDelayMs: 1000,
+    backoffMultiplier: 2,
+    retryOn: (err: unknown) => isFileBusy(err) || isTimeout(err),
+  },
+} as const satisfies Record<string, RetryConfig>;
+
+type RetryCategory = keyof typeof RETRY_CONFIGS;
+
+/**
+ * Context for retry logging
+ */
+interface RetryContext {
+  tool: string;
+  params?: unknown;
+}
+
+/**
+ * Execute an operation with retry logic and exponential backoff.
+ *
+ * @param operation - Async function to execute
+ * @param config - Retry configuration
+ * @param context - Optional context for logging
+ * @returns Result of the operation
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => lspGotoDefinition({ queries }),
+ *   RETRY_CONFIGS.lsp,
+ *   { tool: 'lspGotoDefinition' }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  config: RetryConfig,
+  context?: RetryContext
+): Promise<T> {
+  let lastError: unknown;
+  let delay = config.initialDelayMs;
+
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      // Don't retry if error type doesn't match or last attempt
+      if (!config.retryOn(error) || attempt === config.maxAttempts) {
+        throw error;
+      }
+
+      // Log retry attempt
+      const toolName = context?.tool || 'operation';
+      console.log(
+        `⟳ Retry ${attempt}/${config.maxAttempts} for ${toolName} in ${delay}ms`
+      );
+
+      await sleep(delay);
+      delay = Math.min(delay * config.backoffMultiplier, config.maxDelayMs);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Convenience wrapper that selects config by category
+ */
+export async function withCategoryRetry<T>(
+  category: RetryCategory,
+  operation: () => Promise<T>,
+  context?: RetryContext
+): Promise<T> {
+  return withRetry(operation, RETRY_CONFIGS[category], context);
+}
+
+// =============================================================================
+// Error Type Detection
+// =============================================================================
+
+// Error codes for reliable detection (check these first)
+const RATE_LIMIT_CODES = [403, 429] as const;
+const RATE_LIMIT_PATTERNS = [/rate\s*limit/i, /too\s*many\s*requests/i] as const;
+
+const LSP_ERROR_CODES = ['LSP_NOT_READY', 'LSP_NOT_INITIALIZED', 'ECONNREFUSED'] as const;
+const LSP_ERROR_PATTERNS = [/not initialized/i, /server not started/i, /lsp.*not.*ready/i] as const;
+
+const TIMEOUT_CODES = ['ETIMEDOUT', 'ESOCKETTIMEDOUT', 'ECONNRESET'] as const;
+const TIMEOUT_PATTERNS = [/timeout/i, /timed?\s*out/i] as const;
+
+const FILE_BUSY_CODES = ['EBUSY', 'EAGAIN', 'ENOTEMPTY'] as const;
+
+const CONNECTION_REFUSED_CODES = ['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH'] as const;
+
+const SYMBOL_NOT_FOUND_CODES = ['SYMBOL_NOT_FOUND', 'NOT_FOUND'] as const;
+const SYMBOL_NOT_FOUND_PATTERNS = [/symbol\s*not\s*found/i, /definition\s*not\s*found/i] as const;
+
+/**
+ * Check if error indicates GitHub rate limiting
+ */
+function isRateLimited(err: unknown): boolean {
+  // Check status codes first (more reliable)
+  if (hasStatusIn(err, RATE_LIMIT_CODES)) {
+    return true;
+  }
+
+  // Fall back to message patterns
+  return messageMatches(err, RATE_LIMIT_PATTERNS);
+}
+
+/**
+ * Check if error indicates LSP server not ready
+ */
+function isLspNotReady(err: unknown): boolean {
+  // Check error codes first (more reliable)
+  if (hasCodeIn(err, LSP_ERROR_CODES)) {
+    return true;
+  }
+
+  // Fall back to message patterns
+  return messageMatches(err, LSP_ERROR_PATTERNS);
+}
+
+/**
+ * Check if error is a timeout
+ */
+function isTimeout(err: unknown): boolean {
+  // Check error codes first (more reliable)
+  if (hasCodeIn(err, TIMEOUT_CODES)) {
+    return true;
+  }
+
+  // Fall back to message patterns
+  return messageMatches(err, TIMEOUT_PATTERNS);
+}
+
+/**
+ * Check if error is a server error (5xx)
+ */
+function isServerError(err: unknown): boolean {
+  const status = getErrorStatus(err);
+  return status !== undefined && status >= 500 && status < 600;
+}
+
+/**
+ * Check if file is busy/locked
+ */
+function isFileBusy(err: unknown): boolean {
+  return hasCodeIn(err, FILE_BUSY_CODES);
+}
+
+/**
+ * Check if connection was refused
+ */
+function isConnectionRefused(err: unknown): boolean {
+  return hasCodeIn(err, CONNECTION_REFUSED_CODES);
+}
+
+/**
+ * Check if symbol was not found (LSP)
+ */
+export function isSymbolNotFound(err: unknown): boolean {
+  // Check error codes first (more reliable)
+  if (hasCodeIn(err, SYMBOL_NOT_FOUND_CODES)) {
+    return true;
+  }
+
+  // Fall back to message patterns
+  return messageMatches(err, SYMBOL_NOT_FOUND_PATTERNS);
+}
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Get suggested retry delay from error (if available)
+ */
+export function getRetryAfter(err: unknown): number | null {
+  if (isRateLimited(err)) {
+    const retryAfter = getErrorHeader(err, 'retry-after');
+    if (retryAfter) {
+      return parseInt(retryAfter, 10) * 1000;
+    }
+    return 60000; // Default 60s for rate limits
+  }
+
+  if (isLspNotReady(err)) {
+    return 3000; // 3s for LSP warm-up
+  }
+
+  return null;
+}
+
+/**
+ * Determine if an error is recoverable
+ */
+export function isRecoverable(err: unknown): boolean {
+  return (
+    isRateLimited(err) ||
+    isLspNotReady(err) ||
+    isTimeout(err) ||
+    isServerError(err) ||
+    isFileBusy(err) ||
+    isConnectionRefused(err)
+  );
+}