@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/node_modules/playwright/node_modules/playwright-core/src/server/recorder.ts

@@ -677,7 +677,8 @@ export class Recorder extends EventEmitter<RecorderEventMap> implements Instrume
     const isSameDocument = !!event && !event.newDocument;
     this._prevFrameUrls.set(frame, frame.url());
     const url = userInitiatedNavigationUrl(event) ?? frame.url();
-    this._signalProcessor.signal(pageAlias!, frame, { name: 'navigation', url, isReload, isSameDocument });
+    const fromBlankPage = isBlankUrl(prevUrl) && !isBlankUrl(url);
+    this._signalProcessor.signal(pageAlias!, frame, { name: 'navigation', url, isReload, isSameDocument, fromBlankPage });
   }
 
   private _onPopup(page: Page, popup: Page) {
@@ -716,6 +717,10 @@ function userInitiatedNavigationUrl(event?: NavigationEvent): string | undefined
   return request.url();
 }
 
+function isBlankUrl(url: string | undefined): boolean {
+  return !url || url === 'about:blank';
+}
+
 function languageForFile(file: string): Language {
   if (file.endsWith('.py'))
     return 'python';

package/node_modules/playwright/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/playwright",
-  "version": "1.58.2-skyramp.8.14.6",
+  "version": "1.58.2-skyramp.8.14.9",
   "description": "Skyramp's fork of Playwright with trace recording for UI test generation",
   "publishConfig": {
     "access": "public"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.3.8",
+  "version": "0.4.0-rc.1",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
@@ -41,6 +41,7 @@
   "files": [
     "build/**/*.js",
     "build/**/*.d.ts",
+    "plugin/**",
     "README.md"
   ],
   "bundleDependencies": [
@@ -70,12 +71,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@playwright/test": "^1.55.0",
-    "@skyramp/skyramp": "1.3.40",
+    "@skyramp/skyramp": "1.3.44",
     "dockerode": "^5.0.0",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.1.1",
     "picomatch": "^4.0.5",
-    "playwright": "file:vendor/skyramp-playwright-1.58.2-skyramp.8.14.6.tgz",
+    "playwright": "file:vendor/skyramp-playwright-1.58.2-skyramp.8.14.9.tgz",
     "simple-git": "^3.30.0",
     "ts-is-record": "^3.0.5",
     "typescript": "^5.8.3",

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "skyramp",
+  "description": "Skyramp Agent Skills. Workflow instructions that pair with the Skyramp MCP server tools.",
+  "author": {
+    "name": "Skyramp Inc."
+  },
+  "homepage": "https://skyramp.dev/"
+}

package/plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "skyramp",
+  "description": "Skyramp Agent Skills. Workflow instructions that pair with the Skyramp MCP server tools.",
+  "skills": "./skills"
+}

package/plugin/prompts/declaring-a-plan.md

@@ -0,0 +1,20 @@
+## How to declare your plan
+
+The procedure says how to plan. The description of each field in the tool schema says what to put in the field and what its check reads. Each objection says what to do next, and it contains the decision that the check cannot make for you.
+
+## Answering an objection
+
+Each objection contains an `objectionId`, the evidence for the objection, and a suggested next step. You have two options:
+
+1. Change the plan and register it again.
+2. Register the plan again with an entry in `answers`. The entry gives the `objectionId` and your answer.
+
+Use only the ids that the last registration returned.
+
+One objection has no answer: an objection with an id that starts with `coverage:stateTest:` closes only when the plan holds the test, so add the test.
+
+The report shows each objection. If you gave an answer, the report shows the answer next to the objection. If you disagree with an objection, answer it. Do not leave it without an answer.
+
+## If you find a test that is not in your plan
+
+If you find a test that the diff needs and that is not in your plan, register the plan again with the new planned test. Then write the test. The report joins each delivered test to a plan planned test by id. The report refuses a contract test or an integration test that has no plan entry. This usually happens when you find a bug while you write or run the planned tests.

package/plugin/prompts/generate-tests/context-fetching.md

@@ -0,0 +1,4 @@
+<context_fetching_protocol>
+## Execution Plan Context
+Before calling any tool, replace every `<from source>` placeholder in the tool call parameters with actual values read from the relevant source file (handler, schema, or model). Do not proceed with placeholders still present — every parameter must trace to a concrete source.
+</context_fetching_protocol>

package/plugin/prompts/generate-tests/execution-plan.md

@@ -0,0 +1,63 @@
+# Generation step bodies
+
+Each section is one step of the recommendation prompt's generation plan. A `{name}`
+in the text is a value the prompt fills in. The analysis and planning instruction
+that used to live here is now in `../SKILL.md` and `declaring-a-plan.md`.
+
+## Parameter grounding
+
+Quote the source you read while planning in `<source_evidence>` blocks — include route handler signatures, request body schema fields, response shapes, and computed field formulas. Use these quotes to derive tool call parameters. Resolve:
+- **Auth middleware** — check for known signals ({authMiddlewarePatterns}). If any match, override `authHeader` and `authScheme` even if workspace.yml says authType: none. **If no known signal matches but {enrichSurface} shows security-adjacent code** (decorators like `@requiresRole`/`@Protected`, function names like `validateToken`/`checkPermission`/`verifyHMAC`, or imports from auth/security packages), read the relevant source file to determine the actual auth scheme before proceeding. Auth handling for `skyramp_integration_test_generation` with `scenarioFile` is covered in the Tool Workflows section below.
+- Business rules and formulas (e.g. total_cost = compute * rate + memory * rate)
+- State transitions and domain constraints (e.g. budget cannot drop below current spend)
+- Validation logic (field constraints, cross-field dependencies)
+- Security boundaries your plan does not already cover
+
+A candidate is worth planning when it is specific to THIS codebase — derived from a concrete business rule, formula, constraint, state transition or boundary in the changed files, not a general pattern that fits any API. Attack-surface `security_boundary` tests keep their value: they cover sibling destructive endpoints that could bypass the auth boundary this diff changed.
+
+{testPatternGuidelines}
+
+**Source-code validation gates:**
+- **Cascade vs referential integrity**: If both a cascade-delete and a delete-blocked scenario appear for the same resource pair, the source foreign-key delete policy says which one the code can actually do (ON DELETE CASCADE / cascade=True / onDelete: 'CASCADE' → cascade-delete; RESTRICT/PROTECT/no annotation → delete-blocked). The other variant asserts a policy this codebase does not have.
+- **Unique constraints**: Before you plan a unique-constraint scenario (duplicate POST → 409), confirm the code enforces it: SQL UNIQUE index, Mongoose unique: true, Prisma @unique, or explicit duplicate-check code. If the backend is Redis, schema-less, or has no explicit constraint in the changed files, nothing enforces uniqueness, so there is no 409 to catch.
+
+## Execute the plan
+
+Write the tests the plan you registered holds, with its objections answered or its cause removed.
+
+Every scenario must follow the foreign-key relationships the codebase really has. Never pair unrelated resources.
+Use the field names and values from the `<source_evidence>` blocks you quoted in Step {enrichStep} to fill all tool call parameters. Prefer reusing Step {enrichStep} evidence when it already resolves a placeholder, but if a placeholder cannot be replaced with concrete values from files already read, you may read the specific schema, model, or handler file needed to resolve it. Assert response field values, not just status codes.
+
+{testQualityCriteria}
+
+{generationRules}
+
+**A missing input is not a reason to skip a test:** No OpenAPI spec → use source code for shapes. No traces → provide `skyramp_start_trace_collection` instructions. No backend trace → use the scenario pipeline.
+
+If the work shows you a test worth writing that the plan does not hold — a flaw you find while writing, most often — register the plan again with it first.
+
+## UI and E2E tool workflow
+
+**UI/E2E tool workflow** — use it for each UI or E2E test your plan holds:
+- **E2E**: {e2eStep}
+- **UI**: {uiStep}
+Derive scenario names and steps from the actual changed frontend files. If your plan holds no UI or E2E test, skip this.
+
+**Empty page**: If a page carries no test data — an empty state, nothing to interact with — write the Playwright test from the component structure, event handlers and expected behavior you read in the diff, or seed the data through `page.evaluate()` or an API call. At minimum assert that the page renders and that its interactive elements carry the right attributes. An empty page is not a reason to write no test.
+
+## E2E with a trace
+
+Use discovered trace/recording files with `skyramp_e2e_test_generation`.
+
+## E2E with no trace
+
+Follow the E2E rule in the Tool Workflows section: skip the generation call and say in the report that both traces have to be recorded in a live environment first.
+
+## UI with a trace
+
+Use the trace you exported while walking that behaviour, or an existing Playwright `.zip` trace, with `skyramp_ui_test_generation`.
+
+## UI with no trace
+
+Record again with the UI steps in the Tool Workflows section — only when the plan changed that test after you registered it, or when no trace covers it — then call `skyramp_ui_test_generation` with `outputDir` set to {frontendTestDir}.
+

package/plugin/prompts/generate-tests/generation.md

@@ -0,0 +1,108 @@
+# Generation rules and the sections around them
+
+Each section is one block of the recommendation prompt. A `{name}` is a value
+the prompt fills in per run.
+
+## Architect preamble
+
+You are acting as a Skyramp Integration Architect. You will receive {scopeInput}. Your responsibility is to map test intent to the Skyramp generation spec with precision. No guessing — derive all parameters from the codebase, workspace config, and provided context only.
+
+Your task:
+1. **{scopeTask}** — prioritize tests most likely to catch real production bugs (state machine violations, cross-resource data integrity, computed field errors, security boundary bypasses) over trivial coverage
+2. **Register your plan, then write the tests it holds** by calling Skyramp MCP generation tools — only these types: **integration, contract, E2E, UI**. Never smoke. Never fuzz.
+3. **Account for existing coverage** — when an existing test already covers an endpoint + test type, make your planned test a maintenance update of that test, or say how the two differ
+
+Every tool parameter must trace to a concrete source: repository analysis, source code, or OpenAPI spec. Do not invent field names, request shapes, base URLs, or auth values. If a required value is unknown, read the relevant source file before calling the tool.
+
+## Test pattern guidelines
+
+### Test Pattern Guidelines
+
+- CRUD lifecycle per resource group (Create → Read → Update → Delete)
+- Auth flow (Register → Login → Access protected → Token refresh → Logout)
+- Pagination & filtering (boundary values, empty results, large page sizes)
+- Error responses (400, 401, 403, 404, 409, 422 — each with a specific trigger)
+  **422 prerequisite:** Only recommend a 422 / missing-field test when you can confirm from source or schema that the field is **required**. In source, optional types such as `Optional[str]` or `field?: T` are not omission failures. In OpenAPI, omission is controlled solely by the parent schema's `required` list; `nullable: true` only permits an explicitly provided `null` value. Also verify the exact error body field name returned by the handler (e.g. `detail` in FastAPI, `message` in Express) before asserting a specific string like `"missing"` — the server may return a different key or value.
+- **Middleware chains**: If auth/rate-limit/logging middleware exists, test the chain (e.g., rate limit hit → auth still checked → correct error returned)
+- **N+1 query risk**: If list endpoints join related data (e.g., orders with products), test with large datasets
+- **State machines**: If resources have status transitions (draft→published→archived), test invalid transitions (e.g., archived→draft should fail)
+- **Cascade deletes**: Only recommend after reading source code to confirm which resource holds the foreign key. The resource with the foreign key is the child; the one it points to is the parent. Example: if orders.product_id references products, then products is the parent — deleting a product tests whether orders are protected or cascade-deleted. Getting this backwards (treating the child as the parent) produces a nonsensical test.
+- **Race conditions**: If concurrent writes are possible (inventory deduction, counter increment), test concurrent requests
+- **Computed fields**: If response contains derived values (total, average, count), verify computation with known inputs (e.g., total_cost = compute_seconds * rate + memory_mb * rate + external_cost)
+- **Mutation with collection modification**: See the mutation-recalc rule in the Tool Workflows section — it is the most common source of user-reported bugs, so prefer it over a single-field update on the same endpoint.
+- **Webhook/event side effects**: If endpoints trigger async operations, test that side effects occur (e.g., POST /orders triggers notification)
+- **Cross-user isolation**: If resources are owned by users, test that user B cannot access/modify user A's resources (GET /users/{other_id}/data → 403 Forbidden)
+- **Range/boundary invariants**: If business rules cap values (max retries, min balance, discount ≤ subtotal), test the boundary (e.g., set retries to max+1 → expect rejection)
+- **Breaking change migration**: If the diff renames a route, changes auth headers, or removes a required field, test both old path (should 404) and new path (should succeed)
+
+## Test quality criteria
+
+### What Makes a Good Test
+
+**Integration tests** should demonstrate cross-resource data flow — step A creates data
+that step B depends on (e.g., create product → create order referencing that product's ID →
+verify order contains correct product). Single-resource CRUD alone is not an integration test.
+Use actual field names and values from the source code schema or OpenAPI schema (not `{}` or invented field names); verify response data, not just status codes.
+
+**Contract tests** (single-step) are the right choice for: error-handling scenarios on a single
+endpoint (e.g., PATCH/GET/DELETE a nonexistent resource → 404, POST with invalid payload → 422),
+validation boundary checks, and any test that exercises one endpoint's API contract in isolation.
+Do NOT add setup steps just to avoid hardcoding an ID — use a realistic hardcoded nonexistent ID
+(e.g., 99999 or a random UUID) and keep it a single-step contract test.
+
+**E2E tests** should follow realistic user journeys end-to-end: browse products → search →
+add to cart → checkout. Verify that frontend actions trigger the correct API calls and
+that the UI reflects backend state.
+
+**UI tests** should exercise component behavior and interaction flows: fill form → validate
+inputs → submit → see confirmation. Include visual state changes (loading, error, empty)
+and accessibility checks.
+
+## Generation rules
+
+### Generation Guidelines
+
+**Available test types:** integration, contract, E2E, UI. **No smoke or fuzz tests.**
+Choose based on what adds the most value for this PR's changes. The contract test modes
+this build supports are in the Tool Workflows section.
+
+**Scenario fidelity:** Every workflow scenario should reflect the actual resource
+relationships in the code.
+
+For a UI test, use the trace you exported while walking that behaviour in the planning
+procedure. Record again with the Playwright browser tools (`browser_navigate`,
+`browser_click`, etc.) and export via `skyramp_export_zip` only when the plan changed that
+test after you registered it, or when no trace covers it.
+
+### The SDK helpers a generated TypeScript test uses
+
+All of these come from `@skyramp/skyramp`, the import the generated file already has.
+
+- `client.sendRequest({ url, path, method, body, headers, dataOverride, queryParams })` sends one request. `body` is a JSON string. `headers` is a plain object.
+- The client adds no authorization header on its own. Put the bearer token in `headers` as an `Authorization` header whose value is the word Bearer, a space, and `getEnv("SKYRAMP_TEST_TOKEN")`.
+- `headers` is per request. A step that sends no `headers` is the unauthenticated call. A step that needs another user's identity sends that user's token in its own `headers`.
+- A second identity is a second token. Create the user through the API, log that user in the same way the first token was obtained, and use the returned token on the steps that act as that user.
+- `response.statusCode` is the status. `getResponseValue(response, "<path>")` returns the value at that path in the response body, or `null` when the path is absent. Index an array element with `.0`, `.1`.
+- `dataOverride: { field: value }` replaces a top-level field of `body` by name. For a nested field, write the value into the body string with `${...}`.
+- `uniqueSuffix("base")` returns `base` with a run-unique suffix. Use it through `dataOverride` on a field the server requires to be unique; an email keeps its domain.
+- `getBaseUrl("SKYRAMP_TEST_BASE_URL", "<fallback>")` and `getEnv("<NAME>")` read the environment.
+
+## Before you finish a test
+
+Each of these is about the test file you are writing. Correct it in the file.
+
+- A negative assertion on a body (`not.toContain`, `not.toBe`) stands beside a positive one on the same response — the status, or a field the response must carry. A negative assertion alone passes on the wrong response too.
+- An assertion on a change checks the value the change states. If the change says the first response is a MISS, assert MISS, not one of MISS or HIT. If the value depends on test order or timing, do not assert either value: answer the change's objection with that reason.
+- An issue you will report at `high` or `critical` has a test, or one sentence saying why no test can reach it.
+- A test deletes each record it created, in its last steps. If the API has no delete for that record, say so in the test's description.
+- A test never leaves a record it did not create in a different state from the one it found. A seeded record may be the starting state of a mutation test when the test restores it afterwards (a reset endpoint, or the reverse mutation) or when the mutation under test is the one that should be REFUSED, which leaves the record unchanged.
+- A field the diff adds to a record appears in every expected body of that record, in new and in updated tests.
+- A timestamp is parsed and compared as a time, never indexed as characters.
+- A test declared to fail asserts the fixed behaviour, not today's status code. A `why` saying the test turns green after a fix has to be true of every assertion in the file, not just the last one.
+
+## Verification checklist
+
+<verification>
+Before finalizing your output, verify:
+1. **scenarioFile**: `skyramp_integration_test_generation` uses the exact `filePath` returned by `skyramp_batch_scenario_test_generation` — not a guessed or hardcoded filename.
+</verification>

package/plugin/prompts/generate-tests/path-parameters.md

@@ -0,0 +1 @@
+**Path parameters:** keep the placeholder in `endpointURL` (e.g. `/coupons/{coupon_id}`). Pass the value via `pathParams` (e.g. `coupon_id=<random-uuid-v4>`). Use example values from the OpenAPI schema if available; otherwise generate a fresh random UUID v4 — not all-zeros or repeated-digit patterns.

package/plugin/prompts/generate-tests/reasoning-protocol.md

@@ -0,0 +1,17 @@
+<reasoning_protocol>
+## Parameter Grounding Rule
+Before each GENERATE tool call, confirm WHERE each key value comes from:
+
+- **requestBody / responseBody fields** → source code schema (Zod, Pydantic, DTO), enriched scenario, or OpenAPI spec. **The generation tool rejects empty `{}` request bodies for POST/PUT/PATCH** — read the source schema first if the fields are unknown.
+- **endpointURL** → workspace `baseUrl` + endpoint path (both required — never path alone)
+- **authHeader / authScheme** → workspace config or OpenAPI `securitySchemes`
+- **Foreign-key path params** → chained from a prior step's response — never invented or hardcoded. Common field names: `id`, `uuid`, `_id`, `*_id`; use whatever identifier field the server returns for this resource. The chaining source can be a response body (POST or GET), a response header (e.g. `Location`), or a cookie.
+- **Names / string values** → realistic. Do NOT hardcode a timestamp/uuid suffix. Instead, for create fields that carry a UNIQUE constraint (e.g. `name`, `slug`, `email` — confirm from the source schema: `unique=True`, SQL `UNIQUE`, DTO), list their field paths in the step's `uniqueFields` (gjson notation) — the generator injects a run-unique value so re-runs don't 409.
+
+## Bug-Target Rule
+For each test you plan, include one sentence in your output (before the tool calls) stating the specific bug or failure it targets, derived from your source-code reading. Example: "Targets: order total miscalculation — total_amount = sum(item.price × item.quantity) should recompute when items array changes."
+
+Read the source and name the target before you plan the test.
+
+If a value cannot be sourced, read the relevant source file before calling the tool. Do not proceed with invented values.
+</reasoning_protocol>

package/plugin/prompts/generate-tests/tool-workflow-variants.md

@@ -0,0 +1,61 @@
+# Tool workflow variants
+
+Each pair below is one sentence the run chooses between: the workspace auth
+shape, and whether consumer-mode contract tests are built in.
+
+## Auth verification required
+
+**Auth Verification Required:** The workspace config indicates no authentication, but you MUST verify this independently before omitting auth:
+1. **OpenAPI spec** → check `securitySchemes` / `securityDefinitions` for `type: http`, `type: apiKey`, or `type: oauth2`
+2. **Source code** → look for the auth middleware signals listed in Step {enrichStep} of the Generation Plan.
+3. **Route definitions** → check if routes have auth decorators or middleware applied
+4. **Still unknown** → proceed with `authHeader: ""` and note "auth pattern unrecognized" in your recommendation description.
+If you find auth requirements, pass the appropriate `authHeader` and `authScheme` to EVERY tool call. Only pass `authHeader: ""` if you confirm the API is truly unauthenticated.
+**NEVER invent auth header names.** Only use header names explicitly defined in route/middleware source code or derived from OpenAPI security schemes. For `apiKey` schemes with `in: header`, use the scheme's `name` value. For `http` bearer/basic schemes, use `Authorization`. Do not treat `securitySchemes` map keys as header names, and do not guess headers from naming conventions such as `X-Admin-Key`, `X-API-Token`, or `X-Auth-Header` unless that exact header is explicitly defined in source or schema.
+
+## Auth scheme
+
+**Auth Scheme:** {authTypeLine}
+**Where to find the scheme** (check in order):
+1. **OpenAPI spec** → look at `securitySchemes` / `securityDefinitions` for `type: http, scheme: bearer` or `type: apiKey`
+2. **Source code** → the auth middleware signals listed in Step {enrichStep} of the Generation Plan
+3. **Fallback** → when the workspace sets `api.authType`, use that value as the scheme if the source is inconclusive; when it does not, use `"Bearer"` only if the project clearly uses JWT or OAuth, and `authScheme: ""` otherwise
+Pass the prefix as `authScheme` (e.g., `"Bearer"`, `"Token"`, `"Basic"`). If the API uses raw tokens with no prefix, pass `authScheme: ""`.
+**Do NOT guess the scheme.**
+To skip auth on an unauthenticated endpoint, pass `authHeader: ""`.
+
+## Auth header, not Authorization
+
+**Auth Header:** `{authHeader}` is a non-Authorization header — a placeholder token is auto-generated. Just pass `authHeader` — do NOT pass `authScheme` (it is only for Authorization headers and will be ignored).
+To skip auth for unauthenticated endpoints, pass `authHeader: ""`.
+
+## Integration auth, workspace handles it
+
+omit ALL auth params (passing auth alongside workspace authType causes "{authConflictError}").
+
+## Integration auth, header only
+
+pass `{authHeaderOnlyParams}` only (no `authScheme`, no `authToken`).
+
+## Auth line, none configured
+
+**No Auth (from workspace config):** Workspace indicates no authentication. **Verify independently** — if you find auth in the OpenAPI spec or source code, override with the correct `authHeader` and `authScheme`.
+
+## Auth line, configured
+
+**Auth params:** `{authCallParams}` — pass to EVERY tool call below.
+
+## Contract modes, consumer enabled
+
+**Contract test mode selection — set based on this service's role at the boundary:**
+- `providerMode: true` — this service IS the API; validates the implementation matches the spec.
+  Use for new or modified endpoints this codebase owns.
+- `consumerMode: true` — this service CALLS another API; validates outbound requests conform to the downstream contract.
+  Use when the endpoint's implementation makes HTTP calls to external services (look for fetch/axios/httpx/http.Client/service clients).
+  A request-aware mock stands in for the real downstream service — no live dependency needed.
+- **Both modes** (`providerMode: true, consumerMode: true`) — same output as omitting both flags. Generates both consumer and provider contract tests. Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).
+
+## Contract modes, provider only
+
+**Contract tests — provider-only:**
+Only provider-side contract tests are supported. Pass `providerMode: true` for new or modified endpoints this codebase owns.

package/plugin/prompts/generate-tests/tool-workflows.md

@@ -0,0 +1,65 @@
+## How to Generate Tests — Tool Workflows
+
+**Contract**: The following tool signatures are strict technical contracts. Every parameter should match the schema exactly. Omit optional parameters rather than guessing values. If a required field cannot be resolved, fetch context first.
+
+**Before every tool call**: Confirm WHERE each key value comes from — source code schema, enriched scenario, or OpenAPI spec. See Mandatory Reasoning Protocol above.
+
+{authHeaderLine}
+{authGuidance}
+
+**For multi-endpoint workflows (integration tests) — Batch Scenario → Integration pipeline:**
+1. Call `skyramp_batch_scenario_test_generation` with ALL steps in a single call: `scenarioName`, `destination`,
+   `baseURL`, `{authCallParams}`, and a `steps` array where each element has `method`, `path`, `requestBody` OR `queryParams`, `responseBody`, `statusCode`.
+   `statusCode` is optional for DELETE/GET/PUT/PATCH — defaults: DELETE→204 and GET/PUT/PATCH→200. For POST, always pass the confirmed `statusCode` explicitly after reading the handler, OpenAPI spec, existing test, or trace: resource-creation endpoints commonly return `201`, while action-style endpoints often return `200`.
+   **Action-style POST check:** Treat action verbs as path segments, not substrings. If the terminal path segment, or another clearly action-oriented segment, is a verb signalling an operation rather than resource creation (e.g. `/run`, `/trigger`, `/execute`, `/deploy`, `/submit`, `/start`, `/stop`, `/cancel`, `/send`, `/publish`, `/process`, `/validate`, `/check`, `/apply`, `/retry`), confirm the actual status code before setting `statusCode` — do NOT infer `201` from POST alone.
+   **OpenAPI spec is NOT required.** `apiSchema` is OPTIONAL — omit it if no spec exists.
+   **CRITICAL — Query params vs request body:**
+   - For **POST/PUT/PATCH**: use `requestBody` with realistic field values from source code schemas.
+   - For **GET/DELETE with search/filter/pagination**: use `queryParams`. Do not put query parameters in `requestBody` for GET requests — GET request bodies are non-standard and may be ignored or rejected.
+   - For **GET by ID**: no `requestBody` or `queryParams` needed — the ID is in the path.
+   `responseBody` should match the actual API response shape from source code (including all fields
+   returned by the controller — e.g., `id`, `ownerId`, `createdAt`, included relations like `collection`, `tags`).
+   Wrap in `{"response": ...}` if the API uses an envelope pattern. If omitted, a synthetic response is generated.
+   Inspect the source code to determine the correct request AND response body shapes — avoid sending `{}`.
+   **For PATCH/PUT mutation-recalc scenarios:** The request body should include the child
+   collection array (e.g. `"items": [{"product_id": <chained from prior POST>, "quantity": 2}]`).
+   Never send a PATCH that only modifies metadata (discount, status) without also including the
+   items/products collection — such a test will not catch collection-level or total-recalculation
+   bugs, and it is where user-reported bugs concentrate, so prefer it over a single-field update
+   on the same endpoint. Read the source for the child-collection field name, its foreign-key and
+   quantity sub-fields, and the total formula. Then assert the child items in the response
+   (product_id, quantity, unit_price) and the recomputed total, not just the top-level metadata.
+   For UNIQUE-constrained create fields, set the step's `uniqueFields` (gjson paths) rather than
+   hardcoding timestamp suffixes — the generator makes them run-unique so re-runs don't 409.
+   For every resource-creating step (POST/PUT), also add a matching DELETE step for the created
+   resource (path ID chained from the create response) so the scenario cleans up after itself.
+   For GET/PUT/DELETE with path IDs, use a placeholder — chaining resolves the real ID.
+2. Produces a `scenario_<name>.json` in the same `outputDir` as the test files (not `.skyramp/`).
+3. Call `skyramp_integration_test_generation` with `scenarioFile`: {integrationAuthNote}
+   Do NOT pass `chainingKey` — defaults to `response.id`. After generation, the testbot
+   will verify and fix path param chaining in the generated test.
+
+**For single-endpoint tests (contract):**
+`skyramp_contract_test_generation` with `endpointURL` (full URL incl. base + path), `method`,
+`{authCallParams}`, and `requestData` from source code schemas.
+If an OpenAPI spec exists, ALSO pass `apiSchema` — it enables schema-aware validation
+(contract tests verify response structure against the spec).
+Without a spec, `endpointURL` alone is sufficient.
+{pathParamUuidGuidance}
+
+{contractModeSelection}
+
+**For UI tests:**
+1. `browser_navigate` to the target URL (from workspace `api.baseUrl`)
+2. `browser_snapshot` to see the page (ARIA tree)
+3. Interact using `browser_click`, `browser_type`, `browser_fill_form`, etc.
+4. `browser_snapshot` after each interaction that changes the page
+5. `skyramp_export_zip` with an **absolute** output path: `<repositoryPath>/.skyramp/<test_name>_trace.zip`
+6. `skyramp_ui_test_generation` with `playwrightInput` = the **absolute** path of the exported zip, and `outputDir` = {frontendTestDir} (e.g. `frontend/tests`). Do NOT use the backend service's testDirectory — UI tests must go in the frontend service's test directory.
+
+Tips: For custom dropdowns (Radix, MUI): click combobox → snapshot → click option (NOT `browser_select_option`).
+
+**For E2E tests (mixed PR — both backend and frontend changed):**
+Only generate when pre-existing backend trace `.json` AND Playwright `.zip` both exist in the repo.
+Use them directly with `skyramp_e2e_test_generation`.
+If traces are missing, skip E2E and say in the report that both traces have to be recorded first.

package/plugin/prompts/plan-tests.md

@@ -0,0 +1,42 @@
+
+# Plan the tests a pull request needs
+
+## Terms
+
+You decide what to test. The tools give you the diff and the existing tests; they do not choose tests for you.
+
+A **change** is one thing the pull request should make happen, or reject, for a user or a caller. Say on each change whether it is on the API, on a page, or both.
+
+A **behaviour** is one rule about one endpoint or one page. One change can carry two behaviours, one on the API and one on the page. A test may prove several behaviours. Every behaviour has at least one test that proves it. All the rejections of one endpoint's input are one test with one case each. Declare on each change the inputs that prove it: what the route must accept and what it must reject.
+
+## The procedure
+
+Do the steps in this order.
+
+1. **Read the pull request title and description.** If they name a requirements file, read it too.
+2. **Read the whole diff.** Run `git diff <base>...HEAD` in the repository path. No tool returns the diff text. Page it if it is large.
+3. **Write the changes.** List every change, one line each, with a short id and where you read it. Write the list in your reply before you go on.
+   Keep each line through the rest of the procedure. Do not fold a change into another one or drop it because no test covers it.
+   For each edit in the diff, write one line: what it makes different for a user or a caller.
+   For each input a request takes, declare one case with a value the request must reject. Declare it even when the code does not reject that value today.
+   If a request must reject a value because of a record that already exists, declare that case too.
+   A request that names a record by id, in the path, in a query parameter, or in the body, must reject a record that does not exist or does not belong to the parent.
+   A record that belongs to another user is its own case, even when the answer is the same.
+4. **Find where each change is served.** Read the code that declares routes and pages, and write each route's full path with its mount prefix. Follow the callers of a changed file that has no route of its own to the endpoint or page that runs it. Read the code that writes each stored value the new code reads; any rule on that value is a rejection to list.
+5. **Read the existing tests that reach a change.** The analysis lists the repository's test files. Read the ones that import a changed file, call a changed route, or open a changed page.
+6. **Group the changes into behaviours and decide each.** A planned test names every change it covers. A change gets no test only when a test already in the repository proves it; the size of the edit or the kind of file is never a reason. A change no behaviour needs gets one sentence that says why.
+   If a state comes from time passing, create the record with the nearest allowed deadline and wait for it.
+7. **Walk each page behaviour once, as its test will run.** Start at login, do the steps of the behaviour, run `browser_blueprint` on each page you use, and export the trace when the flow ends. Name only elements from those captures. Do not try other values or read messages; the recording is the test.
+8. **Declare each planned test.** The tool schema says what goes in each field. A test that expects a rejection sends an accepted request first and asserts it succeeds. Two planned tests on one endpoint each say how they differ.
+9. **Register the whole plan in one call to `skyramp_register_test_plan`.**
+10. **Answer each objection, or change the plan and register it again.**
+    An answer that says a state cannot be produced says what you tried.
+11. **Stop when every objection has an answer.** Disagreeing in the answer closes it too.
+
+Then write the tests. The generation instructions say how.
+
+## Decisions the checks leave to you
+
+- **Requirement conflict.** Only a file the title or description names is a requirement source; a generated file or a URL is not. Do not search for other sources. Judge an edited requirements file on its new text. If the file is unchanged and the description presents the new behaviour as intended, the file is out of date, not in conflict. Report a conflict only when the named file states a behaviour and the code does not do it.
+- **Removed element.** If the diff removes an element from a page that still renders, plan a test that asserts it is absent. If it removes a whole component, route, or page, delete the tests that covered it.
+- **Reaching a screen after login.** If a control in the application leads to the screen, use the control. If no control leads to it, call `browser_navigate` with its URL once and continue in the same session.

package/plugin/prompts/testbot-task1.md

@@ -0,0 +1,82 @@
+# Testbot task 1: the v2 parts
+
+The blueprint citation rule for a UI recommendation, and the guardrail that
+stops a follow-up run from generating more tests.
+
+## Blueprint citation
+
+{uiGroundingStep}. **Blueprint Citation Invariant** (UI entries of `newTestsCreated` only). Every UI
+element you name comes from an element a blueprint of this run actually captured. Copy the values the
+capture gives and invent none — it omits `testId`, `stableId` and `contextText` for an element that
+has no such value, so omit them too. The report tool's schema states each field's shape and which
+entries may carry it.
+
+Judgment the schema cannot make for you:
+
+- **One element or several.** One when the test has a single dominant target — a click, a type, a
+  single visibility check, which is most tests. Several when it verifies elements together: a render
+  state, a workflow whose action is in one element and whose result is in another, a form fill. When
+  there is no single focus, anchor on the page heading or the most stable element on the page.
+- **A negative test still cites a real capture.** Ground `elements.items` against a page where the
+  element DOES render, so the citation can be confirmed.
+- **A removal guard is the one entry not lifted from a capture.** The element the PR removed renders
+  nowhere, so no blueprint holds it. Cite it from `uiContext.removedElements` — `testId` for a
+  `data-testid`, otherwise name the `attribute="value"` pair in `reasoning` and leave `testId` null —
+  take `role` and `accessibleName` from the deleted JSX in the diff, set `elements.pageUrl` to the
+  page you established for it, and prefix `reasoning` with `[removed-element]`.
+- **`description` and `reasoning` are complementary, not two spellings of one sentence.**
+  `description` walks through what the test does; `reasoning` says in one sentence what it verifies
+  and why. The report schema says how to name a UI element in either.
+
+Before submitting, check that every element name in `reasoning` matches an entry's `accessibleName`
+exactly and every backticked identifier comes from an entry's `testId` or `stableId`. If one does
+not, re-capture or drop that test. The `[no-blueprint-data]` marker and the two kinds of absence it
+does and does not cover are in the UI recommendation grounding section of the execution plan.
+
+## Follow-up generation guardrail
+
+- If the prompt requests adding, extending, or generating any test — including "all", "more", a count, or a named scenario → STOP EARLY. Call `skyramp_submit_report` with an empty array for `newTestsCreated` and a single entry in `issuesFound` with description set to EXACTLY this template: "Testbot generated every test this change warranted in its first run. The previous report's objections and their answers list what was deliberately not tested and why. Follow-up requests for more tests are not generated." Do NOT add any other text and do NOT paraphrase this template.
+
+## Analyze the change
+
+{analyzeStep}. Call `skyramp_analyze_changes` with `repositoryPath`: "{repositoryPath}", `scope`: "branch_diff"{analyzeCountArgs}{baseBranchArg}{prNumberArg}{testsRepoDirArg}.
+
+   **Follow all instructions returned by `skyramp_analyze_changes`.**{uiCredentialsNote}
+
+
+   **Feature context check:** After you capture a blueprint, cross-check whether it actually shows the changed feature. Look at the diff — what component, field, or UI element was changed? If that component only renders in a specific context (a particular collection type, a non-empty list, a specific user role, a form that only appears after a prior action), and the blueprint you captured doesn't contain it, navigate to the right context before using this blueprint for recommendations. A blueprint that doesn't show the changed feature produces recommendations that test the wrong thing — for example, recommending tests against a system collection when the PR changed behavior on custom collections. If you cannot reach the right context from the diff and the workspace config, leave the planned test's element list empty, name the page you opened, and note it in `issuesFound`.
+
+   **If `skyramp_analyze_changes` returns an error:** retry once only if the error is transient (timeout, network blip, temporary unavailability) — do NOT retry for permanent errors (invalid repository path, missing required parameter, authentication failure). If it fails again, call `skyramp_submit_report` with a minimal valid payload: leave all test arrays empty and add the error to `issuesFound`. Refer to the `skyramp_submit_report` schema for required fields. Do NOT attempt {generateTask} until an analysis succeeds: it writes the state file every later tool reads.
+
+## Log in before capturing
+
+Log in once via the credentials in your <ui-credentials> context before you navigate to any page you capture.
+
+## Multi-repo context
+
+   **MULTI-REPO CONTEXT (MANDATORY).** This run includes {relatedRepoCount} related {repoWord} listed in the `<related_repositories>` block below, each with an explicit `repository` (`owner/repo`), `path`, and `base_branch`. Use the `repository` value verbatim — do NOT infer it from git remotes or paths. You MUST analyze EACH related repository — exactly one `skyramp_analyze_changes` call per listed repo ({relatedRepoCount} {callWord}), in addition to the primary call in step {analyzeStep}.
+
+   **Run the primary call (step {analyzeStep}) FIRST, then the related repos in listed order — not in parallel.** All calls in this run automatically share ONE run-scoped state file — you do NOT pass a state-file path; setting `repository` is enough. The primary writes its root section; each related repo's call upserts its own section into that same file. Concurrent calls would race on the shared file, so they must be sequential. For each related repo:
+   - **({registerServicesStep})** Register its services into the **single unified workspace** — do NOT write a `.skyramp/workspace.yml` into the related repo (it is read-only context, and a per-repo file would need its own PR). The unified workspace always lives in the **primary repo** (where the testbot workflow is installed): `{repositoryPath}`{testRepoExclusionNote}. Steps: call `skyramp_init_scan` with `workspacePath`: the related repo's `path` to DISCOVER its services, then call `skyramp_init_workspace` with `workspacePath`: "{repositoryPath}" (the PRIMARY repo, NOT the related repo's path{testRepoExclusionShort}), `merge`: true, the `scanToken`, and the discovered services — each with its `repository` field set to that repo's `repository` value from the block. This upserts the related repo's services into the one unified `.skyramp/workspace.yml` (services are keyed by the composite of `repository` + `serviceName`).
+   - **({analyzeRepoStep})** Then call `skyramp_analyze_changes` with that repo's `path` (as `repositoryPath`), `scope`: "branch_diff", and `repository`: that repo's `repository` value. Passing `repository` stores this analysis as a section within the one run-scoped state file (the file is reused automatically across calls — do NOT pass any state-file path). Pass `baseBranch` only when the repo's `base_branch` attribute names a concrete branch; when `base_branch` is `auto-detect`, OMIT `baseBranch` and let the tool detect the repo's default branch.
+   - **({onFailureStep})** If analysis of a related repo fails (e.g. workspace init or diff error), record a one-line `issuesFound` note and CONTINUE — a missing related repo must not block the primary analysis.
+   Keep ALL returned diffs and recommendations from every repo in your working context. **Correlate** cross-repo changes when forming recommendations and the business case — e.g. an API contract changed in one repo and consumed by another, a request/response shape that must stay compatible across the boundary.
+
+   **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`); pass `primaryRepository: {primaryRepo}` on every one of those calls too, so the root section is the primary's whichever call runs first. When you maintain/act on any repo's tests — `skyramp_analyze_test_health`, `skyramp_actions`, `skyramp_execute_test` — pass that repo's `repository` (`owner/repo`) as the `repository` argument alongside the `stateFile` path returned by `skyramp_analyze_changes`, so the tool reads/writes that repo's section. The primary repo's `repository` is `{primaryRepo}`; pass it for the primary repo's tests just as you do for related repos.
+
+   **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.
+   - **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).
+
+## Code review
+
+{codeReviewStep}. **Code review:** Find the logic bugs in the code that this change touches. Read the implementation of each changed endpoint: the route handler, and the functions that it calls to read or write data. For a changed screen, read the component and the functions that it calls. Read these files even when the diff does not contain them — a defect often sits in the code that the change depends on. Report each objection in `issuesFound` with a severity, and say which file and line holds it. Common patterns to flag:
+   - Computed fields not recalculated after mutation (e.g. `total_amount` unchanged after items are added/removed)
+   - Incomplete CRUD: create without cleanup, update that adds new records without removing old ones
+   - Missing input validation on new endpoints
+   - Frontend rendering errors visible in the code (e.g. invalid props, missing required attributes)
+   - Incorrect arithmetic in business logic (discount calculations, price aggregation)
+   Log each objection in `issuesFound` with a `severity` (critical/high/medium/low). These bugs should inform your test design in {generateTask}.
+
+   **In the same pass, check the code against what the PR says it does**, following the full rule and its four checks under "The decisions that no check makes" in the planning procedure.