aub-workspace 0.3.0

package/vendor/aub/scripts/run-agent-readability.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scoreAgentOutput } from './score-agent-readability.mjs';
+
+const args = process.argv.slice(2);
+const separator = args.indexOf('--');
+const options = separator >= 0 ? args.slice(0, separator) : args;
+const command = separator >= 0 ? args.slice(separator + 1) : [];
+const name = options.find((value) => !value.startsWith('--'));
+const allowsExternal = options.includes('--allow-external');
+
+if (!name || command.length === 0) {
+  console.error('Usage: node scripts/run-agent-readability.mjs <agent-name> --allow-external -- <command> [args...]');
+  process.exit(2);
+}
+
+if (!allowsExternal) {
+  console.error('Refusing to run an external agent without the explicit --allow-external flag.');
+  process.exit(2);
+}
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const benchmarkDir = resolve(root, 'benchmarks/agent-readability');
+const resultDir = resolve(benchmarkDir, 'results');
+const prompt = await readFile(resolve(benchmarkDir, 'prompt.md'), 'utf8');
+const fixture = await readFile(resolve(root, 'examples/freeform-actions.ui.json'), 'utf8');
+const expected = JSON.parse(await readFile(resolve(benchmarkDir, 'expected.json'), 'utf8'));
+await mkdir(resultDir, { recursive: true });
+
+const benchmarkInput = [
+  prompt.trim(),
+  '',
+  '<blueprint_json>',
+  fixture.trim(),
+  '</blueprint_json>',
+  '',
+].join('\n');
+const result = await run(command[0], command.slice(1), benchmarkInput, root);
+const slug = name.replace(/[^a-zA-Z0-9._-]+/g, '-');
+await writeFile(resolve(resultDir, `${slug}.stdout.txt`), result.stdout, 'utf8');
+await writeFile(resolve(resultDir, `${slug}.stderr.txt`), result.stderr, 'utf8');
+
+if (result.code !== 0) {
+  console.error(`${name} exited with code ${result.code}. See benchmarks/agent-readability/results/${slug}.stderr.txt`);
+  process.exit(result.code || 1);
+}
+
+const actual = extractJsonObject(result.stdout);
+const report = {
+  agent: name,
+  command: command.map(redactArgument),
+  executed_at: new Date().toISOString(),
+  ...scoreAgentOutput(actual, expected),
+};
+await writeFile(resolve(resultDir, `${slug}.output.json`), `${JSON.stringify(actual, null, 2)}\n`, 'utf8');
+await writeFile(resolve(resultDir, `${slug}.report.json`), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+console.log(JSON.stringify(report, null, 2));
+process.exit(report.score === 100 ? 0 : 1);
+
+function run(executable, commandArgs, stdin, cwd) {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn(executable, commandArgs, {
+      cwd,
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code) => resolveRun({ code: code ?? 1, stdout, stderr }));
+    child.stdin.end(stdin);
+  });
+}
+
+function extractJsonObject(text) {
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+  for (const candidate of [trimmed, fenced].filter(Boolean)) {
+    try {
+      const value = JSON.parse(candidate);
+      if (isBenchmarkOutput(value)) return value;
+    } catch {
+      // Continue to balanced-object extraction.
+    }
+  }
+
+  for (let start = trimmed.indexOf('{'); start >= 0; start = trimmed.indexOf('{', start + 1)) {
+    const candidate = balancedObjectAt(trimmed, start);
+    if (!candidate) continue;
+    try {
+      const value = JSON.parse(candidate);
+      if (isBenchmarkOutput(value)) return value;
+    } catch {
+      // Try the next opening brace.
+    }
+  }
+  throw new Error('Agent output did not contain one parseable JSON object.');
+}
+
+function isBenchmarkOutput(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    typeof value.version === 'string' &&
+    typeof value.root_id === 'string' &&
+    Array.isArray(value.direct_root_children)
+  );
+}
+
+function balancedObjectAt(text, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = start; index < text.length; index += 1) {
+    const character = text[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === '\\') escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') inString = true;
+    else if (character === '{') depth += 1;
+    else if (character === '}') {
+      depth -= 1;
+      if (depth === 0) return text.slice(start, index + 1);
+    }
+  }
+  return null;
+}
+
+function redactArgument(argument) {
+  return /(?:key|token|secret|password)=/i.test(argument)
+    ? argument.replace(/=.*/, '=REDACTED')
+    : argument;
+}

package/vendor/aub/scripts/run-ollama-prompt.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+const [model, baseUrl = 'http://127.0.0.1:11434'] = process.argv.slice(2);
+if (!model) {
+  console.error('Usage: node scripts/run-ollama-prompt.mjs <model> [ollama-base-url]');
+  process.exit(2);
+}
+
+let prompt = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) prompt += chunk;
+const response = await fetch(`${baseUrl.replace(/\/$/, '')}/api/generate`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    model,
+    prompt,
+    stream: false,
+    think: false,
+    format: 'json',
+    options: { temperature: 0 },
+  }),
+});
+
+if (!response.ok) {
+  throw new Error(`Ollama request failed: ${response.status} ${await response.text()}`);
+}
+
+const result = await response.json();
+process.stdout.write(result.response ?? '');

package/vendor/aub/scripts/scaffold-blueprint.lib.d.mts

@@ -0,0 +1,38 @@
+export type Blueprint = Record<string, any>;
+
+export type ScaffoldSection = 'interactions' | 'responsive' | 'acceptance';
+export type ScaffoldLanguage = 'en' | 'zh-Hant';
+
+export interface ScaffoldOptions {
+  sections?: ScaffoldSection[];
+  language?: ScaffoldLanguage;
+}
+
+export interface ScaffoldSummary {
+  interactions: number;
+  responsive: number;
+  acceptance: number;
+  total: number;
+}
+
+export const SCAFFOLD_SECTIONS: ScaffoldSection[];
+
+export function scaffoldInteractions(
+  blueprint: Blueprint,
+  options?: { language?: ScaffoldLanguage }
+): { interactions: any[]; added: any[] };
+
+export function scaffoldResponsive(
+  blueprint: Blueprint,
+  options?: { language?: ScaffoldLanguage }
+): { responsive: any[]; added: any[] };
+
+export function scaffoldAcceptance(
+  blueprint: Blueprint,
+  options?: { language?: ScaffoldLanguage }
+): { acceptance: any[]; added: any[] };
+
+export function scaffoldBlueprint(
+  blueprint: Blueprint,
+  options?: ScaffoldOptions
+): { blueprint: Blueprint; summary: ScaffoldSummary };

package/vendor/aub/scripts/scaffold-blueprint.lib.mjs

@@ -0,0 +1,316 @@
+// Pure, deterministic scaffolding for the three specification sections that are
+// often left empty when a blueprint does not come from a built-in template
+// (blank starts, custom trees, Angular imports): interactions, responsive rules,
+// and acceptance criteria.
+//
+// Every function is NON-DESTRUCTIVE: it only appends derived items for things not
+// already covered and never rewrites or reorders existing user content. Output is
+// deterministic so the editor, the CLI, and the MCP server all produce the same
+// result for the same blueprint.
+
+export const SCAFFOLD_SECTIONS = ['interactions', 'responsive', 'acceptance'];
+
+const MAX_GENERATED_INTERACTIONS = 12;
+
+// Component types that imply a user interaction worth declaring.
+const ACTIONABLE_TYPES = new Set([
+  'button',
+  'icon_button',
+  'button_group',
+  'nav_item',
+  'link',
+  'menu',
+  'command_palette',
+  'form',
+  'search_input',
+  'text_input',
+  'textarea',
+  'select',
+  'checkbox',
+  'radio_group',
+  'toggle',
+  'slider',
+  'date_picker',
+  'file_upload',
+  'tabs',
+  'stepper',
+]);
+
+const CHANGE_TYPES = new Set([
+  'select',
+  'checkbox',
+  'radio_group',
+  'toggle',
+  'slider',
+  'date_picker',
+  'file_upload',
+  'text_input',
+  'textarea',
+]);
+
+const SUBMIT_TYPES = new Set(['form', 'search_input']);
+
+function pick(language, en, zh) {
+  return language === 'zh-Hant' ? zh : en;
+}
+
+function uniqueId(prefix, existing) {
+  const used = new Set(existing);
+  let index = existing.length + 1;
+  let candidate = `${prefix}_${index}`;
+  while (used.has(candidate)) {
+    index += 1;
+    candidate = `${prefix}_${index}`;
+  }
+  return candidate;
+}
+
+function nodeList(blueprint) {
+  return Array.isArray(blueprint?.nodes) ? blueprint.nodes : [];
+}
+
+function triggerFor(type) {
+  if (SUBMIT_TYPES.has(type)) return 'submit';
+  if (CHANGE_TYPES.has(type)) return 'change';
+  return 'click';
+}
+
+function actionFor(node) {
+  const declared = node?.content?.action;
+  if (typeof declared === 'string' && declared.trim()) return declared.trim();
+  const type = node.type;
+  if (SUBMIT_TYPES.has(type)) return `submit:${node.id}`;
+  if (CHANGE_TYPES.has(type)) return `change:${node.id}`;
+  if (type === 'link' || type === 'nav_item') return `navigate:${node.id}`;
+  return `activate:${node.id}`;
+}
+
+/** Append interactions derived from actionable nodes not already wired. */
+export function scaffoldInteractions(blueprint, { language = 'en' } = {}) {
+  const existing = Array.isArray(blueprint?.interactions) ? blueprint.interactions : [];
+  const wired = new Set(existing.map((item) => item?.source_node_id).filter(Boolean));
+  const ids = existing.map((item) => item?.id).filter(Boolean);
+  const added = [];
+
+  for (const node of nodeList(blueprint)) {
+    if (added.length >= MAX_GENERATED_INTERACTIONS) break;
+    if (!node?.id || !ACTIONABLE_TYPES.has(node.type)) continue;
+    if (wired.has(node.id)) continue;
+    wired.add(node.id);
+
+    const trigger = triggerFor(node.type);
+    const id = uniqueId('interaction', [...ids, ...added.map((item) => item.id)]);
+    const name = node.name ?? node.id;
+    added.push({
+      id,
+      trigger,
+      source_node_id: node.id,
+      action: actionFor(node),
+      result_state: pick(
+        language,
+        `The result of ${name} is visibly presented to the user.`,
+        `${name} 的操作結果清楚呈現給使用者。`
+      ),
+    });
+  }
+
+  return { interactions: [...existing, ...added], added };
+}
+
+const SUB_DESKTOP_VIEWPORTS = new Set(['tablet', 'mobile']);
+
+function isMultiColumnGrid(node) {
+  const layout = node?.layout;
+  if (!layout) return false;
+  const columns = layout.grid?.columns ?? layout.columns;
+  return (layout.display === 'grid' || layout.mode === 'grid') && Number(columns) > 1;
+}
+
+function responsiveTargetsFor(blueprint, viewportId) {
+  const nodes = nodeList(blueprint);
+  const targets = [];
+  const seen = new Set();
+  const push = (nodeId, rule, changes) => {
+    if (!nodeId || seen.has(nodeId)) return;
+    seen.add(nodeId);
+    targets.push({ target_node_id: nodeId, rule, changes });
+  };
+
+  for (const node of nodes) {
+    if (node.type === 'sidebar') push(node.id, 'drawer', {});
+  }
+  for (const node of nodes) {
+    if (node.type === 'top_bar' || node.type === 'bottom_nav' || node.type === 'toolbar') {
+      push(node.id, viewportId === 'mobile' ? 'bottom_nav' : 'icon_only', {});
+    }
+  }
+  for (const node of nodes) {
+    if (isMultiColumnGrid(node)) push(node.id, 'col_reduce', { columns: viewportId === 'mobile' ? 1 : 2 });
+  }
+
+  if (targets.length === 0) {
+    const root = nodes.find((node) => node.parent_id == null) ?? nodes[0];
+    if (root) push(root.id, 'stack', {});
+  }
+  return targets;
+}
+
+/** Append responsive rules for sub-desktop viewports not already covered. */
+export function scaffoldResponsive(blueprint) {
+  const existing = Array.isArray(blueprint?.responsive) ? blueprint.responsive : [];
+  const covered = new Set(existing.map((item) => `${item?.viewport}::${item?.target_node_id}`));
+  const viewports = Array.isArray(blueprint?.viewports) ? blueprint.viewports : [];
+  const added = [];
+
+  for (const viewport of viewports) {
+    const viewportId = viewport?.id;
+    if (!SUB_DESKTOP_VIEWPORTS.has(viewportId)) continue;
+    for (const target of responsiveTargetsFor(blueprint, viewportId)) {
+      const key = `${viewportId}::${target.target_node_id}`;
+      if (covered.has(key)) continue;
+      covered.add(key);
+      added.push({
+        viewport: viewportId,
+        rule: target.rule,
+        target_node_id: target.target_node_id,
+        changes: target.changes,
+      });
+    }
+  }
+
+  return { responsive: [...existing, ...added], added };
+}
+
+const REQUIRED_ACCEPTANCE_TYPES = ['layout', 'interaction', 'responsive', 'a11y'];
+const MIN_ACCEPTANCE = 5;
+
+function acceptanceCriterion(type, blueprint, language) {
+  const nodes = nodeList(blueprint);
+  const root = nodes.find((node) => node.parent_id == null) ?? nodes[0];
+  const subViewport =
+    (blueprint?.viewports ?? []).map((viewport) => viewport?.id).find((id) => SUB_DESKTOP_VIEWPORTS.has(id)) ??
+    'mobile';
+  switch (type) {
+    case 'layout':
+      return {
+        type: 'layout',
+        statement: pick(
+          language,
+          'All major regions match their declared placements on desktop.',
+          '桌面版所有主要區域的位置與尺寸符合 placement。'
+        ),
+        target: 'desktop',
+        priority: 'blocker',
+        verification_method: 'screenshot_diff',
+      };
+    case 'interaction':
+      return {
+        type: 'interaction',
+        statement: pick(
+          language,
+          'Primary buttons and navigation controls declare and perform their actions.',
+          '所有主要按鈕與導覽操作都有明確 action 並可執行。'
+        ),
+        target: '*',
+        priority: 'must',
+        verification_method: 'interaction_replay',
+      };
+    case 'responsive':
+      return {
+        type: 'responsive',
+        statement: pick(
+          language,
+          `The ${subViewport} layout adapts without horizontal overflow.`,
+          `${subViewport} 版面自適應且不水平溢出。`
+        ),
+        target: subViewport,
+        priority: 'must',
+        verification_method: 'screenshot_diff',
+      };
+    case 'a11y':
+      return {
+        type: 'a11y',
+        statement: pick(
+          language,
+          'Interactive controls have understandable labels and visible focus states.',
+          '互動元件具備可理解的文字標籤與可見的 focus 狀態。'
+        ),
+        target: '*',
+        priority: 'must',
+        verification_method: 'axe_audit',
+      };
+    case 'content':
+    default:
+      return {
+        type: 'content',
+        statement: pick(
+          language,
+          `Names and content explain the purpose of each major region${root ? ` starting at ${root.name ?? root.id}` : ''}.`,
+          '每個主要區域的名稱與內容能說明其用途。'
+        ),
+        target: '*',
+        priority: 'should',
+        verification_method: 'manual_ia_review',
+      };
+  }
+}
+
+/** Append acceptance criteria so coverage spans the required types and totals >= 5. */
+export function scaffoldAcceptance(blueprint, { language = 'en' } = {}) {
+  const existing = Array.isArray(blueprint?.acceptance) ? blueprint.acceptance : [];
+  const presentTypes = new Set(existing.map((item) => item?.type).filter(Boolean));
+  const ids = existing.map((item) => item?.id).filter(Boolean);
+  const added = [];
+
+  const emit = (type) => {
+    const criterion = acceptanceCriterion(type, blueprint, language);
+    const id = uniqueId('acc', [...ids, ...added.map((item) => item.id)]);
+    added.push({ id, ...criterion });
+  };
+
+  for (const type of REQUIRED_ACCEPTANCE_TYPES) {
+    if (!presentTypes.has(type)) {
+      presentTypes.add(type);
+      emit(type);
+    }
+  }
+
+  const padOrder = ['content', 'responsive', 'a11y', 'interaction', 'layout'];
+  let padIndex = 0;
+  while (existing.length + added.length < MIN_ACCEPTANCE) {
+    emit(padOrder[padIndex % padOrder.length]);
+    padIndex += 1;
+  }
+
+  return { acceptance: [...existing, ...added], added };
+}
+
+/**
+ * Scaffold the requested sections of a blueprint. Returns a NEW blueprint plus a
+ * per-section summary of how many items were added. Never mutates the input and
+ * never overwrites existing entries.
+ */
+export function scaffoldBlueprint(blueprint, { sections = SCAFFOLD_SECTIONS, language = 'en' } = {}) {
+  const requested = new Set(sections);
+  const next = { ...blueprint };
+  const summary = { interactions: 0, responsive: 0, acceptance: 0 };
+
+  if (requested.has('interactions')) {
+    const result = scaffoldInteractions(blueprint, { language });
+    next.interactions = result.interactions;
+    summary.interactions = result.added.length;
+  }
+  if (requested.has('responsive')) {
+    const result = scaffoldResponsive(next, { language });
+    next.responsive = result.responsive;
+    summary.responsive = result.added.length;
+  }
+  if (requested.has('acceptance')) {
+    const result = scaffoldAcceptance(next, { language });
+    next.acceptance = result.acceptance;
+    summary.acceptance = result.added.length;
+  }
+
+  summary.total = summary.interactions + summary.responsive + summary.acceptance;
+  return { blueprint: next, summary };
+}

package/vendor/aub/scripts/scaffold-blueprint.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Scaffold the spec sections (interactions, responsive, acceptance) of a Blueprint.
+// Derivation is deterministic and non-destructive: existing entries are preserved
+// and only missing items are appended.
+//
+// Usage:
+//   node scripts/scaffold-blueprint.mjs <file.ui.json|yaml> [options]
+// Options:
+//   --sections a,b,c   Comma list of sections to scaffold (default: all).
+//   --language <lang>  'en' (default) or 'zh-Hant' for generated statements.
+//   --write            Write the result back to the input file.
+//   --stdout           Print the scaffolded blueprint to stdout (default if not --write).
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import { scaffoldBlueprint, SCAFFOLD_SECTIONS } from './scaffold-blueprint.lib.mjs';
+
+function parseArgs(argv) {
+  const args = { file: null, sections: null, language: 'en', write: false, stdout: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--write') args.write = true;
+    else if (token === '--stdout') args.stdout = true;
+    else if (token === '--sections') args.sections = splitSections(argv[++i]);
+    else if (token.startsWith('--sections=')) args.sections = splitSections(token.slice('--sections='.length));
+    else if (token === '--language') args.language = argv[++i];
+    else if (token.startsWith('--language=')) args.language = token.slice('--language='.length);
+    else if (!args.file) args.file = token;
+  }
+  return args;
+}
+
+function splitSections(value) {
+  return (value ?? '')
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function isYaml(path) {
+  const ext = extname(path).toLowerCase();
+  return ext === '.yaml' || ext === '.yml';
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.file) {
+    console.error('Usage: node scripts/scaffold-blueprint.mjs <file.ui.json|yaml> [--sections a,b,c] [--language en|zh-Hant] [--write|--stdout]');
+    process.exit(2);
+  }
+
+  const sections = args.sections ?? SCAFFOLD_SECTIONS;
+  const unknown = sections.filter((section) => !SCAFFOLD_SECTIONS.includes(section));
+  if (unknown.length > 0) {
+    console.error(`Unknown section(s): ${unknown.join(', ')}. Valid: ${SCAFFOLD_SECTIONS.join(', ')}`);
+    process.exit(2);
+  }
+
+  const filePath = resolve(args.file);
+  const raw = await readFile(filePath, 'utf8');
+  const document = isYaml(filePath) ? yaml.load(raw) : JSON.parse(raw);
+
+  const { blueprint, summary } = scaffoldBlueprint(document, { sections, language: args.language });
+
+  const serialized = isYaml(filePath)
+    ? yaml.dump(blueprint, { noRefs: true, lineWidth: 120, sortKeys: false })
+    : `${JSON.stringify(blueprint, null, 2)}\n`;
+
+  if (args.write) {
+    await writeFile(filePath, serialized, 'utf8');
+    console.error(
+      `✓ scaffolded ${args.file} (+${summary.interactions} interactions, +${summary.responsive} responsive, +${summary.acceptance} acceptance)`
+    );
+  } else {
+    process.stdout.write(serialized);
+    console.error(
+      `✓ +${summary.interactions} interactions, +${summary.responsive} responsive, +${summary.acceptance} acceptance (use --write to save)`
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(2);
+});

package/vendor/aub/scripts/score-agent-implementation.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { scoreImplementationBenchmark } from './agent-implementation-benchmark.lib.mjs';
+
+const [measurementsPath, implementationReportPath, outputPath] = process.argv.slice(2);
+if (!measurementsPath || !implementationReportPath) {
+  console.error('Usage: node scripts/score-agent-implementation.mjs <measurements.json> <implementation-report.json> [output.json]');
+  process.exit(2);
+}
+
+const [blueprint, measurements, implementationReport] = await Promise.all([
+  readFile(resolve('examples/freeform-actions.ui.json'), 'utf8').then(JSON.parse),
+  readFile(resolve(measurementsPath), 'utf8').then(JSON.parse),
+  readFile(resolve(implementationReportPath), 'utf8').then(JSON.parse),
+]);
+const result = scoreImplementationBenchmark(
+  blueprint,
+  measurements.candidate,
+  measurements.reference,
+  implementationReport
+);
+const output = `${JSON.stringify(result, null, 2)}\n`;
+if (outputPath) await writeFile(resolve(outputPath), output, 'utf8');
+else process.stdout.write(output);
+process.exit(result.ready ? 0 : 1);

package/vendor/aub/scripts/score-agent-readability.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export function scoreAgentOutput(actual, expected) {
+  const checks = [];
+  compare(expected, actual, '$', checks);
+  const passed = checks.filter((check) => check.pass).length;
+  return {
+    score: Math.round((passed / checks.length) * 100),
+    passed,
+    total: checks.length,
+    checks,
+  };
+}
+
+async function main() {
+  const [actualPath, expectedPath = 'benchmarks/agent-readability/expected.json'] = process.argv.slice(2);
+  if (!actualPath) {
+    console.error('Usage: node scripts/score-agent-readability.mjs <agent-output.json> [expected.json]');
+    process.exit(2);
+  }
+
+  const actual = JSON.parse(await readFile(resolve(actualPath), 'utf8'));
+  const expected = JSON.parse(await readFile(resolve(expectedPath), 'utf8'));
+  const report = scoreAgentOutput(actual, expected);
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(report.score === 100 ? 0 : 1);
+}
+
+function compare(expectedValue, actualValue, path, checks) {
+  if (Array.isArray(expectedValue)) {
+    checks.push({
+      path,
+      pass: JSON.stringify(actualValue) === JSON.stringify(expectedValue),
+      expected: expectedValue,
+      actual: actualValue,
+    });
+    return;
+  }
+  if (expectedValue && typeof expectedValue === 'object') {
+    for (const [key, value] of Object.entries(expectedValue)) {
+      compare(value, actualValue?.[key], `${path}.${key}`, checks);
+    }
+    return;
+  }
+  checks.push({ path, pass: Object.is(actualValue, expectedValue), expected: expectedValue, actual: actualValue });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  await main();
+}