gitroots 0.0.0-stage → 0.5.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.
+Code governance and agent sessions in the terminal. Built from the **gitroots CLI Terminal** design canvas. Each artboard maps to one command, using the same colors, symbols and layout.
+
+## 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
+
+```bash
+npm test
+node scripts/build.mjs            # all platforms → dist/
+```
+`dist/` is the whole release. Upload it as-is to the download location: `https://gitroots.com/cli` by default, or any static host/bucket. To use another host, set `GITROOTS_DOWNLOAD_BASE` at build time (it goes into the Homebrew formula) and in `src/runtime.js` (`DOWNLOAD_BASE`, used by `update` and `doctor`).
+```
+dist/install.sh  dist/install.ps1  dist/latest
+dist/0.5.0/gitroots-0.5.0-{darwin-arm64,darwin-x64,linux-x64,linux-arm64}.tar.gz
+dist/0.5.0/gitroots-0.5.0-win32-x64.zip
+dist/0.5.0/gitroots-0.5.0.tgz  dist/0.5.0/SHA256SUMS  dist/0.5.0/manifest.json
+dist/Formula/gitroots.rb
+```
+- The binaries are Node 22 LTS single-executable apps, about 35–42 MB compressed. macOS builds are ad-hoc signed. For Gatekeeper-friendly distribution outside the curl installer, sign and notarize them with your Developer ID.
+- For npm, run `npm publish` from this folder (the name `gitroots` was free on npm when this was written).
+- For a new version, bump `version` in `package.json` and `VERSION` in `src/runtime.js`. The build refuses to run if they differ.
+
+## Commands
+
+| Design screen | Command |
+|---|---|
+| Welcome and boot | `gitroots` |
+| Status | `gitroots status` |
+| Repo · branch · clone | `gitroots repo list` · `branch list <repo> [--all]` · `branch rules <repo> <branch>` · `branch restore <repo> <branch>` · `clone <repo\|url> [--url <git-url>]` |
+| git push · gitroots checks | `gitroots hooks install` then a normal `git push` · `gitroots check` (dry run) |
+| PR list · view | `gitroots pr list [repo]` · `pr view <n>` · `pr diff <n>` |
+| PR create | `gitroots pr create [--base staging] [--head branch] [--title "…"] [--draft]` |
+| PR approve · merge | `gitroots pr approve <n> -m "…"` · `pr review <n> --request-changes -m "…"` · `pr merge <n> [--yes]` |
+| Audit · follow | `gitroots audit [--repo --since 2h --actor --action --decision --pr --csv]` · `audit <ev-id>` · `audit follow` |
+| Watch (live dashboard) | `gitroots watch [--machine m --agent codex --repo erp --state running]` (full screen) · `gitroots sessions` (plain list) |
+| Attach | `gitroots attach <session>` · `attach <session> --shell` (prefix `ctrl-g`: d detach · b backup · t transfer · f fork · s share · h history) |
+| Transfer | `gitroots transfer <session> --to <machine>` |
+| Backup · backups | `gitroots backup <session> --label "…"` · `backups [--repo --session --all]` · `backup policy` · `backup policy set --every 10m --store s3://bucket` |
+| Restore | `gitroots restore <session> --pick` · `restore <b-id>` · `--point <turn\|b-id>` · `--machine <m>` · `--fork` |
+| Tunnel · share | `gitroots tunnel <session> --port 8069` · `tunnel ls` · `tunnel close <t-id>\|--all` · `share <session> --read-only --expires 1h` |
+| (account) | `gitroots login [--server URL] [--org slug]` · `whoami` · `logout` |
+| (setup) | `gitroots doctor` · `update` · `uninstall [--purge]` · `completion bash\|zsh\|fish` |
+
+`gitroots help <command>` shows the details for one command.
+
+## Terminal design rules (from the canvas)
+
+- Every state pairs a symbol with a word: `● running`, `◐ waiting`, `○ queued`, `✓ done`, `✕ blocked`.
+- Green is used only for success and the one next action. Amber means it needs you. Red means a real block or failure.
+- Every screen ends with the next command (`→ gitroots pr view 412`).
+- `--json` works on every command. Colors drop when output is piped or `NO_COLOR` is set.
+- Motion (spinners, progress bars, live rows) stops when output is piped, with `NO_COLOR`, in `CI`, or when `GITROOTS_REDUCED_MOTION=1`.
+- The welcome screen shows the real logo image (`assets/logo.png`) in Kitty, Ghostty, WezTerm and iTerm2. Other terminals, tmux and screen get a plain `gitroots` line. Set `GITROOTS_NO_IMAGES=1` to turn the image off.
+
+## What is real and what is sample data
+
+- **Push checks (real):** `gitroots hooks install` writes a `pre-push` hook. An existing hook is kept and run first with `--force`. On every `git push` the hook checks your actual commits:
+  - the branch rule
+  - protected paths
+  - a secrets scan of added lines (AWS, GitHub, GitLab, Slack, Stripe, Google, Anthropic and OpenAI keys, private keys, hard-coded passwords)
+  - commit authors and signatures
+  - migration files
+
+  A blocked push exits non-zero, so nothing leaves the machine. If gitroots itself can't be found, the hook blocks the push rather than skipping the checks.
+- **Rules:** rules come from the gitroots org. For any other repo, put a `.gitroots.json` at its root:
+  ```json
+  { "protected": ["main", "release/*"], "paths": [{ "pattern": "infra/**", "needs": "an ops review" }] }
+  ```
+- **Signed in (real):** `gitroots login` signs in to your gitroots server (gitroots_core) with its Basic auth. The password is stored in the macOS Keychain, or in `~/.gitroots/credentials.json` (mode 600) elsewhere. After that, these use the real API:
+  - `whoami` and the `status` header
+  - `repo list` and `branch list` (GitHub repos synced in the dashboard)
+  - `audit`, `audit <ev-id>` and `audit follow` (which polls the API)
+  - the welcome screen's sign-in and repository checks
+- **Sample data:** PRs, agent sessions, machines, backups and tunnels aren't in the gitroots API yet. They run on the design's sample org, and screens say so when you're signed in. Your changes to them are saved in `~/.gitroots/state.json`, so commands build on each other. `gitroots demo reset` starts over. When the API grows those endpoints, add them in `src/connected.js` the same way repos and audit work.
+- **Shells:** `attach --shell` opens a real shell for sessions on this machine. A remote shell would need an agentd on that machine, which doesn't exist yet.
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `GITROOTS_HOME` | where state, config and credentials live (default `~/.gitroots`) |
+| `GITROOTS_SERVER` | default server for `gitroots login` (default `https://gitroots.com`) |
+| `GITROOTS_DOWNLOAD_BASE` | where `update` and the installers fetch releases |
+| `GITROOTS_NO_KEYCHAIN` | store the password in credentials.json even on macOS |
+| `GITROOTS_RELAY_DOMAIN` | domain used for tunnel and share links (default `<relay>.relay.gitroots.com`) |
+| `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             argument parsing, dispatch, help
+src/runtime.js         version, npm vs standalone binary, install paths
+src/api.js             gitroots API client, credentials
+src/connected.js       real data when signed in
+src/installer.js       download, verify, install (gitroots update)
+scripts/               build.mjs (release), install.sh, install.ps1
+src/ui/                colors (design tokens), steps/spinners/prompts, full-screen helpers, inline images
+src/commands/          one file per design screen
+src/git/checks.js      the real push checks
+src/data/              sample org, persisted store, live activity streams
+test/                  node --test (includes a real git push against a scratch repo)
+```

package/bin/gitroots.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+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,37 @@
 {
   "name": "gitroots",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.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",
+    "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/api.js

@@ -0,0 +1,121 @@
+// gitroots API client (gitroots_core, Django REST framework).
+// Sign-in uses the API's Basic auth; the password is kept in the macOS Keychain,
+// or in $GITROOTS_HOME/credentials.json (mode 600) elsewhere.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { home } from './data/store.js';
+
+export const DEFAULT_SERVER = process.env.GITROOTS_SERVER || 'https://gitroots.com';
+
+const configFile = () => path.join(home(), 'config.json');
+const credFile = () => path.join(home(), 'credentials.json');
+
+export function readConfig() {
+  try { return JSON.parse(fs.readFileSync(configFile(), 'utf8')); } catch { return {}; }
+}
+
+export function writeConfig(cfg) {
+  fs.mkdirSync(home(), { recursive: true });
+  fs.writeFileSync(configFile(), JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+
+const service = (server) => `gitroots:${server}`;
+const useKeychain = () => process.platform === 'darwin' && !process.env.GITROOTS_NO_KEYCHAIN;
+
+export function savePassword(server, username, password) {
+  if (useKeychain()) {
+    const r = spawnSync('security', ['add-generic-password', '-U', '-a', username, '-s', service(server), '-w', password], { stdio: 'ignore' });
+    if (r.status === 0) return 'keychain';
+  }
+  fs.mkdirSync(home(), { recursive: true });
+  let all = {};
+  try { all = JSON.parse(fs.readFileSync(credFile(), 'utf8')); } catch { /* none */ }
+  all[`${username}@${server}`] = password;
+  fs.writeFileSync(credFile(), JSON.stringify(all, null, 2), { mode: 0o600 });
+  fs.chmodSync(credFile(), 0o600);
+  return 'file';
+}
+
+export function loadPassword(server, username) {
+  if (process.env.GITROOTS_PASSWORD) return process.env.GITROOTS_PASSWORD;
+  if (useKeychain()) {
+    const r = spawnSync('security', ['find-generic-password', '-a', username, '-s', service(server), '-w'], { encoding: 'utf8' });
+    if (r.status === 0) return r.stdout.replace(/\n$/, '');
+  }
+  try { return JSON.parse(fs.readFileSync(credFile(), 'utf8'))[`${username}@${server}`] || null; } catch { return null; }
+}
+
+export function forgetPassword(server, username) {
+  if (process.platform === 'darwin') spawnSync('security', ['delete-generic-password', '-a', username, '-s', service(server)], { stdio: 'ignore' });
+  try {
+    const all = JSON.parse(fs.readFileSync(credFile(), 'utf8'));
+    delete all[`${username}@${server}`];
+    fs.writeFileSync(credFile(), JSON.stringify(all, null, 2), { mode: 0o600 });
+  } catch { /* none */ }
+}
+
+export class ApiError extends Error {
+  constructor(message, status) { super(message); this.status = status; }
+}
+
+export class Api {
+  constructor({ server, username, password }) {
+    this.server = server.replace(/\/+$/, '');
+    this.username = username;
+    this.auth = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+  }
+
+  static fromConfig() {
+    const cfg = readConfig();
+    if (!cfg.server || !cfg.username) return null;
+    const password = loadPassword(cfg.server, cfg.username);
+    if (!password) return null;
+    return new Api({ server: cfg.server, username: cfg.username, password });
+  }
+
+  async get(p, query = {}) {
+    const url = new URL(`${this.server}/api/${p.replace(/^\/+/, '')}`);
+    for (const [k, v] of Object.entries(query)) if (v !== undefined && v !== null) url.searchParams.set(k, v);
+    let res;
+    try {
+      res = await fetch(url, { headers: { Authorization: this.auth, Accept: 'application/json', 'User-Agent': 'gitroots-cli' }, signal: AbortSignal.timeout(15000) });
+    } catch (e) {
+      throw new ApiError(`can't reach ${this.server} (${e.cause?.code || e.name})`, 0);
+    }
+    if (res.status === 401 || res.status === 403) {
+      let detail = '';
+      try { detail = (await res.json()).detail || ''; } catch { /* not json */ }
+      throw new ApiError(res.status === 401 ? 'not signed in, or the password changed · gitroots login' : `not allowed${detail ? `: ${detail}` : ''}`, res.status);
+    }
+    if (!res.ok) {
+      let detail = '';
+      try { detail = (await res.json()).detail || ''; } catch { /* not json */ }
+      throw new ApiError(`${res.status} from ${url.pathname}${detail ? `: ${detail}` : ''}`, res.status);
+    }
+    const ct = res.headers.get('content-type') || '';
+    if (!ct.includes('json')) throw new ApiError(`${url.pathname} did not return JSON · is ${this.server} a gitroots server?`, res.status);
+    return res.json();
+  }
+
+  // DRF list: a plain array, or paginated { results, next }.
+  async list(p, query = {}) {
+    let data = await this.get(p, query);
+    if (Array.isArray(data)) return data;
+    const out = [...(data.results || [])];
+    let pages = 0;
+    while (data.next && pages++ < 50) {
+      const next = new URL(data.next);
+      data = await this.get(next.pathname.replace(/^\/api\//, ''), Object.fromEntries(next.searchParams));
+      out.push(...(data.results || []));
+    }
+    return out;
+  }
+
+  me() { return this.list('users/').then((us) => us.find((u) => u.username === this.username || u.email === this.username) || null); }
+  orgs() { return this.list('orgs/'); }
+  memberships() { return this.list('memberships/'); }
+  auditEvents() { return this.list('audit/events/'); }
+  repos(orgId) { return this.get('integrations/github/org-repos', { org_id: orgId, limit: 200 }).then((d) => d.repos || []); }
+  branches(orgId, fullName) { return this.get('integrations/github/org-branches', { org_id: orgId, full_name: fullName }).then((d) => d.branches || []); }
+}

package/src/cli.js

@@ -0,0 +1,150 @@
+import { setColor, c } from './ui/ansi.js';
+import { line } from './ui/term.js';
+import { brand, dot } from './ui/components.js';
+import { Store } from './data/store.js';
+import { VERSION } from './runtime.js';
+import { connect } from './connected.js';
+
+export { VERSION } from './runtime.js';
+
+// Flags that never take a value.
+const BOOL = new Set(['password-stdin', 'purge', 'draft', 'json', 'csv', 'all', 'pick', 'read-only', 'shell', 'request-changes', 'approve', 'comment', 'yes', 'y',
+  'help', 'h', 'version', 'v', 'no-color', 'fork', 'follow', 'squash', 'rebase', 'merge-commit', 'keep-branch', 'no-hooks', 'force', 'dry-run']);
+
+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);
+      if (key.startsWith('no-') && !BOOL.has(key)) { args.flags[key.slice(3)] = false; continue; }
+      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;
+}
+
+const COMMANDS = {
+  status: () => import('./commands/status.js'),
+  repo: () => import('./commands/repos.js'),
+  repos: () => import('./commands/repos.js'),
+  branch: () => import('./commands/repos.js'),
+  clone: () => import('./commands/repos.js'),
+  hooks: () => import('./commands/push.js'),
+  hook: () => import('./commands/push.js'),
+  check: () => import('./commands/push.js'),
+  pr: () => import('./commands/pr.js'),
+  audit: () => import('./commands/audit.js'),
+  watch: () => import('./commands/watch.js'),
+  attach: () => import('./commands/attach.js'),
+  transfer: () => import('./commands/transfer.js'),
+  backup: () => import('./commands/backup.js'),
+  backups: () => import('./commands/backup.js'),
+  restore: () => import('./commands/restore.js'),
+  tunnel: () => import('./commands/tunnel.js'),
+  share: () => import('./commands/tunnel.js'),
+  sessions: () => import('./commands/watch.js'),
+  demo: () => import('./commands/demo.js'),
+  login: () => import('./commands/auth.js'),
+  logout: () => import('./commands/auth.js'),
+  whoami: () => import('./commands/auth.js'),
+  doctor: () => import('./commands/doctor.js'),
+  completion: () => import('./commands/completion.js'),
+  __complete: () => import('./commands/completion.js'),
+  update: () => import('./commands/update.js'),
+  upgrade: () => import('./commands/update.js'),
+  uninstall: () => import('./commands/update.js'),
+};
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.flags.color === false || args.flags['no-color']) setColor(false);
+  if (args.flags.json || args.flags.csv) setColor(false);
+  if (args.flags.version || args.flags.v) { line(`gitroots ${VERSION}`); return 0; }
+
+  const [cmd, ...rest] = args._;
+  if (!cmd) {
+    if (args.flags.help || args.flags.h) { help(); return 0; }
+    const { default: splash } = await import('./commands/splash.js');
+    return splash(connect(Store.open()), args);
+  }
+  if (cmd === 'help' || args.flags.help || args.flags.h) { help(cmd === 'help' ? rest[0] : cmd); return 0; }
+  if (cmd === 'version') { line(`gitroots ${VERSION}`); return 0; }
+
+  const load = COMMANDS[cmd];
+  if (!load) {
+    line(`${c.r('✕')} unknown command ${c.b(cmd)}`);
+    line(`  ${c.g('→ gitroots help')}`);
+    return 2;
+  }
+  const mod = await load();
+  const store = connect(Store.open());
+  const code = await mod.run(cmd, rest, args.flags, store);
+  return code ?? 0;
+}
+
+const HELP = [
+  ['repos', 'gitroots repo list · branch list <repo> · branch rules <repo> <branch> · clone <repo>', 'repositories and branch rules'],
+  ['push', 'git push  (after gitroots hooks install)  · gitroots check', 'gitroots checks every push before it leaves'],
+  ['review', 'gitroots pr list · pr view <n> · pr diff <n> · pr approve <n> · pr merge <n>', 'reviews and merges'],
+  ['audit', 'gitroots audit · audit <ev-id> · audit follow', 'who did what, when, and what was blocked'],
+  ['agents', 'gitroots watch · attach · transfer · backup · backups · restore · tunnel · share', 'every agent session, one place'],
+  ['account', 'gitroots login · whoami · logout', 'sign in to your gitroots server'],
+  ['setup', 'gitroots doctor · update · completion <shell> · uninstall', 'keep the CLI healthy and current'],
+];
+
+const DETAIL = {
+  status: ['gitroots status', 'Everything at a glance: what needs you, repositories, agent sessions, the last hour.'],
+  repo: ['gitroots repo list', 'List repositories you can see, with protected branches and your role.'],
+  branch: ['gitroots branch list <repo> [--all]\ngitroots branch rules <repo> <branch>', 'Branches and the rules gitroots enforces on them.'],
+  clone: ['gitroots clone <repo|git-url> [dir] [--url <git-url>]', 'Clone a repository and install the gitroots push checks.'],
+  hooks: ['gitroots hooks install [--force]\ngitroots hooks uninstall', 'Install the pre-push hook so git push runs gitroots checks first.'],
+  check: ['gitroots check [<base>..<head>] [--branch <name>]', 'Run the push checks on local commits without pushing.'],
+  pr: ['gitroots pr list [repo] [--state open|merged|all]\ngitroots pr view <n>\ngitroots pr diff <n>\ngitroots pr create [--base staging] [--head branch] [--title "…"] [--draft]\ngitroots pr approve <n> [-m "note"]\ngitroots pr review <n> --request-changes -m "why"\ngitroots pr merge <n> [--yes] [--squash|--rebase|--merge-commit] [--keep-branch]', 'Pull requests: review, approve and merge under the branch rules.'],
+  audit: ['gitroots audit [--repo r] [--since 2h] [--actor a] [--action a] [--decision blocked] [--pr n] [--csv]\ngitroots audit <ev-id>\ngitroots audit follow', 'History of every push, approval, merge and rule change, plus a live stream.'],
+  watch: ['gitroots watch [--machine m]', 'Live dashboard of every agent session. Keys: ↑↓ move · tab machines/sessions · a attach · t transfer · b backup · r restore · f fork · u tunnel · p pause · s stop · / filter · ? help · q quit'],
+  attach: ['gitroots attach <session>', 'Attach to an agent session. Prefix ctrl-g: d detach · b backup · t transfer · f fork · s share read-only. Everything else goes to the agent.'],
+  transfer: ['gitroots transfer <session> --to <machine>', 'Move a running agent session to another machine with its conversation and workspace.'],
+  backup: ['gitroots backup <session> [--label "…"]\ngitroots backups [--repo r] [--session s] [--all]\ngitroots backup policy', 'Snapshot an agent session: conversation, workspace and environment.'],
+  restore: ['gitroots restore <session|backup> [--machine m] [--pick] [--point turn|backup] [--fork]', 'Bring a session back to an earlier point, on any machine.'],
+  tunnel: ['gitroots tunnel <session> --port <n>  [--shell]\ngitroots tunnel ls\ngitroots tunnel close <t-id> | --all\ngitroots share <session> --read-only [--expires 1h]', 'Reach a port on the agent\'s machine, or share a read-only live view.'],
+  demo: ['gitroots demo reset', 'Reset the demo organisation to its starting state.'],
+  login: ['gitroots login [--server https://gitroots.com] [--username u] [--org slug] [--password-stdin]', 'Sign in to a gitroots server. Repositories, branches and audit then come from the API.'],
+  whoami: ['gitroots whoami', 'Show who you are signed in as.'],
+  logout: ['gitroots logout', 'Sign out and forget the stored password.'],
+  doctor: ['gitroots doctor', 'Check the install, git, hooks in this repo, sign-in and terminal support.'],
+  update: ['gitroots update [--version x.y.z]', 'Update to the latest release, the same way gitroots was installed.'],
+  completion: ['gitroots completion bash|zsh|fish', 'Print a shell completion script. e.g. gitroots completion zsh > "${fpath[1]}/_gitroots"'],
+  uninstall: ['gitroots uninstall [--purge]', 'Remove the native install (--purge also removes ~/.gitroots).'],
+};
+DETAIL.upgrade = DETAIL.update; DETAIL.repos = DETAIL.repo; DETAIL.backups = DETAIL.backup; DETAIL.share = DETAIL.tunnel; DETAIL.hook = DETAIL.hooks;
+
+export function help(topic) {
+  if (topic && DETAIL[topic]) {
+    const [usage, desc] = DETAIL[topic];
+    line(desc);
+    line();
+    for (const u of usage.split('\n')) line(`  ${c.g(u)}`);
+    line();
+    line(c.m('  --json on every command · colors and motion drop when piped or with NO_COLOR'));
+    return;
+  }
+  line(`${brand()}  ${c.s(`v${VERSION}`)}  ${dot()}  ${c.s('code governance and agent sessions')}`);
+  line();
+  line(c.m('QUICK START'));
+  for (const [k, cmds, what] of HELP) line(`  ${c.s(k.padEnd(8))}  ${c.g(cmds)}`), line(`  ${' '.repeat(8)}  ${c.m(what)}`);
+  line();
+  line(c.m('  gitroots help <command> for details · --json on every command'));
+}