@aexol/spectral 0.9.42 → 0.9.43

package/dist/extensions/browser/scenario/scenario-tool.js

@@ -0,0 +1,381 @@
+import { parseMarkdownScenarioFile, } from "./markdown-parser.js";
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Normalise an inline step into the ScenarioStep shape. */
+function normalizeStep(raw, index) {
+    return {
+        action: (raw.action?.toLowerCase() ?? "note"),
+        raw: `Step ${index}: ${raw.action ?? "note"}${raw.target ? " " + raw.target : ""}`,
+        target: raw.target,
+        value: raw.value,
+        fields: raw.fields,
+        waitMs: raw.waitMs,
+    };
+}
+export function registerScenarioTools(ext, bs) {
+    const scenarioTool = {
+        name: "browser_run_scenario",
+        label: "Run Browser Scenario",
+        description: "Use this when the user asks to RUN, EXECUTE, PLAY, or WALK THROUGH a markdown test scenario in the browser. " +
+            "Executes the scenario steps in a real (visible) browser with optional video recording of the whole session. " +
+            "Accepts either inline `steps` or a `scenarioFile` path to a markdown scenario file. " +
+            "Do NOT write `.spec.ts` files or run `npx playwright test` for ad-hoc scenario execution or demo recordings — " +
+            "use this tool instead. Reserve `.spec.ts` / Playwright test authoring for when the user EXPLICITLY asks for " +
+            "durable e2e test code. Returns per-step pass/fail results and, if recording, the video path plus ffmpeg " +
+            "conversion commands.",
+        promptSnippet: "`browser_run_scenario { url, steps? | scenarioFile?, record?, filename?, stepDelayMs? }` — execute a markdown scenario in the browser with optional video recording (prefer this over writing .spec.ts for ad-hoc runs)",
+        parameters: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "The exact reachable URL to navigate to before running the scenario.",
+                },
+                steps: {
+                    type: "array",
+                    description: "Inline scenario steps. Each step: { action, target?, value?, fields?, waitMs? }. " +
+                        "Actions: navigate, click, type, press, select, hover, wait, screenshot, evaluate, fill_form, note.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            action: { type: "string", description: "One of: navigate, click, type, press, select, hover, wait, screenshot, evaluate, fill_form, note" },
+                            target: { type: "string", description: "CSS selector, text, or URL depending on action" },
+                            value: { type: "string", description: "Text to type, key to press, option to select, or wait duration" },
+                            fields: {
+                                type: "array",
+                                description: "For fill_form: list of { name, value } pairs.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        name: { type: "string" },
+                                        value: { type: "string" },
+                                    },
+                                },
+                            },
+                            waitMs: { type: "number", description: "Per-step pause in ms after the action (overrides stepDelayMs)" },
+                        },
+                        required: ["action"],
+                    },
+                },
+                scenarioFile: {
+                    type: "string",
+                    description: "Path to a markdown scenario file to parse and execute. Used as an alternative to inline `steps`. " +
+                        "Numbered list items (1. **Action** ...) are converted to steps.",
+                },
+                record: {
+                    type: "boolean",
+                    description: "If true, record the whole session as a .webm video. Default: false.",
+                },
+                filename: {
+                    type: "string",
+                    description: "Base filename (without extension) for the recording, e.g. 'login-demo'. Ignored unless record=true.",
+                },
+                stepDelayMs: {
+                    type: "number",
+                    description: "Default pause (ms) after each step for readable video. Default: 800. Set 0 to disable.",
+                },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const p = params;
+            if (!p.url) {
+                return {
+                    content: [{ type: "text", text: "Error: url (string) is required." }],
+                    details: { isError: true },
+                };
+            }
+            // Resolve steps.
+            let steps = [];
+            try {
+                if (p.scenarioFile) {
+                    steps = await parseMarkdownScenarioFile(p.scenarioFile);
+                    if (steps.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No numbered steps found in scenario file: ${p.scenarioFile}`,
+                                },
+                            ],
+                            details: { isError: true },
+                        };
+                    }
+                }
+                else if (p.steps && p.steps.length > 0) {
+                    steps = p.steps.map((s, i) => normalizeStep(s, i + 1));
+                }
+                else {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Error: provide either `steps` (inline) or `scenarioFile` (path to markdown).",
+                            },
+                        ],
+                        details: { isError: true },
+                    };
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `Failed to load scenario: ${msg}` }],
+                    details: { isError: true },
+                };
+            }
+            const record = p.record === true;
+            const stepDelay = typeof p.stepDelayMs === "number" ? p.stepDelayMs : 800;
+            const results = [];
+            // Optional recording start.
+            let videoPath;
+            let durationSeconds;
+            if (record) {
+                try {
+                    const rec = await bs.startRecording({ filename: p.filename });
+                    videoPath = rec.outputPath;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: "text", text: `Failed to start recording: ${msg}` }],
+                        details: { isError: true },
+                    };
+                }
+            }
+            // Navigate to the start URL.
+            try {
+                await bs.navigate(p.url);
+                await sleep(stepDelay);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // If we can't even navigate, fail everything.
+                for (let i = 0; i < steps.length; i++) {
+                    results.push({
+                        step: i + 1,
+                        action: steps[i].action,
+                        status: "skipped",
+                        detail: `Blocked: navigation failed (${msg})`,
+                        durationMs: 0,
+                    });
+                }
+                if (record) {
+                    try {
+                        const stop = await bs.stopRecording();
+                        videoPath = stop.outputPath;
+                        durationSeconds = stop.durationSeconds;
+                    }
+                    catch { /* ignore */ }
+                }
+                return finalize(results, videoPath, durationSeconds, false);
+            }
+            // Execute steps.
+            for (let i = 0; i < steps.length; i++) {
+                const step = steps[i];
+                const start = Date.now();
+                let status = "pass";
+                let detail = "";
+                try {
+                    const page = bs.getActivePage();
+                    switch (step.action) {
+                        case "navigate": {
+                            if (step.target) {
+                                await bs.navigate(step.target);
+                                detail = `Navigated to ${step.target}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "No target URL";
+                            }
+                            break;
+                        }
+                        case "click": {
+                            if (step.target) {
+                                await page.click(step.target, { timeout: bs.getConfig().actionTimeout || 5000 });
+                                detail = `Clicked ${step.target}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "No target";
+                            }
+                            break;
+                        }
+                        case "hover": {
+                            if (step.target) {
+                                await page.hover(step.target, { timeout: bs.getConfig().actionTimeout || 5000 });
+                                detail = `Hovered ${step.target}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "No target";
+                            }
+                            break;
+                        }
+                        case "type": {
+                            if (step.target && step.value !== undefined) {
+                                await page.fill(step.target, step.value, { timeout: bs.getConfig().actionTimeout || 5000 });
+                                detail = `Typed into ${step.target}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "Missing target or value";
+                            }
+                            break;
+                        }
+                        case "press": {
+                            const key = step.value ?? step.target;
+                            if (key) {
+                                await page.keyboard.press(key);
+                                detail = `Pressed ${key}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "No key";
+                            }
+                            break;
+                        }
+                        case "select": {
+                            if (step.target && step.value !== undefined) {
+                                await page.selectOption(step.target, step.value);
+                                detail = `Selected ${step.value} in ${step.target}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "Missing target or value";
+                            }
+                            break;
+                        }
+                        case "wait": {
+                            const ms = step.waitMs ?? (step.value && /^\d+$/.test(step.value) ? Number(step.value) : null);
+                            if (ms !== null) {
+                                await page.waitForTimeout(ms);
+                                detail = `Waited ${ms}ms`;
+                            }
+                            else if (step.value) {
+                                await page.waitForSelector(`text=${step.value}`, { timeout: 30_000 });
+                                detail = `Waited for text "${step.value}"`;
+                            }
+                            else {
+                                await page.waitForTimeout(1000);
+                                detail = "Waited 1000ms (default)";
+                            }
+                            break;
+                        }
+                        case "screenshot": {
+                            const config = bs.getConfig();
+                            const { mkdirSync } = await import("node:fs");
+                            mkdirSync(config.outputDir, { recursive: true });
+                            const ts = new Date().toISOString().replace(/[:.]/g, "-");
+                            const filepath = `${config.outputDir}/scenario-step-${i + 1}-${ts}.png`;
+                            await page.screenshot({ path: filepath });
+                            detail = `Screenshot: ${filepath}`;
+                            break;
+                        }
+                        case "evaluate": {
+                            const expr = step.target ?? step.value;
+                            if (expr) {
+                                const res = await page.evaluate(expr);
+                                detail = `Evaluated: ${expr}${res !== undefined ? ` → ${JSON.stringify(res).slice(0, 120)}` : ""}`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "No expression";
+                            }
+                            break;
+                        }
+                        case "fill_form": {
+                            if (step.fields && step.fields.length > 0) {
+                                for (const f of step.fields) {
+                                    await page.fill(f.name, f.value, { timeout: bs.getConfig().actionTimeout || 5000 });
+                                }
+                                detail = `Filled ${step.fields.length} field(s)`;
+                            }
+                            else {
+                                status = "skipped";
+                                detail = "No fields";
+                            }
+                            break;
+                        }
+                        case "note":
+                        default: {
+                            detail = `Note: ${step.raw}`;
+                            break;
+                        }
+                    }
+                }
+                catch (err) {
+                    status = "fail";
+                    detail = err instanceof Error ? err.message : String(err);
+                }
+                const durationMs = Date.now() - start;
+                results.push({ step: i + 1, action: step.action, status, detail, durationMs });
+                // Per-step pause for readable video (skip for wait actions already paused).
+                if (step.action !== "wait") {
+                    await sleep(step.waitMs ?? stepDelay);
+                }
+            }
+            // Optional recording stop.
+            if (record) {
+                try {
+                    const stop = await bs.stopRecording();
+                    videoPath = stop.outputPath;
+                    durationSeconds = stop.durationSeconds;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return finalize(results, videoPath, durationSeconds, true, `Recording stop failed: ${msg}`);
+                }
+            }
+            return finalize(results, videoPath, durationSeconds, true);
+        },
+    };
+    try {
+        ext.registerTool(scenarioTool);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[browser-scenario] Failed to register browser_run_scenario: ${msg}\n`);
+    }
+}
+/** Build the final text response from step results. */
+function finalize(results, videoPath, durationSeconds, ranToCompletion, warning) {
+    const passed = results.filter((r) => r.status === "pass").length;
+    const failed = results.filter((r) => r.status === "fail").length;
+    const skipped = results.filter((r) => r.status === "skipped").length;
+    const lines = [];
+    lines.push(ranToCompletion ? "✓ Scenario execution complete" : "✗ Scenario execution stopped early");
+    if (warning)
+        lines.push(`⚠ ${warning}`);
+    lines.push("");
+    lines.push("### Step Results");
+    for (const r of results) {
+        const icon = r.status === "pass" ? "✅" : r.status === "fail" ? "❌" : "⏭️";
+        lines.push(`${icon} Step ${r.step}: ${r.action} — ${r.detail} (${r.durationMs}ms)`);
+    }
+    lines.push("");
+    lines.push("### Summary");
+    lines.push(`- Steps total: ${results.length}`);
+    lines.push(`- Passed: ${passed}`);
+    lines.push(`- Failed: ${failed}`);
+    lines.push(`- Skipped: ${skipped}`);
+    if (videoPath) {
+        lines.push("");
+        lines.push("### Recording");
+        lines.push(`- File: ${videoPath}`);
+        if (durationSeconds !== undefined) {
+            lines.push(`- Duration: ${durationSeconds}s (${Math.floor(durationSeconds / 60)}m ${durationSeconds % 60}s)`);
+        }
+        const mp4 = videoPath.replace(/\.webm$/i, ".mp4");
+        const gif = videoPath.replace(/\.webm$/i, ".gif");
+        lines.push("- Convert to MP4:");
+        lines.push(`  ffmpeg -i "${videoPath}" -c:v libx264 -crf 23 "${mp4}"`);
+        lines.push("- Convert to GIF:");
+        lines.push(`  ffmpeg -i "${videoPath}" -vf "fps=15,scale=1280:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" "${gif}"`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { results, videoPath, durationSeconds, passed, failed, skipped },
+    };
+}

package/dist/extensions/browser/tools/core.js

@@ -5,7 +5,7 @@ export function registerCoreTools(ext, bs) {
     const navigateTool = {
         name: "browser_navigate",
         label: "Browser Navigate",
-        description: "Navigate to a URL in the browser. Auto-prepends https:// if no protocol is given.",
+        description: "Navigate to a URL in the browser. Auto-prepends https:// if no protocol is given. For multi-step scenario walkthroughs with optional recording, prefer browser_run_scenario.",
         promptSnippet: "`browser_navigate { url }` — navigate the browser to a URL",
         parameters: {
             type: "object",

package/dist/extensions/browser/tools/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/tools/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAgKnF"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/tools/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAiKnF"}

package/dist/extensions/browser/tools/screenshot.js

@@ -8,7 +8,8 @@ export function registerScreenshotTools(ext, bs) {
         name: "browser_take_screenshot",
         label: "Browser Take Screenshot",
         description: "Take a screenshot of the current page or viewport. " +
-            "Saves to the output directory. Use browser_snapshot for text-based page analysis.",
+            "Saves to the output directory. Use browser_snapshot for text-based page analysis. " +
+            "For multi-step scenario walkthroughs with recording, prefer browser_run_scenario.",
         promptSnippet: "`browser_take_screenshot` — capture a screenshot of the page",
         parameters: {
             type: "object",

package/dist/extensions/seo/analyzers/agent-ux.d.ts

@@ -0,0 +1,5 @@
+import type { AgentUxAuditResult } from "../types.js";
+import type { RenderResult } from "../utils/renderer.js";
+/** Audit agent UX using a rendered page result (with accessibility tree). */
+export declare function auditAgentUx(renderResult: RenderResult): AgentUxAuditResult;
+//# sourceMappingURL=agent-ux.d.ts.map

package/dist/extensions/seo/analyzers/agent-ux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-ux.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/analyzers/agent-ux.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAgEzD,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,kBAAkB,CAyD3E"}

package/dist/extensions/seo/analyzers/agent-ux.js

@@ -0,0 +1,95 @@
+/**
+ * Agent UX analyzer — audits pages for AI-agent friendliness.
+ *
+ * Ported from the Python `agent_ux_check.py` in claude-seo. Uses Playwright's
+ * accessibility tree plus semantic HTML analysis to score how easily an AI
+ * agent (not just a summarizer) can navigate and interact with the page.
+ */
+import * as cheerio from "cheerio";
+const SEMANTIC_LANDMARKS = new Set([
+    "header", "nav", "main", "article", "section", "aside", "footer",
+    "form", "search", "figure", "figcaption",
+]);
+function analyzeHtml(html) {
+    const $ = cheerio.load(html);
+    const realButtons = $("button").length;
+    const realAnchors = $("a[href]").length;
+    const divOnclick = $('div[onclick]').length;
+    const semanticLandmarks = $([...SEMANTIC_LANDMARKS].join(",")).length;
+    const inputsTotal = $("input, textarea, select").length;
+    let inputsMissingLabel = 0;
+    $("input, textarea, select").each((_, el) => {
+        const id = $(el).attr("id");
+        const ariaLabel = $(el).attr("aria-label");
+        const ariaLabelledby = $(el).attr("aria-labelledby");
+        const hasLabel = id ? $(`label[for="${id}"]`).length > 0 : false;
+        if (!hasLabel && !ariaLabel && !ariaLabelledby) {
+            inputsMissingLabel++;
+        }
+    });
+    return {
+        realButtons,
+        realAnchors,
+        divOnclickWidgets: divOnclick,
+        semanticLandmarks,
+        inputsTotal,
+        inputsMissingLabel,
+    };
+}
+function analyzeAccessibilityTree(tree) {
+    if (!tree || typeof tree !== "object") {
+        return { totalNodes: 0, interactiveNodes: 0, unnamedInteractive: 0, roleGenericRatio: 0 };
+    }
+    const n = tree;
+    const totalNodes = n.totalNodes ?? 0;
+    const interactiveNodes = n.interactiveNodes ?? 0;
+    const unnamedInteractive = n.unnamedInteractive ?? 0;
+    const genericNodes = n.genericNodes ?? 0;
+    return {
+        totalNodes,
+        interactiveNodes,
+        unnamedInteractive,
+        roleGenericRatio: totalNodes > 0 ? Math.round((genericNodes / totalNodes) * 100) / 100 : 0,
+    };
+}
+/** Audit agent UX using a rendered page result (with accessibility tree). */
+export function auditAgentUx(renderResult) {
+    const htmlAnalysis = analyzeHtml(renderResult.content);
+    const a11yAnalysis = analyzeAccessibilityTree(renderResult.accessibilityTree);
+    // Score: start at 100, deduct for issues.
+    let score = 100;
+    const opportunities = [];
+    // Penalize div onclick widgets.
+    if (htmlAnalysis.divOnclickWidgets > 0) {
+        score -= Math.min(30, htmlAnalysis.divOnclickWidgets * 5);
+        opportunities.push(`Replace ${htmlAnalysis.divOnclickWidgets} <div onclick> widgets with semantic <button> or <a> elements.`);
+    }
+    // Penalize missing labels.
+    if (htmlAnalysis.inputsMissingLabel > 0) {
+        score -= Math.min(20, htmlAnalysis.inputsMissingLabel * 5);
+        opportunities.push(`${htmlAnalysis.inputsMissingLabel} of ${htmlAnalysis.inputsTotal} inputs are missing labels. Add <label for> or aria-label.`);
+    }
+    // Penalize unnamed interactive elements.
+    if (a11yAnalysis.unnamedInteractive > 0) {
+        score -= Math.min(20, a11yAnalysis.unnamedInteractive * 3);
+        opportunities.push(`${a11yAnalysis.unnamedInteractive} interactive elements in the accessibility tree have no accessible name.`);
+    }
+    // Penalize low semantic landmark count.
+    if (htmlAnalysis.semanticLandmarks < 3) {
+        score -= 10;
+        opportunities.push(`Only ${htmlAnalysis.semanticLandmarks} semantic landmarks found. Use <header>, <nav>, <main>, <footer> for structure.`);
+    }
+    // Penalize high generic role ratio.
+    if (a11yAnalysis.roleGenericRatio > 0.5) {
+        score -= 10;
+        opportunities.push(`${Math.round(a11yAnalysis.roleGenericRatio * 100)}% of accessibility tree nodes have role="generic". Use semantic HTML to improve structure.`);
+    }
+    score = Math.max(0, Math.min(100, score));
+    return {
+        url: renderResult.finalUrl,
+        agentUxScore: score,
+        html: htmlAnalysis,
+        accessibilityTree: a11yAnalysis,
+        opportunities,
+    };
+}

package/dist/extensions/seo/analyzers/content.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Content quality analyzer.
+ *
+ * Ported from the Python `content_quality.py` in claude-seo. Pure heuristic
+ * analysis: filler phrase detection, AI-pattern detection, information density,
+ * and repetition scoring. No external API calls.
+ */
+import type { ContentQualityResult } from "../types.js";
+/**
+ * Analyze content quality of a text string.
+ *
+ * All scores are 0-100 where higher is better (except filler and AI pattern
+ * scores, where higher means MORE problematic content).
+ */
+export declare function analyzeContentQuality(text: string, url?: string): ContentQualityResult;
+//# sourceMappingURL=content.d.ts.map

package/dist/extensions/seo/analyzers/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/analyzers/content.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AA8HxD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAgDtF"}