@tokenoftrust/cli 1.4.0 → 1.5.0

package/src/validate.mjs

@@ -27,6 +27,38 @@ function mk(level, rule, file, message, fix) {
   return { level, rule, file, message, fix };
 }
 
+// --- git conflict markers ----------------------------------------------------
+// A half-resolved merge/rebase can commit literal conflict markers into content
+// (the incident: `<<<<<<<`/`=======`/`>>>>>>>` in content/home.html slipped past
+// preview as "validated"). These are the default and diff3 marker lines, anchored
+// at line start and exactly 7 chars with a trailing boundary — precise enough that
+// real content never matches. `=======` / `|||||||` ALONE are NOT flagged (a lone
+// `=======` is a common markdown/prose horizontal rule); only the START (`<<<<<<<`)
+// and END (`>>>>>>>`) markers trigger — either one is a near-certain conflict, so
+// we err false-negative-averse and flag on either.
+const CONFLICT_START = /^<{7}(?=[ \t]|$)/;
+const CONFLICT_END = /^>{7}(?=[ \t]|$)/;
+
+/**
+ * Line numbers (1-based) of git conflict markers in `content`. Empty ⇒ none.
+ * Pure — exported for focused testing.
+ * @param {string} content
+ * @returns {number[]}
+ */
+export function detectConflictMarkers(content) {
+  if (typeof content !== "string" || (!content.includes("<<<<<<<") && !content.includes(">>>>>>>"))) return [];
+  const lines = content.split(/\r?\n/);
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (CONFLICT_START.test(lines[i]) || CONFLICT_END.test(lines[i])) hits.push(i + 1);
+  }
+  return hits;
+}
+
+// Text artifacts a conflict marker can hide in (images/fonts live in public/, not scanned).
+const CONFLICT_SCAN_EXT = new Set([".html", ".htm", ".json", ".md", ".txt", ".css", ".js", ".mjs", ".svg", ".xml"]);
+const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])[0].toLowerCase());
+
 // --- canonical `.tot/config.json` shape (the #24/#25 regression guard) --------
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
@@ -98,31 +130,110 @@ function validateRawHtmlBody(html) {
   if (!html.includes("<")) return "no markup tags found";
   return null;
 }
+// Compact structural mirror of @tot/public-runtime chrome.ts's `ChromeConfig`
+// shape — the consolidated header/footer schema (retired both the old lean
+// `SiteChrome` and the `sharedChrome: true`-gated `TenantChrome`). This is
+// NOT a full validateChromeConfig() pass — deep per-item errors (a nav item
+// missing its `id`, an invalid header `variant`, ...) are the write-path's
+// job (packages/private-controlplane/src/customization-chrome.ts, which does
+// call the real validateChromeConfig()); this only decides whether the
+// tenant's chrome.json looks enough like a ChromeConfig to opt the tenant
+// into shared chrome for the html-fragment check below. The published `tot`
+// CLI bundle can't reach the repo's public-runtime package at runtime (same
+// constraint as the KNOWN_EMBEDS mirror above), so this is a copy — parity
+// test: packages/public-runtime/tests/chrome-config-shape-parity.test.ts.
+const CHROME_HEADER_VARIANTS = new Set(["primary", "minimal"]);
+const CHROME_FOOTER_VARIANTS = new Set(["default"]);
+export function looksLikeChromeConfig(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+  const header = value.header;
+  if (header == null || typeof header !== "object" || Array.isArray(header)) return false;
+  if (!CHROME_HEADER_VARIANTS.has(header.variant)) return false;
+  const brand = header.brand;
+  if (brand == null || typeof brand !== "object" || typeof brand.label !== "string" || brand.label.trim() === "") return false;
+  if (!Array.isArray(header.nav)) return false;
+  const footer = value.footer;
+  if (footer == null || typeof footer !== "object" || Array.isArray(footer)) return false;
+  if (!CHROME_FOOTER_VARIANTS.has(footer.variant)) return false;
+  if (!Array.isArray(footer.columns)) return false;
+  return true;
+}
+
 /**
- * Does the tenant provide chrome to wrap body-only fragments? True when it ships
- * EITHER a hand-authored `content/chrome.html`, OR a `content/chrome.json` that
- * opts into the canonical shared chrome. Mirrors the serve-time resolution in
- * apps/storefront getChromeHtml() → parseChromeConfig(): an opted-in config is
- * rendered into the wrapper (renderRawChrome), so a fragment is NOT served naked.
- * Kept in step with lib/chrome/parseConfig.ts's opt-in gate.
+ * Does the tenant provide chrome to wrap body-only fragments? True when it
+ * ships EITHER a hand-authored `content/chrome.html`, OR a `content/chrome.json`
+ * that looks like a consolidated `ChromeConfig` (see {@link looksLikeChromeConfig}).
+ * Mirrors the serve-time resolution in apps/storefront getChromeHtml() →
+ * parseChromeConfig(): a config that parses is rendered into the wrapper
+ * (renderRawChrome), so a fragment is NOT served naked.
  */
 function providesChrome(contentDir) {
   if (existsSync(join(contentDir, "chrome.html"))) return true;
   const configPath = join(contentDir, "chrome.json");
   if (!existsSync(configPath)) return false;
   const { value } = readJsonSafe(configPath);
-  if (value == null || typeof value !== "object") return false;
-  if (value.sharedChrome !== true) return false;
-  const brand = value.brand;
-  if (brand == null || typeof brand !== "object" || typeof brand.label !== "string") return false;
-  if (!Array.isArray(value.nav)) return false;
-  const footer = value.footer;
-  if (footer == null || typeof footer !== "object" || !Array.isArray(footer.columns)) return false;
-  return true;
+  return looksLikeChromeConfig(value);
 }
 
 const CAPABILITY_KEYS = new Set(["cartCheckout", "ageVerification", "exciseTax"]);
 
+// Compact mirror of EMBED_PROVIDERS (packages/public-runtime/src/embed-catalog.mjs)
+// for the embed-CSP shift-left scan. The published `tot` CLI bundle can't reach
+// the repo's public-runtime package at runtime, so this is a copy — but a parity
+// test (packages/public-runtime/tests/embed-catalog-parity.test.ts) pins it to
+// the shared source so it can't silently drift. markers = substrings meaning the
+// embed is on the page; origins = the exact hosts it needs.
+export const KNOWN_EMBEDS = [
+  {
+    slug: "pipedrive",
+    label: "Pipedrive Web Forms",
+    markers: ["webforms.pipedrive.com", "pipedriveWebForms"],
+    origins: ["https://webforms.pipedrive.com"],
+  },
+];
+const KNOWN_EMBED_SLUGS = new Set(KNOWN_EMBEDS.map((p) => p.slug));
+const EMBED_ALWAYS_ALLOWED = new Set(["static.cloudflareinsights.com", "cloudflareinsights.com"]);
+const EMBED_SRC_RE = /<(?:script|iframe)\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi;
+
+/** Classify one HTML doc: which known providers + unknown external src origins. */
+function scanHtmlForEmbeds(html) {
+  const knownSlugs = KNOWN_EMBEDS.filter((p) => p.markers.some((m) => html.includes(m))).map((p) => p.slug);
+  const catalogOrigins = new Set(KNOWN_EMBEDS.flatMap((p) => p.origins));
+  const unknown = new Set();
+  EMBED_SRC_RE.lastIndex = 0;
+  let m;
+  while ((m = EMBED_SRC_RE.exec(html))) {
+    let origin;
+    try {
+      origin = new URL(m[1]).origin;
+    } catch {
+      continue;
+    }
+    const host = new URL(origin).hostname;
+    if (EMBED_ALWAYS_ALLOWED.has(host) || catalogOrigins.has(origin)) continue;
+    unknown.add(origin);
+  }
+  return { knownSlugs, unknownOrigins: [...unknown] };
+}
+
+function validateEmbedsDoc(doc, file) {
+  // embeds.json: the tenant's self-serve third-party embed opt-in — a JSON array
+  // of catalogued provider slugs (e.g. ["pipedrive"]). Unknown slug = WARNING
+  // (resolveEffectiveEmbeds drops it, so it's inert, not dangerous).
+  if (!Array.isArray(doc)) {
+    return [mk(ERROR, "embeds-root", file, 'embeds.json must be a JSON array of provider slugs, e.g. ["pipedrive"]')];
+  }
+  const out = [];
+  for (const slug of doc) {
+    if (typeof slug !== "string") {
+      out.push(mk(ERROR, "embeds-shape", file, `every entry must be a string slug; got ${typeof slug}`));
+    } else if (!KNOWN_EMBED_SLUGS.has(slug)) {
+      out.push(mk(WARN, "embed-unknown", file, `"${slug}" is not a known embed provider — it will be ignored (the CSP will still block that embed). Known: ${[...KNOWN_EMBED_SLUGS].join(", ")}.`));
+    }
+  }
+  return out;
+}
+
 function complianceObligations(config) {
   const compliance = config?.compliance || {};
   return {
@@ -481,6 +592,16 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  const embedsPath = join(tenantDir, "embeds.json");
+  if (existsSync(embedsPath)) {
+    const { value, error } = readJsonSafe(embedsPath);
+    if (error) {
+      findings.push(mk(ERROR, "embeds-parse", "embeds.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateEmbedsDoc(value, "embeds.json"));
+    }
+  }
+
   // 3. content JSON — parse + blocks shape
   for (const name of ["home.json", "chrome.json"]) {
     const p = join(contentDir, name);
@@ -519,7 +640,7 @@ export function validateTenant(tenantDir, opts = {}) {
       findings.push(
         mk(ERROR, "html-fragment", r,
           "is an HTML fragment but the tenant ships no chrome to wrap it — it will serve unwrapped/naked",
-          "make it a full <!doctype html> document, add a content/chrome.json with \"sharedChrome\": true (brand + nav + footer), or add content/chrome.html with <!--PAGE_BODY-->"),
+          "make it a full <!doctype html> document, add a content/chrome.json with header.variant/header.brand.label/header.nav and footer.variant/footer.columns, or add content/chrome.html with <!--PAGE_BODY-->"),
       );
     }
     if (STYLE_OPEN_WITH_ATTRS_RE.test(html)) {
@@ -539,6 +660,53 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // 5. git conflict markers — advisory (never blocks), but LOUD: a half-resolved
+  // merge/rebase must not slip past as "validated". Scans text artifacts under
+  // content/ plus the root config files.
+  const conflictScanFiles = [
+    ...walk(contentDir, hasScanExt),
+    ...["theme.json", "capabilities.json", "scripts.json", join(".tot", "config.json")]
+      .map((f) => join(tenantDir, f))
+      .filter((p) => existsSync(p)),
+  ];
+  for (const p of conflictScanFiles) {
+    const lines = detectConflictMarkers(readFileSync(p, "utf8"));
+    if (lines.length) {
+      findings.push(
+        mk(WARN, "git-conflict-markers", rel(p),
+          `git conflict markers at line(s) ${lines.join(", ")} — looks like an unfinished merge/rebase (the page would still build/serve broken)`,
+          "resolve the conflict and remove the <<<<<<< / ======= / >>>>>>> lines before submitting"),
+      );
+    }
+  }
+
+  // Embed CSP shift-left: warn (in the dev loop) about third-party embeds that
+  // the strict CSP will silently block, instead of leaving a blank spot. A known
+  // provider not opted into embeds.json, or an unknown external <script>/<iframe>
+  // origin, is blocking; advisory (info) when there's no embeds.json to compare.
+  {
+    let declaredEmbeds = null;
+    const embedsFile = join(tenantDir, "embeds.json");
+    if (existsSync(embedsFile)) {
+      const { value } = readJsonSafe(embedsFile);
+      if (Array.isArray(value)) declaredEmbeds = new Set(value.filter((s) => typeof s === "string"));
+    }
+    for (const file of walk(contentDir, (p) => p.endsWith(".html"))) {
+      const { knownSlugs, unknownOrigins } = scanHtmlForEmbeds(readFileSync(file, "utf8"));
+      for (const slug of knownSlugs) {
+        const label = KNOWN_EMBEDS.find((p) => p.slug === slug)?.label ?? slug;
+        if (declaredEmbeds && !declaredEmbeds.has(slug)) {
+          findings.push(mk(ERROR, "embed-csp", rel(file), `embeds ${label} but "${slug}" is not in embeds.json — the CSP will block it. Add "${slug}" to embeds.json.`));
+        } else if (!declaredEmbeds) {
+          findings.push(mk("info", "embed-csp", rel(file), `embeds ${label}: ensure "${slug}" is in embeds.json, or the CSP will block it.`));
+        }
+      }
+      for (const origin of unknownOrigins) {
+        findings.push(mk(ERROR, "embed-csp", rel(file), `embeds ${origin}, which is not a known embed provider — the CSP will block it. Needs a platform catalog entry, or remove the embed.`));
+      }
+    }
+  }
+
   const ok = !findings.some((f) => f.level === ERROR);
   return { ok, findings };
 }
@@ -555,6 +723,10 @@ function buildPageTargetSet(contentDir, pagesDir) {
   return set;
 }
 
+/**
+ * @param {any} href @param {any} file @param {any} scope @param {any} pageTargets
+ * @param {(path: string) => boolean} [ownsPlatformRoute]
+ */
 function checkLink(href, file, scope, pageTargets, ownsPlatformRoute = () => false) {
   const out = [];
   if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;

package/src/vendor/private-apps-devkit.mjs

@@ -1,7 +1,7 @@
 /**
- * Vendored subset of `@tokenoftrust/private-apps-devkit` (PrivateApps epic D6
- * Chunk B, `packages/private-apps-devkit/src/{signing,jwt,manifest}.ts`) — for
- * `tot app` (D6 Chunk C+D) to sign/verify webhook deliveries, mint dev JWTs,
+ * Vendored subset of `@tokenoftrust/private-apps-devkit` (PrivateApps epic,
+ * `packages/private-apps-devkit/src/{signing,jwt,manifest}.ts`) — for
+ * `tot app` to sign/verify webhook deliveries, mint dev JWTs,
  * and validate `tot-app.json` manifests WITHOUT a package.json dependency on
  * that package.
  *

package/src/viewer-session.mjs

@@ -0,0 +1,118 @@
+/**
+ * Viewer-session transport for the ship surface — the NO-operator-secret path.
+ *
+ * An invited developer holds a `tot login` MCP session but no operator secret and no
+ * storefront cookie, so the old ship-surface transport dead-ended on them. This mints
+ * a storefront VIEWER session from the developer's OWN MCP token (POST
+ * /api/dev/cli-session on the tenant's own host, which resolves WHO the opaque token
+ * is via the MCP and hands back a `tot_session` cookie), then hands the caller a
+ * cookie-based transport pointed at the tenant host. Authorization is still the
+ * developer's live `ship-on-behalf` grant, enforced server-side at the ship route —
+ * this only carries their identity, it grants nothing.
+ *
+ * Minted FRESH per call (no disk cache): a `tot accept` is interactive + infrequent,
+ * and minting-per-call means a revoked session/grant is never honored past its life.
+ */
+import { resolveDeveloperSession, AuthUnavailableError } from "./auth.mjs";
+
+const SESSION_COOKIE = "tot_session";
+
+/** The tenant's own storefront host — the dev-viewer admission derives the tenant
+ *  from the request host, so the session + integrate MUST target it (not the generic
+ *  storefront origin + X-Tot-Owner, which only steers the operator-secret path). */
+function tenantBase(tenant) {
+  return `https://${String(tenant || "").trim().toLowerCase()}`;
+}
+
+/** Pull `tot_session=<id>` out of a (possibly comma-folded) Set-Cookie header. The
+ *  id is base64url — no comma/semicolon — so a non-greedy stop-set is unambiguous. */
+export function parseSessionCookie(setCookie) {
+  if (!setCookie) return null;
+  const m = new RegExp(`${SESSION_COOKIE}=([^;,\\s]+)`).exec(setCookie);
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve a viewer-session transport for `tenant`. Returns
+ *   { ok:true, base, authHeaders }               — base = tenant host; cookie transport
+ *   { ok:false, message, hint }                  — a clean, actionable refusal
+ * Never throws.
+ *
+ * @param {{ tenant:string, env?:NodeJS.ProcessEnv, fetchImpl?:typeof fetch,
+ *   resolveDev?:typeof resolveDeveloperSession }} params
+ * @returns {Promise<
+ *   { ok:true, base:string, authHeaders:Record<string,string> } |
+ *   { ok:false, message:string, hint:string }
+ * >}
+ */
+export async function resolveViewerTransport({
+  tenant,
+  env = process.env,
+  fetchImpl = fetch,
+  resolveDev = resolveDeveloperSession,
+}) {
+  // The developer's OWN MCP token (read + silently refreshed by the resolver). No
+  // client needed — resolveDeveloperSession tolerates a null client.
+  let dev;
+  try {
+    dev = await resolveDev(null, env, { fetchImpl });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      return { ok: false, message: e.message, hint: e.hint || "run `tot login`, then re-run." };
+    }
+    return {
+      ok: false,
+      message: `couldn't read your Token of Trust session: ${e?.message || e}`,
+      hint: "run `tot login`, then re-run.",
+    };
+  }
+
+  const base = tenantBase(tenant);
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/dev/cli-session`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${dev.token}` },
+    });
+  } catch (e) {
+    return {
+      ok: false,
+      message: `couldn't reach ${base} to start a session: ${e?.message || e}`,
+      hint: "check the --tenant domain / your network, then re-run.",
+    };
+  }
+  if (res.status === 401) {
+    return {
+      ok: false,
+      message: "your `tot` session wasn't recognized for this store.",
+      hint: "run `tot login`, then re-run.",
+    };
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      message: `couldn't start a session at ${base} (HTTP ${res.status}).`,
+      hint: "retry shortly; if it persists, this store may not be set up for CLI publishing yet.",
+    };
+  }
+
+  const cookie = parseSessionCookie(res.headers.get("set-cookie"));
+  if (!cookie) {
+    return {
+      ok: false,
+      message: "the store started a session but returned no session cookie.",
+      hint: "re-run; if it persists, report it via `tot` feedback.",
+    };
+  }
+
+  return {
+    ok: true,
+    base,
+    authHeaders: {
+      cookie: `${SESSION_COOKIE}=${cookie}`,
+      // Matches the admin browser client; the server IGNORES this hint and re-reads
+      // the live ship-on-behalf grant, so it authorizes nothing on its own.
+      "x-tot-capability": "ship-on-behalf",
+    },
+  };
+}

package/template/private-app/README.md

@@ -1,17 +1,22 @@
 # my-app
 
-A Storefront Private App, scaffolded by `tot app scaffold`. See
-[the Private Apps devbook](https://github.com/tokenoftrust/storefront/blob/main/docs/private-apps/devbook/private-apps-devbook.md)
-for the full contract this manifest and receiver implement.
+A Storefront Private App, scaffolded by `tot app scaffold`. Start with the
+[public Storefront Devkit Apps / Private track](https://github.com/tokenoftrust/storefront-devkit/tree/main/apps/private)
+for the canonical contract this manifest and receiver implement. The Devkit's
+root [`README.md`](https://github.com/tokenoftrust/storefront-devkit/blob/main/README.md),
+[`AGENTS.md`](https://github.com/tokenoftrust/storefront-devkit/blob/main/AGENTS.md), and
+[`manifest.json`](https://github.com/tokenoftrust/storefront-devkit/blob/main/manifest.json)
+are the stable human and LLM entry points.
 
 ## What's here
 
 - **`tot-app.json`** — your app's manifest: identity, scopes, webhook
   subscriptions, widgets. Validated against
-  [`tot-app.schema.json`](https://github.com/tokenoftrust/storefront/blob/main/docs/private-apps/contract/tot-app.schema.json).
+  [`tot-app.schema.json`](https://github.com/tokenoftrust/storefront-devkit/blob/main/apps/private/contract/tot-app.schema.json).
   Everything here is a PLACEHOLDER — edit `id`, `owner`, `webhooks.endpoint`,
   and `scopes` for your real app before you install it anywhere.
-- **`fixtures/`** — sample CloudEvents (from `docs/private-apps/contract/examples/`)
+- **`fixtures/`** — sample CloudEvents (from the Devkit's
+  [`apps/private/contract/examples/`](https://github.com/tokenoftrust/storefront-devkit/tree/main/apps/private/contract/examples/))
   you can sign and deliver to your own receiver locally, before you have a
   real install. Add one fixture per topic you subscribe to.
 - **`server.js`** — a minimal Node HTTP receiver for `webhooks.endpoint`. It
@@ -42,4 +47,5 @@ for the full command surface.
 2. Get your manifest installed for a real `(tenant, env)` — this issues your
    real client credentials; nothing above touches them.
 3. Swap the dev-only signature verification for the real gateway's published
-   JWKS/signing-key metadata (see the devbook's Signature Verification section).
+   JWKS/signing-key metadata (see the Devkit's
+   [`webhooks-and-api.md`](https://github.com/tokenoftrust/storefront-devkit/blob/main/apps/private/webhooks-and-api.md)).

package/src/commands/retire.mjs

@@ -1,203 +0,0 @@
-/**
- * `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;
-}