@jonaskahn/relo 0.1.4-beta.27.8d9c8af7 → 0.1.4

package/README.md

@@ -14,22 +14,49 @@
 
 ---
 
+## ▓ CONSOLE
+
+<div align="center">
+
+https://github.com/user-attachments/assets/cbda11c8-b60c-413b-8a08-03144dd06e7a
+
+<sub>Demo: using Relo in Codex</sub>
+</div>
+
+|                                                                              |                                                                        |                                                                     |
+|------------------------------------------------------------------------------|------------------------------------------------------------------------|---------------------------------------------------------------------|
+| Dashboard                                                                    | Connections                                                            | Groups                                                              |
+| <img src="https://github.com/user-attachments/assets/ba44719e-f176-4d02-9e92-10cf7055a6e8" alt="Dashboard" width="320">        | <img src="https://github.com/user-attachments/assets/b27d9948-1f30-4aac-a0f5-d98109c5522e" alt="Connections" width="320"> | <img src="https://github.com/user-attachments/assets/29ce8e23-925f-4d22-b571-a49d8bc70841" alt="Groups" width="320">    |
+| Agent Harness                                                                | Add agent                                                              | Usage                                                               |
+| <img src="https://github.com/user-attachments/assets/3e5bfe37-ad48-4c12-a32a-f4901f8f982a" alt="Agent Harness" width="320"> | <img src="https://github.com/user-attachments/assets/f4730cb7-7177-40c0-8d48-905dfde29ba3" alt="Add agent" width="320">    | <img src="https://github.com/user-attachments/assets/42f329be-4d1b-408c-bc8e-87a1237eccf6" alt="Usage" width="320"> |
+
 ## Install
 
-```console
-$ npm i -g @jonaskahn/relo        # latest stable (Node 22+)
-$ npm i -g @jonaskahn/relo@beta   # fresh from main
+- Latest, Stable
+
+```bash
+npm i -g @jonaskahn/relo --foreground-scripts
+```
+
+- Beta, Risk
+```bash
+npm i -g @jonaskahn/relo@beta --foreground-scripts
 ```
 
-Installs the `relo` binary, verified against the release checksums. State
-lives in `~/.relo` (`$RELO_HOME`), shared with every other installer. Never
-installed twice: if another Relo is on your PATH, this one refuses and tells
-you where it found it.
+Installs the `relo` binary, verified against the release checksums. The
+install downloads the ~13 MB daemon binary and prints each step, with a
+download bar showing the rate and the time left. `--foreground-scripts` keeps
+that output under the install: npm otherwise runs it in the background and
+shows nothing until the command ends, which makes a slow download look stuck.
+
+State lives in `~/.relo` (`$RELO_HOME`), shared with every other installer.
+Never installed twice: if another Relo is on your PATH, this one refuses and
+tells you where it found it.
 
 ## Start
 
-```console
-$ relo daemon start                 # console at http://127.0.0.1:10101
+```bash
+relo daemon start                 # console at http://127.0.0.1:10101
 ```
 
 One port serves everything: the console, the management API, and the data
@@ -42,16 +69,23 @@ is free. Your data is never touched. If another program holds the port, the
 install fails instead of killing it:
 
 ```
-relo: install failed -- something else is listening on port 10101
+✗ INSTALL FAILED
+something else is listening on port 10101
+  free the port, or point relo at another one, and install again
 ```
 
 ## Uninstall
 
-```console
-$ npm uninstall -g @jonaskahn/relo   # keeps your data
-$ relo uninstall --wipe               # removes data too
+- Remove and Keep Data
+```bash
+npm uninstall -g @jonaskahn/relo
+```
+- Remove and Wipe Data
+```bash
+relo uninstall --wipe 
 ```
 
+
 ## Links
 
 [Source](https://github.com/jonaskahn/relo) · [Releases](https://github.com/jonaskahn/relo/releases) · [Docs](https://github.com/jonaskahn/relo#readme)

package/lib/daemon.mjs

@@ -7,9 +7,10 @@
 // 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 { closeSync, existsSync, openSync, readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { ReadStream } from 'node:tty';
 
 // reloHome is the state directory the daemon serves: $RELO_HOME, else ~/.relo.
 export function reloHome(env = process.env) {
@@ -70,11 +71,25 @@ export function parseNetstat(text, port) {
 	return pids;
 }
 
-// isReloImage reports whether an executable name is the relo binary, so a
-// signal never reaches a process that merely reused the port.
+// isReloImage reports whether an executable name is a relo binary, so a
+// signal never reaches a process that merely reused the port. The installers
+// name the daemon `relo`, but the release assets and this package keep the
+// platform in the name (`relo-darwin-arm64`, `relo-darwin-arm64-0.1.1`), so
+// both spellings count.
 export function isReloImage(comm) {
 	const base = comm.trim().split(/[\\/]/).pop().toLowerCase();
-	return base === 'relo' || base === 'relo.exe';
+	if (base === 'relo' || base === 'relo.exe') return true;
+	return /^relo-(?:darwin|linux|windows)-(?:amd64|arm64)(?:-[0-9][0-9a-z.+-]*)?(?:\.exe)?$/.test(base);
+}
+
+// isReloProcess reports whether a process is a relo binary. Linux truncates
+// the command name at fifteen characters, which can cut `relo-linux-amd64`
+// short, so the executable in the command line settles it when the name does
+// not.
+export function isReloProcess({ comm = '', args = '' } = {}) {
+	if (isReloImage(comm)) return true;
+	const executable = args.trim().split(/\s+/)[0] ?? '';
+	return executable !== '' && isReloImage(executable);
 }
 
 // servesHome reports whether a relo process belongs to this home. The pid
@@ -200,7 +215,7 @@ export function quiesce(home, { binary } = {}) {
 			owner = 0;
 		}
 		const info = owner ? processInfo(owner) : null;
-		if (!info || !isReloImage(info.comm)) owner = 0;
+		if (!info || !isReloProcess(info)) owner = 0;
 	}
 	const candidates = new Set();
 	if (owner) candidates.add(owner);
@@ -209,7 +224,7 @@ export function quiesce(home, { binary } = {}) {
 	}
 	const victims = [...candidates].filter((pid) => {
 		const info = processInfo(pid);
-		return info && isReloImage(info.comm) && servesHome({ pid, owner, args: info.args, home, defaultHome });
+		return info && isReloProcess(info) && servesHome({ pid, owner, args: info.args, home, defaultHome });
 	});
 	const stopped = victims.length > 0;
 
@@ -235,7 +250,7 @@ export function quiesce(home, { binary } = {}) {
 		const holders = listeningPids(port);
 		if (holders.length > 0) {
 			throw new Error(
-				`relo: install failed -- something else is listening on port ${port}\n` +
+				`something else is listening on port ${port}\n` +
 					'  free the port, or point relo at another one, and install again'
 			);
 		}
@@ -243,37 +258,206 @@ export function quiesce(home, { binary } = {}) {
 	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();
+// move steps a menu selection like a game menu: it wraps at both ends, so
+// left from the first option lands on the last.
+export function move(index, count, delta) {
+	if (count <= 0) return 0;
+	return (index + delta + count) % count;
+}
+
+// decodeKeys reads the keys a terminal chunk carries: 'left', 'right',
+// 'enter', or 'interrupt'. pending holds an escape sequence the previous
+// chunk ended in the middle of; the returned pending is carried into the
+// next call.
+//
+// Arrows arrive in either form a terminal sends them, CSI (`ESC [ D`) and
+// application-cursor SS3 (`ESC O D`). A modified arrow -- parameters before
+// the final byte -- and every other sequence is consumed and ignored.
+export function decodeKeys(pending = '', chunk = '') {
+	const text = pending + chunk;
+	const keys = [];
+	let at = 0;
+	while (at < text.length) {
+		if (text[at] === '\x1b') {
+			const end = escapeEnd(text, at);
+			if (end === 0) return { keys, pending: text.slice(at) };
+			// A lone Esc, or the Esc of an Alt chord, leaves nothing to act
+			// on. Dropping only the Esc lets the next byte read as its own
+			// key, so an Esc press never swallows a following Enter.
+			if (end === at + 1) {
+				at += 1;
+				continue;
+			}
+			const sequence = text.slice(at, end);
+			if (sequence === '\x1b[C' || sequence === '\x1bOC') keys.push('right');
+			else if (sequence === '\x1b[D' || sequence === '\x1bOD') keys.push('left');
+			at = end;
+			continue;
 		}
+		const key = text[at];
+		if (key === '\r' || key === '\n') keys.push('enter');
+		else if (key === '\x03') keys.push('interrupt');
+		at += 1;
 	}
-	let input;
+	return { keys, pending: '' };
+}
+
+// escapeEnd finds the byte after the escape sequence starting at `at`. Zero
+// means the text ended before the sequence did, so the rest is a pending
+// prefix for the next chunk.
+function escapeEnd(text, at) {
+	const next = text[at + 1];
+	if (next === undefined) return 0;
+	if (next === '[') {
+		for (let cursor = at + 2; cursor < text.length; cursor += 1) {
+			const code = text.charCodeAt(cursor);
+			if (code >= 0x40 && code <= 0x7e) return cursor + 1;
+			// A control byte cannot sit inside a CSI: drop the Esc so the
+			// control byte still reads as itself.
+			if (code < 0x20) return at + 1;
+		}
+		return 0;
+	}
+	if (next === 'O') {
+		const third = text[at + 2];
+		if (third === undefined) return 0;
+		return third.charCodeAt(0) < 0x20 ? at + 1 : at + 3;
+	}
+	// A bare Esc, or the Esc of an Alt chord.
+	if (next === '\x1b' || next.charCodeAt(0) < 0x20) return at + 1;
+	return at + 2;
+}
+
+// terminalInput opens the terminal for raw keys. POSIX reads the controlling
+// tty, not stdin: under a piped install stdin is not the user. Windows has no
+// /dev/tty, so a console stdin is the only source there.
+function terminalInput() {
+	if (process.platform === 'win32') {
+		if (!process.stdin?.isTTY) return null;
+		return {
+			input: process.stdin,
+			close() {
+				// stdin stays open for the daemon spawn that follows.
+				process.stdin.pause();
+				process.stdin.unref();
+			}
+		};
+	}
+	let fd;
 	try {
-		input = createReadStream('/dev/tty');
-		await new Promise((resolve, reject) => {
-			input.once('open', resolve);
-			input.once('error', reject);
-		});
+		fd = openSync('/dev/tty', 'r+');
 	} catch {
-		return 'unattended';
+		return null;
 	}
-	const terminal = createInterface({ input, output: createWriteStream('/dev/tty') });
+	let input;
 	try {
-		const answer = await terminal.question('start relo now? [Y/n] ');
-		return /^[nN]/.test(answer.trim()) ? 'no' : 'yes';
+		input = new ReadStream(fd);
 	} catch {
-		return 'unattended';
+		// The stream owns the fd once it is built, but not when it is not.
+		closeSync(fd);
+		return null;
+	}
+	return {
+		input,
+		close() {
+			input.destroy();
+		}
+	};
+}
+
+// select shows labels as a left/right menu and resolves the chosen index, -1
+// when the user interrupts, or null when there is no terminal to ask on.
+// onDraw hears every move, so the caller can repaint its own screen.
+export async function select(labels, { onDraw } = {}) {
+	const source = terminalInput();
+	if (!source) return null;
+	const { input } = source;
+	let at = 0;
+	let pending = '';
+	let settled = false;
+	let resolve;
+	const settle = (value) => {
+		if (settled) return;
+		settled = true;
+		resolve(value);
+	};
+	const onStop = () => settle(null);
+	const onData = (chunk) => {
+		if (settled) return;
+		const decoded = decodeKeys(pending, chunk.toString('utf8'));
+		pending = decoded.pending;
+		for (const key of decoded.keys) {
+			if (key === 'left' || key === 'right') {
+				at = move(at, labels.length, key === 'right' ? 1 : -1);
+				onDraw?.(at);
+			} else if (key === 'enter') {
+				settle(at);
+				return;
+			} else if (key === 'interrupt') {
+				settle(-1);
+				return;
+			}
+		}
+	};
+	try {
+		return await new Promise((done) => {
+			resolve = done;
+			// The error listener goes on before raw mode: a failed setRawMode
+			// emits rather than throws, and an unhandled emit would crash.
+			input.once('error', onStop);
+			input.once('end', onStop);
+			input.once('close', onStop);
+			try {
+				input.setRawMode(true);
+			} catch {
+				settle(null);
+				return;
+			}
+			if (settled) return;
+			onDraw?.(at);
+			input.on('data', onData);
+		});
 	} finally {
-		terminal.close();
+		// Restore cooked mode before the error listener is removed, so a
+		// failed restore cannot surface as an unhandled error.
+		try {
+			input.setRawMode(false);
+		} catch {
+			// The terminal is gone; there is nothing left to restore.
+		}
+		input.removeListener('data', onData);
+		input.removeListener('error', onStop);
+		input.removeListener('end', onStop);
+		input.removeListener('close', onStop);
+		source.close();
+	}
+}
+
+// askStart asks the start question 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. onQuestion and onAnswer
+// let the caller draw the question inside its own screen; onQuestion hears
+// every move of the left/right menu, and the first label is Yes.
+//
+// A raw key stream is used rather than readline: a readline stream leaves tty
+// handles open, and those keep the installer's process alive after the work
+// is done, so npm waits on a postinstall that has already finished. select()
+// tears its stream down instead. Ctrl-C means "not now", never a failed
+// install: the binary is already in place.
+export async function askStart({ labels = ['YES', 'NO'], onQuestion, onAnswer } = {}) {
+	if (process.platform === 'win32' && !onQuestion) {
+		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();
+		}
 	}
+	const at = await select(labels, { onDraw: onQuestion });
+	if (at === null) return 'unattended';
+	if (at < 0) return 'no';
+	onAnswer?.(labels[at]);
+	return at === 0 ? 'yes' : 'no';
 }

package/lib/download.mjs

@@ -16,11 +16,20 @@ function failFast(status) {
 }
 
 // fetchBytes returns the body of a URL. fetchImpl and sleep take arguments
-// so tests can fake the network and skip the waits.
+// so tests can fake the network and skip the waits. onProgress is called with
+// the bytes received so far, the total when the server sends a length, and
+// the milliseconds since the body started arriving. onRetry is told about
+// each attempt that will be retried, so the caller can show it where the user
+// is watching.
 export async function fetchBytes(
 	target,
 	what,
-	{ fetchImpl = fetch, sleep = (ms) => new Promise((done) => setTimeout(done, ms)) } = {}
+	{
+		fetchImpl = fetch,
+		sleep = (ms) => new Promise((done) => setTimeout(done, ms)),
+		onProgress,
+		onRetry = (message) => console.warn(`relo: ${message}`)
+	} = {}
 ) {
 	let last;
 	for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
@@ -38,15 +47,37 @@ export async function fetchBytes(
 				}
 				throw new Error(`${response.status} ${response.statusText}`);
 			}
-			return Buffer.from(await response.arrayBuffer());
+			return await readBody(response, onProgress);
 		} catch (error) {
 			if (error?.permanent) throw error;
 			last = error;
 			if (attempt < ATTEMPTS) {
-				console.warn(`relo: ${what} failed (${error.message}), retrying`);
+				onRetry(`${what} failed (${error.message}), retrying`);
 				await sleep(attempt * 1000);
 			}
 		}
 	}
 	throw new Error(`could not download ${what} from ${target}: ${last.message}`);
 }
+
+// readBody reads the response body, reporting the bytes as they arrive when
+// the response is a stream. A response without a readable stream -- a test
+// double, or an older runtime -- is read whole.
+async function readBody(response, onProgress) {
+	if (!onProgress || !response.body?.getReader) {
+		return Buffer.from(await response.arrayBuffer());
+	}
+	const total = Number(response.headers?.get?.('content-length')) || 0;
+	const started = Date.now();
+	const reader = response.body.getReader();
+	const chunks = [];
+	let received = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		chunks.push(Buffer.from(value));
+		received += value.length;
+		onProgress(received, total, Date.now() - started);
+	}
+	return Buffer.concat(chunks);
+}

package/lib/install.mjs

@@ -21,6 +21,24 @@ import { expect, parse } from './checksums.mjs';
 import { askStart, quiesce, reloHome } from './daemon.mjs';
 import { findConflictingRelo, findReloApp, findSetupInstall } from './conflict.mjs';
 import { fetchBytes } from './download.mjs';
+import {
+	bar,
+	bytes,
+	choices,
+	chosen,
+	clear,
+	closeScreen,
+	done,
+	duration,
+	failed,
+	interactive,
+	note,
+	openScreen,
+	progress,
+	separator,
+	step,
+	warn
+} from './progress.mjs';
 import { target } from './platform.mjs';
 import { assets, checksumsUrl, prereleaseTag, selectBundle, tagFromArgs, url } from './release.mjs';
 import { extractBinary } from './archive.mjs';
@@ -38,33 +56,102 @@ async function writeAtomic(destination, body) {
 	await rename(staging, destination);
 }
 
-async function fromRelease(tag) {
-	const asset = target();
-	const { version } = assets(tag);
+// LOGO is the installer's block-letter mark. Six rows of shadow type give
+// the title card its arcade weight.
+const LOGO = [
+	'██████╗ ███████╗██╗      ██████╗',
+	'██╔══██╗██╔════╝██║     ██╔═══██╗',
+	'██████╔╝█████╗  ██║     ██║   ██║',
+	'██╔══██╗██╔══╝  ██║     ██║   ██║',
+	'██║  ██║███████╗███████╗╚██████╔╝',
+	'╚═╝  ╚═╝╚══════╝╚══════╝ ╚═════╝'
+];
+
+// label pads a step name to one column, so the values line up under it.
+const label = (name) => name.padEnd(8);
+
+// downloadStats renders the running download: the shimmering bar, the
+// percentage, the bytes, the rate, and the time left.
+function downloadStats(received, total, elapsed, tick) {
+	const seconds = Math.max(elapsed, 1) / 1000;
+	const rate = received / seconds;
+	const parts = [];
+	if (total > 0) parts.push(`${Math.floor((received / total) * 100)}%`);
+	parts.push(total > 0 ? `${bytes(received)}/${bytes(total)}` : bytes(received));
+	// A rate needs a moment to mean anything: the first chunk lands before
+	// any time has passed, which reads as an absurd speed and a wrong ETA.
+	if (elapsed >= 500) {
+		parts.push(`${bytes(rate)}/s`);
+		if (total > received && rate > 0) {
+			parts.push(`ETA ${Math.max(1, Math.ceil((total - received) / rate))}s`);
+		}
+	}
+	const barText = total > 0 ? `[${bar(received / total, { width: 12, color: true, frame: tick })}]  ` : '';
+	return `${barText}${parts.join('  ')}`;
+}
+
+async function fromRelease(tag, asset, startedAt) {
+	step(label('MANIFEST'));
+	const checksums = await fetchBytes(checksumsUrl(tag), 'checksums.txt', { onRetry: warn });
+	done(`${label('MANIFEST')}  ${bytes(checksums.length)}`);
 
 	// One manifest lists every asset in the release, so a single fetch
 	// verifies the binary before anything executable is written. A release
 	// carrying the raw binary uses it; one carrying only the versioned
 	// tarballs falls back to this host's archive, and the binary inside is
 	// what the launcher beside it already expects.
-	const manifest = parse(await fetchBytes(checksumsUrl(tag), 'checksums.txt'));
+	const manifest = parse(checksums);
 	const pick = selectBundle(manifest, asset);
-	const downloaded = await fetchBytes(url(pick.name, tag), pick.name);
+	step(label('DOWNLOAD'));
+	const downloadStart = Date.now();
+	let latest = { received: 0, total: 0 };
+	const downloaded = await fetchBytes(url(pick.name, tag), pick.name, {
+		onProgress: (received, total) => {
+			latest = { received, total };
+			progress(
+				(tick) => downloadStats(latest.received, latest.total, Date.now() - downloadStart, tick),
+				{ force: total > 0 && received === total }
+			);
+		},
+		onRetry: warn
+	});
+	done(`${label('DOWNLOAD')}  ${bytes(downloaded.length)} in ${duration(Date.now() - downloadStart)}`);
+
 	expect(manifest, pick.name, downloaded);
+	done(`${label('CHECKSUM')}  sha256 verified`);
+
 	const inner = asset.os === 'windows' ? 'relo.exe' : 'relo';
-	const body = pick.kind === 'raw' ? downloaded : extractBinary(downloaded, { names: [inner] });
+	let body = downloaded;
+	if (pick.kind !== 'raw') {
+		step(label('EXTRACT'));
+		body = extractBinary(downloaded, { names: [inner] });
+		done(`${label('EXTRACT')}  ${inner}`);
+	}
+
 	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.
+	step(label('DAEMON'));
 	const { stopped } = quiesce(home, { binary: existsSync(destination) ? destination : undefined });
+	done(`${label('DAEMON')}  ${stopped ? 'stopped the running daemon' : 'not running'}`);
+
+	step(label('INSTALL'));
 	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');
+	done(`${label('INSTALL')}  ${bytes(body.length)} · ${asset.os}-${asset.arch} · ${duration(Date.now() - startedAt)}`);
 	return destination;
 }
 
 try {
+	const startedAt = Date.now();
+	const tag = tagFromArgs(process.argv.slice(2)) ?? prereleaseTag(publishedVersion);
+	const asset = target();
+	const { version } = assets(tag);
+	await openScreen(LOGO, 'I N S T A L L E R', [
+		version ? `v${version}` : 'latest release',
+		`${asset.os} · ${asset.arch}`.toUpperCase()
+	]);
+	step(label('CONFLICT'));
 	// 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
@@ -92,21 +179,48 @@ try {
 				'  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();
+	done(`${label('CONFLICT')}  no other relo install`);
+
+	const destination = await fromRelease(tag, asset, startedAt);
+	separator();
+	const question = 'START RELO NOW?';
+	const labels = ['YES', 'NO'];
+	const answer = interactive()
+		? await askStart({
+				labels,
+				onQuestion: (at) => choices(question, labels, at),
+				onAnswer: (value) => chosen(question, value)
+			})
+		: await askStart();
 	if (answer === 'yes') {
-		const started = spawnSync(destination, ['daemon', 'start'], { stdio: 'inherit' });
+		closeScreen();
+		// The daemon's error goes into the result block rather than through
+		// the screen: a start refused before it spawned anything names the
+		// cause on stderr, and that is the whole answer.
+		const started = spawnSync(destination, ['daemon', 'start'], {
+			stdio: ['inherit', 'inherit', 'pipe'],
+			encoding: 'utf8'
+		});
 		if (started.status !== 0) {
-			console.warn('relo: could not start the daemon; run relo daemon start to try again');
+			const detail = (started.stderr ?? '').trim() || started.error?.message || '';
+			failed(
+				'DAEMON DID NOT START',
+				detail
+					? `${detail}\n  start it later: relo daemon start`
+					: 'start it later: relo daemon start'
+			);
 		}
 	} else {
-		console.log('relo: start it later with: relo daemon start');
+		note('start it later: relo daemon start');
+		closeScreen();
 	}
 } 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}`);
+	clear();
+	closeScreen();
+	failed('INSTALL FAILED', error.message);
 	process.exitCode = 1;
 }

package/lib/progress.mjs

@@ -0,0 +1,409 @@
+// Writes the install's progress where the user can watch it, styled as a
+// Game Boy screen: the DMG palette, a title screen that reveals itself, and
+// a menu of steps inside the same frame.
+//
+// npm runs a postinstall in the background by default, so everything the
+// installer prints on stdout is captured and shown only when the script
+// fails. The user's terminal is still there, so the progress goes straight
+// to /dev/tty and stays visible while the daemon binary downloads. Without a
+// terminal to write to -- windows, or a piped install -- the same lines go
+// to the console, where npm shows them under --foreground-scripts.
+import { openSync, writeSync } from 'node:fs';
+
+// The four shades of a Game Boy screen.
+const DARK = [15, 56, 15];
+const MID = [48, 98, 48];
+const LIGHT = [139, 172, 15];
+const BRIGHT = [155, 188, 15];
+
+// The screen is one rectangle: the card, the steps, and the closing border
+// all share this width, so every row ends on the same column.
+const INNER = 76;
+
+let handle;
+let tried = false;
+let active = null;
+let frame = 0;
+let ticker = null;
+let renderer = null;
+let framed = false;
+let lastAt = 0;
+let lastText = null;
+
+// terminal is the file descriptor of the user's terminal, or null when there
+// is none to write to.
+function terminal() {
+	if (tried) return handle;
+	tried = true;
+	if (process.platform === 'win32') return null;
+	try {
+		handle = openSync('/dev/tty', 'a');
+	} catch {
+		// No controlling terminal: the console is the only place left.
+		handle = null;
+	}
+	return handle;
+}
+
+// emit writes to the terminal and reports whether it landed there.
+function emit(text) {
+	const fd = terminal();
+	if (fd === null) return false;
+	try {
+		writeSync(fd, text);
+		return true;
+	} catch {
+		// The terminal went away mid-install; the console still works.
+		return false;
+	}
+}
+
+// paint writes a line that will be rewritten in place. Windows has no
+// /dev/tty here, so its console gets the line instead when it is a terminal.
+function paint(text) {
+	if (emit(text)) return;
+	if (process.stdout?.isTTY) process.stdout.write(text);
+}
+
+// colorEnabled reports whether the output can carry color. NO_COLOR and a
+// dumb terminal turn it off; FORCE_COLOR turns it on.
+function colorEnabled() {
+	if (process.env.NO_COLOR || process.env.FORCE_COLOR === '0') return false;
+	if (process.env.FORCE_COLOR) return true;
+	if (process.env.TERM === 'dumb') return false;
+	return terminal() !== null || Boolean(process.stdout?.isTTY);
+}
+
+function truecolor() {
+	return /^(truecolor|24bit)$/i.test(process.env.COLORTERM ?? '');
+}
+
+// shade paints text in one of the screen's greens. A terminal that speaks
+// 24-bit color gets the exact DMG shade; anything else gets the nearest
+// basic green, and no color at all stays plain.
+function shade(color, text) {
+	if (!colorEnabled()) return text;
+	if (truecolor()) {
+		return `\x1b[38;2;${color[0]};${color[1]};${color[2]}m${text}\x1b[0m`;
+	}
+	const code = color === BRIGHT ? '92' : color === LIGHT ? '32' : '2';
+	return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+const bright = (text) => shade(BRIGHT, text);
+const light = (text) => shade(LIGHT, text);
+const mid = (text) => shade(MID, text);
+
+// width counts the columns a painted line occupies, ignoring its escapes.
+function width(text) {
+	return text.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// row wraps a line in the screen's walls and pads it to the full width, so
+// every line of the screen is a rectangle of the same size.
+function row(text) {
+	if (!framed) return text;
+	const pad = Math.max(0, INNER - width(text) - 2);
+	return `${bright('│')} ${text}${' '.repeat(pad)} ${bright('│')}`;
+}
+
+// stopActivity ends the redraw timer, so a finished (or failed) download
+// never leaves one behind.
+function stopActivity() {
+	if (ticker !== null) {
+		clearInterval(ticker);
+		ticker = null;
+	}
+	renderer = null;
+}
+
+// clear wipes the line the progress bar drew on, so the next write -- a
+// step, or an error -- starts on a clean line.
+export function clear() {
+	stopActivity();
+	paint('\r\x1b[2K');
+}
+
+// rawLine clears the running line and prints one line exactly as given.
+function rawLine(text) {
+	clear();
+	active = null;
+	lastText = null;
+	if (emit(`${text}\n`)) return;
+	console.log(text);
+}
+
+// line clears the running line and prints one line, framed when the screen
+// is open.
+function line(text) {
+	rawLine(row(text));
+}
+
+// pause breathes between the lines of the screen, so it draws itself the way
+// a game's title screen comes up. The console gets no delay.
+function pause(ms = 28) {
+	return terminal() === null ? Promise.resolve() : new Promise((done) => setTimeout(done, ms));
+}
+
+// openScreen draws the top of the screen: the logo centered, the label, the
+// release details, and the rule the menu sits under. closeScreen draws the
+// bottom when the install is over.
+export async function openScreen(logo, label, details) {
+	const logoWidth = Math.max(...logo.map((text) => text.length));
+	const center = (text, paint) => {
+		const pad = Math.floor((INNER - text.length) / 2);
+		return paint(' '.repeat(pad) + text + ' '.repeat(INNER - text.length - pad));
+	};
+	const blank = () => `${bright('│')}${' '.repeat(INNER)}${bright('│')}`;
+	const card = (text, paint) => `${bright('│')}${center(text, paint)}${bright('│')}`;
+
+	framed = true;
+	rawLine(bright(`┌${'─'.repeat(INNER)}┐`));
+	await pause();
+	rawLine(blank());
+	await pause();
+	for (const text of logo) {
+		rawLine(card(text.padEnd(logoWidth), bright));
+		await pause();
+	}
+	rawLine(blank());
+	await pause();
+	rawLine(card(label, bright));
+	await pause();
+	rawLine(blank());
+	await pause();
+	for (const text of details) {
+		rawLine(card(text, light));
+		await pause();
+	}
+	rawLine(blank());
+	await pause();
+	rawLine(bright(`├${'─'.repeat(INNER)}┤`));
+}
+
+// separator draws the rule between two blocks of the screen.
+export function separator() {
+	if (!framed) return;
+	rawLine(bright(`├${'─'.repeat(INNER)}┤`));
+}
+
+// closeScreen draws the bottom border. It is safe to call when no screen is
+// open, so the error path can close whatever was drawn.
+export function closeScreen() {
+	if (!framed) return;
+	framed = false;
+	rawLine(bright(`└${'─'.repeat(INNER)}┘`));
+}
+
+// interactive reports whether there is a screen to draw and keys to read.
+export function interactive() {
+	return terminal() !== null || Boolean(process.stdin?.isTTY && process.stdout?.isTTY);
+}
+
+// choices draws a question and its option buttons on the running line. The
+// cursor stays there, so the next key redraws the same row.
+export function choices(question, labels, at) {
+	active = null;
+	lastText = null;
+	clear();
+	paint(row(`${light(question)}  ${buttons(labels, at)}`));
+}
+
+// chosen replaces the question row with the option that was picked.
+export function chosen(question, value) {
+	line(`${light('▶')} ${question} ${value}`);
+}
+
+// buttons renders the options as one row of keycaps. Every form of a label is
+// the same width, so moving the selection never shifts the row.
+export function buttons(labels, at) {
+	return labels
+		.map((label, index) => (index === at ? highlight(`▶ ${label} ◀`) : mid(`[ ${label} ]`)))
+		.join('  ');
+}
+
+// highlight paints text as the chosen menu item: bright background, dark text.
+// A terminal without 24-bit color falls back to inverse video.
+function highlight(text) {
+	if (!colorEnabled()) return text;
+	if (truecolor()) {
+		return `\x1b[48;2;${BRIGHT[0]};${BRIGHT[1]};${BRIGHT[2]}m\x1b[38;2;${DARK[0]};${DARK[1]};${DARK[2]}m${text}\x1b[0m`;
+	}
+	return `\x1b[7m${text}\x1b[0m`;
+}
+
+// selected paints the running step the way a Game Boy highlights the chosen
+// menu item: bright background, dark text. The cursor blinks and the dots
+// cycle so the chip reads as busy.
+function selected(label, tick = 0) {
+	const dots = '.'.repeat(tick % 4).padEnd(3);
+	const cursor = tick % 4 < 2 ? '▶' : '▷';
+	return highlight(` ${`${cursor} ${label}${dots}`} `);
+}
+
+// draw paints one running line, throttled so a fast download neither floods
+// the terminal with frames nor skips a percentage.
+function draw(text, force) {
+	const now = Date.now();
+	const onTerminal = terminal() !== null;
+	if (!force) {
+		if (text === lastText) return;
+		if (onTerminal ? now - lastAt < 50 : now - lastAt < 1000) return;
+	}
+	lastText = text;
+	lastAt = now;
+	const rendered = row(`${selected(active ?? '', frame)}  ${text}`);
+	if (onTerminal) {
+		emit(`\r\x1b[2K${rendered}`);
+		return;
+	}
+	console.log(rendered);
+}
+
+// step starts a step and leaves the cursor on its line. On the console the
+// running line is printed by progress() instead, so a step that never
+// reports progress leaves only its finished line behind.
+export function step(text) {
+	active = text;
+	frame = 0;
+	clear();
+	lastText = null;
+	emit(row(selected(text, 0)));
+}
+
+// done ends the running step.
+export function done(text) {
+	line(`${light('✓')} ${text}`);
+}
+
+// warn prints a step that did not go to plan but does not stop the install.
+export function warn(text) {
+	line(`${bright('!')} ${text}`);
+}
+
+// note prints something the installer did not do, such as a command to run
+// later.
+export function note(text) {
+	line(`${mid('·')} ${mid(text)}`);
+}
+
+// failed prints a failed result as the fourth block, below the closed screen.
+// It goes to stderr, where npm shows it even when a postinstall's stdout was
+// captured.
+export function failed(title, message) {
+	console.error(errorBox(title, message));
+}
+
+// errorBox renders a failure result: a red-walled block the same width as the
+// screen, the headline, and the message wrapped to fit. Exported so its shape
+// can be tested without a terminal.
+export function errorBox(title, message) {
+	const wall = red('│');
+	const rows = [red(`┌${'─'.repeat(INNER)}┐`)];
+	const add = (text, paint) => {
+		const pad = Math.max(0, INNER - width(text) - 2);
+		rows.push(`${wall} ${paint(text)}${' '.repeat(pad)} ${wall}`);
+	};
+	add(`✗ ${title}`, redBright);
+	add('', red);
+	for (const line of wrapText(message, INNER - 2)) add(line, red);
+	rows.push(red(`└${'─'.repeat(INNER)}┘`));
+	return rows.join('\n');
+}
+
+// errorColor follows the same switches as the screen but looks at stderr,
+// the stream the failure block is printed on, so a captured log stays clean
+// when stderr is not a terminal.
+function errorColor() {
+	if (process.env.NO_COLOR || process.env.FORCE_COLOR === '0') return false;
+	if (process.env.FORCE_COLOR) return true;
+	if (process.env.TERM === 'dumb') return false;
+	return Boolean(process.stderr?.isTTY);
+}
+
+const red = (text) => (errorColor() ? `\x1b[31m${text}\x1b[0m` : text);
+const redBright = (text) => (errorColor() ? `\x1b[1;31m${text}\x1b[0m` : text);
+
+// wrapText breaks a message into lines no wider than width, keeping the
+// two-space indent a hint line starts with. A word longer than a line -- a
+// path in a daemon error, say -- is split so the box walls stay aligned.
+function wrapText(text, width) {
+	const lines = [];
+	for (const paragraph of text.split('\n')) {
+		const indent = paragraph.match(/^\s*/)[0];
+		const room = Math.max(1, width - indent.length);
+		const words = paragraph.trim().split(/\s+/).filter(Boolean);
+		if (words.length === 0) {
+			lines.push('');
+			continue;
+		}
+		let line = '';
+		for (const word of words) {
+			let rest = word;
+			while (rest.length > room) {
+				if (line !== '') {
+					lines.push(indent + line);
+					line = '';
+				}
+				lines.push(indent + rest.slice(0, room));
+				rest = rest.slice(room);
+			}
+			if (rest === '') continue;
+			if (line !== '' && line.length + 1 + rest.length > room) {
+				lines.push(indent + line);
+				line = rest;
+			} else line = line === '' ? rest : `${line} ${rest}`;
+		}
+		if (line !== '') lines.push(indent + line);
+	}
+	return lines;
+}
+
+// progress starts a running line. render is called with a frame number and
+// returns the text, so the line can keep moving -- the bar's shade, the
+// blinking cursor -- even while no bytes arrive. A terminal redraws it at
+// most twenty times a second; the console prints it once a second instead,
+// since there the output is a log rather than a redrawn line. force draws
+// the frame that ends a download.
+export function progress(render, { force = false } = {}) {
+	renderer = render;
+	draw(render(frame), force);
+	if (ticker !== null || terminal() === null) return;
+	// Unreferenced: an animation must never be the reason an install hangs.
+	ticker = setInterval(() => {
+		if (renderer === null) return;
+		frame += 1;
+		draw(renderer(frame), true);
+	}, 90);
+	ticker.unref();
+}
+
+// bar renders a fraction of a whole as a fixed width block bar. Every filled
+// cell is the same full block, so the bar stays a clean rectangle; a frame
+// only moves the shade across those blocks, which keeps it moving even on a
+// stalled connection. color dims the track.
+export function bar(fraction, { width: cells = 24, color = false, frame: tick } = {}) {
+	const filled = Math.max(0, Math.min(cells, Math.round(fraction * cells)));
+	const track = '░'.repeat(cells - filled);
+	if (!color || !colorEnabled()) return `${'█'.repeat(filled)}${track}`;
+	let paint = '';
+	for (let index = 0; index < filled; index += 1) {
+		paint += tick !== undefined && (index + tick) % 6 > 3 ? light('█') : bright('█');
+	}
+	return `${paint}${mid(track)}`;
+}
+
+// bytes renders a byte count the way a person reads it.
+export function bytes(count) {
+	if (count < 1024) return `${count} B`;
+	if (count < 1024 * 1024) return `${(count / 1024).toFixed(1)} KB`;
+	return `${(count / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// duration renders an elapsed time the way a person reads it.
+export function duration(ms) {
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const seconds = ms / 1000;
+	if (seconds < 60) return `${seconds.toFixed(1)}s`;
+	return `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jonaskahn/relo",
-	"version": "0.1.4-beta.27.8d9c8af7",
+	"version": "0.1.4",
 	"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",
@@ -47,6 +47,7 @@
 		"lib/download.mjs",
 		"lib/install.mjs",
 		"lib/platform.mjs",
+		"lib/progress.mjs",
 		"lib/release.mjs",
 		"lib/uninstall.mjs",
 		"README.md"