skillrepo 4.1.0 → 4.3.0

package/bin/skillrepo.mjs

@@ -3,7 +3,8 @@
 /**
  * SkillRepo CLI — pull-based command dispatcher (#674, part of #646).
  *
- * Routes seven commands: init, update, get, add, remove, list, search.
+ * Routes the user-facing commands: init, update, get, add, push,
+ * publish, unpublish, remove, list, search, uninstall, session-sync.
  *
  * PR1 ships only the dispatcher; command modules other than init are
  * stubbed and exit with a "not yet implemented" message. The existing
@@ -25,6 +26,9 @@ 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 { runPush } from "../src/commands/push.mjs";
+import { runPublish } from "../src/commands/publish.mjs";
+import { runUnpublish } from "../src/commands/unpublish.mjs";
 import { runRemove } from "../src/commands/remove.mjs";
 import { runList } from "../src/commands/list.mjs";
 import { runSearch } from "../src/commands/search.mjs";
@@ -62,6 +66,23 @@ const COMMANDS = {
     usage: "skillrepo add <@owner/name> [--global] [--agent <list>] [--json]",
     run: async (argv) => runAdd(argv),
   },
+  push: {
+    description: "Push a local skill directory to your library (create or release new version)",
+    usage:
+      "skillrepo push <path> [--version <label>] [--changelog <text>] " +
+      "[--idempotency-key <key>] [--json]",
+    run: async (argv) => runPush(argv),
+  },
+  publish: {
+    description: "Make one of your skills visible in the public catalog",
+    usage: "skillrepo publish <@owner/name> [--json] [--key <key>] [--url <url>]",
+    run: async (argv) => runPublish(argv),
+  },
+  unpublish: {
+    description: "Remove one of your skills from the public catalog (subscribers keep their copy)",
+    usage: "skillrepo unpublish <@owner/name> [--json] [--key <key>] [--url <url>]",
+    run: async (argv) => runUnpublish(argv),
+  },
   remove: {
     description: "Remove a skill from your library and delete it locally",
     usage: "skillrepo remove <@owner/name> [--global] [--agent <list>] [--json]",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {
@@ -13,13 +13,19 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/atxpace/skill-repo.git",
+    "url": "https://github.com/skill-repo/skill-repo.git",
     "directory": "packages/cli"
   },
-  "keywords": ["skillrepo", "cli", "mcp", "ai-skills"],
+  "keywords": [
+    "skillrepo",
+    "cli",
+    "mcp",
+    "ai-skills"
+  ],
   "author": "SkillRepo LLC",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "cli-table3": "^0.6.5"
+    "cli-table3": "^0.6.5",
+    "gray-matter": "^4.0.3"
   }
 }

package/src/commands/publish.mjs

@@ -0,0 +1,125 @@
+/**
+ * `skillrepo publish <@owner/name>` — flip a skill's visibility from
+ * `private` to `global`, making it discoverable in the public catalog
+ * (Epic #1444 R3 #1456).
+ *
+ * Verb is RESERVED for visibility transitions. Releasing a new version
+ * happens via `skillrepo push <path>`. The `publish` and `unpublish`
+ * pair is symmetric — same auth, same access-key scope, same flag
+ * surface — and shares an `setSkillVisibility` HTTP helper under
+ * the hood.
+ *
+ * Outcomes (mirror the server's discriminated `LibraryVisibilityResult`):
+ *   - `published`        → 200 OK, "✓ Published @owner/name…"
+ *   - `unchanged`        → 200 OK, "✓ Already published…"
+ *   - `not-found`        → exit 5 (EXIT_VALIDATION) with skill-not-found message
+ *   - `forbidden`        → exit 4 (EXIT_SCOPE) with the permission hint
+ *   - `publish-blocked`  → exit 5 (EXIT_VALIDATION) with the precondition reason
+ *
+ * Other 4xx/5xx flow through `mapErrorResponse` in `http.mjs` and
+ * surface as `authError` / `scopeError` / `networkError`.
+ *
+ * Flags: `--json --key --url`. NO disk write. NO `--global` /
+ * `--agent` (visibility transitions touch only the registry; local
+ * skill files are unaffected).
+ */
+
+import { publishLibrarySkill } from "../lib/http.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
+import { validationError, scopeError } from "../lib/errors.mjs";
+
+/**
+ * Run `publish`. 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 runPublish(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 publish <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const ref = formatIdentifier({ owner, name });
+
+  const result = await publishLibrarySkill(flags.serverUrl, flags.apiKey, owner, name);
+
+  if (result.action === "not-found") {
+    throw validationError(`Skill ${ref} not found in your account.`, {
+      hint: "You can only publish skills that you own. Check `skillrepo list` for your skills.",
+    });
+  }
+
+  if (result.action === "forbidden") {
+    // exit 4 (EXIT_SCOPE) — same exit code as "missing API-key
+    // scope," semantically the closest match for "you're not
+    // permitted to do this." Scripts can distinguish via the `code`
+    // string in JSON output.
+    //
+    // Server `result.reason` already explains the entitlement model
+    // ("Admins, or members with the `canPublish` entitlement…").
+    // Hint must NOT repeat that text — just point at the next step
+    // the user takes, otherwise the terminal shows the same sentence
+    // twice (once as `error:`, once as `hint:`).
+    throw scopeError(result.reason, {
+      hint: "Ask an account admin to grant you the `canPublish` capability if you should have it.",
+    });
+  }
+
+  if (result.action === "publish-blocked") {
+    // 422 — product-rule precondition. The reason text from the server
+    // is already actionable (it tells the user what to do); pass it
+    // through verbatim. exit 5 (EXIT_VALIDATION) signals "the request
+    // was understood but cannot be processed in the current state."
+    throw validationError(result.reason);
+  }
+
+  if (flags.json) {
+    // Shape matches the rest of the CLI (`add`, `remove`, `push`):
+    // `action` is the success discriminator. No `ok: true` field —
+    // the CLI exits non-zero on error, so the presence of stdout
+    // JSON already implies success.
+    stdout.write(
+      JSON.stringify(
+        {
+          action: result.action,
+          owner,
+          name,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  if (result.action === "unchanged") {
+    stdout.write(
+      `\n  ✓ Already published — ${ref} is already in the public catalog.\n\n`,
+    );
+    return;
+  }
+
+  // result.action === "published"
+  stdout.write(`\n  ✓ Published ${ref} — now in the public catalog.\n\n`);
+}

package/src/commands/push.mjs

@@ -0,0 +1,187 @@
+/**
+ * `skillrepo push <path>` (#1455).
+ *
+ * Smart upsert: walks a local skill directory and uploads it via
+ * `POST /api/v1/library` (#1452 multipart endpoint). The server detects
+ * existence by SKILL.md frontmatter name and either creates a new
+ * private skill (first push) or releases a new version (subsequent push
+ * with changed content). Identical content is a server-side no-op.
+ *
+ * **No write-back.** The files already live at `<path>` on the user's
+ * disk. The CLI uploads them and prints success — it does not write
+ * anything back. `skillrepo update` remains the canonical command for
+ * disk sync from server → local.
+ *
+ * Flags: --idempotency-key / --json / --key / --url
+ * Positional: <path>
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+
+import { pushSkill } from "../lib/http.mjs";
+import { walkSkillFiles } from "../lib/skill-walk.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `push`. 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 runPush(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  let skillPath = null;
+
+  // `resolveFlags` only knows the shared flags (`--global`, `--agent`,
+  // `--json`, `--key`, `--url`, `--verbose`). The per-command value flag
+  // (`--idempotency-key <val>`) is consumed in `acceptPositional` by
+  // returning `2` to claim both the flag name and its value.
+  let idempotencyKey = null;
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg, i, allArgv) {
+      // Value flags: claim flag + value (2 args).
+      if (arg === "--idempotency-key") {
+        if (allArgv[i + 1] === undefined) {
+          throw validationError("Missing value for --idempotency-key.", {
+            hint: "Pass a key, e.g., --idempotency-key my-uuid-here.",
+          });
+        }
+        idempotencyKey = allArgv[i + 1];
+        return 2;
+      }
+      // Otherwise it must be the (sole) positional skill-path argument.
+      if (skillPath !== null) {
+        throw validationError(`Unexpected extra argument: ${arg}`, {
+          hint: "Pass exactly one local directory path.",
+        });
+      }
+      skillPath = arg;
+      return 1;
+    },
+  });
+
+  if (!skillPath) {
+    throw validationError("Missing skill directory path.", {
+      hint: "Usage: skillrepo push <path-to-skill>",
+    });
+  }
+
+  // ── Resolve the skill directory ────────────────────────────────────
+  const absDir = path.resolve(process.cwd(), skillPath);
+  let stat;
+  try {
+    stat = await fs.stat(absDir);
+  } catch (err) {
+    throw validationError(
+      `Path not found: ${skillPath}`,
+      { hint: `Resolved to ${absDir}. Pass a directory containing a SKILL.md.`, cause: err },
+    );
+  }
+  if (!stat.isDirectory()) {
+    throw validationError(`Not a directory: ${skillPath}`, {
+      hint: "Pass a directory containing a SKILL.md, not a single file.",
+    });
+  }
+
+  // ── Read + parse SKILL.md (local validation only) ──────────────────
+  // The walker below picks SKILL.md up as a regular file and sends it
+  // through the multipart `files[]` array. We still read it here for an
+  // early failure check: without this the user would upload every
+  // supporting file before the server's frontmatter-parser rejected the
+  // push.
+  const skillMdPath = path.join(absDir, "SKILL.md");
+  let skillMdLocal;
+  try {
+    skillMdLocal = await fs.readFile(skillMdPath, "utf-8");
+  } catch (err) {
+    throw validationError(`No SKILL.md at ${skillPath}/SKILL.md.`, {
+      hint:
+        "Every skill must have a SKILL.md at its root with YAML " +
+        "frontmatter including `name` and `description` fields.",
+      cause: err,
+    });
+  }
+
+  let frontmatter;
+  try {
+    const parsed = matter(skillMdLocal);
+    frontmatter = parsed.data;
+  } catch (err) {
+    throw validationError(
+      `SKILL.md frontmatter could not be parsed.`,
+      {
+        hint:
+          "Ensure the file starts with `---`, contains valid YAML, and " +
+          "ends the frontmatter block with `---` on its own line.",
+        cause: err,
+      },
+    );
+  }
+
+  if (!frontmatter?.name || typeof frontmatter.name !== "string") {
+    throw validationError("SKILL.md is missing the required `name` field.", {
+      hint: "Add `name: my-skill-name` to the YAML frontmatter.",
+    });
+  }
+
+  // ── Walk the skill folder ──────────────────────────────────────────
+  // The walker returns every file (including the root `SKILL.md`) per
+  // the agentskills.io spec. They all go up as `files[]` parts.
+  const walked = await walkSkillFiles(absDir);
+
+  const files = await Promise.all(
+    walked.map(async (f) => ({
+      relativePath: f.relativePath,
+      content: await fs.readFile(f.absolutePath),
+    })),
+  );
+
+  // ── POST to /api/v1/library ────────────────────────────────────────
+  const result = await pushSkill(flags.serverUrl, flags.apiKey, {
+    files,
+    idempotencyKey: idempotencyKey ?? undefined,
+  });
+
+  // ── Report ─────────────────────────────────────────────────────────
+  const totalUploaded = files.length;
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          action: result.action,
+          bump: result.bump,
+          owner: result.skill?.owner ?? null,
+          name: result.skill?.name ?? frontmatter.name,
+          version: result.skill?.version ?? null,
+          filesUploaded: totalUploaded,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  const ident = `@${result.skill?.owner ?? "?"}/${result.skill?.name ?? frontmatter.name}`;
+  const fileCount = `${totalUploaded} file${totalUploaded === 1 ? "" : "s"}`;
+
+  if (result.action === "created") {
+    stdout.write(
+      `\n  ✓ Created ${ident} v${result.skill?.version ?? "1.0"} (${fileCount})\n\n`,
+    );
+  } else if (result.action === "updated") {
+    stdout.write(
+      `\n  ✓ Released ${ident} v${result.skill?.version} (${result.bump} bump, ${fileCount})\n\n`,
+    );
+  } else {
+    // unchanged
+    stdout.write(
+      `\n  ✓ No changes — ${ident} is already at v${result.skill?.version}\n\n`,
+    );
+  }
+}

package/src/commands/unpublish.mjs

@@ -0,0 +1,129 @@
+/**
+ * `skillrepo unpublish <@owner/name>` — flip a skill's visibility from
+ * `global` to `private`, removing it from the public catalog
+ * (Epic #1444 R3 #1456).
+ *
+ * Pair to `publish.mjs`. Same auth, same scope, same flag surface.
+ *
+ * Side-effect note (per the locked decision in #1446 — surface to
+ * the user via the success-line copy):
+ *   - Subscribers KEEP their current copy of the skill on disk.
+ *   - Subscribers stop receiving future updates unless the publisher
+ *     re-publishes.
+ *   - Each affected subscriber account's owner-role member(s) get
+ *     an unpublish-notification email, debounced 24h per
+ *     (skill, subscriber-account) pair.
+ *
+ * The success line for an actual unpublish includes
+ * `notifiedSubscriberCount` so the publisher knows how many accounts
+ * the unpublish reached.
+ *
+ * Outcomes:
+ *   - `unpublished` → 200 OK, "✓ Unpublished @owner/name (notified N subscribers…)"
+ *   - `unchanged`   → 200 OK, "✓ Already private…"
+ *   - `not-found`   → exit 5 (EXIT_VALIDATION) with skill-not-found message
+ *   - `forbidden`   → exit 4 (EXIT_SCOPE) with the permission hint
+ *
+ * Unpublish has no product-rule preconditions of its own, so the
+ * `publish-blocked` outcome is never returned by the server here.
+ */
+
+import { unpublishLibrarySkill } from "../lib/http.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
+import { validationError, scopeError } from "../lib/errors.mjs";
+
+/**
+ * Run `unpublish`. 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 runUnpublish(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 unpublish <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const ref = formatIdentifier({ owner, name });
+
+  const result = await unpublishLibrarySkill(flags.serverUrl, flags.apiKey, owner, name);
+
+  if (result.action === "not-found") {
+    throw validationError(`Skill ${ref} not found in your account.`, {
+      hint: "You can only unpublish skills that you own. Check `skillrepo list` for your skills.",
+    });
+  }
+
+  if (result.action === "forbidden") {
+    // exit 4 (EXIT_SCOPE) — same code as missing API-key scope.
+    // Server `result.reason` already names the entitlement. Hint
+    // stays short and action-only to avoid duplicating that text.
+    throw scopeError(result.reason, {
+      hint: "Ask an account admin to grant you the `canPublish` capability if you should have it.",
+    });
+  }
+
+  if (flags.json) {
+    // Shape matches the rest of the CLI: `action` is the success
+    // discriminator, no `ok` field. `notifiedSubscriberCount` is
+    // always present so scripts don't need conditional access.
+    stdout.write(
+      JSON.stringify(
+        {
+          action: result.action,
+          owner,
+          name,
+          notifiedSubscriberCount:
+            result.action === "unpublished" ? result.notifiedSubscriberCount : 0,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  if (result.action === "unchanged") {
+    stdout.write(
+      `\n  ✓ Already private — ${ref} is not in the public catalog.\n\n`,
+    );
+    return;
+  }
+
+  // result.action === "unpublished"
+  // Locked decision #1446: subscribers keep their copy; they stop
+  // getting updates. Surface that explicitly so the publisher knows
+  // the action was non-destructive for existing users.
+  const count = result.notifiedSubscriberCount;
+  if (count === 0) {
+    stdout.write(
+      `\n  ✓ Unpublished ${ref} — no other accounts had it in their library, no notifications sent.\n\n`,
+    );
+  } else {
+    const subscribers = count === 1 ? "subscriber" : "subscribers";
+    stdout.write(
+      `\n  ✓ Unpublished ${ref} — notified ${count} ${subscribers} ` +
+        `(they keep their current copy but won't receive future updates).\n\n`,
+    );
+  }
+}