@tokenoftrust/cli 1.0.0

package/src/commands/submit.mjs

@@ -0,0 +1,284 @@
+/**
+ * `tot submit` — submit your store for PREVIEW (the deliberate, gated step).
+ *
+ * From inside a tenant checkout:
+ *   1. validate locally and refuse on errors (fail fast before anything leaves the machine),
+ *   2. push your committed work to the tenant repo's `preview` ref (triggers reconcile),
+ *   3. report back — reconcile result + compliance verdict + the preview URL — from the MCP.
+ *
+ * This is submit-for-PREVIEW, not ship-to-live (`change_accept` / a future `tot ship`
+ * is the separate ship gate). Step 3 calls the MCP `preview_status` read-back
+ * (~/.tot-mcp/handoffs/2026-07-09-tot-mcp-tot-submit-contract.md): given the commit
+ * just pushed it returns { status, reconcile, compliance, previewUrl } and we poll it
+ * while reconcile is pending. If that tool isn't present (older MCP) the command still
+ * validates + pushes and reports "reconcile pending" — degrading visibly, never a crash.
+ *
+ * Polling (E2): every call carries `waitMs` so a preview_status-aware MCP long-polls
+ * (blocks up to waitMs, waking immediately on arrival) instead of us sleeping blind
+ * between calls. An MCP that doesn't honor it still returns fast while pending, so
+ * pollPreviewStatus measures elapsed time and sleeps the rest of delayMs itself —
+ * the original fixed-interval poll, automatically as a fallback, no version check
+ * needed. `--watch` just raises the budget (longer waitMs, more attempts) so an
+ * attached dev can stay and watch reconcile+compliance resolve live.
+ *
+ * Watching through to accept (E1b): `--watch` also sets untilShipped, so once
+ * reconcile resolves cleanly the loop keeps going (preview_status reuses the
+ * SAME waitMs budget server-side to long-poll for a ship decision too — one
+ * poll axis, not two) until change_accept ships it or the attempts budget
+ * runs out. A failed reconcile never waits for ship — it can't have shipped.
+ * Detached devs get the E1 email instead; this is the attached half.
+ *
+ * Dependency-free (global fetch + `git`).
+ */
+import { execFileSync } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { createMcpClient } from "../mcp.mjs";
+import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { validateTenant, ERROR } from "../validate.mjs";
+import { openBrowser } from "../open.mjs";
+import { fail } from "../errors.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const DEFAULT_REF = "preview";
+
+function parseArgs(argv) {
+  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--ref") a.ref = argv[++i];
+    else if (t === "--skip-validate") a.skipValidate = true;
+    else if (t === "--no-wait") a.noWait = true;
+    else if (t === "--watch") a.watch = true;
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot submit — submit your store for preview
+
+  tot submit                    validate → push the preview ref → stream the result
+  tot submit --watch            stay attached through reconcile + compliance + accept (long-poll)
+  tot submit --skip-validate    push without the local lint (not recommended)
+  tot submit --ref <name>       push ref (default: ${DEFAULT_REF})
+  tot submit --no-wait          push and exit without polling for the reconcile result
+  tot submit --no-open          don't open the preview URL in the browser on success
+  tot submit --mcp <url>        MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)`;
+
+// Default bounded wait (~20s, matching the pre-E2 fixed poll's total budget) vs.
+// --watch's longer per-call long-poll + more attempts (~8 min ceiling) for a dev
+// who's deliberately staying attached to watch reconcile+compliance resolve live.
+const DEFAULT_POLL = { attempts: 8, delayMs: 2500 };
+const WATCH_POLL = { attempts: 24, delayMs: 20_000, waitMs: 20_000, untilShipped: true };
+
+const redactUrl = (s) => String(s).replace(/\/\/[^/@\s]*@/g, "//***@");
+
+/** @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;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot submit` runs from inside a tenant checkout",
+        "tot checkout <tenant> --clone <dir>   (then `cd` in, commit your work, and re-run)",
+      ),
+    );
+    return 2;
+  }
+  const workspace = ctx.workspacePath;
+  const tenant = ctx.tenant;
+  const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+
+  // 1. validate locally — refuse on errors.
+  if (!args.skipValidate) {
+    const { ok, findings } = validateTenant(workspace, { tenantId: tenant, scope: ctx.config?.scope });
+    if (!ok) {
+      const errs = findings.filter((f) => f.level === ERROR);
+      console.error(
+        fail(`${errs.length} validation error(s)`, "fix these (below), or re-run with --skip-validate") + "\n",
+      );
+      for (const f of errs) console.error(`  ✗ [${f.rule}] ${f.file} — ${f.message}`);
+      return 1;
+    }
+    console.error("~ validated (no errors)");
+  }
+
+  // 2. push the preview ref over the checkout's authenticated remote.
+  let commit;
+  try {
+    commit = git(["rev-parse", "HEAD"]).trim();
+  } catch {
+    console.error(fail("no commits here yet", "git add <files> && git commit -m '…', then re-run"));
+    return 1;
+  }
+  const short = commit.slice(0, 9);
+  console.error(`~ pushing ${short} → ${args.ref} (origin)`);
+  try {
+    const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
+    if (out.trim()) console.error(redactUrl(out.trim()));
+  } catch (e) {
+    console.error(
+      fail(
+        `push failed: ${redactUrl(String(e.stderr || e.message || e))}`,
+        "check your commit and that the checkout's remote is reachable, then re-run",
+      ),
+    );
+    return 1;
+  }
+  console.log(`\n+ submitted ${short} to ${args.ref}.`);
+
+  // 3. report reconcile + compliance + preview URL from the MCP (graceful seam).
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await client.initialize();
+    await resolveSession(client, { env, prefer: args.identity || undefined });
+    // Set the active tenant so preview_status reads the right scope (it keys on
+    // the session's tenant + the commit — no tenant arg of its own).
+    await client.callTool("client_switch", { tenant });
+    const status = args.noWait
+      ? normalizePreviewStatus(await client.callTool("preview_status", { commit }))
+      : await pollPreviewStatus(client, commit, {
+          ...(args.watch ? WATCH_POLL : DEFAULT_POLL),
+          onTick: (s, i) => {
+            if (s.status === "pending") console.error(`~ reconcile running for ${short} … (${i + 1})`);
+            else if (s.status === "reconciled" && !s.shipped) {
+              console.error(`~ reconciled — waiting for a ship decision … (${i + 1})`);
+            }
+          },
+        });
+    reportStatus(status, tenant, { open: !args.noOpen });
+    return status?.status === "failed" ? 1 : 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
+    } else {
+      console.log(`  (reconcile is running — the result read-back isn't available yet: ${String(e?.message || e)})`);
+    }
+    console.log(`  Your push is in; the preview updates once reconcile completes.`);
+    return 0;
+  }
+}
+
+/**
+ * Normalize a `preview_status` tool response to the contract shape the CLI reports
+ * on: { status, reconcile:{ok,errors}, compliance:{verdict,detail}, previewUrl,
+ * shipped }. A live tool always returns status pending|reconciled|failed; anything
+ * else (an older MCP without the tool's flat fields) normalizes to "unknown" so the
+ * CLI degrades visibly instead of pretending it reconciled. `shipped` (E1b) is
+ * null until change_accept ships this exact commit. Pure — unit-tested.
+ */
+export function normalizePreviewStatus(r) {
+  const status = r?.status;
+  const known = status === "pending" || status === "reconciled" || status === "failed";
+  return {
+    status: known ? status : "unknown",
+    reconcile: r?.reconcile ?? null,
+    compliance: r?.compliance ?? null,
+    previewUrl: r?.previewUrl ?? null,
+    shipped: r?.shipped ?? null,
+    raw: r,
+  };
+}
+
+/**
+ * Poll `preview_status` while reconcile is pending (and, with untilShipped, while
+ * reconciled-but-not-yet-shipped). E2: every call carries `waitMs` so a
+ * preview_status that supports it long-polls (blocks up to waitMs, waking
+ * immediately on the report's — or, once reconciled, the ship decision's —
+ * arrival) instead of us guessing an interval — most calls resolve on attempt 1 or
+ * 2 instead of walking the full attempts budget. An MCP that ignores waitMs (older
+ * deploy, or genuinely still pending) just returns fast; we measure elapsed time
+ * and sleep the REST of delayMs ourselves, so the net cadence degrades to exactly
+ * the pre-E2 fixed-interval poll — no version check needed, the fallback is
+ * automatic. Stops as soon as status resolves to "failed"/"unknown" (a failed
+ * reconcile can't ship), or resolves to "reconciled" AND (not untilShipped, or
+ * already shipped). Injectable delay/attempts/waitMs for tests.
+ * @param {{callTool:Function}} client
+ * @param {string} commit
+ * @param {{ attempts?: number, delayMs?: number, waitMs?: number, untilShipped?: boolean, onTick?: (s:object,i:number)=>void }} [opts]
+ */
+export async function pollPreviewStatus(
+  client,
+  commit,
+  { attempts = 8, delayMs = 2500, waitMs = delayMs, untilShipped = false, onTick } = {},
+) {
+  let last = null;
+  for (let i = 0; i < attempts; i++) {
+    const startedAt = Date.now();
+    const args = waitMs ? { commit, waitMs } : { commit };
+    last = normalizePreviewStatus(await client.callTool("preview_status", args));
+    if (onTick) onTick(last, i);
+    const stillWatchingForShip = untilShipped && last.status === "reconciled" && !last.shipped;
+    if (last.status !== "pending" && !stillWatchingForShip) return last;
+    if (i < attempts - 1) {
+      const remaining = delayMs - (Date.now() - startedAt);
+      if (remaining > 0) await delay(remaining);
+    }
+  }
+  return last;
+}
+
+const CHECK_GLYPH = { pass: "✓", fail: "✗", warn: "⚠", skip: "~" };
+
+/**
+ * Print one per-rule compliance check: id/label, required-ness, why it didn't
+ * pass (detail), and a concrete fix suggestion (hint) when there is one. This is
+ * the moat over a bare pass/fail — an agent (or a human) reading `tot submit`
+ * output should know exactly what to change and why, with no dashboard round-trip.
+ */
+function reportComplianceCheck(c) {
+  const glyph = CHECK_GLYPH[c.status] ?? "?";
+  const tag = c.required ? " (required)" : "";
+  const detail = c.detail ? ` — ${c.detail}` : "";
+  console.log(`    ${glyph} [${c.id}] ${c.label}${tag}${detail}`);
+  if (c.hint) console.log(`        → fix: ${c.hint}`);
+}
+
+/**
+ * Print the reconcile/compliance/preview result and, on a clean reconcile with a
+ * preview URL, open it in the browser (unless opts.open === false).
+ */
+function reportStatus(s, tenant, { open = true } = {}) {
+  if (!s || s.status === "unknown") {
+    console.log(
+      `  (this MCP doesn't return the per-commit reconcile result yet — your push is in;\n` +
+        `   the preview updates once reconcile runs. Check the preview dashboard.)`,
+    );
+    return;
+  }
+  if (s.status === "pending") {
+    console.log(`  reconcile still running for ${tenant} — check back shortly (re-run \`tot submit --no-wait\`).`);
+    return;
+  }
+  const rc = s.reconcile;
+  if (rc) {
+    if (rc.ok) console.log(`  ✓ reconcile ok`);
+    else {
+      console.log(`  ✗ reconcile failed:`);
+      for (const e of rc.errors ?? []) console.log(`      [${e.rule ?? "?"}] ${e.message ?? ""}`);
+    }
+  }
+  if (s.compliance?.verdict) {
+    console.log(`  compliance: ${s.compliance.verdict}${s.compliance.detail ? ` — ${s.compliance.detail}` : ""}`);
+    for (const c of s.compliance.checks ?? []) reportComplianceCheck(c);
+  }
+  if (s.shipped) {
+    console.log(`\n  ✓ shipped — change ${s.shipped.changeId} accepted at ${s.shipped.shippedAt}`);
+  } else if (s.status === "reconciled") {
+    console.log(`\n  ~ not yet shipped — a reviewer still needs to run change_accept.`);
+  }
+  if (s.previewUrl) {
+    console.log(`\n  Preview: ${s.previewUrl}`);
+    if (open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
+      console.log("  (opened in your browser)");
+    }
+  }
+}

package/src/commands/validate.mjs

@@ -0,0 +1,99 @@
+/**
+ * `tot validate` — lint your store before you commit/submit.
+ *
+ * Context-aware target resolution (see src/context.mjs):
+ *   checkout  — validate the checkout root itself (the flat tenant layout).
+ *   monorepo  — `tot validate <tenant>` → tenants/<tenant>/; or --workspace <dir>.
+ *   loose     — needs an explicit --workspace <dir>.
+ *
+ *   tot validate                 (inside a checkout) lint this store
+ *   tot validate <tenant>        (inside the monorepo) lint tenants/<tenant>/
+ *   tot validate --workspace DIR lint a specific checkout directory
+ *   tot validate --json          machine-readable findings
+ *
+ * Exit 0 = no errors (warnings allowed); 1 = one or more errors; 2 = usage / no target.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { validateTenant, ERROR, WARN } from "../validate.mjs";
+import { fail } from "../errors.mjs";
+
+function parseArgs(argv) {
+  const a = { tenant: null, workspace: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--workspace") a.workspace = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
+  }
+  return a;
+}
+
+const USAGE = `tot validate — lint your store before you submit
+
+  tot validate                  (inside a checkout) lint this store
+  tot validate <tenant>         (inside the monorepo) lint tenants/<tenant>/
+  tot validate --workspace <dir>  lint a specific checkout directory
+  tot validate --json           machine-readable findings`;
+
+/**
+ * Resolve the tenant directory + id + scope to validate, from args + context.
+ * @returns {{ dir?: string, tenantId?: string|null, scope?: string|null, error?: string }}
+ */
+function resolveTarget(args, ctx) {
+  if (args.workspace) {
+    return { dir: resolve(args.workspace), tenantId: ctx.config?.tenant ?? null, scope: ctx.config?.scope ?? null };
+  }
+  if (args.tenant) {
+    if (ctx.mode === "monorepo") {
+      return { dir: join(ctx.repoRoot, "tenants", args.tenant), tenantId: args.tenant };
+    }
+    // A bare tenant name outside the monorepo has no directory to resolve.
+    return { error: `"${args.tenant}" is a tenant name, but you're not in a storefront monorepo. Run from a checkout, or use --workspace <dir>.` };
+  }
+  if (ctx.mode === "checkout") {
+    return { dir: ctx.workspacePath, tenantId: ctx.tenant, scope: ctx.config?.scope ?? null };
+  }
+  return { error: "nothing to validate — run inside a tenant checkout, pass a <tenant> (in the monorepo), or --workspace <dir>." };
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export function run(argv, ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const target = resolveTarget(args, ctx);
+  if (target.error) {
+    console.error(fail(target.error, "tot checkout <tenant> --clone <dir>, or pass --workspace <dir>"));
+    return 2;
+  }
+  if (!existsSync(target.dir)) {
+    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot checkout <tenant> --clone <dir>`"));
+    return 2;
+  }
+
+  const { ok, findings } = validateTenant(target.dir, {
+    tenantId: target.tenantId ?? undefined,
+    scope: target.scope ?? undefined,
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify({ ok, findings }, null, 2));
+    return ok ? 0 : 1;
+  }
+
+  const errors = findings.filter((f) => f.level === ERROR);
+  const warns = findings.filter((f) => f.level === WARN);
+  console.log(`\ntot validate — ${target.tenantId ?? target.dir}\n`);
+  for (const f of findings) {
+    const tag = f.level === ERROR ? "✗" : "⚠";
+    console.log(`  ${tag} [${f.rule}] ${f.file}\n      ${f.message}${f.fix ? `\n      → ${f.fix}` : ""}`);
+  }
+  if (findings.length === 0) console.log("  (no findings)");
+  console.log(`\n${errors.length === 0 ? "✔" : "✖"} ${errors.length} error(s), ${warns.length} warning(s).\n`);
+  return errors.length === 0 ? 0 : 1;
+}

package/src/commands/whoami.mjs

@@ -0,0 +1,69 @@
+/**
+ * `tot whoami` — who is `tot` signed in as, and what can they touch.
+ *
+ * Reads the cached session (~/.tot/credentials.json). If a live token is present
+ * it best-effort asks the MCP for the stores this identity may act on (proving the
+ * token still works), degrading cleanly to the cached status if the MCP is
+ * unreachable or the identity isn't entitled yet. Operator credentials in the env
+ * are reported too, since they take precedence for tool calls.
+ *
+ * Dependency-free.
+ */
+import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
+import { hasOperatorCreds, resolveDeveloperSession } from "../auth.mjs";
+import { createMcpClient } from "../mcp.mjs";
+import { normalizeStores } from "./checkout.mjs";
+
+/**
+ * Pure summary of the cached session — no network. Returned for both display and
+ * tests: { signedIn, expired, mcpUrl, expiresAt }.
+ */
+export function sessionStatus(creds, { now = Date.now() } = {}) {
+  if (!creds || !creds.accessToken) return { signedIn: false, expired: false, mcpUrl: null, expiresAt: null };
+  return {
+    signedIn: true,
+    expired: isExpired(creds, { now }),
+    mcpUrl: creds.mcpUrl || null,
+    expiresAt: creds.expiresAt || null,
+  };
+}
+
+/** @param {string[]} argv @param {any} _ctx */
+export async function run(argv, _ctx) {
+  const env = process.env;
+  const creds = readCredentials(defaultCredentialsPath(env));
+  const status = sessionStatus(creds);
+
+  if (hasOperatorCreds(env)) {
+    console.log(`operator credentials set in this shell (TOT_APP_DOMAIN=${env.TOT_APP_DOMAIN}).`);
+    console.log("  these take precedence for `tot` tool calls.");
+  }
+
+  if (!status.signedIn) {
+    console.log("developer: not signed in.");
+    if (!hasOperatorCreds(env)) console.log("  → next: tot login");
+    return hasOperatorCreds(env) ? 0 : 1;
+  }
+
+  const when = status.expiresAt ? new Date(status.expiresAt).toISOString() : "unknown";
+  console.log(`developer: signed in via ${status.mcpUrl || "the MCP"}${status.expired ? " (token expired — will refresh on next use)" : ""}.`);
+  console.log(`  token expires: ${when}`);
+
+  // Best-effort live check: resolve the session (refreshes if needed) and list the
+  // stores this identity can act on. Never fails the command — a gated/unentitled
+  // identity or an unreachable MCP just shows the cached status above.
+  try {
+    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", {}));
+    if (stores.length) {
+      console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
+    } else {
+      console.log("  (no stores resolved yet for this identity)");
+    }
+  } catch {
+    console.log("  (couldn't reach the MCP to list your stores right now — your cached session is above)");
+  }
+  return 0;
+}

package/src/context.mjs

@@ -0,0 +1,97 @@
+/**
+ * Context detection — "be smart about where `tot` is invoked from."
+ *
+ * A globally-installed `tot` runs in one of three places, and every command
+ * dispatches off which one:
+ *
+ *   monorepo   — inside a full storefront checkout (pnpm-workspace.yaml +
+ *                apps/storefront + tenants/). This is us / a platform dev.
+ *                `tot dev` here runs the in-tree astro dev; `tot checkout`
+ *                can suggest cloning a sibling dir.
+ *   checkout   — inside a STANDALONE tenant checkout: the flat, content-only
+ *                shape `content/ public/ theme.json .tot/config.json` a
+ *                developer clones. The tenant is read from .tot/config.json.
+ *                `tot dev` here boots the bundled runner against this dir.
+ *   loose      — anywhere else. `tot checkout <tenant>` still works (it's how
+ *                you GET a checkout); commands that need a workspace say so.
+ *
+ * Detection walks UP from the cwd so `tot` works from any subdirectory of a
+ * checkout or the monorepo, the way `git` does. Dependency-free.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Walk up from `start` (inclusive) to the filesystem root, yielding each dir. */
+function* ancestors(start) {
+  let dir = resolve(start);
+  for (;;) {
+    yield dir;
+    const parent = dirname(dir);
+    if (parent === dir) return; // hit the root
+    dir = parent;
+  }
+}
+
+/** A dir is the storefront monorepo root if it carries all three markers. */
+function isMonorepoRoot(dir) {
+  return (
+    existsSync(join(dir, "pnpm-workspace.yaml")) &&
+    existsSync(join(dir, "apps", "storefront")) &&
+    existsSync(join(dir, "tenants"))
+  );
+}
+
+/** A dir is a standalone tenant checkout if it carries a readable .tot/config.json. */
+function readCheckoutConfig(dir) {
+  const cfgPath = join(dir, ".tot", "config.json");
+  if (!existsSync(cfgPath)) return null;
+  try {
+    return JSON.parse(readFileSync(cfgPath, "utf8"));
+  } catch {
+    return null; // present but malformed — treat as "not a clean checkout"
+  }
+}
+
+/**
+ * Detect the invocation context.
+ *
+ * @param {string} [cwd] - defaults to process.cwd().
+ * @returns {{
+ *   mode: "monorepo" | "checkout" | "loose",
+ *   cwd: string,
+ *   repoRoot: string | null,     // set in monorepo mode
+ *   workspacePath: string | null,// set in checkout mode (the checkout root)
+ *   config: object | null,       // .tot/config.json contents in checkout mode
+ *   tenant: string | null,       // tenant inferred from the checkout config
+ * }}
+ */
+export function detectContext(cwd = process.cwd()) {
+  const base = {
+    cwd: resolve(cwd),
+    repoRoot: null,
+    workspacePath: null,
+    config: null,
+    tenant: null,
+  };
+
+  // Monorepo wins if we're inside one (its own tenant checkouts live under
+  // tenants/<id>/, which do NOT carry a root .tot/config.json, so there's no
+  // ambiguity in practice — but check monorepo first regardless).
+  for (const dir of ancestors(cwd)) {
+    if (isMonorepoRoot(dir)) {
+      return { ...base, mode: "monorepo", repoRoot: dir };
+    }
+    const cfg = readCheckoutConfig(dir);
+    if (cfg) {
+      return {
+        ...base,
+        mode: "checkout",
+        workspacePath: dir,
+        config: cfg,
+        tenant: typeof cfg.tenant === "string" ? cfg.tenant : null,
+      };
+    }
+  }
+
+  return { ...base, mode: "loose" };
+}

package/src/errors.mjs

@@ -0,0 +1,64 @@
+/**
+ * The one place `tot` turns a failure into words. Every command routes its
+ * terminal errors through here so the developer NEVER sees a raw stack trace —
+ * they see `✗ <what happened> → next: <the exact command to run>`.
+ *
+ * Two shapes flow in:
+ *   - CliError — a failure we raised on purpose, already carrying its next step.
+ *   - anything else (thrown Error, AuthUnavailableError, a string) — we render
+ *     its message and, when we can recognise it, its remedy.
+ *
+ * Dependency-free. Kept import-cycle-free by duck-typing AuthUnavailableError
+ * (matched on `.name`/`.hint`) rather than importing auth.mjs.
+ */
+
+/**
+ * A failure worth surfacing with a concrete next step.
+ * @param {string} what   - what went wrong, in plain words.
+ * @param {{ next?: string, exitCode?: number, cause?: unknown }} [opts]
+ *   next     - the exact command (or one-line instruction) to run next.
+ *   exitCode - process exit code to use (default 1).
+ */
+export class CliError extends Error {
+  constructor(what, { next, exitCode = 1, cause } = {}) {
+    super(what);
+    this.name = "CliError";
+    this.what = what;
+    this.next = next || null;
+    this.exitCode = exitCode;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/** Render `what` (+ optional `next`) in the house style. No trailing newline. */
+export function fail(what, next) {
+  const head = `✗ ${what}`;
+  return next ? `${head}\n  → next: ${next}` : head;
+}
+
+/**
+ * Format ANY error into the house style. Never emits a stack trace.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function formatError(err) {
+  if (err instanceof CliError) return fail(err.what, err.next);
+  // AuthUnavailableError, duck-typed to avoid an import cycle with auth.mjs.
+  if (err && typeof err === "object" && err.name === "AuthUnavailableError") {
+    return fail(String(err.message), err.hint || null);
+  }
+  if (err && typeof err === "object" && "message" in err && err.message) {
+    return fail(String(err.message), null);
+  }
+  return fail(String(err), null);
+}
+
+/** Exit code an error asks for (CliError carries its own; default 1). */
+export function exitCodeFor(err) {
+  return err instanceof CliError && Number.isInteger(err.exitCode) ? err.exitCode : 1;
+}
+
+/** Print a formatted failure to stderr. */
+export function printError(err, write = (s) => console.error(s)) {
+  write(formatError(err));
+}

package/src/last-tenant.mjs

@@ -0,0 +1,49 @@
+/**
+ * The "last tenant" cache for `tot start` (A4 — smart zero-arg default). After
+ * a multi-store identity picks (or is told) a tenant, remember it here so a
+ * bare `tot start` on the next run just goes instead of re-prompting.
+ *
+ * ONE file, `~/.tot/last-tenant.json`, scoped by `mcpUrl` — a different MCP
+ * means a different set of stores, so a tenant remembered there doesn't carry
+ * over. Same atomic-write discipline as token-store.mjs (0600 in a 0700 dir,
+ * write-tmp-then-rename). Dependency-free (node:fs/os/path).
+ *
+ * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+/** Absolute path to the last-tenant cache for this environment. */
+export function defaultLastTenantPath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "last-tenant.json");
+}
+
+/**
+ * Read back the remembered tenant for `mcpUrl`, or null if there isn't one
+ * (absent, unreadable, malformed, or remembered against a different MCP).
+ * Never throws — a miss just means "nothing remembered".
+ */
+export function readLastTenant(filePath, mcpUrl) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    if (parsed.mcpUrl !== mcpUrl) return null;
+    return typeof parsed.tenant === "string" && parsed.tenant ? parsed.tenant : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remember `tenant` for `mcpUrl`, atomically and owner-only. */
+export function writeLastTenant(filePath, { mcpUrl, tenant }) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp`;
+  const record = { mcpUrl, tenant, updatedAt: Date.now() };
+  writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, filePath);
+  chmodSync(filePath, 0o600);
+}