happy-stacks 0.2.0 → 0.3.0

package/scripts/utils/server/urls.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { resolvePublicServerUrl } from '../../tailscale.mjs';
+import { resolveServerPortFromEnv } from './port.mjs';
+
+function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
+  try {
+    const envPath =
+      (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+      resolveStackEnvPath(stackName).envPath;
+    if (!envPath || !existsSync(envPath)) return false;
+    const raw = readFileSync(envPath, 'utf-8');
+    return /^(HAPPY_STACKS_SERVER_URL|HAPPY_LOCAL_SERVER_URL)=/m.test(raw);
+  } catch {
+    return false;
+  }
+}
+
+function stackEnvExplicitlySetsWebappUrl({ env, stackName }) {
+  try {
+    const envPath =
+      (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+      resolveStackEnvPath(stackName).envPath;
+    if (!envPath || !existsSync(envPath)) return false;
+    const raw = readFileSync(envPath, 'utf-8');
+    return /^HAPPY_WEBAPP_URL=/m.test(raw);
+  } catch {
+    return false;
+  }
+}
+
+export function getPublicServerUrlEnvOverride({ env = process.env, serverPort, stackName = null } = {}) {
+  const defaultPublicUrl = `http://localhost:${serverPort}`;
+  const name =
+    (stackName ?? '').toString().trim() ||
+    (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
+    getStackName();
+
+  let envPublicUrl =
+    (env.HAPPY_STACKS_SERVER_URL ?? env.HAPPY_LOCAL_SERVER_URL ?? '').toString().trim() || '';
+
+  // Safety: for non-main stacks, ignore a global SERVER_URL unless it was explicitly set in the stack env file.
+  if (name !== 'main' && envPublicUrl && !stackEnvExplicitlySetsPublicUrl({ env, stackName: name })) {
+    envPublicUrl = '';
+  }
+
+  return { defaultPublicUrl, envPublicUrl, publicServerUrl: envPublicUrl || defaultPublicUrl };
+}
+
+export function getWebappUrlEnvOverride({ env = process.env, stackName = null } = {}) {
+  const name =
+    (stackName ?? '').toString().trim() ||
+    (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
+    getStackName();
+
+  let envWebappUrl = (env.HAPPY_WEBAPP_URL ?? '').toString().trim() || '';
+
+  // Safety: for non-main stacks, ignore a global HAPPY_WEBAPP_URL unless it was explicitly set in the stack env file.
+  if (name !== 'main' && envWebappUrl && !stackEnvExplicitlySetsWebappUrl({ env, stackName: name })) {
+    envWebappUrl = '';
+  }
+
+  return { envWebappUrl };
+}
+
+export async function resolveServerUrls({ env = process.env, serverPort, allowEnable = true } = {}) {
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env, serverPort });
+  const resolved = await resolvePublicServerUrl({
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    allowEnable,
+  });
+  return {
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    publicServerUrl: resolved.publicServerUrl,
+    publicServerUrlSource: resolved.source,
+  };
+}
+
+export function getInternalServerUrl({ env = process.env, defaultPort = 3005 } = {}) {
+  const port = resolveServerPortFromEnv({ env, defaultPort });
+  return { port, internalServerUrl: `http://127.0.0.1:${port}` };
+}
+
+export { resolveServerPortFromEnv };
+

package/scripts/utils/{validate.mjs → server/validate.mjs}

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { getComponentsDir } from './paths.mjs';
+import { getComponentsDir } from '../paths/paths.mjs';
 
 function isInside(path, dir) {
   const p = resolve(path);

package/scripts/utils/service/autostart_darwin.mjs

@@ -0,0 +1,142 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+
+import { runCapture } from '../proc/proc.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+import { resolveInstalledCliRoot, resolveInstalledPath } from '../paths/runtime.mjs';
+
+function plistPathForLabel(label) {
+  return join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+}
+
+function xmlEscape(s) {
+  return String(s ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function plistXml({ label, programArgs, env = {}, stdoutPath, stderrPath, workingDirectory }) {
+  const envEntries = Object.entries(env ?? {}).filter(([k, v]) => String(k).trim() && String(v ?? '').trim());
+  const programArgsXml = programArgs.map((a) => `      <string>${xmlEscape(a)}</string>`).join('\n');
+  const envXml = envEntries
+    .map(([k, v]) => `      <key>${xmlEscape(k)}</key>\n      <string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  const workingDirXml = workingDirectory
+    ? `\n    <key>WorkingDirectory</key>\n    <string>${xmlEscape(workingDirectory)}</string>\n`
+    : '\n';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xmlEscape(label)}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgsXml}
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+${workingDirXml}    <key>StandardOutPath</key>
+    <string>${xmlEscape(stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(stderrPath)}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+  </dict>
+</plist>
+`;
+}
+
+export async function ensureMacAutostartEnabled({ rootDir, label, env }) {
+  if (process.platform !== 'darwin') {
+    throw new Error('[local] macOS autostart is only supported on Darwin');
+  }
+  const l = String(label ?? '').trim();
+  if (!l) throw new Error('[local] missing launchd label');
+
+  const plistPath = plistPathForLabel(l);
+  const { stdoutPath, stderrPath } = getDefaultAutostartPaths();
+  await mkdir(dirname(plistPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stdoutPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stderrPath), { recursive: true }).catch(() => {});
+
+  const programArgs = [process.execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+  const mergedEnv = {
+    ...(env ?? {}),
+    // Ensure a reasonable PATH for subprocesses (git/docker/etc) in launchd’s minimal environment.
+    PATH: (process.env.PATH ?? '').trim() || '/usr/bin:/bin:/usr/sbin:/sbin',
+  };
+
+  const xml = plistXml({
+    label: l,
+    programArgs,
+    env: mergedEnv,
+    stdoutPath,
+    stderrPath,
+    workingDirectory: resolveInstalledCliRoot(rootDir),
+  });
+
+  const tmp = join(dirname(plistPath), `.tmp.${l}.${Date.now()}.plist`);
+  await writeFile(tmp, xml, 'utf-8');
+  await rename(tmp, plistPath);
+
+  // Best-effort load/enable; `scripts/service.mjs` has a more robust bootstrap fallback.
+  try {
+    await runCapture('launchctl', ['load', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+}
+
+export async function ensureMacAutostartDisabled({ label }) {
+  if (process.platform !== 'darwin') {
+    return;
+  }
+  const l = String(label ?? '').trim();
+  if (!l) return;
+  const plistPath = plistPathForLabel(l);
+
+  const uidRaw = Number(process.env.UID);
+  const uid = Number.isFinite(uidRaw) ? uidRaw : null;
+
+  try {
+    await runCapture('launchctl', ['unload', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+  try {
+    await runCapture('launchctl', ['unload', plistPath]);
+  } catch {
+    // ignore
+  }
+  if (uid != null) {
+    try {
+      await runCapture('launchctl', ['disable', `gui/${uid}/${l}`]);
+    } catch {
+      // ignore
+    }
+    try {
+      await runCapture('launchctl', ['bootout', `gui/${uid}`, plistPath]);
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    await runCapture('launchctl', ['remove', l]);
+  } catch {
+    // ignore
+  }
+}
+

package/scripts/utils/{stack_context.mjs → stack/context.mjs}

@@ -1,5 +1,5 @@
-import { getStackName, resolveStackEnvPath } from './paths.mjs';
-import { getStackRuntimeStatePath } from './stack_runtime_state.mjs';
+import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getStackRuntimeStatePath } from './runtime_state.mjs';
 
 export function resolveStackContext({ env = process.env, autostart = null } = {}) {
   const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();

package/scripts/utils/stack/dirs.mjs

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+
+import { expandHome } from '../paths/canonical_home.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+
+export function getCliHomeDirFromEnvOrDefault({ stackBaseDir, env }) {
+  const fromEnv = (env?.HAPPY_STACKS_CLI_HOME_DIR ?? env?.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
+  return fromEnv || join(stackBaseDir, 'cli');
+}
+
+export function getServerLightDataDirFromEnvOrDefault({ stackBaseDir, env }) {
+  const fromEnv = (env?.HAPPY_SERVER_LIGHT_DATA_DIR ?? '').trim();
+  return fromEnv || join(stackBaseDir, 'server-light');
+}
+
+export function resolveCliHomeDir(env = process.env) {
+  const fromExplicit = (env.HAPPY_HOME_DIR ?? '').trim();
+  if (fromExplicit) {
+    return expandHome(fromExplicit);
+  }
+  const fromStacks = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
+  if (fromStacks) {
+    return expandHome(fromStacks);
+  }
+  return join(getDefaultAutostartPaths().baseDir, 'cli');
+}
+

package/scripts/utils/stack/editor_workspace.mjs

@@ -0,0 +1,152 @@
+import { join, resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+
+import { expandHome } from '../paths/canonical_home.mjs';
+import { getComponentDir, getWorkspaceDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { ensureDir } from '../fs/ops.mjs';
+import { getEnvValueAny } from '../env/values.mjs';
+import { readEnvObjectFromFile } from '../env/read.mjs';
+import { resolveCommandPath } from '../proc/commands.mjs';
+import { run, runCapture } from '../proc/proc.mjs';
+import { getCliHomeDirFromEnvOrDefault } from './dirs.mjs';
+
+function resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv }) {
+  const raw = getEnvValueAny(stackEnv, ['HAPPY_STACKS_WORKSPACE_DIR', 'HAPPY_LOCAL_WORKSPACE_DIR']);
+  if (!raw) {
+    return getWorkspaceDir(rootDir);
+  }
+  const expanded = expandHome(raw);
+  return expanded.startsWith('/') ? expanded : resolve(rootDir, expanded);
+}
+
+function resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component }) {
+  const raw = getEnvValueAny(stackEnv, keys);
+  if (!raw) return getComponentDir(rootDir, component);
+  const expanded = expandHome(raw);
+  if (expanded.startsWith('/')) return expanded;
+  const workspaceDir = resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv });
+  return resolve(workspaceDir, expanded);
+}
+
+export async function isCursorInstalled({ cwd, env } = {}) {
+  if (await resolveCommandPath('cursor', { cwd, env })) return true;
+  if (process.platform !== 'darwin') return false;
+  try {
+    await runCapture('open', ['-Ra', 'Cursor'], { cwd, env });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function openWorkspaceInEditor({ rootDir, editor, workspacePath }) {
+  if (editor === 'code') {
+    const codePath = await resolveCommandPath('code', { cwd: rootDir, env: process.env });
+    if (!codePath) {
+      throw new Error(
+        "[stack] VS Code CLI 'code' not found on PATH. In VS Code: Cmd+Shift+P → 'Shell Command: Install code command in PATH'."
+      );
+    }
+    await run(codePath, ['-n', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return;
+  }
+
+  const cursorPath = await resolveCommandPath('cursor', { cwd: rootDir, env: process.env });
+  if (cursorPath) {
+    try {
+      await run(cursorPath, ['-n', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    } catch {
+      await run(cursorPath, [workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    }
+    return;
+  }
+
+  if (process.platform === 'darwin') {
+    // Cursor installed but CLI missing is common on macOS.
+    await run('open', ['-na', 'Cursor', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return;
+  }
+
+  throw new Error("[stack] Cursor CLI 'cursor' not found on PATH (and non-macOS fallback is unavailable).");
+}
+
+export async function writeStackCodeWorkspace({
+  rootDir,
+  stackName,
+  includeStackDir,
+  includeAllComponents,
+  includeCliHome,
+}) {
+  const { baseDir, envPath } = resolveStackEnvPath(stackName);
+  const stackEnv = await readEnvObjectFromFile(envPath);
+
+  const serverComponent =
+    getEnvValueAny(stackEnv, ['HAPPY_STACKS_SERVER_COMPONENT', 'HAPPY_LOCAL_SERVER_COMPONENT']) || 'happy-server-light';
+
+  const selectedComponents = includeAllComponents
+    ? ['happy', 'happy-cli', 'happy-server-light', 'happy-server']
+    : ['happy', 'happy-cli', serverComponent];
+
+  const componentSpecs = [
+    { component: 'happy', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY'] },
+    { component: 'happy-cli', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_CLI'] },
+    {
+      component: 'happy-server-light',
+      keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT'],
+    },
+    { component: 'happy-server', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER'] },
+  ];
+  const byName = new Map(componentSpecs.map((c) => [c.component, c.keys]));
+
+  const folders = [];
+  if (includeStackDir) {
+    folders.push({ name: `stack:${stackName}`, path: baseDir });
+  }
+  if (includeCliHome) {
+    const cliHomeDir = getCliHomeDirFromEnvOrDefault({ stackBaseDir: baseDir, env: stackEnv });
+    folders.push({ name: `cli:${stackName}`, path: expandHome(cliHomeDir) });
+  }
+  for (const component of selectedComponents) {
+    const keys = byName.get(component) ?? [];
+    const dir = resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component });
+    folders.push({ name: component, path: dir });
+  }
+
+  // Deduplicate by path (can happen if multiple components are pointed at the same dir).
+  const uniqFolders = folders.filter((f, i, arr) => arr.findIndex((x) => x.path === f.path) === i);
+
+  await ensureDir(baseDir);
+  const workspacePath = join(baseDir, `stack.${stackName}.code-workspace`);
+  const payload = {
+    folders: uniqFolders,
+    settings: {
+      'search.exclude': {
+        '**/node_modules/**': true,
+        '**/.git/**': true,
+        '**/logs/**': true,
+        '**/cli/logs/**': true,
+      },
+      'files.watcherExclude': {
+        '**/node_modules/**': true,
+        '**/.git/**': true,
+        '**/logs/**': true,
+        '**/cli/logs/**': true,
+      },
+    },
+  };
+  await writeFile(workspacePath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+
+  return {
+    workspacePath,
+    baseDir,
+    envPath,
+    serverComponent,
+    folders: uniqFolders,
+    flags: {
+      includeStackDir: Boolean(includeStackDir),
+      includeCliHome: Boolean(includeCliHome),
+      includeAllComponents: Boolean(includeAllComponents),
+    },
+  };
+}
+

package/scripts/utils/stack/names.mjs

@@ -0,0 +1,12 @@
+export function sanitizeStackName(raw, { fallback = 'stack', maxLen = 64 } = {}) {
+  const s = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  const out = s || String(fallback ?? 'stack');
+  return Number.isFinite(maxLen) && maxLen > 0 ? out.slice(0, maxLen) : out;
+}
+

package/scripts/utils/{stack_runtime_state.mjs → stack/runtime_state.mjs}

@@ -1,45 +1,28 @@
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { unlink } from 'node:fs/promises';
+import { join } from 'node:path';
 
-import { resolveStackEnvPath } from './paths.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+import { readJsonIfExists, writeJsonAtomic } from '../fs/json.mjs';
+import { isPidAlive } from '../proc/pids.mjs';
+
+export { isPidAlive };
 
 export function getStackRuntimeStatePath(stackName) {
   const { baseDir } = resolveStackEnvPath(stackName);
   return join(baseDir, 'stack.runtime.json');
 }
 
-export function isPidAlive(pid) {
-  const n = Number(pid);
-  if (!Number.isFinite(n) || n <= 1) return false;
-  try {
-    process.kill(n, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function readStackRuntimeStateFile(statePath) {
-  try {
-    if (!statePath || !existsSync(statePath)) return null;
-    const raw = await readFile(statePath, 'utf-8');
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  } catch {
-    return null;
-  }
+  const parsed = await readJsonIfExists(statePath, { defaultValue: null });
+  return parsed && typeof parsed === 'object' ? parsed : null;
 }
 
 export async function writeStackRuntimeStateFile(statePath, state) {
   if (!statePath) {
     throw new Error('[stack] missing runtime state path');
   }
-  const dir = dirname(statePath);
-  await mkdir(dir, { recursive: true }).catch(() => {});
-  const tmp = join(dir, `.stack.runtime.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
-  await writeFile(tmp, JSON.stringify(state, null, 2) + '\n', 'utf-8');
-  await rename(tmp, statePath);
+  await writeJsonAtomic(statePath, state);
 }
 
 function isPlainObject(v) {

package/scripts/utils/{stacks.mjs → stack/stacks.mjs}

@@ -2,8 +2,9 @@ import { readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { getLegacyStorageRoot, getStacksStorageRoot } from './paths.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
+import { getLegacyStorageRoot, getStacksStorageRoot } from '../paths/paths.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from '../env/sandbox.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
 
 export async function listAllStackNames() {
   const names = new Set(['main']);
@@ -36,3 +37,9 @@ export async function listAllStackNames() {
 
   return Array.from(names).sort();
 }
+
+export function stackExistsSync(stackName) {
+  const name = String(stackName ?? '').trim() || 'main';
+  if (name === 'main') return true;
+  return existsSync(resolveStackEnvPath(name).envPath);
+}

package/scripts/utils/{stack_startup.mjs → stack/startup.mjs}

@@ -1,5 +1,5 @@
-import { runCapture } from './proc.mjs';
-import { ensureDepsInstalled, pmExecBin } from './pm.mjs';
+import { runCapture } from '../proc/proc.mjs';
+import { ensureDepsInstalled, pmExecBin } from '../proc/pm.mjs';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 

package/scripts/utils/{stack_stop.mjs → stack/stop.mjs}

@@ -2,19 +2,13 @@ import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { getComponentDir } from './paths.mjs';
-import { isPidAlive, readPidState } from './expo.mjs';
-import { stopLocalDaemon } from '../daemon.mjs';
-import { stopHappyServerManagedInfra } from './happy_server_infra.mjs';
-import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './stack_runtime_state.mjs';
-import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedle } from './ownership.mjs';
-
-function parseIntOrNull(raw) {
-  const s = String(raw ?? '').trim();
-  if (!s) return null;
-  const n = Number(s);
-  return Number.isFinite(n) && n > 0 ? n : null;
-}
+import { getComponentDir } from '../paths/paths.mjs';
+import { isPidAlive, readPidState } from '../expo/expo.mjs';
+import { stopLocalDaemon } from '../../daemon.mjs';
+import { stopHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './runtime_state.mjs';
+import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedle } from '../proc/ownership.mjs';
+import { coercePort } from '../server/port.mjs';
 
 function resolveServerComponentFromStackEnv(env) {
   const v =
@@ -139,8 +133,8 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
   };
 
   const serverComponent = resolveServerComponentFromStackEnv(env);
-  const port = parseIntOrNull(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
-  const backendPort = parseIntOrNull(env.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? env.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT);
+  const port = coercePort(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
+  const backendPort = coercePort(env.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? env.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT);
   const cliHomeDir = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? join(baseDir, 'cli')).toString();
   const cliBin = join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs');
   const envPath = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString();

package/scripts/utils/{browser.mjs → ui/browser.mjs}

@@ -1,4 +1,4 @@
-import { runCapture } from './proc.mjs';
+import { runCapture } from '../proc/proc.mjs';
 
 export async function openUrlInBrowser(url, { timeoutMs = 5_000 } = {}) {
   const u = String(url ?? '').trim();

package/scripts/utils/ui/text.mjs

@@ -0,0 +1,16 @@
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+export function padRight(s, n) {
+  const str = String(s ?? '');
+  if (str.length >= n) return str.slice(0, n);
+  return str + ' '.repeat(n - str.length);
+}
+
+export function parsePrefixedLabel(line) {
+  const m = String(line ?? '').match(/^\[([^\]]+)\]\s*/);
+  return m ? m[1] : null;
+}
+

package/scripts/where.mjs

@@ -1,15 +1,15 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { parseArgs } from './utils/cli/args.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { getComponentsDir, getComponentDir, getHappyStacksHomeDir, getRootDir, getStackLabel, getStackName, getWorkspaceDir, resolveStackEnvPath } from './utils/paths.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getComponentsDir, getComponentDir, getHappyStacksHomeDir, getRootDir, getStackLabel, getStackName, getWorkspaceDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-import { getCanonicalHomeDir, getCanonicalHomeEnvPath } from './utils/config.mjs';
-import { getSandboxDir } from './utils/sandbox.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { getCanonicalHomeDir, getCanonicalHomeEnvPath } from './utils/env/config.mjs';
+import { getSandboxDir } from './utils/env/sandbox.mjs';
 
 function getHomeEnvPaths() {
   const homeDir = getHappyStacksHomeDir();