@runeditrun/rer 0.2.1 → 0.2.4

package/README.md

@@ -22,8 +22,11 @@ refuses archives with absolute paths, `..` entries, links or devices, then runs
 the package's own `rer cli install`. A failed or refused download leaves the
 version you had selected.
 
-No installer edits shell profiles. When `~/.local/bin` is not on your PATH, the
-install prints the exact line to add for your shell. The launcher runs `node` from
+No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
+When that directory is absent from PATH, installation also links it into an
+existing writable, user-owned PATH directory if available, preserving foreign
+commands. Otherwise it prints one activation line to run in the current shell:
+`export PATH="$HOME/.local/bin:$PATH"` (with fish syntax for fish). The launcher runs `node` from
 PATH, so a Node upgrade does not break it. A re-run with the same build changes
 nothing; a different build is installed beside the current one, the previous one
 is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
@@ -179,8 +182,15 @@ as an exact devDependency instead (`"@runeditrun/rer": "0.2.0"`, locked in
 which inside `pnpm run` is the pinned copy in `node_modules/.bin`, so
 `pnpm install --frozen-lockfile && pnpm run build` needs no global `rer`. A global
 `rer` hands every verb to the pinned package, launching included. Until
-`node_modules` holds the pinned version, `rer install` and `rer dev` install it
-first (the frozen `pnpm install`) and every other verb says to run `rer install`.
+`node_modules` holds the pinned version (a fresh clone, or a pulled pin change),
+every verb installs it first (the frozen `pnpm install`), then runs it; verbs
+started at once share that one install.
+Every dependency install, `rer release`'s included, receives an allowlisted
+environment: the shell, locale, terminal and temporary-folder variables, `CI`,
+`TZ`, `SSH_AUTH_SOCK`, `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `XDG_*`, proxy
+settings without their user:password, and `npm_config_*`, `PNPM_*`,
+`COREPACK_*` and `RER_*` settings that carry no credential by name or value.
+No other variable reaches the package manager or a dependency's build script.
 
 Heavy package scripts wait for this computer's job queue with
 `rer queue NAME -- COMMAND [ARGS]` (in vendored mode,
@@ -267,3 +277,10 @@ Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
 `rer queue NAME -- COMMAND`, `rer --version` and `rer --help`.
 
 Licence: MIT.
+
+First-party commands acquire the exact `packageManager` pnpm pin when PATH lacks
+it, verify its registry sha512 integrity and cache it under `$HOME/.rer/pnpm`.
+No global package manager installation or sudo is needed. Independent projects
+continue to run their declared commands with their own tools. Server and job
+state default to `$HOME/.rer/servers` and `$HOME/.rer/jobs`; supplied
+`RER_SERVERS_DIR` and `RER_JOBS_DIR` take precedence and are passed to older pins.

package/cli/README.md

@@ -268,3 +268,24 @@ reproducible and `.github/workflows/rer-release.yml` publishes it; see
 to end on the package-mode reference (served from a local registry, see
 `scripts/rer-package/registry.mjs`), and drives `install.sh` and `rer update`
 against that registry.
+
+
+Owner-account application deploy completion is shared across standard and custom
+hooks. An adapter can declare `deployDeclaration` (or `deploy.declaration`);
+legacy hooks with one root owner deployment declaration are supported too. A
+custom hook may return only `{ deployed: true, origin }`: rer verifies the
+recorded Worker, runs the adapter's actual owner bootstrap, records successful
+ownership separately from retired secrets, and removes the setup token before
+returning success. An owner already claimed by the hook is kept without another
+bootstrap. An existing owner is explicitly reported as kept. Function owner
+hooks run their complete bootstrap flow; setup manifest paths do not replace it.
+A missing or ambiguous declaration or deployment receipt refuses completion.
+
+`--env-file` values are available in the command's preflight, custom hook and
+child build environment and are redacted; the caller environment is restored
+on success and failure. `--remove`, `--set-secret` and `--unset-secret` always go
+through the owner-account controller, without invoking the application's build
+or deploy hook. Failure reports distinguish deployment, owner claim and token
+retirement and preserve the environment, checkout and env-file in recovery
+commands. Retirement can be finished with `rer deploy --unset-secret SETUP_TOKEN`
+plus the same `--environment`, `--env-file` and `--cwd` arguments.

package/cli/auth-copy.mjs

@@ -7,16 +7,17 @@ import { contained } from './project.mjs';
 // 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.
+// Base bytes it copied. Application runtime and schema sources share one pin;
+// the CLI's bundled tooling has its own. Numbered SQL under migrations keeps
+// its historical revision independently: refreshing runtime must not rewrite
+// SQL a database may already have applied. Every copy still needs a valid pin
+// and exact bytes. 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 groupOf = path => typeof path === 'string' && within(path, CLI_ROOT) ? 'cli'
+ : /(?:^|\/)migrations\/(?:[^/]+\/)*\d+[^/]*\.sql$/.test(path) ? 'migration' : 'application';
+const pinned = revision => typeof revision === 'string' && /^[a-f0-9]{40}$/.test(revision);
 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; } }
 
@@ -30,22 +31,24 @@ async function walk(root, path) {
  return files;
 }
 
-// [{ group, path, revision, files: { local path: sha256 } }] for every recorded auth copy.
+// [{ 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) });
+  if (typeof copy?.originPath !== 'string' || !within(copy.originPath, ORIGIN)) continue;
+  const files = copy.files && typeof copy.files === 'object' && !Array.isArray(copy.files) ? copy.files : {};
+  copies.push({ path: copy.path, revision: copy.revision, files, directory: copy.originPath === ORIGIN || Object.keys(files).some(path => path !== copy.path && within(path, 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]));
+  for (const cli of [false, true]) {
+   const entries = Object.entries(lock.files).filter(([path, file]) => (groupOf(path) === 'cli') === cli && typeof file?.source === 'string' && within(file.source, ORIGIN));
+   const files = Object.fromEntries(entries.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 });
+   if (Object.keys(files).length) copies.push({ path: directories[0] ?? null, revision, files, directory: directories.length === 1 });
   }
  }
  return copies;
@@ -55,18 +58,22 @@ 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);
+ for (const [group, id, scope] of [['application', 'SC-05.auth-copy.pin', 'the application runtime and schema sources'], ['cli', 'SC-05.auth-copy.cli-pin', `the CLI's bundled copy under ${CLI_ROOT}`]]) {
+  const grouped = copies.filter(copy => Object.keys(copy.files).some(path => groupOf(path) === 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'}.`]);
+  clauses.push([id, revisions.length === 1 && pinned(revisions[0]), `Copy ${scope} of operator-auth from one pinned Base revision; the seed records ${revisions.join(', ') || 'none'}.`]);
  }
  for (const copy of copies) {
+  if (!Object.keys(copy.files).length) clauses.push([`SC-05.auth-copy.${copy.path}`, false, `${copy.path} has no recorded bytes; record its copied files and their SHA-256 digests.`]);
   for (const [path, expected] of Object.entries(copy.files)) {
+   if (groupOf(path) === 'migration') clauses.push([`SC-05.auth-copy.migration-pin.${path}`, pinned(copy.revision), `${path} must retain a valid pinned Base revision for its historical SQL; the seed records ${copy.revision ?? 'none'}.`]);
    let actual = null; try { actual = sha256(await readFile(await contained(root, path))); } catch {}
-   clauses.push([`SC-05.auth-copy.${path}`, actual === expected, actual === null
+   clauses.push([`SC-05.auth-copy.${path}`, actual !== null && 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.`]);
+    : groupOf(path) === 'migration'
+     ? `${path} differs from Base ${copy.revision}; restore its historical bytes and put schema changes in a new migration.`
+     : `${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)) {

package/cli/bounded.mjs

@@ -16,7 +16,7 @@ export async function boundedCommand(project,options,argv,out){
  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='';
+ let store,result,finalEvent,errorEvent,buffer='';const unclosed=[];
  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);
@@ -47,11 +47,18 @@ export async function boundedCommand(project,options,argv,out){
      const held=await recoverInterrupted(project.root);await held?.release();
     }
    }
+  }).catch(error=>{
+   // The workflow already reported its outcome; only stopping its process group
+   // failed. Keep that outcome, and say so, instead of losing it.
+   if(!finalEvent||cancellation.signal.aborted)throw error;
+   unclosed.push(error);return {code:finalEvent.exitCode};
   });
  }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);}
+  // Every closer runs: a policy socket left listening keeps this process alive.
+  for(const close of [()=>store?.closeCommands(),()=>policy.close(),()=>rm(directory,{recursive:true,force:true})]){try{await close();}catch(error){unclosed.push(error);}}
+  for(const [name,handler] of handlers)process.off(name,handler);
  }
+ if(unclosed.length)out.progress(`Local cleanup could not confirm that every helper process stopped (${unclosed.map(error=>store?.redact?.(String(error?.message))??'unknown cause').join('; ')}). The ${options.verb} itself finished.\n`);
  const termination=cancellation.signal.aborted?cancellation.signal.reason:undefined;
  if(!result&&!termination)return null;
  const exitCode=termination?(termination==='SIGINT'?130:143):result.code;
@@ -61,7 +68,9 @@ export async function boundedCommand(project,options,argv,out){
  }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))));
+  // Redaction can cut through a value that matches a credential; the outcome stands without its details.
+  let shown;try{shown=JSON.parse(store.redact(JSON.stringify(details)));}catch{shown={};}
+  out.result(exitCode===0,exitCode,shown);
  }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};

package/cli/container.mjs

@@ -18,6 +18,16 @@ async function run(command,args,options={}) {
  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');}
 }
+/** The image's build folder (.rer/container/image unless `output`), built with the checkout's private local settings hidden. */
+export async function imageFolder(project,operation,config,{output,engine}={}) {
+ const {root}=project,{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,JSON.stringify({output,engine})],{cwd:root,env:buildEnvironment([...declared,...(config.secrets??[]).flatMap(item=>[item.binding,item.environment])])});
+ },{nested:operation.token,settings:[...(project.adapter?.settings??[]),...(project.privateInputs??[])]});
+}
 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');
@@ -35,16 +45,7 @@ async function runContainer(project,options,out,operation) {
   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.image){await imageFolder(project,operation,config);await run('docker',['build','--tag',image,join(root,'.rer/container/image')],{cwd:root});}
   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});

package/cli/contract.mjs

@@ -6,12 +6,12 @@ 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', '--door'], 'Build, migrate, prepare private settings and first owner; stop the temporary app. --door sets a fresh checkout up at its front-door origin http://NAME.localhost:PORT (after rer door enable).'],
- dev: [['--port', '--host', '--idle-timeout', '--stop', '--detach', '--foreground', '--as', '--login', '--models', '--models-service', '--door', '--direct'], 'Development with assets, HMR and the declared scheduled triggers run locally on their schedule. --detach returns once ready; --foreground keeps this command serving. 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. --door moves this checkout to its front-door origin http://NAME.localhost:PORT, keeping its data; --direct moves it back; --port and --host serve directly.'],
+ dev: [['--port', '--host', '--idle-timeout', '--stop', '--detach', '--foreground', '--as', '--login', '--models', '--models-service', '--door', '--direct', '--demo'], 'Development with assets, HMR and the declared scheduled triggers run locally on their schedule. --detach returns once ready; --foreground keeps this command serving. 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. --door moves this checkout to its front-door origin http://NAME.localhost:PORT, keeping its data; --direct moves it back; --port and --host serve directly. --demo (or rer demo) serves a throwaway demo: fresh data in .rer/demo/START (deleted when it stops: --stop, Ctrl-C or its end, one hour by default or --idle-timeout), the saved owner signed in, the seed\'s demo data, a Demo bar, and nothing sent (RER_DEMO=1; the checkout\'s own data is never touched).'],
  preview: [['--port', '--host', '--idle-timeout', '--stop', '--detach', '--foreground'], 'Production output; --detach returns once ready, --foreground keeps this command serving. Reuse intact build, refresh changed assets, preserve owner/state, idle timeout and explicit stop.'],
  build: [['--site'], 'Production build with private local settings excluded and restored. --site instead writes the static run site (homepage, /run, docs) to its declared folder and prints that folder.'],
  verify: [[], 'Run the complete internal verification target.'],
  reset: [['--yes'], 'Confirmed removal of the declared local inventory only.'],
- deploy: [['--environment', '--dry-run', '--site', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port'], 'Owner-account deployment and health; dry run performs local validation/build only. --site deploys the run site instead: an assets-only Worker on its custom domain with www redirected; with --dry-run it builds the site and prints the plan with no provider request.'],
+ deploy: [['--environment', '--dry-run', '--site', '--demo', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port', '--remove', '--yes', '--set-secret', '--unset-secret'], 'Owner-account deployment and health; dry run performs local validation/build only. Declared secrets come from the environment or --env-file (an owned 0600 KEY=VALUE file); a new Worker gets the local setup owner and fresh generated secrets when they are not given. After a healthy deploy rer claims the setup owner on the hosted app with the one-time setup token, then removes the token. --set-secret NAME (value from the environment or --env-file) and --unset-secret NAME change one secret of the deployed Worker without a build and record its new version. --remove --yes deletes what this environment\'s deploy record says rer created (Worker, D1, R2, KV, queues), reads back that each is gone, and touches nothing else. --site deploys the run site instead: an assets-only Worker on its custom domain with www redirected; with --dry-run it builds the site and prints the plan with no provider request. --demo deploys the hosted demo instead (deploy-demo.json): a front Worker on demo.<domain> giving each visitor their own signed-in, throwaway container of this seed that can send nothing; --dry-run writes it to .rer/demo-host with no provider request.'],
  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.'],

package/cli/demo-host.mjs

@@ -0,0 +1,47 @@
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { contained } from './project.mjs';
+import { invalid, missing, refuse, RerError } from './errors.mjs';
+import { imageFolder } from './container.mjs';
+import { DEMO_FILES, demoPlan } from '../modules/demo-host/plan.mjs';
+
+// `rer deploy --demo [--dry-run]`: the seed's hosted demo at demo.<domain>
+// (modules/demo-host), from deploy-demo.json. It writes .rer/demo-host/: the
+// front Worker, its wrangler.json and the container image folder (workerd
+// engine). --dry-run stops there, so `wrangler dev` can serve that folder with
+// Docker; a deploy runs `wrangler deploy` on it with the Turnstile secret.
+export async function demoHostCommand(project, options, store, signal, out, operation) {
+ const read = async path => { try { return JSON.parse(await readFile(await contained(project.root, path), 'utf8')); } catch (error) { if (error instanceof RerError) throw error; throw invalid(`Missing or malformed ${path}.`); } };
+ const app = await read(project.adapter.deploy?.declaration ?? 'deploy.json'), declaration = await read('deploy-demo.json');
+ if (!(app.platforms ?? ['workers']).includes('container')) throw refuse('A hosted demo runs the seed\'s container image: declare "container" in deploy.json platforms first.');
+ let plan;
+ try { plan = demoPlan({ project: app.project, environment: options.environment ?? 'production', compatibilityDate: app.compatibilityDate, originVar: app.originVar, declaration, turnstileSiteKey: process.env.TURNSTILE_SITE_KEY?.trim() }); }
+ catch (error) { throw invalid(`The demo deploy declaration is invalid (${error.message}). deploy-demo.json holds {"version": 1, "domain": "<run site apex>", "name": "<product name>"}, optionally "maxInstances" and plain "settings".`); }
+ const folder = join(project.root, '.rer', 'demo-host');
+ await rm(folder, { recursive: true, force: true });
+ await mkdir(folder, { recursive: true, mode: 0o700 });
+ await store.step('Building the demo container image (workerd engine)');
+ await imageFolder(project, operation, app, { output: join(folder, 'image'), engine: 'workerd' });
+ for (const file of DEMO_FILES) await cp(new URL(`../modules/demo-host/${file}`, import.meta.url), join(folder, file));
+ await writeFile(join(folder, 'wrangler.json'), JSON.stringify(plan.wrangler, null, 2) + '\n');
+ const summary = { worker: plan.worker, origin: plan.origin, hostname: plan.hostname, folder: '.rer/demo-host', maxInstances: plan.maxInstances, settings: plan.settings, instanceType: 'basic', startsPerIpPerMinute: 3, minutes: 60, idleMinutes: 15, enableInternet: false };
+ const human = [`Demo plan: Worker ${summary.worker} on ${summary.hostname} (custom domain; workers.dev off), written to ${summary.folder}`,
+  `  one container per visitor (basic, at most ${summary.maxInstances} at once, no internet, RER_DEMO=1), 3 starts per IP per minute behind Turnstile`,
+  `  each demo ends after 60 minutes or 15 idle minutes; its container is destroyed and its state deleted`];
+ if (options.dryRun) {
+  if (options.json) out.event('demo', summary); else for (const line of human) out.human(line);
+  store.report('deploy --demo: dry run complete; no deployment occurred and no provider request was made.');
+  return { dryRun: true, deployed: false, demo: summary };
+ }
+ const names = ['CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN', 'TURNSTILE_SITE_KEY', 'TURNSTILE_SECRET_KEY'];
+ if (names.some(name => !process.env[name]?.trim())) throw missing(`${names.join(', ')} are required; see DEMO.md "Hosting the demo".`);
+ if (!options.json) for (const line of human) out.human(line);
+ const secrets = join(folder, '.secrets.json');
+ await writeFile(secrets, JSON.stringify({ TURNSTILE_SECRET_KEY: process.env.TURNSTILE_SECRET_KEY.trim() }), { mode: 0o600 });
+ try {
+  const wrangler = createRequire(join(project.root, 'package.json')).resolve('wrangler/bin/wrangler.js');
+  await store.run('Deploying the demo Worker and its container image', process.execPath, [wrangler, 'deploy', '--config', 'wrangler.json', '--secrets-file', '.secrets.json'], { cwd: folder, signal });
+ } finally { await rm(secrets, { force: true }); }
+ return { dryRun: false, deployed: true, origin: plan.origin, demo: summary };
+}

package/cli/demo.mjs

@@ -0,0 +1,47 @@
+import { readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { refuse } from './errors.mjs';
+import { shared } from './shared.mjs';
+
+// `rer demo` (dev --demo) state and its two adoption checks (export/DEMO.md).
+const adopt = 'See DEMO.md: a seed adopts demo mode with src/demo.ts, withDemo as the first import of its Worker entry, and three vite.config changes.';
+
+// Before anything starts: the seed's Vite persists where rer says, so the
+// checkout's own .wrangler/state is never opened by a demo, and hands the
+// Worker's cloudflare:sockets imports demo mode's guarded connect.
+export async function demoAdopted(root) {
+ let text = '';
+ for (const name of ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs']) {
+  try { text = await readFile(join(root, name), 'utf8'); break; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+ }
+ if (!text.includes('RER_STATE_DIR')) throw refuse(`This seed's vite.config does not persist to RER_STATE_DIR, so a demo would run on this checkout's own data. ${adopt}`);
+ if (!text.includes('demoSockets(')) throw refuse(`This seed's vite.config does not list demoSockets(), so a demo's cloudflare:sockets connections could leave this computer. ${adopt}`);
+}
+
+// A demo's data lives in .rer/demo/START. Only one server runs per checkout, so
+// any other demo folder is a stopped demo's leftover (a hard kill) and goes now.
+// The end is local ISO time with its offset: the Demo bar shows its HH:MM as written.
+export async function demoState(root, seconds) {
+ const { privateDirectory } = await shared('private-files.mjs');
+ const started = new Date(), stamp = started.toISOString().replace(/[-:]|\.\d+/g, '');
+ const parent = await privateDirectory(root, ['.rer', 'demo']);
+ for (const entry of await readdir(parent)) await rm(join(parent, entry), { recursive: true, force: true });
+ const end = new Date(started.getTime() + seconds * 1000), offset = -end.getTimezoneOffset();
+ const local = new Date(end.getTime() + offset * 60000).toISOString().slice(0, 19);
+ const zone = `${offset < 0 ? '-' : '+'}${String(Math.trunc(Math.abs(offset) / 60)).padStart(2, '0')}:${String(Math.abs(offset) % 60).padStart(2, '0')}`;
+ return { state: await privateDirectory(root, ['.rer', 'demo', stamp]), ends: local + zone };
+}
+
+// After start: a request has passed withDemo, which creates rer_demo in the
+// demo's own database. Without it nothing is blocked, so the demo stops.
+export async function demoGuarded(url, state, signal) {
+ const { appFetch } = await shared('app-fetch.mjs');
+ await (await appFetch(url + '/health', { signal })).body?.cancel();
+ const directory = join(state, 'v3/d1/miniflare-D1DatabaseObject');
+ for (const file of (await readdir(directory).catch(() => [])).filter(name => name.endsWith('.sqlite') && name !== 'metadata.sqlite')) {
+  const db = new DatabaseSync(join(directory, file), { readOnly: true });
+  try { if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'rer_demo'").get()) return; } finally { db.close(); }
+ }
+ throw refuse(`The app did not start in demo mode (no withDemo guard answered), so it could send. The demo was stopped and its data deleted. ${adopt}`);
+}

package/cli/dependencies.mjs

@@ -1,25 +1,41 @@
 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 { INTERFACE, 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.
+// setup answers, generated runtime configuration, logs or an archive. Returns
+// connected dependencies and the verified native owner outcome; an unanswered
+// optional dependency is skipped.
 export async function linkDependencies({project,input,origin,store,signal,appSetupToken,fetch:fetcher=globalThis.fetch,clock=Date.now}) {
- const links=[];
+ const links=[],connected=[];
+ const ownerDependency = project.setupManifest?.steps?.find(step => step.type === 'owner-claim' && step.mode === 'idp')?.dependency;
+ let ownerClaimed = false;
+ let ownerIssuer;
+ const ownerState = async () => {
+  if (ownerDependency !== INTERFACE || !ownerIssuer) return undefined;
+  const document = await readJson(fetcher, origin+'/.well-known/rer-dependencies', {timeoutMs:5000});
+  // claim:false also describes apps without owner-capable dependencies.
+  if (document.origin === origin && document.dependencies?.some(item => item.interface === INTERFACE) && typeof document.claim === 'boolean') return document.claim;
+ };
  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;}
+  connected.push(dependency);
+  if(dependency.interface===ownerDependency)ownerIssuer=issuer;
   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(current?.links?.some(link=>link.interface===dependency.interface && link.issuer===issuer && link.linked===true)){ if(dependency.interface===ownerDependency)ownerClaimed=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});
  }
+ // Validate every approval first, then distinguish an existing native owner
+ // from one this link is about to claim, without relying on local deploy history.
+ const unclaimedBefore = await ownerState();
  // 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) {
@@ -39,7 +55,13 @@ export async function linkDependencies({project,input,origin,store,signal,appSet
   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.');
+  if(dependency.interface===ownerDependency)ownerClaimed=true;
   await unlink(path);
   store.report('Dependency linked; its one-time approval token was deleted.');
  }
+ if (ownerClaimed) {
+  const status = await readJson(fetcher, origin+'/auth/dependencies/status', {timeoutMs:5000});
+  ownerClaimed = unclaimedBefore !== undefined && await ownerState() === false && status.links?.some(link => link.interface === ownerDependency && link.issuer === ownerIssuer && link.linked === true) === true;
+ }
+ return {connected,ownerClaimed, ...(ownerClaimed ? {ownerOutcome: unclaimedBefore ? 'claimed' : 'kept'} : {})};
 }

package/cli/deploy-command.mjs

@@ -0,0 +1,94 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { contained } from './project.mjs';
+import { invalid, refuse, RerError } from './errors.mjs';
+import { ownerDeploy } from './deploy.mjs';
+import { deployEnvironment, deployAgain } from './deploy-inputs.mjs';
+import { claimHostedOwner } from './deploy-owner.mjs';
+import { mutationReadinessFailure } from './deploy-readiness.mjs';
+import { observeOwner } from './deploy-observation.mjs';
+import { main as owner } from '../modules/deploy-kit/owner-cli.mjs';
+import { localOnlyBinding, ownerWorkerName } from '../modules/deploy-kit/owner.mjs';
+import { refuseLocalModels } from '../modules/deploy-kit/local-only.mjs';
+import { shared } from './shared.mjs';
+
+export function validateDeployOptions(options) {
+ const changes = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret'].filter(Boolean);
+ if (changes.length > 1 || changes.length && options.dryRun) throw invalid(`Use ${changes.join(', ')}${options.dryRun ? ' and --dry-run' : ''} on separate runs.`);
+ if (options.remove && !options.yes) throw invalid(`${deployAgain(options)} --remove deletes this environment's Worker and every D1, R2, KV and queue rer created for it, with their data. Add --yes to confirm.`);
+}
+
+// An explicit adapter declaration wins. Older hooks use a conventional root
+// declaration; discover it by its schema, never by seed identity or hook source.
+async function declarationFor(root, adapter) {
+ const declared = adapter.deployDeclaration ?? adapter.deploy?.declaration;
+ const paths = declared ? [declared] : (await readdir(root)).filter(path => path.endsWith('.json') && path !== adapter.site?.declaration);
+ const matches = [];
+ for (const path of paths) {
+  let value;
+  try { value = JSON.parse(await readFile(await contained(root, path), 'utf8')); }
+  catch (error) { if (declared) throw error; continue; }
+  if (declared || value?.version === 1 && typeof value.project === 'string' && typeof value.compatibilityDate === 'string') matches.push({ path, value });
+ }
+ if (matches.length !== 1) throw refuse('A single owner-account deploy declaration is required. Declare deployDeclaration on the adapter; missing or ambiguous declarations cannot be used safely.');
+ return matches[0];
+}
+
+export async function deployCommand(context) {
+ const { adapter, root, options, store, setupManifest, linkDependencies, localOnlyKeys = [] } = context;
+ validateDeployOptions(options);
+ 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 { path, value: declaration } = await declarationFor(root, adapter);
+ ownerWorkerName(declaration.project, options.environment ?? 'production');
+ const local = localOnlyBinding(declaration, localOnlyKeys);
+ if (local) throw refuse(`${path} names the local-only key ${local} as a deploy binding or secret. Remove it; local dev keys never reach a deployment.`);
+ // Custom hooks historically ignored these flags. Only the ownership controller
+ // may perform them; neither a build nor a custom upload runs here.
+ if (options.remove || options.setSecret || options.unsetSecret) return ownerDeploy(path, adapter)(context);
+ if (adapter.deploy.managesHostedOwner) return adapter.deploy(context);
+ const { env, supplied } = await deployEnvironment({ root, options, declaration, setupManifest, settings: adapter.settings, localOnlyKeys });
+ const { createRedaction, credentialValues } = await shared('redaction.mjs');
+ const redaction = createRedaction();
+ const addSecret = value => { redaction.addSecrets([value]); store.addSecrets?.([value]); };
+ for (const value of [...credentialValues(env), env.CLOUDFLARE_ACCOUNT_ID, ...(declaration.secrets ?? []).map(item => env[item.environment])].filter(Boolean)) addSecret(value);
+ const command = (verb, extra = [], values = env) => owner([verb, '--declaration', path, '--environment', options.environment ?? 'production', ...extra], values, { cwd: root, localOnlyKeys });
+ let recorded;
+ const inspect = async () => (recorded = await command('inspect'));
+ let observedClaims = [];
+ let deployed, claimed, linked = false, linkResult, step = 'custom deploy';
+ const link = async token => { if (!linked) { const state = await inspect(); linkResult = await linkDependencies?.(state.origin, token); linked = true; } return linkResult; };
+ try {
+  return await observeOwner({ paths: ['/auth/bootstrap', adapter.hooks?.owner?.path, setupManifest?.steps?.find(item => item.type === 'owner-claim')?.path].filter(Boolean), inspect, beforeClaim: link, addSecret }, async claims => {
+   observedClaims = claims;
+   const saved = { ...process.env };
+   try {
+    Object.assign(process.env, env);
+    deployed = await adapter.deploy({ ...context, linkDependencies: async (_origin, token) => link(token) });
+   } finally {
+    for (const key of Object.keys(process.env)) if (!Object.hasOwn(saved, key)) delete process.env[key];
+    Object.assign(process.env, saved);
+   }
+   if (options.dryRun) return deployed;
+   if (!deployed?.deployed) throw new Error('custom-deploy-did-not-confirm-deployment');
+   step = 'verify recorded deployment';
+   const state = await inspect();
+   if (state.origin !== deployed.origin) throw new Error('owner-claim-origin-mismatch');
+   if (claims.some(item => !item.outcome)) throw new Error('owner-claim-failed');
+   claimed = claims.at(-1)?.outcome;
+   step = 'claim owner';
+   claimed = await claimHostedOwner({ hook: adapter.hooks?.owner, setupManifest, declaration, deployed: { ...state, owner: claimed, observedOwner: () => claims.at(-1)?.outcome }, env, supplied, secret: (extra, values) => command('secret', extra, values), addSecret, beforeClaim: link, recordClaim: outcome => command('record-owner', ['--outcome', outcome]), store, signal: context.signal });
+   if (!linked) await linkDependencies?.(state.origin);
+   if (claimed) store.report(`${claimed === 'claimed' ? 'Claimed the hosted owner' : 'The hosted owner was already claimed and was kept'}; the one-time setup token was removed. Sign in by email at ${state.origin}.`);
+   return { ...deployed, ...(claimed ? { owner: claimed } : {}), dependenciesLinked: true };
+  });
+ } catch (error) {
+  const again = deployAgain(options);
+  if (error instanceof RerError && !deployed?.deployed && !recorded) { error.message = store.redact?.(redaction.redact(error.message)) ?? redaction.redact(error.message); throw error; }
+  const { commandFailure } = await shared('failures.mjs');
+  const outcome = error.owner ?? claimed ?? observedClaims.at(-1)?.outcome;
+  const state = deployed?.deployed || recorded ? `The application is deployed at ${deployed?.origin ?? recorded.origin}; ${outcome ? `owner ${outcome}` : 'owner claim is not confirmed'}; setup token retirement is not confirmed.` : 'The custom deploy did not finish; inspect its deployment record before recovery.';
+  const redact = value => store.redact?.(redaction.redact(value)) ?? redaction.redact(value);
+  const readiness = mutationReadinessFailure(error, { again, redact });
+  if (readiness) throw commandFailure(readiness);
+  throw commandFailure(redact(`${state} Failed at ${step}: ${error.message}${error.cause ? ` (${error.cause})` : ''}. Fix the cause and run ${again} again using the same environment credentials. ${outcome ? `To retire the token without rebuilding: ${again} --unset-secret ${setupManifest?.steps?.find(item => item.type === 'owner-claim')?.tokenField ?? 'SETUP_TOKEN'}.` : ''}`));
+ }
+}

package/cli/deploy-inputs.mjs

@@ -0,0 +1,55 @@
+import { randomBytes } from 'node:crypto';
+import { shared } from './shared.mjs';
+import { invalid } from './errors.mjs';
+import { readDeployEnvFile } from '../modules/deploy-kit/env-file.mjs';
+
+// The values a Workers deploy reads for its declared secrets: this process's
+// environment, then the --env-file (which wins), then what rer supplies itself:
+// the local setup owner's email, and a fresh value for each secret the setup
+// manifest generates (a session secret, the one-time setup token). A value only
+// reaches a Worker that lacks that secret; an existing one is kept unchanged.
+export async function deployEnvironment({ root, options, declaration, setupManifest, settings, localOnlyKeys = [] }) {
+ const env = { ...process.env }, supplied = [];
+ if (options.envFile) {
+  let values;
+  try { values = await readDeployEnvFile(root, options.envFile, localOnlyKeys); }
+  catch (error) { throw invalid(`The --env-file ${options.envFile} could not be used: ${error.code === 'ENOENT' ? 'no such file' : error.message}.`); }
+  Object.assign(env, values);
+ }
+ const secrets = Array.isArray(declaration.secrets) ? declaration.secrets : [];
+ const absent = item => item && !env[item.environment]?.trim();
+ const emailField = setupManifest?.steps?.find(step => step.type === 'owner-claim')?.emailField;
+ const email = secrets.find(item => item?.binding === emailField);
+ if (absent(email) && settings) {
+  const { readSettings } = await shared('adapter-settings.mjs');
+  const owner = (await readSettings(root, settings)).values[emailField];
+  if (typeof owner === 'string' && owner.includes('@')) { env[email.environment] = owner; supplied.push(email.binding); }
+ }
+ for (const field of setupManifest?.fields ?? []) {
+  const item = field.kind === 'secret' && field.generate ? secrets.find(entry => entry?.binding === field.name) : undefined;
+  if (absent(item)) { env[item.environment] = randomBytes(32).toString(field.generate); supplied.push(item.binding); }
+ }
+ return { env, supplied };
+}
+
+// Hooks and their child builds read process.env. Install the private file for
+// this command only, and restore even keys changed by a failing hook.
+export async function withDeployEnvironment(root, options, run) {
+ const saved = { ...process.env };
+ const { env } = await deployEnvironment({ root, options, declaration: {} });
+ const { createRedaction, credentialValues } = await shared('redaction.mjs');
+ const redaction = createRedaction();
+ redaction.addSecrets([...credentialValues(env), ...Object.entries(env).filter(([key, value]) => saved[key] !== value).map(([, value]) => value)]);
+ Object.assign(process.env, env);
+ try { return await run(redaction); }
+ catch (error) { if (typeof error?.message === 'string') error.message = redaction.redact(error.message); throw error; }
+ finally {
+  for (const key of Object.keys(process.env)) if (!Object.hasOwn(saved, key)) delete process.env[key];
+  Object.assign(process.env, saved);
+ }
+}
+
+export function deployAgain(options) {
+ const quote = value => /^[a-zA-Z0-9_./-]+$/.test(value) ? value : `'${String(value).replaceAll("'", "'\"'\"'")}'`;
+ return `rer deploy --environment ${quote(options.environment ?? 'production')}${options.envFile ? ` --env-file ${quote(options.envFile)}` : ''}${options.cwd ? ` --cwd ${quote(options.cwd)}` : ''}`;
+}

package/cli/deploy-observation.mjs

@@ -0,0 +1,28 @@
+// Observe the actual bootstrap exchange of a custom hook, including hooks that
+// call the shared owner helper themselves. Never issue a second claim after it.
+// The deployment record is checked before linking with its live setup token.
+export async function observeOwner({ paths, inspect, beforeClaim, addSecret }, run) {
+ const fetch = globalThis.fetch, claims = [];
+ globalThis.fetch = async (input, init = {}) => {
+  const url = new URL(input instanceof Request ? input.url : input);
+  let body;
+  if (paths.includes(url.pathname) && (init.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase() === 'POST') {
+   try { body = JSON.parse(typeof init.body === 'string' ? init.body : input instanceof Request ? await input.clone().text() : 'null'); } catch {}
+  }
+  if (typeof body?.token !== 'string' || !body.token) return fetch(input, init);
+  addSecret(body.token);
+  const deployed = await inspect();
+  if (url.origin !== deployed.origin) throw new Error('owner-claim-origin-mismatch');
+  await beforeClaim?.(body.token);
+  const response = await fetch(input, init);
+  let code;
+  if (response.status !== 303) {
+   try { code = (await response.clone().json()).error; } catch {}
+  }
+  const outcome = response.status === 303 ? 'claimed' : response.status === 409 && code === 'already_initialized' ? 'kept' : undefined;
+  claims.push({ origin: url.origin, outcome, status: response.status });
+  return response;
+ };
+ try { return await run(claims); }
+ finally { globalThis.fetch = fetch; }
+}