@pkgseer/cli 0.4.0 → 0.4.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-c1e7ntb6.js";
+} from "./shared/chunk-d340pysc.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -6021,7 +6021,7 @@ var schemas = {
   navigationMode: z2.enum(["summary", "detailed"]).optional().describe("Response detail level. summary (default) returns core fields; detailed adds all optional fields."),
   waitTimeoutMs: z2.number().int().min(0).max(30000).optional().describe("Max milliseconds to wait for package indexing (0-30000). 0 = error immediately if not indexed."),
   symbolReference: z2.object({
-    symbol_id: z2.number().int().optional().describe("Direct symbol ID (preferred when available)"),
+    symbol_id: z2.number().int().optional().describe("Direct symbol ID from find_symbol or list_symbols results (preferred, avoids ambiguity)"),
     registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).optional().describe("Package registry (required for name-based lookup)"),
     package_name: z2.string().max(255).optional().describe("Package name (required for name-based lookup)"),
     symbol_name: z2.string().max(500).optional().describe("Symbol name or qualified path (required for name-based lookup). Matches both short name and qualifiedPath.")
@@ -6083,7 +6083,7 @@ var argsSchema = {
 function createCallPathTool(pkgseerService) {
   return {
     name: "call_path",
-    description: "Find the shortest call path between two symbols in the same package. " + "Uses BFS to find how function A eventually calls function B through intermediate calls. " + "Returns: whether a path was found, source and destination symbols, " + "and ordered call paths (shortest first) with hop details.",
+    description: "Find the shortest call path between two symbols in the same package. " + "Uses BFS to trace how function A eventually calls function B through intermediate calls. " + "Returns whether a path was found, with ordered call paths (shortest first) and hop details. " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
     schema: argsSchema,
     handler: async (args, _extra) => {
       return withErrorHandling("find call path", async () => {
@@ -6157,7 +6157,7 @@ var argsSchema3 = {
 function createFetchCodeContextTool(pkgseerService) {
   return {
     name: "fetch_code_context",
-    description: "Fetch code content from a repository. Use this to expand code search results and see " + "more context around a match. Returns full file by default, or a specific line range. " + "Requires repo_url, git_ref (tag/commit/branch), and file_path from search results.",
+    description: "Fetch code content from a repository by file path and line range. " + "Returns full file by default, or a specific line range. " + "For symbol-based lookup, use find_symbol(include_code=true) instead. " + "Requires repo_url, git_ref (tag/commit/branch), and file_path.",
     schema: argsSchema3,
     handler: async ({ repo_url, git_ref, file_path, start_line, end_line }, _extra) => {
       return withErrorHandling("fetch code context", async () => {
@@ -6226,7 +6226,7 @@ var argsSchema5 = {
 function createFindSymbolTool(pkgseerService) {
   return {
     name: "find_symbol",
-    description: "Find functions, methods, or classes by name in a package. " + "Use for targeted lookups when you know the symbol name. " + "Returns: symbol ID, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
+    description: "Find functions, methods, or classes by name in a package. " + "Set include_code=true to get full source code inline, avoiding separate fetch_code_context calls. " + "Returns: symbol ID, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
     schema: argsSchema5,
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol", async () => {
@@ -6295,7 +6295,7 @@ var argsSchema7 = {
 function createListSymbolsTool(pkgseerService) {
   return {
     name: "list_symbols",
-    description: "Browse symbols in a package by scope. " + "Use scope='exports' for public API exploration with namespace grouping and optional popularity data. " + "Use scope='file' with file_path to see all symbols in a specific file. " + "Returns: symbols with IDs, names, qualified paths, kinds, and file locations.",
+    description: "Browse symbols in a package by scope. " + "Use scope='exports' for public API with namespace grouping and optional popularity. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbols with IDs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to get source for any listed symbol.",
     schema: argsSchema7,
     handler: async (args, _extra) => {
       return withErrorHandling("list symbols", async () => {
@@ -6617,7 +6617,7 @@ Results may be incomplete. Retry later for more complete results.`;
 function createSearchTool(pkgseerService) {
   return {
     name: "search",
-    description: "Search code and documentation across packages. Returns functions, classes, and documentation pages " + "matching your query. Use mode='code' for code only, mode='docs' for documentation only, or " + "mode='all' (default) for both. Provide 1-20 packages to search. Results include relevance scores " + "and snippets showing matches. If packages need indexing, the search will wait up to waitTimeoutMs " + "(default 10s). If not complete, returns progress info with searchRef for follow-up.",
+    description: "Search code and documentation across packages. Returns functions, classes, and doc pages " + "matching your query. Use mode='code' for code only, mode='docs' for docs only, or " + "mode='all' (default). Provide 1-20 packages. Results include relevance scores and snippets. " + "For full source of code results, use find_symbol(name=<title>, include_code=true). " + "If packages need indexing, waits up to waitTimeoutMs (default 10s) or returns searchRef — use search_status to poll.",
     schema: argsSchema13,
     handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
       return withErrorHandling("search packages", async () => {
@@ -6737,7 +6737,7 @@ var argsSchema15 = {
 function createSearchStatusTool(pkgseerService) {
   return {
     name: "search_status",
-    description: "Check the status of an async search and get results if complete. " + "Use this after a search returns incomplete (completed=false) to poll for completion. " + "Returns status (PENDING, INDEXING, SEARCHING, COMPLETED, TIMEOUT, FAILED), " + "progress info (packagesReady/packagesTotal), and results when status is COMPLETED.",
+    description: "Check the status of an async search and get results if complete. " + "Use after search returns completed=false with a searchRef. Sessions expire after 1 hour. " + "Returns status (PENDING, INDEXING, SEARCHING, COMPLETED, TIMEOUT, FAILED), " + "progress info (packagesReady/packagesTotal), and results when COMPLETED.",
     schema: argsSchema15,
     handler: async ({ searchRef }, _extra) => {
       return withErrorHandling("check search status", async () => {
@@ -6801,7 +6801,7 @@ var argsSchema16 = {
 function createSearchSymbolsTool(pkgseerService) {
   return {
     name: "search_symbols",
-    description: "Full-text search within package code. " + "Searches across functions, classes, modules, and doc sections. " + "Returns: matching code chunks with name, type, file path, line numbers, " + "and content previews. Use for finding implementations by keyword.",
+    description: "Full-text search within package code. " + "Searches across functions, classes, modules, and doc sections. " + "Returns matching code chunks with name, type, file path, line numbers, and content previews. " + "Follow-up: use find_symbol(name=<result.name>, include_code=true) to get full source.",
     schema: argsSchema16,
     handler: async (args, _extra) => {
       return withErrorHandling("search symbols", async () => {
@@ -6837,7 +6837,7 @@ var argsSchema17 = {
 function createSymbolCalleesTool(pkgseerService) {
   return {
     name: "symbol_callees",
-    description: "Find what a symbol calls (its dependencies). " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes: callee names, qualified paths, file locations, call lines, " + "and external package references. Use to understand a function's dependency footprint.",
+    description: "Find what a symbol calls (its dependencies). " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes callee names, qualified paths, file locations, call lines, and external package references. " + "Get symbol_id from find_symbol or list_symbols results. See symbol_callers for the reverse.",
     schema: argsSchema17,
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callees", async () => {
@@ -6876,7 +6876,7 @@ var argsSchema18 = {
 function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
-    description: "Find what calls a symbol (its dependents/callers). " + "Returns: the target symbol and a list of symbols that call it, " + "with their file locations and call line numbers. " + "Use same_package_only to limit to callers within the same package.",
+    description: "Find what calls a symbol (its dependents/callers). " + "Returns the target symbol and a list of callers with file locations and call line numbers. " + "Use same_package_only to limit to callers within the same package. " + "Get symbol_id from find_symbol or list_symbols results. See symbol_callees for the reverse.",
     schema: argsSchema18,
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callers", async () => {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-c1e7ntb6.js";
+} from "./shared/chunk-d340pysc.js";
 export {
   version
 };

package/dist/shared/{chunk-c1e7ntb6.js → chunk-d340pysc.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.4.0";
+var version = "0.4.1";
 
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pkgseer/cli",
   "description": "CLI companion for PkgSeer - package intelligence for developers and AI assistants",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "files": [
     "dist",