@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/tools/pages/handlers-audit.js

@@ -1,714 +0,0 @@
-/**
- * `pages_audit` handler — Task 6 of the pages_audit implementation plan
- * (2026-07-19-04). Kept in its OWN file (not `handlers-read.ts`, already
- * 981 LoC) per the plan's explicit instruction.
- *
- * The handler is a thin REST-to-MCP adapter: `GET /pages/audit` already
- * returns the FULL, severity-sorted, deterministic sweep
- * ({@see \WootsUp\BuilderMcp\Pages\Audit\PageAuditService::audit()}); this
- * file only (a) forwards the optional filters as query params, (b) renders
- * a COMPACT truncate-tolerant text-leg table (never the raw JSON dump —
- * design §5), and (c) carries the complete, UNTRIMMED payload in
- * `structuredContent` via `structuredResult` (mirrors
- * `local-content/handlers.ts` — `applyMaxChars` only ever clips the text
- * leg, never `structuredContent`).
- *
- * @license MIT
- */
-import { tableResult } from '@getimo/mcp-toolkit';
-import { RestError } from '../../errors.js';
-import { applyMaxChars } from '../sparse-fields.js';
-import { errorResult, structuredResult } from '../tool-builder.js';
-import { appendTargetParams, isTypedTargetError, malformedTargetError, normalizeTarget, serverTooOldError, TARGET_FAILURE_HINT, targetKeysOf, tooManyTargetsError, typesConflictsWithTargetError, } from './target.js';
-const FINDINGS_COLUMNS = [
-    { key: 'severity', label: 'SEVERITY', width: 8 },
-    { key: 'code', label: 'CODE', width: 22 },
-    { key: 'category', label: 'CATEGORY', width: 10 },
-    { key: 'count', label: 'COUNT', width: 6, align: 'right' },
-    { key: 'title', label: 'TITLE', width: 44 },
-];
-/**
- * COUNT-COLUMN RULE (2026-07-22, cold-agent acceptance finding). The column
- * always answers *"how many of the unit this sweep counts"* — and the LABEL
- * names that unit, because the number alone is ambiguous:
- *
- * | scope    | label   | value                                     |
- * |----------|---------|-------------------------------------------|
- * | site     | `COUNT` | `finding.count` — affected PAGES          |
- * | `single` | `HITS`  | hits on that page ({@see hitCountOf})     |
- *
- * A single-page sweep scanned exactly ONE page, so the affected-page count is
- * structurally `1` for every finding and carries no information at all. A cold
- * agent auditing a page with 19 alt-less images read that `1` as "one image is
- * affected". Renaming the column in single mode (rather than silently swapping
- * the number under an unchanged header) is what makes the two readings
- * distinguishable.
- *
- * Site mode is deliberately byte-identical to before — pinned by
- * "locators NEVER enter the site-mode text leg" in `pages-audit.test.ts`.
- *
- * The KEY stays `count` in both modes: it is the machine-side row key that ties
- * `_meta.ui.payload.columns[]` to `_meta.ui.payload.data[]`, and `tableResult`
- * derives BOTH legs from this one column list, so text and Rich-Card can never
- * drift apart. `structuredContent.findings[].count` is NOT touched — that is a
- * published contract and stays page-based in every scope.
- */
-function findingsColumns(isSingleScope) {
-    if (!isSingleScope)
-        return [...FINDINGS_COLUMNS];
-    return FINDINGS_COLUMNS.map((col) => (col.key === 'count' ? { ...col, label: 'HITS' } : col));
-}
-/**
- * How many individual hits one finding represents on the page(s) it lists.
- *
- * Defensive by construction — every input here is host-supplied and may be
- * missing, capped or malformed, and the value is RENDERED, so it must never
- * come out as `undefined`/`NaN`:
- *   - no `pages` at all → fall back to `finding.count` (itself sanity-checked);
- *   - a page entry with no usable `count` → ONE hit (the page itself is the
- *     hit — that is exactly the shape `empty-page` & friends emit);
- *   - a non-integer / non-positive / non-numeric `count` → the same one-hit
- *     floor, never a negative or fractional cell.
- *
- * The sum runs over ALL listed pages. Single mode lists exactly one, so this is
- * that page's hit total; summing rather than reading `pages[0]` keeps the
- * function honest if a host ever scopes to a small group.
- */
-function hitCountOf(finding) {
-    if (finding.pages.length === 0) {
-        return Number.isFinite(finding.count) && finding.count > 0 ? Math.trunc(finding.count) : 0;
-    }
-    return finding.pages.reduce((total, page) => {
-        // NAME-2: prefer the unambiguous `hits` alias when the host sends it —
-        // a page entry's `count` is a hit tally only SOMETIMES (a finding whose
-        // unit is the page itself carries no hit count), and `hits` is emitted
-        // exactly when it is one. An older host sends only `count`, so it stays
-        // the fallback; neither present means the page IS the single hit.
-        const raw = typeof page.hits === 'number' ? page.hits : page.count;
-        const usable = typeof raw === 'number' && Number.isFinite(raw) && raw >= 1;
-        return total + (usable ? Math.trunc(raw) : 1);
-    }, 0);
-}
-/**
- * PHP already normalizes an empty sweep's `by_type` to `(object) []`
- * (`{}` over the wire — see `PageAuditService::audit()`), so this is
- * belt-and-braces against an older/partial host that still emits the
- * empty-array shape `template_summary` hit before its own Friction-3 fix.
- */
-function normalizeByType(value) {
-    return Array.isArray(value) ? {} : value;
-}
-/**
- * How many locators ONE finding may render into the TEXT leg before the rest
- * is summarised (2026-07-22 review finding 3).
- *
- * This budget is UNCONDITIONAL, and it has to be: `max_chars` is `.optional()`
- * with no default, `applyMaxChars(result, undefined)` returns the result
- * untouched, and agents rarely pass it. Single mode meanwhile raises the host's
- * `hit_cap` to 100 across five locator-emitting checks, so a pathological page
- * could render ~500 locator blocks ≈ 75 KB of prose in one tool result.
- *
- * Per FINDING, not per response: each finding is a different problem the agent
- * has to act on, and 15 examples are enough to characterise any one of them.
- * `structuredContent` is never affected — it keeps every locator, which is what
- * the remainder line points at.
- */
-const LOCATOR_LINES_PER_FINDING = 15;
-/**
- * PERF-4 / PROD-2 — the DEFAULT ceiling (chars of serialised JSON) on the
- * `structuredContent` leg of one `pages_audit` result.
- *
- * There was NO ceiling at all: `applyMaxChars` clips only `content[0].text`
- * (it says so in its own docblock), `max_chars` has no default, and the
- * projection forwarded `findings` verbatim. Measured on this transport: **349.1
- * KB (~89k tokens)** for a site sweep and **193.9 KB (~50k tokens)** for ONE
- * busy page — against 12,000 chars for the identical request on the in-process
- * native transport. A single tool result could eat most of a context window.
- *
- * WHY 48,000 and not the native handler's 12,000:
- *
- *   - The two transports carry DIFFERENT things under that number. Native emits
- *     ONE payload — the audit JSON rendered as the text the model reads — so
- *     12,000 chars is the whole result. Here the legs are separate: the text leg
- *     is independently bounded ({@link LOCATOR_LINES_PER_FINDING} = 15 locators
- *     per finding) and `structuredContent` is the MACHINE leg an agent drills
- *     into for the exact paths it is about to write to. Sharing one constant
- *     across that boundary would make each transport's budget wrong for the
- *     other's payload.
- *   - 48,000 chars ≈ 12k tokens at 4 chars/token — a bounded, predictable slice
- *     of a context window, and still a ~7× cut from the measured 349 KB.
- *   - It is above every realistic SINGLE-page audit (the headline case: ~100
- *     hits × ~250 chars of locator ≈ 25 KB), so the capability that motivated
- *     locators is never shed on a normal page — only pathological ones degrade.
- *
- * `max_chars` overrides it in BOTH directions (the schema's range is
- * 200…100,000), which is why the `max_chars` describe on THIS tool states that
- * it bounds both legs while the shared one still says text-only.
- */
-export const STRUCTURED_BUDGET_CHARS = 48_000;
-/**
- * Safety cap on the halving loops — mirrors PHP `MAX_SHRINK_ITERATIONS`.
- * A loop also exits on its own once there is nothing left to halve.
- */
-const MAX_SHRINK_ITERATIONS = 8;
-/**
- * The per-page-entry keys the evidence rung KEEPS — mirrors
- * `McpPagesAuditHandler::PAGE_IDENTITY_KEYS`, and is pinned against the value
- * PHP derives from its own constant by
- * `tests/contracts/audit-shrink-ladder.test.ts`.
- *
- * An allow-list, not a drop-list, on purpose: evidence keys are check-SPECIFIC
- * (`paths`, `alt_paths`, `anchors`, `generic_alts`, `skips`, `dead_anchors`,
- * `long_headings`, `first_headline_path`, `cluster_id`, `iterated`, …) and a
- * new check on the HOST adds new ones this package has never heard of. A
- * drop-list would silently stop shedding the day a host ships one; an
- * allow-list keeps identity + counts protected by construction.
- */
-export const PAGE_IDENTITY_KEYS = [
-    'id',
-    'label',
-    'count',
-    'hits',
-    'builder_url',
-    'locators',
-    'locators_stripped',
-    'hits_truncated',
-    'evidence_stripped',
-];
-/**
- * BUGS-2 — the raw per-hit evidence arrays that are a PROVABLE DUPLICATE of the
- * locators riding on the same page entry, and may therefore be shed BEFORE a
- * single locator is thinned. Mirrors
- * `McpPagesAuditHandler::REDUNDANT_EVIDENCE_KEYS`; same contract test pins it.
- *
- * "Provable" means every field the array element carries also rides on the
- * locator built from the SAME hit, host-side in `AuditCheckRegistry`:
- * `paths` → path (+ the locator adds heading_source + repeat, which a bare
- * pointer cannot express), `alt_paths` → path (+ prop), `dead_anchors` →
- * {path,name}, `anchors` → {path,reason,text}, `generic_alts` →
- * {path,prop,text}, `long_headings` → {path,length}.
- *
- * DELIBERATELY ABSENT: `skips` (heading-skip). Its elements are
- * `{path, from, to}` and that check builds its locator with no from/to rider,
- * so the jumped heading levels ride on that array and nothing else. It is shed
- * by the allow-list rung instead.
- *
- * Being a DROP-list this one is allowed to be incomplete — a new host check's
- * array simply is not shed EARLY, and the allow-list rung behind it still sheds
- * everything. Opposite failure modes on purpose: this one under-sheds, the
- * other cannot.
- */
-export const REDUNDANT_EVIDENCE_KEYS = [
-    'paths',
-    'alt_paths',
-    'dead_anchors',
-    'anchors',
-    'generic_alts',
-    'long_headings',
-];
-/** The serialised size the host actually transmits for `structuredContent`. */
-function encodedLength(payload) {
-    return JSON.stringify(payload).length;
-}
-/** Rebuild one page entry, keeping only the keys `keep` accepts, in order. */
-function pickPageKeys(page, keep) {
-    // `id`/`label` are seeded first so the result provably satisfies the
-    // interface's two required members — no cast has to be taken on faith.
-    const kept = { id: page.id, label: page.label };
-    for (const [key, value] of Object.entries(page)) {
-        if (keep(key))
-            kept[key] = value;
-    }
-    return kept;
-}
-/**
- * Shrink stage 1 (BUGS-2) — drop the {@link REDUNDANT_EVIDENCE_KEYS} arrays
- * from every page entry that carries LOCATORS to duplicate them, flagging
- * `evidence_stripped: true` on each entry actually shortened.
- *
- * These are the only bytes in the payload that cost something and carry
- * nothing, so they go before anything else. Shedding the locators FIRST — which
- * both ladders used to do — spends budget on the copy while discarding the
- * original, richer data: the same hit's breadcrumb, element name and snippet.
- *
- * The `locators` gate is load-bearing, not defensive decoration. This handler
- * consumes a REMOTE host's payload, and a host predating B-3 emits no
- * `locators` key at all; there `alt_paths` IS the evidence, exactly as `skips`
- * is. Nothing is a duplicate then, so those entries fall through to the
- * allow-list rung untouched and the arrays degrade together.
- */
-function stripRedundantEvidence(findings) {
-    return findings.map((finding) => ({
-        ...finding,
-        pages: finding.pages.map((page) => {
-            if (!Array.isArray(page.locators) || page.locators.length === 0)
-                return page;
-            const hasRedundant = REDUNDANT_EVIDENCE_KEYS.some((key) => key in page);
-            if (!hasRedundant)
-                return page;
-            return {
-                ...pickPageKeys(page, (key) => !REDUNDANT_EVIDENCE_KEYS.includes(key)),
-                evidence_stripped: true,
-            };
-        }),
-    }));
-}
-/** The largest `locators` list on any page entry — the halving base for stage 2a. */
-function largestLocatorCount(findings) {
-    let largest = 0;
-    for (const finding of findings) {
-        for (const page of finding.pages) {
-            if (Array.isArray(page.locators))
-                largest = Math.max(largest, page.locators.length);
-        }
-    }
-    return largest;
-}
-/**
- * Shrink stage 2a (PROD-1) — TRIM every page entry's `locators` list to `cap`,
- * flagging `locators_stripped: true` on each entry actually shortened.
- *
- * Emptying the whole list the moment the payload is one char over is a cliff: a
- * page at the host's single-target `hit_cap` of 100 sits just above the budget,
- * and losing 100% of the evidence to save 5% of the bytes is a bad trade.
- * Halving (like the page rung below) sheds the smallest amount that fits.
- *
- * The flag carries ONE meaning — "the transport shed locator prose to fit its
- * budget" — equally true of a partial and a total shed, so a reader can never
- * mistake a trimmed list for the complete one.
- */
-function capLocators(findings, cap) {
-    return findings.map((finding) => ({
-        ...finding,
-        pages: finding.pages.map((page) => {
-            if (!Array.isArray(page.locators))
-                return page;
-            if (page.locators.length <= cap)
-                return page;
-            return { ...page, locators: page.locators.slice(0, cap), locators_stripped: true };
-        }),
-    }));
-}
-/**
- * Shrink stage 2b — EMPTY every page entry's `locators`, flagging
- * `locators_stripped: true` wherever locators were actually dropped.
- *
- * Emptied, NOT removed: an ABSENT `locators` key means "this host predates B-3
- * and cannot produce locators", whereas `locators: []` + `locators_stripped:
- * true` says the honest thing — the hits exist, they were too expensive to
- * transmit, and re-running the audit scoped to that one page returns them.
- * `builder_url` stays: one short string, and it is the caller's way BACK to the
- * hits this stage dropped.
- *
- * `hits_truncated` is deliberately untouched — it means the HOST's `hit_cap`
- * dropped hits (so the raw `paths`/`alt_paths`/… arrays are incomplete), which
- * is a different fact from the transport shedding prose. Two causes, two flags
- * (the same separation the PHP stage documents).
- */
-function stripLocators(findings) {
-    return findings.map((finding) => ({
-        ...finding,
-        pages: finding.pages.map((page) => {
-            if (!Array.isArray(page.locators))
-                return page;
-            if (page.locators.length === 0)
-                return page;
-            return { ...page, locators: [], locators_stripped: true };
-        }),
-    }));
-}
-/**
- * Shrink stage 3 (PROD-1) — reduce every page entry to
- * {@link PAGE_IDENTITY_KEYS}: its identity, hit totals, shed flags and
- * `builder_url`. Entries actually shortened are flagged
- * `evidence_stripped: true`.
- *
- * What reaches this rung is the evidence stage 1 could NOT prove redundant
- * (`skips`' `{from, to}`, `cluster_id`, whatever a newer host ships) plus, on a
- * locator-less host, everything. With the prose already gone there is no richer
- * copy left to prefer, and identity + counts are still worth more than any of
- * it: an entry naming the page, its hit total and its `builder_url` is
- * actionable; one carrying only `{from, to}` is not.
- *
- * `hits_truncated` is kept and never touched — it reports the HOST's `hit_cap`,
- * not a transport shed.
- */
-function stripPageEvidence(findings) {
-    return findings.map((finding) => ({
-        ...finding,
-        pages: finding.pages.map((page) => {
-            const kept = pickPageKeys(page, (key) => PAGE_IDENTITY_KEYS.includes(key));
-            if (Object.keys(kept).length === Object.keys(page).length)
-                return page;
-            return { ...kept, evidence_stripped: true };
-        }),
-    }));
-}
-/** Shrink stage 4 — cap every finding's evidence `pages` at `cap`. */
-function applyPageCap(findings, cap) {
-    return findings.map((finding) => finding.pages.length > cap
-        ? { ...finding, pages: finding.pages.slice(0, cap), pages_truncated: true }
-        : finding);
-}
-/** Shrink final stage — counts-only: bounded regardless of the site's size. */
-function stripPages(findings) {
-    return findings.map((finding) => finding.pages.length > 0 ? { ...finding, pages: [], pages_truncated: true } : finding);
-}
-/**
- * PERF-4 / PROD-2 — bring `structuredContent` under `budget`, shedding in the
- * SAME ORDER as `McpPagesAuditHandler::shrinkToFit()` so the two transports
- * degrade identically rather than each inventing a policy:
- *
- *   0.  as received (the host already caps evidence pages at 30/finding);
- *   1.  the DUPLICATE raw evidence arrays ({@link stripRedundantEvidence}) —
- *       free bytes: every field also rides on a locator of the same hit;
- *   2a. THIN the locator prose by halving ({@link capLocators});
- *   2b. shed the prose entirely ({@link stripLocators}) — re-derivable by
- *       re-auditing that one page;
- *   3.  the REMAINING raw evidence ({@link stripPageEvidence}), keeping each
- *       entry's identity + counts;
- *   4.  halve every finding's page cap, repeatedly, until it fits or no finding
- *       has more than one page left;
- *   5.  counts-only — drop `pages` entirely, flagging `pages_truncated`.
- *
- * The order encodes what is worth protecting LAST: a dropped locator can be
- * recovered with one scoped re-run, a dropped page id is simply invisible.
- * Shedding stops the moment the payload fits, so a result 1 char over loses
- * only the duplicate, never a page.
- *
- * THE PARITY CLAIM ABOVE IS ENFORCED, NOT ASSERTED (PERF-5 / MM-2 / QUAL-1).
- * This docblock used to make it while the ladder had rungs 1, 2a and 3 missing:
- * PHP grew them in c8fe86acb and this file was never revisited, so on one
- * identical 90,825-byte payload the native transport kept 18 locators and this
- * one kept 0 — while the prose said "degrade identically" and SKILL.md
- * documented an `evidence_stripped` rung this transport could never emit.
- * `tests/contracts/audit-shrink-ladder.test.ts` now DERIVES the rung order from
- * this function by driving it over the shared fixture at a sweep of budgets and
- * compares it with the order PHP derives from its own handler, so a rung added
- * on one side alone goes red instead of shipping.
- *
- * The BUDGETS stay deliberately separate (see {@link STRUCTURED_BUDGET_CHARS}):
- * the two legs carry different things. The two agree on the shed ORDER — a
- * contract — not on a magic number.
- */
-function shrinkStructured(envelope, findings, budget) {
-    // Every stage after the first EMITS `structured_truncated`, so its own bytes
-    // are counted against the budget it certifies — otherwise the marker could
-    // push a payload that "fits" back over the line it was measured against.
-    const fits = (candidate, marked) => encodedLength({
-        ...envelope,
-        findings: candidate,
-        ...(marked ? { structured_truncated: true } : {}),
-    }) <= budget;
-    if (fits(findings, false))
-        return { findings, shrunk: false };
-    let current = stripRedundantEvidence(findings);
-    if (fits(current, true))
-        return { findings: current, shrunk: true };
-    for (let i = 0; i < MAX_SHRINK_ITERATIONS; i += 1) {
-        const largest = largestLocatorCount(current);
-        if (largest <= 1)
-            break;
-        current = capLocators(current, Math.max(1, Math.trunc(largest / 2)));
-        if (fits(current, true))
-            return { findings: current, shrunk: true };
-    }
-    current = stripLocators(current);
-    if (fits(current, true))
-        return { findings: current, shrunk: true };
-    current = stripPageEvidence(current);
-    if (fits(current, true))
-        return { findings: current, shrunk: true };
-    for (let i = 0; i < MAX_SHRINK_ITERATIONS; i += 1) {
-        const largest = current.reduce((max, f) => Math.max(max, f.pages.length), 0);
-        if (largest <= 1)
-            break;
-        current = applyPageCap(current, Math.max(1, Math.trunc(largest / 2)));
-        if (fits(current, true))
-            return { findings: current, shrunk: true };
-    }
-    return { findings: stripPages(current), shrunk: true };
-}
-/**
- * A-6 — render the per-hit LOCATOR prose for a SINGLE-target sweep.
- *
- * Only reached when the host answered `scope:'single'`. The SITE sweep
- * deliberately gets NONE of this — see the text-leg rule below.
- *
- * Rendered from the ORIGINAL (un-shrunk) findings: the text leg carries its own
- * budget and a human reading it must see the true evidence. `structuredComplete`
- * only changes where the remainder line POINTS — promising "the complete list in
- * structuredContent" after that leg was shrunk would be a lie.
- *
- * Returns `''` when nothing has locators, so a host predating B-3 (or a clean
- * page) never gets an empty, confusing section header.
- */
-function renderLocatorDetail(findings, structuredComplete) {
-    const lines = [];
-    for (const finding of findings) {
-        const pagesWithLocators = finding.pages.filter((p) => Array.isArray(p.locators) && p.locators.length > 0);
-        if (pagesWithLocators.length === 0)
-            continue;
-        lines.push(`${finding.code} — ${finding.title}`);
-        let budget = LOCATOR_LINES_PER_FINDING;
-        let omitted = 0;
-        for (const page of pagesWithLocators) {
-            const locators = page.locators ?? [];
-            if (budget === 0) {
-                // Budget already spent on an earlier page of this finding —
-                // count the rest rather than printing a header with no entries.
-                omitted += locators.length;
-                continue;
-            }
-            const builder = typeof page.builder_url === 'string' && page.builder_url !== ''
-                ? ` — open in builder: ${page.builder_url}`
-                : '';
-            lines.push(`  ${page.label} (${page.id})${builder}`);
-            for (const locator of locators) {
-                if (budget === 0) {
-                    omitted += 1;
-                    continue;
-                }
-                budget -= 1;
-                // `breadcrumb · element_name · heading_source` — the three facts
-                // a human needs to FIND the element in the customizer. Absent
-                // members are dropped rather than rendered as "null".
-                const parts = [
-                    locator.breadcrumb,
-                    typeof locator.element_name === 'string' && locator.element_name !== ''
-                        ? locator.element_name
-                        : locator.element_type,
-                    typeof locator.heading_source === 'string' && locator.heading_source !== ''
-                        ? locator.heading_source
-                        : undefined,
-                ].filter((p) => typeof p === 'string' && p !== '');
-                const repeat = locator.repeat > 1 ? ` ×${String(locator.repeat)}` : '';
-                lines.push(`    • ${parts.join(' · ')}${repeat}`);
-                if (typeof locator.content_snippet === 'string' && locator.content_snippet !== '') {
-                    lines.push(`      "${locator.content_snippet}"`);
-                }
-            }
-            if (page.hits_truncated === true) {
-                lines.push('    … more hits exist on this page (hits_truncated).');
-            }
-            if (page.locators_stripped === true) {
-                lines.push('    … locator detail was shed to fit (locators_stripped).');
-            }
-        }
-        if (omitted > 0) {
-            lines.push(`    … ${String(omitted)} more locator${omitted === 1 ? '' : 's'} for this ` +
-                (structuredComplete
-                    ? 'finding (complete list in structuredContent).'
-                    : 'finding (structuredContent was shrunk too — raise max_chars for the full list).'));
-        }
-    }
-    if (lines.length === 0)
-        return '';
-    return ['Where to fix:', ...lines].join('\n');
-}
-/**
- * Splice `detail` into an already-built text leg, BEFORE the trailing
- * `<!-- structured-meta:... -->` marker the toolkit appends (that marker is a
- * machine rider; prose belongs above it).
- */
-function appendDetailText(result, detail) {
-    if (detail === '')
-        return result;
-    const first = result.content[0];
-    if (first === undefined || first.type !== 'text' || typeof first.text !== 'string') {
-        return result;
-    }
-    const markerAt = first.text.indexOf('\n<!-- structured-meta:');
-    const text = markerAt === -1
-        ? `${first.text}\n\n${detail}`
-        : `${first.text.slice(0, markerAt)}\n\n${detail}\n${first.text.slice(markerAt + 1)}`;
-    return { ...result, content: [{ ...first, text }, ...result.content.slice(1)] };
-}
-export async function handlePagesAudit(client, { mode, types, checks, thin_content_threshold, stale_after_months, max_chars, target, include_meta }) {
-    // A-6 / F205: exactly-one-of lives HERE, not in a zod `.refine` — an
-    // SDK-level rejection surfaces as a raw -32602 with none of this steering.
-    const resolvedTarget = normalizeTarget(target);
-    // BUG-4: a target bag that survived nothing is a MALFORMED ADDRESS, not an
-    // absent one. Checked FIRST (mirroring the PHP controllers' ordering)
-    // because the alternative is a full site sweep answered 200 and read as the
-    // audit of one page.
-    const malformed = malformedTargetError(target, resolvedTarget, {
-        context: { target: target ?? null, types: types ?? null },
-        hint: 'Each target member must be a non-empty string or number — e.g. '
-            + 'target:{special:"home"} or target:{template_id:"page:4816"}. Omit `target` '
-            + 'entirely to audit the whole site.',
-    });
-    if (malformed !== null)
-        return malformed;
-    const suppliedKeys = targetKeysOf(resolvedTarget);
-    if (suppliedKeys.length > 1) {
-        return tooManyTargetsError({
-            supplied: suppliedKeys,
-            context: { target: resolvedTarget, types: types ?? null },
-        });
-    }
-    const hasTarget = suppliedKeys.length === 1;
-    // Key decision 11 — `types` narrows a SITE sweep; a target already names
-    // exactly one page. Refusing here (rather than letting PHP 400 it) keeps the
-    // agent out of the generic catch's "run diagnose" hint, which would blame
-    // connectivity for a request-shape clash, and saves the round-trip.
-    if (hasTarget && types !== undefined && types.length > 0) {
-        return typesConflictsWithTargetError({
-            context: { target: resolvedTarget, types: [...types] },
-        });
-    }
-    try {
-        const qs = new URLSearchParams();
-        appendTargetParams(qs, resolvedTarget);
-        if (mode !== undefined)
-            qs.set('mode', mode);
-        if (types !== undefined && types.length > 0)
-            qs.set('types', types.join(','));
-        if (checks !== undefined && checks.length > 0)
-            qs.set('checks', checks.join(','));
-        if (typeof thin_content_threshold === 'number') {
-            qs.set('thin_content_threshold', String(thin_content_threshold));
-        }
-        if (typeof stale_after_months === 'number') {
-            qs.set('stale_after_months', String(stale_after_months));
-        }
-        const query = qs.toString();
-        const data = await client.get(`/pages/audit${query !== '' ? `?${query}` : ''}`);
-        // A-6 VERSION-SKEW GUARD (blocker-class). A host plugin predating
-        // single-target addressing IGNORES the unknown `target[...]` query
-        // params and answers HTTP 200 with a FULL SITE SWEEP. The existing 404
-        // gate does not cover this (it only fires when the route is absent), so
-        // returning `data` here would present whole-site findings as "the audit
-        // of your homepage" — wrong findings attributed to the wrong page. We
-        // therefore require POSITIVE proof of scoping and never fall back to
-        // the sweep.
-        if (hasTarget && data.scope !== 'single') {
-            return serverTooOldError({
-                message: 'The site answered a single-target audit with an UNSCOPED result ' +
-                    `(scope: ${data.scope === undefined ? 'absent' : JSON.stringify(data.scope)}, ` +
-                    `${String(data.scanned.templates)} templates scanned). Refusing to report a ` +
-                    'site-wide sweep as a single-page audit.',
-                context: { target: resolvedTarget, scope: data.scope ?? null },
-            });
-        }
-        const findings = data.findings;
-        const byType = normalizeByType(data.scanned.by_type);
-        // Single mode counts HITS, site mode counts PAGES — see the
-        // COUNT-COLUMN RULE on `findingsColumns`. Both the text table and the
-        // `_meta.ui` data-table are built from these two values by
-        // `tableResult`, so the label and the number cannot disagree.
-        const isSingleScope = data.scope === 'single';
-        const rows = findings.map((f) => ({
-            severity: f.severity,
-            code: f.code,
-            category: f.category,
-            count: isSingleScope ? hitCountOf(f) : f.count,
-            title: f.title,
-        }));
-        // TEXT-LEG RULE (B-5, pinned by a test): the SITE-sweep text leg is
-        // and stays this 5-column summary table. Per-hit LOCATORS — breadcrumb,
-        // element name, snippet, builder_url — are structuredContent-ONLY: a
-        // site sweep can carry dozens of findings × 30 evidence pages × N hits,
-        // and inlining that prose would blow the text budget and force
-        // `applyMaxChars` to clip the table itself. Do NOT render locators here.
-        //
-        // A-6: a SINGLE-target sweep is the one exception — one page, bounded
-        // hits — and gets the locator prose spliced in below (Key decision 8).
-        const toolkitResult = tableResult(rows, {
-            columns: findingsColumns(isSingleScope),
-            header: (count) => `${String(count)} finding${count === 1 ? '' : 's'} — ` +
-                `${String(data.summary.critical)} critical / ` +
-                `${String(data.summary.warning)} warning / ` +
-                `${String(data.summary.info)} info ` +
-                `(scanned ${String(data.scanned.templates)} templates, etag ${data.etag})`,
-            footer: `${data.disclaimer} Drill into a flagged page with ` +
-                'yootheme_builder_template_summary({ template_id }); apply a fix via the ' +
-                "finding's fix_hint (e.g. element_update_settings), one page at a time.",
-            includeMeta: include_meta,
-        });
-        // The projection is rebuilt FIELD BY FIELD, so a top-level field the
-        // host starts sending is silently DROPPED unless it is named here
-        // (`findings` passes through verbatim, which is why per-page locators
-        // survive on their own). `scope`/`note`/`resolved_target` are forwarded
-        // ONLY when the host actually sent them — a site sweep and every host
-        // predating single-target mode omit all three, and inventing defaults
-        // would make an old server look like it answered a scoped audit.
-        const envelope = {
-            etag: data.etag,
-            ...(data.scope !== undefined ? { scope: data.scope } : {}),
-            ...(data.note !== undefined ? { note: data.note } : {}),
-            ...(data.resolved_target !== undefined ? { resolved_target: data.resolved_target } : {}),
-            scanned: { templates: data.scanned.templates, by_type: byType },
-            summary: { ...data.summary },
-            disclaimer: data.disclaimer,
-            // T-A2 — forwarded only when the host actually sent them (a
-            // builder-mode sweep and every host predating rendered mode omit
-            // all three, same "absent means the old behaviour" convention as
-            // scope/note/resolved_target above).
-            ...(data.mode !== undefined ? { mode: data.mode } : {}),
-            ...(data.render_scan !== undefined ? { render_scan: data.render_scan } : {}),
-            ...(data.render_errors !== undefined ? { render_errors: data.render_errors } : {}),
-        };
-        // PERF-4 / PROD-2: bound the MACHINE leg. `max_chars` overrides the
-        // default in both directions; the ladder is a no-op when the payload
-        // already fits, so a normal audit is byte-identical to before.
-        const budget = max_chars ?? STRUCTURED_BUDGET_CHARS;
-        const shrunk = shrinkStructured(envelope, findings, budget);
-        // The text leg is built from the ORIGINAL findings — its own budget is
-        // independent (15 locators/finding), and rewriting the numbers a human
-        // reads because the machine leg was shed would be the silent-swap the
-        // COUNT-COLUMN RULE exists to prevent.
-        const detail = [
-            isSingleScope ? renderLocatorDetail(findings, !shrunk.shrunk) : '',
-            shrunk.shrunk
-                ? `Note: structuredContent exceeded its ${String(budget)}-char budget and was `
-                    + 'shrunk (duplicate raw evidence first, then locator detail, then the remaining '
-                    + 'evidence, then whole pages — flagged per entry as evidence_stripped / '
-                    + 'locators_stripped / pages_truncated). Raise max_chars, or re-run scoped to '
-                    + 'one page with target:{…}, for the complete payload.'
-                : '',
-        ]
-            .filter((part) => part !== '')
-            .join('\n\n');
-        const textLeg = appendDetailText(toolkitResult, detail);
-        return structuredResult(applyMaxChars(textLeg, max_chars), {
-            ...envelope,
-            findings: shrunk.findings,
-            // Never invented on a complete payload — its PRESENCE is the signal.
-            ...(shrunk.shrunk ? { structured_truncated: true } : {}),
-        });
-    }
-    catch (e) {
-        const context = { types: types ?? null, checks: checks ?? null, target: resolvedTarget };
-        // BUG-3 / MM-5 — a TYPED `yootheme_builder_mcp.pages.*` failure answers
-        // the ADDRESS, not the connection. It must be tested FIRST, because four
-        // of its members are 404s (`title_no_match`, `special_not_resolvable`,
-        // `url_no_match`, `template_not_found`) that the capability gate below
-        // would otherwise mis-report as "your plugin predates pages_audit" — a
-        // false claim, actionable in the wrong direction. The server's own
-        // message rides through `errorResult` unchanged; only the HINT is ours,
-        // and it is the SAME string `pages_resolve` already used for this family
-        // so one error family cannot read two ways depending on which sibling
-        // tool the agent happened to call.
-        if (hasTarget && isTypedTargetError(e)) {
-            return errorResult({ error: e, context, hint: TARGET_FAILURE_HINT });
-        }
-        if (e instanceof RestError && e.status === 404) {
-            return errorResult({
-                error: e,
-                context,
-                hint: 'GET /pages/audit was not found on this site — the yt-builder-mcp host ' +
-                    'plugin predates pages_audit (added in 1.10.0). Update the plugin on this ' +
-                    'site, then retry.',
-            });
-        }
-        // Everything left is a genuine transport / auth / server failure — the
-        // one case the diagnose steer is actually for.
-        return errorResult({
-            error: e,
-            context,
-            hint: 'Run yootheme_builder_diagnose to verify auth + that the host plugin is reachable.',
-        });
-    }
-}
-//# sourceMappingURL=handlers-audit.js.map