@runeditrun/rer 0.1.1 → 0.2.1

package/global/launch/prepare.mjs

@@ -5,41 +5,73 @@
 // settings are never changed. An install or setup this launcher started and
 // that did not finish runs again on the next launch.
 import { realpath } from 'node:fs/promises';
-import { dispatcher } from '../checkout.mjs';
+import { dispatcher, pinnedPackage } from '../checkout.mjs';
 import { liveServers } from '../registry.mjs';
 import { checkCapacity, personEnvironment, pinPolicy } from './capacity.mjs';
+import { bringBackDoor, doorPlan } from './door.mjs';
+import { LaunchFailure } from './failure.mjs';
 import { describeCheckout, freePort, localOwner, needsInstall, setupNeeded } from './facts.mjs';
 import { claimPort, installState, setupState } from './state.mjs';
 import { runVerb } from './steps.mjs';
 import { localDefaults } from './local-defaults.mjs';
+import { installPinned } from './install-pinned.mjs';
 
 // The value given for a flag in the user's dev arguments.
 export const flagValue = (args, flag) => { const index = args.indexOf(flag); return index < 0 ? undefined : args[index + 1]; };
 
 // A worker passes the signal a stop aborts: no step starts after it, and the
-// step running then is signalled through `children`.
-export async function prepare({ root, args, env, report, directory, log, children, signal }) {
+// step running then is signalled through `children`. `doorStart`: the front
+// door is starting this checkout on a visit, which never installs or sets up;
+// an unprepared checkout is refused with the reason.
+export async function prepare({ root, args, env, report, directory, log, children, signal, doorStart = false }) {
+ // A checkout pinning the rer package whose node_modules lacks that version
+ // installs it first (after the same quick server-limit check: a pin with
+ // package mode has the person defaults); every step after this runs the
+ // pinned package's verbs.
+ let installed = false;
+ if (pinnedPackage(root)?.ready === false) {
+  if (doorStart) throw new LaunchFailure(3, `${root} is not installed, and the front door starts only prepared checkouts. Run rer dev in it once.`);
+  const current = await pinPolicy(root, 'package');
+  report({ phase: 'check', message: 'checking the server limit' });
+  const capacity = await checkCapacity(await realpath(root), { ...env, ...personEnvironment(env, args, current) }, current);
+  if (capacity.own) throw new LaunchFailure(3, `A server of ${root} is running, but its node_modules lacks the rer version it pins. Stop it with rer dev --stop, then run rer dev again.`);
+  report({ phase: 'install', message: 'installing dependencies' });
+  await recorded(directory, installState, () => installPinned(root, { env, output: text => log(text.trimEnd()), children, signal }));
+  installed = true;
+ }
  const checkout = await realpath(root), { mode, entry } = dispatcher(root);
  const described = await describeCheckout(root, entry, env, signal);
  const pin = await pinPolicy(root, mode, described);
  const added = personEnvironment(env, args, pin), childEnv = { ...env, ...added };
+ const plan = await doorPlan(described, args, env);
+ if (plan.note) report({ phase: 'note', message: plan.note });
  report({ phase: 'check', message: 'checking the server limit' });
  const capacity = await checkCapacity(checkout, childEnv, pin);
- if (capacity.own) return { entry, added, own: capacity.own };
+ if (capacity.own) { await bringBackDoor(plan, env, report); return { entry, added, own: capacity.own }; }
  const note = message => report({ phase: 'note', message });
  const step = (record, args, fields, env = childEnv) => recorded(directory, record, () => runVerb(entry, args, { root, env, note, log, children, signal }), fields);
  // Only this setup fills the seed's declared local defaults.
  const setupEnv = { ...childEnv, [localDefaults]: '1' };
- if (await needsInstall(root, await installState.read(directory))) {
+ const unprepared = what => new LaunchFailure(3, `${checkout} is not ${what}, and the front door starts only prepared checkouts. Run rer dev in it once.`);
+ if (!installed && await needsInstall(root, await installState.read(directory))) {
+  if (doorStart) throw unprepared('installed');
   report({ phase: 'install', message: 'installing dependencies' });
   await step(installState, ['install']);
  }
  const last = await setupState.read(directory), setup = await setupNeeded(root, described, last);
+ if (setup && doorStart) throw unprepared('set up');
  const host = flagValue(args, '--host'), hostArgs = host ? ['--host', host] : [];
  if (setup === 'resume') {
   // Saved settings hold an owner and origin; setup keeps them.
   report({ phase: 'setup', message: 'finishing this checkout\'s setup, keeping its saved owner and port' });
   await step(setupState, ['setup', ...hostArgs], {}, setupEnv);
+ } else if (setup === 'fresh' && plan.freshAtDoor) {
+  // With the door enabled, a fresh checkout is set up at its door origin.
+  const owner = localOwner(checkout);
+  report({ phase: 'setup', message: `setting up a local owner (${owner}) at its front-door address` });
+  await step(setupState, ['setup', '--owner-email', owner, '--door'], { owner, door: true }, setupEnv);
+  await bringBackDoor({ ...plan, atDoor: true }, env, report);
+  return { entry, added };
  } else if (setup === 'fresh') {
   // An interrupted setup resumes on the port it chose while that port is free.
   const owner = localOwner(checkout), explicit = flagValue(args, '--port');
@@ -50,6 +82,7 @@ export async function prepare({ root, args, env, report, directory, log, childre
   // The claim lasts until the server registers the port: the caller releases it.
   return { entry, added, release };
  }
+ await bringBackDoor(plan, env, report);
  return { entry, added };
 }
 

package/global/launch/render.mjs

@@ -3,7 +3,9 @@
 const elapsed = ms => { const s = Math.round(ms / 1000); return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`; };
 const quiet = 20000;
 
-export function printer({ json, login, stopHint }) {
+// `keyless` (a start by the front door, whose log this is): the ready lines
+// leave out the dev-key link, so the door's files never hold a key.
+export function printer({ json, login, stopHint, keyless = false }) {
  const started = Date.now();
  let current = 'preparing', last = Date.now();
  const event = (name, fields) => process.stdout.write(JSON.stringify({ version: 1, verb: 'dev', event: name, ...fields }) + '\n');
@@ -19,6 +21,7 @@ export function printer({ json, login, stopHint }) {
   heartbeat() { if (Date.now() - last >= quiet) progress('waiting', `still ${current} (${elapsed(Date.now() - started)}). Allow up to 10 minutes; if this command is stopped, run rer dev again to reattach.`); },
   // The dispatcher's ready event, as its own human ready lines.
   ready(ready, { log, pid }) {
+   if (keyless) { const { openUrl, ...rest } = ready; ready = rest; }
    if (json) { event('server', { pid, log }); process.stdout.write(JSON.stringify(ready) + '\n'); return; }
    const out = [`RER_READY ${ready.url}`];
    if (ready.openUrl && !login) {
@@ -29,6 +32,8 @@ export function printer({ json, login, stopHint }) {
     if (ready.openUrl) out.push(`RER_OPEN ${ready.openUrl}`);
     out.push(`Open ${ready.openUrl ? 'the last link on this computer (it carries the dev key; never share it)' : 'the outbox'}, choose the newest sign-in message and follow its link. No email was sent.`);
    }
+   // A seed with a run site: its static homepage, /run and docs, served locally.
+   if (ready.siteUrl) out.push(`RER_SITE ${ready.siteUrl}`);
    out.push(`The server keeps running in the background${pid ? ` (PID ${pid})` : ''}. Stop it with: ${stopHint}`);
    if (log) out.push(`Server log (private): ${log}`);
    process.stdout.write(out.join('\n') + '\n');

package/global/launch/steps.mjs

@@ -63,19 +63,24 @@ async function follow(path, from, onLine, stopped) {
 // Start `dev` detached into its own process group with its output in a private
 // log, and return its ready event once it prints one. The server outlives this
 // process and stops on rer dev --stop or its idle timeout.
-export async function startServer(entry, args, { root, env, logPath, children, signal }) {
+export async function startServer(entry, args, { root, env, logPath, children, signal, note = () => {} }) {
  signal?.throwIfAborted();
  const handle = await open(logPath, 'a', 0o600), from = (await handle.stat()).size;
- let child;
- try { child = spawn(process.execPath, [entry, 'dev', ...args, '--json'], { cwd: root, env, detached: true, stdio: ['ignore', handle.fd, handle.fd] }); }
- finally { await handle.close(); }
+ let child, exit, spawnError;
+ // Listening before anything is awaited: a spawn that fails reports it on the next tick.
+ try {
+  child = spawn(process.execPath, [entry, 'dev', ...args, '--json'], { cwd: root, env, detached: true, stdio: ['ignore', handle.fd, handle.fd] });
+  child.once('error', failure => { spawnError = failure; exit ??= 1; });
+  child.once('exit', (code, name) => { exit = code ?? (name ? 128 : 1); });
+ } finally { await handle.close(); }
  own(children, child, signal);
- let exit, ready, error, output = '';
- child.once('exit', (code, name) => { exit = code ?? (name ? 128 : 1); });
+ let ready, error, output = '';
  await follow(logPath, from, line => {
   const event = events(line);
   if (event?.event === 'ready') { ready = event; return true; }
   if (event?.event === 'error') error = event;
+  // rer dev --door / --direct: where the checkout moved.
+  if (event?.event === 'moved') note(`moved this checkout from ${event.from} to ${event.to}; its data is kept`);
   if (!event) output = (output + line + '\n').slice(-8192);
   return false;
  }, () => exit !== undefined);
@@ -84,7 +89,7 @@ export async function startServer(entry, args, { root, env, logPath, children, s
   for await (const line of createInterface({ input: createReadStream(logPath, { start: from }) })) { const event = events(line); if (event?.event === 'ready') ready = event; if (event?.event === 'error') error = event; }
  }
  children.delete(child);
- if (!ready) throw failureFrom(exit, error, output);
+ if (!ready) throw failureFrom(exit, error, spawnError ? `rer could not run in ${root}: ${spawnError.code ?? spawnError.message}.` : output);
  child.unref();
  return { ready, pid: child.pid, reused: exit === 0 };
 }

package/global/launch/worker.mjs

@@ -16,7 +16,7 @@ import { prepare } from './prepare.mjs';
 import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord, stopRequest } from './state.mjs';
 import { startServer } from './steps.mjs';
 
-const [root, token, argsJSON, requestedAtText] = process.argv.slice(2), args = JSON.parse(argsJSON), requestedAt = Number(requestedAtText);
+const [root, token, argsJSON, requestedAtText, mode] = process.argv.slice(2), args = JSON.parse(argsJSON), requestedAt = Number(requestedAtText), doorStart = mode === 'door-start';
 const checkout = await realpath(root), directory = await launchDirectory(checkout), events = eventLog(directory, token);
 // Listening before the claim: a stop may signal this worker as soon as it is the holder.
 const children = new Set(), stopping = new AbortController();
@@ -32,13 +32,13 @@ if (!await claimLaunch(directory, token)) {
  try {
   if (await stopRequest.covers(directory, requestedAt)) stop();
   stopping.signal.throwIfAborted();
-  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children, signal: stopping.signal });
+  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children, signal: stopping.signal, doorStart });
   await events.write({ event: 'phase', phase: 'start', message: prepared.own ? 'the app is already running; checking it' : 'starting the app' });
   // A server rer started logs to server.log; asking a running one for its
   // ready lines goes to reuse.log, and names server.log only when rer started it.
   const serverLog = join(directory, 'server.log');
   let started;
-  try { started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children, signal: stopping.signal }); }
+  try { started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children, signal: stopping.signal, note: message => events.write({ event: 'phase', phase: 'note', message }) }); }
   finally { await prepared.release?.(); }
   const record = (await liveServers(process.env)).find(item => item.checkout === checkout);
   const pid = record?.owner?.pid ?? started.pid;

package/global/list.mjs

@@ -4,7 +4,7 @@ import { execFile } from 'node:child_process';
 import { readdir, realpath, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
-import { descriptorProfile, dispatcher } from './checkout.mjs';
+import { descriptorProfile, dispatcher, pinnedPackage } from './checkout.mjs';
 import { liveServers } from './registry.mjs';
 import { describeCheckout, setupNeeded } from './launch/facts.mjs';
 import { launchPath, setupState } from './launch/state.mjs';
@@ -27,8 +27,11 @@ async function entry(path, running) {
  if (!result.launchable) result.reason = reasons[facts.profile] ?? `OPERATIONS.json is version ${facts.version ?? '(none)'}, which rer does not run`;
  result.prepared = null;
  if (profile === 'first-party') {
-  // Set up: saved settings, and no setup a launch started left unfinished.
-  try { result.prepared = !await setupNeeded(path, await describeCheckout(path, dispatcher(path).entry, process.env), await setupState.read(launchPath(path))); }
+  // Set up: saved settings, and no setup a launch started left unfinished. A
+  // checkout whose pinned rer package is not installed yet has never been
+  // launched: rer dev installs it first.
+  if (pinnedPackage(path)?.ready === false) result.prepared = false;
+  else try { result.prepared = !await setupNeeded(path, await describeCheckout(path, dispatcher(path).entry, process.env), await setupState.read(launchPath(path))); }
   catch (failure) { result.launchable = false; result.reason = `rer describe fails here: ${failure.message.split('\n')[0]}`; }
  }
  result.url = running.get(path) ?? null;

package/global/main.mjs

@@ -1,11 +1,14 @@
-import { dispatcher, locate, unsupportedMessage } from './checkout.mjs';
+import { dispatcher, locate, pinnedPackage, unsupportedMessage } from './checkout.mjs';
 import { delegate } from './delegate.mjs';
 import { localDefaults } from './launch/local-defaults.mjs';
+import { handleBrokenPipes } from './output.mjs';
+import { packageName as pinnedName } from './package-info.mjs';
 
 const help = `Usage: rer VERB [FLAGS]
 
 Inside a project (the nearest OPERATIONS.json at or above this folder, or --cwd DIR),
-every verb runs that checkout's own pinned rer, exactly as node scripts/rer.mjs VERB would.
+every verb runs that checkout's own pinned rer: the @runeditrun/rer version its package.json
+pins (installed first by rer install or rer dev), else its vendored scripts/rer.mjs.
 
   rer dev              Launch a first-party checkout with no setup steps: installs dependencies,
                        sets up a local owner and a free port when needed, starts the app and prints
@@ -14,6 +17,8 @@ every verb runs that checkout's own pinned rer, exactly as node scripts/rer.mjs
                        to 10 minutes on a first launch, or rerun it to reattach. rer dev --stop stops it.
   rer list [DIR]       The checkouts in DIR (default: here), newest first, with whether rer dev can
                        launch them, whether they are set up, and their running URL. --json for data.
+  rer door ...         The opt-in front door: every checkout at http://NAME.localhost:PORT, started
+                       on its first visit and stopped when idle. rer door --help for its verbs.
   rer cli status       This rer: version, contents digest, install channel, launcher and other rer
                        commands on PATH. --json for data.
   rer cli install      Install this package for the current user (~/.local/bin/rer).
@@ -21,12 +26,19 @@ every verb runs that checkout's own pinned rer, exactly as node scripts/rer.mjs
   rer update           Move to the latest published rer (--version X for an exact one), the way it
                        was installed: npx and install.sh installs switch atomically, npm installs run npm.
   rer --version        Print this rer's version; inside a checkout, also the version the checkout pins.
+  rer queue NAME -- COMMAND [ARGS]
+                       Run COMMAND once this computer's job queue admits it (heavy package scripts
+                       of a checkout that pins the rer package use it).
 
 Checkout verbs: install, setup, dev, preview, build, verify, reset, deploy, export, import,
 outbox, doctor, describe, check, release. Run rer VERB --help in a checkout for its flags.
 `;
 
+// The verbs that install an uninstalled pinned package before they run.
+const installsFirst = new Set(['install', 'check', 'describe']);
+
 export async function main(argv) {
+ handleBrokenPipes();
  const [verb] = argv;
  if (verb === '--version' || verb === '-v') return (await import('./version.mjs')).versionCommand(argv);
  // Only the zero-setup launch sets this, for its own setup child; an explicit
@@ -38,10 +50,34 @@ export async function main(argv) {
  if (!verb || verb === '--help' || verb === '-h' || verb === 'help') { process.stdout.write(help); return 0; }
  if (verb === 'cli') return (await import('./cli/command.mjs')).cliCommand(argv.slice(1));
  if (verb === 'list') return (await import('./list.mjs')).listCommand(argv.slice(1));
+ if (verb === 'door') return (await import('./door/command.mjs')).doorCommand(argv.slice(1));
  const target = locate(argv);
  if (target.profile === 'unsupported') { process.stderr.write(unsupportedMessage(target.root, target.version) + '\n'); return 2; }
+ const first = target.profile === 'first-party', mode = first ? dispatcher(target.root).mode : undefined;
+ if (verb === 'queue') {
+  const [, name, separator, command] = argv;
+  if (!name || separator !== '--' || !command) { process.stderr.write('Usage: rer queue NAME -- COMMAND [ARGS]\n'); return 2; }
+  if (mode === 'package') return delegate(target, target.args);
+  return (await import('../onboarding/queued-entry.mjs')).queuedCommandLine(argv.slice(1));
+ }
  // A checkout that pins its own rer package runs all of it, launching included.
- const mode = target.profile === 'first-party' ? dispatcher(target.root).mode : undefined;
+ // Until node_modules holds the pinned version, install, check and describe
+ // install it with the frozen lockfile (then run the pinned verb, so a fresh
+ // clone checks with the pinned bytes), the zero-setup launch installs it
+ // first, and every other verb says to install.
+ const pinned = first && mode !== 'package' ? pinnedPackage(target.root) : undefined;
+ if (pinned && !pinned.ready && !argv.includes('--help')) {
+  if (installsFirst.has(verb)) {
+   const { installPinned } = await import('./launch/install-pinned.mjs'), { LaunchFailure } = await import('./launch/failure.mjs');
+   try { await installPinned(target.root); }
+   catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
+   return delegate(target, target.args);
+  }
+  if (verb !== 'dev') {
+   process.stderr.write(`${target.root} pins ${pinnedName} ${pinned.declared}, ${pinned.installed ? `but node_modules holds ${pinned.installed}` : 'which is not installed yet'}. Run rer install, then rer ${verb} again.\n`);
+   return 3;
+  }
+ }
  if (verb === 'dev' && mode && mode !== 'package' && !argv.includes('--help')) return (await import('./launch/dev.mjs')).launchDev(target);
  // Every other server start or queued job on a vendored pin gets the person
  // defaults too (a pinned package applies its own).

package/global/output.mjs

@@ -0,0 +1,12 @@
+let installed = false;
+
+export function handleBrokenPipes() {
+ if (installed) return;
+ installed = true;
+ for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', error => {
+   if (error.code === 'EPIPE') return;
+   throw error;
+  });
+ }
+}

package/global/rer.mjs

@@ -2,6 +2,9 @@
 // The installed `rer` command. This file avoids newer syntax so that an old
 // Node still reaches the one-line minimum-version message.
 import { readFileSync } from 'node:fs';
+import { handleBrokenPipes } from './output.mjs';
+
+handleBrokenPipes();
 
 function manifest() {
  // Packed: the package's own package.json. From a Base checkout: the template.

package/global/version.mjs

@@ -2,9 +2,7 @@
 // checkout (or with --cwd DIR) a second line names the version that checkout
 // pins: its package's, or the one its vendored copy recorded, which
 // `rer describe` reports as cliVersion.
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { dispatcher, locate } from './checkout.mjs';
+import { dispatcher, locate, pinnedPackage } from './checkout.mjs';
 import { describeCheckout } from './launch/facts.mjs';
 import { ownManifest } from './package-info.mjs';
 
@@ -12,13 +10,15 @@ export async function versionCommand(argv) {
  process.stdout.write(ownManifest().version + '\n');
  const target = locate(argv);
  if (target.profile !== 'first-party') return 0;
- const { mode, entry } = dispatcher(target.root);
- if (mode === 'bundled') return 0;
- if (mode === 'package') {
-  const pinned = JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8')).version;
-  process.stdout.write(`This checkout (${target.root}) pins rer ${pinned} (package).\n`);
+ const pinned = pinnedPackage(target.root);
+ if (pinned) {
+  process.stdout.write(pinned.ready
+   ? `This checkout (${target.root}) pins rer ${pinned.installed} (package).\n`
+   : `This checkout (${target.root}) pins rer ${pinned.declared} (package), ${pinned.installed ? `but node_modules holds ${pinned.installed}` : 'not installed yet'}: run rer install.\n`);
   return 0;
  }
+ const { mode, entry } = dispatcher(target.root);
+ if (mode === 'bundled') return 0;
  let described;
  try { described = await describeCheckout(target.root, entry, process.env); }
  catch (failure) { process.stdout.write(`This checkout (${target.root}): its pinned rer version could not be read: ${failure.message.split('\n')[0]}\n`); return 0; }

package/modules/dependencies/protocol.mjs

@@ -1,5 +1,6 @@
 import { readJson, discover } from '../operator-auth/identity/oidc/network.mjs';
 import { PRESETS, MINIMUM_PROVIDER_VERSION } from '../operator-auth/identity/oidc/presets.mjs';
+import { isLoopbackHost } from '../operator-auth/loopback.mjs';
 export const INTERFACE = 'oidc-provider@1';
 export const CALLBACK = '/.well-known/rer-link/callback';
 export const PATHS = ['/auth/oidc/auth/callback','/auth/oidc/auth/logout'];
@@ -7,7 +8,7 @@ export const NETWORK = { timeoutMs:5000 };
 export function insist(value, code = 'invalid_link', status = 400) { if (!value) throw Object.assign(new Error(code),{code,status}); }
 export function originOf(value, local = false) {
  let u;try { u=new URL(value); } catch { insist(false); }
- insist(u.origin===value && !u.username && !u.password && (u.protocol==='https:' || local && u.protocol==='http:' && ['localhost','127.0.0.1','[::1]'].includes(u.hostname)));
+ insist(u.origin===value && !u.username && !u.password && (u.protocol==='https:' || local && u.protocol==='http:' && isLoopbackHost(u.hostname)));
  return u.origin;
 }
 export async function providerMetadata(issuer, fetcher, contract = INTERFACE) {

package/modules/deploy-kit/README.md

@@ -140,12 +140,45 @@ When a token lacks a permission, the CLI prints which one instead of only a stat
 A seed carries a copy of `modules/deploy-kit/` from a Base pin. Refresh the copy, write a `deploy.json` from the plan the seed already builds, and point `deploy`, and the hosting step of `setup`, at `owner-cli.mjs`. Keep any throwaway controller only for proofs. In `deploy.json` declare:
 
 - the bindings the app uses (`DB`, `FILES`, `JOBS` and so on), with each queue's consumer and dead-letter queue and each SQLite Durable Object class;
-- the secrets the app reads, such as its session secret and the mail provider's key;
+- the secrets the app reads, such as its session secret and the mail provider's key. A secret item may add `verifyStandIn`, the hosted-valid value `rer verify`'s hosted check binds in its place (`{"binding": "MAIL_PROVIDER", "environment": "MAIL_PROVIDER", "verifyStandIn": "resend"}`); the kit validates it (a non-empty string), leaves it out of the plan and its fingerprint, and never sends it or makes it a secret value;
 - any Cron schedule and the public setup fields the app takes in `vars`;
 - `originVar`, the variable that holds the app's public origin (for example `APP_ORIGIN`).
 
 A seed whose setup provisions nothing declares the same bindings and deploys through its own `deploy` verb. Resource names change from `rer-seedproof-*` or a chosen prefix to `<project>-<environment>-*`. The kit refuses rather than adopts an earlier installation's resources.
 
+### Run site (`rer deploy --site`)
+
+A seed's run site (`run-<seed>.com`: its marketing homepage, `/run` and docs, written by `rer build --site`) deploys to the owner's account as a **Base-generated site Worker** (`site.mjs`). The seed declares only the apex domain, beside `deploy.json`, in the file its `commandAdapter` `site.declaration` names (Base's seeds: `deploy-site.json`):
+
+```json
+{ "version": 1, "domain": "run-cradle.com" }
+```
+
+The domain is an apex hostname: no scheme, path, port, upper case or `www.`. The plan (`sitePlan`) names:
+
+- the Worker `<project>-<environment>--site`. Owner Worker names never contain `--`, so it can never be the installed app's Worker (`<project>-<environment>`), and a site deploy never reads or writes the app Worker or any of its resources;
+- its one module, `site-worker.mjs` (`SITE_WORKER`): fixed content Base generates, with no seed code. Its only binding is the assets (`ASSETS`), it runs first on every request (`run_worker_first`), and it has no secrets, no schedules and workers.dev off. A request to `www.<domain>` gets a 301 to `https://<domain>` with path and query kept; every other request is answered from the assets exactly as an assets-only Worker would answer it: the `rer build --site` folder with `html_handling: auto-trailing-slash` (`/run` serves `run.html`) and `not_found_handling: 404-page`;
+- the apex as a Workers Custom Domain, and `www.<domain>` as a second Custom Domain on the same Worker, so the www host has DNS and a certificate and its requests reach the Worker's redirect.
+
+No zone ruleset is read or written. Every request now invokes the Worker: one page view costs one Worker request for the page and one per same-origin file it loads (the default seed's run site: at most 7 per uncached page view).
+
+`rer deploy --site --dry-run` builds the site and prints that plan (`--json`: a `site` event and a result with `dryRun: true`, `deployed: false` and the same `site` object) with no provider request and nothing written, even with `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` set. Without `--dry-run` it needs both inputs. Ownership is read from the provider alone, so a deploy from a fresh checkout (a CI runner with no `.rer/`) recognises the site it deployed before:
+
+- the Worker is the kit's when its latest deployment serves, at 100%, the Worker's newest version, and that version's message annotation is the kit's `rer-site:<fingerprint>` (every site upload sets it);
+- a Custom Domain is the kit's when its service is the kit's Worker.
+
+A read-only preflight reads the zone (it must be in this account, else `site-zone-missing`), the Worker and the zone's Custom Domains, and refuses before any write: `resource-name-collision` for a Worker of the name whose live version the kit did not upload, or for a hostname attached to another service (or to a Worker that is not the kit's); `owned-resource-replaced` for a kit Worker whose latest deployment is not the kit's upload (a dashboard rollback or a split deployment). It then uploads the assets and the site Worker, checks that the new version is live, turns workers.dev off, attaches each missing hostname, and reads the Worker and both domains back. A repeat attaches nothing new. `.rer/deploy/site-<environment>.json` receives a receipt for the person; it is never read. The real path is tested only against the fake Cloudflare API in `tests/site-provider.mjs`, where every zone ruleset path answers 403; it has not run against a live account.
+
+The token needs, beyond the owner-account permissions above:
+
+| Permission | Scope | Used for |
+| --- | --- | --- |
+| Workers Scripts: Edit | the account | the site Worker upload, its assets, versions and deployments, workers.dev, and Workers Custom Domains (`/workers/domains`) |
+| Zone: Read | the run site zones | finding the zone by name |
+| Workers Routes: Edit | the run site zones | Workers Custom Domains, which also create their DNS records and certificates |
+
+No Single Redirect (dynamic redirect ruleset) permission is needed. Base's references declare reserved `.example` domains (`run-default-seed.example`, `run-<edition>.example` for a new foundation), so a real deploy of either stops at `site-zone-missing`.
+
 ## Migration safety
 
 SQL files have ordered unique names and SHA-256 identities. `_rer_deploy_migrations` is permanent controller-owned history. Applied entries must be an unchanged prefix of the desired set. A new migration gets an `applying` claim before its SQL and completion marker are submitted together to the D1 batch query API. Any interrupted, failed or uncertain outcome remains blocked and must be inspected explicitly; the kit never automatically retries, rolls back user data, or marks an unknown outcome successful. Readback checks every final identity.

package/modules/deploy-kit/artifact.mjs

@@ -40,6 +40,16 @@ export async function collectFiles(root, directory = '', budget = {bytes:0,count
   }
   return files;
 }
+// Wrangler's .assetsignore in an assets folder: gitignore-style lines naming
+// files that are never assets. The file itself is never one either.
+export function assetsIgnore(text = '') {
+  const rules = String(text).split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#')).map(line => {
+    const negate = line.startsWith('!'), body = negate ? line.slice(1) : line, directory = body.endsWith('/'), pattern = body.replace(/\/+$/, '');
+    const glob = pattern.replace(/^\//, '').split('/').map(part => part === '**' ? '.*' : part.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*').replaceAll('?', '[^/]')).join('/');
+    return { negate, test: new RegExp(`^${pattern.includes('/') ? '' : '(?:.*/)?'}${glob}${directory ? '/.*' : '(?:/.*)?'}$`) };
+  });
+  return path => path === '.assetsignore' || rules.reduce((ignored, rule) => rule.test.test(path) ? !rule.negate : ignored, false);
+}
 /** Built files a deployed Worker must serve: everything for the browser except documents
  * (the app answers those; asset html_handling redirects them) and dot paths (never public). */
 export const publicAssetPaths = paths => paths.filter(path => !path.split('/').some(part => part.startsWith('.')) && extname(path) !== '.html');

package/modules/deploy-kit/deploy.mjs

@@ -1,3 +1,4 @@
+import { recordDeployFailure } from './diagnostics.mjs';
 import { verifyServiceGrants } from './service-grants.mjs';
 import { assert, hash, validatePlan } from './validation.mjs';
 import { validateArtifact, publicAssetPaths } from './artifact.mjs';
@@ -55,8 +56,10 @@ export async function deploy({api,plan,artifact,artifactSha256,previousReceipt,r
   if (onReceipt) await onReceipt(receipt);
   // One built file proves the Worker hands static assets to the browser (assets run behind it).
   const asset = publicAssetPaths(artifact.assets.map(x => x.path))[0];
-  if (unchanged) await verifyHealth({...healthOptions,api,plan,receipt,fetch,asset});
-  else await firstHealth({api,plan,receipt,fetch,healthOptions,readiness,onHealth,asset});
+  try {
+    if (unchanged) await verifyHealth({...healthOptions,api,plan,receipt,fetch,asset});
+    else await firstHealth({api,plan,receipt,fetch,healthOptions,readiness,onHealth,asset});
+  } catch (error) { throw recordDeployFailure(error,{step:'health',...(error.code ? {code:error.code,output:error.message} : {})}); }
   return receipt;
 }
 

package/modules/deploy-kit/diagnostics.mjs

@@ -0,0 +1,55 @@
+// Provider text is private until the CLI's existing credential redactor approves
+// it. Identity, rather than mutable Error properties, carries this diagnostic.
+const failures = new WeakMap();
+export function recordDeployFailure(error, details) {
+  failures.set(error,{...failures.get(error),...details});
+  return error;
+}
+export function deployDiagnostic(error, redact) {
+  const detail = failures.get(error);
+  if (!detail) return undefined;
+  const clean = value => (redact ?? String)(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g,'').replace(/\b[a-f0-9]{32}\b/gi,'[REDACTED]');
+  const failureCode = detail.code ?? error.message;
+  const code = /^[a-zA-Z0-9_-]{1,120}$/.test(failureCode) ? clean(failureCode) : 'deploy-failed';
+  return {code,step:detail.step ?? 'deploy',created:(detail.created ?? []).map(clean),
+    ...(typeof error.resource==='string' && /^(?:d1|r2|kv|queues|worker|service):[a-z0-9-]+$/.test(error.resource) ? {resource:clean(error.resource)} : {}),
+    ...(detail.providerCodes?.length ? {providerCodes:detail.providerCodes} : {}),
+    output:(detail.output ? (redact ? clean(detail.output) : '(provider output withheld; rer deploy provides redacted details)') : '(no provider output)').split(/\r?\n/).slice(0,8).map(line=>line.slice(0,500)).join('\n')};
+}
+function operation(path, options = {}) {
+  const write = options.method && options.method !== 'GET';
+  if (/\/d1\/database\/[^/]+\/query/.test(path)) return 'migrate D1';
+  for (const [prefix,kind] of [['/d1/database','D1'],['/r2/buckets','R2'],['/queues','queue'],['/storage/kv/namespaces','KV']]) {
+    if (path === prefix && options.method === 'POST') return `create ${kind}`;
+    if (path.startsWith(prefix)) return `check ${kind}`;
+  }
+  if (path.includes('/secrets')) return 'secrets';
+  if (path.includes('/subdomain') || path.includes('/routes') || path.includes('/domains')) return 'route';
+  if (path.includes('/schedules')) return 'scheduled triggers';
+  if (write && path.startsWith('/workers/')) return 'upload Worker';
+  return 'check Worker';
+}
+export function deploymentDiagnostics(api, {onCreated} = {}) {
+  const created = [];
+  const recordCreated = resource => { created.push(resource); onCreated?.(resource); };
+  let currentStep = 'prepare deploy';
+  const guard = method => async (path, options) => {
+    const step = operation(path,options);
+    currentStep = step;
+    try {
+      const result = await api[method](path,options);
+      if (step.startsWith('create ')) recordCreated(`${step.slice(7)}:${options.body.name ?? options.body.queue_name ?? options.body.title}`);
+      return result;
+    } catch (error) { throw recordDeployFailure(error,{step,created:[...created]}); }
+  };
+  return {...api,request:guard('request'),list:guard('list'),envelope:guard('envelope'),recordCreated,
+    annotateFailure(error, step = currentStep) {
+      const prior = failures.get(error);
+      // Node filesystem/CLI codes are structural; their messages can hold paths
+      // and inputs, so retain them privately for the caller's redaction boundary.
+      const cliCode = typeof error.code === 'string' && /^(?:E[A-Z0-9_]{1,63}|health-[a-z-]+)$/.test(error.code) ? error.code : undefined;
+      recordDeployFailure(error,{step:prior?.step ?? step,created:prior?.created ?? [...created],
+        ...(!prior?.code && cliCode ? {code:cliCode,...(!prior?.output ? {output:error.message} : {})} : {})});
+      return error;
+    }};
+}

package/modules/deploy-kit/owner-cli.mjs

@@ -1,3 +1,4 @@
+import { deploymentDiagnostics, deployDiagnostic } from './diagnostics.mjs';
 import { execFileSync } from 'node:child_process';
 import { resolve, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -21,7 +22,7 @@ async function ownerArtifact(root, product) {
 }
 
 /** Inputs: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, plus the secrets the declaration names on first deploy. */
-export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, localOnlyKeys = [], notice = line => console.error(line)} = {}) {
+export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, localOnlyKeys = [], notice = line => console.error(line), onCreated} = {}) {
   let parsed;
   try { parsed = parseArgs({args:argv,allowPositionals:true,strict:true,options:{declaration:{type:'string'},environment:{type:'string'},product:{type:'string',default:''},state:{type:'string'}}}); }
   catch { throw new Error('usage'); }
@@ -36,23 +37,28 @@ export async function main(argv = process.argv.slice(2), env = process.env, {fet
   try { declaration = JSON.parse(await regularBytes(resolve(root,values.declaration),256 * 1024)); }
   catch (error) { throw new Error(error.code === 'ENOENT' ? 'missing-owner-declaration' : 'invalid-owner-declaration'); }
   assert(typeof declaration?.project === 'string','missing-owner-project');
-  const api = cloudflare({accountId:env.CLOUDFLARE_ACCOUNT_ID,token:env.CLOUDFLARE_API_TOKEN,fetch});
+  const api = deploymentDiagnostics(cloudflare({accountId:env.CLOUDFLARE_ACCOUNT_ID,token:env.CLOUDFLARE_API_TOKEN,fetch}),{onCreated});
   const target = await ownerTarget(api,{project:declaration.project,environment:values.environment});
   const statePath = values.state ? resolve(root,values.state) : join(root,'.rer','deploy',`${target.environment}.json`);
   const artifact = await ownerArtifact(root,values.product);
   const plan = ownerPlan(target,declaration,artifact,{localOnlyKeys});
   if (command === 'health') {
-    await ownerHealth({api,target,plan,statePath,fetch,healthOptions:{...healthOptions,readiness:{single:true,totalMs:30000}}});
+    await ownerHealth({api,target,plan,statePath,fetch,healthOptions:{...healthOptions,readiness:{single:true,totalMs:30000}}}).catch(error=>{throw api.annotateFailure(error,'health');});
     return {ok:true,worker:target.worker,origin:target.origin};
   }
   // Dispatch is the provider's: on some accounts a new Cron starts only at the account scheduler's next refresh.
   if (plan.crons.length) notice(cronNotice);
-  const {receipt,created} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions});
+  const {receipt,created} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions}).catch(error => {
+    api.annotateFailure(error,error.message.startsWith('missing-secret-') ? 'secrets' : undefined);
+    throw error;
+  });
   return {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,state:statePath};
 }
 
 /** Prints refusal codes and resource names only; never inputs, tokens or provider bodies. */
 export function report(error) {
+  const diagnostic = deployDiagnostic(error);
+  if (diagnostic) return {ok:false,...diagnostic};
   if (error.message === 'missing-input') return {ok:false,code:'missing-input',inputs:error.inputs};
   if (error.message === 'usage') return {ok:false,code:'usage',usage};
   return {ok:false,code:/^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? error.message : 'owner-deploy-failed',...(error.resource ? {resource:error.resource} : {})};

package/modules/deploy-kit/owner.mjs

@@ -18,7 +18,7 @@ const segment = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const STATE_KIND = 'rer-deploy-owner-state';
 const KINDS = ['d1','r2','kv','queues'];
 const DECLARATION_KEYS = ['version','project','compatibilityDate','compatibilityFlags','d1','r2','kv','queues','durableObjects','secrets','crons','vars','originVar','services','workersDev','platforms','container'];
-const ENTRY_KEYS = {d1:['binding'],r2:['binding','locationHint'],kv:['binding'],queues:['binding','consumer','deadLetterQueue'],durableObjects:['binding','className','storage'],secrets:['binding','environment'],services:['binding','project','entrypoint','allowedHosts','grant']};
+const ENTRY_KEYS = {d1:['binding'],r2:['binding','locationHint'],kv:['binding'],queues:['binding','consumer','deadLetterQueue'],durableObjects:['binding','className','storage'],secrets:['binding','environment','verifyStandIn'],services:['binding','project','entrypoint','allowedHosts','grant']};
 
 function refuse(code, kind, name) { const error = new Error(code); error.resource = `${kind}:${name}`; return error; }
 
@@ -110,7 +110,8 @@ export function ownerPlan(target, declaration, artifact, { localOnlyKeys = [] }
     ...(kv.length ? {kv} : {}),
     queues:queues.map(item => ({...item,name:name(item.binding),...(item.deadLetterQueue === undefined ? {} : {deadLetterQueue:name(item.deadLetterQueue)})})),
     durableObjects:entries(declaration,'durableObjects').map(item => ({...item})),
-    secrets:entries(declaration,'secrets').map(item => ({...item})),
+    // verifyStandIn is only `rer verify`'s hosted-check value: never planned, sent or stored.
+    secrets:entries(declaration,'secrets').map(({verifyStandIn,...item}) => { assert(verifyStandIn === undefined || typeof verifyStandIn === 'string' && verifyStandIn.length > 0 && verifyStandIn.length <= 1024, 'invalid-verify-stand-in'); return item; }),
     crons:[...(declaration.crons ?? [])],vars,
     // Only declarations using these add the keys, so earlier plans and fingerprints are unchanged.
     ...(services.length ? {services} : {}),...(declaration.workersDev === false ? {workersDev:false} : {})});
@@ -182,7 +183,7 @@ async function checkSavedResourceIdentities(api, state) {
 async function checkServiceWorkers(api, plan) {
   for (const {service} of plan.services ?? []) if (await workerSettings(api, service) === null) throw refuse('service-worker-missing','service',service);
 }
-async function workerSettings(api, worker) {
+export async function workerSettings(api, worker) {
   try { return await api.request(`/workers/scripts/${worker}/settings`); }
   catch (error) { if (error.status === 404) return null; throw error; }
 }
@@ -220,7 +221,7 @@ async function checkOwnedWorker(api, plan, artifact, state) {
 }
 
 /** One deploy at a time per state file: an exclusive lock file for the whole run. */
-async function withStateLock(path, run) {
+export async function withStateLock(path, run) {
   await mkdir(dirname(path),{recursive:true,mode:0o700});
   const lock = `${path}.lock`;
   let handle;
@@ -272,6 +273,9 @@ async function deployLocked({api, target, plan, artifact, statePath, env, fetch,
     }
     const result = await api.request(path, options);
     if (sending) {
+      // A successful upload creates a Worker only when ownership preflight found
+      // it absent. Record it before readback, which can fail after creation.
+      if (!exists) api.recordCreated?.(`Worker:${plan.worker}`);
       const active = await activeWorker(api, plan.worker);
       assert(active && deployedFingerprint(active.settings) === state.pendingUpload.fingerprint, 'uploaded-worker-drift');
       state.pendingUpload.provider = {versionId:active.versionId,deploymentId:active.deploymentId,etag:active.etag};