@octocodeai/octocode-core 16.1.0 → 16.2.0

package/dist/resources/tools/localSearchCode.d.ts

@@ -1,2 +1,51 @@
+import { z } from "zod";
 import type { ToolSpec } from "../../types/index.js";
 export declare const localSearchCode: ToolSpec;
+export declare const RipgrepQuerySchema: z.ZodObject<{
+    keywords: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<{
+        paginated: "paginated";
+        discovery: "discovery";
+        detailed: "detailed";
+        structural: "structural";
+    }>>;
+    pattern: z.ZodOptional<z.ZodString>;
+    rule: z.ZodOptional<z.ZodString>;
+    fixedString: z.ZodOptional<z.ZodBoolean>;
+    perlRegex: z.ZodOptional<z.ZodBoolean>;
+    caseInsensitive: z.ZodOptional<z.ZodBoolean>;
+    caseSensitive: z.ZodOptional<z.ZodBoolean>;
+    wholeWord: z.ZodOptional<z.ZodBoolean>;
+    invertMatch: z.ZodOptional<z.ZodBoolean>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeDir: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    noIgnore: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    filesOnly: z.ZodOptional<z.ZodBoolean>;
+    filesWithoutMatch: z.ZodOptional<z.ZodBoolean>;
+    contextLines: z.ZodOptional<z.ZodNumber>;
+    matchContentLength: z.ZodDefault<z.ZodNumber>;
+    maxMatchesPerFile: z.ZodOptional<z.ZodNumber>;
+    maxFiles: z.ZodOptional<z.ZodNumber>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+    multilineDotall: z.ZodOptional<z.ZodBoolean>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        path: "path";
+        modified: "modified";
+        created: "created";
+        accessed: "accessed";
+    }>>;
+    sortReverse: z.ZodOptional<z.ZodBoolean>;
+    langType: z.ZodOptional<z.ZodString>;
+    countLinesPerFile: z.ZodOptional<z.ZodBoolean>;
+    countMatchesPerFile: z.ZodOptional<z.ZodBoolean>;
+    matchPage: z.ZodOptional<z.ZodNumber>;
+    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/resources/tools/localSearchCode.js

@@ -1 +1 @@
-export const localSearchCode={name:"localSearchCode",description:"Local ripgrep search for file+line.\nPage only on hasMore; use matchPage for more matches in one file; narrow path/include/exclude/keywords before paging noisy results.\nNext: localGetFileContent(path,matchString), lspGetSemanticContent(uri,symbolName,lineHint), localViewStructure if root unknown.",schema:{keywords:"Text or regex. fixedString:true for literal; perlRegex:true for PCRE2 features.",path:"File or directory to search; absolute paths are safest.",mode:'"paginated" for normal reading; "discovery" for cheap presence checks; "detailed" for expanded snippets.',fixedString:"Literal match — disables regex.",perlRegex:"PCRE2 regex — lookaheads, backreferences.",caseInsensitive:"Use case-insensitive matching (-i). Exclusive with caseSensitive.",caseSensitive:"Use case-sensitive matching.",wholeWord:"Match whole-word occurrences.",invertMatch:"Return non-matching lines (-v). For files lacking the pattern use filesWithoutMatch.",include:"File path include globs (e.g. '*.ts', 'src/**/*.tsx').",exclude:"File path exclude globs (e.g. '*.min.js', 'dist/**').",excludeDir:"Directory names to skip (e.g. 'node_modules', 'dist', '.git').",noIgnore:"Bypass .gitignore and .ignore files.",hidden:"Include hidden (dot) files.",filesOnly:"Return matching file paths without line content.",filesWithoutMatch:"Files that do not match.",contextLines:"Lines of context around each match.",matchContentLength:"Chars per match snippet; raise for very long lines such as minified code or JSON blobs.",maxMatchesPerFile:"Limit matches returned per file.",maxFiles:"Limit matched files returned.",multiline:"Cross-line matching (-U). Add multilineDotall when dot should match newlines.",multilineDotall:". matches newlines. Requires multiline=true.",sort:"Sort by path, modified time, access time, or creation time.",sortReverse:"Reverse sort order (e.g. sort=modified + sortReverse=true → oldest first).",langType:"Ripgrep language type filter such as ts, js, py, or go.",countLinesPerFile:"Matching-line count per file instead of content. Exclusive with countMatchesPerFile.",countMatchesPerFile:"Total match count per file (multiple per line counted). Exclusive with countLinesPerFile.",matchPage:"Per-file match page (1-based). Use with maxMatchesPerFile.",itemsPerPage:"Files per page.",page:"Result page (1-based)."}};
+import{z as e}from"zod";import{buildObject as t,contextLines as a,DEFAULT_MATCH_CONTENT_LENGTH as s,intRange as i,MAX_MATCH_CONTENT_LENGTH as n,MAX_PAGE_NUMBER as o,metaFields as l,optionalPageNumber as r,pageNumber as c,StringArray as u}from"./_toolkit.js";export const localSearchCode={name:"localSearchCode",description:'Local code/text search for file+line.\nChoose mode first: "paginated" returns snippets; "discovery" returns file paths only — cheapest orientation; "detailed" returns expanded context per match.\nFor count-only output use countLinesPerFile:true or countMatchesPerFile:true — do NOT use mode:"count" (does not exist).\nOutput signal: searchEngine flags when a reduced-capability fallback ran — perlRegex features are dropped and countMatchesPerFile becomes line-count semantics.\nPage only on hasMore; use matchPage for more matches in one file; narrow include/exclude/path before paging noisy results.\nBatch: pass up to 5 {keywords, path} objects in one call — e.g. search same keyword across multiple directories simultaneously.\nevidence.answerReady:true means at least one result exists; check pagination.hasMore separately before deciding to stop.\nPair with lspGetSemantics for semantic navigation — matches[0].line feeds directly as lineHint for definition, references, and call hierarchy.\nmode:"structural" (+ pattern OR rule): AST/shape queries regex can\'t express and that aren\'t symbol-identity questions — e.g. eval($X) call sites excluding comments/strings, or async fns lacking try/catch. pattern is a code-shaped query (foo($X), console.log($$$ARGS)); rule is a YAML relational/composite blob (not/inside/has/all/any). Returns node ranges; matches[].line still feeds lspGetSemantics lineHint. keywords is ignored in this mode.\nNext: localGetFileContent(path, matchString=keyword) to read context; lspGetSemantics(uri=files[0].path, symbolName, lineHint=matches[0].line) for semantics; localViewStructure if root unknown; localFindFiles when searching by filename or metadata.',schema:{keywords:"The search pattern (text or regex). Set fixedString:true for a literal match, or perlRegex:true for advanced regex features (lookaheads, backreferences).",path:"File or directory to search (absolute paths are safest).",mode:'"paginated": matches with snippets. "discovery": file paths only — cheapest, for orienting before you read. "detailed": snippets with surrounding context, for deep reading without a follow-up read. "structural": AST/shape search (set pattern OR rule) for queries regex can\'t express. For counts only, set countLinesPerFile or countMatchesPerFile.',pattern:'mode:"structural" only. An ast-grep code-shaped pattern. Metavariables: $X matches a single node (captured), $$$ARGS matches a list of nodes. E.g. eval($X) / console.log($$$) / oldApi.foo($X). Matches code structure, so comments and strings never false-positive. Mutually exclusive with rule.',rule:'mode:"structural" only. A YAML relational/composite ast-grep rule blob for what plain patterns can\'t express — negation and parent/child relations (not/inside/has/all/any). E.g. "rule:\\n  pattern: await $C\\n  inside:\\n    kind: for_statement\\n    stopBy: end". NOTE: relational sub-rules need stopBy: end to walk all ancestors/descendants, else they silently match nothing. Mutually exclusive with pattern.',fixedString:"Literal match (disables regex). Mutually exclusive with perlRegex.",perlRegex:"Advanced regex (lookaheads, backreferences). Mutually exclusive with fixedString.",caseInsensitive:"Case-insensitive matching. Mutually exclusive with caseSensitive.",caseSensitive:"Case-sensitive matching. Mutually exclusive with caseInsensitive.",wholeWord:"Matches whole words only.",invertMatch:"Returns non-matching lines. To list files lacking the pattern, use filesWithoutMatch instead.",include:"Globs of files to search, e.g. '*.ts', 'src/**/*.tsx'. Only files matching any glob are searched.",exclude:"Globs of files to skip, e.g. '*.min.js', 'dist/**'.",excludeDir:"Directory names to skip entirely (e.g. 'node_modules', 'dist', '.git') — faster than exclude globs for whole directories.",noIgnore:"Searches files normally hidden by .gitignore/.ignore.",hidden:"Includes hidden (dot) files.",filesOnly:"Returns matching file paths without line content. Mutually exclusive with filesWithoutMatch.",filesWithoutMatch:"Returns files that do NOT contain the pattern — useful to find files missing a required import or header. Mutually exclusive with filesOnly.",contextLines:"Lines of context around each match. Pair with mode:'detailed' for self-contained snippets.",matchContentLength:"Characters kept per match snippet. Raise for minified code or JSON, or when truncation hides matches.",maxMatchesPerFile:"Caps matches per file and sets the per-file page size; when a file has more, file.pagination.hasMore appears — page it with matchPage. No effect in filesOnly/count modes.",maxFiles:"Caps how many matched files are returned.",multiline:"Lets a match span lines. Add multilineDotall to let . cross newlines.",multilineDotall:"Lets . match newlines too. Requires multiline:true.",sort:"Order results by path, modified time, access time, or creation time.",sortReverse:"Reverses the sort (e.g. sort:'modified' + sortReverse:true = oldest first).",langType:"Language filter (ts, js, py, go, rust, …) — more precise than include globs.",countLinesPerFile:"Returns the count of matching lines per file instead of content — good for orientation (which files have the most hits). Mutually exclusive with countMatchesPerFile.",countMatchesPerFile:"Returns the total match count per file (counts multiple hits on one line). Mutually exclusive with countLinesPerFile.",matchPage:"Page within one file's matches; pair with maxMatchesPerFile to walk a noisy file.",itemsPerPage:"Files per page.",page:"Result page."}};export const RipgrepQuerySchema=t(localSearchCode.schema,{...l,keywords:e.string().optional(),path:e.string(),mode:e.enum(["paginated","discovery","detailed","structural"]).default("paginated"),pattern:e.string().optional(),rule:e.string().optional(),fixedString:e.boolean().optional(),perlRegex:e.boolean().optional(),caseInsensitive:e.boolean().optional(),caseSensitive:e.boolean().optional(),wholeWord:e.boolean().optional(),invertMatch:e.boolean().optional(),include:u,exclude:u,excludeDir:u,noIgnore:e.boolean().optional(),hidden:e.boolean().optional(),filesOnly:e.boolean().optional(),filesWithoutMatch:e.boolean().optional(),contextLines:a(),matchContentLength:i(1,n).default(s),maxMatchesPerFile:i(1,n).optional(),maxFiles:i(1,n).optional(),multiline:e.boolean().optional(),multilineDotall:e.boolean().optional(),sort:e.enum(["path","modified","accessed","created"]).default("path"),sortReverse:e.boolean().optional(),langType:e.string().optional(),countLinesPerFile:e.boolean().optional(),countMatchesPerFile:e.boolean().optional(),matchPage:r(),itemsPerPage:i(1,o).optional(),page:c()}).superRefine((e,t)=>{if("structural"===e.mode){e.pattern||e.rule||t.addIssue({code:"custom",message:'mode:"structural" requires `pattern` (a code-shaped query) or `rule` (a YAML relational rule).',path:["pattern"]}),e.pattern&&e.rule&&t.addIssue({code:"custom",message:"`pattern` and `rule` are mutually exclusive.",path:["rule"]});for(const a of["fixedString","perlRegex","wholeWord","invertMatch","multiline","multilineDotall"])e[a]&&t.addIssue({code:"custom",message:`\`${a}\` is not valid with mode:"structural".`,path:[a]})}else(e.pattern||e.rule)&&t.addIssue({code:"custom",message:'`pattern`/`rule` require mode:"structural".',path:[e.pattern?"pattern":"rule"]}),e.keywords||t.addIssue({code:"custom",message:'`keywords` is required unless mode:"structural".',path:["keywords"]});e.filesOnly&&e.filesWithoutMatch&&t.addIssue({code:"custom",message:"filesOnly and filesWithoutMatch are mutually exclusive.",path:["filesWithoutMatch"]}),e.fixedString&&e.perlRegex&&t.addIssue({code:"custom",message:"fixedString and perlRegex are mutually exclusive.",path:["perlRegex"]}),e.caseSensitive&&e.caseInsensitive&&t.addIssue({code:"custom",message:"caseSensitive and caseInsensitive are mutually exclusive.",path:["caseInsensitive"]}),e.multilineDotall&&!e.multiline&&t.addIssue({code:"custom",message:"multilineDotall requires multiline=true.",path:["multilineDotall"]}),e.countLinesPerFile&&e.countMatchesPerFile&&t.addIssue({code:"custom",message:"countLinesPerFile and countMatchesPerFile are mutually exclusive.",path:["countMatchesPerFile"]})});

package/dist/resources/tools/localViewStructure.d.ts

@@ -1,2 +1,29 @@
+import { z } from "zod";
 import type { ToolSpec } from "../../types/index.js";
 export declare const localViewStructure: ToolSpec;
+export declare const ViewStructureQuerySchema: z.ZodObject<{
+    path: z.ZodString;
+    details: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    sortBy: z.ZodDefault<z.ZodEnum<{
+        extension: "extension";
+        size: "size";
+        name: "name";
+        time: "time";
+    }>>;
+    reverse: z.ZodOptional<z.ZodBoolean>;
+    pattern: z.ZodOptional<z.ZodString>;
+    directoriesOnly: z.ZodOptional<z.ZodBoolean>;
+    filesOnly: z.ZodOptional<z.ZodBoolean>;
+    recursive: z.ZodOptional<z.ZodBoolean>;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    showFileLastModified: z.ZodOptional<z.ZodBoolean>;
+    page: z.ZodDefault<z.ZodNumber>;
+    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/resources/tools/localViewStructure.js

@@ -1 +1 @@
-export const localViewStructure={name:"localViewStructure",description:"Inspect local directory tree and separate implementation from tests, fixtures, docs, generated output.\nNext: localGetFileContent(path), localSearchCode, lspGetSemanticContent after localSearchCode gives uri/symbolName/lineHint.",schema:{path:"Directory to browse.",details:"Set true for per-entry objects with size, permissions, and dates.",hidden:"Include hidden (dot) files and directories.",sortBy:"Sort by name, size, time, or extension.",reverse:"Reverse sort order.",pattern:"Filename/directory name filter — glob (e.g. '*.ts') or plain substring. For regex use localFindFiles.",directoriesOnly:"Return directories; mutually exclusive with filesOnly.",filesOnly:"Return files; mutually exclusive with directoriesOnly.",recursive:"Recursively walk subdirectories; depth controls how far to descend.",extensions:"Extension whitelist (['ts', 'js']).",depth:"Recursion depth.",limit:"Pre-pagination cap on discovered entries; distinct from page size.",showFileLastModified:"Set true to include last-modified timestamps; also enabled with details or sortBy=time.",page:"Result page (1-based).",itemsPerPage:"Directory entries per page for structure pagination."}};
+import{z as e}from"zod";import{buildObject as t,intRange as i,MAX_LOCAL_DEPTH as o,MAX_LOCAL_ITEMS_PER_PAGE as s,MAX_LOCAL_LIMIT as n,metaFields as a,pageNumber as r,StringArray as l}from"./_toolkit.js";export const localViewStructure={name:"localViewStructure",description:'Browse a local directory tree. Returns files[], folders[], and links[] (symlinks) at each level. When details:true or showFileLastModified:true, switches to entries[] objects with size, permissions, and timestamps.\nUse this to map a directory before searching. Use localFindFiles when you need metadata (size, modified date) or filename patterns. Use localSearchCode(mode:"discovery") to find which files contain a pattern.\nMutual exclusion: filesOnly and directoriesOnly cannot both be true.\nBulk: queries:[{path:d1},{path:d2}] to browse multiple directories in one call (max 5).\nPaginate with page=N when pagination.hasMore is true.\nNext: localGetFileContent(path), localSearchCode, lspGetSemantics after localSearchCode gives uri/symbolName/lineHint.',schema:{path:"Directory to browse (absolute or workspace-relative). Defaults to the workspace root.",details:"Returns per-entry objects with size, permissions, and dates (structured entries[] output).",hidden:"Includes hidden (dot) files and directories, e.g. .env, .git, .github.",sortBy:"Ordering. 'name': A–Z. 'size': by bytes. 'time': by last-modified (implicitly enables showFileLastModified). 'extension': grouped by file type.",reverse:"Reverses the sort (e.g. sortBy:'time' + reverse:true = oldest first).",pattern:"Name filter — a glob (e.g. '*.ts') or plain substring; only matching entries are returned. For regex, use localFindFiles.",directoriesOnly:"Returns directories only. Mutually exclusive with filesOnly.",filesOnly:"Returns files only. Mutually exclusive with directoriesOnly.",recursive:"Descends into subdirectories (top level only when off). When on without maxDepth, depth is capped automatically; set maxDepth to control cost.",extensions:"Extension whitelist, without dots, e.g. ['ts', 'tsx', 'js']. Only matching files are returned; directories always appear.",maxDepth:"Recursion depth when recursive is on (0 = immediate children). Start shallow on large monorepos, then drill in.",limit:"Caps how many entries are discovered before pagination — guards against huge scans. Distinct from page size.",showFileLastModified:"Adds last-modified timestamps per file. Independent of details. Use to spot recently changed files without switching to localFindFiles.",page:"Result page.",itemsPerPage:"Entries per page."}};export const ViewStructureQuerySchema=t(localViewStructure.schema,{...a,path:e.string(),details:e.boolean().optional(),hidden:e.boolean().optional(),sortBy:e.enum(["name","size","time","extension"]).default("name"),reverse:e.boolean().optional(),pattern:e.string().optional(),directoriesOnly:e.boolean().optional(),filesOnly:e.boolean().optional(),recursive:e.boolean().optional(),extensions:l,maxDepth:i(0,o).optional(),limit:i(1,n).optional(),showFileLastModified:e.boolean().optional(),page:r(),itemsPerPage:i(1,s).optional()}).superRefine((e,t)=>{e.filesOnly&&e.directoriesOnly&&t.addIssue({code:"custom",message:"filesOnly and directoriesOnly are mutually exclusive.",path:["directoriesOnly"]})});

package/dist/resources/tools/lspGetSemantics.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import type { ToolSpec } from "../../types/index.js";
+export declare const lspGetSemantics: ToolSpec;
+export declare const LSPGotoDefinitionQuerySchema: z.ZodObject<{
+    contextLines: z.ZodOptional<z.ZodNumber>;
+    uri: z.ZodString;
+    symbolName: z.ZodString;
+    lineHint: z.ZodNumber;
+    orderHint: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const LSPFindReferencesQuerySchema: z.ZodObject<{
+    includeDeclaration: z.ZodOptional<z.ZodBoolean>;
+    contextLines: z.ZodOptional<z.ZodNumber>;
+    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodNumber>;
+    groupByFile: z.ZodOptional<z.ZodBoolean>;
+    uri: z.ZodString;
+    symbolName: z.ZodString;
+    lineHint: z.ZodNumber;
+    orderHint: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const LSPCallHierarchyQuerySchema: z.ZodObject<{
+    direction: z.ZodEnum<{
+        incoming: "incoming";
+        outgoing: "outgoing";
+    }>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    contextLines: z.ZodOptional<z.ZodNumber>;
+    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodNumber>;
+    uri: z.ZodString;
+    symbolName: z.ZodString;
+    lineHint: z.ZodNumber;
+    orderHint: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const LspGetSemanticsQuerySchema: z.ZodObject<{
+    uri: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        references: "references";
+        definition: "definition";
+        callers: "callers";
+        callees: "callees";
+        callHierarchy: "callHierarchy";
+        hover: "hover";
+        documentSymbols: "documentSymbols";
+        typeDefinition: "typeDefinition";
+        implementation: "implementation";
+    }>>;
+    symbolName: z.ZodOptional<z.ZodString>;
+    lineHint: z.ZodOptional<z.ZodNumber>;
+    orderHint: z.ZodDefault<z.ZodNumber>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    includeDeclaration: z.ZodDefault<z.ZodBoolean>;
+    groupByFile: z.ZodOptional<z.ZodBoolean>;
+    page: z.ZodDefault<z.ZodNumber>;
+    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+    contextLines: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodDefault<z.ZodEnum<{
+        structured: "structured";
+        compact: "compact";
+    }>>;
+    workspaceRoot: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/resources/tools/lspGetSemantics.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{buildObject as t,contextLines as n,intRange as o,MAX_LINE_NUMBER as i,MAX_LOCAL_DEPTH as l,MAX_ORDER_HINT as a,MAX_PR_ITEMS_PER_PAGE as s,metaFields as r,pageNumber as c}from"./_toolkit.js";export const lspGetSemantics={name:"lspGetSemantics",description:"Typed LSP queries for semantic navigation (default type: definition).\nPrerequisites: all types except documentSymbols require symbolName + lineHint. lineHint must come from a real localSearchCode match (matches[0].line) — never guess. A wrong lineHint causes silent empty results. If lineHint is unknown: run documentSymbols (uri only) or localSearchCode first.\nType routing: documentSymbols=file outline (uri only); hover=signature+JSDoc; definition=jump to decl; typeDefinition=generic types; implementation=abstract member impl (member name, not class); references=same-package usages (bounded by the language server's open files, NOT cross-package — zero results does NOT mean unused, try callers); callers=cross-package incoming calls (TS/JS/Go/Rust only — Python/C++ use references instead); callees=outgoing calls; callHierarchy=both.\nToken efficiency: format:\"compact\" on callers/callees/callHierarchy → significantly fewer tokens. groupByFile:true on references → per-file summary with lines[] (each is a valid lineHint for follow-up calls). contextLines=3–10 on callers/callees embeds source context, reducing follow-up localGetFileContent calls.\nLanguage tiers — Tier 1 all types: TS/JS/Go/Rust. Tier 2 no callHierarchy: Python/C++. Tier 3 documentSymbols+hover+definition only: Shell/HTML/CSS/YAML/TOML.\nOutput signal: resolvedSymbol.foundAtLine confirms which line LSP resolved — if far from lineHint, re-run localSearchCode to get an accurate anchor. payload.kind='empty' means LSP returned no results (symbolNotFound → re-anchor with localSearchCode; serverUnavailable → fall back to localSearchCode). In callers/callees results, each ranges[].line is the lineHint for the next lspGetSemantics call on that symbol.\nevidence.answerReady:true — stop calling.\nNext: localGetFileContent(startLine/endLine) to read the definition; lspGetSemantics(callers) for impact analysis. Batch: up to 5 queries per call — combine definition+hover or definition+callers in one request.",schema:{uri:"Target source file as an absolute path or file:/// URI.",type:"Which query to run — see the type-routing list in the description.",symbolName:"Exact identifier sitting at lineHint — bare name only, no parentheses or type annotations (e.g. 'fetchPRDetail', not 'fetchPRDetail()'). Case-sensitive, must match the token exactly. Required for every type except documentSymbols.",lineHint:"Line where symbolName appears. Must come from a real localSearchCode match (matches[0].line) — never guess; a wrong value silently returns nothing. Required for every type except documentSymbols.",orderHint:"Disambiguates when symbolName occurs multiple times on lineHint (e.g. overloads, chained calls) — increment if you get the wrong symbol.",depth:"Recursion depth for callHierarchy/callers/callees — immediate calls only unless raised. Raise for full chains; pair high depth on hot symbols with format:'compact' to limit size.",includeDeclaration:"references: whether to include the symbol's own declaration. Set false to get only usages, not the definition site.",groupByFile:"references: returns a per-file summary (path + count + all line numbers in lines[]) instead of per-location rows — ideal for blast radius; each line is a valid lineHint for follow-ups.",page:"Result page for documentSymbols and call-flow results.",itemsPerPage:"Items per page (symbol/location lists get a larger page than call-flow results).",contextLines:"Source lines around each call site in callers/callees/callHierarchy (locations only unless set). Raise to embed calling context and skip a follow-up localGetFileContent.",format:'"structured": typed objects with full location metadata. "compact": line-oriented strings, far fewer tokens. Prefer "compact" for navigation; use "structured" only when parsing locations programmatically.',workspaceRoot:"Overrides the LSP workspace root (absolute path). Omit to auto-resolve from uri; needed only when the server spans multiple roots."}};const m={...r,uri:e.string(),symbolName:e.string(),lineHint:o(1,i),orderHint:o(0,a).default(0)};export const LSPGotoDefinitionQuerySchema=t(lspGetSemantics.schema,{...m,contextLines:n()});export const LSPFindReferencesQuerySchema=t(lspGetSemantics.schema,{...m,includeDeclaration:e.boolean().optional(),contextLines:n(),itemsPerPage:o(1,s).optional(),page:c(),groupByFile:e.boolean().optional()});export const LSPCallHierarchyQuerySchema=t(lspGetSemantics.schema,{...m,direction:e.enum(["incoming","outgoing"]),depth:o(0,l).optional(),contextLines:n(),itemsPerPage:o(1,s).optional(),page:c()});export const LspGetSemanticsQuerySchema=t(lspGetSemantics.schema,{...r,uri:e.string(),type:e.enum(["definition","references","callers","callees","callHierarchy","hover","documentSymbols","typeDefinition","implementation"]).default("definition"),symbolName:e.string().min(1).optional(),lineHint:o(1,i).optional(),orderHint:o(0,a).default(0),depth:o(0,l).optional(),includeDeclaration:e.boolean().default(!0),groupByFile:e.boolean().optional(),page:c(),itemsPerPage:o(1,s).optional(),contextLines:n(),format:e.enum(["structured","compact"]).default("structured"),workspaceRoot:e.string().optional()}).superRefine((e,t)=>{"documentSymbols"!==e.type&&(e.symbolName||t.addIssue({code:"custom",path:["symbolName"],message:"symbolName is required unless type is documentSymbols"}),Number.isInteger(e.lineHint)||t.addIssue({code:"custom",path:["lineHint"],message:"lineHint is required unless type is documentSymbols"}))});

package/dist/resources/tools/npmSearch.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import type { ToolSpec } from "../../types/index.js";
+export declare const npmSearch: ToolSpec;
+export declare const NpmPackageQuerySchema: z.ZodObject<{
+    packageName: z.ZodString;
+    page: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodOptional<z.ZodString>;
+    mainResearchGoal: z.ZodOptional<z.ZodString>;
+    researchGoal: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/resources/tools/npmSearch.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{buildObject as r,metaFields as t,pageNumber as a}from"./_toolkit.js";export const npmSearch={name:"npmSearch",description:'npm package lookup and keyword search. Returns package metadata and source repository handoff.\nExact package name (e.g. "react", "@octokit/rest") returns one rich result with version, description, keywords, and repository owner/repo for GitHub handoff.\nKeyword query (e.g. "http client typescript") returns lean results — paginate with page; pagination.hasMore and totalFound available in output.\nWhen owner+repo is present in the result, pass directly to ghViewRepoStructure or ghSearchCode. If a repositoryDirectory path follows owner/repo in the result, pass it as path= to ghViewRepoStructure to scope the tree to the package subdirectory.\nSkip if owner/repo is already known — go directly to ghViewRepoStructure.\nBatch up to 5 packages in one call: queries:[{packageName:"react"},{packageName:"lodash"}].\nNext: ghViewRepoStructure or ghSearchCode when owner/repo exists; ghSearchRepos when owner/repo is absent or non-GitHub.',schema:{packageName:"An exact npm package name or a keyword query. An exact name (e.g. 'react', '@octokit/rest') returns one rich result, or empty if it doesn't exist (check spelling before assuming it's private). A keyword query returns a lean list. Scoped packages need the full scope: '@octokit/rest', not 'rest'.",page:"Page for keyword results; exact-name lookups always return page 1. Paginate while pagination.hasMore."}};export const NpmPackageQuerySchema=r(npmSearch.schema,{...t,packageName:e.string(),page:a()});

package/dist/schemas/extraTypes.d.ts

@@ -1,14 +1,3 @@
-/**
- * Auxiliary downstream shapes for provider mappers and finalisers.
- * These types are too downstream-shaped to live in `src/types/index.ts`.
- *
- * Canonical data shapes (`LocalSearchCodeMatch`, `LocalSearchCodeFile`,
- * `LocalFindFilesEntry`, etc.) live in `src/types/index.ts`. This file only carries:
- *   - the `BaseQuery` meta + `BaseQueryLocal`,
- *   - the *mutable, flat* `*ToolResult` envelopes built by `octocode-mcp`,
- *   - provider-mapper shapes (`GitHubRepositoryOutput`,
- *     `GitHubSearchRepositoriesData`).
- */
 import type { CharPagination, LspRange, LspLocation, LspMode, PaginationInfo, LocalSearchCodeFile, LocalFindFilesEntry, GitHubRepositoryItem, GitHubPullRequestItem, GitHubSearchCodeGroup, GitHubFileContentData } from "../types/index.js";
 export interface BaseQuery {
     id?: string;
@@ -17,7 +6,6 @@ export interface BaseQuery {
     reasoning?: string;
     verbose?: boolean;
 }
-/** Local-tool flavour — adds the conventional `path` field. */
 export interface BaseQueryLocal extends BaseQuery {
     path?: string;
 }
@@ -47,12 +35,6 @@ interface BaseToolResult {
     error?: string;
     errorCode?: string;
     rawResponseChars?: number;
-    /**
-     * Index signature — `octocode-mcp`'s bulk runner threads extra
-     * fields (`data`, provider-specific blobs) through the result
-     * envelope. Keep it permissive so structural assignment to its
-     * `ProcessedBulkResult` succeeds without a cast.
-     */
     [key: string]: unknown;
 }
 export interface LocalSearchCodeToolResult extends BaseToolResult {
@@ -64,7 +46,6 @@ export interface LocalFindFilesToolResult extends BaseToolResult {
     files?: LocalFindFilesEntry[];
     pagination?: PaginationInfo;
 }
-/** Char-range pair carried by `LocalGetFileContentToolResult.matchRanges`. */
 export interface MatchRange {
     start: number;
     end: number;
@@ -78,11 +59,6 @@ export interface LocalGetFileContentToolResult extends BaseToolResult {
     endLine?: number;
     isPartial?: boolean;
     matchRanges?: MatchRange[];
-    /**
-     * Pagination metadata — either a char-budget paginator
-     * (`CharPagination`) for fully rendered output, or a row-counter
-     * paginator when results are paginated by line/match index.
-     */
     pagination?: CharPagination | PaginationInfo;
     modified?: string;
     lastModified?: string;
@@ -90,7 +66,6 @@ export interface LocalGetFileContentToolResult extends BaseToolResult {
     filePath?: string;
 }
 export interface LocalViewStructureEntryFlat {
-    /** Entry display name for rich directory listings. */
     name?: string;
     type: "file" | "dir" | "link" | "directory" | "symlink";
     path?: string;
@@ -100,15 +75,10 @@ export interface LocalViewStructureEntryFlat {
     permissions?: string;
 }
 export interface LocalViewStructureToolResult extends BaseToolResult {
-    /** Rich per-entry objects — emitted with details=true or showFileLastModified=true. */
     entries?: LocalViewStructureEntryFlat[];
-    /** Base directory for the flat name lists (lean default output). */
     path?: string;
-    /** Flat file name list (lean default; names carry subpaths in recursive mode). */
     files?: string[];
-    /** Flat directory name list (lean default). */
     folders?: string[];
-    /** Flat symlink name list (lean default, only when present). */
     links?: string[];
     summary?: string | Record<string, unknown>;
     pagination?: PaginationInfo;
@@ -201,12 +171,6 @@ export interface GitHubRepositoryOutput {
     license?: string;
     homepage?: string;
 }
-/**
- * Provider-facing repos-search result. Mirrors `GitHubSearchReposData`
- * but uses `GitHubRepositoryOutput` (the structurally rich shape with
- * `owner`/`repo` split, provider metadata) instead of the simpler
- * `GitHubRepositoryItem`.
- */
 export interface GitHubSearchRepositoriesData {
     repositories: GitHubRepositoryOutput[];
     pagination?: PaginationInfo;