happy-stacks 0.4.0 → 0.5.0

package/scripts/utils/proc/pm.mjs

@@ -50,12 +50,12 @@ export async function requirePnpm() {
   );
 }
 
-async function getComponentPm(dir) {
+async function getComponentPm(dir, env = process.env) {
   const yarnLock = join(dir, 'yarn.lock');
   if (await pathExists(yarnLock)) {
     // IMPORTANT: when happy-stacks itself is pinned to pnpm via Corepack, running `yarn`
     // from the happy-stacks cwd can be blocked. Always probe yarn with cwd=componentDir.
-    if (!(await commandExists('yarn', { cwd: dir }))) {
+    if (!(await commandExists('yarn', { cwd: dir, env }))) {
       throw new Error(`[local] yarn is required for component at ${dir} (yarn.lock present). Install it via Corepack: \`corepack enable\``);
     }
     return { name: 'yarn', cmd: 'yarn' };
@@ -66,6 +66,23 @@ async function getComponentPm(dir) {
   return { name: 'pnpm', cmd: 'pnpm' };
 }
 
+const _yarnReadyKeys = new Set();
+
+async function ensureYarnReady({ dir, env, quiet = false }) {
+  const e = env && typeof env === 'object' ? env : process.env;
+  // In stack mode we isolate HOME/cache; key by effective HOME+XDG cache so we only do this once.
+  const key = `${resolve(dir)}|${String(e.HOME ?? '')}|${String(e.XDG_CACHE_HOME ?? '')}`;
+  if (_yarnReadyKeys.has(key)) return;
+
+  // If stdin isn't a TTY (e.g. `happys tui ...` uses stdio:ignore for child stdin),
+  // Corepack prompts can deadlock. Provide a single "yes" to unblock initial downloads.
+  const isTui = (e.HAPPY_STACKS_TUI ?? e.HAPPY_LOCAL_TUI ?? '').toString().trim() === '1';
+  const autoYes = isTui || !process.stdin.isTTY;
+  const stdio = quiet ? 'ignore' : 'inherit';
+  await run('yarn', ['--version'], { cwd: dir, env: e, stdio, ...(autoYes ? { input: 'y\n' } : {}) });
+  _yarnReadyKeys.add(key);
+}
+
 export async function requireDir(label, dir) {
   if (await pathExists(dir)) {
     return;
@@ -76,7 +93,71 @@ export async function requireDir(label, dir) {
   );
 }
 
-export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
+function resolveStackCacheBaseDirFromEnv(env) {
+  const envFile = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim();
+  if (!envFile) return null;
+  try {
+    return join(dirname(envFile), 'cache');
+  } catch {
+    return null;
+  }
+}
+
+async function applyStackCacheEnv(baseEnv) {
+  const env = { ...(baseEnv && typeof baseEnv === 'object' ? baseEnv : process.env) };
+  const envFile = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim();
+  const stackCacheBase = resolveStackCacheBaseDirFromEnv(env);
+  if (!stackCacheBase) return env;
+
+  // Prisma engines currently default to ~/.cache/prisma (via os.homedir()).
+  // In stack mode, isolate HOME for package-manager driven commands so Prisma/Yarn/NPM don't
+  // depend on global home caches (and so sandboxed runs can succeed).
+  const isolateHomeRaw = (env.HAPPY_STACKS_PM_ISOLATE_HOME ?? env.HAPPY_LOCAL_PM_ISOLATE_HOME ?? '').toString().trim();
+  const isolateHome = isolateHomeRaw ? isolateHomeRaw !== '0' : true;
+  if (isolateHome && envFile) {
+    const stackHome = join(dirname(envFile), 'home');
+    env.HOME = stackHome;
+    env.USERPROFILE = stackHome;
+    try {
+      await mkdir(stackHome, { recursive: true });
+    } catch {
+      // best-effort
+    }
+  }
+
+  if (!(env.XDG_CACHE_HOME ?? '').toString().trim()) {
+    env.XDG_CACHE_HOME = join(stackCacheBase, 'xdg');
+  }
+  if (!(env.YARN_CACHE_FOLDER ?? '').toString().trim()) {
+    env.YARN_CACHE_FOLDER = join(stackCacheBase, 'yarn');
+  }
+  if (!(env.npm_config_cache ?? '').toString().trim()) {
+    env.npm_config_cache = join(stackCacheBase, 'npm');
+  }
+  // Corepack caches downloaded package managers (like Yarn) under COREPACK_HOME.
+  // In stack mode we want this to be stable and writable so first-run downloads don't prompt/hang in TUI.
+  if (!(env.COREPACK_HOME ?? '').toString().trim()) {
+    env.COREPACK_HOME = join(stackCacheBase, 'corepack');
+  }
+  // Avoid Corepack mutating package.json by auto-adding a packageManager field.
+  // (This is safe and reduces noise when Corepack is used implicitly.)
+  if (!(env.COREPACK_ENABLE_AUTO_PIN ?? '').toString().trim()) {
+    env.COREPACK_ENABLE_AUTO_PIN = '0';
+  }
+
+  try {
+    await mkdir(env.XDG_CACHE_HOME, { recursive: true });
+    await mkdir(env.YARN_CACHE_FOLDER, { recursive: true });
+    await mkdir(env.npm_config_cache, { recursive: true });
+    await mkdir(env.COREPACK_HOME, { recursive: true });
+  } catch {
+    // best-effort
+  }
+
+  return env;
+}
+
+export async function ensureDepsInstalled(dir, label, { quiet = false, env: envIn = process.env } = {}) {
   const pkgJson = join(dir, 'package.json');
   if (!(await pathExists(pkgJson))) {
     return;
@@ -84,8 +165,12 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
 
   const nodeModules = join(dir, 'node_modules');
   const pnpmModulesMeta = join(dir, 'node_modules', '.modules.yaml');
-  const pm = await getComponentPm(dir);
   const stdio = quiet ? 'ignore' : 'inherit';
+  const env = await applyStackCacheEnv(envIn);
+  const pm = await getComponentPm(dir, env);
+  if (pm.name === 'yarn') {
+    await ensureYarnReady({ dir, env, quiet });
+  }
 
   if (await pathExists(nodeModules)) {
     const yarnLock = join(dir, 'yarn.lock');
@@ -100,7 +185,7 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
         console.log(`[local] converting ${label} dependencies back to yarn (reinstalling node_modules)...`);
       }
       await rm(nodeModules, { recursive: true, force: true });
-      await run(pm.cmd, ['install'], { cwd: dir, stdio });
+      await run(pm.cmd, ['install'], { cwd: dir, stdio, env });
     }
 
     // If dependencies changed since the last install, re-run install even if node_modules exists.
@@ -145,7 +230,7 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
           // eslint-disable-next-line no-console
           console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json/patches changed)...`);
         }
-        await run(pm.cmd, ['install'], { cwd: dir, stdio });
+        await run(pm.cmd, ['install'], { cwd: dir, stdio, env });
       }
     }
 
@@ -157,7 +242,7 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
           // eslint-disable-next-line no-console
           console.log(`[local] refreshing ${label} dependencies (pnpm-lock changed)...`);
         }
-        await run(pm.cmd, ['install'], { cwd: dir, stdio });
+        await run(pm.cmd, ['install'], { cwd: dir, stdio, env });
       }
     }
 
@@ -168,7 +253,7 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
     // eslint-disable-next-line no-console
     console.log(`[local] installing ${label} dependencies (first run)...`);
   }
-  await run(pm.cmd, ['install'], { cwd: dir, stdio });
+  await run(pm.cmd, ['install'], { cwd: dir, stdio, env });
 }
 
 export async function ensureCliBuilt(cliDir, { buildCli }) {
@@ -329,11 +414,15 @@ export async function pmExecBin(dirOrOpts, binArg, argsArg, optsArg) {
   const bin = usesObjectStyle ? dirOrOpts.bin : binArg;
   const args = usesObjectStyle ? (dirOrOpts.args ?? []) : (argsArg ?? []);
 
-  const env = usesObjectStyle ? (dirOrOpts.env ?? process.env) : (optsArg?.env ?? process.env);
+  const envIn = usesObjectStyle ? (dirOrOpts.env ?? process.env) : (optsArg?.env ?? process.env);
+  const env = await applyStackCacheEnv(envIn);
   const quiet = usesObjectStyle ? Boolean(dirOrOpts.quiet) : Boolean(optsArg?.quiet);
   const stdio = quiet ? 'ignore' : 'inherit';
 
-  const pm = await getComponentPm(dir);
+  const pm = await getComponentPm(dir, env);
+  if (pm.name === 'yarn') {
+    await ensureYarnReady({ dir, env, quiet });
+  }
   if (pm.name === 'yarn') {
     await run(pm.cmd, ['run', bin, ...args], { cwd: dir, env, stdio });
     return;
@@ -350,11 +439,15 @@ export async function pmSpawnBin(dir, label, bin, args, { env = process.env } =
   const componentEnv = usesObjectStyle ? (dir.env ?? process.env) : (env ?? process.env);
   const options = usesObjectStyle ? (dir.options ?? {}) : {};
 
-  const pm = await getComponentPm(componentDir);
+  const effectiveEnv = await applyStackCacheEnv(componentEnv);
+  const pm = await getComponentPm(componentDir, effectiveEnv);
   if (pm.name === 'yarn') {
-    return spawnProc(componentLabel, pm.cmd, ['run', componentBin, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
+    await ensureYarnReady({ dir: componentDir, env: effectiveEnv, quiet: false });
   }
-  return spawnProc(componentLabel, pm.cmd, ['exec', componentBin, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
+  if (pm.name === 'yarn') {
+    return spawnProc(componentLabel, pm.cmd, ['run', componentBin, ...componentArgs], effectiveEnv, { cwd: componentDir, ...options });
+  }
+  return spawnProc(componentLabel, pm.cmd, ['exec', componentBin, ...componentArgs], effectiveEnv, { cwd: componentDir, ...options });
 }
 
 export async function pmSpawnScript(dir, label, script, args, { env = process.env } = {}) {
@@ -366,9 +459,13 @@ export async function pmSpawnScript(dir, label, script, args, { env = process.en
   const componentEnv = usesObjectStyle ? (dir.env ?? process.env) : (env ?? process.env);
   const options = usesObjectStyle ? (dir.options ?? {}) : {};
 
-  const pm = await getComponentPm(componentDir);
+  const effectiveEnv = await applyStackCacheEnv(componentEnv);
+  const pm = await getComponentPm(componentDir, effectiveEnv);
+  if (pm.name === 'yarn') {
+    await ensureYarnReady({ dir: componentDir, env: effectiveEnv, quiet: false });
+  }
   if (pm.name === 'yarn') {
-    return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
+    return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], effectiveEnv, { cwd: componentDir, ...options });
   }
-  return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
+  return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], effectiveEnv, { cwd: componentDir, ...options });
 }

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

@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { pmSpawnBin, pmSpawnScript } from './pm.mjs';
+
+async function writeJson(path, obj) {
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+async function waitExit(child) {
+  return await new Promise((resolve) => {
+    child.on('exit', (code, signal) => resolve({ code, signal }));
+  });
+}
+
+async function writeStubYarn({ binDir }) {
+  await mkdir(binDir, { recursive: true });
+  const yarnPath = join(binDir, 'yarn');
+  await writeFile(
+    yarnPath,
+    [
+      '#!/usr/bin/env node',
+      'const args = process.argv.slice(2);',
+      // ensureYarnReady calls: yarn --version
+      "if (args.includes('--version')) { console.log('1.22.22'); process.exit(0); }",
+      // pmSpawn* calls: yarn run <script/bin> ...
+      'if (args[0] === "run") process.exit(0);',
+      'process.exit(0);',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(yarnPath, 0o755);
+}
+
+test('pmSpawnScript does not reference effectiveEnv before initialization', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-spawn-script-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const componentDir = join(root, 'component');
+  await mkdir(componentDir, { recursive: true });
+  await writeJson(join(componentDir, 'package.json'), { name: 'component', version: '0.0.0' });
+  await writeFile(join(componentDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+
+  const binDir = join(root, 'bin');
+  await writeStubYarn({ binDir });
+
+  const env = { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` };
+  const child = await pmSpawnScript(componentDir, 'spawn-test', 'noop', [], { env });
+  const res = await waitExit(child);
+  assert.equal(res.code, 0);
+});
+
+test('pmSpawnBin does not reference effectiveEnv before initialization', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-spawn-bin-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const componentDir = join(root, 'component');
+  await mkdir(componentDir, { recursive: true });
+  await writeJson(join(componentDir, 'package.json'), { name: 'component', version: '0.0.0' });
+  await writeFile(join(componentDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+
+  const binDir = join(root, 'bin');
+  await writeStubYarn({ binDir });
+
+  const env = { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` };
+  const child = await pmSpawnBin(componentDir, 'spawn-test', 'prisma', ['generate'], { env });
+  const res = await waitExit(child);
+  assert.equal(res.code, 0);
+});

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

@@ -0,0 +1,142 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { ensureDepsInstalled, pmExecBin } from './pm.mjs';
+
+async function writeYarnEnvDumpStub({ binDir, outputPath }) {
+  await mkdir(binDir, { recursive: true });
+  const yarnPath = join(binDir, 'yarn');
+  await writeFile(
+    yarnPath,
+    [
+      '#!/usr/bin/env node',
+      "const { writeFileSync } = require('node:fs');",
+      "const out = {",
+      '  XDG_CACHE_HOME: process.env.XDG_CACHE_HOME ?? null,',
+      '  YARN_CACHE_FOLDER: process.env.YARN_CACHE_FOLDER ?? null,',
+      '  npm_config_cache: process.env.npm_config_cache ?? null,',
+      '};',
+      "writeFileSync(process.env.OUTPUT_PATH, JSON.stringify(out, null, 2) + '\\n');",
+      'process.exit(0);',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(yarnPath, 0o755);
+  await writeFile(outputPath, '', 'utf-8');
+}
+
+function expectedCacheEnv({ envPath }) {
+  const base = join(dirname(envPath), 'cache');
+  return {
+    xdg: join(base, 'xdg'),
+    yarn: join(base, 'yarn'),
+    npm: join(base, 'npm'),
+  };
+}
+
+async function withEnv(vars, fn) {
+  const old = {};
+  for (const k of Object.keys(vars)) old[k] = process.env[k];
+  try {
+    for (const [k, v] of Object.entries(vars)) {
+      if (v == null) delete process.env[k];
+      else process.env[k] = String(v);
+    }
+    return await fn();
+  } finally {
+    for (const [k, v] of Object.entries(old)) {
+      if (v == null) delete process.env[k];
+      else process.env[k] = v;
+    }
+  }
+}
+
+test('ensureDepsInstalled sets stack-scoped cache env vars for yarn installs', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-stack-cache-install-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const stackDir = join(root, 'stacks', 'exp1');
+  const envPath = join(stackDir, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(envPath, 'HAPPY_STACKS_STACK=exp1\n', 'utf-8');
+
+  const componentDir = join(root, 'component');
+  await mkdir(componentDir, { recursive: true });
+  await writeFile(join(componentDir, 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(componentDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+
+  const binDir = join(root, 'bin');
+  const outputPath = join(root, 'env.json');
+  await writeYarnEnvDumpStub({ binDir, outputPath });
+
+  const exp = expectedCacheEnv({ envPath });
+  const oldPath = process.env.PATH;
+
+  await withEnv(
+    {
+      PATH: `${binDir}:${oldPath ?? ''}`,
+      OUTPUT_PATH: outputPath,
+      HAPPY_STACKS_ENV_FILE: envPath,
+      HAPPY_LOCAL_ENV_FILE: envPath,
+      XDG_CACHE_HOME: null,
+      YARN_CACHE_FOLDER: null,
+      npm_config_cache: null,
+    },
+    async () => {
+      await ensureDepsInstalled(componentDir, 'test-component', { quiet: true });
+      const parsed = JSON.parse(await readFile(outputPath, 'utf-8'));
+      assert.equal(parsed.XDG_CACHE_HOME, exp.xdg);
+      assert.equal(parsed.YARN_CACHE_FOLDER, exp.yarn);
+      assert.equal(parsed.npm_config_cache, exp.npm);
+    }
+  );
+});
+
+test('pmExecBin sets stack-scoped cache env vars for yarn runs', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-stack-cache-exec-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const stackDir = join(root, 'stacks', 'exp1');
+  const envPath = join(stackDir, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(envPath, 'HAPPY_STACKS_STACK=exp1\n', 'utf-8');
+
+  const componentDir = join(root, 'component');
+  await mkdir(componentDir, { recursive: true });
+  await writeFile(join(componentDir, 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(componentDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+
+  const binDir = join(root, 'bin');
+  const outputPath = join(root, 'env.json');
+  await writeYarnEnvDumpStub({ binDir, outputPath });
+
+  const exp = expectedCacheEnv({ envPath });
+  const oldPath = process.env.PATH;
+
+  await withEnv(
+    {
+      PATH: `${binDir}:${oldPath ?? ''}`,
+      OUTPUT_PATH: outputPath,
+      HAPPY_STACKS_ENV_FILE: envPath,
+      HAPPY_LOCAL_ENV_FILE: envPath,
+      XDG_CACHE_HOME: null,
+      YARN_CACHE_FOLDER: null,
+      npm_config_cache: null,
+    },
+    async () => {
+      await pmExecBin({ dir: componentDir, bin: 'prisma', args: ['generate'], env: process.env, quiet: true });
+      const parsed = JSON.parse(await readFile(outputPath, 'utf-8'));
+      assert.equal(parsed.XDG_CACHE_HOME, exp.xdg);
+      assert.equal(parsed.YARN_CACHE_FOLDER, exp.yarn);
+      assert.equal(parsed.npm_config_cache, exp.npm);
+    }
+  );
+});
+

package/scripts/utils/proc/proc.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
 
 function nextLineBreakIndex(s) {
   const n = s.indexOf('\n');
@@ -80,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(() => {
@@ -148,13 +165,46 @@ export async function runCapture(cmd, args, options = {}) {
 }
 
 export async function runCaptureResult(cmd, args, options = {}) {
-  const { timeoutMs, ...spawnOptions } = 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 t =
+    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 {
@@ -162,7 +212,7 @@ export async function runCaptureResult(cmd, args, options = {}) {
             } catch {
               // ignore
             }
-            resolvePromise({
+            resolveWith({
               ok: false,
               exitCode: null,
               signal: null,
@@ -175,11 +225,19 @@ export async function runCaptureResult(cmd, args, options = {}) {
             });
           }, timeoutMs)
         : null;
-    proc.stdout?.on('data', (d) => (out += d.toString()));
-    proc.stderr?.on('data', (d) => (err += d.toString()));
+    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);
-      resolvePromise({
+      resolveWith({
         ok: false,
         exitCode: null,
         signal: null,
@@ -193,7 +251,7 @@ export async function runCaptureResult(cmd, args, options = {}) {
     });
     proc.on('close', (code, signal) => {
       if (t) clearTimeout(t);
-      resolvePromise({
+      resolveWith({
         ok: code === 0,
         exitCode: code,
         signal: signal ?? null,
@@ -206,4 +264,4 @@ export async function runCaptureResult(cmd, args, options = {}) {
       });
     });
   });
-}
+}

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
+    }
+  }
+});