@ahood/cli 0.8.1 → 0.8.3

package/dist/commands/add.js

@@ -330,9 +330,25 @@ function summarizeConflictingEntry(entry) {
 export function readMcpConfig() {
     if (!existsSync(MCP_CONFIG_PATH))
         return { mcpServers: {} };
+    // Read and parse are separate try blocks so an I/O failure isn't reported
+    // as a syntax error: EACCES/EISDIR/EMFILE used to surface as "is not valid
+    // JSON" about a file that often parses fine, sending the user hunting for a
+    // syntax error when the fix is chmod or removing a stray directory
+    // (ahood-cli#117). No "-- fix or remove it" advice on this branch: the
+    // remedy depends on the errno, Node's own message already names the code
+    // and the path, and remove.ts deliberately quotes only the text before
+    // " -- " (ahood-cli#115).
+    let raw;
+    try {
+        raw = readFileSync(MCP_CONFIG_PATH, "utf-8");
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`${MCP_CONFIG_PATH} exists but could not be read: ${reason}`);
+    }
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(MCP_CONFIG_PATH, "utf-8"));
+        parsed = JSON.parse(raw);
     }
     catch {
         throw new Error(`${MCP_CONFIG_PATH} exists but is not valid JSON -- fix or remove it before running this command.`);
@@ -370,7 +386,23 @@ function assertNoCollision(fileContents, owner, skill) {
 // 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.
-export async function resolveMcpServerConfig(buffer) {
+// `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,
@@ -392,9 +424,22 @@ export async function resolveMcpServerConfig(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 };
@@ -406,13 +451,69 @@ export async function resolveMcpServerConfig(buffer) {
 // 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.
+// install. Hashes a canonical (recursively key-sorted) serialization rather
+// than raw JSON.stringify output, because .mcp.json is shared with other MCP
+// clients by design (see CLAUDE.md) and so gets rewritten by things that are
+// not ahood -- `jq -S`, a format-on-save plugin, another client's serializer,
+// a user retyping the block -- any of which can reorder keys without changing
+// what the entry means. Fingerprinting insertion order turned every such
+// reformat into a permanent refusal from both `update` and `remove`,
+// recoverable only by hand-deleting the entry and re-entering its secret
+// (ahood-cli#116). Arrays keep their order: `args` is order-significant.
 export function hashMcpServerConfig(config) {
+    return createHash("sha256").update(JSON.stringify(canonicalizeForHash(config))).digest("hex");
+}
+function canonicalizeForHash(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeForHash);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = canonicalizeForHash(value[key]);
+    }
+    return sorted;
+}
+// LEGACY (ahood-cli#116): the pre-canonicalization fingerprint format. Every
+// mcp entry pinned by an older CLI carries one of these, so changing the
+// algorithm without a fallback would invalidate all of them at once --
+// inflicting the exact permanent-refusal failure #116 is about on every
+// existing user, on upgrade. Only ever consulted as a second chance after the
+// canonical hash misses; drop this function and matchesMcpConfigHash's
+// fallback branch a few releases on.
+function hashMcpServerConfigLegacy(config) {
     return createHash("sha256").update(JSON.stringify(config)).digest("hex");
 }
+// The single "is this on-disk entry still what we recorded?" decision, shared
+// by every comparison site (updateMcpEntry's pre-check and its re-check under
+// lock, remove's read and its re-check under lock). Centralized deliberately:
+// a legacy fallback open-coded at four call sites is a fallback that ends up
+// at three of them. A legacy match needs no separate signal to callers --
+// update rewrites the pin with a canonical hash as part of its normal
+// lockfile write, so such an entry self-heals silently on the next version
+// bump, and remove is deleting the entry anyway.
+export function matchesMcpConfigHash(entry, recordedHash) {
+    return hashMcpServerConfig(entry) === recordedHash || hashMcpServerConfigLegacy(entry) === recordedHash;
+}
+// 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
@@ -498,12 +599,18 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         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) {
+        if (!matchesMcpConfigHash(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);
-    const { serverConfig } = await resolveMcpServerConfig(buffer);
+    // 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
@@ -514,7 +621,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         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)) {
+        if (freshExisting !== undefined && (recordedHash === undefined || !matchesMcpConfigHash(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;
@@ -529,25 +636,43 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         });
     }
     catch (error) {
-        if (!(error instanceof LockfileChecksumConflictError))
-            throw 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.
-        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);
-        });
-        throw new Error(checksumConflictMessage(key, meta, error.existing));
+        //
+        // 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) {

package/dist/commands/remove.js

@@ -2,7 +2,7 @@ import { existsSync, rmSync, unlinkSync } from "node:fs";
 import { confirm } from "../confirm.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 { readMcpConfig, matchesMcpConfigHash } from "./add.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood skill remove <owner>/<skill> [--yes]";
 export async function remove(args) {
@@ -58,6 +58,7 @@ export async function remove(args) {
     let removedMcpEntry = false;
     let mcpEntryModified = false;
     let mcpEntryPresent = false;
+    let mcpConfigUnreadable;
     let recordedHash;
     try {
         const fileContents = readMcpConfig();
@@ -65,20 +66,28 @@ export async function remove(args) {
         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;
+                mcpEntryModified = !matchesMcpConfigHash(mcpServers[skill], recordedHash);
             }
         }
     }
-    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.
+    catch (error) {
+        // A malformed .mcp.json still isn't this command's problem to fix or
+        // crash on -- add.ts's readMcpConfig is the strict validator for that
+        // path. But leaving every flag false here meant the unreadable case
+        // printed a bare "Removed" with the entry (and its secret) still live,
+        // the very false-assurance bug the block above exists to prevent
+        // (ahood-cli#115). The lockfile's mcp_config_hash, read at the top of
+        // this function before the pin was cleared, is direct evidence that
+        // ahood DID install an entry into this file, so record why the read
+        // failed and warn off that instead of off a shape we can't inspect.
+        mcpConfigUnreadable = error instanceof Error ? error.message : String(error);
     }
     if (mcpEntryPresent && recordedHash !== undefined && !mcpEntryModified) {
+        // Rebound to a const so the `!== undefined` narrowing above survives into
+        // the closure below -- `recordedHash` is a `let`, which TypeScript widens
+        // back to `string | undefined` inside a callback.
+        const verifiedHash = recordedHash;
         try {
             // Re-check under lock rather than trusting the read above -- another
             // process could have changed or removed the entry in between,
@@ -94,7 +103,7 @@ export async function remove(args) {
                 const fresh = readMcpConfig();
                 const freshServers = fresh.mcpServers;
                 if (Object.prototype.hasOwnProperty.call(freshServers, skill) &&
-                    hashMcpServerConfig(freshServers[skill]) === recordedHash) {
+                    matchesMcpConfigHash(freshServers[skill], verifiedHash)) {
                     delete freshServers[skill];
                     writeJsonFileAtomic(MCP_CONFIG_PATH, fresh);
                     removedMcpEntry = true;
@@ -105,7 +114,24 @@ export async function remove(args) {
             // removedMcpEntry stays false -- falls through to the warning below.
         }
     }
-    if (mcpEntryPresent && !removedMcpEntry) {
+    if (mcpConfigUnreadable !== undefined && lockEntry?.mcp_config_hash !== undefined) {
+        // Its own wording rather than the branch below's: "remove it manually"
+        // isn't actionable while the file doesn't parse, and we can't say the
+        // entry is definitely still there -- only that one was installed and
+        // we couldn't check (ahood-cli#115).
+        // Only readMcpConfig's diagnosis, not the "-- fix or remove it before
+        // running this command" advice two of its three messages carry: "remove
+        // it" means deleting .mcp.json, which is shared with other MCP clients
+        // (see CLAUDE.md), so repeating it here would offer to destroy other
+        // servers' config in the same breath as this warning's own, correctly
+        // scoped advice (ahood-cli#115).
+        const diagnosis = mcpConfigUnreadable.split(" -- ")[0];
+        const reason = diagnosis.endsWith(".") ? diagnosis : `${diagnosis}.`;
+        console.warn(`WARNING: ${key} may still have an entry in ${MCP_CONFIG_PATH} (which may contain secrets you entered), ` +
+            `but ahood could not check: ${reason}` +
+            ` Fix the file, then delete the "${skill}" entry from mcpServers by hand.`);
+    }
+    else 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.`);

package/dist/commands/snap.js

@@ -212,6 +212,14 @@ export async function unshareSnap(args) {
 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);

package/package.json

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