@happier-dev/stack 0.1.0-preview.9.1 → 0.1.0

package/scripts/utils/proc/pm.mjs

@@ -15,6 +15,25 @@ function sha256Hex(s) {
   return createHash('sha256').update(String(s ?? ''), 'utf-8').digest('hex');
 }
 
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf-8'));
+}
+
+function isServiceMode(env = process.env) {
+  const raw = String(env?.HAPPIER_STACK_SERVICE_MODE ?? '').trim();
+  if (raw) return raw !== '0';
+
+  // In CI, we prefer deterministic builds and want failures to surface.
+  const isCi = Boolean(String(env?.CI ?? '').trim());
+  if (isCi) return false;
+
+  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (isInteractive) return false;
+
+  // launchd (macOS) and systemd (Linux) typically run as pid 1.
+  return process.ppid === 1;
+}
+
 function resolveBuildStatePath({ label, dir }) {
   const homeDir = getHappyStacksHomeDir();
   const key = sha256Hex(resolve(dir));
@@ -105,6 +124,32 @@ function resolveStackCacheBaseDirFromEnv(env) {
 
 export async function applyStackCacheEnv(baseEnv) {
   const env = { ...(baseEnv && typeof baseEnv === 'object' ? baseEnv : process.env) };
+  // IMPORTANT:
+  // Stack setup/bootstrap frequently runs `yarn install` inside the Happier monorepo.
+  // Many workspace lifecycle scripts depend on devDependencies (e.g. TypeScript for `tsc`).
+  //
+  // If a user (or CI) has NODE_ENV=production / *production* npm/Yarn flags set globally,
+  // Yarn can skip devDependencies and the install fails in confusing ways.
+  //
+  // Default: scrub production-mode flags for stack-invoked package-manager commands.
+  // Opt-out via: HAPPIER_STACK_PM_ALLOW_PRODUCTION=1
+  const allowProduction = String(env.HAPPIER_STACK_PM_ALLOW_PRODUCTION ?? '').trim() === '1';
+  const isTruthy = (v) => {
+    const s = String(v ?? '').trim().toLowerCase();
+    return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+  };
+  const wantsProduction =
+    String(env.NODE_ENV ?? '').trim().toLowerCase() === 'production'
+    || isTruthy(env.YARN_PRODUCTION)
+    || isTruthy(env.npm_config_production)
+    || isTruthy(env.NPM_CONFIG_PRODUCTION);
+  if (!allowProduction && wantsProduction) {
+    env.NODE_ENV = 'development';
+    env.YARN_PRODUCTION = '0';
+    env.npm_config_production = 'false';
+    env.NPM_CONFIG_PRODUCTION = 'false';
+  }
+
   const envFile = (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim();
   const stackCacheBase = resolveStackCacheBaseDirFromEnv(env);
   if (!stackCacheBase) return env;
@@ -158,21 +203,44 @@ export async function applyStackCacheEnv(baseEnv) {
 }
 
 export async function ensureDepsInstalled(dir, label, { quiet = false, env: envIn = process.env } = {}) {
-  const pkgJson = join(dir, 'package.json');
-  if (!(await pathExists(pkgJson))) {
+  const componentDir = dir;
+  const componentPkgJson = join(componentDir, 'package.json');
+  if (!(await pathExists(componentPkgJson))) {
     return;
   }
 
-  const nodeModules = join(dir, 'node_modules');
+  const monorepoRoot = coerceHappyMonorepoRootFromPath(componentDir);
+  const installDir = (() => {
+    if (!monorepoRoot) return componentDir;
+    const rootPkgJson = join(monorepoRoot, 'package.json');
+    return existsSync(rootPkgJson) ? monorepoRoot : componentDir;
+  })();
+
+  const installPkgJson = join(installDir, 'package.json');
+  const nodeModules = join(installDir, 'node_modules');
   const stdio = quiet ? 'ignore' : 'inherit';
   const env = await applyStackCacheEnv(envIn);
-  const pm = await getComponentPm(dir, env);
+  const pm = await getComponentPm(installDir, env);
   if (pm.name === 'yarn') {
-    await ensureYarnReady({ dir, env, quiet });
+    await ensureYarnReady({ dir: installDir, env, quiet });
   }
+  const installArgs = pm.name === 'yarn' ? ['install', '--production=false'] : ['install'];
 
   if (await pathExists(nodeModules)) {
-    const yarnLock = join(dir, 'yarn.lock');
+    // In service contexts (launchd/systemd), avoid doing surprise dependency refreshes just because
+    // files changed on disk. This keeps long-running stacks resilient even if the checkout becomes
+    // temporarily un-buildable (e.g. mid-rebase / failing typecheck).
+    const allowRefresh =
+      String(env?.HAPPIER_STACK_SERVICE_ALLOW_REFRESH_DEPS ?? '').trim() === '1' ||
+      String(env?.HAPPIER_STACK_ALLOW_REFRESH_DEPS ?? '').trim() === '1';
+    if (isServiceMode(env) && !allowRefresh) {
+      return;
+    }
+
+    // Yarn workspaces keep yarn.lock at the monorepo root. If invoked from a workspace directory,
+    // we must read lock/integrity from the root; otherwise "deps changed" detection silently breaks
+    // (because apps/* typically has no yarn.lock, and node_modules is often nohoisted).
+    const yarnLock = join(installDir, 'yarn.lock');
     const yarnIntegrity = join(nodeModules, '.yarn-integrity');
 
     // If dependencies changed since the last install, re-run install even if node_modules exists.
@@ -185,6 +253,11 @@ export async function ensureDepsInstalled(dir, label, { quiet = false, env: envI
       }
     };
 
+    const componentPkgMtimeMs = async () => {
+      if (installDir === componentDir) return 0;
+      return await mtimeMs(componentPkgJson);
+    };
+
     const patchesMtimeMs = async () => {
       // Happy's mobile app (and some other repos) use patch-package and keep patches under `patches/`.
       // If a patch file changes but yarn.lock/package.json do not, Yarn won't reinstall and
@@ -209,15 +282,16 @@ export async function ensureDepsInstalled(dir, label, { quiet = false, env: envI
 
     if (pm.name === 'yarn' && (await pathExists(yarnLock))) {
       const lockM = await mtimeMs(yarnLock);
-      const pkgM = await mtimeMs(pkgJson);
+      const pkgM = await mtimeMs(installPkgJson);
+      const componentPkgM = await componentPkgMtimeMs();
       const intM = await mtimeMs(yarnIntegrity);
       const patchM = await patchesMtimeMs();
-      if (!intM || lockM > intM || pkgM > intM || patchM > intM) {
+      if (!intM || lockM > intM || pkgM > intM || componentPkgM > intM || patchM > intM) {
         if (!quiet) {
           // eslint-disable-next-line no-console
           console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json/patches changed)...`);
         }
-        await run(pm.cmd, ['install'], { cwd: dir, stdio, env });
+        await run(pm.cmd, installArgs, { cwd: installDir, stdio, env });
       }
     }
 
@@ -228,7 +302,119 @@ export async function ensureDepsInstalled(dir, label, { quiet = false, env: envI
     // eslint-disable-next-line no-console
     console.log(`[local] installing ${label} dependencies (first run)...`);
   }
-  await run(pm.cmd, ['install'], { cwd: dir, stdio, env });
+  await run(pm.cmd, installArgs, { cwd: installDir, stdio, env });
+}
+
+function collectExpectedExportFileTargets(exportsField) {
+  const out = [];
+  const visit = (value) => {
+    if (!value) return;
+    if (typeof value === 'string') {
+      out.push(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const v of value) visit(v);
+      return;
+    }
+    if (typeof value === 'object') {
+      for (const v of Object.values(value)) visit(v);
+    }
+  };
+  visit(exportsField);
+  return out;
+}
+
+function collectExpectedPackageFilesFromPackageJson(pkgJson) {
+  const candidates = [];
+  for (const key of ['main', 'module', 'types']) {
+    const v = pkgJson?.[key];
+    if (typeof v === 'string' && v.trim()) candidates.push(v.trim());
+  }
+  candidates.push(...collectExpectedExportFileTargets(pkgJson?.exports));
+
+  // Only relative file targets are meaningful on disk.
+  return [...new Set(candidates)].filter((p) => typeof p === 'string' && (p.startsWith('./') || p.startsWith('dist/')));
+}
+
+async function ensureWorkspacePackageBuilt(pkgDir, { quiet = false, env: envIn = process.env } = {}) {
+  const pkgJsonPath = join(pkgDir, 'package.json');
+  if (!(await pathExists(pkgJsonPath))) return { built: false, reason: 'missing-package-json' };
+
+  const env = await applyStackCacheEnv(envIn);
+  const stdio = quiet ? 'ignore' : 'inherit';
+  const pkgJson = await readJson(pkgJsonPath);
+  const expectedFiles = collectExpectedPackageFilesFromPackageJson(pkgJson).map((p) => join(pkgDir, p));
+  if (expectedFiles.length === 0) return { built: false, reason: 'no-expected-files' };
+
+  const missingBefore = expectedFiles.filter((p) => !existsSync(p));
+  if (missingBefore.length === 0) return { built: false, reason: 'already-built' };
+
+  const buildScript = pkgJson?.scripts?.build;
+  if (!buildScript) {
+    throw new Error(
+      `[local] missing build outputs for ${pkgJson?.name ?? pkgDir}:\n` +
+        missingBefore.map((p) => `- ${p}`).join('\n') +
+        '\nFix: add a build script, or ensure the package does not export dist/* paths.',
+    );
+  }
+
+  const pm = await getComponentPm(pkgDir, env);
+  if (pm.name === 'yarn') {
+    await ensureYarnReady({ dir: pkgDir, env, quiet });
+    await run(pm.cmd, ['-s', 'build'], { cwd: pkgDir, stdio, env });
+  } else {
+    await run(pm.cmd, ['run', '-s', 'build'], { cwd: pkgDir, stdio, env });
+  }
+
+  const missingAfter = expectedFiles.filter((p) => !existsSync(p));
+  if (missingAfter.length > 0) {
+    throw new Error(
+      `[local] build completed but expected outputs are still missing for ${pkgJson?.name ?? pkgDir}:\n` +
+        missingAfter.map((p) => `- ${p}`).join('\n') +
+        '\nFix: ensure the package build generates the files referenced by package.json exports/main/types.',
+    );
+  }
+
+  return { built: true, reason: 'rebuilt' };
+}
+
+export async function ensureWorkspacePackagesBuiltForComponent(componentDir, { quiet = false, env = process.env } = {}) {
+  const monorepoRoot = coerceHappyMonorepoRootFromPath(componentDir);
+  if (!monorepoRoot) {
+    return { ok: true, built: [], skipped: ['not-monorepo'] };
+  }
+
+  const componentPkgPath = join(componentDir, 'package.json');
+  if (!(await pathExists(componentPkgPath))) {
+    return { ok: true, built: [], skipped: ['missing-component-package-json'] };
+  }
+
+  const componentPkg = await readJson(componentPkgPath);
+  const componentName = typeof componentPkg?.name === 'string' ? componentPkg.name : '';
+  const depSources = [componentPkg?.dependencies, componentPkg?.optionalDependencies, componentPkg?.devDependencies];
+  const internalDeps = new Set();
+  for (const src of depSources) {
+    if (!src || typeof src !== 'object') continue;
+    for (const name of Object.keys(src)) {
+      if (!name.startsWith('@happier-dev/')) continue;
+      if (name === componentName) continue;
+      internalDeps.add(name);
+    }
+  }
+
+  const built = [];
+  for (const name of internalDeps) {
+    const id = String(name).split('/')[1] ?? '';
+    if (!id) continue;
+    const pkgDir = join(monorepoRoot, 'packages', id);
+    if (!(await pathExists(join(pkgDir, 'package.json')))) continue;
+
+    const res = await ensureWorkspacePackageBuilt(pkgDir, { quiet, env });
+    if (res.built) built.push(name);
+  }
+
+  return { ok: true, built, skipped: [] };
 }
 
 export async function ensureCliBuilt(cliDir, { buildCli, quiet = false, env: envIn = process.env } = {}) {
@@ -242,7 +428,8 @@ export async function ensureCliBuilt(cliDir, { buildCli, quiet = false, env: env
   // - HAPPIER_STACK_CLI_BUILD_MODE=always
   // Or disable via:
   // - HAPPIER_STACK_CLI_BUILD=0
-  const modeRaw = (process.env.HAPPIER_STACK_CLI_BUILD_MODE ?? 'auto').trim().toLowerCase();
+  const serviceDefaultMode = isServiceMode(envIn) ? 'never' : 'auto';
+  const modeRaw = (envIn.HAPPIER_STACK_CLI_BUILD_MODE ?? serviceDefaultMode).trim().toLowerCase();
   const mode = modeRaw === 'always' || modeRaw === 'auto' || modeRaw === 'never' ? modeRaw : 'auto';
   const distEntrypoint = join(cliDir, 'dist', 'index.mjs');
   const distDir = join(cliDir, 'dist');

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

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
 
 import { ensureCliBuilt, ensureDepsInstalled, pmExecBin } from './pm.mjs';
 
@@ -18,6 +19,10 @@ async function writeYarnEnvDumpStub({ binDir, outputPath }) {
       '  XDG_CACHE_HOME: process.env.XDG_CACHE_HOME ?? null,',
       '  YARN_CACHE_FOLDER: process.env.YARN_CACHE_FOLDER ?? null,',
       '  npm_config_cache: process.env.npm_config_cache ?? null,',
+      '  NODE_ENV: process.env.NODE_ENV ?? null,',
+      '  YARN_PRODUCTION: process.env.YARN_PRODUCTION ?? null,',
+      '  npm_config_production: process.env.npm_config_production ?? null,',
+      '  NPM_CONFIG_PRODUCTION: process.env.NPM_CONFIG_PRODUCTION ?? null,',
       '};',
       "writeFileSync(process.env.OUTPUT_PATH, JSON.stringify(out, null, 2) + '\\n');",
       'process.exit(0);',
@@ -86,6 +91,47 @@ async function writeYarnBuildFailAfterDeletingDistStub({ binDir, outputPath }) {
   await writeFile(outputPath, '', 'utf-8');
 }
 
+async function writeYarnBuildCreatesDistStub({ binDir, outputPath, cliDir }) {
+  await mkdir(binDir, { recursive: true });
+  const yarnPath = join(binDir, 'yarn');
+  await writeFile(
+    yarnPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'echo "$*" >> "${OUTPUT_PATH:?}"',
+      'if [ "${1:-}" = "--version" ]; then',
+      '  echo "1.22.22"',
+      '  exit 0',
+      'fi',
+      'if [ "${1:-}" = "build" ]; then',
+      `  mkdir -p ${JSON.stringify(join(cliDir, 'dist'))}`,
+      `  echo "export const built = true;" > ${JSON.stringify(join(cliDir, 'dist', 'index.mjs'))}`,
+      '  exit 0',
+      'fi',
+      'exit 0',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(yarnPath, 0o755);
+  await writeFile(outputPath, '', 'utf-8');
+}
+
+async function runCapture(cmd, args, { cwd, env } = {}) {
+  return await new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    proc.stdout.on('data', (c) => (out += String(c)));
+    proc.stderr.on('data', (c) => (err += String(c)));
+    proc.on('error', reject);
+    proc.on('close', (code) => {
+      if (code === 0) resolve(out);
+      else reject(new Error(`command failed: ${cmd} ${args.join(' ')} (code=${code})\n${err}`));
+    });
+  });
+}
+
 function expectedCacheEnv({ envPath }) {
   const base = join(dirname(envPath), 'cache');
   return {
@@ -155,13 +201,85 @@ test('ensureDepsInstalled sets stack-scoped cache env vars for yarn installs', a
   assert.equal(parsed.npm_config_cache, exp.npm);
 });
 
+test('ensureDepsInstalled skips dependency refresh in service mode when node_modules already exists', async (t) => {
+  const fixture = await createStackCacheFixture(t, 'hs-pm-stack-cache-service-install-skip-');
+  const { root, envPath, componentDir, binDir } = fixture;
+  const outputPath = join(root, 'argv.txt');
+
+  await writeYarnArgDumpStub({ binDir, outputPath });
+
+  // Simulate existing node_modules + stale integrity so refresh would normally run.
+  await mkdir(join(componentDir, 'node_modules'), { recursive: true });
+  await writeFile(join(componentDir, 'node_modules', '.yarn-integrity'), 'old\n', 'utf-8');
+  await writeFile(join(componentDir, 'yarn.lock'), '# new lock\n', 'utf-8');
+
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    OUTPUT_PATH: outputPath,
+    HAPPIER_STACK_ENV_FILE: envPath,
+    HAPPIER_STACK_SERVICE_MODE: '1',
+  });
+
+  await ensureDepsInstalled(componentDir, 'test-component', { quiet: true, env: process.env });
+  const out = await readFile(outputPath, 'utf-8');
+  assert.ok(!out.includes('install'), `expected no yarn install in service mode, got:\n${out}`);
+});
+
+test('ensureDepsInstalled scrubs production-mode env for yarn installs', async (t) => {
+  const fixture = await createStackCacheFixture(t, 'hs-pm-stack-cache-prod-scrub-');
+  const { root, envPath, componentDir, binDir } = fixture;
+  const outputPath = join(root, 'env.json');
+  await writeYarnEnvDumpStub({ binDir, outputPath });
+
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    OUTPUT_PATH: outputPath,
+    HAPPIER_STACK_ENV_FILE: envPath,
+    NODE_ENV: 'production',
+    YARN_PRODUCTION: '1',
+    npm_config_production: 'true',
+    NPM_CONFIG_PRODUCTION: 'true',
+  });
+
+  await ensureDepsInstalled(componentDir, 'test-component', { quiet: true });
+  const parsed = JSON.parse(await readFile(outputPath, 'utf-8'));
+  assert.notEqual(parsed.NODE_ENV, 'production');
+  assert.notEqual(parsed.YARN_PRODUCTION, '1');
+  assert.notEqual(parsed.npm_config_production, 'true');
+  assert.notEqual(parsed.NPM_CONFIG_PRODUCTION, 'true');
+});
+
+test('ensureDepsInstalled scrubs production-mode env even without a stack env file', async (t) => {
+  const fixture = await createStackCacheFixture(t, 'hs-pm-prod-scrub-no-env-file-');
+  const { root, componentDir, binDir } = fixture;
+  const outputPath = join(root, 'env.json');
+  await writeYarnEnvDumpStub({ binDir, outputPath });
+
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    OUTPUT_PATH: outputPath,
+    HAPPIER_STACK_ENV_FILE: null,
+    NODE_ENV: 'production',
+    YARN_PRODUCTION: '1',
+    npm_config_production: 'true',
+    NPM_CONFIG_PRODUCTION: 'true',
+  });
+
+  await ensureDepsInstalled(componentDir, 'test-component', { quiet: true });
+  const parsed = JSON.parse(await readFile(outputPath, 'utf-8'));
+  assert.notEqual(parsed.NODE_ENV, 'production');
+  assert.notEqual(parsed.YARN_PRODUCTION, '1');
+  assert.notEqual(parsed.npm_config_production, 'true');
+  assert.notEqual(parsed.NPM_CONFIG_PRODUCTION, 'true');
+});
+
 test('ensureDepsInstalled prefers yarn when component is inside the Happy monorepo (packages/ layout)', async (t) => {
   const root = await mkdtemp(join(tmpdir(), 'hs-pm-happy-monorepo-yarn-'));
   t.after(async () => {
     await rm(root, { recursive: true, force: true });
   });
 
-  // Create the minimum monorepo markers (packages/ layout) + root yarn.lock.
+  // Create the minimum monorepo markers (apps/ layout) + root yarn.lock.
   await mkdir(join(root, 'apps', 'ui'), { recursive: true });
   await mkdir(join(root, 'apps', 'cli'), { recursive: true });
   await mkdir(join(root, 'apps', 'server'), { recursive: true });
@@ -189,6 +307,79 @@ test('ensureDepsInstalled prefers yarn when component is inside the Happy monore
   assert.ok(out.includes('install') || out.includes('--version'));
 });
 
+test('ensureDepsInstalled forces non-production yarn installs', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-yarn-production-flag-'));
+  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');
+  await writeFile(join(root, 'package.json'), '{ "name": "monorepo", "private": true }\n', 'utf-8');
+  await writeFile(join(root, 'yarn.lock'), '# yarn\n', 'utf-8');
+
+  const componentDir = join(root, 'apps', 'server');
+  const binDir = join(root, 'bin');
+  const outputPath = join(root, 'argv.txt');
+  await writeYarnArgDumpStub({ binDir, outputPath });
+
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:/usr/bin:/bin`,
+    OUTPUT_PATH: outputPath,
+    HAPPIER_STACK_ENV_FILE: null,
+  });
+
+  await ensureDepsInstalled(componentDir, 'happier-server', { quiet: true });
+  const out = await readFile(outputPath, 'utf-8');
+  const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+  const installLine = lines.find((l) => l.startsWith('install'));
+  assert.ok(installLine, `expected yarn install to be invoked, got:\n${out}`);
+  assert.match(installLine, /--production=false\b/);
+});
+
+test('ensureDepsInstalled refreshes monorepo dependencies when root yarn.lock changes', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-happy-monorepo-refresh-'));
+  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');
+  await writeFile(join(root, 'package.json'), '{ "name": "monorepo", "private": true }\n', 'utf-8');
+
+  // Simulate an already-installed workspace (so we don't trigger the first-run install branch).
+  await mkdir(join(root, 'apps', 'ui', 'node_modules'), { recursive: true });
+
+  // Simulate a previous monorepo install.
+  await mkdir(join(root, 'node_modules'), { recursive: true });
+  await writeFile(join(root, 'node_modules', '.yarn-integrity'), 'ok\n', 'utf-8');
+
+  // Root yarn.lock is newer than the integrity file -> should trigger `yarn install`.
+  await writeFile(join(root, 'yarn.lock'), '# yarn\n', 'utf-8');
+
+  const binDir = join(root, 'bin');
+  const outputPath = join(root, 'argv.txt');
+  await writeYarnArgDumpStub({ binDir, outputPath });
+
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:/usr/bin:/bin`,
+    OUTPUT_PATH: outputPath,
+    HAPPIER_STACK_ENV_FILE: null,
+  });
+
+  await ensureDepsInstalled(join(root, 'apps', 'ui'), 'happier-ui', { quiet: true });
+  const out = await readFile(outputPath, 'utf-8');
+  assert.match(out, /\binstall\b/);
+});
+
 test('ensureDepsInstalled falls back to npm in binary mode when yarn is unavailable', async (t) => {
   const root = await mkdtemp(join(tmpdir(), 'hs-pm-binary-mode-npm-'));
   t.after(async () => {
@@ -311,3 +502,55 @@ test('ensureCliBuilt restores dist from .dist.hstack-backup when previous build
   const argv = await readFile(outputPath, 'utf-8');
   assert.ok(!argv.includes('build'), `expected no build invocation, got: ${argv}`);
 });
+
+test('ensureCliBuilt defaults to no rebuild in service mode even when git signature changed', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-pm-cli-build-service-skip-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const cliDir = join(root, 'apps', 'cli');
+  await mkdir(cliDir, { recursive: true });
+  await writeFile(join(cliDir, 'package.json'), '{ "name": "cli-test" }\n', 'utf-8');
+  await writeFile(join(cliDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+  await mkdir(join(cliDir, 'node_modules'), { recursive: true });
+  await writeFile(join(cliDir, 'node_modules', '.yarn-integrity'), 'ok\n', 'utf-8');
+  const distIndex = join(cliDir, 'dist', 'index.mjs');
+  await mkdir(dirname(distIndex), { recursive: true });
+  await writeFile(distIndex, 'export const stable = true;\n', 'utf-8');
+
+  // Real git repo so computeGitWorktreeSignature() returns a signature.
+  await runCapture('git', ['init'], { cwd: cliDir });
+  await runCapture('git', ['config', 'user.email', 'hstack-test@example.test'], { cwd: cliDir });
+  await runCapture('git', ['config', 'user.name', 'hstack-test'], { cwd: cliDir });
+  await runCapture('git', ['add', '.'], { cwd: cliDir });
+  await runCapture('git', ['commit', '-m', 'init'], { cwd: cliDir });
+
+  const binDir = join(root, 'bin');
+  const outputPath = join(root, 'argv.txt');
+  await writeYarnBuildCreatesDistStub({ binDir, outputPath, cliDir });
+
+  // 1) Force an initial build so a build state is written.
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:/usr/bin:/bin`,
+    OUTPUT_PATH: outputPath,
+    HAPPIER_STACK_HOME_DIR: join(root, 'home'),
+    HAPPIER_STACK_CLI_BUILD_MODE: 'always',
+    HAPPIER_STACK_SERVICE_MODE: null,
+    HAPPIER_STACK_ENV_FILE: null,
+  });
+  await ensureCliBuilt(cliDir, { buildCli: true, quiet: true, env: process.env });
+  const out1 = await readFile(outputPath, 'utf-8');
+  assert.match(out1, /\bbuild\b/, `expected initial build, got:\n${out1}`);
+
+  // 2) Dirty the worktree so git signature changes (auto mode would rebuild).
+  await writeFile(join(cliDir, 'dirty.txt'), 'x\n', 'utf-8');
+  await writeFile(outputPath, '', 'utf-8');
+  applyEnvOverrides(t, {
+    HAPPIER_STACK_CLI_BUILD_MODE: null,
+    HAPPIER_STACK_SERVICE_MODE: '1',
+  });
+  await ensureCliBuilt(cliDir, { buildCli: true, quiet: true, env: process.env });
+  const out2 = await readFile(outputPath, 'utf-8');
+  assert.ok(!out2.includes('build'), `expected no rebuild in service mode, got:\n${out2}`);
+});

package/scripts/utils/proc/proc.mjs

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
-import { createWriteStream } from 'node:fs';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
 
 function nextLineBreakIndex(s) {
   const n = s.indexOf('\n');
@@ -33,6 +34,12 @@ function flushPrefixed(stream, prefix, bufState) {
   bufState.buf = '';
 }
 
+function sanitizeLogFileToken(raw) {
+  const s = String(raw ?? '').trim().toLowerCase();
+  const cleaned = s.replace(/[^a-z0-9._-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+  return cleaned || 'proc';
+}
+
 export function spawnProc(label, cmd, args, env, options = {}) {
   const { silent = false, teeFile, teeLabel, ...spawnOptions } = options ?? {};
   const child = spawn(cmd, args, {
@@ -49,7 +56,18 @@ export function spawnProc(label, cmd, args, env, options = {}) {
   const outPrefix = `[${label}] `;
   const errPrefix = `[${label}] `;
 
-  const teePath = typeof teeFile === 'string' && teeFile.trim() ? teeFile.trim() : '';
+  let teePath = typeof teeFile === 'string' && teeFile.trim() ? teeFile.trim() : '';
+  if (!teePath) {
+    const teeDir = String(env?.HAPPIER_STACK_LOG_TEE_DIR ?? '').trim();
+    if (teeDir) {
+      try {
+        mkdirSync(teeDir, { recursive: true });
+      } catch {
+        // ignore
+      }
+      teePath = join(teeDir, `${sanitizeLogFileToken(label)}.log`);
+    }
+  }
   const teeStream = teePath ? createWriteStream(teePath, { flags: 'a' }) : null;
   const teeOutState = { buf: '' };
   const teeErrState = { buf: '' };

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

@@ -4,7 +4,7 @@ import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { runCaptureResult } from './proc.mjs';
+import { runCaptureResult, spawnProc } from './proc.mjs';
 
 async function withTempRoot(t) {
   const root = await mkdtemp(join(tmpdir(), 'happy-proc-test-'));
@@ -83,3 +83,18 @@ test('runCaptureResult emits periodic keepalive logs while process is running',
   const raw = await readFile(teeFile, 'utf-8');
   assert.match(raw, /\[keepalive-test\] still running \(elapsed \d+s, pid=\d+\)/);
 });
+
+test('spawnProc can tee output to an env-scoped tee dir when no explicit teeFile is provided', async (t) => {
+  const root = await withTempRoot(t);
+  const teeDir = join(root, 'tee');
+  const env = { ...process.env, HAPPIER_STACK_LOG_TEE_DIR: teeDir };
+
+  const child = spawnProc('server', process.execPath, ['-e', 'console.log("hello"); console.error("oops")'], env, {
+    silent: true,
+  });
+  await new Promise((resolve) => child.on('exit', resolve));
+
+  const raw = await readFile(join(teeDir, 'server.log'), 'utf-8');
+  assert.match(raw, /\[server\] hello/);
+  assert.match(raw, /\[server\] oops/);
+});

package/scripts/utils/server/port.mjs

@@ -26,8 +26,26 @@ export function coercePort(v) {
 
 export function resolveServerPortFromEnv({ env = process.env, defaultPort = 3005 } = {}) {
   const raw = (env.HAPPIER_STACK_SERVER_PORT ?? '').toString().trim() || '';
-  const n = raw ? Number(raw) : Number(defaultPort);
-  return Number.isFinite(n) && n > 0 ? n : Number(defaultPort);
+  const explicitPort = raw ? Number(raw) : NaN;
+  if (Number.isFinite(explicitPort) && explicitPort > 0) {
+    return explicitPort;
+  }
+
+  const serverUrlRaw = (env.HAPPIER_SERVER_URL ?? '').toString().trim();
+  if (serverUrlRaw) {
+    try {
+      const parsed = new URL(serverUrlRaw);
+      const urlPort = Number(parsed.port);
+      if (Number.isFinite(urlPort) && urlPort > 0) {
+        return urlPort;
+      }
+    } catch {
+      // Ignore invalid URL and use the default fallback below.
+    }
+  }
+
+  const fallback = Number(defaultPort);
+  return Number.isFinite(fallback) && fallback > 0 ? fallback : 3005;
 }
 
 export function listPortsFromEnvObject(env, keys) {