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

package/scripts/self_host_runtime.test.mjs

@@ -1,13 +1,93 @@
 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 test from 'node:test';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
 
 import {
   parseSelfHostInvocation,
   pickReleaseAsset,
+  resolveSelfHostReleaseTargets,
+  resolveMinisignPublicKeyText,
+  resolveSelfHostAutoUpdateDefault,
+  resolveSelfHostAutoUpdateIntervalMinutes,
+  resolveSelfHostHealthTimeoutMs,
+  resolveSelfHostDefaults,
+  renderUpdaterLaunchdPlistXml,
+  renderUpdaterScheduledTaskWrapperPs1,
+  renderUpdaterSystemdUnit,
+  renderUpdaterSystemdTimerUnit,
+  buildUpdaterScheduledTaskCreateArgs,
   renderServerEnvFile,
   renderServerServiceUnit,
+  renderSelfHostStatusText,
+  buildSelfHostDoctorChecks,
+  normalizeSelfHostAutoUpdateState,
+  decideSelfHostAutoUpdateReconcile,
+  mergeEnvTextWithDefaults,
+  installBinaryAtomically,
+  installSelfHostBinaryFromLocalPath,
 } from './self_host_runtime.mjs';
 
+function b64(buf) {
+  return Buffer.from(buf).toString('base64');
+}
+
+function base64UrlToBuffer(value) {
+  const s = String(value ?? '')
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(Math.ceil(String(value ?? '').length / 4) * 4, '=');
+  return Buffer.from(s, 'base64');
+}
+
+function createMinisignKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const jwk = publicKey.export({ format: 'jwk' });
+  const rawPublicKey = base64UrlToBuffer(jwk.x);
+  assert.equal(rawPublicKey.length, 32);
+
+  const keyId = Buffer.from('0123456789abcdef', 'hex');
+  const publicKeyBytes = Buffer.concat([Buffer.from('Ed'), keyId, rawPublicKey]);
+  const pubkeyFile = `untrusted comment: minisign public key\n${b64(publicKeyBytes)}\n`;
+  return { pubkeyFile, keyId, privateKey };
+}
+
+function signMinisignMessage({ message, keyId, privateKey }) {
+  const signature = sign(null, message, privateKey);
+  const sigLineBytes = Buffer.concat([Buffer.from('Ed'), keyId, signature]);
+  const trustedComment = 'trusted comment: test';
+  const trustedSuffix = Buffer.from(trustedComment.slice('trusted comment: '.length), 'utf-8');
+  const globalSignature = sign(null, Buffer.concat([signature, trustedSuffix]), privateKey);
+  return [
+    'untrusted comment: signature from happier stack test',
+    b64(sigLineBytes),
+    trustedComment,
+    b64(globalSignature),
+    '',
+  ].join('\n');
+}
+
+function sha256Hex(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function createLocalSelfHostRuntimePayloadRoot({ rootDir, binaryName, binaryText = '#!/bin/sh\necho ok\n' }) {
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'ok', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '.prisma', 'client', 'query_engine.so'), 'engine', 'utf-8');
+  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' });
+  return binaryPath;
+}
+
 test('parseSelfHostInvocation accepts optional self-host prefix', () => {
   const parsed = parseSelfHostInvocation(['self-host', 'install', '--channel=preview']);
   assert.equal(parsed.subcommand, 'install');
@@ -37,6 +117,798 @@ test('pickReleaseAsset returns matching archive and checksum assets', () => {
   assert.equal(picked.signatureUrl, 'https://example.test/checksums.txt.minisig');
 });
 
+test('self-host release installer reports archive source url', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  const staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.3-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'ok', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '.prisma', 'client', 'query_engine.so'), 'engine', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = {};\n', 'utf-8');
+
+  const binaryName = 'happier-server';
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho ok\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await (await import('node:fs/promises')).readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const archiveUrl = `data:application/octet-stream;base64,${archiveBytes.toString('base64')}`;
+  const checksumsUrl = `data:text/plain,${encodeURIComponent(checksumsText)}`;
+  const sigUrl = `data:text/plain,${encodeURIComponent(sigFile)}`;
+
+  const bundle = {
+    version: '1.2.3-preview.1',
+    archive: { name: archiveName, url: archiveUrl },
+    checksums: { name: `checksums-happier-server-v1.2.3-preview.1.txt`, url: checksumsUrl },
+    checksumsSig: { name: `checksums-happier-server-v1.2.3-preview.1.txt.minisig`, url: sigUrl },
+  };
+
+  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`),
+  };
+
+  const mod = await import('./self_host_runtime.mjs');
+  assert.equal(typeof mod.installSelfHostBinaryFromBundle, 'function');
+
+  const result = await mod.installSelfHostBinaryFromBundle({
+    bundle,
+    binaryName,
+    config,
+    pubkeyFile,
+  });
+
+  assert.equal(result.version, '1.2.3-preview.1');
+  assert.equal(result.source, archiveUrl);
+  const packagedPrismaEngine = join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so');
+  const packagedPrismaClient = join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js');
+  const packagedPrismaCheck = spawnSync(
+    'bash',
+    [
+      '-lc',
+      `test -f "${packagedPrismaEngine.replaceAll('"', '\\"')}" && test -f "${packagedPrismaClient.replaceAll('"', '\\"')}"`,
+    ],
+    { encoding: 'utf-8' }
+  );
+  assert.equal(packagedPrismaCheck.status, 0, packagedPrismaCheck.stderr || packagedPrismaCheck.stdout);
+});
+
+test('self-host release installer fails closed when packaged node_modules sidecars are missing', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-missing-sidecars-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  const staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.3-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'ok', 'utf-8');
+
+  const binaryName = 'happier-server';
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho ok\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await (await import('node:fs/promises')).readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const archiveUrl = `data:application/octet-stream;base64,${archiveBytes.toString('base64')}`;
+  const checksumsUrl = `data:text/plain,${encodeURIComponent(checksumsText)}`;
+  const sigUrl = `data:text/plain,${encodeURIComponent(sigFile)}`;
+
+  const bundle = {
+    version: '1.2.3-preview.1',
+    archive: { name: archiveName, url: archiveUrl },
+    checksums: { name: `checksums-happier-server-v1.2.3-preview.1.txt`, url: checksumsUrl },
+    checksumsSig: { name: `checksums-happier-server-v1.2.3-preview.1.txt.minisig`, url: sigUrl },
+  };
+
+  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`),
+  };
+
+  const mod = await import('./self_host_runtime.mjs');
+  assert.equal(typeof mod.installSelfHostBinaryFromBundle, 'function');
+
+  await assert.rejects(
+    mod.installSelfHostBinaryFromBundle({
+      bundle,
+      binaryName,
+      config,
+      pubkeyFile,
+    }),
+    /node_modules sidecars/i
+  );
+});
+
+test('self-host release installer fails closed when packaged Prisma sidecar set is incomplete', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const cases = [
+    {
+      name: 'only packaged .prisma sidecar is present',
+      setup: async (rootDir) => {
+        await mkdir(join(rootDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+        await writeFile(join(rootDir, 'node_modules', '.prisma', 'client', 'query_engine.so'), 'engine', 'utf-8');
+      },
+    },
+    {
+      name: 'only packaged @prisma sidecar is present',
+      setup: async (rootDir) => {
+        await mkdir(join(rootDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+        await writeFile(join(rootDir, 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = {}\n', 'utf-8');
+      },
+    },
+  ];
+
+  for (const testCase of cases) {
+    await t.test(testCase.name, async () => {
+      const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-incomplete-prisma-sidecars-test-'));
+      t.after(async () => {
+        await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+      });
+
+      const staging = join(tmp, 'staging');
+      const rootName = 'happier-server-v1.2.3-preview.1-linux-x64';
+      const rootDir = join(staging, rootName);
+      await mkdir(join(rootDir, 'generated'), { recursive: true });
+      await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'ok', 'utf-8');
+      await testCase.setup(rootDir);
+
+      const binaryName = 'happier-server';
+      const binaryPath = join(rootDir, binaryName);
+      await writeFile(binaryPath, '#!/bin/sh\necho ok\n', 'utf-8');
+      spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+      const archiveName = `${rootName}.tar.gz`;
+      const archivePath = join(tmp, archiveName);
+      const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+      assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+      const archiveBytes = await readFile(archivePath);
+      const archiveSha = sha256Hex(archiveBytes);
+      const checksumsText = `${archiveSha} ${archiveName}\n`;
+      const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+      const sigFile = signMinisignMessage({
+        message: Buffer.from(checksumsText, 'utf-8'),
+        keyId,
+        privateKey,
+      });
+
+      const bundle = {
+        version: '1.2.3-preview.1',
+        archive: { name: archiveName, url: `data:application/octet-stream;base64,${archiveBytes.toString('base64')}` },
+        checksums: { name: `checksums-happier-server-v1.2.3-preview.1.txt`, url: `data:text/plain,${encodeURIComponent(checksumsText)}` },
+        checksumsSig: { name: `checksums-happier-server-v1.2.3-preview.1.txt.minisig`, url: `data:text/plain,${encodeURIComponent(sigFile)}` },
+      };
+
+      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`),
+      };
+
+      const mod = await import('./self_host_runtime.mjs');
+      await assert.rejects(
+        mod.installSelfHostBinaryFromBundle({
+          bundle,
+          binaryName,
+          config,
+          pubkeyFile,
+        }),
+        /node_modules sidecars/i
+      );
+    });
+  }
+});
+
+test('self-host release update preserves the last known-good runtime when bundle sidecars are missing', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-preserve-runtime-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  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');
+  spawnSync('bash', ['-lc', `chmod +x "${config.serverBinaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  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');
+  await mkdir(config.versionsDir, { recursive: true });
+  await writeFile(join(config.versionsDir, `${binaryName}-last-known-good`), 'old-version', 'utf-8');
+
+  const staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.4-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'new-generated', 'utf-8');
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho new-runtime\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const bundle = {
+    version: '1.2.4-preview.1',
+    archive: { name: archiveName, url: `data:application/octet-stream;base64,${archiveBytes.toString('base64')}` },
+    checksums: { name: `checksums-happier-server-v1.2.4-preview.1.txt`, url: `data:text/plain,${encodeURIComponent(checksumsText)}` },
+    checksumsSig: { name: `checksums-happier-server-v1.2.4-preview.1.txt.minisig`, url: `data:text/plain,${encodeURIComponent(sigFile)}` },
+  };
+
+  const mod = await import('./self_host_runtime.mjs');
+  await assert.rejects(
+    mod.installSelfHostBinaryFromBundle({
+      bundle,
+      binaryName,
+      config,
+      pubkeyFile,
+    }),
+    /node_modules sidecars/i
+  );
+
+  const installedBinary = spawnSync(config.serverBinaryPath, [], { encoding: 'utf-8' });
+  assert.equal(installedBinary.status, 0, installedBinary.stderr || installedBinary.stdout);
+  assert.equal(String(installedBinary.stdout ?? '').trim(), 'old-runtime');
+  assert.equal(await readFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'utf-8'), 'old-generated');
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'utf-8'),
+    'old-engine'
+  );
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'utf-8'),
+    'module.exports = { old: true };\n'
+  );
+  const versionEntries = spawnSync('bash', ['-lc', `ls -1 "${config.versionsDir.replaceAll('"', '\\"')}"`], { encoding: 'utf-8' });
+  assert.equal(versionEntries.status, 0, versionEntries.stderr || versionEntries.stdout);
+  assert.deepEqual(
+    String(versionEntries.stdout ?? '').split(/\r?\n/).filter(Boolean),
+    [`${binaryName}-last-known-good`]
+  );
+});
+
+test('self-host release update rolls back promoted sidecars when binary install fails', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-rollback-runtime-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  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');
+  spawnSync('bash', ['-lc', `chmod +x "${config.serverBinaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  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');
+
+  await mkdir(dirname(config.versionsDir), { recursive: true });
+  await writeFile(config.versionsDir, 'blocked by test', 'utf-8');
+
+  const staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.5-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'new-generated', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '.prisma', 'client', 'query_engine.so'), 'new-engine', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = { new: true };\n', 'utf-8');
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho new-runtime\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const bundle = {
+    version: '1.2.5-preview.1',
+    archive: { name: archiveName, url: `data:application/octet-stream;base64,${archiveBytes.toString('base64')}` },
+    checksums: { name: `checksums-happier-server-v1.2.5-preview.1.txt`, url: `data:text/plain,${encodeURIComponent(checksumsText)}` },
+    checksumsSig: { name: `checksums-happier-server-v1.2.5-preview.1.txt.minisig`, url: `data:text/plain,${encodeURIComponent(sigFile)}` },
+  };
+
+  const mod = await import('./self_host_runtime.mjs');
+  await assert.rejects(
+    mod.installSelfHostBinaryFromBundle({
+      bundle,
+      binaryName,
+      config,
+      pubkeyFile,
+    }),
+    /not a directory|eexist|enotdir/i
+  );
+
+  const installedBinary = spawnSync(config.serverBinaryPath, [], { encoding: 'utf-8' });
+  assert.equal(installedBinary.status, 0, installedBinary.stderr || installedBinary.stdout);
+  assert.equal(String(installedBinary.stdout ?? '').trim(), 'old-runtime');
+  assert.equal(await readFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'utf-8'), 'old-generated');
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'utf-8'),
+    'old-engine'
+  );
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'utf-8'),
+    'module.exports = { old: true };\n'
+  );
+});
+
+test('self-host release update fails closed if the process dies after sidecar promotion and before binary install', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-crash-window-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  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');
+  spawnSync('bash', ['-lc', `chmod +x "${config.serverBinaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  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 staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.6-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'new-generated', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '.prisma', 'client', 'query_engine.so'), 'new-engine', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = { new: true };\n', 'utf-8');
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho new-runtime\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const bundle = {
+    version: '1.2.6-preview.1',
+    archive: { name: archiveName, url: `data:application/octet-stream;base64,${archiveBytes.toString('base64')}` },
+    checksums: { name: `checksums-happier-server-v1.2.6-preview.1.txt`, url: `data:text/plain,${encodeURIComponent(checksumsText)}` },
+    checksumsSig: { name: `checksums-happier-server-v1.2.6-preview.1.txt.minisig`, url: `data:text/plain,${encodeURIComponent(sigFile)}` },
+  };
+
+  const runtimeModuleUrl = new URL('./self_host_runtime.mjs', import.meta.url).href;
+  const child = spawnSync(process.execPath, [
+    '--input-type=module',
+    '--eval',
+    [
+      `import { installSelfHostBinaryFromBundle } from ${JSON.stringify(runtimeModuleUrl)};`,
+      'const bundle = JSON.parse(process.env.HAPPIER_TEST_SELF_HOST_BUNDLE_JSON ?? "null");',
+      'const config = JSON.parse(process.env.HAPPIER_TEST_SELF_HOST_CONFIG_JSON ?? "null");',
+      'const pubkeyFile = process.env.HAPPIER_TEST_SELF_HOST_PUBKEY ?? "";',
+      'await installSelfHostBinaryFromBundle({',
+      '  bundle,',
+      '  binaryName: "happier-server",',
+      '  config,',
+      '  pubkeyFile,',
+      '  beforeBinaryInstall: async () => { process.exit(17); },',
+      '});',
+    ].join('\n'),
+  ], {
+    env: {
+      ...process.env,
+      HAPPIER_TEST_SELF_HOST_BUNDLE_JSON: JSON.stringify(bundle),
+      HAPPIER_TEST_SELF_HOST_CONFIG_JSON: JSON.stringify(config),
+      HAPPIER_TEST_SELF_HOST_PUBKEY: pubkeyFile,
+    },
+    encoding: 'utf-8',
+  });
+
+  assert.equal(child.status, 17, child.stderr || child.stdout);
+  assert.equal(existsSync(config.serverBinaryPath), false);
+  assert.equal(await readFile(join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt'), 'utf-8'), 'new-generated');
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '.prisma', 'client', 'query_engine.so'), 'utf-8'),
+    'new-engine'
+  );
+  assert.equal(
+    await readFile(join(dirname(config.serverBinaryPath), 'node_modules', '@prisma', 'client', 'index.js'), 'utf-8'),
+    'module.exports = { new: true };\n'
+  );
+  const previousBinary = spawnSync(config.serverPreviousBinaryPath, [], { encoding: 'utf-8' });
+  assert.equal(previousBinary.status, 0, previousBinary.stderr || previousBinary.stdout);
+  assert.equal(String(previousBinary.stdout ?? '').trim(), 'old-runtime');
+  assert.equal(existsSync(join(config.versionsDir, `${binaryName}-1.2.6-preview.1`)), false);
+});
+
+test('self-host release installer ignores extra root entries when extracting bundles', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('tar-based bundle test does not run on windows');
+    return;
+  }
+  if (spawnSync('bash', ['-lc', 'command -v tar >/dev/null 2>&1'], { stdio: 'ignore' }).status !== 0) {
+    t.skip('tar is required for bundle installation test');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-bundle-appledouble-test-'));
+  t.after(async () => {
+    await spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  const staging = join(tmp, 'staging');
+  const rootName = 'happier-server-v1.2.3-preview.1-linux-x64';
+  const rootDir = join(staging, rootName);
+  await mkdir(join(rootDir, 'generated'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(rootDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+  await writeFile(join(rootDir, 'generated', 'dummy.txt'), 'ok', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '.prisma', 'client', 'query_engine.so'), 'engine', 'utf-8');
+  await writeFile(join(rootDir, 'node_modules', '@prisma', 'client', 'index.js'), 'module.exports = {};\n', 'utf-8');
+
+  // Simulate archives that include extra top-level entries (e.g. AppleDouble `._*` files, stray metadata files).
+  await mkdir(staging, { recursive: true });
+  const extraRootEntry = '000-root-metadata';
+  await writeFile(join(staging, extraRootEntry), 'metadata', 'utf-8');
+
+  const binaryName = 'happier-server';
+  const binaryPath = join(rootDir, binaryName);
+  await writeFile(binaryPath, '#!/bin/sh\necho ok\n', 'utf-8');
+  spawnSync('bash', ['-lc', `chmod +x "${binaryPath.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+
+  const archiveName = `${rootName}.tar.gz`;
+  const archivePath = join(tmp, archiveName);
+  const tar = spawnSync('tar', ['-czf', archivePath, '-C', staging, extraRootEntry, rootName], { encoding: 'utf-8' });
+  assert.equal(tar.status, 0, tar.stderr || tar.stdout);
+
+  const archiveBytes = await (await import('node:fs/promises')).readFile(archivePath);
+  const archiveSha = sha256Hex(archiveBytes);
+  const checksumsText = `${archiveSha} ${archiveName}\n`;
+  const { pubkeyFile, keyId, privateKey } = createMinisignKeyPair();
+  const sigFile = signMinisignMessage({
+    message: Buffer.from(checksumsText, 'utf-8'),
+    keyId,
+    privateKey,
+  });
+
+  const archiveUrl = `data:application/octet-stream;base64,${archiveBytes.toString('base64')}`;
+  const checksumsUrl = `data:text/plain,${encodeURIComponent(checksumsText)}`;
+  const sigUrl = `data:text/plain,${encodeURIComponent(sigFile)}`;
+
+  const bundle = {
+    version: '1.2.3-preview.1',
+    archive: { name: archiveName, url: archiveUrl },
+    checksums: { name: `checksums-happier-server-v1.2.3-preview.1.txt`, url: checksumsUrl },
+    checksumsSig: { name: `checksums-happier-server-v1.2.3-preview.1.txt.minisig`, url: sigUrl },
+  };
+
+  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`),
+  };
+
+  const mod = await import('./self_host_runtime.mjs');
+  assert.equal(typeof mod.installSelfHostBinaryFromBundle, 'function');
+
+  await mod.installSelfHostBinaryFromBundle({
+    bundle,
+    binaryName,
+    config,
+    pubkeyFile,
+  });
+
+  const installedDummy = join(dirname(config.serverBinaryPath), 'generated', 'dummy.txt');
+  const raw = spawnSync('bash', ['-lc', `test -f "${installedDummy.replaceAll('"', '\\"')}" && cat "${installedDummy.replaceAll('"', '\\"')}"`], {
+    encoding: 'utf-8',
+  });
+  assert.equal(raw.status, 0, raw.stderr || raw.stdout);
+  assert.equal(String(raw.stdout ?? '').trim(), 'ok');
+});
+
+test('installSelfHostBinaryFromLocalPath prunes older retained local versions after promotion', async (t) => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-local-retention-test-'));
+  const previousDateNow = Date.now;
+  t.after(async () => {
+    Date.now = previousDateNow;
+    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(config.versionsDir, { recursive: true });
+  await writeFile(join(config.versionsDir, `${binaryName}-local-500`), '#!/bin/sh\necho old\n', 'utf-8');
+
+  Date.now = () => 1_000;
+  const sourceOne = await createLocalSelfHostRuntimePayloadRoot({
+    rootDir: join(tmp, 'payload-1'),
+    binaryName,
+    binaryText: '#!/bin/sh\necho local-one\n',
+  });
+  await installSelfHostBinaryFromLocalPath({
+    sourceBinaryPath: sourceOne,
+    binaryName,
+    config,
+  });
+
+  Date.now = () => 2_000;
+  const sourceTwo = await createLocalSelfHostRuntimePayloadRoot({
+    rootDir: join(tmp, 'payload-2'),
+    binaryName,
+    binaryText: '#!/bin/sh\necho local-two\n',
+  });
+  await installSelfHostBinaryFromLocalPath({
+    sourceBinaryPath: sourceTwo,
+    binaryName,
+    config,
+  });
+
+  assert.equal(existsSync(join(config.versionsDir, `${binaryName}-local-500`)), false);
+  assert.equal(existsSync(join(config.versionsDir, `${binaryName}-local-1000`)), true);
+  assert.equal(existsSync(join(config.versionsDir, `${binaryName}-local-2000`)), true);
+});
+
+test('installBinaryAtomically swaps a running binary on Linux without ETXTBSY', async (t) => {
+  if (process.platform !== 'linux') {
+    t.skip('ETXTBSY behavior is Linux-specific');
+    return;
+  }
+
+  const sleepPath = '/bin/sleep';
+  const truePath = '/bin/true';
+  if (spawnSync('bash', ['-lc', `test -x "${sleepPath}" && test -x "${truePath}"`], { stdio: 'ignore' }).status !== 0) {
+    t.skip('requires /bin/sleep and /bin/true');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happier-self-host-etxtbsy-'));
+  t.after(() => {
+    spawnSync('bash', ['-lc', `rm -rf "${tmp.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
+  });
+
+  const targetBinaryPath = join(tmp, 'bin', 'happier-server');
+  const previousBinaryPath = join(tmp, 'bin', 'happier-server.previous');
+  const versioned1 = join(tmp, 'versions', 'happier-server-1');
+  const versioned2 = join(tmp, 'versions', 'happier-server-2');
+
+  await installBinaryAtomically({
+    sourceBinaryPath: sleepPath,
+    targetBinaryPath,
+    previousBinaryPath,
+    versionedTargetPath: versioned1,
+  });
+
+  const child = spawn(targetBinaryPath, ['30'], { stdio: 'ignore' });
+  t.after(() => {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      // ignore
+    }
+  });
+
+  // Wait briefly for the process to enter the running state.
+  await new Promise((r) => setTimeout(r, 200));
+
+  await installBinaryAtomically({
+    sourceBinaryPath: truePath,
+    targetBinaryPath,
+    previousBinaryPath,
+    versionedTargetPath: versioned2,
+  });
+
+  const ran = spawnSync(targetBinaryPath, [], { encoding: 'utf-8' });
+  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');
+
+  assert.equal(
+    mod.resolveSelfHostEffectiveServerPort({
+      config: { serverPort: 3005 },
+      env: { PORT: '3999' },
+    }),
+    3999,
+  );
+});
+
 test('pickReleaseAsset rejects releases missing minisign signature assets', () => {
   assert.throws(() => {
     pickReleaseAsset({
@@ -48,7 +920,37 @@ test('pickReleaseAsset rejects releases missing minisign signature assets', () =
       os: 'linux',
       arch: 'x64',
     });
-  }, /signature/i);
+  }, /minisig|signature/i);
+});
+
+test('pickReleaseAsset supports windows zip artifacts', () => {
+  const assets = [
+    { name: 'happier-server-v1.2.3-windows-x64.zip', browser_download_url: 'https://example.test/server.zip' },
+    { name: 'checksums-happier-server-v1.2.3.txt', browser_download_url: 'https://example.test/checksums.txt' },
+    { name: 'checksums-happier-server-v1.2.3.txt.minisig', browser_download_url: 'https://example.test/checksums.txt.minisig' },
+  ];
+  const picked = pickReleaseAsset({
+    assets,
+    product: 'happier-server',
+    os: 'windows',
+    arch: 'x64',
+  });
+  assert.equal(picked.archiveUrl, 'https://example.test/server.zip');
+});
+
+test('pickReleaseAsset supports windows tar.gz artifacts', () => {
+  const assets = [
+    { name: 'happier-server-v1.2.3-windows-x64.tar.gz', browser_download_url: 'https://example.test/server.tgz' },
+    { name: 'checksums-happier-server-v1.2.3.txt', browser_download_url: 'https://example.test/checksums.txt' },
+    { name: 'checksums-happier-server-v1.2.3.txt.minisig', browser_download_url: 'https://example.test/checksums.txt.minisig' },
+  ];
+  const picked = pickReleaseAsset({
+    assets,
+    product: 'happier-server',
+    os: 'windows',
+    arch: 'x64',
+  });
+  assert.equal(picked.archiveUrl, 'https://example.test/server.tgz');
 });
 
 test('renderServerServiceUnit references configured binary and env file', () => {
@@ -65,6 +967,28 @@ test('renderServerServiceUnit references configured binary and env file', () =>
   assert.match(unit, /StandardOutput=append:\/var\/log\/happier\/server.log/);
 });
 
+test('resolveSelfHostDefaults uses user-mode paths by default', () => {
+  const cfg = resolveSelfHostDefaults({ platform: 'linux', mode: 'user', homeDir: '/home/me' });
+  assert.equal(cfg.installRoot, '/home/me/.happier/self-host');
+  assert.equal(cfg.binDir, '/home/me/.happier/bin');
+  assert.equal(cfg.configDir, '/home/me/.happier/self-host/config');
+});
+
+test('resolveSelfHostDefaults isolates publicdev into a side-by-side self-host root and service name', () => {
+  const cfg = resolveSelfHostDefaults({ platform: 'linux', mode: 'user', channel: 'publicdev', homeDir: '/home/me' });
+  assert.equal(cfg.installRoot, '/home/me/.happier/self-host-dev');
+  assert.equal(cfg.configDir, '/home/me/.happier/self-host-dev/config');
+  assert.equal(cfg.dataDir, '/home/me/.happier/self-host-dev/data');
+  assert.equal(cfg.logDir, '/home/me/.happier/self-host-dev/logs');
+  assert.equal(cfg.serviceName, 'happier-server-dev');
+});
+
+test('resolveMinisignPublicKeyText prefers inline override and otherwise returns bundled key', () => {
+  const bundled = resolveMinisignPublicKeyText({});
+  assert.match(bundled, /minisign public key/i);
+  assert.equal(resolveMinisignPublicKeyText({ HAPPIER_MINISIGN_PUBKEY: 'hello' }), 'hello');
+});
+
 test('renderServerEnvFile emits sqlite/local defaults for self-host mode', () => {
   const envText = renderServerEnvFile({
     port: 3005,
@@ -74,9 +998,410 @@ test('renderServerEnvFile emits sqlite/local defaults for self-host mode', () =>
     dbDir: '/var/lib/happier/pglite',
   });
   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, /HAPPIER_FILES_BACKEND=local/);
+  assert.match(envText, /HAPPIER_SQLITE_AUTO_MIGRATE=1/);
+  assert.match(envText, /HAPPIER_SQLITE_MIGRATIONS_DIR=\/var\/lib\/happier\/migrations\/sqlite/);
   assert.match(envText, /HAPPIER_SERVER_LIGHT_DATA_DIR=\/var\/lib\/happier/);
   assert.match(envText, /HAPPIER_SERVER_LIGHT_FILES_DIR=\/var\/lib\/happier\/files/);
   assert.match(envText, /HAPPIER_SERVER_LIGHT_DB_DIR=\/var\/lib\/happier\/pglite/);
 });
+
+test('renderServerEnvFile includes ui bundle directory when provided', () => {
+  const envText = renderServerEnvFile({
+    port: 3005,
+    host: '127.0.0.1',
+    dataDir: '/var/lib/happier',
+    filesDir: '/var/lib/happier/files',
+    dbDir: '/var/lib/happier/pglite',
+    uiDir: '/var/lib/happier/ui-web/current',
+  });
+  assert.match(envText, /HAPPIER_SERVER_UI_DIR=\/var\/lib\/happier\/ui-web\/current/);
+});
+
+test('renderServerEnvFile includes PRISMA_QUERY_ENGINE_LIBRARY when a packaged sqlite engine is present', async () => {
+  const serverBinDir = await mkdtemp(join(tmpdir(), 'happier-self-host-bin-'));
+  await mkdir(join(serverBinDir, 'generated', 'sqlite-client'), { recursive: true });
+  const enginePath = join(serverBinDir, 'generated', 'sqlite-client', 'libquery_engine-darwin-arm64.dylib.node');
+  await writeFile(enginePath, 'stub', 'utf-8');
+
+  const envText = renderServerEnvFile({
+    port: 3005,
+    host: '127.0.0.1',
+    platform: 'darwin',
+    arch: 'arm64',
+    serverBinDir,
+    dataDir: '/var/lib/happier',
+    filesDir: '/var/lib/happier/files',
+    dbDir: '/var/lib/happier/pglite',
+  });
+  assert.match(envText, /PRISMA_CLIENT_ENGINE_TYPE=library/);
+  assert.match(envText, new RegExp(`PRISMA_QUERY_ENGINE_LIBRARY=${enginePath.replaceAll('\\\\', '\\\\\\\\')}`));
+});
+
+test('renderServerEnvFile includes PRISMA_QUERY_ENGINE_LIBRARY for packaged postgres prisma engine on linux arm64', async () => {
+  const serverBinDir = await mkdtemp(join(tmpdir(), 'happier-self-host-bin-postgres-'));
+  await mkdir(join(serverBinDir, 'node_modules', '.prisma', 'client'), { recursive: true });
+  await mkdir(join(serverBinDir, 'node_modules', '@prisma', 'client'), { recursive: true });
+  const enginePath = join(serverBinDir, 'node_modules', '.prisma', 'client', 'libquery_engine-linux-arm64-openssl-3.0.x.so.node');
+  await writeFile(enginePath, 'stub', 'utf-8');
+
+  const envText = renderServerEnvFile({
+    port: 3005,
+    host: '127.0.0.1',
+    platform: 'linux',
+    arch: 'arm64',
+    serverBinDir,
+    dataDir: '/var/lib/happier',
+    filesDir: '/var/lib/happier/files',
+    dbDir: '/var/lib/happier/pglite',
+  });
+  assert.match(envText, /PRISMA_CLIENT_ENGINE_TYPE=library/);
+  assert.match(envText, new RegExp(`PRISMA_QUERY_ENGINE_LIBRARY=${enginePath.replaceAll('\\\\', '\\\\\\\\')}`));
+  assert.match(envText, new RegExp(`NODE_PATH=${join(serverBinDir, 'node_modules').replaceAll('\\\\', '\\\\\\\\')}`));
+});
+
+test('renderServerEnvFile uses file 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',
+  });
+  assert.match(envText, /DATABASE_URL=file:\/\/\/C:\/Users\/me\/\.happier\/self-host\/data\/happier-server-light\.sqlite/);
+});
+
+test('resolveSelfHostHealthTimeoutMs defaults to a safe health timeout', () => {
+  assert.equal(resolveSelfHostHealthTimeoutMs({}), 90_000);
+});
+
+test('resolveSelfHostHealthTimeoutMs honors explicit timeout values >= 10s', () => {
+  assert.equal(resolveSelfHostHealthTimeoutMs({ HAPPIER_SELF_HOST_HEALTH_TIMEOUT_MS: '120000' }), 120_000);
+});
+
+test('resolveSelfHostHealthTimeoutMs ignores invalid or too-small values', () => {
+  assert.equal(resolveSelfHostHealthTimeoutMs({ HAPPIER_SELF_HOST_HEALTH_TIMEOUT_MS: 'abc' }), 90_000);
+  assert.equal(resolveSelfHostHealthTimeoutMs({ HAPPIER_SELF_HOST_HEALTH_TIMEOUT_MS: '5000' }), 90_000);
+});
+
+test('resolveSelfHostAutoUpdateDefault is opt-in (disabled by default)', () => {
+  assert.equal(resolveSelfHostAutoUpdateDefault({}), false);
+  assert.equal(resolveSelfHostAutoUpdateDefault({ HAPPIER_SELF_HOST_AUTO_UPDATE: '1' }), true);
+});
+
+test('resolveSelfHostAutoUpdateIntervalMinutes provides a safe default and bounds invalid values', () => {
+  assert.equal(resolveSelfHostAutoUpdateIntervalMinutes({}), 1440);
+  assert.equal(resolveSelfHostAutoUpdateIntervalMinutes({ HAPPIER_SELF_HOST_AUTO_UPDATE_INTERVAL_MINUTES: '60' }), 60);
+  assert.equal(resolveSelfHostAutoUpdateIntervalMinutes({ HAPPIER_SELF_HOST_AUTO_UPDATE_INTERVAL_MINUTES: '0' }), 1440);
+  assert.equal(resolveSelfHostAutoUpdateIntervalMinutes({ HAPPIER_SELF_HOST_AUTO_UPDATE_INTERVAL_MINUTES: 'abc' }), 1440);
+});
+
+test('renderUpdaterSystemdUnit runs self-host update without restart loops', () => {
+  const unit = renderUpdaterSystemdUnit({
+    updaterLabel: 'happier-server-updater',
+    hstackPath: '/home/me/.happier/bin/hstack',
+    channel: 'publicdev',
+    mode: 'user',
+    workingDirectory: '/home/me/.happier/self-host',
+    stdoutPath: '/home/me/.happier/self-host/logs/updater.out.log',
+    stderrPath: '/home/me/.happier/self-host/logs/updater.err.log',
+    wantedBy: 'default.target',
+  });
+  assert.match(unit, /ExecStart=\/home\/me\/\.happier\/bin\/hstack self-host update --channel=dev --mode=user --non-interactive/);
+  assert.match(unit, /Restart=no/);
+  assert.match(unit, /WantedBy=default\.target/);
+});
+
+test('renderUpdaterLaunchdPlistXml runs self-host update without keepalive loops', () => {
+  const plist = renderUpdaterLaunchdPlistXml({
+    updaterLabel: 'happier-server-updater',
+    hstackPath: '/Users/me/.happier/bin/hstack',
+    channel: 'preview',
+    mode: 'user',
+    intervalMinutes: 60,
+    workingDirectory: '/Users/me/.happier/self-host',
+    stdoutPath: '/Users/me/.happier/self-host/logs/updater.out.log',
+    stderrPath: '/Users/me/.happier/self-host/logs/updater.err.log',
+  });
+
+  assert.match(plist, /<key>RunAtLoad<\/key>\s*<true\/>/);
+  assert.match(plist, /<key>StartInterval<\/key>\s*<integer>3600<\/integer>/);
+  assert.doesNotMatch(plist, /<key>StartCalendarInterval<\/key>/);
+  assert.doesNotMatch(plist, /<key>KeepAlive<\/key>/);
+  assert.match(plist, /<key>PATH<\/key>/);
+  assert.match(plist, /<string>\/Users\/me\/\.happier\/bin\/hstack<\/string>/);
+  assert.match(plist, /<string>self-host<\/string>/);
+  assert.match(plist, /<string>update<\/string>/);
+  assert.match(plist, /<string>--channel=preview<\/string>/);
+  assert.match(plist, /<string>--mode=user<\/string>/);
+  assert.match(plist, /<string>--non-interactive<\/string>/);
+});
+
+test('renderUpdaterLaunchdPlistXml supports daily time-of-day schedules', () => {
+  const plist = renderUpdaterLaunchdPlistXml({
+    updaterLabel: 'happier-server-updater',
+    hstackPath: '/Users/me/.happier/bin/hstack',
+    channel: 'stable',
+    mode: 'user',
+    at: '03:15',
+    workingDirectory: '/Users/me/.happier/self-host',
+    stdoutPath: '/Users/me/.happier/self-host/logs/updater.out.log',
+    stderrPath: '/Users/me/.happier/self-host/logs/updater.err.log',
+  });
+  assert.match(plist, /<key>StartCalendarInterval<\/key>/);
+  assert.match(plist, /<key>Hour<\/key>\s*<integer>3<\/integer>/);
+  assert.match(plist, /<key>Minute<\/key>\s*<integer>15<\/integer>/);
+  assert.doesNotMatch(plist, /<key>StartInterval<\/key>/);
+});
+
+test('renderUpdaterSystemdTimerUnit schedules periodic updater runs', () => {
+  const timer = renderUpdaterSystemdTimerUnit({
+    updaterLabel: 'happier-server-updater',
+    intervalMinutes: 60,
+  });
+  assert.match(timer, /OnUnitActiveSec=60m/);
+  assert.doesNotMatch(timer, /OnCalendar=/);
+  assert.match(timer, /Unit=happier-server-updater\.service/);
+  assert.match(timer, /WantedBy=timers\.target/);
+});
+
+test('renderUpdaterSystemdTimerUnit supports daily time-of-day schedules', () => {
+  const timer = renderUpdaterSystemdTimerUnit({
+    updaterLabel: 'happier-server-updater',
+    at: '03:15',
+  });
+  assert.match(timer, /OnCalendar=\*-\*-\*\s+03:15:00/);
+  assert.doesNotMatch(timer, /OnUnitActiveSec=/);
+  assert.match(timer, /Unit=happier-server-updater\.service/);
+});
+
+test('renderUpdaterScheduledTaskWrapperPs1 runs self-host update without node dependencies', () => {
+  const wrapper = renderUpdaterScheduledTaskWrapperPs1({
+    updaterLabel: 'happier-server-updater',
+    hstackPath: 'C:\\\\Users\\\\me\\\\.happier\\\\bin\\\\hstack.exe',
+    channel: 'publicdev',
+    mode: 'user',
+    workingDirectory: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host',
+    stdoutPath: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\logs\\\\updater.out.log',
+    stderrPath: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\logs\\\\updater.err.log',
+  });
+
+  assert.match(
+    wrapper,
+    /hstack\.exe"\s+"self-host"\s+"update"\s+"--channel=dev"\s+"--mode=user"\s+"--non-interactive"/i
+  );
+});
+
+test('renderSelfHostStatusText reports dev as the public channel label for the publicdev ring', () => {
+  const text = renderSelfHostStatusText(
+    {
+      channel: 'publicdev',
+      mode: 'user',
+      serviceName: 'happier-server-dev',
+      serverUrl: 'http://127.0.0.1:3005',
+      healthy: true,
+      service: { active: true, enabled: true },
+      versions: { server: '1.2.3-dev.1', uiWeb: '9.9.9-dev.2' },
+      autoUpdate: {
+        label: 'happier-server-dev-updater',
+        job: { active: true, enabled: true },
+        configured: { enabled: true, intervalMinutes: 60 },
+      },
+      updatedAt: '2026-02-15T00:00:00.000Z',
+    },
+    { colors: false },
+  );
+
+  assert.match(text, /channel:\s*dev/);
+  assert.match(text, /service:\s*happier-server-dev/);
+});
+
+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', () => {
+  const args = buildUpdaterScheduledTaskCreateArgs({
+    backend: 'schtasks-user',
+    taskName: 'Happier\\\\happier-server-updater',
+    definitionPath: 'C:\\\\Users\\\\me\\\\.happier\\\\self-host\\\\services\\\\happier-server-updater.ps1',
+    at: '03:15',
+  });
+  assert.ok(args.includes('DAILY'));
+  assert.ok(args.includes('03:15'));
+  assert.equal(args.includes('MINUTE'), false);
+});
+
+test('mergeEnvTextWithDefaults preserves overrides while backfilling new default keys', () => {
+  const defaults = renderServerEnvFile({
+    port: 3005,
+    host: '127.0.0.1',
+    dataDir: '/var/lib/happier',
+    filesDir: '/var/lib/happier/files',
+    dbDir: '/var/lib/happier/pglite',
+  });
+  const existing = [
+    ...defaults
+      .split('\n')
+      .filter((line) => !line.startsWith('HAPPIER_SQLITE_AUTO_MIGRATE=') && !line.startsWith('HAPPIER_SQLITE_MIGRATIONS_DIR=')),
+    'PORT=7777',
+    'FOO=bar',
+    '',
+  ].join('\n');
+
+  const merged = mergeEnvTextWithDefaults(existing, defaults);
+  assert.match(merged, /PORT=7777/);
+  assert.match(merged, /HAPPIER_SQLITE_AUTO_MIGRATE=1/);
+  assert.match(merged, /HAPPIER_SQLITE_MIGRATIONS_DIR=\/var\/lib\/happier\/migrations\/sqlite/);
+  assert.match(merged, /FOO=bar/);
+});
+
+test('renderSelfHostStatusText reports versions, health, and auto-update config separately from job state', () => {
+  const text = renderSelfHostStatusText(
+    {
+      channel: 'preview',
+      mode: 'user',
+      serviceName: 'happier-server',
+      serverUrl: 'http://127.0.0.1:3005',
+      healthy: true,
+      service: { active: true, enabled: true },
+      versions: { server: '1.2.3-preview.1', uiWeb: '9.9.9-preview.2' },
+      autoUpdate: {
+        label: 'happier-server-updater',
+        job: { active: true, enabled: true },
+        configured: { enabled: true, intervalMinutes: 60 },
+      },
+      updatedAt: '2026-02-15T00:00:00.000Z',
+    },
+    { colors: false },
+  );
+
+  assert.match(text, /channel:\s*preview/);
+  assert.match(text, /mode:\s*user/);
+  assert.match(text, /url:\s*http:\/\/127\.0\.0\.1:3005/);
+  assert.match(text, /health:\s*ok/);
+  assert.match(text, /server:\s*1\.2\.3-preview\.1/);
+  assert.match(text, /ui-web:\s*9\.9\.9-preview\.2/);
+  assert.match(text, /auto-update:\s*configured enabled \(every 60m\); job enabled, active/);
+  assert.match(text, /updated:\s*2026-02-15T00:00:00\.000Z/);
+});
+
+test('renderSelfHostStatusText shows disabled auto-update config even if job state is unknown', () => {
+  const text = renderSelfHostStatusText(
+    {
+      channel: 'stable',
+      mode: 'user',
+      serviceName: 'happier-server',
+      serverUrl: 'http://127.0.0.1:3005',
+      healthy: false,
+      service: { active: null, enabled: null },
+      versions: { server: null, uiWeb: null },
+      autoUpdate: {
+        label: 'happier-server-updater',
+        job: { active: null, enabled: null },
+        configured: { enabled: false, intervalMinutes: 1440 },
+      },
+      updatedAt: null,
+    },
+    { colors: false },
+  );
+
+  assert.match(text, /auto-update:\s*configured disabled; job unknown/);
+  assert.match(text, /health:\s*failed/);
+});
+
+test('buildSelfHostDoctorChecks does not require external minisign and includes ui-web checks when installed', () => {
+  const checks = buildSelfHostDoctorChecks(
+    {
+      platform: 'linux',
+      mode: 'user',
+      serverBinaryPath: '/home/me/.happier/self-host/bin/happier-server',
+      configEnvPath: '/home/me/.happier/self-host/config/server.env',
+      uiWebCurrentDir: '/home/me/.happier/self-host/ui-web/current',
+    },
+    {
+      state: { uiWeb: { installed: true } },
+      commandExists: (name) => new Set(['tar', 'systemctl']).has(name),
+      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);
+});
+
+test('buildSelfHostDoctorChecks flags missing ui-web bundle when state expects ui-web installed', () => {
+  const checks = buildSelfHostDoctorChecks(
+    {
+      platform: 'linux',
+      mode: 'user',
+      serverBinaryPath: '/home/me/.happier/self-host/bin/happier-server',
+      configEnvPath: '/home/me/.happier/self-host/config/server.env',
+      uiWebCurrentDir: '/home/me/.happier/self-host/ui-web/current',
+    },
+    {
+      state: { uiWeb: { installed: true } },
+      commandExists: () => true,
+      pathExists: (p) => !p.endsWith('index.html'),
+    },
+  );
+
+  assert.equal(checks.find((c) => c.name === 'ui-web')?.ok, false);
+});
+
+test('normalizeSelfHostAutoUpdateState upgrades legacy boolean config to structured config', () => {
+  assert.deepEqual(
+    normalizeSelfHostAutoUpdateState({ autoUpdate: true }, { fallbackIntervalMinutes: 1440 }),
+    { enabled: true, intervalMinutes: 1440, at: '' },
+  );
+  assert.deepEqual(
+    normalizeSelfHostAutoUpdateState({ autoUpdate: false }, { fallbackIntervalMinutes: 1440 }),
+    { enabled: false, intervalMinutes: 1440, at: '' },
+  );
+});
+
+test('normalizeSelfHostAutoUpdateState preserves explicit interval and bounds invalid values', () => {
+  assert.deepEqual(
+    normalizeSelfHostAutoUpdateState({ autoUpdate: { enabled: true, intervalMinutes: 60 } }, { fallbackIntervalMinutes: 1440 }),
+    { enabled: true, intervalMinutes: 60, at: '' },
+  );
+  assert.deepEqual(
+    normalizeSelfHostAutoUpdateState({ autoUpdate: { enabled: true, intervalMinutes: 0 } }, { fallbackIntervalMinutes: 1440 }),
+    { enabled: true, intervalMinutes: 1440, at: '' },
+  );
+  assert.deepEqual(
+    normalizeSelfHostAutoUpdateState({}, { fallbackIntervalMinutes: 1440 }),
+    { enabled: false, intervalMinutes: 1440, at: '' },
+  );
+});
+
+test('decideSelfHostAutoUpdateReconcile maps configured state to an install/uninstall action', () => {
+  assert.deepEqual(
+    decideSelfHostAutoUpdateReconcile({ autoUpdate: true }, { fallbackIntervalMinutes: 1440 }),
+    { action: 'install', enabled: true, intervalMinutes: 1440, at: '' },
+  );
+  assert.deepEqual(
+    decideSelfHostAutoUpdateReconcile({ autoUpdate: false }, { fallbackIntervalMinutes: 1440 }),
+    { action: 'uninstall', enabled: false, intervalMinutes: 1440, at: '' },
+  );
+  assert.deepEqual(
+    decideSelfHostAutoUpdateReconcile({}, { fallbackIntervalMinutes: 1440 }),
+    { action: 'uninstall', enabled: false, intervalMinutes: 1440, at: '' },
+  );
+});