@happier-dev/stack 0.2.0 → 0.2.1-preview.1775586714.26562

package/scripts/ghops.test.mjs

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { chmodSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import test from 'node:test';
@@ -76,3 +76,44 @@ process.stdout.write(JSON.stringify(payload));
   assert.equal(out.env.GH_PROMPT_DISABLED, '1');
   assert.equal(out.env.GH_CONFIG_DIR, configDir);
 });
+
+test('expands ~/ overrides for gh binary and config dir against HOME', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ghops-home-test-'));
+  const homeDir = join(dir, 'home');
+  const fakeGh = join(homeDir, 'bin', 'fake-gh');
+  const configDir = join(homeDir, 'gh-config');
+  mkdirSync(join(homeDir, 'bin'), { recursive: true });
+
+  writeFileSync(
+    fakeGh,
+    `#!/usr/bin/env node
+const payload = {
+  argv: process.argv.slice(2),
+  env: {
+    GH_TOKEN: process.env.GH_TOKEN ?? null,
+    GH_PROMPT_DISABLED: process.env.GH_PROMPT_DISABLED ?? null,
+    GH_CONFIG_DIR: process.env.GH_CONFIG_DIR ?? null,
+  },
+};
+process.stdout.write(JSON.stringify(payload));
+`,
+    'utf8',
+  );
+  chmodSync(fakeGh, 0o755);
+
+  const token = 'test-bot-token';
+  const res = runGhop(['api', 'user'], {
+    HOME: homeDir,
+    USERPROFILE: homeDir,
+    HAPPIER_GITHUB_BOT_TOKEN: token,
+    HAPPIER_GHOPS_GH_PATH: '~/bin/fake-gh',
+    HAPPIER_GHOPS_CONFIG_DIR: '~/gh-config',
+  });
+
+  assert.equal(res.status, 0, res.stderr);
+  const out = JSON.parse(res.stdout);
+  assert.deepEqual(out.argv, ['api', 'user']);
+  assert.equal(out.env.GH_TOKEN, token);
+  assert.equal(out.env.GH_PROMPT_DISABLED, '1');
+  assert.equal(out.env.GH_CONFIG_DIR, configDir);
+});

package/scripts/happier.mjs

@@ -5,7 +5,7 @@ import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getComponentDir, getRootDir, getStackName } from './utils/paths/paths.mjs';
+import { getComponentDir, getRootDir, getStackName, resolveExplicitStackEnvFilePath } from './utils/paths/paths.mjs';
 import { resolveCliHomeDir } from './utils/stack/dirs.mjs';
 import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv } from './utils/server/urls.mjs';
 import { resolveLocalServerPortForStack } from './utils/server/resolve_stack_server_port.mjs';
@@ -328,7 +328,7 @@ async function main() {
   // We treat an invocation as "stack-scoped" only when the stack env file actually exists (or when the
   // CLI home dir is explicitly overridden by the stack). This keeps plain `hstack happier` able to
   // reuse the user's CLI settings even when stack helper env vars are present in test/dev harnesses.
-  const stackEnvFilePath = String(env.HAPPIER_STACK_ENV_FILE ?? '').trim();
+  const stackEnvFilePath = resolveExplicitStackEnvFilePath(env);
   const isStackScopedInvocation =
     Boolean(String(env.HAPPIER_STACK_CLI_HOME_DIR ?? '').trim()) ||
     Boolean(stackEnvFilePath && existsSync(stackEnvFilePath));

package/scripts/menubar.mjs

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { getHappyStacksHomeDir, getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { getHappyStacksHomeDir, getRootDir, resolveExplicitStackEnvFilePath, resolveStackEnvPath } from './utils/paths/paths.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
@@ -208,7 +208,7 @@ async function main() {
     const pluginBasename = String(process.env.HAPPIER_STACK_SWIFTBAR_PLUGIN_BASENAME ?? '').trim() || defaultBasename;
     const pluginFile = `${pluginBasename}.${interval}.sh`;
 
-    const defaultEnvFile = (process.env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim();
+    const defaultEnvFile = resolveExplicitStackEnvFilePath(process.env);
     const resolvedEnvFile = explicitStack
       ? resolveStackEnvPath(normalizedStack, process.env).envPath
       : (defaultEnvFile || resolveStackEnvPath(normalizedStack, process.env).envPath);

package/scripts/run.mjs

@@ -2,7 +2,7 @@ import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { pathExists } from './utils/fs/fs.mjs';
 import { killProcessTree, runCapture, spawnProc } from './utils/proc/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir, resolveExplicitStackEnvFilePath } from './utils/paths/paths.mjs';
 import { killPortListeners } from './utils/net/ports.mjs';
 import { getServerComponentName, isHappierServerRunning, waitForServerReady } from './utils/server/server.mjs';
 import { ensureCliBuilt, ensureDepsInstalled, pmExecBin, pmSpawnScript, requireDir } from './utils/proc/pm.mjs';
@@ -387,7 +387,7 @@ async function main() {
   if (serverComponentName === 'happier-server') {
     const managed = (baseEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1') !== '0';
     if (managed) {
-      const envPath = baseEnv.HAPPIER_STACK_ENV_FILE ?? '';
+      const envPath = resolveExplicitStackEnvFilePath(baseEnv);
       const infra = await ensureHappyServerManagedInfra({
         stackName: autostart.stackName,
         baseDir: autostart.baseDir,

package/scripts/self_host_runtime.mjs

@@ -35,6 +35,8 @@ import {
 } from '@happier-dev/cli-common/service';
 import {
   parseEnvText as parseEnvTextShared,
+  resolveConfiguredRelayRuntimeBinaryOverride,
+  resolveConfiguredRelayRuntimePaths,
   renderSelfHostServerEnvText as renderSelfHostServerEnvTextShared,
 } from '@happier-dev/cli-common/firstPartyRuntime';
 import { DEFAULT_MINISIGN_PUBLIC_KEY } from '@happier-dev/release-runtime/minisign';
@@ -469,13 +471,14 @@ async function applySelfHostSqliteMigrationsAtInstallTime({ env }) {
   return { applied: appliedNow, skipped: false, reason: 'ok' };
 }
 
-function resolveConfig({ channel, mode = 'user', platform = process.platform } = {}) {
+export function resolveConfig({ channel, mode = 'user', platform = process.platform } = {}) {
   const defaults = resolveSelfHostDefaults({ platform, mode, channel, homeDir: homedir() });
-  const installRoot = String(process.env.HAPPIER_SELF_HOST_INSTALL_ROOT ?? defaults.installRoot).trim();
-  const binDir = String(process.env.HAPPIER_SELF_HOST_BIN_DIR ?? defaults.binDir).trim();
-  const configDir = String(process.env.HAPPIER_SELF_HOST_CONFIG_DIR ?? defaults.configDir).trim();
-  const dataDir = String(process.env.HAPPIER_SELF_HOST_DATA_DIR ?? defaults.dataDir).trim();
-  const logDir = String(process.env.HAPPIER_SELF_HOST_LOG_DIR ?? defaults.logDir).trim();
+  const configuredPaths = resolveConfiguredRelayRuntimePaths({ defaults, env: process.env });
+  const installRoot = configuredPaths.installRoot;
+  const binDir = configuredPaths.binDir;
+  const configDir = configuredPaths.configDir;
+  const dataDir = configuredPaths.dataDir;
+  const logDir = configuredPaths.logDir;
   const serviceName = String(process.env.HAPPIER_SELF_HOST_SERVICE_NAME ?? DEFAULTS.serviceName).trim();
   const serverHost = String(process.env.HAPPIER_SERVER_HOST ?? DEFAULTS.serverHost).trim();
   const serverPort = parsePort(process.env.HAPPIER_SERVER_PORT, DEFAULTS.serverPort);
@@ -1914,7 +1917,7 @@ async function cmdInstall({ channel, mode, argv, json }) {
       || parseBoolean(process.env.HAPPIER_WITH_UI, true) === false
       || parseBoolean(process.env.HAPPIER_SELF_HOST_WITH_UI, true) === false);
   const nonInteractive = argvSansEnv.includes('--non-interactive') || parseBoolean(process.env.HAPPIER_NONINTERACTIVE, false);
-  const serverBinaryOverride = String(process.env.HAPPIER_SELF_HOST_SERVER_BINARY ?? '').trim();
+  const serverBinaryOverride = resolveConfiguredRelayRuntimeBinaryOverride(process.env);
 
   if (normalizeOs(config.platform) !== 'windows' && !commandExists('tar')) {
     throw new Error('[self-host] tar is required to extract release artifacts');

package/scripts/self_host_runtime.test.mjs

@@ -983,6 +983,53 @@ test('resolveSelfHostDefaults isolates publicdev into a side-by-side self-host r
   assert.equal(cfg.serviceName, 'happier-server-dev');
 });
 
+test('resolveConfig expands ~/ self-host path overrides against HOME', async () => {
+  const mod = await import('./self_host_runtime.mjs');
+  assert.equal(typeof mod.resolveConfig, 'function');
+
+  const previous = {
+    HOME: process.env.HOME,
+    USERPROFILE: process.env.USERPROFILE,
+    HAPPIER_SELF_HOST_INSTALL_ROOT: process.env.HAPPIER_SELF_HOST_INSTALL_ROOT,
+    HAPPIER_SELF_HOST_BIN_DIR: process.env.HAPPIER_SELF_HOST_BIN_DIR,
+    HAPPIER_SELF_HOST_CONFIG_DIR: process.env.HAPPIER_SELF_HOST_CONFIG_DIR,
+    HAPPIER_SELF_HOST_DATA_DIR: process.env.HAPPIER_SELF_HOST_DATA_DIR,
+    HAPPIER_SELF_HOST_LOG_DIR: process.env.HAPPIER_SELF_HOST_LOG_DIR,
+  };
+
+  process.env.HOME = '/scoped/home';
+  process.env.USERPROFILE = '/scoped/home';
+  process.env.HAPPIER_SELF_HOST_INSTALL_ROOT = '~/relay/install';
+  process.env.HAPPIER_SELF_HOST_BIN_DIR = '~/relay/bin';
+  process.env.HAPPIER_SELF_HOST_CONFIG_DIR = '~/relay/config';
+  process.env.HAPPIER_SELF_HOST_DATA_DIR = '~/relay/data';
+  process.env.HAPPIER_SELF_HOST_LOG_DIR = '~/relay/logs';
+
+  try {
+    const config = mod.resolveConfig({ platform: 'linux', mode: 'user', channel: 'stable' });
+    assert.equal(config.installRoot, '/scoped/home/relay/install');
+    assert.equal(config.binDir, '/scoped/home/relay/bin');
+    assert.equal(config.configDir, '/scoped/home/relay/config');
+    assert.equal(config.dataDir, '/scoped/home/relay/data');
+    assert.equal(config.logDir, '/scoped/home/relay/logs');
+  } finally {
+    if (previous.HOME === undefined) delete process.env.HOME;
+    else process.env.HOME = previous.HOME;
+    if (previous.USERPROFILE === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = previous.USERPROFILE;
+    if (previous.HAPPIER_SELF_HOST_INSTALL_ROOT === undefined) delete process.env.HAPPIER_SELF_HOST_INSTALL_ROOT;
+    else process.env.HAPPIER_SELF_HOST_INSTALL_ROOT = previous.HAPPIER_SELF_HOST_INSTALL_ROOT;
+    if (previous.HAPPIER_SELF_HOST_BIN_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_BIN_DIR;
+    else process.env.HAPPIER_SELF_HOST_BIN_DIR = previous.HAPPIER_SELF_HOST_BIN_DIR;
+    if (previous.HAPPIER_SELF_HOST_CONFIG_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_CONFIG_DIR;
+    else process.env.HAPPIER_SELF_HOST_CONFIG_DIR = previous.HAPPIER_SELF_HOST_CONFIG_DIR;
+    if (previous.HAPPIER_SELF_HOST_DATA_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_DATA_DIR;
+    else process.env.HAPPIER_SELF_HOST_DATA_DIR = previous.HAPPIER_SELF_HOST_DATA_DIR;
+    if (previous.HAPPIER_SELF_HOST_LOG_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_LOG_DIR;
+    else process.env.HAPPIER_SELF_HOST_LOG_DIR = previous.HAPPIER_SELF_HOST_LOG_DIR;
+  }
+});
+
 test('resolveMinisignPublicKeyText prefers inline override and otherwise returns bundled key', () => {
   const bundled = resolveMinisignPublicKeyText({});
   assert.match(bundled, /minisign public key/i);

package/scripts/service.mjs

@@ -1,6 +1,13 @@
 import './utils/env/env.mjs';
 import { run, runCapture } from './utils/proc/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir, getSystemdUnitInfo, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import {
+  getComponentDir,
+  getDefaultAutostartPaths,
+  getRootDir,
+  getSystemdUnitInfo,
+  resolveExplicitStackEnvFilePath,
+  resolveStackEnvPath,
+} from './utils/paths/paths.mjs';
 import { getInternalServerUrl, getPublicServerUrlEnvOverride } from './utils/server/urls.mjs';
 import { resolveServerUrls } from './utils/server/urls.mjs';
 import { installService as installManagedService, uninstallService as uninstallManagedService } from './utils/service/service_manager.mjs';
@@ -67,7 +74,7 @@ function getAutostartEnv({ mode, systemUserHomeDir } = {}) {
   // Main installs:
   // - default to the main stack env (outside the repo): ~/.happier/stacks/main/env
 
-  const explicitEnvFilePath = process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '';
+  const explicitEnvFilePath = resolveExplicitStackEnvFilePath(process.env);
   const defaultMainEnvFilePath = resolveStackEnvPath('main').envPath;
   const envFile = resolveAutostartEnvFilePath({
     mode,
@@ -546,7 +553,7 @@ async function stopLaunchAgent({ persistent, requestedBy = 'service stop', reaso
 
   const envFile = resolveAutostartEnvFilePath({
     mode: 'user',
-    explicitEnvFilePath: process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '',
+    explicitEnvFilePath: resolveExplicitStackEnvFilePath(process.env),
     defaultMainEnvFilePath: resolveStackEnvPath('main').envPath,
     systemUserHomeDir: null,
   });

package/scripts/stack.mjs

@@ -15,6 +15,7 @@ import {
   getRootDir,
   getWorkspaceDir,
   happyMonorepoSubdirForComponent,
+  resolveExplicitStackEnvFilePath,
   resolveStackEnvPath,
 } from './utils/paths/paths.mjs';
 import { isTcpPortFree, pickNextFreeTcpPort } from './utils/net/ports.mjs';
@@ -1115,7 +1116,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
                 serverPort,
                 internalServerUrl,
                 publicServerUrl,
-                envPath: env.HAPPIER_STACK_ENV_FILE ?? '',
+                envPath: resolveExplicitStackEnvFilePath(env),
                 stackMode: true,
                 runtimeStatePath: null,
                 serverAlreadyRunning: false,
@@ -1141,7 +1142,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
                 stackMode: true,
                 runtimeStatePath: null,
                 stackName: name,
-                envPath: env.HAPPIER_STACK_ENV_FILE ?? '',
+                envPath: resolveExplicitStackEnvFilePath(env),
                 children,
                 spawnOptions: quietAuthFlow ? { silent: true, teeFile: expoLogPath, teeLabel: 'expo' } : {},
                 quiet: quietAuthFlow,

package/scripts/tailscale.mjs

@@ -4,7 +4,7 @@ import { run } from './utils/proc/proc.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 import { getInternalServerUrl } from './utils/server/urls.mjs';
-import { getStackName, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { getStackName, resolveExplicitStackEnvFilePath, resolveStackEnvPath } from './utils/paths/paths.mjs';
 import { banner, bullets, cmd as cmdFmt, kv, ok, sectionTitle } from './utils/ui/layout.mjs';
 import { cyan, dim, green } from './utils/ui/ansi.mjs';
 import {
@@ -352,7 +352,7 @@ async function main() {
         );
       }
       const stackName = getStackName(process.env);
-      const envPath = (process.env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim() || resolveStackEnvPath(stackName, process.env).envPath;
+      const envPath = resolveExplicitStackEnvFilePath(process.env) || resolveStackEnvPath(stackName, process.env).envPath;
       const { upstream } = getServeConfig(internalServerUrl);
       const res = await tailscaleServeEnable({ internalServerUrl });
       if (res?.enableUrl && !res?.httpsUrl) {

package/scripts/utils/env/config.mjs

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { ensureEnvFileUpdated } from './env_file.mjs';
-import { getHappyStacksHomeDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getHappyStacksHomeDir, resolveActiveStackEnvFilePath } from '../paths/paths.mjs';
 import { getCanonicalHomeDirFromEnv } from '../paths/canonical_home.mjs';
 
 export function getHomeEnvPath() {
@@ -20,17 +20,12 @@ export function getHomeEnvLocalPath() {
 }
 
 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;
+  return resolveActiveStackEnvFilePath('main', process.env);
 }
 
 export async function ensureHomeEnvUpdated({ updates }) {

package/scripts/utils/env/env.mjs

@@ -3,6 +3,7 @@ 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 { getStacksStorageRoot, resolveExplicitStackEnvFilePath } from '../paths/paths.mjs';
 import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 import { loadEnvFile, loadEnvFileIgnoringPrefixes } from './load_env_file.mjs';
 
@@ -16,7 +17,7 @@ const __cliRootDir = dirname(__scriptsDir);
 function resolveHomeDir() {
   const fromEnv = (process.env.HAPPIER_STACK_HOME_DIR ?? '').trim();
   if (fromEnv) {
-    return expandHome(fromEnv);
+    return expandHome(fromEnv, process.env);
   }
   return join(homedir(), '.happier-stack');
 }
@@ -76,13 +77,13 @@ if (hasHomeConfig) {
   if ((process.env.HAPPIER_STACK_DISABLE_STACK_ENV_AUTOLOAD ?? '').toString().trim() === '1') {
     return;
   }
-  const stacksEnv = (process.env.HAPPIER_STACK_ENV_FILE ?? '').trim();
+  const stacksEnv = resolveExplicitStackEnvFilePath(process.env);
   if (stacksEnv) {
+    process.env.HAPPIER_STACK_ENV_FILE = 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 stacksStorageRoot = getStacksStorageRoot(process.env);
 
   const candidates = [
     join(stacksStorageRoot, stackName, 'env'),
@@ -98,7 +99,10 @@ if (hasHomeConfig) {
 // 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 stacksEnv = resolveExplicitStackEnvFilePath(process.env);
+  if (stacksEnv) {
+    process.env.HAPPIER_STACK_ENV_FILE = stacksEnv;
+  }
   const unique = Array.from(new Set([stacksEnv].filter(Boolean)));
   for (const p of unique) {
     // eslint-disable-next-line no-await-in-loop

package/scripts/utils/env/env_local.mjs

@@ -3,13 +3,14 @@ import { join } from 'node:path';
 
 import { ensureEnvFileUpdated } from './env_file.mjs';
 import { ensureUserConfigEnvUpdated, getHomeEnvLocalPath, getHomeEnvPath } from './config.mjs';
+import { resolveExplicitStackEnvFilePath } from '../paths/paths.mjs';
 
 export async function ensureEnvLocalUpdated({ rootDir, updates }) {
   // Behavior:
   // - If a stack env file is explicitly set, write there (stack-scoped).
   // - If the user has run `hstack init` (home config exists), write to the main stack env file (user config).
   // - If no home config exists (legacy cloned-repo usage), write to <repo>/env.local for repo-local behavior.
-  const explicit = (process.env.HAPPIER_STACK_ENV_FILE ?? '').trim();
+  const explicit = resolveExplicitStackEnvFilePath(process.env);
   if (explicit) {
     await ensureEnvFileUpdated({ envPath: explicit, updates });
     return;

package/scripts/utils/paths/canonical_home.mjs

@@ -1,13 +1,21 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export function expandHome(p) {
-  return String(p ?? '').replace(/^~(?=[/\\])/, homedir());
+function resolveHomeDirFromEnv(env = process.env) {
+  const candidate = process.platform === 'win32'
+    ? (env?.USERPROFILE ?? env?.HOME)
+    : env?.HOME;
+  const trimmed = String(candidate ?? '').trim();
+  return trimmed || homedir();
+}
+
+export function expandHome(p, env = process.env) {
+  return String(p ?? '').replace(/^~(?=[/\\])/, resolveHomeDirFromEnv(env));
 }
 
 export function getCanonicalHomeDirFromEnv(env = process.env) {
   const fromEnv = (env.HAPPIER_STACK_CANONICAL_HOME_DIR ?? '').trim();
-  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happier-stack');
+  return fromEnv ? expandHome(fromEnv, env) : join(resolveHomeDirFromEnv(env), '.happier-stack');
 }
 
 export function getCanonicalHomeEnvPathFromEnv(env = process.env) {

package/scripts/utils/paths/canonical_home.test.mjs

@@ -5,10 +5,12 @@ import { homedir } from 'node:os';
 import { expandHome, getCanonicalHomeDirFromEnv, getCanonicalHomeEnvPathFromEnv } from './canonical_home.mjs';
 
 test('expandHome expands ~/ paths', () => {
+  assert.equal(expandHome('~/x', { HOME: '/scoped/home' }), '/scoped/home/x');
   assert.equal(expandHome('~/x'), `${homedir()}/x`);
 });
 
 test('expandHome expands ~\\ paths (Windows)', () => {
+  assert.equal(expandHome('~\\x', { HOME: '/scoped/home', USERPROFILE: '/scoped/home' }), '/scoped/home\\x');
   assert.equal(expandHome('~\\x'), `${homedir()}\\x`);
 });
 
@@ -18,11 +20,17 @@ test('expandHome leaves non-home-prefixed paths unchanged', () => {
 });
 
 test('getCanonicalHomeDirFromEnv expands override and defaults to ~/.happier-stack', () => {
-  assert.equal(getCanonicalHomeDirFromEnv({ HAPPIER_STACK_CANONICAL_HOME_DIR: '~/custom-home' }), `${homedir()}/custom-home`);
+  assert.equal(
+    getCanonicalHomeDirFromEnv({ HOME: '/scoped/home', HAPPIER_STACK_CANONICAL_HOME_DIR: '~/custom-home' }),
+    '/scoped/home/custom-home'
+  );
   assert.equal(getCanonicalHomeDirFromEnv({}), `${homedir()}/.happier-stack`);
 });
 
 test('getCanonicalHomeEnvPathFromEnv resolves .env under canonical home', () => {
-  const envPath = getCanonicalHomeEnvPathFromEnv({ HAPPIER_STACK_CANONICAL_HOME_DIR: '~/custom-home' });
-  assert.equal(envPath, `${homedir()}/custom-home/.env`);
+  const envPath = getCanonicalHomeEnvPathFromEnv({
+    HOME: '/scoped/home',
+    HAPPIER_STACK_CANONICAL_HOME_DIR: '~/custom-home',
+  });
+  assert.equal(envPath, '/scoped/home/custom-home/.env');
 });

package/scripts/utils/paths/paths.mjs

@@ -108,7 +108,7 @@ export function getRootDir(importMetaUrl) {
 export function getHappyStacksHomeDir(env = process.env) {
   const fromEnv = (env.HAPPIER_STACK_HOME_DIR ?? '').trim();
   if (fromEnv) {
-    return expandHome(fromEnv);
+    return expandHome(fromEnv, env);
   }
   return PRIMARY_HOME_DIR;
 }
@@ -116,9 +116,9 @@ export function getHappyStacksHomeDir(env = process.env) {
 export function getWorkspaceDir(cliRootDir = null, env = process.env) {
   const fromEnv = (env.HAPPIER_STACK_WORKSPACE_DIR ?? '').trim();
   if (fromEnv) {
-    return expandHome(fromEnv);
+    return expandHome(fromEnv, env);
   }
-  const homeDir = getHappyStacksHomeDir();
+  const homeDir = getHappyStacksHomeDir(env);
   return join(homeDir, 'workspace');
 }
 
@@ -159,7 +159,7 @@ function normalizePathForEnv(rootDir, raw, env = process.env) {
   if (!trimmed) {
     return '';
   }
-  const expanded = expandHome(trimmed);
+  const expanded = expandHome(trimmed, env);
   // If the path is relative, treat it as relative to the workspace root (default: repo root).
   const workspaceDir = getWorkspaceDir(rootDir, env);
   const abs = isAbsolute(expanded) || isWin32ShapedAbsolutePath(expanded);
@@ -244,11 +244,19 @@ export function getStackLabel(stackName = null, env = process.env) {
 export function getStacksStorageRoot(env = process.env) {
   const fromEnv = (env.HAPPIER_STACK_STORAGE_DIR ?? '').trim();
   if (fromEnv) {
-    return expandHome(fromEnv);
+    return expandHome(fromEnv, env);
   }
   return PRIMARY_STORAGE_ROOT;
 }
 
+export function resolveExplicitStackEnvFilePath(env = process.env) {
+  const explicit = (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim();
+  if (!explicit) {
+    return '';
+  }
+  return expandHome(explicit, env);
+}
+
 export function resolveStackBaseDir(stackName = null, env = process.env) {
   const name = (stackName ?? '').toString().trim() || getStackName(env);
   return { baseDir: join(getStacksStorageRoot(env), name), isLegacy: false };
@@ -260,6 +268,10 @@ export function resolveStackEnvPath(stackName = null, env = process.env) {
   return { envPath: join(baseDir, 'env'), isLegacy: false, baseDir };
 }
 
+export function resolveActiveStackEnvFilePath(stackName = null, env = process.env) {
+  return resolveExplicitStackEnvFilePath(env) || resolveStackEnvPath(stackName, env).envPath;
+}
+
 export function getDefaultAutostartPaths(env = process.env) {
   const stackName = getStackName(env);
   const { baseDir, isLegacy } = resolveStackBaseDir(stackName, env);

package/scripts/utils/paths/paths_home_env.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+
+import {
+  getHappyStacksHomeDir,
+  getStacksStorageRoot,
+  getWorkspaceDir,
+  resolveActiveStackEnvFilePath,
+} from './paths.mjs';
+
+test('stack path overrides expand ~/ against the provided HOME env', () => {
+  const env = {
+    HOME: '/scoped/home',
+    HAPPIER_STACK_HOME_DIR: '~/.happier-stack-custom',
+    HAPPIER_STACK_STORAGE_DIR: '~/.happier/stacks-custom',
+  };
+
+  assert.equal(getHappyStacksHomeDir(env), '/scoped/home/.happier-stack-custom');
+  assert.equal(getWorkspaceDir('/tmp/root', env), '/scoped/home/.happier-stack-custom/workspace');
+  assert.equal(getStacksStorageRoot(env), '/scoped/home/.happier/stacks-custom');
+});
+
+test('resolveActiveStackEnvFilePath expands ~/ explicit overrides against the provided HOME env', () => {
+  const env = {
+    HOME: '/scoped/home',
+    HAPPIER_STACK_ENV_FILE: '~/.happier/stacks/dev/env',
+  };
+
+  assert.equal(resolveActiveStackEnvFilePath('dev', env), '/scoped/home/.happier/stacks/dev/env');
+});
+
+test('resolveActiveStackEnvFilePath falls back to the resolved stack env file when no explicit override is set', () => {
+  const env = {
+    HOME: '/scoped/home',
+    HAPPIER_STACK_STORAGE_DIR: '~/.happier/stacks-custom',
+  };
+
+  assert.equal(
+    resolveActiveStackEnvFilePath('dev', env),
+    join('/scoped/home/.happier/stacks-custom', 'dev', 'env')
+  );
+});

package/scripts/utils/proc/pm.mjs

@@ -8,7 +8,12 @@ import { pathExists } from '../fs/fs.mjs';
 import { readJsonIfExists, writeJsonAtomic } from '../fs/json.mjs';
 import { run, runCapture, spawnProc } from './proc.mjs';
 import { commandExists } from './commands.mjs';
-import { coerceHappyMonorepoRootFromPath, getDefaultAutostartPaths, getHappyStacksHomeDir } from '../paths/paths.mjs';
+import {
+  coerceHappyMonorepoRootFromPath,
+  getDefaultAutostartPaths,
+  getHappyStacksHomeDir,
+  resolveExplicitStackEnvFilePath,
+} from '../paths/paths.mjs';
 import { resolveInstalledPath, resolveInstalledCliRoot } from '../paths/runtime.mjs';
 import { expandHome } from '../paths/canonical_home.mjs';
 import { withCliDistBuildLock } from './cliDistBuildLock.mjs';
@@ -325,12 +330,12 @@ function resolveStackCacheBaseDirFromEnv(env) {
   const explicit = (env.HAPPIER_STACK_PM_CACHE_BASE_DIR ?? '').toString().trim();
   if (explicit) {
     try {
-      return resolve(expandHome(explicit));
+      return resolve(expandHome(explicit, env));
     } catch {
       return null;
     }
   }
-  const envFile = (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim();
+  const envFile = resolveExplicitStackEnvFilePath(env);
   if (!envFile) return null;
   try {
     return join(dirname(envFile), 'cache');
@@ -367,7 +372,7 @@ export async function applyStackCacheEnv(baseEnv) {
     env.NPM_CONFIG_PRODUCTION = 'false';
   }
 
-  const envFile = (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim();
+  const envFile = resolveExplicitStackEnvFilePath(env);
   const stackCacheBase = resolveStackCacheBaseDirFromEnv(env);
   if (!stackCacheBase) return env;
 

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

@@ -452,6 +452,34 @@ test('ensureDepsInstalled honors HAPPIER_STACK_PM_CACHE_BASE_DIR when no stack e
   assert.equal(parsed.HOME, join(cacheBase, 'home'));
 });
 
+test('ensureDepsInstalled derives stack cache roots from ~/ env file overrides against HOME', async (t) => {
+  const fixture = await createStackCacheFixture(t, 'hs-pm-tilde-stack-env-file-');
+  const { root, componentDir, binDir } = fixture;
+  const outputPath = join(root, 'env.json');
+  const homeDir = join(root, 'home');
+  const expectedCacheBase = join(homeDir, '.happier', 'stacks', 'dev', 'cache');
+  const expectedStackHome = join(homeDir, '.happier', 'stacks', 'dev', 'home');
+  await writeYarnEnvDumpStub({ binDir, outputPath });
+
+  applyEnvOverrides(t, {
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    OUTPUT_PATH: outputPath,
+    HOME: homeDir,
+    USERPROFILE: homeDir,
+    HAPPIER_STACK_ENV_FILE: '~/.happier/stacks/dev/env',
+    XDG_CACHE_HOME: null,
+    YARN_CACHE_FOLDER: null,
+    npm_config_cache: null,
+  });
+
+  await ensureDepsInstalled(componentDir, 'test-component', { quiet: true });
+  const parsed = JSON.parse(await readFile(outputPath, 'utf-8'));
+  assert.equal(parsed.XDG_CACHE_HOME, join(expectedCacheBase, 'xdg'));
+  assert.equal(parsed.YARN_CACHE_FOLDER, join(expectedCacheBase, 'yarn'));
+  assert.equal(parsed.npm_config_cache, join(expectedCacheBase, 'npm'));
+  assert.equal(parsed.HOME, expectedStackHome);
+});
+
 test('ensureDepsInstalled prefers the .nvmrc node runtime for yarn shebangs when available', async (t) => {
   const fixture = await createStackCacheFixture(t, 'hs-pm-nvm-node-runtime-');
   const { root, componentDir, binDir } = fixture;

package/scripts/utils/review/targets.mjs

@@ -1,8 +1,8 @@
-import { getRepoDir } from '../paths/paths.mjs';
+import { getRepoDir, resolveExplicitStackEnvFilePath } from '../paths/paths.mjs';
 
 export function isStackMode(env = process.env) {
   const stack = String(env.HAPPIER_STACK_STACK ?? '').trim();
-  const envFile = String(env.HAPPIER_STACK_ENV_FILE ?? '').trim();
+  const envFile = resolveExplicitStackEnvFilePath(env);
   return Boolean(stack && envFile);
 }
 

package/scripts/utils/server/apply_server_light_env_defaults.mjs

@@ -1,14 +1,15 @@
 import { join } from 'node:path';
+import { expandHome } from '../paths/canonical_home.mjs';
 
 export function applyServerLightEnvDefaults({ baseEnv, serverEnv, baseDir }) {
   const dataDir = baseEnv.HAPPIER_SERVER_LIGHT_DATA_DIR?.trim()
-    ? baseEnv.HAPPIER_SERVER_LIGHT_DATA_DIR.trim()
+    ? expandHome(baseEnv.HAPPIER_SERVER_LIGHT_DATA_DIR.trim(), baseEnv)
     : join(baseDir, 'server-light');
   serverEnv.HAPPIER_SERVER_LIGHT_DATA_DIR = dataDir;
   serverEnv.HAPPIER_SERVER_LIGHT_FILES_DIR = baseEnv.HAPPIER_SERVER_LIGHT_FILES_DIR?.trim()
-    ? baseEnv.HAPPIER_SERVER_LIGHT_FILES_DIR.trim()
+    ? expandHome(baseEnv.HAPPIER_SERVER_LIGHT_FILES_DIR.trim(), baseEnv)
     : join(dataDir, 'files');
   serverEnv.HAPPIER_SERVER_LIGHT_DB_DIR = baseEnv.HAPPIER_SERVER_LIGHT_DB_DIR?.trim()
-    ? baseEnv.HAPPIER_SERVER_LIGHT_DB_DIR.trim()
+    ? expandHome(baseEnv.HAPPIER_SERVER_LIGHT_DB_DIR.trim(), baseEnv)
     : join(dataDir, 'pglite');
 }