octocode-cli 1.2.6 → 1.2.7

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

@@ -0,0 +1,371 @@
+# Code Review: octocode-research Skill
+
+**Date:** 2026-01-22
+**Target:** `/Users/guybary/Documents/octocode-mcp/skills/octocode-research`
+**Version:** 2.2.0
+**Overall Rating:** ⭐⭐⭐⭐☆ (Good Quality)
+
+---
+
+## Research Goal
+
+Comprehensive code review of the octocode-research skill covering architecture, API routes, utilities, middleware, validation, types, and test coverage.
+
+---
+
+## Answer (TL;DR)
+
+The codebase demonstrates **mature engineering practices** with clean architecture, comprehensive type safety via Zod schemas, and thoughtful resilience patterns (circuit breaker, retry, timeout). Key strengths include race condition prevention in server initialization, strong path traversal security, and a well-designed route factory pattern.
+
+**Primary concerns requiring attention:**
+1. Missing jitter in retry backoff (thundering herd risk)
+2. No rate limiting middleware
+3. Test coverage gaps for security-critical code (`safePath`, `readiness.ts`)
+4. Some `any` types in Express declarations weakening type safety
+
+---
+
+## Details
+
+### Codebase Structure
+
+```
+src/
+├── index.ts              # Entry point/exports
+├── server.ts             # Main HTTP server (~8.9KB)
+├── server-init.ts        # Initialization with locking (~10.2KB)
+├── mcpCache.ts           # MCP content caching
+├── middleware/
+│   ├── errorHandler.ts   # Centralized error handling
+│   ├── logger.ts         # Request logging with correlation IDs
+│   ├── queryParser.ts    # Batch query parsing
+│   └── readiness.ts      # Initialization gate
+├── routes/
+│   ├── github.ts         # GitHub API routes
+│   ├── local.ts          # Local file operations
+│   ├── lsp.ts            # LSP integration
+│   ├── package.ts        # Package search
+│   ├── prompts.ts        # Prompt management
+│   └── tools.ts          # Tool execution (~20.2KB, largest)
+├── types/
+│   ├── errorGuards.ts    # Error type guards
+│   ├── express.d.ts      # Express type augmentation
+│   ├── guards.ts         # General type guards
+│   ├── mcp.ts            # MCP types
+│   ├── responses.ts      # Response types
+│   └── toolTypes.ts      # Tool parameter types
+├── utils/
+│   ├── circuitBreaker.ts # Circuit breaker pattern (~14.1KB)
+│   ├── retry.ts          # Retry with backoff
+│   ├── resilience.ts     # Resilience composition
+│   ├── responseBuilder.ts # Response construction
+│   ├── logger.ts         # File logging with rotation
+│   └── ... (8 more utilities)
+└── validation/
+    ├── schemas.ts        # Zod validation schemas (~18.7KB)
+    ├── toolCallSchema.ts # Tool call validation
+    └── httpPreprocess.ts # HTTP input preprocessing
+```
+
+**Stats:** 45 TypeScript files, 8 directories, ~260KB source code
+
+---
+
+## Code Flows
+
+### Server Startup Flow
+
+```
+npm run server-init
+       │
+       ▼
+┌─────────────────────┐
+│  server-init.ts     │
+│  - Acquire lock     │
+│  - Check health     │
+│  - Start if needed  │
+└─────────────────────┘
+       │
+       ▼
+┌─────────────────────┐
+│  server.ts          │
+│  - Create Express   │
+│  - Mount routes     │
+│  - Initialize MCP   │
+│  - PM2 ready signal │
+└─────────────────────┘
+       │
+       ▼
+┌─────────────────────┐
+│  Idle monitoring    │
+│  - 30min timeout    │
+│  - Auto-restart     │
+└─────────────────────┘
+```
+
+### Request Flow
+
+```
+Request
+   │
+   ▼
+┌──────────────────┐
+│ express.json()   │
+└──────────────────┘
+   │
+   ▼
+┌──────────────────┐
+│ Activity tracker │
+└──────────────────┘
+   │
+   ▼
+┌──────────────────┐
+│ requestLogger    │
+│ (X-Request-ID)   │
+└──────────────────┘
+   │
+   ▼
+┌──────────────────┐
+│ readinessCheck   │
+│ (503 if init)    │
+└──────────────────┘
+   │
+   ▼
+┌──────────────────┐
+│ Route handler    │
+│ ┌──────────────┐ │
+│ │ Validation   │ │
+│ │ (Zod schema) │ │
+│ └──────────────┘ │
+│ ┌──────────────┐ │
+│ │ Resilience   │ │
+│ │ timeout →    │ │
+│ │ circuit →    │ │
+│ │ retry        │ │
+│ └──────────────┘ │
+│ ┌──────────────┐ │
+│ │ MCP Tool     │ │
+│ └──────────────┘ │
+│ ┌──────────────┐ │
+│ │ Response     │ │
+│ │ Builder      │ │
+│ └──────────────┘ │
+└──────────────────┘
+   │
+   ▼
+┌──────────────────┐
+│ errorHandler     │
+│ (if error)       │
+└──────────────────┘
+   │
+   ▼
+Response
+```
+
+### Resilience Layer
+
+```
+withGitHubResilience(operation)
+         │
+         ▼
+┌─────────────────────────┐
+│ withTimeout (30s)       │
+│ ┌─────────────────────┐ │
+│ │ withCircuitBreaker  │ │
+│ │ ┌─────────────────┐ │ │
+│ │ │ withRetry       │ │ │
+│ │ │ (3 attempts,    │ │ │
+│ │ │  exp backoff)   │ │ │
+│ │ └─────────────────┘ │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+---
+
+## Key Findings
+
+### Strengths
+
+#### 1. Race Condition Prevention (`server-init.ts:60-130`)
+- File-based locking with PID tracking
+- Stale lock detection (checks if PID process is alive)
+- Atomic lock acquisition using `O_CREAT | O_EXCL` flags
+- Exponential backoff in health polling
+
+#### 2. Path Security (`httpPreprocess.ts:64-108`)
+```typescript
+export const safePath = z.string().refine((p) => {
+  if (p.includes('\0')) return false;              // Null byte injection
+  const normalized = path.normalize(p);
+  if (normalized.includes('..')) return false;     // Directory traversal
+  if (os.platform() !== 'win32' && p.includes('\\')) return false;
+  // URL-encoded traversal patterns checked
+});
+```
+
+#### 3. Circuit Breaker Implementation (`circuitBreaker.ts`)
+- Clean state machine (closed → open → half-open → closed)
+- Memory leak prevention with `cleanupStaleCircuits()`, MAX_CIRCUITS=100
+- Per-tool circuit isolation
+- `CircuitOpenError` includes `retryAfterMs` for informed backoff
+
+#### 4. Route Factory Pattern (`routeFactory.ts:21-45`)
+```typescript
+export function createRouteHandler<TQuery, TParams, TResponse>(
+  config: RouteConfig<TQuery, TParams, TResponse>
+): RequestHandler {
+  // Consistent: validation → resilience → transform → response
+}
+```
+
+#### 5. Comprehensive Type Guards (`types/guards.ts`, `types/errorGuards.ts`)
+- Properly narrowing type guards using `is` return types
+- Utility functions: `hasProperty`, `hasStringProperty`, `getErrorStatus`
+
+### Issues
+
+#### High Priority
+
+| Issue | File:Line | Impact |
+|-------|-----------|--------|
+| Missing jitter in retry backoff | `retry.ts:129` | Thundering herd on rate limits |
+| No rate limiting middleware | All routes | Abuse/DDoS vulnerability |
+| Test setup doesn't match server | `routes.test.ts:78-81` | Tests may pass but miss real bugs |
+| No tests for safePath validator | `httpPreprocess.ts` | Security code untested |
+
+#### Medium Priority
+
+| Issue | File:Line | Impact |
+|-------|-----------|--------|
+| `any` types in Express declarations | `express.d.ts:16,24,25,28,37` | Loses type safety |
+| Pre-configured circuits can be deleted | `circuitBreaker.ts:415-419` | Circuits lose custom config |
+| package.ts doesn't use factory | `package.ts:14-40` | Inconsistent error handling |
+| GET routes lack MAX_QUERIES check | `queryParser.ts` | Resource exhaustion |
+| No path length validation | `httpPreprocess.ts` | DoS via long paths |
+| Initialization resolves early | `server.ts:225-248` | Callers may assume ready |
+
+#### Low Priority
+
+| Issue | File:Line | Impact |
+|-------|-----------|--------|
+| Hardcoded PORT, timeouts | `server.ts:16-18` | Inflexible deployment |
+| Inconsistent logging (emojis) | `circuitBreaker.ts` | Log parsing issues |
+| AbortController not passed through | `tools.ts` POST handler | Can't cancel mid-flight |
+| Untyped catch blocks | Multiple files | Weaker type safety |
+
+---
+
+## Edge Cases / Caveats
+
+### Known Limitations
+
+1. **Comma in query values** - `toArray` preprocessor splits on comma without escaping, so values containing commas will be incorrectly split
+
+2. **Float handling** - `toNumber` preprocessor only handles integers (`/^\d+$/`), floats passed as strings
+
+3. **404 handler isolation** - 404 handler sends response directly without calling `next()`, so it bypasses errorHandler middleware
+
+4. **Test environment drift** - Integration tests mount routes at `/` instead of `/tools`, may miss path-related bugs
+
+### Security Considerations
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Path Traversal | ✅ Protected | Multiple attack vectors blocked |
+| Input Validation | ✅ Comprehensive | Zod schemas on all inputs |
+| Error Exposure | ⚠️ Partial | Validation details exposed to clients |
+| Rate Limiting | ❌ Missing | Add express-rate-limit |
+| DoS Prevention | ⚠️ Partial | No path length limit |
+
+---
+
+## Recommendations
+
+### Immediate Actions
+
+```typescript
+// 1. Add jitter to retry.ts:129
+const jitter = 0.5 + Math.random(); // 0.5 to 1.5
+delay = Math.min(delay * config.backoffMultiplier * jitter, config.maxDelayMs);
+
+// 2. Add rate limiting to server.ts
+import rateLimit from 'express-rate-limit';
+app.use(rateLimit({ windowMs: 60000, max: 100 }));
+
+// 3. Add path length validation to httpPreprocess.ts
+if (p.length > 4096) return false; // Before other checks
+```
+
+### Short-term
+
+4. Add unit tests for `safePath` security validation
+5. Add unit tests for `readiness.ts` middleware
+6. Refactor `package.ts` to use `createRouteHandler`
+7. Fix `routes.test.ts` to mount at `/tools` with full middleware
+
+### Long-term
+
+8. Replace `any` with `unknown` in Express type declarations
+9. Extract configuration to environment variables
+10. Consider OpenAPI spec generation from Zod schemas
+11. Add structured JSON logging option for production
+
+---
+
+## Test Coverage Summary
+
+| Component | Tested | Missing |
+|-----------|--------|---------|
+| Circuit breaker | ✅ Excellent | - |
+| Retry logic | ✅ Excellent | - |
+| Response builder | ✅ Excellent | - |
+| Error handler | ✅ Good | Stack trace exposure |
+| Logger | ⚠️ Partial | requestLogger middleware |
+| Query parser | ⚠️ Partial | parseAndValidate function |
+| Schemas | ⚠️ Partial | Transform functions |
+| Readiness | ❌ None | Full middleware |
+| safePath | ❌ None | Security validation |
+| Routes integration | ⚠️ Fair | Config doesn't match server |
+
+---
+
+## References
+
+### Architecture & Entry Points
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/server.ts` - Main server
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/server-init.ts` - Initialization
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/index.ts` - Exports
+
+### Routes
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/routes/tools.ts` - Tool execution (largest)
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/routes/github.ts` - GitHub API
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/routes/local.ts` - Local files
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/routes/lsp.ts` - LSP integration
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/routes/package.ts` - Package search
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/routes/prompts.ts` - Prompts
+
+### Utilities
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/utils/circuitBreaker.ts` - Circuit breaker
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/utils/retry.ts` - Retry logic
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/utils/resilience.ts` - Resilience composition
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/utils/responseBuilder.ts` - Response building
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/utils/logger.ts` - File logging
+
+### Validation
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/validation/schemas.ts` - Zod schemas
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/validation/httpPreprocess.ts` - Security validation
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/validation/toolCallSchema.ts` - Tool call validation
+
+### Types
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/types/express.d.ts` - Express augmentation
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/types/guards.ts` - Type guards
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/types/errorGuards.ts` - Error guards
+
+### Tests
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/__tests__/unit/` - Unit tests
+- `/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src/__tests__/integration/` - Integration tests
+
+---
+
+Created by Octocode Research Agent 🔍🐙