octocode-cli 1.5.1 → 1.5.3

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

@@ -1,88 +1,42 @@
-/**
- * Route handler factory for reducing boilerplate in route files.
- *
- * Abstracts the common pattern:
- * 1. Parse and validate query params
- * 2. Execute tool with resilience wrapper
- * 3. Parse tool response
- * 4. Transform data to response format
- * 5. Send response with appropriate status
- *
- * @module utils/routeFactory
- */
-
 import type { Request, Response, NextFunction, RequestHandler } from 'express';
-import type { z } from 'zod/v4';
+import type { z } from 'zod';
 import { parseAndValidate } from '../middleware/queryParser.js';
 import { parseToolResponse, type ParsedResponse } from './responseParser.js';
 
-/**
- * Resilience wrapper type - matches the signature of withLocalResilience, withGitHubResilience, etc.
- */
+
 type ResilienceWrapper = <T>(
   fn: () => Promise<T>,
   toolName: string
 ) => Promise<T>;
 
-/**
- * Transformer function type - converts parsed tool response to final response
- */
+
 type ResponseTransformer<TQuery, TResponse> = (
   parsed: ParsedResponse,
   queries: TQuery[]
 ) => TResponse;
 
-/**
- * MCP tool function type for the route factory.
- *
- * Uses `any` for the params intentionally: HTTP schemas produce slightly different
- * types than MCP tool functions expect (optional vs required fields, auto-generated id).
- * Type safety is enforced by Zod schema validation at runtime, not by static types
- * at this HTTP→MCP boundary.
- */
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type McpToolFn = (params: any) => Promise<any>;
 
-/**
- * Route configuration options.
- * TQuery flows from schema validation through to response transformation.
- * The toolFn boundary uses McpToolFn because the schema's runtime transforms
- * (defaults, id generation) produce MCP-compatible data that TypeScript can't verify.
- */
+
 interface RouteConfig<TQuery, TResponse> {
-  /** Zod schema for query validation - accepts schemas with transforms */
+  
   schema: z.ZodType<TQuery>;
 
-  /** The MCP tool function to execute */
+  
   toolFn: McpToolFn;
 
-  /** Tool name for logging/resilience */
+  
   toolName: string;
 
-  /** Resilience wrapper (withLocalResilience, withGitHubResilience, etc.) */
+  
   resilience: ResilienceWrapper;
 
-  /** Transform parsed response to final format */
+  
   transform: ResponseTransformer<TQuery, TResponse>;
 }
 
-/**
- * Create a route handler with standard error handling, validation, and resilience.
- *
- * @example
- * ```typescript
- * localRoutes.get('/search', createRouteHandler({
- *   schema: localSearchSchema,
- *   toolFn: localSearchCode,
- *   toolName: 'localSearchCode',
- *   resilience: withLocalResilience,
- *   transform: (parsed, queries) => {
- *     // Custom transformation logic
- *     return ResearchResponse.searchResults({ ... });
- *   },
- * }));
- * ```
- */
 export function createRouteHandler<TQuery, TResponse>(
   config: RouteConfig<TQuery, TResponse>
 ): RequestHandler {
@@ -90,25 +44,20 @@ export function createRouteHandler<TQuery, TResponse>(
 
   return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
     try {
-      // 1. Parse and validate query params
       const queries = parseAndValidate(
         req.query as Record<string, unknown>,
         schema as z.ZodType<TQuery>
       ) as TQuery[];
 
-      // 2. Execute tool with resilience wrapper
       const rawResult = await resilience(
         () => toolFn({ queries }),
         toolName
       );
 
-      // 3. Parse tool response
       const parsed = parseToolResponse(rawResult as { content: Array<{ type: string; text: string }> });
 
-      // 4. Transform to final response format
       const response = transform(parsed, queries);
 
-      // 5. Send response with appropriate status
       res.status(parsed.isError ? 500 : 200).json(response);
     } catch (error) {
       next(error);

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

@@ -1,16 +1,11 @@
 export function extractToolName(path: string): string {
-  // Handle /tools/call/:toolName format
   const toolCallMatch = path.match(/^\/tools\/call\/(\w+)$/);
   if (toolCallMatch) {
     return toolCallMatch[1];
   }
 
-  // Fallback: extract from path segments
   const parts = path.split('/').filter(Boolean);
   if (parts.length >= 2) {
-    // e.g., /tools/list -> toolsList (camelCase)
-    // or just return the second part if it looks like a tool name
-    // But typically we want the tool name if it's in the URL
     if (parts[0] === 'tools' && parts[1] === 'call' && parts[2]) {
         return parts[2];
     }

package/skills/octocode-research/src/validation/httpPreprocess.ts

@@ -1,32 +1,15 @@
-/**
- * HTTP Query String Preprocessing Utilities
- *
- * HTTP query strings are always strings. These utilities convert them
- * to proper types before Zod schema validation.
- *
- * @module validation/httpPreprocess
- */
-
-import { z } from 'zod/v4';
+import { z } from 'zod';
 import path from 'path';
 import os from 'os';
 
-// =============================================================================
-// Preprocessors - Convert HTTP query strings to proper types
-// =============================================================================
 
-/**
- * Preprocess string to number (for query params)
- */
 export const toNumber = (val: unknown): unknown => {
   if (typeof val === 'number') return val;
   if (typeof val === 'string' && /^\d+$/.test(val)) return parseInt(val, 10);
   return val;
 };
 
-/**
- * Preprocess string to boolean
- */
+
 export const toBoolean = (val: unknown): unknown => {
   if (typeof val === 'boolean') return val;
   if (val === 'true') return true;
@@ -34,9 +17,7 @@ export const toBoolean = (val: unknown): unknown => {
   return val;
 };
 
-/**
- * Preprocess comma-separated string to array
- */
+
 export const toArray = (val: unknown): unknown => {
   if (Array.isArray(val)) return val;
   if (typeof val === 'string') {
@@ -46,56 +27,38 @@ export const toArray = (val: unknown): unknown => {
   return val;
 };
 
-// =============================================================================
-// Reusable Schema Parts for HTTP
-// =============================================================================
 
-/** Numeric string that gets converted to number */
 export const numericString = z.preprocess(toNumber, z.number().optional());
 
-/** Required numeric string */
+
 export const requiredNumber = z.preprocess(toNumber, z.number());
 
-/** Boolean string that gets converted to boolean */
+
 export const booleanString = z.preprocess(toBoolean, z.boolean().optional());
 
-/** Comma-separated string that gets converted to array */
+
 export const stringArray = z.preprocess(toArray, z.array(z.string()));
 
-/**
- * URL-encoded traversal patterns to detect
- */
+
 const URL_ENCODED_TRAVERSAL = [
-  '%2e%2e',    // ..
-  '%2e%2e%2f', // ../
-  '%2e%2e%5c', // ..\
-  '%252e',     // double-encoded .
-  '%2f',       // /
-  '%5c',       // \
+  '%2e%2e',
+  '%2e%2e%2f',
+  '%2e%2e%5c',
+  '%252e',
+  '%2f',
+  '%5c',
 ] as const;
 
-/**
- * Safe path that blocks traversal attacks.
- *
- * Validates:
- * - No directory traversal (..)
- * - No null bytes
- * - No Windows backslashes on non-Windows systems
- * - No URL-encoded traversal patterns
- */
+
 export const safePath = z.string().refine(
   (p) => {
-    // Check for null bytes
     if (p.includes('\0')) return false;
 
-    // Normalize and check for traversal
     const normalized = path.normalize(p);
     if (normalized.includes('..')) return false;
 
-    // Reject Windows backslashes on non-Windows (can bypass checks)
     if (os.platform() !== 'win32' && p.includes('\\')) return false;
 
-    // Check for URL-encoded traversal patterns (case-insensitive)
     const lowerPath = p.toLowerCase();
     if (URL_ENCODED_TRAVERSAL.some((pattern) => lowerPath.includes(pattern))) {
       return false;
@@ -110,13 +73,7 @@ export const safePath = z.string().refine(
   }
 );
 
-// =============================================================================
-// Default Research Context
-// =============================================================================
 
-/**
- * Default research context values for HTTP requests
- */
 const RESEARCH_DEFAULTS = {
   mainResearchGoal: 'HTTP API request',
   researchGoal: 'Execute tool via HTTP',
@@ -125,10 +82,7 @@ const RESEARCH_DEFAULTS = {
 
 let httpQueryCounter = 0;
 
-/**
- * Apply research defaults and auto-generate `id`, ensuring structural compatibility
- * with MCP tool query types (which require `id`, `mainResearchGoal`, `researchGoal`, `reasoning`).
- */
+
 export function withResearchDefaults<T extends Record<string, unknown>>(
   data: T
 ): Omit<T, 'id' | 'mainResearchGoal' | 'researchGoal' | 'reasoning'> & {

package/skills/octocode-research/src/validation/schemas.ts

@@ -1,17 +1,5 @@
-/**
- * HTTP-compatible Zod schemas for octocode-research routes.
- *
- * These schemas wrap the authoritative schemas from octocode-mcp/public
- * with HTTP query string preprocessing (string → number/boolean/array).
- *
- * @module validation/schemas
- */
-
-import { z } from 'zod/v4';
-
-// =============================================================================
-// Import HTTP preprocessing utilities
-// =============================================================================
+import { z } from 'zod';
+
 import {
   toArray,
   safePath,
@@ -22,52 +10,37 @@ import {
   withResearchDefaults,
 } from './httpPreprocess.js';
 
-// =============================================================================
-// Local Route Schemas
-// =============================================================================
 
-/**
- * HTTP schema for localSearchCode (ripgrep)
- * Wraps RipgrepQuerySchema with HTTP preprocessing
- */
 export const localSearchSchema = z
   .object({
-    // Required
     pattern: z.string().min(1, 'Pattern is required'),
     path: safePath,
 
-    // Workflow mode preset
     mode: z.enum(['discovery', 'paginated', 'detailed']).optional(),
 
-    // Pattern interpretation
     fixedString: booleanString,
     perlRegex: booleanString,
 
-    // Case sensitivity
     smartCase: booleanString,
     caseInsensitive: booleanString,
     caseSensitive: booleanString,
 
-    // Match behavior
     wholeWord: booleanString,
     invertMatch: booleanString,
     multiline: booleanString,
     multilineDotall: booleanString,
     lineRegexp: booleanString,
 
-    // File filtering
     type: z.string().optional(),
     include: stringArray.optional(),
     exclude: stringArray.optional(),
     excludeDir: stringArray.optional(),
     binaryFiles: z.enum(['text', 'without-match', 'binary']).optional(),
 
-    // Ignore control
     noIgnore: booleanString,
     hidden: booleanString,
     followSymlinks: booleanString,
 
-    // Output control
     filesOnly: booleanString,
     filesWithoutMatch: booleanString,
     count: booleanString,
@@ -75,31 +48,26 @@ export const localSearchSchema = z
     lineNumbers: booleanString,
     column: booleanString,
 
-    // Context control
     contextLines: numericString,
     beforeContext: numericString,
     afterContext: numericString,
-    context: numericString, // deprecated alias
+    context: numericString,
     matchContentLength: numericString,
 
-    // Match limiting
     maxMatchesPerFile: numericString,
     maxFiles: numericString,
-    maxResults: numericString, // deprecated alias
+    maxResults: numericString,
 
-    // Pagination
     limit: numericString,
     filesPerPage: numericString,
     filePageNumber: numericString,
     matchesPerPage: numericString,
 
-    // Stats & output format
     includeStats: booleanString,
     includeDistribution: booleanString,
     jsonOutput: booleanString,
     vimgrepFormat: booleanString,
 
-    // Advanced options
     threads: numericString,
     mmap: booleanString,
     noUnicode: booleanString,
@@ -111,7 +79,6 @@ export const localSearchSchema = z
     debug: booleanString,
     showFileLastModified: booleanString,
 
-    // Research context (optional for HTTP)
     mainResearchGoal: z.string().optional(),
     researchGoal: z.string().optional(),
     reasoning: z.string().optional(),
@@ -127,39 +94,30 @@ export const localSearchSchema = z
     return result;
   });
 
-/**
- * HTTP schema for localGetFileContent
- * Wraps FetchContentQuerySchema with HTTP preprocessing
- */
+
 export const localContentSchema = z
   .object({
     path: safePath,
 
-    // Line-based pagination
     startLine: numericString,
     endLine: numericString,
     fullContent: booleanString,
 
-    // Pattern matching within file
     matchString: z.string().optional(),
     matchStringContextLines: numericString,
     matchStringIsRegex: booleanString,
     matchStringCaseSensitive: booleanString,
 
-    // Character-based pagination
     charOffset: numericString,
     charLength: numericString,
 
-    // Research context
     mainResearchGoal: z.string().optional(),
     researchGoal: z.string().optional(),
     reasoning: z.string().optional(),
   })
   .transform(withResearchDefaults);
 
-/**
- * Transform human-readable file type to MCP's Unix-style type codes
- */
+
 const fileTypeTransform = (val: string | undefined) => {
   if (!val) return undefined;
   const typeMap: Record<string, string | undefined> = {
@@ -182,10 +140,7 @@ const fileTypeTransform = (val: string | undefined) => {
   return typeMap[val] ?? val;
 };
 
-/**
- * HTTP schema for localFindFiles
- * Wraps FindFilesQuerySchema with HTTP preprocessing
- */
+
 export const localFindSchema = z
   .object({
     path: safePath,
@@ -239,10 +194,7 @@ export const localFindSchema = z
     return result;
   });
 
-/**
- * HTTP schema for localViewStructure
- * Wraps ViewStructureQuerySchema with HTTP preprocessing
- */
+
 export const localStructureSchema = z
   .object({
     path: safePath,
@@ -281,14 +233,7 @@ export const localStructureSchema = z
     return result;
   });
 
-// =============================================================================
-// LSP Route Schemas
-// =============================================================================
 
-/**
- * HTTP schema for lspGotoDefinition
- * Wraps LSPGotoDefinitionQuerySchema with HTTP preprocessing
- */
 export const lspDefinitionSchema = z
   .object({
     uri: safePath,
@@ -302,10 +247,7 @@ export const lspDefinitionSchema = z
   })
   .transform(withResearchDefaults);
 
-/**
- * HTTP schema for lspFindReferences
- * Wraps LSPFindReferencesQuerySchema with HTTP preprocessing
- */
+
 export const lspReferencesSchema = z
   .object({
     uri: safePath,
@@ -322,10 +264,7 @@ export const lspReferencesSchema = z
   })
   .transform(withResearchDefaults);
 
-/**
- * HTTP schema for lspCallHierarchy
- * Wraps LSPCallHierarchyQuerySchema with HTTP preprocessing
- */
+
 export const lspCallsSchema = z
   .object({
     uri: safePath,
@@ -345,14 +284,7 @@ export const lspCallsSchema = z
   })
   .transform(withResearchDefaults);
 
-// =============================================================================
-// GitHub Route Schemas
-// =============================================================================
 
-/**
- * HTTP schema for githubSearchCode
- * Wraps GitHubCodeSearchQuerySchema with HTTP preprocessing
- */
 export const githubSearchSchema = z
   .object({
     keywordsToSearch: stringArray,
@@ -370,10 +302,7 @@ export const githubSearchSchema = z
   })
   .transform(withResearchDefaults);
 
-/**
- * HTTP schema for githubGetFileContent
- * Wraps FileContentQuerySchema with HTTP preprocessing
- */
+
 export const githubContentSchema = z
   .object({
     owner: z.string().min(1, 'Owner is required'),
@@ -393,10 +322,7 @@ export const githubContentSchema = z
   })
   .transform(withResearchDefaults);
 
-/**
- * HTTP schema for githubSearchRepositories
- * Wraps GitHubReposSearchSingleQuerySchema with HTTP preprocessing
- */
+
 export const githubReposSchema = z
   .object({
     keywordsToSearch: stringArray.optional(),
@@ -425,10 +351,7 @@ export const githubReposSchema = z
   )
   .transform(withResearchDefaults);
 
-/**
- * HTTP schema for githubViewRepoStructure
- * Wraps GitHubViewRepoStructureQuerySchema with HTTP preprocessing
- */
+
 export const githubStructureSchema = z
   .object({
     owner: z.string().min(1, 'Owner is required'),
@@ -444,10 +367,7 @@ export const githubStructureSchema = z
   })
   .transform(withResearchDefaults);
 
-/**
- * HTTP schema for githubSearchPullRequests
- * Wraps GitHubPullRequestSearchQuerySchema with HTTP preprocessing
- */
+
 export const githubPRsSchema = z
   .object({
     query: z.string().optional(),
@@ -492,14 +412,7 @@ export const githubPRsSchema = z
   })
   .transform(withResearchDefaults);
 
-// =============================================================================
-// Package Route Schemas
-// =============================================================================
 
-/**
- * HTTP schema for packageSearch
- * Wraps PackageSearchQuerySchema with HTTP preprocessing
- */
 export const packageSearchSchema = z
   .object({
     name: z.string().min(1, 'Package name is required'),

package/skills/octocode-research/src/validation/toolCallSchema.ts

@@ -1,40 +1,15 @@
-/**
- * Shared Zod schema for tool call body validation.
- *
- * Centralizes validation logic to avoid duplication across routes.
- *
- * @module validation/toolCallSchema
- */
-
-import { z } from 'zod/v4';
-
-// =============================================================================
-// Constants
-// =============================================================================
-
-/**
- * Maximum number of queries per tool call.
- * Limits parallel execution to prevent resource exhaustion.
- */
+import { z } from 'zod';
+
+
 export const MAX_QUERIES = 3;
 
-// =============================================================================
-// Schemas
-// =============================================================================
 
-/**
- * Schema for individual query objects.
- * Each query must be a non-empty object with arbitrary key-value pairs.
- */
 const querySchema = z.record(z.string(), z.unknown()).refine(
   (obj) => Object.keys(obj).length > 0,
   { message: 'Query object cannot be empty' }
 );
 
-/**
- * Schema for tool call request body.
- * Requires a queries array with 1-3 items.
- */
+
 const toolCallBodySchema = z.object({
   queries: z
     .array(querySchema)
@@ -42,18 +17,10 @@ const toolCallBodySchema = z.object({
     .max(MAX_QUERIES, `Maximum ${MAX_QUERIES} queries per request`),
 });
 
-/**
- * Inferred type from the schema
- */
+
 type ToolCallBody = z.infer<typeof toolCallBodySchema>;
 
-// =============================================================================
-// Validation Function
-// =============================================================================
 
-/**
- * Validation result type
- */
 interface ValidationResult<T> {
   success: boolean;
   data?: T;
@@ -63,25 +30,6 @@ interface ValidationResult<T> {
   };
 }
 
-/**
- * Validate tool call body against schema.
- *
- * @param body - Request body to validate
- * @returns Validation result with data or error details
- *
- * @example
- * ```typescript
- * const result = validateToolCallBody(req.body);
- * if (!result.success) {
- *   res.status(400).json({
- *     success: false,
- *     hints: [result.error.message, ...result.error.details.map(d => d.message)]
- *   });
- *   return;
- * }
- * const { queries } = result.data;
- * ```
- */
 export function validateToolCallBody(body: unknown): ValidationResult<ToolCallBody> {
   const result = toolCallBodySchema.safeParse(body);
 
@@ -104,20 +52,12 @@ export function validateToolCallBody(body: unknown): ValidationResult<ToolCallBo
   };
 }
 
-/**
- * Generate user-friendly hints for validation errors.
- *
- * @param toolName - Name of the tool being called
- * @param error - Validation error details
- * @returns Array of hint strings for the user
- */
 export function getValidationHints(
   toolName: string,
   error: { message: string; details: z.core.$ZodIssue[] }
 ): string[] {
   const hints = [error.message];
 
-  // Add specific hints based on error type
   const hasQueriesError = error.details.some(
     (d) => d.path.includes('queries') || d.message.includes('queries')
   );