@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.21

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;
+}

package/src/commands/retire.mjs

@@ -0,0 +1,203 @@
+/**
+ * `tot retire --tenant <t> --pr <N>` — OPERATOR retire/GC (unit U7).
+ *
+ * Evict a candidate PR's hosted preview — its `ReviewEnvironment` projection +
+ * its immutable site version — to RECLAIM SPACE. It calls the
+ * session-authenticated storefront endpoint `POST /api/preview/retire` (unit
+ * U7), which deletes the candidate record + prunes the tenant index and evicts
+ * the candidate version (guarded: it refuses any version a channel points at).
+ *
+ * DISTINCT FROM `tot accept` / reject: retire touches NO change lifecycle — the
+ * change stays open. It is REVERSIBLE-BY-REBUILD: because U1 build-on-demand
+ * (`tot preview build`) + the U2 fallback page can rematerialize the PR head on
+ * request, a retired PR degrades to "not built yet", NOT a dead 404.
+ *
+ * IDEMPOTENT — retiring an already-absent candidate is a clean success
+ * (nothing to evict). Unlike `tot preview build`, retire needs NO head sha: it
+ * targets an EXISTING candidate by `--pr` (→ `pr-<N>`) or an explicit
+ * `--change-id`.
+ *
+ * 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 `tot preview build` and the
+ * `/admin` AdminPublishTab retire call.
+ *
+ * SELF-DECLARING — it prints the EXACT plan (which PR → which tenant → evict +
+ * rebuildable) and confirms before acting (`--yes` to skip; a non-TTY without
+ * `--yes` aborts rather than acting silently). Retire is INERT re: shared
+ * channels — it flips no preview/live channel and touches no live pointer — so
+ * this is a teardown, 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 (build/accept/ship) and the `/admin` confirm dialog use, per
+ * decision `operator-verb-and-hosting-model`.
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/** Parse `tot retire` argv. Pure — unit-testable. */
+export function parseRetireArgs(argv) {
+  const a = {
+    tenant: null,
+    pr: 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 === "--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 retire — operator retire/GC: evict a candidate PR's hosted preview
+
+Usage:
+  tot retire --tenant <appDomain> --pr <N> [options]
+  tot retire --tenant <appDomain> --change-id <id> [options]
+
+Evicts the candidate preview for PR #N of <tenant> — its review environment +
+immutable version — to reclaim space. REVERSIBLE: rebuild it any time with
+\`tot preview build\` (the change stays open; this is NOT reject). It flips NO
+shared channel and is NOT go-live.
+
+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 retire (identifies the candidate pr-<N>).
+  --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`;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const args = parseRetireArgs(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;
+  const changeId = (args.changeId || "").trim() || null;
+  if (pr == null && !changeId) {
+    console.error(
+      "✗ no candidate to retire.\n\n  → next: pass --pr <N> (the PR number to retire), or --change-id <id>.",
+    );
+    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;
+  }
+
+  // Self-declaring: state the EXACT plan before acting (the shared plan module).
+  const planLines = planForAction({
+    action: "retire",
+    tenant,
+    pr,
+    changeId,
+    endpoint: `${base}/api/preview/retire`,
+  });
+  const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+    yes: args.yes,
+    question: "Retire this preview now?",
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error("✗ refusing to retire without confirmation on a non-TTY.\n\n  → next: re-run with --yes.");
+      return 1;
+    }
+    console.log("Aborted — nothing was retired.");
+    return 1;
+  }
+
+  const body = {
+    ...(pr != null ? { pr } : {}),
+    ...(changeId ? { changeId } : {}),
+  };
+
+  let res;
+  try {
+    res = await fetch(`${base}/api/preview/retire`, {
+      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 label = pr != null ? `PR #${pr}` : changeId;
+
+  if (res.ok && data?.ok) {
+    if (data.evicted) {
+      console.log(`✓ Retired ${label} for ${tenant} — the preview was evicted (rebuildable on demand).`);
+    } else {
+      console.log(`✓ Retire ${label} for ${tenant}: nothing to evict (already retired).`);
+    }
+    console.log("\n  → rebuild any time: `tot preview build --tenant " + tenant + (pr != null ? " --pr " + pr : "") + "`\n");
+    return 0;
+  }
+
+  // A refusal (e.g. 409 version-pinned) or an auth/other failure.
+  const message = data?.error || `HTTP ${res.status}`;
+  console.error(`✗ Retire did not succeed (HTTP ${res.status}).`);
+  console.error(`  • ${message}`);
+  return 1;
+}