@ahood/cli 0.1.0 → 0.2.1

package/README.md

@@ -5,26 +5,28 @@ CLI for [ahood](https://ahood.vercel.app), a registry for installing and publish
 ## Quick start
 
 ```
-npx @alexkay/ahood-cli@latest login
-npx @alexkay/ahood-cli@latest search <something>
-npx @alexkay/ahood-cli@latest add <owner>/<skill>
+npx @ahood/cli@latest login
+npx @ahood/cli@latest search <something>
+npx @ahood/cli@latest add <owner>/<skill>
 ```
 
 ## Install
 
 ```
-npx @alexkay/ahood-cli@latest <command>
+npx @ahood/cli@latest <command>
 ```
 
 or install it globally, so the plain `ahood` command works without `npx`:
 
 ```
-npm i -g @alexkay/ahood-cli
+npm i -g @ahood/cli
 ahood <command>
 ```
 
 For CI or any non-interactive environment, set `AHOOD_TOKEN` instead of running `login` -- every command checks it first.
 
+`AHOOD_API_URL` overrides the registry endpoint (defaults to `https://ahood.vercel.app`). It must be `https://`, except for `localhost`/`127.0.0.1` or an `.test`/`.invalid`/`.example`/`.localhost` host, which may use plain `http://` for local development.
+
 ## Commands
 
 <!-- Kept in sync by hand with cli/src/help.ts's COMMANDS_HELP (the terminal
@@ -33,21 +35,34 @@ For CI or any non-interactive environment, set `AHOOD_TOKEN` instead of running
 
 | Command | What it does |
 | --- | --- |
-| `ahood login` | Device-code browser login, stores a token at `~/.config/ahood/credentials.json`. |
+| `ahood login` | Device-code browser login, stores a token at `~/.config/ahood/credentials.json` (or `$XDG_CONFIG_HOME/ahood/`). |
 | `ahood logout` | Removes the stored token. |
-| `ahood whoami` | Reports whether your stored token still authenticates. |
-| `ahood search <query>` | Search published skills. |
-| `ahood list-mine` | List your own skills, public and private, with their visibility and download/star counts. |
+| `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>]` | Move the lockfile pin forward to the latest version. |
+| `ahood update [<owner>/<skill> ...]` | Move the lockfile pin(s) forward to the latest version. One skill failing to update doesn't stop the rest. |
 | `ahood remove <owner>/<skill>` | Uninstall and unpin (local only -- does not affect the published skill). |
-| `ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility]` | Update a skill you own. Only the flags you pass are changed; requires the `publish` scope. |
-| `ahood unpublish <owner>/<skill>` | Deletes the skill from the registry for every consumer, not just your local install -- prompts for a typed "yes" confirmation first. |
+| `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 star <owner>/<skill>` | Star a skill. |
 | `ahood unstar <owner>/<skill>` | Remove your star from a skill. |
-| `ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>` | Publish a new version of an existing skill from a folder containing `SKILL.md`. The skill itself is created from the web UI first. |
-| `ahood token create\|list\|revoke` | Manage personal API tokens. Creating a token requires an existing logged-in session -- see the docs. |
+| `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 completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |
+
+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.
 
-Run `ahood help` or `ahood <command> --help` for the same reference directly in your terminal.
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | General error |
+| `2` | Usage or validation error (bad arguments, or the server rejected the request as invalid) |
+| `4` | Authentication required or rejected (not logged in, or the token was refused) |
+| `5` | Not found |
+| `6` | Network/transport error |
 
 Full reference, including personal API tokens, CI usage, the public REST API, and the MCP server: **https://ahood.vercel.app/docs**

package/dist/commands/add.js

@@ -1,10 +1,15 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { mkdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import * as tarStream from "tar-stream";
 import { gunzipSync } from "node:zlib";
 import { apiFetch, apiJson } from "../http.js";
-import { writeLockfileEntry } from "../lockfile.js";
+import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir } from "../spec.js";
+import { readLockfile, writeLockfileEntry } from "../lockfile.js";
+const USAGE = "Usage: ahood add <owner>/<skill>[@version]";
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB compressed
+const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024; // 200 MB decompressed
+const MAX_ENTRY_COUNT = 10_000;
 // GET /api/v1/skills/{owner}/{skill}/versions/{version} matches the version
 // string with an exact .eq() (verified live against this branch's route) --
 // there is no "latest" literal in skill_versions.version, so requesting
@@ -19,28 +24,37 @@ import { writeLockfileEntry } from "../lockfile.js";
 // rather than assumed.
 async function fetchVersionMeta(owner, skill, version) {
     if (version === "latest") {
-        const { skill_versions } = await apiJson(`/api/v1/skills/${owner}/${skill}`);
+        const { skill_versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
         if (!skill_versions)
             throw new Error(`${owner}/${skill} has no published version`);
         return { ...skill_versions, yanked_at: null };
     }
-    return apiJson(`/api/v1/skills/${owner}/${skill}/versions/${version}`);
-}
-function parseSpec(spec) {
-    const atIndex = spec.lastIndexOf("@");
-    const ownerSkill = atIndex > 0 ? spec.slice(0, atIndex) : spec;
-    const version = atIndex > 0 ? spec.slice(atIndex + 1) : "latest";
-    const [owner, skill] = ownerSkill.split("/");
-    if (!owner || !skill)
-        throw new Error("Usage: ahood add <owner>/<skill>[@version]");
-    return { owner, skill, version };
+    return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/${encodeURIComponent(version)}`);
 }
 export async function extractTarGz(buffer, destDir) {
-    const tarBuffer = gunzipSync(buffer);
+    let decompressed;
+    try {
+        // maxOutputLength caps decompression itself, so a highly-compressed
+        // "bomb" (whose checksum otherwise matches, since that check runs on the
+        // compressed bytes) can't exhaust memory -- it throws before the
+        // oversized buffer is ever materialized.
+        decompressed = gunzipSync(buffer, { maxOutputLength: MAX_EXTRACTED_BYTES });
+    }
+    catch (error) {
+        throw new Error(`Archive decompresses to more than ${MAX_EXTRACTED_BYTES / (1024 * 1024)} MB, or is not valid gzip -- refusing to extract.`, { cause: error });
+    }
     const extract = tarStream.extract();
     const resolvedDest = resolve(destDir);
+    let entryCount = 0;
     await new Promise((resolvePromise, reject) => {
         extract.on("entry", (header, stream, next) => {
+            entryCount++;
+            if (entryCount > MAX_ENTRY_COUNT) {
+                stream.resume();
+                reject(new Error(`Archive has more than ${MAX_ENTRY_COUNT} entries -- refusing to extract.`));
+                extract.destroy();
+                return;
+            }
             // Path containment, checked BEFORE anything is written. A tar entry
             // name is attacker-controlled data in an archive we merely downloaded
             // -- the server's publish-time validateEntries is supposed to have
@@ -68,25 +82,72 @@ export async function extractTarGz(buffer, destDir) {
             const chunks = [];
             stream.on("data", (chunk) => chunks.push(chunk));
             stream.on("end", () => {
-                mkdirSync(join(fullPath, ".."), { recursive: true });
-                writeFileSync(fullPath, Buffer.concat(chunks));
-                next();
+                try {
+                    mkdirSync(join(fullPath, ".."), { recursive: true });
+                    // Preserve the tar entry's mode (e.g. a scripts/*.sh published with
+                    // its executable bit set) instead of always writing with the
+                    // default mode.
+                    writeFileSync(fullPath, Buffer.concat(chunks), header.mode ? { mode: header.mode } : undefined);
+                    next();
+                }
+                catch (error) {
+                    // Previously uncaught here -- an ENOSPC/EACCES/EROFS mid-extract
+                    // surfaced as a raw Node stack trace instead of the clean,
+                    // single-line error every other failure in this CLI produces.
+                    reject(error);
+                }
             });
             stream.on("error", reject);
         });
         extract.on("finish", () => resolvePromise());
         extract.on("error", reject);
-        extract.end(tarBuffer);
+        extract.end(decompressed);
     });
 }
+// Extracts into a fresh temp directory next to destDir, then swaps it in.
+// Extracting straight into destDir (the old behavior) only ever ADDED files
+// on an upgrade -- anything removed in a newer version, including a script
+// pulled for a security reason, silently stuck around. The temp+rename swap
+// also means a failed/interrupted extract never leaves destDir half-upgraded.
+async function extractFreshVersion(buffer, destDir) {
+    const parentDir = dirname(destDir);
+    mkdirSync(parentDir, { recursive: true });
+    const tempDir = join(parentDir, `.${basename(destDir)}.tmp-${process.pid}-${Date.now()}`);
+    rmSync(tempDir, { recursive: true, force: true });
+    try {
+        await extractTarGz(buffer, tempDir);
+    }
+    catch (error) {
+        rmSync(tempDir, { recursive: true, force: true });
+        try {
+            rmdirSync(parentDir);
+        }
+        catch {
+            // parentDir wasn't empty (other skills from the same owner) -- fine.
+        }
+        throw error;
+    }
+    rmSync(destDir, { recursive: true, force: true });
+    renameSync(tempDir, destDir);
+}
 export async function add(args) {
     const spec = args[0];
     if (!spec)
-        throw new Error("Usage: ahood add <owner>/<skill>[@version]");
-    const { owner, skill, version: requestedVersion } = parseSpec(spec);
+        throw new Error(USAGE);
+    const { owner, skill, version: requestedVersion } = parseOwnerSkillVersion(spec, USAGE);
+    const key = `${owner}/${skill}`;
     const meta = await fetchVersionMeta(owner, skill, requestedVersion);
+    // A lockfile entry records the checksum this exact version was installed
+    // with; if a later fetch of the "same" version disagrees, either the
+    // published artifact changed after being pinned or the registry response
+    // was tampered with in transit -- either way this is not something to
+    // silently accept and overwrite.
+    const existingEntry = readLockfile(LOCKFILE_PATH)[key];
+    if (existingEntry && existingEntry.version === meta.version && existingEntry.checksum_sha256 !== meta.checksum_sha256) {
+        throw new Error(`Refusing to install ${key}@${meta.version}: its checksum (${meta.checksum_sha256}) does not match the one already pinned in the lockfile (${existingEntry.checksum_sha256}) for this exact version. If you trust this change, remove ${key}'s lockfile entry first.`);
+    }
     if (meta.yanked_at) {
-        console.warn(`WARNING: ${owner}/${skill}@${meta.version} has been yanked. Installing anyway.`);
+        console.warn(`WARNING: ${key}@${meta.version} has been yanked. Installing anyway.`);
     }
     // scripts/ warning: mirrors the web detail page's banner (platform ADR's
     // Open Risk #7) -- a CLI-only user installing via `add` would otherwise
@@ -94,27 +155,29 @@ export async function add(args) {
     if (meta.manifest.some((f) => f.path.startsWith("scripts/"))) {
         console.warn("WARNING: this skill includes a scripts/ directory. Review its contents before use.");
     }
-    const downloadRes = await apiFetch(`/api/v1/skills/${owner}/${skill}/download?version=${meta.version}`, {
-        headers: { "X-Ahood-Source": "cli" },
-        redirect: "follow",
-    });
-    if (!downloadRes.ok)
-        throw new Error(`Download failed with status ${downloadRes.status}`);
+    const downloadRes = await apiFetch(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/download?version=${encodeURIComponent(meta.version)}`, { headers: { "X-Ahood-Source": "cli" }, redirect: "follow" });
+    if (!downloadRes.ok) {
+        const body = await downloadRes.text().catch(() => "");
+        throw new Error(`Download failed with status ${downloadRes.status}${body ? `: ${body}` : ""}`);
+    }
+    const contentLength = Number(downloadRes.headers.get("content-length") ?? NaN);
+    if (Number.isFinite(contentLength) && contentLength > MAX_DOWNLOAD_BYTES) {
+        throw new Error(`Download is ${contentLength} bytes, over the ${MAX_DOWNLOAD_BYTES / (1024 * 1024)} MB limit -- refusing to install.`);
+    }
     const buffer = Buffer.from(await downloadRes.arrayBuffer());
+    if (buffer.length > MAX_DOWNLOAD_BYTES) {
+        throw new Error(`Downloaded archive is ${buffer.length} bytes, over the ${MAX_DOWNLOAD_BYTES / (1024 * 1024)} MB limit -- refusing to install.`);
+    }
     const actualChecksum = createHash("sha256").update(buffer).digest("hex");
     if (actualChecksum !== meta.checksum_sha256) {
-        throw new Error(`Checksum mismatch for ${owner}/${skill}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);
+        throw new Error(`Checksum mismatch for ${key}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);
     }
     // Owner-namespaced on disk, mirroring npm's node_modules/@scope/package.
-    // Keyed on the slug alone, alice/utils and bob/utils were the same
-    // directory: installing one silently overwrote the other's files, and
-    // `remove` deleted whichever happened to be there. The lockfile key is
-    // already "owner/skill" and needs no change.
-    const destDir = join(".claude", "skills", owner, skill);
-    await extractTarGz(buffer, destDir);
-    writeLockfileEntry(join(".claude", "skills.lock.json"), `${owner}/${skill}`, {
+    const destDir = skillDir(owner, skill);
+    await extractFreshVersion(buffer, destDir);
+    writeLockfileEntry(LOCKFILE_PATH, key, {
         version: meta.version,
         checksum_sha256: meta.checksum_sha256,
     });
-    console.log(`Installed ${owner}/${skill}@${meta.version} to ${destDir}`);
+    console.log(`Installed ${key}@${meta.version} to ${destDir}`);
 }

package/dist/commands/completion.js

@@ -0,0 +1,46 @@
+import { COMMANDS_HELP } from "../help.js";
+const USAGE = "Usage: ahood completion <bash|zsh|fish>";
+function commandNames() {
+    return COMMANDS_HELP.map((c) => c.usage.split(" ")[1]);
+}
+function bashCompletion() {
+    const names = commandNames().join(" ");
+    return [
+        "_ahood_completions() {",
+        '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+        `  COMPREPLY=($(compgen -W "${names}" -- "$cur"))`,
+        "}",
+        "complete -F _ahood_completions ahood",
+    ].join("\n");
+}
+function zshCompletion() {
+    const names = commandNames().join(" ");
+    return [
+        "#compdef ahood",
+        `_arguments '1: :(${names})'`,
+    ].join("\n");
+}
+function fishCompletion() {
+    return commandNames()
+        .map((name) => `complete -c ahood -n "__fish_use_subcommand" -a "${name}"`)
+        .join("\n");
+}
+// Command-name completion only (not per-command flags) -- still the primary
+// way users discover the available subcommands without reading docs, which
+// this CLI otherwise has no mechanism for at all.
+export async function completion(args) {
+    const shell = args[0];
+    switch (shell) {
+        case "bash":
+            console.log(bashCompletion());
+            return;
+        case "zsh":
+            console.log(zshCompletion());
+            return;
+        case "fish":
+            console.log(fishCompletion());
+            return;
+        default:
+            throw new Error(USAGE);
+    }
+}

package/dist/commands/edit.js

@@ -1,8 +1,7 @@
 import { apiJson } from "../http.js";
-function flagValue(args, flag) {
-    const index = args.indexOf(flag);
-    return index >= 0 ? args[index + 1] : undefined;
-}
+import { flagValue } from "../flags.js";
+import { parseOwnerSkill } from "../spec.js";
+const USAGE = "Usage: ahood edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private] [--homepage <url>] [--repository <url>]";
 // Mirrors PATCH /api/v1/skills/{owner}/{skill}'s allow-list exactly
 // (lib/skills/mutations.ts's UpdateSkillInput) -- only a field the caller
 // explicitly passed a flag for is included in the body, so an omitted flag
@@ -10,12 +9,9 @@ function flagValue(args, flag) {
 // that are present on the body at all).
 export async function edit(args) {
     const spec = args[0];
-    if (!spec || spec.startsWith("--")) {
-        throw new Error("Usage: ahood edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private]");
-    }
-    const [owner, skill] = spec.split("/");
-    if (!owner || !skill)
-        throw new Error("Usage: ahood edit <owner>/<skill> [--tagline ...] [--tags ...] [--license ...] [--visibility ...]");
+    if (!spec || spec.startsWith("--"))
+        throw new Error(USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const body = {};
     const tagline = flagValue(args, "--tagline");
     if (tagline !== undefined)
@@ -27,12 +23,22 @@ export async function edit(args) {
     if (license !== undefined)
         body.license = license;
     const visibility = flagValue(args, "--visibility");
-    if (visibility !== undefined)
+    if (visibility !== undefined) {
+        if (visibility !== "public" && visibility !== "private") {
+            throw new Error(`--visibility must be "public" or "private" (got "${visibility}").`);
+        }
         body.visibility = visibility;
+    }
+    const homepage = flagValue(args, "--homepage");
+    if (homepage !== undefined)
+        body.homepage = homepage;
+    const repository = flagValue(args, "--repository");
+    if (repository !== undefined)
+        body.repository = repository;
     if (Object.keys(body).length === 0) {
-        throw new Error("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility.");
+        throw new Error("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility, --homepage, --repository.");
     }
-    const updated = await apiJson(`/api/v1/skills/${owner}/${skill}`, {
+    const updated = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),

package/dist/commands/list-mine.js

@@ -1,11 +1,16 @@
 import { apiJson } from "../http.js";
-export async function listMine() {
+export async function listMine(args = []) {
+    const jsonOutput = args.includes("--json");
     const { skills } = await apiJson("/api/v1/skills?mine=true");
+    if (jsonOutput) {
+        console.log(JSON.stringify(skills));
+        return;
+    }
     if (skills.length === 0) {
         console.log("You haven't published any skills yet.");
         return;
     }
     for (const skill of skills) {
-        console.log(`${skill.slug} (${skill.visibility}) — ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads, ${skill.stars_count} stars)`);
+        console.log(`${skill.profiles.username}/${skill.slug} (${skill.visibility}) - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads, ${skill.stars_count} stars)`);
     }
 }

package/dist/commands/login.js

@@ -1,5 +1,8 @@
 import { apiJson } from "../http.js";
+import { getApiUrl } from "../config.js";
 import { writeCredentials } from "../credentials.js";
+const DEFAULT_EXPIRES_IN_SECONDS = 600; // 10 minutes, matching the previous timeout loop's real-world duration
+const POLL_TIMEOUT_MS = 10_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -9,14 +12,24 @@ export async function login() {
     });
     console.log(`First, confirm this code matches what you see in your browser: ${code}`);
     console.log(`Open ${verification_url} to approve.`);
-    const deadline = Date.now() + expires_in * 1000;
+    // expires_in is server-supplied; a missing/non-finite value previously
+    // produced `Date.now() + undefined * 1000` = NaN, so `Date.now() < NaN` is
+    // always false and the poll loop's body never ran even once -- login
+    // failed instantly with "timed out" instead of ever actually polling.
+    const seconds = Number.isFinite(expires_in) && expires_in > 0 ? expires_in : DEFAULT_EXPIRES_IN_SECONDS;
+    const deadline = Date.now() + seconds * 1000;
     while (Date.now() < deadline) {
         await sleep(2000);
         let res;
         let body;
         try {
-            res = await fetch(`${verification_url.split("?")[0].replace("/cli-auth", "")}/api/v1/auth/cli/device/${code}`);
-            body = await res.json();
+            // Poll against the CONFIGURED API host (getApiUrl()), not a URL derived
+            // from the server-supplied verification_url -- that field is only ever
+            // shown to the human, never used to build a request, so a compromised
+            // or redirected registry response can't point this at a host that
+            // then harvests the device code and hands back an attacker's token.
+            res = await apiFetchWithTimeout(`/api/v1/auth/cli/device/${encodeURIComponent(code)}`);
+            body = (await res.json());
         }
         catch (error) {
             // A THROWN fetch (DNS blip, dropped socket, a body that isn't JSON) is
@@ -40,3 +53,10 @@ export async function login() {
     }
     throw new Error("Login timed out. Run `ahood login` again.");
 }
+// Not apiJson: a non-2xx poll response ("pending", still-provisioning, etc.)
+// is expected and must not throw -- the status code is inspected by the
+// caller instead. Still routed through the same trusted host + a bounded
+// timeout, unlike the raw, unbounded `fetch` this replaced.
+async function apiFetchWithTimeout(path) {
+    return fetch(`${getApiUrl()}${path}`, { signal: AbortSignal.timeout(POLL_TIMEOUT_MS) });
+}