octocode-cli 1.5.1 → 1.5.3

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

@@ -1,29 +1,12 @@
-/**
- * Research-specific response builders for octocode-research skill.
- *
- * Provides high-level response helpers that wrap the MCP role-based response API
- * with research-specific patterns and formatting.
- *
- * NOTE: The MCP tools already provide rich reasoning context via:
- * - mainResearchGoal, researchGoal, reasoning in each result
- * - hasResultsStatusHints, emptyStatusHints, errorStatusHints for guidance
- * - Dynamic per-tool hints based on context
- *
- * This module focuses on formatting and presentation, NOT duplicating reasoning.
- */
-
 import {
   createRoleBasedResult,
   QuickResult,
   StatusEmoji,
 } from 'octocode-mcp/public';
 
-// CallToolResult type from MCP SDK (re-exported via octocode-mcp)
 type CallToolResult = ReturnType<typeof createRoleBasedResult>;
 
-/**
- * Pagination info for paginated responses
- */
+
 interface PaginationInfo {
   page: number;
   total: number;
@@ -32,9 +15,7 @@ interface PaginationInfo {
   totalItems?: number;
 }
 
-/**
- * Detailed match location info (preserved from MCP response)
- */
+
 interface MatchLocation {
   line: number;
   column?: number;
@@ -43,49 +24,40 @@ interface MatchLocation {
   charOffset?: number;
 }
 
-/**
- * File match info for search results
- */
+
 interface FileMatch {
   path: string;
   matches?: number;
   line?: number;
   preview?: string;
   repo?: string;
-  /** All match locations - preserved from MCP for detailed analysis */
+  
   allMatches?: MatchLocation[];
 }
 
-/**
- * Research context from MCP response
- */
+
 interface ResearchContext {
   mainResearchGoal?: string;
   researchGoal?: string;
   reasoning?: string;
 }
 
-/**
- * Research-specific response builders
- */
+
 export const ResearchResponse = {
-  /**
-   * Search results with navigation hints
-   */
+  
   searchResults(results: {
     files: FileMatch[];
     totalMatches: number;
     pagination?: PaginationInfo;
     searchPattern?: string;
     isLocal?: boolean;
-    /** MCP workflow hints - passed through from tool response */
+    
     mcpHints?: string[];
-    /** Research context - preserved from the query */
+    
     research?: ResearchContext;
   }): CallToolResult {
     const { files, totalMatches, pagination, searchPattern, mcpHints = [] } = results;
 
-    // Build summary
     const patternInfo = searchPattern ? ` for "${searchPattern}"` : '';
     const summary =
       files.length > 0
@@ -100,7 +72,6 @@ export const ResearchResponse = {
           (files.length > 10 ? `\n... and ${files.length - 10} more files` : '')
         : `No matches found${patternInfo}`;
 
-    // Build hints - start with MCP hints, add pagination info
     const hints: string[] = [...mcpHints];
     if (files.length > 10) {
       hints.push(`Showing 10 of ${files.length} files`);
@@ -109,9 +80,7 @@ export const ResearchResponse = {
       hints.push(`Next page: page=${pagination.page + 1}`);
     }
 
-    // Return appropriate response type
     if (files.length === 0) {
-      // For empty results, MCP already provides relevant hints
       const emptyHints = mcpHints.length > 0 ? mcpHints : [
         'Try broader search terms',
         'Check spelling and case sensitivity',
@@ -127,9 +96,7 @@ export const ResearchResponse = {
     return QuickResult.success(summary, results, hints);
   },
 
-  /**
-   * File content with context
-   */
+  
   fileContent(result: {
     path: string;
     content: string;
@@ -137,9 +104,9 @@ export const ResearchResponse = {
     language?: string;
     totalLines?: number;
     isPartial?: boolean;
-    /** MCP workflow hints - passed through from tool response */
+    
     mcpHints?: string[];
-    /** Research context - preserved from the query */
+    
     research?: ResearchContext;
   }): CallToolResult {
     const { path, content, lines, language, totalLines, isPartial, mcpHints = [] } = result;
@@ -147,10 +114,8 @@ export const ResearchResponse = {
     const lineInfo = lines ? ` (lines ${lines.start}-${lines.end})` : '';
     const lang = language || detectLanguage(path);
 
-    // Format content with code fence
     const formattedContent = `📄 ${path}${lineInfo}\n\n\`\`\`${lang}\n${content}\n\`\`\``;
 
-    // Build hints - start with MCP hints, add contextual info
     const hints: string[] = [...mcpHints];
     hints.push('Content retrieved successfully');
     if (lines) {
@@ -169,16 +134,14 @@ export const ResearchResponse = {
     });
   },
 
-  /**
-   * LSP definition/reference/call hierarchy results
-   */
+  
   lspResult(result: {
     symbol: string;
     locations: Array<{ uri: string; line: number; preview?: string }>;
     type: 'definition' | 'references' | 'calls' | 'incoming' | 'outgoing';
-    /** MCP workflow hints - passed through from tool response */
+    
     mcpHints?: string[];
-    /** Research context - preserved from the query */
+    
     research?: ResearchContext;
   }): CallToolResult {
     const { symbol, locations, type, mcpHints = [] } = result;
@@ -212,7 +175,6 @@ export const ResearchResponse = {
             .join('\n')
         : `No ${type} found for "${symbol}"`;
 
-    // Build hints - start with MCP hints, add contextual info
     const hints: string[] = [...mcpHints];
     if (locations.length > 0) {
       hints.push('Use returned line numbers for further navigation');
@@ -235,9 +197,7 @@ export const ResearchResponse = {
     });
   },
 
-  /**
-   * Repository structure view
-   */
+  
   repoStructure(result: {
     path: string;
     structure: { files: string[]; folders: string[] };
@@ -246,9 +206,9 @@ export const ResearchResponse = {
     totalFolders?: number;
     owner?: string;
     repo?: string;
-    /** MCP workflow hints - passed through from tool response */
+    
     mcpHints?: string[];
-    /** Research context - preserved from the query */
+    
     research?: ResearchContext;
   }): CallToolResult {
     const { path, structure, depth, totalFiles, totalFolders, owner, repo, mcpHints = [] } =
@@ -269,7 +229,6 @@ export const ResearchResponse = {
         ? `Files:\n${fileList.map(f => `  📄 ${f}`).join('\n')}`
         : 'No files in this directory');
 
-    // Build hints - start with MCP hints, add contextual info
     const hints: string[] = [...mcpHints];
     if (depth === 1) {
       hints.push('Use depth=2 to see nested contents');
@@ -301,9 +260,7 @@ export const ResearchResponse = {
     });
   },
 
-  /**
-   * Package search results
-   */
+  
   packageSearch(result: {
     packages: Array<{
       name: string;
@@ -313,9 +270,9 @@ export const ResearchResponse = {
     }>;
     registry: 'npm' | 'pypi';
     query?: string;
-    /** MCP workflow hints - passed through from tool response */
+    
     mcpHints?: string[];
-    /** Research context - preserved from the query */
+    
     research?: ResearchContext;
   }): CallToolResult {
     const { packages, registry, query, mcpHints = [] } = result;
@@ -333,7 +290,6 @@ export const ResearchResponse = {
             .join('\n')
         : `No packages found${queryInfo} on ${registry.toUpperCase()}`;
 
-    // Build hints - start with MCP hints, add contextual info
     const hints: string[] = [...mcpHints];
     if (packages.length > 0) {
       hints.push('Use repository URL with githubViewRepoStructure to explore source');
@@ -350,9 +306,7 @@ export const ResearchResponse = {
     return QuickResult.success(summary, result, hints);
   },
 
-  /**
-   * Pull request search results
-   */
+  
   pullRequests(result: {
     prs: Array<{
       number: number;
@@ -363,9 +317,9 @@ export const ResearchResponse = {
     }>;
     repo?: string;
     pagination?: PaginationInfo;
-    /** MCP workflow hints - passed through from tool response */
+    
     mcpHints?: string[];
-    /** Research context - preserved from the query */
+    
     research?: ResearchContext;
   }): CallToolResult {
     const { prs, repo, pagination, mcpHints = [] } = result;
@@ -383,7 +337,6 @@ export const ResearchResponse = {
             .join('\n')
         : `No pull requests found${repoInfo}`;
 
-    // Build hints - start with MCP hints, add contextual info
     const hints: string[] = [...mcpHints];
     if (prs.length > 0) {
       hints.push('Use prNumber with type="fullContent" to see full diff');
@@ -404,9 +357,7 @@ export const ResearchResponse = {
     return QuickResult.success(summary, result, hints);
   },
 
-  /**
-   * Generic bulk operation result
-   */
+  
   bulkResult(result: {
     results: Array<{ status: string; data?: unknown; error?: string }>;
     operation: string;
@@ -452,9 +403,7 @@ export const ResearchResponse = {
   },
 };
 
-/**
- * Detect language from file extension
- */
+
 function detectLanguage(path: string): string {
   const ext = path.split('.').pop()?.toLowerCase() || '';
   const langMap: Record<string, string> = {
@@ -491,5 +440,4 @@ function detectLanguage(path: string): string {
   return langMap[ext] || '';
 }
 
-// Re-export utilities for convenience
 export { QuickResult, detectLanguage as detectLanguageFromPath };

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

@@ -1,10 +1,3 @@
-/**
- * Response utilities for route handlers.
- * Provides type-safe extractors and helpers for processing MCP responses.
- *
- * @module utils/responseFactory
- */
-
 import { isObject, hasProperty, isArray, hasStringProperty, hasNumberProperty } from '../types/guards.js';
 
 export function safeString(obj: unknown, key: string, fallback = ''): string {

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

@@ -1,21 +1,3 @@
-/**
- * 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 {
@@ -37,34 +19,32 @@ interface BulkResultItem {
   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';
 }
 
 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;
@@ -73,17 +53,7 @@ interface ParsedBulkResponse {
   };
 }
 
-/**
- * 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: {},
@@ -93,23 +63,20 @@ export function parseToolResponse(response: McpToolResponse): ParsedResponse {
     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
+      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[];
@@ -119,12 +86,10 @@ export function parseToolResponse(response: McpToolResponse): ParsedResponse {
         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,
@@ -145,7 +110,6 @@ export function parseToolResponse(response: McpToolResponse): ParsedResponse {
         }
       }
 
-      // Fallback: return parsed object directly
       return {
         data: parsed || {},
         isError: Boolean(response.isError),
@@ -154,22 +118,13 @@ export function parseToolResponse(response: McpToolResponse): ParsedResponse {
         status: 'unknown',
       };
     } catch {
-      // YAML parsing failed, return empty
       return emptyResult;
     }
   }
 
-  // No data found
   return emptyResult;
 }
 
-/**
- * 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: [],
@@ -179,7 +134,6 @@ export function parseToolResponseBulk(response: McpToolResponse): ParsedBulkResp
     counts: { total: 0, hasResults: 0, empty: 0, error: 0 },
   };
 
-  // Parse YAML from content text
   if (!response.content || !response.content[0]?.text) {
     return emptyResult;
   }
@@ -191,7 +145,6 @@ export function parseToolResponseBulk(response: McpToolResponse): ParsedBulkResp
       return emptyResult;
     }
 
-    // Extract all results
     const results: BulkResultItem[] = [];
     let hasResultsCount = 0;
     let emptyCount = 0;
@@ -219,7 +172,6 @@ export function parseToolResponseBulk(response: McpToolResponse): ParsedBulkResp
       });
     }
 
-    // Extract categorized hints
     const hints = {
       hasResults: Array.isArray(parsed.hasResultsStatusHints)
         ? (parsed.hasResultsStatusHints as string[])

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

@@ -1,9 +1,3 @@
-/**
- * Retry utilities with exponential backoff for resilient tool calls.
- *
- * @module utils/retry
- */
-
 import {
   getErrorStatus,
   hasStatusIn,
@@ -19,13 +13,9 @@ export interface RetryConfig {
   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,
@@ -35,9 +25,7 @@ export const RETRY_CONFIGS = {
       isLspNotReady(err) || isTimeout(err) || isConnectionRefused(err),
   },
 
-  /**
-   * GitHub API - rate limits and server errors
-   */
+  
   github: {
     maxAttempts: 3,
     initialDelayMs: 1000,
@@ -47,9 +35,7 @@ export const RETRY_CONFIGS = {
       isRateLimited(err) || isServerError(err) || isTimeout(err),
   },
 
-  /**
-   * Package APIs (npm/PyPI) - similar to GitHub
-   */
+  
   package: {
     maxAttempts: 3,
     initialDelayMs: 1000,
@@ -59,9 +45,7 @@ export const RETRY_CONFIGS = {
       isRateLimited(err) || isServerError(err) || isTimeout(err),
   },
 
-  /**
-   * Local file operations - quick retries
-   */
+  
   local: {
     maxAttempts: 2,
     initialDelayMs: 100,
@@ -71,32 +55,12 @@ export const RETRY_CONFIGS = {
   },
 } as const satisfies Record<string, RetryConfig>;
 
-/**
- * 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,
@@ -111,12 +75,10 @@ export async function withRetry<T>(
     } 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`
@@ -130,11 +92,7 @@ export async function withRetry<T>(
   throw lastError;
 }
 
-// =============================================================================
-// 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;
 
@@ -148,70 +106,49 @@ const FILE_BUSY_CODES = ['EBUSY', 'EAGAIN', 'ENOTEMPTY'] as const;
 
 const CONNECTION_REFUSED_CODES = ['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH'] 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);
 }
 
-// =============================================================================
-// Utilities
-// =============================================================================
 
 const sleep = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, ms));