@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/tauri_dev.test.mjs

@@ -0,0 +1,117 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+
+const execFileAsync = promisify(execFile);
+
+test('tauri_dev --json prints the resolved launch plan without running build hooks', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const scriptPath = join(scriptsDir, 'tauri_dev.mjs');
+
+  const { stdout, stderr } = await execFileAsync(process.execPath, [scriptPath, '--json'], {
+    cwd: dirname(scriptsDir),
+    env: {
+      ...process.env,
+      HAPPIER_STACK_TAURI_WAIT_FOR_EXPO: '0',
+    },
+    encoding: 'utf8',
+  });
+
+  assert.equal(String(stderr ?? '').trim(), '');
+  assert.equal(String(stdout ?? '').trim().startsWith('{'), true);
+  assert.equal(stdout.includes('yarn run'), false);
+  assert.equal(stdout.includes('prepareTauriSidecar'), false);
+
+  const payload = JSON.parse(stdout);
+  assert.equal(payload?.ok, true);
+  assert.equal(typeof payload?.devUrl, 'string');
+  const normalizedConfigPath = String(payload?.configPath ?? '').trim().replaceAll('\\', '/');
+  assert.equal(normalizedConfigPath.endsWith('/apps/ui/src-tauri/tauri.publicdev.conf.json'), true);
+});
+
+test('tauri_dev fails fast with a clear error when repo dir does not contain src-tauri', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const scriptPath = join(scriptsDir, 'tauri_dev.mjs');
+
+  const fakeRepo = await mkdir(join(tmpdir(), `happier-tauri-dev-missing-repo-${Date.now()}`), { recursive: true });
+
+  let stderr = '';
+  try {
+    await execFileAsync(process.execPath, [scriptPath], {
+      cwd: dirname(scriptsDir),
+      env: {
+        ...process.env,
+        HAPPIER_STACK_TAURI_WAIT_FOR_EXPO: '0',
+        HAPPIER_STACK_REPO_DIR: fakeRepo,
+      },
+      encoding: 'utf8',
+    });
+    assert.fail('expected tauri_dev to fail');
+  } catch (error) {
+    stderr = String(error?.stderr ?? '');
+  }
+
+  assert.match(
+    stderr,
+    /\[tauri-dev\] failed: \[tauri-dev\] expected a Happier repo checkout containing apps\/ui\/src-tauri/i
+  );
+});
+
+test('tauri_dev falls back to HAPPIER_STACK_CLI_ROOT_DIR when HAPPIER_STACK_REPO_DIR is misconfigured', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const repoRoot = dirname(scriptsDir);
+  const scriptPath = join(scriptsDir, 'tauri_dev.mjs');
+  const fakeRepo = await mkdir(join(tmpdir(), `happier-tauri-dev-bad-repo-${Date.now()}`), { recursive: true });
+
+  const { stdout, stderr } = await execFileAsync(process.execPath, [scriptPath, '--json'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      HAPPIER_STACK_TAURI_WAIT_FOR_EXPO: '0',
+      HAPPIER_STACK_REPO_DIR: fakeRepo,
+      HAPPIER_STACK_CLI_ROOT_DIR: repoRoot,
+      HAPPIER_STACK_CLI_ROOT_DISABLE: '1',
+    },
+    encoding: 'utf8',
+  });
+
+  assert.equal(String(stderr ?? '').trim(), '');
+  const payload = JSON.parse(stdout);
+  assert.equal(payload?.ok, true);
+  const normalizedUiDir = String(payload?.uiDir ?? '').replaceAll('\\', '/');
+  assert.equal(normalizedUiDir.endsWith('/apps/ui'), true);
+  const normalizedTauriCwd = String(payload?.tauri?.cwd ?? '').replaceAll('\\', '/');
+  assert.equal(normalizedTauriCwd.endsWith('/apps/ui/src-tauri'), true);
+  const normalizedTauriArgs = Array.isArray(payload?.tauri?.args) ? payload.tauri.args.map((arg) => String(arg).replaceAll('\\', '/')) : [];
+  assert.equal(normalizedTauriArgs.some((arg) => arg.endsWith('/node_modules/@tauri-apps/cli/tauri.js')), true);
+});
+
+test('tauri_dev --json falls back to the CLI root repo when the stack repo dir is missing src-tauri', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const scriptPath = join(scriptsDir, 'tauri_dev.mjs');
+  const repoRoot = dirname(scriptsDir);
+
+  const fakeRepo = await mkdir(join(tmpdir(), `happier-tauri-dev-fallback-repo-${Date.now()}`), { recursive: true });
+
+  const { stdout, stderr } = await execFileAsync(process.execPath, [scriptPath, '--json'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      HAPPIER_STACK_TAURI_WAIT_FOR_EXPO: '0',
+      HAPPIER_STACK_REPO_DIR: fakeRepo,
+      HAPPIER_STACK_CLI_ROOT_DIR: repoRoot,
+    },
+    encoding: 'utf8',
+  });
+
+  assert.equal(String(stderr ?? '').trim(), '');
+  const payload = JSON.parse(stdout);
+  assert.equal(payload?.ok, true);
+  const normalizedConfigPath = String(payload?.configPath ?? '').trim().replaceAll('\\', '/');
+  assert.equal(normalizedConfigPath.endsWith('/apps/ui/src-tauri/tauri.publicdev.conf.json'), true);
+});

package/scripts/test_ci.mjs

@@ -1,23 +1,26 @@
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { collectTestFiles } from './utils/test/collect_test_files.mjs';
+import { collectStackUnitTestFiles } from './utils/test/test_collection.mjs';
+import { runNodeTestFilesSync } from './utils/test/test_process.mjs';
+import { ensureWorkspacePackagesBuiltForComponent } from './utils/proc/pm.mjs';
+import { coerceHappyMonorepoRootFromPath } from './utils/paths/paths.mjs';
+import { bundleWorkspaceDeps } from './bundleWorkspaceDeps.mjs';
 
 async function main() {
-  const packageRoot = fileURLToPath(new URL('..', import.meta.url));
-  const scriptsDir = join(packageRoot, 'scripts');
-  const testsDir = join(packageRoot, 'tests');
+  const { packageRoot, scriptsDir, testsDir, testFiles } = await collectStackUnitTestFiles(import.meta.url, {
+    collect: collectTestFiles,
+  });
 
-  const testFiles = [];
-  testFiles.push(...(await collectTestFiles({
-    dir: scriptsDir,
-    includeSuffixes: ['.test.mjs'],
-    excludeSuffixes: ['.integration.test.mjs', '.real.integration.test.mjs'],
-  })));
-  testFiles.push(...(await collectTestFiles({
-    dir: testsDir,
-    includeSuffixes: ['.test.mjs'],
-    excludeSuffixes: ['.integration.test.mjs', '.real.integration.test.mjs'],
-  })));
+  // Stack scripts import internal workspace packages via `exports` pointing at `dist/**`.
+  // Ensure those packages are built so `node --test` can execute stack scripts in a fresh checkout.
+  await ensureWorkspacePackagesBuiltForComponent(packageRoot, { quiet: true, env: process.env });
+
+  // Stack unit tests execute `bin/hstack.mjs`, which runs as if `@happier-dev/stack` were installed
+  // from npm with bundled internal deps. Ensure those bundled deps exist and have their external
+  // runtime dependency trees vendored (e.g. `zod` for `@happier-dev/agents`).
+  const monorepoRoot = coerceHappyMonorepoRootFromPath(packageRoot);
+  if (monorepoRoot) {
+    await bundleWorkspaceDeps({ repoRoot: monorepoRoot, stackDir: packageRoot });
+  }
 
   if (testFiles.length === 0) {
     process.stderr.write(`[stack:test] no .test.mjs files found under ${scriptsDir} or ${testsDir}\n`);
@@ -25,8 +28,9 @@ async function main() {
   }
 
   // Node 20 does not expand globs for `--test`, so we enumerate files.
-  const { spawnSync } = await import('node:child_process');
-  const res = spawnSync(process.execPath, ['--test', ...testFiles], { stdio: 'inherit' });
+  // Run serially: stack tests spawn real `node` subprocesses and mutate local fixture dirs; running
+  // them concurrently makes failures non-deterministic (and can race bundled-deps preparation).
+  const res = runNodeTestFilesSync(testFiles, { cwd: packageRoot, env: process.env, serial: true });
   process.exit(res.status ?? 1);
 }
 

package/scripts/test_cmd.mjs

@@ -8,7 +8,9 @@ import { pathExists } from './utils/fs/fs.mjs';
 import { run, runCapture } from './utils/proc/proc.mjs';
 import { detectPackageManagerCmd, pickFirstScript, readPackageJsonScripts } from './utils/proc/package_scripts.mjs';
 import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
-import { readdir, readFile } from 'node:fs/promises';
+import { collectTestFiles } from './utils/test/collect_test_files.mjs';
+import { collectStackUnitTestFiles } from './utils/test/test_collection.mjs';
+import { readFile } from 'node:fs/promises';
 import { dirname, join, sep } from 'node:path';
 
 const EXTRA_COMPONENTS = ['stacks'];
@@ -56,25 +58,6 @@ function normalizeTargetsOrThrow(rawTargets) {
   return mapped;
 }
 
-async function collectTestFiles(dir) {
-  const entries = await readdir(dir, { withFileTypes: true });
-  const files = [];
-  for (const e of entries) {
-    // Avoid dot-dirs and dot-files (e.g. .DS_Store).
-    if (e.name.startsWith('.')) continue;
-    const p = join(dir, e.name);
-    if (e.isDirectory()) {
-      files.push(...(await collectTestFiles(p)));
-      continue;
-    }
-    if (!e.isFile()) continue;
-    if (!e.name.endsWith('.test.mjs')) continue;
-    files.push(p);
-  }
-  files.sort();
-  return files;
-}
-
 function pickTestScript(scripts) {
   const candidates = [
     'test',
@@ -179,10 +162,11 @@ async function main() {
         // Note: do not rely on shell glob expansion here.
         // Node 20 does not expand globs for `--test`, and bash/sh won't expand globs inside quotes.
         // Enumerate files ourselves so this works reliably in CI.
-        const scriptsDir = join(rootDir, 'scripts');
-        const testFiles = await collectTestFiles(scriptsDir);
+        const { scriptsDir, testsDir, testFiles } = await collectStackUnitTestFiles(import.meta.url, {
+          collect: collectTestFiles,
+        });
         if (testFiles.length === 0) {
-          throw new Error(`[test] stacks: no test files found under ${scriptsDir}`);
+          throw new Error(`[test] stacks: no test files found under ${scriptsDir} or ${testsDir}`);
         }
         await run(process.execPath, ['--test', ...testFiles], { cwd: rootDir, env: process.env });
         results.push({ target, ok: true, skipped: false, dir: rootDir, pm: 'node', script: '--test' });

package/scripts/test_cmd.test.mjs

@@ -1,22 +1,12 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-function runNode(args, { cwd, env }) {
-  return new Promise((resolve, reject) => {
-    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    proc.stdout.on('data', (d) => (stdout += String(d)));
-    proc.stderr.on('data', (d) => (stderr += String(d)));
-    proc.on('error', reject);
-    proc.on('exit', (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), signal: signal ?? null, stdout, stderr }));
-  });
-}
+import { buildStackHarnessEnv, writeFakeBin } from './testkit/core/fake_bin_harness.mjs';
+import { runNodeCapture } from './testkit/core/run_node_capture.mjs';
+import { createTempFixture } from './testkit/core/temp_fixture.mjs';
 
 async function writeYarnOkPackage({ dir, name, scriptOutput }) {
   await mkdir(join(dir, 'node_modules'), { recursive: true });
@@ -42,31 +32,52 @@ async function writeYarnOkPackage({ dir, name, scriptOutput }) {
   await writeFile(join(dir, 'node_modules', '.yarn-integrity'), 'ok\n', 'utf-8');
 }
 
+async function writeFakeYarn({ dir }) {
+  return writeFakeBin({
+    root: dir,
+    name: 'yarn',
+    content: [
+      '#!/usr/bin/env node',
+      "const args = process.argv.slice(2);",
+      "if (args[0] === '-s') args.shift();",
+      "if (args[0] !== 'test') process.exit(0);",
+      "const { spawnSync } = require('node:child_process');",
+      "const { readFileSync } = require('node:fs');",
+      "const pkg = JSON.parse(readFileSync('package.json', 'utf8'));",
+      "const command = String(pkg.scripts.test || '');",
+      "const parts = command.split(/\\s+/).filter(Boolean);",
+      "const res = spawnSync(parts[0], parts.slice(1), { stdio: 'inherit' });",
+      "process.exit(res.status == null ? 1 : res.status);",
+    ].join('\n'),
+  });
+}
+
 async function setupTestCmdFixture({ importMetaUrl, t, tmpPrefix }) {
   const scriptsDir = dirname(fileURLToPath(importMetaUrl));
   const rootDir = dirname(scriptsDir);
 
-  const tmp = await mkdtemp(join(tmpdir(), tmpPrefix));
-  t.after(async () => {
-    await rm(tmp, { recursive: true, force: true }).catch(() => {});
-  });
+  const fixture = await createTempFixture(t, { prefix: tmpPrefix });
+  const tmp = fixture.root;
 
   const monoRoot = join(tmp, 'mono');
   const appDir = join(monoRoot, 'apps', 'ui');
+  const { binDir } = await writeFakeYarn({ dir: tmp });
 
   await mkdir(appDir, { recursive: true });
 
   await writeYarnOkPackage({ dir: monoRoot, name: 'monorepo', scriptOutput: 'ROOT_TEST_RUN' });
   await writeYarnOkPackage({ dir: appDir, name: 'happy-app', scriptOutput: 'APP_TEST_RUN' });
 
-  const env = {
-    ...process.env,
-    HAPPIER_STACK_REPO_DIR: monoRoot,
-    // Prevent env.mjs from auto-discovering and loading a real machine stack env file,
-    // which would overwrite our component dir override.
-    HAPPIER_STACK_STACK: 'test-stack',
-    HAPPIER_STACK_ENV_FILE: join(tmp, 'nonexistent-env'),
-  };
+  const env = buildStackHarnessEnv({
+    binDirs: [binDir],
+    extraEnv: {
+      HAPPIER_STACK_REPO_DIR: monoRoot,
+      // Prevent env.mjs from auto-discovering and loading a real machine stack env file,
+      // which would overwrite our component dir override.
+      HAPPIER_STACK_STACK: 'test-stack',
+      HAPPIER_STACK_ENV_FILE: join(tmp, 'nonexistent-env'),
+    },
+  });
 
   return { rootDir, monoRoot, appDir, env };
 }
@@ -78,7 +89,7 @@ test('hstack test --json keeps stdout JSON-only and runs monorepo root when happ
     tmpPrefix: 'happy-stacks-test-cmd-json-',
   });
 
-  const res = await runNode([join(fixture.rootDir, 'scripts', 'test_cmd.mjs'), 'ui', '--json'], {
+  const res = await runNodeCapture([join(fixture.rootDir, 'scripts', 'test_cmd.mjs'), 'ui', '--json'], {
     cwd: fixture.rootDir,
     env: fixture.env,
   });
@@ -119,7 +130,7 @@ test('hstack test (non-json) keeps monorepo-root routing and reports human-reada
     tmpPrefix: 'happy-stacks-test-cmd-text-',
   });
 
-  const res = await runNode([join(fixture.rootDir, 'scripts', 'test_cmd.mjs'), 'ui'], {
+  const res = await runNodeCapture([join(fixture.rootDir, 'scripts', 'test_cmd.mjs'), 'ui'], {
     cwd: fixture.rootDir,
     env: fixture.env,
   });

package/scripts/test_integration.mjs

@@ -1,30 +1,43 @@
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { collectTestFiles } from './utils/test/collect_test_files.mjs';
+import { collectStackIntegrationTestFiles } from './utils/test/test_collection.mjs';
+import {
+  formatRealIntegrationSkipMessage,
+  resolveIntegrationRunPlan,
+} from './utils/test/integration_test_runner.mjs';
+import { runNodeTestFilesSync } from './utils/test/test_process.mjs';
 
 async function main() {
-  const packageRoot = fileURLToPath(new URL('..', import.meta.url));
-  const scriptsDir = join(packageRoot, 'scripts');
-  const testsDir = join(packageRoot, 'tests');
-
-  const testFiles = [];
-  testFiles.push(...(await collectTestFiles({
-    dir: scriptsDir,
-    includeSuffixes: ['.integration.test.mjs', '.real.integration.test.mjs'],
-  })));
-  testFiles.push(...(await collectTestFiles({
-    dir: testsDir,
-    includeSuffixes: ['.integration.test.mjs', '.real.integration.test.mjs'],
-  })));
+  const { packageRoot, scriptsDir, testsDir, testFiles } = await collectStackIntegrationTestFiles(import.meta.url, {
+    collect: collectTestFiles,
+  });
 
   if (testFiles.length === 0) {
     process.stdout.write('[stack:test:integration] no integration test files found; skipping\n');
     process.exit(0);
   }
 
-  const { spawnSync } = await import('node:child_process');
-  const res = spawnSync(process.execPath, ['--test', ...testFiles], { stdio: 'inherit' });
-  process.exit(res.status ?? 1);
+  const { regular, real, runReal } = resolveIntegrationRunPlan(testFiles, process.env);
+
+  if (regular.length > 0) {
+    // Stack integration files share mutable workspace build artifacts and bundled runtime outputs.
+    // Run them serially to avoid races between files that rebuild or resync those artifacts.
+    const res = runNodeTestFilesSync(regular, { cwd: packageRoot, env: process.env, serial: true });
+    if ((res.status ?? 1) !== 0) process.exit(res.status ?? 1);
+  }
+
+  if (real.length > 0 && !runReal) {
+    process.stdout.write(formatRealIntegrationSkipMessage(real.length));
+    process.exit(0);
+  }
+
+  // Real integration tests may install/uninstall OS services and build global release assets,
+  // which is not safe under Node's default parallel test file execution.
+  for (const file of real) {
+    const res = runNodeTestFilesSync([file], { cwd: packageRoot, env: process.env, serial: true });
+    if ((res.status ?? 1) !== 0) process.exit(res.status ?? 1);
+  }
+
+  process.exit(0);
 }
 
 main().catch((e) => {

package/scripts/testkit/auth_testkit.mjs

@@ -1,60 +1,25 @@
 import { spawn } from 'node:child_process';
-import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 
-function sanitizeEnv(env) {
-  if (!env) return undefined;
-  const clean = {};
-  for (const [key, value] of Object.entries(env)) {
-    if (value == null) continue;
-    clean[key] = String(value);
-  }
-  return clean;
-}
+import { buildStackFixtureEnv } from './core/env_scope.mjs';
+import { runNodeCapture as runNodeCaptureCore } from './core/run_node_capture.mjs';
+import { resolveHstackBinPath, resolveStackRootFromMeta, resolveStackScriptPath } from './core/stack_root.mjs';
+import { createTempFixture } from './core/temp_fixture.mjs';
 
 export function getStackRootFromMeta(metaUrl) {
-  const scriptsDir = dirname(fileURLToPath(metaUrl));
-  return dirname(scriptsDir);
+  return resolveStackRootFromMeta(metaUrl);
 }
 
 export function hstackBinPath(rootDir) {
-  return join(rootDir, 'bin', 'hstack.mjs');
+  return resolveHstackBinPath(rootDir);
 }
 
 export function authScriptPath(rootDir) {
-  return join(rootDir, 'scripts', 'auth.mjs');
+  return resolveStackScriptPath(rootDir, 'auth.mjs');
 }
 
-export async function runNodeCapture(args, { cwd, env, input } = {}) {
-  return await new Promise((resolve, reject) => {
-    const usePipeInput = input != null;
-    const proc = spawn(process.execPath, args, {
-      cwd,
-      env: sanitizeEnv(env),
-      stdio: [usePipeInput ? 'pipe' : 'ignore', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-    proc.stdout.on('data', (chunk) => {
-      stdout += String(chunk);
-    });
-    proc.stderr.on('data', (chunk) => {
-      stderr += String(chunk);
-    });
-    proc.on('error', reject);
-    proc.on('close', (code, signal) => {
-      resolve({ code: code ?? (signal ? 128 : 0), signal, stdout, stderr });
-    });
-
-    if (usePipeInput) {
-      proc.stdin.write(String(input));
-      proc.stdin.end();
-    }
-  });
-}
+export const runNodeCapture = runNodeCaptureCore;
 
 function wait(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -91,11 +56,13 @@ export async function terminateChildProcess(child, { signal = 'SIGTERM', timeout
 }
 
 export async function createAuthStackFixture({
+  t,
   prefix,
   stackName = 'main',
   stackEnvLines = [],
 }) {
-  const tmpDir = await mkdtemp(join(tmpdir(), prefix));
+  const fixture = await createTempFixture(t, { prefix });
+  const tmpDir = fixture.root;
   const storageDir = join(tmpDir, 'storage');
   await mkdir(join(storageDir, stackName), { recursive: true });
   const envPath = join(storageDir, stackName, 'env');
@@ -106,16 +73,15 @@ export async function createAuthStackFixture({
     storageDir,
     envPath,
     buildEnv(extra = {}) {
-      return {
-        ...process.env,
-        HAPPIER_STACK_STORAGE_DIR: storageDir,
-        HAPPIER_STACK_STACK: stackName,
-        HAPPIER_STACK_ENV_FILE: envPath,
-        ...extra,
-      };
+      return buildStackFixtureEnv({
+        storageDir,
+        stackName,
+        envPath,
+        extraEnv: extra,
+      });
     },
     async cleanup() {
-      await rm(tmpDir, { recursive: true, force: true });
+      await fixture.cleanup();
     },
   };
 }

package/scripts/testkit/core/env_scope.mjs

@@ -0,0 +1,88 @@
+import { delimiter } from 'node:path';
+
+import { sanitizeDefinedEnv } from '../../utils/test/test_env.mjs';
+
+export function buildStackFixtureEnv({
+  baseEnv = process.env,
+  homeDir,
+  storageDir,
+  workspaceDir,
+  sandboxDir,
+  stackName,
+  envPath,
+  stripStackEnv = false,
+  extraEnv = {},
+} = {}) {
+  const seed = stripStackEnv
+    ? Object.fromEntries(Object.entries(baseEnv ?? {}).filter(([key]) => !key.startsWith('HAPPIER_STACK_')))
+    : { ...(baseEnv ?? {}) };
+
+  return sanitizeDefinedEnv({
+    ...seed,
+    ...(homeDir ? { HAPPIER_STACK_HOME_DIR: homeDir } : {}),
+    ...(storageDir ? { HAPPIER_STACK_STORAGE_DIR: storageDir } : {}),
+    ...(workspaceDir ? { HAPPIER_STACK_WORKSPACE_DIR: workspaceDir } : {}),
+    ...(sandboxDir ? { HAPPIER_STACK_SANDBOX_DIR: sandboxDir } : {}),
+    ...(stackName ? { HAPPIER_STACK_STACK: stackName } : {}),
+    ...(envPath ? { HAPPIER_STACK_ENV_FILE: envPath } : {}),
+    ...extraEnv,
+  });
+}
+
+export function buildGitIdentityEnv({ baseEnv = process.env, stripStackEnv = true, extraEnv = {} } = {}) {
+  return buildStackFixtureEnv({
+    baseEnv,
+    stripStackEnv,
+    extraEnv: {
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 'test@example.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 'test@example.com',
+      ...extraEnv,
+    },
+  });
+}
+
+export function prependPathEntries(env = process.env, entries = []) {
+  const cleanEnv = sanitizeDefinedEnv(env);
+  const currentEntries = (cleanEnv.PATH ?? '')
+    .split(delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const nextEntries = [...entries, ...currentEntries].map((entry) => String(entry ?? '').trim()).filter(Boolean);
+  cleanEnv.PATH = [...new Set(nextEntries)].join(delimiter);
+  return cleanEnv;
+}
+
+export function filterEnvForSpawn(env = process.env, { keepKeys = [], keepPrefixes = [] } = {}) {
+  const cleanEnv = {};
+  for (const key of keepKeys) {
+    const value = env?.[key];
+    if (value == null) continue;
+    cleanEnv[key] = String(value);
+  }
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (key in cleanEnv) continue;
+    if (value == null) continue;
+    if (!keepPrefixes.some((prefix) => key.startsWith(prefix))) continue;
+    cleanEnv[key] = String(value);
+  }
+  return cleanEnv;
+}
+
+export function withPatchedProcessEnv(t, overrides = {}) {
+  const previous = new Map();
+  for (const [key, value] of Object.entries(overrides)) {
+    previous.set(key, Object.prototype.hasOwnProperty.call(process.env, key) ? process.env[key] : undefined);
+    if (value == null) delete process.env[key];
+    else process.env[key] = String(value);
+  }
+  const restore = () => {
+    for (const [key, value] of previous.entries()) {
+      if (value == null) delete process.env[key];
+      else process.env[key] = value;
+    }
+  };
+  if (t?.after) t.after(restore);
+  return restore;
+}

package/scripts/testkit/core/fake_bin_harness.mjs

@@ -0,0 +1,53 @@
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { prependPathEntries } from './env_scope.mjs';
+
+const STACK_TEST_PATH_FALLBACKS = [
+  '/opt/homebrew/bin',
+  '/opt/homebrew/sbin',
+  '/usr/local/bin',
+  '/usr/bin',
+  '/bin',
+];
+
+export function writeFakeBin({ root, name, content, binDirName = 'bin' }) {
+  const binDir = join(root, binDirName);
+  const binPath = join(binDir, name);
+  mkdirSync(binDir, { recursive: true });
+  writeFileSync(binPath, content, 'utf-8');
+  chmodSync(binPath, 0o755);
+  return { binDir, binPath };
+}
+
+export function writeLoggedJsonBin({
+  root,
+  name,
+  logEnvVar,
+  body = '',
+  binDirName = 'bin',
+} = {}) {
+  return writeFakeBin({
+    root,
+    name,
+    binDirName,
+    content: `#!/usr/bin/env node
+const { appendFileSync } = require('node:fs');
+const log = process.env.${logEnvVar} || '';
+if (log) appendFileSync(log, JSON.stringify({ bin: ${JSON.stringify(name)}, argv: process.argv.slice(2) }) + "\\n", 'utf-8');
+${String(body).trim()}
+`,
+  });
+}
+
+export function buildStackHarnessEnv({
+  baseEnv = process.env,
+  binDirs = [],
+  extraEnv = {},
+} = {}) {
+  const nodeBinDir = dirname(process.execPath);
+  return prependPathEntries({
+    ...(baseEnv ?? {}),
+    ...extraEnv,
+  }, [...binDirs, nodeBinDir, ...STACK_TEST_PATH_FALLBACKS]);
+}