@tokenoftrust/cli 2.0.9 → 2.0.10

package/package.json

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