@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

package/src/commands/pr.mjs

@@ -16,12 +16,22 @@
  * checkout's origin remote, exactly as `tot submit` does) and reads over the MCP
  * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
  * `git`).
+ *
+ * OPERATOR MODE (unit U17). `tot pr list --tenant <t>` lists a tenant's OPEN
+ * candidate queue WITHOUT a checkout — the read-only companion to `tot ship --pr <N>
+ * --tenant <t>` (U16). It reuses U16's exact transport: the SAME `GET /api/changes`
+ * HTTP endpoint + operator-secret Bearer auth (`resolveOperatorSecret`,
+ * `normalizeChangesQueue` from ship.mjs). `view`/`close` stay developer-only.
  */
 import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
-import { repoNameFromRemote } from "./submit.mjs";
+import { repoNameFromRemote, currentBranch } from "./submit.mjs";
+// U17 reuses U16's operator-secret transport helpers verbatim (same env precedence,
+// same queue normalisation) so the operator `tot pr list` and `tot ship --pr` speak
+// one wire, not two.
+import { resolveOperatorSecret, normalizeChangesQueue } from "./ship.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -29,29 +39,73 @@ import {
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 const SUBCOMMANDS = ["list", "view", "close"];
 
-const USAGE = `tot pr — see and manage your candidate PRs
+/**
+ * The storefront-owned, shareable `/preview/<tenant>/pr/<N>` link — NEVER the
+ * forge/Gitea `url` (2026-08-18 incident: a raw forge PR URL reached an
+ * owner). `candidate_status` (the local-checkout MCP tool) has no
+ * `previewUrl` field at all, unlike the operator `GET /api/changes` path — so
+ * this constructs it the same way `runPrListOperator`'s caller resolves
+ * `storefrontUrl`, from the same env/--url override chain. Pure.
+ * @param {string} storefrontUrl
+ * @param {string} tenant
+ * @param {number|null|undefined} prNumber
+ * @returns {string|null}
+ */
+export function buildPreviewUrl(storefrontUrl, tenant, prNumber) {
+  if (typeof prNumber !== "number" || !tenant) return null;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  return `${base}/preview/${tenant}/pr/${prNumber}`;
+}
+
+const USAGE = `tot pr — see and manage candidate PRs
 
   tot pr [list]              list your open candidate PRs for this store
+  tot pr list --tenant <t>   OPERATOR: list a tenant's open candidate PRs (no checkout)
   tot pr view <N|id>         show one candidate PR (by PR number or changeId)
   tot pr close <N|id>        close (reject) a candidate PR without merging
   tot pr close <N|id> --reason "<why>"   record why it was closed (audit note)
   tot pr --mcp <url>         MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
-  A candidate PR is what \`tot submit\` opens for review. A re-submit updates your
-  open one by default; \`tot submit --new\` forks another. Use these to see and
-  manage them.`;
+  DEVELOPER (default) — run inside your OWN store checkout: lists/manages the
+  candidates \`tot submit\` opens. A re-submit updates your open one by default;
+  \`tot submit --new\` forks another.
+
+  OPERATOR — \`tot pr list --tenant <appDomain>\` lists ANY tenant's open candidate
+  queue WITHOUT a checkout (the read-only companion to \`tot ship --pr <N> --tenant\`).
+  It reads \`GET /api/changes\` with an operator secret:
+
+    tot pr list --tenant <t>   list <t>'s open candidate PRs
+    tot pr list --url <origin> storefront origin (default: env TOT_STOREFRONT_URL)
+    tot pr list --secret <s>   operator secret (prefer the env vars below)
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
 
-/** Parse `tot pr` argv into { sub, target, reason, mcp, identity, help }. Pure. */
+/** Parse `tot pr` argv into { sub, target, reason, mcp, identity, tenant, url, secret, help }. Pure. */
 export function parsePrArgs(argv) {
-  const a = { sub: null, target: null, reason: null, mcp: null, identity: null, help: false };
+  const a = {
+    sub: null,
+    target: null,
+    reason: null,
+    mcp: null,
+    identity: null,
+    tenant: null,
+    url: null,
+    secret: null,
+    help: false,
+  };
   const positional = [];
   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 === "--reason") a.reason = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
     else positional.push(t);
   }
@@ -79,11 +133,150 @@ export function matchCandidate(candidates, target) {
   return candidates.find((c) => c.changeId === target) ?? null;
 }
 
-/** One-line candidate summary for `tot pr list`. */
-function line(c) {
+/**
+ * One-line candidate summary for `tot pr list` — surfaces branch ↔ PR# ↔ preview
+ * URL so a dev sees, at a glance, which git branch each candidate belongs to (u4 —
+ * branch-bound candidates) and where its preview lives. ONLY `previewUrl` (the
+ * storefront-owned `/preview/<tenant>/pr/<N>` link) — NEVER `url` (the forge/
+ * Gitea `html_url`), which must never reach a terminal (2026-08-18 incident:
+ * a raw forge PR URL reached an owner). `active` marks the one
+ * THIS checkout's branch resolves to. Pure — unit-tested.
+ * @param {{prNumber?:number|null, branch?:string|null, changeId:string, state?:string|null,
+ *   previewUrl?:string|null, url?:string|null}} c
+ * @param {{ active?: boolean }} [opts]
+ */
+export function formatCandidateLine(c, { active = false } = {}) {
+  const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
+  const branch = c.branch ? c.branch : "(no branch)";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
+  const activePart = active ? "  ← active" : "";
+  return `  PR ${pr}  ${branch}  ${c.changeId}  [${c.state ?? "?"}]${urlPart}${activePart}`;
+}
+
+// ─── Operator queue listing (unit U17) ──────────────────────────────────────────────
+//
+// The read-only companion to `tot ship --pr <N> --tenant <t>` (U16): list a tenant's
+// OPEN candidate queue WITHOUT a checkout. It reuses U16's exact transport — the SAME
+// `GET /api/changes` endpoint (operator accept queue) + Bearer operator-secret auth
+// (`resolveOperatorSecret` / `normalizeChangesQueue` from ship.mjs) — so a listing and
+// a ship read one wire. NO merge/deploy/side-effect; pure listing.
+
+/**
+ * One-line summary of an OPEN operator-queue candidate for `tot pr list --tenant`.
+ * Two shapes come off `GET /api/changes`:
+ *   - BUILT candidate (`built:true`, has a `changeId`): PR # / status / changeId /
+ *     short head sha / preview URL — the fields an operator needs to pick a PR to ship.
+ *   - NOT-BUILT forge PR (`built:false` / `changeId:null` / `status:"not-built"`): an
+ *     open PR with no preview yet. Render it DISTINCTLY — no changeId (there is none),
+ *     a `[not built]` tag, and a build HINT instead of a preview URL — so an operator
+ *     sees it's listable but must `tot preview build` before it can ship.
+ * Adapts `formatCandidateLine`'s house style to the `GET /api/changes` shape (`status`
+ * not `state`; `previewUrl`; a `headSha` to short-render). Pure — unit-tested.
+ * @param {{prNumber?:number|null, status?:string|null, changeId?:string|null,
+ *   headSha?:string|null, previewUrl?:string|null, built?:boolean}} c
+ * @returns {string}
+ */
+export function formatOperatorCandidateLine(c) {
   const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
-  const url = c.url ? `  ${c.url}` : "";
-  return `  PR ${pr}  ${c.changeId}  [${c.state ?? "?"}]${url}`;
+  const head = c.headSha ? c.headSha.slice(0, 8) : "(no head)";
+  // A not-built PR: no changeId, so route the operator to build it first.
+  const notBuilt = c.built === false || (!c.changeId && c.status === "not-built");
+  if (notBuilt) {
+    const hint =
+      typeof c.prNumber === "number"
+        ? `  → tot preview build --pr ${c.prNumber}`
+        : "  → tot preview build";
+    return `  PR ${pr}  [not built]  ${head}${hint}`;
+  }
+  const status = c.status ?? "?";
+  const urlPart = c.previewUrl ? `  ${c.previewUrl}` : "";
+  return `  PR ${pr}  [${status}]  ${c.changeId}  ${head}${urlPart}`;
+}
+
+/**
+ * Sort an OPEN candidate queue by PR number DESC (newest PR first); candidates
+ * without a PR number sort last, then stably by changeId. Pure — unit-tested.
+ * @param {ReturnType<typeof normalizeChangesQueue>} changes
+ */
+export function sortQueueByPrDesc(changes) {
+  return [...(changes || [])].sort((a, b) => {
+    const ap = typeof a.prNumber === "number" ? a.prNumber : -Infinity;
+    const bp = typeof b.prNumber === "number" ? b.prNumber : -Infinity;
+    if (ap !== bp) return bp - ap;
+    return String(a.changeId).localeCompare(String(b.changeId));
+  });
+}
+
+/**
+ * The OPERATOR `tot pr list --tenant <t>` flow: fetch the tenant's OPEN candidate
+ * queue over `GET /api/changes` (Bearer operator secret + `X-Tot-Owner` +
+ * `x-tot-capability: ship-on-behalf`, mirroring U16) and print each candidate one per
+ * line, sorted by PR number desc. Fail-closed: no secret → honest refusal (exit 2)
+ * BEFORE any network. `fetch` is injected so it's unit-tested with no live network.
+ *
+ * @param {{ tenant:string, secret:string, storefrontUrl?:string|null }} params
+ * @param {{ fetch?:typeof fetch }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runPrListOperator({ tenant, secret, storefrontUrl = null }, deps = {}) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+
+  if (!secret) {
+    console.error(
+      fail(
+        "listing a tenant's queue is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+
+  const authHeaders = {
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the candidate queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  if (!res.ok) {
+    const msg = data?.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the candidate queue refused the request: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const changes = sortQueueByPrDesc(normalizeChangesQueue(data));
+  if (!changes.length) {
+    console.log(`No open candidate PRs for ${tenant}.`);
+    return 0;
+  }
+  console.log(`Open PRs for ${tenant}:`);
+  for (const c of changes) {
+    console.log(formatOperatorCandidateLine(c));
+  }
+  return 0;
 }
 
 /** @param {string[]} argv @param {any} ctx */
@@ -98,9 +291,34 @@ export async function run(argv, ctx) {
     console.error(fail(`unknown subcommand: \`tot pr ${args.sub}\``, "tot pr list | view <N> | close <N>"));
     return 2;
   }
+
+  // OPERATOR MODE (U17): `--tenant <t>` lists that tenant's OPEN candidate queue with
+  // NO checkout, over the same HTTP transport `tot ship --pr` uses. Only `list` has an
+  // operator path today — `view`/`close` stay developer-only (checkout-bound).
+  if (args.tenant && `${args.tenant}`.trim()) {
+    if (args.sub !== "list") {
+      console.error(
+        fail(
+          `\`tot pr ${args.sub} --tenant\` isn't wired — only \`tot pr list --tenant\` has an operator path`,
+          "use `tot pr list --tenant <t>` to list, then act from a checkout",
+        ),
+      );
+      return 2;
+    }
+    const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+    return await runPrListOperator({
+      tenant: `${args.tenant}`.trim(),
+      secret: resolveOperatorSecret(args.secret, env),
+      storefrontUrl,
+    });
+  }
+
   if (ctx.mode !== "checkout") {
     console.error(
-      fail("`tot pr` runs from inside a tenant checkout", "tot clone <tenant> <dir>   (then `cd` in and re-run)"),
+      fail(
+        "`tot pr` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in and re-run), or `tot pr list --tenant <t>` for operator mode",
+      ),
     );
     return 2;
   }
@@ -127,8 +345,11 @@ export async function run(argv, ctx) {
   }
 
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
   const statePath = defaultCandidateStatePath(env);
-  const scope = { mcpUrl: baseUrl, repo };
+  // Branch-bound (u4): the active-pointer namespace is scoped to the current git
+  // branch, so the "← active" marker reflects THIS branch's candidate.
+  const scope = { mcpUrl: baseUrl, repo, branch: currentBranch(gitSafe) };
   const client = createMcpClient(baseUrl);
   try {
     const session = await establishSession(client, { env, prefer: args.identity || undefined });
@@ -146,7 +367,8 @@ export async function run(argv, ctx) {
       const active = readActiveChangeId(statePath, scope);
       console.log(`Open candidate PRs for ${repo}:`);
       for (const c of candidates) {
-        console.log(line(c) + (active && c.changeId === active ? "  ← active" : ""));
+        const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
+        console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
       }
       return 0;
     }
@@ -165,7 +387,9 @@ export async function run(argv, ctx) {
       if (match.headSha) console.log(`  head:             ${match.headSha}`);
       if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
       console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
-      if (match.url) console.log(`  ${match.url}`);
+      // ONLY the storefront-owned preview link -- never the raw forge/Gitea `url`.
+      const previewUrl = match.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, match.prNumber);
+      if (previewUrl) console.log(`  ${previewUrl}`);
       return 0;
     }
 

package/src/commands/preview-build.mjs

@@ -0,0 +1,225 @@
+/**
+ * `tot preview build --tenant <t> --pr <N>` — OPERATOR build-on-demand (unit U3).
+ *
+ * Materialize ANY PR's hosted preview (including one that isn't yours, and one that
+ * was orphaned — its webhook never processed so it has no ReviewEnvironment). It
+ * calls the session-authenticated storefront endpoint `POST /api/preview/build`
+ * (unit U1), which runs the EXISTING `reconcileCandidate` against the PR head. The
+ * CLI passes the KNOWN descriptor (the head sha it holds), so there is NO forge
+ * PR-read dependency: reconcile reads the tenant files at that sha (content-addressed).
+ *
+ * This is distinct from `tot preview` (the developer's push-your-checkout-to-preview
+ * flow, which talks MCP). `tot preview build` is an OPERATOR verb over a specific
+ * `--tenant`/`--pr`, gated server-side on owner / ship-on-behalf privilege.
+ *
+ * AUTH — the storefront endpoint accepts the headless Bearer-operator-secret path
+ * (`resolveOwnerSession` fallback). This verb sends `Authorization: Bearer <secret>`
+ * (from `PREVIEW_RECONCILE_SECRET` / `GRANTS_ADMIN_SECRET` / `TOT_OPERATOR_SECRET`,
+ * or `--secret`), `X-Tot-Owner: <tenant>`, and `X-Tot-Capability: ship-on-behalf` —
+ * mirroring the `/admin` AdminPublishTab accept call.
+ *
+ * SELF-DECLARING — it prints the EXACT plan (which PR → which tenant → the preview
+ * URL) and confirms before acting (`--yes` to skip; a non-TTY without `--yes`
+ * aborts rather than acting silently). Build-on-demand is INERT — it flips no shared
+ * channel and is not go-live — so this is a materialize, not a deploy. The plan
+ * itself is built by the SHARED plan module (`../plan.mjs`, unit U10) — the same
+ * affordance every other mutating operator verb (accept/ship/retire) and the
+ * `/admin` confirm dialog use, per decision `operator-verb-and-hosting-model`.
+ *
+ * Dependency-free (global fetch + `git` for the optional head-sha default).
+ */
+import { execFileSync } from "node:child_process";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/** Parse `tot preview build` argv. Pure — unit-testable. */
+export function parseBuildArgs(argv) {
+  const a = {
+    tenant: null,
+    pr: null,
+    headSha: null,
+    baseSha: null,
+    changeId: null,
+    url: null,
+    secret: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--head-sha" || t === "--head") a.headSha = argv[++i];
+    else if (t === "--base-sha" || t === "--base") a.baseSha = argv[++i];
+    else if (t === "--change-id") a.changeId = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+export function renderUsage() {
+  return `tot preview build — operator build-on-demand: materialize a PR's hosted preview
+
+Usage:
+  tot preview build --tenant <appDomain> --pr <N> [--head-sha <sha>] [options]
+
+Materializes (or rebuilds) the candidate preview for PR #N of <tenant> by running
+the server-side reconcile. Recovers an orphaned PR (one with no built preview yet).
+It performs NO merge, NO go-live, and flips NO shared channel.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --pr <N>               PR number to build.
+  --head-sha <sha>       PR head commit to materialize. Defaults to \`git rev-parse
+                         HEAD\` when run inside a git checkout.
+  --base-sha <sha>       Optional merge-base (projection metadata only).
+  --change-id <id>       Optional explicit candidate id (defaults to pr-<N>).
+  --url <origin>         Storefront origin. Defaults to $TOT_STOREFRONT_URL or
+                         ${DEFAULT_STOREFRONT_URL}.
+  --secret <s>           Operator secret. Prefer the env vars below.
+  --yes, -y              Skip the confirmation prompt.
+  --help, -h             Show this help.
+
+Auth (operator secret, from env, first found):
+  PREVIEW_RECONCILE_SECRET, GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET`;
+}
+
+/** Best-effort local HEAD sha (only when invoked inside a git checkout). */
+function gitHeadSha() {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const args = parseBuildArgs(argv);
+  if (args.help) {
+    console.log(renderUsage());
+    return 0;
+  }
+
+  const base = (args.url || process.env.TOT_STOREFRONT_URL || process.env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL)
+    .trim()
+    .replace(/\/+$/, "");
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      "✗ no target tenant.\n\n  → next: pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), " +
+        "or run inside a store checkout.",
+    );
+    return 2;
+  }
+
+  const prRaw = args.pr;
+  const pr = prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+  if (pr == null && !args.changeId) {
+    console.error("✗ no PR to build.\n\n  → next: pass --pr <N> (the PR number to materialize).");
+    return 2;
+  }
+
+  const headSha = (args.headSha || gitHeadSha() || "").trim();
+  if (!headSha) {
+    console.error(
+      "✗ no head sha.\n\n  → next: pass --head-sha <sha> (the PR head commit to build), " +
+        "or run inside a checkout of that commit.",
+    );
+    return 2;
+  }
+
+  const secret = (args.secret || process.env.PREVIEW_RECONCILE_SECRET || process.env.GRANTS_ADMIN_SECRET || process.env.TOT_OPERATOR_SECRET || "").trim();
+  if (!secret) {
+    console.error(
+      "✗ no operator secret.\n\n  → next: set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / " +
+        "TOT_OPERATOR_SECRET) in the environment.",
+    );
+    return 2;
+  }
+
+  const previewUrl = pr != null ? `${base}/preview/${encodeURIComponent(tenant)}/pr/${pr}` : null;
+
+  // Self-declaring: state the EXACT plan before acting (the shared plan module).
+  const planLines = planForAction({
+    action: "build",
+    tenant,
+    pr,
+    changeId: args.changeId,
+    headSha,
+    endpoint: `${base}/api/preview/build`,
+    targets: { preview: previewUrl },
+  });
+  const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+    yes: args.yes,
+    question: "Build this preview now?",
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error("✗ refusing to build without confirmation on a non-TTY.\n\n  → next: re-run with --yes.");
+      return 1;
+    }
+    console.log("Aborted — nothing was built.");
+    return 1;
+  }
+
+  const body = {
+    ...(pr != null ? { pr } : {}),
+    ...(args.changeId ? { changeId: args.changeId } : {}),
+    headSha,
+    ...(args.baseSha ? { baseSha: args.baseSha } : {}),
+  };
+
+  let res;
+  try {
+    res = await fetch(`${base}/api/preview/build`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${secret}`,
+        "x-tot-owner": tenant,
+        "x-tot-capability": "ship-on-behalf",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    console.error(`✗ could not reach ${base}: ${e?.message || e}\n\n  → next: check --url / your network.`);
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON error body */
+  }
+
+  const resolvedUrl = data?.previewUrl || data?.environment?.previewUrl || previewUrl || null;
+
+  if (res.ok && data?.ok) {
+    const status = data?.environment?.status || "ready";
+    console.log(`✓ Preview built (status: ${status}).`);
+    if (resolvedUrl) console.log(`\n  ${resolvedUrl}\n`);
+    return 0;
+  }
+
+  // Blocked (422) or an auth/other failure.
+  const errors = Array.isArray(data?.errors) && data.errors.length
+    ? data.errors
+    : [data?.error || `HTTP ${res.status}`];
+  console.error(`✗ Build did not succeed (HTTP ${res.status}).`);
+  for (const e of errors) console.error(`  • ${e}`);
+  if (resolvedUrl && res.status === 422) {
+    console.error(`\n  The PR page will show the reason: ${resolvedUrl}`);
+  }
+  return 1;
+}

package/src/commands/preview.mjs

@@ -0,0 +1,80 @@
+/**
+ * `tot preview` — submit your store for PREVIEW (the deliberate, gated step).
+ *
+ * This is the first-class verb for 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)  ← you are here
+ *   tot ship       promote a reconciled preview live                                     ← unit u3
+ *
+ * The whole preview flow (validate, push the preview ref, open/update the PR-backed
+ * candidate, stream the reconcile/compliance/preview result) lives in submit.mjs — this
+ * module is a thin wrapper that runs that SAME flow and, on success, teaches the next
+ * verb (`tot ship`). Keeping the flow in one place means `tot preview` and its teaching
+ * aliases (`tot submit` / `tot deploy`, below) share exactly one implementation — every
+ * submit flag works identically through preview, with no chance of drift.
+ *
+ * TEACHING ALIASES: `tot submit` and `tot deploy` are the same preview flow. They run it
+ * unchanged and then print a one-line hint teaching the rename (and `tot ship`), so a
+ * developer who reaches for the old verb is nudged onto the new model without losing a
+ * step. Pass `{ alias }` (the verb the developer typed) to get that hint.
+ *
+ * Dependency-free (delegates to submit.mjs, which uses global fetch + `git`).
+ */
+import { run as runPreviewFlow, parseArgs, renderUsage } from "./submit.mjs";
+
+/** The ship hint printed after a successful `tot preview` — teaches the next verb.
+ *  Pure — unit-tested. */
+export const shipHint = () =>
+  "\n  → next: once this preview reconciles cleanly, `tot ship` promotes it live.";
+
+/** The teaching hint printed when the preview flow is reached via an old verb
+ *  (`tot submit` / `tot deploy`). Names the rename AND the ship verb in one line.
+ *  Pure — unit-tested. */
+export const aliasHint = (alias) =>
+  `\n  ℹ \`tot ${alias}\` is now \`tot preview\` — and \`tot ship\` promotes it live.`;
+
+/** The hint to print after the flow returns, or null when there's nothing to teach
+ *  (the flow failed). An alias gets the rename+ship hint; the first-class verb gets
+ *  the ship hint; a non-zero exit teaches nothing (the push didn't land). Pure. */
+export function postRunHint(code, alias) {
+  if (code !== 0) return null;
+  return alias ? aliasHint(alias) : shipHint();
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ * @param {{ alias?: string|null }} [opts] — `alias` is the old verb the developer typed
+ *   (`"submit"` / `"deploy"`) when this flow is reached as a teaching alias; null/omitted
+ *   for the first-class `tot preview`.
+ */
+export async function run(argv, ctx, { alias = null } = {}) {
+  // `tot preview build …` is the OPERATOR build-on-demand subcommand (unit U3) —
+  // a distinct verb from the developer preview flow, so it's dispatched BEFORE the
+  // submit-flow arg parse. Only the first-class `tot preview` carries it (not the
+  // `submit`/`deploy` teaching aliases, which are the push-your-checkout flow).
+  if (!alias && argv[0] === "build") {
+    const { run: runBuild } = await import("./preview-build.mjs");
+    return runBuild(argv.slice(1), ctx);
+  }
+
+  const verb = alias || "preview";
+  const args = parseArgs(argv);
+
+  // Handle --help here so we can brand the usage with the typed verb and, for an
+  // alias, teach the rename — without also printing the post-success ship hint.
+  if (args.help) {
+    console.log(renderUsage(verb));
+    if (alias) console.log(aliasHint(alias));
+    return 0;
+  }
+
+  const code = await runPreviewFlow(argv, ctx, { verb });
+
+  // Teach the next step only on a successful preview (the push landed). An alias
+  // gets the rename+ship hint; the first-class verb just gets the ship hint.
+  const hint = postRunHint(code, alias);
+  if (hint) console.log(hint);
+  return code;
+}