happy-stacks 0.3.0 → 0.4.0

package/scripts/utils/paths/paths.mjs

@@ -26,8 +26,8 @@ export function getHappyStacksHomeDir(env = process.env) {
   return PRIMARY_HOME_DIR;
 }
 
-export function getWorkspaceDir(cliRootDir = null) {
-  const fromEnv = (process.env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
+export function getWorkspaceDir(cliRootDir = null, env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
   if (fromEnv) {
     return expandHome(fromEnv);
   }
@@ -41,8 +41,8 @@ export function getWorkspaceDir(cliRootDir = null) {
   return cliRootDir ? cliRootDir : defaultWorkspace;
 }
 
-export function getComponentsDir(rootDir) {
-  const workspaceDir = getWorkspaceDir(rootDir);
+export function getComponentsDir(rootDir, env = process.env) {
+  const workspaceDir = getWorkspaceDir(rootDir, env);
   return join(workspaceDir, 'components');
 }
 
@@ -50,46 +50,48 @@ export function componentDirEnvKey(name) {
   return `HAPPY_STACKS_COMPONENT_DIR_${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
 }
 
-function normalizePathForEnv(rootDir, raw) {
+function normalizePathForEnv(rootDir, raw, env = process.env) {
   const trimmed = (raw ?? '').trim();
   if (!trimmed) {
     return '';
   }
   const expanded = expandHome(trimmed);
   // If the path is relative, treat it as relative to the workspace root (default: repo root).
-  const workspaceDir = getWorkspaceDir(rootDir);
+  const workspaceDir = getWorkspaceDir(rootDir, env);
   return expanded.startsWith('/') ? expanded : resolve(workspaceDir, expanded);
 }
 
-export function getComponentDir(rootDir, name) {
+export function getComponentDir(rootDir, name, env = process.env) {
   const stacksKey = componentDirEnvKey(name);
   const legacyKey = stacksKey.replace(/^HAPPY_STACKS_/, 'HAPPY_LOCAL_');
-  const fromEnv = normalizePathForEnv(rootDir, process.env[stacksKey] ?? process.env[legacyKey]);
+  const fromEnv = normalizePathForEnv(rootDir, env[stacksKey] ?? env[legacyKey], env);
   if (fromEnv) {
     return fromEnv;
   }
-  return join(getComponentsDir(rootDir), name);
+  return join(getComponentsDir(rootDir, env), name);
 }
 
-export function getStackName() {
-  const raw = process.env.HAPPY_STACKS_STACK?.trim()
-    ? process.env.HAPPY_STACKS_STACK.trim()
-    : process.env.HAPPY_LOCAL_STACK?.trim()
-      ? process.env.HAPPY_LOCAL_STACK.trim()
+export function getStackName(env = process.env) {
+  const raw = env.HAPPY_STACKS_STACK?.trim()
+    ? env.HAPPY_STACKS_STACK.trim()
+    : env.HAPPY_LOCAL_STACK?.trim()
+      ? env.HAPPY_LOCAL_STACK.trim()
       : '';
   return raw || 'main';
 }
 
-export function getStackLabel(stackName = getStackName()) {
-  return stackName === 'main' ? PRIMARY_LABEL_BASE : `${PRIMARY_LABEL_BASE}.${stackName}`;
+export function getStackLabel(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  return name === 'main' ? PRIMARY_LABEL_BASE : `${PRIMARY_LABEL_BASE}.${name}`;
 }
 
-export function getLegacyStackLabel(stackName = getStackName()) {
-  return stackName === 'main' ? LEGACY_LABEL_BASE : `${LEGACY_LABEL_BASE}.${stackName}`;
+export function getLegacyStackLabel(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  return name === 'main' ? LEGACY_LABEL_BASE : `${LEGACY_LABEL_BASE}.${name}`;
 }
 
-export function getStacksStorageRoot() {
-  const fromEnv = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
+export function getStacksStorageRoot(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_STORAGE_DIR ?? env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
   if (fromEnv) {
     return expandHome(fromEnv);
   }
@@ -100,19 +102,20 @@ export function getLegacyStorageRoot() {
   return LEGACY_STORAGE_ROOT;
 }
 
-export function resolveStackBaseDir(stackName = getStackName()) {
-  const preferredRoot = getStacksStorageRoot();
-  const newBase = join(preferredRoot, stackName);
-  const legacyBase = stackName === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', stackName);
+export function resolveStackBaseDir(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  const preferredRoot = getStacksStorageRoot(env);
+  const newBase = join(preferredRoot, name);
+  const legacyBase = name === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', name);
   const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   // Prefer the new layout by default.
   //
   // For non-main stacks, keep legacy layout if the legacy env exists and the new env does not.
   // This avoids breaking existing stacks until `happys stack migrate` is run.
-  if (allowLegacy && stackName !== 'main') {
-    const newEnv = join(preferredRoot, stackName, 'env');
-    const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  if (allowLegacy && name !== 'main') {
+    const newEnv = join(preferredRoot, name, 'env');
+    const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', name, 'env');
     if (!existsSync(newEnv) && existsSync(legacyEnv)) {
       return { baseDir: legacyBase, isLegacy: true };
     }
@@ -121,30 +124,31 @@ export function resolveStackBaseDir(stackName = getStackName()) {
   return { baseDir: newBase, isLegacy: false };
 }
 
-export function resolveStackEnvPath(stackName = getStackName()) {
-  const { baseDir: activeBase, isLegacy } = resolveStackBaseDir(stackName);
+export function resolveStackEnvPath(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  const { baseDir: activeBase, isLegacy } = resolveStackBaseDir(name, env);
   // New layout: ~/.happy/stacks/<name>/env
-  const newEnv = join(getStacksStorageRoot(), stackName, 'env');
+  const newEnv = join(getStacksStorageRoot(env), name, 'env');
   // Legacy layout: ~/.happy/local/stacks/<name>/env
-  const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', name, 'env');
   const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   if (existsSync(newEnv)) {
-    return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(), stackName) };
+    return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(env), name) };
   }
   if (allowLegacy && existsSync(legacyEnv)) {
-    return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', stackName) };
+    return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', name) };
   }
   return { envPath: newEnv, isLegacy, baseDir: activeBase };
 }
 
-export function getDefaultAutostartPaths() {
-  const stackName = getStackName();
-  const { baseDir, isLegacy } = resolveStackBaseDir(stackName);
+export function getDefaultAutostartPaths(env = process.env) {
+  const stackName = getStackName(env);
+  const { baseDir, isLegacy } = resolveStackBaseDir(stackName, env);
   const logsDir = join(baseDir, 'logs');
 
-  const primaryLabel = getStackLabel(stackName);
-  const legacyLabel = getLegacyStackLabel(stackName);
+  const primaryLabel = getStackLabel(stackName, env);
+  const legacyLabel = getLegacyStackLabel(stackName, env);
   const primaryPlistPath = join(homedir(), 'Library', 'LaunchAgents', `${primaryLabel}.plist`);
   const legacyPlistPath = join(homedir(), 'Library', 'LaunchAgents', `${legacyLabel}.plist`);
 

package/scripts/utils/proc/parallel.mjs

@@ -0,0 +1,25 @@
+export async function runWithConcurrencyLimit({ items, limit, fn }) {
+  const list = Array.isArray(items) ? items : [];
+  const max = Number(limit);
+  const concurrency = Number.isFinite(max) && max > 0 ? Math.floor(max) : 4;
+
+  const results = new Array(list.length);
+  let nextIndex = 0;
+
+  const worker = async () => {
+    while (true) {
+      const i = nextIndex;
+      nextIndex += 1;
+      if (i >= list.length) return;
+      results[i] = await fn(list[i], i);
+    }
+  };
+
+  const workers = [];
+  for (let i = 0; i < Math.min(concurrency, list.length); i++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+

package/scripts/utils/proc/pm.mjs

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { existsSync } from 'node:fs';
-import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 
 import { pathExists } from '../fs/fs.mjs';
@@ -113,14 +113,37 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
       }
     };
 
+    const patchesMtimeMs = async () => {
+      // Happy's mobile app (and some other repos) use patch-package and keep patches under `patches/`.
+      // If a patch file changes but yarn.lock/package.json do not, Yarn won't reinstall and
+      // patch-package won't re-apply the patch, leading to confusing "why isn't my patch wired?"
+      // failures later (e.g. during iOS pod install).
+      const patchesDir = join(dir, 'patches');
+      if (!(await pathExists(patchesDir))) return 0;
+      try {
+        const entries = await readdir(patchesDir, { withFileTypes: true });
+        let max = 0;
+        for (const e of entries) {
+          if (!e.isFile()) continue;
+          if (!e.name.endsWith('.patch')) continue;
+          const m = await mtimeMs(join(patchesDir, e.name));
+          if (m > max) max = m;
+        }
+        return max;
+      } catch {
+        return 0;
+      }
+    };
+
     if (pm.name === 'yarn' && (await pathExists(yarnLock))) {
       const lockM = await mtimeMs(yarnLock);
       const pkgM = await mtimeMs(pkgJson);
       const intM = await mtimeMs(yarnIntegrity);
-      if (!intM || lockM > intM || pkgM > intM) {
+      const patchM = await patchesMtimeMs();
+      if (!intM || lockM > intM || pkgM > intM || patchM > intM) {
         if (!quiet) {
           // eslint-disable-next-line no-console
-          console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
+          console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json/patches changed)...`);
         }
         await run(pm.cmd, ['install'], { cwd: dir, stdio });
       }
@@ -161,14 +184,20 @@ export async function ensureCliBuilt(cliDir, { buildCli }) {
   // - HAPPY_STACKS_CLI_BUILD=0 (legacy: HAPPY_LOCAL_CLI_BUILD=0)
   const modeRaw = (process.env.HAPPY_STACKS_CLI_BUILD_MODE ?? process.env.HAPPY_LOCAL_CLI_BUILD_MODE ?? 'auto').trim().toLowerCase();
   const mode = modeRaw === 'always' || modeRaw === 'auto' || modeRaw === 'never' ? modeRaw : 'auto';
-  if (mode === 'never') {
-    return { built: false, reason: 'mode_never' };
-  }
   const distEntrypoint = join(cliDir, 'dist', 'index.mjs');
   const buildStatePath = resolveBuildStatePath({ label: 'happy-cli', dir: cliDir });
   const gitSig = await computeGitWorktreeSignature(cliDir);
   const prev = await readJsonIfExists(buildStatePath);
 
+  // "never" should prevent rebuild churn, but it must not make the stack unrunnable.
+  // If the dist entrypoint is missing, build once even in "never" mode.
+  if (mode === 'never') {
+    if (await pathExists(distEntrypoint)) {
+      return { built: false, reason: 'mode_never' };
+    }
+    // fallthrough to build
+  }
+
   if (mode === 'auto') {
     // If dist doesn't exist, we must build.
     if (!(await pathExists(distEntrypoint))) {
@@ -186,6 +215,18 @@ export async function ensureCliBuilt(cliDir, { buildCli }) {
   const pm = await getComponentPm(cliDir);
   await run(pm.cmd, ['build'], { cwd: cliDir });
 
+  // Sanity check: happy-cli daemon entrypoint must exist after a successful build.
+  // Without this, watch-based rebuilds can restart the daemon into a MODULE_NOT_FOUND crash,
+  // which looks like the UI "dies out of nowhere" even though the root cause is missing build output.
+  if (!(await pathExists(distEntrypoint))) {
+    throw new Error(
+      `[local] happy-cli build finished but did not produce expected entrypoint.\n` +
+        `Expected: ${distEntrypoint}\n` +
+        `Fix: run the component build directly and inspect its output:\n` +
+        `  cd "${cliDir}" && ${pm.cmd} build`
+    );
+  }
+
   // Persist new build state (best-effort).
   const nowSig = gitSig ?? (await computeGitWorktreeSignature(cliDir));
   if (nowSig) {
@@ -301,17 +342,33 @@ export async function pmExecBin(dirOrOpts, binArg, argsArg, optsArg) {
 }
 
 export async function pmSpawnBin(dir, label, bin, args, { env = process.env } = {}) {
-  const pm = await getComponentPm(dir);
+  const usesObjectStyle = typeof dir === 'object' && dir !== null;
+  const componentDir = usesObjectStyle ? dir.dir : dir;
+  const componentLabel = usesObjectStyle ? dir.label : label;
+  const componentBin = usesObjectStyle ? dir.bin : bin;
+  const componentArgs = usesObjectStyle ? (dir.args ?? []) : (args ?? []);
+  const componentEnv = usesObjectStyle ? (dir.env ?? process.env) : (env ?? process.env);
+  const options = usesObjectStyle ? (dir.options ?? {}) : {};
+
+  const pm = await getComponentPm(componentDir);
   if (pm.name === 'yarn') {
-    return spawnProc(label, pm.cmd, ['run', bin, ...args], env, { cwd: dir });
+    return spawnProc(componentLabel, pm.cmd, ['run', componentBin, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
   }
-  return spawnProc(label, pm.cmd, ['exec', bin, ...args], env, { cwd: dir });
+  return spawnProc(componentLabel, pm.cmd, ['exec', componentBin, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
 }
 
 export async function pmSpawnScript(dir, label, script, args, { env = process.env } = {}) {
-  const pm = await getComponentPm(dir);
+  const usesObjectStyle = typeof dir === 'object' && dir !== null;
+  const componentDir = usesObjectStyle ? dir.dir : dir;
+  const componentLabel = usesObjectStyle ? dir.label : label;
+  const componentScript = usesObjectStyle ? dir.script : script;
+  const componentArgs = usesObjectStyle ? (dir.args ?? []) : (args ?? []);
+  const componentEnv = usesObjectStyle ? (dir.env ?? process.env) : (env ?? process.env);
+  const options = usesObjectStyle ? (dir.options ?? {}) : {};
+
+  const pm = await getComponentPm(componentDir);
   if (pm.name === 'yarn') {
-    return spawnProc(label, pm.cmd, ['run', script, ...args], env, { cwd: dir });
+    return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
   }
-  return spawnProc(label, pm.cmd, ['run', script, ...args], env, { cwd: dir });
+  return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
 }

package/scripts/utils/proc/proc.mjs

@@ -1,13 +1,27 @@
 import { spawn } from 'node:child_process';
 
+function nextLineBreakIndex(s) {
+  const n = s.indexOf('\n');
+  const r = s.indexOf('\r');
+  if (n < 0) return r;
+  if (r < 0) return n;
+  return Math.min(n, r);
+}
+
+function consumeLineBreak(buf) {
+  if (buf.startsWith('\r\n')) return buf.slice(2);
+  if (buf.startsWith('\n') || buf.startsWith('\r')) return buf.slice(1);
+  return buf;
+}
+
 function writeWithPrefix(stream, prefix, bufState, chunk) {
   const s = chunk.toString();
   bufState.buf += s;
   while (true) {
-    const idx = bufState.buf.indexOf('\n');
+    const idx = nextLineBreakIndex(bufState.buf);
     if (idx < 0) break;
     const line = bufState.buf.slice(0, idx);
-    bufState.buf = bufState.buf.slice(idx + 1);
+    bufState.buf = consumeLineBreak(bufState.buf.slice(idx));
     stream.write(`${prefix}${line}\n`);
   }
 }
@@ -133,3 +147,63 @@ export async function runCapture(cmd, args, options = {}) {
   });
 }
 
+export async function runCaptureResult(cmd, args, options = {}) {
+  const { timeoutMs, ...spawnOptions } = options ?? {};
+  const startedAt = Date.now();
+  return await new Promise((resolvePromise) => {
+    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false, ...spawnOptions });
+    let out = '';
+    let err = '';
+    const t =
+      Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? setTimeout(() => {
+            try {
+              proc.kill('SIGKILL');
+            } catch {
+              // ignore
+            }
+            resolvePromise({
+              ok: false,
+              exitCode: null,
+              signal: null,
+              out,
+              err,
+              timedOut: true,
+              startedAt,
+              finishedAt: Date.now(),
+              durationMs: Date.now() - startedAt,
+            });
+          }, timeoutMs)
+        : null;
+    proc.stdout?.on('data', (d) => (out += d.toString()));
+    proc.stderr?.on('data', (d) => (err += d.toString()));
+    proc.on('error', (e) => {
+      if (t) clearTimeout(t);
+      resolvePromise({
+        ok: false,
+        exitCode: null,
+        signal: null,
+        out,
+        err: err + (err.endsWith('\n') || !err ? '' : '\n') + String(e) + '\n',
+        timedOut: false,
+        startedAt,
+        finishedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+      });
+    });
+    proc.on('close', (code, signal) => {
+      if (t) clearTimeout(t);
+      resolvePromise({
+        ok: code === 0,
+        exitCode: code,
+        signal: signal ?? null,
+        out,
+        err,
+        timedOut: false,
+        startedAt,
+        finishedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+      });
+    });
+  });
+}

package/scripts/utils/review/base_ref.mjs

@@ -0,0 +1,74 @@
+import { inferRemoteNameForOwner, parseGithubOwner } from '../git/worktrees.mjs';
+import { gitCapture, gitOk, normalizeRemoteName, resolveRemoteDefaultBranch, ensureRemoteRefAvailable } from '../git/git.mjs';
+
+async function currentBranchName({ cwd }) {
+  const branch = (await gitCapture({ cwd, args: ['branch', '--show-current'] }).catch(() => '')).trim();
+  return branch;
+}
+
+function branchOwnerPrefix(branch) {
+  const b = String(branch ?? '').trim();
+  if (!b || !b.includes('/')) return '';
+  return b.split('/')[0] ?? '';
+}
+
+async function inferRemoteFromBranchOwner({ cwd }) {
+  const branch = await currentBranchName({ cwd });
+  const owner = branchOwnerPrefix(branch);
+  if (!owner) return '';
+
+  // Confirm this "owner" is plausible (matches at least one remote's GitHub owner).
+  for (const remoteName of ['upstream', 'origin', 'fork']) {
+    try {
+      const url = (await gitCapture({ cwd, args: ['remote', 'get-url', remoteName] })).trim();
+      const parsedOwner = parseGithubOwner(url);
+      if (parsedOwner && parsedOwner === owner) {
+        return remoteName;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Fall back to the generic inference helper (it checks remotes in priority order).
+  return await inferRemoteNameForOwner({ repoDir: cwd, owner });
+}
+
+export async function resolveBaseRef({
+  cwd,
+  baseRefOverride = '',
+  baseRemoteOverride = '',
+  baseBranchOverride = '',
+  stackRemoteFallback = '',
+} = {}) {
+  const repoDir = String(cwd ?? '').trim();
+  if (!repoDir) {
+    throw new Error('[review] missing cwd for base resolution');
+  }
+
+  if (!(await gitOk({ cwd: repoDir, args: ['rev-parse', '--is-inside-work-tree'] }))) {
+    throw new Error(`[review] not a git repository: ${repoDir}`);
+  }
+
+  const explicitRef = String(baseRefOverride ?? '').trim();
+  if (explicitRef) {
+    return { baseRef: explicitRef, remote: '', branch: '' };
+  }
+
+  const stackFallback = String(stackRemoteFallback ?? '').trim();
+  const inferredRemote = await inferRemoteFromBranchOwner({ cwd: repoDir });
+  const rawRemote = String(baseRemoteOverride ?? '').trim() || inferredRemote || stackFallback || 'upstream';
+  const remote = await normalizeRemoteName({ cwd: repoDir, remote: rawRemote });
+
+  const branch = String(baseBranchOverride ?? '').trim() || (await resolveRemoteDefaultBranch({ cwd: repoDir, remote }));
+  const ok = await ensureRemoteRefAvailable({ cwd: repoDir, remote, branch });
+  if (!ok) {
+    throw new Error(
+      `[review] unable to resolve base ref refs/remotes/${remote}/${branch} in ${repoDir}\n` +
+        `[review] hint: ensure remote "${remote}" exists and has a configured HEAD/default branch (or pass --base-ref).`
+    );
+  }
+
+  return { baseRef: `${remote}/${branch}`, remote, branch };
+}
+

package/scripts/utils/review/base_ref.test.mjs

@@ -0,0 +1,54 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCapture } from '../proc/proc.mjs';
+import { resolveBaseRef } from './base_ref.mjs';
+
+async function runGit(cwd, args) {
+  await runCapture('git', args, { cwd });
+}
+
+async function makeRepoWithRemoteHead() {
+  const root = await mkdtemp(join(tmpdir(), 'hs-review-base-ref-'));
+  const remote = join(root, 'remote.git');
+  const local = join(root, 'local');
+
+  await runGit(root, ['init', '--bare', remote]);
+  await runGit(root, ['init', '-b', 'main', local]);
+  await runGit(local, ['config', 'user.email', 'test@example.com']);
+  await runGit(local, ['config', 'user.name', 'Test User']);
+  await writeFile(join(local, 'file.txt'), 'hello\n', 'utf-8');
+  await runGit(local, ['add', '.']);
+  await runGit(local, ['commit', '-m', 'initial']);
+  await runGit(local, ['remote', 'add', 'upstream', remote]);
+  await runGit(local, ['push', '-u', 'upstream', 'main']);
+  // Ensure refs/remotes/upstream/HEAD exists.
+  await runGit(local, ['remote', 'set-head', 'upstream', '--auto']);
+
+  return { root, local };
+}
+
+test('resolveBaseRef uses explicit --base-ref override', async () => {
+  const { root, local } = await makeRepoWithRemoteHead();
+  try {
+    const res = await resolveBaseRef({ cwd: local, baseRefOverride: 'upstream/main' });
+    assert.equal(res.baseRef, 'upstream/main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolveBaseRef infers default branch from refs/remotes/<remote>/HEAD', async () => {
+  const { root, local } = await makeRepoWithRemoteHead();
+  try {
+    const res = await resolveBaseRef({ cwd: local, baseRemoteOverride: 'upstream' });
+    assert.equal(res.baseRef, 'upstream/main');
+    assert.equal(res.remote, 'upstream');
+    assert.equal(res.branch, 'main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+

package/scripts/utils/review/runners/coderabbit.mjs

@@ -0,0 +1,19 @@
+import { runCaptureResult } from '../../proc/proc.mjs';
+
+export async function runCodeRabbitReview({ repoDir, baseRef, env }) {
+  const args = [
+    'review',
+    '--plain',
+    '--no-color',
+    '--type',
+    'all',
+    '--cwd',
+    repoDir,
+  ];
+  if (baseRef) {
+    args.push('--base', baseRef);
+  }
+  const res = await runCaptureResult('coderabbit', args, { cwd: repoDir, env });
+  return { ...res, stdout: res.out, stderr: res.err };
+}
+

package/scripts/utils/review/runners/codex.mjs

@@ -0,0 +1,51 @@
+import { runCaptureResult } from '../../proc/proc.mjs';
+
+export function extractCodexReviewFromJsonl(jsonlText) {
+  const lines = String(jsonlText ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+
+  // JSONL events typically look like: { "type": "...", "payload": {...} } or similar.
+  // We keep this resilient by searching for keys matching the exec output format.
+  for (const line of lines) {
+    let obj = null;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const msg = obj?.msg ?? obj?.payload ?? obj;
+    // We’ve observed EventMsg names like "ExitedReviewMode" in Codex protocol events.
+    // Accept several shapes:
+    // - { msg: { ExitedReviewMode: { review_output: {...} } } }
+    // - { type: "ExitedReviewMode", review_output: {...} }
+    const exited =
+      msg?.ExitedReviewMode ??
+      (obj?.type === 'ExitedReviewMode' ? obj : null) ??
+      (msg?.type === 'ExitedReviewMode' ? msg : null);
+
+    const reviewOutput = exited?.review_output ?? exited?.reviewOutput ?? null;
+    if (reviewOutput) return reviewOutput;
+  }
+  return null;
+}
+
+export async function runCodexReview({ repoDir, baseRef, env, jsonMode }) {
+  const args = ['review', '--cd', repoDir, '--color=never'];
+
+  if (baseRef) {
+    args.push('--base', baseRef);
+  } else {
+    // Codex requires one of --uncommitted/--base/--commit/prompt; baseRef should exist in our flow.
+    args.push('--uncommitted');
+  }
+
+  if (jsonMode) {
+    args.push('--json');
+  }
+
+  const res = await runCaptureResult('codex', args, { cwd: repoDir, env });
+  return { ...res, stdout: res.out, stderr: res.err };
+}
+

package/scripts/utils/review/targets.mjs

@@ -0,0 +1,24 @@
+import { getComponentsDir, getComponentDir } from '../paths/paths.mjs';
+import { join } from 'node:path';
+
+export function isStackMode(env = process.env) {
+  const stack = String(env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').trim();
+  const envFile = String(env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').trim();
+  return Boolean(stack && envFile);
+}
+
+export function defaultComponentCheckoutDir(rootDir, component) {
+  return join(getComponentsDir(rootDir), component);
+}
+
+export function resolveDefaultStackReviewComponents({ rootDir, components }) {
+  const list = Array.isArray(components) ? components : [];
+  const out = [];
+  for (const c of list) {
+    const effective = getComponentDir(rootDir, c);
+    const def = defaultComponentCheckoutDir(rootDir, c);
+    if (effective !== def) out.push(c);
+  }
+  return out;
+}
+

package/scripts/utils/review/targets.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveDefaultStackReviewComponents } from './targets.mjs';
+
+test('resolveDefaultStackReviewComponents returns only non-default pinned components', () => {
+  const rootDir = '/tmp/hs-root';
+  const keys = [
+    'HAPPY_STACKS_WORKSPACE_DIR',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER',
+  ];
+  const old = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+  try {
+    process.env.HAPPY_STACKS_WORKSPACE_DIR = '/tmp/hs-root';
+    // Default checkouts
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY = '';
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = '';
+    // Pinned overrides
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = '/tmp/custom/happy-cli';
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = '/tmp/custom/happy-server';
+
+    const comps = resolveDefaultStackReviewComponents({
+      rootDir,
+      components: ['happy', 'happy-cli', 'happy-server-light', 'happy-server'],
+    });
+    assert.deepEqual(comps.sort(), ['happy-cli', 'happy-server'].sort());
+  } finally {
+    for (const k of keys) {
+      if (old[k] == null) delete process.env[k];
+      else process.env[k] = old[k];
+    }
+  }
+});
+