@ahood/cli 0.3.3 → 0.3.5

package/README.md

@@ -29,29 +29,32 @@ For CI or any non-interactive environment, set `AHOOD_TOKEN` instead of running
 
 ## Commands
 
-<!-- Kept in sync by hand with cli/src/help.ts's COMMANDS_HELP (the terminal
-     --help output's source) and app/docs/page.tsx's COMMANDS array -- update
-     all three when a command changes. -->
+<!-- Generated from src/help.ts's COMMANDS_HELP by scripts/sync-readme.mjs --
+     do not hand-edit the table below. Run `npm run sync-readme` after
+     changing COMMANDS_HELP to regenerate it. -->
 
+<!-- COMMANDS_TABLE_START -->
 | Command | What it does |
 | --- | --- |
-| `ahood login` | Device-code browser login, stores a token at `~/.config/ahood/credentials.json` (or `$XDG_CONFIG_HOME/ahood/`). |
+| `ahood login` | Device-code browser login, stores a token locally. |
 | `ahood logout` | Removes the stored token. |
 | `ahood whoami [--json]` | Reports whether your stored token still authenticates. |
 | `ahood search <query> [--json] [--limit <n>]` | Search published skills. |
-| `ahood view <owner>/<skill> [--json] [--web]` (alias: `show`) | Show a single skill's details -- tags, license, homepage, repository, dates, etc. -- without installing it, or open its page in a browser. |
-| `ahood list-mine [--json]` | List your own skills, public and private, with their visibility and download/star counts. |
-| `ahood add <owner>/<skill>[@version]` | Install into `.claude/skills/<owner>/<skill>/`, pinned in `.claude/skills.lock.json`. |
-| `ahood update [<owner>/<skill> ...] [--dry-run] [--json]` | Move the lockfile pin(s) forward to the latest version. One skill failing to update doesn't stop the rest. `--dry-run` previews current vs. latest version (plus the changelog for anything behind) without installing anything; add `--json` for structured output. |
-| `ahood remove <owner>/<skill>` | Uninstall and unpin (local only -- does not affect the published skill). |
-| `ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a skill you own. Only the flags you pass are changed; requires the `publish` scope. |
-| `ahood unpublish <owner>/<skill> [--yes]` | Deletes the skill from the registry for every consumer, not just your local install -- prompts for a typed "yes" confirmation, or pass `--yes` for scripts/CI. |
+| `ahood view\|show <owner>/<skill> [--json] [--web]` | Show a single skill's details -- tags, license, homepage, repository, dates, and more -- without installing it (alias: ahood show). |
+| `ahood versions <owner>/<skill> [--json]` | List a skill's published-version history -- version, changelog, size, and publish date. |
+| `ahood list-mine [--json]` | List your own skills, public and private. |
+| `ahood add <owner>/<skill>[@version]` | Install a skill into .claude/skills/, pinned in the lockfile. |
+| `ahood update [<owner>/<skill> ...] [--dry-run] [--json]` | Move the lockfile pin(s) forward to the latest version, for one skill or all installed skills at once. |
+| `ahood remove <owner>/<skill>` | Uninstall and unpin a skill (local only). |
+| `ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a skill you own, changing only the flags you pass. |
+| `ahood unpublish <owner>/<skill>[@version] [--yes]` | Delete a skill from the registry for every consumer, or yank a single version, not just your local install (prompts for confirmation unless --yes is passed). |
 | `ahood star <owner>/<skill>` | Star a skill. |
 | `ahood unstar <owner>/<skill>` | Remove your star from a skill. |
-| `ahood init [name]` | Scaffold a new skill folder with a minimal, valid `SKILL.md` -- `./<name>/SKILL.md` if a name is given, `./SKILL.md` otherwise. Refuses to overwrite an existing `SKILL.md`. |
-| `ahood publish <owner>/<skill>@<version> [--path <dir>] [--name] [--tagline] [--tags] [--license] [--homepage] [--repository]` | Publish a new version of a skill from a folder containing `SKILL.md` (defaults to the current directory). If the skill doesn't exist yet, creates it first -- `--name` is required in that case; `--tagline`/`--tags`/`--license`/`--homepage`/`--repository` are optional and only used at creation. Processing (validation, checksumming, secret scanning) happens server-side after upload; this command polls and reports the final published/failed status. The legacy form `ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>` is still accepted. |
-| `ahood token create <name>\|list [--json]\|revoke <id>` | Manage personal API tokens. Creating a token requires an existing logged-in session -- see the docs. |
+| `ahood init [name]` | Scaffold a new skill folder with a minimal, valid SKILL.md. |
+| `ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]` | Publish a new version of a skill from a folder containing SKILL.md, creating the skill first if it doesn't already exist. |
+| `ahood token create <name>\|list [--json]\|revoke <id> [--yes]` | Manage personal API tokens. |
 | `ahood completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |
+<!-- COMMANDS_TABLE_END -->
 
 Run `ahood help`, `ahood help <command>`, or `ahood <command> --help` for the same reference directly in your terminal. `ahood --version` prints the installed CLI version.
 

package/dist/commands/edit.js

@@ -48,4 +48,7 @@ export async function edit(args) {
         body: JSON.stringify(body),
     });
     console.log(`Updated ${owner}/${updated.slug}: tagline=${JSON.stringify(updated.tagline)}, license=${JSON.stringify(updated.license)}, visibility=${updated.visibility}, tags=[${updated.tags.join(", ")}]`);
+    if (updated.tags_warning) {
+        console.warn(`WARNING: ${updated.tags_warning}`);
+    }
 }

package/dist/commands/init.js

@@ -1,6 +1,22 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, join, resolve, sep } from "node:path";
 const USAGE = "Usage: ahood init [name]";
+// Mirrors the server's slug convention referenced by ahood-cli#60 (and the
+// same shape as spec.ts's SEGMENT_RE, minus "." and "_" -- skill slugs are
+// strictly lowercase-alnum-and-hyphen). A name that already matches this is
+// left untouched; one that doesn't gets normalized rather than rejected,
+// since `init` is meant to be the friendly first-run command.
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+// Lowercases and collapses any run of non-alphanumeric characters (spaces,
+// punctuation, path separators that survived the containment check, etc.)
+// into a single hyphen, then trims leading/trailing hyphens. E.g.
+// "Bad Name!" -> "bad-name".
+function normalizeToSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 // publish.ts's only client-side check on SKILL.md is that the file exists
 // (see publish.ts's `existsSync(skillMdPath)`) -- actual frontmatter
 // validation happens server-side, after upload, as part of the processing
@@ -40,9 +56,33 @@ function skillNameFor(dirPath) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base) ? base : "my-skill";
 }
 export async function init(args) {
-    const name = args[0];
+    let name = args[0];
     if (name !== undefined && name.startsWith("-"))
         throw new Error(USAGE);
+    if (name) {
+        // Path containment first (ahood-cli#61), mirroring spec.ts's
+        // validateSegment containment discipline used by add/remove: a resolved
+        // path that escapes the current directory is a hard rejection, since
+        // normalizing something meant to escape the directory doesn't make
+        // sense -- this has to run on the raw name, before any slug
+        // normalization would mangle "/" and ".." into harmless hyphens.
+        const cwd = resolve(process.cwd());
+        const resolvedName = resolve(cwd, name);
+        if (resolvedName !== cwd && !resolvedName.startsWith(cwd + sep)) {
+            throw new Error(`Invalid name "${name}" -- resolves to "${resolvedName}", which is outside the current directory (${cwd}). Refusing to create files outside the project directory.`);
+        }
+        // Then slug normalization (ahood-cli#60): a name that stays within cwd
+        // but isn't already a valid slug gets normalized with a note, rather
+        // than rejected outright.
+        if (!SLUG_RE.test(name)) {
+            const normalized = normalizeToSlug(name);
+            if (!normalized) {
+                throw new Error(`Invalid name "${name}" -- could not derive a valid name from it (must contain at least one letter or digit).`);
+            }
+            console.log(`Note: normalized "${name}" to "${normalized}".`);
+            name = normalized;
+        }
+    }
     const targetDir = name ? resolve(name) : process.cwd();
     const skillMdPath = join(targetDir, "SKILL.md");
     if (existsSync(skillMdPath)) {

package/dist/commands/search.js

@@ -16,7 +16,7 @@ export async function search(args) {
     }
     const qs = new URLSearchParams({ q: query });
     if (limit !== undefined)
-        qs.set("limit", limit);
+        qs.set("per_page", limit);
     const { skills } = await apiJson(`/api/v1/skills?${qs}`);
     if (jsonOutput) {
         console.log(JSON.stringify(skills));

package/dist/commands/token.js

@@ -1,4 +1,5 @@
 import { apiJson } from "../http.js";
+import { confirm } from "../confirm.js";
 export async function token(args) {
     const [subcommand, ...rest] = args;
     switch (subcommand) {
@@ -9,7 +10,7 @@ export async function token(args) {
         case "revoke":
             return tokenRevoke(rest);
         default:
-            throw new Error("Usage: ahood token create <name>|list [--json]|revoke <id>");
+            throw new Error("Usage: ahood token create <name>|list [--json]|revoke <id> [--yes]");
     }
 }
 async function tokenCreate(args) {
@@ -48,9 +49,40 @@ async function tokenList(args) {
     }
 }
 async function tokenRevoke(args) {
-    const id = args[0];
+    const yes = args.includes("--yes");
+    const id = args.find((a) => !a.startsWith("--"));
     if (!id)
-        throw new Error("Usage: ahood token revoke <id>");
+        throw new Error("Usage: ahood token revoke <id> [--yes]");
+    // --yes bypasses both the lookup and the prompt entirely, preserving the
+    // original one-shot behavior (a single DELETE call) for scripts/CI that
+    // already call `ahood token revoke <id> --yes` unattended.
+    if (!yes) {
+        const confirmed = await confirm(`${await revokePrompt(id)} Type "yes" to confirm: `);
+        if (!confirmed) {
+            console.log("Aborted.");
+            return;
+        }
+    }
     await apiJson(`/api/v1/auth/tokens/${encodeURIComponent(id)}`, { method: "DELETE" });
     console.log(`Revoked ${id}`);
 }
+// Looks up the token's name/prefix via the same list endpoint tokenList
+// uses, so the confirmation prompt shows something a human recognizes
+// (e.g. `Revoke token "ci-runner" (ahd_ab...)?`) instead of a bare opaque
+// UUID copied from `ahood token list` output -- easy to mistype with
+// nothing to catch it. The lookup is best-effort: if it fails for any
+// reason (network hiccup, the id not being present in the list, ...) this
+// falls back to the bare id rather than blocking the revoke on a lookup
+// that isn't itself the destructive operation.
+async function revokePrompt(id) {
+    try {
+        const { tokens } = await apiJson("/api/v1/auth/tokens");
+        const match = tokens.find((t) => t.id === id);
+        if (match)
+            return `Revoke token "${match.name}" (${match.token_prefix}...)?`;
+    }
+    catch {
+        // Fall through to the bare-id form below.
+    }
+    return `Revoke token ${id}?`;
+}

package/dist/commands/unpublish.js

@@ -1,32 +1,8 @@
-import { createInterface } from "node:readline";
 import { apiJson } from "../http.js";
+import { confirm } from "../confirm.js";
 import { parseOwnerSkill, parseOwnerSkillVersion } from "../spec.js";
+import { fetchVersionMeta } from "./add.js";
 const USAGE = "Usage: ahood unpublish <owner>/<skill>[@version] [--yes]";
-// On closed/non-interactive stdin, readline/promises' rl.question() promise
-// never settles -- but since nothing else keeps the event loop alive at that
-// point, the process used to exit 0 anyway once the loop drained, having
-// printed only the prompt (no "Aborted.", no deletion, no error: a silent
-// false success). The plain callback-style API is used instead specifically
-// so the "close" listener can be a reliable signal for "closed without ever
-// answering": `settled` is set synchronously inside the answer callback,
-// before rl.close() is called, so that same close doesn't self-reject.
-function confirm(promptText) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        rl.once("close", () => {
-            if (settled)
-                return;
-            settled = true;
-            reject(new Error("Confirmation was not answered (stdin closed)."));
-        });
-        rl.question(promptText, (answer) => {
-            settled = true;
-            rl.close();
-            resolve(answer.trim().toLowerCase() === "yes");
-        });
-    });
-}
 // A bare "owner/skill" has no "@" at all, so lastIndexOf("@") is -1 and this
 // is a whole-skill unpublish (preserves the exact pre-existing behavior).
 // "owner/skill@1.2.3" has an "@" at index > 0 and is a single-version yank
@@ -42,7 +18,24 @@ export async function unpublish(args) {
     if (!spec)
         throw new Error(USAGE);
     if (isVersioned(spec)) {
-        const { owner, skill, version } = parseOwnerSkillVersion(spec, USAGE);
+        const { owner, skill, version: parsedVersion } = parseOwnerSkillVersion(spec, USAGE);
+        // parseOwnerSkillVersion only validates *syntax* -- an omitted "@version"
+        // or an explicit "@latest" both parse to the literal string "latest".
+        // But the yank request below hits DELETE .../versions/{version}, which
+        // does an exact match against skill_versions.version (ahood-cli#62):
+        // there is no "latest" row there, only the download endpoint resolves
+        // that literal server-side. So "latest" has to be resolved to a real
+        // version string client-side, up front, or the DELETE just 404s with a
+        // generic "Not found" that gives no hint the problem is the word
+        // "latest". add.ts's fetchVersionMeta already solves exactly this (GET
+        // /api/v1/skills/{owner}/{skill}, whose response is joined against
+        // latest_version_id) for its own metadata lookup -- reused verbatim here
+        // rather than duplicating the resolution logic, and it already throws a
+        // clear "<owner>/<skill> has no published version" error for the
+        // no-versions-yet edge case instead of leaving that to a confusing 404.
+        // An explicit @1.2.3 skips this lookup entirely -- it's already a
+        // literal the DELETE endpoint understands, so no extra request is made.
+        const version = parsedVersion === "latest" ? (await fetchVersionMeta(owner, skill, "latest")).version : parsedVersion;
         const key = `${owner}/${skill}@${version}`;
         // Yanking is less destructive than a whole-skill delete (existing
         // lockfile-pinned installs keep resolving/verifying against it -- see
@@ -62,8 +55,18 @@ export async function unpublish(args) {
         // just scoped one level down to skill_versions.yanked_at/yanked_reason
         // instead of skills.deleted_at. Mirroring that existing verb/path
         // convention rather than inventing a new one.
-        await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/${encodeURIComponent(version)}`, { method: "DELETE" });
+        const result = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/${encodeURIComponent(version)}`, { method: "DELETE" });
         console.log(`Yanked ${key}. Existing lockfile pins still resolve; new installs will be warned off it.`);
+        // yankVersion (lib/skills/mutations.ts) still returns ok:true here even
+        // when the yank itself succeeded but the latest_version_id recompute
+        // that follows it failed -- it attaches this field instead of failing
+        // the whole request, since the yank already took effect. Discarding the
+        // response body would silently drop that signal (ahood-cli#68): the
+        // pointer could now be stale with nothing in the terminal to say so, and
+        // a later `ahood add owner/skill` trusts latest_version_id completely.
+        if (result.latest_version_warning) {
+            console.warn(`WARNING: ${result.latest_version_warning}`);
+        }
         return;
     }
     const { owner, skill } = parseOwnerSkill(spec, USAGE);

package/dist/commands/update.js

@@ -86,9 +86,12 @@ export async function update(args) {
     }
     const failures = [];
     for (const ownerSlashSkill of skillKeys) {
-        if (!lockfile[ownerSlashSkill] && targets.length === 0) {
-            // Only reachable when targets came from the lockfile itself, so this
-            // would mean the lockfile changed under us mid-loop -- skip, don't abort.
+        if (!lockfile[ownerSlashSkill]) {
+            // Reachable two ways: an explicitly-named skill that was never
+            // installed (`ahood add` is the right command for that -- `update`
+            // must not silently install and pin it), or -- when targets came from
+            // the lockfile itself -- the lockfile changing out from under us
+            // mid-loop. Either way: skip, don't abort.
             console.warn(`Skipping ${ownerSlashSkill}: not currently installed.`);
             continue;
         }

package/dist/commands/view.js

@@ -41,6 +41,13 @@ export async function view(args) {
     }
     const field = (label, value) => console.log(`  ${label.padEnd(13)}${value}`);
     console.log(`${detail.owner}/${detail.slug}`);
+    // Mirrors the wording/tone of `ahood add`'s yanked warning (src/commands/add.ts)
+    // and the website's skill detail page banner -- this is the one CLI surface
+    // whose entire job is "let me check this out before deciding to install it",
+    // so it must not be the one place that stays silent about a yanked version.
+    if (detail.skill_versions?.yanked_at) {
+        console.warn(`WARNING: ${detail.owner}/${detail.slug}@${detail.skill_versions.version} has been yanked${detail.skill_versions.yanked_reason ? `: ${detail.skill_versions.yanked_reason}` : "."}`);
+    }
     field("name:", detail.name);
     if (detail.tagline)
         field("tagline:", detail.tagline);

package/dist/confirm.js

@@ -0,0 +1,31 @@
+import { createInterface } from "node:readline";
+// On closed/non-interactive stdin, readline/promises' rl.question() promise
+// never settles -- but since nothing else keeps the event loop alive at that
+// point, the process used to exit 0 anyway once the loop drained, having
+// printed only the prompt (no "Aborted.", no deletion, no error: a silent
+// false success). The plain callback-style API is used instead specifically
+// so the "close" listener can be a reliable signal for "closed without ever
+// answering": `settled` is set synchronously inside the answer callback,
+// before rl.close() is called, so that same close doesn't self-reject.
+//
+// Shared by any command that needs a "Type yes to confirm" prompt before a
+// destructive/irreversible action (unpublish's whole-skill delete and
+// per-version yank, token revoke, ...) so they all get the same TTY-safe
+// behavior instead of each reimplementing it slightly differently.
+export function confirm(promptText) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        rl.once("close", () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error("Confirmation was not answered (stdin closed)."));
+        });
+        rl.question(promptText, (answer) => {
+            settled = true;
+            rl.close();
+            resolve(answer.trim().toLowerCase() === "yes");
+        });
+    });
+}

package/dist/help.js

@@ -124,10 +124,11 @@ export const COMMANDS_HELP = [
         ],
     },
     {
-        usage: "ahood token create <name>|list [--json]|revoke <id>",
+        usage: "ahood token create <name>|list [--json]|revoke <id> [--yes]",
         summary: "Manage personal API tokens.",
         desc: "Manage personal API tokens. `create` requires an existing browser-backed session.",
-        examples: ["ahood token create ci-runner", "ahood token list --json", "ahood token revoke <id>"],
+        flags: ["--yes    (revoke only) Skip the confirmation prompt and revoke immediately."],
+        examples: ["ahood token create ci-runner", "ahood token list --json", "ahood token revoke <id>", "ahood token revoke <id> --yes"],
     },
     {
         usage: "ahood completion <bash|zsh|fish>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",
@@ -28,7 +28,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
-    "test": "vitest run"
+    "test": "vitest run",
+    "sync-readme": "node scripts/sync-readme.mjs"
   },
   "dependencies": {
     "tar-stream": "^3.2.1"