@runeditrun/rer 0.0.0-stage → 0.1.0

package/cli/jsonc.mjs

@@ -0,0 +1,111 @@
+function location(text, position) {
+ const lines = text.slice(0, position).split('\n');
+ return `position ${position} (line ${lines.length} column ${lines.at(-1).length + 1})`;
+}
+
+// Validate JSONC before JSON.parse so diagnostics do not depend on the Node
+// version's error wording. An explicit stack also handles deeply nested input.
+// Only comments and commas accepted by the grammar are masked; offsets stay in
+// the original source and comment removal can never join separate tokens.
+export function parseJsonc(text) {
+ const result = text.split(''), stack = [{ kind: 'root', state: 'value' }];
+ let index = 0;
+ const fail = (message, position = index) => {
+  throw new SyntaxError(`${position === text.length ? 'Unexpected end of JSON input' : message} at ${location(text, position)}`);
+ };
+ const unterminated = (kind, start) => {
+  throw new SyntaxError(`Unterminated ${kind} at ${location(text, start)}; close the ${kind}.`);
+ };
+ const blank = start => {
+  for (let i = start; i < index; i++) if (text[i] !== '\n' && text[i] !== '\r') result[i] = ' ';
+ };
+ const space = () => {
+  while (index < text.length) {
+   if (' \t\r\n'.includes(text[index])) { index++; continue; }
+   const start = index;
+   if (text[index] === '/' && text[index + 1] === '/') {
+    index += 2;
+    while (index < text.length && text[index] !== '\n' && text[index] !== '\r') index++;
+   } else if (text[index] === '/' && text[index + 1] === '*') {
+    const end = text.indexOf('*/', index + 2);
+    if (end === -1) unterminated('block comment', start);
+    index = end + 2;
+   } else break;
+   blank(start);
+  }
+ };
+ const string = () => {
+  const start = index++;
+  let end = index;
+  while (end < text.length && text[end] !== '"') end = Math.min(text.length, end + (text[end] === '\\' ? 2 : 1));
+  if (end === text.length) unterminated('string', start);
+  while (index < end) {
+   if (text.charCodeAt(index) < 32) fail('Unescaped control character in string');
+   if (text[index++] !== '\\') continue;
+   if (text[index] === 'u') {
+    index++;
+    for (let digit = 0; digit < 4; digit++, index++) {
+     if (index >= end || !/[0-9a-fA-F]/.test(text[index])) fail('Invalid Unicode escape');
+    }
+   } else {
+    if (!'"\\/bfnrt'.includes(text[index])) fail('Invalid string escape');
+    index++;
+   }
+  }
+  index++;
+ };
+ const digit = () => index < text.length && text[index] >= '0' && text[index] <= '9';
+ const digits = () => {
+  if (!digit()) fail('Expected a digit');
+  do { index++; } while (digit());
+ };
+ const number = () => {
+  if (text[index] === '-') index++;
+  if (text[index] === '0') index++;
+  else digits();
+  if (text[index] === '.') { index++; digits(); }
+  if (text[index] === 'e' || text[index] === 'E') {
+   index++;
+   if (text[index] === '+' || text[index] === '-') index++;
+   digits();
+  }
+ };
+ while (stack.length) {
+  space();
+  const frame = stack.at(-1), char = text[index], closing = frame.kind === 'object' ? '}' : ']';
+  if (frame.state === 'end') {
+   if (index < text.length) fail('Unexpected token after JSON value');
+   stack.pop();
+  } else if ((frame.state === 'keyOrEnd' || frame.state === 'valueOrEnd' || frame.state === 'comma') && char === closing) {
+   index++; stack.pop();
+  } else if (frame.state === 'keyOrEnd') {
+   if (char !== '"') fail('Expected a property name');
+   string(); frame.state = 'colon';
+  } else if (frame.state === 'colon') {
+   if (char !== ':') fail("Expected ':' after property name");
+   index++; frame.state = 'value';
+  } else if (frame.state === 'comma') {
+   if (char !== ',') fail(`Expected ',' or '${closing}'`);
+   const comma = index++;
+   space();
+   if (text[index] === closing) result[comma] = ' ';
+   frame.state = frame.kind === 'object' ? 'keyOrEnd' : 'valueOrEnd';
+  } else {
+   frame.state = frame.kind === 'root' ? 'end' : 'comma';
+   if (char === '{' || char === '[') {
+    index++;
+    stack.push({ kind: char === '{' ? 'object' : 'array', state: char === '{' ? 'keyOrEnd' : 'valueOrEnd' });
+   } else if (char === '"') string();
+   else if (char === '-' || digit()) number();
+   else {
+    const literal = { t: 'true', f: 'false', n: 'null' }[char];
+    if (!literal) fail('Unexpected token in JSON value');
+    for (const expected of literal) {
+     if (text[index] !== expected) fail(`Expected '${literal}'`);
+     index++;
+    }
+   }
+  }
+ }
+ return JSON.parse(result.join(''));
+}

package/cli/lifecycle.mjs

@@ -0,0 +1,148 @@
+import { createHmac } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { dependencyInputs } from './dependency-input.mjs';
+import { linkDependencies } from './dependencies.mjs';
+import { savedSetupAnswers } from './setup-answers.mjs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { shared } from './shared.mjs';
+import { tools, doctor } from './inspect.mjs';
+import { availablePort, selectedOrigin, setupInput, stateSafety, refuseLegacyProcess } from './local.mjs';
+import { missing, refuse, RerError, lifecycleError } from './errors.mjs';
+import { executeDeclared } from './independent.mjs';
+import { transfer } from './transfers.mjs';
+import { runtimeFrontDoor } from './runtime-front-door.mjs';
+import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
+import { rememberSetupAnswers } from './setup-answers.mjs';
+import { ensureDevKey, readDevKey, refuseDevLayerOutput, openUrl, DEV_KEY_HEADER } from './dev-identity.mjs';
+
+export async function runCommand(project, options, out) {
+ if(project.profile==='first-party'&&['dev','preview'].includes(options.verb))return (await import('./managed-server.mjs')).managedServer(project,options,out);
+ const cancellation = new AbortController(), signal = cancellation.signal;
+ let termination, operation, store, temporary, proxy;
+ const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { if (!termination) { termination = name; cancellation.abort(name); } }]));
+ for (const [name, handler] of handlers) process.on(name, handler);
+ try {
+  let selected, input;
+  if (project.profile === 'first-party') {
+   if (project.adapter?.setup) {
+    const { loadInstallerSeed } = await shared('setup-manifest.mjs');
+    try { project.setupSeed = await loadInstallerSeed(project.root, project.adapter); }
+    catch (error) { throw new RerError('invalid_setup_manifest', `The declared setup manifest or presentation is invalid. ${String(error.message).replace(/\.?$/, '.')} Correct or restore its sources before retrying.`, 2); }
+    project.setupManifest = project.setupSeed.manifest;
+   }
+  }
+  if (project.profile === 'first-party' && options.verb !== 'doctor') {
+   if (!project.adapter?.run) throw refuse('The first-party command adapter is unavailable. Restore the shared lifecycle adapter.');
+   if (options.forwarded.length) throw refuse('First-party commands do not accept arbitrary forwarded arguments. Run rer VERB --help.');
+   await stateSafety(project);
+   if(options.verb==='setup')await refuseLegacyProcess(project);
+   if (['setup', 'outbox'].includes(options.verb)) {
+    selected = await selectedOrigin(project, options, { setup: options.verb === 'setup' });
+    if (options.verb === 'setup') {input = await setupInput(project, options, selected.vars, signal, { origin: selected.url });await dependencyInputs({project,input,origin:selected.url});}
+    else if (requiredLocalSettings(project, selected.vars).length) throw missing('Private owner settings are missing. Run rer setup --owner-email EMAIL first.');
+    if (options.verb !== 'outbox') await availablePort(selected.host, selected.port, { root: project.root, saved: !selected.explicitPort && selected.savedOrigin !== undefined });
+    if (options.verb === 'setup') announcePort(out, options, selected);
+   }
+   const { localOperation } = await shared('local/operation.mjs');
+   if (options.verb !== 'outbox') try { operation = await localOperation(project.root, process.env.RER_LOCAL_OPERATION); } catch (error) { throw refuse(error.message); }
+   const { recoverInterrupted } = await shared('local/recovery.mjs');
+   if (operation) await recoverInterrupted(project.root, operation);
+  }
+  const { createCommands } = await shared('commands.mjs');
+  const { privateDirectory } = await shared('private-files.mjs');
+  // Nested public commands stream into their caller's capture and keep their
+  // own log separate, including the browser install/setup/preview journey.
+  const capture = ['.seed', 'installer', ...(process.env.RER_LOCAL_OPERATION || process.env.RER_ONBOARDING_PROCESS_OWNER ? [`commands-${process.pid}`] : [])];
+  const directory = project.profile === 'first-party' && !['outbox', 'doctor'].includes(options.verb) ? await privateDirectory(project.root, capture) : (temporary = await mkdtemp(join(tmpdir(), 'rer-command-')));
+  const state = { logs: [] };
+  store = await createCommands(directory, state, { terminal: text => out.progress(text), onWaiting: options.json ? details => out.event('waiting', details) : undefined, queue: ['install','setup','build','verify','deploy','export','import'].includes(options.verb)?{verb:options.verb,originalCI:process.env.CI==='true'}:undefined });
+  store.state = state;
+  store.setupManifest = project.setupManifest;
+  store.step = async label => { state.step = store.redact(label); store.report(label); };
+  store.phase = async phase => { state.phase = phase; };
+  store.setCommandSignal(signal);
+  if (options.verb === 'doctor') return await doctor(project, store, signal);
+  if (project.profile === 'independent') return await executeDeclared(project, options, store, signal);
+  await tools(project.root, store, signal);
+  const adapter = project.adapter;
+  if (options.verb === 'install') {
+   await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...process.env, CI: 'true' } }); return {};
+  }
+  if (options.verb === 'verify') {
+   const target = adapter.verify;
+   if (!Array.isArray(target)) throw refuse('A complete internal verification target is missing.');
+   await store.run('Verifying application', target[0], target[1], { cwd: project.root, signal, env: { ...process.env, RER_LOCAL_OPERATION: operation.token } });
+   await store.step('Serving the production build as rer deploy hosts it');
+   return { hosted: await (await import('./hosted-output.mjs')).checkHostedOutput(project.root, { declaration: adapter.deployDeclaration ?? adapter.deploy?.declaration }) };
+  }
+  if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
+  if (options.verb === 'deploy') {
+   if (typeof adapter.deploy !== 'function') throw refuse('Owner-account deploy declaration is missing.');
+   const deployed = await adapter.deploy({ root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity) });
+   if(deployed.deployed && !options.dryRun) await linkDependencies({project,input:await savedSetupAnswers(project,project.setupSeed.model),origin:deployed.origin,store,signal,appSetupToken:process.env[project.setupManifest?.steps.find(step=>step.type==='owner-claim')?.tokenField??'SETUP_TOKEN']});
+   return deployed;
+  }
+  // Setup writes the checkout's dev key; its temporary app and the CLI's own
+  // outbox reads present it. Captured logs redact it.
+  const devKey = adapter.devIdentity ? options.verb === 'setup' ? await ensureDevKey(project.root) : await readDevKey(project.root) : null;
+  if (devKey) store.addSecrets?.([devKey]);
+  let app;
+  if (options.verb === 'setup') proxy = await runtimeFrontDoor(selected);
+  const emailKey = localSettingKeys(project).email;
+  await adapter.run(project.root, input ?? { [emailKey]: options.ownerEmail ?? selected?.vars[emailKey] }, store,
+   child => { app = child; }, signal,
+   { verb: options.verb, ownerKey: emailKey, selectedOrigin: selected?.url, runtimePort: proxy?.runtimePort, operationToken: operation?.token, dev: adapter.dev, privateSettings: [...adapter.settings, '.rer/local/models.json', ...(project.privateInputs??[])], signInEmail: options.verb === 'outbox' ? options.ownerEmail : undefined, requestSignIn: Boolean(options.ownerEmail), devKey: devKey ?? undefined });
+  if (['setup', 'build'].includes(options.verb)) await refuseDevLayerOutput(project.root, adapter.devIdentity);
+  const url = selected?.url, signInUrl = url ? url + '/__dev/outbox' : undefined;
+  if (options.verb === 'setup') {
+   await linkDependencies({project,input,origin:url,store,signal});
+   if(project.setupManifest?.dependencies?.length) {
+    const { localVariables }=await shared('local/environment.mjs');
+    const values=localVariables(await readFile(new URL(project.adapter.hooks?.secrets?.file??'.dev.vars','file://'+project.root+'/'),'utf8'));
+    const proof=createHmac('sha256',values.SESSION_SECRET).update('local-cli\0sign-in').digest('hex');
+    store.addSecrets?.([proof]);
+    const completed=await fetch(url+'/auth/setup-complete',{method:'POST',headers:{Origin:url,'Content-Type':'application/json','x-rer-local-cli':proof},body:'{}',signal});
+    if(!completed.ok)throw missing('The dependency setup has not completed an owner claim.');
+    await completed.body?.cancel();
+   }
+   await store.stop(app);
+   await rememberSetupAnswers(project, input);
+   if (options.json) out.event('setup-ready', { url, signInUrl, setupUrl: url+'/setup' });
+   else if (devKey) { out.human(`RER_SETUP_READY ${url}`); out.human(`Next: rer dev opens ${url} signed in as the owner; first-run setup finishes at ${url}/setup.`); }
+   else { out.human(`RER_SETUP_READY ${url}`); signInInstructions(out, signInUrl); out.human(`Finish first-run setup at ${url}/setup after sign-in.`); out.human('Next: rer dev'); }
+  } else if (options.verb === 'outbox') {
+   const response = await fetch(signInUrl, { headers: devKey ? { [DEV_KEY_HEADER]: devKey } : {}, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) });
+   if (!response.ok) throw new RerError('outbox_unavailable', 'The local application outbox is unavailable. Start rer dev first.', 1);
+   await response.body?.cancel();
+   const open = devKey ? openUrl(url, devKey, { path: '/__dev/key', next: '/__dev/outbox' }) : signInUrl;
+   if (options.json) out.event('outbox', { signInUrl, ...(devKey ? { openUrl: open } : {}) }); else { signInInstructions(out, signInUrl); if (devKey) out.human(`RER_OPEN ${open}`); }
+   if (options.open && !options.json && !options.nonInteractive) await store.run('Opening local outbox', process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer.exe' : 'xdg-open', [open], { cwd: project.root, signal });
+  } else if (options.verb !== 'build') throw refuse('The requested first-party capability is unavailable.');
+  return {};
+ } catch (error) {
+  if (error instanceof RerError) throw error;
+  throw await lifecycleError(error, store);
+ } finally {
+  await store?.closeCommands(); await proxy?.close(); await operation?.release();
+  if (temporary) await rm(temporary, { recursive: true, force: true });
+  for (const [name, handler] of handlers) process.removeListener(name, handler);
+  if (termination) throw new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143);
+ }
+}
+
+// One plain line saying which port this checkout uses, and what moved.
+function announcePort(out, options, selected) {
+ const { moved, skipped } = selected;
+ const line = moved ? `Moving this checkout from port ${moved.from} to port ${moved.to}. Its data is kept.`
+  : !selected.savedOrigin ? `Using port ${selected.port} for this checkout${skipped ? ` (${skipped} is in use)` : ''}.` : undefined;
+ if (!line) return;
+ if (options.json) out.event('port', { port: selected.port, ...(moved ? { movedFrom: moved.from } : {}) });
+ else out.human(line);
+}
+
+function signInInstructions(out, url) {
+ out.human(`RER_SIGN_IN ${url}`);
+ out.human('Open the outbox, choose the newest sign-in message and follow its link. No email was sent.');
+}

package/cli/local.mjs

@@ -0,0 +1,100 @@
+import { lstat, readdir, rm } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { createServer } from 'node:net';
+import { createInterface } from 'node:readline/promises';
+import { contained } from './project.mjs';
+import { shared } from './shared.mjs';
+import { origin, loopback } from './parse.mjs';
+import { refuse } from './errors.mjs';
+import { defaultPort, firstFreePort, busyPortMessage } from './port.mjs';
+import { localSettingKeys } from './settings.mjs';
+
+export async function selectedOrigin(project, options, { setup = false } = {}) {
+ const { readSettings } = await shared('adapter-settings.mjs');
+ const vars = project.adapter?.hooks?.secrets ? (await readSettings(project.root, project.adapter.hooks.secrets)).values : {};
+ const { origin: originKey } = localSettingKeys(project);
+ let previous;
+ if (vars[originKey]) {
+  try { previous = new URL(vars[originKey]); } catch { throw refuse('Saved origin is malformed. Restore private settings or use confirmed reset.'); }
+  if (previous.origin !== vars[originKey] || previous.protocol !== 'http:' || !loopback(previous.hostname.replace(/^\[|\]$/g, ''))) throw refuse('Saved origin is unsafe. Restore private settings or use confirmed reset.');
+ }
+ const host = options.host ?? previous?.hostname.replace(/^\[|\]$/g, '') ?? '127.0.0.1';
+ const savedPort = previous ? Number(previous.port || 80) : undefined;
+ // A first setup with no port asked for takes the first free one, never a busy one.
+ let port = options.port ?? savedPort, taken;
+ if (port === undefined && setup) { port = await firstFreePort(host); taken = port !== defaultPort; }
+ port ??= defaultPort;
+ const url = origin(host, port);
+ // Setup on a saved checkout moves it to another port; the host stays.
+ let moved;
+ if (setup && previous && previous.origin !== url) {
+  if (previous.hostname.replace(/^\[|\]$/g, '') !== host) throw refuse('Setup origin conflicts with the saved installation. Reuse its origin or back up data and run rer reset --yes.');
+  moved = { from: savedPort, to: port };
+ }
+ return { url, host, port, vars, savedOrigin: previous?.origin, moved, explicitPort: options.port !== undefined, ...(taken ? { skipped: defaultPort } : {}) };
+}
+
+export async function availablePort(host, port, { root, saved = false } = {}) {
+ const socket = createServer();
+ try { await new Promise((resolve, reject) => { socket.once('error', reject); socket.listen(port, host, resolve); }); }
+ catch (error) {
+  if (error.code !== 'EADDRINUSE') throw refuse(`Port ${port} cannot be used on ${host}: ${error.code ?? error.message}.`);
+  throw refuse(await busyPortMessage({ port, host, root, saved }));
+ }
+ finally { if (socket.listening) await new Promise(resolve => socket.close(resolve)); }
+ // A server on every address (*:port) lets a bind to 127.0.0.1 succeed.
+ const { portListener } = await shared('process-diagnostics.mjs');
+ if (await portListener(port, host)) throw refuse(await busyPortMessage({ port, host, root, saved }));
+}
+
+export {setupInput} from './setup-input.mjs';
+
+export async function stateSafety(project) {
+ const { selectLocalState } = await shared('local/state.mjs');
+ try { await selectLocalState(project.root, project.adapter.state); }
+ catch { throw refuse('Local state placement is unsafe or ambiguous. Preserve legacy state and recover it explicitly before retrying.'); }
+}
+
+async function safeTree(project, path) {
+ const absolute = await contained(project.root, path, { optional: true });
+ let status; try { status = await lstat(absolute); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+ if (status.isSymbolicLink() || (!status.isFile() && !status.isDirectory()) || (process.getuid && status.uid !== process.getuid()) || (status.isFile() && status.nlink !== 1)) throw refuse('Reset inventory contains unsafe or linked storage. Preserve it and resolve placement.');
+ if (status.isDirectory()) for (const entry of await readdir(absolute)) await safeTree(project, relative(project.root, resolve(absolute, entry)));
+ return absolute;
+}
+
+export async function reset(project, options, out) {
+ await stateSafety(project);
+ await refuseLegacyProcess(project,{reset:true});
+ const { strandedOriginals } = await shared('local/recovery.mjs');
+ if ((await strandedOriginals(project.root)).length) throw refuse('An interrupted build holds private settings. Run rer build to recover them before reviewing reset.');
+ const declared = project.adapter.settings ?? [];
+ for (const path of declared) if (!/^\.dev\.vars(?:\.previous)?$|^data\/[a-zA-Z0-9_-]+\.json$/.test(path)) throw refuse('Generated settings inventory is unsafe; declare specific private settings files.');
+ const paths = [...new Set(['.wrangler/state', '.rer/local', '.seed/installer', ...declared])];
+ const inventory = [];
+ for (const path of paths) if (await safeTree(project, path)) inventory.push(path);
+ if (options.json) out.event('inventory', { paths: inventory }); else out.human(`reset inventory: ${inventory.length ? inventory.join(', ') : '(empty)'}`);
+ let confirmed = options.yes;
+ if (!confirmed && !options.json && !options.nonInteractive && process.stdin.isTTY) {
+  const prompt = createInterface({ input: process.stdin, output: process.stderr });
+  try { confirmed = (await prompt.question('Remove exactly this local inventory? Type yes: ')) === 'yes'; } finally { prompt.close(); }
+ }
+ if (!confirmed) throw refuse('Reset requires explicit confirmation. Review the inventory, then pass --yes.');
+ // The shared lock lives outside every removal path and remains held throughout.
+ const { localOperation } = await shared('local/operation.mjs');
+ let operation;
+ try { operation = await localOperation(project.root); } catch (error) { throw refuse(error.message); }
+ try {
+  for (const path of inventory) { const absolute = await safeTree(project, path); if (absolute) await rm(absolute, { recursive: true, force: true }); }
+ } finally { await operation.release(); }
+ return { paths: inventory };
+}
+
+export async function refuseLegacyProcess(project,{reset=false}={}) {
+ let selected;try{selected=await selectedOrigin(project,{});}catch(error){if(!reset)throw error;}
+ // Confirmed reset can recover malformed settings; checkout/state custody is
+ // still checked even when there is no usable saved origin.
+ const {localProcessConflict}=await shared('process-diagnostics.mjs');
+ const conflict=await localProcessConflict(project.root,selected?.savedOrigin);
+ if(conflict)throw refuse(`A local process holds ${conflict.reason}: PID ${conflict.pid} (${conflict.command}). Stop it with kill -TERM ${conflict.pid}, then retry. Use rer dev --stop or rer preview --stop for a registered server.`);
+}

package/cli/main.mjs

@@ -0,0 +1,57 @@
+import { parse, help } from './parse.mjs';
+import { output } from './output.mjs';
+import { invalid, RerError } from './errors.mjs';
+import { resolveProject, parsingProfile } from './project.mjs';
+import { check, describe } from './inspect.mjs';
+import { selectNodeRuntime } from './node-runtime.mjs';
+
+export async function main(argv = process.argv.slice(2)) {
+ // Every runtime a seed's hooks start inherits this: Wrangler and the Cloudflare
+ // Vite plugin otherwise serve the Local Explorer, which reads and writes the
+ // store without the dev key.
+ process.env.X_LOCAL_EXPLORER = 'false';
+ let options = { verb: argv[0], json: argv.includes('--json') }, out = output(options);
+ try {
+  options = parse(argv,process.cwd(),{deferTail:true}); out = output(options);
+  if (options.help) return showHelp(options,out);
+  if (options.verb === 'archive') return (await import('./archive.mjs')).archiveCommand(options.archiveArgs,out);
+  if (options.verb === 'release') return (await import('./release.mjs')).dispatchRelease(options.releaseArgs);
+  const independent = await parsingProfile(options.cwd)==='independent'&&!['describe','check','doctor'].includes(options.verb);
+  options=parse(argv,process.cwd(),{independent});out=output(options);
+  if (options.help) return showHelp(options,out);
+  if (!independent && options.forwarded.length) throw invalid('First-party commands accept only the documented flags, without forwarded arguments.');
+  if(options.noQueue){const {shared}=await import('./shared.mjs');const {commandPolicy}=await shared('queue.mjs');const policy=await commandPolicy();try{if(!policy.ci)throw invalid('--no-queue requires the original caller CI=true.');}finally{await policy.close();}}
+  const runtime = await selectNodeRuntime(options, argv, out);
+  if (runtime) return runtime.exitCode;
+  const project = await resolveProject(options.cwd);
+  if (project.profile === 'independent' && !['describe', 'check', 'doctor'].includes(options.verb)) options = parse(argv, process.cwd(), { independent: true });
+  else if (options.forwarded.length) throw invalid('First-party commands accept only the documented flags, without forwarded arguments.');
+  out = output(options);
+  if (options.verb === 'describe') { const result = await describe(project); out.human(options.json ? JSON.stringify(result) : JSON.stringify(result, null, 2)); return 0; }
+  if (options.verb === 'check') {
+   const result = await check(project, options.profile);
+   if (!options.json) for (const clause of result.clauses.filter(c => !c.ok)) out.human(`${clause.id}: ${clause.message}`);
+   out.result(result.ok, result.ok ? 0 : 1, { clauses: result.clauses }); return result.ok ? 0 : 1;
+  }
+  if (options.verb === 'doctor') {
+   const result = await (await import('./lifecycle.mjs')).runCommand(project, options, out);
+   if (!options.json) out.human(JSON.stringify(result, null, 2));
+   out.result(result.ok, result.ok ? 0 : 3, { diagnostics: result }); return result.ok ? 0 : 3;
+  }
+  const bounded=await (await import('./bounded.mjs')).boundedCommand(project,options,argv,out);
+  if(bounded)return bounded.exitCode;
+  if(options.platform==='container' && !['export','import'].includes(options.verb)) { const result = await (await import('./container.mjs')).containerCommand(project,options,out); out.result(true,0,result); return 0; }
+  let result;
+  if (options.verb === 'reset' && project.profile === 'first-party') result = await (await import('./local.mjs')).reset(project, options, out);
+  else result = await (await import('./lifecycle.mjs')).runCommand(project, options, out);
+  out.result(true, 0, result); return 0;
+ } catch (error) {
+  const failure = error instanceof RerError ? error : new RerError('command_failed', 'Command failed; inspect the project operating documentation.', 1);
+  out.error(failure); out.result(false, failure.exitCode, failure.childExitCode === undefined ? {} : { childExitCode: failure.childExitCode, signal: failure.signal }); return failure.exitCode;
+ }
+}
+
+function showHelp(options,out) {
+ if(options.json){out.event('help',{usage:help(options.verb)});out.result(true,0);}else out.human(help(options.verb));
+ return 0;
+}

package/cli/managed-server.mjs

@@ -0,0 +1,143 @@
+import { prepareLiveModels } from './ai-local.mjs';
+import {fileURLToPath} from 'node:url';
+import { serverRegistry } from './server-registry.mjs';
+import { activityClock } from './server-activity.mjs';
+import { runtimeFrontDoor } from './runtime-front-door.mjs';
+import {serverResources} from './server-resources.mjs';
+import { productionBuild } from './preview-cache.mjs';
+import {localSettingKeys} from './settings.mjs';
+import { shared } from './shared.mjs';
+import { availablePort,selectedOrigin,stateSafety,refuseLegacyProcess } from './local.mjs';
+import { tools } from './inspect.mjs';
+import { invalid,missing,refuse,RerError,lifecycleError } from './errors.mjs';
+import { processInfo } from '../modules/job-queue/processes.mjs';
+import { declaredCrons,runScheduled } from './scheduled.mjs';
+import { readDevKey,requireDevKey,refuseManagedInstallation,resolvePersona,openUrl,DEV_KEY_HEADER } from './dev-identity.mjs';
+
+// Seeds without devIdentity keep the outbox sign-in unchanged. With it, dev
+// opens signed in (RER_SIGNED_IN, RER_OPEN); --login and preview keep the
+// outbox, reached through RER_OPEN's one-time key exchange. A runtime that
+// serves no outbox (a seed's preview without one) is not pointed at it.
+export function ready(out,url,dev,json=false,outbox=true){
+ const signInUrl=url+'/__dev/outbox',open=dev&&(dev.identity||outbox);
+ if(json){out.event('ready',{url,...(outbox?{signInUrl}:{}),...(dev?{signedInAs:dev.signedInAs??null,...(open?{openUrl:dev.openUrl}:{})}:{})});return;}
+ out.human(`RER_READY ${url}`);
+ if(dev?.identity){if(dev.signedInAs)out.human(`RER_SIGNED_IN ${dev.signedInAs}`);out.human(`RER_OPEN ${dev.openUrl}`);out.human('Open that link on this computer. Its fragment holds this checkout\'s dev key, which the page keeps only as a cookie; never share the link.');return;}
+ if(!outbox)return;
+ out.human(`RER_SIGN_IN ${signInUrl}`);
+ if(dev)out.human(`RER_OPEN ${dev.openUrl}`);
+ out.human(`Open ${dev?'the last link on this computer (it carries the dev key; never share it)':'the outbox'}, choose the newest sign-in message and follow its link. No email was sent.`);
+}
+export async function managedServer(project,options,out,{clock={}}={}){
+ const registry=await serverRegistry(project.root),controller=new AbortController();
+ let store,operation,proxy,activity,app,termination,reason,cleanupPromise,finished,selected,cleaned;
+ const scheduling=new AbortController();
+ let activityWrites=Promise.resolve(),pendingActivity,activityWriting=false,infrastructureFailure;
+ function recordActivity(fields){
+  pendingActivity=fields;if(activityWriting)return;activityWriting=true;
+  activityWrites=(async()=>{while(pendingActivity){const latest=pendingActivity;pendingActivity=undefined;await registry.updateActivity(latest);}})().catch(error=>{infrastructureFailure=error;void stop('activity bookkeeping failed');}).finally(()=>{activityWriting=false;if(pendingActivity)recordActivity(pendingActivity);});
+ }
+ const stopped=new Promise(resolve=>{finished=resolve;});
+ const cleanupDone=new Promise(resolve=>{cleaned=resolve;});
+ const cleanup=()=>cleanupPromise??=(async()=>{scheduling.abort();activity?.close();await store?.closeCommands();await proxy?.close();await operation?.release();})();
+ const stop=async why=>{reason??=why;controller.abort();finished();await cleanupDone;return {};};
+ const handlers=new Map(['SIGINT','SIGTERM'].map(name=>[name,()=>{termination=name;void stop(name);} ]));
+ for(const [name,handler]of handlers)process.on(name,handler);
+ try{
+  if(options.stop){await registry.stop(options.verb,options);return {};}
+  controller.signal.throwIfAborted();
+  const devIdentity=project.adapter.devIdentity;
+  if(options.as!==undefined&&!(devIdentity&&options.verb==='dev'))throw invalid('--as needs a seed that declares devIdentity.');
+  let devKey=devIdentity?await readDevKey(project.root):null;
+  let current=await registry.existing(options.verb,options);
+  if(!current){
+   const reservation=await registry.reserve(options.verb,options);
+   current=reservation.existing;
+  }
+  if(current){
+   // Resolve a competing reservation through the same explicit-option check.
+   current=await registry.existing(options.verb,options);
+   const running=await registry.waitReady(current,controller.signal);
+   await registry.existing(options.verb,options);
+   if(options.verb==='dev' && (running.models??'fake')!==(options.models??'fake'))throw refuse('Stop the running dev server before changing --models mode.');
+   if(options.modelsService)throw refuse('Stop the running dev server before saving live-dev credentials.');
+   if(options.verb==='dev'&&Boolean(running.login)!==Boolean(options.login))throw refuse(`The running dev server ${running.login?'uses':'does not use'} --login. Stop it with rer dev --stop to change sign-in mode.`);
+   const response=await fetch(running.url+'/health',{headers:{'x-rer-probe':running.probe},signal:AbortSignal.timeout(5000)});
+   if(!response.ok || (await response.json()).status!=='ok')throw refuse('Registered application failed health verification. Stop it before retrying.');
+   if(devIdentity)devKey=await requireDevKey(project.root);
+   emitReady(out,options,running.url,devIdentity&&await devReady(running.url,devKey,options,controller.signal));return {reused:true};
+  }
+  await registry.serve(async action=>{
+   if(action==='status')return {...activity?.snapshot(),url:selected?.url,probe:proxy?.probe};
+   if(action==='stop')return stop('explicit stop');
+   throw Error('Unknown management operation');
+  });
+  await stateSafety(project);
+  await refuseLegacyProcess(project);
+  const {localOperation}=await shared('local/operation.mjs');
+  try{operation=await localOperation(project.root);}catch(error){throw refuse(error.message);}
+  const {recoverInterrupted}=await shared('local/recovery.mjs');await recoverInterrupted(project.root,operation);
+  const {loadInstallerSeed}=await shared('setup-manifest.mjs');
+  const seed=project.adapter.setup?await loadInstallerSeed(project.root,project.adapter):undefined;project.setupManifest=seed?.manifest;
+  const keys=localSettingKeys(project);
+  selected=await selectedOrigin(project,options);
+  await availablePort(selected.host,selected.port,{root:project.root,saved:!selected.explicitPort&&selected.savedOrigin!==undefined});
+  if(!selected.vars[keys.email])throw missing('Private owner settings are missing. Run rer setup first.');
+  if(devIdentity&&!devKey)devKey=await requireDevKey(project.root);
+  if(devIdentity&&options.verb==='dev'&&!options.login)refuseManagedInstallation(selected.vars,process.env);
+  if(project.adapter.localPrerequisites&&!await project.adapter.localPrerequisites({root:project.root,vars:selected.vars,email:selected.vars[keys.email]}))throw missing('Local migrations, owner or local authentication/mail settings are missing. Run rer setup first.');
+  await registry.update({url:selected.url,host:selected.host,port:selected.port,login:Boolean(options.login),models:options.models??'fake'});
+  const {privateDirectory}=await shared('private-files.mjs');
+  await privateDirectory(project.root,['.wrangler','state']);
+  const directory=await privateDirectory(project.root,['.seed','installer',...(process.env.RER_ONBOARDING_PROCESS_OWNER?[`commands-${process.pid}`]:[])]);
+  const {createCommands}=await shared('commands.mjs');const state={logs:[]};
+  store=await createCommands(directory,state,{terminal:text=>out.progress(text),onWaiting:options.json?details=>out.event('waiting',details):undefined,custodyToken:registry.custodyToken(),queue:{verb:options.verb,originalCI:process.env.CI==='true'}});
+  store.state=state;store.step=async label=>store.report(label);store.phase=async phase=>{state.phase=phase;};store.setCommandSignal(controller.signal);
+  store.setupManifest=seed?.manifest;if(devKey)store.addSecrets([devKey]);
+  await tools(project.root,store,controller.signal);
+  activity=activityClock({...clock,seconds:options.idleTimeout,onIdle:()=>void stop('idle timeout'),onChange:recordActivity});
+  const crons=project.adapter.scheduled!==false?await declaredCrons(project.root,project.adapter).catch(error=>{throw refuse(`The declared scheduled triggers cannot run locally: ${error.message}`);}):[];
+  proxy=await runtimeFrontDoor({host:selected.host,port:selected.port,activity});const internal=proxy.runtimePort;
+  const modelsLive = options.verb==='dev' ? await prepareLiveModels(project.root,options,store,controller.signal) : undefined;
+  const adapterOptions={modelsLive,selectedOrigin:selected.url,operationToken:operation.token,privateSettings:project.adapter.settings,runtimePort:internal,devKey:devKey??undefined,devLogin:Boolean(options.login),scheduled:crons.length>0};
+  const input={[keys.email]:selected.vars[keys.email]};
+  if(options.verb==='preview')await productionBuild(project,()=>store.run('Building fixed production output',process.execPath,[fileURLToPath(new URL('../bin/rer.mjs',import.meta.url)),'build','--cwd',project.root,'--json'],{cwd:project.root,phase:'build',signal:controller.signal,env:{...process.env,RER_LOCAL_OPERATION:operation.token},afterCommand:()=>recoverInterrupted(project.root,operation)}),text=>store.report(text));
+  await serverResources(project.root);
+  await project.adapter.run(project.root,input,store,async child=>{
+   app=child;
+   child.once('exit',code=>{if(!reason){reason='unexpected application exit';void cleanup().then(()=>finished({code:code||1}));}});
+   const identity=await processInfo(child.pid);
+   if(!identity)throw Error('Runtime exited before custody registration.');
+   await registry.update({runtimeProcess:{pid:identity.pid,start:identity.start}});
+  },controller.signal,{...adapterOptions,verb:options.verb,dev:project.adapter.dev,preview:project.adapter.preview});
+  const dev=devIdentity&&await devReady(selected.url,devKey,options,controller.signal);
+  const outbox=await outboxServed(selected.url,devKey,controller.signal);
+  activity.ready();emitReady(out,options,selected.url,dev,outbox);
+  if(crons.length){
+   out.progress(`Running ${crons.length===1?'the scheduled trigger':'the scheduled triggers'} locally: ${crons.join(' | ')}\n`);
+   void runScheduled({crons,url:`http://127.0.0.1:${internal}`,path:options.verb==='preview'?'/cdn-cgi/local/scheduled':undefined,signal:scheduling.signal,report:run=>reportScheduled(out,options,run)});
+  }
+  const result=await stopped;
+  if(termination)throw new RerError('cancelled',`Stopped by ${termination} after owned children were stopped.`,termination==='SIGINT'?130:143);
+  if(infrastructureFailure)throw new RerError('server_bookkeeping_failed','Server bookkeeping failed; owned serving was stopped.',1);
+  if(result?.code)throw new RerError('app_exited','The application stopped unexpectedly.',result.code);
+  out.progress(`Server stopped: ${reason}.\n`);return {};
+ }catch(error){if(termination)throw new RerError('cancelled',`Stopped by ${termination} after owned children were stopped.`,termination==='SIGINT'?130:143);if(['idle timeout','explicit stop'].includes(reason))return {};throw await lifecycleError(error,store);}finally{await cleanup();cleaned();while(activityWriting)await activityWrites;await registry.close();for(const [name,handler]of handlers)process.off(name,handler);}
+}
+function reportScheduled(out,options,run){
+ const at=new Date().toISOString().replace(/\.\d+Z$/,'Z'),outcome=run.skipped?`skipped (${run.error})`:run.ok?`ok ${run.ms}ms`:`failed (${run.status?`HTTP ${run.status}`:run.error}) ${run.ms}ms`;
+ if(options.json)out.event('scheduled',{at,cron:run.cron,ok:run.ok,skipped:Boolean(run.skipped),status:run.status,ms:run.ms});else out.human(`RER_SCHEDULED ${at} "${run.cron}" ${outcome}`);
+}
+// GET, not HEAD: a seed's outbox route need not answer HEAD. The body is never read.
+async function outboxServed(url,devKey,signal){
+ const response=await fetch(url+'/__dev/outbox',{headers:devKey?{[DEV_KEY_HEADER]:devKey}:{},signal});
+ await response.body?.cancel();
+ return response.ok;
+}
+function emitReady(out,options,url,dev,outbox){ready(out,url,dev||undefined,options.json,outbox);}
+async function devReady(url,key,options,signal){
+ if(options.verb==='preview')return {openUrl:openUrl(url,key,{path:'/__dev/key',next:'/__dev/outbox'})};
+ if(options.login)return {openUrl:openUrl(url,key,{next:'/__dev/outbox'})};
+ const as=options.as??'owner',persona=await resolvePersona(url,key,as,signal);
+ return {identity:true,signedInAs:persona.email??null,openUrl:openUrl(url,key,{path:'/__dev/key',as})};
+}

package/cli/node-runtime-cache.mjs

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { missing } from './errors.mjs';
+
+export const nodeCache = () => join(homedir(), '.rer', 'node');
+export const runtimeName = version => `node-v${version}-${process.platform}-${process.arch}`;
+export const runtimeBinary = directory => join(directory, ...(process.platform === 'win32' ? ['node.exe'] : ['bin', 'node']));
+export const shellQuote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+export async function binaryDigest(path) {
+ const hash = createHash('sha256');
+ for await (const chunk of createReadStream(path)) hash.update(chunk);
+ return hash.digest('hex');
+}
+async function owned(path, directory) {
+ const stat = await lstat(path);
+ if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()) || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o022)) throw Error('Unsafe runtime cache placement.');
+}
+export async function prepareNodeCache() {
+ const cache = nodeCache();
+ for (const path of [join(homedir(), '.rer'), cache]) {
+  await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+  try { await owned(path, true); } catch { throw missing(`Node cache directory must be an owned, non-linked directory without group/other write access: ${path}. Correct its placement and permissions before retrying.`); }
+ }
+ return cache;
+}
+export async function cachedRuntime(version) {
+ const directory = join(nodeCache(), runtimeName(version));
+ try { await lstat(directory); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+ try {
+  await owned(join(homedir(), '.rer'), true); await owned(nodeCache(), true); await owned(directory, true);
+  const binary = runtimeBinary(directory), receipt = join(directory, '.rer-verified.json');
+  if (process.platform !== 'win32') await owned(join(directory, 'bin'), true);
+  await owned(binary, false); await owned(receipt, false);
+  const record = JSON.parse(await readFile(receipt, 'utf8'));
+  if (record.version !== version || !/^[a-f0-9]{64}$/.test(record.releaseSha256) || record.binarySha256 !== await binaryDigest(binary)) throw Error('Node cache integrity mismatch.');
+  return binary;
+ } catch {
+  throw missing(`The cached Node runtime is unsafe or incomplete. Preserve it for inspection with: mv ${shellQuote(directory)} ${shellQuote(directory + '.quarantine-' + Date.now())}. Then rerun the original rer command to acquire a verified release.`);
+ }
+}
+export async function recordRuntime(directory, version, releaseSha256) {
+ await writeFile(join(directory, '.rer-verified.json'), JSON.stringify({ version, releaseSha256, binarySha256: await binaryDigest(runtimeBinary(directory)) }) + '\n', { flag: 'wx', mode: 0o600 });
+}
+
+// Housekeeping for a runtime whose receipt and binary have just verified. Its
+// quarantined predecessors (renamed aside by the recovery message below) are
+// stale, and Node's C++ headers in include/ are read by nothing rer runs: the
+// seeds' lockfiles hold no package that builds native code. Both cost disk on
+// every Node pin, so they go. A failure here never blocks the command; doctor
+// reports whatever is left.
+export const quarantinePrefix = version => runtimeName(version) + '.quarantine-';
+export async function tidyRuntime(version) {
+ const directory = join(nodeCache(), runtimeName(version));
+ const removable = async path => {
+  const info = await lstat(path).catch(() => undefined);
+  return info?.isDirectory() && !info.isSymbolicLink() && (!process.getuid || info.uid === process.getuid());
+ };
+ try {
+  for (const entry of await readdir(nodeCache())) {
+   if (entry.startsWith(quarantinePrefix(version)) && await removable(join(nodeCache(), entry))) await rm(join(nodeCache(), entry), { recursive: true, force: true });
+  }
+  if (await removable(join(directory, 'include'))) await rm(join(directory, 'include'), { recursive: true, force: true });
+ } catch {}
+}