@runeditrun/rer 0.0.0-stage → 0.1.1

package/global/cli/layout.mjs

@@ -0,0 +1,45 @@
+// Where a user install lives. Data: ${XDG_DATA_HOME:-$HOME/.local/share}/rer,
+// as immutable versions/<version>-<digest8> directories and a `current` link.
+// Launcher: $HOME/.local/bin/rer, a POSIX sh script that runs node from PATH.
+import { readFile, lstat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function layout(env = process.env) {
+ const home = env.HOME || homedir();
+ const data = join(env.XDG_DATA_HOME || join(home, '.local/share'), 'rer');
+ const bin = join(home, '.local/bin');
+ return { home, data, versions: join(data, 'versions'), current: join(data, 'current'), record: join(data, 'install.json'), bin, launcher: join(bin, 'rer') };
+}
+
+const marker = '# rer launcher, written by `rer cli install` (@runeditrun/rer). Do not edit.';
+const quote = value => `'${value.replaceAll("'", `'\\''`)}'`;
+
+// No absolute Node path is baked in, so a Node upgrade never breaks it.
+export function launcherScript(data) {
+ return `#!/bin/sh
+${marker}
+# It runs the installed version with the node on PATH.
+root=${quote(data)}
+if ! command -v node >/dev/null 2>&1; then
+ echo "rer: node is not on PATH. Install Node 22 or later, then run rer again." >&2
+ exit 127
+fi
+exec node "$root/current/global/rer.mjs" "$@"
+`;
+}
+
+// 'absent', 'ours' (with the install root it runs), or 'foreign'.
+export async function launcherOwner(path) {
+ let info;
+ try { info = await lstat(path); } catch (error) { if (error.code === 'ENOENT') return { state: 'absent' }; throw error; }
+ if (!info.isFile()) return { state: 'foreign' };
+ const text = await readFile(path, 'utf8');
+ if (text.split('\n')[1] !== marker) return { state: 'foreign' };
+ const root = /^root='((?:[^']|'\\'')*)'$/m.exec(text)?.[1]?.replaceAll(`'\\''`, "'");
+ return { state: 'ours', root, text };
+}
+
+export async function installRecord(paths) {
+ try { return JSON.parse(await readFile(paths.record, 'utf8')); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+}

package/global/cli/status.mjs

@@ -0,0 +1,54 @@
+// rer cli status: what this rer is and every other rer on PATH.
+import { access, constants, realpath } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { ownManifest, ownRoot, packageDigest } from '../package-info.mjs';
+import { installRecord, launcherOwner, layout } from './layout.mjs';
+
+const inside = (path, root) => path === root || path.startsWith(root + sep);
+async function real(path) { try { return await realpath(path); } catch { return undefined; } }
+
+export async function channelOf(paths) {
+ const data = await real(paths.data);
+ if (data && inside(ownRoot, join(data, 'versions'))) return { channel: (await installRecord(paths))?.channel ?? 'npx', root: data };
+ if (ownRoot.split(sep).includes('_npx')) return { channel: 'npx', root: ownRoot };
+ if (ownRoot.endsWith(join('node_modules', '@runeditrun', 'rer'))) return { channel: 'npm-global', root: ownRoot };
+ return { channel: 'source', root: ownRoot };
+}
+
+// Every executable `rer` on PATH except the ones that run this very install.
+export async function pathCommands(installRoot, env = process.env) {
+ const seen = new Set(), self = [], others = [];
+ for (const directory of (env.PATH ?? '').split(':').filter(Boolean)) {
+  const candidate = resolve(directory, 'rer');
+  if (seen.has(candidate)) continue;
+  seen.add(candidate);
+  try { await access(candidate, constants.X_OK); } catch { continue; }
+  const target = await real(candidate);
+  const launcher = await launcherOwner(candidate);
+  if (target && inside(target, ownRoot) || launcher.state === 'ours' && launcher.root && await real(launcher.root) === installRoot) self.push(candidate);
+  else others.push(candidate);
+ }
+ return { self, others };
+}
+
+export async function status({ json }) {
+ const paths = layout(), manifest = ownManifest(), { channel, root } = await channelOf(paths);
+ const launcher = await launcherOwner(paths.launcher), commands = await pathCommands(root);
+ const result = {
+  version: manifest.version,
+  digest: await packageDigest(ownRoot),
+  channel,
+  launcher: channel === 'npm-global' ? commands.self[0] ?? null : launcher.state === 'ours' ? paths.launcher : null,
+  root,
+  others: commands.others,
+ };
+ if (json) process.stdout.write(JSON.stringify(result) + '\n');
+ else process.stdout.write([
+  `rer ${result.version} (${result.channel})`,
+  `digest:   ${result.digest}`,
+  `root:     ${result.root}`,
+  `launcher: ${result.launcher ?? '(none)'}`,
+  `others on PATH: ${result.others.length ? '\n  ' + result.others.join('\n  ') : '(none)'}`,
+ ].join('\n') + '\n');
+ return 0;
+}

package/global/cli/uninstall.mjs

@@ -0,0 +1,36 @@
+// rer cli uninstall: remove the user install (the launcher `rer cli install`
+// wrote and the install root it runs), and nothing else. ~/.rer (servers, jobs,
+// Node runtimes) is untouched, and so is any folder that is not a rer install
+// root. An npm global rer leaves other channels' installs alone.
+import { lstat, readlink, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { launcherOwner, layout } from './layout.mjs';
+import { channelOf } from './status.mjs';
+
+// A folder `rer cli install` made: a versions/ directory and a `current` link into it.
+async function installRoot(path) {
+ try {
+  if (!(await lstat(join(path, 'versions'))).isDirectory()) return false;
+  return /^versions\/[^/]+$/.test(await readlink(join(path, 'current')));
+ } catch { return false; }
+}
+
+export async function uninstall() {
+ const paths = layout(), { channel } = await channelOf(paths), launcher = await launcherOwner(paths.launcher), lines = [];
+ // The root the launcher runs; with no launcher, the layout's own root.
+ const root = launcher.state === 'ours' && launcher.root ? launcher.root : paths.data;
+ const user = launcher.state === 'ours' || await installRoot(root);
+ if (channel === 'npm-global') {
+  lines.push('This rer came from npm; remove it with: npm uninstall -g @runeditrun/rer');
+  if (user) lines.push(`A user install is also present${launcher.state === 'ours' ? ` (${paths.launcher})` : ` (${root})`}; remove it with: ${launcher.state === 'ours' ? paths.launcher : 'npx -y @runeditrun/rer'} cli uninstall`);
+  process.stdout.write(lines.join('\n') + '\n');
+  return 0;
+ }
+ if (launcher.state === 'ours') { await rm(paths.launcher); lines.push(`Removed ${paths.launcher}.`); }
+ else if (launcher.state === 'foreign') lines.push(`Left ${paths.launcher} in place: rer cli install did not write it.`);
+ if (await installRoot(root)) { await rm(root, { recursive: true, force: true }); lines.push(`Removed ${root}.`); }
+ else if (launcher.state === 'ours') lines.push(`Left ${root} in place: it is not a rer install root.`);
+ if (!lines.length) lines.push('No user install of rer was found; nothing changed.');
+ process.stdout.write(lines.join('\n') + '\n');
+ return 0;
+}

package/global/delegate.mjs

@@ -0,0 +1,13 @@
+// Run an invocation with the checkout's own dispatcher, in this process, exactly
+// as `node scripts/rer.mjs ...` would from the project root: process.argv[1] is
+// that file, so its Node-pin re-exec and queued child spawns behave as they do
+// when it is run directly. The dispatcher sets process.exitCode itself.
+import { pathToFileURL } from 'node:url';
+import { dispatcher } from './checkout.mjs';
+
+export async function delegate(target, args) {
+ const { entry } = dispatcher(target.root);
+ if (target.root) process.chdir(target.root);
+ process.argv = [process.argv[0], entry, ...args];
+ await import(pathToFileURL(entry).href);
+}

package/global/launch/capacity.mjs

@@ -0,0 +1,72 @@
+// Person defaults and the server-limit check, applied by the launcher on every
+// pin. A pin from before Base's person defaults (2 servers, 1800 s, and a cap
+// set by the lowest limit any running server recorded) gets 10 servers and 12
+// hours unless the person chose otherwise. The 1-minute-load guard belongs to
+// the fleet's own environment: a person's start never waits or is refused for
+// load alone, so an unset threshold becomes an unbounded one for old pins.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { liveServers, stopCommand } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
+
+export const personDefaults = { limit: 10, idleSeconds: 43200 };
+const unboundedLoad = '1000000';
+// The verbs that start a server or enter the job queue on every pin.
+export const personVerbs = new Set(['dev', 'preview', 'install', 'setup', 'build', 'verify', 'deploy', 'export', 'import']);
+
+// How the pinned dispatcher counts servers, and which person defaults it lacks.
+// describe's `defaults` (from rer-cli-2) is authoritative: the launcher supplies
+// a person default only where the pin's own is lower, so a current pin never
+// records a limit nobody set. Before it, a pin whose registry exports its
+// default limit already has the person defaults and binds only explicit limits;
+// older pins have neither.
+export async function pinPolicy(root, mode, described) {
+ const own = described?.defaults;
+ if (own) return { supply: { limit: !(own.serverLimit >= personDefaults.limit), idle: !(own.idleSeconds >= personDefaults.idleSeconds) }, explicitOnly: true, limit: own.serverLimit ?? personDefaults.limit };
+ if (mode !== 'vendored') return { supply: { limit: false, idle: false }, explicitOnly: true, limit: personDefaults.limit };
+ const registry = join(root, 'scripts/base-cli/cli/server-registry.mjs');
+ const exported = existsSync(registry) ? await import(pathToFileURL(registry).href) : {};
+ return 'defaultServerLimit' in exported
+  ? { supply: { limit: false, idle: false }, explicitOnly: true, limit: exported.defaultServerLimit }
+  : { supply: { limit: true, idle: true }, explicitOnly: false, limit: 2 };
+}
+
+export function personEnvironment(env, args, pin) {
+ const added = {};
+ if (pin.supply.limit && env.RER_SERVER_LIMIT === undefined) added.RER_SERVER_LIMIT = String(personDefaults.limit);
+ if (pin.supply.idle && env.RER_SERVER_IDLE_SECONDS === undefined && !args.includes('--idle-timeout')) added.RER_SERVER_IDLE_SECONDS = String(personDefaults.idleSeconds);
+ if (env.RER_SERVERS_LOAD_THRESHOLD === undefined) added.RER_SERVERS_LOAD_THRESHOLD = unboundedLoad;
+ if (env.RER_JOBS_LOAD_THRESHOLD === undefined) added.RER_JOBS_LOAD_THRESHOLD = unboundedLoad;
+ return added;
+}
+
+const listing = record => `  ${record.mode} on port ${record.port ?? '(starting)'} in ${record.checkout} (PID ${record.owner?.pid})\n    stop it with: ${stopCommand(record)}`;
+
+// Refuse in seconds, before any install or setup, when the pinned dispatcher
+// would refuse the start for the server limit. Returns this checkout's own
+// running server when there is one.
+export async function checkCapacity(checkout, env, pin) {
+ const running = await liveServers(env);
+ const own = running.find(record => record.checkout === checkout);
+ if (own) return { own };
+ if (env.RER_SERVER_JOURNEY === '1') return {};
+ const counted = running.filter(record => !record.journey);
+ const limit = Number(env.RER_SERVER_LIMIT ?? pin.limit);
+ const binding = pin.explicitOnly ? counted.filter(record => record.explicit) : counted;
+ const cap = Math.min(limit, ...binding.map(record => record.limit));
+ if (counted.length < cap) return {};
+ const holders = cap < limit ? binding.filter(record => record.limit === cap) : [];
+ if (holders.length) throw new LaunchFailure(4, [
+  `Not started: ${holders.length === 1 ? 'a server' : 'servers'} started with a limit of ${cap} hold${holders.length === 1 ? 's' : ''} this checkout's rer copy to ${cap} running servers, and ${counted.length} ${counted.length === 1 ? 'is' : 'are'} running:`,
+  ...holders.map(record => `  ${record.mode} for ${record.checkout} (PID ${record.owner?.pid})`),
+  `Restart ${holders.length === 1 ? 'it' : 'each'} under rer, which records ${personDefaults.limit} servers:`,
+  ...holders.flatMap(record => [`  rer ${record.mode} --stop --cwd ${JSON.stringify(record.checkout)}`, `  rer ${record.mode} --cwd ${JSON.stringify(record.checkout)}`]),
+  'rer never stops another checkout\'s server itself.',
+ ].join('\n'));
+ throw new LaunchFailure(4, [
+  `Not started: ${counted.length} dev or preview ${counted.length === 1 ? 'server is' : 'servers are'} running on this computer and the limit is ${cap}.`,
+  'Running now:', ...counted.map(listing),
+  `To make room, stop one with its command above, or start this one with a higher limit, for example RER_SERVER_LIMIT=${cap * 2} rer dev.`,
+ ].join('\n'));
+}

package/global/launch/dev.mjs

@@ -0,0 +1,117 @@
+// Zero-setup `rer dev` for a first-party checkout. With stdout not a terminal
+// (an agent's shell tool) the preparation and start run in a detached worker
+// and this command returns once the app is ready, leaving it running; in a
+// terminal it stays in the foreground as the dispatcher's own dev does.
+// --detach and --foreground override the choice.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createWriteStream, existsSync } from 'node:fs';
+import { open, realpath, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dispatcher } from '../checkout.mjs';
+import { delegate } from '../delegate.mjs';
+import { ownRoot } from '../package-info.mjs';
+import { LaunchFailure } from './failure.mjs';
+import { prepare } from './prepare.mjs';
+import { printer } from './render.mjs';
+import { stopLaunch } from './stop.mjs';
+import { launchDirectory, liveWorker } from './state.mjs';
+
+const workerPath = fileURLToPath(new URL('./worker.mjs', import.meta.url));
+
+export async function launchDev(target) {
+ const args = target.args.slice(1);
+ if (args.includes('--detach') && args.includes('--foreground')) { process.stderr.write('Choose one of --detach and --foreground.\n'); return 2; }
+ const devArgs = args.filter(arg => arg !== '--detach' && arg !== '--foreground');
+ // An invocation the pinned dispatcher refuses goes straight to it, so the
+ // refusal is its own, with nothing prepared first.
+ if (!await accepted(target.root, devArgs)) return delegate(target, ['dev', ...devArgs]);
+ const checkout = await realpath(target.root), directory = await launchDirectory(checkout);
+ if (devArgs.includes('--stop')) {
+  try { return await stopLaunch(target, devArgs, { checkout, directory }); }
+  catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
+ }
+ const here = await realpath(process.cwd()).catch(() => undefined);
+ const out = printer({ json: devArgs.includes('--json'), login: devArgs.includes('--login'), stopHint: `rer dev --stop${here === checkout ? '' : ` --cwd ${JSON.stringify(checkout)}`}` });
+ const detach = args.includes('--detach') || (!args.includes('--foreground') && !process.stdout.isTTY);
+ return detach ? detached(target, devArgs, directory, out) : foreground(target, devArgs, directory, out);
+}
+
+async function accepted(root, devArgs) {
+ const parser = dispatcher(root).mode === 'vendored' ? join(root, 'scripts/base-cli/cli/parse.mjs') : join(ownRoot, 'cli/parse.mjs');
+ if (!existsSync(parser)) return true;
+ try { (await import(pathToFileURL(parser).href)).parse(['dev', ...devArgs], process.cwd()); return true; } catch { return false; }
+}
+
+async function foreground(target, devArgs, directory, out) {
+ const holder = await liveWorker(directory);
+ if (holder) {
+  out.attaching(holder.startedAt);
+  const code = await follow(directory, holder.token, out, { quiet: true });
+  if (code !== 0) return code;
+ }
+ const log = createWriteStream(join(directory, 'launch.log'), { flags: 'a', mode: 0o600 });
+ let prepared;
+ // The same progress lines as a detached launch while install or setup runs.
+ const heartbeat = setInterval(() => out.heartbeat(), 1000);
+ try { prepared = await prepare({ root: target.root, args: devArgs, env: process.env, report: fields => out.phase(fields), directory, log: text => log.write(text + '\n'), children: new Set() }); }
+ catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; out.failure(failure); return failure.exitCode; }
+ finally { clearInterval(heartbeat); log.end(); }
+ Object.assign(process.env, prepared.added);
+ return delegate(target, ['dev', ...devArgs]);
+}
+
+async function detached(target, devArgs, directory, out) {
+ let token, worker;
+ const holder = await liveWorker(directory);
+ if (holder) { token = holder.token; out.attaching(holder.startedAt); }
+ else {
+  token = randomUUID();
+  // The worker ends itself for a stop that ran after this command started.
+  worker = spawn(process.execPath, [workerPath, target.root, token, JSON.stringify(devArgs.filter(arg => arg !== '--json')), String(performance.timeOrigin)], { cwd: target.root, env: process.env, detached: true, stdio: 'ignore' });
+  worker.unref();
+ }
+ return follow(directory, token, out, { worker });
+}
+
+// Print a worker's events until it is ready or has failed. A redirect means
+// another worker already held this checkout's launch; follow that one.
+async function follow(directory, token, out, { worker, quiet = false }) {
+ const path = join(directory, `events-${token}.jsonl`);
+ let offset = 0, rest = '', exited = false, missingSince, polls = 0;
+ worker?.once('exit', () => { exited = true; });
+ for (;;) {
+  let size = 0;
+  try { size = (await stat(path)).size; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (size > offset) {
+   const handle = await open(path, 'r');
+   try { const { buffer, bytesRead } = await handle.read({ buffer: Buffer.alloc(size - offset), position: offset }); offset += bytesRead; rest += buffer.subarray(0, bytesRead).toString('utf8'); }
+   finally { await handle.close(); }
+   const lines = rest.split('\n'); rest = lines.pop();
+   for (const line of lines) {
+    const event = JSON.parse(line);
+    if (event.event === 'phase') out.phase(event);
+    else if (event.event === 'redirect') return event.token ? follow(directory, event.token, out, { quiet }) : missing(directory);
+    else if (event.event === 'ready') { if (!quiet) out.ready(event.ready, event); return 0; }
+    else if (event.event === 'failed') { out.failure(new LaunchFailure(event.exitCode, event.message, event.error)); return event.exitCode; }
+   }
+   continue;
+  }
+  // No terminal event: is the worker still there? (checked about once a second)
+  const gone = worker ? exited : (polls++ % 4 === 0 ? (await liveWorker(directory))?.token !== token : false);
+  if (gone || missingSince) {
+   missingSince ??= Date.now();
+   // Let a just-finished worker's last write land before calling it lost.
+   if (Date.now() - missingSince > 1000) return missing(directory);
+  }
+  out.heartbeat();
+  await delay(250);
+ }
+}
+
+function missing(directory) {
+ process.stderr.write(`rer dev: the launch stopped before it finished. Run rer dev again; its log is ${join(directory, 'launch.log')}.\n`);
+ return 1;
+}

package/global/launch/facts.mjs

@@ -0,0 +1,94 @@
+// What a launch needs to know about a checkout before it changes anything.
+import { execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { listeningPorts } from '../../onboarding/process-diagnostics.mjs';
+import { LaunchFailure } from './failure.mjs';
+
+const run = promisify(execFile);
+async function mtime(path) { try { return (await stat(path)).mtimeMs; } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; } }
+
+// The pinned dispatcher's own read-only description.
+export async function describeCheckout(root, entry, env, signal) {
+ try {
+  const { stdout } = await run(process.execPath, [entry, 'describe', '--json'], { cwd: root, env, maxBuffer: 16 * 1024 * 1024, signal });
+  return JSON.parse(stdout);
+ } catch (error) {
+  if (signal?.aborted) throw signal.reason;
+  throw new LaunchFailure(error.code ?? 1, (error.stderr?.trim() || `rer describe failed in ${root}.`));
+ }
+}
+
+// Install when the last install did not finish or the lockfile changed since.
+// pnpm writes node_modules/.modules.yaml only once dependencies are linked and
+// built, so a stopped install leaves it absent. An install this launcher ran
+// is finished only when its record says so: that also covers the project's
+// own install hooks, which pnpm runs after writing the manifest.
+export async function needsInstall(root, last) {
+ if (last && last.state !== 'done') return true;
+ const manifest = await mtime(join(root, 'node_modules/.modules.yaml'));
+ if (manifest === undefined) return true;
+ const lock = await mtime(join(root, 'pnpm-lock.yaml'));
+ return lock !== undefined && Math.max(manifest, last?.at ?? 0) < lock;
+}
+
+// A checkout is set up when its pin's describe says so (`local.prepared`, from
+// rer-cli-2); for older pins, when its primary private settings file holds
+// anything. The pin's describe names it (`local.settings`, where the pin has it).
+export async function hasSettings(root, described) {
+ if (typeof described?.local?.prepared === 'boolean') return described.local.prepared;
+ const primary = described?.local?.settings?.[0] ?? '.dev.vars';
+ try { return (await stat(join(root, primary))).size > 0; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+// Every pin's setup saves its answers file only once it has finished, so a
+// file newer than this launcher's record of its own attempt (its start for
+// 'running', its end for 'failed') is a setup that finished after it.
+async function finishedSince(root, described, at) {
+ const saved = await mtime(join(root, described?.local?.installerState ?? '.seed/installer', 'setup-answers.json'));
+ return saved !== undefined && typeof at === 'number' && saved > at;
+}
+
+// Setup runs on a checkout with no saved settings ('fresh'). When a setup this
+// launcher started did not finish ('running' after a kill, or 'failed') and no
+// setup has finished since, it runs again ('resume') and keeps what the earlier
+// attempt saved. A checkout set up any other way is never set up again.
+// A checkout that is not prepared but already holds an owner (a setting a newer
+// manifest added is missing) resumes too, so the saved owner and origin are
+// kept; one without a saved owner gets the local owner ('fresh').
+export async function setupNeeded(root, described, last) {
+ if (!await hasSettings(root, described)) return described?.local?.ownerSaved === true ? 'resume' : 'fresh';
+ if (!last || last.state === 'done') return undefined;
+ return await finishedSince(root, described, last.at) ? undefined : 'resume';
+}
+
+export function localOwner(root) {
+ const label = basename(root).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 63) || 'checkout';
+ return `owner@${label}.test`;
+}
+
+async function bindable(host, port) {
+ const socket = createServer();
+ try { await new Promise((resolve, reject) => { socket.once('error', reject); socket.listen({ port, host, exclusive: true }, resolve); }); return true; }
+ catch (error) { return host === '::1' && ['EADDRNOTAVAIL', 'EAFNOSUPPORT'].includes(error.code); }
+ finally { if (socket.listening) await new Promise(resolve => socket.close(resolve)); }
+}
+
+// The first port from 8787 (RER_DEV_PORT_FROM moves the start) that no
+// registered server holds, nothing listens on, binds on both 127.0.0.1 and ::1
+// (a browser that tries ::1 first never reaches another server) and that
+// `claim` secures against another launch choosing it at the same time.
+export async function freePort(servers, claim, env = process.env) {
+ const from = Number(env.RER_DEV_PORT_FROM ?? 8787);
+ if (!Number.isInteger(from) || from < 1 || from > 65535) throw new LaunchFailure(2, 'RER_DEV_PORT_FROM must be a port number.');
+ const held = new Set(servers.map(record => record.port).filter(Boolean)), busy = await listeningPorts();
+ for (let port = from; port <= 65535; port++) {
+  if (held.has(port) || busy.has(port)) continue;
+  if (!await bindable('127.0.0.1', port) || !await bindable('::1', port)) continue;
+  const claimed = await claim(port);
+  if (claimed) return { port, ...claimed };
+ }
+ throw new LaunchFailure(4, `No free port from ${from} upward. Pass one with rer dev --port PORT.`);
+}

package/global/launch/failure.mjs

@@ -0,0 +1,5 @@
+// A launch that stops with the dispatcher's own message (or the launcher's)
+// and exit code. `event` keeps the dispatcher's JSON error event when it sent one.
+export class LaunchFailure extends Error {
+ constructor(exitCode, message, event) { super(message); this.exitCode = exitCode; this.event = event; }
+}

package/global/launch/local-defaults.mjs

@@ -0,0 +1,4 @@
+// Set only for the setup a zero-setup `rer dev` runs: that setup fills each
+// field's declared localDefault (rer-setup.json). Pins from before local
+// defaults ignore it.
+export const localDefaults = 'RER_SETUP_LOCAL_DEFAULTS';

package/global/launch/prepare.mjs

@@ -0,0 +1,63 @@
+// Zero-setup preparation, composed only of the pinned dispatcher's public
+// verbs so it works on every pin: limit check, install when needed, setup with
+// local answers when the checkout is not set up. It never prompts and never
+// runs setup on a checkout that is set up, so a saved owner, origin or private
+// settings are never changed. An install or setup this launcher started and
+// that did not finish runs again on the next launch.
+import { realpath } from 'node:fs/promises';
+import { dispatcher } from '../checkout.mjs';
+import { liveServers } from '../registry.mjs';
+import { checkCapacity, personEnvironment, pinPolicy } from './capacity.mjs';
+import { describeCheckout, freePort, localOwner, needsInstall, setupNeeded } from './facts.mjs';
+import { claimPort, installState, setupState } from './state.mjs';
+import { runVerb } from './steps.mjs';
+import { localDefaults } from './local-defaults.mjs';
+
+// The value given for a flag in the user's dev arguments.
+export const flagValue = (args, flag) => { const index = args.indexOf(flag); return index < 0 ? undefined : args[index + 1]; };
+
+// A worker passes the signal a stop aborts: no step starts after it, and the
+// step running then is signalled through `children`.
+export async function prepare({ root, args, env, report, directory, log, children, signal }) {
+ const checkout = await realpath(root), { mode, entry } = dispatcher(root);
+ const described = await describeCheckout(root, entry, env, signal);
+ const pin = await pinPolicy(root, mode, described);
+ const added = personEnvironment(env, args, pin), childEnv = { ...env, ...added };
+ report({ phase: 'check', message: 'checking the server limit' });
+ const capacity = await checkCapacity(checkout, childEnv, pin);
+ if (capacity.own) return { entry, added, own: capacity.own };
+ const note = message => report({ phase: 'note', message });
+ const step = (record, args, fields, env = childEnv) => recorded(directory, record, () => runVerb(entry, args, { root, env, note, log, children, signal }), fields);
+ // Only this setup fills the seed's declared local defaults.
+ const setupEnv = { ...childEnv, [localDefaults]: '1' };
+ if (await needsInstall(root, await installState.read(directory))) {
+  report({ phase: 'install', message: 'installing dependencies' });
+  await step(installState, ['install']);
+ }
+ const last = await setupState.read(directory), setup = await setupNeeded(root, described, last);
+ const host = flagValue(args, '--host'), hostArgs = host ? ['--host', host] : [];
+ if (setup === 'resume') {
+  // Saved settings hold an owner and origin; setup keeps them.
+  report({ phase: 'setup', message: 'finishing this checkout\'s setup, keeping its saved owner and port' });
+  await step(setupState, ['setup', ...hostArgs], {}, setupEnv);
+ } else if (setup === 'fresh') {
+  // An interrupted setup resumes on the port it chose while that port is free.
+  const owner = localOwner(checkout), explicit = flagValue(args, '--port');
+  const { port, release } = explicit ? { port: Number(explicit) } : await freePort(await liveServers(childEnv), port => claimPort(port, childEnv), last?.port ? { ...childEnv, RER_DEV_PORT_FROM: String(last.port) } : childEnv);
+  report({ phase: 'setup', message: `setting up a local owner (${owner}) on port ${port}` });
+  try { await step(setupState, ['setup', '--owner-email', owner, '--port', String(port), ...hostArgs], { port, owner }, setupEnv); }
+  catch (failure) { await release?.(); throw failure; }
+  // The claim lasts until the server registers the port: the caller releases it.
+  return { entry, added, release };
+ }
+ return { entry, added };
+}
+
+// Run one step with its record: 'running' while it runs (left so by a killed
+// process), then 'done' or 'failed'.
+async function recorded(directory, record, run, fields = {}) {
+ await record.write(directory, { state: 'running', ...fields });
+ let state = 'failed';
+ try { await run(); state = 'done'; }
+ finally { await record.write(directory, { state, ...fields }); }
+}

package/global/launch/render.mjs

@@ -0,0 +1,44 @@
+// What `rer dev` prints while it launches: a progress line at least every 30
+// seconds (a `progress` event with --json), then the dispatcher's ready lines.
+const elapsed = ms => { const s = Math.round(ms / 1000); return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`; };
+const quiet = 20000;
+
+export function printer({ json, login, stopHint }) {
+ const started = Date.now();
+ let current = 'preparing', last = Date.now();
+ const event = (name, fields) => process.stdout.write(JSON.stringify({ version: 1, verb: 'dev', event: name, ...fields }) + '\n');
+ const line = text => process.stderr.write(`rer dev: ${text}\n`);
+ const progress = (phase, message) => {
+  last = Date.now();
+  if (json) event('progress', { phase, message, elapsedSeconds: Math.round((last - started) / 1000) });
+  else line(message);
+ };
+ return {
+  phase({ phase, message }) { if (phase !== 'note') current = message; progress(phase, message); },
+  attaching(startedAt) { progress('attach', `attaching to the launch already preparing this checkout (started ${elapsed(Date.now() - startedAt)} ago)`); },
+  heartbeat() { if (Date.now() - last >= quiet) progress('waiting', `still ${current} (${elapsed(Date.now() - started)}). Allow up to 10 minutes; if this command is stopped, run rer dev again to reattach.`); },
+  // The dispatcher's ready event, as its own human ready lines.
+  ready(ready, { log, pid }) {
+   if (json) { event('server', { pid, log }); process.stdout.write(JSON.stringify(ready) + '\n'); return; }
+   const out = [`RER_READY ${ready.url}`];
+   if (ready.openUrl && !login) {
+    if (ready.signedInAs) out.push(`RER_SIGNED_IN ${ready.signedInAs}`);
+    out.push(`RER_OPEN ${ready.openUrl}`, 'Open that link on this computer. Its fragment holds this checkout\'s dev key, which the page keeps only as a cookie; never share the link.');
+   } else if (ready.signInUrl) {
+    out.push(`RER_SIGN_IN ${ready.signInUrl}`);
+    if (ready.openUrl) out.push(`RER_OPEN ${ready.openUrl}`);
+    out.push(`Open ${ready.openUrl ? 'the last link on this computer (it carries the dev key; never share it)' : 'the outbox'}, choose the newest sign-in message and follow its link. No email was sent.`);
+   }
+   out.push(`The server keeps running in the background${pid ? ` (PID ${pid})` : ''}. Stop it with: ${stopHint}`);
+   if (log) out.push(`Server log (private): ${log}`);
+   process.stdout.write(out.join('\n') + '\n');
+  },
+  failure(failure) {
+   if (json) {
+    if (failure.event) process.stdout.write(JSON.stringify(failure.event) + '\n');
+    else event('error', { code: 'launch_refused', message: failure.message, exitCode: failure.exitCode });
+    event('result', { ok: false, exitCode: failure.exitCode });
+   } else process.stderr.write(failure.message + '\n');
+  },
+ };
+}