@happier-dev/stack 0.1.0-preview.74.1

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

@@ -0,0 +1,117 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { run, runCapture } from '../proc/proc.mjs';
+import { createHeadSliceCommits, getChangedOps } from './head_slice.mjs';
+
+function gitEnv() {
+  const clean = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith('HAPPIER_STACK_')) continue;
+    clean[k] = v;
+  }
+  return {
+    ...clean,
+    GIT_AUTHOR_NAME: 'Test',
+    GIT_AUTHOR_EMAIL: 'test@example.com',
+    GIT_COMMITTER_NAME: 'Test',
+    GIT_COMMITTER_EMAIL: 'test@example.com',
+  };
+}
+
+test('createHeadSliceCommits produces a focused diff while keeping full HEAD code', async (t) => {
+  const repo = await mkdtemp(join(tmpdir(), 'happy-review-head-slice-'));
+  const env = gitEnv();
+
+  const wt = join(repo, 'wt');
+  try {
+    await run('git', ['init', '-q'], { cwd: repo, env });
+    await run('git', ['checkout', '-q', '-b', 'main'], { cwd: repo, env });
+    await mkdir(join(repo, 'apps', 'ui'), { recursive: true });
+    await mkdir(join(repo, 'apps', 'cli'), { recursive: true });
+    await mkdir(join(repo, 'apps', 'server'), { recursive: true });
+    await writeFile(join(repo, 'apps', 'ui', 'a.txt'), 'base-a\n', 'utf-8');
+    await writeFile(join(repo, 'apps', 'cli', 'c.txt'), 'base-c\n', 'utf-8');
+    await writeFile(join(repo, 'apps', 'server', 'b.txt'), 'base-b\n', 'utf-8');
+    await run('git', ['add', '.'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'chore: base'], { cwd: repo, env });
+
+    // HEAD commit with mixed changes across areas.
+    await writeFile(join(repo, 'apps', 'ui', 'a.txt'), 'head-a\n', 'utf-8');
+    await writeFile(join(repo, 'apps', 'ui', 'new.txt'), 'new\n', 'utf-8');
+    await writeFile(join(repo, 'apps', 'cli', 'c.txt'), 'head-c\n', 'utf-8');
+    await rm(join(repo, 'apps', 'server', 'b.txt'));
+    await run('git', ['add', '-A'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'feat: head'], { cwd: repo, env });
+
+    const headCommit = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repo, env })).trim();
+    const baseCommit = (await runCapture('git', ['rev-parse', 'HEAD^'], { cwd: repo, env })).trim();
+
+    // Create an ephemeral worktree to run the slice commit builder in isolation.
+    await run('git', ['worktree', 'add', '--detach', wt, baseCommit], { cwd: repo, env });
+
+    const ops = await getChangedOps({ cwd: repo, baseRef: baseCommit, headRef: headCommit, env });
+    const { baseSliceCommit, headSliceCommit } = await createHeadSliceCommits({
+      cwd: wt,
+      env,
+      baseRef: baseCommit,
+      headCommit,
+      ops,
+      slicePaths: ['apps/ui/a.txt', 'apps/ui/new.txt'],
+      label: 'apps/ui',
+    });
+
+    // Working tree should match full HEAD.
+    const a = await readFile(join(wt, 'apps', 'ui', 'a.txt'), 'utf-8');
+    const c = await readFile(join(wt, 'apps', 'cli', 'c.txt'), 'utf-8');
+    assert.equal(a, 'head-a\n');
+    assert.equal(c, 'head-c\n');
+    await assert.rejects(async () => await readFile(join(wt, 'apps', 'server', 'b.txt'), 'utf-8'));
+
+    // Diff between slice commits should include only apps/ui changes.
+    const diffNames = (
+      await runCapture('git', ['diff', '--name-only', `${baseSliceCommit}...${headSliceCommit}`], { cwd: wt, env })
+    )
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .sort();
+    assert.deepEqual(diffNames, ['apps/ui/a.txt', 'apps/ui/new.txt']);
+  } finally {
+    try {
+      await run('git', ['worktree', 'remove', '--force', wt], { cwd: repo, env });
+      await run('git', ['worktree', 'prune'], { cwd: repo, env });
+    } catch {
+      // ignore cleanup errors (best-effort)
+    }
+    await rm(repo, { recursive: true, force: true });
+  }
+});
+
+test('getChangedOps tracks rename as remove plus checkout', async () => {
+  const repo = await mkdtemp(join(tmpdir(), 'happy-review-head-slice-rename-'));
+  const env = gitEnv();
+
+  try {
+    await run('git', ['init', '-q'], { cwd: repo, env });
+    await run('git', ['checkout', '-q', '-b', 'main'], { cwd: repo, env });
+    await mkdir(join(repo, 'apps', 'ui'), { recursive: true });
+    await writeFile(join(repo, 'apps', 'ui', 'old.txt'), 'old\n', 'utf-8');
+    await run('git', ['add', '.'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'chore: base'], { cwd: repo, env });
+
+    const baseCommit = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repo, env })).trim();
+    await run('git', ['mv', 'apps/ui/old.txt', 'apps/ui/new.txt'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'refactor: rename'], { cwd: repo, env });
+    const headCommit = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repo, env })).trim();
+
+    const ops = await getChangedOps({ cwd: repo, baseRef: baseCommit, headRef: headCommit, env });
+    assert.deepEqual([...ops.checkout].sort(), ['apps/ui/new.txt']);
+    assert.deepEqual([...ops.remove].sort(), ['apps/ui/old.txt']);
+    assert.deepEqual([...ops.all].sort(), ['apps/ui/new.txt', 'apps/ui/old.txt']);
+  } finally {
+    await rm(repo, { recursive: true, force: true });
+  }
+});

package/scripts/utils/review/instructions/deep.md

@@ -0,0 +1,20 @@
+You are running a deep, long-form code review.
+
+Goals:
+- Find correctness bugs, edge cases, and regressions vs upstream/main.
+- Find performance problems (big-O, unnecessary allocations, redundant work) and reliability issues.
+- Find security and safety issues (filesystem access, env handling, process spawning, injection risks).
+- Find maintainability issues (duplication, unclear ownership boundaries, inconsistent patterns).
+- Ensure i18n coverage is complete: do not introduce hardcoded user-visible strings.
+
+Constraints:
+- Prefer fixes that are unified/coherent and avoid duplicating logic.
+- Avoid “brittle” tests that assert on wording/phrasing or hardcoded text; test real behavior and observable outcomes.
+- Do not suggest broad refactors unless clearly justified and low-risk.
+- Treat every recommendation as a suggestion: validate against best practices and the existing codebase patterns; do not propose changes that conflict with project invariants.
+- If a recommendation is uncertain, depends on product/UX decisions, or might have hidden tradeoffs, explicitly mark it as "needs discussion".
+
+Output:
+- Provide specific, actionable recommendations with file paths and a brief rationale.
+- Call out any items that are uncertain or require product/UX decisions separately.
+- Be exhaustive: include all findings you notice, not only the highest-signal ones.

package/scripts/utils/review/prompts.mjs

@@ -0,0 +1,279 @@
+function normalizeChangeType(raw) {
+  const t = String(raw ?? '').trim().toLowerCase();
+  if (!t) return 'committed';
+  if (t === 'committed' || t === 'uncommitted' || t === 'all') return t;
+  // Be defensive: unknown values shouldn't crash prompt building.
+  return 'committed';
+}
+
+function codexScopePathForComponent(component) {
+  switch (component) {
+    case 'happier-ui':
+      return 'apps/ui';
+    case 'happier-cli':
+      return 'apps/cli';
+    case 'happier-server-light':
+    case 'happier-server':
+      return 'apps/server';
+    default:
+      return null;
+  }
+}
+
+function normalizeScopePaths(raw) {
+  const arr = Array.isArray(raw) ? raw : [];
+  const cleaned = arr
+    .map((p) => String(p ?? '').trim().replace(/\/+$/g, ''))
+    .filter(Boolean);
+  return Array.from(new Set(cleaned));
+}
+
+function buildPromptBaseLines({ title, baseRef, changeType, scopePath, deep, customPrompt }) {
+  const ct = normalizeChangeType(changeType);
+  const committedCmd = scopePath
+    ? `git diff ${baseRef}...HEAD -- ${scopePath}/`
+    : `git diff ${baseRef}...HEAD`;
+  const uncommittedCmd = scopePath
+    ? `git diff HEAD -- ${scopePath}/`
+    : `git diff HEAD`;
+  const cmds = ct === 'committed' ? [committedCmd] : ct === 'uncommitted' ? [uncommittedCmd] : [committedCmd, uncommittedCmd];
+
+  const focusLines = deep
+    ? [
+      '- Focus on correctness, edge cases, reliability, performance, and security.',
+      '- Prefer unified/coherent fixes; avoid duplication.',
+      '- Avoid brittle tests that assert on wording/phrasing/config; test real behavior and observable outcomes.',
+      '- Ensure i18n coverage is complete: do not introduce hardcoded user-visible strings; add translation keys across locales as needed.',
+      '- Be exhaustive: list all findings you notice, not only the highest-signal ones.',
+    ]
+    : [
+      '- Focus on correctness, edge cases, reliability, performance, and security.',
+      '- Prefer unified/coherent fixes; avoid duplication.',
+      '- Avoid low-signal nits and docs-only wording feedback unless it affects correctness, safety, or long-term maintainability.',
+      '- Limit to the highest-signal items (aim for <= 15 findings).',
+    ];
+
+  const extra = String(customPrompt ?? '').trim();
+  const customLines = extra
+    ? [
+      'Custom focus:',
+      extra,
+      '',
+    ]
+    : [];
+
+  return [
+    title,
+    '',
+    `Change type: ${ct}`,
+    ct === 'uncommitted' ? 'Base for review: (uncommitted-only)' : `Base for review: ${baseRef}`,
+    scopePath ? `Scope: ${scopePath}/` : 'Scope: full repo',
+    '',
+    'Instructions:',
+    ...cmds.map((c) => `- Use: ${c}`),
+    ct !== 'committed'
+      ? '- Include untracked files (if any): git status --porcelain=v1'
+      : null,
+    ...customLines,
+    ...focusLines,
+    '- Do not wait for other agents/reviewers and do not attempt to coordinate with them. Produce your own review output immediately.',
+    "- Treat every recommendation as a suggestion: validate it against best practices and this codebase's existing patterns. Do not propose changes that violate project invariants.",
+    '- Clearly mark any item that is uncertain, has tradeoffs, or needs product/UX decisions as "needs discussion".',
+    '',
+    'Output format:',
+    '- Start with a short overall verdict.',
+    '- Then list findings as bullets with severity (blocker/major/minor/nit) and a concrete fix suggestion.',
+    '',
+    'Machine-readable output (required):',
+    '- After your review, output a JSON array of findings preceded by a line containing exactly: ===FINDINGS_JSON===',
+    '- Each finding should include: severity, file, (optional) lines, title, description, recommendation, needsDiscussion (boolean).',
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function buildAuditPromptBaseLines({ title, scopePaths, deep, customPrompt }) {
+  const paths = normalizeScopePaths(scopePaths);
+  const scopeLine = paths.length ? `Scope paths: ${paths.join(', ')}` : 'Scope paths: (not specified)';
+  const focusLines = deep
+    ? [
+      '- Focus on correctness, edge cases, reliability, performance, and security.',
+      '- Prefer unified/coherent fixes; avoid duplication.',
+      '- Avoid brittle tests that assert on wording/phrasing/config; test real behavior and observable outcomes.',
+      '- Be exhaustive: list all findings you notice, not only the highest-signal ones.',
+    ]
+    : [
+      '- Focus on correctness, edge cases, reliability, performance, and security.',
+      '- Prefer unified/coherent fixes; avoid duplication.',
+      '- Avoid low-signal nits and docs-only wording feedback unless it affects correctness, safety, or long-term maintainability.',
+      '- Limit to the highest-signal items (aim for <= 15 findings).',
+    ];
+
+  const extra = String(customPrompt ?? '').trim();
+  const customLines = extra
+    ? [
+      'Custom focus:',
+      extra,
+      '',
+    ]
+    : [];
+
+  return [
+    title,
+    '',
+    'Mode: audit (no diff).',
+    scopeLine,
+    '',
+    'Instructions:',
+    '- Inspect the current repository state directly (not a diff).',
+    '- Prefer starting from the scope paths above; follow cross-references as needed, but keep findings grounded in concrete code.',
+    ...customLines,
+    ...focusLines,
+    '- Do not wait for other agents/reviewers and do not attempt to coordinate with them. Produce your own review output immediately.',
+    "- Treat every recommendation as a suggestion: validate it against best practices and this codebase's existing patterns. Do not propose changes that violate project invariants.",
+    '- Clearly mark any item that is uncertain, has tradeoffs, or needs product/UX decisions as "needs discussion".',
+    '',
+    'Output format:',
+    '- Start with a short overall verdict.',
+    '- Then list findings as bullets with severity (blocker/major/minor/nit) and a concrete fix suggestion.',
+    '',
+    'Machine-readable output (required):',
+    '- After your review, output a JSON array of findings preceded by a line containing exactly: ===FINDINGS_JSON===',
+    '- Each finding should include: severity, file, (optional) lines, title, description, recommendation, needsDiscussion (boolean).',
+  ].join('\n');
+}
+
+export function buildCodexDeepPrompt({ component, baseRef, changeType, customPrompt }) {
+  const scopePath = codexScopePathForComponent(component);
+  return buildPromptBaseLines({
+    title: 'Run a deep, long-form code review.',
+    baseRef,
+    changeType,
+    scopePath,
+    deep: true,
+    customPrompt,
+  });
+}
+
+export function buildCodexNormalPrompt({ component, baseRef, changeType, customPrompt }) {
+  const scopePath = codexScopePathForComponent(component);
+  return buildPromptBaseLines({
+    title: 'Run a focused code review.',
+    baseRef,
+    changeType,
+    scopePath,
+    deep: false,
+    customPrompt,
+  });
+}
+
+export function buildCodexMonorepoDeepPrompt({ baseRef, changeType, customPrompt }) {
+  return buildPromptBaseLines({
+    title: 'Run a deep, long-form code review on the monorepo.',
+    baseRef,
+    changeType,
+    scopePath: null,
+    deep: true,
+    customPrompt,
+  });
+}
+
+export function buildCodexMonorepoNormalPrompt({ baseRef, changeType, customPrompt }) {
+  return buildPromptBaseLines({
+    title: 'Run a focused code review on the monorepo.',
+    baseRef,
+    changeType,
+    scopePath: null,
+    deep: false,
+    customPrompt,
+  });
+}
+
+export function buildCodexAuditPrompt({ component, deep = true, scopePaths = [], customPrompt }) {
+  const scopePath = codexScopePathForComponent(component);
+  const paths = normalizeScopePaths(scopePaths);
+  // If no explicit paths are provided, fall back to the component scope path for signal.
+  const effective = paths.length ? paths : scopePath ? [scopePath] : [];
+  return buildAuditPromptBaseLines({
+    title: deep ? 'Run a deep, long-form repository audit.' : 'Run a focused repository audit.',
+    scopePaths: effective,
+    deep: Boolean(deep),
+    customPrompt,
+  });
+}
+
+export function buildCodexMonorepoAuditPrompt({ deep = true, scopePaths = [], customPrompt }) {
+  return buildAuditPromptBaseLines({
+    title: deep ? 'Run a deep, long-form repository audit on the monorepo.' : 'Run a focused repository audit on the monorepo.',
+    scopePaths,
+    deep: Boolean(deep),
+    customPrompt,
+  });
+}
+
+export function buildCodexMonorepoSlicePrompt({ sliceLabel, baseCommit, baseRef, deep = true, customPrompt }) {
+  const diffCmd = `git -C \"$(git rev-parse --show-toplevel)\" diff ${baseCommit}...HEAD`;
+  const focusLines = deep
+    ? [
+      '- Focus on correctness, edge cases, reliability, performance, and security.',
+      '- Prefer unified/coherent fixes; avoid duplication.',
+      '- Avoid brittle tests that assert on wording/phrasing/config; test real behavior and observable outcomes.',
+      '- Ensure i18n coverage is complete: do not introduce hardcoded user-visible strings; add translation keys across locales as needed.',
+      '- Be exhaustive within this slice: list all findings you notice, not only the highest-signal ones.',
+    ]
+    : [
+      '- Focus on correctness, edge cases, reliability, performance, and security.',
+      '- Prefer unified/coherent fixes; avoid duplication.',
+      '- Avoid low-signal nits and docs-only wording feedback unless it affects correctness, safety, or long-term maintainability.',
+      '- Limit to the highest-signal items (aim for <= 15 findings).',
+    ];
+
+  const extra = String(customPrompt ?? '').trim();
+  const customLines = extra
+    ? [
+      '',
+      'Custom focus:',
+      extra,
+    ]
+    : [];
+
+  return [
+    deep ? 'Run a deep, long-form code review on the monorepo.' : 'Run a focused code review on the monorepo.',
+    '',
+    `Base ref: ${baseRef}`,
+    `Slice: ${sliceLabel}`,
+    '',
+    'Important:',
+    '- The base commit for this slice is synthetic: it represents upstream plus all NON-slice changes.',
+    '- Therefore, the diff below contains ONLY the changes for this slice, but the checked-out code is the full final HEAD.',
+    '',
+    'Instructions:',
+    `- Use: ${diffCmd}`,
+    '- You may inspect any file in the repo for cross-references (server/cli/ui), but keep findings scoped to this slice diff.',
+    ...customLines,
+    ...focusLines,
+    '- Do not wait for other agents/reviewers and do not attempt to coordinate with them. Produce your own review output immediately.',
+    "- Treat every recommendation as a suggestion: validate it against best practices and this codebase's existing patterns. Do not propose changes that violate project invariants.",
+    '- Clearly mark any item that is uncertain, has tradeoffs, or needs product/UX decisions as "needs discussion".',
+    '',
+    'Output format:',
+    '- Start with a short overall verdict.',
+    '- Then list findings as bullets with severity (blocker/major/minor/nit) and a concrete fix suggestion.',
+    '',
+    'Machine-readable output (required):',
+    '- After your review, output a JSON array of findings preceded by a line containing exactly: ===FINDINGS_JSON===',
+    '- Each finding should include: severity, file, (optional) lines, title, description, recommendation, needsDiscussion (boolean).',
+  ].join('\n');
+}
+
+export function buildUncommittedSlicePrompt({ sliceLabel, basePrompt }) {
+  return [
+    `Slice: ${sliceLabel}`,
+    '- The worktree is pre-scoped for this slice only.',
+    '- Files outside this slice may be intentionally absent in this temporary worktree.',
+    '- Do not file "missing file/module" findings unless the missing path is part of this slice diff.',
+    '- Review only the uncommitted changes currently present in this worktree.',
+    '',
+    basePrompt,
+  ].join('\n');
+}

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

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  buildCodexDeepPrompt,
+  buildCodexNormalPrompt,
+  buildCodexMonorepoDeepPrompt,
+  buildCodexMonorepoNormalPrompt,
+  buildCodexAuditPrompt,
+  buildCodexMonorepoAuditPrompt,
+  buildCodexMonorepoSlicePrompt,
+} from './prompts.mjs';
+
+test('monorepo normal prompt is focused and includes findings JSON marker', () => {
+  const prompt = buildCodexMonorepoNormalPrompt({ baseRef: 'upstream/main', changeType: 'uncommitted' });
+  assert.match(prompt, /focused code review on the monorepo/i);
+  assert.match(prompt, /git diff HEAD/i);
+  assert.match(prompt, /===FINDINGS_JSON===/);
+  assert.match(prompt, /Do not wait for other agents\/reviewers/i);
+  assert.doesNotMatch(prompt, /Be exhaustive/i);
+});
+
+test('monorepo deep prompt is exhaustive and includes findings JSON marker', () => {
+  const prompt = buildCodexMonorepoDeepPrompt({ baseRef: 'upstream/main', changeType: 'committed' });
+  assert.match(prompt, /deep, long-form code review on the monorepo/i);
+  assert.match(prompt, /git diff upstream\/main\.\.\.HEAD/i);
+  assert.match(prompt, /===FINDINGS_JSON===/);
+  assert.match(prompt, /Be exhaustive/i);
+});
+
+test('component normal prompt scopes diff to component path', () => {
+  const prompt = buildCodexNormalPrompt({ component: 'happier-ui', baseRef: 'upstream/main', changeType: 'committed' });
+  assert.match(prompt, /Scope: apps\/ui\//);
+  assert.match(prompt, /git diff upstream\/main\.\.\.HEAD -- apps\/ui\//);
+});
+
+test('component deep prompt scopes diff to component path', () => {
+  const prompt = buildCodexDeepPrompt({ component: 'happier-cli', baseRef: 'upstream/main', changeType: 'committed' });
+  assert.match(prompt, /Scope: apps\/cli\//);
+  assert.match(prompt, /git diff upstream\/main\.\.\.HEAD -- apps\/cli\//);
+});
+
+test('monorepo slice prompt toggles focused vs deep wording', () => {
+  const deep = buildCodexMonorepoSlicePrompt({ sliceLabel: 'apps/cli', baseCommit: 'abc123', baseRef: 'upstream/main', deep: true });
+  const focused = buildCodexMonorepoSlicePrompt({ sliceLabel: 'apps/cli', baseCommit: 'abc123', baseRef: 'upstream/main', deep: false });
+  assert.match(deep, /deep, long-form/i);
+  assert.match(focused, /focused code review/i);
+});
+
+test('prompts support appending custom focus instructions', () => {
+  const prompt = buildCodexMonorepoNormalPrompt({
+    baseRef: 'upstream/main',
+    changeType: 'uncommitted',
+    customPrompt: 'Focus specifically on machine_id_conflict behavior and cross-account machine claiming risks.',
+  });
+  assert.match(prompt, /Custom focus:/i);
+  assert.match(prompt, /machine_id_conflict/i);
+  assert.match(prompt, /===FINDINGS_JSON===/);
+});
+
+test('audit prompts do not require git diff and include scope paths', () => {
+  const prompt = buildCodexMonorepoAuditPrompt({
+    deep: true,
+    scopePaths: ['apps/cli/src/daemon', 'apps/server/sources/app/api/routes/machines'],
+    customPrompt: 'Focus on machine identity invariants across accounts.',
+  });
+  assert.match(prompt, /Mode: audit/i);
+  assert.match(prompt, /Scope paths:/i);
+  assert.doesNotMatch(prompt, /git diff/i);
+  assert.match(prompt, /===FINDINGS_JSON===/);
+});
+
+test('component audit prompt falls back to component scope path when no explicit scope paths provided', () => {
+  const prompt = buildCodexAuditPrompt({ component: 'happier-ui', deep: false, scopePaths: [] });
+  assert.match(prompt, /Scope paths: apps\/ui/i);
+  assert.doesNotMatch(prompt, /git diff/i);
+});

package/scripts/utils/review/run_reviewers_safe.mjs

@@ -0,0 +1,12 @@
+export async function runReviewersSafe({ reviewers, runReviewer, onError }) {
+  const list = Array.isArray(reviewers) ? reviewers : [];
+  const run = typeof runReviewer === 'function' ? runReviewer : async () => null;
+  const handleError = typeof onError === 'function' ? onError : (_reviewer, error) => ({ ok: false, error });
+
+  const settled = await Promise.allSettled(list.map((r) => run(r)));
+  return settled.map((s, i) => {
+    if (s.status === 'fulfilled') return s.value;
+    return handleError(list[i], s.reason);
+  });
+}
+

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

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { runReviewersSafe } from './run_reviewers_safe.mjs';
+
+test('runReviewersSafe returns values in reviewer order', async () => {
+  const reviewers = ['a', 'b', 'c'];
+  const seen = [];
+
+  const res = await runReviewersSafe({
+    reviewers,
+    runReviewer: async (r) => {
+      seen.push(r);
+      return { reviewer: r, ok: true };
+    },
+    onError: (reviewer, error) => ({ reviewer, ok: false, error }),
+  });
+
+  assert.deepEqual(seen, reviewers);
+  assert.deepEqual(
+    res.map((r) => r.reviewer),
+    reviewers
+  );
+  assert.equal(res.every((r) => r.ok), true);
+});
+
+test('runReviewersSafe converts thrown errors into onError results', async () => {
+  const reviewers = ['ok', 'boom', 'ok2'];
+
+  const res = await runReviewersSafe({
+    reviewers,
+    runReviewer: async (r) => {
+      if (r === 'boom') throw new Error('kaboom');
+      return { reviewer: r, ok: true };
+    },
+    onError: (reviewer, error) => ({ reviewer, ok: false, message: String(error?.message ?? error) }),
+  });
+
+  assert.deepEqual(res.map((r) => r.reviewer), reviewers);
+  assert.equal(res[0].ok, true);
+  assert.equal(res[1].ok, false);
+  assert.match(res[1].message, /kaboom/);
+  assert.equal(res[2].ok, true);
+});
+

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

@@ -0,0 +1,91 @@
+import { runCaptureResult } from '../../proc/proc.mjs';
+
+export function detectAugmentAuthError({ stdout, stderr }) {
+  const combined = `${stdout ?? ''}\n${stderr ?? ''}`;
+  return combined.includes('Authentication failed') && combined.includes("Run 'auggie login'");
+}
+
+function parsePositiveInt(raw) {
+  const n = Number(String(raw ?? '').trim());
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+function resolveAugmentKeepaliveMs(env) {
+  const specific = parsePositiveInt(env?.HAPPIER_STACK_REVIEW_AUGMENT_KEEPALIVE_MS);
+  if (specific !== null) return specific;
+  const global = parsePositiveInt(env?.HAPPIER_STACK_REVIEW_KEEPALIVE_MS);
+  if (global !== null) return global;
+  return 30_000;
+}
+
+export function buildAugmentReviewArgs({
+  prompt,
+  workspaceRoot,
+  cacheDir,
+  model,
+  rulesFiles = [],
+  retryTimeoutSec,
+  maxTurns,
+} = {}) {
+  const args = ['--print', '--quiet', '--dont-save-session', '--ask', '--output-format', 'text'];
+
+  const wr = String(workspaceRoot ?? '').trim();
+  if (wr) args.push('--workspace-root', wr);
+
+  const cd = String(cacheDir ?? '').trim();
+  if (cd) args.push('--augment-cache-dir', cd);
+
+  const m = String(model ?? '').trim();
+  if (m) args.push('--model', m);
+
+  const rt = String(retryTimeoutSec ?? '').trim();
+  if (rt) args.push('--retry-timeout', rt);
+
+  const mt = String(maxTurns ?? '').trim();
+  if (mt) args.push('--max-turns', mt);
+
+  for (const rf of Array.isArray(rulesFiles) ? rulesFiles : []) {
+    const p = String(rf ?? '').trim();
+    if (!p) continue;
+    args.push('--rules', p);
+  }
+
+  const p = String(prompt ?? '').trim();
+  if (!p) throw new Error('[review] augment: missing prompt');
+  args.push(p);
+  return args;
+}
+
+export async function runAugmentReview({
+  repoDir,
+  prompt,
+  env,
+  streamLabel,
+  teeFile,
+  teeLabel,
+  cacheDir,
+  model,
+  rulesFiles = [],
+  retryTimeoutSec = 60 * 60 * 2,
+  maxTurns,
+} = {}) {
+  const args = buildAugmentReviewArgs({
+    prompt,
+    workspaceRoot: repoDir,
+    cacheDir,
+    model,
+    rulesFiles,
+    retryTimeoutSec,
+    maxTurns,
+  });
+  const heartbeatMs = resolveAugmentKeepaliveMs(env ?? {});
+  const res = await runCaptureResult('auggie', args, {
+    cwd: repoDir,
+    env: env ?? {},
+    streamLabel,
+    teeFile,
+    teeLabel,
+    heartbeatMs,
+  });
+  return { ...res, stdout: res.out, stderr: res.err };
+}