@runeditrun/rer 0.2.0 → 0.2.2

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`
@@ -247,7 +250,7 @@ line that still names it. A later refresh is a version bump:
 | `@runeditrun/rer/server-resources` | managed server resource readings (runtime journeys) | `scripts/base-cli/cli/server-resources.mjs` |
 | `@runeditrun/rer/operations` | OPERATIONS describe and check | `scripts/base-cli/operations/operations.mjs` |
 | `@runeditrun/rer/modules/portability`, `/catalogue`, `/cli`, `/cli-options`, `/files`, `/format`, `/http`, `/import`, `/journal`, `/legacy-safety`, `/migration-history`, `/storage` | portability module | `scripts/base-cli/modules/portability/*.mjs` |
-| `@runeditrun/rer/modules/release/export`, `/publication-scan`, `/source` | release export and publication scan | `scripts/base-cli/modules/release/*.mjs` |
+| `@runeditrun/rer/modules/release/export`, `/publication-scan`, `/source`, `/signature` | release export, publication scan and shared signature verifier | `scripts/base-cli/modules/release/*.mjs` |
 | `@runeditrun/rer/modules/deploy-kit/owner`, `/owner-cli`, `/prepare`, `/provider` | deploy kit | `scripts/base-cli/modules/deploy-kit/*.mjs` |
 | `@runeditrun/rer/modules/operator-auth`, `/dev`, `/dev/badge`, `/dev-admission`, `/accounts/native`, `/identity/email-link` | operator auth | `scripts/base-cli/modules/operator-auth/index.mjs`, `dev/index.mjs`, `dev/badge.mjs`, `dev-admission.mjs`, `accounts/native.mjs`, `identity/email-link/index.mjs` |
 | `@runeditrun/rer/modules/erasure/fence` | erasure fence statements | `scripts/base-cli/modules/erasure/fence.mjs` |
@@ -260,9 +263,17 @@ In a checkout, every verb runs that checkout's own pinned `rer`; `rer VERB --hel
 there lists its flags:
 
 `install`, `setup`, `dev`, `preview`, `build`, `verify`, `reset --yes`, `deploy`,
-`export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`.
+`export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`,
+`release sign`, `release receipt` and `release keygen`.
 
 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

@@ -131,8 +131,10 @@ Existing seeds receive this policy by refreshing `scripts/base-cli/` with
 onboarding copy). For production, adopt the persistent root-head stylesheet,
 primary preload and matched fallback described in `export/UI-CONVENTIONS.md`.
 
-Both are managed foreground servers; their first invocation stays active while
-serving. A compatible repeated invocation verifies the registered application,
+Both are managed servers. `--detach` returns after readiness, leaving the server
+running; `--foreground` keeps the invocation active while serving. Preview
+refreshes changed built assets and their ETags; source edits need a restart and
+rebuild. A compatible repeated invocation verifies the registered application,
 prints its safe ready/outbox URLs and exits without a new build or sign-in.
 Explicit conflicting host, port or timeout, or the other mode, refuses with
 exit 4 and the correct stop command. `--stop` is idempotent;

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/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', '--as', '--login', '--models', '--models-service', '--door', '--direct'], 'Foreground development with assets, HMR and the declared scheduled triggers run locally on their schedule. With devIdentity it opens signed in as the owner (--as PERSONA picks another start, --login uses the outbox sign-in instead); otherwise ordinary owner sign-in through the outbox. --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.'],
- preview: [['--port', '--host', '--idle-timeout', '--stop'], 'Foreground fixed production output; reuse intact build, preserve owner/state, idle timeout and explicit stop.'],
+ 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.'],
+ 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', '--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.'],
  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/deploy-inputs.mjs

@@ -0,0 +1,33 @@
+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 };
+}

package/cli/deploy-owner.mjs

@@ -0,0 +1,61 @@
+import { randomBytes } from 'node:crypto';
+
+// After a healthy deploy, the hosted app's first owner is the setup owner: rer
+// claims it with the one-time setup token through the seed's standard owner step
+// (Base operator-auth POST /auth/bootstrap), then removes that token from the
+// Worker and records the new Worker version. A Worker still holding a token rer
+// did not upload this run gets a fresh one first, unless the person supplied the
+// token (environment or --env-file): that value is the deployed token and is used. A seed with its own owner step
+// function, an identity-provider claim, or no declared token secret is left to it.
+// `beforeClaim(token)` runs while the token is live (dependency approvals need it).
+export async function claimHostedOwner({ hook, setupManifest, declaration, deployed, env, supplied = [], secret, addSecret, beforeClaim, fetch = globalThis.fetch, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), boundMs = 90000 }) {
+ if (!hook || typeof hook !== 'object' || Array.isArray(hook) || !deployed.origin) return undefined;
+ const claim = setupManifest?.steps?.find(step => step.type === 'owner-claim');
+ if (claim?.mode === 'idp') return undefined;
+ const tokenKey = hook.tokenKey ?? claim?.tokenField ?? 'SETUP_TOKEN';
+ const item = (Array.isArray(declaration.secrets) ? declaration.secrets : []).find(entry => entry?.binding === tokenKey);
+ if (!item || deployed.retiredSecrets?.includes(tokenKey)) return undefined;
+ const given = env[item.environment]?.trim() && !supplied.includes(tokenKey);
+ let token = deployed.sentSecrets?.includes(tokenKey) || given ? env[item.environment] : undefined;
+ if (!token) {
+  token = randomBytes(32).toString('hex'); addSecret(token);
+  const { versionId } = await secret(['--set', tokenKey], { ...env, [item.environment]: token });
+  // A secret change is a new Worker version; claim once the app answers from it.
+  await servingVersion({ origin: deployed.origin, versionId, fetch, sleep, boundMs });
+ }
+ await beforeClaim?.(token);
+ const displayName = (typeof hook.displayName === 'function' ? hook.displayName({}) : undefined) || 'Owner';
+ let response, code;
+ // Edge locations can briefly answer from the previous version, which lacks this token.
+ for (let attempt = 1; ; attempt++) {
+  try {
+   response = await fetch(new URL(hook.path ?? '/auth/bootstrap', deployed.origin), { method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(30000),
+    headers: { Origin: deployed.origin, 'Content-Type': 'application/json' }, body: JSON.stringify({ token, displayName, returnTo: hook.returnTo ?? '/' }) });
+  } catch { throw ownerFailure('the hosted application did not answer'); }
+  code = 'no code';
+  if (response.status !== 303) { try { const body = await response.json(); if (typeof body?.error === 'string' && /^[a-z_]{1,64}$/.test(body.error)) code = body.error; } catch {} }
+  else await response.body?.cancel();
+  if (response.status !== 403 || code !== 'invalid_setup_token' || attempt === 3) break;
+  await sleep(5000);
+ }
+ const outcome = response.status === 303 ? 'claimed' : response.status === 409 && code === 'already_initialized' ? 'kept' : undefined;
+ if (!outcome) throw ownerFailure(`HTTP ${response.status} (${code})${code === 'invalid_setup_token' && given ? `; the ${item.environment} you supplied is not the deployed setup token: leave it unset and rer issues a fresh one` : ''}`);
+ await secret(['--unset', tokenKey], env);
+ return outcome;
+}
+
+async function servingVersion({ origin, versionId, fetch, sleep, boundMs }) {
+ const deadline = Date.now() + boundMs;
+ while (true) {
+  try {
+   const response = await fetch(new URL('/health', origin), { redirect: 'manual', signal: AbortSignal.timeout(10000), headers: { 'Cache-Control': 'no-cache', Accept: 'application/json' } });
+   if ((await response.json().catch(() => null))?.deployment?.versionId === versionId) return;
+  } catch {}
+  if (Date.now() >= deadline) throw ownerFailure(`the hosted app did not answer from the Worker version holding the new setup token within ${Math.round(boundMs / 1000)} seconds`);
+  await sleep(2000);
+ }
+}
+
+function ownerFailure(cause) {
+ const error = new Error('owner-claim-failed'); error.cause = cause; return error;
+}

package/cli/deploy.mjs

@@ -1,22 +1,33 @@
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { deployDiagnostic } from '../modules/deploy-kit/diagnostics.mjs';
+import { shared } from './shared.mjs';
 import { contained } from './project.mjs';
-import { missing, invalid, refuse } from './errors.mjs';
+import { missing, invalid, refuse, RerError } from './errors.mjs';
 import { ownerPlan, ownerWorkerName, localOnlyBinding } from '../modules/deploy-kit/owner.mjs';
 import { packageBuild } from '../modules/deploy-kit/prepare.mjs';
 import { refuseLocalModels } from '../modules/deploy-kit/local-only.mjs';
+import { deployEnvironment } from './deploy-inputs.mjs';
+import { claimHostedOwner } from './deploy-owner.mjs';
 
 export function ownerDeploy(declarationPath, lifecycle) {
  // rer verify serves the build with this declaration's vars and secrets.
- return Object.assign(async ({ root, options, store, signal, operationToken, localOnlyKeys = [], checkBuild = async () => {} }) => {
+ return Object.assign(async ({ root, options, store, signal, operationToken, localOnlyKeys = [], checkBuild = async () => {}, setupManifest, linkDependencies }) => {
   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 = await contained(root, declarationPath);
   let declaration; try { declaration = JSON.parse(await readFile(path, 'utf8')); } catch { throw invalid('Malformed owner-account deploy declaration.'); }
   const local = localOnlyBinding(declaration, localOnlyKeys);
   if (local) throw refuse(`${declarationPath} names the local-only key ${local} as a deploy binding or secret. Remove it; local dev keys never reach a deployment.`);
   const environment = options.environment ?? 'production';
-  await lifecycle.run(root, {}, store, () => {}, signal, { verb: 'build', operationToken });
-  await checkBuild();
+  const again = `rer deploy --environment ${environment}`;
+  const change = [options.remove && '--remove', options.setSecret && '--set-secret', options.unsetSecret && '--unset-secret'].filter(Boolean);
+  // The command that finishes what this run started: the same verb, never a plain deploy in its place.
+  const retry = options.remove ? `${again} --remove --yes` : options.setSecret ? `${again} --set-secret ${options.setSecret}` : options.unsetSecret ? `${again} --unset-secret ${options.unsetSecret}` : again;
+  if (change.length > 1 || change.length && options.dryRun) throw invalid(`Use ${change.join(', ')}${options.dryRun ? ' and --dry-run' : ''} on separate runs.`);
+  if (options.remove && !options.yes) throw invalid(`${again} --remove deletes this environment's Worker and every D1, R2, KV and queue rer created for it, with their data. Add --yes to confirm.`);
+  if (!change.length) {
+   await lifecycle.run(root, {}, store, () => {}, signal, { verb: 'build', operationToken });
+   await checkBuild();
+  }
   if (options.dryRun) {
    // Locally validate the real declaration/artifact without ownerTarget's
    // account lookup. This synthetic target is validation data, not a provider.
@@ -28,10 +39,85 @@ export function ownerDeploy(declarationPath, lifecycle) {
   }
   const names = ['CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN'];
   if (names.some(name => !process.env[name]?.trim())) throw missing('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required. See the deploy-kit owner-account instructions.');
+  const { env, supplied } = await deployEnvironment({ root, options, declaration, setupManifest, settings: lifecycle.settings, localOnlyKeys });
   const { main } = await import('../modules/deploy-kit/owner-cli.mjs');
-  const argv = ['deploy', '--declaration', declarationPath, '--environment', environment];
-  const result = await main(argv, process.env, { cwd: root, localOnlyKeys, notice: line => store.report(line) });
-  await main(['health', ...argv.slice(1)], process.env, { cwd: root, localOnlyKeys });
-  return { deployed: true, origin: result.origin };
+  const { createRedaction, credentialValues } = await shared('redaction.mjs');
+  const redaction = createRedaction();
+  redaction.addSecrets([...credentialValues(env), env.CLOUDFLARE_ACCOUNT_ID, ...(declaration.secrets ?? []).map(item => env[item.environment]).filter(Boolean)]);
+  const claim = setupManifest?.steps?.find(item => item.type === 'owner-claim');
+  const declared = binding => (Array.isArray(declaration.secrets) ? declaration.secrets : []).find(item => item?.binding === binding);
+  const owner = (command, extra = [], values = env, more = {}) => main([command, '--declaration', declarationPath, '--environment', environment, ...extra], values, { cwd: root, localOnlyKeys, ...more });
+  // Keep confirmed creation events across deploy and the independent health call.
+  const created = [];
+  let step = 'deploy', deployed;
+  try {
+   if (options.remove) {
+    step = 'remove';
+    const result = await owner('remove');
+    store.report(`Removed ${result.removed.join(', ') || 'nothing (already gone)'}; read back: none of them remains.`);
+    return { removed: result.removed, deployed: false };
+   }
+   if (change.length) {
+    step = 'secrets';
+    const binding = options.setSecret ?? options.unsetSecret;
+    await owner('secret', [options.setSecret ? '--set' : '--unset', binding]);
+    store.report(`${options.setSecret ? `Set ${binding}` : `Removed ${binding}`} on this environment's Worker and recorded its new version; the next ${again} updates it.`);
+    return { binding, present: Boolean(options.setSecret), deployed: false };
+   }
+   deployed = await owner('deploy', [], env, { notice: line => store.report(line), onCreated: resource => created.push(redaction.redact(resource)) });
+   const sent = supplied.filter(name => deployed.sentSecrets.includes(name));
+   if (sent.length) store.report(`rer supplied ${sent.join(', ')} from the local setup owner and fresh generated values.`);
+   step = 'health';
+   await owner('health');
+   step = 'claim owner';
+   const linked = token => linkDependencies?.(deployed.origin, token);
+   const claimed = await claimHostedOwner({ hook: lifecycle.hooks?.owner, setupManifest, declaration, deployed, env, supplied, addSecret: value => redaction.addSecrets([value]),
+    secret: (extra, values) => owner('secret', extra, values), beforeClaim: linked });
+   // A seed that claims its owner its own way links with the token it was given.
+   if (claimed === undefined) await linked(env[declared(claim?.tokenField ?? 'SETUP_TOKEN')?.environment]);
+   // The app claims the OWNER_EMAIL the Worker holds: the local one only when this run uploaded it.
+   const email = declared(claim?.emailField);
+   const named = !email ? '' : deployed.sentSecrets.includes(email.binding) && env[email.environment] ? ` (${env[email.environment]})` : ` (the ${email.binding} already set on the Worker)`;
+   if (claimed) store.report(`${claimed === 'claimed' ? 'Claimed the hosted owner' : 'The hosted owner was already claimed and was kept'}${named}; the one-time setup token was used and removed. Sign in by email at ${deployed.origin}.`);
+   return { deployed: true, origin: deployed.origin, ...(claimed ? { owner: claimed } : {}), dependenciesLinked: true };
+  } catch (error) {
+   if (error instanceof RerError) throw error;
+   const { commandFailure } = await shared('failures.mjs');
+   throw commandFailure(failureText({ error, step, created, again, retry, secretChange: Boolean(change.length && !options.remove), deployed, redact: redaction.redact }));
+  }
  }, { declaration: declarationPath });
 }
+
+// The failing step, its redacted cause, what this run created and the command that continues.
+function failureText({ error, step, created, again, retry, secretChange, deployed, redact }) {
+ const diagnostic = deployDiagnostic(error, redact);
+ const code = diagnostic?.code ?? (/^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? redact(error.message) : 'deploy-failed');
+ const at = step === 'deploy' ? diagnostic?.step ?? 'prepare deploy' : step;
+ const input = /^missing-secret-([A-Z][A-Z0-9_]*)$/.exec(code)?.[1];
+ if (input) return `Deploy needs ${input}, which the deploy declaration lists as a secret and the Worker does not hold it. Set ${input} in the environment or in an --env-file file (an owned 0600 file of KEY=VALUE lines), then run the same command again. Nothing was uploaded.${created.length ? ` Resources created this attempt: ${created.join(', ')}.` : ''}`;
+ if (code === 'remove-incomplete') return `Removal stopped with ${error.remaining.join(', ')} still present${error.failed.length ? ` (${error.failed.map(item => `${item.resource}: ${item.code}`).join('; ')})` : ''}. Removed: ${error.removed.join(', ') || 'nothing'}. An R2 bucket must be empty before it can be deleted. Run ${again} --remove --yes again to finish.`;
+ if (code === 'nothing-to-remove') return `This checkout has no rer deployment record for this environment, so --remove deletes nothing. Run it from the checkout that deployed it.`;
+ if (code === 'owner-claim-failed') return `The application is deployed at ${deployed?.origin}, but claiming its owner failed: ${redact(String(error.cause))}. The setup token is still on the Worker; run ${again} again to retry the claim.`;
+ const resource = diagnostic?.resource ?? (error.resource ? redact(String(error.resource)) : undefined);
+ const lines = [`Deploy failed at ${at}: ${code}${resource ? ` (${resource})` : ''}${diagnostic?.providerCodes?.length ? ` (provider ${diagnostic.providerCodes.join(', ')})` : ''}.`];
+ if (diagnostic?.output && diagnostic.output !== '(no provider output)') lines.push(`First redacted output lines:\n${diagnostic.output}`);
+ lines.push(`Resources created this attempt: ${created.join(', ') || 'none'}.`);
+ lines.push(recovery({ code, at, resource, again, retry, secretChange }));
+ return lines.join('\n');
+}
+
+function recovery({ code, at, resource, again, retry, secretChange }) {
+ const remove = `${again} --remove --yes`, removing = retry === remove;
+ if (code === 'owned-resource-replaced' || code === 'resource-name-collision') return `rer refuses to change a resource it did not create or that was replaced after it did; nothing was changed. Choose another --environment name, or remove the other resource yourself.`;
+ // A lost create answer: the resource may exist, and rer cannot prove it made it.
+ if (resource && (code === 'uncertain-resource-create' || code === 'provider-transport-failed' && at.startsWith('create '))) {
+  if (resource.startsWith('worker:')) return `Possibly created: ${resource}. The answer to its first upload was lost and the live Worker does not match the build rer sent, so rer cannot prove it is its own. Deploy the same commit again to recover it, or inspect it in the Cloudflare dashboard: if it is the Worker from the interrupted run and its Durable Object data is disposable, delete it, then run ${retry} again.`;
+  return `Possibly created: ${resource}. The provider's answer to its create was lost, so rer cannot prove it made it. Inspect it in the Cloudflare dashboard: if it exists and is the empty one from the interrupted run, delete it, then run ${retry} again.${removing || resource.startsWith('queues:') ? '' : ` Or run ${remove}: it deletes it once it confirms it is empty, together with everything else this environment created.`}`;
+ }
+ if (code === 'uncertain-resource-not-empty') return `Possibly created: ${resource}, but it holds data, so it may not be the one rer's interrupted run made and rer will not delete it. Inspect it in the Cloudflare dashboard; delete it yourself only if its data is disposable, then run ${retry} again.`;
+ if (code === 'uncertain-resource-unverifiable') return `Possibly created: ${resource}. rer cannot read whether a queue holds messages, so it will not delete it. Inspect it in the Cloudflare dashboard: if it is the empty one from the interrupted run, delete it, then run ${retry} again.`;
+ if (code === 'changed-or-uncertain-migration-history') return `${resource ?? 'A D1 database'} holds a migration rer started but could not confirm, or one changed since it was applied; rer never retries or guesses a migration. Inspect it in the Cloudflare dashboard: if it is the empty one from this interrupted first deploy, delete it with ${remove} (that deletes everything this environment created), then run ${again} again. If it holds data, resolve the interrupted migration by hand first (deploy-kit README, Migration safety).`;
+ if (removing) return `Fix the cause, then run ${retry} again.`;
+ if (secretChange) return `Fix the cause, then run ${retry} again; a plain ${again} does not make this change.`;
+ return `Fix the cause, then run ${again} again: it continues with what was created. To delete what this environment created instead: ${remove}.`;
+}

package/cli/detached-server.mjs

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { open, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { shared } from './shared.mjs';
+import { ready } from './managed-server.mjs';
+import { RerError } from './errors.mjs';
+
+// The actual dispatcher owns the server, registry and shutdown. Only its
+// lifetime changes: its parent follows private JSON events until readiness,
+// then leaves that process serving. A failed/interrupted start stops its child.
+export async function detachedServer(options, argv, out) {
+ const {privateDirectory} = await shared('private-files.mjs');
+ const directory = await privateDirectory(options.cwd,['.rer','local']);
+ const log = join(directory,`${options.verb}-launch-${randomUUID()}.log`), handle = await open(log,'wx',0o600);
+ const args = argv.filter(arg => !['--detach','--foreground','--json'].includes(arg));
+ let child, exit, spawnError, keep = false;
+ const stop = () => child?.kill('SIGTERM');
+ for (const signal of ['SIGINT','SIGTERM']) process.once(signal,stop);
+ try {
+  child = spawn(process.execPath,[fileURLToPath(new URL('../bin/rer.mjs',import.meta.url)),...args,'--foreground','--json'], {cwd:options.cwd, env:process.env, detached:true, stdio:['ignore',handle.fd,handle.fd]});
+  child.once('error',error => {spawnError=error;exit=1;});
+  child.once('exit',(code,signal) => {exit=code ?? (signal ? 128 : 1);});
+  await handle.close();
+  let offset=0, pending='', failure;
+  for (;;) {
+   const bytes = await readFile(log), text = bytes.subarray(offset).toString('utf8'); offset=bytes.length;
+   pending += text;
+   const lines=pending.split('\n');pending=lines.pop();
+   for (const line of lines) {
+    let event; try { event=JSON.parse(line); } catch { continue; }
+    if (event.event==='error') failure=event;
+    if (event.event==='ready') {
+     keep=true;child.unref();
+     const dev = event.openUrl ? {openUrl:event.openUrl,identity:options.verb === 'dev' && !options.login,signedInAs:event.signedInAs,ownerLeft:options.verb === 'dev' && !options.login && event.signedInAs === null} : undefined;
+     ready(out,event.url,dev,options.json,Boolean(event.signInUrl),event.siteUrl);
+     return 0;
+    }
+    if (event.event==='waiting' || event.event==='warning') out.event(event.event,event);
+   }
+   if (exit!==undefined) throw new RerError(failure?.code ?? 'command_failed',failure?.message ?? `The ${options.verb} server stopped before readiness (${spawnError?.code ?? exit}); inspect ${log}.`,failure?.exitCode ?? (exit || 1));
+   await delay(200);
+  }
+ } finally {
+  await handle.close().catch(() => {});
+  for (const signal of ['SIGINT','SIGTERM']) process.off(signal,stop);
+  if (!keep) stop();
+ }
+}

package/cli/door.mjs

@@ -36,7 +36,7 @@ export const doorChallengeHeader = 'x-rer-door-challenge';
 export const doorIdentityPath = '/__rer/door/identity';
 export const doorDefaults = Object.freeze({ serverLimit: 10, idleSeconds: 43200 });
 
-export const doorDirectory = (env = process.env) => resolve(env.RER_DOOR_DIR ?? join(userInfo().homedir, '.rer/door'));
+export const doorDirectory = (env = process.env) => resolve(env.RER_DOOR_DIR ?? join(env.HOME || userInfo().homedir, '.rer/door'));
 export const doorOrigin = (name, port) => `http://${name}.localhost:${port}`;
 export const doorHost = (name, port) => `${name}.localhost:${port}`;
 

package/cli/hosted-output.mjs

@@ -1,4 +1,4 @@
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, realpath } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
 import { join, resolve, extname } from 'node:path';
@@ -114,7 +114,7 @@ export async function checkHostedOutput(root, options) {
  } finally { await hosted.close(); }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (process.argv[1] && await realpath(new URL(import.meta.url)) === await realpath(process.argv[1])) {
  try { console.log(JSON.stringify(await checkHostedOutput(resolve(process.argv[2] ?? '.'), { declaration: process.argv[3] }))); }
  catch (error) { console.error(error.message); process.exitCode = 1; }
 }

package/cli/hydration/check.mjs

@@ -7,7 +7,7 @@
 // is replaced, an intro replays, a frame loses a section, recovery is noisy or
 // uncounted, or a hydrated page's document lacks Cache-Control: no-transform.
 import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { realpath } from 'node:fs/promises';
 import { RerError } from '../errors.mjs';
 import { hostedServer, launchChromium, originServer, pool, runLoad } from './browser.mjs';
 import { cloudflareRewrite, describeCase, planCases, selectPages } from './cases.mjs';
@@ -90,7 +90,7 @@ async function declaredPages(root) {
  catch { return {}; }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (process.argv[1] && await realpath(new URL(import.meta.url)) === await realpath(process.argv[1])) {
  const args = process.argv.slice(2), flag = name => { const at = args.indexOf(name); return at < 0 ? undefined : args.splice(at, 2)[1]; };
  const origin = flag('--origin'), pages = flag('--pages')?.split(',').filter(Boolean), details = args.includes('--details');
  const root = resolve(args.find(arg => !arg.startsWith('--')) ?? '.'), declared = await declaredPages(root);