@runeditrun/rer 0.0.0-stage → 0.1.0

package/global/launch/state.mjs

@@ -0,0 +1,97 @@
+// 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
+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');
+
+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,81 @@
+// 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);
+}
+
+// One bounded verb, never prompting: no stdin, --non-interactive, --json.
+export async function runVerb(entry, args, { root, env, note, log, children }) {
+ const child = spawn(process.execPath, [entry, ...args, '--json', '--non-interactive'], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
+ children.add(child);
+ 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 }) {
+ 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(); }
+ children.add(child);
+ let exit, ready, error, output = '';
+ child.once('exit', (code, signal) => { exit = code ?? (signal ? 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/worker.mjs

@@ -0,0 +1,43 @@
+// The detached launch worker: node worker.mjs ROOT TOKEN ARGS_JSON
+// 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.
+import { createWriteStream } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { liveServers } from '../registry.mjs';
+import { prepare } from './prepare.mjs';
+import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord } from './state.mjs';
+import { startServer } from './steps.mjs';
+
+const [root, token, argsJSON] = process.argv.slice(2), args = JSON.parse(argsJSON);
+const checkout = await realpath(root), directory = await launchDirectory(checkout), events = eventLog(directory, token);
+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');
+ const children = new Set();
+ for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { for (const child of children) child.kill('SIGTERM'); });
+ process.on('SIGHUP', () => {});
+ try {
+  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children });
+  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');
+  const started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children });
+  const record = (await liveServers(process.env)).find(item => item.checkout === checkout);
+  await prepared.release?.();
+  const pid = record?.owner?.pid ?? started.pid;
+  if (!prepared.own) await serverRecord.write(directory, { pid });
+  const ours = !prepared.own || (await serverRecord.read(directory))?.pid === pid;
+  await events.write({ event: 'ready', ready: started.ready, pid, ...(ours ? { log: serverLog } : {}) });
+ } catch (error) {
+  log(String(error?.stack ?? error));
+  await events.write({ event: 'failed', exitCode: error.exitCode ?? 1, message: error.exitCode ? error.message : `The launch failed unexpectedly; see ${join(directory, 'launch.log')}.`, ...(error.event ? { error: error.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; }
+ }
+}

package/global/update/command.mjs

@@ -0,0 +1,90 @@
+// rer update [--version X]: move this rer to the registry's latest version (or
+// X), the way it was installed. A user install (npx or install.sh) downloads,
+// verifies and switches atomically through the new package's own
+// `rer cli install`, keeping its channel; a failed or mismatched download
+// leaves the current version selected. An npm global install runs npm for its
+// own prefix and never writes a second launcher.
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { layout } from '../cli/layout.mjs';
+import { channelOf } from '../cli/status.mjs';
+import { ownManifest, ownRoot, packageDigest, packageName } from '../package-info.mjs';
+import { readPackage, writePackage } from './archive.mjs';
+import { compareVersions, packageMetadata, pickRelease, registryUrl, UpdateFailure } from './registry.mjs';
+
+const usage = 'Usage: rer update [--version X]\n';
+
+function parse(args) {
+ if (!args.length) return {};
+ if (args.length === 1 && args[0].startsWith('--version=') && args[0].length > 10) return { version: args[0].slice(10) };
+ if (args.length === 2 && args[0] === '--version' && args[1] && !args[1].startsWith('-')) return { version: args[1] };
+ return undefined;
+}
+
+const run = (program, args, env = process.env) => new Promise((resolve, reject) => {
+ const child = spawn(program, args, { env, stdio: ['ignore', 'inherit', 'inherit'] });
+ child.once('error', reject);
+ child.once('close', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+});
+
+// <prefix>/lib/node_modules/@runeditrun/rer, npm's global layout on macOS and Linux.
+function npmPrefix() {
+ const scope = dirname(ownRoot), modules = dirname(scope), lib = dirname(modules);
+ if (basename(scope) !== '@runeditrun' || basename(modules) !== 'node_modules' || basename(lib) !== 'lib') throw new UpdateFailure(`This npm global rer is at ${ownRoot}, outside npm's usual layout; update it with npm install -g ${packageName}.`);
+ return dirname(lib);
+}
+
+async function download(release) {
+ const response = await fetch(release.dist.tarball).catch(error => { throw new UpdateFailure(`Could not download ${release.dist.tarball} (${error.cause?.code ?? error.message}).`); });
+ if (!response.ok) throw new UpdateFailure(`${release.dist.tarball} answered ${response.status}.`);
+ return readPackage(Buffer.from(await response.arrayBuffer()), release.dist);
+}
+
+async function npmGlobal(version) {
+ const prefix = npmPrefix(), args = ['install', '-g', '--prefix', prefix, `${packageName}@${version}`];
+ const command = `npm ${args.map(arg => /^[\w@./:=-]+$/.test(arg) ? arg : JSON.stringify(arg)).join(' ')}`;
+ process.stdout.write(`Updating the npm global rer: ${command}\n`);
+ let code;
+ try { code = await run('npm', args); } catch (error) { code = 127; process.stderr.write(`Could not run npm (${error.code ?? error.message}).\n`); }
+ if (code !== 0) {
+  process.stderr.write(`npm could not update rer (exit ${code}); rer is unchanged. Fix the problem npm reports (for example, a prefix you cannot write), then run:\n  ${command}\n`);
+  return code || 1;
+ }
+ const installed = JSON.parse(await readFile(join(prefix, 'lib/node_modules', packageName, 'package.json'), 'utf8')).version;
+ process.stdout.write(`rer is now ${installed} (npm global, prefix ${prefix}).\n`);
+ return 0;
+}
+
+export async function update(args) {
+ const options = parse(args);
+ if (!options) { process.stderr.write(`Unsupported: rer update ${args.join(' ')}\n${usage}`); return 2; }
+ const { channel } = await channelOf(layout()), current = ownManifest().version;
+ if (channel === 'source') { process.stderr.write(`This rer runs from a source checkout (${ownRoot}), which rer update does not change. Update the checkout with git, or install rer with: npx -y ${packageName} cli install\n`); return 1; }
+ const work = await mkdtemp(join(tmpdir(), 'rer-update-'));
+ try {
+  const release = pickRelease(await packageMetadata(), options.version);
+  if (!options.version && compareVersions(current, release.version) > 0) {
+   process.stdout.write(`rer ${current} is newer than the latest published version (${release.version}); nothing changed. rer update --version ${release.version} installs that one.\n`);
+   return 0;
+  }
+  // The same version counts as current only with the same contents: a
+  // different build of that version is an update. (A development build's
+  // version differs from its release's, so it always moves.)
+  if (release.version === current || channel !== 'npm-global') {
+   process.stdout.write(`Checking rer ${release.version} from ${registryUrl()}\n`);
+   await writePackage(await download(release), join(work, 'package'));
+   if (release.version === current && await packageDigest(join(work, 'package')) === await packageDigest(ownRoot)) {
+    process.stdout.write(`rer ${current} is already current. Nothing changed.\n`);
+    return 0;
+   }
+  }
+  if (channel === 'npm-global') return await npmGlobal(release.version);
+  return await run(process.execPath, [join(work, 'package/global/rer.mjs'), 'cli', 'install'], { ...process.env, RER_INSTALL_CHANNEL: channel });
+ } catch (error) {
+  if (!(error instanceof UpdateFailure)) throw error;
+  process.stderr.write(`rer update: ${error.message} rer ${current} is still selected.\n`);
+  return 1;
+ } finally { await rm(work, { recursive: true, force: true }); }
+}

package/global/update/latest.mjs

@@ -0,0 +1,6 @@
+// Prints the registry's latest @runeditrun/rer version on one line. The update
+// notice runs this as a child process so that it can kill it at its time budget.
+import { packageMetadata } from './registry.mjs';
+
+const latest = (await packageMetadata())['dist-tags']?.latest;
+if (typeof latest === 'string') process.stdout.write(latest + '\n');