@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/proc/happy_monorepo_deps.mjs

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+
+import { pathExists } from '../fs/fs.mjs';
+import { coerceHappyMonorepoRootFromPath } from '../paths/paths.mjs';
+
+export async function ensureHappyMonorepoNestedDepsInstalled({
+  happyTestDir,
+  quiet = false,
+  env = process.env,
+  ensureDepsInstalled,
+} = {}) {
+  const dir = String(happyTestDir ?? '').trim();
+  if (!dir) return { monorepoRoot: null, ensured: [] };
+
+  const monorepoRoot = coerceHappyMonorepoRootFromPath(dir);
+  if (!monorepoRoot || monorepoRoot !== dir) return { monorepoRoot: monorepoRoot ?? null, ensured: [] };
+
+  const ensure = ensureDepsInstalled;
+  if (typeof ensure !== 'function') {
+    throw new Error('ensureHappyMonorepoNestedDepsInstalled: missing ensureDepsInstalled implementation');
+  }
+
+  const candidates = [
+    { subdir: join('apps', 'cli'), label: 'happier-cli (monorepo)' },
+    { subdir: join('apps', 'server'), label: 'happier-server (monorepo)' },
+  ];
+
+  const ensured = [];
+  for (const c of candidates) {
+    const pkgDir = join(monorepoRoot, c.subdir);
+    if (!(await pathExists(join(pkgDir, 'package.json')))) continue;
+    await ensure(pkgDir, c.label, { quiet, env });
+    ensured.push(c.subdir);
+  }
+
+  return { monorepoRoot, ensured };
+}

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

@@ -0,0 +1,89 @@
+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 { ensureHappyMonorepoNestedDepsInstalled } from './happy_monorepo_deps.mjs';
+
+async function mkMonorepoRoot(t) {
+  const root = await mkdtemp(join(tmpdir(), 'hs-mono-deps-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+  await mkdir(join(root, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(root, 'apps', 'cli'), { recursive: true });
+  await mkdir(join(root, 'apps', 'server'), { recursive: true });
+  await writeFile(join(root, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(root, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(root, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+  return root;
+}
+
+test('ensureHappyMonorepoNestedDepsInstalled installs cli/server deps when running tests at the monorepo root', async (t) => {
+  const root = await mkMonorepoRoot(t);
+
+  const calls = [];
+  const ensureDepsInstalled = async (dir, label) => {
+    calls.push({ dir, label });
+  };
+
+  const out = await ensureHappyMonorepoNestedDepsInstalled({
+    happyTestDir: root,
+    quiet: true,
+    env: { ...process.env },
+    ensureDepsInstalled,
+  });
+
+  assert.equal(out.monorepoRoot, root);
+  assert.deepEqual(out.ensured.sort(), ['apps/cli', 'apps/server']);
+  assert.equal(calls.length, 2);
+  assert.deepEqual(
+    calls.map((c) => c.dir).sort(),
+    [join(root, 'apps', 'cli'), join(root, 'apps', 'server')].sort()
+  );
+});
+
+test('ensureHappyMonorepoNestedDepsInstalled is a no-op when invoked from inside a package directory', async (t) => {
+  const root = await mkMonorepoRoot(t);
+
+  const calls = [];
+  const ensureDepsInstalled = async (dir, label) => {
+    calls.push({ dir, label });
+  };
+
+  const out = await ensureHappyMonorepoNestedDepsInstalled({
+    happyTestDir: join(root, 'apps', 'ui'),
+    quiet: true,
+    env: { ...process.env },
+    ensureDepsInstalled,
+  });
+
+  assert.equal(out.monorepoRoot, root);
+  assert.deepEqual(out.ensured, []);
+  assert.equal(calls.length, 0);
+});
+
+test('ensureHappyMonorepoNestedDepsInstalled is a no-op outside monorepo roots', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-mono-deps-non-root-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+  await mkdir(join(root, 'random', 'folder'), { recursive: true });
+  const out = await ensureHappyMonorepoNestedDepsInstalled({
+    happyTestDir: join(root, 'random', 'folder'),
+    quiet: true,
+    env: { ...process.env },
+    ensureDepsInstalled: async () => {},
+  });
+  assert.equal(out.monorepoRoot, null);
+  assert.deepEqual(out.ensured, []);
+});
+
+test('ensureHappyMonorepoNestedDepsInstalled throws when ensureDepsInstalled is missing for monorepo root', async (t) => {
+  const root = await mkMonorepoRoot(t);
+  await assert.rejects(
+    () => ensureHappyMonorepoNestedDepsInstalled({ happyTestDir: root, quiet: true, env: { ...process.env } }),
+    /missing ensureDepsInstalled implementation/i
+  );
+});

package/scripts/utils/proc/ownership.mjs

@@ -0,0 +1,217 @@
+import { runCapture } from './proc.mjs';
+import { killPid } from '../expo/expo.mjs';
+import { terminateProcessGroup } from './terminate.mjs';
+import { readdir, readFile } from 'node:fs/promises';
+
+function normalizeNeedles(needles) {
+  const raw = Array.isArray(needles) ? needles : [];
+  return raw.map((n) => String(n ?? '').trim()).filter(Boolean);
+}
+
+async function readLinuxProcEnviron(pid) {
+  try {
+    const raw = await readFile(`/proc/${pid}/environ`, 'utf-8');
+    return String(raw ?? '').replaceAll('\0', ' ').trim();
+  } catch {
+    return '';
+  }
+}
+
+async function readLinuxProcCmdline(pid) {
+  try {
+    const raw = await readFile(`/proc/${pid}/cmdline`, 'utf-8');
+    return String(raw ?? '').replaceAll('\0', ' ').trim();
+  } catch {
+    return '';
+  }
+}
+
+async function listLinuxProcPidsWithEnvNeedles(needles) {
+  if (process.platform !== 'linux') return null;
+  const ns = normalizeNeedles(needles);
+  if (ns.length === 0) return [];
+  try {
+    const entries = await readdir('/proc', { withFileTypes: true });
+    const pids = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (!/^\d+$/.test(entry.name)) continue;
+      const pid = Number(entry.name);
+      if (!Number.isFinite(pid) || pid <= 1) continue;
+      // eslint-disable-next-line no-await-in-loop
+      const envText = await readLinuxProcEnviron(pid);
+      if (!envText) continue;
+      if (ns.every((needle) => envText.includes(needle))) {
+        pids.push(pid);
+      }
+    }
+    return Array.from(new Set(pids));
+  } catch {
+    return null;
+  }
+}
+
+export function parsePsPidCommandOutputForNeedles(output, needles) {
+  const ns = normalizeNeedles(needles);
+  if (ns.length === 0) return [];
+
+  const text = String(output ?? '');
+  const pids = [];
+  for (const line of text.split('\n')) {
+    if (!ns.every((n) => line.includes(n))) continue;
+    const m = line.trim().match(/^(\d+)\s+/);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (Number.isFinite(pid) && pid > 1) {
+      pids.push(pid);
+    }
+  }
+  return Array.from(new Set(pids));
+}
+
+export async function getPsEnvLine(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  if (process.platform === 'linux') {
+    const envText = await readLinuxProcEnviron(n);
+    if (envText) {
+      const cmdline = await readLinuxProcCmdline(n);
+      return `${n} ${cmdline} ${envText}`.trim();
+    }
+  }
+  try {
+    const out = await runCapture('ps', ['eww', '-p', String(n)]);
+    // Output usually includes a header line and then a single process line.
+    const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length >= 2) return lines[1];
+    if (lines.length === 1) return lines[0];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getPidStartTime(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['-o', 'lstart=', '-p', String(n)]);
+    const v = String(out ?? '').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function listPidsWithEnvNeedle(needle) {
+  const n = String(needle ?? '').trim();
+  if (!n) return [];
+  if (process.platform === 'win32') return [];
+  const viaProc = await listLinuxProcPidsWithEnvNeedles([n]);
+  if (Array.isArray(viaProc)) return viaProc;
+  try {
+    // Include environment variables (eww) so we can match on HAPPIER_STACK_ENV_FILE=/.../env safely.
+    const out = await runCapture('ps', ['eww', '-ax', '-o', 'pid=,command=']);
+    return parsePsPidCommandOutputForNeedles(out, [n]);
+  } catch {
+    return [];
+  }
+}
+
+export async function listPidsWithEnvNeedles(needles) {
+  const ns = normalizeNeedles(needles);
+  if (ns.length === 0) return [];
+  if (process.platform === 'win32') return [];
+  const viaProc = await listLinuxProcPidsWithEnvNeedles(ns);
+  if (Array.isArray(viaProc)) return viaProc;
+  try {
+    // Include environment variables (eww) so we can match on HAPPIER_STACK_ENV_FILE=/.../env safely.
+    const out = await runCapture('ps', ['eww', '-ax', '-o', 'pid=,command=']);
+    return parsePsPidCommandOutputForNeedles(out, ns);
+  } catch {
+    return [];
+  }
+}
+
+export async function getProcessGroupId(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['-o', 'pgid=', '-p', String(n)]);
+    const raw = out.trim();
+    const pgid = raw ? Number(raw) : NaN;
+    return Number.isFinite(pgid) && pgid > 1 ? pgid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir } = {}) {
+  const line = await getPsEnvLine(pid);
+  if (!line) return false;
+  const sn = String(stackName ?? '').trim();
+  const ep = String(envPath ?? '').trim();
+  const ch = String(cliHomeDir ?? '').trim();
+
+  // Require at least one stack identifier.
+  const hasStack =
+    (sn && line.includes(`HAPPIER_STACK_STACK=${sn}`)) ||
+    (!sn && line.includes('HAPPIER_STACK_STACK='));
+  if (!hasStack) return false;
+
+  // Prefer env-file binding (strongest).
+  if (ep) {
+    if (line.includes(`HAPPIER_STACK_ENV_FILE=${ep}`)) {
+      return true;
+    }
+  }
+
+  // Fallback: CLI home dir binding (useful for daemon-related processes).
+  if (ch) {
+    if (line.includes(`HAPPIER_HOME_DIR=${ch}`) || line.includes(`HAPPIER_STACK_CLI_HOME_DIR=${ch}`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export async function killPidOwnedByStack(pid, { stackName, envPath, cliHomeDir, label = 'process', json = false } = {}) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  await killPid(pid);
+  return { killed: true, reason: 'killed' };
+}
+
+export async function killProcessGroupOwnedByStack(
+  pid,
+  { stackName, envPath, cliHomeDir, label = 'process-group', json = false, signal = 'SIGTERM', graceMs = 800 } = {}
+) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  const pgid = await getProcessGroupId(pid);
+  if (!pgid) {
+    await killPid(pid);
+    return { killed: true, reason: 'killed_pid_only' };
+  }
+  const terminated = await terminateProcessGroup(pgid, { graceMs, signal });
+  if (!terminated.ok) {
+    return { killed: false, reason: 'kill_timeout', pgid, signal: terminated.signal ?? 'SIGKILL' };
+  }
+  return { killed: true, reason: 'killed_pgid', pgid, signal: terminated.signal ?? 'SIGKILL' };
+}

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

@@ -0,0 +1,216 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { isPidAlive } from './pids.mjs';
+import { killProcessGroupOwnedByStack } from './ownership.mjs';
+
+function spawnOwnedGracefulExit({ env, exitFile, readyFile }) {
+  const cleanEnv = {};
+  for (const [k, v] of Object.entries(env ?? {})) {
+    if (v == null) continue;
+    cleanEnv[k] = String(v);
+  }
+
+  // Wait for SIGINT/SIGTERM, then write a marker file right before exiting.
+  const code = `
+    const fs = require('fs');
+    const exitFile = process.argv[1];
+    const readyFile = process.argv[2];
+    function onStop() {
+      setTimeout(() => {
+        try { fs.writeFileSync(exitFile, 'ok'); } catch {}
+        process.exit(0);
+      }, 120);
+    }
+    process.on('SIGINT', onStop);
+    process.on('SIGTERM', onStop);
+    try { fs.writeFileSync(readyFile, 'ready'); } catch {}
+    setInterval(() => {}, 1000);
+  `;
+
+  const child = spawn(process.execPath, ['-e', code, exitFile, readyFile], {
+    env: cleanEnv,
+    stdio: 'ignore',
+    detached: true,
+  });
+  child.unref();
+  return child;
+}
+
+async function waitForCondition({ description, timeoutMs, intervalMs = 30, fn }) {
+  const end = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  while (Date.now() < end) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await fn()) return;
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(`timed out waiting for condition: ${description}`);
+}
+
+async function waitForFile(path, timeoutMs) {
+  await waitForCondition({
+    description: `file to exist at ${path}`,
+    timeoutMs,
+    fn: async () => {
+      try {
+        await stat(path);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+}
+
+async function waitForFileContent(path, timeoutMs) {
+  let content = '';
+  await waitForCondition({
+    description: `file content at ${path}`,
+    timeoutMs,
+    fn: async () => {
+      try {
+        content = (await readFile(path, 'utf-8')).trim();
+        return Boolean(content);
+      } catch {
+        return false;
+      }
+    },
+  });
+  return content;
+}
+
+function killGroup(pid) {
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    // ignore
+  }
+}
+
+test('killProcessGroupOwnedByStack allows graceful exit before SIGKILL', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('POSIX process-group signaling semantics');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-kill-grace-'));
+  const envPath = join(tmp, 'env');
+  const exitFile = join(tmp, 'exited.txt');
+  const readyFile = join(tmp, 'ready.txt');
+
+  const child = spawnOwnedGracefulExit({
+    readyFile,
+    exitFile,
+    env: {
+      ...process.env,
+      HAPPIER_STACK_STACK: 't',
+      HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_PROCESS_KIND: 'infra',
+    },
+  });
+
+  try {
+    assert.ok(Number(child.pid) > 1, 'expected child pid');
+    assert.ok(isPidAlive(child.pid), 'expected child alive before kill');
+
+    await waitForFile(readyFile, 1200);
+
+    const res = await killProcessGroupOwnedByStack(child.pid, {
+      stackName: 't',
+      envPath,
+      cliHomeDir: '',
+      json: true,
+      graceMs: 600,
+    });
+
+    assert.equal(res.killed, true);
+    assert.equal(isPidAlive(child.pid), false, 'expected child to exit');
+
+    await waitForFile(exitFile, 1200);
+  } finally {
+    killGroup(child.pid);
+    try {
+      await rm(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+});
+
+test('killProcessGroupOwnedByStack honors requested initial signal when provided', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('POSIX process-group signaling semantics');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-kill-signal-'));
+  const envPath = join(tmp, 'env');
+  const signalFile = join(tmp, 'signal.txt');
+  const readyFile = join(tmp, 'ready.txt');
+
+  const child = spawn(
+    process.execPath,
+    [
+      '-e',
+      `
+      const fs = require('fs');
+      const signalFile = process.argv[1];
+      const readyFile = process.argv[2];
+      let done = false;
+      function onSignal(sig) {
+        if (done) return;
+        done = true;
+        try { fs.writeFileSync(signalFile, sig); } catch {}
+        setTimeout(() => process.exit(0), 30);
+      }
+      process.on('SIGINT', () => onSignal('SIGINT'));
+      process.on('SIGTERM', () => onSignal('SIGTERM'));
+      try { fs.writeFileSync(readyFile, 'ready'); } catch {}
+      setInterval(() => {}, 1000);
+    `,
+      signalFile,
+      readyFile,
+    ],
+    {
+      env: {
+        ...process.env,
+        HAPPIER_STACK_STACK: 't',
+        HAPPIER_STACK_ENV_FILE: envPath,
+      },
+      stdio: 'ignore',
+      detached: true,
+    }
+  );
+  child.unref();
+
+  try {
+    assert.ok(Number(child.pid) > 1, 'expected child pid');
+    assert.ok(isPidAlive(child.pid), 'expected child alive before kill');
+    await waitForFile(readyFile, 1200);
+
+    const res = await killProcessGroupOwnedByStack(child.pid, {
+      stackName: 't',
+      envPath,
+      signal: 'SIGTERM',
+      graceMs: 600,
+      json: true,
+    });
+    assert.equal(res.killed, true);
+
+    const firstSignal = await waitForFileContent(signalFile, 1200);
+    assert.ok(firstSignal, 'expected signal marker file to be written');
+    assert.equal(firstSignal, 'SIGTERM');
+  } finally {
+    killGroup(child.pid);
+    try {
+      await rm(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+});

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

@@ -0,0 +1,88 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { listPidsWithEnvNeedles, parsePsPidCommandOutputForNeedles } from './ownership.mjs';
+
+test('parsePsPidCommandOutputForNeedles requires all needles to match', () => {
+  const output = [
+    '101 node server.js HAPPIER_STACK_ENV_FILE=/tmp/a/env HAPPIER_STACK_PROCESS_KIND=infra',
+    '102 node server.js HAPPIER_STACK_ENV_FILE=/tmp/a/env HAPPIER_STACK_PROCESS_KIND=session',
+    '103 node server.js HAPPIER_STACK_ENV_FILE=/tmp/b/env HAPPIER_STACK_PROCESS_KIND=infra',
+  ].join('\n');
+
+  const pids = parsePsPidCommandOutputForNeedles(output, [
+    'HAPPIER_STACK_ENV_FILE=/tmp/a/env',
+    'HAPPIER_STACK_PROCESS_KIND=infra',
+  ]);
+
+  assert.deepEqual(pids, [101]);
+});
+
+test('parsePsPidCommandOutputForNeedles deduplicates matches and ignores invalid pid lines', () => {
+  const output = [
+    '201 cmd HAPPIER_STACK_ENV_FILE=/tmp/x/env HAPPIER_STACK_PROCESS_KIND=infra',
+    'not-a-pid cmd HAPPIER_STACK_ENV_FILE=/tmp/x/env HAPPIER_STACK_PROCESS_KIND=infra',
+    '201 cmd HAPPIER_STACK_ENV_FILE=/tmp/x/env HAPPIER_STACK_PROCESS_KIND=infra',
+    '1 cmd HAPPIER_STACK_ENV_FILE=/tmp/x/env HAPPIER_STACK_PROCESS_KIND=infra',
+  ].join('\n');
+
+  const pids = parsePsPidCommandOutputForNeedles(output, [
+    'HAPPIER_STACK_ENV_FILE=/tmp/x/env',
+    'HAPPIER_STACK_PROCESS_KIND=infra',
+  ]);
+
+  assert.deepEqual(pids, [201]);
+});
+
+test('listPidsWithEnvNeedles finds real stack-owned infra processes', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('requires posix process listing');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-needles-live-'));
+  const envPath = join(tmp, 'env');
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+    env: {
+      PATH: process.env.PATH ?? '',
+      HOME: process.env.HOME ?? '',
+      HAPPIER_STACK_STACK: 'test-stack',
+      HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_PROCESS_KIND: 'infra',
+    },
+    stdio: 'ignore',
+    detached: true,
+  });
+  child.unref();
+
+  const childPid = Number(child.pid);
+  try {
+    assert.ok(Number.isFinite(childPid) && childPid > 1, 'expected child pid');
+    const needles = [
+      `HAPPIER_STACK_ENV_FILE=${envPath}`,
+      'HAPPIER_STACK_PROCESS_KIND=infra',
+    ];
+    const timeoutMs = 5_000;
+    const startedAt = Date.now();
+    let found = [];
+    while (Date.now() - startedAt < timeoutMs) {
+      // eslint-disable-next-line no-await-in-loop
+      found = await listPidsWithEnvNeedles(needles);
+      if (found.includes(childPid)) break;
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => setTimeout(resolve, 40));
+    }
+    assert.ok(found.includes(childPid), `expected pid ${childPid} in ${JSON.stringify(found)}`);
+  } finally {
+    try {
+      process.kill(-childPid, 'SIGKILL');
+    } catch {
+      // ignore
+    }
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  }
+});

package/scripts/utils/proc/package_scripts.mjs

@@ -0,0 +1,38 @@
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { pathExists } from '../fs/fs.mjs';
+import { coerceHappyMonorepoRootFromPath } from '../paths/paths.mjs';
+
+export async function detectPackageManagerCmd(dir) {
+  if (await pathExists(join(dir, 'yarn.lock'))) {
+    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
+  }
+
+  // When running against the Happy monorepo, stacks/worktrees often point at a package directory
+  // (e.g. apps/server) instead of the monorepo root. Prefer Yarn in that case so
+  // workspace-only deps like `@happier-dev/agents` resolve locally instead of being fetched from npm.
+  const happyMonorepoRoot = coerceHappyMonorepoRootFromPath(dir);
+  if (happyMonorepoRoot && (await pathExists(join(happyMonorepoRoot, 'yarn.lock')))) {
+    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
+  }
+  // Yarn-only: if no lockfile is found, still default to yarn to avoid mixing package managers.
+  return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
+}
+
+export async function readPackageJsonScripts(dir) {
+  try {
+    const raw = await readFile(join(dir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    return scripts;
+  } catch {
+    return null;
+  }
+}
+
+export function pickFirstScript(scripts, candidates) {
+  if (!scripts) return null;
+  const list = Array.isArray(candidates) ? candidates : [];
+  return list.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+}