@tokenoftrust/cli 3.10.2 → 3.10.4

package/bin/tot.mjs

@@ -29,10 +29,6 @@ import {
   recordDiagnostic,
   resetInvocationDiagnostics,
 } from "../src/diagnostics.mjs";
-import {
-  nativeWindowsRefuseMessage,
-  shouldRefuseNativeWindows,
-} from "../src/platform.mjs";
 
 const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
 
@@ -120,14 +116,6 @@ async function dispatch(cmd, rest, ctx) {
     return cmd ? 0 : 2;
   }
 
-  // Native Windows: refuse before login/--device/start burn cycles on a host the
-  // local loop cannot run on. doctor/feedback/ideas stay available so the gate
-  // itself is discoverable. WSL reports as linux and passes through.
-  if (shouldRefuseNativeWindows(cmd)) {
-    process.stderr.write(nativeWindowsRefuseMessage(cmd));
-    return 2;
-  }
-
   // A mounted publication space's checkout (spaces/<id>/, recorded by `tot clone`) is its own
   // repository: the store-root verbs below would push it with the ROOT's credential or merge the
   // root's preview branch into it. Refuse them there, naming the space's own path.

package/package.json

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

@@ -913,7 +913,20 @@ export function rendererNativeBindingGaps(runnerDir, { platform = process.platfo
  * `platform`/`arch` are injectable so this is testable off the host's real arch.
  */
 export function rendererCacheHealthy(runnerDir, opts = {}) {
-  return rendererNativeBindingGaps(runnerDir, opts).length === 0;
+  return rendererNativeBindingGaps(runnerDir, opts).length === 0 && rendererDepsResolve(runnerDir);
+}
+
+/**
+ * Does the renderer's own dependency tree resolve from where it sits? `existsSync`
+ * follows links, so a `node_modules` entry whose target is gone (a junction left
+ * pointing into a renamed staging directory) reads as absent. A tree with no
+ * `apps/storefront/package.json` has nothing to check and passes.
+ * @param {string} runnerDir
+ */
+export function rendererDepsResolve(runnerDir) {
+  const app = join(runnerDir, "apps", "storefront");
+  if (!existsSync(join(app, "package.json"))) return true;
+  return existsSync(join(app, "node_modules", "astro", "package.json"));
 }
 
 /**
@@ -1266,7 +1279,7 @@ export async function installRunnerTarball(
   // Bounded to one retry so a genuinely-broken source still fails loudly.
   for (let attempt = 1; ; attempt++) {
     const archivePath = /** @type {string} */ (isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${attempt}.tar.gz`) : localSource);
-    const stagingDir = `${runnerDir}.staging-${process.pid}`;
+    const stagingDir = installsInPlace() ? runnerDir : `${runnerDir}.staging-${process.pid}`;
     try {
       if (isUrl) {
         // The fetch itself is otherwise silent (no per-byte output) and can run
@@ -1339,8 +1352,10 @@ export async function installRunnerTarball(
       // Atomic-ish: only rename into the final, discoverable path once install
       // succeeded, so a crashed/interrupted run never leaves a half-built cache
       // entry that a later `tot dev` would treat as ready.
-      rmSync(runnerDir, { recursive: true, force: true });
-      renameSync(stagingDir, runnerDir);
+      if (stagingDir !== runnerDir) {
+        rmSync(runnerDir, { recursive: true, force: true });
+        renameSync(stagingDir, runnerDir);
+      }
       // Fence a fresh install against npm/cli#4828: if the installer left the wrong
       // arch's native bindings (or none) for this host, DON'T stamp the completion
       // marker — an unmarked tree is never reused, so the next run reinstalls cleanly
@@ -1368,6 +1383,19 @@ export async function installRunnerTarball(
         /** @type {any} */ (err).permanent = true;
         throw err;
       }
+      if (!rendererDepsResolve(runnerDir)) {
+        await emitObstacle("install-failed");
+        const err = new CliError(
+          `the store preview engine installed but its dependencies don't resolve from where it was installed` +
+            `\n     details: ${installLog}`,
+          {
+            next: `re-run \`tot start --reset-cache\`; if it repeats, file feedback naming preview engine ${version} and your OS`,
+            exitCode: 2,
+          },
+        );
+        /** @type {any} */ (err).permanent = true;
+        throw err;
+      }
       writeCacheMarker(runnerDir, { version, integrity: contentId });
       return runnerDir;
     } catch (e) {
@@ -1547,9 +1575,9 @@ function extractTarball(archivePath, destDir, { strip = 0 } = {}) {
  * missing or disabled (a locked-down host), pnpm install below falls through to
  * the pnpm-missing obstacle instead of failing here.
  * @param {string} runnerDir
- * @param {{ logPath?: string, spawnFn?: typeof spawnSync }} [opts]
+ * @param {{ logPath?: string, spawnFn?: (cmd: string, args: string[], opts?: any) => any }} [opts]
  */
-export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } = {}) {
+export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnLauncherSync } = {}) {
   const pkgPath = join(runnerDir, "package.json");
   if (!existsSync(pkgPath)) return;
   let pm;
@@ -1598,13 +1626,68 @@ export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } =
  * @param {string} cmd @param {string[]} args @param {object} opts
  * @returns {Promise<{ status: number|null, error: Error|null, signal?: string|null }>}
  */
+/**
+ * Windows installs the renderer where it will live. pnpm there writes `node_modules`
+ * junctions with ABSOLUTE targets into the directory it installs in, so renaming a
+ * staging directory into place leaves every one dangling. The completion marker is still
+ * written last and an unmarked tree is never reused, so a half install cannot be served.
+ * @param {string} [platform]
+ */
+export function installsInPlace(platform = process.platform) {
+  return platform === "win32";
+}
+
+/**
+ * On Windows `pnpm`, `corepack` and `npm` are `.cmd` shims, which Node refuses to
+ * spawn without a shell.
+ * @param {string} [platform]
+ */
+export function launcherNeedsShell(platform = process.platform) {
+  return platform === "win32";
+}
+
+const SAFE_LAUNCHER_ARG = /^[\w@.:+=/-]+$/;
+
+/**
+ * `[file, args, opts]` to spawn a package-manager launcher. On Windows that is one
+ * command string run through a shell (an args array alongside `shell: true` trips
+ * Node's DEP0190 warning). The shell sees every argument, so each must match a safe
+ * alphabet; anything else throws instead of reaching it.
+ * @param {string} cmd @param {string[]} args @param {object} [opts] @param {string} [platform]
+ * @returns {[string, string[], object]}
+ */
+export function launcherSpawn(cmd, args, opts = {}, platform = process.platform) {
+  if (!launcherNeedsShell(platform)) return [cmd, args, opts];
+  for (const a of args) {
+    if (!SAFE_LAUNCHER_ARG.test(a)) throw new Error(`refusing to pass an unsafe argument to ${cmd} through a shell: ${a}`);
+  }
+  return [[cmd, ...args].join(" "), [], { ...opts, shell: true }];
+}
+
+/**
+ * Is the launcher on PATH? POSIX answers with ENOENT at spawn, so this is always true
+ * there. Through cmd.exe a missing launcher is an ordinary non-zero exit that cannot be
+ * told from a failed install, so Windows asks `where` (a real executable, no shell).
+ * @param {string} cmd @param {string} [platform]
+ */
+export function launcherAvailable(cmd, platform = process.platform) {
+  if (!launcherNeedsShell(platform)) return true;
+  return spawnSync("where", [cmd], { stdio: "ignore" }).status === 0;
+}
+
+/** @param {string} cmd @param {string[]} args @param {object} [opts] */
+function spawnLauncherSync(cmd, args, opts = {}) {
+  const [file, fileArgs, fileOpts] = launcherSpawn(cmd, args, opts);
+  return spawnSync(file, fileArgs, fileOpts);
+}
+
 function spawnAsyncResult(cmd, args, opts = {}) {
   return new Promise((resolvePromise) => {
     let settled = false;
     const settle = (v) => { if (!settled) { settled = true; resolvePromise(v); } };
     let child;
     try {
-      child = spawn(cmd, args, opts);
+      child = spawn(...launcherSpawn(cmd, args, opts));
     } catch (error) {
       settle({ status: null, error });
       return;
@@ -1616,10 +1699,10 @@ function spawnAsyncResult(cmd, args, opts = {}) {
 
 /**
  * @param {string} runnerDir
- * @param {{ logPath?: string, spawnFn?: (cmd: string, args: string[], opts?: any) => any }} [opts]
+ * @param {{ logPath?: string, spawnFn?: (cmd: string, args: string[], opts?: any) => any, available?: (cmd: string) => boolean }} [opts]
  * @returns {Promise<string>} the launcher that completed the install ("pnpm" | "corepack" | "npm").
  */
-export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
+export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult, available = launcherAvailable } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
   // pnpm FIRST: the renderer tree is a bundle of native optional deps (rolldown,
@@ -1644,6 +1727,10 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
   ];
   try {
     for (const { cmd, args } of attempts) {
+      if (!available(cmd)) {
+        if (fd !== null) writeSync(fd, `[tot] ${cmd} not found on PATH — trying the next launcher\n`);
+        continue;
+      }
       // Awaited: the default spawnFn (spawnAsyncResult) runs the launcher
       // NON-BLOCKING so the caller's "installing…" spinner keeps ticking during
       // the (long, one-time) npm install instead of freezing at "(0s)" — a
@@ -1661,6 +1748,13 @@ export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncR
         if (fd !== null) writeSync(fd, `[tot] ${cmd} not found (ENOENT) — trying the next launcher\n`);
         continue;
       }
+      // corepack is the one launcher that can run and still fail for a reason that has
+      // nothing to do with the install (no write access to its shim directory, no
+      // network to fetch pnpm); npm below is the escape hatch that always exists.
+      if (cmd === "corepack") {
+        if (fd !== null) writeSync(fd, `[tot] corepack exited ${r.status} — trying npm\n`);
+        continue;
+      }
       // The launcher ran; the install itself failed. That's the actionable error.
       // installRunnerTarball retries transient failures once from a clean slate;
       // deterministic broken-release 404s are marked permanent below and skip it.

package/src/commands/doctor.mjs

@@ -25,11 +25,7 @@ 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 {
-  isNativeWindows,
-  nativeWindowsDetail,
-  shouldAttemptDoctorAutoLogin,
-} from "../platform.mjs";
+import { isNativeWindows, nativeWindowsDetail } from "../platform.mjs";
 import { readSessionCredentials, isExpired } from "../token-store.mjs";
 import { dockerAvailable, tryStartDocker, RENDERER_CACHE_ROOT, rendererArtifactComplete } from "./dev.mjs";
 import { loginAndCache } from "./login.mjs";
@@ -71,15 +67,15 @@ export function collectChecks(_ctx, env = process.env) {
     blocking: true,
   });
 
-  // Native Windows isn't a supported host for the local loop (the runner install
-  // + tar extraction assume a POSIX toolchain) — WSL is, and reports as linux
-  // here. Say so up front instead of letting `tot login` / `tot dev` fail opaquely.
+  // Native Windows runs everything except the local renderer (`dev` / `start`: the
+  // runner install + tar extraction assume a POSIX toolchain) — WSL is the host for
+  // those, and reports as linux here. Informational, so the gap is visible up front.
   const nativeWindows = isNativeWindows();
   checks.push({
-    name: "supported platform",
-    pass: !nativeWindows,
+    name: "platform",
+    pass: true,
     detail: nativeWindows ? nativeWindowsDetail() : "macOS / Linux / WSL",
-    blocking: true,
+    blocking: false,
   });
 
   // Informational: the versions + OS this invocation is running on — the same
@@ -181,17 +177,13 @@ async function applyFixes(checks, env) {
 
   const auth = checks.find((c) => c.name === "auth identity");
   if (auth && !auth.pass) {
-    if (!shouldAttemptDoctorAutoLogin()) {
-      console.log(`  ~ not signed in — skipping auto-login (${nativeWindowsDetail()})`);
-    } else {
-      const mcpUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
-      console.log("  ~ not signed in — opening the browser to sign in…");
-      try {
-        await loginAndCache(mcpUrl, env, { log: (m) => console.log(`  ${m}`) });
-        console.log("  ✓ signed in");
-      } catch (e) {
-        console.log(`  ~ couldn't sign in automatically (${e?.message || e}) — run \`tot login\``);
-      }
+    const mcpUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+    console.log("  ~ not signed in — opening the browser to sign in…");
+    try {
+      await loginAndCache(mcpUrl, env, { log: (m) => console.log(`  ${m}`) });
+      console.log("  ✓ signed in");
+    } catch (e) {
+      console.log(`  ~ couldn't sign in automatically (${e?.message || e}) — run \`tot login\``);
     }
   }
 }

package/src/git-credential.mjs

@@ -252,6 +252,13 @@ export function forgeShimPath(env = process.env) {
   return join(home, ".tot", "bin", "tot-git-credential");
 }
 
+/** The shim path as git's `!` helper runs it (through sh). Git for Windows' sh reads
+ *  forward slashes, not backslashes, and a home directory may contain spaces, so a
+ *  Windows path is slash-normalized and single-quoted. POSIX paths pass through. Pure. */
+export function helperCommandPath(shim, platform = process.platform) {
+  return platform === "win32" ? shq(shim.replace(/\\/g, "/")) : shim;
+}
+
 /** The shim's contents: pin the ABSOLUTE node + CLI entry active at write time, with a
  *  PATH-search fallback for node, and FAIL LOUD to stderr (never silently) when no node
  *  is found — so a broken helper says how to fix itself instead of yielding an opaque
@@ -324,7 +331,7 @@ export function installForgeCredentialHelper(git, {
 } = {}) {
   if (!host) return false;
   const shim = writeShim(env, nodePath, entryPath);
-  const helperValue = shim ? `!${shim}` : CREDENTIAL_HELPER;
+  const helperValue = shim ? `!${helperCommandPath(shim)}` : CREDENTIAL_HELPER;
   const key = `credential.https://${host}.helper`;
   let raw = null;
   try { raw = git(["config", "--local", "--get-all", key]); } catch { raw = null; }

package/src/open.mjs

@@ -58,6 +58,17 @@ export async function firstFreePort(preferred, maxTries = 64) {
   return preferred;
 }
 
+/**
+ * The OS opener as [command, args]. Windows goes through `rundll32` with no shell:
+ * `cmd /c start` would treat the `&` in an OAuth URL as a command separator.
+ * @param {string} url @param {string} platform @returns {[string, string[]]}
+ */
+export function openerCommand(url, platform) {
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+  return ["xdg-open", [url]];
+}
+
 /**
  * Open `url` in the user's default browser. Best-effort and non-blocking: the
  * child is detached + unref'd so it never holds `tot` open, and any failure
@@ -65,21 +76,9 @@ export async function firstFreePort(preferred, maxTries = 64) {
  * @returns {boolean} whether we managed to launch an opener.
  */
 export function openBrowser(url, platform = process.platform) {
-  let cmd, args, shell = false;
-  if (platform === "darwin") {
-    cmd = "open";
-    args = [url];
-  } else if (platform === "win32") {
-    // `start` is a shell builtin; the empty first arg is the window title.
-    cmd = "start";
-    args = ["", url];
-    shell = true;
-  } else {
-    cmd = "xdg-open";
-    args = [url];
-  }
+  const [cmd, args] = openerCommand(url, platform);
   try {
-    const child = spawn(cmd, args, { stdio: "ignore", detached: true, shell });
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
     child.on("error", () => {}); // swallow "opener not found" async errors
     child.unref();
     return true;

package/src/platform.mjs

@@ -1,10 +1,8 @@
 /**
- * Host-platform readiness for the local loop.
+ * Host-platform copy shared by `tot doctor` and login recovery hints.
  *
- * Native Windows is unsupported (runner install + tar extraction assume a POSIX
- * toolchain). WSL reports as `linux` and is the supported path on a Windows box.
- * Keep the check + copy in ONE place so doctor, the CLI gate, and login recovery
- * hints cannot drift.
+ * Every command runs on native Windows. WSL reports as `linux` and remains the
+ * better-trodden path for the local renderer (`tot dev` / `tot start`).
  */
 
 export const WSL_INSTALL_URL = "https://learn.microsoft.com/windows/wsl/install";
@@ -17,75 +15,17 @@ export function isNativeWindows(platform = process.platform) {
   return platform === "win32";
 }
 
-/**
- * One-line detail used by `tot doctor` and CliError footers.
- * @param {{ url?: string }} [opts]
- */
-export function nativeWindowsDetail(opts = {}) {
-  const url = opts.url ?? WSL_INSTALL_URL;
-  return `native Windows isn't supported yet — run tot inside WSL (${url})`;
-}
-
-/**
- * Multi-line refuse message printed before exit. Names the attempted command so
- * a pasted invite (`tot login --code … && tot start`) still points at WSL.
- * @param {string} [command] e.g. "login", "start"
- */
-export function nativeWindowsRefuseMessage(command) {
-  const verb = command ? `tot ${command}` : "tot";
-  return (
-    `✗ ${nativeWindowsDetail()}\n` +
-    `  → next: install WSL, open an Ubuntu (or other Linux) terminal, install Node 24 LTS + git there,\n` +
-    `    then re-run \`${verb}\` inside WSL — don't keep retrying login/--device on native Windows.\n`
-  );
+/** One-line detail used by `tot doctor`. */
+export function nativeWindowsDetail() {
+  return `native Windows — if \`tot dev\` or \`tot start\` misbehaves, WSL is the better-trodden path (${WSL_INSTALL_URL})`;
 }
 
 /**
- * Commands that are safe / useful to run on native Windows so the developer can
- * learn the gate (`doctor`) or report friction (`feedback`) without a false start.
- */
-export const NATIVE_WINDOWS_ALLOWED_COMMANDS = new Set([
-  "help",
-  "--help",
-  "-h",
-  "--version",
-  "-v",
-  "version",
-  "doctor",
-  "feedback",
-  "ideas",
-]);
-
-/**
- * @param {string | null | undefined} command
- * @param {string} [platform] Node `process.platform` value (defaults to current).
- * @returns {boolean} true when this command must refuse on native Windows
- */
-export function shouldRefuseNativeWindows(command, platform = process.platform) {
-  if (!isNativeWindows(/** @type {string} */ (platform))) return false;
-  const cmd = String(command ?? "").trim();
-  if (!cmd) return false; // bare `tot` → help
-  return !NATIVE_WINDOWS_ALLOWED_COMMANDS.has(cmd);
-}
-
-/**
- * Recovery hint after a failed `tot login`. Never steers native Windows at
- * `--device` — that path still can't run the local loop on win32.
- * @param {{ device?: boolean, platform?: string }} [opts]
+ * Recovery hint after a failed `tot login`.
+ * @param {{ device?: boolean }} [opts]
  */
 export function loginFailureNext(opts = {}) {
-  const platform = /** @type {string} */ (opts.platform ?? process.platform);
-  if (isNativeWindows(platform)) return nativeWindowsDetail();
   return opts.device
     ? "re-run `tot login --device` and approve the code."
     : "re-run `tot login` and finish the browser sign-in (approve the request) — or try `tot login --device`.";
 }
-
-/**
- * `tot doctor --fix` must not open OAuth on native Windows — the session
- * would be unusable for the local loop, and the browser hop burns a cycle.
- * @param {string} [platform] Node `process.platform` value (defaults to current).
- */
-export function shouldAttemptDoctorAutoLogin(platform = process.platform) {
-  return !isNativeWindows(/** @type {string} */ (platform));
-}