happy-stacks 0.0.0

package/scripts/utils/paths.mjs

@@ -0,0 +1,184 @@
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+const PRIMARY_APP_SLUG = 'happy-stacks';
+const LEGACY_APP_SLUG = 'happy-local';
+const PRIMARY_LABEL_BASE = 'com.happy.stacks';
+const LEGACY_LABEL_BASE = 'com.happy.local';
+const PRIMARY_STORAGE_ROOT = join(homedir(), '.happy', 'stacks');
+const LEGACY_STORAGE_ROOT = join(homedir(), '.happy', 'local');
+const PRIMARY_HOME_DIR = join(homedir(), '.happy-stacks');
+
+export function getRootDir(importMetaUrl) {
+  return dirname(dirname(fileURLToPath(importMetaUrl)));
+}
+
+export function getHappyStacksHomeDir() {
+  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
+  if (fromEnv) {
+    return fromEnv.replace(/^~(?=\/)/, homedir());
+  }
+  return PRIMARY_HOME_DIR;
+}
+
+export function getWorkspaceDir(cliRootDir = null) {
+  const fromEnv = (process.env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
+  if (fromEnv) {
+    return fromEnv.replace(/^~(?=\/)/, homedir());
+  }
+  const homeDir = getHappyStacksHomeDir();
+  const defaultWorkspace = join(homeDir, 'workspace');
+  // Prefer the default home workspace if present.
+  if (existsSync(defaultWorkspace)) {
+    return defaultWorkspace;
+  }
+  // Back-compat: for cloned-repo usage before init, keep components inside the repo.
+  return cliRootDir ? cliRootDir : defaultWorkspace;
+}
+
+export function getComponentsDir(rootDir) {
+  const workspaceDir = getWorkspaceDir(rootDir);
+  return join(workspaceDir, 'components');
+}
+
+export function componentDirEnvKey(name) {
+  return `HAPPY_STACKS_COMPONENT_DIR_${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
+}
+
+function normalizePathForEnv(rootDir, raw) {
+  const trimmed = (raw ?? '').trim();
+  if (!trimmed) {
+    return '';
+  }
+  const expanded = trimmed.replace(/^~(?=\/)/, homedir());
+  // If the path is relative, treat it as relative to the workspace root (default: repo root).
+  const workspaceDir = getWorkspaceDir(rootDir);
+  return expanded.startsWith('/') ? expanded : resolve(workspaceDir, expanded);
+}
+
+export function getComponentDir(rootDir, name) {
+  const stacksKey = componentDirEnvKey(name);
+  const legacyKey = stacksKey.replace(/^HAPPY_STACKS_/, 'HAPPY_LOCAL_');
+  const fromEnv = normalizePathForEnv(rootDir, process.env[stacksKey] ?? process.env[legacyKey]);
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return join(getComponentsDir(rootDir), name);
+}
+
+export function getStackName() {
+  const raw = process.env.HAPPY_STACKS_STACK?.trim()
+    ? process.env.HAPPY_STACKS_STACK.trim()
+    : process.env.HAPPY_LOCAL_STACK?.trim()
+      ? process.env.HAPPY_LOCAL_STACK.trim()
+      : '';
+  return raw || 'main';
+}
+
+export function getStackLabel(stackName = getStackName()) {
+  return stackName === 'main' ? PRIMARY_LABEL_BASE : `${PRIMARY_LABEL_BASE}.${stackName}`;
+}
+
+export function getLegacyStackLabel(stackName = getStackName()) {
+  return stackName === 'main' ? LEGACY_LABEL_BASE : `${LEGACY_LABEL_BASE}.${stackName}`;
+}
+
+export function getStacksStorageRoot() {
+  const fromEnv = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
+  if (fromEnv) {
+    return fromEnv.replace(/^~(?=\/)/, homedir());
+  }
+  return PRIMARY_STORAGE_ROOT;
+}
+
+export function getLegacyStorageRoot() {
+  return LEGACY_STORAGE_ROOT;
+}
+
+export function resolveStackBaseDir(stackName = getStackName()) {
+  const preferredRoot = getStacksStorageRoot();
+  const newBase = join(preferredRoot, stackName);
+  const legacyBase = stackName === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', stackName);
+
+  // Prefer the new layout by default.
+  //
+  // For non-main stacks, keep legacy layout if the legacy env exists and the new env does not.
+  // This avoids breaking existing stacks until `happys stack migrate` is run.
+  if (stackName !== 'main') {
+    const newEnv = join(preferredRoot, stackName, 'env');
+    const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+    if (!existsSync(newEnv) && existsSync(legacyEnv)) {
+      return { baseDir: legacyBase, isLegacy: true };
+    }
+  }
+
+  return { baseDir: newBase, isLegacy: false };
+}
+
+export function resolveStackEnvPath(stackName = getStackName()) {
+  const { baseDir: activeBase, isLegacy } = resolveStackBaseDir(stackName);
+  // New layout: ~/.happy/stacks/<name>/env
+  const newEnv = join(getStacksStorageRoot(), stackName, 'env');
+  // Legacy layout: ~/.happy/local/stacks/<name>/env
+  const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+
+  if (existsSync(newEnv)) {
+    return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(), stackName) };
+  }
+  if (existsSync(legacyEnv)) {
+    return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', stackName) };
+  }
+  return { envPath: newEnv, isLegacy, baseDir: activeBase };
+}
+
+export function getDefaultAutostartPaths() {
+  const stackName = getStackName();
+  const { baseDir, isLegacy } = resolveStackBaseDir(stackName);
+  const logsDir = join(baseDir, 'logs');
+
+  const primaryLabel = getStackLabel(stackName);
+  const legacyLabel = getLegacyStackLabel(stackName);
+  const primaryPlistPath = join(homedir(), 'Library', 'LaunchAgents', `${primaryLabel}.plist`);
+  const legacyPlistPath = join(homedir(), 'Library', 'LaunchAgents', `${legacyLabel}.plist`);
+
+  const primaryStdoutPath = join(logsDir, `${PRIMARY_APP_SLUG}.out.log`);
+  const primaryStderrPath = join(logsDir, `${PRIMARY_APP_SLUG}.err.log`);
+  const legacyStdoutPath = join(logsDir, `${LEGACY_APP_SLUG}.out.log`);
+  const legacyStderrPath = join(logsDir, `${LEGACY_APP_SLUG}.err.log`);
+
+  // Best-effort: prefer primary, but fall back to legacy if that's what's installed.
+  const hasPrimaryPlist = existsSync(primaryPlistPath);
+  const hasLegacyPlist = existsSync(legacyPlistPath);
+  const hasPrimaryLogs = existsSync(primaryStdoutPath) || existsSync(primaryStderrPath);
+  const hasLegacyLogs = existsSync(legacyStdoutPath) || existsSync(legacyStderrPath);
+
+  const activeLabel = hasPrimaryPlist ? primaryLabel : hasLegacyPlist ? legacyLabel : primaryLabel;
+  const activePlistPath = hasPrimaryPlist ? primaryPlistPath : hasLegacyPlist ? legacyPlistPath : primaryPlistPath;
+  const stdoutPath = hasPrimaryLogs ? primaryStdoutPath : hasLegacyLogs ? legacyStdoutPath : primaryStdoutPath;
+  const stderrPath = hasPrimaryLogs ? primaryStderrPath : hasLegacyLogs ? legacyStderrPath : primaryStderrPath;
+
+  return {
+    baseDir,
+    logsDir,
+    stackName,
+    isLegacy,
+
+    // Active (best-effort) for commands like status/logs/start/stop.
+    label: activeLabel,
+    plistPath: activePlistPath,
+    stdoutPath,
+    stderrPath,
+
+    // Primary/legacy info (for display + migration).
+    primaryLabel,
+    legacyLabel,
+    primaryPlistPath,
+    legacyPlistPath,
+    primaryStdoutPath,
+    primaryStderrPath,
+    legacyStdoutPath,
+    legacyStderrPath,
+  };
+}

package/scripts/utils/pm.mjs

@@ -0,0 +1,294 @@
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, rm, stat, writeFile } from 'node:fs/promises';
+
+import { pathExists } from './fs.mjs';
+import { run, runCapture, spawnProc } from './proc.mjs';
+import { getDefaultAutostartPaths, getHappyStacksHomeDir } from './paths.mjs';
+import { resolveInstalledPath, resolveInstalledCliRoot } from './runtime.mjs';
+
+async function commandExists(cmd, options = {}) {
+  try {
+    await runCapture(cmd, ['--version'], options);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function requirePnpm() {
+  if (await commandExists('pnpm')) {
+    return;
+  }
+  throw new Error(
+    '[local] pnpm is required to install dependencies for Happy Stacks.\n' +
+      'Install it via Corepack: `corepack enable && corepack prepare pnpm@latest --activate`'
+  );
+}
+
+async function getComponentPm(dir) {
+  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 }))) {
+      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' };
+  }
+
+  // Default fallback if no yarn.lock: use pnpm.
+  await requirePnpm();
+  return { name: 'pnpm', cmd: 'pnpm' };
+}
+
+export async function requireDir(label, dir) {
+  if (await pathExists(dir)) {
+    return;
+  }
+  throw new Error(
+    `[local] missing ${label} at ${dir}\n` +
+      `Run: happys bootstrap (auto-clones missing components), or place the repo under components/`
+  );
+}
+
+export async function ensureDepsInstalled(dir, label) {
+  const pkgJson = join(dir, 'package.json');
+  if (!(await pathExists(pkgJson))) {
+    return;
+  }
+
+  const nodeModules = join(dir, 'node_modules');
+  const pnpmModulesMeta = join(dir, 'node_modules', '.modules.yaml');
+  const pm = await getComponentPm(dir);
+
+  if (await pathExists(nodeModules)) {
+    const yarnLock = join(dir, 'yarn.lock');
+    const yarnIntegrity = join(nodeModules, '.yarn-integrity');
+    const pnpmLock = join(dir, 'pnpm-lock.yaml');
+
+    // If this repo is Yarn-managed (yarn.lock present) but node_modules was created by pnpm,
+    // reinstall with Yarn to restore upstream-locked dependency versions.
+    if (pm.name === 'yarn' && (await pathExists(pnpmModulesMeta))) {
+      // eslint-disable-next-line no-console
+      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 });
+    }
+
+    // If dependencies changed since the last install, re-run install even if node_modules exists.
+    const mtimeMs = async (p) => {
+      try {
+        const s = await stat(p);
+        return s.mtimeMs ?? 0;
+      } catch {
+        return 0;
+      }
+    };
+
+    if (pm.name === 'yarn' && (await pathExists(yarnLock))) {
+      const lockM = await mtimeMs(yarnLock);
+      const pkgM = await mtimeMs(pkgJson);
+      const intM = await mtimeMs(yarnIntegrity);
+      if (!intM || lockM > intM || pkgM > intM) {
+        // eslint-disable-next-line no-console
+        console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
+        await run(pm.cmd, ['install'], { cwd: dir });
+      }
+    }
+
+    if (pm.name === 'pnpm' && (await pathExists(pnpmLock))) {
+      const lockM = await mtimeMs(pnpmLock);
+      const metaM = await mtimeMs(pnpmModulesMeta);
+      if (!metaM || lockM > metaM) {
+        // eslint-disable-next-line no-console
+        console.log(`[local] refreshing ${label} dependencies (pnpm-lock changed)...`);
+        await run(pm.cmd, ['install'], { cwd: dir });
+      }
+    }
+
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] installing ${label} dependencies (first run)...`);
+  await run(pm.cmd, ['install'], { cwd: dir });
+}
+
+export async function ensureCliBuilt(cliDir, { buildCli }) {
+  await ensureDepsInstalled(cliDir, 'happy-cli');
+  if (!buildCli) {
+    return;
+  }
+  // eslint-disable-next-line no-console
+  console.log('[local] building happy-cli...');
+  const pm = await getComponentPm(cliDir);
+  await run(pm.cmd, ['build'], { cwd: cliDir });
+}
+
+function getPathEntries() {
+  const raw = process.env.PATH ?? '';
+  const delimiter = process.platform === 'win32' ? ';' : ':';
+  return raw.split(delimiter).filter(Boolean);
+}
+
+function isPathInside(path, dir) {
+  const p = resolve(path);
+  const d = resolve(dir);
+  return p === d || p.startsWith(d.endsWith(sep) ? d : d + sep);
+}
+
+export async function ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli }) {
+  if (!npmLinkCli) {
+    return;
+  }
+
+  const homeDir = getHappyStacksHomeDir();
+  const binDir = join(homeDir, 'bin');
+  await mkdir(binDir, { recursive: true });
+
+  const happysShim = join(binDir, 'happys');
+  const happyShim = join(binDir, 'happy');
+
+  const shim = `#!/bin/bash
+set -euo pipefail
+HOME_DIR="\${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
+HAPPYS="$HOME_DIR/bin/happys"
+if [[ -x "$HAPPYS" ]]; then
+  exec "$HAPPYS" happy "$@"
+fi
+exec happys happy "$@"
+`;
+
+  await writeFile(happyShim, shim, 'utf-8');
+  await chmod(happyShim, 0o755).catch(() => {});
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] installed 'happy' shim at ${happyShim}`);
+  if (!existsSync(happysShim)) {
+    // eslint-disable-next-line no-console
+    console.log(`[local] note: run \`happys init\` to install a stable ${happysShim} shim for services/SwiftBar.`);
+  }
+}
+
+export async function pmSpawnScript({ label, dir, script, env, options = {} }) {
+  const pm = await getComponentPm(dir);
+  if (pm.name === 'yarn') {
+    return spawnProc(label, pm.cmd, ['-s', script], env, { ...options, cwd: dir });
+  }
+  return spawnProc(label, pm.cmd, ['--silent', script], env, { ...options, cwd: dir });
+}
+
+export async function pmExecBin({ dir, bin, args, env }) {
+  const pm = await getComponentPm(dir);
+  if (pm.name === 'yarn') {
+    await run(pm.cmd, [bin, ...args], { env, cwd: dir });
+    return;
+  }
+  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir });
+}
+
+export async function ensureMacAutostartEnabled({ rootDir, label = 'com.happy.local', env = {} }) {
+  if (process.platform !== 'darwin') {
+    throw new Error('[local] autostart is currently only implemented for macOS (LaunchAgents).');
+  }
+
+  const {
+    logsDir,
+    stdoutPath,
+    stderrPath,
+    plistPath,
+    primaryLabel,
+    legacyLabel,
+    primaryPlistPath,
+    legacyPlistPath,
+    primaryStdoutPath,
+    primaryStderrPath,
+    legacyStdoutPath,
+    legacyStderrPath,
+  } = getDefaultAutostartPaths();
+  await mkdir(logsDir, { recursive: true });
+
+  const nodePath = process.env.HAPPY_STACKS_NODE?.trim()
+    ? process.env.HAPPY_STACKS_NODE.trim()
+    : process.env.HAPPY_LOCAL_NODE?.trim()
+      ? process.env.HAPPY_LOCAL_NODE.trim()
+      : process.execPath;
+  const installedRoot = resolveInstalledCliRoot(rootDir);
+  const happysEntrypoint = resolveInstalledPath(rootDir, join('bin', 'happys.mjs'));
+
+  // Ensure we write to the plist path that matches the label we're installing, instead of the
+  // "active" plist path (which might be legacy and cause filename/label mismatches).
+  const resolvedPlistPath =
+    label === primaryLabel ? primaryPlistPath : label === legacyLabel ? legacyPlistPath : join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+  const resolvedStdoutPath = label === primaryLabel ? primaryStdoutPath : label === legacyLabel ? legacyStdoutPath : stdoutPath;
+  const resolvedStderrPath = label === primaryLabel ? primaryStderrPath : label === legacyLabel ? legacyStderrPath : stderrPath;
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${label}</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${nodePath}</string>
+      <string>${happysEntrypoint}</string>
+      <string>start</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${installedRoot}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${resolvedStdoutPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${resolvedStderrPath}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+${Object.entries(env)
+  .map(([k, v]) => `      <key>${k}</key>\n      <string>${String(v)}</string>`)
+  .join('\n')}
+    </dict>
+  </dict>
+</plist>
+`;
+
+  await mkdir(dirname(resolvedPlistPath), { recursive: true });
+  await writeFile(resolvedPlistPath, plist, 'utf-8');
+
+  // Best-effort (works on most macOS setups). If it fails, the plist still exists and can be loaded manually.
+  try {
+    await run('launchctl', ['unload', '-w', resolvedPlistPath]);
+  } catch {
+    // ignore
+  }
+  await run('launchctl', ['load', '-w', resolvedPlistPath]);
+}
+
+export async function ensureMacAutostartDisabled({ label = 'com.happy.local' }) {
+  if (process.platform !== 'darwin') {
+    return;
+  }
+  const { primaryLabel, legacyLabel, primaryPlistPath, legacyPlistPath } = getDefaultAutostartPaths();
+  const resolvedPlistPath =
+    label === primaryLabel ? primaryPlistPath : label === legacyLabel ? legacyPlistPath : join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+  try {
+    await run('launchctl', ['unload', '-w', resolvedPlistPath]);
+  } catch {
+    // Old-style unload can fail on newer macOS; fall back to modern bootout.
+    try {
+      const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+      if (uid != null) {
+        await run('launchctl', ['bootout', `gui/${uid}/${label}`]);
+      }
+    } catch {
+      // ignore
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log(`[local] autostart disabled (${label})`);
+}

package/scripts/utils/ports.mjs

@@ -0,0 +1,66 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { runCapture } from './proc.mjs';
+
+/**
+ * Best-effort: kill any processes LISTENing on a TCP port.
+ * Used to avoid EADDRINUSE when a previous run left a server behind.
+ */
+export async function killPortListeners(port, { label = 'port' } = {}) {
+  if (!Number.isFinite(port) || port <= 0) {
+    return [];
+  }
+  if (process.platform === 'win32') {
+    return [];
+  }
+
+  let raw = '';
+  try {
+    // `lsof` exits non-zero if no matches; normalize to empty output.
+    raw = await runCapture('sh', [
+      '-lc',
+      `command -v lsof >/dev/null 2>&1 && lsof -nP -iTCP:${port} -sTCP:LISTEN -t 2>/dev/null || true`,
+    ]);
+  } catch {
+    return [];
+  }
+
+  const pids = Array.from(
+    new Set(
+      raw
+        .split(/\s+/g)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => Number(s))
+        .filter((n) => Number.isInteger(n) && n > 1)
+    )
+  );
+
+  if (!pids.length) {
+    return [];
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] ${label}: freeing tcp:${port} (killing pids: ${pids.join(', ')})`);
+
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // ignore
+    }
+  }
+
+  await delay(500);
+
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 0);
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // not running / no permission
+    }
+  }
+
+  return pids;
+}
+

package/scripts/utils/proc.mjs

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+
+export function spawnProc(label, cmd, args, env, options = {}) {
+  const child = spawn(cmd, args, {
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: false,
+    // Create a new process group so we can kill the whole tree reliably on shutdown.
+    detached: process.platform !== 'win32',
+    ...options,
+  });
+
+  child.stdout?.on('data', (d) => process.stdout.write(`[${label}] ${d.toString()}`));
+  child.stderr?.on('data', (d) => process.stderr.write(`[${label}] ${d.toString()}`));
+  child.on('exit', (code, sig) => {
+    if (code !== 0) {
+      process.stderr.write(`[${label}] exited (code=${code}, sig=${sig})\n`);
+    }
+  });
+
+  return child;
+}
+
+export function killProcessTree(child, signal) {
+  if (!child || child.exitCode != null || !child.pid) {
+    return;
+  }
+
+  try {
+    if (process.platform !== 'win32') {
+      // Kill the process group.
+      process.kill(-child.pid, signal);
+    } else {
+      child.kill(signal);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+export async function run(cmd, args, options = {}) {
+  await new Promise((resolvePromise, rejectPromise) => {
+    const proc = spawn(cmd, args, { stdio: 'inherit', shell: false, ...options });
+    proc.on('error', rejectPromise);
+    proc.on('exit', (code) => (code === 0 ? resolvePromise() : rejectPromise(new Error(`${cmd} failed (code=${code})`))));
+  });
+}
+
+export async function runCapture(cmd, args, options = {}) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false, ...options });
+    let out = '';
+    let err = '';
+    proc.stdout?.on('data', (d) => (out += d.toString()));
+    proc.stderr?.on('data', (d) => (err += d.toString()));
+    proc.on('error', rejectPromise);
+    proc.on('exit', (code) => {
+      if (code === 0) {
+        resolvePromise(out);
+      } else {
+        rejectPromise(new Error(`${cmd} ${args.join(' ')} failed (code=${code}): ${err.trim()}`));
+      }
+    });
+  });
+}
+

package/scripts/utils/runtime.mjs

@@ -0,0 +1,30 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function expandHome(p) {
+  return p.replace(/^~(?=\/)/, homedir());
+}
+
+export function getRuntimeDir() {
+  const fromEnv = (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  const homeDir = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() ? expandHome(process.env.HAPPY_STACKS_HOME_DIR.trim()) : join(homedir(), '.happy-stacks');
+  return join(homeDir, 'runtime');
+}
+
+export function resolveInstalledCliRoot(cliRootDir) {
+  const runtimeDir = getRuntimeDir();
+  const runtimePkgRoot = join(runtimeDir, 'node_modules', 'happy-stacks');
+  if (existsSync(runtimePkgRoot)) {
+    return runtimePkgRoot;
+  }
+  return cliRootDir;
+}
+
+export function resolveInstalledPath(cliRootDir, relativePath) {
+  return join(resolveInstalledCliRoot(cliRootDir), relativePath);
+}
+

package/scripts/utils/server.mjs

@@ -0,0 +1,41 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+export function getServerComponentName({ kv } = {}) {
+  const fromArgRaw = kv?.get('--server')?.trim() ? kv.get('--server').trim() : '';
+  const fromEnvRaw = process.env.HAPPY_STACKS_SERVER_COMPONENT?.trim()
+    ? process.env.HAPPY_STACKS_SERVER_COMPONENT.trim()
+    : process.env.HAPPY_LOCAL_SERVER_COMPONENT?.trim()
+      ? process.env.HAPPY_LOCAL_SERVER_COMPONENT.trim()
+      : '';
+  const raw = fromArgRaw || fromEnvRaw || 'happy-server-light';
+  const v = raw.toLowerCase();
+  if (v === 'light' || v === 'server-light' || v === 'happy-server-light') {
+    return 'happy-server-light';
+  }
+  if (v === 'server' || v === 'full' || v === 'happy-server') {
+    return 'happy-server';
+  }
+  if (v === 'both') {
+    return 'both';
+  }
+  // Allow explicit component dir names (advanced).
+  return raw;
+}
+
+export async function waitForServerReady(url) {
+  const deadline = Date.now() + 60_000;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { method: 'GET' });
+      const text = await res.text();
+      if (res.ok && text.includes('Welcome to Happy Server!')) {
+        return;
+      }
+    } catch {
+      // ignore
+    }
+    await delay(300);
+  }
+  throw new Error(`Timed out waiting for server at ${url}`);
+}
+