@runeditrun/rer 0.0.0-stage → 0.1.1

package/cli/runtime-front-door.mjs

@@ -0,0 +1,46 @@
+import { createServer } from 'node:net';
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { trafficProxy } from './server-proxy.mjs';
+
+// All public serving, including setup's bounded runtime, uses this listener.
+// The adapter receives a separate loopback port and keeps the public origin
+// for application URLs, cookies and sign-in links.
+export async function runtimeFrontDoor({ host, port, activity }) {
+ const runtimePort = await runtimeLoopbackPort(port);
+ const observer = activity ?? { begin: () => () => {}, touch: () => {} };
+ const proxy = await trafficProxy({ host, port, target: runtimePort, activity: observer });
+ return { ...proxy, runtimePort };
+}
+
+// The runtime binds this port strictly, seconds after it is chosen. A port the
+// OS assigned to listen(0) comes from its ephemeral range, which meanwhile hands
+// ports to every other socket (the runtime's own listeners, outbound requests),
+// so the runtime's bind could find it taken. Choose a free port the OS never
+// assigns on its own instead.
+async function runtimeLoopbackPort(publicPort) {
+ const [first, last] = await ephemeralRange();
+ const candidates = [[10000, first - 1], [last + 1, 65535]].filter(([low, high]) => low <= high);
+ if (!candidates.length) throw Error(`The OS assigns every local port from 10000 (ephemeral range ${first}-${last}); leave part of that space outside the range for the local runtime.`);
+ const size = candidates.reduce((total, [low, high]) => total + high - low + 1, 0);
+ for (let attempt = 0; attempt < 100; attempt++) {
+  let offset = Math.floor(Math.random() * size), candidate;
+  for (const [low, high] of candidates) { if (offset <= high - low) { candidate = low + offset; break; } offset -= high - low + 1; }
+  if (candidate !== publicPort && await free(candidate)) return candidate;
+ }
+ throw Error('No free loopback port outside the ephemeral range was found for the local runtime.');
+}
+async function ephemeralRange() {
+ if (process.platform === 'linux') return (await readFile('/proc/sys/net/ipv4/ip_local_port_range', 'utf8')).trim().split(/\s+/).map(Number);
+ if (process.platform === 'darwin') return (await promisify(execFile)('/usr/sbin/sysctl', ['-n', 'net.inet.ip.portrange.first', 'net.inet.ip.portrange.last'])).stdout.trim().split(/\s+/).map(Number);
+ // Windows' default dynamic range, the IANA range.
+ return [49152, 65535];
+}
+function free(port) {
+ const probe = createServer();
+ return new Promise(resolve => {
+  probe.once('error', () => resolve(false));
+  probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)));
+ });
+}

package/cli/scheduled.mjs

@@ -0,0 +1,81 @@
+import { declaredCronSources } from './deploy-config.mjs';
+
+// `rer dev` runs the project's declared Cron Triggers (wrangler `triggers.crons`, from wrangler.jsonc, wrangler.toml or a deploy template)
+// on their schedule by calling the local runtime's scheduled test endpoint (the Vite plugin's under dev, Miniflare's own under preview), so
+// alerts, retries and checks behave on the owner's computer as they do deployed.
+
+const fields = [[0, 59], [0, 23], [1, 31], [1, 12], [1, 7]];
+
+function field(text, [low, high]) {
+ const values = new Set();
+ for (const part of text.split(',')) {
+  const match = /^(?:(\*)|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/.exec(part);
+  if (!match) throw new Error(`Unsupported cron field "${text}"`);
+  const step = match[4] === undefined ? 1 : Number(match[4]);
+  const start = match[1] ? low : Number(match[2]), end = match[1] ? high : match[3] === undefined ? (match[4] === undefined ? start : high) : Number(match[3]);
+  if (!step || start < low || end > high || start > end) throw new Error(`Cron field "${text}" is out of range`);
+  for (let value = start; value <= end; value += step) values.add(value);
+ }
+ return values;
+}
+
+// Same grammar the deploy kit accepts: five numeric fields with lists, ranges and
+// steps, in UTC. Day of week counts 1 (Sunday) to 7 (Saturday), as Cloudflare does.
+export function parseCron(expression) {
+ const parts = expression.trim().split(/\s+/);
+ if (parts.length !== 5) throw new Error(`Cron "${expression}" needs five fields`);
+ const [minute, hour, day, month, weekday] = parts.map((part, index) => field(part, fields[index]));
+ return { minute, hour, day, month, weekday, dayRestricted: parts[2] !== '*', weekdayRestricted: parts[4] !== '*' };
+}
+
+export function cronMatches(cron, date) {
+ const parsed = typeof cron === 'string' ? parseCron(cron) : cron;
+ const day = parsed.day.has(date.getUTCDate()), weekday = parsed.weekday.has(date.getUTCDay() + 1);
+ const days = parsed.dayRestricted && parsed.weekdayRestricted ? day || weekday : day && weekday;
+ return parsed.minute.has(date.getUTCMinutes()) && parsed.hour.has(date.getUTCHours()) && parsed.month.has(date.getUTCMonth() + 1) && days;
+}
+
+// The Cron Triggers a project declares, read from the same files `rer check` reads
+// for the deployed Worker (deploy-config.mjs). Two files that both declare
+// triggers.crons must declare the same ones: otherwise `rer dev` would run a
+// schedule the deployed Worker does not have.
+export async function declaredCrons(root, adapter) {
+ const sources = await declaredCronSources(root, adapter);
+ for (const { path, crons } of sources) for (const cron of crons) parseCron(cron);
+ const [first, ...others] = sources;
+ const clash = others.find(({ crons }) => crons.length !== first.crons.length || crons.some(cron => !first.crons.includes(cron)));
+ if (clash) throw new Error(`${first.path} declares ${JSON.stringify(first.crons)} but ${clash.path} declares ${JSON.stringify(clash.crons)}; make them the same.`);
+ return first?.crons ?? [];
+}
+
+// Fire each matching cron at the start of its minute until `signal` aborts.
+// `report` receives one record per run: { cron, ok, status?, ms, error? }.
+export function runScheduled({ crons, url, path = '/cdn-cgi/handler/scheduled', signal, report, now = () => new Date(), fetchImpl = fetch, runTimeout = 300000 }) {
+ const parsed = crons.map(cron => [cron, parseCron(cron)]), running = new Set();
+ let timer;
+ const settled = new Promise(resolve => {
+  const finish = () => { clearTimeout(timer); resolve(); };
+  if (signal.aborted) return finish();
+  signal.addEventListener('abort', finish, { once: true });
+  const wait = () => { timer = setTimeout(tick, 60000 - (now().getTime() % 60000) + 250); };
+  const tick = () => {
+   const minute = now();
+   for (const [cron, expression] of parsed) if (cronMatches(expression, minute)) void run(cron);
+   wait();
+  };
+  async function run(cron) {
+   if (running.has(cron)) { report({ cron, ok: false, skipped: true, error: 'previous run still in progress' }); return; }
+   running.add(cron);
+   const started = Date.now();
+   try {
+    const response = await fetchImpl(`${url}${path}?cron=${encodeURIComponent(cron)}`, { signal: AbortSignal.any([signal, AbortSignal.timeout(runTimeout)]) });
+    await response.body?.cancel();
+    report({ cron, ok: response.ok, status: response.status, ms: Date.now() - started });
+   } catch (error) {
+    if (!signal.aborted) report({ cron, ok: false, ms: Date.now() - started, error: error.name === 'TimeoutError' ? 'timed out' : 'the runtime did not answer' });
+   } finally { running.delete(cron); }
+  }
+  wait();
+ });
+ return settled;
+}

package/cli/server-activity.mjs

@@ -0,0 +1,12 @@
+// Inject the monotonic clock and scheduling together: tests advance logical time,
+// never assert the operating system schedules a callback in a wall-clock window.
+export function activityClock({seconds,onIdle,now=()=>Number(process.hrtime.bigint()/1000000n),schedule=setTimeout,cancel=clearTimeout,onChange=()=>{}}={}) {
+ let ready=false,active=0,last=now(),timer,closed=false;
+ function arm(){cancel(timer);if(ready&&!closed&&!active)timer=schedule(()=>{if(now()-last>=seconds*1000)onIdle();else arm();},Math.min(2**31-1,Math.max(1,seconds*1000-(now()-last))));}
+ function touch(){last=now();onChange({lastActivity:last,active});arm();}
+ return {ready(){ready=true;touch();},touch,
+  begin(){active++;touch();let ended=false;return()=>{if(ended)return;ended=true;active--;touch();};},
+  snapshot(){return {ready,active,lastActivity:last,idleSeconds:(now()-last)/1000};},
+  close(){closed=true;cancel(timer);}
+ };
+}

package/cli/server-proxy.mjs

@@ -0,0 +1,93 @@
+import http from 'node:http';
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { refuse } from './errors.mjs';
+import { fontResponseHeaders } from './font-cache.mjs';
+
+// The public listener observes transport lifetime without buffering or replacing
+// application responses. Preserve Host, Origin, cookies, status and streaming.
+// Each request opens its own loopback connection: a pooled keep-alive socket
+// that the runtime has already dropped would otherwise fail a fresh request.
+export async function trafficProxy({host,port,target,activity}) {
+ const probe=randomUUID(),sockets=new Set();
+ const server=http.createServer((req,res)=>{
+  if(!publicPath(req.url)){req.resume();notFound(res);return;}
+  const internal=req.headers['x-rer-probe']===probe;delete req.headers['x-rer-probe'];
+  const finish=internal?()=>{}:activity.begin();
+  let requestEnded=req.complete,responseEnded=false;
+  const completed=()=>{if(requestEnded&&responseEnded)finish();};
+  req.once('end',()=>{requestEnded=true;completed();});req.once('aborted',finish);
+  res.once('close',()=>{responseEnded=true;if(req.destroyed)finish();else completed();});res.once('finish',()=>{responseEnded=true;completed();});
+  const upstream=http.request({host:'127.0.0.1',port:target,path:req.url,method:req.method,headers:req.headers,agent:false},reply=>{
+   res.writeHead(reply.statusCode,fontResponseHeaders(req.url,reply.statusCode,reply.rawHeaders,req.headers));reply.pipe(res);
+  });
+  req.once('aborted',()=>upstream.destroy());res.once('close',()=>upstream.destroy());
+  upstream.on('error',()=>{if(!res.headersSent)notFound(res);else res.destroy();});req.pipe(upstream);
+ });
+ server.on('connection',socket=>{sockets.add(socket);socket.on('close',()=>sockets.delete(socket));});
+ server.on('upgrade',(req,socket,head)=>{
+  if(!publicPath(req.url)){socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');return;}
+  const hmr=String(req.headers['sec-websocket-protocol']??'').split(',').map(s=>s.trim()).includes('vite-hmr');
+  const upstream=net.connect(target,'127.0.0.1',()=>{
+   upstream.write(`${req.method} ${req.url} HTTP/${req.httpVersion}\r\n${req.rawHeaders.reduce((lines,value,i)=>i%2?lines:lines+value+': '+req.rawHeaders[i+1]+'\r\n','')}\r\n`);
+   if(head.length)upstream.write(head);socket.pipe(upstream);upstream.pipe(socket);
+  });
+  if(!hmr){
+   const observeSafely=observer=>chunk=>{try{observer(chunk);}catch{socket.destroy();upstream.destroy();}};
+   const finish=activity.begin(),observe=observeSafely(frameObserver(()=>activity.touch())),replyFrames=observeSafely(frameObserver(()=>activity.touch()));
+   let handshake=Buffer.alloc(0),upgraded=false;
+   if(head.length)observe(head);socket.on('data',observe);socket.once('close',finish);
+   upstream.on('data',chunk=>{
+    if(upgraded){replyFrames(chunk);return;}
+    handshake=Buffer.concat([handshake,chunk]);const end=handshake.indexOf('\r\n\r\n');
+    if(end<0){if(handshake.length>65536)upstream.destroy();return;}
+    upgraded=/^HTTP\/1\.[01] 101 /.test(handshake.toString('latin1',0,end));
+    if(upgraded)replyFrames(handshake.subarray(end+4));else finish();handshake=Buffer.alloc(0);
+   });
+  }
+  upstream.on('error',()=>socket.destroy());socket.on('error',()=>upstream.destroy());socket.on('close',()=>upstream.destroy());upstream.on('close',()=>socket.destroy());
+ });
+ try{await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(port,host,resolve);});}
+ catch(error){
+  if(['EADDRINUSE','EACCES'].includes(error.code))throw refuse(`Requested port ${port} is unavailable. Stop its owner or choose an explicit free port; rer does not drift.`);
+  throw error;
+ }
+ return {probe,port:server.address().port,async close(){for(const socket of sockets)socket.destroy();await new Promise(resolve=>server.close(resolve));}};
+}
+function notFound(res){res.writeHead(404,{'content-type':'text/plain; charset=utf-8'});res.end('Not found');}
+// The runtime's built-in routes (/cdn-cgi/*: Local Explorer, trigger handlers,
+// R2 and platform proxies), the checkout's private files and export archives
+// (*.rer and their in-progress .partial files) never answer on the public
+// listener; rer's scheduler calls the runtime's internal port. Decode as often as
+// a server might and test every segment, so encoded, dotted or backslashed
+// spellings of either are refused too (APFS ignores case). The documented
+// exports/ folder is refused where Vite serves the checkout (the root and its
+// /@fs, /@id prefixes), so an app's own /api/.../exports routes still answer.
+const privateSegment=/^(?:cdn-cgi|\.rer|\.seed|\.wrangler|\.git|\.dev\.vars.*|\.env.*|.*\.rer(?:\.[\w-]+\.partial)?)$/i;
+export function publicPath(url){
+ let path=String(url).split(/[?#]/)[0];
+ for(let round=0;round<4;round++){let decoded;try{decoded=decodeURIComponent(path);}catch{return false;}if(decoded===path)break;path=decoded;}
+ const segments=path.replace(/\\/g,'/').split('/').map(segment=>segment.trim());
+ if(segments.some(segment=>privateSegment.test(segment)))return false;
+ const served=posix.normalize('/'+segments.join('/')).split('/').filter(Boolean),exports=segment=>/^exports$/i.test(segment);
+ return !exports(served[0])&&!(served[0]?.startsWith('@')&&served.some(exports));
+}
+// Count application data frames, not protocol ping/pong or an open control
+// socket. Parse lengths incrementally without retaining application payloads.
+export function frameObserver(touch) {
+ let buffer=Buffer.alloc(0),remaining=0;
+ return chunk=>{
+  buffer=Buffer.concat([buffer,chunk]);
+  for(;;){
+   if(remaining){const count=Math.min(remaining,buffer.length);remaining-=count;buffer=buffer.subarray(count);if(remaining)return;}
+   if(buffer.length<2)return;
+   const opcode=buffer[0]&15,masked=Boolean(buffer[1]&128);let length=buffer[1]&127,offset=2;
+   if(length===126){if(buffer.length<4)return;length=buffer.readUInt16BE(2);offset=4;}
+   else if(length===127){if(buffer.length<10)return;const big=buffer.readBigUInt64BE(2);if(big>BigInt(Number.MAX_SAFE_INTEGER))throw Error('WebSocket frame too large');length=Number(big);offset=10;}
+   if(masked)offset+=4;if(buffer.length<offset)return;
+   if(opcode<=2)touch();buffer=buffer.subarray(offset);remaining=length;
+   if(!remaining&&!buffer.length)return;
+  }
+ };
+}

package/cli/server-registry.mjs

@@ -0,0 +1,182 @@
+import { createConnection, createServer } from 'node:net';
+import { randomUUID, createHash } from 'node:crypto';
+import { userInfo, tmpdir } from 'node:os';
+import { chmod, realpath, unlink, lstat, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { processInfo } from '../modules/job-queue/processes.mjs';
+import { identity, alive } from '../modules/job-queue/identity.mjs';
+import { transaction } from '../modules/job-queue/storage.mjs';
+import { refuse, invalid } from './errors.mjs';
+import { serverDefaults } from './contract.mjs';
+import { availableMemory } from '../modules/job-queue/resources.mjs';
+
+export function positive(value, name, fallback) {
+ if(value===undefined)return fallback;
+ if(!/^[1-9][0-9]*$/.test(String(value)) || !Number.isSafeInteger(Number(value)))throw invalid(`${name} must be positive integer seconds/count.`);
+ return Number(value);
+}
+export const stopInstruction = record => `rer ${record.mode} --cwd ${JSON.stringify(record.checkout)} --stop`;
+// Plain-words listing of one running server for the limit refusal.
+const listing = record => `  ${record.mode} on port ${record.port ?? '(starting)'} in ${record.checkout}\n    stop it with: ${stopInstruction(record)}`;
+export const description = record => `${record.mode} ${record.url ?? '(starting)'} for ${record.checkout}; stop it with: ${stopInstruction(record)}`;
+// A test or CI journey declares itself, the way RER_SERVERS_LOAD_THRESHOLD
+// declares load. It serves on its own port and never counts toward the cap.
+export const declaresJourney = env => {
+ if(env.RER_SERVER_JOURNEY===undefined)return false;
+ if(env.RER_SERVER_JOURNEY==='1')return true;
+ throw invalid('RER_SERVER_JOURNEY must be 1 to declare a test or CI journey.');
+};
+async function request(record, action) {
+ return new Promise((resolveRequest,reject)=>{
+  const socket=createConnection(record.control);let text='';
+  socket.setTimeout(35000,()=>socket.destroy(Error('Managed server did not complete cleanup.')));
+  socket.on('connect',()=>socket.end(JSON.stringify({token:record.token,action})));
+  socket.on('data',chunk=>{text+=chunk;if(text.length>16384)socket.destroy(Error('Invalid managed server reply.'));});
+  socket.on('end',()=>{try{const value=JSON.parse(text);if(value.token!==record.token)throw Error('Unverified server');resolveRequest(value);}catch(error){reject(error);}});
+  socket.on('error',reject);
+ });
+}
+
+// A new server starts only while this much memory is available. An idle dev
+// server holds 0.5-1.3 GiB (preview 0.4-0.8 GiB), so 1.5 GiB leaves room for the
+// largest one measured to start and settle. Below it the OS is already compressing
+// and swapping, and one more server makes every running one slower.
+export const defaultMemoryFloor=1.5*1024**3;
+export function memoryFloor(env=process.env){
+ const value=env.RER_SERVERS_MIN_MEMORY_BYTES;
+ if(value===undefined)return defaultMemoryFloor;
+ if(!/^(0|[1-9][0-9]*)$/.test(value)||!Number.isSafeInteger(Number(value)))throw invalid('RER_SERVERS_MIN_MEMORY_BYTES must be a number of bytes, 0 for no floor.');
+ return Number(value);
+}
+function memoryMessage(counted,available,floor,mode) {
+ const gib=bytes=>(bytes/1024**3).toFixed(1);
+ const head=`Not started: this computer is short of memory. ${gib(available)} GiB is available and a new server starts only at ${gib(floor)} GiB or more.`;
+ const list=counted.length?`Running now:\n${counted.map(listing).join('\n')}\nA dev server holds about 0.5-1.3 GiB and a preview 0.4-0.8 GiB; stopping one with its command above frees that.`:'No dev or preview server is running, so something else is using the memory.';
+ return `${head}\n${list}\nTo start anyway, lower the floor, for example RER_SERVERS_MIN_MEMORY_BYTES=${Math.floor(floor/2)} rer ${mode} (0 turns it off).`;
+}
+function limitMessage(counted,cap,limit,mode) {
+ const holders=cap<limit?counted.filter(item=>item.explicit&&item.limit===cap):[];
+ const head=`Not started: ${counted.length} dev or preview ${counted.length===1?'server is':'servers are'} running on this computer and the limit is ${cap}.`;
+ const list=`Running now:\n${counted.map(listing).join('\n')}`;
+ const raise=holders.length
+  ?`The limit is ${cap} because ${holders.length===1?'a server was':'servers were'} started with RER_SERVER_LIMIT=${cap} (${holders.map(item=>item.checkout).join(', ')}). Stop ${holders.length===1?'it':'them'} and start again, or start everything with a higher RER_SERVER_LIMIT=N.`
+  :`To allow more, start this one with a higher limit, for example RER_SERVER_LIMIT=${cap*2} rer ${mode}. Servers started without RER_SERVER_LIMIT allow ${defaultServerLimit}.`;
+ return `${head}\n${list}\nTo make room, stop one with its command above. ${raise}`;
+}
+// A server is only ever stopped by the checkout that owns it, through its own
+// --stop, idle timeout or signal. Capacity never stops another checkout's
+// server: a request over the cap is refused with the running servers named.
+// Lock order: short machine transaction -> reserve checkout; release transaction
+// before queue admission/local operation. Stop waits for process+state cleanup,
+// which never needs the machine transaction. Generation removal happens last.
+// The limit is 10 unless the person sets RER_SERVER_LIMIT. Every record keeps the
+// limit it started with and whether the person set it. Across the running
+// servers the cap is the lowest limit a person set explicitly, so a deliberate
+// "RER_SERVER_LIMIT=3" keeps holding every start. A recorded default (including
+// the old default of 2 in records written before this rule) never lowers the cap
+// below the current default.
+export const defaultServerLimit=serverDefaults.serverLimit;
+export const serversDirectory=(env=process.env)=>resolve(env.RER_SERVERS_DIR??join(userInfo().homedir,'.rer/servers'));
+export async function serverRegistry(root,{env=process.env,memory=availableMemory}={}) {
+ const floor=memoryFloor(env),explicit=env.RER_SERVER_LIMIT!==undefined,limit=positive(env.RER_SERVER_LIMIT,'RER_SERVER_LIMIT',defaultServerLimit),journey=declaresJourney(env);
+ const checkout=await realpath(root), lifetime=await identity();
+ const directory=serversDirectory(env);
+ let secured;
+ async function secure(){
+  for(const path of [directory,join(directory,'locks')]){
+   await mkdir(path,{recursive:true,mode:0o700});const info=await lstat(path);
+   if(info.isSymbolicLink()||!info.isDirectory()||info.uid!==process.getuid())throw refuse('Server registry directory is foreign or linked. Preserve it and choose an owned RER_SERVERS_DIR.');
+   await chmod(path,0o700);
+  }
+  try{const info=await lstat(join(directory,'state.json'));if(!info.isFile()||info.isSymbolicLink()||info.nlink!==1||info.uid!==process.getuid())throw refuse('Server registry state is foreign or linked. Preserve it for inspection.');await chmod(join(directory,'state.json'),0o600);}catch(error){if(error.code!=='ENOENT')throw error;}
+ }
+ const change=async action=>{await (secured??=secure());return transaction(directory,lifetime.info,action);};
+ let owned, control, closing;
+ async function inspect(state) {
+  const kept=[];
+  for(const record of state.running){
+   let live;try{live=await alive(record.owner);}catch{throw refuse(`Unverifiable server identity: ${description(record)}. Preserve it for inspection.`);}
+   if(live) kept.push(record);
+   else {
+    const current=await processInfo(record.owner.pid);
+    if(current&&!current.zombie&&current.start===record.owner.start)throw refuse(`Server lifetime cannot be verified: ${description(record)}. Preserve its process.`);
+    // A runtime capability grants recovery only to the captured process scope.
+    if(record.runtime) {
+     const { shared }=await import('./shared.mjs');
+     const { recoverCommand }=await shared('command-recovery.mjs');
+     await recoverCommand(record.runtime);
+    }
+   }
+  }
+  state.running=kept;
+ }
+ async function existing(mode,options,{stop=false}={}) {
+  return change(async state=>{
+   await inspect(state);const record=state.running.find(item=>item.checkout===checkout);
+   if(!record)return null;
+   if(record.mode!==mode)throw refuse(`This checkout already owns ${description(record)}.`);
+   if(!stop && (options.supplied.has('--host')&&record.host!==undefined&&options.host!==record.host || options.supplied.has('--port')&&record.port!==undefined&&options.port!==record.port || options.supplied.has('--idle-timeout')&&options.idleTimeout!==record.idleTimeout))throw refuse(`Options conflict with ${description(record)}.`);
+   return record;
+  });
+ }
+ async function stop(mode,options) {
+  try{await lstat(join(directory,'state.json'));}catch(error){if(error.code==='ENOENT')return;throw error;}
+  const record=await existing(mode,options,{stop:true});if(!record)return;
+  await request(record,'stop');
+  await change(state=>{state.running=state.running.filter(item=>item.generation!==record.generation);});
+ }
+ async function reserve(mode,options) {
+  return change(async state=>{
+   await inspect(state);
+   const same=state.running.find(item=>item.checkout===checkout);
+   if(same)return {existing:same};
+   // Journeys are listed but uncounted: they neither use nor lower the cap.
+   const counted=state.running.filter(item=>!item.journey),cap=Math.min(limit,...counted.filter(item=>item.explicit).map(item=>item.limit));
+   if(!journey&&counted.length>=cap)throw refuse(limitMessage(counted,cap,limit,mode));
+   // Unreadable memory is not a reason to refuse; only a reading below the floor is.
+   const available=journey||floor===0?NaN:await memory();
+   if(available<floor)throw refuse(memoryMessage(counted,available,floor,mode));
+   owned={checkout,mode,journey,generation:randomUUID(),token:randomUUID(),owner:lifetime.info,limit,explicit,startedAt:Number(process.hrtime.bigint()/1000000n),idleTimeout:options.idleTimeout};
+   owned.lastActivity=owned.startedAt;owned.active=0;
+   const name=`rer-server-${createHash('sha256').update(owned.generation).digest('hex').slice(0,20)}.sock`;
+   owned.control=join(tmpdir(),name);if(Buffer.byteLength(owned.control)>=100)owned.control=join('/tmp',name);
+   owned.runtime={pid:process.pid,token:owned.token};
+   state.running.push(owned);return {owned};
+  });
+ }
+ async function serve(handler) {
+  control=createServer({allowHalfOpen:true},socket=>{
+   let text='';socket.setTimeout(35000,()=>socket.destroy());
+   socket.on('data',data=>{text+=data;if(text.length>1024)socket.destroy();});
+   socket.on('end',async()=>{
+    try{const request=JSON.parse(text);if(request.token!==owned.token)throw Error('Invalid capability');socket.end(JSON.stringify({...await handler(request.action),token:owned.token}));}
+    catch{socket.destroy();}
+   });
+  });
+  await new Promise((resolve,reject)=>{control.once('error',reject);control.listen(owned.control,resolve);});await chmod(owned.control,0o600);
+ }
+ async function update(fields){Object.assign(owned,fields);await change(state=>{const item=state.running.find(item=>item.generation===owned.generation);if(!item)throw Error('Server reservation disappeared');Object.assign(item,fields);});}
+ async function updateActivity(fields){await change(state=>{const item=state.running.find(item=>item.generation===owned.generation);if(item)Object.assign(item,fields);});}
+ async function waitReady(record,signal){
+  for(let attempt=0;attempt<1200;attempt++){
+   signal?.throwIfAborted();if(!await alive(record.owner))throw refuse('Concurrent server startup failed. Retry after recovery.');
+   try{const status=await request(record,'status');if(status.ready)return {...record,...status};}catch(error){if(attempt===1199)throw error;}
+   await delay(250,undefined,{signal});
+  }
+  throw refuse('The existing server is still starting. Wait for its ready output.');
+ }
+ return {checkout,existing,stop,reserve,serve,update,updateActivity,waitReady,custodyToken:()=>owned?.token,
+  // The sockets close even when the record cannot be removed (its registry
+  // deleted under it, say): an open listener would keep this process alive.
+  close(){return closing??=(async()=>{
+   try{if(owned)await change(state=>{state.running=state.running.filter(item=>item.generation!==owned.generation);});}
+   finally{
+    try{
+     if(control)await new Promise(resolve=>control.close(resolve));
+     if(owned)await unlink(owned.control).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    }finally{await lifetime.close();}
+   }
+  })();}
+ };
+}

package/cli/server-resources.mjs

@@ -0,0 +1,22 @@
+import {loadavg,tmpdir} from 'node:os';
+import {statfs} from 'node:fs/promises';
+import {refuse} from './errors.mjs';
+// Persistent serving is not a bounded queue job. Check its launch separately,
+// after finite preparation, while its canonical server reservation is held.
+// The 1-minute-load guard is a fleet's rule, set in the fleet's environment:
+// without RER_SERVERS_LOAD_THRESHOLD a person's start is never refused for load.
+export function servingLoadThreshold(env=process.env){
+ if(env.RER_SERVERS_LOAD_THRESHOLD===undefined)return Infinity;
+ const threshold=Number(env.RER_SERVERS_LOAD_THRESHOLD);
+ if(!Number.isFinite(threshold)||threshold<0)throw refuse('Invalid server load threshold.');
+ return threshold;
+}
+export async function serverResources(root,{load=()=>loadavg()[0],disk=statfs,env=process.env}={}){
+ const threshold=servingLoadThreshold(env);
+ const measured=threshold===Infinity?0:await load();
+ if(!Number.isFinite(measured)||measured>threshold)throw refuse(`Not started: this computer is busy. Its 1-minute load is ${Number.isFinite(measured)?measured.toFixed(1):'unknown'} and a server starts only at ${threshold} or below.\nTry again in a few minutes, or start it anyway with a higher threshold, for example RER_SERVERS_LOAD_THRESHOLD=${Math.ceil(Math.max(threshold,Number.isFinite(measured)?measured:0)*2)} rer dev.`);
+ for(const path of new Set([root,tmpdir()])){
+  const state=await disk(path,{bigint:true});
+  if(state.bavail*state.bsize<15n*1024n**3n)throw refuse('Server startup requires 15 GiB free on checkout and temporary volumes. Recover owned space before retrying.');
+ }
+}

package/cli/settings.mjs

@@ -0,0 +1,15 @@
+// Reuse the seed's existing declarations; no parallel auth setting aliases.
+export function localSettingKeys(project) {
+ const manifest = project.setupManifest ?? project.setupSeed?.manifest;
+ const claim = manifest?.steps.find(step => step.type === 'owner-claim');
+ return {
+  origin: project.adapter?.hooks?.secrets?.originKey ?? 'AUTH_ORIGIN',
+  email: claim?.emailField ?? project.adapter?.input?.names?.email ?? 'OWNER_EMAIL',
+ };
+}
+
+export function requiredLocalSettings(project, values) {
+ const keys=localSettingKeys(project);
+ const manifest=project.setupManifest ?? project.setupSeed?.manifest;
+ return [...new Set([keys.email,keys.origin,...(manifest?.fields??[]).filter(field=>field.kind==='secret'&&field.required&&!field.when&&field.input!=='entered'&&field.name!==manifest?.steps.find(step=>step.type==='owner-claim')?.tokenField).map(field=>field.name)])].filter(name=>!values[name]);
+}

package/cli/setup-answers.mjs

@@ -0,0 +1,29 @@
+import { join } from 'node:path';
+import { contained } from './project.mjs';
+import { shared } from './shared.mjs';
+import { invalid } from './errors.mjs';
+
+const path = '.seed/installer/setup-answers.json';
+
+// Installer choices and local runtime bindings need not have the same meaning.
+// Keep only declared nonsecret answers, after successful setup, in owned storage.
+export async function savedSetupAnswers(project, model) {
+ const file = await contained(project.root, path, { optional: true, privateFile: true });
+ let saved;
+ try { saved = JSON.parse(await (await shared('private-files.mjs')).readPrivateFile(file)); }
+ catch (error) {
+  if (error.code === 'ENOENT') return undefined;
+  throw invalid('Saved setup answers are unreadable or invalid. Preserve private settings and repair the saved setup answers before retrying.');
+ }
+ if (!saved || typeof saved !== 'object' || Array.isArray(saved) || Object.values(saved).some(value => typeof value !== 'string'))
+  throw invalid('Saved setup answers must be a JSON object of installer answers.');
+ return Object.fromEntries(model.safeKeys.filter(key => Object.hasOwn(saved, key)).map(key => [key, saved[key]]));
+}
+
+export async function rememberSetupAnswers(project, input) {
+ const answers = Object.fromEntries(project.setupSeed.model.safeKeys.filter(key => typeof input[key] === 'string').map(key => [key, input[key]]));
+ const { privateDirectory, writePrivateFile } = await shared('private-files.mjs');
+ await privateDirectory(project.root, ['.seed', 'installer']);
+ await contained(project.root, path, { optional: true, privateFile: true });
+ await writePrivateFile(join(project.root, path), JSON.stringify(answers) + '\n');
+}

package/cli/setup-input.mjs

@@ -0,0 +1,113 @@
+import {randomBytes} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+import {createInterface} from 'node:readline/promises';
+import {Writable} from 'node:stream';
+import {contained} from './project.mjs';
+import {shared} from './shared.mjs';
+import {localSettingKeys} from './settings.mjs';
+import {mailbox} from './parse.mjs';
+import {invalid,missing,refuse} from './errors.mjs';
+import {savedSetupAnswers} from './setup-answers.mjs';
+
+// RER_SETUP_LOCAL_DEFAULTS=1 is set only by the zero-setup `rer dev` launch for
+// its own setup run: it fills each empty active field that declares a
+// localDefault. Explicit setup and deploy never read it.
+export const localDefaultsVariable = 'RER_SETUP_LOCAL_DEFAULTS';
+
+export async function setupInput(project, options, vars, signal, { origin } = {}) {
+ let answers = {};
+ const { loadInstallerSeed } = await shared('setup-manifest.mjs');
+ let seed;
+ try { seed = project.setupSeed ?? await loadInstallerSeed(project.root, project.adapter); }
+ catch { throw invalid('Setup manifest is missing, invalid or incompatible with its installer. Restore the declared manifest and presentation sources.'); }
+ project.setupManifest = seed.manifest;
+ if (options.answers) {
+  const path = await contained(project.root, options.answers, { privateFile: true });
+  try { answers = JSON.parse(await readFile(path, 'utf8')); } catch { throw invalid('Answers must be a private JSON object using the installer model names.'); }
+  if (!answers || typeof answers !== 'object' || Array.isArray(answers)) throw invalid('Answers must be a JSON object.');
+  if (Object.keys(answers).some(key=>/LINK.*TOKEN|IDENTITY_PRIVATE_KEY/i.test(key))) throw invalid('Link credentials are not setup answers. Use RER_LINK_TOKEN_FILE.');
+  project.privateInputs=[options.answers];
+ }
+ const names = { name: 'displayName', ...project.adapter.input?.names, email: localSettingKeys(project).email };
+ const hasOwnerName = Object.hasOwn(seed.model.fields, names.name);
+ if (!hasOwnerName && options.ownerName !== undefined) throw invalid('This installer does not declare an owner-name field; --owner-name is unsupported.');
+ for (const [flag, name] of [['ownerEmail', names.email], ['ownerName', names.name]]) {
+  if (options[flag] !== undefined && answers[name] !== undefined && options[flag] !== answers[name]) throw invalid('A setup flag conflicts with the answers file. Choose one consistent answer before setup.');
+  if (options[flag] !== undefined) answers[name] = options[flag];
+ }
+ const defaults=Object.fromEntries(seed.manifest.fields.filter(field=>field.kind!=='secret'&&field.default!==undefined).map(field=>[field.name,field.default]));
+ const adapterDefaults=await project.adapter.input?.defaults?.(project.root) ?? {};
+ // Older installations saved runtime bindings only. A runtime select value
+ // outside the installer domain is not an answer to that field; retain its
+ // private bytes and use the adapter's declared local installer choice.
+ const savedAnswers = Object.fromEntries(seed.manifest.fields.filter(field => field.kind !== 'secret' && typeof vars[field.name] === 'string' &&
+  !(field.kind === 'select' && Object.hasOwn(adapterDefaults, field.name) && !seed.model.fields[field.name].valid(vars[field.name]))).map(field => [field.name, vars[field.name]]));
+ const installerAnswers = await savedSetupAnswers(project, seed.model);
+ answers = { ...defaults, ...adapterDefaults, ...(installerAnswers ?? savedAnswers), ...answers };
+ const savedEmail = vars[names.email];
+ if (!answers[names.email] && savedEmail) answers[names.email] = savedEmail;
+ if (hasOwnerName) answers[names.name] ??= seed.model.fields[names.name].default ?? 'Owner';
+ if(process.env[localDefaultsVariable]==='1')applyLocalDefaults(seed,answers,vars,origin);
+ const entered=seed.manifest.fields.filter(field=>field.kind==='secret'&&field.input==='entered');
+ for(const field of entered)if(!answers[field.name]&&!vars[field.name]&&process.env[field.name])answers[field.name]=process.env[field.name];
+ const known={secretReadiness:Object.fromEntries(seed.manifest.fields.filter(field=>field.kind==='secret').map(field=>[field.name,Boolean(vars[field.name])]))};
+ if(!options.nonInteractive&&!options.json&&process.stdin.isTTY){
+  const asked=new Set();
+  for(;;){
+   const required=seed.model.setupModel(answers,known).missing;
+   const key=required.find(key=>!asked.has(key)&&seed.model.fieldVisible(key,answers));
+   if(!key)break;
+   asked.add(key);
+   const field=seed.model.fieldDefinition(key,answers);
+   if(field.kind==='secret'&&field.input!=='entered')continue;
+   const choices=field.options?.map(([value])=>value).join(' | ');
+   const label=`${field.label??key} (${key})${choices?` [${choices}]`:''}: `;
+   answers[key]=await question(label,field.type==='password',signal);
+  }
+ }
+ const invalidKeys=Object.entries(answers).filter(([key,value])=>!seed.model.fields[key]||(value!==''&&value!==undefined&&!seed.model.fields[key].valid(value))).map(([key])=>key);
+ const missingKeys=seed.model.setupModel(answers,known).missing;
+ const keys=[...new Set([...missingKeys,...invalidKeys])];
+ if(keys.length){
+  // Only declared metadata and example choices are public, never supplied values.
+  const shape={},details=keys.map(key=>{
+   const field=Object.hasOwn(seed.model.fields,key)?seed.model.fields[key]:undefined;
+   if(!field)return '(undeclared field)';
+   const privateValue=field.type==='password',choices=privateValue?undefined:field.options?.map(([value])=>value);
+   const type=privateValue?'secret':field.kind??(choices?'select':field.type??'text');
+   shape[key]=privateValue?'<private value>':choices?.[0]??'<value>';
+   return `${key} (${type}${choices?`; choices: ${choices.map(value=>JSON.stringify(value)).join(' | ')}`:''})`;
+  });
+  throw missing(`Missing or invalid active setup fields: ${details.join(', ')}. Create an owner-only JSON file (chmod 600 answers.json) shaped ${JSON.stringify(shape)}, then run rer setup --answers answers.json --non-interactive. --owner-email EMAIL and --owner-name NAME are also accepted when declared; use manifest field names inside the JSON, never an environment-file wrapper.`);
+ }
+ if(!mailbox(answers[names.email]))throw invalid('Provide a valid plain owner mailbox.');
+ answers[names.email]=answers[names.email].toLowerCase();
+ const {assertLocalOwner}=await shared('local/owner.mjs');
+ const owners=await assertLocalOwner(project.root,answers[names.email],message=>refuse(message),project.adapter.hooks?.localOwner,`${names.email} in ${project.adapter.hooks?.secrets?.file??'.dev.vars'}`);
+ if(savedEmail&&!mailbox(savedEmail))throw refuse('Saved owner is malformed. Restore private settings or run rer reset --yes.');
+ if(savedEmail&&savedEmail.toLowerCase()!==answers[names.email]){
+  if(owners.length)throw refuse(`Private setting ${names.email} differs from the retained database owner. Restore ${names.email} in ${project.adapter.hooks?.secrets?.file??'.dev.vars'} to ${answers[names.email]}, then run rer setup --owner-email ${answers[names.email]}; or back up data and run rer reset --yes. Private bytes were kept.`);
+  throw refuse(`Owner conflicts with the saved installation (${savedEmail}). Run rer setup --owner-email ${savedEmail}, or back up data and run rer reset --yes.`);
+ }
+
+ try{return seed.model.validateInput(answers,known);}catch{throw missing('Installer answers are incomplete. Supply the active manifest fields using rer setup --answers answers.json --non-interactive.');}
+}
+
+async function question(label,privateValue,signal){
+ let muted=false;
+ const output=new Writable({write(chunk,_encoding,done){if(!muted)process.stderr.write(chunk);done();}});
+ const prompt=createInterface({input:process.stdin,output,terminal:true});
+ prompt.on('SIGINT',()=>process.kill(process.pid,'SIGINT'));
+ const closed=new Promise((_,reject)=>prompt.once('close',()=>reject(missing('Terminal input closed before setup answers were complete. Use rer setup --answers answers.json --non-interactive.'))));
+ try{const pending=prompt.question(label+'\n',{signal});muted=privateValue;return await Promise.race([pending,closed]);}finally{prompt.close();muted=false;output.end();if(privateValue)process.stderr.write('\n');}
+}
+
+// A generated value goes only into the answers, which setup writes to the
+// checkout's 0600 private settings and registers for redaction.
+function applyLocalDefaults(seed,answers,vars,origin){
+ for(const field of seed.manifest.fields){
+  const value=field.localDefault;
+  if(value===undefined||answers[field.name]||vars[field.name]||!seed.model.fieldVisible(field.name,answers))continue;
+  answers[field.name]=typeof value==='string'?value:value.generate?randomBytes(32).toString(value.generate):origin;
+ }
+}

package/cli/shared.mjs

@@ -0,0 +1,7 @@
+import { basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The only relocation boundary. The portable inventory mirrors Base's cli,
+// modules and operations topology, while reusing the seed's one onboarding copy.
+const portable = basename(dirname(fileURLToPath(new URL('../', import.meta.url)))) === 'scripts';
+export const onboardingURL = new URL(portable ? '../../base-onboarding/' : '../onboarding/', import.meta.url);
+export const shared = file => import(new URL(file, onboardingURL));