@botbuddy/cli 1.59.9 → 1.60.0

package/src/git-transport.mjs

@@ -0,0 +1,476 @@
+// BOT-2599 — keep git's SSH connection alive through a long pre-push hook.
+//
+// git opens the SSH transport and reads the remote's ref advertisement BEFORE it
+// runs the pre-push hook (githooks(5)). A hook that runs for minutes leaves that
+// connection idle until something on the path drops it, and the pack send then
+// dies on a closed pipe (exit 141) after every gate passed. An SSH-level
+// keepalive (`ServerAliveInterval` > 0) keeps it open.
+//
+// This module answers "will THIS clone's push connection carry a keepalive?" the
+// way git itself picks the ssh command — GIT_SSH_COMMAND, then core.sshCommand,
+// then GIT_SSH, then plain `ssh` — and, for ssh, the way ssh resolves options:
+// an explicit `-o ServerAliveInterval=…` on the command line wins over every
+// config file; otherwise `ssh -G` prints the effective value. `ssh -G` reads
+// config only (no network), but a config can `Match exec`, so it is bounded and
+// a timeout is a typed `unknown`, never a false `ok`.
+//
+// `--fix` writes `git config --local core.sshCommand` only when NOTHING is
+// configured; an existing GIT_SSH_COMMAND, core.sshCommand or GIT_SSH is never
+// overwritten — the report carries the exact edit instead. The remote URL is
+// never reported (an HTTPS URL can embed a credential); only its host.
+//
+// Dependency-free (Node stdlib only); every git/ssh call goes through `run`
+// (spawnSync-compatible) so the unit tests need no network and no real config.
+
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { basename } from "node:path";
+
+export const GIT_TRANSPORT_CHECK = "git_transport";
+export const KEEPALIVE_OPTIONS = "-o ServerAliveInterval=20 -o ServerAliveCountMax=60";
+export const KEEPALIVE_SSH_COMMAND = `ssh ${KEEPALIVE_OPTIONS}`;
+export const SSH_CONFIG_TIMEOUT_MS = 5_000;
+const GIT_TIMEOUT_MS = 5_000;
+
+/** Statuses that let a push proceed. `unknown` never does: it cannot prove a keepalive. */
+export const GIT_TRANSPORT_PASSING = Object.freeze(new Set(["ok", "n/a"]));
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Classify a remote URL by transport. Only ssh remotes carry host/user/port;
+ * nothing else of the URL is kept (it may embed a credential).
+ */
+export function classifyRemoteUrl(url) {
+  const value = String(url ?? "").trim();
+  if (!value) return { transport: "none" };
+  const scheme = value.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+  if (scheme) {
+    const name = scheme[1].toLowerCase();
+    if (name === "ssh" || name === "git+ssh" || name === "ssh+git") {
+      let parsed;
+      try {
+        parsed = new URL(`ssh://${value.slice(scheme[0].length)}`);
+      } catch {
+        return { transport: "ssh", host: null, user: null, port: null };
+      }
+      return {
+        transport: "ssh",
+        host: parsed.hostname.replace(/^\[|\]$/g, "") || null,
+        user: parsed.username ? decodeURIComponent(parsed.username) : null,
+        port: parsed.port || null,
+      };
+    }
+    return { transport: name === "https" || name === "http" ? "https" : name };
+  }
+  // git's scp-like syntax, `[user@]host:path`, applies only when no slash comes
+  // before the first colon; anything else is a local path.
+  const scp = value.match(/^(?:([^@/:]+)@)?(\[[^\]/]+\]|[^:/]+):/);
+  if (scp) return { transport: "ssh", host: scp[2].replace(/^\[|\]$/g, ""), user: scp[1] ?? null, port: null };
+  return { transport: "local" };
+}
+
+/**
+ * Split a git ssh command the way `sh -c` evaluates it (git runs
+ * core.sshCommand / GIT_SSH_COMMAND through the shell): words, quotes,
+ * backslash escapes, a leading `~` / `~/` (the home directory) and plain
+ * `$NAME` / `${NAME}` expansions from `env`. Returns null for anything a real
+ * shell would do that this cannot reproduce faithfully — command substitution,
+ * other parameter forms, `~user`, pipes, redirects, a leading comment, an
+ * unbalanced quote, or an unquoted expansion that word splitting or globbing
+ * would change — so the caller reports `unknown` instead of guessing.
+ */
+export function splitShellWords(text, env = {}) {
+  const words = [];
+  let current = "";
+  let inWord = false;
+  let quote = null;
+  const home = () => env.HOME || homedir() || null;
+  // `$NAME` / `${NAME}` at text[i] ("$"); returns { value, next } or null.
+  const expand = (i) => {
+    const braced = text[i + 1] === "{";
+    const m = text.slice(braced ? i + 2 : i + 1).match(/^[A-Za-z_][A-Za-z0-9_]*/);
+    if (!m) return null;
+    let next = i + 1 + (braced ? 1 : 0) + m[0].length;
+    if (braced) {
+      if (text[next] !== "}") return null;
+      next += 1;
+    }
+    return { value: env[m[0]] ?? "", next: next - 1 };
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote === "'") {
+      if (ch === "'") quote = null;
+      else current += ch;
+      continue;
+    }
+    if (quote === '"') {
+      if (ch === '"') quote = null;
+      else if (ch === "\\" && i + 1 < text.length && '"\\$`'.includes(text[i + 1])) current += text[++i];
+      else if (ch === "`") return null;
+      else if (ch === "$") {
+        const ex = expand(i);
+        if (!ex) return null;
+        current += ex.value;
+        i = ex.next;
+      } else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      inWord = true;
+      continue;
+    }
+    if (ch === "\\") {
+      if (i + 1 >= text.length) return null;
+      current += text[++i];
+      inWord = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (inWord) words.push(current);
+      current = "";
+      inWord = false;
+      continue;
+    }
+    if (ch === "~" && !inWord) {
+      // Tilde-prefix: only a bare `~` ending at `/`, whitespace or the end.
+      const after = text[i + 1];
+      if (after !== undefined && after !== "/" && !/\s/.test(after)) return null;
+      const dir = home();
+      if (!dir) return null;
+      current += dir;
+      inWord = true;
+      continue;
+    }
+    if (ch === "$") {
+      const ex = expand(i);
+      if (!ex || /[\s*?[]/.test(ex.value)) return null;
+      current += ex.value;
+      if (ex.value) inWord = true;
+      i = ex.next;
+      continue;
+    }
+    if ("|&;<>()`".includes(ch) || (ch === "#" && !inWord)) return null;
+    current += ch;
+    inWord = true;
+  }
+  if (quote) return null;
+  if (inWord) words.push(current);
+  return words;
+}
+
+/** ssh's time format (`20`, `30s`, `1m`, `1h30m`) in seconds, or null. */
+export function parseSshTime(value) {
+  const text = String(value ?? "").trim().toLowerCase();
+  if (/^\d+$/.test(text)) return Number(text);
+  const units = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
+  let total = 0;
+  let rest = text;
+  if (!rest) return null;
+  while (rest) {
+    const m = rest.match(/^(\d+)([smhdw])/);
+    if (!m) return null;
+    total += Number(m[1]) * units[m[2]];
+    rest = rest.slice(m[0].length);
+  }
+  return total;
+}
+
+// ssh(1) options that take an argument (`ssh -h` usage line).
+const SSH_ARG_FLAGS = new Set("BbcDEeFIiJLlmOoPpQRSWw");
+
+/**
+ * Parse ssh's own argument list (everything after the program) the way ssh's
+ * getopt does: `-o` values, and any positional word. A positional word in a
+ * configured ssh command is an embedded destination (`ssh bastion ssh …`): git
+ * appends its host and remote command AFTER it, so a probe that appended `-G`
+ * would become a remote command and connect. Returns null when an option is
+ * missing its argument.
+ */
+export function parseSshArgs(args) {
+  const options = [];
+  const positional = [];
+  // The arguments up to (not including) a `--` terminator: a probe must put its
+  // own options before the terminator, or ssh reads `-G` as the destination.
+  let optionArgs = args;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") {
+      optionArgs = args.slice(0, i);
+      positional.push(...args.slice(i + 1));
+      break;
+    }
+    if (!arg.startsWith("-") || arg === "-") {
+      positional.push(arg);
+      continue;
+    }
+    for (let j = 1; j < arg.length; j += 1) {
+      const flag = arg[j];
+      if (!SSH_ARG_FLAGS.has(flag)) continue;
+      let value = arg.slice(j + 1);
+      if (!value) {
+        if (i + 1 >= args.length) return null;
+        value = args[++i];
+      }
+      if (flag === "o") options.push(value);
+      break;
+    }
+  }
+  return { options, positional, optionArgs };
+}
+
+/**
+ * The ServerAliveInterval an ssh argument list sets explicitly, or null. ssh
+ * keeps the FIRST value it obtains and the command line beats every config
+ * file, so the first explicit `-o ServerAliveInterval` is authoritative.
+ */
+export function explicitServerAliveInterval(args) {
+  const parsed = parseSshArgs(args);
+  for (const option of parsed?.options ?? []) {
+    const m = option.match(/^\s*serveraliveinterval\s*(?:=\s*|\s+)(\S+)\s*$/i);
+    if (m) return parseSshTime(m[1]);
+  }
+  return null;
+}
+
+/** Insert the keepalive options right after the program, so they win over any later `-o`. */
+export function withKeepalive(command) {
+  const m = String(command).match(/^(\s*)(\S+)/);
+  if (!m) return KEEPALIVE_SSH_COMMAND;
+  return `${m[1]}${m[2]} ${KEEPALIVE_OPTIONS}${command.slice(m[0].length)}`;
+}
+
+function runQuiet(run, cmd, args, { cwd, env, timeout }) {
+  let res;
+  try {
+    res = run(cmd, args, { cwd, env, encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    return { status: null, stdout: "", stderr: "", error };
+  }
+  return {
+    status: typeof res?.status === "number" ? res.status : null,
+    stdout: String(res?.stdout ?? ""),
+    stderr: String(res?.stderr ?? ""),
+    error: res?.error ?? null,
+    signal: res?.signal ?? null,
+  };
+}
+
+function git(run, args, { cwd, env }) {
+  return runQuiet(run, "git", args, { cwd, env, timeout: GIT_TIMEOUT_MS });
+}
+
+function gitConfigValue(run, key, ctx) {
+  const res = git(run, ["config", "--get", key], ctx);
+  return res.status === 0 ? res.stdout.replace(/\n$/, "") : null;
+}
+
+/** Which remote this push would use: branch pushRemote → remote.pushDefault → branch remote → origin. */
+function defaultPushRemote(run, ctx) {
+  const head = git(run, ["symbolic-ref", "--quiet", "--short", "HEAD"], ctx);
+  const branch = head.status === 0 ? head.stdout.trim() : null;
+  return (branch && gitConfigValue(run, `branch.${branch}.pushRemote`, ctx))
+    || gitConfigValue(run, "remote.pushDefault", ctx)
+    || (branch && gitConfigValue(run, `branch.${branch}.remote`, ctx))
+    || "origin";
+}
+
+/**
+ * Every URL this push may go to. A hook passes the actual destination (`$2`) as
+ * `url`; otherwise all of the remote's push URLs (`--all`: a remote can push to
+ * several) so the verdict covers each, not just the first.
+ */
+function resolveDestinations(run, { remote, url }, ctx) {
+  // A remote given as a URL (a push to a URL) is never echoed: it can embed a credential.
+  if (url) return { name: remote && classifyRemoteUrl(remote).transport === "local" ? remote : null, urls: [url] };
+  const name = remote || defaultPushRemote(run, ctx);
+  const res = git(run, ["remote", "get-url", "--push", "--all", name], ctx);
+  const urls = res.status === 0 ? res.stdout.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+  if (urls.length) return { name, urls };
+  // A pre-push hook's $1 is the URL itself when the push named a URL, not a remote.
+  if (remote && classifyRemoteUrl(remote).transport !== "local") return { name: null, urls: [remote] };
+  return { name, urls: [], error: res.error ? "git_unavailable" : "no_push_remote" };
+}
+
+/** git's own order: GIT_SSH_COMMAND, core.sshCommand, GIT_SSH, then plain `ssh`. */
+function resolveSshCommand(run, env, ctx) {
+  if (env.GIT_SSH_COMMAND) return { source: "GIT_SSH_COMMAND", command: env.GIT_SSH_COMMAND, words: splitShellWords(env.GIT_SSH_COMMAND, env) };
+  let res = git(run, ["config", "--show-scope", "--get", "core.sshCommand"], ctx);
+  if (res.status === 129) res = git(run, ["config", "--get", "core.sshCommand"], ctx); // git < 2.26
+  if (res.status === 0) {
+    const line = res.stdout.replace(/\n$/, "");
+    const tab = line.indexOf("\t");
+    const scoped = tab > 0 && /^(local|global|system|worktree|command)$/.test(line.slice(0, tab));
+    const command = scoped ? line.slice(tab + 1) : line;
+    return { source: "core.sshCommand", scope: scoped ? line.slice(0, tab) : null, command, words: splitShellWords(command, env) };
+  }
+  if (env.GIT_SSH) return { source: "GIT_SSH", command: env.GIT_SSH, words: [env.GIT_SSH] };
+  return { source: "ssh_config", command: "ssh", words: ["ssh"] };
+}
+
+function sshEffectiveInterval(run, optionArgs, program, remote, { env, timeout }) {
+  // The configured options, then the probe's, then `--` and the host: a host can
+  // never be read as an option, and a configured trailing `--` cannot swallow -G.
+  const args = [...optionArgs, "-G"];
+  if (remote.port) args.push("-p", remote.port);
+  if (remote.user) args.push("-l", remote.user);
+  args.push("--", remote.host);
+  const res = runQuiet(run, program, args, { env, timeout });
+  if (res.error?.code === "ETIMEDOUT" || (res.signal && res.status === null)) return { reason: "ssh_config_timeout" };
+  if (res.error?.code === "ENOENT") return { reason: "ssh_not_found" };
+  if (res.error || res.status !== 0) return { reason: "ssh_config_unreadable" };
+  const m = res.stdout.match(/^serveraliveinterval\s+(\S+)\s*$/im);
+  const interval = m ? parseSshTime(m[1]) : null;
+  return interval == null ? { reason: "ssh_config_unparseable" } : { interval };
+}
+
+function recoveryFor(report, resolved) {
+  if (report.status === "ok" || report.status === "n/a") return null;
+  if (resolved.source === "ssh_config") {
+    if (report.status === "needs_fix") {
+      return `nothing gives this push a keepalive (ssh config for ${report.host}: ServerAliveInterval ${report.server_alive_interval}); run \`bb doctor --fix\` — it sets git config --local core.sshCommand "${KEEPALIVE_SSH_COMMAND}" for this clone and its worktrees`;
+    }
+    return `\`ssh -G ${report.host}\` gave no answer (${report.reason}), so a keepalive cannot be proven; run \`bb doctor --fix\` to set an explicit one in core.sshCommand`;
+  }
+  if (report.reason === "ssh_command_has_destination") {
+    return `the ssh command embeds a destination (a nested connection such as \`ssh bastion ssh\`), so its keepalive cannot be proven without connecting and \`bb doctor --fix\` never edits it; use ProxyJump instead: ssh -J <bastion> ${KEEPALIVE_OPTIONS}`;
+  }
+  // Echo the configured command back only when it is plain ssh: another program
+  // (sshpass, a wrapper) can carry a secret on its command line.
+  const plainSsh = Boolean(resolved.words?.length) && basename(resolved.words[0]) === "ssh";
+  const suggested = plainSsh ? withKeepalive(resolved.command) : null;
+  const edit = suggested
+    ? `add ${KEEPALIVE_OPTIONS} right after the program`
+    : `make its keepalive explicit with ${KEEPALIVE_OPTIONS}`;
+  if (resolved.source === "GIT_SSH_COMMAND") {
+    return `GIT_SSH_COMMAND overrides git config and \`bb doctor --fix\` never edits it; ${edit}${suggested ? `: export GIT_SSH_COMMAND=${shellQuote(suggested)}` : ""} (or unset it and run \`bb doctor --fix\`)`;
+  }
+  if (resolved.source === "GIT_SSH") {
+    return `GIT_SSH is set and \`bb doctor --fix\` never overrides it; export GIT_SSH_COMMAND=${shellQuote(`${resolved.command} ${KEEPALIVE_OPTIONS}`)} or unset GIT_SSH and run \`bb doctor --fix\``;
+  }
+  const where = resolved.scope && resolved.scope !== "command" ? ` --${resolved.scope}` : "";
+  const how = resolved.scope === "command" ? "it is passed with `git -c`; change it there" : null;
+  return `core.sshCommand${resolved.scope ? ` (${resolved.scope} config)` : ""} has no keepalive and \`bb doctor --fix\` never overwrites it; ${edit}${how ? ` — ${how}` : suggested ? `: git config${where} core.sshCommand ${shellQuote(suggested)}` : ""}`;
+}
+
+/** The verdict for one push URL. `sshCommand()` resolves the ssh command once, on first need. */
+function evaluateDestination(rawUrl, { run, env, sshTimeoutMs, sshCommand }) {
+  const url = classifyRemoteUrl(rawUrl);
+  if (url.transport !== "ssh") return { status: "n/a", transport: url.transport, reason: `${url.transport}_remote` };
+  if (!url.host) return { status: "unknown", transport: "ssh", host: null, reason: "unparseable_remote_url" };
+  // git refuses a host or user that starts with "-" (it would be read as an ssh
+  // option, CVE-2017-1000117); so does this probe, without running ssh.
+  if (url.host.startsWith("-") || url.user?.startsWith("-")) return { status: "unknown", transport: "ssh", host: null, reason: "unsafe_remote_url" };
+  const resolved = sshCommand();
+  const report = {
+    transport: "ssh", host: url.host, source: resolved.source,
+    ...(resolved.scope ? { scope: resolved.scope } : {}),
+    server_alive_interval: null,
+  };
+  if (!resolved.words || resolved.words.length === 0) {
+    report.reason = "unparseable_ssh_command";
+  } else {
+    const isSsh = basename(resolved.words[0]) === "ssh";
+    const sshArgs = isSsh ? parseSshArgs(resolved.words.slice(1)) : null;
+    const explicit = explicitServerAliveInterval(resolved.words.slice(1));
+    if (isSsh && (!sshArgs || sshArgs.positional.length > 0)) {
+      // `ssh bastion ssh`: a nested connection. Never probe it (the probe would
+      // connect); its inner keepalive cannot be proven from here either.
+      report.reason = sshArgs ? "ssh_command_has_destination" : "unparseable_ssh_command";
+    } else if (explicit != null) {
+      report.server_alive_interval = explicit;
+      report.interval_origin = "command_line";
+    } else if (isSsh) {
+      const effective = sshEffectiveInterval(run, sshArgs.optionArgs, resolved.words[0], url, { env, timeout: sshTimeoutMs });
+      if (effective.reason) report.reason = effective.reason;
+      else {
+        report.server_alive_interval = effective.interval;
+        report.interval_origin = "ssh_config";
+      }
+    } else {
+      report.reason = "custom_ssh_program";
+    }
+  }
+  if (report.server_alive_interval == null) report.status = "unknown";
+  else report.status = report.server_alive_interval > 0 ? "ok" : "needs_fix";
+  return report;
+}
+
+function evaluate({ cwd, env, remote, url, run, sshTimeoutMs }) {
+  const ctx = { cwd, env };
+  const target = resolveDestinations(run, { remote, url }, ctx);
+  const base = { check: GIT_TRANSPORT_CHECK, remote: target.name ?? null };
+  if (target.urls.length === 0) {
+    if (target.error === "git_unavailable") return { report: { ...base, status: "unknown", transport: null, reason: "git_unavailable", recovery: "git could not run here (not on PATH, or the directory is missing); run the check from the clone you push from" } };
+    return { report: { ...base, status: "n/a", transport: "none", reason: "no_push_remote" } };
+  }
+  let resolved = null;
+  const sshCommand = () => (resolved ??= resolveSshCommand(run, env, ctx));
+  const results = target.urls.map((u) => evaluateDestination(u, { run, env, sshTimeoutMs, sshCommand }));
+  // The push passes only if every destination does: report the first that does not.
+  const primary = results.find((r) => !GIT_TRANSPORT_PASSING.has(r.status))
+    ?? results.find((r) => r.transport === "ssh") ?? results[0];
+  const report = { ...base, ...primary };
+  if (results.length > 1) {
+    report.destinations = results.map((r) => ({
+      transport: r.transport, ...(r.host ? { host: r.host } : {}), status: r.status,
+      ...(r.server_alive_interval != null ? { server_alive_interval: r.server_alive_interval } : {}),
+      ...(r.reason ? { reason: r.reason } : {}),
+    }));
+  }
+  if (report.reason === "unparseable_remote_url" || report.reason === "unsafe_remote_url") report.recovery = "a push URL's host cannot be parsed safely; check `git remote get-url --push --all`";
+  else if (resolved) {
+    const recovery = recoveryFor(report, resolved);
+    if (recovery) report.recovery = recovery;
+  }
+  return { report, resolved };
+}
+
+/**
+ * Check (and with `fix`, repair) the keepalive on this clone's push transport.
+ * `url` is the push's actual destination (a pre-push hook's `$2`); without it
+ * every push URL of `remote` (default: the branch's push remote) is checked.
+ * Returns the report: { check, status: ok|needs_fix|n/a|unknown, remote,
+ * transport, host?, source?, scope?, server_alive_interval?, interval_origin?,
+ * reason?, recovery?, destinations? (when several URLs), fix? }.
+ */
+export function checkGitTransport({
+  cwd = process.cwd(), env = process.env, remote = null, url = null, fix = false,
+  run = spawnSync, sshTimeoutMs = SSH_CONFIG_TIMEOUT_MS,
+} = {}) {
+  const first = evaluate({ cwd, env, remote, url, run, sshTimeoutMs });
+  if (!fix || GIT_TRANSPORT_PASSING.has(first.report.status) || !first.resolved) return first.report;
+  if (first.resolved.source !== "ssh_config") {
+    return { ...first.report, fix: { applied: false, reason: `existing_${first.resolved.source}_left_untouched` } };
+  }
+  const set = git(run, ["config", "--local", "core.sshCommand", KEEPALIVE_SSH_COMMAND], { cwd, env });
+  if (set.status !== 0) {
+    return { ...first.report, fix: { applied: false, reason: "git_config_failed" } };
+  }
+  // Report fixed only on proof: re-resolve exactly as a push would.
+  const after = evaluate({ cwd, env, remote, url, run, sshTimeoutMs }).report;
+  return { ...after, fix: { applied: true, set: `git config --local core.sshCommand "${KEEPALIVE_SSH_COMMAND}"`, verified: after.status === "ok" } };
+}
+
+/** One human line for `bb doctor` / `bb setup`. */
+export function formatGitTransportLine(report) {
+  if (!report) return "git transport: unknown (check failed)";
+  const parts = [];
+  if (report.host) parts.push(`ssh ${report.host}`);
+  else if (report.transport && report.transport !== "none" && report.transport !== "ssh") parts.push(`${report.transport} remote`);
+  if (report.server_alive_interval != null) {
+    const via = report.interval_origin === "command_line" ? report.source
+      : report.source === "ssh_config" ? "ssh config" : `${report.source} → ssh config`;
+    parts.push(`ServerAliveInterval ${report.server_alive_interval} via ${via}`);
+  } else if (report.reason && !(report.transport && report.reason === `${report.transport}_remote`)) {
+    parts.push(report.reason);
+  }
+  const fixed = report.fix?.applied
+    ? (report.fix.verified ? " — fixed: set core.sshCommand (local)" : " — fix applied but NOT verified")
+    : "";
+  return `git transport: ${report.status}${parts.length ? ` (${parts.join(", ")})` : ""}${fixed}`;
+}