fimo 2.6.0-staging.1 → 2.6.0-staging.3

package/assets/skills/fimo-migration/references/workers/content-execution.md

@@ -22,7 +22,8 @@ do not poll indefinitely.
 Start only after this batch's real records read back as non-empty. Own exactly
 the consumer files assigned by the planner.
 
-1. Load the active framework's `fimo-code` reference.
+1. Load the active framework's `fimo-code` reference. Before changing a media
+   read or image component, load `fimo skills get fimo-migration --ref media`.
 2. Establish the generated Fimo client/adapter needed by the batch.
 3. Replace every planned `sourceFile`/`sourceKey` at its existing consumer in
    place. Appending a disconnected duplicate section is not wiring.

package/assets/skills/fimo-migration/references/workers/validator.md

@@ -1,11 +1,13 @@
 # Migration validator
 
 Validation is one independent read-only wave after all writers return. The
-coordinator gives every validator the accepted migration scope and deliberate
-user-approved differences, but no producer findings, repair reasoning,
-transcript, or expected verdict. A validator checks the finished target against
-the source within that contract. It does not report an explicitly excluded
-route, integration, or control as migration drift.
+coordinator gives every validator the accepted migration scope, deliberate
+user-approved differences, and the guardrail inventory path
+(`references/qa.md`, Rendered guardrails), but no producer findings, repair
+reasoning, transcript, or expected verdict. A validator may add a rule the
+source proves; it never removes or narrows one. A validator checks the
+finished target against the source within that contract. It does not report an
+explicitly excluded route, integration, or control as migration drift.
 
 When subagents are available, launch separate workers for build and runtime,
 Fimo data and content, and rendered browser behavior. Run them concurrently
@@ -13,11 +15,18 @@ after their prerequisites pass. They may inspect overlapping files because none
 of them writes.
 
 Compare the source, content plan, actual `git diff`, real Fimo state, and local
-application behavior. A worker report is a claim, not evidence.
+application behavior. A worker report, manifest, or coverage table is a
+diagnostic, not acceptance evidence. A check that observed nothing - zero
+rendered routes, zero collected links, zero matched rules - is failed, not
+passed.
 
 Verify:
 
 - every source route renders with expected status and representative content;
+- the rendered guardrail inventory passes: brand, legal, compliance, and
+  navigation rules are proven on rendered HTML or a running local server with
+  `scripts/check-rendered-guardrails.mjs`, never by grepping target source.
+  Browser captures include the response metadata required by `references/qa.md`;
 - schemas, entries, singles, labels, media, forms, and locales exist through
   CLI read-back;
 - every planned source item is consumed at its original behavior path, not in
@@ -43,6 +52,13 @@ duration, checks run, counts, failing source items, blocked descendants, and
 suggested repair ownership. Stop only when a failed prerequisite makes a check
 meaningless.
 
+End every validator report with an `Acceptance` section: the exact commands
+another party can rerun (build, local start, the guardrail check with its
+inventory and observation source, CLI read-back) and the expected evidence for
+each - exit status, the unmodified `## Guardrails` block ending in
+`Result: passed`, and the counts observed. A pass reported without its command
+and output is a claim.
+
 The coordinator fans every lane into one finding set before editing. It assigns
 disjoint repair owners, waits for the whole repair wave, then reruns one central
 validation wave. It does not restart every worker, repair findings one at a

package/assets/skills/fimo-migration/references/workers.md

@@ -76,9 +76,11 @@ other after it. Do not add a metadata format for a small overlap.
    framework gate.
 6. Start each code worker only after its own imported records read back as
    non-empty. A build over empty data proves nothing.
-7. After every writer returns, start one read-only validation wave. When
-   subagents are available, run build and runtime, Fimo data and content, and
-   rendered browser checks concurrently after their prerequisites pass.
+7. Before the validation wave, write the cited rendered-guardrail inventory
+   required by `references/qa.md`. After every writer returns, start one
+   read-only validation wave. When subagents are available, run build and
+   runtime, Fimo data and content, and rendered browser checks concurrently
+   after their prerequisites pass.
 
 Each prompt names the worker's source paths, exact target ownership, applicable
 reference above, and dependencies. Each report states status, duration, source

package/assets/skills/fimo-migration/scripts/check-rendered-guardrails.mjs

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+// @ts-check
+// Evaluates the migration guardrail inventory against the final rendered
+// application. Inputs are rendered HTML observations (browser/HTTP captures or
+// a running local server), never the target's source files: once copy moves
+// into Fimo, a source grep proves nothing about what visitors see.
+//
+// The check fails closed. An empty inventory, a route with no rendered text,
+// or a rule that ends up evaluated against zero observations is a failure, not
+// a pass.
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+/**
+ * Shipped as plain JavaScript so a migration target needs only Node.
+ * Checked with its subprocess tests by tsconfig.guardrails.json.
+ * @typedef {{projectRoot?: string, inventory?: string, captures?: string, baseUrl?: string, output?: string}} Args
+ * @typedef {{id: string, kind: string, source?: string, text?: string | string[], href?: string, routes?: string[], allow?: string[]}} Rule
+ * @typedef {{routes: string[], rules: Rule[]}} Inventory
+ * @typedef {{route: string, source: string, url: string, baseUrl: string, html: string | null, text: string, links: string[], passed: boolean, reason: string}} Observation
+ * @typedef {{id: string, kind: string, passed: boolean, observed: number, failures: string[], extra: string | null}} Result
+ */
+
+const USAGE =
+  'Usage: node check-rendered-guardrails.mjs [project-root] [--inventory .fimo/migration/guardrails.json] ' +
+  '(--captures <dir> | --base-url <http://localhost:port>) [--output .fimo/migration/guardrails-report.md]';
+
+const RULE_KINDS = ['required-text', 'forbidden-text', 'required-link', 'links-resolve'];
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const projectRoot = path.resolve(args.projectRoot ?? process.cwd());
+  const inventoryPath = path.resolve(projectRoot, args.inventory ?? '.fimo/migration/guardrails.json');
+  const inventory = loadInventory(inventoryPath);
+
+  if (!args.captures && !args.baseUrl) fail(`Provide --captures <dir> or --base-url <url>.\n${USAGE}`);
+  if (args.captures && args.baseUrl) fail('Provide either --captures or --base-url, not both.');
+
+  const observations = args.baseUrl
+    ? await fetchObservations(inventory.routes, args.baseUrl)
+    : readCaptures(inventory.routes, path.resolve(projectRoot, args.captures ?? ''));
+  const results = evaluateRules(inventory, observations);
+  const passed = observations.every((item) => item.passed) && results.every((item) => item.passed);
+
+  const report = buildReport({
+    inventoryPath: toPosix(path.relative(projectRoot, inventoryPath)),
+    inventory,
+    source: args.baseUrl
+      ? `fetched from ${args.baseUrl}`
+      : `captures in ${toPosix(path.relative(projectRoot, path.resolve(projectRoot, args.captures ?? '')))}`,
+    observations,
+    results,
+    passed,
+  });
+
+  if (args.output) {
+    const outputPath = path.resolve(projectRoot, args.output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, report, 'utf8');
+  }
+  console.log(report);
+  if (!passed) process.exitCode = 1;
+}
+
+/** @param {string[]} argv */
+function parseArgs(argv) {
+  /** @type {Args} */
+  const args = {};
+  /** @type {Record<string, keyof Args>} */
+  const valueFlags = {
+    '--inventory': 'inventory',
+    '--captures': 'captures',
+    '--base-url': 'baseUrl',
+    '--output': 'output',
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      console.log(USAGE);
+      process.exit(0);
+    }
+    const [flag, inlineValue] = arg.includes('=')
+      ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)]
+      : [arg, undefined];
+    if (valueFlags[flag]) {
+      const value = inlineValue ?? argv[++i];
+      if (!value || value.startsWith('--')) fail(`Missing value for ${flag}.\n${USAGE}`);
+      args[valueFlags[flag]] = value;
+      continue;
+    }
+    if (!arg.startsWith('--') && !args.projectRoot) {
+      args.projectRoot = arg;
+      continue;
+    }
+    fail(`Unknown argument: ${arg}\n${USAGE}`);
+  }
+  return args;
+}
+
+// The inventory is the explicit acceptance contract. It must name the route
+// surface and at least one rule; the script never infers either from the
+// target, so a migration cannot pass by declaring nothing.
+/** @param {string} inventoryPath @returns {Inventory} */
+function loadInventory(inventoryPath) {
+  if (!fs.existsSync(inventoryPath)) fail(`Guardrail inventory not found: ${inventoryPath}`);
+  /** @type {unknown} */
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(inventoryPath, 'utf8'));
+  } catch (error) {
+    fail(`Could not parse ${inventoryPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord(raw) || !Array.isArray(raw.routes) || !Array.isArray(raw.rules)) {
+    fail('Invalid guardrail inventory: expected an object with routes and rules arrays.');
+  }
+  if (!raw.routes.every(isNonEmptyString)) fail('Invalid guardrail inventory: routes must be non-empty strings.');
+  // Keep trailing slashes for document-relative URL resolution during fetches.
+  const routes = uniqueArray(
+    raw.routes.map(
+      (route) => normalizePath(route) + (route.trim().endsWith('/') && normalizePath(route) !== '/' ? '/' : '')
+    )
+  );
+  const rules = raw.rules;
+  if (routes.length === 0)
+    fail(
+      `Empty guardrail inventory: ${inventoryPath} lists no routes. Inventory every rendered route the migration must prove.`
+    );
+  if (rules.length === 0)
+    fail(
+      `Empty guardrail inventory: ${inventoryPath} lists no rules. Add the brand, legal/compliance, and navigation rules the source imposes.`
+    );
+  rules.forEach((rule, index) => {
+    if (!isRecord(rule)) fail(`Rule #${index + 1} must be an object.`);
+    if (!isNonEmptyString(rule.id)) fail(`Rule #${index + 1} has no id.`);
+    if (typeof rule.kind !== 'string' || !RULE_KINDS.includes(rule.kind))
+      fail(`Rule ${rule.id} has unknown kind "${rule.kind}". Use one of: ${RULE_KINDS.join(', ')}.`);
+    if (
+      ['required-text', 'forbidden-text'].includes(String(rule.kind)) &&
+      (asArray(rule.text).length === 0 || !asArray(rule.text).every(isNonEmptyString))
+    ) {
+      fail(`Rule ${rule.id} (${rule.kind}) needs a non-empty "text".`);
+    }
+    if (rule.kind === 'required-link' && !isNonEmptyString(rule.href))
+      fail(`Rule ${rule.id} (required-link) needs an "href".`);
+    if (rule.kind === 'required-link' && /^(?!https?:)[a-z][a-z0-9+.-]*:/i.test(String(rule.href))) {
+      fail(`Rule ${rule.id} (required-link) supports paths and http(s) URLs; prove ${rule.href} in the browser pass.`);
+    }
+    for (const field of ['routes', 'allow']) {
+      if (rule[field] !== undefined && (!Array.isArray(rule[field]) || !rule[field].every(isNonEmptyString))) {
+        fail(`Rule ${rule.id} (${field}) needs an array of non-empty strings.`);
+      }
+    }
+    if (!isNonEmptyString(rule.source))
+      fail(`Rule ${rule.id} needs "source": cite the original page, file, or owner decision that imposes it.`);
+    const unknownScope = asArray(rule.routes)
+      .filter(isNonEmptyString)
+      .map(normalizePath)
+      .filter((route) => !routes.some((item) => normalizePath(item) === route));
+    if (unknownScope.length > 0) {
+      fail(
+        `Rule ${rule.id} is scoped to routes missing from the inventory: ${unknownScope.join(', ')}. A rule cannot be proven on a route that is never rendered.`
+      );
+    }
+  });
+  return { routes, rules: /** @type {Rule[]} */ (rules) };
+}
+
+/** @param {string[]} routes @param {string} capturesDir */
+function readCaptures(routes, capturesDir) {
+  return routes.map((route) => {
+    const name = captureFileName(route);
+    const file = path.join(capturesDir, name);
+    if (!fs.existsSync(file)) return observation(route, `capture missing: ${name}`, null);
+    // Status must come from the navigation response, never from HTML content.
+    try {
+      /** @type {unknown} */
+      const metadata = JSON.parse(fs.readFileSync(`${file}.json`, 'utf8'));
+      if (!isRecord(metadata) || metadata.status !== 200 || metadata.error != null) {
+        return observation(route, `capture rejected: ${name}.json must record status 200 and no error`, null);
+      }
+      if (!isNonEmptyString(metadata.url) || !/^https?:\/\//i.test(metadata.url)) {
+        return observation(route, `capture rejected: ${name}.json needs the final HTTP(S) document URL`, null);
+      }
+      const finalUrl = new URL(metadata.url).href;
+      const finalPath = normalizePath(new URL(finalUrl).pathname);
+      if (finalPath !== normalizePath(route)) {
+        return observation(
+          route,
+          `capture rejected: ${name}.json records ${finalPath}, not ${normalizePath(route)}`,
+          null
+        );
+      }
+      return observation(route, `capture ${name}`, fs.readFileSync(file, 'utf8'), finalUrl);
+    } catch (error) {
+      return observation(
+        route,
+        `capture evidence unreadable: ${name}.json: ${error instanceof Error ? error.message : String(error)}`,
+        null
+      );
+    }
+  });
+}
+
+// `/` -> index.html, `/legal/privacy` -> legal/privacy.html. The validator saves
+// the hydrated document under these names when it captures with a browser.
+/** @param {string} route */
+function captureFileName(route) {
+  route = normalizePath(route);
+  return route === '/' ? 'index.html' : `${route.replace(/^\//, '')}.html`;
+}
+
+/** @param {string[]} routes @param {string} baseUrl */
+async function fetchObservations(routes, baseUrl) {
+  const base = baseUrl.replace(/\/$/, '');
+  return Promise.all(
+    routes.map(async (route) => {
+      try {
+        const response = await fetch(`${base}${route}`, { redirect: 'follow' });
+        const body = await response.text();
+        if (response.status !== 200) {
+          return observation(route, `HTTP ${response.status} from ${base}${route}`, null);
+        }
+        const finalPath = normalizePath(new URL(response.url).pathname);
+        if (finalPath !== normalizePath(route)) {
+          return observation(
+            route,
+            `redirected to ${finalPath}: the route surface is not preserved`,
+            null,
+            response.url
+          );
+        }
+        return observation(route, `HTTP 200 from ${base}${route}`, body, response.url);
+      } catch (error) {
+        return observation(route, `request failed: ${error instanceof Error ? error.message : String(error)}`, null);
+      }
+    })
+  );
+}
+
+/** @param {string} route @param {string} source @param {string | null} html @param {string} [url] @returns {Observation} */
+function observation(route, source, html, url = '') {
+  const context = { route, source, url, baseUrl: url };
+  if (html === null) {
+    return { ...context, html: null, text: '', links: [], passed: false, reason: source };
+  }
+  const text = visibleText(html);
+  const links = extractLinks(html);
+  const baseHref = html
+    .replace(/<!--[^]*?-->/g, '')
+    .replace(/<(script|style|template)\b[^>]*>[^]*?<\/\1\s*>/gi, ' ')
+    .match(/<base\b[^>]*\s+href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/i);
+  if (baseHref) context.baseUrl = new URL(decodeEntities(baseHref[1] ?? baseHref[2] ?? baseHref[3]), url).href;
+  if (text.length === 0) {
+    return {
+      ...context,
+      html,
+      text,
+      links,
+      passed: false,
+      reason:
+        'rendered HTML has no visible text (an empty client-rendered root is not a page; capture after hydration)',
+    };
+  }
+  return {
+    ...context,
+    html,
+    text,
+    links,
+    passed: true,
+    reason: `${text.length} visible characters, ${links.length} links`,
+  };
+}
+
+// Visible text is body text plus the attributes a visitor or crawler reads:
+// alt, title, aria-label, placeholder, and meta content. Scripts, styles, and
+// comments are excluded on purpose: a brand string inside a bundle or JSON
+// payload is source presence, not a rendered observation.
+/** @param {string} html */
+function visibleText(html) {
+  const stripped = html
+    .replace(/<(script|style|noscript|template)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+  const attributeText = [
+    ...stripped.matchAll(/\b(?:alt|title|aria-label|placeholder|content)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi),
+  ].map((match) => match[1] ?? match[2] ?? '');
+  const bodyText = stripped.replace(/<[^>]+>/g, ' ');
+  return decodeEntities([bodyText, ...attributeText].join(' '))
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** @param {string} html */
+function extractLinks(html) {
+  const withoutHidden = html
+    .replace(/<(script|style|noscript|template)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+  return [...withoutHidden.matchAll(/<a\b[^>]*\s+href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/gi)].map((match) =>
+    decodeEntities(match[1] ?? match[2] ?? match[3] ?? '').trim()
+  );
+}
+
+/** @param {Inventory} inventory @param {Observation[]} observations */
+function evaluateRules(inventory, observations) {
+  const rendered = observations.filter((item) => item.passed);
+  return inventory.rules.map((rule) => {
+    const scope = rule.routes?.length ? rule.routes.map(normalizePath) : inventory.routes.map(normalizePath);
+    const observed = rendered.filter((item) => scope.includes(normalizePath(item.route)));
+    if (observed.length === 0) {
+      return result(rule, false, 0, [`vacuous: evaluated against 0 rendered routes (scope: ${scope.join(', ')})`]);
+    }
+    switch (rule.kind) {
+      case 'required-text':
+        return textRule(rule, observed, (haystack, phrase) => !haystack.includes(phrase), 'missing');
+      case 'forbidden-text':
+        return textRule(rule, observed, (haystack, phrase) => haystack.includes(phrase), 'found');
+      case 'required-link':
+        return linkRule(rule, observed);
+      case 'links-resolve':
+        return linksResolveRule(rule, inventory, observed);
+      default:
+        return result(rule, false, observed.length, [`unknown rule kind ${rule.kind}`]);
+    }
+  });
+}
+
+/** @param {Rule} rule @param {Observation[]} observed @param {(haystack: string, phrase: string) => boolean} isFailure @param {string} verb */
+function textRule(rule, observed, isFailure, verb) {
+  const failures = [];
+  for (const item of observed) {
+    const haystack = item.text.toLowerCase();
+    for (const phrase of phrases(rule)) {
+      const needle = phrase.toLowerCase();
+      if (isFailure(haystack, needle)) {
+        failures.push(
+          `"${phrase}" ${verb} on ${item.route}${verb === 'found' ? `: ${snippet(item.text, phrase)}` : ''}`
+        );
+      }
+    }
+  }
+  return result(rule, failures.length === 0, observed.length, failures);
+}
+
+/** @param {Rule} rule @param {Observation[]} observed */
+function linkRule(rule, observed) {
+  const failures = observed
+    .filter((item) => {
+      const target = linkTarget(rule.href ?? '', item, false);
+      return !target || !item.links.some((href) => linkTarget(href, item, false) === target);
+    })
+    .map((item) => `no <a href="${rule.href}"> rendered on ${item.route} (${item.links.length} links collected)`);
+  return result(rule, failures.length === 0, observed.length, failures);
+}
+
+// Every internal link rendered on the observed routes must point at a route
+// the inventory proves, or at an explicitly allowed path prefix. Collecting
+// zero links is a failure: a navigation check over nothing checks nothing.
+/** @param {Rule} rule @param {Inventory} inventory @param {Observation[]} observed */
+function linksResolveRule(rule, inventory, observed) {
+  const allow = asArray(rule.allow).filter(isNonEmptyString).map(normalizePath);
+  const internal = [];
+  for (const item of observed) {
+    for (const href of item.links) {
+      const target = linkTarget(href, item);
+      if (target !== null) internal.push({ route: item.route, href, target });
+    }
+  }
+  if (internal.length === 0) {
+    return result(rule, false, observed.length, [
+      `vacuous: 0 internal links collected across ${observed.length} rendered routes`,
+    ]);
+  }
+  const failures = uniqueArray(
+    internal
+      .filter(
+        ({ target }) =>
+          !inventory.routes.some((route) => normalizePath(route) === target) &&
+          !allow.some((prefix) => target === prefix || target.startsWith(`${prefix}/`))
+      )
+      .map(({ route, href }) => `${href} on ${route} resolves to no inventoried route`)
+  );
+  return result(rule, failures.length === 0, observed.length, failures, `${internal.length} internal links`);
+}
+
+/** @param {Rule} rule @param {boolean} passed @param {number} observed @param {string[]} failures @param {string} [extra] @returns {Result} */
+function result(rule, passed, observed, failures, extra) {
+  return { id: rule.id, kind: rule.kind, passed, observed, failures, extra: extra ?? null };
+}
+
+/** @param {{inventoryPath: string, inventory: Inventory, source: string, observations: Observation[], results: Result[], passed: boolean}} report */
+function buildReport({ inventoryPath, inventory, source, observations, results, passed }) {
+  const lines = [
+    '## Guardrails',
+    '',
+    `- Inventory: ${inventoryPath} (${inventory.routes.length} routes, ${inventory.rules.length} rules)`,
+    `- Observations: ${source}`,
+    '',
+    '### Rendered routes',
+    '',
+    ...observations.map((item) => `- ${box(item.passed)} ${item.route}: ${item.reason}`),
+    '',
+    '### Rules',
+    '',
+    ...results.flatMap((item) => [
+      `- ${box(item.passed)} ${item.id} (${item.kind}) observed on ${item.observed} routes${item.extra ? `, ${item.extra}` : ''}`,
+      ...item.failures.map((failure) => `  - ${failure}`),
+    ]),
+    '',
+    `Result: ${passed ? 'passed' : 'failed'}`,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+/** @param {Rule} rule */
+function phrases(rule) {
+  return asArray(rule.text ?? []).filter(isNonEmptyString);
+}
+
+/** @param {string} text @param {string} phrase */
+function snippet(text, phrase) {
+  const index = text.toLowerCase().indexOf(phrase.toLowerCase());
+  const start = Math.max(0, index - 40);
+  const end = Math.min(text.length, index + phrase.length + 40);
+  return `"${start > 0 ? '…' : ''}${text.slice(start, end)}${end < text.length ? '…' : ''}"`;
+}
+
+// Queries and fragments address the same route. Absolute and protocol-relative
+// URLs are internal only when their origin matches the observed document.
+/** @param {string} href @param {Observation} item @param {boolean} [internalOnly] @returns {string | null} */
+function linkTarget(href, item, internalOnly = true) {
+  try {
+    const url = new URL(href, item.baseUrl);
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    if (url.origin !== new URL(item.url).origin)
+      return internalOnly ? null : `${url.origin}${normalizePath(url.pathname)}`;
+    return normalizePath(url.pathname);
+  } catch {
+    return ''; // Invalid URLs cannot match an inventoried route.
+  }
+}
+
+/** @param {string} value */
+function normalizePath(value) {
+  const trimmed = value.trim();
+  if (trimmed === '' || trimmed === '/') return '/';
+  return `/${trimmed.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+
+/** @param {string} value */
+function decodeEntities(value) {
+  return value
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(Number.parseInt(code, 16)))
+    .replace(
+      /&(amp|lt|gt|quot|apos|nbsp);/g,
+      (_, name) =>
+        /** @type {Record<string, string>} */ ({ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' })[name]
+    );
+}
+
+/** @param {boolean} passed */
+function box(passed) {
+  return passed ? '[x]' : '[ ]';
+}
+
+/** @template T @param {T | T[]} value @returns {T[]} */
+function asArray(value) {
+  if (Array.isArray(value)) return value;
+  if (value === undefined || value === null) return [];
+  return [value];
+}
+
+/** @template T @param {T[]} items */
+function uniqueArray(items) {
+  return [...new Set(items)];
+}
+
+/** @param {unknown} value @returns {value is string} */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {string} value */
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+/** @param {string} message @returns {never} */
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+await main();

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-09-09T17:05:37.211Z",
+  "bundledAt": "2026-09-11T17:18:35.411Z",
   "cliVersion": "2.5.1",
   "external": [
     "oxc-parser",