happy-stacks 0.3.0 → 0.5.0

package/scripts/utils/proc/proc.mjs

@@ -1,13 +1,28 @@
 import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+
+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`);
   }
 }
@@ -66,9 +81,25 @@ export function killProcessTree(child, signal) {
 }
 
 export async function run(cmd, args, options = {}) {
-  const { timeoutMs, ...spawnOptions } = options ?? {};
+  const { timeoutMs, input, ...spawnOptions } = options ?? {};
   await new Promise((resolvePromise, rejectPromise) => {
-    const proc = spawn(cmd, args, { stdio: 'inherit', shell: false, ...spawnOptions });
+    const baseStdio = spawnOptions.stdio ?? 'inherit';
+    const stdio =
+      input != null
+        ? Array.isArray(baseStdio)
+          ? ['pipe', baseStdio[1] ?? 'inherit', baseStdio[2] ?? 'inherit']
+          : ['pipe', baseStdio, baseStdio]
+        : baseStdio;
+
+    const proc = spawn(cmd, args, { stdio, shell: false, ...spawnOptions });
+    if (input != null && proc.stdin) {
+      try {
+        proc.stdin.write(String(input));
+        proc.stdin.end();
+      } catch {
+        // ignore
+      }
+    }
     const t =
       Number.isFinite(timeoutMs) && timeoutMs > 0
         ? setTimeout(() => {
@@ -133,3 +164,104 @@ export async function runCapture(cmd, args, options = {}) {
   });
 }
 
+export async function runCaptureResult(cmd, args, options = {}) {
+  const { timeoutMs, streamLabel, teeFile, teeLabel, ...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 label = String(streamLabel ?? '').trim();
+    const shouldStream = Boolean(label);
+    const outState = { buf: '' };
+    const errState = { buf: '' };
+    const prefix = shouldStream ? `[${label}] ` : '';
+
+    const teePath = String(teeFile ?? '').trim();
+    const shouldTee = Boolean(teePath);
+    const teeOutState = { buf: '' };
+    const teeErrState = { buf: '' };
+    const teePrefix = (() => {
+      const t = String(teeLabel ?? '').trim();
+      if (t) return `[${t}] `;
+      if (label) return `[${label}] `;
+      return '';
+    })();
+    const teeStream = shouldTee ? createWriteStream(teePath, { flags: 'a' }) : null;
+
+    function resolveWith(res) {
+      if (shouldStream) {
+        flushPrefixed(process.stdout, prefix, outState);
+        flushPrefixed(process.stderr, prefix, errState);
+      }
+      if (shouldTee && teeStream) {
+        flushPrefixed(teeStream, teePrefix, teeOutState);
+        flushPrefixed(teeStream, teePrefix, teeErrState);
+        try {
+          teeStream.end();
+        } catch {
+          // ignore
+        }
+      }
+      resolvePromise(res);
+    }    const t =
+      Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? setTimeout(() => {
+            try {
+              proc.kill('SIGKILL');
+            } catch {
+              // ignore
+            }
+            resolveWith({
+              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();
+      if (shouldStream) writeWithPrefix(process.stdout, prefix, outState, d);
+      if (shouldTee && teeStream) writeWithPrefix(teeStream, teePrefix, teeOutState, d);
+    });
+    proc.stderr?.on('data', (d) => {
+      err += d.toString();
+      if (shouldStream) writeWithPrefix(process.stderr, prefix, errState, d);
+      if (shouldTee && teeStream) writeWithPrefix(teeStream, teePrefix, teeErrState, d);
+    });
+    proc.on('error', (e) => {
+      if (t) clearTimeout(t);
+      resolveWith({
+        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);
+      resolveWith({
+        ok: code === 0,
+        exitCode: code,
+        signal: signal ?? null,
+        out,
+        err,
+        timedOut: false,
+        startedAt,
+        finishedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+      });
+    });
+  });
+}

package/scripts/utils/proc/proc.test.mjs

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { runCaptureResult } from './proc.mjs';
+
+test('runCaptureResult captures stdout/stderr', async () => {
+  const res = await runCaptureResult(process.execPath, ['-e', 'console.log("hello"); console.error("oops")'], {
+    env: process.env,
+  });
+  assert.equal(res.ok, true);
+  assert.equal(res.exitCode, 0);
+  assert.match(res.out, /hello/);
+  assert.match(res.err, /oops/);
+});
+
+test('runCaptureResult streams output when streamLabel is set (without affecting captured output)', async () => {
+  const stdoutWrites = [];
+  const stderrWrites = [];
+
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
+  const origStderrWrite = process.stderr.write.bind(process.stderr);
+
+  // Capture streaming output without polluting the test runner output.
+  // eslint-disable-next-line no-console
+  process.stdout.write = (chunk) => {
+    stdoutWrites.push(String(chunk));
+    return true;
+  };
+  // eslint-disable-next-line no-console
+  process.stderr.write = (chunk) => {
+    stderrWrites.push(String(chunk));
+    return true;
+  };
+
+  try {
+    const res = await runCaptureResult(process.execPath, ['-e', 'console.log("hello"); console.error("oops")'], {
+      env: process.env,
+      streamLabel: 'proc-test',
+    });
+    assert.equal(res.ok, true);
+    assert.equal(res.exitCode, 0);
+    assert.match(res.out, /hello/);
+    assert.match(res.err, /oops/);
+
+    const streamedOut = stdoutWrites.join('');
+    const streamedErr = stderrWrites.join('');
+    assert.match(streamedOut, /\[proc-test\] hello/);
+    assert.match(streamedErr, /\[proc-test\] oops/);
+  } finally {
+    process.stdout.write = origStdoutWrite;
+    process.stderr.write = origStderrWrite;
+  }
+});
+
+test('runCaptureResult can tee streamed output to a file', async () => {
+  const teeFile = join(tmpdir(), `happy-proc-tee-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
+  try {
+    const res = await runCaptureResult(process.execPath, ['-e', 'console.log("hello"); console.error("oops")'], {
+      env: process.env,
+      teeFile,
+      teeLabel: 'tee-test',
+    });
+    assert.equal(res.ok, true);
+    const raw = readFileSync(teeFile, 'utf-8');
+    assert.match(raw, /\[tee-test\] hello/);
+    assert.match(raw, /\[tee-test\] oops/);
+  } finally {
+    try {
+      rmSync(teeFile, { force: true });
+    } catch {
+      // ignore
+    }
+  }
+});

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/chunks.mjs

@@ -0,0 +1,55 @@
+export async function planCommitChunks({ baseCommit, commits, maxFiles, countFilesBetween }) {
+  if (!Array.isArray(commits)) throw new Error('[review] planCommitChunks: commits must be an array');
+  const max = Number(maxFiles);
+  if (!Number.isFinite(max) || max <= 0) throw new Error('[review] planCommitChunks: maxFiles must be a positive number');
+  if (typeof countFilesBetween !== 'function') throw new Error('[review] planCommitChunks: countFilesBetween must be a function');
+
+  const list = commits.map((c) => String(c ?? '').trim()).filter(Boolean);
+  if (!list.length) return [];
+
+  const chunks = [];
+  let base = String(baseCommit ?? '').trim();
+  if (!base) throw new Error('[review] planCommitChunks: baseCommit is required');
+  let startIndex = 0;
+
+  while (startIndex < list.length) {
+    let lo = startIndex;
+    let hi = list.length - 1;
+    let bestIndex = -1;
+    let bestCount = -1;
+
+    while (lo <= hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      const head = list[mid];
+      // eslint-disable-next-line no-await-in-loop
+      const n = await countFilesBetween({ base, head });
+      if (!Number.isFinite(n) || n < 0) throw new Error('[review] planCommitChunks: countFilesBetween returned invalid count');
+
+      if (n <= max) {
+        bestIndex = mid;
+        bestCount = n;
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+
+    // If even the smallest chunk exceeds the limit, emit a single over-limit chunk so the caller can decide what to do.
+    if (bestIndex === -1) {
+      const head = list[startIndex];
+      // eslint-disable-next-line no-await-in-loop
+      const n = await countFilesBetween({ base, head });
+      chunks.push({ base, head, fileCount: n, overLimit: true });
+      base = head;
+      startIndex += 1;
+      continue;
+    }
+
+    const head = list[bestIndex];
+    chunks.push({ base, head, fileCount: bestCount, overLimit: false });
+    base = head;
+    startIndex = bestIndex + 1;
+  }
+
+  return chunks;
+}

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

@@ -0,0 +1,51 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { planCommitChunks } from './chunks.mjs';
+
+test('planCommitChunks greedily selects the largest end commit within maxFiles', async () => {
+  const commits = ['c1', 'c2', 'c3', 'c4'];
+
+  const counts = new Map([
+    ['BASE->c1', 1],
+    ['BASE->c2', 3],
+    ['BASE->c3', 4],
+    ['BASE->c4', 7],
+    ['c2->c3', 2],
+    ['c2->c4', 5],
+    ['c3->c4', 2],
+  ]);
+
+  const chunks = await planCommitChunks({
+    baseCommit: 'BASE',
+    commits,
+    maxFiles: 3,
+    countFilesBetween: async ({ base, head }) => counts.get(`${base}->${head}`),
+  });
+
+  assert.deepEqual(chunks, [
+    { base: 'BASE', head: 'c2', fileCount: 3, overLimit: false },
+    { base: 'c2', head: 'c3', fileCount: 2, overLimit: false },
+    { base: 'c3', head: 'c4', fileCount: 2, overLimit: false },
+  ]);
+});
+
+test('planCommitChunks marks overLimit when a single step exceeds maxFiles', async () => {
+  const commits = ['c1', 'c2'];
+
+  const counts = new Map([
+    ['BASE->c1', 10],
+    ['c1->c2', 2],
+  ]);
+
+  const chunks = await planCommitChunks({
+    baseCommit: 'BASE',
+    commits,
+    maxFiles: 3,
+    countFilesBetween: async ({ base, head }) => counts.get(`${base}->${head}`),
+  });
+
+  assert.deepEqual(chunks, [
+    { base: 'BASE', head: 'c1', fileCount: 10, overLimit: true },
+    { base: 'c1', head: 'c2', fileCount: 2, overLimit: false },
+  ]);
+});

package/scripts/utils/review/findings.mjs

@@ -0,0 +1,165 @@
+function parseLineRange(raw) {
+  const s = String(raw ?? '').trim();
+  // Common CodeRabbit format: "17 to 31"
+  const m = s.match(/^(\d+)\s+to\s+(\d+)$/i);
+  if (m) return { start: Number(m[1]), end: Number(m[2]) };
+  const n = s.match(/^(\d+)$/);
+  if (n) {
+    const v = Number(n[1]);
+    return { start: v, end: v };
+  }
+  return null;
+}
+
+export function parseCodeRabbitPlainOutput(text) {
+  const lines = String(text ?? '').split('\n');
+  const findings = [];
+
+  let current = null;
+  let mode = null; // 'comment' | 'prompt' | null
+
+  function flush() {
+    if (!current) return;
+    const comment = (current._commentLines ?? []).join('\n').trim();
+    const prompt = (current._promptLines ?? []).join('\n').trim();
+    const title =
+      current.title ??
+      comment
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)[0] ??
+      '';
+
+    findings.push({
+      reviewer: 'coderabbit',
+      file: current.file ?? '',
+      lines: current.lines ?? null,
+      type: current.type ?? '',
+      title,
+      comment,
+      prompt: prompt || null,
+    });
+    current = null;
+    mode = null;
+  }
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const trimmed = line.trimEnd();
+
+    if (trimmed.startsWith('============================================================================')) {
+      flush();
+      continue;
+    }
+    if (trimmed.startsWith('File: ')) {
+      flush();
+      current = { _commentLines: [], _promptLines: [] };
+      current.file = trimmed.slice('File: '.length).trim();
+      continue;
+    }
+    if (!current) continue;
+
+    if (trimmed.startsWith('Line: ')) {
+      const range = parseLineRange(trimmed.slice('Line: '.length).trim());
+      current.lines = range;
+      continue;
+    }
+    if (trimmed.startsWith('Type: ')) {
+      current.type = trimmed.slice('Type: '.length).trim();
+      continue;
+    }
+    if (trimmed === 'Comment:') {
+      mode = 'comment';
+      continue;
+    }
+    if (trimmed === 'Prompt for AI Agent:') {
+      mode = 'prompt';
+      continue;
+    }
+
+    if (mode === 'comment') {
+      // Title is first non-empty comment line.
+      if (!current.title && trimmed.trim()) current.title = trimmed.trim();
+      current._commentLines.push(trimmed);
+    } else if (mode === 'prompt') {
+      current._promptLines.push(trimmed);
+    }
+  }
+
+  flush();
+  // Drop empty placeholders
+  return findings.filter((f) => f.file && f.title);
+}
+
+export function parseCodexReviewText(reviewText) {
+  const s = String(reviewText ?? '');
+  const marker = '===FINDINGS_JSON===';
+  const idx = s.indexOf(marker);
+  if (idx < 0) return [];
+  const jsonText = s.slice(idx + marker.length).trim();
+  if (!jsonText) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .map((x) => ({
+      reviewer: 'codex',
+      severity: x?.severity ?? null,
+      file: x?.file ?? null,
+      title: x?.title ?? null,
+      recommendation: x?.recommendation ?? null,
+      needsDiscussion: Boolean(x?.needsDiscussion),
+    }))
+    .filter((x) => x.file && x.title);
+}
+
+export function formatTriageMarkdown({ runLabel, baseRef, findings }) {
+  const items = Array.isArray(findings) ? findings : [];
+  const header = [
+    `# Review triage: ${runLabel}`,
+    '',
+    `- Base ref: ${baseRef ?? ''}`,
+    `- Findings: ${items.length}`,
+    '',
+    '## Mandatory workflow',
+    '',
+    'For each finding below:',
+    '1) Open the referenced file/lines in the *validation worktree* (committed-only).',
+    '2) Decide if it is a real bug/risk/correctness gap, already fixed, expected behavior, or style preference.',
+    '3) Record a final decision + rationale here (`apply` / `adjust` / `defer`).',
+    '4) If `apply/adjust`: implement in the main worktree as a clean commit (no unrelated changes), then sync that commit to validation.',
+    '',
+    'Notes:',
+    '- Treat reviewer output as suggestions; verify against best practices and codebase invariants before applying.',
+    '- Avoid brittle tests that assert on wording/phrasing/config; test observable behavior.',
+    '',
+  ].join('\n');
+
+  const body = items
+    .map((f) => {
+      const lines = f.lines?.start ? `${f.lines.start}-${f.lines.end ?? f.lines.start}` : '';
+      const meta = [
+        `- [ ] \`${f.id ?? ''}\` reviewer=\`${f.reviewer ?? ''}\`${f.severity ? ` severity=\`${f.severity}\`` : ''}${
+          f.type ? ` type=\`${f.type}\`` : ''
+        } \`${f.file ?? ''}\`${lines ? ` (lines ${lines})` : ''}: ${f.title ?? ''}`,
+        f.sourceLog ? `  - Source log: \`${f.sourceLog}\`` : null,
+        '  - Final decision: **TBD** (apply|adjust|defer)',
+        '  - Verified in validation worktree: **TBD**',
+        '  - Rationale: **TBD**',
+        '  - Action taken: **TBD**',
+        '  - Commit: **TBD**',
+        '  - Needs discussion: **TBD**',
+      ];
+      if (f.comment) meta.push(`  - Reviewer detail: ${String(f.comment).split('\n')[0].trim()}`);
+      if (f.recommendation) meta.push(`  - Reviewer suggested fix: ${String(f.recommendation).split('\n')[0].trim()}`);
+      return meta.filter(Boolean).join('\n');
+    })
+    .join('\n\n');
+
+  return `${header}${body ? `${body}\n` : ''}`;
+}