gitroots 0.0.0-stage → 0.5.0

package/src/commands/push.js

@@ -0,0 +1,273 @@
+// git push · gitroots checks
+//   gitroots hooks install|uninstall   writes .git/hooks/pre-push
+//   gitroots hook pre-push <remote> <url>   (called by git, refs on stdin)
+//   gitroots check [base..head]        same checks without pushing
+import fs from 'node:fs';
+import path from 'node:path';
+import { selfCommand } from '../runtime.js';
+import { c, pad } from '../ui/ansi.js';
+import { line, runSteps } from '../ui/term.js';
+import { brand, dot, box, json } from '../ui/components.js';
+import { git, tryGit, ZERO, commitsToPush, changedFiles, addedLines, scanSecrets, authors, MIGRATION_RE, lastSubjectSlug } from '../git/checks.js';
+
+const MARK = '# gitroots push checks';
+
+export async function run(cmd, rest, flags, store) {
+  if (cmd === 'hooks') {
+    const [sub = 'install', dir = '.'] = rest;
+    if (sub === 'install') {
+      const r = installHook(dir, { force: flags.force });
+      if (flags.json) { json(r); return 0; }
+      line(`  ${c.g('✓')} Push checks installed   ${c.m(r.path.replace(process.env.HOME || '\u0000', '~'))}${r.chained ? c.m(` · your previous hook runs first (${path.basename(r.chained)})`) : ''}`);
+      line(`    ${c.m('git push now runs gitroots checks first')}     ${c.g('→ gitroots check')}`);
+      return 0;
+    }
+    if (sub === 'uninstall') {
+      const r = uninstallHook(dir);
+      if (flags.json) { json(r); return 0; }
+      line(r.removed ? `  ${c.g('✓')} Push checks removed` : `  ${c.m('○ no gitroots hook installed')}`);
+      return 0;
+    }
+    throw new Error('usage: gitroots hooks install|uninstall [dir]');
+  }
+  if (cmd === 'hook') {
+    const [kind, remote, url] = rest;
+    if (kind !== 'pre-push') throw new Error(`unknown hook ${kind}`);
+    let input = '';
+    try { input = fs.readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+    return prePush({ remote, url, input, store, flags });
+  }
+  // check
+  return checkLocal(rest, flags, store);
+}
+
+function hooksDir(dir) {
+  const top = tryGit(['rev-parse', '--show-toplevel'], dir);
+  if (!top) throw new Error(`${path.resolve(dir)} is not a git repository`);
+  return path.resolve(dir, git(['rev-parse', '--git-path', 'hooks'], dir).trim());
+}
+
+export function installHook(dir = '.', { force = false } = {}) {
+  const hd = hooksDir(dir);
+  fs.mkdirSync(hd, { recursive: true });
+  const file = path.join(hd, 'pre-push');
+  let chained = null;
+  if (fs.existsSync(file)) {
+    const existing = fs.readFileSync(file, 'utf8');
+    if (!existing.includes(MARK)) {
+      if (!force) throw new Error(`a pre-push hook already exists at ${file} · rerun with --force to keep it and run it before gitroots`);
+      chained = path.join(hd, 'pre-push.local');
+      fs.renameSync(file, chained);
+    } else if (fs.existsSync(path.join(hd, 'pre-push.local'))) chained = path.join(hd, 'pre-push.local');
+  }
+  const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+  // The gitroots that installed the hook; if it moved (update, node version switch), the launcher or PATH.
+  const cmd = selfCommand();
+  const self = cmd.map(q).join(' ');
+  const script = `#!/bin/sh
+${MARK} · installed by gitroots hooks install
+input=$(cat)
+here=$(dirname "$0")
+if [ -x "$here/pre-push.local" ]; then
+  printf '%s\\n' "$input" | "$here/pre-push.local" "$@" || exit $?
+fi
+if [ -x ${q(cmd[0])} ] && { [ ${cmd.length} -eq 1 ] || [ -f ${q(cmd[cmd.length - 1])} ]; }; then
+  printf '%s\\n' "$input" | ${self} hook pre-push "$@"; exit $?
+elif [ -x "$HOME/.local/bin/gitroots" ]; then
+  printf '%s\\n' "$input" | "$HOME/.local/bin/gitroots" hook pre-push "$@"; exit $?
+elif command -v gitroots >/dev/null 2>&1; then
+  printf '%s\\n' "$input" | gitroots hook pre-push "$@"; exit $?
+fi
+echo "gitroots: push checks could not run (gitroots not found) · reinstall with gitroots hooks install" >&2
+exit 1
+`;
+  fs.writeFileSync(file, script, { mode: 0o755 });
+  return { path: file, chained };
+}
+
+function uninstallHook(dir = '.') {
+  const hd = hooksDir(dir);
+  const file = path.join(hd, 'pre-push');
+  if (!fs.existsSync(file) || !fs.readFileSync(file, 'utf8').includes(MARK)) return { removed: false };
+  fs.rmSync(file);
+  const local = path.join(hd, 'pre-push.local');
+  if (fs.existsSync(local)) fs.renameSync(local, file);
+  return { removed: true, restored: fs.existsSync(file) };
+}
+
+/**
+ * Run every check for one ref update. Returns { blocked, reason, results }.
+ */
+async function checkRef({ store, repoName, branch, localSha, remoteSha, cwd, quiet }) {
+  const commits = commitsToPush(localSha, remoteSha, cwd);
+  const cfg = repoName ? null : repoConfig(cwd);
+  const rule = repoName ? store.ruleFor(repoName, branch) : configRule(store, cfg, branch);
+  const paths = repoName ? store.protectedPaths(repoName) : (cfg?.paths || []);
+
+  if (rule.protected && rule.directPush === false) {
+    return { blocked: true, kind: 'rule', rule, commits };
+  }
+  if (!quiet) line(`${brand()}  ${c.s(`checking ${commits.length} commit${commits.length === 1 ? '' : 's'} before ${commits.length === 1 ? 'it leaves' : 'they leave'}`)}`);
+  let files = [];
+  let secretHits = [];
+  const steps = [
+    { name: 'Branch rule', live: `reading rules for ${branch}…`, ms: 400, run: async () => ({ detail: `${rule.name === '*' ? branch : rule.name} · ${rule.label.replace(/^[^·]*· /, '')}` }) },
+    {
+      name: 'Protected paths', live: 'checking changed files…', ms: 400,
+      run: async () => {
+        files = changedFiles(commits, cwd);
+        if (!paths.length) return { detail: `${files.length} files changed · no protected paths on ${branch}` };
+        const hits = files.filter((f) => paths.some((p) => store.matchPath(p.pattern, f)));
+        if (!hits.length) return { detail: `no files under ${paths.map((p) => p.pattern).join(', ')}` };
+        const p = paths.find((x) => hits.some((f) => store.matchPath(x.pattern, f)));
+        return { status: 'warn', detail: `${hits.length} file${hits.length > 1 ? 's' : ''} under ${p.pattern} · needs ${p.needs}`, hits };
+      },
+    },
+    {
+      name: 'Secrets scan', live: `scanning ${commits.length} commits…`, ms: 600,
+      run: async () => {
+        secretHits = scanSecrets(addedLines(commits, cwd));
+        if (!secretHits.length) return { detail: '0 keys or passwords found' };
+        const f = secretHits[0];
+        return { status: 'fail', detail: `${f.kind} in ${f.file}:${f.line}${secretHits.length > 1 ? ` · ${secretHits.length - 1} more` : ''}` };
+      },
+    },
+    {
+      name: 'Commit authors', live: 'checking authors…', ms: 300,
+      run: async () => {
+        const a = authors(commits, cwd);
+        const names = [...new Set(a.map((x) => x.name))];
+        const signed = a.filter((x) => x.signed).length;
+        const sig = !a.length ? '' : signed === a.length ? ' · verified' : signed ? ` · ${signed} of ${a.length} signed` : ' · unsigned';
+        return { detail: `${a.length} commit${a.length === 1 ? '' : 's'} · ${names.slice(0, 3).join(', ')}${names.length > 3 ? ` +${names.length - 3}` : ''}${sig}` };
+      },
+    },
+    {
+      name: 'Migration files', live: 'looking for database changes…', ms: 400,
+      run: async () => {
+        const mig = files.filter((f) => MIGRATION_RE.test(f));
+        if (!mig.length) return { detail: 'no database changes' };
+        return { status: 'warn', detail: `${path.basename(mig[0])}${mig.length > 1 ? ` +${mig.length - 1}` : ''} changes data, flagged for review` };
+      },
+    },
+  ];
+  const results = await runSteps(steps, { nameWidth: 20, showQueued: true });
+  if (secretHits.length) return { blocked: true, kind: 'secret', hits: secretHits, rule, commits, results };
+  return { blocked: false, rule, commits, results, files };
+}
+
+// Rules for repositories outside the gitroots org: .gitroots.json at the repo root.
+//   { "protected": ["main", "release/*"], "paths": [{ "pattern": "infra/**", "needs": "an ops review" }] }
+export function repoConfig(cwd) {
+  const top = tryGit(['rev-parse', '--show-toplevel'], cwd);
+  if (!top) return null;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(top, '.gitroots.json'), 'utf8'));
+    return { repo: cfg.repo || path.basename(top), protected: cfg.protected || [], paths: (cfg.paths || []).map((p) => (typeof p === 'string' ? { pattern: p, needs: 'a review' } : p)), suggest: cfg.suggest };
+  } catch { return null; }
+}
+
+function configRule(store, cfg, branch) {
+  if (!cfg) return { name: '*', protected: false, directPush: true, label: 'repository not managed by gitroots' };
+  const hit = cfg.protected.find((p) => store.matchPath(p, branch));
+  if (hit) return { name: hit, protected: true, directPush: false, label: `${hit}: no direct push, PR only`, suggest: cfg.suggest || 'push to a feature branch, then open a PR' };
+  return { name: '*', protected: false, directPush: true, label: 'developers can push · .gitroots.json' };
+}
+
+function blockedBox(store, { repoName, branch, rule, localSha, cwd, ev, remote }) {
+  const slug = lastSubjectSlug(localSha, cwd);
+  box([
+    `${brand()}  ${c.r(c.b('✕ Push blocked'))}   ${c.m('nothing left your machine')}`,
+    `  ${c.s('repo')}     ${repoName} ${dot()} ${c.s('branch')} ${branch} ${dot()} ${c.s('rule')} ${rule.label}`,
+    `  ${c.s('you can')}  ${rule.suggest || 'push to a feature branch, then open a PR'}`,
+    `  ${c.g(`→ git switch -c feature/${slug} && git push -u ${remote || 'origin'} feature/${slug}`)}      ${c.m(`this attempt is logged · ${ev.id}`)}`,
+  ], 'r');
+}
+
+export async function prePush({ remote, url, input, store, flags }) {
+  const cwd = process.cwd();
+  const repo = store.repoByRemote(url);
+  const repoName = repo ? repo.name : null;
+  const shownName = repoName || repoConfig(cwd)?.repo || path.basename(cwd);
+  const updates = input.split('\n').map((l) => l.trim().split(/\s+/)).filter((p) => p.length === 4);
+  let code = 0;
+  for (const [localRef, localSha, remoteRef, remoteSha] of updates) {
+    if (!remoteRef.startsWith('refs/heads/')) continue; // tags are not checked
+    const branch = remoteRef.slice('refs/heads/'.length);
+    if (ZERO.test(localSha)) {
+      const rule = repoName ? store.ruleFor(repoName, branch) : configRule(store, repoConfig(cwd), branch);
+      if (rule.protected) {
+        const ev = store.record({ actor: store.org.user, action: 'delete branch', target: `${branch}`, decision: 'blocked', note: rule.label, repo: shownName, rule: rule.label });
+        store.save();
+        line(`${brand()}  ${c.r('✕ Deleting a protected branch is blocked')}  ${c.m(`${shownName} · ${branch} · ${ev.id}`)}`);
+        code = 1;
+      }
+      continue;
+    }
+    const res = await checkRef({ store, repoName, branch, localSha, remoteSha, cwd });
+    if (res.blocked && res.kind === 'rule') {
+      const ev = store.record({ actor: store.org.user, action: 'push', target: `${branch} · ${res.commits.length} commit${res.commits.length === 1 ? '' : 's'}`, decision: 'blocked', note: res.rule.label, repo: shownName, rule: res.rule.label, ack: true });
+      store.save();
+      blockedBox(store, { repoName: shownName, branch, rule: res.rule, localSha, cwd, ev, remote });
+      code = 1;
+      continue;
+    }
+    if (res.blocked) {
+      const h0 = res.hits[0];
+      const ev = store.record({ actor: store.org.user, action: 'push', target: `${branch} · secrets scan`, decision: 'blocked', note: `${h0.kind} in ${path.basename(h0.file)}`, repo: shownName });
+      store.save();
+      line();
+      box([
+        `${brand()}  ${c.r(c.b('✕ Push blocked'))}   ${c.m('nothing left your machine')}`,
+        ...res.hits.slice(0, 4).map((x) => `  ${c.r('✕')} ${pad(x.kind, 18)} ${x.file}:${x.line}  ${c.m(`commit ${x.sha.slice(0, 7)}`)}`),
+        `  ${c.s('you can')}  remove the secret, rotate it, then rewrite the commit (git commit --amend or git rebase -i)`,
+        `  ${c.m(`this attempt is logged · ${ev.id}`)}`,
+      ], 'r');
+      code = 1;
+      continue;
+    }
+    const warns = res.results.filter((r) => r.status === 'warn').length;
+    store.record({ actor: store.org.user, action: 'push', target: `${branch} · ${res.commits.length} commit${res.commits.length === 1 ? '' : 's'}`, decision: 'allowed', note: warns ? `${warns} note${warns > 1 ? 's' : ''} for review` : 'checks passed', repo: shownName });
+    store.save();
+    const pr = repoName && store.prs(repoName).find((p) => p.from === branch && p.state === 'open');
+    const tail = pr ? `PR #${pr.number} will update ${dot()} reviewers notified` : `pushing to ${remote || 'origin'}`;
+    line(`${brand()}  ${c.g('✓ Checks passed')} ${dot()} ${tail}${warns ? ` ${dot()} ${warns} note${warns > 1 ? 's' : ''} for review` : ''}${pr ? `       ${c.g(`→ gitroots pr view ${pr.number}`)}` : ''}`);
+  }
+  if (flags?.json) json({ ok: code === 0 });
+  return code;
+}
+
+async function checkLocal(rest, flags, store) {
+  const cwd = process.cwd();
+  if (!tryGit(['rev-parse', '--show-toplevel'], cwd)) throw new Error('not inside a git repository');
+  let localSha;
+  let remoteSha = '';
+  const range = rest[0];
+  if (range && range.includes('..')) {
+    const [a, b] = range.split('..');
+    remoteSha = git(['rev-parse', a || 'HEAD'], cwd).trim();
+    localSha = git(['rev-parse', b || 'HEAD'], cwd).trim();
+  } else {
+    localSha = git(['rev-parse', range || 'HEAD'], cwd).trim();
+    const up = tryGit(['rev-parse', '@{upstream}'], cwd);
+    remoteSha = up || '';
+  }
+  const current = tryGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  const branch = flags.branch || current;
+  const url = tryGit(['remote', 'get-url', tryGit(['config', `branch.${current}.remote`], cwd) || 'origin'], cwd);
+  const repo = store.repoByRemote(url) || (flags.repo ? store.repo(flags.repo) : null);
+  line(`${c.m(cwd.replace(process.env.HOME || '\u0000', '~'))} ${c.i(branch)}${repo ? c.m(`  ${dot()} gitroots repo ${repo.name}`) : (repoConfig(cwd) ? c.m(`  ${dot()} rules from .gitroots.json`) : c.m(`  ${dot()} not a gitroots repo, default rules`))}`);
+  const res = await checkRef({ store, repoName: repo?.name, branch, localSha, remoteSha, cwd });
+  if (res.blocked && res.kind === 'rule') {
+    line(`${brand()}  ${c.r('✕ This push would be blocked')}  ${c.m(`rule ${res.rule.label}`)}`);
+    line(`  ${c.s('you can')}  ${res.rule.suggest || 'push to a feature branch, then open a PR'}`);
+    return 1;
+  }
+  if (res.blocked) {
+    for (const x of res.hits.slice(0, 6)) line(`  ${c.r('✕')} ${pad(x.kind, 18)} ${x.file}:${x.line}  ${c.m(`commit ${x.sha.slice(0, 7)}`)}`);
+    line(`${brand()}  ${c.r('✕ This push would be blocked')}  ${c.m('remove the secret and rewrite the commit')}`);
+    return 1;
+  }
+  line(`${brand()}  ${c.g('✓ Ready to push')}       ${c.g('→ git push')}`);
+  return 0;
+}

package/src/commands/repos.js

@@ -0,0 +1,122 @@
+// gitroots repo list · branch list · branch rules · clone
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { c, h, pad } from '../ui/ansi.js';
+import { line } from '../ui/term.js';
+import { dot, json, next } from '../ui/components.js';
+import { installHook } from './push.js';
+import { apiRepos, apiBranches } from '../connected.js';
+
+export async function run(cmd, rest, flags, store) {
+  if (cmd === 'clone') return clone(rest, flags, store);
+  const [sub = 'list', ...args] = rest;
+  if (cmd === 'repo' || cmd === 'repos') {
+    if (sub === 'list' || sub === 'ls') return repoList(flags, store);
+    if (sub === 'view') return branchRules([args[0], store.repo(args[0]).default], flags, store);
+    throw new Error(`unknown: gitroots repo ${sub} · try gitroots repo list`);
+  }
+  if (sub === 'list' || sub === 'ls') return branchList(args, flags, store);
+  if (sub === 'rules') return branchRules(args, flags, store);
+  if (sub === 'restore') return branchRestore(args, flags, store);
+  throw new Error(`unknown: gitroots branch ${sub} · try gitroots branch list <repo>`);
+}
+
+async function repoList(flags, store) {
+  const repos = store.api ? await apiRepos(store) : store.repos();
+  if (flags.json) { json(repos); return 0; }
+  line(`  ${h(`${pad('NAME', 14)}${pad('PROVIDER', 11)}${pad('DEFAULT', 10)}${pad('PROTECTED', 12)}${pad('BRANCHES', 11)}${pad('OPEN PRS', 11)}${pad('YOUR ROLE', 14)}LAST PUSH`)}`);
+  for (const r of repos) {
+    line(`  ${c.b(pad(r.name, 14))}${pad(r.provider, 11)}${pad(r.default, 10)}${pad(r.protected.length ? String(r.protected.length) : c.m('—'), 12)}${pad(String(r.branches), 11)}${pad(r.openPrs === null ? c.m('—') : String(r.openPrs), 11)}${pad(r.role, 14)}${r.lastPush || c.m('—')}`);
+  }
+  if (!repos.length) line(c.m(store.api ? '  no repositories synced yet · connect GitHub in the gitroots dashboard' : '  no repositories'));
+  line();
+  line(next(`gitroots branch list ${repos[0]?.name || '<repo>'}`));
+  return 0;
+}
+
+function ruleCell(b) {
+  return b.rule === 'protected' ? `${c.g(pad('● protected', 12))} ${pad(b.ruleText, 28)}` : `${c.i(pad('○ open', 12))} ${pad(b.ruleText, 28)}`;
+}
+
+async function branchList([repoName], flags, store) {
+  if (!repoName) throw new Error('which repository? gitroots branch list <repo>');
+  const all = store.api ? await apiBranches(store, repoName) : store.branches(repoName);
+  const shown = flags.all ? all : all.slice(0, 6);
+  if (flags.json) { json(all); return 0; }
+  line(`  ${h(`${pad('BRANCH', 24)}${pad('RULE', 41)}${pad('APPROVALS', 12)}${pad('LAST COMMIT', 25)}AHEAD / BEHIND`)}`);
+  for (const b of shown) {
+    const name = b.rule === 'protected' ? c.b(pad(b.name, 24)) : pad(b.name, 24);
+    const appr = b.approvals ? pad(String(b.approvals), 12) : c.m(pad('—', 12));
+    line(`  ${name}${ruleCell(b)}${appr}${pad(b.commit ? `${b.commit}  ${b.by} · ${b.age}` : c.m('—'), 25)}${c.m(b.aheadBehind || '—')}`);
+  }
+  if (all.length > shown.length) line(`  ${c.m(`+ ${all.length - shown.length} more · gitroots branch list ${repoName} --all`)}`);
+  line();
+  const prot = all.find((b) => b.rule === 'protected' && b.name !== 'main') || all[0];
+  if (prot) line(next(`gitroots branch rules ${repoName} ${prot.name}`));
+  return 0;
+}
+
+function branchRules([repoName, branch], flags, store) {
+  if (!repoName || !branch) throw new Error('usage: gitroots branch rules <repo> <branch>');
+  if (!store.api) store.repo(repoName);
+  const rule = store.ruleFor(repoName, branch);
+  const paths = store.protectedPaths(repoName);
+  const agents = store.rules(repoName).agents;
+  if (flags.json) { json({ repo: repoName, branch, rule, paths, agents }); return 0; }
+  line(`  ${c.b(branch)}  ${rule.protected ? c.g('● protected') : c.i('○ open')}`);
+  if (rule.protected) {
+    line(`    ${pad('push', 13)}${c.r('✕')} ${pad(rule.push, 44)} ${c.m('changes arrive through PRs')}`);
+    line(`    ${pad('merge', 13)}${c.g('✓')} ${rule.mergeText}`);
+  } else {
+    line(`    ${pad('push', 13)}${c.g('✓')} ${rule.label}`);
+    line(`    ${pad('merge', 13)}${c.g('✓')} through a PR into a protected branch`);
+  }
+  for (const p of paths) line(`    ${pad('paths', 13)}${c.w('◐')} ${p.pattern} needs ${p.needs}`);
+  if (agents) line(`    ${pad('agents', 13)}${c.g('✓')} ${agents}`);
+  line();
+  line(next(`gitroots clone ${repoName}`));
+  return 0;
+}
+
+function branchRestore([repoName, branch], flags, store) {
+  if (!repoName || !branch) throw new Error('usage: gitroots branch restore <repo> <branch>');
+  store.repo(repoName);
+  const deleted = (store.d.deletedBranches || {})[repoName] || [];
+  const b = deleted.find((x) => x.name === branch);
+  if (!b) throw new Error(`no deleted branch ${branch} in ${repoName}`);
+  store.d.deletedBranches[repoName] = deleted.filter((x) => x !== b);
+  store.d.branches[repoName].push(b);
+  const ev = store.record({ actor: store.org.user, action: 'branch restore', target: `${repoName} ${branch}`, decision: 'allowed', repo: repoName });
+  store.save();
+  if (flags.json) { json({ restored: b, event: ev.id }); return 0; }
+  line(`  ${c.g('✓')} Restored ${c.b(branch)} at ${b.commit}   ${c.m(`audit ${ev.id}`)}`);
+  return 0;
+}
+
+function clone([target, dirArg], flags, store) {
+  if (!target) throw new Error('usage: gitroots clone <repo|git-url> [dir]');
+  const isUrl = /[:/]/.test(target);
+  const repo = isUrl ? store.repoByRemote(target) : store.repo(target);
+  const name = repo ? repo.name : path.basename(target).replace(/\.git$/, '');
+  const url = flags.url || (isUrl ? target : null);
+  const dir = path.resolve(dirArg || name);
+  const shown = dir.replace(process.env.HOME || '\u0000', '~');
+
+  if (!url) {
+    // Demo org repositories have no reachable remote: show what clone does.
+    if (flags.json) { json({ repo: name, dir, cloned: false, reason: 'demo repository has no remote · pass --url' }); return 0; }
+    line(`  ${c.g('✓')} Cloned ${name} into ${shown}   ${c.m(`${repo?.branches ?? '?'} branches · default ${repo?.default ?? 'main'}`)}`);
+    line(`  ${c.g('✓')} Push checks installed        ${c.m('git push now runs gitroots checks first')}     ${c.g(`→ cd ${name} && git switch -c feature/…`)}`);
+    line(c.m(`  sample data · nothing was cloned · gitroots clone ${name} --url <git-url> clones for real`));
+    return 0;
+  }
+  const r = spawnSync('git', ['clone', url, dir], { stdio: flags.json ? 'ignore' : ['ignore', 'ignore', 'inherit'] });
+  if (r.status !== 0) { line(`  ${c.r('✕')} git clone failed ${c.m(`(exit ${r.status})`)}`); return r.status || 1; }
+  const branches = spawnSync('git', ['-C', dir, 'branch', '-r'], { encoding: 'utf8' }).stdout.split('\n').filter((l) => l.trim() && !l.includes('->')).length;
+  const def = (spawnSync('git', ['-C', dir, 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).stdout || 'main').trim();
+  const hook = installHook(dir, { force: true, repo: name });
+  if (flags.json) { json({ repo: name, dir, cloned: true, branches, default: def, hook: hook.path }); return 0; }
+  line(`  ${c.g('✓')} Cloned ${name} into ${shown}   ${c.m(`${branches} branches ${dot()} default ${def}`)}`);
+  line(`  ${c.g('✓')} Push checks installed        ${c.m('git push now runs gitroots checks first')}     ${c.g(`→ cd ${path.basename(dir)} && git switch -c feature/…`)}`);
+  return 0;
+}

package/src/commands/restore.js

@@ -0,0 +1,125 @@
+// gitroots restore <session|backup> [--machine m] [--pick] [--point turn|b-id] [--fork]
+import { c, h, pad, fit } from '../ui/ansi.js';
+import { line, runSteps, select, interactive, size } from '../ui/term.js';
+import { dot, json, next, sessionState } from '../ui/components.js';
+
+export async function run(_cmd, rest, flags, store) {
+  const [target] = rest;
+  if (!target) throw new Error('usage: gitroots restore <session|backup> [--machine m] [--pick] [--fork]');
+  return restore(store, target, flags);
+}
+
+function pointsFor(store, s) {
+  return store.backups().filter((b) => b.session === s.id).sort((a, b) => b.turn - a.turn);
+}
+
+function panels(left, right, total) {
+  const w = Math.floor((total - 2) / 2);
+  const inner = w - 4;
+  const rows = Math.max(left.length, right.length);
+  const out = [];
+  const top = c.m(`╭${'─'.repeat(w - 2)}╮`);
+  const bot = c.m(`╰${'─'.repeat(w - 2)}╯`);
+  out.push(`${top}  ${top}`);
+  for (let i = 0; i < rows; i++) {
+    out.push(`${c.m('│')} ${fit(left[i] || '', inner)} ${c.m('│')}  ${c.m('│')} ${fit(right[i] || '', inner)} ${c.m('│')}`);
+  }
+  out.push(`${bot}  ${bot}`);
+  return out.join('\n');
+}
+
+export async function restore(store, target, flags = {}) {
+  let s;
+  let point;
+  if (/^b-\d+$/.test(target)) { point = store.backup(target); s = store.session(point.session); } else s = store.session(target);
+  const points = pointsFor(store, s);
+  if (!points.length) throw new Error(`no backups for ${s.id} · gitroots backup ${s.id} makes one`);
+  if (!point && flags.point) {
+    point = /^b-/.test(flags.point) ? store.backup(flags.point) : points.find((p) => String(p.turn) === String(flags.point).replace(/^turn\s*/, ''));
+    if (!point) throw new Error(`no restore point ${flags.point} for ${s.id}`);
+  }
+  const machine = store.machine(flags.machine || s.machine);
+  if (!machine.online) throw new Error(`${machine.name} is offline · pick an online machine with --machine`);
+  let fork = Boolean(flags.fork);
+
+  if (!point && flags.pick && !flags.json) {
+    if (!interactive()) throw new Error('--pick needs a terminal · use --point <turn|backup>');
+    const latest = points[0];
+    line(`${c.i(c.b('?'))} Restore ${c.b(s.id)} to which point?   ${c.m(`${s.agent} · ${s.repo} · ${s.branch}`)}`);
+    line();
+    const cols = Math.min(size().cols, 140);
+    const res = await select({
+      count: points.length,
+      initial: Math.min(1, points.length - 1),
+      keys: { f: 'fork', d: 'diff' },
+      render: (idx) => {
+        const rows = [`     ${h(`${pad('POINT', 12)}${pad('WHEN', 14)}${pad('LAST PROMPT', 46)}${pad('FILES', 9)}BACKUP`)}`];
+        points.forEach((p, i) => {
+          const sel = i === idx;
+          const text = `${pad(`turn ${p.turn}`, 12)}${pad(p.created, 14)}${pad(p.prompt || p.label, 46)}${pad(String(p.files), 9)}${p.id}`;
+          rows.push(sel ? `  ${c.g('❯')} ${c.bg('sel')(c.b(text))}` : `     ${text}`);
+        });
+        const p = points[idx];
+        const dropped = latest.turn - p.turn;
+        const left = [
+          h(`Preview · turn ${p.turn}`),
+          `${c.s(pad('workspace', 11))}HEAD ${p.head} · ${p.files} file${p.files === 1 ? '' : 's'} changed`,
+          ...(p.diff || []).map((f) => `  ${pad(f.path, 26)}${c.g(pad(`+${f.add}`, 4))} ${c.r(`−${f.del}`)}`),
+          dropped > 0 ? `${c.s(pad('dropped', 11))}${dropped} later turns` : `${c.s(pad('dropped', 11))}nothing, this is the latest point`,
+          dropped > 0 ? `${' '.repeat(11)}${c.m(`kept safe in ${latest.id}, nothing is deleted`)}` : '',
+        ];
+        const right = [
+          h('Target'),
+          `${c.s(pad('machine', 11))}${machine.name} · ${machine.os}${machine.self ? ' · this machine' : ''}`,
+          `${c.s(pad('folder', 11))}~/work/${s.repo}${s.changed ? ` · ${c.w('has uncommitted changes')}` : ''}`,
+          `${c.s(pad('plan', 11))}${s.changed ? 'stash local changes as gitroots/pre-restore' : 'checkout, apply, resume'}`,
+          s.changed ? `${' '.repeat(11)}then checkout, apply, resume` : '',
+          `${c.s(pad('resume', 11))}${s.resume} · same conversation`,
+        ];
+        return `${rows.join('\n')}\n\n${panels(left, right, cols)}\n\n${c.m('↑↓ move   enter restore   f restore as a fork (keep ' + s.id + ' as is)   esc cancel')}`;
+      },
+    });
+    if (res.action === 'cancel') { line(c.m('  nothing restored')); return 1; }
+    if (res.action === 'fork') fork = true;
+    point = points[res.index];
+    line();
+  }
+  point = point || points[0];
+
+  if (flags.json) {
+    const r = apply(store, s, point, machine, fork);
+    json(r);
+    return 0;
+  }
+
+  const steps = [];
+  if (s.changed && s.turns !== point.turn && !fork) steps.push({ name: 'Stashed local changes', live: 'git stash push -m gitroots/pre-restore…', ms: 500, ok: 'gitroots/pre-restore' });
+  steps.push({ name: `Workspace at turn ${point.turn}`, live: `checkout ${point.head} · apply backup ${point.id}…`, ms: 900, ok: `HEAD ${point.head} · ${point.files} file${point.files === 1 ? '' : 's'}` });
+  steps.push({ name: 'Conversation', live: `rewinding to turn ${point.turn}…`, ms: 500, ok: `${point.turn} turns · later turns kept in ${points[0].id}` });
+  await runSteps(steps, { nameWidth: 28 });
+  const r = apply(store, s, point, machine, fork);
+  const ss = store.session(r.session);
+  line(`  ${c.g('✓')} ${c.b(`${fork ? 'Forked' : 'Restored'} ${r.session} on ${machine.name}`)}   ${sessionState(ss)} ${dot()} picks up from turn ${point.turn}   ${c.g(`→ gitroots attach ${r.session}`)}`);
+  if (fork) line(`    ${c.m(`${s.id} is unchanged`)}`);
+  return 0;
+}
+
+function apply(store, s, point, machine, fork) {
+  let target = s;
+  if (fork) {
+    target = { ...s, id: store.nextSessionId(), ask: undefined, forkedFrom: s.id };
+    store.d.sessions.push(target);
+  }
+  target.turns = point.turn;
+  target.head = point.head;
+  target.changed = point.files;
+  target.machine = machine.name;
+  target.state = 'running';
+  target.updated = 'just now';
+  if (!fork) target.ask = undefined;
+  const ev = store.record({ actor: store.org.user, action: fork ? 'fork' : 'restore', target: `${target.id} → turn ${point.turn} (${point.id})`, decision: 'allowed', note: machine.name, repo: s.repo });
+  store.save();
+  return { session: target.id, from: s.id, point: point.id, turn: point.turn, machine: machine.name, fork, event: ev.id };
+}
+
+export { next };

package/src/commands/splash.js

@@ -0,0 +1,95 @@
+// `gitroots` with no arguments: welcome and boot.
+import { c, pad } from '../ui/ansi.js';
+import { line, write, spinner, sleep, motion, logoImage } from '../ui/term.js';
+import { brand, dot, json } from '../ui/components.js';
+import { VERSION } from '../runtime.js';
+import { apiRepos } from '../connected.js';
+
+export function needsSummary(store) {
+  const items = store.needsYou();
+  const parts = [];
+  const reviews = items.filter((x) => x.kind === 'review');
+  const agents = items.filter((x) => x.kind === 'agent');
+  const blocked = items.filter((x) => x.kind === 'blocked');
+  for (const r of reviews) parts.push(`PR #${r.pr.number} review`);
+  for (const a of agents) parts.push(`${a.session.id} approval`);
+  if (blocked.length) parts.push(`${blocked.length} blocked push${blocked.length > 1 ? 'es' : ''}`);
+  return { count: items.length, text: parts.join(' · ') };
+}
+
+export default async function splash(store, args) {
+  const { org } = store;
+  const repos = store.repos();
+  const branchCount = repos.reduce((n, r) => n + r.branches, 0);
+  const providers = [...new Set(repos.map((r) => r.provider))].join(' · ');
+  const machines = store.machines().filter((m) => m.online);
+  const sessions = store.sessions();
+  const needs = needsSummary(store);
+
+  if (args.flags.json) {
+    json({ version: VERSION, org: org.name, user: org.user, role: org.role, relay: org.relay, repos: repos.length, branches: branchCount, machines: machines.length, sessions: sessions.length, needsYou: needs });
+    return 0;
+  }
+
+  const anim = motion();
+  line();
+  // Logo: the real image in Kitty, Ghostty, WezTerm and iTerm2; a plain gitroots line elsewhere.
+  const img = logoImage(26, 4);
+  const ver = `${c.s(`v${VERSION}`)}  ${dot()}  ${c.s('code governance and agent sessions')}`;
+  const tag = c.g('Secure it to the root, scale with confidence.');
+  if (img) {
+    write('\n\n\n\n\x1b[4A');
+    write(`\x1b7${img}\x1b8`);
+    const rows = ['', ver, tag, ''];
+    for (const r of rows) write(`\x1b[28C${c.m('│')}  ${r}\n`);
+  } else {
+    line(`${brand()}  ${c.m('│')}  ${ver}`);
+    line(`${' '.repeat(8)}  ${c.m('│')}  ${tag}`);
+  }
+  line();
+
+  const checks = [
+    { wait: 'Signing in…', ok: `Signed in as ${org.user}`, meta: `org ${org.name} ${dot()} ${org.role}` },
+    { wait: 'Checking repositories…', ok: `${repos.length} repos · ${branchCount} branches`, meta: `${providers} ${dot()} rules in sync` },
+    { wait: `Connecting agentd and relay ${org.relay.name}…`, ok: `${store.machines().length} machines · ${sessions.length} agent sessions`, meta: `relay ${org.relay.name} ${dot()} ${org.relay.latencyMs} ms` },
+  ];
+  if (store.api) {
+    // Signed in: the first two checks are real calls to the gitroots server.
+    checks[0].run = async () => {
+      const me = await store.api.me();
+      if (!me) throw new Error('user not found');
+      return { ok: `Signed in as ${me.username}`, meta: `org ${org.name} ${dot()} ${org.role} ${dot()} ${store.api.server.replace(/^https?:\/\//, '')}` };
+    };
+    checks[1].run = async () => {
+      const rs = await apiRepos(store);
+      return { ok: `${rs.length} repos · ${rs.reduce((n, r) => n + (r.branches || 0), 0)} branches`, meta: 'GitHub · from the gitroots API' };
+    };
+    checks[2].meta += ` ${dot()} sample sessions`;
+  }
+  for (const ch of checks) {
+    const sp = spinner((f) => `${c.i(f)} ${c.s(ch.wait)}`);
+    const t0 = Date.now();
+    let r = {};
+    try { if (ch.run) r = await ch.run(); } catch (e) { sp.stop(`${c.r('✕')} ${e.message}`); continue; }
+    if (anim && Date.now() - t0 < 700) await sleep(700 - (Date.now() - t0));
+    sp.stop(`${c.g('✓')} ${r.ok || ch.ok}  ${c.m(r.meta || ch.meta)}`);
+  }
+  line();
+  line(c.m('QUICK START'));
+  const qs = [
+    ['repos', `${c.g('gitroots repo list')} ${dot()} ${c.g('branch list erp')} ${dot()} ${c.g('clone erp')}`, 'repositories and branch rules'],
+    ['push', c.g('git push'), 'gitroots checks every push before it leaves'],
+    ['review', `${c.g('gitroots pr list')} ${dot()} ${c.g('pr view 412')} ${dot()} ${c.g('pr approve')} ${dot()} ${c.g('pr merge')}`, 'reviews and merges'],
+    ['audit', `${c.g('gitroots audit')} ${dot()} ${c.g('audit follow')}`, 'who did what, when, and what was blocked'],
+    ['agents', `${c.g('gitroots watch')} ${dot()} ${c.g('attach')} ${dot()} ${c.g('transfer')} ${dot()} ${c.g('backup')} ${dot()} ${c.g('tunnel')}`, 'every agent session, one place'],
+  ];
+  for (const [k, cmds, what] of qs) line(`  ${c.s(pad(k, 8))}  ${pad(cmds, 55)}  ${c.m(what)}`);
+  line();
+  if (needs.count) {
+    line(`${c.w(`◐ ${needs.count} thing${needs.count > 1 ? 's' : ''} need${needs.count > 1 ? '' : 's'} you`)}   ${c.m(needs.text)}   ${c.g('→ gitroots status')}`);
+  } else {
+    line(`${c.g('✓ nothing needs you')}   ${c.g('→ gitroots watch')}`);
+  }
+  if (store.mode === 'demo') line(c.m(`  sample data · gitroots login connects your gitroots server · gitroots demo reset starts over`));
+  return 0;
+}