@happier-dev/stack 0.1.0 → 0.2.0-preview.1775370152.55749

package/scripts/menubar.mjs

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
+import { getHappyStacksHomeDir, getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
@@ -13,6 +13,7 @@ import { normalizeProfile } from './utils/cli/normalize.mjs';
 import { banner, kv, sectionTitle } from './utils/ui/layout.mjs';
 import { cyan, dim, green } from './utils/ui/ansi.mjs';
 import { detectSwiftbarPluginInstalled, removeSwiftbarPlugins } from './utils/menubar/swiftbar.mjs';
+import { normalizeStackNameOrNull, sanitizeStackName } from './utils/stack/names.mjs';
 
 async function ensureSwiftbarAssets({ cliRootDir }) {
   const homeDir = getHappyStacksHomeDir();
@@ -48,18 +49,27 @@ function sandboxPluginBasename() {
   return `hstack.sandbox-${hash}`;
 }
 
+function stackPluginBasename(stackName) {
+  const normalized = sanitizeStackName(stackName, { fallback: 'stack', maxLen: 64 });
+  const hash = createHash('sha256').update(String(stackName ?? '')).digest('hex').slice(0, 6);
+  const short = normalized.length > 32 ? normalized.slice(0, 32) : normalized;
+  return sanitizeStackName(`hstack-${short}-${hash}`, { fallback: 'hstack', maxLen: 64 });
+}
+
 async function main() {
   const rawArgv = process.argv.slice(2);
   const argv = rawArgv[0] === 'menubar' ? rawArgv.slice(1) : rawArgv;
   const helpSepIdx = argv.indexOf('--');
   const helpScopeArgv = helpSepIdx === -1 ? argv : argv.slice(0, helpSepIdx);
   const { flags } = parseArgs(helpScopeArgv);
+  const { kv: kvFlags } = parseArgs(helpScopeArgv);
   const json = wantsJson(helpScopeArgv, { flags });
+  const dryRun = flags.has('--dry-run') || helpScopeArgv.includes('--dry-run');
 
   const cmd = helpScopeArgv.find((a) => a && a !== '--' && !a.startsWith('-')) || 'help';
   const wantsHelpFlag = wantsHelp(helpScopeArgv, { flags });
   const usageByCmd = new Map([
-    ['install', 'hstack menubar install [--json]'],
+    ['install', 'hstack menubar install [--stack=<name>] [--mode=selfhost|dev] [--json]'],
     ['uninstall', 'hstack menubar uninstall [--json]'],
     ['open', 'hstack menubar open [--json]'],
     ['mode', 'hstack menubar mode <selfhost|dev> [--json]'],
@@ -86,7 +96,7 @@ async function main() {
         banner('menubar', { subtitle: 'SwiftBar menu bar plugin (macOS).' }),
         '',
         sectionTitle('usage:'),
-        `  ${cyan('hstack menubar')} install [--json]`,
+        `  ${cyan('hstack menubar')} install [--stack=<name>] [--mode=selfhost|dev] [--json]`,
         `  ${cyan('hstack menubar')} uninstall [--json]`,
         `  ${cyan('hstack menubar')} open [--json]`,
         `  ${cyan('hstack menubar')} mode <selfhost|dev> [--json]`,
@@ -119,7 +129,7 @@ async function main() {
     }
     const patterns = isSandboxed()
       ? [`${sandboxPluginBasename()}.*.sh`]
-      : ['hstack.*.sh'];
+      : ['hstack.*.sh', 'hstack-*.sh'];
     const res = await removeSwiftbarPlugins({ patterns });
     const dir = res.pluginsDir;
     printResult({
@@ -175,16 +185,93 @@ async function main() {
     }
     const { destDir } = await ensureSwiftbarAssets({ cliRootDir });
     const installer = join(destDir, 'install.sh');
+
+    const explicitStackRaw = String(kvFlags.get('--stack') ?? '').trim();
+    const explicitStack = explicitStackRaw ? normalizeStackNameOrNull(explicitStackRaw) : null;
+    if (explicitStackRaw && !explicitStack) {
+      throw new Error('[menubar] invalid --stack name (expected letters, numbers, and dashes)');
+    }
+    const explicitModeRaw = String(kvFlags.get('--mode') ?? '').trim();
+    const explicitMode = explicitModeRaw ? normalizeProfile(explicitModeRaw) : null;
+    if (explicitModeRaw && !explicitMode) {
+      throw new Error('[menubar] invalid --mode (expected selfhost or dev)');
+    }
+    const effectiveMode = explicitMode || String(process.env.HAPPIER_STACK_MENUBAR_MODE ?? 'dev').trim() || 'dev';
+    const stackName = explicitStack || String((process.env.HAPPIER_STACK_STACK ?? '').trim() || 'main');
+    const normalizedStack = sanitizeStackName(stackName, { fallback: 'main', maxLen: 64 });
+    const stackScoped = normalizedStack !== 'main';
+
+    const interval = String(process.env.HAPPIER_STACK_SWIFTBAR_INTERVAL ?? '').trim() || '5m';
+    const defaultBasename = isSandboxed()
+      ? sandboxPluginBasename()
+      : (stackScoped ? stackPluginBasename(normalizedStack) : 'hstack');
+    const pluginBasename = String(process.env.HAPPIER_STACK_SWIFTBAR_PLUGIN_BASENAME ?? '').trim() || defaultBasename;
+    const pluginFile = `${pluginBasename}.${interval}.sh`;
+
+    const defaultEnvFile = (process.env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim();
+    const resolvedEnvFile = explicitStack
+      ? resolveStackEnvPath(normalizedStack, process.env).envPath
+      : (defaultEnvFile || resolveStackEnvPath(normalizedStack, process.env).envPath);
+
     const env = {
       ...process.env,
       HAPPIER_STACK_HOME_DIR: getHappyStacksHomeDir(),
-      ...(isSandboxed()
+      HAPPIER_STACK_MENUBAR_MODE: effectiveMode,
+      ...(pluginBasename ? { HAPPIER_STACK_SWIFTBAR_PLUGIN_BASENAME: pluginBasename } : {}),
+      ...((isSandboxed() || stackScoped)
         ? {
-            HAPPIER_STACK_SWIFTBAR_PLUGIN_BASENAME: sandboxPluginBasename(),
             HAPPIER_STACK_SWIFTBAR_PLUGIN_WRAPPER: '1',
+            ...(stackScoped
+              ? {
+                  HAPPIER_STACK_SWIFTBAR_PRIMARY_STACK: normalizedStack,
+                  HAPPIER_STACK_SWIFTBAR_PRIMARY_ENV_FILE: resolvedEnvFile,
+                }
+              : {}),
           }
         : {}),
     };
+
+    if (dryRun) {
+      const data = {
+        ok: true,
+        stack: {
+          name: normalizedStack,
+          scoped: stackScoped,
+          envFile: resolvedEnvFile || null,
+        },
+        mode: effectiveMode,
+        swiftbar: {
+          pluginBasename,
+          pluginInterval: interval,
+          pluginFile,
+          wrapper: Boolean(isSandboxed() || stackScoped),
+        },
+        installer: {
+          cmd: 'bash',
+          args: [installer, '--force'],
+        },
+      };
+      printResult({
+        json,
+        data,
+        text: [
+          sectionTitle('Menubar install (dry-run)'),
+          `- ${kv('stack:', cyan(normalizedStack))}`,
+          `- ${kv('plugin:', cyan(pluginFile))}`,
+          `- ${kv('wrapper:', cyan(String(data.swiftbar.wrapper)))}`,
+          `- ${kv('env file:', resolvedEnvFile ? cyan(resolvedEnvFile) : dim('(none)'))}`,
+        ].join('\n'),
+      });
+      return;
+    }
+
+    if (explicitMode) {
+      await ensureEnvLocalUpdated({
+        rootDir: cliRootDir,
+        updates: [{ key: 'HAPPIER_STACK_MENUBAR_MODE', value: explicitMode }],
+      });
+    }
+
     const res = spawnSync('bash', [installer, '--force'], { stdio: 'inherit', env });
     if (res.status !== 0) {
       process.exit(res.status ?? 1);

package/scripts/menubar_install_stack_scoped_dry_run.test.mjs

@@ -0,0 +1,117 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function runHstack(args, { env } = {}) {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const repoRoot = resolve(rootDir, '..', '..');
+  const hstackBin = resolve(repoRoot, 'apps', 'stack', 'bin', 'hstack.mjs');
+
+  return spawnSync(process.execPath, [hstackBin, ...args], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      HAPPIER_STACK_CLI_ROOT_DISABLE: '1',
+      HAPPIER_STACK_UPDATE_CHECK: '0',
+      ...env,
+    },
+    encoding: 'utf8',
+  });
+}
+
+test('hstack menubar install --dry-run derives a unique plugin basename for non-main stacks', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-menubar-dryrun-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  });
+
+  const storageDir = join(tmp, 'stacks');
+  const stackName = 'repo-foo-1234567890';
+  const stackDir = join(storageDir, stackName);
+  await mkdir(stackDir, { recursive: true });
+  const envFile = join(stackDir, 'env');
+  await writeFile(envFile, 'HAPPIER_STACK_STACK=repo-foo-1234567890\n', 'utf8');
+
+  const res = runHstack(['menubar', 'install', '--dry-run', '--json'], {
+    env: {
+      HAPPIER_STACK_STACK: stackName,
+      HAPPIER_STACK_ENV_FILE: envFile,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+    },
+  });
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const data = JSON.parse(res.stdout);
+  assert.equal(data.ok, true);
+  assert.equal(data.stack?.name, stackName);
+  assert.equal(data.swiftbar?.wrapper, true);
+  assert.match(String(data.swiftbar?.pluginBasename ?? ''), /^hstack-[a-z0-9-]+-[a-f0-9]{6}$/);
+  assert.equal(data.swiftbar?.pluginBasename === 'hstack', false);
+  assert.equal(data.swiftbar?.pluginFile, `${data.swiftbar.pluginBasename}.5m.sh`);
+});
+
+test('hstack menubar install --dry-run keeps the default plugin basename for main', () => {
+  const res = runHstack(['menubar', 'install', '--dry-run', '--json'], {
+    env: {
+      HAPPIER_STACK_STACK: 'main',
+    },
+  });
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const data = JSON.parse(res.stdout);
+  assert.equal(data.ok, true);
+  assert.equal(data.stack?.name, 'main');
+  assert.equal(data.swiftbar?.wrapper, false);
+  assert.equal(data.swiftbar?.pluginBasename, 'hstack');
+  assert.equal(data.swiftbar?.pluginFile, 'hstack.5m.sh');
+});
+
+test('hstack menubar install --dry-run uses the explicit stack env file instead of a stale exported env file', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-menubar-explicit-stack-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  });
+
+  const storageDir = join(tmp, 'stacks');
+  const mainDir = join(storageDir, 'main');
+  const devBuiltDir = join(storageDir, 'dev-built');
+  await mkdir(mainDir, { recursive: true });
+  await mkdir(devBuiltDir, { recursive: true });
+
+  const mainEnvFile = join(mainDir, 'env');
+  const devBuiltEnvFile = join(devBuiltDir, 'env');
+  await writeFile(mainEnvFile, 'HAPPIER_STACK_STACK=main\n', 'utf8');
+  await writeFile(devBuiltEnvFile, 'HAPPIER_STACK_STACK=dev-built\n', 'utf8');
+
+  const res = runHstack(['menubar', 'install', '--stack=dev-built', '--dry-run', '--json'], {
+    env: {
+      HAPPIER_STACK_STACK: 'main',
+      HAPPIER_STACK_ENV_FILE: mainEnvFile,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+    },
+  });
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const data = JSON.parse(res.stdout);
+  assert.equal(data.ok, true);
+  assert.equal(data.stack?.name, 'dev-built');
+  assert.equal(data.stack?.envFile, devBuiltEnvFile);
+});
+
+test('hstack menubar install --dry-run honors an explicit mode flag', () => {
+  const res = runHstack(['menubar', 'install', '--stack=dev-built', '--mode=selfhost', '--dry-run', '--json'], {
+    env: {
+      HAPPIER_STACK_STACK: 'main',
+    },
+  });
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const data = JSON.parse(res.stdout);
+  assert.equal(data.ok, true);
+  assert.equal(data.mode, 'selfhost');
+});

package/scripts/mobile.mjs

@@ -6,7 +6,7 @@ import { run, runCapture, spawnProc } from './utils/proc/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
 import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/proc/pm.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths } from './utils/expo/expo.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, resolveExpoTmpDir } from './utils/expo/expo.mjs';
 import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
 import { resolveMobileExpoConfig } from './utils/mobile/config.mjs';
 import { resolveStackContext } from './utils/stack/context.mjs';
@@ -26,7 +26,7 @@ import { pickMetroPort, resolveStablePortStart } from './utils/expo/metro_ports.
  * Usage:
  *   hstack mobile
  *   hstack mobile --host=lan
- *   hstack mobile --scheme=dev.happier.app.dev
+ *   hstack mobile --scheme=happier-internaldev
   *   hstack mobile --no-metro
  *   hstack mobile --run-ios --device="Your iPhone"
  */
@@ -50,6 +50,7 @@ async function main() {
           '--app-env=development|production',
           '--prebuild [--platform=ios|all] [--clean]',
           '--run-ios [--device=<id-or-name>] [--configuration=Debug|Release]',
+          '--run-android [--device=<id-or-name>]',
           '--metro / --no-metro',
           '--restart',
           '--no-signing-fix',
@@ -61,12 +62,13 @@ async function main() {
         '  hstack mobile [--host=lan|localhost|tunnel] [--port=8081] [--scheme=...] [--json]',
         '  hstack mobile --restart   # force-restart Metro for this stack/worktree',
         '  hstack mobile --run-ios [--device=...] [--configuration=Debug|Release]',
+        '  hstack mobile --run-android [--device=...]',
         '  hstack mobile --prebuild [--platform=ios|all] [--clean]',
         '  hstack mobile --no-metro   # just build/install (if --run-ios) without starting Metro',
         '',
         'Notes:',
         '- This script is designed to avoid editing upstream UI config in-place.',
-        '- If you explicitly set HAPPIER_STACK_SERVER_URL, it bakes that URL into the app via EXPO_PUBLIC_HAPPY_SERVER_URL.',
+        '- If you explicitly set HAPPIER_PUBLIC_SERVER_URL (or HAPPIER_STACK_SERVER_URL as a fallback), it bakes that URL into the app via EXPO_PUBLIC_HAPPY_SERVER_URL.',
       ].join('\n'),
     });
     return;
@@ -102,8 +104,8 @@ async function main() {
     return Array.isArray(parsed) ? parsed : [];
   }
 
-  // Default to the existing dev bundle identifier, which is also registered as a URL scheme
-  // (Info.plist includes `dev.happier.app.dev`), so iOS will open the dev build instead of the App Store app.
+  // Default to a dev bundle identifier/scheme that is distinct from the App Store build so iOS opens
+  // the dev build instead of the App Store app when scanning QR/deeplinks.
   const appEnv = process.env.APP_ENV ?? kv.get('--app-env') ?? 'development';
   const host = kv.get('--host') ?? process.env.HAPPIER_STACK_MOBILE_HOST ?? 'lan';
   const portFromArg = kv.get('--port') ?? '';
@@ -114,7 +116,7 @@ async function main() {
   // - `hstack mobile --run-ios` / `hstack mobile:ios` just builds/installs and exits (unless --metro is provided).
   const shouldStartMetro =
     flags.has('--metro') ||
-    (!flags.has('--no-metro') && !flags.has('--run-ios') && !flags.has('--prebuild'));
+    (!flags.has('--no-metro') && !flags.has('--run-ios') && !flags.has('--run-android') && !flags.has('--prebuild'));
 
   const env = {
     ...process.env,
@@ -136,7 +138,7 @@ async function main() {
   // Strategy:
   // - If the user explicitly sets --port or HAPPIER_STACK_MOBILE_PORT, honor it.
   // - Otherwise pick a stable, collision-resistant port in a higher range for build-only steps.
-  const needsNativeBuildPort = flags.has('--prebuild') || flags.has('--run-ios');
+  const needsNativeBuildPort = flags.has('--prebuild') || flags.has('--run-ios') || flags.has('--run-android');
   if (needsNativeBuildPort) {
     const forcedPort = (portFromArg || portFromEnv).toString().trim();
     const stableKey = (stackMode && stackName ? stackName : '') || iosBundleId || scheme || 'happier';
@@ -172,11 +174,12 @@ async function main() {
     projectDir: uiDir,
     stateFileName: 'expo.state.json',
   });
+  const tmpDir = resolveExpoTmpDir({ env, defaultTmpDir: expoPaths.tmpDir, kind: 'expo-dev', projectDir: uiDir });
   await ensureExpoIsolationEnv({
     env,
     stateDir: expoPaths.stateDir,
     expoHomeDir: expoPaths.expoHomeDir,
-    tmpDir: expoPaths.tmpDir,
+    tmpDir,
   });
 
   // Allow happy-stacks to define the default server URL baked into the app bundle.
@@ -344,6 +347,18 @@ async function main() {
     await expoExec({ dir: happyDir, projectDir: uiDir, args, env, ensureDepsLabel: 'happy' });
   }
 
+  if (flags.has('--run-android')) {
+    const device = (kv.get('--device') ?? '').toString().trim();
+    if (device) {
+      // Prefer ANDROID_SERIAL over passing Expo CLI flags (keeps this robust across Expo versions).
+      env.ANDROID_SERIAL = device;
+    }
+
+    const metroPort = String(env.RCT_METRO_PORT ?? portRaw ?? '8081');
+    const args = ['run:android', '--port', metroPort, '--no-build-cache'];
+    await expoExec({ dir: happyDir, projectDir: uiDir, args, env, ensureDepsLabel: 'happy' });
+  }
+
   if (!shouldStartMetro) {
     return;
   }

package/scripts/mobile_dev_client.mjs

@@ -1,12 +1,32 @@
 import './utils/env/env.mjs';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getFlagValue } from './utils/cli/arg_values.mjs';
 import { run } from './utils/proc/proc.mjs';
-import { getRootDir } from './utils/paths/paths.mjs';
+import { getHappyStacksHomeDir, getRepoDir, getRootDir } from './utils/paths/paths.mjs';
 import { banner, cmd, sectionTitle } from './utils/ui/layout.mjs';
 import { cyan, dim, yellow } from './utils/ui/ansi.mjs';
 
+import { commandExists } from './utils/proc/commands.mjs';
 import { buildMobileDevClientInstallInvocation } from './utils/mobile/dev_client_install_invocation.mjs';
+import { resolveDevClientPlatformAndDevice } from './utils/mobile/dev_client_autopick.mjs';
+import { resolveAndroidDevClientInstallStrategy } from './utils/mobile/dev_client_android_strategy.mjs';
+
+function resolveAbsPathFromRepoRoot(repoRoot, rawPath) {
+  const p = String(rawPath ?? '').trim();
+  if (!p) return '';
+  if (isAbsolute(p)) return p;
+  // Basic Windows drive-letter absolute support.
+  if (/^[A-Za-z]:[\\/]/.test(p)) return p;
+  return join(repoRoot, p);
+}
+
+function resolveAndroidDevClientCachedApkPath({ env } = {}) {
+  const home = getHappyStacksHomeDir(env ?? process.env);
+  return join(home, 'mobile-dev-client', 'android', 'happier-dev-client-android.apk');
+}
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -17,18 +37,31 @@ async function main() {
     printResult({
       json,
       data: {
-        flags: ['--device=<id-or-name>', '--port=<port>', '--clean', '--configuration=Debug|Release', '--json'],
+        flags: [
+          '--platform=ios|android',
+          '--device=<id-or-name>',
+          '--scheme=<url-scheme>',
+          '--bundle-id=<bundle-id>',
+          '--app-name=<name>',
+          '--port=<port>',
+          '--reuse',
+          '--apk=<path>',
+          '--clean',
+          '--configuration=Debug|Release',
+          '--json',
+        ],
       },
       text: [
-        banner('mobile-dev-client', { subtitle: 'Install the shared iOS dev-client app (one-time).' }),
+        banner('mobile-dev-client', { subtitle: 'Install the shared dev-client app (one-time).' }),
         '',
         sectionTitle('usage:'),
-        `  ${cyan('hstack mobile-dev-client')} --install [--device=...] [--port=...] [--clean] [--configuration=Debug|Release] [--json]`,
+        `  ${cyan('hstack mobile-dev-client')} --install [--platform=ios|android] [--device=...] [--scheme=...] [--bundle-id=...] [--app-name=...] [--port=...] [--clean] [--configuration=Debug|Release] [--json]`,
         '',
         sectionTitle('notes:'),
-        `- Installs a dedicated ${cyan('hstack Dev')} Expo dev-client app on your iPhone.`,
+        `- Installs a dedicated ${cyan('hstack Dev')} Expo dev-client app on your phone.`,
         `- This app is intended to be ${cyan('reused across stacks')} (no per-stack installs).`,
-        `- Requires ${yellow('Xcode')} + ${yellow('CocoaPods')} (macOS).`,
+        `- If you install with a custom ${cyan('--scheme')}, set ${cyan('HAPPIER_STACK_DEV_CLIENT_SCHEME')} to the same value so QR links open the right app.`,
+        `- iOS requires ${yellow('Xcode')} + ${yellow('CocoaPods')} (macOS).`,
       ].join('\n'),
     });
     return;
@@ -44,15 +77,208 @@ async function main() {
   }
 
   const rootDir = getRootDir(import.meta.url);
-  const invocation = buildMobileDevClientInstallInvocation({ rootDir, argv, baseEnv: process.env });
+  const repoRoot = getRepoDir(rootDir, process.env);
+  const platformArg = getFlagValue({ argv, kv, flag: '--platform' });
+  const deviceArg = getFlagValue({ argv, kv, flag: '--device' });
+  const wantsReuseApk = flags.has('--reuse');
+  const apkArg = getFlagValue({ argv, kv, flag: '--apk' });
+
+  const isTestStub = String(process.env.HSTACK_MOBILE_DEV_CLIENT_TEST_STUB ?? '').trim() === '1';
+
+  const resolved = await resolveDevClientPlatformAndDevice({
+    platformArg,
+    deviceArg,
+    env: process.env,
+    cwd: repoRoot,
+  });
+
+  if (resolved.kind === 'ambiguous') {
+    if (isTestStub) {
+      printResult({
+        json: true,
+        data: {
+          ok: false,
+          error: 'ambiguous_platform',
+          androidSerial: resolved.androidSerial,
+          iosIdentifier: resolved.iosIdentifier,
+        },
+      });
+      return;
+    }
+    printResult({
+      json,
+      data: { ok: false, error: 'ambiguous_platform' },
+      text:
+        `[mobile-dev-client] Both Android + iOS USB devices are connected.\n` +
+        `Pass ${cyan('--platform=android')} or ${cyan('--platform=ios')} to disambiguate.`,
+    });
+    process.exit(1);
+  }
+
+  const platform = resolved.platform;
+  const argvWithAutopick = [...argv];
+  if (!platformArg) {
+    argvWithAutopick.push(`--platform=${platform}`);
+  }
+  if (!deviceArg && resolved.device) {
+    argvWithAutopick.push(`--device=${resolved.device}`);
+  }
+
+  const invocation = buildMobileDevClientInstallInvocation({ rootDir, argv: argvWithAutopick, baseEnv: process.env });
+
+  /** @type {{ platform: string; strategy: string; steps: Array<{ cmd: string; args: string[]; cwd: string; env: Record<string, string | undefined> }> }} */
+  const plan = { platform, strategy: platform === 'android' ? 'unknown' : 'ios', steps: [] };
 
-  const env = {
-    ...invocation.env,
-  };
+  if (platform === 'android') {
+    const defaultApkAbs = join(repoRoot, 'dist', 'ui-mobile', 'happier-dev-client-android.apk');
+    const cachedApkAbs = resolveAndroidDevClientCachedApkPath({ env: process.env });
+    const requestedApkAbs = apkArg ? resolveAbsPathFromRepoRoot(repoRoot, apkArg) : '';
+    const reuseApkAbs = (() => {
+      if (requestedApkAbs) return requestedApkAbs;
+      if (existsSync(defaultApkAbs)) return defaultApkAbs;
+      if (existsSync(cachedApkAbs)) return cachedApkAbs;
+      return defaultApkAbs;
+    })();
+
+    if (wantsReuseApk || requestedApkAbs) {
+      const hasAdb = await commandExists('adb', { cwd: repoRoot, env: process.env, timeoutMs: 5_000 });
+      const hasApk = Boolean(reuseApkAbs) && existsSync(reuseApkAbs);
+
+      if (!hasApk || !hasAdb) {
+        const missing = [];
+        if (!hasApk) missing.push('apk');
+        if (!hasAdb) missing.push('adb');
+
+        if (isTestStub) {
+          printResult({
+            json: true,
+            data: { ok: false, platform, strategy: 'reuse_apk', missing, steps: [] },
+          });
+          return;
+        }
+
+        printResult({
+          json,
+          data: { ok: false, error: 'android_reuse_missing', missing },
+          text:
+            `[mobile-dev-client] Cannot reuse an existing APK.\n` +
+            `Missing: ${missing.join(', ')}\n` +
+            `Looked for APK at: ${cyan(defaultApkAbs)}\n` +
+            `Or cached at: ${cyan(cachedApkAbs)}\n` +
+            `Tip: run without ${cyan('--reuse')} to rebuild.`,
+        });
+        process.exit(1);
+      }
+
+      plan.strategy = 'reuse_apk';
+      plan.steps.push({
+        cmd: 'adb',
+        args: ['install', '-r', reuseApkAbs],
+        cwd: repoRoot,
+        env: {
+          ...process.env,
+          ...(invocation.device ? { ANDROID_SERIAL: invocation.device } : {}),
+        },
+      });
+    } else {
+    const strategy = await resolveAndroidDevClientInstallStrategy({ env: process.env, cwd: repoRoot });
+    plan.strategy = strategy.kind;
+
+    if (strategy.kind === 'expo_run_android') {
+      plan.steps.push({ cmd: process.execPath, args: invocation.nodeArgs, cwd: rootDir, env: invocation.env });
+    } else if (strategy.kind === 'eas_local_dagger') {
+      const artifactOutRel = 'dist/ui-mobile/happier-dev-client-android.apk';
+      const outJsonRel = 'dist/ui-mobile/eas_build_dev_client_android.json';
+      const pipelineScript = `${repoRoot}/scripts/pipeline/run.mjs`;
+
+      plan.steps.push({
+        cmd: process.execPath,
+        args: [
+          pipelineScript,
+          'expo-native-build',
+          '--platform',
+          'android',
+          '--profile',
+          'development',
+          '--out',
+          outJsonRel,
+          '--build-mode',
+          'local',
+          '--local-runtime',
+          'dagger',
+          '--artifact-out',
+          artifactOutRel,
+          '--secrets-source',
+          'auto',
+          '--keychain-service',
+          'happier/pipeline',
+        ],
+        cwd: repoRoot,
+        env: invocation.env,
+      });
+
+      const copyArtifactScript = join(rootDir, 'scripts', 'utils', 'mobile', 'copy_artifact.mjs');
+      const artifactAbs = join(repoRoot, artifactOutRel);
+      plan.steps.push({
+        cmd: process.execPath,
+        args: [copyArtifactScript, '--from', artifactAbs, '--to', cachedApkAbs],
+        cwd: repoRoot,
+        env: process.env,
+      });
+
+      const hasAdb = await commandExists('adb', { cwd: repoRoot, env: process.env, timeoutMs: 5_000 });
+      if (hasAdb) {
+        plan.steps.push({
+          cmd: 'adb',
+          args: ['install', '-r', cachedApkAbs],
+          cwd: repoRoot,
+          env: {
+            ...process.env,
+            ...(invocation.device ? { ANDROID_SERIAL: invocation.device } : {}),
+          },
+        });
+      }
+    } else {
+      // Fail closed: keep behavior explicit when nothing is configured.
+      if (isTestStub) {
+        printResult({
+          json: true,
+          data: { ok: false, platform, strategy: strategy.kind, missing: strategy.missing, steps: [] },
+        });
+        return;
+      }
+      printResult({
+        json,
+        data: { ok: false, error: 'android_prereqs_missing', missing: strategy.missing },
+        text:
+          `[mobile-dev-client] Android tooling not configured.\n` +
+          `- To build/install on host: set ANDROID_HOME or ANDROID_SDK_ROOT and ensure adb+java are on PATH.\n` +
+          `- To use the pipeline fallback: ensure docker+dagger are on PATH, and provide Expo auth via EXPO_TOKEN or Keychain bundle (service 'happier/pipeline').\n` +
+          `Missing: ${strategy.missing.join(', ')}`,
+      });
+      process.exit(1);
+    }
+    }
+  } else {
+    plan.steps.push({ cmd: process.execPath, args: invocation.nodeArgs, cwd: rootDir, env: invocation.env });
+  }
+
+  if (isTestStub) {
+    const steps = plan.steps.map((s) => ({ cmd: s.cmd, args: s.args, cwd: s.cwd }));
+    printResult({ json: true, data: { ok: true, platform: plan.platform, strategy: plan.strategy, steps } });
+    return;
+  }
+
+  if (plan.steps.length === 0) {
+    throw new Error('[mobile-dev-client] internal error: empty plan');
+  }
+
+  for (const step of plan.steps) {
+    await run(step.cmd, step.args, { cwd: step.cwd, env: step.env });
+  }
 
-  const out = await run(process.execPath, invocation.nodeArgs, { cwd: rootDir, env });
   if (json) {
-    printResult({ json, data: { ok: true, installed: true, identity: invocation.identity, out } });
+    printResult({ json, data: { ok: true, installed: true, identity: invocation.identity, platform, strategy: plan.strategy } });
   }
 }