@runeditrun/rer 0.0.0-stage → 0.1.1

package/global/update/command.mjs

@@ -0,0 +1,90 @@
+// rer update [--version X]: move this rer to the registry's latest version (or
+// X), the way it was installed. A user install (npx or install.sh) downloads,
+// verifies and switches atomically through the new package's own
+// `rer cli install`, keeping its channel; a failed or mismatched download
+// leaves the current version selected. An npm global install runs npm for its
+// own prefix and never writes a second launcher.
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { layout } from '../cli/layout.mjs';
+import { channelOf } from '../cli/status.mjs';
+import { ownManifest, ownRoot, packageDigest, packageName } from '../package-info.mjs';
+import { readPackage, writePackage } from './archive.mjs';
+import { compareVersions, packageMetadata, pickRelease, registryUrl, UpdateFailure } from './registry.mjs';
+
+const usage = 'Usage: rer update [--version X]\n';
+
+function parse(args) {
+ if (!args.length) return {};
+ if (args.length === 1 && args[0].startsWith('--version=') && args[0].length > 10) return { version: args[0].slice(10) };
+ if (args.length === 2 && args[0] === '--version' && args[1] && !args[1].startsWith('-')) return { version: args[1] };
+ return undefined;
+}
+
+const run = (program, args, env = process.env) => new Promise((resolve, reject) => {
+ const child = spawn(program, args, { env, stdio: ['ignore', 'inherit', 'inherit'] });
+ child.once('error', reject);
+ child.once('close', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+});
+
+// <prefix>/lib/node_modules/@runeditrun/rer, npm's global layout on macOS and Linux.
+function npmPrefix() {
+ const scope = dirname(ownRoot), modules = dirname(scope), lib = dirname(modules);
+ if (basename(scope) !== '@runeditrun' || basename(modules) !== 'node_modules' || basename(lib) !== 'lib') throw new UpdateFailure(`This npm global rer is at ${ownRoot}, outside npm's usual layout; update it with npm install -g ${packageName}.`);
+ return dirname(lib);
+}
+
+async function download(release) {
+ const response = await fetch(release.dist.tarball).catch(error => { throw new UpdateFailure(`Could not download ${release.dist.tarball} (${error.cause?.code ?? error.message}).`); });
+ if (!response.ok) throw new UpdateFailure(`${release.dist.tarball} answered ${response.status}.`);
+ return readPackage(Buffer.from(await response.arrayBuffer()), release.dist);
+}
+
+async function npmGlobal(version) {
+ const prefix = npmPrefix(), args = ['install', '-g', '--prefix', prefix, `${packageName}@${version}`];
+ const command = `npm ${args.map(arg => /^[\w@./:=-]+$/.test(arg) ? arg : JSON.stringify(arg)).join(' ')}`;
+ process.stdout.write(`Updating the npm global rer: ${command}\n`);
+ let code;
+ try { code = await run('npm', args); } catch (error) { code = 127; process.stderr.write(`Could not run npm (${error.code ?? error.message}).\n`); }
+ if (code !== 0) {
+  process.stderr.write(`npm could not update rer (exit ${code}); rer is unchanged. Fix the problem npm reports (for example, a prefix you cannot write), then run:\n  ${command}\n`);
+  return code || 1;
+ }
+ const installed = JSON.parse(await readFile(join(prefix, 'lib/node_modules', packageName, 'package.json'), 'utf8')).version;
+ process.stdout.write(`rer is now ${installed} (npm global, prefix ${prefix}).\n`);
+ return 0;
+}
+
+export async function update(args) {
+ const options = parse(args);
+ if (!options) { process.stderr.write(`Unsupported: rer update ${args.join(' ')}\n${usage}`); return 2; }
+ const { channel } = await channelOf(layout()), current = ownManifest().version;
+ if (channel === 'source') { process.stderr.write(`This rer runs from a source checkout (${ownRoot}), which rer update does not change. Update the checkout with git, or install rer with: npx -y ${packageName} cli install\n`); return 1; }
+ const work = await mkdtemp(join(tmpdir(), 'rer-update-'));
+ try {
+  const release = pickRelease(await packageMetadata(), options.version);
+  if (!options.version && compareVersions(current, release.version) > 0) {
+   process.stdout.write(`rer ${current} is newer than the latest published version (${release.version}); nothing changed. rer update --version ${release.version} installs that one.\n`);
+   return 0;
+  }
+  // The same version counts as current only with the same contents: a
+  // different build of that version is an update. (A development build's
+  // version differs from its release's, so it always moves.)
+  if (release.version === current || channel !== 'npm-global') {
+   process.stdout.write(`Checking rer ${release.version} from ${registryUrl()}\n`);
+   await writePackage(await download(release), join(work, 'package'));
+   if (release.version === current && await packageDigest(join(work, 'package')) === await packageDigest(ownRoot)) {
+    process.stdout.write(`rer ${current} is already current. Nothing changed.\n`);
+    return 0;
+   }
+  }
+  if (channel === 'npm-global') return await npmGlobal(release.version);
+  return await run(process.execPath, [join(work, 'package/global/rer.mjs'), 'cli', 'install'], { ...process.env, RER_INSTALL_CHANNEL: channel });
+ } catch (error) {
+  if (!(error instanceof UpdateFailure)) throw error;
+  process.stderr.write(`rer update: ${error.message} rer ${current} is still selected.\n`);
+  return 1;
+ } finally { await rm(work, { recursive: true, force: true }); }
+}

package/global/update/latest.mjs

@@ -0,0 +1,6 @@
+// Prints the registry's latest @runeditrun/rer version on one line. The update
+// notice runs this as a child process so that it can kill it at its time budget.
+import { packageMetadata } from './registry.mjs';
+
+const latest = (await packageMetadata())['dist-tags']?.latest;
+if (typeof latest === 'string') process.stdout.write(latest + '\n');

package/global/update/notice.mjs

@@ -0,0 +1,58 @@
+// The update notice: in human output on a terminal, at most once per 24 hours,
+// one line naming a newer published version. Never in --json output or when
+// stdout is not a terminal, never more than about 1.5 s of delay (even when the
+// registry accepts the connection and never answers), and off with
+// RER_NO_UPDATE_CHECK=1. The check time lives in ${XDG_CACHE_HOME:-~/.cache}/rer.
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { layout } from '../cli/layout.mjs';
+import { channelOf } from '../cli/status.mjs';
+import { ownManifest } from '../package-info.mjs';
+import { compareVersions } from './registry.mjs';
+
+const interval = 24 * 60 * 60 * 1000, budget = 1500;
+
+export const wantsNotice = (argv, env = process.env) => env.RER_NO_UPDATE_CHECK !== '1' && Boolean(process.stdout.isTTY) && !argv.includes('--json');
+
+export async function updateNotice(env = process.env) {
+ const file = join(env.XDG_CACHE_HOME || join(env.HOME || homedir(), '.cache'), 'rer', 'update-check.json');
+ try {
+  if ((await channelOf(layout(env))).channel === 'source') return;
+  let checkedAt = 0;
+  try { checkedAt = JSON.parse(await readFile(file, 'utf8')).checkedAt ?? 0; } catch {}
+  if (Date.now() - checkedAt < interval) return;
+  // Record the attempt first: a slow or failed registry costs one wait a day.
+  await mkdir(join(file, '..'), { recursive: true });
+  await writeFile(file, JSON.stringify({ checkedAt: Date.now() }) + '\n');
+  const latest = await latestVersion(env);
+  const current = ownManifest().version;
+  if (latest && compareVersions(latest, current) > 0) process.stderr.write(`rer ${latest} is available (this is ${current}). Update with: rer update\n`);
+ } catch {
+  // The notice never stands in the way of the command.
+ }
+}
+
+// The registry is asked by a child process that is killed at the budget. An
+// in-process request can be aborted, but its pending TCP connect (or DNS
+// lookup) still holds this process open until the system gives up: about 10 s
+// when the registry drops packets.
+function latestVersion(env) {
+ return new Promise(resolve => {
+  const child = spawn(process.execPath, [fileURLToPath(new URL('./latest.mjs', import.meta.url))], { env, stdio: ['ignore', 'pipe', 'ignore'] });
+  let output = '';
+  const finish = () => {
+   clearTimeout(timer);
+   child.kill('SIGKILL');
+   child.unref();
+   child.stdout.destroy();
+   resolve(/^\S+(?=\n)/.exec(output)?.[0]);
+  };
+  const timer = setTimeout(finish, budget);
+  child.stdout.setEncoding('utf8').on('data', data => { output += data; if (output.includes('\n')) finish(); });
+  child.once('error', finish);
+  child.once('close', finish);
+ });
+}

package/global/update/registry.mjs

@@ -0,0 +1,47 @@
+// The npm registry's view of @runeditrun/rer: which versions exist, which is
+// latest, and each one's tarball and integrity. The registry is
+// npm_config_registry when set (npm sets it for npx), else the public one.
+import { packageName } from '../package-info.mjs';
+
+export const registryUrl = (env = process.env) => (env.npm_config_registry || 'https://registry.npmjs.org').replace(/\/+$/, '');
+
+export class UpdateFailure extends Error {}
+
+export async function packageMetadata({ env = process.env, signal } = {}) {
+ const url = `${registryUrl(env)}/${packageName.replace('/', '%2f')}`;
+ let response;
+ try { response = await fetch(url, { headers: { accept: 'application/json' }, signal }); }
+ catch (error) { if (error.name === 'AbortError' || error.name === 'TimeoutError') throw error; throw new UpdateFailure(`Could not reach ${registryUrl(env)} (${error.cause?.code ?? error.message}).`); }
+ if (!response.ok) throw new UpdateFailure(`${url} answered ${response.status}${response.status === 404 ? ': @runeditrun/rer is not published there' : ''}.`);
+ try { return await response.json(); } catch { throw new UpdateFailure(`${url} did not answer with package metadata.`); }
+}
+
+// The release to install: the exact version asked for, else latest.
+export function pickRelease(metadata, wanted) {
+ const version = wanted ?? metadata['dist-tags']?.latest, release = metadata.versions?.[version];
+ if (!release) throw new UpdateFailure(wanted ? `Version ${wanted} of ${packageName} is not published.` : `The registry names no latest version of ${packageName}.`);
+ return release;
+}
+
+// Semantic version order, prereleases below their release:
+// 0.1.0-dev.gaa9b4d4f < 0.1.0 < 0.1.1-dev.g12345678 < 0.1.1.
+export function compareVersions(a, b) {
+ const parse = version => {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/.exec(version);
+  if (!match) throw new UpdateFailure(`Not a version: ${version}`);
+  return { core: match.slice(1, 4).map(Number), pre: match[4]?.split('.') ?? [] };
+ };
+ const x = parse(a), y = parse(b);
+ for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] < y.core[i] ? -1 : 1;
+ if (!x.pre.length || !y.pre.length) return x.pre.length === y.pre.length ? 0 : x.pre.length ? -1 : 1;
+ for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+  const p = x.pre[i], q = y.pre[i];
+  if (p === undefined || q === undefined) return p === undefined ? -1 : 1;
+  if (p === q) continue;
+  const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+  if (pn && qn) return Number(p) < Number(q) ? -1 : 1;
+  if (pn !== qn) return pn ? -1 : 1;
+  return p < q ? -1 : 1;
+ }
+ return 0;
+}

package/global/version.mjs

@@ -0,0 +1,29 @@
+// rer --version: this rer's version on the first line. Inside a first-party
+// checkout (or with --cwd DIR) a second line names the version that checkout
+// pins: its package's, or the one its vendored copy recorded, which
+// `rer describe` reports as cliVersion.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { dispatcher, locate } from './checkout.mjs';
+import { describeCheckout } from './launch/facts.mjs';
+import { ownManifest } from './package-info.mjs';
+
+export async function versionCommand(argv) {
+ process.stdout.write(ownManifest().version + '\n');
+ const target = locate(argv);
+ if (target.profile !== 'first-party') return 0;
+ const { mode, entry } = dispatcher(target.root);
+ if (mode === 'bundled') return 0;
+ if (mode === 'package') {
+  const pinned = JSON.parse(readFileSync(join(dirname(dirname(entry)), 'package.json'), 'utf8')).version;
+  process.stdout.write(`This checkout (${target.root}) pins rer ${pinned} (package).\n`);
+  return 0;
+ }
+ let described;
+ try { described = await describeCheckout(target.root, entry, process.env); }
+ catch (failure) { process.stdout.write(`This checkout (${target.root}): its pinned rer version could not be read: ${failure.message.split('\n')[0]}\n`); return 0; }
+ process.stdout.write(described.cliVersion
+  ? `This checkout (${target.root}) pins rer ${described.cliVersion} (vendored scripts/rer.mjs).\n`
+  : `This checkout (${target.root}) pins an unversioned rer copy: its vendored scripts/rer.mjs is older than version recording. Refresh its vendored Base to record one.\n`);
+ return 0;
+}

package/install.sh

@@ -0,0 +1,144 @@
+#!/bin/sh
+# Install the rer command (@runeditrun/rer) for this user:
+#
+#   curl -fsSL https://runeditrun.com/install.sh | sh
+#
+# It reads the version, tarball and sha512 integrity from the npm registry
+# (npm_config_registry, default https://registry.npmjs.org; RER_VERSION=X pins an
+# exact version, otherwise latest), verifies the download, refuses archives with
+# absolute paths, .. entries, links or devices (and anything tar could read
+# differently from this script's own check), and installs through the
+# package's own `rer cli install`: the same layout as
+# `npx -y @runeditrun/rer cli install`. A failure leaves any previous install
+# selected and working. It never edits shell profiles.
+#
+# Needs curl, tar and Node (the package's minimum). macOS or Linux on x64 or
+# arm64; on Windows, run it inside WSL2.
+
+# Everything runs from main, so a partly downloaded script does nothing.
+main() {
+ set -eu
+ package='@runeditrun/rer'
+
+ case "$(uname -s 2>/dev/null || echo unknown)" in
+  Linux | Darwin) ;;
+  MINGW* | MSYS* | CYGWIN* | Windows_NT) fail 'native Windows is not supported; run this inside WSL2 (https://learn.microsoft.com/windows/wsl/install).' ;;
+  *) fail "this system ($(uname -s 2>/dev/null || echo unknown)) is not supported; rer runs on macOS and Linux (on Windows, inside WSL2)." ;;
+ esac
+ case "$(uname -m)" in
+  x86_64 | amd64 | arm64 | aarch64) ;;
+  *) fail "this processor ($(uname -m)) is not supported; rer runs on x64 and arm64." ;;
+ esac
+ for tool in curl tar node; do
+  command -v "$tool" >/dev/null 2>&1 || fail "$tool is required. Install it, then run this again."
+ done
+
+ registry=${npm_config_registry:-https://registry.npmjs.org}
+ registry=${registry%/}
+ work=$(mktemp -d "${TMPDIR:-/tmp}/rer-install.XXXXXX")
+ trap 'rm -rf "$work"' EXIT
+ trap 'exit 130' INT TERM
+
+ curl -fsSL --proto '=http,https' -H 'Accept: application/json' "$registry/@runeditrun%2frer" -o "$work/metadata.json" \
+  || fail "could not read $package from $registry."
+ # Writes version, tarball URL, integrity, file count and unpacked size, one per line.
+ node - "$work/metadata.json" "${RER_VERSION:-}" >"$work/release" <<'NODE' || exit 1
+var fs = require('fs');
+var wanted = process.argv[3];
+function stop(message) { process.stderr.write('rer install: ' + message + '\n'); process.exit(1); }
+var metadata;
+try { metadata = JSON.parse(fs.readFileSync(process.argv[2], 'utf8')); } catch (error) { stop('the registry answered with something that is not package metadata.'); }
+var version = wanted || (metadata['dist-tags'] || {}).latest;
+var release = (metadata.versions || {})[version];
+if (!release) stop(wanted ? 'version ' + wanted + ' of @runeditrun/rer is not published.' : 'the registry names no latest version of @runeditrun/rer.');
+var dist = release.dist || {};
+if (!/^sha512-[A-Za-z0-9+\/]+=*$/.test(dist.integrity || '')) stop('the registry gives no sha512 integrity for ' + version + '.');
+if (!dist.tarball) stop('the registry gives no tarball for ' + version + '.');
+var minimum = String((release.engines || {}).node || '0').replace(/^>=\s*/, '');
+var have = process.versions.node.split('.').map(Number), need = minimum.split('.').map(Number);
+for (var i = 0; i < 3; i++) {
+ if ((have[i] || 0) > (need[i] || 0)) break;
+ if ((have[i] || 0) < (need[i] || 0)) stop('rer ' + version + ' needs Node ' + minimum + ' or later; this is Node ' + process.versions.node + '. Install a newer Node, then run this again.');
+}
+process.stdout.write([version, dist.tarball, dist.integrity, dist.fileCount === undefined ? '' : dist.fileCount, dist.unpackedSize === undefined ? '' : dist.unpackedSize].join('\n') + '\n');
+NODE
+ { read -r version; read -r tarball; read -r integrity; read -r files; read -r size; } <"$work/release"
+
+ printf 'Downloading rer %s from %s\n' "$version" "$registry"
+ curl -fsSL --proto '=http,https' "$tarball" -o "$work/rer.tgz" || fail "could not download $tarball."
+ # The exact bytes the registry names, and nothing tar could write outside its folder.
+ node - "$work/rer.tgz" "$integrity" "$files" "$size" <<'NODE' || fail "the download of rer $version was refused; nothing was installed."
+var fs = require('fs'), hashes = require('crypto'), zlib = require('zlib');
+function stop(message) { process.stderr.write('rer install: ' + message + '\n'); process.exit(1); }
+var bytes = fs.readFileSync(process.argv[2]);
+if ('sha512-' + hashes.createHash('sha512').update(bytes).digest('base64') !== process.argv[3]) stop('the download does not match the registry\'s sha512 integrity.');
+var tar;
+try { tar = zlib.gunzipSync(bytes); } catch (error) { stop('the download is not a gzip archive.'); }
+function text(block, start, length) { var end = start; while (end < start + length && block[end] !== 0) end++; return block.toString('utf8', start, end); }
+function zero(bytes) { for (var z = 0; z < bytes.length; z++) if (bytes[z] !== 0) return false; return true; }
+// tar reads a pax extended header too; only path and size (both honoured here)
+// and mtime (only a time) may appear, so both readers see the same entries.
+function paxFields(data) {
+ var fields = {}, at = 0;
+ while (at < data.length) {
+  var space = data.indexOf(0x20, at), digits = space === -1 ? '' : data.toString('latin1', at, space), length = Number(digits);
+  if (!/^[1-9][0-9]*$/.test(digits) || at + length <= space + 1 || at + length > data.length || data[at + length - 1] !== 0x0a) stop('the archive has a damaged extended header.');
+  var record = data.toString('utf8', space + 1, at + length - 1), equals = record.indexOf('='), key = record.slice(0, equals), value = record.slice(equals + 1);
+  at += length;
+  if (equals < 1) stop('the archive has a damaged extended header.');
+  if (key === 'linkpath') stop('the archive contains a link.');
+  if (key === 'size' && !/^[0-9]+$/.test(value)) stop('the archive has a damaged extended header.');
+  if (key !== 'path' && key !== 'size' && key !== 'mtime') stop('the archive has an extended header field this installer does not read (' + key + ').');
+  fields[key] = key === 'size' ? Number(value) : value;
+ }
+ return fields;
+}
+var offset = 0, count = 0, total = 0, pax = null, ended = false;
+while (offset + 512 <= tar.length) {
+ var block = tar.subarray(offset, offset + 512);
+ if (zero(block)) {
+  if (!zero(tar.subarray(offset))) stop('the archive has data after its end.');
+  ended = true;
+  break;
+ }
+ var sum = 0;
+ for (var i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 32 : block[i];
+ if (parseInt(text(block, 148, 8), 8) !== sum) stop('the archive has a damaged header.');
+ if (block.toString('latin1', 257, 265) !== 'ustar\u0000' + '00') stop('the archive is not a ustar archive.');
+ var sizeField = text(block, 124, 12).trim();
+ if (!/^[0-7]+$/.test(sizeField)) stop('the archive has a damaged header.');
+ var type = String.fromCharCode(block[156] || 48), length = type !== 'x' && pax && pax.size !== undefined ? pax.size : parseInt(sizeField, 8);
+ var data = tar.subarray(offset + 512, offset + 512 + length);
+ if (data.length < length) stop('the archive is truncated.');
+ offset += 512 + Math.ceil(length / 512) * 512;
+ if (type === 'x') {
+  if (pax) stop('the archive has two extended headers for one entry.');
+  pax = paxFields(data);
+  continue;
+ }
+ var name = pax && pax.path !== undefined ? pax.path : text(block, 345, 155) ? text(block, 345, 155) + '/' + text(block, 0, 100) : text(block, 0, 100);
+ pax = null;
+ if (type !== '0' && type !== '5') stop('the archive contains a link, device or other special entry (' + name + ').');
+ if (name.charAt(0) === '/' || name.split('/').indexOf('..') !== -1 || name.indexOf('\\') !== -1 || name.split('/')[0] !== 'package') stop('the archive contains an unsafe path (' + name + ').');
+ if (type === '5' && length !== 0) stop('the archive gives the folder ' + name + ' contents.');
+ if (type === '0' && name.charAt(name.length - 1) === '/') stop('the archive gives the file ' + name + ' a folder\'s name.');
+ // The registry's file count counts every entry, folders included.
+ count++;
+ total += length;
+}
+if (!ended || pax) stop('the archive is truncated.');
+if (process.argv[4] !== '' && Number(process.argv[4]) !== count) stop('the archive holds ' + count + ' entries; the registry says ' + process.argv[4] + '.');
+if (process.argv[5] !== '' && Number(process.argv[5]) !== total) stop('the archive unpacks to ' + total + ' bytes; the registry says ' + process.argv[5] + '.');
+NODE
+ mkdir "$work/stage"
+ tar -xzf "$work/rer.tgz" -C "$work/stage" || fail "could not unpack rer $version; nothing was installed."
+ RER_INSTALL_CHANNEL=script node "$work/stage/package/global/rer.mjs" cli install </dev/null \
+  || fail "rer cli install failed; any previous install is still selected."
+}
+
+fail() {
+ printf 'rer install: %s\n' "$*" >&2
+ exit 1
+}
+
+main "$@"

package/modules/ai/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/modules/ai/README.md

@@ -0,0 +1,90 @@
+# AI client
+
+`ai` implements Base's `ai.provider.v1` slot. Copy this module with the matching
+`operator-auth` module, as with mail. Import production code from `ai/index.mjs`.
+There are no SDK dependencies, automatic retries, schema repairs or provider
+fallbacks. The seed owns enablement, consent, deadlines, budgets and retry policy.
+
+```js
+import { aiConfig, createAiClient, AiError } from './modules/ai/index.mjs';
+const ai = createAiClient(aiConfig(env, { images: 'direct' }));
+const response = await ai.responses({
+  model: 'openai/exact-model-id', input: approvedInput, store: false,
+}, { feature: 'analysis', signal: request.signal });
+```
+
+`chat`, `responses` and `embeddings` return the raw `Response`, including raw
+usage, receipt headers and native SSE. Streaming passes through without buffering.
+Consume JSON or SSE in the seed's own format. Embeddings have no native streaming
+format; the direct transport passes the caller's fields without translating them.
+`receipt(id)` calls the linked service's receipt endpoint. An omitted feature
+leaves Models to use the app key's first/default feature. Do not forward
+`x-models-*` headers to browsers. Pinned names (provider name, slash, then exact model ID) require an exact
+`x-models-target` match when linked; aliases (including `@app/alias`) do not.
+
+`AI_ENABLED=true` is required. Direct calls use `AI_API_KEY`, `AI_MODEL` and
+`AI_BASE_URL` (defaults to OpenAI's `/v1`). Any OpenAI-compatible URL works,
+including OpenRouter or Cloudflare AI Gateway. Direct calls preserve the supplied
+API path prefix. Linked calls use `MODELS_SERVICE`
+and `MODELS_KEY`. Neither a link nor credentials turn AI on. URLs must be HTTPS
+or local loopback HTTP, with no credentials, query or fragment. Redirects fail.
+
+Both transports configured for a feature give `AiError.code ===
+'ai_misconfigured'` when called, and diagnostics in `rer check` and `rer doctor`.
+The app still starts. Declare `ai: { features: { images: 'direct' } }` on the
+command adapter and pass the same feature map to `aiConfig` for capabilities
+that deliberately use their own provider key while the app is linked. An
+explicit feature transport never falls through to the other transport.
+
+For a custom provider-edge adapter, `createAiClient(config, { transport })`
+accepts `request({operation,body,feature,signal,selected}) -> Response`; selection,
+enablement and pinned-target checks still apply. Ordinary HTTP uses `{ fetch }`.
+Errors expose fixed text and typed codes, never upstream exception messages.
+
+## Local development
+
+The reference and composed foundation mount `withDevAi` from `./dev/index.mjs` in their
+local-only Worker entry. `GET /__dev/ai` lists captures as JSON. POST to
+`/__dev/ai/v1/chat/completions`, `/responses`, or `/embeddings` to call the double.
+Every surface needs operator-auth's `RER_DEV_KEY` header or its exchanged,
+host-only cookie. Requests without the key return 404 even through a proxy.
+
+Product routes can import `createDevAiClient` in their local-only implementation;
+it also checks the originating product request's key gate. AI enablement still
+comes from the seed. A local call answers text as `[dev] <feature> <hash8>`
+(two chunks when streamed), `json_object` as `{}`, and embeddings as deterministic
+input-derived vectors. Schema output and forced tools throw
+`dev_fake_cannot_answer` with instructions to use a capped Models dev app.
+The double produces development output only; it cannot stand in for a real
+product result. `./fake/index.mjs` supports a supplied `script` for provider-edge tests.
+
+Outbox rows use local D1 and survive restarts. They are bounded by age and count,
+excluded from installation exports, and deleted with D1 by `rer reset --yes`.
+Capture failures return `dev_outbox_unavailable` and close any live response.
+Production imports neither `./dev/index.mjs` nor `./fake/index.mjs`. `rer build` scans output for
+their marker and refuses a bundle containing it, even without dev identity.
+
+For live dev, first create a Models **dev app** with a low cap, short expiry and
+cheap model allow-list. Models enforces those limits; the client does not invent
+a local budget or claim that the key prefix proves a cap. Pipe its key on stdin:
+
+```sh
+your-secret-reader | rer dev --models live --models-service https://models.example
+```
+
+The key is saved in `.rer/local/models.json` (0600, directories 0700), never in
+arguments or tracked settings. Subsequent `rer dev --models live` reads the file,
+checks the app's authenticated model catalogue, and prints
+`RER_MODELS_LIVE <origin> via <providers>`. No failed live call switches to the
+double. Live outbox rows contain receipt metadata and fixed error codes only.
+`rer check` and `rer doctor` flag unsafe storage. A default `rer dev` still uses
+the double, even when a live file exists. Stop dev before changing modes.
+
+Build hides the private file and restores it afterward. Deploy, dry-run deploy
+and deployment artifact/plan preparation refuse it; local binding names are
+refused in deploy declarations too. Remove it explicitly before deployment.
+`rer reset --yes` deletes it along with the checkout's other local-only state.
+
+Models routing, billing and app administration, Worker probes and Pencil's first
+analytics journey belong to their separate tasks. No provider account is needed
+to run this module's tests.

package/modules/ai/client.mjs

@@ -0,0 +1,71 @@
+import { AiError, serviceErrorCodes } from './errors.mjs';
+import { selectTransport } from './config.mjs';
+
+const endpoints = { chat: 'chat/completions', responses: 'responses', embeddings: 'embeddings' };
+const featureName = value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_.:/-]{0,127}$/.test(value);
+async function discard(response) {
+  try { await response.body?.cancel(); } catch {}
+}
+function endpoint(base, path, models) {
+  const url = new URL(base);
+  url.pathname = url.pathname.replace(/\/$/, '') + (models && !url.pathname.replace(/\/$/, '').endsWith('/v1') ? '/v1/' : '/') + path;
+  return url.href;
+}
+
+/** ai.provider.v1: one attempt, raw JSON/SSE and usage, caller-owned deadlines. */
+export function createAiClient(config = {}, { fetch: send = globalThis.fetch, transport: adapter } = {}) {
+  async function request(operation, body, options = {}) {
+    const feature = options.feature ?? 'default';
+    if (!featureName(feature)) throw new AiError('ai_invalid_request', 400);
+    const selected = selectTransport(config, feature);
+    let model;
+    if (operation !== 'receipt') {
+      if (!body || typeof body !== 'object' || Array.isArray(body)) throw new AiError('ai_invalid_request', 400);
+      model = body.model ?? config.model;
+      if (typeof model !== 'string' || !model.trim()) throw new AiError('ai_invalid_request', 400);
+    } else if (selected.name !== 'models' || typeof body !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(body)) {
+      throw new AiError('ai_invalid_request', 400);
+    }
+    const payload = operation === 'receipt' ? undefined : { ...body, model };
+    const headers = { authorization: `Bearer ${selected.apiKey}`, accept: payload?.stream ? 'text/event-stream' : 'application/json' };
+    if (payload) headers['content-type'] = 'application/json';
+    if (selected.name === 'models') {
+      if (options.feature !== undefined) headers['x-models-feature'] = feature;
+      if (options.subject !== undefined) headers['x-models-subject'] = options.subject;
+    }
+    let response;
+    try {
+      if (options.signal?.aborted) throw new AiError('upstream_uncertain', 504);
+      response = adapter ? await adapter.request({ operation, body: payload, feature, signal: options.signal, selected }) :
+        await send(endpoint(selected.baseUrl, operation === 'receipt' ? `receipts/${body}` : endpoints[operation], selected.name === 'models'), {
+          method: payload ? 'POST' : 'GET', headers, body: payload ? JSON.stringify(payload) : undefined,
+          signal: options.signal, redirect: 'manual',
+        });
+    } catch (error) {
+      if (error instanceof AiError) throw error;
+      // A rejection may have been billed. Never retry it or switch transport.
+      throw new AiError('upstream_uncertain', 504);
+    }
+    if (!(response instanceof Response)) throw new AiError('ai_invalid_response');
+    if (!response.ok) {
+      let code;
+      // Only a fixed code is accepted; upstream messages are never returned.
+      if (selected.name === 'models') {
+        try { code = (await response.json()).error?.code; } catch {}
+      } else await discard(response);
+      const fallback = response.status === 429 ? 'upstream_limited' : response.status === 401 || response.status === 403 ? 'upstream_auth' : response.status >= 500 ? 'upstream_unavailable' : 'upstream_error';
+      throw new AiError(serviceErrorCodes.has(code) ? code : fallback, response.status);
+    }
+    if (selected.name === 'models' && operation !== 'receipt' && model.includes('/') && !model.startsWith('@') && response.headers.get('x-models-target') !== model) {
+      await discard(response);
+      throw new AiError('ai_target_mismatch');
+    }
+    return response;
+  }
+  return Object.freeze({
+    chat: (body, options) => request('chat', body, options),
+    responses: (body, options) => request('responses', body, options),
+    embeddings: (body, options) => request('embeddings', body, options),
+    receipt: (id, options) => request('receipt', id, options),
+  });
+}

package/modules/ai/config.mjs

@@ -0,0 +1,39 @@
+import { AiError } from './errors.mjs';
+
+export function aiConfig(env = {}, features = {}) {
+  return {
+    enabled: env.AI_ENABLED === true || env.AI_ENABLED === 'true',
+    model: env.AI_MODEL,
+    direct: env.AI_BASE_URL || env.AI_API_KEY ? { baseUrl: env.AI_BASE_URL || 'https://api.openai.com/v1', apiKey: env.AI_API_KEY } : undefined,
+    models: env.MODELS_SERVICE || env.MODELS_KEY ? { baseUrl: env.MODELS_SERVICE, apiKey: env.MODELS_KEY } : undefined,
+    features,
+  };
+}
+
+export function validBaseUrl(value) {
+  try {
+    const url = new URL(value);
+    const local = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(url.hostname);
+    return (url.protocol === 'https:' || (url.protocol === 'http:' && local)) && !url.username && !url.password && !url.search && !url.hash;
+  } catch { return false; }
+}
+
+export function selectTransport(config = {}, feature = 'default') {
+  if (config.enabled !== true) throw new AiError('ai_disabled', 503);
+  const requested = config.features && Object.hasOwn(config.features, feature) ? config.features[feature] : undefined;
+  if (requested !== undefined && !['direct', 'models'].includes(requested)) throw new AiError('ai_misconfigured', 503);
+  const configured = ['direct', 'models'].filter(name => config[name] && (config[name].baseUrl || config[name].apiKey));
+  const name = requested ?? (configured.length === 1 ? configured[0] : undefined);
+  const transport = name && config[name];
+  if (!transport || !validBaseUrl(transport.baseUrl) || typeof transport.apiKey !== 'string' || !transport.apiKey || /\s/.test(transport.apiKey)) throw new AiError('ai_misconfigured', 503);
+  return { name, ...transport };
+}
+
+/** Diagnostics use the same selection as calls; no network or credential output. */
+export function aiDiagnostics(config = {}) {
+  if (config.enabled !== true) return [];
+  return [...new Set(['default', ...Object.keys(config.features ?? {})])].flatMap(feature => {
+    try { selectTransport(config, feature); return []; }
+    catch (error) { return [{ feature, code: error.code, message: error.message }]; }
+  });
+}

package/modules/ai/dev/index.d.mts

@@ -0,0 +1,6 @@
+import type { AiClient, AiConfig, AiTransport } from '../index.mjs';
+export const DEV_AI_MARKER: string;
+export interface AiOutbox { put(record: object): Promise<void>; list(): Promise<object[]>; }
+export function createAiOutbox(options: { db: D1Database; clock?: () => number; maxRequests?: number; maxAgeMs?: number }): AiOutbox;
+export function createDevAiClient(config: AiConfig, dependencies: { request: Request; key?: string; origin: string; local: boolean; outbox: AiOutbox; live?: { baseUrl: string; apiKey: string }; fetch?: typeof fetch; script?: AiTransport['request'] }): AiClient;
+export function withDevAi<Env, Worker extends { fetch?: (request: never, env: Env, execution: never) => unknown }>(worker: Worker, options?: { bindings?: (env: Env) => Env }): Worker;