gitroots 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# gitroots CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+gitroots in your terminal, as a session like Claude Code. Run `gitroots` and you get a welcome box with the gitroots mark and what needs you right now. Type `/` to pick a command from the list, use ↑↓ and Enter, and everything works on your real workspace.
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ██ ██ ██ ██   gitroots v0.6.0                                │
+│ ██ ██ ██ ██   code governance and agent sessions             │
+│ ██ ██ ██ ██   Shawki Aladdin · Acme ERP (owner) · gitroots.com│
+│ ██ ██ ██ ██   ~/work/erp · acme/erp @ main                   │
+╰──────────────────────────────────────────────────────────────╯
+  ◐ 1 approval waiting  ·  ◐ 1 agent needs you   → /approvals
+
+╭──────────────────────────────────────────────────────────────╮
+│ > /ap                                                        │
+╰──────────────────────────────────────────────────────────────╯
+ ❯ /approvals      Review merge and access requests · approve or decline
+   /attach         Open one session live · approve, message, stop, resume
+```
+
+## Install
+
+**macOS / Linux**: standalone binary, no Node needed:
+```bash
+curl -fsSL https://gitroots.com/cli/install.sh | bash
+```
+**Windows** (PowerShell):
+```powershell
+irm https://gitroots.com/cli/install.ps1 | iex
+```
+**npm** (any OS with Node 18+):
+```bash
+npm install -g gitroots
+```
+**Homebrew** (after publishing `dist/Formula/gitroots.rb` to a tap):
+```bash
+brew install <you>/tap/gitroots
+```
+
+Then run `gitroots`, `gitroots login` and `gitroots doctor`. `gitroots update` updates the same way it was installed (native binary or npm), and `gitroots uninstall` removes a native install.
+
+The native installer works like Claude Code's:
+- binaries go to `~/.local/share/gitroots/versions/<version>/`
+- `~/.local/bin/gitroots` links to the current one
+- every download is checked against `SHA256SUMS`
+- the current and previous versions are kept
+- `~/.local/bin` is added to your shell profile (skip with `GITROOTS_NO_MODIFY_PATH=1`)
+
+Pin a version with `… | bash -s -- 0.5.0`. On a platform without a binary (for example Alpine/musl), the installer falls back to the npm package if Node 18+ is present.
+
+From a checkout: `npm link`.
+
+## Releasing
+
+1. Bump `version` in `package.json` and `VERSION` in `src/runtime.js`. The build refuses to run if they differ.
+2. Build and publish:
+   ```bash
+   npm test
+   npm run build      # binaries for all platforms, installers, checksums → dist/
+   npm run deploy     # uploads to the gitroots-cli Railway service; https://gitroots.com/cli serves it
+   npm publish        # npm asks you to approve with your passkey in the browser
+   ```
+
+How it's hosted:
+- https://gitroots.com/cli is the install page, in the Django app on `railway-main` (`apps/core/cli_downloads.py`, `templates/landing/cli.html`).
+- Every file under `/cli/` redirects to the `gitroots-cli` service in the GITROOTS Railway project (production). Its server is in `deploy/downloads/`. The redirect target can be changed with `GITROOTS_CLI_DOWNLOADS_URL`.
+- Railway caps uploads at a few hundred MB, so `npm run deploy` uploads only the current release's binaries. Older versions stay installable from npm with `npm install -g gitroots@<version>`.
+
+Notes:
+- The binaries are Node 22 LTS single-executable apps, about 35–42 MB compressed each. macOS builds are ad-hoc signed. Sign and notarize them with a Developer ID if you distribute outside the curl installer.
+- The Homebrew formula is written to `dist/Formula/gitroots.rb`. Publish it in a tap repo to enable `brew install`.
+
+## Commands
+
+Inside the session, type `/` to see and pick them. Outside it, each one also runs on its own (`gitroots status`, `gitroots repos --json`) for scripts and CI.
+
+| | |
+|---|---|
+| `/status` | What needs you, workspace posture, agents |
+| `/approvals` | Merge and access requests: pick one, then approve, request changes or decline |
+| `/repos` · `/repo [name]` | Repositories, their branch rules, environments and people |
+| `/pushes [--blocked]` | Recent pushes and the ones gitroots blocked |
+| `/audit [blocked\|merges\|access] [search]` | Who did what, when |
+| `/activity` · `/members` | Team activity, people and roles |
+| `/agents` | Agent sessions on your machines (as the gitroots app reports them) and on this computer (Claude Code, Codex): approve, deny, message, stop, or resume a local one |
+| `/watch` · `/attach` | Full-screen live view of agent sessions (`y` approve, `n` deny, `m` message, `s` stop, `r` resume) |
+| `/machines` | Machines the gitroots app manages |
+| `/hooks [install]` · `/check` | Push checks for the repository you're in |
+| `/login` · `/logout` · `/whoami` · `/workspace` | Account and workspace |
+| `/doctor` · `/update` · `/help` · `/clear` · `/exit` | |
+
+Keys: `/` opens the list (type to filter, ↑↓ choose, Tab completes, Enter runs) · ↑↓ history · Esc clears · ctrl-c cancels a running command, twice to exit.
+
+## Where the data comes from
+
+All of it is real: nothing is sample data.
+
+- **Sign-in:** `/login` shows a code and opens gitroots.com/cli/auth. Approve it there while you're signed in, and the CLI receives your API token, which it keeps in the macOS Keychain (or `~/.gitroots/credentials.json`, mode 600). It works for GitHub-login accounts too.
+- **Workspace:** status, approvals, repositories, branch rules, pushes, audit, activity and members come from the gitroots API (`/api/mobile/gov/…`), the same endpoints the mobile app uses.
+- **Agents:**
+  - Your machines: from what the gitroots app reports (`/api/cli/agents`). Approve, deny, message and stop are queued through gitroots, and the app on that machine runs them.
+  - This computer: read from Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) session files. "Resume here" runs `claude --resume <id>` or `codex resume <id>` in the session's folder, and you come back to gitroots when it exits.
+- **Push checks:** `gitroots hooks install` adds a `pre-push` hook. It uses your workspace's branch rules for the GitHub repo you push to: no direct push, leads only, required approvals. The rules are cached so the hook works offline. Repos outside gitroots can use a `.gitroots.json`:
+  ```json
+  { "protected": ["main", "release/*"], "paths": [{ "pattern": "infra/**", "needs": "an ops review" }] }
+  ```
+  Every push also gets a secrets scan, an author check and migration flags. A blocked push never leaves the machine.
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `GITROOTS_HOME` | where state, config and credentials live (default `~/.gitroots`) |
+| `GITROOTS_SERVER` | gitroots server (default `https://gitroots.com`) |
+| `GITROOTS_TOKEN` | use this API token instead of the stored sign-in (CI) |
+| `GITROOTS_DOWNLOAD_BASE` | where `update` and the installers fetch releases |
+| `GITROOTS_NO_KEYCHAIN` | store the password in credentials.json even on macOS |
+| `NO_COLOR` / `FORCE_COLOR` | turn colors off or force them on |
+| `GITROOTS_REDUCED_MOTION` | no spinners or animation |
+| `GITROOTS_NO_IMAGES` | no inline logo image |
+| `GITROOTS_DEBUG` | print stack traces |
+
+## Layout
+
+```
+bin/gitroots.js        entry
+src/cli.js             one-shot commands and plumbing (hook, completion, uninstall)
+src/session/           the session: repl.js (input, / menu, history), logo.js, registry.js (every command),
+                       workspace.js, agents.js (incl. /watch and /attach), account.js, setup.js
+src/api.js             gitroots API client (token auth)
+src/config.js          settings, Keychain/credentials, caches
+src/agents/local.js    Claude Code and Codex sessions on this computer
+src/rules.js           branch rules for the push hook
+src/commands/push.js   the pre-push hook and checks · update.js · completion.js
+src/git/checks.js      secrets scan, authors, migrations
+scripts/               build.mjs (release), deploy.sh, install.sh, install.ps1
+test/                  node --test (includes a mock gitroots API and real git pushes)
+```

package/bin/gitroots.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+// `gitroots status | head` closes the pipe early: stop quietly instead of crashing.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (err) => {
+    if (err && err.code === 'EPIPE') process.exit(0);
+    throw err;
+  });
+}
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code ?? 0; },
+  (err) => {
+    process.stderr.write(`gitroots: ${err && err.message ? err.message : err}\n`);
+    if (process.env.GITROOTS_DEBUG) process.stderr.write(`${err.stack}\n`);
+    process.exitCode = 1;
+  }
+);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "gitroots",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "gitroots CLI: code governance and agent sessions.",
+  "type": "module",
+  "bin": {
+    "gitroots": "bin/gitroots.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "build": "node scripts/build.mjs",
+    "build:npm": "node scripts/build.mjs --no-binaries",
+    "deploy": "bash scripts/deploy.sh",
+    "prepublishOnly": "node --test test/"
+  },
+  "keywords": [
+    "gitroots",
+    "git",
+    "governance",
+    "code-review",
+    "agents",
+    "cli"
+  ],
+  "homepage": "https://gitroots.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/src/agents/local.js

@@ -0,0 +1,219 @@
+// Agent sessions on this machine, read from the agents' own session files.
+//   Claude Code   ~/.claude/projects/<folder>/<session-id>.jsonl     resume: claude --resume <id>
+//   Codex         ~/.codex/sessions/YYYY/MM/DD/rollout-…-<id>.jsonl  resume: codex resume <id>
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const TAIL = 192 * 1024;
+const LIVE_MS = 2 * 60 * 1000;
+const RECENT_MS = 14 * 24 * 3600 * 1000;
+
+function readSlice(file, start, length) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(length);
+    const n = fs.readSync(fd, buf, 0, length, start);
+    return buf.subarray(0, n).toString('utf8');
+  } finally { fs.closeSync(fd); }
+}
+
+// Walk the start of a file line by line, 128 KB at a time, until visit() returns true (max 2 MB).
+function scanHead(file, size, visit) {
+  const CHUNK = 128 * 1024;
+  let pos = 0;
+  let carry = '';
+  while (pos < Math.min(size, 2 * 1024 * 1024)) {
+    const text = carry + readSlice(file, pos, CHUNK);
+    pos += CHUNK;
+    const lines = text.split('\n');
+    carry = pos < size ? lines.pop() : '';
+    for (const l of lines) {
+      if (!l.trim()) continue;
+      let d;
+      try { d = JSON.parse(l); } catch { continue; }
+      if (visit(d)) return;
+    }
+  }
+}
+
+function jsonLines(text, dropFirst) {
+  const lines = text.split('\n');
+  if (dropFirst) lines.shift();
+  const out = [];
+  for (const l of lines) { if (!l.trim()) continue; try { out.push(JSON.parse(l)); } catch { /* partial line */ } }
+  return out;
+}
+
+function textOf(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.map((c) => (c && (c.type === 'text' || c.type === 'input_text' || c.type === 'output_text') ? c.text : '')).filter(Boolean).join(' ');
+}
+
+const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+const isNoise = (t) => !t || t.startsWith('<') || t.startsWith('Caveat:') || /^\[Request interrupted/.test(t);
+
+function state(mtime) {
+  const age = Date.now() - mtime;
+  return age < LIVE_MS ? 'live' : 'idle';
+}
+
+// ---------------------------------------------------------------- Claude Code
+
+function claudeSession(file, st) {
+  const size = st.size;
+  const tail = jsonLines(readSlice(file, Math.max(0, size - TAIL), Math.min(size, TAIL)), size > TAIL);
+  let title = '';
+  let cwd = '';
+  let branch = '';
+  let id = path.basename(file, '.jsonl');
+  scanHead(file, size, (d) => {
+    if (d.cwd && !cwd) cwd = d.cwd;
+    if (d.sessionId) id = d.sessionId;
+    if (d.type === 'summary' && d.summary && !title) title = d.summary;
+    if (!title && d.type === 'user' && d.message && d.message.role === 'user') {
+      const t = clean(textOf(d.message.content));
+      if (!isNoise(t)) title = t;
+    }
+    return Boolean(title && cwd);
+  });
+  const log = [];
+  let lastUser = '';
+  for (const d of tail) {
+    if (d.cwd) cwd = d.cwd;
+    if (d.gitBranch) branch = d.gitBranch;
+    const m = d.message;
+    if (!m) continue;
+    if (d.type === 'user' && m.role === 'user') {
+      const t = clean(textOf(m.content));
+      if (!isNoise(t)) { lastUser = t; log.push({ who: 'you', text: t, at: d.timestamp }); }
+    } else if (d.type === 'assistant' && Array.isArray(m.content)) {
+      for (const c of m.content) {
+        if (c.type === 'text' && clean(c.text)) log.push({ who: 'agent', text: clean(c.text), at: d.timestamp });
+        if (c.type === 'tool_use') log.push({ who: 'tool', text: `${c.name}${c.input && (c.input.command || c.input.file_path || c.input.pattern) ? ` ${clean(c.input.command || c.input.file_path || c.input.pattern)}` : ''}`, at: d.timestamp });
+      }
+    }
+  }
+  if (!cwd) return null;
+  return {
+    source: 'local', agent: 'claude', agentName: 'Claude Code', id, file, cwd, branch: branch === 'HEAD' ? '' : branch,
+    title: title || lastUser || '(no prompt yet)', lastPrompt: lastUser, mtime: st.mtimeMs, status: state(st.mtimeMs),
+    log: log.slice(-60), resume: { cmd: 'claude', args: ['--resume', id] },
+  };
+}
+
+function findClaude(root) {
+  const out = [];
+  let dirs = [];
+  try { dirs = fs.readdirSync(root); } catch { return out; }
+  for (const d of dirs) {
+    let files = [];
+    try { files = fs.readdirSync(path.join(root, d)); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.jsonl')) continue;
+      const p = path.join(root, d, f);
+      try { const st = fs.statSync(p); if (Date.now() - st.mtimeMs < RECENT_MS && st.size > 0) out.push([p, st]); } catch { /* gone */ }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- Codex
+
+function codexSession(file, st) {
+  const size = st.size;
+  const tail = jsonLines(readSlice(file, Math.max(0, size - TAIL), Math.min(size, TAIL)), size > TAIL);
+  let id = (/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/.exec(file) || [])[1] || path.basename(file);
+  let cwd = '';
+  let title = '';
+  let branch = '';
+  scanHead(file, size, (d) => {
+    const p = d.payload || {};
+    if (d.type === 'session_meta') { id = p.id || id; cwd = p.cwd || cwd; if (p.git && p.git.branch) branch = p.git.branch; }
+    if (!title && d.type === 'response_item' && p.type === 'message' && p.role === 'user') {
+      const t = clean(textOf(p.content));
+      if (!isNoise(t)) title = t;
+    }
+    return Boolean(title && cwd);
+  });
+  const log = [];
+  let lastUser = '';
+  for (const d of tail) {
+    const p = d.payload || {};
+    if (d.type === 'turn_context' && p.cwd) cwd = p.cwd;
+    if (d.type !== 'response_item') continue;
+    if (p.type === 'message' && (p.role === 'user' || p.role === 'assistant')) {
+      const t = clean(textOf(p.content));
+      if (isNoise(t)) continue;
+      if (p.role === 'user') lastUser = t;
+      log.push({ who: p.role === 'user' ? 'you' : 'agent', text: t, at: d.timestamp });
+    } else if (p.type === 'function_call' || p.type === 'local_shell_call' || p.type === 'custom_tool_call') {
+      let args = '';
+      try { const a = JSON.parse(p.arguments || '{}'); args = Array.isArray(a.command) ? a.command.join(' ') : a.command || a.cmd || ''; } catch { args = ''; }
+      log.push({ who: 'tool', text: `${p.name || 'shell'}${args ? ` ${clean(args)}` : ''}`, at: d.timestamp });
+    }
+  }
+  if (!cwd) return null;
+  return {
+    source: 'local', agent: 'codex', agentName: 'Codex', id, file, cwd, branch,
+    title: title || lastUser || '(no prompt yet)', lastPrompt: lastUser, mtime: st.mtimeMs, status: state(st.mtimeMs),
+    log: log.slice(-60), resume: { cmd: 'codex', args: ['resume', id] },
+  };
+}
+
+function findCodex(root) {
+  const out = [];
+  const walk = (dir, depth) => {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory() && depth < 3) walk(p, depth + 1);
+      else if (e.isFile() && e.name.endsWith('.jsonl')) {
+        try { const st = fs.statSync(p); if (Date.now() - st.mtimeMs < RECENT_MS && st.size > 0) out.push([p, st]); } catch { /* gone */ }
+      }
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+// ---------------------------------------------------------------- public
+
+export function localSessions({ limit = 40, homeDir = os.homedir() } = {}) {
+  const claudeRoot = process.env.CLAUDE_CONFIG_DIR ? path.join(process.env.CLAUDE_CONFIG_DIR, 'projects') : path.join(homeDir, '.claude', 'projects');
+  const codexRoot = path.join(process.env.CODEX_HOME || path.join(homeDir, '.codex'), 'sessions');
+  const files = [
+    ...findClaude(claudeRoot).map(([p, st]) => ['claude', p, st]),
+    ...findCodex(codexRoot).map(([p, st]) => ['codex', p, st]),
+  ].sort((a, b) => b[2].mtimeMs - a[2].mtimeMs).slice(0, limit);
+  const out = [];
+  for (const [kind, p, st] of files) {
+    try {
+      const s = kind === 'claude' ? claudeSession(p, st) : codexSession(p, st);
+      if (s) out.push(s);
+    } catch { /* unreadable */ }
+  }
+  return out;
+}
+
+export function refreshLocal(s) {
+  try {
+    const st = fs.statSync(s.file);
+    return s.agent === 'claude' ? claudeSession(s.file, st) : codexSession(s.file, st);
+  } catch { return s; }
+}
+
+export function shortPath(p) {
+  const h = os.homedir();
+  return p && p.startsWith(h) ? `~${p.slice(h.length)}` : p || '';
+}
+
+export function ago(ms) {
+  const s = Math.max(0, Math.round((Date.now() - ms) / 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`;
+}

package/src/api.js

@@ -0,0 +1,84 @@
+// gitroots API client. Uses the same token as the gitroots mobile app.
+import { DEFAULT_SERVER, readConfig, loadToken } from './config.js';
+
+export class ApiError extends Error {
+  constructor(message, status, body) { super(message); this.status = status; this.body = body; }
+}
+
+export class Api {
+  constructor({ server = DEFAULT_SERVER, token = null, orgId = null } = {}) {
+    this.server = server.replace(/\/+$/, '');
+    this.token = token;
+    this.orgId = orgId;
+  }
+
+  static fromConfig() {
+    const cfg = readConfig();
+    const server = process.env.GITROOTS_SERVER || cfg.server || DEFAULT_SERVER;
+    const token = loadToken(server, cfg.username);
+    return new Api({ server, token, orgId: cfg.org?.id ?? null });
+  }
+
+  get signedIn() { return Boolean(this.token); }
+  get host() { return this.server.replace(/^https?:\/\//, ''); }
+
+  async request(method, p, { query = {}, body, signal, auth = true, timeout = 20000, okStatuses = [] } = {}) {
+    const url = new URL(`${this.server}/api/${p.replace(/^\/+/, '')}`);
+    for (const [k, v] of Object.entries(query)) if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, v);
+    const headers = { Accept: 'application/json', 'User-Agent': 'gitroots-cli' };
+    if (auth) {
+      if (!this.token) throw new ApiError('not signed in · /login', 401);
+      headers.Authorization = `Token ${this.token}`;
+    }
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    const signals = [AbortSignal.timeout(timeout)];
+    if (signal) signals.push(signal);
+    let res;
+    try {
+      res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.any ? AbortSignal.any(signals) : signals[0] });
+    } catch (e) {
+      if (signal?.aborted) throw new ApiError('cancelled', 0);
+      throw new ApiError(`can't reach ${this.host} (${e.cause?.code || e.name})`, 0);
+    }
+    let data = null;
+    const ct = res.headers.get('content-type') || '';
+    if (ct.includes('json')) { try { data = await res.json(); } catch { data = null; } }
+    if (res.ok || okStatuses.includes(res.status)) return { status: res.status, data };
+    const detail = (data && (data.detail || data.error)) || '';
+    if (res.status === 401) throw new ApiError('your sign-in expired or was revoked · /login', 401, data);
+    if (res.status === 403) throw new ApiError(detail || 'not allowed for your role in this workspace', 403, data);
+    if (res.status === 404) throw new ApiError(detail || `not found (${url.pathname})`, 404, data);
+    if (!ct.includes('json')) throw new ApiError(`${this.host} answered ${res.status} · is it a gitroots server?`, res.status);
+    throw new ApiError(detail || `${res.status} from ${url.pathname}`, res.status, data);
+  }
+
+  async get(p, query, opts = {}) { return (await this.request('GET', p, { ...opts, query: { org_id: this.orgId, ...query } })).data; }
+  async post(p, body, opts = {}) { return (await this.request('POST', p, { ...opts, body, query: { org_id: this.orgId, ...(opts.query || {}) } })).data; }
+
+  // ---- sign-in (no token yet)
+  authStart(clientName) { return this.request('POST', 'cli/auth/start', { auth: false, body: { client_name: clientName } }).then((r) => r.data); }
+  authPoll(deviceCode, signal) {
+    return this.request('POST', 'cli/auth/poll', { auth: false, body: { device_code: deviceCode }, signal, okStatuses: [202, 403, 404, 410] });
+  }
+
+  // ---- account & workspace
+  me(opts) { return this.get('mobile/me', {}, opts); }
+
+  // ---- governance
+  home(opts) { return this.get('mobile/gov/home', {}, opts); }
+  repos(opts) { return this.get('mobile/gov/repos', {}, opts); }
+  repo(fullName, opts) { return this.get('mobile/gov/repos/detail', { repo: fullName }, opts); }
+  approvals(state = 'waiting', opts) { return this.get('mobile/gov/approvals', { state }, opts); }
+  approveSync(id, note, opts) { return this.request('POST', `provision/sync-requests/${id}/approve/`, { ...opts, body: { note: note || '' } }).then((r) => r.data); }
+  declineSync(id, mode, reason, opts) { return this.post(`mobile/gov/sync-requests/${id}/decline`, { mode, reason }, opts); }
+  decideAccess(id, decision, reason, opts) { return this.post(`mobile/gov/access-requests/${id}/decide`, { decision, reason }, opts); }
+  pushEvents(blocked, opts) { return this.get('mobile/gov/push-events', { blocked: blocked ? 1 : undefined }, opts); }
+  audit(category, q, opts) { return this.get('mobile/gov/audit', { category, q }, opts); }
+  teamActivity(opts) { return this.get('mobile/gov/team-activity', {}, opts); }
+  members(opts) { return this.get('mobile/gov/members', {}, opts); }
+
+  // ---- agents
+  agents(opts) { return this.get('cli/agents', {}, opts); }
+  agentSession(id, opts) { return this.get(`cli/agents/sessions/${id}`, {}, opts); }
+  agentAction(id, action, text, opts) { return this.post(`cli/agents/sessions/${id}/action`, { action, text }, opts); }
+}

package/src/cli.js

@@ -0,0 +1,76 @@
+import { setColor, c } from './ui/ansi.js';
+import { line, interactive } from './ui/term.js';
+import { VERSION } from './runtime.js';
+
+export { VERSION };
+
+// Flags that never take a value.
+const BOOL = new Set(['json', 'help', 'h', 'version', 'v', 'no-color', 'yes', 'y', 'force', 'blocked', 'purge', 'no-browser']);
+
+export function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { args._.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > -1) { args.flags[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+      const key = a.slice(2);
+      const nxt = argv[i + 1];
+      if (!BOOL.has(key) && nxt !== undefined && !nxt.startsWith('-')) { args.flags[key] = nxt; i++; } else args.flags[key] = true;
+      continue;
+    }
+    if (a.startsWith('-') && a.length > 1 && !/^-\d/.test(a)) {
+      const key = a.slice(1);
+      const nxt = argv[i + 1];
+      if (!BOOL.has(key) && key.length === 1 && nxt !== undefined && !nxt.startsWith('-')) { args.flags[key] = nxt; i++; } else args.flags[key] = true;
+      continue;
+    }
+    args._.push(a);
+  }
+  return args;
+}
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.flags['no-color'] || args.flags.json) setColor(false);
+  if (args.flags.version || args.flags.v) { line(`gitroots ${VERSION}`); return 0; }
+  const [name, ...rest] = args._;
+
+  // Hidden plumbing
+  if (name === 'hook') {
+    const fs = await import('node:fs');
+    const { prePush } = await import('./commands/push.js');
+    if (rest[0] !== 'pre-push') throw new Error(`unknown hook ${rest[0]}`);
+    let input = '';
+    try { input = fs.readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+    return prePush({ remote: rest[1], url: rest[2], input });
+  }
+  if (name === 'completion') return (await import('./commands/completion.js')).run(rest, args.flags);
+  if (name === 'uninstall') return (await import('./commands/update.js')).run('uninstall', rest, args.flags);
+  if (name === 'version') { line(`gitroots ${VERSION}`); return 0; }
+
+  const { find, suggest } = await import('./session/registry.js');
+  const { makeCtx, printHelp, startSession } = await import('./session/repl.js');
+
+  if (!name) {
+    if (args.flags.help || args.flags.h || !interactive()) { printHelp(false); return 0; }
+    return startSession();
+  }
+  if (name === 'help' || args.flags.help || args.flags.h) { printHelp(false); return 0; }
+
+  const cmd = find(name);
+  if (!cmd || cmd.session || !cmd.run) {
+    const near = suggest(name);
+    line(`${c.r('✕')} unknown command ${c.b(name)}${near.length ? `  ${c.m('did you mean')} ${near.map((x) => c.g(x.name)).join(', ')}?` : ''}`);
+    line(`  ${c.m('gitroots help lists them all · gitroots on its own opens a session')}`);
+    return 2;
+  }
+  const ctx = makeCtx({ session: false });
+  ctx.json = Boolean(args.flags.json);
+  const ac = new AbortController();
+  ctx.signal = ac.signal;
+  process.on('SIGINT', () => { ac.abort(); process.exit(130); });
+  const code = await cmd.run(ctx, rest, args.flags);
+  return code ?? 0;
+}

package/src/commands/completion.js

@@ -0,0 +1,46 @@
+// gitroots completion bash|zsh|fish
+import { COMMANDS } from '../session/registry.js';
+
+const SUBS = { hooks: ['install', 'uninstall'], approvals: ['waiting', 'approved', 'declined'], audit: ['blocked', 'merges', 'access', 'other'] };
+const FLAGS = '--json --help --no-color --blocked --force --server';
+
+export async function run(rest) {
+  const shell = rest[0] || (process.env.SHELL || '').split('/').pop();
+  const cmds = COMMANDS.filter((c) => !c.session).map((c) => c.name).join(' ');
+  const subs = Object.entries(SUBS);
+  if (shell === 'bash') {
+    process.stdout.write(`# gitroots bash completion · eval "$(gitroots completion bash)"
+_gitroots() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "${cmds}" -- "$cur") ); return; fi
+  case "$cur" in -*) COMPREPLY=( $(compgen -W "${FLAGS}" -- "$cur") ); return;; esac
+  case "\${COMP_WORDS[1]}" in
+${subs.map(([k, v]) => `    ${k}) COMPREPLY=( $(compgen -W "${v.join(' ')}" -- "$cur") );;`).join('\n')}
+  esac
+}
+complete -F _gitroots gitroots
+`);
+    return 0;
+  }
+  if (shell === 'zsh') {
+    process.stdout.write(`#compdef gitroots
+# gitroots zsh completion · gitroots completion zsh > "\${fpath[1]}/_gitroots"
+_gitroots() {
+  if (( CURRENT == 2 )); then compadd -- ${cmds}; return; fi
+  if [[ $words[CURRENT] == -* ]]; then compadd -- ${FLAGS}; return; fi
+  case $words[2] in
+${subs.map(([k, v]) => `    ${k}) compadd -- ${v.join(' ')};;`).join('\n')}
+  esac
+}
+compdef _gitroots gitroots
+`);
+    return 0;
+  }
+  if (shell === 'fish') {
+    const lines = ['# gitroots fish completion · gitroots completion fish > ~/.config/fish/completions/gitroots.fish', 'complete -c gitroots -f', `complete -c gitroots -n __fish_use_subcommand -a "${cmds}"`];
+    for (const [k, v] of subs) lines.push(`complete -c gitroots -n "__fish_seen_subcommand_from ${k}" -a "${v.join(' ')}"`);
+    process.stdout.write(`${lines.join('\n')}\n`);
+    return 0;
+  }
+  throw new Error('usage: gitroots completion bash|zsh|fish');
+}