perfgraph 0.1.0

package/dist/mcp/handlers.d.ts

@@ -0,0 +1,72 @@
+/**
+ * MCP tool handler implementations.
+ *
+ * Each handler corresponds to a registered MCP tool. The primary shortcut
+ * `perfgraph_run` runs the full pipeline (collect → normalize → extract →
+ * analyze → report) in a single call. Advanced users can call individual
+ * pipeline steps via the dedicated tools.
+ *
+ * @packageDocumentation
+ */
+import type { IRBundle } from '../normalize/types.js';
+import type { ProgressReporter } from './progress.js';
+/**
+ * Collect raw performance data from a URL.
+ */
+export declare function handleCollect(url: string, outputDir?: string, runs?: number, onProgress?: ProgressReporter | null, mobile?: string): Promise<{
+    success: boolean;
+    runDir?: string;
+    error?: string;
+}>;
+/**
+ * Normalize collected data into an IRBundle.
+ */
+export declare function handleNormalize(runDir: string): Promise<{
+    ir: IRBundle;
+    irFile: string;
+}>;
+/**
+ * Extract diagnostic features from an IRBundle.
+ */
+export declare function handleExtract(irFile: string): Promise<{
+    featuresFile: string;
+}>;
+/**
+ * Build a causal graph from extracted features.
+ */
+export declare function handleAnalyze(featuresFile: string): Promise<{
+    graphFile: string;
+}>;
+/**
+ * Generate a diagnostic report from extracted features.
+ */
+export declare function handleReport(featuresFile: string): Promise<{
+    reportFile: string;
+}>;
+/**
+ * Run the full PerfGraph pipeline: collect → normalize → extract → analyze → report.
+ *
+ * Sends progress notifications and returns structured results suitable for
+ * AI agent consumption.
+ */
+export declare function handleRun(url: string, outputDir?: string, runs?: number, onProgress?: ProgressReporter | null, mobile?: string): Promise<{
+    url: string;
+    outputDir: string;
+    files: {
+        report: string;
+        features: string;
+        graph: string;
+        insights: string;
+        networkSummary: string;
+        lighthouseSummary: string;
+        coverageSummary: string;
+    };
+    summary: {
+        score: string;
+        criticalIssues: number;
+        warnings: number;
+        infos: number;
+        issues: Record<string, string>;
+    };
+}>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/mcp/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAetD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAmEtD;;GAEG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,EACpC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAsBD;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAU3C;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBnC;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBhC;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBjC;AAMD;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,EACpC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;CACH,CAAC,CA6GD"}

package/dist/mcp/handlers.js

@@ -0,0 +1,285 @@
+/**
+ * MCP tool handler implementations.
+ *
+ * Each handler corresponds to a registered MCP tool. The primary shortcut
+ * `perfgraph_run` runs the full pipeline (collect → normalize → extract →
+ * analyze → report) in a single call. Advanced users can call individual
+ * pipeline steps via the dedicated tools.
+ *
+ * @packageDocumentation
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { writeManifest } from '../output/manifest.js';
+import { run } from '../collect/orchestrator.js';
+import { loadRunDir } from '../shared/fs-utils.js';
+import { DEFAULT_RUN_OPTIONS } from '../shared/types.js';
+import { normalize } from '../normalize/index.js';
+import { extract } from '../extract/index.js';
+import { buildInsights } from '../distill/insights.js';
+import { buildNetworkSummary, buildLighthouseSummary, buildCoverageSummary, } from '../distill/summaries.js';
+import { buildCausalGraph } from '../causal/index.js';
+import { buildReport } from '../report/index.js';
+import { buildReportMarkdown } from '../report/markdown.js';
+import { convertToon } from '../output/toon.js';
+import { severityOrder } from '../shared/utils.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Write a JSON or TOON file and return its path. */
+async function writeJson(dir, filename, data) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const filePath = resolve(dir, filename);
+    const content = filename.endsWith('.toon')
+        ? await convertToon(data)
+        : JSON.stringify(data, null, 2);
+    writeFileSync(filePath, content, 'utf-8');
+    return filePath;
+}
+/** Build a compact issues summary map from the report. */
+function buildIssuesMap(issues) {
+    const map = {};
+    for (const issue of issues) {
+        let key;
+        if (issue.id.startsWith('rb-')) {
+            key = 'renderBlocking';
+        }
+        else if (issue.id.includes('waterfall') || issue.id === 'cascade-delay') {
+            key = 'cascadeDelay';
+        }
+        else if (issue.id.includes('deep-critical') || issue.id === 'deep-critical-chain') {
+            key = 'deepCriticalChain';
+        }
+        else if (issue.id.includes('lcp')) {
+            key = 'lcpIncrease';
+        }
+        else if (issue.id.includes('layout') || issue.id.includes('cls')) {
+            key = 'layoutShifts';
+        }
+        else if (issue.id.includes('js') ||
+            issue.id.includes('long-task') ||
+            issue.id.includes('tbt')) {
+            key = 'javaScript';
+        }
+        else if (issue.id.includes('third-party')) {
+            key = 'thirdParty';
+        }
+        else if (issue.id.includes('ttfb')) {
+            key = 'ttfb';
+        }
+        else {
+            key = issue.id.replace(/[^a-zA-Z0-9]/g, '');
+        }
+        // Upgrade severity if we already have a weaker one
+        const existing = map[key];
+        if (!existing ||
+            severityOrder(issue.severity) > severityOrder(existing)) {
+            map[key] = issue.severity;
+        }
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Pipeline steps
+// ---------------------------------------------------------------------------
+/**
+ * Collect raw performance data from a URL.
+ */
+export async function handleCollect(url, outputDir, runs, onProgress, mobile) {
+    const options = {
+        ...DEFAULT_RUN_OPTIONS,
+        url,
+        output: outputDir ?? DEFAULT_RUN_OPTIONS.output,
+        runs: runs ?? 1,
+        mobile,
+    };
+    await onProgress?.report(0, 1, `Collecting data from ${url}...`);
+    const results = await run(url, options);
+    const successRuns = results.filter((r) => r.success);
+    if (successRuns.length === 0) {
+        const errors = results
+            .map((r) => r.error)
+            .filter(Boolean)
+            .join('; ');
+        return { success: false, error: errors || 'All collection runs failed' };
+    }
+    return { success: true, runDir: resolve(successRuns[0].outputDir) };
+}
+/**
+ * Normalize collected data into an IRBundle.
+ */
+export async function handleNormalize(runDir) {
+    if (!existsSync(runDir)) {
+        throw new Error(`Run directory not found: ${runDir}`);
+    }
+    const raw = loadRunDir(runDir);
+    const ir = normalize(raw);
+    const irFile = await writeJson(runDir, 'ir.json', ir);
+    return { ir, irFile };
+}
+/**
+ * Extract diagnostic features from an IRBundle.
+ */
+export async function handleExtract(irFile) {
+    if (!existsSync(irFile)) {
+        throw new Error(`IR file not found: ${irFile}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(irFile, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse IR file: ${err.message}`);
+    }
+    const ir = raw;
+    const features = extract(ir);
+    const dir = resolve(irFile, '..');
+    const featuresFile = await writeJson(dir, 'features.toon', features);
+    return { featuresFile };
+}
+/**
+ * Build a causal graph from extracted features.
+ */
+export async function handleAnalyze(featuresFile) {
+    if (!existsSync(featuresFile)) {
+        throw new Error(`Features file not found: ${featuresFile}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(featuresFile, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse features file: ${err.message}`);
+    }
+    const features = raw;
+    const graph = buildCausalGraph(features);
+    const dir = resolve(featuresFile, '..');
+    const graphFile = await writeJson(dir, 'graph.toon', graph);
+    return { graphFile };
+}
+/**
+ * Generate a diagnostic report from extracted features.
+ */
+export async function handleReport(featuresFile) {
+    if (!existsSync(featuresFile)) {
+        throw new Error(`Features file not found: ${featuresFile}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(featuresFile, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse features file: ${err.message}`);
+    }
+    const features = raw;
+    const graph = buildCausalGraph(features);
+    const report = buildReport(graph, features);
+    const dir = resolve(featuresFile, '..');
+    const reportFile = await writeJson(dir, 'report.toon', report);
+    return { reportFile };
+}
+// ---------------------------------------------------------------------------
+// Primary shortcut: run full pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Run the full PerfGraph pipeline: collect → normalize → extract → analyze → report.
+ *
+ * Sends progress notifications and returns structured results suitable for
+ * AI agent consumption.
+ */
+export async function handleRun(url, outputDir, runs, onProgress, mobile) {
+    const baseOutput = outputDir ?? DEFAULT_RUN_OPTIONS.output;
+    const options = {
+        ...DEFAULT_RUN_OPTIONS,
+        url,
+        output: baseOutput,
+        runs: runs ?? 1,
+        mobile,
+    };
+    await onProgress?.report(1, 5, 'Collecting data...');
+    const collectResults = await run(url, options);
+    const successRuns = collectResults.filter((r) => r.success);
+    if (successRuns.length === 0) {
+        const errors = collectResults
+            .map((r) => r.error)
+            .filter(Boolean)
+            .join('; ');
+        throw new Error(`All collection runs failed: ${errors || 'unknown error'}`);
+    }
+    const runDir = resolve(successRuns[0].outputDir);
+    // Normalize
+    await onProgress?.report(2, 5, 'Normalizing collected data...');
+    const raw = loadRunDir(runDir);
+    // Write compact summaries of raw data files before normalization
+    if (raw.network) {
+        const networkSummary = buildNetworkSummary(raw.network);
+        await writeJson(runDir, 'network-summary.toon', networkSummary);
+    }
+    if (raw.lighthouse) {
+        const lighthouseSummary = buildLighthouseSummary(raw.lighthouse);
+        await writeJson(runDir, 'lighthouse-summary.toon', lighthouseSummary);
+    }
+    if (raw.coverage) {
+        const coverageSummary = buildCoverageSummary(raw.coverage);
+        await writeJson(runDir, 'coverage-summary.toon', coverageSummary);
+    }
+    let ir;
+    try {
+        ir = normalize(raw);
+    }
+    catch (err) {
+        throw new Error(`Normalization failed: ${err.message}`);
+    }
+    await writeJson(runDir, 'ir.json', ir);
+    // Extract features
+    await onProgress?.report(3, 5, 'Extracting diagnostic features...');
+    const features = extract(ir);
+    const featuresFile = await writeJson(runDir, 'features.toon', features);
+    // Build insights
+    const insights = buildInsights(features, raw.lighthouse ?? {});
+    const insightsFile = await writeJson(runDir, 'insights.toon', insights);
+    // Build causal graph
+    await onProgress?.report(4, 5, 'Building causal degradation graph...');
+    const graph = buildCausalGraph(features);
+    const graphFile = await writeJson(runDir, 'graph.toon', graph);
+    // Generate report (pass Lighthouse performance for score blending)
+    await onProgress?.report(5, 5, 'Generating diagnostic report...');
+    const lighthousePerf = ir.lighthouse.scores?.performance;
+    const report = buildReport(graph, features, lighthousePerf);
+    const reportFile = await writeJson(runDir, 'report.toon', report);
+    // Write human-readable markdown report
+    const reportMarkdown = buildReportMarkdown(report, insights);
+    const reportMdFile = resolve(runDir, 'report.md');
+    writeFileSync(reportMdFile, reportMarkdown, 'utf-8');
+    // Write manifest
+    const manifestFile = await writeManifest(runDir);
+    // Build light summary for the agent
+    const issuesMap = buildIssuesMap(report.issues);
+    const result = {
+        url,
+        outputDir: runDir,
+        files: {
+            report: reportFile,
+            reportMd: reportMdFile,
+            features: featuresFile,
+            graph: graphFile,
+            insights: insightsFile,
+            ir: resolve(runDir, 'ir.json'),
+            manifest: manifestFile,
+            networkSummary: resolve(runDir, 'network-summary.toon'),
+            lighthouseSummary: resolve(runDir, 'lighthouse-summary.toon'),
+            coverageSummary: resolve(runDir, 'coverage-summary.toon'),
+        },
+        summary: {
+            score: report.summary.score,
+            criticalIssues: report.summary.criticalIssues,
+            warnings: report.summary.warnings,
+            infos: report.summary.infos,
+            issues: issuesMap,
+        },
+    };
+    return result;
+}
+//# sourceMappingURL=handlers.js.map

package/dist/mcp/handlers.js.map

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

package/dist/mcp/progress.d.ts

@@ -0,0 +1,37 @@
+/**
+ * MCP progress notification helper.
+ *
+ * Provides a typed wrapper around `extra.sendNotification` for sending
+ * `notifications/progress` updates during long-running tool operations
+ * (collect, run-full-pipeline).
+ *
+ * Usage:
+ * ```ts
+ * const prog = createProgressReporter(extra.sendNotification, extra._meta?.progressToken);
+ * await prog?.report(1, 5, 'Collecting data…');
+ * await prog?.report(2, 5, 'Normalizing…');
+ * // ...
+ * ```
+ *
+ * Returns `null` when the client did not request progress, so callers
+ * can always `await prog?.report(...)` unconditionally.
+ *
+ * @packageDocumentation
+ */
+import type { ServerNotification } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Progress reporter — a lightweight function that sends one progress update.
+ * Returns `void`; errors are silently caught to avoid crashing the handler.
+ */
+export interface ProgressReporter {
+    report(progress: number, total: number, message?: string): Promise<void>;
+}
+/**
+ * Create a ProgressReporter when the client supplied a progressToken.
+ *
+ * @param sendNotification  - The `extra.sendNotification` function from the MCP tool callback.
+ * @param progressToken     - The `progressToken` from `extra._meta?.progressToken`.
+ * @returns A ProgressReporter, or `null` if the client did not request progress.
+ */
+export declare function createProgressReporter(sendNotification: (notification: ServerNotification) => Promise<void>, progressToken: string | number | undefined): ProgressReporter | null;
+//# sourceMappingURL=progress.d.ts.map

package/dist/mcp/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/mcp/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,EACrE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GACzC,gBAAgB,GAAG,IAAI,CAqBzB"}

package/dist/mcp/progress.js

@@ -0,0 +1,51 @@
+/**
+ * MCP progress notification helper.
+ *
+ * Provides a typed wrapper around `extra.sendNotification` for sending
+ * `notifications/progress` updates during long-running tool operations
+ * (collect, run-full-pipeline).
+ *
+ * Usage:
+ * ```ts
+ * const prog = createProgressReporter(extra.sendNotification, extra._meta?.progressToken);
+ * await prog?.report(1, 5, 'Collecting data…');
+ * await prog?.report(2, 5, 'Normalizing…');
+ * // ...
+ * ```
+ *
+ * Returns `null` when the client did not request progress, so callers
+ * can always `await prog?.report(...)` unconditionally.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Create a ProgressReporter when the client supplied a progressToken.
+ *
+ * @param sendNotification  - The `extra.sendNotification` function from the MCP tool callback.
+ * @param progressToken     - The `progressToken` from `extra._meta?.progressToken`.
+ * @returns A ProgressReporter, or `null` if the client did not request progress.
+ */
+export function createProgressReporter(sendNotification, progressToken) {
+    if (progressToken === undefined)
+        return null;
+    return {
+        report: async (progress, total, message) => {
+            try {
+                await sendNotification({
+                    method: 'notifications/progress',
+                    params: {
+                        progressToken,
+                        progress,
+                        total,
+                        ...(message !== undefined ? { message } : {}),
+                    },
+                });
+            }
+            catch {
+                // Swallow — progress is advisory; a failing notification must not
+                // break the tool response.
+            }
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/mcp/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/mcp/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAYH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,gBAAqE,EACrE,aAA0C;IAE1C,IAAI,aAAa,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAE7C,OAAO;QACL,MAAM,EAAE,KAAK,EAAE,QAAgB,EAAE,KAAa,EAAE,OAAgB,EAAiB,EAAE;YACjF,IAAI,CAAC;gBACH,MAAM,gBAAgB,CAAC;oBACrB,MAAM,EAAE,wBAAwB;oBAChC,MAAM,EAAE;wBACN,aAAa;wBACb,QAAQ;wBACR,KAAK;wBACL,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAC9C;iBACF,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;gBAClE,2BAA2B;YAC7B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/mcp/prompts.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MCP diagnostic prompt templates.
+ *
+ * Prompts provide guided starting points for common diagnostic workflows.
+ * When an AI client invokes a prompt, it receives structured messages that
+ * guide it through the analysis process using PerfGraph tools.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import type { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const LcpAnalysisArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+    reportUri: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Guided LCP (Largest Contentful Paint) performance analysis.
+ *
+ * The prompt instructs the AI to run a focused analysis on LCP performance,
+ * examining the LCP breakdown (TTFB, resource delay, render delay, element
+ * render time) and all contributing factors.
+ */
+export declare function buildLcpAnalysisPrompt(args: z.infer<typeof LcpAnalysisArgsSchema>): GetPromptResult;
+export declare const AuditArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+    runs: z.ZodOptional<z.ZodNumber>;
+    focus: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        network: "network";
+        js: "js";
+        layout: "layout";
+        lcp: "lcp";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Comprehensive full-site performance audit.
+ *
+ * Instructs the AI to perform a thorough analysis across all performance
+ * dimensions and produce a complete diagnostic report.
+ */
+export declare function buildAuditPrompt(args: z.infer<typeof AuditArgsSchema>): GetPromptResult;
+export declare const SummarizeArgsSchema: z.ZodObject<{
+    reportUri: z.ZodString;
+    detail: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        detailed: "detailed";
+        brief: "brief";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Summarize an existing PerfGraph report in natural language.
+ *
+ * Takes a report resource URI (as returned by perfgraph_run) and produces
+ * a human-readable summary of the findings.
+ */
+export declare function buildSummarizePrompt(args: z.infer<typeof SummarizeArgsSchema>): GetPromptResult;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/mcp/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/mcp/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAsC1E,eAAO,MAAM,qBAAqB;;;iBAKhC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,GAAG,eAAe,CA6CnG;AAMD,eAAO,MAAM,eAAe;;;;;;;;;;iBAO1B,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,GAAG,eAAe,CAyDvF;AAMD,eAAO,MAAM,mBAAmB;;;;;;;iBAK9B,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,GAAG,eAAe,CAqC/F"}