gitroots 0.0.0-stage → 0.6.0

package/src/session/helpers.js

@@ -0,0 +1,71 @@
+// Shared bits for commands: loading spinners, hints, empty states, time.
+import { c, h, pad, fit, width } from '../ui/ansi.js';
+import { line, spinner, size } from '../ui/term.js';
+import { ApiError } from '../api.js';
+
+export { c, h, pad, fit, width, line };
+
+export function cols() { return Math.max(60, Math.min(size().cols, 160)); }
+
+// "/status" inside the session, "gitroots status" outside.
+export function cmdText(ctx, name, args = '') {
+  return ctx.session ? `/${name}${args ? ` ${args}` : ''}` : `gitroots ${name}${args ? ` ${args}` : ''}`;
+}
+
+export function next(ctx, name, args, alt) {
+  const tail = alt ? `   ${c.m('or')}  ${c.s(alt)}` : '';
+  line(`${c.g(`→ ${cmdText(ctx, name, args)}`)}${tail}`);
+}
+
+export function needSignIn(ctx) {
+  if (ctx.api.signedIn) return;
+  throw new ApiError(`not signed in · ${cmdText(ctx, 'login')} connects your gitroots account`, 401);
+}
+
+export function needWorkspace(ctx) {
+  needSignIn(ctx);
+  if (ctx.api.orgId === null || ctx.api.orgId === undefined) throw new ApiError(`no workspace chosen · ${cmdText(ctx, 'workspace')}`, 400);
+}
+
+/** Await work behind a one-line spinner. */
+export async function load(ctx, label, fn) {
+  if (ctx.json) return fn();
+  const sp = spinner((f) => `${c.i(f)} ${c.s(label)}`);
+  try { return await fn(); } finally { sp.stop(); }
+}
+
+export function ago(iso) {
+  if (!iso) return '';
+  const s = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+export function empty(text) { line(`  ${c.m(text)}`); }
+
+// A table that fits the terminal: the last column takes what's left.
+export function table(columns, rows) {
+  const total = cols() - 2;
+  const fixed = columns.slice(0, -1).reduce((n, col) => n + col.w, 0);
+  const lastW = Math.max(10, total - fixed);
+  line(`  ${h(columns.map((col, i) => (i === columns.length - 1 ? col.label : pad(col.label, col.w))).join(''))}`);
+  for (const r of rows) {
+    line(`  ${columns.map((col, i) => {
+      const v = col.fmt ? col.fmt(r) : String(r[col.key] ?? '');
+      return i === columns.length - 1 ? fit(v, lastW).trimEnd() : fit(v, col.w - 1) + ' ';
+    }).join('')}`);
+  }
+}
+
+export const STATUS_MARK = {
+  live: (w = 'live') => c.g(`● ${w}`),
+  waiting: (w = 'needs you') => c.w(`◐ ${w}`),
+  blocked: (w = 'blocked') => c.r(`✕ ${w}`),
+  idle: (w = 'idle') => c.s(`○ ${w}`),
+  done: (w = 'finished') => c.m(`✓ ${w}`),
+  stopped: (w = 'stopped') => c.m(`■ ${w}`),
+  failed: (w = 'failed') => c.r(`✕ ${w}`),
+};
+export function statusMark(s) { return (STATUS_MARK[s] || STATUS_MARK.idle)(); }

package/src/session/logo.js

@@ -0,0 +1,40 @@
+// The gitroots mark (4×4 green grid) drawn with block characters, so it shows in every terminal.
+import { state as colorState, c, width, fit } from '../ui/ansi.js';
+
+// Cell colors sampled from assets/logo.png, light lime (top left) to deep green (bottom right).
+const GRID = [
+  ['#B8DB4A', '#9CCF3A', '#5BB33A', '#22954E'],
+  ['#7DC035', '#63B535', '#258C35', '#0A743F'],
+  ['#1F8932', '#11713F', '#0A6435', '#0A4F33'],
+  ['#0A5835', '#0B4F27', '#0A3A27', '#0A3328'],
+];
+const FALLBACK = [[149, 112, 70, 29], [106, 70, 28, 23], [28, 23, 22, 22], [22, 22, 22, 22]];
+
+function cell(hex, r, col) {
+  if (!colorState.color) return '██';
+  const [R, G, B] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+  const code = colorState.truecolor ? `\x1b[38;2;${R};${G};${B}m` : `\x1b[38;5;${FALLBACK[r][col]}m`;
+  return `${code}██\x1b[39m`;
+}
+
+// Four rows, 11 columns: "██ ██ ██ ██"
+export function logoRows() {
+  return GRID.map((row, r) => row.map((hex, col) => cell(hex, r, col)).join(' '));
+}
+
+// Claude Code-style welcome box: logo on the left, lines of text on the right.
+export function welcomeBox(lines, cols) {
+  const inner = Math.max(40, Math.min(cols - 2, 100));
+  const logo = logoRows();
+  const rows = Math.max(logo.length, lines.length);
+  const out = [];
+  const b = (s) => c.g(s);
+  out.push(b(`╭${'─'.repeat(inner)}╮`));
+  for (let i = 0; i < rows; i++) {
+    const left = logo[i] || ' '.repeat(11);
+    const right = lines[i] || '';
+    out.push(`${b('│')} ${left}   ${fit(right, inner - 16)}${' '.repeat(Math.max(0, inner - 16 - width(fit(right, inner - 16))))} ${b('│')}`);
+  }
+  out.push(b(`╰${'─'.repeat(inner)}╯`));
+  return out;
+}

package/src/session/registry.js

@@ -0,0 +1,61 @@
+// Every command, used by the session's / picker and by one-shot `gitroots <command>`.
+import * as ws from './workspace.js';
+import * as ag from './agents.js';
+import * as acct from './account.js';
+import * as setup from './setup.js';
+
+export const COMMANDS = [
+  { name: 'status', group: 'Workspace', desc: 'What needs you, posture, agents', run: ws.status },
+  { name: 'approvals', group: 'Workspace', args: '[waiting|approved|declined]', desc: 'Review merge and access requests · approve or decline', run: ws.approvals },
+  { name: 'repos', group: 'Workspace', desc: 'Repositories in this workspace', run: ws.repos },
+  { name: 'repo', group: 'Workspace', args: '[name]', desc: 'One repository: branch rules, environments, people', run: ws.repo },
+  { name: 'pushes', group: 'Workspace', args: '[--blocked]', desc: 'Recent pushes and the ones that were blocked', run: ws.pushes },
+  { name: 'audit', group: 'Workspace', args: '[blocked|merges|access] [search]', desc: 'Who did what, when', run: ws.audit },
+  { name: 'activity', group: 'Workspace', desc: 'Team activity over the last 20 weeks', run: ws.activity },
+  { name: 'members', group: 'Workspace', desc: 'People in this workspace and their roles', run: ws.members },
+
+  { name: 'agents', group: 'Agents', desc: 'Agent sessions on your machines and this computer', run: ag.agents },
+  { name: 'watch', group: 'Agents', desc: 'Live dashboard of every agent session', run: ag.watch },
+  { name: 'attach', group: 'Agents', args: '[session]', desc: 'Open one session live · approve, message, stop, resume', run: ag.attach },
+  { name: 'machines', group: 'Agents', desc: 'Machines the gitroots app manages for you', run: ag.machines },
+
+  { name: 'hooks', group: 'This repository', args: '[install|uninstall]', desc: 'Push checks for this repository', run: setup.hooks },
+  { name: 'check', group: 'This repository', desc: 'Run the push checks on your local commits', run: setup.check },
+
+  { name: 'login', group: 'Account', desc: 'Sign in with your browser', run: acct.login },
+  { name: 'logout', group: 'Account', desc: 'Sign out on this computer', run: acct.logout },
+  { name: 'whoami', group: 'Account', aliases: ['account'], desc: 'Who you are signed in as', run: acct.whoami },
+  { name: 'workspace', group: 'Account', args: '[slug]', desc: 'Switch workspace', run: acct.workspace },
+
+  { name: 'doctor', group: 'gitroots', desc: 'Check the install, sign-in, git and hooks', run: setup.doctor },
+  { name: 'update', group: 'gitroots', desc: 'Update gitroots', run: async (ctx, args, flags) => (await import('../commands/update.js')).run('update', args, flags) },
+  { name: 'help', group: 'gitroots', desc: 'All commands and keys', run: null },
+  { name: 'clear', group: 'gitroots', session: true, desc: 'Clear the screen', run: null },
+  { name: 'exit', group: 'gitroots', session: true, aliases: ['quit'], desc: 'Leave gitroots', run: null },
+];
+
+export function find(name) {
+  const n = String(name || '').replace(/^\//, '').toLowerCase();
+  return COMMANDS.find((c) => c.name === n || (c.aliases || []).includes(n)) || null;
+}
+
+/** Commands for the / menu: prefix matches first, then names or descriptions containing the text. */
+export function match(query, { session = true } = {}) {
+  const q = query.toLowerCase();
+  const list = COMMANDS.filter((c) => session || !c.session);
+  if (!q) return list;
+  const starts = list.filter((c) => c.name.startsWith(q) || (c.aliases || []).some((a) => a.startsWith(q)));
+  const contains = list.filter((c) => !starts.includes(c) && (c.name.includes(q) || c.desc.toLowerCase().includes(q)));
+  return [...starts, ...contains];
+}
+
+export function suggest(word) {
+  const w = word.toLowerCase();
+  const dist = (a, b) => {
+    const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++) m[0][j] = j;
+    for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return m[a.length][b.length];
+  };
+  return COMMANDS.map((c) => [c, dist(w, c.name)]).filter(([, d]) => d <= 2).sort((a, b) => a[1] - b[1]).map(([c]) => c).slice(0, 3);
+}

package/src/session/repl.js

@@ -0,0 +1,332 @@
+// The gitroots session: run `gitroots`, get a welcome box and an input; type / to pick a command.
+import fs from 'node:fs';
+import { c, h, pad, fit, width } from '../ui/ansi.js';
+import { out, write, size, parseKeys } from '../ui/term.js';
+import { Api, ApiError } from '../api.js';
+import { readConfig, historyFile } from '../config.js';
+import { VERSION } from '../runtime.js';
+import { tryGit } from '../git/checks.js';
+import { localSessions, shortPath } from '../agents/local.js';
+import { remoteFullName } from '../rules.js';
+import { welcomeBox } from './logo.js';
+import { COMMANDS, find, match, suggest } from './registry.js';
+
+const MENU_ROWS = 8;
+
+export function makeCtx({ session }) {
+  const ctx = {
+    session,
+    json: false,
+    api: Api.fromConfig(),
+    signal: null,
+    reload() { ctx.api = Api.fromConfig(); },
+  };
+  return ctx;
+}
+
+// Split a line into words, keeping "quoted text" together.
+export function words(text) {
+  const outw = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(text))) outw.push(m[1] ?? m[2] ?? m[3]);
+  return outw;
+}
+
+function header(ctx) {
+  const cfg = readConfig();
+  const { cols } = size();
+  const top = tryGit(['rev-parse', '--show-toplevel']);
+  const branch = top ? tryGit(['rev-parse', '--abbrev-ref', 'HEAD']) : '';
+  const repo = top ? remoteFullName(tryGit(['remote', 'get-url', 'origin'])) || top.split('/').pop() : '';
+  const who = ctx.api.signedIn
+    ? `${c.b(cfg.user?.name || cfg.username)} ${c.m('·')} ${cfg.org ? `${cfg.org.name} ${c.m(`(${cfg.org.role})`)}` : c.w('no workspace · /workspace')} ${c.m(`· ${ctx.api.host}`)}`
+    : `${c.w('Not signed in')} ${c.m('· /login to connect your gitroots account')}`;
+  return welcomeBox([
+    `${c.b('gitroots')} ${c.m(`v${VERSION}`)}`,
+    c.m('code governance and agent sessions'),
+    who,
+    c.m(`${shortPath(process.cwd())}${repo ? ` · ${repo}${branch ? ` @ ${branch}` : ''}` : ''}`),
+  ], cols);
+}
+
+class Repl {
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.input = '';
+    this.pos = 0;
+    this.menuIdx = 0;
+    this.menuDismissed = false;
+    this.drawn = 0;
+    this.cursorRow = 0;
+    this.notice = null;
+    this.lastCtrlC = 0;
+    this.running = false;
+    this.history = [];
+    this.hIdx = -1;
+    this.draft = '';
+    try { this.history = fs.readFileSync(historyFile(), 'utf8').split('\n').filter(Boolean).slice(-300); } catch { /* none */ }
+    this.onData = (buf) => { for (const k of parseKeys(buf)) this.key(k); };
+    this.onResize = () => { if (!this.running) { this.drawn = 0; write('\r\x1b[J'); this.draw(); } };
+  }
+
+  menuItems() {
+    if (this.menuDismissed || !this.input.startsWith('/') || /\s/.test(this.input)) return null;
+    return match(this.input.slice(1));
+  }
+
+  render() {
+    const { cols } = size();
+    const W = Math.max(30, cols - 1);
+    const inner = W - 2;
+    const vis = inner - 4;
+    let shown = this.input;
+    let cur = this.pos;
+    if (width(shown) > vis - 1) {
+      const start = Math.max(0, this.pos - (vis - 1));
+      shown = shown.slice(start, start + vis - 1);
+      cur = this.pos - start;
+    }
+    const body = this.input ? shown : c.m('Type / for commands');
+    const lines = [
+      c.m(`╭${'─'.repeat(inner)}╮`),
+      `${c.m('│')} ${c.g('>')} ${fit(body, vis)} ${c.m('│')}`,
+      c.m(`╰${'─'.repeat(inner)}╯`),
+    ];
+    const items = this.menuItems();
+    if (items && items.length) {
+      this.menuIdx = Math.min(this.menuIdx, items.length - 1);
+      const start = Math.max(0, Math.min(this.menuIdx - MENU_ROWS + 1, items.length - MENU_ROWS));
+      for (let i = start; i < Math.min(items.length, start + MENU_ROWS); i++) {
+        const it = items[i];
+        const sel = i === this.menuIdx;
+        const name = `/${it.name}`;
+        const text = `${pad(sel ? c.g(c.b(name)) : name, 16)}${sel ? it.desc : c.s(it.desc)}${it.args ? c.m(`  ${it.args}`) : ''}`;
+        lines.push(fit(`${sel ? c.g(' ❯ ') : '   '}${text}`, W));
+      }
+      if (items.length > MENU_ROWS) lines.push(c.m(fit(`   ${items.length} commands · ↑↓ choose · tab complete · enter run · esc close`, W)));
+    } else if (items && !items.length) {
+      lines.push(c.m(fit(`   no command matches “${this.input.slice(1)}” · /help lists them all`, W)));
+    } else {
+      const cfg = readConfig();
+      const left = this.notice || c.m('  / commands · ↑↓ history · esc clear · ctrl-c twice to exit');
+      const right = this.ctx.api.signedIn && cfg.org ? c.m(`${cfg.org.name} `) : '';
+      lines.push(`${fit(left, Math.max(0, W - width(right)))}${right}`);
+    }
+    return { lines, cursorRow: 1, cursorCol: 4 + width(this.input ? shown.slice(0, cur) : '') };
+  }
+
+  draw() {
+    if (this.running) return;
+    const { lines, cursorRow, cursorCol } = this.render();
+    let s = '';
+    if (this.drawn) s += `${this.cursorRow ? `\x1b[${this.cursorRow}A` : ''}\r\x1b[J`;
+    s += lines.join('\n');
+    const up = lines.length - 1 - cursorRow;
+    if (up) s += `\x1b[${up}A`;
+    s += `\r${cursorCol ? `\x1b[${cursorCol}C` : ''}`;
+    write(s);
+    this.drawn = lines.length;
+    this.cursorRow = cursorRow;
+  }
+
+  clearPrompt() {
+    if (!this.drawn) return;
+    write(`${this.cursorRow ? `\x1b[${this.cursorRow}A` : ''}\r\x1b[J`);
+    this.drawn = 0;
+  }
+
+  // Print above the prompt, e.g. a background notice.
+  print(text) {
+    if (this.running) { write(`${text}\n`); return; }
+    this.clearPrompt();
+    write(`${text}\n`);
+    this.draw();
+  }
+
+  setInput(text) { this.input = text; this.pos = text.length; this.menuIdx = 0; this.menuDismissed = false; }
+
+  key(k) {
+    if (this.running) return;
+    this.notice = null;
+    const items = this.menuItems();
+    const n = k.name;
+    if (items && items.length) {
+      if (n === 'up') { this.menuIdx = (this.menuIdx - 1 + items.length) % items.length; return this.draw(); }
+      if (n === 'down') { this.menuIdx = (this.menuIdx + 1) % items.length; return this.draw(); }
+      if (n === 'tab') { const it = items[this.menuIdx]; this.setInput(`/${it.name}${it.args ? ' ' : ''}`); return this.draw(); }
+      if (n === 'enter') { this.setInput(`/${items[this.menuIdx].name}`); return this.submit(); }
+      if (n === 'escape') { this.menuDismissed = true; return this.draw(); }
+    }
+    switch (n) {
+      case 'enter': return this.submit();
+      case 'escape': this.setInput(''); break;
+      case 'tab': if (!this.input) this.setInput('/'); break;
+      case 'ctrl-c':
+        if (this.input) { this.setInput(''); break; }
+        if (Date.now() - this.lastCtrlC < 1500) return this.exit();
+        this.lastCtrlC = Date.now();
+        this.notice = c.w('  press ctrl-c again to exit');
+        break;
+      case 'ctrl-d': if (!this.input) return this.exit(); this.input = this.input.slice(0, this.pos) + this.input.slice(this.pos + 1); break;
+      case 'ctrl-l': write('\x1b[2J\x1b[H'); this.drawn = 0; write(`${header(this.ctx).join('\n')}\n\n`); break;
+      case 'left': this.pos = Math.max(0, this.pos - 1); break;
+      case 'right': this.pos = Math.min(this.input.length, this.pos + 1); break;
+      case 'home': case 'ctrl-a': this.pos = 0; break;
+      case 'end': case 'ctrl-e': this.pos = this.input.length; break;
+      case 'word-left': { const m = /\S*\s*$/.exec(this.input.slice(0, this.pos)); this.pos -= m ? m[0].length : 0; break; }
+      case 'word-right': { const m = /^\s*\S*/.exec(this.input.slice(this.pos)); this.pos += m ? m[0].length : 0; break; }
+      case 'backspace': if (this.pos) { this.input = this.input.slice(0, this.pos - 1) + this.input.slice(this.pos); this.pos--; this.menuDismissed = false; this.menuIdx = 0; } break;
+      case 'delete': this.input = this.input.slice(0, this.pos) + this.input.slice(this.pos + 1); break;
+      case 'ctrl-u': this.input = this.input.slice(this.pos); this.pos = 0; break;
+      case 'ctrl-k': this.input = this.input.slice(0, this.pos); break;
+      case 'ctrl-w': { const m = /\S*\s*$/.exec(this.input.slice(0, this.pos)); const cut = m ? m[0].length : 0; this.input = this.input.slice(0, this.pos - cut) + this.input.slice(this.pos); this.pos -= cut; break; }
+      case 'up':
+        if (!this.history.length) break;
+        if (this.hIdx === -1) { this.draft = this.input; this.hIdx = this.history.length; }
+        this.hIdx = Math.max(0, this.hIdx - 1);
+        this.input = this.history[this.hIdx]; this.pos = this.input.length; this.menuDismissed = true;
+        break;
+      case 'down':
+        if (this.hIdx === -1) break;
+        this.hIdx++;
+        if (this.hIdx >= this.history.length) { this.hIdx = -1; this.input = this.draft; } else this.input = this.history[this.hIdx];
+        this.pos = this.input.length; this.menuDismissed = true;
+        break;
+      default:
+        if (k.ch && !k.ctrl) {
+          this.input = this.input.slice(0, this.pos) + k.ch + this.input.slice(this.pos);
+          this.pos += k.ch.length;
+          this.menuDismissed = false;
+          this.menuIdx = 0;
+          this.hIdx = -1;
+        }
+    }
+    this.draw();
+  }
+
+  remember(lineText) {
+    if (this.history[this.history.length - 1] !== lineText) {
+      this.history.push(lineText);
+      try { fs.appendFileSync(historyFile(), `${lineText}\n`, { mode: 0o600 }); } catch { /* read-only */ }
+    }
+    this.hIdx = -1;
+  }
+
+  async submit() {
+    const text = this.input.trim();
+    this.clearPrompt();
+    this.setInput('');
+    if (!text) { this.draw(); return; }
+    this.remember(text);
+    write(`${c.m('>')} ${c.b(text)}\n`);
+    const [first, ...rest] = words(text);
+    const cmd = find(first);
+    if (!cmd) {
+      const near = suggest(first.replace(/^\//, ''));
+      write(`${c.r('✕')} ${first.startsWith('/') ? 'No command' : 'Not a command:'} ${c.b(first)}${near.length ? `  ${c.m('did you mean')} ${near.map((x) => c.g(`/${x.name}`)).join(c.m(', '))}${c.m('?')}` : ''}  ${c.m('· type / to pick one')}\n\n`);
+      this.draw();
+      return;
+    }
+    if (cmd.name === 'exit') return this.exit();
+    if (cmd.name === 'clear') { write('\x1b[2J\x1b[3J\x1b[H'); write(`${header(this.ctx).join('\n')}\n\n`); this.draw(); return; }
+    if (cmd.name === 'help') { printHelp(true); write('\n'); this.draw(); return; }
+    await this.run(cmd, rest);
+  }
+
+  async run(cmd, rest) {
+    const { parseArgs } = await import('../cli.js');
+    const parsed = parseArgs(rest);
+    this.running = true;
+    process.stdin.off('data', this.onData);
+    process.stdin.setRawMode(false);
+    const ac = new AbortController();
+    this.ctx.signal = ac.signal;
+    const onInt = () => ac.abort();
+    process.on('SIGINT', onInt);
+    try {
+      await cmd.run(this.ctx, parsed._, parsed.flags);
+    } catch (e) {
+      const msg = e instanceof ApiError || e instanceof Error ? e.message : String(e);
+      write(`${ac.signal.aborted ? c.m('○ cancelled') : `${c.r('✕')} ${msg}`}\n`);
+      if (process.env.GITROOTS_DEBUG && e && e.stack) write(`${e.stack}\n`);
+    } finally {
+      process.off('SIGINT', onInt);
+      this.ctx.signal = null;
+      this.running = false;
+      write('\n');
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.on('data', this.onData);
+      this.draw();
+    }
+  }
+
+  exit() {
+    this.clearPrompt();
+    write(`${c.m('bye ·')} ${c.g('gitroots')} ${c.m('to come back')}\n`);
+    process.stdin.setRawMode(false);
+    process.exit(0);
+  }
+
+  async greet() {
+    // What needs you, fetched after the prompt is up so the session opens instantly.
+    const ctx = this.ctx;
+    const local = localSessions({ limit: 40 });
+    const liveLocal = local.filter((s) => s.status === 'live').length;
+    const parts = [];
+    let hint = '';
+    if (ctx.api.signedIn && ctx.api.orgId != null) {
+      const [home, agents] = await Promise.all([
+        ctx.api.home({ timeout: 8000 }).catch((e) => ({ error: e.message })),
+        ctx.api.agents({ timeout: 8000 }).catch(() => null),
+      ]);
+      if (home.error) { this.print(`  ${c.w(`◐ couldn't reach gitroots: ${home.error}`)}\n`); return; }
+      if (home.pending_count) { parts.push(c.w(`◐ ${home.pending_count} approval${home.pending_count > 1 ? 's' : ''} waiting`)); hint = '/approvals'; }
+      const waiting = (agents?.sessions || []).filter((s) => s.needs_you).length;
+      if (waiting) { parts.push(c.w(`◐ ${waiting} agent${waiting > 1 ? 's' : ''} need${waiting > 1 ? '' : 's'} you`)); hint = hint || '/agents'; }
+      if (home.blocked_24h) { parts.push(c.r(`✕ ${home.blocked_24h} blocked push${home.blocked_24h > 1 ? 'es' : ''} today`)); hint = hint || '/pushes --blocked'; }
+      if (!parts.length) parts.push(c.g('✓ nothing waiting on you'));
+    }
+    if (liveLocal) parts.push(c.g(`● ${liveLocal} agent session${liveLocal > 1 ? 's' : ''} live on this computer`));
+    if (parts.length) this.print(`${fit(`  ${parts.join(c.m('  ·  '))}${hint ? `   ${c.g(`→ ${hint}`)}` : ''}`, size().cols - 1)}\n`);
+  }
+
+  start() {
+    write(`\n${header(this.ctx).join('\n')}\n`);
+    write(`  ${c.m('Type')} ${c.g('/')} ${c.m('to pick a command, or')} ${c.g('/help')} ${c.m('for all of them.')}${this.ctx.api.signedIn ? '' : `  ${c.m('Start with')} ${c.g('/login')}${c.m('.')}`}\n\n`);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', this.onData);
+    out.on('resize', this.onResize);
+    this.draw();
+    this.greet().catch(() => {});
+    return new Promise(() => {}); // runs until exit
+  }
+}
+
+export function printHelp(session) {
+  const p = session ? '/' : 'gitroots ';
+  const groups = [...new Set(COMMANDS.map((x) => x.group))];
+  for (const g of groups) {
+    write(`${h(g)}\n`);
+    for (const x of COMMANDS.filter((y) => y.group === g && (session || !y.session))) {
+      const left = c.g(`${p}${x.name}`) + (x.args ? ` ${c.m(x.args)}` : '');
+      write(`  ${width(left) >= 48 ? `${left}  ` : pad(left, 50)}${x.desc}\n`);
+    }
+    write('\n');
+  }
+  if (session) {
+    write(`${h('Keys')}\n`);
+    write(`  ${pad(c.g('/'), 14)}open the command list · type to filter · ↑↓ choose · tab complete · enter run\n`);
+    write(`  ${pad(c.g('↑ ↓'), 14)}history  ·  ${c.g('esc')} clear  ·  ${c.g('ctrl-l')} clear screen  ·  ${c.g('ctrl-c')} cancel a running command, twice to exit\n`);
+  } else {
+    write(`  ${c.m('Run gitroots with no command to open a session. --json on list commands.')}\n`);
+  }
+}
+
+export async function startSession() {
+  const ctx = makeCtx({ session: true });
+  const repl = new Repl(ctx);
+  return repl.start();
+}

package/src/session/setup.js

@@ -0,0 +1,101 @@
+// /hooks · /check · /doctor
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { json } from '../ui/components.js';
+import { state as colorState } from '../ui/ansi.js';
+import { motion } from '../ui/term.js';
+import { installHook, uninstallHook, hookStatus, checkLocal } from '../commands/push.js';
+import { loadRules } from '../rules.js';
+import { tryGit } from '../git/checks.js';
+import { VERSION, DOWNLOAD_BASE, installMethod, nativePaths, platformKey, isBinary } from '../runtime.js';
+import { latestVersion, newer, onPath } from '../installer.js';
+import { home, readConfig } from '../config.js';
+import { localSessions } from '../agents/local.js';
+import { c, line, pad, next, load, cmdText } from './helpers.js';
+
+export async function hooks(ctx, args, flags) {
+  const sub = args[0] || 'status';
+  if (sub === 'install') {
+    const r = installHook('.', { force: flags.force });
+    if (ctx.json) { json(r); return 0; }
+    line(`${c.g('✓')} Push checks installed in ${c.b(path.basename(tryGit(['rev-parse', '--show-toplevel'])))}${r.chained ? c.m(' · your previous hook still runs first') : ''}`);
+    line(`  ${c.m('every git push now checks branch rules, secrets, authors and migrations first')}`);
+    next(ctx, 'check');
+    return 0;
+  }
+  if (sub === 'uninstall') {
+    const r = uninstallHook('.');
+    if (ctx.json) { json(r); return 0; }
+    line(r.removed ? `${c.g('✓')} Push checks removed from this repository` : c.m('○ no gitroots hook in this repository'));
+    return 0;
+  }
+  const st = hookStatus('.');
+  if (!st.repo) throw new Error('not inside a git repository · cd into one first');
+  const set = await load(ctx, 'Reading branch rules…', () => loadRules(process.cwd(), { api: ctx.api }));
+  if (ctx.json) { json({ ...st, rules: set }); return 0; }
+  line(`${c.b(set.repo || path.basename(st.repo))}  ${st.installed ? c.g('● push checks on') : c.w('○ push checks off')}`);
+  const src = { gitroots: `from gitroots (${ctx.api.host})`, cache: 'from gitroots, cached', '.gitroots.json': 'from .gitroots.json', none: 'none for this repo' }[set.source];
+  line(`  ${c.s(pad('rules', 9))}${src}`);
+  for (const r of set.rules) line(`  ${' '.repeat(9)}${c.b(pad(r.pattern, 20))}${r.allow_direct_push === false ? c.r('✕ no direct push') : c.g('✓ direct push')}  ${c.m(r.description || r.level)}`);
+  if (!st.installed) next(ctx, 'hooks', 'install');
+  else next(ctx, 'check');
+  return 0;
+}
+
+export async function check(ctx, args, flags) {
+  return checkLocal(args, { api: ctx.api, branch: flags.branch });
+}
+
+export async function doctor(ctx) {
+  const rows = [];
+  const add = (group, name, status, detail, fix) => rows.push({ group, name, status, detail, fix });
+  add('install', 'gitroots', 'ok', `${VERSION} · ${installMethod()}${isBinary ? ` · ${process.execPath}` : ''}`);
+  add('install', 'platform', 'ok', platformKey());
+  if (!isBinary) {
+    const major = Number(process.versions.node.split('.')[0]);
+    add('install', 'node', major >= 18 ? 'ok' : 'fail', process.version, major >= 18 ? null : 'install Node 18+ or the standalone build');
+  }
+  if (installMethod() === 'native') {
+    const { bin } = nativePaths();
+    add('install', 'PATH', onPath(bin) ? 'ok' : 'warn', onPath(bin) ? `${bin} is on PATH` : `${bin} is not on PATH`, onPath(bin) ? null : `export PATH="${bin}:$PATH"`);
+  }
+  try {
+    const latest = await latestVersion(DOWNLOAD_BASE, 4000);
+    add('install', 'updates', newer(latest, VERSION) ? 'warn' : 'ok', newer(latest, VERSION) ? `${latest} is available` : 'up to date', newer(latest, VERSION) ? cmdText(ctx, 'update') : null);
+  } catch (e) { add('install', 'updates', 'warn', `couldn't check (${e.message})`); }
+
+  const cfg = readConfig();
+  if (ctx.api.signedIn) {
+    try {
+      const me = await ctx.api.me({ timeout: 6000 });
+      add('account', 'signed in', 'ok', `${me.user.username} · ${ctx.api.host}`);
+      add('account', 'workspace', cfg.org ? 'ok' : 'warn', cfg.org ? `${cfg.org.name} (${cfg.org.role})` : 'none chosen', cfg.org ? null : cmdText(ctx, 'workspace'));
+    } catch (e) { add('account', 'signed in', 'fail', e.message, cmdText(ctx, 'login')); }
+  } else add('account', 'signed in', 'warn', 'no', cmdText(ctx, 'login'));
+  try { fs.mkdirSync(home(), { recursive: true }); fs.accessSync(home(), fs.constants.W_OK); add('account', 'settings', 'ok', home()); } catch { add('account', 'settings', 'fail', `${home()} is not writable`); }
+
+  const git = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  add('git', 'git', git.status === 0 ? 'ok' : 'fail', git.status === 0 ? git.stdout.trim() : 'not found', git.status === 0 ? null : 'install git');
+  const st = hookStatus('.');
+  if (st.repo) add('git', 'push checks', st.installed ? 'ok' : 'warn', `${st.installed ? 'on' : 'off'} in ${path.basename(st.repo)}`, st.installed ? null : cmdText(ctx, 'hooks', 'install'));
+  else add('git', 'repository', 'ok', 'not inside a git repo (skipped)');
+
+  const local = localSessions({ limit: 200 });
+  add('agents', 'this computer', 'ok', `${local.filter((s) => s.agent === 'claude').length} Claude Code · ${local.filter((s) => s.agent === 'codex').length} Codex sessions in the last 14 days`);
+  add('terminal', 'colors', colorState.color ? 'ok' : 'warn', colorState.color ? (colorState.truecolor ? 'truecolor' : '256 colors') : 'off (piped or NO_COLOR)');
+  add('terminal', 'motion', 'ok', motion() ? 'on' : 'off');
+
+  if (ctx.json) { json(rows); return rows.some((r) => r.status === 'fail') ? 1 : 0; }
+  let group = '';
+  for (const r of rows) {
+    if (r.group !== group) { if (group) line(); line(c.m(r.group.toUpperCase())); group = r.group; }
+    const mark = r.status === 'ok' ? c.g('✓') : r.status === 'warn' ? c.w('◐') : c.r('✕');
+    line(`  ${mark} ${pad(r.name, 14)}${r.status === 'fail' ? c.r(r.detail) : r.status === 'warn' ? c.w(r.detail) : c.s(r.detail)}${r.fix ? `   ${c.g(`→ ${r.fix}`)}` : ''}`);
+  }
+  const fails = rows.filter((r) => r.status === 'fail').length;
+  const warns = rows.filter((r) => r.status === 'warn').length;
+  line();
+  line(fails ? c.r(`✕ ${fails} problem${fails > 1 ? 's' : ''}`) : warns ? c.w(`◐ ${warns} thing${warns > 1 ? 's' : ''} to look at`) : c.g('✓ all good'));
+  return fails ? 1 : 0;
+}