@ahood/cli 0.8.8 → 0.9.0

package/dist/lockfile.js

@@ -1,5 +1,5 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 export function readLockfile(path) {
     if (!existsSync(path))
         return {};
@@ -72,16 +72,83 @@ function sweepStaleTempFiles(path, ownTempName) {
         }
     }
 }
+// How many links deep resolveWriteTarget will follow before declaring a cycle.
+// Same order of magnitude as the kernel's own ceiling (40 on Linux); the exact
+// number doesn't matter, only that a self-referential link terminates with an
+// actionable error instead of spinning.
+const MAX_SYMLINK_HOPS = 32;
+// THE CONTRACT: a symlinked destination is written THROUGH, onto the file the
+// link resolves to, and the link itself is left in place.
+//
+// The alternative -- letting renameSync replace the link with a regular file,
+// which is what this used to do -- is indefensible for .mcp.json in
+// particular: symlinking it at a shared or out-of-tree config is how a user
+// keeps MCP server secrets OUT of the project directory, so replacing the link
+// drops those secrets into precisely the directory the arrangement exists to
+// keep them out of, while the real config silently keeps stale content.
+// ahood-cli#119's mode preservation made that harder to notice rather than
+// easier, since the file left behind carried the target's permissions
+// (ahood-cli#144).
+//
+// Refusing outright (lstat, throw "this must be a regular file") was the other
+// candidate, and was rejected: every caller here READS the same path first,
+// through the link -- add.ts merges the existing .mcp.json, the lockfile
+// writers merge the existing pins -- so a read-modify-write that reads the
+// target and writes anywhere else is incoherent no matter which file ends up
+// holding the result. Refusing would also make a crash-safety implementation
+// detail visible as a hard failure: the plain writeFileSync this replaced
+// followed the link, as does every editor and every shell redirection, and the
+// callers have no idea a symlink is involved at all.
+//
+// lstatSync, never statSync, and deliberately so: statSync follows the link and
+// therefore cannot answer the only question asked here ("is this path itself a
+// link?"). Asking it with statSync is the original bug -- the mode came back
+// from the link's target and was then applied to the regular file that had
+// taken the link's place.
+function resolveWriteTarget(path) {
+    let current = path;
+    for (let hop = 0; hop <= MAX_SYMLINK_HOPS; hop++) {
+        let isLink;
+        try {
+            isLink = lstatSync(current).isSymbolicLink();
+        }
+        catch {
+            // Nothing at this path: either a brand-new destination, or the dangling
+            // end of a chain whose final target doesn't exist yet -- a user who sets
+            // the symlink up before the first install. Write there, so the link
+            // starts resolving to the file the caller's next read will follow it to.
+            return current;
+        }
+        if (!isLink)
+            return current;
+        const link = readlinkSync(current);
+        current = isAbsolute(link) ? link : resolve(dirname(current), link);
+    }
+    throw new Error(`Refusing to write ${path}: it resolves through more than ${MAX_SYMLINK_HOPS} symlinks, so the chain loops back on itself. Repoint or delete that link.`);
+}
 // 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
 // writeFileSync that risks truncating the file on interruption.
 export function writeJsonFileAtomic(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
+    // Resolved before the mkdir so the directory that actually gets created is
+    // the resolved target's, not the link's -- a link set up ahead of the first
+    // install can point somewhere that doesn't exist yet -- and so that every
+    // step below (temp file, rename, chmod, sweep) names the same single file.
+    const dest = resolveWriteTarget(path);
+    mkdirSync(dirname(dest), { recursive: true });
     // Write-then-rename so a process interrupted mid-write never leaves a
     // 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()}`;
+    //
+    // The temp file must be a sibling of the RESOLVED destination rather than of
+    // `path`: renameSync cannot cross filesystems (EXDEV), and an out-of-tree
+    // target -- a different mount, a home directory on another volume -- is
+    // exactly the case a symlinked .mcp.json is used for. Deriving the temp name
+    // from `dest` keeps the rename inside one directory and keeps #119's
+    // `finally` unlink and #125's sweep pointed at the directory this code
+    // actually creates temp files in (ahood-cli#144).
+    const tmpPath = `${dest}.tmp-${process.pid}-${process.hrtime.bigint()}`;
     // 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
@@ -89,9 +156,14 @@ export function writeJsonFileAtomic(path, data) {
     // 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.
+    //
+    // lstatSync rather than statSync even though `dest` is by construction never
+    // a symlink (resolveWriteTarget walked until it wasn't): the two agree here,
+    // and lstat says so at the call site instead of leaving a link-following stat
+    // one refactor away from reintroducing #144.
     let finalMode;
     try {
-        finalMode = statSync(path).mode & 0o777;
+        finalMode = lstatSync(dest).mode & 0o777;
     }
     catch {
         finalMode = 0o666 & ~process.umask();
@@ -101,9 +173,9 @@ export function writeJsonFileAtomic(path, data) {
         // 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);
+        renameSync(tmpPath, dest);
         try {
-            chmodSync(path, finalMode);
+            chmodSync(dest, finalMode);
         }
         catch {
             // Best-effort, and deliberately after the rename rather than on the temp
@@ -113,7 +185,13 @@ export function writeJsonFileAtomic(path, data) {
             // already landed -- the caller would roll back a successful install.
         }
         try {
-            sweepStaleTempFiles(path, basename(tmpPath));
+            sweepStaleTempFiles(dest, basename(tmpPath));
+            // Every version before ahood-cli#144 put its temp file next to the LINK
+            // instead of next to the target, so a crash under one of those can have
+            // stranded a plaintext-secret orphan there that no later write would ever
+            // look at again. One extra sweep of the link's own directory retires them.
+            if (dest !== path)
+                sweepStaleTempFiles(path, basename(tmpPath));
         }
         catch {
             // Swallowed for the same reason as the chmod above and #119's unlink:
@@ -139,25 +217,116 @@ export function writeJsonFileAtomic(path, data) {
 function writeLockfile(path, lockfile) {
     writeJsonFileAtomic(path, lockfile);
 }
-// A lock directory is stale if the PID recorded inside it (written by the
-// acquirer below) belongs to a process that's no longer running, 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) {
+// The pid recorded in a lock directory by its acquirer below, or undefined if
+// there is no readable, plausible one: no pid file at all (a lock from before
+// this file existed, or one whose acquirer is still mid-way through setting it
+// up -- mkdirSync succeeded, the pid write hasn't landed yet), or contents
+// that don't parse as a pid.
+function readLockPid(pidFile) {
     let pidText;
     try {
         pidText = readFileSync(pidFile, "utf-8");
     }
     catch {
-        return false;
+        return undefined;
     }
     const pid = Number(pidText);
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    return isPidDead(pid);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+// A lock directory is stale if the pid recorded inside it belongs to a process
+// that's no longer running, per isPidDead above. No readable pid means "not
+// stale": safer to wait out a lock that may still be being set up than to
+// reclaim one that is actually held.
+function isLockStale(pidFile) {
+    const pid = readLockPid(pidFile);
+    return pid !== undefined && isPidDead(pid);
+}
+// Deliberately NOT the negation of isLockStale: with no readable pid at all a
+// lock is neither stale nor demonstrably held, and the two callers want
+// opposite answers in that case. Reclaiming needs proof the holder is dead
+// (hence isLockStale), while withLock's deadline branch needs proof that
+// someone is alive before it backs off a reclaim failure it already observed.
+function isLockHeldByLiveProcess(pidFile) {
+    const pid = readLockPid(pidFile);
+    return pid !== undefined && !isPidDead(pid);
+}
+// Name of the reclaim claim directory created inside a lock directory that is
+// about to be reclaimed. A single well-known name, deliberately not a
+// per-process one: its entire job is to be a name exactly one process can
+// create.
+const RECLAIM_CLAIM = "reclaiming";
+// Reclaiming a stale lock is a claim-verify-remove, not the bare
+// check-then-delete it used to be: two waiters could both judge the SAME dead
+// holder stale off the same snapshot, and then the second one's rmSync would
+// delete the first one's freshly-taken, live lock -- two processes inside the
+// critical section at once, which is the exact lost update on .mcp.json /
+// skills.lock.json that withLock exists to prevent (ahood-cli#141).
+//
+// The claim is a directory created INSIDE the lock directory, so it rides on
+// the same mkdir atomicity the lock itself is built on: exactly one waiter can
+// create it, and the losers fall through to the ordinary wait. Two
+// alternatives were weighed and rejected:
+//   - Merely re-reading the pid immediately before the rmSync narrows the
+//     window but never closes it; the check and the unlink still aren't atomic.
+//   - renameSync-ing the lock directory itself to a unique name makes the
+//     rename the claim, but a rename succeeds against WHATEVER directory sits
+//     at that path -- a live successor's included -- and it leaves the lock
+//     path briefly absent, so a third process can mkdir it and acquire for
+//     real. That manufactures two live holders rather than preventing them.
+// This claim never removes or rewrites anything a holder owns and never makes
+// the lock path vanish, so mutual exclusion survives even a claim that turns
+// out to have been a mistake.
+//
+// Winning the claim is what makes the staleness verdict trustworthy, which is
+// why the pid is re-read UNDER it: the directory judged stale a moment ago may
+// already have been reclaimed and retaken by someone alive. Once the claim is
+// held and the pid still reads dead, nothing else can remove that directory --
+// a release by its holder is ruled out by that dead pid, and every other
+// reclaimer is blocked by the claim -- so the verdict still holds at the moment
+// of the rmSync below.
+//
+// Returns the error to remember for withLock's deadline branch (see
+// ahood-cli#140), or undefined when there is nothing worth remembering.
+function reclaimStaleLock(lockDir, pidFile) {
+    const claim = join(lockDir, RECLAIM_CLAIM);
+    try {
+        mkdirSync(claim);
+    }
+    catch (error) {
+        const code = error.code;
+        // EEXIST means another waiter is reclaiming this very directory right now
+        // and ENOENT that it is already gone; both resolve themselves on the next
+        // retry. Anything else (EACCES/EPERM/EROFS on a directory this process
+        // cannot write into) is a reclaim that can never succeed, and is what the
+        // deadline branch reports instead of a misleading "waiting for the lock".
+        if (code === "EEXIST" || code === "ENOENT")
+            return undefined;
+        return existsSync(lockDir) ? error : undefined;
+    }
+    if (!isLockStale(pidFile)) {
+        // Not the directory that was judged stale after all -- it was reclaimed and
+        // retaken while this process looked, or it belongs to a holder that hasn't
+        // written its pid yet. Hand the claim back, leaving the lock exactly as it
+        // was found.
+        try {
+            rmSync(claim, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort: the holder's own release takes this directory, claim and
+            // all, with it. Worst case is a lock nothing reclaims, which times out
+            // with an actionable message rather than corrupting anything -- the same
+            // outcome as a process killed between the two syscalls above.
+        }
+        return undefined;
+    }
+    try {
+        rmSync(lockDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (existsSync(lockDir))
+            return error;
+    }
+    return undefined;
 }
 // Simple advisory lock via mkdir's atomicity (EEXIST on a second caller),
 // so two concurrent `ahood skill add`/`remove` invocations against the same
@@ -177,6 +346,15 @@ export function withLock(path, fn) {
     const lockDir = `${path}.lock`;
     const pidFile = join(lockDir, "pid");
     const deadline = Date.now() + 5000;
+    // Set when the lock was judged stale but could not actually be removed and
+    // that directory is still sitting there -- see the reclaim branch below.
+    // Reported instead of the generic timeout, because "another process holds
+    // the lock" sends the user hunting for a process that provably no longer
+    // exists (ahood-cli#140).
+    let reclaimError;
+    // Whether this process's own pid ever made it into the lock directory --
+    // what lets the release below tell its own lock from a successor's.
+    let wrotePid = false;
     for (;;) {
         try {
             mkdirSync(lockDir);
@@ -185,6 +363,7 @@ export function withLock(path, fn) {
             // just without staleness detection for this particular acquisition.
             try {
                 writeFileSync(pidFile, String(process.pid));
+                wrotePid = true;
             }
             catch {
                 // non-fatal, see comment above
@@ -194,22 +373,54 @@ export function withLock(path, fn) {
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
-            if (isLockStale(pidFile)) {
-                // Reclaim it. Best-effort removal: if a concurrent process wins the
-                // race and reclaims (or a live holder finishes and releases) first,
-                // this just falls through to the normal wait/retry below instead of
-                // throwing.
-                try {
-                    rmSync(lockDir, { recursive: true, force: true });
-                }
-                catch {
-                    // lost the race -- fall through to wait/retry
-                }
-                continue;
-            }
+            // The deadline is tested FIRST so that every retry path is bounded by
+            // it. The reclaim branch below used to `continue` straight past both
+            // this check and the sleep, so a stale lock this process could not
+            // actually remove (rmSync's force:true suppresses only ENOENT, never
+            // EACCES/EPERM/EROFS) turned into an unbounded 100%-CPU spin that never
+            // threw and never printed anything -- the one thing a CLI built to run
+            // unattended in CI must never do (ahood-cli#140).
             if (Date.now() > deadline) {
+                // The remembered failure is re-confirmed here rather than trusted,
+                // because a process that DOES have permission (a root/owner ahood in
+                // another terminal) can clear that directory and take the lock for
+                // real while this one waits -- and "the process that held it is gone"
+                // would then be a confident lie about a lock somebody is legitimately
+                // holding. Re-confirming asks exactly what the message claims: is
+                // there still a directory, and is nobody alive holding it? Identity
+                // (inode, birthtime) deliberately isn't used for this: a removed and
+                // immediately recreated directory routinely gets the same inode back,
+                // so it can't tell a replacement from the original anyway.
+                if (reclaimError && existsSync(lockDir) && !isLockHeldByLiveProcess(pidFile)) {
+                    throw new Error(`Could not reclaim the stale lock on ${path} at ${lockDir}: ${reclaimError.code ?? reclaimError.message}. The process that held it is gone, but this one cannot remove that directory -- delete it manually (it may belong to another user, e.g. left behind by a sudo/root run, or sit on a read-only filesystem).`);
+                }
                 throw new Error(`Timed out waiting for the lock on ${path} at ${lockDir}. If no other ahood process is running, delete that directory manually.`);
             }
+            if (isLockStale(pidFile)) {
+                // Reclaim it. Two very different conditions can fail that, and only
+                // one of them is the race the old comment here claimed: if the
+                // directory is GONE afterwards, a concurrent process reclaimed it (or
+                // a live holder released it) first, which is harmless -- the retry
+                // below simply takes the lock. If it is still THERE, this process
+                // cannot remove it at all, and retrying can only fail the same way,
+                // so the failure is remembered for the deadline branch above rather
+                // than swallowed (ahood-cli#140). It is remembered rather than thrown
+                // immediately because a mid-reclaim race can also surface as e.g.
+                // ENOTEMPTY with the directory still present, and that one does clear
+                // itself on the next attempt.
+                //
+                // The memory deliberately survives later iterations (hence `??`
+                // rather than a plain assignment): a failed recursive removal can take
+                // the `pid` file with it (it deletes the contents, then fails on the
+                // directory itself -- which of the two happens before the error is an
+                // implementation detail that differs between Node versions), and
+                // without a pid file isLockStale reports "not stale", so this branch
+                // never runs again and there is no second chance to observe the
+                // failure. Clearing it per-iteration made the error message depend on
+                // that detail, which is why it read correctly on one machine and fell
+                // back to the generic timeout on another (ahood-cli#145).
+                reclaimError = reclaimStaleLock(lockDir, pidFile) ?? reclaimError;
+            }
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
         }
     }
@@ -217,7 +428,30 @@ export function withLock(path, fn) {
         return fn();
     }
     finally {
-        rmSync(lockDir, { recursive: true, force: true });
+        // Releasing used to be an unconditional rmSync, which is only correct for
+        // as long as this process still holds the lock it took -- and it does not
+        // always. A reclaimer that judged this process dead can delete this lock
+        // out from under a running critical section (ahood-cli#141 on one host,
+        // and the host-local pid probe above across a container bind mount or a
+        // network share), and the unconditional removal then took the SUCCESSOR's
+        // lock down with it, turning one lost update into a chain of them.
+        // Removing only a directory that still records THIS process's pid keeps
+        // the damage to the process that was wronged.
+        //
+        // A pid file that is unreadable despite having been written is left alone
+        // for the same reason: the only thing that removes it is a reclaimer
+        // partway through taking this lock, so whatever is at that path is no
+        // longer this process's to delete.
+        //
+        // With no pid of this process's own ever written (the best-effort write
+        // above failed) there is nothing to compare against -- and nothing to
+        // protect either, since a lock directory with no readable pid is never
+        // judged stale and so can never have been reclaimed. Removing it
+        // unconditionally is then both safe and necessary: leaving it behind
+        // strands a lock that nothing is able to reclaim.
+        if (!wrotePid || readLockPid(pidFile) === process.pid) {
+            rmSync(lockDir, { recursive: true, force: true });
+        }
     }
 }
 export function writeLockfileEntry(path, ownerSlashSkill, entry) {

package/dist/terminal-safe.js

@@ -0,0 +1,62 @@
+// Control characters are replaced with a space rather than deleted so that
+// stripping can't silently glue two tokens into one misleading word.
+//
+// Newlines (\x0a) and carriage returns (\x0d) are inside this range and are
+// deliberately flattened too (ahood-cli#127): a forged prompt line
+// ("...\n\nEnter your token:") needs no escape sequence at all, just a
+// newline, so preserving them would leave the spoofing half of the threat
+// model open while closing the escape half. The readability cost is small
+// because callers bound what reaches here to a few lines' worth of text, not
+// a stack trace.
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/g;
+// Text that reaches the terminal but originates outside this CLI -- a manifest
+// field from a third-party-published archive, an error string forwarded by the
+// API -- can smuggle a terminal control sequence (cursor movement, line-clear)
+// that repaints what the user sees. That matters most in `add`, which prints
+// such text immediately before a masked secret prompt: the exact moment a
+// repaint can convince a user to type a credential into an attacker's message.
+// This 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 a caller's "string" may be a
+// declared type over an unchecked 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 that
+// same path (ahood-cli#122).
+export function sanitizeForTerminal(text, maxLength = 200) {
+    return String(text).replace(CONTROL_CHARACTERS, " ").slice(0, maxLength);
+}
+// Same C0/C1 range as CONTROL_CHARACTERS above, minus the three characters
+// that carry a document's layout rather than a terminal instruction: tab
+// (\x09), line feed (\x0a) and carriage return (\x0d).
+const CONTROL_CHARACTERS_EXCEPT_LAYOUT = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+// The document-shaped sibling of sanitizeForTerminal, for the one caller that
+// prints a whole publisher-authored file to a human's terminal
+// (`ahood skill read`, ahood-cli#133) rather than a field interpolated into a
+// CLI-authored message. Two of sanitizeForTerminal's decisions invert at that
+// size, which is why this is a separate function rather than an extra
+// argument on that one -- a flag that flips half of a function's documented
+// behaviour is harder to reason about than two functions with two rationales:
+//
+//   - Newlines are preserved. #127 flattens them because a forged prompt line
+//     ("...\n\nEnter your token:") needs no escape sequence at all, and that
+//     rationale explicitly rests on callers bounding input "to a few lines'
+//     worth of text". A markdown document is not that: flattening it yields
+//     one unreadable line, destroying the command. The spoofing risk it trades
+//     away is also much weaker here -- `read` prints and exits without ever
+//     prompting, and a user who typed `ahood skill read` has already been told
+//     they are looking at someone else's untrusted prose.
+//
+//   - There is no length cap. sanitizeForTerminal's 200 exists so one field
+//     can't flood the terminal; capping a document the user explicitly asked
+//     to read is its own failure mode, and a hostile one: a publisher could
+//     simply push the part worth hiding past the cap and let the CLI truncate
+//     it away, turning a safety measure into a concealment primitive. Once the
+//     escapes are gone the residue is plain text that scrolls -- which the
+//     terminal's scrollback, a pager, or Ctrl-C already handles, and which
+//     cannot repaint, retitle, or hide anything.
+//
+// Takes `unknown` for the same reason sanitizeForTerminal does (ahood-cli#122).
+export function sanitizeDocumentForTerminal(text) {
+    return String(text).replace(CONTROL_CHARACTERS_EXCEPT_LAYOUT, " ");
+}

package/package.json

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