@happier-dev/stack 0.1.0-preview.5.1

package/scripts/setup_pr_orchestrated_auth_flow_util_import.test.mjs

@@ -0,0 +1,117 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr }));
+  });
+}
+
+function toDataUrl(source) {
+  return `data:text/javascript,${encodeURIComponent(source)}`;
+}
+
+test('setup_pr guided-login path delegates to orchestrated auth flow helpers at runtime', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-setup-pr-orchestrated-'));
+  try {
+    const markerPath = join(tmp, 'orchestrated.markers.log');
+    const loaderPath = join(tmp, 'loader.mjs');
+    const registerPath = join(tmp, 'register-loader.mjs');
+    await writeFile(markerPath, '', 'utf-8');
+
+    const stubBySpecifier = {
+      './utils/cli/prereqs.mjs': toDataUrl(`
+export async function assertCliPrereqs() {}
+`),
+      './utils/proc/proc.mjs': toDataUrl(`
+export async function run() {}
+`),
+      './utils/auth/guided_pr_auth.mjs': toDataUrl(`
+export async function decidePrAuthPlan() {
+  return { mode: 'login', loginNow: true };
+}
+`),
+      './utils/auth/orchestrated_stack_auth_flow.mjs': toDataUrl(`
+import { appendFileSync } from 'node:fs';
+const markerPath = process.env.HSTACK_SETUP_PR_MARKER;
+function mark(name) {
+  if (!markerPath) return;
+  appendFileSync(markerPath, String(name) + '\\n', 'utf-8');
+}
+export async function runOrchestratedGuidedAuthFlow() {
+  mark('runOrchestratedGuidedAuthFlow');
+  return { ok: true, webappUrl: 'http://127.0.0.1:3010' };
+}
+export async function startDaemonPostAuth() {
+  mark('startDaemonPostAuth');
+  return { ok: true };
+}
+`),
+    };
+
+    const loaderSource = `
+const stubBySpecifier = ${JSON.stringify(stubBySpecifier)};
+
+export async function resolve(specifier, context, defaultResolve) {
+  const stub = stubBySpecifier[specifier];
+  if (stub) {
+    return { url: stub, shortCircuit: true };
+  }
+  return defaultResolve(specifier, context, defaultResolve);
+}
+`;
+    await writeFile(loaderPath, loaderSource, 'utf-8');
+    await writeFile(
+      registerPath,
+      [
+        `import { register } from 'node:module';`,
+        `register(${JSON.stringify(pathToFileURL(loaderPath).href)}, import.meta.url);`,
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_TEST_TTY: '1',
+      HAPPIER_STACK_VERBOSE: '1',
+      HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+      HAPPIER_STACK_STORAGE_DIR: join(tmp, 'storage'),
+      HAPPIER_STACK_WORKSPACE_DIR: join(tmp, 'workspace'),
+      HSTACK_SETUP_PR_MARKER: markerPath,
+    };
+
+    const res = await runNode(
+      [
+        '--import',
+        registerPath,
+        join(rootDir, 'scripts', 'setup_pr.mjs'),
+        '--repo=123',
+        '--name=pr123',
+        '--dev',
+        '--no-seed-auth',
+      ],
+      { cwd: rootDir, env }
+    );
+    assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+    const markerLog = await readFile(markerPath, 'utf-8');
+    assert.match(markerLog, /\brunOrchestratedGuidedAuthFlow\b/, `expected setup_pr to call runOrchestratedGuidedAuthFlow\n${markerLog}`);
+    assert.match(markerLog, /\bstartDaemonPostAuth\b/, `expected setup_pr to call startDaemonPostAuth\n${markerLog}`);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/stack/command_arguments.mjs

@@ -0,0 +1,91 @@
+import { resolvehstackCommand } from '../utils/cli/cli_registry.mjs';
+
+const STACK_NAME_FIRST_SUPPORTED_COMMANDS = new Set([
+  'new',
+  'edit',
+  'list',
+  'migrate',
+  'audit',
+  'archive',
+  'duplicate',
+  'info',
+  'pr',
+  'create-dev-auth-seed',
+  'daemon',
+  'happier',
+  'env',
+  'auth',
+  'dev',
+  'start',
+  'build',
+  'review',
+  'typecheck',
+  'lint',
+  'test',
+  'doctor',
+  'mobile',
+  'mobile:install',
+  'mobile-dev-client',
+  'resume',
+  'stop',
+  'code',
+  'cursor',
+  'open',
+  'srv',
+  'wt',
+  'service',
+]);
+
+export function resolveTopLevelNodeScriptFile(cmd) {
+  const command = resolvehstackCommand(cmd);
+  if (!command || command.kind !== 'node') return null;
+  const rel = String(command.scriptRelPath ?? '').trim();
+  if (!rel) return null;
+  return rel.startsWith('scripts/') ? rel.slice('scripts/'.length) : rel;
+}
+
+export function stackNameFromArg(positionals, idx) {
+  const name = positionals[idx]?.trim() ? positionals[idx].trim() : '';
+  return name;
+}
+
+export function isKnownStackCommandToken(token) {
+  const value = (token ?? '').toString().trim();
+  if (!value) return false;
+  if (value.startsWith('service:')) return true;
+  if (value.startsWith('tailscale:')) return true;
+  return STACK_NAME_FIRST_SUPPORTED_COMMANDS.has(value);
+}
+
+export function normalizeStackNameFirstArgs(argv, { stackExists }) {
+  // Back-compat UX:
+  // Allow `hstack stack <name> <command> ...` (stack name first) as a shortcut for:
+  //   `hstack stack <command> <name> ...`
+  //
+  // We only apply this rewrite when the first positional is *not* a known stack subcommand,
+  // but *is* an existing stack name.
+  const args = Array.isArray(argv) ? argv : [];
+  const positionalIdx = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (!a) continue;
+    if (a === '--') continue;
+    if (a.startsWith('-')) continue;
+    positionalIdx.push(i);
+    if (positionalIdx.length >= 2) break;
+  }
+  if (positionalIdx.length < 2) return args;
+
+  const [i0, i1] = positionalIdx;
+  const first = args[i0];
+  const second = args[i1];
+
+  if (isKnownStackCommandToken(first)) return args;
+  if (!isKnownStackCommandToken(second)) return args;
+  if (typeof stackExists !== 'function' || !stackExists(first)) return args;
+
+  const next = [...args];
+  next[i0] = second;
+  next[i1] = first;
+  return next;
+}

package/scripts/stack/copy_auth_from_stack.mjs

@@ -0,0 +1,111 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnvToObject } from '../utils/env/dotenv.mjs';
+import { readTextOrEmpty } from '../utils/fs/ops.mjs';
+import { resolveStackEnvPath } from '../utils/paths/paths.mjs';
+import { resolveServerPortFromEnv } from '../utils/server/urls.mjs';
+import { getCliHomeDirFromEnvOrDefault } from '../utils/stack/dirs.mjs';
+import { applyStackActiveServerScopeEnv } from '../utils/auth/stable_scope_id.mjs';
+import { resolveHandyMasterSecretFromStack } from '../utils/auth/handy_master_secret.mjs';
+import { copyFileIfMissing, linkFileIfMissing, writeSecretFileIfMissing } from '../utils/auth/files.mjs';
+import { findAnyCredentialPathInCliHome, findExistingStackCredentialPath, resolveStackCredentialPaths } from '../utils/auth/credentials_paths.mjs';
+
+const readExistingEnv = readTextOrEmpty;
+
+export async function copyAuthFromStackIntoNewStack({
+  fromStackName,
+  stackName,
+  stackEnv,
+  serverComponent,
+  json,
+  requireSourceStackExists,
+  linkMode = false,
+}) {
+  const { secret, source } = await resolveHandyMasterSecretFromStack({
+    stackName: fromStackName,
+    requireStackExists: requireSourceStackExists,
+  });
+
+  const copied = { secret: false, accessKey: false, settings: false, sourceStack: fromStackName };
+
+  if (secret) {
+    if (serverComponent === 'happier-server-light') {
+      const dataDir = stackEnv.HAPPIER_SERVER_LIGHT_DATA_DIR;
+      const target = join(dataDir, 'handy-master-secret.txt');
+      const sourcePath = source && !String(source).includes('(HANDY_MASTER_SECRET)') ? String(source) : '';
+      copied.secret =
+        linkMode && sourcePath && existsSync(sourcePath)
+          ? await linkFileIfMissing({ from: sourcePath, to: target })
+          : await writeSecretFileIfMissing({ path: target, secret });
+    } else if (serverComponent === 'happier-server') {
+      const target = stackEnv.HAPPIER_STACK_HANDY_MASTER_SECRET_FILE;
+      if (target) {
+        const sourcePath = source && !String(source).includes('(HANDY_MASTER_SECRET)') ? String(source) : '';
+        copied.secret =
+          linkMode && sourcePath && existsSync(sourcePath)
+            ? await linkFileIfMissing({ from: sourcePath, to: target })
+            : await writeSecretFileIfMissing({ path: target, secret });
+      }
+    }
+  }
+
+  const { baseDir: sourceBaseDir, envPath: sourceEnvPath } = resolveStackEnvPath(fromStackName);
+  const sourceEnvRaw = await readExistingEnv(sourceEnvPath);
+  const sourceEnv = parseEnvToObject(sourceEnvRaw);
+  const sourceCli = getCliHomeDirFromEnvOrDefault({ stackBaseDir: sourceBaseDir, env: sourceEnv });
+  const targetCli = stackEnv.HAPPIER_STACK_CLI_HOME_DIR;
+  const sourceInternalServerUrl = `http://127.0.0.1:${resolveServerPortFromEnv({ env: sourceEnv, defaultPort: 3005 })}`;
+  const targetInternalServerUrl = `http://127.0.0.1:${resolveServerPortFromEnv({ env: stackEnv, defaultPort: 3005 })}`;
+  const sourceEnvScoped = applyStackActiveServerScopeEnv({ env: sourceEnv, stackName: fromStackName, cliIdentity: 'default' });
+  const targetEnvScoped = applyStackActiveServerScopeEnv({ env: stackEnv, stackName, cliIdentity: 'default' });
+  const sourceCredentialPaths = resolveStackCredentialPaths({
+    cliHomeDir: sourceCli,
+    serverUrl: sourceInternalServerUrl,
+    env: sourceEnvScoped,
+  });
+  const targetCredentialPaths = resolveStackCredentialPaths({
+    cliHomeDir: targetCli,
+    serverUrl: targetInternalServerUrl,
+    env: targetEnvScoped,
+  });
+  const sourceAccessKeyPath =
+    findExistingStackCredentialPath({ cliHomeDir: sourceCli, serverUrl: sourceInternalServerUrl, env: sourceEnvScoped }) ||
+    [sourceCredentialPaths.serverScopedPath, sourceCredentialPaths.urlHashServerScopedPath, sourceCredentialPaths.legacyPath]
+      .filter(Boolean)
+      .find((candidate) => existsSync(candidate)) ||
+    findAnyCredentialPathInCliHome({ cliHomeDir: sourceCli });
+
+  if (linkMode) {
+    copied.accessKey =
+      sourceAccessKeyPath
+        ? await linkFileIfMissing({ from: sourceAccessKeyPath, to: targetCredentialPaths.serverScopedPath })
+        : false;
+    copied.settings = await linkFileIfMissing({ from: join(sourceCli, 'settings.json'), to: join(targetCli, 'settings.json') });
+  } else {
+    copied.accessKey =
+      sourceAccessKeyPath
+        ? await copyFileIfMissing({
+            from: sourceAccessKeyPath,
+            to: targetCredentialPaths.serverScopedPath,
+            mode: 0o600,
+          })
+        : false;
+    copied.settings = await copyFileIfMissing({
+      from: join(sourceCli, 'settings.json'),
+      to: join(targetCli, 'settings.json'),
+      mode: 0o600,
+    });
+  }
+
+  if (!json) {
+    const any = copied.secret || copied.accessKey || copied.settings;
+    if (any) {
+      console.log(`[stack] copied auth from "${fromStackName}" into "${stackName}" (no re-login needed)`);
+      if (copied.secret) console.log(`  - master secret: copied (${source || 'unknown source'})`);
+      if (copied.accessKey) console.log(`  - cli: copied access.key`);
+      if (copied.settings) console.log(`  - cli: copied settings.json`);
+    }
+  }
+
+  return copied;
+}

package/scripts/stack/delegated_script_commands.mjs

@@ -0,0 +1,92 @@
+import { join } from 'node:path';
+import { run } from '../utils/proc/proc.mjs';
+import { listAllStackNames } from '../utils/stack/stacks.mjs';
+import { getRuntimePortExtraEnv, withStackEnv } from './stack_environment.mjs';
+
+export async function cmdService({ rootDir, stackName, svcCmd }) {
+  await withStackEnv({
+    stackName,
+    fn: async ({ env }) => {
+      await run(process.execPath, [join(rootDir, 'scripts', 'service.mjs'), svcCmd], { cwd: rootDir, env });
+    },
+  });
+}
+
+export async function cmdTailscale({ rootDir, stackName, subcmd, args }) {
+  const extraEnv = await getRuntimePortExtraEnv(stackName);
+  await withStackEnv({
+    stackName,
+    ...(extraEnv ? { extraEnv } : {}),
+    fn: async ({ env }) => {
+      await run(process.execPath, [join(rootDir, 'scripts', 'tailscale.mjs'), subcmd, ...args], { cwd: rootDir, env });
+    },
+  });
+}
+
+export async function cmdSrv({ rootDir, stackName, args }) {
+  // Forward to scripts/server_flavor.mjs under the stack env.
+  const forwarded = args[0] === '--' ? args.slice(1) : args;
+  await withStackEnv({
+    stackName,
+    fn: async ({ env }) => {
+      await run(process.execPath, [join(rootDir, 'scripts', 'server_flavor.mjs'), ...forwarded], { cwd: rootDir, env });
+    },
+  });
+}
+
+export async function cmdWt({ rootDir, stackName, args }) {
+  // Forward to scripts/worktrees.mjs under the stack env.
+  // This makes `hstack stack wt <name> -- ...` behave exactly like `hstack wt ...`,
+  // but read/write the stack env file (HAPPIER_STACK_ENV_FILE) instead of repo env.local.
+  let forwarded = args[0] === '--' ? args.slice(1) : args;
+
+  // Stack users usually want to see what *this stack* is using (active checkout),
+  // not an exhaustive enumeration of every worktree on disk.
+  //
+  // `hstack wt list` defaults to showing all worktrees. In stack mode, default to
+  // an active-only view unless the caller opts into `--all`.
+  if (forwarded[0] === 'list') {
+    const wantsAll = forwarded.includes('--all') || forwarded.includes('--all-worktrees');
+    const wantsActive = forwarded.includes('--active') || forwarded.includes('--active-only');
+    if (!wantsAll && !wantsActive) {
+      forwarded = [...forwarded, '--active'];
+    }
+  }
+
+  await withStackEnv({
+    stackName,
+    fn: async ({ env }) => {
+      await run(process.execPath, [join(rootDir, 'scripts', 'worktrees.mjs'), ...forwarded], { cwd: rootDir, env });
+    },
+  });
+}
+
+export async function cmdAuth({ rootDir, stackName, args }) {
+  // Forward to scripts/auth.mjs under the stack env.
+  // This makes `hstack stack auth <name> ...` resolve CLI home/urls for that stack.
+  const forwarded = args[0] === '--' ? args.slice(1) : args;
+  const extraEnv = await getRuntimePortExtraEnv(stackName);
+  await withStackEnv({
+    stackName,
+    ...(extraEnv ? { extraEnv } : {}),
+    fn: async ({ env }) => {
+      await run(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), ...forwarded], { cwd: rootDir, env });
+    },
+  });
+}
+
+export async function cmdListStacks() {
+  try {
+    const names = (await listAllStackNames()).filter((n) => n !== 'main');
+    if (!names.length) {
+      console.log('[stack] no stacks found');
+      return;
+    }
+    console.log('[stack] stacks:');
+    for (const n of names) {
+      console.log(`- ${n}`);
+    }
+  } catch {
+    console.log('[stack] no stacks found');
+  }
+}

package/scripts/stack/help_text.mjs

@@ -0,0 +1,110 @@
+const STACK_HELP_USAGE_LINES = [
+  'hstack stack new <name> [--port=NNN] [--server=happier-server|happier-server-light] [--repo=default|dev|<owner/...>|<path>] [--db-provider=pglite|sqlite|postgres|mysql] [--database-url=<url>] [--interactive] [--non-interactive] [--copy-auth-from=<stack>] [--no-copy-auth] [--force-port] [--json]',
+  'hstack stack edit <name> --interactive [--json]',
+  'hstack stack list [--json]',
+  'hstack stack audit [--fix] [--fix-main] [--fix-ports] [--fix-workspace] [--fix-paths] [--unpin-ports] [--unpin-ports-except=stack1,stack2] [--json]',
+  'hstack stack archive <name> [--dry-run] [--date=YYYY-MM-DD] [--json]',
+  'hstack stack duplicate <from> <to> [--duplicate-worktrees] [--deps=none|link|install|link-or-install] [--json]',
+  'hstack stack info <name> [--json]',
+  'hstack stack pr <name> --repo=<pr-url|number> [--server-flavor=light|full] [--dev|--start] [--json] [-- ...]',
+  'hstack stack create-dev-auth-seed [name] [--server=happier-server|happier-server-light] [--login|--no-login] [--skip-default-seed] [--non-interactive] [--json]',
+  'hstack stack daemon <name> start|stop|restart|status [--json]',
+  'hstack stack happier <name> [-- ...]',
+  'hstack stack env <name> set KEY=VALUE [KEY2=VALUE2...] | unset KEY [KEY2...] | get KEY | list | path [--json]',
+  'hstack stack auth <name> status|login|copy-from [--json]',
+  'hstack stack dev <name> [-- ...]',
+  'hstack stack start <name> [-- ...]',
+  'hstack stack build <name> [-- ...]',
+  'hstack stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--chunks|--no-chunks] [--chunking=auto|head-slice|commit-window] [--chunk-max-files=N] [--json]',
+  'hstack stack typecheck <name> [component...] [--json]',
+  'hstack stack lint <name> [component...] [--json]',
+  'hstack stack test <name> [component...] [--json]',
+  'hstack stack doctor <name> [-- ...]',
+  'hstack stack mobile <name> [-- ...]',
+  'hstack stack mobile:install <name> [--name="Happier (exp1)"] [--device=...] [--json]',
+  'hstack stack mobile-dev-client <name> --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
+  'hstack stack resume <name> <sessionId...> [--json]',
+  'hstack stack stop <name> [--aggressive] [--sweep-owned] [--no-docker] [--json]',
+  'hstack stack code <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]',
+  'hstack stack cursor <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]',
+  'hstack stack open <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]   # prefer Cursor, else VS Code',
+  'hstack stack srv <name> -- status|use ...',
+  'hstack stack wt <name> -- <wt args...>',
+  'hstack stack tailscale:status|enable|disable|url <name> [-- ...]',
+  'hstack stack service <name> <install|uninstall|status|start|stop|restart|enable|disable|logs|tail>',
+  'hstack stack service:* <name>   # legacy alias',
+];
+
+export const STACK_HELP_COMMANDS = [
+  'new',
+  'edit',
+  'list',
+  'audit',
+  'archive',
+  'duplicate',
+  'info',
+  'pr',
+  'create-dev-auth-seed',
+  'daemon',
+  'eas',
+  'happier',
+  'env',
+  'auth',
+  'dev',
+  'start',
+  'build',
+  'review',
+  'typecheck',
+  'lint',
+  'test',
+  'doctor',
+  'mobile',
+  'mobile:install',
+  'mobile-dev-client',
+  'resume',
+  'stop',
+  'code',
+  'cursor',
+  'open',
+  'srv',
+  'wt',
+  'tailscale:*',
+  'service:*',
+];
+
+const STACK_HELP_USAGE_BY_CMD = (() => {
+  const map = new Map();
+  for (const line of STACK_HELP_USAGE_LINES) {
+    const parts = line.trim().split(/\s+/);
+    if (parts[0] !== 'hstack' || parts[1] !== 'stack') continue;
+    const command = parts[2] ?? '';
+    if (command) map.set(command, line);
+  }
+  return map;
+})();
+
+export function getStackHelpUsageLine(cmd) {
+  const command = (cmd ?? '').toString().trim();
+  if (!command) return null;
+  return STACK_HELP_USAGE_BY_CMD.get(command) ?? null;
+}
+
+export function renderStackRootHelpText() {
+  return ['[stack] usage:', ...STACK_HELP_USAGE_LINES.map((line) => `  ${line}`)].join('\n');
+}
+
+export function renderStackSubcommandHelpText(cmd) {
+  const command = (cmd ?? '').toString().trim();
+  if (!command) return null;
+
+  const lines = [];
+  const direct = STACK_HELP_USAGE_BY_CMD.get(command);
+  if (direct) lines.push(direct);
+  else if (command.startsWith('tailscale:')) lines.push(STACK_HELP_USAGE_BY_CMD.get('tailscale:status|enable|disable|url'));
+  else if (command.startsWith('service:')) lines.push(STACK_HELP_USAGE_BY_CMD.get('service:*') || STACK_HELP_USAGE_BY_CMD.get('service'));
+
+  const filtered = lines.filter(Boolean);
+  if (!filtered.length) return null;
+
+  return [`[stack ${command}] usage:`, ...filtered.map((line) => `  ${line}`), '', 'see also:', '  hstack stack --help'].join('\n');
+}

package/scripts/stack/port_reservation.mjs

@@ -0,0 +1,74 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readTextOrEmpty } from '../utils/fs/ops.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from '../utils/net/ports.mjs';
+import { getStacksStorageRoot } from '../utils/paths/paths.mjs';
+import { parseEnvToObject } from '../utils/env/dotenv.mjs';
+import { coercePort, listPortsFromEnvObject, readPinnedServerPortFromEnvFile, STACK_RESERVED_PORT_KEYS } from '../utils/server/port.mjs';
+
+const readExistingEnv = readTextOrEmpty;
+
+export function getDefaultPortStart(stackName = null) {
+  const raw = process.env.HAPPIER_STACK_STACK_PORT_START?.trim() ? process.env.HAPPIER_STACK_STACK_PORT_START.trim() : '';
+  // Default port strategy:
+  // - main historically lives at 3005
+  // - non-main stacks should avoid 3005 to reduce accidental collisions/confusion
+  const target = (stackName ?? '').toString().trim() || (process.env.HAPPIER_STACK_STACK ?? '').trim() || 'main';
+  const fallback = target === 'main' ? 3005 : 3009;
+  const n = raw ? Number(raw) : fallback;
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export async function isPortFree(port, { host = '127.0.0.1' } = {}) {
+  return await isTcpPortFree(port, { host });
+}
+
+export async function pickNextFreePort(startPort, { reservedPorts = new Set(), host = '127.0.0.1' } = {}) {
+  try {
+    return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(msg.replace(/^\[local\]/, '[stack]'));
+  }
+}
+
+export async function readPortFromEnvFile(envPath) {
+  return await readPinnedServerPortFromEnvFile(envPath);
+}
+
+async function readPortsFromEnvFile(envPath) {
+  const raw = await readExistingEnv(envPath);
+  if (!raw.trim()) return [];
+  const parsed = parseEnvToObject(raw);
+  return listPortsFromEnvObject(parsed, STACK_RESERVED_PORT_KEYS);
+}
+
+export async function collectReservedStackPorts({ excludeStackName = null } = {}) {
+  const reserved = new Set();
+  const roots = [getStacksStorageRoot()];
+
+  for (const root of roots) {
+    let entries = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const name = entry.name;
+      if (excludeStackName && name === excludeStackName) continue;
+      const envPath = join(root, name, 'env');
+      // eslint-disable-next-line no-await-in-loop
+      const ports = await readPortsFromEnvFile(envPath);
+      for (const port of ports) {
+        const coerced = coercePort(port);
+        if (coerced) reserved.add(coerced);
+      }
+    }
+  }
+
+  return reserved;
+}

package/scripts/stack/repo_checkout_resolution.mjs

@@ -0,0 +1,31 @@
+import { isAbsolute, resolve } from 'node:path';
+import { createWorktree, resolveComponentSpecToDir } from '../utils/git/worktrees.mjs';
+import { coerceHappyMonorepoRootFromPath, getRepoDir, getWorkspaceDir } from '../utils/paths/paths.mjs';
+
+export async function resolveRequestedRepoCheckoutDir({ rootDir, repoSelection, remoteName, defaultRepoDir = '' }) {
+  if (!repoSelection) return '';
+
+  let resolved = '';
+  if (typeof repoSelection === 'object' && repoSelection.create) {
+    const uiPkgDir = await createWorktree({
+      rootDir,
+      component: 'happier-ui',
+      slug: repoSelection.slug,
+      remoteName,
+    });
+    resolved = uiPkgDir ? coerceHappyMonorepoRootFromPath(uiPkgDir) || uiPkgDir : '';
+  } else {
+    const spec = String(repoSelection ?? '').trim();
+    if (spec === 'default' || spec === 'main') {
+      resolved = defaultRepoDir || getRepoDir(rootDir, { ...process.env, HAPPIER_STACK_REPO_DIR: '' });
+    } else if (spec === 'active') {
+      resolved = getRepoDir(rootDir, process.env);
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: 'happier-ui', spec });
+      const abs = dir ? resolve(rootDir, dir) : isAbsolute(spec) ? spec : resolve(getWorkspaceDir(rootDir), spec);
+      resolved = coerceHappyMonorepoRootFromPath(abs) || abs;
+    }
+  }
+
+  return resolved;
+}