@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/service.mjs

@@ -1,6 +1,13 @@
 import './utils/env/env.mjs';
 import { run, runCapture } from './utils/proc/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir, getSystemdUnitInfo, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import {
+  getComponentDir,
+  getDefaultAutostartPaths,
+  getRootDir,
+  getSystemdUnitInfo,
+  resolveExplicitStackEnvFilePath,
+  resolveStackEnvPath,
+} from './utils/paths/paths.mjs';
 import { getInternalServerUrl, getPublicServerUrlEnvOverride } from './utils/server/urls.mjs';
 import { resolveServerUrls } from './utils/server/urls.mjs';
 import { installService as installManagedService, uninstallService as uninstallManagedService } from './utils/service/service_manager.mjs';
@@ -24,13 +31,14 @@ import {
   resolvePreferredStackDaemonStatePaths,
   resolveStackCredentialPaths,
 } from './utils/auth/credentials_paths.mjs';
+import { applyStackDaemonLifecycleScopeEnv } from './utils/auth/stable_scope_id.mjs';
 import {
   resolveAutostartEnvFilePath,
   resolveAutostartLogPaths,
   resolveAutostartWorkingDirectory,
 } from './utils/service/stack_autostart_resolution.mjs';
 import { buildServiceAuthGuidance } from './utils/service/auth_guidance.mjs';
-import { recordStackRuntimeStopRequest } from './utils/stack/runtime_state.mjs';
+import { stopStackServiceWithEnv } from './utils/stack/stop.mjs';
 
 /**
  * Manage the autostart service installed by `hstack bootstrap -- --autostart`.
@@ -67,7 +75,7 @@ function getAutostartEnv({ mode, systemUserHomeDir } = {}) {
   // Main installs:
   // - default to the main stack env (outside the repo): ~/.happier/stacks/main/env
 
-  const explicitEnvFilePath = process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '';
+  const explicitEnvFilePath = resolveExplicitStackEnvFilePath(process.env);
   const defaultMainEnvFilePath = resolveStackEnvPath('main').envPath;
   const envFile = resolveAutostartEnvFilePath({
     mode,
@@ -206,6 +214,8 @@ export async function installService({ mode = 'user', systemUser = null } = {})
       runAsUser: mode === 'system' && systemUser ? systemUser : '',
       stdoutPath,
       stderrPath,
+      // Match launchd's SuccessfulExit=false behavior: a successful wrapper disposition is terminal.
+      restartPolicy: 'on-failure',
     },
     persistent: true,
   });
@@ -294,10 +304,6 @@ async function systemdStop({ persistent }) {
   }
 }
 
-async function systemdRestart() {
-  await run('systemctl', ['--user', 'restart', systemdUnitName()]);
-}
-
 async function systemdLogs({ lines = 120 } = {}) {
   await run('journalctl', ['--user', '-u', systemdUnitName(), '-n', String(lines), '--no-pager']);
 }
@@ -315,19 +321,6 @@ async function launchctlTry(args) {
   }
 }
 
-async function restartLaunchAgentBestEffort() {
-  const { plistPath, label } = getDefaultAutostartPaths();
-  if (!existsSync(plistPath)) {
-    throw new Error(`[local] LaunchAgent plist not found at ${plistPath}. Run: hstack service:install (or hstack bootstrap -- --autostart)`);
-  }
-  const uid = getUid();
-  if (uid == null) {
-    return false;
-  }
-  // Prefer kickstart -k to avoid overlapping stop/start windows (which can stop a freshly started daemon).
-  return await launchctlTry(['kickstart', '-k', `gui/${uid}/${label}`]);
-}
-
 async function startLaunchAgent({ persistent }) {
   const { plistPath } = getDefaultAutostartPaths();
   if (!existsSync(plistPath)) {
@@ -359,13 +352,21 @@ async function startLaunchAgent({ persistent }) {
   await launchctlTry(['kickstart', '-k', `gui/${uid}/${label}`]);
 }
 
-async function postStartDiagnostics() {
+export async function postStartDiagnostics() {
   const rootDir = getRootDir(import.meta.url);
-  const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
+  const defaults = getDefaultAutostartPaths();
+  const stackName = defaults.stackName;
+  const cliIdentity = String(process.env.HAPPIER_STACK_CLI_IDENTITY ?? '').trim() || 'default';
+  const scopedEnv = applyStackDaemonLifecycleScopeEnv({
+    env: process.env,
+    stackName,
+    cliIdentity,
+  });
+  const internalUrl = getInternalServerUrl({ env: scopedEnv, defaultPort: 3005 }).internalServerUrl;
 
-  const cliHomeDir = process.env.HAPPIER_STACK_CLI_HOME_DIR?.trim()
-    ? expandHome(process.env.HAPPIER_STACK_CLI_HOME_DIR.trim())
-    : join(getDefaultAutostartPaths().baseDir, 'cli');
+  const cliHomeDir = scopedEnv.HAPPIER_STACK_CLI_HOME_DIR?.trim()
+    ? expandHome(scopedEnv.HAPPIER_STACK_CLI_HOME_DIR.trim())
+    : join(defaults.baseDir, 'cli');
 
   let port = 3005;
   try {
@@ -373,20 +374,20 @@ async function postStartDiagnostics() {
   } catch {
     port = 3005;
   }
-  const resolvedUrls = await resolveServerUrls({ env: process.env, serverPort: port, allowEnable: false }).catch(() => null);
+  const resolvedUrls = await resolveServerUrls({ env: scopedEnv, serverPort: port, allowEnable: false }).catch(() => null);
   const publicUrl =
     resolvedUrls?.publicServerUrl
       ? String(resolvedUrls.publicServerUrl)
-      : getPublicServerUrlEnvOverride({ env: process.env, serverPort: port }).publicServerUrl;
+      : getPublicServerUrlEnvOverride({ env: scopedEnv, serverPort: port }).publicServerUrl;
   const publicServerUrlSource = String(resolvedUrls?.publicServerUrlSource ?? '').trim();
 
   const cliDir = getComponentDir(rootDir, 'happier-cli');
   const cliBin = join(cliDir, 'bin', 'happier.mjs');
 
-  const credentialPaths = resolveStackCredentialPaths({ cliHomeDir, serverUrl: internalUrl });
-  const existingCredentialPath = findExistingStackCredentialPath({ cliHomeDir, serverUrl: internalUrl });
+  const credentialPaths = resolveStackCredentialPaths({ cliHomeDir, serverUrl: internalUrl, env: scopedEnv });
+  const existingCredentialPath = findExistingStackCredentialPath({ cliHomeDir, serverUrl: internalUrl, env: scopedEnv });
   const accessKey = existingCredentialPath || credentialPaths.serverScopedPath;
-  const daemonPaths = resolvePreferredStackDaemonStatePaths({ cliHomeDir, serverUrl: internalUrl });
+  const daemonPaths = resolvePreferredStackDaemonStatePaths({ cliHomeDir, serverUrl: internalUrl, env: scopedEnv });
   const stateFile = daemonPaths.statePath;
   const lockFile = daemonPaths.lockPath;
   const logsDir = join(cliHomeDir, 'logs');
@@ -461,7 +462,6 @@ async function postStartDiagnostics() {
     }
   }
 
-  const stackName = getDefaultAutostartPaths().stackName;
   console.log('');
   console.log(banner('service', { subtitle: `Post-start diagnostics (${stackName})` }));
   console.log('');
@@ -469,7 +469,7 @@ async function postStartDiagnostics() {
   const authGuidance = buildServiceAuthGuidance({
     stackName,
     publicServerUrl: publicUrl,
-    tailscaleServeEnabled: (process.env.HAPPIER_STACK_TAILSCALE_SERVE ?? '0') === '1',
+    tailscaleServeEnabled: (scopedEnv.HAPPIER_STACK_TAILSCALE_SERVE ?? '0') === '1',
     publicServerUrlSource,
   });
 
@@ -537,26 +537,13 @@ async function postStartDiagnostics() {
   }
 }
 
-async function stopLaunchAgent({ persistent, requestedBy = 'service stop', reason = '' }) {
+async function stopLaunchAgent({ persistent }) {
   const { plistPath } = getDefaultAutostartPaths();
   if (!existsSync(plistPath)) {
     // Service isn't installed for this stack (common for ad-hoc stacks). Treat as a no-op.
     return;
   }
 
-  const envFile = resolveAutostartEnvFilePath({
-    mode: 'user',
-    explicitEnvFilePath: process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '',
-    defaultMainEnvFilePath: resolveStackEnvPath('main').envPath,
-    systemUserHomeDir: null,
-  });
-  const runtimeStatePath = join(dirname(envFile), 'stack.runtime.json');
-  await recordStackRuntimeStopRequest(runtimeStatePath, {
-    signal: 'SIGTERM',
-    requestedBy,
-    reason,
-  }).catch(() => {});
-
   const { label } = getDefaultAutostartPaths();
 
   // Old-style
@@ -658,6 +645,51 @@ async function tailLogs() {
   await new Promise((resolve) => child.on('exit', resolve));
 }
 
+export async function stopServiceWithCanonicalCleanup({
+  rootDir,
+  mode = 'user',
+  json = false,
+  persistent,
+  requestedBy,
+  reason,
+  disable = false,
+  platform = process.platform,
+  env = process.env,
+  stopStackServiceWithEnvImpl = stopStackServiceWithEnv,
+  runImpl = run,
+  stopLaunchAgentImpl = stopLaunchAgent,
+  systemdStopImpl = systemdStop,
+} = {}) {
+  const defaults = getDefaultAutostartPaths(env);
+  await stopStackServiceWithEnvImpl({
+    rootDir,
+    stackName: defaults.stackName,
+    baseDir: defaults.baseDir,
+    env,
+    json,
+    noDocker: false,
+    autoSweep: true,
+    preserveDaemon: false,
+    stopAttribution: { requestedBy, reason },
+  }, async () => {
+    if (platform === 'win32') {
+      await runImpl('schtasks', ['/End', '/TN', `Happier\\${defaults.label}`]).catch(() => {});
+      if (disable) await runImpl('schtasks', ['/Change', '/TN', `Happier\\${defaults.label}`, '/Disable']).catch(() => {});
+      return;
+    }
+    if (platform === 'darwin') {
+      await stopLaunchAgentImpl({ persistent });
+      return;
+    }
+    if (mode === 'system') {
+      const { unitName } = getSystemdUnitInfo({ env, mode });
+      await runImpl('systemctl', [disable ? 'disable' : 'stop', ...(disable ? ['--now'] : []), unitName]);
+    } else {
+      await systemdStopImpl({ persistent });
+    }
+  });
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const helpSepIdx = argv.indexOf('--');
@@ -829,45 +861,27 @@ async function main() {
       if (json) printResult({ json, data: { ok: true, action: 'start' } });
       return;
     case 'stop':
-      if (process.platform === 'win32') {
-        const { label } = getDefaultAutostartPaths();
-        await run('schtasks', ['/End', '/TN', `Happier\\${label}`]).catch(() => {});
-        if (json) printResult({ json, data: { ok: true, action: 'stop' } });
-        return;
-      }
-      if (process.platform === 'darwin') {
-        await stopLaunchAgent({ persistent: false, requestedBy: 'service stop', reason: 'explicit service stop' });
-      } else {
-        if (mode === 'system') {
-          const { unitName } = getSystemdUnitInfo({ mode });
-          await run('systemctl', ['stop', unitName]);
-        } else {
-          await systemdStop({ persistent: false });
-        }
-      }
+      await stopServiceWithCanonicalCleanup({ rootDir, mode, json, persistent: false, requestedBy: 'service stop', reason: 'explicit service stop' });
       if (json) printResult({ json, data: { ok: true, action: 'stop' } });
       return;
     case 'restart':
+      await stopServiceWithCanonicalCleanup({ rootDir, mode, json, persistent: false, requestedBy: 'service restart', reason: 'explicit service restart' });
       if (process.platform === 'win32') {
         const { label } = getDefaultAutostartPaths();
-        await run('schtasks', ['/End', '/TN', `Happier\\${label}`]).catch(() => {});
         await run('schtasks', ['/Run', '/TN', `Happier\\${label}`]).catch(() => {});
         await postStartDiagnostics();
         if (json) printResult({ json, data: { ok: true, action: 'restart' } });
         return;
       }
       if (process.platform === 'darwin') {
-        if (!(await restartLaunchAgentBestEffort())) {
-          await stopLaunchAgent({ persistent: false, requestedBy: 'service restart', reason: 'explicit service restart' });
-          await waitForLaunchAgentStopped();
-          await startLaunchAgent({ persistent: false });
-        }
+        await waitForLaunchAgentStopped();
+        await startLaunchAgent({ persistent: false });
       } else {
         if (mode === 'system') {
           const { unitName } = getSystemdUnitInfo({ mode });
-          await run('systemctl', ['restart', unitName]);
+          await run('systemctl', ['start', unitName]);
         } else {
-          await systemdRestart();
+          await systemdStart({ persistent: false });
         }
       }
       await postStartDiagnostics();
@@ -908,23 +922,7 @@ async function main() {
       if (json) printResult({ json, data: { ok: true, action: 'enable' } });
       return;
     case 'disable':
-      if (process.platform === 'win32') {
-        const { label } = getDefaultAutostartPaths();
-        await run('schtasks', ['/End', '/TN', `Happier\\${label}`]).catch(() => {});
-        await run('schtasks', ['/Change', '/TN', `Happier\\${label}`, '/Disable']).catch(() => {});
-        if (json) printResult({ json, data: { ok: true, action: 'disable' } });
-        return;
-      }
-      if (process.platform === 'darwin') {
-        await stopLaunchAgent({ persistent: true, requestedBy: 'service disable', reason: 'explicit service disable' });
-      } else {
-        if (mode === 'system') {
-          const { unitName } = getSystemdUnitInfo({ mode });
-          await run('systemctl', ['disable', '--now', unitName]);
-        } else {
-          await systemdStop({ persistent: true });
-        }
-      }
+      await stopServiceWithCanonicalCleanup({ rootDir, mode, json, persistent: true, requestedBy: 'service disable', reason: 'explicit service disable', disable: true });
       if (json) printResult({ json, data: { ok: true, action: 'disable' } });
       return;
     case 'logs':

package/scripts/service.post_start_diagnostics_scope.test.mjs

@@ -0,0 +1,97 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveStackDaemonStatePaths } from './utils/auth/credentials_paths.mjs';
+import { applyStackDaemonLifecycleScopeEnv } from './utils/auth/stable_scope_id.mjs';
+
+function runNode(args, { cwd, env, timeoutMs = 15_000 }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`timed out after ${timeoutMs}ms\nstdout:\n${stdout}\nstderr:\n${stderr}`));
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.once('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr });
+    });
+  });
+}
+
+test('postStartDiagnostics reads the exact named-stack daemon lifecycle scope', async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'hstack-service-post-start-scope-'));
+  t.after(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const stackRoot = dirname(scriptsDir);
+  const repoRoot = dirname(dirname(stackRoot));
+  const stackName = 'named-service-stack';
+  const cliIdentity = 'account-b';
+  const cliHomeDir = join(tempRoot, 'cli');
+  const storageDir = join(tempRoot, 'stacks');
+  const stackHomeDir = join(tempRoot, 'stack-home');
+  const envPath = join(tempRoot, 'named-stack.env');
+  const internalServerUrl = 'http://127.0.0.1:43127';
+  const baseEnv = {
+    ...process.env,
+    HAPPIER_STACK_STORAGE_DIR: storageDir,
+    HAPPIER_STACK_HOME_DIR: stackHomeDir,
+    HAPPIER_STACK_ENV_FILE: envPath,
+    HAPPIER_STACK_DISABLE_STACK_ENV_AUTOLOAD: '1',
+    HAPPIER_STACK_STACK: stackName,
+    HAPPIER_STACK_CLI_IDENTITY: cliIdentity,
+    HAPPIER_STACK_CLI_HOME_DIR: cliHomeDir,
+    HAPPIER_STACK_SERVER_PORT: '43127',
+    HAPPIER_ACTIVE_SERVER_ID: 'named-endpoint-profile',
+    HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID: 'stack_ambient__id_default',
+  };
+  await mkdir(stackHomeDir, { recursive: true });
+  await writeFile(envPath, [
+    `HAPPIER_STACK_STORAGE_DIR=${storageDir}`,
+    `HAPPIER_STACK_STACK=${stackName}`,
+    `HAPPIER_STACK_CLI_IDENTITY=${cliIdentity}`,
+    `HAPPIER_STACK_CLI_HOME_DIR=${cliHomeDir}`,
+    'HAPPIER_STACK_SERVER_PORT=43127',
+    'HAPPIER_ACTIVE_SERVER_ID=named-endpoint-profile',
+    'HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID=stack_ambient__id_default',
+    '',
+  ].join('\n'));
+  const exactEnv = applyStackDaemonLifecycleScopeEnv({
+    env: baseEnv,
+    stackName,
+    cliIdentity,
+  });
+  const { serverScopedStatePath } = resolveStackDaemonStatePaths({
+    cliHomeDir,
+    serverUrl: internalServerUrl,
+    env: exactEnv,
+  });
+  await mkdir(dirname(serverScopedStatePath), { recursive: true });
+  await writeFile(serverScopedStatePath, JSON.stringify({ pid: process.pid, httpPort: 43127 }) + '\n');
+
+  const serviceUrl = new URL('./service.mjs', import.meta.url).href;
+  const result = await runNode([
+    '--input-type=module',
+    '-e',
+    `const { postStartDiagnostics } = await import(${JSON.stringify(serviceUrl)}); await postStartDiagnostics();`,
+  ], { cwd: repoRoot, env: baseEnv });
+
+  assert.equal(result.code, 0, `expected diagnostics to complete\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  assert.match(result.stdout, /running.*pid=/s, `expected named-stack daemon running result\n${result.stdout}`);
+  assert.doesNotMatch(result.stdout, /auth required/i);
+});

package/scripts/service_cleanup_ownership.test.mjs

@@ -0,0 +1,41 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { stopServiceWithCanonicalCleanup } from './service.mjs';
+
+test('service stop, restart-stop, and disable execute OS destruction inside canonical cleanup ownership', async () => {
+  for (const scenario of [
+    { platform: 'win32', mode: 'user', disable: true, expected: ['schtasks:/End', 'schtasks:/Change'] },
+    { platform: 'darwin', mode: 'user', disable: false, expected: ['launchd'] },
+    { platform: 'linux', mode: 'system', disable: true, expected: ['systemctl:disable'] },
+    { platform: 'linux', mode: 'user', disable: false, expected: ['systemd-user'] },
+  ]) {
+    const events = [];
+    const env = {
+      HAPPIER_STACK_STACK: 'service-owner-test',
+      HAPPIER_STACK_STORAGE_DIR: '/tmp/happier-service-owner-test',
+    };
+    await stopServiceWithCanonicalCleanup({
+      rootDir: '/repo',
+      mode: scenario.mode,
+      persistent: scenario.disable,
+      requestedBy: 'service test',
+      reason: 'verify ownership',
+      disable: scenario.disable,
+      platform: scenario.platform,
+      env,
+      stopStackServiceWithEnvImpl: async (input, stopServiceImpl) => {
+        events.push('cleanup-owner-enter');
+        assert.equal(input.stopAttribution.requestedBy, 'service test');
+        await stopServiceImpl();
+        events.push('canonical-cleanup');
+      },
+      runImpl: async (command, args) => { events.push(`${command}:${args[0]}`); },
+      stopLaunchAgentImpl: async () => { events.push('launchd'); },
+      systemdStopImpl: async () => { events.push('systemd-user'); },
+    });
+    assert.equal(events[0], 'cleanup-owner-enter');
+    assert.deepEqual(events.slice(1, -1), scenario.expected);
+    assert.equal(events.at(-1), 'canonical-cleanup');
+  }
+});

package/scripts/setup.mjs

@@ -36,6 +36,7 @@ import { parseGithubOwnerRepo } from './utils/git/worktrees.mjs';
 import { findAnyCredentialPathInCliHome, findExistingStackCredentialPath } from './utils/auth/credentials_paths.mjs';
 import { normalizeStackNameOrNull } from './utils/stack/names.mjs';
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
+import { resolveEffectiveDbProviderTransition } from './utils/server/effective_db_provider.mjs';
 
 function resolveWorkspaceDirDefault() {
   const explicit = (process.env.HAPPIER_STACK_WORKSPACE_DIR ?? '').toString().trim();
@@ -305,6 +306,24 @@ async function ensureSetupConfigPersisted({ rootDir, profile, serverComponent, t
   const repoSourceForProfile = profile === 'selfhost' ? 'upstream' : null;
   const monoRepo = String(happierRepoUrl ?? '').trim();
   const stable = String(stableBranch ?? '').trim();
+  const previousServerComponent = process.env.HAPPIER_STACK_SERVER_COMPONENT?.trim() || 'happier-server-light';
+  const dbTransition = resolveEffectiveDbProviderTransition({
+    previousServerComponentName: previousServerComponent,
+    nextServerComponentName: serverComponent,
+    env: process.env,
+  });
+  if (!dbTransition.ok) {
+    if (dbTransition.reason === 'missing_mysql_database_url') {
+      throw new Error('[setup] mysql requires an explicit DATABASE_URL');
+    }
+    if (dbTransition.reason === 'missing_postgres_database_url') {
+      throw new Error('[setup] postgres requires an explicit DATABASE_URL with the light preset');
+    }
+    if (dbTransition.reason === 'invalid_postgres_database_url') {
+      throw new Error('[setup] postgres DATABASE_URL must use postgres:// or postgresql://');
+    }
+    throw new Error(`[setup] invalid DB provider for ${serverComponent}: ${dbTransition.input ?? dbTransition.reason}`);
+  }
   const updates = [
     ...(stable
       ? [
@@ -312,6 +331,8 @@ async function ensureSetupConfigPersisted({ rootDir, profile, serverComponent, t
         ]
       : []),
     { key: 'HAPPIER_STACK_SERVER_COMPONENT', value: serverComponent },
+    { key: 'HAPPIER_DB_PROVIDER', value: dbTransition.provider },
+    ...(dbTransition.databaseUrl ? [{ key: 'DATABASE_URL', value: dbTransition.databaseUrl }] : []),
     // Default for selfhost:
     // - monorepo: upstream (Happier)
     // - server-light: fork-only today (handled in bootstrap)
@@ -334,7 +355,11 @@ async function ensureSetupConfigPersisted({ rootDir, profile, serverComponent, t
         ]
       : []),
   ];
-  await ensureEnvLocalUpdated({ rootDir, updates });
+  await ensureEnvLocalUpdated({
+    rootDir,
+    updates,
+    removeKeys: dbTransition.removeDatabaseUrl ? ['DATABASE_URL'] : [],
+  });
 }
 
 async function ensureSystemdAvailable() {

package/scripts/setup_dev_child_env.test.mjs

@@ -132,8 +132,8 @@ function mark(payload) {
   appendFileSync(markerPath, String(payload) + '\\n', 'utf-8');
 }
 
-export async function ensureEnvLocalUpdated() {
-  mark(JSON.stringify({ type: 'ensureEnvLocalUpdated' }));
+export async function ensureEnvLocalUpdated({ updates, removeKeys }) {
+  mark(JSON.stringify({ type: 'ensureEnvLocalUpdated', updates, removeKeys }));
 }
 `),
     './utils/proc/commands.mjs': toDataUrl(`
@@ -176,6 +176,11 @@ export async function resolve(specifier, context, defaultResolve) {
 
   const env = {
     ...process.env,
+    HAPPIER_STACK_SERVER_COMPONENT: 'happier-server',
+    HAPPIER_DB_PROVIDER: 'mysql',
+    DATABASE_URL: 'mysql://operator:secret@db.example.test:3306/happier',
+    HAPPIER_STACK_ENV_FILE: '',
+    HAPPIER_STACK_DISABLE_STACK_ENV_AUTOLOAD: '1',
     HAPPIER_STACK_TEST_TTY: '1',
     HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
     HAPPIER_STACK_STORAGE_DIR: join(tmp, 'storage'),
@@ -238,6 +243,22 @@ export async function resolve(specifier, context, defaultResolve) {
     assert.equal(stackCheck.gotEnvArg, true, 'expected stackExistsSync to receive explicit setup env for existence checks');
     assert.equal(stackCheck.setupChild, '1', `expected setup-child marker on stackExistsSync, got ${stackCheck.setupChild}`);
     assert.equal(stackCheck.workspace, workspaceDir, `expected workspace propagation on stackExistsSync, got ${stackCheck.workspace}`);
+
+    const setupConfigWrite = records.find((record) =>
+      record.type === 'ensureEnvLocalUpdated' &&
+      (record.updates ?? []).some((update) => update.key === 'HAPPIER_STACK_SERVER_COMPONENT')
+    );
+    assert.ok(setupConfigWrite, 'expected setup config persistence call');
+    assert.deepEqual(
+      (setupConfigWrite.updates ?? []).filter((update) =>
+        update.key === 'HAPPIER_STACK_SERVER_COMPONENT' || update.key === 'HAPPIER_DB_PROVIDER'
+      ),
+      [
+        { key: 'HAPPIER_STACK_SERVER_COMPONENT', value: 'happier-server-light' },
+        { key: 'HAPPIER_DB_PROVIDER', value: 'mysql' },
+      ],
+    );
+    assert.deepEqual(setupConfigWrite.removeKeys, []);
   } finally {
     await rm(tmp, { recursive: true, force: true });
   }

package/scripts/sqlite_snapshot.mjs

@@ -0,0 +1,86 @@
+import './utils/env/env.mjs';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import {
+  createSqliteSnapshot,
+  restoreSqliteSnapshot,
+} from './utils/sqlite/sqlite_snapshot.mjs';
+
+function usage() {
+  return [
+    '[sqlite-snapshot] usage:',
+    '  hstack sqlite-snapshot snapshot --source PATH --output PATH --disposable-root PATH [--json]',
+    '  hstack sqlite-snapshot restore --snapshot PATH --output PATH --disposable-root PATH [--json]',
+    '',
+    'Safety:',
+    '- Every path must be absolute; stack paths are never inferred.',
+    '- Output must not exist and must be under the explicit disposable root.',
+    '- Snapshot publishes a sibling .manifest.json with content, structure, and Prisma-ledger fingerprints.',
+    '- Fingerprints detect mismatches; they do not authenticate files or replace controlled root access.',
+    '- Restore accepts only a snapshot and matching manifest under that same disposable root.',
+    '- Direct symlink inputs, roots, and output parents are rejected; resolved paths cannot escape the root.',
+    '- Snapshot uses SQLite online backup, so committed WAL state is included.',
+    '- Private mode enforcement must be rehearsed on the target OS and filesystem before use.',
+    '- Publication is atomic and no-overwrite, but is not a system-crash durability guarantee.',
+    '- Keep the disposable root quiescent for the full operation.',
+    '- Namespace replacement fails closed but can leave a private partial or unmanifested database for operator removal.',
+  ].join('\n');
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  const operation = argv.find((value) => !value.startsWith('-'));
+  if (!operation || wantsHelp(argv, { flags }) || operation === 'help') {
+    printResult({
+      json,
+      data: {
+        commands: ['snapshot', 'restore'],
+        requiredFlags: ['--output', '--disposable-root'],
+      },
+      text: usage(),
+    });
+    return;
+  }
+
+  const outputPath = kv.get('--output');
+  const disposableRoot = kv.get('--disposable-root');
+  let result;
+  if (operation === 'snapshot') {
+    result = await createSqliteSnapshot({
+      sourcePath: kv.get('--source'),
+      outputPath,
+      disposableRoot,
+    });
+  } else if (operation === 'restore') {
+    result = await restoreSqliteSnapshot({
+      snapshotPath: kv.get('--snapshot'),
+      outputPath,
+      disposableRoot,
+    });
+  } else {
+    throw new Error(`unknown sqlite-snapshot operation: ${operation}`);
+  }
+
+  printResult({
+    json,
+    data: { ok: true, ...result },
+    text: [
+      `[sqlite-snapshot] ${result.operation} complete`,
+      `output: ${result.outputPath}`,
+      `manifest: ${result.manifestPath}`,
+      `integrity_check: ${result.integrityCheck}`,
+      `content_sha256: ${result.fingerprints.contentSha256}`,
+      `structure_sha256: ${result.fingerprints.structureSha256}`,
+      `prisma_migrations: ${result.fingerprints.prismaMigrations.state}`,
+    ].join('\n'),
+  });
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[sqlite-snapshot] failed: ${message}`);
+  process.exit(1);
+});