@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

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

@@ -92,7 +92,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/git-credential.mjs

@@ -0,0 +1,184 @@
+/**
+ * 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) {
+  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/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")}`,
+  );
+});