@ahood/cli 0.7.3 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ alice/pdf-tools        Merge, split, and compress PDFs from the command line
 bob/pdf-form-filler     Fill PDF form fields from a JSON or CSV data source
 
 $ ahood skill add alice/pdf-tools
-Installed alice/pdf-tools@1.4.0 to .claude/skills/alice/pdf-tools
+Installed alice/pdf-tools@1.4.0 to .claude/skills/alice@pdf-tools
 ```
 
 ---
@@ -85,7 +85,7 @@ Paths `ahood` reads and writes in your project, none of which need to be gitigno
 
 | Path | What's in it |
 | --- | --- |
-| `.claude/skills/<owner>/<skill>/` | Installed skill files. |
+| `.claude/skills/<owner>@<skill>/` | Installed skill files. |
 | `.claude/agents/<owner>@<skill>.md` | An installed agent, as a single file (`@` owner/skill separator, since Claude Code's own subagent loader scans `.claude/agents/*.md` flat, non-recursively). |
 | `.claude/skills.lock.json` | Exact installed version + checksum per skill or agent, written by `add`/`update`, read by every install to verify integrity. |
 
@@ -116,7 +116,7 @@ description: Merge, split, and compress PDFs from the command line
 ...
 
 $ ahood skill add alice/pdf-tools@1.4.0
-Installed alice/pdf-tools@1.4.0 to .claude/skills/alice/pdf-tools
+Installed alice/pdf-tools@1.4.0 to .claude/skills/alice@pdf-tools
 ```
 </details>
 
@@ -216,7 +216,7 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood skill add <owner>/<skill>[@version]` | Install a skill into .claude/skills/, pinned in the lockfile. |
 | `ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]` | Move the lockfile pin(s) forward to the latest version, for one skill or all installed skills at once. |
 | `ahood skill outdated [<owner>/<skill> ...] [--json]` | Read-only staleness check comparing current and latest versions (with changelog) for installed skills. |
-| `ahood skill remove <owner>/<skill>` | Uninstall and unpin a skill (local only). |
+| `ahood skill remove <owner>/<skill> [--yes]` | Uninstall and unpin a skill (local only, prompts for confirmation unless --yes is passed). |
 | `ahood skill edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a skill you own, changing only the flags you pass. |
 | `ahood skill unpublish <owner>/<skill>[@version] [--yes]` | Delete a skill from the registry for every consumer, or yank a single version, not just your local install (prompts for confirmation unless --yes is passed). |
 | `ahood skill star <owner>/<skill>` | Star a skill. |
@@ -235,12 +235,24 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | `ahood group members <group> [--json]` | List a group's members and their role (owner-only visible to members). |
 | `ahood group invite-link <group> [--json]` | Create (or regenerate) a shareable invite link for a group you own. |
 | `ahood group join <invite-url-or-token>` | Join a group using an invite link or its raw token. |
-| `ahood group remove-member <group> <username>` | Remove a member from a group you own. |
-| `ahood group leave <group>` | Leave a group you belong to. |
+| `ahood group remove-member <group> <username> [--yes]` | Remove a member from a group you own (prompts for confirmation unless --yes is passed). |
+| `ahood group leave <group> [--yes]` | Leave a group you belong to (prompts for confirmation unless --yes is passed). |
 | `ahood group delete <group> [--yes]` | Permanently delete a group you own (prompts for confirmation unless --yes is passed). |
+
+### Snap
+
+| Command | What it does |
+| --- | --- |
+| `ahood snap create <content> [--json]` | Capture a new private snap, from an argument or piped stdin. |
+| `ahood snap list [--json] [--limit <n>]` | List your own snaps, most recent first. |
+| `ahood snap search <query> [--json] [--limit <n>]` | Search your own snaps by content. |
+| `ahood snap show <id> [--json]` | Print a single snap's full content. |
+| `ahood snap remove <id> [--yes]` | Permanently delete a snap (prompts for confirmation unless --yes is passed). |
+| `ahood snap share <id> [--json]` | Mint (or return the existing) shareable link for a snap. |
+| `ahood snap unshare <id> [--yes]` | Revoke a snap's share link (the snap itself is untouched; prompts for confirmation unless --yes is passed). |
 <!-- COMMANDS_TABLE_END -->
 
-Run `ahood --help`, `ahood skill --help`, `ahood group --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>` / `ahood help group <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
+Run `ahood --help`, `ahood skill --help`, `ahood group --help`, `ahood snap --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>` / `ahood help group <verb>` / `ahood help snap <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
 
 ## Exit codes
 

package/dist/commands/add.js

@@ -3,15 +3,21 @@ import { mkdirSync, renameSync, rmSync, rmdirSync, writeFileSync, readFileSync,
 import { basename, dirname, join, resolve, sep } from "node:path";
 import * as tarStream from "tar-stream";
 import { gunzipSync } from "node:zlib";
-import { apiFetch, apiJson } from "../http.js";
+import { apiFetch, apiJson, ApiError, sanitizeErrorMessage } from "../http.js";
 import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, AGENTS_ROOT, MCP_CONFIG_PATH } from "../spec.js";
-import { readLockfile, writeLockfileEntry, withLock, writeJsonFileAtomic } from "../lockfile.js";
+import { readLockfile, withLock, writeJsonFileAtomic, writeLockfileEntryVerifyingChecksum, LockfileChecksumConflictError, } from "../lockfile.js";
 import { promptSecret } from "../secret-prompt.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill add <owner>/<skill>[@version]";
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB compressed
 const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024; // 200 MB decompressed
 const MAX_ENTRY_COUNT = 10_000;
+// Shared wording for the checksum-pin tamper-detection guard, used both by
+// the early unlocked fast-fail check in add() and by the real,
+// concurrency-safe enforcement at each write site below (ahood-cli#101).
+function checksumConflictMessage(key, meta, existing) {
+    return `Refusing to install ${key}@${meta.version}: its checksum (${meta.checksum_sha256}) does not match the one already pinned in the lockfile (${existing.checksum_sha256}) for this exact version. If you trust this change, remove ${key}'s lockfile entry first.`;
+}
 // GET /api/v1/skills/{owner}/{skill}/versions/{version} matches the version
 // string with an exact .eq() (verified live against this branch's route) --
 // there is no "latest" literal in skill_versions.version, so requesting
@@ -398,7 +404,22 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         fileContents.mcpServers[skill] = serverConfig;
         writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
     });
-    writeLockfileEntry(LOCKFILE_PATH, `${owner}/${skill}`, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+    const mcpKey = `${owner}/${skill}`;
+    try {
+        writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, mcpKey, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+    }
+    catch (error) {
+        if (!(error instanceof LockfileChecksumConflictError))
+            throw error;
+        // Roll back the .mcp.json merge above under the same lock pattern --
+        // re-read+delete rather than assuming nothing else changed it since.
+        withLock(MCP_CONFIG_PATH, () => {
+            const fileContents = readMcpConfig();
+            delete fileContents.mcpServers[skill];
+            writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+        });
+        throw new Error(checksumConflictMessage(mcpKey, meta, error.existing));
+    }
     console.log(`Installed ${owner}/${skill}@${meta.version} into ${MCP_CONFIG_PATH} as "${skill}"`);
     if (Object.keys(secretEnv).length > 0) {
         console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
@@ -412,8 +433,14 @@ async function installMcpEntry(owner, skill, meta, buffer) {
 export async function downloadVerifiedArchive(owner, skill, meta) {
     const downloadRes = await apiFetch(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/download?version=${encodeURIComponent(meta.version)}`, { headers: { "X-Ahood-Source": "cli" }, redirect: "follow" });
     if (!downloadRes.ok) {
-        const body = await downloadRes.text().catch(() => "");
-        throw new Error(`Download failed with status ${downloadRes.status}${body ? `: ${body}` : ""}`);
+        // Same host as every other apiJson call, so this must throw ApiError
+        // (not a plain Error) to get the right exitCodeFor mapping (401/404/5xx),
+        // and route the body through sanitizeErrorMessage -- an unsanitized WAF/
+        // proxy HTML page would otherwise dump straight to the terminal here,
+        // exactly what that function exists to prevent elsewhere (ahood-cli#102).
+        const rawBody = await downloadRes.text().catch(() => "");
+        const body = rawBody ? sanitizeErrorMessage(rawBody) : "";
+        throw new ApiError(downloadRes.status, `Download failed with status ${downloadRes.status}${body ? `: ${body}` : ""}`);
     }
     const buffer = await readBoundedBody(downloadRes, MAX_DOWNLOAD_BYTES);
     const actualChecksum = createHash("sha256").update(buffer).digest("hex");
@@ -433,10 +460,15 @@ export async function add(args) {
     // with; if a later fetch of the "same" version disagrees, either the
     // published artifact changed after being pinned or the registry response
     // was tampered with in transit -- either way this is not something to
-    // silently accept and overwrite.
+    // silently accept and overwrite. This early, UNLOCKED read is a fast-fail
+    // optimization only (skip an entire download for the common, non-
+    // concurrent case) -- it provides no real guarantee under concurrent
+    // installs. The actual enforcement is the locked, read-check-write
+    // writeLockfileEntryVerifyingChecksum call at each write site below
+    // (ahood-cli#101).
     const existingEntry = readLockfile(LOCKFILE_PATH)[key];
     if (existingEntry && existingEntry.version === meta.version && existingEntry.checksum_sha256 !== meta.checksum_sha256) {
-        throw new Error(`Refusing to install ${key}@${meta.version}: its checksum (${meta.checksum_sha256}) does not match the one already pinned in the lockfile (${existingEntry.checksum_sha256}) for this exact version. If you trust this change, remove ${key}'s lockfile entry first.`);
+        throw new Error(checksumConflictMessage(key, meta, existingEntry));
     }
     if (meta.yanked_at) {
         console.warn(`WARNING: ${key}@${meta.version} has been yanked. Installing anyway.`);
@@ -458,7 +490,15 @@ export async function add(args) {
         mkdirSync(AGENTS_ROOT, { recursive: true });
         const destPath = agentPath(owner, skill);
         writeFileSync(destPath, content);
-        writeLockfileEntry(LOCKFILE_PATH, key, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+        try {
+            writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+        }
+        catch (error) {
+            if (!(error instanceof LockfileChecksumConflictError))
+                throw error;
+            rmSync(destPath, { force: true });
+            throw new Error(checksumConflictMessage(key, meta, error.existing));
+        }
         console.log(`Installed ${key}@${meta.version} to ${destPath}`);
         return;
     }
@@ -466,12 +506,21 @@ export async function add(args) {
         await installMcpEntry(owner, skill, meta, buffer);
         return;
     }
-    // Owner-namespaced on disk, mirroring npm's node_modules/@scope/package.
+    // Flat, owner@skill-joined directory name so Claude Code's own one-level-deep
+    // project-skill scan actually discovers it (see skillDir's comment in spec.ts).
     const destDir = skillDir(owner, skill);
     await extractFreshVersion(buffer, destDir);
-    writeLockfileEntry(LOCKFILE_PATH, key, {
-        version: meta.version,
-        checksum_sha256: meta.checksum_sha256,
-    });
+    try {
+        writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, {
+            version: meta.version,
+            checksum_sha256: meta.checksum_sha256,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof LockfileChecksumConflictError))
+            throw error;
+        rmSync(destDir, { recursive: true, force: true });
+        throw new Error(checksumConflictMessage(key, meta, error.existing));
+    }
     console.log(`Installed ${key}@${meta.version} to ${destDir}`);
 }

package/dist/commands/group.js

@@ -8,8 +8,8 @@ const LIST_USAGE = "Usage: ahood group list [--json]";
 const MEMBERS_USAGE = "Usage: ahood group members <group> [--json]";
 const INVITE_LINK_USAGE = "Usage: ahood group invite-link <group> [--json]";
 const JOIN_USAGE = "Usage: ahood group join <invite-url-or-token>";
-const REMOVE_MEMBER_USAGE = "Usage: ahood group remove-member <group> <username>";
-const LEAVE_USAGE = "Usage: ahood group leave <group>";
+const REMOVE_MEMBER_USAGE = "Usage: ahood group remove-member <group> <username> [--yes]";
+const LEAVE_USAGE = "Usage: ahood group leave <group> [--yes]";
 const DELETE_USAGE = "Usage: ahood group delete <group> [--yes]";
 // Creates a group (caller becomes owner). Follows edit.ts's convention of
 // requiring the positional argument first, since --description takes a
@@ -115,10 +115,22 @@ export async function joinGroup(args) {
 // "remove yourself"). No flags today, so plain positional filtering is
 // unambiguous.
 export async function removeMember(args) {
+    const yes = args.includes("--yes");
     const positional = args.filter((a) => !a.startsWith("--"));
     const [slug, username] = positional;
     if (!slug || !username)
         throw new UsageError(REMOVE_MEMBER_USAGE);
+    // Mirrors deleteGroup's confirm-before-destroy pattern (CLAUDE.md:
+    // "Destructive commands ... prompt for confirmation unless --yes is
+    // passed") -- a typo'd username here instantly removes the wrong member
+    // with no other command to undo it (ahood-cli#99).
+    const confirmed = yes
+        ? true
+        : await confirm(`Remove ${username} from ${slug}? Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
     await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { method: "DELETE" });
     console.log(`Removed ${username} from ${slug}.`);
 }
@@ -134,9 +146,18 @@ async function getOwnUsername() {
 // handles both cases identically (DELETE .../members/{username} with your
 // own username removes you, same as an owner removing someone else).
 export async function leaveGroup(args) {
+    const yes = args.includes("--yes");
     const slug = args.find((a) => !a.startsWith("--"));
     if (!slug)
         throw new UsageError(LEAVE_USAGE);
+    // Same confirm-before-destroy gate as removeMember -- an accidentally
+    // re-run `leave` drops you from a private group with no other command to
+    // undo it (ahood-cli#99).
+    const confirmed = yes ? true : await confirm(`Leave ${slug}? Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
     const username = await getOwnUsername();
     await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { method: "DELETE" });
     console.log(`Left ${slug}.`);

package/dist/commands/init.js

@@ -29,7 +29,7 @@ function normalizeToSlug(name) {
 // 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
+// .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.

package/dist/commands/list.js

@@ -15,6 +15,10 @@ export async function listSkills(args = []) {
         return;
     }
     for (const skill of skills) {
-        console.log(`${skill.profiles.username}/${skill.slug} (${skill.visibility}) - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads, ${skill.stars_count} stars)`);
+        // profiles comes from a server-side join that can plausibly be null for
+        // an individual row -- degrade that one row instead of crashing the
+        // whole command (ahood-cli#106).
+        const username = skill.profiles?.username ?? "(unknown)";
+        console.log(`${username}/${skill.slug} (${skill.visibility}) - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads, ${skill.stars_count} stars)`);
     }
 }

package/dist/commands/login.js

@@ -21,7 +21,6 @@ export async function login() {
     while (Date.now() < deadline) {
         await sleep(2000);
         let res;
-        let body;
         try {
             // Poll against the CONFIGURED API host (getApiUrl()), not a URL derived
             // from the server-supplied verification_url -- that field is only ever
@@ -29,15 +28,33 @@ export async function login() {
             // or redirected registry response can't point this at a host that
             // then harvests the device code and hands back an attacker's token.
             res = await apiFetchWithTimeout(`/api/v1/auth/cli/device/${encodeURIComponent(code)}`);
+        }
+        catch (error) {
+            // A THROWN fetch (DNS blip, dropped socket) is transient by nature, and
+            // this loop runs for up to ten minutes while a human walks to their
+            // browser -- one bad network moment must not kill a login that is
+            // about to succeed. The deadline is untouched, so this cannot loop
+            // forever.
+            console.error(`Polling failed (${error instanceof Error ? error.message : String(error)}); retrying...`);
+            continue;
+        }
+        // Checked BEFORE res.json(): these are terminal statuses regardless of
+        // body shape, so a non-JSON body on them (e.g. a proxy/WAF error page --
+        // the same threat class sanitizeErrorMessage guards against elsewhere)
+        // must fail fast here instead of throwing inside the try below and being
+        // swallowed as "transient, retry" for up to ten minutes (ahood-cli#104).
+        if (res.status === 410 || res.status === 404) {
+            throw new Error("This login was cancelled or expired. Run `ahood login` again.");
+        }
+        let body;
+        try {
             body = (await res.json());
         }
         catch (error) {
-            // A THROWN fetch (DNS blip, dropped socket, a body that isn't JSON) is
-            // transient by nature, and this loop runs for up to ten minutes while a
-            // human walks to their browser -- one bad network moment must not kill
-            // a login that is about to succeed. HTTP *statuses* are still decided
-            // below; only the transport failure is retried. The deadline is
-            // untouched, so this cannot loop forever.
+            // A genuinely malformed/non-JSON body on a non-terminal status (e.g. a
+            // transient 502 while still pending) is the same kind of transient
+            // blip a thrown fetch above is -- retry rather than fail the whole
+            // login.
             console.error(`Polling failed (${error instanceof Error ? error.message : String(error)}); retrying...`);
             continue;
         }
@@ -46,9 +63,6 @@ export async function login() {
             console.log("Logged in.");
             return;
         }
-        if (res.status === 410 || res.status === 404) {
-            throw new Error("This login was cancelled or expired. Run `ahood login` again.");
-        }
         // status === "pending" -- keep polling.
     }
     throw new Error("Login timed out. Run `ahood login` again.");

package/dist/commands/publish.js

@@ -42,6 +42,10 @@ const USAGE = "Usage: ahood skill publish <owner>/<skill>@<version> [--path <dir
 //   .npmrc / .yarnrc.yml / .netrc / .pypirc -- package-manager/network auth
 //                tokens (npm_..., ghp_...) that don't match the server
 //                scanner's regexes either.
+//   .envrc    -- direnv's own file, commonly holding `export`ed secrets,
+//                exact-matched (not a `.env` prefix match -- "rc" makes it a
+//                distinct name, not a `.env.*` variant) since it doesn't
+//                match the server scanner's regexes either (ahood-cli#97).
 //   id_rsa / id_ed25519 / id_ecdsa / id_dsa (+ .pub) / .ssh -- SSH keys.
 //   .aws / .docker -- cloud and registry credentials.
 //   .DS_Store -- noise.
@@ -53,6 +57,7 @@ const EXCLUDED_NAMES = new Set([
     ".yarnrc.yml",
     ".netrc",
     ".pypirc",
+    ".envrc",
     ".ssh",
     ".aws",
     ".docker",

package/dist/commands/read.js

@@ -46,5 +46,11 @@ export async function read(args) {
     // Plain mode prints the raw content verbatim -- no formatting/labels/
     // trailing decoration -- since the whole point is fast/pipeable access to
     // the exact prompt text (e.g. piping into a file or another tool).
-    console.log(content);
+    // process.stdout.write, not console.log: console.log unconditionally
+    // appends its own "\n", so a well-formed SKILL.md that already ends in one
+    // (the normal case) came out with a second, spurious trailing blank line --
+    // a real, reported round-trip mismatch between "ahood skill read" and the
+    // source file, even though the registry itself stores/serves the content
+    // byte-exact (ahood-cli#90).
+    process.stdout.write(content);
 }

package/dist/commands/remove.js

@@ -1,42 +1,44 @@
-import { existsSync, readdirSync, readFileSync, rmSync, rmdirSync, unlinkSync } from "node:fs";
-import { dirname } from "node:path";
-import { removeLockfileEntry } from "../lockfile.js";
+import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { confirm } from "../confirm.js";
+import { readLockfile, removeLockfileEntry } from "../lockfile.js";
 import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
 import { UsageError } from "../usage-error.js";
-const USAGE = "Usage: ahood skill remove <owner>/<skill>";
+const USAGE = "Usage: ahood skill remove <owner>/<skill> [--yes]";
 export async function remove(args) {
     const spec = args[0];
     if (!spec)
         throw new UsageError(USAGE);
+    const yes = args.includes("--yes");
     const { owner, skill } = parseOwnerSkill(spec, USAGE);
     const key = `${owner}/${skill}`;
+    // Flat owner@skill directory (see skillDir's comment in spec.ts) -- no
+    // owner-namespace folder to sweep afterward, unlike the old nested layout.
     const dir = skillDir(owner, skill);
     const dirExisted = existsSync(dir);
-    if (dirExisted)
-        rmSync(dir, { recursive: true, force: true });
-    // Sweep the owner directory once it holds nothing, so uninstalling an
-    // owner's last skill doesn't leave an empty namespace folder behind (npm
-    // does the same with node_modules/@scope). Guarded on emptiness, so another
-    // skill by the same owner is never touched.
-    const ownerDir = dirname(dir);
-    if (existsSync(ownerDir) && readdirSync(ownerDir).length === 0)
-        rmdirSync(ownerDir);
     // An agent installs as a single flat file (.claude/agents/<owner>@<skill>.md),
-    // never a directory under .claude/skills/ -- skillDir's rmSync above never
-    // touches it. Without this, removing an installed agent silently left the
-    // file on disk (still loaded by Claude Code forever) while reporting
-    // success and clearing the lockfile entry, so a later `update` wouldn't
-    // catch it either (ahood-cli final review finding #2).
+    // never a directory under .claude/skills/ -- distinct from the dir check above.
     const agentFile = agentPath(owner, skill);
     const agentExisted = existsSync(agentFile);
-    if (agentExisted)
-        unlinkSync(agentFile);
-    const hadLockfileEntry = removeLockfileEntry(LOCKFILE_PATH, key);
+    const hadLockfileEntry = key in readLockfile(LOCKFILE_PATH);
     if (!dirExisted && !agentExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
         return;
     }
+    // Matches unpublish.ts/group.ts's confirm-before-destroy pattern (CLAUDE.md:
+    // "Destructive commands ... prompt for confirmation unless --yes is passed").
+    // Checked only once something is actually installed, so a no-op remove of an
+    // uninstalled skill never blocks on a prompt (ahood-cli#98).
+    const confirmed = yes ? true : await confirm(`Remove ${key} from this project? Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
+    if (dirExisted)
+        rmSync(dir, { recursive: true, force: true });
+    if (agentExisted)
+        unlinkSync(agentFile);
+    removeLockfileEntry(LOCKFILE_PATH, key);
     // An mcp-kind install has no directory or agent file on disk -- its only
     // footprint here is the lockfile entry just cleared above and a live
     // entry in .mcp.json (which add.ts's installMcpEntry merged in, possibly

package/dist/commands/search.js

@@ -1,5 +1,5 @@
 import { apiJson } from "../http.js";
-import { flagValue } from "../flags.js";
+import { flagValue, parseSearchQuery } from "../flags.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill search <query> [--json] [--limit <n>]";
 export async function searchSkills(query, limit) {
@@ -12,13 +12,7 @@ export async function searchSkills(query, limit) {
 export async function search(args) {
     const jsonOutput = args.includes("--json");
     const limitStr = flagValue(args, "--limit");
-    const queryParts = args.filter((a, i) => a !== "--json" && a !== "--limit" && args[i - 1] !== "--limit");
-    const unknownFlag = queryParts.find((a) => a.startsWith("--"));
-    if (unknownFlag)
-        throw new UsageError(`Unknown flag: ${unknownFlag}\n${USAGE}`);
-    const query = queryParts.join(" ");
-    if (!query)
-        throw new UsageError(USAGE);
+    const query = parseSearchQuery(args, USAGE);
     if (limitStr !== undefined && (!/^\d+$/.test(limitStr) || Number(limitStr) < 1)) {
         throw new UsageError(`--limit must be a positive integer (got "${limitStr}").\n${USAGE}`);
     }
@@ -33,7 +27,11 @@ export async function search(args) {
         return;
     }
     for (const skill of skills) {
-        console.log(`${skill.profiles.username}/${skill.slug} - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads)`);
+        // profiles comes from a server-side join that can plausibly be null for
+        // an individual row (orphaned skill, deleted owner account) -- degrade
+        // that one row instead of crashing the whole command (ahood-cli#106).
+        const username = skill.profiles?.username ?? "(unknown)";
+        console.log(`${username}/${skill.slug} - ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads)`);
     }
     if (limit !== undefined && skills.length >= limit) {
         console.log(`(showing up to ${limit} results -- pass a higher --limit for more)`);

package/dist/commands/snap.js

@@ -0,0 +1,191 @@
+import { apiJson } from "../http.js";
+import { flagValue, parseSearchQuery } from "../flags.js";
+import { confirm } from "../confirm.js";
+import { UsageError } from "../usage-error.js";
+const CREATE_USAGE = "Usage: ahood snap create <content> (or pipe content on stdin)";
+const LIST_USAGE = "Usage: ahood snap list [--json] [--limit <n>]";
+const SEARCH_USAGE = "Usage: ahood snap search <query> [--json] [--limit <n>]";
+const SHOW_USAGE = "Usage: ahood snap show <id> [--json]";
+const REMOVE_USAGE = "Usage: ahood snap remove <id> [--yes]";
+const SHARE_USAGE = "Usage: ahood snap share <id> [--json]";
+const UNSHARE_USAGE = "Usage: ahood snap unshare <id> [--yes]";
+// There's no existing "read stdin to completion" helper in this codebase to
+// reuse -- confirm.ts and secret-prompt.ts both only ever read a single
+// line via readline, never an arbitrary-length paste/pipe. Standard Node
+// read-to-end pattern: accumulate 'data' chunks until 'end'.
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+function validateLimit(limitStr, usage) {
+    if (limitStr !== undefined && (!/^\d+$/.test(limitStr) || Number(limitStr) < 1)) {
+        throw new UsageError(`--limit must be a positive integer (got "${limitStr}").\n${usage}`);
+    }
+}
+// Shared by list/search -- both print the same one-line-per-snap shape and
+// the same --json passthrough (the raw `snaps` array, matching
+// search.ts/list.ts's convention of emitting just the result array, not the
+// whole {snaps, next_cursor} envelope -- neither command exposes cursor-based
+// pagination today, only --limit, per ahood-cli#107's spec).
+function printSnaps(jsonOutput, snaps, emptyMessage) {
+    if (jsonOutput) {
+        console.log(JSON.stringify(snaps));
+        return;
+    }
+    if (snaps.length === 0) {
+        console.log(emptyMessage);
+        return;
+    }
+    for (const snap of snaps) {
+        // content_preview can plausibly contain the note's own internal
+        // newlines (it's freeform text) -- collapsed to spaces and re-truncated
+        // here so one snap never spills across multiple terminal lines and
+        // breaks the "one line per snap" contract.
+        const flat = snap.content_preview.replace(/\s+/g, " ").trim();
+        const preview = flat.length > 60 ? `${flat.slice(0, 60)}...` : flat;
+        console.log(`${snap.id} - ${preview} (${snap.created_at})${snap.shared ? " (shared)" : ""}`);
+    }
+}
+export async function createSnap(args) {
+    const jsonOutput = args.includes("--json");
+    // Joined, not just args[0] -- an unquoted multi-word note (e.g. `ahood
+    // snap create Debugged the flaky CI step`) arrives as multiple positional
+    // tokens, and taking only the first one silently dropped the rest with no
+    // error. Mirrors searchSnaps' own query-joining below.
+    const positionals = args.filter((a) => a !== "--json");
+    const positional = positionals.length > 0 ? positionals.join(" ") : undefined;
+    let content;
+    if (positional !== undefined) {
+        content = positional;
+    }
+    else {
+        // No positional content -- fall back to stdin (echo "..." | ahood snap
+        // create, or a piped heredoc), same convention as e.g. `git commit -F
+        // -`. A TTY with nothing piped in would otherwise hang forever waiting
+        // for input that will never arrive -- this CLI must never hang
+        // indefinitely for unattended/agent use (same reasoning as http.ts's
+        // 30s request timeout) -- so that case fails fast with the usage error
+        // instead of blocking on readStdin().
+        if (process.stdin.isTTY)
+            throw new UsageError(CREATE_USAGE);
+        content = await readStdin();
+    }
+    if (!content.trim())
+        throw new UsageError(CREATE_USAGE);
+    const created = await apiJson("/api/v1/snaps", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ content }),
+    });
+    if (jsonOutput) {
+        console.log(JSON.stringify(created));
+        return;
+    }
+    console.log(created.id);
+}
+export async function listSnaps(args) {
+    const jsonOutput = args.includes("--json");
+    const limitStr = flagValue(args, "--limit");
+    validateLimit(limitStr, LIST_USAGE);
+    const qs = new URLSearchParams();
+    if (limitStr !== undefined)
+        qs.set("limit", limitStr);
+    const query = qs.toString();
+    const { snaps } = await apiJson(`/api/v1/snaps${query ? `?${query}` : ""}`);
+    // ?? [], not a bare destructure -- a degraded response (snaps: null)
+    // must degrade to "no snaps" instead of crashing, matching list.ts/
+    // search.ts's own guard for the identical shape (ahood-cli#106).
+    printSnaps(jsonOutput, snaps ?? [], "You have no snaps yet. Run `ahood snap create <content>` to make one.");
+}
+export async function searchSnaps(args) {
+    const jsonOutput = args.includes("--json");
+    const limitStr = flagValue(args, "--limit");
+    const query = parseSearchQuery(args, SEARCH_USAGE);
+    validateLimit(limitStr, SEARCH_USAGE);
+    const qs = new URLSearchParams({ q: query });
+    if (limitStr !== undefined)
+        qs.set("limit", limitStr);
+    const { snaps } = await apiJson(`/api/v1/snaps?${qs}`);
+    // ?? [] -- see listSnaps' identical guard above (ahood-cli#106).
+    printSnaps(jsonOutput, snaps ?? [], "No snaps found.");
+}
+export async function showSnap(args) {
+    const jsonOutput = args.includes("--json");
+    const id = args.find((a) => !a.startsWith("--"));
+    if (!id)
+        throw new UsageError(SHOW_USAGE);
+    const snap = await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}`);
+    if (jsonOutput) {
+        console.log(JSON.stringify(snap));
+        return;
+    }
+    // Plain mode prints the raw content verbatim -- no formatting/labels/
+    // trailing decoration -- mirroring read.ts's own plain-mode contract
+    // exactly, process.stdout.write and not console.log: console.log
+    // unconditionally appends its own "\n", which double-adds a trailing
+    // blank line when the content already ends in one (ahood-cli#108).
+    process.stdout.write(snap.content);
+}
+export async function removeSnap(args) {
+    const id = args.find((a) => !a.startsWith("--"));
+    if (!id)
+        throw new UsageError(REMOVE_USAGE);
+    const yes = args.includes("--yes");
+    // Matches remove.ts/group.ts's confirm-before-destroy pattern (CLAUDE.md:
+    // "Destructive commands ... prompt for confirmation unless --yes is
+    // passed") -- deletion is irreversible per the API contract, same class
+    // of mistake ahood-cli#98/#99 already fixed for other commands.
+    const confirmed = yes ? true : await confirm(`Delete snap ${id}? Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
+    await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}`, { method: "DELETE" });
+    console.log(`Deleted snap ${id}.`);
+}
+export async function shareSnap(args) {
+    const jsonOutput = args.includes("--json");
+    const id = args.find((a) => !a.startsWith("--"));
+    if (!id)
+        throw new UsageError(SHARE_USAGE);
+    // POST .../share is documented idempotent -- mints a link on first call,
+    // returns the same existing one on any later call -- so this never needs
+    // a confirm() gate: re-running it can't clobber or duplicate anything.
+    const { share_url } = await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}/share`, {
+        method: "POST",
+    });
+    if (jsonOutput) {
+        console.log(JSON.stringify({ share_url }));
+        return;
+    }
+    console.log(share_url);
+}
+export async function unshareSnap(args) {
+    const id = args.find((a) => !a.startsWith("--"));
+    if (!id)
+        throw new UsageError(UNSHARE_USAGE);
+    const yes = args.includes("--yes");
+    // Not destructive in the data-loss sense -- the snap itself is untouched,
+    // and re-sharing mints/returns a link exactly as before (share is
+    // idempotent). But whoever the old link was handed to loses access the
+    // instant this runs, with no warning otherwise -- a real effect even
+    // though it's recoverable by re-running `share`. Gated the same way as
+    // every other snap verb with a live, external side effect (remove,
+    // and by analogy group.ts's removeMember/leaveGroup) for consistency
+    // across this command group, rather than carving out a silent exception
+    // here just because the data itself survives.
+    const confirmed = yes ? true : await confirm(`Revoke the share link for snap ${id}? Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
+    await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}/share`, { method: "DELETE" });
+    console.log(`Unshared snap ${id}.`);
+}

package/dist/flags.js

@@ -28,3 +28,21 @@ export function flagValue(args, flag) {
     }
     return undefined;
 }
+// Shared by every "<verb> <query> [--json] [--limit <n>]" command (skill
+// search, snap search) -- factored out after this exact logic was
+// duplicated verbatim between them, which is exactly how ahood-cli#105's
+// "--limit=5 misparsed as an unknown flag" bug could have silently come
+// back in one copy while being fixed in the other. Strips --json and
+// --limit (both "--limit N" and "--limit=N" forms) from the positional
+// args, rejects any other unrecognized "--" flag, and joins what's left
+// into a single query string.
+export function parseSearchQuery(args, usage) {
+    const queryParts = args.filter((a, i) => a !== "--json" && a !== "--limit" && !a.startsWith("--limit=") && args[i - 1] !== "--limit");
+    const unknownFlag = queryParts.find((a) => a.startsWith("--"));
+    if (unknownFlag)
+        throw new UsageError(`Unknown flag: ${unknownFlag}\n${usage}`);
+    const query = queryParts.join(" ");
+    if (!query)
+        throw new UsageError(usage);
+    return query;
+}

package/dist/help.js

@@ -117,9 +117,9 @@ export const SKILL_COMMANDS_HELP = [
         examples: ["ahood skill outdated", "ahood skill outdated alice/pdf-tools --json"],
     },
     {
-        usage: "ahood skill remove <owner>/<skill>",
-        summary: "Uninstall and unpin a skill (local only).",
-        desc: "Uninstall and unpin (local only).",
+        usage: "ahood skill remove <owner>/<skill> [--yes]",
+        summary: "Uninstall and unpin a skill (local only, prompts for confirmation unless --yes is passed).",
+        desc: "Uninstall and unpin (local only). Prompts for confirmation unless --yes is passed.",
     },
     {
         usage: "ahood skill edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]",
@@ -246,15 +246,19 @@ export const GROUP_COMMANDS_HELP = [
         ],
     },
     {
-        usage: "ahood group remove-member <group> <username>",
-        summary: "Remove a member from a group you own.",
+        usage: "ahood group remove-member <group> <username> [--yes]",
+        summary: "Remove a member from a group you own (prompts for confirmation unless --yes is passed).",
         desc: "Remove a member from a group you own. The group's owner cannot be removed this way -- delete the " +
-            "group instead. Only the group's owner can remove someone other than themselves.",
+            "group instead. Only the group's owner can remove someone other than themselves. Prompts for a typed " +
+            "\"yes\" unless --yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
     {
-        usage: "ahood group leave <group>",
-        summary: "Leave a group you belong to.",
-        desc: "Leave a group you belong to. The group's owner cannot leave -- delete the group instead.",
+        usage: "ahood group leave <group> [--yes]",
+        summary: "Leave a group you belong to (prompts for confirmation unless --yes is passed).",
+        desc: "Leave a group you belong to. The group's owner cannot leave -- delete the group instead. Prompts for " +
+            "a typed \"yes\" unless --yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
     {
         usage: "ahood group delete <group> [--yes]",
@@ -264,6 +268,68 @@ export const GROUP_COMMANDS_HELP = [
         flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
 ];
+// Every snap-entity verb, all reached as `ahood snap <verb>` -- mirrors
+// GROUP_COMMANDS_HELP above, just for the "Snaps" feature (ahood-cli#107):
+// a private, freeform text note capturing "what happened this session",
+// searchable later by its owner, optionally shareable via a revocable link,
+// never public otherwise.
+export const SNAP_COMMANDS_HELP = [
+    {
+        usage: "ahood snap create <content> [--json]",
+        summary: "Capture a new private snap, from an argument or piped stdin.",
+        desc: "Capture a new private snap. Pass the content as an argument, or omit it and pipe content on stdin " +
+            "(e.g. `echo \"...\" | ahood snap create`, or a piped heredoc) -- useful for capturing a whole session's " +
+            "worth of freeform text at once. Prints the new snap's id on success.",
+        flags: ["--json    Emit {id, created_at} instead of just the bare id."],
+        examples: ['ahood snap create "Debugged the flaky CI step, root cause was a race in the cache key."', 'echo "..." | ahood snap create'],
+    },
+    {
+        usage: "ahood snap list [--json] [--limit <n>]",
+        summary: "List your own snaps, most recent first.",
+        desc: "List your own snaps: id, a truncated content preview, created_at, and a (shared) marker if shared.",
+        flags: [
+            "--json        Emit the raw snap objects instead of formatted lines.",
+            "--limit <n>   Cap the number of results.",
+        ],
+    },
+    {
+        usage: "ahood snap search <query> [--json] [--limit <n>]",
+        summary: "Search your own snaps by content.",
+        desc: "Search your own snaps by content. Same output shape as `ahood snap list`.",
+        flags: [
+            "--json        Emit the raw snap objects instead of formatted lines.",
+            "--limit <n>   Cap the number of results.",
+        ],
+        examples: ["ahood snap search flaky-ci"],
+    },
+    {
+        usage: "ahood snap show <id> [--json]",
+        summary: "Print a single snap's full content.",
+        desc: "Print a single snap's full content. Plain mode prints the raw content verbatim to stdout -- no " +
+            "formatting, no labels -- so it's safe to pipe into a file or another tool.",
+        flags: ["--json    Emit the full snap object instead of the raw content."],
+    },
+    {
+        usage: "ahood snap remove <id> [--yes]",
+        summary: "Permanently delete a snap (prompts for confirmation unless --yes is passed).",
+        desc: "Permanently delete a snap. Irreversible. Prompts for a typed \"yes\" unless --yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+    },
+    {
+        usage: "ahood snap share <id> [--json]",
+        summary: "Mint (or return the existing) shareable link for a snap.",
+        desc: "Mint or return the existing shareable link for a snap. Idempotent -- safe to run more than once.",
+        flags: ["--json    Emit {share_url} instead of just the bare URL."],
+    },
+    {
+        usage: "ahood snap unshare <id> [--yes]",
+        summary: "Revoke a snap's share link (the snap itself is untouched; prompts for confirmation unless --yes is passed).",
+        desc: "Revoke a snap's share link -- the snap itself is untouched, and re-running `ahood snap share` mints a new " +
+            "link. Prompts for a typed \"yes\" unless --yes is passed, since anyone using the old link loses access " +
+            "immediately.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+    },
+];
 // Exported so other consumers of the command list (e.g. shell completion) can
 // surface aliases without needing their own copy of this map. Aliases apply
 // at the skill-verb level today (e.g. "show" for "view"); nothing at the
@@ -276,6 +342,7 @@ export const COMMAND_ALIASES = { show: "view" };
 const ENTITY_COMMANDS_HELP = {
     skill: SKILL_COMMANDS_HELP,
     group: GROUP_COMMANDS_HELP,
+    snap: SNAP_COMMANDS_HELP,
 };
 // Two-token lookup for an entity verb (findCommandHelp("skill", "search"),
 // findCommandHelp("group", "create")) or a single-token lookup for a
@@ -283,6 +350,16 @@ const ENTITY_COMMANDS_HELP = {
 export function findCommandHelp(command, subcommand) {
     const entityList = ENTITY_COMMANDS_HELP[command];
     if (entityList && subcommand !== undefined) {
+        // Try the literal verb first -- COMMAND_ALIASES is a single global map
+        // ("show" -> "view", for skill's alias), but a different entity can
+        // have its own real verb that happens to share the alias's name (e.g.
+        // `ahood snap show`, a real verb, not an alias for anything). Resolving
+        // through COMMAND_ALIASES unconditionally would send that lookup to a
+        // nonexistent "ahood snap view" entry instead of the literal "ahood
+        // snap show" one that's actually in this list.
+        const literal = entityList.find((c) => c.usage.startsWith(`ahood ${command} ${subcommand} `) || c.usage === `ahood ${command} ${subcommand}`);
+        if (literal)
+            return literal;
         const resolved = COMMAND_ALIASES[subcommand] ?? subcommand;
         return entityList.find((c) => c.usage.startsWith(`ahood ${command} ${resolved} `) || c.usage === `ahood ${command} ${resolved}`);
     }
@@ -403,18 +480,34 @@ export function formatGroupHelp() {
         "Run `ahood group <command> --help` for a single command's flags and examples.",
     ].join("\n");
 }
+// `ahood snap --help` -- the group-level listing for every snap verb.
+export function formatSnapHelp() {
+    const lines = formatCommandTable(SNAP_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })));
+    return [
+        "ahood snap -- capture and search private, session-scoped notes",
+        "",
+        "Commands:",
+        ...lines,
+        "",
+        "Run `ahood snap <command> --help` for a single command's flags and examples.",
+    ].join("\n");
+}
 // `ahood --help` -- the top-level listing: account commands rendered in
-// full, plus a single summary line each pointing at `ahood skill --help`
-// and `ahood group --help` for their (much longer) entity command lists.
+// full, plus a single summary line each pointing at `ahood skill --help`,
+// `ahood group --help`, and `ahood snap --help` for their (much longer)
+// entity command lists.
 export function formatHelp() {
     const skillGroupUsage = "ahood skill <command>";
     const skillGroupSummary = "Search, install, and publish skills -- run `ahood skill --help` for the full list.";
     const groupGroupUsage = "ahood group <command>";
     const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
+    const snapGroupUsage = "ahood snap <command>";
+    const snapGroupSummary = "Capture and search private, session-scoped notes -- run `ahood snap --help` for the full list.";
     const lines = formatCommandTable([
         ...TOP_LEVEL_COMMANDS_HELP.map((c) => ({ usage: usageWithAliases(c), summary: c.summary })),
         { usage: skillGroupUsage, summary: skillGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
+        { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
     return [
         "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
@@ -430,6 +523,7 @@ export function formatHelp() {
         "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
         "Run `ahood skill --help` for the full list of skill commands.",
         "Run `ahood group --help` for the full list of group commands.",
+        "Run `ahood snap --help` for the full list of snap commands.",
         "Run `ahood --version` to print the installed CLI version.",
         "",
         "Exit codes: 0 success, 1 general error, 2 usage/validation error,",

package/dist/http.js

@@ -65,8 +65,17 @@ export async function apiJson(path, init = {}) {
             : `Request failed with status ${res.status}`;
         throw new ApiError(res.status, message);
     }
+    // A 204 No Content (or any 2xx with an empty body) has nothing to parse --
+    // res.json() throws on empty input, which previously surfaced as a
+    // generic "Malformed response" error even though the request succeeded
+    // (ahood-cli#103). Callers that don't need response data (e.g. token
+    // revoke, which awaits this without using the result) get `undefined`
+    // back instead of a spurious failure.
+    const text = await res.text();
+    if (text === "")
+        return undefined;
     try {
-        return (await res.json());
+        return JSON.parse(text);
     }
     catch {
         throw new Error(`Malformed response from ${getApiUrl()}${path}: expected JSON.`);

package/dist/index.js

@@ -22,7 +22,8 @@ import { completion } from "./commands/completion.js";
 import { mcp } from "./commands/mcp.js";
 import { init } from "./commands/init.js";
 import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
-import { formatHelp, formatSkillHelp, formatGroupHelp, formatCommandHelp, findCommandHelp } from "./help.js";
+import { createSnap, listSnaps, searchSnaps, showSnap, removeSnap, shareSnap, unshareSnap, } from "./commands/snap.js";
+import { formatHelp, formatSkillHelp, formatGroupHelp, formatSnapHelp, formatCommandHelp, findCommandHelp } from "./help.js";
 import { ApiError } from "./http.js";
 import { exitCodeFor } from "./exit-code.js";
 import { CLI_NAME, CLI_VERSION } from "./version.js";
@@ -68,10 +69,22 @@ const GROUP_VERBS = {
     leave: leaveGroup,
     delete: deleteGroup,
 };
+// Every snap-entity verb, reached only as `ahood snap <verb>` -- see
+// dispatchSnap() below. Mirrors GROUP_VERBS above exactly; a snap is a pure
+// API-client entity like a group, with no local filesystem footprint.
+const SNAP_VERBS = {
+    create: createSnap,
+    list: listSnaps,
+    search: searchSnaps,
+    show: showSnap,
+    remove: removeSnap,
+    share: shareSnap,
+    unshare: unshareSnap,
+};
 // Top level is now just account/auth-scoped commands (not entity-specific --
-// same reasoning `gh auth login` isn't `gh account login`) plus the `skill`
-// and `group` entity groups. Future entities (e.g. "personality",
-// "protocols") get their own entry here alongside these two.
+// same reasoning `gh auth login` isn't `gh account login`) plus the `skill`,
+// `group`, and `snap` entity groups. Future entities get their own entry
+// here alongside these.
 const COMMANDS = {
     login: () => login(),
     logout: () => logout(),
@@ -81,6 +94,7 @@ const COMMANDS = {
     mcp,
     skill: dispatchSkill,
     group: dispatchGroup,
+    snap: dispatchSnap,
 };
 // Commands whose handler owns its own --help handling (at both the group
 // level, e.g. `ahood skill --help` / `ahood group --help`, and the per-verb
@@ -88,8 +102,9 @@ const COMMANDS = {
 // instead of the generic top-level interception in main(). Despite the
 // name, this Set has nothing to do with the "Groups" feature -- "group"
 // here just means "a command that owns its own sub-verb dispatch", the same
-// sense "skill" already used before "group" (the entity) existed.
-const GROUP_COMMANDS = new Set(["skill", "group"]);
+// sense "skill" already used before "group" (the entity) existed. "snap"
+// joins this set for the exact same reason (ahood-cli#107).
+const GROUP_COMMANDS = new Set(["skill", "group", "snap"]);
 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++)
@@ -124,6 +139,9 @@ function closestSkillCommand(input) {
 function closestGroupVerb(input) {
     return closestOf(input, Object.keys(GROUP_VERBS));
 }
+function closestSnapVerb(input) {
+    return closestOf(input, Object.keys(SNAP_VERBS));
+}
 // `ahood skill <verb> [...]` -- owns its own help handling at both the
 // group level (`ahood skill` / `ahood skill --help`) and the per-verb level
 // (`ahood skill <verb> --help`), since neither should fall through to
@@ -175,6 +193,32 @@ async function dispatchGroup(args) {
     }
     await handler(rest);
 }
+// `ahood snap <verb> [...]` -- owns its own help handling at both the
+// group level (`ahood snap` / `ahood snap --help`) and the per-verb level
+// (`ahood snap <verb> --help`), exactly mirroring dispatchSkill()/
+// dispatchGroup() above.
+async function dispatchSnap(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === "--help" || sub === "-h") {
+        console.log(formatSnapHelp());
+        return;
+    }
+    const handler = SNAP_VERBS[sub];
+    if (!handler) {
+        console.error(`Unknown snap command: ${sub}`);
+        const suggestion = closestSnapVerb(sub);
+        if (suggestion)
+            console.error(`Did you mean '${suggestion}'?`);
+        console.error("Run `ahood snap --help` for a list of commands.");
+        process.exit(2);
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        const entry = findCommandHelp("snap", sub);
+        console.log(entry ? formatCommandHelp(entry) : formatSnapHelp());
+        return;
+    }
+    await handler(rest);
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (command === "--version" || command === "-v") {
@@ -195,6 +239,12 @@ async function main() {
             console.log(entry ? formatCommandHelp(entry) : formatGroupHelp());
             return;
         }
+        if (sub === "snap") {
+            const verb = args[1];
+            const entry = verb ? findCommandHelp("snap", verb) : undefined;
+            console.log(entry ? formatCommandHelp(entry) : formatSnapHelp());
+            return;
+        }
         const entry = sub ? findCommandHelp(sub) : undefined;
         console.log(entry ? formatCommandHelp(entry) : formatHelp());
         return;
@@ -223,8 +273,10 @@ async function main() {
         console.error("Run `ahood help` for a list of commands.");
         process.exit(2);
     }
-    // Group commands (currently just "skill") own their own --help handling
-    // at both the group and per-verb level -- don't intercept here.
+    // Entities with their own sub-dispatch ("skill", "group", "snap" --
+    // GROUP_COMMANDS despite the name, unrelated to the "group" entity itself)
+    // own their own --help handling at both the entity and per-verb level --
+    // don't intercept here.
     if (!GROUP_COMMANDS.has(command) && (args.includes("--help") || args.includes("-h"))) {
         const entry = findCommandHelp(command);
         console.log(entry ? formatCommandHelp(entry) : formatHelp());
@@ -257,4 +309,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchGroup, COMMANDS, SKILL_COMMANDS, GROUP_VERBS };
+export { main, dispatchSkill, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/lockfile.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
@@ -31,24 +31,83 @@ export function writeJsonFileAtomic(path, data) {
 function writeLockfile(path, lockfile) {
     writeJsonFileAtomic(path, lockfile);
 }
+// A lock directory is stale if the PID recorded inside it (written by the
+// acquirer below) belongs to a process that's no longer running -- signal 0
+// doesn't actually deliver a signal, just probes whether the process could
+// be signaled. ESRCH means it's dead; EPERM means it's alive but owned by
+// someone else, which is conservatively treated as still alive since that
+// can't be disproven. A missing/unparseable pid file is also treated as
+// "not stale" -- either a lock from before this file existed, or another
+// process is still mid-way through acquiring (mkdirSync succeeded, the pid
+// write hasn't landed yet) -- safer to wait it out than to reclaim a lock
+// that's actually still being set up.
+function isLockStale(pidFile) {
+    let pidText;
+    try {
+        pidText = readFileSync(pidFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const pid = Number(pidText);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
 // Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
 // so two concurrent `ahood skill add`/`remove` invocations against the same
 // project don't race a read-modify-write and silently drop one another's
 // entry. Exported so other same-directory JSON files with the same
 // read-modify-write shape (e.g. add.ts's .mcp.json merge) can reuse it
 // instead of duplicating the pattern.
+//
+// The lock directory holds a `pid` file naming its holder, so a process
+// that finds the lock held can tell a live holder from one that was
+// hard-killed (SIGKILL/OOM) mid-critical-section: without this, such a lock
+// is never released, and every subsequent add/remove/update in that project
+// busy-waits out the full timeout below and then fails permanently until a
+// human manually deletes the stale directory (ahood-cli#100).
 export function withLock(path, fn) {
     mkdirSync(dirname(path), { recursive: true });
     const lockDir = `${path}.lock`;
+    const pidFile = join(lockDir, "pid");
     const deadline = Date.now() + 5000;
     for (;;) {
         try {
             mkdirSync(lockDir);
+            // Best-effort: mkdirSync above is what actually holds the lock: if
+            // this write fails for some reason, the lock is still correctly held,
+            // just without staleness detection for this particular acquisition.
+            try {
+                writeFileSync(pidFile, String(process.pid));
+            }
+            catch {
+                // non-fatal, see comment above
+            }
             break;
         }
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
+            if (isLockStale(pidFile)) {
+                // Reclaim it. Best-effort removal: if a concurrent process wins the
+                // race and reclaims (or a live holder finishes and releases) first,
+                // this just falls through to the normal wait/retry below instead of
+                // throwing.
+                try {
+                    rmSync(lockDir, { recursive: true, force: true });
+                }
+                catch {
+                    // lost the race -- fall through to wait/retry
+                }
+                continue;
+            }
             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.`);
             }
@@ -59,7 +118,7 @@ export function withLock(path, fn) {
         return fn();
     }
     finally {
-        rmdirSync(lockDir);
+        rmSync(lockDir, { recursive: true, force: true });
     }
 }
 export function writeLockfileEntry(path, ownerSlashSkill, entry) {
@@ -69,6 +128,40 @@ export function writeLockfileEntry(path, ownerSlashSkill, entry) {
         writeLockfile(path, lockfile);
     });
 }
+// Thrown by writeLockfileEntryVerifyingChecksum -- carries the conflicting
+// entry so the caller (add.ts) can build its own user-facing message and
+// decide what to roll back (an already-extracted skill dir, an already-
+// written agent file, an already-merged .mcp.json entry).
+export class LockfileChecksumConflictError extends Error {
+    existing;
+    constructor(existing) {
+        super("Lockfile checksum conflict");
+        this.existing = existing;
+    }
+}
+// add.ts's checksum-pin tamper-detection guard used to read the lockfile
+// (unlocked) well before the eventual writeLockfileEntry call, which
+// acquires its OWN, separate lock later -- two independently-locked steps,
+// not one atomic operation. Under concurrent installs of "the same"
+// version with different (tampered) checksums, both processes' unlocked
+// reads could see no conflict, so both writes would proceed and whichever
+// wins the later lock silently overwrites the other with no error ever
+// surfaced -- exactly the tampering this guard exists to catch
+// (ahood-cli#101). Performing the read, the check, and the write inside one
+// locked critical section closes that window: whichever caller's write
+// actually lands is checked against the lockfile state as it exists AT
+// THAT MOMENT, not a possibly-stale snapshot from earlier.
+export function writeLockfileEntryVerifyingChecksum(path, ownerSlashSkill, entry) {
+    withLock(path, () => {
+        const lockfile = readLockfile(path);
+        const existing = lockfile[ownerSlashSkill];
+        if (existing && existing.version === entry.version && existing.checksum_sha256 !== entry.checksum_sha256) {
+            throw new LockfileChecksumConflictError(existing);
+        }
+        lockfile[ownerSlashSkill] = entry;
+        writeLockfile(path, lockfile);
+    });
+}
 export function removeLockfileEntry(path, ownerSlashSkill) {
     return withLock(path, () => {
         const lockfile = readLockfile(path);

package/dist/spec.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { UsageError } from "./usage-error.js";
-// Owner and skill segments become filesystem path components (.claude/skills/<owner>/<skill>)
+// 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).
@@ -76,23 +76,34 @@ export function validateExternalUrl(value, flag) {
 }
 export const SKILLS_ROOT = join(".claude", "skills");
 export const LOCKFILE_PATH = join(".claude", "skills.lock.json");
+// Claude Code's own project-skill loader scans .claude/skills/ exactly one
+// level deep (each immediate child directory is checked for a SKILL.md),
+// not recursively -- so the previous owner-nested layout
+// (.claude/skills/<owner>/<skill>/SKILL.md) was never discovered by Claude
+// Code at all; it only ever worked via this CLI's own commands (ahood-cli#96).
+// Joining owner and skill into one flat directory name with "@" fixes that
+// while staying collision-resistant, mirroring agentPath below: SEGMENT_RE's
+// character class [a-z0-9._-] (case-insensitive) never contains "@", so the
+// joined name always has exactly one "@", unambiguous for any pair of
+// SEGMENT_RE-valid values. "@" is a valid path-segment character on Linux,
+// macOS, and Windows.
 export function skillDir(owner, skill) {
-    return join(SKILLS_ROOT, owner, skill);
+    return join(SKILLS_ROOT, `${owner}@${skill}`);
 }
 // Claude Code's own subagent loader scans .claude/agents/*.md as flat files
-// (non-recursive), unlike .claude/skills/<owner>/<skill>/ which nests by
-// owner -- a bare .claude/agents/<skill>.md would let two different owners'
-// same-named agent collide and silently overwrite each other. Joining the
-// owner into the filename with "@" keeps the layout flat (so Claude Code
-// still finds it) while staying collision-resistant: SEGMENT_RE's character
-// class is exactly [a-z0-9._-] (case-insensitive), which does not include
-// "@" -- so "@" can never appear inside a valid owner or skill segment, and
-// the joined filename always contains exactly one "@", at the boundary
-// between the two segments. That makes the join unambiguous for any pair of
-// SEGMENT_RE-valid values, including ones containing hyphens (e.g.
-// owner="al-ice"/skill="bob" joins to "al-ice@bob.md", which cannot also be
-// produced by any other valid owner/skill pair). "@" is a valid filename
-// character on Linux, macOS, and Windows.
+// (non-recursive), same reasoning as skillDir above -- a bare
+// .claude/agents/<skill>.md would let two different owners' same-named agent
+// collide and silently overwrite each other. Joining the owner into the
+// filename with "@" keeps the layout flat (so Claude Code still finds it)
+// while staying collision-resistant: SEGMENT_RE's character class is exactly
+// [a-z0-9._-] (case-insensitive), which does not include "@" -- so "@" can
+// never appear inside a valid owner or skill segment, and the joined
+// filename always contains exactly one "@", at the boundary between the two
+// segments. That makes the join unambiguous for any pair of SEGMENT_RE-valid
+// values, including ones containing hyphens (e.g. owner="al-ice"/skill="bob"
+// joins to "al-ice@bob.md", which cannot also be produced by any other valid
+// owner/skill pair). "@" is a valid filename character on Linux, macOS, and
+// Windows.
 export const AGENTS_ROOT = join(".claude", "agents");
 export function agentPath(owner, skill) {
     return join(AGENTS_ROOT, `${owner}@${skill}.md`);

package/package.json

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