@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/tools/test-management/resolveScreenTool.d.ts

@@ -0,0 +1,75 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ScreenRouteCandidate } from "../../utils/screenRoutes.js";
+/** Where a bound route parameter came from. `unresolved` never carries a value. */
+export type ParamSource = "currentUrl" | "blueprint" | "unresolved";
+export interface ResolvedParam {
+    value: string;
+    from: ParamSource;
+}
+export interface ScreenCandidate {
+    /** The route with its known parameters filled in, prefixed by `baseUrl` when one
+     *  is known. Any parameter still in `needs` is left in its pattern spelling. */
+    url: string;
+    routePattern: string;
+    params: Record<string, ResolvedParam>;
+    /** Route entry file first, changed file last — the evidence for `routePattern`. */
+    mountChain: string[];
+}
+export interface ResolveScreenResult {
+    status: "resolved" | "unmounted" | "unknown";
+    candidates: ScreenCandidate[];
+    /** Route patterns ruled out. When the browser's page is known this is that page's
+     *  own route: the result then reads as a correction of where the browser is. */
+    notOn: string[];
+    /** Route parameters nothing could fill. */
+    needs: string[];
+    summary: string;
+}
+/** Where the browser is, as this server saw it. */
+export interface BrowserLocation {
+    url: string;
+    source: "currentUrl" | "blueprint";
+}
+/** The path half of a url, or the value itself when it is already a path. */
+export declare function urlPath(raw: string): string;
+/**
+ * The parameters the browser's current page supplies, and the route it is on.
+ *
+ * The binding runs against the CURRENT page's own pattern, and the values carry
+ * across by NAME. In the motivating run the browser sat on
+ * `/organizations/8f2e6b9f/projects/secret-management/1eb91367/overview`, whose
+ * pattern names `$orgId` and `$projectId`; the target route names those two and
+ * `$envSlug`, so two are known and one is not.
+ *
+ * A url matching several patterns is ambiguous, and the most literal one wins: a
+ * static segment is a stronger claim about the page than a parameter that accepts
+ * anything.
+ */
+export declare function bindFromLocation(location: BrowserLocation | undefined, patterns: string[]): {
+    pattern: string;
+    values: Record<string, string>;
+    source: ParamSource;
+} | undefined;
+/**
+ * Turn the resolver's three-state answer into the tool's, with parameters bound
+ * from wherever the browser is. Pure: every input is passed in, so the shape of the
+ * answer is testable without a repository or a browser.
+ */
+export declare function buildResolveScreenResult(input: {
+    changedFile: string;
+    candidates: ScreenRouteCandidate[] | undefined;
+    routePatterns: string[];
+    location?: BrowserLocation;
+    baseUrl?: string;
+}): ResolveScreenResult;
+/**
+ * The origin the UI is served from, as `.skyramp/workspace.yml` records it.
+ *
+ * There is no explicit "this one is the UI" marker in the workspace schema, so the
+ * service that runs Playwright is the proxy for it; failing that, an unambiguous
+ * single service with a baseUrl. Ambiguity yields nothing rather than a guess —
+ * the caller can pass `baseUrl`, and a route path without an origin is still a
+ * correct answer.
+ */
+export declare function workspaceUiBaseUrl(repositoryPath: string): Promise<string | undefined>;
+export declare function registerResolveScreenTool(server: McpServer): void;

package/build/tools/test-management/resolveScreenTool.js

@@ -0,0 +1,289 @@
+/**
+ * `skyramp_resolve_screen` — which URL renders this changed file, and how to get
+ * there from where the browser already is (SKYR-4341).
+ *
+ * The dead end this tool ends: an agent recording a UI trace finds the element it
+ * is looking for is not in the snapshot, and has nowhere to go. In run 33999747382
+ * it went to `browser_evaluate`, twenty-nine times, on a page that never rendered
+ * the changed component, and produced no test. The page was wrong, not the
+ * selector, and nothing in the run could say so.
+ *
+ * THE TOOL TAKES NO `currentUrl`. This server forwards every `browser_navigate`
+ * and records every blueprint capture, so it knows which page the browser is on;
+ * asking the agent instead would take the answer from the party this tool exists
+ * to correct. An agent-supplied url can be stale or invented, and the correction
+ * would then be built on the mistake.
+ *
+ * It reports what the resolver knows and never more: `resolved` with routes,
+ * `unmounted` when nothing renders the file, `unknown` when the scan cannot speak.
+ * A route parameter nothing could fill goes in `needs` — never a guessed value,
+ * because a plausible wrong id sends the browser to an empty page that looks real.
+ */
+import * as path from "path";
+import { z } from "zod";
+import { TOOL_RESOLVE_SCREEN } from "../../toolNames.js";
+import { logger } from "../../utils/logger.js";
+import { lastKnownBrowserUrl } from "../../playwright/blueprintDigestStore.js";
+import { readWorkspaceServices } from "../../prompts/prompt-utils.js";
+import { createScreenRouteLookup } from "../../utils/screenRoutes.js";
+// ── Route patterns ──────────────────────────────────────────────────────────
+/** A pattern segment, in the four spellings the frameworks this run meets use:
+ *  TanStack `$id`, React/Vue `:id`, Next `[id]`, OpenAPI-ish `{id}`. Mirrors the
+ *  `screenRoute` verifier — the two answer the same question about the same
+ *  patterns, and disagreeing about what a parameter looks like would let one pass
+ *  what the other objects to. */
+function parameterName(segment) {
+    if (segment.startsWith("$"))
+        return segment.slice(1) || undefined;
+    if (segment.startsWith(":"))
+        return segment.slice(1) || undefined;
+    if (segment.startsWith("[") && segment.endsWith("]"))
+        return segment.slice(1, -1).replace(/^\.\.\./, "") || undefined;
+    if (segment.startsWith("{") && segment.endsWith("}"))
+        return segment.slice(1, -1) || undefined;
+    return undefined;
+}
+function segments(value) {
+    return value.split("/").filter(Boolean);
+}
+/** The path half of a url, or the value itself when it is already a path. */
+export function urlPath(raw) {
+    const value = (raw ?? "").trim();
+    if (!value)
+        return "";
+    try {
+        return new URL(value).pathname.replace(/\/+$/, "") || "/";
+    }
+    catch {
+        return value.startsWith("/") ? value.split(/[?#]/)[0].replace(/\/+$/, "") || "/" : "";
+    }
+}
+function origin(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bind a pattern's parameters from a concrete path, or nothing when the path is
+ *  not that pattern filled in. Depth agrees or nothing does: a parameter matches
+ *  one segment and never spans two. */
+function bind(pattern, concretePath) {
+    const wanted = segments(pattern);
+    const actual = segments(concretePath);
+    if (wanted.length !== actual.length)
+        return undefined;
+    const bound = {};
+    for (let i = 0; i < wanted.length; i++) {
+        const name = parameterName(wanted[i]);
+        if (name)
+            bound[name] = actual[i];
+        else if (wanted[i] !== actual[i])
+            return undefined;
+    }
+    return bound;
+}
+/**
+ * The parameters the browser's current page supplies, and the route it is on.
+ *
+ * The binding runs against the CURRENT page's own pattern, and the values carry
+ * across by NAME. In the motivating run the browser sat on
+ * `/organizations/8f2e6b9f/projects/secret-management/1eb91367/overview`, whose
+ * pattern names `$orgId` and `$projectId`; the target route names those two and
+ * `$envSlug`, so two are known and one is not.
+ *
+ * A url matching several patterns is ambiguous, and the most literal one wins: a
+ * static segment is a stronger claim about the page than a parameter that accepts
+ * anything.
+ */
+export function bindFromLocation(location, patterns) {
+    if (!location)
+        return undefined;
+    const concretePath = urlPath(location.url);
+    if (!concretePath)
+        return undefined;
+    let best;
+    for (const pattern of patterns) {
+        const values = bind(pattern, concretePath);
+        if (!values)
+            continue;
+        const literals = segments(pattern).filter((segment) => !parameterName(segment)).length;
+        if (!best || literals > best.literals)
+            best = { pattern, values, literals };
+    }
+    return best ? { pattern: best.pattern, values: best.values, source: location.source } : undefined;
+}
+/** The pattern with its bound parameters substituted, prefixed by the origin when
+ *  one is known. An unbound parameter is left in its own spelling rather than
+ *  dropped: a url missing a segment silently names a different page. */
+function buildUrl(pattern, params, baseUrl) {
+    const filled = segments(pattern)
+        .map((segment) => {
+        const name = parameterName(segment);
+        const bound = name ? params[name] : undefined;
+        return bound && bound.from !== "unresolved" ? bound.value : segment;
+    })
+        .join("/");
+    const pathPart = "/" + filled;
+    const base = baseUrl ? baseUrl.replace(/\/+$/, "") : "";
+    return base ? base + pathPart : pathPart;
+}
+// ── The answer ──────────────────────────────────────────────────────────────
+/**
+ * Turn the resolver's three-state answer into the tool's, with parameters bound
+ * from wherever the browser is. Pure: every input is passed in, so the shape of the
+ * answer is testable without a repository or a browser.
+ */
+export function buildResolveScreenResult(input) {
+    const { changedFile, candidates, routePatterns, location, baseUrl } = input;
+    const here = bindFromLocation(location, routePatterns);
+    if (candidates === undefined) {
+        return {
+            status: "unknown",
+            candidates: [],
+            notOn: [],
+            needs: [],
+            summary: `No route table this server can read covers ${changedFile}, so it cannot say which page renders it. ` +
+                "Find the page yourself; do not treat this as evidence that nothing renders the file.",
+        };
+    }
+    if (candidates.length === 0) {
+        return {
+            status: "unmounted",
+            candidates: [],
+            // The current page is ruled out along with every other: nothing mounts it.
+            notOn: here ? [here.pattern] : [],
+            needs: [],
+            summary: `No route in this repository renders ${changedFile}. It is not reachable in the running app, ` +
+                "so a browser recording cannot exercise it. Say so in one line and keep the planned test out of the browser.",
+        };
+    }
+    const needs = new Set();
+    const resolved = candidates.map((candidate) => {
+        const params = {};
+        for (const segment of segments(candidate.routePattern)) {
+            const name = parameterName(segment);
+            if (!name)
+                continue;
+            const value = here?.values[name];
+            if (value !== undefined)
+                params[name] = { value, from: here?.source ?? "unresolved" };
+            else {
+                params[name] = { value: "", from: "unresolved" };
+                needs.add(name);
+            }
+        }
+        return {
+            url: buildUrl(candidate.routePattern, params, baseUrl),
+            routePattern: candidate.routePattern,
+            params,
+            mountChain: candidate.mountChain,
+        };
+    });
+    const mounts = new Set(resolved.map((candidate) => candidate.routePattern));
+    const notOn = here && !mounts.has(here.pattern) ? [here.pattern] : [];
+    const lines = [];
+    if (notOn.length > 0) {
+        lines.push(`The browser is on ${location?.url}, which is ${notOn[0]} — that page does not render ${changedFile}.`);
+        lines.push(`Navigate to ${resolved[0].url} instead.`);
+    }
+    else {
+        lines.push(`${changedFile} is rendered on ${resolved.map((c) => c.routePattern).join("; ")}.`);
+    }
+    if (needs.size > 0) {
+        lines.push(`No value is known for ${[...needs].join(", ")}. Read ${needs.size === 1 ? "it" : "them"} off the app with ` +
+            "`browser_snapshot`: the value shows up as a link or a list entry in the ARIA tree, so open the parent " +
+            "page and snapshot it if the current one does not hold it. Do not dig for it with `browser_evaluate`, " +
+            "and do not invent one — a plausible wrong id renders an empty page that looks real.");
+    }
+    lines.push("`mountChain` is the import path from the route file to the changed file: check it rather than trust it.");
+    return { status: "resolved", candidates: resolved, notOn, needs: [...needs], summary: lines.join(" ") };
+}
+// ── Workspace default for baseUrl ───────────────────────────────────────────
+/**
+ * The origin the UI is served from, as `.skyramp/workspace.yml` records it.
+ *
+ * There is no explicit "this one is the UI" marker in the workspace schema, so the
+ * service that runs Playwright is the proxy for it; failing that, an unambiguous
+ * single service with a baseUrl. Ambiguity yields nothing rather than a guess —
+ * the caller can pass `baseUrl`, and a route path without an origin is still a
+ * correct answer.
+ */
+export async function workspaceUiBaseUrl(repositoryPath) {
+    try {
+        const services = (await readWorkspaceServices(repositoryPath));
+        const withUrl = services.filter((service) => typeof service?.api?.baseUrl === "string" && service.api.baseUrl);
+        const playwright = withUrl.filter((service) => service.framework === "playwright");
+        const chosen = playwright.length === 1 ? playwright[0] : withUrl.length === 1 ? withUrl[0] : undefined;
+        return chosen ? origin(chosen.api?.baseUrl) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Registration ────────────────────────────────────────────────────────────
+const inputSchema = {
+    repositoryPath: z.string().describe("Absolute path to the repository checkout that holds the frontend file."),
+    changedFile: z
+        .string()
+        .describe("Repository-relative path of the frontend file the test is about — the file the diff changed, " +
+        "not the page you think renders it."),
+    baseUrl: z
+        .string()
+        .optional()
+        .describe("Origin the UI is served from, e.g. 'http://localhost:3000'. Defaults to the UI service's " +
+        "`api.baseUrl` in `.skyramp/workspace.yml`; when neither is known the returned urls are route paths."),
+};
+const outputSchema = {
+    status: z
+        .enum(["resolved", "unmounted", "unknown"])
+        .describe("resolved — the routes in `candidates` render the file. unmounted — no route renders it, so no browser " +
+        "recording can reach it. unknown — no route table could be read; this says nothing about the file."),
+    candidates: z
+        .array(z.object({
+        url: z.string(),
+        routePattern: z.string(),
+        params: z.record(z.object({ value: z.string(), from: z.enum(["currentUrl", "blueprint", "unresolved"]) })),
+        mountChain: z.array(z.string()),
+    }))
+        .describe("Each route that renders the file, with the import chain from its route file down to the file."),
+    notOn: z
+        .array(z.string())
+        .describe("The route the browser is currently on, when it is not one that renders the file."),
+    needs: z.array(z.string()).describe("Route parameters no known value fills. Read them off the app; never invent one."),
+    summary: z.string().describe("The same answer in one paragraph."),
+};
+const DESCRIPTION = "Answer which page of the running app renders a changed frontend file, and give the url to open. " +
+    "Call it BEFORE hunting for an element that is not in the snapshot: the usual cause is that the browser is " +
+    "on the wrong page, and no amount of browser_evaluate finds an element the page never rendered. " +
+    "Returns status 'resolved' with candidate urls, 'unmounted' when no route renders the file at all " +
+    "(skip the browser and say so), or 'unknown' when no route table could be read (find the page yourself). " +
+    "The current page is read from this server's own browser session — do not pass it.";
+export function registerResolveScreenTool(server) {
+    server.registerTool(TOOL_RESOLVE_SCREEN, { description: DESCRIPTION, inputSchema, outputSchema }, async (params) => {
+        const repositoryPath = String(params.repositoryPath ?? "").trim();
+        const changedFile = String(params.changedFile ?? "").trim();
+        const location = lastKnownBrowserUrl();
+        const baseUrl = (typeof params.baseUrl === "string" && params.baseUrl.trim()
+            ? origin(params.baseUrl.trim()) || params.baseUrl.trim()
+            : undefined) ??
+            (await workspaceUiBaseUrl(repositoryPath)) ??
+            (location ? origin(location.url) : undefined);
+        const lookup = createScreenRouteLookup(path.resolve(repositoryPath));
+        const result = buildResolveScreenResult({
+            changedFile,
+            candidates: lookup.candidatesFor(changedFile),
+            routePatterns: lookup.routePatterns(),
+            location,
+            baseUrl,
+        });
+        logger.info("skyramp_resolve_screen answered", {
+            changedFile,
+            status: result.status,
+            routes: result.candidates.length,
+            needs: result.needs.length,
+        });
+        return { structuredContent: { ...result }, content: [{ type: "text", text: result.summary }] };
+    });
+}

package/build/types/BlueprintDigest.d.ts

@@ -0,0 +1,34 @@
+/** What is kept from one `browser_blueprint` capture so a plan-time check can ask
+ *  whether an element the agent named was really on the page. A DIGEST, never the
+ *  capture: the largest real one is 26,542 bytes and a run takes many, so only the
+ *  fields an element can be recognised by are kept. */
+export interface BlueprintElementDigest {
+    /** ARIA role, as the capture spells it. */
+    role: string;
+    /** The element's accessible name. For a REPEATING element the capture carries
+     *  `accessibleNameTemplate` instead — one entry is kept for the template and one
+     *  per row with `{param}` filled in, so either spelling is recognised. */
+    accessibleName: string;
+    /** `data-testid` value. Absent when the element has none — SKYR-4208 removed
+     *  null-valued keys from the capture, so an absence is what arrives. */
+    testId?: string;
+    /** Unique `id` attribute value, absent when the element has none. */
+    stableId?: string;
+    /** Surrounding row text for an element inside a repeating section. It is the
+     *  only thing that separates two rows whose rendered names collide. */
+    contextText?: string[];
+}
+/** One capture, keyed by the page it was taken from. */
+export interface BlueprintCaptureDigest {
+    /** The page URL the capture reports. A repeat capture at the same URL carries
+     *  no URL of its own, so it inherits the one before it. */
+    url: string;
+    /** The capture's own page hash. Stored so a stale citation can be recognised
+     *  later; v0 matching does not narrow by it — see `uiElementGrounded`. */
+    pageHash?: string;
+    elements: BlueprintElementDigest[];
+    /** Whether the element cap cut this capture. An ungrounded objection says so,
+     *  because "no capture holds that element" is not a fact about a page whose
+     *  elements were only partly kept. */
+    elementsTruncated?: boolean;
+}

package/build/types/BlueprintDigest.js

@@ -0,0 +1 @@
+export {};