@skyramp/mcp 0.4.4-rc.1 → 0.4.4

package/build/workspace/workspace.js

@@ -61,7 +61,7 @@ export const serviceSchema = z
          *  the auth header). Literal values only — no env-var interpolation.
          *  Explicit per-request queryParams always win on a key collision
          *  (SKYR-4050). */
-        defaultQueryParams: z.record(z.string()).optional(),
+        defaultQueryParams: z.record(z.string(), z.string()).optional(),
         /** Path-scoped overrides layered on top of defaultQueryParams
          *  (SKYR-4127). For a given request, the single most-specific matching
          *  pathPattern wins and its values override the base map key by key;
@@ -84,7 +84,7 @@ export const serviceSchema = z
             .array(z
             .object({
             pathPattern: z.string().min(1),
-            values: z.record(z.string()),
+            values: z.record(z.string(), z.string()),
         })
             .strict())
             .optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.4.4-rc.1",
+  "version": "0.4.4",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
@@ -69,9 +69,10 @@
     "url": "https://github.com/skyramp/mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@playwright/test": "^1.55.0",
-    "@skyramp/skyramp": "1.3.47",
+    "@skyramp/skyramp": "1.3.50",
     "dockerode": "^5.0.0",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.1.1",
@@ -82,7 +83,7 @@
     "smol-toml": "^1.8.0",
     "ts-is-record": "^3.0.5",
     "typescript": "^5.8.3",
-    "zod": "^3.25.3"
+    "zod": "^4.2.0"
   },
   "devDependencies": {
     "@types/dockerode": "^3.3.39",
@@ -100,6 +101,6 @@
     "ts-jest": "^29.3.4"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/plugin/prompts/testbot-task1.md

@@ -65,7 +65,7 @@ Log in once via the credentials in your <ui-credentials> context before you navi
    **One state file, per-repo sections.** There is exactly ONE state file for the whole run (created automatically and reused across calls). Each `skyramp_analyze_changes` call writes its repo's section into it, keyed by `repository`. The run declares its primary when it starts, so the root section is the primary's whichever call runs first. When you maintain or act on a related repo's tests, pass that repo's `repository` value on the call, exactly as step {analyzeStep} says to pass `{primaryRepo}` for the primary repo's tests.
 
    **Cross-repo test generation ({generateTask} spans all repos).** Draft your planned tests from the analysis of the primary AND every related repo together, and register them as ONE plan. When you generate a test for a related repo's endpoint:
-   - **Execute it only if that repo's service is already running and reachable.** The workflow's setup may have started multiple services; before generating an API test for a related repo, confirm its `base_url` (from that repo's workspace/Execution Plan) responds. If the service is unreachable, still GENERATE the test but mark its `testResults` status as `Skipped` with details "service not running in this run" — do NOT count an unreachable service as a failure.
+   - **Execute it only if that repo's service is already running and reachable.** The workflow's setup may have started multiple services; before generating an API test for a related repo, confirm its `base_url` (from that repo's workspace/Execution Plan) responds. If the service is unreachable, still GENERATE the test but mark its `testResults` status as `Skipped` with details "service not running in this run" and `failureCause` `{ "kind": "environment", "family": "app_not_started" }` — do NOT count an unreachable service as a failure.
    - **Write the test file into that service's own `testDirectory`** — the one declared for the service in the unified workspace.yml (the related repo's services were registered there in {registerServicesRef}, each with its `repository`). The `testDirectory` is interpreted relative to the **single delivery root** (the configured test repo if set, otherwise the primary repo), so all generated tests are delivered together by the existing single-target delivery. Do NOT invent a per-source-repo subdirectory, and do NOT write into the related repo's own checkout — it is read-only context. (If two repos happen to declare the same `testDirectory`, their files coexist there; the `repository` field on each report item — below — is what attributes ownership, not the path.)
    - **Set the `repository` field** (`owner/repo`) on every such `newTestsCreated` / `testResults` item so the report attributes it to the originating repo (see Report Guidelines).
 

package/plugin/skills/repair-staged-files/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: repair-staged-files
+description: Get the files a Testbot run created or modified ready to commit under the target repo's own standards — lint, format, typecheck, naming, CI, dependencies, commit message and PR title, credential safety. Use once, after all generation, maintenance, and execution are done, before the report is submitted.
+---
+
+# Repair staged files
+
+**Goal:** the files this run created or modified are ready to deliver: `git commit` passes the repo's hooks, and the PR passes the repo's own checks. Find the staged and unstaged changed files with git commands.
+
+1. **Lint and format.** Find the repo's linter, formatter, type checker, and every commit hook — husky, lint-staged, the pre-commit framework, or a plain script — wherever git runs them from. The files and planned commit message must pass each. Hooks check only staged files; one that checked none of them has not passed. Run them on the files and fix every violation; a formatter's rewrite is the fix. Where a hook fails on warnings (`--max-warnings=0`), fix warnings too. `.editorconfig` and `.gitattributes` apply to every file. A tool applies per file, by that file's language, the repo's own included. Re-run until clean; record the command.
+2. **Conventions.** A new file must match the repo's test naming and directory convention (see existing tests and runner config). Fix a mismatch by renaming or moving the new file, and update every reference to it, the report included. Edit a maintained test in place; never rename or move it.
+3. **CI readiness.** Confirm CI will run the new files; if not, name the change the author must make — a note, not a blocker.
+4. **Dependencies.** Declare every package a test imports in the right manifest, and update its lockfile; both ship with the tests. For an import that does not resolve, use the `fix-test-import-errors` skill.
+5. **Commit and PR text.** Find every rule the repo applies to commit messages and PR titles, wherever it is defined; write both to satisfy all of it, and check them with the repo's own tool where one exists. Only when the repo has none, use "Skyramp Testbot: <concise>". Keep each within 72 characters, and add a body summarizing the tests added and maintained, naming the CODEOWNERS team and covering the PR template.
+   - DCO (Developer Certificate of Origin) sign-off is a `Signed-off-by: Skyramp Testbot <test-bot@skyramp.dev>` trailer in the commit message. Add it only when a CI check or the contributing docs require it. It is not a cryptographic signature: do not GPG- or SSH-sign the commit.
+
+Re-run any test you edit; its outcome must not change. Never weaken or remove an assertion, and never edit the repo's lint, format, or runner config, disable a rule, or add an ignore comment (`# noqa`, `eslint-disable`) to make a file pass. No real secret in a delivered file, the report, or the PR comment — that path skips every hook. If a finding can't be fixed without breaking these rules, stop and say what blocks the commit.

package/build/recommendation/blockerProbes.d.ts

@@ -1,13 +0,0 @@
-import { BlockerChecks } from "./blockers.js";
-import { PlanBlocker } from "./types.js";
-/** The three checks, resolved. Every await happens HERE, before the plan verifiers
- *  run: they are synchronous, so a probe cannot be reached from inside one. Each
- *  distinct URL and branch is probed once however many answers name it.
- *
- *  Called by both tools. The plan tool has a `VerifyContext` to hang the result on
- *  and the report tool does not, so this returns the checks rather than the context. */
-export declare function probeBlockers(blockers: PlanBlocker[]): Promise<BlockerChecks>;
-/** The blockers an answers list carries. */
-export declare function blockersIn(answers: ReadonlyArray<{
-    blocker?: PlanBlocker;
-}>): PlanBlocker[];

package/build/recommendation/blockerProbes.js

@@ -1,91 +0,0 @@
-import { probeUrl } from "./blockers.js";
-import { uiCredentialsSupplied } from "./pullRequestText.js";
-import { capturedBlueprintDigests } from "../playwright/blueprintDigestStore.js";
-import { logger } from "../utils/logger.js";
-/** How long a service gets to answer before the run calls it unreachable. Long
- *  enough for a container still warming up, short enough that a plan registration
- *  with several blockers does not stall the agent. */
-const PROBE_TIMEOUT_MS = 5_000;
-/** Whether the service at `url` answered. ANY status counts — a 500 is a service
- *  that is running, and the claim under test is only that the run could not reach
- *  it. UNDEFINED is never returned here: a request either gets a response or does
- *  not, and `verifyBlocker` decides what an unparseable URL means. */
-async function serviceAnswers(url) {
-    for (const method of ["HEAD", "GET"]) {
-        try {
-            await fetch(url, {
-                method,
-                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
-                redirect: "manual",
-            });
-            return true;
-        }
-        catch {
-            // HEAD is refused by some servers that answer GET perfectly well, so a
-            // failure on it is not yet an unreachable service.
-        }
-    }
-    return false;
-}
-/** A URL's path with no trailing slash, or UNDEFINED. The host is not compared: the
- *  agent writes `localhost` where the capture wrote `127.0.0.1`, and the reverse. */
-function pagePath(raw) {
-    try {
-        const path = new URL(raw).pathname.replace(/\/+$/, "");
-        return path || "/";
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Whether a capture this run took reached the page at `url` and read elements
- *  from it. */
-function pageLoaded(url) {
-    const wanted = pagePath(url);
-    return capturedBlueprintDigests().some((capture) => capture.elements.length > 0 && pagePath(capture.url) === wanted);
-}
-/** The three checks, resolved. Every await happens HERE, before the plan verifiers
- *  run: they are synchronous, so a probe cannot be reached from inside one. Each
- *  distinct URL and branch is probed once however many answers name it.
- *
- *  Called by both tools. The plan tool has a `VerifyContext` to hang the result on
- *  and the report tool does not, so this returns the checks rather than the context. */
-export async function probeBlockers(blockers) {
-    const urls = new Set();
-    for (const blocker of blockers) {
-        const detail = String(blocker?.detail ?? "").trim();
-        if (!detail)
-            continue;
-        if (blocker.kind === "service-unreachable")
-            urls.add(detail);
-    }
-    const serviceResults = new Map();
-    await Promise.all([
-        ...[...urls].map(async (raw) => {
-            // The SAME filter `verifyBlocker` applies, and it gates the request. Reading
-            // the detail with a bare `new URL` sent the server after whatever the agent
-            // wrote — `file:`, `data:`, a link-local address — and made the verdict a
-            // reachability oracle for anything the URL could name.
-            const url = probeUrl(raw);
-            if (!url)
-                return;
-            serviceResults.set(url, await serviceAnswers(url));
-        }),
-    ]).catch((error) => {
-        // A probe that throws leaves its entry unset, and an unset entry reads as
-        // "could not tell". A blocker must never close because a check crashed, and it
-        // must never be refused for that either.
-        logger.warning(`Blocker probe failed: ${error instanceof Error ? error.message : String(error)}`);
-    });
-    return {
-        serviceAnswers: (url) => serviceResults.get(url),
-        credentialsSupplied: uiCredentialsSupplied(),
-        pageLoaded,
-    };
-}
-/** The blockers an answers list carries. */
-export function blockersIn(answers) {
-    return answers
-        .map((entry) => entry.blocker)
-        .filter((blocker) => blocker !== undefined);
-}

package/build/recommendation/blockers.d.ts

@@ -1,65 +0,0 @@
-import { z } from "zod";
-import { PlanBlocker } from "./types.js";
-/** What `blocker` is, in the words both tools' schemas give the agent. One string:
- *  the plan states the rule before the tests run and the report states it after, and
- *  two copies drifted the moment either was edited. */
-export declare const BLOCKER_DESCRIPTION = "What stopped this run from writing the test, as one of two claims the server checks: `service-unreachable` with the URL the run needed, or `credential-missing` with the URL of the page the missing login guards. An objection about a change or a reported bug with no test, or about a value a page and API change accepts or refuses that no UI test names, closes only with one of these, and the server probes it \u2014 a claim it finds untrue leaves the objection open. A reason the test is not worth writing is not a blocker. A step that the browser tools cannot record is not a blocker either: record the steps they can, then edit the test file the generator writes and add the missing step yourself.";
-/** The `kind` values, in the schema's own words. */
-export declare const BLOCKER_KIND_DESCRIPTION = "Which of the two checkable things stopped the test. `service-unreachable`: the run could not reach a service it needed. `credential-missing`: the run holds no login for a page the test has to get past.";
-export declare const BLOCKER_DETAIL_DESCRIPTION = "The fact behind the claim: for `service-unreachable` the URL, spelled as the run tried it \u2014 the server requests it; for `credential-missing` the URL of the page that asked for the login \u2014 the server reads it against the pages this run already loaded, and a page the run loaded with no login needs none.";
-/** The blocker both tools take, as the schema that rejects anything else. An
- *  OBJECT, not a sentence: free text let an argument close an untested defect, and
- *  each kind here names one fact the server can probe. `.strict()` so an invented
- *  kind or an extra field fails the schema rather than reading as a claim nothing
- *  could check. */
-export declare const blockerSchema: z.ZodEffects<z.ZodObject<{
-    kind: z.ZodEnum<["service-unreachable", "credential-missing"]>;
-    detail: z.ZodEffects<z.ZodString, string, string>;
-}, "strict", z.ZodTypeAny, {
-    kind: "service-unreachable" | "credential-missing";
-    detail: string;
-}, {
-    kind: "service-unreachable" | "credential-missing";
-    detail: string;
-}>, {
-    kind: "service-unreachable" | "credential-missing";
-    detail: string;
-}, {
-    kind: "service-unreachable" | "credential-missing";
-    detail: string;
-}>;
-/** What the server made of a blocker's claim.
- *
- *  `refuted` is the one that costs the agent something: the probe found the
- *  opposite of what the blocker said, so the answer closes nothing. `unverifiable`
- *  is not a soft refusal — it is the server saying it could not look, which is
- *  where every close stood before these checks existed. */
-export type BlockerVerdict = "verified" | "refuted" | "unverifiable";
-/** The three probes, INJECTED so this module reaches neither the network nor the
- *  filesystem — the same rule `VerifyContext.citedFileExists` follows. Each returns
- *  UNDEFINED when it could not tell, which is a verdict of its own and never a
- *  silent pass. */
-export interface BlockerChecks {
-    /** Whether the service at this URL answered an HTTP request. Any status counts:
-     *  a 500 is a service that is running. */
-    serviceAnswers(url: string): boolean | undefined;
-    /** Whether the run was given browser credentials. */
-    credentialsSupplied: boolean | undefined;
-    /** Whether a page capture this run took reached this URL's page and read its
-     *  elements. A page that redirected to a login reports the login's URL. */
-    pageLoaded(url: string): boolean | undefined;
-}
-/** Whether an answer carries a blocker at all: a kind the schema knows and a detail
- *  that says something. Read defensively — the plan comes off disk, so the declared
- *  type holds only on the validated path. */
-export declare function hasBlocker(blocker: unknown): blocker is PlanBlocker;
-/** The blocker as one line, for a report field and an objection's evidence. */
-export declare function blockerText(blocker: PlanBlocker): string;
-/** An http(s) URL the probe can be pointed at, or UNDEFINED. A detail that is not
- *  one is not a wrong claim — it is a claim nothing can be made of. */
-export declare function probeUrl(detail: string): string | undefined;
-/** What the server made of this blocker. Pure: every fact comes from `checks`. */
-export declare function verifyBlocker(blocker: PlanBlocker, checks: BlockerChecks): BlockerVerdict;
-/** What the server saw, in the words the refusal quotes back. Only ever called on a
- *  `refuted` verdict, so each branch states the opposite of the claim. */
-export declare function refutedEvidence(blocker: PlanBlocker): string;

package/build/recommendation/blockers.js

@@ -1,135 +0,0 @@
-import { z } from "zod";
-/** What `blocker` is, in the words both tools' schemas give the agent. One string:
- *  the plan states the rule before the tests run and the report states it after, and
- *  two copies drifted the moment either was edited. */
-export const BLOCKER_DESCRIPTION = "What stopped this run from writing the test, as one of two claims the server checks: `service-unreachable` with the URL the run needed, or `credential-missing` with the URL of the page the missing login guards. An objection about a change or a reported bug with no test, or about a value a page and API change accepts or refuses that no UI test names, closes only with one of these, and the server probes it — a claim it finds untrue leaves the objection open. A reason the test is not worth writing is not a blocker. A step that the browser tools cannot record is not a blocker either: record the steps they can, then edit the test file the generator writes and add the missing step yourself.";
-/** The `kind` values, in the schema's own words. */
-export const BLOCKER_KIND_DESCRIPTION = "Which of the two checkable things stopped the test. `service-unreachable`: the run could not reach a service it needed. `credential-missing`: the run holds no login for a page the test has to get past.";
-export const BLOCKER_DETAIL_DESCRIPTION = "The fact behind the claim: for `service-unreachable` the URL, spelled as the run tried it — the server requests it; for `credential-missing` the URL of the page that asked for the login — the server reads it against the pages this run already loaded, and a page the run loaded with no login needs none.";
-/** The blocker both tools take, as the schema that rejects anything else. An
- *  OBJECT, not a sentence: free text let an argument close an untested defect, and
- *  each kind here names one fact the server can probe. `.strict()` so an invented
- *  kind or an extra field fails the schema rather than reading as a claim nothing
- *  could check. */
-export const blockerSchema = z
-    .object({
-    kind: z
-        .enum(["service-unreachable", "credential-missing"])
-        .describe(BLOCKER_KIND_DESCRIPTION),
-    detail: z
-        .string()
-        .refine((value) => value.trim().length > 0, {
-        message: "a blocker's detail must not be blank",
-    })
-        .describe(BLOCKER_DETAIL_DESCRIPTION),
-})
-    .strict()
-    // A detail the server cannot make anything of used to be accepted and then called
-    // `unverifiable`, which closes — so `service-unreachable: outside this PR` was the
-    // free-text escape this schema exists to remove. Each kind states its detail in the
-    // shape its check takes, or the plan is refused here. `credential-missing` was a
-    // sentence, and it closed an XR02 page objection on a page that needs no login.
-    .superRefine((blocker, ctx) => {
-    const detail = String(blocker?.detail ?? "").trim();
-    if (!detail || probeUrl(detail))
-        return;
-    ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["detail"],
-        message: blocker.kind === "credential-missing"
-            ? "a `credential-missing` detail is the URL of the page that asked for the login, with an `http://` or `https://` scheme — the server reads it against the pages this run loaded."
-            : "a `service-unreachable` detail is the URL the run tried, with an `http://` or `https://` scheme — the server requests it. A cloud metadata address is not requested.",
-    });
-});
-/** Whether an answer carries a blocker at all: a kind the schema knows and a detail
- *  that says something. Read defensively — the plan comes off disk, so the declared
- *  type holds only on the validated path. */
-export function hasBlocker(blocker) {
-    const kind = blocker?.kind;
-    const detail = blocker?.detail;
-    return ((kind === "service-unreachable" || kind === "credential-missing") &&
-        typeof detail === "string" &&
-        detail.trim().length > 0);
-}
-/** The blocker as one line, for a report field and an objection's evidence. */
-export function blockerText(blocker) {
-    return `${blocker.kind}: ${String(blocker.detail ?? "").trim()}`;
-}
-/** The addresses a probe must never be pointed at: the cloud metadata endpoint, in
- *  the two spellings it wears. The service under test runs on the runner, so
- *  loopback, `host.docker.internal` and the private ranges stay reachable — they
- *  are the probe's whole purpose. Only the link-local range, which serves nothing
- *  a test needs and serves instance credentials on every major cloud, is closed. */
-function isMetadataAddress(hostname) {
-    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
-    // 169.254.0.0/16, the same range mapped into IPv6 (the URL parser writes it as
-    // `::ffff:a9fe:…`), and fe80::/10 written as any of its four leading nibbles.
-    if (/^169\.254\./.test(host) ||
-        /^::ffff:a9fe:/.test(host) ||
-        /^fe[89ab][0-9a-f]:/.test(host))
-        return true;
-    return host === "metadata" || host === "metadata.google.internal";
-}
-/** An http(s) URL the probe can be pointed at, or UNDEFINED. A detail that is not
- *  one is not a wrong claim — it is a claim nothing can be made of. */
-export function probeUrl(detail) {
-    try {
-        const url = new URL(detail.trim());
-        if (url.protocol !== "http:" && url.protocol !== "https:")
-            return undefined;
-        // `fetch` throws on a URL with a login in it, which would read as unreachable.
-        if (url.username || url.password)
-            return undefined;
-        return isMetadataAddress(url.hostname) ? undefined : url.toString();
-    }
-    catch {
-        return undefined;
-    }
-}
-/** What the server made of this blocker. Pure: every fact comes from `checks`. */
-export function verifyBlocker(blocker, checks) {
-    const detail = String(blocker?.detail ?? "").trim();
-    switch (blocker?.kind) {
-        case "service-unreachable": {
-            const url = probeUrl(detail);
-            if (!url)
-                return "unverifiable";
-            const answered = checks?.serviceAnswers(url);
-            return answered === undefined
-                ? "unverifiable"
-                : answered
-                    ? "refuted"
-                    : "verified";
-        }
-        case "credential-missing": {
-            // The run records ONE opaque credentials string, so `true` says a login was
-            // supplied and nothing about which one — and that login may be what let a
-            // capture reach the page. Only `false` states a fact about the claim, and then
-            // a capture of the page says the page needed no login.
-            const url = probeUrl(detail);
-            if (!url || checks?.credentialsSupplied !== false)
-                return "unverifiable";
-            const loaded = checks?.pageLoaded(url);
-            return loaded === undefined
-                ? "unverifiable"
-                : loaded
-                    ? "refuted"
-                    : "verified";
-        }
-        default:
-            return "unverifiable";
-    }
-}
-/** What the server saw, in the words the refusal quotes back. Only ever called on a
- *  `refuted` verdict, so each branch states the opposite of the claim. */
-export function refutedEvidence(blocker) {
-    const detail = String(blocker?.detail ?? "").trim();
-    switch (blocker?.kind) {
-        case "service-unreachable":
-            return `${detail} answered an HTTP request, so the service is running`;
-        case "credential-missing":
-            return `this run loaded ${detail} with no login and read its elements, so the page needs none`;
-        default:
-            return blockerText(blocker);
-    }
-}