@tokenoftrust/cli 1.4.0-rc.20 → 1.4.0-rc.22

package/src/commands/sync.mjs

@@ -31,6 +31,7 @@
  */
 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";
@@ -159,6 +160,16 @@ export async function run(argv, ctx) {
     }
   };
 
+  // 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.

package/src/commands/validate.mjs

@@ -71,12 +71,13 @@ export function run(argv, ctx) {
     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 clone <tenant>`"));
+  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/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/merge-doctor-report.mjs

@@ -0,0 +1,208 @@
+/**
+ * merge-doctor-report — the SHARED, pure rendering + one-GET fetch of the hosted
+ * merge-doctor seam (`GET /<tenant>/api/preview/merge-doctor`, unit A2), so every
+ * CLI surface speaks ONE doctor taxonomy:
+ *
+ *   - `tot preview doctor` (preview-doctor.mjs) — the full, ordered report on demand.
+ *   - `tot accept` / `tot ship` (accept.mjs / ship.mjs) — the C5 PUSH: on a failed
+ *     accept/integrate or a refused ship, auto-append the COMPACT summary right where
+ *     the failure already surfaced, so a developer doesn't have to remember to run the
+ *     doctor themselves.
+ *
+ * The render helpers here are a faithful PORT of the analyzer's own
+ * formatReport/attentionBanner/supportContext (mergeDoctor.ts §render / the
+ * scripts/tenant/gitea-merge-doctor.mjs mirror) — the published `@tokenoftrust/cli`
+ * is dependency-free and cannot import the app/scripts source, so this port is kept in
+ * sync with that taxonomy by hand.
+ *
+ * Dependency-light: `fail` + global fetch only. Imports NOTHING from the command
+ * modules (accept/ship/preview-doctor), so accept.mjs and ship.mjs can both depend on
+ * it without a cycle (preview-doctor.mjs already imports ship.mjs for the operator
+ * secret; routing the shared pieces through here keeps ship.mjs ⟷ preview-doctor.mjs
+ * acyclic).
+ */
+
+/** The hosted seam path — one GET, one answer (composed server-side over the SAME
+ *  reads the admin Publish tab builds, run through the shared analyzer). */
+export const DOCTOR_PATH = "/api/preview/merge-doctor";
+
+/** Who resolves a finding — the ticket-deflection axis. */
+export const OWNERSHIP = { developer: "developer", platform: "platform", operator: "operator" };
+export const SEV_GLYPH = { blocker: "✗", warn: "⚠", info: "•" };
+export const OWN_TAG = { developer: "you", platform: "on-us", operator: "housekeeping" };
+
+/**
+ * Defensively read the endpoint body into the analysis shape. The endpoint is a
+ * trust boundary, so a plausible field gap degrades rather than crashes. Pure.
+ * @param {any} data
+ * @returns {{ scopeKnown:boolean, verdict:string, findings:any[], counts:{blocker:number,warn:number,info:number} }}
+ */
+export function normalizeAnalysis(data) {
+  const o = data && typeof data === "object" ? data : {};
+  const findings = Array.isArray(o.findings) ? o.findings : [];
+  const c = o.counts && typeof o.counts === "object" ? o.counts : {};
+  const counts = {
+    blocker: Number.isFinite(c.blocker) ? c.blocker : findings.filter((f) => f?.severity === "blocker").length,
+    warn: Number.isFinite(c.warn) ? c.warn : findings.filter((f) => f?.severity === "warn").length,
+    info: Number.isFinite(c.info) ? c.info : findings.filter((f) => f?.severity === "info").length,
+  };
+  return {
+    scopeKnown: o.scopeKnown === true,
+    verdict: typeof o.verdict === "string" ? o.verdict : "(no verdict returned)",
+    findings,
+    counts,
+  };
+}
+
+/**
+ * The one-line banner shown at the top of the report — counts only
+ * DEVELOPER-actionable findings (what a person can self-serve); platform faults are
+ * narrated separately by {@link supportContext}. Pure.
+ */
+export function attentionBanner(result) {
+  const dev = result.findings.filter((f) => f.ownership === OWNERSHIP.developer && f.severity !== "info");
+  const fixable = dev.filter((f) => f.action).length;
+  if (!dev.length) {
+    const platform = result.findings.filter((f) => f.ownership === OWNERSHIP.platform && f.severity === "blocker");
+    if (platform.length) return `${platform.length} issue(s) are on us — Retry, then Report to support if they persist.`;
+    return "Nothing needs your attention.";
+  }
+  const conflicts = dev.filter((f) => f.code === "PR_CONFLICT").length;
+  const builds = dev.filter((f) => f.code === "NOT_BUILT_PR").length;
+  const bits = [];
+  if (conflicts) bits.push(`${conflicts} conflict(s)${conflicts <= fixable ? " (1-click fix)" : ""}`);
+  if (builds) bits.push(`${builds} need a build`);
+  return `${dev.length} change(s) need your attention: ${bits.join(", ") || "see below"}.`;
+}
+
+/**
+ * The PRE-FILLED support escalation, generated ONLY when there are PLATFORM-owned
+ * findings (a retry didn't clear it) — so "I'm stuck" becomes a structured report.
+ * Returns null when nothing is platform-owned. Pure.
+ */
+export function supportContext(result) {
+  const platform = result.findings.filter((f) => f.ownership === OWNERSHIP.platform);
+  if (!platform.length) return null;
+  const lines = [
+    `Tenant scope: ${result.scopeKnown ? "supplied" : "unknown"}`,
+    `Verdict: ${result.verdict}`,
+    "Platform-owned issues (a retry did not clear these — please investigate):",
+    ...platform.map((f) => `  • [${f.code}] ${f.subject} — ${f.detail}`),
+    "Next diagnostic hop: scripts/preview/pipeline-doctor.sh <tenant> --commit <headSha> (reconcile plane).",
+  ];
+  return lines.join("\n");
+}
+
+/** Render the analysis as the compact, ordered, agent-cheap report. Pure. */
+export function formatReport(result) {
+  const lines = [];
+  lines.push("== gitea-merge-doctor ==");
+  lines.push(`VERDICT: ${result.verdict}`);
+  lines.push(attentionBanner(result));
+  lines.push("");
+  for (const f of result.findings) {
+    const act = f.action ? `  [action: ${f.action.label}]` : "";
+    lines.push(`${SEV_GLYPH[f.severity] ?? "?"} [${f.code}] (${OWN_TAG[f.ownership] ?? f.ownership}) ${f.subject}${act}`);
+    lines.push(`    ${f.detail}`);
+    lines.push(`    → ${f.remedy}`);
+  }
+  lines.push("");
+  lines.push(
+    `${result.counts.blocker} blocker(s), ${result.counts.warn} warning(s), ${result.counts.info} info. First ✗/⚠ above is the thing to fix.`,
+  );
+  const support = supportContext(result);
+  if (support) {
+    lines.push("");
+    lines.push("── if a platform issue persists after Retry, escalate with this (no free-text “stuck”): ──");
+    lines.push(support);
+  }
+  return lines.join("\n");
+}
+
+// ── C5: auto-surface on failure (the PUSH) ───────────────────────────────────────
+
+/** How many findings the COMPACT summary lists before it defers the rest to the
+ *  full `tot preview doctor` report — enough to name the thing to fix, not the whole
+ *  multi-page report at a failure moment. */
+export const COMPACT_FINDING_LIMIT = 3;
+
+/**
+ * Render the COMPACT "here's what's blocking you" summary appended to a failed
+ * accept/integrate or a refused ship (C5). Unlike {@link formatReport} (the full
+ * on-demand report), this lists ONLY the actionable (blocker/warn) findings, capped
+ * at {@link COMPACT_FINDING_LIMIT}, and points at the full report for the rest. Returns
+ * an EMPTY array when there's nothing actionable to say (a clean/info-only verdict, or
+ * no analysis at all) — so a failure whose cause the doctor can't see gets NO noise
+ * appended. Pure — returns the lines to print, never prints itself.
+ * @param {ReturnType<typeof normalizeAnalysis>|null} result
+ * @param {{ limit?: number }} [opts]
+ * @returns {string[]}
+ */
+export function formatCompactSummary(result, { limit = COMPACT_FINDING_LIMIT } = {}) {
+  if (!result || !Array.isArray(result.findings)) return [];
+  const actionable = result.findings.filter((f) => f?.severity === "blocker" || f?.severity === "warn");
+  if (!actionable.length) return [];
+  const lines = [`\n  ── merge doctor — what's blocking your merges:`];
+  lines.push(`  ${attentionBanner(result)}`);
+  for (const f of actionable.slice(0, limit)) {
+    const act = f.action?.label ? `  [${f.action.label}]` : "";
+    lines.push(`    ${SEV_GLYPH[f.severity] ?? "?"} [${f.code}] (${OWN_TAG[f.ownership] ?? f.ownership}) ${f.subject}${act}`);
+    if (f.remedy) lines.push(`      → ${f.remedy}`);
+  }
+  const more = actionable.length - limit;
+  lines.push(
+    more > 0
+      ? `    …and ${more} more — run \`tot preview doctor\` for the full report.`
+      : `    Run \`tot preview doctor\` for the full report.`,
+  );
+  return lines;
+}
+
+/**
+ * One GET to the hosted merge-doctor over an ALREADY-RESOLVED transport (the SAME
+ * `base` + `authHeaders` the calling verb used to reach `/api/changes` /
+ * `/api/changes/ship`), normalized to the analysis shape. Best-effort by contract:
+ * ANY failure (unreachable, non-2xx incl. the 401/403 an auth-refused caller would
+ * also hit, non-JSON body, a throw) resolves to `null` — the doctor is a diagnostic
+ * ADD-ON at a failure moment, so it must never itself become a second failure. Pure
+ * given the injected fetch.
+ * @param {{ base:string, authHeaders:Record<string,string> }} transport
+ * @param {typeof fetch} [fetchImpl]
+ * @returns {Promise<ReturnType<typeof normalizeAnalysis>|null>}
+ */
+export async function fetchDoctorAnalysis({ base, authHeaders }, fetchImpl = globalThis.fetch) {
+  try {
+    const res = await fetchImpl(`${String(base).replace(/\/+$/, "")}${DOCTOR_PATH}`, {
+      method: "GET",
+      headers: authHeaders,
+    });
+    if (!res || !res.ok) return null;
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      return null;
+    }
+    return normalizeAnalysis(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * C5 entry point: fetch the merge-doctor over the given transport and render the
+ * COMPACT failure summary. Returns the lines to print (or `[]` when there's nothing
+ * actionable / the doctor couldn't be reached). Never throws — a caller can
+ * `for (const l of await autoSurfaceDoctor(...)) console.error(l)` unconditionally at
+ * a failure return without touching the exit code.
+ * @param {{ base:string, authHeaders:Record<string,string>, fetchImpl?:typeof fetch, limit?:number }} opts
+ * @returns {Promise<string[]>}
+ */
+export async function autoSurfaceDoctor({ base, authHeaders, fetchImpl = globalThis.fetch, limit }) {
+  try {
+    const analysis = await fetchDoctorAnalysis({ base, authHeaders }, fetchImpl);
+    return formatCompactSummary(analysis, { limit });
+  } catch {
+    return [];
+  }
+}

package/src/oauth.mjs

@@ -188,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");
@@ -204,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 */ } },
   };
@@ -247,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);
@@ -364,7 +364,7 @@ export async function rendezvousLoginFlow({
   mcpUrl,
   code,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {
@@ -474,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() } = {},
 ) {
@@ -505,7 +509,7 @@ export async function deviceLoginFlow({
   mcpUrl,
   clientId,
   fetchImpl = fetch,
-  log = () => {},
+  log = /** @type {(m?: string) => void} */ (() => {}),
   sleep = delay,
   now = () => Date.now(),
 }) {

package/src/obstacle-beacon.cjs

@@ -103,9 +103,9 @@ function beacon(opts, done) {
 
 /** Promise wrapper for the ESM side (src/obstacle.mjs) so a failure path can await delivery. */
 function beaconAsync(opts) {
-  return new Promise(function (resolve) {
+  return /** @type {Promise<void>} */ (new Promise(function (resolve) {
     try { beacon(opts, resolve); } catch (e) { resolve(); }
-  });
+  }));
 }
 
 module.exports = { parseActivityArgs: parseActivityArgs, beacon: beacon, beaconAsync: beaconAsync };

package/src/obstacle.mjs

@@ -19,7 +19,7 @@ import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
  * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
  * bridge credential is cached — the developer signed in with a build that didn't
  * carry the activity flags, or ran a bare `tot login`.
- * @param {"pnpm-missing"|"install-failed"|"clone-failed"} kind
+ * @param {"pnpm-missing"|"install-failed"|"clone-failed"|"renderer-native-bindings-missing"} kind
  * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
  */
 export async function emitObstacle(kind, { have, need, env = process.env } = {}) {

package/src/plan.mjs

@@ -57,11 +57,11 @@ function targetLabel({ pr, changeId }) {
  *   context?: "developer"|"operator",
  *   pinnedSha?: string|null,
  *   artifactDigest?: string|null,
- *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|null,
  *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
  *   paywall?: { allowed: boolean, message?: string|null } | null,
- *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>,
- *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>|null,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|null,
  *   bypassedPreviewSha?: string|null,
  * }} params
  * @returns {string[]} plan lines (no leading/trailing blank line)

package/src/sample.mjs

@@ -94,7 +94,7 @@ export function pickNvmrcVersion(env = process.env) {
     const best = readdirSync(root)
       .map((name) => /^v(\d+)\.(\d+)\.(\d+)$/.exec(name))
       .filter((m) => m && nodeMeetsFloor(m.slice(1).join(".")))
-      .map((m) => m.slice(1).map(Number))
+      .map((m) => /** @type {RegExpExecArray} */ (m).slice(1).map(Number))
       .sort((a, b) => b[0] - a[0] || b[1] - a[1] || b[2] - a[2])[0];
     if (best) return best.join(".");
   } catch {
@@ -177,7 +177,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
     const err = new Error(
       `${dir} isn't empty and isn't a sample checkout — scaffold into an empty directory (or pass a new --workspace)`,
     );
-    err.code = "ENOTEMPTY_SAMPLE";
+    /** @type {any} */ (err).code ="ENOTEMPTY_SAMPLE";
     throw err;
   }
 
@@ -187,7 +187,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
       "the sample store isn't available in this release yet — it's coming soon. " +
         "To build a real store now: `tot login --code <invite>` then `tot start`.",
     );
-    err.code = "SAMPLE_UNAVAILABLE";
+    /** @type {any} */ (err).code ="SAMPLE_UNAVAILABLE";
     throw err;
   }