@niroai/niro 0.3.0

package/src/commands/watch.js

@@ -0,0 +1,498 @@
+/**
+ * `niro watch [path]` — resume watching a registered local repo.
+ *
+ * On startup:
+ *   1. Load gitId + patterns + fileHashes from ~/.niro/projects.json
+ *   2. Delta sync: walk included paths, compare file hashes, upload changed files
+ *   3. Start fs.watch loop (recursive) for ongoing changes
+ *   4. Heartbeat every 30s
+ *
+ * Also exported as `startWatch(dir)` so `niro add repo` can transition into
+ * watch mode automatically after initial sync.
+ */
+const path = require("path");
+const fs = require("fs");
+const api = require("../lib/api");
+const agentApi = require("../lib/agentApi");
+const watchState = require("../lib/watchState");
+const credentials = require("../lib/credentials");
+const prompt = require("../lib/prompt");
+const color = require("../lib/color");
+const folderSync = require("../lib/folderSync");
+const {
+  SOURCE_EXTENSIONS, STRUCTURAL_EXTENSIONS, STRUCTURAL_FILENAMES,
+  IGNORED_DIRS, isConfigName, chunk,
+} = folderSync;
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const DEBOUNCE_MS = 2_000;
+// Folders with a deltaSyncOnResume in flight. The 60s backstop, live file events, and the startup sync can
+// otherwise run concurrently for the same folder; each ends with a whole-map `watchState.update({fileHashes})`,
+// so a slower run would clobber a faster one's hash updates. A per-folder guard serializes them (a skipped
+// run is safe — the in-progress one re-hashes the whole tree and so already covers the skipped trigger).
+const syncInFlight = new Set();
+// The state file is rewritten several times during a `niro takeover` (per-file hashes), so debounce
+// before reconciling the watch set. Also the interval for the mtime backstop re-scan below.
+const STATE_RELOAD_DEBOUNCE_MS = 1_500;
+const RESCAN_INTERVAL_MS = 60_000;
+
+async function watch(pathArg, opts = {}) {
+  const creds = credentials.requireCreds();
+
+  if (!pathArg) {
+    // Watch all registered local repos for the CURRENT backend (entries from
+    // another stack are skipped — their gitIds are invalid here).
+    const all = watchState.allLocal(api.currentBaseUrl());
+    if (all.length === 0) {
+      console.error("No registered local repos found. Run `niro add repo` first.");
+      process.exitCode = 1;
+      return;
+    }
+    // Daemon safety net: ONE bad entry or one stray fs/network error must never kill the
+    // whole daemon. A crash-looping daemon (PM2 auto-restart) re-syncs and re-marks every
+    // project stale on each restart, causing endless rebuild churn server-side.
+    process.on("uncaughtException", (err) =>
+      console.error(color.red(`Watch daemon error (recovered): ${err && err.message ? err.message : err}`)));
+    process.on("unhandledRejection", (err) =>
+      console.error(color.red(`Watch daemon error (recovered): ${err && err.message ? err.message : err}`)));
+    const watched = new Set();
+    for (const entry of all) {
+      watched.add(path.resolve(entry.folderPath));
+      startWatch(entry.folderPath, opts).catch(err => handleEntryFailure(entry, err, watched));
+    }
+    // Pick up folders added by `niro takeover` / `niro add repo` WITHOUT a daemon restart. Those commands
+    // rewrite the state file, so watch it and start watching any NEW entry live. (A takeover that only
+    // re-points an ALREADY-watched folder's gitId is handled per-event by handleFileEvent re-reading
+    // watchState; this covers the other half — a brand-new folder the daemon wasn't started with.)
+    let reconcileTimer = null;
+    const reconcile = () => {
+      if (reconcileTimer) clearTimeout(reconcileTimer);
+      reconcileTimer = setTimeout(() => {
+        for (const entry of watchState.allLocal(api.currentBaseUrl())) {
+          const resolved = path.resolve(entry.folderPath);
+          if (!watched.has(resolved)) {
+            watched.add(resolved);
+            console.log(`  ${color.green("↻")} Now watching new folder: ${entry.folderPath}`);
+            startWatch(entry.folderPath, opts).catch(err => handleEntryFailure(entry, err, watched));
+          }
+        }
+      }, STATE_RELOAD_DEBOUNCE_MS);
+    };
+    // Watch the DIRECTORY, not the file: watchState writes projects.json via atomic tmp+rename, which
+    // swaps the inode — an fs.watch bound to the FILE stops firing after the first rewrite (and the daemon's
+    // own 60s backstop guarantees a rewrite), so new folders added mid-session were never picked up. A watch
+    // on the parent dir has a stable inode and survives the rename; filter events to the state file's name.
+    try {
+      const stateDir = path.dirname(watchState.FILE);
+      const stateName = path.basename(watchState.FILE);
+      fs.watch(stateDir, { persistent: false }, (_evt, filename) => {
+        if (!filename || filename === stateName) reconcile();
+      }).on("error", (err) =>
+        console.error(color.yellow(`  State-file watcher error (recovered): ${err.message}`)));
+    } catch (err) {
+      console.error(color.yellow(`  Could not watch the state file for new folders: ${err.message}`));
+    }
+    // Keep process alive
+    await new Promise(() => {});
+    return;
+  }
+
+  const targetDir = path.isAbsolute(pathArg) ? path.resolve(pathArg) : path.resolve(process.cwd(), pathArg);
+  await startWatch(targetDir, opts);
+}
+
+/**
+ * One watch entry failed to start (its startup delta sync threw). Contain the failure to that
+ * entry — and when the cause is "the repo no longer exists on this backend" (a poison entry left
+ * by a deleted/rebuilt repo), SELF-HEAL by removing the entry, same policy as `niro init`'s
+ * repoExists re-run guard. Everything else is kept for retry on the next daemon start.
+ * Exported for tests.
+ */
+async function handleEntryFailure(entry, err, watched) {
+  if (agentApi.isRepoNotFound(err)) {
+    try {
+      const exists = await agentApi.repoExists(entry.gitId);
+      if (!exists) {
+        // Compare-and-delete by gitId: during the repoExists round-trip a concurrent new-temp-project may
+        // have re-pointed this folder to a NEW valid gitId — don't clobber that fresh registration.
+        const removed = watchState.remove(entry.folderPath, entry.gitId);
+        if (!removed) {
+          console.error(color.yellow(
+            `  Self-heal skipped for ${entry.folderPath}: it was re-pointed to a new repo mid-check — kept.`));
+          return;
+        }
+        // CRITICAL: also drop the folder from the daemon's live `watched` set. Otherwise, when the same
+        // folder is re-added with a NEW gitId (e.g. `niro sandbox` after the old sandbox was discarded),
+        // the reconcile loop sees it as "already watched" and never re-watches it — the folder's edits
+        // silently stop syncing until a full daemon restart. Pruning here lets the reconcile re-adopt it.
+        if (watched) watched.delete(path.resolve(entry.folderPath));
+        console.error(color.yellow(
+          `  Self-healed: ${entry.folderPath} pointed at a repo that no longer exists on this ` +
+          `backend (${entry.gitId}) — entry removed; other folders unaffected.`));
+        return;
+      }
+    } catch {
+      // Can't verify — treat as transient below.
+    }
+  }
+  console.error(color.red(
+    `Watch error for ${entry.folderPath}: ${err.message} — entry kept, will retry on next daemon start.`));
+}
+
+async function startWatch(targetDir, opts = {}) {
+  // Scope to the current backend: a folder registered against a different stack
+  // has a gitId that is invalid here, so resume must refuse rather than 404 on
+  // every sync. (The daemon's allLocal() already filters; this also guards the
+  // explicit `niro watch <path>` entry point.)
+  const state = watchState.get(targetDir, api.currentBaseUrl());
+  if (!state || !state.gitId) {
+    console.error(color.red(`No registration found for ${targetDir} on this backend. Run \`niro add repo\` first.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const { gitId } = state;
+
+  console.log(`\n  ${color.cyan("Watching")} ${targetDir}`);
+  console.log(`  gitId: ${color.dim(gitId)}`);
+
+  // Delta sync on startup. A repo-not-found error must still propagate so the caller's handleEntryFailure
+  // can self-heal a poison entry. But a TRANSIENT failure (network blip at daemon start) must NOT prevent
+  // the watcher + backstop from being installed below — otherwise the folder is left permanently unwatched
+  // for the whole session, and the reconcile loop treats it as "already watched" and never retries it. Catch
+  // transient errors here and let the periodic backstop re-sync once connectivity returns.
+  try {
+    await deltaSyncOnResume(gitId, targetDir, state);
+  } catch (err) {
+    if (agentApi.isRepoNotFound(err)) throw err; // poison entry — let handleEntryFailure remove it
+    console.error(color.yellow(
+      `  Initial sync failed for ${targetDir} (${err.message}) — watching anyway; the backstop will retry.`));
+  }
+
+  // Start heartbeat. Re-read fresh state each tick exactly like the backstop below: a `niro
+  // new-temp-project` / `niro discard-temp-project` re-point mid-session changes the folder's gitId, and a
+  // discard removes the entry entirely — heartbeating the startup gitId would ping the WRONG repo forever
+  // (or a now-deleted one every 30s after a discard).
+  const heartbeatTimer = setInterval(async () => {
+    try {
+      const fresh = watchState.get(targetDir, api.currentBaseUrl());
+      if (!fresh || !fresh.gitId) return; // folder released — nothing to heartbeat
+      await agentApi.heartbeat(fresh.gitId);
+    } catch {
+      // Non-fatal — network may be temporarily unavailable
+    }
+  }, HEARTBEAT_INTERVAL_MS);
+
+  // Periodic backstop re-scan. fs.watch silently DROPS events (recursive watches especially, and on
+  // some editors/filesystems), so a real edit can be missed and never synced until the next daemon
+  // restart. Every RESCAN_INTERVAL_MS, re-hash the tree against the recorded hashes and sync anything
+  // that drifted — the reliable, content-checked form of "also pick up changes we didn't get a live
+  // event for". Re-reads fresh state, so a folder re-pointed by `niro takeover` or removed by `niro
+  // release` mid-session is handled (or skipped) rather than synced to a stale gitId.
+  const rescanTimer = setInterval(() => {
+    const fresh = watchState.get(targetDir, api.currentBaseUrl());
+    if (!fresh || !fresh.gitId) return; // folder released — nothing to sync
+    deltaSyncOnResume(fresh.gitId, targetDir, fresh, { quiet: true }).catch(err =>
+      console.error(color.red(`  Backstop re-scan failed for ${targetDir}: ${err.message}`)));
+  }, RESCAN_INTERVAL_MS);
+
+  // Start file watcher
+  const debounceTimers = new Map();
+
+  const watcher = fs.watch(targetDir, { recursive: true }, (eventType, filename) => {
+    if (!filename) return;
+    const relativePath = filename.replace(/\\/g, "/");
+    if (shouldIgnore(relativePath)) return;
+
+    // Clear existing debounce for this path
+    if (debounceTimers.has(relativePath)) {
+      clearTimeout(debounceTimers.get(relativePath));
+    }
+
+    debounceTimers.set(relativePath, setTimeout(() => {
+      debounceTimers.delete(relativePath);
+      // A rejection here would be an unhandled promise rejection = process death in
+      // modern Node. One file's failure must never take the daemon down.
+      handleFileEvent(gitId, targetDir, relativePath, state).catch(err =>
+        console.error(color.red(`  Watch event failed for ${relativePath}: ${err.message}`)));
+    }, DEBOUNCE_MS));
+  });
+
+  // fs.watch emits 'error' events (EMFILE, watched dir removed, …); with no listener
+  // an EventEmitter 'error' THROWS and kills the process.
+  watcher.on("error", (err) =>
+    console.error(color.red(`  Watcher error for ${targetDir}: ${err.message}`)));
+
+  console.log(`  ${color.green("✓")} Watching for changes. Press Ctrl+C to stop.\n`);
+
+  // Graceful shutdown
+  process.on("SIGINT", () => {
+    clearInterval(heartbeatTimer);
+    clearInterval(rescanTimer);
+    watcher.close();
+    for (const t of debounceTimers.values()) clearTimeout(t);
+    console.log("\n  Watch stopped.");
+    process.exit(0);
+  });
+
+  // Keep alive
+  await new Promise(() => {});
+}
+
+async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
+  const inFlightKey = path.resolve(targetDir);
+  if (syncInFlight.has(inFlightKey)) {
+    // A sync (startup, live event, or backstop) is already running for this folder — skip to avoid the
+    // whole-map fileHashes clobber race; the in-progress run re-hashes the whole tree and covers this trigger.
+    return;
+  }
+  syncInFlight.add(inFlightKey);
+  try {
+  const quiet = opts.quiet === true; // periodic backstop re-scan runs silently unless it actually syncs
+  const storedHashes = state.fileHashes || {};
+  const currentHashes = {};
+  const changed = [];
+  const deleted = [];
+
+  // Walk all currently included files
+  const manifest = buildMinimalManifest(targetDir, state.includePatterns, state.excludePatterns);
+
+  for (const relativePath of manifest) {
+    const absPath = path.join(targetDir, relativePath);
+    const hash = watchState.hashFile(absPath);
+    if (!hash) continue;
+    currentHashes[relativePath] = hash;
+    if (storedHashes[relativePath] !== hash) {
+      changed.push(relativePath);
+    }
+  }
+
+  // Files that were in stored hashes but no longer exist
+  for (const rp of Object.keys(storedHashes)) {
+    if (!currentHashes[rp]) {
+      deleted.push(rp);
+    }
+  }
+
+  if (changed.length === 0 && deleted.length === 0) {
+    if (!quiet) console.log(`  No changes since last sync.`);
+    watchState.update(targetDir, { fileHashes: currentHashes });
+    return;
+  }
+
+  // A quiet backstop run only speaks up when it actually found something fs.watch missed.
+  console.log(`  ${quiet ? color.yellow("↻ backstop: ") : ""}Delta: ${changed.length} changed, ${deleted.length} deleted — syncing...`);
+
+  // Honor .gitignore (+ fail-closed-for-config) on the changed set BEFORE upload,
+  // using the same helper as init/add-repo. A gitignored secret edited after
+  // onboarding (e.g. a raw .env) must never be re-uploaded here.
+  let changedToUpload = changed;
+  if (changed.length > 0) {
+    const drops = folderSync.gitignoreDrops(targetDir, changed);
+    if (drops.size > 0) {
+      changedToUpload = changed.filter(rp => !drops.has(rp));
+      // Don't persist hashes for dropped (gitignored / unverifiable) files — they
+      // were never uploaded, so leave them out of state so they're re-evaluated
+      // rather than recorded as synced.
+      for (const rp of drops) delete currentHashes[rp];
+    }
+  }
+
+  // Use a sync session for the delta (atomic move on complete)
+  if (changedToUpload.length > 0) {
+    const sessionId = await agentApi.startSync(gitId);
+    const batches = chunk(changedToUpload, folderSync.BATCH_SIZE);
+    let uploaded = 0;
+    for (const batch of batches) {
+      const fileBatch = batch.map(rp => ({ relativePath: rp, absolutePath: path.join(targetDir, rp) }));
+      await agentApi.uploadFileBatch(gitId, sessionId, fileBatch);
+      uploaded += fileBatch.length;
+      process.stdout.write(`\r  Uploading delta... ${uploaded}/${changedToUpload.length}`);
+    }
+    process.stdout.write("\n");
+    await agentApi.completeSync(gitId, sessionId);
+  }
+
+  for (const rp of deleted) {
+    try {
+      await agentApi.deleteFile(gitId, rp);
+    } catch (err) {
+      console.warn(color.yellow(`  Warning: failed to delete ${rp}: ${err.message}`));
+    }
+  }
+
+  watchState.update(targetDir, { fileHashes: currentHashes, lastSyncedAt: new Date().toISOString() });
+  console.log(`  ${color.green("✓")} Delta sync complete.`);
+  } finally {
+    syncInFlight.delete(inFlightKey);
+  }
+}
+
+async function handleFileEvent(gitId, targetDir, relativePath, state) {
+  // Re-read this folder's current state on every event instead of trusting the value
+  // captured when the daemon started. A mid-session `niro takeover` re-points the folder
+  // at a NEW working-copy gitId (and `niro release` removes it); without this re-read the
+  // daemon kept uploading to the OLD gitId — every edit failed with "Repository not found"
+  // until the daemon was manually restarted. Reading fresh also picks up include/exclude
+  // pattern changes from `niro edit`.
+  const fresh = watchState.get(targetDir, api.currentBaseUrl());
+  if (!fresh || !fresh.gitId) {
+    // Folder was released / is no longer tracked for this backend — stop syncing it.
+    return;
+  }
+  gitId = fresh.gitId;
+  state = fresh;
+
+  if (!matchesPatterns(relativePath, state.includePatterns, state.excludePatterns)) {
+    // New path — check if it's a directory we haven't seen before
+    const absPath = path.join(targetDir, relativePath);
+    let isDirectory = false;
+    try {
+      // existsSync/statSync race: the path can vanish between the two calls (editor temp
+      // files do this constantly) — a throw here must not escape the event handler.
+      isDirectory = fs.existsSync(absPath) && fs.statSync(absPath).isDirectory();
+    } catch {
+      return;
+    }
+    if (isDirectory) {
+      const topDir = relativePath.split("/")[0];
+      if (topDir && !state.excludePatterns.some(p => p.startsWith(topDir))) {
+        if (prompt.isNonInteractive()) {
+          // A daemon has no TTY — never block on (or crash in) a prompt. Leave the
+          // directory unsynced and tell the user how to include it.
+          console.log(color.yellow(
+            `  New directory '${relativePath}' detected — not synced. ` +
+            `Run \`niro watch\` interactively (or \`niro edit\`) to include it.`));
+          return;
+        }
+        const add = await prompt.confirm(
+          `\n  New directory '${relativePath}' detected. Add to sync?`,
+          false
+        );
+        if (add) {
+          const newPattern = relativePath + "/**";
+          state.includePatterns.push(newPattern);
+          watchState.update(targetDir, { includePatterns: state.includePatterns });
+          console.log(`  Added include pattern: ${color.cyan(newPattern)}`);
+        } else {
+          state.excludePatterns.push(relativePath + "/**");
+          watchState.update(targetDir, { excludePatterns: state.excludePatterns });
+        }
+      }
+      return;
+    }
+    return; // not a source file or not matched
+  }
+
+  const absPath = path.join(targetDir, relativePath);
+
+  if (!fs.existsSync(absPath)) {
+    // File deleted
+    try {
+      await agentApi.deleteFile(gitId, relativePath);
+      const hashes = { ...(watchState.get(targetDir) || {}).fileHashes };
+      delete hashes[relativePath];
+      watchState.update(targetDir, { fileHashes: hashes, lastSyncedAt: new Date().toISOString() });
+      console.log(`  ${color.yellow("−")} ${relativePath}`);
+    } catch (err) {
+      console.error(color.red(`  Failed to delete ${relativePath}: ${err.message}`));
+    }
+    return;
+  }
+
+  // Only upload files in the accept set (source / structural / committed config).
+  // matchesPatterns can pass anything when the server-supplied includePatterns are
+  // empty; this keeps the per-file event from uploading stray files (e.g. a *.txt
+  // that could carry secrets), matching what the manifest walk would offer.
+  if (!folderSync.isUploadableName(relativePath)) return;
+
+  // File changed or created
+  const newHash = watchState.hashFile(absPath);
+  const storedHashes = (watchState.get(targetDir) || {}).fileHashes || {};
+  if (newHash && storedHashes[relativePath] === newHash) return; // no actual change
+
+  // Honor .gitignore (+ fail-closed-for-config) before uploading this one file,
+  // same policy as init/add-repo and the delta resume. A gitignored file (or, if
+  // git can't answer on a work tree, an unverifiable config/env file) is skipped
+  // so a secret is never leaked. We do NOT record its hash, so it is re-evaluated
+  // on the next event rather than silently treated as synced.
+  if (folderSync.gitignoreDrops(targetDir, [relativePath]).has(relativePath)) {
+    return;
+  }
+
+  try {
+    await agentApi.upsertFile(gitId, relativePath, absPath);
+    const hashes = { ...storedHashes, [relativePath]: newHash };
+    watchState.update(targetDir, { fileHashes: hashes, lastSyncedAt: new Date().toISOString() });
+    console.log(`  ${color.green("+")} ${relativePath}`);
+  } catch (err) {
+    console.error(color.red(`  Failed to sync ${relativePath}: ${err.message}`));
+  }
+}
+
+function shouldIgnore(relativePath) {
+  const parts = relativePath.replace(/\\/g, "/").split("/");
+  return parts.some(p => IGNORED_DIRS.has(p) || p.startsWith("."));
+}
+
+function matchesPatterns(relativePath, includePatterns, excludePatterns) {
+  if (!includePatterns || includePatterns.length === 0) return true;
+  const matched = includePatterns.some(p => minimatch(relativePath, p));
+  if (!matched) return false;
+  if (!excludePatterns || excludePatterns.length === 0) return true;
+  return !excludePatterns.some(p => minimatch(relativePath, p));
+}
+
+/** Simple glob matching without a dependency: handles ** and * patterns. */
+function minimatch(filePath, pattern) {
+  const regexStr = pattern
+    .replace(/\./g, "\\.")
+    .replace(/\*\*/g, "§§")    // temp placeholder
+    .replace(/\*/g, "[^/]*")
+    .replace(/§§/g, ".*");
+  return new RegExp("^" + regexStr + "$").test(filePath);
+}
+
+/** Walk the directory respecting stored patterns to find all currently included files. */
+function buildMinimalManifest(rootDir, includePatterns, excludePatterns) {
+  const results = [];
+
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(rootDir, fullPath).replace(/\\/g, "/");
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+          walk(fullPath);
+        }
+      } else if (entry.isFile()) {
+        // Same accept SET as the init/add-repo walk (folderSync.walkDir): source +
+        // structural + committed config files. Without the config/structural files
+        // here, a behavioural default edited AFTER onboarding (application.yml,
+        // Dockerfile, ...) would never re-sync. These are gitignore-filtered (and
+        // fail-closed) before upload in deltaSyncOnResume, same as init.
+        const lower = entry.name.toLowerCase();
+        const ext = path.extname(lower);
+        if (
+          SOURCE_EXTENSIONS.has(ext) ||
+          STRUCTURAL_EXTENSIONS.has(ext) ||
+          STRUCTURAL_FILENAMES.has(lower) ||
+          isConfigName(lower)
+        ) {
+          if (!includePatterns || includePatterns.length === 0 ||
+              matchesPatterns(relativePath, includePatterns, excludePatterns)) {
+            results.push(relativePath);
+          }
+        }
+      }
+    }
+  }
+  walk(rootDir);
+  return results;
+}
+
+// handleFileEvent + deltaSyncOnResume are exported for unit testing the
+// gitignore/fail-closed guards without a live server or fs.watch loop.
+module.exports = { watch, startWatch, handleFileEvent, deltaSyncOnResume, handleEntryFailure };

package/src/commands/whoami.js

@@ -0,0 +1,74 @@
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+const color = require("../lib/color");
+
+async function whoami(opts = {}) {
+  if (opts.json) return whoamiJson();
+
+  const creds = credentials.requireCreds();
+  try {
+    const data = await api.get("/api/users/details");
+    const email = data.email || creds.email || "(unknown)";
+    const userId = data.id || creds.userId || "(unknown)";
+    const accountId = data.account_id || data.accountId || "(unknown)";
+    const label = (s) => color.dim(s.padEnd(9));
+    console.log(`${label("Email:")} ${color.bold(email)}`);
+    console.log(`${label("User ID:")} ${userId}`);
+    console.log(`${label("Account:")} ${accountId}`);
+    console.log(`${label("API URL:")} ${color.cyan(creds.apiUrl)}`);
+  } catch (err) {
+    if (err.status === 401) {
+      console.error(color.red("Credentials rejected by server (401).") + ` Run ${color.cyan("niro login")} to refresh.`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Machine-readable identity for agents.
+ * - Unauthed: short-circuit BEFORE requireCreds's throwing path so we can emit
+ *   {authed:false} and exit 0, letting an agent branch instead of crash.
+ * - Authed: emit the identity (server-confirmed where possible) and exit 0.
+ * Never emits tokens or api keys.
+ */
+async function whoamiJson() {
+  const creds = credentials.load();
+  const durable = creds && (creds.cliToken || creds.niroApiKey);
+  if (!creds || (!creds.token && !durable)) {
+    console.log(JSON.stringify({ authed: false }));
+    return;
+  }
+
+  let email = creds.email || null;
+  let userId = creds.userId || null;
+  let accountId = null;
+  try {
+    const data = await api.get("/api/users/details");
+    email = data.email || email;
+    userId = data.id || userId;
+    accountId = data.account_id || data.accountId || null;
+  } catch (err) {
+    // A 401 means the server reached us and REJECTED the credential (revoked/expired/
+    // locked out) — report authed:false even if a durable token is stored locally. A
+    // network error (no err.status) just means offline: fall back to local creds below
+    // and report authed:true so the agent can still proceed.
+    if (err && err.status === 401) {
+      console.log(JSON.stringify({ authed: false }));
+      return;
+    }
+  }
+
+  console.log(
+    JSON.stringify({
+      email,
+      user_id: userId,
+      account_id: accountId,
+      api_url: creds.apiUrl || api.DEFAULT_API_URL,
+      authed: true,
+    })
+  );
+}
+
+module.exports = { whoami };