octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-research/src/types/errorGuards.ts

@@ -0,0 +1,151 @@
+/**
+ * Type guards for safe error handling.
+ *
+ * Replaces unsafe type coercion (err as { status?: number }) with
+ * proper runtime type checking for better type safety.
+ *
+ * @module types/errorGuards
+ */
+
+// =============================================================================
+// Error Interfaces
+// =============================================================================
+
+/**
+ * Error with HTTP status code (e.g., from API responses)
+ */
+export interface ErrorWithStatus {
+  status: number;
+  message?: string;
+}
+
+/**
+ * Error with error code (e.g., Node.js system errors)
+ */
+export interface ErrorWithCode {
+  code: string;
+  message?: string;
+}
+
+/**
+ * Error with headers (e.g., rate limit responses)
+ */
+export interface ErrorWithHeaders {
+  headers: Record<string, string>;
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Check if error has a status property (number)
+ */
+export function isErrorWithStatus(err: unknown): err is ErrorWithStatus {
+  return (
+    err !== null &&
+    typeof err === 'object' &&
+    'status' in err &&
+    typeof (err as ErrorWithStatus).status === 'number'
+  );
+}
+
+/**
+ * Check if error has a code property (string)
+ */
+export function isErrorWithCode(err: unknown): err is ErrorWithCode {
+  return (
+    err !== null &&
+    typeof err === 'object' &&
+    'code' in err &&
+    typeof (err as ErrorWithCode).code === 'string'
+  );
+}
+
+/**
+ * Check if error has a message property (string)
+ */
+export function hasMessage(err: unknown): err is { message: string } {
+  return (
+    err !== null &&
+    typeof err === 'object' &&
+    'message' in err &&
+    typeof (err as { message: unknown }).message === 'string'
+  );
+}
+
+/**
+ * Check if error has headers property (object)
+ */
+export function hasHeaders(err: unknown): err is ErrorWithHeaders {
+  return (
+    err !== null &&
+    typeof err === 'object' &&
+    'headers' in err &&
+    typeof (err as { headers: unknown }).headers === 'object' &&
+    (err as ErrorWithHeaders).headers !== null
+  );
+}
+
+// =============================================================================
+// Safe Property Accessors
+// =============================================================================
+
+/**
+ * Safely get status from error (undefined if not present)
+ */
+export function getErrorStatus(err: unknown): number | undefined {
+  return isErrorWithStatus(err) ? err.status : undefined;
+}
+
+/**
+ * Safely get code from error (undefined if not present)
+ */
+export function getErrorCode(err: unknown): string | undefined {
+  return isErrorWithCode(err) ? err.code : undefined;
+}
+
+/**
+ * Safely get message from error (undefined if not present)
+ */
+export function getErrorMessage(err: unknown): string | undefined {
+  return hasMessage(err) ? err.message : undefined;
+}
+
+/**
+ * Safely get header value from error (undefined if not present)
+ */
+export function getErrorHeader(err: unknown, header: string): string | undefined {
+  if (hasHeaders(err)) {
+    return err.headers[header];
+  }
+  return undefined;
+}
+
+// =============================================================================
+// Composite Checks
+// =============================================================================
+
+/**
+ * Check if error status is in a given list
+ */
+export function hasStatusIn(err: unknown, statuses: readonly number[]): boolean {
+  const status = getErrorStatus(err);
+  return status !== undefined && statuses.includes(status);
+}
+
+/**
+ * Check if error code is in a given list
+ */
+export function hasCodeIn(err: unknown, codes: readonly string[]): boolean {
+  const code = getErrorCode(err);
+  return code !== undefined && codes.includes(code);
+}
+
+/**
+ * Check if error message matches any pattern
+ */
+export function messageMatches(err: unknown, patterns: readonly RegExp[]): boolean {
+  const message = getErrorMessage(err);
+  return message !== undefined && patterns.some((p) => p.test(message));
+}

package/skills/octocode-research/src/types/express.d.ts

@@ -0,0 +1,76 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+declare module 'express' {
+  import { IncomingMessage, ServerResponse, Server } from 'http';
+
+  export interface ResearchContext {
+    sessionId: string;
+    mainGoal: string;
+    toolChain: string[];
+    startTime: number;
+    lastActivity: number;
+  }
+
+  export interface Request extends IncomingMessage {
+    query: Record<string, any>;
+    params: Record<string, string>;
+    body: any;
+    method: string;
+    path: string;
+    researchContext?: ResearchContext;
+  }
+
+  export interface Response extends ServerResponse {
+    status(code: number): Response;
+    json(body: any): Response;
+    send(body: any): Response;
+  }
+
+  export type NextFunction = (err?: any) => void;
+
+  export type RequestHandler = (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ) => void | Promise<void>;
+
+  export type ErrorRequestHandler = (
+    err: any,
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ) => void | Promise<void>;
+
+  export interface Router {
+    get(path: string, ...handlers: RequestHandler[]): Router;
+    post(path: string, ...handlers: RequestHandler[]): Router;
+    put(path: string, ...handlers: RequestHandler[]): Router;
+    delete(path: string, ...handlers: RequestHandler[]): Router;
+    use(...handlers: (RequestHandler | ErrorRequestHandler)[]): Router;
+  }
+
+  export interface Express {
+    listen(port: number, hostname: string, backlog: number, callback?: () => void): Server;
+    listen(port: number, hostname: string, callback?: () => void): Server;
+    listen(port: number, callback?: () => void): Server;
+    listen(callback?: () => void): Server;
+    get(path: string, handler: RequestHandler): Express;
+    use(path: string, router: Router): Express;
+    use(handler: RequestHandler | ErrorRequestHandler): Express;
+  }
+
+  interface ExpressFunction {
+    (): Express;
+    Router(): Router;
+    json(): RequestHandler;
+  }
+
+  const express: ExpressFunction;
+  export default express;
+  export function Router(): Router;
+}
+
+declare module 'qs' {
+  export interface ParsedQs {
+    [key: string]: any;
+  }
+}

package/skills/octocode-research/src/types/guards.ts

@@ -0,0 +1,98 @@
+/**
+ * Type guard utilities for consistent runtime type checking.
+ * Use these instead of inline typeof checks across routes.
+ *
+ * @module types/guards
+ */
+
+/**
+ * Check if value is a non-empty string
+ */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Check if value is a positive finite number
+ */
+export function isPositiveNumber(value: unknown): value is number {
+  return typeof value === 'number' && value > 0 && Number.isFinite(value);
+}
+
+/**
+ * Check if value is a non-negative finite number
+ */
+export function isNonNegativeNumber(value: unknown): value is number {
+  return typeof value === 'number' && value >= 0 && Number.isFinite(value);
+}
+
+/**
+ * Check if value is an array of non-empty strings
+ */
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(isNonEmptyString);
+}
+
+/**
+ * Check if value is an array (of any type)
+ */
+export function isArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}
+
+/**
+ * Check if value is a non-null object
+ */
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Check if object has a specific property
+ */
+export function hasProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, unknown> {
+  return typeof obj === 'object' && obj !== null && key in obj;
+}
+
+/**
+ * Check if object has a string property
+ */
+export function hasStringProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, string> {
+  return hasProperty(obj, key) && typeof obj[key] === 'string';
+}
+
+/**
+ * Check if object has a number property
+ */
+export function hasNumberProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, number> {
+  return hasProperty(obj, key) && typeof obj[key] === 'number';
+}
+
+/**
+ * Check if object has a boolean property
+ */
+export function hasBooleanProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, boolean> {
+  return hasProperty(obj, key) && typeof obj[key] === 'boolean';
+}
+
+/**
+ * Check if object has an array property
+ */
+export function hasArrayProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, unknown[]> {
+  return hasProperty(obj, key) && Array.isArray(obj[key]);
+}

package/skills/octocode-research/src/types/mcp.ts

@@ -0,0 +1,119 @@
+/**
+ * MCP Protocol Types for /tools/list and /prompts/list endpoints
+ * Based on: https://modelcontextprotocol.io/docs/concepts/tools
+ */
+
+// JSON Schema type for tool input schemas
+export interface JsonSchema {
+  $schema?: string;
+  type: 'object';
+  properties: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+export interface JsonSchemaProperty {
+  type: string;
+  description?: string;
+  items?: JsonSchemaProperty;
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  minItems?: number;
+  maxItems?: number;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  enum?: (string | number | boolean)[];
+  default?: unknown;
+}
+
+/**
+ * MCP Tool representation for /tools/list
+ */
+interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+}
+
+/**
+ * MCP Prompt argument for /prompts/list
+ */
+export interface McpPromptArgument {
+  name: string;
+  description: string;
+  required?: boolean;
+}
+
+/**
+ * MCP Prompt representation for /prompts/list
+ */
+export interface McpPrompt {
+  name: string;
+  description: string;
+  arguments?: McpPromptArgument[];
+}
+
+/**
+ * Response metadata
+ */
+export interface ListResponseMeta {
+  totalCount: number;
+  version: string;
+}
+
+/**
+ * Response type for GET /tools/list
+ */
+export interface ListToolsResponse {
+  tools: McpTool[];
+  _meta?: ListResponseMeta;
+}
+
+/**
+ * Response type for GET /prompts/list
+ */
+export interface ListPromptsResponse {
+  prompts: McpPrompt[];
+  _meta?: ListResponseMeta;
+}
+
+/**
+ * Transform description-based schema to JSON Schema format
+ * This is a fallback transformer when full JSON schemas are not available
+ */
+export function transformToJsonSchema(
+  schemaDescriptions: Record<string, string>,
+  toolName: string
+): JsonSchema {
+  const properties: Record<string, JsonSchemaProperty> = {};
+  
+  // Create properties from descriptions
+  for (const [key, description] of Object.entries(schemaDescriptions)) {
+    properties[key] = {
+      type: 'string', // Default type - could be enhanced with type inference
+      description,
+    };
+  }
+
+  // Wrap in queries array structure (standard MCP bulk query pattern)
+  return {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    properties: {
+      queries: {
+        type: 'array',
+        description: `Research queries for ${toolName} (1-3 queries per call for optimal resource management). Review schema before use for optimal results`,
+        items: {
+          type: 'object',
+          properties,
+          required: ['mainResearchGoal', 'researchGoal', 'reasoning'],
+        },
+        minItems: 1,
+        maxItems: 3,
+      },
+    },
+    required: ['queries'],
+  };
+}

package/skills/octocode-research/src/types/responses.ts

@@ -0,0 +1,199 @@
+/**
+ * Response types for MCP tool results.
+ * Use these instead of Record<string, unknown> for type-safe data handling.
+ *
+ * @module types/responses
+ */
+
+import { hasProperty, hasArrayProperty } from './guards.js';
+
+// =============================================================================
+// File and Search Types
+// =============================================================================
+
+/**
+ * A match within a file
+ */
+export interface MatchLocation {
+  line: number;
+  column?: number;
+  value?: string;
+  byteOffset?: number;
+  charOffset?: number;
+}
+
+/**
+ * A file with matches from search results
+ */
+export interface FileMatch {
+  path: string;
+  line?: number;
+  column?: number;
+  matchText?: string;
+  matchCount?: number;
+  contextBefore?: string[];
+  contextAfter?: string[];
+  allMatches?: MatchLocation[];
+}
+
+/**
+ * Pagination info for paginated results
+ */
+export interface PaginationInfo {
+  page?: number;
+  currentPage?: number;
+  totalPages?: number;
+  totalMatches?: number;
+  totalFiles?: number;
+  hasMore?: boolean;
+  nextCursor?: string;
+}
+
+/**
+ * Search result from localSearchCode or githubSearchCode
+ */
+interface SearchResult {
+  files?: FileMatch[];
+  totalMatches?: number;
+  totalFiles?: number;
+  pagination?: PaginationInfo;
+}
+
+// =============================================================================
+// LSP Types
+// =============================================================================
+
+/**
+ * LSP position
+ */
+interface LspPosition {
+  line: number;
+  character: number;
+}
+
+/**
+ * LSP range
+ */
+interface LspRange {
+  start: LspPosition;
+  end: LspPosition;
+}
+
+/**
+ * LSP definition location
+ */
+interface LspDefinition {
+  uri: string;
+  range: LspRange;
+}
+
+/**
+ * LSP reference location
+ */
+export interface LspReference extends LspDefinition {
+  context?: string;
+}
+
+/**
+ * LSP call hierarchy item
+ */
+export interface LspCallHierarchyItem {
+  name: string;
+  kind?: number;
+  uri: string;
+  range?: LspRange;
+  selectionRange?: LspRange;
+}
+
+// =============================================================================
+// Repository Structure Types
+// =============================================================================
+
+/**
+ * Repository structure result
+ */
+export interface RepoStructure {
+  files?: string[];
+  folders?: string[];
+  totalFiles?: number;
+  totalDirectories?: number;
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Check if an object is a FileMatch
+ */
+function isFileMatch(obj: unknown): obj is FileMatch {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'path' in obj &&
+    typeof (obj as FileMatch).path === 'string'
+  );
+}
+
+/**
+ * Check if an object has valid pagination info
+ */
+function hasValidPagination(obj: unknown): obj is { pagination: PaginationInfo } {
+  if (!hasProperty(obj, 'pagination')) return false;
+  const p = obj.pagination;
+  return typeof p === 'object' && p !== null;
+}
+
+/**
+ * Check if an object is a SearchResult
+ */
+export function isSearchResult(obj: unknown): obj is SearchResult {
+  if (typeof obj !== 'object' || obj === null) return false;
+  if (hasArrayProperty(obj, 'files')) {
+    const files = (obj as { files: unknown[] }).files;
+    return files.every(isFileMatch);
+  }
+  return hasProperty(obj, 'totalMatches') || hasProperty(obj, 'totalFiles');
+}
+
+/**
+ * Check if an object is an LspDefinition
+ */
+export function isLspDefinition(obj: unknown): obj is LspDefinition {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'uri' in obj &&
+    'range' in obj &&
+    typeof (obj as LspDefinition).uri === 'string'
+  );
+}
+
+/**
+ * Extract files array from data safely
+ */
+export function extractFiles(data: unknown): FileMatch[] {
+  if (!hasArrayProperty(data, 'files')) return [];
+  return (data as { files: unknown[] }).files.filter(isFileMatch);
+}
+
+/**
+ * Extract pagination from data safely
+ */
+export function extractPagination(data: unknown): PaginationInfo | undefined {
+  if (!hasValidPagination(data)) return undefined;
+  return data.pagination;
+}
+
+/**
+ * Extract total matches from data safely
+ */
+export function extractTotalMatches(data: unknown): number {
+  if (hasProperty(data, 'totalMatches') && typeof data.totalMatches === 'number') {
+    return data.totalMatches;
+  }
+  if (hasValidPagination(data) && typeof data.pagination.totalMatches === 'number') {
+    return data.pagination.totalMatches;
+  }
+  return 0;
+}

package/skills/octocode-research/src/types/toolTypes.ts

@@ -0,0 +1,33 @@
+/**
+ * Type adapter for converting validated query inputs to MCP tool parameters.
+ * All MCP tools expect { queries: T[] } format.
+ *
+ * @module types/toolTypes
+ */
+
+/**
+ * Base query parameters that all tool queries may include.
+ */
+export interface BaseQueryParams {
+  mainResearchGoal?: string;
+  researchGoal?: string;
+  reasoning?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Result type for tool query parameters.
+ */
+export interface QueryParamsResult<T extends BaseQueryParams = BaseQueryParams> {
+  queries: T[];
+}
+
+/**
+ * Convert validated query to MCP tool format.
+ * Works for all tools - local, GitHub, LSP, and package search.
+ */
+export function toQueryParams<T extends BaseQueryParams>(
+  validated: T[]
+): QueryParamsResult<T> {
+  return { queries: validated };
+}