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

package/scripts/auth.mjs

@@ -12,6 +12,7 @@ import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { run, runCapture } from './utils/proc/proc.mjs';
@@ -22,11 +23,12 @@ import { clearDevAuthKey, readDevAuthKey, writeDevAuthKey } from './utils/auth/d
 import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
 import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
 import { copyFileIfMissing, linkFileIfMissing, removeFileOrSymlinkIfExists, writeSecretFileIfMissing } from './utils/auth/files.mjs';
+import { clearStackForceLoginCredentialPaths } from './utils/auth/clearStackForceLoginCredentialPaths.mjs';
 import { resolveHandyMasterSecretFromStack } from './utils/auth/handy_master_secret.mjs';
 import { ensureDir, readTextIfExists } from './utils/fs/ops.mjs';
 import { stackExistsSync } from './utils/stack/stacks.mjs';
 import { checkDaemonState } from './daemon.mjs';
-import { isTty, prompt, withRl } from './utils/cli/wizard.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
 import { parseCliIdentityOrThrow, resolveCliHomeDirForIdentity } from './utils/stack/cli_identities.mjs';
 import {
   getCliHomeDirFromEnvOrDefault,
@@ -39,6 +41,8 @@ import { bold, cyan, dim } from './utils/ui/ansi.mjs';
 import { getVerbosityLevel } from './utils/cli/verbosity.mjs';
 import { runOrchestratedGuidedAuthFlow, startDaemonPostAuth } from './utils/auth/orchestrated_stack_auth_flow.mjs';
 import { applyStackActiveServerScopeEnv } from './utils/auth/stable_scope_id.mjs';
+import { isLocalishUrl } from './utils/service/auth_guidance.mjs';
+import { resolveStackAuthCliExecutable } from './utils/auth/stack_guided_login.mjs';
 import {
   findAnyCredentialPathInCliHome,
   findExistingStackCredentialPath,
@@ -48,6 +52,7 @@ import { decodeJwtPayloadUnsafe } from './utils/auth/decode_jwt_payload_unsafe.m
 import { fileHasContent } from './utils/fs/file_has_content.mjs';
 import { buildConfigureServerLinks } from '@happier-dev/cli-common/links';
 import { getStackRuntimeStatePath, isPidAlive as isRuntimePidAlive, readStackRuntimeStateFile } from './utils/stack/runtime_state.mjs';
+import { resolveStackRuntimeLaunchContext } from './runtime/launch/resolveStackRuntimeLaunchContext.mjs';
 
 function resolveGuidedStartAction({ healthOk = false, runtimeOwnerAlive = false, autoStart = false } = {}) {
   if (healthOk) return 'proceed';
@@ -56,7 +61,31 @@ function resolveGuidedStartAction({ healthOk = false, runtimeOwnerAlive = false,
   return 'prompt';
 }
 
-function getInternalServerUrlCompat() {
+function resolveGuidedStackStartCommand({ stackName, startKind = 'dev' } = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+  if (startKind === 'runtime') {
+    return `hstack stack start ${name} --background --runtime`;
+  }
+  if (startKind === 'start') {
+    return `hstack stack start ${name} --background`;
+  }
+  return `hstack stack dev ${name} --background`;
+}
+
+async function getInternalServerUrlCompat() {
+  const stackName = getStackName();
+  try {
+    const statePath = getStackRuntimeStatePath(stackName);
+    const st = await readStackRuntimeStateFile(statePath);
+    const ownerPid = Number(st?.ownerPid);
+    const runtimeOwnerAlive = Number.isFinite(ownerPid) && ownerPid > 1 ? isRuntimePidAlive(ownerPid) : false;
+    const port = Number(st?.ports?.server);
+    if (runtimeOwnerAlive && Number.isFinite(port) && port > 0) {
+      return { port, url: `http://127.0.0.1:${port}` };
+    }
+  } catch {
+    // ignore; fall back to env/default port
+  }
   const { port, internalServerUrl } = getInternalServerUrl({ env: process.env, defaultPort: 3005 });
   return { port, url: internalServerUrl };
 }
@@ -216,6 +245,28 @@ function resolveGuidedServerReadyTimeoutMs(env = process.env) {
   return Number.isFinite(n) && n >= 1_000 ? n : 30_000;
 }
 
+function resolveAuthExpoSoftTimeoutMs(env = process.env) {
+  const raw = String(env.HAPPIER_STACK_AUTH_EXPO_SOFT_TIMEOUT_MS ?? '').trim();
+  if (!raw) return 120_000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 1 ? n : 120_000;
+}
+
+function resolveAuthExpoMaxTimeoutMs(env = process.env) {
+  const raw = String(env.HAPPIER_STACK_AUTH_EXPO_MAX_TIMEOUT_MS ?? '').trim();
+  if (!raw) return 900_000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 1 ? n : 900_000;
+}
+
+function formatDurationMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n <= 0) return `${ms}ms`;
+  if (n < 60_000) return `${Math.round(n / 1000)}s`;
+  const m = Math.round(n / 60_000);
+  return `${m}m`;
+}
+
 async function isStackRuntimeOwnerAlive(stackName) {
   try {
     const statePath = getStackRuntimeStatePath(stackName);
@@ -256,7 +307,7 @@ async function cmdSeed({ argv, json }) {
 }
 
 async function cmdDevKey({ argv, json }) {
-  const { flags, kv } = parseArgs(argv);
+  const { flags, kv: argKv } = parseArgs(argv);
 
   // parseArgs currently only supports --k=v, but UX/docs commonly use: --k "value".
   // Support both forms here (without changing global parsing semantics).
@@ -278,14 +329,14 @@ async function cmdDevKey({ argv, json }) {
   };
 
   const wantPrint = flags.has('--print');
-  const fmtRaw = (argvKvValue('--format') || (kv.get('--format') ?? '')).trim();
+  const fmtRaw = (argvKvValue('--format') || (argKv.get('--format') ?? '')).trim();
   // UX: the Happy UI restore screen expects the "backup" (XXXXX-...) format.
   //
   // IMPORTANT: the Happy restore screen treats any key containing '-' as "backup format",
   // so printing a base64url key (which may contain '-') is *not reliably pasteable*.
   // Default to backup always unless explicitly overridden.
   const fmt = fmtRaw || 'backup'; // base64url | backup
-  const set = (argvKvValue('--set') || (kv.get('--set') ?? '')).trim();
+  const set = (argvKvValue('--set') || (argKv.get('--set') ?? '')).trim();
   const clear = flags.has('--clear');
 
   if (set) {
@@ -448,11 +499,26 @@ function resolveLightDirsForStack({ env, baseDir }) {
   return { dataDir, filesDir, dbDir };
 }
 
-function resolveDbProviderForLightFromEnv(env) {
+export function buildLightMigrationBaseEnv(processEnv, envIn) {
+  const baseEnv = { ...(processEnv && typeof processEnv === 'object' ? processEnv : {}) };
+  delete baseEnv.DATABASE_URL;
+  delete baseEnv.HAPPIER_SERVER_LIGHT_DATA_DIR;
+  delete baseEnv.HAPPIER_SERVER_LIGHT_FILES_DIR;
+  delete baseEnv.HAPPIER_SERVER_LIGHT_DB_DIR;
+  delete baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR;
+  delete baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR;
+  delete baseEnv.HAPPY_SERVER_LIGHT_DB_DIR;
+  delete baseEnv.HAPPIER_DB_PROVIDER;
+  delete baseEnv.HAPPY_DB_PROVIDER;
+  return { ...baseEnv, ...(envIn && typeof envIn === 'object' ? envIn : {}) };
+}
+
+export function resolveDbProviderForLightFromEnv(env) {
   const raw = (env.HAPPIER_DB_PROVIDER ?? env.HAPPY_DB_PROVIDER ?? '').toString().trim().toLowerCase();
   if (raw === 'sqlite') return 'sqlite';
-  // Default for light flavor (embedded Postgres via pglite).
-  return 'pglite';
+  if (raw === 'pglite') return 'pglite';
+  // Default for light flavor.
+  return 'sqlite';
 }
 
 function resolveDbProviderForFullFromEnv(env) {
@@ -468,7 +534,7 @@ function resolveSqliteDatabaseUrlForLight({ dataDir }) {
 async function ensureLightMigrationsApplied({ serverDir, baseDir, envIn, quiet = false }) {
   // IMPORTANT: envIn is often parsed from a stack env file (so it does not include PATH).
   // Start from the current process env so we can spawn Yarn reliably, then overlay stack-specific vars.
-  const env = { ...process.env, ...(envIn && typeof envIn === 'object' ? envIn : {}) };
+  const env = buildLightMigrationBaseEnv(process.env, envIn);
   const { dataDir, filesDir, dbDir } = resolveLightDirsForStack({ env, baseDir });
   env.HAPPIER_SERVER_LIGHT_DATA_DIR = dataDir;
   env.HAPPIER_SERVER_LIGHT_FILES_DIR = filesDir;
@@ -887,13 +953,13 @@ async function cmdCopyFrom({ argv, json }) {
 
   const positionals = argv.filter((a) => !a.startsWith('--'));
   const fromStackName = (positionals[1] ?? '').trim();
-  if (!fromStackName) {
-    throw new Error(
-      '[auth] usage: hstack stack auth <name> copy-from <sourceStack> [--force] [--with-infra] [--json]  OR  hstack auth copy-from <sourceStack> --all [--except=main,dev-auth] [--force] [--with-infra] [--json]\n' +
-        'notes:\n' +
-        '  - sourceStack can be a stack name (e.g. main, dev-auth)'
-    );
-  }
+	  if (!fromStackName) {
+	    throw new Error(
+	      '[auth] usage: hstack stack auth <name> copy-from <sourceStack> [--force] [--with-infra] [--offline-ok] [--json]  OR  hstack auth copy-from <sourceStack> --all [--except=main,dev-auth] [--force] [--with-infra] [--offline-ok] [--json]\n' +
+	        'notes:\n' +
+	        '  - sourceStack can be a stack name (e.g. main, dev-auth)'
+	    );
+	  }
 
   const { flags, kv } = parseArgs(argv);
   const all = flags.has('--all');
@@ -902,16 +968,26 @@ async function cmdCopyFrom({ argv, json }) {
     flags.has('--overwrite') ||
     (kv.get('--force') ?? '').trim() === '1' ||
     (kv.get('--overwrite') ?? '').trim() === '1';
-  const withInfra =
-    flags.has('--with-infra') ||
-    flags.has('--ensure-infra') ||
-    flags.has('--infra') ||
-    (kv.get('--with-infra') ?? '').trim() === '1' ||
-    (kv.get('--ensure-infra') ?? '').trim() === '1';
-  const linkMode =
-    flags.has('--link') ||
-    flags.has('--symlink') ||
-    flags.has('--link-auth') ||
+	  const withInfra =
+	    flags.has('--with-infra') ||
+	    flags.has('--ensure-infra') ||
+	    flags.has('--infra') ||
+	    (kv.get('--with-infra') ?? '').trim() === '1' ||
+	    (kv.get('--ensure-infra') ?? '').trim() === '1';
+	  const offlineOk =
+	    flags.has('--offline-ok') ||
+	    flags.has('--offline') ||
+	    (kv.get('--offline-ok') ?? '').trim() === '1' ||
+	    (kv.get('--offline') ?? '').trim() === '1';
+	  const noSecret =
+	    flags.has('--no-secret') ||
+	    flags.has('--skip-secret') ||
+	    (kv.get('--no-secret') ?? '').trim() === '1' ||
+	    (kv.get('--skip-secret') ?? '').trim() === '1';
+	  const linkMode =
+	    flags.has('--link') ||
+	    flags.has('--symlink') ||
+	    flags.has('--link-auth') ||
     (kv.get('--link') ?? '').trim() === '1' ||
     (kv.get('--symlink') ?? '').trim() === '1' ||
     (kv.get('--auth-mode') ?? '').trim() === 'link' ||
@@ -1086,7 +1162,7 @@ async function cmdCopyFrom({ argv, json }) {
     stackName,
     cliIdentity: 'default',
   });
-  const { url: targetInternalServerUrl } = getInternalServerUrlCompat();
+  const { url: targetInternalServerUrl } = await getInternalServerUrlCompat();
   const targetCredentialPaths = resolveStackCredentialPaths({
     cliHomeDir: targetCli,
     serverUrl: targetInternalServerUrl,
@@ -1143,15 +1219,21 @@ async function cmdCopyFrom({ argv, json }) {
     return await listAccountsFromPostgres({ cwd: sourceCwd, clientImport: sourceClientImport, databaseUrl: fromDatabaseUrl });
   };
 
-  let sourceAccounts = null;
-  const sourceTokenSubject = resolveJwtSubjectFromCredentialPath(sourceCredentialPath);
-  let sourceTokenValidation = null;
-  const sourceRuntimeOwnerAlive = await isStackRuntimeOwnerAlive(fromStackName);
-  if (sourceCredentialPath && sourceRuntimeOwnerAlive) {
-    sourceTokenValidation = await validateAuthTokenAgainstServer({
-      credentialPath: sourceCredentialPath,
-      internalServerUrl: sourceInternalServerUrl,
-    });
+	  let sourceAccounts = null;
+	  const sourceTokenSubject = resolveJwtSubjectFromCredentialPath(sourceCredentialPath);
+	  let sourceTokenValidation = null;
+	  const sourceRuntimeOwnerAlive = await isStackRuntimeOwnerAlive(fromStackName);
+	  if (sourceCredentialPath && !sourceRuntimeOwnerAlive && !offlineOk) {
+	    throw new Error(
+	      `[auth] source stack "${fromStackName}" does not appear to be running (no live stack.runtime.json). ` +
+	        `Start the source stack and retry, or re-run with --offline-ok to copy credentials without live server validation.`
+	    );
+	  }
+	  if (sourceCredentialPath && sourceRuntimeOwnerAlive) {
+	    sourceTokenValidation = await validateAuthTokenAgainstServer({
+	      credentialPath: sourceCredentialPath,
+	      internalServerUrl: sourceInternalServerUrl,
+	    });
     if (sourceTokenValidation.checked && sourceTokenValidation.valid === false) {
       const status = sourceTokenValidation.status != null ? sourceTokenValidation.status : 'error';
       const code = sourceTokenValidation.code ? `/${sourceTokenValidation.code}` : '';
@@ -1182,12 +1264,12 @@ async function cmdCopyFrom({ argv, json }) {
     }
   }
 
-  if (secret) {
-    if (serverComponent === 'happier-server-light') {
-      const target = join(targetServerLightDataDir, 'handy-master-secret.txt');
-      const sourcePath = source && !String(source).includes('(HANDY_MASTER_SECRET)') ? String(source) : '';
-      if (linkMode && sourcePath && existsSync(sourcePath)) {
-        copied.secret = await linkFileIfMissing({ from: sourcePath, to: target, force });
+	  if (secret && !noSecret) {
+	    if (serverComponent === 'happier-server-light') {
+	      const target = join(targetServerLightDataDir, 'handy-master-secret.txt');
+	      const sourcePath = source && !String(source).includes('(HANDY_MASTER_SECRET)') ? String(source) : '';
+	      if (linkMode && sourcePath && existsSync(sourcePath)) {
+	        copied.secret = await linkFileIfMissing({ from: sourcePath, to: target, force });
       } else {
         copied.secret = await writeSecretFileIfMissing({ path: target, secret, force });
       }
@@ -1278,7 +1360,7 @@ async function cmdCopyFrom({ argv, json }) {
         // so we can seed DB accounts reliably.
         const managed = (targetEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1').toString().trim() !== '0';
 	        if (targetServerComponent === 'happier-server' && targetDbProvider === 'postgres' && withInfra && managed) {
-          const { port } = getInternalServerUrlCompat();
+          const { port } = await getInternalServerUrlCompat();
           const publicServerUrl = await preferStackLocalhostUrl(`http://localhost:${port}`, { stackName });
           const envPath = resolveStackEnvPath(stackName).envPath;
           const infra = await ensureHappyServerManagedInfra({
@@ -1364,7 +1446,7 @@ async function cmdStatus({ json }) {
   const { kv } = parseArgs(argv);
   const identity = parseCliIdentityOrThrow((kv.get('--identity') ?? '').trim());
 
-  const { port, url: internalServerUrl } = getInternalServerUrlCompat();
+  const { port, url: internalServerUrl } = await getInternalServerUrlCompat();
   const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port, stackName });
   const { publicServerUrl } = await resolvePublicServerUrl({
     internalServerUrl,
@@ -1499,7 +1581,7 @@ async function cmdLogin({ argv, json }) {
   const { flags, kv } = parseArgs(argv);
 
   const tty = isTty();
-  const { port, url: internalServerUrl } = getInternalServerUrlCompat();
+  const { port, url: internalServerUrl } = await getInternalServerUrlCompat();
   const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port, stackName });
   const { publicServerUrl } = await resolvePublicServerUrl({
     internalServerUrl,
@@ -1511,37 +1593,56 @@ async function cmdLogin({ argv, json }) {
 
   const webappModeRaw =
     (argvKvValue(argv, '--webapp') || (kv.get('--webapp') ?? '')).toString().trim().toLowerCase();
-  const webappMode = webappModeRaw || 'auto'; // auto|stack|public|expo|hosted
+  const requestedWebappMode = webappModeRaw || 'auto'; // auto|stack|public|expo|hosted
+  const HOSTED_WEBAPP_URL = 'https://app.happier.dev';
   const explicitWebappUrl =
     (argvKvValue(argv, '--webapp-url') || (kv.get('--webapp-url') ?? '')).toString().trim();
   const methodRaw = (argvKvValue(argv, '--method') || (kv.get('--method') ?? '')).toString().trim().toLowerCase();
-  const method = methodRaw === 'mobile' ? 'mobile' : methodRaw === 'web' || methodRaw === 'browser' ? 'web' : '';
+  let method = methodRaw === 'mobile' ? 'mobile' : methodRaw === 'web' || methodRaw === 'browser' ? 'web' : '';
   if (methodRaw && !method) {
     throw new Error(`[auth] login: invalid --method=${methodRaw} (expected: web|browser|mobile)`);
   }
 
   const { envWebappUrl } = getWebappUrlEnvOverride({ env: process.env, stackName });
   const expoWebappUrl = await resolveWebappUrlFromRunningExpo({ rootDir, stackName });
+  const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv: [], env: process.env });
+  const runtimeSnapshotActive = Boolean(runtimeLaunchContext.snapshot);
+
+  const serviceMode = (process.env.HAPPIER_STACK_SERVICE_MODE ?? '').toString().trim() === '1';
+  const wantsDefaultExpoInAuto =
+    requestedWebappMode === 'auto' &&
+    !explicitWebappUrl &&
+    !envWebappUrl &&
+    method !== 'mobile' &&
+    tty &&
+    !serviceMode &&
+    !runtimeSnapshotActive;
+  const effectiveWebappMode = wantsDefaultExpoInAuto ? 'expo' : requestedWebappMode;
+  const shouldUseRuntimeStart = runtimeSnapshotActive && effectiveWebappMode !== 'expo';
+  const guidedStartKind = shouldUseRuntimeStart ? 'runtime' : effectiveWebappMode === 'expo' ? 'dev' : 'start';
+  const guidedStartCommand = resolveGuidedStackStartCommand({
+    stackName,
+    startKind: guidedStartKind,
+  });
 
   let webappUrlRaw = '';
   let webappUrlSource = '';
   if (explicitWebappUrl) {
     webappUrlRaw = explicitWebappUrl;
     webappUrlSource = 'webapp-url flag';
-  } else if (webappMode === 'public') {
+  } else if (effectiveWebappMode === 'public') {
     webappUrlRaw = publicServerUrl;
     webappUrlSource = 'public server';
-  } else if (webappMode === 'hosted') {
-    // Use happier-cli defaults (do not force a URL here).
-    webappUrlRaw = '';
-    webappUrlSource = 'cli default';
-  } else if (webappMode === 'expo') {
+  } else if (effectiveWebappMode === 'hosted') {
+    webappUrlRaw = HOSTED_WEBAPP_URL;
+    webappUrlSource = 'hosted';
+  } else if (effectiveWebappMode === 'expo') {
     webappUrlRaw = expoWebappUrl || '';
     webappUrlSource = 'expo';
   } else {
     // auto|stack: preserve existing ordering for now (env override wins unless explicitly forced otherwise).
-    webappUrlRaw = envWebappUrl || expoWebappUrl || publicServerUrl;
-    webappUrlSource = envWebappUrl ? 'stack env override' : expoWebappUrl ? 'expo' : 'server';
+    webappUrlRaw = runtimeSnapshotActive ? envWebappUrl || publicServerUrl || expoWebappUrl : envWebappUrl || expoWebappUrl || publicServerUrl;
+    webappUrlSource = envWebappUrl ? 'stack env override' : runtimeSnapshotActive ? (publicServerUrl ? 'server' : expoWebappUrl ? 'expo' : 'server') : expoWebappUrl ? 'expo' : 'server';
   }
 
   const webappUrl = webappUrlRaw ? await preferStackLocalhostUrl(webappUrlRaw, { stackName }) : '';
@@ -1553,7 +1654,6 @@ async function cmdLogin({ argv, json }) {
 
   const identity = parseCliIdentityOrThrow((kv.get('--identity') ?? '').trim());
   const cliHomeDir = resolveCliHomeDirForIdentity({ cliHomeDir: resolveCliHomeDir(), identity });
-  const cliBin = join(getComponentDir(rootDir, 'happier-cli'), 'bin', 'happier.mjs');
 
   const force =
     argv.includes('--force') ||
@@ -1561,17 +1661,6 @@ async function cmdLogin({ argv, json }) {
   const wantPrint = argv.includes('--print');
   const noOpen = flags.has('--no-open') || flags.has('--no-browser') || flags.has('--no-browser-open');
 
-  const nodeArgs = [cliBin, 'auth', 'login'];
-  if (force || argv.includes('--force')) {
-    nodeArgs.push('--force');
-  }
-  if (noOpen) {
-    nodeArgs.push('--no-open');
-  }
-  if (method) {
-    nodeArgs.push('--method', method);
-  }
-
   let env = {
     ...process.env,
     HAPPIER_HOME_DIR: cliHomeDir,
@@ -1583,20 +1672,37 @@ async function cmdLogin({ argv, json }) {
     ...(force ? { HAPPIER_AUTH_FORCE: '1' } : {}),
   };
   env = applyStackActiveServerScopeEnv({ env, stackName, cliIdentity: identity });
+  const credentialPaths = resolveStackCredentialPaths({ cliHomeDir, serverUrl: internalServerUrl, env });
+  const loginEnv =
+    credentialPaths.activeServerId && credentialPaths.activeServerId !== env.HAPPIER_ACTIVE_SERVER_ID
+      ? { ...env, HAPPIER_ACTIVE_SERVER_ID: credentialPaths.activeServerId }
+      : env;
+
+  const cliExecutable = await resolveStackAuthCliExecutable({ rootDir, env: loginEnv });
+  const executableLooksLikeScript =
+    cliExecutable.endsWith('.mjs') || cliExecutable.endsWith('.js') || cliExecutable.endsWith('.cjs');
+  const loginCommand = executableLooksLikeScript ? process.execPath : cliExecutable;
+  let loginArgs = executableLooksLikeScript ? [cliExecutable, 'auth', 'login'] : ['auth', 'login'];
+  if (force || argv.includes('--force')) {
+    loginArgs.push('--force');
+  }
+  if (noOpen) {
+    loginArgs.push('--no-open');
+  }
+  if (method) {
+    loginArgs.push('--method', method);
+  }
 
   if (wantPrint) {
     const cmd =
       `HAPPIER_HOME_DIR="${cliHomeDir}" ` +
       `HAPPIER_SERVER_URL="${internalServerUrl}" ` +
       `HAPPIER_PUBLIC_SERVER_URL="${publicServerUrl}" ` +
-      (env.HAPPIER_ACTIVE_SERVER_ID ? `HAPPIER_ACTIVE_SERVER_ID="${env.HAPPIER_ACTIVE_SERVER_ID}" ` : '') +
+      (loginEnv.HAPPIER_ACTIVE_SERVER_ID ? `HAPPIER_ACTIVE_SERVER_ID="${loginEnv.HAPPIER_ACTIVE_SERVER_ID}" ` : '') +
       (webappUrl ? `HAPPIER_WEBAPP_URL="${webappUrl}" ` : '') +
       (noOpen ? `HAPPIER_NO_BROWSER_OPEN="1" ` : '') +
       (method ? `HAPPIER_AUTH_METHOD="${method}" ` : '') +
-      `node "${cliBin}" auth login` +
-      (nodeArgs.includes('--force') ? ' --force' : '') +
-      (noOpen ? ' --no-open' : '') +
-      (method ? ` --method ${method}` : '');
+      `"${loginCommand}" ${loginArgs.map((arg) => `"${arg}"`).join(' ')}`;
 
     const configureServer =
       webappUrl && publicServerUrl
@@ -1642,7 +1748,7 @@ async function cmdLogin({ argv, json }) {
       throw new Error(
         `[auth] ${stackName}: server did not become healthy in time (${guidedReadyTimeoutMs}ms) while ${reason}.\n` +
           `[auth] Start it manually:\n` +
-          `  hstack stack dev ${stackName} --background`
+          `  ${guidedStartCommand}`
       );
     }
   };
@@ -1659,7 +1765,42 @@ async function cmdLogin({ argv, json }) {
     if (action === 'wait') {
       // eslint-disable-next-line no-console
       console.error(`[auth] ${stackName}: stack runtime is already starting; waiting for health before guided login...`);
-      await waitForGuidedServerReadyOrThrow('already starting');
+      if (serviceMode && method !== 'web') {
+        // Service-mode stacks tend to be the crash-looping case: auth must not sit around
+        // waiting for a UI that is not going to stabilize. Fall back immediately to mobile.
+        // eslint-disable-next-line no-console
+        console.error(`[auth] ${stackName}: service-mode stack is not becoming healthy; falling back to mobile login.`);
+        method = 'mobile';
+        env.HAPPIER_AUTH_METHOD = 'mobile';
+        const methodIdx = loginArgs.indexOf('--method');
+        if (methodIdx >= 0) {
+          loginArgs[methodIdx + 1] = 'mobile';
+        } else {
+          loginArgs = [...loginArgs, '--method', 'mobile'];
+        }
+      } else {
+        try {
+          await waitForGuidedServerReadyOrThrow('already starting');
+        } catch (waitErr) {
+          if (method === 'web') {
+            throw waitErr;
+          }
+          // The runtime is alive but the UI is not becoming healthy. Fall back to mobile auth so
+          // the user can still complete authentication without a browser-backed stack UI.
+          // eslint-disable-next-line no-console
+          console.error(
+            `[auth] ${stackName}: the stack UI did not become healthy in time; falling back to mobile login.`
+          );
+          method = 'mobile';
+          env.HAPPIER_AUTH_METHOD = 'mobile';
+          const methodIdx = loginArgs.indexOf('--method');
+          if (methodIdx >= 0) {
+            loginArgs[methodIdx + 1] = 'mobile';
+          } else {
+            loginArgs = [...loginArgs, '--method', 'mobile'];
+          }
+        }
+      }
     } else {
       let startOk = action === 'start';
       if (!startOk) {
@@ -1667,7 +1808,7 @@ async function cmdLogin({ argv, json }) {
           throw new Error(
             `[auth] ${stackName}: cannot run guided login because the stack is not running in non-interactive mode.\n` +
               `[auth] Re-run with --start-if-needed or start it manually:\n` +
-              `  hstack stack dev ${stackName} --background`
+              `  ${guidedStartCommand}`
           );
         }
         startOk = await withRl(async (rl) => {
@@ -1682,22 +1823,30 @@ async function cmdLogin({ argv, json }) {
       if (!startOk) {
         throw new Error(
           `[auth] ${stackName}: cannot run guided login because the stack is not running.\n` +
-            `[auth] Start it with: hstack stack dev ${stackName} --background`
+            `[auth] Start it with: ${guidedStartCommand}`
         );
       }
 
       await run(
         process.execPath,
-        [join(rootDir, 'scripts', 'stack.mjs'), 'dev', stackName, '--background', '--no-daemon', '--no-browser'],
+        [
+          join(rootDir, 'scripts', 'stack.mjs'),
+          shouldUseRuntimeStart ? 'start' : effectiveWebappMode === 'expo' ? 'dev' : 'start',
+          stackName,
+          '--background',
+          ...(shouldUseRuntimeStart ? ['--runtime'] : []),
+          '--no-daemon',
+          '--no-browser',
+        ],
         {
           cwd: rootDir,
-          env: { ...process.env, HAPPIER_STACK_AUTH_FLOW: '1' },
+          env: { ...process.env, ...(!shouldUseRuntimeStart && effectiveWebappMode === 'expo' ? { HAPPIER_STACK_AUTH_FLOW: '1' } : {}) },
         }
       ).catch((err) => {
         const msg =
           `[auth] ${stackName}: failed to start the stack for guided login.\n` +
           `[auth] Try starting it manually:\n` +
-          `  hstack stack dev ${stackName} --background\n\n` +
+          `  ${guidedStartCommand}\n\n` +
           `${String(err?.stack ?? err)}`;
         throw new Error(msg);
       });
@@ -1707,29 +1856,169 @@ async function cmdLogin({ argv, json }) {
   }
 
   const verbosity = getVerbosityLevel(process.env);
-  const guidedEnv = applyStackActiveServerScopeEnv({
-    env: { ...env, HAPPIER_STACK_AUTH_FLOW: '1' },
-    stackName,
-    cliIdentity: identity,
-  });
-  const guided = await runOrchestratedGuidedAuthFlow({
-    rootDir,
-    stackName,
-    env: guidedEnv,
-    verbosity,
-    json: false,
-  });
+  const scopedEnv = loginEnv;
+  let clearedForceCredentials = false;
+  const runLogin = async (runEnv) => {
+    if (force && !clearedForceCredentials) {
+      await clearStackForceLoginCredentialPaths({
+        cliHomeDir,
+        serverUrl: internalServerUrl,
+        env,
+      });
+      clearedForceCredentials = true;
+    }
+    await run(loginCommand, loginArgs, { cwd: rootDir, env: runEnv });
+  };
 
-  const daemonStart = await startDaemonPostAuth({
-    rootDir,
-    stackName,
-    env: guidedEnv,
-    forceRestart: true,
-    webappUrl: guided?.webappUrl,
-  });
-  if (daemonStart?.ok === false) {
+  let webappUrlForDaemon = webappUrl;
+  if (method !== 'mobile' && effectiveWebappMode === 'expo') {
+    const guidedEnv = applyStackActiveServerScopeEnv({
+      env: { ...scopedEnv, HAPPIER_STACK_AUTH_FLOW: '1' },
+      stackName,
+      cliIdentity: identity,
+    });
+    const publicIsLocalish = isLocalishUrl(publicServerUrl);
+
+    // Auto mode is "local-first": try Expo first (but avoid making users think it's stalled).
+    // If Expo doesn't become ready within a soft timeout, offer safe fallbacks.
+    if (requestedWebappMode === 'auto') {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[auth] ${stackName}: starting guided login via the stack’s Expo web UI (local-first).\n` +
+          `[auth] This can take several minutes on the first run while the stack starts and the web bundle builds.`
+      );
+    }
+
+    const baseSoftTimeoutMs = requestedWebappMode === 'auto' ? resolveAuthExpoSoftTimeoutMs(process.env) : null;
+    const maxTimeoutMs = requestedWebappMode === 'auto' ? resolveAuthExpoMaxTimeoutMs(process.env) : null;
+    let attemptTimeoutMs = baseSoftTimeoutMs;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        const guided = await runOrchestratedGuidedAuthFlow({
+          rootDir,
+          stackName,
+          env:
+            requestedWebappMode === 'auto' && attemptTimeoutMs
+              ? {
+                  ...guidedEnv,
+                  HAPPIER_STACK_AUTH_UI_READY_TIMEOUT_MS: String(attemptTimeoutMs),
+                  HAPPIER_STACK_AUTH_EXPO_BUNDLE_READY_TIMEOUT_MS: String(attemptTimeoutMs),
+                }
+              : guidedEnv,
+          verbosity,
+          json: false,
+        });
+        webappUrlForDaemon = guided?.webappUrl || webappUrlForDaemon;
+        break;
+      } catch (e) {
+        if (requestedWebappMode === 'expo') {
+          throw e;
+        }
+        if (publicIsLocalish) {
+          // Hosted/mobile can't reach localhost; fail closed and let the error surface.
+          throw e;
+        }
+
+        if (!tty) {
+          // Non-interactive: default to the most reliable completion path.
+          // eslint-disable-next-line no-console
+          console.error(
+            `[auth] ${stackName}: Expo web UI is not ready yet.\n` +
+              `[auth] Falling back to hosted web app (${HOSTED_WEBAPP_URL}) for the approval UI (targets: ${publicServerUrl}).`
+          );
+          const hostedEnv = { ...scopedEnv, HAPPIER_WEBAPP_URL: HOSTED_WEBAPP_URL };
+          await runLogin(hostedEnv);
+          webappUrlForDaemon = HOSTED_WEBAPP_URL;
+          break;
+        }
+
+        const choice = await withRl(async (rl) => {
+          const timeoutText = attemptTimeoutMs ? formatDurationMs(attemptTimeoutMs) : '';
+          const title =
+            `[auth] ${stackName}: Expo web UI is not ready yet` +
+            (timeoutText ? ` (waited ~${timeoutText})` : '') +
+            `.\n` +
+            `[auth] First-time web builds can take several minutes.`;
+          return await promptSelect(rl, {
+            title,
+            options: [
+              { label: 'keep waiting for Expo (recommended)', value: 'wait' },
+              { label: `use hosted web app for approval UI (${HOSTED_WEBAPP_URL}) — still logs into your stack`, value: 'hosted' },
+              { label: 'use mobile QR / deep link (no browser; requires a public URL)', value: 'mobile' },
+              { label: 'cancel and show error', value: 'cancel' },
+            ],
+            defaultIndex: 0,
+          });
+        });
+
+        if (choice === 'cancel') {
+          throw e;
+        }
+        if (choice === 'hosted') {
+          // eslint-disable-next-line no-console
+          console.error(
+            `[auth] ${stackName}: falling back to hosted web app (${HOSTED_WEBAPP_URL}) for the approval UI (targets: ${publicServerUrl}).`
+          );
+          const hostedEnv = { ...scopedEnv, HAPPIER_WEBAPP_URL: HOSTED_WEBAPP_URL };
+          await runLogin(hostedEnv);
+          webappUrlForDaemon = HOSTED_WEBAPP_URL;
+          break;
+        }
+        if (choice === 'mobile') {
+          // eslint-disable-next-line no-console
+          console.error(`[auth] ${stackName}: switching to mobile login (targets: ${publicServerUrl}).`);
+          const mobileArgs = [...loginArgs];
+          if (!mobileArgs.includes('--method')) {
+            mobileArgs.push('--method', 'mobile');
+          } else {
+            const idx = mobileArgs.indexOf('--method');
+            if (idx >= 0) {
+              mobileArgs[idx + 1] = 'mobile';
+            }
+          }
+          if (force && !clearedForceCredentials) {
+            await clearStackForceLoginCredentialPaths({
+              cliHomeDir,
+              serverUrl: internalServerUrl,
+              env,
+            });
+            clearedForceCredentials = true;
+          }
+          await run(loginCommand, mobileArgs, { cwd: rootDir, env: scopedEnv });
+          break;
+        }
+
+        // wait: increase timeout and retry
+        const next = attemptTimeoutMs ? Math.min(attemptTimeoutMs * 2, maxTimeoutMs ?? attemptTimeoutMs * 2) : null;
+        attemptTimeoutMs = next;
+        // eslint-disable-next-line no-console
+        console.error(
+          `[auth] ${stackName}: continuing to wait for Expo...` +
+            (attemptTimeoutMs ? ` (next timeout: ${formatDurationMs(attemptTimeoutMs)})` : '')
+        );
+      }
+    }
+  } else {
+    await runLogin(scopedEnv);
+  }
+
+  try {
+    const daemonStart = await startDaemonPostAuth({
+      rootDir,
+      stackName,
+      env: scopedEnv,
+      forceRestart: true,
+      webappUrl: webappUrlForDaemon,
+    });
+    if (daemonStart?.ok === false) {
+      // eslint-disable-next-line no-console
+      console.error(daemonStart.error ?? `[auth] ${stackName}: post-auth daemon start verification timed out`);
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
     // eslint-disable-next-line no-console
-    console.error(daemonStart.error ?? `[auth] ${stackName}: post-auth daemon start verification timed out`);
+    console.error(`[auth] ${stackName}: post-auth daemon start failed (non-fatal): ${msg}`);
   }
   return;
 }
@@ -1748,7 +2037,7 @@ async function main() {
   const usageByCmd = new Map([
     ['status', 'hstack auth status [--json]'],
     ['login', 'hstack auth login [--identity=<name>] [--no-open] [--force] [--method=web|mobile] [--print] [--webapp=auto|stack|public|expo|hosted] [--webapp-url=<url>] [--start-if-needed] [--json]'],
-    ['seed', 'hstack auth seed [name=dev-auth] [--login|--no-login] [--server=...] [--skip-default-seed] [--non-interactive] [--json]'],
+    ['seed', 'hstack auth seed [name=dev-auth] [--login|--no-login] [--force] [--server=...] [--skip-default-seed] [--non-interactive] [--json]'],
     ['copy-from', 'hstack auth copy-from <sourceStack|legacy> --all [--except=main,dev-auth] [--force] [--with-infra] [--link] [--json]'],
     ['dev-key', 'hstack auth dev-key [--print] [--format=base64url|backup] [--set=<secret>] [--clear] [--json]'],
   ]);
@@ -1777,7 +2066,7 @@ async function main() {
         bullets([
           `${dim('status:')} ${cmdFmt('hstack auth status')} ${dim('[--json]')}`,
           `${dim('login:')}  ${cmdFmt('hstack auth login')} ${dim('[--identity=<name>] [--no-open] [--force] [--method=web|mobile] [--print] [--webapp=auto|stack|public|expo|hosted] [--webapp-url=<url>] [--start-if-needed] [--json]')}`,
-          `${dim('seed stack:')} ${cmdFmt('hstack auth seed')} ${dim('[name=dev-auth] [--login|--no-login] [--server=...] [--skip-default-seed] [--non-interactive] [--json]')}`,
+          `${dim('seed stack:')} ${cmdFmt('hstack auth seed')} ${dim('[name=dev-auth] [--login|--no-login] [--force] [--server=...] [--skip-default-seed] [--non-interactive] [--json]')}`,
           `${dim('seed:')}   ${cmdFmt('hstack auth copy-from <sourceStack|legacy> --all')} ${dim('[--except=main,dev-auth] [--force] [--with-infra] [--link] [--json]')}`,
           `${dim('dev key:')} ${cmdFmt('hstack auth dev-key')} ${dim('[--print] [--format=base64url|backup] [--set=<secret>] [--clear] [--json]')}`,
         ]),
@@ -1823,7 +2112,10 @@ async function main() {
   throw new Error(`[auth] unknown command: ${cmd}`);
 }
 
-main().catch((err) => {
-  console.error('[auth] failed:', err);
-  process.exit(1);
-});
+const isMainModule = process.argv[1] ? fileURLToPath(import.meta.url) === process.argv[1] : false;
+if (isMainModule) {
+  main().catch((err) => {
+    console.error('[auth] failed:', err);
+    process.exit(1);
+  });
+}