@expo/code-review-cli 0.2.3 → 0.3.0

package/build/commands/ci.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { loadReviewConfig } from '../config/load.js';
-import { repoRoot } from '../core/exec.js';
+import { repoRoot, run } from '../core/exec.js';
 import { errorMessage } from '../core/util.js';
 import { runReview } from '../core/review.js';
 import { GitHubPRSource } from '../sources/github-pr.js';
@@ -62,6 +62,23 @@ export async function ciCommand(argv = []) {
         process.stderr.write(`CI reviewer: ${errorMessage(error)}\n`);
         return;
     }
+    // Config-driven trigger policy (.expo-code-review/config.jsonc → review): decide
+    // whether this PR should be reviewed at all. Fetch current labels via gh (more
+    // authoritative than the possibly-stale event payload); on failure, default to
+    // reviewing so a label-read hiccup never silently skips a PR.
+    let labels = [];
+    try {
+        const { stdout } = await run('gh', ['pr', 'view', String(prNumber), '--repo', repo, '--json', 'labels', '--jq', '.labels[].name'], { cwd: process.cwd() });
+        labels = stdout.split('\n').map(name => name.trim()).filter(Boolean);
+    }
+    catch (error) {
+        process.stderr.write(`CI reviewer: could not read PR labels (continuing): ${errorMessage(error)}\n`);
+    }
+    const gate = shouldReview(labels, config.review);
+    if (!gate.review) {
+        process.stderr.write(`CI reviewer: skipping — ${gate.reason}.\n`);
+        return;
+    }
     const reporter = new GitHubReporter({
         prNumber,
         repo,
@@ -110,6 +127,25 @@ export async function ciCommand(argv = []) {
         }
     }
 }
+/**
+ * Decide whether a PR should be reviewed, given its labels and the repo's trigger
+ * policy. `skipLabel` always wins (write-gated opt-out). In "label" mode a PR must
+ * carry `label` or a `label:<agent>` variant; in "all" mode every non-skipped PR
+ * is reviewed. Pure so it's unit-testable and matches exact label names (no
+ * substring surprises like `ai-review:skip` satisfying an `ai-review` check).
+ */
+export function shouldReview(labels, review) {
+    if (labels.includes(review.skipLabel)) {
+        return { review: false, reason: `the ${review.skipLabel} label is set` };
+    }
+    if (review.trigger === 'label') {
+        const optedIn = labels.some(name => name === review.label || name.startsWith(`${review.label}:`));
+        return optedIn
+            ? { review: true, reason: `the ${review.label} label is set` }
+            : { review: false, reason: `trigger is "label" and no ${review.label} label is set` };
+    }
+    return { review: true, reason: 'trigger is "all"' };
+}
 /** Parse `--agents a,b,c` from argv (undefined = all agents). */
 function parseAgents(argv) {
     const index = argv.indexOf('--agents');

package/build/commands/doctor.js

@@ -1,4 +1,5 @@
 import { loadReviewConfig, hasConfig } from '../config/load.js';
+import { checkProviderAuth } from '../core/auth.js';
 import { onPath, repoRoot, run } from '../core/exec.js';
 import { errorMessage } from '../core/util.js';
 const USAGE = `ecr doctor — check environment, config, and credentials
@@ -61,16 +62,8 @@ export async function doctorCommand(argv = []) {
             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`);
-            }
+            const readiness = checkProviderAuth(config);
+            line(readiness.ok, `auth: ${readiness.detail}`);
         }
         catch (error) {
             line(false, `config invalid: ${errorMessage(error)}`);

package/build/commands/review.js

@@ -16,7 +16,8 @@ Source (pick one):
   (default)          diff the working tree against the merge-base
   --base <ref>       base ref to diff against
   --head <ref>       head ref to diff
-  --staged           review only staged changes
+  --staged           review only staged changes (index vs HEAD; not combinable
+                     with --base/--head)
   --pr <n>           review GitHub PR #n by number (diff fetched via \`gh\`, no
                      checkout needed); can't be combined with --base/--head/--staged
 
@@ -187,5 +188,10 @@ function validateArgs(args) {
     if (args.pr == null && (args.repo || args.post)) {
         throw new Error('--repo/--post only apply together with --pr.');
     }
+    // --staged diffs the index against HEAD, so --base/--head have no effect. Reject
+    // the combination rather than silently ignoring the range the user asked for.
+    if (args.staged && (args.base || args.head)) {
+        throw new Error('--staged reviews the staged changes (index vs HEAD) and cannot be combined with --base/--head.');
+    }
 }
 /** Resolve owner/repo from the current checkout via gh (for --post). */

package/build/config/load.js

@@ -87,6 +87,7 @@ export async function loadReviewConfig(repoRoot) {
             provider: parsed.auth.provider,
             tokenEnv: parsed.auth.tokenEnv,
         },
+        review: parsed.review,
     };
 }
 /**

package/build/config/schema.js

@@ -62,4 +62,19 @@ export const ReviewConfigSchema = z.object({
         tokenEnv: z.string().optional(),
     })
         .default({ mode: 'api-key', provider: 'anthropic' }),
+    review: z
+        .object({
+        // Which PRs `ecr ci` acts on — the source of truth for trigger policy (a
+        // workflow `if:` gate, if any, is an optional coarse filter layered on top):
+        //   "all"   — review every PR, unless it carries the `skipLabel`.
+        //   "label" — review only PRs carrying `label` (e.g. `ai-review`) or a
+        //             `label:<agent>` variant. `skipLabel` still wins.
+        trigger: z.enum(['all', 'label']).default('all'),
+        // Opt-in label (and prefix for `label:<agent>`) used when trigger is "label".
+        label: z.string().default('ai-review'),
+        // Opt a single PR out of review. A label (not a config flag) because labels
+        // are write-gated to maintainers — a PR author can't add one to dodge review.
+        skipLabel: z.string().default('ai-review:skip'),
+    })
+        .default({ trigger: 'all', label: 'ai-review', skipLabel: 'ai-review:skip' }),
 });

package/build/core/auth.js

@@ -32,6 +32,67 @@ const FORBIDDEN_TOKEN_ENVS = new Set([
     'SSH_PRIVATE_KEY',
 ]);
 const YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+/**
+ * Decide whether the configured model provider has a usable credential, WITHOUT
+ * mutating the environment. Shared by `prepareAuth` (fail fast before spinning up
+ * the server and every pass) and `doctor` (report), so the two never drift.
+ *
+ * We only report `ok: false` when we're confident there is no credential — a
+ * missing OAuth token, a forbidden tokenEnv, or an api-key run with neither the
+ * configured tokenEnv nor the provider's own key env set. When nothing is
+ * configured and no known key env is present, we assume OpenCode's own login may
+ * cover it and don't hard-fail. `REVIEWER_MODEL` bypasses provider auth entirely.
+ */
+export function checkProviderAuth(config, env = process.env) {
+    const { mode, provider, tokenEnv } = config.auth;
+    if (env.REVIEWER_MODEL) {
+        return {
+            ok: true,
+            detail: `REVIEWER_MODEL override (${env.REVIEWER_MODEL}); using OpenCode's own login for that model`,
+        };
+    }
+    if (tokenEnv && FORBIDDEN_TOKEN_ENVS.has(tokenEnv)) {
+        return {
+            ok: false,
+            detail: `auth.tokenEnv is "${tokenEnv}", a well-known non-provider secret; refusing to ` +
+                `forward it to the model provider (that would leak it). Point auth.tokenEnv at a ` +
+                `token minted for the provider instead.`,
+        };
+    }
+    if (mode === 'oauth') {
+        if (!tokenEnv) {
+            return {
+                ok: false,
+                detail: 'auth.mode "oauth" requires auth.tokenEnv to name the env var holding the OAuth token.',
+            };
+        }
+        if (!env[tokenEnv]) {
+            return { ok: false, detail: `auth is oauth for ${provider} but token env "${tokenEnv}" is not set.` };
+        }
+        return { ok: true, detail: `oauth for ${provider}; token env ${tokenEnv} is set` };
+    }
+    // api-key: usable if the configured tokenEnv is set, or the provider's own key
+    // env is already present in the environment.
+    const providerKeyEnv = PROVIDER_KEY_ENV[provider];
+    if (tokenEnv && env[tokenEnv]) {
+        return { ok: true, detail: `api-key for ${provider}; token env ${tokenEnv} is set` };
+    }
+    if (providerKeyEnv && env[providerKeyEnv]) {
+        return { ok: true, detail: `api-key for ${provider}; ${providerKeyEnv} is set` };
+    }
+    if (!tokenEnv && !providerKeyEnv) {
+        return {
+            ok: true,
+            detail: `api-key for ${provider}; no tokenEnv configured and no known key env — relying on OpenCode's own login`,
+        };
+    }
+    const names = [tokenEnv, providerKeyEnv].filter(Boolean).join(' or ');
+    return {
+        ok: false,
+        detail: `configured api-key for ${provider} but no credential is set — set ${names}, or set ` +
+            `REVIEWER_MODEL to a model you're already logged into.`,
+    };
+}
 /**
  * Prepare model credentials for the OpenCode server based on the repo's auth mode.
  * Must run before the server starts (it mutates env). Returns a cleanup handle.
@@ -53,12 +114,13 @@ export async function prepareAuth(config) {
     if (process.env.REVIEWER_MODEL) {
         return noop;
     }
-    // Refuse to forward a well-known unrelated secret as the provider credential,
-    // even if the (repo/PR-controlled) config names one — that would leak it.
-    if (tokenEnv && FORBIDDEN_TOKEN_ENVS.has(tokenEnv)) {
-        throw new Error(`auth.tokenEnv is set to "${tokenEnv}", a well-known non-provider secret. Refusing ` +
-            `to forward it to the model provider (that would leak the secret). Point auth.tokenEnv ` +
-            `at a token minted for the model provider instead.`);
+    // Fail fast, before starting the server and every pass, if the configured
+    // provider has no usable credential — otherwise it surfaces as N failed passes
+    // mid-run. This is the same readiness check `doctor` reports, and it also covers
+    // the forbidden-secret guard (refusing to forward a well-known unrelated secret).
+    const readiness = checkProviderAuth(config);
+    if (!readiness.ok) {
+        throw new Error(readiness.detail);
     }
     if (mode === 'api-key') {
         if (tokenEnv) {
@@ -72,13 +134,11 @@ export async function prepareAuth(config) {
         }
         return noop;
     }
-    // oauth
-    if (!tokenEnv) {
-        throw new Error('auth.mode "oauth" requires auth.tokenEnv to name the env var holding the OAuth token.');
-    }
-    const token = process.env[tokenEnv];
+    // oauth — checkProviderAuth guarantees tokenEnv is set and present; read
+    // defensively so TypeScript narrows and this stays correct if called directly.
+    const token = tokenEnv ? process.env[tokenEnv] : undefined;
     if (!token) {
-        throw new Error(`OAuth token env "${tokenEnv}" is not set.`);
+        throw new Error('auth.mode "oauth" requires auth.tokenEnv to name a set OAuth token env.');
     }
     const dir = await mkdtemp(path.join(tmpdir(), 'ecr-auth-'));
     await mkdir(path.join(dir, 'opencode'), { recursive: true });

package/build/core/opencode.js

@@ -1,6 +1,6 @@
 import { createOpencode } from '@opencode-ai/sdk';
 import { toolMap } from './tools.js';
-import { sleep } from './util.js';
+import { errorMessage, sleep } from './util.js';
 /** Sum token usage across attempts (for per-task/run totals). */
 export function addTokenUsage(into, from) {
     if (!from) {
@@ -240,6 +240,60 @@ const CORRECTIVE = '\n\nIMPORTANT: your previous reply could not be parsed. Repl
 // Budget for a corrective "re-emit the JSON" reply — no fresh investigation, so
 // it should return almost immediately.
 const CORRECTIVE_WAIT_MS = 2 * 60 * 1000;
+/** Backoff (ms) before the 2nd and 3rd attempt of a transient-failing model call. */
+const TRANSIENT_BACKOFF_MS = [2_000, 8_000];
+/**
+ * A transient, retryable API failure — a one-off rate-limit (429), server error
+ * (5xx), or network blip — as opposed to a timeout (which means "abandon", see
+ * AgentTimeoutError) or a JSON-parse failure (handled by the corrective re-emit in
+ * promptAndParse). We match on the error text because the OpenCode SDK surfaces
+ * these as plain Errors; an AgentTimeoutError is never transient.
+ */
+const TRANSIENT_PATTERNS = [
+    /\b429\b/,
+    /\b50[0-9]\b/,
+    /rate.?limit/i,
+    /overloaded/i,
+    /too many requests/i,
+    /temporarily unavailable/i,
+    /ETIMEDOUT/i,
+    /ECONNRESET/i,
+    /ECONNREFUSED/i,
+    /ENOTFOUND/i,
+    /EAI_AGAIN/i,
+    /socket hang ?up/i,
+    /network error/i,
+    /fetch failed/i,
+];
+export function isTransientApiError(error) {
+    if (error instanceof AgentTimeoutError) {
+        return false;
+    }
+    const message = errorMessage(error);
+    return TRANSIENT_PATTERNS.some(pattern => pattern.test(message));
+}
+/**
+ * Run a model call, retrying with bounded backoff on a transient API error. This
+ * is deliberately separate from the timeout path (abandon, never retry) and the
+ * parse-failure path (corrective re-emit): a one-off 429/5xx/network error used to
+ * drop the whole pass with no retry, reported as a coverage gap. Non-transient
+ * errors (incl. AgentTimeoutError) propagate immediately.
+ */
+async function withTransientRetry(label, onActivity, fn) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const waitMs = TRANSIENT_BACKOFF_MS[attempt];
+            if (waitMs === undefined || !isTransientApiError(error)) {
+                throw error;
+            }
+            onActivity?.(`${label}: transient API error (${errorMessage(error)}); retry ${attempt + 1}/${TRANSIENT_BACKOFF_MS.length} in ${Math.round(waitMs / 1000)}s`);
+            await sleep(waitMs);
+        }
+    }
+}
 /**
  * Prompt an agent and parse its reply. On a JSON-parse failure, first retry in
  * the SAME session: the model still holds all the file context it read, so the
@@ -259,7 +313,7 @@ export async function promptAndParse(handle, args, parse) {
         truncated = truncated || (result.truncated ?? false);
         addTokenUsage(tokens, result.tokens);
     };
-    const first = await promptAgent(handle, args);
+    const first = await withTransientRetry(`Agent "${args.agent}"`, args.onActivity, () => promptAgent(handle, args));
     record(first);
     try {
         return { value: parse(first.text), cost, truncated, tokens };

package/build/core/review.js

@@ -245,7 +245,12 @@ export async function runReview(source, options) {
                 if (!(error instanceof AgentTimeoutError)) {
                     failedPasses++;
                     progress(`  ${task.label}: FAILED (${errorMessage(error)})`);
-                    incomplete.push(`${capitalize(task.coverageLabel)} failed to run; those changes were not reviewed.`);
+                    // An auth/permission failure hits every pass identically; push one shared,
+                    // actionable note (deduped into a single coverage line) instead of N generic
+                    // per-pass failures that bury the real, fixable cause.
+                    incomplete.push(isAuthError(error)
+                        ? AUTH_FAILURE_NOTE
+                        : `${capitalize(task.coverageLabel)} failed to run; those changes were not reviewed.`);
                     return;
                 }
                 // Account for the abandoned investigation's spend regardless of what's next.
@@ -375,6 +380,7 @@ export async function runReview(source, options) {
         if (removedAfterChecks > 0) {
             output = { ...output, summary: reconcileSummary(output.summary, output.findings.length) };
         }
+        progress(formatUsageSummary(tokenTotals, sum(agentCosts)));
         await safeLog(logPath, {
             ...baseRecord,
             agentCosts,
@@ -488,6 +494,29 @@ export function reconcileSummary(summary, remaining) {
 function capitalize(text) {
     return text.length > 0 ? text[0].toUpperCase() + text.slice(1) : text;
 }
+/**
+ * An authentication/authorization failure from the model provider (401/403, a
+ * rejected/expired/missing credential) — distinct from a transient blip or a real
+ * code finding. Every pass hits the same wall, so the caller collapses it into one
+ * actionable coverage note instead of N generic "failed to run" lines.
+ */
+export function isAuthError(error) {
+    const message = errorMessage(error).toLowerCase();
+    const cred = /(api.?key|token|credential)/;
+    const problem = /(invalid|expired|revoked|missing|rejected|no)/;
+    return (/\b401\b|\b403\b/.test(message) ||
+        /unauthor/.test(message) ||
+        /\bforbidden\b/.test(message) ||
+        /authentication/.test(message) ||
+        /permission denied/.test(message) ||
+        /invalid x-api-key/.test(message) ||
+        // a credential noun and a problem word near each other, in either order
+        new RegExp(`${problem.source}\\b[^.]{0,20}${cred.source}`).test(message) ||
+        new RegExp(`${cred.source}[^.]{0,20}${problem.source}`).test(message));
+}
+const AUTH_FAILURE_NOTE = 'The model provider rejected the request (authentication or permission). Check the ' +
+    'configured credential (auth.tokenEnv, or REVIEWER_MODEL for a local run) and re-run — ' +
+    'those changes were not reviewed.';
 function selectAgents(all, filter) {
     if (!filter?.length) {
         return all;
@@ -563,6 +592,21 @@ export async function runGrowableQueue(initial, limit, fn) {
 function sum(costs) {
     return Object.values(costs).reduce((total, value) => total + value, 0);
 }
+/**
+ * One-line usage summary for the run. Emitted via progress so it lands in the CI
+ * job log (and the local terminal) — `.runs/reviews.jsonl` is ephemeral in CI, so
+ * this is the only place the token/cache totals are visible after a CI run, which
+ * is how prompt-cache effectiveness gets confirmed there.
+ */
+export function formatUsageSummary(tokens, totalCost) {
+    const parts = [`input ${tokens.input ?? 0}`, `output ${tokens.output ?? 0}`];
+    if (tokens.reasoning) {
+        parts.push(`reasoning ${tokens.reasoning}`);
+    }
+    parts.push(`cache read ${tokens.cache?.read ?? 0}`, `cache write ${tokens.cache?.write ?? 0}`);
+    const cost = totalCost > 0 ? ` (cost $${totalCost.toFixed(4)})` : '';
+    return `Token usage — ${parts.join(', ')}${cost}`;
+}
 async function safeLog(logPath, record) {
     try {
         await writeRunLog(logPath, record);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/config.jsonc

@@ -25,6 +25,16 @@
   // full-context pass. Defaults shown; raise/lower per your model + PR sizes.
   // "chunk": { "maxChangedLines": 1000, "maxFiles": 20, "concurrency": 4 },
 
+  // Which PRs `ecr ci` reviews. This is the source of truth for trigger policy;
+  // the scaffolded workflow always calls `ecr ci` and lets this decide. (If you'd
+  // rather gate in the workflow instead, add an `if:` to the job — see the
+  // workflow template — and this still applies on top.)
+  //   "trigger": "all"   — review every PR, unless it has the `skipLabel`.
+  //   "trigger": "label" — review only PRs labeled `label` (or `label:<agent>`).
+  // The `skipLabel` is write-gated (only maintainers can add labels), so a PR
+  // author can't opt their own PR out.
+  "review": { "trigger": "all", "label": "ai-review", "skipLabel": "ai-review:skip" },
+
   // A maintainer comment containing this marker skips the CI review.
   "breakGlass": { "marker": "/skip-review" },
 

package/templates/workflow.yml

@@ -17,9 +17,14 @@ concurrency:
 jobs:
   review:
     runs-on: ubuntu-latest
-    # Opt-in per PR: only run when the `ai-review` label is present. Remove this
-    # line to review every PR automatically.
-    if: contains(join(github.event.pull_request.labels.*.name, ','), 'ai-review')
+    # Trigger policy lives in .expo-code-review/config.jsonc (review.trigger); `ecr ci`
+    # self-gates on it (and honors the ai-review:skip label). This coarse gate just
+    # avoids spinning up a runner for a PR that explicitly opted out. Uses the array
+    # form of contains() for an EXACT label match ("ai-review:skip" is not "ai-review").
+    # Prefer to gate entirely here instead? Set config trigger to "label" and replace
+    # the line below with, e.g.:
+    #   if: contains(github.event.pull_request.labels.*.name, 'ai-review')
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'ai-review:skip') }}
     # Backstop so a stalled review fails fast instead of hanging.
     timeout-minutes: 60
     # A reviewer failure must never fail the PR's checks.