@runeditrun/rer 0.2.2 → 0.2.4

package/README.md

@@ -182,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,

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/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', '--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.'],
+ 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

@@ -31,3 +31,25 @@ export async function deployEnvironment({ root, options, declaration, setupManif
  }
  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; }
+}

package/cli/deploy-owner.mjs

@@ -1,3 +1,4 @@
+import { observeOwner } from './deploy-observation.mjs';
 import { randomBytes } from 'node:crypto';
 
 // After a healthy deploy, the hosted app's first owner is the setup owner: rer
@@ -5,55 +6,69 @@ import { randomBytes } from 'node:crypto';
 // (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.
+// token (environment or --env-file) and inspection has not found it absent. A
+// seed with its own owner step function runs its own bootstrap; identity-provider
+// linking runs before retirement.
 // `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;
+export async function claimHostedOwner({ hook, setupManifest, declaration, deployed, env, supplied = [], secret, addSecret, beforeClaim, recordClaim, inspect, store, signal, fetch = globalThis.fetch }) {
  const claim = setupManifest?.steps?.find(step => step.type === 'owner-claim');
- if (claim?.mode === 'idp') return undefined;
+ if (!hook || !['object', 'function'].includes(typeof hook) || Array.isArray(hook) || !deployed.origin) {
+  if (declaration.secrets?.some(item => item.binding === (claim?.tokenField ?? 'SETUP_TOKEN'))) throw ownerFailure('the owner bootstrap hook is unavailable');
+  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);
+ if (!item) { if (claim) throw ownerFailure('the deploy declaration does not name the owner setup token secret'); return undefined; }
+ const retire = async outcome => {
+  try { await recordClaim?.(outcome); await secret(['--unset', tokenKey], env); }
+  catch (cause) {
+   if (cause.secretChange) { cause.owner = outcome; cause.tokenKey = tokenKey; cause.ownerFinalization = true; throw cause; }
+   const error = new Error('owner-token-retirement-failed'); error.owner = outcome; error.tokenKey = tokenKey; error.cause = cause.message; throw error; }
+  return outcome;
+ };
+ // Only a recorded successful bootstrap proves ownership; --unset-secret alone
+ // can retire a token while the application is still unclaimed. A legacy hook
+ // can re-upload a spent token, so always remove it again after ownership proof.
+ if (deployed.owner || deployed.ownerClaim) { await beforeClaim?.(); return retire(deployed.owner ?? 'kept'); }
+ // Older direct callers only recorded token retirement, without an ownership
+ // record or live-secret inspection. Keep their completed deploys idempotent.
+ if (!deployed.liveSecrets && deployed.retiredSecrets?.includes(tokenKey)) return undefined;
+ const given = (!deployed.liveSecrets || deployed.liveSecrets.includes(tokenKey)) && 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 });
+  // The secret controller confirms readiness of the full new version identity.
+  await secret(['--set', tokenKey], { ...env, [item.environment]: token });
  }
- 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++) {
+ const linked = await beforeClaim?.(token);
+ if (claim?.mode === 'idp') {
+  if (!linked?.ownerClaimed || !['claimed', 'kept'].includes(linked.ownerOutcome)) throw ownerFailure('the identity provider has not confirmed the designated owner link');
+  return retire(linked.ownerOutcome);
+ }
+ if (typeof hook === 'function') {
+  const context = { origin: deployed.origin, vars: { ...env, [tokenKey]: token }, input: {}, store, signal, ownerClaim: claim, fail: () => ownerFailure('the seed owner hook failed') };
+  let observed;
   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);
+   if (deployed.observedOwner) await hook(context);
+   else await observeOwner({ paths: ['/auth/bootstrap', claim?.path].filter(Boolean), inspect, addSecret }, async claims => { await hook(context); observed = claims.at(-1)?.outcome; });
+  } catch (cause) { if (cause.message === 'owner-claim-failed') throw cause; throw ownerFailure(cause.message); }
+  // Function hooks can keep existing owners without returning a value. Observe
+  // their actual response, instead of assuming that a resolved promise claimed.
+  const outcome = context.ownerClaimed ?? observed ?? deployed.observedOwner?.();
+  if (!['claimed', 'kept'].includes(outcome)) throw ownerFailure('the seed owner hook did not confirm its bootstrap exchange');
+  return retire(outcome);
  }
+ const displayName = (typeof hook.displayName === 'function' ? hook.displayName({}) : undefined) || 'Owner';
+ let response, code = 'no code';
+ 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'); }
+ 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();
  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);
- }
+ return retire(outcome);
 }
 
 function ownerFailure(cause) {

package/cli/deploy-readiness.mjs

@@ -0,0 +1,16 @@
+// Mutation readiness errors carry confirmed state separately from the hosted
+// response. Only show that response through the command's existing redactor.
+export function mutationReadinessFailure(error, { again, redact }) {
+ if (!error.secretChange) return undefined;
+ const { binding, present } = error.secretChange;
+ const last = error.attempts?.at(-1);
+ const status = last?.status == null ? 'no HTTP response' : `HTTP ${last.status}`;
+ const first = redact(String(last?.body ?? '').split(/[\r\n]/, 1)[0]).slice(0, 256);
+ const state = error.ownerFinalization
+  ? `Owner ${error.owner === 'kept' ? 'already claimed and kept' : 'claimed'}; setup token retirement was applied and its new Worker version recorded.`
+  : `The secret change for ${binding} was applied and its new Worker version recorded.`;
+ const step = error.ownerFinalization ? 'owner claim/token retirement' : `secret change for ${binding}`;
+ const reason = /^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? error.message : 'health-check-failed';
+ const retirement = error.ownerFinalization || binding === 'SETUP_TOKEN' && !present;
+ return redact(`${state} Hosted readiness failed after ${step}. ${status} (${reason}).${first ? ` First response line: ${first}` : ''} Update the seed/app configuration to match the changed secrets and redeploy with ${again}. ${retirement ? 'If the app requires the spent setup token, remove that requirement from its configuration before redeploying; keep the recorded owner and token retirement.' : 'If the secret input was incorrect, correct it and apply the intended secret change again.'}`);
+}