optbrew 0.1.2 → 0.2.0

package/skills/optbrew/scripts/core/transport.mjs

@@ -0,0 +1,157 @@
+import http from 'node:http';
+import https from 'node:https';
+import tls from 'node:tls';
+import { isIP } from 'node:net';
+import { performance } from 'node:perf_hooks';
+import { unbracket, urlTarget } from './scope.mjs';
+
+const DNS_FAILURES = new Set(['ENOTFOUND', 'EAI_AGAIN']);
+
+/** Send one request (`body`, when there is one, is its whole payload) and read the response into `{ status, headers, rawHeaders, body }`; both transports share this, byte limit included. */
+function exchange({ send, timeoutMs, maxBytes, body = null }) {
+  return new Promise((resolve, reject) => {
+    // Reject first: once a response has started, destroying the request ends it quietly and would resolve a truncated body.
+    const overLimit = () => { reject(new Error('response byte limit exceeded')); req.destroy(); };
+    const req = send(res => {
+      const chunks = []; let size = 0;
+      if (Number(res.headers['content-length']) > maxBytes) { overLimit(); return; }
+      res.on('data', chunk => {
+        size += chunk.length;
+        if (size > maxBytes) { overLimit(); return; }
+        chunks.push(chunk);
+      });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, rawHeaders: res.rawHeaders, body: Buffer.concat(chunks) }));
+      res.on('error', reject);
+    });
+    req.setTimeout(timeoutMs, () => req.destroy(new Error('request timeout')));
+    req.on('error', reject);
+    req.end(body ?? undefined);
+  });
+}
+
+/** Request headers; a body brings its Content-Length, and a caller's own Content-Length (any case) is dropped so it can never disagree with the bytes sent. */
+const requestHeaders = (headers, body = null) => {
+  const merged = Object.fromEntries(Object.entries({ 'User-Agent': 'optbrew/0.1 (bounded public audit)', Accept: '*/*', 'Accept-Encoding': 'identity', ...headers })
+    .filter(([name]) => name.toLowerCase() !== 'content-length'));
+  return body === null ? merged : { ...merged, 'Content-Length': Buffer.byteLength(body) };
+};
+
+/** Node's lookup callback pins the already-vetted address while TLS still verifies the URL hostname. */
+export function directTransport({ url, address, timeoutMs, maxBytes, headers = {}, signal, method = 'GET', body = null }) {
+  const client = url.protocol === 'https:' ? https : http;
+  const { host: hostname } = urlTarget(url);
+  return exchange({ timeoutMs, maxBytes, body, send: onResponse => client.request(url, {
+    method, agent: false, signal, headers: requestHeaders(headers, body),
+    lookup: (_hostname, options, callback) => options.all ?
+      callback(null, [{ address: address.address, family: address.family }]) : callback(null, address.address, address.family),
+    ...(url.protocol === 'https:' ? { rejectUnauthorized: true,
+      ...(!isIP(hostname) ? { servername: hostname } : {}) } : {}),
+  }, onResponse) });
+}
+
+/** Error that names the proxy by host and port only, so no credential can reach a message. */
+function proxyError(proxy, what, code) {
+  const error = new Error(`${what} via ${proxy.host}:${proxy.port}`);
+  error.code = code;
+  return error;
+}
+
+/** Open a CONNECT tunnel to the target; resolves with the raw tunnel socket. */
+function openTunnel(proxy, url, { timeoutMs, signal }) {
+  const { port } = urlTarget(url);
+  const authority = `${url.hostname}:${port}`;
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: proxy.host, port: proxy.port, method: 'CONNECT', path: authority, agent: false, signal,
+      headers: { Host: authority, ...(proxy.authorization ? { 'Proxy-Authorization': proxy.authorization } : {}) } });
+    req.setTimeout(timeoutMs, () => { reject(proxyError(proxy, 'proxy CONNECT timed out', 'proxy_timeout')); req.destroy(); });
+    req.on('connect', (res, socket, head) => {
+      if (res.statusCode < 200 || res.statusCode > 299) {
+        socket.destroy();
+        const hint = port === 443 ? '' : ` (a proxy may allow CONNECT to port 443 only; the target port is ${port})`;
+        reject(proxyError(proxy, `proxy CONNECT refused with status ${res.statusCode}${hint}`, 'proxy_connect_refused'));
+        return;
+      }
+      if (head.length) socket.unshift(head);
+      resolve(socket);
+    });
+    req.on('error', error => reject(proxyError(proxy, `proxy connection failed (${error.code ?? error.message})`, 'proxy_unreachable')));
+    req.end();
+  });
+}
+
+/**
+ * Transport that sends every request, plain http included, through a CONNECT tunnel; the proxy resolves the target name.
+ * HTTPS targets get TLS over the tunnel: the certificate is checked against the target host (`host`), and SNI
+ * (`servername`, names only) is set because Node leaves it off when a socket is supplied.
+ * The CONNECT and the request share one deadline. The returned function is tagged for `fetchScoped`, which refuses
+ * proxy address vetting on any other transport.
+ */
+export function proxyTransport(proxy, { connectTls = tls.connect } = {}) {
+  const transport = async ({ url, timeoutMs, maxBytes, headers = {}, signal, method = 'GET', body = null }) => {
+    const deadline = performance.now() + timeoutMs;
+    const tunnel = await openTunnel(proxy, url, { timeoutMs, signal });
+    let stream = tunnel;
+    try {
+      const { host, port } = urlTarget(url);
+      if (url.protocol === 'https:')
+        stream = connectTls({ socket: tunnel, host, rejectUnauthorized: true, ...(!isIP(host) ? { servername: host } : {}) });
+      const remainingMs = Math.ceil(deadline - performance.now());
+      if (remainingMs <= 0) throw proxyError(proxy, 'proxy tunnel timed out', 'proxy_timeout');
+      // No `agent` option: `agent: false` makes Node build an Agent that ignores createConnection and dials the name itself.
+      return await exchange({ timeoutMs: remainingMs, maxBytes, body, send: onResponse => http.request({
+        host, port, path: `${url.pathname}${url.search}`, method, signal,
+        createConnection: () => stream, headers: { Host: url.host, ...requestHeaders(headers, body) } }, onResponse) });
+    } finally { stream.destroy(); tunnel.destroy(); }
+  };
+  return Object.assign(transport, { addressVetting: 'proxy' });
+}
+
+/** `HTTPS_PROXY` as `{ host, port, authorization }`. Only plain-HTTP proxies work (a missing scheme counts as plain HTTP); userinfo becomes a Basic header and is not kept. */
+export function parseProxy(env) {
+  const value = (env.HTTPS_PROXY || env.https_proxy || '').trim();
+  const parts = /^(?:([a-z][a-z\d+.-]*):\/\/)?(.*)$/i.exec(value);
+  const scheme = (parts[1] ?? 'http').toLowerCase();
+  if (!value || scheme !== 'http') return null;
+  let url;
+  try { url = new URL(`${scheme}://${parts[2]}`); } catch { return null; }
+  if (!url.hostname) return null;
+  const decode = text => { try { return decodeURIComponent(text); } catch { return text; } };
+  const authorization = url.username || url.password ?
+    `Basic ${Buffer.from(`${decode(url.username)}:${decode(url.password)}`).toString('base64')}` : null;
+  const proxy = { host: unbracket(url.hostname), port: Number(url.port || 80) };
+  // Not enumerable: JSON.stringify, spread and inspect all leave the credential out; only a direct read sees it.
+  return Object.defineProperty(proxy, 'authorization', { value: authorization, enumerable: false });
+}
+
+/** NO_PROXY entries: comma-separated, case-insensitive, `*` matches all, an entry matches the host or any subdomain; ports are ignored. */
+function bypassesProxy(env, host) {
+  const entries = (env.NO_PROXY || env.no_proxy || '').split(',').map(entry => entry.trim().toLowerCase()).filter(Boolean);
+  const name = unbracket(host.toLowerCase());
+  return entries.some(entry => {
+    if (entry === '*') return true;
+    const bare = entry.startsWith('[') ? entry.slice(1, entry.indexOf(']')) :
+      entry.split(':').length === 2 ? entry.split(':')[0] : entry;
+    const domain = bare.replace(/^\*?\./, '');
+    return name === domain || name.endsWith(`.${domain}`);
+  });
+}
+
+function dnsError(host, code, reason) {
+  const error = new Error(`DNS lookup for ${host} failed (${code}) and ${reason}`);
+  error.code = 'dns_unresolvable';
+  error.dns_code = code;
+  return error;
+}
+
+/** Direct transport when DNS works; the HTTPS proxy when DNS fails and one is set (NO_PROXY respected); a classified error otherwise. */
+export async function selectTransport({ env, resolve, probeHost }) {
+  try {
+    await resolve(probeHost);
+    return { transport: directTransport, resolve, address_vetting: 'direct', proxy: null };
+  } catch (error) {
+    if (!DNS_FAILURES.has(error?.code)) throw error;
+    const proxy = bypassesProxy(env, probeHost) ? null : parseProxy(env);
+    if (!proxy) throw dnsError(probeHost, error.code, 'no usable HTTPS_PROXY is set');
+    return { transport: proxyTransport(proxy), resolve: async () => [], address_vetting: 'proxy', proxy };
+  }
+}

package/skills/optbrew/scripts/core/weights.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { publicOnlyFamily } from './config.mjs';
 import { ContractError, validateEntity } from './contracts.mjs';
 import { freezeProtocol } from './protocol.mjs';
 
@@ -8,7 +9,7 @@ const profiles = JSON.parse(readFileSync(new URL('../../references/profiles.json
 const tolerance = 1e-9;
 
 function candidateUnits(definition, plan, protocol) {
-  const publicOnly = ['index-policy', 'search-crawl-policy', 'discovery'].includes(definition.family_id);
+  const publicOnly = publicOnlyFamily(definition.family_id);
   const pageTypes = protocol.page_types.map(type => ({ ...type,
     urls: type.urls.filter(url => (!publicOnly || url.public_indexing) &&
       (!plan.urls || plan.urls.includes(url.normalized))) })).filter(type => type.urls.length);

package/skills/optbrew/scripts/key.mjs

@@ -0,0 +1,90 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { googleKeyStatus, keyHome, removeGoogleKey, saveGoogleKey } from './core/keys.mjs';
+
+const USAGE = 'usage: key.mjs <set google | status | remove google>';
+const CTRL_C = '\u0003';
+const CTRL_D = '\u0004';
+const DELETE = '\u007f';
+const BACKSPACE = '\b';
+
+/**
+ * Read a secret from a terminal without echoing it: raw mode, characters are collected and never written back.
+ * Enter submits; Ctrl-C, Ctrl-D on empty input, end of input and stream errors end the read without a value.
+ */
+function readHidden(stdin, stdout) {
+  return new Promise((resolve, reject) => {
+    let value = '';
+    const finish = settle => {
+      stdin.off('data', onData); stdin.off('end', cancel); stdin.off('error', fail);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdout.write('\n');
+      settle();
+    };
+    const cancel = () => finish(() => reject(new Error('cancelled')));
+    const fail = error => finish(() => reject(error));
+    const onData = chunk => {
+      for (const char of String(chunk)) {
+        if (char === '\r' || char === '\n') return finish(() => resolve(value));
+        if (char === CTRL_C || (char === CTRL_D && !value)) return cancel();
+        if (char === DELETE || char === BACKSPACE) value = value.slice(0, -1);
+        else if (char >= ' ') value += char;
+      }
+    };
+    stdout.write('Google API key (input is hidden): ');
+    stdin.setRawMode(true);
+    stdin.setEncoding('utf8');
+    stdin.on('data', onData);
+    stdin.on('end', cancel);
+    stdin.on('error', fail);
+    stdin.resume();
+  });
+}
+
+/** Read one line from a pipe or file. */
+function readLine(stdin) {
+  return new Promise((resolve, reject) => {
+    let buffer = '';
+    const finish = () => {
+      stdin.off('data', onData); stdin.off('end', finish); stdin.off('error', reject);
+      stdin.pause();
+      resolve(buffer.split(/\r?\n/)[0]);
+    };
+    const onData = chunk => { buffer += chunk; if (buffer.includes('\n')) finish(); };
+    stdin.setEncoding('utf8');
+    stdin.on('data', onData);
+    stdin.on('end', finish);
+    stdin.on('error', reject);
+    stdin.resume();
+  });
+}
+
+/** Return a process code: 0 success, 2 usage error, 1 failure. Messages never contain the key value. */
+export async function runKeyCommand(argv, { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, env = process.env, home = keyHome(env) } = {}) {
+  const [action, provider, ...extra] = argv;
+  const valid = extra.length === 0 && ((['set', 'remove'].includes(action) && provider === 'google') || (action === 'status' && provider === undefined));
+  if (!valid) { stderr.write(`${USAGE}\n`); return 2; }
+  try {
+    if (action === 'status') {
+      stdout.write(`${JSON.stringify(googleKeyStatus({ env, home }))}\n`);
+    } else if (action === 'remove') {
+      stdout.write(await removeGoogleKey({ home }) ? 'google key removed\n' : 'no google key in the key file; nothing to remove\n');
+      if (googleKeyStatus({ env, home }).google.present) stderr.write('OPTBREW_GOOGLE_API_KEY is still set in the environment\n');
+    } else {
+      const key = (stdin.isTTY ? await readHidden(stdin, stdout) : await readLine(stdin)).trim();
+      if (!key) { stderr.write('no key entered; nothing saved\n'); return 2; }
+      await saveGoogleKey({ home, key });
+      stdout.write('google key saved\n');
+    }
+    return 0;
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  runKeyCommand(process.argv.slice(2)).then(code => { process.exitCode = code; });
+}

package/skills/optbrew/scripts/preflight.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { lookup } from 'node:dns/promises';
+import { realpathSync } from 'node:fs';
+import { isIP } from 'node:net';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchScoped, links } from './core/collector.mjs';
+import { findChrome as realFindChrome } from './core/chrome.mjs';
+import { limits } from './core/config.mjs';
+import { openStore } from './core/evidence-store.mjs';
+import { pageFacts } from './core/facts.mjs';
+import { decodeEntities } from './core/html.mjs';
+import { readGoogleKey as realReadGoogleKey } from './core/keys.mjs';
+import { probeEnvironment, runbookHarnesses } from './core/probe.mjs';
+import { startRunbooks } from './core/runbooks.mjs';
+import { assertUrlInScope, unbracket } from './core/scope.mjs';
+import { selectTransport as realSelectTransport } from './core/transport.mjs';
+
+const USAGE = 'usage: node skills/optbrew/scripts/preflight.mjs --url <URL> --out <dir> [--source-tools a,b] [--skill-root <path>] [--level beginner|brief]';
+/** The guidance level is asked in the same start questions this file feeds, so a blocking runbook is shown at the beginner level. */
+const START_LEVEL = 'beginner';
+const SITEMAP_PATH = '/sitemap.xml';
+const defaultSkillRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+const locCount = text => (text.match(/<loc>/gi) ?? []).length;
+const locs = text => [...text.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/gi)].map(match => decodeEntities(match[1]));
+const inner = (html, pattern) => { const found = pattern.exec(html)?.[1]; return found === undefined ? null : decodeEntities(found.replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim() || null; };
+
+/** The origins of the page's own site: itself, its apex/www twin and its http/https twin. A named port or an IP literal has no twin. */
+function sameSiteOrigins(start) {
+  if (start.port || isIP(unbracket(start.hostname))) return [start.origin];
+  const twin = start.hostname.startsWith('www.') ? start.hostname.slice(4) : `www.${start.hostname}`;
+  return ['http:', 'https:'].flatMap(protocol => [start.hostname, twin].map(host => `${protocol}//${host}`));
+}
+
+/** What an agent needs to propose the question list: where the page is, its title, description and first heading. */
+function questionInput(artifact, html) {
+  const tag = /<meta\b[^>]*\bname\s*=\s*["']description["'][^>]*>/i.exec(html)?.[0];
+  const content = tag && /\bcontent\s*=\s*(?:"([^"]*)"|'([^']*)')/i.exec(tag);
+  return { url: artifact.final_url, title: inner(html, /<title\b[^>]*>([\s\S]*?)<\/title>/i), h1: inner(html, /<h1\b[^>]*>([\s\S]*?)<\/h1>/i),
+    description: content ? decodeEntities(content[1] ?? content[2]).trim() || null : null };
+}
+
+/** Facts the pages state about the business, one candidate per fact type and normalized value; the first page that states it is the source. */
+function factCandidates(pages) {
+  const seen = new Set();
+  const candidates = [];
+  for (const { artifact, html } of pages) {
+    const facts = pageFacts(html);
+    for (const bucket of [facts.visible, facts.linked]) for (const [type, values] of Object.entries(bucket)) for (const [key, value] of values) {
+      if (seen.has(`${type}|${key}`)) continue;
+      seen.add(`${type}|${key}`);
+      candidates.push({ key: type, value, source_url: artifact.final_url });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * The unscored read before the start questions (C17): the probe, the sitemap size, a few pages for question and fact
+ * candidates, and the start runbooks. At most `preflight_pages` requests are sent in all, redirect hops and the sitemap
+ * included. Evidence goes in its own store under `<out>/preflight/evidence`, never in the audit's evidence index, and
+ * nothing here enters the protocol or a score.
+ */
+export async function preflight({ url, out, sourceTools = [], skillRoot = defaultSkillRoot, level = START_LEVEL, env = process.env, home,
+  resolve = host => lookup(host, { all: true, verbatim: true }), selectTransport = realSelectTransport, findChrome = realFindChrome, readGoogleKey = realReadGoogleKey }) {
+  const start = new URL(url);
+  if (!['http:', 'https:'].includes(start.protocol)) throw new Error('url must be http or https');
+  // The first request may end on the same site under another name (apex and www, http and https); once it lands, scope narrows to where it landed.
+  const scopeOf = origins => ({ allowed: origins.map(origin => ({ origin, path_prefix: '/' })) });
+  let scope = scopeOf(sameSiteOrigins(start));
+  const dir = path.join(out, 'preflight');
+  const evidenceDir = path.join(dir, 'evidence');
+  await mkdir(evidenceDir, { recursive: true });
+  const store = openStore(evidenceDir);
+  const budget = limits().preflight_pages;
+  let used = 0;
+  const reserveRequest = () => { if (used >= budget) return false; used++; return true; };
+  let route = null;
+
+  // Where the first request was sent when that was another site (it is recorded for the run, which stops on it).
+  let leftTo = null;
+  const get = async href => {
+    try {
+      const artifact = await fetchScoped(href, { context: { scope }, ...route, reserveRequest });
+      const { ref, sha256 } = await store.write(artifact.capability === 'raw_html' ? 'html' : 'bin', artifact.body);
+      await store.append('raw', { normalized_url: artifact.normalized_url, evidence_ref: ref, content_hash: sha256 });
+      return artifact;
+    } catch (error) {
+      await store.append('failures', { normalized_url: href, error: error.code ?? 'fetch_failed' });
+      if (href === start.href && error.redirect_to) leftTo = error.redirect_to;
+      throw error;
+    }
+  };
+  const tryGet = href => get(href).catch(() => null);
+
+  let first = null;
+  const reach = async selected => {
+    route = { transport: selected.transport, resolve: selected.resolve, addressVetting: selected.address_vetting };
+    first = await get(start.href);
+    scope = scopeOf([new URL(first.final_url).origin]);
+  };
+  const probe = await probeEnvironment({ env, url, selectTransport: input => selectTransport({ ...input, resolve }), findChrome, readGoogleKey, home, sourceTools, reach });
+
+  const pages = [];
+  const addPage = artifact => { if (artifact?.status === 200 && artifact.capability === 'raw_html') pages.push({ artifact, html: artifact.body.toString('utf8') }); };
+  let sitemapPages = null;
+  let sitemapBasis = null;
+  // Where /sitemap.xml ended up: WordPress and Yoast send it on to an index file under another name.
+  let sitemapFinal = null;
+  // The sitemap files the audit will declare: /sitemap.xml, where it ended up, and the child files of an index that were read.
+  const sitemapFiles = new Set();
+  if (first && !probe.block_reason) {
+    addPage(first);
+    const sitemapUrl = new URL(SITEMAP_PATH, new URL(first.final_url).origin).href;
+    const sitemap = await tryGet(sitemapUrl);
+    sitemapFinal = sitemap?.status === 200 ? sitemap.final_url : null;
+    sitemapFiles.add(sitemapUrl);
+    if (sitemapFinal) sitemapFiles.add(sitemapFinal);
+    if (sitemap?.status === 200) {
+      const text = sitemap.body.toString('utf8');
+      if (/<sitemapindex/i.test(text)) {
+        const children = locs(text);
+        let read = 0;
+        let counted = 0;
+        for (const child of children) {
+          if (used >= budget) break;
+          const artifact = await tryGet(child);
+          if (artifact?.status === 200) { read += locCount(artifact.body.toString('utf8')); counted++; sitemapPages = read; sitemapFiles.add(child); }
+        }
+        sitemapBasis = counted === children.length ? 'exact' : 'lower_bound';
+      } else { sitemapPages = locCount(text); sitemapBasis = 'exact'; }
+    }
+    const seen = new Set([start.href, first.normalized_url, sitemapUrl]);
+    for (const href of pages.length ? links(pages[0].html, first.final_url) : []) {
+      if (used >= budget) break;
+      let normalized;
+      try { normalized = assertUrlInScope(href, scope).href; } catch { continue; }
+      if (seen.has(normalized)) continue;
+      seen.add(normalized);
+      addPage(await tryGet(normalized));
+    }
+  }
+
+  const startJson = {
+    // Where the first request landed (after apex/www and http/https redirects): the address the audit should start from.
+    requested_url: start.href,
+    final_url: first?.final_url ?? null,
+    redirected_to: leftTo,
+    sitemap_final_url: sitemapFinal,
+    probe: { ...probe, sitemap_pages: sitemapPages },
+    sitemap_pages: sitemapPages,
+    sitemap_pages_basis: sitemapBasis,
+    sitemap_declared: sitemapFiles.size,
+    question_candidates_input: pages.map(({ artifact, html }) => questionInput(artifact, html)),
+    fact_candidates: factCandidates(pages),
+    start_runbooks: startRunbooks(probe, { level, skillRoot, harnesses: runbookHarnesses(probe.harness) }),
+  };
+  const startPath = path.join(dir, 'start.json');
+  await writeFile(startPath, `${JSON.stringify(startJson, null, 2)}\n`);
+  return { startJson, startPath };
+}
+
+if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    const args = process.argv.slice(2);
+    const option = name => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+    const url = option('--url');
+    const out = option('--out');
+    if (!url || !out || args.length % 2 || args.some((arg, i) => i % 2 === 0 && !['--url', '--out', '--source-tools', '--skill-root', '--level'].includes(arg))) throw new Error(USAGE);
+    const { startJson, startPath } = await preflight({ url, out: path.resolve(out), sourceTools: (option('--source-tools') ?? '').split(',').filter(Boolean),
+      ...(option('--skill-root') ? { skillRoot: option('--skill-root') } : {}), ...(option('--level') ? { level: option('--level') } : {}) });
+    process.stdout.write(`${JSON.stringify({ start_json: startPath, block_reason: startJson.probe.block_reason })}\n`);
+  } catch (error) { process.stderr.write(`preflight failed: ${error.message}\n`); process.exitCode = 2; }
+}

package/skills/optbrew/scripts/run.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { lookup } from 'node:dns/promises';
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findChrome } from './core/chrome.mjs';
+import { validateEntity } from './core/contracts.mjs';
+import { renderChrome } from './core/render.mjs';
+import { prepareOutput, restoreState, runStages, stages } from './core/stages.mjs';
+import { selectTransport } from './core/transport.mjs';
+
+const USAGE = 'usage: node skills/optbrew/scripts/run.mjs --answers <intake-answers.json> --out <dir> [--judgments <judgments.json>]';
+const RESUME_FROM = 'judge';
+const STATUS_DONE = 'done';
+
+/** One render chrome per run, made when the render stage asks for it. Its owner calls `close()` in a `finally`. */
+function chromeHolder(env) {
+  let handle = null;
+  return {
+    open: ({ context, route }) => (handle ??= renderChrome({ context, transport: route, find: () => findChrome({ env }) })),
+    close: () => handle?.close(),
+  };
+}
+
+/** A JSON file as a value; a file that is missing or not JSON is a plain sentence, not a stack trace. */
+async function readJson(file, what) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch { throw new Error(`The ${what} file cannot be read as JSON: ${file}`); }
+}
+
+/** The model's judgments: one bare JSON array, handed to the merge as it is. */
+function judgmentList(value) {
+  if (!Array.isArray(value)) throw new Error('The judgments file must hold one JSON array of judgments.');
+  return value;
+}
+
+/**
+ * One audit: the first call runs context, collect, render, cwv, derive and judge, and stops at the judge queue; the second call
+ * (same `out`, now with `judgmentsPath`) rebuilds its state from the evidence in `out` and runs judge, score and report.
+ * `overrides` is for tests: `env`, `home`, `chrome` (holder), `fetchFn`, `selectTransport`, `stages` (the stage list), `localTargets`
+ * (loopback `{ host, port }` pairs a test may audit; the shipped command refuses a local address, as preflight does).
+ * Everything is written under `out`, and the render chrome is closed whatever happens.
+ */
+export async function run({ answersPath, out, judgmentsPath = null }, overrides = {}) {
+  const outDir = path.resolve(out);
+  const env = overrides.env ?? process.env;
+  const chrome = overrides.chrome ?? chromeHolder(env);
+  try {
+    const answers = await readJson(answersPath, 'answers');
+    try { validateEntity('IntakeAnswers', answers); }
+    catch (error) { throw new Error(`The start answers are not valid (${error.message}).`); }
+    const judgments = judgmentsPath ? judgmentList(await readJson(judgmentsPath, 'judgments')) : null;
+    const deps = { env, home: overrides.home, chrome, fetchFn: overrides.fetchFn, localTargets: overrides.localTargets,
+      selectTransport: overrides.selectTransport ?? (input => selectTransport({ ...input, resolve: host => lookup(host, { all: true, verbatim: true }) })) };
+    const resuming = await prepareOutput(outDir) === 'resume';
+    const state = resuming ? await restoreState({ out: outDir, answers }) : { answers, out: outDir, answersDir: path.dirname(path.resolve(answersPath)) };
+    const { state: end, halt } = await runStages(overrides.stages ?? stages(), { ...state, judgments }, deps, { from: resuming ? RESUME_FROM : null });
+    return halt ? { status: halt, judge_queue: path.join(outDir, 'judge-queue.json'), queue_items: end.queue.items.length } :
+      { status: STATUS_DONE, reports: end.reports, score_input: path.join(outDir, 'score-input.json'), ...(end.lab_cwv ? { lab_cwv: end.lab_cwv } : {}) };
+  } finally { await chrome.close(); }
+}
+
+if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  const chrome = chromeHolder(process.env);
+  // Ctrl-C or a terminate signal still closes the render chrome (and its profile folder) before the process leaves.
+  for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { chrome.close().finally(() => process.exit(1)); });
+  try {
+    const args = process.argv.slice(2);
+    const option = name => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+    const answersPath = option('--answers');
+    const out = option('--out');
+    if (!answersPath || !out || args.length % 2 || args.some((arg, i) => i % 2 === 0 && !['--answers', '--out', '--judgments'].includes(arg))) throw new Error(USAGE);
+    const result = await run({ answersPath, out, judgmentsPath: option('--judgments') }, { chrome });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    // The last line of stderr is one plain sentence saying why the run stopped.
+    process.stderr.write(`${String(error.message).replace(/\s*\n\s*/g, ' ')}\n`);
+    process.exitCode = 2;
+  }
+}

package/skills/optbrew/source-lock.json

@@ -395,7 +395,7 @@
       "package_path": "skills/optbrew/modules/naver-searchadvisor/scripts/audit.mjs",
       "original_git_blob_sha": "de8c4a3430633cb2445e339d7a943d944cbf45a9",
       "original_sha256": "3fd83141a00a9d45d4fbffa9d8ff515c7a49e7b1ea4637844e92375ea7797ff9",
-      "distributed_sha256": "fa70051e07b429ad9477b8d778232cc4b3ca0bae8d2a1352074dfd4cb6f5f884",
+      "distributed_sha256": "f19425a43be0d974756722d6069285317b4897720ede58a7bea8f211b6f73103",
       "transformations": [
         "Audit output routes policy evidence to official URL index",
         "reviewed distribution patch naver-robots-rfc9309"

package/source-lock.json

@@ -395,7 +395,7 @@
       "package_path": "skills/optbrew/modules/naver-searchadvisor/scripts/audit.mjs",
       "original_git_blob_sha": "de8c4a3430633cb2445e339d7a943d944cbf45a9",
       "original_sha256": "3fd83141a00a9d45d4fbffa9d8ff515c7a49e7b1ea4637844e92375ea7797ff9",
-      "distributed_sha256": "fa70051e07b429ad9477b8d778232cc4b3ca0bae8d2a1352074dfd4cb6f5f884",
+      "distributed_sha256": "f19425a43be0d974756722d6069285317b4897720ede58a7bea8f211b6f73103",
       "transformations": [
         "Audit output routes policy evidence to official URL index",
         "reviewed distribution patch naver-robots-rfc9309"