@expo/code-review-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 650 Industries, Inc. (Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# expo-code-review
+
+A config-driven, multi-agent AI code reviewer. Specialist agents review a diff in
+parallel; a coordinator consolidates their findings into one structured review.
+Runs the same engine locally (advisory) and in CI (posts a PR comment).
+
+> **Status: experimental.** Phase 1 is **comment-only and non-blocking** — it
+> never blocks a merge and never auto-approves. The package is incubated inside
+> `eas-cli` for fast iteration and is intended to graduate into its own repo; see
+> [`ROADMAP.md`](./ROADMAP.md).
+
+The CLI is the **engine**. Each repo supplies its own agents and settings under
+`.expo-code-review/`, so behavior is configured per-repo, not baked in.
+
+## How it works
+
+```
+diff source ─▶ noise filter ─▶ chunk ─▶ agents (parallel) ─▶ coordinator ─▶ reporter
+(git / gh)     drop lockfiles,  by       each agent reviews    dedupe,        one PR comment
+               generated,       changed  every chunk +         re-judge,      (CI) or terminal
+               binary files     lines    a cross-cutting pass   decide         output (local)
+```
+
+- **Source** — local git (working tree, staged, or a ref range) or a GitHub PR
+  (diff + metadata fetched over the `gh` API).
+- **Noise filter** — drops lockfiles, generated bundles/maps, snapshots, files
+  matching the repo's `additionalIgnores`, and binary files (no textual diff to
+  review). Filtered files are recorded, not silently dropped.
+- **Chunking** — small PRs run in a single pass; large PRs are split into chunks
+  bounded by changed lines, plus one combined **cross-cutting pass** that looks
+  for issues spanning multiple changed files across every agent's concern.
+- **Agents** — every `.md` file in `.expo-code-review/agents/` is an agent. They
+  run in parallel with read-only repo tools (`read`/`grep`/`glob`/`list`).
+- **Coordinator** — a single pass that dedupes, re-judges severity, and produces
+  the final `{ decision, findings, summary }`.
+- **Reporter** — posts/updates a single fingerprinted PR comment (CI), or prints
+  a grouped summary (local). Findings below the configured severity floor are
+  suppressed.
+
+Built on the [OpenCode](https://opencode.ai) SDK, which spawns the model provider
+and applies Anthropic prompt caching automatically.
+
+## Commands
+
+Run via the workspace during incubation (`yarn workspace expo-code-review dev …`),
+or as the `ecr` / `expo-code-review` binary once built/installed.
+
+| Command | What it does |
+| --- | --- |
+| `ecr review [options]` | Review local changes and print an advisory review (default command). |
+| `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
+| `ecr init [--with-workflow] [--force]` | Scaffold `.expo-code-review/` (config, agents, prompts) in this repo. |
+| `ecr doctor` | Check environment, config, and model credentials. |
+
+### `ecr review` options
+
+```
+--base <ref>       Base ref to diff against (default: merge-base with default branch)
+--head <ref>       Head ref to diff (default: working tree, incl. uncommitted changes)
+--staged           Review only staged changes
+--pr <n>           Review GitHub PR #n by number (diff fetched via gh, no checkout);
+                   not combinable with --base/--head/--staged
+--repo <owner/repo>  Repo for --pr (default: inferred from the current checkout)
+--post             With --pr: also post the result as the PR comment (needs gh auth).
+                   Omit to preview only; re-run with --post to publish.
+--agents <a,b>     Run only these agents (comma-separated ids); default: all
+--route            Let an LLM router pick the relevant agents from the diff
+--json             Emit machine-readable JSON on stdout
+--no-fail          Always exit 0 (otherwise a request_changes decision exits non-zero)
+-h, --help         Show help
+```
+
+Reviewing a PR without checking it out — preview, then optionally post:
+
+```bash
+ecr review --pr 4057            # print the review here; posts nothing
+ecr review --pr 4057 --post     # re-run and post it as the PR comment
+```
+
+`--pr` uses the PR's diff (authoritative) but reads your checked-out files for
+surrounding context; for full fidelity, `gh pr checkout <n>` first and run a plain
+`ecr review`.
+
+## Configuration — `.expo-code-review/`
+
+```
+.expo-code-review/
+  config.jsonc        # model, policy, noise, auth, break-glass, comment tag
+  shared.md           # instructions prepended to every agent (optional)
+  coordinator.md      # the consolidation prompt (required)
+  agents/
+    correctness.md    # each .md here is an agent (id = filename)
+    security.md
+    consistency.md
+```
+
+`shared.md` and `coordinator.md` are reserved names; every other `.md` in
+`agents/` becomes an agent. Per-agent overrides go in each file's frontmatter:
+
+```markdown
+---
+description: One line the router uses to decide relevance.
+alwaysRun: true        # run even when the router would skip this agent
+model: anthropic/claude-sonnet-5     # override the default model (e.g. haiku for the coordinator)
+temperature: 0.1
+---
+
+# Agent instructions in Markdown…
+```
+
+### `config.jsonc`
+
+```jsonc
+{
+  "model": "anthropic/claude-sonnet-5",       // default model for the specialists
+  "policy": { "includeSuggestions": false },  // suppress suggestion-severity findings
+  "chunk": { "maxChangedLines": 1000, "maxFiles": 20, "concurrency": 6 },
+  "noise": { "additionalIgnores": ["packages/*/build/**"] },
+  "breakGlass": { "marker": "/skip-review" }, // PR body marker that skips the review
+  "commentTag": "expo-ai-code-reviewer",      // hidden tag used to find/update the comment
+  "auth": { "mode": "oauth", "provider": "anthropic",
+            "tokenEnv": "DO_NOT_USE_EXPERIMENTAL_ANTHROPIC_API_KEY" }
+}
+```
+
+JSONC (comments + trailing commas) is supported.
+
+## Authentication
+
+Model credentials come from OpenCode. Two modes, set in `config.auth`:
+
+- **`api-key`** — the token in `tokenEnv` is copied into the provider's API-key
+  env var (e.g. `ANTHROPIC_API_KEY`).
+- **`oauth`** — a Claude Pro/Max token (from `claude setup-token`, an
+  `sk-ant-oat…` token, *not* an x-api-key) is written into an isolated OpenCode
+  `auth.json` as a bearer credential, so it uses the native subscription path.
+
+Set **`REVIEWER_MODEL`** to override the model for every agent and use your own
+OpenCode login instead of the repo's configured credentials — handy locally
+(e.g. `REVIEWER_MODEL=openai/gpt-5.4-mini-fast`). There is no shared fallback key;
+if a run fails for lack of credentials, authenticate a provider in OpenCode.
+
+Run `ecr doctor` to diagnose setup.
+
+## Model selection
+
+Models are resolved with this precedence: **`REVIEWER_MODEL` env** (global override)
+→ per-file **frontmatter `model:`** → **`config.jsonc` `model`** (the default). So a
+repo can run a mixed setup, and a developer can override everything locally.
+
+Rules of thumb for the reviewer's workload:
+
+- **Specialist agents** (correctness/security/consistency) do the real bug-finding
+  and benefit from a reasoning-tier model — **Sonnet** is the quality/speed sweet
+  spot (the default for correctness/consistency). **Opus** finds more but is slower
+  and more rate-limited, which makes large-PR timeouts worse — so scope it to the
+  one agent where the extra threat-model reasoning pays off most: **security runs on
+  Opus** (set in `security.md` frontmatter), the rest on Sonnet. This keeps the
+  latency/rate-limit cost to a single agent, and the timeout handling (subdivide +
+  per-fetch deadline) keeps a slow Opus pass from hanging the run.
+- **The coordinator** only consolidates text (no repo tools), so a fast, cheap
+  model — **Haiku** — fits well and keeps the serial tail short. Set it in
+  `coordinator.md` frontmatter.
+- If latency/timeouts dominate on big PRs, moving the specialists to a faster model
+  is the most direct lever (a real recall tradeoff — measure it).
+
+Example mixed setup:
+
+```jsonc
+// config.jsonc
+"model": "anthropic/claude-sonnet-5"        // default: specialists + cross-file pass
+```
+```markdown
+<!-- security.md frontmatter -->  → Opus for the highest-stakes agent
+---
+model: anthropic/claude-opus-4-8
+---
+
+<!-- coordinator.md frontmatter --> → Haiku for the text-only consolidation
+---
+model: anthropic/claude-haiku-4-5-20251001
+---
+```
+
+There is no automatic cross-provider "equivalent" fallback — that would silently
+change which model reviewed your code. Use an explicit override instead.
+
+## Reliability
+
+A review must never hang, silently produce nothing, or present an unreviewed
+change as "looks good":
+
+- **Per-task time caps** — focused chunk passes get 15 min; the cross-cutting pass
+  gets 25 min; the coordinator gets 10 min. A global passes budget (32 min) bounds
+  all passes incl. the subdivision waves below, so everything fits inside the CI
+  job's `timeout-minutes` (60), since the coordinator + verification run afterward.
+- **Tool-call cap** — a pass that makes too many `read`/`grep` calls without
+  finishing is *wandering*, not converging (the usual cause of a non-convergent
+  timeout). Hitting the cap trips the same soft landing as the time cap.
+- **Soft landing on timeout** — at either cap, the run is interrupted and the agent
+  is asked to return the findings it already has, rather than discarding its work.
+- **Subdivide-on-timeout — the reviewer never silently drops work.** If a pass
+  times out with nothing to show, its chunk is split in half and the halves are
+  re-reviewed (recursively, down to a single file). A chunk that won't converge at
+  13 files almost always converges at 6. If even a single file won't converge, a
+  fast **no-tools fallback** reviews just its inlined diff (a lighter review, but
+  never nothing). Only if *that* can't finish inside the budget is a coverage gap
+  reported — and it is always reported, never silent.
+- **Parse failures are retried** (same session, then once in a bounded fresh
+  session); that is separate from the timeout path above.
+- **A failed run never reads as "Approve"** — if every pass fails, the review says
+  it could not complete (treat as unreviewed); if some passes fail, the decision
+  is never a clean approve, and the coordinator is told coverage was reduced.
+- **The coordinator can't sink the run** — if the consolidation step fails, findings
+  are merged deterministically and still posted, rather than thrown away.
+- **Coverage notes** — passes that timed out or failed are listed so a real
+  coverage gap is never silent (routine noise filtering is *not* flagged — it's
+  expected and stays in the run log).
+- **CI always gets a terminal state** — on any failure the PR gets a comment saying
+  the reviewer didn't run, not a stuck reaction and silence.
+
+## CI usage
+
+`ecr init --with-workflow` scaffolds a `pull_request` workflow. In this repo the
+reviewer runs via two workflows, split along a clean line: **comments = one-shot
+actions, labels = persistent configuration.**
+
+- **`expo-code-review-command.yml`** — one-shot `/review` comments (maintainers):
+  - `/review` — run once now; the router picks the agents
+  - `/review all` — run once with every agent
+  - `/review correctness security` — run once with just those agents
+
+  These never change configuration.
+- **`expo-code-review.yml`** — continuous review, configured by **labels**:
+  - `ai-review` — auto-review every push; the router picks the agents
+  - `ai-review:all` — auto-review with every agent
+  - `ai-review:<agent>` — auto-review with only those agents (e.g.
+    `ai-review:security`); combine several to widen the set
+  - `ai-review:skip` — never auto-review this PR (opt-out)
+- **`expo-code-review-dismiss.yml`** — dismiss/restore a finding on a PR (maintainers):
+  - `/dismiss <id> [<id> …] [-- reason]` — hide finding(s); they move to a collapsed
+    "Dismissed" section and stay dismissed across re-reviews
+  - `/undismiss <id> …` — restore them
+
+  Each finding shows a short `` `id:…` `` in the comment. Dismissal is a **display
+  filter only** — the reviewer still analyzes the code every run, and a `critical`
+  or `secrets` finding can never be hidden this way. (Also: an inline
+  `expo-code-review-ignore` comment on/above a line suppresses that line's findings,
+  same critical/secrets carve-out.)
+
+These workflows are comment-only (they never fail the PR's checks). For security,
+they build/run only the trusted base ref (never the PR head) — see the comment at
+the top of each file.
+
+## Run logs
+
+Each run appends a JSON line to `.expo-code-review/.runs/reviews.jsonl` with the
+inputs, decision, finding count, duration, per-agent cost, and aggregate token
+usage (including prompt-cache read/write counts) — for auditing and measuring
+cost/latency/cache reuse over time.

package/build/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { ciCommand } from './commands/ci.js';
+import { dismissCommand } from './commands/dismiss.js';
+import { doctorCommand } from './commands/doctor.js';
+import { initCommand } from './commands/init.js';
+import { reviewCommand } from './commands/review.js';
+const USAGE = `expo-code-review (ecr) — config-driven AI code reviewer
+
+Usage:
+  ecr review [options]   Review local changes (default). See \`ecr review --help\`.
+  ecr ci                 Review the current PR and post a comment (GitHub Actions).
+  ecr dismiss --pr <n> <id...>     Hide a finding on a PR (see \`ecr dismiss --help\`).
+  ecr undismiss --pr <n> <id...>   Restore a dismissed finding.
+  ecr init [--with-workflow] [--force]   Scaffold .expo-code-review/ in this repo.
+  ecr doctor             Check environment, config, and credentials.
+
+Agents live in each repo under .expo-code-review/. This CLI is the engine.
+`;
+async function main() {
+    const [, , sub, ...rest] = process.argv;
+    if (sub === '-h' || sub === '--help' || sub === 'help') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    // No subcommand (or a leading flag) defaults to `review`.
+    if (!sub || sub.startsWith('-')) {
+        await reviewCommand(process.argv.slice(2));
+        return;
+    }
+    switch (sub) {
+        case 'review':
+            await reviewCommand(rest);
+            break;
+        case 'ci':
+            await ciCommand(rest);
+            break;
+        case 'dismiss':
+            await dismissCommand(rest, 'add');
+            break;
+        case 'undismiss':
+            await dismissCommand(rest, 'remove');
+            break;
+        case 'init':
+            await initCommand(rest);
+            break;
+        case 'doctor':
+            await doctorCommand(rest);
+            break;
+        default:
+            process.stderr.write(`Unknown command: ${sub}\n\n${USAGE}`);
+            process.exitCode = 2;
+    }
+}
+void main();

package/build/commands/ci.js

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+import { loadReviewConfig } from '../config/load.js';
+import { repoRoot } from '../core/exec.js';
+import { errorMessage } from '../core/util.js';
+import { runReview } from '../core/review.js';
+import { GitHubPRSource } from '../sources/github-pr.js';
+import { GitHubReporter } from '../reporters/github.js';
+/** Resolve the PR number from the Actions event payload or GITHUB_REF. */
+async function resolvePrNumber() {
+    const eventPath = process.env.GITHUB_EVENT_PATH;
+    if (eventPath) {
+        try {
+            const event = JSON.parse(await readFile(eventPath, 'utf8'));
+            const number = event.pull_request?.number ?? event.issue?.number ?? event.number;
+            if (typeof number === 'number') {
+                return number;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    const match = (process.env.GITHUB_REF ?? '').match(/refs\/pull\/(\d+)\//);
+    return match ? Number(match[1]) : null;
+}
+const CI_USAGE = `ecr ci — review the current GitHub PR and post/update one comment.
+
+For GitHub Actions: reads the PR number + repo from the event/env, gets the diff
+via \`gh pr diff\`, runs the reviewer, and upserts a single PR comment. Comment-only
+and non-blocking (a reviewer failure never fails the PR's checks).
+
+Options:
+  --agents <a,b>   Run only these agents (comma-separated ids); default: all
+  --route          Let the router pick relevant agents from the diff
+  -h, --help       Show this help
+
+Env: GITHUB_REPOSITORY, GITHUB_EVENT_PATH/GITHUB_REF (PR number), GH_TOKEN,
+and model credentials per .expo-code-review/config.jsonc (or REVIEWER_MODEL).
+`;
+export async function ciCommand(argv = []) {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(CI_USAGE);
+        return;
+    }
+    const agents = parseAgents(argv);
+    const route = argv.includes('--route');
+    const root = await repoRoot();
+    if (root && root !== process.cwd()) {
+        process.chdir(root);
+    }
+    const repo = process.env.GITHUB_REPOSITORY;
+    const prNumber = await resolvePrNumber();
+    if (!repo || prNumber == null) {
+        process.stderr.write('CI reviewer: could not determine repository or PR number from the environment. Skipping.\n');
+        return;
+    }
+    let config;
+    try {
+        config = await loadReviewConfig(process.cwd());
+    }
+    catch (error) {
+        process.stderr.write(`CI reviewer: ${errorMessage(error)}\n`);
+        return;
+    }
+    const reporter = new GitHubReporter({
+        prNumber,
+        repo,
+        commentTag: config.commentTag,
+        breakGlassMarker: config.breakGlassMarker,
+        cwd: process.cwd(),
+    });
+    try {
+        if (await reporter.checkBreakGlass()) {
+            process.stderr.write(`CI reviewer: ${config.breakGlassMarker} detected; skipping.\n`);
+            await reporter.postSkipNote();
+            return;
+        }
+    }
+    catch (error) {
+        process.stderr.write(`CI reviewer: break-glass check failed (continuing): ${errorMessage(error)}\n`);
+    }
+    try {
+        const review = await runReview(new GitHubPRSource({ prNumber, repo, cwd: process.cwd() }), {
+            config,
+            mode: 'ci',
+            agents,
+            route,
+            onProgress: message => process.stderr.write(`${message}\n`),
+        });
+        await reporter.report(review);
+        process.stderr.write(`CI reviewer: posted review (${review.decision}).\n`);
+    }
+    catch (error) {
+        // A reviewer failure must never fail the PR's checks — but it must also not be
+        // silent. Post a terminal state to the PR so the maintainer who triggered it
+        // (e.g. a `/review` with a typo'd agent name, or a crash) gets feedback
+        // instead of a stuck 👀 reaction and nothing else.
+        const reason = errorMessage(error);
+        process.stderr.write(`CI reviewer: run failed (non-blocking): ${reason}\n`);
+        try {
+            await reporter.report({
+                decision: 'approve_with_comments',
+                findings: [],
+                summary: `⚠️ The AI reviewer failed to run, so this change was **not** reviewed:\n\n> ${reason}`,
+                incomplete: [],
+            });
+        }
+        catch (postError) {
+            process.stderr.write(`CI reviewer: also failed to post the failure notice: ${errorMessage(postError)}\n`);
+        }
+    }
+}
+/** Parse `--agents a,b,c` from argv (undefined = all agents). */
+function parseAgents(argv) {
+    const index = argv.indexOf('--agents');
+    if (index === -1) {
+        return undefined;
+    }
+    const value = argv[index + 1];
+    // A missing value, or the next token being another flag (e.g. `--agents --route`),
+    // means no agent list was given — treat as "all" rather than misparsing `--route`
+    // as an agent id. Mirrors review.ts's requireValue.
+    if (!value || value.startsWith('--')) {
+        return undefined;
+    }
+    return value
+        .split(',')
+        .map(id => id.trim())
+        .filter(Boolean);
+}

package/build/commands/dismiss.js

@@ -0,0 +1,97 @@
+import { loadReviewConfig } from '../config/load.js';
+import { repoRoot, resolveRepo } from '../core/exec.js';
+import { errorMessage } from '../core/util.js';
+import { GitHubReporter } from '../reporters/github.js';
+const USAGE = `ecr dismiss / undismiss — hide (or restore) a finding on a PR
+
+Usage:
+  ecr dismiss   --pr <n> [--repo <owner/repo>] <id...> [--reason <text>] [--by <user>]
+  ecr undismiss --pr <n> [--repo <owner/repo>] <id...>
+
+<id> is a finding's short id (shown as \`id:...\` in the reviewer comment). Dismissed
+findings move to a collapsed "Dismissed on this PR" section and stay there across
+re-reviews; the review still runs — this only affects display.
+`;
+function parseArgs(argv) {
+    const args = { ids: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--pr':
+                args.pr = Number(argv[++i]);
+                break;
+            case '--repo':
+                args.repo = argv[++i];
+                break;
+            case '--reason':
+                args.reason = argv[++i];
+                break;
+            case '--by':
+                args.by = argv[++i];
+                break;
+            default:
+                if (arg.startsWith('--')) {
+                    throw new Error(`Unknown argument: ${arg}`);
+                }
+                // Bare arg = a finding id. Sanitize to the fingerprint alphabet.
+                args.ids.push(arg.replace(/[^a-f0-9]/g, ''));
+        }
+    }
+    args.ids = args.ids.filter(Boolean);
+    return args;
+}
+export async function dismissCommand(argv, mode) {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (args.pr == null || !Number.isInteger(args.pr) || args.pr <= 0) {
+        process.stderr.write('dismiss: --pr <number> is required.\n');
+        process.exitCode = 2;
+        return;
+    }
+    if (args.ids.length === 0) {
+        process.stderr.write('dismiss: provide at least one finding id.\n');
+        process.exitCode = 2;
+        return;
+    }
+    const root = await repoRoot();
+    if (root && root !== process.cwd()) {
+        process.chdir(root);
+    }
+    const cwd = process.cwd();
+    try {
+        const config = await loadReviewConfig(cwd);
+        const repo = args.repo ?? (await resolveRepo(cwd));
+        const reporter = new GitHubReporter({
+            prNumber: args.pr,
+            repo,
+            commentTag: config.commentTag,
+            breakGlassMarker: config.breakGlassMarker,
+            cwd,
+        });
+        const result = await reporter.applyDismissal(mode === 'add' ? args.ids : [], mode === 'remove' ? args.ids : [], args.by, args.reason);
+        if (mode === 'add') {
+            process.stderr.write(`Dismissed ${result.matched.length} finding(s) on ${repo}#${args.pr}.\n`);
+        }
+        else {
+            process.stderr.write(`Restored finding(s) on ${repo}#${args.pr}.\n`);
+        }
+        if (result.unmatched.length > 0) {
+            process.stderr.write(`Unknown id(s) (no matching finding): ${result.unmatched.join(', ')}\n`);
+        }
+    }
+    catch (error) {
+        process.stderr.write(`dismiss failed: ${errorMessage(error)}\n`);
+        process.exitCode = 2;
+    }
+}

package/build/commands/doctor.js

@@ -0,0 +1,81 @@
+import { loadReviewConfig, hasConfig } from '../config/load.js';
+import { onPath, repoRoot, run } from '../core/exec.js';
+import { errorMessage } from '../core/util.js';
+const USAGE = `ecr doctor — check environment, config, and credentials
+
+Usage:
+  ecr doctor
+
+Verifies: opencode + git (+ gh for \`ecr ci\`) on PATH, .expo-code-review/ config is
+valid, agent prompts resolve, and the configured model's token env is set.
+`;
+/** Preflight checks so a broken setup surfaces clearly instead of silently no-opping. */
+export async function doctorCommand(argv = []) {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const root = (await repoRoot()) ?? process.cwd();
+    let ok = true;
+    const line = (pass, message) => {
+        if (!pass) {
+            ok = false;
+        }
+        process.stdout.write(`  ${pass ? '✓' : '✗'} ${message}\n`);
+    };
+    process.stdout.write(`expo-code-review doctor (repo: ${root})\n`);
+    const opencodeInstalled = await onPath('opencode');
+    line(opencodeInstalled, opencodeInstalled
+        ? 'opencode CLI found on PATH'
+        : 'opencode CLI NOT on PATH (install `opencode-ai`, or add node_modules/.bin to PATH)');
+    line(await onPath('git'), 'git found on PATH');
+    // `gh` is only needed for `ecr ci` (posting PR comments), so treat it as
+    // informational (ℹ) rather than a hard failure for local `ecr review` users.
+    const info = (message) => {
+        process.stdout.write(`  ℹ ${message}\n`);
+    };
+    if (await onPath('gh')) {
+        let authed = false;
+        try {
+            await run('gh', ['auth', 'status'], { cwd: root });
+            authed = true;
+        }
+        catch {
+            authed = false;
+        }
+        if (authed) {
+            line(true, 'gh CLI found and authenticated (used by `ecr ci`)');
+        }
+        else {
+            info('gh CLI found but not authenticated — run `gh auth login` before `ecr ci`');
+        }
+    }
+    else {
+        info('gh CLI not on PATH — only needed for `ecr ci` (posting PR comments)');
+    }
+    if (!hasConfig(root)) {
+        line(false, `no ${'.expo-code-review'}/config.jsonc (run \`ecr init\`)`);
+    }
+    else {
+        try {
+            const config = await loadReviewConfig(root);
+            line(true, `config valid: ${config.agents.length} agent(s) [${config.agents.map(a => a.id).join(', ')}], coordinator model ${config.coordinator.model}`);
+            line(config.agents.every(a => Boolean(a.promptText.trim())), 'all agent prompt files resolved and non-empty');
+            const { mode, provider, tokenEnv } = config.auth;
+            if (tokenEnv) {
+                const present = Boolean(process.env[tokenEnv]);
+                line(present, present
+                    ? `auth: ${mode} for ${provider}; token env ${tokenEnv} is set`
+                    : `auth: ${mode} for ${provider}; token env ${tokenEnv} is NOT set`);
+            }
+            else {
+                line(true, `auth: ${mode} for ${provider}; no tokenEnv configured — relying on OpenCode's own login or REVIEWER_MODEL`);
+            }
+        }
+        catch (error) {
+            line(false, `config invalid: ${errorMessage(error)}`);
+        }
+    }
+    process.stdout.write(ok ? '\nAll good.\n' : '\nIssues found (see ✗ above).\n');
+    process.exitCode = ok ? 0 : 1;
+}