@ahood/cli 0.8.5 → 0.8.7

package/README.md

@@ -81,13 +81,15 @@ Requires Node.js 18 or later.
 | `AHOOD_API_URL` | Overrides the registry endpoint (default: `https://ahood.vercel.app`). Must be `https://`, except for `localhost`/`127.0.0.1` or a `.test`/`.invalid`/`.example`/`.localhost` host, which may use plain `http://` for local development. |
 | `XDG_CONFIG_HOME` | If set, browser-login credentials are stored under `$XDG_CONFIG_HOME/ahood/credentials.json` instead of the default `~/.config/ahood/credentials.json`. |
 
-Paths `ahood` reads and writes in your project, none of which need to be gitignored (the lockfile is meant to be committed, same as `package-lock.json`):
+Paths `ahood` reads and writes in your project. The lockfile is meant to be committed, same as `package-lock.json`:
 
 | Path | What's in it |
 | --- | --- |
 | `.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. |
+| `.mcp.json` | MCP server entries, for `mcp`-kind artifacts only. Merged into rather than owned — other MCP clients share this file. **May contain secrets in plaintext**, since a server manifest can declare credentials that `add` prompts for; `add` warns when it writes one. |
+| `*.json.tmp-<pid>-<hrtime>` | Never, in normal operation. Writes to the two `.json` files above go through a temp file that is renamed into place, and only a hard kill (SIGKILL, OOM, power loss) mid-write can strand one. A stranded copy of `.mcp.json` carries the same plaintext secrets, so **gitignore this pattern**. The next successful write removes any left by a process that is no longer running. |
 
 ## Usage examples
 
@@ -244,8 +246,8 @@ Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private
 | Command | What it does |
 | --- | --- |
 | `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 list [--json] [--limit <n>] [--tags tag1,tag2]` | List your own snaps, most recent first. |
+| `ahood snap search <query> [--json] [--limit <n>] [--tags tag1,tag2]` | 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. |

package/dist/commands/add.js

@@ -114,7 +114,7 @@ export async function extractTarGz(buffer, destDir) {
             const fullPath = resolve(destDir, entryPath);
             if (fullPath !== resolvedDest && !fullPath.startsWith(resolvedDest + sep)) {
                 stream.resume();
-                reject(new Error(`Refusing to extract unsafe archive entry: ${header.name}`));
+                reject(new Error(`Refusing to extract unsafe archive entry: ${sanitizeForTerminal(header.name)}`));
                 // next() is deliberately NOT called -- nothing further in this archive
                 // should be processed. destroy() tears the paused extractor down
                 // rather than leaving it stalled mid-entry.
@@ -237,17 +237,24 @@ export async function extractSingleFileContent(buffer, entryName) {
         throw new Error(`${entryName} not found in the downloaded archive`);
     return found;
 }
-// Every manifest field used below reaches the terminal (an error message, or
+// Every manifest field used below -- and every tar entry name extractTarGz
+// quotes back in an error above -- reaches the terminal (an error message, or
 // -- worse -- the text printed immediately before a masked secret prompt)
-// but comes verbatim from a third-party-published server.json: server-side
+// but comes verbatim from a third-party-published archive: server-side
 // validation only checks these are strings, not that they're free of
 // control/escape characters. A malicious description could otherwise smuggle
 // a terminal control sequence (cursor movement, line-clear) that repaints
 // what the user sees at the exact moment they're about to type a credential.
 // Strips C0/C1 control characters (including ESC, \x1b) and caps length so a
 // single field can't also flood the terminal.
+//
+// Takes `unknown` rather than `string` because every caller's "string" is a
+// declared type over an unchecked `as ServerManifest` cast of downloaded JSON,
+// not a guarantee: calling .replace() directly on a `registry_type: 123` would
+// turn a diagnosable message into the raw TypeError ahood-cli#121 removed from
+// this same path (ahood-cli#122).
 function sanitizeForTerminal(text) {
-    return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
+    return String(text).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 200);
 }
 // Only npm+npx is supported in v1 (docs/superpowers/specs/2026-09-03-mcp-server-artifacts-design.md) --
 // server-side publish validation (lib/publish/parse-server-manifest.ts) already
@@ -260,7 +267,7 @@ function buildMcpServerConfig(manifest, env) {
     if (manifest.packages && manifest.packages.length === 1) {
         const pkg = manifest.packages[0];
         if (pkg.registry_type !== "npm" || pkg.runtime_hint !== "npx") {
-            throw new Error(`${manifestName}'s server.json uses registry_type "${pkg.registry_type}"/runtime_hint "${pkg.runtime_hint}", which this version of ahood does not know how to install (only npm+npx is supported).`);
+            throw new Error(`${manifestName}'s server.json uses registry_type "${sanitizeForTerminal(pkg.registry_type)}"/runtime_hint "${sanitizeForTerminal(pkg.runtime_hint)}", which this version of ahood does not know how to install (only npm+npx is supported).`);
         }
         const config = { command: "npx", args: ["-y", `${pkg.identifier}@${pkg.version}`] };
         if (Object.keys(env).length > 0)
@@ -379,8 +386,8 @@ function assertNoCollision(fileContents, owner, skill) {
             `Remove it manually first if you want to reinstall ${owner}/${skill}.`);
     }
 }
-// Extracts server.json, validates its shape, and resolves every secret
-// environment variable it declares (prompting only for ones not already
+// Extracts server.json, validates its shape, and resolves every
+// environment variable it declares (prompting only for secrets 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)
@@ -401,10 +408,38 @@ function assertNoCollision(fileContents, owner, skill) {
 // 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.
+//
+// `secretNames` comes back alongside the config because `env` also carries
+// non-secret configuration now (ahood-cli#120): callers that need to know
+// whether what they just wrote to disk is actually a credential can no longer
+// infer it from `env` being non-empty.
 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"));
+    // Guarded the same way readMcpConfig guards .mcp.json: an unguarded parse
+    // surfaced a raw V8 SyntaxError with a stack instead of this CLI's usual
+    // single-line error (ahood-cli#121). The parser's own message is dropped
+    // rather than run through sanitizeForTerminal, because V8 quotes a snippet
+    // of the offending source in it -- that source is third-party archive
+    // content, and sanitizing would still paste it into the terminal, just
+    // with its control characters flattened.
+    let parsed;
+    try {
+        parsed = JSON.parse(content.toString("utf-8"));
+    }
+    catch {
+        throw new Error("The downloaded archive's server.json is not valid JSON -- this published version is malformed and cannot be installed.");
+    }
+    // Checked before the cast because buildMcpServerConfig immediately reads
+    // properties off the result: valid JSON that isn't an object (`[]`, `"x"`,
+    // `3`, `null`) would otherwise reach it and surface as an unactionable raw
+    // TypeError (ahood-cli#121). Deliberately stops at "is it an object" -- the
+    // manifest's actual shape is buildMcpServerConfig's job just below, and a
+    // second implementation of that check here would be free to drift from it.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("The downloaded archive's server.json is valid JSON but its top level is not an object -- this published version is malformed and cannot be installed.");
+    }
+    const manifest = parsed;
     // Validate the manifest's shape (unsupported registry_type/runtime_hint,
     // or neither a single 'packages' nor a single 'remotes' entry) BEFORE
     // prompting for any secret -- an install/update that's going to be
@@ -414,10 +449,46 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
     // secretEnv is known.
     buildMcpServerConfig(manifest, {});
     const envVars = manifest.packages?.[0]?.environment_variables ?? [];
-    const secretEnv = {};
+    const env = {};
+    // Non-secret variables used to be skipped outright, so a server declaring
+    // one installed into a config that could not start it, with no diagnostic
+    // (ahood-cli#120). They're configuration, not credentials: read them from
+    // the shell, but never prompt -- a prompt here would reintroduce exactly
+    // the unattended-use hazard ahood-cli#169/0.8.2 removed from the update
+    // path, and there is nothing to mask anyway.
+    //
+    // Resolved in a first pass, ahead of any masked prompt below, for the same
+    // reason buildMcpServerConfig is dry-run above and assertNoCollision runs
+    // before installMcpEntry's resolve: an install that's going to be refused
+    // for a missing required variable must not first cost the user a secret
+    // prompt.
+    for (const variable of envVars) {
+        if (variable.is_secret)
+            continue;
+        // Same truthiness rule as the secret branch below: an empty-string env
+        // var reads as "not set" rather than installing an empty value.
+        const fromEnv = process.env[variable.name];
+        if (fromEnv) {
+            env[variable.name] = fromEnv;
+            continue;
+        }
+        // `is_required` was parsed and validated but never consulted at install
+        // time (ahood-cli#120). Optional means optional -- install without it.
+        // Required means the server cannot start without it, so refusing beats
+        // writing a config that is broken in a way nothing reports.
+        if (variable.is_required) {
+            throw new Error(`${sanitizeForTerminal(variable.name)} is required by ${sanitizeForTerminal(manifest.name)} but is not set -- export ${sanitizeForTerminal(variable.name)} and re-run.`);
+        }
+    }
+    // Required-ness needs no separate check on the secret path: every branch
+    // below either resolves a value or throws, so a required secret with
+    // nothing to fall back on already fails loudly (the non-TTY guard) or is
+    // supplied at the prompt (ahood-cli#120).
+    const secretNames = [];
     for (const variable of envVars) {
         if (!variable.is_secret)
             continue;
+        secretNames.push(variable.name);
         const fromEnv = process.env[variable.name];
         // Truthiness, not `!== undefined` -- matches credentials.ts's
         // resolveToken(), the precedent this feature was explicitly modeled on
@@ -425,24 +496,41 @@ export async function resolveMcpServerConfig(buffer, options = {}) {
         // specifically so an empty-string env var falls through to the real
         // source instead of silently installing an empty secret.
         if (fromEnv) {
-            secretEnv[variable.name] = fromEnv;
+            env[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.
+        // shadowed by the stale value already on disk. Deliberately not extended
+        // to non-secret variables (ahood-cli#120): carrying a value forward from
+        // .mcp.json is credential-preservation machinery, and a non-secret is
+        // plain configuration that the shell should stay authoritative for.
         const carriedForward = existingEnv?.[variable.name];
         if (carriedForward) {
-            secretEnv[variable.name] = carriedForward;
+            env[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)}): `);
+        env[variable.name] = await promptSecret(`${sanitizeForTerminal(variable.name)} (${sanitizeForTerminal(variable.description)}): `);
     }
-    const serverConfig = buildMcpServerConfig(manifest, secretEnv);
-    return { manifest, serverConfig };
+    const serverConfig = buildMcpServerConfig(manifest, env);
+    return { manifest, serverConfig, secretNames };
+}
+// The plaintext-secret warning printed after a successful mcp install/update.
+// Still derived from the config that actually landed on disk -- the property
+// the old bare `serverConfig.env` check was chosen for -- but intersected with
+// the manifest's declared secrets, because `env` now also holds non-secret
+// configuration (ahood-cli#120) and would otherwise warn about credentials
+// for a server that declares none.
+function warnIfSecretsWereWritten(serverConfig, secretNames) {
+    const env = serverConfig.env;
+    if (!env)
+        return;
+    if (!secretNames.some((name) => Object.prototype.hasOwnProperty.call(env, name)))
+        return;
+    console.warn(`WARNING: ${MCP_CONFIG_PATH} now contains one or more secret values in plaintext -- do not commit it to version control.`);
 }
 // Fingerprint of exactly what ahood wrote into .mcp.json's mcpServers.<skill>
 // entry, stored in the lockfile alongside the version/checksum pin. Lets
@@ -520,7 +608,7 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     // 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);
+    const { serverConfig, secretNames } = 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
@@ -558,13 +646,8 @@ async function installMcpEntry(owner, skill, meta, buffer) {
     }
     console.log(`Installed ${owner}/${skill}@${meta.version} into ${MCP_CONFIG_PATH} as "${skill}"`);
     // 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.`);
-    }
+    // on a remote entry are static per v1's scope, per buildMcpServerConfig).
+    warnIfSecretsWereWritten(serverConfig, secretNames);
 }
 // 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).
@@ -610,7 +693,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
     // (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 });
+    const { serverConfig, secretNames } = 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
@@ -675,9 +758,7 @@ export async function updateMcpEntry(owner, skill, meta, currentEntry) {
         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.`);
-    }
+    warnIfSecretsWereWritten(serverConfig, secretNames);
 }
 // Downloads a specific version's archive and verifies it against the
 // checksum in `meta`, WITHOUT extracting anything -- the shared first half

package/dist/commands/snap.js

@@ -3,8 +3,8 @@ 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> [--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 LIST_USAGE = "Usage: ahood snap list [--json] [--limit <n>] [--tags tag1,tag2]";
+const SEARCH_USAGE = "Usage: ahood snap search <query> [--json] [--limit <n>] [--tags tag1,tag2]";
 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]";
@@ -113,10 +113,19 @@ export async function createSnap(args) {
 export async function listSnaps(args) {
     const jsonOutput = args.includes("--json");
     const limitStr = flagValue(args, "--limit");
+    const tagsStr = flagValue(args, "--tags");
     validateLimit(limitStr, LIST_USAGE);
     const qs = new URLSearchParams();
     if (limitStr !== undefined)
         qs.set("limit", limitStr);
+    // Passed through verbatim rather than split/trimmed the way createSnap's
+    // own --tags is: the server owns what a tag filter means (comma-separated,
+    // ANDed, case-insensitive, 400 past 8 terms) and deliberately keeps an
+    // unstorable term instead of dropping it, since dropping one would silently
+    // broaden the result set. Re-parsing here would be a second implementation
+    // of that contract, free to drift from it (ahood-cli#118).
+    if (tagsStr !== undefined)
+        qs.set("tags", tagsStr);
     const query = qs.toString();
     const { snaps } = await apiJson(`/api/v1/snaps${query ? `?${query}` : ""}`);
     // ?? [], not a bare destructure -- a degraded response (snaps: null)
@@ -127,11 +136,19 @@ export async function listSnaps(args) {
 export async function searchSnaps(args) {
     const jsonOutput = args.includes("--json");
     const limitStr = flagValue(args, "--limit");
-    const query = parseSearchQuery(args, SEARCH_USAGE);
+    const tagsStr = flagValue(args, "--tags");
+    // --tags declared here so its VALUE isn't swallowed into the joined query
+    // string -- `snap search deploy --tags ci` must search for "deploy" filtered
+    // to tag "ci", not for "deploy ci" (ahood-cli#118).
+    const query = parseSearchQuery(args, SEARCH_USAGE, ["--tags"]);
     validateLimit(limitStr, SEARCH_USAGE);
     const qs = new URLSearchParams({ q: query });
     if (limitStr !== undefined)
         qs.set("limit", limitStr);
+    // Verbatim -- see listSnaps' identical pass-through above (ahood-cli#118).
+    // The server ANDs a tag filter with `q`, so this narrows the text results.
+    if (tagsStr !== undefined)
+        qs.set("tags", tagsStr);
     const { snaps } = await apiJson(`/api/v1/snaps?${qs}`);
     // ?? [] -- see listSnaps' identical guard above (ahood-cli#106).
     printSnaps(jsonOutput, snaps ?? [], "No snaps found.");

package/dist/flags.js

@@ -36,8 +36,18 @@ export function flagValue(args, flag) {
 // --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");
+// `valueFlags` names ADDITIONAL "--flag value" flags this particular command
+// accepts (snap search's --tags, ahood-cli#118), on top of --limit, which
+// every caller takes. Passed per-caller rather than stripping a shared union
+// of every search-ish flag, so `ahood skill search --tags x` still errors on
+// a flag that command doesn't implement instead of silently ignoring it and
+// returning unfiltered results.
+export function parseSearchQuery(args, usage, valueFlags = []) {
+    const stripped = ["--limit", ...valueFlags];
+    const queryParts = args.filter((a, i) => a !== "--json" &&
+        !stripped.includes(a) &&
+        !stripped.some((f) => a.startsWith(`${f}=`)) &&
+        !stripped.includes(args[i - 1]));
     const unknownFlag = queryParts.find((a) => a.startsWith("--"));
     if (unknownFlag)
         throw new UsageError(`Unknown flag: ${unknownFlag}\n${usage}`);

package/dist/help.js

@@ -294,24 +294,29 @@ export const SNAP_COMMANDS_HELP = [
         ],
     },
     {
-        usage: "ahood snap list [--json] [--limit <n>]",
+        usage: "ahood snap list [--json] [--limit <n>] [--tags tag1,tag2]",
         summary: "List your own snaps, most recent first.",
         desc: "List your own snaps: id, a truncated content preview, created_at, a (shared) marker if shared, and " +
-            "any tags in brackets.",
+            "any tags in brackets. --tags narrows the list to snaps carrying every tag given (not any of them), " +
+            "matched case-insensitively.",
         flags: [
-            "--json        Emit the raw snap objects instead of formatted lines.",
-            "--limit <n>   Cap the number of results.",
+            "--json               Emit the raw snap objects instead of formatted lines.",
+            "--limit <n>          Cap the number of results.",
+            "--tags tag1,tag2     Only snaps carrying ALL of these tags. Case-insensitive; at most 8.",
         ],
+        examples: ["ahood snap list --tags deploy", "ahood snap list --tags deploy,bugfix --limit 5"],
     },
     {
-        usage: "ahood snap search <query> [--json] [--limit <n>]",
+        usage: "ahood snap search <query> [--json] [--limit <n>] [--tags tag1,tag2]",
         summary: "Search your own snaps by content.",
-        desc: "Search your own snaps by content. Same output shape as `ahood snap list`.",
+        desc: "Search your own snaps by content. Same output shape as `ahood snap list`. The query matches snap " +
+            "CONTENT only and never a tag -- use --tags to filter by tag, which narrows the text results further.",
         flags: [
-            "--json        Emit the raw snap objects instead of formatted lines.",
-            "--limit <n>   Cap the number of results.",
+            "--json               Emit the raw snap objects instead of formatted lines.",
+            "--limit <n>          Cap the number of results.",
+            "--tags tag1,tag2     Only snaps carrying ALL of these tags. Case-insensitive; at most 8.",
         ],
-        examples: ["ahood snap search flaky-ci"],
+        examples: ["ahood snap search flaky-ci", "ahood snap search deploy --tags ci"],
     },
     {
         usage: "ahood snap show <id> [--json]",

package/dist/lockfile.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
@@ -15,6 +15,63 @@ export function readLockfile(path) {
         throw new Error(`Lockfile at ${path} is corrupted and could not be parsed as JSON. Fix or delete it before continuing.`);
     }
 }
+// Signal 0 doesn't deliver anything, it just probes whether the process could
+// be signaled. ESRCH means it's gone; EPERM means it's alive but owned by
+// someone else, which is conservatively treated as still alive since that
+// can't be disproven. Shared by the stale-lock reclaim (ahood-cli#100) and the
+// stale-temp sweep (ahood-cli#125) so both answer "is the process that left
+// this behind still around?" the same way, rather than growing two divergent
+// staleness rules.
+function isPidDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+// Exactly what the temp name below produces: a decimal pid and a decimal
+// hrtime, nothing else. Anything the user merely happened to name
+// `<basename>.tmp-something` fails this and is left alone -- deleting a file
+// that was never ours is far worse than leaving a stale temp file behind
+// (ahood-cli#125).
+const TEMP_SUFFIX_RE = /^([1-9][0-9]{0,9})-[0-9]{1,25}$/;
+// The finally in writeJsonFileAtomic can't run on SIGKILL, an OOM kill or
+// power loss, so a temp file can still be orphaned in the window between the
+// write and the rename -- and for .mcp.json that orphan holds resolved MCP
+// server secrets under a name nothing else ever removes (ahood-cli#125). The
+// next successful write to the same destination collects them.
+//
+// withLock serializes the writers this CLI itself starts, but a temp file is
+// only provably collectable once the process that created it is gone, so the
+// pid embedded in the name is checked rather than trusting the lock alone. A
+// pid recycled since the last boot can only make a dead writer look alive,
+// which just defers the cleanup; it can never make a live writer look dead, so
+// this never deletes a file still being written.
+function sweepStaleTempFiles(path, ownTempName) {
+    const dir = dirname(path);
+    const prefix = `${basename(path)}.tmp-`;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (entry.name === ownTempName)
+            continue;
+        if (!entry.name.startsWith(prefix))
+            continue;
+        const match = TEMP_SUFFIX_RE.exec(entry.name.slice(prefix.length));
+        if (!match)
+            continue;
+        if (!isPidDead(Number(match[1])))
+            continue;
+        try {
+            rmSync(join(dir, entry.name), { force: true });
+        }
+        catch {
+            // One unremovable orphan must not stop the rest of the sweep.
+        }
+    }
+}
 // Generalized so callers other than the lockfile itself (e.g. add.ts's
 // .mcp.json merge, which sits right next to the lockfile and can hold other
 // servers' secrets) get the same crash-safety guarantee instead of a bare
@@ -25,22 +82,70 @@ export function writeJsonFileAtomic(path, data) {
     // truncated file on disk -- a reader always sees either the old or the new
     // complete content, never a partial one.
     const tmpPath = `${path}.tmp-${process.pid}-${process.hrtime.bigint()}`;
-    writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
-    renameSync(tmpPath, path);
+    // The mode the destination must end up with. Preserving an existing file's
+    // permissions matters because .mcp.json is a project-shared config other MCP
+    // clients read: whether it should be 0644 or tighter is its own decision
+    // (ahood#169), not something this write path gets to change as a side effect
+    // of the 0600 temp file below (ahood-cli#119). With no destination yet there
+    // is nothing to preserve, so fall back to what a plain writeFileSync would
+    // have produced -- 0666 masked by the process umask.
+    let finalMode;
+    try {
+        finalMode = statSync(path).mode & 0o777;
+    }
+    catch {
+        finalMode = 0o666 & ~process.umask();
+    }
+    try {
+        // 0600 from the moment of creation: for .mcp.json this temp file holds
+        // resolved MCP server secrets, and it must never be world-readable, not
+        // even for the instant before the rename (ahood-cli#119).
+        writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+        renameSync(tmpPath, path);
+        try {
+            chmodSync(path, finalMode);
+        }
+        catch {
+            // Best-effort, and deliberately after the rename rather than on the temp
+            // file: widening the temp file first would reopen the world-readable
+            // window this fix closes. A failure here leaves the file MORE restrictive
+            // than intended, never less, so it isn't worth failing a write that has
+            // already landed -- the caller would roll back a successful install.
+        }
+        try {
+            sweepStaleTempFiles(path, basename(tmpPath));
+        }
+        catch {
+            // Swallowed for the same reason as the chmod above and #119's unlink:
+            // the rename has already landed, so failing to tidy up somebody else's
+            // abandoned temp file must never turn a successful write into an error
+            // the caller rolls back (ahood-cli#125).
+        }
+    }
+    finally {
+        // The rename consumes the temp file on success; this only bites when the
+        // write or the rename threw, where an orphaned *.tmp-* copy of .mcp.json
+        // would strand plaintext secrets under a name no .gitignore rule matches
+        // (ahood-cli#119). Swallowed because it must never mask the real reason
+        // the write failed -- that error is what the caller has to report.
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best effort, see comment above
+        }
+    }
 }
 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.
+// acquirer below) belongs to a process that's no longer running, per
+// isPidDead above. A missing/unparseable pid file is 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 {
@@ -52,13 +157,7 @@ function isLockStale(pidFile) {
     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";
-    }
+    return isPidDead(pid);
 }
 // Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
 // so two concurrent `ahood skill add`/`remove` invocations against the same
@@ -109,7 +208,7 @@ export function withLock(path, fn) {
                 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.`);
+                throw new Error(`Timed out waiting for the lock on ${path} at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
             }
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
         }

package/package.json

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