@runeditrun/rer 0.0.0-stage → 0.1.1

package/cli/node-runtime-discovery.mjs

@@ -0,0 +1,56 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { delimiter, join, resolve, sep } from 'node:path';
+import { invalid, missing } from './errors.mjs';
+import { cachedRuntime, nodeCache, tidyRuntime } from './node-runtime-cache.mjs';
+
+const exact = value => typeof value === 'string' && /^v?\d+\.\d+\.\d+$/.test(value);
+// Read project-owned declarations, never import an adapter under the wrong Node.
+// Independent projects without an exact pin keep their chosen runtime.
+export async function projectNodePin(root) {
+ let descriptor;
+ try { descriptor = JSON.parse(await readFile(resolve(root, 'OPERATIONS.json'), 'utf8')); }
+ catch { return undefined; } // Normal project validation owns descriptor errors.
+ const firstParty = Boolean(descriptor.seedContract);
+ let file, nvm, pkg = {};
+ try { file = (await readFile(resolve(root, '.node-version'), 'utf8')).trim(); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+ try { nvm = (await readFile(resolve(root, '.nvmrc'), 'utf8')).trim(); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+ try { pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8')); } catch {}
+ if (file && !exact(file)) throw invalid('Use an exact Node release (major.minor.patch) in .node-version.');
+ const declarations = [file, nvm, pkg.engines?.node, pkg.volta?.node].filter(exact).map(value => value.replace(/^v/, ''));
+ if (new Set(declarations).size > 1) throw invalid('The exact Node pins in .node-version, .nvmrc, package.json engines.node or volta.node disagree. Make the project pins agree before running rer.');
+ const pin = declarations[0];
+ if (!pin && firstParty) throw missing('Declare the project Node release in .node-version and package.json engines.node before running rer.');
+ return pin?.replace(/^v/, '');
+}
+
+export function matchesRuntime(binary, version) {
+ const result = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 1500, maxBuffer: 1024, windowsHide: true });
+ return result.status === 0 && result.stdout.trim() === `v${version}`;
+}
+
+export async function installedRuntime(version) {
+ const home = homedir(), name = process.platform === 'win32' ? 'node.exe' : 'node';
+ let cached, cacheError;
+ try { cached = await cachedRuntime(version); } catch (error) { cacheError = error; }
+ if (cached && matchesRuntime(cached, version)) { await tidyRuntime(version); return cached; }
+ const candidates = [
+  join(home, '.nvm', 'versions', 'node', `v${version}`, 'bin', name),
+  ...(process.env.NVM_DIR ? [join(process.env.NVM_DIR, 'versions', 'node', `v${version}`, 'bin', name)] : []),
+  join(home, '.volta', 'tools', 'image', 'node', version, 'bin', name),
+  ...['.fnm', '.local/share/fnm', 'Library/Application Support/fnm'].map(path => join(home, path, 'node-versions', `v${version}`, 'installation', 'bin', name)),
+  ...(process.env.PATH ?? '').split(delimiter).filter(Boolean).map(path => join(path, name)),
+  ...['/opt/homebrew/opt', '/usr/local/opt', '/usr/local/homebrew/opt'].map(path => join(path, `node@${version.split('.')[0]}`, 'bin', name)),
+ ];
+ let cacheRoot; try { cacheRoot = await realpath(nodeCache()); } catch {}
+ const seen = new Set(), deadline = Date.now() + 10000;
+ for (const candidate of candidates) {
+  if (Date.now() > deadline) break;
+  let canonical; try { canonical = await realpath(candidate); } catch { continue; }
+  if (cacheRoot && canonical.startsWith(cacheRoot + sep)) continue; // Cache binaries require their verified receipt.
+  if (seen.has(canonical)) continue; seen.add(canonical);
+  if (matchesRuntime(canonical, version)) return canonical;
+ }
+ if (cacheError) throw cacheError;
+}

package/cli/node-runtime-download.mjs

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { chmod, mkdtemp, readFile, rename, rm } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { Transform } from 'node:stream';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { matchesRuntime } from './node-runtime-discovery.mjs';
+import { prepareNodeCache, runtimeBinary, runtimeName, recordRuntime, cachedRuntime, tidyRuntime } from './node-runtime-cache.mjs';
+
+async function download(url, destination, limit, signal) {
+ const response = await fetch(url, { signal, redirect: 'error' });
+ if (!response.ok || !response.body) throw Error('The official Node release could not be downloaded.');
+ let bytes = 0;
+ const bounded = new Transform({ transform(chunk, encoding, callback) {
+  bytes += chunk.length; callback(bytes > limit ? Error('Node release download exceeds its size limit.') : null, chunk);
+ } });
+ await pipeline(response.body, bounded, createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal });
+}
+
+async function extract(archive, directory, name, signal) {
+ const child = spawn('tar', ['-xzf', archive, '-C', directory, '--exclude', name + '/include'], { stdio: 'ignore', signal });
+ await new Promise((resolve, reject) => {
+  let failure;
+  child.once('error', error => { failure = error; });
+  child.once('close', code => code === 0 && !failure ? resolve() : reject(failure ?? Error('Verified Node release extraction failed.')));
+ });
+}
+
+export async function downloadRuntime(version, cancellation) {
+ if (!['darwin', 'linux'].includes(process.platform) || !['x64', 'arm64', 'armv7l', 'ppc64', 's390x'].includes(process.arch)) throw Error('Automatic Node download is unavailable on this platform.');
+ const cache = await prepareNodeCache(), name = runtimeName(version), filename = `${name}.tar.gz`;
+ const url = `https://nodejs.org/dist/v${version}/`;
+ const temporary = await mkdtemp(join(cache, '.download-'));
+ const signal = AbortSignal.any([cancellation, AbortSignal.timeout(60000)]);
+ try {
+  const sums = join(temporary, 'SHASUMS256.txt'), archive = join(temporary, filename);
+  await download(url + 'SHASUMS256.txt', sums, 1024 * 1024, signal);
+  const expected = (await readFile(sums, 'utf8')).split(/\r?\n/).map(line => line.trim().split(/\s+/)).find(parts => parts[1] === filename)?.[0];
+  if (!/^[a-f0-9]{64}$/.test(expected ?? '')) throw Error('The official release checksum is missing.');
+  await download(url + filename, archive, 150 * 1024 * 1024, signal);
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(archive)) hash.update(chunk);
+  if (hash.digest('hex') !== expected) throw Error('Official Node release checksum verification failed; nothing was extracted or executed.');
+  // This is the first point at which any downloaded content can be executed.
+  await extract(archive, temporary, name, signal);
+  const extracted = join(temporary, name), binary = runtimeBinary(extracted);
+  if (!matchesRuntime(binary, version)) throw Error('Verified Node release did not report the project pin.');
+  await chmod(extracted, 0o700);
+  await recordRuntime(extracted, version, expected);
+  const destination = join(cache, name);
+  try { await rename(extracted, destination); }
+  catch (error) {
+   if (!['EEXIST', 'ENOTEMPTY'].includes(error.code) || !(await cachedRuntime(version))) throw error;
+  }
+  await tidyRuntime(version);
+  return runtimeBinary(destination);
+ } finally { await rm(temporary, { recursive: true, force: true }); }
+}

package/cli/node-runtime.mjs

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { dirname, delimiter, resolve } from 'node:path';
+import { projectNodePin, installedRuntime } from './node-runtime-discovery.mjs';
+import { downloadRuntime } from './node-runtime-download.mjs';
+import { missing, RerError } from './errors.mjs';
+
+import { shellQuote } from './node-runtime-cache.mjs';
+function repair(version, options) {
+ return `npm exec --yes --package=node@${version} -- node ${[resolve(process.argv[1]), options.verb, '--cwd', options.cwd].map(shellQuote).join(' ')}`;
+}
+
+export async function selectNodeRuntime(options, argv, out) {
+ // Inspection keeps its read-only contract, and stop works without tool setup.
+ if (['describe', 'check', 'doctor'].includes(options.verb) || options.stop) return undefined;
+ const version = await projectNodePin(options.cwd);
+ if (!version || process.versions.node === version) return undefined;
+ const command = repair(version, options);
+ if (process.env.RER_NODE_AUTO === '0') throw missing(`Node ${version} is required; automatic selection is disabled by RER_NODE_AUTO=0. Run: ${command} (repeat any original options privately).`);
+ const cancellation = new AbortController();
+ let termination, child;
+ const handlers = new Map(['SIGINT', 'SIGTERM'].map(signal => [signal, () => {
+  termination = signal; cancellation.abort(); if (child) child.kill(signal);
+ }]));
+ for (const [signal, handler] of handlers) process.on(signal, handler);
+ try {
+  let binary = await installedRuntime(version);
+  if (termination) return { exitCode: termination === 'SIGINT' ? 130 : 143 };
+  if (!binary) {
+   try { binary = await downloadRuntime(version, cancellation.signal); }
+   catch (error) {
+    if (termination) return { exitCode: termination === 'SIGINT' ? 130 : 143 };
+    if (error instanceof RerError) throw error;
+    const reason = /unavailable on this platform/.test(error.message) ? error.message : /checksum/.test(error.message) ? 'Official release checksum verification failed.' : 'The exact official release could not be acquired within 60 seconds; check the connection and available disk space.';
+    throw missing(`Node ${version} is required. ${reason} With network access, run: ${command} (repeat any original options privately).`);
+   }
+  }
+  const message = `Using project Node ${version} (current Node ${process.versions.node}).`;
+  if (options.json) out.event('node-selection', { versionSelected: version, previousVersion: process.versions.node, message });
+  else out.human(message);
+  child = spawn(binary, [...process.execArgv, process.argv[1], ...argv], {
+   cwd: process.cwd(), stdio: 'inherit', env: { ...process.env, PATH: dirname(binary) + delimiter + (process.env.PATH ?? '') },
+  });
+  const result = await new Promise((resolve, reject) => {
+   child.once('error', reject);
+   child.once('exit', (code, signal) => resolve({ exitCode: code ?? (signal && constants.signals[signal] ? 128 + constants.signals[signal] : 1) }));
+  });
+  return result;
+ } finally { for (const [signal, handler] of handlers) process.off(signal, handler); }
+}

package/cli/output.mjs

@@ -0,0 +1,22 @@
+import { writeSync } from 'node:fs';
+export function output(options) {
+ let closed = false, finished = false;
+ // A bounded child retains the caller's human progress but sends its closing
+ // outcome as data, so only the drained outer workflow renders the result.
+ const structuredResult = options.json || process.env.RER_BOUNDED_OUTPUT === '1';
+ const write = (fd, text) => { if (closed && fd === 1) return; try { writeSync(fd, text); } catch (error) { if (error.code === 'EPIPE') closed = true; else if (!['EAGAIN', 'EWOULDBLOCK'].includes(error.code)) throw error; } };
+ return {
+  event(event, details = {}) { write(1, JSON.stringify({ version: 1, verb: options.verb ?? 'unknown', event, ...details }) + '\n'); },
+  human(text) { write(1, text + '\n'); },
+  progress(text) { write(2, text); },
+  result(ok, exitCode, details = {}) {
+   if (finished) throw Error('Duplicate CLI result'); finished = true;
+   if (structuredResult) this.event('result', { ok, exitCode, ...details });
+   else if (!['describe', 'check', 'dev', 'preview', 'outbox', 'setup'].includes(options.verb) || !ok) this.human(`${options.verb}: ${ok ? 'complete' : 'failed'} (exit ${exitCode})`);
+  },
+  error(error) {
+   if (structuredResult) this.event('error', { code: error.code, message: error.message, exitCode: error.exitCode });
+   else write(2, error.message + '\n');
+  },
+ };
+}

package/cli/parse.mjs

@@ -0,0 +1,77 @@
+import { resolve } from 'node:path';
+import { commonFlags, serverDefaults, verbs } from './contract.mjs';
+import { invalid, refuse } from './errors.mjs';
+const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata']);
+export const mailbox = value => typeof value === 'string' && value.length <= 254 && /^[a-zA-Z0-9.!+_%\-]+@[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+$/.test(value);
+export const loopback = host => ['127.0.0.1', 'localhost', '::1'].includes(host);
+export const origin = (host, port) => `http://${host === '::1' ? '[::1]' : host}:${port}`;
+
+export function parse(argv, cwd = process.cwd(), { independent = false, deferTail = false } = {}) {
+ const [verb, ...args] = argv;
+ if (!verb || verb === '--help') return { help: true };
+ if (verb === 'release') return { verb, releaseArgs: args };
+ if (verb === 'archive') return { verb, archiveArgs: args };
+ // Independent projects own verb names; only the common wrapper flags apply
+ // to unknown names. Profile resolution rejects undeclared commands later.
+ if (!/^[a-z][a-z0-9-]*$/.test(verb)) throw invalid('Unknown rer command. Run rer --help.');
+ const allowed = new Set(independent ? [...commonFlags,...(['install','setup','build','verify','deploy','release','export','import','dev','preview'].includes(verb)?['--no-queue']:[])] : verbs[verb]?.flags ?? commonFlags), options = { verb, cwd: resolve(cwd), forwarded: [], supplied: new Set() };
+ let separator = false;
+ for (let i = 0; i < args.length; i++) {
+  const flag = args[i];
+  if (flag === '--') { if (separator) throw invalid('Use only one -- separator.'); separator = true; if (independent || deferTail) { options.forwarded = args.slice(i + 1); break; } continue; }
+  if (separator && !flag.startsWith('--')) { options.forwarded.push(...args.slice(i)); break; }
+  // pnpm run VERB -- FLAGS forwards the separator before wrapper flags.
+  if (separator && !allowed.has(flag) && !flag.startsWith('--')) { options.forwarded.push(...args.slice(i)); break; }
+  if (!allowed.has(flag)) {
+   if(flag==='--strictPort')throw invalid('Unsupported --strictPort. Use --port PORT; strict port binding is automatic.');
+   const suggestion=[...allowed].sort((a,b)=>distance(flag,a)-distance(flag,b))[0];
+   throw invalid(`Unsupported flag ${/^--[a-zA-Z-]{1,40}$/.test(flag)?flag:'(invalid)'} for ${verb}.${suggestion?` Did you mean ${suggestion}?`:''} Run rer ${verb} --help.`);
+  }
+  if (options.supplied.has(flag)) throw invalid(`Repeated flag ${flag} for ${verb}. Run rer ${verb} --help.`);
+  options.supplied.add(flag);
+  const key = flag.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  if (booleans.has(flag)) options[key] = true;
+  else {
+   const value = args[++i];
+   if (value === undefined || value.startsWith('--') || !value.trim()) throw invalid(`A value is required for ${flag}.`);
+   options[key] = value;
+  }
+ }
+ if (options.help) return options;
+ if (deferTail) { options.cwd=resolve(cwd,options.cwd);return options; }
+ if(options.stop && ['--port','--host','--idle-timeout','--no-queue','--as','--login','--models','--models-service'].some(flag=>options.supplied.has(flag)))throw invalid('--stop cannot be combined with start-only flags.');
+ if(options.models!==undefined && !['fake','live'].includes(options.models))throw invalid('--models takes fake or live.');
+ if(options.modelsService!==undefined && options.models!=='live')throw invalid('--models-service requires --models live.');
+ if(options.as!==undefined && (options.login || !/^[a-z][a-z0-9-]{0,39}$/.test(options.as)))throw invalid(options.login?'--as and --login cannot be combined.':'--as takes a persona name such as owner, signed-out or admin.');
+ if(['dev','preview'].includes(verb) && !options.stop){
+  const value=options.idleTimeout??process.env.RER_SERVER_IDLE_SECONDS??String(serverDefaults.idleSeconds);
+  if(!/^[1-9][0-9]*$/.test(value)||!Number.isSafeInteger(Number(value)))throw invalid('Idle timeout must be positive integer seconds.');
+  options.idleTimeout=Number(value);
+ }
+ if (options.port !== undefined) {
+  if (!/^\d+$/.test(options.port) || Number(options.port) < 1 || Number(options.port) > 65535) throw invalid('Port must be a decimal integer from 1 to 65535.');
+  options.port = Number(options.port);
+ }
+ for(const key of ['httpPort','httpsPort'])if(options[key]!==undefined){if(!/^[0-9]+$/.test(options[key])||Number(options[key])<1||Number(options[key])>65535)throw invalid('Ingress port must be an integer from 1 to 65535.');options[key]=Number(options[key]);}
+ if(['image','bindAddress','httpPort','httpsPort'].some(key=>options[key]!==undefined)&&options.platform!=='container')throw invalid('Container image and ingress flags require --platform container.');
+ if(options.platform !== undefined && !['workers','container'].includes(options.platform))throw invalid('Platform must be workers or container.');
+ if (options.host !== undefined && !(verb === 'deploy' && options.platform === 'container') && !loopback(options.host)) throw refuse('Host must be exactly 127.0.0.1, localhost or ::1.');
+ if (options.ownerEmail !== undefined) { if (!mailbox(options.ownerEmail)) throw invalid('Provide a valid plain owner mailbox.'); options.ownerEmail = options.ownerEmail.toLowerCase(); }
+ if (options.ownerName !== undefined && (options.ownerName.length > 200 || /[\p{Cc}\p{Cf}]/u.test(options.ownerName))) throw invalid('Provide a valid owner name.');
+ if (options.target !== undefined && !['local', 'remote'].includes(options.target)) throw invalid('Target must be local or remote.');
+ if (options.profile !== undefined && options.profile !== 'first-party') throw invalid('The supported explicit profile is first-party.');
+ if (options.environment !== undefined && !/^[a-z][a-z0-9-]{0,39}$/.test(options.environment)) throw invalid('Provide a valid deployment environment name.');
+ if (options.origin !== undefined) {
+  let url; try { url = new URL(options.origin); } catch { throw invalid('Provide a valid credential-free origin.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw invalid('Provide a credential-free HTTP origin without a path.');
+ }
+ if (options.cwd !== undefined) options.cwd = resolve(cwd, options.cwd);
+ return options;
+}
+
+export function help(verb) {
+ if (!verb) return `Usage: rer VERB [FLAGS]\nCommands: ${Object.keys(verbs).join(', ')}, release\nRun rer VERB --help for flags.\n`;
+ return `Usage: rer ${verb} [FLAGS]\nFlags: ${(verbs[verb]?.flags ?? commonFlags).join(', ')}\n${verbs[verb]?.effects ?? 'Execute the declared OPERATIONS v2 argv with explicit arguments after --.'}\n`;
+}
+
+function distance(a,b){let row=Array.from({length:b.length+1},(_,i)=>i);for(let i=1;i<=a.length;i++){const next=[i];for(let j=1;j<=b.length;j++)next[j]=Math.min(next[j-1]+1,row[j]+1,row[j-1]+(a[i-1]===b[j-1]?0:1));row=next;}return row[b.length];}

package/cli/port.mjs

@@ -0,0 +1,52 @@
+import { createServer } from 'node:net';
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readJson } from '../modules/job-queue/storage.mjs';
+import { serversDirectory, stopInstruction } from './server-registry.mjs';
+import { shared } from './shared.mjs';
+
+export const defaultPort = 8787;
+
+async function bindable(host, port) {
+ const socket = createServer();
+ try { await new Promise((resolve, reject) => { socket.once('error', reject); socket.listen(port, host, resolve); }); return true; }
+ catch { return false; }
+ finally { if (socket.listening) await new Promise(resolve => socket.close(resolve)); }
+}
+
+// The first port from `from` that nothing listens on, on any address, and that
+// this host can bind. Another checkout's server may listen on every address,
+// which a bind to 127.0.0.1 alone does not notice.
+export async function firstFreePort(host, from = defaultPort) {
+ const { listeningPorts } = await shared('process-diagnostics.mjs');
+ const busy = await listeningPorts();
+ for (let port = from; port <= 65535; port++) if (!busy.has(port) && await bindable(host, port)) return port;
+ throw Error(`No free port from ${from} upward.`);
+}
+
+// Who holds a port: a server another checkout registered (its path and the
+// command that stops it), else the process and its working directory.
+export async function portHolder(port, host, root, env = process.env) {
+ const { portListener } = await shared('process-diagnostics.mjs');
+ const listener = await portListener(port, host);
+ if (!listener) return undefined;
+ const state = await readJson(join(serversDirectory(env), 'state.json'), { running: [] }).catch(() => ({ running: [] }));
+ const record = (state.running ?? []).find(item => item.owner?.pid === listener.pid && item.port === port);
+ return { ...listener, ...(record ? { server: record, checkout: record.checkout, own: record.checkout === await realpath(root) } : {}) };
+}
+
+// The refusal for a busy port. For a checkout that wants to move, it names the
+// holder and gives the exact command that moves this checkout to a free port.
+export async function busyPortMessage({ port, host, root, saved, env = process.env }) {
+ const holder = await portHolder(port, host, root, env);
+ const next = await firstFreePort(host, port + 1).catch(() => undefined);
+ const kind = saved ? `Port ${port} is saved for this checkout but is` : `Port ${port} is`;
+ if (!holder) return `${kind} in use by another process that this account cannot inspect. Stop it, or pick a free port${next ? ` such as ${next}` : ''}.`;
+ if (holder.own) return `${kind} held by this checkout's own ${holder.server.mode} server (PID ${holder.pid}). Stop it with: ${stopInstruction(holder.server)}`;
+ const who = holder.server
+  ? `the ${holder.server.mode} server for ${holder.checkout} (PID ${holder.pid})`
+  : `PID ${holder.pid} (${holder.command})${holder.cwd ? ` running in ${holder.cwd}` : ''}`;
+ const move = next ? `\nTo move this checkout to a free port and keep its data, run this in its folder:\n  rer setup --port ${next}` : '';
+ const stop = holder.server ? `\nOr stop that server first: ${stopInstruction(holder.server)}` : `\nOr stop it with: kill -TERM ${holder.pid}`;
+ return `${kind} in use by ${who}.${move}${stop}`;
+}

package/cli/portability-worker.mjs

@@ -0,0 +1,56 @@
+import { portabilityPlan, ensurePortabilitySchema } from '../modules/container/portability-schema.mjs';
+import { exportArchive, importArchive, fileRecords } from '../modules/portability/files.mjs';
+import { readLegacyArchive } from '../modules/portability/format.mjs';
+import { recoverLegacyArchive } from '../modules/portability/legacy-files.mjs';
+import { legacyEmptyTables, requireLegacyEmpty } from '../modules/portability/legacy-safety.mjs';
+import { migrationReplay } from '../modules/portability/migration-history.mjs';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { createPortability, PortabilityError, readArchive } from '../modules/portability/index.mjs';
+import { parseJsonc } from './jsonc.mjs';
+
+// The migrations this installation applied, in Wrangler's applied order, so a
+// restore can place an older archive within them.
+async function appliedMigrations(root, db, binding, split) {
+ const config = parseJsonc(await readFile(join(root, 'wrangler.jsonc'), 'utf8'));
+ const directory = join(root, config.d1_databases.find(entry => entry.binding === binding).migrations_dir ?? 'migrations');
+ const names = (await db.prepare('SELECT name FROM d1_migrations ORDER BY id').all()).results.map(row => row.name);
+ return Promise.all(names.map(async name => ({ name, statements: split(await readFile(join(directory, name), 'utf8')) })));
+}
+
+async function run(direction, { root, path, journal, binding, buckets, policy, transient, legacyRecovery }) {
+ // Validate all inputs before opening bindings or acquiring a restore lock.
+ if (direction === 'import') {
+  for await (const record of fileRecords(path,legacyRecovery?readLegacyArchive:readArchive)) {}
+  if(journal)for await(const record of fileRecords(journal)) {}
+ }
+ const { getPlatformProxy, unstable_splitSqlQuery } = createRequire(join(root, 'package.json'))('wrangler');
+
+ // Unlike Wrangler's --persist-to base, the API takes the versioned directory.
+ const proxy = await getPlatformProxy({ configPath: join(root, 'wrangler.jsonc'), persist: { path: join(root, '.wrangler/state/v3') }, remoteBindings: false });
+ try {
+  const migrations=async()=>migrationReplay(await appliedMigrations(root,proxy.env[binding],binding,unstable_splitSqlQuery),policy);
+  const options={ db: proxy.env[binding], buckets: Object.fromEntries(Object.entries(buckets).map(([name, binding]) => [name, proxy.env[binding]])), policy, migrations };
+  if(direction==='legacy-preflight') {
+   await requireLegacyEmpty(options,await legacyEmptyTables(options.db));
+   return {checkedEmpty:true};
+  }
+  await ensurePortabilitySchema(proxy.env[binding], await portabilityPlan(unstable_splitSqlQuery));
+  if(legacyRecovery)return await recoverLegacyArchive(options,path,legacyRecovery.output,transient,legacyRecovery.acknowledged);
+  const service = await createPortability(options);
+  return await (direction === 'export' ? exportArchive(service,path,transient) : importArchive(service,path,transient,journal));
+ } finally { await proxy.dispose(); }
+}
+
+try { console.log(JSON.stringify({ ok: true, ...await run(process.argv[2], JSON.parse(process.argv[3])) })); }
+catch (error) {
+ // Erasure-fence refusals name the fence: an older archive is refused, not a failed transfer.
+ const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal'].includes(error.code.split(':')[0]));
+ const exitCode = error.message === 'archive_json' ? 2 : refusal || error.code === 'EEXIST' ? 4 : 1;
+ // Report only symbolic codes; native database errors can contain private data.
+ const reason = error instanceof PortabilityError ? error.code.split(':')[0] : /^[A-Z_]+$/.test(error.code ?? '') ? error.code : error.message === 'archive_json' ? 'archive_json' : 'native_error';
+ // A later migration that changes restorable data is named: it is a file of this installation.
+ const migration = error instanceof PortabilityError && error.code.startsWith('schema_mismatch:migration_data:') ? error.code.slice('schema_mismatch:migration_data:'.length) : undefined;
+ console.log(JSON.stringify({ ok: false, code: exitCode === 2 ? 'invalid_archive' : exitCode === 4 ? 'restore_refused' : 'transfer_failed', reason, ...(migration ? { migration } : {}), exitCode })); process.exitCode = exitCode;
+}

package/cli/portability.mjs

@@ -0,0 +1,66 @@
+import { lstat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { relative } from 'node:path';
+import { readArchive, PortabilityError } from '../modules/portability/index.mjs';
+import { readLegacyArchive } from '../modules/portability/format.mjs';
+import { fileRecords } from '../modules/portability/files.mjs';
+import { RerError, refuse } from './errors.mjs';
+
+// Seeds declare their real bindings and data policy. The shared module owns the
+// archive format and atomic restore; the shared runner owns its native children.
+export function localPortability({ database, binding = 'DB', buckets = {}, policy, transient = [] }) {
+ async function run({ root, path, journal, store, signal, operationToken, platform, legacyRecovery }, direction) {
+  if (direction === 'export') {
+   if (await lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; })) throw refuse('Export requires a new archive path.');
+  }
+  if(legacyRecovery && (!legacyRecovery.acknowledged || await lstat(legacyRecovery.output).catch(error=>{if(error.code==='ENOENT')return null;throw error;})))throw refuse('Legacy recovery requires acknowledgement and a new output archive path.');
+  if (direction === 'import') {
+   // Refuse damaged or unverifiable archives before migrations open the
+   // destination database. Worker and finalization verify again before publish.
+   try {
+    for await (const record of fileRecords(path,legacyRecovery?readLegacyArchive:readArchive)) {}
+    if(journal)for await(const record of fileRecords(journal)) {}
+   }
+   catch (error) {
+    if (!(error instanceof PortabilityError)) throw error;
+    const message = error.code === 'legacy_archive_unverifiable'
+     ? 'Restore refused (legacy_archive_unverifiable): version 1 metadata cannot be authenticated. Upgrade the original installation and re-export, or use rer import --legacy-v1 --input FILE --yes --acknowledge-unverified-metadata --output exports/recovered-v2.rer in an empty installation. See modules/portability/README.md#backup-only-v1-recovery.'
+     : `Restore refused (${error.code}): archive verification failed.`;
+    const refused = error.status === 409;
+    throw new RerError(refused ? 'restore_refused' : 'transfer_failed', message, refused ? 4 : 1);
+   }
+  }
+  if(legacyRecovery)store.report('Legacy v1 recovery: manifest metadata is unverified. Restored data will be audited and exported to a new v2 backup.');
+  if(platform==='container') return (await import('./container-transfer.mjs')).containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy,transient});
+  const input={ root, path, journal, binding, buckets, policy, transient, legacyRecovery };
+  // Do not apply pending product migrations to a populated recovery target.
+  // Check real existing bindings first; finalize repeats this under the lock.
+  if(legacyRecovery)await nativeWorker(store,'legacy-preflight',input,signal);
+  await store.run('Applying local data migrations', 'pnpm', ['exec', 'wrangler', 'd1', 'migrations', 'apply', database, '--local', '--persist-to', '.wrangler/state', '--config', 'wrangler.jsonc'], {
+   cwd: root, signal, env: { ...process.env, RER_LOCAL_OPERATION: operationToken, WRANGLER_SEND_METRICS: 'false' },
+  });
+  const receipt=await nativeWorker(store,direction,input,signal);
+  if(legacyRecovery)receipt.output=relative(root,legacyRecovery.output);
+  return { target: 'local', [direction === 'export' ? 'output' : 'input']: relative(root, path), ...receipt };
+ }
+ return { legacyRecovery:true, export: context => run(context, 'export'), import: context => run(context, 'import') };
+}
+
+async function nativeWorker(store,direction,input,signal) {
+  const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url));
+  const child = store.spawn(`${direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
+   [worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' } });
+  let output = '';
+  child.stdout.on('data', chunk => { output += chunk; });
+  const closed = new Promise(resolve => child.once('close', (code, signal) => resolve({ code, signal })));
+  await new Promise(resolve => { child.once('exit', resolve); child.once('error', resolve); });
+  await store.stop(child);
+  const status = await closed;
+  let receipt; try { receipt = JSON.parse(output.trim().split('\n').at(-1)); } catch { throw new RerError('transfer_failed', 'Local portability did not return a complete receipt.', 1); }
+  if (status.code !== 0 || !receipt.ok) throw new RerError(receipt.code ?? 'transfer_failed', receipt.reason==='legacy_restored_export_failed'
+   ? 'Legacy data was restored and audited, but its v2 export failed. Preserve this installation, resolve the output problem, then run rer export --output FILE. Do not reset it to retry recovery.'
+   : receipt.migration ? `Restore refused (schema_mismatch:migration_data): migration ${receipt.migration} changed data after this archive was made, so its rows would skip that change. Restore an archive made after it.`
+   : `The portability module refused or failed the archive operation (${receipt.reason ?? 'incomplete'}).`, receipt.exitCode ?? 1);
+  delete receipt.ok;
+  return receipt;
+}

package/cli/preview-cache.mjs

@@ -0,0 +1,99 @@
+import {shared} from './shared.mjs';
+import {invalid,refuse} from './errors.mjs';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, unlink } from 'node:fs/promises';
+import { join, relative, resolve, dirname, extname } from 'node:path';
+const excluded = new Set(['node_modules','.git','.wrangler','.seed','.rer','.cache','.state','dist','coverage','test-results','playwright-report']);
+// A project declares the paths its build regenerates (`generatedOutputs` on the
+// adapter): project-relative files or directories. They are not build inputs.
+export function generatedOutputs(project) {
+ const declared=project.adapter.generatedOutputs??[];
+ if(!Array.isArray(declared))throw invalid('Adapter generatedOutputs must be a list of project-relative paths.');
+ return declared.map(path=>{
+  const name=typeof path==='string'?path.replace(/\/+$/,''):'';
+  if(!name||name.startsWith('/')||name.includes('\\')||name.split('/').some(part=>part===''||part==='.'||part==='..'))throw invalid(`Adapter generatedOutputs entry ${JSON.stringify(path)} must be a project-relative file or directory path.`);
+  return name;
+ });
+}
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+async function tree(root,{privateFiles=[],generated=[],outputs=false,metadata}={}) {
+ 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),name=relative(root,path);
+   if(!outputs && (((directory===root&&excluded.has(entry.name))||['node_modules','.git'].includes(entry.name))||/^\.env(?:\.|$)|^\.dev\.vars(?:\.|$)/.test(entry.name)||privateFiles.includes(name)))continue;
+   if(generated.some(item=>name===item||name.startsWith(item+'/')))continue;
+   if(entry.isSymbolicLink())throw Error('Build receipt cannot certify symbolic source/output links.');
+   if(entry.isDirectory())await walk(path);
+   else if(entry.isFile()){
+    const before=await lstat(path,{bigint:true});files[name]=digest(await readFile(path));
+    const after=await lstat(path,{bigint:true});
+    if(stamp(before)!==stamp(after))throw Error('Build input/output changed while it was read.');
+    if(metadata)metadata[name]=stamp(after);
+   }
+   else throw Error('Build receipt requires regular files.');
+  }
+ }
+ await walk(root);return files;
+}
+const stamp=status=>[status.dev,status.ino,status.size,status.mtimeNs,status.ctimeNs].map(String).join(':');
+export async function buildInputs(project,{revision=false}={}) {
+ const metadata={},sources=await tree(project.root,{privateFiles:project.adapter.settings,generated:generatedOutputs(project),metadata});
+ const pending=Object.keys(sources).filter(name=>/\.[cm]?[jt]sx?$/.test(name)).map(name=>resolve(project.root,name));
+ const seen=new Set(),external={};
+ while(pending.length){
+  const file=pending.pop();if(seen.has(file))continue;seen.add(file);
+  const bytes=await readFile(file);const name=relative(project.root,file);
+  if(name.startsWith('..')){external[name]=digest(bytes);metadata[name]=stamp(await lstat(file,{bigint:true}));}
+  for(const match of bytes.toString().matchAll(/(?:from\s*|import\s*\(?|require\s*\()(['"])(\.[^'"\n]+)\1/g)){
+   const path=resolve(dirname(file),match[2]);
+   for(const candidate of [path,...['.ts','.tsx','.js','.mjs','/index.ts','/index.js'].map(ext=>path+ext),...(extname(path)==='.js'?[path.slice(0,-3)+'.ts']:[])]){
+    try{if((await lstat(candidate)).isFile()){if(!/\.dev\.vars|(?:^|\/)\.env(?:\.|$)/.test(candidate))pending.push(candidate);break;}}catch{}
+   }
+  }
+ }
+ const tools={};
+ for(const name of ['vite','wrangler','@cloudflare/vite-plugin','typescript']){
+  try{const pkg=JSON.parse(await readFile(join(project.root,'node_modules',name,'package.json'),'utf8'));tools[name]=pkg.version;}catch{tools[name]=null;}
+ }
+ const inputs=digest(JSON.stringify({sources,external:Object.fromEntries(Object.entries(external).sort()),node:process.versions.node,tools,build:project.adapter.hooks.build}));
+ return revision?{inputs,revision:digest(JSON.stringify(metadata)),files:{...sources,...external},stamps:metadata}:inputs;
+}
+
+// Name the inputs the build touched: edited contents versus a rewrite that left
+// the bytes alone (a generated file the project has not declared).
+function changedInputs(before,after) {
+ const names=new Set([...Object.keys(before.files),...Object.keys(after.files)]);
+ const edited=[...names].filter(name=>before.files[name]!==after.files[name]).sort();
+ const rewritten=[...names].filter(name=>before.files[name]===after.files[name]&&before.stamps[name]!==after.stamps[name]).sort();
+ // Many files in one directory read as that directory, which is also the declaration to make.
+ const grouped=items=>{
+  const folders=new Map();for(const name of items){const folder=dirname(name);folders.set(folder,(folders.get(folder)??0)+1);}
+  return [...new Set(items.map(name=>folders.get(dirname(name))>1?`${dirname(name)}/ (${folders.get(dirname(name))} files)`:name))];
+ };
+ const list=(items,group)=>{const names=group?grouped(items):items;return names.slice(0,5).join(', ')+(names.length>5?` and ${names.length-5} more`:'');};
+ const parts=[];
+ if(edited.length)parts.push(`Source changed while the production build ran: ${list(edited)}. Leave it alone during the build, then run preview again.`);
+ if(rewritten.length){const them=rewritten.length>1?'them':'it';parts.push(`The production build rewrote ${list(rewritten,true)} with identical contents. If the build generates ${them}, declare ${them} as generatedOutputs in the project adapter; otherwise stop whatever rewrites ${them}.`);}
+ return parts.join(' ')||'Build inputs changed during the production build (tools, Node or the build command). Run preview again.';
+}
+
+export async function productionBuild(project,build,report=()=>{}) {
+ const {privateDirectory,writePrivateFile,readPrivateFile}=await shared('private-files.mjs');
+ const directory=await privateDirectory(project.root,['.rer','local']),receipt=join(directory,'production.json'),output=join(project.root,'dist');
+ try{const info=await lstat(receipt);if(!info.isFile()||info.isSymbolicLink()||info.uid!==process.getuid())throw Error('Production receipt must be an owned regular file.');}catch(error){if(error.code!=='ENOENT')throw error;}
+ const before=await buildInputs(project,{revision:true}),inputs=before.inputs;
+ try {
+  const prior=JSON.parse(await readPrivateFile(receipt));
+  const outputs=await tree(output,{outputs:true});
+  if(prior.version===1 && prior.inputs===inputs && outputs['server/wrangler.json'] && prior.outputs===digest(JSON.stringify(outputs))){report('Reusing intact production output.');return {reused:true};}
+ } catch { /* Missing/corrupt input receipt or output cannot authorize reuse. */ }
+ await unlink(receipt).catch(error=>{if(error.code!=='ENOENT')throw error;});
+ report('Building production output.');const started=performance.now();await build();const buildMilliseconds=performance.now()-started;
+ const outputs=await tree(output,{outputs:true});
+ if(!outputs['server/wrangler.json'])throw Error('Production configuration is missing.');
+ const after=await buildInputs(project,{revision:true});
+ if(after.inputs!==inputs||after.revision!==before.revision)throw refuse(changedInputs(before,after));
+ await writePrivateFile(receipt,JSON.stringify({version:1,inputs,outputs:digest(JSON.stringify(outputs)),buildMilliseconds})+'\n');
+ return {reused:false};
+}

package/cli/project.mjs

@@ -0,0 +1,48 @@
+import { readFile, lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readOperations } from '../operations/operations.mjs';
+import { invalid, missing, refuse } from './errors.mjs';
+
+export async function contained(root, path, { optional = false, privateFile = false } = {}) {
+ if (typeof path !== 'string' || !path || isAbsolute(path) || path.split(/[\\/]/).some(part => part === '..' || part === '')) throw refuse('Path must be a contained checkout path without traversal.');
+ const checkout = await realpath(root), destination = resolve(checkout, path), parts = relative(checkout, destination).split(sep);
+ let current = checkout;
+ for (let i = 0; i < parts.length; i++) {
+  current = resolve(current, parts[i]);
+  let status; try { status = await lstat(current); } catch (error) { if (error.code === 'ENOENT' && optional) return destination; if (error.code === 'ENOENT') throw missing(`Missing input file: ${path}. See the project operating documentation.`); throw error; }
+  if (status.isSymbolicLink()) throw refuse(`Symlink refused at ${path}; preserve it and resolve placement first.`);
+  if (i < parts.length - 1 && !status.isDirectory()) throw refuse(`Unsafe path ancestor for ${path}.`);
+  if (privateFile && i === parts.length - 1 && (!status.isFile() || status.nlink !== 1 || (status.mode & 0o077) !== 0 || (process.getuid && status.uid !== process.getuid()))) throw refuse(`Input must be an owned regular private file (0600): ${path}.`);
+ }
+ return destination;
+}
+
+export async function resolveProject(root) {
+ root = await realpath(root);
+ let loaded;
+ try { loaded = await readOperations(root); } catch (error) {
+  if (error.code === 'ENOENT') throw missing('OPERATIONS.json or a declared input is missing. See the project operating documentation.');
+  throw invalid('Malformed operations descriptor or unsafe input. Correct OPERATIONS.json and its contained inputs.');
+ }
+ const marker = loaded.descriptor.seedContract;
+ let adapter;
+ if (marker) {
+  await contained(root, marker.adapter);
+  try { adapter = (await import(pathToFileURL(resolve(root, marker.adapter)))).commandAdapter; }
+  catch { throw invalid('The declared adapter could not be loaded. Restore its portable sources.'); }
+ }
+ return { root, ...loaded, profile: marker ? 'first-party' : 'independent', adapter };
+}
+
+// Only the descriptor marker distinguishes package forwarding from a raw
+// independent tail. Schema validation and adapter imports happen after parsing.
+export async function parsingProfile(root) {
+ try { const descriptor=JSON.parse(await readFile(resolve(root,'OPERATIONS.json'),'utf8'));return descriptor.version===2&&!descriptor.seedContract?'independent':'first-party'; }
+ catch { return 'first-party'; } // Help still works with absent/broken metadata.
+}
+
+export async function readPackage(root) {
+ try { return JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8')); }
+ catch { return {}; }
+}

package/cli/release.mjs

@@ -0,0 +1,24 @@
+// Preserve release's accepted parser, producer, receipt and validation exits.
+export async function dispatchRelease(args) {
+ try {
+  const options = {};
+  for (let index = 0; index < args.length; index++) {
+   if(args[index]==='--no-queue'){}
+   else if (args[index] === '--tag') options.tag = args[index + 1]?.startsWith('v') ? args[++index] : true;
+   else if (args[index] === '--clean-history') options.cleanHistory = true;
+   else if (args[index] === '--dry-run') options.dryRun = true;
+   else if (['--repo', '--project', '--repository', '--output', '--ref', '--env-file', '--onto'].includes(args[index]) && args[index + 1] && !args[index + 1].startsWith('--'))
+    options[args[index] === '--env-file' ? 'envFile' : args[index].slice(2)] = args[++index];
+   else throw Error('Invalid release arguments');
+  }
+  if(args.includes('--no-queue')){const {shared}=await import('./shared.mjs');const {commandPolicy}=await shared('queue.mjs');const policy=await commandPolicy();try{if(!policy.ci)throw Error('Original CI required');}finally{await policy.close();}}
+  if (!options.repo || !options.output) throw Error('Release requires --repo and --output');
+  const { release } = await import('../modules/release/produce.mjs');
+  const receipt = await release(options);
+  console.log(JSON.stringify(receipt, null, 2));
+  return receipt.status === 'BLOCKED' ? 1 : 0;
+ } catch {
+  console.error('Release failed during argument, source or artifact validation. No release completed.');
+  return 2;
+ }
+}