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

package/src/commands/ship.mjs

@@ -47,6 +47,7 @@ import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
+import { emitActivity } from "../activity.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -414,7 +415,25 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const shipData = await readJsonSafe(shipRes);
   progress?.stop();
 
-  return reportShipResult(normalizeShipResult(shipData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const shipResult = normalizeShipResult(shipData);
+  // D3: emit the ship publish lifecycle event — `tot ship` does no LOCAL git op
+  // (it's HTTP-orchestrated), so this marks the outcome of the publish step
+  // itself, distinct from the outer command's invoked/result pair. Fire-and-
+  // forget best-effort: a silent no-op without a hosted-bridge credential, never
+  // awaited, never throws, never alters the ship. `errorClass` stays low-
+  // cardinality (the orchestrator's own terminal state/reason, never free text).
+  const shipped = shipResult.state === "shipped";
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: {
+      status: shipped ? "succeeded" : "failed",
+      ...(shipped ? {} : { errorClass: `ship_${shipResult.state}` }),
+    },
+    scope: { tenantId: tenant },
+    payload: { args: { command: "ship", subcommand: "ship.publish" } },
+  });
+
+  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
 }
 
 /**

package/src/commands/submit.mjs

@@ -50,6 +50,7 @@ import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
+import { emitActivity } from "../activity.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -81,6 +82,23 @@ export function candidateRefFor(changeId) {
   return `${CANDIDATE_REF_PREFIX}${changeId}`;
 }
 
+/**
+ * D3: emit a git-op lifecycle event for `tot submit`/`tot preview` — one per git
+ * operation (commit / push), carrying its own success/failure, so the timeline sees
+ * the individual git steps, not just the outer command's invoked/result pair. Uses
+ * the `cli.command.result` catalog key with a `git.<op>` subcommand (a fixed, safe
+ * value). Fire-and-forget best-effort: a silent no-op without a hosted-bridge
+ * credential, never awaited, never throws, never alters the command. `errorClass` is
+ * a low-cardinality class (never a raw git stderr, which can carry a token/path).
+ */
+function emitGitOp(op, ok, { command = "submit", durationMs, errorClass } = {}) {
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: { status: ok ? "succeeded" : "failed", ...(durationMs != null ? { durationMs } : {}), ...(errorClass ? { errorClass } : {}) },
+    payload: { args: { command, subcommand: `git.${op}`, ...(durationMs != null ? { durationMs } : {}) } },
+  });
+}
+
 export function parseArgs(argv) {
   // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
   // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
@@ -818,6 +836,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 } : {}),
@@ -889,11 +908,13 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     auto = autoCommitKnownTrees(git, { message: args.message, noCommit: args.noCommit });
   } catch (e) {
+    emitGitOp("commit", false, { command: verb, errorClass: "git_commit_failed" });
     const msg = `auto-commit failed: ${String(e?.stderr || e?.message || e)}`;
     console.error(fail(msg, "commit your content manually (git add / git commit), or re-run with --no-commit"));
     emitJson(args, buildJsonResult({ ok: false, error: msg }));
     return 1;
   }
+  if (auto.committed) emitGitOp("commit", true, { command: verb });
   if (auto.refused) {
     console.error(
       fail(
@@ -1006,9 +1027,22 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     try {
       const out = git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
       if (out.trim()) console.error(redactUrl(out.trim()));
+      emitGitOp("push", true, { command: verb });
     } catch (pushErr) {
+      emitGitOp("push", false, {
+        command: verb,
+        errorClass: isForgeAuthError(pushErr?.stderr || pushErr?.message || pushErr) ? "forge_auth" : "git_push_failed",
+      });
       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 +1050,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.`);
@@ -1057,7 +1091,12 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   try {
     const { out } = await pushPreviewRef(git, mintRemote, { ref });
     if (out && out.trim()) console.error(redactUrl(out.trim()));
+    emitGitOp("push", true, { command: verb });
   } catch (e) {
+    emitGitOp("push", false, {
+      command: verb,
+      errorClass: isForgeAuthError(e?.stderr || e?.message || e) ? "forge_auth" : "git_push_failed",
+    });
     const msg = `push failed: ${redactUrl(String(e.stderr || e.message || e))}`;
     console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
     emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: msg }));
@@ -1157,14 +1196,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 +1289,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 +1361,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 +1432,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 +1457,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 +1485,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 +1495,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") {

package/src/no-gitea-links.test.mjs

@@ -0,0 +1,55 @@
+// Regression guard: the `tot` CLI must never print/reference a raw Gitea
+// forge URL to a developer's terminal. Gitea's API returns `html_url` when a
+// PR is opened (e.g. `https://git.tokenoftrust.com/storefront/<repo>/pulls/<n>`)
+// -- the CLI must surface the storefront-owned `/preview/<tenant>/pr/<n>` link
+// instead (see apps/storefront's matching noGiteaLinks.test.ts and its header
+// for the full architecture reasoning: apps/CLI never expose the forge
+// directly, the MCP proxies every read/write). Precipitating incident
+// (2026-08-18): a raw git.tokenoftrust.com PR URL reached an owner reviewing
+// tokenoftrust.com. Test fixtures are exempt (they legitimately mock a Gitea
+// URL to test the forge client), everything else in `src` must stay clean.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+const SELF = fileURLToPath(import.meta.url);
+const SRC_ROOT = dirname(SELF);
+
+const TEST_FILE_RE = /\.test\.[cm]?js$/;
+const FORGE_HOST_RE = /\bgit\.tokenoftrust\.com\b/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (/\.[cm]?js$/.test(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+test("no Gitea forge links in the CLI source outside test fixtures", () => {
+  const offenders = [];
+  for (const file of walk(SRC_ROOT)) {
+    if (TEST_FILE_RE.test(file)) continue;
+    if (file === SELF) continue;
+    const content = readFileSync(file, "utf8");
+    content.split("\n").forEach((line, i) => {
+      if (FORGE_HOST_RE.test(line)) {
+        offenders.push(`${relative(SRC_ROOT, file)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `Found Gitea forge links in non-test CLI source:\n${offenders.join("\n")}`,
+  );
+});