@jonaskahn/relo 0.0.0-stage → 0.1.0-beta.15.f766ed9a

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+<div align="center">
+<img src="assets/logo.png" alt="Relo" width="96">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h2>Relo</h2>
+
+<code>▚▚▚▚▚▚▚ Light • Fast • Reliable ▚▚▚▚▚▚▚</code>
+
+</div>
+
+> One local proxy that lets Codex, Claude Code, Cursor and Grok, etc. Talk to any model, any provider with no config changes.
+
+## Installation
+
+```console
+$ npm install -g @jonaskahn/relo
+$ relo daemon start
+```
+
+## What you get
+
+This package installs the `relo` binary and puts a `relo` command on your
+PATH. It is the daemon with its tray icon, downloaded from the GitHub release
+and verified against the release checksums.
+
+`relo` runs headless where there is no desktop session — a container or a
+server — and shows its tray icon where there is one. The installers
+(`Relo-Setup-*.exe` on Windows, the `Relo-Setup-*.deb` / `Relo-Setup-*.rpm`
+packages on Linux, and `Relo.app` on macOS) install the same binary.
+
+Every install provides the `relo` command, so they are never installed
+together: if another relo is already on your PATH, this install refuses and
+tells you where it found it. Removing that install first lets this package
+take over.
+
+Supported hosts: macOS, Linux, and Windows on both Intel and Apple Silicon (or
+their ARM equivalents). State lives in `$RELO_HOME`, `~/.relo` by default, so
+an npm install and a `.deb` install share the same configuration.
+
+## Updates
+
+The postinstall stops a running relo before replacing the binary: it asks the
+old build to drain, ends the processes of this home that still hold a
+configured port, and checks the ports are free before it writes the new one. A
+port another program holds fails the install rather than killing that program:
+
+```
+relo: install failed -- something else is listening on port 10101
+```
+
+Free the port, or point `$RELO_HOME/config.toml` at another one, and install
+again. The data is never touched by an update.
+
+## Uninstalling
+
+```console
+$ npm uninstall -g @jonaskahn/relo
+```
+
+This keeps your data in `$RELO_HOME`: the preuninstall script stops the daemon,
+frees its ports, and turns off start-at-login. To remove the data as well, use
+the daemon itself, which also removes the program:
+
+```console
+$ relo uninstall --wipe
+```
+
+Without a flag, `relo uninstall` asks whether the data goes.
+
+## Install options
+
+The installer downloads the daemon binary from a GitHub release: the latest
+one by default, or the tag `--relo-version` names when the installer is run
+by hand:
+
+```console
+$ node "$(npm root -g)/relo/lib/install.mjs" --relo-version 0.2.0
+```
+
+## Troubleshooting
+
+An install that printed a platform or checksum error left nothing behind, so
+fix the cause and run the installer again:
+
+```console
+$ node "$(npm root -g)/relo/lib/install.mjs"
+```
+
+Downloads are verified against `checksums.txt` from the release. A mismatch
+fails the install rather than writing an executable.
+
+## Links
+
+- [Source](https://github.com/jonaskahn/relo)
+- [Releases](https://github.com/jonaskahn/relo/releases)
+- [Documentation](https://github.com/jonaskahn/relo#readme)
+
+AGPL-3.0-only

package/bin/relo.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Entry point npm links as `relo`. It execs the platform binary the postinstall
+// placed beside it, passing through arguments, streams, and exit status.
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { target } from '../lib/platform.mjs';
+
+const binary = resolve(dirname(fileURLToPath(import.meta.url)), target().name);
+
+try {
+	accessSync(binary, constants.X_OK);
+} catch {
+	console.error(
+		'relo: this install has no daemon binary. Reinstall without --ignore-scripts, or run\n' +
+			'  node node_modules/relo/lib/install.mjs'
+	);
+	process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+
+// A terminal interrupt already reaches the child through the process group.
+// These cover a service manager or a shell that signals only the launcher.
+if (process.platform !== 'win32') {
+	for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+		process.on(signal, () => child.kill(signal));
+	}
+}
+
+child.on('error', (error) => {
+	console.error(`relo: could not start ${binary}: ${error.message}`);
+	process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+	// A signalled child reports no code; pass the shell convention through so a
+	// caller waiting on relo still sees a failure.
+	process.exit(code ?? (signal === 'SIGINT' ? 130 : 1));
+});

package/lib/checksums.mjs

@@ -0,0 +1,31 @@
+// Verifies a downloaded asset against the digest the release publishes beside
+// it, so a tampered or truncated download fails the install instead of being
+// written into the package as an executable.
+import { createHash } from 'node:crypto';
+
+// digestOf is the lowercase hex sha256 of a buffer.
+export function digestOf(body) {
+	return createHash('sha256').update(body).digest('hex');
+}
+
+// parse reads the `sha256  name` lines of a sha256sum file into a lookup. It
+// accepts the two-column form both shasum and sha256sum emit, with one or two
+// spaces and the optional leading asterisk binary mode adds.
+export function parse(manifest) {
+	const entries = new Map();
+	for (const line of manifest.toString('utf8').split('\n')) {
+		const match = /^([0-9a-f]{64})\s+\*?(.+?)\s*$/.exec(line);
+		if (match) entries.set(match[2], match[1]);
+	}
+	return entries;
+}
+
+// expect finds the digest for one asset and checks the body against it.
+export function expect(entries, name, body) {
+	const expected = entries.get(name);
+	if (!expected) throw new Error(`${name} is not listed in the release checksums`);
+	const actual = digestOf(body);
+	if (actual !== expected) {
+		throw new Error(`${name} does not match its published sha256. expected ${expected}, got ${actual}`);
+	}
+}

package/lib/conflict.mjs

@@ -0,0 +1,68 @@
+// Finds another Relo command on PATH. The binary is one product now: a daemon
+// with its tray icon, built the same way for the npm package and the
+// installers. Two installs would still fight over the name, the home
+// directory, and the ports, so the install refuses when a command this
+// package did not install answers PATH.
+import { accessSync, constants, realpathSync } from 'node:fs';
+import { delimiter, join, resolve, sep } from 'node:path';
+
+// candidates lists the relo commands a PATH resolves, in order. Windows
+// installs the app's command as relo.cmd, a shim that starts the GUI
+// relo.exe, and npm's bin as its own shim; both spellings are candidates
+// there, while POSIX installs the bare command.
+export function candidates({ pathValue = '', nodePlatform = 'linux', name = 'relo' } = {}) {
+	const executables = nodePlatform === 'win32' ? [`${name}.exe`, `${name}.cmd`] : [name];
+	const found = [];
+	for (const dir of pathValue.split(delimiter).filter(Boolean)) {
+		for (const file of executables) {
+			const candidate = join(dir, file);
+			try {
+				accessSync(candidate, constants.X_OK);
+				found.push(candidate);
+			} catch {
+				// Not there, or not executable: keep looking.
+			}
+		}
+	}
+	return found;
+}
+
+// findConflictingRelo returns the path of the first relo command on PATH
+// this package did not install, or null. Commands inside selfDir are this
+// package's own install and are skipped, so a reinstall is not a conflict.
+// selfDir, PATH, and the platform are parameters so the search can be tested
+// against fixture directories.
+export function findConflictingRelo({
+	env = process.env,
+	nodePlatform = process.platform,
+	selfDir = null
+} = {}) {
+	const pathValue = env.PATH ?? env.Path ?? '';
+	for (const candidate of candidates({ pathValue, nodePlatform })) {
+		if (selfDir && insideDir(candidate, selfDir)) {
+			continue;
+		}
+		return candidate;
+	}
+	return null;
+}
+
+// insideDir reports whether candidate resolves inside dir, following a link
+// the way the npm bin shim points into the installed package. Both sides
+// resolve, because either path may itself sit under a link. A path that
+// resolves nowhere compares by its raw form instead.
+function insideDir(candidate, dir) {
+	const prefix = existingPath(dir) + sep;
+	const resolved = existingPath(candidate);
+	return resolved === prefix.slice(0, -1) || resolved.startsWith(prefix);
+}
+
+// existingPath resolves a path through any links, or returns its raw form
+// when nothing is there to resolve.
+function existingPath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return resolve(path);
+	}
+}

package/lib/daemon.mjs

@@ -0,0 +1,280 @@
+// Quiesces the daemon running from one home before its binary is replaced, and
+// offers to start the new one: a graceful `daemon stop --force` first, then
+// signals against this home's processes only, so a process that merely reused a
+// port is never touched.
+//
+// The config scan reads key names instead of parsing TOML, so a key this
+// scan cannot see keeps its default.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { createReadStream, createWriteStream, existsSync, readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// reloHome is the state directory the daemon serves: $RELO_HOME, else ~/.relo.
+export function reloHome(env = process.env) {
+	return env.RELO_HOME?.trim() || join(homedir(), '.relo');
+}
+
+const DEFAULTS = { port: 10101, openai: 10201, anthropic: 10202, gemini: 10203 };
+
+// servicePorts lists the ports a home opens: the management port plus one per
+// client protocol. A protocol whose port is 0 is not opened.
+export function servicePorts(configText = '') {
+	const found = {};
+	for (const line of configText.split('\n')) {
+		const match = line.match(/^\s*(port|openai|anthropic|gemini)\s*=\s*(\d+)/);
+		if (match) found[match[1]] ??= Number(match[2]);
+	}
+	return ['port', 'openai', 'anthropic', 'gemini']
+		.map((key) => found[key] ?? DEFAULTS[key])
+		.filter((port) => port !== 0);
+}
+
+// runtimePid reads the pid a daemon published, or null when no usable file
+// is there.
+export function runtimePid(text) {
+	const match = text.match(/"pid"\s*:\s*(\d+)/);
+	return match ? Number(match[1]) : null;
+}
+
+// parseLsof reads `lsof -nP -iTCP:<port> -sTCP:LISTEN -t` output: one pid
+// per line.
+export function parseLsof(text) {
+	return text
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => /^\d+$/.test(line))
+		.map(Number);
+}
+
+// parseSs reads `ss -ltnp` output, collecting every pid= on a line that names
+// the port.
+export function parseSs(text, port) {
+	const names = new RegExp(`:${port}(?!\\d)`);
+	const pids = [];
+	for (const line of text.split('\n')) {
+		if (!names.test(line)) continue;
+		for (const match of line.matchAll(/pid=(\d+)/g)) pids.push(Number(match[1]));
+	}
+	return pids;
+}
+
+// parseNetstat reads `netstat -ano -p tcp` output (windows), pairing a
+// LISTENING local port with its owning pid.
+export function parseNetstat(text, port) {
+	const pids = [];
+	for (const line of text.split('\n')) {
+		const match = line.match(/^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)/i);
+		if (match && Number(match[1]) === port) pids.push(Number(match[2]));
+	}
+	return pids;
+}
+
+// isReloImage reports whether an executable name is the relo binary, so a
+// signal never reaches a process that merely reused the port.
+export function isReloImage(comm) {
+	const base = comm.trim().split(/[\\/]/).pop().toLowerCase();
+	return base === 'relo' || base === 'relo.exe';
+}
+
+// servesHome reports whether a relo process belongs to this home. The pid
+// the home published always does; otherwise the command line must name
+// --home. A relo started without --home serves the default home.
+export function servesHome({ pid, owner, args, home, defaultHome }) {
+	if (owner && pid === owner) return true;
+	if (args.includes(`--home ${home}`) || args.includes(`--home=${home}`)) return true;
+	if (!/--home(?:=|\s)/.test(args)) return home === defaultHome;
+	return false;
+}
+
+// listeningPids lists the processes holding a port. An unavailable or empty
+// lookup reads as no listeners, so a missing lsof never fails the install.
+function listeningPids(port) {
+	try {
+		if (process.platform === 'win32') {
+			const out = execFileSync('netstat', ['-ano', '-p', 'tcp'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'ignore']
+			});
+			return parseNetstat(out, port);
+		}
+		if (process.platform === 'darwin') {
+			const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'ignore']
+			});
+			return parseLsof(out);
+		}
+		try {
+			const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'ignore']
+			});
+			return parseLsof(out);
+		} catch {
+			const out = execFileSync('ss', ['-ltnp'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'ignore']
+			});
+			return parseSs(out, port);
+		}
+	} catch {
+		return [];
+	}
+}
+
+// processInfo describes a pid, or null when it is already gone. The command
+// line comes from powershell on windows, which can fail; an empty line then
+// falls back to the owner and default-home rules in servesHome.
+function processInfo(pid) {
+	try {
+		if (process.platform === 'win32') {
+			const listing = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'ignore']
+			}).trim();
+			const comm = listing.match(/^"([^"]+)"/)?.[1] ?? '';
+			let args = '';
+			try {
+				args = execFileSync(
+					'powershell',
+					['-NoProfile', '-Command', `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`],
+					{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+				).trim();
+			} catch {}
+			return { comm, args };
+		}
+		const comm = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore']
+		}).trim();
+		const args = execFileSync('ps', ['-p', String(pid), '-o', 'args='], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore']
+		}).trim();
+		return { comm, args };
+	} catch {
+		return null;
+	}
+}
+
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function signal(pid, name) {
+	try {
+		process.kill(pid, name);
+	} catch {}
+}
+
+// sleep blocks without a dependency, so the poll below stays synchronous.
+function sleep(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// quiesce leaves no Relo running from one home before its binary is replaced:
+// a graceful `daemon stop --force` through the already-installed binary, then
+// signals against this home's processes only, then a check that the configured
+// ports are free. Reports whether a daemon was there at all.
+//
+// A port another program holds fails the install. The daemon that would have
+// served it is gone either way, so replacing its binary now would leave a new
+// daemon that cannot bind -- and an automatic `npm install` must never kill a
+// process that is not Relo.
+export function quiesce(home, { binary } = {}) {
+	const configPath = join(home, 'config.toml');
+	const ports = servicePorts(existsSync(configPath) ? readFileSync(configPath, 'utf8') : '');
+	const runtimePath = join(home, 'runtime.json');
+	const defaultHome = join(homedir(), '.relo');
+	let owner = 0;
+	if (existsSync(runtimePath)) {
+		try {
+			owner = runtimePid(readFileSync(runtimePath, 'utf8')) ?? 0;
+		} catch {
+			owner = 0;
+		}
+		const info = owner ? processInfo(owner) : null;
+		if (!info || !isReloImage(info.comm)) owner = 0;
+	}
+	const candidates = new Set();
+	if (owner) candidates.add(owner);
+	for (const port of ports) {
+		for (const pid of listeningPids(port)) candidates.add(pid);
+	}
+	const victims = [...candidates].filter((pid) => {
+		const info = processInfo(pid);
+		return info && isReloImage(info.comm) && servesHome({ pid, owner, args: info.args, home, defaultHome });
+	});
+	const stopped = victims.length > 0;
+
+	if (binary && existsSync(binary)) {
+		// --force frees the ports too; a build that predates it rejects the
+		// flag, and the signals below cover that build.
+		spawnSync(binary, ['--home', home, 'daemon', 'stop', '--force'], { stdio: 'ignore' });
+	}
+
+	for (const pid of victims.filter(alive)) signal(pid, 'SIGTERM');
+	// A daemon gets ten seconds to close its listeners before the kill it
+	// cannot catch. On windows both signals terminate.
+	const deadline = Date.now() + 10_000;
+	let live = victims.filter(alive);
+	while (live.length > 0 && Date.now() < deadline) {
+		sleep(1000);
+		live = live.filter(alive);
+	}
+	for (const pid of live) signal(pid, 'SIGKILL');
+	rmSync(runtimePath, { force: true });
+
+	for (const port of ports) {
+		const holders = listeningPids(port);
+		if (holders.length > 0) {
+			throw new Error(
+				`relo: install failed -- something else is listening on port ${port}\n` +
+					'  free the port, or point relo at another one, and install again'
+			);
+		}
+	}
+	return { stopped };
+}
+
+// askStart prompts on a terminal and reports 'yes', 'no', or 'unattended'
+// when no terminal can be asked on. The answer never comes from stdin: under
+// a piped install stdin is not the user.
+export async function askStart() {
+	if (process.platform === 'win32') {
+		if (!process.stdin.isTTY) return 'unattended';
+		const terminal = createInterface({ input: process.stdin, output: process.stdout });
+		try {
+			const answer = await terminal.question('start relo now? [Y/n] ');
+			return /^[nN]/.test(answer.trim()) ? 'no' : 'yes';
+		} finally {
+			terminal.close();
+		}
+	}
+	let input;
+	try {
+		input = createReadStream('/dev/tty');
+		await new Promise((resolve, reject) => {
+			input.once('open', resolve);
+			input.once('error', reject);
+		});
+	} catch {
+		return 'unattended';
+	}
+	const terminal = createInterface({ input, output: createWriteStream('/dev/tty') });
+	try {
+		const answer = await terminal.question('start relo now? [Y/n] ');
+		return /^[nN]/.test(answer.trim()) ? 'no' : 'yes';
+	} catch {
+		return 'unattended';
+	} finally {
+		terminal.close();
+	}
+}

package/lib/download.mjs

@@ -0,0 +1,52 @@
+// Fetches a URL with a few spaced attempts. Kept out of install.mjs so the
+// retry and error rules can be tested without running a download.
+//
+// A permanent client error fails fast: retrying a missing asset only burns
+// three waits before printing the same dead end. Network errors, throttling,
+// and 5xx keep the retries, since GitHub answers a cold CDN edge with an
+// error often enough that a single attempt reads as a broken install.
+const ATTEMPTS = 3;
+
+// failFast reports whether another attempt would hit the same wall. 408
+// timed out and 429 was throttled, so both are worth retrying; every other
+// 4xx names something the next attempt will hit too.
+function failFast(status) {
+	if (status === 408 || status === 429 || status >= 500) return false;
+	return status >= 400 && status < 500;
+}
+
+// fetchBytes returns the body of a URL. fetchImpl and sleep take arguments
+// so tests can fake the network and skip the waits.
+export async function fetchBytes(
+	target,
+	what,
+	{ fetchImpl = fetch, sleep = (ms) => new Promise((done) => setTimeout(done, ms)) } = {}
+) {
+	let last;
+	for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+		try {
+			const response = await fetchImpl(target, { redirect: 'follow' });
+			if (!response.ok) {
+				if (failFast(response.status)) {
+					throw Object.assign(
+						new Error(
+							`no ${what} in the release (HTTP ${response.status}). ` +
+								'No release may be published yet; rerun the installer with --relo-version <tag> for a published tag, or without it for the latest release.'
+						),
+						{ permanent: true }
+					);
+				}
+				throw new Error(`${response.status} ${response.statusText}`);
+			}
+			return Buffer.from(await response.arrayBuffer());
+		} catch (error) {
+			if (error?.permanent) throw error;
+			last = error;
+			if (attempt < ATTEMPTS) {
+				console.warn(`relo: ${what} failed (${error.message}), retrying`);
+				await sleep(attempt * 1000);
+			}
+		}
+	}
+	throw new Error(`could not download ${what} from ${target}: ${last.message}`);
+}

package/lib/install.mjs

@@ -0,0 +1,90 @@
+// Puts the binary for this host inside the installed package. The launcher
+// in bin/ execs it, so the daemon and its tray run as their own process and
+// do not need node at run time. The install refuses a machine where another
+// Relo already owns the relo command, whether an installer or an older
+// package put it there: two installs would fight over the name, the home
+// directory, and the ports. A relo running from this home is quiesced before
+// its binary is replaced -- its daemon is stopped and the ports it served
+// are freed -- and the install asks whether to start the new one.
+//
+// The binary always comes from a GitHub release: the one --relo-version names,
+// the one this package was published as when that is a prerelease, or the
+// latest release. Rerun this file by hand with the flag to install a specific
+// release.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { expect, parse } from './checksums.mjs';
+import { askStart, quiesce, reloHome } from './daemon.mjs';
+import { findConflictingRelo } from './conflict.mjs';
+import { fetchBytes } from './download.mjs';
+import { target } from './platform.mjs';
+import { assets, checksumsUrl, prereleaseTag, tagFromArgs, url } from './release.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const binaryDir = resolve(packageRoot, 'bin');
+const home = reloHome();
+const publishedVersion = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8')).version;
+
+// writeAtomic lands the binary in one rename, so an interrupted install leaves
+// no truncated executable behind for the launcher to find.
+async function writeAtomic(destination, body) {
+	const staging = `${destination}.download`;
+	await writeFile(staging, body, { mode: 0o755 });
+	await rename(staging, destination);
+}
+
+async function fromRelease(tag) {
+	const asset = target();
+	const { version } = assets(tag);
+
+	// One manifest lists every asset in the release, so a single fetch
+	// verifies the binary before anything executable is written.
+	const manifest = await fetchBytes(checksumsUrl(tag), 'checksums.txt');
+	const body = await fetchBytes(url(asset.name, tag), asset.name);
+	expect(parse(manifest), asset.name, body);
+	const destination = resolve(binaryDir, asset.name);
+	// Quiesced first: on windows the rename below fails over a running exe, and
+	// the new daemon cannot bind a port the old one still serves.
+	const { stopped } = quiesce(home, { binary: existsSync(destination) ? destination : undefined });
+	await mkdir(binaryDir, { recursive: true });
+	await writeAtomic(destination, body);
+	console.log(`relo: installed the ${version ? `v${version} ` : ''}daemon binary for ${asset.os}-${asset.arch}`);
+	console.log(stopped ? 'relo: stopped the running daemon' : 'relo: not running');
+	return destination;
+}
+
+try {
+	// One binary answers the relo command now, whether it came from this
+	// package or an installer, so a command this package did not install
+	// stops this one: it already provides the name, and a second Relo would
+	// fight it for the home directory and the ports. A previous install from
+	// this package is simply replaced below.
+	const conflict = findConflictingRelo({ selfDir: binaryDir });
+	if (conflict) {
+		throw new Error(
+			`another Relo install provides the relo command at ${conflict}\n` +
+				'  remove that install first to install this package, or keep using that install instead'
+		);
+	}
+	const destination = await fromRelease(tagFromArgs(process.argv.slice(2)) ?? prereleaseTag(publishedVersion));
+	const answer = await askStart();
+	if (answer === 'yes') {
+		const started = spawnSync(destination, ['daemon', 'start'], { stdio: 'inherit' });
+		if (started.status !== 0) {
+			console.warn('relo: could not start the daemon; run relo daemon start to try again');
+		}
+	} else {
+		console.log('relo: start it later with: relo daemon start');
+	}
+} catch (error) {
+	// Remove only the staging file this install wrote. Removing the directory
+	// would take bin/relo.mjs with it, leaving a package whose `relo` command
+	// no longer exists.
+	await rm(resolve(binaryDir, `${target().name}.download`), { force: true }).catch(() => {});
+	console.error(`relo: install failed\n${error.message}`);
+	process.exitCode = 1;
+}

package/lib/platform.mjs

@@ -0,0 +1,24 @@
+// Maps the host onto a release asset name. The assets are the ones
+// make build-all writes, so this translates Node's platform and arch into the
+// Go names the release job already publishes rather than keeping a second
+// table of its own.
+import { arch, platform } from 'node:os';
+
+const GOOS = { darwin: 'darwin', linux: 'linux', win32: 'windows' };
+const GOARCH = { arm64: 'arm64', x64: 'amd64' };
+
+const SUPPORTED = 'darwin and linux on amd64 and arm64, windows on amd64 and arm64.';
+
+// target describes the daemon binary a host installs. The platform and arch
+// default to this machine and take arguments so every host the package claims
+// to support can be tested from one machine. It throws with a message naming
+// the host when the release has no asset for it, so a failed install says
+// which platform is missing instead of what a 404 means.
+export function target({ platform: nodePlatform = platform(), arch: nodeArch = arch() } = {}) {
+	const os = GOOS[nodePlatform];
+	const cpu = GOARCH[nodeArch];
+	if (!os || !cpu) {
+		throw new Error(`relo publishes no binary for ${nodePlatform}-${nodeArch}. Supported: ${SUPPORTED}`);
+	}
+	return { os, arch: cpu, name: `relo-${os}-${cpu}${os === 'windows' ? '.exe' : ''}` };
+}

package/lib/release.mjs

@@ -0,0 +1,55 @@
+// Where the daemon binaries live and how they are named. Kept out of
+// install.mjs so the rules can be tested without running a download.
+
+// REPO is the GitHub repository the release job uploads to.
+export const REPO = 'https://github.com/jonaskahn/relo';
+
+// version normalizes a release tag, accepting both `v0.1.0` and `0.1.0`.
+export function version(tag) {
+	return tag?.trim().replace(/^v/, '') || null;
+}
+
+// tagFromArgs reads the release to install from the command line. The
+// installer takes no other argument; an unknown one is ignored so a bare
+// postinstall keeps installing the latest release.
+export function tagFromArgs(argv = []) {
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg.startsWith('--relo-version=')) return version(arg.slice('--relo-version='.length));
+		if (arg === '--relo-version' && i + 1 < argv.length) return version(argv[i + 1]);
+	}
+	return null;
+}
+
+// prereleaseTag pins an install to the version this package was published as,
+// and only when that version is a prerelease. A beta published under the beta
+// dist-tag would otherwise resolve "latest" and install the stable binary,
+// which is not the build its caller asked for. A stable package keeps
+// following the latest release, so re-publishing an old stable version still
+// tracks the channel instead of pinning itself.
+export function prereleaseTag(published) {
+	const pinned = version(published);
+	return pinned && /^\d+\.\d+\.\d+-/.test(pinned) ? pinned : null;
+}
+
+// assets resolves the download directory for one release. Without a tag it
+// returns the latest-release directory, which is how a release is always
+// found when no pin is given.
+export function assets(tag = null) {
+	const pinned = version(tag);
+	return {
+		base: pinned ? `${REPO}/releases/download/v${pinned}` : `${REPO}/releases/latest/download`,
+		version: pinned
+	};
+}
+
+// checksums lists every asset in a release with its sha256, so one fetch
+// covers the single binary this host needs.
+export function checksumsUrl(tag = null) {
+	return `${assets(tag).base}/checksums.txt`;
+}
+
+// url is the asset one host installs.
+export function url(name, tag = null) {
+	return `${assets(tag).base}/${name}`;
+}

package/lib/uninstall.mjs

@@ -0,0 +1,31 @@
+// Runs before npm removes this package: the daemon is stopped, its ports are
+// freed, and autostart is unregistered. The data is never touched here, because
+// an npm removal keeps it -- `relo uninstall` is the way to wipe it.
+//
+// The work goes through the installed binary, which is the one thing that
+// knows the configured ports and the login items. Without it the same quiesce
+// runs in node, so a removal that lost the binary still frees what it can.
+//
+// Best effort by design: npm skips this with --ignore-scripts, and an
+// uninstall must not fail over it.
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+import { quiesce, reloHome } from './daemon.mjs';
+import { target } from './platform.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const binary = resolve(packageRoot, 'bin', target().name);
+const home = reloHome();
+
+try {
+	if (existsSync(binary)) {
+		spawnSync(binary, ['--home', home, 'uninstall', '--prepare'], { stdio: 'inherit' });
+	} else {
+		quiesce(home);
+	}
+} catch (error) {
+	console.warn(`relo: could not stop the running daemon; ${error.message}`);
+}

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@jonaskahn/relo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@jonaskahn/relo",
+	"version": "0.1.0-beta.15.f766ed9a",
+	"description": "One local proxy that lets Codex, Claude Code, Cursor and Grok, etc. Talk to any model, any provider with no config changes",
+	"license": "AGPL-3.0-only",
+	"type": "module",
+	"homepage": "https://github.com/jonaskahn/relo#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jonaskahn/relo.git"
+	},
+	"bugs": {
+		"url": "https://github.com/jonaskahn/relo/issues"
+	},
+	"keywords": [
+		"llm",
+		"proxy",
+		"gateway",
+		"openai",
+		"anthropic",
+		"codex",
+		"claude-code",
+		"cursor",
+		"cli"
+	],
+	"bin": {
+		"relo": "bin/relo.mjs"
+	},
+	"os": [
+		"darwin",
+		"linux",
+		"win32"
+	],
+	"cpu": [
+		"x64",
+		"arm64"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"files": [
+		"bin/relo.mjs",
+		"lib/checksums.mjs",
+		"lib/conflict.mjs",
+		"lib/daemon.mjs",
+		"lib/download.mjs",
+		"lib/install.mjs",
+		"lib/platform.mjs",
+		"lib/release.mjs",
+		"lib/uninstall.mjs",
+		"README.md"
+	],
+	"scripts": {
+		"postinstall": "node lib/install.mjs",
+		"preuninstall": "node lib/uninstall.mjs",
+		"test": "node --test"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org"
+	}
+}