nfunc-mcp 0.2.0 → 0.4.0

package/dist/utils/httpClient.js

@@ -0,0 +1,171 @@
+/**
+ * HTTP counterpart to shellRunner.
+ *
+ * Every tool before this one reached the outside world by spawning a process,
+ * so `runShell` was the single choke point for timeout, error and duration
+ * handling. PSI is an HTTP API, and bending shellRunner around `curl` would
+ * trade a typed response for string parsing. This mirrors shellRunner's
+ * contract instead: never throws for a reachable-but-unhappy endpoint, always
+ * reports duration, and leaves the decision about what counts as failure to
+ * the caller.
+ *
+ * Node 18+ ships global fetch, so this adds no dependency.
+ */
+/**
+ * Sites behind a bot wall reject the default Node fetch agent outright, which
+ * turns a healthy site into a 403 and a sitemap into a "not found". Naming
+ * ourselves honestly and looking like a browser gets through most of them;
+ * a caller can override it via `headers`.
+ */
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36 nfunc-mcp/qa-audit";
+/** Query parameters whose values are stripped before a URL is quoted anywhere. */
+const SENSITIVE_PARAMS = new Set(["key", "api_key", "apikey", "token", "access_token"]);
+/**
+ * A URL safe to put in an error message.
+ *
+ * The PSI request URL carries the API key in the query string, so any error
+ * that interpolates the URL leaks the key into the tool response — and from
+ * there into the conversation transcript. Redacting at the point of formatting
+ * rather than asking every call site to remember is the only version of this
+ * that stays correct.
+ */
+export function sanitizeUrl(url) {
+    try {
+        const u = new URL(url);
+        for (const param of u.searchParams.keys()) {
+            if (SENSITIVE_PARAMS.has(param.toLowerCase())) {
+                u.searchParams.set(param, "REDACTED");
+            }
+        }
+        return u.toString();
+    }
+    catch {
+        return "[unparseable url]";
+    }
+}
+function redactAll(message, secrets) {
+    let out = message;
+    for (const secret of secrets) {
+        // A short "secret" would redact half the message; a real key is far longer.
+        if (secret && secret.length >= 8)
+            out = out.split(secret).join("REDACTED");
+    }
+    return out;
+}
+/** Retry only what a retry can plausibly fix. A 400 will be a 400 next time too. */
+function isRetryable(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/**
+ * `Retry-After` is either a delay in seconds or an HTTP date. Google sends
+ * seconds on 429s, but the date form is legal and cheap to support.
+ */
+function retryAfterMs(header) {
+    if (!header)
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - Date.now());
+    return null;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function httpGet(url, options = {}) {
+    const { timeoutMs = 60_000, retries = 2, retryDelayMs = 2_000, headers, raw = false, totalBudgetMs, retryOnTimeout = false, redact = [], } = options;
+    const start = Date.now();
+    const safeUrl = sanitizeUrl(url);
+    let lastError = "";
+    let lastStatus = 0;
+    const deadline = totalBudgetMs === undefined ? null : start + totalBudgetMs;
+    const remainingMs = () => (deadline === null ? Infinity : deadline - Date.now());
+    for (let attempt = 1; attempt <= retries + 1; attempt++) {
+        const budgetLeft = remainingMs();
+        if (budgetLeft <= 0) {
+            lastError = lastError || `Request to ${safeUrl} ran out of time budget`;
+            break;
+        }
+        try {
+            const response = await fetch(url, {
+                headers: { "user-agent": DEFAULT_USER_AGENT, ...headers },
+                signal: AbortSignal.timeout(Math.min(timeoutMs, budgetLeft)),
+            });
+            lastStatus = response.status;
+            if (response.ok) {
+                const bytes = new Uint8Array(await response.arrayBuffer());
+                return {
+                    ok: true,
+                    status: response.status,
+                    body: raw ? "" : new TextDecoder().decode(bytes),
+                    ...(raw ? { bytes } : {}),
+                    durationMs: Date.now() - start,
+                    attempts: attempt,
+                };
+            }
+            // Read the body before deciding — a non-2xx from PSI carries a JSON
+            // error object that says far more than the status code does.
+            const body = await response.text().catch(() => "");
+            lastError = `HTTP ${response.status} from ${safeUrl}${body ? `: ${body.slice(0, 300)}` : ""}`;
+            if (!isRetryable(response.status) || attempt > retries) {
+                return {
+                    ok: false,
+                    status: response.status,
+                    body,
+                    durationMs: Date.now() - start,
+                    attempts: attempt,
+                    error: redactAll(lastError, redact),
+                };
+            }
+            const serverAsked = retryAfterMs(response.headers.get("retry-after"));
+            const backoff = Math.min(serverAsked ?? retryDelayMs * 2 ** (attempt - 1), Math.max(0, remainingMs()));
+            await sleep(backoff);
+        }
+        catch (err) {
+            // Timeouts and network failures land here. AbortSignal.timeout raises a
+            // TimeoutError, which reads as an unexplained abort unless named.
+            const e = err;
+            const timedOut = e.name === "TimeoutError" || e.name === "AbortError";
+            lastStatus = 0;
+            lastError = timedOut
+                ? `Request to ${safeUrl} timed out after ${timeoutMs} ms`
+                : `Request to ${safeUrl} failed: ${e.message ?? "unknown network error"}`;
+            if (timedOut && !retryOnTimeout)
+                break;
+            if (attempt > retries)
+                break;
+            await sleep(Math.min(retryDelayMs * 2 ** (attempt - 1), Math.max(0, remainingMs())));
+        }
+    }
+    return {
+        ok: false,
+        status: lastStatus,
+        body: "",
+        durationMs: Date.now() - start,
+        attempts: retries + 1,
+        error: redactAll(lastError, redact),
+    };
+}
+/**
+ * `httpGet` plus JSON parsing, with malformed JSON demoted to `ok: false`
+ * rather than a thrown SyntaxError. A 200 carrying truncated JSON is a failed
+ * request as far as every caller is concerned.
+ */
+export async function httpGetJson(url, options = {}) {
+    const result = await httpGet(url, options);
+    if (!result.ok)
+        return { ...result, data: null };
+    try {
+        return { ...result, data: JSON.parse(result.body) };
+    }
+    catch (err) {
+        return {
+            ...result,
+            ok: false,
+            data: null,
+            error: redactAll(`Response from ${sanitizeUrl(url)} was not valid JSON: ${err.message}`, options.redact ?? []),
+        };
+    }
+}
+//# sourceMappingURL=httpClient.js.map

package/dist/utils/httpClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpClient.js","sourceRoot":"","sources":["../../src/utils/httpClient.ts"],"names":[],"mappings":"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"}

package/dist/utils/outputParsers.d.ts

@@ -6,6 +6,17 @@ export interface LighthouseAuditRef {
     displayValue: string;
     numericValue?: number;
     numericUnit?: string;
+    /**
+     * The audit's weight inside its Lighthouse category, taken from
+     * categories[].auditRefs[]. This is Lighthouse's own statement of how much
+     * the audit matters: weight 0 means it is a diagnostic that contributes
+     * nothing to the category score. Undefined when the audit belongs to no
+     * category (rare — treat as unknown, not as zero).
+     */
+    weight?: number;
+    /** Highest-weighted category the audit belongs to, for traceability. */
+    category?: string;
+    scoreDisplayMode?: string;
 }
 export interface ParsedLighthouse {
     categoryScores: Record<string, number>;
@@ -15,6 +26,8 @@ export interface ParsedLighthouse {
 }
 export declare function parseLighthouseJSON(rawJson: string): ParsedLighthouse;
 export type WcagLevel = "A" | "AA" | "AAA" | "unknown";
+export type A11yRunner = "htmlcs" | "axe";
+export type AxeImpact = "critical" | "serious" | "moderate" | "minor";
 export interface Pa11yViolation {
     code: string;
     technique: string;
@@ -24,6 +37,18 @@ export interface Pa11yViolation {
     type: "error" | "warning" | "notice";
     wcagLevel: WcagLevel;
     criterion: string | null;
+    /**
+     * Which engine produced this. The two emit completely different `code`
+     * shapes — htmlcs gives WCAG technique paths
+     * ("WCAG2AA.Principle1.Guideline1_1.1_1_1.H37"), axe gives bare rule ids
+     * ("image-alt") — so every consumer has to branch on this rather than
+     * pattern-matching the code.
+     */
+    runner: A11yRunner;
+    /** axe only: axe's own severity rating, its equivalent of Lighthouse weight. */
+    impact?: AxeImpact;
+    /** axe only: the rule could not decide alone and wants human confirmation. */
+    needsReview?: boolean;
 }
 export interface ParsedPa11y {
     violationCount: number;

package/dist/utils/outputParsers.js

@@ -1,10 +1,21 @@
 export function parseLighthouseJSON(rawJson) {
     const lhr = JSON.parse(rawJson);
     const categoryScores = {};
+    // An audit can appear in more than one category; keep the highest weight,
+    // since that is the strongest claim Lighthouse makes about its importance.
+    const auditWeights = {};
     for (const [key, cat] of Object.entries(lhr.categories ?? {})) {
         if (typeof cat?.score === "number") {
             categoryScores[key] = Math.round(cat.score * 100);
         }
+        for (const ref of cat?.auditRefs ?? []) {
+            if (!ref.id || typeof ref.weight !== "number")
+                continue;
+            const prev = auditWeights[ref.id];
+            if (!prev || ref.weight > prev.weight) {
+                auditWeights[ref.id] = { weight: ref.weight, category: key };
+            }
+        }
     }
     const scoreValues = Object.values(categoryScores);
     const totalScore = scoreValues.length > 0
@@ -21,6 +32,7 @@ export function parseLighthouseJSON(rawJson) {
         const scorePct = Math.round(audit.score * 100);
         if (scorePct >= 90)
             continue;
+        const weightRef = auditWeights[id];
         failedAudits.push({
             id,
             title: audit.title ?? id,
@@ -29,6 +41,9 @@ export function parseLighthouseJSON(rawJson) {
             displayValue: audit.displayValue ?? "",
             numericValue: typeof audit.numericValue === "number" ? audit.numericValue : undefined,
             numericUnit: audit.numericUnit,
+            weight: weightRef?.weight,
+            category: weightRef?.category,
+            scoreDisplayMode: audit.scoreDisplayMode,
         });
     }
     return { categoryScores, totalScore, ttfbMs, failedAudits };
@@ -108,6 +123,9 @@ function deriveWcagLevel(code) {
         return { level: "A", criterion };
     return { level: "unknown", criterion };
 }
+function isAxeImpact(v) {
+    return v === "critical" || v === "serious" || v === "moderate" || v === "minor";
+}
 function extractTechnique(code) {
     // pa11y/HTMLCS code shape: WCAG2AA.PrincipleN.GuidelineN_N.N_N_N.<technique>[.<variant>...]
     // The technique starts at the segment immediately after the criterion (e.g. "1_1_1").
@@ -167,6 +185,29 @@ export function parsePa11yJSON(rawJson) {
     for (const issue of issues) {
         const code = issue.code ?? "";
         const type = (issue.type ?? "error");
+        const runner = issue.runner === "axe" ? "axe" : "htmlcs";
+        if (runner === "axe") {
+            // axe codes are bare rule ids with no WCAG path to parse, so the
+            // criterion-derivation below cannot classify them — it would return
+            // level "unknown", which the priority mapper drops. Severity comes from
+            // axe's own impact rating instead. (Skipping this branch silently
+            // discarded every axe finding.)
+            const impact = issue.runnerExtras?.impact;
+            violations.push({
+                code,
+                technique: code,
+                message: issue.message ?? "",
+                selector: issue.selector ?? "",
+                context: issue.context ?? "",
+                type,
+                wcagLevel: "unknown",
+                criterion: null,
+                runner,
+                impact: isAxeImpact(impact) ? impact : undefined,
+                needsReview: issue.runnerExtras?.needsFurtherReview === true,
+            });
+            continue;
+        }
         const { level, criterion } = deriveWcagLevel(code);
         violations.push({
             code,
@@ -177,6 +218,7 @@ export function parsePa11yJSON(rawJson) {
             type,
             wcagLevel: level,
             criterion,
+            runner,
         });
     }
     return { violationCount: violations.length, violations };

package/dist/utils/outputParsers.js.map

@@ -1 +1 @@
-{"version":3,"file":"outputParsers.js","sourceRoot":"","sources":["../../src/utils/outputParsers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"outputParsers.js","sourceRoot":"","sources":["../../src/utils/outputParsers.ts"],"names":[],"mappings":"AA4BA,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAqB7B,CAAC;IAEF,MAAM,cAAc,GAA2B,EAAE,CAAC;IAClD,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,YAAY,GAAyD,EAAE,CAAC;IAE9E,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,OAAO,GAAG,EAAE,KAAK,KAAK,QAAQ,EAAE,CAAC;YACnC,cAAc,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;QACpD,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;gBAAE,SAAS;YACxD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;gBACtC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAClD,MAAM,UAAU,GACd,WAAW,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC;QACzE,CAAC,CAAC,CAAC,CAAC;IAER,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,sBAAsB,CAAC,CAAC;IAC5D,MAAM,MAAM,GACV,OAAO,cAAc,EAAE,YAAY,KAAK,QAAQ;QAC9C,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,YAAY,CAAC;QACzC,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,YAAY,GAAyB,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC3D,IAAI,KAAK,EAAE,KAAK,KAAK,IAAI,IAAI,KAAK,EAAE,KAAK,KAAK,SAAS;YAAE,SAAS;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;QAC/C,IAAI,QAAQ,IAAI,EAAE;YAAE,SAAS;QAC7B,MAAM,SAAS,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QACnC,YAAY,CAAC,IAAI,CAAC;YAChB,EAAE;YACF,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;YACpC,KAAK,EAAE,QAAQ;YACf,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,EAAE;YACtC,YAAY,EACV,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;YACzE,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,MAAM,EAAE,SAAS,EAAE,MAAM;YACzB,QAAQ,EAAE,SAAS,EAAE,QAAQ;YAC7B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;SACzC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;AAC9D,CAAC;AAiDD,MAAM,qBAAqB,GAA8B;IACvD,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,SAAS,eAAe,CAAC,IAAY;IAInC,qEAAqE;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,SAAS,IAAI,qBAAqB,CAAC,SAAS,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,KAAK,EAAE,qBAAqB,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;IAChE,CAAC;IACD,kEAAkE;IAClE,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC9D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC5D,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;IAC1D,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,WAAW,CAAC,CAAqB;IACxC,OAAO,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,OAAO,CAAC;AAClF,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,4FAA4F;IAC5F,sFAAsF;IACtF,mFAAmF;IACnF,yEAAyE;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC/C,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;AAC/C,CAAC;AA8BD,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,CAAC;IACrD,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,GAAG,CAAC,MAAM;gBAAE,SAAS;YAC1B,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ;gBACR,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC;gBACnB,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC;gBACvB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE;gBAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACrC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC;AA4BD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqC,CAAC;IACvE,MAAM,QAAQ,GAAqB,EAAE,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QAC1C,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE;YAC3B,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC;YAC7B,MAAM,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;YAC7B,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,EAAE;YACpC,QAAQ,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,IAAI,MAAM,CAAC,CAAC,WAAW,EAAE;YAC1D,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ;SAC3C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAmD,CAAC;IACrF,MAAM,MAAM,GAAoB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACnD,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAE1B,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,OAAO,CAA2B,CAAC;QAC/D,MAAM,MAAM,GAAe,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;QAErE,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YACrB,iEAAiE;YACjE,oEAAoE;YACpE,wEAAwE;YACxE,kEAAkE;YAClE,gCAAgC;YAChC,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC;YAC1C,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI;gBACJ,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;gBAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;gBAC9B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;gBAC5B,IAAI;gBACJ,SAAS,EAAE,SAAS;gBACpB,SAAS,EAAE,IAAI;gBACf,MAAM;gBACN,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;gBAChD,WAAW,EAAE,KAAK,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI;aAC7D,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACnD,UAAU,CAAC,IAAI,CAAC;YACd,IAAI;YACJ,SAAS,EAAE,gBAAgB,CAAC,IAAI,CAAC;YACjC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;YAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;YAC9B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;YAC5B,IAAI;YACJ,SAAS,EAAE,KAAK;YAChB,SAAS;YACT,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;AAC3D,CAAC"}

package/dist/utils/psiAuth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PSI API key resolution.
+ *
+ * Precedence: explicit tool input → PAGESPEED_API_KEY → keyless.
+ *
+ * The preferred setup is the `env` block in the MCP client config, because the
+ * client launches this server and we do not control its flags — `--env-file`
+ * is not available to us. An explicit input is supported for people who want
+ * to paste a key once, but it is the worst option: it lands in the
+ * conversation transcript and in any client-side logging, so it is never
+ * echoed back and every error that touches a request URL is redacted.
+ */
+export type KeySource = "input" | "env" | "none";
+export interface ResolvedKey {
+    key: string | null;
+    source: KeySource;
+}
+export declare const KEY_ENV_VAR = "PAGESPEED_API_KEY";
+/**
+ * Keyless PSI is rate-limited hard enough that a batch will 429 partway
+ * through, leaving a half-finished audit and a confusing error. Refusing up
+ * front with instructions is a better failure than discovering it at run 12.
+ */
+export declare const KEYLESS_RUN_CAP = 4;
+export declare function resolveApiKey(explicit?: string): ResolvedKey;
+export declare function keylessWarning(runs: number): string;

package/dist/utils/psiAuth.js

@@ -0,0 +1,36 @@
+/**
+ * PSI API key resolution.
+ *
+ * Precedence: explicit tool input → PAGESPEED_API_KEY → keyless.
+ *
+ * The preferred setup is the `env` block in the MCP client config, because the
+ * client launches this server and we do not control its flags — `--env-file`
+ * is not available to us. An explicit input is supported for people who want
+ * to paste a key once, but it is the worst option: it lands in the
+ * conversation transcript and in any client-side logging, so it is never
+ * echoed back and every error that touches a request URL is redacted.
+ */
+export const KEY_ENV_VAR = "PAGESPEED_API_KEY";
+/**
+ * Keyless PSI is rate-limited hard enough that a batch will 429 partway
+ * through, leaving a half-finished audit and a confusing error. Refusing up
+ * front with instructions is a better failure than discovering it at run 12.
+ */
+export const KEYLESS_RUN_CAP = 4;
+export function resolveApiKey(explicit) {
+    const trimmed = explicit?.trim();
+    if (trimmed)
+        return { key: trimmed, source: "input" };
+    const fromEnv = process.env[KEY_ENV_VAR]?.trim();
+    if (fromEnv)
+        return { key: fromEnv, source: "env" };
+    return { key: null, source: "none" };
+}
+export function keylessWarning(runs) {
+    return (`No ${KEY_ENV_VAR} set — running unauthenticated against a shared, ` +
+        `heavily rate-limited quota. This is fine for ${KEYLESS_RUN_CAP} runs or ` +
+        `fewer; ${runs} runs will almost certainly hit HTTP 429 partway through. ` +
+        `Get a key from the Google Cloud console (enable the PageSpeed Insights ` +
+        `API) and set ${KEY_ENV_VAR} in your MCP client config.`);
+}
+//# sourceMappingURL=psiAuth.js.map

package/dist/utils/psiAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"psiAuth.js","sourceRoot":"","sources":["../../src/utils/psiAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,MAAM,UAAU,aAAa,CAAC,QAAiB;IAC7C,MAAM,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjC,IAAI,OAAO;QAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAEtD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC;IACjD,IAAI,OAAO;QAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAEpD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,CACL,MAAM,WAAW,mDAAmD;QACpE,gDAAgD,eAAe,WAAW;QAC1E,UAAU,IAAI,4DAA4D;QAC1E,yEAAyE;QACzE,gBAAgB,WAAW,6BAA6B,CACzD,CAAC;AACJ,CAAC"}

package/dist/utils/psiParser.d.ts

@@ -0,0 +1,124 @@
+/**
+ * PageSpeed Insights response parsing.
+ *
+ * One PSI call returns two unrelated datasets: `lighthouseResult` (a lab run
+ * on Google's hardware) and `loadingExperience` (CrUX field data from real
+ * Chrome users). They are measured differently, they disagree routinely, and
+ * conflating them produces confidently wrong reports — so they stay separate
+ * all the way through this module and only meet in the comparator.
+ *
+ * The lab half is the same LHR schema `parseLighthouseJSON` already handles
+ * and is delegated to it unchanged. Everything here is about the field half
+ * and about pulling numeric lab metrics that survive aggregation.
+ */
+import { type ParsedLighthouse } from "./outputParsers.js";
+export type CruxCategory = "FAST" | "AVERAGE" | "SLOW" | "NONE";
+/** The five field metrics PSI reports. `fid` is deliberately absent — see below. */
+export type WebVital = "lcp" | "inp" | "cls" | "fcp" | "ttfb";
+export type FieldSource = "url" | "origin";
+export interface CruxMetric {
+    /**
+     * 75th percentile across the collection window. Milliseconds for every
+     * metric except `cls`, which is unitless.
+     */
+    p75: number;
+    category: CruxCategory;
+    /** Share of real users in each bucket. Sums to ~1. */
+    distribution: {
+        good: number;
+        needsImprovement: number;
+        poor: number;
+    };
+    /**
+     * Whether this specific metric came from the URL or from origin-wide data.
+     * Per metric, not per response — see the note on `parseCrux`.
+     */
+    source: FieldSource;
+}
+export interface ParsedCrux {
+    /**
+     * Always 28. PSI does not return the collection window, but CrUX in PSI is
+     * defined as a trailing 28-day aggregate, so this is a documented constant
+     * rather than a parsed value. Stated explicitly because reports must not
+     * describe field data as real-time.
+     */
+    collectionPeriodDays: 28;
+    overallCategory: CruxCategory | null;
+    /** Which source the majority of metrics came from, for a one-line summary. */
+    primarySource: FieldSource;
+    metrics: Partial<Record<WebVital, CruxMetric>>;
+}
+export interface LabMetrics {
+    lcpMs: number | null;
+    fcpMs: number | null;
+    cls: number | null;
+    tbtMs: number | null;
+    speedIndexMs: number | null;
+    ttiMs: number | null;
+    ttfbMs: number | null;
+}
+export interface ParsedPsi {
+    requestedUrl: string;
+    finalUrl: string;
+    strategy: string;
+    fetchTime: string | null;
+    lighthouseVersion: string | null;
+    scores: Record<string, number>;
+    lab: LabMetrics;
+    /** Null when the URL has too little real-user traffic and origin fallback is off or empty. */
+    field: ParsedCrux | null;
+    lighthouse: ParsedLighthouse;
+    /** Lighthouse audits that failed, for the existing defect formatter. */
+    runWarnings: string[];
+}
+/** PSI returned a 200 whose Lighthouse run did not actually complete. */
+export declare class PsiRuntimeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+interface RawCruxMetric {
+    percentile?: number;
+    category?: string;
+    distributions?: Array<{
+        min?: number;
+        max?: number;
+        proportion?: number;
+    }>;
+}
+interface RawLoadingExperience {
+    id?: string;
+    overall_category?: string;
+    metrics?: Record<string, RawCruxMetric>;
+}
+/**
+ * Merge URL-level and origin-level CrUX into one metric set.
+ *
+ * Field availability is **per metric, not per URL** — a page can have enough
+ * traffic for CrUX to report CLS but not LCP. A real response in the Five
+ * Below batch carried two of the five metrics at URL level while the origin
+ * carried all five, which is why the manual audit shows "No field data" for
+ * one metric and a category for another on the same row.
+ *
+ * So the fallback runs per metric, and each metric records where it came from.
+ * A single response-level `field_source` flag would have to either discard the
+ * URL-level metrics that do exist or silently label origin data as page data,
+ * and origin CrUX for a homepage says nothing about a checkout page.
+ */
+export declare function parseCrux(urlLevel: RawLoadingExperience | undefined, originLevel: RawLoadingExperience | undefined, originFallback: boolean): ParsedCrux | null;
+export interface ParsePsiOptions {
+    strategy: string;
+    /** Fall back to origin-wide CrUX per metric when URL-level data is absent. */
+    originFallback?: boolean;
+}
+/**
+ * Parse a full PSI v5 response.
+ *
+ * Throws `PsiRuntimeError` when Lighthouse itself failed inside a 200
+ * response. PSI does this routinely — a page that times out or refuses the
+ * fetch comes back as HTTP 200 with `lighthouseResult.runtimeError` set and
+ * every score null. Parsing it anyway records a real page as scoring zero
+ * across the board, which is worse than a failed run, because a zero looks
+ * like data. Callers should treat this as retryable.
+ */
+export declare function parsePsiResponse(rawJson: string, options: ParsePsiOptions): ParsedPsi;
+export {};