@ahood/cli 0.1.0 → 0.2.1

package/dist/commands/whoami.js

@@ -1,9 +1,17 @@
 import { ApiError, apiJson } from "../http.js";
 import { resolveToken } from "../credentials.js";
-export async function whoami() {
+export async function whoami(args = []) {
+    const wantsJson = args.includes("--json");
     const token = resolveToken();
     if (!token) {
-        console.log("Not logged in. Run `ahood login`.");
+        // Previously exited 0 here, defeating whoami's purpose as a scriptable
+        // auth check -- "no token configured at all" must fail just like "token
+        // rejected by the server" does below.
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: false }));
+        else
+            console.error("Not logged in. Run `ahood login` (or set AHOOD_TOKEN).");
+        process.exitCode = 1;
         return;
     }
     // There is no endpoint that returns an identity for a bearer caller yet, so
@@ -16,21 +24,38 @@ export async function whoami() {
     //          being a token rather than a session. The token is valid.
     //   401 -> resolveCaller could not resolve the token at all: unknown,
     //          revoked, or expired.
+    //   anything else (network failure, 5xx, timeout) is NOT the same as an
+    //          invalid token, and is reported as its own distinct failure.
     try {
         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.
-        console.log("Authenticated.");
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: true, mode: "session" }));
+        else
+            console.log("Authenticated.");
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 403) {
-            console.log("Authenticated with a personal API token.");
+            if (wantsJson)
+                console.log(JSON.stringify({ authenticated: true, mode: "token" }));
+            else
+                console.log("Authenticated with a personal API token.");
+            return;
+        }
+        if (error instanceof ApiError && error.status === 401) {
+            if (wantsJson)
+                console.log(JSON.stringify({ authenticated: false, reason: "invalid_token" }));
+            else
+                console.error("Not authenticated -- your token is invalid or has been revoked.");
+            process.exitCode = 1;
             return;
         }
-        // 401 and anything else (network failure, 5xx) are both "we could not
-        // confirm this token works" -- exit non-zero so `ahood whoami` is
-        // usable as a scriptable auth check.
-        console.error("Not authenticated -- your token is invalid or has been revoked.");
+        const message = error instanceof Error ? error.message : String(error);
+        if (wantsJson)
+            console.log(JSON.stringify({ authenticated: null, error: message }));
+        else
+            console.error(`Could not verify your token: ${message}`);
         process.exitCode = 1;
     }
 }

package/dist/config.js

@@ -1,7 +1,36 @@
 const DEFAULT_API_URL = "https://ahood.vercel.app";
+let warnedAboutOverride = false;
+// AHOOD_API_URL is trusted with the bearer token on every request (see
+// http.ts's apiFetch), so a scheme/host is validated rather than accepted
+// verbatim -- an unvalidated override lets one stray env var (a malicious
+// .envrc, CI config, or a script inside an installed skill) exfiltrate the
+// token to an arbitrary host.
 export function getApiUrl() {
     const configured = process.env.AHOOD_API_URL;
     if (!configured)
         return DEFAULT_API_URL;
-    return configured.endsWith("/") ? configured.slice(0, -1) : configured;
+    const trimmed = configured.replace(/\/+$/, "");
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`AHOOD_API_URL is not a valid URL: "${configured}"`);
+    }
+    // Plain http:// is only allowed for localhost and the RFC 2606 reserved
+    // test TLDs (.test/.invalid/.example/.localhost), which can never resolve
+    // on the public internet -- everything else must be https:// so the
+    // bearer token attached in http.ts is never sent in cleartext.
+    const isLocalHost = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "::1" ||
+        /\.(test|invalid|example|localhost)$/i.test(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocalHost)) {
+        throw new Error(`AHOOD_API_URL must use https:// (http:// is only allowed for localhost/test hosts); got "${configured}".`);
+    }
+    if (trimmed !== DEFAULT_API_URL && !warnedAboutOverride) {
+        console.error(`warning: using non-default API endpoint from AHOOD_API_URL: ${trimmed}`);
+        warnedAboutOverride = true;
+    }
+    return trimmed;
 }

package/dist/credentials.js

@@ -1,15 +1,22 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+function credentialsDir() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "ahood");
+}
 function credentialsPath() {
-    return join(homedir(), ".config", "ahood", "credentials.json");
+    return join(credentialsDir(), "credentials.json");
 }
 export function readCredentials() {
     const path = credentialsPath();
     if (!existsSync(path))
         return null;
     try {
-        return JSON.parse(readFileSync(path, "utf-8"));
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || typeof parsed.token !== "string") {
+            return null;
+        }
+        return parsed;
     }
     catch {
         return null;
@@ -17,7 +24,7 @@ export function readCredentials() {
 }
 export function writeCredentials(creds) {
     const path = credentialsPath();
-    const dir = join(homedir(), ".config", "ahood");
+    const dir = credentialsDir();
     // The `mode` option on mkdirSync/writeFileSync only applies when the
     // directory/file is actually created (POSIX O_CREAT semantics) -- if
     // either already exists with looser permissions (manual chmod, a restored

package/dist/flags.js

@@ -0,0 +1,13 @@
+// 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).
+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.`);
+    }
+    return value;
+}

package/dist/help.js

@@ -1,31 +1,110 @@
 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 whoami", desc: "Reports whether your stored token still authenticates." },
-    { usage: "ahood search <query>", desc: "Search published skills." },
-    { usage: "ahood list-mine", desc: "List your own skills, public and private." },
-    { usage: "ahood add <owner>/<skill>[@version]", desc: "Install a skill into .claude/skills/, pinned in the lockfile." },
-    { usage: "ahood update [<owner>/<skill>]", desc: "Move the lockfile pin forward to the latest version." },
+    {
+        usage: "ahood whoami [--json]",
+        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>]",
+        desc: "Search published skills.",
+        flags: [
+            "--json        Emit the raw skill objects instead of formatted lines.",
+            "--limit <n>   Cap the number of results.",
+        ],
+        examples: ["ahood search pdf-tools", "ahood search pdf-tools --json"],
+    },
+    {
+        usage: "ahood view <owner>/<skill> [--json] [--web]",
+        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 list-mine [--json]",
+        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]",
+        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> ...]",
+        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 edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility]",
-        desc: "Update a skill you own.",
+        usage: "ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]",
+        desc: "Update a skill you own. Only the flags you pass are changed.",
+        flags: [
+            "--tagline <text>              Short one-line description.",
+            "--tags <comma,separated>      Replaces the skill's tag list.",
+            "--license <id>                An SPDX license identifier, e.g. MIT.",
+            "--visibility public|private   Who can see and install the skill.",
+            "--homepage <url>              The skill's homepage URL.",
+            "--repository <url>            The skill's source repository URL.",
+        ],
+        examples: ['ahood edit alice/pdf-tools --tagline "Merge and split PDFs"'],
+    },
+    {
+        usage: "ahood unpublish <owner>/<skill> [--yes]",
+        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 unpublish <owner>/<skill>", desc: "Delete a skill from the registry (asks for confirmation)." },
     { usage: "ahood star <owner>/<skill>", desc: "Star a skill." },
     { usage: "ahood unstar <owner>/<skill>", desc: "Remove your star from a skill." },
     {
-        usage: "ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>",
-        desc: "Publish a new version of an existing skill.",
+        usage: "ahood publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>]",
+        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.",
+        flags: [
+            "--name <text>                 Required only when creating the skill on this publish.",
+            "--tagline <text>              Short one-line description, used only when creating.",
+            "--tags <comma,separated>      Initial tags, used only when creating.",
+            "--license <id>                An SPDX license identifier, e.g. MIT, used only when creating.",
+            "--homepage <url>              The skill's homepage URL, used only when creating.",
+            "--repository <url>            The skill's source repository URL, used only when creating.",
+        ],
+        examples: [
+            "ahood publish alice/pdf-tools@1.1.0",
+            'ahood publish alice/pdf-tools@1.0.0 --name "PDF Tools" --tagline "Merge and split PDFs"',
+            "ahood publish alice/pdf-tools@1.1.0 --path ./pdf-tools",
+        ],
+    },
+    {
+        usage: "ahood token create <name>|list [--json]|revoke <id>",
+        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>",
+        desc: "Print a shell completion script for the command names.",
+        examples: ["ahood completion bash >> ~/.bashrc"],
     },
-    { usage: "ahood token create|list|revoke", desc: "Manage personal API tokens (requires a browser session)." },
 ];
+const COMMAND_ALIASES = { show: "view" };
 export function findCommandHelp(command) {
-    return COMMANDS_HELP.find((c) => c.usage === command || c.usage.startsWith(`ahood ${command} `) || c.usage === `ahood ${command}`);
+    const resolved = COMMAND_ALIASES[command] ?? command;
+    return COMMANDS_HELP.find((c) => c.usage.startsWith(`ahood ${resolved} `) || c.usage === `ahood ${resolved}`);
+}
+export function formatCommandHelp(entry) {
+    const lines = [entry.usage, "", entry.desc];
+    if (entry.flags?.length)
+        lines.push("", "Flags:", ...entry.flags.map((f) => `  ${f}`));
+    if (entry.examples?.length)
+        lines.push("", "Examples:", ...entry.examples.map((e) => `  ${e}`));
+    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}`);
+    const lines = COMMANDS_HELP.map((c) => `  ${c.usage.padEnd(width + 2)}${c.desc.split(". ")[0].replace(/\.$/, "")}.`);
     return [
         "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
         "",
@@ -37,7 +116,12 @@ export function formatHelp() {
         "Commands:",
         ...lines,
         "",
-        "Run `ahood <command> --help` for a single command's usage.",
+        "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
+        "Run `ahood --version` to print the installed CLI version.",
+        "",
+        "Exit codes: 0 success, 1 general error, 2 usage/validation error,",
+        "            4 authentication required or rejected, 5 not found, 6 network/transport error.",
+        "",
         "Full reference: https://ahood.vercel.app/docs",
     ].join("\n");
 }

package/dist/http.js

@@ -1,5 +1,6 @@
 import { getApiUrl } from "./config.js";
 import { resolveToken } from "./credentials.js";
+import { CLI_NAME, CLI_VERSION } from "./version.js";
 export class ApiError extends Error {
     status;
     constructor(status, message) {
@@ -7,18 +8,50 @@ export class ApiError extends Error {
         this.status = status;
     }
 }
+// Distinguished from ApiError so index.ts's top-level handler can map it to
+// its own exit code -- "the network/transport failed" is a different
+// situation for a caller/script than "the server responded with an error".
+export class NetworkError extends Error {
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+// A hung/black-holed server would otherwise stall the process indefinitely --
+// relevant since this CLI is meant to run unattended in CI and be driven by
+// agents. Callers (e.g. publish's upload) can still pass their own `signal`.
 export async function apiFetch(path, init = {}) {
     const token = resolveToken();
     const headers = new Headers(init.headers);
     if (token)
         headers.set("Authorization", `Bearer ${token}`);
-    return fetch(`${getApiUrl()}${path}`, { ...init, headers });
+    headers.set("User-Agent", `${CLI_NAME}/${CLI_VERSION}`);
+    try {
+        return await fetch(`${getApiUrl()}${path}`, {
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+            ...init,
+            headers,
+        });
+    }
+    catch (error) {
+        const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+        const message = error instanceof Error ? error.message : String(error);
+        throw new NetworkError(`Request to ${getApiUrl()}${path} failed (${message}${cause})`);
+    }
 }
 export async function apiJson(path, init = {}) {
     const res = await apiFetch(path, init);
-    const body = await res.json().catch(() => ({}));
     if (!res.ok) {
-        throw new ApiError(res.status, body.error ?? `Request failed with status ${res.status}`);
+        // The error body may not be valid/object JSON (proxy error pages, an
+        // empty body, a literal `null`) -- fall back to the status-only message
+        // rather than crashing on `body.error` of something that isn't an object.
+        const body = await res.json().catch(() => undefined);
+        const message = body && typeof body === "object" && typeof body.error === "string"
+            ? body.error
+            : `Request failed with status ${res.status}`;
+        throw new ApiError(res.status, message);
+    }
+    try {
+        return (await res.json());
+    }
+    catch {
+        throw new Error(`Malformed response from ${getApiUrl()}${path}: expected JSON.`);
     }
-    return body;
 }

package/dist/index.js

@@ -12,40 +12,100 @@ import { edit } from "./commands/edit.js";
 import { unpublish } from "./commands/unpublish.js";
 import { listMine } from "./commands/list-mine.js";
 import { star, unstar } from "./commands/star.js";
-import { formatHelp, findCommandHelp } from "./help.js";
+import { view } from "./commands/view.js";
+import { completion } from "./commands/completion.js";
+import { formatHelp, formatCommandHelp, findCommandHelp } from "./help.js";
+import { ApiError, NetworkError } from "./http.js";
+import { CLI_NAME, CLI_VERSION } from "./version.js";
 const COMMANDS = {
     login: () => login(),
     logout: () => logout(),
-    whoami: () => whoami(),
-    search: (args) => search(args),
-    add: (args) => add(args),
-    update: (args) => update(args),
-    remove: (args) => remove(args),
-    publish: (args) => publish(args),
-    token: (args) => token(args),
-    edit: (args) => edit(args),
-    unpublish: (args) => unpublish(args),
-    "list-mine": () => listMine(),
-    star: (args) => star(args),
-    unstar: (args) => unstar(args),
+    whoami,
+    search,
+    add,
+    update,
+    remove,
+    publish,
+    token,
+    edit,
+    unpublish,
+    "list-mine": listMine,
+    star,
+    unstar,
+    view,
+    show: view, // alias -- "ahood show" is the name issue #30 proposed; same command as "view"
+    completion,
 };
+function levenshtein(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = 0; i <= a.length; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[a.length][b.length];
+}
+function closestCommand(input) {
+    let best;
+    let bestDistance = Infinity;
+    for (const name of Object.keys(COMMANDS)) {
+        const distance = levenshtein(input, name);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = name;
+        }
+    }
+    return bestDistance <= 2 ? best : undefined;
+}
+// A hung/black-holed connection throws undici's generic TypeError("fetch
+// failed") -- http.ts wraps that into NetworkError so it gets its own exit
+// code here, distinct from a server-returned ApiError.
+function exitCodeFor(error) {
+    if (error instanceof ApiError) {
+        if (error.status === 401 || error.status === 403)
+            return 4;
+        if (error.status === 404)
+            return 5;
+        return 2;
+    }
+    if (error instanceof NetworkError)
+        return 6;
+    return 1;
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
+    if (command === "--version" || command === "-v") {
+        console.log(`${CLI_NAME} ${CLI_VERSION}`);
+        return;
+    }
+    if (command === "help") {
+        const sub = args[0];
+        const entry = sub ? findCommandHelp(sub) : undefined;
+        console.log(entry ? formatCommandHelp(entry) : formatHelp());
+        return;
+    }
     // Bare invocation and an explicit help request both just want to see
     // what's available -- neither is an error.
-    if (!command || command === "help" || command === "--help" || command === "-h") {
+    if (!command || command === "--help" || command === "-h") {
         console.log(formatHelp());
         return;
     }
     const handler = COMMANDS[command];
     if (!handler) {
-        console.error(`Unknown command: ${command}\n`);
-        console.error(formatHelp());
-        process.exit(1);
+        console.error(`Unknown command: ${command}`);
+        const suggestion = closestCommand(command);
+        if (suggestion)
+            console.error(`Did you mean '${suggestion}'?`);
+        console.error("Run `ahood help` for a list of commands.");
+        process.exit(2);
     }
     if (args.includes("--help") || args.includes("-h")) {
         const entry = findCommandHelp(command);
-        console.log(entry ? `${entry.usage}\n\n${entry.desc}` : formatHelp());
+        console.log(entry ? formatCommandHelp(entry) : formatHelp());
         return;
     }
     try {
@@ -54,14 +114,10 @@ async function main() {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(message);
-        // "Unauthorized" is the exact, literal body every resolveCaller-gated
-        // route returns on a 401 (see lib/resolve-caller.ts's callers) -- the
-        // one signal worth appending a next-step to, since every other error
-        // message is already command-specific.
-        if (/^unauthorized$/i.test(message)) {
+        if (error instanceof ApiError && (error.status === 401 || error.status === 403)) {
             console.error("Run `ahood login` first (or set AHOOD_TOKEN).");
         }
-        process.exit(1);
+        process.exit(exitCodeFor(error));
     }
 }
 main();

package/dist/lockfile.js

@@ -1,26 +1,71 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
+    const raw = readFileSync(path, "utf-8");
     try {
-        return JSON.parse(readFileSync(path, "utf-8"));
+        return JSON.parse(raw);
     }
     catch {
-        return {};
+        // Silently treating a corrupted lockfile as "nothing installed" is how
+        // every existing pin gets permanently discarded on the very next write --
+        // refuse instead, so a truncated/interrupted write is a loud, fixable
+        // error rather than silent data loss.
+        throw new Error(`Lockfile at ${path} is corrupted and could not be parsed as JSON. Fix or delete it before continuing.`);
     }
 }
 function writeLockfile(path, lockfile) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(lockfile, null, 2) + "\n");
+    // Write-then-rename so a process interrupted mid-write never leaves a
+    // truncated lockfile on disk -- a reader always sees either the old or the
+    // new complete content, never a partial one.
+    const tmpPath = `${path}.tmp-${process.pid}-${process.hrtime.bigint()}`;
+    writeFileSync(tmpPath, JSON.stringify(lockfile, null, 2) + "\n");
+    renameSync(tmpPath, path);
+}
+// Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
+// so two concurrent `ahood add`/`remove` invocations against the same
+// project don't race a read-modify-write and silently drop one another's
+// entry.
+function withLock(path, fn) {
+    mkdirSync(dirname(path), { recursive: true });
+    const lockDir = `${path}.lock`;
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        try {
+            mkdirSync(lockDir);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for the lockfile lock at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        rmdirSync(lockDir);
+    }
 }
 export function writeLockfileEntry(path, ownerSlashSkill, entry) {
-    const lockfile = readLockfile(path);
-    lockfile[ownerSlashSkill] = entry;
-    writeLockfile(path, lockfile);
+    withLock(path, () => {
+        const lockfile = readLockfile(path);
+        lockfile[ownerSlashSkill] = entry;
+        writeLockfile(path, lockfile);
+    });
 }
 export function removeLockfileEntry(path, ownerSlashSkill) {
-    const lockfile = readLockfile(path);
-    delete lockfile[ownerSlashSkill];
-    writeLockfile(path, lockfile);
+    return withLock(path, () => {
+        const lockfile = readLockfile(path);
+        const existed = ownerSlashSkill in lockfile;
+        delete lockfile[ownerSlashSkill];
+        writeLockfile(path, lockfile);
+        return existed;
+    });
 }

package/dist/spec.js

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+// Owner and skill segments become filesystem path components (.claude/skills/<owner>/<skill>)
+// and URL path segments, so both are restricted to a safe charset that cannot contain "..",
+// "/", "\", 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 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 "-".`);
+    }
+}
+export function parseOwnerSkill(spec, usage) {
+    if (!spec)
+        throw new Error(usage);
+    const parts = spec.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        throw new Error(usage);
+    const [owner, skill] = parts;
+    validateSegment(owner, "owner", spec);
+    validateSegment(skill, "skill", spec);
+    return { owner, skill };
+}
+export function parseOwnerSkillVersion(spec, usage) {
+    if (!spec)
+        throw new Error(usage);
+    const atIndex = spec.lastIndexOf("@");
+    const ownerSkill = atIndex > 0 ? spec.slice(0, atIndex) : spec;
+    const version = atIndex > 0 ? spec.slice(atIndex + 1) : "latest";
+    if (atIndex > 0 && version === "") {
+        throw new Error(`Missing version after "@" in "${spec}".\n${usage}`);
+    }
+    if (version !== "latest" && !SEMVER_RE.test(version)) {
+        throw new Error(`Invalid version "${version}" in "${spec}" -- expected "latest" or a semver like 1.2.3.\n${usage}`);
+    }
+    const { owner, skill } = parseOwnerSkill(ownerSkill, usage);
+    return { owner, skill, version };
+}
+export const SKILLS_ROOT = join(".claude", "skills");
+export const LOCKFILE_PATH = join(".claude", "skills.lock.json");
+export function skillDir(owner, skill) {
+    return join(SKILLS_ROOT, owner, skill);
+}

package/dist/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+export const CLI_NAME = pkg.name;
+export const CLI_VERSION = pkg.version;

package/package.json

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