@runeditrun/rer 0.2.1 → 0.2.4

package/cli/managed-server.mjs

@@ -1,6 +1,7 @@
 import { prepareLiveModels } from './ai-local.mjs';
 import {fileURLToPath} from 'node:url';
 import {join} from 'node:path';
+import {rm} from 'node:fs/promises';
 import { serverRegistry } from './server-registry.mjs';
 import { activityClock } from './server-activity.mjs';
 import { runtimeFrontDoor } from './runtime-front-door.mjs';
@@ -13,6 +14,7 @@ import { tools } from './inspect.mjs';
 import { invalid,missing,refuse,RerError,lifecycleError } from './errors.mjs';
 import { processInfo } from '../modules/job-queue/processes.mjs';
 import { declaredCrons,runScheduled } from './scheduled.mjs';
+import { demoAdopted,demoGuarded,demoState } from './demo.mjs';
 import { readDevKey,requireDevKey,refuseManagedInstallation,resolvePersona,openUrl,DEV_KEY_HEADER } from './dev-identity.mjs';
 import { announceDoorRoute,claimSavedName,moveCheckout,routeRunning,verifyDoorFor } from './door-mode.mjs';
 
@@ -22,9 +24,10 @@ import { announceDoorRoute,claimSavedName,moveCheckout,routeRunning,verifyDoorFo
 // serves no outbox (a seed's preview without one) is not pointed at it.
 // A seed that declares a run site also gets RER_SITE: its static run site
 // (homepage, /run, docs) served locally on its own port, after the ready lines.
-export function ready(out,url,dev,json=false,outbox=true,siteUrl){
+// A demo adds RER_DEMO_ENDS_ON_STOP: its own data folder, deleted when it stops.
+export function ready(out,url,dev,json=false,outbox=true,siteUrl,demo){
  const signInUrl=url+'/__dev/outbox',open=dev&&(dev.identity||outbox);
- if(json){out.event('ready',{url,...(outbox?{signInUrl}:{}),...(dev?{signedInAs:dev.signedInAs??null,...(open?{openUrl:dev.openUrl}:{})}:{}),...(siteUrl?{siteUrl}:{})});return;}
+ if(json){out.event('ready',{url,...(outbox?{signInUrl}:{}),...(dev?{signedInAs:dev.signedInAs??null,...(open?{openUrl:dev.openUrl}:{})}:{}),...(siteUrl?{siteUrl}:{}),...(demo?{demo}:{})});return;}
  out.human(`RER_READY ${url}`);
  if(dev?.identity){if(dev.signedInAs)out.human(`RER_SIGNED_IN ${dev.signedInAs}`);else if(dev.ownerLeft)out.human('No active owner remains in this app, so rer dev cannot sign in as one. Use rer dev --login with another operator, or rer reset --yes and rer setup for a new owner.');out.human(`RER_OPEN ${dev.openUrl}`);out.human('Open that link on this computer. Its fragment holds this checkout\'s dev key, which the page keeps only as a cookie; never share the link.');}
  else if(outbox){
@@ -33,10 +36,13 @@ export function ready(out,url,dev,json=false,outbox=true,siteUrl){
   out.human(`Open ${dev?'the last link on this computer (it carries the dev key; never share it)':'the outbox'}, choose the newest sign-in message and follow its link. No email was sent.`);
  }
  if(siteUrl)out.human(`RER_SITE ${siteUrl}`);
+ if(demo){out.human(`RER_DEMO_ENDS_ON_STOP ${demo.state}`);out.human(`This demo runs on its own data in that folder, which is deleted when it stops: rer demo --stop, Ctrl-C, or at its end (${demo.ends.slice(11,16)}). Nothing it does is sent; this checkout's own data is untouched.`);}
 }
 export async function managedServer(project,options,out,{clock={}}={}){
  const registry=await serverRegistry(project.root),controller=new AbortController();
- let store,operation,proxy,activity,app,termination,reason,cleanupPromise,finished,selected,cleaned,site;
+ // A demo registers as its own mode: `rer dev --stop` never stops it by accident.
+ const mode=options.demo?'demo':options.verb;
+ let store,operation,proxy,activity,app,termination,reason,cleanupPromise,finished,selected,cleaned,site,demo,demoEnd;
  const scheduling=new AbortController();
  let activityWrites=Promise.resolve(),pendingActivity,activityWriting=false,infrastructureFailure;
  function recordActivity(fields){
@@ -45,27 +51,27 @@ export async function managedServer(project,options,out,{clock={}}={}){
  }
  const stopped=new Promise(resolve=>{finished=resolve;});
  const cleanupDone=new Promise(resolve=>{cleaned=resolve;});
- const cleanup=()=>cleanupPromise??=(async()=>{scheduling.abort();activity?.close();await site?.close();await store?.closeCommands();await proxy?.close();await operation?.release();})();
+ const cleanup=()=>cleanupPromise??=(async()=>{scheduling.abort();clearTimeout(demoEnd);activity?.close();await site?.close();await store?.closeCommands();if(demo)await rm(demo.state,{recursive:true,force:true});await proxy?.close();await operation?.release();})();
  const stop=async why=>{reason??=why;controller.abort();finished();await cleanupDone;return {};};
  const handlers=new Map(['SIGINT','SIGTERM'].map(name=>[name,()=>{termination=name;void stop(name);} ]));
  for(const [name,handler]of handlers)process.on(name,handler);
  try{
-  if(options.stop){await registry.stop(options.verb,options);return {};}
+  if(options.stop){await registry.stop(mode,options);return {};}
   controller.signal.throwIfAborted();
   if(options.door||options.direct)await moveCheckout(project,options,out,registry);
   const devIdentity=project.adapter.devIdentity;
   if(options.as!==undefined&&!(devIdentity&&options.verb==='dev'))throw invalid('--as needs a seed that declares devIdentity.');
   let devKey=devIdentity?await readDevKey(project.root):null;
-  let current=await registry.existing(options.verb,options);
+  let current=await registry.existing(mode,options);
   if(!current){
-   const reservation=await registry.reserve(options.verb,options);
+   const reservation=await registry.reserve(mode,options);
    current=reservation.existing;
   }
   if(current){
    // Resolve a competing reservation through the same explicit-option check.
-   current=await registry.existing(options.verb,options);
+   current=await registry.existing(mode,options);
    const running=await registry.waitReady(current,controller.signal);
-   await registry.existing(options.verb,options);
+   await registry.existing(mode,options);
    if(options.verb==='dev' && (running.models??'fake')!==(options.models??'fake'))throw refuse('Stop the running dev server before changing --models mode.');
    if(options.modelsService)throw refuse('Stop the running dev server before saving live-dev credentials.');
    if(options.verb==='dev'&&Boolean(running.login)!==Boolean(options.login))throw refuse(`The running dev server ${running.login?'uses':'does not use'} --login. Stop it with rer dev --stop to change sign-in mode.`);
@@ -79,10 +85,10 @@ export async function managedServer(project,options,out,{clock={}}={}){
    // A key is sent (or printed) for a door origin only once the door proves it is ours.
    if(devIdentity)await verifyDoorFor(running.url);
    const dev=devIdentity&&await devReady(running.url,devKey,options,controller.signal);
-   await emitReady(out,options,project.root,running.url,dev,true,running.siteUrl);return {reused:true};
+   await emitReady(out,options,project.root,running.url,dev,true,running.siteUrl,running.demo);return {reused:true};
   }
   await registry.serve(async action=>{
-   if(action==='status')return {...activity?.snapshot(),url:selected?.url,probe:proxy?.probe,siteUrl:site?.url};
+   if(action==='status')return {...activity?.snapshot(),url:selected?.url,probe:proxy?.probe,siteUrl:site?.url,demo};
    if(action==='stop')return stop('explicit stop');
    throw Error('Unknown management operation');
   });
@@ -99,10 +105,11 @@ export async function managedServer(project,options,out,{clock={}}={}){
   if(!selected.vars[keys.email])throw missing('Private owner settings are missing. Run rer setup first.');
   if(devIdentity&&!devKey)devKey=await requireDevKey(project.root);
   if(devIdentity&&options.verb==='dev'&&!options.login)refuseManagedInstallation(selected.vars,process.env);
-  if(project.adapter.localPrerequisites&&!await project.adapter.localPrerequisites({root:project.root,vars:selected.vars,email:selected.vars[keys.email]}))throw missing('Local migrations, owner or local authentication/mail settings are missing. Run rer setup first.');
+  if(project.adapter.localPrerequisites&&!await project.adapter.localPrerequisites({root:project.root,vars:selected.vars,email:selected.vars[keys.email],demo:Boolean(options.demo)}))throw missing('Local migrations, owner or local authentication/mail settings are missing. Run rer setup first.');
   await registry.update({url:selected.url,host:selected.host,port:selected.port,login:Boolean(options.login),models:options.models??'fake'});
   const {privateDirectory}=await shared('private-files.mjs');
-  await privateDirectory(project.root,['.wrangler','state']);
+  if(options.demo){await demoAdopted(project.root);demo=await demoState(project.root,options.idleTimeout);}
+  else await privateDirectory(project.root,['.wrangler','state']);
   const directory=await privateDirectory(project.root,['.seed','installer',...(process.env.RER_ONBOARDING_PROCESS_OWNER?[`commands-${process.pid}`]:[])]);
   const {createCommands}=await shared('commands.mjs');const state={logs:[]};
   store=await createCommands(directory,state,{terminal:text=>out.progress(text),onWaiting:options.json?details=>out.event('waiting',details):undefined,custodyToken:registry.custodyToken(),queue:{verb:options.verb,originalCI:process.env.CI==='true'}});
@@ -110,11 +117,12 @@ export async function managedServer(project,options,out,{clock={}}={}){
   store.setupManifest=seed?.manifest;if(devKey)store.addSecrets([devKey]);
   await tools(project.root,store,controller.signal);
   activity=activityClock({...clock,seconds:options.idleTimeout,onIdle:()=>void stop('idle timeout'),onChange:recordActivity});
+  if(demo)demoEnd=setTimeout(()=>void stop('demo ended'),Math.min(Date.parse(demo.ends)-Date.now(),2**31-1));
   const crons=project.adapter.scheduled!==false?await declaredCrons(project.root,project.adapter).catch(error=>{throw refuse(`The declared scheduled triggers cannot run locally: ${error.message}`);}):[];
   proxy=await runtimeFrontDoor({host:selected.host,port:selected.port,activity,door:selected.door,devKey:devKey??undefined,origin:selected.url});const internal=proxy.runtimePort;
   if(selected.door)await announceDoorRoute(selected,proxy,registry);
   const modelsLive = options.verb==='dev' ? await prepareLiveModels(project.root,options,store,controller.signal) : undefined;
-  const adapterOptions={modelsLive,selectedOrigin:selected.url,operationToken:operation.token,privateSettings:project.adapter.settings,runtimePort:internal,devKey:devKey??undefined,devLogin:Boolean(options.login),scheduled:crons.length>0};
+  const adapterOptions={modelsLive,demo,selectedOrigin:selected.url,operationToken:operation.token,privateSettings:project.adapter.settings,runtimePort:internal,devKey:devKey??undefined,devLogin:Boolean(options.login),scheduled:crons.length>0};
   const input={[keys.email]:selected.vars[keys.email]};
   if(options.verb==='preview')await productionBuild(project,()=>store.run('Building fixed production output',process.execPath,[fileURLToPath(new URL('../bin/rer.mjs',import.meta.url)),'build','--cwd',project.root,'--json'],{cwd:project.root,phase:'build',signal:controller.signal,env:{...process.env,RER_LOCAL_OPERATION:operation.token},afterCommand:()=>recoverInterrupted(project.root,operation)}),text=>store.report(text));
   await serverResources(project.root);
@@ -127,6 +135,7 @@ export async function managedServer(project,options,out,{clock={}}={}){
   },controller.signal,{...adapterOptions,verb:options.verb,dev:project.adapter.dev,preview:project.adapter.preview});
   // A key is sent (or printed) for a door origin only once the door proves it is ours.
   if(devKey)await verifyDoorFor(selected.url);
+  if(demo)await demoGuarded(selected.url,demo.state,controller.signal);
   const dev=devIdentity&&await devReady(selected.url,devKey,options,controller.signal);
   const outbox=await outboxServed(selected.url,devKey,controller.signal);
   if(options.verb==='dev'&&project.adapter.site){
@@ -140,7 +149,7 @@ export async function managedServer(project,options,out,{clock={}}={}){
     if(options.json)out.event('warning',{code:error.code,message});else out.progress(`Warning: ${message}\n`);
    }
   }
-  activity.ready();await emitReady(out,options,project.root,selected.url,dev,outbox,site?.url);
+  activity.ready();await emitReady(out,options,project.root,selected.url,dev,outbox,site?.url,demo);
   if(crons.length){
    out.progress(`Running ${crons.length===1?'the scheduled trigger':'the scheduled triggers'} locally: ${crons.join(' | ')}\n`);
    void runScheduled({crons,url:`http://127.0.0.1:${internal}`,path:options.verb==='preview'?'/cdn-cgi/local/scheduled':undefined,signal:scheduling.signal,report:run=>reportScheduled(out,options,run)});
@@ -150,7 +159,7 @@ export async function managedServer(project,options,out,{clock={}}={}){
   if(infrastructureFailure)throw new RerError('server_bookkeeping_failed','Server bookkeeping failed; owned serving was stopped.',1);
   if(result?.code)throw new RerError('app_exited','The application stopped unexpectedly.',result.code);
   out.progress(`Server stopped: ${reason}.\n`);return {};
- }catch(error){if(termination)throw new RerError('cancelled',`Stopped by ${termination} after owned children were stopped.`,termination==='SIGINT'?130:143);if(['idle timeout','explicit stop'].includes(reason))return {};throw await lifecycleError(error,store);}finally{await cleanup();cleaned();while(activityWriting)await activityWrites;await registry.close();for(const [name,handler]of handlers)process.off(name,handler);}
+ }catch(error){if(termination)throw new RerError('cancelled',`Stopped by ${termination} after owned children were stopped.`,termination==='SIGINT'?130:143);if(['idle timeout','explicit stop','demo ended'].includes(reason))return {};throw await lifecycleError(error,store);}finally{await cleanup();cleaned();while(activityWriting)await activityWrites;await registry.close();for(const [name,handler]of handlers)process.off(name,handler);}
 }
 function reportScheduled(out,options,run){
  const error=options.verb==='preview'&&run.status===404 ? 'The preview target does not expose /cdn-cgi/local/scheduled. Forward the adapter context scheduled flag to previewTarget, or set RER_RUNTIME_TRIGGERS=1 in a custom target using the shared production runtime. For another runtime, expose that internal trigger endpoint or declare scheduled:false.' : run.error;
@@ -167,12 +176,12 @@ async function outboxServed(url,devKey,signal){
 // dev also keeps its RER_OPEN link in owner-only .rer/local/open-url (0600),
 // which reset removes with the rest of .rer/local, for a person or agent that
 // did not keep the terminal output.
-async function emitReady(out,options,root,url,dev,outbox,siteUrl){
+async function emitReady(out,options,root,url,dev,outbox,siteUrl,demo){
  if(options.verb==='dev'&&dev?.openUrl){
   const {privateDirectory,writePrivateFile}=await shared('private-files.mjs');
   await writePrivateFile(join(await privateDirectory(root,['.rer','local']),'open-url'),dev.openUrl+'\n');
  }
- ready(out,url,dev||undefined,options.json,outbox,siteUrl);
+ ready(out,url,dev||undefined,options.json,outbox,siteUrl,demo);
 }
 async function devReady(url,key,options,signal){
  if(options.verb==='preview')return {openUrl:openUrl(url,key,{path:'/__dev/key',next:'/__dev/outbox'})};

package/cli/parse.mjs

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { commonFlags, serverDefaults, verbs } from './contract.mjs';
 import { invalid, refuse } from './errors.mjs';
 import { isLoopbackHost } from '../modules/operator-auth/loopback.mjs';
-const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--door', '--direct', '--site']);
+const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--door', '--direct', '--site', '--remove', '--demo']);
 export const mailbox = value => typeof value === 'string' && value.length <= 254 && /^[a-zA-Z0-9.!+_%\-]+@[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+$/.test(value);
 // A loopback host: the shared predicate (including `*.localhost` door names),
 // plus `::1` as --host and a bracket-stripped hostname spell it.
@@ -17,6 +17,8 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
  if (!verb || verb === '--help') return { help: true };
  if (verb === 'release') return { verb, releaseArgs: args };
  if (verb === 'archive') return { verb, archiveArgs: args };
+ // rer demo is rer dev --demo.
+ if (verb === 'demo' && !independent) return parse(['dev', '--demo', ...args], cwd, { independent, deferTail });
  // Independent projects own verb names; only the common wrapper flags apply
  // to unknown names. Profile resolution rejects undeclared commands later.
  if (!/^[a-z][a-z0-9-]*$/.test(verb)) throw invalid('Unknown rer command. Run rer --help.');
@@ -53,8 +55,10 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
  if(options.models!==undefined && !['fake','live'].includes(options.models))throw invalid('--models takes fake or live.');
  if(options.modelsService!==undefined && options.models!=='live')throw invalid('--models-service requires --models live.');
  if(options.as!==undefined && (options.login || !/^[a-z][a-z0-9-]{0,39}$/.test(options.as)))throw invalid(options.login?'--as and --login cannot be combined.':'--as takes a persona name such as owner, signed-out or admin.');
+ if(options.demo&&['--door','--direct','--as','--login','--models','--models-service'].some(flag=>options.supplied.has(flag)))throw invalid('A demo opens signed in as the owner on its own data: --demo takes only --port, --host, --idle-timeout, --stop, --detach and --foreground.');
  if(['dev','preview'].includes(verb) && !options.stop){
-  const value=options.idleTimeout??process.env.RER_SERVER_IDLE_SECONDS??String(serverDefaults.idleSeconds);
+  // A demo ends one hour after it starts unless --idle-timeout says otherwise.
+  const value=options.idleTimeout??(options.demo?'3600':process.env.RER_SERVER_IDLE_SECONDS??String(serverDefaults.idleSeconds));
   if(!/^[1-9][0-9]*$/.test(value)||!Number.isSafeInteger(Number(value)))throw invalid('Idle timeout must be positive integer seconds.');
   options.idleTimeout=Number(value);
  }
@@ -72,6 +76,9 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
  if (options.target !== undefined && !['local', 'remote'].includes(options.target)) throw invalid('Target must be local or remote.');
  if (options.profile !== undefined && options.profile !== 'first-party') throw invalid('The supported explicit profile is first-party.');
  if (options.environment !== undefined && !/^[a-z][a-z0-9-]{0,39}$/.test(options.environment)) throw invalid('Provide a valid deployment environment name.');
+ for (const key of ['setSecret', 'unsetSecret']) if (options[key] !== undefined && !/^[A-Z][A-Z0-9_]{0,63}$/.test(options[key])) throw invalid('Name a declared secret binding, such as SESSION_SECRET.');
+ if(verb==='deploy'&&options.demo&&(options.site||['platform','image','bindAddress','httpPort','httpsPort','envFile','host','remove','setSecret','unsetSecret'].some(key=>options[key]!==undefined)))throw invalid('--demo takes only --environment and --dry-run: the hosted demo is its own Worker on demo.<domain>.');
+ if ((options.remove || options.setSecret || options.unsetSecret) && options.site) throw invalid('--remove, --set-secret and --unset-secret act on the application Worker, not the run site.');
  if (options.origin !== undefined) {
   let url; try { url = new URL(options.origin); } catch { throw invalid('Provide a valid credential-free origin.'); }
   if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw invalid('Provide a credential-free HTTP origin without a path.');

package/cli/pnpm-probe.mjs

@@ -0,0 +1,17 @@
+import { missing } from './errors.mjs';
+import { shared } from './shared.mjs';
+
+// A version check owns its descendants just like a lifecycle command. Cleanup
+// starts at leader exit, even when quiet descendants still hold the pipes.
+// The package manager never sees the caller's credentials.
+export async function probePnpm(root, store, signal, env = process.env) {
+ const { dependencyEnvironment } = await shared('dependency-environment.mjs');
+ const probeSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean));
+ const child = store.spawn('Checking pinned pnpm', 'pnpm', ['--version'], { cwd: root, env: dependencyEnvironment(env), signal: probeSignal });
+ let version = '';
+ child.stdout.on('data', chunk => { version = (version + chunk).slice(-1024); });
+ const code = await new Promise(resolve => { child.once('error', () => resolve(null)); child.once('exit', code => resolve(code)); });
+ await store.stop(child);
+ if (probeSignal.aborted || code !== 0) throw missing('The pinned pnpm version probe failed. Select the documented tool.');
+ return version.trim();
+}

package/cli/pnpm-runtime.mjs

@@ -15,11 +15,11 @@ import { shellQuote } from './node-runtime-cache.mjs';
 // rer's own cache (~/.rer/pnpm/pnpm-VERSION). Only rer's own commands for the
 // project put it on their PATH; nothing global changes, and it is used only
 // when the person's PATH has no pnpm of the pinned version.
-export const pnpmCache = () => join(homedir(), '.rer', 'pnpm');
-const directoryOf = version => join(pnpmCache(), `pnpm-${version}`);
-const shim = version => join(directoryOf(version), 'shim');
-const receipt = version => join(directoryOf(version), '.rer-verified.json');
-const entry = version => join(directoryOf(version), 'bin', 'pnpm.cjs');
+export const pnpmCache = (env = process.env) => join(env.HOME || homedir(), '.rer', 'pnpm');
+const directoryOf = (version, env) => join(pnpmCache(env), `pnpm-${version}`);
+const shim = (version, env) => join(directoryOf(version, env), 'shim');
+const receipt = (version, env) => join(directoryOf(version, env), '.rer-verified.json');
+const entry = (version, env) => join(directoryOf(version, env), 'bin', 'pnpm.cjs');
 
 async function digest(path, algorithm, encoding) {
  const hash = createHash(algorithm);
@@ -30,25 +30,25 @@ async function owned(path, directory) {
  const stat = await lstat(path);
  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()) || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o022)) throw Error('Unsafe pnpm cache placement.');
 }
-async function prepareCache() {
- for (const path of [join(homedir(), '.rer'), pnpmCache()]) {
+async function prepareCache(env) {
+ for (const path of [join(env.HOME || homedir(), '.rer'), pnpmCache(env)]) {
   await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
   try { await owned(path, true); } catch { throw missing(`The pnpm cache directory must be an owned, non-linked directory without group/other write access: ${path}. Correct its placement and permissions before retrying.`); }
  }
- return pnpmCache();
+ return pnpmCache(env);
 }
 
 /** The verified cached pnpm's PATH directory, or undefined when none is cached. */
-export async function cachedPnpm(version) {
- try { await lstat(directoryOf(version)); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+export async function cachedPnpm(version, env = process.env) {
+ try { await lstat(directoryOf(version, env)); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
  try {
-  for (const path of [join(homedir(), '.rer'), pnpmCache(), directoryOf(version), shim(version)]) await owned(path, true);
-  for (const path of [receipt(version), entry(version), join(shim(version), 'pnpm')]) await owned(path, false);
-  const record = JSON.parse(await readFile(receipt(version), 'utf8'));
-  if (record.version !== version || !/^sha512-/.test(record.integrity) || record.entrySha256 !== await digest(entry(version), 'sha256', 'hex')) throw Error('pnpm cache integrity mismatch.');
-  return shim(version);
+  for (const path of [join(env.HOME || homedir(), '.rer'), pnpmCache(env), directoryOf(version, env), shim(version, env)]) await owned(path, true);
+  for (const path of [receipt(version, env), entry(version, env), join(shim(version, env), 'pnpm')]) await owned(path, false);
+  const record = JSON.parse(await readFile(receipt(version, env), 'utf8'));
+  if (record.version !== version || !/^sha512-/.test(record.integrity) || record.entrySha256 !== await digest(entry(version, env), 'sha256', 'hex')) throw Error('pnpm cache integrity mismatch.');
+  return shim(version, env);
  } catch {
-  throw missing(`The cached pnpm is unsafe or incomplete. Preserve it for inspection with: mv ${shellQuote(directoryOf(version))} ${shellQuote(directoryOf(version) + '.quarantine-' + Date.now())}. Then rerun the original rer command to fetch a verified release.`);
+  throw missing(`The cached pnpm is unsafe or incomplete. Preserve it for inspection with: mv ${shellQuote(directoryOf(version, env))} ${shellQuote(directoryOf(version, env) + '.quarantine-' + Date.now())}. Then rerun the original rer command to fetch a verified release.`);
  }
 }
 
@@ -69,8 +69,8 @@ function extract(archive, directory, signal) {
 }
 
 /** Fetch, verify and cache pnpm VERSION; returns its PATH directory. `registry` is the npm registry origin. */
-export async function downloadPnpm(version, cancellation, { registry = 'https://registry.npmjs.org' } = {}) {
- const cache = await prepareCache(), temporary = await mkdtemp(join(cache, '.download-'));
+export async function downloadPnpm(version, cancellation, { registry = 'https://registry.npmjs.org', env = process.env } = {}) {
+ const cache = await prepareCache(env), temporary = await mkdtemp(join(cache, '.download-'));
  const signal = AbortSignal.any([cancellation, AbortSignal.timeout(60000)].filter(Boolean));
  try {
   const metadata = join(temporary, 'release.json'), archive = join(temporary, 'pnpm.tgz');
@@ -86,11 +86,11 @@ export async function downloadPnpm(version, cancellation, { registry = 'https://
   if (JSON.parse(await readFile(join(extracted, 'package.json'), 'utf8')).version !== version) throw Error('Verified pnpm release did not name the project pin.');
   await mkdir(join(extracted, 'shim'), { mode: 0o700 });
   // `node` is rer's own: the command puts its Node first on PATH beside this.
-  await writeFile(join(extracted, 'shim', 'pnpm'), `#!/bin/sh\nexec node ${shellQuote(entry(version))} "$@"\n`, { mode: 0o700 });
+  await writeFile(join(extracted, 'shim', 'pnpm'), `#!/bin/sh\nexec node ${shellQuote(entry(version, env))} "$@"\n`, { mode: 0o700 });
   await writeFile(join(extracted, '.rer-verified.json'), JSON.stringify({ version, integrity, entrySha256: await digest(join(extracted, 'bin', 'pnpm.cjs'), 'sha256', 'hex') }) + '\n', { flag: 'wx', mode: 0o600 });
   await chmod(extracted, 0o700);
-  try { await rename(extracted, directoryOf(version)); }
-  catch (error) { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code) || !(await cachedPnpm(version))) throw error; }
-  return shim(version);
+  try { await rename(extracted, directoryOf(version, env)); }
+  catch (error) { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code) || !(await cachedPnpm(version, env))) throw error; }
+  return shim(version, env);
  } finally { await rm(temporary, { recursive: true, force: true }); }
 }

package/cli/portability-policy.mjs

@@ -0,0 +1,55 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { policy as validatePolicy } from '../modules/portability/catalogue.mjs';
+import { PortabilityError } from '../modules/portability/index.mjs';
+
+// Only seed configuration supplies this entry point. Never resolve executable
+// policy from archive metadata, or stringify functions across the process seam.
+export async function policyModuleURL(root, entry) {
+ try {
+  let path;
+  if (entry instanceof URL || (typeof entry === 'string' && entry.startsWith('file:'))) {
+   const url = new URL(entry);
+   if (url.protocol !== 'file:' || url.search || url.hash) throw new Error();
+   path = fileURLToPath(url);
+  } else {
+   if (typeof entry !== 'string' || !entry || isAbsolute(entry) || /^[a-z][a-z\d+.-]*:/i.test(entry)) throw new Error();
+   path = resolve(root, entry);
+  }
+  const base = await realpath(root), actual = await realpath(path), within = relative(base, actual);
+  if (!within || within === '..' || within.startsWith('..' + sep) || isAbsolute(within) || !(await stat(actual)).isFile()) throw new Error();
+  return pathToFileURL(actual).href;
+ } catch { throw new PortabilityError('invalid_policy_module', 409); }
+}
+
+export function serializablePolicy(input) {
+ const seen = new Set();
+ function copy(value) {
+  if (value === null || value === undefined || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) return value;
+  if (typeof value !== 'object' || seen.has(value) || (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))) throw new PortabilityError('policy_module_required', 409);
+  seen.add(value);
+  const result = Array.isArray(value) ? [] : Object.create(null);
+  for (const key of Reflect.ownKeys(value)) {
+   if (Array.isArray(value) && key === 'length') continue;
+   const descriptor = Object.getOwnPropertyDescriptor(value, key);
+   if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor)) throw new PortabilityError('policy_module_required', 409);
+   result[key] = copy(descriptor.value);
+  }
+  seen.delete(value);
+  return result;
+ }
+ const result = copy(input);
+ validatePolicy(result);
+ return result;
+}
+
+export async function loadPolicy(root, policy, policyModule) {
+ if (policyModule === undefined) return serializablePolicy(policy);
+ if (policy !== undefined) throw new PortabilityError('ambiguous_policy', 409);
+ try {
+  const { default: input } = await import(await policyModuleURL(root, policyModule));
+  validatePolicy(input);
+  return input;
+ } catch { throw new PortabilityError('invalid_policy_module', 409); }
+}

package/cli/portability-worker.mjs

@@ -4,27 +4,31 @@ import { readLegacyArchive } from '../modules/portability/format.mjs';
 import { recoverLegacyArchive } from '../modules/portability/legacy-files.mjs';
 import { legacyTargetState, requireLegacyEmpty } from '../modules/portability/legacy-safety.mjs';
 import { migrationReplay } from '../modules/portability/migration-history.mjs';
+import { appliedMigrations as appliedMigrationNames } from '../modules/portability/bridge.mjs';
 import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { createPortability, PortabilityError, readArchive } from '../modules/portability/index.mjs';
 import { parseJsonc } from './jsonc.mjs';
+import { loadPolicy } from './portability-policy.mjs';
 
-// The migrations this installation applied, in Wrangler's applied order, so a
+// The migrations this installation applied, in its ledger's order, so a
 // restore can place an older archive within them.
 async function appliedMigrations(root, db, binding, split) {
  const config = parseJsonc(await readFile(join(root, 'wrangler.jsonc'), 'utf8'));
  const directory = join(root, config.d1_databases.find(entry => entry.binding === binding).migrations_dir ?? 'migrations');
- const names = (await db.prepare('SELECT name FROM d1_migrations ORDER BY id').all()).results.map(row => row.name);
+ const names = await appliedMigrationNames(db) ?? [];
  return Promise.all(names.map(async name => ({ name, statements: split(await readFile(join(directory, name), 'utf8')) })));
 }
 
-async function run(direction, { root, path, journal, binding, buckets, policy, transient, legacyRecovery }) {
+async function run(direction, { root, path, journal, binding, buckets, policy, policyModule, transient, legacyRecovery }) {
  // Validate all inputs before opening bindings or acquiring a restore lock.
  if (direction === 'import') {
   for await (const record of fileRecords(path,legacyRecovery?readLegacyArchive:readArchive)) {}
   if(journal)for await(const record of fileRecords(journal)) {}
  }
+ policy = await loadPolicy(root, policy, policyModule);
+ if (direction === 'policy-preflight') return { checkedPolicy: true };
  const { getPlatformProxy, unstable_splitSqlQuery } = createRequire(join(root, 'package.json'))('wrangler');
 
  // Unlike Wrangler's --persist-to base, the API takes the versioned directory.
@@ -46,7 +50,7 @@ async function run(direction, { root, path, journal, binding, buckets, policy, t
 try { console.log(JSON.stringify({ ok: true, ...await run(process.argv[2], JSON.parse(process.argv[3])) })); }
 catch (error) {
  // Erasure-fence refusals name the fence: an older archive is refused, not a failed transfer.
- const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal'].includes(error.code.split(':')[0]));
+ const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal', 'staged_validation'].includes(error.code.split(':')[0]));
  const exitCode = error.message === 'archive_json' ? 2 : refusal || error.code === 'EEXIST' ? 4 : 1;
  // Report only symbolic codes; native database errors can contain private data.
  const reason = error instanceof PortabilityError ? error.code.split(':')[0] : /^[A-Z_]+$/.test(error.code ?? '') ? error.code : error.message === 'archive_json' ? 'archive_json' : 'native_error';

package/cli/portability.mjs

@@ -5,10 +5,12 @@ import { readArchive, PortabilityError } from '../modules/portability/index.mjs'
 import { readLegacyArchive } from '../modules/portability/format.mjs';
 import { fileRecords } from '../modules/portability/files.mjs';
 import { RerError, refuse } from './errors.mjs';
+import { policyModuleURL, serializablePolicy } from './portability-policy.mjs';
+import { shared } from './shared.mjs';
 
 // Seeds declare their real bindings and data policy. The shared module owns the
 // archive format and atomic restore; the shared runner owns its native children.
-export function localPortability({ database, binding = 'DB', buckets = {}, policy, transient = [] }) {
+export function localPortability({ database, binding = 'DB', buckets = {}, policy, policyModule, transient = [] }) {
  async function run({ root, path, journal, store, signal, operationToken, platform, legacyRecovery }, direction) {
   if (direction === 'export') {
    if (await lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; })) throw refuse('Export requires a new archive path.');
@@ -22,6 +24,7 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
     if(journal)for await(const record of fileRecords(journal)) {}
    }
    catch (error) {
+    if (error.message === 'archive_json') throw new RerError('invalid_archive', 'Restore refused (archive_json): archive JSON is invalid.', 2);
     if (!(error instanceof PortabilityError)) throw error;
     const message = error.code === 'legacy_archive_unverifiable'
      ? 'Restore refused (legacy_archive_unverifiable): version 1 metadata cannot be authenticated. Upgrade the original installation and re-export, or use rer import --legacy-v1 --input FILE --yes --acknowledge-unverified-metadata --output exports/recovered-v2.rer in an empty installation. See modules/portability/README.md#backup-only-v1-recovery.'
@@ -31,13 +34,29 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
    }
   }
   if(legacyRecovery)store.report('Legacy v1 recovery: manifest metadata is unverified. Restored data will be audited and exported to a new v2 backup.');
-  if(platform==='container') return (await import('./container-transfer.mjs')).containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy,transient});
-  const input={ root, path, journal, binding, buckets, policy, transient, legacyRecovery };
+  let declaration;
+  try {
+   if (policyModule !== undefined) {
+    if (policy !== undefined) throw new PortabilityError('ambiguous_policy', 409);
+    if (platform === 'container') throw new PortabilityError('container_policy_module_unsupported', 409);
+    declaration = { policyModule: await policyModuleURL(root, policyModule) };
+   } else declaration = { policy: serializablePolicy(policy) };
+  } catch (error) {
+   if (!(error instanceof PortabilityError)) throw error;
+   throw refuse(`Local portability policy refused (${error.code}). Executable policies require a seed-owned policyModule with a valid default policy export; policyModule requires native local transport.`);
+  }
+  if(platform==='container') return (await import('./container-transfer.mjs')).containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy:declaration.policy,transient});
+  const input={ root, path, journal, binding, buckets, ...declaration, transient, legacyRecovery };
+  // Check the executable policy before migrations; the transfer worker imports
+  // it again in its own process so module closures are retained during restore.
+  if (policyModule !== undefined) await nativeWorker(store,'policy-preflight',input,signal);
   // Do not apply pending product migrations to a populated recovery target.
   // Check real existing bindings first; finalize repeats this under the lock.
   if(legacyRecovery)await nativeWorker(store,'legacy-preflight',input,signal);
+  // Local migrations need no provider account: wrangler runs without credentials.
+  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
   await store.run('Applying local data migrations', 'pnpm', ['exec', 'wrangler', 'd1', 'migrations', 'apply', database, '--local', '--persist-to', '.wrangler/state', '--config', 'wrangler.jsonc'], {
-   cwd: root, signal, env: { ...process.env, RER_LOCAL_OPERATION: operationToken, WRANGLER_SEND_METRICS: 'false' },
+   cwd: root, signal, env: { ...dependencyEnvironment(), RER_LOCAL_OPERATION: operationToken, WRANGLER_SEND_METRICS: 'false' },
   });
   const receipt=await nativeWorker(store,direction,input,signal);
   if(legacyRecovery)receipt.output=relative(root,legacyRecovery.output);
@@ -48,7 +67,7 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
 
 async function nativeWorker(store,direction,input,signal) {
   const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url));
-  const child = store.spawn(`${direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
+  const child = store.spawn(`${direction === 'policy-preflight' ? 'Checking archive policy' : direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
    [worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' } });
   let output = '';
   child.stdout.on('data', chunk => { output += chunk; });

package/cli/project-pnpm.mjs

@@ -0,0 +1,67 @@
+// Resolve the checkout's package manager before its own rer can be loaded.
+// The verified cache is private to rer; the resulting PATH travels to children.
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { delimiter, dirname, join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { cachedPnpm, downloadPnpm } from './pnpm-runtime.mjs';
+import { missing, RerError } from './errors.mjs';
+import { shellQuote } from './node-runtime-cache.mjs';
+import { probePnpm } from './pnpm-probe.mjs';
+import { shared } from './shared.mjs';
+
+export async function projectPnpmPin(root) {
+ let pkg;
+ try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')); } catch {}
+ const pin = /^pnpm@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\+sha\d+\.[0-9a-f]+)?$/.exec(pkg?.packageManager ?? '')?.[1];
+ if (!pin) throw missing('This first-party checkout must declare an exact pnpm version in package.json packageManager. Correct that declaration, then rerun rer.');
+ return pin;
+}
+async function probe(root, env, signal, store) {
+ try { return await probePnpm(root, store, signal, env); }
+ catch (error) { if (signal?.aborted) throw error; return undefined; }
+}
+export async function ensureProjectPnpm(root, options = {}) {
+ if (options.store) return ensure(root, options);
+ // Global bootstrap has no adapter or lifecycle store yet. Give it the same
+ // command custody, with a temporary log and cancellation lasting through the
+ // download, both probes, and cleanup.
+ const cancellation = new AbortController();
+ const signal = AbortSignal.any([options.signal, cancellation.signal].filter(Boolean));
+ let termination, directory, store;
+ const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { termination ??= name; cancellation.abort(name); }]));
+ for (const [name, handler] of handlers) process.on(name, handler);
+ try {
+  // Invalid manifests refuse before acquiring command custody or tools.
+  const pin = await projectPnpmPin(root);
+  directory = await mkdtemp(join(tmpdir(), 'rer-prerequisites-'));
+  const { createCommands } = await shared('commands.mjs');
+  store = await createCommands(directory, { logs: [] }, { terminal: () => {} });
+  store.setCommandSignal(signal);
+  return await ensure(root, { ...options, signal, store }, pin);
+ } finally {
+  try { await store?.closeCommands(); if (directory) await rm(directory, { recursive: true, force: true }); }
+  finally { for (const [name, handler] of handlers) process.removeListener(name, handler); }
+  if (termination) throw new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143);
+ }
+}
+async function ensure(root, { env = process.env, signal, report = () => {}, store }, pin) {
+ pin ??= await projectPnpmPin(root);
+ if (await probe(root, env, signal, store) === pin) return env;
+ let directory = await cachedPnpm(pin, env);
+ if (!directory) {
+  report(`Fetching pnpm ${pin} for this project; rer keeps it in its own cache.`);
+  try { directory = await downloadPnpm(pin, signal, { env }); }
+  catch (error) {
+   if (signal?.aborted || error instanceof RerError) throw error;
+   const prefix = join(env.HOME || homedir(), '.rer', 'pnpm', `manual-${pin}`);
+   throw missing(`pnpm ${pin} could not be fetched (${error.message}). Retry with a working connection, or run in this shell: npm install --prefix ${shellQuote(prefix)} --no-save pnpm@${pin} && export PATH=${shellQuote(join(prefix, 'node_modules/.bin'))}:"$PATH"`);
+  }
+ }
+ // Select the verified pnpm before any tool beside Node. Its shim still finds
+ // this process's Node before the caller's PATH, but cannot be shadowed by a
+ // different pnpm installed in that Node's bin directory.
+ const supplied = { ...env, PATH: [directory, dirname(process.execPath), env.PATH].filter(Boolean).join(delimiter) };
+ if (await probe(root, supplied, signal, store) !== pin) throw missing(`The verified pnpm ${pin} did not report the project version. Run ${shellQuote(join(directory, 'pnpm'))} --version to inspect it, then rerun rer.`);
+ Object.assign(env, supplied);
+ return env;
+}

package/cli/release.mjs

@@ -1,5 +1,40 @@
 // Preserve release's accepted parser, producer, receipt and validation exits.
+const releaseHelp = `Usage: rer release --repo DIR --project PUBLISHER/NAME --repository GITHUB_URL --output NEW_DIR [FLAGS]
+
+Produce local release artifacts after frozen installation, verification and publication checks.
+Without --tag, write a preview. This command never pushes, uploads or deploys.
+
+  --repo DIR             Source Git repository.
+  --project PUBLISHER/NAME
+                         Publishing identity.
+  --repository GITHUB_URL
+                         Credential-free https://github.com/<owner>/<repository> destination.
+  --output NEW_DIR       New output directory outside the source repository.
+  --ref REF              Selected committed source (default: HEAD).
+  --tag [vVERSION]       Prepare source artifacts and create a local annotated tag;
+                         an explicit tag must match the committed release version.
+  --dry-run              Run the real gates and suppress local tag creation.
+  --clean-history        Prepare a parentless public export.
+  --onto GITHUB_URL#BRANCH
+                         Prepare a public child of the destination's current branch;
+                         cannot be combined with --clean-history.
+  --env-file FILE        Credential file for publication inspection.
+  --no-queue             Bypass the job queue only in the original CI environment.
+  --help                 Print this help without performing release work.
+
+Signing and receipt commands:
+  rer release sign --artifact DIR (--key-file FILE | --key-stdin) [--scope test|rer]
+  rer release receipt --artifact DIR --anchors FILE [--environment test] [--after VERSION:SHA256]
+  rer release keygen --scope test|rer --publisher NAMESPACE --github-owner LOGIN --github-owner-id ID --anchor-out FILE
+    [--not-before YYYY-MM-DDTHH:MM:SSZ] [--not-after YYYY-MM-DDTHH:MM:SSZ]
+    [--unsigned-through PROJECT:VERSION ...]
+
+Signing scope defaults to rer; receipt environment defaults to production.
+Key generation requires non-terminal stdout; --key-stdin requires non-terminal stdin.
+`;
+
 export async function dispatchRelease(args) {
+ if (args.length === 1 && args[0] === '--help') { console.log(releaseHelp); return 0; }
  if (['sign', 'receipt', 'keygen'].includes(args[0])) return (await import('../modules/release/signing-cli.mjs')).dispatchSigning(args[0], args.slice(1));
  try {
   const options = {};

package/cli/scheduled.mjs

@@ -1,5 +1,3 @@
-import { declaredCronSources } from './deploy-config.mjs';
-
 // `rer dev` runs the project's declared Cron Triggers (wrangler `triggers.crons`, from wrangler.jsonc, wrangler.toml or a deploy template)
 // on their schedule by calling the local runtime's scheduled test endpoint (the Vite plugin's under dev, Miniflare's own under preview), so
 // alerts, retries and checks behave on the owner's computer as they do deployed.
@@ -40,6 +38,8 @@ export function cronMatches(cron, date) {
 // triggers.crons must declare the same ones: otherwise `rer dev` would run a
 // schedule the deployed Worker does not have.
 export async function declaredCrons(root, adapter) {
+ // Imported here: the container image runs this file's parseCron and cronMatches without the CLI's project modules.
+ const { declaredCronSources } = await import('./deploy-config.mjs');
  const sources = await declaredCronSources(root, adapter);
  for (const { path, crons } of sources) for (const cron of crons) parseCron(cron);
  const [first, ...others] = sources;

package/cli/server-registry.mjs

@@ -1,6 +1,6 @@
 import { createConnection, createServer } from 'node:net';
 import { randomUUID, createHash } from 'node:crypto';
-import { userInfo, tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { chmod, realpath, unlink, lstat, mkdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -80,7 +80,7 @@ function limitMessage(counted,cap,explicit,mode) {
 // the old default of 2 in records written before this rule) never lowers the cap
 // below the current default.
 export const defaultServerLimit=serverDefaults.serverLimit;
-export const serversDirectory=(env=process.env)=>resolve(env.RER_SERVERS_DIR??join(userInfo().homedir,'.rer/servers'));
+export const serversDirectory=(env=process.env)=>resolve(env.RER_SERVERS_DIR??join((env.HOME || homedir()),'.rer/servers'));
 export async function serverRegistry(root,{env=process.env,memory=availableMemory}={}) {
  const floor=memoryFloor(env),explicit=env.RER_SERVER_LIMIT!==undefined,limit=positive(env.RER_SERVER_LIMIT,'RER_SERVER_LIMIT',defaultServerLimit),journey=declaresJourney(env);
  const checkout=await realpath(root), lifetime=await identity();