@runeditrun/rer 0.1.0 → 0.2.0

package/global/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
@@ -117,7 +121,10 @@ override the choice, and `--json` prints `progress` events and the ready event.
 first launch can take minutes: it prints a progress line at least every 30
 seconds, and if the calling command is killed the launch carries on; run
 `rer dev` again to reattach. A second `rer dev` reprints the ready lines.
-`rer dev --stop` stops the server.
+`rer dev --stop` stops the server, or a launch still preparing (which then
+reports that it was stopped), waits until every process they started has
+exited and says what it stopped; if any is still running it exits non-zero
+naming their PIDs.
 
 Servers started through `rer` (`rer dev`, `rer preview`) get a 10-server limit and a 12-hour idle timeout
 unless you set `RER_SERVER_LIMIT`, `RER_SERVER_IDLE_SECONDS` or `--idle-timeout`.
@@ -127,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
@@ -141,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`
@@ -150,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/global/checkout.mjs

@@ -2,6 +2,7 @@
 // above the working directory, or exactly --cwd DIR. Then pick whose code runs it.
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { exactVersion } from '../cli/package-mode.mjs';
 import { ownRoot, packageName } from './package-info.mjs';
 
 // The value of --cwd among the wrapper flags (never after a -- separator).
@@ -53,19 +54,32 @@ export function unsupportedMessage(root, version) {
  return `${join(root, 'OPERATIONS.json')} is an OPERATIONS version ${version ?? '(none)'} descriptor, which rer does not run. Use the commands that project documents, or move it to OPERATIONS version 2.`;
 }
 
-function declaresPackage(root) {
- try {
-  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
-  return Boolean(manifest.dependencies?.[packageName] ?? manifest.devDependencies?.[packageName]);
- } catch { return false; }
+// The rer package a checkout pins in package.json (package mode): the declared
+// specifier, the version node_modules holds, and whether that installed copy is
+// the one to run (`ready`: present, and equal to an exact pin). undefined for a
+// checkout that does not declare it.
+export function pinnedPackage(root) {
+ let manifest;
+ try { manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); } catch { return undefined; }
+ const declared = manifest.devDependencies?.[packageName] ?? manifest.dependencies?.[packageName];
+ if (!declared) return undefined;
+ let installed;
+ try { installed = JSON.parse(readFileSync(join(root, 'node_modules', packageName, 'package.json'), 'utf8')).version; } catch {}
+ return { declared, installed, ready: installed !== undefined && (installed === declared || !exactVersion.test(declared)) };
 }
 
-// 1. the checkout's own pinned package, 2. its vendored scripts/rer.mjs,
-// 3. this package's bundled dispatcher.
+// What runs a checkout's verbs: `entry` is the dispatcher (the verbs
+// themselves) and, for a pinned package, `launcher` is its own rer command.
+// 1. the checkout's own pinned package, once node_modules holds the version
+// package.json pins (see pinnedPackage), 2. its vendored scripts/rer.mjs, 3. this package's
+// bundled dispatcher.
 export function dispatcher(root) {
- if (root && declaresPackage(root)) {
-  const pinned = join(root, 'node_modules', packageName);
-  if (existsSync(join(pinned, 'global/rer.mjs')) && realpathSync(pinned) !== ownRoot) return { mode: 'package', entry: join(realpathSync(pinned), 'global/rer.mjs') };
+ const pinned = root ? pinnedPackage(root) : undefined;
+ if (pinned?.ready) {
+  const location = realpathSync(join(root, 'node_modules', packageName));
+  // This package is that pin: it runs the checkout itself, whatever else the checkout holds.
+  if (location === ownRoot) return { mode: 'bundled', entry: join(ownRoot, 'bin/rer.mjs') };
+  if (existsSync(join(location, 'global/rer.mjs'))) return { mode: 'package', entry: join(location, 'bin/rer.mjs'), launcher: join(location, 'global/rer.mjs') };
  }
  if (root && existsSync(join(root, 'scripts/rer.mjs'))) return { mode: 'vendored', entry: join(root, 'scripts/rer.mjs') };
  return { mode: 'bundled', entry: join(ownRoot, 'bin/rer.mjs') };

package/global/cli/install.mjs

@@ -2,10 +2,11 @@
 // version directory, switch `current` atomically, keep the previous version,
 // prune older ones and write the launcher. Never edits shell profiles.
 import { randomUUID } from 'node:crypto';
-import { chmod, cp, mkdir, readdir, readlink, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import { chmod, cp, mkdir, readdir, readlink, realpath, rename, rm, symlink, writeFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
 import { ownManifest, ownRoot, packageDigest, packageFileList } from '../package-info.mjs';
 import { installRecord, launcherOwner, launcherScript, layout } from './layout.mjs';
+import { runningDoor } from '../../cli/door.mjs';
 
 async function readLink(path) { try { return await readlink(path); } catch (error) { if (['ENOENT', 'EINVAL'].includes(error.code)) return undefined; throw error; } }
 
@@ -66,7 +67,10 @@ export async function install() {
  if (!present) { await rm(join(paths.versions, name), { recursive: true, force: true }); await copyVersion(paths, name); }
  const previousName = current?.startsWith('versions/') && current !== join('versions', name) ? current.slice('versions/'.length) : record?.previous;
  if (current !== join('versions', name)) await switchCurrent(paths, name);
- const keep = new Set([name, previousName].filter(Boolean));
+ // A running front door keeps running from its own version: never prune it.
+ const door = await runningDoor().catch(() => undefined);
+ const doorVersion = door?.versionDir && resolve(door.versionDir, '..') === await realpath(paths.versions).catch(() => resolve(paths.versions)) ? basename(door.versionDir) : undefined;
+ const keep = new Set([name, previousName, doorVersion].filter(Boolean));
  for (const entry of await readdir(paths.versions)) if (!keep.has(entry) && !entry.startsWith('.staging-')) await rm(join(paths.versions, entry), { recursive: true, force: true });
  await writeFile(paths.record, JSON.stringify({ channel, previous: previousName && keep.has(previousName) ? previousName : null }, null, 2) + '\n', { mode: 0o644 });
  if (launcher.text !== script) await writeLauncher(paths);

package/global/delegate.mjs

@@ -1,13 +1,15 @@
-// Run an invocation with the checkout's own dispatcher, in this process, exactly
-// as `node scripts/rer.mjs ...` would from the project root: process.argv[1] is
-// that file, so its Node-pin re-exec and queued child spawns behave as they do
-// when it is run directly. The dispatcher sets process.exitCode itself.
+// Run an invocation with the checkout's own rer, in this process. A pinned
+// package runs it with its own rer command, so launching is its own too. A
+// vendored or bundled dispatcher runs it exactly as `node scripts/rer.mjs ...`
+// would from the project root: process.argv[1] is that file, so its Node-pin
+// re-exec and queued child spawns behave as they do when it is run directly.
+// The dispatcher sets process.exitCode itself.
 import { pathToFileURL } from 'node:url';
 import { dispatcher } from './checkout.mjs';
 
 export async function delegate(target, args) {
- const { entry } = dispatcher(target.root);
+ const { entry, launcher } = dispatcher(target.root);
  if (target.root) process.chdir(target.root);
- process.argv = [process.argv[0], entry, ...args];
- await import(pathToFileURL(entry).href);
+ process.argv = [process.argv[0], launcher ?? entry, ...args];
+ await import(pathToFileURL(launcher ?? entry).href);
 }

package/global/door/command.mjs

@@ -0,0 +1,254 @@
+// rer door: the opt-in front door. One process on one port serves every
+// registered checkout at http://NAME.localhost:PORT, starting it on its first
+// visit and stopping it when idle.
+import { readFile, realpath } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { changeDoorState, checkoutIdentity, claimEntry, defaultDoorPort, doorOrigin, doorProtocol, doorSite, ensureToken, prepareDoorDirectory, readDoorState, runningDoor, saveCheckoutIdentity, verifyDoor } from '../../cli/door.mjs';
+import { openUrl, readDevKey } from '../../cli/dev-identity.mjs';
+import { descriptorProfile, dispatcher, unsupportedMessage } from '../checkout.mjs';
+import { describeCheckout } from '../launch/facts.mjs';
+import { ownManifest } from '../package-info.mjs';
+import { DoorFailure, startDoor, stopDoor } from './control.mjs';
+import { rebootNote } from './pages.mjs';
+import { enabledPolicy } from './policy.mjs';
+import { doorSites } from './sites.mjs';
+
+export const doorHelp = `Usage: rer door VERB
+
+The front door serves every registered checkout at http://NAME.localhost:PORT
+from one process on one port. A checkout starts on its first visit in a browser
+and stops when idle. It is opt-in for this computer.
+
+  rer door enable [--port N] [--server-limit N] [--idle-timeout S]
+                        Opt this computer in, record the policy and start the door.
+                        Defaults: port 8700, 10 servers, 43200 s (12 hours) idle.
+                        The policy and the RER_* variables in effect now are stored;
+                        sites the door starts get those, never another shell's.
+  rer door disable      Stop the door and opt this computer out.
+  rer door start        Start the enabled door (needed after a reboot or logout).
+  rer door stop         Stop the door. Running sites keep running until idle.
+  rer door restart      Drain and restart the door; open tabs reconnect.
+  rer door add [PATH ...]
+                        Register checkouts (default: here) for lazy start, printing
+                        each URL and, for a set-up door-mode checkout with dev
+                        identity, a sign-in link that starts it and signs in.
+  rer door remove NAME  Unregister one checkout. Its name stays reserved for it;
+                        rer dev there, or rer door add, registers it again.
+  rer door status [--json] [--links]
+                        The door, its policy and every site with its state and URL;
+                        --links adds sign-in links.
+
+Fresh checkouts launched with rer dev while the door is enabled are set up at
+their door URL. Move an existing one with rer dev --door (rer dev --direct moves
+it back); rer dev --port N always serves directly.
+`;
+
+const out = text => process.stdout.write(text + '\n');
+const err = text => process.stderr.write(text + '\n');
+
+function flags(args, valued, booleans = []) {
+ const result = { positional: [] };
+ for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (valued.includes(arg)) { const value = args[++i]; if (value === undefined || value.startsWith('--')) throw new DoorFailure(2, `${arg} needs a value.`); result[arg] = value; }
+  else if (booleans.includes(arg)) result[arg] = true;
+  else if (arg.startsWith('-')) throw new DoorFailure(2, `Unsupported flag ${arg}. Run rer door --help.`);
+  else result.positional.push(arg);
+ }
+ return result;
+}
+
+async function enabledState(env) {
+ const state = await readDoorState(env);
+ if (!state?.door?.enabled) throw new DoorFailure(3, 'The front door is not enabled on this computer. Enable it with: rer door enable');
+ return state;
+}
+
+function runningLine(door, record) {
+ return `Front door running at http://localhost:${record.port} (PID ${record.pid}, rer ${record.version}); limit ${door.policy.serverLimit} servers, idle stop after ${door.policy.idleSeconds} s.`;
+}
+
+// Replace a running door with a new one: the old one stops accepting, hands
+// the starts under way to the new one and gives up its port at once, then
+// finishes its requests; the new one carries those starts on (each one's own
+// rer dev waits for it before its key is printed) and open tabs reconnect.
+// `change` edits the state between the two (rer door enable's new policy).
+async function replaceDoor(env, change) {
+ const running = await runningDoor(env);
+ if (running) await changeDoorState(env, state => { if (state.door) state.door.restarting = Date.now(); });
+ try {
+  const stopped = running ? await stopDoor(env, { released: true }) : undefined;
+  if (change) await changeDoorState(env, change);
+  const { door } = await startDoor(env);
+  return { stopped, door };
+ } finally { if (running) await changeDoorState(env, state => { if (state.door) delete state.door.restarting; }); }
+}
+
+async function enable(args, env) {
+ const given = flags(args, ['--port', '--server-limit', '--idle-timeout']);
+ if (given.positional.length) throw new DoorFailure(2, 'rer door enable takes only flags. Run rer door --help.');
+ const chosen = enabledPolicy({ port: given['--port'], serverLimit: given['--server-limit'], idleTimeout: given['--idle-timeout'] }, env);
+ const previous = (await readDoorState(env))?.door;
+ const port = chosen.port ?? previous?.port ?? defaultDoorPort;
+ const directory = await prepareDoorDirectory(env);
+ await ensureToken(directory);
+ const { door: record } = await replaceDoor(env, state => {
+  state.door = { protocol: doorProtocol, enabled: true, port, policy: chosen.policy, directory: chosen.directory, serversDir: chosen.serversDir, environment: chosen.environment, started: state.door?.started ?? [], ...(state.door?.handoff ? { handoff: state.door.handoff } : {}), ...(state.door?.restarting ? { restarting: state.door.restarting } : {}), enabledAt: new Date().toISOString() };
+ });
+ out(runningLine({ policy: chosen.policy }, record));
+ if (previous?.port && previous.port !== port) out(`Checkouts already moved to the door keep their saved port ${previous.port}; move each again with rer dev --direct, then rer dev --door.`);
+ out(`Register checkouts with rer door add PATH. ${rebootNote.replace(/<\/?code>/g, '')}`);
+ return 0;
+}
+
+async function disable(args, env) {
+ if (args.length) throw new DoorFailure(2, 'rer door disable takes no arguments.');
+ const stopped = await stopDoor(env);
+ if (await readDoorState(env)) await changeDoorState(env, state => { if (state.door) state.door.enabled = false; });
+ out(`${stopped ? `Stopped the front door (PID ${stopped.pid}). ` : ''}The front door is disabled on this computer. Registered checkouts stay registered; rer door enable turns it back on.`);
+ return 0;
+}
+
+async function start(env) {
+ const state = await enabledState(env);
+ const { door: record, already } = await startDoor(env);
+ out(already ? `The front door is already running (PID ${record.pid}).` : runningLine(state.door, record));
+ return 0;
+}
+
+async function stop(env) {
+ const stopped = await stopDoor(env);
+ out(stopped ? `Stopped the front door (PID ${stopped.pid}). Sites it started keep running until idle; rer door start brings it back.` : 'The front door is not running.');
+ return 0;
+}
+
+async function restart(env) {
+ const state = await enabledState(env);
+ const { stopped, door: record } = await replaceDoor(env);
+ out(`${stopped ? `Drained the front door (PID ${stopped.pid}); open tabs reconnect. ` : ''}${runningLine(state.door, record)}`);
+ return 0;
+}
+
+// The sign-in link for a set-up door-mode checkout with dev identity, after the
+// door proves it is this account's. It carries the checkout's dev key in its
+// fragment: printed for the person, never given to the door.
+async function signInLink(site, port) {
+ if (site.mode !== 'door') return undefined;
+ let key; try { key = await readDevKey(site.path); } catch { return undefined; }
+ return key ? openUrl(doorOrigin(site.name, port), key, { path: '/__dev/key', as: 'owner' }) : undefined;
+}
+
+// A pin from before the door does not describe its saved origin; its direct
+// link is the AUTH_ORIGIN its settings file holds (read only for the link).
+async function oldPinOrigin(root, described) {
+ try {
+  const text = await readFile(join(root, described.local?.settings?.[0] ?? '.dev.vars'), 'utf8');
+  const origin = /^AUTH_ORIGIN=(http:\/\/(?:127\.0\.0\.1|localhost|\[::1\]):\d+)\s*$/m.exec(text)?.[1];
+  return origin ?? null;
+ } catch { return null; }
+}
+
+class NameHeld extends Error {}
+
+async function add(args, env) {
+ const given = flags(args, []);
+ const state = await enabledState(env), port = state.door.port;
+ let verified, verifyError;
+ try { verified = await verifyDoor(env, port); } catch (error) { verifyError = error; }
+ let skipped = 0;
+ for (const path of given.positional.length ? given.positional : ['.']) {
+  let root;
+  try { root = await realpath(resolve(path)); } catch { out(`skipped ${path}: no such folder`); skipped++; continue; }
+  const facts = descriptorProfile(join(root, 'OPERATIONS.json'));
+  if (facts.profile !== 'first-party') {
+   out(`skipped ${path}: ${facts.profile === 'independent' ? 'an independent project; the front door serves first-party checkouts' : facts.profile === 'unreadable' ? 'no readable OPERATIONS.json, so not a first-party checkout' : unsupportedMessage(root, facts.version)}`);
+   skipped++; continue;
+  }
+  let described;
+  try { described = await describeCheckout(root, dispatcher(root).entry, env); } catch (failure) { out(`skipped ${path}: rer describe fails here: ${failure.message.split('\n')[0]}`); skipped++; continue; }
+  const saved = described.local && 'origin' in described.local ? described.local.origin : await oldPinOrigin(root, described), site = saved && doorSite(saved), mode = site && site.port === port ? 'door' : 'direct';
+  // A door-mode checkout's saved origin names its site, so it registers under
+  // that name or not at all; another checkout keeps a name it holds.
+  // A moved or renamed checkout is found by the identity its folder holds.
+  let name, id;
+  try {
+   ({ name, id } = await changeDoorState(env, state => {
+    const { entry, holder } = claimEntry(state, root, site?.name, checkoutIdentity(root));
+    // Thrown, so the state is left as it was.
+    if (mode === 'door' && entry.name !== site.name) throw new NameHeld(holder?.checkout ?? `this checkout under ${entry.name}`);
+    Object.assign(entry, { mode, door: Boolean(described.door) });
+    if (saved && mode === 'direct') entry.origin = saved; else delete entry.origin;
+    return { name: entry.name, id: entry.id };
+   }));
+   await saveCheckoutIdentity(root, id);
+  } catch (error) {
+   if (!(error instanceof NameHeld)) throw error;
+   out(`skipped ${path}: its saved origin names ${site.name}.localhost, which the front door has registered for ${error.message}. Give it its own name with rer dev --direct, then rer dev --door, in ${root}.`);
+   skipped++; continue;
+  }
+  const url = doorOrigin(name, port);
+  out(`${name}  ${url}  (${mode === 'door' ? 'door mode' : `direct${saved ? ` at ${saved}` : ''}; opening the door URL starts it and redirects there`})  ${root}`);
+  if (mode === 'door' && described.local?.devIdentity) {
+   const link = verified && await signInLink({ name, path: root, mode }, port);
+   if (link) out(`  sign in: ${link}`);
+   else if (verifyError) out(`  no sign-in link: ${verifyError.message}`);
+  }
+ }
+ return skipped && skipped === (given.positional.length || 1) ? 3 : 0;
+}
+
+// The checkout keeps its name reserved: its saved origin still names it, so no
+// other checkout may take it, and its own next rer dev (or rer door add)
+// registers it again.
+async function remove(args, env) {
+ const given = flags(args, []);
+ if (given.positional.length !== 1) throw new DoorFailure(2, 'Usage: rer door remove NAME');
+ const [name] = given.positional;
+ const removed = await changeDoorState(env, state => { const site = state.sites.find(item => item.name === name && !item.removed); if (site) site.removed = true; return site; });
+ if (!removed) { err(`No checkout is registered as ${name}. rer door status lists them.`); return 3; }
+ out(`Unregistered ${name} (${removed.checkout}). Its checkout and any running server are untouched, and the name stays reserved for it: rer dev there, or rer door add, registers it again.`);
+ return 0;
+}
+
+async function status(args, env) {
+ const given = flags(args, [], ['--json', '--links']);
+ if (given.positional.length) throw new DoorFailure(2, 'Usage: rer door status [--json] [--links]');
+ const state = await readDoorState(env), record = await runningDoor(env), version = record?.version ?? ownManifest().version;
+ const door = state?.door;
+ const views = door ? await doorSites({ env, door }).views() : [];
+ let linkNote;
+ if (given['--links'] && door) {
+  try {
+   await verifyDoor(env, door.port);
+   for (const view of views) { const link = await signInLink(view, door.port); if (link) view.signIn = link; }
+  } catch (error) { linkNote = error.message; }
+ }
+ const sites = views.map(view => ({ name: view.name, path: view.path, mode: view.mode, state: view.state === 'failed' ? 'stopped' : view.state, url: view.url, ...(view.proxyPort && view.state === 'running' ? { proxyPort: view.proxyPort } : {}), ...(view.signIn ? { signIn: view.signIn } : {}) }));
+ const result = { running: Boolean(record), enabled: Boolean(door?.enabled), port: door?.port ?? record?.port ?? null, pid: record?.pid ?? null, version, policy: door ? { serverLimit: door.policy.serverLimit, idleSeconds: door.policy.idleSeconds } : null, sites };
+ if (given['--json']) { out(JSON.stringify({ ...result, ...(linkNote ? { linksUnavailable: linkNote } : {}), ...(!record && door?.enabled ? { note: 'After a reboot or logout the front door needs rer door start.' } : {}) })); return 0; }
+ if (!door) { out('The front door is not enabled on this computer. Enable it with: rer door enable'); return 0; }
+ out(record ? runningLine(door, record) : door.enabled ? `The front door is enabled on port ${door.port} but not running. Start it with: rer door start` : 'The front door is disabled on this computer. Enable it with: rer door enable');
+ if (sites.length) {
+  const width = Math.max(4, ...sites.map(site => site.name.length));
+  out(`${'NAME'.padEnd(width)}  STATE     MODE    URL`);
+  for (const site of sites) {
+   out(`${site.name.padEnd(width)}  ${site.state.padEnd(8)}  ${site.mode.padEnd(6)}  ${site.url}${site.proxyPort ? `  (proxy 127.0.0.1:${site.proxyPort})` : ''}`);
+   if (site.signIn) out(`${' '.repeat(width)}  sign in: ${site.signIn}`);
+  }
+ } else out('No checkouts are registered. Add one with: rer door add PATH');
+ if (linkNote) out(`No sign-in links: ${linkNote}`);
+ if (!record && door.enabled) out('After a reboot or logout the front door needs rer door start (or any rer dev in a door-mode checkout).');
+ return 0;
+}
+
+export async function doorCommand(args, env = process.env) {
+ // A reader that stops early (rer door status | grep -q) is not a failure.
+ process.stdout.on('error', error => { if (error.code === 'EPIPE') process.exit(0); throw error; });
+ const [verb, ...rest] = args;
+ if (!verb || ['--help', '-h', 'help'].includes(verb) || rest.includes('--help')) { process.stdout.write(doorHelp); return 0; }
+ const verbs = { enable, disable, add, remove, status, start: (_, e) => start(e), stop: (_, e) => stop(e), restart: (_, e) => restart(e) };
+ if (!verbs[verb]) { err(`Unknown rer door command: ${verb}. Run rer door --help.`); return 2; }
+ if (['start', 'stop', 'restart'].includes(verb) && rest.length) { err(`rer door ${verb} takes no arguments.`); return 2; }
+ try { return await verbs[verb](rest, env); }
+ catch (error) { if (error instanceof DoorFailure || error.exitCode) { err(error.message); return error.exitCode ?? 1; } throw error; }
+}

package/global/door/control.mjs

@@ -0,0 +1,65 @@
+// Start and stop the door process. It runs detached from the installed
+// version's own files, with the allowlisted base environment and RER_DOOR_DIR
+// only; its policy comes from the state `rer door enable` recorded.
+import { spawn } from 'node:child_process';
+import { open, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { doorProtocol, prepareDoorDirectory, readDoorState, runningDoor, verifyDoor } from '../../cli/door.mjs';
+import { doorProcessEnvironment } from './policy.mjs';
+
+const serverPath = fileURLToPath(new URL('./server.mjs', import.meta.url));
+
+export class DoorFailure extends Error { constructor(exitCode, message) { super(message); this.exitCode = exitCode; } }
+
+export async function startDoor(env = process.env) {
+ const state = await readDoorState(env);
+ if (!state?.door?.enabled) throw new DoorFailure(3, 'The front door is not enabled on this computer. Enable it with: rer door enable');
+ const running = await runningDoor(env);
+ if (running) {
+  if (running.protocol !== doorProtocol) throw new DoorFailure(4, `A front door speaking protocol ${running.protocol} is running (PID ${running.pid}); this rer speaks protocol ${doorProtocol}. Run rer door restart.`);
+  return { door: running, already: true };
+ }
+ const door = state.door, directory = await prepareDoorDirectory(env), logPath = join(directory, 'logs', 'door.log');
+ const log = await open(logPath, 'a', 0o600), from = (await log.stat()).size;
+ let child, exited, failed;
+ // Listening before anything is awaited: a spawn that fails reports it on the next tick.
+ try {
+  child = spawn(process.execPath, [serverPath], { cwd: directory, env: doorProcessEnvironment(door, env), detached: true, stdio: ['ignore', log.fd, log.fd] });
+  child.once('error', error => { failed = error; exited ??= 1; });
+  child.once('exit', code => { exited = code ?? 1; });
+ } finally { await log.close(); }
+ for (let waited = 0; waited < 20000; waited += 100) {
+  const record = await runningDoor(env);
+  if (record && record.pid === child.pid) { child.unref(); await verifyDoor(env, record.port); return { door: record }; }
+  if (exited !== undefined) {
+   if (failed) throw new DoorFailure(1, `The front door could not be started: ${failed.code ?? failed.message}.`);
+   // Another start (a rer dev bringing the door back) won the port: use that door.
+   if (record?.protocol === doorProtocol) { await verifyDoor(env, record.port); return { door: record, already: true }; }
+   const text = (await readFile(logPath, 'utf8')).slice(from).split('\n').filter(line => line.startsWith('rer door: ')).map(line => line.slice('rer door: '.length));
+   throw new DoorFailure(exited === 4 ? 4 : 1, text.join('\n') || `The front door stopped while starting (exit ${exited}); see ${logPath}.`);
+  }
+  await delay(100);
+ }
+ child.kill('SIGTERM');
+ throw new DoorFailure(1, `The front door did not start within 20 seconds; see ${logPath}.`);
+}
+
+// Stop the recorded door by its PID (after checking its start time) and wait
+// until it has drained and exited, or with `released` (a restart) only until
+// it has given up its port and process record, which it does before draining.
+export async function stopDoor(env = process.env, { timeoutMs = 30000, released = false } = {}) {
+ const running = await runningDoor(env);
+ if (!running) return undefined;
+ try { process.kill(running.pid, 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') throw error; }
+ for (let waited = 0; waited < timeoutMs; waited += 100) {
+  const current = await processInfo(running.pid);
+  // The door removes its own process record as it drains; a stale one names a dead PID.
+  if (!current || current.zombie || current.start !== running.start) return running;
+  if (released && (await runningDoor(env))?.pid !== running.pid) return running;
+  await delay(100);
+ }
+ throw new DoorFailure(1, `The front door (PID ${running.pid}) did not stop within ${timeoutMs / 1000} seconds.`);
+}

package/global/door/cookies.mjs

@@ -0,0 +1,41 @@
+// The door makes every cookie a site sets host-only when its Domain names
+// localhost itself: WebKit stores Domain=localhost (and its dotted spellings,
+// such as localhost. and .localhost.) for every *.localhost site and plain
+// localhost, so one site's cookie would reach every other. It applies to every
+// reply that can carry Set-Cookie: HTTP replies and WebSocket handshake replies.
+
+// A Domain value as a browser reads it: whitespace and quotes trimmed, leading
+// and trailing dots ignored, any letter case.
+const namesLocalhost = value => value.trim().replace(/^"(.*)"$/, '$1').trim().replace(/^\.+|\.+$/g, '').toLowerCase() === 'localhost';
+
+// One Set-Cookie value with each Domain attribute that names localhost removed.
+export function hostOnlyCookie(value) {
+ const [pair, ...attributes] = String(value).split(';');
+ const kept = attributes.filter(attribute => {
+  const at = attribute.indexOf('=');
+  return at < 0 || attribute.slice(0, at).trim().toLowerCase() !== 'domain' || !namesLocalhost(attribute.slice(at + 1));
+ });
+ return [pair, ...kept].join(';');
+}
+
+// An HTTP response head (status line and headers, without the blank line) as
+// bytes, read the way browsers read it (CRLF or bare LF line ends, folded
+// continuation lines joined), with every Set-Cookie made host-only.
+export function hostOnlyHead(head) {
+ const lines = [];
+ for (const line of head.toString('latin1').split(/\r?\n/)) {
+  if (/^[ \t]/.test(line) && lines.length > 1) lines[lines.length - 1] += ' ' + line.trim();
+  else lines.push(line);
+ }
+ return Buffer.from(lines.map((line, index) => {
+  const at = line.indexOf(':');
+  return index > 0 && at > 0 && line.slice(0, at).trim().toLowerCase() === 'set-cookie' ? `${line.slice(0, at)}: ${hostOnlyCookie(line.slice(at + 1).trim())}` : line;
+ }).join('\r\n') + '\r\n\r\n', 'latin1');
+}
+
+// The end of a response head in `buffer`: { head, rest }, or undefined while
+// the blank line has not arrived.
+export function splitHead(buffer) {
+ const match = /\r?\n\r?\n/.exec(buffer.toString('latin1'));
+ return match && { head: buffer.subarray(0, match.index), rest: buffer.subarray(match.index + match[0].length) };
+}