@pkgseer/cli 0.3.0 → 0.3.1

package/README.md

@@ -100,10 +100,16 @@ pkgseer search "auth" -P lodash --mode docs   # Docs only
 # Wait options (for packages that need indexing)
 pkgseer search "api" -P new-package --wait 60000  # Wait up to 60s
 pkgseer search "api" -P new-package --no-wait     # Return immediately
+
+# Resume long-running searches
+pkgseer search "api" -P large-package --no-poll   # Disable polling, get searchRef
+pkgseer search --resume <searchRef>               # Check status / get results
 ```
 
 If packages haven't been indexed yet, the search will wait up to 30 seconds by default. Use `--wait <ms>` to customize or `--no-wait` to return immediately with progress info.
 
+For long-running searches, use `--no-poll` to get a searchRef and later resume with `--resume <ref>`.
+
 ### Package Commands
 
 ```bash

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-9yar14cw.js";
+} from "./shared/chunk-55x4vqp2.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -261,6 +261,52 @@ var CombinedSearchDocument = gql`
   }
 }
     `;
+var SearchProgressDocument = gql`
+    query SearchProgress($searchRef: String!) {
+  searchProgress(searchRef: $searchRef) {
+    searchRef
+    status
+    packagesTotal
+    packagesReady
+    elapsedMs
+  }
+}
+    `;
+var SearchResultsDocument = gql`
+    query SearchResults($searchRef: String!) {
+  searchResults(searchRef: $searchRef) {
+    query
+    mode
+    totalResults
+    entries {
+      id
+      type
+      title
+      subtitle
+      packageName
+      registry
+      score
+      snippet
+      filePath
+      startLine
+      endLine
+      language
+      chunkType
+      repoUrl
+      gitRef
+      pageId
+      sourceUrl
+    }
+    indexingStatus {
+      registry
+      packageName
+      version
+      codeStatus
+      docsStatus
+    }
+  }
+}
+    `;
 var FetchCodeContextDocument = gql`
     query FetchCodeContext($repoUrl: String!, $gitRef: String!, $filePath: String!, $startLine: Int, $endLine: Int) {
   fetchCodeContext(
@@ -629,6 +675,8 @@ var CliDocsSearchDocumentString = print(CliDocsSearchDocument);
 var CliProjectDocsSearchDocumentString = print(CliProjectDocsSearchDocument);
 var CliDocsListDocumentString = print(CliDocsListDocument);
 var CombinedSearchDocumentString = print(CombinedSearchDocument);
+var SearchProgressDocumentString = print(SearchProgressDocument);
+var SearchResultsDocumentString = print(SearchResultsDocument);
 var FetchCodeContextDocumentString = print(FetchCodeContextDocument);
 var CliDocsGetDocumentString = print(CliDocsGetDocument);
 var CreateProjectDocumentString = print(CreateProjectDocument);
@@ -671,6 +719,12 @@ function getSdk(client, withWrapper = defaultWrapper) {
     CombinedSearch(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(CombinedSearchDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CombinedSearch", "query", variables);
     },
+    SearchProgress(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(SearchProgressDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "SearchProgress", "query", variables);
+    },
+    SearchResults(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(SearchResultsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "SearchResults", "query", variables);
+    },
     FetchCodeContext(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(FetchCodeContextDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "FetchCodeContext", "query", variables);
     },
@@ -1037,6 +1091,7 @@ var TOOL_NAMES = [
   "list_package_docs",
   "fetch_package_doc",
   "search",
+  "search_status",
   "fetch_code_context",
   "search_project_docs"
 ];
@@ -1440,6 +1495,14 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
+  async getSearchProgress(searchRef) {
+    const result = await this.client.SearchProgress({ searchRef });
+    return { data: result.data, errors: result.errors };
+  }
+  async getSearchResults(searchRef) {
+    const result = await this.client.SearchResults({ searchRef });
+    return { data: result.data, errors: result.errors };
+  }
   async fetchCodeContext(repoUrl, gitRef, filePath, options) {
     const result = await this.client.FetchCodeContext({
       repoUrl,
@@ -2358,8 +2421,59 @@ function registerDocsListCommand(program) {
     });
   });
 }
+// src/lib/polling.ts
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function pollUntilDone(config) {
+  const {
+    fetch: fetch2,
+    isDone,
+    onUpdate,
+    intervalMs,
+    maxWaitMs,
+    sleep = defaultSleep,
+    now = Date.now
+  } = config;
+  const startTime = now();
+  let lastData;
+  while (true) {
+    try {
+      const data = await fetch2();
+      lastData = data;
+      if (onUpdate) {
+        onUpdate(data);
+      }
+      if (isDone(data)) {
+        return { success: true, data };
+      }
+      const elapsed = now() - startTime;
+      if (elapsed >= maxWaitMs) {
+        return {
+          success: false,
+          error: `Client polling timeout after ${elapsed}ms`,
+          lastData
+        };
+      }
+      await sleep(intervalMs);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: `Poll failed: ${message}`,
+        lastData
+      };
+    }
+  }
+}
+
 // src/commands/search.ts
 var DEFAULT_WAIT_TIMEOUT_MS = 30000;
+var DEFAULT_POLL_INTERVAL_MS = 2000;
+var DEFAULT_MAX_POLL_TIME_MS = 120000;
+var TERMINAL_STATUSES = [
+  "COMPLETED",
+  "TIMEOUT",
+  "FAILED"
+];
 var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -2753,8 +2867,122 @@ function getWaitTimeoutMs(options) {
   }
   return DEFAULT_WAIT_TIMEOUT_MS;
 }
+function shouldPoll(options) {
+  if (options.noPoll) {
+    return false;
+  }
+  return process.stdout.isTTY ?? false;
+}
+async function pollSearchProgress(searchRef, pkgseerService, useColors) {
+  const result = await pollUntilDone({
+    fetch: async () => {
+      const res = await pkgseerService.getSearchProgress(searchRef);
+      return res.data.searchProgress ?? null;
+    },
+    isDone: (progress) => {
+      if (!progress)
+        return true;
+      return TERMINAL_STATUSES.includes(progress.status);
+    },
+    onUpdate: (progress) => {
+      if (progress) {
+        const statusText = progress.status?.toLowerCase() ?? "unknown";
+        const ready = progress.packagesReady ?? 0;
+        const total = progress.packagesTotal ?? 0;
+        const elapsed = ((progress.elapsedMs ?? 0) / 1000).toFixed(1);
+        console.log(`  ${statusText} (${ready}/${total} ready) - ${elapsed}s`);
+      }
+    },
+    intervalMs: DEFAULT_POLL_INTERVAL_MS,
+    maxWaitMs: DEFAULT_MAX_POLL_TIME_MS
+  });
+  if (!result.success) {
+    return { success: false, error: result.error };
+  }
+  if (!result.data) {
+    return { success: false, error: "Search session not found" };
+  }
+  return { success: true, status: result.data.status };
+}
+async function handleResume(searchRef, pkgseerService, options, useColors) {
+  const progressResult = await pkgseerService.getSearchProgress(searchRef);
+  if (progressResult.errors?.length) {
+    handleErrors(progressResult.errors, options.json ?? false);
+    return true;
+  }
+  const progress = progressResult.data.searchProgress;
+  if (!progress) {
+    outputError("Search session not found. It may have expired (sessions last 1 hour).", options.json ?? false);
+    return true;
+  }
+  if (progress.status === "COMPLETED") {
+    const resultsResponse = await pkgseerService.getSearchResults(searchRef);
+    if (resultsResponse.errors?.length) {
+      handleErrors(resultsResponse.errors, options.json ?? false);
+      return true;
+    }
+    const searchResults = resultsResponse.data.searchResults;
+    if (!searchResults) {
+      outputError("Search completed but no results returned.", options.json ?? false);
+      return true;
+    }
+    outputResults(searchResults, options, useColors);
+    return true;
+  }
+  if (progress.status === "FAILED") {
+    outputError(`Search failed. Ref: ${searchRef}`, options.json ?? false);
+    return true;
+  }
+  if (progress.status === "TIMEOUT") {
+    outputError(`Search timed out. Try again or use --wait with a higher value.
+Ref: ${searchRef}`, options.json ?? false);
+    return true;
+  }
+  if (options.json) {
+    output({
+      completed: false,
+      searchRef,
+      progress: {
+        status: progress.status,
+        packagesTotal: progress.packagesTotal,
+        packagesReady: progress.packagesReady,
+        elapsedMs: progress.elapsedMs
+      },
+      message: "Search is still in progress."
+    }, true);
+    return true;
+  }
+  console.log("Checking search status...");
+  console.log(`Status: ${progress.status?.toLowerCase() ?? "unknown"}`);
+  if (shouldPoll(options)) {
+    console.log("Polling for completion...");
+    const pollResult = await pollSearchProgress(searchRef, pkgseerService, useColors);
+    if (!pollResult.success) {
+      outputError(pollResult.error, false);
+      console.log(`Resume with: pkgseer search --resume ${searchRef}`);
+      return true;
+    }
+    if (pollResult.status === "COMPLETED") {
+      const resultsResponse = await pkgseerService.getSearchResults(searchRef);
+      if (resultsResponse.data.searchResults) {
+        outputResults(resultsResponse.data.searchResults, options, useColors);
+      }
+    } else {
+      console.log(`Search ended with status: ${pollResult.status.toLowerCase()}`);
+    }
+  } else {
+    console.log(`
+Resume with: pkgseer search --resume ${searchRef}`);
+  }
+  return true;
+}
 async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
   const { pkgseerService } = deps;
+  const useColors = shouldUseColors(options.noColor);
+  if (options.resume?.trim()) {
+    await handleResume(options.resume.trim(), pkgseerService, options, useColors);
+    return;
+  }
   const query = Array.isArray(queryArg) ? queryArg.join(" ") : queryArg ?? "";
   if (!query.trim()) {
     outputError("Search query required. Provide query as argument.", options.json ?? false);
@@ -2771,7 +2999,6 @@ async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
   const packages = parsePackageList(options.packages);
   const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
   const mode = options.mode ? toSearchMode(options.mode) : defaultMode;
-  const useColors = shouldUseColors(options.noColor);
   const waitTimeoutMs = getWaitTimeoutMs(options);
   const result = await pkgseerService.combinedSearch(packages, query, {
     mode,
@@ -2785,16 +3012,40 @@ async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
     return;
   }
   if (!asyncResult.completed) {
+    const searchRef = asyncResult.searchRef;
     if (options.json) {
       output({
         completed: false,
-        searchRef: asyncResult.searchRef,
+        searchRef,
         progress: asyncResult.progress,
         message: "Search is still indexing. Retry for complete results."
       }, true);
-    } else {
-      console.log(formatSearchProgress(asyncResult.progress, asyncResult.searchRef, useColors));
+      return;
     }
+    if (shouldPoll(options) && searchRef) {
+      console.log("Search in progress, polling for completion...");
+      const pollResult = await pollSearchProgress(searchRef, pkgseerService, useColors);
+      if (pollResult.success && pollResult.status === "COMPLETED") {
+        const resultsResponse = await pkgseerService.getSearchResults(searchRef);
+        if (resultsResponse.data.searchResults) {
+          console.log("");
+          outputResults(resultsResponse.data.searchResults, options, useColors);
+          return;
+        }
+      }
+      if (!pollResult.success) {
+        console.log(`
+${pollResult.error}`);
+      } else if (pollResult.status !== "COMPLETED") {
+        console.log(`
+Search ended with status: ${pollResult.status.toLowerCase()}`);
+      }
+      if (searchRef) {
+        console.log(`Resume with: pkgseer search --resume ${searchRef}`);
+      }
+      return;
+    }
+    console.log(formatSearchProgress(asyncResult.progress, searchRef, useColors));
     return;
   }
   const searchResults = asyncResult.result;
@@ -2853,7 +3104,7 @@ Examples:
   # JSON output
   pkgseer search "error" -P express --json`;
 function addSearchOptions(cmd) {
-  return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: name or registry/name[@version]. Examples: express | express,lodash | pypi/django@4.2").option("-m, --mode <mode>", "Search mode: all (default), code, docs").option("-l, --limit <n>", "Max results (default: 25)").option("-v, --verbose", "Expanded output with more details").option("--refs-only", "Output only references (for piping)").option("--count", "Output result counts by package").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON").option("--wait <ms>", "Max milliseconds to wait for indexing (default: 30000)").option("--no-wait", "Return immediately without waiting for indexing");
+  return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: name or registry/name[@version]. Examples: express | express,lodash | pypi/django@4.2").option("-m, --mode <mode>", "Search mode: all (default), code, docs").option("-l, --limit <n>", "Max results (default: 25)").option("-v, --verbose", "Expanded output with more details").option("--refs-only", "Output only references (for piping)").option("--count", "Output result counts by package").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON").option("--wait <ms>", "Max milliseconds to wait for indexing (default: 30000)").option("--no-wait", "Return immediately without waiting for indexing").option("--resume <ref>", "Resume a previous search by reference").option("--no-poll", "Disable auto-polling for incomplete searches");
 }
 function registerSearchCommand(program) {
   const cmd = program.command("search [query...]").summary("Search code and documentation across packages").description(SEARCH_DESCRIPTION);
@@ -5219,6 +5470,55 @@ function createSearchProjectDocsTool(deps) {
     }
   };
 }
+// src/tools/search-status.ts
+import { z as z9 } from "zod";
+var argsSchema11 = {
+  searchRef: z9.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 this after a search returns incomplete (completed=false) to poll for completion. " + "Returns status (PENDING, INDEXING, SEARCHING, COMPLETED, TIMEOUT, FAILED), " + "progress info (packagesReady/packagesTotal), and results when status is COMPLETED.",
+    schema: argsSchema11,
+    handler: async ({ searchRef }, _extra) => {
+      return withErrorHandling("check search status", async () => {
+        const progressResult = await pkgseerService.getSearchProgress(searchRef);
+        const graphqlError = handleGraphQLErrors(progressResult.errors);
+        if (graphqlError)
+          return graphqlError;
+        const progress = progressResult.data.searchProgress;
+        if (!progress) {
+          return errorResult("Search session not found. It may have expired (sessions last 1 hour).");
+        }
+        if (progress.status === "COMPLETED") {
+          const resultsResponse = await pkgseerService.getSearchResults(searchRef);
+          const resultsError = handleGraphQLErrors(resultsResponse.errors);
+          if (resultsError)
+            return resultsError;
+          const searchResults = resultsResponse.data.searchResults;
+          if (!searchResults) {
+            return errorResult("Search completed but results are no longer available. " + "The session may have expired (sessions last 1 hour).");
+          }
+          return textResult(JSON.stringify({
+            status: progress.status,
+            searchRef: progress.searchRef,
+            result: searchResults
+          }, null, 2));
+        }
+        return textResult(JSON.stringify({
+          status: progress.status,
+          searchRef: progress.searchRef,
+          progress: {
+            packagesTotal: progress.packagesTotal,
+            packagesReady: progress.packagesReady,
+            elapsedMs: progress.elapsedMs
+          },
+          message: progress.status === "FAILED" ? "Search failed." : progress.status === "TIMEOUT" ? "Search timed out before completion." : "Search is still in progress. Poll again to check status."
+        }, null, 2));
+      });
+    }
+  };
+}
 // src/commands/mcp.ts
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
@@ -5229,6 +5529,7 @@ var TOOL_FACTORIES = {
   list_package_docs: ({ pkgseerService }) => createListPackageDocsTool(pkgseerService),
   fetch_package_doc: ({ pkgseerService }) => createFetchPackageDocTool(pkgseerService),
   search: ({ pkgseerService }) => createSearchTool(pkgseerService),
+  search_status: ({ pkgseerService }) => createSearchStatusTool(pkgseerService),
   fetch_code_context: ({ pkgseerService }) => createFetchCodeContextTool(pkgseerService),
   search_project_docs: ({ pkgseerService, configService, defaultProjectDir }) => createSearchProjectDocsTool({
     pkgseerService,
@@ -5245,6 +5546,7 @@ var PUBLIC_READ_TOOLS = [
   "list_package_docs",
   "fetch_package_doc",
   "search",
+  "search_status",
   "fetch_code_context"
 ];
 var PROJECT_READ_TOOLS = ["search_project_docs"];

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-9yar14cw.js";
+} from "./shared/chunk-55x4vqp2.js";
 export {
   version
 };

package/dist/shared/{chunk-9yar14cw.js → chunk-55x4vqp2.js}

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

package/package.json

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