@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/utils/mobile/copy_artifact.mjs

@@ -0,0 +1,42 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/**
+ * @param {{ from: string; to: string }} params
+ */
+export async function copyArtifactFile(params) {
+  const from = String(params?.from ?? '').trim();
+  const to = String(params?.to ?? '').trim();
+  if (!from) throw new Error('copyArtifactFile: missing "from"');
+  if (!to) throw new Error('copyArtifactFile: missing "to"');
+  await mkdir(dirname(to), { recursive: true });
+  await copyFile(from, to);
+}
+
+function readFlagValue(argv, name) {
+  const key = `--${name}`;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === key) return String(argv[i + 1] ?? '').trim();
+    if (a.startsWith(`${key}=`)) return String(a.slice(key.length + 1)).trim();
+  }
+  return '';
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const from = readFlagValue(argv, 'from');
+  const to = readFlagValue(argv, 'to');
+  if (!from || !to) {
+    process.stderr.write('[copy-artifact] usage: node copy_artifact.mjs --from <path> --to <path>\n');
+    process.exit(2);
+  }
+  await copyArtifactFile({ from, to });
+}
+
+if (import.meta.url === new URL(process.argv[1], 'file:').href) {
+  main().catch((e) => {
+    process.stderr.write(`[copy-artifact] ${String(e?.stack ?? e)}\n`);
+    process.exit(1);
+  });
+}

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

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { copyArtifactFile } from './copy_artifact.mjs';
+
+test('copyArtifactFile copies a file and creates parent dirs', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-copy-artifact-'));
+  try {
+    const from = join(tmp, 'from.bin');
+    const to = join(tmp, 'nested', 'dir', 'to.bin');
+    await writeFile(from, 'hello', 'utf-8');
+    await mkdir(dirname(to), { recursive: true });
+    // Ensure the function works even if the directory already exists.
+
+    await copyArtifactFile({ from, to });
+
+    assert.equal(await readFile(to, 'utf-8'), 'hello');
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/mobile/dev_client_android_strategy.mjs

@@ -0,0 +1,54 @@
+import { commandExists } from '../proc/commands.mjs';
+
+function hasAndroidSdkEnv(env) {
+  const e = env && typeof env === 'object' ? env : process.env;
+  const home = String(e.ANDROID_HOME ?? '').trim();
+  const root = String(e.ANDROID_SDK_ROOT ?? '').trim();
+  return Boolean(home || root);
+}
+
+/**
+ * @typedef {'expo_run_android' | 'eas_local_dagger' | 'missing_prereqs'} AndroidDevClientStrategyKind
+ */
+
+/**
+ * Decide how to install an Android dev-client when requested via `hstack mobile-dev-client --install --platform=android`.
+ *
+ * - Prefer `expo run:android` on the host when it looks like an Android SDK is configured.
+ * - Otherwise fall back to an EAS local build inside Dagger (Linux container), which requires EXPO_TOKEN.
+ *
+ * @param {{ env?: Record<string, string | undefined>; cwd?: string }} [opts]
+ * @returns {Promise<
+ *   | { kind: 'expo_run_android' }
+ *   | { kind: 'eas_local_dagger' }
+ *   | { kind: 'missing_prereqs'; missing: string[] }
+ * >}
+ */
+export async function resolveAndroidDevClientInstallStrategy(opts = {}) {
+  const env = opts.env && typeof opts.env === 'object' ? opts.env : process.env;
+  const cwd = typeof opts.cwd === 'string' && opts.cwd.trim() ? opts.cwd.trim() : undefined;
+
+  const sdkEnv = hasAndroidSdkEnv(env);
+  const hasAdb = await commandExists('adb', { cwd, env, timeoutMs: 5_000 });
+  const hasJava = await commandExists('java', { cwd, env, timeoutMs: 5_000 });
+
+  if (sdkEnv && hasAdb && hasJava) {
+    return { kind: 'expo_run_android' };
+  }
+
+  const hasDagger = await commandExists('dagger', { cwd, env, timeoutMs: 5_000 });
+  const hasDocker = await commandExists('docker', { cwd, env, timeoutMs: 5_000 });
+  if (hasDagger && hasDocker) {
+    return { kind: 'eas_local_dagger' };
+  }
+
+  /** @type {string[]} */
+  const missing = [];
+  if (!(sdkEnv && hasAdb && hasJava)) {
+    missing.push('android_sdk');
+  }
+  if (!hasDagger) missing.push('dagger');
+  if (!hasDocker) missing.push('docker');
+
+  return { kind: 'missing_prereqs', missing };
+}

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

@@ -0,0 +1,56 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { writeFakeBin } from '../../testkit/core/fake_bin_harness.mjs';
+import { resolveAndroidDevClientInstallStrategy } from './dev_client_android_strategy.mjs';
+
+test('resolveAndroidDevClientInstallStrategy prefers expo run:android when Android SDK env is present', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'hstack-android-strategy-'));
+  try {
+    const binDir = join(tmp, 'bin');
+    await mkdir(binDir, { recursive: true });
+    writeFakeBin({ root: tmp, name: 'adb', content: '#!/bin/bash\nexit 0\n' });
+    writeFakeBin({ root: tmp, name: 'java', content: '#!/bin/bash\nexit 0\n' });
+
+    const env = {
+      PATH: `${binDir}:/usr/bin:/bin`,
+      ANDROID_HOME: join(tmp, 'android-home'),
+    };
+
+    const res = await resolveAndroidDevClientInstallStrategy({ env });
+    assert.equal(res.kind, 'expo_run_android');
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('resolveAndroidDevClientInstallStrategy falls back to EAS local (Dagger) when SDK is missing but dagger+docker exist', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-android-strategy-'));
+  try {
+    const binDir = join(tmp, 'bin');
+    await mkdir(binDir, { recursive: true });
+    writeFakeBin({ root: tmp, name: 'dagger', content: '#!/bin/bash\nexit 0\n' });
+    writeFakeBin({ root: tmp, name: 'docker', content: '#!/bin/bash\nexit 0\n' });
+
+    const env = {
+      PATH: `${binDir}:/usr/bin:/bin`,
+    };
+
+    const res = await resolveAndroidDevClientInstallStrategy({ env });
+    assert.equal(res.kind, 'eas_local_dagger');
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('resolveAndroidDevClientInstallStrategy returns missing prereqs when neither SDK nor pipeline fallback is available', async () => {
+  const env = {
+    PATH: `/usr/bin:/bin`,
+  };
+  const res = await resolveAndroidDevClientInstallStrategy({ env });
+  assert.equal(res.kind, 'missing_prereqs');
+  assert.ok(Array.isArray(res.missing) && res.missing.length > 0, 'expected missing prereqs to be listed');
+});

package/scripts/utils/mobile/dev_client_autopick.mjs

@@ -0,0 +1,201 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { runCapture } from '../proc/proc.mjs';
+
+function resolveCommandPathFromEnv(cmd, env) {
+  const c = String(cmd ?? '').trim();
+  if (!c) return '';
+  if (c.includes('/') || c.includes('\\')) {
+    return existsSync(c) ? c : '';
+  }
+
+  const e = env && typeof env === 'object' ? env : process.env;
+  const delimiter = process.platform === 'win32' ? ';' : ':';
+  const pathEntries = String(e.PATH ?? '')
+    .split(delimiter)
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  if (process.platform === 'win32') {
+    const pathextRaw = String(e.PATHEXT ?? '.EXE;.CMD;.BAT;.COM');
+    const pathext = pathextRaw
+      .split(';')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    for (const dir of pathEntries) {
+      // If cmd already has an extension, try it first.
+      const direct = join(dir, c);
+      if (existsSync(direct)) return direct;
+      for (const ext of pathext) {
+        const candidate = join(dir, `${c}${ext}`);
+        if (existsSync(candidate)) return candidate;
+      }
+    }
+    return '';
+  }
+
+  for (const dir of pathEntries) {
+    const candidate = join(dir, c);
+    if (existsSync(candidate)) return candidate;
+  }
+  return '';
+}
+
+async function runCaptureIfCommandExists(cmd, args, { env, cwd, timeoutMs } = {}) {
+  const resolved = resolveCommandPathFromEnv(cmd, env);
+  if (!resolved) return '';
+  try {
+    return await runCapture(resolved, args, { env, cwd, timeoutMs });
+  } catch {
+    return '';
+  }
+}
+
+function parseFirstAdbConnectedSerial(raw) {
+  const text = String(raw ?? '');
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^List of devices attached/i.test(trimmed)) continue;
+    const m = trimmed.match(/^(\S+)\s+device\b/);
+    if (m?.[1]) return m[1];
+  }
+  return '';
+}
+
+function parseXcdeviceList(raw) {
+  const text = String(raw ?? '');
+  const start = text.indexOf('[');
+  const jsonText = start >= 0 ? text.slice(start) : text;
+  try {
+    const parsed = JSON.parse(jsonText);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function findFirstConnectedUsbIosDeviceIdentifier(list) {
+  const arr = Array.isArray(list) ? list : [];
+  const firstConnected = arr.find(
+    (d) =>
+      d &&
+      d.platform === 'com.apple.platform.iphoneos' &&
+      d.interface === 'usb' &&
+      (d.available === true || d.available === 'YES') &&
+      d.simulator === false &&
+      typeof d.identifier === 'string' &&
+      d.identifier.length > 0
+  );
+  return firstConnected?.identifier || '';
+}
+
+async function resolveConnectedAndroidSerial({ env, cwd } = {}) {
+  const out = await runCaptureIfCommandExists('adb', ['devices'], { env, cwd, timeoutMs: 10_000 });
+  return parseFirstAdbConnectedSerial(out);
+}
+
+async function resolveConnectedUsbIosIdentifier({ env, cwd } = {}) {
+  if (process.platform !== 'darwin') return '';
+  const out = await runCaptureIfCommandExists('xcrun', ['xcdevice', 'list'], { env, cwd, timeoutMs: 10_000 });
+  if (!out) return '';
+  const list = parseXcdeviceList(out);
+  return findFirstConnectedUsbIosDeviceIdentifier(list);
+}
+
+async function isExplicitDeviceAndroid({ device, env, cwd } = {}) {
+  const d = String(device ?? '').trim();
+  if (!d) return false;
+  const out = await runCaptureIfCommandExists('adb', ['devices'], { env, cwd, timeoutMs: 10_000 });
+  if (!out) return false;
+  const re = new RegExp(`^${d.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\s+device\\b`, 'm');
+  return re.test(out);
+}
+
+async function isExplicitDeviceIos({ device, env, cwd } = {}) {
+  const d = String(device ?? '').trim();
+  if (!d) return false;
+  if (process.platform !== 'darwin') return false;
+  const out = await runCaptureIfCommandExists('xcrun', ['xcdevice', 'list'], { env, cwd, timeoutMs: 10_000 });
+  if (!out) return false;
+  const list = parseXcdeviceList(out);
+  return Boolean(
+    Array.isArray(list) &&
+      list.some((x) => x && (x.identifier === d || x.name === d) && x.platform === 'com.apple.platform.iphoneos')
+  );
+}
+
+/**
+ * @param {string} raw
+ * @returns {'ios'|'android'|''}
+ */
+function normalizePlatform(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (v === 'android') return 'android';
+  if (v === 'ios') return 'ios';
+  return '';
+}
+
+/**
+ * Autodetect `--platform` (and optionally `--device`) for `mobile-dev-client`.
+ *
+ * Rules:
+ * - If `--platform` is explicitly set, honor it.
+ * - If `--device` is set but platform is not, infer platform by matching connected devices.
+ * - Else: pick android if there's a connected adb device; pick ios if there's a connected USB iPhone.
+ * - If both iOS+Android are connected and nothing disambiguates, return ambiguous.
+ *
+ * @param {{ platformArg?: string; deviceArg?: string; env?: Record<string, string | undefined>; cwd?: string }} [opts]
+ * @returns {Promise<
+ *   | { kind: 'explicit'; platform: 'ios'|'android'; device: string }
+ *   | { kind: 'autopicked'; platform: 'ios'|'android'; device: string }
+ *   | { kind: 'ambiguous'; androidSerial: string; iosIdentifier: string }
+ * >}
+ */
+export async function resolveDevClientPlatformAndDevice(opts = {}) {
+  const env = opts.env && typeof opts.env === 'object' ? opts.env : process.env;
+  const cwd = typeof opts.cwd === 'string' && opts.cwd.trim() ? opts.cwd.trim() : undefined;
+  const explicitPlatform = normalizePlatform(opts.platformArg);
+  const explicitDevice = String(opts.deviceArg ?? '').trim();
+
+  if (explicitPlatform) {
+    if (explicitDevice) {
+      return { kind: 'explicit', platform: explicitPlatform, device: explicitDevice };
+    }
+    if (explicitPlatform === 'android') {
+      const androidSerial = await resolveConnectedAndroidSerial({ env, cwd });
+      return { kind: 'explicit', platform: 'android', device: androidSerial };
+    }
+    return { kind: 'explicit', platform: explicitPlatform, device: '' };
+  }
+
+  if (explicitDevice) {
+    if (await isExplicitDeviceAndroid({ device: explicitDevice, env, cwd })) {
+      return { kind: 'explicit', platform: 'android', device: explicitDevice };
+    }
+    if (await isExplicitDeviceIos({ device: explicitDevice, env, cwd })) {
+      return { kind: 'explicit', platform: 'ios', device: explicitDevice };
+    }
+    // If a device is explicitly provided but can't be matched, preserve legacy default (ios) and pass the device through.
+    return { kind: 'explicit', platform: 'ios', device: explicitDevice };
+  }
+
+  const [androidSerial, iosIdentifier] = await Promise.all([
+    resolveConnectedAndroidSerial({ env, cwd }),
+    resolveConnectedUsbIosIdentifier({ env, cwd }),
+  ]);
+
+  if (androidSerial && iosIdentifier) {
+    return { kind: 'ambiguous', androidSerial, iosIdentifier };
+  }
+  if (androidSerial) {
+    return { kind: 'autopicked', platform: 'android', device: androidSerial };
+  }
+  if (iosIdentifier) {
+    return { kind: 'autopicked', platform: 'ios', device: '' };
+  }
+
+  return { kind: 'autopicked', platform: 'ios', device: '' };
+}

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

@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildMobileDevClientInstallInvocation } from './dev_client_install_invocation.mjs';
+
+test('buildMobileDevClientInstallInvocation builds an Android run invocation when --platform=android is set', () => {
+  const inv = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install', '--platform=android', '--port=14362', '--device=ABC123'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(inv.nodeArgs.includes('--prebuild'), 'expected invocation to include --prebuild');
+  assert.ok(inv.nodeArgs.includes('--run-android'), 'expected invocation to include --run-android');
+  assert.ok(!inv.nodeArgs.includes('--run-ios'), 'expected invocation to not include --run-ios');
+
+  const platformIdx = inv.nodeArgs.indexOf('--platform=android');
+  assert.ok(platformIdx >= 0, `expected prebuild to be android-scoped\nnodeArgs:\n${inv.nodeArgs.join(' ')}`);
+
+  assert.ok(inv.nodeArgs.includes('--port=14362'), `expected --port to be forwarded\nnodeArgs:\n${inv.nodeArgs.join(' ')}`);
+  assert.ok(inv.nodeArgs.includes('--device=ABC123'), `expected --device to be forwarded\nnodeArgs:\n${inv.nodeArgs.join(' ')}`);
+});
+
+test('buildMobileDevClientInstallInvocation accepts space-separated --platform android', () => {
+  const inv = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install', '--platform', 'android', '--port', '14362', '--device', 'ABC123'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(inv.nodeArgs.includes('--prebuild'), 'expected invocation to include --prebuild');
+  assert.ok(inv.nodeArgs.includes('--run-android'), 'expected invocation to include --run-android');
+  assert.ok(!inv.nodeArgs.includes('--run-ios'), 'expected invocation to not include --run-ios');
+  assert.ok(inv.nodeArgs.includes('--platform=android'), `expected prebuild to be android-scoped\nnodeArgs:\n${inv.nodeArgs.join(' ')}`);
+  assert.ok(inv.nodeArgs.includes('--port=14362'), `expected --port to be forwarded\nnodeArgs:\n${inv.nodeArgs.join(' ')}`);
+  assert.ok(inv.nodeArgs.includes('--device=ABC123'), `expected --device to be forwarded\nnodeArgs:\n${inv.nodeArgs.join(' ')}`);
+});

package/scripts/utils/mobile/dev_client_install_invocation.mjs

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 
 import { parseArgs } from '../cli/args.mjs';
+import { getFlagValue } from '../cli/arg_values.mjs';
 import { defaultDevClientIdentity } from './identifiers.mjs';
 
 function normalizePortArg(raw) {
@@ -24,13 +25,31 @@ export function buildMobileDevClientInstallInvocation({
   const a = Array.isArray(argv) ? argv : [];
   const { flags, kv } = parseArgs(a);
 
-  const device = (kv.get('--device') ?? '').toString();
+  const platformRaw = String(getFlagValue({ argv: a, kv, flag: '--platform' }) ?? '')
+    .trim()
+    .toLowerCase();
+  const platform = platformRaw === 'android' ? 'android' : 'ios';
+
+  const device = String(getFlagValue({ argv: a, kv, flag: '--device' }) ?? '');
   const clean = flags.has('--clean');
-  const configuration = (kv.get('--configuration') ?? 'Debug').toString() || 'Debug';
-  const port = normalizePortArg(kv.get('--port'));
+  const configuration =
+    (getFlagValue({ argv: a, kv, flag: '--configuration' }) ?? kv.get('--configuration') ?? 'Debug').toString() ||
+    'Debug';
+  const port = normalizePortArg(getFlagValue({ argv: a, kv, flag: '--port' }));
 
   const user = (baseEnv.USER ?? baseEnv.USERNAME ?? 'user').toString();
-  const identity = defaultDevClientIdentity({ user });
+  const identityBase = defaultDevClientIdentity({ user });
+
+  const schemeOverride = String(getFlagValue({ argv: a, kv, flag: '--scheme' }) ?? '').trim();
+  const bundleIdOverride = String(getFlagValue({ argv: a, kv, flag: '--bundle-id' }) ?? '').trim();
+  const appNameOverride = String(getFlagValue({ argv: a, kv, flag: '--app-name' }) ?? '').trim();
+
+  const identity = {
+    ...identityBase,
+    ...(schemeOverride ? { scheme: schemeOverride } : {}),
+    ...(bundleIdOverride ? { iosBundleId: bundleIdOverride } : {}),
+    ...(appNameOverride ? { iosAppName: appNameOverride } : {}),
+  };
 
   const mobileScript = join(r, 'scripts', 'mobile.mjs');
 
@@ -42,9 +61,9 @@ export function buildMobileDevClientInstallInvocation({
     `--scheme=${identity.scheme}`,
     ...(port ? [`--port=${port}`] : []),
     '--prebuild',
+    ...(platform === 'android' ? ['--platform=android'] : []),
     ...(clean ? ['--clean'] : []),
-    '--run-ios',
-    `--configuration=${configuration}`,
+    ...(platform === 'android' ? ['--run-android'] : ['--run-ios', `--configuration=${configuration}`]),
     '--no-metro',
     ...(device ? [`--device=${device}`] : []),
   ];
@@ -52,17 +71,24 @@ export function buildMobileDevClientInstallInvocation({
   const env = {
     ...baseEnv,
     EXPO_APP_SCHEME: identity.scheme,
+    EXPO_APP_NAME: identity.iosAppName,
+    EXPO_APP_BUNDLE_ID: identity.iosBundleId,
     EXPO_PUBLIC_HAPPY_STORAGE_SCOPE: baseEnv.EXPO_PUBLIC_HAPPY_STORAGE_SCOPE ?? '',
   };
+  // Keep Expo slug stable so EAS local builds don't fail when `extra.eas.projectId` is configured.
+  // Dev/prod isolation should be done via EXPO_APP_SCHEME (and bundle id), not slug.
+  // Explicitly blank EXPO_APP_SLUG so higher-precedence pipeline env sources (env-files/Keychain bundles)
+  // cannot accidentally override it back to a non-matching slug.
+  env.EXPO_APP_SLUG = '';
 
   return {
     nodeArgs,
     env,
     identity,
+    platform,
     device,
     clean,
     configuration,
     port,
   };
 }
-

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

@@ -14,6 +14,71 @@ test('buildMobileDevClientInstallInvocation forwards --port to mobile.mjs args',
   assert.ok(invocation.nodeArgs.includes('--port=14362'), 'expected --port to be forwarded to mobile.mjs');
 });
 
+test('buildMobileDevClientInstallInvocation accepts space-separated --port 14362', 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 sets EXPO_APP_SCHEME for dev-client isolation', async () => {
+  const invocation = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install'],
+    baseEnv: { USER: 'leeroy', EXPO_APP_SLUG: 'custom-slug' },
+  });
+
+  assert.equal(invocation.env.EXPO_APP_SCHEME, invocation.identity.scheme);
+  assert.equal(
+    invocation.env.EXPO_APP_SLUG,
+    '',
+    'expected EXPO_APP_SLUG to be explicitly blank so pipeline env files/Keychain bundles cannot override it',
+  );
+});
+
+test('buildMobileDevClientInstallInvocation allows overriding scheme via --scheme', async () => {
+  const invocation = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install', '--scheme=acme-dev'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(invocation.nodeArgs.includes('--scheme=acme-dev'), 'expected overridden scheme to be forwarded to mobile.mjs');
+  assert.equal(invocation.env.EXPO_APP_SCHEME, 'acme-dev');
+});
+
+test('buildMobileDevClientInstallInvocation allows overriding bundle id via --bundle-id', async () => {
+  const invocation = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install', '--bundle-id=com.example.happier.devclient'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(
+    invocation.nodeArgs.includes('--ios-bundle-id=com.example.happier.devclient'),
+    'expected overridden bundle id to be forwarded to mobile.mjs',
+  );
+  assert.equal(invocation.env.EXPO_APP_BUNDLE_ID, 'com.example.happier.devclient');
+});
+
+test('buildMobileDevClientInstallInvocation allows overriding app name via --app-name', async () => {
+  const invocation = buildMobileDevClientInstallInvocation({
+    rootDir: '/repo/apps/stack',
+    argv: ['--install', '--app-name=Happier Dev (Acme)'],
+    baseEnv: { USER: 'leeroy' },
+  });
+
+  assert.ok(
+    invocation.nodeArgs.includes('--ios-app-name=Happier Dev (Acme)'),
+    'expected overridden app name to be forwarded to mobile.mjs',
+  );
+  assert.equal(invocation.env.EXPO_APP_NAME, 'Happier Dev (Acme)');
+});
+
 test('buildMobileDevClientInstallInvocation omits --port when not provided', async () => {
   const invocation = buildMobileDevClientInstallInvocation({
     rootDir: '/repo/apps/stack',
@@ -24,4 +89,3 @@ test('buildMobileDevClientInstallInvocation omits --port when not provided', asy
   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/mobile/dev_client_links.mjs

@@ -48,12 +48,22 @@ export function resolveDevClientDeepLink({ scheme, metroUrl }) {
   return `${s}://expo-development-client/?url=${encodeURIComponent(url)}`;
 }
 
+function normalizeExpoSlug(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (!v) return '';
+  // Expo slug should be safe for use in a URL scheme segment (`exp+<slug>`).
+  return v.replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+}
+
 export function resolveMobileQrPayload({ env = process.env, port }) {
   const metroUrl = resolveMetroUrlForMobile({ env, port });
   const scheme = resolveMobileScheme(env);
+  const slug = normalizeExpoSlug(env.EXPO_APP_SLUG);
+  const expoDevClientScheme = slug ? `exp+${slug}` : '';
+
+  // Prefer the configured app scheme for dev-client links so we can isolate dev/prod apps without
+  // needing to change Expo slug (which must match the EAS project id configuration).
   const deepLink = resolveDevClientDeepLink({ scheme, metroUrl });
-  // Match Expo CLI / @expo/cli UrlCreator: QR encodes the dev-client deep link.
-  // Note: iOS Camera will still offer to open custom schemes when the app is installed.
   const payload = deepLink || metroUrl;
-  return { scheme, metroUrl, deepLink, payload };
+  return { scheme, metroUrl, deepLink, payload, expoDevClientScheme, slug };
 }

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

@@ -0,0 +1,28 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveMobileQrPayload } from './dev_client_links.mjs';
+
+test('resolveMobileQrPayload uses the configured app scheme for the dev-client deep link', () => {
+  const env = {
+    HAPPIER_STACK_MOBILE_HOST: 'localhost',
+    EXPO_APP_SCHEME: 'happier-dev',
+  };
+
+  const { metroUrl, deepLink, payload } = resolveMobileQrPayload({ env, port: 8081 });
+  assert.equal(metroUrl, 'http://localhost:8081');
+  assert.equal(deepLink, `happier-dev://expo-development-client/?url=${encodeURIComponent(metroUrl)}`);
+  assert.equal(payload, deepLink);
+});
+
+test('resolveMobileQrPayload does not require EXPO_APP_SLUG', () => {
+  const env = {
+    HAPPIER_STACK_MOBILE_HOST: 'localhost',
+    EXPO_APP_SCHEME: 'happier-dev',
+    EXPO_APP_SLUG: undefined,
+  };
+
+  const { metroUrl, deepLink } = resolveMobileQrPayload({ env, port: 8081 });
+  assert.equal(metroUrl, 'http://localhost:8081');
+  assert.equal(deepLink, `happier-dev://expo-development-client/?url=${encodeURIComponent(metroUrl)}`);
+});

package/scripts/utils/mobile/identifiers.mjs

@@ -26,11 +26,14 @@ export function stackSlugForMobileIds(stackName) {
 }
 
 export function defaultDevClientIdentity({ user = null } = {}) {
-  const u = sanitizeBundleIdSegment(user ?? 'user');
   return {
-    iosAppName: 'Happier Dev',
-    iosBundleId: `dev.happier.stack.dev.${u}`,
-    scheme: 'happier-dev',
+    iosAppName: 'Happier (internal dev)',
+    // IMPORTANT:
+    // Keep the dev-client bundle id stable so EAS Android signing credentials (keystore) can be
+    // provisioned once and reused across runs. This also matches the default development variant
+    // bundle id in apps/ui/app.config.js.
+    iosBundleId: 'dev.happier.app.dev.internal',
+    scheme: 'happier-internaldev',
   };
 }
 

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

@@ -28,9 +28,9 @@ test('stackSlugForMobileIds derives a stable slug', () => {
 
 test('defaultDevClientIdentity is stable and safe', () => {
   const id = defaultDevClientIdentity({ user: 'Leeroy' });
-  assert.equal(id.iosAppName, 'Happier Dev');
-  assert.equal(id.scheme, 'happier-dev');
-  assert.equal(id.iosBundleId, 'dev.happier.stack.dev.leeroy');
+  assert.equal(id.iosAppName, 'Happier (internal dev)');
+  assert.equal(id.scheme, 'happier-internaldev');
+  assert.equal(id.iosBundleId, 'dev.happier.app.dev.internal');
 });
 
 test('defaultStackReleaseIdentity is per-stack', () => {