@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/self_host_runtime.test.mjs

@@ -1,11 +1,12 @@
 import assert from 'node:assert/strict';
 import { createHash, generateKeyPairSync, sign } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from 'node:fs/promises';
 import test from 'node:test';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import * as selfHostRuntimeModule from './self_host_runtime.mjs';
 
 import {
   parseSelfHostInvocation,
@@ -30,7 +31,10 @@ import {
   mergeEnvTextWithDefaults,
   installBinaryAtomically,
   installSelfHostBinaryFromLocalPath,
+  installUiWebFromEmbeddedRuntime,
+  resolveSelfHostServerInstallFromReleaseParams,
 } from './self_host_runtime.mjs';
+import { buildServiceDefinition, resolveServiceBackend } from './utils/service/service_manager.mjs';
 
 function b64(buf) {
   return Buffer.from(buf).toString('base64');
@@ -84,10 +88,87 @@ async function createLocalSelfHostRuntimePayloadRoot({ rootDir, binaryName, bina
   await writeFile(join(rootDir, 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = {};\n', 'utf-8');
   const binaryPath = join(rootDir, binaryName);
   await writeFile(binaryPath, binaryText, 'utf-8');
-  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  await chmod(binaryPath, 0o755);
   return binaryPath;
 }
 
+test('local self-host runtime promotion exposes the server-embedded UI to the post-promote owner', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-embedded-ui-test-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const binaryName = 'happier-server';
+  const payloadRoot = join(tmp, 'payload');
+  const sourceBinaryPath = await createLocalSelfHostRuntimePayloadRoot({ rootDir: payloadRoot, binaryName });
+  await mkdir(join(payloadRoot, 'ui-web', 'current'), { recursive: true });
+  await writeFile(join(payloadRoot, 'ui-web', 'current', 'index.html'), '<!doctype html><title>embedded</title>', 'utf-8');
+
+  const installRoot = join(tmp, 'install');
+  const config = {
+    platform: process.platform,
+    dataDir: join(installRoot, 'data'),
+    versionsDir: join(installRoot, 'versions'),
+    serverBinaryPath: join(installRoot, 'bin', binaryName),
+    serverPreviousBinaryPath: join(installRoot, 'bin', `${binaryName}.previous`),
+  };
+  let observedEmbeddedUi = '';
+
+  await selfHostRuntimeModule.installSelfHostBinaryFromLocalPath({
+    sourceBinaryPath,
+    binaryName,
+    config,
+    afterPromote: async ({ embeddedUiDir }) => {
+      observedEmbeddedUi = await readFile(join(embeddedUiDir, 'index.html'), 'utf-8');
+    },
+  });
+
+  assert.equal(observedEmbeddedUi, '<!doctype html><title>embedded</title>');
+});
+
+test('local self-host runtime promotion keeps the complete migration closure beside the installed server', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-migration-closure-test-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const binaryName = 'happier-server';
+  const payloadRoot = join(tmp, 'payload');
+  const sourceBinaryPath = await createLocalSelfHostRuntimePayloadRoot({ rootDir: payloadRoot, binaryName });
+  await mkdir(join(payloadRoot, 'runtime'), { recursive: true });
+  await mkdir(join(payloadRoot, 'prisma', 'migrations'), { recursive: true });
+  await writeFile(join(payloadRoot, 'runtime', 'prisma-migrate'), 'runner\n', 'utf8');
+  await writeFile(join(payloadRoot, 'prisma', 'migrations', 'migration.sql'), '-- migration\n', 'utf8');
+  await writeFile(join(payloadRoot, 'happier-server-migrate'), '#!/bin/sh\nexit 0\n', 'utf8');
+  await chmod(join(payloadRoot, 'happier-server-migrate'), 0o755);
+
+  const installRoot = join(tmp, 'install');
+  const config = {
+    platform: process.platform,
+    dataDir: join(installRoot, 'data'),
+    versionsDir: join(installRoot, 'versions'),
+    serverBinaryPath: join(installRoot, 'bin', binaryName),
+    serverPreviousBinaryPath: join(installRoot, 'bin', `${binaryName}.previous`),
+  };
+
+  await installSelfHostBinaryFromLocalPath({ sourceBinaryPath, binaryName, config });
+
+  assert.equal(await readFile(join(installRoot, 'bin', 'runtime', 'prisma-migrate'), 'utf8'), 'runner\n');
+  assert.equal(await readFile(join(installRoot, 'bin', 'prisma', 'migrations', 'migration.sql'), 'utf8'), '-- migration\n');
+  assert.match(await readFile(join(installRoot, 'bin', 'happier-server-migrate'), 'utf8'), /exit 0/);
+});
+
+test('managed UI activation fails closed when the server payload has no embedded UI', async () => {
+  await assert.rejects(
+    installUiWebFromEmbeddedRuntime({
+      config: {},
+      embeddedUiDir: '',
+      version: '0.2.10-test.1',
+    }),
+    /missing its embedded UI/i,
+  );
+});
+
 test('parseSelfHostInvocation accepts optional self-host prefix', () => {
   const parsed = parseSelfHostInvocation(['self-host', 'install', '--channel=preview']);
   assert.equal(parsed.subcommand, 'install');
@@ -100,6 +181,81 @@ test('parseSelfHostInvocation supports direct command invocation', () => {
   assert.deepEqual(parsed.rest, ['--json']);
 });
 
+test('relay-host forwarding maps legacy HStack update onto the canonical idempotent install command', () => {
+  assert.deepEqual(
+    selfHostRuntimeModule.resolveRelayHostForwardedArgv(['update', '--channel=preview', '--json']),
+    ['install', '--channel=preview', '--json'],
+  );
+  assert.deepEqual(
+    selfHostRuntimeModule.resolveRelayHostForwardedArgv(['status', '--channel=preview', '--json']),
+    ['status', '--channel=preview', '--json'],
+  );
+});
+
+test('self-host install-time migration delegates to the canonical provider plan', async () => {
+  assert.equal(typeof selfHostRuntimeModule.applySelfHostServerMigrationsAtInstallTime, 'function');
+  const calls = [];
+  const env = {
+    HAPPIER_SQLITE_AUTO_MIGRATE: '0',
+    HAPPIER_SQLITE_MIGRATIONS_DIR: '/var/lib/happier/migrations/sqlite',
+    DATABASE_URL: 'file:/var/lib/happier/happier-server-light.sqlite',
+  };
+  const config = {
+    installRoot: '/opt/happier',
+    serverBinaryPath: '/opt/happier/bin/happier-server',
+  };
+
+  await selfHostRuntimeModule.applySelfHostServerMigrationsAtInstallTime({
+    config,
+    env,
+    runCommandImpl: (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+      return { status: 0 };
+    },
+  });
+
+  assert.deepEqual(calls, [
+    {
+      cmd: config.serverBinaryPath,
+      args: ['--migrate-only'],
+      options: {
+        cwd: config.installRoot,
+        env,
+        stdio: 'pipe',
+      },
+    },
+  ]);
+
+  calls.length = 0;
+  await selfHostRuntimeModule.applySelfHostServerMigrationsAtInstallTime({
+    config,
+    env: { HAPPIER_DB_PROVIDER: 'postgres', DATABASE_URL: 'postgresql://db/happier' },
+    runCommandImpl: (cmd, args, options) => {
+      calls.push({ cmd, args, options });
+      return { status: 0 };
+    },
+  });
+  assert.equal(calls[0].cmd, '/opt/happier/bin/happier-server-migrate');
+  assert.deepEqual(calls[0].args, []);
+});
+
+test('self-host install-time SQLite migration preserves canonical binary failure', async () => {
+  const failure = new Error('canonical migration exit 23');
+  await assert.rejects(
+    selfHostRuntimeModule.applySelfHostServerMigrationsAtInstallTime({
+      config: {
+        installRoot: '/opt/happier',
+        serverBinaryPath: '/opt/happier/bin/happier-server',
+      },
+      env: { HAPPIER_SQLITE_AUTO_MIGRATE: '0' },
+      runCommandImpl: () => {
+        throw failure;
+      },
+    }),
+    (error) => error === failure,
+  );
+});
+
 test('pickReleaseAsset returns matching archive and checksum assets', () => {
   const assets = [
     { name: 'happier-server-v1.2.3-linux-x64.tar.gz', browser_download_url: 'https://example.test/server.tar.gz' },
@@ -819,6 +975,444 @@ test('installSelfHostBinaryFromLocalPath prunes older retained local versions af
   assert.equal(existsSync(join(config.versionsDir, `${binaryName}-local-2000`)), true);
 });
 
+test('installSelfHostBinaryFromLocalPath runs the pre-promotion hook before mutating the active runtime', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-local-pre-promote-test-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const installRoot = join(tmp, 'install');
+  const binaryName = 'happier-server';
+  const config = {
+    platform: process.platform,
+    dataDir: join(installRoot, 'data'),
+    versionsDir: join(installRoot, 'versions'),
+    serverBinaryPath: join(installRoot, 'bin', binaryName),
+    serverPreviousBinaryPath: join(installRoot, 'bin', `${binaryName}.previous`),
+  };
+
+  await mkdir(join(dirname(config.serverBinaryPath), 'generated'), { recursive: true });
+  await mkdir(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(config.serverBinaryPath, '#!/bin/sh\necho old-runtime\n', 'utf-8');
+  await chmod(config.serverBinaryPath, 0o755);
+  await writeFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'old-generated', 'utf-8');
+  await writeFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'old-engine', 'utf-8');
+  await writeFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = { old: true };\n', 'utf-8');
+
+  const source = await createLocalSelfHostRuntimePayloadRoot({
+    rootDir: join(tmp, 'payload'),
+    binaryName,
+    binaryText: '#!/bin/sh\necho new-runtime\n',
+  });
+
+  const hookSnapshots = [];
+
+  await installSelfHostBinaryFromLocalPath({
+    sourceBinaryPath: source,
+    binaryName,
+    config,
+    beforeRuntimePromote: async () => {
+      hookSnapshots.push({
+        binary: await readFile(config.serverBinaryPath, 'utf-8'),
+        generated: await readFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'utf-8'),
+        prismaEngine: await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'utf-8'),
+      });
+    },
+  });
+
+  assert.deepEqual(hookSnapshots, [{
+    binary: '#!/bin/sh\necho old-runtime\n',
+    generated: 'old-generated',
+    prismaEngine: 'old-engine',
+  }]);
+});
+
+test('runSelfHostRuntimeMutationWithServiceRecovery restores the previous service definition and env after a later failure', async (t) => {
+  assert.equal(typeof selfHostRuntimeModule.runSelfHostRuntimeMutationWithServiceRecovery, 'function');
+
+  const tempRoot = await mkdtemp(join(tmpdir(), 'happier-self-host-service-recovery-'));
+  const binDir = join(tempRoot, 'bin');
+  const logPath = join(tempRoot, 'systemctl.log');
+  const previousPath = process.env.PATH;
+  const previousLogPath = process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;
+  const previousHome = process.env.HOME;
+
+  t.after(async () => {
+    process.env.PATH = previousPath;
+    if (previousHome == null) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
+    if (previousLogPath == null) {
+      delete process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;
+    } else {
+      process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH = previousLogPath;
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await mkdir(binDir, { recursive: true });
+  const systemctlPath = join(binDir, 'systemctl');
+  await writeFile(
+    systemctlPath,
+    [
+      '#!/usr/bin/env node',
+      "const fs = require('node:fs');",
+      "const logPath = process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;",
+      "if (logPath) fs.appendFileSync(logPath, `${JSON.stringify(process.argv.slice(2))}\\n`, 'utf8');",
+    ].join('\n'),
+    'utf8',
+  );
+  await chmod(systemctlPath, 0o755);
+
+  process.env.PATH = `${binDir}${process.platform === 'win32' ? ';' : ':'}${previousPath ?? ''}`;
+  process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH = logPath;
+  process.env.HOME = tempRoot;
+
+  const config = {
+    platform: 'linux',
+    mode: 'user',
+    serviceName: 'happier-self-host-preview',
+    installRoot: join(tempRoot, 'install'),
+    versionsDir: join(tempRoot, 'install', 'versions'),
+    configDir: join(tempRoot, 'install', 'config'),
+    configEnvPath: join(tempRoot, 'install', 'config', 'server.env'),
+    serverBinaryPath: join(tempRoot, 'install', 'bin', 'happier-server'),
+    serverStdoutLogPath: join(tempRoot, 'install', 'logs', 'server.out.log'),
+    serverStderrLogPath: join(tempRoot, 'install', 'logs', 'server.err.log'),
+  };
+
+  await mkdir(join(dirname(config.serverBinaryPath), 'generated'), { recursive: true });
+  await mkdir(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(config.serverBinaryPath, '#!/bin/sh\necho old-runtime\n', 'utf8');
+  await chmod(config.serverBinaryPath, 0o755);
+  await writeFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'old-generated', 'utf8');
+  await writeFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'old-engine', 'utf8');
+  await writeFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = { old: true };\n', 'utf8');
+
+  await mkdir(dirname(config.configEnvPath), { recursive: true });
+  const previousEnvText = 'PORT=4010\nCUSTOM_FLAG=previous\n';
+  await writeFile(config.configEnvPath, previousEnvText, 'utf8');
+
+  const backend = resolveServiceBackend({ platform: config.platform, mode: config.mode });
+  const definition = buildServiceDefinition({
+    backend,
+    homeDir: tempRoot,
+    spec: {
+      label: config.serviceName,
+      description: `Happier Self-Host (${config.serviceName})`,
+      programArgs: [config.serverBinaryPath],
+      workingDirectory: config.installRoot,
+      env: {},
+      stdoutPath: config.serverStdoutLogPath,
+      stderrPath: config.serverStderrLogPath,
+    },
+  });
+  await mkdir(dirname(definition.path), { recursive: true });
+  await writeFile(definition.path, definition.contents, 'utf8');
+
+  await assert.rejects(
+    selfHostRuntimeModule.runSelfHostRuntimeMutationWithServiceRecovery({
+      config,
+      mutateRuntime: async ({ beforeRuntimePromote }) => {
+        await beforeRuntimePromote();
+        await writeFile(config.configEnvPath, 'PORT=9999\nCUSTOM_FLAG=new\n', 'utf8');
+        throw new Error('simulated runtime install failure');
+      },
+    }),
+    /simulated runtime install failure/,
+  );
+
+  assert.equal(await readFile(config.configEnvPath, 'utf8'), previousEnvText);
+  const systemctlInvocations = (await readFile(logPath, 'utf8'))
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+
+  assert.deepEqual(systemctlInvocations, [
+    ['--user', 'disable', '--now', `${config.serviceName}.service`],
+    ['--user', 'daemon-reload'],
+    ['--user', 'enable', `${config.serviceName}.service`],
+    ['--user', 'restart', `${config.serviceName}.service`],
+  ]);
+});
+
+test('runSelfHostRuntimeMutationWithServiceRecovery does not recreate env or reinstall a missing service after a first-install failure', async (t) => {
+  assert.equal(typeof selfHostRuntimeModule.runSelfHostRuntimeMutationWithServiceRecovery, 'function');
+
+  const tempRoot = await mkdtemp(join(tmpdir(), 'happier-self-host-first-install-failure-'));
+  const binDir = join(tempRoot, 'bin');
+  const logPath = join(tempRoot, 'systemctl.log');
+  const previousPath = process.env.PATH;
+  const previousLogPath = process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;
+  const previousHome = process.env.HOME;
+
+  t.after(async () => {
+    process.env.PATH = previousPath;
+    if (previousHome == null) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
+    if (previousLogPath == null) {
+      delete process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;
+    } else {
+      process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH = previousLogPath;
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await mkdir(binDir, { recursive: true });
+  const systemctlPath = join(binDir, 'systemctl');
+  await writeFile(
+    systemctlPath,
+    [
+      '#!/usr/bin/env node',
+      "const fs = require('node:fs');",
+      "const logPath = process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;",
+      "if (logPath) fs.appendFileSync(logPath, `${JSON.stringify(process.argv.slice(2))}\\n`, 'utf8');",
+    ].join('\n'),
+    'utf8',
+  );
+  await chmod(systemctlPath, 0o755);
+
+  process.env.PATH = `${binDir}${process.platform === 'win32' ? ';' : ':'}${previousPath ?? ''}`;
+  process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH = logPath;
+  process.env.HOME = tempRoot;
+
+  const config = {
+    platform: 'linux',
+    mode: 'user',
+    serviceName: 'happier-self-host-preview',
+    installRoot: join(tempRoot, 'install'),
+    versionsDir: join(tempRoot, 'install', 'versions'),
+    configDir: join(tempRoot, 'install', 'config'),
+    configEnvPath: join(tempRoot, 'install', 'config', 'server.env'),
+    serverBinaryPath: join(tempRoot, 'install', 'bin', 'happier-server'),
+    serverStdoutLogPath: join(tempRoot, 'install', 'logs', 'server.out.log'),
+    serverStderrLogPath: join(tempRoot, 'install', 'logs', 'server.err.log'),
+  };
+
+  await assert.rejects(
+    selfHostRuntimeModule.runSelfHostRuntimeMutationWithServiceRecovery({
+      config,
+      mutateRuntime: async ({ beforeRuntimePromote }) => {
+        await beforeRuntimePromote();
+        await mkdir(dirname(config.configEnvPath), { recursive: true });
+        await writeFile(config.configEnvPath, 'PORT=9999\nCUSTOM_FLAG=new\n', 'utf8');
+        throw new Error('simulated first install failure');
+      },
+    }),
+    /simulated first install failure/,
+  );
+
+  await assert.rejects(readFile(config.configEnvPath, 'utf8'));
+  const systemctlInvocations = (await readFile(logPath, 'utf8'))
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+
+  assert.deepEqual(systemctlInvocations, [
+    ['--user', 'disable', '--now', `${config.serviceName}.service`],
+  ]);
+});
+
+test('runSelfHostRuntimeMutationWithServiceRecovery restores promoted runtime, ui, env, and service state after a later failure', async (t) => {
+  assert.equal(typeof selfHostRuntimeModule.runSelfHostRuntimeMutationWithServiceRecovery, 'function');
+
+  const tempRoot = await mkdtemp(join(tmpdir(), 'happier-self-host-runtime-rollback-'));
+  const binDir = join(tempRoot, 'bin');
+  const logPath = join(tempRoot, 'systemctl.log');
+  const previousPath = process.env.PATH;
+  const previousLogPath = process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;
+  const previousHome = process.env.HOME;
+
+  t.after(async () => {
+    process.env.PATH = previousPath;
+    if (previousHome == null) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
+    if (previousLogPath == null) {
+      delete process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;
+    } else {
+      process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH = previousLogPath;
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await mkdir(binDir, { recursive: true });
+  const systemctlPath = join(binDir, 'systemctl');
+  await writeFile(
+    systemctlPath,
+    [
+      '#!/usr/bin/env node',
+      "const fs = require('node:fs');",
+      "const logPath = process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH;",
+      "if (logPath) fs.appendFileSync(logPath, `${JSON.stringify(process.argv.slice(2))}\\n`, 'utf8');",
+    ].join('\n'),
+    'utf8',
+  );
+  await chmod(systemctlPath, 0o755);
+
+  process.env.PATH = `${binDir}${process.platform === 'win32' ? ';' : ':'}${previousPath ?? ''}`;
+  process.env.HAPPIER_TEST_SYSTEMCTL_LOG_PATH = logPath;
+  process.env.HOME = tempRoot;
+
+  const config = {
+    platform: 'linux',
+    mode: 'user',
+    serviceName: 'happier-self-host-preview',
+    installRoot: join(tempRoot, 'install'),
+    versionsDir: join(tempRoot, 'install', 'versions'),
+    configDir: join(tempRoot, 'install', 'config'),
+    configEnvPath: join(tempRoot, 'install', 'config', 'server.env'),
+    serverBinaryPath: join(tempRoot, 'install', 'bin', 'happier-server'),
+    serverPreviousBinaryPath: join(tempRoot, 'install', 'bin', 'happier-server.previous'),
+    dataDir: join(tempRoot, 'install', 'data'),
+    uiWebRootDir: join(tempRoot, 'install', 'ui-web'),
+    uiWebVersionsDir: join(tempRoot, 'install', 'ui-web', 'versions'),
+    uiWebCurrentDir: join(tempRoot, 'install', 'ui-web', 'current'),
+    serverStdoutLogPath: join(tempRoot, 'install', 'logs', 'server.out.log'),
+    serverStderrLogPath: join(tempRoot, 'install', 'logs', 'server.err.log'),
+  };
+
+  await mkdir(join(dirname(config.serverBinaryPath), 'generated'), { recursive: true });
+  await mkdir(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(config.serverBinaryPath, '#!/bin/sh\necho old-runtime\n', 'utf8');
+  await chmod(config.serverBinaryPath, 0o755);
+  await writeFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'old-generated', 'utf8');
+  await writeFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'old-engine', 'utf8');
+  await writeFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = { old: true };\n', 'utf8');
+
+  await mkdir(dirname(config.configEnvPath), { recursive: true });
+  const previousEnvText = 'PORT=4010\nCUSTOM_FLAG=previous\n';
+  await writeFile(config.configEnvPath, previousEnvText, 'utf8');
+
+  await mkdir(join(config.dataDir, 'migrations', 'sqlite'), { recursive: true });
+  await writeFile(join(config.dataDir, 'migrations', 'sqlite', '0001-old.sql'), 'old-migration', 'utf8');
+
+  const previousUiVersionDir = join(config.uiWebVersionsDir, 'ui-web-old');
+  await mkdir(previousUiVersionDir, { recursive: true });
+  await writeFile(join(previousUiVersionDir, 'index.html'), 'old-ui', 'utf8');
+  await mkdir(dirname(config.uiWebCurrentDir), { recursive: true });
+  await symlink(previousUiVersionDir, config.uiWebCurrentDir, 'dir');
+
+  const backend = resolveServiceBackend({ platform: config.platform, mode: config.mode });
+  const definition = buildServiceDefinition({
+    backend,
+    homeDir: tempRoot,
+    spec: {
+      label: config.serviceName,
+      description: `Happier Self-Host (${config.serviceName})`,
+      programArgs: [config.serverBinaryPath],
+      workingDirectory: config.installRoot,
+      env: {},
+      stdoutPath: config.serverStdoutLogPath,
+      stderrPath: config.serverStderrLogPath,
+    },
+  });
+  await mkdir(dirname(definition.path), { recursive: true });
+  await writeFile(definition.path, definition.contents, 'utf8');
+
+  const sourceRoot = await mkdtemp(join(tempRoot, 'source-runtime-'));
+  const sourceBinaryPath = await createLocalSelfHostRuntimePayloadRoot({
+    rootDir: sourceRoot,
+    binaryName: 'happier-server',
+    binaryText: '#!/bin/sh\necho new-runtime\n',
+  });
+
+  await assert.rejects(
+    selfHostRuntimeModule.runSelfHostRuntimeMutationWithServiceRecovery({
+      config,
+      mutateRuntime: async ({ beforeRuntimePromote }) => {
+        await selfHostRuntimeModule.installSelfHostBinaryFromLocalPath({
+          sourceBinaryPath,
+          binaryName: 'happier-server',
+          config,
+          beforeRuntimePromote,
+          afterPromote: async () => {
+            await selfHostRuntimeModule.runSelfHostUiWebMutationWithRollback({
+              config,
+              mutateUi: async () => {
+                const nextUiVersionDir = join(config.uiWebVersionsDir, 'ui-web-new');
+                await mkdir(nextUiVersionDir, { recursive: true });
+                await writeFile(join(nextUiVersionDir, 'index.html'), 'new-ui', 'utf8');
+                await rm(config.uiWebCurrentDir, { recursive: true, force: true });
+                await symlink(nextUiVersionDir, config.uiWebCurrentDir, 'dir');
+                await writeFile(config.configEnvPath, 'PORT=9999\nCUSTOM_FLAG=new\n', 'utf8');
+                throw new Error('simulated post-promotion failure');
+              },
+            });
+          },
+        });
+      },
+    }),
+    /simulated post-promotion failure/,
+  );
+
+  assert.equal(await readFile(config.serverBinaryPath, 'utf8'), '#!/bin/sh\necho old-runtime\n');
+  assert.equal(await readFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'utf8'), 'old-generated');
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'utf8'),
+    'old-engine'
+  );
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'utf8'),
+    'module.exports = { old: true };\n'
+  );
+  assert.equal(await readFile(config.configEnvPath, 'utf8'), previousEnvText);
+  assert.equal(await readlink(config.uiWebCurrentDir), previousUiVersionDir);
+  assert.equal(await readFile(join(previousUiVersionDir, 'index.html'), 'utf8'), 'old-ui');
+
+  const systemctlInvocations = (await readFile(logPath, 'utf8'))
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+
+  assert.deepEqual(systemctlInvocations, [
+    ['--user', 'disable', '--now', `${config.serviceName}.service`],
+    ['--user', 'daemon-reload'],
+    ['--user', 'enable', `${config.serviceName}.service`],
+    ['--user', 'restart', `${config.serviceName}.service`],
+  ]);
+});
+
+test('resolveSelfHostServerInstallFromReleaseParams carries the local server binary override from env', () => {
+  const config = {
+    platform: 'linux',
+    versionsDir: '/tmp/versions',
+    serverBinaryPath: '/tmp/bin/happier-server',
+  };
+  const beforeRuntimePromote = async () => {};
+
+  const params = resolveSelfHostServerInstallFromReleaseParams({
+    product: 'happier-server',
+    binaryName: 'happier-server',
+    config,
+    env: {
+      HAPPIER_SELF_HOST_SERVER_BINARY: '/tmp/local/happier-server',
+    },
+    beforeRuntimePromote,
+  });
+
+  assert.deepEqual(params, {
+    product: 'happier-server',
+    binaryName: 'happier-server',
+    config,
+    explicitBinaryPath: '/tmp/local/happier-server',
+    beforeRuntimePromote,
+  });
+});
+
 test('installBinaryAtomically swaps a running binary on Linux without ETXTBSY', async (t) => {
   if (process.platform !== 'linux') {
     t.skip('ETXTBSY behavior is Linux-specific');
@@ -872,30 +1466,6 @@ test('installBinaryAtomically swaps a running binary on Linux without ETXTBSY',
   assert.equal(ran.status, 0, `expected swapped binary to run cleanly, got:\n${ran.stderr || ran.stdout || ''}`);
 });
 
-test('resolveExtractedUiWebBundleRootDir picks the directory that contains index.html', async (t) => {
-  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-ui-root-test-'));
-  t.after(async () => {
-    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
-  });
-
-  const extractDir = join(tmp, 'extract');
-  await mkdir(extractDir, { recursive: true });
-
-  // Extra top-level entry that should be ignored (e.g. AppleDouble metadata files).
-  await writeFile(join(extractDir, '000-root-metadata'), 'metadata', 'utf-8');
-
-  const bundleRootName = 'happier-ui-web-v1.2.3-web-any';
-  const bundleRootDir = join(extractDir, bundleRootName);
-  await mkdir(bundleRootDir, { recursive: true });
-  await writeFile(join(bundleRootDir, 'index.html'), '<!doctype html>', 'utf-8');
-
-  const mod = await import('./self_host_runtime.mjs');
-  assert.equal(typeof mod.resolveExtractedUiWebBundleRootDir, 'function');
-
-  const resolved = await mod.resolveExtractedUiWebBundleRootDir({ extractDir });
-  assert.equal(resolved, bundleRootDir);
-});
-
 test('resolveSelfHostEffectiveServerPort prefers PORT override', async () => {
   const mod = await import('./self_host_runtime.mjs');
   assert.equal(typeof mod.resolveSelfHostEffectiveServerPort, 'function');
@@ -983,6 +1553,67 @@ test('resolveSelfHostDefaults isolates publicdev into a side-by-side self-host r
   assert.equal(cfg.serviceName, 'happier-server-dev');
 });
 
+test('resolveConfig defaults serviceName to the channel-suffixed self-host defaults', () => {
+  const previous = {
+    HAPPIER_SELF_HOST_SERVICE_NAME: process.env.HAPPIER_SELF_HOST_SERVICE_NAME,
+  };
+
+  process.env.HAPPIER_SELF_HOST_SERVICE_NAME = '';
+  try {
+    const cfg = selfHostRuntimeModule.resolveConfig({ platform: 'linux', mode: 'user', channel: 'publicdev' });
+    assert.equal(cfg.serviceName, 'happier-server-dev');
+  } finally {
+    process.env.HAPPIER_SELF_HOST_SERVICE_NAME = previous.HAPPIER_SELF_HOST_SERVICE_NAME;
+  }
+});
+
+test('resolveConfig expands ~/ self-host path overrides against HOME', async () => {
+  const mod = await import('./self_host_runtime.mjs');
+  assert.equal(typeof mod.resolveConfig, 'function');
+
+  const previous = {
+    HOME: process.env.HOME,
+    USERPROFILE: process.env.USERPROFILE,
+    HAPPIER_SELF_HOST_INSTALL_ROOT: process.env.HAPPIER_SELF_HOST_INSTALL_ROOT,
+    HAPPIER_SELF_HOST_BIN_DIR: process.env.HAPPIER_SELF_HOST_BIN_DIR,
+    HAPPIER_SELF_HOST_CONFIG_DIR: process.env.HAPPIER_SELF_HOST_CONFIG_DIR,
+    HAPPIER_SELF_HOST_DATA_DIR: process.env.HAPPIER_SELF_HOST_DATA_DIR,
+    HAPPIER_SELF_HOST_LOG_DIR: process.env.HAPPIER_SELF_HOST_LOG_DIR,
+  };
+
+  process.env.HOME = '/scoped/home';
+  process.env.USERPROFILE = '/scoped/home';
+  process.env.HAPPIER_SELF_HOST_INSTALL_ROOT = '~/relay/install';
+  process.env.HAPPIER_SELF_HOST_BIN_DIR = '~/relay/bin';
+  process.env.HAPPIER_SELF_HOST_CONFIG_DIR = '~/relay/config';
+  process.env.HAPPIER_SELF_HOST_DATA_DIR = '~/relay/data';
+  process.env.HAPPIER_SELF_HOST_LOG_DIR = '~/relay/logs';
+
+  try {
+    const config = mod.resolveConfig({ platform: 'linux', mode: 'user', channel: 'stable' });
+    assert.equal(config.installRoot, '/scoped/home/relay/install');
+    assert.equal(config.binDir, '/scoped/home/relay/bin');
+    assert.equal(config.configDir, '/scoped/home/relay/config');
+    assert.equal(config.dataDir, '/scoped/home/relay/data');
+    assert.equal(config.logDir, '/scoped/home/relay/logs');
+  } finally {
+    if (previous.HOME === undefined) delete process.env.HOME;
+    else process.env.HOME = previous.HOME;
+    if (previous.USERPROFILE === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = previous.USERPROFILE;
+    if (previous.HAPPIER_SELF_HOST_INSTALL_ROOT === undefined) delete process.env.HAPPIER_SELF_HOST_INSTALL_ROOT;
+    else process.env.HAPPIER_SELF_HOST_INSTALL_ROOT = previous.HAPPIER_SELF_HOST_INSTALL_ROOT;
+    if (previous.HAPPIER_SELF_HOST_BIN_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_BIN_DIR;
+    else process.env.HAPPIER_SELF_HOST_BIN_DIR = previous.HAPPIER_SELF_HOST_BIN_DIR;
+    if (previous.HAPPIER_SELF_HOST_CONFIG_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_CONFIG_DIR;
+    else process.env.HAPPIER_SELF_HOST_CONFIG_DIR = previous.HAPPIER_SELF_HOST_CONFIG_DIR;
+    if (previous.HAPPIER_SELF_HOST_DATA_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_DATA_DIR;
+    else process.env.HAPPIER_SELF_HOST_DATA_DIR = previous.HAPPIER_SELF_HOST_DATA_DIR;
+    if (previous.HAPPIER_SELF_HOST_LOG_DIR === undefined) delete process.env.HAPPIER_SELF_HOST_LOG_DIR;
+    else process.env.HAPPIER_SELF_HOST_LOG_DIR = previous.HAPPIER_SELF_HOST_LOG_DIR;
+  }
+});
+
 test('resolveMinisignPublicKeyText prefers inline override and otherwise returns bundled key', () => {
   const bundled = resolveMinisignPublicKeyText({});
   assert.match(bundled, /minisign public key/i);
@@ -1000,7 +1631,7 @@ test('renderServerEnvFile emits sqlite/local defaults for self-host mode', () =>
   assert.match(envText, /PORT=3005/);
   assert.match(envText, /METRICS_ENABLED=false/);
   assert.match(envText, /HAPPIER_DB_PROVIDER=sqlite/);
-  assert.match(envText, /DATABASE_URL=file:\/var\/lib\/happier\/happier-server-light\.sqlite/);
+  assert.match(envText, /DATABASE_URL=file:\/\/\/var\/lib\/happier\/happier-server-light\.sqlite/);
   assert.match(envText, /HAPPIER_FILES_BACKEND=local/);
   assert.match(envText, /HAPPIER_SQLITE_AUTO_MIGRATE=1/);
   assert.match(envText, /HAPPIER_SQLITE_MIGRATIONS_DIR=\/var\/lib\/happier\/migrations\/sqlite/);
@@ -1063,16 +1694,16 @@ test('renderServerEnvFile includes PRISMA_QUERY_ENGINE_LIBRARY for packaged post
   assert.match(envText, new RegExp(`NODE_PATH=${join(serverBinDir, 'node_modules').replaceAll('\\\\', '\\\\\\\\')}`));
 });
 
-test('renderServerEnvFile uses file URL semantics on Windows', () => {
+test('renderServerEnvFile uses Prisma-compatible sqlite DATABASE_URL semantics on Windows', () => {
   const envText = renderServerEnvFile({
     port: 3005,
     host: '127.0.0.1',
     platform: 'win32',
-    dataDir: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\data',
-    filesDir: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\data\\\\files',
-    dbDir: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\data\\\\pglite',
+    dataDir: 'C:\\\\Users\\\\me\\\\Happier QA\\\\self-host\\\\data',
+    filesDir: 'C:\\\\Users\\\\me\\\\Happier QA\\\\self-host\\\\data\\\\files',
+    dbDir: 'C:\\\\Users\\\\me\\\\Happier QA\\\\self-host\\\\data\\\\pglite',
   });
-  assert.match(envText, /DATABASE_URL=file:\/\/\/C:\/Users\/me\/\.happier\/self-host\/data\/happier-server-light\.sqlite/);
+  assert.match(envText, /DATABASE_URL=file:C:\/Users\/me\/Happier%20QA\/self-host\/data\/happier-server-light\.sqlite/);
 });
 
 test('resolveSelfHostHealthTimeoutMs defaults to a safe health timeout', () => {
@@ -1224,14 +1855,12 @@ test('resolveSelfHostReleaseTargets maps the publicdev ring to dev rolling tags'
   const targets = resolveSelfHostReleaseTargets('publicdev');
   assert.equal(targets.serverTag, 'server-dev');
   assert.deepEqual(targets.serverTags, ['server-dev', 'server-preview', 'server-stable']);
-  assert.deepEqual(targets.uiWebTags, ['ui-web-dev', 'ui-web-preview', 'ui-web-stable']);
 });
 
 test('resolveSelfHostReleaseTargets preserves stable release tags without fallback churn', () => {
   const targets = resolveSelfHostReleaseTargets('stable');
   assert.equal(targets.serverTag, 'server-stable');
   assert.deepEqual(targets.serverTags, ['server-stable']);
-  assert.deepEqual(targets.uiWebTags, ['ui-web-stable']);
 });
 
 test('buildUpdaterScheduledTaskCreateArgs uses DAILY schedule when at is provided', () => {
@@ -1246,6 +1875,15 @@ test('buildUpdaterScheduledTaskCreateArgs uses DAILY schedule when at is provide
   assert.equal(args.includes('MINUTE'), false);
 });
 
+test('buildUpdaterScheduledTaskCreateArgs uses hidden non-interactive PowerShell on Windows', () => {
+  const args = buildUpdaterScheduledTaskCreateArgs({
+    backend: 'schtasks-user',
+    taskName: 'Happier\\\\happier-server-updater',
+    definitionPath: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\services\\\\happier-server-updater.ps1',
+  });
+  assert.equal(args[args.indexOf('/TR') + 1], 'powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\services\\\\happier-server-updater.ps1"');
+});
+
 test('mergeEnvTextWithDefaults preserves overrides while backfilling new default keys', () => {
   const defaults = renderServerEnvFile({
     port: 3005,
@@ -1335,12 +1973,11 @@ test('buildSelfHostDoctorChecks does not require external minisign and includes
     },
     {
       state: { uiWeb: { installed: true } },
-      commandExists: (name) => new Set(['tar', 'systemctl']).has(name),
+      commandExists: (name) => name === 'systemctl',
       pathExists: (p) => p.endsWith('happier-server') || p.endsWith('server.env') || p.endsWith('index.html'),
     },
   );
 
-  assert.ok(checks.find((c) => c.name === 'tar')?.ok);
   assert.ok(checks.find((c) => c.name === 'systemctl')?.ok);
   assert.equal(checks.some((c) => c.name === 'minisign'), false);
   assert.ok(checks.find((c) => c.name === 'ui-web')?.ok);
@@ -1365,6 +2002,42 @@ test('buildSelfHostDoctorChecks flags missing ui-web bundle when state expects u
   assert.equal(checks.find((c) => c.name === 'ui-web')?.ok, false);
 });
 
+test('buildSelfHostDoctorChecks resolves Windows PATHEXT commands without an external where executable', async (t) => {
+  const originalPlatformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform');
+  assert.ok(originalPlatformDescriptor);
+  const originalPath = process.env.PATH;
+  const originalPathExt = process.env.PATHEXT;
+  const root = await mkdtemp(join(tmpdir(), 'happier-self-host-doctor-windows-path-'));
+  t.after(async () => {
+    Object.defineProperty(process, 'platform', originalPlatformDescriptor);
+    if (originalPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalPath;
+    if (originalPathExt === undefined) delete process.env.PATHEXT;
+    else process.env.PATHEXT = originalPathExt;
+    await rm(root, { recursive: true, force: true });
+  });
+
+  await writeFile(join(root, 'powershell.exe'), '', 'utf8');
+  await writeFile(join(root, 'schtasks.exe'), '', 'utf8');
+  Object.defineProperty(process, 'platform', { ...originalPlatformDescriptor, value: 'win32' });
+  process.env.PATH = root;
+  process.env.PATHEXT = '.EXE;.CMD';
+
+  const checks = buildSelfHostDoctorChecks({
+    platform: 'win32',
+    mode: 'user',
+    serverBinaryPath: 'C:\\happier\\happier-server.exe',
+    configEnvPath: 'C:\\happier\\server.env',
+    uiWebCurrentDir: 'C:\\happier\\ui-web',
+  }, {
+    state: { uiWeb: { installed: false } },
+    pathExists: () => true,
+  });
+
+  assert.equal(checks.find((check) => check.name === 'powershell')?.ok, true);
+  assert.equal(checks.find((check) => check.name === 'schtasks')?.ok, true);
+});
+
 test('normalizeSelfHostAutoUpdateState upgrades legacy boolean config to structured config', () => {
   assert.deepEqual(
     normalizeSelfHostAutoUpdateState({ autoUpdate: true }, { fallbackIntervalMinutes: 1440 }),