@runeditrun/rer 0.0.0-stage → 0.1.0

package/cli/deploy.mjs

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { contained } from './project.mjs';
+import { missing, invalid, refuse } from './errors.mjs';
+import { ownerPlan, ownerWorkerName, localOnlyBinding } from '../modules/deploy-kit/owner.mjs';
+import { packageBuild } from '../modules/deploy-kit/prepare.mjs';
+import { refuseLocalModels } from '../modules/deploy-kit/local-only.mjs';
+
+export function ownerDeploy(declarationPath, lifecycle) {
+ // rer verify serves the build with this declaration's vars and secrets.
+ return Object.assign(async ({ root, options, store, signal, operationToken, localOnlyKeys = [], checkBuild = async () => {} }) => {
+  try { await refuseLocalModels(root); } catch { throw refuse('Deploy refuses the local-only key file .rer/local/models.json. Remove live-dev credentials before deployment.'); }
+  const path = await contained(root, declarationPath);
+  let declaration; try { declaration = JSON.parse(await readFile(path, 'utf8')); } catch { throw invalid('Malformed owner-account deploy declaration.'); }
+  const local = localOnlyBinding(declaration, localOnlyKeys);
+  if (local) throw refuse(`${declarationPath} names the local-only key ${local} as a deploy binding or secret. Remove it; local dev keys never reach a deployment.`);
+  const environment = options.environment ?? 'production';
+  await lifecycle.run(root, {}, store, () => {}, signal, { verb: 'build', operationToken });
+  await checkBuild();
+  if (options.dryRun) {
+   // Locally validate the real declaration/artifact without ownerTarget's
+   // account lookup. This synthetic target is validation data, not a provider.
+   const worker = ownerWorkerName(declaration.project, environment);
+   const artifact = await packageBuild({ root, source: { sha: '0'.repeat(40), tree: '0'.repeat(40) }, runIdentity: { id: '0', attempt: '1' }, productDirectory: '' });
+   ownerPlan({ project: declaration.project, environment, worker, origin: `https://${worker}.example.invalid` }, declaration, artifact, { localOnlyKeys });
+   store.report('deploy: dry run complete; no deployment occurred and no provider request was made.');
+   return { dryRun: true, deployed: false };
+  }
+  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. See the deploy-kit owner-account instructions.');
+  const { main } = await import('../modules/deploy-kit/owner-cli.mjs');
+  const argv = ['deploy', '--declaration', declarationPath, '--environment', environment];
+  const result = await main(argv, process.env, { cwd: root, localOnlyKeys, notice: line => store.report(line) });
+  await main(['health', ...argv.slice(1)], process.env, { cwd: root, localOnlyKeys });
+  return { deployed: true, origin: result.origin };
+ }, { declaration: declarationPath });
+}

package/cli/dev-identity.mjs

@@ -0,0 +1,80 @@
+import { randomBytes } from 'node:crypto';
+import { lstat, open, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { shared } from './shared.mjs';
+import { contained } from './project.mjs';
+import { invalid, missing, refuse } from './errors.mjs';
+import { loopback } from './parse.mjs';
+
+// The per-checkout key gate. Setup writes RER_DEV_KEY (32 random bytes) to
+// owner-only .rer/local/ (directory 0700, file 0600); a repeat setup keeps it,
+// reset removes it with the rest of .rer/local. Only local runtimes receive it.
+export const DEV_KEY_FILE = '.rer/local/dev-key.env';
+export const DEV_KEY_HEADER = 'x-rer-dev-key';
+// modules/operator-auth/dev/index.mjs DEV_LAYER_MARKER: present in any output
+// that bundles the local-only dev layer.
+export const DEV_LAYER_MARKER = 'rer-dev-layer:local-only-never-deploy';
+export const DEV_AI_MARKER = 'rer-ai-dev:local-only-never-deploy';
+const KEY = /^RER_DEV_KEY=([A-Za-z0-9_-]{43,256})\n?$/;
+
+export async function ensureDevKey(root) {
+ const existing = await readDevKey(root);
+ if (existing) return existing;
+ const { privateDirectory, writePrivateFile } = await shared('private-files.mjs');
+ const directory = await privateDirectory(root, ['.rer', 'local']), key = randomBytes(32).toString('base64url');
+ await writePrivateFile(join(directory, 'dev-key.env'), `RER_DEV_KEY=${key}\n`);
+ return key;
+}
+
+export async function readDevKey(root) {
+ let path; try { path = await contained(root, DEV_KEY_FILE, { privateFile: true }); } catch (error) { if (error.code === 'missing_input') return null; throw error; }
+ const { privateDirectory, readPrivateFile } = await shared('private-files.mjs');
+ await privateDirectory(root, ['.rer', 'local']);
+ const key = KEY.exec(await readPrivateFile(path))?.[1];
+ if (!key) throw refuse(`${DEV_KEY_FILE} is malformed. Run rer reset --yes, then rer setup, for a new key.`);
+ return key;
+}
+
+export async function requireDevKey(root) {
+ const key = await readDevKey(root);
+ if (!key) throw missing(`The local dev key ${DEV_KEY_FILE} is missing. Run rer setup to create it.`);
+ return key;
+}
+
+// RER_OPEN carries the key in the fragment only: browsers never send a
+// fragment to a server, and the page removes it from the address bar.
+export function openUrl(url, key, { path = '/', as, next } = {}) {
+ const fragment = new URLSearchParams({ 'rer-dev': key, ...(as ? { as } : {}), ...(next ? { next } : {}) });
+ return `${url}${path}#${fragment}`;
+}
+
+export function refuseManagedInstallation(...sources) {
+ for (const vars of sources) {
+  if (!vars?.RER_INSTALLATION_ID || !vars.RER_MANAGEMENT_ORIGIN) continue;
+  let host; try { host = new URL(vars.RER_MANAGEMENT_ORIGIN).hostname.replace(/^\[|\]$/g, ''); } catch {}
+  if (!loopback(host)) throw refuse('Dev identity refuses to start beside RER_INSTALLATION_ID with a non-loopback RER_MANAGEMENT_ORIGIN. Remove them from local settings or run rer dev --login.');
+ }
+}
+
+// The persona list the running app declares, read with the key header.
+export async function resolvePersona(url, key, as, signal) {
+ const response = await fetch(url + '/__dev/personas', { headers: { [DEV_KEY_HEADER]: key }, signal: AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean)) });
+ if (!response.ok) { await response.body?.cancel(); throw refuse(`The application did not serve dev identity (HTTP ${response.status}). Check its local-only entry.`); }
+ const personas = await response.json(), persona = personas.find(entry => entry.as === as);
+ if (!persona) throw invalid(`Unknown dev persona ${as}. This app declares: ${personas.map(entry => entry.as).join(', ')}.`);
+ return persona;
+}
+
+// rer build refuses output that bundles the dev layer, naming the file.
+export async function refuseDevLayerOutput(root, devIdentity) {
+ const markers = [DEV_LAYER_MARKER, DEV_AI_MARKER].map(value => Buffer.from(value));
+ async function walk(path) {
+  let status; try { status = await lstat(path); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  if (status.isDirectory()) { for (const entry of (await readdir(path)).sort()) await walk(join(path, entry)); return; }
+  if (!status.isFile()) return;
+  const file = await open(path, 'r');
+  try { const bytes = await file.readFile(); if (markers.some(marker => bytes.includes(marker))) throw refuse(`The build output contains the local-only dev layer: ${relative(root, path)}. Import dev modules only from the local entry ${devIdentity?.entry ?? 'server.dev'}.`); }
+  finally { await file.close(); }
+ }
+ for (const output of devIdentity?.output ?? ['dist']) await walk(await contained(root, output, { optional: true }));
+}

package/cli/errors.mjs

@@ -0,0 +1,14 @@
+export class RerError extends Error {
+ constructor(code, message, exitCode, details = {}) { super(message); Object.assign(this, { code, exitCode, ...details }); }
+}
+export const invalid = message => new RerError('invalid_invocation', message, 2);
+export const missing = message => new RerError('missing_input', message, 3);
+export const refuse = message => new RerError('safety_refusal', message, 4);
+
+export async function lifecycleError(error, store) {
+ if(error instanceof RerError)return error;
+ const {shared}=await import('./shared.mjs');
+ const {approvedFailure}=await shared('failures.mjs');
+ const approved=approvedFailure(error);
+ return new RerError(approved?.code==='owner_conflict'?'safety_refusal':'command_failed', approved?.message ?? `${store?.state?.step ?? 'Local lifecycle'} failed. Inspect the private redacted capture log.`, approved?.exitCode ?? 1, {childExitCode:approved?.childExitCode,signal:approved?.signal});
+}

package/cli/export.mjs

@@ -0,0 +1,42 @@
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { resolve, dirname, relative } from 'node:path';
+import { testSource } from '../composition/git-source.mjs';
+import { cliVersion } from './version.mjs';
+
+// Copy whole maintained source/tooling directories. Python publication scans
+// load sibling modules and data dynamically; they belong in the inventory too.
+export const sourceRoots = ['bin/rer.mjs', 'cli', 'modules/job-queue', 'modules/release', 'modules/deploy-kit', 'modules/container', 'modules/integrations/core', 'modules/mail', 'modules/ai', 'modules/portability', 'modules/erasure', 'modules/dependencies', 'modules/operator-auth', 'modules/owner-claim', 'operations', 'scripts/publish-check', 'scripts/publish-check.mjs', 'composition/git-source.mjs', 'edition-authoring/manifest.mjs', 'edition-authoring/files.mjs'];
+export async function inventory(base, roots = sourceRoots) {
+ const files = [];
+ async function walk(path) {
+  for (const entry of (await readdir(resolve(base, path), { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+   if (['node_modules', '__pycache__', '.state', '.wrangler', '.rer', '.seed', '.cache'].includes(entry.name)) continue;
+   const name = `${path}/${entry.name}`;
+   if (testSource(name)) continue;
+   if (entry.isDirectory()) await walk(name);
+   else if (entry.isFile()) files.push(name);
+   else throw Error('Non-file CLI export source');
+  }
+ }
+ for (const source of roots) { if (source.endsWith('.mjs')) files.push(source); else await walk(source); }
+ return files.sort();
+}
+
+export async function exportCLI(base, destination) {
+ const target = resolve(destination, 'scripts/base-cli');
+ await rm(target, { recursive: true, force: true });
+ await mkdir(target, { recursive: true });
+ const files = await inventory(base), record = {};
+ for (const path of files) {
+  const bytes = await readFile(resolve(base, path));
+  await mkdir(dirname(resolve(target, path)), { recursive: true });
+  await cp(resolve(base, path), resolve(target, path));
+  record[path] = { source: path, sha256: createHash('sha256').update(bytes).digest('hex') };
+ }
+ const onboardingFiles=Object.fromEntries(await Promise.all((await inventory(base,['onboarding'])).map(async path=>[path.slice('onboarding/'.length),{source:path,sha256:createHash('sha256').update(await readFile(resolve(base,path))).digest('hex')}])));
+ // cliVersion: the rer version of this Base source, which `rer describe` reports.
+ const version = cliVersion(base);
+ await writeFile(resolve(target, 'inventory.json'), JSON.stringify({ version: 1, ...(version ? { cliVersion: version } : {}), onboarding: '../base-onboarding', onboardingFiles, files: record }, null, 2) + '\n');
+ await writeFile(resolve(destination, 'scripts/rer.mjs'), "#!/usr/bin/env node\nimport { main } from './base-cli/cli/main.mjs';\nprocess.exitCode = await main();\n");
+}

package/cli/font-cache.mjs

@@ -0,0 +1,29 @@
+// Fonts must survive stylesheet replacement during dev hydration without a
+// network revalidation. Keep all other response headers (including repeated
+// Set-Cookie fields) in their original order.
+export function fontResponseHeaders(url, status, headers, requestHeaders = {}) {
+ if (![200, 206, 304].includes(status)) return headers;
+ let path;
+ try { path = new URL(url, 'http://localhost'); } catch { return headers; }
+ const index = headers.findIndex((value, index) => index % 2 === 0 && value.toLowerCase() === 'content-type');
+ const mime = index < 0 ? '' : headers[index + 1].split(';', 1)[0].trim().toLowerCase();
+ const fontType = /^(?:font\/[^;]+|application\/(?:font-(?:woff2?|sfnt)|x-font-(?:woff2?|ttf|otf|truetype|opentype)|vnd\.ms-opentype))$/.test(mime);
+ // Vite's ?import font modules are JavaScript, not font bytes. Likewise, an
+ // HTML route/error with a font suffix must retain its original policy.
+ // Conditional Vite module responses may omit Content-Type. Their transform
+ // queries or script destination still distinguish them from font bytes.
+ const transformed = requestHeaders['sec-fetch-dest'] === 'script' || ['import', 'raw', 'url', 'inline'].some(name => path.searchParams.has(name));
+ const fontPath = /\.(?:woff2?|ttf|otf)$/i.test(path.pathname) && (!mime || mime === 'application/octet-stream') &&
+  (requestHeaders['sec-fetch-dest'] === 'font' || !transformed);
+ if (!fontType && !fontPath) return headers;
+ const packageFont = path.pathname.split('/').includes('node_modules');
+ const hashed = /[.-][a-f0-9]{8,}\.(?:woff2?|ttf|otf)$/i.test(path.pathname) ||
+  /\/assets\/[^/]+-[A-Za-z0-9_-]{8}\.(?:woff2?|ttf|otf)$/.test(path.pathname) ||
+  /^[a-f0-9]{8,}$/i.test(path.searchParams.get('v') ?? '');
+ const result = [];
+ for (let i = 0; i < headers.length; i += 2) {
+  if (headers[i].toLowerCase() !== 'cache-control') result.push(headers[i], headers[i + 1]);
+ }
+ result.push('Cache-Control', packageFont || hashed ? 'public, max-age=31536000, immutable' : 'public, max-age=3600');
+ return result;
+}

package/cli/hosted-output.mjs

@@ -0,0 +1,110 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { createHash, randomBytes } from 'node:crypto';
+import { join, resolve, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { RUN_WORKER_FIRST } from '../modules/deploy-kit/render.mjs';
+import { publicAssetPaths } from '../modules/deploy-kit/artifact.mjs';
+import { migrate } from '../modules/container/migrations.mjs';
+import { RerError } from './errors.mjs';
+
+// Serve the production build the way rer deploy hosts it (assets behind the
+// Worker, deploy identity bound, a public https origin) on loopback, with no
+// network or account. The ingress hands the app the hosted URL and Host.
+const ORIGIN = 'https://rer-hosted-check.invalid';
+const ingress = `export default {fetch(request,env){const url=new URL(request.headers.get('x-rer-original-url')),headers=new Headers(request.headers);headers.delete('x-rer-original-url');headers.set('host',url.host);return env.APP.fetch(new Request(url,{method:request.method,headers,redirect:'manual',...(!['GET','HEAD'].includes(request.method)?{body:request.body}:{})}))}}`;
+const read = async path => JSON.parse(await readFile(path, 'utf8'));
+const optional = path => read(path).catch(error => { if (error.code === 'ENOENT') return {}; throw error; });
+
+async function files(root, directory = '') {
+ const result = [];
+ for (const entry of await readdir(join(root, directory), { withFileTypes: true })) {
+  const path = directory ? `${directory}/${entry.name}` : entry.name;
+  if (entry.isDirectory()) result.push(...await files(root, path)); else if (entry.isFile()) result.push(path);
+ }
+ return result.sort();
+}
+const moduleTypes = { '.js':'ESModule', '.mjs':'ESModule', '.cjs':'CommonJS', '.wasm':'CompiledWasm', '.bin':'Data', '.txt':'Text', '.html':'Text', '.sql':'Text' };
+
+// The seed's own wrangler carries the Miniflare its preview already runs.
+async function miniflareFor(root) {
+ const wrangler = createRequire(join(root, 'package.json')).resolve('wrangler/package.json');
+ return import(pathToFileURL(createRequire(wrangler).resolve('miniflare')));
+}
+
+// Deploy binds its declared secrets; stand-ins follow the setup manifest's kind or default.
+const standIn = field => field?.kind === 'email' ? 'owner@example.com' : typeof field?.default === 'string' && field.default ? field.default : randomBytes(24).toString('hex');
+const links = html => [...html.matchAll(/(?:src|href)=["'](\/[^"'#?\s]+)/g)].map(match => match[1].slice(1)).filter(path => !path.startsWith('/') && /\.[A-Za-z0-9]+$/.test(path));
+
+/** The build served as rer deploy hosts it, with the vars, origin and (stand-in) secrets of its
+ * deploy declaration. `fetch(path, init)` answers for the deployed origin. */
+export async function serveHosted(root, { declaration: declarationPath = 'deploy.json' } = {}) {
+ const build = join(root, 'dist/server'), client = join(root, 'dist/client');
+ let config;
+ try { config = await read(join(build, 'wrangler.json')); }
+ catch { throw new RerError('hosted_output_missing', 'No production build at dist/server/wrangler.json. Run rer build, then rer verify.', 1); }
+ let declaration;
+ try { declaration = await read(join(root, declarationPath)); }
+ catch { throw new RerError('hosted_output_missing', `No readable deploy declaration at ${declarationPath}. A seed whose deploy reads another file names it with the commandAdapter option deployDeclaration.`, 1); }
+ const manifest = await optional(join(root, 'rer-setup.json'));
+ const { Miniflare, convertV4MiniflareOptions = options => options } = await miniflareFor(root);
+ const entry = join(build, config.main);
+ const modules = [entry, ...(await files(build)).map(path => join(build, path)).filter(path => path !== entry && moduleTypes[extname(path)])].map(path => ({ type: moduleTypes[extname(path)], path }));
+ const identity = { sourceSha: createHash('sha1').update(randomBytes(16)).digest('hex'), fingerprint: createHash('sha256').update(randomBytes(16)).digest('hex'), versionId: crypto.randomUUID() };
+ const secrets = Object.fromEntries((declaration.secrets ?? []).map(item => [item.binding, standIn(manifest.fields?.find(field => field.name === item.binding))]));
+ const mf = new Miniflare(convertV4MiniflareOptions({ host: '127.0.0.1', port: 0, cf: false, workers: [{ name: 'ingress', modules: true, script: ingress, serviceBindings: { APP: 'app' } }, {
+  name: 'app', modules, modulesRoot: build, compatibilityDate: config.compatibility_date, compatibilityFlags: config.compatibility_flags,
+  bindings: { ...config.vars, ...declaration.vars, ...secrets, ...(declaration.originVar ? { [declaration.originVar]: ORIGIN } : {}),
+   RER_DEPLOY_SOURCE: identity.sourceSha, RER_DEPLOY_FINGERPRINT: identity.fingerprint, RER_VERSION: { id: identity.versionId, tag: '', timestamp: new Date().toISOString() } },
+  d1Databases: Object.fromEntries((config.d1_databases ?? []).map(item => [item.binding, item.database_id ?? item.database_name])),
+  r2Buckets: Object.fromEntries((config.r2_buckets ?? []).map(item => [item.binding, item.bucket_name])),
+  kvNamespaces: Object.fromEntries((config.kv_namespaces ?? []).map(item => [item.binding, item.id ?? item.binding])),
+  queueProducers: Object.fromEntries((config.queues?.producers ?? []).map(item => [item.binding, item.queue])),
+  durableObjects: Object.fromEntries((config.durable_objects?.bindings ?? []).filter(item => !item.script_name).map(item => [item.name, { className: item.class_name, useSQLite: true }])),
+  ...(config.assets ? { assets: { directory: client, binding: config.assets.binding ?? 'ASSETS', routerConfig: { has_user_worker: true, invoke_user_worker_ahead_of_assets: RUN_WORKER_FIRST } } } : {}),
+ }] }));
+ let loopback;
+ try {
+  loopback = await mf.ready;
+  const { unstable_splitSqlQuery: split } = createRequire(join(root, 'package.json'))('wrangler');
+  for (const item of config.d1_databases ?? []) {
+   const directory = resolve(build, item.migrations_dir ?? 'migrations'), plan = [];
+   for (const name of (await readdir(directory).catch(() => [])).filter(name => name.endsWith('.sql')).sort()) {
+    const sql = await readFile(join(directory, name), 'utf8');
+    plan.push({ name, sql, sha256: createHash('sha256').update(sql).digest('hex'), statements: split(sql) });
+   }
+   await migrate(await mf.getD1Database(item.binding, 'app'), plan);
+  }
+ } catch (error) { await mf.dispose(); throw error; }
+ return { client, identity, origin: ORIGIN, close: () => mf.dispose(),
+  fetch: (path, { headers, ...init } = {}) => fetch(loopback, { ...init, redirect: 'manual', headers: { ...headers, 'x-rer-original-url': `${ORIGIN}/${path}` } }) };
+}
+
+export async function checkHostedOutput(root, options) {
+ const hosted = await serveHosted(root, options), { client, identity } = hosted, failures = [];
+ try {
+  const request = async path => { const response = await hosted.fetch(path); return { status: response.status, type: response.headers.get('content-type') ?? '', body: await response.text() }; };
+  const built = await files(client).catch(() => []);
+  const documents = await Promise.all(built.filter(path => extname(path) === '.html').map(path => readFile(join(client, path), 'utf8')));
+  const home = await request('');
+  if (home.status === 200 && home.type.includes('text/html')) documents.push(home.body);
+  const paths = [...new Set([...publicAssetPaths(built).map(path => path.split('/').map(encodeURIComponent).join('/')), ...documents.flatMap(links)])];
+  for (let i = 0; i < paths.length; i += 8) await Promise.all(paths.slice(i, i + 8).map(async path => {
+   const answer = await request(path);
+   if (answer.status !== 200) failures.push(`${answer.status} /${path}`);
+  }));
+  failures.sort();
+  const health = await request('health');
+  let body; try { body = JSON.parse(health.body); } catch {}
+  const deployment = body?.deployment ?? {};
+  const wrong = health.status !== 200 ? [`HTTP ${health.status}`] : [...(body?.ok === true ? [] : ['ok']), ...['sourceSha', 'fingerprint', 'versionId'].filter(key => deployment[key] !== identity[key]).map(key => `deployment.${key}`)];
+  if (wrong.length) failures.push(`/health lacks the deploy identity (${wrong.join(', ')}); it must answer {ok:true, deployment:{sourceSha, fingerprint, versionId}} from RER_DEPLOY_SOURCE, RER_DEPLOY_FINGERPRINT and RER_VERSION.id`);
+  if (failures.length) throw new RerError('hosted_output_failed', `The production build would break when hosted: rer deploy runs the Worker before static assets (run_worker_first), and served this way:\n  ${failures.join('\n  ')}\nServe built files with staticAssetResponse and answer /health with deploymentHealth (SEED-COMMAND-CONTRACT.md, Hosted assets and deploy identity).`, 1, { failures });
+  return { assets: paths.length, health: 'identity' };
+ } finally { await hosted.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+ try { console.log(JSON.stringify(await checkHostedOutput(resolve(process.argv[2] ?? '.'), { declaration: process.argv[3] }))); }
+ catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/cli/independent.mjs

@@ -0,0 +1,29 @@
+import { isAbsolute } from 'node:path';
+import { inspectRequiredLoops } from '../operations/project-operations.mjs';
+import { contained } from './project.mjs';
+import { missing, refuse, RerError } from './errors.mjs';
+
+export async function executeDeclared(project, options, store, signal) {
+ if (project.descriptor.version !== 2) throw refuse('Execution requires explicit OPERATIONS v2 argv; version 1 remains inspection-only.');
+ const command = project.descriptor.commands[options.verb];
+ if (!command) throw refuse('No command declared for this verb. Add a real OPERATIONS v2 argv or use the project commands.');
+ for (const input of command.inputs) await contained(project.root, input);
+ const absent = project.descriptor.requiredEnvironment.filter(name => typeof process.env[name] !== 'string' || !process.env[name].trim());
+ const loops = inspectRequiredLoops(project.descriptor, process.env);
+ if (absent.length || loops.some(loop => !['ready', 'optional-disabled'].includes(loop.status))) throw missing(`Required declared inputs or loops are missing. See ${project.descriptor.documentation?.document ?? 'the project operating documentation'}.`);
+ const [program, ...argv] = command.argv;
+ if (!isAbsolute(program) && (program.includes('/') || program.includes('\\'))) await contained(project.root, program);
+ if(['install','setup','build','verify','deploy','release','export','import'].includes(options.verb)) {
+  try{await store.run('Running declared project command',program,[...argv,...options.forwarded],{cwd:project.root,signal});return {childExitCode:0,signal:null};}
+  catch(error){const code=error.signal?({SIGINT:130,SIGTERM:143}[error.signal]??1):error.childExitCode??1;throw new RerError('child_failed','The declared command failed.',code,{childExitCode:error.childExitCode,signal:error.signal});}
+ }
+ const child = store.spawn('Running declared project command', program, [...argv, ...options.forwarded], { cwd: project.root, signal });
+ const completion = new Promise(resolve => { child.once('error', () => resolve({ error: true })); child.once('close', (code, terminationSignal) => resolve({ code, signal: terminationSignal })); });
+ await new Promise(resolve => { child.once('error', resolve); child.once('exit', resolve); });
+ await store.stop(child);
+ const result = await completion;
+ if (result.error) throw missing('The declared command executable is unavailable. See the project runtime requirements.');
+ const exitCode = result.signal ? ({ SIGINT: 130, SIGTERM: 143 }[result.signal] ?? 1) : result.code;
+ if (exitCode !== 0) throw new RerError('child_failed', 'The declared command failed.', exitCode, { childExitCode: result.code, signal: result.signal });
+ return { childExitCode: result.code, signal: result.signal };
+}

package/cli/inspect.mjs

@@ -0,0 +1,174 @@
+import { dependencyDoctor } from './dependency-doctor.mjs';
+import { inventory } from './export.mjs';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { aliases, pins, requiredHooks, serverDefaults, verbs, releaseFlags } from './contract.mjs';
+import { runningVersion } from './version.mjs';
+import { contained, readPackage } from './project.mjs';
+import { shared } from './shared.mjs';
+import { missing } from './errors.mjs';
+import { projectNodePin } from './node-runtime-discovery.mjs';
+import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
+import { localAiDiagnostics } from './ai-local.mjs';
+import { authCopyClauses } from './auth-copy.mjs';
+import { cacheWarnings } from './cache-doctor.mjs';
+import { deployedMain } from './deploy-config.mjs';
+
+// cliVersion: the rer version of the code answering (absent for a vendored copy
+// too old to record one). defaults: what a server start applies when the person
+// sets nothing.
+export async function describe(project) {
+ const pkg = await readPackage(project.root), cliVersion = runningVersion(), versioned = cliVersion ? { cliVersion } : {};
+ const defaults = { serverLimit: serverDefaults.serverLimit, idleSeconds: serverDefaults.idleSeconds };
+ if (project.profile === 'independent') return {
+  contractVersion: 1, ...versioned, profile: 'independent', defaults, pins: {}, aliases: {},
+  verbs: Object.fromEntries(Object.entries(project.descriptor.commands).map(([verb, declaration]) => [verb, { flags: ['--help', '--cwd', '--non-interactive', '--json', ...(['install','setup','build','verify','dev','preview','deploy','export','import'].includes(verb)?['--no-queue']:[]), '--'], effects: declaration.effects }])),
+ };
+ const capabilities = project.adapter?.verbs ?? {};
+ return { contractVersion: 1, ...versioned, profile: 'first-party', defaults, pins: { node: pkg.engines?.node, pnpm: pkg.packageManager?.replace(/^pnpm@/, '') },
+  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects: verbs[verb]?.effects ?? 'Existing Base release producer.' }])),
+  aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === `node scripts/rer.mjs${verb ? ' ' + verb : ''}`)),
+  local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
+ };
+}
+
+// prepared: local setup has completed (the private settings file holds the
+// owner, the origin and every required generated or supplied secret).
+// ownerSaved: that file already holds the owner email, which a later setup keeps.
+async function localState(project) {
+ const settings = project.adapter?.hooks?.secrets ?? {}, unprepared = { prepared: false, ownerSaved: false };
+ let values;
+ try {
+  const text = await readFile(await contained(project.root, settings.file ?? '.dev.vars'), 'utf8');
+  values = settings.format === 'json' ? JSON.parse(text) : (await shared('local/environment.mjs')).localVariables(text);
+ } catch { return unprepared; }
+ if (!values || typeof values !== 'object' || Array.isArray(values)) return unprepared;
+ if (project.adapter?.setup && !project.setupManifest) {
+  const { loadInstallerSeed } = await shared('setup-manifest.mjs');
+  try { project.setupManifest = (await loadInstallerSeed(project.root, project.adapter)).manifest; } catch { return unprepared; }
+ }
+ return { prepared: requiredLocalSettings(project, values).length === 0, ownerSaved: Boolean(values[localSettingKeys(project).email]) };
+}
+
+export async function check(project, explicitProfile) {
+ const clauses = [], add = (id, ok, message) => clauses.push({ id, ok: Boolean(ok), ...(!ok ? { message } : {}) });
+ for (const command of project.commands) add('SC-10.inputs.' + command.name, command.available, `Restore the declared inputs for ${command.name}.`);
+ for (const loop of project.descriptor.loops ?? []) add('SC-10.loop.' + loop.id, !loop.required || loop.enabled, `Enable the required ${loop.id} loop or correct its declaration.`);
+ if (project.profile === 'first-party' || explicitProfile === 'first-party') {
+  const adapter = project.adapter, pkg = await readPackage(project.root), marker = project.descriptor.seedContract;
+  add('SC-09.profile', marker?.version === 1 && marker?.profile === 'first-party', 'Restore OPERATIONS v2 seedContract version 1, profile first-party and the adapter pointer.');
+  add('SC-01.adapter', adapter?.version === 1, 'Export commandAdapter version 1 from scripts/installer/local.mjs.');
+  for (const hook of requiredHooks) add('SC-01.hook.' + hook, adapter?.[hook] ?? adapter?.hooks?.[hook], `Missing ${hook} hook/inventory; adopt the shared command adapter with a real ${hook} target.`);
+  for (const [verb, definition] of Object.entries({ ...verbs, release: { flags: releaseFlags } })) {
+   const declaration = project.descriptor.commands[verb];
+   add('SC-01.verb.' + verb, declaration && adapter?.verbs?.[verb], `Missing ${verb}; declare it in OPERATIONS and expose its shared implementation.`);
+   for (const flag of definition.flags) add('SC-01.flag.' + verb + '.' + flag.slice(2), adapter?.verbs?.[verb]?.flags?.includes(flag), `Missing ${verb} ${flag}; restore the shared implementation supporting this flag.`);
+   add('SC-02.target.' + verb, declaration?.argv?.join('\0') === ['node', 'scripts/rer.mjs', verb].join('\0'), `Declare ${verb} argv as node scripts/rer.mjs ${verb}.`);
+  }
+  for (const [alias, verb] of Object.entries(aliases)) add('SC-02.alias.' + alias, pkg.scripts?.[alias] === `node scripts/rer.mjs${verb ? ' ' + verb : ''}`, `Set package script ${alias} to node scripts/rer.mjs${verb ? ' ' + verb : ''}.`);
+  add('SC-02.install-lifecycle', !pkg.scripts?.install, 'Remove the install lifecycle alias; use deps or frozen pnpm install.');
+  let nodeFile; try { nodeFile = (await readFile(resolve(project.root, '.node-version'), 'utf8')).trim(); } catch {}
+  add('SC-02.node-file', nodeFile === pins.node, `Set .node-version to ${pins.node}.`);
+  add('SC-02.node-engine', pkg.engines?.node === pins.node, `Pin package.json engines.node to ${pins.node}.`);
+  add('SC-02.pnpm', pkg.packageManager === `pnpm@${pins.pnpm}`, `Pin packageManager to pnpm@${pins.pnpm}.`);
+  for (const path of ['scripts/rer.mjs', 'scripts/base-cli/inventory.json', 'scripts/base-onboarding/adapter.mjs']) {
+   let exists = false; try { await contained(project.root, path); exists = true; } catch {}
+   add('SC-01.portable.' + path, exists, `Restore portable source ${path} through the documented export tool.`);
+  }
+  try {
+   const record = JSON.parse(await readFile(resolve(project.root, 'scripts/base-cli/inventory.json'), 'utf8'));
+   for(const name of ['production-runtime.mjs','production-options.mjs','production-plan.mjs','production-modules.mjs','project-vite.mjs','operator-install.mjs','operator-prerequisites.mjs','command-recovery.mjs','queue.mjs','queued-entry.mjs','commands.mjs','process-scope.mjs'])
+    add('SC-12.onboarding.'+name,record.onboardingFiles?.[name],`Restore the required onboarding/queue source ${name}.`);
+   for(const [path,source]of Object.entries(record.onboardingFiles??{})){
+    let exact=false;try{const local=await contained(project.root,'scripts/base-onboarding/'+path);exact=createHash('sha256').update(await readFile(local)).digest('hex')===source.sha256;}catch{}
+    add('SC-12.onboarding-inventory.'+path,exact,`Restore stale or missing shared execution source ${path}.`);
+   }
+   const actual=await inventory(resolve(project.root,'scripts/base-cli'));
+   add('SC-09.inventory-complete',JSON.stringify(actual)===JSON.stringify(Object.keys(record.files).sort()),'Regenerate the complete portable source inventory.');
+   for(const path of ['cli/settings.mjs','cli/bounded.mjs','cli/server-resources.mjs','cli/managed-server.mjs','cli/server-registry.mjs','cli/server-activity.mjs','cli/server-proxy.mjs','cli/preview-cache.mjs','modules/job-queue/cli.mjs','modules/job-queue/config.mjs','modules/job-queue/resources.mjs','modules/job-queue/storage.mjs','modules/job-queue/identity.mjs','modules/job-queue/processes.mjs','modules/job-queue/index.mjs','modules/job-queue/command.mjs','modules/job-queue/supervisor.mjs','modules/job-queue/membership.mjs','modules/job-queue/policy.mjs'])
+    add(path.startsWith('cli/')?'SC-11.source.'+path:'SC-12.source.'+path,record.files[path],`Restore required managed lifecycle/queue source ${path}.`);
+   for (const [path, source] of Object.entries(record.files)) {
+    let exact = false;
+    try { const local = await contained(project.root, 'scripts/base-cli/' + path); exact = createHash('sha256').update(await readFile(local)).digest('hex') === source.sha256; } catch {}
+    add('SC-01.inventory.' + path, exact, `Restore stale or missing portable CLI source ${path} with the source export tool.`);
+   }
+  } catch { add('SC-01.inventory', false, 'Restore the deterministic portable CLI source inventory.'); }
+  add('SC-08.portability', typeof adapter?.portability?.export === 'function' && typeof adapter?.portability?.import === 'function', 'Adopt the reviewed mainline complete local portability API; archive support remains unavailable until then.');
+  if (adapter?.devIdentity) for (const [id, ok, message] of await devIdentityClauses(project.root, adapter)) add(id, ok, message);
+  for (const [id, ok, message] of await authCopyClauses(project.root)) add(id, ok, message);
+ }
+ for(const issue of await localAiDiagnostics(project,process.env))add('AI.'+issue.feature,false,issue.code+': '+issue.message);
+ return { clauses, ok: clauses.every(clause => clause.ok) };
+}
+
+export async function tools(root, store, signal) {
+ const node = await projectNodePin(root);
+ if (node && process.versions.node !== node) throw missing(`Node ${node} is required. Run it with rer, with automatic project runtime selection enabled.`);
+ const version = await probePnpm(root, store, signal);
+ if (version !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. Install/select the documented pin; rer never changes global tools.`);
+}
+
+export async function doctor(project, store, signal) {
+ const { inspectOperations } = await import('../operations/operations.mjs');
+ const diagnostic = await inspectOperations(project.root);
+ const { localVariables } = await shared('local/environment.mjs');
+ let values = {}, pnpm, stateValid = true;
+ if (project.profile === 'first-party') {
+  const { selectLocalState } = await shared('local/state.mjs');
+  try { await selectLocalState(project.root, project.adapter.state); } catch { stateValid = false; }
+ }
+ if (project.profile === 'first-party') {
+  try {
+   const settings = project.adapter?.hooks?.secrets ?? {};
+   const file = await contained(project.root, settings.file ?? '.dev.vars');
+   const text = await readFile(file, 'utf8');
+   const parsed = settings.format === 'json' ? JSON.parse(text) : localVariables(text);
+   if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) values = parsed;
+  } catch {}
+  try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; }
+ }
+ const aiIssues = await localAiDiagnostics(project,process.env);
+ const dependencies=project.profile==='first-party'?await dependencyDoctor(project.root):[];
+ const expectedNode = await projectNodePin(project.root);
+ const keys = localSettingKeys(project);
+ const inputs = project.profile === 'first-party' ? requiredLocalSettings(project, values) : [];
+ const warnings = project.profile === 'first-party' ? await cacheWarnings(project.root) : [];
+ return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (process.versions.node === expectedNode && pnpm === pins.pnpm)),
+  node: { actual: process.versions.node, expected: expectedNode },
+  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: pins.pnpm } : undefined,
+  ai: { issues: aiIssues },
+  missingInputs: [...new Set([...diagnostic.missingEnvironment, ...inputs])],
+  sources: project.descriptor.environmentSources ?? {}, state: { path: project.adapter?.state, safe: stateValid }, scope: 'local-inputs-only' };
+}
+
+// Diagnostics and execution use the same identity-checked process custody.
+// Exit starts cleanup even if a descendant still holds the output pipes.
+async function probePnpm(root, store, signal) {
+ const probeSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean));
+ const child = store.spawn('Checking pinned pnpm', 'pnpm', ['--version'], { cwd: root, signal: probeSignal });
+ let version = '';
+ child.stdout.on('data', chunk => { version = (version + chunk).slice(-1024); });
+ const code = await new Promise(resolve => { child.once('error', () => resolve(null)); child.once('exit', code => resolve(code)); });
+ await store.stop(child);
+ if (probeSignal.aborted || code !== 0) throw missing('The pinned pnpm version probe failed. Select the documented tool.');
+ return version.trim();
+}
+
+// SC-05: a seed declaring devIdentity loads the dev layer only from a local-only
+// entry that its dev configuration names, never from the deployed main, lets
+// rer build scan its output, and keeps one end-to-end email-link test.
+async function devIdentityClauses(root, adapter) {
+ const declaration = adapter.devIdentity;
+ const text = async path => { try { return await readFile(await contained(root, path), 'utf8'); } catch { return null; } };
+ const entry = typeof declaration.entry === 'string' ? declaration.entry.replace(/^\.\//, '') : '';
+ const main = await deployedMain(root, adapter);
+ const production = main ? await text(main) : null;
+ const configs = (await Promise.all(['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs', 'wrangler.local.jsonc', 'wrangler.local.json', 'wrangler.local.toml'].map(text))).filter(Boolean);
+ const test = typeof declaration.emailLinkTest === 'string' ? await text(declaration.emailLinkTest) : null;
+ return [
+  ['SC-05.dev-identity.entry', entry && await text(entry) !== null && entry !== main && configs.some(config => config.includes(entry)), 'Declare devIdentity.entry as an existing local-only Worker entry that the local Vite or wrangler configuration loads and that is not the deployed main.'],
+  ['SC-05.dev-identity.exclusion', production !== null && !/operator-auth\/dev\//.test(production) && !production.includes(entry.replace(/\.[a-z]+$/, '')) && Array.isArray(declaration.output) && declaration.output.length > 0, 'Keep the deployed main free of the dev layer and its local entry, and declare devIdentity.output so rer build refuses output containing the dev layer.'],
+  ['SC-05.dev-identity.email-link-test', test !== null && /outbox/i.test(test), 'Keep one end-to-end email-link test through the outbox and declare it as devIdentity.emailLinkTest.'],
+ ];
+}