create-pmos 0.132.0 → 0.133.0

package/workspace/lib/vendor/workspace/lib/git-info.js

@@ -0,0 +1,306 @@
+'use strict';
+// Read-mostly git helpers for the workspace (branch awareness + select/create at session start).
+// Everything here shells `git` via spawnSync with an ARGS ARRAY — never a shell string — so no
+// caller input is ever interpolated into a command line.
+//
+// Two truths this module exists to keep straight:
+//   1. A workspace's working tree is SHARED by every session in it (D62), so `checkout` is a
+//      property of the REPO, not a session: switching moves every session in that repo — and every
+//      OTHER workspace registered under the same repo too. Callers surface that; we never pretend.
+//   2. The way OUT of that shared-tree constraint is a linked worktree: `addWorktree` gives a
+//      branch its own directory, so a new session can start on a new branch while every running
+//      session stays exactly where it was. That is the isolated path, and it is the default the
+//      UI offers for "+ new branch".
+//
+// "Is this a repo?" is answered by `git rev-parse`, NOT by looking for a `.git` entry: a workspace
+// registered at a SUBDIRECTORY of a repo (common for a tenant product repo added by path) is
+// inside git, and reporting "not a git repository" there was a lie that cost the PM real time.
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const GIT_TIMEOUT = 5000;   // never let a slow/hung repo (huge tree, network remote) block the server
+
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT });
+  return { code: r.status, out: (r.stdout || '').trim(), err: (r.stderr || '').trim(), failed: !!r.error };
+}
+
+// The repo's top-level directory, or null when `root` is not inside a repo. Works from any depth,
+// which is the whole point: a workspace at repo/packages/app is still in git.
+function repoRoot(root) {
+  if (!root || !isDir(root)) return null;
+  const r = git(root, ['rev-parse', '--show-toplevel']);
+  if (r.failed || r.code !== 0 || !r.out) return null;
+  const top = r.out.split('\n')[0].trim();
+  return top ? path.resolve(top) : null;
+}
+
+function isRepo(root) {
+  if (!root) return false;
+  if (repoRoot(root)) return true;
+  // git absent from PATH: fall back to the on-disk marker so we don't call a real repo "not a
+  // repo". A normal repo has a `.git` dir; a linked worktree has a `.git` FILE — both count.
+  try { return fs.existsSync(path.join(root, '.git')); } catch { return false; }
+}
+
+// git check-ref-format for a BRANCH name, re-implemented defensively so nothing dubious ever
+// reaches `git` (defense in depth — `git` itself is the final authority and rejects the rest).
+// Rejects: empty, whitespace/control, the special chars ~ ^ : ? * [ \ , the sequences .. and @{,
+// a leading '-' (would be read as a flag), leading/trailing '/' or '.', doubled '/', a trailing
+// '.lock', and the lone '@'. Allows the ordinary set A–Z a–z 0–9 . _ / -, e.g. initiative/foo-bar.
+function validBranchName(name) {
+  if (typeof name !== 'string') return false;
+  const n = name.trim();
+  if (!n || n.length > 200) return false;
+  if (/[\x00-\x20~^:?*[\\\s]/.test(n)) return false;   // control/space + git's forbidden set
+  if (n.includes('..') || n.includes('@{') || n.includes('//')) return false;
+  if (n === '@') return false;
+  if (n.startsWith('-') || n.startsWith('/') || n.startsWith('.')) return false;
+  if (n.endsWith('/') || n.endsWith('.') || n.endsWith('.lock')) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(n)) return false;
+  return true;
+}
+
+// Every working tree attached to this repo: [{ dir, branch|null }]. Used for two honest answers —
+// "this branch is already open over there" (git will refuse a second checkout of it, so the picker
+// says so instead of letting the PM hit a raw git error) and "here is where an isolated session
+// would land".
+function worktrees(root) {
+  const top = repoRoot(root);
+  return top ? worktreesAt(top) : [];
+}
+// same, for a caller that already resolved the top (saves a `git rev-parse` per call)
+function worktreesAt(top) {
+  const r = git(top, ['worktree', 'list', '--porcelain']);
+  if (r.failed || r.code !== 0 || !r.out) return [];
+  const out = [];
+  let cur = null;
+  for (const line of r.out.split('\n')) {
+    if (line.startsWith('worktree ')) { cur = { dir: line.slice(9).trim(), branch: null }; out.push(cur); }
+    else if (cur && line.startsWith('branch ')) cur.branch = line.slice(7).trim().replace(/^refs\/heads\//, '');
+  }
+  return out;
+}
+
+// The URL `origin` fetches from, or null when there is no origin (or no git at all). This is the
+// ONLY thing that can answer "did this working tree come from somewhere, or is it a folder on this
+// machine?" — the presence of a `.git` directory answers a different question and answering with it
+// would put a provenance label on a row that no read supports.
+// `git remote get-url` rather than `git config remote.origin.url`: it resolves insteadOf/pushInsteadOf
+// rewrites, so what comes back is the URL git would actually contact.
+function originUrl(root) {
+  if (!root || !isDir(root)) return null;
+  const r = git(root, ['remote', 'get-url', 'origin']);
+  if (r.failed || r.code !== 0 || !r.out) return null;
+  return r.out.split('\n')[0].trim() || null;
+}
+
+// Is this remote a GitHub one? Both URL shapes git accepts: scp-style (git@github.com:o/r.git) and
+// a real URL (https://github.com/o/r, ssh://git@github.com/o/r). Any other host — GitLab, Gitea, a
+// bare path, a local mirror — is NOT github, and saying otherwise would be the unsupported label
+// this function exists to avoid. It answers about the URL only; the caller decides what to call it.
+function isGithubRemote(url) {
+  const u = String(url || '').trim();
+  if (!u) return false;
+  const scp = u.match(/^[^/@]+@([^:/]+):/);              // git@host:owner/repo.git
+  const host = scp ? scp[1] : (u.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/:]+)/i) || [])[1];
+  if (!host) return false;
+  const h = host.toLowerCase();
+  return h === 'github.com' || h.endsWith('.github.com');
+}
+
+// Where an isolated worktree lands: a sibling of the repo, gathered under one `<repo>-worktrees/`
+// folder. Deliberately OUTSIDE the repo — nothing new appears inside the tree, so no `git status`
+// noise and nothing for .gitignore to chase. The path is derived from a name already passed
+// through validBranchName (charset A–Za–z0–9._/-, no `..`, no leading `.`), so the only
+// transformation needed is '/' → '-' to keep it one directory segment.
+function worktreePath(root, branch) {
+  const top = repoRoot(root);
+  if (!top || !validBranchName(branch)) return null;
+  return path.join(path.dirname(top), path.basename(top) + '-worktrees', branch.replace(/\//g, '-'));
+}
+
+// The start point of a NEW branch: an existing branch name or a commit id, nothing else. A name that
+// passes validBranchName cannot begin with `-`, so it cannot be read by git as an option; it must
+// also resolve to a commit, so a typo is refused here with a reason and not by git's own message.
+// No base means "where this tree is now" — git's default.
+function baseRef(root, from) {
+  if (from === null || from === undefined || from === '') return { ok: true, ref: null };
+  const ref = String(from);
+  if (!validBranchName(ref) && !/^[0-9a-f]{7,40}$/i.test(ref)) return { ok: false, error: 'invalid base' };
+  const r = git(root, ['rev-parse', '--verify', '--quiet', ref + '^{commit}']);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) return { ok: false, error: `base '${ref}' does not exist` };
+  return { ok: true, ref };
+}
+
+// Check out an existing branch, or create one with -b. THIS MOVES THE WHOLE REPO — every session
+// in every workspace under it. Confined to `root` by cwd; the name is validated first so nothing
+// malformed reaches git. On any failure returns { ok:false, error } and leaves the caller to NOT
+// spawn a session on the wrong branch (a failed checkout must never spawn).
+function checkout(root, branch, { create = false, from = null } = {}) {
+  if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
+  if (!validBranchName(branch)) return { ok: false, error: 'invalid branch name' };
+  const base = baseRef(root, from);
+  if (!base.ok) return base;
+  const args = create ? ['checkout', '-b', branch, ...(base.ref ? [base.ref] : []), '--'] : ['checkout', branch, '--'];
+  const r = git(root, args);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) return { ok: false, error: (r.err || r.out || 'checkout failed').split('\n')[0].slice(0, 200) };
+  const info = branchInfo(root);
+  return { ok: true, current: info.ok ? info.current : branch };
+}
+
+// Put `branch` in its OWN working tree, so a session can start on it while every already-running
+// session stays untouched. `create` makes the branch (`-b`); otherwise the branch must exist and
+// must not already be checked out somewhere else (git refuses — we return that plainly).
+// Returns { ok, dir, branch, reused } or { ok:false, error }.
+function addWorktree(root, branch, { create = false, from = null } = {}) {
+  const top = repoRoot(root);
+  if (!top) return { ok: false, error: 'not a git repository' };
+  if (!validBranchName(branch)) return { ok: false, error: 'invalid branch name' };
+  const base = baseRef(top, from);
+  if (!base.ok) return base;
+
+  // Already checked out somewhere? Say where, rather than letting git's message be the first the
+  // PM sees — and if it is exactly the worktree we would have made, reuse it instead of failing.
+  const dir = worktreePath(top, branch);
+  const existing = worktreesAt(top).find((w) => w.branch === branch);
+  if (existing) {
+    if (create) return { ok: false, error: `branch '${branch}' already exists (checked out at ${existing.dir})` };
+    if (path.resolve(existing.dir) === path.resolve(dir)) return { ok: true, dir, branch, reused: true };
+    return { ok: false, error: `branch '${branch}' is already checked out at ${existing.dir} — git allows one working tree per branch` };
+  }
+  if (fs.existsSync(dir)) return { ok: false, error: `${dir} already exists — move or remove it, or pick another branch name` };
+
+  try { fs.mkdirSync(path.dirname(dir), { recursive: true }); }
+  catch (e) { return { ok: false, error: `cannot create ${path.dirname(dir)}: ${e.code || e.message}` }; }
+
+  const args = create ? ['worktree', 'add', '-b', branch, dir, ...(base.ref ? [base.ref] : [])] : ['worktree', 'add', dir, branch];
+  const r = git(top, args);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) {
+    // never leave a half-made directory behind to block the next attempt
+    try { if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir); } catch {}
+    return { ok: false, error: (r.err || r.out || 'worktree add failed').split('\n').filter(Boolean).pop().slice(0, 200) };
+  }
+  return { ok: true, dir, branch, reused: false };
+}
+
+// Everything needed to decide whether a worktree can be removed WITHOUT losing work. Two hazards
+// live in git itself, and each is reported BY NAME so the UI can say why rather than just greying
+// out a button:
+//   dirty          — uncommitted or untracked files sitting in the tree
+//   unique commits — commits on this branch that no other branch, remote or tag holds, so removing
+//                    the tree is the last thing standing between them and `git gc`
+// Anything unreadable counts as unsafe: this gates a delete, so "I could not check" must never
+// read as "fine". (The caller adds the two hazards git cannot see: live sessions in the tree, and
+// "this is the repo's main worktree".)
+function worktreeSafety(dir, branch) {
+  const reasons = [];
+  const st = git(dir, ['status', '--porcelain']);
+  const dirty = st.failed || st.code !== 0 ? true : st.out.length > 0;
+  if (dirty) reasons.push(st.code === 0 ? 'uncommitted changes' : 'its state could not be read');
+
+  let unique = 0;
+  if (!branch) {
+    unique = -1;
+    reasons.push('detached HEAD — no branch names its commits');
+  } else {
+    // "commits reachable from this branch and from nothing else". --exclude applies to the NEXT
+    // ref-listing option only, so --branches drops this branch while --remotes and --tags still
+    // count: a copy on a remote means the commits survive the removal.
+    const rl = git(dir, ['rev-list', '--count', 'refs/heads/' + branch,
+      '--not', '--exclude=' + branch, '--branches', '--remotes', '--tags']);
+    unique = rl.code === 0 && /^\d+$/.test(rl.out) ? parseInt(rl.out, 10) : -1;
+    if (unique > 0) reasons.push(`${unique} commit${unique === 1 ? '' : 's'} not on any other branch or remote`);
+    if (unique < 0) reasons.push('could not verify its commits exist elsewhere');
+  }
+  return { removable: reasons.length === 0, reasons, dirty, unique };
+}
+
+// Remove a linked worktree, refusing anything that would lose work. `dir` arrives from a client, so
+// it is never passed through as given: it must match one of THIS repo's linked worktrees (git's own
+// list is the allowlist), and the main worktree is unreachable by construction. The BRANCH is left
+// alone — a branch is a cheap pointer, and deleting one is a different decision than reclaiming a
+// directory.
+function removeWorktree(root, dir) {
+  const top = repoRoot(root);
+  if (!top) return { ok: false, error: 'not a git repository' };
+  const trees = worktreesAt(top);
+  // index 0 is always the main worktree — sliced off, so it can never be the target
+  const target = trees.slice(1).find((w) => path.resolve(w.dir) === path.resolve(String(dir || '')));
+  if (!target) return { ok: false, error: 'not a linked worktree of this repository' };
+
+  // Gone from disk already (the PM deleted it by hand): there is nothing to protect, just stale
+  // bookkeeping to clear.
+  if (!isDir(target.dir)) {
+    const p = git(top, ['worktree', 'prune']);
+    if (p.code !== 0) return { ok: false, error: (p.err || 'prune failed').split('\n')[0].slice(0, 200) };
+    return { ok: true, dir: target.dir, pruned: true };
+  }
+
+  const safety = worktreeSafety(target.dir, target.branch);
+  if (!safety.removable) return { ok: false, error: 'kept — ' + safety.reasons.join('; '), safety };
+  const r = git(top, ['worktree', 'remove', target.dir]);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) return { ok: false, error: (r.err || r.out || 'worktree remove failed').split('\n').filter(Boolean).pop().slice(0, 200) };
+  return { ok: true, dir: target.dir, branch: target.branch, pruned: false };
+}
+
+// { ok, current, detached } — only the HEAD half of branchInfo, with the same failure codes. The
+// workspace list and the session heartbeat need the branch name and nothing else; branchInfo also
+// lists every branch, runs `git status --porcelain` and lists the worktrees, which on a large repo
+// is most of the cost and was paid for every workspace every 15 seconds. `top` may be passed when
+// the caller already resolved the repo root, saving one more shell-out.
+function headInfo(root, top) {
+  const t = top === undefined ? repoRoot(root) : top;
+  if (!t) {
+    if (!isRepo(root)) return { ok: false, code: 'no-git', error: 'not a git repository' };
+    return { ok: false, code: 'git-error', error: 'git not available' };
+  }
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head.failed) return { ok: false, code: 'git-error', error: 'git not available' };
+  if (head.code !== 0) return { ok: false, code: 'git-error', error: head.err || 'could not read HEAD' };
+  const detached = head.out === 'HEAD';
+  return { ok: true, current: detached ? null : head.out, detached };
+}
+
+// { ok, current, branches[], detached, dirty, repoRoot, subdir, linked, worktrees[] }. A non-repo
+// or a failed git returns ok:false with a reason — NEVER a fabricated branch (a wrong branch chip
+// is worse than none; anti-drift). `subdir` is the workspace's path INSIDE the repo ('' at the
+// top): non-empty means a checkout here moves a tree larger than this workspace, which the UI says
+// out loud.
+function branchInfo(root) {
+  // `code` lets a caller tell the two failures apart without matching on prose: `no-git` is a
+  // perfectly normal folder (a tenant product repo with no git at all) and deserves no alarm;
+  // `git-error` is something the PM may want to look at.
+  const top = repoRoot(root);
+  if (!top) {
+    if (!isRepo(root)) return { ok: false, code: 'no-git', error: 'not a git repository' };
+    return { ok: false, code: 'git-error', error: 'git not available' };
+  }
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head.failed) return { ok: false, code: 'git-error', error: 'git not available' };
+  if (head.code !== 0) return { ok: false, code: 'git-error', error: head.err || 'could not read HEAD' };
+  const detached = head.out === 'HEAD';
+  const current = detached ? null : head.out;
+  const refs = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
+  const branches = refs.code === 0 && refs.out ? refs.out.split('\n').filter(Boolean) : [];
+  const status = git(root, ['status', '--porcelain']);
+  const dirty = status.code === 0 ? status.out.length > 0 : false;
+  const rel = path.relative(top, path.resolve(root));
+  const trees = worktreesAt(top);
+  const linked = path.resolve(top) !== path.resolve(trees[0] ? trees[0].dir : top);
+  return {
+    ok: true, current, branches, detached, dirty,
+    repoRoot: top, subdir: rel === '' || rel === '.' ? '' : rel, linked,
+    worktrees: trees.map((w) => ({ dir: w.dir, branch: w.branch })),
+  };
+}
+
+module.exports = { isRepo, repoRoot, validBranchName, branchInfo, headInfo, checkout, worktrees, worktreePath,
+  addWorktree, worktreeSafety, removeWorktree, originUrl, isGithubRemote };