happy-stacks 0.2.0 → 0.3.0

package/scripts/typecheck.mjs

@@ -1,36 +1,15 @@
-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 { getComponentDir, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, requirePnpm } from './utils/pm.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run } from './utils/proc.mjs';
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { detectPackageManagerCmd, pickFirstScript, readPackageJsonScripts } from './utils/proc/package_scripts.mjs';
 
 const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
 
-async function detectPackageManagerCmd(dir) {
-  if (await pathExists(join(dir, 'yarn.lock'))) {
-    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
-  }
-  await requirePnpm();
-  return { name: 'pnpm', cmd: 'pnpm', argsForScript: (script) => ['--silent', script] };
-}
-
-async function readScripts(dir) {
-  try {
-    const raw = await readFile(join(dir, 'package.json'), 'utf-8');
-    const pkg = JSON.parse(raw);
-    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
-    return scripts;
-  } catch {
-    return null;
-  }
-}
-
 function pickTypecheckScript(scripts) {
-  if (!scripts) return null;
   const candidates = [
     'typecheck',
     'type-check',
@@ -39,7 +18,7 @@ function pickTypecheckScript(scripts) {
     'tsc',
     'typescript',
   ];
-  return candidates.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+  return pickFirstScript(scripts, candidates);
 }
 
 async function main() {
@@ -86,7 +65,7 @@ async function main() {
       continue;
     }
 
-    const scripts = await readScripts(dir);
+    const scripts = await readPackageJsonScripts(dir);
     if (!scripts) {
       results.push({ component, ok: true, skipped: true, dir, reason: 'no package.json' });
       continue;

package/scripts/ui_gateway.mjs

@@ -1,4 +1,4 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import http from 'node:http';
 import net from 'node:net';
 import { extname, resolve, sep } from 'node:path';

package/scripts/uninstall.mjs

@@ -1,4 +1,4 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
@@ -7,11 +7,11 @@ import { spawnSync } from 'node:child_process';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { getHappyStacksHomeDir, getRootDir, getStacksStorageRoot } from './utils/paths.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-import { getCanonicalHomeEnvPath } from './utils/config.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getHappyStacksHomeDir, getRootDir, getStacksStorageRoot } from './utils/paths/paths.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { getCanonicalHomeEnvPath } from './utils/env/config.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 function resolveWorkspaceDir({ rootDir, homeDir }) {
   // Uninstall should never default to deleting the repo root (getWorkspaceDir() can fall back to cliRootDir).

package/scripts/utils/{dev_auth_key.mjs → auth/dev_key.mjs}

@@ -1,17 +1,11 @@
 import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
-import { expandHome } from './canonical_home.mjs';
-
-export function resolveHappyStacksHomeDir(env = process.env) {
-  const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').toString().trim();
-  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happy-stacks');
-}
+import { getHappyStacksHomeDir } from '../paths/paths.mjs';
 
 export function getDevAuthKeyPath(env = process.env) {
-  return join(resolveHappyStacksHomeDir(env), 'keys', 'dev-auth.json');
+  return join(getHappyStacksHomeDir(env), 'keys', 'dev-auth.json');
 }
 
 function base64UrlToBytes(s) {

package/scripts/utils/{auth_files.mjs → auth/files.mjs}

@@ -1,10 +1,8 @@
-import { chmod, copyFile, lstat, mkdir, symlink, unlink, writeFile } from 'node:fs/promises';
+import { chmod, copyFile, lstat, symlink, unlink, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 
-async function ensureDir(p) {
-  await mkdir(p, { recursive: true });
-}
+import { ensureDir } from '../fs/ops.mjs';
 
 export async function removeFileOrSymlinkIfExists(path) {
   try {

package/scripts/utils/{handy_master_secret.mjs → auth/handy_master_secret.mjs}

@@ -1,38 +1,12 @@
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { parseDotenv } from './dotenv.mjs';
-import { resolveStackEnvPath } from './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);
-}
+import { parseEnvToObject } from '../env/dotenv.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './sources.mjs';
+import { getEnvValue } from '../env/values.mjs';
+import { readTextIfExists } from '../fs/ops.mjs';
+import { stackExistsSync } from '../stack/stacks.mjs';
 
 export async function resolveHandyMasterSecretFromStack({
   stackName,

package/scripts/utils/cli/flags.mjs

@@ -0,0 +1,17 @@
+export function boolFromFlags({ flags, onFlag, offFlag, defaultValue }) {
+  if (flags.has(offFlag)) return false;
+  if (flags.has(onFlag)) return true;
+  return defaultValue;
+}
+
+export 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;
+}
+

package/scripts/utils/cli/normalize.mjs

@@ -0,0 +1,16 @@
+export 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' || v === 'development') return 'dev';
+  return '';
+}
+
+export function normalizeServerComponent(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 '';
+}
+

package/scripts/utils/cli/smoke_help.mjs

@@ -6,8 +6,8 @@ import { dirname } from 'node:path';
 import { getHappysRegistry } from './cli_registry.mjs';
 
 function cliRootDir() {
-  // scripts/utils/* -> scripts -> repo root
-  return dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  // scripts/utils/cli/* -> scripts/utils -> scripts -> repo root
+  return dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
 }
 
 function runOrThrow(label, args) {

package/scripts/utils/cli/wizard.mjs

@@ -1,5 +1,5 @@
 import { createInterface } from 'node:readline/promises';
-import { listWorktreeSpecs } from '../worktrees.mjs';
+import { listWorktreeSpecs } from '../git/worktrees.mjs';
 
 export function isTty() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);

package/scripts/utils/crypto/tokens.mjs

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto';
+
+export function base64Url(buf) {
+  return Buffer.from(buf)
+    .toString('base64')
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replaceAll('=', '');
+}
+
+export function randomToken(lenBytes = 24) {
+  return base64Url(randomBytes(lenBytes));
+}
+

package/scripts/utils/{dev_daemon.mjs → dev/daemon.mjs}

@@ -1,9 +1,9 @@
 import { resolve } from 'node:path';
 
-import { ensureCliBuilt, ensureDepsInstalled } from './pm.mjs';
-import { watchDebounced } from './watch.mjs';
-import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from './stack_startup.mjs';
-import { startLocalDaemonWithAuth } from '../daemon.mjs';
+import { ensureCliBuilt, ensureDepsInstalled } from '../proc/pm.mjs';
+import { watchDebounced } from '../proc/watch.mjs';
+import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from '../stack/startup.mjs';
+import { startLocalDaemonWithAuth } from '../../daemon.mjs';
 
 export async function ensureDevCliReady({ cliDir, buildCli }) {
   await ensureDepsInstalled(cliDir, 'happy-cli');

package/scripts/utils/{dev_expo_web.mjs → dev/expo_web.mjs}

@@ -1,8 +1,8 @@
-import { ensureDepsInstalled, pmSpawnBin } from './pm.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, wantsExpoClearCache, writePidState } from './expo.mjs';
-import { pickDevMetroPort, resolveStackUiDevPortStart } from './dev_server.mjs';
-import { recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
-import { killProcessGroupOwnedByStack } from './ownership.mjs';
+import { ensureDepsInstalled, pmSpawnBin } from '../proc/pm.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, wantsExpoClearCache, writePidState } from '../expo/expo.mjs';
+import { pickDevMetroPort, resolveStackUiDevPortStart } from './server.mjs';
+import { recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
 
 export async function startDevExpoWebUi({
   startUi,

package/scripts/utils/{dev_server.mjs → dev/server.mjs}

@@ -1,12 +1,12 @@
 import { join, resolve } from 'node:path';
 
-import { ensureDepsInstalled, pmSpawnScript } from './pm.mjs';
-import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './happy_server_infra.mjs';
-import { waitForServerReady } from './server.mjs';
-import { isTcpPortFree, pickNextFreeTcpPort } from './ports.mjs';
-import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
-import { killProcessGroupOwnedByStack } from './ownership.mjs';
-import { watchDebounced } from './watch.mjs';
+import { ensureDepsInstalled, pmSpawnScript } from '../proc/pm.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { waitForServerReady } from '../server/server.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.mjs';
+import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
+import { watchDebounced } from '../proc/watch.mjs';
 
 function hashStringToInt(s) {
   let h = 0;

package/scripts/utils/{config.mjs → env/config.mjs}

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { ensureEnvFileUpdated } from './env_file.mjs';
-import { getHappyStacksHomeDir, resolveStackEnvPath } from './paths.mjs';
-import { getCanonicalHomeDirFromEnv } from './canonical_home.mjs';
+import { getHappyStacksHomeDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getCanonicalHomeDirFromEnv } from '../paths/canonical_home.mjs';
 
 export function getHomeEnvPath() {
   return join(getHappyStacksHomeDir(), '.env');
@@ -50,3 +50,4 @@ export async function ensureUserConfigEnvUpdated({ cliRootDir, updates }) {
   await ensureEnvFileUpdated({ envPath, updates });
   return envPath;
 }
+

package/scripts/utils/{dotenv.mjs → env/dotenv.mjs}

@@ -28,3 +28,6 @@ export function parseDotenv(contents) {
   return out;
 }
 
+export function parseEnvToObject(contents) {
+  return Object.fromEntries(parseDotenv(contents));
+}

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

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDotenv } from './dotenv.mjs';
-import { expandHome, getCanonicalHomeEnvPathFromEnv } from './canonical_home.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../paths/canonical_home.mjs';
 import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 
 async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
@@ -57,8 +57,9 @@ async function loadEnvFileIgnoringPrefixes(path, { ignorePrefixes = [] } = {}) {
 }
 
 // Load happy-stacks env (optional). This is intentionally lightweight and does not require extra deps.
-// This file lives under scripts/utils/, so repo root is two directories up.
-const __utilsDir = dirname(fileURLToPath(import.meta.url));
+// This file lives under scripts/utils/env, so repo root is three directories up.
+const __envDir = dirname(fileURLToPath(import.meta.url));
+const __utilsDir = dirname(__envDir);
 const __scriptsDir = dirname(__utilsDir);
 const __cliRootDir = dirname(__scriptsDir);
 
@@ -207,3 +208,4 @@ process.env.NPM_CONFIG_PACKAGE_MANAGER_STRICT = process.env.NPM_CONFIG_PACKAGE_M
   const next = [...want.filter((p) => p && !current.includes(p)), ...current];
   process.env.PATH = next.join(delimiter);
 })();
+

package/scripts/utils/{env_file.mjs → env/env_file.mjs}

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { pathExists } from './fs.mjs';
+import { pathExists } from '../fs/fs.mjs';
 
 export async function ensureEnvFileUpdated({ envPath, updates }) {
   if (!updates.length) {
@@ -93,3 +93,4 @@ async function writeFileIfChanged(existingContent, nextContent, path) {
   }
   await writeFile(path, normalizedNext, 'utf-8');
 }
+

package/scripts/utils/{env_local.mjs → env/env_local.mjs}

@@ -23,3 +23,4 @@ export async function ensureEnvLocalUpdated({ rootDir, updates }) {
 
   await ensureEnvFileUpdated({ envPath: join(rootDir, 'env.local'), updates });
 }
+

package/scripts/utils/env/read.mjs

@@ -0,0 +1,30 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+
+import { parseDotenv } from './dotenv.mjs';
+
+export async function readEnvValueFromFile(envPath, key, { defaultValue = '' } = {}) {
+  try {
+    const p = String(envPath ?? '').trim();
+    const k = String(key ?? '').trim();
+    if (!p || !k) return defaultValue;
+    if (!existsSync(p)) return defaultValue;
+    const raw = await readFile(p, 'utf-8');
+    const parsed = parseDotenv(raw ?? '');
+    return String(parsed.get(k) ?? '').trim();
+  } catch {
+    return defaultValue;
+  }
+}
+
+export async function readEnvObjectFromFile(envPath) {
+  try {
+    const p = String(envPath ?? '').trim();
+    if (!p || !existsSync(p)) return {};
+    const raw = await readFile(p, 'utf-8');
+    return Object.fromEntries(parseDotenv(raw ?? '').entries());
+  } catch {
+    return {};
+  }
+}
+

package/scripts/utils/env/values.mjs

@@ -0,0 +1,13 @@
+export function getEnvValue(obj, key) {
+  const v = (obj?.[key] ?? '').toString().trim();
+  return v || '';
+}
+
+export function getEnvValueAny(obj, keys) {
+  for (const k of keys) {
+    const v = getEnvValue(obj, k);
+    if (v) return v;
+  }
+  return '';
+}
+

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

@@ -3,6 +3,9 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
+import { isPidAlive } from '../proc/pids.mjs';
+
+export { isPidAlive };
 
 function hashDir(dir) {
   return createHash('sha1').update(String(dir ?? '')).digest('hex').slice(0, 12);
@@ -56,15 +59,6 @@ export async function readPidState(statePath) {
   }
 }
 
-export function isPidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function isStateProcessRunning(statePath) {
   const state = await readPidState(statePath);
   if (!state) return { running: false, state: null };

package/scripts/utils/fs/json.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+
+export async function readJsonIfExists(path, { defaultValue = null } = {}) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return defaultValue;
+    const raw = await readFile(p, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return defaultValue;
+  }
+}
+
+export async function writeJsonAtomic(path, value) {
+  const p = String(path ?? '').trim();
+  if (!p) throw new Error('writeJsonAtomic: path is required');
+  const dir = dirname(p);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.tmp.${Date.now()}.${Math.random().toString(16).slice(2)}.json`);
+  await writeFile(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+  await rename(tmp, p);
+}
+

package/scripts/utils/fs/ops.mjs

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+
+export async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+export async function readTextIfExists(path) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return null;
+    const raw = await readFile(p, 'utf-8');
+    const t = raw.trim();
+    return t ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readTextOrEmpty(path) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return '';
+    return await readFile(p, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+

package/scripts/utils/fs/package_json.mjs

@@ -0,0 +1,8 @@
+import { readJsonIfExists } from './json.mjs';
+
+export async function readPackageJsonVersion(path) {
+  const pkg = await readJsonIfExists(path, { defaultValue: null });
+  const v = String(pkg?.version ?? '').trim();
+  return v || null;
+}
+

package/scripts/utils/fs/tail.mjs

@@ -0,0 +1,12 @@
+import { readFile } from 'node:fs/promises';
+
+export async function readLastLines(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;
+  }
+}
+

package/scripts/utils/git/refs.mjs

@@ -0,0 +1,26 @@
+export function parseGithubPullRequest(input) {
+  const raw = (input ?? '').trim();
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) {
+    return { number: Number(raw), owner: null, repo: null };
+  }
+  // https://github.com/<owner>/<repo>/pull/<num>
+  const m = raw.match(/github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)\/pull\/(?<num>\d+)/);
+  if (!m?.groups?.num) return null;
+  return {
+    number: Number(m.groups.num),
+    owner: m.groups.owner ?? null,
+    repo: m.groups.repo ?? null,
+  };
+}
+
+export function sanitizeSlugPart(s) {
+  return (s ?? '')
+    .toString()
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._/-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+

package/scripts/utils/{worktrees.mjs → git/worktrees.mjs}

@@ -1,8 +1,8 @@
 import { readdir } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
-import { getComponentsDir } from './paths.mjs';
-import { pathExists } from './fs.mjs';
-import { run, runCapture } from './proc.mjs';
+import { getComponentsDir } from '../paths/paths.mjs';
+import { pathExists } from '../fs/fs.mjs';
+import { run, runCapture } from '../proc/proc.mjs';
 
 export function parseGithubOwner(remoteUrl) {
   const raw = (remoteUrl ?? '').trim();

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

@@ -1,6 +1,6 @@
 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) {
   if (!Number.isFinite(port) || port <= 0) return [];
@@ -9,10 +9,7 @@ async function listListenPids(port) {
   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']);
   } catch {
     raw = '';
   }
@@ -102,3 +99,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/{localhost_host.mjs → paths/localhost_host.mjs}

@@ -1,17 +1,9 @@
 import { getStackName } from './paths.mjs';
-
-function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
-  const s = String(raw ?? '')
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '');
-  return s || fallback;
-}
+import { sanitizeDnsLabel } from '../net/dns.mjs';
 
 export function resolveLocalhostHost({ stackMode, stackName = getStackName() } = {}) {
   if (!stackMode) return 'localhost';
   if (!stackName || stackName === 'main') return 'localhost';
   return `happy-${sanitizeDnsLabel(stackName)}.localhost`;
 }
+