@tokenoftrust/cli 2.0.11 → 2.0.14

package/bin/tot.mjs

@@ -21,6 +21,12 @@ import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
 import { emitActivity, capRendered } from "../src/activity.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
+import {
+  currentInvocationDiagnostics,
+  hasRequiredInvocationDiagnostic,
+  recordDiagnostic,
+  resetInvocationDiagnostics,
+} from "../src/diagnostics.mjs";
 
 const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
 
@@ -305,6 +311,7 @@ async function main() {
   const ctx = detectContext();
   const startedAt = Date.now();
   const command = cmd || "(none)";
+  resetInvocationDiagnostics({ command, cliVersion: VERSION });
   const subcommand = safeSubcommand(cmd, rest);
   let code = 0;
   let errMsg = null;
@@ -323,10 +330,18 @@ async function main() {
     return code;
   } catch (e) {
     errMsg = e?.message || String(e);
+    recordDiagnostic(e, { command, operation: command, cliVersion: VERSION, required: true });
     throw e;
   } finally {
-    const exitCode = errMsg ? 1 : (code ?? 0);
+    const exitCode = errMsg ? 1 : (Number.isInteger(code) ? code : 0);
     const durationMs = Date.now() - startedAt;
+    if (exitCode !== 0 && !hasRequiredInvocationDiagnostic()) {
+      recordDiagnostic(new Error(errMsg || `command exited ${exitCode}`), {
+        command, operation: command, category: "handled_exit", required: true,
+      });
+    }
+    const diagnostics = currentInvocationDiagnostics();
+    const diagnosticIds = diagnostics.map((entry) => entry.diagnosticId).filter(Boolean);
     // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
     // free-text message is omitted — it's user-typed and belongs only in the report.
     recordActivity({
@@ -337,6 +352,7 @@ async function main() {
       code: exitCode,
       ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
+      ...(diagnosticIds.length ? { diagnosticId: diagnosticIds.at(-1), diagnosticIds } : {}),
     });
     // Emit `cli.command.result` (exit code + duration + a bounded/redacted
     // rendered field). The house-style error text is capped + run through the JS
@@ -347,9 +363,12 @@ async function main() {
     // when there's no credential.
     const resultEmit = emitActivity({
       action: "cli.command.result",
-      outcome: { status: errMsg ? "failed" : "succeeded", durationMs },
+      outcome: { status: exitCode === 0 ? "succeeded" : "failed", durationMs },
       payload: {
-        args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, exitCode, durationMs },
+        args: {
+          command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION,
+          exitCode, durationMs, ...(diagnosticIds.length ? { diagnosticId: diagnosticIds.at(-1) } : {}),
+        },
         ...(errMsg ? { rendered: { output: capRendered(errMsg) } } : {}),
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.11",
+  "version": "2.0.14",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/activity-log.mjs

@@ -4,7 +4,8 @@
  * (sent through the Token of Trust MCP's `feedback_submit` tool).
  *
  * ONE file, `~/.tot/activity.log` (JSON-lines), beside the credential cache. Each
- * line is one command invocation: { ts, v, cmd, args, code, ms, err? }. Bounded to
+ * line is one command invocation: { ts, v, cmd, args, code, ms, err?, diagnosticId?,
+ * diagnosticIds? }. Bounded to
  * the most recent MAX_ENTRIES so it never grows without limit.
  *
  * NEVER records secrets: the value after `--code` / `--token` (the single-use

package/src/activity.mjs

@@ -63,7 +63,7 @@ export const CLI_ACTION_CATALOG = {
     renderedAllow: [],
   },
   "cli.command.result": {
-    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs"],
+    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs", "diagnosticId"],
     renderedAllow: [],
   },
   "cli.obstacle.reported": {

package/src/candidate-state.mjs

@@ -3,9 +3,10 @@
  * updates, per forge repo.
  *
  * `tot submit` is idempotent on a STABLE changeId (`deriveChangeId`) so a re-submit
- * updates the same PR by default — the common case needs NO state and writes
- * nothing here (backward-compatible with the stateless original). This file only
- * records a DIVERGENCE from that stable default:
+ * updates the same PR by default. Every chosen identity is persisted before its
+ * ref is pushed, which makes a failed push or MCP registration retry the same ref.
+ * The stored pointer is especially important when the chosen id diverges from the
+ * stable default:
  *
  *   - `tot submit --fork-candidate` forks a fresh candidate and remembers it here, so the
  *     NEXT plain `tot submit` keeps updating the NEW PR (like pushing more commits
@@ -18,14 +19,13 @@
  * candidates): a different MCP, repo, OR non-default git branch is a different
  * candidate namespace, so a feature branch gets its OWN candidate PR instead of
  * fighting main's over the same handle. The default branch deliberately keeps the
- * OLD branch-less key so existing devs' state is byte-identical (zero migration),
- * and a branch-scoped read that misses FALLS BACK to that old key so state written
- * before the rekey (or by the default branch) is never orphaned. Same atomic-write
- * discipline as last-tenant.mjs (0600 in a 0700 dir, write-tmp-then-rename).
+ * branch-less key. Non-default branches never inherit that pointer. Updates hold an
+ * exclusive lock across read-modify-write so concurrent submits cannot lose either
+ * identity. Files use mode 0600 in a 0700 directory.
  * Dependency-free (node:fs/os/path). `TOT_HOME` overrides home (tests).
  */
 import {
-  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync, statSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
@@ -79,45 +79,70 @@ function readMap(filePath) {
 }
 
 function writeMap(filePath, map) {
-  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
-  const tmp = `${filePath}.tmp`;
+  const tmp = `${filePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
   writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
   renameSync(tmp, filePath);
   chmodSync(filePath, 0o600);
 }
 
+const LOCK_RETRY_MS = 10;
+const LOCK_ATTEMPTS = 200;
+const STALE_LOCK_MS = 30_000;
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+
+function updateMap(filePath, mutate) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const lockPath = `${filePath}.lock`;
+  let locked = false;
+  for (let attempt = 0; attempt < LOCK_ATTEMPTS && !locked; attempt += 1) {
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      locked = true;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > STALE_LOCK_MS) rmdirSync(lockPath);
+      } catch (staleError) {
+        if (staleError?.code !== "ENOENT" && staleError?.code !== "ENOTEMPTY") throw staleError;
+      }
+      if (!locked) Atomics.wait(lockWait, 0, 0, LOCK_RETRY_MS);
+    }
+  }
+  if (!locked) throw new Error(`Candidate state is busy: ${lockPath}`);
+  try {
+    const map = readMap(filePath);
+    if (mutate(map)) writeMap(filePath, map);
+  } finally {
+    rmdirSync(lockPath);
+  }
+}
+
 /**
  * The remembered active changeId for `(mcpUrl, repo, branch)`, or null when there
  * isn't one (absent/unreadable/malformed) — a miss means "use the stable default".
- * On a non-default branch whose branch-scoped key misses, FALLS BACK to the legacy
- * branch-less key so state written before the rekey (or by the default branch)
- * isn't orphaned. Never throws.
+ * Non-default branches never read the default branch's pointer. Never throws.
  */
 export function readActiveChangeId(filePath, { mcpUrl, repo, branch }) {
   const map = readMap(filePath);
-  const primary = recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
-  if (primary) return primary;
-  // Legacy fallback: a branch-scoped miss reads the old branch-less key (a no-op
-  // when we're already on the default branch, which IS the legacy key).
-  if (!isDefaultBranch(branch)) return recordChangeId(map[legacyStateKey(mcpUrl, repo)]);
-  return null;
+  return recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
 }
 
 /** Remember `changeId` as the active candidate for `(mcpUrl, repo, branch)`, atomically. */
 export function writeActiveChangeId(filePath, { mcpUrl, repo, branch, changeId }) {
-  const map = readMap(filePath);
-  map[stateKey(mcpUrl, repo, branch)] = { changeId, updatedAt: Date.now() };
-  writeMap(filePath, map);
+  updateMap(filePath, (map) => {
+    map[stateKey(mcpUrl, repo, branch)] = { changeId, updatedAt: Date.now() };
+    return true;
+  });
 }
 
 /** Forget the active candidate for `(mcpUrl, repo, branch)` (e.g. after closing it). */
 export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
-  const map = readMap(filePath);
-  const key = stateKey(mcpUrl, repo, branch);
-  if (key in map) {
+  updateMap(filePath, (map) => {
+    const key = stateKey(mcpUrl, repo, branch);
+    if (!(key in map)) return false;
     delete map[key];
-    writeMap(filePath, map);
-  }
+    return true;
+  });
 }
 
 /**

package/src/commands/clone.mjs

@@ -55,6 +55,7 @@ import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
 import { splitAuthedRemote, basicAuthExtraHeader, installForgeCredentialHelper } from "../git-credential.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -364,6 +365,7 @@ async function cloneRepo(gitRemote, dir, redact) {
     await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
+      cause: e,
     });
   }
   // Install the HOST-SCOPED helper, not a bare `credential.helper`. A bare one is appended to
@@ -376,9 +378,12 @@ async function cloneRepo(gitRemote, dir, redact) {
     const gitSync = (/** @type {string[]} */ cargs) =>
       execFileSync("git", ["-C", dir, ...cargs], { encoding: "utf8" });
     installForgeCredentialHelper(gitSync, { host: new URL(gitRemote).host });
-  } catch {
+  } catch (error) {
     // Best-effort — never fail a good clone over credential plumbing. The next
     // `tot preview`/`tot sync` installs it, and the fetch that needs it says why.
+    recordDiagnostic(error, {
+      command: "clone", operation: "credential_helper_install", required: false, degraded: true,
+    });
   }
   const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
   writeNvmrc(dir); // version-manager hooks land on a supported Node on cd

package/src/commands/dev.mjs

@@ -53,6 +53,7 @@ import {
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { cockpitUrlFrom } from "../banner.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -874,7 +875,10 @@ export function probeRunnerVersion(runnerDir, { timeoutMs = 4000 } = {}) {
     });
     const v = String(out).trim().split(/\s+/)[0];
     return /^\d+\.\d+\.\d+/.test(v) ? v : null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "dev", operation: "runner_version_probe", required: false, degraded: true,
+    });
     return null; // old runner (no --version), timeout, or spawn failure → treat as unversioned
   }
 }
@@ -1323,7 +1327,10 @@ export async function publishedRunnerIntegrity(env, version, { timeoutMs = 2000,
     if (!res.ok) return null;
     const dist = (await res.json())?.versions?.[version]?.dist;
     return dist?.integrity || dist?.shasum || null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "dev", operation: "runner_integrity_probe", required: false, degraded: true,
+    }, env);
     return null;
   }
 }
@@ -1809,6 +1816,9 @@ export async function ensureRegistryLogin(image, args, { client: providedClient
     });
     console.error(`~ registry sign-in ok (${reg})`);
   } catch (e) {
+    recordDiagnostic(e, {
+      command: "dev", operation: "dev_image_pull_token", required: false, degraded: true,
+    });
     console.error(
       `~ (using existing docker login for ${registry} — MCP pull-token not available: ${String(e?.message || e)})`,
     );

package/src/commands/feedback.mjs

@@ -26,6 +26,7 @@ import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { fail } from "../errors.mjs";
+import { formatDiagnostics, readDiagnostics, recordDiagnostic } from "../diagnostics.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const TYPES = new Set(["bug", "feature", "improvement"]);
@@ -57,9 +58,14 @@ Requires a signed-in session — run \`tot login\` first if needed.`;
  * `traceId` link) is unit-testable without driving the MCP handshake. Both extras
  * are OMITTED when their source is absent — never sent as null/empty.
  * @param {{ type: string, category: string, severity: string, title: string,
- *   description: string, activityText?: string|null, traceId?: string|null }} f
+ *   description: string, activityText?: string|null, diagnosticsText?: string|null,
+ *   traceId?: string|null }} f
  */
-export function buildFeedbackPayload({ type, category, severity, title, description, activityText, traceId }) {
+export function buildFeedbackPayload({ type, category, severity, title, description, activityText, diagnosticsText, traceId }) {
+  const attachments = [
+    activityText ? `tot CLI activity (most recent last):\n${activityText}` : null,
+    diagnosticsText ? `tot CLI diagnostics (redacted, most recent last):\n${diagnosticsText}` : null,
+  ].filter(Boolean);
   return {
     type,
     category,
@@ -67,9 +73,9 @@ export function buildFeedbackPayload({ type, category, severity, title, descript
     title,
     description,
     scenario: "tot-cli",
-    // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
-    // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
-    ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
+    // CLI context → `sensitive` (ToT-admins-only, never clustered/shared). It is
+    // redacted before attachment; `sensitive` is the belt-and-suspenders home for it.
+    ...(attachments.length ? { sensitive: attachments.join("\n\n") } : {}),
     // Invite→terminal→problem trace link (omitted when this wasn't an invite login).
     ...(traceId ? { traceId } : {}),
   };
@@ -138,6 +144,8 @@ export async function run(argv) {
 
   const entries = args.activity ? readActivity(env, { limit: 40 }) : [];
   const activityText = entries.length ? formatActivity(entries) : null;
+  const diagnostics = args.activity ? readDiagnostics(env, { limit: 20 }) : [];
+  const diagnosticsText = diagnostics.length ? formatDiagnostics(diagnostics) : null;
   const title = message.length > 80 ? `${message.slice(0, 79)}…` : message;
 
   // The invite→terminal→problem trace id `tot login` cached from the pasted invite
@@ -153,9 +161,9 @@ export async function run(argv) {
   console.error(`  ${args.type} · ${args.category} · ${args.severity}`);
   console.error(`  "${title}"`);
   console.error(
-    activityText
-      ? `  + your last ${entries.length} CLI command(s) — secret-redacted, ToT-admins-only`
-      : "  (no activity log attached)",
+    activityText || diagnosticsText
+      ? `  + ${entries.length} recent command(s) and ${diagnostics.length} diagnostic(s) — redacted, ToT-admins-only`
+      : "  (no activity or diagnostics attached)",
   );
 
   if (!args.yes) {
@@ -192,6 +200,7 @@ export async function run(argv) {
       title,
       description: message,
       activityText,
+      diagnosticsText,
       traceId,
     });
     const res = await client.callTool("feedback_submit", payload);
@@ -199,6 +208,7 @@ export async function run(argv) {
     console.log(`\n+ sent — thank you.${id ? ` (report ${id})` : ""}`);
     return 0;
   } catch (e) {
+    recordDiagnostic(e, { command: "feedback", operation: "feedback_submit", required: true }, env);
     if (e instanceof AuthUnavailableError) {
       console.error(fail(`can't send feedback: ${e.message}`, e.hint || "run `tot login` first."));
       return 1;

package/src/commands/grants.mjs

@@ -29,6 +29,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { storeListError, noStoresGuidance } from "./clone.mjs";
 import { offerSignIn } from "./login.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -169,7 +170,10 @@ async function tryIntrospect(client) {
     const r = await client.callTool("grant_introspect", {});
     if (r && typeof r === "object" && Array.isArray(r.grants)) return r;
     return null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "grants", operation: "grant_introspect", required: false, degraded: true,
+    });
     return null;
   }
 }

package/src/commands/link.mjs

@@ -25,6 +25,7 @@ import { offerSignIn } from "./login.mjs";
 import { openBrowser } from "../open.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { normalizeStores } from "./clone.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -131,6 +132,7 @@ export async function run(argv, _ctx) {
     } catch (e) {
       throw new CliError(`couldn't start the identity link: ${String(e?.message || e)}`, {
         next: "your MCP may not support `tot link` yet — run `tot whoami` for the current guidance",
+        cause: e,
       });
     }
     const { authUrl, pollHandle } = linkBeginFields(begin);
@@ -172,7 +174,10 @@ export async function run(argv, _ctx) {
       } else {
         console.log("  Next: `tot start` — if it still shows no stores, ask your ToT contact for a store invite.");
       }
-    } catch {
+    } catch (error) {
+      recordDiagnostic(error, {
+        command: "link", operation: "client_list", required: false, degraded: true,
+      }, env);
       console.log("  Next: `tot start` to build your store.");
     }
     return 0;
@@ -205,6 +210,9 @@ export async function pollLink(client, pollHandle, { timeoutMs = 120000, interva
       res = await client.callTool("identity_link_poll", { pollHandle });
     } catch (e) {
       // A transient poll error isn't fatal — keep trying until the deadline.
+      recordDiagnostic(e, {
+        command: "link", operation: "identity_link_poll", required: false, degraded: true,
+      });
       await delay(intervalMs);
       continue;
     }