@runeditrun/rer 0.0.0-stage → 0.1.1

package/onboarding/local/recovery.mjs

@@ -0,0 +1,79 @@
+import { readdir, rmdir, unlink } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { inspect } from './files.mjs'
+import { buildDestination, inspectBuildFile, restoreBuildFile } from './build-files.mjs'
+import { localOperation } from './operation.mjs'
+
+// Legacy setup/build names and encoded build inventory names retain private
+// originals across a hard kill. The next local operation recovers them first.
+const hiddenOriginals = [['local-build', 'original.dev.vars'], ['local-setup', 'previous.dev.vars']]
+
+export async function strandedOriginals(root) {
+  const found = []
+  // Never follow a symlinked output directory; setup refuses those itself.
+  const realDirectory = async (path) => { const status = await inspect(path); return status?.isDirectory() && !status.isSymbolicLink() }
+  if (!await realDirectory(join(root, '.wrangler'))) return found
+  for (const [folder, name] of hiddenOriginals) {
+    const directory = join(root, '.wrangler', folder)
+    if (!await realDirectory(directory)) continue
+    let runs
+    try { runs = await readdir(directory, { withFileTypes: true }) } catch (error) {
+      if (error.code === 'ENOENT') continue
+      throw error
+    }
+    for (const run of runs) {
+      if (!run.isDirectory() || !run.name.startsWith('run-')) continue
+      const path = join(directory, run.name, name)
+      const status = await inspect(path)
+      if (status?.isFile()) found.push({ path, status, folder, file: '.dev.vars' })
+      if (folder === 'local-build') {
+        for (const entry of await readdir(join(directory, run.name), { withFileTypes: true })) {
+          const file = buildDestination(entry.name)
+          if (!file) continue
+          const hidden = join(directory, run.name, entry.name)
+          const status = await inspect(hidden)
+          if (!status?.isFile() || status.isSymbolicLink()) throw new Error('Unsafe private build recovery file.')
+          found.push({ path: hidden, status, folder, file })
+        }
+      }
+    }
+  }
+  return found
+}
+
+// Restores stranded private originals before anything reads or replaces them.
+// Recovery runs under the operation lock, so a live build's hidden file is
+// never taken: that build owns the lock and the caller is told to wait. Returns
+// the operation the caller now holds (the one passed in, or a new one).
+export async function recoverInterrupted(root, operation) {
+  if ((await strandedOriginals(root)).length === 0) return operation
+  const held = operation ?? await localOperation(root)
+  try { await restore(root) } catch (error) {
+    if (!operation) await held.release()
+    throw error
+  }
+  return held
+}
+
+async function restore(root) {
+  const stranded = await strandedOriginals(root)
+  for (const file of new Set(stranded.map(item => item.file))) {
+    const items = stranded.filter(item => item.file === file)
+    const current = (await inspectBuildFile(root, file, { publication: true })).status
+    const pending = []
+    for (const item of items) {
+      if (current && item.status.ino === current.ino && item.status.dev === current.dev) await unlink(item.path)
+      else pending.push(item)
+    }
+    if (current) {
+      for (const item of pending) console.error(`An interrupted build or setup left an earlier private copy of ${file} at ${item.path}. The current file was kept; delete that copy once you no longer need it.`)
+      continue
+    }
+    if (pending.length > 1) throw new Error(`${file} is missing and interrupted runs left several private originals:\n${pending.map(item => `  ${item.path}`).join('\n')}\nMove the one to keep to ${file}, then run again.`)
+    if (!pending.length) continue
+    const [item] = pending
+    await restoreBuildFile(root, item)
+    if (item.folder === 'local-build') await rmdir(dirname(item.path)).catch(() => {})
+    console.error(`Restored ${file} from an interrupted build or setup (${item.path}).`)
+  }
+}

package/onboarding/local/state.mjs

@@ -0,0 +1,31 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+export class LocalStateSafetyError extends Error {}
+async function physicalPath(path) {
+ const absolute = resolve(path), parent = resolve(absolute, '..');
+ if (parent === absolute) return realpath(absolute);
+ const physicalParent = await physicalPath(parent), candidate = resolve(physicalParent, relative(parent, absolute));
+ let status; try { status = await lstat(candidate); } catch (error) { if (error.code === 'ENOENT') return candidate; throw error; }
+ if (status.isSymbolicLink()) { try { return await realpath(candidate); } catch { throw new LocalStateSafetyError('Local state safety: unresolved symlink. Preserve it and resolve placement before retrying.'); } }
+ return candidate;
+}
+function contains(parent, path) { const suffix = relative(parent, path); return suffix === '' || (!isAbsolute(suffix) && suffix !== '..' && !suffix.startsWith('..' + sep)); }
+export async function selectLocalState(root, persistTo = process.env.RER_LOCAL_STATE_PATH ?? '.wrangler/state') {
+ if (typeof persistTo !== 'string' || !persistTo.trim()) throw new LocalStateSafetyError('Local state safety: choose an explicit nonempty persistence directory.');
+ const checkout = await realpath(root), lexical = resolve(checkout, persistTo), state = await physicalPath(lexical);
+ for (const name of ['dist', '.output', '.tanstack', 'node_modules', '.wrangler/deploy']) {
+  const output = resolve(checkout, name), physical = await physicalPath(output);
+  for (const [a, b] of [[lexical, output], [state, physical]]) if (contains(a, b) || contains(b, a)) throw new LocalStateSafetyError(`Local state safety: persistence overlaps generated ${name}. Preserve data and resolve placement.`);
+ }
+ if (lexical !== resolve(checkout, '.wrangler/state') || state !== lexical) throw new LocalStateSafetyError('Local state safety: canonical persistence must be contained at .wrangler/state without symlinks. Preserve existing data and recover it explicitly.');
+ for (const name of ['.wrangler/reference', 'dist/server/.wrangler/state', 'dist/.wrangler/state', '.output/server/.wrangler/state']) {
+  const legacy = resolve(checkout, name); await physicalPath(legacy);
+  try { await lstat(legacy); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+  throw new LocalStateSafetyError(`Local state safety: legacy state exists at ${name}. Preserve it and explicitly recover its data; nothing was moved or deleted.`);
+ }
+ for (const name of ['.wrangler', '.wrangler/state']) {
+  let status; try { status = await lstat(resolve(checkout, name)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (status && (!status.isDirectory() || status.isSymbolicLink())) throw new LocalStateSafetyError('Local state safety: state must be a directory without symlinks. Preserve it and resolve placement.');
+ }
+ return state;
+}

package/onboarding/metadata.mjs

@@ -0,0 +1,7 @@
+import { execFile } from 'node:child_process';
+const command=(root,tool,args)=>new Promise(resolve=>execFile(tool,args,{cwd:root,timeout:8000,maxBuffer:10000},(error,stdout)=>resolve(error?null:stdout.trim())));
+export async function metadata(root){
+ const [name,email,remote,github]=await Promise.all([command(root,'git',['config','user.name']),command(root,'git',['config','user.email']),command(root,'git',['remote','get-url','origin']),command(root,'gh',['api','user','--jq','.login'])]);
+ let repository=null;if(remote){const match=remote.match(/github\.com[:/]([^\s?#]+?)(?:\.git)?$/);if(match)repository=match[1]}
+ return {name,email,repository,githubAccount:github,cloudflareAccount:process.env.CLOUDFLARE_ACCOUNT_ID||null,cloudflareAuthentication:process.env.CLOUDFLARE_API_TOKEN?'environment-token':'not-checked',nodeWarning:process.versions.node.split('.').map(Number).some(Number.isNaN)?null:(Number(process.versions.node.split('.')[0])===26&&Number(process.versions.node.split('.')[1])<8?'This checkout recommends Node 26.8.1 or later.':null)};
+}

package/onboarding/operator-install.mjs

@@ -0,0 +1,45 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, unlink } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { chooseOrigin } from './adapter-settings.mjs';
+import { privateDirectory, writePrivateFile } from './private-files.mjs';
+import { installationFailure, installationFailureMessage } from './failures.mjs';
+import { labels } from './adapter-labels.mjs';
+
+// The browser and terminal use the same bounded setup journey. Its temporary
+// runtime is gone before that lease releases. The foreground preview belongs
+// to the installer process, outside the bounded job's descendant tree.
+export async function installOperator(root,input,store,onApp,signal,hooks){
+ let answer,app,step='setup';
+ try{
+  await store.configureQueue?.({verb:'installer'});
+  const origin=await chooseOrigin({root,input,store},hooks),address=new URL(origin);
+  const directory=await privateDirectory(root,['.seed','installer']);
+  answer=join(directory,`answers-${randomUUID()}.json`);
+  await writePrivateFile(answer,JSON.stringify(input));
+  // The browser owns no local operation. A verifier may have launched it while
+  // holding a different checkout's token; each public command takes its own.
+  const env={...process.env};delete env.RER_LOCAL_OPERATION;
+  const run=(label,args)=>store.run(label,process.execPath,['scripts/rer.mjs',...args,'--non-interactive','--json'],{cwd:root,signal,env,heavy:false});
+  step='dependencies';await store.step(labels.dependencies);await run(labels.dependencies,['install']);
+  step='setup';await store.step(labels.build);await run(labels.build,['setup','--answers',relative(root,answer),'--host',address.hostname.replace(/^\[|\]$/g,''),'--port',address.port]);
+  await unlink(answer);answer=undefined;
+  // Preview's ready event carries RER_OPEN; keep the checkout's dev key out of this log.
+  const devKey=/^RER_DEV_KEY=(\S+)$/m.exec(await readFile(join(root,'.rer/local/dev-key.env'),'utf8').catch(()=>''))?.[1];if(devKey)store.addSecrets?.([devKey]);
+  step='start';await store.step(labels.start);
+  app=store.spawn(labels.start,process.execPath,['scripts/rer.mjs','preview','--non-interactive','--json'],{cwd:root,signal,env});onApp(app);
+  let buffer='',ready=false,openUrl;
+  app.stdout.on('data',chunk=>{buffer+=chunk;let end;while((end=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,end);buffer=buffer.slice(end+1);try{const event=JSON.parse(line);if(event.version===1&&event.verb==='preview'&&event.event==='ready'&&event.url===origin){ready=true;openUrl=event.openUrl;}}catch{}}});
+  await store.waitForReady(labels.start,app,async probeSignal=>{
+   if(!ready)return {ready:false,message:'Waiting for managed application readiness'};
+   const response=await fetch(origin+'/health',{signal:probeSignal});
+   return {ready:response.ok&&(await response.json()).status==='ok'};
+  },{signal,timeoutMs:1200000});
+  // A dev-identity seed's outbox needs the key exchange RER_OPEN carries. State
+  // never holds the key: the installer page asks /api/open-app when it shows the link.
+  store.state.appUrl=origin+'/__dev/outbox';store.state.devOpen=Boolean(openUrl?.startsWith(origin+'/'));await store.step(labels.complete);await store.phase('complete');
+ }catch(error){
+  if(app)await store.stop(app);await store.stopCommands?.(signal);
+  store.state.error=installationFailureMessage(installationFailure('command_failed',{step,diagnostic:error}));await store.phase('failed');
+ }finally{if(answer)await unlink(answer);}
+}

package/onboarding/operator-installer.mjs

@@ -0,0 +1,39 @@
+import {fileURLToPath} from 'node:url';
+import { privateDirectory } from './private-files.mjs';
+import { localInstaller } from './adapter.mjs';
+import { selectLocalState, LocalStateSafetyError } from './local/state.mjs';
+import {operatorPrerequisites} from './operator-prerequisites.mjs';
+import { installOperator } from './operator-install.mjs';
+import { projectViteBinary } from './project-vite.mjs';
+import { join, delimiter } from 'node:path';
+
+export function operatorInstaller({ database, features, prepare, prepareData }) {
+ const lifecycle=localInstaller({
+  features, node: '22.20.0',
+  failure: (error,{store})=>error instanceof LocalStateSafetyError ? store.redact(error.message) : undefined,
+  async prepare(context) { context.localState = await selectLocalState(context.root); await privateDirectory(context.root, ['.wrangler', 'state']); await prepare?.(context); },
+  prepareData,
+  guard: async ({ root }) => { await selectLocalState(root); },
+  secrets: {
+   keepExisting: true, originKey: 'AUTH_ORIGIN',
+   values: ({ origin }) => ({ AUTH_LOCAL: 'true', AUTH_ORIGIN: origin, MAIL_PROVIDER: 'development', MAIL_FROM: 'auth@localhost.test' }),
+  },
+  build: ['pnpm', ['run', 'build:app']],
+  migrate: ['pnpm', ['exec', 'wrangler', 'd1', 'migrations', 'apply', database, '--local', '--persist-to', '.wrangler/state', '--config', 'dist/server/wrangler.json']],
+  // Setup uses preview's production runtime behind the same public proxy.
+  start: previewTarget,
+  owner: { existingOwnerViaSignIn: true, displayName: input => input.displayName || 'Owner' },
+  signIn: { emailKey: 'OWNER_EMAIL', returnTo: '/setup' },
+ });
+ return {...lifecycle,localPrerequisites:async({root,vars,email})=>vars.AUTH_LOCAL==='true'&&vars.MAIL_PROVIDER==='development'&&Boolean(vars.SESSION_SECRET)&&await operatorPrerequisites(root,email),install:(root,input,store,onApp,signal)=>installOperator(root,input,store,onApp,signal,lifecycle.hooks)};
+}
+
+// Only local runtimes receive the dev key; vite.config.ts passes it to `vite dev` alone.
+// No runtime rer starts serves the Local Explorer: it reads and writes the store
+// without the key. trafficProxy also refuses /cdn-cgi/* on the public listener.
+const devBindings = (devKey, devLogin) => devKey ? { RER_DEV_KEY: devKey, RER_DEV_IDENTITY: devLogin ? 'off' : 'on' } : {};
+const internalPort = port => { if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('A local runtime requires the traffic proxy internal port.'); return String(port); };
+const developmentEnvironment = () => { const { RER_MODELS_SERVICE, RER_MODELS_KEY, ...env } = process.env; return env; };
+export const developmentTarget = ({ root, origin, runtimePort, devKey, devLogin, modelsLive }) => [process.execPath, [projectViteBinary(root), 'dev', '--host', '127.0.0.1', '--port', internalPort(runtimePort), '--strictPort'], { env: { ...developmentEnvironment(), PATH: join(root, 'node_modules', '.bin') + delimiter + (process.env.PATH ?? ''), RER_DEV_ORIGIN: origin, WRANGLER_SEND_METRICS: 'false', X_LOCAL_EXPLORER: 'false', ...devBindings(devKey, devLogin), ...(modelsLive ? { RER_MODELS_SERVICE: modelsLive.baseUrl, RER_MODELS_KEY: modelsLive.apiKey } : {}) } }];
+
+export const previewTarget = ({ origin, runtimePort, devKey, scheduled }) => [process.execPath, [fileURLToPath(new URL('./production-runtime.mjs', import.meta.url))], { env: { ...process.env, RER_DEV_ORIGIN: origin, RER_RUNTIME_HOST: '127.0.0.1', RER_RUNTIME_PORT: internalPort(runtimePort), WRANGLER_SEND_METRICS: 'false', CLOUDFLARE_INCLUDE_PROCESS_ENV: 'false', X_LOCAL_EXPLORER: 'false', RER_RUNTIME_TRIGGERS: scheduled ? '1' : '0', ...(devKey ? { RER_DEV_KEY: devKey } : {}) } }];

package/onboarding/operator-prerequisites.mjs

@@ -0,0 +1,27 @@
+import { readdir,lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+// A read-only preflight prevents an empty resource directory from being treated
+// as completed setup. Ordinary application sign-in then verifies the actual
+// configured binding before readiness; no database or owner is created here.
+export async function operatorPrerequisites(root,email){
+ const migrations=(await readdir(join(root,'migrations/core'))).filter(name=>name.endsWith('.sql'));
+ const directory=join(root,'.wrangler/state/v3/d1/miniflare-D1DatabaseObject');
+ let files;try{
+  let path=root;for(const part of ['.wrangler','state','v3','d1','miniflare-D1DatabaseObject']){path=join(path,part);const info=await lstat(path);if(!info.isDirectory()||info.isSymbolicLink()||info.uid!==process.getuid())return false;}
+  files=await readdir(directory,{withFileTypes:true});}catch{return false;}
+ for(const file of files){
+  if(!file.isFile()||!file.name.endsWith('.sqlite'))continue;
+  let db;
+  try{
+   db=new DatabaseSync(join(directory,file.name),{readOnly:true});
+   const applied=new Set(db.prepare('SELECT name FROM d1_migrations').all().map(row=>row.name));
+   const claimed=db.prepare('SELECT COUNT(*) AS count FROM oa_bootstrap').get().count;
+   const owner=db.prepare("SELECT COUNT(*) AS count FROM oa_operators WHERE email=? AND role='owner' AND status='active'").get(email).count;
+   if(claimed===1&&owner===1&&migrations.every(name=>applied.has(name)))return true;
+  }catch{/* A missing/corrupt/unrelated database cannot prove prior setup. */}
+  finally{db?.close();}
+ }
+ return false;
+}

package/onboarding/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@run-edit-run/onboarding",
+  "private": true,
+  "type": "module",
+  "description": "Dependency-free Base seed installer and local runner; seeds copy its runtime source without Base tests."
+}

package/onboarding/prefill.mjs

@@ -0,0 +1,16 @@
+import { readFile } from 'node:fs/promises';
+import { SETUP_VALUE_LIMIT, setupInputLimit } from './input-limits.mjs';
+export function validateAnswers(input,{fields,safeKeys}) {
+ if(!input||typeof input!=='object'||Array.isArray(input))throw Error('Provide a JSON object of known nonsecret answers.');
+ const answers={};
+ for(const [key,value] of Object.entries(input)){
+  if(!safeKeys.includes(key))throw Error('Only supported nonsecret answer fields are accepted. Use the secure stdin path for credentials.');
+  if(typeof value!=='string'||value.length>SETUP_VALUE_LIMIT)throw Error('Answers must be strings within the field limits.');
+  if(value!==''&&!fields[key].valid(value))throw Error(`Invalid ${(fields[key].label||key).toLowerCase()}.`);
+  if(value&&fields[key].type==='url')answers[key]=new URL(value).origin;else answers[key]=value;
+ }
+ for(const [key,mode] of [['prefix','prefixMode'],['appOrigin','addressMode']])if(safeKeys.includes(mode)&&answers[key]&&!Object.hasOwn(answers,mode))answers[mode]='custom';
+ return answers;
+}
+export async function readAnswers(path,model){const text=await readFile(path,'utf8');if(Buffer.byteLength(text)>setupInputLimit(model))throw Error('The answers file is too large.');let value;try{value=JSON.parse(text)}catch{throw Error('The answers file must contain valid JSON.')}return validateAnswers(value,model)}
+export async function readSecrets(stream,model){const limit=setupInputLimit(model);let text='';for await(const chunk of stream){text+=chunk;if(Buffer.byteLength(text)>limit)throw Error('Secure input is too large.')}try{return JSON.parse(text)}catch{throw Error('Secure stdin must contain a JSON object.')}}

package/onboarding/private-files.mjs

@@ -0,0 +1,97 @@
+import { constants, linkSync, unlinkSync, writeSync, openSync, closeSync, fstatSync, fchmodSync, ftruncateSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function requireOwner(stat, path, directory = false) {
+ if (!(directory ? stat.isDirectory() : stat.isFile()) || (!directory && stat.nlink > 1 && (stat.mode & 0o7777) !== 0o600) || (process.getuid && stat.uid !== process.getuid())) {
+  throw Error(`Installer private storage must be an owned ${directory ? 'directory' : 'regular private file (no permissive hard links)'}: ${path}`);
+ }
+}
+
+// Refuse links and foreign-owned storage before changing permissions or bytes.
+export async function privateDirectory(root, parts) {
+ let path = root;
+ for (const part of parts) {
+  path = join(path, part);
+  try { await mkdir(path, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try { const stat = await handle.stat(); requireOwner(stat, path, true); if ((stat.mode & 0o7777) !== 0o700) await handle.chmod(0o700); } finally { await handle.close(); }
+  // Self-ignore on both creation and resume. Atomic private-file replacement
+  // validates existing ownership/links before changing any bytes.
+  if (part === '.seed') await writePrivateFile(join(path, '.gitignore'), '*\n');
+ }
+ return path;
+}
+
+async function privateFile(path, flags, action) {
+ const handle = await open(path, flags | constants.O_NOFOLLOW, 0o600);
+ try {
+  const stat = await handle.stat();
+  requireOwner(stat, path);
+  // Already-private hard links are safe to read or replace. Never chmod their
+  // shared inode; this also permits a complete exclusive publication in flight.
+  if (stat.nlink <= 1 && (stat.mode & 0o7777) !== 0o600) await handle.chmod(0o600);
+  return await action(handle);
+ } finally { await handle.close(); }
+}
+export const readPrivateFile = path => privateFile(path, constants.O_RDONLY, handle => handle.readFile('utf8'));
+export async function writePrivateFile(path, content, exclusive = false) {
+ if (!exclusive) {
+  try { await privateFile(path, constants.O_RDONLY, () => {}); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+ }
+ const temporary = `${path}.${randomBytes(16).toString('hex')}.tmp`;
+ try {
+  await privateFile(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+   async handle => { await handle.writeFile(content); });
+  if (exclusive) {
+   // Publish complete bytes without replacing another process's credential.
+   // Readers can safely use the fully written, already-private linked inode.
+   // A process interruption before unlink does not invalidate the receipt.
+   linkSync(temporary, path);
+   unlinkSync(temporary);
+  } else await rename(temporary, path);
+ } finally {
+  try { await unlink(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+ }
+}
+
+// Validate each append, so replacement with a link is refused as well. Short
+// synchronous writes cannot queue unbounded command output or leak descriptors.
+export const PRIVATE_LOG_LIMIT = 16 * 1024 * 1024;
+const TRUNCATED = Buffer.from('\n[log truncated]\n');
+
+export async function openPrivateLog(path) {
+ let written=0, truncated=false, closed=false;
+ const withFile = action => {
+  const fd=openSync(path,constants.O_WRONLY|constants.O_APPEND|constants.O_CREAT|constants.O_NOFOLLOW,0o600);
+  try {
+   const stat=fstatSync(fd);requireOwner(stat,path);
+   if(stat.nlink!==1)throw Error('Installer append logs must not have hard links.');
+   if((stat.mode&0o7777)!==0o600)fchmodSync(fd,0o600);
+   action(fd,stat);
+  } finally {closeSync(fd);}
+ };
+ const writeAll = (fd,bytes) => { let offset=0;while(offset<bytes.length)offset+=writeSync(fd,bytes,offset,bytes.length-offset); };
+ // O_TRUNC would destroy linked targets before validation. Truncate only after
+ // the opened inode passes the same ownership/link checks as every append.
+ withFile(fd=>ftruncateSync(fd,0));
+ const append = text => {
+  if(closed||truncated||!text)return;
+  withFile((fd,stat)=>{
+   written=Math.max(written,stat.size);
+   const available=Math.max(0,PRIVATE_LOG_LIMIT-TRUNCATED.length-written);
+   // The caller normally emits small chunks. Bound conversion here too so a
+   // direct huge write cannot allocate a second copy of the entire input.
+   const source=String(text), length=Buffer.byteLength(source);
+   const bytes=Buffer.from(source.slice(0,available));
+   let end=Math.min(bytes.length,available);
+   // Do not leave half of a UTF-8 code point before the truncation marker.
+   if(end<bytes.length)while(end>0&&(bytes[end]&0xc0)===0x80)end--;
+   writeAll(fd,bytes.subarray(0,end));written+=end;
+   if(length>available){writeAll(fd,TRUNCATED);written+=TRUNCATED.length;truncated=true;}
+  });
+ };
+ return {write:append,close:async()=>{closed=true;}};
+}

package/onboarding/private.mjs

@@ -0,0 +1,35 @@
+import { unlink } from 'node:fs/promises';
+import { privateDirectory, readPrivateFile, writePrivateFile } from './private-files.mjs';
+import { join } from 'node:path';
+import { randomBytes, createHash } from 'node:crypto';
+export async function installationReceipt(root,origin,scope){
+ await privateDirectory(root,['.seed','installer','private']);
+ const path=join(root,'.seed/installer/private',createHash('sha256').update(origin).digest('hex')+'.json');
+ let saved;try{saved=JSON.parse(await readPrivateFile(path))}catch(error){if(error.code==='ENOENT')return null;throw error}
+ if(saved.origin!==origin||typeof saved.token!=='string'||!saved.token)throw Error('The saved installation receipt is invalid. Preserve it and inspect this installation before continuing.');
+ if(scope&&(saved.accountId!==scope.accountId||saved.prefix!==scope.prefix))throw Error('The saved installation receipt does not identify this Cloudflare account and Worker. Preserve it and verify the existing installation before continuing.');
+ return saved;
+}
+export async function installationCredential(root,origin,scope){
+ const directory=await privateDirectory(root,['.seed','installer','private']);
+ const path=join(directory,createHash('sha256').update(origin).digest('hex')+'.json');
+ let saved=await installationReceipt(root,origin,scope);let token=saved?.token,deployed=saved?.deployed===true;
+ const record=()=>({...saved,origin,token,...(scope?{accountId:scope.accountId,prefix:scope.prefix}:{})});
+ if(!token){token=randomBytes(32).toString('hex');try{await writePrivateFile(path,JSON.stringify(record()),true)}catch(error){if(error.code!=='EEXIST')throw error;saved=await installationReceipt(root,origin,scope);token=saved.token;deployed=saved.deployed===true}}
+ return {token,deployed,markDeployed:()=>writePrivateFile(path,JSON.stringify({...record(),deployed:true})),clear:()=>unlink(path)};
+}
+export async function localSetupToken(root,key){
+ try{const text=await readPrivateFile(join(root,'.dev.vars'));const line=text.split(/\r?\n/).find(value=>value.slice(0,value.indexOf('=')).trim()===key);if(!line)return undefined;const value=line.slice(line.indexOf('=')+1).trim();return /^['"].*['"]$/.test(value)?value.slice(1,-1):value}catch(error){if(error.code==='ENOENT')return undefined;throw error}
+}
+export function stopChild(child){if(!child||!child.pid||child.exitCode!==null||child.signalCode!==null)return;try{process.kill(-child.pid,'SIGTERM')}catch{child.kill('SIGTERM')}}
+export async function persistLocalEmail(root,variables){
+ const path=join(root,'.dev.vars');let content='';try{content=await readPrivateFile(path)}catch(error){if(error.code!=='ENOENT')throw error}
+ const lines=content.split(/\r?\n/).filter(line=>!Object.keys(variables).some(key=>line.startsWith(key+'=')));
+ await writePrivateFile(path,lines.join('\n').replace(/\n*$/,'\n')+Object.entries(variables).map(([key,value])=>key+'='+JSON.stringify(value)).join('\n')+'\n');
+}
+export async function localEmailBindings(root){
+ let text;try{text=await readPrivateFile(join(root,'.dev.vars'))}catch(error){if(error.code==='ENOENT')return {};throw error}
+ const allowed=new Set(['EMAIL_PROVIDER','EMAIL_FROM','EMAIL_ACCOUNT_ID','EMAIL_API_KEY']);const values={};
+ for(const line of text.split(/\r?\n/)){const index=line.indexOf('=');const key=line.slice(0,index).trim();if(index<0||!allowed.has(key))continue;let value=line.slice(index+1).trim();if(value.startsWith('"')){try{value=JSON.parse(value)}catch{continue}}else if(value.startsWith("'")&&value.endsWith("'"))value=value.slice(1,-1);values[key]=value}
+ return values;
+}

package/onboarding/process-cleanup.mjs

@@ -0,0 +1,134 @@
+import { setTimeout as delay } from 'node:timers/promises'
+import { inspectionMs, readProcessIdentity, readProcessTable, sameBirth, sameProcess, validPid } from './process-table.mjs'
+import { readOwnedTree } from './process-tree.mjs'
+
+const graceMs = 1000
+const cleanupMs = 30000
+// macOS ps already spaces observations by tens of milliseconds.
+const pollMs = process.platform === 'darwin' ? 5 : 25
+const isZombie = (member) => member.state.startsWith('Z')
+const isStopped = (member) => /^[Tt]/.test(member.state)
+const key = (member) => `${member.pid}:${member.birth}:${member.command}`
+const isLeaf = (member, group) => !group.some((other) => other.ppid === member.pid)
+
+// Ask every owned process to shut down gracefully, including supervisors that
+// would restart a killed worker. Forced escalation is leaf-first so surviving
+// parents can reap children. Every signal rechecks numeric birth identity.
+export async function stopOwnedGroup(child, signal, ownership) {
+  const pgid = child.pid
+  if (!validPid(pgid)) throw new Error('Invalid owned process group.')
+  const deadline = Date.now() + cleanupMs
+  // Even callers without a prior capture must establish actual ancestry. A
+  // same-PGID sibling is not ours, and a lost launcher cannot establish custody.
+  ownership ??= await readOwnedTree(child)
+  const inspect = async (timeout) => {
+    const current = await readOwnedTree(child, ownership, timeout)
+    // Retain departed group leaders as provenance, not as signal targets.
+    for (const member of current) if (!ownership.some(saved => sameProcess(saved, member))) ownership.push(member)
+    return current
+  }
+  let group
+  const signalled = new Map()
+  const stopped = new Map()
+  let lastGroup = []
+
+  const snapshot = async (limit = deadline) => {
+    const current = await inspect(Math.min(inspectionMs, limit - Date.now()))
+    if (Date.now() >= limit) throw new Error('Process inspection deadline expired.')
+    lastGroup = current
+    return current
+  }
+  const send = async (member, name, requireLeaf = true, limit = deadline) => {
+    // Recheck both identity and children immediately before each numeric PID
+    // signal. Never send a negative/group signal that can kill parents first.
+    const timeout = Math.min(inspectionMs, limit - Date.now())
+    const current = requireLeaf ? await readProcessTable(timeout) : []
+    const target = await readProcessIdentity(member.pid, Math.min(inspectionMs, limit - Date.now()))
+    if (Date.now() >= limit) throw new Error('Process inspection deadline expired.')
+    if (!sameProcess(member, target) || isZombie(target)) return false
+    if (requireLeaf && !isLeaf(target, current)) return false
+    if (name === 'SIGKILL' && !isStopped(target)) return false
+    if (requireLeaf && target.pid === pgid && current.some(other => other.pid !== pgid
+      && ownership.some(saved => sameBirth(saved, other)))) return false
+    // The full identity was read immediately before this numeric signal. A
+    // stopped leaf cannot fork across its final SIGKILL inspection. Discovery
+    // continues on every outer scan, including after a graceful late fork.
+    try { process.kill(target.pid, name) } catch (error) {
+      if (error.code !== 'ESRCH') throw new Error(`Could not send ${name} to owned process ${target.pid}.`)
+      return false
+    }
+    return true
+  }
+
+  // A captured direct supervisor can receive its graceful shutdown signal
+  // promptly. Identity is rechecked first; no group or descendant is signalled
+  // until scoped/ancestry discovery establishes its own full identity.
+  const leader = ownership.find(member => member.pid === pgid)
+  if (leader && child.exitCode == null && child.signalCode == null) {
+    const live = await readProcessIdentity(pgid, inspectionMs)
+    if (sameProcess(leader, live) && live.ppid === process.pid && !isZombie(live)) {
+      try { process.kill(pgid, signal); signalled.set(key(live), Date.now()) }
+      catch (error) { if (error.code !== 'ESRCH') throw new Error(`Could not send ${signal} to owned process ${pgid}.`) }
+    }
+  }
+
+  const unfinished = (cause) => new Error(`Owned processes remain after cancellation (last observed ${lastGroup.map((member) => `${member.pid}:${isZombie(member) ? 'zombie' : 'live'}`).join(', ')}).`, { cause })
+  let cleanupError
+  try {
+    while (Date.now() < deadline) {
+      group = await snapshot()
+      if (!group.length) {
+        await delay(pollMs)
+        group = await snapshot()
+        if (!group.length && (child.exitCode !== null || child.signalCode !== null)) return
+        if (!group.length) continue
+      }
+      let resuming = false
+      // Resume raced parents before considering any leaves, regardless of the
+      // order ps returns them. Confirm SIGCONT took effect on the next scan.
+      for (const member of group) {
+        if (!stopped.has(key(member)) || isLeaf(member, group)) continue
+        // SIGCONT also cancels a still-pending SIGSTOP; a running snapshot
+        // alone is not evidence that our stop can no longer suspend a parent.
+        if (await send(member, 'SIGCONT', false)) stopped.delete(key(member))
+        resuming = true
+      }
+      if (resuming) { await delay(pollMs); continue }
+      for (const member of group) {
+        if (Date.now() >= deadline) break
+        const identity = key(member)
+        if (isZombie(member)) continue
+        if (!signalled.has(identity)) {
+          // A supervisor needs its shutdown signal before its worker disappears;
+          // otherwise normal restart behavior can keep this tree alive forever.
+          if (await send(member, signal, false)) signalled.set(identity, Date.now())
+        } else if (Date.now() - signalled.get(identity) >= graceMs) {
+          if (!isLeaf(member, group) || (member.pid === pgid && group.length !== 1)) continue
+          if (!stopped.has(identity)) {
+            // Freeze only a childless process before its final inspection. It
+            // cannot fork between that inspection and SIGKILL once stopped.
+            if (await send(member, 'SIGSTOP')) stopped.set(identity, member)
+          } else if (isStopped(member)) {
+            if (await send(member, 'SIGKILL')) stopped.delete(identity)
+          }
+        }
+      }
+      await delay(pollMs)
+    }
+    throw unfinished()
+  } catch (error) {
+    cleanupError = Date.now() >= deadline ? unfinished(error) : error
+    throw cleanupError
+  } finally {
+    // Inspection/signalling failures must not leave a process suspended.
+    const errors = []
+    const resumeDeadline = Math.min(deadline + 1000, Date.now() + 1000)
+    for (const member of stopped.values()) {
+      try { await send(member, 'SIGCONT', false, resumeDeadline) } catch (error) { errors.push(error) }
+    }
+    // Preserve the original failure while reporting a failure to resume an owned process.
+    // eslint-disable-next-line no-unsafe-finally
+    if (errors.length) throw new AggregateError([cleanupError, ...errors].filter(Boolean),
+      [cleanupError?.message, 'Could not resume every suspended owned process.', ...errors.map((error) => error.message)].filter(Boolean).join(' '))
+  }
+}

package/onboarding/process-diagnostics.mjs

@@ -0,0 +1,91 @@
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {realpath,readFile,readdir,readlink} from 'node:fs/promises';
+import {basename,join} from 'node:path';
+const exec=promisify(execFile);
+// macOS supplies lsof in /usr/sbin, which a command PATH may omit.
+// Diagnose sockets with the system utility even when that PATH is constrained.
+const lsof=process.platform==='darwin'?'/usr/sbin/lsof':'lsof';
+const run=async(command,args)=>{
+ try{return (await exec(command,args,{timeout:3000,maxBuffer:1024*1024})).stdout;}
+ catch(error){
+  // lsof exits 1 when a selected PID has exited,
+  // while still returning the live listeners of other selected PIDs.
+  return command===lsof&&error.code===1&&typeof error.stdout==='string'?error.stdout:'';
+ }
+};
+export async function processName(pid){
+ if(process.platform==='linux'){const name=await readFile(`/proc/${pid}/comm`,'utf8').catch(()=>'');if(name)return name.trim().replace(/[^a-zA-Z0-9._-]/g,'').slice(0,80)||'process';}
+ const text=await run('/bin/ps',['-p',String(pid),'-o','comm=']);
+ return basename(text.trim()).replace(/[^a-zA-Z0-9._-]/g,'').slice(0,80)||'process';
+}
+function records(text){let record;const rows=[];for(const line of text.split('\n')){if(line[0]==='p'){record={pid:Number(line.slice(1)),names:[]};rows.push(record);}else if(line[0]==='n'&&record)record.names.push(line.slice(1));}return rows;}
+export async function listeners(pids){
+ // -a is essential: otherwise lsof ORs the PID and network selections and
+ // still walks every process's sockets. Read only the owned tree on failure.
+ if(process.platform!=='linux')return records(await run(lsof,['-nP',...(pids?['-a','-p',pids.join(',')]:[]),'-iTCP','-sTCP:LISTEN','-Fpn']));
+ const sockets=new Map();
+ for(const file of ['tcp','tcp6'])for(const line of (await readFile('/proc/net/'+file,'utf8').catch(()=>'' )).trim().split('\n').slice(1)){
+  const parts=line.trim().split(/\s+/);if(parts[3]==='0A')sockets.set(parts[9],parseInt(parts[1].split(':')[1],16));
+ }
+ const found=[];
+ for(const pid of pids??await linuxPids()){
+  const names=[];for(const target of await descriptors(pid)){const inode=/^socket:\[(\d+)\]$/.exec(target)?.[1];if(sockets.has(inode))names.push('127.0.0.1:'+sockets.get(inode));}
+  if(names.length)found.push({pid,names});
+ }return found;
+}
+async function linuxPids(){return (await readdir('/proc')).filter(name=>/^\d+$/.test(name)).map(Number);}
+async function descriptors(pid){return Promise.all((await readdir(`/proc/${pid}/fd`).catch(()=>[])).map(fd=>readlink(`/proc/${pid}/fd/${fd}`).catch(()=>'')));}
+
+const portOf=name=>Number(/:(\d+)$/.exec(name)?.[1]);
+export async function processCwd(pid){
+ if(process.platform==='linux')return readlink(`/proc/${pid}/cwd`).catch(()=>undefined);
+ return records(await run(lsof,['-a','-p',String(pid),'-d','cwd','-Fpn'])).flatMap(row=>row.names)[0];
+}
+// Every TCP port some process listens on, on any address: a wildcard listener
+// does not stop a bind to 127.0.0.1, yet it still serves that port's traffic.
+export async function listeningPorts(){return new Set((await listeners()).flatMap(row=>row.names.map(portOf)).filter(Number.isInteger));}
+// The process that listens on a port on the given host's address or on every
+// address, with its command and working directory.
+export async function portListener(port,host){
+ const bare=host?.replace(/^\[|\]$/g,''),serves=name=>{const address=name.slice(0,name.lastIndexOf(':')).replace(/^\[|\]$/g,'');return portOf(name)===port&&(!host||address==='*'||address===bare);};
+ const row=(await listeners()).find(item=>item.names.some(serves));
+ return row&&{pid:row.pid,command:await processName(row.pid),cwd:await processCwd(row.pid)};
+}
+
+export async function listenerPorts(pid){
+ // Include child processes: pnpm commonly delegates the actual Vite listener.
+ const rows=(await run('/bin/ps',['-axo','pid=,ppid='])).trim().split('\n').map(line=>line.trim().split(/\s+/).map(Number));
+ const owned=new Set([pid]);for(let changed=true;changed;){changed=false;for(const [child,parent]of rows)if(owned.has(parent)&&!owned.has(child)){owned.add(child);changed=true;}}
+ return [...new Set((await listeners([...owned])).filter(row=>owned.has(row.pid)).flatMap(row=>row.names.map(name=>Number(/:(\d+)$/.exec(name)?.[1])).filter(port=>Number.isInteger(port)&&port>0&&port<=65535)))].sort((a,b)=>a-b);
+}
+// The caller and the chain that launched it (an installer server running setup,
+// pnpm, a shell) act for this command, never against it.
+async function callerLineage(){
+ const parents=new Map((await run('/bin/ps',['-axo','pid=,ppid='])).trim().split('\n').map(line=>line.trim().split(/\s+/).map(Number)));
+ const lineage=new Set([process.pid,process.ppid]);
+ for(let pid=process.ppid;pid>1&&parents.has(pid);){pid=parents.get(pid);if(lineage.has(pid))break;lineage.add(pid);}
+ return lineage;
+}
+export async function localProcessConflict(root,savedOrigin){
+ root=await realpath(root);const all=await listeners(),lineage=await callerLineage();
+ const cwdRecords=process.platform!=='linux'&&all.length?records(await run(lsof,['-a','-p',all.map(row=>row.pid).join(','),'-d','cwd','-Fpn'])):[];
+ let port;try{const url=new URL(savedOrigin);port=Number(url.port||80);}catch{}
+ for(const row of all){
+  if(lineage.has(row.pid))continue;
+  const onSavedPort=port&&row.names.some(name=>Number(/:(\d+)$/.exec(name)?.[1])===port);
+  const cwd=process.platform==='linux'?[await readlink(`/proc/${row.pid}/cwd`).catch(()=>undefined)].filter(Boolean):cwdRecords.filter(item=>item.pid===row.pid).flatMap(item=>item.names);
+  const places=(await Promise.all(cwd.map(path=>realpath(path).catch(()=>undefined)))).filter(Boolean),inCheckout=places.includes(root);
+  // A listener running somewhere else is another program's or another checkout's
+  // server: it does not use this checkout's state, so it only blocks the port.
+  if(onSavedPort&&places.length&&!places.some(place=>place===root||place.startsWith(root+'/')))continue;
+  if(onSavedPort||inCheckout)return {pid:row.pid,command:await processName(row.pid),reason:onSavedPort?`saved local port ${port}`:'this checkout'};
+ }
+ // A process may hold the canonical database without listening. Inspect only
+ // actual state files, never broad checkout contents or a process environment.
+ const state=join(root,'.wrangler/state');
+ let held;
+ if(process.platform==='linux'){for(const pid of await linuxPids())if(!lineage.has(pid)&&(await descriptors(pid)).some(path=>path.startsWith(state+'/'))){held={pid};break;}}
+ else held=records(await run(lsof,['-nP','+D',state,'-Fpn'])).find(row=>!lineage.has(row.pid));
+ if(held)return {pid:held.pid,command:await processName(held.pid),reason:'the canonical local state'};
+}