@tokenoftrust/cli 2.0.12 → 2.0.15

package/src/commands/whoami.mjs

@@ -13,6 +13,7 @@ import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 /**
  * Pure summary of the cached session — no network. Returned for both display and
@@ -73,7 +74,10 @@ export async function run(argv, _ctx) {
       console.log(`  (${g.headline})`);
       console.log(`  → next: ${g.next}`);
     }
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "whoami", operation: "client_list", required: false, degraded: true,
+    }, env);
     console.log("  (couldn't reach the MCP to list your stores right now — your cached session is above)");
   }
   return 0;

package/src/diagnostics.mjs

@@ -0,0 +1,224 @@
+/**
+ * Safe, bounded diagnostics for the standalone CLI. Detailed failures live here;
+ * normal command output carries only a short message and diagnostic id.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const CLI_PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+export const MAX_DIAGNOSTIC_ENTRIES = 200;
+export const MAX_DIAGNOSTIC_BYTES = 256 * 1024;
+export const MAX_DIAGNOSTIC_EXCERPT = 1024;
+
+const SECRET_KEYS = new Set([
+  "authorization", "password", "secret", "apikey", "token", "accesstoken",
+  "refreshtoken", "credential", "cookie", "code", "confirmationcode",
+]);
+const TOKEN_VALUE = /\b(?:eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}|[A-Za-z0-9_-]{40,})\b/gi;
+const URL_CREDENTIAL = /(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi;
+const QUERY_SECRET = /([?&](?:code|token|secret|api[_-]?key|access[_-]?token|refresh[_-]?token)=)[^&#\s]*/gi;
+const EMAIL_VALUE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const PAYMENT_CARD_VALUE = /\b(?:\d[ -]*?){13,19}\b/g;
+const PHONE_VALUE = /(?<!\w)\+?\d{1,3}[\s.-]*(?:\(\d{2,4}\)|\d{2,4})[\s.-]*\d{3,4}[\s.-]*\d{4}(?!\w)/g;
+const PRIVATE_KEY_VALUE = /-----BEGIN [^-\r\n]*PRIVATE KEY-----[\s\S]*?-----END [^-\r\n]*PRIVATE KEY-----/gi;
+const CORRELATION_KEYS = new Set(["diagnosticid", "traceid", "requestid"]);
+const STRUCTURED_CORRELATION_ID = /^(?:[0-9a-f]{16,64}|[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}|(?:req(?:uest)?|trace|diag)[-_:][A-Za-z0-9._:-]{1,120})$/i;
+
+let invocationDiagnostics = [];
+let invocationContext = {};
+
+export function diagnosticsLogPath(env = process.env) {
+  return join(env.TOT_HOME || homedir(), ".tot", "diagnostics.log");
+}
+
+export function sanitizeDiagnosticText(value, maxLength = MAX_DIAGNOSTIC_EXCERPT) {
+  return String(value ?? "")
+    .replace(URL_CREDENTIAL, "$1«redacted»@")
+    .replace(QUERY_SECRET, "$1«redacted»")
+    .replace(/\b(Bearer|Basic)\s+\S+/gi, "$1 «redacted»")
+    .replace(PRIVATE_KEY_VALUE, "«redacted-private-key»")
+    .replace(EMAIL_VALUE, "«redacted-email»")
+    .replace(PAYMENT_CARD_VALUE, "«redacted-card»")
+    .replace(PHONE_VALUE, "«redacted-phone»")
+    .replace(TOKEN_VALUE, "«redacted»")
+    .slice(0, maxLength);
+}
+
+function safeObject(value, depth = 0, key = "") {
+  if (depth > 5) return "[depth-limit]";
+  if (value == null || typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") {
+    const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (CORRELATION_KEYS.has(normalizedKey) && STRUCTURED_CORRELATION_ID.test(value)) return value;
+    return sanitizeDiagnosticText(value);
+  }
+  if (Array.isArray(value)) return value.slice(0, 20).map((item) => safeObject(item, depth + 1));
+  if (typeof value !== "object") return sanitizeDiagnosticText(value);
+  const out = {};
+  for (const [key, item] of Object.entries(value).slice(0, 30)) {
+    const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    out[key] = SECRET_KEYS.has(normalizedKey) ? "[REDACTED]" : safeObject(item, depth + 1, key);
+  }
+  return out;
+}
+
+function causeClasses(error) {
+  const classes = [];
+  const seen = new Set();
+  let current = error;
+  while (current && typeof current === "object" && classes.length < 6 && !seen.has(current)) {
+    seen.add(current);
+    classes.push(String(current.name || current.constructor?.name || "Error").slice(0, 80));
+    current = current.cause;
+  }
+  return classes;
+}
+
+function diagnosticSource(error) {
+  const seen = new Set();
+  let current = error;
+  while (current && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    if (current.diagnostic && typeof current.diagnostic === "object") return current.diagnostic;
+    current = current.cause;
+  }
+  return {};
+}
+
+function parsedLines(path) {
+  try {
+    return readFileSync(path, "utf8").split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function atomicWrite(path, lines) {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, lines.length ? `${lines.join("\n")}\n` : "", { mode: 0o600 });
+  renameSync(tmp, path);
+  chmodSync(path, 0o600);
+}
+
+function persist(record, env) {
+  const path = diagnosticsLogPath(env);
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const line = JSON.stringify(record);
+  let lines = parsedLines(path);
+  lines.push(line);
+  lines = lines.slice(-MAX_DIAGNOSTIC_ENTRIES);
+  const rendered = `${lines.join("\n")}\n`;
+  if (Buffer.byteLength(rendered) > MAX_DIAGNOSTIC_BYTES) {
+    const prior = parsedLines(path);
+    if (prior.length) atomicWrite(`${path}.1`, prior.slice(-MAX_DIAGNOSTIC_ENTRIES));
+    lines = [line];
+  }
+  atomicWrite(path, lines);
+}
+
+export class CliDiagnosticError extends Error {
+  constructor(message, diagnostic = {}, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "CliDiagnosticError";
+    this.diagnostic = safeObject(diagnostic);
+  }
+}
+
+export function recordDiagnostic(error, context = {}, env = process.env) {
+  if (error && typeof error === "object" && error.diagnosticRecord) {
+    return error.diagnosticRecord;
+  }
+  context = { ...invocationContext, ...context };
+  const source = diagnosticSource(error);
+  const record = safeObject({
+    diagnosticId: source.diagnosticId || randomUUID(),
+    timestamp: source.timestamp || new Date().toISOString(),
+    cliVersion: context.cliVersion || CLI_PACKAGE_VERSION,
+    packages: context.packages || { cli: context.cliVersion || CLI_PACKAGE_VERSION },
+    command: context.command,
+    operation: source.operation || context.operation,
+    category: source.category || context.category || "unexpected",
+    httpStatus: source.httpStatus,
+    statusText: source.statusText,
+    serverCode: source.serverCode,
+    message: source.message || (error && typeof error === "object" ? error.message : error),
+    traceId: source.traceId,
+    requestId: source.requestId,
+    contentType: source.contentType,
+    responseBytes: source.responseBytes,
+    responseExcerpt: source.responseExcerpt,
+    causeClasses: causeClasses(error),
+    required: context.required ?? source.required ?? true,
+    degraded: context.degraded ?? source.degraded ?? false,
+  });
+  try {
+    persist(record, env);
+  } catch {
+    // Diagnostics must never replace the original result.
+  }
+  invocationDiagnostics.push(record);
+  if (error && typeof error === "object") {
+    try {
+      error.diagnosticId = record.diagnosticId;
+      error.diagnosticRecord = record;
+    } catch {
+      // Frozen/foreign errors still retain the record in the invocation registry.
+    }
+  }
+  return record;
+}
+
+export function readDiagnostics(env = process.env, { limit = 40 } = {}) {
+  const path = diagnosticsLogPath(env);
+  const lines = [...parsedLines(`${path}.1`), ...parsedLines(path)].slice(-limit);
+  return lines.flatMap((line) => {
+    try {
+      return [JSON.parse(line)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function formatDiagnostics(records) {
+  return records.map((record) => JSON.stringify(record)).join("\n");
+}
+
+export function diagnosticReference(record, env = process.env) {
+  return record?.diagnosticId
+    ? `diagnostic ${record.diagnosticId} (${diagnosticsLogPath(env)})`
+    : null;
+}
+
+export function resetInvocationDiagnostics(context = {}) {
+  invocationDiagnostics = [];
+  invocationContext = { ...context };
+}
+
+export function currentInvocationDiagnostics() {
+  return [...invocationDiagnostics];
+}
+
+export function hasRequiredInvocationDiagnostic() {
+  return invocationDiagnostics.some((entry) => entry.required && !entry.degraded);
+}
+
+export function invocationDegradedResult() {
+  const degraded = invocationDiagnostics.filter((record) => record.degraded);
+  return degraded.length
+    ? { degraded: true, diagnosticId: degraded.at(-1).diagnosticId }
+    : {};
+}

package/src/errors.mjs

@@ -14,6 +14,7 @@
  * can't cycle back here.
  */
 import { versionStamp } from "./mcp.mjs";
+import { diagnosticReference, recordDiagnostic } from "./diagnostics.mjs";
 
 /**
  * The version/OS context appended to every failure's stderr — so a bug report
@@ -67,7 +68,11 @@ export function fail(what, next) {
  * @returns {string}
  */
 export function formatError(err) {
-  return formatErrorBody(err) + versionFooter();
+  const record = recordDiagnostic(err, {
+    required: true,
+  });
+  const ref = diagnosticReference(record);
+  return formatErrorBody(err) + (ref ? `\n  → ${ref}` : "") + versionFooter();
 }
 
 /** The house-style failure line(s), WITHOUT the trailing version/OS footer. */

package/src/mcp.mjs

@@ -8,7 +8,66 @@
  * `Mcp-Session-Id` header across calls. Dependency-free (global fetch, Node 20+).
  */
 import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
+import { CliDiagnosticError, recordDiagnostic, sanitizeDiagnosticText } from "./diagnostics.mjs";
+
+const TRACE_HEADER = "X-Trace-Id";
+const REQUEST_ID_HEADERS = ["x-request-id", "x-amzn-trace-id", "x-correlation-id"];
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+
+function responseRequestId(headers) {
+  for (const name of REQUEST_ID_HEADERS) {
+    const value = headers.get(name);
+    if (value) return value;
+  }
+  return null;
+}
+
+function parseResponseText(text, contentType) {
+  if (!text) return null;
+  if (contentType.includes("text/event-stream")) {
+    const frames = text
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trim())
+      .filter(Boolean);
+    if (!frames.length) throw new SyntaxError("SSE response contained no data frame");
+    return JSON.parse(frames[frames.length - 1]);
+  }
+  return JSON.parse(text);
+}
+
+function safeServerFailure(parsed) {
+  const raw = parsed && typeof parsed === "object" ? parsed.error : null;
+  if (raw && typeof raw === "object") {
+    return {
+      serverCode: typeof raw.code === "string" || typeof raw.code === "number" ? raw.code : undefined,
+      message: typeof raw.message === "string" ? raw.message : undefined,
+      requestId: typeof raw.requestId === "string" ? raw.requestId : undefined,
+    };
+  }
+  if (typeof raw === "string") {
+    return {
+      serverCode: raw,
+      message: typeof parsed?.error_description === "string"
+        ? parsed.error_description
+        : typeof parsed?.message === "string" ? parsed.message : raw,
+    };
+  }
+  if (parsed && typeof parsed === "object") {
+    return {
+      serverCode: typeof parsed.code === "string" || typeof parsed.code === "number" ? parsed.code : undefined,
+      message: typeof parsed.message === "string" ? parsed.message : undefined,
+      requestId: typeof parsed.requestId === "string" ? parsed.requestId : undefined,
+    };
+  }
+  return {};
+}
+
+function diagnosticError(message, details, cause) {
+  return new CliDiagnosticError(message, details, { cause });
+}
 
 // The CLI's REAL version for the MCP handshake — the transmission channel the
 // server-side support policy (update-awareness Layer 2) decides against. Read from
@@ -83,13 +142,15 @@ export function versionStamp(mode) {
 
 /**
  * @param {string} baseUrl - MCP base URL; `/mcp` is appended if absent.
- * @param {{ token?: string, clientVersion?: string }} [opts] - optional developer OAuth
- *   bearer to attach; `clientVersion` overrides the handshake version (tests).
+ * @param {{ token?: string, clientVersion?: string, timeoutMs?: number, exactUrl?: boolean }} [opts]
+ *   optional developer OAuth bearer to attach; `clientVersion` overrides the handshake version
+ *   (tests), `timeoutMs` bounds each request, and `exactUrl` preserves a non-default MCP resource
+ *   path such as `/workstreams`.
  * @returns a small client: { mcpUrl, initialize, callRaw, callTool, sessionId(), setToken }
  */
 export function createMcpClient(baseUrl, opts = {}) {
   const trimmed = String(baseUrl).replace(/\/+$/, "");
-  const mcpUrl = trimmed.endsWith("/mcp") ? trimmed : `${trimmed}/mcp`;
+  const mcpUrl = opts.exactUrl ? trimmed : trimmed.endsWith("/mcp") ? trimmed : `${trimmed}/mcp`;
   let rpcId = 0;
   let sessionId = null;
   // The developer OAuth bearer (set at login-resolve time via setToken, or up
@@ -102,44 +163,122 @@ export function createMcpClient(baseUrl, opts = {}) {
     bearer = token || null;
   }
 
-  async function callRaw(method, params) {
+  async function callRawWithContext(method, params) {
+    const traceId = randomUUID().replaceAll('-', '');
     const envelope = { jsonrpc: "2.0", id: ++rpcId, method, params };
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json, text/event-stream",
+      [TRACE_HEADER]: traceId,
     };
     if (bearer) headers.Authorization = `Bearer ${bearer}`;
     if (sessionId) headers["Mcp-Session-Id"] = sessionId;
 
-    const res = await fetch(mcpUrl, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(envelope),
-    });
+    const timeoutMs = opts.timeoutMs || DEFAULT_REQUEST_TIMEOUT_MS;
+    const signal = AbortSignal.timeout(timeoutMs);
+    let res;
+    try {
+      res = await fetch(mcpUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(envelope),
+        signal,
+      });
+    } catch (cause) {
+      const category = signal.aborted ? "timeout" : "network";
+      const message = signal.aborted
+        ? `${method} timed out after ${timeoutMs}ms`
+        : `${method} failed before a response arrived: ${sanitizeDiagnosticText(cause?.message || cause, 300)}`;
+      throw diagnosticError(message, { operation: method, category, message, traceId }, cause);
+    }
     const sid = res.headers.get("Mcp-Session-Id");
     if (sid) sessionId = sid;
 
     const ct = res.headers.get("content-type") || "";
-    const text = await res.text();
-    if (!res.ok && !text) {
-      throw new Error(`${method} failed: HTTP ${res.status} ${res.statusText}`);
+    const responseTraceId = res.headers.get("x-trace-id") || traceId;
+    const headerRequestId = responseRequestId(res.headers);
+    let text;
+    try {
+      text = await res.text();
+    } catch (cause) {
+      throw diagnosticError(`${method} failed: response body was unreadable`, {
+        operation: method, category: "malformed_response", httpStatus: res.status,
+        statusText: res.statusText, traceId: responseTraceId, requestId: headerRequestId,
+        contentType: ct,
+      }, cause);
     }
+    const responseBytes = Buffer.byteLength(text);
 
     let parsed;
-    if (ct.includes("text/event-stream")) {
-      const lines = text
-        .split(/\r?\n/)
-        .filter((l) => l.startsWith("data:"))
-        .map((l) => l.slice(5).trim())
-        .filter(Boolean);
-      parsed = lines.length ? JSON.parse(lines[lines.length - 1]) : null;
-    } else {
-      parsed = text ? JSON.parse(text) : null;
+    try {
+      parsed = parseResponseText(text, ct);
+    } catch (cause) {
+      if (res.ok) {
+        throw diagnosticError(`${method} failed: malformed MCP response`, {
+          operation: method, category: "malformed_response", httpStatus: res.status,
+          statusText: res.statusText, traceId: responseTraceId, requestId: headerRequestId,
+          contentType: ct, responseBytes,
+        }, cause);
+      }
+      parsed = null;
+    }
+
+    if (!res.ok) {
+      const failure = safeServerFailure(parsed);
+      const oauth = typeof parsed?.error === "string" && typeof parsed?.error_description === "string";
+      const category = oauth ? "oauth" : res.status === 413 ? "http_413" : `http_${res.status}`;
+      const message = sanitizeDiagnosticText(
+        failure.message || parsed?.error_description || `${res.status} ${res.statusText}`,
+        300,
+      );
+      throw diagnosticError(`${method} failed: HTTP ${res.status}${message ? ` — ${message}` : ""}`, {
+        operation: method, category, httpStatus: res.status, statusText: res.statusText,
+        serverCode: failure.serverCode, message, traceId: responseTraceId,
+        requestId: failure.requestId || headerRequestId, contentType: ct, responseBytes,
+      });
+    }
+
+    if (parsed === null) {
+      throw diagnosticError(`${method} failed: empty MCP response`, {
+        operation: method, category: "empty_response", httpStatus: res.status,
+        statusText: res.statusText, message: "MCP returned an empty success response",
+        traceId: responseTraceId, requestId: headerRequestId,
+        contentType: ct, responseBytes,
+      });
     }
+
     if (parsed?.error) {
-      throw new Error(`${method} failed: ${JSON.stringify(parsed.error)}`);
+      const failure = safeServerFailure(parsed);
+      const message = sanitizeDiagnosticText(failure.message || "JSON-RPC error", 300);
+      throw diagnosticError(`${method} failed: ${message}`, {
+        operation: method, category: "json_rpc", httpStatus: res.status,
+        statusText: res.statusText, serverCode: failure.serverCode, message,
+        traceId: responseTraceId, requestId: failure.requestId || headerRequestId,
+        contentType: ct, responseBytes,
+      });
+    }
+    if (!parsed || typeof parsed !== "object" || !Object.hasOwn(parsed, "result")) {
+      throw diagnosticError(`${method} failed: MCP response contained no result`, {
+        operation: method, category: "malformed_response", httpStatus: res.status,
+        statusText: res.statusText, message: "MCP response contained neither result nor error",
+        traceId: responseTraceId, requestId: headerRequestId,
+        contentType: ct, responseBytes,
+      });
     }
-    return parsed?.result;
+    return {
+      result: parsed.result,
+      context: {
+        traceId: responseTraceId,
+        requestId: headerRequestId,
+        contentType: ct,
+        responseBytes,
+        httpStatus: res.status,
+      },
+    };
+  }
+
+  async function callRaw(method, params) {
+    return (await callRawWithContext(method, params)).result;
   }
 
   /**
@@ -149,7 +288,41 @@ export function createMcpClient(baseUrl, opts = {}) {
    * @returns {Promise<any>}
    */
   async function callTool(name, args) {
-    const r = await callRaw("tools/call", { name, arguments: args });
+    let r;
+    let responseContext = {};
+    try {
+      const response = await callRawWithContext("tools/call", { name, arguments: args });
+      r = response.result;
+      responseContext = response.context;
+    } catch (error) {
+      if (error?.diagnostic) error.diagnostic.operation = name;
+      throw error;
+    }
+    if (r?.isError) {
+      const tb = Array.isArray(r?.content)
+        ? r.content.find((c) => c?.type === "text")
+        : null;
+      let payload = null;
+      try {
+        payload = tb?.text ? JSON.parse(tb.text) : null;
+      } catch {
+        payload = null;
+      }
+      const message = sanitizeDiagnosticText(
+        payload?.message || payload?.error?.message || tb?.text || `${name} failed`,
+        300,
+      );
+      throw diagnosticError(`${name} failed: ${message}`, {
+        operation: name, category: "tool_error",
+        serverCode: payload?.code || payload?.error?.code,
+        message,
+        traceId: payload?.traceId || responseContext.traceId,
+        requestId: payload?.requestId || responseContext.requestId,
+        contentType: responseContext.contentType,
+        responseBytes: responseContext.responseBytes,
+        httpStatus: responseContext.httpStatus,
+      });
+    }
     if (r?.structuredContent) return r.structuredContent;
     const tb = Array.isArray(r?.content)
       ? r.content.find((c) => c?.type === "text")
@@ -157,11 +330,19 @@ export function createMcpClient(baseUrl, opts = {}) {
     if (tb?.text) {
       try {
         return JSON.parse(tb.text);
-      } catch {
-        return { raw: tb.text };
+      } catch (cause) {
+        throw diagnosticError(`${name} failed: tool result contained malformed JSON`, {
+          operation: name, category: "malformed_response",
+          message: "MCP tool text result was not valid JSON",
+          ...responseContext,
+        }, cause);
       }
     }
-    return r;
+    if (r && typeof r === "object") return r;
+    throw diagnosticError(`${name} failed: tool result was empty`, {
+      operation: name, category: "empty_response", message: "MCP tool returned no result",
+      ...responseContext,
+    });
   }
 
   /** Complete the MCP handshake. Call once before any tool call. */
@@ -182,7 +363,11 @@ export function createMcpClient(baseUrl, opts = {}) {
       clientInfo,
     });
     // Best-effort — some servers don't require the notification.
-    await callRaw("notifications/initialized", undefined).catch(() => {});
+    await callRaw("notifications/initialized", undefined).catch((error) => {
+      recordDiagnostic(error, {
+        operation: "notifications/initialized", required: false, degraded: true,
+      });
+    });
   }
 
   return { mcpUrl, initialize, callRaw, callTool, sessionId: () => sessionId, setToken };