@tokenoftrust/cli 4.11.0 → 4.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "4.11.0",
+  "version": "4.11.2",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/go-live.mjs

@@ -37,13 +37,16 @@ import { fail } from "../errors.mjs";
 import { isInteractive, promptYesNo } from "../prompt.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
+import { formatImageTypes, normalizeImageTypes } from "../image-census.mjs";
+import { DEFAULT_STOREFRONT_ORIGIN, describeIdentity, resolveViewerTransport } from "../viewer-session.mjs";
+import { missingGrantsOf, refusalHint } from "../admission-hint.mjs";
 
 const USAGE = `tot go-live — cut the apex domain over to the storefront
 
   tot go-live                 show apex readiness, then (if ready) connect the apex
   tot go-live --rehearsal     dispatch a DRY-RUN cutover (never moves DNS state)
   tot go-live --rollback      restore the captured prior DNS records (the revert)
-  tot go-live --url <base>    storefront base URL (default: env TOT_STOREFRONT_URL / https://<owner>)
+  tot go-live --url <origin>  storefront origin (default: env TOT_STOREFRONT_URL / ${DEFAULT_STOREFRONT_ORIGIN})
   tot go-live --owner <domain> owner/appDomain to act on (default: env TOT_STOREFRONT_OWNER / checkout tenant)
   tot go-live --no-open       don't open the store in your browser afterward
 
@@ -51,7 +54,11 @@ const USAGE = `tot go-live — cut the apex domain over to the storefront
   same server readiness gate. It ALWAYS shows you the readiness itemization and
   asks for a single y/N confirmation first; a CONNECT is refused unless the server
   reports ready. There is no --yes/--force, and it refuses to run without an
-  interactive terminal. Reversible: \`tot go-live --rollback\`.`;
+  interactive terminal. Reversible: \`tot go-live --rollback\`.
+
+  Authentication: your own \`tot login\` session. The store decides what you may
+  do: the owner reads readiness and cuts over; others see what the store admits.
+  Operators/CI may instead set TOT_STOREFRONT_OPERATOR_TOKEN or PREVIEW_RECONCILE_SECRET.`;
 
 /** Parse `tot go-live` argv. Pure. Deliberately NO --yes/--force (see the header). */
 export function parseGoLiveArgs(argv) {
@@ -111,6 +118,7 @@ export function normalizeReadiness(r) {
       ? rd.blockedReasons.filter((s) => typeof s === "string")
       : checks.filter((c) => !c.ok).map((c) => c.detail),
     appDomain: typeof o.appDomain === "string" ? o.appDomain : null,
+    imageTypes: normalizeImageTypes(o.imageTypes),
     domainState: rd && o.domain && typeof o.domain === "object" ? o.domain : null,
   };
 }
@@ -201,6 +209,10 @@ export function renderReadiness({ appDomain, readiness, action }) {
     if (!c.ok && c.remedy) lines.push(`        → ${c.remedy}`);
   }
   if (action === "connect") {
+    lines.push(
+      "",
+      `  Uncaptured images by type: ${readiness.imageTypes ? formatImageTypes(readiness.imageTypes) : "not recorded for the live bundle"}`,
+    );
     lines.push(
       "",
       readiness.ready
@@ -245,7 +257,9 @@ export async function pollRunTerminal(http, { attempts = 8, delayMs = 2000, slee
  * @param {{ appDomain:string, action:"connect"|"rollback", rehearsal:boolean, noOpen?:boolean,
  *   dnsSetup?: { domainConnectDeclared?: boolean, ciRoleCanChangeZone?: boolean, nameserversAtRegistrar?: boolean } }} params
  * @param {{ interactive?:()=>boolean, confirm?:(q:string,d:boolean)=>Promise<boolean>,
- *   poll?:typeof pollRunTerminal, openUrl?:(u:string)=>boolean, progress?:boolean }} [deps]
+ *   poll?:typeof pollRunTerminal, openUrl?:(u:string)=>boolean, progress?:boolean,
+ *   base?:string|null, identity?:{ account?:string|null, mcp?:string|null }|null }} [deps]
+ *   `base`/`identity` only name where and as whom a failed readiness read was made.
  * @returns {Promise<number>} process exit code
  */
 export async function runGoLive(http, { appDomain, action, rehearsal, noOpen, dnsSetup }, deps = {}) {
@@ -258,12 +272,8 @@ export async function runGoLive(http, { appDomain, action, rehearsal, noOpen, dn
   try {
     readiness = normalizeReadiness(await http.get("/api/domain/readiness"));
   } catch (e) {
-    console.error(
-      fail(
-        `couldn't read apex readiness: ${String(e?.message || e)}`,
-        "check your connection and that the operator token/owner are set, then re-run",
-      ),
-    );
+    const { message, hint } = describeReadinessFailure(e, { base: deps.base ?? null, identity: deps.identity ?? null });
+    console.error(fail(message, hint));
     return 1;
   }
   const domain = appDomain || readiness.appDomain;
@@ -453,21 +463,99 @@ function cap(s) {
 }
 
 /**
- * Build an HTTP client over the storefront apex-domain endpoints. Auth mirrors the
- * headless operator trust boundary the storefront's `resolveOwnerSession` Path 2
- * accepts: a Bearer operator secret + `X-Tot-Owner`, plus the `x-tot-capability`
- * ship floor. Throws on a non-2xx with the server's error message (so the caller
- * surfaces the real refusal). `fetchImpl` is injectable for tests.
+ * Why the readiness read failed, as one `{ message, hint }`. Pure. Reads the HTTP
+ * status and server error code `createStorefrontHttp` attaches; an error without a
+ * status never reached a server, and only that case is a connection problem.
+ * @param {any} e
+ * @param {{ base?: string|null, identity?: { account?: string|null, mcp?: string|null }|null }} [ctx]
+ * @returns {{ message: string, hint: string }}
+ */
+export function describeReadinessFailure(e, { base = null, identity = null } = {}) {
+  const status = typeof e?.status === "number" ? e.status : null;
+  const code = typeof e?.code === "string" ? e.code : null;
+  const where = base ? ` at ${base}` : "";
+  if (status === 404) {
+    return {
+      message: `couldn't read apex readiness${where}: HTTP 404 — that host is not serving this store from the storefront yet (before cutover the domain still points at the old platform)`,
+      hint: `drop --url / TOT_STOREFRONT_URL to use the shared storefront, or pass --url ${DEFAULT_STOREFRONT_ORIGIN}`,
+    };
+  }
+  if (status === 401 || status === 403 || code === "store-not-public") {
+    const who = describeIdentity(identity);
+    const missing = missingGrantsOf(e?.body);
+    return {
+      message: `the store refused the readiness read${where} (${code || `HTTP ${status}`})${who ? ` for ${who}` : ""}`,
+      // The server names what is missing; with nothing named, a refusal here means the
+      // caller is not signed in as someone this store admits.
+      hint: missing.length
+        ? refusalHint(status ?? 401, missing)
+        : "run `tot login` as the store owner (or a developer invited to the store), then re-run",
+    };
+  }
+  if (status !== null) {
+    return {
+      message: `couldn't read apex readiness${where}: ${code || `HTTP ${status}`}`,
+      hint: "retry shortly; if it persists, report it with `tot feedback`",
+    };
+  }
+  return {
+    message: `couldn't reach the storefront${where}: ${String(e?.message || e)}`,
+    hint: "check your connection, then re-run",
+  };
+}
+
+/**
+ * The storefront origin go-live talks to. Pure. The shared storefront serves every
+ * tenant before and after cutover, so it is the default; the apex is never assumed.
+ * A `--url` already scoped to this tenant (`<origin>/<owner>`) names the same store.
+ * @param {{ url?: string|null, envUrl?: string|null, owner: string }} p
+ */
+export function resolveGoLiveOrigin({ url = null, envUrl = null, owner }) {
+  const raw = String(url || envUrl || DEFAULT_STOREFRONT_ORIGIN).trim().replace(/\/+$/, "");
+  const suffix = `/${String(owner || "").trim().toLowerCase()}`;
+  return suffix.length > 1 && raw.toLowerCase().endsWith(suffix) ? raw.slice(0, -suffix.length) : raw;
+}
+
+/**
+ * The transport for the apex-domain endpoints. An operator secret (operators/CI)
+ * keeps the Bearer + `X-Tot-Owner` route on the origin; without one, the caller's own
+ * `tot login` is exchanged for a storefront viewer session on the tenant's base, the
+ * same transport `tot ship` / `tot accept` use. The server's admission decides what
+ * either may do; this only carries the identity.
+ * @param {{ origin: string, owner: string, token?: string|null, env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch, resolveViewer?: typeof resolveViewerTransport }} p
+ * @returns {Promise<{ ok: true, base: string, token: string|null, headers: Record<string,string>,
+ *   identity: { account: string|null, mcp: string|null }|null } | { ok: false, message: string, hint: string }>}
+ */
+export async function resolveGoLiveTransport({
+  origin, owner, token = null, env = process.env, fetchImpl = fetch, resolveViewer = resolveViewerTransport,
+}) {
+  if (token) return { ok: true, base: origin, token, headers: {}, identity: null };
+  const viewer = await resolveViewer({ tenant: owner, env, fetchImpl, storefrontUrl: origin });
+  if (!viewer.ok) return { ok: false, message: viewer.message, hint: viewer.hint };
+  return { ok: true, base: viewer.base, token: null, headers: viewer.authHeaders, identity: viewer.identity };
+}
+
+/**
+ * Build an HTTP client over the storefront apex-domain endpoints. With `token`, it
+ * sends the headless operator trust boundary `resolveOwnerSession` Path 2 accepts:
+ * a Bearer operator secret + `X-Tot-Owner`. `headers` carries a viewer-session
+ * cookie instead. Every request carries the `x-tot-capability` ship floor. Throws on
+ * a non-2xx with the server's error message, plus `status` and `code` (the server's
+ * error code), so the caller can tell a refusal from a missing route.
+ * `fetchImpl` is injectable for tests.
  * @param {string} base
- * @param {{ token?:string, owner?:string, capability?:string, fetchImpl?:typeof fetch }} [auth]
+ * @param {{ token?:string|null, owner?:string, capability?:string, headers?:Record<string,string>,
+ *   fetchImpl?:typeof fetch }} [auth]
  */
-export function createStorefrontHttp(base, { token, owner, capability = "ship-on-behalf", fetchImpl } = {}) {
+export function createStorefrontHttp(base, { token, owner, capability = "ship-on-behalf", headers: extra = {}, fetchImpl } = {}) {
   const root = base.replace(/\/+$/, "");
   const doFetch = fetchImpl || fetch;
   const headers = () => ({
     ...(token ? { authorization: `Bearer ${token}` } : {}),
-    ...(owner ? { "x-tot-owner": owner } : {}),
+    ...(token && owner ? { "x-tot-owner": owner } : {}),
     "x-tot-capability": capability,
+    ...extra,
   });
   const parse = async (res) => {
     const text = await res.text();
@@ -478,9 +566,12 @@ export function createStorefrontHttp(base, { token, owner, capability = "ship-on
       body = null;
     }
     if (!res.ok) {
-      const msg = (body && typeof body === "object" && typeof body.error === "string" && body.error) ||
-        `HTTP ${res.status}`;
-      throw new Error(msg);
+      const code = (body && typeof body === "object" && typeof body.error === "string" && body.error) || null;
+      const err = /** @type {Error & { status?: number, code?: string|null, body?: any }} */ (new Error(code || `HTTP ${res.status}`));
+      err.status = res.status;
+      err.code = code;
+      err.body = body;
+      throw err;
     }
     return body;
   };
@@ -521,9 +612,8 @@ export async function run(argv, ctx) {
     return 2;
   }
 
-  // The owner/appDomain to act on, and the storefront base URL. Owner defaults to
-  // the checkout's tenant (owner == appDomain in this platform); the base URL
-  // defaults to https://<owner> unless overridden.
+  // The owner/appDomain to act on. Owner defaults to the checkout's tenant
+  // (owner == appDomain in this platform).
   const owner = args.owner || env.TOT_STOREFRONT_OWNER || ctx.tenant;
   if (!owner) {
     console.error(
@@ -534,17 +624,24 @@ export async function run(argv, ctx) {
     );
     return 1;
   }
-  const base = args.url || env.TOT_STOREFRONT_URL || `https://${owner}`;
-  const token = env.TOT_STOREFRONT_OPERATOR_TOKEN || env.PREVIEW_RECONCILE_SECRET;
-
-  // The storefront apex-domain endpoints authenticate via the operator token +
-  // X-Tot-Owner (resolveOwnerSession Path 2), NOT the MCP OAuth session — so there
-  // is no MCP sign-in step here. Owner INTENT is enforced by the explicit confirm
-  // below and, authoritatively, by the server's owner-only readiness/dispatch gate.
-  const http = createStorefrontHttp(base, { token, owner });
+  const origin = resolveGoLiveOrigin({ url: args.url, envUrl: env.TOT_STOREFRONT_URL, owner });
+  const transport = await resolveGoLiveTransport({
+    origin,
+    owner,
+    token: env.TOT_STOREFRONT_OPERATOR_TOKEN || env.PREVIEW_RECONCILE_SECRET || null,
+    env,
+  });
+  if (!transport.ok) {
+    console.error(fail(transport.message, transport.hint));
+    return 2;
+  }
+
+  // Owner INTENT is enforced by the explicit confirm in runGoLive and,
+  // authoritatively, by the server's owner-only readiness/dispatch gate.
+  const http = createStorefrontHttp(transport.base, { token: transport.token, owner, headers: transport.headers });
   return await runGoLive(
     http,
     { appDomain: owner, action: /** @type {any} */ (args.action), rehearsal: args.rehearsal, noOpen: args.noOpen },
-    { openUrl: (u) => openBrowser(u) },
+    { openUrl: (u) => openBrowser(u), base: transport.base, identity: transport.identity },
   );
 }

package/src/commands/validate.mjs

@@ -22,6 +22,7 @@ import { join, relative, resolve, sep } from "node:path";
 import { validateTenant, ERROR, WARN, printLoudAdvisories } from "../validate.mjs";
 import { validateVisualParityClosure } from "../visual-parity.mjs";
 import { fail } from "../errors.mjs";
+import { countSourceImages, formatImageTypes } from "../image-census.mjs";
 import { tenantDirSegments } from "../tenant-dirs.mjs";
 import {
   describeOwner, readWorkspaceTopology, rootFilesOwnedByMounts, TOPOLOGY_FILE,
@@ -187,7 +188,7 @@ export function run(argv, ctx) {
   const { ok, findings } = result;
 
   if (args.json) {
-    console.log(JSON.stringify({ ok, findings }, null, 2));
+    console.log(JSON.stringify({ ok, findings, imageCensus: countSourceImages(dir) }, null, 2));
     return ok ? 0 : 1;
   }
 
@@ -210,6 +211,9 @@ export function run(argv, ctx) {
     console.log(`  ${tag} [${f.rule}] ${f.file}\n      ${f.message}${f.fix ? `\n      → ${f.fix}` : ""}`);
   }
   if (findings.length === 0) console.log("  (no findings)");
+  // Informational, never a finding: the repo keeps source URLs and the publish captures them. A
+  // non-zero type is what `tot go-live` will still block on until a publish has captured it.
+  console.log(`\n  Uncaptured images by type: ${formatImageTypes(countSourceImages(dir))}`);
   console.log(`\n${errors.length === 0 ? "✔" : "✖"} ${errors.length} error(s), ${warns.length} warning(s).\n`);
   return errors.length === 0 ? 0 : 1;
 }

package/src/image-census.mjs

@@ -0,0 +1,86 @@
+/**
+ * The local image census behind `tot validate`, and the one-line format `tot go-live` shares.
+ *
+ * The repo keeps source URLs by design; the publish captures every image into the platform pool.
+ * This counts, without a network or a publish, the source-hosted image references capture will
+ * still have to pull, by type: catalog, blog, pages, other. It is an estimate of the same quantity
+ * the publish census measures (`scripts/publish/lib/captured-image-rewrite.mjs`); the type rule is
+ * the same and a test pins the two together. Dependency-free.
+ */
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const IMAGE_TYPES = ["catalog", "blog", "pages", "other"];
+const TEXT = /\.(?:html?|css|json)$/i;
+const MAX_TEXT = 1_500_000;
+const PAGES_PREFIXES = ["content/pages/", "content/pages-html/"];
+const REMOTE_URL = /https?:\/\/[^\s"'<>()\\,]+/gi;
+const IMAGE_PATH = /\.(?:jpe?g|png|gif|webp|avif|svg|ico|bmp|tiff?)$/i;
+
+/** @param {string} path @returns {"catalog"|"blog"|"pages"|"other"} */
+export function imageTypeOf(path) {
+  if (path.startsWith("content/catalog/")) return "catalog";
+  if (path.startsWith("content/blog/")) return "blog";
+  if (PAGES_PREFIXES.some((prefix) => path.startsWith(prefix))) return "pages";
+  return "other";
+}
+
+/** Whether `candidate` names a remote image: an image file extension, or a Shopify files path. */
+function isRemoteImage(candidate) {
+  let url;
+  try { url = new URL(candidate); } catch { return false; }
+  return IMAGE_PATH.test(url.pathname) || /(?:^|\.)cdn\.shopify\.com$/i.test(url.hostname) && url.pathname.includes("/files/");
+}
+
+/**
+ * Source-hosted image references under `content/`, `public/` and `theme.json`, by type. A file over
+ * the byte cap counts as one uncaptured reference, as the publish census counts it.
+ * @param {string} dir the tenant checkout
+ * @returns {Record<"catalog"|"blog"|"pages"|"other", {files: number, references: number, uncaptured: number}>}
+ */
+export function countSourceImages(dir) {
+  const out = Object.fromEntries(IMAGE_TYPES.map((type) => [type, { files: 0, references: 0, uncaptured: 0 }]));
+  /** @param {string} rel */
+  const visit = (rel) => {
+    const absolute = join(dir, rel);
+    const stat = lstatSync(absolute, { throwIfNoEntry: false });
+    if (!stat || stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) {
+      for (const name of readdirSync(absolute).sort()) visit(rel ? `${rel}/${name}` : name);
+      return;
+    }
+    if (!stat.isFile() || !TEXT.test(rel)) return;
+    const bucket = out[imageTypeOf(rel)];
+    bucket.files += 1;
+    if (stat.size > MAX_TEXT) { bucket.references += 1; bucket.uncaptured += 1; return; }
+    const found = (readFileSync(absolute, "utf8").match(REMOTE_URL) ?? []).filter(isRemoteImage).length;
+    bucket.references += found;
+    bucket.uncaptured += found;
+  };
+  visit("content");
+  visit("public");
+  visit("theme.json");
+  return /** @type {any} */ (out);
+}
+
+/** `catalog 0, blog 3, pages 1, other 0` */
+export function formatImageTypes(types) {
+  return IMAGE_TYPES.map((type) => `${type} ${types[type].uncaptured}`).join(", ");
+}
+
+/**
+ * A per-type census from untrusted JSON (a server response): every type must carry non-negative
+ * integer counts, or the whole thing is null — nothing is invented for a missing type.
+ * @param {unknown} raw
+ */
+export function normalizeImageTypes(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const out = {};
+  for (const type of IMAGE_TYPES) {
+    const c = /** @type {any} */ (raw)[type];
+    const counts = [c?.files, c?.references, c?.uncaptured];
+    if (!counts.every((n) => Number.isSafeInteger(n) && n >= 0)) return null;
+    out[type] = { files: c.files, references: c.references, uncaptured: c.uncaptured };
+  }
+  return out;
+}