@runeditrun/rer 0.2.0 → 0.2.1

package/cli/site-markup.mjs

@@ -0,0 +1,102 @@
+import { decodedText } from './site-data.mjs';
+
+// CSS strings and identifiers have their own escapes; comments can separate an
+// at-rule or a function from its value. Tokenize them before selecting URLs.
+export const decodeCSS = text => text.replace(/\\(?:([\da-f]{1,6})\s?|([^\r\n\f]))|\\(?:\r\n|[\r\n\f])/gi, (_, hex, char) => hex ? String.fromCodePoint(parseInt(hex, 16) > 0x10ffff ? 0xfffd : parseInt(hex, 16) || 0xfffd) : char ?? '');
+function cssTokens(text) {
+ const tokens = [];
+ for (let i = 0; i < text.length;) {
+  if (/\s/.test(text[i])) { i++; continue; }
+  if (text.slice(i, i + 2) === '/*') { const end = text.indexOf('*/', i + 2); i = end < 0 ? text.length : end + 2; continue; }
+  const start = i, quote = text[i] === '"' || text[i] === "'" ? text[i++] : null;
+  if (quote) {
+   const begin = i;
+   while (i < text.length && text[i] !== quote) { if (text[i] === '\\') i++; i++; }
+   tokens.push({type:'string', value:decodeCSS(text.slice(begin, i))}); i++;
+  } else if (/[a-z0-9_@#./%~-]/i.test(text[i]) || text[i] === '\\') {
+   while (i < text.length && !/[\s(){};:,"']/.test(text[i])) {
+    if (text[i] === '\\') { const escape = /^\\(?:[\da-f]{1,6}\s?|[^\r\n\f])/i.exec(text.slice(i)); if (escape) { i += escape[0].length; continue; } }
+    if (text.slice(i, i + 2) === '/*') break;
+    i++;
+   }
+   tokens.push({type:'word', value:decodeCSS(text.slice(start, i))});
+  } else tokens.push({type:text[i], value:text[i++]});
+ }
+ return tokens;
+}
+export const cssStrings = text => cssTokens(text).filter(token => token.type === 'string').map(token => token.value);
+export function cssReferences(text) {
+ const tokens = cssTokens(text), found = [];
+ for (let i = 0; i < tokens.length; i++) {
+  const token = tokens[i], name = token.value.toLowerCase();
+  if (token.type === 'word' && ['@import','@use','@forward'].includes(name) && tokens[i + 1]?.type === 'string') found.push({url:tokens[i + 1].value, import:true, navigates:false});
+  if (token.type === 'word' && name === 'url' && tokens[i + 1]?.type === '(') {
+   let j = i + 2, url = '';
+   while (j < tokens.length && tokens[j].type !== ')') url += tokens[j++].value;
+   found.push({url, import:tokens[i - 1]?.value.toLowerCase() === '@import', navigates:false});
+  }
+  if (token.type === 'word' && ['image-set','-webkit-image-set'].includes(name) && tokens[i + 1]?.type === '(') {
+   for (let j = i + 2, depth = 1; j < tokens.length && depth; j++) {
+    if (tokens[j].type === '(') depth++;
+    if (tokens[j].type === ')') depth--;
+    if (depth === 1 && tokens[j].type === 'string') found.push({url:tokens[j].value,navigates:false});
+   }
+  }
+ }
+ return found;
+}
+
+// Attribute values may be quoted or unquoted. Raw script/style content is not
+// parsed as tags, and a quoted greater-than sign does not end its tag.
+export function htmlElements(text) {
+ const elements = [], tags = /<!--[\s\S]*?(?:-->|$)|<([a-z][a-z0-9:-]*)\b((?:[^"'<>]|"[^"]*"|'[^']*')*)>/gi;
+ for (let match; (match = tags.exec(text));) {
+  if (!match[1]) continue;
+  const tag = match[1].toLowerCase(), attributes = new Map();
+  for (const attribute of match[2].matchAll(/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) {
+   const name = attribute[1].toLowerCase();
+   if (!attributes.has(name)) attributes.set(name, decodedText(attribute[2] ?? attribute[3] ?? attribute[4] ?? ''));
+  }
+  let content;
+  if (['script','style','textarea','title'].includes(tag)) {
+   const end = new RegExp('</' + tag + '\\s*>', 'ig'); end.lastIndex = tags.lastIndex;
+   const closing = end.exec(text);
+   content = text.slice(tags.lastIndex, closing?.index ?? text.length);
+   tags.lastIndex = closing ? end.lastIndex : text.length;
+  }
+  elements.push({tag, attributes, content});
+ }
+ return elements;
+}
+
+// Preserve markup/CSS string boundaries when those languages occur inside a
+// JavaScript string. A quote delimiting an attribute is not part of its value.
+export function markupStrings(text) {
+ const values = [];
+ for (const {tag, attributes, content} of htmlElements(text)) {
+  values.push(...attributes.values());
+  if (tag === 'style') values.push(...cssStrings(content));
+  if (attributes.has('style')) values.push(...cssStrings(attributes.get('style')));
+  if (attributes.has('srcdoc')) values.push(...markupStrings(attributes.get('srcdoc')));
+ }
+ return values;
+}
+
+// Shared for complete pages and markup created by a browser island.
+export function markupReferences(text, html) {
+ const found = [];
+ if (!html) return cssReferences(text);
+ for (const {tag, attributes, content} of htmlElements(text)) {
+  const rel = attributes.get('rel') ?? '';
+  if (tag === 'style') found.push(...cssReferences(content));
+  for (const [attribute, value] of attributes) {
+   const name = attribute === 'xlink:href' ? 'href' : attribute;
+   if (name === 'style') found.push(...cssReferences(value));
+   if (!['href','src','srcset','action','formaction','poster','data'].includes(name)) continue;
+   const navigates = name === 'href' && (['a','area'].includes(tag) || (tag === 'link' && /\b(?:canonical|alternate|author|license|help|me)\b/i.test(rel)));
+   const values = name === 'srcset' ? value.split(',').map(part => part.trim().split(/\s+/)[0]).filter(Boolean) : [value];
+   for (const url of values) found.push({url, navigates});
+  }
+ }
+ return found;
+}

package/cli/site-private.mjs

@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+import { readFile, realpath } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { identityPattern } from './site-check.mjs';
+const run = promisify(execFile);
+
+// An identity is a public example only when the entire source file is the
+// committed blob, unchanged in both index and working tree. Secrets never qualify.
+export async function unpublishedIdentities(root, identities, privateFiles = []) {
+ identities = [...new Set(identities)].filter(value => typeof value === 'string' && value.length);
+ if (!identities.length) return [];
+ const git = args => run('git', args, {cwd:root, maxBuffer:32 * 1024 * 1024, encoding:'buffer'});
+ let paths, prefix;
+ try {
+  prefix = (await git(['rev-parse', '--show-prefix'])).stdout.toString().trim();
+  paths = (await git(['ls-files', '--cached', '-z'])).stdout.toString().split('\0').filter(Boolean);
+  await git(['rev-parse', '--verify', 'HEAD']);
+ } catch (error) { if (error.code === 128) return identities; throw error; }
+ const patterns = identities.map(identityPattern), published = new Set();
+ for (const path of paths) {
+  if (!/\.(?:[cm]?[jt]sx?|md|html|css|json|jsonc|toml|txt|ya?ml)$/.test(path) || path.split('/').some(part => part.startsWith('.')) || privateFiles.some(file => path === file || path.startsWith(file + '/'))) continue;
+  const file = resolve(root, path), physical = await realpath(file).catch(() => null);
+  if (!physical || relative(resolve(root), physical).split(sep).includes('..') || physical !== file) continue;
+  const bytes = await readFile(file), text = bytes.toString('utf8');
+  const matches = patterns.map(({pattern}, index) => !published.has(index) && pattern.test(text) ? index : -1).filter(index => index >= 0);
+  if (!matches.length) continue;
+  try {
+   await git(['diff', '--quiet', 'HEAD', '--', path]);
+   const indexed = (await git(['show', ':' + prefix + path])).stdout;
+   const committed = (await git(['show', 'HEAD:' + prefix + path])).stdout;
+   if (bytes.equals(indexed) && bytes.equals(committed)) for (const index of matches) published.add(index);
+  } catch (error) { if (![1,128].includes(error.code)) throw error; }
+ }
+ return identities.filter((_, index) => !published.has(index));
+}

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

@@ -9,12 +9,13 @@
 // 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, rm, writeFile } from 'node:fs/promises';
+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] = process.argv.slice(2);
+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; };
@@ -46,7 +47,9 @@ try {
  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 build = await module.sitePages({ styles });
+ 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();
@@ -68,8 +71,7 @@ try {
  }
  // Only the emitted files: the Node chunks share the folder and never ship.
  for (const file of files) {
-  await mkdir(dirname(join(output, file)), { recursive: true });
-  await cp(join(server, file), join(output, file), { errorOnExist: true, force: false });
+  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 }); }

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

@@ -6,6 +6,8 @@ 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
@@ -18,21 +20,28 @@ const relativePath = value => typeof value === 'string' && /^[A-Za-z0-9._/-]+$/.
 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)) || ['src', 'public', 'node_modules', 'migrations'].some(top => site.output === top || site.output.startsWith(top + '/'))) throw invalid('The declared run site needs a relative entry, an output folder outside src, public and node_modules, a deploy declaration and, when named, a relative site Vite config.');
+ 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 values = [], names = project.adapter.input?.names ?? {};
+ 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) || /SECRET|TOKEN|PASSWORD|_KEY$/.test(key)) values.push(value);
+ 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 of [names.email, names.name]) if (typeof answers?.[key] === 'string') values.push(answers[key]);
+ 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) values.push(key);
- return values;
+ 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. */
@@ -40,18 +49,26 @@ 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);
-  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 ? [site.config] : [])], { cwd: project.root, signal, heavy: false });
-  const checked = await checkSite(staging, { privateValues: await privateValues(project) });
+  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`].map(path => rm(path, { recursive: true, force: true }))); }
+ } finally { await Promise.all([staging, `${staging}.render`, `${staging}.refusal`].map(path => rm(path, { recursive: true, force: true }))); }
 }
 
 async function siteDeployment(project, options, folder) {
@@ -66,17 +83,21 @@ async function siteDeployment(project, options, folder) {
 /** `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 } };
+  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, domain: plan.domain, hostnames: plan.hostnames, workersDev: false, runWorkerFirst: true, assetsConfig: plan.assetsConfig, redirects: plan.redirects.map(({ from, to, status }) => ({ from, to, status })) };
+ 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.');

package/global/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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/global/README.md

@@ -247,7 +247,7 @@ line that still names it. A later refresh is a version bump:
 | `@runeditrun/rer/server-resources` | managed server resource readings (runtime journeys) | `scripts/base-cli/cli/server-resources.mjs` |
 | `@runeditrun/rer/operations` | OPERATIONS describe and check | `scripts/base-cli/operations/operations.mjs` |
 | `@runeditrun/rer/modules/portability`, `/catalogue`, `/cli`, `/cli-options`, `/files`, `/format`, `/http`, `/import`, `/journal`, `/legacy-safety`, `/migration-history`, `/storage` | portability module | `scripts/base-cli/modules/portability/*.mjs` |
-| `@runeditrun/rer/modules/release/export`, `/publication-scan`, `/source` | release export and publication scan | `scripts/base-cli/modules/release/*.mjs` |
+| `@runeditrun/rer/modules/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` |
@@ -260,7 +260,8 @@ In a checkout, every verb runs that checkout's own pinned `rer`; `rer VERB --hel
 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 queue NAME -- COMMAND`, `rer --version` and `rer --help`.

package/global/main.mjs

@@ -1,6 +1,7 @@
 import { dispatcher, locate, pinnedPackage, unsupportedMessage } from './checkout.mjs';
 import { delegate } from './delegate.mjs';
 import { localDefaults } from './launch/local-defaults.mjs';
+import { handleBrokenPipes } from './output.mjs';
 import { packageName as pinnedName } from './package-info.mjs';
 
 const help = `Usage: rer VERB [FLAGS]
@@ -37,6 +38,7 @@ outbox, doctor, describe, check, release. Run rer VERB --help in a checkout for
 const installsFirst = new Set(['install', 'check', 'describe']);
 
 export async function main(argv) {
+ handleBrokenPipes();
  const [verb] = argv;
  if (verb === '--version' || verb === '-v') return (await import('./version.mjs')).versionCommand(argv);
  // Only the zero-setup launch sets this, for its own setup child; an explicit

package/global/output.mjs

@@ -0,0 +1,12 @@
+let installed = false;
+
+export function handleBrokenPipes() {
+ if (installed) return;
+ installed = true;
+ for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', error => {
+   if (error.code === 'EPIPE') return;
+   throw error;
+  });
+ }
+}

package/global/rer.mjs

@@ -2,6 +2,9 @@
 // The installed `rer` command. This file avoids newer syntax so that an old
 // Node still reaches the one-line minimum-version message.
 import { readFileSync } from 'node:fs';
+import { handleBrokenPipes } from './output.mjs';
+
+handleBrokenPipes();
 
 function manifest() {
  // Packed: the package's own package.json. From a Base checkout: the template.

package/modules/deploy-kit/deploy.mjs

@@ -1,3 +1,4 @@
+import { recordDeployFailure } from './diagnostics.mjs';
 import { verifyServiceGrants } from './service-grants.mjs';
 import { assert, hash, validatePlan } from './validation.mjs';
 import { validateArtifact, publicAssetPaths } from './artifact.mjs';
@@ -55,8 +56,10 @@ export async function deploy({api,plan,artifact,artifactSha256,previousReceipt,r
   if (onReceipt) await onReceipt(receipt);
   // One built file proves the Worker hands static assets to the browser (assets run behind it).
   const asset = publicAssetPaths(artifact.assets.map(x => x.path))[0];
-  if (unchanged) await verifyHealth({...healthOptions,api,plan,receipt,fetch,asset});
-  else await firstHealth({api,plan,receipt,fetch,healthOptions,readiness,onHealth,asset});
+  try {
+    if (unchanged) await verifyHealth({...healthOptions,api,plan,receipt,fetch,asset});
+    else await firstHealth({api,plan,receipt,fetch,healthOptions,readiness,onHealth,asset});
+  } catch (error) { throw recordDeployFailure(error,{step:'health',...(error.code ? {code:error.code,output:error.message} : {})}); }
   return receipt;
 }
 

package/modules/deploy-kit/diagnostics.mjs

@@ -0,0 +1,55 @@
+// Provider text is private until the CLI's existing credential redactor approves
+// it. Identity, rather than mutable Error properties, carries this diagnostic.
+const failures = new WeakMap();
+export function recordDeployFailure(error, details) {
+  failures.set(error,{...failures.get(error),...details});
+  return error;
+}
+export function deployDiagnostic(error, redact) {
+  const detail = failures.get(error);
+  if (!detail) return undefined;
+  const clean = value => (redact ?? String)(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g,'').replace(/\b[a-f0-9]{32}\b/gi,'[REDACTED]');
+  const failureCode = detail.code ?? error.message;
+  const code = /^[a-zA-Z0-9_-]{1,120}$/.test(failureCode) ? clean(failureCode) : 'deploy-failed';
+  return {code,step:detail.step ?? 'deploy',created:(detail.created ?? []).map(clean),
+    ...(typeof error.resource==='string' && /^(?:d1|r2|kv|queues|worker|service):[a-z0-9-]+$/.test(error.resource) ? {resource:clean(error.resource)} : {}),
+    ...(detail.providerCodes?.length ? {providerCodes:detail.providerCodes} : {}),
+    output:(detail.output ? (redact ? clean(detail.output) : '(provider output withheld; rer deploy provides redacted details)') : '(no provider output)').split(/\r?\n/).slice(0,8).map(line=>line.slice(0,500)).join('\n')};
+}
+function operation(path, options = {}) {
+  const write = options.method && options.method !== 'GET';
+  if (/\/d1\/database\/[^/]+\/query/.test(path)) return 'migrate D1';
+  for (const [prefix,kind] of [['/d1/database','D1'],['/r2/buckets','R2'],['/queues','queue'],['/storage/kv/namespaces','KV']]) {
+    if (path === prefix && options.method === 'POST') return `create ${kind}`;
+    if (path.startsWith(prefix)) return `check ${kind}`;
+  }
+  if (path.includes('/secrets')) return 'secrets';
+  if (path.includes('/subdomain') || path.includes('/routes') || path.includes('/domains')) return 'route';
+  if (path.includes('/schedules')) return 'scheduled triggers';
+  if (write && path.startsWith('/workers/')) return 'upload Worker';
+  return 'check Worker';
+}
+export function deploymentDiagnostics(api, {onCreated} = {}) {
+  const created = [];
+  const recordCreated = resource => { created.push(resource); onCreated?.(resource); };
+  let currentStep = 'prepare deploy';
+  const guard = method => async (path, options) => {
+    const step = operation(path,options);
+    currentStep = step;
+    try {
+      const result = await api[method](path,options);
+      if (step.startsWith('create ')) recordCreated(`${step.slice(7)}:${options.body.name ?? options.body.queue_name ?? options.body.title}`);
+      return result;
+    } catch (error) { throw recordDeployFailure(error,{step,created:[...created]}); }
+  };
+  return {...api,request:guard('request'),list:guard('list'),envelope:guard('envelope'),recordCreated,
+    annotateFailure(error, step = currentStep) {
+      const prior = failures.get(error);
+      // Node filesystem/CLI codes are structural; their messages can hold paths
+      // and inputs, so retain them privately for the caller's redaction boundary.
+      const cliCode = typeof error.code === 'string' && /^(?:E[A-Z0-9_]{1,63}|health-[a-z-]+)$/.test(error.code) ? error.code : undefined;
+      recordDeployFailure(error,{step:prior?.step ?? step,created:prior?.created ?? [...created],
+        ...(!prior?.code && cliCode ? {code:cliCode,...(!prior?.output ? {output:error.message} : {})} : {})});
+      return error;
+    }};
+}

package/modules/deploy-kit/owner-cli.mjs

@@ -1,3 +1,4 @@
+import { deploymentDiagnostics, deployDiagnostic } from './diagnostics.mjs';
 import { execFileSync } from 'node:child_process';
 import { resolve, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -21,7 +22,7 @@ async function ownerArtifact(root, product) {
 }
 
 /** Inputs: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, plus the secrets the declaration names on first deploy. */
-export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, localOnlyKeys = [], notice = line => console.error(line)} = {}) {
+export async function main(argv = process.argv.slice(2), env = process.env, {fetch = globalThis.fetch, cwd = process.cwd(), healthOptions, localOnlyKeys = [], notice = line => console.error(line), onCreated} = {}) {
   let parsed;
   try { parsed = parseArgs({args:argv,allowPositionals:true,strict:true,options:{declaration:{type:'string'},environment:{type:'string'},product:{type:'string',default:''},state:{type:'string'}}}); }
   catch { throw new Error('usage'); }
@@ -36,23 +37,28 @@ export async function main(argv = process.argv.slice(2), env = process.env, {fet
   try { declaration = JSON.parse(await regularBytes(resolve(root,values.declaration),256 * 1024)); }
   catch (error) { throw new Error(error.code === 'ENOENT' ? 'missing-owner-declaration' : 'invalid-owner-declaration'); }
   assert(typeof declaration?.project === 'string','missing-owner-project');
-  const api = cloudflare({accountId:env.CLOUDFLARE_ACCOUNT_ID,token:env.CLOUDFLARE_API_TOKEN,fetch});
+  const api = deploymentDiagnostics(cloudflare({accountId:env.CLOUDFLARE_ACCOUNT_ID,token:env.CLOUDFLARE_API_TOKEN,fetch}),{onCreated});
   const target = await ownerTarget(api,{project:declaration.project,environment:values.environment});
   const statePath = values.state ? resolve(root,values.state) : join(root,'.rer','deploy',`${target.environment}.json`);
   const artifact = await ownerArtifact(root,values.product);
   const plan = ownerPlan(target,declaration,artifact,{localOnlyKeys});
   if (command === 'health') {
-    await ownerHealth({api,target,plan,statePath,fetch,healthOptions:{...healthOptions,readiness:{single:true,totalMs:30000}}});
+    await ownerHealth({api,target,plan,statePath,fetch,healthOptions:{...healthOptions,readiness:{single:true,totalMs:30000}}}).catch(error=>{throw api.annotateFailure(error,'health');});
     return {ok:true,worker:target.worker,origin:target.origin};
   }
   // Dispatch is the provider's: on some accounts a new Cron starts only at the account scheduler's next refresh.
   if (plan.crons.length) notice(cronNotice);
-  const {receipt,created} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions});
+  const {receipt,created} = await ownerDeploy({api,target,plan,artifact,statePath,env,fetch,healthOptions}).catch(error => {
+    api.annotateFailure(error,error.message.startsWith('missing-secret-') ? 'secrets' : undefined);
+    throw error;
+  });
   return {ok:true,changed:receipt.changed,worker:target.worker,origin:receipt.origin,versionId:receipt.provider.versionId,created,state:statePath};
 }
 
 /** Prints refusal codes and resource names only; never inputs, tokens or provider bodies. */
 export function report(error) {
+  const diagnostic = deployDiagnostic(error);
+  if (diagnostic) return {ok:false,...diagnostic};
   if (error.message === 'missing-input') return {ok:false,code:'missing-input',inputs:error.inputs};
   if (error.message === 'usage') return {ok:false,code:'usage',usage};
   return {ok:false,code:/^[a-zA-Z0-9_-]{1,120}$/.test(error.message) ? error.message : 'owner-deploy-failed',...(error.resource ? {resource:error.resource} : {})};

package/modules/deploy-kit/owner.mjs

@@ -273,6 +273,9 @@ async function deployLocked({api, target, plan, artifact, statePath, env, fetch,
     }
     const result = await api.request(path, options);
     if (sending) {
+      // A successful upload creates a Worker only when ownership preflight found
+      // it absent. Record it before readback, which can fail after creation.
+      if (!exists) api.recordCreated?.(`Worker:${plan.worker}`);
       const active = await activeWorker(api, plan.worker);
       assert(active && deployedFingerprint(active.settings) === state.pendingUpload.fingerprint, 'uploaded-worker-drift');
       state.pendingUpload.provider = {versionId:active.versionId,deploymentId:active.deploymentId,etag:active.etag};