@happier-dev/stack 0.1.0-preview.74.1

package/scripts/utils/dev/expo_dev_verbose_logs.test.mjs

@@ -0,0 +1,60 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile, chmod, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { ensureDevExpoServer } from './expo_dev.mjs';
+
+test('ensureDevExpoServer does not drop Expo output when spawnOptions stdio is ignore', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-verbose-'));
+  try {
+    const uiDir = join(tmp, 'ui');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+    await mkdir(join(uiDir, 'node_modules'), { recursive: true });
+    await writeFile(join(uiDir, 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n', 'utf-8');
+
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await writeFile(
+      expoBin,
+      [
+        '#!/usr/bin/env node',
+        "console.log('hello-from-fake-expo');",
+        "setTimeout(() => process.exit(0), 100);",
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    await chmod(expoBin, 0o755);
+
+    const teeFile = join(tmp, 'expo.log');
+    const children = [];
+    await ensureDevExpoServer({
+      startUi: true,
+      startMobile: false,
+      uiDir,
+      autostart: { baseDir: tmp },
+      baseEnv: { ...process.env, HAPPIER_STACK_VERBOSE: '1' },
+      apiServerUrl: 'http://127.0.0.1:1',
+      restart: true,
+      stackMode: false,
+      runtimeStatePath: null,
+      stackName: 'test',
+      envPath: '',
+      children,
+      spawnOptions: {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        silent: true,
+        teeFile,
+        teeLabel: 'expo',
+      },
+      quiet: true,
+    });
+
+    await delay(400);
+    const log = await readFile(teeFile, 'utf-8').catch(() => '');
+    assert.match(log, /hello-from-fake-expo/);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/dev/server.mjs

@@ -0,0 +1,180 @@
+import { resolve } from 'node:path';
+
+import { ensureDepsInstalled, pmSpawnScript } from '../proc/pm.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { applyServerLightEnvDefaults } from '../server/apply_server_light_env_defaults.mjs';
+import { resolveServerDevScript } from '../server/flavor_scripts.mjs';
+import { waitForServerReady } from '../server/server.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.mjs';
+import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
+import { watchDebounced } from '../proc/watch.mjs';
+import { pickMetroPort, resolveStablePortStart } from '../expo/metro_ports.mjs';
+
+export function resolveStackUiDevPortStart({ env = process.env, stackName }) {
+  return resolveStablePortStart({
+    env: {
+      ...env,
+      HAPPIER_STACK_UI_DEV_PORT_BASE: (env.HAPPIER_STACK_UI_DEV_PORT_BASE ?? '8081').toString(),
+      HAPPIER_STACK_UI_DEV_PORT_RANGE: (env.HAPPIER_STACK_UI_DEV_PORT_RANGE ?? '1000').toString(),
+    },
+    stackName,
+    baseKey: 'HAPPIER_STACK_UI_DEV_PORT_BASE',
+    rangeKey: 'HAPPIER_STACK_UI_DEV_PORT_RANGE',
+    defaultBase: 8081,
+    defaultRange: 1000,
+  });
+}
+
+export async function pickDevMetroPort({ startPort, reservedPorts = new Set(), host = '127.0.0.1' } = {}) {
+  const forcedPort = (process.env.HAPPIER_STACK_UI_DEV_PORT ?? '').toString().trim();
+  return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
+}
+
+export async function startDevServer({
+  serverComponentName,
+  serverDir,
+  autostart,
+  baseEnv,
+  serverPort,
+  internalServerUrl,
+  publicServerUrl,
+  envPath,
+  stackMode,
+  runtimeStatePath,
+  serverAlreadyRunning,
+  restart,
+  children,
+  spawnOptions = {},
+  quiet = false,
+}) {
+  const serverEnv = {
+    ...baseEnv,
+    PORT: String(serverPort),
+    PUBLIC_URL: publicServerUrl,
+    // Avoid noisy failures if a previous run left the metrics port busy.
+    METRICS_ENABLED: baseEnv.METRICS_ENABLED ?? 'false',
+  };
+
+  if (serverComponentName === 'happier-server-light') {
+    applyServerLightEnvDefaults({ baseEnv, serverEnv, baseDir: autostart.baseDir });
+  }
+
+  if (serverComponentName === 'happier-server') {
+    const managed = (baseEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1') !== '0';
+    if (managed) {
+      const infra = await ensureHappyServerManagedInfra({
+        stackName: autostart.stackName,
+        baseDir: autostart.baseDir,
+        serverPort,
+        publicServerUrl,
+        envPath,
+        env: baseEnv,
+      });
+      Object.assign(serverEnv, infra.env);
+    }
+
+    const autoMigrate = (baseEnv.HAPPIER_STACK_PRISMA_MIGRATE ?? '1') !== '0';
+    if (autoMigrate) {
+      await applyHappyServerMigrations({ serverDir, env: serverEnv });
+    }
+  }
+
+  // Ensure server deps exist before any Prisma/docker work.
+  await ensureDepsInstalled(serverDir, serverComponentName, { quiet, env: serverEnv });
+
+  const prismaPush = (baseEnv.HAPPIER_STACK_PRISMA_PUSH ?? '1').toString().trim() !== '0';
+  const serverScript = resolveServerDevScript({ serverComponentName, serverDir, prismaPush });
+
+  // Restart behavior (stack-safe): only kill when we can prove ownership via runtime state.
+  if (restart && stackMode && runtimeStatePath && serverAlreadyRunning) {
+    const st = await readStackRuntimeStateFile(runtimeStatePath);
+    const pid = Number(st?.processes?.serverPid);
+    if (pid > 1) {
+      const res = await killProcessGroupOwnedByStack(pid, { stackName: autostart.stackName, envPath, label: 'server', json: true });
+      if (!res.killed) {
+        // Fail-closed if the port is still occupied.
+        const free = await isTcpPortFree(serverPort, { host: '127.0.0.1' });
+        if (!free) {
+          throw new Error(
+            `[local] restart refused: server port ${serverPort} is occupied and the PID is not provably stack-owned.\n` +
+              `[local] Fix: run 'hstack stack stop ${autostart.stackName}' then re-run, or re-run without --restart.`
+          );
+        }
+      }
+    }
+  }
+
+  if (serverAlreadyRunning && !restart) {
+    return { serverEnv, serverScript, serverProc: null };
+  }
+
+  const server = await pmSpawnScript({
+    label: 'server',
+    dir: serverDir,
+    script: serverScript,
+    env: serverEnv,
+    options: spawnOptions,
+    quiet,
+  });
+  children.push(server);
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: server.pid } }).catch(() => {});
+  }
+  await waitForServerReady(internalServerUrl);
+  return { serverEnv, serverScript, serverProc: server };
+}
+
+export function watchDevServerAndRestart({
+  enabled,
+  stackMode,
+  serverComponentName,
+  serverDir,
+  serverPort,
+  internalServerUrl,
+  serverScript,
+  serverEnv,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  serverProcRef,
+  isShuttingDown,
+}) {
+  if (!enabled) return null;
+
+  // Only watch full server by default; server-light already has a good upstream dev loop.
+  if (serverComponentName !== 'happier-server') return null;
+
+  return watchDebounced({
+    paths: [resolve(serverDir)],
+    debounceMs: 600,
+    onChange: async () => {
+      if (isShuttingDown?.()) return;
+      const pid = Number(serverProcRef?.current?.pid);
+      if (!Number.isFinite(pid) || pid <= 1) return;
+
+      try {
+        // eslint-disable-next-line no-console
+        console.log('[local] watch: server changed → restarting...');
+        await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: 'server', json: false });
+
+        const next = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+        children.push(next);
+        serverProcRef.current = next;
+        if (stackMode && runtimeStatePath) {
+          await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: next.pid } }).catch(() => {});
+        }
+        await waitForServerReady(internalServerUrl);
+        // eslint-disable-next-line no-console
+        console.log(`[local] watch: server restarted (pid=${next.pid}, port=${serverPort})`);
+      } catch (e) {
+        const msg = e instanceof Error ? e.stack || e.message : String(e);
+        // eslint-disable-next-line no-console
+        console.error('[local] watch: server restart failed; keeping existing process as-is (will retry on next change).');
+        // eslint-disable-next-line no-console
+        console.error(msg);
+      }
+    },
+  });
+}

package/scripts/utils/dev_auth_key.mjs

@@ -0,0 +1,7 @@
+import { getHappyStacksHomeDir } from './paths/paths.mjs';
+
+export * from './auth/dev_key.mjs';
+
+export function resolveHappyStacksHomeDir(env = process.env) {
+  return getHappyStacksHomeDir(env);
+}

package/scripts/utils/edison/git_roots.mjs

@@ -0,0 +1,30 @@
+import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+export function findGitRootForPath(dir) {
+  const raw = String(dir ?? '').trim();
+  if (!raw) return '';
+
+  let cur = resolve(raw);
+  while (true) {
+    try {
+      if (existsSync(join(cur, '.git'))) {
+        return cur;
+      }
+    } catch {
+      // ignore
+    }
+    const parent = dirname(cur);
+    if (parent === cur) return '';
+    cur = parent;
+  }
+}
+
+export function normalizeGitRoots(paths) {
+  const list = Array.isArray(paths) ? paths : [];
+  const normalized = list
+    .map((d) => findGitRootForPath(d) || String(d ?? '').trim())
+    .map((d) => resolve(d))
+    .filter(Boolean);
+  return Array.from(new Set(normalized));
+}

package/scripts/utils/edison/git_roots.test.mjs

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { findGitRootForPath, normalizeGitRoots } from './git_roots.mjs';
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-edison-git-roots-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+test('findGitRootForPath returns nearest ancestor containing .git marker', async (t) => {
+  const root = await withTempRoot(t);
+  const repoRoot = join(root, 'repo');
+  await mkdir(join(repoRoot, 'a', 'b'), { recursive: true });
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  assert.equal(findGitRootForPath(join(repoRoot, 'a', 'b')), repoRoot);
+});
+
+test('normalizeGitRoots de-duplicates multiple paths inside the same repo', async (t) => {
+  const root = await withTempRoot(t);
+  const repoRoot = join(root, 'repo');
+  await mkdir(join(repoRoot, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(repoRoot, 'apps', 'cli'), { recursive: true });
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  const roots = normalizeGitRoots([join(repoRoot, 'apps', 'ui'), join(repoRoot, 'apps', 'cli')]);
+  assert.deepEqual(roots, [repoRoot]);
+});
+
+test('findGitRootForPath returns empty string for blank path input', () => {
+  assert.equal(findGitRootForPath(''), '');
+  assert.equal(findGitRootForPath('   '), '');
+});
+
+test('normalizeGitRoots keeps non-repo paths and de-duplicates by resolved absolute path', async (t) => {
+  const root = await withTempRoot(t);
+  const plainDir = join(root, 'plain');
+  await mkdir(plainDir, { recursive: true });
+
+  const roots = normalizeGitRoots([plainDir, join(plainDir, '..', 'plain')]);
+  assert.deepEqual(roots, [plainDir]);
+});

package/scripts/utils/env/config.mjs

@@ -0,0 +1,52 @@
+import { join } from 'node:path';
+import { ensureEnvFileUpdated } from './env_file.mjs';
+import { getHappyStacksHomeDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getCanonicalHomeDirFromEnv } from '../paths/canonical_home.mjs';
+
+export function getHomeEnvPath() {
+  return join(getHappyStacksHomeDir(), '.env');
+}
+
+export function getCanonicalHomeDir() {
+  return getCanonicalHomeDirFromEnv(process.env);
+}
+
+export function getCanonicalHomeEnvPath() {
+  return join(getCanonicalHomeDir(), '.env');
+}
+
+export function getHomeEnvLocalPath() {
+  return join(getHappyStacksHomeDir(), 'env.local');
+}
+
+export function resolveUserConfigEnvPath({ cliRootDir }) {
+  const explicit = (process.env.HAPPIER_STACK_ENV_FILE ?? '').trim();
+  if (explicit) {
+    return explicit;
+  }
+
+  // By default, persist configuration to the main stack env file so config is
+  // outside the repo and consistent across install modes.
+  //
+  // This also matches the stack env precedence in scripts/utils/env.mjs.
+  void cliRootDir;
+  return resolveStackEnvPath('main').envPath;
+}
+
+export async function ensureHomeEnvUpdated({ updates }) {
+  await ensureEnvFileUpdated({ envPath: getHomeEnvPath(), updates });
+}
+
+export async function ensureCanonicalHomeEnvUpdated({ updates }) {
+  await ensureEnvFileUpdated({ envPath: getCanonicalHomeEnvPath(), updates });
+}
+
+export async function ensureHomeEnvLocalUpdated({ updates }) {
+  await ensureEnvFileUpdated({ envPath: getHomeEnvLocalPath(), updates });
+}
+
+export async function ensureUserConfigEnvUpdated({ cliRootDir, updates }) {
+  const envPath = resolveUserConfigEnvPath({ cliRootDir });
+  await ensureEnvFileUpdated({ envPath, updates });
+  return envPath;
+}

package/scripts/utils/env/dotenv.mjs

@@ -0,0 +1,32 @@
+import { expandHome } from '../paths/canonical_home.mjs';
+
+export function parseDotenv(contents) {
+  const out = new Map();
+  for (const rawLine of contents.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    const idx = line.indexOf('=');
+    if (idx <= 0) {
+      continue;
+    }
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (!key) {
+      continue;
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (value.startsWith('~/') || value.startsWith('~\\')) {
+      value = expandHome(value);
+    }
+    out.set(key, value);
+  }
+  return out;
+}
+
+export function parseEnvToObject(contents) {
+  return Object.fromEntries(parseDotenv(contents));
+}

package/scripts/utils/env/dotenv.test.mjs

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { homedir } from 'node:os';
+
+import { parseDotenv, parseEnvToObject } from './dotenv.mjs';
+
+test('parseDotenv expands ~/ paths', () => {
+  const env = parseDotenv('FOO=~/x\n');
+  assert.equal(env.get('FOO'), `${homedir()}/x`);
+});
+
+test('parseDotenv expands ~\\ paths (Windows)', () => {
+  const env = parseDotenv('FOO=~\\x\n');
+  assert.equal(env.get('FOO'), `${homedir()}\\x`);
+});
+
+test('parseDotenv expands quoted ~/ paths and trims keys/values', () => {
+  const env = parseDotenv("  FOO = '~/x'  \n");
+  assert.equal(env.get('FOO'), `${homedir()}/x`);
+});
+
+test('parseDotenv ignores comments and malformed assignments', () => {
+  const env = parseDotenv('# comment\nNO_EQ\n=BAD\nOK=value\n');
+  assert.equal(env.get('OK'), 'value');
+  assert.equal(env.has('NO_EQ'), false);
+  assert.equal(env.has(''), false);
+});
+
+test('parseEnvToObject returns the final value for duplicate keys', () => {
+  const env = parseEnvToObject('FOO=first\nFOO=second\n');
+  assert.deepEqual(env, { FOO: 'second' });
+});

package/scripts/utils/env/env.mjs

@@ -0,0 +1,130 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../paths/canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
+import { loadEnvFile, loadEnvFileIgnoringPrefixes } from './load_env_file.mjs';
+
+// Load stack env (optional). This is intentionally lightweight and does not require extra deps.
+// This file lives under scripts/utils/env, so repo root is three directories up.
+const __envDir = dirname(fileURLToPath(import.meta.url));
+const __utilsDir = dirname(__envDir);
+const __scriptsDir = dirname(__utilsDir);
+const __cliRootDir = dirname(__scriptsDir);
+
+function resolveHomeDir() {
+  const fromEnv = (process.env.HAPPIER_STACK_HOME_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  return join(homedir(), '.happier-stack');
+}
+
+// If HAPPIER_STACK_HOME_DIR isn't set, try the canonical pointer file at <canonicalHomeDir>/.env first.
+//
+// This allows installs where the "real" home/workspace/runtime are elsewhere, while still
+// giving us a stable discovery location for launchd/SwiftBar/minimal shells.
+const canonicalEnvPath = getCanonicalHomeEnvPathFromEnv(process.env);
+if (!(process.env.HAPPIER_STACK_HOME_DIR ?? '').trim() && existsSync(canonicalEnvPath)) {
+  await loadEnvFile(canonicalEnvPath, { override: false });
+  await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPIER_STACK_' });
+}
+
+const __homeDir = resolveHomeDir();
+process.env.HAPPIER_STACK_HOME_DIR = process.env.HAPPIER_STACK_HOME_DIR ?? __homeDir;
+
+// Prefer canonical home config:
+//   ~/.happier-stack/.env
+//   ~/.happier-stack/env.local
+//
+// Additionally: when running from a cloned repo, load <repo>/.env as a *fallback* even if home config exists.
+// This helps keep repo-local dev settings (e.g. custom Codex binaries) working without requiring users to
+// duplicate them into ~/.happier-stack/env.local.
+const homeEnv = join(__homeDir, '.env');
+const homeLocal = join(__homeDir, 'env.local');
+// In sandbox mode, never load repo env.local (it can contain "real" machine paths/URLs).
+// Treat sandbox runs as having home config even if the sandbox home env files don't exist yet.
+const hasHomeConfig = isSandboxed() || existsSync(homeEnv) || existsSync(homeLocal);
+const repoEnv = join(__cliRootDir, '.env');
+
+// 1) Load defaults first (lowest precedence)
+if (hasHomeConfig) {
+  await loadEnvFile(homeEnv, { override: false });
+  await loadEnvFile(homeLocal, { override: true, overridePrefix: 'HAPPIER_STACK_' });
+} else {
+  await loadEnvFile(join(__cliRootDir, '.env'), { override: false });
+  await loadEnvFile(join(__cliRootDir, 'env.local'), { override: true, overridePrefix: 'HAPPIER_STACK_' });
+}
+
+// Repo-local fallback (dev convenience):
+// If the repo has a .env, load it without overriding anything already set by the environment or home config.
+// Note: we intentionally do NOT load repo env.local here, because env.local is treated as higher-precedence
+// overrides and could unexpectedly fight with stack/home configuration when present.
+if (hasHomeConfig) {
+  // IMPORTANT:
+  // When home config exists, do not let repo-local .env set HAPPIER_STACK_* keys.
+  // Otherwise a cloned repo's .env can accidentally leak global URLs/ports into every stack.
+  await loadEnvFileIgnoringPrefixes(repoEnv, { ignorePrefixes: ['HAPPIER_STACK_'] });
+} else {
+  await loadEnvFile(repoEnv, { override: false });
+}
+
+// If no explicit env file is set, and we're on the default "main" stack, prefer the stack-scoped env file
+// if it exists: ~/.happier/stacks/main/env
+(() => {
+  const stacksEnv = (process.env.HAPPIER_STACK_ENV_FILE ?? '').trim();
+  if (stacksEnv) {
+    return;
+  }
+  const stackName = (process.env.HAPPIER_STACK_STACK ?? '').trim() || 'main';
+  const stacksStorageRootRaw = (process.env.HAPPIER_STACK_STORAGE_DIR ?? '').trim();
+  const stacksStorageRoot = stacksStorageRootRaw ? expandHome(stacksStorageRootRaw) : join(homedir(), '.happier', 'stacks');
+
+  const candidates = [
+    join(stacksStorageRoot, stackName, 'env'),
+  ];
+  const envPath = candidates.find((p) => existsSync(p));
+  if (!envPath) return;
+
+  process.env.HAPPIER_STACK_ENV_FILE = envPath;
+})();
+// 3) Load explicit env file overlay (stack env, or any caller-provided env file) last (highest precedence).
+//
+// IMPORTANT:
+// Stack env files intentionally include some non-prefixed keys (e.g. DATABASE_URL, HAPPIER_SERVER_LIGHT_DATA_DIR)
+// that must apply for true per-stack isolation. Do not filter by prefix here.
+{
+  const stacksEnv = process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '';
+  const unique = Array.from(new Set([stacksEnv].filter(Boolean)));
+  for (const p of unique) {
+    // eslint-disable-next-line no-await-in-loop
+    await loadEnvFile(p, { override: true });
+  }
+}
+
+// Legacy Happy env prefixes are intentionally not supported here.
+// If a user still has older prefixes exported from previous installs, scrub them to avoid accidental leakage.
+const __legacyPrefixes = ['LOCAL_', 'STACKS_'].map((s) => `HAPPY_${s}`);
+for (const k of Object.keys(process.env)) {
+  if (__legacyPrefixes.some((p) => k.startsWith(p))) {
+    delete process.env[k];
+  }
+}
+
+// Corepack strictness can prevent running Yarn in subfolders when the repo root is pinned to a different manager.
+// We intentionally keep child processes Yarn-friendly, so relax strictness for child processes.
+process.env.COREPACK_ENABLE_STRICT = process.env.COREPACK_ENABLE_STRICT ?? '0';
+process.env.NPM_CONFIG_PACKAGE_MANAGER_STRICT = process.env.NPM_CONFIG_PACKAGE_MANAGER_STRICT ?? 'false';
+
+// LaunchAgents often run with a very minimal PATH which won't include NVM's bin dir, so child
+// processes like `yarn` can look "missing" even though Node is running from NVM.
+// Ensure the directory containing this Node binary is on PATH.
+(() => {
+  const delimiter = process.platform === 'win32' ? ';' : ':';
+  const current = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+  const nodeBinDir = dirname(process.execPath);
+  const want = [nodeBinDir, '/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin', '/usr/bin', '/bin'];
+  const next = [...want.filter((p) => p && !current.includes(p)), ...current];
+  process.env.PATH = next.join(delimiter);
+})();

package/scripts/utils/env/env_file.mjs

@@ -0,0 +1,98 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { pathExists } from '../fs/fs.mjs';
+
+export async function ensureEnvFileUpdated({ envPath, updates }) {
+  if (!updates.length) {
+    return;
+  }
+  await mkdir(dirname(envPath), { recursive: true });
+  const existing = await readText(envPath);
+  const next = applyEnvUpdates(existing, updates);
+  await writeFileIfChanged(existing, next, envPath);
+}
+
+export async function ensureEnvFilePruned({ envPath, removeKeys }) {
+  const keys = Array.from(new Set((removeKeys ?? []).map((k) => String(k).trim()).filter(Boolean)));
+  if (!keys.length) {
+    return;
+  }
+  await mkdir(dirname(envPath), { recursive: true });
+  const existing = await readText(envPath);
+  const next = pruneEnvKeys(existing, keys);
+  await writeFileIfChanged(existing, next, envPath);
+}
+
+async function readText(path) {
+  try {
+    return (await pathExists(path)) ? await readFile(path, 'utf-8') : '';
+  } catch {
+    return '';
+  }
+}
+
+function applyEnvUpdates(existing, updates) {
+  const lines = existing ? existing.split('\n') : [];
+  const next = [...lines];
+
+  const upsert = (key, value) => {
+    const line = `${key}=${value}`;
+    const idx = next.findIndex((l) => l.trim().startsWith(`${key}=`));
+    if (idx >= 0) {
+      next[idx] = line;
+    } else {
+      if (next.length && next[next.length - 1].trim() !== '') {
+        next.push('');
+      }
+      next.push(line);
+    }
+  };
+
+  for (const { key, value } of updates) {
+    upsert(key, value);
+  }
+
+  return next.join('\n');
+}
+
+function pruneEnvKeys(existing, removeKeys) {
+  const keys = new Set(removeKeys);
+  const lines = (existing ?? '').split('\n');
+  const kept = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      kept.push(line);
+      continue;
+    }
+    // Remove any "KEY=..." line for keys in removeKeys.
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) {
+      kept.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keys.has(key)) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+async function writeFileIfChanged(existingContent, nextContent, path) {
+  const normalizedNext = nextContent.endsWith('\n') ? nextContent : nextContent + '\n';
+  const normalizedExisting = existingContent.endsWith('\n') ? existingContent : existingContent + (existingContent ? '\n' : '');
+  if (normalizedExisting === normalizedNext) {
+    return;
+  }
+  try {
+    const dir = dirname(path);
+    // if dir doesn't exist, writeFile will throw; that's fine (we only target known files).
+    void dir;
+  } catch {
+    // ignore
+  }
+  await writeFile(path, normalizedNext, 'utf-8');
+}
+