@runeditrun/rer 0.2.1 → 0.2.4

package/cli/deploy-owner.mjs

@@ -0,0 +1,76 @@
+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
+// 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) 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, recordClaim, inspect, store, signal, fetch = globalThis.fetch }) {
+ const claim = setupManifest?.steps?.find(step => step.type === 'owner-claim');
+ 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) { 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);
+  // The secret controller confirms readiness of the full new version identity.
+  await secret(['--set', tokenKey], { ...env, [item.environment]: token });
+ }
+ 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 {
+   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` : ''}`);
+ return retire(outcome);
+}
+
+function ownerFailure(cause) {
+ const error = new Error('owner-claim-failed'); error.cause = cause; return error;
+}

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.'}`);
+}

package/cli/deploy.mjs

@@ -1,24 +1,36 @@
 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, deployAgain } from './deploy-inputs.mjs';
+import { claimHostedOwner } from './deploy-owner.mjs';
+import { mutationReadinessFailure } from './deploy-readiness.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 = deployAgain(options);
+  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.`);
+  // A dry run reads the settings file too, so a refused key fails here and not only on the real deploy.
+  if (options.dryRun && options.envFile) await deployEnvironment({ root, options, declaration, localOnlyKeys });
+  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,24 +40,94 @@ export function ownerDeploy(declarationPath, lifecycle) {
    store.report('deploy: dry run complete; no deployment occurred and no provider request was made.');
    return { dryRun: true, deployed: false };
   }
+  const { env, supplied } = await deployEnvironment({ root, options, declaration, setupManifest, settings: lifecycle.settings, localOnlyKeys });
   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.');
+  if (names.some(name => !env[name]?.trim())) throw missing('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required. See the deploy-kit owner-account instructions.');
   const { main } = await import('../modules/deploy-kit/owner-cli.mjs');
-  const argv = ['deploy', '--declaration', declarationPath, '--environment', environment];
-  const {createRedaction,credentialValues} = await shared('redaction.mjs');
+  const { createRedaction, credentialValues } = await shared('redaction.mjs');
   const redaction = createRedaction();
-  redaction.addSecrets([...credentialValues(process.env),process.env.CLOUDFLARE_ACCOUNT_ID,...(declaration.secrets ?? []).map(item=>process.env[item.environment]).filter(Boolean)]);
+  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 {
-   const result = await main(argv, process.env, { cwd: root, localOnlyKeys, notice: line => store.report(line), onCreated: resource => created.push(redaction.redact(resource)) });
-   await main(['health', ...argv.slice(1)], process.env, { cwd: root, localOnlyKeys });
-   return { deployed: true, origin: result.origin };
+   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, recorded its new version and verified hosted readiness.`);
+    return { binding, present: Boolean(options.setSecret), deployed: false };
+   }
+   store.report(`Deploying the ${environment} environment to your Cloudflare account.`);
+   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');
+   store.report(`Your application is live on your Cloudflare account at ${deployed.origin}.`);
+   step = 'claim owner';
+   const { liveSecrets, retiredSecrets, ownerClaim } = await owner('inspect');
+   const linked = token => linkDependencies?.(deployed.origin, token);
+   const claimed = await claimHostedOwner({ hook: lifecycle.hooks?.owner, setupManifest, declaration, deployed: { ...deployed, liveSecrets, retiredSecrets, ownerClaim }, env, supplied, addSecret: value => { redaction.addSecrets([value]); store.addSecrets?.([value]); },
+    secret: (extra, values) => owner('secret', extra, values), beforeClaim: linked, recordClaim: outcome => owner('record-owner', ['--outcome', outcome]), inspect: () => owner('inspect'), store, signal });
+   // 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 removed. Sign in by email at ${deployed.origin}.`);
+   return { deployed: true, origin: deployed.origin, ...(claimed ? { owner: claimed } : {}), dependenciesLinked: true };
   } catch (error) {
-   const diagnostic = deployDiagnostic(error,redaction.redact);
-   const code = /^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? redaction.redact(error.message) : 'deploy-failed';
-   const {commandFailure} = await shared('failures.mjs');
-   throw commandFailure(`Deploy failed at ${diagnostic?.step ?? 'prepare deploy'}: ${diagnostic?.code ?? code}${diagnostic?.providerCodes?.length ? ` (provider ${diagnostic.providerCodes.join(', ')})` : ''}.\nFirst redacted output lines:\n${diagnostic?.output ?? '(no provider output)'}\nResources created this attempt: ${created.join(', ') || 'none recorded'}.`);
+   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 });
+ }, { declaration: declarationPath, managesHostedOwner: true });
+}
+
+// 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 readiness = mutationReadinessFailure(error, { again, redact });
+ if (readiness) return readiness;
+ 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-token-retirement-failed') return `The application is deployed at ${deployed?.origin}; owner ${error.owner}; setup token retirement failed (${redact(String(error.cause))}). Run ${again} --unset-secret ${error.tokenKey ?? 'SETUP_TOKEN'} using the same environment credentials, or run ${again} again to finish.`;
+ if (code === 'owner-claim-failed') return `The application is deployed at ${deployed?.origin}, but claiming its owner failed: ${redact(String(error.cause))}. Owner claim and setup token retirement are not confirmed; run ${again} again using the same environment credentials to finish.`;
+ const resource = diagnostic?.resource ?? (error.resource ? redact(String(error.resource)) : undefined);
+ if (code === 'resource-not-listed') return `Deploy stopped at ${at}: ${resource} was created, but Cloudflare's account listing still does not show it after two minutes. Nothing was uploaded.\nResources created this attempt: ${created.join(', ') || 'none'}.\nRun ${again} again once the listing catches up: it reuses ${resource}. To delete what this environment created instead: ${again} --remove --yes.`;
+ 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

@@ -35,7 +35,7 @@ export async function detachedServer(options, argv, out) {
     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);
+     ready(out,event.url,dev,options.json,Boolean(event.signInUrl),event.siteUrl,event.demo);
      return 0;
     }
     if (event.event==='waiting' || event.event==='warning') out.event(event.event,event);

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/export.mjs

@@ -6,7 +6,7 @@ import { cliVersion } from './version.mjs';
 
 // Copy whole maintained source/tooling directories. Python publication scans
 // load sibling modules and data dynamically; they belong in the inventory too.
-export const sourceRoots = ['bin/rer.mjs', 'cli', 'modules/job-queue', 'modules/release', 'modules/deploy-kit', 'modules/container', 'modules/integrations/core', 'modules/mail', 'modules/ai', 'modules/portability', 'modules/erasure', 'modules/dependencies', 'modules/operator-auth', 'modules/owner-claim', 'operations', 'scripts/publish-check', 'scripts/publish-check.mjs', 'composition/git-source.mjs', 'edition-authoring/manifest.mjs', 'edition-authoring/files.mjs'];
+export const sourceRoots = ['bin/rer.mjs', 'cli', 'modules/job-queue', 'modules/release', 'modules/deploy-kit', 'modules/container', 'modules/demo-host', 'modules/integrations/core', 'modules/mail', 'modules/ai', 'modules/portability', 'modules/erasure', 'modules/dependencies', 'modules/operator-auth', 'modules/owner-claim', 'operations', 'scripts/publish-check', 'scripts/publish-check.mjs', 'composition/git-source.mjs', 'edition-authoring/manifest.mjs', 'edition-authoring/files.mjs'];
 export async function inventory(base, roots = sourceRoots) {
  const files = [];
  async function walk(path) {

package/cli/hosted-output.mjs

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url';
 import { RUN_WORKER_FIRST } from '../modules/deploy-kit/render.mjs';
 import { publicAssetPaths } from '../modules/deploy-kit/artifact.mjs';
 import { migrate } from '../modules/container/migrations.mjs';
+import { readMigrationRewrites, withRewrites } from '../modules/deploy-kit/migrations.mjs';
 import { RerError } from './errors.mjs';
 
 // Serve the production build the way rer deploy hosts it (assets behind the
@@ -76,7 +77,7 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
     const sql = await readFile(join(directory, name), 'utf8');
     plan.push({ name, sql, sha256: createHash('sha256').update(sql).digest('hex'), statements: split(sql) });
    }
-   await migrate(await mf.getD1Database(item.binding, 'app'), plan);
+   await migrate(await mf.getD1Database(item.binding, 'app'), withRewrites(plan, await readMigrationRewrites(root), { partial: true }));
   }
  } catch (error) { await mf.dispose(); throw error; }
  return { client, identity, origin: ORIGIN, close: () => mf.dispose(),

package/cli/inspect.mjs

@@ -7,7 +7,7 @@ import { aliases, pins, requiredHooks, serverDefaults, verbs, releaseFlags } fro
 import { runningVersion } from './version.mjs';
 import { contained, readPackage } from './project.mjs';
 import { shared } from './shared.mjs';
-import { missing, RerError } from './errors.mjs';
+import { missing } from './errors.mjs';
 import { projectNodePin } from './node-runtime-discovery.mjs';
 import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { localAiDiagnostics } from './ai-local.mjs';
@@ -18,6 +18,7 @@ import { commandArgv, commandLine, declaredPackage, exactVersion, lockedPackage,
 import { vendoredCalls } from './package-calls.mjs';
 import { doorProtocol } from './door.mjs';
 import { savedOrigin } from './door-mode.mjs';
+import { probePnpm } from './pnpm-probe.mjs';
 
 // cliVersion: the rer version of the code answering (absent for a vendored copy
 // too old to record one). defaults: what a server start applies when the person
@@ -31,7 +32,16 @@ export async function describe(project) {
  };
  const capabilities = project.adapter?.verbs ?? {};
  return { contractVersion: 1, ...versioned, profile: 'first-party', defaults, pins: { node: pkg.engines?.node, pnpm: pkg.packageManager?.replace(/^pnpm@/, '') },
-  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects: verbs[verb]?.effects ?? 'Produce releases; keygen writes a public anchor and, on success, its private key to non-terminal stdout; sign writes a detached signature and prints (but does not execute) the GitHub upload command; receipt verifies against local anchors offline.' }])),
+  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => {
+   const adapterEffects = capability.effects;
+   const operationsEffects = project.descriptor.commands?.[verb]?.effects;
+   const effects = typeof adapterEffects === 'string' && adapterEffects.trim()
+    ? adapterEffects
+    : typeof operationsEffects === 'string' && operationsEffects.trim()
+     ? operationsEffects
+     : verbs[verb]?.effects ?? 'Produce releases; keygen writes a public anchor and, on success, its private key to non-terminal stdout; sign writes a detached signature and prints (but does not execute) the GitHub upload command; receipt verifies against local anchors offline.';
+   return [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects }];
+  })),
   aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === commandLine(verb, declaredPackage(pkg) !== undefined))),
   local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), origin: await savedOrigin(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
   // This pin serves a checkout through the machine's front door (rer door).
@@ -137,25 +147,20 @@ async function packageClauses(root, pkg) {
 export async function tools(root, store, signal) {
  const node = await projectNodePin(root);
  if (node && process.versions.node !== node) throw missing(`Node ${node} is required. Run it with rer, with automatic project runtime selection enabled.`);
- const found = await probePnpm(root, store, signal).catch(error => { if (signal?.aborted) throw error; return null; });
- if (found === pins.pnpm) return;
- const { cachedPnpm, downloadPnpm } = await import('./pnpm-runtime.mjs');
- let directory = await cachedPnpm(pins.pnpm);
- if (!directory) {
-  store.report?.(`Fetching pnpm ${pins.pnpm} for this project (PATH has ${found ? `pnpm ${found}` : 'no pnpm'}); rer keeps it in its own cache.`);
-  try { directory = await downloadPnpm(pins.pnpm, signal); }
-  catch (error) { if (signal?.aborted || error instanceof RerError) throw error; throw missing(`pnpm ${pins.pnpm} is required and could not be fetched (${error.message}). Check the connection, or install pnpm ${pins.pnpm} yourself.`); }
- }
- usePnpm(directory);
- if (await probePnpm(root, store, signal) !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. The pnpm rer provides did not report it; install pnpm ${pins.pnpm} yourself.`);
+ const { ensureProjectPnpm } = await import('./project-pnpm.mjs');
+ await ensureProjectPnpm(root, { signal, store, report: text => store.report?.(text) });
 }
-const usePnpm = directory => { process.env.PATH = [dirname(process.execPath), directory, process.env.PATH].filter(Boolean).join(delimiter); };
+const usePnpm = directory => { process.env.PATH = [directory, dirname(process.execPath), process.env.PATH].filter(Boolean).join(delimiter); };
 
 export async function doctor(project, store, signal) {
  const { inspectOperations } = await import('../operations/operations.mjs');
  const diagnostic = await inspectOperations(project.root);
  const { localVariables } = await shared('local/environment.mjs');
- let values = {}, pnpm, stateValid = true;
+ let values = {}, pnpm, expectedPnpm, pnpmIssue, stateValid = true;
+ if (project.profile === 'first-party') {
+  try { expectedPnpm = await (await import('./project-pnpm.mjs')).projectPnpmPin(project.root); }
+  catch (error) { pnpmIssue = error.message; }
+ }
  if (project.profile === 'first-party') {
   const { selectLocalState } = await shared('local/state.mjs');
   try { await selectLocalState(project.root, project.adapter.state); } catch { stateValid = false; }
@@ -170,8 +175,8 @@ export async function doctor(project, store, signal) {
   } catch {}
   try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; }
   // A pnpm rer already provides counts; doctor never fetches one.
-  if (pnpm !== pins.pnpm) {
-   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(pins.pnpm).catch(() => undefined);
+  if (expectedPnpm && pnpm !== expectedPnpm) {
+   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(expectedPnpm).catch(() => undefined);
    if (directory) { usePnpm(directory); try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; } }
   }
  }
@@ -181,27 +186,14 @@ export async function doctor(project, store, signal) {
  const keys = localSettingKeys(project);
  const inputs = project.profile === 'first-party' ? requiredLocalSettings(project, values) : [];
  const warnings = project.profile === 'first-party' ? await cacheWarnings(project.root) : [];
- return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (process.versions.node === expectedNode && pnpm === pins.pnpm)),
+ return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (Boolean(expectedPnpm) && process.versions.node === expectedNode && pnpm === expectedPnpm)),
   node: { actual: process.versions.node, expected: expectedNode },
-  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: pins.pnpm } : undefined,
+  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: expectedPnpm ?? null, ...(pnpmIssue ? { issue: pnpmIssue } : {}) } : undefined,
   ai: { issues: aiIssues },
   missingInputs: [...new Set([...diagnostic.missingEnvironment, ...inputs])],
   sources: project.descriptor.environmentSources ?? {}, state: { path: project.adapter?.state, safe: stateValid }, scope: 'local-inputs-only' };
 }
 
-// Diagnostics and execution use the same identity-checked process custody.
-// Exit starts cleanup even if a descendant still holds the output pipes.
-async function probePnpm(root, store, signal) {
- const probeSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean));
- const child = store.spawn('Checking pinned pnpm', 'pnpm', ['--version'], { cwd: root, signal: probeSignal });
- let version = '';
- child.stdout.on('data', chunk => { version = (version + chunk).slice(-1024); });
- const code = await new Promise(resolve => { child.once('error', () => resolve(null)); child.once('exit', code => resolve(code)); });
- await store.stop(child);
- if (probeSignal.aborted || code !== 0) throw missing('The pinned pnpm version probe failed. Select the documented tool.');
- return version.trim();
-}
-
 // SC-05: a seed declaring devIdentity loads the dev layer only from a local-only
 // entry that its dev configuration names, never from the deployed main, lets
 // rer build scan its output, and keeps one end-to-end email-link test.

package/cli/lifecycle.mjs

@@ -17,9 +17,19 @@ import { ensureDevKey, readDevKey, refuseDevLayerOutput, openUrl, DEV_KEY_HEADER
 import { announceDoorRoute, routeRunning, verifyDoorFor } from './door-mode.mjs';
 
 export async function runCommand(project, options, out) {
+ if (options.verb === 'deploy' && !options.site && !options.demo) {
+  const { validateDeployOptions } = await import('./deploy-command.mjs');
+  validateDeployOptions(options);
+  const { withDeployEnvironment } = await import('./deploy-inputs.mjs');
+  return withDeployEnvironment(project.root, options, redaction => runLifecycle(project, options, out, redaction));
+ }
+ return runLifecycle(project, options, out);
+}
+
+async function runLifecycle(project, options, out, deployRedaction) {
  if(project.profile==='first-party'&&['dev','preview'].includes(options.verb))return (await import('./managed-server.mjs')).managedServer(project,options,out);
  const cancellation = new AbortController(), signal = cancellation.signal;
- let termination, operation, store, temporary, proxy;
+ let termination, operation, store, temporary, proxy, failed = false;
  const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { if (!termination) { termination = name; cancellation.abort(name); } }]));
  for (const [name, handler] of handlers) process.on(name, handler);
  try {
@@ -59,6 +69,7 @@ export async function runCommand(project, options, out) {
   const state = { logs: [] };
   store = await createCommands(directory, state, { terminal: text => out.progress(text), onWaiting: options.json ? details => out.event('waiting', details) : undefined, queue: ['install','setup','build','verify','deploy','export','import'].includes(options.verb)?{verb:options.verb,originalCI:process.env.CI==='true'}:undefined });
   store.state = state;
+  if (deployRedaction) store.addSecrets?.(Object.values(process.env).filter(value => value && deployRedaction.redact(value) !== value));
   store.setupManifest = project.setupManifest;
   store.step = async label => { state.step = store.redact(label); store.report(label); };
   store.phase = async phase => { state.phase = phase; };
@@ -69,8 +80,11 @@ export async function runCommand(project, options, out) {
   const adapter = project.adapter;
   // The run site: static pages built from edition identity, never the app build.
   if (options.site) return await (await import('./site.mjs')).siteCommand(project, options, store, signal, out);
+  // The hosted demo: a front Worker and the seed's container image on demo.<domain>.
+  if (options.verb === 'deploy' && options.demo) return await (await import('./demo-host.mjs')).demoHostCommand(project, options, store, signal, out, operation);
   if (options.verb === 'install') {
-   await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...process.env, CI: 'true' } }); return {};
+   const { dependencyEnvironment } = await shared('dependency-environment.mjs');
+   await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...dependencyEnvironment(), CI: 'true' } }); return {};
   }
   if (options.verb === 'verify') {
    const target = adapter.verify;
@@ -85,9 +99,8 @@ export async function runCommand(project, options, out) {
   if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
   if (options.verb === 'deploy') {
    if (typeof adapter.deploy !== 'function') throw refuse('Owner-account deploy declaration is missing.');
-   const deployed = await adapter.deploy({ root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity) });
-   if(deployed.deployed && !options.dryRun) await linkDependencies({project,input:await savedSetupAnswers(project,project.setupSeed.model),origin:deployed.origin,store,signal,appSetupToken:process.env[project.setupManifest?.steps.find(step=>step.type==='owner-claim')?.tokenField??'SETUP_TOKEN']});
-   return deployed;
+   const link = async (origin, appSetupToken) => linkDependencies({project,input:project.setupSeed?await savedSetupAnswers(project,project.setupSeed.model):undefined,origin,store,signal,appSetupToken});
+   return await (await import('./deploy-command.mjs')).deployCommand({ adapter, root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity), setupManifest: project.setupManifest, linkDependencies: link });
   }
   // Setup writes the checkout's dev key; its temporary app and the CLI's own
   // outbox reads present it. Captured logs redact it.
@@ -112,8 +125,10 @@ export async function runCommand(project, options, out) {
   if (['setup', 'build'].includes(options.verb)) await refuseDevLayerOutput(project.root, adapter.devIdentity);
   const url = selected?.url, signInUrl = url ? url + '/__dev/outbox' : undefined;
   if (options.verb === 'setup') {
-   await linkDependencies({project,input,origin:url,store,signal});
-   if(project.setupManifest?.dependencies?.length) {
+   // Only a connected provider leaves first setup open; a native claim with
+   // every optional dependency unanswered has already closed it.
+   const {connected}=await linkDependencies({project,input,origin:url,store,signal});
+   if(connected.length) {
     const proof=await localCliSessionProof(project);
     store.addSecrets?.([proof]);
     const completed=await appFetch(url+'/auth/setup-complete',{method:'POST',headers:{Origin:url,'Content-Type':'application/json','x-rer-local-cli':proof},body:'{}',signal});
@@ -135,10 +150,18 @@ export async function runCommand(project, options, out) {
   } else if (options.verb !== 'build') throw refuse('The requested first-party capability is unavailable.');
   return {};
  } catch (error) {
+  failed = true;
   if (error instanceof RerError) throw error;
   throw await lifecycleError(error, store);
  } finally {
-  await store?.closeCommands(); await proxy?.close(); await operation?.release();
+  // Every closer runs: one that fails must not leave the job-queue policy socket
+  // listening (the process would never exit) or the local operation held, and
+  // must not turn a finished command into a failure or hide the real one.
+  const unclosed = [];
+  for (const close of [() => store?.closeCommands(), () => proxy?.close(), () => operation?.release()]) {
+   try { await close(); } catch (error) { unclosed.push(store?.redact?.(String(error?.message)) ?? 'unknown cause'); }
+  }
+  if (unclosed.length && !failed) out.progress(`Local cleanup could not confirm that every helper process stopped (${unclosed.join('; ')}). The ${options.verb} itself finished.\n`);
   if (temporary) await rm(temporary, { recursive: true, force: true });
   for (const [name, handler] of handlers) process.removeListener(name, handler);
   if (termination) throw new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143);

package/cli/local.mjs

@@ -73,6 +73,13 @@ export async function reset(project, options, out) {
  await refuseLegacyProcess(project,{reset:true});
  const { strandedOriginals } = await shared('local/recovery.mjs');
  if ((await strandedOriginals(project.root)).length) throw refuse('An interrupted build holds private settings. Run rer build to recover them before reviewing reset.');
+ // The seed's own safety check (legacy data it still has to recover, for
+ // example) runs before the inventory and confirmation; --yes cannot skip it.
+ const preflight = project.adapter.resetPreflight;
+ if (preflight !== undefined) {
+  if (typeof preflight !== 'function') throw refuse('The seed adapter declares a reset preflight that is not a function.');
+  try { await preflight({ root: project.root }); } catch (error) { throw refuse(`Reset refused by the seed's preflight: ${error?.message || 'no reason given'}`); }
+ }
  const declared = project.adapter.settings ?? [];
  for (const path of declared) if (!/^\.dev\.vars(?:\.previous)?$|^data\/[a-zA-Z0-9_-]+\.json$/.test(path)) throw refuse('Generated settings inventory is unsafe; declare specific private settings files.');
  const paths = [...new Set(['.wrangler/state', '.rer/local', '.seed/installer', ...declared])];

package/cli/main.mjs

@@ -27,7 +27,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (project.profile === 'independent' && !['describe', 'check', 'doctor'].includes(options.verb)) options = parse(argv, process.cwd(), { independent: true });
   else if (options.forwarded.length) throw invalid('First-party commands accept only the documented flags, without forwarded arguments.');
   out = output(options);
-  if (project.profile === 'first-party' && options.detach && ['dev','preview'].includes(options.verb)) return (await import('./detached-server.mjs')).detachedServer(options, argv, out);
+  if (project.profile === 'first-party' && options.detach && ['dev','preview'].includes(options.verb)) return await (await import('./detached-server.mjs')).detachedServer(options, argv, out);
   if (options.verb === 'describe') { const result = await describe(project); out.human(options.json ? JSON.stringify(result) : JSON.stringify(result, null, 2)); return 0; }
   if (options.verb === 'check') {
    const result = await check(project, options.profile);