@runeditrun/rer 0.1.1 → 0.2.1

package/cli/site-references.mjs

@@ -0,0 +1,93 @@
+import { memberName, stringValue, walkSyntax } from './site-syntax.mjs';
+import { localValues } from './site-bindings.mjs';
+import { browserObjects } from './site-browser-objects.mjs';
+import { markupReferences, cssReferences, markupStrings, cssStrings } from './site-markup.mjs';
+
+export function javascriptContent(tree) {
+ const values = localValues(tree), {strings, names, resources, origins, global, localClass} = values;
+ const browser = browserObjects(values), found = [], literals = [], unresolved = [];
+ const properties = new Set(['src','href','srcset','action','formaction','poster','data']);
+ const elementFactory = callee => {
+  const methods = names(callee);
+  if (!methods.some(name => ['createElement','jsx','jsxs','jsxDEV'].includes(name)) || localClass(callee.object)) return false;
+  const receivers = origins(callee.object);
+  // Native document construction takes options, whereas framework factories
+  // render props. Mixed receiver alternatives must retain their framework use.
+  return !(methods.every(name => name === 'createElement') && receivers.length && receivers.every(browser.document));
+ };
+ const add = (node, kind, navigates = false, documentRelative = true, srcset = false) => {
+  const targets = resources(node);
+  if (targets.some(target => !target.complete)) unresolved.push({kind});
+  for (const {value, complete} of targets) for (const url of srcset ? value.split(',').map(part => part.trim().split(/\s+/)[0]) : [value]) found.push({url, navigates, documentRelative, dynamic:!complete});
+ };
+ const css = (node, emitted) => {for (const {value, complete} of resources(node)) {
+  literals.push(...cssStrings(value));
+  if (!emitted) continue;
+  const references = cssReferences(value);
+  found.push(...references.map(reference => ({...reference,documentRelative:true,dynamic:!complete})));
+  if (!complete && references.length) unresolved.push({kind:'CSS.url'});
+ }};
+ const markup = (node, emitted) => { for (const value of strings(node)) {
+  literals.push(...markupStrings(value));
+  if (emitted) found.push(...markupReferences(value, true).map(reference => ({...reference, documentRelative:true})));
+ }};
+ walkSyntax(tree, node => {
+  if (['ImportDeclaration','ExportNamedDeclaration','ExportAllDeclaration','ImportExpression'].includes(node.type) && node.source) add(node.source, node.type === 'ImportExpression' ? 'import()' : 'import', false, false);
+  if (node.type === 'AssignmentExpression') {
+   const object = node.left.object, fields = names(node.left);
+   if (browser.location(node.left)) add(node.right, 'location.href');
+   for (const property of fields) {
+    const name = property.toLowerCase();
+    if (properties.has(name) && browser.dom(object)) add(node.right, `DOM.${property}`, name === 'href' && browser.anchor(object), true, name === 'srcset');
+    if (property === 'href' && browser.location(object)) add(node.right, 'location.href');
+    if (['innerHTML','outerHTML','srcdoc'].includes(property)) markup(node.right, browser.dom(object));
+   }
+   // String extraction retains its privacy scope even for inert object fields.
+   if (fields.some(property => ['style','cssText'].includes(property)) || origins(object).some(value => memberName(value) === 'style')) css(node.right, browser.style(object) || (fields.includes('style') && browser.dom(object)));
+  }
+  if (node.type === 'Property') {
+   const property = node.computed ? stringValue(node.key) : node.key.name ?? node.key.value;
+   // Keep extracting private text from stored markup; resource use is checked
+   // where the value reaches a DOM write or a recognized element factory.
+   if (property === '__html') markup(node.value, false);
+  }
+  if (!['CallExpression','NewExpression'].includes(node.type)) return;
+  const args = node.arguments;
+  const createsElement = node.type === 'CallExpression' && origins(node.callee).some(elementFactory);
+  const tags = createsElement ? strings(args[0]) : [];
+  if (tags.length) for (const props of origins(args[1])) {
+   if (props.type !== 'ObjectExpression') continue;
+   for (const field of props.properties) for (const property of names(field)) {
+    if (properties.has(property.toLowerCase())) add(field.value, `DOM.${property}`, property === 'href' && tags.some(tag => ['a','area'].includes(tag)), true, property.toLowerCase() === 'srcset');
+    if (property === 'dangerouslySetInnerHTML') for (const html of origins(field.value)) {
+     if (html.type === 'ObjectExpression') for (const content of html.properties) if (names(content).includes('__html')) markup(content.value, true);
+    }
+   }
+  }
+  for (const name of ['fetch','Worker','SharedWorker','WebSocket','EventSource']) if (global(node.callee, name)) add(args[0], name);
+  for (const callee of origins(node.callee)) for (const method of names(callee)) {
+   const object = callee.object;
+   if (method === 'sendBeacon' && global(object, 'navigator')) add(args[0], 'navigator.sendBeacon');
+   // URL and Request construct data. Their arguments are resolved only when
+   // the resulting value reaches a resource operation such as fetch.
+   if (method === 'setProperty' && origins(object).some(value => memberName(value) === 'style')) css(args[1], browser.style(object));
+   if (method === 'open') {
+    if (browser.window(object)) add(args[0], 'window.open');
+    else if (browser.constructed(object, 'XMLHttpRequest')) add(args[1], 'XMLHttpRequest.open');
+   }
+   if (['assign','replace'].includes(method) && browser.location(object)) add(args[0], `location.${method}`);
+   if (['setAttribute','setAttributeNS'].includes(method)) {
+    const index = method === 'setAttributeNS' ? 1 : 0;
+    for (const attribute of strings(args[index])) {
+     const property = attribute.toLowerCase();
+     if (properties.has(property) && browser.dom(object)) add(args[index + 1], `DOM.${method}(${property})`, property === 'href' && browser.anchor(object), true, property === 'srcset');
+     if (property === 'srcdoc') markup(args[index + 1], browser.dom(object));
+     if (property === 'style') css(args[index + 1], browser.dom(object));
+    }
+   }
+   if (method === 'insertAdjacentHTML') markup(args[1], browser.dom(object));
+   if (method === 'write' || method === 'writeln') for (const argument of args) markup(argument, browser.document(object));
+  }
+ });
+ return {references:found, unresolved, literals};
+}

package/cli/site-render.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Child of `rer build --site` and `rer dev`: builds the seed's declared site
+// entry with the checkout's own Vite for Node (an SSR build), loads it and
+// calls its sitePages({ styles }), then writes the static run site: "/" to
+// index.html, "/run" to run.html, "/docs/a" to docs/a.html, "/404" to
+// 404.html, the declared public files, and the stylesheet and files the
+// entry's CSS imports compile to. The optional site config is a Vite config
+// naming the plugins the site pages need (a docs virtual module, a CSS
+// toolchain); the app's own Vite config is never loaded, because its Worker
+// plugins do not run in Node. It reads no installation data.
+// Usage: node site-render.mjs ROOT ENTRY OUTPUT [CONFIG]
+import { cp, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { buildClients, writeSiteAsset } from './site-client.mjs';
+
+const [root, entry, output, config, clientJSON] = process.argv.slice(2);
+const fail = message => { process.stderr.write(`${message}\n`); process.exit(2); };
+if (!root || !entry || !output) fail('Usage: site-render.mjs ROOT ENTRY OUTPUT [CONFIG]');
+const inside = (base, path) => { const target = resolve(base, path); return target === base || target.startsWith(base + sep) ? target : null; };
+// Compiled CSS and the files it references land under this folder of the site.
+const ASSETS = 'site-assets';
+
+let vite;
+try { vite = await import(pathToFileURL(createRequire(join(root, 'package.json')).resolve('vite')).href); }
+catch { fail('The run site renders with the checkout\'s own Vite. Run rer install first.'); }
+process.env.NODE_ENV ??= 'production';
+
+// The Node bundle sits beside the output, inside the checkout, so its external
+// imports resolve from the checkout's node_modules. It never enters the site.
+const server = `${output}.render`;
+let module, styles = [], files = [];
+try {
+ const built = await vite.build({
+  root, configFile: config ? resolve(root, config) : false, envFile: false, logLevel: 'error', mode: 'production',
+  build: {
+   ssr: resolve(root, entry), outDir: server, emptyOutDir: true, copyPublicDir: false, ssrEmitAssets: true,
+   cssCodeSplit: false, assetsDir: ASSETS, sourcemap: false, minify: false, reportCompressedSize: false, watch: null,
+  },
+ }).catch(error => fail(`The run site entry ${entry} did not build: ${error.message.split('\n')[0]}${config ? '' : ' If its pages need Vite plugins (a docs virtual module, a CSS toolchain), name a site Vite config: site: { config } in the command adapter.'}`));
+ const outputs = (Array.isArray(built) ? built : [built]).flatMap(result => result.output ?? []);
+ const chunk = outputs.find(item => item.type === 'chunk' && item.isEntry);
+ if (!chunk) fail(`The run site entry ${entry} produced no module.`);
+ files = outputs.filter(item => item.type === 'asset' && item.fileName.startsWith(`${ASSETS}/`)).map(item => item.fileName);
+ styles = files.filter(name => name.endsWith('.css')).map(name => `/${name}`);
+ await writeFile(join(server, 'package.json'), '{"type":"module"}\n');
+ module = await import(pathToFileURL(join(server, chunk.fileName)).href);
+ if (typeof module.sitePages !== 'function') fail(`${entry} must export sitePages(), returning { pages: [{ path, html }], assets: [public paths] }.`);
+ const clientBuild = await buildClients(vite, root, output, clientJSON ? JSON.parse(clientJSON) : {}), clients = clientBuild.clients;
+ styles = [...new Set([...styles,...clientBuild.styles])];
+ const build = await module.sitePages({ styles, clients });
+ if (!Array.isArray(build?.pages) || !Array.isArray(build.assets)) fail('sitePages() returns { pages, assets }.');
+
+ const written = new Set();
+ for (const page of build.pages) {
+  if (typeof page?.path !== 'string' || !/^\/(?:[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*)?$/i.test(page.path) || page.path.endsWith('.html') || typeof page.html !== 'string') fail(`Invalid site page ${JSON.stringify(page?.path)}: a path such as /run with its HTML.`);
+  const file = page.path === '/' ? 'index.html' : `${page.path.slice(1)}.html`;
+  if (written.has(file) || file.startsWith(`${ASSETS}/`)) fail(`Duplicate site page ${page.path}.`);
+  written.add(file);
+  await mkdir(dirname(join(output, file)), { recursive: true });
+  await writeFile(join(output, file), page.html);
+ }
+ const publicDirectory = resolve(root, 'public');
+ for (const asset of build.assets) {
+  const source = typeof asset === 'string' && !asset.split('/').some(part => !part || part.startsWith('.')) && inside(publicDirectory, asset);
+  if (!source || source === publicDirectory) fail(`Invalid site asset ${JSON.stringify(asset)}: a file or folder under public/.`);
+  if (asset === ASSETS || asset.startsWith(`${ASSETS}/`)) fail(`public/${ASSETS} is reserved for the run site's compiled styles; rename it.`);
+  await lstat(source).catch(() => fail(`Missing site asset public/${asset}.`));
+  await cp(source, join(output, asset), { recursive: true, errorOnExist: true, force: false, verbatimSymlinks: true });
+ }
+ // Only the emitted files: the Node chunks share the folder and never ship.
+ for (const file of files) {
+  await writeSiteAsset(output,file,await readFile(join(server,file)));
+ }
+ process.stdout.write(`${JSON.stringify({ pages: build.pages.length, assets: build.assets.length, styles: styles.length })}\n`);
+} finally { await rm(server, { recursive: true, force: true }); }
+// Vite and the loaded pages can keep handles open; every file is written.
+process.exit(0);

package/cli/site-syntax.mjs

@@ -0,0 +1,21 @@
+// Shared ESTree helpers. Walk actual syntax so comments, string delimiters and
+// formatting do not change which values the site checks.
+export function walkSyntax(node, visit, parents = []) {
+ if (!node || typeof node !== 'object' || !node.type) return;
+ visit(node, parents);
+ for (const value of Object.values(node)) {
+  if (Array.isArray(value)) for (const child of value) walkSyntax(child, visit, [...parents, node]);
+  else if (value?.type) walkSyntax(value, visit, [...parents, node]);
+ }
+}
+export const memberName = node => node?.type === 'MemberExpression' ? node.computed ? stringValue(node.property) : node.property.name : undefined;
+export const stringValue = node => node?.type === 'Literal' && typeof node.value === 'string' ? node.value : node?.type === 'TemplateLiteral' && !node.expressions.length ? node.quasis[0].value.cooked : undefined;
+export function javascriptStrings(tree) {
+ const values = [];
+ walkSyntax(tree, node => {
+  const value = stringValue(node);
+  if (value !== undefined) values.push(value);
+  if (node.type === 'TemplateElement' && node.value.cooked !== null) values.push(node.value.cooked);
+ });
+ return values;
+}

package/cli/site.mjs

@@ -0,0 +1,130 @@
+import { readFile, rename, rm, mkdir } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { contained } from './project.mjs';
+import { invalid, missing, refuse, RerError } from './errors.mjs';
+import { checkSite } from './site-check.mjs';
+import { readDevKey } from './dev-identity.mjs';
+import { shared } from './shared.mjs';
+import { unpublishedIdentities } from './site-private.mjs';
+import { privateSitePaths } from './site-inputs.mjs';
+
+// The run site: a seed's static marketing pages, /run and docs, built from
+// edition identity with no installation data. A seed opts in with
+// commandAdapter's `site: { entry, output, declaration, config? }`: the module
+// whose sitePages({ styles }) returns the pages, the ignored folder the build
+// writes, the deploy declaration naming the run site's domain, and optionally
+// the Vite config holding the plugins the site pages need.
+const relativePath = value => typeof value === 'string' && /^[A-Za-z0-9._/-]+$/.test(value) && !value.split('/').some(part => !part || part === '.' || part === '..');
+
+export function declaredSite(project) {
+ const site = project.adapter?.site;
+ if (!site) throw refuse('This checkout declares no run site. A seed opts in with site: { entry, output, declaration } in its command adapter; see SEED-COMMAND-CONTRACT.md.');
+ if (!relativePath(site.entry) || !relativePath(site.output) || !relativePath(site.declaration) || (site.config !== undefined && !relativePath(site.config)) || (site.clientConfig !== undefined && !relativePath(site.clientConfig)) || ['src', 'public', 'node_modules', 'migrations'].some(top => site.output === top || site.output.startsWith(top + '/'))) throw invalid('The declared run site needs relative entries/configs, an output folder outside src, public and node_modules, and a deploy declaration.');
+ if (site.clients !== undefined && (!site.clients || Array.isArray(site.clients) || typeof site.clients !== 'object' || Object.entries(site.clients).some(([name, entry]) => !/^[a-z][a-z0-9-]*$/i.test(name) || !relativePath(entry)))) throw invalid('Run site clients is a map of island names to relative client entry paths.');
+ return site;
+}
+
+// Owner identity, secrets and the dev key: none may appear in the run site.
+async function privateValues(project) {
+ const privateValues = [], privateIdentities = [], names = project.adapter.input?.names ?? {};
+ const { localVariables } = await shared('local/environment.mjs');
+ const manifest = await readFile(join(project.root, project.adapter.setup?.manifestFile ?? 'rer-setup.json'), 'utf8').then(JSON.parse, () => ({}));
+ const secretNames = new Set((manifest.fields ?? []).filter(field => field.kind === 'secret').map(field => field.name));
+ const variables = await readFile(join(project.root, project.adapter.hooks?.secrets?.file ?? '.dev.vars'), 'utf8').then(localVariables, () => ({}));
+ for (const [key, value] of Object.entries(variables)) {
+  if ([names.email, names.name].includes(key)) privateIdentities.push(value);
+  else if (secretNames.has(key) || /SECRET|TOKEN|PASSWORD|_KEY$/.test(key)) privateValues.push(value);
+ }
+ const answers = await readFile(join(project.root, '.seed/installer/setup-answers.json'), 'utf8').then(JSON.parse, () => ({}));
+ for (const [key, value] of Object.entries(answers)) if (secretNames.has(key) || /SECRET|TOKEN|PASSWORD|_KEY$/.test(key)) privateValues.push(value);
+ for (const key of [names.email, names.name]) if (typeof answers?.[key] === 'string') privateIdentities.push(answers[key]);
+ const key = await readDevKey(project.root).catch(() => null);
+ if (key) privateValues.push(key);
+ return { privateValues, privateIdentities: await unpublishedIdentities(project.root, privateIdentities, privateSitePaths(project.adapter)) };
+}
+
+/** Render the run site into its declared folder, check it and replace the previous build. */
+export async function buildSite(project, store, signal) {
+ const site = declaredSite(project);
+ await contained(project.root, site.entry);
+ if (site.config) await contained(project.root, site.config);
+ if (site.clientConfig) await contained(project.root, site.clientConfig);
+ for (const entry of Object.values(site.clients ?? {})) await contained(project.root, entry);
+ const folder = await contained(project.root, site.output, { optional: true });
+ await mkdir(dirname(folder), { recursive: true });
+ const staging = `${folder}.building-${process.pid}`;
+ await rm(staging, { recursive: true, force: true });
+ try {
+  await mkdir(staging);
+  try { await store.run('Building the run site', process.execPath, [fileURLToPath(new URL('./site-render.mjs', import.meta.url)), project.root, site.entry, staging, site.config ?? '', JSON.stringify({entries:site.clients ?? {}, config:site.clientConfig, privatePaths:privateSitePaths(project.adapter)})], { cwd: project.root, signal, heavy: false }); }
+  catch (error) {
+   const code = await readFile(`${staging}.refusal`, 'utf8').catch(() => '');
+   if (code === 'site_private_input') throw new RerError(code, 'Run site client imports a private installation file or a file outside the seed and its declared dependencies.', 4);
+   if (code === 'site_client_server_import') throw new RerError(code, 'Run site client imports a server-only module. Use browser dependencies in every reachable island module.', 4);
+   throw error;
+  }
+  const checked = await checkSite(staging, {root:project.root, ...await privateValues(project)});
+  await rm(folder, { recursive: true, force: true });
+  await rename(staging, folder);
+  return { folder, ...checked };
+ } finally { await Promise.all([staging, `${staging}.render`, `${staging}.refusal`].map(path => rm(path, { recursive: true, force: true }))); }
+}
+
+async function siteDeployment(project, options, folder) {
+ const site = declaredSite(project), environment = options.environment ?? 'production';
+ const read = async path => { try { return JSON.parse(await readFile(await contained(project.root, path), 'utf8')); } catch (error) { if (error instanceof RerError) throw error; throw invalid(`Malformed ${path}.`); } };
+ const app = await read(project.adapter.deploy?.declaration ?? 'deploy.json'), declaration = await read(site.declaration);
+ const { sitePlan } = await import('../modules/deploy-kit/site.mjs');
+ try { return sitePlan({ project: app.project, environment, compatibilityDate: app.compatibilityDate, declaration, assets: folder }); }
+ catch (error) { throw invalid(`The run site deploy declaration is invalid (${error.message}). ${site.declaration} holds {"version": 1, "domain": "<apex hostname>"}.`); }
+}
+
+/** `rer build --site` and `rer deploy --site [--dry-run]`. */
+export async function siteCommand(project, options, store, signal, out) {
+ const built = await buildSite(project, store, signal);
+ if (!options.json && built.references.unresolved.length) {
+  out.human(`Run site references: ${built.references.unresolved.length} runtime resource target(s) could not be resolved statically:`);
+  for (const {asset, kind} of built.references.unresolved) out.human(`  ${asset}: ${kind}`);
+ }
+ if (options.verb === 'build') {
+  // Output redaction masks an inherited PWD (a credential-shaped name), so the
+  // checkout-relative folder is named too.
+  const path = relative(project.root, built.folder);
+  if (!options.json) out.human(`Run site written to ${path} (${built.pages} pages, ${built.files} files): ${built.folder}`);
+  return { site: { folder: built.folder, path, pages: built.pages, files: built.files, references:built.references } };
+ }
+ const plan = await siteDeployment(project, options, built.folder);
+ const human = [`Run site plan: site Worker ${plan.worker}, Base-generated, its only binding the assets (the app's Worker ${plan.appWorker} is not touched)`, `  assets: ${plan.assets} (${built.files} files; HTML ${plan.assetsConfig.html_handling}, not found ${plan.assetsConfig.not_found_handling}; the Worker runs first)`,
+  `  custom domains: ${plan.hostnames.join(', ')}; workers.dev off`, ...plan.redirects.map(rule => `  redirect in the Worker: ${rule.from} -> ${rule.to} (${rule.status}, keeps ${rule.keeps.join(' and ')})`)];
+ const summary = { worker: plan.worker, appWorker: plan.appWorker, module: plan.module, bindings: plan.bindings, assets: plan.assets, files: built.files, references:built.references, domain: plan.domain, hostnames: plan.hostnames, workersDev: false, runWorkerFirst: true, assetsConfig: plan.assetsConfig, redirects: plan.redirects.map(({ from, to, status }) => ({ from, to, status })) };
+ if (options.dryRun) {
+  if (options.json) out.event('site', summary); else for (const line of human) out.human(line);
+  store.report('deploy --site: dry run complete; no deployment occurred and no provider request was made.');
+  return { dryRun: true, deployed: false, site: summary };
+ }
+ const names = ['CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN'];
+ if (names.some(name => !process.env[name]?.trim())) throw missing('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required, with the run site token permissions in the deploy-kit README.');
+ if (!options.json) for (const line of human) out.human(line);
+ const { cloudflare } = await import('../modules/deploy-kit/provider.mjs');
+ const { collectFiles } = await import('../modules/deploy-kit/artifact.mjs');
+ const { siteDeploy } = await import('../modules/deploy-kit/site.mjs');
+ const environment = options.environment ?? 'production';
+ try {
+  const api = cloudflare({ accountId: process.env.CLOUDFLARE_ACCOUNT_ID, token: process.env.CLOUDFLARE_API_TOKEN });
+  // The receipt is for the person; ownership is read from the provider, so a fresh checkout deploys too.
+  const result = await siteDeploy({ api, plan, files: await collectFiles(built.folder), receiptPath: join(project.root, '.rer', 'deploy', `site-${environment}.json`) });
+  return { dryRun: false, deployed: true, origin: result.origin, site: summary };
+ } catch (error) {
+  if (error instanceof RerError) throw error;
+  throw new RerError('deploy_refused', `Run site deploy stopped: ${/^[a-z0-9-]{1,80}$/.test(error.message) ? error.message : 'site-deploy-failed'}${error.resource ? ` (${error.resource})` : ''}.`, 1);
+ }
+}
+
+/** For rer dev: build the run site and serve it on the first free port above the app's. */
+export async function devSite(project, store, signal, { host, port }) {
+ const built = await buildSite(project, store, signal);
+ const { sitePreview } = await import('./site-preview.mjs');
+ return { ...await sitePreview(built.folder, { host, ports: Array.from({ length: 50 }, (_, index) => port + 1 + index).filter(value => value <= 65535) }), folder: relative(project.root, built.folder) };
+}
+

package/global/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 0.2.1
+
+- `rer release keygen` prepares publisher keys and anchor entries; `rer release sign` writes a detached signature for a completed tagged release.
+- `rer release receipt` verifies signed artifacts against local anchors offline, using the shared verifier and vectors exported for reuse.
+- Tagged releases record the annotated tag object, public commit and public tree needed to sign their artifacts.
+- Package-mode conversion removes obsolete vendored-copy checks, component selections and packaging globs, and rewrites test launches to the installed rer entry with foreground development.
+- Hosted-output and hydration checks run when invoked through pnpm's package symlinks.
+- Run sites support seed-declared browser client islands, with bundled scripts and styles checked during the build.
+- Run-site privacy checks match complete owner identifiers and accept examples already committed in source; `rer dev` warns on a run-site privacy refusal while `rer build --site` still refuses.
+- `rer preview --detach` starts a background preview, refreshes stale build output after source changes and serves scheduled trigger routes.
+- `rer dev --foreground --help` shows the command's help.
+- Deploy failures name the failed step and error code, show redacted provider output and list resources created during that attempt.
+- Sign-in pages hide the email form when mail is unavailable and expose typed handler options.
+- Dev badge and sign-in outbox controls have larger click targets.
+- The Lobby stays script-free; `RER_OPEN` exchanges the development key on `/__dev/key` under its own content security policy.
+- `rer --version` handles a closed output pipe without an EPIPE stack.
+- The publication scan accepts recognised vendor no-reply co-author trailers while continuing to flag personal email addresses.
+- Local-run instructions give the stop, export, reset, import and setup order.
+- Base provides an optional run-site workflow template for manual adoption.
+- Base's source and reference import kit can erase selected personal fields from retained shared records and undo images; this kit is outside the rer npm package.
+
+### Known limitations
+
+the run-site privacy check does not detect deliberately obfuscated secrets, such as base64 concatenated to other text, in client islands
+
+## 0.2.0
+
+What changes for a user since 0.1.1.
+
+### Package mode
+
+- A first-party seed pins `@runeditrun/rer` as an exact devDependency instead of
+  carrying `scripts/rer.mjs`, `scripts/base-cli` and `scripts/base-onboarding`.
+  `node scripts/export-cli.mjs --to-package SEED_ROOT [--version X]` converts a
+  vendored seed (it refuses local edits and lists them).
+- `rer check` and `rer describe` in a checkout whose `node_modules` lacks its
+  pin install it with the frozen lockfile first, then run the pinned verb, so a
+  fresh clone checks with the pinned bytes. `rer check --profile first-party`
+  accepts package mode (SC-13) and still accepts vendored mode.
+- Named exports for every Base file a seed's adapter, Vite config, build or
+  package script imports; nothing needs `internal/`.
+
+### Lobby, homepage variants, setup state
+
+- The Lobby (the pre-claim page) and `GET /setup/state`; a seed supplies its own
+  first-run read, and the fonts stylesheet its edition names.
+- Homepage variants and a hydration check that follows a redirecting `/`, counts
+  cross-origin client scripts and fails an edit case React hydrated too early to test.
+
+### Run sites
+
+- `rer build --site` builds the seed's run site (with its own Vite config and
+  CSS) and `rer deploy --site` deploys it. Ownership is proven from the provider
+  alone (the latest deployment serves the newest version, which carries the
+  kit's annotation), so a fresh CI checkout redeploys; a foreign Worker or
+  domain is refused.
+- The site Worker is Base-generated: `www.<domain>` answers a 301 to the apex
+  (path and query kept) and everything else comes from assets. No zone ruleset
+  is read or written.
+- The publication scan accepts the run-NAME repository names the owner
+  proposed (for example run-lamp under the just-every account) as intended
+  public destinations; the earlier names stay valid.
+
+### Local development hardening
+
+- A request with a foreign `Host` gets a plain 421; keyless `/@fs` and any
+  path Vite would answer with its 403 "Restricted" page (which lists checkout
+  and home paths) get 404. The dev key opens them.
+- `rer` fetches the pinned pnpm from the npm registry, checked against its
+  integrity hash, when PATH lacks it.
+- An explicit `RER_SERVER_LIMIT` caps its own start, higher or lower.
+- `rer door`: keys never go through the door, a moved checkout keeps its name,
+  a restart hands starts over, a missing folder is a plain page.
+
+### Hosted output
+
+- Built `.html` files are served by the hosted Worker (`staticAssetResponse`),
+  including revalidation (`If-None-Match` answers 304). The hosted check
+  requests every built file and sends one conditional request per `.html`.
+- A deploy secret may carry `verifyStandIn` for the hosted check.
+- Packed deploy assets leave out `.assetsignore` and what it names.
+
+### Fixes
+
+- Setup reads the seed's declared settings format and session-secret name.
+- Large stores export, and a fresh install recovers a legacy backup.

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
@@ -130,6 +134,27 @@ checkout never records a limit you did not set.
 A start is never refused for machine load alone unless `RER_SERVERS_LOAD_THRESHOLD`
 or `RER_JOBS_LOAD_THRESHOLD` is set; memory and disk guards stay.
 
+## The front door
+
+```sh
+rer door enable              # opt this computer in: port 8700, 10 servers, 12 hours idle
+rer door add ~/review/*      # register checkouts; prints each http://NAME.localhost:8700
+rer door status --links      # every checkout, its state, and sign-in links
+```
+
+One process on one port serves every registered checkout at
+`http://NAME.localhost:PORT` (NAME is its folder name, unique and stable);
+`http://localhost:PORT` lists them. A stopped checkout starts when you open it
+in a browser and stops when idle; subresources, API calls and WebSockets never
+start one. `rer door enable` stores the policy (`--port`, `--server-limit`,
+`--idle-timeout`) and the `RER_*` variables in effect, so whoever later starts
+the door cannot change what its checkouts run with. While it is enabled, `rer
+dev` sets fresh checkouts up behind it; `rer dev --door` moves an existing one
+(keeping its data), `rer dev --direct` moves it back, and `--port N` always
+serves directly. `rer door start`, `stop`, `restart`, `disable` and `remove
+NAME` do what they say; after a reboot or logout the door needs `rer door
+start`. `rer door --help` has the details.
+
 ## Find what to launch
 
 ```sh
@@ -144,15 +169,101 @@ 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`, `/signature` | release export, publication scan and shared signature verifier | `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`
 there lists its flags:
 
 `install`, `setup`, `dev`, `preview`, `build`, `verify`, `reset --yes`, `deploy`,
-`export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`.
+`export`, `import`, `outbox`, `doctor`, `describe`, `check`, `release`,
+`release sign`, `release receipt` and `release keygen`.
 
 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') };