happy-stacks 0.3.0 → 0.4.0

package/scripts/mobile.mjs

@@ -1,13 +1,17 @@
 import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { pickNextFreeTcpPort } from './utils/net/ports.mjs';
 import { run, runCapture, spawnProc } from './utils/proc/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
 import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/proc/pm.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo/expo.mjs';
-import { killProcessGroupOwnedByStack } from './utils/proc/ownership.mjs';
-import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv } from './utils/server/urls.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths } from './utils/expo/expo.mjs';
+import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
+import { resolveMobileExpoConfig } from './utils/mobile/config.mjs';
+import { resolveStackContext } from './utils/stack/context.mjs';
+import { expoExec } from './utils/expo/command.mjs';
+import { ensureDevExpoServer } from './utils/dev/expo_dev.mjs';
+import { resolveMobileReachableServerUrl } from './utils/server/mobile_api_url.mjs';
+import { patchIosXcodeProjectsForSigningAndIdentity, resolveIosAppXcodeProjects } from './utils/mobile/ios_xcodeproj_patch.mjs';
 
 /**
  * Mobile dev helper for the embedded `components/happy` Expo app.
@@ -70,19 +74,6 @@ async function main() {
   await requireDir('happy', uiDir);
   await ensureDepsInstalled(uiDir, 'happy');
 
-  const sanitizeBundleIdSegment = (s) =>
-    (s ?? '')
-      .toString()
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9-]+/g, '-')
-      .replace(/^-+|-+$/g, '') || 'user';
-
-  const defaultLocalBundleId = (() => {
-    const user = sanitizeBundleIdSegment(process.env.USER ?? process.env.USERNAME ?? 'user');
-    return `com.happy.local.${user}.dev`;
-  })();
-
   async function readXcdeviceList() {
     if (process.platform !== 'darwin') {
       return [];
@@ -97,21 +88,6 @@ async function main() {
   // Default to the existing dev bundle identifier, which is also registered as a URL scheme
   // (Info.plist includes `com.slopus.happy.dev`), so iOS will open the dev build instead of the App Store app.
   const appEnv = process.env.APP_ENV ?? kv.get('--app-env') ?? 'development';
-  const iosAppName =
-    kv.get('--ios-app-name') ??
-    process.env.HAPPY_STACKS_IOS_APP_NAME ??
-    process.env.HAPPY_LOCAL_IOS_APP_NAME ??
-    '';
-  const iosBundleId =
-    kv.get('--ios-bundle-id') ??
-    process.env.HAPPY_STACKS_IOS_BUNDLE_ID ??
-    process.env.HAPPY_LOCAL_IOS_BUNDLE_ID ??
-    defaultLocalBundleId;
-  const scheme =
-    kv.get('--scheme') ??
-    process.env.HAPPY_STACKS_MOBILE_SCHEME ??
-    process.env.HAPPY_LOCAL_MOBILE_SCHEME ??
-    iosBundleId;
   const host = kv.get('--host') ?? process.env.HAPPY_STACKS_MOBILE_HOST ?? process.env.HAPPY_LOCAL_MOBILE_HOST ?? 'lan';
   const portRaw = kv.get('--port') ?? process.env.HAPPY_STACKS_MOBILE_PORT ?? process.env.HAPPY_LOCAL_MOBILE_PORT ?? '8081';
   // Default behavior:
@@ -126,26 +102,56 @@ async function main() {
     APP_ENV: appEnv,
   };
 
+  const cfgBase = resolveMobileExpoConfig({ env });
+  const iosAppName = (kv.get('--ios-app-name') ?? cfgBase.iosAppName ?? '').toString();
+  const iosBundleId = (kv.get('--ios-bundle-id') ?? cfgBase.iosBundleId ?? '').toString();
+  const scheme = (kv.get('--scheme') ?? cfgBase.scheme ?? iosBundleId).toString();
+
   const autostart = getDefaultAutostartPaths();
-  const mobilePaths = getExpoStatePaths({
+  const stackCtx = resolveStackContext({ env, autostart });
+  const { stackMode, runtimeStatePath, stackName, envPath } = stackCtx;
+
+  // Ensure the built iOS app registers the same scheme we use for dev-client QR links.
+  // (Happy app reads EXPO_APP_SCHEME in app.config.js; default remains unchanged when unset.)
+  env.EXPO_APP_SCHEME = scheme;
+  // Ensure the app display name + bundle id are consistent with what we install.
+  // (app.config.js keeps upstream defaults unless these are explicitly set.)
+  if (iosAppName && iosAppName.trim()) {
+    env.EXPO_APP_NAME = iosAppName.trim();
+  }
+  if (iosBundleId && iosBundleId.trim()) {
+    env.EXPO_APP_BUNDLE_ID = iosBundleId.trim();
+  }
+
+  // Always isolate Expo home + TMPDIR to avoid cross-worktree cache pollution (and to keep sandbox runs contained).
+  const expoPaths = getExpoStatePaths({
     baseDir: autostart.baseDir,
-    kind: 'mobile-dev',
+    kind: 'expo-dev',
     projectDir: uiDir,
-    stateFileName: 'mobile.state.json',
+    stateFileName: 'expo.state.json',
   });
   await ensureExpoIsolationEnv({
     env,
-    stateDir: mobilePaths.stateDir,
-    expoHomeDir: mobilePaths.expoHomeDir,
-    tmpDir: mobilePaths.tmpDir,
+    stateDir: expoPaths.stateDir,
+    expoHomeDir: expoPaths.expoHomeDir,
+    tmpDir: expoPaths.tmpDir,
   });
 
   // Allow happy-stacks to define the default server URL baked into the app bundle.
   // This is read by the app via `process.env.EXPO_PUBLIC_HAPPY_SERVER_URL`.
-  const serverPort = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
-  const { envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort });
-  if (envPublicUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
-    env.EXPO_PUBLIC_HAPPY_SERVER_URL = envPublicUrl;
+  const serverPort = resolveServerPortFromEnv({ env, defaultPort: 3005 });
+  const allowEnableTailscale =
+    !stackMode || stackName === 'main' || (env.HAPPY_STACKS_TAILSCALE_SERVE ?? env.HAPPY_LOCAL_TAILSCALE_SERVE ?? '0').toString().trim() === '1';
+  const resolvedUrls = await resolveServerUrls({ env, serverPort, allowEnable: allowEnableTailscale });
+  if (resolvedUrls.publicServerUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
+    env.EXPO_PUBLIC_HAPPY_SERVER_URL = resolvedUrls.publicServerUrl;
+  }
+  if (env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
+    env.EXPO_PUBLIC_HAPPY_SERVER_URL = resolveMobileReachableServerUrl({
+      env,
+      serverUrl: env.EXPO_PUBLIC_HAPPY_SERVER_URL,
+      serverPort,
+    });
   }
 
   if (json) {
@@ -179,13 +185,12 @@ async function main() {
     if (shouldClean) {
       prebuildArgs.push('--clean');
     }
-    await pmExecBin({ dir: uiDir, bin: 'expo', args: prebuildArgs, env });
+    await expoExec({ dir: uiDir, args: prebuildArgs, env, ensureDepsLabel: 'happy' });
 
     // Always patch iOS props if iOS was generated.
     if (platform === 'ios' || platform === 'all') {
       const fs = await import('node:fs/promises');
       const podPropsPath = `${uiDir}/ios/Podfile.properties.json`;
-      const pbxprojPath = `${uiDir}/ios/Happydev.xcodeproj/project.pbxproj`;
       try {
         const raw = await fs.readFile(podPropsPath, 'utf-8');
         const json = JSON.parse(raw);
@@ -196,14 +201,17 @@ async function main() {
         // ignore if path missing (platform != ios)
       }
 
-      try {
-        const raw = await fs.readFile(pbxprojPath, 'utf-8');
-        const next = raw.replaceAll('IPHONEOS_DEPLOYMENT_TARGET = 15.1;', 'IPHONEOS_DEPLOYMENT_TARGET = 16.0;');
-        if (next !== raw) {
-          await fs.writeFile(pbxprojPath, next, 'utf-8');
+      const iosProjects = await resolveIosAppXcodeProjects({ uiDir });
+      for (const project of iosProjects) {
+        try {
+          const raw = await fs.readFile(project.pbxprojPath, 'utf-8');
+          const next = raw.replaceAll('IPHONEOS_DEPLOYMENT_TARGET = 15.1;', 'IPHONEOS_DEPLOYMENT_TARGET = 16.0;');
+          if (next !== raw) {
+            await fs.writeFile(project.pbxprojPath, next, 'utf-8');
+          }
+        } catch {
+          // ignore missing/invalid pbxproj; Expo will surface actionable errors if needed
         }
-      } catch {
-        // ignore missing pbxproj (unexpected)
       }
 
       // Ensure CocoaPods doesn't crash due to locale issues.
@@ -264,25 +272,9 @@ async function main() {
       // xcodebuild fails with:
       //   "Automatic signing is disabled ... pass -allowProvisioningUpdates"
       //
-      // We force Expo CLI to go through its signing configuration path by clearing DEVELOPMENT_TEAM,
-      // so it will re-set the team and include the provisioning flags.
-      try {
-        const fs = await import('node:fs/promises');
-        const pbxprojPath = `${uiDir}/ios/Happydev.xcodeproj/project.pbxproj`;
-        const raw = await fs.readFile(pbxprojPath, 'utf-8');
-        let next = raw.replaceAll(/^\s*DEVELOPMENT_TEAM = ".*";\s*$/gm, '');
-        next = next.replaceAll(/PRODUCT_BUNDLE_IDENTIFIER = [^;]+;/g, `PRODUCT_BUNDLE_IDENTIFIER = ${iosBundleId};`);
-        if (iosAppName && iosAppName.trim()) {
-          const name = iosAppName.trim();
-          const quoted = name.includes(' ') || name.includes('"') ? `"${name.replaceAll('"', '\\"')}"` : name;
-          next = next.replaceAll(/PRODUCT_NAME = [^;]+;/g, `PRODUCT_NAME = ${quoted};`);
-        }
-        if (next !== raw) {
-          await fs.writeFile(pbxprojPath, next, 'utf-8');
-        }
-      } catch {
-        // ignore
-      }
+      // We force Expo CLI to go through its signing configuration path by clearing any pre-existing
+      // team/profile identifiers, so it will re-set the team and include the provisioning flags.
+      await patchIosXcodeProjectsForSigningAndIdentity({ uiDir, iosBundleId, iosAppName });
     }
 
     const configuration = kv.get('--configuration') ?? 'Debug';
@@ -293,47 +285,39 @@ async function main() {
     // Ensure CocoaPods doesn't crash due to locale issues.
     env.LANG = env.LANG ?? 'en_US.UTF-8';
     env.LC_ALL = env.LC_ALL ?? 'en_US.UTF-8';
-    await pmExecBin({ dir: uiDir, bin: 'expo', args, env });
+    await expoExec({ dir: uiDir, args, env, ensureDepsLabel: 'happy' });
   }
 
   if (!shouldStartMetro) {
     return;
   }
 
-  const running = await isStateProcessRunning(mobilePaths.statePath);
-  if (!restart && running.running) {
-    // eslint-disable-next-line no-console
-    console.log(`[mobile] Metro already running for this stack/worktree (pid=${running.state.pid}, port=${running.state.port})`);
-    return;
-  }
-  if (restart && running.state?.pid) {
-    const prevPid = Number(running.state.pid);
-    const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || autostart.stackName;
-    const envPath = (process.env.HAPPY_STACKS_ENV_FILE ?? process.env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
-    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-mobile', json: true });
-    if (!res.killed) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[mobile] not stopping existing Metro pid=${prevPid} because it does not look stack-owned.\n` +
-          `[mobile] continuing by starting a new Metro on a free port.`
-      );
-    }
-  }
-
-  const requestedPort = Number.parseInt(String(portRaw), 10);
-  const startPort = Number.isFinite(requestedPort) && requestedPort > 0 ? requestedPort : 8081;
-  const portNumber = await pickNextFreeTcpPort(startPort);
-  env.RCT_METRO_PORT = String(portNumber);
+  // Unify Expo: one Expo dev server per stack/worktree. If dev mode already started Expo, we reuse it.
+  // If Expo is already running without dev-client enabled, we fail closed (no second Expo).
+  env.HAPPY_STACKS_EXPO_HOST = host;
+  env.HAPPY_LOCAL_EXPO_HOST = host;
+  env.HAPPY_STACKS_MOBILE_HOST = host;
+  env.HAPPY_LOCAL_MOBILE_HOST = host;
+  env.HAPPY_STACKS_MOBILE_SCHEME = scheme;
+  env.HAPPY_LOCAL_MOBILE_SCHEME = scheme;
+  env.HAPPY_STACKS_EXPO_DEV_PORT = String(portRaw);
+  env.HAPPY_LOCAL_EXPO_DEV_PORT = String(portRaw);
 
-  // Start Metro for a dev client.
-  // The critical part is --scheme: without it, Expo defaults to `exp+<slug>` (here `exp+happy`)
-  // which the App Store app also registers, so iOS can open the wrong app.
-  const args = ['start', '--dev-client', '--host', host, '--port', String(portNumber), '--scheme', scheme];
-  if (wantsExpoClearCache({ env })) {
-    args.push('--clear');
-  }
-  const child = await pmSpawnBin({ label: 'mobile', dir: uiDir, bin: 'expo', args, env });
-  await writePidState(mobilePaths.statePath, { pid: child.pid, port: portNumber, uiDir, startedAt: new Date().toISOString() });
+  const children = [];
+  await ensureDevExpoServer({
+    startUi: false,
+    startMobile: true,
+    uiDir,
+    autostart,
+    baseEnv: env,
+    apiServerUrl: env.EXPO_PUBLIC_HAPPY_SERVER_URL ?? '',
+    restart,
+    stackMode,
+    runtimeStatePath,
+    stackName,
+    envPath,
+    children,
+  });
 
   await new Promise(() => {});
 }

package/scripts/mobile_dev_client.mjs

@@ -0,0 +1,83 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { getRootDir } from './utils/paths/paths.mjs';
+import { join } from 'node:path';
+
+import { defaultDevClientIdentity } from './utils/mobile/identifiers.mjs';
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags }) || flags.has('--help') || argv.length === 0) {
+    printResult({
+      json,
+      data: {
+        flags: ['--device=<id-or-name>', '--clean', '--configuration=Debug|Release', '--json'],
+      },
+      text: [
+        '[mobile-dev-client] usage:',
+        '  happys mobile-dev-client --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
+        '',
+        'Notes:',
+        '- Installs a dedicated "Happy Stacks Dev" Expo dev-client app on your iPhone.',
+        '- This app is intended to be reused across stacks (no per-stack installs for dev-client).',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  if (!flags.has('--install')) {
+    printResult({
+      json,
+      data: { ok: false, error: 'missing_install_flag' },
+      text: '[mobile-dev-client] missing --install. Run: happys mobile-dev-client --help',
+    });
+    process.exit(1);
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const mobileScript = join(rootDir, 'scripts', 'mobile.mjs');
+
+  const device = kv.get('--device') ?? '';
+  const clean = flags.has('--clean');
+  const configuration = kv.get('--configuration') ?? 'Debug';
+
+  const id = defaultDevClientIdentity({ user: process.env.USER ?? process.env.USERNAME ?? 'user' });
+
+  const args = [
+    mobileScript,
+    '--app-env=development',
+    `--ios-app-name=${id.iosAppName}`,
+    `--ios-bundle-id=${id.iosBundleId}`,
+    `--scheme=${id.scheme}`,
+    '--prebuild',
+    ...(clean ? ['--clean'] : []),
+    '--run-ios',
+    `--configuration=${configuration}`,
+    '--no-metro',
+    ...(device ? [`--device=${device}`] : []),
+  ];
+
+  const env = {
+    ...process.env,
+    // Ensure Expo app config uses the dev-client scheme.
+    EXPO_APP_SCHEME: id.scheme,
+    // Ensure per-stack storage isolation is available during dev-client usage.
+    EXPO_PUBLIC_HAPPY_STORAGE_SCOPE: process.env.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE ?? '',
+  };
+
+  const out = await run(process.execPath, args, { cwd: rootDir, env });
+  if (json) {
+    printResult({ json, data: { ok: true, installed: true, identity: id, out } });
+  }
+}
+
+main().catch((err) => {
+  console.error('[mobile-dev-client] failed:', err);
+  process.exit(1);
+});
+

package/scripts/provision/linux-ubuntu-review-pr.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Provision a fresh Ubuntu VM for running happy-local's `review-pr` end-to-end.
+# Intended for Apple Silicon users running Ubuntu ARM64 via Lima/UTM.
+#
+# This installs:
+# - Node (via nvm)
+# - corepack (yarn/pnpm shims)
+# - basic build tooling for native deps used by Expo/React Native ecosystem
+
+if [[ "$(uname -s)" != "Linux" ]]; then
+  echo "[provision] expected Linux; got: $(uname -s)" >&2
+  exit 1
+fi
+
+export DEBIAN_FRONTEND=noninteractive
+
+echo "[provision] installing apt dependencies..."
+sudo apt-get update -y
+sudo apt-get install -y \
+  ca-certificates \
+  curl \
+  git \
+  build-essential \
+  python3 \
+  pkg-config
+
+echo "[provision] installing nvm + Node..."
+export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+if [[ ! -s "$NVM_DIR/nvm.sh" ]]; then
+  mkdir -p "$NVM_DIR"
+  curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+fi
+
+# shellcheck disable=SC1090
+source "$NVM_DIR/nvm.sh"
+
+# Use a modern Node; match the repo's expectations if it ever adds .nvmrc.
+NODE_VERSION="${NODE_VERSION:-22}"
+nvm install "$NODE_VERSION"
+nvm use "$NODE_VERSION"
+
+echo "[provision] enabling corepack..."
+corepack enable >/dev/null 2>&1 || true
+
+echo "[provision] done."
+echo "[provision] Node: $(node --version)"
+echo "[provision] npm:  $(npm --version)"
+echo "[provision] git:  $(git --version)"
+

package/scripts/review.mjs

@@ -0,0 +1,217 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
+import { assertCliPrereqs } from './utils/cli/prereqs.mjs';
+import { resolveBaseRef } from './utils/review/base_ref.mjs';
+import { isStackMode, resolveDefaultStackReviewComponents } from './utils/review/targets.mjs';
+import { runWithConcurrencyLimit } from './utils/proc/parallel.mjs';
+import { runCodeRabbitReview } from './utils/review/runners/coderabbit.mjs';
+import { extractCodexReviewFromJsonl, runCodexReview } from './utils/review/runners/codex.mjs';
+
+const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
+const VALID_COMPONENTS = DEFAULT_COMPONENTS;
+const VALID_REVIEWERS = ['coderabbit', 'codex'];
+
+function parseCsv(raw) {
+  return String(raw ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function normalizeReviewers(list) {
+  const raw = Array.isArray(list) ? list : [];
+  const lower = raw.map((r) => String(r).trim().toLowerCase()).filter(Boolean);
+  const uniq = Array.from(new Set(lower));
+  return uniq.length ? uniq : ['coderabbit'];
+}
+
+function usage() {
+  return [
+    '[review] usage:',
+    '  happys review [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--concurrency=N] [--json]',
+    '',
+    'components:',
+    `  ${VALID_COMPONENTS.join(' | ')}`,
+    '',
+    'reviewers:',
+    `  ${VALID_REVIEWERS.join(' | ')}`,
+    '',
+    'notes:',
+    '- If run from inside a component checkout/worktree and no components are provided, defaults to that component.',
+    '- In stack mode (invoked via `happys stack review <stack>`), if no components are provided, defaults to stack-pinned non-default components only.',
+    '',
+    'examples:',
+    '  happys review',
+    '  happys review happy-cli --reviewers=coderabbit,codex',
+    '  happys stack review exp1 --reviewers=codex',
+    '  happys review happy --base-remote=upstream --base-branch=main',
+  ].join('\n');
+}
+
+function resolveComponentFromCwdOrNull({ rootDir, invokedCwd }) {
+  return inferComponentFromCwd({ rootDir, invokedCwd, components: DEFAULT_COMPONENTS });
+}
+
+function stackRemoteFallbackFromEnv(env) {
+  return String(env.HAPPY_STACKS_STACK_REMOTE ?? env.HAPPY_LOCAL_STACK_REMOTE ?? '').trim();
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({ json, data: { usage: usage() }, text: usage() });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const invokedCwd = getInvokedCwd(process.env);
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+
+  const reviewers = normalizeReviewers(parseCsv(kv.get('--reviewers') ?? ''));
+  for (const r of reviewers) {
+    if (!VALID_REVIEWERS.includes(r)) {
+      throw new Error(`[review] unknown reviewer: ${r} (expected one of: ${VALID_REVIEWERS.join(', ')})`);
+    }
+  }
+
+  await assertCliPrereqs({
+    git: true,
+    coderabbit: reviewers.includes('coderabbit'),
+    codex: reviewers.includes('codex'),
+  });
+
+  const inferred = positionals.length === 0 ? resolveComponentFromCwdOrNull({ rootDir, invokedCwd }) : null;
+  if (inferred) {
+    // Make downstream getComponentDir() resolve to the inferred repo dir for this run.
+    process.env[`HAPPY_STACKS_COMPONENT_DIR_${inferred.component.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`] = inferred.repoDir;
+  }
+
+  const inStackMode = isStackMode(process.env);
+  const requestedComponents = positionals.length ? positionals : inferred ? [inferred.component] : ['all'];
+  const wantAll = requestedComponents.includes('all');
+
+  let components = wantAll ? DEFAULT_COMPONENTS : requestedComponents;
+  if (!positionals.length && !inferred && inStackMode) {
+    const pinned = resolveDefaultStackReviewComponents({ rootDir, components: DEFAULT_COMPONENTS });
+    components = pinned.length ? pinned : [];
+  }
+
+  for (const c of components) {
+    if (!VALID_COMPONENTS.includes(c)) {
+      throw new Error(`[review] unknown component: ${c} (expected one of: ${VALID_COMPONENTS.join(', ')})`);
+    }
+  }
+
+  if (!components.length) {
+    const msg = inStackMode ? '[review] no non-default stack-pinned components to review' : '[review] no components selected';
+    printResult({ json, data: { ok: true, skipped: true, reason: msg }, text: msg });
+    return;
+  }
+
+  const baseRefOverride = (kv.get('--base-ref') ?? '').trim();
+  const baseRemoteOverride = (kv.get('--base-remote') ?? '').trim();
+  const baseBranchOverride = (kv.get('--base-branch') ?? '').trim();
+  const stackRemoteFallback = stackRemoteFallbackFromEnv(process.env);
+  const concurrency = (kv.get('--concurrency') ?? '').trim();
+  const limit = concurrency ? Number(concurrency) : 4;
+
+  const jobs = [];
+  for (const component of components) {
+    const repoDir = getComponentDir(rootDir, component);
+    jobs.push({ component, repoDir });
+  }
+
+  const jobResults = await runWithConcurrencyLimit({
+    items: jobs,
+    limit,
+    fn: async (job) => {
+      const { component, repoDir } = job;
+      const base = await resolveBaseRef({
+        cwd: repoDir,
+        baseRefOverride,
+        baseRemoteOverride,
+        baseBranchOverride,
+        stackRemoteFallback,
+      });
+
+      const perReviewer = await Promise.all(
+        reviewers.map(async (reviewer) => {
+          if (reviewer === 'coderabbit') {
+            const res = await runCodeRabbitReview({ repoDir, baseRef: base.baseRef, env: process.env });
+            return {
+              reviewer,
+              ok: Boolean(res.ok),
+              exitCode: res.exitCode,
+              signal: res.signal,
+              durationMs: res.durationMs,
+              stdout: res.stdout ?? '',
+              stderr: res.stderr ?? '',
+            };
+          }
+          if (reviewer === 'codex') {
+            const res = await runCodexReview({ repoDir, baseRef: base.baseRef, env: process.env, jsonMode: true });
+            const extracted = extractCodexReviewFromJsonl(res.stdout ?? '');
+            return {
+              reviewer,
+              ok: Boolean(res.ok),
+              exitCode: res.exitCode,
+              signal: res.signal,
+              durationMs: res.durationMs,
+              stdout: res.stdout ?? '',
+              stderr: res.stderr ?? '',
+              review_output: extracted,
+            };
+          }
+          return { reviewer, ok: false, exitCode: null, signal: null, durationMs: 0, stdout: '', stderr: 'unknown reviewer\n' };
+        })
+      );
+
+      return { component, repoDir, base, results: perReviewer };
+    },
+  });
+
+  const ok = jobResults.every((r) => r.results.every((x) => x.ok));
+  if (json) {
+    printResult({ json, data: { ok, reviewers, components, results: jobResults } });
+    if (!ok) process.exit(1);
+    return;
+  }
+
+  const lines = [];
+  lines.push('[review] results:');
+  for (const r of jobResults) {
+    lines.push('============================================================================');
+    lines.push(`component: ${r.component}`);
+    lines.push(`dir: ${r.repoDir}`);
+    lines.push(`baseRef: ${r.base.baseRef}`);
+    for (const rr of r.results) {
+      lines.push('');
+      const status = rr.ok ? '✅ ok' : '❌ failed';
+      lines.push(`[${rr.reviewer}] ${status} (exit=${rr.exitCode ?? 'null'} durMs=${rr.durationMs ?? '?'})`);
+      if (rr.stderr) {
+        lines.push('--- stderr ---');
+        lines.push(String(rr.stderr).trimEnd());
+      }
+      if (rr.stdout) {
+        lines.push('--- stdout ---');
+        lines.push(String(rr.stdout).trimEnd());
+      }
+    }
+    lines.push('');
+  }
+  lines.push(ok ? '[review] ok' : '[review] failed');
+  printResult({ json: false, text: lines.join('\n') });
+  if (!ok) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('[review] failed:', err);
+  process.exit(1);
+});
+