@runeditrun/rer 0.1.1 → 0.2.0

package/cli/hydration/verdict.mjs

@@ -0,0 +1,85 @@
+// Turns probe records into failures. Every failure names the page, the case, the
+// section and its evidence.
+import { describeCase } from './cases.mjs';
+
+const LATE_MS = 34; // two frames
+const within = (key, scope) => key === scope || key.startsWith(scope + '>');
+const list = (keys, limit = 6) => keys.slice(0, limit).join(', ') + (keys.length > limit ? ` and ${keys.length - limit} more` : '');
+
+/** Replays in one load: a one-shot animation on a rebuilt element starting more
+ * than two frames after the original did, or an animated element whose opacity
+ * dropped by more than 0.15 after rising (unless it did so on the plain load). */
+export function replays(record, baseline) {
+ const found = [];
+ for (const [id, entries] of Object.entries(record.starts ?? {})) {
+  const [key, name] = id.split(' ');
+  for (const entry of entries.slice(1)) { const late = entry.start - entries[0].start; if (late > LATE_MS) { found.push(`${key} restarted its ${name} animation ${Math.round(late)} ms late`); break; } }
+ }
+ for (const [key, opacity] of Object.entries(record.opacity ?? {})) {
+  if (opacity.dip && !baseline?.opacity?.[key]?.dip) found.push(`${key} opacity fell from ${opacity.dip.from.toFixed(2)} to ${opacity.dip.to.toFixed(2)}`);
+ }
+ return found;
+}
+
+/** What one edit load did: replaced elements (less those the plain load replaces),
+ * those outside the region the case may rebuild, replays, and frames that lacked
+ * a page section present at the edit. */
+export function measure(item, record, { survey, baseline }) {
+ const base = baseline.record ?? {}, excluded = new Set(base.replaced ?? []);
+ const replaced = (record.replaced ?? []).filter(key => !excluded.has(key));
+ let allowed = () => true;
+ if (item.kind === 'section') { const scope = survey.sections[item.section].key; allowed = key => within(key, scope); }
+ else if (item.kind === 'loose') allowed = key => !survey.sections.some(section => within(key, section.key));
+ else if (item.kind === 'cloudflare') allowed = key => (record.addressSections ?? []).some(scope => within(key, scope)) || (record.addressLoose && !survey.sections.some(section => within(key, section.key)));
+ return { replaced, outside: replaced.filter(key => !allowed(key)), replays: replays(record, base), missing: record.missing ?? [] };
+}
+
+/** A page the check may skip: React never hydrated it, it loads no application
+ * script (scripts.mjs) and its plain load raised no page or console error. A page
+ * whose scripts load but never hydrate (a broken client entry, or client scripts
+ * on another origin that the check aborts) is a failure, not a skip. */
+export const plainHtml = (load, scripts) => load.record?.settled === 'not hydrated' && !scripts.length && !load.errors.length;
+
+/** The failure for a page whose plain load never hydrated and is not plain HTML. */
+export function judgeUnhydrated({ path, scripts, baseline: { record, errors } }) {
+ const state = record?.settled ?? 'no probe record';
+ const why = state === 'not hydrated' ? `React never hydrated the page${scripts.length ? ` although it loads application scripts (${list(scripts, 3)})` : ''}` : `the page did not settle (${state}${record?.error ? ': ' + record.error : ''})`;
+ return `${path} plain load: ${why}${errors.length ? `; ${list([...new Set(errors)], 3)}` : ''}`;
+}
+
+/** Failures for one page: its plain load, its case loads and its canaries. */
+export function judgePage(page) {
+ const failures = [], { path, baseline, loads, survey } = page, base = baseline.record;
+ const fail = (what, evidence) => failures.push(`${path} ${what}: ${evidence}`);
+ const noisy = (what, load) => { if (load.errors.length) fail(what, `recovery was not quiet (${list([...new Set(load.errors)], 3)})`); };
+ const unheld = (what, load) => { if (load.unheld?.length) fail(what, `not exercised: the check's script hold let ${list(load.unheld, 3)} reach the page before the probe released the scripts`); return load.unheld?.length > 0; };
+ unheld('plain load', baseline);
+ noisy('plain load', baseline);
+ if (base.rer?.count) fail('plain load', `window.__rerHydration.count is ${base.rer.count} with no edit (${list(base.rer.stacks ?? [], 2)})`);
+ let exercised = false;
+ for (const { item, load } of loads) {
+  const what = describeCase(item, survey), record = load.record;
+  if (!record || record.settled !== 'hydrated') { fail(what, record?.settled === 'error' ? `the probe failed: ${record.error}` : `the page did not settle after hydration within the time limit (${record?.settled ?? 'no record'})`); continue; }
+  if (unheld(what, load)) continue;
+  noisy(what, load);
+  if (item.kind === 'plain') {
+   if (item.reduced && record.oneShot.length) fail(what, `one-shot animations ran: ${list(record.oneShot)}`);
+   if (record.rer?.count) fail(what, `window.__rerHydration.count is ${record.rer.count} with no edit`);
+   continue;
+  }
+  if (!record.editBeforeHydration) { fail(what, 'not exercised: the edit landed after React had started hydrating'); continue; }
+  if (record.fiberAtRelease !== false) { fail(what, 'not exercised: React hydrated before the probe released the scripts (a script the check cannot hold, such as the client bundle inlined in an inline module script, hydrated the page)'); continue; }
+  if (item.kind !== 'cloudflare' && !record.edit) { fail(what, 'not exercised: the probe found no text to edit'); continue; }
+  const { replaced, outside, replays: replayed, missing } = measure(item, record, page);
+  if (outside.length) fail(what, `React replaced ${outside.length} element(s) outside ${item.kind === 'section' ? 'the edited section' : item.kind === 'loose' ? 'the loose content (a page section was rebuilt)' : 'the sections holding addresses'}: ${list(outside)}`);
+  if (replaced.length) {
+   if (item.kind !== 'cloudflare') exercised = true;
+   if (!(record.rer?.count >= 1)) fail(what, `React rebuilt ${replaced.length} element(s) but window.__rerHydration.count is ${record.rer?.count ?? 'absent'}; the client entry must pass onRecoverableError: createRecoverableErrorHandler()`);
+  }
+  for (const replay of replayed) fail(what, `an intro replayed: ${replay}`);
+  if (missing.length) fail(what, `${missing.length} frame(s) lacked a page section present at the edit (${list([...new Set(missing.flatMap(frame => frame.lost))])})`);
+ }
+ if (survey.sections.length && loads.some(({ item }) => item.kind === 'section' || item.kind === 'loose') && !exercised) fail('all edits', 'not exercised: no edit before hydration made React rebuild anything, so the check proved nothing on this page');
+ if (survey.sections.length && !loads.some(({ item }) => item.kind === 'section')) fail('all edits', 'not exercised: no page section has text to edit');
+ return failures;
+}

package/cli/inspect.mjs

@@ -1,19 +1,23 @@
 import { dependencyDoctor } from './dependency-doctor.mjs';
 import { inventory } from './export.mjs';
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { resolve } from 'node:path';
+import { delimiter, dirname, resolve } from 'node:path';
 import { aliases, pins, requiredHooks, serverDefaults, verbs, releaseFlags } from './contract.mjs';
 import { runningVersion } from './version.mjs';
 import { contained, readPackage } from './project.mjs';
 import { shared } from './shared.mjs';
-import { missing } from './errors.mjs';
+import { missing, RerError } from './errors.mjs';
 import { projectNodePin } from './node-runtime-discovery.mjs';
 import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { localAiDiagnostics } from './ai-local.mjs';
 import { authCopyClauses } from './auth-copy.mjs';
 import { cacheWarnings } from './cache-doctor.mjs';
 import { deployedMain } from './deploy-config.mjs';
+import { commandArgv, commandLine, declaredPackage, exactVersion, lockedPackage, packageName, vendoredPaths } from './package-mode.mjs';
+import { vendoredCalls } from './package-calls.mjs';
+import { doorProtocol } from './door.mjs';
+import { savedOrigin } from './door-mode.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
@@ -28,8 +32,10 @@ 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 ?? 'Existing Base release producer.' }])),
-  aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === `node scripts/rer.mjs${verb ? ' ' + verb : ''}`)),
-  local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
+  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).
+  door: { protocol: doorProtocol },
  };
 }
 
@@ -57,6 +63,9 @@ export async function check(project, explicitProfile) {
  for (const loop of project.descriptor.loops ?? []) add('SC-10.loop.' + loop.id, !loop.required || loop.enabled, `Enable the required ${loop.id} loop or correct its declaration.`);
  if (project.profile === 'first-party' || explicitProfile === 'first-party') {
   const adapter = project.adapter, pkg = await readPackage(project.root), marker = project.descriptor.seedContract;
+  // Package mode (an @runeditrun/rer pin) and vendored mode differ only in
+  // where rer comes from: the command targets and the source clauses below.
+  const packaged = declaredPackage(pkg) !== undefined;
   add('SC-09.profile', marker?.version === 1 && marker?.profile === 'first-party', 'Restore OPERATIONS v2 seedContract version 1, profile first-party and the adapter pointer.');
   add('SC-01.adapter', adapter?.version === 1, 'Export commandAdapter version 1 from scripts/installer/local.mjs.');
   for (const hook of requiredHooks) add('SC-01.hook.' + hook, adapter?.[hook] ?? adapter?.hooks?.[hook], `Missing ${hook} hook/inventory; adopt the shared command adapter with a real ${hook} target.`);
@@ -64,14 +73,18 @@ export async function check(project, explicitProfile) {
    const declaration = project.descriptor.commands[verb];
    add('SC-01.verb.' + verb, declaration && adapter?.verbs?.[verb], `Missing ${verb}; declare it in OPERATIONS and expose its shared implementation.`);
    for (const flag of definition.flags) add('SC-01.flag.' + verb + '.' + flag.slice(2), adapter?.verbs?.[verb]?.flags?.includes(flag), `Missing ${verb} ${flag}; restore the shared implementation supporting this flag.`);
-   add('SC-02.target.' + verb, declaration?.argv?.join('\0') === ['node', 'scripts/rer.mjs', verb].join('\0'), `Declare ${verb} argv as node scripts/rer.mjs ${verb}.`);
+   const argv = commandArgv(verb, packaged);
+   add('SC-02.target.' + verb, declaration?.argv?.join('\0') === argv.join('\0'), `Declare ${verb} argv as ${argv.join(' ')}.`);
   }
-  for (const [alias, verb] of Object.entries(aliases)) add('SC-02.alias.' + alias, pkg.scripts?.[alias] === `node scripts/rer.mjs${verb ? ' ' + verb : ''}`, `Set package script ${alias} to node scripts/rer.mjs${verb ? ' ' + verb : ''}.`);
+  for (const [alias, verb] of Object.entries(aliases)) add('SC-02.alias.' + alias, pkg.scripts?.[alias] === commandLine(verb, packaged), `Set package script ${alias} to ${commandLine(verb, packaged)}.`);
   add('SC-02.install-lifecycle', !pkg.scripts?.install, 'Remove the install lifecycle alias; use deps or frozen pnpm install.');
   let nodeFile; try { nodeFile = (await readFile(resolve(project.root, '.node-version'), 'utf8')).trim(); } catch {}
   add('SC-02.node-file', nodeFile === pins.node, `Set .node-version to ${pins.node}.`);
   add('SC-02.node-engine', pkg.engines?.node === pins.node, `Pin package.json engines.node to ${pins.node}.`);
   add('SC-02.pnpm', pkg.packageManager === `pnpm@${pins.pnpm}`, `Pin packageManager to pnpm@${pins.pnpm}.`);
+  if (packaged) for (const [id, ok, message] of await packageClauses(project.root, pkg)) add(id, ok, message);
+  // Vendored mode: the copy and its recorded inventory.
+  else {
   for (const path of ['scripts/rer.mjs', 'scripts/base-cli/inventory.json', 'scripts/base-onboarding/adapter.mjs']) {
    let exists = false; try { await contained(project.root, path); exists = true; } catch {}
    add('SC-01.portable.' + path, exists, `Restore portable source ${path} through the documented export tool.`);
@@ -94,6 +107,7 @@ export async function check(project, explicitProfile) {
     add('SC-01.inventory.' + path, exact, `Restore stale or missing portable CLI source ${path} with the source export tool.`);
    }
   } catch { add('SC-01.inventory', false, 'Restore the deterministic portable CLI source inventory.'); }
+  }
   add('SC-08.portability', typeof adapter?.portability?.export === 'function' && typeof adapter?.portability?.import === 'function', 'Adopt the reviewed mainline complete local portability API; archive support remains unavailable until then.');
   if (adapter?.devIdentity) for (const [id, ok, message] of await devIdentityClauses(project.root, adapter)) add(id, ok, message);
   for (const [id, ok, message] of await authCopyClauses(project.root)) add(id, ok, message);
@@ -102,12 +116,40 @@ export async function check(project, explicitProfile) {
  return { clauses, ok: clauses.every(clause => clause.ok) };
 }
 
+// Package mode: the exact pin, its lockfile entry, no vendored copy and no
+// command still calling one.
+async function packageClauses(root, pkg) {
+ const declared = declaredPackage(pkg), locked = await lockedPackage(root), clauses = [];
+ clauses.push(['SC-13.package.pin', pkg.devDependencies?.[packageName] === declared && exactVersion.test(declared), `Pin ${packageName} in devDependencies to an exact version (for example "0.2.0"), not ${JSON.stringify(declared)} or a runtime dependency.`]);
+ clauses.push(['SC-13.package.lockfile', locked?.locked && locked.specifier === declared && locked.version === declared, `Run pnpm install so pnpm-lock.yaml locks ${packageName} ${declared}${locked?.version ? ` (it locks ${locked.version})` : ''}.`]);
+ for (const path of vendoredPaths) {
+  let present = true; try { await lstat(resolve(root, path)); } catch { present = false; }
+  clauses.push(['SC-13.package.vendored.' + path, !present, `Remove ${path}: a checkout that pins ${packageName} runs the package, not a vendored copy (node scripts/export-cli.mjs --to-package converts one).`]);
+ }
+ // Delivery operations, the scripts they run and CI workflows call the package too.
+ const calls = await vendoredCalls(root);
+ clauses.push(['SC-13.package.calls', !calls.length, `Run pnpm exec rer VERB instead of the removed vendored copy (pnpm install --frozen-lockfile first where nothing has installed yet) in ${calls.length} place${calls.length === 1 ? '' : 's'}:\n${calls.slice(0, 20).join('\n')}${calls.length > 20 ? `\n...and ${calls.length - 20} more` : ''}`]);
+ return clauses;
+}
+
+// Without the pinned pnpm on PATH, rer provides it for this command only
+// (cli/pnpm-runtime.mjs); it never changes global tools.
 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 version = await probePnpm(root, store, signal);
- if (version !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. Install/select the documented pin; rer never changes global tools.`);
+ 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 usePnpm = directory => { process.env.PATH = [dirname(process.execPath), directory, process.env.PATH].filter(Boolean).join(delimiter); };
 
 export async function doctor(project, store, signal) {
  const { inspectOperations } = await import('../operations/operations.mjs');
@@ -127,6 +169,11 @@ export async function doctor(project, store, signal) {
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) values = parsed;
   } 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 (directory) { usePnpm(directory); try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; } }
+  }
  }
  const aiIssues = await localAiDiagnostics(project,process.env);
  const dependencies=project.profile==='first-party'?await dependencyDoctor(project.root):[];

package/cli/lifecycle.mjs

@@ -1,5 +1,3 @@
-import { createHmac } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
 import { dependencyInputs } from './dependency-input.mjs';
 import { linkDependencies } from './dependencies.mjs';
 import { savedSetupAnswers } from './setup-answers.mjs';
@@ -13,9 +11,10 @@ import { missing, refuse, RerError, lifecycleError } from './errors.mjs';
 import { executeDeclared } from './independent.mjs';
 import { transfer } from './transfers.mjs';
 import { runtimeFrontDoor } from './runtime-front-door.mjs';
-import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
+import { localCliSessionProof, localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { rememberSetupAnswers } from './setup-answers.mjs';
 import { ensureDevKey, readDevKey, refuseDevLayerOutput, openUrl, DEV_KEY_HEADER } from './dev-identity.mjs';
+import { announceDoorRoute, routeRunning, verifyDoorFor } from './door-mode.mjs';
 
 export async function runCommand(project, options, out) {
  if(project.profile==='first-party'&&['dev','preview'].includes(options.verb))return (await import('./managed-server.mjs')).managedServer(project,options,out);
@@ -42,11 +41,12 @@ export async function runCommand(project, options, out) {
     selected = await selectedOrigin(project, options, { setup: options.verb === 'setup' });
     if (options.verb === 'setup') {input = await setupInput(project, options, selected.vars, signal, { origin: selected.url });await dependencyInputs({project,input,origin:selected.url});}
     else if (requiredLocalSettings(project, selected.vars).length) throw missing('Private owner settings are missing. Run rer setup --owner-email EMAIL first.');
-    if (options.verb !== 'outbox') await availablePort(selected.host, selected.port, { root: project.root, saved: !selected.explicitPort && selected.savedOrigin !== undefined });
+    if (options.verb !== 'outbox' && !selected.door) await availablePort(selected.host, selected.port, { root: project.root, saved: !selected.explicitPort && selected.savedOrigin !== undefined });
     if (options.verb === 'setup') announcePort(out, options, selected);
    }
    const { localOperation } = await shared('local/operation.mjs');
-   if (options.verb !== 'outbox') try { operation = await localOperation(project.root, process.env.RER_LOCAL_OPERATION); } catch (error) { throw refuse(error.message); }
+   // The run site reads no local state: it builds beside a running rer dev.
+   if (options.verb !== 'outbox' && !options.site) try { operation = await localOperation(project.root, process.env.RER_LOCAL_OPERATION); } catch (error) { throw refuse(error.message); }
    const { recoverInterrupted } = await shared('local/recovery.mjs');
    if (operation) await recoverInterrupted(project.root, operation);
   }
@@ -67,6 +67,8 @@ export async function runCommand(project, options, out) {
   if (project.profile === 'independent') return await executeDeclared(project, options, store, signal);
   await tools(project.root, store, signal);
   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);
   if (options.verb === 'install') {
    await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...process.env, CI: 'true' } }); return {};
   }
@@ -75,7 +77,10 @@ export async function runCommand(project, options, out) {
    if (!Array.isArray(target)) throw refuse('A complete internal verification target is missing.');
    await store.run('Verifying application', target[0], target[1], { cwd: project.root, signal, env: { ...process.env, RER_LOCAL_OPERATION: operation.token } });
    await store.step('Serving the production build as rer deploy hosts it');
-   return { hosted: await (await import('./hosted-output.mjs')).checkHostedOutput(project.root, { declaration: adapter.deployDeclaration ?? adapter.deploy?.declaration }) };
+   const declaration = adapter.deployDeclaration ?? adapter.deploy?.declaration;
+   const hosted = await (await import('./hosted-output.mjs')).checkHostedOutput(project.root, { declaration });
+   await store.step('Checking that page sections hydrate as separate units');
+   return { hosted, hydration: await (await import('./hydration/check.mjs')).checkHydration(project.root, { pages: adapter.publicPages, declaration, report: lines => lines.forEach(line => store.report(line)) }) };
   }
   if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
   if (options.verb === 'deploy') {
@@ -89,7 +94,17 @@ export async function runCommand(project, options, out) {
   const devKey = adapter.devIdentity ? options.verb === 'setup' ? await ensureDevKey(project.root) : await readDevKey(project.root) : null;
   if (devKey) store.addSecrets?.([devKey]);
   let app;
-  if (options.verb === 'setup') proxy = await runtimeFrontDoor(selected);
+  if (options.verb === 'setup') { proxy = await runtimeFrontDoor({ ...selected, devKey: devKey ?? undefined, origin: selected.url }); if (selected.door) await announceDoorRoute(selected, proxy); }
+  // The outbox of a door-mode checkout is read from its running server's own
+  // proxy, never through the door: with no such server nothing is sent. A key
+  // is sent only once the door has proved it is this account's.
+  if (options.verb === 'outbox' && selected?.door) {
+   const running = await runningRecord(project.root);
+   if (!running?.door) throw new RerError('outbox_unavailable', 'The local application outbox is unavailable. Start rer dev first.', 1);
+   if (devKey) await verifyDoorFor(selected.url);
+   await routeRunning(running);
+  }
+  const { appFetch } = await shared('app-fetch.mjs');
   const emailKey = localSettingKeys(project).email;
   await adapter.run(project.root, input ?? { [emailKey]: options.ownerEmail ?? selected?.vars[emailKey] }, store,
    child => { app = child; }, signal,
@@ -99,11 +114,9 @@ export async function runCommand(project, options, out) {
   if (options.verb === 'setup') {
    await linkDependencies({project,input,origin:url,store,signal});
    if(project.setupManifest?.dependencies?.length) {
-    const { localVariables }=await shared('local/environment.mjs');
-    const values=localVariables(await readFile(new URL(project.adapter.hooks?.secrets?.file??'.dev.vars','file://'+project.root+'/'),'utf8'));
-    const proof=createHmac('sha256',values.SESSION_SECRET).update('local-cli\0sign-in').digest('hex');
+    const proof=await localCliSessionProof(project);
     store.addSecrets?.([proof]);
-    const completed=await fetch(url+'/auth/setup-complete',{method:'POST',headers:{Origin:url,'Content-Type':'application/json','x-rer-local-cli':proof},body:'{}',signal});
+    const completed=await appFetch(url+'/auth/setup-complete',{method:'POST',headers:{Origin:url,'Content-Type':'application/json','x-rer-local-cli':proof},body:'{}',signal});
     if(!completed.ok)throw missing('The dependency setup has not completed an owner claim.');
     await completed.body?.cancel();
    }
@@ -113,7 +126,7 @@ export async function runCommand(project, options, out) {
    else if (devKey) { out.human(`RER_SETUP_READY ${url}`); out.human(`Next: rer dev opens ${url} signed in as the owner; first-run setup finishes at ${url}/setup.`); }
    else { out.human(`RER_SETUP_READY ${url}`); signInInstructions(out, signInUrl); out.human(`Finish first-run setup at ${url}/setup after sign-in.`); out.human('Next: rer dev'); }
   } else if (options.verb === 'outbox') {
-   const response = await fetch(signInUrl, { headers: devKey ? { [DEV_KEY_HEADER]: devKey } : {}, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) });
+   const response = await appFetch(signInUrl, { headers: devKey ? { [DEV_KEY_HEADER]: devKey } : {}, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) }).catch(() => ({ ok: false }));
    if (!response.ok) throw new RerError('outbox_unavailable', 'The local application outbox is unavailable. Start rer dev first.', 1);
    await response.body?.cancel();
    const open = devKey ? openUrl(url, devKey, { path: '/__dev/key', next: '/__dev/outbox' }) : signInUrl;
@@ -132,8 +145,19 @@ export async function runCommand(project, options, out) {
  }
 }
 
+// This checkout's running server, from the shared registry (routeRunning
+// checks that it is alive and holds its proxy port).
+async function runningRecord(root) {
+ const { readJson } = await import('../modules/job-queue/storage.mjs');
+ const { serversDirectory } = await import('./server-registry.mjs');
+ const { realpath } = await import('node:fs/promises');
+ const checkout = await realpath(root), state = await readJson(join(serversDirectory(), 'state.json'), { running: [] });
+ return (state.running ?? []).find(record => record.checkout === checkout);
+}
+
 // One plain line saying which port this checkout uses, and what moved.
 function announcePort(out, options, selected) {
+ if (selected.door) { if (options.json) out.event('origin', { url: selected.url, door: true }); else out.human(`Using ${selected.url} for this checkout, served through the front door.`); return; }
  const { moved, skipped } = selected;
  const line = moved ? `Moving this checkout from port ${moved.from} to port ${moved.to}. Its data is kept.`
   : !selected.savedOrigin ? `Using port ${selected.port} for this checkout${skipped ? ` (${skipped} is in use)` : ''}.` : undefined;

package/cli/local.mjs

@@ -8,6 +8,8 @@ import { origin, loopback } from './parse.mjs';
 import { refuse } from './errors.mjs';
 import { defaultPort, firstFreePort, busyPortMessage } from './port.mjs';
 import { localSettingKeys } from './settings.mjs';
+import { doorSite } from './door.mjs';
+import { selectDoor } from './door-mode.mjs';
 
 export async function selectedOrigin(project, options, { setup = false } = {}) {
  const { readSettings } = await shared('adapter-settings.mjs');
@@ -18,8 +20,11 @@ export async function selectedOrigin(project, options, { setup = false } = {}) {
   try { previous = new URL(vars[originKey]); } catch { throw refuse('Saved origin is malformed. Restore private settings or use confirmed reset.'); }
   if (previous.origin !== vars[originKey] || previous.protocol !== 'http:' || !loopback(previous.hostname.replace(/^\[|\]$/g, ''))) throw refuse('Saved origin is unsafe. Restore private settings or use confirmed reset.');
  }
- const host = options.host ?? previous?.hostname.replace(/^\[|\]$/g, '') ?? '127.0.0.1';
- const savedPort = previous ? Number(previous.port || 80) : undefined;
+ // A front-door origin (saved, or --door on a fresh setup) serves through the door.
+ const door = await selectDoor(project, options, previous, { vars, savedOrigin: previous?.origin });
+ if (door) return door;
+ const host = options.host ?? (previous && !doorSite(previous.origin) ? previous.hostname.replace(/^\[|\]$/g, '') : '127.0.0.1');
+ const savedPort = previous && !doorSite(previous.origin) ? Number(previous.port || 80) : undefined;
  // A first setup with no port asked for takes the first free one, never a busy one.
  let port = options.port ?? savedPort, taken;
  if (port === undefined && setup) { port = await firstFreePort(host); taken = port !== defaultPort; }
@@ -95,6 +100,7 @@ export async function refuseLegacyProcess(project,{reset=false}={}) {
  // Confirmed reset can recover malformed settings; checkout/state custody is
  // still checked even when there is no usable saved origin.
  const {localProcessConflict}=await shared('process-diagnostics.mjs');
- const conflict=await localProcessConflict(project.root,selected?.savedOrigin);
+ // The front door holds a door origin's port, not this checkout.
+ const conflict=await localProcessConflict(project.root,selected?.door?undefined:selected?.savedOrigin);
  if(conflict)throw refuse(`A local process holds ${conflict.reason}: PID ${conflict.pid} (${conflict.command}). Stop it with kill -TERM ${conflict.pid}, then retry. Use rer dev --stop or rer preview --stop for a registered server.`);
 }

package/cli/main.mjs

@@ -38,6 +38,8 @@ export async function main(argv = process.argv.slice(2)) {
    if (!options.json) out.human(JSON.stringify(result, null, 2));
    out.result(result.ok, result.ok ? 0 : 3, { diagnostics: result }); return result.ok ? 0 : 3;
   }
+  // A checkout without a declared run site refuses --site before any effect.
+  if (options.site) (await import('./site.mjs')).declaredSite(project);
   const bounded=await (await import('./bounded.mjs')).boundedCommand(project,options,argv,out);
   if(bounded)return bounded.exitCode;
   if(options.platform==='container' && !['export','import'].includes(options.verb)) { const result = await (await import('./container.mjs')).containerCommand(project,options,out); out.result(true,0,result); return 0; }

package/cli/managed-server.mjs

@@ -1,5 +1,6 @@
 import { prepareLiveModels } from './ai-local.mjs';
 import {fileURLToPath} from 'node:url';
+import {join} from 'node:path';
 import { serverRegistry } from './server-registry.mjs';
 import { activityClock } from './server-activity.mjs';
 import { runtimeFrontDoor } from './runtime-front-door.mjs';
@@ -13,24 +14,29 @@ import { invalid,missing,refuse,RerError,lifecycleError } from './errors.mjs';
 import { processInfo } from '../modules/job-queue/processes.mjs';
 import { declaredCrons,runScheduled } from './scheduled.mjs';
 import { readDevKey,requireDevKey,refuseManagedInstallation,resolvePersona,openUrl,DEV_KEY_HEADER } from './dev-identity.mjs';
+import { announceDoorRoute,claimSavedName,moveCheckout,routeRunning,verifyDoorFor } from './door-mode.mjs';
 
 // Seeds without devIdentity keep the outbox sign-in unchanged. With it, dev
 // opens signed in (RER_SIGNED_IN, RER_OPEN); --login and preview keep the
 // outbox, reached through RER_OPEN's one-time key exchange. A runtime that
 // serves no outbox (a seed's preview without one) is not pointed at it.
-export function ready(out,url,dev,json=false,outbox=true){
+// A seed that declares a run site also gets RER_SITE: its static run site
+// (homepage, /run, docs) served locally on its own port, after the ready lines.
+export function ready(out,url,dev,json=false,outbox=true,siteUrl){
  const signInUrl=url+'/__dev/outbox',open=dev&&(dev.identity||outbox);
- if(json){out.event('ready',{url,...(outbox?{signInUrl}:{}),...(dev?{signedInAs:dev.signedInAs??null,...(open?{openUrl:dev.openUrl}:{})}:{})});return;}
+ if(json){out.event('ready',{url,...(outbox?{signInUrl}:{}),...(dev?{signedInAs:dev.signedInAs??null,...(open?{openUrl:dev.openUrl}:{})}:{}),...(siteUrl?{siteUrl}:{})});return;}
  out.human(`RER_READY ${url}`);
- if(dev?.identity){if(dev.signedInAs)out.human(`RER_SIGNED_IN ${dev.signedInAs}`);out.human(`RER_OPEN ${dev.openUrl}`);out.human('Open that link on this computer. Its fragment holds this checkout\'s dev key, which the page keeps only as a cookie; never share the link.');return;}
- if(!outbox)return;
- out.human(`RER_SIGN_IN ${signInUrl}`);
- if(dev)out.human(`RER_OPEN ${dev.openUrl}`);
- out.human(`Open ${dev?'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.`);
+ if(dev?.identity){if(dev.signedInAs)out.human(`RER_SIGNED_IN ${dev.signedInAs}`);else if(dev.ownerLeft)out.human('No active owner remains in this app, so rer dev cannot sign in as one. Use rer dev --login with another operator, or rer reset --yes and rer setup for a new owner.');out.human(`RER_OPEN ${dev.openUrl}`);out.human('Open that link on this computer. Its fragment holds this checkout\'s dev key, which the page keeps only as a cookie; never share the link.');}
+ else if(outbox){
+  out.human(`RER_SIGN_IN ${signInUrl}`);
+  if(dev)out.human(`RER_OPEN ${dev.openUrl}`);
+  out.human(`Open ${dev?'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.`);
+ }
+ if(siteUrl)out.human(`RER_SITE ${siteUrl}`);
 }
 export async function managedServer(project,options,out,{clock={}}={}){
  const registry=await serverRegistry(project.root),controller=new AbortController();
- let store,operation,proxy,activity,app,termination,reason,cleanupPromise,finished,selected,cleaned;
+ let store,operation,proxy,activity,app,termination,reason,cleanupPromise,finished,selected,cleaned,site;
  const scheduling=new AbortController();
  let activityWrites=Promise.resolve(),pendingActivity,activityWriting=false,infrastructureFailure;
  function recordActivity(fields){
@@ -39,13 +45,14 @@ export async function managedServer(project,options,out,{clock={}}={}){
  }
  const stopped=new Promise(resolve=>{finished=resolve;});
  const cleanupDone=new Promise(resolve=>{cleaned=resolve;});
- const cleanup=()=>cleanupPromise??=(async()=>{scheduling.abort();activity?.close();await store?.closeCommands();await proxy?.close();await operation?.release();})();
+ const cleanup=()=>cleanupPromise??=(async()=>{scheduling.abort();activity?.close();await site?.close();await store?.closeCommands();await proxy?.close();await operation?.release();})();
  const stop=async why=>{reason??=why;controller.abort();finished();await cleanupDone;return {};};
  const handlers=new Map(['SIGINT','SIGTERM'].map(name=>[name,()=>{termination=name;void stop(name);} ]));
  for(const [name,handler]of handlers)process.on(name,handler);
  try{
   if(options.stop){await registry.stop(options.verb,options);return {};}
   controller.signal.throwIfAborted();
+  if(options.door||options.direct)await moveCheckout(project,options,out,registry);
   const devIdentity=project.adapter.devIdentity;
   if(options.as!==undefined&&!(devIdentity&&options.verb==='dev'))throw invalid('--as needs a seed that declares devIdentity.');
   let devKey=devIdentity?await readDevKey(project.root):null;
@@ -62,13 +69,20 @@ export async function managedServer(project,options,out,{clock={}}={}){
    if(options.verb==='dev' && (running.models??'fake')!==(options.models??'fake'))throw refuse('Stop the running dev server before changing --models mode.');
    if(options.modelsService)throw refuse('Stop the running dev server before saving live-dev credentials.');
    if(options.verb==='dev'&&Boolean(running.login)!==Boolean(options.login))throw refuse(`The running dev server ${running.login?'uses':'does not use'} --login. Stop it with rer dev --stop to change sign-in mode.`);
-   const response=await fetch(running.url+'/health',{headers:{'x-rer-probe':running.probe},signal:AbortSignal.timeout(5000)});
+   // A door-mode server is probed on its own proxy, never through the door.
+   await claimSavedName(project,running.url);
+   await routeRunning(running);
+   const {appFetch}=await shared('app-fetch.mjs');
+   const response=await appFetch(running.url+'/health',{headers:{'x-rer-probe':running.probe},signal:AbortSignal.timeout(5000)});
    if(!response.ok || (await response.json()).status!=='ok')throw refuse('Registered application failed health verification. Stop it before retrying.');
    if(devIdentity)devKey=await requireDevKey(project.root);
-   emitReady(out,options,running.url,devIdentity&&await devReady(running.url,devKey,options,controller.signal));return {reused:true};
+   // A key is sent (or printed) for a door origin only once the door proves it is ours.
+   if(devIdentity)await verifyDoorFor(running.url);
+   const dev=devIdentity&&await devReady(running.url,devKey,options,controller.signal);
+   await emitReady(out,options,project.root,running.url,dev,true,running.siteUrl);return {reused:true};
   }
   await registry.serve(async action=>{
-   if(action==='status')return {...activity?.snapshot(),url:selected?.url,probe:proxy?.probe};
+   if(action==='status')return {...activity?.snapshot(),url:selected?.url,probe:proxy?.probe,siteUrl:site?.url};
    if(action==='stop')return stop('explicit stop');
    throw Error('Unknown management operation');
   });
@@ -81,7 +95,7 @@ export async function managedServer(project,options,out,{clock={}}={}){
   const seed=project.adapter.setup?await loadInstallerSeed(project.root,project.adapter):undefined;project.setupManifest=seed?.manifest;
   const keys=localSettingKeys(project);
   selected=await selectedOrigin(project,options);
-  await availablePort(selected.host,selected.port,{root:project.root,saved:!selected.explicitPort&&selected.savedOrigin!==undefined});
+  if(!selected.door)await availablePort(selected.host,selected.port,{root:project.root,saved:!selected.explicitPort&&selected.savedOrigin!==undefined});
   if(!selected.vars[keys.email])throw missing('Private owner settings are missing. Run rer setup first.');
   if(devIdentity&&!devKey)devKey=await requireDevKey(project.root);
   if(devIdentity&&options.verb==='dev'&&!options.login)refuseManagedInstallation(selected.vars,process.env);
@@ -97,7 +111,8 @@ export async function managedServer(project,options,out,{clock={}}={}){
   await tools(project.root,store,controller.signal);
   activity=activityClock({...clock,seconds:options.idleTimeout,onIdle:()=>void stop('idle timeout'),onChange:recordActivity});
   const crons=project.adapter.scheduled!==false?await declaredCrons(project.root,project.adapter).catch(error=>{throw refuse(`The declared scheduled triggers cannot run locally: ${error.message}`);}):[];
-  proxy=await runtimeFrontDoor({host:selected.host,port:selected.port,activity});const internal=proxy.runtimePort;
+  proxy=await runtimeFrontDoor({host:selected.host,port:selected.port,activity,door:selected.door,devKey:devKey??undefined,origin:selected.url});const internal=proxy.runtimePort;
+  if(selected.door)await announceDoorRoute(selected,proxy,registry);
   const modelsLive = options.verb==='dev' ? await prepareLiveModels(project.root,options,store,controller.signal) : undefined;
   const adapterOptions={modelsLive,selectedOrigin:selected.url,operationToken:operation.token,privateSettings:project.adapter.settings,runtimePort:internal,devKey:devKey??undefined,devLogin:Boolean(options.login),scheduled:crons.length>0};
   const input={[keys.email]:selected.vars[keys.email]};
@@ -110,9 +125,16 @@ export async function managedServer(project,options,out,{clock={}}={}){
    if(!identity)throw Error('Runtime exited before custody registration.');
    await registry.update({runtimeProcess:{pid:identity.pid,start:identity.start}});
   },controller.signal,{...adapterOptions,verb:options.verb,dev:project.adapter.dev,preview:project.adapter.preview});
+  // A key is sent (or printed) for a door origin only once the door proves it is ours.
+  if(devKey)await verifyDoorFor(selected.url);
   const dev=devIdentity&&await devReady(selected.url,devKey,options,controller.signal);
   const outbox=await outboxServed(selected.url,devKey,controller.signal);
-  activity.ready();emitReady(out,options,selected.url,dev,outbox);
+  if(options.verb==='dev'&&project.adapter.site){
+   const {devSite}=await import('./site.mjs');
+   site=await devSite(project,store,controller.signal,{host:selected.host,port:selected.port});
+   await registry.update({siteUrl:site.url});
+  }
+  activity.ready();await emitReady(out,options,project.root,selected.url,dev,outbox,site?.url);
   if(crons.length){
    out.progress(`Running ${crons.length===1?'the scheduled trigger':'the scheduled triggers'} locally: ${crons.join(' | ')}\n`);
    void runScheduled({crons,url:`http://127.0.0.1:${internal}`,path:options.verb==='preview'?'/cdn-cgi/local/scheduled':undefined,signal:scheduling.signal,report:run=>reportScheduled(out,options,run)});
@@ -130,14 +152,26 @@ function reportScheduled(out,options,run){
 }
 // GET, not HEAD: a seed's outbox route need not answer HEAD. The body is never read.
 async function outboxServed(url,devKey,signal){
- const response=await fetch(url+'/__dev/outbox',{headers:devKey?{[DEV_KEY_HEADER]:devKey}:{},signal});
+ const {appFetch}=await shared('app-fetch.mjs');
+ const response=await appFetch(url+'/__dev/outbox',{headers:devKey?{[DEV_KEY_HEADER]:devKey}:{},signal});
  await response.body?.cancel();
  return response.ok;
 }
-function emitReady(out,options,url,dev,outbox){ready(out,url,dev||undefined,options.json,outbox);}
+// dev also keeps its RER_OPEN link in owner-only .rer/local/open-url (0600),
+// which reset removes with the rest of .rer/local, for a person or agent that
+// did not keep the terminal output.
+async function emitReady(out,options,root,url,dev,outbox,siteUrl){
+ if(options.verb==='dev'&&dev?.openUrl){
+  const {privateDirectory,writePrivateFile}=await shared('private-files.mjs');
+  await writePrivateFile(join(await privateDirectory(root,['.rer','local']),'open-url'),dev.openUrl+'\n');
+ }
+ ready(out,url,dev||undefined,options.json,outbox,siteUrl);
+}
 async function devReady(url,key,options,signal){
  if(options.verb==='preview')return {openUrl:openUrl(url,key,{path:'/__dev/key',next:'/__dev/outbox'})};
  if(options.login)return {openUrl:openUrl(url,key,{next:'/__dev/outbox'})};
  const as=options.as??'owner',persona=await resolvePersona(url,key,as,signal);
- return {identity:true,signedInAs:persona.email??null,openUrl:openUrl(url,key,{path:'/__dev/key',as})};
+ // The owner persona names the owner the session will actually have (the
+ // remaining owner once the setup owner has left), or none when none is left.
+ return {identity:true,signedInAs:persona.email??null,ownerLeft:as==='owner'&&!persona.email,openUrl:openUrl(url,key,{path:'/__dev/key',as})};
 }

package/cli/package-calls.mjs

@@ -0,0 +1,81 @@
+// A package-mode checkout's commands outside package.json and OPERATIONS.json:
+// its delivery operations (rer-project.json, and the delivery producer's
+// packaging.json that rer-project.json is generated from), the scripts those
+// operations and its CI workflows run, and the workflows themselves. Converting
+// to package mode rewrites their calls into the removed vendored copy
+// (scripts/rer.mjs, scripts/base-cli, scripts/base-onboarding); check fails
+// while any remains.
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+// A command line that runs a file of the vendored copy, and (in a JavaScript
+// file) a string literal naming one, as a spawn argument does.
+const vendoredCall = /\b(?:node|bash|sh)\s+(?:\.\/)?scripts\/(?:rer\.mjs|base-cli\/|base-onboarding\/)/;
+const vendoredLiteral = /(['"`])(?:\.\/)?scripts\/(?:rer\.mjs|base-cli\/|base-onboarding\/)[^'"`\n]*\1/;
+const commentLine = /^\s*(?:#|\/\/|\/?\*)/;
+const jsFile = /\.(?:mjs|cjs|js)$/;
+// A seed-relative script path in a command.
+const scriptToken = /(?<![\w./$-])(?:\.\/)?((?:[\w.-]+\/)*[\w.-]+\.(?:sh|bash|mjs|cjs|js))(?![\w./-])/g;
+
+// The files holding delivery operations, and where in each they are.
+export const operationFiles = [
+ { file: 'rer-project.json', operations: value => value?.operations },
+ { file: 'scripts/delivery/base/packaging.json', operations: value => value?.project?.operations },
+];
+
+async function text(root, file) {
+ try { return await readFile(resolve(root, file), 'utf8'); } catch (error) { if (error.code === 'ENOENT' || error.code === 'EISDIR') return undefined; throw error; }
+}
+
+// Each operations file present: { file, text, value, operations }.
+export async function operationSources(root) {
+ const found = [];
+ for (const { file, operations } of operationFiles) {
+  const source = await text(root, file);
+  if (source === undefined) continue;
+  let value; try { value = JSON.parse(source); } catch { continue; }
+  const commands = operations(value);
+  if (commands && typeof commands === 'object') found.push({ file, text: source, value, operations: commands });
+ }
+ return found;
+}
+
+// The checkout's CI workflow files: { file, text }.
+export async function workflowSources(root) {
+ let names;
+ try { names = await readdir(resolve(root, '.github/workflows')); } catch { return []; }
+ const found = [];
+ for (const name of names.filter(name => /\.ya?ml$/.test(name)).sort()) found.push({ file: `.github/workflows/${name}`, text: await text(root, `.github/workflows/${name}`) });
+ return found.filter(source => source.text !== undefined);
+}
+
+// The seed's own script files a command runs (that exist, outside node_modules
+// and the vendored copy).
+export async function calledScripts(root, command) {
+ const found = [];
+ for (const [, path] of command.matchAll(scriptToken)) {
+  if (/^(?:node_modules\/|scripts\/(?:rer\.mjs$|base-cli\/|base-onboarding\/))/.test(path) || found.includes(path)) continue;
+  if (await text(root, path) !== undefined) found.push(path);
+ }
+ return found;
+}
+
+// Every place these commands still call the vendored copy, as `file:line: text`
+// (or `file operations.NAME: command`).
+export async function vendoredCalls(root) {
+ const calls = [], scripts = new Set();
+ for (const { file, operations } of await operationSources(root)) for (const [name, command] of Object.entries(operations)) {
+  if (typeof command !== 'string') continue;
+  if (vendoredCall.test(command)) calls.push(`${file} operations.${name}: ${command}`);
+  for (const path of await calledScripts(root, command)) scripts.add(path);
+ }
+ const lines = (file, source, literals) => source.split('\n').forEach((line, index) => {
+  if (!commentLine.test(line) && (vendoredCall.test(line) || (literals && vendoredLiteral.test(line)))) calls.push(`${file}:${index + 1}: ${line.trim().slice(0, 160)}`);
+ });
+ for (const { file, text: source } of await workflowSources(root)) {
+  lines(file, source, false);
+  for (const path of await calledScripts(root, source)) scripts.add(path);
+ }
+ for (const path of [...scripts].sort()) lines(path, await text(root, path), jsFile.test(path));
+ return calls;
+}