@tokenoftrust/cli 1.4.0-rc.4 → 1.4.0-rc.5

package/bin/tot.mjs

@@ -8,6 +8,7 @@
  *   tot login                 sign in to Token of Trust (OAuth)          ← built (MCP OAuth PKCE loopback; caches ~/.tot/credentials.json)
  *   tot logout                sign out (clear the cached session)        ← built (deletes ~/.tot/credentials.json; local-only, no server revoke)
  *   tot whoami                who you're signed in as                    ← built
+ *   tot link                  link your identity to the ToT broker (resolve store scope)  ← built
  *   tot grants                capability/tier/expiry per store you can act on  ← built (introspection diagnostics)
  *   tot checkout [<tenant>]   clone a store you can build on            ← built
  *   tot validate              lint your store before you submit         ← built
@@ -53,6 +54,7 @@ tot — Token of Trust developer CLI
   tot login                 sign in to Token of Trust
   tot logout                sign out (clear the cached session)
   tot whoami                show who you're signed in as
+  tot link                  link your identity so your stores resolve
   tot grants                capability/tier/expiry per store you can act on
   tot checkout [<tenant>]   clone a store you can build on
   tot validate              lint your store before you submit
@@ -109,6 +111,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "link") {
+    const { run } = await import("../src/commands/link.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "doctor") {
     const { run } = await import("../src/commands/doctor.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.4",
+  "version": "1.4.0-rc.5",
   "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

@@ -308,6 +308,86 @@ export function storeListError(list) {
   return null;
 }
 
+/**
+ * Extract card c1's broker-identity remediation signal from a `client_list`
+ * result. When the identity resolved ZERO stores, the server MAY carry:
+ *   - `brokerStatus`: 'unlinked' | 'unconfigured' | 'broker_error' — present only
+ *      when the empty scope is a BROKER-IDENTITY problem (not an entitlement one);
+ *      ABSENT for the genuine linked-but-zero-grants case.
+ *   - `nextAction`: a status-specific human remediation string the server owns
+ *      (single source of truth; e.g. an unlinked identity is told to finish
+ *      linking, an operator sees a diagnostic, zero-grants sees NO_TENANTS_MESSAGE).
+ * Returns { brokerStatus, nextAction } with nulls when absent. Pure + exported so
+ * it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @returns {{ brokerStatus: string|null, nextAction: string|null }}
+ */
+export function brokerRemediation(list) {
+  const c = list && typeof list === "object" && !Array.isArray(list) ? list : null;
+  const brokerStatus = c && typeof c.brokerStatus === "string" ? c.brokerStatus : null;
+  const nextAction =
+    c && typeof c.nextAction === "string" && c.nextAction.trim() ? c.nextAction.trim() : null;
+  return { brokerStatus, nextAction };
+}
+
+/**
+ * Status-aware human guidance for an authenticated identity that resolved ZERO
+ * stores (card c2 — the fix for the misleading "may still be propagating / ask for
+ * a store invite" copy that dead-ended an UNLINKED identity). Driven by card c1's
+ * `brokerStatus`/`nextAction`:
+ *   - `unlinked` → the identity isn't linked to the ToT broker yet, so no scope can
+ *      resolve. This is NOT an entitlement problem — point at `tot link` (the
+ *      terminal action), NOT "ask for a store invite".
+ *   - `unconfigured` | `broker_error` → an operator/diagnostic condition; surface
+ *      the server's own `nextAction`, never "ask for an invite".
+ *   - no brokerStatus → the genuine linked-but-zero-grants case; keep the existing
+ *      "invite may still be propagating / ask for one" wording (NO_TENANTS_MESSAGE),
+ *      preferring the server's `nextAction` when present.
+ *
+ * Prefers the server's `nextAction` as the concrete `next` step (single source of
+ * truth) and falls back to sensible local copy when it's absent (older server).
+ * `linkHint` names the terminal action an unlinked identity is pointed at — the
+ * built-in `tot link`; a caller that didn't build `tot link` passes an MCP-client
+ * phrasing instead. Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @param {{ linkHint?: string }} [opts]
+ * @returns {{ brokerStatus: string|null, headline: string, next: string }}
+ */
+export function noStoresGuidance(list, { linkHint = "tot link" } = {}) {
+  const { brokerStatus, nextAction } = brokerRemediation(list);
+
+  if (brokerStatus === "unlinked") {
+    // The actionable terminal step beats the server's identity_link_begin/poll
+    // MCP-tool wording for a CLI user, so lead with `tot link` (c2 optional-arm
+    // directive). Fall back to the server string only if there's no link action.
+    return {
+      brokerStatus,
+      headline: "your Token of Trust identity isn't linked yet, so no stores could be resolved",
+      next: linkHint
+        ? `run \`${linkHint}\` to finish linking your identity, then re-run`
+        : nextAction || "finish linking your identity (identity_link_begin), then re-run",
+    };
+  }
+  if (brokerStatus === "unconfigured" || brokerStatus === "broker_error") {
+    // Operator/diagnostic conditions — surface the server's own words; do NOT tell
+    // the developer to "ask for an invite" (it isn't an entitlement problem).
+    return {
+      brokerStatus,
+      headline: "no stores could be resolved — the Token of Trust identity broker had a problem",
+      next: nextAction || "run `tot whoami` for details, or contact your Token of Trust operator",
+    };
+  }
+  // No brokerStatus → the genuine linked-but-zero-grants case.
+  return {
+    brokerStatus: null,
+    headline: "you have no stores to build on yet",
+    next:
+      nextAction ||
+      "if you were just invited, it may still be propagating — try again in a minute; " +
+        "otherwise ask your Token of Trust contact for a store invite (see `tot whoami`)",
+  };
+}
+
 function printClientList(list) {
   const err = storeListError(list);
   const stores = normalizeStores(list);
@@ -317,9 +397,12 @@ function printClientList(list) {
     return;
   }
   if (stores.length === 0) {
-    console.log("\nNo stores available to build on for this identity yet.");
-    console.log("If you were just invited, it may still be propagating — try again in a minute.");
-    if (list && !Array.isArray(list)) console.log(JSON.stringify(list, null, 2));
+    // Status-aware, human-readable guidance — NEVER a raw JSON dump (the old
+    // behaviour, James's 2026-07-19 failure mode).
+    const g = noStoresGuidance(list);
+    const line = g.headline.charAt(0).toUpperCase() + g.headline.slice(1);
+    console.log(`\n${line}.`);
+    console.log(`Next: ${g.next}`);
     return;
   }
   console.log("\nStores you can build on:\n");

package/src/commands/link.mjs

@@ -0,0 +1,217 @@
+/**
+ * `tot link` — link your signed-in Token of Trust identity to the ToT identity
+ * broker so your store scope can be resolved.
+ *
+ * Some developers sign in fine (a valid ToT OAuth session) but their identity
+ * isn't yet linked to the broker that maps a person → the tenants they can build
+ * on — so `tot start` / `tot checkout` / `tot whoami` resolve ZERO stores. That's
+ * NOT a "you weren't invited" problem and NOT "the invite is still propagating";
+ * it's a one-time link step. This command drives it end-to-end from the terminal:
+ *
+ *   identity_link_begin           → the MCP returns an authUrl + a poll handle
+ *   open the authUrl              → you approve the link in the browser
+ *   identity_link_poll(handle)    → we poll until it's linked, then confirm scope
+ *
+ * It reuses the SAME auth ceremony as the rest of the CLI (establishSession — the
+ * cached `tot login` session, offering an inline sign-in when there's none and
+ * we're on a TTY), so a not-signed-in developer isn't dead-ended.
+ *
+ * Dependency-free (node built-ins via mcp.mjs / auth.mjs / open.mjs).
+ */
+import { setTimeout as delay } from "node:timers/promises";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { offerSignIn } from "./login.mjs";
+import { openBrowser } from "../open.mjs";
+import { CliError, fail, formatError } from "../errors.mjs";
+import { normalizeStores } from "./checkout.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+function parseArgs(argv) {
+  const a = { mcp: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot link — link your Token of Trust identity so your stores resolve
+
+  tot link                  open the browser, approve the link, confirm your scope
+  tot link --mcp <url>      MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+Run this when \`tot whoami\` / \`tot start\` say your identity isn't linked yet.`;
+
+/**
+ * Tolerant extraction of the fields `identity_link_begin` returns. The link URL
+ * and poll handle field names can vary by server version, so probe the known
+ * candidates (the `pollHandle` name is fixed by the identity_link_poll contract).
+ * Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} res
+ * @returns {{ authUrl: string|null, pollHandle: string|null }}
+ */
+export function linkBeginFields(res) {
+  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  const authUrl =
+    c.authUrl ||
+    c.url ||
+    c.verificationUrl ||
+    c.verificationUriComplete ||
+    c.verification_uri_complete ||
+    null;
+  const pollHandle = c.pollHandle || c.handle || c.poll_handle || c.pollHandleId || null;
+  return {
+    authUrl: typeof authUrl === "string" && authUrl ? authUrl : null,
+    pollHandle: typeof pollHandle === "string" && pollHandle ? pollHandle : null,
+  };
+}
+
+/**
+ * Classify an `identity_link_poll` result into 'linked' | 'pending' | a raw error
+ * status. Tolerant of the shape (a boolean flag, or a status/state string) so a
+ * server-version drift doesn't strand the poll. Pure + exported for unit tests.
+ * @param {unknown} res
+ * @returns {"linked"|"pending"|string}
+ */
+export function linkPollStatus(res) {
+  const c = res && typeof res === "object" && !Array.isArray(res) ? res : {};
+  if (c.linked === true || c.done === true || c.complete === true) return "linked";
+  const raw =
+    (typeof c.status === "string" && c.status) || (typeof c.state === "string" && c.state) || "";
+  const s = raw.toLowerCase();
+  if (!s) return "pending";
+  if (/^(linked|complete|completed|done|ok|success|active)$/.test(s)) return "linked";
+  if (/^(pending|waiting|in_?progress|processing|started)$/.test(s)) return "pending";
+  return s; // an unknown/error status — surfaced to the caller
+}
+
+/** @param {string[]} argv @param {any} _ctx */
+export async function run(argv, _ctx) {
+  const env = process.env;
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+
+  try {
+    // Same auth ordering as checkout/start — developer bearer BEFORE initialize —
+    // and the same inline sign-in offer so a not-signed-in dev isn't dead-ended.
+    try {
+      await establishSession(client, { env });
+    } catch (e) {
+      if (e instanceof AuthUnavailableError && e.reason === "missing") {
+        const signedIn = await offerSignIn(client.mcpUrl, env, {});
+        if (!signedIn) throw e;
+        await establishSession(client, { env });
+      } else {
+        throw e;
+      }
+    }
+    console.error(`~ signed in → ${client.mcpUrl}`);
+
+    console.error("~ identity_link_begin — asking Token of Trust to start the link");
+    let begin;
+    try {
+      begin = await client.callTool("identity_link_begin", {});
+    } catch (e) {
+      throw new CliError(`couldn't start the identity link: ${String(e?.message || e)}`, {
+        next: "your MCP may not support `tot link` yet — run `tot whoami` for the current guidance",
+      });
+    }
+    const { authUrl, pollHandle } = linkBeginFields(begin);
+    if (!pollHandle) {
+      throw new CliError("Token of Trust didn't return a link handle to poll", {
+        next: "re-run `tot link`, or run `tot whoami` for the current guidance",
+      });
+    }
+
+    if (authUrl) {
+      const opened = openBrowser(authUrl);
+      console.log(
+        opened
+          ? `\n+ opening your browser to finish linking:\n  ${authUrl}`
+          : `\nOpen this URL to finish linking your identity:\n  ${authUrl}`,
+      );
+    } else {
+      console.log("\n+ finishing the link — no approval step needed …");
+    }
+
+    const linked = await pollLink(client, pollHandle, {
+      log: (m) => console.error(m),
+    });
+    if (!linked) {
+      throw new CliError("the identity link didn't complete in time", {
+        next: "finish the approval in your browser, then re-run `tot link`",
+      });
+    }
+
+    console.log("\n+ your identity is linked.");
+    // Confirm scope now resolves — best-effort, so a transient list hiccup doesn't
+    // fail an otherwise-successful link.
+    try {
+      const list = await client.callTool("client_list", {});
+      const stores = normalizeStores(list);
+      if (stores.length) {
+        console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
+        console.log("  Next: `tot start` (or `tot checkout <tenant>`).");
+      } else {
+        console.log("  Next: `tot start` — if it still shows no stores, ask your ToT contact for a store invite.");
+      }
+    } catch {
+      console.log("  Next: `tot start` to build your store.");
+    }
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError || e instanceof CliError) {
+      console.error(formatError(e));
+      return e instanceof CliError ? (e.exitCode ?? 1) : 1;
+    }
+    console.error(fail(`link failed: ${String(e?.message || e)}`));
+    return 1;
+  }
+}
+
+/**
+ * Poll `identity_link_poll(pollHandle)` until the link is complete, or give up
+ * after `timeoutMs`. Returns true on 'linked', false on timeout; throws a CliError
+ * on a definite error status the server reports. Injectable clock/interval keep it
+ * unit-testable, but the default path is the live poll.
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {string} pollHandle
+ * @param {{ timeoutMs?: number, intervalMs?: number, log?: (m:string)=>void }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function pollLink(client, pollHandle, { timeoutMs = 120000, intervalMs = 2500, log = () => {} } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let announced = false;
+  while (Date.now() < deadline) {
+    let res;
+    try {
+      res = await client.callTool("identity_link_poll", { pollHandle });
+    } catch (e) {
+      // A transient poll error isn't fatal — keep trying until the deadline.
+      await delay(intervalMs);
+      continue;
+    }
+    const status = linkPollStatus(res);
+    if (status === "linked") return true;
+    if (status !== "pending") {
+      throw new CliError(`Token of Trust reported the link couldn't complete (${status})`, {
+        next: "re-run `tot link`, or run `tot whoami` for the current guidance",
+      });
+    }
+    if (!announced) {
+      log("~ waiting for you to approve the link in your browser …");
+      announced = true;
+    }
+    await delay(intervalMs);
+  }
+  return false;
+}

package/src/commands/start.mjs

@@ -59,7 +59,7 @@ import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { readCredentials, defaultCredentialsPath } from "../token-store.mjs";
 import { collectChecks } from "./doctor.mjs";
-import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
+import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./checkout.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
@@ -246,6 +246,7 @@ export async function run(argv, ctx) {
       tenant = await resolveTenant(stores, args, env, baseUrl, {
         session,
         listErr: storeListError(listResp),
+        list: listResp,
       });
     } catch (e) {
       stopEarlyHeartbeat();
@@ -560,7 +561,7 @@ function mcpOrigin(baseUrl) {
  * (surface the reason — likely an auth/entitlement problem) from a genuinely empty
  * result (invite may still be propagating, or you need one). Points at `tot whoami`.
  */
-function noStoresError({ session, baseUrl, listErr }) {
+function noStoresError({ session, baseUrl, listErr, list = null }) {
   const who = describeIdentity(session);
   const origin = mcpOrigin(baseUrl);
   if (listErr) {
@@ -569,14 +570,10 @@ function noStoresError({ session, baseUrl, listErr }) {
       { next: "run `tot whoami` to check your session, or `tot login` again — then re-run `tot start`" },
     );
   }
-  return new CliError(
-    `signed in as ${who} via ${origin}, but you have no stores to build on yet`,
-    {
-      next:
-        "if you were just invited, it may still be propagating — try again in a minute; " +
-        "otherwise ask your Token of Trust contact for a store invite (see `tot whoami`)",
-    },
-  );
+  // Status-aware (card c2): an UNLINKED identity is pointed at `tot link`, not the
+  // misleading "ask for a store invite" copy; the genuine zero-grants case keeps it.
+  const g = noStoresGuidance(list);
+  return new CliError(`signed in as ${who} via ${origin}, but ${g.headline}`, { next: g.next });
 }
 
 /**
@@ -584,7 +581,7 @@ function noStoresError({ session, baseUrl, listErr }) {
  * the remembered last tenant (A4) — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
-async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null } = {}) {
+async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null, list = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
     explicit: args.tenant || null,
@@ -593,7 +590,7 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
 
   let tenant;
   if (pick.kind === "none") {
-    throw noStoresError({ session, baseUrl, listErr });
+    throw noStoresError({ session, baseUrl, listErr, list });
   } else if (pick.kind === "explicit") {
     tenant = pick.tenant;
     console.log(`  → your store: ${tenant} (--tenant)`);

package/src/commands/whoami.mjs

@@ -11,7 +11,7 @@
 import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
 import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { normalizeStores, storeListError } from "./checkout.mjs";
+import { normalizeStores, storeListError, noStoresGuidance } from "./checkout.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
 /**
@@ -67,7 +67,11 @@ export async function run(argv, _ctx) {
     } else if (listErr) {
       console.log(`  (couldn't list your stores: ${listErr} — try \`tot login\` again)`);
     } else {
-      console.log("  (no stores resolved yet — if you were just invited, it may still be propagating)");
+      // Status-aware (card c2): an UNLINKED identity is told to link (not "may
+      // still be propagating" — that's only the genuine zero-grants case).
+      const g = noStoresGuidance(listResp);
+      console.log(`  (${g.headline})`);
+      console.log(`  → next: ${g.next}`);
     }
   } catch {
     console.log("  (couldn't reach the MCP to list your stores right now — your cached session is above)");