@pkgseer/cli 0.2.0 → 0.2.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-1m9g9ehr.js";
+} from "./shared/chunk-9016p6c6.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -3839,6 +3839,317 @@ function registerProjectInitCommand(program) {
   });
 }
 
+// src/commands/skill-init.ts
+function generateSkillContent() {
+  return `---
+name: pkgseer
+version: ${version}
+description: >-
+  Search code and documentation across npm, PyPI, and Hex packages.
+  Find functions, classes, APIs, and usage examples. Also provides
+  quality scores, security vulnerabilities, dependencies, and comparisons.
+  Triggers on: "how does X work", "find examples of", "search for",
+  "is X secure", "compare X vs Y", package evaluation, dependency decisions,
+  "what package should I use for", API lookup, security audits.
+---
+
+# PkgSeer - Package Intelligence
+
+Search and analyze packages across npm, PyPI, and Hex. All commands support \`--json\`.
+
+## Search (Primary Use Case)
+
+\`\`\`bash
+# Search code and docs across packages
+pkgseer search "<query>" -P lodash,express    # npm packages
+pkgseer search "<query>" -P requests -r pypi  # PyPI packages
+pkgseer search "authentication" -P phoenix,plug -r hex
+
+# Search modes
+pkgseer search "<query>" -P <packages> --code  # Code only
+pkgseer search "<query>" -P <packages> --docs  # Docs only
+
+# Search project dependencies (requires pkgseer.yml)
+pkgseer docs search "<query>"
+\`\`\`
+
+## Package Analysis
+
+\`\`\`bash
+# Overview: metadata, versions, quickstart
+pkgseer pkg info <package> [-r npm|pypi|hex]
+
+# Quality score (0-100) with category breakdown
+pkgseer pkg quality <package> [-r registry] [-v version]
+
+# Security: CVEs, severity, upgrade paths
+pkgseer pkg vulns <package> [-r registry] [-v version]
+
+# Dependencies: direct, transitive, tree view
+pkgseer pkg deps <package> [-r registry] [-t] [-d depth]
+
+# Compare up to 10 packages
+pkgseer pkg compare lodash underscore ramda
+pkgseer pkg compare npm:axios pypi:httpx  # cross-registry
+\`\`\`
+
+## Documentation
+
+\`\`\`bash
+pkgseer docs list <package> [-r registry]  # List pages
+pkgseer docs get <package>/<page-id>       # Fetch content
+\`\`\`
+
+## Tips
+
+- Default registry: npm. Use \`-r pypi\` or \`-r hex\` for others
+- Use \`--json\` for structured output when parsing
+- Version defaults to latest; use \`-v\` for specific
+`;
+}
+function extractSkillVersion(content) {
+  const match = content.match(/^version:\s*["']?([^"'\n]+)["']?/m);
+  return match?.[1]?.trim() ?? null;
+}
+function getClaudeCodeSkillPaths(fs, scope) {
+  const baseDir = scope === "user" ? fs.joinPath(fs.getHomeDir(), ".claude", "skills", "pkgseer") : fs.joinPath(fs.getCwd(), ".claude", "skills", "pkgseer");
+  return {
+    skillDir: baseDir,
+    skillPath: fs.joinPath(baseDir, "SKILL.md")
+  };
+}
+function getCodexSkillPaths(fs, scope) {
+  const baseDir = scope === "user" ? fs.joinPath(fs.getHomeDir(), ".codex", "skills", "pkgseer") : fs.joinPath(fs.getCwd(), ".codex", "skills", "pkgseer");
+  return {
+    skillDir: baseDir,
+    skillPath: fs.joinPath(baseDir, "SKILL.md")
+  };
+}
+async function installSkill(fs, skillDir, skillPath) {
+  try {
+    const exists = await fs.exists(skillPath);
+    let updated = false;
+    if (exists) {
+      const existingContent = await fs.readFile(skillPath);
+      const existingVersion = extractSkillVersion(existingContent);
+      if (existingVersion === version) {
+        return {
+          success: true,
+          path: skillPath,
+          updated: false
+        };
+      }
+      updated = true;
+    }
+    await fs.ensureDir(skillDir);
+    const content = generateSkillContent();
+    await fs.writeFile(skillPath, content);
+    return {
+      success: true,
+      path: skillPath,
+      updated
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function skillInitAction(deps) {
+  const { fileSystemService: fs, promptService } = deps;
+  const useColors = shouldUseColors2();
+  console.log("Skill Setup");
+  console.log(`───────────
+`);
+  console.log(`Install PkgSeer as an agent skill for your AI assistant.
+`);
+  console.log(dim(`Skills provide Claude/Codex with package intelligence capabilities
+` + `through natural language - no MCP server required.
+`, useColors));
+  const tool = await promptService.select("Which AI tool would you like to configure?", [
+    {
+      value: "claude-code",
+      name: "Claude Code",
+      description: "Install skill for Claude Code CLI"
+    },
+    {
+      value: "codex",
+      name: "Codex CLI",
+      description: "Install skill for OpenAI Codex CLI"
+    },
+    {
+      value: "other",
+      name: "Other / Manual",
+      description: "Show SKILL.md content for manual installation"
+    }
+  ]);
+  if (tool === "other") {
+    showManualInstructions2(useColors);
+    return;
+  }
+  const scope = await promptService.select("Where should the skill be installed?", [
+    {
+      value: "user",
+      name: "User-level (recommended)",
+      description: "Available in all your projects"
+    },
+    {
+      value: "project",
+      name: "Project-level",
+      description: "Only available in this project"
+    }
+  ]);
+  const paths = tool === "claude-code" ? getClaudeCodeSkillPaths(fs, scope) : getCodexSkillPaths(fs, scope);
+  const exists = await fs.exists(paths.skillPath);
+  if (exists) {
+    const existingContent = await fs.readFile(paths.skillPath);
+    const existingVersion = extractSkillVersion(existingContent);
+    if (existingVersion === version) {
+      console.log(success(`
+PkgSeer skill already installed (v${version})`, useColors));
+      console.log(`Location: ${highlight(paths.skillPath, useColors)}`);
+      return;
+    }
+    console.log(`
+Existing skill found: v${existingVersion ?? "unknown"} → v${version}`);
+    const proceed = await promptService.confirm("Update to latest version?", true);
+    if (!proceed) {
+      console.log(dim(`
+Skip update.`, useColors));
+      return;
+    }
+  }
+  console.log(dim(`
+Installing skill...`, useColors));
+  const result = await installSkill(fs, paths.skillDir, paths.skillPath);
+  if (!result.success) {
+    console.log(error(`
+Failed to install skill: ${result.error}`, useColors));
+    showManualInstructions2(useColors);
+    return;
+  }
+  const toolName = tool === "claude-code" ? "Claude Code" : "Codex";
+  const action = result.updated ? "updated" : "installed";
+  console.log(success(`
+PkgSeer skill ${action} for ${toolName}!`, useColors));
+  console.log(`Location: ${highlight(paths.skillPath, useColors)}`);
+  console.log(dim(`
+The skill is now available. Try asking:
+` + `  "Search for authentication examples in express"
+` + `  "Is lodash secure? Check for vulnerabilities"
+` + '  "Compare axios vs fetch vs got"', useColors));
+}
+function showManualInstructions2(useColors) {
+  console.log(`
+Manual Installation`);
+  console.log(`───────────────────
+`);
+  console.log(`Create a SKILL.md file in your skills directory:
+`);
+  console.log("Claude Code:");
+  console.log(`  User:    ${highlight("~/.claude/skills/pkgseer/SKILL.md", useColors)}`);
+  console.log(`  Project: ${highlight(".claude/skills/pkgseer/SKILL.md", useColors)}
+`);
+  console.log("Codex:");
+  console.log(`  User:    ${highlight("~/.codex/skills/pkgseer/SKILL.md", useColors)}`);
+  console.log(`  Project: ${highlight(".codex/skills/pkgseer/SKILL.md", useColors)}
+`);
+  console.log(`Content:
+`);
+  console.log("─".repeat(60));
+  console.log(generateSkillContent());
+  console.log("─".repeat(60));
+}
+async function skillUpdateAction(deps) {
+  const { fileSystemService: fs } = deps;
+  const useColors = shouldUseColors2();
+  console.log(`Checking for skill updates...
+`);
+  const locations = [
+    {
+      name: "Claude Code (user)",
+      ...getClaudeCodeSkillPaths(fs, "user")
+    },
+    {
+      name: "Claude Code (project)",
+      ...getClaudeCodeSkillPaths(fs, "project")
+    },
+    {
+      name: "Codex (user)",
+      ...getCodexSkillPaths(fs, "user")
+    },
+    {
+      name: "Codex (project)",
+      ...getCodexSkillPaths(fs, "project")
+    }
+  ];
+  let foundAny = false;
+  let updatedAny = false;
+  for (const loc of locations) {
+    const exists = await fs.exists(loc.skillPath);
+    if (!exists)
+      continue;
+    foundAny = true;
+    const content = await fs.readFile(loc.skillPath);
+    const existingVersion = extractSkillVersion(content);
+    if (existingVersion === version) {
+      console.log(`${loc.name}: ${highlight(`v${version}`, useColors)} (current)`);
+      continue;
+    }
+    const result = await installSkill(fs, loc.skillDir, loc.skillPath);
+    if (result.success) {
+      console.log(`${loc.name}: ${dim(`v${existingVersion ?? "unknown"}`, useColors)} → ${highlight(`v${version}`, useColors)}`);
+      updatedAny = true;
+    } else {
+      console.log(error(`${loc.name}: Failed to update - ${result.error}`, useColors));
+    }
+  }
+  if (!foundAny) {
+    console.log(dim("No installed skills found.", useColors));
+    console.log(dim(`Run 'pkgseer skill init' to install the skill.
+`, useColors));
+    return;
+  }
+  if (updatedAny) {
+    console.log(success(`
+Skills updated successfully!`, useColors));
+  } else {
+    console.log(dim(`
+All skills are up to date.`, useColors));
+  }
+}
+var SKILL_INIT_DESCRIPTION = `Install PkgSeer as an agent skill for AI assistants.
+
+Skills provide package intelligence through natural language:
+  • Search code and documentation across packages
+  • Check security vulnerabilities and quality scores
+  • Compare packages and analyze dependencies
+
+Supports Claude Code and Codex CLI with user or project scope.`;
+var SKILL_UPDATE_DESCRIPTION = `Update installed PkgSeer skills to the latest version.
+
+Checks all installed skill locations and updates any that are outdated.`;
+function registerSkillCommand(program) {
+  const skillCmd = program.command("skill").summary("Manage PkgSeer agent skill").description("Install and manage PkgSeer as an agent skill for AI assistants.");
+  skillCmd.command("init").summary("Install skill for AI assistants").description(SKILL_INIT_DESCRIPTION).action(async () => {
+    const deps = await createContainer();
+    await skillInitAction({
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+  });
+  skillCmd.command("update").summary("Update installed skills").description(SKILL_UPDATE_DESCRIPTION).action(async () => {
+    const deps = await createContainer();
+    await skillUpdateAction({
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+  });
+}
+
 // src/commands/init.ts
 async function initAction(options, deps) {
   const useColors = shouldUseColors2();
@@ -3847,22 +4158,43 @@ async function initAction(options, deps) {
 `);
   console.log(`Set up PkgSeer for your project:
 ` + `  1. Project configuration – track dependencies and monitor vulnerabilities
-` + `  2. MCP server – enable AI assistant integration
+` + `  2. AI integration – enable AI assistant capabilities
 `);
-  console.log(dim(`Or run separately: pkgseer project init, pkgseer mcp init
+  console.log(dim(`Or run separately: pkgseer project init, pkgseer skill init, pkgseer mcp init
 `, useColors));
   let setupProject = !options.skipProject;
-  let setupMcp = !options.skipMcp;
-  if (options.skipProject && options.skipMcp) {
+  let aiIntegration = "none";
+  if (options.skipProject && options.skipMcp && options.skipSkill) {
     showCliUsage(useColors);
     return;
   }
-  if (!options.skipProject && !options.skipMcp) {
-    const choice = await deps.promptService.select("What would you like to set up?", [
+  const promptForAiIntegration = async () => {
+    return deps.promptService.select("Which AI integration would you like?", [
+      {
+        value: "skill",
+        name: "Skill (recommended for Claude Code / Codex)",
+        description: "Lightweight file-based integration, auto-triggers on package queries"
+      },
+      {
+        value: "mcp",
+        name: "MCP server (for Cursor / advanced use)",
+        description: "Structured tool integration via Model Context Protocol"
+      }
+    ]);
+  };
+  if (options.skipMcp && !options.skipSkill) {
+    aiIntegration = "skill";
+  } else if (!options.skipMcp && options.skipSkill) {
+    aiIntegration = "mcp";
+  } else if (options.skipMcp && options.skipSkill) {
+    aiIntegration = "none";
+  }
+  if (!options.skipProject && !options.skipMcp && !options.skipSkill) {
+    const setupChoice = await deps.promptService.select("What would you like to set up?", [
       {
-        value: "both",
-        name: "Both project and MCP server (recommended)",
-        description: "Full setup: dependency tracking + AI assistant integration"
+        value: "full",
+        name: "Project + AI integration (recommended)",
+        description: "Full setup: dependency tracking + AI assistant capabilities"
       },
       {
         value: "project",
@@ -3870,9 +4202,9 @@ async function initAction(options, deps) {
         description: "Track dependencies and monitor for vulnerabilities"
       },
       {
-        value: "mcp",
-        name: "MCP server only",
-        description: "Enable AI assistant integration"
+        value: "ai",
+        name: "AI integration only",
+        description: "Enable AI assistant capabilities"
       },
       {
         value: "cli",
@@ -3880,15 +4212,21 @@ async function initAction(options, deps) {
         description: "Use PkgSeer as a command-line tool"
       }
     ]);
-    if (choice === "cli") {
+    if (setupChoice === "cli") {
       showCliUsage(useColors);
       return;
     }
-    setupProject = choice === "both" || choice === "project";
-    setupMcp = choice === "both" || choice === "mcp";
+    setupProject = setupChoice === "full" || setupChoice === "project";
+    const setupAi = setupChoice === "full" || setupChoice === "ai";
+    if (setupAi) {
+      aiIntegration = await promptForAiIntegration();
+    }
+  } else if (!options.skipMcp && !options.skipSkill) {
+    aiIntegration = await promptForAiIntegration();
   }
   const projectInit = deps.projectInitAction ?? projectInitAction;
   const mcpInit = deps.mcpInitAction ?? mcpInitAction;
+  const skillInit = deps.skillInitAction ?? skillInitAction;
   if (setupProject) {
     const existingConfig = await deps.configService.loadProjectConfig();
     if (existingConfig?.config.project) {
@@ -3920,7 +4258,21 @@ ${highlight("✓", useColors)} Project setup complete!
       }
     }
   }
-  if (setupMcp) {
+  if (aiIntegration === "skill") {
+    console.log(`
+` + "=".repeat(50));
+    console.log("Skill Setup");
+    console.log("=".repeat(50) + `
+`);
+    await skillInit({
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+    console.log(`
+${highlight("✓", useColors)} Skill setup complete!
+`);
+  } else if (aiIntegration === "mcp") {
     const currentConfig = await deps.configService.loadProjectConfig();
     const hasProjectNow = currentConfig?.config.project !== undefined;
     console.log(`
@@ -3951,15 +4303,18 @@ ${highlight("✓", useColors)} MCP setup complete!
       console.log(dim(`  View at: ${deps.baseUrl}/projects/${finalConfig.config.project}`, useColors));
     }
   }
-  if (setupMcp) {
-    console.log("MCP Server: Configured");
+  if (aiIntegration === "skill") {
+    console.log("AI Integration: Skill installed");
+    console.log(dim("  The skill is available immediately.", useColors));
+  } else if (aiIntegration === "mcp") {
+    console.log("AI Integration: MCP server configured");
     console.log(dim("  Restart your AI assistant to activate the MCP server.", useColors));
   }
   console.log(dim(`
 Next steps:
 ` + `  • Use CLI commands: pkgseer pkg info <package>
-` + `  • Search docs: pkgseer docs search <query>
-` + "  • Quick reference: pkgseer quickstart", useColors));
+` + `  • Search packages: pkgseer search <query> -P <packages>
+` + "  • Search project docs: pkgseer docs search <query>", useColors));
 }
 function showCliUsage(useColors) {
   console.log("Using PkgSeer via CLI");
@@ -3984,13 +4339,13 @@ function showCliUsage(useColors) {
 ` + "Tip: Run 'pkgseer quickstart' for a quick reference guide.", useColors));
 }
 function registerInitCommand(program) {
-  program.command("init").summary("Set up project and MCP server").description(`Set up PkgSeer for your project.
+  program.command("init").summary("Set up project and AI integration").description(`Set up PkgSeer for your project.
 
 Guides you through:
   • Project configuration – track dependencies, monitor vulnerabilities
-  • MCP server – enable AI assistant integration
+  • AI integration – skill or MCP server for AI assistants
 
-Run separately: pkgseer project init, pkgseer mcp init`).option("--skip-project", "Skip project setup").option("--skip-mcp", "Skip MCP setup").action(async (options) => {
+Run separately: pkgseer project init, pkgseer skill init, pkgseer mcp init`).option("--skip-project", "Skip project setup").option("--skip-mcp", "Skip MCP setup (use skill instead)").option("--skip-skill", "Skip skill setup (use MCP instead)").action(async (options) => {
     const deps = await createContainer();
     await initAction(options, deps);
   });
@@ -5665,103 +6020,13 @@ function registerProjectUploadCommand(program) {
     });
   });
 }
-// src/commands/quickstart.ts
-var QUICKSTART_TEXT = `# PkgSeer CLI - Quick Reference for AI Agents
-
-PkgSeer provides package intelligence for npm, PyPI, and Hex registries.
-
-## Package Commands (pkgseer pkg)
-
-### Get package info
-\`pkgseer pkg info <package> [-r npm|pypi|hex] [--json]\`
-Returns: metadata, versions, security advisories, quickstart
-
-### Check quality score
-\`pkgseer pkg quality <package> [-r registry] [-v pkg-version] [--json]\`
-Returns: overall score, category breakdown, rule details
-
-### List dependencies
-\`pkgseer pkg deps <package> [-r registry] [-v pkg-version] [-t] [-d depth] [--json]\`
-Returns: direct deps, transitive count, dependency tree (with -t)
-
-### Check vulnerabilities
-\`pkgseer pkg vulns <package> [-r registry] [-v pkg-version] [--json]\`
-Returns: CVEs, severity, affected versions, upgrade guidance
-
-### Compare packages
-\`pkgseer pkg compare <pkg1> <pkg2> [...] [--json]\`
-Format: [registry:]name[@version] (e.g., npm:lodash, pypi:requests@2.31.0)
-Returns: side-by-side quality, downloads, vulnerabilities
-
-## Documentation Commands (pkgseer docs)
-
-### List doc pages
-\`pkgseer docs list <package> [-r registry] [-v pkg-version] [--json]\`
-Returns: page titles, IDs (slugs), word counts
-
-### Get doc page
-\`pkgseer docs get <package>/<page-id> [<package>/<page-id> ...] [-r registry] [-v pkg-version] [--json]\`
-Returns: full page content (markdown), breadcrumbs, source URL
-Supports multiple pages: \`pkgseer docs get express/readme express/api\`
-
-### Search docs
-\`pkgseer docs search "<query>" [-p package] [-r registry] [--json]\`
-\`pkgseer docs search --keywords term1,term2 [-s] [-l limit]\`
-Default: searches project docs (if project configured)
-With -p: searches specific package docs
-Returns: ranked results with relevance scores
-
-## Tips for AI Agents
-
-1. Use \`--json\` for structured data parsing
-2. Default registry is npm; use \`-r pypi\` or \`-r hex\` for others
-3. Version defaults to latest; use \`-v <version>\` for specific version
-4. For docs search, configure project in pkgseer.yml for project-wide search
-5. Compare up to 10 packages at once with \`pkg compare\`
-
-## MCP Server
-
-For Model Context Protocol integration:
-\`pkgseer mcp\`
-
-Add to MCP config:
-{
-  "pkgseer": {
-    "command": "pkgseer",
-    "args": ["mcp"]
-  }
-}
-`;
-function quickstartAction(options) {
-  if (options.json) {
-    console.log(JSON.stringify({
-      version,
-      quickstart: QUICKSTART_TEXT
-    }));
-  } else {
-    console.log(QUICKSTART_TEXT);
-  }
-}
-var QUICKSTART_DESCRIPTION = `Show quick reference for AI agents.
-
-Displays a concise guide to pkgseer CLI commands optimized
-for LLM agents. Includes command syntax, options, and tips
-for effective usage.
-
-Use --json for structured output.`;
-function registerQuickstartCommand(program) {
-  program.command("quickstart").summary("Show quick reference for AI agents").description(QUICKSTART_DESCRIPTION).option("--json", "Output as JSON").action((options) => {
-    quickstartAction(options);
-  });
-}
-
 // src/cli.ts
 var program = new Command;
 program.name("pkgseer").description("Package intelligence for your AI assistant").version(version).addHelpText("after", `
 Getting started:
-  pkgseer init         Interactive setup wizard (project + MCP)
+  pkgseer init         Interactive setup wizard (project + AI)
   pkgseer login        Authenticate with your account
-  pkgseer quickstart   Quick reference for AI agents
+  pkgseer skill init   Install AI agent skill
 
 Package commands:
   pkgseer pkg info <package>      Get package summary
@@ -5778,9 +6043,9 @@ Documentation commands:
 Learn more at https://pkgseer.dev`);
 registerInitCommand(program);
 registerMcpCommand(program);
+registerSkillCommand(program);
 registerLoginCommand(program);
 registerLogoutCommand(program);
-registerQuickstartCommand(program);
 var auth = program.command("auth").description("View and manage authentication");
 registerAuthStatusCommand(auth);
 var config = program.command("config").description("View and manage configuration");

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-1m9g9ehr.js";
+} from "./shared/chunk-9016p6c6.js";
 export {
   version
 };

package/dist/shared/{chunk-1m9g9ehr.js → chunk-9016p6c6.js}

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