@retasc/cli 1.3.0 → 1.3.2

package/dist/api.js

@@ -46,12 +46,16 @@ export function isAuthError(e) {
  *   1. If there is no stored token at all, the user was never signed in — this
  *      isn't an expiry, so rethrow the clean "sign in first" error rather than
  *      launching a surprise device flow under a misleading "session expired".
- *   2. `refreshSession()` — swap the refresh token for a fresh access token.
- *   3. If that fails (refresh token expired/invalid), fall back to a full
- *      `deviceLogin()` — but only when stdout is a TTY, since the device flow
- *      prints a code to stdout for a human to authorize; in a captured/piped
- *      context we surface a clear "run `retasc login`" error instead of hanging
- *      or spilling the prompt into someone's `$(retasc …)` capture.
+ *   2. `refreshSession()` — swap the refresh token for a fresh access token. A
+ *      transient backend failure here (network/5xx/masked "Server Error") is
+ *      rethrown by `refreshSession`, so it propagates out as a retryable error
+ *      instead of forcing a device-flow re-login on a valid session (RTSC-178).
+ *   3. If the refresh token is genuinely expired/invalid (a clean `false`, not a
+ *      throw), fall back to a full `deviceLogin()` — but only when stdout is a
+ *      TTY, since the device flow prints a code to stdout for a human to
+ *      authorize; in a captured/piped context we surface a clear "run `retasc
+ *      login`" error instead of hanging or spilling the prompt into someone's
+ *      `$(retasc …)` capture.
  * A second auth failure after recovery is real (rethrown) — we never loop.
  */
 async function withAuth(call) {

package/dist/auth.js

@@ -76,6 +76,31 @@ export async function deviceLogin() {
     }
     patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
 }
+/**
+ * Does this thrown error clearly mean "this refresh token can never mint a new
+ * session" — as opposed to a transient backend blip? RTSC-178.
+ *
+ * Note the asymmetry in how Convex Auth's refresh grant fails:
+ *   - A genuinely expired/invalid/reused refresh token does NOT throw — the
+ *     server returns `{ tokens: null }`, which `refreshSession` already reads as
+ *     `false` (no exception reaches here).
+ *   - The `catch` only sees *thrown* errors: network failures, 5xx, and the
+ *     opaque masked "Server Error" prod returns for any uncaught server-side
+ *     throw — all transient — plus the rare corrupt/unparseable stored token
+ *     (`parseRefreshToken` throws "Can't parse refresh token …").
+ *
+ * So we default to "transient" and only classify as unrefreshable when the
+ * message is unmistakably refresh-token-shaped. In prod a corrupt-token throw is
+ * itself masked to "Server Error" and so reads as transient — the deliberate,
+ * safe bias (RTSC-165 saw exactly this masking): never drag a user with a valid
+ * session through the whole device flow on a one-off hiccup. A truly dead
+ * refresh token still reaches `deviceLogin` via the `{ tokens: null }` → `false`
+ * path above, unaffected by this classifier.
+ */
+export function isUnrefreshableRefreshToken(err) {
+    const msg = String(err?.message ?? err);
+    return /can'?t parse refresh token|cannot parse refresh token|invalid refresh token|expired refresh token|refresh token (?:is |has )?(?:invalid|expired)/i.test(msg);
+}
 /**
  * Silently mint a fresh access token from the stored refresh token and persist
  * the rotated pair to ~/.retasc/config.json.
@@ -88,10 +113,12 @@ export async function deviceLogin() {
  * tokens are single-use; the old one is invalidated), so we must write the new
  * pair back immediately and never reuse the old refresh token.
  *
- * Returns true on success (config now holds a fresh session), false if there is
- * no refresh token or the grant is rejected (expired/invalid/reused) — the
- * caller then falls back to a full `deviceLogin()`. Never throws and never
- * prints token values.
+ * Returns true on success (config now holds a fresh session), false when there
+ * is no refresh token or the grant is cleanly rejected (expired/invalid/reused,
+ * which the server signals as `{ tokens: null }`) — the caller then falls back
+ * to a full `deviceLogin()`. A *transient* failure (network/5xx/opaque backend
+ * blip) is RE-THROWN so the caller can surface a retryable error instead of
+ * forcing a needless device-flow re-login (RTSC-178). Never prints token values.
  */
 export async function refreshSession() {
     const cfg = loadConfig();
@@ -106,9 +133,14 @@ export async function refreshSession() {
         patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
         return true;
     }
-    catch {
-        // Expired/invalid/reused refresh token, or a transient backend error. Treat
-        // as "cannot refresh" — the caller re-authenticates via the device flow.
-        return false;
+    catch (err) {
+        // A clearly refresh-token-shaped rejection means we genuinely cannot
+        // refresh — fall through to device login. Anything else (network, 5xx,
+        // masked prod "Server Error") is transient: rethrow so `withAuth` surfaces a
+        // retryable error rather than dragging a valid session through the device
+        // flow at an hourly access-token boundary.
+        if (isUnrefreshableRefreshToken(err))
+            return false;
+        throw err;
     }
 }

package/dist/config.js

@@ -1,6 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, chmodSync, openSync, closeSync, writeSync, statSync, readdirSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 // Production defaults. Overridable via env for dev/testing.
 //   RETASC_DEPLOYMENT_URL — Convex deployment (.cloud) for management calls
 //   RETASC_MCP_URL        — the MCP endpoint agents connect to
@@ -8,20 +9,41 @@ export const DEFAULTS = {
     deploymentUrl: process.env.RETASC_DEPLOYMENT_URL ?? "https://unique-lyrebird-934.convex.cloud",
     mcpUrl: process.env.RETASC_MCP_URL ?? "https://mcp.retasc.com/mcp",
 };
-const DIR = join(homedir(), ".retasc");
-const FILE = join(DIR, "config.json");
+/** The dir config lives in. RETASC_DIR overrides it (tests, sandboxes) — same
+ *  knob the keystore reads, so the two stay co-located. */
+function configDir() {
+    return process.env.RETASC_DIR || join(homedir(), ".retasc");
+}
 export function configPath() {
-    return FILE;
+    return join(configDir(), "config.json");
 }
 export function loadConfig() {
+    const FILE = configPath();
     let stored = {};
     if (existsSync(FILE)) {
+        let raw;
         try {
-            stored = JSON.parse(readFileSync(FILE, "utf8"));
+            raw = readFileSync(FILE, "utf8");
         }
         catch {
-            // Corrupt config — start fresh rather than crash.
-            stored = {};
+            // A read that FAILS (file lock, EIO, EMFILE, stale NFS handle) is transient,
+            // not corruption. Leave the file untouched and fall back to defaults for this
+            // run — self-heal next time — rather than renaming a possibly-valid config
+            // aside and turning a blip into a permanent logout.
+            raw = undefined;
+        }
+        if (raw !== undefined) {
+            try {
+                stored = JSON.parse(raw);
+            }
+            catch {
+                // Read succeeded but the bytes aren't valid JSON → genuinely corrupt/
+                // truncated (e.g. an interrupted write). Preserve them under a backup name
+                // rather than silently discarding — the file may still hold the only copy
+                // of the user's tokens, recoverable by hand. Then start fresh.
+                backupCorruptConfig(FILE);
+                stored = {};
+            }
         }
     }
     // Defaults fill in; a saved value always wins.
@@ -35,25 +57,200 @@ export function loadConfig() {
         defaultProjectPrefix: stored.defaultProjectPrefix,
     };
 }
+/** Move a corrupt config aside to a unique sibling so a human can recover any
+ *  tokens it still holds. Best effort — never throw from the load path. */
+function backupCorruptConfig(file) {
+    try {
+        renameSync(file, `${file}.corrupt-${randomUUID()}`);
+    }
+    catch {
+        /* best effort — if we can't back it up, saveConfig will overwrite it */
+    }
+}
 export function saveConfig(cfg) {
-    // Create the dir user-only and the file 0600 on the initial write, so tokens
-    // never exist world-readable even briefly (the chmod below only closes a
-    // pre-existing 0644 file — it can't undo a world-readable creation window).
-    mkdirSync(DIR, { recursive: true, mode: 0o700 });
-    writeFileSync(FILE, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
-    // Tokens live here — keep it user-only readable (covers overwriting an
-    // existing 0644 file, where the write mode above doesn't apply).
+    const dir = configDir();
+    const FILE = configPath();
+    // Create the dir user-only and the temp file 0600, so tokens never exist
+    // world-readable even briefly (the chmod below only closes a pre-existing
+    // 0644 file — it can't undo a world-readable creation window).
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Atomic write: fully write a sibling temp file, then rename it over the real
+    // one. rename(2) is atomic on POSIX, so a crash or an interleaved write leaves
+    // either the old complete config or the new one — never a truncated file that
+    // loadConfig would read as "logged out". The temp lives in the same dir so the
+    // rename stays on one filesystem (a cross-device rename is not atomic).
+    const tmp = join(dir, `.config.json.${randomUUID()}.tmp`);
+    const body = JSON.stringify(cfg, null, 2) + "\n";
+    try {
+        writeFileSync(tmp, body, { encoding: "utf8", mode: 0o600 });
+        try {
+            chmodSync(tmp, 0o600); // keep user-only if a umask/prior file loosened it
+        }
+        catch {
+            /* best effort (e.g. Windows) */
+        }
+        renameSync(tmp, FILE);
+    }
+    catch (err) {
+        // Don't leave a stray temp file behind on failure.
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* already gone */
+        }
+        throw err;
+    }
+    // Best-effort GC of temp siblings orphaned by a hard kill (SIGKILL / power loss)
+    // between writeFileSync(tmp) and renameSync above — otherwise they accumulate in
+    // ~/.retasc forever across crashes. Runs after our own rename so our temp is
+    // already gone. Age-gated (see sweepStaleTemps) so it never touches a concurrent
+    // writer's in-flight temp.
+    sweepStaleTemps(dir);
+}
+/** A temp sibling this much older than now was orphaned by a crash, not left by a
+ *  live writer — any real writeFileSync→renameSync window is milliseconds. */
+const TEMP_STALE_MS = 60_000;
+/** Delete `.config.json.<uuid>.tmp` leftovers only once they're demonstrably stale,
+ *  so an unconditional sweep can't race-delete a concurrent writer's fresh temp
+ *  (which would reintroduce the very lost-update class this file guards against). */
+function sweepStaleTemps(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return; // dir vanished / unreadable — nothing to sweep
+    }
+    const now = Date.now();
+    for (const name of entries) {
+        if (!name.startsWith(".config.json.") || !name.endsWith(".tmp"))
+            continue;
+        const p = join(dir, name);
+        try {
+            if (now - statSync(p).mtimeMs > TEMP_STALE_MS)
+                unlinkSync(p);
+        }
+        catch {
+            /* raced another sweeper or a writer's own rename — fine, leave it */
+        }
+    }
+}
+// --- Cross-process config lock -------------------------------------------------
+// saveConfig is byte-atomic (temp + rename) but that is NOT isolation: two
+// concurrent load→modify→save sequences both read the old file and the last
+// rename wins, silently dropping the other's fields (RTSC-250). The dangerous
+// case: a `defaultProjectPrefix` write that began before a token refresh writes
+// back the OLD single-use refreshToken, so the next refresh fails and a
+// non-interactive MCP context can't re-run the device flow. An advisory lock file
+// serializes the whole read-modify-write across processes, so every patcher
+// re-reads the freshest config (including a just-rotated token) before writing.
+//
+// Assumes a coherent LOCAL clock: the staleness heuristic compares a lock file's
+// mtime (set by the host that created it) against this host's Date.now(). That
+// holds for the intended case — several processes on ONE machine sharing one
+// ~/.retasc. On a network home with a skewed server clock it degrades to
+// best-effort (over-eager or over-lazy stealing); we don't target that here.
+// Any whole-file mutating writer MUST go through patchConfig so it takes the
+// lock — saveConfig alone is not self-locking (logout's delete is the one benign
+// exception: racing a refresh there is a user-intent race, not a durability bug).
+/** A lock whose mtime is older than this belongs to a holder that died without
+ *  releasing it (a crash leaves the O_EXCL file behind); break it so a crash
+ *  can't wedge every future patch forever. Far larger than any real hold, which
+ *  is a synchronous read+write of a tiny file (single-digit ms). */
+const LOCK_STALE_MS = 30_000;
+/** Absolute backstop: if staleness somehow never frees the lock, force it after
+ *  this. Kept ABOVE the stale threshold so normal breaking is governed by
+ *  staleness, not by a timer that could guillotine a merely-slow live holder. */
+const LOCK_TIMEOUT_MS = 60_000;
+const LOCK_BACKOFF_MS = 25;
+/** Block this (single) thread for `ms` without busy-spinning. Node is
+ *  single-threaded; the lock we wait on is released by ANOTHER process, so
+ *  parking the thread is correct — nothing here could release it. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** The current holder's identity + age, or undefined if the lock just vanished. */
+function readLockHolder(lockPath) {
+    try {
+        const nonce = readFileSync(lockPath, "utf8");
+        return { nonce, ageMs: Date.now() - statSync(lockPath).mtimeMs };
+    }
+    catch {
+        return undefined; // gone between our failed create and this read → just retry
+    }
+}
+/** Run `fn` holding an exclusive on-disk lock, so its read-modify-write of the
+ *  config can't interleave with another process's. Each acquirer stamps a unique
+ *  nonce into the lock file; steal and release only ever remove a lock whose nonce
+ *  still matches the one we observed, so a holder that was judged stale and had its
+ *  lock stolen can't later delete the DIFFERENT holder's lock (which would collapse
+ *  mutual exclusion back into the lost-update this whole mechanism prevents). */
+function withConfigLock(fn) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const lockPath = join(dir, ".config.json.lock");
+    const nonce = randomUUID();
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let fd;
+    for (;;) {
+        try {
+            // "wx" = O_CREAT | O_EXCL | O_WRONLY — atomically fails if the lock is held.
+            fd = openSync(lockPath, "wx", 0o600);
+            writeSync(fd, nonce); // stamp our identity so steal/release can verify it
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const holder = readLockHolder(lockPath);
+            if (!holder)
+                continue; // vanished → retry the create immediately
+            if (holder.ageMs > LOCK_STALE_MS || Date.now() > deadline) {
+                // Dead holder (stale) or backstop expired: break THIS holder's lock only.
+                // If a fresh acquirer replaced it since our read, the nonce differs and we
+                // leave it — never steal a live lock out from under a new owner.
+                breakLockIf(lockPath, holder.nonce);
+                continue;
+            }
+            sleepSync(LOCK_BACKOFF_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* already closed */
+        }
+        // Only remove the lock if it's still OURS. If we were stolen from while stalled,
+        // the file now holds another holder's nonce — leave it for them.
+        breakLockIf(lockPath, nonce);
+    }
+}
+/** Unlink the lock only if it still carries `nonce` — a nonce-checked delete, so
+ *  we never remove a lock a different process now owns. */
+function breakLockIf(lockPath, nonce) {
     try {
-        chmodSync(FILE, 0o600);
+        if (readFileSync(lockPath, "utf8") === nonce)
+            unlinkSync(lockPath);
     }
     catch {
-        /* best effort (e.g. Windows) */
+        /* already gone, replaced, or unreadable — nothing safe to do */
     }
 }
 export function patchConfig(patch) {
-    const next = { ...loadConfig(), ...patch };
-    saveConfig(next);
-    return next;
+    // Load AND save under the lock: re-reading inside the critical section is what
+    // makes this safe — a patch that only sets `defaultProjectPrefix` still picks up
+    // a refreshToken another process rotated a moment ago, instead of clobbering it.
+    return withConfigLock(() => {
+        const next = { ...loadConfig(), ...patch };
+        saveConfig(next);
+        return next;
+    });
 }
 export function isLoggedIn(cfg = loadConfig()) {
     return Boolean(cfg.token);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {