@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.21

package/src/commands/sync.mjs

@@ -0,0 +1,203 @@
+/**
+ * `tot sync` — the common candidate CONFLICT-RECOVERY path (branch-lifecycle
+ * contract, docs/architecture/branch-lifecycle-and-integration-preview.md,
+ * "Two developers touch the same file" / P1 item 12):
+ *
+ *   Both candidate previews may be green in isolation. After the first
+ *   integrates, the second may become conflicted. The queue blocks that PR
+ *   and prints the conflicting paths. The second developer syncs from
+ *   `preview`, resolves locally, reruns `tot preview`, and obtains evidence
+ *   for the new head. Prior approval is stale and must not carry forward
+ *   automatically.
+ *
+ * `tot sync` fetches the protected `preview` branch and MERGES it into the
+ * developer's current local branch — this repo's own canonical policy for
+ * bringing a protected line into a working branch (see playbook/merge.md:
+ * `git fetch` + `git merge --no-edit`, never a history-rewriting rebase of
+ * shared history). It never writes `preview`/`main` (fetch is read-only on
+ * the remote), never force-pushes anything, and never runs `git add -A` — on
+ * a conflict it stops immediately and leaves the merge in progress so the
+ * developer resolves it the normal git way (`git add <file>` + `git commit`,
+ * or `git merge --abort` to back out).
+ *
+ * Distinct from `tot preview`/`tot accept`: sync touches ONLY the developer's
+ * own local branch. It never pushes, never opens/updates a candidate, and
+ * never touches the shared `preview` aggregate or live. A successful sync
+ * moves local HEAD, which makes any prior preview/approval stale by
+ * definition (they were evidence for the OLD head) — so this always closes
+ * by pointing the developer at a fresh `tot preview`.
+ *
+ * Dependency-free (global `git`, no MCP/network beyond `git fetch`).
+ */
+import { execFileSync } from "node:child_process";
+import { fail } from "../errors.mjs";
+import { ensureTokenlessRemote } from "../git-credential.mjs";
+
+/** The protected branch `tot sync` fetches + merges from by default. */
+export const DEFAULT_SYNC_BRANCH = "preview";
+
+const USAGE = `tot sync — fetch \`preview\` and merge it into your local branch
+
+  tot sync                    fetch origin/${DEFAULT_SYNC_BRANCH} and merge it into your current branch
+  tot sync --branch <name>    sync against a different protected branch (default: ${DEFAULT_SYNC_BRANCH})
+  tot sync --help             show this help
+
+  The common conflict-recovery path: after another candidate integrates first,
+  yours may conflict on \`tot accept\`. \`tot sync\` fetches the protected
+  \`${DEFAULT_SYNC_BRANCH}\` branch and merges it into your local branch so you can resolve the
+  conflict locally, THEN re-run \`tot preview\` for a fresh candidate head.
+
+  On a conflict, sync stops SAFELY: it prints the conflicting paths and leaves
+  the merge in progress for you to resolve by hand — it never force-pushes
+  \`${DEFAULT_SYNC_BRANCH}\`/main and never runs \`git add -A\`.
+
+  A successful sync moves your local HEAD, so any prior preview/approval — it
+  was evidence for the OLD head — is now stale. Re-run \`tot preview\` before
+  your next \`tot accept\`.`;
+
+/** Parse `tot sync` argv. Pure — unit-testable. */
+export function parseArgs(argv) {
+  const a = { branch: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--branch") a.branch = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Unmerged (conflicting) paths from `git diff --name-only --diff-filter=U`.
+ *  Pure — unit-tested without git. */
+export function parseConflictPaths(text) {
+  return String(text)
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Fetch `origin/<branch>` and merge it into the current branch. Never throws
+ * for an ordinary merge conflict — git's own nonzero exit on `merge` IS the
+ * conflict signal, and we turn it into a `"conflict"` result with the
+ * conflicting paths; a merge failure that ISN'T an ordinary conflict (no
+ * unmerged paths found) rethrows so the caller reports the real failure
+ * instead of a misleading "conflict".
+ *
+ * @param {(cargs:string[]) => string} git  a THROWING `git -C <workspace>` runner
+ *   (execFileSync-backed) — throws carry `.stderr`/`.message` like execFileSync.
+ * @param {{ branch?: string }} [opts]
+ * @returns {{ state: "up-to-date" } | { state: "synced", sha: string } | { state: "conflict", paths: string[] }}
+ */
+export function syncWithBranch(git, { branch = DEFAULT_SYNC_BRANCH } = {}) {
+  git(["fetch", "origin", branch]);
+
+  // How many commits on origin/<branch> the local branch is missing. 0 means
+  // local HEAD already contains everything from the protected branch —
+  // nothing to merge, regardless of how far ahead the local branch itself is.
+  const ahead = git(["rev-list", "--count", `HEAD..origin/${branch}`]).trim();
+  if (ahead === "0") return { state: "up-to-date" };
+
+  try {
+    git(["merge", "--no-edit", `origin/${branch}`]);
+  } catch (e) {
+    const paths = parseConflictPaths(git(["diff", "--name-only", "--diff-filter=U"]));
+    if (paths.length === 0) throw e; // not an ordinary conflict — surface the real failure
+    return { state: "conflict", paths };
+  }
+  const sha = git(["rev-parse", "HEAD"]).trim();
+  return { state: "synced", sha };
+}
+
+/** Render a `syncWithBranch` result in house style; returns the process exit
+ *  code. Pure given its inputs. */
+export function reportSync(result, { branch }) {
+  if (result.state === "up-to-date") {
+    console.log(`\n  ✓ already in sync with origin/${branch} — nothing to merge.`);
+    return 0;
+  }
+  if (result.state === "synced") {
+    console.log(`\n  ✓ synced with origin/${branch} — new HEAD ${result.sha.slice(0, 9)}.`);
+    console.log(`  → next: any prior preview/approval was evidence for the OLD head and is now stale.`);
+    console.log(`    re-run \`tot preview\` to get a fresh candidate + evidence for this head.`);
+    return 0;
+  }
+  // conflict — stop safely; the merge is left in progress for the developer.
+  console.error(fail(`sync conflicts with origin/${branch} — ${result.paths.length} file(s)`) + "\n");
+  for (const p of result.paths) console.error(`  ✗ conflict: ${p}`);
+  console.error(`\n  → next: resolve each conflict above, then \`git add <file>\` and \`git commit\` to finish the merge`);
+  console.error(`    (or \`git merge --abort\` to back out). Once resolved, re-run \`tot preview\` for a fresh candidate.`);
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot sync` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, and re-run)",
+      ),
+    );
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const branch = (args.branch || DEFAULT_SYNC_BRANCH).trim();
+  const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  const gitSafe = (cargs) => {
+    try {
+      return git(cargs);
+    } catch {
+      return "";
+    }
+  };
+
+  // Self-heal a LEGACY checkout (unit u10, absorbs u7): `tot login` refreshes
+  // this CLI's own session, never the token baked into a checkout's remote at
+  // clone time — the exact reason a stale checkout's `git fetch origin` (below)
+  // used to 401 even right after signing back in. Best-effort, never blocks sync.
+  try {
+    ensureTokenlessRemote(git);
+  } catch {
+    /* best-effort — see above */
+  }
+
+  // Refuse a dirty tree up front — a merge on top of uncommitted edits is how
+  // local work gets silently entangled with the merge, and we never sweep
+  // anything in with `git add -A`. Commit or stash first, then re-run.
+  const status = gitSafe(["status", "--porcelain", "--untracked-files=all"]);
+  if (status.trim()) {
+    console.error(
+      fail(
+        "your working tree has uncommitted changes",
+        "commit them, or `git stash --include-untracked`, then re-run `tot sync`",
+      ) + "\n",
+    );
+    for (const line of status.trim().split("\n")) console.error(`  ${line}`);
+    return 2;
+  }
+
+  console.error(`~ fetching origin/${branch}…`);
+  let result;
+  try {
+    result = syncWithBranch(git, { branch });
+  } catch (e) {
+    console.error(
+      fail(
+        `sync failed: ${String(e.stderr || e.message || e)}`,
+        "check your network / that the checkout's remote is reachable, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportSync(result, { branch });
+}

package/src/commands/validate.mjs

@@ -68,15 +68,16 @@ export function run(argv, ctx) {
 
   const target = resolveTarget(args, ctx);
   if (target.error) {
-    console.error(fail(target.error, "tot checkout <tenant> --clone <dir>, or pass --workspace <dir>"));
+    console.error(fail(target.error, "tot clone <tenant>, 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>`"));
+  const dir = /** @type {string} */ (target.dir);
+  if (!existsSync(dir)) {
+    console.error(fail(`no tenant directory at ${dir}`, "confirm the path, or `tot clone <tenant>`"));
     return 2;
   }
 
-  const { ok, findings } = validateTenant(target.dir, {
+  const { ok, findings } = validateTenant(dir, {
     tenantId: target.tenantId ?? undefined,
     scope: target.scope ?? undefined,
     // A checkout / bare-tenant target is served by the ToT storefront platform, so
@@ -92,7 +93,12 @@ export function run(argv, ctx) {
 
   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`);
+  // Never present the checkout PATH as if it were the tenant name — when the
+  // tenant couldn't be resolved (e.g. an invalid/missing .tot/config.json),
+  // the findings below say why; the header should say so too, not disguise
+  // a directory as a domain.
+  const label = target.tenantId ? target.tenantId : `(tenant unresolved) ${target.dir}`;
+  console.log(`\ntot validate — ${label}\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}` : ""}`);

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 "./clone.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)");

package/src/context.mjs

@@ -6,13 +6,13 @@
  *
  *   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`
+ *                `tot dev` here runs the in-tree astro dev; `tot clone`
  *                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
+ *   loose      — anywhere else. `tot clone <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

package/src/dev-heartbeat.mjs

@@ -35,7 +35,8 @@ const OS_INFO = { os: os.platform(), osVersion: os.release(), arch: os.arch() };
  * an activity URL and a bearer token. Never throws — a failed/offline hosted
  * worker just means the cockpit doesn't light up this beat.
  * @param {{ activityUrl?: string, token?: string, url?: string,
- *   cliVersion?: string, runnerVersion?: string|null, editor?: string|null }} args
+ *   cliVersion?: string, runnerVersion?: string|null, editor?: string|null,
+ *   cwd?: string|null }} args
  */
 export function postHeartbeat({ activityUrl, token, url, cliVersion, runnerVersion, editor, cwd } = {}) {
   if (!activityUrl || !token) return undefined;

package/src/errors.mjs

@@ -32,13 +32,17 @@ function versionFooter() {
 
 /**
  * A failure worth surfacing with a concrete next step.
+ * @typedef {object} CliErrorOpts
+ * @property {string} [next]     - the exact command (or one-line instruction) to run next.
+ * @property {number} [exitCode] - process exit code to use (default 1).
+ * @property {unknown} [cause]
+ *
  * @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).
+ * @param {CliErrorOpts} [opts]
  */
 export class CliError extends Error {
-  constructor(what, { next, exitCode = 1, cause } = {}) {
+  constructor(what, opts = {}) {
+    const { next, exitCode = 1, cause } = opts;
     super(what);
     this.name = "CliError";
     this.what = what;

package/src/git-credential.mjs

@@ -0,0 +1,185 @@
+/**
+ * Shared plumbing for `tot` acting as a git credential helper (unit u10,
+ * workstream tot-merge-conflict-resolution-ux — absorbs u7's `tot fetch`
+ * self-heal idea) — so a checkout never needs a LIVE forge token baked into
+ * `.git/config`'s remote URL. `tot clone` configures a fresh checkout's
+ * `credential.helper` to `CREDENTIAL_HELPER` (git's own extension point for
+ * exactly this — see `git help gitcredentials`), which git then invokes with
+ * `get`/`store`/`erase` on every network operation instead of reading a
+ * persisted secret. This module holds the pieces BOTH the `git-credential`
+ * command (src/commands/git-credential.mjs, which mints fresh tokens via the
+ * MCP) and the self-heal migration (called at the top of every command that
+ * touches git — submit/sync/… — so ANY CLI touch of a legacy checkout
+ * migrates it) share: parsing/formatting git's credential protocol, the
+ * on-disk credential cache, and rewriting a checkout's remote to drop its
+ * embedded token.
+ *
+ * Dependency-free — node:fs/os/path/crypto only. The MCP mint itself (real
+ * network I/O) lives in the command layer, which this module never imports.
+ */
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readCredentials, writeCredentials } from "./token-store.mjs";
+
+/** The git config value that routes credential requests through `tot` — the
+ *  `!` tells git to run this as a shell command (git appends the operation,
+ *  e.g. `get`, as the final argument) — the same convention `gh auth
+ *  git-credential` uses. Repo-LOCAL only (never --global): a checkout not
+ *  built with `tot` must never have its credential resolution silently
+ *  redirected. */
+export const CREDENTIAL_HELPER = "!tot git-credential";
+
+/** How long a minted credential is trusted before `tot git-credential get`
+ *  mints a fresh one — comfortably under the forge push token's own
+ *  multi-hour expiry (see pushPreviewRef in submit.mjs), so a long-running
+ *  session still self-refreshes well before the cached one goes stale. */
+export const CREDENTIAL_TTL_MS = 20 * 60 * 1000;
+
+/**
+ * Split an authenticated forge remote URL (basic-auth `user:token@host`, as
+ * the MCP mints it via `tenant_checkout`) into its tokenless public URL +
+ * the embedded credential, so the token can be handed to git EPHEMERALLY for
+ * one operation instead of being persisted in `.git/config`. Returns null
+ * when the URL won't parse or carries no token — the caller then falls back
+ * to the checkout's existing remote. Pure — unit-tested.
+ * @param {string} remoteUrl
+ * @returns {{ publicUrl: string, username: string, token: string }|null}
+ */
+export function splitAuthedRemote(remoteUrl) {
+  try {
+    const u = new URL(String(remoteUrl));
+    const token = u.password ? decodeURIComponent(u.password) : "";
+    if (!token) return null;
+    const username = u.username ? decodeURIComponent(u.username) : "";
+    return { publicUrl: `${u.protocol}//${u.host}${u.pathname}`, username, token };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `http.extraheader` value that hands a basic-auth credential to a
+ * SINGLE git invocation (base64 of `user:token`) — so a freshly-minted forge
+ * token authenticates one operation without ever being written to
+ * `.git/config`. Pure — unit-tested.
+ * @param {string} username
+ * @param {string} token
+ * @returns {string}
+ */
+export function basicAuthExtraHeader(username, token) {
+  const b64 = Buffer.from(`${username}:${token}`, "utf8").toString("base64");
+  return `Authorization: Basic ${b64}`;
+}
+
+/**
+ * Parse git's credential-helper protocol (key=value lines, terminated by a
+ * blank line or EOF) into a plain object. A malformed line is skipped rather
+ * than throwing — git's own helpers are lenient the same way. Pure.
+ * @param {string} text
+ * @returns {Record<string,string>}
+ */
+export function parseCredentialInput(text) {
+  /** @type {Record<string,string>} */
+  const out = {};
+  for (const line of String(text).split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const i = trimmed.indexOf("=");
+    if (i <= 0) continue;
+    out[trimmed.slice(0, i)] = trimmed.slice(i + 1);
+  }
+  return out;
+}
+
+/**
+ * Format a credential response for git's `get` operation — only the fields
+ * present are emitted (git only needs `username`/`password` filled in;
+ * echoing `protocol`/`host` back is harmless and conventional). Pure.
+ * @param {Record<string,string|undefined|null>} fields
+ * @returns {string}
+ */
+export function formatCredentialOutput(fields) {
+  const lines = [];
+  for (const key of ["protocol", "host", "path", "username", "password"]) {
+    if (fields[key] !== undefined && fields[key] !== null) lines.push(`${key}=${fields[key]}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** A filesystem-safe, collision-resistant cache key for one (tenant, tag) —
+ *  hashed (not the raw tenant string) so an unusual tenant name can never
+ *  escape `~/.tot/git-credentials/` or collide across tags. Pure. */
+export function credentialCacheKey(tenant, tag) {
+  return createHash("sha256").update(`${tenant}|${tag}`).digest("hex").slice(0, 32);
+}
+
+/** Absolute path to one (tenant, tag)'s cached credential — same `~/.tot`
+ *  root (and `TOT_HOME` override) as the OAuth session cache. */
+export function credentialCachePath(tenant, tag, env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "git-credentials", `${credentialCacheKey(tenant, tag)}.json`);
+}
+
+/** Is a cached credential still trusted? A cache with no `mintedAt` is
+ *  treated as stale (mint fresh rather than trust an unknown age). Pure. */
+export function isFreshCredential(cred, { now = Date.now(), ttlMs = CREDENTIAL_TTL_MS } = {}) {
+  return Boolean(cred && cred.username && cred.password && cred.mintedAt && now - cred.mintedAt < ttlMs);
+}
+
+/** Read a cached credential (reusing token-store.mjs's generic reader), or
+ *  null if absent/unreadable/malformed/stale. Never throws. */
+export function readCachedCredential(filePath, opts = {}) {
+  const cred = readCredentials(filePath);
+  return isFreshCredential(cred, opts) ? cred : null;
+}
+
+/** Cache a freshly-minted credential — atomic write, owner-only permissions
+ *  (0600 in a 0700 dir, via token-store.mjs's writer): this file holds a LIVE
+ *  forge push token, same security bar as the OAuth session cache. */
+export function writeCachedCredential(filePath, { username, password }, { now = Date.now() } = {}) {
+  writeCredentials(filePath, { username, password, mintedAt: now });
+}
+
+/**
+ * Self-heal a LEGACY checkout: if `origin`'s remote still carries an
+ * embedded token (the pre-u10 `tot clone` shape, or one predating `tot
+ * login` entirely), strip it — rewriting the remote to the tokenless public
+ * URL — and install the credential helper so future git operations mint
+ * fresh creds through `tot` instead of relying on a token that silently
+ * expires. Meant to be called at the top of every command that touches git,
+ * best-effort (the caller decides how to handle a thrown error — this never
+ * blocks the actual command on a migration hiccup). A no-op on an
+ * already-migrated, tokenless, or non-http(s) (e.g. ssh) remote.
+ * @param {(cargs:string[])=>string} git  a `git -C <workspace>` runner
+ * @returns {{ migrated: boolean }}
+ */
+export function ensureTokenlessRemote(git) {
+  let remote;
+  try {
+    remote = git(["remote", "get-url", "origin"]).trim();
+  } catch {
+    return { migrated: false }; // no `origin` (or not a git repo) — nothing to migrate
+  }
+  let migrated = false;
+  try {
+    const u = new URL(remote);
+    if (u.password) {
+      git(["remote", "set-url", "origin", `${u.protocol}//${u.host}${u.pathname}`]);
+      migrated = true;
+    }
+  } catch {
+    return { migrated }; // not a parseable URL (e.g. an ssh remote) — leave it alone entirely
+  }
+  let helper = "";
+  try {
+    helper = git(["config", "--local", "--get", "credential.helper"]).trim();
+  } catch {
+    /* unset — falls through to configuring it below */
+  }
+  if (helper !== CREDENTIAL_HELPER) {
+    git(["config", "--local", "credential.helper", CREDENTIAL_HELPER]);
+    migrated = true;
+  }
+  return { migrated };
+}

package/src/mcp.mjs

@@ -142,7 +142,12 @@ export function createMcpClient(baseUrl, opts = {}) {
     return parsed?.result;
   }
 
-  /** Call an MCP tool and unwrap its structured / text result to a plain object. */
+  /**
+   * Call an MCP tool and unwrap its structured / text result to a plain object.
+   * @param {string} name
+   * @param {unknown} [args]
+   * @returns {Promise<any>}
+   */
   async function callTool(name, args) {
     const r = await callRaw("tools/call", { name, arguments: args });
     if (r?.structuredContent) return r.structuredContent;

package/src/no-gitea-links.test.mjs

@@ -0,0 +1,55 @@
+// Regression guard: the `tot` CLI must never print/reference a raw Gitea
+// forge URL to a developer's terminal. Gitea's API returns `html_url` when a
+// PR is opened (e.g. `https://git.tokenoftrust.com/storefront/<repo>/pulls/<n>`)
+// -- the CLI must surface the storefront-owned `/preview/<tenant>/pr/<n>` link
+// instead (see apps/storefront's matching noGiteaLinks.test.ts and its header
+// for the full architecture reasoning: apps/CLI never expose the forge
+// directly, the MCP proxies every read/write). Precipitating incident
+// (2026-08-18): a raw git.tokenoftrust.com PR URL reached an owner reviewing
+// tokenoftrust.com. Test fixtures are exempt (they legitimately mock a Gitea
+// URL to test the forge client), everything else in `src` must stay clean.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+const SELF = fileURLToPath(import.meta.url);
+const SRC_ROOT = dirname(SELF);
+
+const TEST_FILE_RE = /\.test\.[cm]?js$/;
+const FORGE_HOST_RE = /\bgit\.tokenoftrust\.com\b/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walk(full, out);
+    } else if (/\.[cm]?js$/.test(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+test("no Gitea forge links in the CLI source outside test fixtures", () => {
+  const offenders = [];
+  for (const file of walk(SRC_ROOT)) {
+    if (TEST_FILE_RE.test(file)) continue;
+    if (file === SELF) continue;
+    const content = readFileSync(file, "utf8");
+    content.split("\n").forEach((line, i) => {
+      if (FORGE_HOST_RE.test(line)) {
+        offenders.push(`${relative(SRC_ROOT, file)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `Found Gitea forge links in non-test CLI source:\n${offenders.join("\n")}`,
+  );
+});

package/src/oauth.mjs

@@ -84,8 +84,15 @@ export async function registerClient(
     headers: { "Content-Type": "application/json", Accept: "application/json" },
     body: JSON.stringify({
       client_name: CLIENT_NAME,
+      // Include the device-code grant: the browserless rendezvous + B3 device flows
+      // redeem their device_code at /oauth/token with this grant, so a client
+      // registered WITHOUT it gets "unauthorized_client: grant_type is invalid".
+      grant_types: [
+        "authorization_code",
+        "refresh_token",
+        "urn:ietf:params:oauth:grant-type:device_code",
+      ],
       redirect_uris: [redirectUri],
-      grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none",
       scope: SCOPE,
@@ -181,7 +188,7 @@ export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
   let settle, reject;
   const callback = new Promise((res, rej) => { settle = res; reject = rej; });
   const server = http.createServer((req, res) => {
-    const u = new URL(req.url, `http://${host}`);
+    const u = new URL(req.url ?? "/", `http://${host}`);
     if (u.pathname !== "/callback") {
       res.writeHead(404, { "Content-Type": "text/plain" });
       res.end("not found");
@@ -197,12 +204,12 @@ export function startLoopbackListener({ host = "127.0.0.1" } = {}) {
       settle({ code: u.searchParams.get("code"), state: u.searchParams.get("state") });
     }
   });
-  const listening = new Promise((res, rej) => {
+  const listening = /** @type {Promise<void>} */ (new Promise((res, rej) => {
     server.once("error", rej);
     server.listen(0, host, () => res());
-  });
+  }));
   return {
-    async ready() { await listening; return server.address().port; },
+    async ready() { await listening; return /** @type {import("net").AddressInfo} */ (server.address()).port; },
     waitForCallback() { return callback; },
     close() { try { server.close(); } catch { /* already closed */ } },
   };
@@ -240,7 +247,7 @@ export async function loginFlow({
   clientId,
   fetchImpl = fetch,
   open = openBrowser,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
@@ -355,15 +362,19 @@ export async function attachRendezvous(attachEndpoint, { rendezvousCode, clientI
  */
 export async function rendezvousLoginFlow({
   mcpUrl,
-  clientId,
   code,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {
   const meta = await discoverMetadata(mcpUrl, fetchImpl);
-  const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
+  // Always register a FRESH client for a rendezvous sign-in — do NOT reuse a cached
+  // clientId. A client cached by an older CLI build was registered without the
+  // device-code grant, so /oauth/token would reject the device grant with
+  // "unauthorized_client". Registration is cheap and a rendezvous has no consent
+  // screen to re-trigger (unlike the loopback/device flows, which reuse the cache).
+  const resolvedClientId = await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl);
   const { verifier, challenge } = generatePkce();
 
   const attach = await attachRendezvous(
@@ -463,11 +474,15 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifi
  * expires), honoring the server's `interval` and the `slow_down` backoff
  * (RFC 8628 §3.5: +5s, keep polling — not a failure). Injectable `sleep`/
  * `now` so it's testable with no real waiting.
+ * @param {string} tokenEndpoint
+ * @param {{ deviceCode: any, clientId: any, codeVerifier?: any, intervalSec?: any, expiresInSec?: any }} params
+ * @param {typeof fetch} [fetchImpl]
+ * @param {{ sleep?: Function, now?: () => number }} [timing]
  * @returns {Promise<object>} the raw token response (→ credentialsFromToken)
  */
 export async function pollDeviceToken(
   tokenEndpoint,
-  { deviceCode, clientId, codeVerifier, intervalSec, expiresInSec },
+  { deviceCode, clientId, codeVerifier = undefined, intervalSec, expiresInSec },
   fetchImpl = fetch,
   { sleep = delay, now = () => Date.now() } = {},
 ) {
@@ -494,7 +509,7 @@ export async function deviceLoginFlow({
   mcpUrl,
   clientId,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {