happy-stacks 0.2.0 → 0.4.0

package/scripts/utils/mobile/ios_xcodeproj_patch.mjs

@@ -0,0 +1,128 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { pathExists } from '../fs/fs.mjs';
+
+function sanitizeXcodeProductName(name) {
+  const raw = (name ?? '').toString().trim();
+  const out = raw
+    .replace(/[^A-Za-z0-9_-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-_]+|[-_]+$/g, '');
+  return out || 'Happy';
+}
+
+async function listIosAppXcodeprojNames({ iosDir }) {
+  let entries = [];
+  try {
+    entries = await readdir(iosDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const names = entries
+    .filter((e) => e.isDirectory() && e.name.endsWith('.xcodeproj') && e.name.startsWith('Happy'))
+    .map((e) => e.name);
+
+  // Prefer the common names first to keep behavior stable if multiple projects exist.
+  const score = (name) => {
+    if (name === 'Happydev.xcodeproj') return 0;
+    if (name === 'Happy.xcodeproj') return 1;
+    return 2;
+  };
+  names.sort((a, b) => score(a) - score(b) || a.localeCompare(b));
+  return names;
+}
+
+export async function resolveIosAppXcodeProjects({ uiDir }) {
+  const iosDir = join(uiDir, 'ios');
+  const projectNames = await listIosAppXcodeprojNames({ iosDir });
+
+  const projects = [];
+  for (const projectName of projectNames) {
+    const pbxprojPath = join(iosDir, projectName, 'project.pbxproj');
+    if (!(await pathExists(pbxprojPath))) {
+      continue;
+    }
+
+    const appDirName = projectName.replace(/\.xcodeproj$/, '');
+    const infoPlistPath = join(iosDir, appDirName, 'Info.plist');
+
+    projects.push({
+      name: appDirName,
+      pbxprojPath,
+      infoPlistPath: (await pathExists(infoPlistPath)) ? infoPlistPath : null,
+    });
+  }
+
+  return projects;
+}
+
+export async function patchIosXcodeProjectsForSigningAndIdentity({
+  uiDir,
+  iosBundleId,
+  iosAppName = '',
+} = {}) {
+  const bundleId = (iosBundleId ?? '').toString().trim();
+  const appName = (iosAppName ?? '').toString().trim();
+  const productName = sanitizeXcodeProductName(appName);
+
+  if (!uiDir || !bundleId) {
+    return;
+  }
+
+  const projects = await resolveIosAppXcodeProjects({ uiDir });
+  if (projects.length === 0) {
+    return;
+  }
+
+  for (const project of projects) {
+    // Patch pbxproj: clear pinned signing fields so Expo can reconfigure and include provisioning update flags,
+    // and force a per-stack bundle id + optional PRODUCT_NAME.
+    try {
+      const raw = await readFile(project.pbxprojPath, 'utf-8');
+      let next = raw;
+
+      // Clear team identifiers (both TargetAttributes and build settings variants).
+      next = next.replaceAll(/^\s*DevelopmentTeam\s*=\s*[^;]+;\s*$/gm, '');
+      next = next.replaceAll(/^\s*DEVELOPMENT_TEAM\s*=\s*[^;]+;\s*$/gm, '');
+      // Clear any pinned provisioning profiles/specifiers (manual signing).
+      next = next.replaceAll(/^\s*PROVISIONING_PROFILE\s*=\s*[^;]+;\s*$/gm, '');
+      next = next.replaceAll(/^\s*PROVISIONING_PROFILE_SPECIFIER\s*=\s*[^;]+;\s*$/gm, '');
+      // Some projects pin code signing identity; remove to let Xcode resolve based on the selected team.
+      next = next.replaceAll(/^\s*CODE_SIGN_IDENTITY\s*=\s*[^;]+;\s*$/gm, '');
+      next = next.replaceAll(/^\s*"CODE_SIGN_IDENTITY\\[sdk=iphoneos\\*\\]"\s*=\s*[^;]+;\s*$/gm, '');
+
+      next = next.replaceAll(/PRODUCT_BUNDLE_IDENTIFIER = [^;]+;/g, `PRODUCT_BUNDLE_IDENTIFIER = ${bundleId};`);
+
+      if (appName) {
+        // Expo CLI appears to treat some escaped build paths as literal (e.g. "Happy\\ (stack).app"),
+        // so keep PRODUCT_NAME free of spaces to avoid breaking post-build Info.plist parsing.
+        next = next.replaceAll(/PRODUCT_NAME = [^;]+;/g, `PRODUCT_NAME = ${productName};`);
+      }
+
+      if (next !== raw) {
+        await writeFile(project.pbxprojPath, next, 'utf-8');
+      }
+    } catch {
+      // ignore project patch errors; Expo will surface actionable failures if needed
+    }
+
+    // Patch Info.plist display name when possible (home screen label).
+    if (appName && project.infoPlistPath) {
+      try {
+        const plistRaw = await readFile(project.infoPlistPath, 'utf-8');
+        const escaped = appName.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+        const replaced = plistRaw.replace(
+          /(<key>CFBundleDisplayName<\/key>\s*<string>)([\s\S]*?)(<\/string>)/m,
+          `$1${escaped}$3`
+        );
+        if (replaced !== plistRaw) {
+          await writeFile(project.infoPlistPath, replaced, 'utf-8');
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+}

package/scripts/utils/mobile/ios_xcodeproj_patch.test.mjs

@@ -0,0 +1,98 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { patchIosXcodeProjectsForSigningAndIdentity } from './ios_xcodeproj_patch.mjs';
+
+async function makeTempUiDir() {
+  return await mkdtemp(join(tmpdir(), 'happy-stacks-mobile-'));
+}
+
+test('patchIosXcodeProjectsForSigningAndIdentity patches legacy ios/Happy.xcodeproj + ios/Happy/Info.plist', async () => {
+  const uiDir = await makeTempUiDir();
+  try {
+    const iosDir = join(uiDir, 'ios');
+    await mkdir(join(iosDir, 'Happy.xcodeproj'), { recursive: true });
+    await mkdir(join(iosDir, 'Happy'), { recursive: true });
+
+    const pbxprojPath = join(iosDir, 'Happy.xcodeproj', 'project.pbxproj');
+    await writeFile(
+      pbxprojPath,
+      [
+        'ProvisioningStyle = Automatic;',
+        'DEVELOPMENT_TEAM = 3RSYVV66F6;',
+        'CODE_SIGN_IDENTITY = "Apple Development";',
+        '"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Developer";',
+        'PROVISIONING_PROFILE_SPECIFIER = some-profile;',
+        'PRODUCT_BUNDLE_IDENTIFIER = com.ex3ndr.happy;',
+        'PRODUCT_NAME = Happy;',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    const infoPlistPath = join(iosDir, 'Happy', 'Info.plist');
+    await writeFile(
+      infoPlistPath,
+      [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<plist version="1.0"><dict>',
+        '<key>CFBundleDisplayName</key><string>Happy</string>',
+        '</dict></plist>',
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    await patchIosXcodeProjectsForSigningAndIdentity({
+      uiDir,
+      iosBundleId: 'com.happystacks.stack.user.pre-pr272',
+      iosAppName: 'HAPPY LEGACY',
+    });
+
+    const pbxproj = await readFile(pbxprojPath, 'utf-8');
+    assert.match(pbxproj, /PRODUCT_BUNDLE_IDENTIFIER = com\.happystacks\.stack\.user\.pre-pr272;/);
+    assert.ok(!pbxproj.includes('DEVELOPMENT_TEAM ='));
+    assert.ok(!pbxproj.includes('PROVISIONING_PROFILE_SPECIFIER ='));
+    assert.ok(!pbxproj.includes('CODE_SIGN_IDENTITY ='));
+    assert.match(pbxproj, /PRODUCT_NAME = HAPPY-LEGACY;/);
+
+    const plist = await readFile(infoPlistPath, 'utf-8');
+    assert.match(plist, /<key>CFBundleDisplayName<\/key><string>HAPPY LEGACY<\/string>/);
+  } finally {
+    await rm(uiDir, { recursive: true, force: true });
+  }
+});
+
+test('patchIosXcodeProjectsForSigningAndIdentity patches both Happydev + Happy projects when present', async () => {
+  const uiDir = await makeTempUiDir();
+  try {
+    const iosDir = join(uiDir, 'ios');
+
+    await mkdir(join(iosDir, 'Happy.xcodeproj'), { recursive: true });
+    await mkdir(join(iosDir, 'Happy'), { recursive: true });
+    await writeFile(join(iosDir, 'Happy.xcodeproj', 'project.pbxproj'), 'PRODUCT_BUNDLE_IDENTIFIER = com.ex3ndr.happy;\n', 'utf-8');
+    await writeFile(join(iosDir, 'Happy', 'Info.plist'), '<key>CFBundleDisplayName</key><string>Happy</string>\n', 'utf-8');
+
+    await mkdir(join(iosDir, 'Happydev.xcodeproj'), { recursive: true });
+    await mkdir(join(iosDir, 'Happydev'), { recursive: true });
+    await writeFile(join(iosDir, 'Happydev.xcodeproj', 'project.pbxproj'), 'PRODUCT_BUNDLE_IDENTIFIER = com.slopus.happy.dev;\n', 'utf-8');
+    await writeFile(join(iosDir, 'Happydev', 'Info.plist'), '<key>CFBundleDisplayName</key><string>Happy (dev)</string>\n', 'utf-8');
+
+    await patchIosXcodeProjectsForSigningAndIdentity({
+      uiDir,
+      iosBundleId: 'com.happystacks.stack.user.pre-pr272',
+      iosAppName: 'HAPPY LEGACY',
+    });
+
+    const pbxprojRelease = await readFile(join(iosDir, 'Happy.xcodeproj', 'project.pbxproj'), 'utf-8');
+    assert.match(pbxprojRelease, /PRODUCT_BUNDLE_IDENTIFIER = com\.happystacks\.stack\.user\.pre-pr272;/);
+
+    const pbxprojDev = await readFile(join(iosDir, 'Happydev.xcodeproj', 'project.pbxproj'), 'utf-8');
+    assert.match(pbxprojDev, /PRODUCT_BUNDLE_IDENTIFIER = com\.happystacks\.stack\.user\.pre-pr272;/);
+  } finally {
+    await rm(uiDir, { recursive: true, force: true });
+  }
+});

package/scripts/utils/net/dns.mjs

@@ -0,0 +1,10 @@
+export function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
+  const s = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  return s || fallback;
+}
+

package/scripts/utils/net/lan_ip.mjs

@@ -0,0 +1,24 @@
+import { networkInterfaces } from 'node:os';
+
+export function pickLanIpv4() {
+  try {
+    const ifaces = networkInterfaces();
+    // Prefer en0 (typical Wi-Fi on macOS), then any non-internal IPv4.
+    const preferred = ['en0', 'en1', 'eth0', 'wlan0'];
+    for (const name of preferred) {
+      const list = ifaces[name] ?? [];
+      for (const i of list) {
+        if (i && i.family === 'IPv4' && !i.internal && i.address) return i.address;
+      }
+    }
+    for (const list of Object.values(ifaces)) {
+      for (const i of list ?? []) {
+        if (i && i.family === 'IPv4' && !i.internal && i.address) return i.address;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return '';
+}
+

package/scripts/utils/{ports.mjs → net/ports.mjs}

@@ -1,18 +1,23 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import net from 'node:net';
-import { runCapture } from './proc.mjs';
+import { runCaptureIfCommandExists } from '../proc/commands.mjs';
 
-async function listListenPids(port) {
+export async function listListenPids(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`,
-    ]);
+    raw = await runCaptureIfCommandExists('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
+    if (!raw && process.platform === 'darwin') {
+      // Some non-interactive shells (launchd/GUI apps) have a PATH that omits /usr/sbin,
+      // which makes `command -v lsof` fail even though lsof exists. Fall back to absolute paths.
+      raw =
+        (await runCaptureIfCommandExists('/usr/sbin/lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'])) ||
+        (await runCaptureIfCommandExists('/usr/bin/lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'])) ||
+        '';
+    }
   } catch {
     raw = '';
   }
@@ -102,3 +107,4 @@ export async function pickNextFreeTcpPort(startPort, { reservedPorts = new Set()
   }
   throw new Error(`[local] unable to find a free TCP port starting at ${startPort}`);
 }
+

package/scripts/utils/net/url.mjs

@@ -0,0 +1,30 @@
+export function normalizeUrlNoTrailingSlash(raw) {
+  const s = String(raw ?? '').trim();
+  if (!s) return '';
+
+  let u;
+  try {
+    u = new URL(s);
+  } catch {
+    // Best-effort: if it's a plain string with trailing slash, trim it.
+    return s.endsWith('/') ? s.replace(/\/+$/, '') : s;
+  }
+
+  // Only normalize "base" URLs without search/hash.
+  // If search/hash is present, removing slashes can change semantics.
+  if (u.search || u.hash) {
+    return u.toString();
+  }
+
+  // Normalize multiple trailing slashes down to none (root) or one-less (non-root).
+  const path = u.pathname || '/';
+  if (path === '/' || path === '') {
+    return u.origin;
+  }
+  if (path.endsWith('/')) {
+    const nextPath = path.replace(/\/+$/, '');
+    return `${u.origin}${nextPath}`;
+  }
+  return u.toString();
+}
+

package/scripts/utils/net/url.test.mjs

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { normalizeUrlNoTrailingSlash } from './url.mjs';
+
+test('normalizeUrlNoTrailingSlash removes trailing slash from origins', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/'), 'https://example.com');
+  assert.equal(normalizeUrlNoTrailingSlash('http://localhost:3005/'), 'http://localhost:3005');
+});
+
+test('normalizeUrlNoTrailingSlash removes trailing slash from path-only base URLs', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/api/'), 'https://example.com/api');
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/api///'), 'https://example.com/api');
+});
+
+test('normalizeUrlNoTrailingSlash preserves query/hash URLs', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/?q=1'), 'https://example.com/?q=1');
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/api/?q=1'), 'https://example.com/api/?q=1');
+});
+

package/scripts/utils/paths/localhost_host.mjs

@@ -0,0 +1,56 @@
+import { getStackName } from './paths.mjs';
+import { sanitizeDnsLabel } from '../net/dns.mjs';
+
+export function resolveLocalhostHost({ stackMode, stackName = null, env = process.env } = {}) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  if (!stackMode) return 'localhost';
+  if (!name || name === 'main') return 'localhost';
+  return `happy-${sanitizeDnsLabel(name)}.localhost`;
+}
+
+export async function preferStackLocalhostHost({ stackName = null, env = process.env } = {}) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  if (!name || name === 'main') return 'localhost';
+  // IMPORTANT:
+  // We intentionally do NOT gate on `dns.lookup()` here.
+  //
+  // On some systems (notably macOS), Node's DNS resolver may return ENOTFOUND for `*.localhost`
+  // even though browsers treat `*.localhost` as loopback and will load it fine.
+  //
+  // Since this hostname is primarily used for browser-facing URLs and origin isolation, we
+  // prefer the stable `happy-<stack>.localhost` form by default and allow opting out via env.
+  const modeRaw = (env.HAPPY_STACKS_LOCALHOST_SUBDOMAINS ?? env.HAPPY_LOCAL_LOCALHOST_SUBDOMAINS ?? '')
+    .toString()
+    .trim()
+    .toLowerCase();
+  const disabled = modeRaw === '0' || modeRaw === 'false' || modeRaw === 'no' || modeRaw === 'off';
+  if (disabled) return 'localhost';
+
+  const preferredHost = resolveLocalhostHost({ stackMode: true, stackName: name, env });
+  return preferredHost || 'localhost';
+}
+
+// Best-effort: for stacks, prefer `happy-<stack>.localhost` over `localhost` when it's reachable.
+// This keeps URLs stable and stack-scoped while still failing closed to plain localhost.
+export async function preferStackLocalhostUrl(url, { stackName = null, env = process.env } = {}) {
+  const raw = String(url ?? '').trim();
+  if (!raw) return '';
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  if (!name || name === 'main') return raw;
+
+  let u = null;
+  try {
+    u = new URL(raw);
+  } catch {
+    return raw;
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return raw;
+
+  const isLoopbackHost = u.hostname === 'localhost' || u.hostname === '127.0.0.1';
+  if (!isLoopbackHost) return raw;
+
+  const preferredHost = await preferStackLocalhostHost({ stackName: name, env });
+  if (!preferredHost || preferredHost === 'localhost') return raw;
+  return raw.replace(`://${u.hostname}`, `://${preferredHost}`);
+}
+

package/scripts/utils/{paths.mjs → paths/paths.mjs}

@@ -2,7 +2,9 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
+
+import { expandHome } from './canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from '../env/sandbox.mjs';
 
 const PRIMARY_APP_SLUG = 'happy-stacks';
 const LEGACY_APP_SLUG = 'happy-local';
@@ -16,18 +18,18 @@ export function getRootDir(importMetaUrl) {
   return dirname(dirname(fileURLToPath(importMetaUrl)));
 }
 
-export function getHappyStacksHomeDir() {
-  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
+export function getHappyStacksHomeDir(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   return PRIMARY_HOME_DIR;
 }
 
-export function getWorkspaceDir(cliRootDir = null) {
-  const fromEnv = (process.env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
+export function getWorkspaceDir(cliRootDir = null, env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   const homeDir = getHappyStacksHomeDir();
   const defaultWorkspace = join(homeDir, 'workspace');
@@ -39,8 +41,8 @@ export function getWorkspaceDir(cliRootDir = null) {
   return cliRootDir ? cliRootDir : defaultWorkspace;
 }
 
-export function getComponentsDir(rootDir) {
-  const workspaceDir = getWorkspaceDir(rootDir);
+export function getComponentsDir(rootDir, env = process.env) {
+  const workspaceDir = getWorkspaceDir(rootDir, env);
   return join(workspaceDir, 'components');
 }
 
@@ -48,48 +50,50 @@ export function componentDirEnvKey(name) {
   return `HAPPY_STACKS_COMPONENT_DIR_${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
 }
 
-function normalizePathForEnv(rootDir, raw) {
+function normalizePathForEnv(rootDir, raw, env = process.env) {
   const trimmed = (raw ?? '').trim();
   if (!trimmed) {
     return '';
   }
-  const expanded = trimmed.replace(/^~(?=\/)/, homedir());
+  const expanded = expandHome(trimmed);
   // If the path is relative, treat it as relative to the workspace root (default: repo root).
-  const workspaceDir = getWorkspaceDir(rootDir);
+  const workspaceDir = getWorkspaceDir(rootDir, env);
   return expanded.startsWith('/') ? expanded : resolve(workspaceDir, expanded);
 }
 
-export function getComponentDir(rootDir, name) {
+export function getComponentDir(rootDir, name, env = process.env) {
   const stacksKey = componentDirEnvKey(name);
   const legacyKey = stacksKey.replace(/^HAPPY_STACKS_/, 'HAPPY_LOCAL_');
-  const fromEnv = normalizePathForEnv(rootDir, process.env[stacksKey] ?? process.env[legacyKey]);
+  const fromEnv = normalizePathForEnv(rootDir, env[stacksKey] ?? env[legacyKey], env);
   if (fromEnv) {
     return fromEnv;
   }
-  return join(getComponentsDir(rootDir), name);
+  return join(getComponentsDir(rootDir, env), 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()
+export function getStackName(env = process.env) {
+  const raw = env.HAPPY_STACKS_STACK?.trim()
+    ? env.HAPPY_STACKS_STACK.trim()
+    : env.HAPPY_LOCAL_STACK?.trim()
+      ? 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 getStackLabel(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  return name === 'main' ? PRIMARY_LABEL_BASE : `${PRIMARY_LABEL_BASE}.${name}`;
 }
 
-export function getLegacyStackLabel(stackName = getStackName()) {
-  return stackName === 'main' ? LEGACY_LABEL_BASE : `${LEGACY_LABEL_BASE}.${stackName}`;
+export function getLegacyStackLabel(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  return name === 'main' ? LEGACY_LABEL_BASE : `${LEGACY_LABEL_BASE}.${name}`;
 }
 
-export function getStacksStorageRoot() {
-  const fromEnv = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
+export function getStacksStorageRoot(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_STORAGE_DIR ?? env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   return PRIMARY_STORAGE_ROOT;
 }
@@ -98,19 +102,20 @@ 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);
+export function resolveStackBaseDir(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  const preferredRoot = getStacksStorageRoot(env);
+  const newBase = join(preferredRoot, name);
+  const legacyBase = name === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', name);
   const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   // 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 (allowLegacy && stackName !== 'main') {
-    const newEnv = join(preferredRoot, stackName, 'env');
-    const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  if (allowLegacy && name !== 'main') {
+    const newEnv = join(preferredRoot, name, 'env');
+    const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', name, 'env');
     if (!existsSync(newEnv) && existsSync(legacyEnv)) {
       return { baseDir: legacyBase, isLegacy: true };
     }
@@ -119,30 +124,31 @@ export function resolveStackBaseDir(stackName = getStackName()) {
   return { baseDir: newBase, isLegacy: false };
 }
 
-export function resolveStackEnvPath(stackName = getStackName()) {
-  const { baseDir: activeBase, isLegacy } = resolveStackBaseDir(stackName);
+export function resolveStackEnvPath(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  const { baseDir: activeBase, isLegacy } = resolveStackBaseDir(name, env);
   // New layout: ~/.happy/stacks/<name>/env
-  const newEnv = join(getStacksStorageRoot(), stackName, 'env');
+  const newEnv = join(getStacksStorageRoot(env), name, 'env');
   // Legacy layout: ~/.happy/local/stacks/<name>/env
-  const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', name, 'env');
   const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   if (existsSync(newEnv)) {
-    return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(), stackName) };
+    return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(env), name) };
   }
   if (allowLegacy && existsSync(legacyEnv)) {
-    return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', stackName) };
+    return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', name) };
   }
   return { envPath: newEnv, isLegacy, baseDir: activeBase };
 }
 
-export function getDefaultAutostartPaths() {
-  const stackName = getStackName();
-  const { baseDir, isLegacy } = resolveStackBaseDir(stackName);
+export function getDefaultAutostartPaths(env = process.env) {
+  const stackName = getStackName(env);
+  const { baseDir, isLegacy } = resolveStackBaseDir(stackName, env);
   const logsDir = join(baseDir, 'logs');
 
-  const primaryLabel = getStackLabel(stackName);
-  const legacyLabel = getLegacyStackLabel(stackName);
+  const primaryLabel = getStackLabel(stackName, env);
+  const legacyLabel = getLegacyStackLabel(stackName, env);
   const primaryPlistPath = join(homedir(), 'Library', 'LaunchAgents', `${primaryLabel}.plist`);
   const legacyPlistPath = join(homedir(), 'Library', 'LaunchAgents', `${legacyLabel}.plist`);
 
@@ -185,3 +191,4 @@ export function getDefaultAutostartPaths() {
     legacyStderrPath,
   };
 }
+

package/scripts/utils/{runtime.mjs → paths/runtime.mjs}

@@ -9,7 +9,9 @@ export function getRuntimeDir() {
   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');
+  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');
 }
 

package/scripts/utils/proc/commands.mjs

@@ -0,0 +1,34 @@
+import { runCapture } from './proc.mjs';
+
+export async function resolveCommandPath(cmd, { cwd, env, timeoutMs } = {}) {
+  const c = String(cmd ?? '').trim();
+  if (!c) return '';
+
+  try {
+    if (process.platform === 'win32') {
+      const out = (await runCapture('where', [c], { cwd, env, timeoutMs })).trim();
+      const first = out.split(/\r?\n/).map((s) => s.trim()).find(Boolean) || '';
+      return first;
+    }
+    return (
+      await runCapture('sh', ['-lc', `command -v "${c}" 2>/dev/null || true`], { cwd, env, timeoutMs })
+    ).trim();
+  } catch {
+    return '';
+  }
+}
+
+export async function runCaptureIfCommandExists(cmd, args, { cwd, env, timeoutMs } = {}) {
+  const resolved = await resolveCommandPath(cmd, { cwd, env, timeoutMs });
+  if (!resolved) return '';
+  try {
+    return await runCapture(resolved, args, { cwd, env, timeoutMs });
+  } catch {
+    return '';
+  }
+}
+
+export async function commandExists(cmd, { cwd } = {}) {
+  return Boolean(await resolveCommandPath(cmd, { cwd }));
+}
+

package/scripts/utils/{ownership.mjs → proc/ownership.mjs}

@@ -1,5 +1,5 @@
 import { runCapture } from './proc.mjs';
-import { killPid } from './expo.mjs';
+import { killPid } from '../expo/expo.mjs';
 
 export async function getPsEnvLine(pid) {
   const n = Number(pid);