@tokenoftrust/cli 2.0.9 → 2.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "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

@@ -1158,9 +1158,9 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  *   status?: {status?: string, reconcile?: object|null, compliance?: object|null,
  *     previewUrl?: string|null, shipped?: object|null, dispatched?: boolean|null,
  *     notDispatched?: boolean, delivery?: object|null}|null,
- *   previewPrUrl?: string|null, error?: string|null, note?: string|null }} input
+ *   previewPrUrl?: string|null, error?: string|null, note?: string|null, noChanges?: boolean }} input
  */
-export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null }) {
+export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null, noChanges = false }) {
   return {
     ok,
     ref,
@@ -1183,6 +1183,13 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     forwardFailed: /** @type {any} */ (status)?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
     previewPrUrl,
+    // Honest-diagnosis parity with the human-readable formatNotDispatchedBlock: a
+    // `--json` caller gets the SAME "why" signal a human sees on the console. Without
+    // this, `candidate:null, notDispatched:true, delivery:null` reads identically for
+    // "no file diff → candidate_open never even ran" and "webhook never registered" /
+    // "wrong tenant scope" — an automation caller (or a human piping --json) had no way
+    // to tell an empty-diff no-op from a genuine platform dispatch failure.
+    ...(noChanges ? { noChanges: true } : {}),
     ...(error ? { error } : {}),
     ...(note ? { note } : {}),
   };
@@ -1756,8 +1763,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // — automation doesn't want a browser popping up.
     // `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 }));
+    const noChanges = patchEntries.length === 0;
+    reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit: statusSha, ref, verb, noChanges });
+    emitJson(args, buildJsonResult({ ok: status?.status !== "failed", ref, commit, changeId, candidate, status, previewPrUrl, noChanges }));
     return status?.status === "failed" ? 1 : 0;
   } catch (e) {
     progress?.stop();

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 } = {}) {

package/src/validate.mjs

@@ -742,7 +742,12 @@ function walk(dir, pred) {
 
 // --- link / asset extraction -------------------------------------------------
 const HREF_RE = /\bhref\s*=\s*"([^"]*)"/gi;
-const SRC_RE = /\b(?:src|srcset)\s*=\s*"([^"]*)"/gi;
+const SRC_RE = /\bsrc\s*=\s*"([^"]*)"/gi;
+// `srcset` carries a comma-separated list of `url descriptor` pairs (e.g.
+// "a.webp 480w, b.webp 800w"), not a single URL — each candidate must be split
+// off its descriptor before being checked as an asset. Mirrors
+// scripts/publish/lib/asset-reachability.mjs's srcset handling.
+const SRCSET_RE = /\bsrcset\s*=\s*"([^"]*)"/gi;
 const STYLE_OPEN_WITH_ATTRS_RE = /<style\s+[^>]*>/i;
 /** An in-page skip link: an anchor to a #main-ish target, or one carrying a skip class. */
 const SKIP_LINK_RE = /<a\b[^>]*(?:class="[^"]*\bskip[-\w]*\b[^"]*"|href="#(?:main|content|main-content)\b")/i;
@@ -974,6 +979,14 @@ export function validateTenant(tenantDir, opts = {}) {
       const f = checkAsset(m[1].trim(), r, publicDir, opts.tenantId || config?.tenant);
       if (f) findings.push(f);
     }
+    for (const m of html.matchAll(SRCSET_RE)) {
+      for (const candidate of m[1].split(",")) {
+        const url = candidate.trim().split(/\s+/)[0];
+        if (!url) continue;
+        const f = checkAsset(url, r, publicDir, opts.tenantId || config?.tenant);
+        if (f) findings.push(f);
+      }
+    }
   }
 
   // 5. git conflict markers — advisory (never blocks), but LOUD: a half-resolved