@tokenoftrust/cli 1.1.0 → 1.2.1

package/bin/tot.mjs

@@ -31,6 +31,7 @@ import { readFileSync } from "node:fs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
+import { maybeNotifyUpdate } from "../src/update-check.mjs";
 
 const BUILD_ORDER = ["checkout", "validate", "dev", "submit"];
 
@@ -166,6 +167,9 @@ async function main() {
       ms: Date.now() - startedAt,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
     });
+    // Nudge if a newer/unsupported version exists (drawn from cache — instant),
+    // and kick a detached registry refresh if stale. Never throws, never blocks.
+    maybeNotifyUpdate(VERSION);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.1.0",
+  "version": "1.2.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/auth.mjs

@@ -27,6 +27,7 @@ import {
   defaultCredentialsPath, readCredentials, writeCredentials, isExpired,
 } from "./token-store.mjs";
 import { refreshAccessToken, credentialsFromToken } from "./oauth.mjs";
+import { recordServerPolicy } from "./update-check.mjs";
 
 /** Thrown when no provider can authenticate — carries actionable guidance. */
 export class AuthUnavailableError extends Error {
@@ -60,11 +61,14 @@ export async function resolveSession(client, opts = {}) {
         { hint: "source apps/storefront/lib/resolve-tot-credentials.sh (from a storefront checkout), or unset --identity to use developer sign-in." },
       );
     }
-    await client.callTool("credential_validate", {
+    const validated = await client.callTool("credential_validate", {
       totApiKey: env.TOT_API_KEY,
       totSecretKey: env.TOT_SECRET_KEY,
       appDomain: env.TOT_APP_DOMAIN,
     });
+    // Update-awareness Layer 2: the MCP may attach a version-support policy to the
+    // authed response (wire contract: `cliPolicy`). Safe no-op when absent.
+    recordServerPolicy(validated?.cliPolicy, env);
     return { identity: "operator", appDomain: env.TOT_APP_DOMAIN };
   }
 

package/src/commands/whoami.mjs

@@ -13,6 +13,7 @@ import { defaultCredentialsPath, readCredentials, isExpired } from "../token-sto
 import { hasOperatorCreds, resolveDeveloperSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { normalizeStores } from "./checkout.mjs";
+import { recordServerPolicy } from "../update-check.mjs";
 
 /**
  * Pure summary of the cached session — no network. Returned for both display and
@@ -56,7 +57,11 @@ export async function run(argv, _ctx) {
     const client = createMcpClient(status.mcpUrl || env.MCP_BASE_URL || env.TOT_MCP_URL || "https://mcp.tokenoftrust.com");
     await client.initialize();
     await resolveDeveloperSession(client, env);
-    const stores = normalizeStores(await client.callTool("client_list", {}));
+    const listResp = await client.callTool("client_list", {});
+    // Update-awareness Layer 2: an authed response may carry a version-support
+    // policy (wire contract: `cliPolicy`). Safe no-op when absent.
+    recordServerPolicy(listResp?.cliPolicy, env);
+    const stores = normalizeStores(listResp);
     if (stores.length) {
       console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
     } else {

package/src/mcp.mjs

@@ -7,10 +7,26 @@
  * answer as JSON or as an SSE stream, with the session id carried in the
  * `Mcp-Session-Id` header across calls. Dependency-free (global fetch, Node 20+).
  */
+import { readFileSync } from "node:fs";
+
+// The CLI's REAL version for the MCP handshake — the transmission channel the
+// server-side support policy (update-awareness Layer 2) decides against. Read from
+// our own package.json (same pattern as bin/tot.mjs); best-effort, never throws.
+export const CLI_VERSION = (() => {
+  try {
+    return (
+      JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ||
+      "0.0.0"
+    );
+  } catch {
+    return "0.0.0";
+  }
+})();
 
 /**
  * @param {string} baseUrl - MCP base URL; `/mcp` is appended if absent.
- * @param {{ token?: string }} [opts] - optional developer OAuth bearer to attach.
+ * @param {{ token?: string, clientVersion?: string }} [opts] - optional developer OAuth
+ *   bearer to attach; `clientVersion` overrides the handshake version (tests).
  * @returns a small client: { mcpUrl, initialize, callRaw, callTool, sessionId(), setToken }
  */
 export function createMcpClient(baseUrl, opts = {}) {
@@ -86,7 +102,9 @@ export function createMcpClient(baseUrl, opts = {}) {
   }
 
   /** Complete the MCP handshake. Call once before any tool call. */
-  async function initialize(clientInfo = { name: "tot-cli", version: "0.1.0" }) {
+  async function initialize(
+    clientInfo = { name: "tot-cli", version: opts.clientVersion || CLI_VERSION },
+  ) {
     await callRaw("initialize", {
       protocolVersion: "2025-06-18",
       capabilities: {},

package/src/update-check-worker.mjs

@@ -0,0 +1,12 @@
+/**
+ * Detached worker for the update check: fetch the `latest` dist-tag from the npm
+ * registry and write it to `~/.tot/update-check.json`. Spawned unref'd by
+ * update-check.mjs's refreshInBackground() so the registry round-trip never adds
+ * latency to (or holds open) the user's actual `tot` command.
+ *
+ * Runs standalone (`node src/update-check-worker.mjs`), inheriting the parent env
+ * (TOT_HOME / TOT_NPM_REGISTRY). Best-effort: any failure just exits quietly.
+ */
+import { runRefresh } from "./update-check.mjs";
+
+runRefresh().finally(() => process.exit(0));

package/src/update-check.mjs

@@ -0,0 +1,217 @@
+/**
+ * Update awareness for `tot` — so an installed CLI can recognize when a newer
+ * (or a no-longer-supported) version exists and nudge the developer to upgrade.
+ *
+ * WHY THIS SHIPS NOW, not later: whatever nudge logic a published version carries
+ * is the FLOOR for that install. A client on today's version can never retroactively
+ * learn to nag — so the mechanism has to be present before the install base grows.
+ *
+ * Two layers, both baked in here:
+ *   • Layer 1 — client compare: fetch our own `latest` dist-tag from the npm registry
+ *     and compare to the running version. Answers "is there something newer?"
+ *   • Layer 2 — server policy: an authed command that talks to the MCP can hand us a
+ *     `{ minSupported, recommended, message }` policy (via recordServerPolicy). Answers
+ *     "is this version still SUPPORTED?" — a decision only the server can make. Because
+ *     the client just renders whatever policy it was last handed, we can raise a hard
+ *     floor years from now and even today's build will honor it. That render-what-the-
+ *     server-says hook is the part that must exist now; the policy stays editable forever.
+ *
+ * Contract (like activity-log / token-store):
+ *   • NEVER throws and NEVER blocks a command. The nudge is drawn from the LAST cached
+ *     result (instant, no network on the hot path); the registry refresh happens in a
+ *     DETACHED, unref'd child so it can't add latency or hold the process open.
+ *   • Cached in `~/.tot/update-check.json`; refreshed at most once per CHECK_INTERVAL_MS.
+ *   • Suppressed when stderr isn't a TTY, in CI, or when TOT_NO_UPDATE_CHECK /
+ *     NO_UPDATE_NOTIFIER is set. `TOT_HOME` overrides the home dir (tests).
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/** Refresh the registry check at most this often. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+
+const PKG = "@tokenoftrust/cli";
+const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+const FETCH_TIMEOUT_MS = 3000;
+
+/** Absolute path to the update-check cache for this environment. */
+export function updateCachePath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "update-check.json");
+}
+
+function readCache(env) {
+  try {
+    return JSON.parse(readFileSync(updateCachePath(env), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Merge-write the cache atomically (0600 in a 0700 dir). Never throws. */
+export function writeCache(patch, env = process.env) {
+  try {
+    const filePath = updateCachePath(env);
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const next = { ...(readCache(env) || {}), ...patch };
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+    renameSync(tmp, filePath);
+    chmodSync(filePath, 0o600);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * True if `latest` is a strictly higher release than `current`, comparing the
+ * numeric major.minor.patch only (a prerelease suffix is ignored — we never nudge
+ * a stable user onto a prerelease). Malformed input compares as not-newer.
+ */
+export function isNewer(latest, current) {
+  const parts = (s) =>
+    String(s || "").split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const a = parts(latest);
+  const b = parts(current);
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+/**
+ * Decide what (if anything) to tell the user, from the cached state only.
+ * Returns null or { level: "required"|"recommended"|"available", latest, message? }.
+ * Server policy (Layer 2) outranks the plain client compare (Layer 1).
+ */
+export function updateNotice(current, env = process.env) {
+  const cache = readCache(env);
+  if (!cache) return null;
+
+  const policy = cache.policy;
+  if (policy) {
+    if (policy.minSupported && isNewer(policy.minSupported, current)) {
+      return {
+        level: "required",
+        latest: policy.recommended || cache.latest || policy.minSupported,
+        message: policy.message,
+      };
+    }
+    if (policy.recommended && isNewer(policy.recommended, current)) {
+      return { level: "recommended", latest: policy.recommended, message: policy.message };
+    }
+  }
+
+  if (cache.latest && isNewer(cache.latest, current)) {
+    return { level: "available", latest: cache.latest };
+  }
+  return null;
+}
+
+/** House-style stderr nudge for a notice. */
+export function renderNotice(notice, current) {
+  const to = notice.latest ? ` ${current} → ${notice.latest}` : "";
+  const upgrade = `  npm i -g ${PKG}`;
+  if (notice.level === "required") {
+    return [
+      `\n✗ This version of \`tot\` (${current}) is no longer supported.`,
+      notice.message ? `  ${notice.message}` : null,
+      `  → update to continue:${upgrade}`,
+      "",
+    ]
+      .filter((l) => l !== null)
+      .join("\n");
+  }
+  const head =
+    notice.level === "recommended"
+      ? `\n▸ A recommended update to \`tot\` is available (${current} → ${notice.latest}).`
+      : `\n▸ Update available for \`tot\`:${to}`;
+  return [head, notice.message ? `  ${notice.message}` : null, `  →${upgrade}`, ""]
+    .filter((l) => l !== null)
+    .join("\n");
+}
+
+/** Whether we should print a nudge at all in this environment. */
+export function shouldShowNudge(env = process.env, stream = process.stderr) {
+  if (env.TOT_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER) return false;
+  if (env.CI) return false;
+  if (!stream || !stream.isTTY) return false;
+  return true;
+}
+
+function cacheIsFresh(env) {
+  const cache = readCache(env);
+  if (!cache || typeof cache.checkedAt !== "number") return false;
+  return Date.now() - cache.checkedAt < CHECK_INTERVAL_MS;
+}
+
+/**
+ * Fetch the `latest` dist-tag from the registry and write it to the cache. Used by
+ * the detached worker; also directly callable/testable. Never throws.
+ */
+export async function runRefresh(env = process.env) {
+  try {
+    const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
+    const metaUrl = `${registry}/${PKG.replace("/", "%2f")}`;
+    const res = await fetch(metaUrl, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return;
+    const meta = await res.json();
+    const latest = meta?.["dist-tags"]?.latest;
+    if (latest) writeCache({ latest, checkedAt: Date.now() }, env);
+  } catch {
+    /* best-effort: offline / timeout / bad JSON — just skip */
+  }
+}
+
+/**
+ * Record a server-issued support policy (Layer 2). Call this from any command that
+ * receives version guidance back from the MCP. `policy` is
+ * { minSupported?, recommended?, message? }. Never throws.
+ */
+export function recordServerPolicy(policy, env = process.env) {
+  if (policy && typeof policy === "object") writeCache({ policy }, env);
+}
+
+/**
+ * Spawn the cache refresh in a DETACHED, unref'd child so it never delays this
+ * process or holds it open. Skips when the cache is still fresh. Never throws.
+ */
+function refreshInBackground(env) {
+  try {
+    if (cacheIsFresh(env)) return;
+    const worker = fileURLToPath(new URL("./update-check-worker.mjs", import.meta.url));
+    const child = spawn(process.execPath, [worker], {
+      detached: true,
+      stdio: "ignore",
+      env,
+    });
+    child.unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Top-level entry: draw a nudge from the last cached result (instant), then kick a
+ * background refresh if stale. Call once per invocation, e.g. as the CLI exits.
+ * Never throws, never blocks.
+ */
+export function maybeNotifyUpdate(current, env = process.env, { stream = process.stderr } = {}) {
+  try {
+    if (shouldShowNudge(env, stream)) {
+      const notice = updateNotice(current, env);
+      if (notice) stream.write(`${renderNotice(notice, current)}\n`);
+    }
+  } catch {
+    /* never break a command over a nudge */
+  }
+  refreshInBackground(env);
+}