skillrepo 2.0.0 → 3.0.0

package/src/commands/list.mjs

@@ -0,0 +1,176 @@
+/**
+ * `skillrepo list` (#679).
+ *
+ * Lists the authenticated account's library contents. Default output
+ * is a human-readable table via `cli-table3`. `--json` flag prints
+ * the raw metadata array for piping into `jq` or other tools.
+ *
+ * Calls GET /api/v1/library and ignores the inlined file content —
+ * we only need metadata for display. There is no metadata-only
+ * endpoint; reading the full library payload is the cost of reusing
+ * the same route the sync engine uses.
+ *
+ * Flags:
+ *   --json           Pipe-friendly JSON output
+ *   --key/--url      Override credentials
+ *
+ * No --global / --ide flags — `list` is a library-state inspector,
+ * not a writer.
+ */
+
+import Table from "cli-table3";
+
+import { getLibrary } from "../lib/http.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { formatIdentifier } from "../lib/identifier.mjs";
+
+/**
+ * Run `list`. Throws CliError on any failure.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runList(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const flags = resolveFlags(argv);
+
+  const result = await getLibrary(flags.serverUrl, flags.apiKey);
+
+  // `list` does not care about removals or sync state — we just want
+  // the current set. Skills are returned by the same endpoint as the
+  // sync, but with full file content we discard.
+  //
+  // Defensive guard: `list` calls getLibrary without an If-None-Match
+  // header so it can't legitimately receive a 304 today. But getLibrary's
+  // contract documents `notModified: true` as a possible return shape,
+  // and a future refactor that adds caching at this layer could
+  // accidentally start sending the header. Treat `result.skills` as
+  // possibly empty rather than possibly undefined.
+  const skills = Array.isArray(result.skills) ? result.skills : [];
+
+  if (flags.json) {
+    stdout.write(JSON.stringify(formatJson(skills), null, 2) + "\n");
+    return;
+  }
+
+  if (skills.length === 0) {
+    stdout.write(
+      "\n  Your library is empty.\n  Use `skillrepo add <@owner/name>` to add a skill.\n\n",
+    );
+    return;
+  }
+
+  printTable(skills, stdout);
+}
+
+/**
+ * Read the column width from the active output stream, falling back
+ * to process.stdout's TTY column count if the injected stream
+ * doesn't carry one (e.g., a test capture stream), then to a 100-col
+ * default for non-TTY contexts. Reading from `out.columns` first
+ * means a future test that injects a stream advertising a specific
+ * width will be honored.
+ */
+function streamColumns(out) {
+  if (out && typeof out.columns === "number" && out.columns > 0) {
+    return out.columns;
+  }
+  if (process.stdout.columns && process.stdout.columns > 0) {
+    return process.stdout.columns;
+  }
+  return 100;
+}
+
+/**
+ * Strip file content and reduce to the JSON shape that scripts care
+ * about. Kept stable as a public-ish contract for `--json` consumers.
+ */
+function formatJson(skills) {
+  return skills
+    .slice()
+    .sort(sortByOwnerAndName)
+    .map((s) => ({
+      owner: s.owner,
+      name: s.name,
+      version: s.version,
+      description: s.description,
+      updatedAt: s.updatedAt,
+      filesIncomplete: s.filesIncomplete ?? false,
+    }));
+}
+
+function printTable(skills, out) {
+  const sorted = skills.slice().sort(sortByOwnerAndName);
+
+  // cli-table3 supports word wrapping but we manually truncate
+  // descriptions so the table stays readable on standard 80-col
+  // terminals. The full description is available via --json.
+  const table = new Table({
+    head: ["Skill", "Version", "Updated", "Description"],
+    colWidths: computeColWidths(streamColumns(out)),
+    wordWrap: true,
+    style: { head: ["bold"] },
+  });
+
+  for (const s of sorted) {
+    table.push([
+      formatIdentifier(s),
+      s.version || "—",
+      formatRelativeDate(s.updatedAt),
+      truncate(s.description || "", 60),
+    ]);
+  }
+
+  out.write("\n" + table.toString() + "\n\n");
+  out.write(`  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library.\n\n`);
+}
+
+function computeColWidths(terminalColumns) {
+  // Cap at 120 so the table doesn't get unreadably wide on
+  // ultra-wide terminals; floor at 100 so the description still has
+  // room when the terminal is narrower than typical.
+  const total = terminalColumns > 60 ? Math.min(terminalColumns, 120) : 100;
+  // Skill ~30, version ~10, updated ~14, description gets the rest
+  const skillCol = 32;
+  const versionCol = 12;
+  const updatedCol = 14;
+  const descCol = Math.max(20, total - skillCol - versionCol - updatedCol - 6); // -6 for borders
+  return [skillCol, versionCol, updatedCol, descCol];
+}
+
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + "…";
+}
+
+/**
+ * Render an ISO timestamp as a relative human-friendly string.
+ * Falls back to the date if it's older than ~6 months.
+ */
+function formatRelativeDate(iso) {
+  if (!iso) return "—";
+  const ts = new Date(iso).getTime();
+  if (!Number.isFinite(ts)) return "—";
+  const now = Date.now();
+  const seconds = Math.floor((now - ts) / 1000);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 26) return `${weeks}w ago`;
+  // Older than ~6 months: fall back to a date
+  return new Date(iso).toISOString().slice(0, 10);
+}
+
+function sortByOwnerAndName(a, b) {
+  const ao = a.owner || "";
+  const bo = b.owner || "";
+  if (ao !== bo) return ao.localeCompare(bo);
+  return (a.name || "").localeCompare(b.name || "");
+}

package/src/commands/remove.mjs

@@ -0,0 +1,167 @@
+/**
+ * `skillrepo remove <@owner/name>` (#678).
+ *
+ * Removes a skill from the authenticated account's library AND
+ * deletes the local files in one command. Two-step flow:
+ *
+ *   1. DELETE /api/v1/library/{owner}/{name}
+ *   2. removeSkillDir(name) — direct local delete across all
+ *      configured placement targets
+ *
+ * Why direct local delete instead of calling sync.mjs to process
+ * the tombstone:
+ *
+ *   - The server's ETag computation does NOT currently factor in
+ *     `libraryRemovals`, so a conditional sync after the DELETE
+ *     would return 304 and the CLI would never see the tombstone.
+ *     The CLI would leave the orphaned skill files on disk until
+ *     some unrelated mutation bumps the ETag. This is documented
+ *     in follow-up #875.
+ *   - A direct local delete avoids that problem entirely. Since
+ *     `remove` is called with a specific (owner, name) the CLI
+ *     already knows exactly what to delete — there's no reason to
+ *     go through a tombstone round-trip.
+ *   - Cross-machine remove still works via the tombstone-on-server
+ *     path (once #875 lands); `remove` just short-circuits the
+ *     single-machine case.
+ *
+ * Idempotent semantics:
+ *
+ *   - 200 removed → DELETE succeeded, now wipe local files
+ *   - 404 not-in-library → NOT an error; the skill wasn't in the
+ *     library anyway. Still wipe local files (the user asked for
+ *     the skill to be gone from disk — if they have stale local
+ *     copies from a prior manual checkout or from another machine,
+ *     clean them up anyway). This matches the "user intent is the
+ *     authoritative request" principle.
+ *   - 403 scope → scopeError (via http.mjs) with write-key hint
+ *   - 401 → authError
+ *
+ * Flags: --global / --ide / --json / --key / --url
+ * Positional: <@owner/name>
+ */
+
+import { removeSkillFromLibrary } from "../lib/http.mjs";
+import { removeSkillDir, 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 `remove`. 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 runRemove(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 remove <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const vendors = effectiveVendors(flags);
+
+  // Pre-flight: clean any .old/ orphans from a prior crashed write.
+  // `remove` isn't writing new files, but it IS deleting, and the
+  // asymmetric behavior of "get/add/update clean orphans but remove
+  // doesn't" was flagged in review. Cleanup is idempotent and
+  // preserves any .tmp/ with a missing live target (Windows recovery
+  // invariant — see cleanupOrphans' comment block).
+  cleanupOrphans({ vendors, global: flags.global });
+
+  // Step 1: DELETE /api/v1/library/{owner}/{name}
+  const removeResult = await removeSkillFromLibrary(
+    flags.serverUrl,
+    flags.apiKey,
+    owner,
+    name,
+  );
+
+  // Both "removed" and "not-in-library" proceed to the local delete.
+  // The user asked for the skill to be gone; we honor that regardless
+  // of whether the library row was there to begin with.
+  const wasRemovedFromLibrary = removeResult.status === "removed";
+
+  // Step 2: delete local files via removeSkillDir. Passes `name` only
+  // (not owner) — the CLI places skills by name alone, matching
+  // sync.mjs's tombstone loop. See the comment there for the future
+  // owner-namespacing caveat.
+  const localResult = removeSkillDir(name, { vendors, global: flags.global });
+
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          action: wasRemovedFromLibrary ? "removed" : "not-in-library",
+          owner,
+          name,
+          libraryUpdated: wasRemovedFromLibrary,
+          localDirsRemoved: localResult.removed.length,
+          localDirsNotFound: localResult.notFound.length,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  // Human-readable summary. Four possible shapes:
+  //
+  //   1. Library updated + local files existed:
+  //      "✓ Removed @a/b from library and deleted N local dirs"
+  //   2. Library updated + no local files:
+  //      "✓ Removed @a/b from library (no local files found)"
+  //   3. Not in library + local files existed:
+  //      "✓ @a/b wasn't in your library; deleted N orphaned local dirs"
+  //   4. Not in library + no local files:
+  //      "• @a/b wasn't in your library and no local files existed — nothing to do"
+  const ident = formatIdentifier({ owner, name });
+  const localCount = localResult.removed.length;
+
+  if (wasRemovedFromLibrary && localCount > 0) {
+    stdout.write(
+      `\n  ✓ Removed ${ident} from your library and deleted ${localCount} local director${localCount === 1 ? "y" : "ies"}\n\n`,
+    );
+  } else if (wasRemovedFromLibrary) {
+    stdout.write(
+      `\n  ✓ Removed ${ident} from your library (no local files found)\n\n`,
+    );
+  } else if (localCount > 0) {
+    // The skill wasn't in the library but local files DID exist.
+    // These could be leftover from a prior `remove` that crashed
+    // after the DELETE but before the local delete, OR manually-
+    // placed files the user dropped into `.claude/skills/<name>/`
+    // outside the CLI. Either way, the user asked for this skill
+    // to be gone; we delete. We avoid the word "orphaned" in the
+    // message because it implies CLI-managed state, which may not
+    // be the case.
+    stdout.write(
+      `\n  ✓ ${ident} wasn't in your library — deleted ${localCount} local director${localCount === 1 ? "y" : "ies"} that matched the name\n\n`,
+    );
+  } else {
+    stdout.write(
+      `\n  • ${ident} wasn't in your library and no local files existed — nothing to do\n\n`,
+    );
+  }
+}

package/src/commands/search.mjs

@@ -0,0 +1,188 @@
+/**
+ * `skillrepo search <query>` (#677).
+ *
+ * Hits GET /api/v1/skills/search via the account-key authenticated
+ * route (NOT the catalog API). Renders results as a `cli-table3`
+ * table by default, or as JSON with `--json`.
+ *
+ * Flags:
+ *   --limit <n>      Max results to return (default 20, max 100)
+ *   --json           Pipe-friendly JSON
+ *   --semantic       No-op in v1; reserved for v1.1 semantic search
+ *                    (documented in --help; sending the flag does not
+ *                    error so v1.0 users can still preview the future
+ *                    behavior without a CLI upgrade)
+ *   --key/--url      Override credentials
+ *
+ * Positional:
+ *   <query>          Free text search query (single argument; quote
+ *                    multi-word queries from the shell)
+ */
+
+import Table from "cli-table3";
+
+import { searchSkills } from "../lib/http.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { formatIdentifier } from "../lib/identifier.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `search`. Throws CliError on any failure.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runSearch(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  let query = null;
+  let limit = 20;
+  let semantic = false;
+
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg, i, all) {
+      // --limit <n> and --semantic are command-specific; intercept
+      // them here so they don't fall through to "Unknown argument".
+      if (arg === "--limit" && all[i + 1] !== undefined) {
+        const n = Number(all[i + 1]);
+        if (!Number.isInteger(n) || n < 1 || n > 100) {
+          throw validationError(`--limit must be an integer between 1 and 100`);
+        }
+        limit = n;
+        return 2; // consume `--limit` + value
+      }
+      if (arg === "--semantic") {
+        semantic = true;
+        return 1;
+      }
+      // Otherwise treat as the query (only the FIRST non-flag becomes the query)
+      if (query !== null) {
+        throw validationError(
+          `Unexpected extra argument: ${arg}`,
+          { hint: "Quote multi-word queries: `skillrepo search \"my query\"`" },
+        );
+      }
+      query = arg;
+      return 1;
+    },
+  });
+
+  if (!query || query.trim() === "") {
+    throw validationError("Search query is required.", {
+      hint: 'Usage: skillrepo search "<query>"',
+    });
+  }
+
+  const result = await searchSkills(flags.serverUrl, flags.apiKey, {
+    q: query,
+    limit,
+  });
+
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          query,
+          semantic,
+          // Surface the no-op explicitly so scripts can see it
+          // wasn't honored, even though the request succeeded.
+          semanticSupported: false,
+          results: result.skills,
+          pagination: result.pagination,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  // Emit the --semantic note BEFORE any table or empty-results
+  // message so the user reads it as context for whatever follows.
+  // The previous ordering only emitted the warning AFTER the table
+  // rendered (and not at all on empty results), which obscured the
+  // fact that semantic search was silently downgraded to keyword.
+  if (semantic) {
+    stderr.write(
+      "  note: --semantic is reserved for v1.1; using keyword search.\n",
+    );
+  }
+
+  if (result.skills.length === 0) {
+    stdout.write(
+      `\n  No skills found matching "${query}".\n  ` +
+        `Try a broader search or browse the catalog at /skills.\n\n`,
+    );
+    return;
+  }
+
+  printTable(query, result, stdout);
+}
+
+function printTable(query, result, out) {
+  const table = new Table({
+    head: ["Skill", "Version", "Installs", "Description"],
+    colWidths: computeColWidths(streamColumns(out)),
+    wordWrap: true,
+    style: { head: ["bold"] },
+  });
+
+  for (const s of result.skills) {
+    table.push([
+      formatIdentifier(s),
+      s.version || "—",
+      formatInstallCount(s.installs),
+      truncate(s.description || "", 60),
+    ]);
+  }
+
+  out.write(`\n  Results for "${query}":\n`);
+  out.write(table.toString() + "\n\n");
+  const total = result.pagination?.total ?? result.skills.length;
+  const shown = result.skills.length;
+  if (total > shown) {
+    out.write(
+      `  Showing ${shown} of ${total} results. Use --limit to see more.\n\n`,
+    );
+  } else {
+    out.write(`  ${total} result${total === 1 ? "" : "s"}.\n\n`);
+  }
+}
+
+function computeColWidths(terminalColumns) {
+  const total = terminalColumns > 60 ? Math.min(terminalColumns, 120) : 100;
+  const skillCol = 32;
+  const versionCol = 10;
+  const installsCol = 10;
+  const descCol = Math.max(20, total - skillCol - versionCol - installsCol - 6);
+  return [skillCol, versionCol, installsCol, descCol];
+}
+
+/**
+ * Read the column width from the active output stream, falling back
+ * to process.stdout's TTY column count, then to a 100-col default.
+ * Same rationale as list.mjs streamColumns().
+ */
+function streamColumns(out) {
+  if (out && typeof out.columns === "number" && out.columns > 0) {
+    return out.columns;
+  }
+  if (process.stdout.columns && process.stdout.columns > 0) {
+    return process.stdout.columns;
+  }
+  return 100;
+}
+
+function formatInstallCount(n) {
+  if (typeof n !== "number" || !Number.isFinite(n)) return "—";
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + "…";
+}

package/src/commands/update.mjs

@@ -0,0 +1,67 @@
+/**
+ * `skillrepo update` (#675).
+ *
+ * Re-syncs the user's library against the registry by calling the
+ * shared `sync.mjs` engine. This is a thin command wrapper around
+ * `runSync` plus argument parsing and a printer.
+ *
+ * Flags (parsed by the shared `resolveFlags` helper):
+ *   --global         Write to ~/.claude/skills/ instead of project-local
+ *   --ide <list>     Comma-separated vendor list
+ *   --json           Print summary as JSON
+ *   --key <key>      Override config-file access key
+ *   --url <url>      Override config-file server URL
+ *
+ * Exit codes are inherited from sync.mjs / http.mjs error types.
+ */
+
+import { runSync } from "../lib/sync.mjs";
+import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+
+/**
+ * Run `update`. Throws CliError on any failure; the dispatcher
+ * formats and exits.
+ *
+ * @param {string[]} argv
+ * @param {object} [io] - Optional injected streams for testability.
+ *        Defaults to process.stdout/stderr. Tests pass a Writable
+ *        sink so they can capture output without monkey-patching the
+ *        global stdout (which collides with node:test's TAP IPC).
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runUpdate(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const flags = resolveFlags(argv);
+  const vendors = effectiveVendors(flags);
+
+  // Forward `io` to runSync so the non-fatal "failed to persist
+  // last-sync state" warning lands on the injected stderr stream
+  // when tests inject one.
+  const summary = await runSync({
+    serverUrl: flags.serverUrl,
+    apiKey: flags.apiKey,
+    vendors,
+    global: flags.global,
+    io,
+  });
+
+  if (flags.json) {
+    stdout.write(JSON.stringify(summary, null, 2) + "\n");
+    return;
+  }
+  printSummary(summary, stdout);
+}
+
+function printSummary(s, out) {
+  const total = s.added + s.updated + s.removed;
+  if (s.notModified || total === 0) {
+    out.write("  ✓ Library is up to date.\n");
+    return;
+  }
+  out.write("\n  Library sync complete:\n");
+  if (s.added > 0)   out.write(`    + ${s.added} added\n`);
+  if (s.updated > 0) out.write(`    ↻ ${s.updated} updated\n`);
+  if (s.removed > 0) out.write(`    − ${s.removed} removed\n`);
+  out.write("\n");
+}