skillrepo 2.0.0 → 3.1.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,162 @@
+/**
+ * `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:
+ *
+ *   - `remove` is called with a specific (owner, name), so the CLI
+ *     already knows exactly what to delete. Going through a full
+ *     sync round-trip to rediscover the tombstone is wasteful —
+ *     a direct unlink is the shortest correct path.
+ *   - Cross-machine remove propagation is handled by the sync
+ *     path: the ETag factors in `libraryRemovals` (fixed in #875)
+ *     so a conditional GET from another machine correctly
+ *     invalidates and returns the tombstone list.
+ *
+ * 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/session-sync.mjs

@@ -0,0 +1,152 @@
+/**
+ * `skillrepo session-sync enable|disable` (#884).
+ *
+ * Thin command wrapper over the session-hook installer/remover in
+ * `src/lib/mergers/session-hook.mjs`. The command exists so users who
+ * want to toggle session-start sync WITHOUT re-running `skillrepo init`
+ * can do so with a single command. `init` calls the same underlying
+ * `mergeSessionHook` helper at its step 6.
+ *
+ * Usage:
+ *   skillrepo session-sync enable       — install the SessionStart hook
+ *   skillrepo session-sync disable      — remove it
+ *   skillrepo session-sync status       — print current state (future — not wired yet)
+ *
+ * Flags:
+ *   --global   Operate on ~/.claude/settings.local.json instead of the
+ *              project-local file. Mirrors `init --global` semantics.
+ *   --json     Emit structured JSON instead of human output.
+ *
+ * Exit codes:
+ *   0   success (installed, updated, unchanged, removed, or already disabled)
+ *   3   disk error (cannot read/write the settings file)
+ *   5   validation error (bad subcommand or flag combination)
+ *
+ * This command does NOT share the `update --session-hook` exit-0-on-
+ * errors contract. That contract exists specifically for the hook
+ * runner's startup path; when a user explicitly invokes
+ * `skillrepo session-sync enable` at the shell, they expect a
+ * non-zero exit on failure so their shell script knows something
+ * went wrong.
+ */
+
+import {
+  mergeSessionHook,
+  removeSessionHook,
+} from "../lib/mergers/session-hook.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `session-sync <subcommand>`. Throws CliError on failure; the
+ * dispatcher maps to the appropriate exit code.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runSessionSync(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+
+  // ── Subcommand + flag parsing ───────────────────────────────────
+  //
+  // The subcommand is the first positional arg — "enable" or
+  // "disable". Use resolveFlags' acceptPositional callback to
+  // consume it (same pattern `get`, `search`, `add`, `remove` use
+  // for their positional args).
+  let subcommand = null;
+  const flags = resolveFlags(argv, {
+    requireAuth: false, // no server call — key not needed
+    skipConfig: true, // don't read the global config file
+    acceptPositional(arg) {
+      if (arg === "enable" || arg === "disable") {
+        if (subcommand !== null) {
+          throw validationError(
+            `session-sync accepts exactly one subcommand; got "${subcommand}" and "${arg}"`,
+          );
+        }
+        subcommand = arg;
+        return 1;
+      }
+      return false;
+    },
+  });
+
+  if (!subcommand) {
+    throw validationError(
+      "session-sync requires a subcommand (enable or disable).",
+      { hint: "Usage: skillrepo session-sync <enable|disable> [--global] [--json]" },
+    );
+  }
+
+  // ── Dispatch ────────────────────────────────────────────────────
+  if (subcommand === "enable") {
+    const result = mergeSessionHook({ global: flags.global });
+    if (flags.json) {
+      stdout.write(JSON.stringify(result, null, 2) + "\n");
+      return;
+    }
+    printEnableResult(result, stdout);
+    return;
+  }
+
+  if (subcommand === "disable") {
+    const result = removeSessionHook({ global: flags.global });
+    if (flags.json) {
+      stdout.write(JSON.stringify(result, null, 2) + "\n");
+      return;
+    }
+    printDisableResult(result, stdout);
+    return;
+  }
+
+  // Unreachable — the acceptPositional callback only accepts the
+  // two subcommands. Defensive throw so a future addition with a
+  // typo'd branch surfaces immediately.
+  throw validationError(`session-sync: unknown subcommand "${subcommand}"`);
+}
+
+function printEnableResult(result, out) {
+  if (result.action === "installed") {
+    out.write(`\n  ✓ SessionStart hook installed (${result.path})\n\n`);
+    return;
+  }
+  if (result.action === "updated") {
+    out.write(`\n  ✓ SessionStart hook updated (${result.path})\n\n`);
+    return;
+  }
+  if (result.action === "unchanged") {
+    out.write(`\n  ✓ SessionStart hook already installed (${result.path})\n\n`);
+    return;
+  }
+  // "skipped" — reason is set
+  out.write(`\n  ⚠ Could not enable session sync: ${result.reason}\n\n`);
+}
+
+function printDisableResult(result, out) {
+  if (result.action === "removed") {
+    out.write(`\n  ✓ SessionStart hook removed (${result.path})\n\n`);
+    return;
+  }
+  if (result.action === "unchanged") {
+    out.write(
+      `\n  ✓ SessionStart hook was not installed (${result.path}) — nothing to do.\n\n`,
+    );
+    return;
+  }
+  // "skipped" with an error — the settings file exists but couldn't
+  // be parsed. Both reviewers (round 2) flagged the observability
+  // gap: without this branch, a corrupt file looked identical to
+  // "file doesn't exist" in human output, and users couldn't tell
+  // the difference. The --json path already surfaces result.error
+  // via its full serialize, so only human mode was affected.
+  if (result.action === "skipped" && result.error) {
+    out.write(`\n  ⚠ ${result.error}\n\n`);
+    return;
+  }
+  // "skipped" without an error — file genuinely doesn't exist.
+  out.write(
+    `\n  ✓ No settings file at ${result.path} — session sync is not enabled.\n\n`,
+  );
+}