happy-stacks 0.3.0 → 0.4.0

package/scripts/utils/handy_master_secret.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { parseDotenv } from './env/dotenv.mjs';
+import { resolveStackEnvPath } from './paths/paths.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './auth_sources.mjs';
+
+async function readTextIfExists(path) {
+  try {
+    if (!path || !existsSync(path)) return null;
+    const raw = await readFile(path, 'utf-8');
+    const t = raw.trim();
+    return t ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseEnvToObject(raw) {
+  const parsed = parseDotenv(raw ?? '');
+  return Object.fromEntries(parsed.entries());
+}
+
+function getEnvValue(env, key) {
+  const v = (env?.[key] ?? '').toString().trim();
+  return v || '';
+}
+
+function stackExistsSync(stackName) {
+  if (stackName === 'main') return true;
+  const envPath = resolveStackEnvPath(stackName).envPath;
+  return existsSync(envPath);
+}
+
+export async function resolveHandyMasterSecretFromStack({
+  stackName,
+  requireStackExists = false,
+  allowLegacyAuthSource = true,
+  allowLegacyMainFallback = true,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+
+  if (isLegacyAuthSourceName(name)) {
+    if (!allowLegacyAuthSource) {
+      throw new Error(
+        '[auth] legacy auth source is disabled in sandbox mode.\n' +
+          'Reason: it reads from ~/.happy (global user state).\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
+    const baseDir = getLegacyHappyBaseDir();
+    const legacySecretPath = join(baseDir, 'server-light', 'handy-master-secret.txt');
+    const secret = await readTextIfExists(legacySecretPath);
+    return secret ? { secret, source: legacySecretPath } : { secret: null, source: null };
+  }
+
+  if (requireStackExists && !stackExistsSync(name)) {
+    throw new Error(`[auth] cannot copy auth: source stack "${name}" does not exist`);
+  }
+
+  const resolved = resolveStackEnvPath(name);
+  const sourceBaseDir = resolved.baseDir;
+  const sourceEnvPath = resolved.envPath;
+  const raw = await readTextIfExists(sourceEnvPath);
+  const env = raw ? parseEnvToObject(raw) : {};
+
+  const inline = getEnvValue(env, 'HANDY_MASTER_SECRET');
+  if (inline) {
+    return { secret: inline, source: `${sourceEnvPath} (HANDY_MASTER_SECRET)` };
+  }
+
+  const secretFile = getEnvValue(env, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE');
+  if (secretFile) {
+    const secret = await readTextIfExists(secretFile);
+    if (secret) return { secret, source: secretFile };
+  }
+
+  const dataDir = getEnvValue(env, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(sourceBaseDir, 'server-light');
+  const secretPath = join(dataDir, 'handy-master-secret.txt');
+  const secret = await readTextIfExists(secretPath);
+  if (secret) return { secret, source: secretPath };
+
+  // Last-resort legacy: if main has never been migrated to stack dirs.
+  if (name === 'main' && allowLegacyMainFallback) {
+    const legacy = join(homedir(), '.happy', 'server-light', 'handy-master-secret.txt');
+    const legacySecret = await readTextIfExists(legacy);
+    if (legacySecret) return { secret: legacySecret, source: legacy };
+  }
+
+  return { secret: null, source: null };
+}
+

package/scripts/utils/mobile/config.mjs

@@ -0,0 +1,31 @@
+import { sanitizeBundleIdSegment, sanitizeUrlScheme } from './identifiers.mjs';
+
+export function resolveMobileExpoConfig({ env = process.env } = {}) {
+  const user = sanitizeBundleIdSegment(env.USER ?? env.USERNAME ?? 'user');
+  const defaultLocalBundleId = `com.happy.local.${user}.dev`;
+
+  const appEnv = env.APP_ENV ?? env.HAPPY_STACKS_APP_ENV ?? env.HAPPY_LOCAL_APP_ENV ?? 'development';
+  const iosAppName = (env.HAPPY_STACKS_IOS_APP_NAME ?? env.HAPPY_LOCAL_IOS_APP_NAME ?? '').toString();
+  const iosBundleId = (env.HAPPY_STACKS_IOS_BUNDLE_ID ?? env.HAPPY_LOCAL_IOS_BUNDLE_ID ?? defaultLocalBundleId).toString();
+  // Happy Stacks convention:
+  // - dev-client QR should open a dedicated "Happy Stacks Dev" app (not a per-stack release build)
+  // - so default to a stable happy-stacks-specific scheme unless explicitly overridden.
+  const scheme = sanitizeUrlScheme(
+    (env.HAPPY_STACKS_MOBILE_SCHEME ??
+      env.HAPPY_LOCAL_MOBILE_SCHEME ??
+      env.HAPPY_STACKS_DEV_CLIENT_SCHEME ??
+      env.HAPPY_LOCAL_DEV_CLIENT_SCHEME ??
+      'happystacks-dev')
+      .toString()
+  );
+  const host = (env.HAPPY_STACKS_MOBILE_HOST ?? env.HAPPY_LOCAL_MOBILE_HOST ?? 'lan').toString();
+
+  return {
+    appEnv,
+    iosAppName,
+    iosBundleId,
+    scheme,
+    host,
+  };
+}
+

package/scripts/utils/mobile/dev_client_links.mjs

@@ -0,0 +1,60 @@
+import { getEnvValueAny } from '../env/values.mjs';
+import { pickLanIpv4 } from '../net/lan_ip.mjs';
+import { resolveMobileExpoConfig } from './config.mjs';
+
+function normalizeHostMode(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (v === 'localhost' || v === 'local') return 'localhost';
+  if (v === 'lan' || v === 'ip') return 'lan';
+  if (v === 'tunnel') return 'tunnel';
+  return v || 'lan';
+}
+
+export function resolveMobileHostMode(env = process.env) {
+  // Prefer explicit host vars (so TUI/setup-pr match the same knobs Expo uses).
+  const raw =
+    getEnvValueAny(env, ['HAPPY_STACKS_MOBILE_HOST', 'HAPPY_LOCAL_MOBILE_HOST']) ||
+    resolveMobileExpoConfig({ env }).host ||
+    'lan';
+  return normalizeHostMode(raw);
+}
+
+export function resolveMobileScheme(env = process.env) {
+  return String(resolveMobileExpoConfig({ env }).scheme || '').trim();
+}
+
+export function resolveMetroUrlForMobile({ env = process.env, port }) {
+  const p = Number(port);
+  if (!Number.isFinite(p) || p <= 0) return '';
+
+  const mode = resolveMobileHostMode(env);
+  if (mode === 'localhost') {
+    return `http://localhost:${p}`;
+  }
+  if (mode === 'lan') {
+    const ip = pickLanIpv4();
+    return `http://${ip || 'localhost'}:${p}`;
+  }
+  // Tunnel URLs are controlled by Expo; we can't reliably derive them locally.
+  // Fall back to localhost so the URL is at least correct for the host machine.
+  return `http://localhost:${p}`;
+}
+
+export function resolveDevClientDeepLink({ scheme, metroUrl }) {
+  const s = String(scheme ?? '').trim();
+  const url = String(metroUrl ?? '').trim();
+  if (!url) return '';
+  if (!s) return url;
+  return `${s}://expo-development-client/?url=${encodeURIComponent(url)}`;
+}
+
+export function resolveMobileQrPayload({ env = process.env, port }) {
+  const metroUrl = resolveMetroUrlForMobile({ env, port });
+  const scheme = resolveMobileScheme(env);
+  const deepLink = resolveDevClientDeepLink({ scheme, metroUrl });
+  // Match Expo CLI / @expo/cli UrlCreator: QR encodes the dev-client deep link.
+  // Note: iOS Camera will still offer to open custom schemes when the app is installed.
+  const payload = deepLink || metroUrl;
+  return { scheme, metroUrl, deepLink, payload };
+}
+

package/scripts/utils/mobile/identifiers.mjs

@@ -0,0 +1,47 @@
+function sanitizeToken(raw, { allowDots = false } = {}) {
+  const s = (raw ?? '').toString().trim().toLowerCase();
+  const re = allowDots ? /[^a-z0-9.-]+/g : /[^a-z0-9-]+/g;
+  const out = s.replace(re, '-').replace(/^-+|-+$/g, '').replace(/-+/g, '-');
+  return out;
+}
+
+export function sanitizeBundleIdSegment(s) {
+  const seg = sanitizeToken(s, { allowDots: false });
+  if (!seg) return 'app';
+  // Bundle id segments should not start with a digit; prefix if needed.
+  return /^[a-z]/.test(seg) ? seg : `s${seg}`;
+}
+
+export function sanitizeUrlScheme(s) {
+  // iOS URL schemes must start with a letter and may contain letters/digits/+.-.
+  const raw = (s ?? '').toString().trim().toLowerCase();
+  const cleaned = raw.replace(/[^a-z0-9+.-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+  if (!cleaned) return 'happystacks-dev';
+  return /^[a-z]/.test(cleaned) ? cleaned : `h${cleaned}`;
+}
+
+export function stackSlugForMobileIds(stackName) {
+  const raw = (stackName ?? '').toString().trim();
+  return sanitizeBundleIdSegment(raw || 'stack');
+}
+
+export function defaultDevClientIdentity({ user = null } = {}) {
+  const u = sanitizeBundleIdSegment(user ?? 'user');
+  return {
+    iosAppName: 'Happy Stacks Dev',
+    iosBundleId: `com.happystacks.dev.${u}`,
+    scheme: 'happystacks-dev',
+  };
+}
+
+export function defaultStackReleaseIdentity({ stackName, user = null, appName = null } = {}) {
+  const slug = stackSlugForMobileIds(stackName);
+  const u = sanitizeBundleIdSegment(user ?? 'user');
+  const label = (appName ?? '').toString().trim();
+  return {
+    iosAppName: label || `Happy (${stackName})`,
+    iosBundleId: `com.happystacks.stack.${u}.${slug}`,
+    scheme: sanitizeUrlScheme(`happystacks-${slug}`),
+  };
+}
+

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

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  defaultDevClientIdentity,
+  defaultStackReleaseIdentity,
+  sanitizeBundleIdSegment,
+  sanitizeUrlScheme,
+  stackSlugForMobileIds,
+} from './identifiers.mjs';
+
+test('sanitizeBundleIdSegment produces a safe segment', () => {
+  assert.equal(sanitizeBundleIdSegment('  PR272-107  '), 'pr272-107');
+  assert.equal(sanitizeBundleIdSegment('---'), 'app');
+  assert.equal(sanitizeBundleIdSegment('123'), 's123');
+});
+
+test('sanitizeUrlScheme produces a safe scheme', () => {
+  assert.equal(sanitizeUrlScheme('HappyStacks-Dev'), 'happystacks-dev');
+  assert.equal(sanitizeUrlScheme('123bad'), 'h123bad');
+  assert.equal(sanitizeUrlScheme(''), 'happystacks-dev');
+});
+
+test('stackSlugForMobileIds derives a stable slug', () => {
+  assert.equal(stackSlugForMobileIds('pr272-107-fixes-2026-01-15'), 'pr272-107-fixes-2026-01-15');
+  assert.equal(stackSlugForMobileIds('  Weird Name  '), 'weird-name');
+});
+
+test('defaultDevClientIdentity is stable and safe', () => {
+  const id = defaultDevClientIdentity({ user: 'Leeroy' });
+  assert.equal(id.iosAppName, 'Happy Stacks Dev');
+  assert.equal(id.scheme, 'happystacks-dev');
+  assert.equal(id.iosBundleId, 'com.happystacks.dev.leeroy');
+});
+
+test('defaultStackReleaseIdentity is per-stack', () => {
+  const id = defaultStackReleaseIdentity({ stackName: 'pr272-107', user: 'Leeroy' });
+  assert.equal(id.iosBundleId, 'com.happystacks.stack.leeroy.pr272-107');
+  assert.equal(id.scheme, 'happystacks-pr272-107');
+  assert.equal(id.iosAppName, 'Happy (pr272-107)');
+});
+

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/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/net/ports.mjs

@@ -2,7 +2,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import net from 'node:net';
 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 [];
 
@@ -10,6 +10,14 @@ async function listListenPids(port) {
   try {
     // `lsof` exits non-zero if no matches; normalize to empty output.
     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 = '';
   }

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

@@ -1,9 +1,56 @@
 import { getStackName } from './paths.mjs';
 import { sanitizeDnsLabel } from '../net/dns.mjs';
 
-export function resolveLocalhostHost({ stackMode, stackName = getStackName() } = {}) {
+export function resolveLocalhostHost({ stackMode, stackName = null, env = process.env } = {}) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
   if (!stackMode) return 'localhost';
-  if (!stackName || stackName === 'main') return 'localhost';
-  return `happy-${sanitizeDnsLabel(stackName)}.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}`);
 }