@ahood/cli 0.2.2 → 0.3.0

package/README.md

@@ -42,12 +42,13 @@ For CI or any non-interactive environment, set `AHOOD_TOKEN` instead of running
 | `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(s) forward to the latest version. One skill failing to update doesn't stop the rest. |
+| `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 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 completion <bash\|zsh\|fish>` | Print a shell completion script for the command names. |

package/dist/commands/add.js

@@ -22,7 +22,7 @@ const MAX_ENTRY_COUNT = 10_000;
 // version in this codebase), so the yanked-skill warning below only fires
 // for an explicit @version -- confirmed by reading both route.ts files
 // rather than assumed.
-async function fetchVersionMeta(owner, skill, version) {
+export async function fetchVersionMeta(owner, skill, version) {
     if (version === "latest") {
         const { skill_versions } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
         if (!skill_versions)
@@ -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/init.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+const USAGE = "Usage: ahood init [name]";
+// 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
+// workflow described in publish.ts's POLL_INTERVAL_MS comment. There's no
+// parser to match locally, so this template instead follows the documented
+// Claude Code skill format: YAML frontmatter delimited by `---` lines, with
+// a `name` and a `description` field -- the same shape every real SKILL.md
+// in this ecosystem uses (see e.g. any installed skill under
+// .claude/skills/<owner>/<skill>/SKILL.md). Keeping to exactly those two
+// fields, rather than inventing extra ones, means nothing here needs
+// updating just because publish.ts's own validation happens to be looser
+// today.
+function buildSkillMd(name) {
+    return `---
+# name: a short, unique identifier for this skill (kebab-case is
+# conventional, e.g. "pdf-tools"). Not the same as the <skill> slug you
+# publish under -- ahood publish reads that from the command line -- but
+# keeping them in sync avoids confusion.
+name: ${name}
+# description: one or two sentences describing what this skill does and
+# when Claude should use it. This is the primary text Claude reads to
+# decide whether to invoke the skill, so be specific rather than generic.
+description: TODO -- describe what this skill does and when Claude should use it.
+---
+
+## Instructions
+
+TODO: describe, step by step, what Claude should do when this skill is invoked.
+`;
+}
+// Falls back to "my-skill" when the directory name itself isn't usable as a
+// bare YAML scalar (empty, or starting with a character like "-" or "@" that
+// would need quoting) -- e.g. running `ahood init` with no name directly in
+// "/" (basename "") or in a directory whose name starts with punctuation.
+function skillNameFor(dirPath) {
+    const base = basename(dirPath);
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base) ? base : "my-skill";
+}
+export async function init(args) {
+    const name = args[0];
+    if (name !== undefined && name.startsWith("-"))
+        throw new Error(USAGE);
+    const targetDir = name ? resolve(name) : process.cwd();
+    const skillMdPath = join(targetDir, "SKILL.md");
+    if (existsSync(skillMdPath)) {
+        throw new Error(`SKILL.md already exists at ${skillMdPath} -- refusing to overwrite it.`);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(skillMdPath, buildSkillMd(name ?? skillNameFor(targetDir)));
+    console.log(`Created ${skillMdPath}`);
+    console.log("Fill in the description, then flesh out the ## Instructions section.");
+    console.log(`Run \`ahood publish <owner>/<skill>@<version>${name ? ` --path ${name}` : ""}\` when ready.`);
+}

package/dist/commands/publish.js

@@ -2,9 +2,9 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pack } from "tar-stream";
 import { createGzip } from "node:zlib";
-import { apiJson, ApiError } from "../http.js";
+import { apiJson, ApiError, sanitizeErrorMessage } 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
@@ -26,8 +26,8 @@ async function pollVersionStatus(owner, skill, version) {
     }
     throw new Error(`Still processing after ${POLL_TIMEOUT_MS / 1000}s -- check \`ahood view ${owner}/${skill}\` later for the result.`);
 }
-const USAGE = "Usage: ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>]\n" +
-    "   or: ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>";
+const USAGE = "Usage: ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]\n" +
+    "   or: ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z> [--json]";
 // Matched by ENTRY NAME at every depth, not by path prefix, so a nested
 // `vendor/thing/.git` is skipped the same as a top-level one. Not a
 // .gitignore parser (out of scope) -- just the fixed set of names that must
@@ -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
@@ -137,7 +144,7 @@ function parsePublishArgs(args) {
 // createSkill requires a name; --tagline/--tags/--license/--homepage/
 // --repository are optional and only used here, never applied to an
 // already-existing skill.
-async function createSkillForPublish(owner, skill, opts) {
+async function createSkillForPublish(owner, skill, opts, jsonOutput) {
     if (!opts.name) {
         throw new Error(`${owner}/${skill} doesn't exist yet -- pass --name to create it as part of this publish (e.g. --name "My Skill").`);
     }
@@ -166,60 +173,101 @@ async function createSkillForPublish(owner, skill, opts) {
             `are always created under your own account (${created.owner}). Retry with: ` +
             `ahood publish ${created.owner}/${skill}@<version>.`);
     }
-    console.log(`Created ${created.owner}/${created.slug} -- publishing its first version now.`);
+    if (!jsonOutput) {
+        console.log(`Created ${created.owner}/${created.slug} -- publishing its first version now.`);
+    }
+    return created;
 }
-async function initVersion(owner, skill, version, packageSizeBytes, createOpts) {
+async function initVersion(owner, skill, version, packageSizeBytes, createOpts, jsonOutput) {
     const path = `/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/init`;
     const body = JSON.stringify({ version, package_size_bytes: packageSizeBytes });
     try {
-        return await apiJson(path, { method: "POST", headers: { "Content-Type": "application/json" }, body });
+        const init = await apiJson(path, { method: "POST", headers: { "Content-Type": "application/json" }, body });
+        return { init };
     }
     catch (error) {
         if (!(error instanceof ApiError) || error.status !== 404)
             throw error;
-        await createSkillForPublish(owner, skill, createOpts);
+        const created = await createSkillForPublish(owner, skill, createOpts, jsonOutput);
         // Retry exactly once. If this ALSO 404s (e.g. a race, or the create
         // silently didn't take), let that error propagate rather than looping.
-        return await apiJson(path, { method: "POST", headers: { "Content-Type": "application/json" }, body });
+        const init = await apiJson(path, { method: "POST", headers: { "Content-Type": "application/json" }, body });
+        return { init, created };
     }
 }
+// --json mode (ahood-cli#57): a CI/script caller needs one machine-readable
+// object on stdout, not the human progress lines below scraped with a
+// regex. jsonOutput therefore gates every intermediate console.log in this
+// flow, and the whole body is wrapped in a try/catch so ANY failure --
+// validation, network, or a rejected publish -- still yields exactly one
+// JSON object (`{error}`) rather than a human message, while still
+// rethrowing so index.ts's exit-code mapping (exitCodeFor) is unaffected.
 export async function publish(args) {
-    const { owner, skill, version, path, name, tagline, tags, license, homepage, repository } = parsePublishArgs(args);
-    const skillMdPath = join(path, "SKILL.md");
-    if (!existsSync(skillMdPath)) {
-        throw new Error(`No SKILL.md found at ${skillMdPath} -- publish must point at a skill folder's root.`);
-    }
-    const archive = await tarGzDirectory(path);
-    const init = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository });
-    // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit
-    // "lib" override, so DOM is included alongside the Node types) type-checks
-    // Buffer/Uint8Array against `Uint8Array<ArrayBuffer>` specifically as of
-    // TS 5.7+'s ArrayBufferLike generics, which a Node Buffer's
-    // `Uint8Array<ArrayBufferLike>` doesn't structurally satisfy even though
-    // it is a valid BufferSource at runtime (this is exactly what Node's own
-    // fetch/undici accepts) -- see undici-types' BodyInit, which includes
-    // `NodeJS.ArrayBufferView` (i.e. Buffer) directly with no such
-    // restriction. Asserting through BodyInit here, rather than reshaping
-    // tsconfig's "lib" for the whole package, keeps this fix local to the one
-    // call site.
-    const putRes = await fetch(init.upload_url, {
-        method: "PUT",
-        body: archive,
-        signal: AbortSignal.timeout(120_000),
-    });
-    if (!putRes.ok) {
-        const body = await putRes.text().catch(() => "");
-        throw new Error(`Upload failed with status ${putRes.status}${body ? `: ${body}` : ""} (version_id: ${init.version_id}, retry with the same command once the underlying issue is fixed).`);
+    const jsonOutput = args.includes("--json");
+    try {
+        const { owner, skill, version, path, name, tagline, tags, license, homepage, repository } = parsePublishArgs(args);
+        const skillMdPath = join(path, "SKILL.md");
+        if (!existsSync(skillMdPath)) {
+            throw new Error(`No SKILL.md found at ${skillMdPath} -- publish must point at a skill folder's root.`);
+        }
+        const archive = await tarGzDirectory(path);
+        const { init, created } = await initVersion(owner, skill, version, archive.length, { name, tagline, tags, license, homepage, repository }, jsonOutput);
+        // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit
+        // "lib" override, so DOM is included alongside the Node types) type-checks
+        // Buffer/Uint8Array against `Uint8Array<ArrayBuffer>` specifically as of
+        // TS 5.7+'s ArrayBufferLike generics, which a Node Buffer's
+        // `Uint8Array<ArrayBufferLike>` doesn't structurally satisfy even though
+        // it is a valid BufferSource at runtime (this is exactly what Node's own
+        // fetch/undici accepts) -- see undici-types' BodyInit, which includes
+        // `NodeJS.ArrayBufferView` (i.e. Buffer) directly with no such
+        // restriction. Asserting through BodyInit here, rather than reshaping
+        // tsconfig's "lib" for the whole package, keeps this fix local to the one
+        // call site.
+        const putRes = await fetch(init.upload_url, {
+            method: "PUT",
+            body: archive,
+            signal: AbortSignal.timeout(120_000),
+        });
+        if (!putRes.ok) {
+            // The signed URL points at Supabase Storage directly, a different host
+            // than the API, so this never goes through apiJson -- sanitize by hand
+            // here for the same reason apiJson does (ahood-cli#31/#50): a raw
+            // proxy/WAF error page must not be spliced verbatim into a thrown Error.
+            const rawBody = await putRes.text().catch(() => "");
+            const body = rawBody ? sanitizeErrorMessage(rawBody) : "";
+            throw new Error(`Upload failed with status ${putRes.status}${body ? `: ${body}` : ""} (version_id: ${init.version_id}, retry with the same command once the underlying issue is fixed).`);
+        }
+        await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/complete`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ version_id: init.version_id }),
+        });
+        if (!jsonOutput)
+            console.log(`Uploaded ${owner}/${skill}@${version} -- processing...`);
+        const result = await pollVersionStatus(owner, skill, version);
+        if (result.status === "failed") {
+            throw new Error(`Publish failed: ${result.failure_reason ?? "unknown reason"}`);
+        }
+        if (jsonOutput) {
+            const output = {
+                version: result.version,
+                status: result.status,
+            };
+            if (result.failure_reason)
+                output.failure_reason = result.failure_reason;
+            if (created)
+                output.created = created;
+            console.log(JSON.stringify(output));
+        }
+        else {
+            console.log(`Published ${owner}/${skill}@${result.version} (${result.status})`);
+        }
     }
-    await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions/complete`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ version_id: init.version_id }),
-    });
-    console.log(`Uploaded ${owner}/${skill}@${version} -- processing...`);
-    const result = await pollVersionStatus(owner, skill, version);
-    if (result.status === "failed") {
-        throw new Error(`Publish failed: ${result.failure_reason ?? "unknown reason"}`);
+    catch (error) {
+        if (jsonOutput) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.log(JSON.stringify({ error: message }));
+        }
+        throw error;
     }
-    console.log(`Published ${owner}/${skill}@${result.version} (${result.status})`);
 }

package/dist/commands/update.js

@@ -1,19 +1,92 @@
-import { LOCKFILE_PATH } from "../spec.js";
+import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
-import { add } from "./add.js";
-// `update` is the only command that moves the lockfile pin forward -- `add`
-// always resolves and pins whatever version it's given (or latest, once,
-// at install time), matching the ADR's "reproducible by default" design.
+import { add, fetchVersionMeta } from "./add.js";
+const USAGE = "Usage: ahood update [<owner>/<skill> ...] [--dry-run] [--json]";
+async function previewSkill(ownerSlashSkill, currentVersion) {
+    const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
+    const meta = await fetchVersionMeta(owner, skill, "latest");
+    const upToDate = currentVersion === meta.version;
+    return {
+        skill: ownerSlashSkill,
+        current_version: currentVersion,
+        latest_version: meta.version,
+        up_to_date: upToDate,
+        changelog_md: upToDate ? null : meta.changelog_md ?? null,
+    };
+}
+function padRow(cells, widths) {
+    return cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+}
+// Prints a side-by-side current/latest table for every previewed skill, then
+// -- for only the skills that actually have an update available -- the
+// changelog for the version they'd move to. Nothing here touches disk or the
+// network beyond the read-only resolution already done in previewSkill().
+function printDryRunTable(previews) {
+    const header = ["SKILL", "CURRENT", "LATEST", "STATUS"];
+    const rows = previews.map((p) => [
+        p.skill,
+        p.current_version ?? "(not installed)",
+        p.latest_version,
+        p.up_to_date ? "up to date" : "update available",
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    console.log(padRow(header, widths));
+    for (const row of rows)
+        console.log(padRow(row, widths));
+    const changed = previews.filter((p) => !p.up_to_date);
+    if (changed.length === 0) {
+        console.log("\nAll skills are already up to date.");
+        return;
+    }
+    for (const p of changed) {
+        console.log(`\n${p.skill}: ${p.current_version ?? "(not installed)"} -> ${p.latest_version}`);
+        console.log(p.changelog_md ? p.changelog_md : "(no changelog available)");
+    }
+}
 export async function update(args) {
+    const dryRun = args.includes("--dry-run");
+    const jsonOutput = args.includes("--json");
+    if (jsonOutput && !dryRun) {
+        throw new Error(`--json is only supported together with --dry-run.\n${USAGE}`);
+    }
+    const targets = args.filter((a) => a !== "--dry-run" && a !== "--json");
     const lockfile = readLockfile(LOCKFILE_PATH);
-    const targets = args.length > 0 ? args : Object.keys(lockfile);
-    if (targets.length === 0) {
+    const skillKeys = targets.length > 0 ? targets : Object.keys(lockfile);
+    if (skillKeys.length === 0) {
         console.log("No installed skills to update.");
         return;
     }
+    if (dryRun) {
+        // Read-only preview: resolves "latest" for each skill via the same
+        // fetchVersionMeta() add() itself uses, but never calls add() -- so
+        // nothing is downloaded, extracted, or written to the lockfile.
+        const previews = [];
+        const failures = [];
+        for (const key of skillKeys) {
+            try {
+                previews.push(await previewSkill(key, lockfile[key]?.version ?? null));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`Failed to resolve latest version for ${key}: ${message}`);
+                failures.push(key);
+            }
+        }
+        if (jsonOutput) {
+            console.log(JSON.stringify(previews));
+        }
+        else if (previews.length > 0) {
+            printDryRunTable(previews);
+        }
+        if (failures.length > 0) {
+            console.error(`${failures.length} of ${skillKeys.length} skill(s) could not be resolved: ${failures.join(", ")}`);
+            process.exitCode = 1;
+        }
+        return;
+    }
     const failures = [];
-    for (const ownerSlashSkill of targets) {
-        if (!lockfile[ownerSlashSkill] && args.length === 0) {
+    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.
             console.warn(`Skipping ${ownerSlashSkill}: not currently installed.`);
@@ -31,7 +104,7 @@ export async function update(args) {
         }
     }
     if (failures.length > 0) {
-        console.error(`${failures.length} of ${targets.length} skill(s) failed to update: ${failures.join(", ")}`);
+        console.error(`${failures.length} of ${skillKeys.length} skill(s) failed to update: ${failures.join(", ")}`);
         process.exitCode = 1;
     }
 }

package/dist/commands/versions.js

@@ -0,0 +1,40 @@
+import { apiJson } from "../http.js";
+import { parseOwnerSkill } from "../spec.js";
+const USAGE = "Usage: ahood versions <owner>/<skill> [--json]";
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex++;
+    }
+    return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+export async function versions(args) {
+    const jsonOutput = args.includes("--json");
+    const spec = args.find((a) => !a.startsWith("--"));
+    if (!spec)
+        throw new Error(USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    const { versions: list } = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/versions`);
+    if (jsonOutput) {
+        console.log(JSON.stringify(list));
+        return;
+    }
+    if (list.length === 0) {
+        console.log(`${owner}/${skill} has no published versions.`);
+        return;
+    }
+    console.log(`${owner}/${skill} -- ${list.length} published version${list.length === 1 ? "" : "s"}`);
+    const field = (label, value) => console.log(`  ${label.padEnd(13)}${value}`);
+    for (const v of list) {
+        console.log("");
+        console.log(v.version);
+        field("published:", v.created_at);
+        field("size:", formatSize(v.package_size_bytes));
+        field("changelog:", v.changelog_md ? v.changelog_md : "-");
+    }
+}

package/dist/commands/whoami.js

@@ -1,5 +1,19 @@
 import { ApiError, apiJson } from "../http.js";
 import { resolveToken } from "../credentials.js";
+// Best-effort enrichment: whoami's real job is answering "does this token
+// still authenticate?", which is already settled by the time this runs.
+// A failure here (network blip, an otherwise-valid token hitting a 500 on
+// this specific route, etc.) must never turn a successful auth check into a
+// command failure -- so every error is swallowed and callers fall back to
+// the plain "Authenticated..." message instead.
+async function fetchProfile() {
+    try {
+        return await apiJson("/api/v1/profile");
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function whoami(args = []) {
     const wantsJson = args.includes("--json");
     const token = resolveToken();
@@ -30,17 +44,21 @@ export async function whoami(args = []) {
         await apiJson("/api/v1/auth/tokens");
         // A session-backed caller (only reachable if this ever runs against a
         // cookie-bearing client) -- the token list came back.
+        const profile = await fetchProfile();
         if (wantsJson)
-            console.log(JSON.stringify({ authenticated: true, mode: "session" }));
+            console.log(JSON.stringify({ authenticated: true, mode: "session", ...profile }));
         else
-            console.log("Authenticated.");
+            console.log(profile ? `Authenticated as ${profile.username}.` : "Authenticated.");
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 403) {
+            const profile = await fetchProfile();
             if (wantsJson)
-                console.log(JSON.stringify({ authenticated: true, mode: "token" }));
+                console.log(JSON.stringify({ authenticated: true, mode: "token", ...profile }));
             else
-                console.log("Authenticated with a personal API token.");
+                console.log(profile
+                    ? `Authenticated as ${profile.username} (personal API token).`
+                    : "Authenticated with a personal API token.");
             return;
         }
         if (error instanceof ApiError && error.status === 401) {

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,30 +23,51 @@ 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.",
             "--web    Open the skill's page in your browser instead of printing.",
         ],
     },
+    {
+        usage: "ahood versions <owner>/<skill> [--json]",
+        summary: "List a skill's published-version history -- version, changelog, size, and publish date.",
+        desc: "List a skill's published-version history: version, changelog, size, and publish date. Most-recent first.",
+        flags: ["--json    Emit the raw version objects instead of formatted text."],
+    },
     {
         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> ...]",
+        usage: "ahood update [<owner>/<skill> ...] [--dry-run] [--json]",
+        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.",
+        flags: [
+            "--dry-run   Preview current vs. latest version (and the changelog for anything behind) without installing anything.",
+            "--json      With --dry-run, emit structured preview objects instead of a formatted table.",
+        ],
+        examples: ["ahood update --dry-run", "ahood update alice/pdf-tools --dry-run --json"],
+    },
+    {
+        usage: "ahood remove <owner>/<skill>",
+        summary: "Uninstall and unpin a skill (local only).",
+        desc: "Uninstall and unpin (local only).",
     },
-    { usage: "ahood remove <owner>/<skill>", 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 +80,31 @@ 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 init [name]",
+        summary: "Scaffold a new skill folder with a minimal, valid SKILL.md.",
+        desc: "Scaffold a new skill folder with a minimal, valid SKILL.md. Creates ./<name>/SKILL.md if a name is given, " +
+            "or ./SKILL.md in the current directory otherwise. Refuses to overwrite an existing SKILL.md at the target path.",
+        examples: ["ahood init pdf-tools", "ahood init"],
+    },
     {
         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 +121,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 +162,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/http.js

@@ -43,7 +43,7 @@ const MAX_ERROR_MESSAGE_LENGTH = 500;
 // -- a regression on any endpoint would otherwise dump multi-KB infra details
 // straight to a user's terminal. Anything HTML-shaped or implausibly long for
 // a normal error string is replaced with a short, safe summary instead.
-function sanitizeErrorMessage(message) {
+export function sanitizeErrorMessage(message) {
     const looksLikeHtml = /<!DOCTYPE|<html[\s>]/i.test(message);
     if (!looksLikeHtml && message.length <= MAX_ERROR_MESSAGE_LENGTH)
         return message;

package/dist/index.js

@@ -13,7 +13,9 @@ import { unpublish } from "./commands/unpublish.js";
 import { listMine } from "./commands/list-mine.js";
 import { star, unstar } from "./commands/star.js";
 import { view } from "./commands/view.js";
+import { versions } from "./commands/versions.js";
 import { completion } from "./commands/completion.js";
+import { init } from "./commands/init.js";
 import { formatHelp, formatCommandHelp, findCommandHelp } from "./help.js";
 import { ApiError } from "./http.js";
 import { exitCodeFor } from "./exit-code.js";
@@ -27,6 +29,7 @@ const COMMANDS = {
     update,
     remove,
     publish,
+    init,
     token,
     edit,
     unpublish,
@@ -35,6 +38,7 @@ const COMMANDS = {
     unstar,
     view,
     show: view, // alias -- "ahood show" is the name issue #30 proposed; same command as "view"
+    versions,
     completion,
 };
 function levenshtein(a, b) {

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.3.0",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",