octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-research/.octocode/review/REVIEW_REPORT.md

@@ -0,0 +1,356 @@
+# Octocode Research Skill - Code Review Report
+
+> **Target**: `/Users/guybary/octocode-mcp/skills/octocode-research`
+> **Version**: 2.0.0
+> **Date**: 2026-01-16
+> **Reviewer**: Claude (automated review)
+
+---
+
+## Executive Summary
+
+The octocode-research skill is a well-architected Express.js HTTP server with strong security practices, comprehensive validation, and good resilience patterns. The main areas for improvement are **test coverage** and **documentation accuracy**.
+
+### Overall Assessment: **GOOD** with recommendations
+
+| Category | Rating | Notes |
+|----------|--------|-------|
+| Security | **A-** | Strong path validation, one medium-risk logging issue |
+| Architecture | **A** | Clean separation, proper middleware order |
+| Validation | **A** | Comprehensive Zod schemas with type-safe preprocessors |
+| Utilities | **B+** | Well-designed but responseBuilder is complex |
+| Testing | **C** | Critical coverage gaps in utilities |
+| Documentation | **B** | ARCHITECTURE.md has outdated endpoint references |
+
+---
+
+## 1. Security Review
+
+### 1.1 Path Traversal Protection - LOW RISK
+
+**File**: `src/validation/schemas.ts:48-56`
+
+**Implementation**:
+```typescript
+const safePath = z.string().refine(
+  (p) => {
+    const normalized = path.normalize(p);
+    if (normalized.includes('..')) return false;  // Blocks traversal
+    if (p.includes('\0')) return false;           // Blocks null byte
+    return true;
+  },
+  { message: 'Path contains invalid traversal patterns' }
+);
+```
+
+**Findings**:
+- Path normalization before `..` check is correct
+- Null byte injection properly blocked
+- All local routes use `safePath` validator
+- URL encoding handled by Express before validation
+
+**Recommendation**: Consider adding symlink traversal documentation warning.
+
+---
+
+### 1.2 Token Handling - LOW RISK
+
+**Files**: `src/routes/github.ts`, `src/validation/schemas.ts`
+
+**Findings**:
+- No token parameters in any HTTP route schemas
+- Token management delegated to `octocode-mcp/public` module
+- Tokens never appear in query parameters or logs
+
+**Verification**: Checked all 5 GitHub schemas - none accept token parameters.
+
+---
+
+### 1.3 Error Message Information Leakage - MEDIUM RISK
+
+**File**: `src/middleware/errorHandler.ts:21-29`
+
+**Issue**:
+```typescript
+if (isValidationError) {
+  logWarn(`[VALIDATION] ${req.method} ${req.path}: ${error.message}`, {
+    path: req.path,
+    query: req.query,    // <-- Full query params logged without sanitization
+    details: error.details,
+  });
+}
+```
+
+**Risk**: If sensitive data is inadvertently passed in query parameters, it will be logged to `~/.octocode/logs/errors.log`.
+
+**Recommendation**: Sanitize or mask sensitive query parameters before logging.
+
+**Client Response**: Safe - only Zod validation details exposed (acceptable for 400 errors), no stack traces.
+
+---
+
+## 2. Core Architecture Review
+
+### 2.1 Server Setup - GOOD
+
+**File**: `src/server.ts`
+
+**Middleware Order** (correct):
+1. `express.json()` - Parse JSON bodies
+2. `requestLogger` - Log requests
+3. Route handlers
+4. `errorHandler` - Catch errors (last)
+
+**Graceful Shutdown** (correct):
+- Handles SIGTERM, SIGINT
+- Stops context cleanup interval
+- 10-second forced shutdown timeout
+
+**Route Mounting**:
+```typescript
+app.use('/', localRoutes);     // /localSearchCode, etc.
+app.use('/', lspRoutes);       // /lspGotoDefinition, etc.
+app.use('/', githubRoutes);    // /githubSearchCode, etc.
+app.use('/', packageRoutes);   // /packageSearch
+app.use('/tools', toolsRoutes);
+app.use('/prompts', promptsRoutes);
+```
+
+---
+
+### 2.2 Middleware Review
+
+| Middleware | Status | Notes |
+|------------|--------|-------|
+| `requestLogger.ts` | GOOD | Clean request/response logging |
+| `errorHandler.ts` | GOOD | Proper error classification, safe responses |
+| `contextPropagation.ts` | OK | Mostly placeholder (cleanup logic empty) |
+| `queryParser.ts` | GOOD | Zod validation with batch mode support |
+
+**Note**: `contextPropagation.ts` contains dead code (interface defined but not used). The cleanup interval logs but doesn't actually clean anything.
+
+---
+
+## 3. Validation Review
+
+### 3.1 Schema Completeness - EXCELLENT
+
+**File**: `src/validation/schemas.ts` (623 lines)
+
+**Strengths**:
+- Type-safe preprocessors (`toNumber`, `toBoolean`, `toArray`)
+- Comprehensive field validation for all endpoints
+- Enum constraints prevent injection
+- Complex validation (e.g., `githubReposSchema` requires keywords OR topics)
+- Backwards compatibility via transform functions
+
+**Coverage**:
+- Local routes: 4 schemas
+- LSP routes: 3 schemas
+- GitHub routes: 5 schemas
+- Package routes: 1 schema
+
+All schemas properly validated against endpoint usage.
+
+---
+
+## 4. Utilities Review
+
+### 4.1 Response Builder
+
+**File**: `src/utils/responseBuilder.ts` (497 lines)
+
+**Assessment**: **NOT over-engineered**
+
+The file provides 7 specialized response formatters:
+- `searchResults` - Search result formatting
+- `fileContent` - File content with code fence
+- `lspResult` - LSP definition/reference/calls
+- `repoStructure` - Repository structure
+- `packageSearch` - Package search results
+- `pullRequests` - PR search results
+- `bulkResult` - Generic bulk operations
+
+**Design**:
+- Uses MCP role-based response API
+- Properly passes through MCP hints
+- Handles empty/paginated states
+- Language detection for syntax highlighting
+
+**Recommendation**: Well-designed, no refactoring needed.
+
+---
+
+### 4.2 Resilience Utilities
+
+**Files**: `circuitBreaker.ts`, `retry.ts`, `resilience.ts`
+
+**Circuit Breaker** (`circuitBreaker.ts:266 lines`):
+- Pre-configured for LSP (10s timeout, 3 failures)
+- Pre-configured for GitHub (60s timeout, 2 failures)
+- Proper state machine (closed → open → half-open → closed)
+- Manual reset capability
+
+**Retry** (`retry.ts:261 lines`):
+- Exponential backoff with max delay cap
+- Category-specific configs (LSP, GitHub, local, package)
+- Error type detection (rate limit, timeout, connection refused, etc.)
+
+**Integration** (`resilience.ts:114 lines`):
+- Circuit breaker wraps retry (correct order)
+- Clean category-based wrapper functions
+
+**Assessment**: Well-implemented resilience patterns.
+
+---
+
+### 4.3 Logger
+
+**File**: `src/utils/logger.ts` (298 lines)
+
+**Features**:
+- Log rotation at 10MB
+- Old log cleanup (keeps last 5)
+- Cross-platform paths (`~/.octocode/logs/`)
+- Graceful fallback on file write errors
+
+**Potential Issue**: Concurrent write safety not explicitly handled (Node.js `appendFileSync` should be atomic for small writes).
+
+---
+
+## 5. Testing Review
+
+### 5.1 Current Coverage
+
+| Test File | Lines | Coverage |
+|-----------|-------|----------|
+| `routes.test.ts` | 375 | All routes - validation and success cases |
+| `circuitBreaker.test.ts` | 206 | Full state machine coverage |
+
+### 5.2 Critical Test Gaps
+
+**CRITICAL - No tests**:
+
+| Utility | Lines | Risk |
+|---------|-------|------|
+| `responseBuilder.ts` | 497 | HIGH - 7 formatters untested |
+| `logger.ts` | 298 | MEDIUM - File I/O untested |
+| `retry.ts` | 261 | HIGH - Backoff logic untested |
+
+**HIGH - No tests**:
+
+| Utility | Lines | Risk |
+|---------|-------|------|
+| `resilience.ts` | 114 | MEDIUM - Integration untested |
+| `routeFactory.ts` | 113 | MEDIUM - Factory pattern untested |
+
+**MEDIUM - No tests**:
+
+| Utility | Lines | Risk |
+|---------|-------|------|
+| `responseParser.ts` | 152 | LOW - YAML parsing |
+| `responseFactory.ts` | 159 | LOW - Transformations |
+
+### 5.3 Test Recommendations (Priority Order)
+
+1. **responseBuilder.ts** - Test each formatter, pagination, empty states
+2. **retry.ts** - Test backoff calculation, error detection functions
+3. **logger.ts** - Test rotation, fallback, cross-platform paths
+4. **resilience.ts** - Test circuit breaker + retry integration
+
+---
+
+## 6. Documentation Review
+
+### 6.1 SKILL.md - ACCURATE
+
+Comprehensive skill guide with:
+- Execution lifecycle
+- Prompt selection matrix
+- API format examples
+- Security guardrails
+
+**Status**: Up-to-date with actual implementation.
+
+### 6.2 ARCHITECTURE.md - OUTDATED
+
+**Issues Found**:
+
+1. **Endpoint references incorrect**:
+   - Document says: `/local/search`, `/lsp/definition`
+   - Actual routes: `/localSearchCode`, `/lspGotoDefinition`
+
+2. **Directory structure incomplete**:
+   - Missing: `routes/tools.ts`, `routes/prompts.ts`
+   - Lists non-existent: `rateLimitHandler.ts`
+
+3. **Known Issues section**:
+   - References `rawResult.structuredContent` issue - may be outdated
+
+**Recommendation**: Update ARCHITECTURE.md endpoint table and directory structure.
+
+---
+
+## 7. Prioritized Recommendations
+
+### Priority 1 - Critical
+
+| # | Issue | File | Action |
+|---|-------|------|--------|
+| 1 | Test coverage gaps | `__tests__/` | Add unit tests for utilities |
+| 2 | Query param logging | `errorHandler.ts:24` | Sanitize sensitive params |
+
+### Priority 2 - Important
+
+| # | Issue | File | Action |
+|---|-------|------|--------|
+| 3 | Documentation mismatch | `ARCHITECTURE.md` | Update endpoint references |
+| 4 | Dead code | `contextPropagation.ts` | Remove unused context tracking |
+
+### Priority 3 - Nice to Have
+
+| # | Issue | File | Action |
+|---|-------|------|--------|
+| 5 | Coverage thresholds | `vitest.config.ts` | Add minimum coverage requirements |
+| 6 | Symlink warning | `SKILL.md` | Document `followSymlinks` security note |
+
+---
+
+## 8. Verification Checklist
+
+Run after making changes:
+
+```bash
+# Run existing tests
+npm test
+
+# Build project
+npm run build
+
+# Start server
+npm run server:start
+
+# Test health endpoint
+curl http://localhost:1987/health
+
+# Test sample endpoint
+curl "http://localhost:1987/localSearchCode?pattern=export&path=/src"
+```
+
+---
+
+## Appendix: Files Reviewed
+
+| Category | Files |
+|----------|-------|
+| Server | `server.ts`, `index.ts`, `mcpCache.ts` |
+| Routes | `local.ts`, `github.ts`, `lsp.ts`, `package.ts`, `tools.ts`, `prompts.ts` |
+| Middleware | `errorHandler.ts`, `logger.ts`, `contextPropagation.ts`, `queryParser.ts` |
+| Validation | `schemas.ts` |
+| Utilities | `responseBuilder.ts`, `circuitBreaker.ts`, `retry.ts`, `resilience.ts`, `logger.ts` |
+| Tests | `routes.test.ts`, `circuitBreaker.test.ts` |
+| Docs | `SKILL.md`, `ARCHITECTURE.md` |
+
+---
+
+*Generated by automated code review*

package/skills/octocode-research/AGENTS.md

@@ -0,0 +1,349 @@
+# Octocode Research Skill - Agent Development Guide
+
+> HTTP API server wrapping `octocode-mcp` tools for code research at `localhost:1987` by default (configurable via `OCTOCODE_RESEARCH_HOST` / `OCTOCODE_RESEARCH_PORT`)
+
+## Project Overview
+
+| Attribute | Value |
+|-----------|-------|
+| **Type** | Express.js HTTP Server |
+| **Host** | localhost (default) |
+| **Port** | 1987 (default) |
+| **Package** | `octocode-research` |
+| **Version** | 2.0.0 |
+| **Main Dependency** | `octocode-mcp` |
+
+---
+
+## Quick Commands
+
+```bash
+# Development
+npm run build       # Bundle with tsdown
+npm start           # Run bundled server
+npm run dev         # Run with tsx watch mode
+npm test            # Run tests with Vitest
+npm run test:watch  # Watch mode testing
+npm run lint        # ESLint check
+npm run lint:fix    # Auto-fix lint issues
+
+# Server Health Check
+curl http://localhost:1987/health
+```
+
+---
+
+## Project Structure
+
+```
+octocode-research/
+├── src/
+│   ├── server.ts              # Express server entry point
+│   ├── index.ts               # Re-exports from octocode-mcp
+│   ├── mcpCache.ts            # MCP client caching
+│   ├── routes/
+│   │   ├── local.ts           # Local tool handlers (used in tests)
+│   │   ├── lsp.ts             # LSP tool handlers (used in tests)
+│   │   ├── github.ts          # GitHub tool handlers (used in tests)
+│   │   ├── package.ts         # Package tool handlers (used in tests)
+│   │   ├── tools.ts           # /tools/* - MAIN tool API (mounted)
+│   │   └── prompts.ts         # /prompts/* - prompt discovery (mounted)
+│   ├── middleware/
+│   │   ├── errorHandler.ts    # Error response formatting
+│   │   ├── logger.ts          # Request/response logging
+│   │   ├── queryParser.ts     # Zod validation
+│   │   └── readiness.ts       # Server readiness check
+│   ├── validation/
+│   │   ├── index.ts           # Schema exports
+│   │   ├── schemas.ts         # HTTP schemas (import from octocode-mcp)
+│   │   └── httpPreprocess.ts  # HTTP query string preprocessing
+│   ├── utils/
+│   │   ├── colors.ts          # Console color functions
+│   │   ├── logger.ts          # File-based logging
+│   │   ├── responseBuilder.ts # Role-based response formatting
+│   │   ├── responseFactory.ts # Response creation helpers
+│   │   ├── responseParser.ts  # MCP response parsing
+│   │   ├── resilience.ts      # Resilience utilities
+│   │   ├── retry.ts           # Retry with backoff
+│   │   ├── circuitBreaker.ts  # Circuit breaker pattern
+│   │   └── routeFactory.ts    # Route handler factory
+│   ├── types/
+│   │   ├── express.d.ts       # Express type extensions
+│   │   ├── guards.ts          # Type guard functions
+│   │   ├── mcp.ts             # MCP protocol types
+│   │   ├── responses.ts       # Response types
+│   │   └── toolTypes.ts       # Tool parameter types
+│   └── __tests__/
+│       ├── integration/       # Integration tests
+│       │   ├── circuitBreaker.test.ts
+│       │   └── routes.test.ts
+│       └── unit/              # Unit tests
+│           ├── circuitBreaker.test.ts
+│           ├── logger.test.ts
+│           ├── responseBuilder.test.ts
+│           └── retry.test.ts
+├── docs/
+│   ├── API_REFERENCE.md       # Complete HTTP API reference
+│   ├── ARCHITECTURE.md        # Architecture documentation
+│   └── FLOWS.md               # Main flows & connections
+├── references/
+│   └── GUARDRAILS.md          # Safety guardrails
+├── scripts/                   # Bundled output
+│   ├── server.js              # Bundled server
+│   └── server.d.ts            # Type declarations
+├── SKILL.md                   # Skill definition for AI agents
+├── AGENTS.md                  # This file
+├── tsdown.config.ts           # tsdown bundler configuration
+├── package.json
+├── tsconfig.json
+├── eslint.config.mjs
+└── vitest.config.ts           # Test configuration
+```
+
+---
+
+## API Endpoints
+
+### Available Routes
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Server health check |
+| `GET /tools/list` | List all tools (concise) |
+| `GET /tools/info` | List all tools with details |
+| `GET /tools/info/:toolName` | Get specific tool schema (call BEFORE using!) |
+| `GET /tools/system` | Get system prompt (load FIRST) |
+| `GET /tools/initContext` | Combined system prompt + all tool schemas (recommended for init) |
+| `POST /tools/call/:toolName` | **Execute any tool** |
+| `GET /prompts/list` | List all prompts |
+| `GET /prompts/info/:promptName` | Get specific prompt content |
+
+### Tool Execution (Unified API)
+
+**All tools are called via `POST /tools/call/:toolName`** with JSON body:
+
+```bash
+curl -X POST http://localhost:1987/tools/call/localSearchCode \
+  -H "Content-Type: application/json" \
+  -d '{"queries":[{
+    "pattern":"useState",
+    "path":"/project",
+    "mainResearchGoal":"Find React hooks",
+    "researchGoal":"Locate useState",
+    "reasoning":"Need source location"
+  }]}'
+```
+
+### Available Tools (via `/tools/call/:toolName`)
+
+| Tool Name | Category | Description |
+|-----------|----------|-------------|
+| `localSearchCode` | Local | Code search via ripgrep |
+| `localGetFileContent` | Local | Read file content |
+| `localFindFiles` | Local | Find files by pattern/metadata |
+| `localViewStructure` | Local | View directory tree |
+| `lspGotoDefinition` | LSP | Go to symbol definition |
+| `lspFindReferences` | LSP | Find all references |
+| `lspCallHierarchy` | LSP | Call hierarchy (incoming/outgoing) |
+| `githubSearchCode` | GitHub | Search GitHub code |
+| `githubGetFileContent` | GitHub | Read GitHub files |
+| `githubSearchRepositories` | GitHub | Search repositories |
+| `githubViewRepoStructure` | GitHub | View repo structure |
+| `githubSearchPullRequests` | GitHub | Search pull requests |
+| `packageSearch` | Package | Search npm/PyPI packages |
+
+---
+
+## Key Files & Responsibilities
+
+### Entry Points
+
+| File | Purpose |
+|------|---------|
+| `src/server.ts` | Express app creation, route mounting, graceful shutdown |
+| `src/index.ts` | Re-exports octocode-mcp functions with cleaner names |
+| `src/mcpCache.ts` | MCP client instance caching and management |
+
+### Routes
+
+Each route file follows the pattern:
+1. Import tool function from `../index.js`
+2. Define Express Router
+3. Apply validation middleware
+4. Execute tool and format response
+
+### Middleware
+
+| File | Purpose |
+|------|---------|
+| `queryParser.ts` | Validates query params against Zod schemas |
+| `errorHandler.ts` | Catches errors, formats consistent responses |
+| `logger.ts` | Logs requests to console and file |
+| `readiness.ts` | Server readiness check middleware |
+
+### Validation
+
+Schemas are imported from `octocode-mcp/public` (source of truth) and wrapped with HTTP preprocessing.
+
+| File | Purpose |
+|------|---------|
+| `schemas.ts` | HTTP-wrapped schemas importing from `octocode-mcp/public` |
+| `httpPreprocess.ts` | Query string conversion (string→number/boolean/array) |
+
+When adding/modifying endpoints:
+1. Check if schema exists in `octocode-mcp/public`
+2. Create HTTP wrapper in `validation/schemas.ts` with preprocessing
+3. Apply schema validation in route handler
+
+---
+
+## Development Guidelines
+
+### Adding a New Endpoint
+
+1. **Add schema** in `src/validation/schemas.ts`
+2. **Create route handler** in appropriate `src/routes/*.ts`
+3. **Add route to server.ts** if new route group
+4. **Update types** if needed
+5. **Add tests** in `src/__tests__/`
+6. **Document** in docs/ARCHITECTURE.md
+
+### Code Style
+
+- **TypeScript strict mode** enabled
+- **Zod** for runtime validation
+- **Express async handlers** - wrap with try/catch or error middleware
+- **Consistent logging** - use `agentLog`, `successLog`, `errorLog` from colors.ts
+
+### Testing
+
+```bash
+yarn test                 # Run all tests
+yarn test:watch          # Watch mode
+yarn test -- --coverage  # With coverage report
+```
+
+---
+
+## Response Format
+
+### Single Query Response (`POST /tools/call/:toolName`)
+
+```typescript
+{
+  tool: "localSearchCode",
+  success: true,
+  data: { files: [...], totalMatches: 10 },
+  hints: ["Use lineHint for LSP tools", ...],
+  research: {
+    mainResearchGoal: "...",
+    researchGoal: "...",
+    reasoning: "..."
+  }
+}
+```
+
+### Bulk Query Response (2-3 queries)
+
+```typescript
+{
+  tool: "localSearchCode",
+  bulk: true,
+  success: true,
+  instructions: "...",
+  results: [
+    { id: 1, status: "hasResults", data: {...}, research: {...} },
+    { id: 2, status: "empty", data: {...}, research: {...} }
+  ],
+  hints: { hasResults: [...], empty: [...], error: [...] },
+  counts: { total: 2, hasResults: 1, empty: 1, error: 0 }
+}
+```
+
+### Error Response
+
+```typescript
+{
+  tool: "localSearchCode",
+  success: false,
+  data: {},
+  hints: ["Error recovery hint..."],
+  research: {...}
+}
+```
+
+---
+
+## Key Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `octocode-mcp` | Core tool implementations |
+| `express` | HTTP server framework |
+| `zod` | Schema validation |
+| `@modelcontextprotocol/sdk` | MCP format types |
+
+---
+
+## Documentation References
+
+| Doc | Purpose |
+|-----|---------|
+| [SKILL.md](./SKILL.md) | How AI agents should USE this skill |
+| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Detailed architecture |
+| [docs/FLOWS.md](./docs/FLOWS.md) | Main flows & component connections |
+
+---
+
+## Console Output Colors
+
+| Category | Color | Function |
+|----------|-------|----------|
+| Agent messages | 🟣 Purple | `agentLog()` |
+| Tool results | 🔵 Blue | `resultLog()` |
+| Success | 🟢 Green | `successLog()` |
+| Errors | 🔴 Red | `errorLog()` |
+| Warnings | 🟡 Yellow | `warnLog()` |
+| Secondary info | Gray | `dimLog()` |
+
+---
+
+## Troubleshooting
+
+### Server won't start
+```bash
+# Check if port 1987 is in use
+lsof -i :1987
+
+# Kill existing process
+kill -9 $(lsof -ti :1987)
+```
+
+### Build errors
+```bash
+# Clean and rebuild
+rm -rf scripts/
+npm run build
+```
+
+### Missing dependencies
+```bash
+# Reinstall
+rm -rf node_modules/
+yarn install
+```
+
+---
+
+## Access Control
+
+| Path | Access |
+|------|--------|
+| `src/`, `src/__tests__/` | ✅ Auto |
+| `docs/`, `references/` | ✅ Auto |
+| `*.json`, `*.config.*` | ⚠️ Ask first |
+| `.env*`, `node_modules/`, `scripts/` | ❌ Never modify |
+
+---
+
+*This skill wraps `octocode-mcp` tools as HTTP endpoints. For tool-specific documentation, see the [octocode-mcp package](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/AGENTS.md).*