@ahood/cli 0.2.2 → 0.2.3

package/dist/commands/add.js

@@ -31,6 +31,39 @@ async function fetchVersionMeta(owner, skill, version) {
     }
     return apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/${encodeURIComponent(version)}`);
 }
+// Reads a fetch Response body while enforcing MAX_DOWNLOAD_BYTES AS bytes
+// arrive, instead of buffering the whole thing via arrayBuffer() and checking
+// afterwards (ahood-cli#37). A content-length header, when present and
+// already over cap, lets us bail before reading a single byte; but the header
+// is attacker/server-controlled and sometimes just absent (chunked transfer,
+// a mutated/redirected presigned URL), so it's a fast-path optimization only
+// -- the streaming check below is what actually bounds memory in every case.
+async function readBoundedBody(res, maxBytes) {
+    const contentLength = Number(res.headers.get("content-length") ?? NaN);
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        await res.body?.cancel().catch(() => { });
+        throw new Error(`Download is ${contentLength} bytes, over the ${maxBytes / (1024 * 1024)} MB limit -- refusing to install.`);
+    }
+    if (!res.body)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let total = 0;
+    // Throwing out of a `for await` loop over a ReadableStream runs the async
+    // iterator's implicit `return()`, which cancels the underlying stream and
+    // releases its reader lock -- no separate res.body.cancel() call needed
+    // (and calling one here would fail anyway: the stream is locked to this
+    // loop's internal reader). This is what actually stops reading mid-download
+    // rather than draining the rest of a huge/malicious body first.
+    for await (const chunk of res.body) {
+        const buf = Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes) {
+            throw new Error(`Downloaded archive is over the ${maxBytes / (1024 * 1024)} MB limit -- refusing to install.`);
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
 export async function extractTarGz(buffer, destDir) {
     let decompressed;
     try {
@@ -160,14 +193,7 @@ export async function add(args) {
         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 buffer = await readBoundedBody(downloadRes, MAX_DOWNLOAD_BYTES);
     const actualChecksum = createHash("sha256").update(buffer).digest("hex");
     if (actualChecksum !== meta.checksum_sha256) {
         throw new Error(`Checksum mismatch for ${key}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);

package/dist/commands/completion.js

@@ -1,7 +1,11 @@
-import { COMMANDS_HELP } from "../help.js";
+import { COMMANDS_HELP, COMMAND_ALIASES } from "../help.js";
 const USAGE = "Usage: ahood completion <bash|zsh|fish>";
+// Includes alias names (e.g. "show" for "view") alongside the primary
+// command names, so shell completion offers every name a user might type,
+// not just the ones with their own COMMANDS_HELP entry.
 function commandNames() {
-    return COMMANDS_HELP.map((c) => c.usage.split(" ")[1]);
+    const primary = COMMANDS_HELP.map((c) => c.usage.split(" ")[1]);
+    return [...primary, ...Object.keys(COMMAND_ALIASES)];
 }
 function bashCompletion() {
     const names = commandNames().join(" ");

package/dist/commands/edit.js

@@ -1,6 +1,6 @@
 import { apiJson } from "../http.js";
 import { flagValue } from "../flags.js";
-import { parseOwnerSkill } from "../spec.js";
+import { parseOwnerSkill, validateExternalUrl } 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
@@ -30,11 +30,15 @@ export async function edit(args) {
         body.visibility = visibility;
     }
     const homepage = flagValue(args, "--homepage");
-    if (homepage !== undefined)
+    if (homepage !== undefined) {
+        validateExternalUrl(homepage, "--homepage");
         body.homepage = homepage;
+    }
     const repository = flagValue(args, "--repository");
-    if (repository !== undefined)
+    if (repository !== undefined) {
+        validateExternalUrl(repository, "--repository");
         body.repository = repository;
+    }
     if (Object.keys(body).length === 0) {
         throw new Error("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility, --homepage, --repository.");
     }

package/dist/commands/publish.js

@@ -4,7 +4,7 @@ import { pack } from "tar-stream";
 import { createGzip } from "node:zlib";
 import { apiJson, ApiError } from "../http.js";
 import { flagValue } from "../flags.js";
-import { parseOwnerSkill, SEMVER_RE } from "../spec.js";
+import { parseOwnerSkill, SEMVER_RE, validateExternalUrl } from "../spec.js";
 // Processing (decompress/validate/checksum/scan/upload) now happens in a
 // background workflow, not inline in versions/complete's response (server
 // issue #120) -- complete returns 202 immediately, so this polls
@@ -129,6 +129,13 @@ function parsePublishArgs(args) {
     if (!SEMVER_RE.test(version)) {
         throw new Error(`--version must be a semver like 1.2.3 (got "${version}").\n${USAGE}`);
     }
+    // Validated here, before any network call (including the tar/gzip of the
+    // skill directory) -- these only ever reach the server via
+    // createSkillForPublish's create-skill body (ahood-cli#34).
+    if (homepage !== undefined)
+        validateExternalUrl(homepage, "--homepage");
+    if (repository !== undefined)
+        validateExternalUrl(repository, "--repository");
     return { owner, skill, version, path: pathFlag ?? legacyPath ?? ".", name, tagline, tags, license, homepage, repository };
 }
 // Creates the skill under the caller's own account when versions/init 404s

package/dist/flags.js

@@ -1,13 +1,29 @@
 // Shared flag-value parsing. Throws instead of silently treating the next flag
 // as this flag's value (e.g. `--tagline --visibility public` used to send
 // "--visibility" as the tagline and drop --visibility entirely).
+//
+// Two forms are accepted:
+//   --flag value    Space-separated. If `value` itself looks like a flag
+//                    (starts with "--"), that's treated as "no value given"
+//                    per the swallow-protection above, and this throws.
+//   --flag=value     Explicit-equals. Everything after the first "=" is the
+//                    value, verbatim, even if it starts with "--" -- this is
+//                    the unambiguous escape hatch for values that genuinely
+//                    start with "--" (e.g. a tagline like "--fast and cheap").
 export function flagValue(args, flag) {
-    const index = args.indexOf(flag);
-    if (index < 0)
-        return undefined;
-    const value = args[index + 1];
-    if (value === undefined || value.startsWith("--")) {
-        throw new Error(`${flag} requires a value.`);
+    const prefix = `${flag}=`;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith(prefix)) {
+            return arg.slice(prefix.length);
+        }
+        if (arg === flag) {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`${flag} requires a value.`);
+            }
+            return value;
+        }
     }
-    return value;
+    return undefined;
 }

package/dist/help.js

@@ -1,13 +1,19 @@
 export const COMMANDS_HELP = [
-    { usage: "ahood login", desc: "Device-code browser login, stores a token locally." },
-    { usage: "ahood logout", desc: "Removes the stored token." },
+    {
+        usage: "ahood login",
+        summary: "Device-code browser login, stores a token locally.",
+        desc: "Device-code browser login, stores a token locally.",
+    },
+    { usage: "ahood logout", summary: "Removes the stored token.", desc: "Removes the stored token." },
     {
         usage: "ahood whoami [--json]",
+        summary: "Reports whether your stored token still authenticates.",
         desc: "Reports whether your stored token still authenticates.",
         flags: ["--json    Emit a machine-readable result instead of prose."],
     },
     {
         usage: "ahood search <query> [--json] [--limit <n>]",
+        summary: "Search published skills.",
         desc: "Search published skills.",
         flags: [
             "--json        Emit the raw skill objects instead of formatted lines.",
@@ -17,6 +23,7 @@ export const COMMANDS_HELP = [
     },
     {
         usage: "ahood view <owner>/<skill> [--json] [--web]",
+        summary: "Show a single skill's details -- tags, license, homepage, repository, dates, and more -- without installing it (alias: ahood show).",
         desc: "Show a single skill's details (tags, license, homepage, repository, dates, etc.) without installing it. Alias: ahood show.",
         flags: [
             "--json   Emit the raw skill object instead of formatted lines.",
@@ -25,22 +32,31 @@ export const COMMANDS_HELP = [
     },
     {
         usage: "ahood list-mine [--json]",
+        summary: "List your own skills, public and private.",
         desc: "List your own skills, public and private.",
         flags: ["--json    Emit the raw skill objects instead of formatted lines."],
     },
     {
         usage: "ahood add <owner>/<skill>[@version]",
+        summary: "Install a skill into .claude/skills/, pinned in the lockfile.",
         desc: "Install a skill into .claude/skills/, pinned in the lockfile.",
         examples: ["ahood add alice/pdf-tools", "ahood add alice/pdf-tools@1.2.0"],
     },
     {
         usage: "ahood update [<owner>/<skill> ...]",
+        summary: "Move the lockfile pin(s) forward to the latest version, for one skill or all installed skills at once.",
         desc: "Move the lockfile pin(s) forward to the latest version. With no argument, updates every installed skill; one failure doesn't stop the rest.",
     },
-    { usage: "ahood remove <owner>/<skill>", desc: "Uninstall and unpin (local only)." },
+    {
+        usage: "ahood remove <owner>/<skill>",
+        summary: "Uninstall and unpin a skill (local only).",
+        desc: "Uninstall and unpin (local only).",
+    },
     {
         usage: "ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]",
-        desc: "Update a skill you own. Only the flags you pass are changed.",
+        summary: "Update a skill you own, changing only the flags you pass.",
+        desc: "Update a skill you own. Only the flags you pass are changed. Every flag also accepts " +
+            "the --flag=value form (e.g. --tagline=--fast and cheap), needed when a value itself starts with --.",
         flags: [
             "--tagline <text>              Short one-line description.",
             "--tags <comma,separated>      Replaces the skill's tag list.",
@@ -53,17 +69,24 @@ export const COMMANDS_HELP = [
     },
     {
         usage: "ahood unpublish <owner>/<skill> [--yes]",
+        summary: "Delete a skill from the registry for every consumer, not just your local install (prompts for confirmation unless --yes is passed).",
         desc: "Delete a skill from the registry for every consumer (not just your local install). Prompts for a typed \"yes\" unless --yes is passed.",
         flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
-    { usage: "ahood star <owner>/<skill>", desc: "Star a skill." },
-    { usage: "ahood unstar <owner>/<skill>", desc: "Remove your star from a skill." },
+    { usage: "ahood star <owner>/<skill>", summary: "Star a skill.", desc: "Star a skill." },
+    {
+        usage: "ahood unstar <owner>/<skill>",
+        summary: "Remove your star from a skill.",
+        desc: "Remove your star from a skill.",
+    },
     {
         usage: "ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>]",
+        summary: "Publish a new version of a skill from a folder containing SKILL.md, creating the skill first if it doesn't already exist.",
         desc: "Publish a new version of a skill from a folder containing SKILL.md. If the skill doesn't exist yet, this " +
             "creates it first -- pass --name (required in that case) and optionally --tagline/--tags/--license/--homepage/--repository. " +
             "Processing 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.",
+            "The legacy form `ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>` is still accepted. " +
+            "Every flag also accepts the --flag=value form, needed when a value itself starts with --.",
         flags: [
             "--name <text>                 Required only when creating the skill on this publish.",
             "--tagline <text>              Short one-line description, used only when creating.",
@@ -80,20 +103,38 @@ export const COMMANDS_HELP = [
     },
     {
         usage: "ahood token create <name>|list [--json]|revoke <id>",
+        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>"],
     },
     {
         usage: "ahood completion <bash|zsh|fish>",
+        summary: "Print a shell completion script for the command names.",
         desc: "Print a shell completion script for the command names.",
         examples: ["ahood completion bash >> ~/.bashrc"],
     },
 ];
-const COMMAND_ALIASES = { show: "view" };
+// Exported so other consumers of the command list (e.g. shell completion) can
+// surface aliases without needing their own copy of this map.
+export const COMMAND_ALIASES = { show: "view" };
 export function findCommandHelp(command) {
     const resolved = COMMAND_ALIASES[command] ?? command;
     return COMMANDS_HELP.find((c) => c.usage.startsWith(`ahood ${resolved} `) || c.usage === `ahood ${resolved}`);
 }
+// Renders a COMMANDS_HELP entry's usage line with any known aliases folded in
+// after the primary command name, e.g. "ahood view <owner>/<skill> ..." ->
+// "ahood view|show <owner>/<skill> ...". Used by the top-level --help listing
+// so aliases (like "show" for "view") aren't invisible to users who only
+// skim `ahood --help`.
+export function usageWithAliases(entry) {
+    const parts = entry.usage.split(" ");
+    const name = parts[1];
+    const aliases = Object.keys(COMMAND_ALIASES).filter((alias) => COMMAND_ALIASES[alias] === name);
+    if (aliases.length === 0)
+        return entry.usage;
+    parts[1] = [name, ...aliases].join("|");
+    return parts.join(" ");
+}
 export function formatCommandHelp(entry) {
     const lines = [entry.usage, "", entry.desc];
     if (entry.flags?.length)
@@ -103,8 +144,8 @@ export function formatCommandHelp(entry) {
     return lines.join("\n");
 }
 export function formatHelp() {
-    const width = Math.max(...COMMANDS_HELP.map((c) => c.usage.length));
-    const lines = COMMANDS_HELP.map((c) => `  ${c.usage.padEnd(width + 2)}${c.desc.split(". ")[0].replace(/\.$/, "")}.`);
+    const width = Math.max(...COMMANDS_HELP.map((c) => usageWithAliases(c).length));
+    const lines = COMMANDS_HELP.map((c) => `  ${usageWithAliases(c).padEnd(width + 2)}${c.summary}`);
     return [
         "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
         "",

package/dist/spec.js

@@ -4,11 +4,25 @@ import { join } from "node:path";
 // "/", "\", or a leading dot -- this is what closes the path-traversal hole in add/remove
 // (a spec like "alice/.." previously resolved outside .claude/skills/ entirely).
 const SEGMENT_RE = /^[a-z0-9][a-z0-9._-]*$/i;
-export const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export const SEMVER_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+// The backend enforces these same caps on write (app/api/v1/profile/route.ts's
+// MAX_USERNAME_LENGTH for owner usernames; lib/skills/mutations.ts's
+// createSkill 3-64 check for skill slugs), so a segment over these lengths
+// can never match a real owner/skill anyway. Rejecting it here -- before any
+// request is built -- turns a validly-charset-formatted but absurdly long
+// segment into a clean local error instead of a network round trip that, at
+// a truly pathological length (thousands of characters), hits a raw infra/
+// CDN-layer URL-length limit and 502s before the backend's own routing ever
+// runs (ahood-cli#38).
+const MAX_SEGMENT_LENGTH = { owner: 32, skill: 64 };
 export function validateSegment(value, kind, spec) {
     if (!SEGMENT_RE.test(value) || value === "." || value === "..") {
         throw new Error(`Invalid ${kind} "${value}" in "${spec}" -- must start with a letter/digit and contain only letters, digits, ".", "_", or "-".`);
     }
+    const maxLength = MAX_SEGMENT_LENGTH[kind];
+    if (value.length > maxLength) {
+        throw new Error(`Invalid ${kind} in "${spec.slice(0, 60)}${spec.length > 60 ? "..." : ""}" -- ${kind} segment is too long (${value.length} characters; must be at most ${maxLength}).`);
+    }
 }
 export function parseOwnerSkill(spec, usage) {
     if (!spec)
@@ -36,6 +50,29 @@ export function parseOwnerSkillVersion(spec, usage) {
     const { owner, skill } = parseOwnerSkill(ownerSkill, usage);
     return { owner, skill, version };
 }
+// Applied to --homepage/--repository in edit and publish (ahood-cli#34):
+// these are arbitrary user-supplied external links that the API stores
+// verbatim and the web frontend renders as a raw <a href> -- a
+// javascript:/data: value would be a stored-XSS vector the moment that
+// page renders it. Rejecting anything but http(s) here, before any network
+// call, mirrors config.ts's getApiUrl() validation pattern but with no
+// localhost special-casing (there's no "trusted local dev" case for a
+// public link). An empty string is allowed through un-validated so
+// `edit --homepage ""` can still be used to clear a previously-set value.
+export function validateExternalUrl(value, flag) {
+    if (value === "")
+        return;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${flag} must be a valid http:// or https:// URL (got "${value}").`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`${flag} must use http:// or https:// (got scheme "${url.protocol}" from "${value}").`);
+    }
+}
 export const SKILLS_ROOT = join(".claude", "skills");
 export const LOCKFILE_PATH = join(".claude", "skills.lock.json");
 export function skillDir(owner, skill) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",