@pkgseer/cli 0.2.4 → 0.2.5

package/README.md

@@ -2,120 +2,209 @@
 
 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:
 
-While you can use PkgSeer without authentication, logging in gives you higher rate limits and access to all features:
+### Skills
+
+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.
+
+### MCP Server
 
-To check your authentication status:
+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
+```
 
-```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 +214,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-drz16bhv.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -1789,7 +1789,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 +1808,8 @@ function toGraphQLRegistry(registry) {
   const map = {
     npm: "NPM",
     pypi: "PYPI",
-    hex: "HEX"
+    hex: "HEX",
+    crates: "CRATES"
   };
   return map[registry.toLowerCase()] || "NPM";
 }
@@ -2559,7 +2560,7 @@ 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 formatEntryCompact(entry, useColors) {
   if (!entry)
@@ -3319,7 +3320,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 +3353,10 @@ var MANIFEST_TYPES = [
   {
     type: "hex",
     filenames: ["mix.exs", "mix.lock"]
+  },
+  {
+    type: "crates",
+    filenames: ["Cargo.toml", "Cargo.lock"]
   }
 ];
 function suggestLabel(relativePath) {
@@ -3360,7 +3365,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 +3431,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 +4300,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 +4323,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 +4339,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 +4357,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 +4398,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 +4467,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 +4588,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 +4637,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 +4647,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 () => {
@@ -5173,7 +5180,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 +5262,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 +5534,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 +5636,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 +5680,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 +5693,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 +5737,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 +5794,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-drz16bhv.js";
 export {
   version
 };

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

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