@tokenoftrust/cli 2.3.0 → 2.4.0

package/bin/tot.mjs

@@ -61,6 +61,7 @@ const COMMANDS = [
   { invocation: "report go-live --pages <dir>", blurb: "your store's go-live readiness report, from its page-check results" },
   { invocation: "dev", blurb: "run your store locally with save→reload" },
   { invocation: "preview", blurb: "push your store to a reviewable preview" },
+  { invocation: "status", blurb: "the pipeline verdict for your active tenant — progressing / stuck / idle, and why" },
   { invocation: "ship", blurb: "publish the tenant's current green aggregate live (plan → confirm → ship)" },
   { invocation: "accept / tot merge", blurb: "queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)" },
   { invocation: "sync", blurb: "fetch `preview` and merge it into your local branch (accept-conflict recovery)" },
@@ -201,6 +202,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "status") {
+    const { run } = await import("../src/commands/status.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "submit" || cmd === "deploy") {
     const { run } = await import("../src/commands/preview.mjs");
     return run(rest, ctx, { alias: cmd });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "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/commands/status.mjs

@@ -0,0 +1,109 @@
+/**
+ * `tot status` — the pipeline verdict for your active tenant (migration DAG §U4):
+ * the SAME `kind`/`reason`/`nextAction` the Publish console and `tot preview`/`tot
+ * submit` print, available on its own without pushing anything. Reads
+ * `store_status` (tenant/repo-scoped, zero live Gitea calls) and prints its
+ * `verdict` field — pipeline state comes from there, never re-derived here.
+ *
+ * Dependency-free (global fetch via mcp.mjs's client).
+ */
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
+import { resolveRepoAndTenant } from "./branches.mjs";
+import { formatVerdictBlock } from "./submit.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot status — the pipeline verdict for your active tenant
+
+  tot status                 verdict for the current checkout's repo
+  tot status --tenant <d>    verdict for a specific store (e.g. --tenant acme.com)
+  tot status --json          machine-readable output
+
+Options:
+  --tenant <appDomain>   the store to read (default: the current checkout / its remote)
+  --repo <repo>          an explicit repo name, when it differs from --tenant
+  --mcp <url>            override the MCP base URL
+  --json                 print the raw { verdict, ... } payload instead of prose
+`;
+
+/**
+ * @param {string[]} argv
+ * @returns {{ tenant: string|null, repo: string|null, mcp: string|null, json: boolean, help: boolean }}
+ */
+function parseStatusArgs(argv) {
+  const args = /** @type {{ tenant: string|null, repo: string|null, mcp: string|null, json: boolean, help: boolean }} */ ({
+    tenant: null, repo: null, mcp: null, json: false, help: false,
+  });
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--json") args.json = true;
+    else if (a === "--tenant") args.tenant = argv[++i] ?? null;
+    else if (a === "--repo") args.repo = argv[++i] ?? null;
+    else if (a === "--mcp") args.mcp = argv[++i] ?? null;
+  }
+  return args;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseStatusArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const { repo, tenant, error } = resolveRepoAndTenant(args, ctx);
+  if (error) {
+    console.error(error);
+    return 2;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env });
+    const scoped = await scopeToTenant(client, /** @type {string} */ (tenant));
+    const result = await scoped.callTool("store_status", { repo, include: ["branches"] });
+
+    if (result?.status === "error" || result?.status === "invalid_input" || result?.error) {
+      console.error(
+        fail(
+          `couldn't read status for ${repo}: ${result.error || result.message || "unknown error"}`,
+          "check --tenant / --repo, then re-run",
+        ),
+      );
+      return 1;
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify({ verdict: result?.verdict ?? null, tenant: repo }, null, 2));
+      return 0;
+    }
+
+    const verdict = result?.verdict ?? null;
+    if (!verdict) {
+      console.log(`  (no pipeline verdict available for ${repo} right now.)`);
+      return 0;
+    }
+    console.log(`${repo}:`);
+    for (const line of formatVerdictBlock(verdict)) console.log(line);
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to read status", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the status service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}

package/src/commands/submit.mjs

@@ -962,14 +962,28 @@ export function chooseChangeId({ tenant, actorKey, branch = null, active = null,
  * @param {{ repo: string, changeId: string }} opts
  * @returns {Promise<string|null>}
  */
+/**
+ * The FULL candidate_status record for one candidate (changeId/prNumber/branch/headSha/
+ * state/…), tolerant of the same three response shapes `candidateStateFor` tolerates
+ * (a bare candidate, `{candidates:[…]}`, or a plain array). Null when the tool throws or
+ * names no matching candidate — never thrown. Shared by `candidateStateFor` (state only)
+ * and `submitCandidate`'s 502-despite-success recovery (the full record).
+ * @param {{callTool:Function}} scoped the tenant-scoped handle from `scopeToTenant` (or a mock)
+ * @param {{ repo: string, changeId: string }} opts
+ */
+export async function fetchCandidateStatus(scoped, { repo, changeId }) {
+  const r = await scoped.callTool("candidate_status", { repo, changeId });
+  const c = Array.isArray(r)
+    ? r.find((x) => x?.changeId === changeId)
+    : Array.isArray(r?.candidates)
+      ? r.candidates.find((x) => x?.changeId === changeId)
+      : r;
+  return c ?? null;
+}
+
 export async function candidateStateFor(scoped, { repo, changeId }) {
   try {
-    const r = await scoped.callTool("candidate_status", { repo, changeId });
-    const c = Array.isArray(r)
-      ? r.find((x) => x?.changeId === changeId)
-      : Array.isArray(r?.candidates)
-        ? r.candidates.find((x) => x?.changeId === changeId)
-        : r;
+    const c = await fetchCandidateStatus(scoped, { repo, changeId });
     return c && typeof c.state === "string" ? c.state : null;
   } catch (error) {
     recordDiagnostic(error, {
@@ -1086,6 +1100,28 @@ export async function submitCandidate(scoped, { repo, changeId, ref, headSha, ch
     return result;
   } catch (e) {
     if (e instanceof CandidateRegistrationError) throw e;
+    // "502 despite success" (migration DAG §U4): candidate_open's forge write is
+    // idempotent and may have LANDED even though its HTTP response never reached us
+    // (a 5xx between MCP and its own caller, a dropped connection, …). Before reporting
+    // a fatal "candidate not created," re-read it by its stable changeId — if it's
+    // already there with the exact ref/head we just pushed, this submit DID succeed;
+    // report that instead of a false failure. Purely a recovery path: any error from
+    // the re-read (including "not found," which is the ordinary case for a genuine
+    // registration failure) falls through to the original fatal error, unchanged.
+    const httpStatus = /** @type {any} */ (e)?.diagnostic?.httpStatus;
+    if (typeof httpStatus === "number" && httpStatus >= 500) {
+      const existing = await fetchCandidateStatus(scoped, { repo, changeId }).catch(() => null);
+      if (
+        existing
+        && typeof existing.prNumber === "number"
+        && existing.branch === ref
+        && existing.headSha === headSha
+        && !isTerminalCandidateState(existing.state)
+      ) {
+        reportCandidate(existing, changeId, { quiet });
+        return existing;
+      }
+    }
     throw new CandidateRegistrationError(`Candidate not created: ${describeReadbackError(e)}`, e);
   }
 }
@@ -1134,7 +1170,7 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  *   candidate?: {prNumber?: number, number?: number, state?: string, url?: string, headSha?: string|null}|null,
  *   status?: {status?: string, reconcile?: object|null, compliance?: object|null,
  *     previewUrl?: string|null, shipped?: object|null, dispatched?: boolean|null,
- *     notDispatched?: boolean, delivery?: object|null}|null,
+ *     notDispatched?: boolean, delivery?: object|null, verdict?: object|null}|null,
  *   previewPrUrl?: string|null, error?: string|null, note?: string|null, noChanges?: boolean,
  *   degraded?: boolean, diagnosticId?: string|null }} input
  */
@@ -1160,6 +1196,7 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     notDispatched: status?.notDispatched ?? false,
     forwardFailed: /** @type {any} */ (status)?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
+    verdict: status?.verdict ?? null,
     previewPrUrl,
     ...(degraded ? { degraded: true } : {}),
     ...(diagnosticId ? { diagnosticId } : {}),
@@ -1868,6 +1905,10 @@ export function normalizePreviewStatus(r) {
     shipped: r?.shipped ?? null,
     delivery,
     dispatched: delivery != null,
+    // The ONE pipeline-status read every surface (console, `preview_status`, `tot
+    // status`) shares (migration DAG §U4) — null when it could not be read. Printed
+    // alongside the legacy fields above, never replacing them.
+    verdict: r?.verdict ?? null,
     raw: r,
   };
 }
@@ -2122,6 +2163,29 @@ export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
   ];
 }
 
+/**
+ * The pipeline-verdict lines (migration DAG §U4): kind, reason, next action — the SAME
+ * verdict the Publish console and `tot status` print, so a developer never sees a
+ * different story in two places. On `stuck`, also prints the support bundle text when
+ * the caller fetched one (preview_status attaches it only when `contactSupport` is
+ * true). Pure — unit-tested. Returns `[]` when there is nothing to print (no verdict,
+ * or a verdict object that isn't shaped as expected — never throws on a malformed one).
+ * @param {any} verdict @param {string|null} [supportBundleText]
+ * @returns {string[]}
+ */
+export function formatVerdictBlock(verdict, supportBundleText = null) {
+  if (!verdict || typeof verdict !== "object" || typeof verdict.kind !== "string") return [];
+  const lines = [`\n  verdict: ${verdict.kind}${verdict.reason ? ` — ${verdict.reason}` : ""}`];
+  const next = verdict.nextAction;
+  if (next && typeof next.label === "string") {
+    lines.push(`    next: ${next.label}${next.command ? ` (${next.command})` : ""}`);
+  }
+  if (verdict.kind === "stuck" && supportBundleText) {
+    lines.push("", "  — support bundle (share this with support) —", supportBundleText);
+  }
+  return lines;
+}
+
 /**
  * Print the reconcile/compliance/preview result and, on a clean reconcile with a
  * preview URL, open it in the browser (unless opts.open === false). `quiet`
@@ -2135,6 +2199,7 @@ export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
  * @param {{ open?: boolean, quiet?: boolean, commit?: string|null, ref?: string|null, verb?: string, noChanges?: boolean }} [opts]
  */
 function reportStatus(s, tenant, { open = true, quiet = false, commit = null, ref = null, verb = "preview", noChanges = false } = {}) {
+  if (!quiet) for (const line of formatVerdictBlock(s?.verdict, s?.supportBundleText)) console.log(line);
   if (!s || s.status === "unknown") {
     if (!quiet) {
       console.log(

package/src/tenant-scope.mjs

@@ -51,6 +51,7 @@ export const PIN_SCOPED_TOOLS = Object.freeze(new Set([
   "candidate_list",
   "candidate_delete",
   "candidate_refresh",
+  "store_status",
 ]));
 
 /**