@ahood/cli 0.8.0 → 0.8.2

package/README.md

@@ -243,13 +243,14 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 
 | Command | What it does |
 | --- | --- |
-| `ahood snap create <content> [--json]` | Capture a new private snap, from an argument or piped stdin. |
+| `ahood snap create <content> [--tags tag1,tag2] [--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). |
+| `ahood snap tags <id> [tag1,tag2,...] [--json]` | Replace a snap's tags (omit the tag list, or pass an empty one, to clear all tags). |
 <!-- COMMANDS_TABLE_END -->
 
 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.

package/dist/commands/add.js

@@ -325,7 +325,9 @@ function summarizeConflictingEntry(entry) {
 // raw TypeError, and would let `"mcpServers": []` pass the collision check
 // silently (an array's numeric-index write is then dropped entirely by
 // JSON.stringify), reporting a successful install that wrote nothing.
-function readMcpConfig() {
+// Exported so remove.ts/update.ts can read the same validated shape when
+// deciding whether it's safe to touch an mcp entry (ahood-cli#169).
+export function readMcpConfig() {
     if (!existsSync(MCP_CONFIG_PATH))
         return { mcpServers: {} };
     let parsed;
@@ -361,18 +363,40 @@ function assertNoCollision(fileContents, owner, skill) {
             `Remove it manually first if you want to reinstall ${owner}/${skill}.`);
     }
 }
-async function installMcpEntry(owner, skill, meta, buffer) {
+// Extracts server.json, validates its shape, and resolves every secret
+// environment variable it declares (prompting only for ones not already
+// set in the shell) -- the part of installing an mcp entry that's identical
+// whether this is a fresh `add` or an `update` moving an existing pin
+// forward. Exported so update.ts's real mcp-update path (ahood-cli#169)
+// re-resolves secrets the same way a fresh install does, instead of
+// duplicating this parsing/prompting logic.
+// `existingEnv` carries forward the secret values already sitting in the
+// entry being updated, so a routine `ahood skill update` doesn't re-prompt
+// for a credential the user has already supplied. Only ever passed by
+// updateMcpEntry, and only from an entry whose fingerprint it has just
+// verified -- i.e. proven to be ahood's own unmodified entry, not something
+// hand-edited or written by another tool.
+//
+// `allowNonTtyPrompt` (default true, preserving `echo secret | ahood skill
+// add ...` for a fresh install the user explicitly asked for) is false on
+// the update path: `ahood skill update` with no arguments walks EVERY locked
+// entry, so a prompt there is never something the caller aimed at. Left
+// interactive, an unattended update would hang on an idle pipe with no
+// timeout -- against this CLI's "must never hang" rule -- or, worse, silently
+// bank the first line of unrelated piped input (`echo y | ahood skill
+// update`) as the credential and fingerprint over it.
+export async function resolveMcpServerConfig(buffer, options = {}) {
+    const { existingEnv, allowNonTtyPrompt = true } = options;
     const content = await extractSingleFileContent(buffer, "server.json");
     const manifest = JSON.parse(content.toString("utf-8"));
     // Validate the manifest's shape (unsupported registry_type/runtime_hint,
-    // or neither a single 'packages' nor a single 'remotes' entry) and check
-    // for an existing .mcp.json collision BEFORE prompting for any secret --
-    // an install that's going to be refused anyway must not first cost the
-    // user a masked secret prompt. buildMcpServerConfig is called here with an
-    // empty env purely to run its validation/throw; the result is discarded
-    // and rebuilt below once secretEnv is known.
+    // or neither a single 'packages' nor a single 'remotes' entry) BEFORE
+    // prompting for any secret -- an install/update that's going to be
+    // refused anyway must not first cost the user a masked secret prompt.
+    // buildMcpServerConfig is called here with an empty env purely to run its
+    // validation/throw; the result is discarded and rebuilt below once
+    // secretEnv is known.
     buildMcpServerConfig(manifest, {});
-    assertNoCollision(readMcpConfig(), owner, skill);
     const envVars = manifest.packages?.[0]?.environment_variables ?? [];
     const secretEnv = {};
     for (const variable of envVars) {
@@ -384,11 +408,66 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         // (per the design spec), which uses `if (process.env.AHOOD_TOKEN)`
         // specifically so an empty-string env var falls through to the real
         // source instead of silently installing an empty secret.
-        secretEnv[variable.name] = fromEnv
-            ? fromEnv
-            : await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
+        if (fromEnv) {
+            secretEnv[variable.name] = fromEnv;
+            continue;
+        }
+        // Ordered after the env var deliberately: exporting the variable stays
+        // the way to rotate a credential during an update, rather than being
+        // shadowed by the stale value already on disk.
+        const carriedForward = existingEnv?.[variable.name];
+        if (carriedForward) {
+            secretEnv[variable.name] = carriedForward;
+            continue;
+        }
+        if (!allowNonTtyPrompt && !process.stdin.isTTY) {
+            throw new Error(`${sanitizeForTerminal(variable.name)} is required by ${sanitizeForTerminal(manifest.name)} but is not set, and there is no terminal to prompt on -- export ${sanitizeForTerminal(variable.name)} and re-run.`);
+        }
+        secretEnv[variable.name] = await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
     }
     const serverConfig = buildMcpServerConfig(manifest, secretEnv);
+    return { manifest, serverConfig };
+}
+// Fingerprint of exactly what ahood wrote into .mcp.json's mcpServers.<skill>
+// entry, stored in the lockfile alongside the version/checksum pin. Lets
+// remove/update (ahood-cli#169) tell "the on-disk entry is still exactly
+// what I last installed" from "something (the user, another tool) has since
+// hand-edited it" -- without this, a real (not just warned-about) removal
+// or update risks silently discarding an intentional local edit, the same
+// class of risk assertNoCollision below exists to prevent on a *fresh*
+// install. JSON.stringify's key order matches insertion order for a plain
+// object, and JSON.parse's key order matches source-text order -- so this
+// is stable between the object this process just built and the same object
+// read back from disk later, as long as nothing reorders keys in between.
+export function hashMcpServerConfig(config) {
+    return createHash("sha256").update(JSON.stringify(config)).digest("hex");
+}
+// Pulls the `env` map out of an .mcp.json entry read off disk, so an update
+// can carry its secrets forward (see resolveMcpServerConfig's `existingEnv`).
+// Written defensively -- the entry is `unknown` here, and only a string value
+// is usable as a credential -- even though the caller has already fingerprint-
+// verified it, so that a shape this function can't read degrades into a
+// prompt rather than a crash.
+function readMcpEntryEnv(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    const env = entry.env;
+    if (typeof env !== "object" || env === null)
+        return undefined;
+    const result = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (typeof value === "string")
+            result[name] = value;
+    }
+    return result;
+}
+async function installMcpEntry(owner, skill, meta, buffer) {
+    // Check for an existing .mcp.json collision BEFORE resolving secrets --
+    // matches resolveMcpServerConfig's own "don't cost the user a prompt for
+    // something that's going to be refused anyway" reasoning, just for the
+    // collision check specifically rather than the manifest-shape check.
+    assertNoCollision(readMcpConfig(), owner, skill);
+    const { serverConfig } = await resolveMcpServerConfig(buffer);
     // Read-modify-write under an advisory lock, mirroring lockfile.ts's own
     // writeLockfileEntry: .mcp.json sits right next to the lockfile and can
     // hold other servers' secrets, so it gets the same protection against a
@@ -406,7 +485,11 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     });
     const mcpKey = `${owner}/${skill}`;
     try {
-        writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, mcpKey, { version: meta.version, checksum_sha256: meta.checksum_sha256 });
+        writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, mcpKey, {
+            version: meta.version,
+            checksum_sha256: meta.checksum_sha256,
+            mcp_config_hash: hashMcpServerConfig(serverConfig),
+        });
     }
     catch (error) {
         if (!(error instanceof LockfileChecksumConflictError))
@@ -421,7 +504,125 @@ async function installMcpEntry(owner, skill, meta, buffer) {
         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) {
+    // Only the npm+npx package path ever carries secrets into `env` (headers
+    // on a remote entry are static per v1's scope, per buildMcpServerConfig) --
+    // checking the final serverConfig's own `env` key (rather than threading
+    // secretEnv out of resolveMcpServerConfig separately) means this warning
+    // can never drift from what was actually written to disk.
+    if (serverConfig.env && Object.keys(serverConfig.env).length > 0) {
+        console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
+    }
+}
+// Re-runs the mcp install flow for an already-installed entry, moving its
+// lockfile pin forward -- update.ts's real mcp-update path (ahood-cli#169).
+// Unlike installMcpEntry, "the entry already exists" is expected here (it's
+// the very entry being updated), so the safety check is inverted: rather
+// than refusing because something's already there, this refuses UNLESS the
+// on-disk entry's fingerprint still matches what was recorded at the last
+// install/update -- same posture as assertNoCollision, applied to "is this
+// still mine to touch" instead of "is this mine to create". If the entry is
+// missing entirely, there's nothing to protect -- write fresh (self-heals a
+// lockfile pin whose .mcp.json entry was deleted by hand without going
+// through `ahood skill remove`). If it's present but doesn't match (or no
+// fingerprint was ever recorded, e.g. an entry installed before this field
+// existed), refuse rather than silently overwrite a possibly-intentional
+// local edit.
+export async function updateMcpEntry(owner, skill, meta, currentEntry) {
+    const key = `${owner}/${skill}`;
+    const recordedHash = currentEntry?.mcp_config_hash;
+    const fileContents = readMcpConfig();
+    const mcpServers = fileContents.mcpServers;
+    const existingOnDisk = Object.prototype.hasOwnProperty.call(mcpServers, skill) ? mcpServers[skill] : undefined;
+    // Both refusal messages below point at manually editing .mcp.json, not
+    // `ahood skill remove` -- remove refuses to delete an entry under
+    // exactly these same two conditions (no recorded fingerprint, or a
+    // fingerprint mismatch), so telling the user to "remove then add" would
+    // send them into a sequence where remove leaves the entry in place *and*
+    // clears the lockfile pin, and the follow-up add then fails on the very
+    // same entry as a collision -- pin gone, credential still live, no CLI
+    // path forward. Editing .mcp.json by hand and then running `add` is the
+    // only sequence that actually resolves the state.
+    if (existingOnDisk !== undefined) {
+        if (recordedHash === undefined) {
+            throw new Error(`Cannot verify ${key}'s .mcp.json entry matches what ahood last installed (no recorded fingerprint) -- delete the "${skill}" entry from mcpServers in .mcp.json by hand, then run \`ahood skill add ${key}\` to reinstall and enable automatic updates going forward.`);
+        }
+        if (hashMcpServerConfig(existingOnDisk) !== recordedHash) {
+            throw new Error(`${key}'s .mcp.json entry appears to have been modified since install -- refusing to overwrite it. Delete the "${skill}" entry from mcpServers in .mcp.json by hand, then run \`ahood skill add ${key}\` to reinstall.`);
+        }
+    }
+    const buffer = await downloadVerifiedArchive(owner, skill, meta);
+    // Reuse the secrets already in the entry rather than re-prompting for
+    // them. Safe to trust specifically because the fingerprint check above has
+    // just proven this is ahood's own unmodified entry; in the self-heal case
+    // (no entry on disk at all) there's nothing to carry forward and a genuine
+    // prompt is correct.
+    const existingEnv = readMcpEntryEnv(existingOnDisk);
+    const { serverConfig } = await resolveMcpServerConfig(buffer, { existingEnv, allowNonTtyPrompt: false });
+    // Read-modify-write under an advisory lock, mirroring installMcpEntry's
+    // own pattern. Re-checks the fingerprint here too (not just above) since
+    // arbitrary time may have passed since the pre-check -- the download, and
+    // any secret prompt inside resolveMcpServerConfig -- during which another
+    // process could have changed the entry.
+    let previousOnDisk;
+    withLock(MCP_CONFIG_PATH, () => {
+        const fresh = readMcpConfig();
+        const freshServers = fresh.mcpServers;
+        const freshExisting = Object.prototype.hasOwnProperty.call(freshServers, skill) ? freshServers[skill] : undefined;
+        if (freshExisting !== undefined && (recordedHash === undefined || hashMcpServerConfig(freshExisting) !== recordedHash)) {
+            throw new Error(`${key}'s .mcp.json entry changed while updating -- refusing to overwrite it. Re-run \`ahood skill update ${key}\` if this was unexpected.`);
+        }
+        previousOnDisk = freshExisting;
+        freshServers[skill] = serverConfig;
+        writeJsonFileAtomic(MCP_CONFIG_PATH, fresh);
+    });
+    try {
+        writeLockfileEntryVerifyingChecksum(LOCKFILE_PATH, key, {
+            version: meta.version,
+            checksum_sha256: meta.checksum_sha256,
+            mcp_config_hash: hashMcpServerConfig(serverConfig),
+        });
+    }
+    catch (error) {
+        // Roll back the .mcp.json overwrite above under the same lock pattern,
+        // restoring the entry to what it was before this update touched it --
+        // not deleting it, unlike installMcpEntry's rollback: unless this was
+        // the self-heal-a-missing-entry case (previousOnDisk undefined), there
+        // WAS a working entry here before this update began.
+        //
+        // Runs for EVERY lockfile failure, not just a checksum conflict. A
+        // rethrow-before-rollback here left .mcp.json holding the new config
+        // while the lockfile kept the old version and old mcp_config_hash, after
+        // which the fingerprint never matches again and both `update` and
+        // `remove` permanently refuse -- the exact dead end the comments above
+        // exist to prevent, reachable from nothing worse than withLock's 5s
+        // timeout against a concurrent ahood, or an EACCES/ENOSPC on the write.
+        try {
+            withLock(MCP_CONFIG_PATH, () => {
+                const fileContents = readMcpConfig();
+                const mcpServers = fileContents.mcpServers;
+                if (previousOnDisk === undefined) {
+                    delete mcpServers[skill];
+                }
+                else {
+                    mcpServers[skill] = previousOnDisk;
+                }
+                writeJsonFileAtomic(MCP_CONFIG_PATH, fileContents);
+            });
+        }
+        catch {
+            // The rollback can fail for the same reason the write did (lock still
+            // contended, disk still full). Warn rather than throw: the original
+            // error below is the more actionable one, and masking it with this
+            // one would hide why the update failed in the first place.
+            console.warn(`WARNING: could not roll back ${MCP_CONFIG_PATH} after ${key}'s update failed -- its mcpServers."${skill}" entry may be on the new version while ${LOCKFILE_PATH} still pins the old one. Delete that entry by hand and run \`ahood skill add ${key}\` to reinstall.`);
+        }
+        if (error instanceof LockfileChecksumConflictError) {
+            throw new Error(checksumConflictMessage(key, meta, error.existing));
+        }
+        throw error;
+    }
+    console.log(`Updated ${key} to ${meta.version}`);
+    if (serverConfig.env && Object.keys(serverConfig.env).length > 0) {
         console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
     }
 }

package/dist/commands/remove.js

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, rmSync, unlinkSync } from "node:fs";
 import { confirm } from "../confirm.js";
-import { readLockfile, removeLockfileEntry } from "../lockfile.js";
+import { readLockfile, removeLockfileEntry, withLock, writeJsonFileAtomic } from "../lockfile.js";
 import { LOCKFILE_PATH, parseOwnerSkill, skillDir, agentPath, MCP_CONFIG_PATH } from "../spec.js";
+import { readMcpConfig, hashMcpServerConfig } from "./add.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill remove <owner>/<skill> [--yes]";
 export async function remove(args) {
@@ -19,7 +20,8 @@ export async function remove(args) {
     // never a directory under .claude/skills/ -- distinct from the dir check above.
     const agentFile = agentPath(owner, skill);
     const agentExisted = existsSync(agentFile);
-    const hadLockfileEntry = key in readLockfile(LOCKFILE_PATH);
+    const lockEntry = readLockfile(LOCKFILE_PATH)[key];
+    const hadLockfileEntry = lockEntry !== undefined;
     if (!dirExisted && !agentExisted && !hadLockfileEntry) {
         console.error(`${key} was not installed -- nothing to remove.`);
         process.exitCode = 1;
@@ -42,30 +44,71 @@ export async function remove(args) {
     // 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
-    // holding a resolved secret in its `env`). remove() doesn't attempt a real
-    // mcp removal, but staying silent about that entry repeats the exact
-    // false-assurance bug already fixed once for agent installs above: a user
-    // who removes an mcp artifact because they no longer trust it would be
-    // told it's gone while the MCP server (and its credential) still runs on
-    // the next Claude Code start -- and since the lockfile pin is now cleared,
-    // nothing will ever surface this again via `list`/`update`. So: warn
-    // instead of pretending it's gone.
-    if (existsSync(MCP_CONFIG_PATH)) {
-        try {
-            const parsed = JSON.parse(readFileSync(MCP_CONFIG_PATH, "utf-8"));
-            const mcpServers = parsed?.mcpServers;
-            if (mcpServers &&
-                typeof mcpServers === "object" &&
-                !Array.isArray(mcpServers) &&
-                Object.prototype.hasOwnProperty.call(mcpServers, skill)) {
-                console.warn(`WARNING: ${key} still has an entry in ${MCP_CONFIG_PATH} (which may contain secrets you entered) -- remove it manually.`);
+    // holding a resolved secret in its `env`). Real removal (delete that one
+    // key) only happens when the on-disk entry's fingerprint still matches
+    // what was recorded at install/update time -- same posture as add.ts's
+    // own assertNoCollision: never blind-write/delete something this process
+    // didn't verify it still owns. Without SOME check here, "Removed" would
+    // repeat the exact false-assurance bug already fixed once for agent
+    // installs above (a user told it's gone while the MCP server, and its
+    // credential, still runs on the next Claude Code start) -- but a hand-
+    // edited entry (fingerprint mismatch, or no fingerprint recorded at all,
+    // e.g. an mcp entry installed before this field existed) is left in
+    // place and warned about instead, exactly as before this fix.
+    let removedMcpEntry = false;
+    let mcpEntryModified = false;
+    let mcpEntryPresent = false;
+    let recordedHash;
+    try {
+        const fileContents = readMcpConfig();
+        const mcpServers = fileContents.mcpServers;
+        mcpEntryPresent = Object.prototype.hasOwnProperty.call(mcpServers, skill);
+        if (mcpEntryPresent) {
+            recordedHash = lockEntry?.mcp_config_hash;
+            const currentHash = hashMcpServerConfig(mcpServers[skill]);
+            if (recordedHash !== undefined) {
+                mcpEntryModified = recordedHash !== currentHash;
             }
         }
+    }
+    catch {
+        // A malformed .mcp.json isn't this command's problem to fix or crash
+        // on -- add.ts's readMcpConfig is the strict validator for that path.
+        // mcpEntryPresent stays false, so there's nothing to warn about either:
+        // if we can't even read the file, we can't know whether this skill has
+        // an entry in it.
+    }
+    if (mcpEntryPresent && recordedHash !== undefined && !mcpEntryModified) {
+        try {
+            // Re-check under lock rather than trusting the read above -- another
+            // process could have changed or removed the entry in between,
+            // mirroring add.ts's own re-check-under-lock before it writes. This
+            // try/catch is deliberately separate from the read above: a failure
+            // HERE (a lock-acquisition timeout, an EACCES/ENOSPC/etc. write
+            // failure) must still fall through to the warning below rather than
+            // being silently swallowed -- letting it share the read's catch block
+            // was the exact bug that let a failed delete print a bare "Removed"
+            // with the credential still live (the false-assurance case this
+            // whole mechanism exists to prevent).
+            withLock(MCP_CONFIG_PATH, () => {
+                const fresh = readMcpConfig();
+                const freshServers = fresh.mcpServers;
+                if (Object.prototype.hasOwnProperty.call(freshServers, skill) &&
+                    hashMcpServerConfig(freshServers[skill]) === recordedHash) {
+                    delete freshServers[skill];
+                    writeJsonFileAtomic(MCP_CONFIG_PATH, fresh);
+                    removedMcpEntry = true;
+                }
+            });
+        }
         catch {
-            // A malformed .mcp.json isn't this command's problem to fix or crash
-            // on -- add.ts's readMcpConfig is the strict validator for that path.
-            // Skip the warning rather than throw here.
+            // removedMcpEntry stays false -- falls through to the warning below.
         }
     }
-    console.log(`Removed ${key}`);
+    if (mcpEntryPresent && !removedMcpEntry) {
+        console.warn(`WARNING: ${key} still has an entry in ${MCP_CONFIG_PATH} (which may contain secrets you entered)` +
+            (mcpEntryModified ? " -- it appears to have been modified since install" : "") +
+            ` -- remove it manually.`);
+    }
+    console.log(removedMcpEntry ? `Removed ${key} (including its ${MCP_CONFIG_PATH} entry)` : `Removed ${key}`);
 }

package/dist/commands/snap.js

@@ -2,13 +2,14 @@ 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 CREATE_USAGE = "Usage: ahood snap create <content> [--tags tag1,tag2] (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]";
+const TAGS_USAGE = "Usage: ahood snap tags <id> [tag1,tag2,...] [--json] (omit or pass an empty value to clear all tags)";
 // 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
@@ -50,16 +51,24 @@ function printSnaps(jsonOutput, snaps, emptyMessage) {
         // 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)" : ""}`);
+        // ?? [] -- see listSnaps/searchSnaps' identical degrade-on-null guard
+        // below; a snap predating the tags column, or a degraded response,
+        // should just show no tags rather than crashing on undefined.length.
+        const tags = snap.tags ?? [];
+        const tagsSuffix = tags.length > 0 ? ` [${tags.join(", ")}]` : "";
+        console.log(`${snap.id} - ${preview} (${snap.created_at})${snap.shared ? " (shared)" : ""}${tagsSuffix}`);
     }
 }
 export async function createSnap(args) {
     const jsonOutput = args.includes("--json");
+    const tagsArg = flagValue(args, "--tags");
     // 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");
+    // error. Mirrors searchSnaps' own query-joining below. --tags and its
+    // value (both "--tags x" and "--tags=x" forms) are stripped the same way
+    // --json is, so they never leak into the joined content.
+    const positionals = args.filter((a, i) => a !== "--json" && a !== "--tags" && !a.startsWith("--tags=") && args[i - 1] !== "--tags");
     const positional = positionals.length > 0 ? positionals.join(" ") : undefined;
     let content;
     if (positional !== undefined) {
@@ -79,10 +88,21 @@ export async function createSnap(args) {
     }
     if (!content.trim())
         throw new UsageError(CREATE_USAGE);
+    // Same comma-split convention as `ahood skill publish --tags`/`edit
+    // --tags`. Omitted entirely when --tags wasn't passed at all, so the
+    // request body matches the "omitting tags is equivalent to []" contract
+    // exactly instead of always sending an (empty) tags array.
+    const body = { content };
+    if (tagsArg !== undefined) {
+        body.tags = tagsArg
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
     const created = await apiJson("/api/v1/snaps", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ content }),
+        body: JSON.stringify(body),
     });
     if (jsonOutput) {
         console.log(JSON.stringify(created));
@@ -189,3 +209,48 @@ export async function unshareSnap(args) {
     await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}/share`, { method: "DELETE" });
     console.log(`Unshared snap ${id}.`);
 }
+export async function tagsSnap(args) {
+    const jsonOutput = args.includes("--json");
+    const positionals = args.filter((a) => a !== "--json");
+    // Reject stray "--" flags rather than folding them into the tag list
+    // (parseSearchQuery in flags.ts does the same). Without this, the natural
+    // mistake `snap tags <id> --tags a,b` -- natural because `snap create`
+    // really does spell it `--tags a,b` -- silently PATCHed the tag set to
+    // ["--tags a", "b"], and `snap tags --yes <id>` used "--yes" as the id.
+    const unknownFlag = positionals.find((a) => a.startsWith("--"));
+    if (unknownFlag)
+        throw new UsageError(`Unknown flag: ${unknownFlag}\n${TAGS_USAGE}`);
+    const id = positionals[0];
+    if (!id)
+        throw new UsageError(TAGS_USAGE);
+    // PATCH replaces the full tag set (not a merge) -- omitting the tags
+    // argument, or passing an empty string, both clear every tag, matching
+    // the "pass [] to clear" contract of the endpoint itself. Joined, not
+    // just positionals[1] -- an unquoted "tag1, tag2" arrives as multiple
+    // positional tokens, and taking only the first one silently dropped the
+    // rest with no error, the same bug createSnap's own content-joining
+    // above already fixed.
+    const tagsArg = positionals.slice(1).join(" ");
+    const tags = tagsArg
+        ? tagsArg
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean)
+        : [];
+    // No confirm() gate, unlike remove/unshare -- this only replaces metadata
+    // (tags), never the snap's content or its shareability, and re-running
+    // `tags` with the old set restores it exactly. Per ahood-cli#114's spec.
+    const updated = await apiJson(`/api/v1/snaps/${encodeURIComponent(id)}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tags }),
+    });
+    if (jsonOutput) {
+        console.log(JSON.stringify(updated));
+        return;
+    }
+    // ?? [] -- see printSnaps' identical degrade-on-null guard above
+    // (ahood-cli#106): a degraded response shouldn't crash on undefined.length.
+    const updatedTags = updated.tags ?? [];
+    console.log(updatedTags.length > 0 ? `Tags for ${updated.id}: ${updatedTags.join(", ")}` : `Cleared tags for ${updated.id}.`);
+}

package/dist/commands/update.js

@@ -1,6 +1,6 @@
 import { LOCKFILE_PATH, parseOwnerSkill } from "../spec.js";
 import { readLockfile } from "../lockfile.js";
-import { add, fetchVersionMeta } from "./add.js";
+import { add, fetchVersionMeta, updateMcpEntry } from "./add.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]";
 async function previewSkill(ownerSlashSkill, currentVersion) {
@@ -99,18 +99,27 @@ export async function update(args) {
         try {
             // add() always hits the .mcp.json collision check for an mcp-kind
             // entry that's already installed (that's the very definition of
-            // "already installed" for that kind), so calling it unconditionally
-            // here would make `ahood skill update` with no arguments permanently
-            // report a failure and exit 1 for every user who has ever installed
-            // an mcp artifact, even when nothing needs updating. fetchVersionMeta
-            // already resolves `kind` as part of the normal "latest" lookup add()
-            // itself does, so resolving it here first lets this skip cleanly
-            // instead of updating and hitting that guaranteed error. This is a
-            // skip-and-report-cleanly fix, not real mcp-update support.
+            // "already installed" for that kind), so it can never be called
+            // unconditionally here the way it is for skill/agent kinds below --
+            // fetchVersionMeta resolves `kind` as part of the normal "latest"
+            // lookup add() itself does, so resolving it here first lets an
+            // mcp-kind entry route to updateMcpEntry (ahood-cli#169's real
+            // mcp-update support) instead.
             const { owner, skill } = parseOwnerSkill(ownerSlashSkill, USAGE);
             const meta = await fetchVersionMeta(owner, skill, "latest");
             if (meta.kind === "mcp") {
-                console.warn(`Skipping ${ownerSlashSkill}: mcp artifacts aren't updatable via this command yet.`);
+                const currentEntry = lockfile[ownerSlashSkill];
+                if (currentEntry && currentEntry.version === meta.version) {
+                    // Matches skill/agent update's own "nothing to do" case for a
+                    // pin that's already at latest -- not a warning (nothing's
+                    // wrong), and, unlike skill/agent (which always blindly
+                    // re-extracts even when nothing changed), skipped here
+                    // specifically so an up-to-date mcp entry with a secret in its
+                    // env never re-triggers a masked prompt for no reason.
+                    console.log(`${ownerSlashSkill} is already up to date (v${meta.version}).`);
+                    continue;
+                }
+                await updateMcpEntry(owner, skill, meta, currentEntry);
                 continue;
             }
             await add([ownerSlashSkill]); // no @version -- resolves to latest again

package/dist/help.js

@@ -100,7 +100,9 @@ export const SKILL_COMMANDS_HELP = [
     {
         usage: "ahood skill update [<owner>/<skill> ...] [--dry-run] [--json]",
         summary: "Move the lockfile pin(s) forward to the latest version, for one skill or all installed skills at once.",
-        desc: "Move the lockfile pin(s) forward to the latest version. With no argument, updates every installed skill; one failure doesn't stop the rest.",
+        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. " +
+            "An mcp-kind entry is updated in place (re-resolving any secret environment variables) as long as its .mcp.json entry still matches what " +
+            "ahood last installed there -- a hand-edited or unverifiable entry is refused rather than silently overwritten.",
         flags: [
             "--dry-run   Preview current vs. latest version (and the changelog for anything behind) without installing anything.",
             "--json      With --dry-run, emit structured preview objects instead of a formatted table.",
@@ -119,7 +121,9 @@ export const SKILL_COMMANDS_HELP = [
     {
         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.",
+        desc: "Uninstall and unpin (local only). Prompts for confirmation unless --yes is passed. For an mcp-kind install, " +
+            "also deletes its .mcp.json entry as long as it still matches what ahood last installed there -- a hand-edited " +
+            "or unverifiable entry is left in place and warned about instead of being silently touched.",
     },
     {
         usage: "ahood skill edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]",
@@ -275,18 +279,25 @@ export const GROUP_COMMANDS_HELP = [
 // never public otherwise.
 export const SNAP_COMMANDS_HELP = [
     {
-        usage: "ahood snap create <content> [--json]",
+        usage: "ahood snap create <content> [--tags tag1,tag2] [--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'],
+        flags: [
+            "--tags <comma,separated>   Attach tags to the new snap.",
+            "--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." --tags deploy,bugfix',
+            '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.",
+        desc: "List your own snaps: id, a truncated content preview, created_at, a (shared) marker if shared, and " +
+            "any tags in brackets.",
         flags: [
             "--json        Emit the raw snap objects instead of formatted lines.",
             "--limit <n>   Cap the number of results.",
@@ -329,6 +340,15 @@ export const SNAP_COMMANDS_HELP = [
             "immediately.",
         flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
     },
+    {
+        usage: "ahood snap tags <id> [tag1,tag2,...] [--json]",
+        summary: "Replace a snap's tags (omit the tag list, or pass an empty one, to clear all tags).",
+        desc: "Replace the full set of tags on a snap -- this is not a merge, so any existing tags not listed are " +
+            "dropped. Omitting the tag list entirely, or passing an empty string, clears all tags. No confirmation " +
+            "prompt: unlike remove/unshare this only touches metadata, never the snap's content or shareability.",
+        flags: ["--json    Emit {id, tags} instead of a plain-text summary."],
+        examples: ["ahood snap tags snap_123 deploy,bugfix", 'ahood snap tags snap_123 ""'],
+    },
 ];
 // 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

package/dist/index.js

@@ -22,7 +22,7 @@ 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 { createSnap, listSnaps, searchSnaps, showSnap, removeSnap, shareSnap, unshareSnap, } from "./commands/snap.js";
+import { createSnap, listSnaps, searchSnaps, showSnap, removeSnap, shareSnap, unshareSnap, tagsSnap, } 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";
@@ -80,6 +80,7 @@ const SNAP_VERBS = {
     remove: removeSnap,
     share: shareSnap,
     unshare: unshareSnap,
+    tags: tagsSnap,
 };
 // 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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",
@@ -26,7 +26,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/index.js",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "sync-readme": "node scripts/sync-readme.mjs"