octocode-cli 1.2.5 → 1.2.7

package/skills/octocode-research/references/tool-reference.md

@@ -1,304 +0,0 @@
-# Tool Reference
-
-Complete parameter reference for Octocode MCP tools.
-
-**Required Fields (ALL queries)**: `mainResearchGoal`, `researchGoal`, `reasoning`
-
----
-
-## Local Tools
-
-> **Priority**: ALWAYS prefer local tools over shell commands (`grep`, `ls`, `find`, `cat`)
-
-### localViewStructure
-
-Explore local directory structure with filtering and sorting.
-
-```typescript
-{
-  path: string;                    // Directory path (required)
-  depth?: number;                  // 1-5 (default 1)
-  entriesPerPage?: number;         // ≤20
-  entryPageNumber?: number;        // Pagination
-  details?: boolean;               // Show file sizes
-  hidden?: boolean;                // Include dotfiles
-  extensions?: string[];           // Filter by extension
-  pattern?: string;                // Filter by name pattern
-  filesOnly?: boolean;
-  directoriesOnly?: boolean;
-  sortBy?: "name" | "size" | "time" | "extension";
-}
-```
-
-**Tips:**
-- Start `depth: 1` at root, drill with `depth: 2` on specific dirs
-- Use `details: true` to see file sizes
-- Check `packages/` or `apps/` for monorepos
-
-### localSearchCode
-
-Fast pattern search with discovery mode and pagination.
-
-```typescript
-{
-  pattern: string;                 // Search pattern (required)
-  path: string;                    // Search root (required)
-  filesOnly?: boolean;             // Discovery mode - just list files
-  type?: string;                   // "ts", "py", "js" etc
-  include?: string[];              // Glob patterns to include
-  exclude?: string[];              // Glob patterns to exclude
-  excludeDir?: string[];           // Directories to skip
-  noIgnore?: boolean;              // Search inside node_modules
-  matchesPerPage?: number;         // 1-100
-  filesPerPage?: number;           // ≤20
-  filePageNumber?: number;         // Pagination
-  contextLines?: number;           // Lines around match
-  caseSensitive?: boolean;
-  wholeWord?: boolean;
-  multiline?: boolean;
-}
-```
-
-**Tips:**
-- Start with `filesOnly: true` for discovery (fast, token-efficient)
-- Use `noIgnore: true` to search inside `node_modules`
-- Use `type` for common file extensions
-- Returns `location.charOffset/charLength` as BYTE offsets (ripgrep)
-
-**node_modules Example:**
-```typescript
-{ pattern: "createContext", path: "node_modules/react", noIgnore: true }
-```
-
-### localGetFileContent
-
-Read local file content with targeted extraction.
-
-```typescript
-{
-  path: string;                    // File path (required)
-  // Choose ONE strategy:
-  matchString?: string;            // Pattern to find
-  matchStringContextLines?: number; // 1-50 lines of context
-  matchStringIsRegex?: boolean;
-  matchStringCaseSensitive?: boolean;
-  charOffset?: number;             // BYTE offset for pagination
-  charLength?: number;             // BYTES to read (1000-4000 recommended)
-  startLine?: number;              // Line range
-  endLine?: number;
-  fullContent?: boolean;           // Small files only
-}
-```
-
-**Tips:**
-- Prefer `matchString` over `fullContent` for token efficiency
-- `charOffset`/`charLength` are BYTES, not characters
-- Use `charLength: 2000-4000` for pagination windows
-- Large files require `charLength` or `matchString`
-
-### localFindFiles
-
-Find files by metadata (name, time, size, permissions).
-
-```typescript
-{
-  path: string;                    // Search root (required)
-  name?: string;                   // "*.ts" pattern
-  iname?: string;                  // Case-insensitive name
-  names?: string[];                // Multiple patterns
-  type?: "f" | "d" | "l";          // file/directory/link
-  modifiedWithin?: string;         // "7d", "2h", "30m"
-  modifiedBefore?: string;
-  sizeGreater?: string;            // "10M", "1K"
-  sizeLess?: string;
-  excludeDir?: string[];
-  maxDepth?: number;               // 1-10
-  filesPerPage?: number;           // ≤20
-  filePageNumber?: number;
-}
-```
-
-**Tips:**
-- Results sorted by modified time (most recent first)
-- Use `modifiedWithin: "7d"` to find recent changes
-- Combine with `localGetFileContent` for content
-
----
-
-## GitHub Tools
-
-### packageSearch
-
-Find package repo location from npm/PyPI.
-
-```typescript
-{
-  name: string;                    // Package name (required)
-  ecosystem: "npm" | "python";     // Registry (required)
-  searchLimit?: number;            // 1-10 (npm only)
-  npmFetchMetadata?: boolean;      // Get full npm metadata
-  pythonFetchMetadata?: boolean;   // Get full PyPI metadata
-}
-```
-
-**Tips:**
-- Use `searchLimit: 1` if package name is known
-- Python always returns 1 result (PyPI limitation)
-- Follow with `githubViewRepoStructure` to explore the repo
-
-### githubSearchRepositories
-
-Discover repos by topics, keywords, stars.
-
-```typescript
-{
-  keywordsToSearch?: string[];     // Search terms
-  topicsToSearch?: string[];       // GitHub topics
-  owner?: string;                  // Org/user filter
-  stars?: string;                  // ">1000", "100..500"
-  updated?: string;                // ">2024-01-01"
-  sort?: "stars" | "forks" | "updated" | "best-match";
-  limit?: number;                  // 1-100
-  page?: number;
-}
-```
-
-**Tips:**
-- Use `stars: ">1000"` to filter noise in public repos
-- Check `pushedAt` (last code change) > `updatedAt` (meta change)
-- Archived repositories excluded automatically
-
-### githubViewRepoStructure
-
-Map repository directory layout.
-
-```typescript
-{
-  owner: string;                   // Repo owner (required)
-  repo: string;                    // Repo name (required)
-  branch: string;                  // Branch (required)
-  path?: string;                   // Subpath (default "")
-  depth?: 1 | 2;                   // Recursion depth
-  entriesPerPage?: number;         // ≤200
-  entryPageNumber?: number;
-}
-```
-
-**Tips:**
-- Start `depth: 1` at root, drill with `depth: 2` on subdirs
-- `depth: 2` is slow on large dirs - use on specific subdirectories
-- Check `packages/` or `apps/` individually for monorepos
-- Auto-filters 85+ directories (.git, node_modules, dist, build, etc.)
-
-### githubSearchCode
-
-Find code patterns across GitHub.
-
-```typescript
-{
-  keywordsToSearch: string[];      // Search terms (required)
-  match: "file" | "path";          // Content vs paths (required)
-  owner?: string;                  // Narrow to org
-  repo?: string;                   // Narrow to repo
-  path?: string;                   // Directory filter (strict prefix)
-  extension?: string;              // File type
-  filename?: string;
-  limit?: number;                  // 1-100
-  page?: number;
-}
-```
-
-**WARNING:** NEVER cite search results directly. Search snippets are incomplete. ALWAYS follow up with `githubGetFileContent` to verify.
-
-**Tips:**
-- `match: "path"` for finding files by name
-- `match: "file"` for searching content
-- Prefer specifying `owner` & `repo` for precision and cost
-- Start with 1-2 filters; 3+ filters risky (may return empty)
-- Path matching is strict prefix: `path: "pkg"` finds `pkg/file`, NOT `parent/pkg/file`
-
-### githubGetFileContent
-
-Read file content with targeted extraction.
-
-```typescript
-{
-  owner: string;                   // (required)
-  repo: string;                    // (required)
-  path: string;                    // (required)
-  branch?: string;
-  // Choose ONE strategy:
-  startLine?: number;              // Line range
-  endLine?: number;
-  matchString?: string;            // Pattern match
-  matchStringContextLines?: number; // 1-50
-  charOffset?: number;             // Byte offset
-  charLength?: number;             // Bytes to read
-  fullContent?: boolean;           // Small files only
-}
-```
-
-**Tips:**
-- Prefer `matchString` over `fullContent` for token efficiency
-- Max file size: 300KB
-- For pagination, use branch NAME (e.g., "main"), not commit SHA
-
-### githubSearchPullRequests
-
-Find PR history, metadata, diffs, and discussions.
-
-```typescript
-{
-  owner?: string;
-  repo?: string;
-  prNumber?: number;               // Ignores all other filters
-  query?: string;                  // Search text
-  state?: "open" | "closed";
-  merged?: boolean;
-  author?: string;
-  type?: "metadata" | "fullContent" | "partialContent";
-  partialContentMetadata?: Array<{
-    file: string;
-    additions?: number[];
-    deletions?: number[];
-  }>;
-  withComments?: boolean;
-  withCommits?: boolean;
-  limit?: number;                  // 1-10
-}
-```
-
-**Tips:**
-- Start with `type: "metadata"` (token-efficient)
-- `prNumber` ignores all other filters
-- Use `type: "partialContent"` for specific file diffs
-- Avoid `type: "fullContent"` on large PRs
-
----
-
-## Error Recovery
-
-| Situation | Action |
-|-----------|--------|
-| Empty results | Try semantic variants (auth → login, security, credentials) |
-| Too many results | Add filters (path, extension, owner/repo, type) |
-| File too large | Use `matchString` or `charLength` pagination |
-| Path is directory | Use structure tool instead |
-| Rate limit | Wait, try different tool |
-| Local not found | Check path exists, try `hidden: true`, verify .gitignore |
-
-## Query Batching
-
-- GitHub tools: Max 3 queries per call
-- Local tools: Max 5 queries per call
-- Use parallel queries for independent searches
-
-```typescript
-{
-  "queries": [
-    { "pattern": "AuthService", "path": "src", "filesOnly": true },
-    { "pattern": "authMiddleware", "path": "src", "filesOnly": true },
-    { "pattern": "AuthUser", "path": "src", "filesOnly": true }
-  ]
-}
-```

package/skills/octocode-research/references/workflow-patterns.md

@@ -1,325 +0,0 @@
-# Workflow Patterns
-
-Common research flows for different investigation types.
-
----
-
-## Local-First Patterns
-
-### 1. Explore-First (Unknown Codebase)
-
-**Use when**: Entry points unclear, mixed tech, new repo.
-
-```
-localViewStructure(depth=1) → drill dirs(depth=2) → localSearchCode → localGetFileContent
-```
-
-**Steps:**
-1. **Map Root**: View top-level folders (`depth: 1`)
-2. **Drill Down**: Pick one relevant folder (e.g., `src`)
-3. **Search**: Look for architectural keywords (`App`, `Server`, `Main`)
-4. **Read**: Get content of entry file
-
-```json
-// 1. Map root
-{ "path": "", "depth": 1 }
-
-// 2. Drill into src
-{ "path": "src", "depth": 2 }
-
-// 3. Find entry points
-{ "pattern": "createServer|createApp", "path": "src", "filesOnly": true }
-
-// 4. Read implementation
-{ "path": "src/index.ts", "matchString": "createApp" }
-```
-
-**Pitfall**: Diving deep without map → keep breadth-first.
-
----
-
-### 2. Search-First (Know WHAT, not WHERE)
-
-**Use when**: Feature name, error keyword, class/function known.
-
-```
-localSearchCode(filesOnly=true) → localGetFileContent(matchString)
-```
-
-**Steps:**
-1. **Discovery**: Find files containing the term (fast)
-2. **Target**: Pick the most likely file
-3. **Read**: Read specific function with context
-
-```json
-// 1. Discovery
-{ "pattern": "AuthService", "path": "src", "type": "ts", "filesOnly": true }
-
-// 2. Read implementation
-{ "path": "src/auth/AuthService.ts", "matchString": "class AuthService", "matchStringContextLines": 20 }
-```
-
-**Pitfall**: Reading full files; prefer `matchString` + small context windows.
-
----
-
-### 3. Trace-from-Match (Follow the Trail)
-
-**Use when**: Found definition, need impact graph (imports/usages).
-
-```
-localSearchCode(symbol) → localGetFileContent → localSearchCode(usages) → iterate
-```
-
-**Steps:**
-1. **Find Definition**: Search for the symbol
-2. **Read Implementation**: Get context
-3. **Trace Usages**: Search for imports/calls
-4. **Iterate**: Follow 1-3 focused branches (cap depth)
-
-```json
-// 1. Find definition
-{ "pattern": "export.*useAuth", "path": "src", "filesOnly": true }
-
-// 2. Read implementation
-{ "path": "src/hooks/useAuth.ts", "matchString": "export function useAuth" }
-
-// 3. Find usages
-{ "pattern": "import.*useAuth|useAuth\\(", "path": "src", "filesOnly": true }
-```
-
-**Pitfall**: Unlimited fan-out; cap depth and batch size.
-
----
-
-### 4. Metadata-Driven (Recent Changes)
-
-**Use when**: Debugging recent breaks, finding config files, large files.
-
-```
-localFindFiles(modifiedWithin/size) → localGetFileContent
-```
-
-**Steps:**
-1. **Filter**: Find files by metadata (time, size, type)
-2. **Read**: Examine content of candidates
-
-```json
-// Find recently modified TypeScript files
-{ "path": "src", "name": "*.ts", "modifiedWithin": "7d" }
-
-// Find large files that might need attention
-{ "path": "", "sizeGreater": "100K", "type": "f" }
-```
-
----
-
-### 5. node_modules Inspection
-
-**Use when**: Debugging dependency behavior, understanding library internals.
-
-```
-localSearchCode(noIgnore=true) → localGetFileContent → compare with GitHub source
-```
-
-**Steps:**
-1. **Search Inside**: Use `noIgnore: true` to search node_modules
-2. **Read Local**: Get content from installed version
-3. **Cross-Reference**: Compare with canonical GitHub source
-
-```json
-// 1. Search inside dependency
-{ "pattern": "createContext", "path": "node_modules/react", "noIgnore": true }
-
-// 2. Read local implementation
-{ "path": "node_modules/react/cjs/react.development.js", "matchString": "createContext" }
-
-// 3. Compare with canonical (use GitHub tools)
-```
-
----
-
-## GitHub Patterns
-
-### 6. Package Investigation
-
-**Goal**: Understand how a package works internally.
-
-```
-packageSearch → githubViewRepoStructure → githubSearchCode → githubGetFileContent
-```
-
-**Steps:**
-1. **Locate**: Find the correct repo URL
-2. **Map**: View directory structure (don't map everything)
-3. **Entry**: Find the main entry point (`package.json` main or index file)
-4. **Read**: Get actual content of the entry file
-
-```json
-// 1. Find repo
-{ "name": "express", "ecosystem": "npm" }
-
-// 2. Map structure
-{ "owner": "expressjs", "repo": "express", "branch": "master", "depth": 1 }
-
-// 3. Find entry
-{ "keywordsToSearch": ["index.js"], "match": "path", "owner": "expressjs", "repo": "express" }
-
-// 4. Read implementation
-{ "owner": "expressjs", "repo": "express", "path": "lib/express.js", "matchString": "createApplication" }
-```
-
----
-
-### 7. Implementation Tracing (Remote)
-
-**Goal**: Understand how a feature is implemented in an external library.
-
-**Pattern**: Trace from *User Surface* → *Internal Logic* → *Data Layer*.
-
-```
-githubSearchCode(surface) → githubGetFileContent → trace imports → repeat
-```
-
-**Steps:**
-1. **Surface**: Find the public API/Component (e.g., `useState`)
-2. **Definition**: Read the function definition
-3. **Dependency**: Identify one key internal dependency
-4. **Trace**: Search for that dependency's definition
-5. **Repeat**: Continue until you hit the bottom
-
-```json
-// 1. Find feature surface
-{ "keywordsToSearch": ["useState"], "match": "file", "path": "packages/react", "owner": "facebook", "repo": "react" }
-
-// 2. Read definition (The Gate: Read before assuming)
-{ "owner": "facebook", "repo": "react", "path": "packages/react/src/ReactHooks.js", "matchString": "export function useState" }
-
-// 3. Trace dependency
-{ "keywordsToSearch": ["resolveDispatcher"], "match": "file", "owner": "facebook", "repo": "react" }
-```
-
----
-
-### 8. Bug Investigation
-
-**Goal**: Find root cause of a bug.
-
-```
-githubSearchCode(error) → githubGetFileContent → githubSearchPullRequests
-```
-
-**Steps:**
-1. **Locate Error**: Find where the error string/code is defined
-2. **Read Context**: Read the condition causing the error
-3. **Blame/History**: Who changed this last and why?
-
-```json
-// 1. Find error source
-{ "keywordsToSearch": ["ENOENT"], "match": "file", "owner": "nodejs", "repo": "node" }
-
-// 2. Read context
-{ "owner": "nodejs", "repo": "node", "path": "lib/fs.js", "matchString": "ENOENT" }
-
-// 3. Check history
-{ "query": "file reader ENOENT", "owner": "nodejs", "repo": "node", "merged": true, "type": "metadata" }
-```
-
----
-
-## Cross-Domain Patterns
-
-### 9. Local → GitHub (Upstream Research)
-
-**Use when**: Local code uses a dependency, need canonical source.
-
-```
-localSearchCode → packageSearch → githubViewRepoStructure → githubGetFileContent
-```
-
-```json
-// 1. Find import in local code
-{ "pattern": "import.*from 'axios'", "path": "src", "filesOnly": true }
-
-// 2. Find package repo
-{ "name": "axios", "ecosystem": "npm" }
-
-// 3. Explore upstream
-{ "owner": "axios", "repo": "axios", "branch": "v1.x", "depth": 1 }
-
-// 4. Read canonical implementation
-{ "owner": "axios", "repo": "axios", "path": "lib/core/Axios.js", "matchString": "class Axios" }
-```
-
-### 10. GitHub → Local (Impact Analysis)
-
-**Use when**: Found upstream change, check local impact.
-
-```
-githubSearchPullRequests → extract changed patterns → localSearchCode
-```
-
-```json
-// 1. Find breaking change PR
-{ "query": "breaking change v2", "owner": "some-lib", "repo": "lib", "merged": true }
-
-// 2. Get changed API (from PR)
-// → Extracted: "oldMethod renamed to newMethod"
-
-// 3. Check local usage
-{ "pattern": "oldMethod", "path": "src", "filesOnly": true }
-```
-
----
-
-## The Verification Gate
-
-**BEFORE claiming a finding, pass this gate:**
-
-1. **IDENTIFY**: What exact lines of code prove this?
-2. **FETCH**: Did you read the *actual file content*? (Search snippets don't count)
-3. **VERIFY**: Does the logic actually do what you think?
-4. **CHECK DATES**: Is this code from 5 years ago?
-5. **ONLY THEN**: Output the finding.
-
----
-
-## Batch Queries
-
-Parallelize independent searches (max 3 GitHub, max 5 local):
-
-```json
-{
-  "queries": [
-    { "pattern": "AuthService", "path": "src", "filesOnly": true },
-    { "pattern": "authMiddleware", "path": "src", "filesOnly": true },
-    { "pattern": "AuthUser", "path": "src", "filesOnly": true }
-  ]
-}
-```
-
----
-
-## Anti-Patterns
-
-| Bad | Good |
-|-----|------|
-| **Citing Search Results** | **Citing File Content** (Read the file!) |
-| **"I assume..."** | **"The code shows..."** |
-| **"Should work like..."** | **"Logic implements..."** |
-| **Broad Search (`auth`)** | **Targeted Search (`class AuthService`)** |
-| **Ignoring Dates** | **Checking `lastModified`** |
-| **Shell commands for search** | **Local tools with pagination** |
-| **Full file dumps** | **matchString + context** |
-
----
-
-## Checklist
-
-- [ ] **Goal defined?** (Atomic question)
-- [ ] **Local-first?** (Checked workspace before GitHub)
-- [ ] **Code evidence found?** (Line numbers/paths)
-- [ ] **The Gate passed?** (Read full content)
-- [ ] **Cross-referenced?** (Imports/Usage)
-- [ ] **Updated dates checked?**
-- [ ] **Gaps documented?**