@runeditrun/rer 0.0.0-stage → 0.1.1

package/onboarding/failures.mjs

@@ -0,0 +1,42 @@
+// Only this module can mark a failure as safe for the browser. Never render a
+// caught error's message, code, cause, command, arguments, output or environment.
+const approved = new WeakMap();
+const tools = Object.freeze({node:'Node.js',npm:'npm',pnpm:'pnpm',git:'Git'});
+const steps = Object.freeze({dependencies:'installing dependencies',setup:'setting up the application',build:'building the application',verify:'verifying the application',start:'starting the application',deploy:'deploying the application'});
+export function installationFailure(code, details = {}) {
+ let message;
+ if(code==='node_version' && typeof details.version==='string' && /^\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(details.version) && !details.version.includes('\n')) {
+  message=`Install Node.js ${details.version}, then restart this installer with that version and resume your saved setup.`;
+ } else if(code==='missing_tool' && typeof details.tool==='string' && Object.hasOwn(tools,details.tool)) {
+  const action=details.tool==='npm'?'Install Node.js with npm included':`Install ${tools[details.tool]}`;
+  message=`${tools[details.tool]} was not found. ${action} and make it available on PATH, then restart this installer and resume your saved setup.`;
+ } else if(code==='command_failed' && typeof details.step==='string' && Object.hasOwn(steps,details.step)) {
+  message=`Installation stopped while ${steps[details.step]}. Ask your agent to check the edition's operating command for that step, correct the cause, then select Start again. Your setup answers are saved; you may need to supply credentials again.`;
+ } else {
+  throw new TypeError('Choose a supported installation failure and its documented details.');
+ }
+ // A captured command diagnostic from this module's command boundary keeps its
+ // first line (the headline the page shows) and its output and log path; the
+ // canned guidance follows that line. Any other value is ignored.
+ const captured=approved.get(details.diagnostic);
+ if(code==='command_failed'&&captured?.code==='captured_command_failed'){
+  const [first,...rest]=captured.message.split('\n');
+  message=[first,message,...rest].join('\n');
+ }
+ const error=new Error(message);
+ approved.set(error,{code,message,...(captured?.details ? {details:captured.details} : {})});
+ return error;
+}
+export function installationFailureMessage(error) {
+ return approved.get(error)?.message || 'Installation stopped unexpectedly. Review the last installation step shown here and ask your agent to inspect the edition’s installer and operating commands. After correcting the cause, select Start again. Your setup answers are saved; you may need to supply credentials again.';
+}
+
+// Only the command capture boundary calls this with its redacted diagnostic.
+// Identity approval remains independent of mutable Error properties.
+export function commandFailure(message, details = {}) {
+ const error=new Error(message);approved.set(error,{code:'captured_command_failed',message,details:{...details}});return error;
+}
+
+// Terminal callers may expose only diagnostics approved at the capture boundary.
+// A prior diagnostic's metadata must not replace the current composed message.
+export const approvedFailure = error => { const value=approved.get(error); return value ? {...value.details,...value} : undefined; };

package/onboarding/input-limits.mjs

@@ -0,0 +1,7 @@
+// SETUP's shared validateSetupValue contract permits 16,384 UTF-16 units.
+export const SETUP_VALUE_LIMIT = 16384;
+// JSON can escape each unit as six ASCII bytes. Bound requests by declared
+// fields, while accepting any valid combination, including secure envelopes.
+export function setupInputLimit(model) {
+ return 1024 + Object.keys(model.fields).reduce((size,key)=>size+6*(key.length+SETUP_VALUE_LIMIT)+16,0);
+}

package/onboarding/installer-inputs.mjs

@@ -0,0 +1,24 @@
+// Installer mechanics are defined here once; application bindings belong in SETUP.
+export const hostingKeys = ['target', 'accountId', 'prefix', 'appOrigin', 'apiToken'];
+export function installerInputs({hosting=false, ownerBootstrap=false}={}) {
+ const fields={},groups=[],secretScopes={};
+ const nonempty=value=>typeof value==='string'&&Boolean(value.trim());
+ if(ownerBootstrap){
+  fields.displayName={label:'Your name',help:'Shown as the first owner of this installation.',valid:value=>nonempty(value)&&value.length<=120};
+  groups.push({id:'local-owner',title:'First owner',keys:['displayName']});
+ }
+ if(hosting){
+  Object.assign(fields,{
+   target:{label:'Where should the workspace run?',options:[['local','On this computer'],['remote','Online for your team']],valid:value=>['local','remote'].includes(value)},
+   accountId:{label:'Cloudflare account',optional:true,valid:value=>/^[a-f0-9]{32}$/i.test(value||'')},
+   prefix:{label:'Resource name',optional:true,valid:value=>/^[a-z][a-z0-9-]{2,39}$/.test(value||'')},
+   appOrigin:{label:'Workspace address',optional:true,type:'url',valid:value=>{try{const url=new URL(value);return url.protocol==='https:'&&!url.username&&!url.password&&!url.href.includes('?')&&!url.href.includes('#')&&url.origin===value;}catch{return false;}}},
+   apiToken:{label:'Cloudflare API token',optional:true,type:'password',valid:nonempty},
+   prefixMode:{optional:true,valid:value=>['automatic','custom'].includes(value)},
+   addressMode:{optional:true,valid:value=>['automatic','custom'].includes(value)},
+  });
+  secretScopes.apiToken=['accountId'];
+  groups.push({id:'hosting',title:'Hosting & connections',kind:'hosting',keys:hostingKeys});
+ }
+ return {fields,groups,secretScopes};
+}

package/onboarding/launcher.mjs

@@ -0,0 +1,34 @@
+import { loadInstallerSeed, refuseLegacySetup } from './setup-manifest.mjs';
+import { spawn } from 'node:child_process';
+import { relative } from 'node:path';
+import { readAnswers, readSecrets } from './prefill.mjs';
+import { startInstaller } from './server.mjs';
+export async function launch(root,seed){
+refuseLegacySetup(seed);
+if(process.argv.includes('--help')){console.log(`Launch the standalone ${seed.product} installer before installing app dependencies.\nCommand-line setup instead: rer install, then rer setup.\nUsage: node ${relative(process.cwd(),process.argv[1])} [--port <local-port>] [--no-open] [--agent] [--no-prefill | --resume] [--answers answers.json] [--secrets-stdin]`);process.exit(0)}
+let noOpen=false,port=0,answersPath,secrets=false,noPrefill=false,resume=false,agent=false;
+const args=process.argv.slice(2);
+for(let index=0;index<args.length;index++){
+ if(args[index]==='--no-open')noOpen=true;
+ else if(args[index]==='--port'&&/^\d+$/.test(args[index+1]||''))port=Number(args[++index]);
+ else if(args[index]==='--answers'&&args[index+1])answersPath=args[++index];
+ else if(args[index]==='--secrets-stdin')secrets=true;
+ else if(args[index]==='--no-prefill')noPrefill=true;
+ else if(args[index]==='--agent')agent=true;
+ else if(args[index]==='--resume')resume=true;
+ else throw Error('Use --help for installer options.');
+}
+if(noPrefill&&(answersPath||secrets))throw Error('--no-prefill cannot be combined with supplied answers or secrets.');
+if(noPrefill&&resume)throw Error('Choose --no-prefill for a new empty session or --resume for saved answers.');
+seed=await loadInstallerSeed(root,seed);
+const contract={...seed};delete contract.model;
+const answers=answersPath?await readAnswers(answersPath,seed.model):undefined;
+let secretInput=secrets?await readSecrets(process.stdin,seed.model):undefined;
+const server=await startInstaller(root,{seed:contract,port,answers,secretInput,noPrefill,resume,agent});secretInput=undefined;
+console.log(`${seed.product} installer: ${server.origin}\nKeep this terminal open while installing and using the local app.`);
+for(const signal of ['SIGTERM','SIGINT','SIGHUP'])process.on(signal,async()=>{await server.close();process.exit()});
+
+if(!noOpen){const tool=process.platform==='darwin'?'open':process.platform==='win32'?'explorer.exe':'xdg-open';const child=spawn(tool,[server.origin],{stdio:'ignore',shell:false});const fallback=()=>console.log('Open the installer URL above in your browser.');child.on('error',fallback);child.on('exit',code=>{if(code)fallback()});}
+
+return server;
+}

package/onboarding/local/build-files.mjs

@@ -0,0 +1,64 @@
+import { lstat, rename, link, unlink } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+import { assertRegular, inspect } from './files.mjs'
+
+// The encoded relative name is also the recovery record. Publishing it by
+// rename records the destination atomically with moving the original inode.
+export function hiddenBuildName(file) {
+  validateName(file)
+  return `original.${Buffer.from(file).toString('base64url')}.private`
+}
+
+function validateName(file) {
+  if (typeof file !== 'string' || !file || isAbsolute(file)
+    || file.split(/[\\/]/).some(part => !part || part === '..' || part === '.')) {
+    throw new Error('Private build files must be contained checkout paths.')
+  }
+}
+
+export function buildDestination(name) {
+  const match = /^original\.([A-Za-z0-9_-]+)\.private$/.exec(name)
+  if (!match) return
+  const file = Buffer.from(match[1], 'base64url').toString('utf8')
+  if (hiddenBuildName(file) !== name) throw new Error('Invalid private build recovery record.')
+  return file
+}
+
+export async function inspectBuildFile(root, file, { publication = false } = {}) {
+  validateName(file)
+  const parts = file.split(/[\\/]/)
+  let path = root
+  for (const [index, part] of parts.entries()) {
+    path = join(path, part)
+    const status = await inspect(path)
+    if (!status) return { path: join(root, ...parts) }
+    if (index < parts.length - 1) {
+      if (!status.isDirectory() || status.isSymbolicLink()) throw new Error('Unsafe private build file ancestor.')
+    } else {
+      if (publication && status.isFile() && !status.isSymbolicLink() && (!process.getuid || status.uid === process.getuid())) return { path, status }
+      assertRegular(status); return { path, status }
+    }
+  }
+}
+
+export async function hideBuildFile(item, work, file) {
+  const current = await lstat(item.path)
+  if (current.ino !== item.status.ino || current.dev !== item.status.dev) throw new Error('Private settings changed during build; run again.')
+  const hidden = join(work, hiddenBuildName(file))
+  await rename(item.path, hidden)
+  return { path: hidden, file }
+}
+
+export async function restoreBuildFile(root, item) {
+  const destination = await inspectBuildFile(root, item.file, { publication: true })
+  const hidden = await inspect(item.path)
+  if (!hidden) return
+  if (destination.status?.ino === hidden.ino && destination.status?.dev === hidden.dev) {
+    await unlink(item.path)
+    return
+  }
+  assertRegular(hidden)
+  // Linking keeps exact bytes/mode and refuses a concurrently created file.
+  await link(item.path, destination.path)
+  await unlink(item.path)
+}

package/onboarding/local/build.mjs

@@ -0,0 +1,49 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { privateDirectory } from './files.mjs'
+import { localVariables, secretValues } from './environment.mjs'
+import { localOperation } from './operation.mjs'
+import { recoverInterrupted } from './recovery.mjs'
+import { inspectBuildFile, hideBuildFile, restoreBuildFile } from './build-files.mjs'
+
+// Hide every declared private setting and backup under the shared operation
+// lock. Renames and exclusive links preserve each original inode and mode;
+// encoded names let the next operation recover a hard-killed build.
+export async function withoutLocalVariables(root, action, { nested = process.env.RER_LOCAL_OPERATION, report, settings = ['.dev.vars', '.dev.vars.previous'] } = {}) {
+  const hidden = []
+  let work, operation, restoration
+  const restore = () => restoration ??= (async () => {
+    const failures = []
+    for (const item of hidden) {
+      try { await restoreBuildFile(root, item) } catch {
+        failures.push(`Could not restore ${item.file} without replacing a concurrent file. Original retained at ${item.path}.`)
+      }
+    }
+    if (work && !failures.length) await rm(work, { recursive: true })
+    await operation?.release()
+    if (failures.length) {
+      if (report) for (const message of failures) report(message)
+      else throw new Error(failures.join('\n'))
+    }
+
+  })()
+  try {
+    operation = await localOperation(root, nested)
+    if (!nested) await recoverInterrupted(root, operation)
+    const files = []
+    for (const file of new Set(['.dev.vars', '.dev.vars.previous', ...settings])) {
+      const item = await inspectBuildFile(root, file)
+      if (item.status) files.push({ ...item, file })
+    }
+    let secrets = []
+    const vars = files.find(item => item.file === '.dev.vars')
+    if (vars) secrets = secretValues(localVariables(await readFile(vars.path, 'utf8')))
+    if (files.length) {
+      const directory = join(root, '.wrangler/local-build')
+      await privateDirectory(root, directory)
+      work = await mkdtemp(join(directory, 'run-'))
+      for (const item of files) hidden.push(await hideBuildFile(item, work, item.file))
+    }
+    return await action({ secrets, operation, restore })
+  } finally { await restore() }
+}

package/onboarding/local/environment.mjs

@@ -0,0 +1,30 @@
+import { parseEnv } from 'node:util'
+
+export function localVariables(text) {
+  // Node's dotenv parser can consume the next assignment after an unquoted
+  // whitespace-only value. Keep such values empty for the preflight checks.
+  return parseEnv(text.replace(/(^[\t ]*(?:export[\t ]+)?[A-Za-z_]\w*[\t ]*=)[\t ]+(?=\r?$)/gm, '$1'))
+}
+
+// Inherited application bindings never reach a build or migration command.
+// The default names are the Base operator-auth and mail bindings.
+export const applicationBindings = /^(SESSION_SECRET|SETUP_TOKEN|OWNER_EMAIL|AUTH_|MAIL_|OIDC_|AI_|MODELS_|RER_MODELS_)/
+
+export function buildEnvironment(bindings = applicationBindings, inherited = process.env) {
+  const env = { ...inherited, CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV: 'false', CLOUDFLARE_INCLUDE_PROCESS_ENV: 'false', WRANGLER_SEND_METRICS: 'false' }
+  const declared = Array.isArray(bindings) ? new Set(bindings) : null
+  for (const key of Object.keys(env)) if (declared ? declared.has(key) || applicationBindings.test(key) : bindings.test(key)) delete env[key]
+  return env
+}
+
+// Values printed by a child are redacted when their name marks a credential.
+export const secretValues = (vars) => Object.entries(vars).filter(([key]) => /SECRET|TOKEN|API_KEY/.test(key)).map(([, value]) => value).filter(Boolean)
+
+export function localOrigin(vars) {
+  let url
+  try { url = new URL(vars.AUTH_ORIGIN) } catch { /* Use a fixed, non-secret diagnostic. */ }
+  if (vars.AUTH_LOCAL !== 'true' || !url || url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || url.origin !== vars.AUTH_ORIGIN || url.username || url.password) {
+    throw new Error('Invalid local origin in .dev.vars: AUTH_ORIGIN must be http://127.0.0.1:PORT with AUTH_LOCAL=true. Run rer setup to save a valid one. If you changed AUTH_ORIGIN yourself, put back the http://127.0.0.1:PORT origin setup saved, or pick a port with rer setup --port PORT.')
+  }
+  return url
+}

package/onboarding/local/files.mjs

@@ -0,0 +1,35 @@
+import { lstat, mkdir, open } from 'node:fs/promises'
+import { relative, resolve, sep } from 'node:path'
+
+export async function inspect(path) {
+  try { return await lstat(path) } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+// Inspect every ancestor: mkdir({recursive:true}) alone follows symlinks.
+export async function privateDirectory(root, path) {
+  const parts = relative(root, resolve(path)).split(sep)
+  if (parts.includes('..')) throw new Error('Unsafe local setup directory.')
+  let current = root
+  for (const part of parts) {
+    current = resolve(current, part)
+    const status = await inspect(current)
+    if (status && (!status.isDirectory() || status.isSymbolicLink())) {
+      throw new Error('Unsafe local setup directory; remove its symlink or non-directory first.')
+    }
+    if (!status) await mkdir(current, { mode: 0o700 })
+  }
+}
+
+export async function privateFile(path, content) {
+  const handle = await open(path, 'wx', 0o600)
+  try { await handle.writeFile(content) } finally { await handle.close() }
+}
+
+export function assertRegular(status) {
+  if (status && (!status.isFile() || status.isSymbolicLink() || status.nlink !== 1)) {
+    throw new Error('Unsafe .dev.vars path; replace its symlink, hard link or non-file before setup.')
+  }
+}

package/onboarding/local/operation.mjs

@@ -0,0 +1,166 @@
+import { randomUUID } from 'node:crypto'
+import { link, lstat, open, readFile, rename, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { privateDirectory } from './files.mjs'
+import { processStart } from './process-table.mjs'
+import {processName} from '../process-diagnostics.mjs'
+
+const busy = async (path) => {
+ let owner;try{owner=JSON.parse(await readFile(path,'utf8'));}catch{}
+ const pid=Number.isSafeInteger(owner?.pid)&&owner.pid>0?owner.pid:undefined;
+ const identity=pid?`PID ${pid} (${await processName(pid)})`:'an unidentified process';
+ return Object.assign(new Error(`An active local operation owns the state: ${identity}. Stop it with rer dev --stop or rer preview --stop; for an unmanaged process, stop PID ${pid ?? 'shown in the lock'} before retrying.`), {code: 'LOCAL_OPERATION_BUSY', ownerPid: pid});
+}
+const graceMs = 10000
+
+// Setup holds this lock through its nested build and migration commands. A
+// separate build/setup cannot restore credentials into another active build.
+// The lock and every takeover guard record the owner's PID and start time, so a
+// PID reused by an unrelated process never keeps a dead owner's lock alive.
+export async function localOperation(root, inheritedToken) {
+  const directory = join(root, '.wrangler/local-operation')
+  await privateDirectory(root, directory)
+  const path = join(directory, 'active.json')
+  if (inheritedToken) {
+    let owner
+    try { owner = JSON.parse(await readFile(path, 'utf8')) } catch { /* Fixed diagnostic below. */ }
+    if (owner?.token !== inheritedToken || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) {
+      throw new Error('The parent local setup operation is no longer active. Run the command again.')
+    }
+    if (!await ownerAlive(owner)) throw new Error('The parent local setup process has stopped. Run the command again.')
+    return { token: inheritedToken, release: async () => {} }
+  }
+  const self = await currentProcess()
+  let file
+  for (let attempt = 0; !file; attempt++) {
+    try { file = await open(path, 'wx', 0o600) } catch (error) {
+      if (error.code !== 'EEXIST') throw error
+      // A killed process cannot release its lock. Take over only when the
+      // recorded process is gone; a half-written file gets a short grace.
+      if (attempt === 0 && await takeOver(path)) continue
+      throw await busy(path)
+    }
+  }
+  const token = randomUUID()
+  try { await file.writeFile(JSON.stringify({ ...self, token })) } finally { await file.close() }
+  const acquired = await identity(path)
+  return { token, release: async () => {
+    if (await identity(path) === acquired) await unlink(path).catch(missing)
+  } }
+}
+
+async function currentProcess() {
+  return { pid: process.pid, start: await processStart(process.pid) }
+}
+
+// A recorded owner is alive only while its PID exists and, when the record
+// carries a start time, that PID still names the same process.
+export async function ownerAlive(owner) {
+  try { process.kill(owner.pid, 0) } catch (error) {
+    if (error.code === 'ESRCH') return false
+    if (error.code !== 'EPERM') throw error
+  }
+  if (typeof owner.start !== 'string') return true
+  return await processStart(owner.pid) === owner.start
+}
+
+// Removing a stale lock by name alone could remove a lock another starter has
+// just created. Every starter that judged the same stale file competes for one
+// exclusive guard named after that file's identity; only the guard holder may
+// remove it, and only while the path still names that exact file. A new lock
+// has a new identity, so it can never be removed as stale.
+async function takeOver(path) {
+  const judged = await staleIdentity(path)
+  if (judged === undefined) return false
+  if (judged === null) return true // Already gone: retry the exclusive create.
+  const guardPath = `${path}.takeover-${judged}`
+  let guard
+  for (let attempt = 0; !guard; attempt++) {
+    try { guard = await open(guardPath, 'wx', 0o600) } catch (error) {
+      if (error.code !== 'EEXIST') throw error
+      // Another starter is taking over; it, or a faster starter, owns the lock.
+      // A guard whose owner was killed is removed once, after its grace.
+      if (attempt > 0 || !await removeAbandonedGuard(guardPath, path)) return false
+    }
+  }
+  try {
+    await guard.writeFile(JSON.stringify(await currentProcess()))
+    const current = await identity(path)
+    if (current === judged) await unlink(path).catch(missing)
+    return true
+  } finally {
+    await guard.close()
+    await unlink(guardPath).catch(missing)
+  }
+}
+
+// Returns the identity of a stale lock, null when the lock is already gone, or
+// undefined when a live (or freshly created) lock holds the path. Judge and
+// identify through one descriptor so the verdict belongs to that exact file.
+async function staleIdentity(path) {
+  let handle
+  try { handle = await open(path, 'r') } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try {
+    const status = await handle.stat({ bigint: true })
+    const id = key(status)
+    try {
+      const owner = JSON.parse(await handle.readFile('utf8'))
+      if (Number.isSafeInteger(owner.pid) && owner.pid > 0) return await ownerAlive(owner) ? undefined : id
+    } catch { /* Half-written or unreadable: judged by age below. */ }
+    return Date.now() - Number(status.mtimeMs) > graceMs ? id : undefined
+  } finally { await handle.close() }
+}
+
+// A takeover guard left by a killed starter would otherwise block every later
+// build. After the grace, a guard whose recorded owner is gone (or that was
+// never written) is moved aside and removed. The move is checked against the
+// judged file; a guard created meanwhile is put back, never discarded.
+async function removeAbandonedGuard(guardPath, lockPath) {
+  let handle
+  try { handle = await open(guardPath, 'r') } catch (error) {
+    if (error.code === 'ENOENT') return true
+    throw error
+  }
+  let judged
+  try {
+    const status = await handle.stat({ bigint: true })
+    if (Date.now() - Number(status.mtimeMs) <= graceMs) return false
+    let owner
+    try { owner = JSON.parse(await handle.readFile('utf8')) } catch { /* Never written: abandoned. */ }
+    if (Number.isSafeInteger(owner?.pid) && owner.pid > 0 && await ownerAlive(owner)) {
+      throw new Error(`A stale-lock takeover has held ${guardPath} for more than ${graceMs / 1000} s. If no local setup or build is running, delete it and ${lockPath}, then run again.`)
+    }
+    judged = movedKey(status)
+  } finally { await handle.close() }
+  const aside = `${guardPath}.abandoned-${randomUUID()}`
+  try { await rename(guardPath, aside) } catch (error) {
+    if (error.code === 'ENOENT') return true
+    throw error
+  }
+  if (movedKey(await lstat(aside, { bigint: true })) !== judged) {
+    // Another starter replaced the abandoned guard first. Restore its guard
+    // without replacing a newer one, and let that starter finish.
+    await link(aside, guardPath).catch((error) => { if (error.code !== 'EEXIST') throw error })
+    await unlink(aside)
+    return false
+  }
+  await unlink(aside)
+  return true
+}
+
+const missing = (error) => { if (error.code !== 'ENOENT') throw error }
+
+async function identity(path) {
+  try { return key(await lstat(path, { bigint: true })) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+// Inode numbers can be reused after deletion; the change time cannot repeat.
+const key = (status) => `${status.dev}-${status.ino}-${status.ctimeNs}`
+// A rename changes ctime, so a moved file is matched by its unchanged fields.
+const movedKey = (status) => `${status.dev}-${status.ino}-${status.birthtimeNs}-${status.mtimeNs}`

package/onboarding/local/owner.mjs

@@ -0,0 +1,34 @@
+import {readdir,lstat} from 'node:fs/promises';
+import {join} from 'node:path';
+import {DatabaseSync} from 'node:sqlite';
+
+// Read only the canonical local D1 files, before settings/build/migrations can
+// mutate anything. An unrelated database does not establish an owner claim.
+export async function localOwners(root){
+ const found=[];
+ let directory=root;
+ for(const part of ['.wrangler','state','v3','d1','miniflare-D1DatabaseObject']){
+  directory=join(directory,part);let status;try{status=await lstat(directory);}catch(error){if(error.code==='ENOENT')return []; throw error;}
+  if(status.isSymbolicLink()||!status.isDirectory())throw Error('Canonical local state is unsafe. Preserve it and recover its placement before setup.');
+ }
+ for(const file of await readdir(directory,{withFileTypes:true})){
+  if(!file.isFile()||!file.name.endsWith('.sqlite'))continue;
+  let db,owners=[];
+  try{db=new DatabaseSync(join(directory,file.name),{readOnly:true});
+   const tables=new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(row=>row.name));
+   if(tables.has('oa_operators'))owners=db.prepare("SELECT email FROM oa_operators WHERE role='owner' AND status='active'").all();
+  }finally{db?.close();}
+  found.push(...owners.map(owner=>owner.email).filter(email=>typeof email==='string'));
+ }
+ return [...new Set(found)];
+}
+export async function assertLocalOwner(root,email,failure=message=>Error(message),inspect,setting='private owner email setting'){
+ const owners=inspect?await inspect(root):await localOwners(root);
+ if(!Array.isArray(owners)||owners.some(owner=>typeof owner!=='string'))throw failure('The localOwner hook must return existing owner email addresses without changing state.');
+ if(owners.length&&!owners.some(owner=>owner.toLowerCase()===email.toLowerCase())){
+  const address=safeOwner(owners[0]);
+  throw failure(`Local database already belongs to ${address}. Restore ${setting} to ${address}, then run rer setup --owner-email ${address}; or back up data and run rer reset --yes. Existing data and private settings were kept.`);
+ }
+ return owners;
+}
+export const safeOwner=email=>email.length<=254&&/^[a-zA-Z0-9.!+_%\-]+@[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+$/.test(email)?email:'<existing-owner-email>';

package/onboarding/local/process-table.mjs

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs';
+import { execFile } from 'node:child_process'
+import { readFile, readdir } from 'node:fs/promises'
+import { promisify } from 'node:util'
+
+const execute = promisify(execFile)
+export const validPid = (pid) => Number.isSafeInteger(pid) && pid > 0 && pid <= 0x7fffffff
+
+// Inspect only numeric process metadata: command lines can contain credentials.
+// Linux's start ticks distinguish recycled PIDs more precisely than ps lstart.
+
+export function parseLinuxProcess(pid, pgid, text) {
+  if (!validPid(pid) || !validPid(pgid) || !text.startsWith(`${pid} (`) || !text.includes(') ')) {
+    throw new Error('Invalid process identity.')
+  }
+  const fields = text.slice(text.lastIndexOf(')') + 2).trim().split(/\s+/)
+  const ppid = Number(fields[1])
+  if (Number(fields[2]) !== pgid) return
+  if (!Number.isSafeInteger(ppid) || ppid < 0 || !/^\d+$/.test(fields[19])) {
+    throw new Error('Invalid process identity.')
+  }
+  return { pid, ppid, pgid, state: fields[0], birth: fields[19] }
+}
+
+async function processGroup(pgid, signal, deadline) {
+  if (process.platform === 'linux') {
+    // Minimal Linux containers need not install ps. Procfs provides exact
+    // start ticks and includes zombies until their actual parent reaps them.
+    const pids = (await readdir('/proc')).filter((name) => /^\d+$/.test(name)).map(Number).filter(validPid)
+    const group = []
+    // Procfs metadata reads are tiny kernel snapshots. Avoid hundreds of
+    // thread-pool round trips delaying cooperative shutdown; retain an explicit
+    // deadline and every PID/start-tick check while scanning the same inventory.
+    for (const pid of pids) {
+      signal.throwIfAborted()
+      if (Date.now() >= deadline) throw new Error('Process inspection deadline expired.')
+      let text
+      try { text = readFileSync(`/proc/${pid}/stat`, 'utf8') } catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ESRCH') continue
+        throw error
+      }
+      const member = parseLinuxProcess(pid, pgid, text)
+      if (member) group.push(member)
+    }
+    return group
+  }
+  const { stdout } = await execute('/bin/ps', [
+    '-ax', '-o', 'pid=', '-o', 'ppid=', '-o', 'pgid=', '-o', 'stat=', '-o', 'lstart=',
+  ], { env: { ...process.env, LC_ALL: 'C' }, signal, killSignal: 'SIGKILL', maxBuffer: 8 * 1024 * 1024 })
+  const group = []
+  for (const line of stdout.split('\n').filter((line) => line.trim())) {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/)
+    if (!match) throw new Error('Could not read process identities.')
+    const [, id, parent, groupId, state, birth] = match
+    const pid = Number(id)
+    const ppid = Number(parent)
+    if (Number(groupId) !== pgid) continue
+    if (!validPid(pid) || !Number.isSafeInteger(ppid) || ppid < 0 || !Number.isFinite(Date.parse(birth))) {
+      throw new Error('Invalid process identity.')
+    }
+    group.push({ pid, ppid, pgid, state, birth })
+  }
+  return group
+}
+
+export async function readOwnedGroup(pgid, timeout = 1000) {
+  if (!validPid(pgid)) throw new Error('Invalid owned process group.')
+  if (!(timeout > 0)) throw new Error('Process inspection deadline expired.')
+  const controller = new AbortController()
+  let timer
+  try {
+    return await Promise.race([processGroup(pgid, controller.signal, Date.now() + timeout), new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        controller.abort()
+        reject(new Error('Process inspection deadline expired.'))
+      }, timeout)
+    })])
+  } finally { clearTimeout(timer) }
+}
+
+export const sameProcess = (left, right) => left?.pid === right?.pid
+  && left?.pgid === right?.pgid && left?.birth === right?.birth
+
+// A process start time distinguishes a live owner from an unrelated process that
+// reused its PID. Linux reports start ticks since boot; elsewhere ps reports a
+// one-second start time, read in UTC so every caller sees the same value.
+// Returns undefined when no process has this PID.
+export async function processStart(pid) {
+  if (!validPid(pid)) throw new Error('Invalid process identity.')
+  if (process.platform === 'linux') {
+    let text
+    try { text = await readFile(`/proc/${pid}/stat`, 'utf8') } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ESRCH') return undefined
+      throw error
+    }
+    const fields = text.slice(text.lastIndexOf(')') + 2).trim().split(/\s+/)
+    if (!/^\d+$/.test(fields[19] ?? '')) throw new Error('Invalid process identity.')
+    return `linux:${fields[19]}`
+  }
+  let stdout
+  try {
+    ({ stdout } = await execute('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], {
+      env: { ...process.env, LC_ALL: 'C', TZ: 'UTC' }, killSignal: 'SIGKILL', timeout: 5000,
+    }))
+  } catch (error) {
+    // ps exits 1 when the PID does not exist.
+    if (error.code === 1 && !String(error.stdout ?? '').trim()) return undefined
+    throw error
+  }
+  if (!stdout.trim()) return undefined
+  const started = Date.parse(`${stdout.trim()} UTC`)
+  if (!Number.isFinite(started)) throw new Error('Invalid process identity.')
+  return `ps:${started}`
+}