octocode-cli 1.2.5 → 1.2.7

package/skills/octocode-pull-request-reviewer/references/parallel-agent-protocol.md

@@ -0,0 +1,182 @@
+# Multi-Agent Parallelization & Swarm Strategy
+
+## When to Parallelize
+
+| PR Size | Files | Mode | Agent Strategy |
+|---------|-------|------|----------------|
+| Small | ≤5 | Quick | No agents — single-pass review |
+| Medium | 6-15 | Full | 2 parallel agents (Flow + Domains) |
+| Large | 16-30 | Full | 3 parallel agents (Flow + Security + Domains) |
+| XL | 30+ | Full | 4 parallel agents (Flow + Security + Architecture + Domains) |
+
+**IF** Quick mode → FORBIDDEN to spawn agents. Single-pass only.
+**IF** Full mode AND >5 files → MUST use parallel agents for Phase 4 (Analysis).
+
+---
+
+## Swarm Architecture
+
+```
+                    ┌─────────────────────┐
+                    │   ORCHESTRATOR (you) │
+                    │   Phases 1-3, 5-6    │
+                    └──────────┬──────────┘
+                               │ Phase 4: Spawn agents
+                    ┌──────────┼──────────┐──────────┐
+                    ▼          ▼          ▼          ▼
+              ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+              │ Agent A   │ │ Agent B   │ │ Agent C   │ │ Agent D   │
+              │ Flow      │ │ Security  │ │ Arch +    │ │ Guidelines│
+              │ Impact    │ │ + Errors  │ │ Quality   │ │ + Dupes   │
+              └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
+                    │             │             │             │
+                    └──────────┬──┴─────────────┴─────────────┘
+                               ▼
+                    ┌─────────────────────┐
+                    │   ORCHESTRATOR      │
+                    │   Merge + Dedupe    │
+                    │   Phase 5-6         │
+                    └─────────────────────┘
+```
+
+**CRITICAL: All agent Task calls MUST be in a SINGLE message for true parallel execution.**
+
+---
+
+## Agent Definitions
+
+### Agent A: Flow Impact Analyst
+- **Scope**: Flow Impact domain + blast radius mapping
+- **Tools**: `localSearchCode` → `lspCallHierarchy(incoming)` → `lspFindReferences` → `githubSearchCode`
+- **Task**: For every modified function/method/type in the diff:
+  1. Call `localSearchCode` to get lineHint for each symbol
+  2. Call `lspCallHierarchy(incoming, depth=1)` to find all callers
+  3. Call `lspFindReferences` for changed types/interfaces
+  4. Document: symbol name, file:line, caller count, breaking change (yes/no)
+- **Output**: List of `{ symbol, file:line, callers: [{file:line, impact}], breaking: bool }`
+- **Prompt template**:
+  ```
+  You are a Flow Impact Analyst. Review the following PR diff and trace ALL
+  modified functions/methods/types to find their callers and consumers.
+
+  PR diff: {diff_summary}
+  Modified symbols: {list_of_changed_functions_types}
+  Repo: {owner}/{repo}
+
+  For EACH modified symbol:
+  1. Use localSearchCode(pattern="symbolName") to get lineHint
+  2. Use lspCallHierarchy(symbolName, lineHint, direction="incoming") for functions
+  3. Use lspFindReferences(symbolName, lineHint) for types/interfaces
+  4. Document the blast radius
+
+  Return findings as structured list with file:line citations.
+  FORBIDDEN: Guessing lineHint. ALWAYS search first.
+  ```
+
+### Agent B: Security & Error Handling Reviewer
+- **Scope**: Security scan + Error Handling domain
+- **Tools**: `localSearchCode` → `githubGetFileContent(matchString=...)` → `localGetFileContent`
+- **Task**:
+  1. Scan changed files for: hardcoded secrets, SQL injection, XSS, data exposure, auth bypass
+  2. Check error handling: swallowed exceptions, missing context, unclear messages
+  3. Verify input validation on new endpoints/functions
+  4. Check for regulatory compliance patterns (GDPR, HIPAA)
+- **Output**: List of `{ issue, file:line, severity, confidence, fix }`
+- **Prompt template**:
+  ```
+  You are a Security & Error Handling Reviewer. Scan the following PR diff
+  for security vulnerabilities and error handling issues.
+
+  PR diff: {diff_content}
+  Changed files: {file_list}
+
+  Security checks: injection, XSS, data exposure, auth bypass, hardcoded secrets
+  Error handling checks: swallowed exceptions, missing context, unclear messages
+
+  Use localSearchCode to find patterns, githubGetFileContent for context.
+  Return findings with file:line, severity, confidence, and fix.
+  ONLY flag issues in CHANGED code ('+' lines).
+  ```
+
+### Agent C: Architecture & Code Quality Reviewer
+- **Scope**: Architecture domain + Code Quality domain + Performance domain
+- **Tools**: `githubViewRepoStructure` → `localViewStructure` → `localSearchCode` → `githubGetFileContent`
+- **Task**:
+  1. Check changed code against repo patterns and conventions
+  2. Detect: coupling, circular deps, wrong module placement, naming violations
+  3. Performance: O(n²), blocking ops, missing cache, unbatched operations
+  4. Check for TODO/FIXME in new code
+- **Output**: List of `{ issue, domain, file:line, severity, confidence, fix }`
+- **Prompt template**:
+  ```
+  You are an Architecture & Code Quality Reviewer. Analyze the following PR diff
+  for architectural issues, code quality problems, and performance concerns.
+
+  PR diff: {diff_content}
+  Changed files: {file_list}
+  Repo structure: {structure_summary}
+
+  Check: pattern violations, coupling, naming, O(n²), blocking ops, magic numbers
+  Use githubViewRepoStructure to understand repo layout.
+  Use localSearchCode to find existing patterns for comparison.
+  Return findings with file:line, domain, severity, confidence, and fix.
+  ONLY flag issues in CHANGED code ('+' lines).
+  ```
+
+### Agent D: Guidelines & Duplicate Code Reviewer (only if guidelines loaded)
+- **Scope**: Guidelines compliance + Duplicate Code domain
+- **Tools**: `localSearchCode` → `githubSearchCode` → `localGetFileContent` → `githubGetFileContent`
+- **Task**:
+  1. Check each changed file against loaded guidelines (from Phase 1)
+  2. Search for existing utilities/patterns that new code could reuse
+  3. Flag DRY violations across the codebase
+- **Output**: List of `{ guideline_source, rule, status: PASS/VIOLATION, file:line }` + duplicate findings
+- **Prompt template**:
+  ```
+  You are a Guidelines & Duplicate Code Reviewer.
+
+  Guidelines context:
+  {guidelines_context_from_phase_1}
+
+  PR diff: {diff_content}
+  Changed files: {file_list}
+
+  Task 1: For each changed file, check compliance against every loaded guideline rule.
+  Task 2: Use localSearchCode/githubSearchCode to find existing utilities that new code duplicates.
+  Return: guidelines compliance table + duplicate code findings with file:line.
+  ```
+
+---
+
+## Scaling Rules
+
+| Agents | Condition | Which Agents |
+|--------|-----------|-------------|
+| 0 | Quick mode OR ≤5 files | None — single-pass |
+| 2 | 6-15 files, no guidelines | A (Flow) + C (Arch+Quality) |
+| 3 | 16-30 files OR guidelines loaded | A (Flow) + B (Security) + C (Arch+Quality) |
+| 3 | 6-15 files + guidelines loaded | A (Flow) + C (Arch+Quality) + D (Guidelines) |
+| 4 | 30+ files + guidelines loaded | A + B + C + D (all agents) |
+
+---
+
+## Merge Protocol (Phase 5 — Orchestrator)
+
+After all agents return, the orchestrator MUST:
+
+1. **Collect**: Gather all findings from all agents into a single list
+2. **Dedupe**: Remove findings with the same root cause or same file:line
+   - **IF** two agents report the same issue → keep the one with higher confidence
+   - **IF** same file:line but different domains → merge into single finding, list both domains
+3. **Cross-check**: Verify agent findings against existing PR comments (Phase 2)
+4. **Prioritize**: Sort by severity (HIGH → MED → LOW), then by domain weight:
+   - Security > Bug > Flow Impact > Architecture > Performance > Quality > Duplicates
+5. **Cap**: Select top ~5-7 most impactful findings
+6. **Enrich**: For each finding, ensure file:line + confidence + code fix exists
+
+**FORBIDDEN:**
+- Spawning agents in Quick mode
+- Spawning >4 agents (diminishing returns, context overhead)
+- Agents modifying files or writing output directly
+- Spawning agents sequentially (MUST be single-message parallel)
+- Proceeding to Phase 6 before ALL agents have returned

package/skills/octocode-pull-request-reviewer/references/review-guidelines.md

@@ -0,0 +1,26 @@
+# Review Guidelines
+
+<confidence>
+
+| Level | Certainty | Action |
+|-------|-----------|--------|
+| **HIGH** | Verified issue exists | MUST include |
+| **MED** | Likely issue, missing context | MUST include with caveat |
+| **LOW** | Uncertain | Investigate more OR skip |
+
+**Note**: Confidence is NOT Severity. HIGH confidence typo = Low Priority. LOW confidence security flaw = flag but mark uncertain.
+</confidence>
+
+<review_mindset>
+**Core Principle: Focus on CHANGED Code Only**
+- **Added code**: Lines with '+' prefix
+- **Modified code**: New implementation ('+') while considering removed context
+- **Deleted code**: Only comment if removal creates new risks
+
+**MUST include when**: HIGH/MED confidence + NEW code ('+' prefix) + real problem + actionable fix
+**FORBIDDEN to suggest when**: LOW confidence, unchanged code, style-only, caught by linters/compilers, already commented by others
+</review_mindset>
+
+<structural_code_vision>
+**Think Like a Parser**: Visualize AST (Entry → Functions → Imports/Calls). Trace `import {X} from 'Y'` → GO TO 'Y'. Follow flow: Entry → Propagation → Termination. Ignore noise.
+</structural_code_vision>

package/skills/octocode-pull-request-reviewer/references/verification-checklist.md

@@ -0,0 +1,40 @@
+# Verification Checklist
+
+<verification>
+Before delivering review, ALL items MUST be checked:
+
+**Target & Mode:**
+- [ ] Review target determined (PR Mode or Local Mode)
+- [ ] **Local Mode**: `ENABLE_LOCAL=true` verified (local tools responding)
+
+**Phase Completion — PR Mode:**
+- [ ] Phase 1: User asked for guidelines/context files
+- [ ] Phase 2: PR metadata, diff, and comments fetched via Octocode MCP
+- [ ] Phase 3: TL;DR summary presented, user checkpoint completed
+- [ ] Phase 4: All search queries executed, flow impact analyzed (Full mode)
+- [ ] Phase 5: Findings deduplicated, verified against guidelines
+- [ ] Phase 6: Chat summary presented, user asked before doc creation
+
+**Phase Completion — Local Mode:**
+- [ ] Phase 1: User asked for guidelines/context files
+- [ ] Phase 2: `git status` + `git diff` collected, changed files enumerated via local tools
+- [ ] Phase 3: TL;DR summary (local template) presented, user checkpoint completed
+- [ ] Phase 4: All search queries executed via `local*` + `lsp*` tools, flow impact analyzed (Full mode)
+- [ ] Phase 5: Findings deduplicated, verified against guidelines
+- [ ] Phase 6: Chat summary presented, user asked before doc creation
+
+**Finding Quality:**
+- [ ] All findings cite exact `file:line` locations
+- [ ] Every finding has an actionable fix with code diff
+- [ ] Confidence level (HIGH/MED) assigned to each finding
+- [ ] Findings capped per Phase 5 limit
+- [ ] No duplicates with existing PR comments (PR Mode only)
+- [ ] Previous review comments verified for resolution (PR Mode only)
+
+**Guidelines & Tools:**
+- [ ] Guidelines loaded and applied throughout analysis (if provided)
+- [ ] Guidelines Compliance section included in report (if guidelines loaded)
+- [ ] All code research done via Octocode MCP tools (not shell commands for reading/searching)
+- [ ] Flow impact analyzed for all modified functions (LSP tools in Local Mode)
+- [ ] Security issues flagged prominently
+</verification>

package/skills/octocode-research/.claude/settings.local.json

@@ -0,0 +1,46 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./install.sh:*)",
+      "Bash(curl:*)",
+      "Bash(npm run build:*)",
+      "Bash(tree:*)",
+      "Bash(npm test:*)",
+      "Skill(octocode-research)",
+      "Bash(npm run server:*)",
+      "Bash(npm run server:start:*)",
+      "Bash(npm install)",
+      "Bash(grep:*)",
+      "Bash(npm run build:dev:*)",
+      "Bash(npm install:*)",
+      "Bash(./cli tools/info/githubViewRepoStructure:*)",
+      "Bash(./cli tools/info/githubSearchCode:*)",
+      "Bash(lsof:*)",
+      "Bash(xargs kill:*)",
+      "Bash(./cli health:*)",
+      "Bash(./cli system:*)",
+      "Bash(./cli prompts:*)",
+      "Bash(./cli localSearchCode:*)",
+      "Bash(./cli prompts/info/research:*)",
+      "mcp__octocode-local__localViewStructure",
+      "mcp__octocode-local__localSearchCode",
+      "mcp__octocode-local__lspFindReferences",
+      "mcp__octocode-local__localGetFileContent",
+      "Bash(npx tsc:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npx tsdown)",
+      "Bash(xargs:*)",
+      "Bash(npm run server:stop:*)",
+      "Bash(yarn build)",
+      "Bash(yarn test:*)",
+      "Bash(yarn lint:fix:*)",
+      "mcp__octocode__packageSearch",
+      "Bash(npm run server-init:*)",
+      "mcp__octocode-local__localFindFiles",
+      "Bash(python3:*)",
+      "Bash(# Test: read a file with sensitive content curl -s -X POST http://localhost:1987/tools/call/localGetFileContent -H \"\"Content-Type: application/json\"\" -d ''{\"\"queries\"\":[{\"\"path\"\":\"\"/etc/hosts\"\",\"\"fullContent\"\":true}]}'' 2>&1 | python3 -m json.tool)",
+      "Bash(# Test: URL encoded path traversal curl -s -X POST http://localhost:1987/tools/call/localSearchCode -H \"\"Content-Type: application/json\"\" -d ''{\"\"queries\"\":[{\"\"pattern\"\":\"\"root\"\",\"\"path\"\":\"\"/etc\"\"}]}'' 2>&1 | python3 -m json.tool)",
+      "Bash(# Test: can we access user home directory files? \\(just check if /Users/guybary is allowed root\\) curl -s -X POST http://localhost:1987/tools/call/localSearchCode -H \"\"Content-Type: application/json\"\" -d ''{\"\"queries\"\":[{\"\"pattern\"\":\"\"password\"\",\"\"path\"\":\"\"/Users/guybary\"\",\"\"maxFiles\"\":1,\"\"filesOnly\"\":true}]}'' 2>&1 | python3 -m json.tool)"
+    ]
+  }
+}

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

@@ -0,0 +1,312 @@
+# Plan: Fix CODE_REVIEW_FINDINGS Issues
+
+## Summary
+
+Fix 9 verified issues from the code review findings in the `skills/octocode-research` package. Prioritized by security impact and type safety, with code quality improvements deferred to later phases.
+
+---
+
+## Research Findings
+
+See [research.md](./research.md) for detailed analysis.
+
+**Key Patterns Discovered:**
+- Server binding issue is a single-line fix
+- Type safety issues require generic type parameters
+- Fire-and-forget patterns are intentional but need error visibility
+- File splitting is straightforward based on existing code structure
+
+---
+
+## Implementation Steps
+
+### Phase 1: Security Fixes (HIGH Priority)
+
+#### 1. [ ] Bind server to localhost only
+**File:** `src/server.ts:118`
+
+```typescript
+// Before
+const httpServer = app.listen(PORT);
+
+// After
+const httpServer = app.listen(PORT, '127.0.0.1');
+```
+
+**Validation:** Server should only be accessible from localhost.
+
+---
+
+#### 2. [ ] Remove path from 404 error response
+**File:** `src/server.ts:64-67`
+
+```typescript
+// Before
+res.status(404).json({
+  success: false,
+  error: {
+    message: `Route not found: ${req.method} ${req.path}`,
+
+// After
+res.status(404).json({
+  success: false,
+  error: {
+    message: 'Route not found',
+    code: 'NOT_FOUND'
+  }
+});
+```
+
+**Validation:** 404 responses should not include request details.
+
+---
+
+#### 3. [ ] Guard or remove debug logging
+**File:** `src/middleware/queryParser.ts:57`
+
+**Option A - Environment guard:**
+```typescript
+if (process.env.NODE_ENV === 'development') {
+  console.debug('[QueryParser] JSON parsing failed, trying single query mode', {
+    error: e instanceof Error ? e.message : String(e),
+  });
+}
+```
+
+**Option B - Remove entirely (recommended):**
+```typescript
+// Remove the console.debug block - the code handles the fallback silently
+```
+
+**Validation:** No user input logged in production.
+
+---
+
+#### 4. [ ] Ensure stack traces not exposed to clients
+**File:** `src/utils/logger.ts:210`
+
+```typescript
+// Before
+console.error(errorLog(`[ERROR] ${message}`), error || '');
+
+// After - only log error message, not full stack in production
+const errorDetail = process.env.NODE_ENV === 'development'
+  ? error
+  : (error instanceof Error ? error.message : String(error));
+console.error(errorLog(`[ERROR] ${message}`), errorDetail);
+```
+
+**Validation:** Stack traces only in development mode.
+
+---
+
+### Phase 2: Type Safety Fixes (HIGH Priority)
+
+#### 5. [ ] Add proper types to toQueryParams
+**File:** `src/types/toolTypes.ts:14`
+
+```typescript
+// Before
+export function toQueryParams(validated: any): any {
+
+// After
+export interface QueryParams {
+  [key: string]: unknown;
+}
+
+export function toQueryParams<T extends Record<string, unknown>>(
+  validated: T
+): QueryParams {
+  // Implementation - transform validated schema output to query params
+  const result: QueryParams = {};
+  for (const [key, value] of Object.entries(validated)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+```
+
+**Validation:** TypeScript compilation with strict mode.
+
+---
+
+#### 6. [ ] Add proper types to ToolFn
+**File:** `src/routes/tools.ts:350`
+
+```typescript
+// Before
+type ToolFn = (params: { queries: any[] }) => Promise<any>;
+
+// After
+import { ToolResponse } from '../types/responses';
+
+interface ToolQuery {
+  mainResearchGoal?: string;
+  researchGoal?: string;
+  reasoning?: string;
+  [key: string]: unknown;
+}
+
+type ToolFn<TQuery extends ToolQuery = ToolQuery> = (
+  params: { queries: TQuery[] }
+) => Promise<ToolResponse>;
+```
+
+**Note:** This may require updating tool handler type casts. Consider using generics for specific tools.
+
+**Validation:** TypeScript compilation, all tool registrations compile.
+
+---
+
+### Phase 3: Code Quality (MEDIUM Priority)
+
+#### 7. [ ] Export isNonEmptyString guard
+**File:** `src/types/guards.ts:11`
+
+```typescript
+// Before
+function isNonEmptyString(value: unknown): value is string {
+
+// After
+export function isNonEmptyString(value: unknown): value is string {
+```
+
+**Alternative:** If intentionally private, add comment:
+```typescript
+/** @internal Used only by isStringArray */
+function isNonEmptyString(value: unknown): value is string {
+```
+
+**Validation:** If exported, verify no naming conflicts.
+
+---
+
+#### 8. [ ] Create bounded error queue for fire-and-forget
+**File:** Create `src/utils/errorQueue.ts`
+
+```typescript
+/**
+ * Bounded queue for fire-and-forget operation errors.
+ * Provides visibility into async errors without blocking main flow.
+ */
+class ErrorQueue {
+  private errors: Array<{ timestamp: Date; error: Error; context?: string }> = [];
+  private readonly maxSize: number;
+
+  constructor(maxSize = 100) {
+    this.maxSize = maxSize;
+  }
+
+  push(error: unknown, context?: string): void {
+    const normalizedError = error instanceof Error ? error : new Error(String(error));
+
+    this.errors.push({
+      timestamp: new Date(),
+      error: normalizedError,
+      context
+    });
+
+    // Bounded: remove oldest when full
+    if (this.errors.length > this.maxSize) {
+      this.errors.shift();
+    }
+  }
+
+  getRecent(count = 10): Array<{ timestamp: Date; error: Error; context?: string }> {
+    return this.errors.slice(-count);
+  }
+
+  clear(): void {
+    this.errors = [];
+  }
+
+  get size(): number {
+    return this.errors.length;
+  }
+}
+
+export const errorQueue = new ErrorQueue();
+```
+
+**Update fire-and-forget locations:**
+```typescript
+// Before
+logSessionError(toolName, errorCode).catch(() => {});
+
+// After
+import { errorQueue } from '../utils/errorQueue';
+logSessionError(toolName, errorCode).catch(err => errorQueue.push(err, 'logSessionError'));
+```
+
+**Files to update:**
+- `src/middleware/errorHandler.ts:37`
+- `src/routes/prompts.ts:110`
+- `src/routes/tools.ts:522`
+- `src/server.ts:136`
+- `src/utils/circuitBreaker.ts:174, 186`
+- `src/utils/logger.ts:127`
+
+**Validation:** Error queue populated on failures, main flow not blocked.
+
+---
+
+### Phase 4: Refactoring (LOW Priority - Future)
+
+#### 9. [ ] Split tools.ts into smaller modules
+**Current:** `src/routes/tools.ts` (555 lines)
+
+**Proposed structure:**
+```
+src/routes/tools/
+  index.ts        - Route definitions, exports
+  handlers.ts     - Tool execution logic
+  registry.ts     - Tool registration and lookup
+  types.ts        - ToolFn and related types
+```
+
+**Approach:**
+1. Create `src/routes/tools/` directory
+2. Extract `ToolFn` type and registry to `registry.ts`
+3. Extract handler logic to `handlers.ts`
+4. Keep route definitions in `index.ts`
+5. Update imports in dependent files
+
+**Validation:** All existing tests pass, no functional changes.
+
+---
+
+## Risk Areas
+
+| Risk | Mitigation |
+|------|------------|
+| Type changes break existing code | Incremental changes with compilation checks |
+| Localhost binding breaks remote testing | Document `--host` flag for remote access if needed |
+| Error queue memory growth | Bounded queue with max 100 entries |
+| File splitting breaks imports | Update all import paths, run full test suite |
+
+---
+
+## Validation Checklist
+
+- [ ] `npm run build` passes
+- [ ] `npm run lint` passes
+- [ ] `npm test` passes
+- [ ] Server only accessible from localhost
+- [ ] 404 responses don't include paths
+- [ ] No TypeScript `any` in modified files
+- [ ] Fire-and-forget errors captured in queue
+
+---
+
+## Implementation Order
+
+1. **Phase 1** - Security fixes (steps 1-4) - Do first, low risk
+2. **Phase 2** - Type safety (steps 5-6) - May require iteration
+3. **Phase 3** - Code quality (steps 7-8) - Independent of above
+4. **Phase 4** - Refactoring (step 9) - Defer until after validation
+
+---
+
+Created by Octocode MCP https://octocode.ai