@happier-dev/stack 0.1.0-preview.17.1 → 0.1.0-preview.21.1

package/scripts/utils/cli/cli_registry.mjs

@@ -244,6 +244,27 @@ export function gethstackRegistry() {
       rootUsage: 'hstack self-host install|status|update|rollback|uninstall [--json]',
       description: 'Happier Self-Host guided install and lifecycle',
     },
+    {
+      name: 'remote',
+      kind: 'node',
+      scriptRelPath: 'scripts/remote_cmd.mjs',
+      rootUsage:
+        [
+          'hstack remote daemon setup --ssh <user@host> [--preview|--stable] [--channel <stable|preview>] [--service <user|none>] [--server-url=<url>] [--webapp-url=<url>] [--public-server-url=<url>] [--json]',
+          'hstack remote server setup --ssh <user@host> [--preview|--stable] [--channel <stable|preview>] [--mode <user|system>] [--env KEY=VALUE]... [--json]',
+        ],
+      description: 'Remote setup helpers (SSH daemon/server setup)',
+    },
+    {
+      name: 'providers',
+      kind: 'node',
+      scriptRelPath: 'scripts/providers_cmd.mjs',
+      rootUsage: [
+        'hstack providers list [--json]',
+        'hstack providers install --providers=<id1,id2> [--dry-run] [--force] [--json]',
+      ],
+      description: 'Install and manage provider CLIs',
+    },
     {
       name: 'auth',
       kind: 'node',

package/scripts/utils/cli/progress.mjs

@@ -27,6 +27,14 @@ function colorSpinner(frame) {
 }
 
 export function createStepPrinter({ enabled = true } = {}) {
+  if (!enabled) {
+    return {
+      start: () => {},
+      stop: () => {},
+      info: () => {},
+    };
+  }
+
   const tty = enabled && isTty();
   const frames = spinnerFrames();
   let timer = null;
@@ -138,4 +146,3 @@ export async function runCommandLogged({
   err.logPath = logPath;
   throw err;
 }
-

package/scripts/utils/cli/progress.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { runCommandLogged } from './progress.mjs';
+
+test('runCommandLogged does not print progress when showSteps=false', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happier-stack-progress-'));
+  const logPath = join(dir, 'log.txt');
+
+  const origWrite = process.stdout.write;
+  let stdout = '';
+  process.stdout.write = ((chunk, encoding, cb) => {
+    stdout += typeof chunk === 'string' ? chunk : chunk.toString(typeof encoding === 'string' ? encoding : 'utf8');
+    if (typeof cb === 'function') cb();
+    return true;
+  });
+
+  try {
+    const res = await runCommandLogged({
+      label: 'noop',
+      cmd: process.execPath,
+      args: ['-e', "process.stdout.write('hello')"],
+      cwd: process.cwd(),
+      env: process.env,
+      logPath,
+      showSteps: false,
+      quiet: true,
+    });
+
+    assert.equal(res.ok, true);
+    assert.equal(stdout, '');
+
+    const logged = await readFile(logPath, 'utf8');
+    assert.ok(logged.includes('hello'));
+  } finally {
+    process.stdout.write = origWrite;
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+

package/scripts/utils/dev/expo_dev.buildEnv.test.mjs

@@ -33,3 +33,20 @@ test('buildExpoDevEnv does not inject auth auto-restore env vars', () => {
   assert.equal(env.EXPO_PUBLIC_HAPPIER_STACK_DEV_AUTH_ENCRYPTION_MACHINE_KEY, undefined);
 });
 
+test('buildExpoDevEnv forces stack context in stack mode even when base env sets a different context', () => {
+  const baseEnv = {
+    ...process.env,
+    EXPO_PUBLIC_HAPPY_SERVER_CONTEXT: 'custom',
+  };
+
+  const env = buildExpoDevEnv({
+    baseEnv,
+    apiServerUrl: 'http://localhost:3013',
+    wantDevClient: false,
+    wantWeb: true,
+    stackMode: true,
+    stackName: 'qa-agent-2',
+  });
+
+  assert.equal(env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT, 'stack');
+});

package/scripts/utils/dev/expo_dev.mjs

@@ -10,7 +10,7 @@ import {
   writePidState,
 } from '../expo/expo.mjs';
 import { pickExpoDevMetroPort } from '../expo/metro_ports.mjs';
-import { recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
+import { isPidAlive, recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
 import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
 import { expoSpawn } from '../expo/command.mjs';
 import { resolveMobileExpoConfig } from '../mobile/config.mjs';
@@ -204,6 +204,10 @@ function expoModeLabel({ wantWeb, wantDevClient }) {
   return 'disabled';
 }
 
+function normalizeApiServerUrl(raw) {
+  return String(raw ?? '').trim().replace(/\/+$/, '');
+}
+
 export function buildExpoDevEnv({
   baseEnv,
   apiServerUrl,
@@ -229,7 +233,7 @@ export function buildExpoDevEnv({
     : apiServerUrl;
 
   env.EXPO_PUBLIC_HAPPY_SERVER_URL = effectiveApiServerUrl;
-  if (stackMode && !env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT) {
+  if (stackMode) {
     env.EXPO_PUBLIC_HAPPY_SERVER_CONTEXT = 'stack';
   }
   env.EXPO_PUBLIC_DEBUG = env.EXPO_PUBLIC_DEBUG ?? '1';
@@ -314,6 +318,7 @@ export async function ensureDevExpoServer({
 
   const running = await isStateProcessRunning(paths.statePath);
   const alreadyRunning = Boolean(running.running);
+  const desiredApiServerUrl = normalizeApiServerUrl(apiServerUrl);
 
   // Resolve Tailscale forwarding preference
   const wantTailscale = resolveExpoTailscaleEnabled({ env: baseEnv, expoTailscale });
@@ -344,8 +349,25 @@ export async function ensureDevExpoServer({
     }).catch(() => {});
   };
 
-  if (alreadyRunning && !restart) {
-    const pid = Number(running.state?.pid);
+  const runningStateApiServerUrl = normalizeApiServerUrl(running.state?.apiServerUrl);
+  const shouldRestartForApiServerMismatch =
+    alreadyRunning &&
+    !restart &&
+    stackMode &&
+    wantWeb &&
+    desiredApiServerUrl &&
+    runningStateApiServerUrl !== desiredApiServerUrl;
+  // In stack mode, never adopt "running by port probe only" state. It may belong to a
+  // different stack/session and has no reliable owned pid for lifecycle control.
+  const shouldRestartForPortFallbackInStackMode =
+    alreadyRunning &&
+    !restart &&
+    stackMode &&
+    running.reason === 'port';
+
+  if (alreadyRunning && !restart && !shouldRestartForApiServerMismatch && !shouldRestartForPortFallbackInStackMode) {
+    const statePid = Number(running.state?.pid);
+    const pid = Number.isFinite(statePid) && statePid > 1 && isPidAlive(statePid) ? statePid : null;
     const port = Number(running.state?.port);
 
     // Capability check: refuse to spawn a second Expo, so if the existing process doesn't match the
@@ -369,12 +391,19 @@ export async function ensureDevExpoServer({
       ok: true,
       skipped: true,
       reason: 'already_running',
-      pid: Number.isFinite(pid) ? pid : null,
+      pid: Number.isFinite(pid) && pid > 1 ? pid : null,
       port: Number.isFinite(port) ? port : null,
       mode: expoModeLabel({ wantWeb, wantDevClient }),
     };
   }
 
+  if (shouldRestartForApiServerMismatch && !quiet) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `[local] expo: restarting to align API server URL (running=${runningStateApiServerUrl || 'unset'}, wanted=${desiredApiServerUrl}).`
+    );
+  }
+
   const reservedMetroPorts = new Set();
 
   if (restart && running.state?.pid) {
@@ -457,6 +486,7 @@ export async function ensureDevExpoServer({
       webEnabled: wantWeb,
       devClientEnabled: wantDevClient,
       host,
+      apiServerUrl: desiredApiServerUrl || null,
       scheme: wantDevClient ? scheme : null,
       tailscaleEnabled: wantTailscale,
       tailscaleForwarderPid: tailscaleResult?.pid ?? null,

package/scripts/utils/dev/expo_dev_restart_port_reservation.test.mjs

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, mkdir, rm, writeFile, chmod } from 'node:fs/promises';
+import { mkdtemp, mkdir, rm, writeFile, chmod, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
@@ -42,6 +42,32 @@ function killProcessTreeByPid(pid) {
   }
 }
 
+function listenMetroStatusServer() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer((socket) => {
+      socket.once('data', () => {
+        socket.write(
+          'HTTP/1.1 200 OK\r\n' +
+            'Content-Type: text/plain\r\n' +
+            'Content-Length: 23\r\n' +
+            '\r\n' +
+            'packager-status:running'
+        );
+        socket.end();
+      });
+    });
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address();
+      if (!addr || typeof addr === 'string') {
+        server.close(() => reject(new Error('failed to resolve metro status server port')));
+        return;
+      }
+      resolve({ server, port: Number(addr.port) });
+    });
+  });
+}
+
 test('ensureDevExpoServer reserves prior metro port when restart cannot kill previous pid', async () => {
   const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-reserve-port-'));
   const children = [];
@@ -118,3 +144,156 @@ test('ensureDevExpoServer reserves prior metro port when restart cannot kill pre
     await rm(tmp, { recursive: true, force: true });
   }
 });
+
+test('ensureDevExpoServer restarts when running Expo state targets a different API server URL', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-restart-api-url-'));
+  const children = [];
+  let metro = null;
+  try {
+    const uiDir = join(tmp, 'ui');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+    await mkdir(join(uiDir, 'node_modules'), { recursive: true });
+    await writeFile(join(uiDir, 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n', 'utf-8');
+
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await writeFile(
+      expoBin,
+      [
+        '#!/usr/bin/env node',
+        "setInterval(() => {}, 1000);",
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    await chmod(expoBin, 0o755);
+
+    const status = await listenMetroStatusServer();
+    metro = status.server;
+    const priorPort = status.port;
+
+    const projectDir = uiDir;
+    const paths = getExpoStatePaths({
+      baseDir: tmp,
+      kind: 'expo-dev',
+      projectDir,
+      stateFileName: 'expo.state.json',
+    });
+    await writePidState(paths.statePath, {
+      pid: 999999,
+      port: priorPort,
+      uiDir,
+      projectDir,
+      startedAt: new Date().toISOString(),
+      webEnabled: true,
+      devClientEnabled: false,
+      host: 'lan',
+      apiServerUrl: 'http://localhost:3012',
+    });
+
+    const result = await ensureDevExpoServer({
+      startUi: true,
+      startMobile: false,
+      uiDir,
+      autostart: { baseDir: tmp },
+      baseEnv: {
+        ...process.env,
+        HAPPIER_STACK_EXPO_DEV_PORT: String(priorPort),
+      },
+      apiServerUrl: 'http://localhost:3014',
+      restart: false,
+      stackMode: true,
+      runtimeStatePath: null,
+      stackName: 'qa-agent-1',
+      envPath: join(tmp, 'stack.env'),
+      children,
+      quiet: true,
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.skipped, false);
+    assert.notEqual(result.port, priorPort);
+
+    const nextState = JSON.parse(await readFile(paths.statePath, 'utf-8'));
+    assert.equal(nextState.apiServerUrl, 'http://localhost:3014');
+  } finally {
+    for (const child of children) {
+      killProcessTreeByPid(child?.pid);
+    }
+    await new Promise((resolve) => metro?.close(() => resolve())).catch(() => {});
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('ensureDevExpoServer in stack mode does not adopt port-only fallback as already running', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-port-fallback-stack-mode-'));
+  const children = [];
+  let metro = null;
+  try {
+    const uiDir = join(tmp, 'ui');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+    await mkdir(join(uiDir, 'node_modules'), { recursive: true });
+    await writeFile(join(uiDir, 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n', 'utf-8');
+
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await writeFile(
+      expoBin,
+      [
+        '#!/usr/bin/env node',
+        "setInterval(() => {}, 1000);",
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    await chmod(expoBin, 0o755);
+
+    const status = await listenMetroStatusServer();
+    metro = status.server;
+    const priorPort = status.port;
+
+    const projectDir = uiDir;
+    const paths = getExpoStatePaths({
+      baseDir: tmp,
+      kind: 'expo-dev',
+      projectDir,
+      stateFileName: 'expo.state.json',
+    });
+    await writePidState(paths.statePath, {
+      pid: 999999,
+      port: priorPort,
+      uiDir,
+      projectDir,
+      startedAt: new Date().toISOString(),
+      webEnabled: true,
+      devClientEnabled: false,
+      host: 'lan',
+      apiServerUrl: 'http://localhost:3014',
+    });
+
+    const result = await ensureDevExpoServer({
+      startUi: true,
+      startMobile: false,
+      uiDir,
+      autostart: { baseDir: tmp },
+      baseEnv: {
+        ...process.env,
+        HAPPIER_STACK_EXPO_DEV_PORT: String(priorPort),
+      },
+      apiServerUrl: 'http://localhost:3014',
+      restart: false,
+      stackMode: true,
+      runtimeStatePath: null,
+      stackName: 'qa-agent-4',
+      envPath: join(tmp, 'stack.env'),
+      children,
+      quiet: true,
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.skipped, false);
+    assert.notEqual(result.port, priorPort);
+  } finally {
+    for (const child of children) {
+      killProcessTreeByPid(child?.pid);
+    }
+    await new Promise((resolve) => metro?.close(() => resolve())).catch(() => {});
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/dev/expo_dev_runtime_metadata.test.mjs

@@ -0,0 +1,126 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtemp, mkdir, rm, writeFile, chmod } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ensureDevExpoServer } from './expo_dev.mjs';
+import { getExpoStatePaths, writePidState } from '../expo/expo.mjs';
+import { readStackRuntimeStateFile } from '../stack/runtime_state.mjs';
+
+function listen(server) {
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+}
+
+function close(server) {
+  return new Promise((resolve) => server.close(() => resolve()));
+}
+
+function killProcessTreeByPid(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return;
+  try {
+    process.kill(-n, 'SIGKILL');
+  } catch {
+    try {
+      process.kill(n, 'SIGKILL');
+    } catch {
+      // ignore
+    }
+  }
+}
+
+test('ensureDevExpoServer in stack mode starts managed Expo instead of adopting port-fallback state', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-expo-runtime-meta-'));
+  const uiDir = join(tmp, 'ui');
+  const projectDir = uiDir;
+  const runtimeStatePath = join(tmp, 'stack.runtime.json');
+  const envPath = join(tmp, 'stack.env');
+  const children = [];
+  const metro = http.createServer((req, res) => {
+    if (req.url === '/status') {
+      res.writeHead(200, { 'content-type': 'text/plain' });
+      res.end('packager-status:running');
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'text/plain' });
+    res.end('ok');
+  });
+
+  try {
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+    await mkdir(join(uiDir, 'node_modules'), { recursive: true });
+    await writeFile(join(uiDir, 'package.json'), JSON.stringify({ name: 'fake-ui', private: true }) + '\n', 'utf-8');
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await writeFile(
+      expoBin,
+      [
+        '#!/usr/bin/env node',
+        "setInterval(() => {}, 1000);",
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    await chmod(expoBin, 0o755);
+
+    await listen(metro);
+    const addr = metro.address();
+    assert.ok(addr && typeof addr === 'object' && typeof addr.port === 'number');
+    const metroPort = addr.port;
+
+    const paths = getExpoStatePaths({
+      baseDir: tmp,
+      kind: 'expo-dev',
+      projectDir,
+      stateFileName: 'expo.state.json',
+    });
+    await writePidState(paths.statePath, {
+      pid: 999999, // intentionally stale
+      port: metroPort,
+      uiDir,
+      projectDir,
+      startedAt: new Date().toISOString(),
+      webEnabled: true,
+      devClientEnabled: false,
+      host: 'lan',
+      apiServerUrl: 'http://127.0.0.1:3009',
+    });
+
+    const result = await ensureDevExpoServer({
+      startUi: true,
+      startMobile: false,
+      uiDir,
+      expoProjectDir: projectDir,
+      autostart: { baseDir: tmp },
+      baseEnv: { ...process.env },
+      apiServerUrl: 'http://127.0.0.1:3009',
+      restart: false,
+      stackMode: true,
+      runtimeStatePath,
+      stackName: 'qa-agent-4',
+      envPath,
+      children,
+      quiet: true,
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.skipped, false);
+    assert.equal(Number.isFinite(Number(result.pid)) && Number(result.pid) > 1, true);
+    assert.notEqual(result.port, metroPort);
+
+    const runtime = await readStackRuntimeStateFile(runtimeStatePath);
+    assert.ok(runtime && typeof runtime === 'object');
+    assert.equal(Number.isFinite(Number(runtime?.processes?.expoPid)) && Number(runtime?.processes?.expoPid) > 1, true);
+    assert.equal(runtime?.expo?.webPort, result.port);
+    assert.notEqual(runtime?.expo?.webPort, metroPort);
+  } finally {
+    for (const child of children) {
+      killProcessTreeByPid(child?.pid);
+    }
+    await close(metro).catch(() => {});
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/dev/expo_dev_verbose_logs.test.mjs

@@ -51,8 +51,15 @@ test('ensureDevExpoServer does not drop Expo output when spawnOptions stdio is i
       quiet: true,
     });
 
-    await delay(400);
-    const log = await readFile(teeFile, 'utf-8').catch(() => '');
+    // CI and local stacks can be noisy/slow (Corepack/Yarn probes, filesystem contention),
+    // so wait deterministically for the tee output instead of using a fixed delay.
+    const deadlineMs = Date.now() + 3000;
+    let log = '';
+    while (Date.now() < deadlineMs) {
+      log = await readFile(teeFile, 'utf-8').catch(() => '');
+      if (/hello-from-fake-expo/.test(log)) break;
+      await delay(100);
+    }
     assert.match(log, /hello-from-fake-expo/);
   } finally {
     await rm(tmp, { recursive: true, force: true });

package/scripts/utils/mobile/dev_client_install_invocation.mjs

@@ -0,0 +1,68 @@
+import { join } from 'node:path';
+
+import { parseArgs } from '../cli/args.mjs';
+import { defaultDevClientIdentity } from './identifiers.mjs';
+
+function normalizePortArg(raw) {
+  const s = String(raw ?? '').trim();
+  if (!s) return '';
+  const n = Number(s);
+  if (!Number.isFinite(n) || n <= 0) return '';
+  return String(Math.floor(n));
+}
+
+export function buildMobileDevClientInstallInvocation({
+  rootDir,
+  argv,
+  baseEnv = process.env,
+} = {}) {
+  const r = String(rootDir ?? '').trim();
+  if (!r) {
+    throw new Error('[mobile-dev-client] missing rootDir');
+  }
+
+  const a = Array.isArray(argv) ? argv : [];
+  const { flags, kv } = parseArgs(a);
+
+  const device = (kv.get('--device') ?? '').toString();
+  const clean = flags.has('--clean');
+  const configuration = (kv.get('--configuration') ?? 'Debug').toString() || 'Debug';
+  const port = normalizePortArg(kv.get('--port'));
+
+  const user = (baseEnv.USER ?? baseEnv.USERNAME ?? 'user').toString();
+  const identity = defaultDevClientIdentity({ user });
+
+  const mobileScript = join(r, 'scripts', 'mobile.mjs');
+
+  const nodeArgs = [
+    mobileScript,
+    '--app-env=development',
+    `--ios-app-name=${identity.iosAppName}`,
+    `--ios-bundle-id=${identity.iosBundleId}`,
+    `--scheme=${identity.scheme}`,
+    ...(port ? [`--port=${port}`] : []),
+    '--prebuild',
+    ...(clean ? ['--clean'] : []),
+    '--run-ios',
+    `--configuration=${configuration}`,
+    '--no-metro',
+    ...(device ? [`--device=${device}`] : []),
+  ];
+
+  const env = {
+    ...baseEnv,
+    EXPO_APP_SCHEME: identity.scheme,
+    EXPO_PUBLIC_HAPPY_STORAGE_SCOPE: baseEnv.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE ?? '',
+  };
+
+  return {
+    nodeArgs,
+    env,
+    identity,
+    device,
+    clean,
+    configuration,
+    port,
+  };
+}
+

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

@@ -0,0 +1,27 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildMobileDevClientInstallInvocation } from './dev_client_install_invocation.mjs';
+
+test('buildMobileDevClientInstallInvocation forwards --port to mobile.mjs args', async () => {
+  const invocation = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install', '--port=14362'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(Array.isArray(invocation.nodeArgs), 'expected nodeArgs array');
+  assert.ok(invocation.nodeArgs.includes('--port=14362'), 'expected --port to be forwarded to mobile.mjs');
+});
+
+test('buildMobileDevClientInstallInvocation omits --port when not provided', async () => {
+  const invocation = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(Array.isArray(invocation.nodeArgs), 'expected nodeArgs array');
+  assert.ok(!invocation.nodeArgs.some((a) => String(a).startsWith('--port=')), 'expected no --port arg by default');
+});
+

package/scripts/utils/server/port.mjs

@@ -26,8 +26,26 @@ export function coercePort(v) {
 
 export function resolveServerPortFromEnv({ env = process.env, defaultPort = 3005 } = {}) {
   const raw = (env.HAPPIER_STACK_SERVER_PORT ?? '').toString().trim() || '';
-  const n = raw ? Number(raw) : Number(defaultPort);
-  return Number.isFinite(n) && n > 0 ? n : Number(defaultPort);
+  const explicitPort = raw ? Number(raw) : NaN;
+  if (Number.isFinite(explicitPort) && explicitPort > 0) {
+    return explicitPort;
+  }
+
+  const serverUrlRaw = (env.HAPPIER_SERVER_URL ?? '').toString().trim();
+  if (serverUrlRaw) {
+    try {
+      const parsed = new URL(serverUrlRaw);
+      const urlPort = Number(parsed.port);
+      if (Number.isFinite(urlPort) && urlPort > 0) {
+        return urlPort;
+      }
+    } catch {
+      // Ignore invalid URL and use the default fallback below.
+    }
+  }
+
+  const fallback = Number(defaultPort);
+  return Number.isFinite(fallback) && fallback > 0 ? fallback : 3005;
 }
 
 export function listPortsFromEnvObject(env, keys) {