skillrepo 2.0.0 → 3.0.0

package/bin/skillrepo.mjs

@@ -1,46 +1,220 @@
 #!/usr/bin/env node
 
 /**
- * SkillRepo CLI — Set up SkillRepo in any IDE, one command.
+ * SkillRepo CLI — pull-based command dispatcher (#674, part of #646).
  *
- * Usage:
- *   npx skillrepo init [--key <key>] [--url <url>] [--yes]
+ * Routes seven commands: init, update, get, add, remove, list, search.
+ *
+ * PR1 ships only the dispatcher; command modules other than init are
+ * stubbed and exit with a "not yet implemented" message. The existing
+ * v2.0.0 init flow continues to work via the runInit import below until
+ * PR3b rewrites it. This keeps the existing cli-init E2E test green
+ * throughout the rewrite.
+ *
+ * Global flags (parsed once, passed to every command):
+ *   --help, -h        Print help (top-level or per-command)
+ *   --version, -v     Print package version
+ *   --verbose         Print stack traces on error
+ *
+ * Per-command flags are parsed inside each command module.
+ *
+ * Exit codes are defined in src/lib/errors.mjs.
  */
 
 import { runInit } from "../src/commands/init.mjs";
+import { runUpdate } from "../src/commands/update.mjs";
+import { runGet } from "../src/commands/get.mjs";
+import { runAdd } from "../src/commands/add.mjs";
+import { runRemove } from "../src/commands/remove.mjs";
+import { runList } from "../src/commands/list.mjs";
+import { runSearch } from "../src/commands/search.mjs";
+import { CliError, EXIT_OK, EXIT_VALIDATION } from "../src/lib/errors.mjs";
+
+// ── Command registry ────────────────────────────────────────────────────
+
+/**
+ * Each command has a `description` (one-liner shown in top-level --help),
+ * an optional `usage` example, and a `run(argv)` async function.
+ *
+ * Stub commands print a "not yet implemented" message and exit
+ * EXIT_VALIDATION. They will be filled in by sibling PRs (PR2 + PR3a + PR3b).
+ */
+const COMMANDS = {
+  init: {
+    description: "Validate access key, configure detected IDEs, and run first sync",
+    usage: "skillrepo init [--key <key>] [--url <url>] [--yes]",
+    run: async (argv) => runInit(argv),
+  },
+  update: {
+    description: "Sync your library against the registry (delta + tombstones)",
+    usage: "skillrepo update [--global] [--ide <list>] [--json]",
+    run: async (argv) => runUpdate(argv),
+  },
+  get: {
+    description: "Fetch a single skill and write it to disk (no library mutation)",
+    usage: "skillrepo get <@owner/name> [--global] [--ide <list>] [--json]",
+    run: async (argv) => runGet(argv),
+  },
+  add: {
+    description: "Add a skill to your library and pull it locally",
+    usage: "skillrepo add <@owner/name> [--global] [--ide <list>] [--json]",
+    run: async (argv) => runAdd(argv),
+  },
+  remove: {
+    description: "Remove a skill from your library and delete it locally",
+    usage: "skillrepo remove <@owner/name> [--global] [--ide <list>] [--json]",
+    run: async (argv) => runRemove(argv),
+  },
+  list: {
+    description: "List skills in your library as a table",
+    usage: "skillrepo list [--json]",
+    run: async (argv) => runList(argv),
+  },
+  search: {
+    description: "Search the public registry by keyword",
+    usage: "skillrepo search <query> [--limit <n>] [--json] [--semantic]",
+    run: async (argv) => runSearch(argv),
+  },
+};
+
+const COMMAND_NAMES = Object.keys(COMMANDS);
+
+// ── Top-level dispatch ──────────────────────────────────────────────────
+// (moved to the BOTTOM of the file so the color helpers + COMMANDS map
+// are fully initialized before main() runs — otherwise the temporal
+// dead zone fires when main() reaches printTopLevelHelp())
+
+async function main(command, fullArgv) {
+  // No command + no args → print top-level help
+  if (!command) {
+    printTopLevelHelp();
+    process.exit(EXIT_OK);
+  }
+
+  // Top-level flags before any command
+  if (command === "--help" || command === "-h") {
+    printTopLevelHelp();
+    process.exit(EXIT_OK);
+  }
+  if (command === "--version" || command === "-v") {
+    await printVersion();
+    process.exit(EXIT_OK);
+  }
+
+  // Unknown command (anything that starts with - and isn't a known flag)
+  if (!COMMANDS[command]) {
+    process.stderr.write(`\n  ${red("Error:")} Unknown command "${command}"\n`);
+    process.stderr.write(`  Run ${bold("skillrepo --help")} to see available commands.\n\n`);
+    process.exit(EXIT_VALIDATION);
+  }
+
+  // Per-command --help short-circuit
+  const rest = fullArgv.slice(1);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    printCommandHelp(command);
+    process.exit(EXIT_OK);
+  }
+
+  await COMMANDS[command].run(rest);
+}
+
+// ── Help printing ───────────────────────────────────────────────────────
+
+function printTopLevelHelp() {
+  process.stdout.write(`
+  ${bold("SkillRepo CLI")} ${dim("— pull-based agent skills")}
+
+  ${bold("Usage:")}
+    skillrepo <command> [options]
 
-const args = process.argv.slice(2);
-const command = args[0];
-
-if (!command || command === "init") {
-  runInit(args.slice(command === "init" ? 1 : 0)).catch((err) => {
-    console.error(`\n  Error: ${err.message}\n`);
-    process.exit(1);
-  });
-} else if (command === "--help" || command === "-h") {
-  console.log(`
-  SkillRepo CLI
-
-  Usage:
-    npx skillrepo init [options]
-
-  Options:
-    --key, -k <key>    Access key (or set SKILLREPO_ACCESS_KEY env var)
-    --url, -u <url>    SkillRepo URL (default: https://skillrepo.dev)
-    --yes, -y          Non-interactive mode
-
-  Examples:
-    npx skillrepo init
-    npx skillrepo init --key sk_live_abc123
-    npx skillrepo init --url https://my-skillrepo.com --yes
+  ${bold("Commands:")}
 `);
-} else if (command === "--version" || command === "-v") {
-  // Read version from package.json
-  import("../package.json", { with: { type: "json" } })
-    .then((pkg) => console.log(pkg.default.version))
-    .catch(() => console.log("1.0.0"));
-} else {
-  console.error(`  Unknown command: ${command}`);
-  console.error(`  Run "npx skillrepo --help" for usage.`);
-  process.exit(1);
+  const longest = Math.max(...COMMAND_NAMES.map((n) => n.length));
+  for (const name of COMMAND_NAMES) {
+    const padding = " ".repeat(longest - name.length + 4);
+    process.stdout.write(`    ${bold(name)}${padding}${COMMANDS[name].description}\n`);
+  }
+  process.stdout.write(`
+  ${bold("Global options:")}
+    --help, -h        Print help
+    --version, -v     Print package version
+    --verbose         Print stack traces on error
+
+  Run ${bold("skillrepo <command> --help")} for command-specific options.
+
+`);
+}
+
+function printCommandHelp(name) {
+  const cmd = COMMANDS[name];
+  process.stdout.write(`
+  ${bold(`skillrepo ${name}`)} ${dim("— ")}${cmd.description}
+
+  ${bold("Usage:")}
+    ${cmd.usage}
+
+`);
+}
+
+async function printVersion() {
+  // ESM JSON imports require the import attribute; behind a try/catch
+  // so a missing package.json doesn't blow up the binary.
+  try {
+    const pkg = await import("../package.json", { with: { type: "json" } });
+    process.stdout.write(`${pkg.default.version}\n`);
+  } catch {
+    process.stdout.write("unknown\n");
+  }
 }
+
+// The `stub()` factory that returned a "not yet implemented" function
+// for unwired commands is gone — all 7 commands have real
+// implementations as of PR3a. If a future command needs to ship as
+// a stub, reintroduce the factory from git history (PR1 + PR2 era).
+
+// ── Color helpers (duplicate of prompt.mjs to avoid an import for the dispatcher) ──
+
+const isTTY = process.stdout.isTTY && !process.env.NO_COLOR;
+function red(s) { return isTTY ? `\x1b[31m${s}\x1b[0m` : s; }
+function bold(s) { return isTTY ? `\x1b[1m${s}\x1b[0m` : s; }
+function dim(s) { return isTTY ? `\x1b[2m${s}\x1b[0m` : s; }
+
+// ── Entry point ─────────────────────────────────────────────────────────
+// Must be at the very bottom: main() calls printTopLevelHelp() which
+// references red/bold/dim above. Putting this at the top would hit the
+// const temporal dead zone before those declarations execute.
+
+const argv = process.argv.slice(2);
+const first = argv[0];
+
+// Thread --verbose into an env var so http.mjs can surface retry
+// attempts without every command needing to pass the flag through
+// to safeFetch. This env var is read by `resolveRetryOptions` in
+// http.mjs and defaults to silent (pre-existing behavior) when
+// unset. The dispatcher is the only writer, so there's no conflict
+// with users who set SKILLREPO_VERBOSE in their own shell.
+const verbose = argv.includes("--verbose");
+if (verbose) {
+  process.env.SKILLREPO_VERBOSE = "1";
+}
+
+main(first, argv).catch((err) => {
+  // CliError carries an exitCode and an optional hint. Plain errors
+  // exit 1 with their message — unknown errors are treated as
+  // transient/network per the documented exit-code matrix.
+  const isCliError = err instanceof CliError;
+  const exitCode = isCliError ? err.exitCode : 1;
+
+  process.stderr.write(`\n  ${red("Error:")} ${err.message}\n`);
+  if (isCliError && err.hint) {
+    process.stderr.write(`  ${dim(err.hint)}\n`);
+  }
+  if (verbose && err.stack) {
+    process.stderr.write(`\n${err.stack}\n`);
+    if (err.cause && err.cause.stack) {
+      process.stderr.write(`\nCaused by:\n${err.cause.stack}\n`);
+    }
+  }
+  process.stderr.write("\n");
+  process.exit(exitCode);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skillrepo",
-  "version": "2.0.0",
-  "description": "Set up SkillRepo in any IDE — one command",
+  "version": "3.0.0",
+  "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {
     "skillrepo": "./bin/skillrepo.mjs"
@@ -16,5 +16,8 @@
     "directory": "packages/cli"
   },
   "keywords": ["skillrepo", "cli", "mcp", "ai-skills"],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "cli-table3": "^0.6.5"
+  }
 }

package/src/commands/add.mjs

@@ -0,0 +1,176 @@
+/**
+ * `skillrepo add <@owner/name>` (#676).
+ *
+ * Adds a skill to the authenticated account's library AND pulls it
+ * locally in one command. Two-step flow:
+ *
+ *   1. POST /api/v1/library { owner, name }
+ *   2. GET /api/v1/skills/{owner}/{name} → writeSkillDir
+ *
+ * Why a direct GET instead of calling sync.mjs with `since`:
+ *
+ *   - The architect's review on PR2 explicitly recommended this. A
+ *     sync with `since=lastSync.syncedAt` can miss the newly-added
+ *     skill under clock skew (server and client clocks disagreeing,
+ *     or both calls landing in the same second).
+ *   - The direct GET is also simpler and has no dependency on the
+ *     persistent last-sync state file.
+ *
+ * Idempotent semantics:
+ *
+ *   - 201 added → POST succeeded, now write the files locally
+ *   - 409 already-in-library → NOT an error; the server didn't
+ *     insert, but we still want the local files. Re-fetch + write
+ *     anyway so a user running `add` twice (e.g., after a local
+ *     cleanup that dropped the skill from disk) gets the skill
+ *     back on disk.
+ *   - 404 not-found → clean error, exit 5
+ *   - 409 self-ownership → clean error, exit 5 ("you can't add your
+ *     own skill to your own library")
+ *   - 403 plan-limit → validationError (via http.mjs) with billing hint
+ *   - 403 scope → scopeError (via http.mjs) with write-key hint
+ *
+ * Flags: --global / --ide / --json / --key / --url
+ * Positional: <@owner/name>
+ */
+
+import { addSkillToLibrary, getSkill } from "../lib/http.mjs";
+import { writeSkillDir, cleanupOrphans } from "../lib/file-write.mjs";
+import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `add`. Throws CliError on failure.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runAdd(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  let identifier = null;
+
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg) {
+      if (identifier !== null) {
+        throw validationError(
+          `Unexpected extra argument: ${arg}`,
+          { hint: "Pass exactly one @owner/name." },
+        );
+      }
+      identifier = arg;
+      return 1;
+    },
+  });
+
+  if (!identifier) {
+    throw validationError("Missing skill identifier.", {
+      hint: "Usage: skillrepo add <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const vendors = effectiveVendors(flags);
+
+  // Pre-flight: clean orphans from prior crashes (same pattern as get.mjs)
+  cleanupOrphans({ vendors, global: flags.global });
+
+  // Step 1: POST /api/v1/library
+  const addResult = await addSkillToLibrary(flags.serverUrl, flags.apiKey, owner, name);
+
+  // Map documented outcomes to user-facing behavior
+  if (addResult.status === "not-found") {
+    throw validationError(`Skill ${formatIdentifier({ owner, name })} not found.`, {
+      hint: "Browse the catalog at /skills or run `skillrepo search <query>`.",
+    });
+  }
+  if (addResult.status === "self-ownership") {
+    throw validationError(
+      `Cannot add your own skill ${formatIdentifier({ owner, name })} to your library.`,
+      { hint: "Your own skills are already accessible — no need to add them." },
+    );
+  }
+
+  // "added" and "already-in-library" both proceed to the write step.
+  // The idempotency model is: the user asked for the skill on disk,
+  // we put it there, regardless of whether the library row was
+  // newly inserted or already existed.
+  const wasNewlyAdded = addResult.status === "added";
+
+  // Step 2: GET /api/v1/skills/{owner}/{name} + writeSkillDir
+  const skill = await getSkill(flags.serverUrl, flags.apiKey, owner, name);
+
+  if (!skill) {
+    // This is a server-side inconsistency: the POST succeeded (or
+    // reported "already in library") but the single-skill GET
+    // returned 404. Most likely causes: the skill was deleted or
+    // moderated between the POST and the GET, or there's a visibility
+    // race. Surface as a typed error rather than silently writing
+    // nothing.
+    throw validationError(
+      `Skill ${formatIdentifier({ owner, name })} was added to your library but the fetch returned 404. ` +
+        `Try running \`skillrepo update\` to re-sync.`,
+    );
+  }
+
+  // Defense in depth: same check as get.mjs — reject a server-side
+  // mismatch where the returned skill doesn't match the requested
+  // identifier.
+  if (skill.name !== name || skill.owner !== owner) {
+    throw validationError(
+      `Server returned wrong skill: requested ${formatIdentifier({ owner, name })}, got @${skill.owner}/${skill.name}`,
+    );
+  }
+
+  if (skill.filesIncomplete) {
+    // The POST already succeeded — the skill is in the user's
+    // library on the server side. We refuse to write partial files
+    // locally because the SKILL.md body likely references files
+    // that weren't inlined, so any agent reading it would hit
+    // broken resource references. The recovery path is to wait
+    // for the server to resolve the inline issue (transient blob
+    // storage failure) and retry via `skillrepo update` OR
+    // `skillrepo add` again.
+    throw validationError(
+      `Skill ${formatIdentifier({ owner, name })} was added to your library but the server returned an incomplete payload — some files failed to inline.`,
+      {
+        hint:
+          "This is usually transient. Run `skillrepo update` to retry the fetch once the issue is resolved.",
+      },
+    );
+  }
+
+  writeSkillDir(skill, { vendors, global: flags.global });
+
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          action: wasNewlyAdded ? "added" : "already-in-library",
+          owner,
+          name,
+          version: skill.version,
+          filesWritten: skill.files.length,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  const where = flags.global
+    ? "personal (~/.claude/skills/)"
+    : "project (.claude/skills/)";
+  if (wasNewlyAdded) {
+    stdout.write(
+      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} files) → ${where}\n\n`,
+    );
+  } else {
+    stdout.write(
+      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} files) → ${where}\n\n`,
+    );
+  }
+}

package/src/commands/get.mjs

@@ -0,0 +1,116 @@
+/**
+ * `skillrepo get <@owner/name>` (#672).
+ *
+ * One-shot single-skill fetch. Hits GET /api/v1/skills/{owner}/{name}
+ * and writes the result via `writeSkillDir`. Does NOT mutate the
+ * library — the user is installing for a specific project or ad-hoc
+ * test. Collisions with library skills are documented as a no-op
+ * (the next `update` will overwrite from the library version).
+ *
+ * Flags (via resolveFlags):
+ *   --global         Write to ~/.claude/skills/ instead of project-local
+ *   --ide <list>     Comma-separated vendor list
+ *   --key/--url      Override credentials
+ *
+ * Positional:
+ *   <@owner/name>    The skill identifier (with or without the @)
+ *
+ * Exit codes:
+ *   0  success
+ *   1  network failure
+ *   2  auth failure
+ *   3  disk failure
+ *   4  scope failure (read-only key — should not happen, but mapped if it does)
+ *   5  validation failure (bad identifier, malformed flags)
+ */
+
+import { getSkill } from "../lib/http.mjs";
+import { writeSkillDir, cleanupOrphans } from "../lib/file-write.mjs";
+import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `get`. Throws CliError on any failure.
+ *
+ * @param {string[]} argv
+ * @param {object} [io] - Optional injected streams for testability.
+ *        Defaults to process.stdout/stderr.
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runGet(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  let identifier = null;
+
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg) {
+      if (identifier !== null) {
+        throw validationError(
+          `Unexpected extra argument: ${arg}`,
+          { hint: "Pass exactly one @owner/name." },
+        );
+      }
+      identifier = arg;
+      return 1; // consume one arg
+    },
+  });
+
+  if (!identifier) {
+    throw validationError("Missing skill identifier.", {
+      hint: "Usage: skillrepo get <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const vendors = effectiveVendors(flags);
+
+  // Pre-flight: clean orphans from prior crashes before any new write
+  cleanupOrphans({ vendors, global: flags.global });
+
+  const skill = await getSkill(flags.serverUrl, flags.apiKey, owner, name);
+
+  if (!skill) {
+    throw validationError(`Skill ${formatIdentifier({ owner, name })} not found.`, {
+      hint: "Browse the catalog at /skills or run `skillrepo search <query>`.",
+    });
+  }
+
+  // Defense in depth: server-returned `name` should already match
+  // the requested name, but a malicious or buggy server could send
+  // a different one. Our writeSkillDir validates frontmatter `name`
+  // matches the directory name; this catches the case where the
+  // SERVER's `name` field disagrees with the requested name.
+  if (skill.name !== name || skill.owner !== owner) {
+    throw validationError(
+      `Server returned wrong skill: requested ${formatIdentifier({ owner, name })}, got @${skill.owner}/${skill.name}`,
+    );
+  }
+
+  if (skill.filesIncomplete) {
+    throw validationError(
+      `Skill ${formatIdentifier({ owner, name })} returned an incomplete payload from the server.`,
+      { hint: "One or more files failed to inline. Try again later or contact support." },
+    );
+  }
+
+  writeSkillDir(skill, { vendors, global: flags.global });
+
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify({
+        action: "fetched",
+        owner,
+        name,
+        version: skill.version,
+        filesWritten: skill.files.length,
+      }, null, 2) + "\n",
+    );
+    return;
+  }
+
+  const where = flags.global ? "personal (~/.claude/skills/)" : "project (.claude/skills/)";
+  stdout.write(
+    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} files) → ${where}\n\n`,
+  );
+}