@tokenoftrust/cli 2.2.11 → 2.2.13

package/package.json

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

@@ -51,6 +51,7 @@ import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { cockpitUrlFrom } from "../banner.mjs";
 import { recordDiagnostic } from "../diagnostics.mjs";
+import { lockRendererDir, unlockRendererDir, rendererDirInUse } from "../renderer-lock.mjs";
 
 // Kept for the internal `tot start` migration path. `tot dev` itself is native-only.
 const DEFAULT_DEV_IMAGE =
@@ -914,8 +915,19 @@ export function rendererArtifactComplete(runnerDir) {
  * runner tree per version forever. Only touches `public-*` dirs: the entitled
  * path caches by bare version and sample tarball runs by `sample-*`, both left
  * alone. Best-effort — a failure here never breaks `tot dev`.
+ *
+ * NEVER deletes a dir a running `tot dev` session is still serving files out
+ * of (per renderer-lock.mjs's cross-process lock) — resolving a newer runner
+ * in one terminal must not crash a DIFFERENT, still-running session in
+ * another with ENOENT reading its own astro templates mid-session
+ * (fb-1791304494289-ussj8l). That dir is simply left for a later prune once
+ * nothing holds it; `log` reports the deferral instead of pruning silently.
  */
-function prunePublicRunnerCache(cacheRoot, keepVersion) {
+export function prunePublicRunnerCache(
+  cacheRoot,
+  keepVersion,
+  { log = (/** @type {string} */ _message) => {}, pidAlive = processAlive, lockDir = undefined } = {},
+) {
   try {
     if (!cacheRoot || !existsSync(cacheRoot)) return;
     // keepVersion == null → keep NOTHING (drop every public-* dir); used when a
@@ -923,7 +935,12 @@ function prunePublicRunnerCache(cacheRoot, keepVersion) {
     const keep = keepVersion == null ? null : `public-${keepVersion}`;
     for (const name of readdirSync(cacheRoot)) {
       if (!name.startsWith("public-") || name === keep) continue;
-      rmSync(join(cacheRoot, name), { recursive: true, force: true });
+      const dir = join(cacheRoot, name);
+      if (rendererDirInUse(dir, { pidAlive, ...(lockDir ? { dir: lockDir } : {}) })) {
+        log(`~ keeping ${name} cached — a running \`tot dev\` session is still serving from it.`);
+        continue;
+      }
+      rmSync(dir, { recursive: true, force: true });
     }
   } catch {
     /* best-effort cache hygiene */
@@ -1044,21 +1061,21 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
             `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
           );
           setRunnerVersion(wantVersion);
-          prunePublicRunnerCache(cacheRoot, wantVersion);
+          prunePublicRunnerCache(cacheRoot, wantVersion, { log: console.error });
           return exact;
         }
         // Same version string, different published contents — a corrected
         // republish. Fall through to resolution + a fresh install (which also
         // verifies the new bytes against the new integrity).
         console.error(`~ renderer: ${wantVersion} was republished with different contents — refetching the corrected artifact`);
-        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none matches what npm now publishes
+        prunePublicRunnerCache(cacheRoot, null, { log: console.error }); // drop ALL public-* — none matches what npm now publishes
       } else {
         console.error(
           rendererCacheHealthy(exact)
             ? `~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`
             : `~ renderer: cached runner at ${exact} is missing native bindings for ${process.platform}-${process.arch} — refetching`,
         );
-        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
+        prunePublicRunnerCache(cacheRoot, null, { log: console.error }); // drop ALL public-* — none is trustworthy
       }
     }
   }
@@ -1096,7 +1113,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   setRunnerVersion(pub.version); // telemetry: the runner version running this session
   // The pinned version is now installed under public-<version> — drop any other
   // public-* dirs (e.g. the stale public-0.1.0) so they can never be reused.
-  prunePublicRunnerCache(cacheRoot, pub.version);
+  prunePublicRunnerCache(cacheRoot, pub.version, { log: console.error });
   return dir;
 }
 
@@ -1715,14 +1732,21 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
     [script, "--workspace", workspace, "--port", port],
     { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
+  // Claim this runnerDir for the lifetime of this child — prunePublicRunnerCache
+  // consults this lock before deleting an un-pinned cached version, so resolving
+  // a NEWER runner in one terminal can never delete the directory THIS session
+  // is still serving files out of (fb-1791304494289-ussj8l).
+  lockRendererDir(runnerDir, { pid: child.pid });
   const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
+      unlockRendererDir({ pid: child.pid });
       resolvePromise(code ?? 0);
     });
     child.on("error", (e) => {
       handle.exited = true;
+      unlockRendererDir({ pid: child.pid });
       console.error(fail(`could not start the native dev runner: ${e.message}`));
       resolvePromise(1);
     });

package/src/renderer-lock.mjs

@@ -0,0 +1,74 @@
+// @ts-check
+/**
+ * Cross-process lock recording which PIDs are actively serving a `tot dev`
+ * native session out of which cached renderer directory (`~/.tot/cache/renderer/
+ * <version>` or `public-<version>`). `prunePublicRunnerCache` (src/commands/dev.mjs)
+ * reads it before deleting an un-pinned cached version, so resolving a NEWER
+ * runner in one terminal can never delete the directory a DIFFERENT, still-running
+ * `tot dev` session in another terminal is serving files out of — which used to
+ * crash the live session with ENOENT reading its own astro templates mid-session
+ * (fb-1791304494289-ussj8l).
+ *
+ * Lives OUTSIDE the renderer cache tree itself (not `<runnerDir>/.tot-dev-lock`)
+ * so a lock entry is never mistaken for cache/package content and never ships
+ * inside a published runner tarball.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const RENDERER_LOCK_DIR = join(homedir(), ".tot", "run", "active-renderers");
+
+/** Record that `pid` (default: this process) is actively serving from `runnerDir`. */
+export function lockRendererDir(runnerDir, { pid = process.pid, dir = RENDERER_LOCK_DIR } = {}) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, String(pid)), runnerDir);
+  } catch {
+    /* best-effort — a failed lock must never block `tot dev` from starting */
+  }
+}
+
+/** Release a lock (best-effort; safe to call more than once, e.g. on every exit path). */
+export function unlockRendererDir({ pid = process.pid, dir = RENDERER_LOCK_DIR } = {}) {
+  try {
+    rmSync(join(dir, String(pid)), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Is any LIVE process's lock pointing at `runnerDir`? Fails CLOSED (true) on any
+ * read error — an unreadable lock state must never read as "safe to delete",
+ * since that's precisely the failure this exists to prevent. A stale (dead-pid)
+ * lock is ignored so cache hygiene still reclaims disk once nothing holds it.
+ * @param {string} runnerDir
+ * @param {{ pidAlive: (pid:number)=>boolean, dir?: string }} deps
+ */
+export function rendererDirInUse(runnerDir, { pidAlive, dir = RENDERER_LOCK_DIR }) {
+  try {
+    if (!existsSync(dir)) return false;
+    let inUse = false;
+    for (const name of readdirSync(dir)) {
+      const pid = Number(name);
+      if (!Number.isInteger(pid) || pid <= 0) continue;
+      let lockedDir;
+      try {
+        lockedDir = readFileSync(join(dir, name), "utf8");
+      } catch {
+        continue; // one unreadable lock entry must not block the rest of the scan
+      }
+      if (pidAlive(pid)) {
+        if (lockedDir === runnerDir) inUse = true;
+      } else {
+        // A crashed/killed session never ran its own exit handler — reap its
+        // lock opportunistically (best-effort) so entries don't accumulate.
+        try { rmSync(join(dir, name), { force: true }); } catch { /* best-effort */ }
+      }
+    }
+    return inUse;
+  } catch {
+    return true; // fail closed: an unreadable lock DIRECTORY must not read as "unused"
+  }
+}

package/src/validate.mjs

@@ -63,6 +63,71 @@ const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
 
+// The keys the platform reads in `.tot/config.json`. Mirrors
+// packages/public-runtime/src/declared-tenant-config.mjs (this package ships to npm
+// on its own); test/declared-config-parity.test.mjs pins the two together, so a
+// field the platform honors can never be refused here, and a key no surface reads
+// can never pass.
+export const TOT_CONFIG_KEYS = [
+  "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
+  "siteType", "compliance", "capabilities", "features",
+];
+// Keys other tooling has written that the platform does NOT read, with the key it does.
+const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
+export const COMPLIANCE_KEYS = [
+  "ruleProfile", "minAge", "nicotineWarning", "shippingRestriction", "pactAct",
+  "adultSignature", "prop65", "purchaseLimit", "stateEligibility", "exciseTax",
+];
+export const FEATURE_KEYS = [
+  "catalog", "productSearch", "savedItems", "quickView", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
+];
+export const SITE_TYPES = ["commerce", "marketing"];
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * Refuse what the platform would silently ignore: an unknown top-level key, an
+ * unknown `compliance`/`features` key, or a declared field of the wrong shape. Each
+ * one passes JSON parsing and renders nothing — on a regulated store that is a
+ * mandated notice that never appears.
+ * @returns {Finding[]}
+ */
+export function validateDeclaredConfig(config, file = ".tot/config.json") {
+  const out = [];
+  for (const key of Object.keys(config)) {
+    if (!TOT_CONFIG_KEYS.includes(key)) {
+      const renamed = RENAMED_CONFIG_KEYS[key];
+      out.push(mk(ERROR, "config-unknown-key", file,
+        `\`${key}\` is not a .tot/config.json key — the platform never reads it`,
+        renamed ? `use \`${renamed}\`` : `known keys: ${TOT_CONFIG_KEYS.join(", ")}`));
+    }
+  }
+  if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
+    out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
+  }
+  /** @type {Array<[string, string[]]>} */
+  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
+  for (const [field, known] of objectFields) {
+    const value = config[field];
+    if (value === undefined) continue;
+    if (!isObject(value)) {
+      out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
+      continue;
+    }
+    for (const key of Object.keys(value)) {
+      if (!known.includes(key)) {
+        out.push(mk(ERROR, `config-${field}-unknown-key`, `${file} ${field}`,
+          `\`${field}.${key}\` is not a ${field} key — nothing renders from it`,
+          `known keys: ${known.join(", ")}`));
+      }
+    }
+  }
+  if (config.capabilities !== undefined && !isObject(config.capabilities)) {
+    out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
+  }
+  return out;
+}
+
 /**
  * Validate a parsed `.tot/config.json` against the shape the reconcile pipeline
  * (`mapToArtifact`) requires. Pure — no I/O.
@@ -76,6 +141,7 @@ export function validateConfigShape(config, file = ".tot/config.json") {
   if (typeof config.tenant !== "string" || !config.tenant) {
     out.push(mk(ERROR, "config-tenant", file, "`tenant` must be a non-empty string"));
   }
+  out.push(...validateDeclaredConfig(config, file));
   if (!Array.isArray(config.mappings)) {
     out.push(mk(ERROR, "config-mappings", file, "`mappings` must be an array", "seed shape: [{workspace,repo,kind}]"));
     return out;

package/template/sample-store/content/chrome.json

@@ -25,7 +25,7 @@
     },
     {
       "label": "About",
-      "href": "/about"
+      "href": "/pages/about-us"
     }
   ],
   "footer": {
@@ -57,15 +57,15 @@
         "links": [
           {
             "label": "About",
-            "href": "/about"
+            "href": "/pages/about-us"
           },
           {
             "label": "Shipping & Returns",
-            "href": "/shipping-returns"
+            "href": "/pages/shipping-returns"
           },
           {
             "label": "Privacy",
-            "href": "/privacy"
+            "href": "/pages/privacy-policy"
           }
         ]
       }