@runeditrun/rer 0.2.0 → 0.2.2

package/cli/site-references.mjs

@@ -0,0 +1,243 @@
+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, htmlElements } from './site-markup.mjs';
+
+// A firstChild expression is not a type proof: its parent may contain an
+// object element. Admit CharacterData only from an unambiguous emitted text
+// child, consistent across all pages, with no script that can replace it.
+export function javascriptContext(documents, trees) {
+ const children = new Map();
+ // Recognize a balanced subset of ordinary HTML, rather than guessing at
+ // browser repair rules. Tables, foreign content, templates and formatting
+ // reconstruction leave every node unknown. Common page links, headings and
+ // buttons are safe when explicitly closed in their ordinary insertion mode.
+ const containers = new Set('p div span section article aside nav header footer main object a button h1 h2 h3 h4 h5 h6 ul ol li dl dt dd figure figcaption details summary'.split(' '));
+ const voids = new Set('br hr img input link meta wbr'.split(' '));
+ const raw = new Set(['script','style','title','textarea']);
+ const ordinary = new Set([...containers, ...voids, ...raw, 'html','head','body']);
+ const blocks = new Set('p div section article aside nav header footer main h1 h2 h3 h4 h5 h6 ul ol li dl dt dd figure figcaption details summary hr'.split(' '));
+ const unknown = () => ({textParents:new Set()});
+ for (const text of documents) {
+  const seen = new Set(), structure = new Set(), stack = [];
+  const tags = /<!--[\s\S]*?(?:-->|$)|<!doctype\s+html\s*>|<\/?([a-z][a-z0-9:-]*)\b((?:[^"'<>]|"[^"]*"|'[^']*')*)>|[^<]+|</gi;
+  for (let match; (match = tags.exec(text));) {
+   if (match[0] === '<') return unknown();
+   if (match[0].startsWith('<!--') && !/^<!--(?:[^<>-]|-(?!-))*-->$/.test(match[0])) return unknown();
+   if (!match[1]) continue;
+   const tag = match[1].toLowerCase();
+   if (!ordinary.has(tag)) return unknown();
+   if (match[0].startsWith('</')) {
+    if (match[2].trim() || stack.pop() !== tag) return unknown();
+    continue;
+   }
+   // Reject malformed attributes and non-void self-closing tags, which HTML
+   // parses differently from XML. Never infer text from the repaired tree.
+   if (!/^(?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*\s*\/?$/.test(match[2]) || (!voids.has(tag) && /\/\s*$/.test(match[2]))) return unknown();
+   if (stack.includes('head') && !['meta','link','title','style','script'].includes(tag)) return unknown();
+   if ((blocks.has(tag) && stack.includes('p')) || (['a','button','li'].includes(tag) && stack.includes(tag)) || (/^h[1-6]$/.test(tag) && stack.some(parent => /^h[1-6]$/.test(parent))) || (['dt','dd'].includes(tag) && stack.some(parent => ['dt','dd'].includes(parent)))) return unknown();
+   if (['html','head','body'].includes(tag)) {
+    if (structure.has(tag) || stack.some(parent => parent !== 'html') || (tag === 'html' && stack.length) || (tag === 'head' && structure.has('body'))) return unknown();
+    structure.add(tag);
+   }
+   const {attributes} = htmlElements(match[0])[0];
+   if ([...attributes.keys()].some(name => name.startsWith('on'))) return unknown();
+   const id = attributes.get('id');
+   if (id !== undefined) {
+    const firstText = /^[^<]*/.exec(text.slice(tags.lastIndex))[0].replace(/\0/g, '');
+    const textChild = containers.has(tag) && firstText.length > 0;
+    children.set(id, textChild && !seen.has(id) && children.get(id) !== false);
+    seen.add(id);
+   }
+   if (raw.has(tag)) {
+    if (tag === 'script' && !/^(?:|module|(?:text|application)\/(?:java|ecma)script|application\/(?:ld\+)?json)$/i.test(attributes.get('type') ?? '')) return unknown();
+    const closing = new RegExp('</' + tag + '(?=[\\s/>])[^>]*>', 'ig'); closing.lastIndex = tags.lastIndex;
+    const end = closing.exec(text);
+    if (!end || !new RegExp('^</' + tag + '\\s*>$', 'i').test(end[0])) return unknown();
+    if (tag === 'script' && /<!--|<script\b/i.test(text.slice(tags.lastIndex, end.index))) return unknown();
+    tags.lastIndex = closing.lastIndex;
+   } else if (!voids.has(tag)) stack.push(tag);
+  }
+  if (stack.length) return unknown();
+ }
+ // Include every emitted script: a different island can change the selected
+ // element, its id or its children before this assignment runs.
+ const nativeMethods = new Set(['querySelector','querySelectorAll','getElementById','getElementsByTagName','getElementsByClassName','getElementsByName','createElement','createElementNS','getAttribute','hasAttribute','addEventListener','removeEventListener','setAttribute','setAttributeNS','removeAttribute','removeAttributeNS']);
+ const reflectiveMethods = new Set(['assign','defineProperty','defineProperties','setPrototypeOf','set','deleteProperty']);
+ const writes = new Set(['id','innerHTML','outerHTML','textContent','innerText','outerText','srcdoc','document','head','firstChild','__proto__',...nativeMethods,...reflectiveMethods]);
+ const changes = new Set(['before','after','append','prepend','appendChild','removeChild','replaceChild','replaceChildren','insertBefore','insertAdjacentHTML','insertAdjacentElement','insertAdjacentText','replaceWith','remove','write','writeln','setHTML','setHTMLUnsafe','normalize','insertNode','surroundContents','extractContents','deleteContents','adoptNode','execCommand','setAttributeNode','setAttributeNodeNS','__defineGetter__','__defineSetter__']);
+ let stable = true;
+ for (const tree of trees) {
+  const values = localValues(tree), browser = browserObjects(values);
+  // A newly created metadata link appended to the head cannot replace a
+  // selected text child in the body. Its resource URLs still get checked.
+  // Requiring fresh native nodes also excludes moving an existing child out
+  // of a text parent. Any id write above still invalidates this proof.
+  const documentObject = node => {
+   const alternatives = values.origins(node);
+   return alternatives.length > 0 && alternatives.every(browser.document);
+  };
+  const plainObject = node => {
+   const receivers = values.origins(node);
+   return receivers.length > 0 && receivers.every(value => value.type === 'ObjectExpression' && value.properties.every(property => property.type === 'Property' && property.kind === 'init'));
+  };
+  // Selector, traversal and head-link proofs depend on native DOM methods.
+  // Writes to those members, including prototype mutation through reflection,
+  // remove the proof across all emitted scripts. A known fresh plain object
+  // can still receive ordinary metadata without changing the native APIs.
+  const reflectiveMutation = node => values.names(node).some(name => reflectiveMethods.has(name))
+   && ['Object','Reflect'].some(name => values.global(node.object, name));
+  const writeTargets = node => {
+   if (!node) return [];
+   if (node.type === 'ObjectPattern') return node.properties.flatMap(property => writeTargets(property.value ?? property.argument));
+   if (node.type === 'ArrayPattern') return node.elements.flatMap(writeTargets);
+   if (node.type === 'AssignmentPattern') return writeTargets(node.left);
+   if (node.type === 'RestElement') return writeTargets(node.argument);
+   return [node];
+  };
+  const headLink = node => {
+   if (node?.type !== 'CallExpression' || memberName(node.callee) !== 'appendChild' || node.arguments.length !== 1) return false;
+   const receivers = values.origins(node.callee.object), arguments_ = values.origins(node.arguments[0]);
+   return receivers.length > 0 && receivers.every(receiver => memberName(receiver) === 'head' && documentObject(receiver.object))
+    && arguments_.length > 0 && arguments_.every(value => value.type === 'CallExpression' && memberName(value.callee) === 'createElement' && value.arguments.length === 1
+     && documentObject(value.callee.object) && values.resources(value.arguments[0]).every(tag => tag.complete && tag.value.toLowerCase() === 'link'));
+  };
+  walkSyntax(tree, (node, parents) => {
+   const target = node.type === 'AssignmentExpression' ? node.left : node.type === 'UpdateExpression' || (node.type === 'UnaryExpression' && node.operator === 'delete') ? node.argument : undefined;
+   for (const write of writeTargets(target)) {
+    if (write.type === 'Identifier' && values.global(write, 'document')) stable = false;
+    if (write.type !== 'MemberExpression') continue;
+    const fields = values.names(write);
+    if ((!fields.length && !plainObject(write.object)) || fields.some(name => writes.has(name))) stable = false;
+   }
+   if (node.type === 'Property' && values.names(node).some(name => writes.has(name) || changes.has(name))) stable = false;
+   if (node.type === 'MemberExpression' && values.names(node).some(name => name === 'attributes' || changes.has(name)) && !headLink(parents.at(-1))) stable = false;
+   if (node.type === 'MemberExpression' && reflectiveMutation(node)) {
+    const call = parents.at(-1);
+    if (call?.type !== 'CallExpression' || call.callee !== node || !plainObject(call.arguments[0])) stable = false;
+   }
+   if (!['CallExpression','NewExpression'].includes(node.type)) return;
+   if (values.global(node.callee, 'eval') || values.global(node.callee, 'Function')) stable = false;
+   const appendsHeadLink = headLink(node);
+   for (const callee of values.origins(node.callee)) {
+    const methods = values.names(callee);
+    if (reflectiveMutation(callee) && !plainObject(node.arguments[0])) stable = false;
+    if (methods.some(name => changes.has(name)) && !appendsHeadLink) stable = false;
+    if (methods.some(name => ['setAttribute','setAttributeNS','removeAttribute','removeAttributeNS'].includes(name))) {
+     const index = methods.some(name => name.endsWith('NS')) ? 1 : 0, attributes = values.resources(node.arguments[index]);
+     if (attributes.some(({value, complete}) => !complete || /^(?:id|on.*)$/i.test(value))) stable = false;
+    } else if (!appendsHeadLink && node.arguments.some(argument => browser.dom(argument))) stable = false;
+    if (!appendsHeadLink && callee.type === 'MemberExpression' && (!methods.length || (browser.dom(callee.object) && methods.some(name => !nativeMethods.has(name))))) stable = false;
+   }
+  });
+ }
+ return {textParents:new Set(stable ? [...children].filter(([,text]) => text).map(([id]) => id) : [])};
+}
+
+export function javascriptContent(tree, {textParents = new Set()} = {}) {
+ 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']);
+ // Unknown DOM nodes retain the data URL check. A selector or traversal
+ // alone cannot distinguish HTMLObjectElement from CharacterData.
+ const characterData = node => {
+  const alternatives = origins(node);
+  return alternatives.length > 0 && alternatives.every(value => {
+   if (value.type !== 'MemberExpression' || memberName(value) !== 'firstChild') return false;
+   const parents = origins(value.object);
+   return parents.length > 0 && parents.every(parent => {
+    if (parent.type !== 'CallExpression') return false;
+    const receivers = origins(parent.callee.object);
+    if (!receivers.length || !receivers.every(browser.document)) return false;
+    const method = memberName(parent.callee), selectors = resources(parent.arguments[0]);
+    return ['querySelector','getElementById'].includes(method) && selectors.length > 0 && selectors.every(({value, complete}) => {
+     const id = method === 'getElementById' ? value : /^#([a-z_][\w-]*)$/i.exec(value)?.[1];
+     return complete && id !== undefined && textParents.has(id);
+    });
+   });
+  });
+ };
+ 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) && (name !== 'data' || !characterData(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,44 @@
 # Changelog
 
+## 0.2.2
+
+- `rer deploy` claims the hosted owner, exits cleanly when it finishes, changes and removes secrets safely, and removes the resources it created when you ask it to.
+- Local restore runs the seed's own restore-validation policies, so a seed no longer needs its own patch or adapter for them.
+- Hosted exports stay portable: the deploy kit's migration ledger is kept out of seed archives, compound D1 migrations such as triggers apply, and an archive or import target with uncertain migration history is refused.
+- Package-mode guidance in the exported docs names the commands a package-mode seed actually runs, and the local-run docs describe the sign-in outbox.
+- `rer release --help` and the job-queue help print their usage.
+- `rer describe` reports the effects a seed declares for each command instead of generic account effects.
+- Linked OIDC providers report health from the token exchange, stay healthy when one authorization code is rejected, and send failures to the configured sign-in path.
+- The run-site privacy check catches registered secrets inside prefixed base64 and accepts constant text that a client island imports.
+- Fresh rer launches provision pnpm, prefer the provisioned pnpm, keep state under your HOME, and clean up their probe processes.
+- Base can export a seed Verify workflow with source freshness checks for manual adoption.
+- Base's default seed and source import kit erase a person in bounded steps after retiring their imported custody; this kit is outside the rer npm package.
+
+## 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

@@ -22,8 +22,11 @@ refuses archives with absolute paths, `..` entries, links or devices, then runs
 the package's own `rer cli install`. A failed or refused download leaves the
 version you had selected.
 
-No installer edits shell profiles. When `~/.local/bin` is not on your PATH, the
-install prints the exact line to add for your shell. The launcher runs `node` from
+No installer edits shell profiles. The canonical launcher is `~/.local/bin/rer`.
+When that directory is absent from PATH, installation also links it into an
+existing writable, user-owned PATH directory if available, preserving foreign
+commands. Otherwise it prints one activation line to run in the current shell:
+`export PATH="$HOME/.local/bin:$PATH"` (with fish syntax for fish). The launcher runs `node` from
 PATH, so a Node upgrade does not break it. A re-run with the same build changes
 nothing; a different build is installed beside the current one, the previous one
 is kept and older ones are removed. It refuses to replace a `~/.local/bin/rer`
@@ -247,7 +250,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,9 +263,17 @@ 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`.
 
 Licence: MIT.
+
+First-party commands acquire the exact `packageManager` pnpm pin when PATH lacks
+it, verify its registry sha512 integrity and cache it under `$HOME/.rer/pnpm`.
+No global package manager installation or sudo is needed. Independent projects
+continue to run their declared commands with their own tools. Server and job
+state default to `$HOME/.rer/servers` and `$HOME/.rer/jobs`; supplied
+`RER_SERVERS_DIR` and `RER_JOBS_DIR` take precedence and are passed to older pins.

package/global/cli/install.mjs

@@ -2,10 +2,12 @@
 // version directory, switch `current` atomically, keep the previous version,
 // prune older ones and write the launcher. Never edits shell profiles.
 import { randomUUID } from 'node:crypto';
-import { chmod, cp, mkdir, readdir, readlink, realpath, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import { access, constants, chmod, cp, mkdir, readdir, readlink, realpath, rename, rm, symlink, writeFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
 import { ownManifest, ownRoot, packageDigest, packageFileList } from '../package-info.mjs';
 import { installRecord, launcherOwner, launcherScript, layout } from './layout.mjs';
+import { exposeLauncher } from './path-link.mjs';
+import { shellQuote } from '../../cli/node-runtime-cache.mjs';
 import { runningDoor } from '../../cli/door.mjs';
 
 async function readLink(path) { try { return await readlink(path); } catch (error) { if (['ENOENT', 'EINVAL'].includes(error.code)) return undefined; throw error; } }
@@ -38,13 +40,20 @@ async function writeLauncher(paths) {
  await rename(temporary, paths.launcher);
 }
 
-export function pathAdvice(paths, env = process.env) {
+export async function pathAdvice(paths, env = process.env) {
  const entries = (env.PATH ?? '').split(':').filter(Boolean).map(entry => resolve(entry));
- if (entries.includes(resolve(paths.bin))) return undefined;
- const shell = basename(env.SHELL ?? '');
- if (shell === 'fish') return `${paths.bin} is not on your PATH. Run this once in fish, then open a new terminal:\n  fish_add_path $HOME/.local/bin`;
- const profile = shell === 'zsh' ? '~/.zshrc' : shell === 'bash' ? (process.platform === 'darwin' ? '~/.bash_profile' : '~/.bashrc') : '~/.profile';
- return `${paths.bin} is not on your PATH. Add this line to ${profile}, then open a new terminal:\n  export PATH="$HOME/.local/bin:$PATH"`;
+ for (const directory of entries) {
+  if (directory === resolve(paths.bin)) return undefined;
+  const candidate = join(directory, 'rer');
+  try {
+   await access(candidate, constants.X_OK);
+   const found = await launcherOwner(await realpath(candidate));
+   if (found.state === 'ours' && found.root === paths.data) return undefined;
+   break; // This command shadows the canonical launcher, even if it is later on PATH.
+  } catch (error) { if (!['ENOENT', 'EACCES', 'ENOTDIR'].includes(error.code)) throw error; }
+ }
+ if (basename(env.SHELL ?? '') === 'fish') return `Activate rer in this shell:\n  set -gx PATH ${shellQuote(paths.bin)} $PATH`;
+ return `Activate rer in this shell:\n  export PATH=${shellQuote(paths.bin)}:"$PATH"`;
 }
 
 export async function install() {
@@ -59,8 +68,8 @@ export async function install() {
  const script = launcherScript(paths.data);
  let present = false;
  try { present = await packageDigest(join(paths.versions, name)) === digest; } catch (error) { if (error.code !== 'ENOENT') throw error; }
- const advice = pathAdvice(paths);
  if (present && current === join('versions', name) && launcher.text === script && record?.channel === channel) {
+  const advice = await activation(paths, record);
   process.stdout.write(`rer ${manifest.version} is already current (${join(paths.versions, name)}). Nothing changed.\n${advice ? advice + '\n' : ''}`);
   return 0;
  }
@@ -72,8 +81,16 @@ export async function install() {
  const doorVersion = door?.versionDir && resolve(door.versionDir, '..') === await realpath(paths.versions).catch(() => resolve(paths.versions)) ? basename(door.versionDir) : undefined;
  const keep = new Set([name, previousName, doorVersion].filter(Boolean));
  for (const entry of await readdir(paths.versions)) if (!keep.has(entry) && !entry.startsWith('.staging-')) await rm(join(paths.versions, entry), { recursive: true, force: true });
- await writeFile(paths.record, JSON.stringify({ channel, previous: previousName && keep.has(previousName) ? previousName : null }, null, 2) + '\n', { mode: 0o644 });
+ await writeFile(paths.record, JSON.stringify({ channel, links: record?.links ?? [], previous: previousName && keep.has(previousName) ? previousName : null }, null, 2) + '\n', { mode: 0o644 });
  if (launcher.text !== script) await writeLauncher(paths);
+ const advice = await activation(paths, await installRecord(paths));
  process.stdout.write(`Installed rer ${manifest.version} in ${join(paths.versions, name)}.\n${paths.launcher} runs it.${previousName ? ` The previous version (${previousName}) is kept.` : ''}\n${advice ? advice + '\n' : ''}`);
  return 0;
 }
+
+async function activation(paths, record) {
+ const link = await exposeLauncher(paths);
+ const links = [...new Set([...(record?.links ?? []), ...(link ? [link] : [])])];
+ if (JSON.stringify(record?.links ?? []) !== JSON.stringify(links)) await writeFile(paths.record, JSON.stringify({ ...record, links }, null, 2) + '\n', { mode: 0o644 });
+ return link ? undefined : await pathAdvice(paths);
+}

package/global/cli/path-link.mjs

@@ -0,0 +1,30 @@
+// Offer the canonical launcher through an existing user-owned PATH directory.
+// Foreign commands and links are never replaced, including during uninstall.
+import { access, constants, lstat, readlink, symlink } from 'node:fs/promises';
+import { delimiter, isAbsolute, join, resolve } from 'node:path';
+
+export async function ownedPathLink(path, launcher) {
+ try { return (await lstat(path)).isSymbolicLink() && (await readlink(path)) === resolve(launcher); }
+ catch (error) { if (error.code === 'ENOENT' || error.code === 'EINVAL') return false; throw error; }
+}
+export async function exposeLauncher(paths, env = process.env) {
+ for (const entry of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
+  const directory = resolve(entry), candidate = join(directory, 'rer');
+  if (directory === resolve(paths.bin)) return undefined;
+  try {
+   try {
+    await lstat(candidate);
+    if (await ownedPathLink(candidate, paths.launcher)) return candidate;
+    await access(candidate, constants.X_OK);
+    return undefined;
+   } catch (error) { if (error.code !== 'ENOENT') continue; }
+   // npm/npx add transient command directories; never install into them.
+   if (!isAbsolute(entry) || directory.split('/').includes('node_modules') || directory.split('/').includes('_npx')) continue;
+   const info = await lstat(directory);
+   if (!info.isDirectory() || !process.getuid || info.uid !== process.getuid() || (!(info.mode & 0o200) || (info.mode & 0o022))) continue;
+   await access(directory, constants.W_OK | constants.X_OK);
+   try { await symlink(paths.launcher, candidate); return candidate; }
+   catch (error) { if (error.code !== 'EEXIST' && error.code !== 'EACCES' && error.code !== 'EPERM') throw error; }
+  } catch (error) { if (!['ENOENT', 'EACCES', 'ENOTDIR'].includes(error.code)) throw error; }
+ }
+}

package/global/cli/status.mjs

@@ -24,7 +24,7 @@ export async function pathCommands(installRoot, env = process.env) {
   seen.add(candidate);
   try { await access(candidate, constants.X_OK); } catch { continue; }
   const target = await real(candidate);
-  const launcher = await launcherOwner(candidate);
+  const launcher = await launcherOwner(target ?? candidate);
   if (target && inside(target, ownRoot) || launcher.state === 'ours' && launcher.root && await real(launcher.root) === installRoot) self.push(candidate);
   else others.push(candidate);
  }