@tokenoftrust/cli 2.0.8 → 2.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "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/dev.mjs

@@ -59,7 +59,7 @@ const DEFAULT_DEV_IMAGE =
   "242086487598.dkr.ecr.us-east-1.amazonaws.com/tot-dev:latest";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 /** Where downloaded+installed renderer-artifact versions are cached, one dir per version. */
-const RENDERER_CACHE_ROOT = join(homedir(), ".tot", "cache", "renderer");
+export const RENDERER_CACHE_ROOT = join(homedir(), ".tot", "cache", "renderer");
 /** The PUBLIC, un-entitled runner published to npm (sample / zero-login mode). */
 const PUBLIC_RUNNER_PACKAGE = "@tokenoftrust/storefront-runner";
 const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
@@ -804,6 +804,31 @@ export function rendererCacheHealthy(runnerDir, { platform = process.platform, a
   }
 }
 
+/**
+ * True unless the installed runner package is missing source the Astro config
+ * chain needs to even boot — the "renderer resolves but `tot dev` can't load
+ * its Astro config" failure mode (fb-1788659971983-kdpj1i: `1.4.2-rc.0` was
+ * packed without `scripts/tenant/`, which `apps/storefront/integrations/
+ * materialize-guard.mjs` and `apps/storefront/dev-plugins/tenant-hot-reload.mjs`
+ * import — both loaded from `astro.config.mjs`). A tarball packing a subset of
+ * the tree is a packaging defect a developer can't fix locally, so this is
+ * checked the same way as `rendererCacheHealthy`: on every cache hit AND right
+ * after a fresh install, never trusted forever once cached. Never throws; on
+ * any probe error it returns true (trust the cache) so the probe itself can't
+ * break `tot dev`.
+ */
+export function rendererArtifactComplete(runnerDir) {
+  try {
+    return (
+      existsSync(join(runnerDir, "apps/storefront/astro.config.mjs")) &&
+      existsSync(join(runnerDir, "scripts/tenant")) &&
+      readdirSync(join(runnerDir, "scripts/tenant")).length > 0
+    );
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Delete every OTHER public-runner cache dir (`public-*` except `keepVersion`)
  * once we've resolved the version this CLI pins to — so a pre-alignment dir
@@ -1046,7 +1071,15 @@ export async function installRunnerTarball(
 
   const cached = readCacheMarker(runnerDir);
   if (cached) {
-    if (!rendererCacheHealthy(runnerDir)) {
+    if (!rendererArtifactComplete(runnerDir)) {
+      // The PACKAGE itself is missing source its own Astro config chain needs
+      // (fb-1788659971983-kdpj1i) — re-downloading the SAME version reproduces
+      // the same incomplete tarball, so this can't self-heal like the transient
+      // cases below. Fall through anyway (uniform code path); the post-install
+      // check further down turns the reproduced failure into a loud, actionable
+      // error instead of silently caching the broken tree again.
+      log(`~ store preview engine ${version} is missing files its own Astro config needs — rebuilding it…`);
+    } else if (!rendererCacheHealthy(runnerDir)) {
       // A cache poisoned with the wrong-arch binaries (npm/cli#4828 — e.g.
       // darwin-x64 on an arm64 Mac) is otherwise trusted forever, and astro
       // crashes at boot with `Cannot find native binding`, swallowed as "the dev
@@ -1100,6 +1133,25 @@ export async function installRunnerTarball(
       rmSync(stagingDir, { recursive: true, force: true });
       mkdirSync(stagingDir, { recursive: true });
       extractTarball(archivePath, stagingDir, { strip });
+      // Fail fast, BEFORE the slow pnpm install, when the package itself is
+      // missing source its own Astro config chain needs (fb-1788659971983-kdpj1i:
+      // a runner published with an incomplete `files`/packing list — e.g.
+      // `scripts/tenant/` absent from a tarball that ships integrations
+      // importing it). This is a packaging defect in the published artifact
+      // itself, so it can't self-heal by retrying and is marked permanent —
+      // the actionable remedy is pinning a different (working) runner version.
+      if (!rendererArtifactComplete(stagingDir)) {
+        await emitObstacle("renderer-artifact-incomplete");
+        const err = new CliError(
+          `the store preview engine ${version} is missing files its own Astro config needs (this is a broken published runner, not something on your machine)`,
+          {
+            next: `pin a known-good runner: tot dev --renderer-version <version> (or TOT_RUNNER_VERSION=<version>), and file feedback naming ${version} as broken`,
+            exitCode: 2,
+          },
+        );
+        /** @type {any} */ (err).permanent = true;
+        throw err;
+      }
       // Pin the runner install to PUBLIC npm. The moat-free runner has only public
       // deps, but the HOST's global ~/.npmrc may point `registry` at a private
       // mirror (an internal proxy that 502s, or one an invited developer can't

package/src/commands/doctor.mjs

@@ -19,14 +19,14 @@
  * in the checks list with its usual next command.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { hasLegacyOperatorEnv, legacyOperatorEnvAdvisory } from "../auth.mjs";
 import { MIN_NODE, nodeMeetsFloor } from "../ensure-node.mjs";
 import { clientPackages, osLabel } from "../mcp.mjs";
 import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
-import { dockerAvailable, tryStartDocker } from "./dev.mjs";
+import { dockerAvailable, tryStartDocker, RENDERER_CACHE_ROOT, rendererArtifactComplete } from "./dev.mjs";
 import { loginAndCache } from "./login.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -102,6 +102,33 @@ export function collectChecks(_ctx, env = process.env) {
     blocking: false,
   });
 
+  // Inspect any ALREADY-CACHED preview engine(s) for completeness — a version
+  // whose published tarball was packed without source its own Astro config
+  // needs (fb-1788659971983-kdpj1i) leaves `tot dev` unable to boot even
+  // though every check above passes. This stays a filesystem stat, never a
+  // spawn (`tot doctor` never runs the runner) — it just reads what's already
+  // on disk, so it can only ever report on a version this developer has
+  // already hit, not pre-flight one that hasn't been resolved/installed yet.
+  try {
+    const cacheRoot = RENDERER_CACHE_ROOT;
+    const cachedVersions = existsSync(cacheRoot)
+      ? readdirSync(cacheRoot).filter(
+          (name) => !name.endsWith(".install.log") && !name.includes(".staging-") && existsSync(join(cacheRoot, name, "package.json")),
+        )
+      : [];
+    const broken = cachedVersions.filter((v) => !rendererArtifactComplete(join(cacheRoot, v)));
+    if (broken.length) {
+      checks.push({
+        name: "cached preview engine",
+        pass: false,
+        detail: `${broken.join(", ")} — missing files its own Astro config needs (broken published runner); pin a different one: tot dev --renderer-version <version>`,
+        blocking: false,
+      });
+    }
+  } catch {
+    /* best-effort — never fail doctor on a cache-inspection error */
+  }
+
   const mcpUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   checks.push({
     name: "MCP endpoint",

package/src/commands/submit.mjs

@@ -1154,7 +1154,7 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  * Defaults to null when no numeric PR number was known at result-build time.
  * Pure — unit-tested.
  * @param {{ ok: boolean, ref?: string|null, commit?: string|null, changeId?: string|null,
- *   candidate?: {prNumber?: number, number?: number, state?: string, url?: string}|null,
+ *   candidate?: {prNumber?: number, number?: number, state?: string, url?: string, headSha?: string|null}|null,
  *   status?: {status?: string, reconcile?: object|null, compliance?: object|null,
  *     previewUrl?: string|null, shipped?: object|null, dispatched?: boolean|null,
  *     notDispatched?: boolean, delivery?: object|null}|null,
@@ -1165,6 +1165,10 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     ok,
     ref,
     commit,
+    // The sha the `status`/`reconcile`/`compliance` fields above are reported against —
+    // the candidate head when the candidate names one, else the local `commit`. Kept
+    // beside `commit` rather than replacing it so automation can tell the two apart.
+    candidateHeadSha: candidate ? resolvePreviewStatusSha(commit, candidate) : null,
     changeId,
     candidate: candidate
       ? { number: candidate.prNumber ?? candidate.number ?? null, state: candidate.state ?? null, url: candidate.url ?? null }
@@ -1184,6 +1188,43 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
   };
 }
 
+/**
+ * The sha `preview_status` actually resolves against. The candidate the forge opened
+ * may carry a DIFFERENT head than the commit you pushed (it is rebuilt onto the
+ * current store), and `preview_status` only knows the candidate head — so polling the
+ * local commit returns a misleading `pending` / "no reconcile delivery observed"
+ * instead of the real result. Prefer the candidate head whenever the candidate names
+ * one; fall back to the local commit (no candidate, or an older MCP that omits it).
+ * Pure — unit-tested.
+ * @param {string|null} commit local HEAD sha
+ * @param {{headSha?: string|null}|null} candidate the candidate_open projection
+ */
+export function resolvePreviewStatusSha(commit, candidate) {
+  const head = typeof candidate?.headSha === "string" ? candidate.headSha.trim() : "";
+  return head || commit;
+}
+
+/**
+ * The two-sha notice, printed ONLY when they actually differ (when they match there is
+ * nothing to disambiguate and a second line would be noise). Names which sha the
+ * reconcile result is reported against, so a developer polling by hand — or reading a
+ * failure — knows which one to use. Pure — unit-tested.
+ * @param {string|null} commit local HEAD sha
+ * @param {{headSha?: string|null}|null} candidate the candidate_open projection
+ * @returns {string[]} lines to print (empty when there is no distinction to draw)
+ */
+export function formatCandidateHeadNotice(commit, candidate) {
+  const head = resolvePreviewStatusSha(commit, candidate);
+  if (!commit || !head || head === commit) return [];
+  return [
+    "",
+    `  ▸ local commit:    ${commit.slice(0, 9)}   (what you committed here)`,
+    `    candidate head:  ${head.slice(0, 9)}   (what preview_status reports on)`,
+    "    They differ because your candidate is rebuilt on the current store. Follow the",
+    "    candidate head — the local commit reads as \"never dispatched\", not as the result.",
+  ];
+}
+
 /** Print the `--json` result as one pretty-printed object on stdout — a no-op
  *  unless `args.json` was passed, so call sites can invoke it unconditionally. */
 function emitJson(args, payload) {
@@ -1663,9 +1704,18 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
     }
 
+    // Poll the sha `preview_status` actually resolves against — the candidate head, not
+    // the local commit, whenever the candidate names its own. Printed first (when they
+    // differ) so the developer reads the result against the right sha.
+    const statusSha = resolvePreviewStatusSha(commit, candidate) ?? commit;
+    const statusShort = statusSha.slice(0, 9);
+    if (!args.json) {
+      for (const line of formatCandidateHeadNotice(commit, candidate)) console.log(line);
+    }
+
     let status;
     if (args.noWait) {
-      status = normalizePreviewStatus(await client.callTool("preview_status", { commit }));
+      status = normalizePreviewStatus(await client.callTool("preview_status", { commit: statusSha }));
     } else {
       // One in-place status line (TTY: a spinner with an elapsed-seconds counter;
       // non-TTY: a ~10s heartbeat) instead of a newline per poll — the wait reads
@@ -1681,11 +1731,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       // stage text ("still reconciling…") IS truthful and is left as-is below.
       let phase = "reconcile";
       if (!args.json) {
-        progress = startProgress(`waiting for reconcile of ${short}…`, {
-          stages: [{ afterMs: 45_000, text: `still reconciling ${short}… (larger changes take longer)` }],
+        progress = startProgress(`waiting for reconcile of ${statusShort}…`, {
+          stages: [{ afterMs: 45_000, text: `still reconciling ${statusShort}… (larger changes take longer)` }],
         });
       }
-      status = await pollPreviewStatus(client, commit, {
+      status = await pollPreviewStatus(client, statusSha, {
         ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
         onTick: (s) => {
           // Reconcile is done but we're still waiting on a ship decision (--watch):
@@ -1693,7 +1743,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
           if (!args.json && s.status === "reconciled" && !s.shipped && phase !== "ship") {
             phase = "ship";
             progress.stop();
-            progress = startProgress(`reconciled ${short} — waiting for a ship decision…`);
+            progress = startProgress(`reconciled ${statusShort} — waiting for a ship decision…`);
           }
         },
       });
@@ -1704,7 +1754,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     }
     // --json also skips the browser auto-open (open: !args.noOpen && !args.json)
     // — automation doesn't want a browser popping up.
-    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit, ref, verb, noChanges: patchEntries.length === 0 });
+    // `commit: statusSha` — the diagnostic blocks name the sha that was actually polled,
+    // so a "never dispatched" hint points at a sha `preview_status` knows about.
+    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit: statusSha, ref, verb, noChanges: patchEntries.length === 0 });
     emitJson(args, buildJsonResult({ ok: status?.status !== "failed", ref, commit, changeId, candidate, status, previewPrUrl }));
     return status?.status === "failed" ? 1 : 0;
   } catch (e) {

package/src/obstacle.mjs

@@ -19,7 +19,7 @@ import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
  * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
  * bridge credential is cached — the developer signed in with a build that didn't
  * carry the activity flags, or ran a bare `tot login`.
- * @param {"pnpm-missing"|"install-failed"|"clone-failed"|"renderer-native-bindings-missing"} kind
+ * @param {"pnpm-missing"|"install-failed"|"clone-failed"|"renderer-native-bindings-missing"|"renderer-artifact-incomplete"} kind
  * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
  */
 export async function emitObstacle(kind, { have, need, env = process.env } = {}) {