@tokenoftrust/cli 1.4.1 → 1.5.0

package/src/commands/ship.mjs

@@ -1,8 +1,7 @@
 /**
  * `tot ship` — publish the tenant's CURRENT GREEN AGGREGATE to live. ONE
- * meaning (unit b10 — SUPERSEDES the retired context-dependent ship, decision
- * `ship-context-dependent-semantics`, and its developer-accept-then-deploy /
- * operator-deploy-only / ship-any-built-PR branches):
+ * meaning — SUPERSEDES the retired context-dependent ship and its
+ * developer-accept-then-deploy / operator-deploy-only / ship-any-built-PR branches:
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
@@ -11,17 +10,17 @@
  * `tot ship` NEVER takes a PR/candidate target and NEVER infers context from
  * your checkout or who's running it. There is nothing to detect: it ships the
  * tenant's shared `preview` aggregate — the batch of PRs that integrated
- * cleanly and went green (b07's queue) — full stop. The candidate-level merge
+ * cleanly and went green — full stop. The candidate-level merge
  * is the separate `tot accept` verb (`accept.mjs`); ship never merges.
  *
  * THE FLOW:
  *
- *   1. GET the read-only PLAN from `/api/changes/ship` — b09's
+ *   1. GET the read-only PLAN from `/api/changes/ship` — the
  *      `AggregateShipOrchestrator.plan()` exposed over HTTP: the pinned
  *      aggregate sha, its content-addressed artifact digest, every included
  *      PR, the rollback target (what a rollback would restore), and the
  *      go-live paywall verdict. Zero side effects.
- *   2. Print the EXACT plan via the shared U10 affordance (`../plan.mjs`) and
+ *   2. Print the EXACT plan via the shared affordance (`../plan.mjs`) and
  *      require ONE explicit confirm, defaulting to NO. `--yes` confirms
  *      non-interactively; a non-TTY WITHOUT `--yes` REFUSES — nothing ships
  *      without an explicit yes.
@@ -48,6 +47,11 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
 import { emitActivity } from "../activity.mjs";
+// The doctor PUSH: on a refused/failed ship (most tellingly "not green"),
+// auto-append the COMPACT summary over the SAME operator transport, so the operator
+// sees WHICH changes are keeping the aggregate from going green without a separate
+// `tot preview doctor` run.
+import { autoSurfaceDoctor } from "../merge-doctor-report.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -98,7 +102,7 @@ export function parseShipArgs(argv) {
   return a;
 }
 
-// ─── Operator-secret transport (shared with `tot pr list --tenant` / u16/u17) ────
+// ─── Operator-secret transport (shared with `tot pr list --tenant`) ────
 //
 // `resolveOperatorSecret` / `normalizeChangesQueue` are the SAME helpers the
 // retired operator-by-PR ship path minted; `tot pr list --tenant` (`pr.mjs`)
@@ -204,7 +208,7 @@ export function liveUrlFor(tenant) {
 // ─── Response normalisation (defensive — one endpoint, but shapes may vary) ─────
 
 /**
- * Normalise a `GET /api/changes/ship` body — b09's `AggregateShipPlan` (a
+ * Normalise a `GET /api/changes/ship` body — the `AggregateShipPlan` (a
  * shippable aggregate) or `AggregateShipRefusal` (nothing shippable), read
  * defensively since it crossed the wire as JSON. Pure — unit-tested.
  * @param {any} data
@@ -245,7 +249,7 @@ export function normalizeShipPlan(data) {
 }
 
 /**
- * Normalise a `POST /api/changes/ship` body — b09's `AggregateShipResult`.
+ * Normalise a `POST /api/changes/ship` body — the `AggregateShipResult`.
  * `state` is the ONLY honest terminal-state authority: render "shipped live"
  * for `"shipped"` and nothing else. Pure — unit-tested.
  * @param {any} data
@@ -327,6 +331,14 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     "x-tot-capability": "ship-on-behalf",
   };
 
+  // Auto-surface the merge-doctor on a refused/failed ship. Best-effort:
+  // fetches the hosted doctor over the SAME operator transport and prints the COMPACT
+  // summary; never throws and never touches the exit code. A clean/unreachable doctor
+  // prints nothing — so this only ever ADDS the "here's what's not green" context.
+  const surfaceDoctor = async () => {
+    for (const line of await autoSurfaceDoctor({ base, authHeaders, fetchImpl })) console.error(line);
+  };
+
   // 1. GET the read-only plan: the pinned sha + artifact digest + included PRs +
   //    rollback target + paywall verdict. Zero side effects.
   let planRes;
@@ -356,10 +368,13 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const plan = normalizeShipPlan(planData);
   if (!plan.ok) {
     console.error(fail(plan.message, refusalNextStep(plan.reason)));
+    // A not-green / no-passed-run refusal is exactly what the doctor diagnoses —
+    // name the changes keeping the aggregate red right here.
+    await surfaceDoctor();
     return 1;
   }
 
-  // 2. Print the EXACT plan via the shared U10 affordance, then require ONE
+  // 2. Print the EXACT plan via the shared affordance, then require ONE
   //    explicit confirm (`--yes` non-interactive; a non-TTY without it refuses).
   const liveUrl = liveUrlFor(tenant);
   const planLines = planForAction({
@@ -416,7 +431,7 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   progress?.stop();
 
   const shipResult = normalizeShipResult(shipData);
-  // D3: emit the ship publish lifecycle event — `tot ship` does no LOCAL git op
+  // 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
@@ -433,7 +448,9 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     payload: { args: { command: "ship", subcommand: "ship.publish" } },
   });
 
-  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const code = reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  if (code !== 0) await surfaceDoctor();
+  return code;
 }
 
 /**

package/src/commands/start.mjs

@@ -4,30 +4,30 @@
  *
  * It COMPOSES the other commands' cores in-process (no shelling out to `tot …`):
  *
- *   preflight   collectChecks()  (F — self-healing where it can be)
+ *   preflight   collectChecks() — self-healing where it can be
  *   login       establishSession()  (developer OAuth; offers inline sign-in when
- *               there's no session yet — no re-run — see tryResolveSession)
- *              (A2 — run concurrently: neither gates the other; wait on the slower)
+ *               there's no session yet — no re-run — see tryResolveSession),
+ *               run concurrently: neither gates the other; wait on the slower
  *      ↓
  *   store       normalizeStores(client_list) → auto-pick if exactly one, else
- *               use --tenant, else the remembered last tenant, else choose (A4)
+ *               use --tenant, else the remembered last tenant, else choose
  *      ↓
  *   checkout ─┬─ checkoutTenant() → ./<tenant>
  *   runner   ─┘  prefetch the runner: the native renderer artifact by default
- *               (F3 — no Docker prerequisite), or the Docker registry
+ *               (no Docker prerequisite), or the Docker registry
  *               credential on --docker / as the automatic fallback if the
  *               native artifact can't be fetched (same fallback `tot dev`
- *               uses — see dev.mjs#NativeArtifactUnavailableError)
- *              (C1 — run concurrently with checkout: both just need the
- *               session resolved above)
+ *               uses — see dev.mjs#NativeArtifactUnavailableError), run
+ *               concurrently with checkout: both just need the
+ *               session resolved above
  *      ↓
  *   dev         spawnNativeDev() or spawnDevContainer() → wait for ready →
- *               open the browser (C/D)
+ *               open the browser
  *      ↓
- *   you're live crafted ending (elapsed time printed — A3), seeded with
- *               IDEAS[0] (G3), THEN the optional "Connect Claude?" prompt: on
+ *   you're live crafted ending (elapsed time printed), seeded with
+ *               IDEAS[0], THEN the optional "Connect Claude?" prompt: on
  *               yes, `claude mcp add` AND drop straight into that seeded
- *               prompt (G2) — the payoff, not a pointer to go write one.
+ *               prompt — the payoff, not a pointer to go write one.
  *
  * ZERO-LOGIN FREE TASTE (--sample / no session): when the user passes --sample,
  * or has no Token of Trust session (and doesn't decline), `tot start` SKIPS
@@ -36,11 +36,11 @@
  * ends on the SAME "connect the ToT MCP for the real power" opt-in. The MCP is
  * repositioned as the upsell, not a gate. See runSampleStart + sample.mjs.
  *
- * Value-first ordering (C): the running site + browser come BEFORE any mention of
+ * Value-first ordering: the running site + browser come BEFORE any mention of
  * connecting the MCP; Claude is the supercharge offered after the aha, not a gate.
- * ONE felt browser login (B2): `claude mcp add` only ever runs behind that final
+ * ONE felt browser login: `claude mcp add` only ever runs behind that final
  * opt-in — the core loop above needs nothing but the cached `tot login` session.
- * Every failure ends with the exact next command via the shared formatter (F).
+ * Every failure ends with the exact next command via the shared formatter.
  *
  * Dependency-free (node:readline/promises + the cores above).
  */
@@ -130,7 +130,7 @@ export function pickStore(stores) {
 /**
  * Decide which tenant to use, given the identity's available stores, an
  * explicit `--tenant` override, and a remembered "last tenant" from a prior
- * run (A4). Pure + exported so the precedence is unit-tested without any I/O.
+ * run. Pure + exported so the precedence is unit-tested without any I/O.
  * Precedence: explicit > single store (pickStore) > remembered (if still one
  * of the available stores) > ambiguous ("many" — caller must prompt).
  * @param {Array<{id:string,name:string}>} stores
@@ -191,7 +191,7 @@ export async function run(argv, ctx) {
 
   const startedAt = Date.now();
 
-  // Explicit free taste: skip login/store/checkout entirely (A0 zero-login).
+  // Explicit free taste: skip login/store/checkout entirely (zero-login).
   if (decideStartMode({ sampleFlag: args.sample, hasSession: true }) === "sample") {
     return runSampleStart(args, ctx, env, startedAt);
   }
@@ -205,7 +205,7 @@ export async function run(argv, ctx) {
     const client = createMcpClient(baseUrl);
 
     // Resolve a session, tolerating a no-session / no-network condition so we can
-    // offer the free local preview instead of dead-ending (B/A0).
+    // offer the free local preview instead of dead-ending.
     const session = await tryResolveSession(client, env, args);
     if (decideStartMode({ sampleFlag: false, hasSession: !!session }) === "sample") {
       if (!(await confirmSampleFallback(args))) {
@@ -216,18 +216,18 @@ export async function run(argv, ctx) {
       return await runSampleStart(args, ctx, env, startedAt);
     }
 
-    // Authenticated path. Preflight (F) now that we know we're taking it — the
+    // Authenticated path. Preflight now that we know we're taking it — the
     // local machine checks (node/git/Docker) that the authed loop needs.
     await preflight(ctx, env);
     console.log(`  ✓ signed in as ${describeIdentity(session)} via ${mcpOrigin(baseUrl)}`);
 
     // Resolve the activity-bridge credential + the hosted Developer Cockpit URL
     // ONCE, up front — both the pre-pick "keep the cockpit alive" heartbeat below
-    // (b2) and the post-boot heartbeat + milestone banners (u2) use them.
+    // and the post-boot heartbeat + milestone banners use them.
     const bridgeEnv = activityBridgeEnv(env);
     const cockpitUrl = cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL);
 
-    // b2 — a >1-store identity blocks on the interactive store picker below, and
+    // A >1-store identity blocks on the interactive store picker below, and
     // (before this) the hosted cockpit got NO heartbeat until the dev server
     // spawned much later, so a multi-store dev's cockpit sat on Step 1 forever
     // while the terminal quietly waited for a number. Start beating NOW (no local
@@ -236,7 +236,7 @@ export async function run(argv, ctx) {
     // the live localhost URL) takes over once we have it.
     const stopEarlyHeartbeat = startHeartbeatFromEnv(bridgeEnv, {});
 
-    // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
+    // 3. store — auto-pick, use --tenant, use the remembered one, or choose.
     // Keep the raw client_list so a tool ERROR (unauthenticated / not-entitled) is
     // surfaced with who + where, not collapsed to an empty list (fb-...f45zg9).
     let tenant;
@@ -254,31 +254,31 @@ export async function run(argv, ctx) {
     }
 
     // 4. checkout → ./<tenant> (reuse an existing checkout on a re-run),
-    // OVERLAPPED (C1) with prefetching the runner: the native artifact by
-    // default (F3 — no Docker prerequisite), or the Docker registry
+    // OVERLAPPED with prefetching the runner: the native artifact by
+    // default (no Docker prerequisite), or the Docker registry
     // credential on --docker / as the automatic native-unavailable fallback.
     // Both are independent authenticated calls once login (above) has
     // resolved, so there's no reason to pay for them serially.
     const dir = resolve(process.cwd(), tenant);
     // Resolve a free port so the URL we open/poll/print matches what the runner
     // binds (Vite strictPort is off → a busy port would drift). No-op if free.
-    const devArgs = {
+    const devArgs = /** @type {any} */ ({
       image: null, port: String(await firstFreePort(Number(args.port || 4321))), mcp: args.mcp,
       noLogin: false, noOpen: args.noOpen, docker: args.docker,
-    };
-    const runtime = { useDocker: args.docker, runnerDir: null };
+    });
+    const runtime = /** @type {{ useDocker: boolean, runnerDir: any }} */ ({ useDocker: args.docker, runnerDir: null });
     await Promise.all([
       ensureCheckout(client, tenant, dir, env),
       prefetchRuntime(client, devArgs, env, runtime, ctx),
     ]);
 
-    // u3 — say EXACTLY where the code landed + THE one next step, so a freshly
+    // Say EXACTLY where the code landed + THE one next step, so a freshly
     // checked-out dev is never left wondering what to open. Absolute path (works
     // from any directory) and a single, unambiguous action.
     printCheckoutLanding(dir, cockpitUrl);
 
-    // 5. dev — native by default (F3), Docker on --docker or the fallback
-    // above; wait for the server, open the browser (C/D).
+    // 5. dev — native by default, Docker on --docker or the fallback
+    // above; wait for the server, open the browser.
     const ctxDev = detectContext(dir);
     let url, handle;
     if (runtime.useDocker) {
@@ -292,11 +292,11 @@ export async function run(argv, ctx) {
       handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: bridgeEnv });
     }
 
-    // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
+    // Heartbeat the hosted cockpit with the CLI version + this live localhost
     // URL for the life of the run — CLI-side, using the cached bridge credential
     // (no-op when none is cached). The runner keeps reporting file-saves itself.
     // Hand off from the pre-pick (URL-less) beat to this URL-bearing one so the
-    // cockpit's live local link lights up exactly when the server is up (b2).
+    // cockpit's live local link lights up exactly when the server is up.
     stopEarlyHeartbeat();
     const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url, cwd: dir });
     handle.done.finally(() => stopHeartbeat());
@@ -314,8 +314,8 @@ export async function run(argv, ctx) {
       console.log("  ✓ opened your browser");
     }
 
-    // 6. you're live (G) — land on the store ROOT (not /dev), print elapsed time
-    // (A3) so the "instant" claim is measured. The "Connect Claude" step is
+    // 6. you're live — land on the store ROOT (not /dev), print elapsed time
+    // so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
     printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl, dir);
@@ -463,10 +463,10 @@ async function confirmSampleFallback(args) {
 }
 
 /**
- * Self-healing preflight (F): run the readiness checks; a blocking failure
- * ends with the next command. Docker is informational-only here (F3: native
+ * Self-healing preflight: run the readiness checks; a blocking failure
+ * ends with the next command. Docker is informational-only here — native
  * is the default runtime, so Docker not running doesn't block `tot start`
- * anymore) — its own readiness is handled lazily in prefetchDockerLogin(),
+ * anymore — its own readiness is handled lazily in prefetchDockerLogin(),
  * only when the run actually needs it (--docker or the native fallback).
  */
 async function preflight(ctx, env) {
@@ -482,8 +482,8 @@ async function preflight(ctx, env) {
 }
 
 /**
- * Prefetch the runner (C1) so it's overlapped with checkout instead of paid
- * for serially afterward: the native renderer artifact by default (F3 — no
+ * Prefetch the runner so it's overlapped with checkout instead of paid
+ * for serially afterward: the native renderer artifact by default (no
  * Docker prerequisite), or the Docker registry pull credential on --docker.
  *
  * On a native (entitled-artifact) fetch failure the runtime stays NATIVE: it
@@ -524,8 +524,8 @@ async function prefetchRuntime(client, devArgs, env, runtime, ctx) {
 
 /**
  * The Docker-path half of prefetchRuntime: registry login (reusing the
- * already-authenticated client, C1) plus a best-effort Docker auto-start
- * (self-healing — F) so buildContainerPlan doesn't have to hard-fail on a
+ * already-authenticated client) plus a best-effort Docker auto-start
+ * (self-healing) so buildContainerPlan doesn't have to hard-fail on a
  * Docker Desktop that just needs a nudge.
  */
 async function prefetchDockerLogin(client, devArgs, env) {
@@ -570,7 +570,7 @@ function noStoresError({ session, baseUrl, listErr, list = null }) {
       { next: "run `tot whoami` to check your session, or `tot login` again — then re-run `tot start`" },
     );
   }
-  // Status-aware (card c2): an UNLINKED identity is pointed at `tot link`, not the
+  // Status-aware: an UNLINKED identity is pointed at `tot link`, not the
   // misleading "ask for a store invite" copy; the genuine zero-grants case keeps it.
   const g = noStoresGuidance(list);
   return new CliError(`signed in as ${who} via ${origin}, but ${g.headline}`, { next: g.next });
@@ -578,9 +578,13 @@ function noStoresError({ session, baseUrl, listErr, list = null }) {
 
 /**
  * Resolve the tenant to work on from the (normalized) store list, args, and
- * the remembered last tenant (A4) — then remember whatever was decided so the
+ * the remembered last tenant — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
+/**
+ * @param {any} stores @param {any} args @param {any} env @param {string} baseUrl
+ * @param {{ session?: any, listErr?: string|null, list?: any }} [opts]
+ */
 async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null, list = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
@@ -603,22 +607,23 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
   } else {
     // Many stores, nothing remembered — choose. Non-interactive (no TTY /
     // --yes without a name) can't guess.
+    const many = /** @type {any} */ (pick);
     if (!isInteractive() || args.yes) {
       throw new CliError("you can build on several stores — pick one", {
-        next: `tot start --tenant <tenant>  (one of: ${pick.stores.map((s) => s.id).join(", ")})`,
+        next: `tot start --tenant <tenant>  (one of: ${many.stores.map((s) => s.id).join(", ")})`,
       });
     }
     // Loud + unmissable: a >1-store dev is often looking at their browser
     // cockpit (which is waiting on this pick), so make the terminal shout for
-    // their attention rather than sitting as a quiet one-liner (b2).
+    // their attention rather than sitting as a quiet one-liner.
     console.log("");
     console.log("  ⚑ ACTION NEEDED IN YOUR TERMINAL — you can build on several stores.");
     console.log("    Pick one here to light up your cockpit:\n");
-    pick.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
+    many.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
     console.log("");
-    const idx = await promptChoice(pick.stores.length);
+    const idx = await promptChoice(many.stores.length);
     console.log("");
-    tenant = pick.stores[idx].id;
+    tenant = many.stores[idx].id;
   }
 
   writeLastTenant(lastTenantPath, { mcpUrl: baseUrl, tenant });
@@ -668,7 +673,7 @@ async function waitForBoot(url, handle) {
 
 /**
  * Format elapsed milliseconds as a short human string for the "you're live"
- * ending (A3 — measure, don't just claim, "instant"). Pure + exported so it's
+ * ending — measure, don't just claim, "instant". Pure + exported so it's
  * unit-tested without any I/O.
  * @param {number} ms
  * @returns {string|null}
@@ -679,12 +684,13 @@ export function formatElapsed(ms) {
 }
 
 /**
- * u3 — after checkout, tell the developer EXACTLY where their code landed and
+ * After checkout, tell the developer EXACTLY where their code landed and
  * THE single next step. `dir` is absolute (from resolve(cwd, tenant)) so the
  * "open this" path works no matter what directory they're in. When we know the
  * Developer Cockpit URL, the one next step is framed as "edit a line → see it in
  * your cockpit"; otherwise it's the same edit-to-see-it-reload action.
  */
+/** @param {string} dir @param {string|null} [cockpitUrl] */
 function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log("");
   console.log(`  📁 Your store code is at:  ${dir}`);
@@ -720,6 +726,10 @@ function editorOpenLines(dir, { platform = process.platform, env = process.env }
  * an editor" suggestion, and the four-pane layout tip (this terminal, cockpit,
  * local preview, editor) so a build problem, a reload, and the code are never
  * more than a glance apart. */
+/**
+ * @param {string} tenant @param {string} url @param {string|null} elapsed
+ * @param {string|null} [cockpitUrl] @param {string|null} [dir]
+ */
 function printLiveEnding(tenant, url, elapsed, cockpitUrl = null, dir = null) {
   const lines = [
     `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
@@ -770,7 +780,7 @@ function printSampleLiveEnding(url, elapsed) {
 }
 
 /**
- * Offer + wire Claude (G2): `claude mcp add`, then — the payoff, not just a
+ * Offer + wire Claude: `claude mcp add`, then — the payoff, not just a
  * pointer — drop the user straight into an interactive Claude session already
  * seeded with IDEAS[0], so there's no blank slate to stare at.
  */