optbrew 0.1.3 → 0.2.0

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

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+
+const levels = ['beginner', 'brief'];
+const placeholder = '{{skill_root}}';
+const dir = new URL('../../references/runbooks/', import.meta.url);
+
+let cachedIndex;
+const index = () => cachedIndex ??= JSON.parse(readFileSync(new URL('index.json', dir), 'utf8'));
+const entryOf = id => index().find(entry => entry.id === id);
+/** One index entry (`id`, `kind`, `when`, `fills`, `item`, and sometimes `line` and `expands_to`), or undefined. */
+export const runbookEntry = entryOf;
+/** The `harness:` value in a runbook's front matter. */
+const harnessOf = id => parse(id, readFileSync(new URL(`${id}.md`, dir), 'utf8')).head.harness;
+
+/** Split a runbook file into its front-matter fields and its `## <name>` sections. */
+function parse(id, raw) {
+  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw.replace(/\r\n/g, '\n'));
+  if (!match) throw new Error(`runbook ${id}: front matter is missing`);
+  const head = Object.fromEntries(match[1].split('\n').map(line => [line.slice(0, line.indexOf(':')), line.slice(line.indexOf(':') + 1).trim()]));
+  const sections = Object.fromEntries(match[2].split(/^## /m).slice(1).map(part => {
+    const newline = part.indexOf('\n');
+    return [part.slice(0, newline).trim(), part.slice(newline + 1).trim()];
+  }));
+  return { head, sections };
+}
+
+/** One stored runbook at one guidance level; `{{skill_root}}` becomes the caller's skill folder, inserted as given. */
+export function loadRunbook(id, level, { skillRoot } = {}) {
+  const entry = entryOf(id);
+  if (!entry) throw new Error(`unknown runbook: ${id}`);
+  if (!levels.includes(level)) throw new Error(`runbook level must be one of ${levels.join(', ')}: ${level}`);
+  const { head, sections } = parse(id, readFileSync(new URL(`${id}.md`, dir), 'utf8'));
+  const body = sections[level];
+  if (!body) throw new Error(`runbook ${id} has no ${level} section`);
+  if (body.includes(placeholder) && !skillRoot) throw new Error(`runbook ${id} needs skillRoot`);
+  return { id, kind: entry.kind, text: body.replaceAll(placeholder, () => skillRoot), checked: head.checked, source: head.source, harness: head.harness };
+}
+
+/** What the start probe says is missing. Owner exports cannot be probed, so they always count as missing. */
+const missingOf = probe => new Set([!probe.google_key && 'google_key', !probe.chrome?.found && 'chrome', 'owner_export'].filter(Boolean));
+
+const matchesStart = (when, probe, missing) =>
+  (when.block_reason !== undefined && when.block_reason === probe.block_reason) || (when.missing !== undefined && missing.has(when.missing));
+
+/**
+ * The runbooks to show before the audit starts. A blocking runbook (at most one) comes whole at the chosen level;
+ * an improving one comes as its single line with its `harness`. An entry with no `block_reason` or `missing` is never shown here.
+ * `harnesses`, when given, lists the runbook `harness` values that apply; others are dropped before the one-blocking cap.
+ */
+export function startRunbooks(probe, { level, skillRoot, harnesses = null }) {
+  const missing = missingOf(probe);
+  const hits = index().filter(entry => matchesStart(entry.when, probe, missing))
+    .map(entry => ({ ...entry, harness: harnessOf(entry.id) })).filter(entry => !harnesses || harnesses.includes(entry.harness));
+  const blocking = hits.filter(entry => entry.kind === 'blocking').slice(0, 1).map(entry => loadRunbook(entry.id, level, { skillRoot }));
+  const improving = hits.filter(entry => entry.kind === 'improving').map(({ id, line, harness }) => ({ id, line, harness }));
+  return { blocking, improving };
+}
+
+/** Runbook ids for the `unknown` observations whose reason a runbook can fix, in index order, each once. */
+export function remainingRunbooks(observations) {
+  const reasons = new Set(observations.filter(observation => observation.state === 'unknown').map(observation => observation.reason));
+  return index().filter(entry => reasons.has(entry.when.unknown_reason)).map(entry => entry.id);
+}

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

@@ -40,13 +40,31 @@ export function assertUrlInScope(input, scope) {
   return url;
 }
 
-/** Check origin, path segment, and every resolved address before a request. */
-export function assertInScope(input, scope, resolvedAddresses) {
+export const unbracket = host => host.replace(/^\[|\]$/g, '');
+
+/** Host without IPv6 brackets and the port the URL connects to. */
+export const urlTarget = url => ({ host: unbracket(url.hostname), port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)) });
+
+/**
+ * Check origin, path segment, and every resolved address before a request.
+ * Through a proxy (`addressVetting: 'proxy'`) the proxy resolves names, so only DNS-name vetting is skipped:
+ * IP literals and localhost names are still checked here.
+ */
+export function assertInScope(input, scope, resolvedAddresses, { addressVetting = 'direct' } = {}) {
   const url = assertUrlInScope(input, scope);
-  if (!Array.isArray(resolvedAddresses) || !resolvedAddresses.length) throw new Error('resolved addresses required');
-  const host = url.hostname.replace(/^\[|\]$/g, '');
-  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+  const target = urlTarget(url);
+  const { port } = target;
+  // A trailing dot is the same name (`localhost.` resolves like `localhost`), so compare without it.
+  const host = target.host.replace(/\.$/, '');
   const local = (scope.local_targets ?? []).some(x => x.host === host && Number(x.port) === port);
+  if (addressVetting === 'proxy') {
+    if (local) return url;
+    if (isIP(host)) {
+      if (privateAddress(host)) throw new Error('private or reserved address outside local target');
+    } else if (host === 'localhost' || host.endsWith('.localhost')) throw new Error('localhost outside local target');
+    return url;
+  }
+  if (!Array.isArray(resolvedAddresses) || !resolvedAddresses.length) throw new Error('resolved addresses required');
   for (const address of resolvedAddresses) if (privateAddress(address) && !local) throw new Error('private or reserved address outside local target');
   return url;
 }

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

@@ -1,11 +1,16 @@
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { validateEntity, cwvVerdict, ContractError } from './contracts.mjs';
+import { versions } from './config.mjs';
 import { compileUnits, scoreWeighted } from './weights.mjs';
+import { assertCurrentEvidence } from './migration.mjs';
 
 const registry = JSON.parse(readFileSync(new URL('../../references/check-registry.json', import.meta.url)));
 const profiles = JSON.parse(readFileSync(new URL('../../references/profiles.json', import.meta.url)));
 const bundleRoot = new URL('../../', import.meta.url);
+// Same rule as fileDigest in bundle.mjs: CRLF from a core.autocrlf checkout hashes as the committed LF bytes.
+const sourceDigest = bytes => createHash('sha256')
+  .update(bytes.includes(0) ? bytes : Buffer.from(bytes.toString('latin1').replaceAll('\r\n', '\n'), 'latin1')).digest('hex');
 
 function assertEvaluationIdentity(context) {
   const manifest = JSON.parse(readFileSync(new URL('bundle-manifest.json', bundleRoot), 'utf8'));
@@ -17,7 +22,7 @@ function assertEvaluationIdentity(context) {
     const sources = manifest[field];
     if (!Array.isArray(sources) || !sources.length ||
         createHash('sha256').update(JSON.stringify(sources)).digest('hex') !== manifest[hashField] ||
-        sources.some(source => createHash('sha256').update(readFileSync(new URL(source.path, bundleRoot))).digest('hex') !== source.sha256))
+        sources.some(source => sourceDigest(readFileSync(new URL(source.path, bundleRoot))) !== source.sha256))
       throw new ContractError(`${field} identity differs from installed bundle`);
   }
 }
@@ -34,6 +39,7 @@ function band(score) {
 
 /** Readiness scores are local audit status, never predicted search or AI outcomes. */
 export function score(input) {
+  assertCurrentEvidence(input, 'score input');
   validateEntity('ScoreInput', input);
   assertEvaluationIdentity(input.run_context);
   const units = compileUnits(input, 'SEO');
@@ -61,11 +67,13 @@ export function score(input) {
   const selectedProfiles = Object.keys(profiles.profiles).filter(name => name !== 'NEO' || input.run_context.protocol.engines.includes('naver'));
   return selectedProfiles.map(profile => {
     const weighted = scoreWeighted(compileUnits(input, profile));
-    const readiness_status = weighted.A === 0 ? 'not_applicable' : blockers.length ? 'blocked' :
+    const readiness = weighted.A === 0 ? 'not_applicable' : blockers.length ? 'blocked' :
       unknown_core.length ? 'unverified' : 100 * weighted.M / weighted.A < 80 - 1e-9 ? 'provisional' : 'measured';
-    const result = { schema_version: '1.0.0', evaluation_version: input.run_context.evaluation_version,
+    // Verdicts of a phase with no audit cannot be replayed from collected evidence, so such a phase is never 'measured'.
+    const readiness_status = readiness === 'measured' && input.run_context.audited !== true ? 'unverified' : readiness;
+    const result = { schema_version: versions().contract_schema, evaluation_version: input.run_context.evaluation_version,
       profile, ...weighted, band: band(weighted.M === 0 ? null : 100 * weighted.N / weighted.M), readiness_status,
-      blockers, unknown_core, source_ref: 'optbrew:scoring:0.1.0' };
+      blockers, unknown_core, source_ref: `optbrew:scoring:${versions().evaluation}` };
     return validateEntity('ScoreResult', result);
   });
 }

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

@@ -0,0 +1,2 @@
+/** Secret and private-identifier shapes that must never reach a report packet, stored evidence, or a model-judgment queue. */
+export const sensitive = /(?:sk-ant-api03-[A-Za-z0-9_-]{32,}|sk-proj-[A-Za-z0-9_-]{32,}|ghp_[A-Za-z0-9]{36,}|AKIA[A-Z0-9]{16}|AIza[0-9A-Za-z_-]{35}|\b\d{6}-[1-8]\d{6}\b)/;