@tokenoftrust/cli 1.4.0-rc.11 → 1.4.0-rc.12

package/src/commands/ship.mjs

@@ -1,25 +1,36 @@
 /**
- * `tot ship` — promote a reconciled PREVIEW live (the deliberate ship gate).
+ * `tot ship` — deploy main → preview + live (decisions operator-verb-and-hosting-model
+ * + ship-context-dependent-semantics). The deliberate ship gate.
  *
  * The second half of the dev → preview → ship loop:
  *
  *   tot dev        run your store locally with save→reload
  *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
- *   tot ship       promote a reconciled preview live                                     ← you are here
+ *   tot ship       accept + deploy (developer) / deploy (operator)                       ← you are here
  *
- * The contract, deliberately strict because this is the step that changes the LIVE
- * site:
+ * SHIP IS CONTEXT-DEPENDENT (decision ship-context-dependent-semantics). It NEVER
+ * silently guesses — it detects the context (`detectShipContext`), prints the EXACT
+ * plan for THAT context via the SHARED affordance (`../plan.mjs`, unit U10 — the same
+ * `planForAction` + `printPlanAndConfirm` every mutating operator verb and the `/admin`
+ * confirm dialog use), and confirms before acting:
+ *
+ *   • DEVELOPER — run in your OWN store checkout on a branch: ship = ACCEPT (merge this
+ *     branch/PR into main) AND THEN DEPLOY (main → preview + live). This is `runShip`.
+ *   • OPERATOR — target a `--pr N --tenant t` that ISN'T your checkout: ship = DEPLOY
+ *     only; the merge is the separate `tot accept` verb. This is `runShipOperator`.
+ *
+ * The DEVELOPER contract, deliberately strict because this changes the LIVE site:
  *
  *   1. Resolve the ACTIVE candidate for this checkout (the SAME handle `tot preview`
  *      last pushed to — see `resolveActiveChangeId`, the seam u4 rekeys to be
  *      branch-bound) and REQUIRE it to be OPEN and RECONCILED. A merged/closed
  *      candidate, or one whose evidence isn't green yet, is refused with a clear
  *      next step — never shipped.
- *   2. ALWAYS render a diff-vs-live (what this ship changes on the live site) and
- *      require ONE explicit [y/N] confirm, defaulting to NO. There is deliberately
- *      NO `--yes` / `--force` bypass in v1: shipping live is a decision a human
- *      makes at the keyboard. In a NON-TTY (CI, piped) we REFUSE rather than
- *      auto-confirm — nothing ships without someone saying yes.
+ *   2. ALWAYS render a diff-vs-live (what this ship changes on the live site), then
+ *      print the EXACT plan and require ONE explicit confirm, defaulting to NO. `--yes`
+ *      confirms non-interactively (the operator's explicit go); a NON-TTY WITHOUT
+ *      `--yes` REFUSES rather than auto-confirm — nothing ships without an explicit yes.
+ *      Merge-to-main / go-live / deploy stay HUMAN GATES.
  *   3. On confirm, `change_accept` (the human ship gate) transitions the change to
  *      shipped; we then poll `change_status` until it reports shipped and print the
  *      live URL.
@@ -50,7 +61,7 @@ import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
-import { isInteractive, promptYesNo } from "../prompt.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
 import {
@@ -68,32 +79,128 @@ import {
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot ship — deploy main → preview + live (context-dependent)
 
-const USAGE = `tot ship — promote a reconciled preview live
+  tot ship                          ship the preview you last pushed with \`tot preview\`
+  tot ship <N>                      DEVELOPER: ship PR #N from your OWN checkout
+  tot ship pr/<N>                   (same — also accepts \`pr#N\`, \`#N\`)
+  tot ship --pr <N> --tenant <t>    OPERATOR: deploy a PR that isn't your checkout
+  tot ship --change-id <chg_…>      target an explicit change record (operator targeting)
+  tot ship --yes                    confirm non-interactively (skip the [y/N] prompt)
+  tot ship --identity <id>          sign in as a specific identity for this ship
+  tot ship --mcp <url>              MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
-  tot ship                 promote the preview you last pushed with \`tot preview\`
-  tot ship --identity <id> sign in as a specific identity for this ship
-  tot ship --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  \`tot ship\` is CONTEXT-DEPENDENT (decision ship-context-dependent-semantics):
 
-  Ship makes your preview LIVE once it has reconciled cleanly — the deliberate step
-  AFTER \`tot preview\`. It ALWAYS shows you the diff about to go live and asks for a
-  single y/N confirmation first; there is no --yes/--force, and it refuses to run
-  without an interactive terminal. If you can't approve the ship yourself, it records
-  the request and tells you who can.`;
+    • DEVELOPER — run in your OWN store checkout on a branch: ship = ACCEPT (merge
+      this branch/PR into main) AND THEN DEPLOY (main → preview + live). A POSITIONAL
+      \`tot ship 4\` / \`tot ship pr/4\` names the PR to ship — same developer semantics,
+      the tenant is inferred from the checkout.
+    • OPERATOR — target a \`--pr N --tenant t\` that ISN'T your checkout: ship = DEPLOY
+      only (the merge is the separate \`tot accept\` verb).
 
-/** Parse `tot ship` argv. Pure. Deliberately NO --yes/--force (see the header). */
+  It NEVER silently guesses: it prints the EXACT plan for THAT context and confirms
+  first (\`--yes\` to confirm non-interactively; a non-TTY without \`--yes\` refuses).
+  Merge-to-main / go-live / deploy stay HUMAN GATES. If you can't approve the ship
+  yourself, it records the request and tells you who can.`;
+
+/**
+ * Parse a POSITIONAL PR token — `4`, `pr/4`, `pr#4`, `pr-4`, `#4`, `PR/4` — to the
+ * PR number as a string, or null when the token isn't a PR reference. Pure. Used so
+ * `tot ship 4` / `tot ship pr/4` name a PR positionally, the same value the `--pr`
+ * flag carries (but developer-context — see `detectShipContext`).
+ * @param {string} token
+ * @returns {string|null}
+ */
+export function parsePrToken(token) {
+  if (typeof token !== "string") return null;
+  const m = token.trim().match(/^(?:pr)?[/#-]?(\d+)$/i);
+  return m ? m[1] : null;
+}
+
+/** Parse `tot ship` argv. Pure. */
 export function parseShipArgs(argv) {
-  const a = { mcp: null, identity: null, noOpen: false, help: false };
+  const a = {
+    mcp: null,
+    identity: null,
+    noOpen: false,
+    yes: false,
+    pr: null,
+    // True when `pr` came from a POSITIONAL token (`tot ship 4`) rather than the
+    // `--pr` flag. A positional PR in your OWN checkout is DEVELOPER intent (ship my
+    // own PR — accept+deploy); the `--pr` flag stays OPERATOR targeting (deploy-only).
+    prPositional: false,
+    tenant: null,
+    changeId: null,
+    headSha: null,
+    url: null,
+    help: false,
+  };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--identity") a.identity = argv[++i];
     else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--change-id") a.changeId = argv[++i];
+    else if (t === "--head-sha" || t === "--head") a.headSha = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
+    else if (!t.startsWith("-") && a.pr == null) {
+      // A POSITIONAL PR reference (`tot ship 4` / `tot ship pr/4` / `tot ship #4`).
+      // Only the first one wins; an explicit `--pr` flag (set above) takes precedence.
+      const n = parsePrToken(t);
+      if (n != null) {
+        a.pr = n;
+        a.prPositional = true;
+      }
+    }
   }
   return a;
 }
 
+/**
+ * Decide ship's CONTEXT (decision ship-context-dependent-semantics). Pure — no I/O.
+ *
+ *  - "developer": run inside your OWN store checkout with no cross-target flags →
+ *    ship = ACCEPT (merge this branch/PR into main) AND THEN DEPLOY (main → preview
+ *    + live). This is the happy-path `tot ship` with no flags.
+ *  - "operator": you're targeting a specific `--pr`/`--tenant` that ISN'T your active
+ *    checkout → ship = DEPLOY only (the merge is the separate `tot accept` verb).
+ *
+ * Ship NEVER silently guesses which it is — this classifies from the EXPLICIT signals
+ * (an explicit `--pr`, a `--tenant` that differs from the checkout, or a `--tenant`
+ * named from outside any checkout), and the caller then prints the concrete plan for
+ * THAT context and confirms.
+ *
+ * A POSITIONAL PR (`tot ship 4`) is the exception the `--pr` FLAG is not: it names the
+ * developer's OWN PR to ship from their OWN checkout, so — absent any cross-target
+ * signal (a differing `--tenant`, or being named from outside a checkout) — it stays
+ * DEVELOPER (accept+deploy). The `--pr` flag remains OPERATOR targeting (deploy-only),
+ * per its documented "a PR that isn't your checkout" contract.
+ *
+ * @param {{ pr?: number|string|null, prPositional?: boolean, tenant?: string|null,
+ *   ctxTenant?: string|null, ctxMode?: string|null }} p
+ * @returns {"developer"|"operator"}
+ */
+export function detectShipContext({ pr = null, prPositional = false, tenant = null, ctxTenant = null, ctxMode = null } = {}) {
+  const hasPr = pr != null && `${pr}`.trim() !== "";
+  const t = (tenant || "").trim();
+  const ct = (ctxTenant || "").trim();
+  const tenantDiffers = Boolean(t && ct && t !== ct);
+  const targetingFromOutside = Boolean(t && ctxMode !== "checkout");
+  // A positional `tot ship 4` inside your OWN checkout, with no cross-target flags, is
+  // the developer shipping their own PR — accept+deploy, NOT operator deploy-only.
+  const positionalOwnPr = hasPr && prPositional && ctxMode === "checkout" && !tenantDiffers && !targetingFromOutside;
+  if (positionalOwnPr) return "developer";
+  if (hasPr || tenantDiffers || targetingFromOutside) return "operator";
+  return "developer";
+}
+
 // ─── Response normalisation (defensive — one MCP, but shapes may vary) ───────────
 
 /**
@@ -434,22 +541,36 @@ export async function pollChangeShipped(client, { id, tenant }, { attempts = 6,
  *
  * @param {{callTool:Function}} client  an MCP client (real or mock)
  * @param {{ tenant:string, changeId:string, repo:string,
- *   git:(args:string[])=>string, noOpen?:boolean,
- *   changeSummary?:{ title?:string, body?:string[] } }} params
- * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
+ *   git:(args:string[])=>string, noOpen?:boolean, yes?:boolean, storefrontUrl?:string|null,
+ *   changeSummary?:{ title?:string, body?:string[] }, expectedPr?:number|string|null }} params
+ * @param {{ confirmPlan?:typeof printPlanAndConfirm,
  *   poll?:typeof pollChangeShipped, openUrl?:(u:string)=>boolean, progress?:boolean,
  *   resolveRecord?:typeof resolveChangeRecordId }} [deps]
  * @returns {Promise<number>} process exit code
  */
-export async function runShip(client, { tenant, changeId, repo, git, noOpen, changeSummary }, deps = {}) {
-  const interactive = deps.interactive || isInteractive;
-  const confirm = deps.confirm || promptYesNo;
+export async function runShip(client, { tenant, changeId, repo, git, noOpen, yes = false, storefrontUrl = null, changeSummary, expectedPr = null }, deps = {}) {
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
   const poll = deps.poll || pollChangeShipped;
   const resolveRecord = deps.resolveRecord || resolveChangeRecordId;
 
   // 1. Resolve the active candidate (the forge slice — open-gate + diff-vs-live).
   const candidate = normalizeCandidate(await client.callTool("candidate_status", { repo, changeId }));
 
+  // 1a. If the developer named a PR positionally (`tot ship 4`), that number is a
+  //     SAFETY assertion of WHICH PR ships — refuse (before opening any change record)
+  //     if the checkout's resolved branch-bound candidate is a DIFFERENT PR, so
+  //     `tot ship 4` can never silently ship PR #7. Only guards when both are known.
+  const want = expectedPr != null && `${expectedPr}`.trim() ? Number(expectedPr) : null;
+  if (want != null && candidate && candidate.prNumber != null && Number(candidate.prNumber) !== want) {
+    console.error(
+      fail(
+        `you asked to ship PR #${want}, but this checkout's active candidate is PR #${candidate.prNumber}`,
+        `switch to the branch whose PR is #${want} (or run \`tot ship\` with no number to ship this checkout's candidate)`,
+      ),
+    );
+    return 1;
+  }
+
   // 1b. Resolve the change-RECORD id (`chg_<uuid>`) that the gate + change_accept key
   //     on — a DISTINCT namespace from the candidate handle (see the header). Only
   //     meaningful for an OPEN candidate; for a missing/closed one we skip it and let
@@ -484,22 +605,38 @@ export async function runShip(client, { tenant, changeId, repo, git, noOpen, cha
     return 1;
   }
 
-  // 2. ALWAYS render the diff-vs-live, then require ONE explicit y/N confirm.
+  // 2. ALWAYS render the diff-vs-live, then print the EXACT plan and gate on ONE
+  //    explicit confirm via the SHARED affordance (plan.mjs). DEVELOPER context =
+  //    accept-then-deploy (merge this PR into main, THEN deploy main → preview + live).
   const diff = computeDiffVsLive(git, candidate.baseSha, candidate.headSha);
   for (const line of renderDiffVsLive({ ...diff, prUrl: candidate.url })) console.log(line);
 
-  // NON-TTY: refuse rather than auto-confirm — nothing ships without a human yes.
-  if (!interactive()) {
-    console.error(
-      fail(
-        "`tot ship` needs an interactive terminal to confirm the live change",
-        "run it from a terminal (there is intentionally no --yes/--force)",
-      ),
-    );
-    return 2;
-  }
-  const proceed = await confirm(`\n  Ship this live to ${tenant}?`, false);
-  if (!proceed) {
+  const previewUrl = review.previewUrl || candidate.url || previewUrlFor(storefrontUrl, tenant, candidate.prNumber);
+  const planLines = planForAction({
+    action: "ship",
+    context: "developer",
+    tenant,
+    pr: candidate.prNumber,
+    changeId: id,
+    headSha: candidate.headSha,
+    targets: { preview: previewUrl, live: liveUrlFor(tenant) },
+  });
+  // `--yes` confirms non-interactively; a non-TTY WITHOUT `--yes` refuses (never
+  // auto-confirm a live change). Default answer is NO on an interactive prompt.
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Ship this live to ${tenant}?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm the live change",
+          "run it from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
     console.log("  Ship cancelled — nothing changed.");
     return 0;
   }
@@ -580,6 +717,188 @@ function reportShipped(accept, status, { tenant, noOpen, openUrl }) {
   return 0;
 }
 
+// ─── URL derivation (pure) ─────────────────────────────────────────────────────────
+
+/** The hosted preview URL for a tenant's PR, or null when the PR/base is unknown. Pure. */
+export function previewUrlFor(base, tenant, pr) {
+  const origin = (base || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  if (pr == null || `${pr}`.trim() === "" || !tenant) return null;
+  return `${origin}/preview/${encodeURIComponent(tenant)}/pr/${pr}`;
+}
+
+/** The live site URL for a tenant (the tenant IS its apex domain, e.g. tokenoftrust.com). Pure. */
+export function liveUrlFor(tenant) {
+  const t = (tenant || "").trim();
+  return t ? `https://${t}` : null;
+}
+
+// ─── Operator ship (DEPLOY-only) ─────────────────────────────────────────────────────
+
+/**
+ * The OPERATOR ship flow (decision ship-context-dependent-semantics): the caller is
+ * targeting a `--pr N --tenant t` that ISN'T their checkout, so ship means DEPLOY
+ * (main → preview + live) — NOT merge. The merge is the separate `tot accept` verb.
+ *
+ * We STATE the exact deploy plan (the shared `planForAction`/`printPlanAndConfirm`
+ * affordance) and confirm before acting (`--yes` to confirm non-interactively; a
+ * non-TTY without `--yes` refuses).
+ *
+ * ┌─ CROSS-TENANT/CROSS-PR TARGETING (the app-bound-identity constraint) ────────────┐
+ * │ Resolving a TARGETED PR's change-record id / head sha from the forge needs a      │
+ * │ `candidate_status` read the CLI's user identity may NOT be allowed (it's           │
+ * │ app-bound). So we take the change-record id (and head sha) via EXPLICIT flags      │
+ * │ (`--change-id` / `--head-sha`) rather than blocking — mirroring U3's descriptor    │
+ * │ flags. See the `u9` marker below for the auto-resolution follow-on.                │
+ * └───────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * @param {{callTool:Function}} client  an MCP client (real or mock)
+ * @param {{ tenant:string, pr?:number|string|null, changeId?:string|null,
+ *   headSha?:string|null, storefrontUrl?:string|null, noOpen?:boolean, yes?:boolean }} params
+ * @param {{ confirmPlan?:typeof printPlanAndConfirm, poll?:typeof pollChangeShipped,
+ *   openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runShipOperator(
+  client,
+  { tenant, pr = null, changeId = null, headSha = null, storefrontUrl = null, noOpen = false, yes = false },
+  deps = {},
+) {
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const poll = deps.poll || pollChangeShipped;
+
+  // u9: auto-resolve targeted PR descriptor (changeId/headSha) via forge PR-read —
+  // the CLI's app-bound user identity may not be allowed the candidate_status read for
+  // a cross-tenant/cross-PR target, so today the operator supplies these via flags.
+  const previewUrl = previewUrlFor(storefrontUrl, tenant, pr);
+  const planLines = planForAction({
+    action: "ship",
+    context: "operator",
+    tenant,
+    pr,
+    changeId,
+    headSha,
+    targets: { preview: previewUrl, live: liveUrlFor(tenant) },
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Deploy ${tenant} live now (main → preview + live)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "`tot ship` needs an interactive terminal to confirm this deploy",
+          "re-run from a terminal, or pass --yes to confirm non-interactively",
+        ),
+      );
+      return 2;
+    }
+    console.log("  Ship cancelled — nothing deployed.");
+    return 0;
+  }
+
+  // We can't auto-resolve the targeted PR's change record from the forge (see above),
+  // so the operator must name it explicitly to promote it.
+  if (!changeId) {
+    console.error(
+      fail(
+        "operator ship needs the target change-record id to deploy",
+        "pass --change-id <chg_…> (u9 will auto-resolve it from --pr via a forge PR-read)",
+      ),
+    );
+    return 2;
+  }
+
+  // TODO(u9): operator ship is DEPLOY-only (the merge is the separate `tot accept`),
+  // but a DISTINCT deploy-only trigger separate from `change_accept` is NOT yet wired.
+  // Until it is, this uses the EXISTING promote path — `change_accept` (u7's
+  // promote-by-digest, keyed on the resolved change-record id) — which is the same
+  // mechanism the developer path calls. Adding a new deploy path is out of scope for u4.
+  let accept;
+  try {
+    accept = normalizeChangeResult(
+      await client.callTool("change_accept", {
+        id: changeId,
+        tenant,
+        dryRun: false,
+        idempotencyKey: `ship-${changeId}-${headSha ?? "head"}`,
+      }),
+    );
+  } catch (e) {
+    console.error(
+      fail(
+        `the deploy gate refused this change: ${String(e?.message || e)}`,
+        "check the change is merged to main and reconciled, then re-run `tot ship`",
+      ),
+    );
+    return 1;
+  }
+
+  const progress = deps.progress === false ? null : startProgress("deploying…");
+  let status;
+  try {
+    status = await poll(client, { id: changeId, tenant });
+  } finally {
+    progress?.stop();
+  }
+  return reportShipped(accept, status, { tenant, noOpen, openUrl: deps.openUrl });
+}
+
+/**
+ * The `run` wrapper for OPERATOR ship — establish a session, bind the target tenant,
+ * and drive `runShipOperator`. Split from `run` for the same reason the developer half
+ * is split from `runShip`: this half does the I/O (auth + tenant switch), the pure flow
+ * is unit-tested with a mock client.
+ * @param {ReturnType<typeof parseShipArgs>} args
+ * @param {any} ctx
+ * @param {NodeJS.ProcessEnv} env
+ */
+async function runOperatorFlow(args, ctx, env) {
+  const tenant = (args.tenant || (ctx.mode === "checkout" ? ctx.tenant : null) || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "operator ship needs a target tenant",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com) with --pr <N>",
+      ),
+    );
+    return 2;
+  }
+  const pr = args.pr != null && `${args.pr}`.trim() && Number.isFinite(Number(args.pr)) ? Number(args.pr) : args.pr;
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env, prefer: args.identity || undefined });
+    await client.callTool("client_switch", { tenant });
+    return await runShipOperator(
+      client,
+      {
+        tenant,
+        pr,
+        changeId: args.changeId,
+        headSha: args.headSha,
+        storefrontUrl,
+        noOpen: args.noOpen,
+        yes: args.yes,
+      },
+      { openUrl: (u) => openBrowser(u) },
+    );
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to ship", e.hint || "run `tot login`, then re-run `tot ship`"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the ship service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}
+
 /**
  * @param {string[]} argv
  * @param {any} ctx
@@ -591,6 +910,23 @@ export async function run(argv, ctx) {
     console.log(USAGE);
     return 0;
   }
+
+  // Context-dependent (decision ship-context-dependent-semantics): targeting a
+  // `--pr`/`--tenant` that isn't your checkout → OPERATOR (deploy-only); otherwise,
+  // inside your own checkout → DEVELOPER (accept + deploy). Never guessed silently —
+  // both branches print the concrete plan for THAT context and confirm.
+  const ctxTenant = ctx.mode === "checkout" ? ctx.tenant : null;
+  const context = detectShipContext({
+    pr: args.pr,
+    prPositional: args.prPositional,
+    tenant: args.tenant,
+    ctxTenant,
+    ctxMode: ctx.mode,
+  });
+  if (context === "operator") {
+    return await runOperatorFlow(args, ctx, env);
+  }
+
   if (ctx.mode !== "checkout") {
     console.error(
       fail(
@@ -647,7 +983,19 @@ export async function run(argv, ctx) {
 
     return await runShip(
       client,
-      { tenant, changeId, repo, git, noOpen: args.noOpen, changeSummary },
+      {
+        tenant,
+        changeId,
+        repo,
+        git,
+        noOpen: args.noOpen,
+        yes: args.yes,
+        storefrontUrl: args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL,
+        changeSummary,
+        // A positional `tot ship 4` asserts WHICH PR — passed as a safety guard so
+        // ship refuses if this checkout's active candidate is a different PR.
+        expectedPr: args.prPositional ? args.pr : null,
+      },
       { openUrl: (u) => openBrowser(u) },
     );
   } catch (e) {

package/src/commands/submit.mjs

@@ -923,6 +923,38 @@ function reportComplianceCheck(c) {
   if (c.hint) console.log(`        → fix: ${c.hint}`);
 }
 
+/**
+ * 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
+ * (`https://storefront.tokenoftrust.store/preview/<tenant>/pr/<N>`, built server-side
+ * by the reconcile report and threaded through as `previewUrl`) is what a developer
+ * hands to a teammate, NOT the internal Gitea PR url `reportCandidate` prints earlier
+ * in the flow (step 2b) — that one stays as-is, secondary, for the developer's own
+ * reference. Labeled prominently + paired with an honest auth caveat: the share
+ * target is a TEAMMATE WITH STORE ACCESS (member/staff of the tenant), never a
+ * public/anonymous link.
+ *
+ * Degrades gracefully when `previewUrl` isn't (yet) on the status result — an older
+ * MCP, or a reconcile that hasn't finished minting it — with a note instead of a
+ * crash or a silent blank. Pure — unit-tested.
+ * @param {{ previewUrl?: string|null, status?: string }|null} s
+ * @param {string} tenant
+ * @returns {string[]}
+ */
+export function formatShareableUrlBlock(s, tenant) {
+  if (s?.previewUrl) {
+    return [
+      `\n  ✓ Preview ready — share this with your reviewer:`,
+      `      ${s.previewUrl}`,
+      `    ℹ your reviewer needs store access (a member/staff of ${tenant}) to view it — it's not a public link.`,
+    ];
+  }
+  if (s?.status === "reconciled") {
+    return [`\n  ~ reconciled, but no shareable preview URL yet — it'll show up here once available.`];
+  }
+  return [];
+}
+
 /**
  * Print the reconcile/compliance/preview result and, on a clean reconcile with a
  * preview URL, open it in the browser (unless opts.open === false).
@@ -956,10 +988,8 @@ function reportStatus(s, tenant, { open = true } = {}) {
   } else if (s.status === "reconciled") {
     console.log(`\n  ~ not yet shipped — a reviewer still needs to run change_accept.`);
   }
-  if (s.previewUrl) {
-    console.log(`\n  Preview: ${s.previewUrl}`);
-    if (open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
-      console.log("  (opened in your browser)");
-    }
+  for (const line of formatShareableUrlBlock(s, tenant)) console.log(line);
+  if (s.previewUrl && open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
+    console.log("  (opened in your browser)");
   }
 }