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

package/scripts/self_host_runtime.test.mjs

@@ -1,8 +1,10 @@
 import assert from 'node:assert/strict';
+import { createHash, generateKeyPairSync, sign } from 'node:crypto';
 import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
 import test from 'node:test';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 import {
   parseSelfHostInvocation,
@@ -16,6 +18,7 @@ import {
   renderUpdaterScheduledTaskWrapperPs1,
   renderUpdaterSystemdUnit,
   renderUpdaterSystemdTimerUnit,
+  buildUpdaterScheduledTaskCreateArgs,
   renderServerEnvFile,
   renderServerServiceUnit,
   renderSelfHostStatusText,
@@ -25,6 +28,49 @@ import {
   mergeEnvTextWithDefaults,
 } from './self_host_runtime.mjs';
 
+function b64(buf) {
+  return Buffer.from(buf).toString('base64');
+}
+
+function base64UrlToBuffer(value) {
+  const s = String(value ?? '')
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(Math.ceil(String(value ?? '').length / 4) * 4, '=');
+  return Buffer.from(s, 'base64');
+}
+
+function createMinisignKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const jwk = publicKey.export({ format: 'jwk' });
+  const rawPublicKey = base64UrlToBuffer(jwk.x);
+  assert.equal(rawPublicKey.length, 32);
+
+  const keyId = Buffer.from('0123456789abcdef', 'hex');
+  const publicKeyBytes = Buffer.concat([Buffer.from('Ed'), keyId, rawPublicKey]);
+  const pubkeyFile = `untrusted comment: minisign public key\n${b64(publicKeyBytes)}\n`;
+  return { pubkeyFile, keyId, privateKey };
+}
+
+function signMinisignMessage({ message, keyId, privateKey }) {
+  const signature = sign(null, message, privateKey);
+  const sigLineBytes = Buffer.concat([Buffer.from('Ed'), keyId, signature]);
+  const trustedComment = 'trusted comment: test';
+  const trustedSuffix = Buffer.from(trustedComment.slice('trusted comment: '.length), 'utf-8');
+  const globalSignature = sign(null, Buffer.concat([signature, trustedSuffix]), privateKey);
+  return [
+    'untrusted comment: signature from happier stack test',
+    b64(sigLineBytes),
+    trustedComment,
+    b64(globalSignature),
+    '',
+  ].join('\n');
+}
+
+function sha256Hex(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
 test('parseSelfHostInvocation accepts optional self-host prefix', () => {
   const parsed = parseSelfHostInvocation(['self-host', 'install', '--channel=preview']);
   assert.equal(parsed.subcommand, 'install');
@@ -54,6 +100,81 @@ test('pickReleaseAsset returns matching archive and checksum assets', () => {
   assert.equal(picked.signatureUrl, 'https://example.test/checksums.txt.minisig');
 });
 
+test('self-host release installer reports archive source url', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  const staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.3-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'ok', 'utf-8');
+
+  const binaryName = 'happier-server';
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho ok\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await (await import('node:fs/promises')).readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const archiveUrl = `data:application/octet-stream;base64,${archiveBytes.toString('base64')}`;
+  const checksumsUrl = `data:text/plain,${encodeURIComponent(checksumsText)}`;
+  const sigUrl = `data:text/plain,${encodeURIComponent(sigFile)}`;
+
+  const bundle = {
+    version: '1.2.3-preview.1',
+    archive: { name: archiveName, url: archiveUrl },
+    checksums: { name: `checksums-happier-server-v1.2.3-preview.1.txt`, url: checksumsUrl },
+    checksumsSig: { name: `checksums-happier-server-v1.2.3-preview.1.txt.minisig`, url: sigUrl },
+  };
+
+  const installRoot = join(tmp, 'install');
+  const config = {
+    platform: process.platform,
+    dataDir: join(installRoot, 'data'),
+    versionsDir: join(installRoot, 'versions'),
+    serverBinaryPath: join(installRoot, 'bin', binaryName),
+    serverPreviousBinaryPath: join(installRoot, 'bin', `${binaryName}.previous`),
+  };
+
+  const mod = await import('./self_host_runtime.mjs');
+  assert.equal(typeof mod.installSelfHostBinaryFromBundle, 'function');
+
+  const result = await mod.installSelfHostBinaryFromBundle({
+    bundle,
+    binaryName,
+    config,
+    pubkeyFile,
+  });
+
+  assert.equal(result.version, '1.2.3-preview.1');
+  assert.equal(result.source, archiveUrl);
+});
+
 test('pickReleaseAsset rejects releases missing minisign signature assets', () => {
   assert.throws(() => {
     pickReleaseAsset({
@@ -244,6 +365,7 @@ test('renderUpdaterLaunchdPlistXml runs self-host update without keepalive loops
 
   assert.match(plist, /<key>RunAtLoad<\/key>\s*<true\/>/);
   assert.match(plist, /<key>StartInterval<\/key>\s*<integer>3600<\/integer>/);
+  assert.doesNotMatch(plist, /<key>StartCalendarInterval<\/key>/);
   assert.doesNotMatch(plist, /<key>KeepAlive<\/key>/);
   assert.match(plist, /<key>PATH<\/key>/);
   assert.match(plist, /<string>\/Users\/me\/\.happier\/bin\/hstack<\/string>/);
@@ -254,16 +376,44 @@ test('renderUpdaterLaunchdPlistXml runs self-host update without keepalive loops
   assert.match(plist, /<string>--non-interactive<\/string>/);
 });
 
+test('renderUpdaterLaunchdPlistXml supports daily time-of-day schedules', () => {
+  const plist = renderUpdaterLaunchdPlistXml({
+    updaterLabel: 'happier-server-updater',
+    hstackPath: '/Users/me/.happier/bin/hstack',
+    channel: 'stable',
+    mode: 'user',
+    at: '03:15',
+    workingDirectory: '/Users/me/.happier/self-host',
+    stdoutPath: '/Users/me/.happier/self-host/logs/updater.out.log',
+    stderrPath: '/Users/me/.happier/self-host/logs/updater.err.log',
+  });
+  assert.match(plist, /<key>StartCalendarInterval<\/key>/);
+  assert.match(plist, /<key>Hour<\/key>\s*<integer>3<\/integer>/);
+  assert.match(plist, /<key>Minute<\/key>\s*<integer>15<\/integer>/);
+  assert.doesNotMatch(plist, /<key>StartInterval<\/key>/);
+});
+
 test('renderUpdaterSystemdTimerUnit schedules periodic updater runs', () => {
   const timer = renderUpdaterSystemdTimerUnit({
     updaterLabel: 'happier-server-updater',
     intervalMinutes: 60,
   });
   assert.match(timer, /OnUnitActiveSec=60m/);
+  assert.doesNotMatch(timer, /OnCalendar=/);
   assert.match(timer, /Unit=happier-server-updater\.service/);
   assert.match(timer, /WantedBy=timers\.target/);
 });
 
+test('renderUpdaterSystemdTimerUnit supports daily time-of-day schedules', () => {
+  const timer = renderUpdaterSystemdTimerUnit({
+    updaterLabel: 'happier-server-updater',
+    at: '03:15',
+  });
+  assert.match(timer, /OnCalendar=\*-\*-\*\s+03:15:00/);
+  assert.doesNotMatch(timer, /OnUnitActiveSec=/);
+  assert.match(timer, /Unit=happier-server-updater\.service/);
+});
+
 test('renderUpdaterScheduledTaskWrapperPs1 runs self-host update without node dependencies', () => {
   const wrapper = renderUpdaterScheduledTaskWrapperPs1({
     updaterLabel: 'happier-server-updater',
@@ -281,6 +431,18 @@ test('renderUpdaterScheduledTaskWrapperPs1 runs self-host update without node de
   );
 });
 
+test('buildUpdaterScheduledTaskCreateArgs uses DAILY schedule when at is provided', () => {
+  const args = buildUpdaterScheduledTaskCreateArgs({
+    backend: 'schtasks-user',
+    taskName: 'Happier\\\\happier-server-updater',
+    definitionPath: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\services\\\\happier-server-updater.ps1',
+    at: '03:15',
+  });
+  assert.ok(args.includes('DAILY'));
+  assert.ok(args.includes('03:15'));
+  assert.equal(args.includes('MINUTE'), false);
+});
+
 test('mergeEnvTextWithDefaults preserves overrides while backfilling new default keys', () => {
   const defaults = renderServerEnvFile({
     port: 3005,
@@ -403,40 +565,40 @@ test('buildSelfHostDoctorChecks flags missing ui-web bundle when state expects u
 test('normalizeSelfHostAutoUpdateState upgrades legacy boolean config to structured config', () => {
   assert.deepEqual(
     normalizeSelfHostAutoUpdateState({ autoUpdate: true }, { fallbackIntervalMinutes: 1440 }),
-    { enabled: true, intervalMinutes: 1440 },
+    { enabled: true, intervalMinutes: 1440, at: '' },
   );
   assert.deepEqual(
     normalizeSelfHostAutoUpdateState({ autoUpdate: false }, { fallbackIntervalMinutes: 1440 }),
-    { enabled: false, intervalMinutes: 1440 },
+    { enabled: false, intervalMinutes: 1440, at: '' },
   );
 });
 
 test('normalizeSelfHostAutoUpdateState preserves explicit interval and bounds invalid values', () => {
   assert.deepEqual(
     normalizeSelfHostAutoUpdateState({ autoUpdate: { enabled: true, intervalMinutes: 60 } }, { fallbackIntervalMinutes: 1440 }),
-    { enabled: true, intervalMinutes: 60 },
+    { enabled: true, intervalMinutes: 60, at: '' },
   );
   assert.deepEqual(
     normalizeSelfHostAutoUpdateState({ autoUpdate: { enabled: true, intervalMinutes: 0 } }, { fallbackIntervalMinutes: 1440 }),
-    { enabled: true, intervalMinutes: 1440 },
+    { enabled: true, intervalMinutes: 1440, at: '' },
   );
   assert.deepEqual(
     normalizeSelfHostAutoUpdateState({}, { fallbackIntervalMinutes: 1440 }),
-    { enabled: false, intervalMinutes: 1440 },
+    { enabled: false, intervalMinutes: 1440, at: '' },
   );
 });
 
 test('decideSelfHostAutoUpdateReconcile maps configured state to an install/uninstall action', () => {
   assert.deepEqual(
     decideSelfHostAutoUpdateReconcile({ autoUpdate: true }, { fallbackIntervalMinutes: 1440 }),
-    { action: 'install', enabled: true, intervalMinutes: 1440 },
+    { action: 'install', enabled: true, intervalMinutes: 1440, at: '' },
   );
   assert.deepEqual(
     decideSelfHostAutoUpdateReconcile({ autoUpdate: false }, { fallbackIntervalMinutes: 1440 }),
-    { action: 'uninstall', enabled: false, intervalMinutes: 1440 },
+    { action: 'uninstall', enabled: false, intervalMinutes: 1440, at: '' },
   );
   assert.deepEqual(
     decideSelfHostAutoUpdateReconcile({}, { fallbackIntervalMinutes: 1440 }),
-    { action: 'uninstall', enabled: false, intervalMinutes: 1440 },
+    { action: 'uninstall', enabled: false, intervalMinutes: 1440, at: '' },
   );
 });

package/scripts/stack/help_text.mjs

@@ -6,7 +6,7 @@ const STACK_HELP_USAGE_LINES = [
   '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 pr <name> --repo=<pr-url|number> [--server-flavor=light|full] [--dev|--start] [--reuse] [--update] [--force] [--background] [--mobile] [--expo-tailscale] [--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> [-- ...]',

package/scripts/stack.mjs

@@ -1622,7 +1622,7 @@ async function cmdPrStack({ rootDir, argv }) {
         '[stack] usage:',
         '  hstack stack pr <name> --repo=<pr-url|number> [--dev|--start]',
         '    [--seed-auth] [--copy-auth-from=<stack>] [--link-auth] [--with-infra] [--auth-force]',
-        '    [--remote=upstream] [--deps=none|link|install|link-or-install] [--update] [--force] [--background]',
+        '    [--remote=upstream] [--deps=none|link|install|link-or-install] [--reuse] [--update] [--force] [--background]',
         '    [--mobile]         # also start Expo dev-client Metro for mobile',
         '    [--expo-tailscale] # forward Expo to Tailscale interface for remote access',
         '    [--json] [-- <stack dev/start args...>]',
@@ -1639,6 +1639,7 @@ async function cmdPrStack({ rootDir, argv }) {
         '',
 	        'notes:',
 	        '  - This composes existing commands: `hstack stack new`, `hstack stack wt ...`, and `hstack stack auth ...`',
+	        '  - `--reuse` reuses an existing PR stack (otherwise `stack pr` fails closed if the stack already exists)',
 	        '  - For auth seeding, pass `--seed-auth` and optionally `--copy-auth-from=dev-auth` (or main)',
 	        '  - `--link-auth` symlinks auth files instead of copying (keeps credentials in sync, but reduces isolation)',
 	      ].join('\n'),

package/scripts/stack_pr_help_cmd.test.mjs

@@ -0,0 +1,38 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+
+import { getStackRootFromMeta, hstackBinPath, runNodeCapture } from './testkit/auth_testkit.mjs';
+
+test('hstack stack pr --help surfaces --reuse (supported flag)', async () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+
+  const env = {
+    ...process.env,
+    // Prevent env.mjs from auto-loading a real machine stack env file (keeps the test hermetic).
+    HAPPIER_STACK_STACK: 'test-stack',
+    HAPPIER_STACK_ENV_FILE: join(rootDir, 'scripts', 'nonexistent-env'),
+  };
+
+  const res = await runNodeCapture([hstackBinPath(rootDir), 'stack', 'pr', '--help'], { cwd: rootDir, env });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstderr:\n${res.stderr}\nstdout:\n${res.stdout}`);
+  assert.match(res.stdout, /--reuse/, `expected stack pr help to include --reuse\nstdout:\n${res.stdout}`);
+});
+
+test('hstack stack --help shows --reuse on the stack pr usage line', async () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+
+  const env = {
+    ...process.env,
+    HAPPIER_STACK_STACK: 'test-stack',
+    HAPPIER_STACK_ENV_FILE: join(rootDir, 'scripts', 'nonexistent-env'),
+  };
+
+  const res = await runNodeCapture([hstackBinPath(rootDir), 'stack', '--help'], { cwd: rootDir, env });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstderr:\n${res.stderr}\nstdout:\n${res.stdout}`);
+  assert.match(
+    res.stdout,
+    /hstack stack pr[^\n]*--reuse\b/,
+    `expected stack root help to include --reuse on the stack pr usage line\nstdout:\n${res.stdout}`
+  );
+});

package/scripts/stop.mjs

@@ -57,7 +57,7 @@ async function listAllStackNames() {
 async function main() {
   const rootDir = getRootDir(import.meta.url);
   const argv = process.argv.slice(2);
-  const { flags, kv } = parseArgs(argv);
+  const { flags, kv: argsKv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
 
   if (wantsHelp(argv, { flags })) {
@@ -65,7 +65,7 @@ async function main() {
     return;
   }
 
-  const exceptStacks = new Set(parseCsv(kv.get('--except-stacks')));
+  const exceptStacks = new Set(parseCsv(argsKv.get('--except-stacks')));
   const yes = flags.has('--yes');
   const aggressive = flags.has('--aggressive');
   const sweepOwned = flags.has('--sweep-owned');
@@ -187,4 +187,3 @@ main().catch((err) => {
   console.error('[stop] failed:', err);
   process.exit(1);
 });
-

package/scripts/utils/auth/orchestrated_stack_auth_flow.mjs

@@ -19,15 +19,76 @@ function appendCauseText(baseMessage, cause) {
   return `${msg}\n\n[auth] Cause: ${c}`;
 }
 
+async function readTextWithTimeout(path, { timeoutMs = 1200 } = {}) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const res = await fetch(path, { signal: controller.signal });
+    clearTimeout(timer);
+    return { ok: res.ok, status: res.status };
+  } catch (error) {
+    return { ok: false, status: 0, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function formatPidStatus(label, pidRaw) {
+  const pid = Number(pidRaw);
+  if (!Number.isFinite(pid) || pid <= 1) return `[auth] ${label}: unavailable`;
+  return `[auth] ${label}: ${pid} (${isPidAlive(pid) ? 'alive' : 'stale/dead'})`;
+}
+
+function formatLogPath(label, logPath) {
+  const p = String(logPath ?? '').trim();
+  return p ? `[auth] ${label}: ${p}` : `[auth] ${label}: unavailable`;
+}
+
+async function appendRuntimeHealthDiagnostics(message, stackName) {
+  const name = String(stackName ?? '').trim() || 'main';
+  const statePath = getStackRuntimeStatePath(name);
+
+  const state = await readStackRuntimeStateFile(statePath).catch(() => null);
+  if (!state || typeof state !== 'object') {
+    return `${message}\n\n[auth] Stack runtime state unavailable: ${statePath}`;
+  }
+
+  const serverPort = Number(state?.ports?.server);
+  let serverHealth = 'not configured';
+  if (Number.isFinite(serverPort) && serverPort > 0) {
+    const probe = await readTextWithTimeout(`http://127.0.0.1:${serverPort}/health`, { timeoutMs: 1200 });
+    if (probe.ok) {
+      serverHealth = `HTTP ${probe.status}`;
+    } else if (probe.error) {
+      serverHealth = probe.error;
+    } else {
+      serverHealth = `HTTP ${probe.status}`;
+    }
+  }
+
+  const runtimeSummary = [
+    `[auth] Stack runtime path: ${statePath}`,
+    formatPidStatus('ownerPid', state?.ownerPid),
+    formatPidStatus('serverPid', state?.processes?.serverPid),
+    formatPidStatus('expoPid', state?.processes?.expoPid),
+    formatPidStatus('expoTailscaleForwarderPid', state?.processes?.expoTailscaleForwarderPid),
+    `[auth] server port: ${Number.isFinite(serverPort) && serverPort > 0 ? serverPort : 'unconfigured'}`,
+    `[auth] server health: ${serverHealth}`,
+    formatLogPath('runner log', state?.logs?.runner),
+    formatLogPath('cli log', state?.logs?.cli),
+  ].join('\n');
+
+  return `${String(message ?? '').trim()}\n\n${runtimeSummary}`;
+}
+
 async function appendRunnerLogTailDiagnostics({ message, stackName, lines = 140 }) {
   const base = String(message ?? '').trim();
   const logPath = await resolveRunnerLogPathFromRuntime({ stackName, waitMs: 1000, pollMs: 100 }).catch(() => '');
-  if (!logPath) return base;
+  const withState = await appendRuntimeHealthDiagnostics(base, stackName).catch(() => base);
+  if (!logPath) return withState;
   const tail = await readLastLines(logPath, lines).catch(() => null);
   if (!tail || !String(tail).trim()) {
-    return `${base}\n\n[auth] Stack runner log: ${logPath}`;
+    return `${withState}\n\n[auth] Stack runner log: ${logPath}`;
   }
-  return `${base}\n\n[auth] Stack runner log: ${logPath}\n\n[auth] Last runner log lines:\n${String(tail).trimEnd()}`;
+  return `${withState}\n\n[auth] Stack runner log: ${logPath}\n\n[auth] Last runner log lines:\n${String(tail).trimEnd()}`;
 }
 
 async function tryStartStackUiInBackgroundForAuth({ rootDir, stackName, env = process.env } = {}) {

package/scripts/utils/cli/cli_registry.mjs

@@ -249,8 +249,11 @@ export function gethstackRegistry() {
       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]',
-      description: 'Remote setup helpers (SSH pairing + daemon setup)',
+        [
+          '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',

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');
+});
+