octocode-cli 1.2.5 → 1.2.7

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

@@ -0,0 +1,186 @@
+/**
+ * Octocode Research Skill
+ *
+ * Re-exports all octocode tools with skill-friendly names.
+ * Each tool can be called as a function with query arrays.
+ *
+ * @example
+ * ```typescript
+ * import { githubSearchCode, localSearchCode, lspGotoDefinition } from 'octocode-research';
+ *
+ * // Search GitHub code
+ * const result = await githubSearchCode({
+ *   queries: [{
+ *     mainResearchGoal: "Find React hooks",
+ *     researchGoal: "Locate useState implementation",
+ *     reasoning: "Understanding state management",
+ *     keywordsToSearch: ["useState"],
+ *     owner: "facebook",
+ *     repo: "react"
+ *   }]
+ * });
+ * ```
+ */
+
+// ============================================================================
+// GitHub Tools (Remote Repository Research)
+// ============================================================================
+
+export {
+  fetchMultipleGitHubFileContents as githubGetFileContent,
+  searchMultipleGitHubCode as githubSearchCode,
+  searchMultipleGitHubPullRequests as githubSearchPullRequests,
+  searchMultipleGitHubRepos as githubSearchRepositories,
+  exploreMultipleRepositoryStructures as githubViewRepoStructure,
+} from 'octocode-mcp/public';
+
+// GitHub Types
+export type {
+  FileContentQuery,
+  ContentResult,
+  GitHubCodeSearchQuery,
+  SearchResult,
+  GitHubPullRequestSearchQuery,
+  PullRequestSearchResult,
+  GitHubReposSearchQuery,
+  RepoSearchResult,
+  GitHubViewRepoStructureQuery,
+  RepoStructureResult,
+} from 'octocode-mcp/public';
+
+// ============================================================================
+// Local Tools (Local Codebase Research)
+// ============================================================================
+
+export {
+  executeFetchContent as localGetFileContent,
+  executeFindFiles as localFindFiles,
+  executeRipgrepSearch as localSearchCode,
+  executeViewStructure as localViewStructure,
+} from 'octocode-mcp/public';
+
+// Local Types
+export type {
+  FetchContentQuery,
+  FetchContentResult,
+  FindFilesQuery,
+  FindFilesResult,
+  RipgrepSearchQuery,
+  SearchContentResult,
+  ViewStructureQuery,
+  ViewStructureResult,
+} from 'octocode-mcp/public';
+
+// ============================================================================
+// LSP Tools (Semantic Code Analysis)
+// ============================================================================
+
+export {
+  executeGotoDefinition as lspGotoDefinition,
+  executeFindReferences as lspFindReferences,
+  executeCallHierarchy as lspCallHierarchy,
+} from 'octocode-mcp/public';
+
+// LSP Types
+export type {
+  LSPGotoDefinitionQuery,
+  GotoDefinitionResult,
+  LSPFindReferencesQuery,
+  FindReferencesResult,
+  LSPCallHierarchyQuery,
+  CallHierarchyResult,
+} from 'octocode-mcp/public';
+
+// ============================================================================
+// Package Search Tools
+// ============================================================================
+
+export { searchPackages as packageSearch } from 'octocode-mcp/public';
+
+// Package Types
+export type {
+  PackageSearchQuery,
+  PackageSearchResult,
+  NpmPackageSearchQuery,
+  PythonPackageSearchQuery,
+} from 'octocode-mcp/public';
+
+// ============================================================================
+// Response Utilities (for custom result formatting)
+// ============================================================================
+
+// Legacy API (backwards compatible)
+export { createResult, createResponseFormat } from 'octocode-mcp/public';
+
+// New Role-Based Response API
+export {
+  createRoleBasedResult,
+  ContentBuilder,
+  QuickResult,
+  StatusEmoji,
+  StatusEmojis,
+} from 'octocode-mcp/public';
+
+export type {
+  ContentRole,
+  RoleContentBlock,
+  RoleBasedResultOptions,
+  RoleAnnotations,
+} from 'octocode-mcp/public';
+
+// Research-specific response builders
+export { ResearchResponse } from './utils/responseBuilder.js';
+
+// ============================================================================
+// Tool Metadata & Configuration
+// ============================================================================
+
+export {
+  TOOL_NAMES,
+  DESCRIPTIONS,
+  getToolHintsSync,
+  getGenericErrorHintsSync,
+} from 'octocode-mcp/public';
+
+// ============================================================================
+// Security Validation (for wrapping tool calls)
+// ============================================================================
+
+export { withBasicSecurityValidation } from 'octocode-mcp/public';
+
+// ============================================================================
+// Token Management (for GitHub API authentication)
+// ============================================================================
+
+export {
+  initialize,
+  initializeProviders,
+  getGitHubToken,
+  getToken,
+  getTokenSource,
+} from 'octocode-mcp/public';
+
+export type { TokenSourceType } from 'octocode-mcp/public';
+
+// ============================================================================
+// Session Management (for tracking usage and telemetry)
+// ============================================================================
+
+export {
+  initializeSession,
+  getSessionManager,
+  logSessionInit,
+  logToolCall,
+  logPromptCall,
+  logSessionError,
+  logRateLimit,
+  resetSessionManager,
+} from 'octocode-mcp/public';
+
+export type {
+  SessionData,
+  ToolCallData,
+  PromptCallData,
+  ErrorData,
+  RateLimitData,
+} from 'octocode-mcp/public';

package/skills/octocode-research/src/mcpCache.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP Content Cache Module
+ *
+ * Loads mcpContent ONCE at server startup and provides cached access.
+ * Routes should use getMcpContent() instead of calling loadToolContent() on each request.
+ */
+
+import type { CompleteMetadata } from 'octocode-mcp/public';
+import { initialize, loadToolContent } from 'octocode-mcp/public';
+
+let mcpContent: CompleteMetadata | null = null;
+let initPromise: Promise<CompleteMetadata> | null = null;
+
+/**
+ * Initialize mcpContent - call ONCE at server startup
+ * Safe to call multiple times (idempotent)
+ */
+export async function initializeMcpContent(): Promise<CompleteMetadata> {
+  if (mcpContent) return mcpContent;
+
+  if (initPromise) return initPromise;
+
+  initPromise = (async () => {
+    await initialize();
+    const content = await loadToolContent();
+    mcpContent = content;
+    return content;
+  })();
+
+  return initPromise;
+}
+
+/**
+ * Get cached mcpContent - use in routes
+ * Throws if not initialized (indicates server startup failed)
+ */
+export function getMcpContent(): CompleteMetadata {
+  if (!mcpContent) {
+    throw new Error('mcpContent not initialized. Call initializeMcpContent() at server startup.');
+  }
+  return mcpContent;
+}
+
+/**
+ * Check if mcpContent is initialized (for health checks)
+ */
+export function isMcpInitialized(): boolean {
+  return mcpContent !== null;
+}

package/skills/octocode-research/src/middleware/errorHandler.ts

@@ -0,0 +1,65 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { z } from 'zod/v4';
+import { logError, logWarn, sanitizeQueryParams } from '../utils/logger.js';
+import { logSessionError } from '../index.js';
+import { fireAndForgetWithTimeout } from '../utils/asyncTimeout.js';
+
+export interface ApiError extends Error {
+  statusCode?: number;
+  code?: string;
+  details?: z.core.$ZodIssue[];
+}
+
+import { extractToolName } from '../utils/url.js';
+
+export function errorHandler(
+  error: ApiError,
+  req: Request,
+  res: Response,
+  _next: NextFunction
+): void {
+  const statusCode = error.statusCode ?? 500;
+  const isValidationError = statusCode === 400;
+
+  // Log with appropriate level - now persisted to ~/.octocode/logs/errors.log
+  if (isValidationError) {
+    logWarn(`[VALIDATION] ${req.method} ${req.path}: ${error.message}`, {
+      path: req.path,
+      query: sanitizeQueryParams(req.query as Record<string, unknown>),
+      details: error.details,
+    });
+  } else {
+    logError(`[SERVER] ${req.method} ${req.path}: ${error.message}`, error);
+  }
+
+  // Log error to session telemetry
+  const toolName = extractToolName(req.path);
+  const errorCode = error.code ?? (isValidationError ? 'VALIDATION_ERROR' : 'INTERNAL_ERROR');
+  fireAndForgetWithTimeout(
+    () => logSessionError(toolName, errorCode),
+    5000,
+    'logSessionError'
+  );
+
+  const response: {
+    success: false;
+    error: {
+      message: string;
+      code: string;
+      details?: z.core.$ZodIssue[];
+    };
+  } = {
+    success: false,
+    error: {
+      message: error.message,
+      code: error.code ?? 'INTERNAL_ERROR',
+    },
+  };
+
+  // Include validation details for 400 errors
+  if (isValidationError && error.details) {
+    response.error.details = error.details;
+  }
+
+  res.status(statusCode).json(response);
+}

package/skills/octocode-research/src/middleware/logger.ts

@@ -0,0 +1,61 @@
+import type { Request, Response, NextFunction } from 'express';
+import { randomUUID } from 'crypto';
+import { logToolCall, sanitizeQueryParams } from '../utils/logger.js';
+import { resultLog, errorLog } from '../utils/colors.js';
+import { extractToolName } from '../utils/url.js';
+
+/**
+ * Generate or retrieve request ID for log correlation.
+ * Uses X-Request-ID header if provided, otherwise generates a new UUID.
+ */
+function getRequestId(req: Request): string {
+  const existingId = req.headers['x-request-id'];
+  if (typeof existingId === 'string' && existingId.length > 0) {
+    return existingId;
+  }
+  return randomUUID();
+}
+
+export function requestLogger(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  const start = Date.now();
+  const requestId = getRequestId(req);
+
+  // Set request ID on response header for correlation
+  res.setHeader('x-request-id', requestId);
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    const status = res.statusCode;
+    const statusIcon = status >= 400 ? '❌' : '✅';
+    const success = status < 400;
+
+    // Results output in BLUE for success, RED for error
+    const resultMessage = `${statusIcon} ${req.method} ${req.path} ${status} ${duration}ms`;
+
+    if (success) {
+      console.log(resultLog(resultMessage));
+    } else {
+      console.log(errorLog(resultMessage));
+    }
+
+    if (req.path !== '/health') {
+      logToolCall({
+        tool: extractToolName(req.path),
+        route: req.path,
+        method: req.method,
+        params: sanitizeQueryParams(req.query as Record<string, unknown>),
+        duration,
+        success,
+        error: success ? undefined : `HTTP ${status}`,
+        requestId,
+      });
+    }
+  });
+
+  next();
+}
+

package/skills/octocode-research/src/middleware/queryParser.ts

@@ -0,0 +1,115 @@
+import type { Response } from 'express';
+import { z } from 'zod/v4';
+
+/**
+ * Custom error class for validation failures.
+ * Carries HTTP status code for proper error responses.
+ */
+class ValidationError extends Error {
+  statusCode: number;
+  code: string;
+  details: z.core.$ZodIssue[];
+
+  constructor(message: string, details: z.core.$ZodIssue[] = []) {
+    super(message);
+    this.name = 'ValidationError';
+    this.statusCode = 400;
+    this.code = 'VALIDATION_ERROR';
+    this.details = details;
+  }
+}
+
+/**
+ * Parse and validate query parameters using a Zod schema.
+ * Returns the validated data wrapped in an array (for tool compatibility).
+ *
+ * @param query - Express request query object
+ * @param schema - Zod schema for validation
+ * @returns Array containing the validated query object
+ * @throws ValidationError if validation fails
+ */
+export function parseAndValidate<T>(
+  query: Record<string, unknown>,
+  schema: z.ZodType<T>
+): T[] {
+  // Check for JSON-encoded queries array (batch mode)
+  if (query.queries && typeof query.queries === 'string') {
+    try {
+      const parsed = JSON.parse(query.queries);
+      if (Array.isArray(parsed)) {
+        // Validate each item in the array
+        const validated = parsed.map((item, index) => {
+          const result = schema.safeParse(item);
+          if (!result.success) {
+            throw new ValidationError(
+              `Validation failed for query[${index}]: ${formatZodError(result.error)}`,
+              result.error.issues
+            );
+          }
+          return result.data;
+        });
+        return validated;
+      }
+    } catch (e) {
+      if (e instanceof ValidationError) throw e;
+      // JSON.parse failed - fall through to single query mode silently
+      // (avoid logging untrusted input in production)
+    }
+  }
+
+  // Parse flat query params (single query mode)
+  const cleanedQuery: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (key !== 'queries') {
+      cleanedQuery[key] = value;
+    }
+  }
+
+  const result = schema.safeParse(cleanedQuery);
+  if (!result.success) {
+    throw new ValidationError(
+      formatZodError(result.error),
+      result.error.issues
+    );
+  }
+
+  return [result.data];
+}
+
+/**
+ * Format Zod error into a human-readable string.
+ */
+function formatZodError(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const path = issue.path.join('.');
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join('; ');
+}
+
+/**
+ * Send standardized tool result response.
+ */
+export function sendToolResult(
+  res: Response,
+  result: {
+    content?: Array<{ type: string; text?: string }>;
+    isError?: boolean;
+  }
+): void {
+  const textContent = result.content?.find(
+    (c) => c.type === 'text' && 'text' in c
+  );
+
+  const isError = result.isError ?? false;
+
+  res.status(isError ? 500 : 200).json({
+    success: !isError,
+    data: textContent?.text ?? null,
+    raw: result,
+  });
+}
+
+// Legacy function for backwards compatibility (deprecated)
+// Internal alias: parseQueryToArray = parseAndValidate

package/skills/octocode-research/src/middleware/readiness.ts

@@ -0,0 +1,17 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import { isMcpInitialized } from '../mcpCache.js';
+
+export const checkReadiness: RequestHandler = (_req: Request, res: Response, next: NextFunction) => {
+  if (!isMcpInitialized()) {
+    res.status(503).json({
+      success: false,
+      error: {
+        message: 'Server is initializing',
+        code: 'SERVER_INITIALIZING',
+        hint: 'Please retry in a few seconds',
+      },
+    });
+    return;
+  }
+  next();
+};

package/skills/octocode-research/src/routes/github.ts

@@ -0,0 +1,197 @@
+/**
+ * GitHub routes using route factory pattern.
+ * 
+ * @module routes/github
+ */
+
+import { Router } from 'express';
+import {
+  githubSearchCode,
+  githubGetFileContent,
+  githubSearchRepositories,
+  githubViewRepoStructure,
+  githubSearchPullRequests,
+} from '../index.js';
+import {
+  githubSearchSchema,
+  githubContentSchema,
+  githubReposSchema,
+  githubStructureSchema,
+  githubPRsSchema,
+} from '../validation/index.js';
+import { ResearchResponse, QuickResult, detectLanguageFromPath } from '../utils/responseBuilder.js';
+import { withGitHubResilience } from '../utils/resilience.js';
+import { createRouteHandler } from '../utils/routeFactory.js';
+import {
+  safeString,
+  safeNumber,
+  safeArray,
+  transformPagination,
+} from '../utils/responseFactory.js';
+import { isObject, hasProperty, hasNumberProperty, hasBooleanProperty } from '../types/guards.js';
+
+export const githubRoutes = Router();
+
+// GET /githubSearchCode - Search code on GitHub
+githubRoutes.get(
+  '/githubSearchCode',
+  createRouteHandler({
+    schema: githubSearchSchema,
+    toolFn: githubSearchCode,
+    toolName: 'githubSearchCode',
+    resilience: withGitHubResilience,
+    transform: (parsed, queries) => {
+      const { data, hints, research } = parsed;
+      const files = safeArray<Record<string, unknown>>(data, 'files');
+
+      return ResearchResponse.searchResults({
+        files: files.map((f) => {
+          const textMatches = safeArray<string>(f, 'text_matches');
+          const firstMatch = textMatches[0];
+          return {
+            path: safeString(f, 'path'),
+            repo: hasProperty(f, 'repo') && typeof f.repo === 'string' ? f.repo : undefined,
+            matches: textMatches.length,
+            preview: typeof firstMatch === 'string' ? firstMatch.trim().slice(0, 200) : undefined,
+          };
+        }),
+        totalMatches: isObject(data.pagination) ? safeNumber(data.pagination, 'totalMatches', 0) : 0,
+        pagination: transformPagination(data.pagination),
+        searchPattern: Array.isArray(queries[0]?.keywordsToSearch)
+          ? queries[0].keywordsToSearch.join(' ')
+          : undefined,
+        mcpHints: hints,
+        research,
+      });
+    },
+  })
+);
+
+// GET /githubGetFileContent - Read file from GitHub
+githubRoutes.get(
+  '/githubGetFileContent',
+  createRouteHandler({
+    schema: githubContentSchema,
+    toolFn: githubGetFileContent,
+    toolName: 'githubGetFileContent',
+    resilience: withGitHubResilience,
+    transform: (parsed, queries) => {
+      const { data, hints, research } = parsed;
+
+      return ResearchResponse.fileContent({
+        path: safeString(data, 'path', queries[0]?.path || 'unknown'),
+        content: safeString(data, 'content'),
+        lines: hasNumberProperty(data, 'startLine')
+          ? {
+              start: data.startLine,
+              end: hasNumberProperty(data, 'endLine') ? data.endLine : data.startLine,
+            }
+          : undefined,
+        language: detectLanguageFromPath(queries[0]?.path || ''),
+        totalLines: hasNumberProperty(data, 'totalLines') ? data.totalLines : undefined,
+        isPartial: hasBooleanProperty(data, 'isPartial') ? data.isPartial : undefined,
+        mcpHints: hints,
+        research,
+      });
+    },
+  })
+);
+
+// GET /githubSearchRepositories - Search repositories
+githubRoutes.get(
+  '/githubSearchRepositories',
+  createRouteHandler({
+    schema: githubReposSchema,
+    toolFn: githubSearchRepositories,
+    toolName: 'githubSearchRepositories',
+    resilience: withGitHubResilience,
+    transform: (parsed) => {
+      const { data, hints: mcpHints } = parsed;
+      const repos = safeArray<Record<string, unknown>>(data, 'repositories');
+
+      const summary = repos.length > 0
+        ? `Found ${repos.length} repositories:\n` +
+          repos
+            .slice(0, 10)
+            .map((r) =>
+              `- ${safeString(r, 'owner')}/${safeString(r, 'repo')}${hasNumberProperty(r, 'stars') ? ` ⭐${r.stars}` : ''}\n  ${safeString(r, 'description', 'No description')}`
+            )
+            .join('\n')
+        : 'No repositories found';
+
+      const hints: string[] = [...mcpHints];
+      return repos.length === 0
+        ? QuickResult.empty(summary, hints.length > 0 ? hints : [
+            'Try different search terms',
+            'Use topicsToSearch for topic-based search',
+          ])
+        : QuickResult.success(summary, data, hints.length > 0 ? hints : [
+            'Use githubViewRepoStructure to explore repo',
+            'Use githubSearchCode to search within repo',
+          ]);
+    },
+  })
+);
+
+// GET /githubViewRepoStructure - View repository structure
+githubRoutes.get(
+  '/githubViewRepoStructure',
+  createRouteHandler({
+    schema: githubStructureSchema,
+    toolFn: githubViewRepoStructure,
+    toolName: 'githubViewRepoStructure',
+    resilience: withGitHubResilience,
+    transform: (parsed, queries) => {
+      const { data, hints, research } = parsed;
+      const structure = isObject(data.structure) ? data.structure : {};
+      const rootEntry = isObject(structure['.']) ? structure['.'] as { files?: string[]; folders?: string[] } : { files: [], folders: [] };
+      const summary = isObject(data.summary) ? data.summary : {};
+
+      return ResearchResponse.repoStructure({
+        path: queries[0]?.path || '/',
+        structure: {
+          files: Array.isArray(rootEntry.files) ? rootEntry.files : [],
+          folders: Array.isArray(rootEntry.folders) ? rootEntry.folders : [],
+        },
+        depth: hasNumberProperty(queries[0], 'depth') ? queries[0].depth : undefined,
+        totalFiles: hasNumberProperty(summary, 'totalFiles') ? summary.totalFiles : undefined,
+        totalFolders: hasNumberProperty(summary, 'totalFolders') ? summary.totalFolders : undefined,
+        owner: queries[0]?.owner,
+        repo: queries[0]?.repo,
+        mcpHints: hints,
+        research,
+      });
+    },
+  })
+);
+
+// GET /githubSearchPullRequests - Search pull requests
+githubRoutes.get(
+  '/githubSearchPullRequests',
+  createRouteHandler({
+    schema: githubPRsSchema,
+    toolFn: githubSearchPullRequests,
+    toolName: 'githubSearchPullRequests',
+    resilience: withGitHubResilience,
+    transform: (parsed, queries) => {
+      const { data, hints, research } = parsed;
+      const prs = safeArray<Record<string, unknown>>(data, 'pull_requests');
+
+      return ResearchResponse.pullRequests({
+        prs: prs.map((pr) => ({
+          number: safeNumber(pr, 'number', 0),
+          title: safeString(pr, 'title'),
+          state: safeString(pr, 'state'),
+          author: hasProperty(pr, 'author') && typeof pr.author === 'string' ? pr.author : undefined,
+          url: hasProperty(pr, 'url') && typeof pr.url === 'string' ? pr.url : undefined,
+        })),
+        repo: queries[0]?.owner && queries[0]?.repo
+          ? `${queries[0].owner}/${queries[0].repo}`
+          : undefined,
+        pagination: transformPagination(data.pagination),
+        mcpHints: hints,
+        research,
+      });
+    },
+  })
+);