external-review 1.0.0

package/bin/external-review.mjs

@@ -0,0 +1,582 @@
+#!/usr/bin/env node
+// external-review — pick a second model, know what it costs you, know where
+// your code goes, and run a review with it.
+//
+// No dependencies on purpose: this reads your API key and syncs your source, so
+// the whole thing should be auditable in one sitting.
+
+import { spawn, spawnSync } from 'node:child_process';
+import {
+  existsSync, readFileSync, writeFileSync, readdirSync, statSync,
+  mkdirSync, copyFileSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const OR = 'https://openrouter.ai/api/v1';
+
+// ---------------------------------------------------------------- utilities
+
+const C = process.stdout.isTTY
+  ? { dim: (s) => `\x1b[2m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`,
+      g: (s) => `\x1b[32m${s}\x1b[0m`, y: (s) => `\x1b[33m${s}\x1b[0m`,
+      r: (s) => `\x1b[31m${s}\x1b[0m`, c: (s) => `\x1b[36m${s}\x1b[0m` }
+  : new Proxy({}, { get: () => (s) => s });
+
+const die = (msg) => { console.error(`${C.r('error')} ${msg}`); process.exit(1); };
+const info = (msg) => console.error(C.dim(msg));
+
+/** Read the OpenRouter key from the env or from opencode's auth store. */
+function apiKey({ required = true } = {}) {
+  if (process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+  const authFile = join(homedir(), '.local/share/opencode/auth.json');
+  if (existsSync(authFile)) {
+    try {
+      const key = JSON.parse(readFileSync(authFile, 'utf8'))?.openrouter?.key;
+      if (key) return key;
+    } catch { /* fall through to the error below */ }
+  }
+  if (!required) return null;
+  die('no API key. Set OPENROUTER_API_KEY, or run `opencode auth login`.');
+}
+
+async function api(path, { key = apiKey(), ...init } = {}) {
+  const res = await fetch(`${OR}${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${key}`, ...(init.headers || {}) },
+  });
+  if (!res.ok) die(`OpenRouter ${path} → HTTP ${res.status}`);
+  return res.json();
+}
+
+const num = (v) => (v == null ? null : Number(v));
+const money = (v) => (v == null ? '—' : `$${Number(v).toFixed(4)}`);
+
+/** Per-million-token price, which is how everyone actually compares models. */
+function perM(pricing = {}) {
+  const p = num(pricing.prompt);
+  const c = num(pricing.completion);
+  if (p == null && c == null) return '—';
+  const fmt = (x) => (x == null ? '?' : x === 0 ? 'free' : `$${(x * 1e6).toFixed(2)}`);
+  return `${fmt(p)} in / ${fmt(c)} out`;
+}
+
+const isFree = (m) => num(m?.pricing?.prompt) === 0 && num(m?.pricing?.completion) === 0;
+
+// ------------------------------------------------------------------ doctor
+
+async function cmdDoctor() {
+  let bad = 0;
+  const check = (ok, label, detail) => {
+    console.log(`${ok ? C.g('  ok  ') : C.y(' warn ')} ${label}${detail ? C.dim(`  ${detail}`) : ''}`);
+    if (!ok) bad++;
+  };
+
+  console.log(C.b('\nexternal-review doctor\n'));
+
+  const key = apiKey({ required: false });
+  check(!!key, 'API key found',
+    key ? `${key.slice(0, 8)}…${key.slice(-4)}` : 'set OPENROUTER_API_KEY or run `opencode auth login`');
+
+  const runner = findRunner();
+  check(!!runner, 'a runner is installed', runner || 'install one: npm i -g opencode-ai');
+
+  for (const tool of ['rsync', 'ssh']) {
+    const ok = spawnSync('which', [tool]).status === 0;
+    check(ok, `${tool} available`, ok ? '' : 'needed only for the remote-machine workflow');
+  }
+
+  if (key) {
+    const { data } = await api('/key', { key });
+    const tier = data.is_free_tier ? 'free tier' : 'paid';
+    check(true, `key reachable (${tier})`, `spent today: ${money(data.usage_daily)}`);
+    if (data.is_free_tier) {
+      console.log(C.dim(
+        '\n  Free tier: OpenRouter caps free-model requests per day (50/day, or\n' +
+        '  1000/day once the account has ever purchased 10 credits). A long review\n' +
+        '  is many requests. `external-review quota` shows where you stand.'));
+    }
+  }
+
+  console.log(bad ? C.y('\nSome checks want attention.\n') : C.g('\nReady.\n'));
+}
+
+function findRunner() {
+  for (const c of [join(homedir(), '.opencode/bin/opencode'), 'opencode']) {
+    if (c.startsWith('/') ? existsSync(c) : spawnSync('which', [c]).status === 0) return c;
+  }
+  return null;
+}
+
+// ------------------------------------------------------------------- quota
+
+async function cmdQuota() {
+  const { data } = await api('/key');
+  console.log(C.b('\nAccount\n'));
+  const row = (k, v) => console.log(`  ${k.padEnd(18)} ${v}`);
+  row('tier', data.is_free_tier ? C.y('free') : C.g('paid'));
+  row('spent today', money(data.usage_daily));
+  row('spent this week', money(data.usage_weekly));
+  row('spent this month', money(data.usage_monthly));
+  row('spent all time', money(data.usage));
+
+  if (data.limit != null) {
+    const pct = Math.round((num(data.limit_remaining) / num(data.limit)) * 100);
+    const bar = '█'.repeat(Math.max(0, Math.round(pct / 5))).padEnd(20, '░');
+    row('credit limit', money(data.limit));
+    row('remaining', `${money(data.limit_remaining)}  ${pct > 25 ? C.g(bar) : C.y(bar)} ${pct}%`);
+    if (data.limit_reset) row('resets', data.limit_reset);
+  } else {
+    row('credit limit', C.dim('none set'));
+  }
+
+  if (data.is_free_tier) {
+    console.log(C.y('\n  Free-model request cap'));
+    console.log(C.dim(
+      '  :free models      50 requests/day, and 20/minute.\n' +
+      '                    1000/day once the account has EVER purchased 10\n' +
+      '                    credits — permanent, not a subscription.\n' +
+      '  resets            on the UTC day.\n\n' +
+      '  The daily counter is ACCOUNT-WIDE across every :free model, so switching\n' +
+      '  free models does not get you a fresh budget. It is not exposed by the\n' +
+      '  API, which is why it is not shown above.\n\n' +
+      '  STEALTH MODELS DRAW ON A SEPARATE POOL. An anonymous/cloaked preview\n' +
+      '  model is not a :free model and has its own, much larger allowance —\n' +
+      '  which is why a day can run far past 50 requests and then stop abruptly\n' +
+      '  when you switch to a genuine :free model. The two errors differ:\n' +
+      '    "Rate limit exceeded: free-models-per-day-stealth"  → stealth pool\n' +
+      '    "Rate limit exceeded: free-models-per-day"          → the 50/day pool\n\n' +
+      '  A whole-subsystem review is 40-150 requests. On the free tier that is\n' +
+      '  ONE pass, maybe two. Add credits, or use stealth models, or expect to\n' +
+      '  plan a day at a time.'));
+  }
+  console.log();
+}
+
+// ------------------------------------------------------------------ models
+
+async function cmdModels(args) {
+  const wantFree = args.includes('--free');
+  const wantAll = args.includes('--all');
+  const limit = Number(argValue(args, '--limit') ?? (wantAll ? 1e9 : 25));
+  const minCtx = Number(argValue(args, '--min-context') ?? 60000);
+
+  const { data } = await api('/models');
+  let models = data.filter((m) => (num(m.context_length) ?? 0) >= minCtx);
+  if (wantFree) models = models.filter(isFree);
+
+  // A code review means reading a lot and writing a little, so rank by context
+  // first — a model that cannot hold the subsystem cannot review it.
+  models.sort((a, b) => (num(b.context_length) ?? 0) - (num(a.context_length) ?? 0));
+
+  console.log(C.b(`\n${models.length} model(s) with ≥${(minCtx / 1000) | 0}k context${wantFree ? ', free only' : ''}\n`));
+  console.log(C.dim('  context   price / 1M tokens          id'));
+  for (const m of models.slice(0, limit)) {
+    const ctx = `${Math.round((num(m.context_length) ?? 0) / 1000)}k`.padStart(7);
+    const price = perM(m.pricing).padEnd(26);
+    console.log(`  ${ctx}   ${isFree(m) ? C.g(price) : price} ${m.id}`);
+  }
+  if (models.length > limit) console.log(C.dim(`\n  …${models.length - limit} more. --all to list them, --limit N to change.`));
+  console.log(C.dim('\n  Next: `external-review providers <id>` to see who serves it and where.\n'));
+}
+
+function argValue(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+// --------------------------------------------------------------- providers
+
+async function cmdProviders(args) {
+  const model = args.find((a) => !a.startsWith('-'));
+  if (!model) die('usage: external-review providers <model-id>');
+
+  const [{ data: detail }, { data: providers }] = await Promise.all([
+    api(`/models/${model}/endpoints`),
+    api('/providers'),
+  ]);
+  const byName = new Map(providers.map((p) => [p.name, p]));
+
+  console.log(C.b(`\n${detail.name || model}\n`));
+
+  const endpoints = detail.endpoints || [];
+
+  // NO ENDPOINTS is an answer, not an error - and the most important one this
+  // command can give. Stealth and cloaked models publish no provider at all, so
+  // there is nothing to look up: you cannot learn who runs the machine your
+  // source is about to be sent to.
+  if (endpoints.length === 0) {
+    console.log(C.y('  This model does not disclose its providers.\n'));
+    console.log(C.dim(
+      '  OpenRouter lists no endpoints for it, which is characteristic of a\n' +
+      '  STEALTH or CLOAKED model: an unreleased model shipped under an\n' +
+      '  anonymous name to gather real-world usage before launch.\n\n' +
+      '  So the questions this command exists to answer — who operates it, from\n' +
+      '  where, under which policy — have no available answer. What IS known is\n' +
+      '  the arrangement: these models are offered free because prompts and\n' +
+      '  completions are logged and used to improve them. That is their purpose,\n' +
+      '  not a side effect.\n\n' +
+      '  They are genuinely good at review work and frequently frontier-class.\n' +
+      '  Use one with code you would not mind training a model. For anything\n' +
+      '  else, pick a model that names its providers.\n'));
+    return;
+  }
+
+  console.log(C.dim('  Your prompt is sent to ONE of these, chosen per request.\n'));
+
+  for (const ep of endpoints) {
+    const p = byName.get(ep.provider_name) || {};
+    const hq = p.headquarters || '?';
+    const dcs = Array.isArray(p.datacenters) && p.datacenters.length
+      ? p.datacenters.join(', ')
+      : C.dim('not published');
+    console.log(`  ${C.c(ep.provider_name)}`);
+    console.log(`    headquarters  ${hq}`);
+    console.log(`    datacenters   ${dcs}`);
+    if (p.privacy_policy_url) console.log(`    privacy       ${C.dim(p.privacy_policy_url)}`);
+    if (p.terms_of_service_url) console.log(`    terms         ${C.dim(p.terms_of_service_url)}`);
+    console.log();
+  }
+
+  console.log(C.dim(
+    '  These are facts from OpenRouter, not a judgement. Where a provider is\n' +
+    '  based and where it runs its hardware may or may not matter for your code —\n' +
+    '  that depends on your obligations, not on ours. Read the linked policy.\n\n' +
+    '  To pin a single provider, use OpenRouter\'s `provider.order` routing, or\n' +
+    '  choose a model with only one endpoint.\n'));
+
+  // Detected from the endpoints' own PRICING, not from the id string: the
+  // canonical slug this command takes has no `:free` suffix, so matching on the
+  // name missed exactly the models the warning is for.
+  const anyFree = endpoints.some((e) => isFree(e));
+  if (anyFree) {
+    console.log(C.y('  Before you send source to this one'));
+    console.log(C.dim(
+      '  Free and stealth endpoints are free because of what they may do with\n' +
+      '  your data. OpenRouter will not route to them at all unless you have\n' +
+      '  enabled, in Settings → Privacy:\n\n' +
+      '    "Enable free endpoints that may train on inputs"\n' +
+      '    "Enable free endpoints that may publish prompts"\n\n' +
+      '  If free models work for you, those are ON, and the code you send may be\n' +
+      '  trained on and published. A stealth model is an unreleased model shipped\n' +
+      '  anonymously to gather real usage — logging your prompts IS its purpose.\n\n' +
+      '  If that is not acceptable for this code, use Zero Data Retention: a\n' +
+      '  privacy-settings toggle, a per-key guardrail, or `"zdr": true` per\n' +
+      '  request. It blocks storage and training, and it removes most free\n' +
+      '  endpoints — which is the trade being made either way.\n'));
+  }
+}
+
+
+// -------------------------------------------------------------------- scan
+
+/* Content-based secret detection.
+ *
+ * The exclusion list catches a credential that lives in a FILE NAMED like a
+ * credential. It does nothing about the far commoner case: a live key pasted
+ * into an ordinary source file. `config.js` matches no pattern, and ships.
+ *
+ * Patterns are deliberately high-signal. A scanner that cries wolf gets
+ * `--force`d past on the second run and then protects nobody, so anything
+ * heuristic enough to fire on real code is left out. This finds keys with
+ * distinctive prefixes and real private-key blocks; it will NOT find every
+ * secret, and the report says so rather than implying a clean bill of health.
+ */
+/* A private key SPANS LINES, so the per-line scan below cannot see it: the
+ * header is on one line and the base64 on the next. It also needs that base64
+ * to be present at all - a lone header is almost always a PARSER stripping it,
+ * which is what a real repo's only false positive of this class turned out to
+ * be. So it gets its own whole-text pattern, matched separately.
+ */
+const PRIVATE_KEY_BLOCK =
+  /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----[\r\n\\]+\s*[A-Za-z0-9+/=]{20,}/;
+
+const SECRET_PATTERNS = [
+  ['AWS access key id', /\bAKIA[0-9A-Z]{16}\b/],
+  ['GitHub token', /\bgh[pousr]_[A-Za-z0-9]{36,}\b/],
+  ['Slack token', /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/],
+  ['Stripe live key', /\bsk_live_[A-Za-z0-9]{20,}\b/],
+  ['OpenAI-style key', /\bsk-[A-Za-z0-9]{20,}\b/],
+  ['OpenRouter key', /\bsk-or-v1-[A-Za-z0-9]{20,}\b/],
+  ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['Anthropic key', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/],
+  ['JWT', /\bey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/],
+  ['connection string with password', /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:[^\s:@/]+@[^\s/]+/],
+];
+
+const SCAN_SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'build', 'dist', 'target', '.venv', 'venv',
+  '__pycache__', '.dart_tool', '.gradle', 'Pods', 'vendor', '.next',
+]);
+
+const SCAN_SKIP_EXT = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.svg', '.pdf', '.zip',
+  '.gz', '.tar', '.mp4', '.mov', '.mp3', '.woff', '.woff2', '.ttf', '.otf',
+  '.jks', '.keystore', '.p12', '.der', '.apk', '.aab', '.so', '.dylib',
+]);
+
+/* Files whose "secrets" are public by design.
+ *
+ * Firebase client config (API key, app id, sender id) is an IDENTIFIER, not a
+ * credential: Google documents it as safe to embed, and access is gated by app
+ * signature / bundle id and security rules, not by the key. Every mobile repo
+ * has these committed, so flagging them trains people to ignore the scanner -
+ * which costs more than the warning is worth.
+ */
+const PUBLIC_BY_DESIGN = [
+  /(^|\/)google-services\.json$/,
+  /(^|\/)GoogleService-Info\.plist$/,
+  /(^|\/)firebase_options\.dart$/,
+  /(^|\/)firebase-config\.(js|ts|json)$/,
+];
+
+function scanTree(root) {
+  const hits = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!SCAN_SKIP_DIRS.has(e.name)) walk(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      const dot = e.name.lastIndexOf('.');
+      if (dot > 0 && SCAN_SKIP_EXT.has(e.name.slice(dot).toLowerCase())) continue;
+      const rel = full.slice(root.length + 1);
+      if (PUBLIC_BY_DESIGN.some((re) => re.test(rel))) continue;
+      let text;
+      try {
+        if (statSync(full).size > 2_000_000) continue; // not source
+        text = readFileSync(full, 'utf8');
+      } catch { continue; }
+      if (text.includes('\u0000')) continue; // binary
+
+      const pem = PRIVATE_KEY_BLOCK.exec(text);
+      if (pem) {
+        hits.push({
+          file: rel,
+          line: text.slice(0, pem.index).split('\n').length,
+          label: 'private key block',
+        });
+      }
+
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        for (const [label, re] of SECRET_PATTERNS) {
+          if (re.test(lines[i])) {
+            hits.push({ file: rel, line: i + 1, label });
+            break;
+          }
+        }
+      }
+    }
+  };
+  walk(root);
+  return hits;
+}
+
+function cmdScan(args) {
+  const root = argValue(args, '--in') ?? process.cwd();
+  const hits = scanTree(root);
+
+  if (hits.length === 0) {
+    console.log(C.g(`\n  no high-signal secrets found in ${root}`));
+    console.log(C.dim(
+      '\n  This is NOT a clean bill of health. It looks for credentials with\n' +
+      '  distinctive shapes - key prefixes, private-key blocks, passworded\n' +
+      '  connection strings. A bare 32-character token in a config file looks\n' +
+      '  exactly like any other string and cannot be found this way.\n' +
+      '  Read your own diff before sending it somewhere.\n'));
+    return hits;
+  }
+
+  console.log(C.r(`\n  ${hits.length} possible secret(s) in ${root}\n`));
+  for (const h of hits) {
+    console.log(`  ${C.y(h.label.padEnd(28))} ${h.file}:${h.line}`);
+  }
+  console.log(C.dim(
+    '\n  Filename exclusions would NOT stop these - they are inside ordinary\n' +
+    '  source files. Before sending this tree to a model:\n' +
+    '    - move the value to an environment variable, or\n' +
+    '    - add the file with --exclude, or\n' +
+    '    - confirm it is a placeholder / already-public identifier.\n' +
+    '  If a live credential has already been sent, rotate it. A provider\n' +
+    '  retention policy is not a recall.\n'));
+  return hits;
+}
+
+// -------------------------------------------------------------------- sync
+
+const DEFAULT_EXCLUDES = [
+  '.git/', 'node_modules/', 'build/', 'dist/', 'target/', '.venv/', 'venv/',
+  '__pycache__/', '.dart_tool/', '.gradle/', 'Pods/',
+  // Anything that is or holds a credential. Extend with --exclude.
+  '.env', '.env.*', '*.pem', '*.der', '*.key', '*.jks', '*.keystore', '*.p12',
+  '*.mobileprovision', 'id_rsa*', '*.crt',
+  'secrets.*', '*.secrets.*', 'credentials.*', 'service-account*.json',
+];
+
+/** Paths that must NOT exist in the synced copy, verified after the sync. */
+function verifyList(extra) {
+  return ['.env', '.git', ...extra];
+}
+
+function cmdSync(args) {
+  const dest = argValue(args, '--to');
+  const src = argValue(args, '--from') ?? process.cwd();
+  const extra = args.filter((a, i) => args[i - 1] === '--exclude');
+  if (!dest) die('usage: external-review sync --to user@host:~/review-dir [--from .] [--exclude PATH]');
+
+  // SCAN BEFORE SENDING, and refuse by default. This is the whole reason the
+  // command exists rather than telling people to run rsync themselves: the
+  // moment a review copy leaves the machine is the last moment anything can be
+  // done about a key inside it.
+  if (!args.includes('--skip-scan')) {
+    const hits = cmdScan(['--in', src]);
+    if (hits.length && !args.includes('--force')) {
+      die('refusing to sync. Resolve the findings above, or pass --force if ' +
+          'every one is a placeholder or an already-public identifier.');
+    }
+    if (hits.length) info('--force given; syncing anyway');
+  }
+
+  const excludes = [...DEFAULT_EXCLUDES, ...extra].flatMap((e) => ['--exclude', e]);
+  info(`syncing ${src} → ${dest}`);
+  const r = spawnSync('rsync', ['-az', '--delete', ...excludes, `${src}/`, dest], { stdio: 'inherit' });
+  if (r.status !== 0) die('rsync failed');
+
+  // VERIFY, do not assume. An exclusion that silently did not match is the
+  // whole risk this command exists to manage.
+  const [userHost, remoteDir] = splitDest(dest);
+  if (userHost) {
+    const checks = verifyList(extra)
+      .map((f) => `if [ -e "${f}" ]; then echo "LEAKED: ${f}"; fi`)
+      .join('; ');
+    const out = spawnSync('ssh', [userHost, `cd ${remoteDir} && { ${checks}; } ; echo VERIFY_DONE`], { encoding: 'utf8' });
+    const leaked = (out.stdout || '').split('\n').filter((l) => l.startsWith('LEAKED:'));
+    if (leaked.length) {
+      console.error(C.r('\nSecrets reached the review copy:'));
+      leaked.forEach((l) => console.error(`  ${l}`));
+      die('delete the remote copy and re-sync with the right --exclude flags');
+    }
+    console.log(C.g('\n  verified: no excluded path is present in the copy\n'));
+  }
+}
+
+function splitDest(dest) {
+  const m = /^([^:]+):(.+)$/.exec(dest);
+  return m ? [m[1], m[2]] : [null, dest];
+}
+
+// --------------------------------------------------------------------- run
+
+function cmdRun(args) {
+  const promptFile = argValue(args, '--prompt');
+  const model = argValue(args, '--model');
+  const cwd = argValue(args, '--in') ?? process.cwd();
+  const out = argValue(args, '--out') ?? join(tmpdir(), `review-${Date.now()}.md`);
+  if (!promptFile || !model) {
+    die('usage: external-review run --prompt FILE --model ID [--in DIR] [--out FILE]');
+  }
+  if (!existsSync(promptFile)) die(`no such prompt file: ${promptFile}`);
+
+  const runner = findRunner();
+  if (!runner) die('no runner found. Install one: npm i -g opencode-ai');
+
+  const prompt = readFileSync(promptFile, 'utf8');
+  info(`model   ${model}`);
+  info(`scope   ${cwd}`);
+  info(`output  ${out}`);
+
+  const child = spawn(runner, ['run', '-m', model, prompt], {
+    cwd, stdio: ['ignore', 'pipe', 'inherit'],
+  });
+  let buf = '';
+  child.stdout.on('data', (d) => { buf += d; process.stdout.write(d); });
+  child.on('close', (code) => {
+    writeFileSync(out, buf);
+    console.error(code === 0 ? C.g(`\nwrote ${out}`) : C.y(`\nrunner exited ${code}; partial output in ${out}`));
+    process.exit(code ?? 0);
+  });
+}
+
+
+// ----------------------------------------------------------- install-skill
+
+/* Copy the skill to where the assistant looks for it.
+ *
+ * A command rather than a documented `cp`, because the path depends on how the
+ * package was installed: a GLOBAL install puts it under the npm root, a local
+ * one under ./node_modules, and running from a clone puts it next to this file.
+ * The README shipped the local path beside the global install instruction,
+ * which is a paper cut on the very first thing a new user does.
+ */
+function cmdInstallSkill(args) {
+  const global = args.includes('--global');
+  const dest = join(global ? homedir() : process.cwd(),
+    '.claude', 'skills', 'external-review');
+
+  // Resolve relative to THIS file, so it works from a global install, a local
+  // one, or a git clone without knowing which.
+  const src = join(dirname(fileURLToPath(import.meta.url)),
+    '..', 'skills', 'external-review');
+  if (!existsSync(join(src, 'SKILL.md'))) {
+    die(`cannot find the skill next to the CLI (looked in ${src})`);
+  }
+
+  if (existsSync(join(dest, 'SKILL.md')) && !args.includes('--force')) {
+    die(`${dest} already exists. Pass --force to overwrite it.`);
+  }
+
+  mkdirSync(dest, { recursive: true });
+  copyFileSync(join(src, 'SKILL.md'), join(dest, 'SKILL.md'));
+
+  console.log(C.g(`\n  installed → ${dest}`));
+  console.log(C.dim(
+    `\n  ${global ? 'Available in every project.' : 'Available in this project.'}` +
+    `${global ? '' : ' Use --global for every project.'}\n` +
+    '  Now ask your assistant to "review this with a second model".\n'));
+}
+
+// -------------------------------------------------------------------- help
+
+const HELP = `
+${C.b('external-review')} — run a code review with a second, independent model.
+
+${C.b('Commands')}
+  install-skill [--global]   put the skill where your assistant will find it
+  doctor                     check your setup and say what is missing
+  quota                      spend so far, credit limit, and the free-tier cap
+  models [--free] [--all]    candidate models, ranked by context window
+         [--min-context N] [--limit N]
+  providers <model-id>       who actually serves that model, and from where
+  scan [--in DIR]            find credentials INSIDE source files, which no
+                             filename exclusion can catch
+  sync --to HOST:DIR         copy your source to a review machine, secrets
+       [--from DIR] [--exclude PATH]   excluded — then VERIFY they are absent
+  run --prompt FILE --model ID [--in DIR] [--out FILE]
+
+${C.b('Typical first run')}
+  external-review doctor
+  external-review models --free
+  external-review providers <the-one-you-liked>
+  external-review run --prompt ./review.txt --model <id> --out findings.md
+
+${C.dim('Docs, and the review prompts that actually found bugs:')}
+${C.dim('https://github.com/yevgavrikov/claude-external-review')}
+`;
+
+// -------------------------------------------------------------------- main
+
+const [cmd, ...rest] = process.argv.slice(2);
+const run = {
+  doctor: cmdDoctor, quota: cmdQuota, models: cmdModels,
+  providers: cmdProviders, scan: cmdScan, sync: cmdSync, run: cmdRun,
+  'install-skill': cmdInstallSkill,
+}[cmd];
+
+if (!run) { console.log(HELP); process.exit(cmd ? 1 : 0); }
+await run(rest);