octocode-cli 1.2.5 → 1.2.7

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

@@ -0,0 +1,117 @@
+/**
+ * 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 { 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.
+ */
+export 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 {
+  const { schema, toolFn, toolName, resilience, transform } = config;
+
+  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

@@ -0,0 +1,20 @@
+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];
+    }
+    return parts[0] + parts[1].charAt(0).toUpperCase() + parts[1].slice(1);
+  }
+  return parts.join('/') || 'unknown';
+}

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

@@ -0,0 +1,155 @@
+/**
+ * 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 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;
+  if (val === 'false') return false;
+  return val;
+};
+
+/**
+ * Preprocess comma-separated string to array
+ */
+export const toArray = (val: unknown): unknown => {
+  if (Array.isArray(val)) return val;
+  if (typeof val === 'string') {
+    if (val.trim() === '') return [];
+    return val.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  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',       // \
+] 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;
+    }
+
+    return true;
+  },
+  {
+    message:
+      'Path contains invalid characters or traversal patterns ' +
+      '(null bytes, .., \\, URL-encoded sequences)',
+  }
+);
+
+// =============================================================================
+// Default Research Context
+// =============================================================================
+
+/**
+ * Default research context values for HTTP requests
+ */
+const RESEARCH_DEFAULTS = {
+  mainResearchGoal: 'HTTP API request',
+  researchGoal: 'Execute tool via HTTP',
+  reasoning: 'HTTP API call',
+} as const;
+
+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'> & {
+  id: string;
+  mainResearchGoal: string;
+  researchGoal: string;
+  reasoning: string;
+} {
+  return {
+    ...data,
+    id: (data.id as string | undefined) ?? `http-${++httpQueryCounter}`,
+    mainResearchGoal:
+      (data.mainResearchGoal as string | undefined) ??
+      RESEARCH_DEFAULTS.mainResearchGoal,
+    researchGoal:
+      (data.researchGoal as string | undefined) ??
+      RESEARCH_DEFAULTS.researchGoal,
+    reasoning:
+      (data.reasoning as string | undefined) ?? RESEARCH_DEFAULTS.reasoning,
+  };
+}
+
+/** @deprecated Use withResearchDefaults() instead */
+export const researchDefaults = RESEARCH_DEFAULTS;

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

@@ -0,0 +1,2 @@
+export * from './schemas.js';
+export * from './httpPreprocess.js';