@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/scripts/stack.mjs

@@ -8,6 +8,7 @@ import { ensureDir, readTextIfExists, readTextOrEmpty } from './utils/fs/ops.mjs
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { killProcessTree, run, runCapture } from './utils/proc/proc.mjs';
+import { resolveServerShutdownGraceMs } from './utils/server/shutdown_grace.mjs';
 import {
   coerceHappyMonorepoRootFromPath,
   getComponentDir,
@@ -35,6 +36,7 @@ import { normalizeStackNameFirstArgs, resolveTopLevelNodeScriptFile, stackNameFr
 import { getStackHelpUsageLine, renderStackRootHelpText, renderStackSubcommandHelpText, STACK_HELP_COMMANDS } from './stack/help_text.mjs';
 import { copyAuthFromStackIntoNewStack } from './stack/copy_auth_from_stack.mjs';
 import {
+  createStackEnv,
   getRuntimePortExtraEnv,
   parseServerComponentFromEnv,
   readStackEnvObject,
@@ -43,6 +45,7 @@ import {
   writeStackEnv,
 } from './stack/stack_environment.mjs';
 import { cmdAuth, cmdListStacks, cmdRuntime, cmdService, cmdSrv, cmdTailscale, cmdWt } from './stack/delegated_script_commands.mjs';
+import { disableInstalledStackServicesBeforeArchive } from './utils/service/archive_service_lifecycle.mjs';
 import { runStackDaemonCommand } from './stack/stack_daemon_command.mjs';
 import { runStackHappierPassthroughCommand } from './stack/stack_happier_passthrough_command.mjs';
 import { runStackMobileInstallCommand } from './stack/stack_mobile_install_command.mjs';
@@ -54,6 +57,7 @@ import { printDelegatedStackHelpIfAvailable } from './stack/stack_delegated_help
 import { runStackWorkspaceCommand } from './stack/stack_workspace_command.mjs';
 import { resolveRequestedRepoCheckoutDir } from './stack/repo_checkout_resolution.mjs';
 import { resolveTransientRepoOverrides } from './stack/transient_repo_overrides.mjs';
+import { runStackInstallCommand } from './stack/stack_install_command.mjs';
 import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env/env_file.mjs';
 import { listAllStackNames, stackExistsSync } from './utils/stack/stacks.mjs';
 import { writeDevAuthKey } from './utils/auth/dev_key.mjs';
@@ -61,6 +65,12 @@ import { startDevServer } from './utils/dev/server.mjs';
 import { ensureDevExpoServer } from './utils/dev/expo_dev.mjs';
 import { requireDir } from './utils/proc/pm.mjs';
 import { waitForHttpOk } from './utils/server/server.mjs';
+import {
+  isCanonicalManagedPostgresAuthority,
+  resolveDbProviderDatabaseUrl,
+  resolveEffectiveDbProvider,
+  resolveEffectiveDbProviderTransition,
+} from './utils/server/effective_db_provider.mjs';
 import { resolveLocalhostHost, preferStackLocalhostUrl } from './utils/paths/localhost_host.mjs';
 import { openUrlInBrowser } from './utils/ui/browser.mjs';
 import { buildConfigureServerLinks } from '@happier-dev/cli-common/links';
@@ -80,7 +90,7 @@ import {
 import { killPid } from './utils/expo/expo.mjs';
 import { randomToken } from './utils/crypto/tokens.mjs';
 import { sanitizeSlugPart } from './utils/git/refs.mjs';
-import { readLastLines } from './utils/fs/tail.mjs';
+import { readLastLinesAfterProcessCompletion } from './utils/fs/tail.mjs';
 import { interactiveEdit, interactiveNew } from './utils/stack/interactive_stack_config.mjs';
 import { normalizeStackNameOrNull } from './utils/stack/names.mjs';
 import { runOrchestratedGuidedAuthFlow } from './utils/auth/orchestrated_stack_auth_flow.mjs';
@@ -104,6 +114,13 @@ const STACK_REPO_OVERRIDE_SCRIPT_BY_COMMAND = new Map([
   ['review', resolveTopLevelNodeScriptFile('review') || 'review.mjs'],
 ]);
 
+function stackAlreadyExistsError(stackName) {
+  return new Error(
+    `[stack] stack already exists: ${stackName}\n` +
+      `[stack] Use \`hstack stack edit ${stackName} --interactive\` or \`hstack stack env ${stackName} ...\` to change it.`,
+  );
+}
+
 async function cmdNew({ rootDir, argv, emit = true }) {
   const { flags, kv } = parseArgs(argv);
   const positionals = argv.filter((a) => !a.startsWith('--'));
@@ -123,7 +140,8 @@ async function cmdNew({ rootDir, argv, emit = true }) {
     (process.env.HAPPIER_STACK_AUTH_LINK ?? '').toString().trim() === '1' ||
     (process.env.HAPPIER_STACK_AUTH_MODE ?? '').toString().trim() === 'link';
   const forcePort = flags.has('--force-port');
-  const dbProviderRaw = (kv.get('--db-provider') ?? kv.get('--db') ?? '').toString().trim().toLowerCase();
+  const dbProviderOptionPresent = kv.has('--db-provider') || kv.has('--db');
+  const dbProviderRaw = (kv.has('--db-provider') ? kv.get('--db-provider') : kv.get('--db') ?? '').toString().trim().toLowerCase();
   const databaseUrlOverride = (kv.get('--database-url') ?? '').toString().trim();
 
   // argv here is already "args after 'new'", so the first positional is the stack name.
@@ -171,28 +189,44 @@ async function cmdNew({ rootDir, argv, emit = true }) {
   if (stackName === 'main') {
     throw new Error('[stack] stack name \"main\" is reserved (use the default stack without creating it)');
   }
+  if (stackExistsSync(stackName)) {
+    throw stackAlreadyExistsError(stackName);
+  }
 
   const serverComponent = (config.serverComponent || 'happier-server-light').trim();
   if (serverComponent !== 'happier-server-light' && serverComponent !== 'happier-server') {
     throw new Error(`[stack] invalid server component: ${serverComponent}`);
   }
-  const effectiveDbProvider =
-    dbProviderRaw ||
-    (serverComponent === 'happier-server-light' ? 'sqlite' : 'postgres');
-  if (serverComponent === 'happier-server-light' && effectiveDbProvider !== 'pglite' && effectiveDbProvider !== 'sqlite') {
-    throw new Error(`[stack] invalid --db-provider for happier-server-light: ${effectiveDbProvider} (supported: pglite, sqlite)`);
+  const dbProviderResolution = resolveEffectiveDbProvider({
+    serverComponentName: serverComponent,
+    env: dbProviderOptionPresent ? { HAPPIER_DB_PROVIDER: dbProviderRaw } : {},
+  });
+  if (!dbProviderResolution.ok) {
+    throw new Error(
+      `[stack] invalid --db-provider for ${serverComponent}: ${dbProviderRaw || '(missing)'} ` +
+        `(supported: ${dbProviderResolution.supportedProviders?.join(', ') ?? 'none'})`,
+    );
   }
-  if (serverComponent === 'happier-server' && effectiveDbProvider !== 'postgres' && effectiveDbProvider !== 'mysql') {
-    throw new Error(`[stack] invalid --db-provider for happier-server: ${effectiveDbProvider} (supported: postgres, mysql)`);
+  const effectiveDbProvider = dbProviderResolution.provider;
+  const databaseAuthority = resolveDbProviderDatabaseUrl({
+    provider: effectiveDbProvider,
+    databaseUrl: databaseUrlOverride,
+  });
+  if (databaseUrlOverride && databaseAuthority.removeDatabaseUrl) {
+    throw new Error(`[stack] --database-url is not valid for --db-provider=${effectiveDbProvider}`);
   }
-  if (serverComponent === 'happier-server' && effectiveDbProvider === 'mysql' && !databaseUrlOverride) {
+  if (effectiveDbProvider === 'mysql' && !databaseUrlOverride) {
+    const presetDefaultProvider = resolveEffectiveDbProvider({ serverComponentName: serverComponent, env: {} }).provider;
     throw new Error(
       `[stack] mysql support requires an explicit DATABASE_URL.\n` +
         `Fix:\n` +
         `- re-run with: --database-url=mysql://...\n` +
-        `- or use the default: --db-provider=postgres\n`
+        `- or omit --db-provider to use the ${presetDefaultProvider} preset default\n`
     );
   }
+  if (serverComponent === 'happier-server-light' && effectiveDbProvider === 'postgres' && !databaseUrlOverride) {
+    throw new Error('[stack] the light preset requires --database-url when --db-provider=postgres');
+  }
 
   const baseDir = resolveStackEnvPath(stackName).baseDir;
   const uiBuildDir = join(baseDir, 'ui');
@@ -242,9 +276,6 @@ async function cmdNew({ rootDir, argv, emit = true }) {
   stackEnv.HAPPIER_DB_PROVIDER = effectiveDbProvider;
   // Power user knob: override DATABASE_URL (required for mysql today, useful for external DBs).
   if (databaseUrlOverride) {
-    if (serverComponent === 'happier-server-light') {
-      throw new Error('[stack] --database-url is not supported for happier-server-light');
-    }
     stackEnv.DATABASE_URL = databaseUrlOverride;
   }
   if (port != null) {
@@ -253,27 +284,32 @@ async function cmdNew({ rootDir, argv, emit = true }) {
 
   // Server-light storage isolation: ensure stacks have their own light data dir.
   // (This prevents a dev stack from mutating main stack's data when schema changes.)
-  if (serverComponent === 'happier-server-light') {
+  if (serverComponent === 'happier-server-light' || effectiveDbProvider === 'sqlite' || effectiveDbProvider === 'pglite') {
     const dataDir = join(baseDir, 'server-light');
     stackEnv.HAPPIER_SERVER_LIGHT_DATA_DIR = dataDir;
-    stackEnv.HAPPIER_SERVER_LIGHT_FILES_DIR = join(dataDir, 'files');
-    if (effectiveDbProvider !== 'sqlite') {
+    if (serverComponent === 'happier-server-light') {
+      stackEnv.HAPPIER_SERVER_LIGHT_FILES_DIR = join(dataDir, 'files');
+    }
+    if (effectiveDbProvider === 'pglite') {
       stackEnv.HAPPIER_SERVER_LIGHT_DB_DIR = join(dataDir, 'pglite');
     }
   }
   if (serverComponent === 'happier-server') {
     // Persist stable infra credentials in the stack env (ports are ephemeral unless explicitly pinned).
-    const pgUser = 'handy';
-    const pgPassword = randomToken(24);
-    const pgDb = 'handy';
+    const usesManagedPostgres = effectiveDbProvider === 'postgres' && !databaseUrlOverride;
+    const pgUser = usesManagedPostgres ? 'handy' : null;
+    const pgPassword = usesManagedPostgres ? randomToken(24) : null;
+    const pgDb = usesManagedPostgres ? 'handy' : null;
     const s3Bucket = sanitizeDnsLabel(`happier-${stackName}`, { fallback: 'happier' });
     const s3AccessKey = randomToken(12);
     const s3SecretKey = randomToken(24);
 
     stackEnv.HAPPIER_STACK_MANAGED_INFRA = stackEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1';
-    stackEnv.HAPPIER_STACK_PG_USER = pgUser;
-    stackEnv.HAPPIER_STACK_PG_PASSWORD = pgPassword;
-    stackEnv.HAPPIER_STACK_PG_DATABASE = pgDb;
+    if (usesManagedPostgres) {
+      stackEnv.HAPPIER_STACK_PG_USER = pgUser;
+      stackEnv.HAPPIER_STACK_PG_PASSWORD = pgPassword;
+      stackEnv.HAPPIER_STACK_PG_DATABASE = pgDb;
+    }
     stackEnv.HAPPIER_STACK_HANDY_MASTER_SECRET_FILE = join(baseDir, 'happier-server', 'handy-master-secret.txt');
     stackEnv.S3_ACCESS_KEY = s3AccessKey;
     stackEnv.S3_SECRET_KEY = s3SecretKey;
@@ -377,7 +413,10 @@ async function cmdNew({ rootDir, argv, emit = true }) {
       });
   }
 
-  const envPath = await writeStackEnv({ stackName, env: stackEnv });
+  const { created, envPath } = await createStackEnv({ stackName, env: stackEnv });
+  if (!created) {
+    throw stackAlreadyExistsError(stackName);
+  }
   const res = { ok: true, stackName, envPath, port: port ?? null, serverComponent, portsMode: port == null ? 'ephemeral' : 'pinned' };
   if (emit) {
     printResult({
@@ -433,6 +472,25 @@ async function cmdEdit({ rootDir, argv }) {
   }
 
   const serverComponent = (config.serverComponent || existingEnv.HAPPIER_STACK_SERVER_COMPONENT || 'happier-server-light').trim();
+  const previousServerComponent = (existingEnv.HAPPIER_STACK_SERVER_COMPONENT || 'happier-server-light').trim();
+  const dbTransition = resolveEffectiveDbProviderTransition({
+    previousServerComponentName: previousServerComponent,
+    nextServerComponentName: serverComponent,
+    env: existingEnv,
+  });
+  if (!dbTransition.ok) {
+    if (dbTransition.reason === 'missing_mysql_database_url') {
+      throw new Error('[stack] mysql support requires an explicit DATABASE_URL');
+    }
+    if (dbTransition.reason === 'missing_postgres_database_url') {
+      throw new Error('[stack] postgres requires an explicit DATABASE_URL with the light preset');
+    }
+    if (dbTransition.reason === 'invalid_postgres_database_url') {
+      throw new Error('[stack] postgres DATABASE_URL must use postgres:// or postgresql://');
+    }
+    throw new Error(`[stack] invalid DB provider for ${serverComponent}: ${dbTransition.input ?? dbTransition.reason}`);
+  }
+  const effectiveDbProvider = dbTransition.provider;
 
   const next = {
     HAPPIER_STACK_STACK: stackName,
@@ -445,6 +503,7 @@ async function cmdEdit({ rootDir, argv }) {
     // Always pin defaults; overrides below can replace.
     ...resolveDefaultRepoEnv({ rootDir }),
   };
+  next.HAPPIER_DB_PROVIDER = effectiveDbProvider;
   if ((existingEnv.HAPPIER_STACK_REPO_DIR ?? '').trim()) {
     next.HAPPIER_STACK_REPO_DIR = String(existingEnv.HAPPIER_STACK_REPO_DIR).trim();
   }
@@ -452,14 +511,19 @@ async function cmdEdit({ rootDir, argv }) {
     next.HAPPIER_STACK_SERVER_PORT = String(port);
   }
 
-  if (serverComponent === 'happier-server-light') {
+  if (serverComponent === 'happier-server-light' || effectiveDbProvider === 'sqlite' || effectiveDbProvider === 'pglite') {
     const dataDir = join(baseDir, 'server-light');
     next.HAPPIER_SERVER_LIGHT_DATA_DIR = dataDir;
-    next.HAPPIER_SERVER_LIGHT_FILES_DIR = join(dataDir, 'files');
-    next.HAPPIER_SERVER_LIGHT_DB_DIR = join(dataDir, 'pglite');
-    // Light flavor manages its own embedded pglite connection string at runtime.
-    // Do not persist DATABASE_URL in the stack env.
-    delete next.DATABASE_URL;
+    if (serverComponent === 'happier-server-light') {
+      next.HAPPIER_SERVER_LIGHT_FILES_DIR = join(dataDir, 'files');
+    }
+    if (effectiveDbProvider === 'pglite') {
+      next.HAPPIER_SERVER_LIGHT_DB_DIR = join(dataDir, 'pglite');
+    }
+    if (dbTransition.removeDatabaseUrl) delete next.DATABASE_URL;
+  }
+  if (dbTransition.databaseUrl) {
+    next.DATABASE_URL = dbTransition.databaseUrl;
   }
   if (serverComponent === 'happier-server') {
     // Persist stable infra credentials. Ports are ephemeral unless explicitly pinned.
@@ -473,15 +537,17 @@ async function cmdEdit({ rootDir, argv }) {
     const s3SecretKey = (existingEnv.S3_SECRET_KEY ?? '').trim() || randomToken(24);
 
     next.HAPPIER_STACK_MANAGED_INFRA = (existingEnv.HAPPIER_STACK_MANAGED_INFRA ?? '1').trim() || '1';
-    next.HAPPIER_STACK_PG_USER = pgUser;
-    next.HAPPIER_STACK_PG_PASSWORD = pgPassword;
-    next.HAPPIER_STACK_PG_DATABASE = pgDb;
+    const usesManagedPostgres = effectiveDbProvider === 'postgres' && !dbTransition.databaseUrl;
+    if (usesManagedPostgres) {
+      next.HAPPIER_STACK_PG_USER = pgUser;
+      next.HAPPIER_STACK_PG_PASSWORD = pgPassword;
+      next.HAPPIER_STACK_PG_DATABASE = pgDb;
+    }
     next.HAPPIER_STACK_HANDY_MASTER_SECRET_FILE =
       (existingEnv.HAPPIER_STACK_HANDY_MASTER_SECRET_FILE ?? '').trim() || join(baseDir, 'happier-server', 'handy-master-secret.txt');
     next.S3_ACCESS_KEY = s3AccessKey;
     next.S3_SECRET_KEY = s3SecretKey;
     next.S3_BUCKET = s3Bucket;
-
     if (port != null) {
       // If user pinned the server port, keep ports + derived URLs stable as well.
       const reservedPorts = await collectReservedStackPorts({ excludeStackName: stackName });
@@ -490,13 +556,15 @@ async function cmdEdit({ rootDir, argv }) {
         ? Number(existingEnv.HAPPIER_STACK_SERVER_BACKEND_PORT.trim())
         : await pickNextFreePort(port + 10, { reservedPorts });
       reservedPorts.add(backendPort);
-      const pgPort = existingEnv.HAPPIER_STACK_PG_PORT?.trim()
-        ? Number(existingEnv.HAPPIER_STACK_PG_PORT.trim())
-        : await pickNextFreePort(port + 1000, { reservedPorts });
-      reservedPorts.add(pgPort);
+      const pgPort = usesManagedPostgres
+        ? (existingEnv.HAPPIER_STACK_PG_PORT?.trim()
+          ? Number(existingEnv.HAPPIER_STACK_PG_PORT.trim())
+          : await pickNextFreePort(port + 1000, { reservedPorts }))
+        : null;
+      if (pgPort != null) reservedPorts.add(pgPort);
       const redisPort = existingEnv.HAPPIER_STACK_REDIS_PORT?.trim()
         ? Number(existingEnv.HAPPIER_STACK_REDIS_PORT.trim())
-        : await pickNextFreePort(pgPort + 1, { reservedPorts });
+        : await pickNextFreePort(pgPort != null ? pgPort + 1 : port + 1000, { reservedPorts });
       reservedPorts.add(redisPort);
       const minioPort = existingEnv.HAPPIER_STACK_MINIO_PORT?.trim()
         ? Number(existingEnv.HAPPIER_STACK_MINIO_PORT.trim())
@@ -506,16 +574,19 @@ async function cmdEdit({ rootDir, argv }) {
         ? Number(existingEnv.HAPPIER_STACK_MINIO_CONSOLE_PORT.trim())
         : await pickNextFreePort(minioPort + 1, { reservedPorts });
 
-      const databaseUrl = `postgresql://${encodeURIComponent(pgUser)}:${encodeURIComponent(pgPassword)}@127.0.0.1:${pgPort}/${encodeURIComponent(pgDb)}`;
       const s3PublicUrl = `http://127.0.0.1:${minioPort}/${s3Bucket}`;
 
       next.HAPPIER_STACK_SERVER_BACKEND_PORT = String(backendPort);
-      next.HAPPIER_STACK_PG_PORT = String(pgPort);
+      if (pgPort != null) next.HAPPIER_STACK_PG_PORT = String(pgPort);
       next.HAPPIER_STACK_REDIS_PORT = String(redisPort);
       next.HAPPIER_STACK_MINIO_PORT = String(minioPort);
       next.HAPPIER_STACK_MINIO_CONSOLE_PORT = String(minioConsolePort);
 
-      next.DATABASE_URL = databaseUrl;
+      if (dbTransition.databaseUrl) {
+        next.DATABASE_URL = dbTransition.databaseUrl;
+      } else if (usesManagedPostgres) {
+        next.DATABASE_URL = `postgresql://${encodeURIComponent(pgUser)}:${encodeURIComponent(pgPassword)}@127.0.0.1:${pgPort}/${encodeURIComponent(pgDb)}`;
+      }
       next.REDIS_URL = `redis://127.0.0.1:${redisPort}`;
       next.S3_HOST = '127.0.0.1';
       next.S3_PORT = String(minioPort);
@@ -601,15 +672,23 @@ async function cmdAudit({ rootDir, argv }) {
         HAPPIER_STACK_STACK_REMOTE: 'upstream',
         ...resolveDefaultRepoEnv({ rootDir }),
       };
+      const repairedProvider = resolveEffectiveDbProvider({ serverComponentName: serverComponent, env });
+      if (repairedProvider.ok) {
+        nextEnv.HAPPIER_DB_PROVIDER = repairedProvider.provider;
+      }
       if (port != null) {
         nextEnv.HAPPIER_STACK_SERVER_PORT = String(port);
       }
 
-      if (serverComponent === 'happier-server-light') {
+      if (serverComponent === 'happier-server-light' || ['sqlite', 'pglite'].includes(repairedProvider.provider)) {
         const dataDir = join(baseDir, 'server-light');
         nextEnv.HAPPIER_SERVER_LIGHT_DATA_DIR = dataDir;
-        nextEnv.HAPPIER_SERVER_LIGHT_FILES_DIR = join(dataDir, 'files');
-        nextEnv.HAPPIER_SERVER_LIGHT_DB_DIR = join(dataDir, 'pglite');
+        if (serverComponent === 'happier-server-light') {
+          nextEnv.HAPPIER_SERVER_LIGHT_FILES_DIR = join(dataDir, 'files');
+        }
+        if (repairedProvider.provider === 'pglite') {
+          nextEnv.HAPPIER_SERVER_LIGHT_DB_DIR = join(dataDir, 'pglite');
+        }
       }
 
       await writeStackEnv({ stackName, env: nextEnv });
@@ -617,10 +696,18 @@ async function cmdAudit({ rootDir, argv }) {
       env = parseEnvToObject(raw);
     }
 
+    let serverComponent = getEnvValue(env, 'HAPPIER_STACK_SERVER_COMPONENT') || 'happier-server-light';
+    let effectiveDbProvider = resolveEffectiveDbProvider({ serverComponentName: serverComponent, env });
+
     // Optional: unpin ports for non-main stacks (ephemeral port model).
     if (unpinPorts && stackName !== 'main' && !unpinPortsExcept.has(stackName) && raw.trim()) {
-      const serverComponentTmp =
-        getEnvValue(env, 'HAPPIER_STACK_SERVER_COMPONENT') || 'happier-server-light';
+      const databaseUrlBeforePortRepair = getEnvValue(env, 'DATABASE_URL');
+      const managedPostgresBeforePortRepair = effectiveDbProvider.ok
+        && effectiveDbProvider.provider === 'postgres'
+        && (
+          !databaseUrlBeforePortRepair
+          || isCanonicalManagedPostgresAuthority({ databaseUrl: databaseUrlBeforePortRepair, env })
+        );
       const remove = [
         // Always remove pinned public server port.
         'HAPPIER_STACK_SERVER_PORT',
@@ -632,16 +719,20 @@ async function cmdAudit({ rootDir, argv }) {
         'HAPPIER_STACK_MINIO_PORT',
         'HAPPIER_STACK_MINIO_CONSOLE_PORT',
       ];
-      if (serverComponentTmp === 'happier-server') {
+      if (serverComponent === 'happier-server') {
         // These are derived from the ports above; safe to re-compute at start time.
-        remove.push('DATABASE_URL', 'REDIS_URL', 'S3_PORT', 'S3_PUBLIC_URL');
+        if (managedPostgresBeforePortRepair) {
+          remove.push('DATABASE_URL');
+        }
+        remove.push('REDIS_URL', 'S3_PORT', 'S3_PUBLIC_URL');
       }
       await ensureEnvFilePruned({ envPath, removeKeys: remove });
       raw = await readExistingEnv(envPath);
       env = parseEnvToObject(raw);
+      serverComponent = getEnvValue(env, 'HAPPIER_STACK_SERVER_COMPONENT') || 'happier-server-light';
+      effectiveDbProvider = resolveEffectiveDbProvider({ serverComponentName: serverComponent, env });
     }
 
-    const serverComponent = getEnvValue(env, 'HAPPIER_STACK_SERVER_COMPONENT') || 'happier-server-light';
     const portRaw = getEnvValue(env, 'HAPPIER_STACK_SERVER_PORT');
     const port = portRaw ? Number(portRaw) : null;
     if (Number.isFinite(port) && port > 0) {
@@ -651,6 +742,26 @@ async function cmdAudit({ rootDir, argv }) {
     }
 
     const issues = [];
+    const dbAuthority = effectiveDbProvider.ok
+      ? resolveEffectiveDbProviderTransition({
+          previousServerComponentName: serverComponent,
+          nextServerComponentName: serverComponent,
+          env,
+        })
+      : null;
+    if (!effectiveDbProvider.ok) {
+      issues.push({
+        code: effectiveDbProvider.reason,
+        message: `unsupported DB provider ${JSON.stringify(effectiveDbProvider.input ?? '')} for ${serverComponent}`,
+      });
+    } else if (dbAuthority && !dbAuthority.ok) {
+      issues.push({
+        code: dbAuthority.reason,
+        message: `${dbAuthority.provider} requires a compatible explicit DATABASE_URL; audit repair will not invent database authority`,
+      });
+    } else if (dbAuthority?.removeDatabaseUrl) {
+      issues.push({ code: 'incompatible_database_url', message: `DATABASE_URL is incompatible with ${dbAuthority.provider}` });
+    }
 
     if (!raw.trim()) {
       issues.push({ code: 'missing_env', message: `env file missing/empty (${envPath})` });
@@ -691,32 +802,32 @@ async function cmdAudit({ rootDir, argv }) {
     }
 
     // Server-light DB/files isolation.
-    const isServerLight = serverComponent === 'happier-server-light';
-    if (isServerLight) {
+    const dbProvider = effectiveDbProvider.ok ? effectiveDbProvider.provider : null;
+    const needsLocalData = serverComponent === 'happier-server-light' || dbProvider === 'sqlite' || dbProvider === 'pglite';
+    const needsLocalFiles = serverComponent === 'happier-server-light'
+      || ['local', 'filesystem'].includes(String(env.HAPPIER_FILES_BACKEND ?? env.HAPPY_FILES_BACKEND ?? '').trim().toLowerCase());
+    if (needsLocalData || needsLocalFiles) {
       const dataDir = getEnvValue(env, 'HAPPIER_SERVER_LIGHT_DATA_DIR');
       const filesDir = getEnvValue(env, 'HAPPIER_SERVER_LIGHT_FILES_DIR');
       const dbDir = getEnvValue(env, 'HAPPIER_SERVER_LIGHT_DB_DIR');
-      const rawDbProvider =
-        (getEnvValue(env, 'HAPPIER_DB_PROVIDER') ?? getEnvValue(env, 'HAPPY_DB_PROVIDER') ?? '').toString().trim().toLowerCase();
-      const dbProvider = rawDbProvider === 'pglite' ? 'pglite' : 'sqlite';
       const expectedDataDir = join(baseDir, 'server-light');
       const expectedFilesDir = join(expectedDataDir, 'files');
       const expectedDbDir = join(expectedDataDir, 'pglite');
 
-      if (!dataDir) issues.push({ code: 'missing_server_light_data_dir', message: `missing HAPPIER_SERVER_LIGHT_DATA_DIR (expected ${expectedDataDir})` });
-      if (!filesDir) issues.push({ code: 'missing_server_light_files_dir', message: `missing HAPPIER_SERVER_LIGHT_FILES_DIR (expected ${expectedFilesDir})` });
-      if (dataDir && dataDir !== expectedDataDir) issues.push({ code: 'server_light_data_dir_mismatch', message: `HAPPIER_SERVER_LIGHT_DATA_DIR=${dataDir} (expected ${expectedDataDir})` });
-      if (filesDir && filesDir !== expectedFilesDir) issues.push({ code: 'server_light_files_dir_mismatch', message: `HAPPIER_SERVER_LIGHT_FILES_DIR=${filesDir} (expected ${expectedFilesDir})` });
+      if (needsLocalData && !dataDir) issues.push({ code: 'missing_server_light_data_dir', message: `missing HAPPIER_SERVER_LIGHT_DATA_DIR (expected ${expectedDataDir})` });
+      if (needsLocalFiles && !filesDir) issues.push({ code: 'missing_server_light_files_dir', message: `missing HAPPIER_SERVER_LIGHT_FILES_DIR (expected ${expectedFilesDir})` });
+      if (needsLocalData && dataDir && dataDir !== expectedDataDir) issues.push({ code: 'server_light_data_dir_mismatch', message: `HAPPIER_SERVER_LIGHT_DATA_DIR=${dataDir} (expected ${expectedDataDir})` });
+      if (needsLocalFiles && filesDir && filesDir !== expectedFilesDir) issues.push({ code: 'server_light_files_dir_mismatch', message: `HAPPIER_SERVER_LIGHT_FILES_DIR=${filesDir} (expected ${expectedFilesDir})` });
       if (dbProvider === 'pglite') {
         if (!dbDir) issues.push({ code: 'missing_server_light_db_dir', message: `missing HAPPIER_SERVER_LIGHT_DB_DIR (expected ${expectedDbDir})` });
         if (dbDir && dbDir !== expectedDbDir) issues.push({ code: 'server_light_db_dir_mismatch', message: `HAPPIER_SERVER_LIGHT_DB_DIR=${dbDir} (expected ${expectedDbDir})` });
       }
 
       const legacyDbUrl = getEnvValue(env, 'DATABASE_URL');
-      if (legacyDbUrl) {
+      if (dbProvider === 'pglite' && legacyDbUrl && !issues.some((issue) => issue.code === 'incompatible_database_url')) {
         issues.push({
-          code: 'legacy_database_url',
-          message: `DATABASE_URL is set for a light stack (${legacyDbUrl}); light manages its own local database and does not require DATABASE_URL in the stack env`,
+          code: 'incompatible_database_url',
+          message: `DATABASE_URL is set for a PGlite stack (${legacyDbUrl}); PGlite manages its local socket authority`,
         });
       }
     }
@@ -725,6 +836,10 @@ async function cmdAudit({ rootDir, argv }) {
     if ((fix || fixWorkspace || fixPaths) && (stackName !== 'main' || fixMain) && raw.trim()) {
       const updates = [];
 
+      if (effectiveDbProvider.ok && effectiveDbProvider.source === 'default') {
+        updates.push({ key: 'HAPPIER_DB_PROVIDER', value: effectiveDbProvider.provider });
+      }
+
       // Always ensure stack directories are explicitly pinned when missing.
       if (!uiBuildDir) updates.push({ key: 'HAPPIER_STACK_UI_BUILD_DIR', value: expectedUi });
       if (!cliHomeDir) updates.push({ key: 'HAPPIER_STACK_CLI_HOME_DIR', value: expectedCli });
@@ -743,16 +858,16 @@ async function cmdAudit({ rootDir, argv }) {
       }
 
       // Server-light storage isolation.
-      if (isServerLight) {
+      if (needsLocalData || needsLocalFiles) {
         const dataDir = getEnvValue(env, 'HAPPIER_SERVER_LIGHT_DATA_DIR');
         const filesDir = getEnvValue(env, 'HAPPIER_SERVER_LIGHT_FILES_DIR');
         const dbDir = getEnvValue(env, 'HAPPIER_SERVER_LIGHT_DB_DIR');
         const expectedDataDir = join(baseDir, 'server-light');
         const expectedFilesDir = join(expectedDataDir, 'files');
         const expectedDbDir = join(expectedDataDir, 'pglite');
-        if (!dataDir || (fixPaths && dataDir !== expectedDataDir)) updates.push({ key: 'HAPPIER_SERVER_LIGHT_DATA_DIR', value: expectedDataDir });
-        if (!filesDir || (fixPaths && filesDir !== expectedFilesDir)) updates.push({ key: 'HAPPIER_SERVER_LIGHT_FILES_DIR', value: expectedFilesDir });
-        if (!dbDir || (fixPaths && dbDir !== expectedDbDir)) updates.push({ key: 'HAPPIER_SERVER_LIGHT_DB_DIR', value: expectedDbDir });
+        if (needsLocalData && (!dataDir || (fixPaths && dataDir !== expectedDataDir))) updates.push({ key: 'HAPPIER_SERVER_LIGHT_DATA_DIR', value: expectedDataDir });
+        if (needsLocalFiles && (!filesDir || (fixPaths && filesDir !== expectedFilesDir))) updates.push({ key: 'HAPPIER_SERVER_LIGHT_FILES_DIR', value: expectedFilesDir });
+        if (dbProvider === 'pglite' && (!dbDir || (fixPaths && dbDir !== expectedDbDir))) updates.push({ key: 'HAPPIER_SERVER_LIGHT_DB_DIR', value: expectedDbDir });
       }
 
       if (fixWorkspace) {
@@ -777,14 +892,14 @@ async function cmdAudit({ rootDir, argv }) {
         await ensureEnvFileUpdated({ envPath, updates });
       }
 
-      // Light stacks no longer persist DATABASE_URL in the env file (light uses embedded PGlite).
-      // For legacy SQLite-era stacks, prune it when fixing paths so future commands don't accidentally
-      // treat the stack as SQLite-backed.
-      if (isServerLight && fixPaths) {
+      if ((needsLocalData || needsLocalFiles) && fixPaths) {
         const legacyDbUrl = getEnvValue(env, 'DATABASE_URL');
-        if (legacyDbUrl) {
+        if (dbAuthority?.ok && dbAuthority.removeDatabaseUrl && legacyDbUrl) {
           await ensureEnvFilePruned({ envPath, removeKeys: ['DATABASE_URL'] });
         }
+        if (dbProvider === 'sqlite') {
+          await ensureEnvFilePruned({ envPath, removeKeys: ['HAPPIER_SERVER_LIGHT_DB_DIR', 'HAPPY_SERVER_LIGHT_DB_DIR'] });
+        }
       }
     }
 
@@ -793,6 +908,7 @@ async function cmdAudit({ rootDir, argv }) {
       envPath,
       baseDir,
       serverComponent,
+      dbProvider: effectiveDbProvider.ok ? effectiveDbProvider.provider : null,
       serverPort: Number.isFinite(port) ? port : null,
       uiBuildDir: uiBuildDir || null,
       cliHomeDir: cliHomeDir || null,
@@ -871,9 +987,15 @@ async function cmdAudit({ rootDir, argv }) {
           planned.add(newServerPort);
           const backendPort = await pickNextFreePort(newServerPort + 10, { reservedPorts: planned });
           planned.add(backendPort);
-          const pgPort = await pickNextFreePort(newServerPort + 1000, { reservedPorts: planned });
-          planned.add(pgPort);
-          const redisPort = await pickNextFreePort(pgPort + 1, { reservedPorts: planned });
+          const databaseUrl = getEnvValue(env, 'DATABASE_URL');
+          const managedPostgres = entry.dbProvider === 'postgres' && (
+            !databaseUrl || isCanonicalManagedPostgresAuthority({ databaseUrl, env })
+          );
+          const pgPort = managedPostgres
+            ? await pickNextFreePort(newServerPort + 1000, { reservedPorts: planned })
+            : null;
+          if (pgPort != null) planned.add(pgPort);
+          const redisPort = await pickNextFreePort(pgPort != null ? pgPort + 1 : newServerPort + 1000, { reservedPorts: planned });
           planned.add(redisPort);
           const minioPort = await pickNextFreePort(redisPort + 1, { reservedPorts: planned });
           planned.add(minioPort);
@@ -881,26 +1003,28 @@ async function cmdAudit({ rootDir, argv }) {
           planned.add(minioConsolePort);
 
           updates.push({ key: 'HAPPIER_STACK_SERVER_BACKEND_PORT', value: String(backendPort) });
-          updates.push({ key: 'HAPPIER_STACK_PG_PORT', value: String(pgPort) });
+          if (pgPort != null) updates.push({ key: 'HAPPIER_STACK_PG_PORT', value: String(pgPort) });
           updates.push({ key: 'HAPPIER_STACK_REDIS_PORT', value: String(redisPort) });
           updates.push({ key: 'HAPPIER_STACK_MINIO_PORT', value: String(minioPort) });
           updates.push({ key: 'HAPPIER_STACK_MINIO_CONSOLE_PORT', value: String(minioConsolePort) });
 
-          // Update URLs while preserving existing credentials.
-          const pgUser = getEnvValue(env, 'HAPPIER_STACK_PG_USER') || 'handy';
-          const pgPassword = getEnvValue(env, 'HAPPIER_STACK_PG_PASSWORD') || '';
-          const pgDb = getEnvValue(env, 'HAPPIER_STACK_PG_DATABASE') || 'handy';
-          let user = pgUser;
-          let pass = pgPassword;
-          let db = pgDb;
-          const parsed = parsePg(getEnvValue(env, 'DATABASE_URL'));
-          if (parsed) {
-            if (parsed.user) user = parsed.user;
-            if (parsed.password) pass = parsed.password;
-            if (parsed.db) db = parsed.db;
+          // Update only managed Postgres; external database authority is operator-owned.
+          if (managedPostgres && pgPort != null) {
+            const pgUser = getEnvValue(env, 'HAPPIER_STACK_PG_USER') || 'handy';
+            const pgPassword = getEnvValue(env, 'HAPPIER_STACK_PG_PASSWORD') || '';
+            const pgDb = getEnvValue(env, 'HAPPIER_STACK_PG_DATABASE') || 'handy';
+            let user = pgUser;
+            let pass = pgPassword;
+            let db = pgDb;
+            const parsed = parsePg(getEnvValue(env, 'DATABASE_URL'));
+            if (parsed) {
+              if (parsed.user) user = parsed.user;
+              if (parsed.password) pass = parsed.password;
+              if (parsed.db) db = parsed.db;
+            }
+            const databaseUrl = `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@127.0.0.1:${pgPort}/${encodeURIComponent(db)}`;
+            updates.push({ key: 'DATABASE_URL', value: databaseUrl });
           }
-          const databaseUrl = `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@127.0.0.1:${pgPort}/${encodeURIComponent(db)}`;
-          updates.push({ key: 'DATABASE_URL', value: databaseUrl });
           updates.push({ key: 'REDIS_URL', value: `redis://127.0.0.1:${redisPort}` });
           updates.push({ key: 'S3_PORT', value: String(minioPort) });
           const bucket = getEnvValue(env, 'S3_BUCKET') || sanitizeDnsLabel(`happier-${stackName}`, { fallback: 'happier' });
@@ -1163,7 +1287,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
                     console.error(`[stack] Expo exited unexpectedly (code=${c ?? 'null'}, sig=${sig ?? 'null'})`);
                     // eslint-disable-next-line no-console
                     console.error(`[stack] expo log: ${expoLogPath}`);
-                    const tail = await readLastLines(expoLogPath, 80);
+                    const tail = await readLastLinesAfterProcessCompletion(uiProc, expoLogPath, 80);
                     if (tail) {
                       // eslint-disable-next-line no-console
                       console.error('');
@@ -1249,7 +1373,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
                 console.log('');
                 console.log(`[stack] stopping temporary UI (pid=${uiProc.pid})...`);
                 uiStopRequested = true;
-                killProcessTree(uiProc, 'SIGINT');
+                await killProcessTree(uiProc, 'SIGINT');
                 await Promise.race([
                   new Promise((resolve) => uiProc.on('exit', resolve)),
                   new Promise((resolve) => setTimeout(resolve, 15_000)),
@@ -1258,7 +1382,8 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
               if (serverProc) {
                 console.log('');
                 console.log(`[stack] stopping temporary server (pid=${serverProc.pid})...`);
-                killProcessTree(serverProc, 'SIGINT');
+                const serverShutdownGraceMs = resolveServerShutdownGraceMs(env);
+                await killProcessTree(serverProc, 'SIGINT', { graceMs: serverShutdownGraceMs });
                 await Promise.race([
                   new Promise((resolve) => serverProc.on('exit', resolve)),
                   new Promise((resolve) => setTimeout(resolve, 15_000)),
@@ -1449,6 +1574,15 @@ async function cmdArchiveStack({ rootDir, argv, stackName }) {
     };
   }
 
+  // Remove the durable OS lifecycle owner while its stack env still exists. Otherwise an archived
+  // stack can leave launchd/systemd/schtasks repeatedly starting a wrapper against a missing env.
+  await disableInstalledStackServicesBeforeArchive({
+    rootDir,
+    stackName,
+    homeDir: homedir(),
+    uninstallStackService: cmdService,
+  });
+
   await mkdir(dirname(destStackDir), { recursive: true });
   await rename(baseDir, destStackDir);
 
@@ -1599,6 +1733,17 @@ async function cmdInfo({ rootDir, argv }) {
     const issueSuffix = issues.length > 0 ? ` (${issues.join(',')})` : '';
     console.log(`- health: ${out.runtime.health.status}${issueSuffix}`);
   }
+  if (out.runtime?.serverLifecycle) {
+    const lifecycle = out.runtime.serverLifecycle;
+    const planned = lifecycle.planned
+      ? ` planned=${lifecycle.planned.mode}@${lifecycle.planned.generation}`
+      : '';
+    const completed = lifecycle.lastCompleted
+      ? ` lastCompleted=${lifecycle.lastCompleted.mode}@${lifecycle.lastCompleted.generation}`
+      : '';
+    const disposition = lifecycle.disposition ? ` disposition=${lifecycle.disposition.code}` : '';
+    console.log(`- server lifecycle: ${lifecycle.phase}${planned}${completed}${disposition}`);
+  }
   if (out.ports.server) console.log(`- port: server=${out.ports.server}${out.ports.backend ? ` backend=${out.ports.backend}` : ''}`);
   if (out.ports.ui) {
     const uiRunning = out.runtime?.components?.ui?.running !== false;
@@ -1698,7 +1843,8 @@ async function cmdPrStack({ rootDir, argv }) {
 
   const remoteNameFromArg = (kv.get('--remote') ?? '').trim();
   const depsMode = (kv.get('--deps') ?? '').trim();
-  const dbProviderFromArg = (kv.get('--db-provider') ?? kv.get('--db') ?? '').toString().trim();
+  const dbProviderOptionPresent = kv.has('--db-provider') || kv.has('--db');
+  const dbProviderFromArg = (kv.has('--db-provider') ? kv.get('--db-provider') : kv.get('--db') ?? '').toString().trim();
   const databaseUrlFromArg = (kv.get('--database-url') ?? '').toString().trim();
 
   const prRepo = (kv.get('--repo') ?? kv.get('--pr') ?? '').trim();
@@ -1838,7 +1984,7 @@ async function cmdPrStack({ rootDir, argv }) {
 	        stackName,
 	        '--no-copy-auth',
 	        `--server=${serverComponent}`,
-	        ...(dbProviderFromArg ? [`--db-provider=${dbProviderFromArg}`] : []),
+	        ...(dbProviderOptionPresent ? [`--db-provider=${dbProviderFromArg}`] : []),
 	        ...(databaseUrlFromArg ? [`--database-url=${databaseUrlFromArg}`] : []),
 	        ...(json ? ['--json'] : []),
 	      ],
@@ -2404,6 +2550,10 @@ async function main() {
     await cmdRuntime({ rootDir, stackName, args: passthrough.slice(1) });
     return;
   }
+  if (cmd === 'install') {
+    await runStackInstallCommand({ rootDir, stackName, argv: passthrough, json });
+    return;
+  }
 
   if (cmd.startsWith('service:')) {
     const svcCmd = cmd.slice('service:'.length);