@runeditrun/rer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Run Edit Run
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# rer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`rer` is the Run Edit Run command. Install it once, then run `rer <verb>` in any
+Run Edit Run checkout: every verb runs that checkout's own pinned copy, so a
+checkout always gets the behaviour it was built and tested with.
+
+## Install
+
+Any one of these leaves `rer` on your PATH:
+
+```sh
+npx -y @runeditrun/rer cli install                # user install in ~/.local/share/rer, launcher ~/.local/bin/rer
+curl -fsSL https://runeditrun.com/install.sh | sh  # the same user install, without npm
+npm install -g @runeditrun/rer                    # npm's own global layout
+```
+
+`install.sh` is the file at the root of this package. It reads the version, the
+tarball and its sha512 integrity from the npm registry (`npm_config_registry`,
+default `https://registry.npmjs.org`; `RER_VERSION=X` pins an exact version,
+otherwise the latest), checks the download's integrity, file count and size,
+refuses archives with absolute paths, `..` entries, links or devices, then runs
+the package's own `rer cli install`. A failed or refused download leaves the
+version you had selected.
+
+No installer edits shell profiles. When `~/.local/bin` is not on your PATH, the
+install prints the exact line to add for your shell. The launcher runs `node` from
+PATH, so a Node upgrade does not break it. A re-run with the same build changes
+nothing; a different build is installed beside the current one, the previous one
+is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
+that it did not write.
+
+`rer --version` prints this rer's version; inside a checkout a second line
+names the version the checkout pins, or says that its vendored copy is
+unversioned (exported before copies recorded one).
+
+`rer cli status` shows the version, the digest of the installed contents, the
+install channel (`npx`, `script` or `npm-global`), the launcher, the install root
+and every other `rer` on PATH. `rer cli uninstall` removes the launcher and the
+install root it runs only; `~/.rer` (servers, jobs, Node runtimes) is untouched.
+An npm global `rer` prints its `npm uninstall -g` command and leaves a user
+install in place.
+
+### Requirements
+
+- macOS or Linux, on x64 or arm64. WSL2 counts as Linux.
+- Node 22 or later on PATH; `rer` stops with one line naming the minimum on an
+  older Node.
+- For `install.sh`: `curl` and `tar`.
+- For `rer dev` in a checkout: the checkout's own package manager (pnpm for
+  Run Edit Run seeds).
+
+Not supported: native Windows (`install.sh` and `rer` say to use WSL2), and
+`OPERATIONS.json` version 1 projects.
+
+## Update
+
+```sh
+rer update               # the latest published version
+rer update --version X   # exactly X
+```
+
+`rer update` follows the way `rer` was installed. A user install (`npx` or
+`install.sh`) downloads the version from the registry, checks it as `install.sh`
+does and switches to it atomically, keeping the previous version and the same
+channel; a damaged or mismatched download leaves the current version selected.
+It says "already current" when the registry's version has the same contents. A
+development build (`<version>-dev.g<sha8>`) moves to the release once that
+version is published, and a different build of the same version counts as an
+update. An npm global install runs `npm install -g @runeditrun/rer@X` for its own
+prefix; when npm fails (for example, a prefix only root can write), `rer update`
+exits non-zero with npm's message and the exact command to run.
+
+In a terminal, `rer` checks the registry at most once a day and prints one line
+when a newer version is published. It never prints in `--json` output or when
+output is not a terminal, never delays a command by more than about 1.5 seconds,
+and `RER_NO_UPDATE_CHECK=1` turns it off.
+
+## Launch a checkout
+
+```sh
+rer dev
+```
+
+In a first-party checkout this is the whole launch. It installs dependencies when
+`node_modules` is missing, incomplete (no `node_modules/.modules.yaml`, or an
+install a launch started did not finish) or older than the lockfile, sets up a local owner
+(`owner@<checkout-name>.test`) on the first free port from 8787 when the checkout
+has never been set up (`--port N` picks the port), fills any setup answer the
+seed declares a `localDefault` for in `rer-setup.json` (a literal, a generated
+secret kept only in the checkout's private settings, or the chosen local
+origin), starts the app and prints:
+
+```
+RER_READY http://127.0.0.1:8787
+RER_SIGNED_IN owner@cradle.test
+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.
+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
+there since (for example your own `rer setup`). A checkout whose pin reports it is
+not set up (`rer describe`'s `local.prepared`) but that already holds an owner
+(`local.ownerSaved`, for example when a newer manifest requires another setting)
+finishes setup keeping that owner and origin. A required setup answer with no value and no
+`localDefault` stops the launch with exit 3 and setup's message naming it.
+
+Inside a checkout `rer` acts on the nearest `OPERATIONS.json` at or above the
+working directory; `--cwd DIR` names the project root itself, exactly as
+`node scripts/rer.mjs` reads it.
+
+Without a terminal (an agent's shell tool) it returns as soon as the app is ready
+and leaves it running, printing the server's private log path; in a terminal it
+stays in the foreground and Ctrl-C stops it. `--detach` and `--foreground`
+override the choice, and `--json` prints `progress` events and the ready event. A
+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.
+
+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`.
+`rer` supplies them only to checkouts whose pinned copy applies lower defaults
+or does not report its own (`rer describe` reports `defaults`), so a current
+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.
+
+## Find what to launch
+
+```sh
+rer list [DIR] [--json]
+```
+
+lists the checkouts in a folder, newest change first, with their profile
+(`first-party`, `independent` or `unsupported`), whether `rer dev` can launch
+them, whether they are set up, and their running URL.
+
+Independent projects (an `OPERATIONS.json` version 2 without a seed contract) run
+their declared commands with `rer <verb> [-- args]`; zero-setup launching does not
+apply to them. `OPERATIONS.json` version 1 is not supported.
+
+## Verbs
+
+In a checkout, every verb runs that checkout's own pinned `rer`; `rer VERB --help`
+there lists its flags:
+
+`install`, `setup`, `dev`, `preview`, `build`, `verify`, `reset --yes`, `deploy`,
+`export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`.
+
+Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
+`rer --version` and `rer --help`.
+
+Licence: MIT.

package/bin/rer.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../cli/main.mjs';
+process.exitCode = await main();

package/cli/README.md

@@ -0,0 +1,243 @@
+# Portable command sources
+
+`bin/rer.mjs` dispatches `cli/main.mjs`. Parsing/contract declarations, project
+resolution, output/exits, shared lifecycle orchestration, local state/reset,
+transfers, independent argv and diagnostics are separate modules. `dev-identity.mjs`
+holds the per-checkout dev key (`.rer/local/dev-key.env`), the `RER_OPEN` URL,
+the managed-installation refusal and the build-output dev-layer scan. Release retains
+its own compatibility parser and producer and does not use the generic executor.
+
+The browser installer that `rer install` opens, and Base's sign-in confirmation and
+`/setup` frames, wear the seed's declared theme (`public/rer-theme.css`); the
+contract and token table are under "Seed theme" in `onboarding/README.md`.
+
+`node scripts/export-cli.mjs SEED_ROOT` copies the deterministic `sourceRoots`
+in `cli/export.mjs`, preserving their relative topology under
+`scripts/base-cli/`. `inventory.json` lists every source and SHA-256. Python
+publication tooling and its data are included for release. The thin seed
+`scripts/rer.mjs` dispatches that copy. `cli/shared.mjs` is the sole relocation
+boundary and imports the existing `scripts/base-onboarding/`; no second onboarding
+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-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
+not substitute an application fixture. Frozen dependency installation occurs
+separately. Refresh copied sources with the export tools after shared edits.
+
+Every first-party seed declares `commandAdapter` alongside its installer hooks.
+`localInstaller.run` supplies shared setup lifecycle behavior; the RER command
+path propagates failures as nonzero exits. Setup and the seed's configured local
+workflow use `onboarding/commands.mjs`, local locks/recovery and the same
+owner/sign-in hooks. The reference hook declaration is
+`onboarding/operator-installer.mjs`. Seeds own answers, real migrations,
+internal build/dev/verify targets and deployment policy. The CLI owns flags,
+pins, containment, cancellation, capture, output and sequencing.
+
+Successful terminal setup saves declared nonsecret installer answers in owned
+0600 storage under `.seed/installer`. A non-interactive repeat reuses those
+answers, with explicit flags or an answers file taking precedence. Runtime
+bindings remain separate: a local mail transport need not be a hosted setup
+choice. Retained settings still determine secret readiness and owner conflicts;
+setup never rebinds an existing owner. A newly required unanswered field causes
+exit 3 with its manifest name and accepted input shape. Reset clears the saved
+answers with the rest of the local installer state.
+For older installations without an answer record, a runtime selection outside
+the installer field's choices cannot replace an adapter-declared local choice.
+Explicit answers and recorded installer choices still undergo strict validation.
+
+Local `export --output FILE` and `import --input FILE --yes` use the Base
+portability implementation through the shared command runner and real Wrangler
+bindings. Seed adapters declare their database, buckets and archive policy.
+Export writes a new 0600 archive and reports its verified content hash, resource
+counts, exclusions and configuration names. Import applies migrations, verifies
+the archive and restores atomically into an empty destination. Stop dev or
+preview before either operation. `import --journal LATER_ARCHIVE` also applies
+the erasure journal of a later archive from the same installation, so a fresh
+destination refuses rows erased since. Erasure-fence refusals (`erased_row`,
+`erasure_epoch`, `later_journal`) exit 4. Reset preserves exports. Remote transfer is
+available only when the adapter declares complete resource coverage; an
+unsupported target exits 4.
+
+Local D1 transfer includes SQLite VIRTUAL and STORED generated columns. Archives
+retain their schema and carry only writable base cells; native expressions and
+indexes in the migrated destination recompute on restore. The public runner's
+generated-column journey compares every visible SQL cell as well as the archived
+base rows across a fresh installation. Ordinary-table archives from before this
+support remain compatible with the same schema.
+
+Every first-party seed verifies local export/import/export equivalence for its
+supported domain and resource data. In default-seed, each export advances the
+included authority generation, so archive hashes may differ even when retained
+domain and identity rows are equal. The technical foundation currently has no
+product domain or background jobs; default-seed retains its durable jobs and
+schedule records while omitting transient queue delivery state, local runtime
+caches and logs, local outbox, transfer bookkeeping, provider credentials,
+provider link keys and transient provider sessions. People, external identity
+bindings, the installation sector and the original owner claim are retained.
+Retained dependency links are marked as needing re-link, and provider sign-in
+and first-setup enablement are off after import. Restore does not re-dispatch
+jobs. Run setup after restore to create local configuration and initiate the
+owner-approved provider re-link. The original owner recovers access through
+ordinary native sign-in; setup does not grant a new owner. A new binding or
+product effect needs an explicit policy and integrated proof.
+
+Setup reads the declared `rer-setup.json` with the shared reader and validates
+answers against the shared manifest model. The manifest owns fields and managed
+secret generation. `--owner-email` maps to its owner-claim email field; private
+`--answers` uses declared field names. Existing owner, settings and data are kept.
+The owner name is prompted or defaulted only when the installer model declares
+the adapter's name field (normally `displayName`). Nameless installers proceed
+without it and refuse `--owner-name`.
+
+Run `node --test --test-concurrency=2 cli/*.test.mjs` from Base. Base's shared tests
+stay in Base; exported seeds carry runtime source and their own adopting tests.
+
+## Managed local serving
+
+Choose `pnpm run preview` for a fixed production build and `pnpm run dev` for
+source editing with Vite HMR. Preview fingerprints actual source, configuration,
+lockfiles, tool versions and output bytes in a nonsecret `.rer/local` receipt;
+changed or incomplete output is rebuilt. Changes made while serving do not
+rebuild preview. A build that regenerates its own files declares them as
+`generatedOutputs` on the command adapter (see the seed command contract); those
+paths are not inputs, while any other file touched during the build is refused by name. Both use the same `.wrangler/state`, saved owner and ordinary
+fresh sign-in through the development outbox. Stop before changing modes.
+Stop dev or preview before build, verification or data transfer; use the
+documented `--stop` flag or Ctrl-C.
+
+The shared public dev/preview proxy gives font bytes a real browser cache
+lifetime so dev stylesheet replacement does not revalidate them on every page
+load. Package fonts and content-hashed URLs are public and immutable for a year;
+unhashed source fonts are public and fresh for an hour. Other response headers
+are preserved, including CSS/JavaScript font imports and error responses. After
+editing a font, hard reload the browser to fetch the changed bytes. Preview
+continues to serve its fixed build; stop and restart it to rebuild edited source.
+Existing seeds receive this policy by refreshing `scripts/base-cli/` with
+`node scripts/export-cli.mjs SEED_ROOT` from Base (which also refreshes its paired
+onboarding copy). For production, adopt the persistent root-head stylesheet,
+primary preload and matched fallback described in `export/UI-CONVENTIONS.md`.
+
+Both are managed foreground servers; their first invocation stays active while
+serving. A compatible repeated invocation verifies the registered application,
+prints its safe ready/outbox URLs and exits without a new build or sign-in.
+Explicit conflicting host, port or timeout, or the other mode, refuses with
+exit 4 and the correct stop command. `--stop` is idempotent;
+start-only flags cannot accompany it. It requires no setup or tool versions.
+
+### Scheduled triggers under dev
+
+`rer dev` runs the Cron Triggers a project declares (`triggers.crons` in
+`wrangler.jsonc` or `wrangler.json`) on their schedule, so alert evaluation,
+retries and checks work on the owner's computer as they do deployed. Each
+minute the CLI calls the local runtime's scheduled test endpoint
+(`/cdn-cgi/handler/scheduled?cron=EXPRESSION`) for every trigger whose
+expression matches, in UTC, and prints one line per run:
+`RER_SCHEDULED 2026-10-10T18:32:00Z "* * * * *" ok 7ms` (or `failed (HTTP 500) ...`;
+`--json` emits a `scheduled` event with `cron`, `ok`, `status`, `ms`). A run that
+is still going when its next minute arrives is reported as skipped. The grammar
+is the one the deploy kit accepts: five numeric fields with lists, ranges and
+steps, day of week 1 (Sunday) to 7; anything else refuses `dev` at start by
+name. Runs go straight to the runtime, so they do not count as activity for the
+idle timeout, and they stop with `dev` (explicit stop, idle timeout, Ctrl-C or
+an application exit). `preview` does not run schedules. A seed that does not
+want this declares one adapter option: `commandAdapter(lifecycle, { scheduled: false, ... })`.
+
+### The CLI's own sign-in requests
+
+`setup` and every `dev` start ask the local application for one ordinary
+sign-in message (and `setup` claims the first owner) so the outbox is ready.
+Those requests carry `x-rer-local-cli`, an HMAC-SHA256 of `local-cli\0sign-in`
+keyed by the installation's private session secret (the setting the adapter
+declares as `sessionSecretKey`, default `SESSION_SECRET`)
+(`onboarding/adapter-auth.mjs`; checked in
+`modules/operator-auth/local-cli.mjs`). A server in local (loopback) mode skips
+the sign-in and owner-claim rate limit for a request with a valid proof, so
+restarting `dev` any number of times never spends the owner's sign-in budget; a
+person's own sign-in requests, and every request to a non-local server, still
+count exactly as before. Seeds receive the change by refreshing their copies as
+described above.
+
+Idle timeout is `--idle-timeout SECONDS`, then `RER_SERVER_IDLE_SECONDS`, then
+43200 seconds (12 hours). Only positive integer seconds are accepted. HTTP requests,
+including assets/outbox, reset inactivity; a live request/stream prevents idle
+shutdown. Internal health probes and Vite HMR control traffic do not prolong
+serving; application WebSocket data messages count. Explicit stop and idle
+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).
+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
+a test or CI journey with `RER_SERVER_JOURNEY=1`, on its own `--port`, neither
+counts toward the cap nor is refused by it; its port must be free, as for any
+server. Concurrent policy uses the stricter active limit among counted servers.
+Symlink/cwd spellings share an instance; distinct worktrees remain distinct.
+A start is also refused while available memory is below 1.5 GiB (`RER_SERVERS_MIN_MEMORY_BYTES`,
+bytes, 0 for no floor), with the memory, the floor, the running servers and the override named.
+Journeys and reuse of a checkout's own server are not refused. `dev` runs the project's own vite
+entry with the pinned Node (no `pnpm exec` wrapper process); `preview`'s resident process holds only
+Miniflare, while a short-lived child resolves the Worker options with Wrangler and hands them over
+through a pipe (secrets never reach an argument).
+
+Bounded workflows enter the queue before checkout custody. Managed serving
+reserves under a short machine transaction, releases that transaction, then takes
+checkout custody before finite preparation. A competing local operation refuses
+immediately rather than waiting with a lease. Cleanup stops processes and releases private/state custody
+before removing a generation's registry record. Stop waits never need
+the machine transaction during process cleanup. A stale generation cannot remove
+its replacement. Unverifiable foreign processes are never adopted or signalled.
+
+## Bounded work
+
+Heavy commands share the dependency-free Base job queue module exported with
+the CLI: install/build/verify, browser suites, setup preparation and temporary app,
+deploy's local build/validation, release's expensive phases and local transfer
+resource work. Serving uses the registry, with finite preparation queued.
+Labels include project, initiating verb/phase and a safe checkout digest. Use
+`node scripts/base-cli/modules/job-queue/cli.mjs status` to inspect admission.
+Waits go to redacted progress/stderr. Nested commands validate live lease
+membership and actual process ancestry before sharing the admitted slot.
+Direct documented browser/runtime entrypoints and indirect package scripts join
+the same executor. Original-caller `CI=true` skips admission; `CI=false` and unset CI queue.
+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.
+
+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.
+
+Portable hosting adds `--platform workers|container` to build, deploy, dev,
+preview and local export/import. Workers remains the default; container support
+must be declared in deploy.json. Container deploy takes `--host ssh://user@host`
+and a private `--env-file`. See [container hosting](../modules/container/README.md)
+for image/runtime, secrets, SSH and owner setup. `rer archive diff BEFORE AFTER`
+validates both archives and lists changes written during a move without merging.
+
+Container SSH deployment also accepts `--image IMAGE` to select an existing local
+image instead of building, and `--bind-address`, `--http-port`, `--https-port` to
+override `deploy.json`'s `container.ingress` bindings. Image identity is pinned
+before transfer. See `modules/container/README.md` for the remote Python/Docker
+requirements, ownership refusal rules and shared TCP/SNI proxy routing.
+
+## The installable `rer` command
+
+`@runeditrun/rer` packages these same portable sources with `onboarding/` at
+Base's own layout and the global launcher in `global/`. Build it from a Base
+checkout root with `node scripts/rer-package.mjs --out DIR`; the last stdout line
+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`.
+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.

package/cli/adapter.mjs

@@ -0,0 +1,10 @@
+import { verbs, releaseFlags } from './contract.mjs';
+
+// Declarative seed boundary; all spawning, secret custody and readiness live in
+// the existing onboarding kit. No adapter gets a second executor.
+export function commandAdapter(lifecycle, options) {
+ const result = { version: 1, ...lifecycle, ...options, state: '.wrangler/state', settings: options.settings ?? ['.dev.vars', '.dev.vars.previous'] };
+ result.verbs = Object.fromEntries(Object.entries(verbs).filter(([verb]) => !['export', 'import'].includes(verb) || typeof result.portability?.[verb] === 'function').map(([verb, definition]) => [verb, { flags: [...definition.flags] }]));
+ result.verbs.release = { flags: [...releaseFlags] };
+ return result;
+}

package/cli/ai-local.mjs

@@ -0,0 +1,65 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { contained } from './project.mjs';
+import { shared } from './shared.mjs';
+import { refuse, missing } from './errors.mjs';
+import { aiConfig, aiDiagnostics } from '../modules/ai/index.mjs';
+import { validBaseUrl } from '../modules/ai/config.mjs';
+
+export const MODELS_FILE = '.rer/local/models.json';
+export async function readLiveModels(root) {
+  let file;
+  try { file = await contained(root, MODELS_FILE, { privateFile: true }); }
+  catch (error) { if (error.code === 'missing_input') return null; throw error; }
+  for (const path of ['.rer', '.rer/local', MODELS_FILE]) {
+    const status = await lstat(join(root, path));
+    if ((status.mode & 0o777) !== (path === MODELS_FILE ? 0o600 : 0o700) || (process.getuid && status.uid !== process.getuid())) throw refuse('Live-dev Models storage requires owned directories 0700 and models.json 0600.');
+  }
+  let values;
+  try { values = JSON.parse(await readFile(file, 'utf8')); } catch { throw refuse('The local Models dev-app file is malformed.'); }
+  if (!validBaseUrl(values.service) || typeof values.key !== 'string' || !/^mdl_[A-Za-z0-9_-]{16,}$/.test(values.key)) throw refuse('Use a Models URL and a dev-app key in the local Models file. Provider keys are refused.');
+  return { baseUrl: values.service, apiKey: values.key };
+}
+
+/** URL is nonsecret; a dev-app key enters through stdin only, never argv. */
+export async function prepareLiveModels(root, options, store, signal) {
+  if ((options.models ?? 'fake') !== 'live') return undefined;
+  let live = await readLiveModels(root);
+  if (options.modelsService) {
+    if (live) throw refuse('A local Models key already exists. Remove models.json explicitly to replace it.');
+    if (!validBaseUrl(options.modelsService) || process.stdin.isTTY) throw refuse('Pipe the dev-app key on stdin with --models live --models-service URL.');
+    let key = '';
+    for await (const chunk of process.stdin) { key += chunk; if (key.length > 4096) throw refuse('The Models key input is too large.'); }
+    key = key.trim();
+    if (!/^mdl_[A-Za-z0-9_-]{16,}$/.test(key)) throw refuse('Use a Models dev-app key; provider keys are refused.');
+    const { privateDirectory, writePrivateFile } = await shared('private-files.mjs');
+    const directory = await privateDirectory(root, ['.rer', 'local']);
+    await writePrivateFile(join(directory, 'models.json'), JSON.stringify({ service: options.modelsService, key }) + '\n');
+    live = await readLiveModels(root);
+  }
+  if (!live) throw missing('Live dev needs .rer/local/models.json. Create a capped, expiring, cheap-models-only Models dev app, then pipe its key with --models-service URL.');
+  store.addSecrets([live.apiKey]);
+  const url = live.baseUrl.replace(/\/$/, '') + (live.baseUrl.replace(/\/$/, '').endsWith('/v1') ? '/models' : '/v1/models');
+  let providers;
+  try {
+    const response = await fetch(url, { headers: { authorization: `Bearer ${live.apiKey}` }, redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(10000)]) });
+    if (!response.ok) { await response.body?.cancel(); throw Error(); }
+    const listing = await response.json();
+    providers = [...new Set(listing.data.flatMap(model => model.providers))];
+    if (!providers.length || !providers.every(provider => typeof provider === 'string' && /^[a-zA-Z0-9_-]{1,40}$/.test(provider))) throw Error();
+  } catch { throw refuse('The Models dev app could not list its allowed providers. No live-dev server was started.'); }
+  store.report(`RER_MODELS_LIVE ${new URL(live.baseUrl).origin} via ${providers.join(', ')}`);
+  return live;
+}
+
+export async function localAiDiagnostics(project, overrides = {}) {
+  let values = {};
+  try {
+    const { readSettings } = await shared('adapter-settings.mjs');
+    if (project.adapter?.hooks?.secrets) values = (await readSettings(project.root, project.adapter.hooks.secrets)).values;
+  } catch {}
+  const issues = aiDiagnostics(aiConfig({ ...values, ...overrides }, project.adapter?.ai?.features));
+  try { await readLiveModels(project.root); }
+  catch { issues.push({ feature: 'live-dev', code: 'ai_misconfigured', message: 'The local Models dev-app file or its permissions are unsafe.' }); }
+  return issues;
+}

package/cli/archive-path.mjs

@@ -0,0 +1,52 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, parse, sep, dirname, basename } from 'node:path';
+import { contained } from './project.mjs';
+import { refuse } from './errors.mjs';
+import { viteServesArchive } from './archive-vite.mjs';
+
+const message = 'Save the archive at a normalized path inside this checkout\'s exports/ (exports/x.rer, ./exports/x.rer or an absolute path there), or at an absolute path outside this checkout. Traversal (..), unsafe symlinks and paths served by the app are refused.';
+// Static refusals (shape, location, links) run here and touch nothing. `unserved()` then asks the seed's
+// real Vite configuration whether the app would serve the path; the caller runs it after prepareData, because
+// that configuration may need a file only prepareData generates (a checkout that never built has none yet).
+export async function locateExport(root, file) {
+ const checkout = await realpath(root);
+ const located = destination => ({ path: destination, unserved: () => requireUnserved(checkout, destination) });
+ if ((!isAbsolute(file) && file.includes('\\')) || file.split(/[\\/]/).includes('..')) throw refuse(message);
+ if (!isAbsolute(file)) {
+  return located(await insideExports(checkout, relative(checkout, resolve(checkout, file))));
+ }
+ let destination = resolve(file); const within = relative(checkout, destination);
+ if (inside(within)) return located(await insideExports(checkout, within));
+ // Resolve existing ancestors, including platform temporary-directory aliases.
+ // A link outside the checkout must not put the export back inside it.
+ let current = parse(destination).root;
+ const parts = destination.slice(current.length).split(sep);
+ for (const [index, part] of parts.entries()) {
+  current = resolve(current, part);
+  const status = await lstat(current).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!status) break;
+  const actual = await realpath(current), name = relative(checkout, actual);
+  // Parent aliases (such as macOS /var) can lead to the real checkout root.
+  // Once there, validate the remaining path without resolving its symlinks.
+  if (!name && !status.isSymbolicLink()) return located(await insideExports(checkout, parts.slice(index + 1).join(sep)));
+  if (inside(name)) throw refuse(message);
+  if (index === parts.length - 1 && status.isSymbolicLink()) throw refuse(message);
+  current = actual;
+  destination = resolve(current, ...parts.slice(index + 1));
+ }
+ return located(destination);
+}
+const inside = path => !path || (!isAbsolute(path) && path !== '..' && !path.startsWith('..' + sep));
+async function insideExports(checkout, path) {
+ if (!path.startsWith('exports' + sep) || !inside(path)) throw refuse(message);
+ return contained(checkout, path, { optional: true });
+}
+async function requireUnserved(root, destination) {
+ try { if (await viteServesArchive(root, destination)) throw Error('Served destination'); }
+ catch { throw refuse(message); }
+}
+export async function locateImport(root, file) {
+ if (!isAbsolute(file)) return { path: await contained(root, file, { privateFile: true }), unserved: async () => {} };
+ const { path, unserved } = await locateExport(root, file);
+ return { path: await contained(dirname(path), basename(path), { privateFile: true }), unserved };
+}

package/cli/archive-vite.mjs

@@ -0,0 +1,55 @@
+import { access, lstat, realpath } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join, relative, resolve, isAbsolute, sep, dirname, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const inside = (parent, child) => { const path = relative(parent, child); return !path || (!isAbsolute(path) && path !== '..' && !path.startsWith('..' + sep)); };
+async function resolvedDirectory(directory) {
+ const pending = [];
+ for (;;) {
+  const actual = await realpath(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (actual) return resolve(actual, ...pending);
+  const status = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (status?.isSymbolicLink()) throw new Error('Configured served directory has an unresolved link.');
+  pending.unshift(basename(directory)); directory = dirname(directory);
+ }
+}
+function buildDirectories(config) {
+ const builds = [config.build, ...Object.values(config.environments ?? {}).map(environment => environment.build)].filter(Boolean);
+ return builds.flatMap(build => {
+  const outputs = Array.isArray(build.rollupOptions?.output) ? build.rollupOptions.output : [build.rollupOptions?.output];
+  return [build.outDir, ...outputs.filter(Boolean).flatMap(output => [output.dir, output.file && dirname(output.file)])];
+ });
+}
+// Resolve the actual config, including plugin hooks and Vite's implicit
+// filesystem allowance. Reading the file alone misses folders a plugin adds.
+export async function viteServesArchive(root, destination) {
+ const names = ['vite.config.ts','vite.config.mts','vite.config.js','vite.config.mjs','vite.config.cjs','vite.config.cts'];
+ let configFile;
+ for (const name of names) if (await access(join(root, name)).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; })) { configFile = join(root, name); break; }
+ if (!configFile) return false;
+ const require = createRequire(join(root, 'package.json'));
+ const { resolveConfig } = await import(pathToFileURL(require.resolve('vite')).href);
+ for (const command of ['serve', 'build']) {
+  const mode = command === 'build' ? 'production' : 'development';
+  const previousNodeEnv = process.env.NODE_ENV, previousCloudflareBuild = process.env.CLOUDFLARE_VITE_BUILD;
+  let config;
+  try {
+   process.env.NODE_ENV = previousNodeEnv ?? mode;
+   config = await resolveConfig({ root, configFile, mode, logLevel: 'silent' }, command, mode, mode);
+  } finally {
+   if (previousNodeEnv === undefined) delete process.env.NODE_ENV; else process.env.NODE_ENV = previousNodeEnv;
+   if (previousCloudflareBuild === undefined) delete process.env.CLOUDFLARE_VITE_BUILD; else process.env.CLOUDFLARE_VITE_BUILD = previousCloudflareBuild;
+  }
+  const base = config.root;
+  if (config.server?.fs?.strict === false) return true;
+  const directories = [config.publicDir, ...buildDirectories(config), ...config.server.fs.allow].filter(path => typeof path === 'string');
+  for (const name of directories) {
+   // An uncreated output/public folder can still sit below /tmp or another
+   // linked ancestor. Compare its future real location with the export path.
+   const directory = await resolvedDirectory(resolve(base, name));
+   if (inside(directory, destination)) return true;
+  }
+ }
+ return false;
+}

package/cli/archive.mjs

@@ -0,0 +1,8 @@
+import { Readable } from 'node:stream';
+import { createReadStream } from 'node:fs';
+import { diffArchives } from '../modules/portability/diff.mjs';
+import { invalid } from './errors.mjs';
+export async function archiveCommand(args,out) {
+ if (args.length!==3 || args[0]!=='diff') throw invalid('Usage: rer archive diff BEFORE AFTER');
+ const result=await diffArchives(Readable.toWeb(createReadStream(args[1])),Readable.toWeb(createReadStream(args[2]))); out.human(JSON.stringify(result,null,2)); return 0;
+}