@runeditrun/rer 0.1.1 → 0.2.0

package/README.md

@@ -97,6 +97,10 @@ RER_OPEN http://127.0.0.1:8787/__dev/key#...
 ```
 
 or `RER_SIGN_IN <outbox>` for a seed that signs in through its development outbox.
+A seed that declares a run site prints one more line after those,
+`RER_SITE http://127.0.0.1:8788`: a local preview of its static run site (its
+marketing homepage, `/run` and docs) on the first free port above the app's. It
+stops with the app.
 It never prompts and never re-runs setup on a checkout that is already set up. A
 setup a launch started that was stopped or failed is run again by the next
 `rer dev`, keeping the owner and origin it saved, unless a setup has finished
@@ -130,6 +134,27 @@ checkout never records a limit you did not set.
 A start is never refused for machine load alone unless `RER_SERVERS_LOAD_THRESHOLD`
 or `RER_JOBS_LOAD_THRESHOLD` is set; memory and disk guards stay.
 
+## The front door
+
+```sh
+rer door enable              # opt this computer in: port 8700, 10 servers, 12 hours idle
+rer door add ~/review/*      # register checkouts; prints each http://NAME.localhost:8700
+rer door status --links      # every checkout, its state, and sign-in links
+```
+
+One process on one port serves every registered checkout at
+`http://NAME.localhost:PORT` (NAME is its folder name, unique and stable);
+`http://localhost:PORT` lists them. A stopped checkout starts when you open it
+in a browser and stops when idle; subresources, API calls and WebSockets never
+start one. `rer door enable` stores the policy (`--port`, `--server-limit`,
+`--idle-timeout`) and the `RER_*` variables in effect, so whoever later starts
+the door cannot change what its checkouts run with. While it is enabled, `rer
+dev` sets fresh checkouts up behind it; `rer dev --door` moves an existing one
+(keeping its data), `rer dev --direct` moves it back, and `--port N` always
+serves directly. `rer door start`, `stop`, `restart`, `disable` and `remove
+NAME` do what they say; after a reboot or logout the door needs `rer door
+start`. `rer door --help` has the details.
+
 ## Find what to launch
 
 ```sh
@@ -144,6 +169,91 @@ Independent projects (an `OPERATIONS.json` version 2 without a seed contract) ru
 their declared commands with `rer <verb> [-- args]`; zero-setup launching does not
 apply to them. `OPERATIONS.json` version 1 is not supported.
 
+## Package mode: a checkout that pins `@runeditrun/rer`
+
+A checkout runs one of two copies of rer. In **vendored mode** it carries
+`scripts/rer.mjs`, `scripts/base-cli` and `scripts/base-onboarding`, and `rer`
+runs that copy. In **package mode** it carries none of them and pins this package
+as an exact devDependency instead (`"@runeditrun/rer": "0.2.0"`, locked in
+`pnpm-lock.yaml`): its `OPERATIONS.json` argv and package scripts are `rer VERB`,
+which inside `pnpm run` is the pinned copy in `node_modules/.bin`, so
+`pnpm install --frozen-lockfile && pnpm run build` needs no global `rer`. A global
+`rer` hands every verb to the pinned package, launching included. Until
+`node_modules` holds the pinned version, `rer install` and `rer dev` install it
+first (the frozen `pnpm install`) and every other verb says to run `rer install`.
+
+Heavy package scripts wait for this computer's job queue with
+`rer queue NAME -- COMMAND [ARGS]` (in vendored mode,
+`node scripts/base-onboarding/queued-entry.mjs NAME -- COMMAND`).
+
+`rer check --profile first-party` accepts either mode. In package mode it asks for
+the exact devDependency (`SC-13.package.pin`), its lockfile entry
+(`SC-13.package.lockfile`), no vendored copy (`SC-13.package.vendored.*`) and `rer
+VERB` targets and aliases (`SC-02.target.*`, `SC-02.alias.*`); in vendored mode for
+the copy and its recorded inventory, as before.
+
+Convert a vendored seed from a Base checkout with
+
+```sh
+node scripts/export-cli.mjs --to-package SEED_ROOT [--version X]
+```
+
+(the default version is the latest published one, read with the seed's own npm
+configuration). It refuses, listing them, when the vendored copy differs from its
+recorded inventory: carry those edits with `pnpm patch @runeditrun/rer` once
+converted, or upstream them to Base. Otherwise it pins and locks the package
+(`pnpm install --lockfile-only`), rewrites imports into the copy to the exports
+below (anything else to `@runeditrun/rer/internal/PATH`, which promises nothing
+beyond the pinned version), rewrites the package scripts and `OPERATIONS.json`
+argv to `rer VERB` and the delivery operations (`rer-project.json` and the
+`scripts/delivery/base/packaging.json` it is generated from), the shell scripts
+they and CI workflows run, and workflow lines to `pnpm exec rer VERB` (a frozen
+`pnpm install` first where nothing has installed yet), drops the copy's own records from `base-copies.json` (the
+app-runtime copies it records stay as they are), removes the copy and lists every
+line that still names it. A later refresh is a version bump:
+`pnpm add -D -E @runeditrun/rer@X`.
+
+### Exports
+
+| Import | What it gives | Vendored path it replaces |
+| --- | --- | --- |
+| `@runeditrun/rer/adapter` | `commandAdapter` | `scripts/base-cli/cli/adapter.mjs` |
+| `@runeditrun/rer/deploy` | `ownerDeploy` | `scripts/base-cli/cli/deploy.mjs` |
+| `@runeditrun/rer/portability` | `localPortability` | `scripts/base-cli/cli/portability.mjs` |
+| `@runeditrun/rer/errors` | the CLI's error helpers | `scripts/base-cli/cli/errors.mjs` |
+| `@runeditrun/rer/jsonc` | JSONC reading | `scripts/base-cli/cli/jsonc.mjs` |
+| `@runeditrun/rer/parse`, `/scheduled` | CLI argument parsing, scheduled-job helpers | `scripts/base-cli/cli/parse.mjs`, `scheduled.mjs` |
+| `@runeditrun/rer/dev-identity` | dev identity helpers | `scripts/base-cli/cli/dev-identity.mjs` |
+| `@runeditrun/rer/operator-installer` | `operatorInstaller`, `developmentTarget`, `previewTarget` | `scripts/base-onboarding/operator-installer.mjs` |
+| `@runeditrun/rer/local-installer` | `localInstaller` | `scripts/base-onboarding/adapter.mjs` |
+| `@runeditrun/rer/operator-install` | `installOperator` | `scripts/base-onboarding/operator-install.mjs` |
+| `@runeditrun/rer/operator-prerequisites` | `operatorPrerequisites` | `scripts/base-onboarding/operator-prerequisites.mjs` |
+| `@runeditrun/rer/local/state` | `selectLocalState` | `scripts/base-onboarding/local/state.mjs` |
+| `@runeditrun/rer/local/build` | local build step | `scripts/base-onboarding/local/build.mjs` |
+| `@runeditrun/rer/state`, `/commands` | onboarding state and command runners | `scripts/base-onboarding/state.mjs`, `commands.mjs` |
+| `@runeditrun/rer/local/environment`, `/local/files`, `/local/operation`, `/local/recovery` | local setup helpers | `scripts/base-onboarding/local/*.mjs` |
+| `@runeditrun/rer/private-files` | private file helpers | `scripts/base-onboarding/private-files.mjs` |
+| `@runeditrun/rer/adapter-settings` | adapter settings helpers | `scripts/base-onboarding/adapter-settings.mjs` |
+| `@runeditrun/rer/adapter-auth`, `/adapter-hosting` | adapter auth and hosting helpers | `scripts/base-onboarding/adapter-auth.mjs`, `adapter-hosting.mjs` |
+| `@runeditrun/rer/process-diagnostics` | process diagnostics | `scripts/base-onboarding/process-diagnostics.mjs` |
+| `@runeditrun/rer/process-cleanup`, `/process-scope` | process cleanup and scope | `scripts/base-onboarding/process-cleanup.mjs`, `process-scope.mjs` |
+| `@runeditrun/rer/failures`, `/redaction` | failure and redaction helpers | `scripts/base-onboarding/failures.mjs`, `redaction.mjs` |
+| `@runeditrun/rer/setup-manifest`, `/setup-schema` | setup manifest loading and its JSON schema | `scripts/base-onboarding/setup-manifest.mjs`, `schema/SETUP.schema.json` |
+| `@runeditrun/rer/production-runtime`, `/production-modules` | production runtime helpers | `scripts/base-onboarding/production-runtime.mjs`, `production-modules.mjs` |
+| `@runeditrun/rer/queued-entry` | the job-queue entry | `scripts/base-onboarding/queued-entry.mjs` |
+| `@runeditrun/rer/archive-output` | `archiveOutputGuard` (with types) | `scripts/base-onboarding/archive-output.mjs` |
+| `@runeditrun/rer/launcher` | the browser installer launcher | `scripts/base-onboarding/launcher.mjs` |
+| `@runeditrun/rer/installer-server` | the browser installer's server (installer journeys) | `scripts/base-onboarding/server.mjs` |
+| `@runeditrun/rer/server-resources` | managed server resource readings (runtime journeys) | `scripts/base-cli/cli/server-resources.mjs` |
+| `@runeditrun/rer/operations` | OPERATIONS describe and check | `scripts/base-cli/operations/operations.mjs` |
+| `@runeditrun/rer/modules/portability`, `/catalogue`, `/cli`, `/cli-options`, `/files`, `/format`, `/http`, `/import`, `/journal`, `/legacy-safety`, `/migration-history`, `/storage` | portability module | `scripts/base-cli/modules/portability/*.mjs` |
+| `@runeditrun/rer/modules/release/export`, `/publication-scan`, `/source` | release export and publication scan | `scripts/base-cli/modules/release/*.mjs` |
+| `@runeditrun/rer/modules/deploy-kit/owner`, `/owner-cli`, `/prepare`, `/provider` | deploy kit | `scripts/base-cli/modules/deploy-kit/*.mjs` |
+| `@runeditrun/rer/modules/operator-auth`, `/dev`, `/dev/badge`, `/dev-admission`, `/accounts/native`, `/identity/email-link` | operator auth | `scripts/base-cli/modules/operator-auth/index.mjs`, `dev/index.mjs`, `dev/badge.mjs`, `dev-admission.mjs`, `accounts/native.mjs`, `identity/email-link/index.mjs` |
+| `@runeditrun/rer/modules/erasure/fence` | erasure fence statements | `scripts/base-cli/modules/erasure/fence.mjs` |
+| `@runeditrun/rer/modules/owner-claim`, `/modules/dependencies` | owner claim, dependency links | `scripts/base-cli/modules/owner-claim/index.mjs`, `dependencies/index.mjs` |
+| `@runeditrun/rer/internal/PATH` | any other package file, for tests | `scripts/base-cli/PATH`, and `scripts/base-onboarding/PATH` with PATH under `onboarding/` |
+
 ## Verbs
 
 In a checkout, every verb runs that checkout's own pinned `rer`; `rer VERB --help`
@@ -153,6 +263,6 @@ there lists its flags:
 `export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`.
 
 Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
-`rer --version` and `rer --help`.
+`rer queue NAME -- COMMAND`, `rer --version` and `rer --help`.
 
 Licence: MIT.

package/cli/README.md

@@ -20,6 +20,18 @@ boundary and imports the existing `scripts/base-onboarding/`; no second onboardi
 tree or neighboring checkout is used. The foundation composition maps copy these
 same sources from an explicit committed Base revision and record their provenance.
 
+`node scripts/export-cli.mjs --to-package SEED_ROOT [--version X]` instead moves a
+vendored seed to package mode: it pins `@runeditrun/rer` exactly (default: the
+latest published version), locks it, rewrites imports into the copy to the
+package's exports and the command targets to `rer VERB`, rewrites delivery
+operations, the shell scripts they and CI workflows run, and workflow lines to
+`pnpm exec rer VERB` (`scripts/export-cli/calls.mjs`), and removes the copy; it
+refuses, listing them, when the copy holds local edits. `cli/package-mode.mjs`
+names what each mode's command targets are and reads the lockfile entry that
+`check` requires (SC-13); `cli/package-calls.mjs` finds any of those commands
+that still calls the removed copy, which `check` refuses (SC-13.package.calls). `global/README.md` lists the exports and the vendored
+path each replaces.
+
 `node scripts/export-reference.mjs NEW_PATH` creates a standalone copy of the
 reference with runtime imports relocated into its own source tree and an explicit
 transformation inventory. It preserves source/tool pins and the real app; it does
@@ -168,7 +180,7 @@ expiry clean up owned descendants before releasing state and capacity.
 
 The private registry defaults to the OS user's `~/.rer/servers` independently
 of checkout and Codex home; `RER_SERVERS_DIR` selects an isolated directory.
-The combined dev/preview cap is 10 (`RER_SERVER_LIMIT`, positive integer; a limit recorded by a server that did not set it never lowers the cap).
+The combined dev/preview cap is 10 (`RER_SERVER_LIMIT`, positive integer). A start that sets `RER_SERVER_LIMIT` is capped by that value, higher or lower, whatever running servers recorded; a start that sets nothing is capped by the lowest limit a running server's person set explicitly, and a limit recorded by a server that did not set it never lowers the cap.
 Starting reservations count. At the cap a start is refused with a plain message
 naming each running server, its checkout and its stop command; rer never stops
 another checkout's server to make room, in any mode. A run that declares itself
@@ -207,6 +219,15 @@ Heavy verbs alone accept `--no-queue`, only with `CI=true`. Synthesized install
 child CI does not change the original decision. Inspection/help/outbox URL,
 stop and reset inventory/removal do not start a heavy job or application.
 
+After the seed's verification target, `verify` runs two checks on the production
+build served as `rer deploy` hosts it: `hosted-output.mjs` (built files and the deploy
+identity) and `hydration/` (page sections hydrate as separate units; split into
+`check.mjs` for the entry and standalone command, `browser.mjs` for Chromium, serving
+and one load, `probe.mjs` for the in-page probe, `cases.mjs` for pages, cases and the
+Cloudflare rewrite, `scripts.mjs` for which scripts are the application's, and
+`verdict.mjs` for failures). SEED-COMMAND-CONTRACT.md,
+"Hydration units", describes the check.
+
 Run the CLI contract and current first-party seed checks as part of Base's
 documented verification workflow. Structural `check` results and local runtime
 checks do not establish hosted acceptance or provider delivery.
@@ -233,11 +254,15 @@ is the tarball's path. `global/package.json` is the one file that names the next
 release version; a build from a commit not tagged `rer-v<version>` is stamped
 `<version>-dev.g<sha8>`. The installed `rer` finds the nearest `OPERATIONS.json`
 (or exactly `--cwd`, with no upward search) and runs the checkout's pinned `node_modules/@runeditrun/rer`, else
-its vendored `scripts/rer.mjs` in process, else its own bundled `bin/rer.mjs`.
+its vendored `scripts/rer.mjs` in process, else its own bundled `bin/rer.mjs`. A
+pinned package that `node_modules` does not hold yet is installed by `rer install`
+and `rer dev` first (the frozen `pnpm install`).
 Global verbs: `rer cli status|install|uninstall`, `rer list [DIR]`, `rer update`,
 and the zero-setup `rer dev`, which composes the pinned dispatcher's public verbs so it
 works on every pin. `global/README.md` is the package's own README; the package
 root also carries the script installer, `install.sh`, kept in `global/`. The build is
 reproducible and `.github/workflows/rer-release.yml` publishes it; see
 `scripts/rer-package/README.md`. `verify:rer` packs, installs and launches it end
-to end, and drives `install.sh` and `rer update` against a local registry.
+to end on the package-mode reference (served from a local registry, see
+`scripts/rer-package/registry.mjs`), and drives `install.sh` and `rer update`
+against that registry.

package/cli/contract.mjs

@@ -5,13 +5,13 @@ export const serverDefaults = Object.freeze({ serverLimit: 10, idleSeconds: 4320
 export const commonFlags = ['--help', '--cwd', '--non-interactive', '--json'];
 const definitions = {
  install: [[], 'Frozen dependency installation; no setup or global tool changes.'],
- setup: [['--owner-email', '--owner-name', '--port', '--host', '--answers'], 'Build, migrate, prepare private settings and first owner; stop the temporary app.'],
- dev: [['--port', '--host', '--idle-timeout', '--stop', '--as', '--login', '--models', '--models-service'], 'Foreground development with assets, HMR and the declared scheduled triggers run locally on their schedule. With devIdentity it opens signed in as the owner (--as PERSONA picks another start, --login uses the outbox sign-in instead); otherwise ordinary owner sign-in through the outbox.'],
+ setup: [['--owner-email', '--owner-name', '--port', '--host', '--answers', '--door'], 'Build, migrate, prepare private settings and first owner; stop the temporary app. --door sets a fresh checkout up at its front-door origin http://NAME.localhost:PORT (after rer door enable).'],
+ dev: [['--port', '--host', '--idle-timeout', '--stop', '--as', '--login', '--models', '--models-service', '--door', '--direct'], 'Foreground development with assets, HMR and the declared scheduled triggers run locally on their schedule. With devIdentity it opens signed in as the owner (--as PERSONA picks another start, --login uses the outbox sign-in instead); otherwise ordinary owner sign-in through the outbox. --door moves this checkout to its front-door origin http://NAME.localhost:PORT, keeping its data; --direct moves it back; --port and --host serve directly.'],
  preview: [['--port', '--host', '--idle-timeout', '--stop'], 'Foreground fixed production output; reuse intact build, preserve owner/state, idle timeout and explicit stop.'],
- build: [[], 'Production build with private local settings excluded and restored.'],
+ build: [['--site'], 'Production build with private local settings excluded and restored. --site instead writes the static run site (homepage, /run, docs) to its declared folder and prints that folder.'],
  verify: [[], 'Run the complete internal verification target.'],
  reset: [['--yes'], 'Confirmed removal of the declared local inventory only.'],
- deploy: [['--environment', '--dry-run', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port'], 'Owner-account deployment and health; dry run performs local validation/build only.'],
+ deploy: [['--environment', '--dry-run', '--site', '--host', '--env-file', '--image', '--bind-address', '--http-port', '--https-port'], 'Owner-account deployment and health; dry run performs local validation/build only. --site deploys the run site instead: an assets-only Worker on its custom domain with www redirected; with --dry-run it builds the site and prints the plan with no provider request.'],
  export: [['--target', '--output', '--origin', '--session-file'], 'Complete supported installation archive with integrity and exclusions.'],
  import: [['--target', '--input', '--journal', '--origin', '--session-file', '--yes', '--legacy-v1', '--acknowledge-unverified-metadata', '--output'], 'Confirmed atomic restore into an empty destination; --journal LATER_ARCHIVE also fences rows that installation erased since. Backup-only local v1 recovery requires --legacy-v1 --acknowledge-unverified-metadata and a new --output v2 archive; --journal requires normal v2 import.'],
  outbox: [['--port', '--host', '--owner-email', '--open'], 'Credential-free local outbox URL; optional ordinary sign-in request and explicit browser opening.'],

package/cli/dev-identity.mjs

@@ -58,7 +58,8 @@ export function refuseManagedInstallation(...sources) {
 
 // The persona list the running app declares, read with the key header.
 export async function resolvePersona(url, key, as, signal) {
- const response = await fetch(url + '/__dev/personas', { headers: { [DEV_KEY_HEADER]: key }, signal: AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean)) });
+ const { appFetch } = await shared('app-fetch.mjs');
+ const response = await appFetch(url + '/__dev/personas', { headers: { [DEV_KEY_HEADER]: key }, signal: AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean)) });
  if (!response.ok) { await response.body?.cancel(); throw refuse(`The application did not serve dev identity (HTTP ${response.status}). Check its local-only entry.`); }
  const personas = await response.json(), persona = personas.find(entry => entry.as === as);
  if (!persona) throw invalid(`Unknown dev persona ${as}. This app declares: ${personas.map(entry => entry.as).join(', ')}.`);

package/cli/door-mode.mjs

@@ -0,0 +1,134 @@
+// Door mode for one checkout: its saved origin is http://NAME.localhost:PORT,
+// it serves on 127.0.0.1:<OS-assigned port> behind the machine's front door,
+// and its probes go straight to that port (never through the door). A saved
+// 127.0.0.1 origin keeps direct mode; --port and --host always serve directly.
+import { randomBytes } from 'node:crypto';
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { claimSiteName, doorHost, doorOrigin, doorProtocol, doorSecretHeader, doorSite, readDoorState, runningDoor, verifyDoor } from './door.mjs';
+import { refuse } from './errors.mjs';
+import { firstFreePort } from './port.mjs';
+import { localSettingKeys } from './settings.mjs';
+import { shared } from './shared.mjs';
+
+const moveRecord = '.rer/local/door-move.json';
+
+// The enabled door this checkout can use, or a refusal saying why not.
+export async function enabledDoor(env = process.env) {
+ const state = await readDoorState(env);
+ if (!state?.door?.enabled) throw refuse(`The front door is not enabled on this computer (${state?.directory ?? 'RER_DOOR_DIR'}). Enable it with rer door enable, or serve directly with rer dev --direct.`);
+ const running = await runningDoor(env);
+ const protocol = running?.protocol ?? state.door.protocol;
+ if (protocol !== doorProtocol) throw refuse(`The front door speaks protocol ${protocol}, which this checkout's rer (protocol ${doorProtocol}) does not know. Run rer door restart with the installed rer.`);
+ return state.door;
+}
+
+// The listening side of a door origin: 127.0.0.1 on a port the OS assigns,
+// guarded by a secret chosen for this start.
+export function doorSelection(name, port, fields) {
+ return { ...fields, url: doorOrigin(name, port), host: '127.0.0.1', port: 0, explicitPort: false, door: { name, port, host: doorHost(name, port), header: doorSecretHeader, secret: randomBytes(32).toString('base64url') } };
+}
+
+// Selection for a checkout whose saved origin is a door origin, or that asks
+// for the door (--door on a fresh setup). Returns undefined for direct mode.
+export async function selectDoor(project, options, previous, fields) {
+ if (options.port !== undefined || options.host !== undefined || options.direct) return undefined;
+ const saved = previous && doorSite(previous.origin);
+ if (saved) {
+  // A server or setup on a saved origin re-claims the name it names
+  // (registering a checkout that rer door remove unregistered) and never
+  // serves under a name another checkout holds.
+  await enabledDoor();
+  if (['dev', 'preview', 'setup'].includes(options.verb)) await claimSavedName(project, previous.origin);
+  return doorSelection(saved.name, saved.port, fields);
+ }
+ if (!options.door) return undefined;
+ if (previous) throw refuse('This checkout is already set up at ' + previous.origin + '. Move it to the front door with rer dev --door, which keeps its data.');
+ const door = await enabledDoor(), name = await claimSiteName(process.env, project.root, { mode: 'door' });
+ return doorSelection(name, door.port, fields);
+}
+
+// A server on a door origin holds the name that origin names: it registers it
+// again after rer door remove, and refuses when another checkout holds it.
+export async function claimSavedName(project, origin) {
+ const site = doorSite(origin);
+ if (site && (await readDoorState())?.door) await claimSiteName(process.env, project.root, { preferred: site.name, mode: 'door', exact: true });
+}
+
+// Record the server's door route on its registry entry and send rer's own
+// requests for the origin straight to its proxy.
+export async function announceDoorRoute(selected, proxy, registry) {
+ const { routeOrigin } = await shared('app-fetch.mjs');
+ routeOrigin(selected.url, { port: proxy.port, headers: { [doorSecretHeader]: selected.door.secret } });
+ await registry?.update({ port: proxy.port, door: { v: doorProtocol, name: selected.door.name, port: selected.door.port, secret: selected.door.secret } });
+}
+
+// A running server's route, from its registry entry: only while its server
+// process is alive and itself listens on the recorded proxy port, so nothing
+// rer sends (a dev key among it) reaches a process that took that port later.
+export async function routeRunning(record) {
+ if (!record?.door) return;
+ const { alive } = await import('../modules/job-queue/identity.mjs');
+ const { listeners } = await shared('process-diagnostics.mjs');
+ const live = await alive(record.owner).catch(() => false);
+ const holds = live && (await listeners([record.owner.pid])).some(row => row.pid === record.owner.pid && row.names.some(name => /^(?:127\.0\.0\.1|\[?::ffff:127\.0\.0\.1\]?):(\d+)$/.exec(name)?.[1] === String(record.port)));
+ if (!holds) throw refuse(`This checkout's server (PID ${record.owner?.pid}) is not serving on its recorded port 127.0.0.1:${record.port}, so nothing was sent to it. Stop it with rer dev --stop, then start it again with rer dev.`);
+ const { routeOrigin } = await shared('app-fetch.mjs');
+ routeOrigin(record.url, { port: record.port, headers: { [doorSecretHeader]: record.door.secret } });
+}
+
+// Before a dev key is printed for a door origin.
+export async function verifyDoorFor(url) {
+ const site = doorSite(url);
+ if (site) await verifyDoor(process.env, site.port);
+}
+
+// The saved origin, read without changing anything (rer describe).
+export async function savedOrigin(project) {
+ const secrets = project.adapter?.hooks?.secrets;
+ if (!secrets) return null;
+ let text;
+ try { text = await readFile(join(project.root, secrets.file ?? '.dev.vars'), 'utf8'); } catch { return null; }
+ try {
+  const values = (secrets.format ?? 'dotenv') === 'json' ? JSON.parse(text) : (await shared('local/environment.mjs')).localVariables(text);
+  return typeof values?.[localSettingKeys(project).origin] === 'string' ? values[localSettingKeys(project).origin] : null;
+ } catch { return null; }
+}
+
+// rer dev --door / --direct: rewrite only the saved origin, keeping the local
+// database and state. --door records the direct origin it replaces; --direct
+// restores it (or the first free port from 8787, or --port).
+export async function moveCheckout(project, options, out, registry) {
+ const secrets = project.adapter?.hooks?.secrets;
+ if (!secrets) throw refuse('This checkout declares no saved origin, so it cannot move to or from the front door.');
+ const { readSettings, replaceSavedOrigin } = await shared('adapter-settings.mjs');
+ const key = localSettingKeys(project).origin, current = (await readSettings(project.root, secrets)).values[key];
+ if (!current) throw refuse('This checkout is not set up yet. Run rer dev without --door or --direct; with the door enabled it is set up there.');
+ const atDoor = Boolean(doorSite(current));
+ if (options.door === atDoor) return;
+ const running = await registry.existing(options.verb, { ...options, supplied: new Set() });
+ if (running) throw refuse(`Stop this checkout's running server first (rer dev --stop), then move it.`);
+ let target, record;
+ const { privateDirectory, readPrivateFile, writePrivateFile } = await shared('private-files.mjs');
+ if (options.door) {
+  const door = await enabledDoor(), name = await claimSiteName(process.env, project.root, { mode: 'door' });
+  target = doorOrigin(name, door.port);
+  record = { previousOrigin: current, movedAt: new Date().toISOString() };
+ } else {
+  let previous;
+  try { previous = JSON.parse(await readPrivateFile(join(project.root, moveRecord))).previousOrigin; } catch {}
+  target = options.port !== undefined ? `http://127.0.0.1:${options.port}` : previous && !doorSite(previous) ? previous : `http://127.0.0.1:${await firstFreePort('127.0.0.1')}`;
+  const site = doorSite(current);
+  if (site && await readDoorState()) await claimSiteName(process.env, project.root, { preferred: site.name, mode: 'direct', origin: target });
+ }
+ const { localOperation } = await shared('local/operation.mjs');
+ let operation;
+ try { operation = await localOperation(project.root); } catch (error) { throw refuse(error.message); }
+ try {
+  await replaceSavedOrigin(project.root, secrets, target);
+  if (record) { await privateDirectory(project.root, ['.rer', 'local']); await writePrivateFile(join(project.root, moveRecord), JSON.stringify(record) + '\n'); }
+  else await rm(join(project.root, moveRecord), { force: true });
+ } finally { await operation.release(); }
+ const line = options.door ? `Moved this checkout from ${current} to ${target}, through the front door. Its data is kept; rer dev --direct moves it back.` : `Moved this checkout from ${current} back to ${target}. Its data is kept.`;
+ if (options.json) out.event('moved', { from: current, to: target }); else out.human(line);
+}

package/cli/door.mjs

@@ -0,0 +1,263 @@
+// The front door's protocol (version 1). The door itself lives in the global
+// `rer` package, which bundles this file; each checkout's pinned copy reads the
+// same state, so the two meet only here.
+//
+// RER_DOOR_DIR (default ~/.rer/door): a 0700 directory owned by this account,
+// never a link, holding 0600 files:
+//   state.json    door policy, recorded environment and the registered sites
+//                 (and the names removed ones keep reserved)
+//                 (written under the job queue's bakery lock)
+//   token         the door's secret; it proves it holds it before rer prints a key
+//   process.json  the running door: protocol, PID and start, port, addresses,
+//                 version and version directory
+// A checkout keeps its door identity in its own .rer/local/door-site.json
+// ({id}, 0600); a registered site records the same id, so a moved or renamed
+// checkout keeps its name (and with it its origin and sign-in).
+// A checkout in door mode serves on 127.0.0.1:<proxyPort> and records
+// `door: {v, name, port, secret}` on its server-registry entry (also 0600). Its
+// proxy answers only its own Host carrying the per-start secret header, which
+// only the door (and rer's own probes) add.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { chmod, lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { userInfo } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { identity } from '../modules/job-queue/identity.mjs';
+import { processInfo } from '../modules/job-queue/processes.mjs';
+import { transaction } from '../modules/job-queue/storage.mjs';
+import { refuse } from './errors.mjs';
+import { shared } from './shared.mjs';
+
+export const doorProtocol = 1;
+export const defaultDoorPort = 8700;
+export const doorSecretHeader = 'x-rer-door-secret';
+export const doorChallengeHeader = 'x-rer-door-challenge';
+export const doorIdentityPath = '/__rer/door/identity';
+export const doorDefaults = Object.freeze({ serverLimit: 10, idleSeconds: 43200 });
+
+export const doorDirectory = (env = process.env) => resolve(env.RER_DOOR_DIR ?? join(userInfo().homedir, '.rer/door'));
+export const doorOrigin = (name, port) => `http://${name}.localhost:${port}`;
+export const doorHost = (name, port) => `${name}.localhost:${port}`;
+
+// A checkout's name: the DNS-safe slug of its folder name.
+export function siteSlug(path) {
+ return basename(path).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 50).replace(/-+$/, '') || 'site';
+}
+
+// { name, port } when `origin` is exactly a saved front-door origin.
+export function doorSite(origin) {
+ let url; try { url = new URL(origin); } catch { return undefined; }
+ const match = /^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.localhost$/.exec(url.hostname);
+ if (!match || url.protocol !== 'http:' || !url.port || url.origin !== origin) return undefined;
+ return { name: match[1], port: Number(url.port) };
+}
+
+async function ownedDirectory(directory, create) {
+ if (create) await mkdir(directory, { recursive: true, mode: 0o700 });
+ let info;
+ try { info = await lstat(directory); } catch (error) { if (error.code === 'ENOENT' && !create) return false; throw error; }
+ if (info.isSymbolicLink() || !info.isDirectory() || info.uid !== process.getuid()) throw refuse(`The front door directory ${directory} is foreign or linked. Preserve it for inspection and choose an owned RER_DOOR_DIR.`);
+ if (create) await chmod(directory, 0o700);
+ return true;
+}
+
+// A 0600 file in the door directory, or undefined when it does not exist.
+export async function readPrivate(path) {
+ let info;
+ try { info = await lstat(path); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+ if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.uid !== process.getuid()) throw refuse(`${path} is foreign or linked. Preserve it for inspection.`);
+ if ((info.mode & 0o077) !== 0) await chmod(path, 0o600);
+ return readFile(path, 'utf8');
+}
+
+export async function writePrivate(path, text) {
+ const existing = await readPrivate(path);
+ if (existing !== undefined) await chmod(path, 0o600);
+ await writeFile(path, text, { mode: 0o600 });
+ await chmod(path, 0o600);
+}
+
+export async function prepareDoorDirectory(env = process.env) {
+ const directory = doorDirectory(env);
+ await ownedDirectory(directory, true);
+ for (const name of ['locks', 'logs']) await ownedDirectory(join(directory, name), true);
+ return directory;
+}
+
+// The recorded door, read-only: { directory, door, sites } or undefined.
+// `sites` lists registered checkouts only, never a removed one's reservation.
+export async function readDoorState(env = process.env) {
+ const directory = doorDirectory(env);
+ if (!await ownedDirectory(directory, false)) return undefined;
+ const text = await readPrivate(join(directory, 'state.json'));
+ if (text === undefined) return undefined;
+ const state = JSON.parse(text);
+ return state.door ? { directory, door: state.door, sites: (state.sites ?? []).filter(site => !site.removed) } : undefined;
+}
+
+// Change the door state under the lock. `action(state)` edits state.door and
+// state.sites in place. (The lock's own file also keeps empty queue fields.)
+export async function changeDoorState(env, action) {
+ const directory = await prepareDoorDirectory(env);
+ await readPrivate(join(directory, 'state.json'));
+ const lifetime = await identity();
+ try {
+  return await transaction(directory, lifetime.info, async state => { state.sites ??= []; return action(state); });
+ } finally { await lifetime.close(); }
+}
+
+export async function ensureToken(directory) {
+ const path = join(directory, 'token');
+ if (await readPrivate(path) === undefined) await writeFile(path, randomBytes(32).toString('hex') + '\n', { flag: 'wx', mode: 0o600 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+ return (await readPrivate(path)).trim();
+}
+
+// The proof names the loopback address it was asked on, so a process holding
+// one address cannot relay a challenge to the door on the other.
+export const doorProof = (token, challenge, address) => createHmac('sha256', token).update(`rer-door:${address}:${challenge}`).digest('hex');
+
+// The running door's record, when its process is alive: { pid, start, port, ... }.
+export async function runningDoor(env = process.env) {
+ const directory = doorDirectory(env);
+ if (!await ownedDirectory(directory, false)) return undefined;
+ const text = await readPrivate(join(directory, 'process.json'));
+ if (!text) return undefined;
+ const record = JSON.parse(text), current = await processInfo(record.pid);
+ return current && !current.zombie && current.start === record.start ? record : undefined;
+}
+
+// Names are unique and stable per checkout. `rer door remove` keeps a removed
+// checkout's name reserved for it (`removed: true`), because its saved origin
+// still names it: the door stops routing it, no other checkout can claim it,
+// and that checkout's next rer dev or rer door add takes it back. A
+// reservation ends only when its checkout folder no longer exists.
+function releaseVanished(state) {
+ state.sites = state.sites.filter(site => !site.removed || existsSync(site.checkout));
+}
+
+const identityFile = '.rer/local/door-site.json';
+const newIdentity = () => randomBytes(16).toString('hex');
+
+// The door identity a checkout folder holds, or undefined.
+export function checkoutIdentity(root) {
+ try { const id = JSON.parse(readFileSync(join(root, identityFile), 'utf8')).id; return /^[0-9a-f]{32}$/.test(id) ? id : undefined; } catch { return undefined; }
+}
+
+export async function saveCheckoutIdentity(root, id) {
+ if (checkoutIdentity(root) === id) return;
+ const { privateDirectory, writePrivateFile } = await shared('private-files.mjs');
+ await privateDirectory(root, ['.rer', 'local']);
+ await writePrivateFile(join(root, identityFile), JSON.stringify({ id }) + '\n');
+}
+
+// In a door state being changed: the checkout's entry, claiming a name when it
+// has none (its slug, or `preferred`, with a numeric suffix when another
+// checkout holds that name). A removed entry is registered again.
+// `id` is the identity the checkout folder holds (undefined when it holds
+// none). A checkout is found by its folder, or else by its identity: a
+// registered checkout whose folder no longer holds that identity has moved,
+// and its entry follows it to the new folder, name and all. A copy (whose
+// identity the original folder still holds) is a checkout of its own and gets
+// a new identity. An entry registered before checkouts kept an identity
+// follows a checkout whose saved origin names it (`preferred`) once its own
+// folder is gone. The caller saves `entry.id` in the checkout folder.
+// `holder` names the checkout that holds `preferred` when it is not this one.
+export function claimEntry(state, checkout, preferred, id) {
+ releaseVanished(state);
+ // By folder, unless that folder now holds another checkout's identity.
+ let entry = state.sites.find(site => site.checkout === checkout && !(site.id && id && site.id !== id)), copy = false;
+ if (!entry && id) {
+  const prior = state.sites.find(site => site.id === id);
+  if (prior && checkoutIdentity(prior.checkout) !== id) entry = Object.assign(prior, { checkout, movedAt: Date.now() });
+  else copy = Boolean(prior);
+ }
+ if (!entry && preferred) {
+  const named = state.sites.find(site => site.name === preferred && !site.id && !existsSync(site.checkout));
+  if (named) entry = Object.assign(named, { checkout, movedAt: Date.now() });
+ }
+ if (entry) delete entry.removed;
+ else {
+  const taken = new Set(state.sites.map(site => site.name)), base = preferred ?? siteSlug(checkout);
+  let name = base;
+  for (let suffix = 2; taken.has(name); suffix++) name = `${base}-${suffix}`;
+  entry = { name, checkout, addedAt: Date.now() };
+  state.sites.push(entry);
+ }
+ entry.id ??= copy || !id ? newIdentity() : id;
+ const holder = preferred && entry.name !== preferred ? state.sites.find(site => site.name === preferred) : undefined;
+ return { entry, holder };
+}
+
+// A checkout's registered name, claiming one when it has none. `mode` (door or
+// direct) and a direct `origin` are kept on the entry for listings while the
+// checkout is stopped. With `exact` (a saved door origin, which names its
+// host), the claim must give `preferred` itself: when another checkout holds
+// it, or this checkout is registered under another name, nothing changes and
+// rer refuses, so a name and its cookies never reach a second checkout.
+export async function claimSiteName(env, checkout, { preferred, mode, origin, exact = false } = {}) {
+ const describe = entry => { if (mode) entry.mode = mode; if (origin) entry.origin = origin; else if (mode === 'door') delete entry.origin; };
+ const held = checkoutIdentity(checkout);
+ const claimed = await changeDoorState(env, state => {
+  const { entry, holder } = claimEntry(state, checkout, preferred, held);
+  if (exact && entry.name !== preferred) throw refuse(holder
+   ? `This checkout's saved origin names ${preferred}.localhost, which the front door has registered for another checkout (${holder.checkout}). Nothing was started and no sign-in link was printed. Give this checkout its own name: rer dev --direct, then rer dev --door.`
+   : `This checkout's saved origin names ${preferred}.localhost, but the front door has it registered as ${entry.name}. Nothing was started and no sign-in link was printed. Move it again: rer dev --direct, then rer dev --door.`);
+  describe(entry);
+  return { name: entry.name, id: entry.id };
+ });
+ await saveCheckoutIdentity(checkout, claimed.id);
+ return claimed.name;
+}
+
+const portOf = name => Number(/:(\d+)$/.exec(name)?.[1]);
+
+async function challenge(host, port, token) {
+ const { loopbackRequest } = await shared('app-fetch.mjs');
+ const nonce = randomBytes(24).toString('hex');
+ const reply = await loopbackRequest({ host, port, path: doorIdentityPath, headers: { host: `localhost:${port}`, [doorChallengeHeader]: nonce }, timeoutMs: 5000 });
+ let answer; try { answer = JSON.parse(reply.body.toString('utf8')); } catch {}
+ const expected = Buffer.from(doorProof(token, nonce, host)), given = Buffer.from(String(answer?.proof ?? ''));
+ return reply.status === 200 && given.length === expected.length && timingSafeEqual(given, expected) ? answer : undefined;
+}
+
+// Before rer prints a dev key for a door origin on port `port`: every loopback
+// listener on it must belong to the door PID recorded in its state, and the
+// door must prove it holds the 0600 token on each address it serves. While
+// `rer door restart` (or enable) replaces the door (`restarting` in its state,
+// for at most restartWindowMs), a failed check is repeated until the new door
+// passes it, so a start under way finishes against the new door.
+export const restartWindowMs = 90_000;
+export async function verifyDoor(env, port) {
+ for (;;) {
+  try { return await verifyOnce(env, port); }
+  catch (error) {
+   const since = (await readDoorState(env).catch(() => undefined))?.door?.restarting;
+   if (!(Date.now() - since < restartWindowMs)) throw error;
+   await delay(250);
+  }
+ }
+}
+
+async function verifyOnce(env, port) {
+ const directory = doorDirectory(env), record = await runningDoor(env);
+ const { listeners, processName } = await shared('process-diagnostics.mjs');
+ const holders = (await listeners()).filter(row => row.names.some(name => portOf(name) === port));
+ const foreign = holders.find(row => row.pid !== record?.pid);
+ const withheld = 'No sign-in link was printed.';
+ if (foreign) throw refuse(`Port ${port} is held by PID ${foreign.pid} (${await processName(foreign.pid)}), which is not this account's front door${record ? ` (PID ${record.pid})` : ''}. ${withheld} Stop PID ${foreign.pid}, then run rer door restart.`);
+ if (!record || record.port !== port) throw refuse(`The front door is not running on port ${port}. ${withheld} Start it with rer door start, then run this again.`);
+ const token = (await readPrivate(join(directory, 'token')))?.trim();
+ if (!token) throw refuse(`The front door's token is missing from ${directory}. ${withheld} Run rer door restart.`);
+ for (const host of ['127.0.0.1', '::1']) {
+  let answer;
+  try { answer = await challenge(host, port, token); }
+  catch (error) {
+   // No IPv6 loopback, or nothing on [::1]:P while the door serves only 127.0.0.1.
+   if (host === '::1' && ['ECONNREFUSED', 'EADDRNOTAVAIL', 'EAFNOSUPPORT', 'ENETUNREACH'].includes(error.code) && !record.addresses?.includes('::1')) continue;
+   throw refuse(`The front door (PID ${record.pid}) did not answer on ${host === '::1' ? '[::1]' : host}:${port}: ${error.code ?? error.message}. ${withheld} Run rer door restart.`);
+  }
+  if (!answer || answer.pid !== record.pid) throw refuse(`Something other than this account's front door (PID ${record.pid}) answers on ${host === '::1' ? '[::1]' : host}:${port}. ${withheld} Find and stop it, then run rer door restart.`);
+ }
+ return record;
+}