@tokenoftrust/cli 1.4.0-rc.17 → 1.4.0-rc.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.17",
+  "version": "1.4.0-rc.18",
   "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/submit.mjs

@@ -818,6 +818,7 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     shipped: status?.shipped ?? null,
     dispatched: status?.dispatched ?? null,
     notDispatched: status?.notDispatched ?? false,
+    forwardFailed: status?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
     previewPrUrl,
     ...(error ? { error } : {}),
@@ -1008,7 +1009,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       if (out.trim()) console.error(redactUrl(out.trim()));
     } catch (pushErr) {
       const msg = `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`;
-      console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
+      // This is the NO-SESSION path pushing the clone-time embedded credential —
+      // which rotation kills the moment any fresh mint happens elsewhere. An auth
+      // failure here is therefore almost always "you're not signed in IN THIS
+      // SHELL", not a network problem; the old remote-is-reachable hint sent a
+      // human down the wrong path live (Trello-13075 polish).
+      const hint = isForgeAuthError(pushErr?.stderr || pushErr?.message || pushErr)
+        ? "you're not signed in in this shell, and the checkout's embedded credential has likely been rotated — run `tot login` (check TOT_PROFILE if you use per-terminal identities), then re-run"
+        : "check your commit and that the checkout's remote is reachable, then re-run";
+      console.error(fail(msg, hint));
       emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: msg }));
       return 1;
     }
@@ -1016,7 +1025,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     printChangeSummary(changeSummary, { quiet: args.json });
     const note = e instanceof AuthUnavailableError
       ? `sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"}`
-      : `couldn't reach Token of Trust for the result read-back: ${String(e?.message || e)}`;
+      : `couldn't reach Token of Trust for the result read-back: ${describeReadbackError(e)}`;
     if (!args.json) {
       console.log(`  (${note})`);
       console.log(`  Your push is in; the preview updates once reconcile completes.`);
@@ -1157,14 +1166,14 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     }
     // --json also skips the browser auto-open (open: !args.noOpen && !args.json)
     // — automation doesn't want a browser popping up.
-    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit, ref, verb });
+    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit, ref, verb, noChanges: patchEntries.length === 0 });
     emitJson(args, buildJsonResult({ ok: status?.status !== "failed", ref, commit, changeId, candidate, status, previewPrUrl }));
     return status?.status === "failed" ? 1 : 0;
   } catch (e) {
     progress?.stop();
     const note = e instanceof AuthUnavailableError
       ? `sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"}`
-      : `reconcile is running — the result read-back isn't available yet: ${String(e?.message || e)}`;
+      : `reconcile is running — the result read-back isn't available yet: ${describeReadbackError(e)}`;
     if (!args.json) {
       console.log(`  (${note})`);
       console.log(`  Your push is in; the preview updates once reconcile completes.`);
@@ -1250,6 +1259,19 @@ export async function pollPreviewStatus(
     if (last.dispatched) everDispatched = true;
     last.everDispatched = everDispatched;
     if (onTick) onTick(last, i);
+    // Terminally-failed forward: the delivery record settled with forwarded:false
+    // (and it isn't the at-receipt `pending` marker) — the control plane could not
+    // deliver this commit to the reconciler, and polling longer cannot change that.
+    // Only a NEW push produces a new delivery. Stop and say so (Trello-13075
+    // honesty discipline: never spin on a state that cannot progress).
+    if (
+      last.status === "pending" &&
+      last.delivery?.actual &&
+      last.delivery.actual.forwarded === false &&
+      !last.delivery.actual.pending
+    ) {
+      return { ...last, forwardFailed: true };
+    }
     // Never-dispatched dead-end: still pending, no delivery has EVER been observed
     // for this commit, and we're past the startup grace — the reconcile will never
     // arrive. Return honestly instead of continuing to show "still reconciling".
@@ -1309,6 +1331,34 @@ export function shareablePrUrl(base, tenant, prNumber) {
   return `${String(base).replace(/\/+$/, "")}/preview/${tenant}/pr/${prNumber}`;
 }
 
+/**
+ * Humanize a result-read-back failure. MCP auth errors arrive as a JSON blob
+ * whose `data.self_repair` carries a summary + step list — dumping that raw
+ * into the terminal (observed live: a wall of escaped JSON mid-submit) buries
+ * the one thing the developer needs: sign in again. Detect that shape and
+ * reduce it to the summary's first sentence + the concrete next step; anything
+ * else passes through unchanged. Pure — unit-tested.
+ * @param {unknown} e
+ * @returns {string}
+ */
+export function describeReadbackError(e) {
+  const msg = String(e?.message || e || "");
+  const jsonStart = msg.indexOf("{");
+  if (jsonStart >= 0 && msg.includes("self_repair")) {
+    try {
+      const body = JSON.parse(msg.slice(jsonStart));
+      const repair = body?.data?.self_repair;
+      const summaryFirst = String(repair?.summary || body?.message || "").split(/(?<=\.)\s/)[0];
+      if (summaryFirst) {
+        return `${summaryFirst} Next: run \`tot login\` in this shell (check TOT_PROFILE), then re-run.`;
+      }
+    } catch {
+      // Not the shape we thought — fall through to the raw message.
+    }
+  }
+  return msg;
+}
+
 /**
  * Build the printed lines for the headline "share this with your reviewer" block —
  * the whole point of U14: on a successful preview, the SHAREABLE deep link
@@ -1352,14 +1402,24 @@ export function formatShareableUrlBlock(s, tenant) {
  * @param {string} tenant @param {string} [verb]
  * @returns {string[]}
  */
-export function formatNotDispatchedBlock({ commit = null, ref = null } = {}, tenant, verb = "preview") {
+export function formatNotDispatchedBlock({ commit = null, ref = null, noChanges = false } = {}, tenant, verb = "preview") {
   const short = commit ? commit.slice(0, 9) : "(unknown commit)";
+  // Empty-diff cause FIRST when we know it applies (live-testing finding: an
+  // empty candidate submit structurally CANNOT build — no diff → no candidate PR
+  // → no pull_request webhook — and blaming webhooks/scope for it sent a human
+  // down two wrong debugging paths).
+  const causes = [
+    ...(noChanges
+      ? [`      • your submit contained NO content changes — a candidate with no diff opens no PR and builds nothing (make an edit, or move the shared ref: \`tot ${verb} --ref preview\`),`]
+      : []),
+    `      • the store's reconcile webhook isn't registered yet (an operator must (re-)provision it), or`,
+    `      • your session is scoped to a different store than the one you pushed.`,
+  ];
   return [
     `\n  ⚠ No reconcile was dispatched for ${short} on ${tenant}.`,
     `    Your push landed${ref ? ` on ${ref}` : ""}, but nothing picked it up to build a preview —`,
     `    re-running \`tot ${verb}\` will NOT change that. This usually means one of:`,
-    `      • the store's reconcile webhook isn't registered yet (an operator must (re-)provision it), or`,
-    `      • your session is scoped to a different store than the one you pushed.`,
+    ...causes,
     `    Next:`,
     `      • \`tot grants\` — confirm ${tenant} is active for you;`,
     `      • check the preview dashboard for ${tenant} (it will read "Last reconcile: never" until a job runs);`,
@@ -1367,6 +1427,26 @@ export function formatNotDispatchedBlock({ commit = null, ref = null } = {}, ten
   ];
 }
 
+/**
+ * The honest "the delivery FAILED to forward" block — the delivery record settled
+ * `forwarded: false` (not the at-receipt pending marker), so the control plane
+ * could not deliver this commit to the reconciler; polling longer cannot change
+ * that, and ONLY a new push produces a new delivery. Distinct from
+ * `formatNotDispatchedBlock` (nothing was ever dispatched) — here the plumbing
+ * fired and died in transit, so the recovery differs. Pure — unit-tested.
+ * @param {{ commit?: string|null }} ctx @param {string} tenant
+ * @returns {string[]}
+ */
+export function formatForwardFailedBlock({ commit = null } = {}, tenant) {
+  const short = commit ? commit.slice(0, 9) : "(unknown commit)";
+  return [
+    `\n  ⚠ The reconcile delivery for ${short} on ${tenant} FAILED in transit (network/timeout at the control plane).`,
+    `    Waiting longer will not help — only a NEW push produces a new delivery.`,
+    `    Next: commit again (an empty commit works: git commit --allow-empty -m retry) and re-push;`,
+    `    if it fails the same way twice, share this with support: commit ${short}, tenant ${tenant}.`,
+  ];
+}
+
 /**
  * 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`
@@ -1375,7 +1455,7 @@ export function formatNotDispatchedBlock({ commit = null, ref = null } = {}, ten
  * --json — automation doesn't want a browser popping up). `commit`/`ref`/`verb`
  * feed the honest never-dispatched block.
  */
-function reportStatus(s, tenant, { open = true, quiet = false, commit = null, ref = null, verb = "preview" } = {}) {
+function reportStatus(s, tenant, { open = true, quiet = false, commit = null, ref = null, verb = "preview", noChanges = false } = {}) {
   if (!s || s.status === "unknown") {
     if (!quiet) {
       console.log(
@@ -1385,9 +1465,16 @@ function reportStatus(s, tenant, { open = true, quiet = false, commit = null, re
     }
     return;
   }
+  // Terminally-failed forward — the delivery fired and died in transit; a re-push
+  // (new delivery) is the only recovery. Checked BEFORE notDispatched: a settled
+  // failed forward IS a dispatch, just a doomed one.
+  if (s.forwardFailed) {
+    if (!quiet) for (const line of formatForwardFailedBlock({ commit }, tenant)) console.log(line);
+    return;
+  }
   // Never-dispatched dead-end — the honest replacement for false "still reconciling".
   if (s.notDispatched) {
-    if (!quiet) for (const line of formatNotDispatchedBlock({ commit, ref }, tenant, verb)) console.log(line);
+    if (!quiet) for (const line of formatNotDispatchedBlock({ commit, ref, noChanges }, tenant, verb)) console.log(line);
     return;
   }
   if (s.status === "pending") {