@ahood/cli 0.2.3 → 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)

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,7 +2,7 @@ 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, validateExternalUrl } from "../spec.js";
 // Processing (decompress/validate/checksum/scan/upload) now happens in a
@@ -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
@@ -144,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").`);
     }
@@ -173,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/help.js

@@ -30,6 +30,12 @@ export const COMMANDS_HELP = [
             "--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.",
@@ -43,9 +49,14 @@ export const COMMANDS_HELP = [
         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>",
@@ -79,6 +90,13 @@ export const COMMANDS_HELP = [
         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.",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.2.3",
+  "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",