@tokenoftrust/cli 2.0.8 → 2.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "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

@@ -1154,7 +1154,7 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  * Defaults to null when no numeric PR number was known at result-build time.
  * Pure — unit-tested.
  * @param {{ ok: boolean, ref?: string|null, commit?: string|null, changeId?: string|null,
- *   candidate?: {prNumber?: number, number?: number, state?: string, url?: string}|null,
+ *   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,
@@ -1165,6 +1165,10 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     ok,
     ref,
     commit,
+    // The sha the `status`/`reconcile`/`compliance` fields above are reported against —
+    // the candidate head when the candidate names one, else the local `commit`. Kept
+    // beside `commit` rather than replacing it so automation can tell the two apart.
+    candidateHeadSha: candidate ? resolvePreviewStatusSha(commit, candidate) : null,
     changeId,
     candidate: candidate
       ? { number: candidate.prNumber ?? candidate.number ?? null, state: candidate.state ?? null, url: candidate.url ?? null }
@@ -1184,6 +1188,43 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
   };
 }
 
+/**
+ * The sha `preview_status` actually resolves against. The candidate the forge opened
+ * may carry a DIFFERENT head than the commit you pushed (it is rebuilt onto the
+ * current store), and `preview_status` only knows the candidate head — so polling the
+ * local commit returns a misleading `pending` / "no reconcile delivery observed"
+ * instead of the real result. Prefer the candidate head whenever the candidate names
+ * one; fall back to the local commit (no candidate, or an older MCP that omits it).
+ * Pure — unit-tested.
+ * @param {string|null} commit local HEAD sha
+ * @param {{headSha?: string|null}|null} candidate the candidate_open projection
+ */
+export function resolvePreviewStatusSha(commit, candidate) {
+  const head = typeof candidate?.headSha === "string" ? candidate.headSha.trim() : "";
+  return head || commit;
+}
+
+/**
+ * The two-sha notice, printed ONLY when they actually differ (when they match there is
+ * nothing to disambiguate and a second line would be noise). Names which sha the
+ * reconcile result is reported against, so a developer polling by hand — or reading a
+ * failure — knows which one to use. Pure — unit-tested.
+ * @param {string|null} commit local HEAD sha
+ * @param {{headSha?: string|null}|null} candidate the candidate_open projection
+ * @returns {string[]} lines to print (empty when there is no distinction to draw)
+ */
+export function formatCandidateHeadNotice(commit, candidate) {
+  const head = resolvePreviewStatusSha(commit, candidate);
+  if (!commit || !head || head === commit) return [];
+  return [
+    "",
+    `  ▸ local commit:    ${commit.slice(0, 9)}   (what you committed here)`,
+    `    candidate head:  ${head.slice(0, 9)}   (what preview_status reports on)`,
+    "    They differ because your candidate is rebuilt on the current store. Follow the",
+    "    candidate head — the local commit reads as \"never dispatched\", not as the result.",
+  ];
+}
+
 /** Print the `--json` result as one pretty-printed object on stdout — a no-op
  *  unless `args.json` was passed, so call sites can invoke it unconditionally. */
 function emitJson(args, payload) {
@@ -1663,9 +1704,18 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
     }
 
+    // Poll the sha `preview_status` actually resolves against — the candidate head, not
+    // the local commit, whenever the candidate names its own. Printed first (when they
+    // differ) so the developer reads the result against the right sha.
+    const statusSha = resolvePreviewStatusSha(commit, candidate) ?? commit;
+    const statusShort = statusSha.slice(0, 9);
+    if (!args.json) {
+      for (const line of formatCandidateHeadNotice(commit, candidate)) console.log(line);
+    }
+
     let status;
     if (args.noWait) {
-      status = normalizePreviewStatus(await client.callTool("preview_status", { commit }));
+      status = normalizePreviewStatus(await client.callTool("preview_status", { commit: statusSha }));
     } else {
       // One in-place status line (TTY: a spinner with an elapsed-seconds counter;
       // non-TTY: a ~10s heartbeat) instead of a newline per poll — the wait reads
@@ -1681,11 +1731,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       // stage text ("still reconciling…") IS truthful and is left as-is below.
       let phase = "reconcile";
       if (!args.json) {
-        progress = startProgress(`waiting for reconcile of ${short}…`, {
-          stages: [{ afterMs: 45_000, text: `still reconciling ${short}… (larger changes take longer)` }],
+        progress = startProgress(`waiting for reconcile of ${statusShort}…`, {
+          stages: [{ afterMs: 45_000, text: `still reconciling ${statusShort}… (larger changes take longer)` }],
         });
       }
-      status = await pollPreviewStatus(client, commit, {
+      status = await pollPreviewStatus(client, statusSha, {
         ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
         onTick: (s) => {
           // Reconcile is done but we're still waiting on a ship decision (--watch):
@@ -1693,7 +1743,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
           if (!args.json && s.status === "reconciled" && !s.shipped && phase !== "ship") {
             phase = "ship";
             progress.stop();
-            progress = startProgress(`reconciled ${short} — waiting for a ship decision…`);
+            progress = startProgress(`reconciled ${statusShort} — waiting for a ship decision…`);
           }
         },
       });
@@ -1704,7 +1754,9 @@ 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, noChanges: patchEntries.length === 0 });
+    // `commit: statusSha` — the diagnostic blocks name the sha that was actually polled,
+    // so a "never dispatched" hint points at a sha `preview_status` knows about.
+    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit: statusSha, 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) {