octocode-cli 1.2.6 → 1.2.8

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

@@ -0,0 +1,391 @@
+# Octocode Research Skill - Improvements
+
+> **Generated from**: Code Review (2026-01-16)
+> **Status**: Proposed
+> **Priority Scale**: P0 (Critical) → P1 (High) → P2 (Medium) → P3 (Low)
+
+---
+
+## Summary
+
+This document outlines actionable improvements identified during the code review. Items are organized by priority and include implementation guidance.
+
+---
+
+## P0 - Critical
+
+### 1. Add Unit Tests for Utility Functions
+
+**Status**: Not Started
+**Effort**: Medium (2-3 days)
+**Risk if unaddressed**: Breaking changes go undetected, regression risk
+
+#### Files Needing Tests
+
+| File | Lines | Priority | Test Focus |
+|------|-------|----------|------------|
+| `responseBuilder.ts` | 497 | **Critical** | 7 formatters, pagination, empty states |
+| `retry.ts` | 261 | **Critical** | Backoff calculation, error detection |
+| `logger.ts` | 298 | **High** | File rotation, fallback, cross-platform |
+| `resilience.ts` | 114 | **High** | Circuit breaker + retry integration |
+| `routeFactory.ts` | 113 | **Medium** | Factory pattern, validation pipeline |
+| `responseParser.ts` | 152 | **Medium** | YAML parsing, hints extraction |
+
+#### Implementation Plan
+
+1. Create `src/__tests__/unit/` directory
+2. Add tests for `responseBuilder.ts`:
+   ```typescript
+   // responseBuilder.test.ts
+   describe('ResearchResponse', () => {
+     describe('searchResults', () => {
+       it('formats files with match counts')
+       it('handles empty results')
+       it('adds pagination hints when hasMore')
+       it('truncates file list at 10 files')
+     })
+     describe('fileContent', () => {
+       it('formats content with code fence')
+       it('detects language from extension')
+       it('includes line range info')
+     })
+     // ... other formatters
+   })
+   ```
+
+3. Add tests for `retry.ts`:
+   ```typescript
+   // retry.test.ts
+   describe('withRetry', () => {
+     it('returns immediately on success')
+     it('retries on retryable error')
+     it('throws on non-retryable error')
+     it('applies exponential backoff')
+     it('caps delay at maxDelayMs')
+   })
+   describe('error detection', () => {
+     it('isRateLimited detects 429 status')
+     it('isTimeout detects ETIMEDOUT')
+     // ... other error types
+   })
+   ```
+
+4. Update `vitest.config.ts` with coverage thresholds:
+   ```typescript
+   coverage: {
+     thresholds: {
+       statements: 70,
+       branches: 60,
+       functions: 70,
+       lines: 70,
+     }
+   }
+   ```
+
+---
+
+## P1 - High Priority
+
+### 2. Sanitize Query Parameters in Error Logs
+
+**Status**: Not Started
+**Effort**: Small (1-2 hours)
+**Risk if unaddressed**: Sensitive data exposure in logs
+
+**File**: `src/middleware/errorHandler.ts:21-26`
+
+**Current Code**:
+```typescript
+logWarn(`[VALIDATION] ${req.method} ${req.path}: ${error.message}`, {
+  path: req.path,
+  query: req.query,  // Full query params logged
+  details: error.details,
+});
+```
+
+**Proposed Fix**:
+```typescript
+const sanitizedQuery = sanitizeQueryParams(req.query);
+logWarn(`[VALIDATION] ${req.method} ${req.path}: ${error.message}`, {
+  path: req.path,
+  query: sanitizedQuery,
+  details: error.details,
+});
+
+// Add to utils/logger.ts or separate file
+function sanitizeQueryParams(query: Record<string, unknown>): Record<string, unknown> {
+  const sensitiveKeys = ['token', 'key', 'secret', 'password', 'auth', 'credential'];
+  const sanitized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(query)) {
+    const isaSensitive = sensitiveKeys.some(s => key.toLowerCase().includes(s));
+    sanitized[key] = isSensitive ? '[REDACTED]' : value;
+  }
+
+  return sanitized;
+}
+```
+
+---
+
+### 3. Update ARCHITECTURE.md Documentation
+
+**Status**: Not Started
+**Effort**: Small (1 hour)
+**Risk if unaddressed**: Developer confusion, onboarding friction
+
+**Issues**:
+
+1. **Endpoint table uses wrong paths**:
+   - Document: `/local/search`, `/lsp/definition`, `/github/search`
+   - Actual: `/localSearchCode`, `/lspGotoDefinition`, `/githubSearchCode`
+
+2. **Directory structure incomplete**:
+   - Missing: `routes/tools.ts`, `routes/prompts.ts`
+   - Lists non-existent: `rateLimitHandler.ts`
+
+3. **Data flow diagram outdated**:
+   - References old route paths
+
+**Action**: Update all endpoint references to match actual routes in `server.ts`.
+
+---
+
+### 4. Remove Dead Code in Context Propagation
+
+**Status**: Not Started
+**Effort**: Small (30 minutes)
+**Risk if unaddressed**: Code confusion, maintenance burden
+
+**File**: `src/middleware/contextPropagation.ts`
+
+**Current State**:
+- `ResearchContext` interface defined but never used
+- Cleanup interval logs but doesn't clean anything
+- No actual context tracking implemented
+
+**Options**:
+
+A. **Remove entirely** (if not planned):
+   - Delete `contextPropagation.ts`
+   - Remove import from `server.ts`
+   - Keep `stopContextCleanup` as no-op for shutdown compatibility
+
+B. **Implement properly** (if needed):
+   - Add actual context storage (Map with session ID)
+   - Implement cleanup logic (remove stale sessions)
+   - Wire up to routes for session tracking
+
+**Recommendation**: Option A - Remove unless there's a planned use case.
+
+---
+
+## P2 - Medium Priority
+
+### 5. Add Coverage Thresholds to Vitest Config
+
+**Status**: Not Started
+**Effort**: Small (15 minutes)
+
+**File**: `vitest.config.ts`
+
+**Current**:
+```typescript
+coverage: {
+  provider: 'v8',
+  reporter: ['text', 'html'],
+  include: ['src/**/*.ts'],
+  exclude: ['src/__tests__/**', 'src/types/**'],
+}
+```
+
+**Proposed**:
+```typescript
+coverage: {
+  provider: 'v8',
+  reporter: ['text', 'html', 'lcov'],
+  include: ['src/**/*.ts'],
+  exclude: ['src/__tests__/**', 'src/types/**'],
+  thresholds: {
+    statements: 70,
+    branches: 60,
+    functions: 70,
+    lines: 70,
+  }
+}
+```
+
+---
+
+### 6. Document Symlink Security Consideration
+
+**Status**: Not Started
+**Effort**: Small (15 minutes)
+
+**File**: `SKILL.md` or `docs/SECURITY.md`
+
+**Issue**: The `followSymlinks` option in local routes could allow traversal outside intended directories via symlinks.
+
+**Proposed Documentation**:
+```markdown
+### Symlink Handling
+
+The `followSymlinks` option (default: `false`) controls whether symbolic links
+are followed during file operations.
+
+**Security Note**: When enabled, symlinks could point to files outside the
+intended search directory. Only enable this option when:
+- You control the directory structure
+- Symlinks are intentional and trusted
+- The server is not exposed to untrusted users
+```
+
+---
+
+### 7. Improve Error Type Detection in Retry Logic
+
+**Status**: Not Started
+**Effort**: Small (1 hour)
+
+**File**: `src/utils/retry.ts`
+
+**Current Issue**: Error detection relies on string matching which is fragile.
+
+**Example**:
+```typescript
+function isLspNotReady(err: unknown): boolean {
+  const error = err as { message?: string; code?: string };
+  return (
+    error?.message?.includes('not initialized') ||  // Fragile
+    error?.message?.includes('server not started') ||
+    error?.message?.includes('LSP') ||  // Too broad
+    error?.code === 'LSP_NOT_READY' ||
+    false
+  );
+}
+```
+
+**Proposed Improvement**:
+```typescript
+// Define error codes as constants
+const LSP_ERROR_CODES = ['LSP_NOT_READY', 'LSP_NOT_INITIALIZED', 'ECONNREFUSED'] as const;
+const LSP_ERROR_PATTERNS = [/not initialized/i, /server not started/i] as const;
+
+function isLspNotReady(err: unknown): boolean {
+  const error = err as { message?: string; code?: string };
+
+  // Check error codes first (more reliable)
+  if (error?.code && LSP_ERROR_CODES.includes(error.code as any)) {
+    return true;
+  }
+
+  // Fall back to message patterns
+  if (error?.message) {
+    return LSP_ERROR_PATTERNS.some(pattern => pattern.test(error.message!));
+  }
+
+  return false;
+}
+```
+
+---
+
+## P3 - Low Priority
+
+### 8. Add Request ID for Log Correlation
+
+**Status**: Not Started
+**Effort**: Small (1-2 hours)
+
+Add request ID header support for correlating logs across requests.
+
+**Implementation**:
+```typescript
+// middleware/requestId.ts
+import { randomUUID } from 'crypto';
+
+export function requestIdMiddleware(req: Request, res: Response, next: NextFunction) {
+  req.id = req.headers['x-request-id'] as string || randomUUID();
+  res.setHeader('x-request-id', req.id);
+  next();
+}
+
+// Update logger to include request ID
+function logToolCall(entry: ToolLogEntry & { requestId?: string }) {
+  // ...
+}
+```
+
+---
+
+### 9. Add Health Check Details
+
+**Status**: Not Started
+**Effort**: Small (30 minutes)
+
+Enhance `/health` endpoint with more diagnostic info.
+
+**Current**:
+```typescript
+res.json({ status: 'ok', port: PORT, version: '2.0.0' });
+```
+
+**Proposed**:
+```typescript
+res.json({
+  status: 'ok',
+  port: PORT,
+  version: '2.0.0',
+  uptime: process.uptime(),
+  memory: process.memoryUsage(),
+  circuits: {
+    lsp: getCircuitState('lsp'),
+    github: getCircuitState('github'),
+  }
+});
+```
+
+---
+
+### 10. Consider Rate Limiting
+
+**Status**: Not Started
+**Effort**: Medium (2-4 hours)
+
+Add basic rate limiting to prevent abuse if server is exposed.
+
+**Options**:
+- `express-rate-limit` package
+- Custom middleware using circuit breaker pattern
+
+**Note**: Only needed if server will be exposed beyond localhost.
+
+---
+
+## Implementation Tracking
+
+| # | Item | Priority | Status | Assignee |
+|---|------|----------|--------|----------|
+| 1 | Unit tests for utilities | P0 | Not Started | - |
+| 2 | Sanitize query params in logs | P1 | Not Started | - |
+| 3 | Update ARCHITECTURE.md | P1 | Not Started | - |
+| 4 | Remove dead code | P1 | Not Started | - |
+| 5 | Coverage thresholds | P2 | Not Started | - |
+| 6 | Document symlink security | P2 | Not Started | - |
+| 7 | Improve error detection | P2 | Not Started | - |
+| 8 | Request ID correlation | P3 | Not Started | - |
+| 9 | Health check details | P3 | Not Started | - |
+| 10 | Rate limiting | P3 | Not Started | - |
+
+---
+
+## Quick Wins (< 1 hour each)
+
+1. Add coverage thresholds to vitest.config.ts
+2. Document symlink security
+3. Remove dead code in contextPropagation.ts
+4. Update endpoint references in ARCHITECTURE.md
+
+---
+
+*Last updated: 2026-01-16*

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

@@ -0,0 +1,289 @@
+# Octocode Research Skill - Code Review Plan
+
+> **Target**: `/Users/guybary/octocode-mcp/skills/octocode-research`
+> **Version**: 2.0.0
+> **Type**: Express.js HTTP Server wrapping `octocode-mcp` tools
+
+---
+
+## 📋 Executive Summary
+
+**Project Purpose**: HTTP API server (port 1987) providing code research capabilities via REST endpoints that wrap `octocode-mcp` tool functions.
+
+**Tech Stack**:
+- Express.js 4.x (HTTP server)
+- TypeScript 5.x (strict mode)
+- Zod 3.x (validation)
+- Vitest (testing)
+- octocode-mcp (core dependency)
+
+**File Stats**:
+- Source files: ~31 TypeScript files
+- Test files: 2 integration tests
+- Documentation: 4 markdown files
+
+---
+
+## 🔍 Review Areas
+
+### 1. Core Architecture Review
+
+| File | Purpose | Review Focus |
+|------|---------|--------------|
+| `src/server.ts` | Express app setup, route mounting, graceful shutdown | Error handling, middleware order, shutdown logic |
+| `src/index.ts` | Re-exports from octocode-mcp | Export completeness, naming consistency |
+| `src/mcpCache.ts` | MCP response caching | Cache invalidation, memory management |
+
+**Key Questions**:
+- [ ] Is the middleware pipeline order optimal?
+- [ ] Does graceful shutdown handle all edge cases?
+- [ ] Is error propagation consistent across routes?
+
+---
+
+### 2. Routes Review
+
+| Route File | Endpoints | Review Focus |
+|------------|-----------|--------------|
+| `src/routes/local.ts` | `/local/search`, `/local/content`, `/local/find`, `/local/structure` | Path validation, file access security |
+| `src/routes/lsp.ts` | `/lsp/definition`, `/lsp/references`, `/lsp/calls` | LSP error handling, timeout management |
+| `src/routes/github.ts` | `/github/search`, `/github/content`, `/github/repos`, `/github/structure`, `/github/prs` | Rate limiting, auth token handling |
+| `src/routes/package.ts` | `/package/search` | Registry API resilience |
+| `src/routes/tools.ts` | `/tools/list`, `/tools/info/:name`, `/tools/call/:toolName`, `/tools/system` | Schema validation, tool discovery |
+| `src/routes/prompts.ts` | `/prompts/list`, `/prompts/info/:name` | Prompt loading, caching |
+
+**Key Questions**:
+- [ ] Are all routes properly validating input?
+- [ ] Is error handling consistent across route groups?
+- [ ] Are async operations properly awaited?
+- [ ] Is response format consistent (status, data, hints)?
+
+---
+
+### 3. Middleware Review
+
+| Middleware | Purpose | Review Focus |
+|------------|---------|--------------|
+| `contextPropagation.ts` | Research session context | Context lifecycle, memory leaks |
+| `errorHandler.ts` | Error response formatting | Error types coverage, stack trace handling |
+| `logger.ts` | Request/response logging | Log format, sensitive data masking |
+| `queryParser.ts` | Zod validation | Schema completeness, coercion safety |
+
+**Key Questions**:
+- [ ] Does context propagation handle concurrent requests?
+- [ ] Are all error types properly mapped to HTTP status codes?
+- [ ] Is sensitive data (tokens, paths) masked in logs?
+- [ ] Does query parser handle edge cases (empty, malformed)?
+
+---
+
+### 4. Validation Review
+
+| File | Content | Review Focus |
+|------|---------|--------------|
+| `src/validation/schemas.ts` | Zod schemas for all endpoints | Schema completeness, constraint accuracy |
+| `src/validation/index.ts` | Schema exports | Export organization |
+
+**Key Questions**:
+- [ ] Do schemas match actual tool requirements?
+- [ ] Are optional vs required fields correct?
+- [ ] Are numeric constraints (min/max) appropriate?
+- [ ] Are string patterns (paths, patterns) validated?
+
+---
+
+### 5. Utilities Review
+
+| Utility | Purpose | Review Focus |
+|---------|---------|--------------|
+| `responseBuilder.ts` (14.7KB) | Role-based response formatting | **Largest file** - complexity, maintainability |
+| `circuitBreaker.ts` (7.2KB) | Circuit breaker pattern | State management, timeout handling |
+| `retry.ts` (6.3KB) | Retry with backoff | Backoff strategy, max attempts |
+| `responseParser.ts` | MCP response parsing | Error handling, type safety |
+| `responseFactory.ts` | Response creation helpers | Consistency, reusability |
+| `resilience.ts` | Resilience utilities | Integration with retry/circuit breaker |
+| `routeFactory.ts` | Route creation helpers | DRY principles, pattern consistency |
+| `logger.ts` (7.8KB) | File-based logging | File rotation, performance |
+| `colors.ts` | Console color functions | Terminal compatibility |
+
+**Key Questions**:
+- [ ] Is `responseBuilder.ts` over-engineered? Can it be simplified?
+- [ ] Are circuit breaker thresholds appropriate?
+- [ ] Is retry logic preventing infinite loops?
+- [ ] Is file logging performant under load?
+
+---
+
+### 6. Types Review
+
+| File | Content | Review Focus |
+|------|---------|--------------|
+| `types/express.d.ts` | Express type extensions | Type completeness |
+| `types/guards.ts` | Type guard functions | Guard correctness, exhaustiveness |
+| `types/mcp.ts` | MCP protocol types | Alignment with octocode-mcp |
+| `types/responses.ts` | Response types | Consistency with actual responses |
+| `types/toolTypes.ts` | Tool parameter types | Alignment with schemas |
+
+**Key Questions**:
+- [ ] Are type guards exhaustive?
+- [ ] Do types match runtime behavior?
+- [ ] Are MCP types in sync with octocode-mcp?
+
+---
+
+### 7. Testing Review
+
+| Test File | Coverage | Review Focus |
+|-----------|----------|--------------|
+| `__tests__/integration/routes.test.ts` (12.3KB) | Route integration tests | Coverage completeness, edge cases |
+| `__tests__/integration/circuitBreaker.test.ts` (6.1KB) | Circuit breaker tests | State transitions, timing |
+
+**Key Questions**:
+- [ ] Are all routes covered by tests?
+- [ ] Are error scenarios tested?
+- [ ] Are edge cases (empty inputs, timeouts) covered?
+- [ ] Is test isolation maintained?
+
+**Gaps Identified**:
+- ⚠️ No unit tests for individual utilities
+- ⚠️ No unit tests for middleware
+- ⚠️ Only 2 integration test files
+
+---
+
+### 8. Documentation Review
+
+| Document | Purpose | Review Focus |
+|----------|---------|--------------|
+| `SKILL.md` | Agent usage guide | Accuracy, completeness |
+| `AGENTS.md` | Development guide | Developer onboarding |
+| `docs/ARCHITECTURE.md` | System design | Accuracy, diagrams |
+| `docs/IMPROVEMENTS.md` | Future work | Prioritization |
+| `docs/BUG_RESPONSE_FORMAT.md` | Bug tracking | Template completeness |
+| `docs/DESIGN_NODE_SERVER_MANAGEMENT.md` | Design decisions | Implementation alignment |
+
+**Key Questions**:
+- [ ] Does SKILL.md match actual API behavior?
+- [ ] Is AGENTS.md up-to-date with current structure?
+- [ ] Are architectural diagrams accurate?
+
+---
+
+### 9. Scripts Review
+
+| Script | Purpose | Review Focus |
+|--------|---------|--------------|
+| `scripts/server.ts` | Server management | Start/stop reliability |
+| `scripts/init.ts` | Initialization | Idempotency |
+| `scripts/discover.ts` | Tool discovery | MCP integration |
+| `scripts/call.ts` | Tool calling | Error handling |
+| `scripts/prompt.ts` | Prompt fetching | Caching |
+| `scripts/getToolsInfo.ts` | Tool info extraction | Schema accuracy |
+| `scripts/common.ts` | Shared utilities | Reusability |
+
+**Key Questions**:
+- [ ] Does `install.sh` handle all edge cases?
+- [ ] Is server start/stop idempotent?
+- [ ] Do scripts have proper error messages?
+
+---
+
+### 10. Security Review
+
+**Critical Areas**:
+| Area | Risk | Check |
+|------|------|-------|
+| Path Validation | Path traversal | Validate paths in local routes |
+| Token Handling | Token exposure | Check log masking |
+| Error Messages | Info leakage | Review error detail level |
+| Input Validation | Injection | Review Zod schemas for completeness |
+
+**Key Questions**:
+- [ ] Are file paths sanitized before access?
+- [ ] Are GitHub tokens masked in logs/responses?
+- [ ] Do error messages avoid leaking sensitive info?
+- [ ] Is there rate limiting on the server?
+
+---
+
+## 📊 Review Checklist
+
+### Priority 1 (Critical)
+- [ ] Security: Path validation in local routes
+- [ ] Security: Token handling in GitHub routes
+- [ ] Error Handling: Consistent error responses
+- [ ] Validation: Schema completeness
+
+### Priority 2 (Important)
+- [ ] Testing: Increase coverage (unit tests for utils)
+- [ ] Resilience: Circuit breaker configuration
+- [ ] Performance: Response builder complexity
+- [ ] Logging: Sensitive data masking
+
+### Priority 3 (Nice to Have)
+- [ ] Documentation: Update ARCHITECTURE.md diagrams
+- [ ] Code Style: Reduce responseBuilder.ts complexity
+- [ ] Scripts: Improve error messages
+
+---
+
+## 🏗️ Suggested Review Order
+
+1. **Security First**: `routes/local.ts`, `routes/github.ts` - path & token handling
+2. **Core Flow**: `server.ts` → `middleware/*` → `routes/*`
+3. **Validation**: `validation/schemas.ts` - ensure completeness
+4. **Utilities**: `responseBuilder.ts` - complexity analysis
+5. **Tests**: Review coverage, identify gaps
+6. **Documentation**: Verify accuracy
+
+---
+
+## 📁 Files by Complexity
+
+### High Complexity (> 10KB)
+| File | Size | Priority |
+|------|------|----------|
+| `src/validation/schemas.ts` | 19.4KB | P1 - Validation completeness |
+| `src/utils/responseBuilder.ts` | 14.7KB | P2 - Refactoring candidate |
+| `src/routes/tools.ts` | 11.8KB | P1 - Tool discovery |
+
+### Medium Complexity (5-10KB)
+| File | Size | Priority |
+|------|------|----------|
+| `src/utils/logger.ts` | 7.8KB | P2 |
+| `src/utils/circuitBreaker.ts` | 7.2KB | P2 |
+| `src/routes/github.ts` | 7.0KB | P1 |
+| `src/routes/local.ts` | 6.2KB | P1 |
+| `src/utils/retry.ts` | 6.3KB | P2 |
+| `src/routes/lsp.ts` | 5.8KB | P2 |
+| `src/server.ts` | 5.5KB | P1 |
+
+### Low Complexity (< 5KB)
+All remaining files - standard review
+
+---
+
+## 🎯 Expected Outcomes
+
+1. **Security Report**: Path validation and token handling findings
+2. **Test Coverage Report**: Current coverage + gaps
+3. **Code Quality Report**: Complexity, maintainability scores
+4. **Documentation Audit**: Accuracy checklist
+5. **Recommendations**: Prioritized action items
+
+---
+
+## 📅 Estimated Review Time
+
+| Phase | Time | Description |
+|-------|------|-------------|
+| Security Review | 2-3 hours | Routes, middleware, validation |
+| Core Review | 3-4 hours | Server, routes, middleware |
+| Utilities Review | 2-3 hours | Response builder, circuit breaker |
+| Testing Review | 1-2 hours | Coverage analysis |
+| Documentation | 1 hour | Accuracy verification |
+| **Total** | **9-13 hours** | Full comprehensive review |
+
+---
+
+*Generated by Octocode Research 🔍🐙*