@pkgseer/cli 0.4.11 → 0.5.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-r3pnzy5b.js";
+} from "./shared/chunk-kh5enjt9.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -315,13 +315,17 @@ var SearchResultsDocument = gql`
 }
     `;
 var FetchCodeContextDocument = gql`
-    query FetchCodeContext($repoUrl: String!, $gitRef: String!, $filePath: String!, $startLine: Int, $endLine: Int) {
+    query FetchCodeContext($repoUrl: String, $gitRef: String, $registry: Registry, $packageName: String, $version: String, $filePath: String!, $startLine: Int, $endLine: Int, $waitTimeoutMs: Int) {
   fetchCodeContext(
     repoUrl: $repoUrl
     gitRef: $gitRef
+    registry: $registry
+    packageName: $packageName
+    version: $version
     filePath: $filePath
     startLine: $startLine
     endLine: $endLine
+    waitTimeoutMs: $waitTimeoutMs
   ) {
     content
     filePath
@@ -656,10 +660,12 @@ var SearchPackageDocsDocument = gql`
 }
     `;
 var FindSymbolDocument = gql`
-    query FindSymbol($registry: Registry!, $packageName: String!, $name: String, $namespace: String, $kind: SymbolKind, $publicOnly: Boolean, $version: String, $includeCode: Boolean, $contextLines: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query FindSymbol($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $name: String, $namespace: String, $kind: SymbolKind, $publicOnly: Boolean, $version: String, $includeCode: Boolean, $contextLines: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
   findSymbol(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     name: $name
     namespace: $namespace
     kind: $kind
@@ -697,10 +703,12 @@ var FindSymbolDocument = gql`
 }
     `;
 var SearchSymbolsDocument = gql`
-    query SearchSymbols($registry: Registry!, $packageName: String!, $query: String, $keywords: [String!], $matchMode: MatchMode, $kind: SymbolKind, $filePath: String, $version: String, $limit: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query SearchSymbols($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $query: String, $keywords: [String!], $matchMode: MatchMode, $kind: SymbolKind, $filePath: String, $version: String, $limit: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
   searchSymbols(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     query: $query
     keywords: $keywords
     matchMode: $matchMode
@@ -743,10 +751,12 @@ var SearchSymbolsDocument = gql`
 }
     `;
 var ListSymbolsDocument = gql`
-    query ListSymbols($registry: Registry!, $packageName: String!, $scope: ListScope!, $filePath: String, $namespace: String, $publicOnly: Boolean, $includePopularity: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query ListSymbols($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $scope: ListScope!, $filePath: String, $namespace: String, $publicOnly: Boolean, $includePopularity: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
   listSymbols(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     scope: $scope
     filePath: $filePath
     namespace: $namespace
@@ -848,10 +858,12 @@ var SymbolDependentsDocument = gql`
 }
     `;
 var PackageImportsDocument = gql`
-    query PackageImports($registry: Registry!, $packageName: String!, $filePath: String, $resolvedOnly: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query PackageImports($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $filePath: String, $resolvedOnly: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
   packageImports(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     filePath: $filePath
     resolvedOnly: $resolvedOnly
     limit: $limit
@@ -941,10 +953,12 @@ var SearchProjectDocsDocument = gql`
 }
     `;
 var ListRepoFilesDocument = gql`
-    query ListRepoFiles($registry: Registry!, $packageName: String!, $version: String, $pathPrefix: String, $limit: Int, $waitTimeoutMs: Int) {
+    query ListRepoFiles($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $version: String, $pathPrefix: String, $limit: Int, $waitTimeoutMs: Int) {
   listRepoFiles(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     version: $version
     pathPrefix: $pathPrefix
     limit: $limit
@@ -971,10 +985,12 @@ var ListRepoFilesDocument = gql`
 }
     `;
 var GrepRepoFileDocument = gql`
-    query GrepRepoFile($registry: Registry!, $packageName: String!, $filePath: String!, $pattern: String!, $contextLines: Int, $maxMatches: Int, $version: String, $waitTimeoutMs: Int) {
+    query GrepRepoFile($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $filePath: String!, $pattern: String!, $contextLines: Int, $maxMatches: Int, $version: String, $waitTimeoutMs: Int) {
   grepRepoFile(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     filePath: $filePath
     pattern: $pattern
     contextLines: $contextLines
@@ -1005,10 +1021,12 @@ var GrepRepoFileDocument = gql`
 }
     `;
 var VersionDiffDocument = gql`
-    query VersionDiff($registry: Registry!, $packageName: String!, $fromVersion: String!, $toVersion: String!, $includePrivate: Boolean, $kind: SymbolKind, $limit: Int, $waitTimeoutMs: Int) {
+    query VersionDiff($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $fromVersion: String!, $toVersion: String!, $includePrivate: Boolean, $kind: SymbolKind, $limit: Int, $waitTimeoutMs: Int) {
   versionDiff(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     fromVersion: $fromVersion
     toVersion: $toVersion
     includePrivate: $includePrivate
@@ -1641,20 +1659,26 @@ var TOOL_NAMES = [
   "fetch_package_doc",
   "search",
   "search_status",
-  "fetch_code_context",
+  "read_file",
   "search_project_docs",
-  "list_package_files",
-  "grep_package_file",
+  "list_files",
+  "grep_file",
   "find_symbol",
   "search_symbols",
   "list_symbols",
   "symbol_callers",
   "symbol_callees",
-  "package_imports",
+  "list_imports",
   "call_path",
   "trigger_indexing",
   "version_diff"
 ];
+var TOOL_NAME_MIGRATION = {
+  fetch_code_context: "read_file",
+  list_package_files: "list_files",
+  grep_package_file: "grep_file",
+  package_imports: "list_imports"
+};
 var ToolNameSchema = z.enum(TOOL_NAMES);
 var SharedConfigFields = {
   enabled_tools: z.array(ToolNameSchema).optional()
@@ -1762,6 +1786,24 @@ class ConfigServiceImpl {
       if (parsed === null || parsed === undefined) {
         return schema.parse({});
       }
+      if (parsed && typeof parsed === "object" && Array.isArray(parsed.enabled_tools)) {
+        const migrated = [];
+        let hasMigrations = false;
+        for (const name of parsed.enabled_tools) {
+          const replacement = TOOL_NAME_MIGRATION[name];
+          if (replacement) {
+            migrated.push(replacement);
+            hasMigrations = true;
+          } else {
+            migrated.push(name);
+          }
+        }
+        if (hasMigrations) {
+          const oldNames = parsed.enabled_tools.filter((n) => TOOL_NAME_MIGRATION[n]);
+          console.warn(`[pkgseer] Config at ${path}: migrating deprecated tool names: ${oldNames.join(", ")}. Update your config to use the new names.`);
+          parsed.enabled_tools = migrated;
+        }
+      }
       const result = schema.safeParse(parsed);
       if (result.success) {
         return result.data;
@@ -2207,9 +2249,13 @@ class PkgseerServiceImpl {
     const result = await this.client.FetchCodeContext({
       repoUrl,
       gitRef,
+      registry: options?.registry,
+      packageName: options?.packageName,
+      version: options?.version,
       filePath,
       startLine: options?.startLine,
-      endLine: options?.endLine
+      endLine: options?.endLine,
+      waitTimeoutMs: options?.waitTimeoutMs
     });
     return { data: result.data, errors: result.errors };
   }
@@ -2217,6 +2263,8 @@ class PkgseerServiceImpl {
     const result = await this.client.FindSymbol({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       name: options?.name,
       namespace: options?.namespace,
       kind: options?.kind,
@@ -2233,6 +2281,8 @@ class PkgseerServiceImpl {
     const result = await this.client.SearchSymbols({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       query: options?.query,
       keywords: options?.keywords,
       matchMode: options?.matchMode,
@@ -2249,6 +2299,8 @@ class PkgseerServiceImpl {
     const result = await this.client.ListSymbols({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       scope,
       filePath: options?.filePath,
       namespace: options?.namespace,
@@ -2289,6 +2341,8 @@ class PkgseerServiceImpl {
     const result = await this.client.PackageImports({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       filePath: options?.filePath,
       resolvedOnly: options?.resolvedOnly,
       limit: options?.limit,
@@ -2312,6 +2366,8 @@ class PkgseerServiceImpl {
     const result = await this.client.ListRepoFiles({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       version: options?.version,
       pathPrefix: options?.pathPrefix,
       limit: options?.limit,
@@ -2323,6 +2379,8 @@ class PkgseerServiceImpl {
     const result = await this.client.GrepRepoFile({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       filePath,
       pattern,
       contextLines: options?.contextLines,
@@ -2336,6 +2394,8 @@ class PkgseerServiceImpl {
     const result = await this.client.VersionDiff({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       fromVersion,
       toVersion,
       includePrivate: options?.includePrivate,
@@ -6747,17 +6807,88 @@ var schemas = {
   waitTimeoutMs: z2.coerce.number().int().min(0).max(30000).optional().describe("Max milliseconds to wait for package indexing (0-30000, default 10000). Set 0 to error immediately if not indexed."),
   symbolReference: z2.object({
     symbol_ref: z2.string().optional().describe("Compound symbol reference (registry:package:version:id) from find_symbol or list_symbols results. Self-contained — no additional fields needed."),
-    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.")
-  })
+    registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).optional().describe("Package registry. For package-scoped lookup (with package_name + symbol_name)."),
+    package_name: z2.string().max(255).optional().describe("Package name. For package-scoped lookup (with registry + symbol_name)."),
+    symbol_name: z2.string().max(500).optional().describe("Symbol name or qualified path (required for name-based lookup). Matches both short name and qualifiedPath."),
+    version: z2.string().max(100).optional().describe("Package version. For package-scoped lookup."),
+    repo_url: z2.string().optional().describe("Repository URL (GitHub). For repo-scoped lookup (with git_ref + symbol_name)."),
+    git_ref: z2.string().optional().describe("Git ref (tag, branch, commit, or HEAD). Required with repo_url.")
+  }),
+  codeTarget: z2.object({
+    registry: z2.enum([
+      "npm",
+      "pypi",
+      "hex",
+      "crates",
+      "nuget",
+      "maven",
+      "zig",
+      "vcpkg"
+    ]).optional().describe("Package registry (npm, pypi, hex, etc.). Required for package scope."),
+    package_name: z2.string().max(255).optional().describe("Package name. Required for package scope."),
+    version: z2.string().max(100).optional().describe("Package version, e.g. '4.18.2' (defaults to latest). For package scope only."),
+    repo_url: z2.string().optional().describe("Repository URL (GitHub). Required for repo scope. Example: https://github.com/expressjs/express"),
+    git_ref: z2.string().optional().describe("Git ref — tag, branch, or commit. Required for repo scope. Use HEAD for latest.")
+  }).describe("Target: provide registry + package_name (package scope) OR repo_url + git_ref (repo scope).")
 };
 function toSymbolReferenceInput(ref) {
   return {
     symbolRef: ref.symbol_ref,
     registry: ref.registry ? toGraphQLRegistry(ref.registry) : undefined,
     packageName: ref.package_name,
-    symbolName: ref.symbol_name
+    symbolName: ref.symbol_name,
+    version: ref.version,
+    repoUrl: ref.repo_url,
+    gitRef: ref.git_ref
+  };
+}
+function isToolError(value) {
+  return "content" in value;
+}
+function resolveCodeTarget(target) {
+  const hasPackage = target.registry || target.package_name;
+  const hasRepo = target.repo_url || target.git_ref;
+  if (hasPackage && hasRepo) {
+    return errorResult("Invalid target: provide either registry + package_name (package scope) or repo_url + git_ref (repo scope), not both.");
+  }
+  if (!hasPackage && !hasRepo) {
+    return errorResult("Missing target: provide registry + package_name (package scope) or repo_url + git_ref (repo scope).");
+  }
+  if (hasPackage) {
+    if (!target.registry || !target.package_name) {
+      return errorResult("Incomplete package target: both registry and package_name are required for package scope.");
+    }
+    return {
+      mode: "package",
+      registry: target.registry,
+      packageName: target.package_name,
+      version: target.version
+    };
+  }
+  if (!target.repo_url) {
+    return errorResult("Incomplete repo target: repo_url is required with git_ref.");
+  }
+  if (!target.git_ref) {
+    return errorResult("Incomplete repo target: git_ref is required with repo_url (use HEAD for latest).");
+  }
+  return { mode: "repo", repoUrl: target.repo_url, gitRef: target.git_ref };
+}
+function buildCodeTargetVars(resolved) {
+  if (resolved.mode === "package") {
+    return {
+      registry: toGraphQLRegistry(resolved.registry),
+      packageName: resolved.packageName,
+      version: resolved.version,
+      repoUrl: undefined,
+      gitRef: undefined
+    };
+  }
+  return {
+    registry: undefined,
+    packageName: undefined,
+    version: undefined,
+    repoUrl: resolved.repoUrl,
+    gitRef: resolved.gitRef
   };
 }
 var DEFAULT_WAIT_TIMEOUT_MS2 = 1e4;
@@ -6818,8 +6949,8 @@ function notFoundError(packageName, registry) {
 
 // src/tools/call-path.ts
 var argsSchema = {
-  from: schemas.symbolReference.describe("Source symbol. Provide either symbol_ref or registry + package_name + symbol_name."),
-  to: schemas.symbolReference.describe("Destination symbol. Provide either symbol_ref or registry + package_name + symbol_name."),
+  from: schemas.symbolReference.describe("Source symbol. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
+  to: schemas.symbolReference.describe("Destination symbol. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
   max_depth: z3.coerce.number().int().min(1).max(10).optional().describe("Maximum path length to search (max hops between from and to)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -6827,18 +6958,18 @@ var argsSchema = {
 function createCallPathTool(pkgseerService) {
   return {
     name: "call_path",
-    description: "Trace how execution flows from one function to another in a dependency — " + "debug how a public API reaches an internal function or error handler. " + "Uses BFS through intermediate calls. " + "Returns ordered call paths (shortest first) with hop details. " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
+    description: "Trace how execution flows from one function to another in a dependency — " + "debug how a public API reaches an internal function or error handler. " + "Uses BFS through intermediate calls. " + "Returns ordered call paths (shortest first) with hop details. " + "Supports package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
     schema: argsSchema,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find call path", async () => {
         const fromInput = toSymbolReferenceInput(args.from);
         const toInput = toSymbolReferenceInput(args.to);
-        if (!fromInput.symbolRef && (!fromInput.symbolName || !fromInput.registry || !fromInput.packageName)) {
-          return errorResult("Invalid 'from' symbol: provide either symbol_ref or symbol_name with registry and package_name.");
+        if (!fromInput.symbolRef && !(fromInput.symbolName && fromInput.registry && fromInput.packageName) && !(fromInput.symbolName && fromInput.repoUrl && fromInput.gitRef)) {
+          return errorResult("Invalid 'from' symbol: provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
-        if (!toInput.symbolRef && (!toInput.symbolName || !toInput.registry || !toInput.packageName)) {
-          return errorResult("Invalid 'to' symbol: provide either symbol_ref or symbol_name with registry and package_name.");
+        if (!toInput.symbolRef && !(toInput.symbolName && toInput.registry && toInput.packageName) && !(toInput.symbolName && toInput.repoUrl && toInput.gitRef)) {
+          return errorResult("Invalid 'to' symbol: provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
         const result = await pkgseerService.callPath(fromInput, toInput, {
           maxDepth: args.max_depth,
@@ -6888,54 +7019,16 @@ function createComparePackagesTool(pkgseerService) {
     }
   };
 }
-// src/tools/fetch-code-context.ts
+// src/tools/fetch-package-doc.ts
 import { z as z5 } from "zod";
 var argsSchema3 = {
-  repo_url: z5.string({
-    error: "repo_url is required. Get it from package_summary (returns repository URL). " + "Or use find_symbol(include_code=true) to read source without needing repo_url."
-  }).min(1).describe("Repository URL (GitHub). Example: https://github.com/expressjs/express"),
-  git_ref: z5.string({
-    error: "git_ref is required. Use the package version as a tag (e.g., 'v4.18.2'). " + "Get the latest version from package_summary."
-  }).min(1).describe("Git reference (tag, commit, or branch). Example: v4.18.2"),
-  file_path: z5.string({
-    error: "file_path is required. Get file paths from find_symbol (returns file locations) " + "or list_package_files (browse package file structure)."
-  }).min(1).describe("Path to file in repository. Example: src/router/index.js"),
-  start_line: z5.coerce.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
-  end_line: z5.coerce.number().int().positive().optional().describe("Ending line. If omitted, returns to end of file.")
-};
-function createFetchCodeContextTool(pkgseerService) {
-  return {
-    name: "fetch_code_context",
-    description: "Read source code from a dependency's repository by file path and line range — " + "use when you have a file path from a stack trace or symbol lookup. " + "Returns full file or a specific line range. " + "Prefer find_symbol(include_code=true) for function/class lookup. " + "Requires repo_url (from package_summary), git_ref (version tag, e.g. 'v4.18.2'), " + "and file_path (from find_symbol or list_package_files). " + "Operates on the full repository — not filtered to package subdirectory in monorepos.",
-    schema: argsSchema3,
-    annotations: { readOnlyHint: true },
-    handler: async ({ repo_url, git_ref, file_path, start_line, end_line }, _extra) => {
-      return withErrorHandling("fetch code context", async () => {
-        const result = await pkgseerService.fetchCodeContext(repo_url, git_ref, file_path, {
-          startLine: start_line,
-          endLine: end_line
-        });
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data?.fetchCodeContext) {
-          return errorResult(`Code not found: ${file_path} at ${git_ref} in ${repo_url}. ` + "Check that the repository, file path, and git ref are correct.");
-        }
-        return textResult(JSON.stringify(result.data?.fetchCodeContext, null, 2));
-      });
-    }
-  };
-}
-// src/tools/fetch-package-doc.ts
-import { z as z6 } from "zod";
-var argsSchema4 = {
-  page_id: z6.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
+  page_id: z5.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
 };
 function createFetchPackageDocTool(pkgseerService) {
   return {
     name: "fetch_package_doc",
     description: "Get full content of a documentation page. Requires page_id from list_package_docs. " + "Returns: title, full content (markdown/HTML), format type, navigation breadcrumbs, " + "source URL, and last updated timestamp. Use this when you need complete documentation, " + "not just search snippets. " + "Requires documentation to have been crawled — if page_id is from a stale listing, re-check with list_package_docs.",
-    schema: argsSchema4,
+    schema: argsSchema3,
     annotations: { readOnlyHint: true },
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
@@ -6952,13 +7045,12 @@ function createFetchPackageDocTool(pkgseerService) {
   };
 }
 // src/tools/find-symbol.ts
-import { z as z7 } from "zod";
-var argsSchema5 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search for symbols"),
-  name: z7.string().max(500).optional().describe("Symbol name to search for (exact match or prefix). Omit to return all public exports."),
-  namespace: z7.string().max(500).optional().describe("Filter by namespace/module path prefix"),
-  kind: z7.enum([
+import { z as z6 } from "zod";
+var argsSchema4 = {
+  target: schemas.codeTarget,
+  name: z6.string().max(500).optional().describe("Symbol name to search for (exact match or prefix). Omit to return all public exports."),
+  namespace: z6.string().max(500).optional().describe("Filter by namespace/module path prefix"),
+  kind: z6.enum([
     "function",
     "method",
     "class",
@@ -6967,31 +7059,36 @@ var argsSchema5 = {
     "type",
     "doc_section"
   ]).optional().describe("Filter by symbol kind"),
-  public_only: z7.boolean().optional().describe("Only return public/exported symbols"),
-  version: schemas.version,
-  include_code: z7.boolean().optional().describe("Include source code in results"),
-  context_lines: z7.coerce.number().int().min(0).max(30).optional().describe("Lines of surrounding context when include_code=true (max 30)"),
+  public_only: z6.boolean().optional().describe("Only return public/exported symbols"),
+  include_code: z6.boolean().optional().describe("Include source code in results"),
+  context_lines: z6.coerce.number().int().min(0).max(30).optional().describe("Lines of surrounding context when include_code=true (max 30)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createFindSymbolTool(pkgseerService) {
   return {
     name: "find_symbol",
-    description: "Read source code of any function, class, or method in a third-party package — " + "use instead of guessing implementations from training data. " + "Set include_code=true for full source inline. " + "Returns: symbolRef, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path. " + "Pass symbolRef from results to symbol_callers, symbol_callees, or call_path.",
-    schema: argsSchema5,
+    description: "Read source code of any function, class, or method — use instead of guessing " + "implementations from training data. Accepts package scope (registry + package_name) " + "or repo scope (repo_url + git_ref) via the target parameter. " + "Set include_code=true for full source inline. " + "Returns: symbolRef, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path. " + "Pass symbolRef from results to symbol_callers, symbol_callees, or call_path.",
+    schema: argsSchema4,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol", async () => {
-        const result = await pkgseerService.findSymbol(toGraphQLRegistry(args.registry), args.package_name, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.findSymbol(tv.registry, tv.packageName, {
           name: args.name,
           namespace: args.namespace,
           kind: toSymbolKind(args.kind),
           publicOnly: args.public_only,
-          version: args.version,
+          version: tv.version,
           includeCode: args.include_code,
           contextLines: args.context_lines,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7005,31 +7102,35 @@ function createFindSymbolTool(pkgseerService) {
     }
   };
 }
-// src/tools/grep-package-file.ts
-import { z as z8 } from "zod";
-var argsSchema6 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search within"),
-  file_path: z8.string().describe("Path to the file (relative to package root)"),
-  pattern: z8.string().max(200).describe("Case-insensitive substring to search for (max 200 chars)"),
-  context_lines: z8.coerce.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
-  max_matches: z8.coerce.number().int().min(1).max(200).optional().describe("Maximum matches to return (max 200)"),
-  version: schemas.version,
+// src/tools/grep-file.ts
+import { z as z7 } from "zod";
+var argsSchema5 = {
+  target: schemas.codeTarget,
+  file_path: z7.string().describe("Path to the file (relative to package root)"),
+  pattern: z7.string().max(200).describe("Case-insensitive substring to search for (max 200 chars)"),
+  context_lines: z7.coerce.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
+  max_matches: z7.coerce.number().int().min(1).max(200).optional().describe("Maximum matches to return (max 200)"),
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createGrepPackageFileTool(pkgseerService) {
+function createGrepFileTool(pkgseerService) {
   return {
-    name: "grep_package_file",
-    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Case-insensitive substring matching with context lines. " + "Use when you know the file path and are looking for specific text. " + "Use list_package_files to discover file paths. " + "In monorepos, operates only within this package's subdirectory. " + "Requires code indexing.",
-    schema: argsSchema6,
+    name: "grep_file",
+    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Case-insensitive substring matching with context lines. " + "Use when you know the file path and are looking for specific text. " + "Use list_files to discover file paths. " + "In monorepos with package scope, operates only within this package's subdirectory. " + "Requires code indexing.",
+    schema: argsSchema5,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("grep package file", async () => {
-        const result = await pkgseerService.grepRepoFile(toGraphQLRegistry(args.registry), args.package_name, args.file_path, args.pattern, {
+      return withErrorHandling("grep file", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.grepRepoFile(tv.registry, tv.packageName, args.file_path, args.pattern, {
           contextLines: args.context_lines,
           maxMatches: args.max_matches,
-          version: args.version,
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+          version: tv.version,
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7043,64 +7144,108 @@ function createGrepPackageFileTool(pkgseerService) {
     }
   };
 }
-// src/tools/list-package-docs.ts
-var argsSchema7 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to list documentation for"),
-  version: schemas.version
+// src/tools/list-files.ts
+import { z as z8 } from "zod";
+var argsSchema6 = {
+  target: schemas.codeTarget,
+  path_prefix: z8.string().optional().describe("Filter to files under this path (e.g., 'src/')"),
+  limit: z8.coerce.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
+  wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createListPackageDocsTool(pkgseerService) {
+function createListFilesTool(pkgseerService) {
   return {
-    name: "list_package_docs",
-    description: "Discover available documentation pages for a package. Start here before fetching or searching docs. " + "Returns: page titles, unique IDs (needed for fetch_package_doc), word counts, and update timestamps. " + "Workflow: list_package_docs → fetch_package_doc for full content, or search(mode='docs') to find specific topics. " + "Requires documentation to have been crawled — if results are empty, use trigger_indexing first, then retry.",
-    schema: argsSchema7,
+    name: "list_files",
+    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals. " + "In monorepos with package scope, returns only files within this package's subdirectory. " + "Requires code indexing.",
+    schema: argsSchema6,
     annotations: { readOnlyHint: true },
-    handler: async ({ registry, package_name, version: version2 }, _extra) => {
-      return withErrorHandling("list package documentation", async () => {
-        const result = await pkgseerService.listPackageDocs(toGraphQLRegistry(registry), package_name, version2);
+    handler: async (args, _extra) => {
+      return withErrorHandling("list files", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.listRepoFiles(tv.registry, tv.packageName, {
+          version: tv.version,
+          pathPrefix: args.path_prefix,
+          limit: args.limit,
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
+        });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listPackageDocs) {
-          return notFoundError(package_name, registry);
+        const data = result.data.listRepoFiles;
+        if (data.files.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
-        return textResult(JSON.stringify(result.data?.listPackageDocs, null, 2));
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
 }
-// src/tools/list-package-files.ts
+// src/tools/list-imports.ts
 import { z as z9 } from "zod";
-var argsSchema8 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to list files for"),
-  version: schemas.version,
-  path_prefix: z9.string().optional().describe("Filter to files under this path (e.g., 'src/')"),
-  limit: z9.coerce.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
+var argsSchema7 = {
+  target: schemas.codeTarget,
+  file_path: z9.string().max(1000).optional().describe("Filter to a specific file path"),
+  resolved_only: z9.boolean().optional().describe("Only return imports resolved to a known package"),
+  limit: z9.coerce.number().int().min(1).max(500).optional().describe("Max imports to return"),
+  mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createListPackageFilesTool(pkgseerService) {
+function createListImportsTool(pkgseerService) {
   return {
-    name: "list_package_files",
-    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals. " + "In monorepos, returns only files within this package's subdirectory. " + "Requires code indexing.",
-    schema: argsSchema8,
+    name: "list_imports",
+    description: "See what a dependency imports — understand its internal dependencies and external package usage. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Returns parsed import/require/use statements with optional resolution to known packages. " + "Use resolved_only=true to see only imports that map to packages in the PkgSeer registry. " + "Includes: source path, imported names, and de-duplicated dependency list.",
+    schema: argsSchema7,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("list package files", async () => {
-        const result = await pkgseerService.listRepoFiles(toGraphQLRegistry(args.registry), args.package_name, {
-          version: args.version,
-          pathPrefix: args.path_prefix,
+      return withErrorHandling("list imports", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.packageImports(tv.registry, tv.packageName, {
+          filePath: args.file_path,
+          resolvedOnly: args.resolved_only,
           limit: args.limit,
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+          version: tv.version,
+          mode: toNavigationMode(args.mode),
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        const data = result.data.listRepoFiles;
-        if (data.files.length === 0 && data.diagnostics?.hint) {
-          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        return textResult(JSON.stringify(result.data.packageImports, null, 2));
+      });
+    }
+  };
+}
+// src/tools/list-package-docs.ts
+var argsSchema8 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to list documentation for"),
+  version: schemas.version
+};
+function createListPackageDocsTool(pkgseerService) {
+  return {
+    name: "list_package_docs",
+    description: "Discover available documentation pages for a package. Start here before fetching or searching docs. " + "Returns: page titles, unique IDs (needed for fetch_package_doc), word counts, and update timestamps. " + "Workflow: list_package_docs → fetch_package_doc for full content, or search(mode='docs') to find specific topics. " + "Requires documentation to have been crawled — if results are empty, use trigger_indexing first, then retry.",
+    schema: argsSchema8,
+    annotations: { readOnlyHint: true },
+    handler: async ({ registry, package_name, version: version2 }, _extra) => {
+      return withErrorHandling("list package documentation", async () => {
+        const result = await pkgseerService.listPackageDocs(toGraphQLRegistry(registry), package_name, version2);
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data?.listPackageDocs) {
+          return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(data, null, 2));
+        return textResult(JSON.stringify(result.data?.listPackageDocs, null, 2));
       });
     }
   };
@@ -7108,22 +7253,20 @@ function createListPackageFilesTool(pkgseerService) {
 // src/tools/list-symbols.ts
 import { z as z10 } from "zod";
 var argsSchema9 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to browse symbols for"),
+  target: schemas.codeTarget,
   scope: z10.enum(["exports", "file"]).describe("Browsing scope: 'exports' for public API, 'file' for all symbols in a specific file"),
   file_path: z10.string().max(1000).optional().describe("File path within the repo (required when scope=file)"),
   namespace: z10.string().max(500).optional().describe("Filter by namespace prefix (e.g., 'React' to see React.*)"),
   public_only: z10.boolean().optional().describe("Only return public symbols"),
   include_popularity: z10.boolean().optional().describe("Include callerCount for each symbol (slightly slower)"),
   limit: z10.coerce.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
-  version: schemas.version,
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createListSymbolsTool(pkgseerService) {
   return {
     name: "list_symbols",
-    description: "Browse a dependency's public API or file-level symbols. " + "Use scope='exports' for the public API with optional popularity ranking. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbol refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to read source for any result.",
+    description: "Browse a dependency's public API or file-level symbols. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Use scope='exports' for the public API with optional popularity ranking. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbol refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to read source for any result.",
     schema: argsSchema9,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
@@ -7140,15 +7283,21 @@ function createListSymbolsTool(pkgseerService) {
             isError: true
           };
         }
-        const result = await pkgseerService.listSymbols(toGraphQLRegistry(args.registry), args.package_name, scope, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.listSymbols(tv.registry, tv.packageName, scope, {
           filePath: args.file_path,
           namespace: args.namespace,
           publicOnly: args.public_only,
           includePopularity: args.include_popularity,
           limit: args.limit,
-          version: args.version,
+          version: tv.version,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7281,44 +7430,8 @@ function createPackageDependenciesTool(pkgseerService) {
     }
   };
 }
-// src/tools/package-imports.ts
-import { z as z12 } from "zod";
-var argsSchema11 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to get imports for"),
-  file_path: z12.string().max(1000).optional().describe("Filter to a specific file path"),
-  resolved_only: z12.boolean().optional().describe("Only return imports resolved to a known package"),
-  limit: z12.coerce.number().int().min(1).max(500).optional().describe("Max imports to return"),
-  version: schemas.version,
-  mode: schemas.navigationMode,
-  wait_timeout_ms: schemas.waitTimeoutMs
-};
-function createPackageImportsTool(pkgseerService) {
-  return {
-    name: "package_imports",
-    description: "See what a dependency imports — understand its internal dependencies and external package usage. " + "Returns parsed import/require/use statements with optional resolution to known packages. " + "Use resolved_only=true to see only imports that map to packages in the PkgSeer registry. " + "Includes: source path, imported names, and de-duplicated dependency list.",
-    schema: argsSchema11,
-    annotations: { readOnlyHint: true },
-    handler: async (args, _extra) => {
-      return withErrorHandling("fetch package imports", async () => {
-        const result = await pkgseerService.packageImports(toGraphQLRegistry(args.registry), args.package_name, {
-          filePath: args.file_path,
-          resolvedOnly: args.resolved_only,
-          limit: args.limit,
-          version: args.version,
-          mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
-        });
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        return textResult(JSON.stringify(result.data.packageImports, null, 2));
-      });
-    }
-  };
-}
 // src/tools/package-quality.ts
-var argsSchema12 = {
+var argsSchema11 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to analyze"),
   version: schemas.version
@@ -7327,7 +7440,7 @@ function createPackageQualityTool(pkgseerService) {
   return {
     name: "package_quality",
     description: "Evaluate package maintenance health and code quality (available immediately — no indexing required). " + "Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
-    schema: argsSchema12,
+    schema: argsSchema11,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package quality", async () => {
@@ -7344,7 +7457,7 @@ function createPackageQualityTool(pkgseerService) {
   };
 }
 // src/tools/package-summary.ts
-var argsSchema13 = {
+var argsSchema12 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to retrieve summary for")
 };
@@ -7352,7 +7465,7 @@ function createPackageSummaryTool(pkgseerService) {
   return {
     name: "package_summary",
     description: "Get a comprehensive overview of a package (available immediately — no indexing required). " + "Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details). " + "Use package.repositoryUrl + package.latestVersion as git_ref with fetch_code_context to read source files.",
-    schema: argsSchema13,
+    schema: argsSchema12,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name }, _extra) => {
       return withErrorHandling("fetch package summary", async () => {
@@ -7369,7 +7482,7 @@ function createPackageSummaryTool(pkgseerService) {
   };
 }
 // src/tools/package-vulnerabilities.ts
-var argsSchema14 = {
+var argsSchema13 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to inspect for vulnerabilities"),
   version: schemas.version
@@ -7378,7 +7491,7 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
   return {
     name: "package_vulnerabilities",
     description: "Check security vulnerabilities for a package (available immediately — no indexing required). " + "Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
-    schema: argsSchema14,
+    schema: argsSchema13,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package vulnerabilities", async () => {
@@ -7394,6 +7507,48 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     }
   };
 }
+// src/tools/read-file.ts
+import { z as z12 } from "zod";
+var argsSchema14 = {
+  target: schemas.codeTarget,
+  file_path: z12.string({
+    error: "file_path is required. Get file paths from find_symbol (returns file locations) " + "or list_files (browse file structure)."
+  }).min(1).describe("Path to file in repository. Example: src/router/index.js"),
+  start_line: z12.coerce.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
+  end_line: z12.coerce.number().int().positive().optional().describe("Ending line. If omitted, returns to end of file."),
+  wait_timeout_ms: schemas.waitTimeoutMs
+};
+function createReadFileTool(pkgseerService) {
+  return {
+    name: "read_file",
+    description: "Read source code from a dependency's repository by file path and line range — " + "use when you have a file path from a stack trace or symbol lookup. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Returns full file or a specific line range. " + "Prefer find_symbol(include_code=true) for function/class lookup. " + "Use list_files to discover file paths. " + "With repo scope, operates on the full repository. " + "With package scope, scoped to the package subdirectory in monorepos.",
+    schema: argsSchema14,
+    annotations: { readOnlyHint: true },
+    handler: async (args, _extra) => {
+      return withErrorHandling("read file", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.fetchCodeContext(tv.repoUrl, tv.gitRef, args.file_path, {
+          startLine: args.start_line,
+          endLine: args.end_line,
+          registry: tv.registry,
+          packageName: tv.packageName,
+          version: tv.version,
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data?.fetchCodeContext) {
+          return errorResult(`File not found: ${args.file_path}. ` + "Check that the file path and target are correct. " + "Use list_files to discover available files.");
+        }
+        return textResult(JSON.stringify(result.data.fetchCodeContext, null, 2));
+      });
+    }
+  };
+}
 // src/tools/search.ts
 import { z as z13 } from "zod";
 var packageInputSchema2 = z13.object({
@@ -7617,8 +7772,7 @@ function createSearchStatusTool(pkgseerService) {
 // src/tools/search-symbols.ts
 import { z as z16 } from "zod";
 var argsSchema18 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search within"),
+  target: schemas.codeTarget,
   query: z16.string().max(500).optional().describe("Search query for full-text code search (max 500 chars). Required if keywords not provided."),
   keywords: z16.array(z16.string()).max(20).optional().describe("Search keywords (max 20). Combined using match_mode. Alternative to query."),
   match_mode: z16.enum(["or", "and"]).optional().describe("How to combine keywords: or (any match) or and (all must match)"),
@@ -7632,7 +7786,6 @@ var argsSchema18 = {
     "doc_section"
   ]).optional().describe("Filter results by code chunk type"),
   file_path: z16.string().optional().describe("Filter results to files whose path starts with this value (e.g., 'src/' for a directory)"),
-  version: schemas.version,
   limit: z16.coerce.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -7640,21 +7793,27 @@ var argsSchema18 = {
 function createSearchSymbolsTool(pkgseerService) {
   return {
     name: "search_symbols",
-    description: "Search a dependency's source code by text using the code navigation index — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns symbol-level results that can feed directly into symbol_callers, symbol_callees, or call_path. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source. " + "For free-form text search across multiple packages, use search(mode='code') instead.",
+    description: "Search a dependency's source code by text using the code navigation index — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns symbol-level results that can feed directly into symbol_callers, symbol_callees, or call_path. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source. " + "For free-form text search across multiple packages, use search(mode='code') instead.",
     schema: argsSchema18,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("search symbols", async () => {
-        const result = await pkgseerService.searchSymbols(toGraphQLRegistry(args.registry), args.package_name, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.searchSymbols(tv.registry, tv.packageName, {
           query: args.query,
           keywords: args.keywords,
           matchMode: toMatchMode(args.match_mode),
           kind: toSymbolKind(args.kind),
           filePath: args.file_path,
-          version: args.version,
+          version: tv.version,
           limit: args.limit,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7678,7 +7837,7 @@ function createSearchSymbolsTool(pkgseerService) {
 // src/tools/symbol-callees.ts
 import { z as z17 } from "zod";
 var argsSchema19 = {
-  symbol: schemas.symbolReference.describe("Symbol to find callees for. Provide either symbol_ref or registry + package_name + symbol_name."),
+  symbol: schemas.symbolReference.describe("Symbol to find callees for. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
   max_depth: z17.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
   limit: z17.coerce.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
   include_external: z17.boolean().optional().describe("Include calls to symbols in other indexed packages. " + "Default (false) shows only calls within the same package."),
@@ -7689,14 +7848,14 @@ var argsSchema19 = {
 function createSymbolCalleesTool(pkgseerService) {
   return {
     name: "symbol_callees",
-    description: "Trace what a function calls internally — " + "understand dependency behavior by following its execution path. " + "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_ref from find_symbol or list_symbols. See symbol_callers for the reverse.",
+    description: "Trace what a function calls internally — " + "understand dependency behavior by following its execution path. " + "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. " + "Supports package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callers for the reverse.",
     schema: argsSchema19,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callees", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
-        if (!symbolInput.symbolRef && (!symbolInput.symbolName || !symbolInput.registry || !symbolInput.packageName)) {
-          return errorResult("Provide either symbol_ref or symbol_name with registry and package_name to identify the symbol.");
+        if (!symbolInput.symbolRef && !(symbolInput.symbolName && symbolInput.registry && symbolInput.packageName) && !(symbolInput.symbolName && symbolInput.repoUrl && symbolInput.gitRef)) {
+          return errorResult("Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
         const result = await pkgseerService.symbolDependencies(symbolInput, {
           maxDepth: args.max_depth,
@@ -7717,7 +7876,7 @@ function createSymbolCalleesTool(pkgseerService) {
 // src/tools/symbol-callers.ts
 import { z as z18 } from "zod";
 var argsSchema20 = {
-  symbol: schemas.symbolReference.describe("Symbol to find callers for. Provide either symbol_ref or registry + package_name + symbol_name."),
+  symbol: schemas.symbolReference.describe("Symbol to find callers for. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
   same_package_only: z18.boolean().optional().describe("Only return callers from the same package. " + "Default (false) includes callers from other indexed packages."),
   max_depth: z18.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callers only, 2+ = transitive, max 5)"),
   limit: z18.coerce.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
@@ -7727,14 +7886,14 @@ var argsSchema20 = {
 function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
-    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse. " + "Use find_symbol(include_code=true) on any caller to read its source.",
+    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Supports package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse. " + "Use find_symbol(include_code=true) on any caller to read its source.",
     schema: argsSchema20,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callers", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
-        if (!symbolInput.symbolRef && (!symbolInput.symbolName || !symbolInput.registry || !symbolInput.packageName)) {
-          return errorResult("Provide either symbol_ref or symbol_name with registry and package_name to identify the symbol.");
+        if (!symbolInput.symbolRef && !(symbolInput.symbolName && symbolInput.registry && symbolInput.packageName) && !(symbolInput.symbolName && symbolInput.repoUrl && symbolInput.gitRef)) {
+          return errorResult("Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
         const result = await pkgseerService.symbolDependents(symbolInput, {
           samePackageOnly: args.same_package_only,
@@ -7811,8 +7970,7 @@ function createTriggerIndexingTool(pkgseerService) {
 // src/tools/version-diff.ts
 import { z as z20 } from "zod";
 var argsSchema22 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to compare versions for"),
+  target: schemas.codeTarget,
   from_version: z20.string().max(100).describe("Source version (git ref, e.g., 'v4.18.2')"),
   to_version: z20.string().max(100).describe("Target version (git ref, e.g., 'v5.0.0')"),
   include_private: z20.boolean().optional().describe("Include private/non-exported symbols in the diff"),
@@ -7831,16 +7989,22 @@ var argsSchema22 = {
 function createVersionDiffTool(pkgseerService) {
   return {
     name: "version_diff",
-    description: "Compare two versions of a dependency to understand what changed — " + "use when debugging issues after upgrades or planning migrations. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
+    description: "Compare two versions of a dependency to understand what changed — " + "use when debugging issues after upgrades or planning migrations. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "With repo scope, from_version and to_version are literal git refs (tags, branches, commits) — " + "the backend does not normalize them. Use target.git_ref=HEAD to identify the repository. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
     schema: argsSchema22,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("version diff", async () => {
-        const result = await pkgseerService.versionDiff(toGraphQLRegistry(args.registry), args.package_name, args.from_version, args.to_version, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.versionDiff(tv.registry, tv.packageName, args.from_version, args.to_version, {
           includePrivate: args.include_private,
           kind: toSymbolKind(args.kind),
           limit: args.limit,
-          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7861,9 +8025,17 @@ Use PkgSeer when:
 - You need to understand what changed between package versions
 
 Instead of guessing library behavior from training data, use find_symbol(include_code=true) to read actual source.
-Instead of cloning repos to search code, use search_symbols or grep_package_file.
+Instead of cloning repos to search code, use search_symbols or grep_file.
 Instead of manually tracing call chains on GitHub, use symbol_callers and symbol_callees.
 
+Dual addressing — code tools accept a target object with two modes:
+- Package scope: target: { registry: "npm", package_name: "express" } (optional version)
+  In monorepos, results are scoped to the package's subdirectory.
+- Repo scope: target: { repo_url: "https://github.com/expressjs/express", git_ref: "v4.18.2" }
+  Operates on the full repository, not filtered to a package subdirectory.
+
+Use package scope when you know the package name. Use repo scope when you have a repo URL (e.g., from package_summary) and need full-repo access or the repo isn't published as a package.
+
 Data availability — tools are grouped by what backend data they need:
 
 1. Registry metadata (available immediately, no indexing):
@@ -7874,32 +8046,31 @@ Data availability — tools are grouped by what backend data they need:
    list_package_docs, fetch_package_doc, search(mode='docs'), search_project_docs
    If results are empty, docs may not be crawled yet — use trigger_indexing first, then retry.
 
-3. Package code (requires code repo indexing):
+3. Code navigation (requires code repo indexing, dual addressing via target):
    find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path,
-   package_imports, version_diff, list_package_files, grep_package_file, search(mode='code')
+   list_imports, version_diff, list_files, grep_file, read_file, search(mode='code')
    These wait up to wait_timeout_ms (default 10s) for indexing. If indexing takes longer, you'll get a "being indexed" response — retry the same call. Most packages index within 10-30 seconds.
 
-4. Repository (full repo scope, not package-filtered):
-   fetch_code_context
-   Uses repo_url (get from package_summary) + git_ref (version tag) + file_path. Operates on the full repository, not filtered to a package subdirectory.
-
-Scope — package vs repository:
-Package code tools (group 3) are scoped to a single package. In monorepos, they return only data from that package's subdirectory. fetch_code_context (group 4) operates on the full repository. symbol_callers/symbol_callees can show cross-package results from other indexed packages.
+Symbol reference tools (symbol_callers, symbol_callees, call_path) accept a symbol object with either:
+- symbol_ref from a previous find_symbol/search_symbols result (preferred, fastest)
+- Package lookup: registry + package_name + symbol_name
+- Repo lookup: repo_url + git_ref + symbol_name
+symbol_callers/symbol_callees can show cross-package results from other indexed packages.
 
 Choosing a code search tool:
 - search_symbols: single package, symbol-level → results feed symbol_callers/callees/call_path
 - search(mode='code'): multi-package, full-text → code chunks with snippets
-- grep_package_file: single file, pattern match → when you know the file path
+- grep_file: single file, pattern match → when you know the file path
 
 Utility: trigger_indexing (pre-warm indexes), search_status (poll async search).
 
-Quick start: find_symbol(registry="npm", name="<function>", package_name="<pkg>", include_code=true) often answers the question in one call.
+Quick start: find_symbol(target={registry:"npm", package_name:"<pkg>"}, name="<function>", include_code=true) often answers the question in one call.
 
 Common workflows (pass symbolRef between tools for chaining):
-- Read source: find_symbol(name=<fn>, include_code=true)
+- Read source: find_symbol(target={registry, package_name}, name=<fn>, include_code=true)
 - Trace calls: find_symbol → symbol_callees(symbol={symbol_ref: <symbolRef>})
 - Find callers: find_symbol → symbol_callers(symbol={symbol_ref: <symbolRef>})
-- Read file: package_summary → fetch_code_context(repo_url, git_ref, file_path)
+- Read file: read_file(target={registry, package_name}, file_path=<path>) or read_file(target={repo_url, git_ref}, file_path=<path>)
 - Search code: search_symbols (single pkg, feeds callers/callees) or search(mode='code', packages=[...]) (multi-pkg)
 - Browse docs: list_package_docs → fetch_package_doc(page_id)`;
 var TOOL_FACTORIES = {
@@ -7912,7 +8083,7 @@ var TOOL_FACTORIES = {
   fetch_package_doc: ({ pkgseerService }) => createFetchPackageDocTool(pkgseerService),
   search: ({ pkgseerService }) => createSearchTool(pkgseerService),
   search_status: ({ pkgseerService }) => createSearchStatusTool(pkgseerService),
-  fetch_code_context: ({ pkgseerService }) => createFetchCodeContextTool(pkgseerService),
+  read_file: ({ pkgseerService }) => createReadFileTool(pkgseerService),
   search_project_docs: ({ pkgseerService, configService, defaultProjectDir }) => createSearchProjectDocsTool({
     pkgseerService,
     configService,
@@ -7923,11 +8094,11 @@ var TOOL_FACTORIES = {
   list_symbols: ({ pkgseerService }) => createListSymbolsTool(pkgseerService),
   symbol_callers: ({ pkgseerService }) => createSymbolCallersTool(pkgseerService),
   symbol_callees: ({ pkgseerService }) => createSymbolCalleesTool(pkgseerService),
-  package_imports: ({ pkgseerService }) => createPackageImportsTool(pkgseerService),
+  list_imports: ({ pkgseerService }) => createListImportsTool(pkgseerService),
   call_path: ({ pkgseerService }) => createCallPathTool(pkgseerService),
   trigger_indexing: ({ pkgseerService }) => createTriggerIndexingTool(pkgseerService),
-  list_package_files: ({ pkgseerService }) => createListPackageFilesTool(pkgseerService),
-  grep_package_file: ({ pkgseerService }) => createGrepPackageFileTool(pkgseerService),
+  list_files: ({ pkgseerService }) => createListFilesTool(pkgseerService),
+  grep_file: ({ pkgseerService }) => createGrepFileTool(pkgseerService),
   version_diff: ({ pkgseerService }) => createVersionDiffTool(pkgseerService)
 };
 var PUBLIC_READ_TOOLS = [
@@ -7940,24 +8111,24 @@ var PUBLIC_READ_TOOLS = [
   "fetch_package_doc",
   "search",
   "search_status",
-  "fetch_code_context",
+  "read_file",
   "find_symbol",
   "search_symbols",
   "list_symbols",
   "symbol_callers",
   "symbol_callees",
-  "package_imports",
+  "list_imports",
   "call_path",
   "trigger_indexing",
-  "list_package_files",
-  "grep_package_file",
+  "list_files",
+  "grep_file",
   "version_diff"
 ];
 var PROJECT_READ_TOOLS = ["search_project_docs"];
 var ALL_TOOLS = [...PUBLIC_READ_TOOLS, ...PROJECT_READ_TOOLS];
 function createMcpServer(deps) {
   const { pkgseerService, configService, config, fileSystemService } = deps;
-  const server = new McpServer({ name: "pkgseer", version: "0.1.0" }, { instructions: PKGSEER_INSTRUCTIONS });
+  const server = new McpServer({ name: "pkgseer", version: "0.5.0" }, { instructions: PKGSEER_INSTRUCTIONS });
   const defaultProjectDir = fileSystemService.getCwd();
   const enabledToolNames = config.enabled_tools ?? ALL_TOOLS;
   const toolsToRegister = enabledToolNames.filter((name) => ALL_TOOLS.includes(name));
@@ -8025,11 +8196,11 @@ When run via stdio (non-TTY), starts the MCP server.
 
 Available tools (22):
   Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
-  Browse files: list_package_files, grep_package_file, fetch_code_context
+  Browse files: list_files, grep_file, read_file
   Search: search, search_project_docs
   Docs: list_package_docs, fetch_package_doc
   Evaluate: package_summary, package_quality, package_vulnerabilities, compare_packages, package_dependencies, version_diff
-  Utility: trigger_indexing, search_status, package_imports`).action(async () => {
+  Utility: trigger_indexing, search_status, list_imports`).action(async () => {
     const deps = await createContainer();
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions(deps);

package/dist/index.js

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

package/dist/shared/{chunk-r3pnzy5b.js → chunk-kh5enjt9.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.4.11";
+var version = "0.5.0";
 
 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.11",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "dist",