@pkgseer/cli 0.4.1 → 0.4.3

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-d340pysc.js";
+} from "./shared/chunk-d3mfgdr9.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -685,16 +685,26 @@ var FindSymbolDocument = gql`
     totalMatches
     hasMore
     indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
   }
 }
     `;
 var SearchSymbolsDocument = gql`
-    query SearchSymbols($registry: Registry!, $packageName: String!, $query: String!, $kind: SymbolKind, $version: String, $limit: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query SearchSymbols($registry: Registry!, $packageName: String!, $query: String, $keywords: [String!], $matchMode: MatchMode, $kind: SymbolKind, $filePath: String, $version: String, $limit: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
   searchSymbols(
     registry: $registry
     packageName: $packageName
     query: $query
+    keywords: $keywords
+    matchMode: $matchMode
     kind: $kind
+    filePath: $filePath
     version: $version
     limit: $limit
     mode: $mode
@@ -708,11 +718,26 @@ var SearchSymbolsDocument = gql`
       endLine
       preview
       contentPreview
+      code
       language
+      symbolId
+      qualifiedPath
+      kind
+      arity
+      isPublic
+      containedSymbols
     }
     totalMatches
     hasMore
     indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
+    warning
   }
 }
     `;
@@ -750,7 +775,6 @@ var ListSymbolsDocument = gql`
       path
       language
     }
-    error
   }
 }
     `;
@@ -913,6 +937,126 @@ var SearchProjectDocsDocument = gql`
   }
 }
     `;
+var ListRepoFilesDocument = gql`
+    query ListRepoFiles($registry: Registry!, $packageName: String!, $version: String, $pathPrefix: String, $limit: Int, $waitTimeoutMs: Int) {
+  listRepoFiles(
+    registry: $registry
+    packageName: $packageName
+    version: $version
+    pathPrefix: $pathPrefix
+    limit: $limit
+    waitTimeoutMs: $waitTimeoutMs
+  ) {
+    files {
+      path
+      name
+      language
+      fileType
+      byteSize
+    }
+    total
+    hasMore
+    indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
+  }
+}
+    `;
+var GrepRepoFileDocument = gql`
+    query GrepRepoFile($registry: Registry!, $packageName: String!, $filePath: String!, $pattern: String!, $contextLines: Int, $maxMatches: Int, $version: String, $waitTimeoutMs: Int) {
+  grepRepoFile(
+    registry: $registry
+    packageName: $packageName
+    filePath: $filePath
+    pattern: $pattern
+    contextLines: $contextLines
+    maxMatches: $maxMatches
+    version: $version
+    waitTimeoutMs: $waitTimeoutMs
+  ) {
+    matches {
+      lineNumber
+      lineContent
+      contextBefore
+      contextAfter
+    }
+    totalMatches
+    hasMore
+    filePath
+    language
+    totalLines
+    indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
+  }
+}
+    `;
+var VersionDiffDocument = gql`
+    query VersionDiff($registry: Registry!, $packageName: String!, $fromVersion: String!, $toVersion: String!, $includePrivate: Boolean, $kind: SymbolKind, $limit: Int, $waitTimeoutMs: Int) {
+  versionDiff(
+    registry: $registry
+    packageName: $packageName
+    fromVersion: $fromVersion
+    toVersion: $toVersion
+    includePrivate: $includePrivate
+    kind: $kind
+    limit: $limit
+    waitTimeoutMs: $waitTimeoutMs
+  ) {
+    fromVersion
+    toVersion
+    summary {
+      added
+      removed
+      moved
+      modified
+      unchanged
+      breaking
+      behaviorChange
+    }
+    changes {
+      qualifiedPath
+      kind
+      arity
+      name
+      changeType
+      severity
+      changedFields
+      from {
+        contentHash
+        filePath
+        arity
+        startLine
+        endLine
+        isPublic
+        minArity
+        symbolId
+      }
+      to {
+        contentHash
+        filePath
+        arity
+        startLine
+        endLine
+        isPublic
+        minArity
+        symbolId
+      }
+    }
+    hasMore
+  }
+}
+    `;
 var defaultWrapper = (action, _operationName, _operationType, _variables) => action();
 var CliPackageInfoDocumentString = print(CliPackageInfoDocument);
 var CliPackageVulnsDocumentString = print(CliPackageVulnsDocument);
@@ -946,6 +1090,9 @@ var SymbolDependentsDocumentString = print(SymbolDependentsDocument);
 var PackageImportsDocumentString = print(PackageImportsDocument);
 var CallPathDocumentString = print(CallPathDocument);
 var SearchProjectDocsDocumentString = print(SearchProjectDocsDocument);
+var ListRepoFilesDocumentString = print(ListRepoFilesDocument);
+var GrepRepoFileDocumentString = print(GrepRepoFileDocument);
+var VersionDiffDocumentString = print(VersionDiffDocument);
 function getSdk(client, withWrapper = defaultWrapper) {
   return {
     CliPackageInfo(variables, requestHeaders) {
@@ -1043,6 +1190,15 @@ function getSdk(client, withWrapper = defaultWrapper) {
     },
     SearchProjectDocs(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(SearchProjectDocsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "SearchProjectDocs", "query", variables);
+    },
+    ListRepoFiles(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(ListRepoFilesDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "ListRepoFiles", "query", variables);
+    },
+    GrepRepoFile(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(GrepRepoFileDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "GrepRepoFile", "query", variables);
+    },
+    VersionDiff(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(VersionDiffDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "VersionDiff", "query", variables);
     }
   };
 }
@@ -1381,7 +1537,10 @@ var TOOL_NAMES = [
   "symbol_callees",
   "package_imports",
   "call_path",
-  "trigger_indexing"
+  "trigger_indexing",
+  "list_repo_files",
+  "grep_repo_file",
+  "version_diff"
 ];
 var ToolNameSchema = z.enum(TOOL_NAMES);
 var SharedConfigFields = {
@@ -1820,12 +1979,15 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
-  async searchSymbols(registry, packageName, query, options) {
+  async searchSymbols(registry, packageName, options) {
     const result = await this.client.SearchSymbols({
       registry,
       packageName,
-      query,
+      query: options?.query,
+      keywords: options?.keywords,
+      matchMode: options?.matchMode,
       kind: options?.kind,
+      filePath: options?.filePath,
       version: options?.version,
       limit: options?.limit,
       mode: options?.mode,
@@ -1894,6 +2056,43 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
+  async listRepoFiles(registry, packageName, options) {
+    const result = await this.client.ListRepoFiles({
+      registry,
+      packageName,
+      version: options?.version,
+      pathPrefix: options?.pathPrefix,
+      limit: options?.limit,
+      waitTimeoutMs: options?.waitTimeoutMs
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async grepRepoFile(registry, packageName, filePath, pattern, options) {
+    const result = await this.client.GrepRepoFile({
+      registry,
+      packageName,
+      filePath,
+      pattern,
+      contextLines: options?.contextLines,
+      maxMatches: options?.maxMatches,
+      version: options?.version,
+      waitTimeoutMs: options?.waitTimeoutMs
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async versionDiff(registry, packageName, fromVersion, toVersion, options) {
+    const result = await this.client.VersionDiff({
+      registry,
+      packageName,
+      fromVersion,
+      toVersion,
+      includePrivate: options?.includePrivate,
+      kind: options?.kind,
+      limit: options?.limit,
+      waitTimeoutMs: options?.waitTimeoutMs
+    });
+    return { data: result.data, errors: result.errors };
+  }
   async triggerIndexing(input) {
     const result = await this.client.TriggerIndexing({ input });
     return { data: result.data, errors: result.errors };
@@ -2263,8 +2462,11 @@ function handleErrors(errors, json) {
   const isNotFound = lower.includes("not found") || lower.includes("does not exist") || lower.includes("unknown");
   const isAuth = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("token") || lower.includes("authentication") || lower.includes("permission");
   const isRateLimit = lower.includes("rate limit") || lower.includes("too many requests");
+  const isBeingIndexed = lower.includes("being indexed") || lower.includes("retry with waittimeoutms");
   let hint = "";
-  if (isTimeout) {
+  if (isBeingIndexed) {
+    hint = " Hint: package is being indexed. Try again with a longer --wait value (e.g., --wait 30000).";
+  } else if (isTimeout) {
     hint = " Hint: lower the limit or narrow the scope, then retry.";
   } else if (isNotFound) {
     hint = " Hint: verify the name/registry and that the resource exists.";
@@ -2302,14 +2504,20 @@ function formatSeverity(severity) {
   return indicators[severity] || severity;
 }
 function extractGraphQLError(error) {
-  if (error && typeof error === "object" && "response" in error && error.response && typeof error.response === "object" && "errors" in error.response && Array.isArray(error.response.errors)) {
-    const errors = error.response.errors;
-    if (errors.length > 0) {
-      const messages = errors.map((e) => e.message).filter((m) => typeof m === "string");
+  if (error && typeof error === "object" && "response" in error && error.response && typeof error.response === "object" && "errors" in error.response) {
+    const respErrors = error.response.errors;
+    if (Array.isArray(respErrors)) {
+      const messages = respErrors.map((e) => e.message).filter((m) => typeof m === "string");
       if (messages.length > 0) {
         return messages.join("; ");
       }
     }
+    if (respErrors && typeof respErrors === "object" && !Array.isArray(respErrors) && "detail" in respErrors) {
+      const detail = respErrors.detail;
+      if (typeof detail === "string") {
+        return detail;
+      }
+    }
   }
   if (error && typeof error === "object" && "errors" in error && Array.isArray(error.errors)) {
     const errors = error.errors;
@@ -2358,6 +2566,10 @@ async function withCliErrorHandling(json, fn) {
     }
     const message = error instanceof Error ? error.message : "Unknown error";
     const lower = message.toLowerCase();
+    if (lower.includes("being indexed") || lower.includes("retry with waittimeoutms")) {
+      outputError(`${message}. Hint: package is being indexed. Try again with a longer --wait value (e.g., --wait 30000).`, json);
+      return;
+    }
     if (lower.includes("-32001") || lower.includes("timeout")) {
       outputError(`${message}. Hint: lower the limit or narrow the scope, then retry.`, json);
       return;
@@ -2599,6 +2811,145 @@ function registerCodeCallersCommand(program) {
     });
   });
 }
+// src/commands/code/diff.ts
+function formatDiffResult(data) {
+  const lines = [];
+  lines.push(`Version diff: ${data.fromVersion} → ${data.toVersion}`);
+  lines.push("");
+  const s = data.summary;
+  lines.push("Summary:");
+  lines.push(`  Added: ${s.added}  Removed: ${s.removed}  Modified: ${s.modified}  Moved: ${s.moved}`);
+  lines.push(`  Unchanged: ${s.unchanged}  Breaking: ${s.breaking}  Behavior changes: ${s.behaviorChange}`);
+  if (data.hasMore) {
+    lines.push("  (more changes available, increase --limit)");
+  }
+  lines.push("");
+  for (const change of data.changes) {
+    const severity = change.severity ? ` [${change.severity}]` : "";
+    const kindLabel = change.kind ? `[${change.kind}]` : "";
+    const name = change.qualifiedPath ?? change.name ?? "unknown";
+    lines.push(`${change.changeType}${severity} ${kindLabel} ${name}`.trim());
+    if (change.from?.filePath) {
+      const loc = change.from.startLine ? `${change.from.filePath}:${change.from.startLine}` : change.from.filePath;
+      lines.push(`  From: ${loc}`);
+    }
+    if (change.to?.filePath) {
+      const loc = change.to.startLine ? `${change.to.filePath}:${change.to.startLine}` : change.to.filePath;
+      lines.push(`  To:   ${loc}`);
+    }
+    if (change.changedFields?.length) {
+      lines.push(`  Changed: ${change.changedFields.join(", ")}`);
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`).trimEnd();
+}
+async function codeDiffAction(packageArg, fromVersion, toVersion, options, deps) {
+  const { pkgseerService } = deps;
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry);
+  const result = await pkgseerService.versionDiff(registry, parsed.name, fromVersion, toVersion, {
+    includePrivate: options.includePrivate,
+    kind: options.kind?.toUpperCase(),
+    limit: parseIntOption(options.limit, "--limit"),
+    waitTimeoutMs: parseWaitTimeout(options.wait)
+  });
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.versionDiff) {
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    output(result.data.versionDiff, true);
+  } else {
+    console.log(formatDiffResult(result.data.versionDiff));
+  }
+}
+var DIFF_DESCRIPTION = `Compare symbols between two package versions.
+
+Detects added, removed, moved, and modified symbols with severity classification.
+Returns summary counts and per-symbol changes with file locations.
+
+Examples:
+  pkgseer code diff npm:express v4.18.2 v5.0.0
+  pkgseer code diff npm:lodash 4.17.20 4.17.21 --include-private
+  pkgseer code diff pypi:requests 2.30.0 2.31.0 --kind function`;
+function registerCodeDiffCommand(program) {
+  program.command("diff <package> <from> <to>").summary("Compare symbols between versions").description(DIFF_DESCRIPTION).option("--include-private", "Include private/non-exported symbols").option("--kind <kind>", "Filter by symbol kind").option("--limit <n>", "Max changes to return (max 500)").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (packageArg, fromVersion, toVersion, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await codeDiffAction(packageArg, fromVersion, toVersion, options, deps);
+    });
+  });
+}
+// src/commands/code/files.ts
+function formatFilesResult(data) {
+  const lines = [];
+  lines.push(`${data.total} file(s)${data.hasMore ? " (more available)" : ""}`);
+  if (data.indexedVersion) {
+    lines.push(`Indexed version: ${data.indexedVersion}`);
+  }
+  lines.push("");
+  for (const file of data.files) {
+    const meta = [];
+    if (file.language)
+      meta.push(file.language);
+    if (file.fileType)
+      meta.push(file.fileType);
+    if (file.byteSize != null)
+      meta.push(`${file.byteSize}B`);
+    const suffix = meta.length > 0 ? `  (${meta.join(", ")})` : "";
+    lines.push(`${file.path}${suffix}`);
+  }
+  return lines.join(`
+`).trimEnd();
+}
+async function codeFilesAction(packageArg, options, deps) {
+  const { pkgseerService } = deps;
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry);
+  const result = await pkgseerService.listRepoFiles(registry, parsed.name, {
+    version: parsed.version,
+    pathPrefix: options.pathPrefix,
+    limit: parseIntOption(options.limit, "--limit"),
+    waitTimeoutMs: parseWaitTimeout(options.wait)
+  });
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.listRepoFiles) {
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
+    return;
+  }
+  const data = result.data.listRepoFiles;
+  if (options.json) {
+    output(data, true);
+  } else {
+    const formatted = formatFilesResult(data);
+    if (data.files.length === 0 && data.diagnostics?.hint) {
+      console.log(`${formatted}
+Note: ${data.diagnostics.hint}`);
+    } else {
+      console.log(formatted);
+    }
+  }
+}
+var FILES_DESCRIPTION = `List files in a package's indexed repository.
+
+Returns file paths, names, languages, types, and sizes.
+Use --path-prefix to filter by directory.
+
+Examples:
+  pkgseer code files npm:express
+  pkgseer code files npm:express --path-prefix src/
+  pkgseer code files pypi:requests --limit 50`;
+function registerCodeFilesCommand(program) {
+  program.command("files <package>").summary("List files in package repository").description(FILES_DESCRIPTION).option("--path-prefix <prefix>", "Filter to files under this path").option("--limit <n>", "Max files to return (max 1000)").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (packageArg, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await codeFilesAction(packageArg, options, deps);
+    });
+  });
+}
 // src/commands/code/find.ts
 function formatFindResult(data) {
   const lines = [];
@@ -2634,10 +2985,17 @@ async function codeFindAction(packageArg, nameArg, options, deps) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
+  const data = result.data.findSymbol;
   if (options.json) {
-    output(result.data.findSymbol, true);
+    output(data, true);
   } else {
-    console.log(formatFindResult(result.data.findSymbol));
+    const formatted = formatFindResult(data);
+    if (data.symbols.length === 0 && data.diagnostics?.hint) {
+      console.log(`${formatted}
+Note: ${data.diagnostics.hint}`);
+    } else {
+      console.log(formatted);
+    }
   }
 }
 var FIND_DESCRIPTION = `Find symbols (functions, classes, modules) by name.
@@ -2658,6 +3016,79 @@ function registerCodeFindCommand(program) {
     });
   });
 }
+// src/commands/code/grep.ts
+function formatGrepResult(data) {
+  const lines = [];
+  lines.push(`${data.totalMatches} match(es) in ${data.filePath ?? "unknown"}${data.hasMore ? " (more available)" : ""}`);
+  if (data.language)
+    lines.push(`Language: ${data.language}`);
+  if (data.totalLines != null)
+    lines.push(`Total lines: ${data.totalLines}`);
+  if (data.indexedVersion)
+    lines.push(`Indexed version: ${data.indexedVersion}`);
+  lines.push("");
+  for (const match of data.matches) {
+    if (match.contextBefore) {
+      for (const line of match.contextBefore) {
+        lines.push(`  ${line}`);
+      }
+    }
+    lines.push(`${match.lineNumber}: ${match.lineContent}`);
+    if (match.contextAfter) {
+      for (const line of match.contextAfter) {
+        lines.push(`  ${line}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`).trimEnd();
+}
+async function codeGrepAction(packageArg, filePath, pattern, options, deps) {
+  const { pkgseerService } = deps;
+  const parsed = parsePackageSpec(packageArg);
+  const registry = toGraphQLRegistry(parsed.registry);
+  const result = await pkgseerService.grepRepoFile(registry, parsed.name, filePath, pattern, {
+    contextLines: parseIntOption(options.contextLines, "--context-lines"),
+    maxMatches: parseIntOption(options.maxMatches, "--max-matches"),
+    version: parsed.version,
+    waitTimeoutMs: parseWaitTimeout(options.wait)
+  });
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.grepRepoFile) {
+    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
+    return;
+  }
+  const data = result.data.grepRepoFile;
+  if (options.json) {
+    output(data, true);
+  } else {
+    const formatted = formatGrepResult(data);
+    if (data.matches.length === 0 && data.diagnostics?.hint) {
+      console.log(`${formatted}
+Note: ${data.diagnostics.hint}`);
+    } else {
+      console.log(formatted);
+    }
+  }
+}
+var GREP_DESCRIPTION = `Search for a pattern within a file in a package's repository.
+
+Case-insensitive substring matching. Returns matching lines with context.
+Use 'code files' to discover available file paths.
+
+Examples:
+  pkgseer code grep npm:express "lib/router/index.js" "middleware"
+  pkgseer code grep pypi:requests "requests/api.py" "timeout" --context-lines 3
+  pkgseer code grep npm:lodash "lodash.js" "cloneDeep" --max-matches 5`;
+function registerCodeGrepCommand(program) {
+  program.command("grep <package> <file> <pattern>").summary("Search for pattern in a package file").description(GREP_DESCRIPTION).option("--context-lines <n>", "Lines of context around each match (max 10)").option("--max-matches <n>", "Maximum matches to return (max 200)").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (packageArg, filePath, pattern, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await codeGrepAction(packageArg, filePath, pattern, options, deps);
+    });
+  });
+}
 // src/commands/code/imports.ts
 function formatImport(entry) {
   const parts = [];
@@ -2748,9 +3179,6 @@ function formatListResult(data) {
   if (data.file) {
     lines.push(`File: ${data.file.path}${data.file.language ? ` (${data.file.language})` : ""}`);
   }
-  if (data.error) {
-    lines.push(`Warning: ${data.error}`);
-  }
   lines.push("");
   for (const symbol of data.symbols) {
     lines.push(formatSymbol(symbol));
@@ -2899,12 +3327,29 @@ function formatSearchResult(data) {
   return lines.join(`
 `).trimEnd();
 }
+function parseMatchMode(mode) {
+  if (!mode)
+    return;
+  const upper = mode.toUpperCase();
+  if (upper === "OR" || upper === "AND")
+    return upper;
+  throw new Error("--match-mode must be 'or' or 'and'");
+}
 async function codeSearchAction(packageArg, query, options, deps) {
   const { pkgseerService } = deps;
   const parsed = parsePackageSpec(packageArg);
   const registry = toGraphQLRegistry(parsed.registry);
-  const result = await pkgseerService.searchSymbols(registry, parsed.name, query, {
+  const keywords = options.keywords ? options.keywords.split(",").map((k) => k.trim()).filter(Boolean) : undefined;
+  if (!query && !keywords?.length) {
+    outputError("Either a query argument or --keywords must be provided", options.json ?? false);
+    return;
+  }
+  const result = await pkgseerService.searchSymbols(registry, parsed.name, {
+    query: query || undefined,
+    keywords,
+    matchMode: parseMatchMode(options.matchMode),
     kind: options.kind?.toUpperCase(),
+    filePath: options.filePath,
     version: parsed.version,
     limit: parseIntOption(options.limit, "--limit"),
     mode: parseNavigationMode(options.mode),
@@ -2915,23 +3360,36 @@ async function codeSearchAction(packageArg, query, options, deps) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
+  const data = result.data.searchSymbols;
   if (options.json) {
-    output(result.data.searchSymbols, true);
+    output(data, true);
   } else {
-    console.log(formatSearchResult(result.data.searchSymbols));
+    let formatted = formatSearchResult(data);
+    if (data.warning) {
+      formatted = `Warning: ${data.warning}
+
+${formatted}`;
+    }
+    if (data.results.length === 0 && data.diagnostics?.hint) {
+      formatted = `${formatted}
+Note: ${data.diagnostics.hint}`;
+    }
+    console.log(formatted);
   }
 }
 var SEARCH_DESCRIPTION = `Full-text search within package code.
 
 Searches across functions, classes, modules, and doc sections.
+Supports query string or keyword list with match mode.
 Returns matching code chunks with names, types, and previews.
 
 Examples:
   pkgseer code search npm:express "middleware"
   pkgseer code search pypi:requests "timeout" --kind function
-  pkgseer code search npm:lodash "deep clone" --limit 10`;
+  pkgseer code search npm:lodash --keywords "deep,clone" --match-mode and
+  pkgseer code search npm:express "router" --file-path src/`;
 function registerCodeSearchCommand(program) {
-  program.command("search <package> <query>").summary("Full-text search in package code").description(SEARCH_DESCRIPTION).option("--kind <kind>", "Filter by chunk type (function, class, module, etc.)").option("--limit <n>", "Max results (default: 25, max: 50)").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (packageArg, query, options) => {
+  program.command("search <package> [query]").summary("Full-text search in package code").description(SEARCH_DESCRIPTION).option("--kind <kind>", "Filter by chunk type (function, class, module, etc.)").option("--limit <n>", "Max results (default: 25, max: 50)").option("--keywords <words>", "Comma-separated keywords (alternative to query)").option("--match-mode <mode>", "How to combine keywords: or (any) or and (all)").option("--file-path <prefix>", "Filter to files matching path prefix").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (packageArg, query, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await codeSearchAction(packageArg, query, options, deps);
@@ -6006,6 +6464,14 @@ function toSymbolKind(kind) {
     return upper;
   return;
 }
+function toMatchMode(mode) {
+  if (!mode)
+    return;
+  const upper = mode.toUpperCase();
+  if (upper === "OR" || upper === "AND")
+    return upper;
+  return;
+}
 function toListScope(scope) {
   if (!scope)
     return;
@@ -6037,10 +6503,30 @@ function toSymbolReferenceInput(ref) {
 }
 function buildHintedMessage(operation, message) {
   const lower = message.toLowerCase();
+  const isBeingIndexed = lower.includes("being indexed") || lower.includes("retry with waittimeoutms");
+  if (isBeingIndexed) {
+    return `Failed to ${operation}: ${message}. ` + "Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).";
+  }
   const isTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
   if (isTimeout) {
     return `Failed to ${operation}: ${message}. ` + "Hint: try lowering the limit or narrowing the scope, then retry.";
   }
+  if (lower.includes("graphql error (code: 500)")) {
+    try {
+      const jsonMatch = message.match(/\{.*\}/s);
+      if (jsonMatch) {
+        const parsed = JSON.parse(jsonMatch[0]);
+        const detail = parsed.errors?.detail ?? parsed.detail;
+        if (typeof detail === "string") {
+          return `Failed to ${operation}: ${detail}`;
+        }
+      }
+    } catch {}
+    const detailMatch = message.match(/"detail"\s*:\s*"([^"]+)"/);
+    if (detailMatch?.[1]) {
+      return `Failed to ${operation}: ${detailMatch[1]}`;
+    }
+  }
   return `Failed to ${operation}: ${message}`;
 }
 function handleGraphQLErrors(errors) {
@@ -6049,10 +6535,14 @@ function handleGraphQLErrors(errors) {
     const combined = messages.join(", ");
     const lower = combined.toLowerCase();
     const hasNotFound = lower.includes("not found") || lower.includes("does not exist");
+    const hasBeingIndexed = lower.includes("being indexed") || lower.includes("retry with waittimeoutms");
     const hasTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
     if (hasNotFound) {
       return errorResult(`Error: ${combined}. Hint: verify the name/registry and that the resource exists.`);
     }
+    if (hasBeingIndexed) {
+      return errorResult(`Error: ${combined}. Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).`);
+    }
     if (hasTimeout) {
       return errorResult(`Error: ${combined}. Hint: try lowering the limit or narrowing the scope, then retry.`);
     }
@@ -6247,13 +6737,57 @@ function createFindSymbolTool(pkgseerService) {
         if (!result.data.findSymbol) {
           return notFoundError(args.package_name, args.registry);
         }
-        return textResult(JSON.stringify(result.data.findSymbol, null, 2));
+        const data = result.data.findSymbol;
+        if (data.symbols.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
 }
-// src/tools/list-package-docs.ts
+// src/tools/grep-repo-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.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
+  max_matches: z8.number().int().min(1).max(200).optional().describe("Maximum matches to return (max 200)"),
+  version: schemas.version,
+  wait_timeout_ms: schemas.waitTimeoutMs
+};
+function createGrepRepoFileTool(pkgseerService) {
+  return {
+    name: "grep_repo_file",
+    description: "Search for a pattern within a file in a package's repository. " + "Case-insensitive substring matching. Returns matching lines with context. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover available file paths.",
+    schema: argsSchema6,
+    handler: async (args, _extra) => {
+      return withErrorHandling("grep repo file", async () => {
+        const result = await pkgseerService.grepRepoFile(toGraphQLRegistry2(args.registry), args.package_name, args.file_path, args.pattern, {
+          contextLines: args.context_lines,
+          maxMatches: args.max_matches,
+          version: args.version,
+          waitTimeoutMs: args.wait_timeout_ms
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.grepRepoFile) {
+          return notFoundError(args.package_name, args.registry);
+        }
+        const data = result.data.grepRepoFile;
+        if (data.matches.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
+      });
+    }
+  };
+}
+// 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
@@ -6262,7 +6796,7 @@ 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_package_docs to find specific topics.",
-    schema: argsSchema6,
+    schema: argsSchema7,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("list package documentation", async () => {
         const result = await pkgseerService.listPackageDocs(toGraphQLRegistry2(registry), package_name, version2);
@@ -6277,17 +6811,55 @@ function createListPackageDocsTool(pkgseerService) {
     }
   };
 }
+// src/tools/list-repo-files.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.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
+  wait_timeout_ms: schemas.waitTimeoutMs
+};
+function createListRepoFilesTool(pkgseerService) {
+  return {
+    name: "list_repo_files",
+    description: "List files in a package's indexed repository. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Useful for exploring package structure before searching or reading code.",
+    schema: argsSchema8,
+    handler: async (args, _extra) => {
+      return withErrorHandling("list repo files", async () => {
+        const result = await pkgseerService.listRepoFiles(toGraphQLRegistry2(args.registry), args.package_name, {
+          version: args.version,
+          pathPrefix: args.path_prefix,
+          limit: args.limit,
+          waitTimeoutMs: args.wait_timeout_ms
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.listRepoFiles) {
+          return notFoundError(args.package_name, args.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(data, null, 2));
+      });
+    }
+  };
+}
 // src/tools/list-symbols.ts
-import { z as z8 } from "zod";
-var argsSchema7 = {
+import { z as z10 } from "zod";
+var argsSchema9 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to browse symbols for"),
-  scope: z8.enum(["exports", "file"]).describe("Browsing scope: 'exports' for public API, 'file' for all symbols in a specific file"),
-  file_path: z8.string().max(1000).optional().describe("File path within the repo (required when scope=file)"),
-  namespace: z8.string().max(500).optional().describe("Filter by namespace prefix (e.g., 'React' to see React.*)"),
-  public_only: z8.boolean().optional().describe("Only return public symbols"),
-  include_popularity: z8.boolean().optional().describe("Include callerCount for each symbol (slightly slower)"),
-  limit: z8.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
+  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.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
@@ -6296,7 +6868,7 @@ function createListSymbolsTool(pkgseerService) {
   return {
     name: "list_symbols",
     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,
+    schema: argsSchema9,
     handler: async (args, _extra) => {
       return withErrorHandling("list symbols", async () => {
         const scope = toListScope(args.scope);
@@ -6333,13 +6905,13 @@ function createListSymbolsTool(pkgseerService) {
   };
 }
 // src/tools/package-dependencies.ts
-import { z as z9 } from "zod";
-var argsSchema8 = {
+import { z as z11 } from "zod";
+var argsSchema10 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to retrieve dependencies for"),
   version: schemas.version,
-  include_transitive: z9.boolean().optional().describe("Whether to include transitive dependency DAG"),
-  max_depth: z9.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
+  include_transitive: z11.boolean().optional().describe("Whether to include transitive dependency DAG"),
+  max_depth: z11.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
 };
 function decodeDag(rawDag) {
   if (!rawDag || typeof rawDag !== "object")
@@ -6417,7 +6989,7 @@ function createPackageDependenciesTool(pkgseerService) {
   return {
     name: "package_dependencies",
     description: "Analyze package dependencies. By default returns direct dependencies only. " + "Set include_transitive=true to get the full dependency tree (use max_depth to limit large trees). " + "Returns: dependency names, version constraints, and for transitive deps, a graph with depth levels. " + "Use this to understand complexity before adding a package, or to find nested dependencies.",
-    schema: argsSchema8,
+    schema: argsSchema10,
     handler: async ({ registry, package_name, version: version2, include_transitive, max_depth }, _extra) => {
       return withErrorHandling("fetch package dependencies", async () => {
         const result = await pkgseerService.getPackageDependencies(toGraphQLRegistry2(registry), package_name, version2, include_transitive, max_depth);
@@ -6455,13 +7027,13 @@ function createPackageDependenciesTool(pkgseerService) {
   };
 }
 // src/tools/package-imports.ts
-import { z as z10 } from "zod";
-var argsSchema9 = {
+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: z10.string().max(1000).optional().describe("Filter to a specific file path"),
-  resolved_only: z10.boolean().optional().describe("Only return imports resolved to a known package"),
-  limit: z10.number().int().min(1).max(500).optional().describe("Max imports to return"),
+  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.number().int().min(1).max(500).optional().describe("Max imports to return"),
   version: schemas.version,
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -6470,7 +7042,7 @@ function createPackageImportsTool(pkgseerService) {
   return {
     name: "package_imports",
     description: "Get import statements in a package. " + "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: argsSchema9,
+    schema: argsSchema11,
     handler: async (args, _extra) => {
       return withErrorHandling("fetch package imports", async () => {
         const result = await pkgseerService.packageImports(toGraphQLRegistry2(args.registry), args.package_name, {
@@ -6493,7 +7065,7 @@ function createPackageImportsTool(pkgseerService) {
   };
 }
 // src/tools/package-quality.ts
-var argsSchema10 = {
+var argsSchema12 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to analyze"),
   version: schemas.version
@@ -6502,7 +7074,7 @@ function createPackageQualityTool(pkgseerService) {
   return {
     name: "package_quality",
     description: "Evaluate package maintenance health and code quality. 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: argsSchema10,
+    schema: argsSchema12,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package quality", async () => {
         const result = await pkgseerService.getPackageQuality(toGraphQLRegistry2(registry), package_name, version2);
@@ -6518,7 +7090,7 @@ function createPackageQualityTool(pkgseerService) {
   };
 }
 // src/tools/package-summary.ts
-var argsSchema11 = {
+var argsSchema13 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to retrieve summary for")
 };
@@ -6526,7 +7098,7 @@ function createPackageSummaryTool(pkgseerService) {
   return {
     name: "package_summary",
     description: "Get a comprehensive overview of a package. 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).",
-    schema: argsSchema11,
+    schema: argsSchema13,
     handler: async ({ registry, package_name }, _extra) => {
       return withErrorHandling("fetch package summary", async () => {
         const result = await pkgseerService.getPackageSummary(toGraphQLRegistry2(registry), package_name);
@@ -6542,7 +7114,7 @@ function createPackageSummaryTool(pkgseerService) {
   };
 }
 // src/tools/package-vulnerabilities.ts
-var argsSchema12 = {
+var argsSchema14 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to inspect for vulnerabilities"),
   version: schemas.version
@@ -6551,7 +7123,7 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
   return {
     name: "package_vulnerabilities",
     description: "Check security vulnerabilities for a package. 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: argsSchema12,
+    schema: argsSchema14,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package vulnerabilities", async () => {
         const result = await pkgseerService.getPackageVulnerabilities(toGraphQLRegistry2(registry), package_name, version2);
@@ -6567,19 +7139,19 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
   };
 }
 // src/tools/search.ts
-import { z as z11 } from "zod";
-var packageInputSchema2 = z11.object({
+import { z as z13 } from "zod";
+var packageInputSchema2 = z13.object({
   registry: schemas.registry,
-  name: z11.string().min(1).describe("Package name"),
-  version: z11.string().optional().describe("Specific version (defaults to latest)")
+  name: z13.string().min(1).describe("Package name"),
+  version: z13.string().optional().describe("Specific version (defaults to latest)")
 });
 var DEFAULT_AGENT_WAIT_TIMEOUT_MS = 1e4;
-var argsSchema13 = {
-  packages: z11.array(packageInputSchema2).min(1).max(20).describe("Packages to search (1-20). Each package needs registry and name."),
-  query: z11.string().min(1).describe("Search query - natural language or keywords"),
-  mode: z11.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
-  limit: z11.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
-  waitTimeoutMs: z11.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
+var argsSchema15 = {
+  packages: z13.array(packageInputSchema2).min(1).max(20).describe("Packages to search (1-20). Each package needs registry and name."),
+  query: z13.string().min(1).describe("Search query - natural language or keywords"),
+  mode: z13.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
+  limit: z13.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
+  waitTimeoutMs: z13.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
 };
 function toSearchMode2(mode) {
   if (!mode)
@@ -6618,7 +7190,7 @@ function createSearchTool(pkgseerService) {
   return {
     name: "search",
     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,
+    schema: argsSchema15,
     handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
       return withErrorHandling("search packages", async () => {
         const normalizedQuery = query.trim();
@@ -6670,21 +7242,21 @@ function createSearchTool(pkgseerService) {
   };
 }
 // src/tools/search-project-docs.ts
-import { z as z12 } from "zod";
-var argsSchema14 = {
-  project_directory: z12.string().optional().describe("Directory to search for pkgseer.yml configuration. " + "Use this to specify which project's context to use when the MCP server " + "is installed at user level. Defaults to MCP server's working directory."),
-  project: z12.string().optional().describe("Project name to search. Overrides value from pkgseer.yml if provided."),
-  terms: z12.array(z12.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
-  match_mode: z12.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
-  include_snippets: z12.boolean().optional().describe("Include content excerpts around matches"),
-  limit: z12.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
+import { z as z14 } from "zod";
+var argsSchema16 = {
+  project_directory: z14.string().optional().describe("Directory to search for pkgseer.yml configuration. " + "Use this to specify which project's context to use when the MCP server " + "is installed at user level. Defaults to MCP server's working directory."),
+  project: z14.string().optional().describe("Project name to search. Overrides value from pkgseer.yml if provided."),
+  terms: z14.array(z14.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
+  match_mode: z14.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
+  include_snippets: z14.boolean().optional().describe("Include content excerpts around matches"),
+  limit: z14.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
 };
 function createSearchProjectDocsTool(deps) {
   const { pkgseerService, configService, defaultProjectDir } = deps;
   return {
     name: "search_project_docs",
     description: "Searches documentation across all dependencies in a PkgSeer project using search terms and match modes (any/all). Returns ranked results from multiple packages. Use project_directory to specify which project's context to use, or project to search a specific project directly.",
-    schema: argsSchema14,
+    schema: argsSchema16,
     handler: async ({
       project_directory,
       project,
@@ -6730,15 +7302,15 @@ function createSearchProjectDocsTool(deps) {
   };
 }
 // src/tools/search-status.ts
-import { z as z13 } from "zod";
-var argsSchema15 = {
-  searchRef: z13.string().min(1).describe("Search reference from a previous incomplete search")
+import { z as z15 } from "zod";
+var argsSchema17 = {
+  searchRef: z15.string().min(1).describe("Search reference from a previous incomplete search")
 };
 function createSearchStatusTool(pkgseerService) {
   return {
     name: "search_status",
     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,
+    schema: argsSchema17,
     handler: async ({ searchRef }, _extra) => {
       return withErrorHandling("check search status", async () => {
         const progressResult = await pkgseerService.getSearchProgress(searchRef);
@@ -6779,12 +7351,14 @@ function createSearchStatusTool(pkgseerService) {
   };
 }
 // src/tools/search-symbols.ts
-import { z as z14 } from "zod";
-var argsSchema16 = {
+import { z as z16 } from "zod";
+var argsSchema18 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to search within"),
-  query: z14.string().max(500).describe("Search query for full-text code search (max 500 chars)"),
-  kind: z14.enum([
+  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)"),
+  kind: z16.enum([
     "function",
     "method",
     "class",
@@ -6793,20 +7367,25 @@ var argsSchema16 = {
     "type",
     "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: z14.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
+  limit: z16.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 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. " + "Follow-up: use find_symbol(name=<result.name>, include_code=true) to get full source.",
-    schema: argsSchema16,
+    description: "Full-text search within package code. " + "Searches across functions, classes, modules, and doc sections. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "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: argsSchema18,
     handler: async (args, _extra) => {
       return withErrorHandling("search symbols", async () => {
-        const result = await pkgseerService.searchSymbols(toGraphQLRegistry2(args.registry), args.package_name, args.query, {
+        const result = await pkgseerService.searchSymbols(toGraphQLRegistry2(args.registry), args.package_name, {
+          query: args.query,
+          keywords: args.keywords,
+          matchMode: toMatchMode(args.match_mode),
           kind: toSymbolKind(args.kind),
+          filePath: args.file_path,
           version: args.version,
           limit: args.limit,
           mode: toNavigationMode(args.mode),
@@ -6818,19 +7397,30 @@ function createSearchSymbolsTool(pkgseerService) {
         if (!result.data.searchSymbols) {
           return notFoundError(args.package_name, args.registry);
         }
-        return textResult(JSON.stringify(result.data.searchSymbols, null, 2));
+        const data = result.data.searchSymbols;
+        const extra = {};
+        if (data.results.length === 0 && data.diagnostics?.hint) {
+          extra._hint = data.diagnostics.hint;
+        }
+        if (data.warning) {
+          extra._warning = data.warning;
+        }
+        if (Object.keys(extra).length > 0) {
+          return textResult(JSON.stringify({ ...data, ...extra }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
 }
 // src/tools/symbol-callees.ts
-import { z as z15 } from "zod";
-var argsSchema17 = {
+import { z as z17 } from "zod";
+var argsSchema19 = {
   symbol: schemas.symbolReference.describe("Symbol to find callees for. Provide either symbol_id or registry + package_name + symbol_name."),
-  max_depth: z15.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
-  limit: z15.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
-  include_external: z15.boolean().optional().describe("Include calls to symbols in other packages"),
-  include_builtins: z15.boolean().optional().describe("Include calls to built-in/standard library functions (console, Math, etc.)"),
+  max_depth: z17.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
+  limit: z17.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 packages"),
+  include_builtins: z17.boolean().optional().describe("Include calls to built-in/standard library functions (console, Math, etc.)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
@@ -6838,7 +7428,7 @@ 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. " + "Get symbol_id from find_symbol or list_symbols results. See symbol_callers for the reverse.",
-    schema: argsSchema17,
+    schema: argsSchema19,
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callees", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
@@ -6865,11 +7455,11 @@ function createSymbolCalleesTool(pkgseerService) {
   };
 }
 // src/tools/symbol-callers.ts
-import { z as z16 } from "zod";
-var argsSchema18 = {
+import { z as z18 } from "zod";
+var argsSchema20 = {
   symbol: schemas.symbolReference.describe("Symbol to find callers for. Provide either symbol_id or registry + package_name + symbol_name."),
-  same_package_only: z16.boolean().optional().describe("Only return callers from the same package"),
-  limit: z16.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
+  same_package_only: z18.boolean().optional().describe("Only return callers from the same package"),
+  limit: z18.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
@@ -6877,7 +7467,7 @@ function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
     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,
+    schema: argsSchema20,
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callers", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
@@ -6902,26 +7492,26 @@ function createSymbolCallersTool(pkgseerService) {
   };
 }
 // src/tools/trigger-indexing.ts
-import { z as z17 } from "zod";
-var packageInputSchema3 = z17.object({
+import { z as z19 } from "zod";
+var packageInputSchema3 = z19.object({
   registry: schemas.registry,
-  name: z17.string().max(255).describe("Package name"),
-  version: z17.string().max(100).optional().describe("Specific version to index")
+  name: z19.string().max(255).describe("Package name"),
+  version: z19.string().max(100).optional().describe("Specific version to index")
 });
-var repositoryInputSchema = z17.object({
-  url: z17.string().max(2000).describe("GitHub repository URL"),
-  ref: z17.string().max(200).optional().describe("Git ref to index (tag, branch, commit). Defaults to HEAD"),
-  discover_packages: z17.boolean().optional().describe("If true, discover packages published from this repo and trigger their metadata fetch")
+var repositoryInputSchema = z19.object({
+  url: z19.string().max(2000).describe("GitHub repository URL"),
+  ref: z19.string().max(200).optional().describe("Git ref to index (tag, branch, commit). Defaults to HEAD"),
+  discover_packages: z19.boolean().optional().describe("If true, discover packages published from this repo and trigger their metadata fetch")
 });
-var argsSchema19 = {
-  packages: z17.array(packageInputSchema3).max(100).optional().describe("Package versions to index (max 100)"),
-  repositories: z17.array(repositoryInputSchema).max(50).optional().describe("Repository URLs to index (max 50)")
+var argsSchema21 = {
+  packages: z19.array(packageInputSchema3).max(100).optional().describe("Package versions to index (max 100)"),
+  repositories: z19.array(repositoryInputSchema).max(50).optional().describe("Repository URLs to index (max 50)")
 };
 function createTriggerIndexingTool(pkgseerService) {
   return {
     name: "trigger_indexing",
     description: "Pre-warm PkgSeer indexes by triggering indexing for packages and/or repositories. " + "Fire-and-forget: triggers jobs and returns immediately with accepted/skipped counts. " + "Use before search requests to ensure packages are indexed. " + "Rate limited to 10 requests per minute.",
-    schema: argsSchema19,
+    schema: argsSchema21,
     handler: async (args, _extra) => {
       return withErrorHandling("trigger indexing", async () => {
         const packages = args.packages?.map((p) => ({
@@ -6957,6 +7547,50 @@ 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"),
+  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"),
+  kind: z20.enum([
+    "function",
+    "method",
+    "class",
+    "module",
+    "interface",
+    "type",
+    "doc_section"
+  ]).optional().describe("Filter by symbol kind"),
+  limit: z20.number().int().min(1).max(500).optional().describe("Max changes to return (max 500). Summary always reflects full counts."),
+  wait_timeout_ms: schemas.waitTimeoutMs
+};
+function createVersionDiffTool(pkgseerService) {
+  return {
+    name: "version_diff",
+    description: "Compare symbols between two package versions. " + "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,
+    handler: async (args, _extra) => {
+      return withErrorHandling("version diff", async () => {
+        const result = await pkgseerService.versionDiff(toGraphQLRegistry2(args.registry), args.package_name, args.from_version, args.to_version, {
+          includePrivate: args.include_private,
+          kind: toSymbolKind(args.kind),
+          limit: args.limit,
+          waitTimeoutMs: args.wait_timeout_ms
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.versionDiff) {
+          return notFoundError(args.package_name, args.registry);
+        }
+        return textResult(JSON.stringify(result.data.versionDiff, null, 2));
+      });
+    }
+  };
+}
 // src/commands/mcp.ts
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
@@ -6981,7 +7615,10 @@ var TOOL_FACTORIES = {
   symbol_callees: ({ pkgseerService }) => createSymbolCalleesTool(pkgseerService),
   package_imports: ({ pkgseerService }) => createPackageImportsTool(pkgseerService),
   call_path: ({ pkgseerService }) => createCallPathTool(pkgseerService),
-  trigger_indexing: ({ pkgseerService }) => createTriggerIndexingTool(pkgseerService)
+  trigger_indexing: ({ pkgseerService }) => createTriggerIndexingTool(pkgseerService),
+  list_repo_files: ({ pkgseerService }) => createListRepoFilesTool(pkgseerService),
+  grep_repo_file: ({ pkgseerService }) => createGrepRepoFileTool(pkgseerService),
+  version_diff: ({ pkgseerService }) => createVersionDiffTool(pkgseerService)
 };
 var PUBLIC_READ_TOOLS = [
   "package_summary",
@@ -7001,7 +7638,10 @@ var PUBLIC_READ_TOOLS = [
   "symbol_callees",
   "package_imports",
   "call_path",
-  "trigger_indexing"
+  "trigger_indexing",
+  "list_repo_files",
+  "grep_repo_file",
+  "version_diff"
 ];
 var PROJECT_READ_TOOLS = ["search_project_docs"];
 var ALL_TOOLS = [...PUBLIC_READ_TOOLS, ...PROJECT_READ_TOOLS];
@@ -8003,8 +8643,11 @@ Documentation commands:
 
 Code navigation commands:
   pkgseer code find <pkg> [name]  Find symbols by name
-  pkgseer code search <pkg> <q>   Search in package code
+  pkgseer code search <pkg> [q]   Search in package code
   pkgseer code list <package>     Browse package symbols
+  pkgseer code files <package>    List repository files
+  pkgseer code grep <pkg> <f> <p> Search pattern in a file
+  pkgseer code diff <pkg> <v> <v> Compare versions
   pkgseer code callers <symbol>   Find what calls a symbol
   pkgseer code callees <symbol>   Find what a symbol calls
   pkgseer code imports <package>  List package imports
@@ -8038,6 +8681,9 @@ var code = program.command("code").description("Code navigation commands");
 registerCodeFindCommand(code);
 registerCodeSearchCommand(code);
 registerCodeListCommand(code);
+registerCodeFilesCommand(code);
+registerCodeGrepCommand(code);
+registerCodeDiffCommand(code);
 registerCodeCallersCommand(code);
 registerCodeCalleesCommand(code);
 registerCodeImportsCommand(code);