@tokenoftrust/cli 2.4.0 → 2.4.1

package/bin/tot.mjs

@@ -219,8 +219,8 @@ async function dispatch(cmd, rest, ctx) {
 
   // `accept` queue-integrates a PR into the protected `preview` aggregate —
   // NO merge-to-main, NO go-live; going live is `tot ship`, which publishes the
-  // whole current GREEN AGGREGATE. Backed by POST /api/changes/integrate
-  // (TenantIntegrationQueue.enqueue); see accept.mjs's header. `merge` is a
+  // whole current GREEN AGGREGATE. Backed by POST /api/changes/integrate (an
+  // `integrate` job in the store's pipeline); see accept.mjs's header. `merge` is a
   // first-class alias, not a teaching nudge: both dispatch straight to the same command.
   if (cmd === "accept" || cmd === "merge") {
     const { run } = await import("../src/commands/accept.mjs");
@@ -245,8 +245,8 @@ async function dispatch(cmd, rest, ctx) {
   // `revert --preview <PR|change-id>` undoes an already-integrated PR out of the
   // protected `preview` aggregate by opening a NEW corrective candidate and
   // merging it through the SAME accept pipeline — NO force-reset, NO touch to
-  // main/live. Backed by POST /api/changes/revert (TenantIntegrationQueue.enqueue,
-  // the same pipeline `tot accept` drives). To undo something already LIVE,
+  // main/live. Backed by POST /api/changes/revert (a `revert` job in the store's
+  // pipeline, the same steps `tot accept` runs). To undo something already LIVE,
   // that's `tot rollback`, not this. See revert.mjs's header.
   if (cmd === "revert") {
     const { run } = await import("../src/commands/revert.mjs");

package/package.json

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

@@ -18,13 +18,13 @@
  * chg-id). An explicit `--change-id` is still accepted (targets a specific record),
  * but is no longer REQUIRED — a PR number alone is enough.
  *
- * TRANSPORT — the honest accept path is `POST /api/changes/integrate` (the ONE call
- * site of `TenantIntegrationQueue.enqueue`). Like `tot ship --pr` and
- * `tot pr list --tenant`, the CLI reaches it with the OPERATOR-SECRET Bearer
- * transport (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`), since the
- * CLI holds no storefront cookie. The response is the honest `IntegrateOutcome` —
- * `queueState` / `runState` / `pointerMoved` / `aggregateSha` / `statusMessage` —
- * which this verb renders VERBATIM, never a bare "merged".
+ * TRANSPORT — the honest accept path is `POST /api/changes/integrate`. Like `tot ship --pr`
+ * and `tot pr list --tenant`, the CLI reaches it with the OPERATOR-SECRET Bearer transport
+ * (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`), since the CLI holds no
+ * storefront cookie. The route submits an `integrate` job to the store's pipeline and answers
+ * `202 {jobId}`; this verb waits on `GET /api/pipeline/jobs/<jobId>` for the job's outcome —
+ * `jobState` / `runState` / `pointerMoved` / `aggregateSha` / `statusMessage` — and renders it
+ * VERBATIM, never a bare "merged". The job runs on the platform whether or not this waits.
  *
  * HUMAN GATE — integrating into the shared preview is a decision a human makes, so
  * this ALWAYS states the EXACT plan (shared `planForAction`: which PR,
@@ -53,6 +53,7 @@ import { resolveViewerTransport } from "../viewer-session.mjs";
 // "here's what's blocking you" summary over the SAME transport we just used, so a
 // developer doesn't have to remember to run `tot preview doctor` themselves.
 import { autoSurfaceDoctor } from "../merge-doctor-report.mjs";
+import { isJobAccepted, waitForPipelineJob } from "../pipeline-job.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -150,7 +151,7 @@ export function parseAcceptArgs(argv) {
  * fields this verb renders. Reads defensively so a plausible field rename degrades
  * rather than crashes. Pure — unit-tested.
  * @param {any} data
- * @returns {{ ok:boolean, queueState:string|null, runState:string|null,
+ * @returns {{ ok:boolean, pending:boolean, jobId:string|null, jobState:string|null, runState:string|null,
  *   pointerMoved:boolean, aggregateSha:string|null, statusMessage:string|null,
  *   reason:string|null, changeId:string|null, prNumber:number|null, error:string|null, raw:any }}
  */
@@ -158,7 +159,9 @@ export function normalizeIntegrateResponse(data) {
   const o = data && typeof data === "object" ? data : {};
   return {
     ok: o.ok === true,
-    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    pending: o.pending === true,
+    jobId: typeof o.jobId === "string" ? o.jobId : null,
+    jobState: typeof o.jobState === "string" ? o.jobState : null,
     runState: typeof o.runState === "string" ? o.runState : null,
     pointerMoved: o.pointerMoved === true,
     aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
@@ -388,8 +391,11 @@ async function handleNotMergeable(
   return { integrate: true, pr: rr.prNumber ?? pr, changeId };
 }
 
-/** POST `/api/changes/integrate` and normalise the outcome. Returns { res, result }. */
-async function postIntegrate({ base, authHeaders, body }, fetchImpl) {
+/**
+ * POST `/api/changes/integrate`, wait on the job it submitted, and normalise the outcome.
+ * Returns { res, result } — `res.ok` is the submit's transport verdict.
+ */
+async function postIntegrate({ base, authHeaders, body }, fetchImpl, waitOpts = {}) {
   const res = await fetchImpl(`${base}/api/changes/integrate`, {
     method: "POST",
     headers: { "content-type": "application/json", ...authHeaders },
@@ -401,6 +407,11 @@ async function postIntegrate({ base, authHeaders, body }, fetchImpl) {
   } catch {
     /* non-JSON / empty body */
   }
+  if (isJobAccepted(res, data)) {
+    console.log(`  submitted as job ${data.jobId} — waiting for it to finish (it continues on the platform if you stop waiting)…`);
+    const { outcome } = await waitForPipelineJob({ base, authHeaders, jobId: data.jobId }, fetchImpl, waitOpts);
+    return { res, result: normalizeIntegrateResponse({ ...outcome, jobId: data.jobId }) };
+  }
   return { res, result: normalizeIntegrateResponse(data) };
 }
 
@@ -422,7 +433,13 @@ function integrateBody({ tenant, pr, changeId, headSha }) {
  * @returns {number}
  */
 export function reportIntegrated(result, { tenant, label }) {
-  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  const state = `${result.jobState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.pending) {
+    console.log(`\n  … ${label} is still being added to ${tenant}'s preview aggregate — it finishes on the platform.`);
+    if (result.jobId) console.log(`  job: ${result.jobId}`);
+    console.log("  → next: re-check the queue (`tot pr list --tenant " + tenant + "`) in a few minutes.");
+    return 0;
+  }
   if (result.ok) {
     console.log(`\n  ✓ queued ${label} into ${tenant}'s preview aggregate — it is GREEN.`);
     console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
@@ -458,7 +475,8 @@ export function reportIntegrated(result, { tenant, label }) {
  *   secret:string, storefrontUrl?:string|null, yes?:boolean, refresh?:boolean,
  *   strategy?:string, mcpUrl?:string|null, identity?:string|null, env?:NodeJS.ProcessEnv }} params
  * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
- *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ *   resolveViewerTransport?:typeof resolveViewerTransport,
+ *   wait?:Parameters<typeof waitForPipelineJob>[2] }} [deps]
  * @returns {Promise<number>} process exit code
  */
 export async function runIntegrate(
@@ -575,6 +593,7 @@ export async function runIntegrate(
     ({ res, result } = await postIntegrate(
       { base, authHeaders, body: integrateBody({ tenant, pr: curPr, changeId: curChangeId, headSha: curHead }) },
       fetchImpl,
+      deps.wait,
     ));
   } catch (e) {
     console.error(
@@ -585,7 +604,7 @@ export async function runIntegrate(
 
   // A pre-flight error (auth, unknown tenant, candidate not found) is an HTTP 4xx
   // with `{ error }` and no queue verdict — surface it distinctly from a red run.
-  if (!res.ok && result.queueState == null) {
+  if (!res.ok) {
     return reportIntegrateHttpError(result, res, { tenant, label });
   }
 
@@ -612,6 +631,7 @@ export async function runIntegrate(
           }),
         },
         fetchImpl,
+        deps.wait,
       ));
     } catch (e) {
       console.error(
@@ -619,7 +639,7 @@ export async function runIntegrate(
       );
       return 1;
     }
-    if (!res.ok && result.queueState == null) {
+    if (!res.ok) {
       return reportIntegrateHttpError(result, res, { tenant, label });
     }
   }

package/src/commands/revert.mjs

@@ -22,15 +22,14 @@
  * anything — when there's nothing TO undo (never integrated, no longer part of
  * the current aggregate, or already undone).
  *
- * TRANSPORT — `POST /api/changes/revert` (opens the corrective candidate, then
- * runs it through the SAME `TenantIntegrationQueue.enqueue` accept pipeline
- * `tot accept` drives). Like `tot accept`, the CLI reaches it with either the
- * operator-secret Bearer transport (`resolveOperatorSecret` + `X-Tot-Owner` +
- * `x-tot-capability`) or a signed-in developer's viewer session when they hold
- * a live `ship-on-behalf` grant. The response is the honest terminal aggregate
- * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
- * `changeId` (the corrective candidate's own id) / `statusMessage` — rendered
- * VERBATIM, never a bare "reverted".
+ * TRANSPORT — `POST /api/changes/revert` submits a `revert` job to the store's pipeline (open
+ * the corrective candidate, then merge → build → evidence → advance the preview, exactly as
+ * `tot accept`) and answers `202 {jobId}`; this verb waits on `GET /api/pipeline/jobs/<jobId>`.
+ * Like `tot accept`, the CLI reaches it with either the operator-secret Bearer transport
+ * (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`) or a signed-in developer's
+ * viewer session when they hold a live `ship-on-behalf` grant. The outcome — `jobState` /
+ * `runState` / `pointerMoved` / `aggregateSha` / `changeId` (the corrective candidate's own id) /
+ * `statusMessage` — is rendered VERBATIM, never a bare "reverted".
  *
  * HUMAN GATE — correcting the shared preview is a decision a human makes, so
  * this ALWAYS states the EXACT plan (a NEW corrective candidate, merged through
@@ -48,6 +47,7 @@ import { resolveOperatorSecret } from "./ship.mjs";
 // No-operator-secret path: mint a viewer session from the developer's OWN `tot`
 // login. The server still gates the request on their live ship-on-behalf grant.
 import { resolveViewerTransport } from "../viewer-session.mjs";
+import { isJobAccepted, waitForPipelineJob } from "../pipeline-job.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -163,7 +163,9 @@ export function normalizeRevertResponse(data) {
   const o = data && typeof data === "object" ? data : {};
   return {
     ok: o.ok === true,
-    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    pending: o.pending === true,
+    jobId: typeof o.jobId === "string" ? o.jobId : null,
+    jobState: typeof o.jobState === "string" ? o.jobState : null,
     runState: typeof o.runState === "string" ? o.runState : null,
     pointerMoved: o.pointerMoved === true,
     aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
@@ -184,7 +186,12 @@ export function normalizeRevertResponse(data) {
  * @returns {number}
  */
 export function reportReverted(result, { tenant, label }) {
-  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  const state = `${result.jobState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.pending) {
+    console.log(`\n  … undoing ${label} in ${tenant}'s preview aggregate is still running — it finishes on the platform.`);
+    if (result.jobId) console.log(`  job: ${result.jobId}`);
+    return 0;
+  }
   if (result.ok) {
     console.log(`\n  ✓ undid ${label} in ${tenant}'s preview aggregate — it is GREEN.`);
     console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
@@ -227,7 +234,8 @@ export function reportReverted(result, { tenant, label }) {
  *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean,
  *   env?:NodeJS.ProcessEnv }} params
  * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
- *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ *   resolveViewerTransport?:typeof resolveViewerTransport,
+ *   wait?:Parameters<typeof waitForPipelineJob>[2] }} [deps]
  * @returns {Promise<number>} process exit code
  */
 export async function runRevert(
@@ -314,11 +322,16 @@ export async function runRevert(
   } catch {
     /* non-JSON / empty body */
   }
+  if (isJobAccepted(res, data)) {
+    console.log(`  submitted as job ${data.jobId} — waiting for it to finish (it continues on the platform if you stop waiting)…`);
+    const { outcome } = await waitForPipelineJob({ base, authHeaders, jobId: data.jobId }, fetchImpl, deps.wait);
+    data = { ...outcome, jobId: data.jobId };
+  }
   const result = normalizeRevertResponse(data);
 
   // A pre-flight error (auth, unknown tenant, bad body) is an HTTP 4xx with
-  // `{ error }` and no queue verdict — surface it distinctly from a red run.
-  if (!res.ok && result.queueState == null) {
+  // `{ error }` and no job outcome — surface it distinctly from a red run.
+  if (!res.ok) {
     const msg = result.error || `HTTP ${res.status}`;
     console.error(
       fail(

package/src/pipeline-job.mjs

@@ -0,0 +1,63 @@
+/**
+ * Waiting on a store pipeline job. Add to release (`tot accept`) and Undo (`tot revert`) run as
+ * jobs in the store's pipeline: the route answers `202 {jobId}` at once, and the job's outcome is
+ * read from `GET /api/pipeline/jobs/<jobId>` until it is no longer pending. The job runs on the
+ * platform whether or not anything is waiting for it — stopping here (Ctrl-C, a timeout) stops
+ * only the wait.
+ *
+ * Dependency-free (global fetch).
+ */
+
+const DEFAULT_INTERVAL_MS = 3_000;
+const DEFAULT_TIMEOUT_MS = 25 * 60_000;
+
+/**
+ * Poll the job until its outcome is terminal, or `timeoutMs` passes. Resolves with
+ * `{ outcome, timedOut }` — `outcome` is the last read (`pending: true` when it timed out).
+ * Network faults between polls are retried; a non-2xx read ends the wait with that status.
+ *
+ * @param {{ base:string, authHeaders:Record<string,string>, jobId:string }} target
+ * @param {typeof fetch} fetchImpl
+ * @param {{ intervalMs?:number, timeoutMs?:number, sleep?:(ms:number)=>Promise<void>,
+ *   now?:()=>number, onPoll?:(outcome:any)=>void }} [opts]
+ */
+export async function waitForPipelineJob({ base, authHeaders, jobId }, fetchImpl, opts = {}) {
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = opts.now ?? (() => Date.now());
+  const started = now();
+  let last = { ok: false, pending: true, jobId };
+  for (;;) {
+    let res = null;
+    try {
+      res = await fetchImpl(`${base}/api/pipeline/jobs/${encodeURIComponent(jobId)}`, {
+        method: "GET",
+        headers: { accept: "application/json", ...authHeaders },
+      });
+    } catch {
+      res = null;
+    }
+    if (res) {
+      let data = {};
+      try {
+        data = await res.json();
+      } catch {
+        data = {};
+      }
+      if (!res.ok) {
+        return { outcome: { ok: false, pending: true, jobId, error: data.error || `job read failed (${res.status})` }, timedOut: false };
+      }
+      last = data && data.outcome && typeof data.outcome === "object" ? data.outcome : last;
+      opts.onPoll?.(last);
+      if (last.pending !== true) return { outcome: last, timedOut: false };
+    }
+    if (now() - started >= timeoutMs) return { outcome: last, timedOut: true };
+    await sleep(intervalMs);
+  }
+}
+
+/** True when a submit answered with a job to wait on (`202 {jobId}`). */
+export function isJobAccepted(res, data) {
+  return Boolean(res && res.status === 202 && data && typeof data.jobId === "string");
+}