@tokenoftrust/cli 1.3.4-rc.3 → 1.3.4-rc.4

package/bin/tot.cjs

@@ -40,21 +40,49 @@ if (!meets) {
       "  → next: install Node " + RECOMMENDED_NODE + " (LTS) — nvm: `nvm install " + RECOMMENDED_NODE +
       " && nvm use " + RECOMMENDED_NODE + "`, or https://nodejs.org/ — then re-run the same command.\n"
   );
-  process.exit(1);
-}
+  // Beacon the hosted cockpit that this machine dead-ended on the Node floor, then
+  // exit. This is THE headline obstacle: an invited dev whose `tot login` (the
+  // pasted setup command) can't even run because their Node is too old. We're
+  // pre-login, pre-ESM, maybe pre-`fetch` — so the beacon reads the bridge
+  // credential straight from the pasted flags and posts over require("https").
+  // Best-effort and time-boxed: the ✗ message is already printed; we only linger
+  // (≤ the beacon's own timeout) to deliver telemetry before exit(1).
+  beaconNodeTooOld(nodeVersion, function () { process.exit(1); });
+} else {
+  // Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
+  // the import specifier correct on Windows drive-letter paths too.
+  var path = require("path");
+  var pathToFileURL = require("url").pathToFileURL;
+  var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
 
-// Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
-// the import specifier correct on Windows drive-letter paths too.
-var path = require("path");
-var pathToFileURL = require("url").pathToFileURL;
-var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
+  // new Function with a CONSTANT body ("return import(u)") — nothing is ever
+  // interpolated into the code string; the entry URL travels as an argument. This
+  // indirection exists only so pre-import() parsers never see the import syntax.
+  new Function("u", "return import(u)")(entry).catch(function (e) {
+    // tot.mjs formats + exits on its own errors; landing here means the CLI
+    // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
+    process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
+    process.exit(1);
+  });
+}
 
-// new Function with a CONSTANT body ("return import(u)") — nothing is ever
-// interpolated into the code string; the entry URL travels as an argument. This
-// indirection exists only so pre-import() parsers never see the import syntax.
-new Function("u", "return import(u)")(entry).catch(function (e) {
-  // tot.mjs formats + exits on its own errors; landing here means the CLI
-  // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
-  process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
-  process.exit(1);
-});
+// Fire the node-too-old obstacle beacon, then always call `done` (exactly once,
+// bounded by the beacon's timeout). Isolated + fully guarded: any hiccup —
+// missing flags, an old Node that can't require a .cjs, a network stall — just
+// falls through to `done`, so the exit path is never blocked or altered. The
+// heavy lifting lives in the shared ES5 helper so the wire shape can't drift.
+function beaconNodeTooOld(have, done) {
+  try {
+    var mod = require("../src/obstacle-beacon.cjs");
+    var act = mod.parseActivityArgs(process.argv);
+    if (!act.url || !act.token) { done(); return; }
+    var cliVersion;
+    try { cliVersion = require("../package.json").version; } catch (e) {}
+    mod.beacon(
+      { url: act.url, token: act.token, kind: "node-too-old", have: have, need: MIN_NODE, cliVersion: cliVersion },
+      done
+    );
+  } catch (e) {
+    done();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.4-rc.3",
+  "version": "1.3.4-rc.4",
   "description": "Token of Trust developer CLI — check out 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/checkout.mjs

@@ -24,6 +24,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
+import { emitObstacle } from "../obstacle.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -202,6 +203,10 @@ async function cloneRepo(gitRemote, dir, redact) {
   try {
     await git(["clone", gitRemote, dir]);
   } catch (e) {
+    // Beacon the cockpit before we surface the error — covers this path for both
+    // `tot checkout` and `tot start` (which clones through here). Awaited so the
+    // packet lands before the process prints + exits; swallowed either way.
+    await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
     });

package/src/commands/dev.mjs

@@ -42,6 +42,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient, CLI_VERSION, setRunnerVersion, versionStamp } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { emitObstacle } from "../obstacle.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
@@ -928,7 +929,7 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
       stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
     });
     try {
-      runPnpmInstall(stagingDir, { logPath: installLog });
+      await runPnpmInstall(stagingDir, { logPath: installLog });
     } finally {
       installSpin.stop();
     }
@@ -1022,7 +1023,7 @@ function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
  * caller's spinner owns the screen. On failure we surface a clean, business-
  * readable message + the log path — never the raw node/pnpm firehose.
  */
-function runPnpmInstall(runnerDir, { logPath } = {}) {
+async function runPnpmInstall(runnerDir, { logPath } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
   // npm FIRST: it ships with EVERY Node (including 25+, where corepack is no
@@ -1055,6 +1056,7 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
         continue;
       }
       // The launcher ran; the install itself failed. That's the actionable error.
+      await emitObstacle("install-failed");
       throw new CliError(
         `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
           (logPath ? `\n     details: ${logPath}` : ""),
@@ -1064,6 +1066,7 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
     // Every launcher ENOENT'd → there's no pnpm on this machine and corepack
     // couldn't provide one (corepack isn't bundled on Node 25+). npm ships with
     // every Node, so `npm i -g pnpm` is the escape hatch that always exists.
+    await emitObstacle("pnpm-missing");
     throw new CliError(
       "couldn't set up the store preview engine — pnpm isn't available on this machine" +
         (logPath ? `\n     details: ${logPath}` : ""),

package/src/obstacle-beacon.cjs

@@ -0,0 +1,111 @@
+/**
+ * The obstacle beacon — a fire-and-forget POST that tells the hosted cockpit a
+ * `tot start` / `tot checkout` failed, so it can show the exact fix in the bridge
+ * strip (obstacle lane, server side already shipped). Best-effort telemetry that
+ * rides ALONGSIDE the house-style `✗ … → next:` error; it must NEVER change,
+ * delay past its timeout, or fail that error path.
+ *
+ *   KEEP THIS FILE ES5/CommonJS: var, string concat, function expressions — no
+ *   arrow functions, template literals, optional chaining, or const/let. The ES5
+ *   launcher (bin/tot.cjs) require()s this on a machine that FAILED the Node
+ *   floor (Node < 22.12, no global `fetch`, no ESM) to beacon `node-too-old`
+ *   pre-login — the exact old-Node dead-end the whole obstacle lane exists for.
+ *   So this uses require("https"/"http"), and a test keeps it parseable by
+ *   ancient Nodes. The ESM side (src/obstacle.mjs) imports beaconAsync from here
+ *   too, so the wire shape + endpoint live in ONE place and can't drift.
+ *
+ * The event contract is DECIDED (owned by the server's rail-obstacle-lane):
+ *   POST <activity-url>/api/dev/activity   Authorization: Bearer <token>
+ *   { event:"obstacle", kind, have?, need?, cliVersion?, at? }
+ * Send ONLY these machine-readable fields — the human remediation copy is composed
+ * SERVER-side per kind, so guidance changes without a CLI release. The server
+ * stamps its own reportedAt (skew-proof) and a later heartbeat CLEARS the obstacle.
+ */
+"use strict";
+
+var VALID_KINDS = { "node-too-old": 1, "pnpm-missing": 1, "install-failed": 1, "clone-failed": 1 };
+var TIMEOUT_MS = 2000;
+
+/**
+ * Pull --activity-url / --activity-token straight out of argv. The launcher runs
+ * BEFORE any arg framework (and before login has cached anything), so on the
+ * node-too-old path this is the only source of the bridge credential — the pasted
+ * setup command carries both flags. Returns {} for whatever is absent.
+ */
+function parseActivityArgs(argv) {
+  var out = { url: undefined, token: undefined };
+  if (!argv) return out;
+  for (var i = 0; i < argv.length; i++) {
+    if (argv[i] === "--activity-url") out.url = argv[i + 1];
+    else if (argv[i] === "--activity-token") out.token = argv[i + 1];
+  }
+  return out;
+}
+
+/**
+ * Fire one obstacle beacon. Everything is wrapped so it can never throw into the
+ * caller's error path; `done` is invoked EXACTLY once (on success, error, timeout,
+ * or a skip) — the launcher passes process.exit as `done` so the process lingers
+ * only as long as the beacon (≤ TIMEOUT_MS) before exiting.
+ *   opts: { url, token, kind, have?, need?, cliVersion?, at? }
+ */
+function beacon(opts, done) {
+  var finished = false;
+  function finish() {
+    if (finished) return;
+    finished = true;
+    try { if (timer) clearTimeout(timer); } catch (e) {}
+    if (typeof done === "function") { try { done(); } catch (e) {} }
+  }
+  var timer = null;
+  try {
+    opts = opts || {};
+    if (!opts.url || !opts.token || !VALID_KINDS[opts.kind]) { finish(); return; }
+
+    var body = { event: "obstacle", kind: opts.kind };
+    if (opts.have) body.have = opts.have;
+    if (opts.need) body.need = opts.need;
+    if (opts.cliVersion) body.cliVersion = opts.cliVersion;
+    body.at = opts.at || Date.now();
+    var payload = JSON.stringify(body);
+
+    var endpoint = String(opts.url).replace(/\/+$/, "") + "/api/dev/activity";
+    var lib = endpoint.indexOf("http://") === 0 ? require("http") : require("https");
+
+    // A hard timeout guarantees the caller's exit (or await) is bounded even if
+    // the socket hangs — telemetry never holds a failing developer hostage.
+    timer = setTimeout(finish, TIMEOUT_MS);
+
+    var req = lib.request(
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: "Bearer " + opts.token,
+          "content-length": Buffer.byteLength(payload),
+        },
+      },
+      function (res) {
+        // Drain and finish — we don't care about the status, only that it was sent.
+        res.on("data", function () {});
+        res.on("end", finish);
+        res.on("error", finish);
+      }
+    );
+    req.on("error", finish);
+    req.write(payload);
+    req.end();
+  } catch (e) {
+    finish();
+  }
+}
+
+/** Promise wrapper for the ESM side (src/obstacle.mjs) so a failure path can await delivery. */
+function beaconAsync(opts) {
+  return new Promise(function (resolve) {
+    try { beacon(opts, resolve); } catch (e) { resolve(); }
+  });
+}
+
+module.exports = { parseActivityArgs: parseActivityArgs, beacon: beacon, beaconAsync: beaconAsync };

package/src/obstacle.mjs

@@ -0,0 +1,35 @@
+/**
+ * ESM front door to the obstacle beacon (src/obstacle-beacon.cjs). The post-login
+ * failure paths — `pnpm-missing`, `install-failed`, `clone-failed` — run on a
+ * supported Node where the bridge credential is already cached, so they resolve
+ * {url, token} from ~/.tot/credentials.json (the same source activityBridgeEnv +
+ * the heartbeat use) rather than argv. `node-too-old` does NOT come through here:
+ * it fires from the ES5 launcher pre-login, where creds may not exist yet.
+ *
+ * emitObstacle is awaited at the failure site so the packet is delivered before
+ * the process prints its `✗ … → next:` and exits — but it is fully swallowed, so
+ * telemetry can never disrupt or delay (past the beacon's own ~2s timeout) the
+ * error the developer actually needs to see.
+ */
+import beaconCore from "./obstacle-beacon.cjs";
+import { CLI_VERSION } from "./mcp.mjs";
+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"} kind
+ * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+export async function emitObstacle(kind, { have, need, env = process.env } = {}) {
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    const url = creds?.activityUrl;
+    const token = creds?.activityToken;
+    if (!url || !token) return;
+    await beaconCore.beaconAsync({ url, token, kind, have, need, cliVersion: CLI_VERSION });
+  } catch {
+    /* best-effort telemetry — never disrupts the error path */
+  }
+}