@runeditrun/rer 0.0.0-stage → 0.1.1

package/global/launch/state.mjs

@@ -0,0 +1,106 @@
+// Per-checkout launch state, private to the account, beside the server
+// registry: <servers>/launches/<name>-<hash>/
+//   worker.json   the preparing worker (PID, start time, token) while it runs
+//   events-<token>.jsonl  what that worker has done, one JSON event per line
+//   install.json  whether an install this launcher started has finished
+//   setup.json    whether a setup this launcher started has finished
+//   launch.log    the worker's private log (child output)
+//   server.log    the private log of the server rer started
+//   server.json   that server's PID and start time, and the process rer spawned
+//   stop.json     when rer dev --stop last ran: a launch requested before it stops
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { serversDirectory } from '../registry.mjs';
+
+export function launchPath(checkout, env = process.env) {
+ const name = basename(checkout).toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 40) || 'checkout';
+ return join(serversDirectory(env), 'launches', `${name}-${createHash('sha256').update(checkout).digest('hex').slice(0, 12)}`);
+}
+
+export async function launchDirectory(checkout, env = process.env) {
+ const directory = launchPath(checkout, env);
+ await mkdir(directory, { recursive: true, mode: 0o700 });
+ return directory;
+}
+
+async function readJson(path) { try { return JSON.parse(await readFile(path, 'utf8')); } catch (error) { if (error.code === 'ENOENT' || error instanceof SyntaxError) return undefined; throw error; } }
+
+async function live(holder) {
+ if (!holder?.pid) return false;
+ const current = await processInfo(holder.pid);
+ return Boolean(current && !current.zombie && current.start === holder.start);
+}
+
+export async function liveWorker(directory) {
+ const holder = await readJson(join(directory, 'worker.json'));
+ return await live(holder) ? holder : undefined;
+}
+
+// A port chosen for a setup stays claimed while the process that chose it
+// lives, so two launches preparing at once never pick the same port.
+export async function claimPort(port, env = process.env) {
+ const directory = join(serversDirectory(env), 'launches', 'ports'), path = join(directory, `${port}.json`);
+ await mkdir(directory, { recursive: true, mode: 0o700 });
+ const { start } = await processInfo(process.pid);
+ for (let attempt = 0; attempt < 2; attempt++) {
+  try {
+   await writeFile(path, JSON.stringify({ pid: process.pid, start }), { flag: 'wx', mode: 0o600 });
+   return { release: async () => { if ((await readJson(path))?.pid === process.pid) await rm(path, { force: true }); } };
+  } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  if (await live(await readJson(path))) return undefined;
+  await rm(path, { force: true });
+ }
+ return undefined;
+}
+
+// The worker claims the checkout's launch; a second worker started at the
+// same moment finds the first and leaves.
+export async function claimLaunch(directory, token) {
+ const path = join(directory, 'worker.json');
+ for (let attempt = 0; attempt < 3; attempt++) {
+  const { start } = await processInfo(process.pid);
+  try {
+   await writeFile(path, JSON.stringify({ token, pid: process.pid, start, startedAt: Date.now(), events: `events-${token}.jsonl` }), { flag: 'wx', mode: 0o600 });
+   for (const entry of await readdir(directory)) if (/^events-.*\.jsonl$/.test(entry) && entry !== `events-${token}.jsonl`) await rm(join(directory, entry), { force: true });
+   return true;
+  } catch (error) {
+   if (error.code !== 'EEXIST') throw error;
+   if (await liveWorker(directory)) return false;
+   await rm(path, { force: true });
+  }
+ }
+ return false;
+}
+
+export async function releaseLaunch(directory, token) {
+ const holder = await readJson(join(directory, 'worker.json'));
+ if (holder?.token === token) await rm(join(directory, 'worker.json'), { force: true });
+}
+
+export function eventLog(directory, token) {
+ const path = join(directory, `events-${token}.jsonl`);
+ return { path, write: event => appendFile(path, JSON.stringify({ at: Date.now(), ...event }) + '\n', { mode: 0o600 }) };
+}
+
+// { state: 'running' | 'done' | 'failed', ... } for the last install or setup
+// this launcher ran. 'running' survives only a step whose process was killed.
+const stepRecord = name => ({
+ read: directory => readJson(join(directory, `${name}.json`)),
+ write: (directory, record) => writeFile(join(directory, `${name}.json`), JSON.stringify({ ...record, at: Date.now() }), { mode: 0o600 }),
+});
+export const installState = stepRecord('install'), setupState = stepRecord('setup');
+
+// A stop asks every launch started before it to end. A worker reads this right
+// after it claims the launch; a stop that ran before the claim found no worker
+// to signal, so the worker ends itself here instead of starting anything.
+export const stopRequest = {
+ write: directory => writeFile(join(directory, 'stop.json'), JSON.stringify({ at: Date.now(), pid: process.pid }), { mode: 0o600 }),
+ covers: async (directory, requestedAt) => ((await readJson(join(directory, 'stop.json')))?.at ?? -Infinity) >= requestedAt,
+};
+
+export const serverRecord = {
+ read: directory => readJson(join(directory, 'server.json')),
+ write: (directory, record) => writeFile(join(directory, 'server.json'), JSON.stringify(record), { mode: 0o600 }),
+};

package/global/launch/steps.mjs

@@ -0,0 +1,90 @@
+// Run the pinned dispatcher's public verbs as children, reading its --json
+// events: install and setup to completion, and dev until its `ready` event.
+import { spawn } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { open, stat } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { setTimeout as delay } from 'node:timers/promises';
+import { LaunchFailure } from './failure.mjs';
+
+function events(line) { try { const value = JSON.parse(line); return value && typeof value === 'object' ? value : undefined; } catch { return undefined; } }
+
+// What a child's JSON event means for the person waiting.
+export function waitingNote(event) {
+ if (event.event === 'waiting') return `waiting in the job queue${event.reason ? `: ${event.reason}` : ''}`;
+ if (event.event === 'node-selection') return event.message;
+ if (event.event === 'port') return `using port ${event.port}`;
+ return undefined;
+}
+
+export function failureFrom(code, error, output) {
+ return new LaunchFailure(code || 1, error?.message ?? (output.trim().split('\n').slice(-5).join('\n') || `The command stopped with exit ${code}.`), error);
+}
+
+// A child joins the set a stop signals; one spawned as the stop arrives is
+// signalled at once rather than left to finish.
+function own(children, child, signal) {
+ children.add(child);
+ if (signal?.aborted) child.kill('SIGTERM');
+}
+
+// One bounded verb, never prompting: no stdin, --non-interactive, --json.
+export async function runVerb(entry, args, { root, env, note, log, children, signal }) {
+ signal?.throwIfAborted();
+ const child = spawn(process.execPath, [entry, ...args, '--json', '--non-interactive'], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
+ own(children, child, signal);
+ let error, output = '';
+ const lines = createInterface({ input: child.stdout });
+ lines.on('line', line => { const event = events(line); if (event?.event === 'error') error = event; const text = event && waitingNote(event); if (text) note(text); log(line); });
+ child.stderr.on('data', data => { output = (output + data).slice(-8192); log(String(data).trimEnd()); });
+ const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('close', (exit, signal) => resolve(exit ?? (signal ? 128 : 1))); });
+ children.delete(child);
+ if (code !== 0) throw failureFrom(code, error, output);
+}
+
+// Follow a growing log file from an offset, line by line.
+async function follow(path, from, onLine, stopped) {
+ let offset = from, rest = '';
+ while (!stopped()) {
+  const size = (await stat(path)).size;
+  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 parts = rest.split('\n'); rest = parts.pop();
+   for (const line of parts) if (onLine(line)) return;
+  }
+  await delay(200);
+ }
+}
+
+// Start `dev` detached into its own process group with its output in a private
+// log, and return its ready event once it prints one. The server outlives this
+// process and stops on rer dev --stop or its idle timeout.
+export async function startServer(entry, args, { root, env, logPath, children, signal }) {
+ signal?.throwIfAborted();
+ const handle = await open(logPath, 'a', 0o600), from = (await handle.stat()).size;
+ let child;
+ try { child = spawn(process.execPath, [entry, 'dev', ...args, '--json'], { cwd: root, env, detached: true, stdio: ['ignore', handle.fd, handle.fd] }); }
+ finally { await handle.close(); }
+ own(children, child, signal);
+ let exit, ready, error, output = '';
+ child.once('exit', (code, name) => { exit = code ?? (name ? 128 : 1); });
+ await follow(logPath, from, line => {
+  const event = events(line);
+  if (event?.event === 'ready') { ready = event; return true; }
+  if (event?.event === 'error') error = event;
+  if (!event) output = (output + line + '\n').slice(-8192);
+  return false;
+ }, () => exit !== undefined);
+ if (!ready) {
+  // Read whatever the exiting dispatcher wrote last.
+  for await (const line of createInterface({ input: createReadStream(logPath, { start: from }) })) { const event = events(line); if (event?.event === 'ready') ready = event; if (event?.event === 'error') error = event; }
+ }
+ children.delete(child);
+ if (!ready) throw failureFrom(exit, error, output);
+ child.unref();
+ return { ready, pid: child.pid, reused: exit === 0 };
+}

package/global/launch/stop.mjs

@@ -0,0 +1,89 @@
+// rer dev --stop for a checkout the launcher may be preparing or serving.
+// It ends a launch still preparing (or one that has not yet claimed the
+// checkout), has the pinned dispatcher stop the registered server, and then
+// checks that every process it found -- the worker, the server rer started,
+// the registered server and everything they spawned -- has exited. It says
+// what it stopped, or exits non-zero naming what is still running.
+import { setTimeout as delay } from 'node:timers/promises';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { readProcessTable, sameBirth } from '../../onboarding/process-table.mjs';
+import { delegate } from '../delegate.mjs';
+import { liveServers } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
+import { liveWorker, serverRecord, stopRequest } from './state.mjs';
+
+export async function stopLaunch(target, devArgs, { checkout, directory }) {
+ // Written before looking for a worker: one that claims the launch after this
+ // look reads it and ends itself (worker.mjs).
+ await stopRequest.write(directory);
+ const holder = await liveWorker(directory);
+ const launch = holder ? await tree([holder]) : [];
+ if (holder) await endWorker(holder);
+ // Only now: a worker stopped while its server came up has registered it.
+ const record = (await liveServers()).find(item => item.checkout === checkout);
+ const started = await serverRecord.read(directory);
+ const server = await tree([record?.owner, record?.runtimeProcess, started, started?.spawned]);
+ await delegate(target, ['dev', ...devArgs]);
+ if (process.exitCode) return process.exitCode;
+ const left = await exited([...launch, ...server], 15000);
+ if (left.length) {
+  const pids = left.map(item => item.pid).join(' ');
+  process.stderr.write(`rer dev --stop: ${left.length === 1 ? 'a process' : `${left.length} processes`} of this checkout's dev server ${left.length === 1 ? 'is' : 'are'} still running 15 seconds after the stop (PID ${pids}). Stop ${left.length === 1 ? 'it' : 'them'} with kill -TERM ${pids}, then run rer dev --stop again.\n`);
+  return 1;
+ }
+ if (!devArgs.includes('--json')) process.stdout.write(said({ checkout, record, started, server, holder, launch }) + '\n');
+ return 0;
+}
+
+// SIGTERM the preparing worker and wait for it to exit.
+async function endWorker(holder) {
+ try { process.kill(holder.pid, 'SIGTERM'); } catch (error) { if (error.code === 'ESRCH') return; throw error; }
+ for (let waited = 0; waited < 60000; waited += 250) {
+  const current = await processInfo(holder.pid);
+  if (!current || current.zombie || current.start !== holder.start) return;
+  await delay(250);
+ }
+ throw new LaunchFailure(1, `The launch worker (PID ${holder.pid}) did not stop within a minute.`);
+}
+
+// The live processes among these recorded identities ({pid, start}), with
+// every process descended from them, as process-table entries.
+async function tree(identities) {
+ const roots = new Set();
+ for (const identity of identities) {
+  if (!identity?.pid || !identity.start) continue;
+  const current = await processInfo(identity.pid);
+  if (current && !current.zombie && current.start === identity.start) roots.add(identity.pid);
+ }
+ if (!roots.size) return [];
+ const table = await readProcessTable(), found = table.filter(entry => roots.has(entry.pid));
+ for (let index = 0; index < found.length; index++) {
+  for (const entry of table) if (entry.ppid === found[index].pid && !found.includes(entry)) found.push(entry);
+ }
+ return found;
+}
+
+// Wait until none of these processes is running; return those still running.
+async function exited(processes, within) {
+ const deadline = Date.now() + within;
+ for (;;) {
+  const table = processes.length ? await readProcessTable() : [];
+  const left = processes.filter(item => table.some(entry => sameBirth(item, entry) && !entry.state.startsWith('Z')));
+  if (!left.length || Date.now() >= deadline) return left;
+  await delay(250);
+ }
+}
+
+function said({ checkout, record, started, server, holder, launch }) {
+ const lines = [], more = n => n > 0 ? ` with ${n} more ${n === 1 ? 'process' : 'processes'}` : '';
+ if (server.length) {
+  const pid = record?.owner?.pid ?? started?.pid ?? server[0].pid;
+  lines.push(`Stopped the dev server${record?.url ? ` at ${record.url}` : ''} for ${checkout} (PID ${pid})${more(server.length - 1)}.`);
+ }
+ if (holder) {
+  const own = launch.filter(item => !server.some(entry => sameBirth(item, entry)));
+  lines.push(`Stopped the launch still running for ${checkout} (PID ${holder.pid})${more(own.length - 1)}.`);
+ }
+ if (!lines.length) lines.push(`No dev server was running for ${checkout}.`);
+ return lines.join('\n');
+}

package/global/launch/worker.mjs

@@ -0,0 +1,62 @@
+// The detached launch worker: node worker.mjs ROOT TOKEN ARGS_JSON REQUESTED_AT
+// (REQUESTED_AT: when the `rer dev` that spawned it started, epoch ms).
+// It runs in its own session, so killing the `rer dev` that started it (or that
+// command's whole process group) leaves it running; a rerun attaches to it.
+// rer dev --stop ends it: SIGTERM, or, for a stop that ran before this worker
+// claimed the launch, the stop request it reads right after claiming. Either
+// way no further step starts, the running one is signalled, and the launch
+// reports that it was stopped instead of ready.
+import { createWriteStream } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { liveServers } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
+import { prepare } from './prepare.mjs';
+import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord, stopRequest } from './state.mjs';
+import { startServer } from './steps.mjs';
+
+const [root, token, argsJSON, requestedAtText] = process.argv.slice(2), args = JSON.parse(argsJSON), requestedAt = Number(requestedAtText);
+const checkout = await realpath(root), directory = await launchDirectory(checkout), events = eventLog(directory, token);
+// Listening before the claim: a stop may signal this worker as soon as it is the holder.
+const children = new Set(), stopping = new AbortController();
+const stop = () => { stopping.abort(); for (const child of children) child.kill('SIGTERM'); };
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, stop);
+process.on('SIGHUP', () => {});
+if (!await claimLaunch(directory, token)) {
+ const holder = await liveWorker(directory);
+ await events.write({ event: 'redirect', token: holder?.token });
+} else {
+ const logFile = createWriteStream(join(directory, 'launch.log'), { flags: 'a', mode: 0o600 });
+ const log = text => logFile.write(text + '\n');
+ try {
+  if (await stopRequest.covers(directory, requestedAt)) stop();
+  stopping.signal.throwIfAborted();
+  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children, signal: stopping.signal });
+  await events.write({ event: 'phase', phase: 'start', message: prepared.own ? 'the app is already running; checking it' : 'starting the app' });
+  // A server rer started logs to server.log; asking a running one for its
+  // ready lines goes to reuse.log, and names server.log only when rer started it.
+  const serverLog = join(directory, 'server.log');
+  let started;
+  try { started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children, signal: stopping.signal }); }
+  finally { await prepared.release?.(); }
+  const record = (await liveServers(process.env)).find(item => item.checkout === checkout);
+  const pid = record?.owner?.pid ?? started.pid;
+  // The server's PID, and the process rer spawned for it (the same one unless
+  // the pin re-runs itself under its own Node), each with its start time.
+  const identity = async id => ({ pid: id, start: (await processInfo(id))?.start });
+  if (!prepared.own) await serverRecord.write(directory, { ...await identity(pid), spawned: await identity(started.pid) });
+  const ours = !prepared.own || (await serverRecord.read(directory))?.pid === pid;
+  // A stop that arrived while the server came up finds it registered and
+  // stops it; this launch reports the stop rather than a server about to end.
+  stopping.signal.throwIfAborted();
+  await events.write({ event: 'ready', ready: started.ready, pid, ...(ours ? { log: serverLog } : {}) });
+ } catch (error) {
+  log(String(error?.stack ?? error));
+  const failure = stopping.signal.aborted ? new LaunchFailure(1, 'rer dev --stop stopped this launch before the app was ready.') : error;
+  await events.write({ event: 'failed', exitCode: failure.exitCode ?? 1, message: failure.exitCode ? failure.message : `The launch failed unexpectedly; see ${join(directory, 'launch.log')}.`, ...(failure.event ? { error: failure.event } : {}) });
+ } finally {
+  await releaseLaunch(directory, token);
+  logFile.end();
+ }
+}

package/global/list.mjs

@@ -0,0 +1,59 @@
+// rer list [DIR] [--json]: the immediate subfolders of DIR that hold an
+// OPERATIONS.json, newest change first, with what rer dev can do for each.
+import { execFile } from 'node:child_process';
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { descriptorProfile, dispatcher } from './checkout.mjs';
+import { liveServers } from './registry.mjs';
+import { describeCheckout, setupNeeded } from './launch/facts.mjs';
+import { launchPath, setupState } from './launch/state.mjs';
+
+const run = promisify(execFile);
+const reasons = {
+ independent: 'independent project: rer runs its declared commands; zero-setup rer dev applies to first-party seeds only',
+ unreadable: 'OPERATIONS.json cannot be read',
+};
+
+async function changed(path) {
+ try { const { stdout } = await run('git', ['-C', path, 'log', '-1', '--format=%ct'], { timeout: 10000 }); if (/^\d+$/.test(stdout.trim())) return Number(stdout.trim()) * 1000; } catch {}
+ return (await stat(path)).mtimeMs;
+}
+
+async function entry(path, running) {
+ const facts = descriptorProfile(join(path, 'OPERATIONS.json'));
+ const profile = ['first-party', 'independent'].includes(facts.profile) ? facts.profile : 'unsupported';
+ const result = { path, name: path.split('/').pop(), profile, launchable: profile === 'first-party' };
+ if (!result.launchable) result.reason = reasons[facts.profile] ?? `OPERATIONS.json is version ${facts.version ?? '(none)'}, which rer does not run`;
+ result.prepared = null;
+ if (profile === 'first-party') {
+  // Set up: saved settings, and no setup a launch started left unfinished.
+  try { result.prepared = !await setupNeeded(path, await describeCheckout(path, dispatcher(path).entry, process.env), await setupState.read(launchPath(path))); }
+  catch (failure) { result.launchable = false; result.reason = `rer describe fails here: ${failure.message.split('\n')[0]}`; }
+ }
+ result.url = running.get(path) ?? null;
+ result.changedAt = new Date(await changed(path)).toISOString();
+ return result;
+}
+
+export async function listCommand(args) {
+ const json = args.includes('--json'), positional = args.filter(arg => arg !== '--json');
+ if (positional.length > 1 || positional.some(arg => arg.startsWith('-'))) { process.stderr.write('Usage: rer list [DIR] [--json]\n'); return 2; }
+ let directory;
+ try { directory = await realpath(resolve(positional[0] ?? '.')); } catch { process.stderr.write(`rer list: ${resolve(positional[0] ?? '.')} is not a folder.\n`); return 3; }
+ const running = new Map((await liveServers()).map(record => [record.checkout, record.url]));
+ const folders = [];
+ for (const item of await readdir(directory, { withFileTypes: true })) {
+  const path = join(directory, item.name);
+  try { if ((await stat(path)).isDirectory() && (await stat(join(path, 'OPERATIONS.json'))).isFile()) folders.push(await realpath(path)); } catch {}
+ }
+ const checkouts = [];
+ for (let i = 0; i < folders.length; i += 4) checkouts.push(...await Promise.all(folders.slice(i, i + 4).map(path => entry(path, running))));
+ checkouts.sort((a, b) => b.changedAt.localeCompare(a.changedAt) || a.name.localeCompare(b.name));
+ if (json) { process.stdout.write(JSON.stringify({ directory, checkouts }) + '\n'); return 0; }
+ if (!checkouts.length) { process.stdout.write(`No checkouts with an OPERATIONS.json in ${directory}.\n`); return 0; }
+ const width = Math.max(4, ...checkouts.map(item => item.name.length));
+ const rows = checkouts.map(item => `${item.name.padEnd(width)}  ${item.profile.padEnd(11)}  ${(item.launchable ? 'yes' : 'no').padEnd(6)}  ${(item.prepared === null ? '-' : item.prepared ? 'yes' : 'no').padEnd(8)}  ${item.url ?? (item.launchable ? '-' : item.reason)}`);
+ process.stdout.write([`${'NAME'.padEnd(width)}  ${'PROFILE'.padEnd(11)}  LAUNCH  PREPARED  URL`, ...rows, '', 'Launch one with: rer dev --cwd FOLDER'].join('\n') + '\n');
+ return 0;
+}

package/global/main.mjs

@@ -0,0 +1,53 @@
+import { dispatcher, locate, unsupportedMessage } from './checkout.mjs';
+import { delegate } from './delegate.mjs';
+import { localDefaults } from './launch/local-defaults.mjs';
+
+const help = `Usage: rer VERB [FLAGS]
+
+Inside a project (the nearest OPERATIONS.json at or above this folder, or --cwd DIR),
+every verb runs that checkout's own pinned rer, exactly as node scripts/rer.mjs VERB would.
+
+  rer dev              Launch a first-party checkout with no setup steps: installs dependencies,
+                       sets up a local owner and a free port when needed, starts the app and prints
+                       RER_READY and a sign-in link. Without a terminal it returns once the app is
+                       ready and leaves it running (--detach and --foreground override); allow up
+                       to 10 minutes on a first launch, or rerun it to reattach. rer dev --stop stops it.
+  rer list [DIR]       The checkouts in DIR (default: here), newest first, with whether rer dev can
+                       launch them, whether they are set up, and their running URL. --json for data.
+  rer cli status       This rer: version, contents digest, install channel, launcher and other rer
+                       commands on PATH. --json for data.
+  rer cli install      Install this package for the current user (~/.local/bin/rer).
+  rer cli uninstall    Remove the launcher and the install root; ~/.rer is untouched.
+  rer update           Move to the latest published rer (--version X for an exact one), the way it
+                       was installed: npx and install.sh installs switch atomically, npm installs run npm.
+  rer --version        Print this rer's version; inside a checkout, also the version the checkout pins.
+
+Checkout verbs: install, setup, dev, preview, build, verify, reset, deploy, export, import,
+outbox, doctor, describe, check, release. Run rer VERB --help in a checkout for its flags.
+`;
+
+export async function main(argv) {
+ const [verb] = argv;
+ if (verb === '--version' || verb === '-v') return (await import('./version.mjs')).versionCommand(argv);
+ // Only the zero-setup launch sets this, for its own setup child; an explicit
+ // verb never inherits it.
+ delete process.env[localDefaults];
+ if (verb === 'update') return (await import('./update/command.mjs')).update(argv.slice(1));
+ const notice = await import('./update/notice.mjs');
+ if (notice.wantsNotice(argv)) await notice.updateNotice();
+ if (!verb || verb === '--help' || verb === '-h' || verb === 'help') { process.stdout.write(help); return 0; }
+ if (verb === 'cli') return (await import('./cli/command.mjs')).cliCommand(argv.slice(1));
+ if (verb === 'list') return (await import('./list.mjs')).listCommand(argv.slice(1));
+ const target = locate(argv);
+ if (target.profile === 'unsupported') { process.stderr.write(unsupportedMessage(target.root, target.version) + '\n'); return 2; }
+ // A checkout that pins its own rer package runs all of it, launching included.
+ const mode = target.profile === 'first-party' ? dispatcher(target.root).mode : undefined;
+ if (verb === 'dev' && mode && mode !== 'package' && !argv.includes('--help')) return (await import('./launch/dev.mjs')).launchDev(target);
+ // Every other server start or queued job on a vendored pin gets the person
+ // defaults too (a pinned package applies its own).
+ if (mode === 'vendored') {
+  const { personEnvironment, personVerbs, pinPolicy } = await import('./launch/capacity.mjs');
+  if (personVerbs.has(verb)) Object.assign(process.env, personEnvironment(process.env, target.args, await pinPolicy(target.root, mode)));
+ }
+ await delegate(target, target.args);
+}

package/global/package-info.mjs

@@ -0,0 +1,38 @@
+// Facts about the running rer package: where it lives, its version and the
+// digest of its contents (which tells two builds of one version apart).
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const packageName = '@runeditrun/rer';
+export const ownRoot = realpathSync(fileURLToPath(new URL('../', import.meta.url)));
+
+export function ownManifest() {
+ const packed = JSON.parse(readFileSync(join(ownRoot, 'package.json'), 'utf8'));
+ return packed.name === packageName ? packed : JSON.parse(readFileSync(join(ownRoot, 'global/package.json'), 'utf8'));
+}
+
+export async function packageFileList(root) {
+ const files = [];
+ async function walk(directory) {
+  for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+   const path = join(directory, entry.name);
+   if (entry.isDirectory()) await walk(path);
+   else if (entry.isFile()) files.push(relative(root, path));
+   else throw Error(`Unexpected non-file entry in the rer package: ${relative(root, path)}`);
+  }
+ }
+ await walk(root);
+ return files.sort();
+}
+
+// sha256 over every file's path and bytes, in a fixed order.
+export async function packageDigest(root) {
+ const hash = createHash('sha256');
+ for (const path of await packageFileList(root)) {
+  hash.update(path).update('\0').update(await readFile(join(root, path))).update('\0');
+ }
+ return hash.digest('hex');
+}

package/global/registry.mjs

@@ -0,0 +1,24 @@
+// Read-only view of the shared server registry that every pinned dispatcher
+// writes (RER_SERVERS_DIR, else the account's ~/.rer/servers).
+import { readFile } from 'node:fs/promises';
+import { userInfo } from 'node:os';
+import { join, resolve } from 'node:path';
+import { alive } from '../modules/job-queue/identity.mjs';
+
+export const serversDirectory = (env = process.env) => resolve(env.RER_SERVERS_DIR ?? join(userInfo().homedir, '.rer/servers'));
+
+export async function liveServers(env = process.env) {
+ let state;
+ try { state = JSON.parse(await readFile(join(serversDirectory(env), 'state.json'), 'utf8')); }
+ catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+ const live = [];
+ for (const record of state.running ?? []) {
+  // An identity that cannot be verified is kept, as the dispatchers keep it.
+  let running = true;
+  try { running = await alive(record.owner); } catch {}
+  if (running) live.push(record);
+ }
+ return live;
+}
+
+export const stopCommand = record => `rer ${record.mode} --stop --cwd ${JSON.stringify(record.checkout)}`;

package/global/rer.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// The installed `rer` command. This file avoids newer syntax so that an old
+// Node still reaches the one-line minimum-version message.
+import { readFileSync } from 'node:fs';
+
+function manifest() {
+ // Packed: the package's own package.json. From a Base checkout: the template.
+ var packed = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+ return packed.name === '@runeditrun/rer' ? packed : JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+}
+
+function below(actual, minimum) {
+ var a = actual.split('.').map(Number), m = minimum.split('.').map(Number);
+ for (var i = 0; i < 3; i++) { if ((a[i] || 0) !== (m[i] || 0)) return (a[i] || 0) < (m[i] || 0); }
+ return false;
+}
+
+var minimum = manifest().engines.node.replace(/^>=\s*/, '');
+if (process.platform === 'win32') {
+ process.stderr.write('rer runs on macOS and Linux. On Windows, install it inside WSL2.\n');
+ process.exitCode = 1;
+} else if (below(process.versions.node, minimum)) {
+ process.stderr.write('rer needs Node ' + minimum + ' or later; this is Node ' + process.versions.node + '. Install a newer Node, then run rer again.\n');
+ process.exitCode = 1;
+} else {
+ import('./main.mjs').then(function (module) { return module.main(process.argv.slice(2)); }).then(function (code) {
+  if (code !== undefined) process.exitCode = code;
+ });
+}

package/global/update/archive.mjs

@@ -0,0 +1,89 @@
+// Read an npm tarball for installing: check it is exactly the registry's bytes
+// (sha512 integrity, and the entry count and unpacked size when the registry
+// gives them) and that every entry is a plain file or folder under package/,
+// then write it out. Absolute paths, .. entries, links and devices are refused,
+// and so is anything another tar reader could read differently: a format other
+// than ustar, a pax extended header with a field other than path, size or
+// mtime, or data after the end of the archive. install.sh checks the same way.
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { UpdateFailure } from './registry.mjs';
+
+const text = (block, start, length) => { const end = block.subarray(start, start + length).indexOf(0); return block.toString('utf8', start, end === -1 ? start + length : start + end); };
+
+// A pax extended header's records ("<length> <key>=<value>\n"): path and size
+// replace the next entry's own, mtime is only a time; any other field is refused.
+function paxFields(data) {
+ const fields = {};
+ for (let offset = 0; offset < data.length;) {
+  const space = data.indexOf(0x20, offset), digits = data.toString('latin1', offset, space), length = Number(digits);
+  if (space === -1 || !/^[1-9]\d*$/.test(digits) || offset + length <= space + 1 || offset + length > data.length || data[offset + length - 1] !== 0x0a) throw new UpdateFailure('The archive has a damaged extended header.');
+  const record = data.toString('utf8', space + 1, offset + length - 1), equals = record.indexOf('=');
+  const key = record.slice(0, equals), value = record.slice(equals + 1);
+  offset += length;
+  if (equals < 1) throw new UpdateFailure('The archive has a damaged extended header.');
+  if (key === 'linkpath') throw new UpdateFailure('The archive contains a link.');
+  if (key === 'size' && !/^\d+$/.test(value)) throw new UpdateFailure('The archive has a damaged extended header.');
+  if (key !== 'path' && key !== 'size' && key !== 'mtime') throw new UpdateFailure(`The archive has an extended header field rer does not read (${key}).`);
+  fields[key] = key === 'size' ? Number(value) : value;
+ }
+ return fields;
+}
+
+// Every entry under package/, folders included (each counts toward the
+// registry's dist.fileCount); a folder has empty data.
+export function readPackage(bytes, dist) {
+ if (!/^sha512-[A-Za-z0-9+/]+=*$/.test(dist.integrity ?? '')) throw new UpdateFailure('The registry gives no sha512 integrity for this version.');
+ if (`sha512-${createHash('sha512').update(bytes).digest('base64')}` !== dist.integrity) throw new UpdateFailure('The download does not match the registry\'s sha512 integrity.');
+ let tar;
+ try { tar = gunzipSync(bytes); } catch { throw new UpdateFailure('The download is not a gzip archive.'); }
+ const entries = [];
+ let offset = 0, pax, ended = false;
+ while (offset + 512 <= tar.length) {
+  const block = tar.subarray(offset, offset + 512);
+  if (block.every(byte => byte === 0)) {
+   if (!tar.subarray(offset).every(byte => byte === 0)) throw new UpdateFailure('The archive has data after its end.');
+   ended = true;
+   break;
+  }
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 32 : block[i];
+  if (parseInt(text(block, 148, 8), 8) !== sum) throw new UpdateFailure('The archive has a damaged header.');
+  if (block.toString('latin1', 257, 265) !== 'ustar\u0000' + '00') throw new UpdateFailure('The archive is not a ustar archive.');
+  const sizeField = text(block, 124, 12).trim();
+  if (!/^[0-7]+$/.test(sizeField)) throw new UpdateFailure('The archive has a damaged header.');
+  const type = String.fromCharCode(block[156] || 48), size = type !== 'x' && pax?.size !== undefined ? pax.size : parseInt(sizeField, 8);
+  const data = tar.subarray(offset + 512, offset + 512 + size);
+  if (data.length < size) throw new UpdateFailure('The archive is truncated.');
+  offset += 512 + Math.ceil(size / 512) * 512;
+  if (type === 'x') {
+   if (pax) throw new UpdateFailure('The archive has two extended headers for one entry.');
+   pax = paxFields(data);
+   continue;
+  }
+  const name = pax?.path ?? (text(block, 345, 155) ? `${text(block, 345, 155)}/${text(block, 0, 100)}` : text(block, 0, 100));
+  pax = undefined;
+  if (type !== '0' && type !== '5') throw new UpdateFailure(`The archive contains a link, device or other special entry (${name}).`);
+  const parts = name.split('/');
+  if (name.startsWith('/') || parts.includes('..') || name.includes('\\') || parts[0] !== 'package') throw new UpdateFailure(`The archive contains an unsafe path (${name}).`);
+  if (type === '5' && size !== 0) throw new UpdateFailure(`The archive gives the folder ${name} contents.`);
+  if (type === '0' && name.endsWith('/')) throw new UpdateFailure(`The archive gives the file ${name} a folder's name.`);
+  entries.push({ path: parts.slice(1).filter(Boolean).join('/'), data, executable: (parseInt(text(block, 100, 8), 8) & 0o100) !== 0, directory: type === '5' });
+ }
+ if (!ended || pax) throw new UpdateFailure('The archive is truncated.');
+ if (dist.fileCount !== undefined && dist.fileCount !== entries.length) throw new UpdateFailure(`The archive holds ${entries.length} entries; the registry says ${dist.fileCount}.`);
+ const total = entries.reduce((sum, entry) => sum + entry.data.length, 0);
+ if (dist.unpackedSize !== undefined && dist.unpackedSize !== total) throw new UpdateFailure(`The archive unpacks to ${total} bytes; the registry says ${dist.unpackedSize}.`);
+ return entries;
+}
+
+export async function writePackage(entries, root) {
+ for (const entry of entries) {
+  if (entry.directory) { await mkdir(join(root, entry.path), { recursive: true }); continue; }
+  await mkdir(dirname(join(root, entry.path)), { recursive: true });
+  try { await writeFile(join(root, entry.path), entry.data, { mode: entry.executable ? 0o755 : 0o644, flag: 'wx' }); }
+  catch (error) { if (['EEXIST', 'EISDIR'].includes(error.code)) throw new UpdateFailure(`The archive holds ${entry.path} twice.`); throw error; }
+ }
+}