@runeditrun/rer 0.0.0-stage → 0.1.1

package/cli/auth-copy.mjs

@@ -0,0 +1,80 @@
+import { readFile, readdir, lstat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { contained } from './project.mjs';
+
+// SC-05.auth-copy: the operator-auth layers a seed copied from Base stay the
+// bytes of the Base revision it pinned. A seed records its copies in
+// base-copies.json (edition authoring) or composition.lock.json /
+// foundation.lock.json (composed foundations); each records the SHA-256 of the
+// Base bytes it copied. Two groups are checked on their own: the application,
+// runtime and schema copies (one revision pins them all, since they are coupled)
+// and the CLI's bundled tooling under scripts/base-cli (one revision of its
+// own, which a CLI refresh moves without touching the application's auth). Each
+// drifted, missing or unrecorded file in either group is named. A seed that
+// imports Base in place has no copy.
+const ORIGIN = 'modules/operator-auth';
+const CLI_ROOT = 'scripts/base-cli';
+const within = (path, prefix) => path === prefix || path.startsWith(`${prefix}/`);
+const groupOf = path => typeof path === 'string' && within(path, CLI_ROOT) ? 'cli' : 'application';
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+async function json(root, path) { try { return JSON.parse(await readFile(await contained(root, path), 'utf8')); } catch { return null; } }
+
+// Every file under a copied directory, so an added file is named too.
+async function walk(root, path) {
+ let stat; try { stat = await lstat(await contained(root, path)); } catch { return []; }
+ if (stat.isFile()) return [path];
+ if (!stat.isDirectory()) return [path];
+ const files = [];
+ for (const entry of await readdir(join(root, path), { withFileTypes: true })) files.push(...await walk(root, `${path}/${entry.name}`));
+ return files;
+}
+
+// [{ group, path, revision, files: { local path: sha256 } }] for every recorded auth copy.
+async function recordedCopies(root) {
+ const copies = [];
+ const record = await json(root, 'base-copies.json');
+ for (const copy of record?.copies ?? []) {
+  if (typeof copy?.originPath === 'string' && within(copy.originPath, ORIGIN) && copy.files && typeof copy.files === 'object') copies.push({ path: copy.path, revision: copy.revision, files: copy.files, directory: copy.originPath === ORIGIN, group: groupOf(copy.path) });
+ }
+ for (const name of ['composition.lock.json', 'foundation.lock.json']) {
+  const lock = await json(root, name);
+  if (!lock?.files) continue;
+  const revision = lock.repositories?.base?.commit ?? lock.base?.commit;
+  for (const group of ['application', 'cli']) {
+   const entries = Object.entries(lock.files).filter(([path, file]) => groupOf(path) === group && typeof file?.source === 'string' && within(file.source, ORIGIN));
+   const files = Object.fromEntries(entries.filter(([, file]) => typeof file.sha256 === 'string').map(([path, file]) => [path, file.sha256]));
+   const directories = [...new Set(entries.filter(([, file]) => !file.source.endsWith('.sql')).map(([path, file]) => path.slice(0, path.length - (file.source.length - ORIGIN.length))))];
+   if (Object.keys(files).length) copies.push({ path: directories[0] ?? null, revision, files, directory: directories.length === 1, group });
+  }
+ }
+ return copies;
+}
+
+export async function authCopyClauses(root) {
+ const copies = await recordedCopies(root);
+ if (!copies.length) return [];
+ const clauses = [];
+ for (const [group, id, scope] of [['application', 'SC-05.auth-copy.pin', 'the application, runtime and schema copies'], ['cli', 'SC-05.auth-copy.cli-pin', `the CLI's bundled copy under ${CLI_ROOT}`]]) {
+  const grouped = copies.filter(copy => copy.group === group);
+  if (!grouped.length) continue;
+  const revisions = [...new Set(grouped.map(copy => copy.revision))];
+  clauses.push([id, revisions.length === 1 && /^[a-f0-9]{40}$/.test(revisions[0] ?? ''), `Copy ${scope} of operator-auth from one pinned Base revision; the seed records ${revisions.join(', ') || 'none'}.`]);
+ }
+ for (const copy of copies) {
+  for (const [path, expected] of Object.entries(copy.files)) {
+   let actual = null; try { actual = sha256(await readFile(await contained(root, path))); } catch {}
+   clauses.push([`SC-05.auth-copy.${path}`, actual === expected, actual === null
+    ? `${path} is missing; restore it from Base ${copy.revision}.`
+    : `${path} differs from Base ${copy.revision}; restore the copied bytes or record a new pin with refresh-base.`]);
+  }
+  if (copy.directory && copy.path) {
+   for (const path of await walk(root, copy.path)) {
+    if (!Object.hasOwn(copy.files, path) && !path.split('/').some(part => ['tests', 'node_modules', '.DS_Store'].includes(part))) {
+     clauses.push([`SC-05.auth-copy.${path}`, false, `${path} is not part of Base ${copy.revision}'s operator-auth; remove it or keep seed code outside the copied layers.`]);
+    }
+   }
+  }
+ }
+ return clauses;
+}

package/cli/bounded.mjs

@@ -0,0 +1,70 @@
+import {mkdtemp,rm} from 'node:fs/promises';
+import {join} from 'node:path';
+import {tmpdir} from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {shared} from './shared.mjs';
+import {RerError} from './errors.mjs';
+
+// Admit the complete bounded workflow before it can acquire checkout custody.
+// The child re-enters the same dispatcher with validated live queue membership.
+// Hold the child's semantic outcome until queue and process custody are released.
+// Child diagnostics remain captured/redacted on stderr. Long-lived servers never
+// enter this boundary.
+export async function boundedCommand(project,options,argv,out){
+ if(!['install','setup','build','verify','deploy','export','import'].includes(options.verb))return null;
+ const {commandPolicy,queuedCommand,queueLabel}=await shared('queue.mjs');
+ const policy=await commandPolicy();
+ const childArgs=[...argv];const cwdIndex=childArgs.indexOf('--cwd');if(cwdIndex>=0&&(childArgs.indexOf('--')<0||cwdIndex<childArgs.indexOf('--')))childArgs[cwdIndex+1]=project.root;
+ const directory=await mkdtemp(join(tmpdir(),'rer-bounded-'));
+ let store,result,finalEvent,errorEvent,buffer='';
+ const cancellation=new AbortController();
+ const handlers=new Map(['SIGINT','SIGTERM'].map(name=>[name,()=>cancellation.abort(name)]));
+ for(const [name,handler] of handlers)process.on(name,handler);
+ try{
+  const {createCommands}=await shared('commands.mjs');
+  store=await createCommands(directory,{logs:[]},{terminal:()=>{}});
+  result=await queuedCommand(process.execPath,[fileURLToPath(new URL('../bin/rer.mjs',import.meta.url)),...childArgs],{
+   cwd:project.root,signal:cancellation.signal,stdio:[!options.json&&!options.nonInteractive?'inherit':'ignore','pipe','pipe'],originalCI:policy.ci,env:{...process.env,...policy.environment,RER_BOUNDED_OUTPUT:'1'},
+   label:await queueLabel(project.root,options.verb,'workflow'),report:text=>out.progress(store.redact(text)+'\n'),onWaiting:options.json?details=>out.event('waiting',details):undefined,
+   spawn:(command,args,native)=>{
+    const child=store.spawn('Running bounded workflow',command,args,native);
+    const stderr=store.redactionStream(text=>out.progress(text));
+    child.stderr.on('data',chunk=>stderr.write(chunk));child.stderr.once('end',()=>stderr.end());
+    child.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);
+     let event;try{event=JSON.parse(line);}catch{}
+     if(event?.version===1&&event.verb===options.verb){
+      if(event.event==='result')finalEvent=event;
+      else if(event.event==='error')errorEvent=event;
+      else out.human(store.redact(JSON.stringify(event)));
+     }else if(!options.json)out.human(store.redact(line));
+    }});
+    child.stdout.once('end',()=>{if(buffer&&!options.json)out.human(store.redact(buffer));buffer='';});return child;
+   },
+   cleanup:async child=>{
+    await store.stop(child);
+    if(project.profile==='first-party'){
+     const {recoverInterrupted}=await shared('local/recovery.mjs');
+     const held=await recoverInterrupted(project.root);await held?.release();
+    }
+   }
+  });
+ }finally{
+  try{await store?.closeCommands();await policy.close();await rm(directory,{recursive:true,force:true});}
+  finally{for(const [name,handler] of handlers)process.off(name,handler);}
+ }
+ const termination=cancellation.signal.aborted?cancellation.signal.reason:undefined;
+ if(!result&&!termination)return null;
+ const exitCode=termination?(termination==='SIGINT'?130:143):result.code;
+ if(termination){
+  out.error(new RerError('cancelled',`Stopped by ${termination} after owned children were stopped.`,exitCode));
+  out.result(false,exitCode);
+ }else if(finalEvent&&finalEvent.exitCode===exitCode){
+  if(errorEvent)out.error(new RerError(errorEvent.code,store.redact(errorEvent.message),exitCode));
+  const {version,verb,event,ok,exitCode:childExit,...details}=finalEvent;
+  out.result(exitCode===0,exitCode,JSON.parse(store.redact(JSON.stringify(details))));
+ }else{
+  const error=new RerError('command_failed',result.supervisorEnded?store.redact(result.error):'Bounded command ended before its result; owned children and private files were recovered.',exitCode||1);
+  out.error(error);out.result(false,error.exitCode);return {exitCode:error.exitCode};
+ }
+ return {exitCode};
+}

package/cli/cache-doctor.mjs

@@ -0,0 +1,63 @@
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { nodeCache } from './node-runtime-cache.mjs';
+import { projectNodePin } from './node-runtime-discovery.mjs';
+
+// Read-only warnings about disk this machine spends twice: Node releases and
+// workerd binaries that checkouts pin differently, quarantine copies nothing
+// cleaned up, and a checkout on a volume where pnpm cannot clone from its store.
+// None of these stop anything, so they never change doctor's ok.
+const MB = 1024 * 1024;
+
+async function size(path) {
+ const info = await stat(path).catch(() => undefined);
+ if (!info) return 0;
+ if (!info.isDirectory()) return info.size;
+ let total = 0;
+ for (const entry of await readdir(path).catch(() => [])) total += await size(join(path, entry));
+ return total;
+}
+
+// Other checkouts this machine knows about: the ones with a dev or preview
+// server registered right now.
+async function runningCheckouts(env) {
+ const directory = resolve(env.RER_SERVERS_DIR ?? join(homedir(), '.rer/servers'));
+ let records;
+ try { records = JSON.parse(await readFile(join(directory, 'state.json'), 'utf8')).running ?? []; } catch { return []; }
+ const found = [];
+ for (const checkout of new Set(records.map(record => record.checkout))) {
+  try { found.push(await realpath(checkout)); } catch {}
+ }
+ return found;
+}
+
+async function pins(root) {
+ const read = async file => { try { return JSON.parse(await readFile(join(root, file), 'utf8')); } catch { return {}; } };
+ const store = await readdir(join(root, 'node_modules/.pnpm')).catch(() => []);
+ return {
+  Node: await projectNodePin(root).catch(() => undefined),
+  pnpm: (await read('package.json')).packageManager?.replace(/^pnpm@/, ''),
+  workerd: [...new Set(store.filter(name => /^workerd@\d/.test(name)).map(name => name.slice('workerd@'.length).split('_')[0]))].sort().join(' and ') || undefined,
+ };
+}
+
+const COSTS = { Node: 'about 125 MB for each extra release', pnpm: 'a separate pnpm download', workerd: 'about 125-145 MB for each extra version' };
+
+export async function cacheWarnings(root, { env = process.env } = {}) {
+ const warnings = [], here = await realpath(root), mine = await pins(here);
+ const cache = nodeCache(), entries = (await readdir(cache).catch(() => [])).filter(name => /^node-v\d/.test(name));
+ for (const name of entries.filter(name => name.includes('.quarantine-'))) {
+  warnings.push(`${join(cache, name)} is a leftover quarantine copy of a Node release (${Math.round(await size(join(cache, name)) / MB)} MB). Delete it with: rm -r ${JSON.stringify(join(cache, name))}`);
+ }
+ const releases = entries.filter(name => !name.includes('.quarantine-')).map(name => name.slice(6).split('-')[0]);
+ if (releases.length > 1 && mine.Node) warnings.push(`The Node cache ${cache} holds ${releases.length} releases (${releases.join(', ')}) and this checkout pins ${mine.Node}. Each release is about 125 MB; delete the ones no checkout pins.`);
+ const homeDevice = (await stat(homedir())).dev, peers = (await runningCheckouts(env)).filter(path => path !== here);
+ if ((await stat(here)).dev !== homeDevice) warnings.push(`This checkout is on another volume than your home folder, where rer keeps its Node cache and pnpm its package store. pnpm cannot clone packages across volumes, so this checkout copies them in full (0.4-0.9 GB instead of 0.02-0.17 GB). Move it to the same volume.`);
+ for (const peer of peers) {
+  const theirs = await pins(peer);
+  for (const [name, value] of Object.entries(mine)) if (value && theirs[name] && value !== theirs[name]) warnings.push(`${peer} pins ${name} ${theirs[name]} and this checkout pins ${value}; every distinct pin keeps its own copy (${COSTS[name]}). Align them when you can.`);
+  if ((await stat(peer)).dev !== (await stat(here)).dev) warnings.push(`${peer} is on another volume than this checkout, so the two cannot share pnpm's package store by cloning files.`);
+ }
+ return warnings;
+}

package/cli/container-transfer.mjs

@@ -0,0 +1,35 @@
+import { writeFile, mkdir, mkdtemp, link, rm } from 'node:fs/promises';
+import { dirname, basename, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileRecords } from '../modules/portability/files.mjs';
+const execute=promisify(execFile);
+export async function containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy,transient}) {
+ if(direction==='import')for(const file of [path,journal].filter(Boolean))for await(const record of fileRecords(file)){}
+ const spec={direction,binding,buckets,policy,transient,file:basename(path),journal:journal?'/private/later.rer':undefined};
+ const encoded=JSON.stringify(spec,(_key,value)=>{if(typeof value==='function')throw new Error('Container local transfer needs a serializable archive policy; use native remote transport for this product');return value;});
+ const configuration=join(root,'.rer/container/transfer.json');await mkdir(dirname(configuration),{recursive:true,mode:0o700});await mkdir(dirname(path),{recursive:true,mode:0o700});await writeFile(configuration,encoded,{mode:0o600});
+ const identity='rer-local-'+createHash('sha256').update(root).digest('hex').slice(0,16),image=identity+':candidate',name='rer-transfer-'+randomUUID();
+ let child,temporary;
+ try {
+  await execute('docker',['create','--name',name,'--entrypoint','sh','-v',identity+'-data:/data',image,'-c','umask 077; exec flock -n --no-fork /data/host.lock node /runtime/modules/container/transfer.mjs']);
+  await execute('docker',['cp',configuration,name+':/private/transfer.json']);
+  if(direction==='import'){
+   await execute('docker',['cp',path,name+':/archive/'+spec.file]);
+   if(journal)await execute('docker',['cp',journal,name+':/private/later.rer']);
+  }
+  child=store.spawn('Transferring container archive','docker',['start','--attach',name],{cwd:root,signal});
+  let output='';child.stdout.on('data',chunk=>output+=chunk);const code=await new Promise(resolve=>{child.once('error',()=>resolve(1));child.once('close',resolve);});await store.stop(child);
+  if(code!==0)throw new Error('Container archive transfer failed');const receipt=JSON.parse(output.trim().split('\n').at(-1));
+  if(direction==='export'){
+   temporary=await mkdtemp(join(dirname(path),'.rer-transfer-'));
+   const copied=join(temporary,'archive.rer');await execute('docker',['cp',name+':/archive/'+spec.file,copied]);
+   for await(const record of fileRecords(copied)){}
+   await link(copied,path);
+  }
+  return{target:'local',platform:'container',...receipt};
+ }finally{
+  await store.stop(child).catch(()=>{});await execute('docker',['stop','-t','10',name]).catch(()=>{});await execute('docker',['rm','-f',name]).catch(()=>{});if(temporary)await rm(temporary,{recursive:true,force:true});
+ }
+}

package/cli/container.mjs

@@ -0,0 +1,62 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { shared } from './shared.mjs';
+import { selectedOrigin } from './local.mjs';
+import { refuse, missing } from './errors.mjs';
+import { refuseLocalModels } from '../modules/deploy-kit/local-only.mjs';
+import { deployInputs } from '../modules/container/deploy-input.mjs';
+import { ingressBindings } from '../modules/container/ssh-plan.mjs';
+import { deploySSH, sshTarget } from '../modules/container/ssh.mjs';
+const execute=promisify(execFile);
+async function run(command,args,options={}) {
+ const child=spawn(command,args,{...options,stdio:'inherit'}),abort=()=>child.kill('SIGTERM');
+ process.once('SIGTERM',abort);process.once('SIGINT',abort);
+ try{await new Promise((resolve,reject)=>{child.once('error',reject);child.once('exit',code=>code===0?resolve():reject(new Error('Container command failed')));});}
+ finally{process.off('SIGTERM',abort);process.off('SIGINT',abort);if(child.exitCode===null&&child.signalCode===null)child.kill('SIGTERM');}
+}
+export async function containerCommand(project,options,out) {
+ if(options.stop)return runContainer(project,options,out);
+ const {localOperation}=await shared('local/operation.mjs'),{recoverInterrupted}=await shared('local/recovery.mjs');
+ const operation=await localOperation(project.root,process.env.RER_LOCAL_OPERATION);
+ try{await recoverInterrupted(project.root,operation);return await runContainer(project,options,out,operation);}catch(error){if(error.code==='SSH_HOST_REFUSAL')throw refuse(error.message);throw error;}finally{await operation.release();}
+}
+async function runContainer(project,options,out,operation) {
+ const {root}=project;
+ if(options.verb==='deploy'){try{await refuseLocalModels(root);}catch{throw refuse('Deploy refuses the local-only key file .rer/local/models.json. Remove live-dev credentials before deployment.');}}
+ const config=JSON.parse(await readFile(join(root,'deploy.json'),'utf8'));
+ if(!(config.platforms??['workers']).includes('container'))throw refuse('This seed does not declare container support.');
+ const name='rer-local-'+createHash('sha256').update(root).digest('hex').slice(0,16),image=name+':candidate';
+ if(options.stop){await execute('docker',['stop','-t','10',name]);return{stopped:true};}
+ if(['build','deploy'].includes(options.verb)){
+  if(options.verb==='deploy'){if(!options.host)throw missing('Container deploy requires --host ssh://user@host.');sshTarget(options.host);await deployInputs({root,envFile:options.envFile,localOnlyKeys:project.adapter?.localOnlyKeys});}
+  const ingress={...(options.bindAddress?{address:options.bindAddress}:{}),...(options.httpPort?{httpPort:options.httpPort}:{}),...(options.httpsPort?{httpsPort:options.httpsPort}:{})};
+  ingressBindings({...config.container?.ingress,...ingress});
+  if(!options.image){
+   const {withoutLocalVariables}=await shared('local/build.mjs'),{buildEnvironment}=await shared('local/environment.mjs');
+   const declaration=await readFile(join(root,'seed.json'),'utf8').then(JSON.parse).catch(()=>({}));
+   const declared=Array.isArray(declaration.env)?declaration.env.map(item=>item.name):Object.keys(declaration.env??{});
+   await withoutLocalVariables(root,async()=>{
+    const builder=fileURLToPath(new URL('../modules/container/build.mjs',import.meta.url));
+    await run(process.execPath,[builder,root],{cwd:root,env:buildEnvironment([...declared,...(config.secrets??[]).flatMap(item=>[item.binding,item.environment])])});
+    await run('docker',['build','--tag',image,join(root,'.rer/container/image')],{cwd:root});
+   },{nested:operation.token,settings:[...(project.adapter?.settings??[]),...(project.privateInputs??[])]});
+  }
+  if(options.verb==='build')return{platform:'container',image};
+  if(!options.host)throw missing('Container deploy requires --host ssh://user@host.');
+  return deploySSH({root,image:options.image??image,ingress,host:options.host,envFile:options.envFile,environment:options.environment,localOnlyKeys:project.adapter?.localOnlyKeys,dryRun:options.dryRun});
+ }
+ if(['dev','preview'].includes(options.verb)){
+  const selected=await selectedOrigin(project,options),env=join(root,'.rer/container/local.env');
+  await mkdir(join(root,'.rer/container'),{recursive:true,mode:0o700});
+  const local={...selected.vars,[config.originVar]:selected.url,PORT:'8080',RER_CONTAINER_IDLE_SECONDS:String(options.idleTimeout)};const {stdout}=await execute('docker',['image','inspect','--format','{{.Id}}',image]);local.RER_IMAGE_DIGEST=stdout.trim();
+  await writeFile(env,Object.entries(local).map(([key,value])=>`${key}=${String(value).replaceAll('\n','\\n')}`).join('\n')+'\n',{mode:0o600});
+  out.human('RER_OPEN '+selected.url);
+  await run('docker',['run','--rm','--name',name,'--env-file',env,'-p',`${selected.host}:${selected.port}:8080`,'-v',name+'-data:/data',image],{cwd:root});
+  return{platform:'container',stopped:true};
+ }
+ throw refuse('Unsupported container command');
+}

package/cli/contract.mjs

@@ -0,0 +1,25 @@
+export const pins = Object.freeze({ node: '22.20.0', pnpm: '10.12.4' });
+// What a server start applies when the person sets nothing (RER_SERVER_LIMIT,
+// RER_SERVER_IDLE_SECONDS or --idle-timeout). describe reports them.
+export const serverDefaults = Object.freeze({ serverLimit: 10, idleSeconds: 43200 });
+export const commonFlags = ['--help', '--cwd', '--non-interactive', '--json'];
+const definitions = {
+ install: [[], 'Frozen dependency installation; no setup or global tool changes.'],
+ setup: [['--owner-email', '--owner-name', '--port', '--host', '--answers'], 'Build, migrate, prepare private settings and first owner; stop the temporary app.'],
+ dev: [['--port', '--host', '--idle-timeout', '--stop', '--as', '--login', '--models', '--models-service'], 'Foreground development with assets, HMR and the declared scheduled triggers run locally on their schedule. With devIdentity it opens signed in as the owner (--as PERSONA picks another start, --login uses the outbox sign-in instead); otherwise ordinary owner sign-in through the outbox.'],
+ preview: [['--port', '--host', '--idle-timeout', '--stop'], 'Foreground fixed production output; reuse intact build, preserve owner/state, idle timeout and explicit stop.'],
+ build: [[], 'Production build with private local settings excluded and restored.'],
+ verify: [[], 'Run the complete internal verification target.'],
+ reset: [['--yes'], 'Confirmed removal of the declared local inventory only.'],
+ deploy: [['--environment', '--dry-run', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port'], 'Owner-account deployment and health; dry run performs local validation/build only.'],
+ export: [['--target', '--output', '--origin', '--session-file'], 'Complete supported installation archive with integrity and exclusions.'],
+ import: [['--target', '--input', '--journal', '--origin', '--session-file', '--yes', '--legacy-v1', '--acknowledge-unverified-metadata', '--output'], 'Confirmed atomic restore into an empty destination; --journal LATER_ARCHIVE also fences rows that installation erased since. Backup-only local v1 recovery requires --legacy-v1 --acknowledge-unverified-metadata and a new --output v2 archive; --journal requires normal v2 import.'],
+ outbox: [['--port', '--host', '--owner-email', '--open'], 'Credential-free local outbox URL; optional ordinary sign-in request and explicit browser opening.'],
+ doctor: [[], 'Read-only installed tool, configuration and state diagnostics.'],
+ describe: [[], 'Read-only description of actual command capabilities.'],
+ check: [['--profile'], 'Read-only structural command contract and operations validation.'],
+};
+export const verbs = Object.fromEntries(Object.entries(definitions).map(([name, [flags, effects]]) => [name, { flags: [...commonFlags, ...flags, ...(['build','deploy','dev','preview','export','import'].includes(name)?['--platform']:[]), ...(['install','setup','dev','preview','build','verify','deploy','export','import'].includes(name)?['--no-queue']:[])], effects }]));
+export const aliases = Object.fromEntries([...Object.keys(verbs).filter(v => v !== 'install'), 'release', 'deps', 'rer'].map(name => [name, name === 'deps' ? 'install' : name === 'rer' ? null : name]));
+export const releaseFlags = ['--repo', '--project', '--repository', '--output', '--ref', '--dry-run', '--tag', '--clean-history', '--onto', '--env-file', '--no-queue'];
+export const requiredHooks = ['preview', 'dependencies', 'build', 'migrate', 'start', 'health', 'owner', 'signIn', 'verify', 'deploy', 'portability', 'state', 'settings', 'input'];

package/cli/dependencies.mjs

@@ -0,0 +1,45 @@
+import {linkApproval,approvalPath} from './dependency-approval.mjs';
+import { unlink } from 'node:fs/promises';
+import { missing } from './errors.mjs';
+import { providerMetadata } from '../modules/dependencies/protocol.mjs';
+import { readJson } from '../modules/operator-auth/identity/oidc/network.mjs';
+
+// Only an owner-only, untracked token file is accepted. The token never enters
+// setup answers, generated runtime configuration, logs or an archive.
+export async function linkDependencies({project,input,origin,store,signal,appSetupToken,fetch:fetcher=globalThis.fetch,clock=Date.now}) {
+ const links=[];
+ for(const dependency of project.setupManifest?.dependencies??[]) {
+  const issuer=input?.[dependency.address];
+  if(!issuer) {if(!dependency.optional)throw missing('A required dependency address is missing.');continue;}
+  const tokenPath=approvalPath(project,dependency.interface);
+  if(!tokenPath) {
+   const current=await readJson(fetcher,origin+'/auth/dependencies/status',{timeoutMs:5000}).catch(()=>null);
+   if(current?.links?.some(link=>link.interface===dependency.interface && link.issuer===issuer && link.linked===true))continue;
+  }
+  if(!tokenPath)throw missing('Provider approval is required. Set RER_LINK_TOKEN_FILE to an owner-only, untracked link-token JSON file for this exact origin and callback set.');
+  const {path,value}=await linkApproval({project,dependency,issuer,origin,store,clock});
+  links.push({dependency,issuer,path,value});
+ }
+ // Open every initial app approval before the first provider can claim its owner.
+ // Hosted runtimes accept their private setup token; no local CLI HMAC is sent.
+ if(links.length && appSetupToken) {
+  store.addSecrets?.([appSetupToken]);
+  for(const {dependency,issuer} of links) {
+   try {
+    const response=await fetcher(origin+'/auth/dependencies/setup',{method:'POST',redirect:'manual',signal:signal?AbortSignal.any([signal,AbortSignal.timeout(5000)]):AbortSignal.timeout(5000),headers:{Origin:origin,'Content-Type':'application/json'},body:JSON.stringify({issuer,interface:dependency.interface,token:appSetupToken})});
+    // A claimed app still needs its owner's existing fresh email approval.
+    const accepted=!response.redirected && (response.status===200 || response.status===409);
+    await response.body?.cancel();if(!accepted)throw Error();
+   }catch{throw missing('Application setup approval was refused. Approve the link with fresh app-owner email proof before retrying.');}
+  }
+ }
+ for(const {dependency,issuer,path,value} of links) {
+  const metadata=await providerMetadata(issuer,fetcher,dependency.interface);
+  let result;try {result=await readJson(fetcher,metadata.link.initiate,{timeoutMs:10000},{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({origin,interface:dependency.interface,token:value.token})});}catch{throw missing('Provider link approval was refused or the provider is unavailable.');}
+  if(result.linked!==true)throw missing('Provider approval did not complete linking.');
+  const status=await readJson(fetcher,origin+'/auth/dependencies/status',{timeoutMs:5000});
+  if(!status.links?.some(link=>link.interface===dependency.interface && link.issuer===issuer && link.linked===true))throw missing('The application has not accepted the provider link.');
+  await unlink(path);
+  store.report('Dependency linked; its one-time approval token was deleted.');
+ }
+}

package/cli/dependency-approval.mjs

@@ -0,0 +1,33 @@
+import {readFile} from 'node:fs/promises';
+import {execFileSync} from 'node:child_process';
+import {relative,resolve} from 'node:path';
+import {contained} from './project.mjs';
+import {invalid,missing} from './errors.mjs';
+import {CALLBACK} from '../modules/dependencies/protocol.mjs';
+export function approvalPath(project,contract) {
+ const single=process.env.RER_LINK_TOKEN_FILE,mapping=process.env.RER_LINK_TOKEN_FILES;
+ if(single && mapping)throw invalid('Choose one link approval input form.');
+ if(!mapping)return single;
+ let files;try{files=JSON.parse(mapping);}catch{throw invalid('RER_LINK_TOKEN_FILES must be a JSON map of interfaces to private file paths.');}
+ const declared=new Set((project.setupManifest?.dependencies??[]).map(d=>d.interface));
+ if(!files || typeof files!=='object' || Array.isArray(files) || Object.entries(files).some(([key,value])=>!declared.has(key)||typeof value!=='string'||!value))throw invalid('Link approval files must name declared interfaces and private file paths.');
+ const paths=Object.values(files).map(path=>resolve(project.root,path));
+ if(new Set(paths).size!==paths.length)throw invalid('Each interface requires a distinct approval file.');
+ return files[contract];
+}
+export async function linkApproval({project,dependency,issuer,origin,store,clock=Date.now}) {
+ const tokenPath=approvalPath(project,dependency.interface);
+ if(!tokenPath)throw missing('Provider approval is required. Supply RER_LINK_TOKEN_FILE.');
+  const path=await contained(project.root,tokenPath,{privateFile:true});
+  let tracked;
+  try{tracked=execFileSync('git',['ls-files','--error-unmatch','--',relative(project.root,path)],{cwd:project.root,stdio:['ignore','pipe','ignore']}).length>0;}catch(e){if(e.status!==1)throw invalid('Link token provenance could not be verified in this checkout.');}
+  if(tracked)throw invalid('A tracked link token is refused. Create a fresh token in an untracked private file.');
+  let value;try{value=JSON.parse(await readFile(path,'utf8'));}catch{throw invalid('Link-token file is invalid.');}
+  if(typeof value.token==='string')store?.addSecrets?.([value.token]);
+  const callbacks=[origin+CALLBACK,...dependency.paths.map(p=>origin+p)].sort();
+  if(typeof value.token!=='string' || !value.token || value.origin!==origin || value.issuer!==issuer || value.interface!==dependency.interface ||
+   !Array.isArray(value.callbacks) || JSON.stringify([...value.callbacks].sort())!==JSON.stringify(callbacks) ||
+   !Number.isSafeInteger(value.issuedAt) || !Number.isSafeInteger(value.expiresAt) || value.issuedAt>clock() || value.expiresAt<=clock() || value.expiresAt-value.issuedAt>3600000)
+   throw missing('Link approval must name this exact origin, interface and callback set, be unused, and expire within one hour.');
+ return {path,value};
+}

package/cli/dependency-doctor.mjs

@@ -0,0 +1,34 @@
+import {providerMetadata} from '../modules/dependencies/protocol.mjs';
+import {readdir,lstat} from 'node:fs/promises';
+import {join} from 'node:path';
+// Canonical local D1, read-only. Diagnostics contain no key, token or metadata body.
+export async function localDependencyLinks(root) {
+ let directory=root;
+ for(const part of ['.wrangler','state','v3','d1','miniflare-D1DatabaseObject']) {
+  directory=join(directory,part);const info=await lstat(directory).catch(()=>null);
+  if(!info)return [];if(info.isSymbolicLink() || !info.isDirectory())return [{ok:false,status:'unsafe_state'}];
+ }
+ const {DatabaseSync}=await import('node:sqlite');
+ const found=[];
+ for(const file of await readdir(directory,{withFileTypes:true})) {
+  if(!file.isFile() || !file.name.endsWith('.sqlite'))continue;
+  const db=new DatabaseSync(join(directory,file.name),{readOnly:true});
+  try {
+   if(!db.prepare("SELECT 1 FROM sqlite_master WHERE name='rer_dependency_link'").get())continue;
+   for(const row of db.prepare('SELECT interface,issuer,needs_relink FROM rer_dependency_link').all()) {
+    found.push(row);
+   }
+  }finally{db.close();}
+ }
+ return found;
+}
+
+export async function dependencyDoctor(root,{fetch:fetcher=globalThis.fetch}={}) {
+ const links=await localDependencyLinks(root),result=[];
+ for(const row of links) {
+  let status=row.needs_relink?'needs_relink':row.status??'linked';
+  if(status==='linked')try{await providerMetadata(row.issuer,fetcher,row.interface);}catch{status='dangling_provider';}
+  result.push({interface:row.interface,ok:status==='linked',status});
+ }
+ return result;
+}

package/cli/dependency-input.mjs

@@ -0,0 +1,43 @@
+import {linkApproval,approvalPath} from './dependency-approval.mjs';
+import { localDependencyLinks } from './dependency-doctor.mjs';
+import { readJson } from '../modules/operator-auth/identity/oidc/network.mjs';
+import { originOf } from '../modules/dependencies/protocol.mjs';
+import { invalid, missing } from './errors.mjs';
+import { shared } from './shared.mjs';
+
+// Read the selected graph before setup writes anything. Optional selected edges
+// participate just like required edges; disconnected declarations do not.
+export async function dependencyInputs({project,input,origin,fetch:fetcher=globalThis.fetch}) {
+ const declarations=project.setupManifest?.dependencies??[],selected=declarations.filter(d=>input[d.address]);
+ if(declarations.some(d=>!d.optional&&!input[d.address]))throw missing('A required dependency address is missing.');
+ if(!selected.length)return;
+ const existing=await localDependencyLinks(project.root);
+ const pending=selected.filter(d=>approvalPath(project,d.interface) || !existing.some(link=>link.interface===d.interface && link.issuer===input[d.address] && !link.needs_relink));
+ if(!pending.length)return;
+ const nodes=new Map([[origin,[...new Set(selected.map(d=>input[d.address]))]]]),documents=new Map();
+ const queue=selected.map(d=>({origin:input[d.address],interface:d.interface}));
+ while(queue.length) {
+  const item=queue.shift();
+  try{originOf(item.origin);}catch{throw invalid('A selected dependency must be an exact HTTPS origin.');}
+  if(item.origin===origin)throw invalid('Selected dependencies contain a cycle.');
+  let doc=documents.get(item.origin);
+  if(!doc) {
+   if(nodes.size>100)throw invalid('The selected dependency graph is too large.');
+   try{doc=await readJson(fetcher,item.origin+'/.well-known/rer-dependencies',{timeoutMs:5000});}catch{throw missing('A selected provider dependency document is unavailable.');}
+   if(doc.origin!==item.origin||doc.version!==1||!Array.isArray(doc.provides)||new Set(doc.provides).size!==doc.provides.length||doc.provides.some(i=>typeof i!=='string'||!/^[a-z][a-z0-9-]*@[1-9][0-9]*$/.test(i))||!Array.isArray(doc.dependencies))throw invalid('A selected provider dependency document is invalid.');
+   documents.set(item.origin,doc);
+   const edges=[],interfaces=new Set();
+   for(const edge of doc.dependencies) {
+    if(!edge || typeof edge.interface!=='string'||!/^[a-z][a-z0-9-]*@[1-9][0-9]*$/.test(edge.interface)||interfaces.has(edge.interface)||typeof edge.optional!=='boolean'||edge.cardinality!==1)throw invalid('A selected provider dependency declaration is invalid.');
+    interfaces.add(edge.interface);
+    if(!edge.provider){if(!edge.optional)throw missing('A selected provider has an unlinked required dependency.');continue;}
+    edges.push(edge.provider);queue.push({origin:edge.provider,interface:edge.interface});
+   }
+   nodes.set(item.origin,[...new Set(edges)]);
+  }
+  if(!doc.provides.includes(item.interface))throw invalid('The selected provider does not provide the declared interface.');
+ }
+ const {validateDependencyGraph}=await shared('schema/dependencies.mjs');
+ try{validateDependencyGraph([...nodes].map(([id,dependencies])=>({id,dependencies})));}catch{throw invalid('Selected dependencies contain a cycle or invalid reference.');}
+ for(const dependency of pending)await linkApproval({project,dependency,issuer:input[dependency.address],origin});
+}

package/cli/deploy-config.mjs

@@ -0,0 +1,118 @@
+import { readFile } from 'node:fs/promises';
+import { contained } from './project.mjs';
+import { parseJsonc } from './jsonc.mjs';
+
+// Where a seed's real Worker configuration lives: the path devIdentity.deployConfig
+// names, else wrangler.jsonc, wrangler.json and wrangler.toml, then a deploy
+// template such as deploy/wrangler.template.toml. A file the adapter lists in
+// generatedOutputs holds whichever configuration was built last, so it is never a
+// source. `rer check` (the deployed main) and `rer dev`/`rer preview` (the Cron
+// Triggers) read these same files.
+const deployConfigs = ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml'], deployTemplates = ['deploy/wrangler.template.toml', 'deploy/wrangler.template.jsonc', 'deploy/wrangler.template.json', 'wrangler.template.toml', 'wrangler.template.jsonc', 'wrangler.template.json'];
+
+export function deployConfigPaths(adapter) {
+ const declared = adapter?.devIdentity?.deployConfig, generated = new Set((adapter?.generatedOutputs ?? []).map(path => path.replace(/^\.\//, '')));
+ return typeof declared === 'string' ? [declared] : [...deployConfigs.filter(path => !generated.has(path)), ...deployTemplates];
+}
+
+export async function readProjectText(root, path) {
+ try { return await readFile(await contained(root, path), 'utf8'); } catch { return null; }
+}
+
+// Top-level `main = "..."` only: a table header ends the top level.
+export function tomlMain(source) {
+ for (const line of source.split('\n')) {
+  if (/^\s*\[/.test(line)) return undefined;
+  const match = /^\s*main\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(line);
+  if (match) return match[1] ?? match[2];
+ }
+}
+export function jsoncMain(source) {
+ try { return JSON.parse(source.replace(/\/\*[\s\S]*?\*\/|^\s*\/\/.*$/gm, '')).main; } catch { return undefined; }
+}
+
+// The deployed Worker entry (`main`) from the first of those files that exists.
+export async function deployedMain(root, adapter) {
+ for (const path of deployConfigPaths(adapter)) {
+  const source = await readProjectText(root, path);
+  if (source === null) continue;
+  return (/\.toml$/.test(path) ? tomlMain(source) : jsoncMain(source))?.replace(/^\.\//, '');
+ }
+}
+
+// Statements of a TOML file with comments removed: one line, or several while a
+// value's bracket is still open. Strings are respected.
+function tomlStatements(source) {
+ const statements = [];
+ let current = '', depth = 0, quote = '';
+ for (let i = 0; i < source.length; i++) {
+  const char = source[i];
+  if (quote) {
+   current += char;
+   if (char === '\\' && quote === '"') current += source[++i] ?? '';
+   else if (char === quote) quote = '';
+  } else if (char === '"' || char === "'") { quote = char; current += char; }
+  else if (char === '#') { while (i + 1 < source.length && source[i + 1] !== '\n') i++; }
+  else if (char === '\n') {
+   if (depth > 0) current += ' ';
+   else { statements.push(current); current = ''; }
+  } else {
+   if (current.includes('=')) { if (char === '[' || char === '{') depth++; else if (char === ']' || char === '}') depth--; }
+   current += char;
+  }
+ }
+ statements.push(current);
+ return statements.map(text => text.trim()).filter(Boolean);
+}
+
+function tomlStrings(text, path) {
+ const list = /^\[([\s\S]*)\]$/.exec(text.trim());
+ if (!list) throw new Error(`${path} triggers.crons must be a list of cron expressions.`);
+ const body = list[1], values = [], pattern = /\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\s*(?:,|$)/y;
+ while (pattern.lastIndex < body.length && body.slice(pattern.lastIndex).trim()) {
+  const match = pattern.exec(body);
+  if (!match) throw new Error(`${path} triggers.crons must be a list of cron expressions.`);
+  values.push(match[1] === undefined ? match[2] : JSON.parse(`"${match[1]}"`));
+ }
+ return values;
+}
+
+// The top-level `triggers.crons` of a wrangler.toml (the [triggers] table, a
+// dotted `triggers.crons` key, or an inline `triggers = { crons = [...] }`);
+// undefined when the file declares none. Environment tables are not read.
+export function tomlCrons(source, path = 'wrangler.toml') {
+ let table = '';
+ for (const statement of tomlStatements(source)) {
+  const header = /^\[\[?\s*([^\]]+?)\s*\]\]?$/.exec(statement);
+  if (header) { table = header[1].replace(/\s+/g, ''); continue; }
+  const pair = /^([A-Za-z0-9_.\-"' ]+?)\s*=\s*([\s\S]*)$/.exec(statement);
+  if (!pair) continue;
+  const key = (table ? `${table}.` : '') + pair[1].replace(/\s+/g, '');
+  if (key === 'triggers.crons') return tomlStrings(pair[2], path);
+  if (key === 'triggers') {
+   const inline = /crons\s*=\s*(\[[\s\S]*?\])/.exec(pair[2]);
+   if (inline) return tomlStrings(inline[1], path);
+  }
+ }
+}
+
+function jsoncCrons(source, path) {
+ let config;
+ try { config = parseJsonc(source); } catch (error) { throw new Error(`${path}: ${error.message}`, { cause: error }); }
+ const crons = config.triggers?.crons;
+ if (crons === undefined) return undefined;
+ if (!Array.isArray(crons) || crons.some(cron => typeof cron !== 'string')) throw new Error(`${path} triggers.crons must be a list of cron expressions.`);
+ return crons;
+}
+
+// Every file of the discovery that declares triggers.crons, as { path, crons }.
+export async function declaredCronSources(root, adapter) {
+ const found = [];
+ for (const path of deployConfigPaths(adapter)) {
+  let source;
+  try { source = await readFile(await contained(root, path, { optional: true }), 'utf8'); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+  const crons = /\.toml$/.test(path) ? tomlCrons(source, path) : jsoncCrons(source, path);
+  if (crons !== undefined) found.push({ path, crons });
+ }
+ return found;
+}