@tokenoftrust/cli 1.2.4 → 1.3.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.2.4",
+  "version": "1.3.0-rc.1",
   "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/activity-log.mjs

@@ -25,7 +25,7 @@ import { join, dirname } from "node:path";
 export const MAX_ENTRIES = 300;
 
 // Flags whose FOLLOWING token is a secret and must never be logged.
-const SECRET_VALUE_FLAGS = new Set(["--code", "--token"]);
+const SECRET_VALUE_FLAGS = new Set(["--code", "--token", "--activity-token"]);
 
 /** Absolute path to the activity log for this environment. */
 export function activityLogPath(env = process.env) {
@@ -41,7 +41,7 @@ export function redactArgs(args) {
   const out = [];
   for (let i = 0; i < args.length; i++) {
     const a = String(args[i]);
-    const eq = a.match(/^(--code|--token)=/);
+    const eq = a.match(/^(--code|--token|--activity-token)=/);
     if (eq) {
       out.push(`${eq[1]}=«redacted»`);
       continue;

package/src/commands/dev.mjs

@@ -39,10 +39,11 @@ import { createHash } from "node:crypto";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
-import { createMcpClient } from "../mcp.mjs";
+import { createMcpClient, CLI_VERSION } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
+import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
-import { openBrowser, waitForServer } from "../open.mjs";
+import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import {
   scaffoldSample, isSampleCheckout, sampleConfig,
   resolveRendererSource as resolveLocalRendererSource, SAMPLE_DIR_NAME,
@@ -97,13 +98,19 @@ preview — nothing is published. Prerequisites: Node.js and an invite (or just
 --sample, which needs neither) — no Docker, no hand-provisioned AWS creds.`;
 
 /** @param {string[]} argv @param {any} ctx */
-export function run(argv, ctx) {
+export async function run(argv, ctx) {
   const args = parseArgs(argv);
   if (args.help) {
     console.log(USAGE);
     return 0;
   }
 
+  // Resolve a free port up front so the URL we derive/open/print matches the port
+  // the runner actually binds — Vite's strictPort is off, so a busy default would
+  // silently drift and strand the browser/liveness poll on the wrong port. No-op
+  // when the requested port is free. (Monorepo re-resolves inside tot-dev.mjs.)
+  args.port = String(await firstFreePort(Number(args.port || 4321)));
+
   // Zero-login free taste: scaffold + run a bundled sample store, no MCP. Wins
   // over every context (works in the monorepo, a checkout, or a loose dir).
   if (args.sample) {
@@ -203,8 +210,19 @@ function runMonorepo(ctx, argv) {
     console.error(`✗ expected the dev runner at ${script} but it's missing.`);
     return 2;
   }
+  // Thread the hosted-activity-bridge credential (if this cached session has one —
+  // minted alongside the invite's cli-signin-code paste) so the spawned tot-dev.mjs
+  // can report file-save activity up to the developer's own hosted /dev panel.
+  // Best-effort: an older cached session (or a bare `tot login`) simply has
+  // neither field, and the local loop runs exactly as before with no hosted signal.
+  const creds = readCredentials(defaultCredentialsPath(process.env));
+  const env = { ...process.env };
+  if (creds?.activityToken && creds?.activityUrl) {
+    env.TOT_DEV_ACTIVITY_TOKEN = creds.activityToken;
+    env.TOT_DEV_ACTIVITY_URL = creds.activityUrl;
+  }
   return new Promise((resolvePromise) => {
-    const child = spawn(process.execPath, [script, ...argv], { stdio: "inherit" });
+    const child = spawn(process.execPath, [script, ...argv], { stdio: "inherit", env });
     child.on("exit", (code) => resolvePromise(code ?? 0));
     child.on("error", (e) => {
       console.error(`✗ could not start the dev runner: ${e.message}`);
@@ -227,17 +245,6 @@ export function deriveUrl(cfg, port) {
   return { domain, url: `http://localhost:${port}/${domain ? `${domain}/` : ""}` };
 }
 
-/**
- * The URL the developer should LAND on: the guided /dev cockpit, not the bare
- * store root. The cockpit embeds a live preview of the store (so they still see
- * it) PLUS the stepper, live Monitor, in-browser file tree/editor/diff, and
- * click-to-source — the whole first-run experience. `deriveUrl().url` (the store
- * root) stays the liveness-poll target (waitForServer); this is what we open + show.
- */
-export function cockpitUrl(baseUrl) {
-  return `${baseUrl}dev`;
-}
-
 async function runNative(workspace, args, ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
@@ -273,7 +280,7 @@ function bootNative(runnerDir, workspace, port, url, args) {
       .then((up) => {
         if (up && !opened) {
           opened = true;
-          openBrowser(cockpitUrl(url));
+          openBrowser(url);
         }
       })
       .catch(() => {});
@@ -347,24 +354,82 @@ export async function resolveRendererSource(args, { client } = {}) {
   return resolveEntitledRendererSource(args, { client });
 }
 
+/**
+/**
+ * Choose which published runner version to fetch, given npm registry metadata.
+ *
+ * The CLI and runner are COUPLED (the CLI spawns the runner's scripts/tot-dev.mjs
+ * + shares the /__tot contract), so by default we pin the runner to the CLI's OWN
+ * minor — the highest published `<major>.<minor>.x` — NOT npm's `latest`. That
+ * keeps a `tot@X.Y` always driving a `runner@X.Y.*`, and because the on-disk cache
+ * is keyed by version, upgrading the CLI busts the stale-runner cache automatically
+ * (the 2026-07-14 "cached runner (prior tot dev)" staleness).
+ *
+ * GRACEFUL + SEQUENCING-SAFE: an explicit pin (`--renderer-version` / TOT_RUNNER_VERSION)
+ * always wins. Otherwise we prefer the CLI-minor match, and FALL BACK to the `latest`
+ * dist-tag when no aligned version is published yet — so this is safe to ship BEFORE
+ * the runner is republished at CLI-aligned versions (today runner=0.1.x, cli=1.2.x →
+ * no 1.2 match → falls back to latest). Once the coupled publish lands, the pin
+ * activates on its own with no further code change.
+ *
+ * Pure (no I/O) for testability.
+ * @param {any} meta npm packument (`dist-tags` + `versions`)
+ * @param {{ cliVersion: string, explicitPin?: string|null }} opts
+ * @returns {{ version: string, reason: string }}
+ */
+export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
+  const distTags = meta?.["dist-tags"] || {};
+  const versions = Object.keys(meta?.versions || {});
+
+  // 1) Explicit pin (flag/env): resolve a dist-tag name, else take it verbatim.
+  if (explicitPin) {
+    return { version: distTags[explicitPin] || explicitPin, reason: `pinned ${explicitPin}` };
+  }
+
+  // 2) EXACT CLI-version match — the primary path for a lockstep release: the runner
+  // is published at the SAME version as the CLI (incl. prereleases like 1.3.0-rc.0,
+  // which the stable-only minor match below deliberately skips). This is what makes
+  // `tot@1.3.0-rc.0` pull `runner@1.3.0-rc.0` instead of falling back to stale latest.
+  if (versions.includes(cliVersion)) {
+    return { version: cliVersion, reason: "exact CLI-version match" };
+  }
+
+  // 3) CLI-minor match: highest published <major>.<minor>.* (numeric patch order).
+  const m = /^(\d+)\.(\d+)\./.exec(cliVersion || "");
+  if (m) {
+    const prefix = `${m[1]}.${m[2]}.`;
+    const inMinor = versions
+      .filter((v) => v.startsWith(prefix) && /^\d+\.\d+\.\d+$/.test(v))
+      .sort((a, b) => Number(a.slice(prefix.length)) - Number(b.slice(prefix.length)));
+    if (inMinor.length) {
+      return { version: inMinor[inMinor.length - 1], reason: `matched CLI minor ${m[1]}.${m[2]}` };
+    }
+  }
+
+  // 4) Fallback: the `latest` dist-tag (pre-alignment safety net).
+  if (distTags.latest) return { version: distTags.latest, reason: "fell back to latest (no CLI-minor match)" };
+  throw new Error("no publishable runner version (no CLI-minor match and no `latest` dist-tag)");
+}
+
 /**
  * PUBLIC, un-entitled source for sample / zero-login mode: the runner
  * straight from the public npm registry — NO MCP call, NO entitlement. Reads the
  * package's registry metadata (unauthenticated JSON) for the tarball URL + version.
- * Pin with `--renderer-version` / TOT_RUNNER_VERSION, else the `latest` dist-tag.
- * Package/registry overridable via env for testing.
+ * Version selection is pinned to the CLI's minor by default (see pickRunnerVersion);
+ * override with `--renderer-version` / TOT_RUNNER_VERSION. Package/registry
+ * overridable via env for testing.
  */
 export async function resolvePublicRendererSource(args, env = process.env) {
   const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
   const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
-  const pin = args.rendererVersion || env.TOT_RUNNER_VERSION || "latest";
+  const explicitPin = args.rendererVersion || env.TOT_RUNNER_VERSION || null;
   const metaUrl = `${registry}/${pkg.replace("/", "%2f")}`;
   const res = await fetch(metaUrl, { headers: { accept: "application/json" } });
   if (!res.ok) {
     throw new Error(`npm metadata for ${pkg} failed: HTTP ${res.status} ${res.statusText}`);
   }
   const meta = await res.json();
-  const version = meta?.["dist-tags"]?.[pin] || pin;
+  const { version } = pickRunnerVersion(meta, { cliVersion: CLI_VERSION, explicitPin });
   const tarball = meta?.versions?.[version]?.dist?.tarball;
   if (!tarball) throw new Error(`no published ${pkg}@${version} on npm`);
   return { kind: "public", version, url: tarball, strip: 1, cacheKey: `public-${version}` };
@@ -665,7 +730,7 @@ async function runContainer(workspace, args, ctx) {
       .then((up) => {
         if (up && !opened) {
           opened = true;
-          openBrowser(cockpitUrl(plan.url));
+          openBrowser(plan.url);
         }
       })
       .catch(() => {});
@@ -742,7 +807,7 @@ export function buildContainerPlan(workspace, args, _ctx) {
 /** The crafted "here's your running store" block (Vite/`vercel dev`-grade). */
 export function printDevBanner(plan) {
   console.error(`\n  tot dev — ${plan.tenant || "(tenant)"}`);
-  console.error(`  ➜  Local:    ${cockpitUrl(plan.url)}`);
+  console.error(`  ➜  Local:    ${plan.url}`);
   console.error(`  ➜  Edit:     content/home.html + save → the browser reloads`);
   console.error(`  ➜  Private local preview — nothing is published. Ctrl-C to stop.\n`);
 }

package/src/commands/login.mjs

@@ -27,17 +27,37 @@ import { fail } from "../errors.mjs";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
-  const a = { mcp: null, device: false, code: null, help: false };
+  const a = {
+    mcp: null, device: false, code: null, help: false,
+    activityToken: null, activityUrl: null,
+  };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--device") a.device = true;
     else if (t === "--code" || t === "--token") a.code = argv[++i];
+    else if (t === "--activity-token") a.activityToken = argv[++i];
+    else if (t === "--activity-url") a.activityUrl = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
 }
 
+/**
+ * Cache the local→hosted activity-bridge credential (storefront's
+ * cli-signin-code mint, piggybacked as two extra login flags — see
+ * apps/storefront/src/lib/dev/cliSignInCode.ts) alongside the MCP creds
+ * `tot login` just wrote. `tot dev` reads these two fields to report file
+ * saves to the developer's own hosted /dev panel. A no-op when either flag is
+ * absent (older invite links, or a bare `tot login`).
+ */
+function cacheActivityBridge(env, activityToken, activityUrl) {
+  if (!activityToken || !activityUrl) return;
+  const path = defaultCredentialsPath(env);
+  const current = readCredentials(path) || {};
+  writeCredentials(path, { ...current, activityToken, activityUrl });
+}
+
 const USAGE = `tot login — sign in to Token of Trust
 
   tot login                 open the browser, sign in, cache your session
@@ -48,6 +68,10 @@ const USAGE = `tot login — sign in to Token of Trust
                             browser opener exists on this box)
   tot login --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
+  --activity-token/--activity-url are set automatically by the pasted invite
+  command (report local dev-loop activity to your hosted /dev panel) — not
+  meant to be typed by hand.
+
 After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
 
 /**
@@ -110,6 +134,7 @@ export async function run(argv, _ctx) {
     console.error(`~ signing in to Token of Trust with your invite code (${mcpUrl})`);
     try {
       await redeemAndCache(mcpUrl, args.code, env);
+      cacheActivityBridge(env, args.activityToken, args.activityUrl);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
       console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
       return 0;

package/src/commands/start.mjs

@@ -52,14 +52,14 @@ import { detectContext } from "../context.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
-import { openBrowser, waitForServer } from "../open.mjs";
+import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { collectChecks } from "./doctor.mjs";
 import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
-  ensureRendererArtifact, ensureSampleRenderer, spawnNativeDev, deriveUrl, cockpitUrl,
+  ensureRendererArtifact, ensureSampleRenderer, spawnNativeDev, deriveUrl,
   NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
@@ -209,8 +209,10 @@ export async function run(argv, ctx) {
     // Both are independent authenticated calls once login (above) has
     // resolved, so there's no reason to pay for them serially.
     const dir = resolve(process.cwd(), tenant);
+    // Resolve a free port so the URL we open/poll/print matches what the runner
+    // binds (Vite strictPort is off → a busy port would drift). No-op if free.
     const devArgs = {
-      image: null, port: String(args.port || "4321"), mcp: args.mcp,
+      image: null, port: String(await firstFreePort(Number(args.port || 4321))), mcp: args.mcp,
       noLogin: false, noOpen: args.noOpen, docker: args.docker,
     };
     const runtime = { useDocker: args.docker, runnerDir: null };
@@ -244,17 +246,15 @@ export async function run(argv, ctx) {
       });
     }
     if (!args.noOpen) {
-      openBrowser(cockpitUrl(url));
+      openBrowser(url);
       console.log("  ✓ opened your browser");
     }
 
-    // 6. you're live (G) — end at the AI-wow, THEN offer the MCP (C). Print the
-    // elapsed time (A3) so the "instant" claim is measured, not just felt.
-    printLiveEnding(tenant, cockpitUrl(url), formatElapsed(Date.now() - startedAt));
-    if (!args.noConnect) {
-      const yes = args.yes || (await promptYesNo("  Connect Claude for AI editing?", true));
-      if (yes) connectClaude();
-    }
+    // 6. you're live (G) — land on the store ROOT (not /dev), print elapsed time
+    // (A3) so the "instant" claim is measured. The "Connect Claude" step is
+    // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
+    // tore down the dev server; revisit AI-connect as a non-blocking step later.
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt));
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Streaming dev logs — edit + save to see reloads. Ctrl-C to stop.\n");
@@ -317,16 +317,14 @@ async function runSampleStart(args, ctx, env, startedAt) {
       });
     }
     if (!args.noOpen) {
-      openBrowser(cockpitUrl(url));
+      openBrowser(url);
       console.log("  ✓ opened your browser");
     }
 
-    // You're live — the FREE preview. End on the MCP upsell (the whole point).
-    printSampleLiveEnding(cockpitUrl(url), formatElapsed(Date.now() - startedAt));
-    if (!args.noConnect) {
-      const yes = args.yes || (await promptYesNo("  Connect the ToT MCP for your real store + AI editing?", true));
-      if (yes) connectClaude();
-    }
+    // You're live — the FREE preview, landing on the store ROOT (not /dev). The
+    // AI/MCP connect step is intentionally removed for now — revisit as a
+    // non-blocking step later (see the run() note above).
+    printSampleLiveEnding(url, formatElapsed(Date.now() - startedAt));
 
     console.log("\n  Streaming preview logs — edit content/*.html + save to see reloads. Ctrl-C to stop.\n");
     handle.child.stdout?.pipe(process.stdout);

package/src/open.mjs

@@ -8,8 +8,41 @@
  * Dependency-free (global fetch, node:child_process, Node 20+).
  */
 import { spawn } from "node:child_process";
+import net from "node:net";
 import { setTimeout as delay } from "node:timers/promises";
 
+/**
+ * Is `port` free to bind? Resolves false if anything already holds it. Host omitted
+ * → Node binds dual-stack (::/0.0.0.0), matching how the dev server grabs the port.
+ * Mirror of scripts/dev/port-check.mjs (separate package — kept dependency-free).
+ * @param {number} port @returns {Promise<boolean>}
+ */
+export function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    try {
+      srv.listen(port);
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * First free port at or after `preferred`. Lets the CLI derive the URL it opens +
+ * polls from the SAME port the runner will bind — Vite's strictPort is off, so a
+ * busy default port would otherwise drift and strand the liveness poll (2026-07-14).
+ * @param {number} preferred @param {number} [maxTries] @returns {Promise<number>}
+ */
+export async function firstFreePort(preferred, maxTries = 64) {
+  for (let p = preferred; p < preferred + maxTries; p++) {
+    if (await isPortFree(p)) return p;
+  }
+  return preferred;
+}
+
 /**
  * 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

package/src/token-store.mjs

@@ -6,11 +6,17 @@
  * a later command needs to authenticate AND to silently refresh:
  *
  *   { mcpUrl, clientId, tokenEndpoint, scope,
- *     accessToken, refreshToken, expiresAt (epoch ms), obtainedAt }
+ *     accessToken, refreshToken, expiresAt (epoch ms), obtainedAt,
+ *     activityToken, activityUrl }
  *
  * We persist `clientId` + `tokenEndpoint` so a refresh needs no re-discovery /
  * re-registration, and `mcpUrl` so we never present a token minted for one MCP
- * to a different one. Dependency-free (node:fs/os/path).
+ * to a different one. `activityToken`/`activityUrl` are a SEPARATE credential
+ * (storefront-issued, not MCP OAuth) that `tot login --code` caches when the
+ * invite paste carries it — see commands/login.mjs `cacheActivityBridge` and
+ * commands/dev.mjs `runMonorepo`, which threads them to the local dev-loop
+ * process so it can report file saves to the developer's hosted /dev panel.
+ * Dependency-free (node:fs/os/path).
  *
  * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).
  */