@happier-dev/relay-server 0.1.2-preview.10.1 → 0.1.2-preview.138.1

package/bin/happier-server.mjs

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, stat } from 'node:fs/promises';
 import { homedir, platform, arch, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 
-import { resolveServerReleaseAssets } from '../src/releaseAssets.mjs';
-import { lookupSha256 } from '../src/checksums.mjs';
-import { verifyMinisign } from '../src/minisign.mjs';
+import { resolveServerReleaseAssets, resolveUiWebReleaseAssets } from '../src/releaseAssets.mjs';
+import { resolveRunnerCacheRoot, resolveServerRunnerTarget } from '../src/target.mjs';
+import { parseRunnerInvocation } from '../src/runnerConfig.mjs';
+import { downloadVerifiedReleaseAssetBundle } from '@happier-dev/release-runtime/verifiedDownload';
+import { planArchiveExtraction } from '@happier-dev/release-runtime/extractPlan';
+import { fetchGitHubReleaseByTag } from '@happier-dev/release-runtime/github';
 
 const OWNER = 'happier-dev';
 const REPO = 'happier';
@@ -17,76 +19,16 @@ function fail(msg) {
   process.exit(1);
 }
 
-function parseArgs(argv) {
-  const kv = new Map();
-  const positionals = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a === '--') {
-      positionals.push(...argv.slice(i + 1));
-      break;
-    }
-    if (!a.startsWith('--')) {
-      positionals.push(a);
-      continue;
-    }
-    const v = argv[i + 1];
-    if (v && !v.startsWith('--')) {
-      kv.set(a, v);
-      i += 1;
-    } else {
-      kv.set(a, 'true');
-    }
-  }
-  return { kv, positionals };
-}
-
 function resolveTarget() {
-  const os = platform();
-  const cpu = arch();
-  // Server binaries are currently built for Linux only in CI.
-  if (os !== 'linux') {
-    fail(`Unsupported platform '${os}'. Server runner currently supports linux only.`);
-  }
-  if (cpu !== 'x64' && cpu !== 'arm64') {
-    fail(`Unsupported architecture '${cpu}'. Expected x64 or arm64.`);
+  try {
+    return resolveServerRunnerTarget({ platform: platform(), arch: arch() });
+  } catch (e) {
+    fail(e instanceof Error ? e.message : String(e));
   }
-  return { os, arch: cpu };
 }
 
 function cacheRoot() {
-  const xdg = String(process.env.XDG_CACHE_HOME ?? '').trim();
-  if (xdg) return xdg;
-  return join(homedir(), '.cache');
-}
-
-async function fetchJson(url) {
-  const res = await fetch(url, {
-    headers: {
-      'user-agent': 'happier-server-runner',
-      accept: 'application/vnd.github+json',
-    },
-  });
-  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-  return res.json();
-}
-
-async function fetchText(url) {
-  const res = await fetch(url, { headers: { 'user-agent': 'happier-server-runner' } });
-  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-  return res.text();
-}
-
-async function downloadFile(url, destPath) {
-  const res = await fetch(url, { headers: { 'user-agent': 'happier-server-runner' } });
-  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-  const ab = await res.arrayBuffer();
-  await writeFile(destPath, Buffer.from(ab));
-}
-
-async function sha256File(path) {
-  const bytes = await readFile(path);
-  return createHash('sha256').update(bytes).digest('hex');
+  return resolveRunnerCacheRoot({ platform: platform(), homedir: homedir(), env: process.env });
 }
 
 async function pathExists(p) {
@@ -99,17 +41,18 @@ async function pathExists(p) {
 }
 
 async function main() {
-  const { kv, positionals } = parseArgs(process.argv.slice(2));
-  const channel = String(kv.get('--channel') ?? '').trim() || 'stable';
-  if (channel !== 'stable' && channel !== 'preview') {
-    fail(`Invalid --channel '${channel}'. Expected stable|preview.`);
-  }
-  const tag = String(kv.get('--tag') ?? '').trim() || (channel === 'preview' ? 'server-preview' : 'server-stable');
+  const parsed = parseRunnerInvocation(process.argv.slice(2));
+  const { serverTag: tag, uiWebTag, withUiWeb, positionals } = parsed;
 
   const target = resolveTarget();
+  const githubRepo = `${OWNER}/${REPO}`;
 
-  const releaseUrl = `https://api.github.com/repos/${OWNER}/${REPO}/releases/tags/${encodeURIComponent(tag)}`;
-  const release = await fetchJson(releaseUrl);
+  const release = await fetchGitHubReleaseByTag({
+    githubRepo,
+    tag,
+    userAgent: 'happier-server-runner',
+    githubToken: String(process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? ''),
+  });
   const assets = resolveServerReleaseAssets({ release, os: target.os, arch: target.arch });
 
   const pubkeyPath = new URL('../assets/happier-release.pub', import.meta.url);
@@ -118,37 +61,37 @@ async function main() {
   const tmp = join(tmpdir(), `happier-server-${process.pid}-${Date.now()}`);
   await mkdir(tmp, { recursive: true });
   try {
-    const checksumsPath = join(tmp, assets.checksums.name);
-    const checksumsSigPath = join(tmp, assets.checksumsSig.name);
-    await downloadFile(assets.checksums.url, checksumsPath);
-    await downloadFile(assets.checksumsSig.url, checksumsSigPath);
-
-    const checksumsText = await readFile(checksumsPath, 'utf-8');
-    const sigFile = await readFile(checksumsSigPath, 'utf-8');
-    const ok = verifyMinisign({ message: Buffer.from(checksumsText, 'utf-8'), pubkeyFile, sigFile });
-    if (!ok) fail('Signature verification failed for checksums file.');
-
-    const expected = lookupSha256({ checksumsText, filename: assets.tarball.name });
-
     const cacheDir = join(cacheRoot(), 'happier', 'server', tag, assets.version, `${target.os}-${target.arch}`);
     await mkdir(cacheDir, { recursive: true });
     const artifactStem = `happier-server-v${assets.version}-${target.os}-${target.arch}`;
     const serverDir = join(cacheDir, artifactStem);
-    const serverBin = join(serverDir, 'happier-server');
+    const serverBin = join(serverDir, target.exeName);
 
     if (!(await pathExists(serverBin))) {
-      const tarballPath = join(tmp, assets.tarball.name);
-      await downloadFile(assets.tarball.url, tarballPath);
-      const actual = await sha256File(tarballPath);
-      if (actual !== expected) {
-        fail(`SHA256 mismatch for ${assets.tarball.name}: expected ${expected}, got ${actual}`);
-      }
+      const downloaded = await downloadVerifiedReleaseAssetBundle({
+        bundle: {
+          version: assets.version,
+          archive: assets.tarball,
+          checksums: assets.checksums,
+          checksumsSig: assets.checksumsSig,
+        },
+        destDir: tmp,
+        pubkeyFile,
+        userAgent: 'happier-server-runner',
+      });
+
+      const plan = planArchiveExtraction({
+        archiveName: downloaded.archiveName,
+        archivePath: downloaded.archivePath,
+        destDir: cacheDir,
+        os: target.os,
+      });
 
       // Extract archive into cache (archive root contains the artifactStem folder).
-      const extract = spawn('tar', ['-xzf', tarballPath, '-C', cacheDir], { stdio: 'inherit' });
+      const extract = spawn(plan.command.cmd, plan.command.args, { stdio: 'inherit' });
       await new Promise((resolve, reject) => {
         extract.on('error', reject);
-        extract.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`tar exited with ${code}`))));
+        extract.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${plan.command.cmd} exited with ${code}`))));
       });
     }
 
@@ -156,7 +99,56 @@ async function main() {
       fail(`Extracted server binary not found at ${serverBin}`);
     }
 
-    const child = spawn(serverBin, positionals, { stdio: 'inherit' });
+    const childEnv = { ...process.env };
+    if (withUiWeb && !String(process.env.HAPPIER_SERVER_UI_DIR ?? '').trim()) {
+      const uiRelease = await fetchGitHubReleaseByTag({
+        githubRepo,
+        tag: uiWebTag,
+        userAgent: 'happier-server-runner',
+        githubToken: String(process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? ''),
+      });
+      const uiAssets = resolveUiWebReleaseAssets({ release: uiRelease });
+      const uiCacheDir = join(cacheRoot(), 'happier', 'ui-web', uiWebTag, uiAssets.version, 'web-any');
+      await mkdir(uiCacheDir, { recursive: true });
+      const uiStem = `happier-ui-web-v${uiAssets.version}-web-any`;
+      const uiDir = join(uiCacheDir, uiStem);
+      const uiIndex = join(uiDir, 'index.html');
+
+      if (!(await pathExists(uiIndex))) {
+        const uiDownloaded = await downloadVerifiedReleaseAssetBundle({
+          bundle: {
+            version: uiAssets.version,
+            archive: uiAssets.tarball,
+            checksums: uiAssets.checksums,
+            checksumsSig: uiAssets.checksumsSig,
+          },
+          destDir: tmp,
+          pubkeyFile,
+          userAgent: 'happier-server-runner',
+        });
+
+        const uiPlan = planArchiveExtraction({
+          archiveName: uiDownloaded.archiveName,
+          archivePath: uiDownloaded.archivePath,
+          destDir: uiCacheDir,
+          os: target.os,
+        });
+
+        const extractUi = spawn(uiPlan.command.cmd, uiPlan.command.args, { stdio: 'inherit' });
+        await new Promise((resolve, reject) => {
+          extractUi.on('error', reject);
+          extractUi.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${uiPlan.command.cmd} exited with ${code}`))));
+        });
+      }
+
+      if (!(await pathExists(uiIndex))) {
+        fail(`Extracted ui web bundle not found at ${uiIndex}`);
+      }
+
+      childEnv.HAPPIER_SERVER_UI_DIR = uiDir;
+    }
+
+    const child = spawn(serverBin, positionals, { stdio: 'inherit', env: childEnv });
     child.on('exit', (code, signal) => {
       if (signal) process.kill(process.pid, signal);
       process.exit(code ?? 1);
@@ -169,4 +161,3 @@ async function main() {
 main().catch((err) => {
   fail(err instanceof Error ? err.message : String(err));
 });
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happier-dev/relay-server",
-  "version": "0.1.2-preview.10.1",
+  "version": "0.1.2-preview.138.1",
   "description": "Happier server runner (downloads and verifies the correct server binary for your platform).",
   "repository": "https://github.com/happier-dev/happier.git",
   "author": "Leeroy Brun <leeroy.brun@gmail.com>",
@@ -15,6 +15,9 @@
     "bin",
     "src"
   ],
+  "bundledDependencies": [
+    "@happier-dev/release-runtime"
+  ],
   "engines": {
     "node": ">=22"
   },
@@ -23,6 +26,7 @@
     "provenance": true
   },
   "scripts": {
+    "prepack": "node ./scripts/bundleWorkspaceDeps.mjs",
     "test": "node --test"
   }
 }

package/src/checksums.mjs

@@ -1,17 +1 @@
-export function lookupSha256({ checksumsText, filename }) {
-  const target = String(filename ?? '').trim();
-  if (!target) throw new Error('[checksums] filename is required');
-
-  const text = String(checksumsText ?? '');
-  const lines = text.split('\n');
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    const m = /^([0-9a-fA-F]{8,})\s+(.+)$/.exec(trimmed);
-    if (!m) continue;
-    const hash = m[1].toLowerCase();
-    const file = m[2].trim();
-    if (file === target) return hash;
-  }
-  throw new Error(`[checksums] sha256 not found for ${target}`);
-}
+export { lookupSha256 } from '@happier-dev/release-runtime/checksums';

package/src/checksums.test.mjs

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import { lookupSha256 } from './checksums.mjs';
+import { lookupSha256 } from '@happier-dev/release-runtime/checksums';
 
 test('lookupSha256 returns sha256 for matching filename', () => {
   const text = [
@@ -15,4 +15,3 @@ test('lookupSha256 returns sha256 for matching filename', () => {
 test('lookupSha256 throws when filename not present', () => {
   assert.throws(() => lookupSha256({ checksumsText: 'aaaa  other', filename: 'missing' }));
 });
-

package/src/minisign.mjs

@@ -1,94 +1 @@
-import { createHash, createPublicKey, verify } from 'node:crypto';
-
-const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
-
-function decodeBase64Line(line, expectedBytes) {
-  const bytes = Buffer.from(String(line ?? '').trim(), 'base64');
-  if (expectedBytes != null && bytes.length !== expectedBytes) {
-    throw new Error(`[minisign] expected ${expectedBytes} bytes, got ${bytes.length}`);
-  }
-  return bytes;
-}
-
-function parseMinisignPublicKeyFile(pubkeyFile) {
-  const lines = String(pubkeyFile ?? '')
-    .split('\n')
-    .map((l) => l.trim())
-    .filter(Boolean);
-  if (lines.length < 2) throw new Error('[minisign] invalid public key file');
-  const payload = lines.at(-1);
-  const bytes = decodeBase64Line(payload, 42);
-  const signatureAlgorithm = bytes.subarray(0, 2);
-  const keyId = bytes.subarray(2, 10);
-  const rawPublicKey = bytes.subarray(10, 42);
-  return { signatureAlgorithm, keyId, rawPublicKey };
-}
-
-function parseMinisignSignatureFile(sigFile) {
-  const lines = String(sigFile ?? '').split('\n');
-  if (lines.length < 4) throw new Error('[minisign] invalid signature file');
-
-  const untrustedPayload = String(lines[1] ?? '').trim();
-  const trustedComment = String(lines[2] ?? '');
-  const globalPayload = String(lines[3] ?? '').trim();
-
-  const untrustedBytes = decodeBase64Line(untrustedPayload, 74);
-  const signatureAlgorithm = untrustedBytes.subarray(0, 2);
-  const keyId = untrustedBytes.subarray(2, 10);
-  const signature = untrustedBytes.subarray(10, 74);
-
-  const globalSignature = decodeBase64Line(globalPayload, 64);
-
-  if (!trustedComment.startsWith('trusted comment: ')) {
-    throw new Error('[minisign] unexpected trusted comment format');
-  }
-  const trustedSuffix = Buffer.from(trustedComment.slice('trusted comment: '.length), 'utf-8');
-
-  return { signatureAlgorithm, keyId, signature, trustedSuffix, globalSignature };
-}
-
-function createEd25519PublicKey(rawPublicKey) {
-  if (!Buffer.isBuffer(rawPublicKey) || rawPublicKey.length !== 32) {
-    throw new Error('[minisign] invalid Ed25519 public key length');
-  }
-  const spki = Buffer.concat([ED25519_SPKI_PREFIX, rawPublicKey]);
-  return createPublicKey({ key: spki, format: 'der', type: 'spki' });
-}
-
-function bytesEqual(a, b) {
-  if (!a || !b) return false;
-  if (a.length !== b.length) return false;
-  // constant-time compare not required here (public data), but keep it simple.
-  return Buffer.compare(a, b) === 0;
-}
-
-export function verifyMinisign({ message, pubkeyFile, sigFile }) {
-  const bin = Buffer.isBuffer(message) ? message : Buffer.from(message ?? '');
-  const pubkey = parseMinisignPublicKeyFile(pubkeyFile);
-  const sig = parseMinisignSignatureFile(sigFile);
-
-  if (!bytesEqual(pubkey.signatureAlgorithm, Buffer.from('Ed'))) {
-    throw new Error('[minisign] incompatible public key signature algorithm');
-  }
-  if (!bytesEqual(pubkey.keyId, sig.keyId)) {
-    throw new Error('[minisign] incompatible key identifiers');
-  }
-
-  let prehashed = false;
-  if (bytesEqual(sig.signatureAlgorithm, Buffer.from('Ed'))) {
-    prehashed = false;
-  } else if (bytesEqual(sig.signatureAlgorithm, Buffer.from('ED'))) {
-    prehashed = true;
-  } else {
-    throw new Error('[minisign] unsupported signature algorithm');
-  }
-
-  const publicKey = createEd25519PublicKey(pubkey.rawPublicKey);
-  const payload = prehashed ? createHash('blake2b512').update(bin).digest() : bin;
-
-  const okSig = verify(null, payload, publicKey, sig.signature);
-  if (!okSig) return false;
-
-  const okGlobal = verify(null, Buffer.concat([sig.signature, sig.trustedSuffix]), publicKey, sig.globalSignature);
-  return okGlobal;
-}
+export { verifyMinisign } from '@happier-dev/release-runtime/minisign';

package/src/minisign.verify.test.mjs

@@ -2,7 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { generateKeyPairSync, sign } from 'node:crypto';
 
-import { verifyMinisign } from './minisign.mjs';
+import { verifyMinisign } from '@happier-dev/release-runtime/minisign';
 
 function b64(buf) {
   return Buffer.from(buf).toString('base64');
@@ -72,4 +72,3 @@ test('verifyMinisign rejects invalid signatures', () => {
 
   assert.equal(verifyMinisign({ message: Buffer.from('tampered', 'utf-8'), pubkeyFile, sigFile }), false);
 });
-

package/src/releaseAssets.mjs

@@ -1,33 +1,33 @@
-export function resolveServerReleaseAssets({ release, os, arch }) {
-  const assets = Array.isArray(release?.assets) ? release.assets : [];
-  const byName = new Map();
-  for (const asset of assets) {
-    const name = String(asset?.name ?? '');
-    const url = String(asset?.browser_download_url ?? '');
-    if (!name || !url) continue;
-    byName.set(name, { name, url });
-  }
-
-  const checksumsName = [...byName.keys()].find((name) => /^checksums-happier-server-v\d+\.\d+\.\d+\.txt$/.test(name));
-  if (!checksumsName) {
-    throw new Error('[server] missing checksums-happier-server-v<version>.txt asset');
-  }
-  const versionMatch = /^checksums-happier-server-v(\d+\.\d+\.\d+)\.txt$/.exec(checksumsName);
-  const version = versionMatch?.[1] ?? null;
-  if (!version) {
-    throw new Error('[server] unable to derive server version from checksums filename');
-  }
-
-  const checksumsSigName = `${checksumsName}.minisig`;
-  const tarballName = `happier-server-v${version}-${os}-${arch}.tar.gz`;
+import { resolveReleaseAssetBundle } from '@happier-dev/release-runtime/assets';
 
-  const checksums = byName.get(checksumsName) ?? null;
-  const checksumsSig = byName.get(checksumsSigName) ?? null;
-  const tarball = byName.get(tarballName) ?? null;
-
-  if (!checksums) throw new Error(`[server] missing release asset: ${checksumsName}`);
-  if (!checksumsSig) throw new Error(`[server] missing release asset: ${checksumsSigName}`);
-  if (!tarball) throw new Error(`[server] missing release asset: ${tarballName}`);
+export function resolveServerReleaseAssets({ release, os, arch }) {
+  const resolved = resolveReleaseAssetBundle({
+    assets: release?.assets,
+    product: 'happier-server',
+    os,
+    arch,
+    preferZipOnWindows: true,
+  });
+  return {
+    version: resolved.version,
+    tarball: resolved.archive,
+    checksums: resolved.checksums,
+    checksumsSig: resolved.checksumsSig,
+  };
+}
 
-  return { version, tarball, checksums, checksumsSig };
+export function resolveUiWebReleaseAssets({ release }) {
+  const resolved = resolveReleaseAssetBundle({
+    assets: release?.assets,
+    product: 'happier-ui-web',
+    os: 'web',
+    arch: 'any',
+    preferZipOnWindows: false,
+  });
+  return {
+    version: resolved.version,
+    tarball: resolved.archive,
+    checksums: resolved.checksums,
+    checksumsSig: resolved.checksumsSig,
+  };
 }

package/src/releaseAssets.test.mjs

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import { resolveServerReleaseAssets } from './releaseAssets.mjs';
+import { resolveServerReleaseAssets, resolveUiWebReleaseAssets } from './releaseAssets.mjs';
 
 test('resolveServerReleaseAssets picks tarball + checksums + minisig for linux-x64', () => {
   const release = {
@@ -21,8 +21,40 @@ test('resolveServerReleaseAssets picks tarball + checksums + minisig for linux-x
   assert.equal(resolved.checksumsSig.name, 'checksums-happier-server-v0.1.0.txt.minisig');
 });
 
+test('resolveServerReleaseAssets prefers windows zip artifacts when available', () => {
+  const release = {
+    tag_name: 'server-preview',
+    assets: [
+      { name: 'checksums-happier-server-v0.2.0-preview.7.txt', browser_download_url: 'https://example/checksums.txt' },
+      { name: 'checksums-happier-server-v0.2.0-preview.7.txt.minisig', browser_download_url: 'https://example/checksums.txt.minisig' },
+      { name: 'happier-server-v0.2.0-preview.7-windows-x64.zip', browser_download_url: 'https://example/server-win.zip' },
+      { name: 'happier-server-v0.2.0-preview.7-windows-x64.tar.gz', browser_download_url: 'https://example/server-win.tgz' },
+    ],
+  };
+
+  const resolved = resolveServerReleaseAssets({ release, os: 'windows', arch: 'x64' });
+  assert.equal(resolved.version, '0.2.0-preview.7');
+  assert.equal(resolved.tarball.name, 'happier-server-v0.2.0-preview.7-windows-x64.zip');
+});
+
 test('resolveServerReleaseAssets throws when required assets are missing', () => {
   const release = { tag_name: 'server-preview', assets: [{ name: 'nope', browser_download_url: 'x' }] };
   assert.throws(() => resolveServerReleaseAssets({ release, os: 'linux', arch: 'x64' }));
 });
 
+test('resolveUiWebReleaseAssets picks ui-web tarball + checksums + minisig', () => {
+  const release = {
+    tag_name: 'ui-web-preview',
+    assets: [
+      { name: 'checksums-happier-ui-web-v0.3.0-preview.1.1.txt', browser_download_url: 'https://example/checksums.txt' },
+      { name: 'checksums-happier-ui-web-v0.3.0-preview.1.1.txt.minisig', browser_download_url: 'https://example/checksums.txt.minisig' },
+      { name: 'happier-ui-web-v0.3.0-preview.1.1-web-any.tar.gz', browser_download_url: 'https://example/ui-web.tgz' },
+    ],
+  };
+
+  const resolved = resolveUiWebReleaseAssets({ release });
+  assert.equal(resolved.version, '0.3.0-preview.1.1');
+  assert.equal(resolved.tarball.name, 'happier-ui-web-v0.3.0-preview.1.1-web-any.tar.gz');
+  assert.equal(resolved.checksums.name, 'checksums-happier-ui-web-v0.3.0-preview.1.1.txt');
+  assert.equal(resolved.checksumsSig.name, 'checksums-happier-ui-web-v0.3.0-preview.1.1.txt.minisig');
+});

package/src/runnerConfig.mjs

@@ -0,0 +1,60 @@
+function parseArgs(argv) {
+  const kv = new Map();
+  const flags = new Set();
+  const positionals = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--') {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!String(a ?? '').startsWith('--')) {
+      positionals.push(String(a));
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next && !String(next).startsWith('--')) {
+      kv.set(a, String(next));
+      i += 1;
+      continue;
+    }
+    flags.add(String(a));
+    kv.set(a, 'true');
+  }
+  return { kv, flags, positionals };
+}
+
+function normalizeChannel(raw) {
+  const channel = String(raw ?? '').trim() || 'stable';
+  if (channel !== 'stable' && channel !== 'preview') {
+    throw new Error(`Invalid --channel '${channel}'. Expected stable|preview.`);
+  }
+  return channel;
+}
+
+function parseBooleanFlag(raw, fallback) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (!value) return fallback;
+  if (value === '1' || value === 'true' || value === 'yes' || value === 'y' || value === 'on') return true;
+  if (value === '0' || value === 'false' || value === 'no' || value === 'n' || value === 'off') return false;
+  return fallback;
+}
+
+export function parseRunnerInvocation(argv = []) {
+  const { kv, flags, positionals } = parseArgs(Array.isArray(argv) ? argv : []);
+  const channel = normalizeChannel(kv.get('--channel'));
+  const serverTag = String(kv.get('--tag') ?? '').trim() || (channel === 'preview' ? 'server-preview' : 'server-stable');
+  const uiWebTag = String(kv.get('--ui-tag') ?? '').trim() || (channel === 'preview' ? 'ui-web-preview' : 'ui-web-stable');
+
+  const withUiWeb =
+    !(flags.has('--without-ui') || parseBooleanFlag(kv.get('--with-ui'), true) === false);
+
+  return {
+    channel,
+    serverTag,
+    uiWebTag,
+    withUiWeb,
+    positionals,
+  };
+}
+

package/src/runnerConfig.test.mjs

@@ -0,0 +1,31 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { parseRunnerInvocation } from './runnerConfig.mjs';
+
+test('parseRunnerInvocation defaults to stable channel and installs ui web bundle', () => {
+  const parsed = parseRunnerInvocation([]);
+  assert.equal(parsed.channel, 'stable');
+  assert.equal(parsed.serverTag, 'server-stable');
+  assert.equal(parsed.uiWebTag, 'ui-web-stable');
+  assert.equal(parsed.withUiWeb, true);
+});
+
+test('parseRunnerInvocation resolves preview tags from channel', () => {
+  const parsed = parseRunnerInvocation(['--channel', 'preview']);
+  assert.equal(parsed.channel, 'preview');
+  assert.equal(parsed.serverTag, 'server-preview');
+  assert.equal(parsed.uiWebTag, 'ui-web-preview');
+});
+
+test('parseRunnerInvocation honors explicit tag overrides', () => {
+  const parsed = parseRunnerInvocation(['--tag', 'server-preview', '--ui-tag', 'ui-web-preview']);
+  assert.equal(parsed.serverTag, 'server-preview');
+  assert.equal(parsed.uiWebTag, 'ui-web-preview');
+});
+
+test('parseRunnerInvocation supports --without-ui', () => {
+  const parsed = parseRunnerInvocation(['--without-ui']);
+  assert.equal(parsed.withUiWeb, false);
+});
+

package/src/target.mjs

@@ -0,0 +1,48 @@
+import { join } from 'node:path';
+
+export function resolveServerRunnerTarget({ platform, arch }) {
+  const p = String(platform ?? '').trim();
+  const a = String(arch ?? '').trim();
+  if (!p) {
+    throw new Error('Unsupported platform: (empty)');
+  }
+  if (p !== 'linux' && p !== 'darwin' && p !== 'win32') {
+    throw new Error(`Unsupported platform '${p}'. Expected linux|darwin|win32.`);
+  }
+
+  const os = p === 'win32' ? 'windows' : p;
+  if (a !== 'x64' && a !== 'arm64') {
+    throw new Error(`Unsupported architecture '${a}'. Expected x64 or arm64.`);
+  }
+  if (p === 'win32' && a !== 'x64') {
+    throw new Error(`Unsupported architecture '${a}' for windows. Expected x64.`);
+  }
+
+  return {
+    os,
+    arch: a,
+    exeName: os === 'windows' ? 'happier-server.exe' : 'happier-server',
+  };
+}
+
+export function resolveRunnerCacheRoot({ platform, homedir, env }) {
+  const p = String(platform ?? '').trim();
+  const home = String(homedir ?? '').trim();
+  const e = env && typeof env === 'object' ? env : {};
+
+  if (String(e.HAPPIER_CACHE_DIR ?? '').trim()) {
+    return String(e.HAPPIER_CACHE_DIR).trim();
+  }
+
+  if (p === 'win32') {
+    const local = String(e.LOCALAPPDATA ?? '').trim();
+    return local || join(home || 'C:\\\\Users\\\\Default', 'AppData', 'Local');
+  }
+  if (p === 'darwin') {
+    return join(home || '', 'Library', 'Caches');
+  }
+  const xdg = String(e.XDG_CACHE_HOME ?? '').trim();
+  if (xdg) return xdg;
+  return join(home || '', '.cache');
+}
+

package/src/target.test.mjs

@@ -0,0 +1,54 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+
+import { resolveServerRunnerTarget, resolveRunnerCacheRoot } from './target.mjs';
+
+test('resolveServerRunnerTarget maps linux platforms to linux assets', () => {
+  assert.deepEqual(resolveServerRunnerTarget({ platform: 'linux', arch: 'x64' }), {
+    os: 'linux',
+    arch: 'x64',
+    exeName: 'happier-server',
+  });
+});
+
+test('resolveServerRunnerTarget maps darwin platforms to darwin assets', () => {
+  assert.deepEqual(resolveServerRunnerTarget({ platform: 'darwin', arch: 'arm64' }), {
+    os: 'darwin',
+    arch: 'arm64',
+    exeName: 'happier-server',
+  });
+});
+
+test('resolveServerRunnerTarget maps win32 platforms to windows assets', () => {
+  assert.deepEqual(resolveServerRunnerTarget({ platform: 'win32', arch: 'x64' }), {
+    os: 'windows',
+    arch: 'x64',
+    exeName: 'happier-server.exe',
+  });
+});
+
+test('resolveServerRunnerTarget rejects unsupported platform/arch combinations', () => {
+  assert.throws(() => resolveServerRunnerTarget({ platform: 'freebsd', arch: 'x64' }), /Unsupported platform/i);
+  assert.throws(() => resolveServerRunnerTarget({ platform: 'win32', arch: 'arm64' }), /Unsupported architecture/i);
+});
+
+test('resolveRunnerCacheRoot uses platform-specific defaults', () => {
+  assert.equal(
+    resolveRunnerCacheRoot({ platform: 'linux', homedir: '/home/me', env: {} }),
+    join('/home/me', '.cache')
+  );
+  assert.equal(
+    resolveRunnerCacheRoot({ platform: 'linux', homedir: '/home/me', env: { XDG_CACHE_HOME: '/tmp/xdg' } }),
+    '/tmp/xdg'
+  );
+  assert.equal(
+    resolveRunnerCacheRoot({ platform: 'darwin', homedir: '/Users/me', env: {} }),
+    join('/Users/me', 'Library', 'Caches')
+  );
+  assert.equal(
+    resolveRunnerCacheRoot({ platform: 'win32', homedir: 'C:\\\\Users\\\\me', env: { LOCALAPPDATA: 'C:\\\\Local' } }),
+    'C:\\\\Local'
+  );
+});
+