happy-stacks 0.2.0 → 0.3.0

package/scripts/mobile.mjs

@@ -1,12 +1,13 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { pickNextFreeTcpPort } from './utils/ports.mjs';
-import { run, runCapture, spawnProc } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/pm.mjs';
+import { pickNextFreeTcpPort } from './utils/net/ports.mjs';
+import { run, runCapture, spawnProc } from './utils/proc/proc.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/proc/pm.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo.mjs';
-import { killProcessGroupOwnedByStack } from './utils/ownership.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo/expo.mjs';
+import { killProcessGroupOwnedByStack } from './utils/proc/ownership.mjs';
+import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv } from './utils/server/urls.mjs';
 
 /**
  * Mobile dev helper for the embedded `components/happy` Expo app.
@@ -58,7 +59,7 @@ async function main() {
         '',
         'Notes:',
         '- This script is designed to avoid editing upstream `components/happy` config in-place.',
-        '- It sets EXPO_PUBLIC_HAPPY_SERVER_URL from HAPPY_STACKS_SERVER_URL (legacy: HAPPY_LOCAL_SERVER_URL) if provided.',
+        '- If you explicitly set HAPPY_STACKS_SERVER_URL (legacy: HAPPY_LOCAL_SERVER_URL), it bakes that URL into the app via EXPO_PUBLIC_HAPPY_SERVER_URL.',
       ].join('\n'),
     });
     return;
@@ -141,10 +142,10 @@ async function main() {
 
   // Allow happy-stacks to define the default server URL baked into the app bundle.
   // This is read by the app via `process.env.EXPO_PUBLIC_HAPPY_SERVER_URL`.
-  const stacksServerUrl =
-    process.env.HAPPY_STACKS_SERVER_URL?.trim() || process.env.HAPPY_LOCAL_SERVER_URL?.trim() || '';
-  if (stacksServerUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
-    env.EXPO_PUBLIC_HAPPY_SERVER_URL = stacksServerUrl;
+  const serverPort = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
+  const { envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort });
+  if (envPublicUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
+    env.EXPO_PUBLIC_HAPPY_SERVER_URL = envPublicUrl;
   }
 
   if (json) {

package/scripts/run.mjs

@@ -1,25 +1,25 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { killProcessTree, runCapture, spawnProc } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { killPortListeners } from './utils/ports.mjs';
-import { getServerComponentName, isHappyServerRunning, waitForServerReady } from './utils/server.mjs';
-import { ensureCliBuilt, ensureDepsInstalled, pmExecBin, pmSpawnScript, requireDir } from './utils/pm.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 { killPortListeners } from './utils/net/ports.mjs';
+import { getServerComponentName, isHappyServerRunning, waitForServerReady } from './utils/server/server.mjs';
+import { ensureCliBuilt, ensureDepsInstalled, pmExecBin, pmSpawnScript, requireDir } from './utils/proc/pm.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { maybeResetTailscaleServe } from './tailscale.mjs';
 import { isDaemonRunning, startLocalDaemonWithAuth, stopLocalDaemon } from './daemon.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/validate.mjs';
-import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/happy_server_infra.mjs';
-import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from './utils/stack_startup.mjs';
-import { recordStackRuntimeStart, recordStackRuntimeUpdate } from './utils/stack_runtime_state.mjs';
-import { resolveStackContext } from './utils/stack_context.mjs';
-import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv, resolveServerUrls } from './utils/server_urls.mjs';
-import { resolveLocalhostHost } from './utils/localhost_host.mjs';
-import { openUrlInBrowser } from './utils/browser.mjs';
+import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/server/validate.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
+import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from './utils/stack/startup.mjs';
+import { recordStackRuntimeStart, recordStackRuntimeUpdate } from './utils/stack/runtime_state.mjs';
+import { resolveStackContext } from './utils/stack/context.mjs';
+import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
+import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { openUrlInBrowser } from './utils/ui/browser.mjs';
 
 /**
  * Run the local stack in "production-like" mode:

package/scripts/self.mjs

@@ -1,16 +1,18 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { parseArgs } from './utils/cli/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { readJsonIfExists } from './utils/fs/json.mjs';
+import { readPackageJsonVersion } from './utils/fs/package_json.mjs';
 
 function cachePaths() {
   const home = getHappyStacksHomeDir();
@@ -21,15 +23,6 @@ function cachePaths() {
   };
 }
 
-async function readJsonSafe(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
 async function writeJsonSafe(path, obj) {
   try {
     await mkdir(join(path, '..'), { recursive: true });
@@ -43,25 +36,14 @@ async function writeJsonSafe(path, obj) {
   }
 }
 
-async function readPkgVersion(pkgJsonPath) {
-  try {
-    const raw = await readFile(pkgJsonPath, 'utf-8');
-    const pkg = JSON.parse(raw);
-    const v = String(pkg.version ?? '').trim();
-    return v || null;
-  } catch {
-    return null;
-  }
-}
-
 async function getRuntimeInstalledVersion() {
   const runtimeDir = getRuntimeDir();
   const pkgJson = join(runtimeDir, 'node_modules', 'happy-stacks', 'package.json');
-  return await readPkgVersion(pkgJson);
+  return await readPackageJsonVersion(pkgJson);
 }
 
 async function getInvokerVersion({ rootDir }) {
-  return await readPkgVersion(join(rootDir, 'package.json'));
+  return await readPackageJsonVersion(join(rootDir, 'package.json'));
 }
 
 async function fetchLatestVersion() {
@@ -102,7 +84,7 @@ async function cmdStatus({ rootDir, argv }) {
   const runtimeDir = getRuntimeDir();
   const runtimeVersion = await getRuntimeInstalledVersion();
 
-  const cached = await readJsonSafe(updateJson);
+  const cached = await readJsonIfExists(updateJson, { defaultValue: null });
 
   let latest = cached?.latest ?? null;
   let checkedAt = cached?.checkedAt ?? null;

package/scripts/server_flavor.mjs

@@ -1,8 +1,8 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { getRootDir } from './utils/paths.mjs';
-import { ensureEnvFileUpdated } from './utils/env_file.mjs';
-import { resolveUserConfigEnvPath } from './utils/config.mjs';
+import { getRootDir } from './utils/paths/paths.mjs';
+import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { resolveUserConfigEnvPath } from './utils/env/config.mjs';
 import { isTty, promptSelect, withRl } from './utils/cli/wizard.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 

package/scripts/service.mjs

@@ -1,9 +1,10 @@
-import './utils/env.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { getDefaultAutostartPaths, getRootDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { ensureMacAutostartDisabled, ensureMacAutostartEnabled } from './utils/pm.mjs';
-import { getCanonicalHomeDir } from './utils/config.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import './utils/env/env.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { getDefaultAutostartPaths, getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { getInternalServerUrl, getPublicServerUrlEnvOverride } from './utils/server/urls.mjs';
+import { ensureMacAutostartDisabled, ensureMacAutostartEnabled } from './utils/service/autostart_darwin.mjs';
+import { getCanonicalHomeDir } from './utils/env/config.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { existsSync } from 'node:fs';
@@ -12,6 +13,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readLastLines } from './utils/fs/tail.mjs';
 
 /**
  * Manage the autostart service installed by `happys bootstrap -- --autostart`.
@@ -35,11 +37,6 @@ function getUid() {
   return Number.isFinite(n) ? n : null;
 }
 
-function getInternalUrl() {
-  const port = process.env.HAPPY_LOCAL_SERVER_PORT?.trim() ? Number(process.env.HAPPY_LOCAL_SERVER_PORT) : 3005;
-  return `http://127.0.0.1:${port}`;
-}
-
 function getAutostartEnv({ rootDir }) {
   // IMPORTANT:
   // LaunchAgents should NOT bake the entire config into the plist, because that would require
@@ -267,16 +264,19 @@ async function startLaunchAgent({ persistent }) {
 
 async function postStartDiagnostics() {
   const rootDir = getRootDir(import.meta.url);
-  const internalUrl = getInternalUrl();
+  const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
 
   const cliHomeDir = process.env.HAPPY_LOCAL_CLI_HOME_DIR?.trim()
     ? process.env.HAPPY_LOCAL_CLI_HOME_DIR.trim().replace(/^~(?=\/)/, homedir())
     : join(getDefaultAutostartPaths().baseDir, 'cli');
 
-  const publicUrl =
-    process.env.HAPPY_LOCAL_SERVER_URL?.trim()
-      ? process.env.HAPPY_LOCAL_SERVER_URL.trim()
-      : internalUrl.replace('127.0.0.1', 'localhost');
+  let port = 3005;
+  try {
+    port = Number(new URL(internalUrl).port || 0) || 3005;
+  } catch {
+    port = 3005;
+  }
+  const { publicServerUrl: publicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port });
 
   const cliDir = join(rootDir, 'components', 'happy-cli');
   const cliBin = join(cliDir, 'bin', 'happy.mjs');
@@ -286,16 +286,6 @@ async function postStartDiagnostics() {
   const lockFile = join(cliHomeDir, 'daemon.state.json.lock');
   const logsDir = join(cliHomeDir, 'logs');
 
-  const readLastLines = async (path, lines = 60) => {
-    try {
-      const raw = await readFile(path, 'utf-8');
-      const parts = raw.split('\n');
-      return parts.slice(Math.max(0, parts.length - lines)).join('\n');
-    } catch {
-      return null;
-    }
-  };
-
   const latestDaemonLog = async () => {
     try {
       const ls = await runCapture('bash', ['-lc', `ls -1t "${logsDir}"/*-daemon.log 2>/dev/null | head -1 || true`]);
@@ -461,7 +451,7 @@ async function waitForLaunchAgentStopped({ timeoutMs = 8000 } = {}) {
 
 async function showStatus() {
   const { plistPath, stdoutPath, stderrPath, label } = getDefaultAutostartPaths();
-  const internalUrl = getInternalUrl();
+  const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
 
   console.log(`label: ${label}`);
   console.log(`plist: ${plistPath} ${existsSync(plistPath) ? '(present)' : '(missing)'}`);
@@ -550,7 +540,7 @@ async function main() {
       return;
     case 'status':
       if (json) {
-        const internalUrl = getInternalUrl();
+        const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
         let health = null;
         try {
           const res = await fetch(`${internalUrl}/health`, { method: 'GET' });

package/scripts/setup.mjs

@@ -1,137 +1,41 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getRootDir, resolveStackEnvPath } from './utils/paths.mjs';
+import { getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
 import { isTty, promptSelect, withRl } from './utils/cli/wizard.mjs';
-import { getCanonicalHomeDir } from './utils/config.mjs';
-import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { fetchHappyHealth } from './utils/server.mjs';
+import { getCanonicalHomeDir } from './utils/env/config.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { waitForHappyHealthOk } from './utils/server/server.mjs';
 import { tailscaleServeEnable, tailscaleServeHttpsUrlForInternalServerUrl } from './tailscale.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { parseDotenv } from './utils/dotenv.mjs';
 import { installService } from './service.mjs';
-import { getDevAuthKeyPath } from './utils/dev_auth_key.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
-
-function boolFromFlagsOrKv({ flags, kv, onFlag, offFlag, key, defaultValue }) {
-  if (flags.has(offFlag)) return false;
-  if (flags.has(onFlag)) return true;
-  if (key && kv.has(key)) {
-    const raw = String(kv.get(key) ?? '').trim().toLowerCase();
-    if (raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y') return true;
-    if (raw === '0' || raw === 'false' || raw === 'no' || raw === 'n') return false;
-  }
-  return defaultValue;
-}
-
-function normalizeProfile(raw) {
-  const v = (raw ?? '').trim().toLowerCase();
-  if (!v) return '';
-  if (v === 'selfhost' || v === 'self-host' || v === 'self_host' || v === 'host') return 'selfhost';
-  if (v === 'dev' || v === 'developer' || v === 'develop') return 'dev';
-  return '';
-}
-
-function normalizeServer(raw) {
-  const v = (raw ?? '').trim().toLowerCase();
-  if (!v) return '';
-  if (v === 'light' || v === 'server-light' || v === 'happy-server-light') return 'happy-server-light';
-  if (v === 'server' || v === 'full' || v === 'happy-server') return 'happy-server';
-  return '';
-}
-
-function boolFromFlags({ flags, onFlag, offFlag, defaultValue }) {
-  if (flags.has(offFlag)) return false;
-  if (flags.has(onFlag)) return true;
-  return defaultValue;
-}
-
-async function commandExists(cmd) {
-  try {
-    const out = (await runCapture('sh', ['-lc', `command -v ${cmd} >/dev/null 2>&1 && echo yes || echo no`])).trim();
-    return out === 'yes';
-  } catch {
-    return false;
-  }
-}
-
-async function openUrl(url) {
-  const u = String(url ?? '').trim();
-  if (!u) return false;
-  if (process.platform === 'darwin') {
-    await run('open', [u]).catch(() => {});
-    return true;
-  }
-  if (process.platform === 'linux') {
-    if (await commandExists('xdg-open')) {
-      await run('xdg-open', [u]).catch(() => {});
-      return true;
-    }
-    return false;
-  }
-  return false;
-}
-
-async function waitForHealthOk(internalServerUrl, { timeoutMs = 60_000 } = {}) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    // eslint-disable-next-line no-await-in-loop
-    const health = await fetchHappyHealth(internalServerUrl);
-    if (health.ok) {
-      return true;
-    }
-    // eslint-disable-next-line no-await-in-loop
-    await new Promise((r) => setTimeout(r, 300));
-  }
-  return false;
-}
-
-function parseEnvFileText(text) {
-  try {
-    return parseDotenv(text ?? '');
-  } catch {
-    return new Map();
-  }
-}
-
-async function readEnvValueFromFile(envPath, key) {
-  try {
-    if (!envPath || !existsSync(envPath)) return '';
-    const raw = await readFile(envPath, 'utf-8');
-    const parsed = parseEnvFileText(raw);
-    return (parsed.get(key) ?? '').trim();
-  } catch {
-    return '';
-  }
-}
+import { getDevAuthKeyPath } from './utils/auth/dev_key.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { boolFromFlags, boolFromFlagsOrKv } from './utils/cli/flags.mjs';
+import { normalizeProfile, normalizeServerComponent } from './utils/cli/normalize.mjs';
+import { openUrlInBrowser } from './utils/ui/browser.mjs';
+import { commandExists } from './utils/proc/commands.mjs';
+import { readEnvValueFromFile } from './utils/env/read.mjs';
+import { readServerPortFromEnvFile, resolveServerPortFromEnv } from './utils/server/port.mjs';
 
 async function resolveMainServerPort() {
   // Priority:
   // - explicit env var
   // - main stack env file (preferred)
   // - default
-  const fromEnv =
-    (process.env.HAPPY_LOCAL_SERVER_PORT ?? process.env.HAPPY_STACKS_SERVER_PORT ?? '').toString().trim();
-  if (fromEnv) {
-    const n = Number(fromEnv);
-    return Number.isFinite(n) && n > 0 ? n : 3005;
+  const hasEnvOverride =
+    (process.env.HAPPY_STACKS_SERVER_PORT ?? process.env.HAPPY_LOCAL_SERVER_PORT ?? '').toString().trim() !== '';
+  if (hasEnvOverride) {
+    return resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
   }
   const envPath = resolveStackEnvPath('main').envPath;
-  const v =
-    (await readEnvValueFromFile(envPath, 'HAPPY_LOCAL_SERVER_PORT')) ||
-    (await readEnvValueFromFile(envPath, 'HAPPY_STACKS_SERVER_PORT')) ||
-    '';
-  if (v) {
-    const n = Number(v);
-    return Number.isFinite(n) && n > 0 ? n : 3005;
-  }
-  return 3005;
+  return await readServerPortFromEnvFile(envPath, { defaultPort: 3005 });
 }
 
 async function ensureSetupConfigPersisted({ rootDir, profile, serverComponent, tailscaleWanted, menubarMode }) {
@@ -393,8 +297,8 @@ async function cmdSetup({ rootDir, argv }) {
   const supportsAutostart = platform === 'darwin' || platform === 'linux';
   const supportsMenubar = platform === 'darwin';
 
-  const serverFromArg = normalizeServer(kv.get('--server'));
-  let serverComponent = serverFromArg || normalizeServer(process.env.HAPPY_STACKS_SERVER_COMPONENT) || 'happy-server-light';
+  const serverFromArg = normalizeServerComponent(kv.get('--server'));
+  let serverComponent = serverFromArg || normalizeServerComponent(process.env.HAPPY_STACKS_SERVER_COMPONENT) || 'happy-server-light';
   if (profile === 'selfhost' && interactive && !serverFromArg) {
     serverComponent = await withRl(async (rl) => {
       const picked = await promptSelect(rl, {
@@ -645,12 +549,12 @@ async function cmdSetup({ rootDir, argv }) {
         // eslint-disable-next-line no-console
         console.log(res.enableUrl);
         // Best-effort open
-        await openUrl(res.enableUrl);
+        await openUrlInBrowser(res.enableUrl).catch(() => {});
       }
     } catch (e) {
       // eslint-disable-next-line no-console
       console.log('[setup] tailscale not available. Install it from: https://tailscale.com/download');
-      await openUrl('https://tailscale.com/download');
+      await openUrlInBrowser('https://tailscale.com/download').catch(() => {});
     }
   }
 
@@ -664,7 +568,7 @@ async function cmdSetup({ rootDir, argv }) {
       await spawnDetachedNodeScript({ rootDir, rel: 'scripts/run.mjs', args: [] });
     }
 
-    const ready = await waitForHealthOk(internalServerUrl, { timeoutMs: 90_000 });
+    const ready = await waitForHappyHealthOk(internalServerUrl, { timeoutMs: 90_000 });
     if (!ready) {
       // eslint-disable-next-line no-console
       console.log(`[setup] started, but server did not become healthy yet: ${internalServerUrl}`);
@@ -742,7 +646,7 @@ async function cmdSetup({ rootDir, argv }) {
       console.log('[setup] tip: when you are ready, authenticate with: happys auth login');
     }
 
-    await openUrl(openTarget);
+    await openUrlInBrowser(openTarget).catch(() => {});
     // eslint-disable-next-line no-console
     console.log(`[setup] open: ${openTarget}`);
   }

package/scripts/setup_pr.mjs

@@ -1,43 +1,26 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getRootDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { run } from './utils/proc.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { parseGithubPullRequest } from './utils/git/refs.mjs';
+import { sanitizeStackName } from './utils/stack/names.mjs';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-function sanitizeStackName(raw) {
-  const s = String(raw ?? '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '');
-  return s || 'pr';
-}
-
-function parseGithubPullRequestNumber(input) {
-  const raw = String(input ?? '').trim();
-  if (!raw) return null;
-  if (/^\d+$/.test(raw)) return Number(raw);
-  const m = raw.match(/github\.com\/[^/]+\/[^/]+\/pull\/(?<num>\d+)/);
-  return m?.groups?.num ? Number(m.groups.num) : null;
-}
-
 function inferStackNameFromPrArgs({ happy, happyCli, server, serverLight }) {
   const parts = [];
-  const hn = parseGithubPullRequestNumber(happy);
-  const cn = parseGithubPullRequestNumber(happyCli);
-  const sn = parseGithubPullRequestNumber(server);
-  const sln = parseGithubPullRequestNumber(serverLight);
+  const hn = parseGithubPullRequest(happy)?.number ?? null;
+  const cn = parseGithubPullRequest(happyCli)?.number ?? null;
+  const sn = parseGithubPullRequest(server)?.number ?? null;
+  const sln = parseGithubPullRequest(serverLight)?.number ?? null;
   if (hn) parts.push(`happy${hn}`);
   if (cn) parts.push(`cli${cn}`);
   if (sn) parts.push(`server${sn}`);
   if (sln) parts.push(`light${sln}`);
-  return sanitizeStackName(parts.length ? `pr-${parts.join('-')}` : 'pr');
+  return sanitizeStackName(parts.length ? `pr-${parts.join('-')}` : 'pr', { fallback: 'pr', maxLen: 64 });
 }
 
 function detectBestAuthSource() {