@pkgseer/cli 0.2.4 → 0.3.0

package/README.md

@@ -2,120 +2,215 @@
 
 CLI and MCP server for [PkgSeer](https://pkgseer.dev) — package intelligence for developers and AI assistants.
 
-Get insights about packages across npm, PyPI, and Hex registries: metadata, security vulnerabilities, dependencies, and quality metrics. Works standalone or as an MCP server for AI assistants like Claude and Cursor.
+Get insights about packages across npm, PyPI, Hex, and crates.io registries: search code and documentation, check security vulnerabilities, analyze dependencies, and compare packages. Works standalone or as an MCP server for AI assistants like Claude and Cursor.
 
 ## Installation
 
-The easiest way to get started is using npx — no installation required:
+Use npx without installation:
 
 ```bash
 npx @pkgseer/cli --help
 ```
 
-For frequent use, install globally:
+Or install globally:
 
 ```bash
 npm install -g @pkgseer/cli
 ```
 
-## Getting Started
+## Quick Start
 
-### 1. Authenticate (Recommended)
+```bash
+# Interactive setup (recommended for first-time users)
+pkgseer init
+
+# Or set up manually:
+pkgseer login              # Authenticate with your PkgSeer account
+pkgseer skill init         # Install as AI assistant skill
+```
+
+## AI Assistant Integration
+
+PkgSeer works with AI assistants in two ways:
+
+### Skills
 
-While you can use PkgSeer without authentication, logging in gives you higher rate limits and access to all features:
+Skills teach your AI assistant to use PkgSeer CLI commands through natural language:
 
 ```bash
-pkgseer login
+pkgseer skill init
 ```
 
-This opens your browser to authenticate with your PkgSeer account. Your credentials are stored securely in `~/.pkgseer/`.
+This installs a skill definition for Claude Code or Codex CLI. The AI runs CLI commands and reads the output.
 
-To check your authentication status:
+### MCP Server
+
+MCP provides structured tools that AI assistants can call programmatically:
 
 ```bash
-pkgseer auth status
+pkgseer mcp init
 ```
 
-### 2. Use with AI Assistants
-
-The main use case for this CLI is as an MCP (Model Context Protocol) server that gives AI assistants access to package intelligence.
+This provides structured tools that AI assistants can call programmatically. Configuration varies by assistant:
 
-#### Cursor IDE
+**Claude Code / Codex CLI**: The `mcp init` command configures these automatically.
 
-Add this to your `.cursor/mcp.json` file:
+**Cursor IDE**: Add to `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "pkgseer": {
       "command": "npx",
-      "args": ["-y", "@pkgseer/cli", "mcp"]
+      "args": ["-y", "@pkgseer/cli", "mcp", "start"]
     }
   }
 }
 ```
 
-#### Claude Desktop
-
-Add this to your Claude Desktop configuration file:
-
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Claude Desktop**: Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
 {
   "mcpServers": {
     "pkgseer": {
       "command": "npx",
-      "args": ["-y", "@pkgseer/cli", "mcp"]
+      "args": ["-y", "@pkgseer/cli", "mcp", "start"]
     }
   }
 }
 ```
 
-Once configured, your AI assistant can use tools to answer questions like:
+## CLI Commands
 
-- "What security vulnerabilities does lodash have?"
-- "Compare react vs preact vs solid-js"
-- "What are the dependencies of express?"
+### Search
 
-#### Prompt for AI Assistants
+Search code and documentation across packages:
 
-To help your AI assistant use PkgSeer proactively, add this to your project rules (`.cursor/rules`, `AGENTS.md`, or similar):
+```bash
+# Search in specific packages
+pkgseer search "authentication" -P express,passport
+pkgseer search "http client" -P pypi:requests,pypi:httpx
+pkgseer search "json parsing" -P hex:jason,hex:poison
+
+# Search modes
+pkgseer search "auth" -P lodash --mode code   # Code only
+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
+```
+
+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.
 
-```markdown
-When working with dependencies:
+### Package Commands
 
-- Use PkgSeer MCP tools to check for security vulnerabilities before adding new packages
-- Compare package alternatives with compare_packages when multiple options exist
-- Review package quality metrics to ensure dependencies are well-maintained
+```bash
+pkgseer pkg info lodash              # Package summary and metadata
+pkgseer pkg vulns lodash@4.17.21     # Security vulnerabilities
+pkgseer pkg quality express          # Quality score (0-100)
+pkgseer pkg deps express             # Direct dependencies
+pkgseer pkg deps express --transitive  # Include transitive deps
+pkgseer pkg compare axios got fetch-h2  # Compare packages
 ```
 
-## Available Tools
+Package format: `[registry:]name[@version]`
+- `lodash` — npm (default registry)
+- `pypi:requests` — PyPI
+- `hex:phoenix` — Hex
+- `crates:serde` — crates.io
+- `lodash@4.17.21` — specific version
+
+### Documentation Commands
 
-When running as an MCP server, the following tools are available to AI assistants:
+```bash
+pkgseer docs list pypi:requests        # List available doc pages
+pkgseer docs get lodash/chunk          # Fetch specific doc page
+pkgseer docs search "routing" -P express  # Search docs only
+```
 
-| Tool                      | What it does                                                                        |
-| ------------------------- | ----------------------------------------------------------------------------------- |
-| `package_summary`         | Get package metadata, latest versions, security advisories, and quickstart examples |
-| `package_vulnerabilities` | Find known security vulnerabilities affecting a package                             |
-| `package_dependencies`    | Explore the dependency tree (direct and transitive)                                 |
-| `package_quality`         | View quality metrics and maintenance scores                                         |
-| `compare_packages`        | Compare multiple packages side-by-side                                              |
+### Project Commands
 
-All tools work with **npm**, **PyPI**, and **Hex** registries.
+```bash
+pkgseer project init     # Create pkgseer.yml config
+pkgseer project detect   # Detect package manifests
+pkgseer project upload   # Upload project to PkgSeer
+```
 
-## CLI Commands
+### Authentication
 
 ```bash
-pkgseer --help           # Show all available commands
-pkgseer --version        # Show version number
+pkgseer login            # Authenticate via browser
+pkgseer logout           # Sign out
+pkgseer auth status      # Check authentication state
+```
+
+### Configuration
+
+```bash
+pkgseer config show      # Display current configuration
+```
+
+## MCP Tools
+
+When running as an MCP server, these tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `package_summary` | Package metadata, versions, quickstart examples |
+| `package_vulnerabilities` | Security advisories and CVEs |
+| `package_dependencies` | Dependency tree (direct and transitive) |
+| `package_quality` | Quality score with category breakdown |
+| `compare_packages` | Side-by-side comparison of packages |
+| `list_package_docs` | Available documentation pages |
+| `fetch_package_doc` | Full content of a documentation page |
+| `search` | Search code and docs across packages |
+| `fetch_code_context` | Fetch code from search results |
+| `search_project_docs` | Search docs for packages in current project |
+
+## Configuration
+
+### Project Configuration
 
-pkgseer login            # Authenticate with your PkgSeer account
-pkgseer logout           # Sign out and clear stored credentials
-pkgseer auth status      # Check if you're logged in and token validity
+Create `pkgseer.yml` in your project root:
 
-pkgseer mcp              # Start the MCP server (for AI assistant integration)
+```yaml
+project: my-project-name
+
+# Optional: limit which tools are available
+enabled_tools:
+  - package_summary
+  - package_vulnerabilities
+  - search_project_docs
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PKGSEER_API_TOKEN` | API token (alternative to `pkgseer login`) |
+| `PKGSEER_URL` | Base URL for PkgSeer (for development/testing) |
+
+## Documentation
+
+- [Architecture Overview](docs/implementation/architecture.md)
+- [MCP Installation Guide](docs/implementation/mcp-installation.md)
+- [Creating MCP Tools](docs/implementation/tools.md)
+- [Authentication Flow](docs/implementation/auth.md)
+- [Skills System](docs/implementation/skills.md)
+- [Configuration Reference](docs/implementation/configuration.md)
+
+## Development
+
+See [CLAUDE.md](CLAUDE.md) for development guidelines.
+
+```bash
+bun install              # Install dependencies
+bun run dev              # Development mode
+bun test                 # Run tests
+bun run build            # Build for production
+bun run codegen          # Regenerate GraphQL types
 ```
 
 ## Need Help?
@@ -125,4 +220,4 @@ pkgseer mcp              # Start the MCP server (for AI assistant integration)
 
 ## License
 
-MIT © [Juha Litola](https://github.com/pkgseer)
+(c) 2025-2026 Juha Litola

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-48mwa8wt.js";
+} from "./shared/chunk-9yar14cw.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -211,36 +211,52 @@ var CliDocsListDocument = gql`
 }
     `;
 var CombinedSearchDocument = gql`
-    query CombinedSearch($packages: [SearchPackageInput!]!, $query: String!, $mode: SearchMode, $limit: Int) {
-  combinedSearch(packages: $packages, query: $query, mode: $mode, limit: $limit) {
-    query
-    mode
-    totalResults
-    entries {
-      id
-      type
-      title
-      subtitle
-      packageName
-      registry
-      score
-      snippet
-      filePath
-      startLine
-      endLine
-      language
-      chunkType
-      repoUrl
-      gitRef
-      pageId
-      sourceUrl
+    query CombinedSearch($packages: [SearchPackageInput!]!, $query: String!, $mode: SearchMode, $limit: Int, $waitTimeoutMs: Int) {
+  combinedSearch(
+    packages: $packages
+    query: $query
+    mode: $mode
+    limit: $limit
+    waitTimeoutMs: $waitTimeoutMs
+  ) {
+    completed
+    searchRef
+    result {
+      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
+      }
     }
-    indexingStatus {
-      registry
-      packageName
-      version
-      codeStatus
-      docsStatus
+    progress {
+      status
+      packagesTotal
+      packagesReady
+      elapsedMs
     }
   }
 }
@@ -1419,7 +1435,8 @@ class PkgseerServiceImpl {
       packages,
       query,
       mode: options?.mode,
-      limit: options?.limit
+      limit: options?.limit,
+      waitTimeoutMs: options?.waitTimeoutMs
     });
     return { data: result.data, errors: result.errors };
   }
@@ -1789,7 +1806,7 @@ function parsePackageSpec(spec) {
   if (spec.includes(":")) {
     const colonIndex = spec.indexOf(":");
     const potentialRegistry = spec.slice(0, colonIndex).toLowerCase();
-    if (["npm", "pypi", "hex"].includes(potentialRegistry)) {
+    if (["npm", "pypi", "hex", "crates"].includes(potentialRegistry)) {
       registry = potentialRegistry;
       rest = spec.slice(colonIndex + 1);
     }
@@ -1808,7 +1825,8 @@ function toGraphQLRegistry(registry) {
   const map = {
     npm: "NPM",
     pypi: "PYPI",
-    hex: "HEX"
+    hex: "HEX",
+    crates: "CRATES"
   };
   return map[registry.toLowerCase()] || "NPM";
 }
@@ -2341,6 +2359,7 @@ function registerDocsListCommand(program) {
   });
 }
 // src/commands/search.ts
+var DEFAULT_WAIT_TIMEOUT_MS = 30000;
 var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -2559,7 +2578,37 @@ function abbrevLang(lang) {
 function truncate(text, maxLen) {
   if (text.length <= maxLen)
     return text;
-  return text.slice(0, maxLen - 3) + "...";
+  return `${text.slice(0, maxLen - 3)}...`;
+}
+function isSubstantiveLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0)
+    return false;
+  if (/^[(){}[\];,]+$/.test(trimmed))
+    return false;
+  if (trimmed.length <= 3 && /^[^a-zA-Z0-9]*$/.test(trimmed))
+    return false;
+  return true;
+}
+function findBestSnippetLine(snippet) {
+  const lines = snippet.split(`
+`).map((l) => l.trim());
+  if (lines.length === 0)
+    return null;
+  const middleIndex = Math.floor((lines.length - 1) / 2);
+  for (let offset = 0;offset <= lines.length; offset++) {
+    const beforeIdx = middleIndex - offset;
+    if (beforeIdx >= 0 && isSubstantiveLine(lines[beforeIdx])) {
+      return lines[beforeIdx];
+    }
+    if (offset > 0) {
+      const afterIdx = middleIndex + offset;
+      if (afterIdx < lines.length && isSubstantiveLine(lines[afterIdx])) {
+        return lines[afterIdx];
+      }
+    }
+  }
+  return null;
 }
 function formatEntryCompact(entry, useColors) {
   if (!entry)
@@ -2578,12 +2627,11 @@ function formatEntryCompact(entry, useColors) {
   }
   let snippet = "";
   if (entry.snippet) {
-    const firstLine = entry.snippet.split(`
-`).map((l) => l.trim()).find((l) => l.length > 0);
-    if (firstLine) {
-      snippet = `  ${truncate(firstLine, 80)}`;
+    const bestLine = findBestSnippetLine(entry.snippet);
+    if (bestLine) {
+      snippet = `  ${truncate(bestLine, 80)}`;
       if (useColors) {
-        snippet = `  ${colors.dim}${truncate(firstLine, 80)}${colors.reset}`;
+        snippet = `  ${colors.dim}${truncate(bestLine, 80)}${colors.reset}`;
       }
     }
   }
@@ -2661,6 +2709,50 @@ function summarizeSearchResults(results) {
   return lines.join(`
 `);
 }
+function formatSearchProgress(progress, searchRef, useColors) {
+  const lines = [];
+  if (useColors) {
+    lines.push(`${colors.yellow}Search in progress...${colors.reset}`);
+  } else {
+    lines.push("Search in progress...");
+  }
+  if (progress) {
+    const statusText = progress.status?.toLowerCase() ?? "unknown";
+    lines.push(`Status: ${statusText}`);
+    if (progress.packagesTotal != null && progress.packagesReady != null) {
+      lines.push(`Packages: ${progress.packagesReady}/${progress.packagesTotal} ready`);
+    }
+    if (progress.elapsedMs != null) {
+      lines.push(`Elapsed: ${(progress.elapsedMs / 1000).toFixed(1)}s`);
+    }
+  }
+  lines.push("");
+  lines.push("Some packages may still be indexing.");
+  lines.push("Run again in a moment for complete results.");
+  if (searchRef) {
+    lines.push("");
+    if (useColors) {
+      lines.push(`${colors.dim}Search ref: ${searchRef}${colors.reset}`);
+    } else {
+      lines.push(`Search ref: ${searchRef}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function getWaitTimeoutMs(options) {
+  if (options.noWait) {
+    return 0;
+  }
+  if (options.wait) {
+    const parsed = Number.parseInt(options.wait, 10);
+    if (!Number.isNaN(parsed) && parsed >= 0) {
+      return parsed;
+    }
+    console.warn(`Warning: Invalid --wait value "${options.wait}". Using default (${DEFAULT_WAIT_TIMEOUT_MS}ms).`);
+  }
+  return DEFAULT_WAIT_TIMEOUT_MS;
+}
 async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
   const { pkgseerService } = deps;
   const query = Array.isArray(queryArg) ? queryArg.join(" ") : queryArg ?? "";
@@ -2680,16 +2772,37 @@ async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
   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,
-    limit
+    limit,
+    waitTimeoutMs
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.combinedSearch) {
+  const asyncResult = result.data.combinedSearch;
+  if (!asyncResult) {
     outputError("No results returned. Check package names and registries.", options.json ?? false);
     return;
   }
-  outputResults(result.data.combinedSearch, options, useColors);
+  if (!asyncResult.completed) {
+    if (options.json) {
+      output({
+        completed: false,
+        searchRef: asyncResult.searchRef,
+        progress: asyncResult.progress,
+        message: "Search is still indexing. Retry for complete results."
+      }, true);
+    } else {
+      console.log(formatSearchProgress(asyncResult.progress, asyncResult.searchRef, useColors));
+    }
+    return;
+  }
+  const searchResults = asyncResult.result;
+  if (!searchResults) {
+    outputError("Search completed but no results returned.", options.json ?? false);
+    return;
+  }
+  outputResults(searchResults, options, useColors);
 }
 function outputResults(results, options, useColors) {
   const format = options.json ? "json" : options.format ?? "human";
@@ -2740,7 +2853,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");
+  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");
 }
 function registerSearchCommand(program) {
   const cmd = program.command("search [query...]").summary("Search code and documentation across packages").description(SEARCH_DESCRIPTION);
@@ -2781,7 +2894,7 @@ Examples:
 
 Note: For code search, use 'pkgseer search --mode code' instead.`;
 function addDocsSearchOptions(cmd) {
-  return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: [registry:]name[@version]. Examples: express | express,lodash | pypi:django@4.2").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");
+  return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: [registry:]name[@version]. Examples: express | express,lodash | pypi:django@4.2").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");
 }
 function registerDocsSearchCommand(program) {
   const cmd = program.command("search [query...]").summary("Search documentation").description(DOCS_SEARCH_DESCRIPTION);
@@ -3319,7 +3432,7 @@ function shouldIgnorePath(relativePath, patterns) {
   return ignored;
 }
 function shouldIgnoreDirectory(relativeDirPath, patterns) {
-  const normalized = relativeDirPath.replace(/\\/g, "/").replace(/\/$/, "") + "/";
+  const normalized = `${relativeDirPath.replace(/\\/g, "/").replace(/\/$/, "")}/`;
   return shouldIgnorePath(normalized, patterns);
 }
 
@@ -3352,6 +3465,10 @@ var MANIFEST_TYPES = [
   {
     type: "hex",
     filenames: ["mix.exs", "mix.lock"]
+  },
+  {
+    type: "crates",
+    filenames: ["Cargo.toml", "Cargo.lock"]
   }
 ];
 function suggestLabel(relativePath) {
@@ -3360,7 +3477,7 @@ function suggestLabel(relativePath) {
   if (parts.length === 1) {
     return "root";
   }
-  return parts[parts.length - 2];
+  return parts[parts.length - 2] ?? "root";
 }
 async function scanDirectoryRecursive(directory, fs, rootDir, options, currentDepth = 0, gitignorePatterns = null) {
   const detected = [];
@@ -3426,12 +3543,12 @@ function filterRedundantPackageJson(manifests) {
     if (!dirToManifests.has(dir)) {
       dirToManifests.set(dir, []);
     }
-    dirToManifests.get(dir).push(manifest);
+    dirToManifests.get(dir)?.push(manifest);
   }
   const filtered = [];
-  for (const [dir, dirManifests] of dirToManifests.entries()) {
+  for (const [_dir, dirManifests] of dirToManifests.entries()) {
     const hasLockFile = dirManifests.some((m) => m.filename === "package-lock.json");
-    const hasPackageJson = dirManifests.some((m) => m.filename === "package.json");
+    const _hasPackageJson = dirManifests.some((m) => m.filename === "package.json");
     for (const manifest of dirManifests) {
       if (manifest.filename === "package.json" && hasLockFile) {
         continue;
@@ -4295,9 +4412,9 @@ Project already configured: ${highlight(existingConfig.config.project, useColors
       setupProject = false;
     } else {
       console.log(`
-` + "=".repeat(50));
+${"=".repeat(50)}`);
       console.log("Project Configuration Setup");
-      console.log("=".repeat(50) + `
+      console.log(`${"=".repeat(50)}
 `);
       await projectInit({}, {
         projectService: deps.projectService,
@@ -4318,9 +4435,9 @@ ${highlight("✓", useColors)} Project setup complete!
   }
   if (aiIntegration === "skill") {
     console.log(`
-` + "=".repeat(50));
+${"=".repeat(50)}`);
     console.log("Skill Setup");
-    console.log("=".repeat(50) + `
+    console.log(`${"=".repeat(50)}
 `);
     await skillInit({
       fileSystemService: deps.fileSystemService,
@@ -4334,9 +4451,9 @@ ${highlight("✓", useColors)} Skill setup complete!
     const currentConfig = await deps.configService.loadProjectConfig();
     const hasProjectNow = currentConfig?.config.project !== undefined;
     console.log(`
-` + "=".repeat(50));
+${"=".repeat(50)}`);
     console.log("MCP Server Setup");
-    console.log("=".repeat(50) + `
+    console.log(`${"=".repeat(50)}
 `);
     await mcpInit({
       fileSystemService: deps.fileSystemService,
@@ -4352,7 +4469,7 @@ ${highlight("✓", useColors)} MCP setup complete!
   }
   console.log("=".repeat(50));
   console.log("Setup Complete!");
-  console.log("=".repeat(50) + `
+  console.log(`${"=".repeat(50)}
 `);
   if (setupProject) {
     const finalConfig = await deps.configService.loadProjectConfig();
@@ -4393,8 +4510,7 @@ function showCliUsage(useColors) {
   console.log(`  ${highlight("pkgseer docs get <pkg>/<page>", useColors)}   Fetch doc content`);
   console.log(`  ${highlight("pkgseer docs search <query>", useColors)}     Search documentation
 `);
-  console.log(dim(`All commands support --json for structured output.
-` + "Tip: Run 'pkgseer quickstart' for a quick reference guide.", useColors));
+  console.log(dim("All commands support --json for structured output.", useColors));
 }
 function registerInitCommand(program) {
   program.command("init").summary("Set up project and AI integration").description(`Set up PkgSeer for your project.
@@ -4463,9 +4579,11 @@ async function loginAction(options, deps) {
   let callback;
   try {
     callback = await Promise.race([serverPromise, timeoutPromise]);
-    clearTimeout(timeoutId);
+    if (timeoutId)
+      clearTimeout(timeoutId);
   } catch (error2) {
-    clearTimeout(timeoutId);
+    if (timeoutId)
+      clearTimeout(timeoutId);
     if (error2 instanceof Error) {
       console.log(`${error2.message}.
 `);
@@ -4582,12 +4700,13 @@ function toGraphQLRegistry2(registry) {
   const map = {
     npm: "NPM",
     pypi: "PYPI",
-    hex: "HEX"
+    hex: "HEX",
+    crates: "CRATES"
   };
   return map[registry.toLowerCase()] || "NPM";
 }
 var schemas = {
-  registry: z2.enum(["npm", "pypi", "hex"]).describe("Package registry (npm, pypi, or hex)"),
+  registry: z2.enum(["npm", "pypi", "hex", "crates"]).describe("Package registry (npm, pypi, hex, or crates)"),
   packageName: z2.string().max(255).describe("Name of the package"),
   version: z2.string().max(100).optional().describe("Specific version (defaults to latest)")
 };
@@ -4630,7 +4749,7 @@ function notFoundError(packageName, registry) {
 
 // src/tools/compare-packages.ts
 var packageInputSchema = z3.object({
-  registry: z3.enum(["npm", "pypi", "hex"]),
+  registry: z3.enum(["npm", "pypi", "hex", "crates"]),
   name: z3.string().max(255),
   version: z3.string().max(100).optional()
 });
@@ -4640,7 +4759,7 @@ var argsSchema = {
 function createComparePackagesTool(pkgseerService) {
   return {
     name: "compare_packages",
-    description: "Compare 2-10 packages side-by-side. Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
+    description: "Compare 2-10 packages side-by-side. Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex, crates). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
     schema: argsSchema,
     handler: async ({ packages }, _extra) => {
       return withErrorHandling("compare packages", async () => {
@@ -4944,11 +5063,13 @@ var packageInputSchema2 = z7.object({
   name: z7.string().min(1).describe("Package name"),
   version: z7.string().optional().describe("Specific version (defaults to latest)")
 });
+var DEFAULT_AGENT_WAIT_TIMEOUT_MS = 1e4;
 var argsSchema9 = {
   packages: z7.array(packageInputSchema2).min(1).max(20).describe("Packages to search (1-20). Each package needs registry and name."),
   query: z7.string().min(1).describe("Search query - natural language or keywords"),
   mode: z7.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
-  limit: z7.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)")
+  limit: z7.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
+  waitTimeoutMs: z7.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
 };
 function toSearchMode2(mode) {
   if (!mode)
@@ -4986,9 +5107,9 @@ Results may be incomplete. Retry later for more complete results.`;
 function createSearchTool(pkgseerService) {
   return {
     name: "search",
-    description: "Search code and documentation across packages. Returns functions, classes, and documentation pages " + "matching your query. Use mode='code' for code only, mode='docs' for documentation only, or " + "mode='all' (default) for both. Provide 1-20 packages to search. Results include relevance scores " + "and snippets showing matches.",
+    description: "Search code and documentation across packages. Returns functions, classes, and documentation pages " + "matching your query. Use mode='code' for code only, mode='docs' for documentation only, or " + "mode='all' (default) for both. Provide 1-20 packages to search. Results include relevance scores " + "and snippets showing matches. If packages need indexing, the search will wait up to waitTimeoutMs " + "(default 10s). If not complete, returns progress info with searchRef for follow-up.",
     schema: argsSchema9,
-    handler: async ({ packages, query, mode, limit }, _extra) => {
+    handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
       return withErrorHandling("search packages", async () => {
         const normalizedQuery = query.trim();
         if (normalizedQuery.length === 0) {
@@ -5001,15 +5122,29 @@ function createSearchTool(pkgseerService) {
         }));
         const result = await pkgseerService.combinedSearch(graphqlPackages, normalizedQuery, {
           mode: toSearchMode2(mode),
-          limit
+          limit,
+          waitTimeoutMs: waitTimeoutMs ?? DEFAULT_AGENT_WAIT_TIMEOUT_MS
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.combinedSearch) {
+        const asyncResult = result.data.combinedSearch;
+        if (!asyncResult) {
           return errorResult("No search results returned. Check package names and registries.");
         }
-        const searchResult = result.data.combinedSearch;
+        if (!asyncResult.completed) {
+          const progressInfo = {
+            completed: false,
+            searchRef: asyncResult.searchRef,
+            progress: asyncResult.progress,
+            message: "Search is still indexing. Retry with same query for results, " + "or increase waitTimeoutMs to wait longer."
+          };
+          return textResult(JSON.stringify(progressInfo, null, 2));
+        }
+        const searchResult = asyncResult.result;
+        if (!searchResult) {
+          return errorResult("Search completed but no results returned.");
+        }
         const entries = searchResult.entries ?? [];
         if (entries.length === 0) {
           return errorResult(`No results found for "${normalizedQuery}". ` + "Try broader terms or different packages.");
@@ -5173,7 +5308,7 @@ function showMcpSetupInstructions(deps) {
   console.log(`  ${highlight(`${deps.baseUrl}/docs/mcp-server`, useColors)}
 `);
   console.log("Alternative: Use CLI directly (no MCP setup needed)");
-  console.log(`  ${highlight("pkgseer quickstart", useColors)}`);
+  console.log(`  ${highlight("pkgseer pkg info <package>", useColors)}`);
 }
 function registerMcpCommand(program) {
   const mcpCommand = program.command("mcp").summary("Show setup instructions or start MCP server").description(`Start the Model Context Protocol (MCP) server using STDIO transport.
@@ -5255,10 +5390,10 @@ async function pkgCompareAction(packages, options, deps) {
   if (options.json) {
     const pkgs = result.data.comparePackages.packages?.filter((p) => p) ?? [];
     const slim = pkgs.map((p) => ({
-      package: `${p.packageName}@${p.version}`,
-      quality: p.quality?.score,
-      downloads: p.downloadsLastMonth,
-      vulnerabilities: p.vulnerabilityCount
+      package: `${p?.packageName}@${p?.version}`,
+      quality: p?.quality?.score,
+      downloads: p?.downloadsLastMonth,
+      vulnerabilities: p?.vulnerabilityCount
     }));
     output(slim, true);
   } else {
@@ -5527,8 +5662,8 @@ async function pkgQualityAction(packageArg, options, deps) {
       score: quality?.overallScore,
       grade: quality?.grade,
       categories: quality?.categories?.filter((c) => c).map((c) => ({
-        name: c.category,
-        score: c.score
+        name: c?.category,
+        score: c?.score
       }))
     };
     output(slim, true);
@@ -5629,10 +5764,10 @@ async function pkgVulnsAction(packageArg, options, deps) {
       package: `${data.package?.name}@${data.package?.version}`,
       count: data.security?.vulnerabilityCount ?? 0,
       vulnerabilities: vulns.filter((v) => v).map((v) => ({
-        id: v.osvId,
-        severity: v.severityScore,
-        summary: v.summary,
-        fixed: v.fixedInVersions
+        id: v?.osvId,
+        severity: v?.severityScore,
+        summary: v?.summary,
+        fixed: v?.fixedInVersions
       }))
     };
     output(slim, true);
@@ -5673,7 +5808,7 @@ function matchManifestsWithConfig(detectedGroups, existingManifests) {
       });
     }
   }
-  const labelToFiles = new Map;
+  const _labelToFiles = new Map;
   const labelToConfig = new Map;
   for (const detectedGroup of detectedGroups) {
     for (const manifest of detectedGroup.manifests) {
@@ -5686,13 +5821,14 @@ function matchManifestsWithConfig(detectedGroups, existingManifests) {
         label = existingConfig?.label ?? detectedGroup.label;
       }
       const allowMixDeps = existingConfig?.allow_mix_deps;
-      if (!labelToConfig.has(label)) {
-        labelToConfig.set(label, {
+      let config = labelToConfig.get(label);
+      if (!config) {
+        config = {
           files: new Set,
           allow_mix_deps: allowMixDeps
-        });
+        };
+        labelToConfig.set(label, config);
       }
-      const config = labelToConfig.get(label);
       config.files.add(manifest.relativePath);
       if (allowMixDeps) {
         config.allow_mix_deps = true;
@@ -5729,7 +5865,7 @@ function matchManifestsWithConfig(detectedGroups, existingManifests) {
   });
 }
 async function projectDetectAction(options, deps) {
-  const { configService, fileSystemService, promptService, shellService } = deps;
+  const { configService, fileSystemService, promptService } = deps;
   const projectConfig = await configService.loadProjectConfig();
   if (!projectConfig?.config.project) {
     console.error(`✗ No project is configured in pkgseer.yml`);
@@ -5786,7 +5922,7 @@ Suggested configuration:`);
       console.log(`${prefix}${file}`);
     }
   }
-  const hasHexManifests = detectedGroups.some((group) => group.manifests.some((m) => m.type === "hex"));
+  const _hasHexManifests = detectedGroups.some((group) => group.manifests.some((m) => m.type === "hex"));
   const hasHexInSuggested = suggestedManifests.some((g) => g.files.some((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock")));
   let allowMixDeps = false;
   if (hasHexInSuggested) {

package/dist/index.js

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

package/dist/shared/{chunk-48mwa8wt.js → chunk-9yar14cw.js}

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