@tokenoftrust/cli 1.4.0 → 1.5.0

package/src/commands/doctor.mjs

@@ -6,12 +6,12 @@
  * auth identity is available, and Docker — plus reports the detected context
  * so a developer knows which mode `tot` will use here.
  *
- * Docker is informational-only (not blocking): WS3/F3 made the native runtime
+ * Docker is informational-only (not blocking): the native runtime is
  * the default for `tot dev`/`tot start`, so a Docker that isn't running no
  * longer stops the loop — it only matters if you pass --docker or the native
  * artifact can't be fetched (see dev.mjs#NativeArtifactUnavailableError).
  *
- * `--fix` (F2) auto-remediates what it safely can, each fix announced as it
+ * `--fix` auto-remediates what it safely can, each fix announced as it
  * runs: starts Docker (macOS, opportunistically — harmless even though it's
  * no longer required), creates ~/.tot if it's missing, and signs you in when
  * there's no usable session at all. Anything it can't fix (or won't — a stale
@@ -135,9 +135,9 @@ export function collectChecks(_ctx, env = process.env) {
 
 /**
  * Auto-remediate the checks that are safely fixable without human judgment
- * (F2) — announcing each one as it runs. A stale-but-refreshable sign-in isn't
+ * — announcing each one as it runs. A stale-but-refreshable sign-in isn't
  * handled here because it isn't a failing check: the developer session refreshes
- * it silently the next time it's actually used (B4).
+ * it silently the next time it's actually used.
  */
 async function applyFixes(checks, env) {
   const totDir = join(env.TOT_HOME || homedir(), ".tot");

package/src/commands/git-credential.mjs

@@ -0,0 +1,180 @@
+/**
+ * `tot git-credential` — git's own credential-helper protocol (see `git help
+ * gitcredentials`), implemented over the developer's cached `tot login`
+ * session. `tot
+ * clone` configures a fresh checkout's `credential.helper` to run this (see
+ * ../git-credential.mjs's CREDENTIAL_HELPER), so `git fetch`/`git push`/`git
+ * pull` — run DIRECTLY by the developer, not just through `tot preview` —
+ * transparently mint a fresh forge token instead of ever needing one
+ * persisted in `.git/config`. This is the fix for the "the panel-prescribed
+ * `git fetch origin` fails even after `tot login`" dead-end: `tot login`
+ * only ever refreshed the CLI's OWN MCP session, never the token baked into
+ * a checkout's remote URL at clone time.
+ *
+ * git invokes this with ONE positional arg (`get`/`store`/`erase`) and the
+ * request on stdin (key=value lines, blank-line/EOF terminated). Only `get`
+ * does real work — this CLI never persists a forge credential of its own
+ * beyond the short-lived cache in ../git-credential.mjs, so `store`/`erase`
+ * are no-ops (git calls them after a successful/failed auth respectively; we
+ * just drain stdin and exit 0, the correct behavior for a stateless helper).
+ *
+ * FAILS SILENT, NEVER LOUD: `get` prints NOTHING and exits non-zero on any
+ * problem (not signed in, MCP unreachable, cwd isn't a recognizable tenant
+ * checkout) — git then falls through to its next configured helper or its
+ * own prompt, exactly as if this helper weren't configured. A stack trace or
+ * a malformed credential line here would otherwise corrupt EVERY git
+ * operation in the checkout. It also NEVER triggers an interactive sign-in —
+ * this runs as a non-interactive subprocess of `git`, so a missing session
+ * fails through rather than trying to open a browser mid-`git fetch`.
+ *
+ * Dependency-free (global fetch + `git`, via the same MCP client + auth
+ * module every other command uses).
+ */
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession } from "../auth.mjs";
+import { checkoutTenant } from "./clone.mjs";
+import { detectContext } from "../context.mjs";
+import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
+import {
+  parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
+  credentialCachePath, readCachedCredential, writeCachedCredential,
+} from "../git-credential.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+/** Does `remoteUrl`'s host equal `host` (case-insensitive)? An unparseable or
+ *  missing remote URL never matches — fail closed. Exported for testing. */
+export function hostMatches(remoteUrl, host) {
+  if (!remoteUrl || !host) return false;
+  try {
+    // scp-like remotes (git@host:owner/repo.git) have no scheme — synthesize one so URL can parse the host.
+    const normalized = /^[^/]+@[^/:]+:/.test(remoteUrl) ? `ssh://${remoteUrl.replace(":", "/")}` : remoteUrl;
+    return new URL(normalized).host.toLowerCase() === host.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/** Read the credential request git writes to stdin — blocking is correct
+ *  here: git writes the request then closes its end, so this returns as
+ *  soon as it's fully sent. Never blocks on an interactive terminal (git
+ *  NEVER attaches a TTY to a credential helper's stdin — only a human
+ *  poking at this command directly by hand would) and never throws (an
+ *  unreadable/absent stdin is treated as an empty request). Exported so a
+ *  test can inject a canned request instead of touching real fd 0. */
+export function readStdin() {
+  if (process.stdin.isTTY) return "";
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Mint (or reuse a cached) forge credential for the tenant the CURRENT
+ * directory checks out — the same `tenant_checkout` MCP call `tot clone`
+ * itself uses, so the credential is exactly as push-capable. Returns null on
+ * ANY failure (wrong dir, not signed in, MCP unreachable) rather than
+ * throwing — `get` treats null as "say nothing, exit non-zero".
+ *
+ * `createClient`/`establish`/`checkout` are injected (default to the real MCP
+ * client + auth + clone.mjs's checkoutTenant) purely so this is testable
+ * without a live MCP — same DI shape as chooseChangeId's injected `mint` /
+ * resolveDeveloperSession's injected `fetchImpl` elsewhere in this CLI.
+ * SCOPED TO THE CHECKOUT'S OWN REMOTE: `expectedHost` (git's requested host,
+ * from the credential-helper request) is checked against the host of this
+ * checkout's `origin` remote before a credential is ever minted or returned
+ * — a `get` for any OTHER host returns null (silent fail), never handing the
+ * tenant's forge token to a host this checkout doesn't itself push to. This
+ * matters because `credential.helper` is invoked per-URL by git, and a
+ * globally-scoped helper (or a checkout with a submodule / unrelated remote)
+ * must not become a way to exfiltrate the token to an arbitrary host.
+ * @param {{
+ *   env?: NodeJS.ProcessEnv, cwd?: string, expectedHost?: string|null,
+ *   createClient?: typeof createMcpClient,
+ *   establish?: typeof establishSession,
+ *   checkout?: typeof checkoutTenant,
+ * }} [opts]
+ * @returns {Promise<{username:string,password:string}|null>}
+ */
+export async function mintOrCacheCredential({
+  env = process.env, cwd = process.cwd(), expectedHost = null,
+  createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
+} = {}) {
+  const ctx = detectContext(cwd);
+  if (ctx.mode !== "checkout" || !ctx.tenant) return null;
+
+  const git = (cargs) =>
+    execFileSync("git", ["-C", ctx.workspacePath, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  let originUrl = null;
+  let repoName = null;
+  try {
+    originUrl = git(["remote", "get-url", "origin"]).trim();
+    repoName = repoNameFromRemote(originUrl);
+  } catch {
+    /* fall through — tagFromRepoName degrades to "main" on a null repo name */
+  }
+  if (expectedHost && !hostMatches(originUrl, expectedHost)) return null;
+  const tag = tagFromRepoName(repoName, ctx.tenant);
+
+  const cachePath = credentialCachePath(ctx.tenant, tag, env);
+  const cached = readCachedCredential(cachePath);
+  if (cached) return { username: cached.username, password: cached.password };
+
+  const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createClient(baseUrl);
+  try {
+    await establish(client, { env });
+  } catch {
+    return null; // not signed in (or session unrefreshable) — nothing this helper can do
+  }
+  try {
+    const res = await checkout(client, { tenant: ctx.tenant, tag, cloneDir: null });
+    const cred = splitAuthedRemote(res.gitRemote || "");
+    if (!cred) return null;
+    const fresh = { username: cred.username, password: cred.token };
+    writeCachedCredential(cachePath, fresh);
+    return fresh;
+  } catch {
+    return null; // MCP unreachable / tenant_checkout refused — say nothing, exit non-zero
+  }
+}
+
+const USAGE = `tot git-credential — git credential-helper protocol over your \`tot login\` session
+
+  Configured automatically by \`tot clone\` (credential.helper = !tot git-credential)
+  in every checkout it creates — you should never need to run this by hand.
+  See \`git help gitcredentials\` for the protocol this implements.`;
+
+/**
+ * @param {string[]} argv  argv[0] is git's operation: get|store|erase
+ * @param {any} _ctx  unused — this command derives its OWN context from cwd
+ *   (mintOrCacheCredential), since git invokes it with the credentialed
+ *   repo's directory as cwd, which may differ from wherever `tot` itself
+ *   was dispatched from.
+ * @param {{ env?: NodeJS.ProcessEnv, cwd?: string, readStdin?: typeof readStdin }
+ *   & Parameters<typeof mintOrCacheCredential>[0]} [opts]
+ */
+export async function run(argv, _ctx, opts = {}) {
+  const { env = process.env, readStdin: read = readStdin } = opts;
+  const op = argv[0];
+  if (!op || op === "--help" || op === "-h") {
+    console.log(USAGE);
+    return op ? 0 : 2;
+  }
+  // git always writes a request to stdin, even for store/erase — drain it either way
+  // so the subprocess exits cleanly instead of leaving git's write blocked on a full pipe.
+  const request = parseCredentialInput(read());
+
+  if (op !== "get") return 0; // store/erase: stateless, nothing to persist or drop.
+
+  const cred = await mintOrCacheCredential({ ...opts, expectedHost: request.host });
+  if (!cred) return 1; // silent — let git fall through to its next helper / its own prompt.
+  process.stdout.write(formatCredentialOutput({
+    protocol: request.protocol, host: request.host, username: cred.username, password: cred.password,
+  }));
+  return 0;
+}

package/src/commands/go-live.mjs

@@ -1,10 +1,10 @@
 /**
- * `tot go-live` — cut the apex domain over to the storefront (unit u9). The CLI
+ * `tot go-live` — cut the apex domain over to the storefront. The CLI
  * counterpart to the admin Publish tab's Domain "Connect" button: it drives the
  * SAME go-live CI/dispatch the button does (the storefront `/api/domain/dispatch`
  * → `www-domain` repository_dispatch → `cutover-dns.mjs`), gated by the SAME
  * server-authoritative readiness gate the admin display reads
- * (`GET /api/domain/readiness`, unit u9). This command CONSUMES those seams — it
+ * (`GET /api/domain/readiness`). This command CONSUMES those seams — it
  * does NOT reimplement the DNS cutover, the readiness policy, or the revert.
  *
  *   tot go-live               show apex readiness, then (if ready) connect the apex
@@ -19,7 +19,7 @@
  *      revert). Fail-closed: a CONNECT is refused unless the server reports
  *      `ready:true` — the CLI never recomputes readiness, it reads the same gate
  *      the cutover is governed by, so they cannot diverge.
- *   2. Owner-only: the server resolves owner capability (u10); a non-owner is
+ *   2. Owner-only: the server resolves owner capability; a non-owner is
  *      DENIED with the itemized reason. The CLI does not assert ownership itself.
  *   3. ALWAYS require ONE explicit [y/N] confirm (default NO). There is NO
  *      `--yes`/`--force`; in a NON-TTY (CI, piped) it REFUSES rather than
@@ -196,6 +196,9 @@ export function renderReadiness({ appDomain, readiness, action }) {
   const lines = ["", `  Apex ${action === "rollback" ? "rollback" : "cutover"} readiness for ${appDomain ?? "this store"}:`];
   for (const c of readiness.checks) {
     lines.push(`    ${c.ok ? "✓" : "✗"} ${c.label}${c.detail ? ` — ${c.detail}` : ""}`);
+    // Blocked checks carry a "how to clear this" remedy from the server gate —
+    // the same guidance the admin panel shows, so the two surfaces never diverge.
+    if (!c.ok && c.remedy) lines.push(`        → ${c.remedy}`);
   }
   if (action === "connect") {
     lines.push(
@@ -217,6 +220,7 @@ export function renderReadiness({ appDomain, readiness, action }) {
  * assuming it from the dispatch. Injectable delay/attempts. Returns the last
  * normalised run status (may still be "dispatched" if CI is slow — reported honestly).
  * @param {{ get:(path:string)=>Promise<any> }} http
+ * @param {{ attempts?: number, delayMs?: number, sleep?: Function }} [opts]
  */
 export async function pollRunTerminal(http, { attempts = 8, delayMs = 2000, sleep } = {}) {
   const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -391,7 +395,7 @@ function cap(s) {
  * ship floor. Throws on a non-2xx with the server's error message (so the caller
  * surfaces the real refusal). `fetchImpl` is injectable for tests.
  * @param {string} base
- * @param {{ token:string|undefined, owner:string, capability?:string, fetchImpl?:typeof fetch }} auth
+ * @param {{ token?:string, owner?:string, capability?:string, fetchImpl?:typeof fetch }} [auth]
  */
 export function createStorefrontHttp(base, { token, owner, capability = "ship-on-behalf", fetchImpl } = {}) {
   const root = base.replace(/\/+$/, "");
@@ -476,7 +480,7 @@ export async function run(argv, ctx) {
   const http = createStorefrontHttp(base, { token, owner });
   return await runGoLive(
     http,
-    { appDomain: owner, action: args.action, rehearsal: args.rehearsal, noOpen: args.noOpen },
+    { appDomain: owner, action: /** @type {any} */ (args.action), rehearsal: args.rehearsal, noOpen: args.noOpen },
     { openUrl: (u) => openBrowser(u) },
   );
 }

package/src/commands/grants.mjs

@@ -61,9 +61,10 @@ function parseArgs(argv) {
  *   exp: number|null, revokedAt: string|null }> }}
  */
 export function normalizeGrantRows(resp) {
-  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(resp.grants)) {
-    const activeTenant = typeof resp.activeTenant === "string" ? resp.activeTenant : null;
-    const rows = resp.grants
+  const rr = /** @type {any} */ (resp);
+  if (resp && typeof resp === "object" && !Array.isArray(resp) && Array.isArray(rr.grants)) {
+    const activeTenant = typeof rr.activeTenant === "string" ? rr.activeTenant : null;
+    const rows = rr.grants
       .map((g) => {
         const tenant = g?.tenant ?? g?.id ?? null;
         return {
@@ -83,7 +84,7 @@ export function normalizeGrantRows(resp) {
 
   // Fallback: client_list — store ids + environment + the selected marker only. No
   // grant detail is knowable here (grantActive/capability/tier/exp/revokedAt stay null).
-  const clients = Array.isArray(resp) ? resp : resp?.clients || resp?.tenants || [];
+  const clients = Array.isArray(resp) ? resp : rr?.clients || rr?.tenants || [];
   const rows = (Array.isArray(clients) ? clients : [])
     .map((c) => ({
       tenant: c?.tenant ?? c?.id ?? c?.clientId ?? c?.appDomain ?? null,
@@ -147,6 +148,7 @@ export function formatExpiry(exp, { now = Date.now() } = {}) {
 export function describeGrantRow(row, { now = Date.now() } = {}) {
   const status = grantStatus(row, { now });
   if (status === "unknown") return "grant detail unavailable (server introspection not enabled)";
+  /** @type {string[]} */
   const parts = [status];
   if (row.capability) parts.push(`capability=${row.capability}`);
   if (row.tier) parts.push(`tier=${row.tier}`);
@@ -238,7 +240,7 @@ export async function run(argv, _ctx) {
     return 1;
   }
   if (rows.length === 0) {
-    // Status-aware, like whoami/checkout (card c2): an UNLINKED identity is told to
+    // Status-aware, like whoami/checkout: an UNLINKED identity is told to
     // link, not given the "may still be propagating" copy — that's only the genuine
     // linked-but-zero-grants case.
     const g = noStoresGuidance(resp);