// git-repo.mjs: the one read-only reader of a git repository. // // Everything the git board and the dashboard need to know about a repository // comes from here: the worktree status, the branch table, the default branch, // a merge or rebase in progress, the remotes and their web addresses, when it // was last fetched, and the pull-request link. This module only reads: it // never changes the repository, the index or the working tree, and every git // call carries GIT_OPTIONAL_LOCKS=0 so a background look cannot take the index // lock out from under a commit. The console imports it directly; the git // skill's scripts reach it through common.mjs. Node built-ins only. import fs from "node:fs"; import path from "node:path"; import { execFileSync } from "node:child_process"; import { prUrl } from "./public/pr-url.js"; export { prUrl }; /* ----------------------------------------------------------- running git */ /** Run git with an args array (never a shell). { ok, out, err }. */ export function git(args, cwd, { raw = false, timeout } = {}) { try { const stdout = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024, windowsHide: true, timeout, // Without this, git status refreshes the index on disk: a write. env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, }); return { ok: true, out: raw ? stdout : stdout.trim(), err: "" }; } catch (e) { return { ok: false, out: "", err: String(e?.stderr || e?.message || "").trim() }; } } // git switch and git switch -c arrived in 2.23 (August 2019). const FLOOR = [2, 23, 0]; let floorResult = null; /** Is git on PATH and at least 2.23? Checked once per process. */ export function gitFloor() { if (floorResult) return floorResult; const res = git(["--version"]); const version = res.ok ? res.out.replace(/^git version\s+/, "") || null : null; const m = version && version.match(/^(\d+)\.(\d+)\.(\d+)/); if (!version) { floorResult = { ok: false, version: null, message: "git is not installed or not on PATH." }; } else { const parts = m ? m.slice(1, 4).map(Number) : [0, 0, 0]; const cmp = parts.map((n, i) => n - FLOOR[i]).find((d) => d !== 0) || 0; floorResult = m && cmp >= 0 ? { ok: true, version } : { ok: false, version, message: `The git board needs git 2.23 or newer (found ${version}). Update git, then try again.` }; } return floorResult; } /* ------------------------------------------------------- worktree status */ // The fields before the path in each porcelain v2 entry kind. const PATH_AFTER = { 1: 8, 2: 9, u: 10 }; function pathField(record, fields) { let at = 0; for (let k = 0; k < fields; k++) { const next = record.indexOf(" ", at); if (next < 0) return ""; at = next + 1; } return record.slice(at); } const letter = (c) => (c === "." ? " " : c); function fileState(x, y) { if (x === "A" || x === "?" || y === "A" || y === "?") return "new"; if (x === "D" || y === "D") return "deleted"; if (x === "R" || x === "C" || y === "R" || y === "C") return "renamed"; return "modified"; } /** * Parse `git status --porcelain=v2 -z --branch --untracked-files=normal`. * Untracked entries come back as files with index " " and worktree "?"; * unmerged entries go only into `conflicted`. ahead/behind are null without * an upstream; hasCommits is false for "(initial)" or without branch headers. */ export function parseStatusV2(text) { const result = { oid: null, hasCommits: false, branch: null, upstream: null, ahead: null, behind: null, files: [], conflicted: [] }; const fields = String(text || "").split("\0"); for (let i = 0; i < fields.length; i++) { const rec = fields[i]; if (!rec) continue; if (rec.startsWith("# ")) { const [key, ...rest] = rec.slice(2).split(" "); const value = rest.join(" "); if (key === "branch.oid") { result.oid = value === "(initial)" ? null : value; result.hasCommits = value !== "(initial)"; } else if (key === "branch.head") result.branch = value === "(detached)" ? null : value; else if (key === "branch.upstream") result.upstream = value; else if (key === "branch.ab") { const m = value.match(/^\+(\d+) -(\d+)$/); if (m) [result.ahead, result.behind] = [Number(m[1]), Number(m[2])]; } continue; } const kind = rec[0]; if (kind === "?") { result.files.push({ path: rec.slice(2), index: " ", worktree: "?", state: "new" }); continue; } if (!(kind in PATH_AFTER)) continue; // "!" ignored, anything unknown too const x = letter(rec[2]); const y = letter(rec[3]); const p = pathField(rec, PATH_AFTER[kind]); if (kind === "u") { result.conflicted.push({ path: p, status: rec.slice(2, 4) }); continue; } const entry = { path: p, index: x, worktree: y, state: fileState(x, y) }; // A rename or copy carries its original path as one more NUL field. if (kind === "2") entry.origPath = fields[++i] || ""; result.files.push(entry); } if (!result.upstream) [result.ahead, result.behind] = [null, null]; return result; } export const LARGE_BYTES = 5 * 1024 * 1024; // Every name is checked for secrets, but only the first STAT_LIMIT files are // sized, so a forgotten node_modules cannot make this slow. export const STAT_LIMIT = 2000; // Basename tests for files that probably hold secrets. export const ENV_OK = new Set([".env.example", ".env.sample", ".env.template"]); export function isSensitive(file) { const b = file.split("/").pop(); if (b === ".env" || (b.startsWith(".env.") && !ENV_OK.has(b))) return true; if (/\.(pem|key|p12|pfx|keystore|jks)$/.test(b)) return true; if (/^id_(rsa|dsa|ecdsa|ed25519)/.test(b)) return true; if (/^credentials.*\.json$/.test(b) || b.endsWith(".credentials")) return true; if (b === ".npmrc" || b === ".pypirc" || b === ".netrc") return true; return b.startsWith("secrets."); } /** Sensitive paths and files over 5 MB among `names` (paths from `root`). */ export function riskyFiles(root, names) { const sensitive = []; const large = []; let statted = 0; for (const p of new Set(names)) { if (isSensitive(p)) sensitive.push(p); if (statted >= STAT_LIMIT) continue; statted++; try { const st = fs.statSync(path.join(root, p)); if (st.isFile() && st.size > LARGE_BYTES) large.push({ path: p, bytes: st.size }); } catch { // a deletion, or a file that vanished } } return { sensitive: sensitive.sort(), large: large.sort((a, b) => a.path.localeCompare(b.path)) }; } /** * What a commit would take, from a parseStatusV2() result. An untracked * folder is one row (its files counted with one ls-files) and counts once; * risky files inside it still count towards heldBack. */ export function readChanges(root, parsed) { const listed = []; const untrackedDirs = []; const inside = []; for (const f of parsed?.files || []) { if (f.worktree === "?" && f.path.endsWith("/")) { const res = git(["ls-files", "-o", "--exclude-standard", "-z", "--", f.path], root, { raw: true }); const names = res.out.split("\0").filter(Boolean); untrackedDirs.push({ path: f.path, files: names.length }); inside.push(...names); } else listed.push(f); } const { sensitive, large } = riskyFiles(root, [...listed.map((f) => f.path), ...inside]); const risky = new Set([...sensitive, ...large.map((l) => l.path)]); const files = listed.map((f) => ({ path: f.path, state: f.state, risky: risky.has(f.path), staged: f.index !== " " })); return { count: files.length + untrackedDirs.length, heldBack: risky.size, files, untrackedDirs, sensitive, large }; } /* ------------------------------------------- branches and repository state */ /** origin/HEAD, else local main, else master, else (no commits, on main or master) that branch. */ export function defaultBranch(root, { branch, hasCommits } = {}) { const head = git(["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"], root); if (head.ok && head.out) return { name: head.out.replace(/^origin\//, ""), from: "origin/HEAD" }; if (git(["show-ref", "--verify", "-q", "refs/heads/main"], root).ok) return { name: "main", from: "local-main" }; if (git(["show-ref", "--verify", "-q", "refs/heads/master"], root).ok) return { name: "master", from: "local-master" }; if (!hasCommits && (branch === "main" || branch === "master")) return { name: branch, from: "unborn" }; return { name: null, from: null }; } const REF_FIELDS = [ "%(refname)", "%(refname:short)", "%(upstream:short)", "%(upstream:track)", "%(upstream:remotename)", "%(symref)", "%(committerdate:iso-strict)", "%(authorname)", "%(contents:subject)", ]; function track(text) { const ahead = text.match(/ahead (\d+)/); const behind = text.match(/behind (\d+)/); return { ahead: ahead ? Number(ahead[1]) : 0, behind: behind ? Number(behind[1]) : 0, gone: text === "[gone]" }; } // Subjects and authors go into the board verbatim: drop control bytes, or a // crafted subject (a \x01 is legal in a commit message) forges a table row. const cleanText = (s) => (s || "").replace(/[\x00-\x1f\x7f]/g, " "); /** Every ref under refs/heads and refs/remotes, from one for-each-ref. */ export function readRefs(root) { const res = git(["for-each-ref", `--format=${REF_FIELDS.join("%00")}%01`, "refs/heads", "refs/remotes"], root, { raw: true }); return res.out .split("\x01") .map((r) => r.replace(/^\r?\n/, "")) .filter(Boolean) .map((r) => { const [ref, short, upstream, trackText, upstreamRemote, symref, at, author, subject] = r.split("\0"); return { ref, short, upstream, trackText, upstreamRemote, symref, last: { subject: cleanText(subject), author: cleanText(author), at: at || "" } }; }); } /** The default branch read off refs already fetched: origin/HEAD's target, else main, else master, else the unborn branch. */ export function defaultBranchFromRefs(refs, { branch, hasCommits } = {}) { const head = refs.find((r) => r.ref === "refs/remotes/origin/HEAD"); if (head && head.symref) { const m = head.symref.match(/^refs\/remotes\/[^/]+\/(.+)$/); if (m) return { name: m[1], from: "origin/HEAD" }; } if (refs.some((r) => r.ref === "refs/heads/main")) return { name: "main", from: "local-main" }; if (refs.some((r) => r.ref === "refs/heads/master")) return { name: "master", from: "local-master" }; if (!hasCommits && (branch === "main" || branch === "master")) return { name: branch, from: "unborn" }; return { name: null, from: null }; } /** * Every local branch, plus a row for each remote branch no local branch * tracks or shares a name with, from the refs readRefs() already fetched * (and one --merged read against the default branch). */ export function branchesFromRefs(refs, root, { current, defaultName } = {}) { const refnames = new Set(refs.map((r) => r.ref)); const local = []; const remote = []; for (const r of refs) { if (r.ref.startsWith("refs/heads/")) { const name = r.ref.slice("refs/heads/".length); const t = r.upstream ? track(r.trackText || "") : { ahead: null, behind: null, gone: false }; local.push({ name, current: name === current, default: name === defaultName, remote: null, upstream: r.upstream || null, upstreamRemote: r.upstreamRemote || null, ahead: t.ahead, behind: t.behind, gone: t.gone, merged: false, last: r.last, }); } else if (r.ref.startsWith("refs/remotes/") && !r.ref.endsWith("/HEAD")) { const rest = r.ref.slice("refs/remotes/".length); const slash = rest.indexOf("/"); if (slash < 0) continue; remote.push({ short: r.short, remote: rest.slice(0, slash), name: rest.slice(slash + 1), last: r.last }); } } const tracked = new Set(local.map((b) => b.upstream).filter(Boolean)); const names = new Set(local.map((b) => b.name)); const remoteOnly = remote .filter((r) => !tracked.has(r.short) && !tracked.has(`${r.remote}/${r.name}`) && !names.has(r.name)) .map((r) => ({ name: r.name, current: false, default: r.name === defaultName, remote: r.remote, upstream: null, upstreamRemote: null, ahead: null, behind: null, gone: false, merged: false, last: r.last, })); if (defaultName) { const defaultRef = refnames.has(`refs/remotes/origin/${defaultName}`) ? `refs/remotes/origin/${defaultName}` : refnames.has(`refs/heads/${defaultName}`) ? `refs/heads/${defaultName}` : null; if (defaultRef) { const merged = new Set( git(["for-each-ref", "--merged", defaultRef, "--format=%(refname)", "refs/heads"], root).out.split(/\r?\n/).filter(Boolean), ); for (const b of local) b.merged = b.name !== defaultName && merged.has(`refs/heads/${b.name}`); } } return [...local, ...remoteOnly]; } /** Every local branch plus remote-only rows: readRefs() + branchesFromRefs() in one call. */ export function readBranches(root, { current, defaultName } = {}) { return branchesFromRefs(readRefs(root), root, { current, defaultName }); } const GIT_PATHS = ["rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "FETCH_HEAD"]; /** Where git keeps its marker files for this worktree, resolved against `root`. {} on failure. */ export function gitPaths(root) { const res = git(["rev-parse", ...GIT_PATHS.flatMap((p) => ["--git-path", p])], root); const lines = res.ok ? res.out.split(/\r?\n/) : []; if (lines.length !== GIT_PATHS.length) return {}; return Object.fromEntries(GIT_PATHS.map((name, i) => [name, path.resolve(root, lines[i])])); } const exists = (p) => !!p && fs.existsSync(p); /** * rebase, am, merge, cherry-pick, revert or null, first match wins, in that * order. The rebase dirs come first: a conflicted `merge` entry in an * interactive rebase leaves MERGE_HEAD beside rebase-merge/, and the outer * operation is the rebase. rebase-apply/applying is git's own am marker * (the rule its shell prompt uses); without it the dir is a rebase. */ export function inProgressOp(paths = {}) { if (exists(paths["rebase-merge"])) return "rebase"; if (exists(paths["rebase-apply"])) return exists(path.join(paths["rebase-apply"], "applying")) ? "am" : "rebase"; if (exists(paths.MERGE_HEAD)) return "merge"; if (exists(paths.CHERRY_PICK_HEAD)) return "cherry-pick"; if (exists(paths.REVERT_HEAD)) return "revert"; return null; } /** * The branch a rebase in progress is rewriting (rebase-merge/ or rebase-apply/ * head-name), so the board can say "main, rebasing" rather than "not on a * branch": HEAD is detached while git replays, but the person is on main. */ export function rebasingBranch(paths = {}) { for (const dir of [paths["rebase-merge"], paths["rebase-apply"]]) { if (!dir) continue; try { const ref = fs.readFileSync(path.join(dir, "head-name"), "utf8").trim(); if (ref.startsWith("refs/heads/")) return ref.slice("refs/heads/".length); } catch {} } return null; } /** FETCH_HEAD's mtime as an ISO string; null when it was never fetched. */ export function lastFetch(paths = {}) { try { return fs.statSync(paths.FETCH_HEAD).mtime.toISOString(); } catch { return null; } } /* --------------------------------------------- remotes and pull requests */ function hostKind(host) { if (host === "github.com") return "github"; if (host === "gitlab.com") return "gitlab"; if (host === "bitbucket.org") return "bitbucket"; if (host === "dev.azure.com" || host === "ssh.dev.azure.com" || host.endsWith(".visualstudio.com")) return "azure"; return null; } // user@host:path, but not a Windows drive (C:/repo) and not a URL. const SCP = /^(?:[^@/]+@)?([^:/]+):(?!\/\/)(.+)$/; /** A remote URL as { host, web, kind }; web is always https:. null when it cannot be read. */ export function parseRemoteUrl(url) { const raw = String(url || "").trim(); let host; let port = ""; let repoPath; let ssh = false; if (/^(https?|ssh):\/\//i.test(raw)) { let u; try { u = new URL(raw); } catch { return null; } host = u.hostname.toLowerCase(); ssh = u.protocol === "ssh:"; if (!ssh && u.port) port = `:${u.port}`; // Already percent-encoded, which is what a web address needs. repoPath = u.pathname; } else { const m = raw.match(SCP); if (!m || /^[A-Za-z]$/.test(m[1])) return null; host = m[1].toLowerCase(); ssh = true; repoPath = m[2]; } repoPath = repoPath.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/, ""); if (!host || !repoPath) return null; // Azure DevOps SSH remotes name the repo as v3///. const v3 = repoPath.match(/^v3\/([^/]+)\/([^/]+)\/([^/]+)$/); if (ssh && v3 && host === "ssh.dev.azure.com") { return { host: "dev.azure.com", web: `https://dev.azure.com/${v3[1]}/${v3[2]}/_git/${v3[3]}`, kind: "azure" }; } if (ssh && v3 && host === "vs-ssh.visualstudio.com") { const web = `https://${v3[1]}.visualstudio.com/${v3[2]}/_git/${v3[3]}`; return { host: `${v3[1]}.visualstudio.com`, web, kind: "azure" }; } return { host, web: `https://${host}${port}/${repoPath}`, kind: hostKind(host) }; } // Userinfo out of a scheme URL: remotes like https://user:token@host/... are // real (Azure DevOps PATs especially), and this string lands in state.json and // every state frame. Scp-style user@host:path keeps its user. const stripUserinfo = (url) => url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/i, "$1"); /** Every remote's fetch URL, web address and host kind; unknown hosts take their kind from prHosts. */ export function readRemotes(root, prHosts = {}) { const res = git(["remote", "-v"], root); const remotes = []; for (const line of res.out.split(/\r?\n/)) { const m = line.match(/^(\S+)\s+(.+?)\s+\(fetch\)$/); if (!m) continue; const parsed = parseRemoteUrl(m[2]); const host = parsed?.host || null; let kind = parsed?.kind || null; if (!kind && host && Object.hasOwn(prHosts || {}, host)) kind = prHosts[host]; remotes.push({ name: m[1], url: stripUserinfo(m[2]), host, web: parsed?.web || null, kind }); } return remotes; } export const PR_LINK_CODES = new Set(["detached", "unknown-branch", "no-base", "is-base", "not-pushed"]); function prLinkError(code, message, next, branch = null) { throw Object.assign(new Error(message), { code, next, branch }); } /** * The create-a-pull-request link for `branch` (default: the current branch) * into `base` (default: the default branch). Returns { url, host, kind, * needsKind, branch, base, ahead }; ahead is the branch's commits not yet on * its upstream. Throws an Error tagged { code, message, next, branch }, code * one of PR_LINK_CODES, when there is no link to give. */ export function prLink(root, { branch, base, prHosts = {} } = {}) { const parsed = parseStatusV2(git(["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=no"], root, { raw: true }).out); const refs = readRefs(root); const def = refs.length ? defaultBranchFromRefs(refs, parsed) : defaultBranch(root, parsed); const b = (branch || "").trim() || parsed.branch; if (!b) prLinkError("detached", "HEAD is detached, so there is no branch to open a pull request for.", "Switch to a branch, or pass --branch."); const row = branchesFromRefs(refs, root, { current: parsed.branch, defaultName: def.name }).find((r) => !r.remote && r.name === b); if (!row) prLinkError("unknown-branch", `There is no local branch named "${b}".`, "Pick a branch from the list.", b); const into = (base || "").trim() || def.name; if (!into) prLinkError("no-base", "There is no default branch to open the pull request against.", "Pass --base .", b); // A pull request from a branch into itself is no pull request (a push to main). if (into === b) prLinkError("is-base", `${b} is the branch pull requests go into, so there is nothing to open.`, "Post no link for this push.", b); const remote = row.upstream && !row.gone ? readRemotes(root, prHosts).find((r) => r.name === row.upstreamRemote) : null; if (!remote) prLinkError("not-pushed", `${b} is not on a remote yet.`, "Publish it first (plan publish).", b); return { url: prUrl(remote, { base: into, head: b }), host: remote.host, kind: remote.kind, needsKind: !!remote.host && !remote.kind, branch: b, base: into, ahead: row.ahead }; } /* ------------------------------------------------- snapshot and the count */ const MARKER = /^(<{7}|={7}|>{7})( |$)/m; function hasMarkers(file) { try { return MARKER.test(fs.readFileSync(file, "utf8")); } catch { return false; } } function safe(fn, fallback) { try { return fn(); } catch { return fallback; } } /** * The state.git snapshot of the worktree at `worktree` (its top level), from * about four git processes plus one ls-files per untracked folder. Never * throws: a git failure inside a section leaves that section empty. */ export function snapshot(worktree, { prHosts = {} } = {}) { const at = new Date().toISOString(); const floor = gitFloor(); if (!floor.ok) return { at, repo: true, error: floor.message }; const status = git(["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=normal"], worktree, { raw: true }); if (!status.ok && !git(["rev-parse", "--git-dir"], worktree).ok) return { at, repo: false }; const parsed = safe(() => parseStatusV2(status.out), parseStatusV2("")); // The branch table's for-each-ref already reads every ref: the default // branch comes off it instead of three more probes. When it is empty the // standalone probes still answer (empty repo, odd ref state). const refs = safe(() => readRefs(worktree), []); const def = refs.length ? defaultBranchFromRefs(refs, parsed) : safe(() => defaultBranch(worktree, parsed), { name: null, from: null }); const branches = safe(() => branchesFromRefs(refs, worktree, { current: parsed.branch, defaultName: def.name }), []); const paths = safe(() => gitPaths(worktree), {}); const remotes = safe(() => readRemotes(worktree, prHosts), []); const changes = safe(() => readChanges(worktree, parsed), { count: 0, heldBack: 0, files: [], untrackedDirs: [], sensitive: [], large: [] }); let pr = null; const cur = branches.find((b) => b.current && !b.remote); if (cur && cur.upstream && !cur.gone && !cur.default && def.name) { const remote = remotes.find((r) => r.name === cur.upstreamRemote); if (remote) pr = prUrl(remote, { base: def.name, head: cur.name }); } return { at, repo: true, hasCommits: parsed.hasCommits, head: { branch: parsed.branch, detached: parsed.branch ? null : parsed.oid ? parsed.oid.slice(0, 7) : null, ...(parsed.branch ? {} : { rebasing: safe(() => rebasingBranch(paths), null) }), upstream: parsed.upstream, // Its remote copy was deleted (fetch --prune): the upstream name is // still configured, but there is nothing behind it to pull or push to. gone: Boolean(cur && cur.gone), ahead: parsed.ahead, behind: parsed.behind, }, defaultBranch: def.name, inProgress: safe(() => inProgressOp(paths), null), conflicted: parsed.conflicted.map((c) => ({ ...c, markers: hasMarkers(path.join(worktree, c.path)) })), changes: { count: changes.count, heldBack: changes.heldBack, files: changes.files, untrackedDirs: changes.untrackedDirs }, remotes, lastFetch: safe(() => lastFetch(paths), null), refreshFailed: false, branches, prUrl: pr, }; } /** How many paths a commit would take from `dir` (an untracked folder counts once); null when git cannot say. */ export function countPending(dir) { const res = git(["status", "--porcelain=v2", "-z", "--untracked-files=normal"], dir, { raw: true, timeout: 3000 }); if (!res.ok) return null; try { const parsed = parseStatusV2(res.out); return parsed.files.length + parsed.conflicted.length; } catch { return null; } }