@skyramp/mcp 0.4.3 → 0.4.4-rc.2

package/node_modules/playwright/node_modules/playwright-core/src/utils/isomorphic/elementOrder.ts

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// SKYR-4544: the one definition of an order assertion ("A starts before B on an
+// axis"). The MCP recorder, the MCP trace export and seeding, the MCP trace
+// replay and the core recorder replay all use it, so record and replay cannot
+// drift apart. (The generated test's comparison lives in the Go codegen, which
+// cannot import this; its goldens and the live demoshop check pin it.)
+
+/** Where the asserted element sits relative to the other one. */
+export const ORDER_RELATIONS = ['left-of', 'right-of', 'above', 'below'] as const;
+export type OrderRelation = typeof ORDER_RELATIONS[number];
+
+export function isOrderRelation(value: unknown): value is OrderRelation {
+  return typeof value === 'string' && (ORDER_RELATIONS as readonly string[]).includes(value);
+}
+
+/** The part of a box the comparison reads: its origin. */
+export type OrderBox = { x: number, y: number };
+
+export type OrderResult = {
+  ok: boolean,
+  /** x for left-of/right-of, y for above/below. */
+  axis: 'x' | 'y',
+  edgeA: number,
+  edgeB: number,
+};
+
+/**
+ * Whether `a` is `relation` of `b`: each box's origin — the left edge (x) for
+ * left-of/right-of, the top edge (y) for above/below — compared strictly. It
+ * says where each element STARTS, not that one lies wholly beyond the other,
+ * and equal edges never hold.
+ */
+export function orderHolds(relation: OrderRelation, a: OrderBox, b: OrderBox): OrderResult {
+  const axis = relation === 'left-of' || relation === 'right-of' ? 'x' : 'y';
+  const edgeA = a[axis];
+  const edgeB = b[axis];
+  const ok = relation === 'left-of' || relation === 'above' ? edgeA < edgeB : edgeA > edgeB;
+  return { ok, axis, edgeA, edgeB };
+}
+
+export type OrderFields = {
+  selector: string,
+  otherSelector: string,
+  relation: OrderRelation,
+  locator?: object,
+  otherLocator?: object,
+};
+
+/**
+ * The fields of an order assertion — a JSONL `assertOrder` line or a recorded
+ * browser_assert type "order" action's args — or null when it is malformed (no
+ * selector, no other end, or a relation outside ORDER_RELATIONS). Export, seeding
+ * and both replays parse through this, so they accept and drop exactly the same
+ * lines.
+ */
+export function parseOrderFields(raw: any): OrderFields | null {
+  if (!raw || typeof raw !== 'object')
+    return null;
+  const { selector, otherSelector, relation, locator, otherLocator } = raw;
+  if (typeof selector !== 'string' || !selector || typeof otherSelector !== 'string' || !otherSelector || !isOrderRelation(relation))
+    return null;
+  const fields: OrderFields = { selector, otherSelector, relation };
+  if (locator && typeof locator === 'object')
+    fields.locator = locator;
+  if (otherLocator && typeof otherLocator === 'object')
+    fields.otherLocator = otherLocator;
+  return fields;
+}

package/node_modules/playwright/node_modules/playwright-core/src/utils.ts

@@ -17,6 +17,7 @@
 export * from './utils/isomorphic/ariaSnapshot';
 export * from './utils/isomorphic/assert';
 export * from './utils/isomorphic/colors';
+export * from './utils/isomorphic/elementOrder';
 export * from './utils/isomorphic/headers';
 export * from './utils/isomorphic/locatorGenerators';
 export * from './utils/isomorphic/locatorParser';

package/node_modules/playwright/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/playwright",
-  "version": "1.58.2-skyramp.8.14.13",
+  "version": "1.58.2-skyramp.8.14.14",
   "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.4.3",
+  "version": "0.4.4-rc.2",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
@@ -69,19 +69,21 @@
     "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",
     "picomatch": "^4.0.5",
-    "playwright": "file:vendor/skyramp-playwright-1.58.2-skyramp.8.14.13.tgz",
+    "playwright": "file:vendor/skyramp-playwright-1.58.2-skyramp.8.14.14.tgz",
+    "semver": "^7.8.5",
     "simple-git": "^3.30.0",
     "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",
@@ -90,6 +92,7 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.15.19",
     "@types/picomatch": "^4.0.3",
+    "@types/semver": "^7.8.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.0.0",
@@ -98,6 +101,6 @@
     "ts-jest": "^29.3.4"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/plugin/prompts/plan-tests.md

@@ -3,11 +3,11 @@
 
 ## Terms
 
-You decide what to test. The tools give you the diff and the existing tests; they do not choose tests for you.
+You decide what to test.
 
 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. Rejections the application already handles share one test, one test case each; a test case a defect breaks gets its own test that expects to fail. Declare on each change the inputs that prove it: what the route must accept and what it must reject.
+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. Rejections the application already handles share one test, one test case each.
 
 ## The procedure
 
@@ -18,7 +18,7 @@ Do the steps in this order.
 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 requirement the title, the description or a requirements file states, write one line, even when no edit in the diff serves it. If the requirement is an item of a numbered or bulleted list, put its number in the line's `source`: `spec:<path>#11` or `pr-description#3`.
+   For each requirement the title, the description or a requirements file states, write one line, even when no edit in the diff serves it.
 4. **Declare the test cases each request must refuse.**
    - For each input a request takes, declare one test case with a value the request must reject. Declare it even when the code does not reject that value today.
    - For each list a request takes, declare one test case that is valid except for one item in the list. Give the test case one `param` and one `value`: the invalid item. The step that sends the test case carries the rest of the list.
@@ -27,33 +27,25 @@ Do the steps in this order.
    - For each state a record can be in that the request must refuse, declare one test case that puts the record in that state first and then sends the request.
    - 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 test case, even when the answer is the same.
-   - For each rule the pull request states, declare the test cases that catch a wrong implementation: each bound, one value past each bound, one value far past a bound, and each value the rule forbids. Take their values from the rule, not from an example.
+   - For each rule the pull request states, declare the test cases that catch a wrong implementation: each bound, one value past each bound, one value far past a bound, and each value the rule forbids. Take their values from the rule, not from an example. If an input accepts only values from a list, declare an accept test case for every value in it, even when the values share code or make the test long.
    - A reject test case expects the request to be refused and the record to be unchanged. Declare an exact status code or error text only when the pull request or a requirements file states it.
 5. **Declare what each response value must be.**
    - For each value the response carries that this change decides, declare what that value must be and where you read it: the pull request title or description, a requirements file the description names, or a rule the application already follows in code this pull request did not change.
    - Quote a value only when it holds for every input the test case can send: a fixed constant, a bound, or one of the allowed names. A value the inputs decide is `derived`, even when the source shows it in an example.
-   - If no source states the value, declare none and assert its shape instead.
    - Never take the value from the running application: that is the one source a defect cannot contradict.
 6. **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.
-7. **Review the code that serves each change.** Read the handler and the functions it calls to read or write data. For a changed screen, read the component and what it calls. Read these files even when the diff does not contain them; a defect often sits in the code the change depends on. Write each defect as one line with an id, the file, the line, and what is wrong. Write the list in your reply before you go on. An empty list is a statement: you read the code and found nothing. Common patterns to flag:
-   - A computed field that is not recalculated after a mutation, such as `total_amount` unchanged after items are added or removed
-   - Incomplete CRUD: a create with no cleanup, an update that adds new records and does not remove the old ones
-   - Missing input validation on a new endpoint
-   - A frontend rendering error visible in the code, such as an invalid prop, a missing required attribute, or a value shown without the formatting its neighbours use
-   - Incorrect arithmetic in business logic, such as a discount calculation or a price aggregation
+7. **Review the code that serves each change.** Read the handler and the functions it calls to read or write data. For a changed screen, read the component and what it calls. Read these files even when the diff does not contain them; a defect often sits in the code the change depends on. Write each defect as one line with an id, the file, the line, and what is wrong. Write the list in your reply before you go on. An empty list is a statement: you read the code and found nothing.
 8. **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.
 9. **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.
-   When the test that proves a change is one you are editing, declare that test in `maintains` and name the changes it covers. Those changes are then covered and get no planned test of their own; a second test beside the one you edited is the mistake. A plan whose only coverage is maintenance is a complete plan.
-   A requirement the title, the description or a named requirements file states and the code does not meet is a defect; its file is the code that contradicts it. A defect gets a planned test that names it in `defects` and expects to fail. A defect in the code the change touches is a defect whether or not this pull request introduced it, and it gets the same test. A defect gets no test only when something stopped the test: say what.
+   When the test that proves a change is one you are editing, or one you will run unchanged as a VERIFY, declare that test in `maintains` and name the changes it covers. Those changes are then covered and get no planned test of their own.
+   A requirement the title, the description or a named requirements file states and the code does not meet is a defect; its file is the code that contradicts it. A defect gets a planned test that names it in `defects` and expects to fail. If a test you ran unchanged as a VERIFY failed on the defect, name the defect in that test's `maintains` entry instead; the defect then needs no planned test. A defect gets no test only when something stopped the test: say what.
    If a state comes from time passing, create the record with the nearest allowed deadline and wait for it.
 10. **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.
-11. **Declare each planned test.** The tool schema says what goes in each field, `defects` included.
+11. **Declare each planned test.**
     - A test that expects a rejection sends an accepted request first. That request is the test's setup.
-    - Two planned tests on one endpoint each say how they differ.
     - A test that expects to fail proves one test case: its first assertion after setup is the one the defect breaks, and a red step stops every step after it. Declare one such test per test case the defect breaks, so each test case reports on its own.
     - Accepted test cases may share one test that expects to pass.
-    - A test that expects to fail asserts a value the code does not return today. Before you declare that test, put that value on the test case it sends, as `expectedValue`, and name where you read it, as `expectedFrom`. If the source states the rule and never writes the number, put the rule in `derived` and leave `expectedValue` out.
-12. **Register the whole plan in one call to `skyramp_register_test_plan`.** The call carries `changes`, `defects` and `plannedTests`.
+12. **Register the whole plan in one call to `skyramp_register_test_plan`.**
 13. **Answer each objection, or change the plan and register it again.**
     An answer that says a state cannot be produced says what you tried.
 14. **Stop when every objection has an answer.** Disagreeing in the answer closes it too.

package/plugin/skills/enhance-assertions/reference/shared-rules.md

@@ -26,7 +26,7 @@ Apply only to new test functions you are adding and existing test functions affe
 
 Before editing `$2`, you must output a `<thinking>` block. It states the behaviour each test evaluates, then works through the rules for the responses that behaviour depends on, so no rule that applies is overlooked. The JSON array must match the `rule_checklist` template that accompanies the `$0` rules. Use the template's keys verbatim; each key is the slug shown in that rule's heading. Every key must appear — `[]` where the rule does not apply.
 
-1. For each test function in scope, name the behaviour it evaluates in one line, taken from the recommendation it came from. Generated test functions are usually named `test_integration` or `testUi`, which claim nothing — use the name only when it is specific enough to add something, and never treat a generic one as evidence the test has no single behaviour. Then scan `$2` and the expected responses for the code change tested.
+1. For each test function in scope, name the behaviour it evaluates in one line, taken from the recommendation it came from. A generated test function may carry a name that states its behaviour — trust that name when it does. A function still named `test_integration` or `testUi` claims nothing, so use the name only when it is specific enough to add something, and never treat a generic one as evidence the test has no single behaviour. Then scan `$2` and the expected responses for the code change tested.
 2. Classify each response first by its response status type and then assign the applicable assertion rules to the response.
    - Success with body (2xx with a response body): all assertion rules below may apply — echo-back of request fields, computed response fields, array / items validation, and chained values across steps.
    - Success with no body (200/202/204 with an empty body — e.g. logout/cancel/submit action endpoints): assert the status code only. Also apply chained-values rules if a follow-up step uses this response's ID.

package/plugin/skills/enhance-assertions/reference/ui.md

@@ -126,7 +126,7 @@ if (await existingSecret.isVisible().catch(() => false)) {
 
 Before editing `$2`, you must output a `<thinking>` block. It states the behaviour each test evaluates, then works through the rules for the items that behaviour depends on, so no rule that applies is overlooked. The JSON array should match the template below — every assertion category and every rule title under it must appear as a key, with `[]` where the rule does not apply.
 
-1. For each test in scope, name the behaviour it evaluates in one line, taken from the recommendation it came from, and name the page where that behaviour shows. Generated specs are usually named `testUi`, which claims nothing — use the name only when it is specific enough to add something.
+1. For each test in scope, name the behaviour it evaluates in one line, taken from the recommendation it came from, and name the page where that behaviour shows. A generated spec may carry a title that names its behaviour — trust that title when it does. A spec still named `testUi` claims nothing, so use the name only when it is specific enough to add something.
 2. Selector inventory — list every selector already present in `$2` (`data-testid`, role + name, text, label, etc.). New assertions may use only selectors from this list. An assertion the recorder dropped because it failed during recording may use the selector of the element named in that recording's blueprint capture. Do not invent `data-testid` values, role names, or aria attributes. Also note captured network responses, repeated element patterns, exact rendered text/value/attribute from trace/source, and existing `toBeVisible()` assertions whose exact text is knowable.
 3. Process — Replay → Identify → Fix or Add — walk through these three steps explicitly.
    a. Replay the scenario mentally. At each state-changing action (form submit, item add/edit/delete), ask: "What is the EXPECTED outcome based on the action performed?"
@@ -206,7 +206,7 @@ expect(trigger).to_be_focused()
 When the PR changes how an element looks or where it sits (colour, class, size, `flex-direction`, a moved block), assert the changed property on the element that OWNS it — `flex-direction` belongs to the flex container, not the clicked child, and an order check needs both compared elements. Use a selector already in the file; if the owner has none, report a recording gap in your `<thinking>` block — do not invent one or screenshot it.
 
 - Colour / class: a class assertion recorded at capture is already written as a bounded regex (`toHaveClass(/(^|\s)bg-blue-600(\s|$)/)`) — leave it as generated. Use `toContainClass('bg-blue-600')` only for a class assertion you add yourself (1.52+; it matches one token, unlike a bare `/bg-blue-600/` which also passes on `hover:bg-blue-600`). For a style, `toHaveCSS('background-color', <the value the app computes>)` — take it from the app, do not convert the diff's hex: Tailwind v4 serializes `oklch(...)`, not `rgb(...)`.
-- Order: compare both elements' `boundingBox()` on the changed axis (holds for `flex-direction` / `order` / `dir` / grid); `toHaveCSS('flex-direction', 'row-reverse')` only when the container is `display: flex` with an unconditional class.
+- Order: an order assertion recorded at capture (`browser_assert` type `order`) is already in the file as two `boundingBox()` reads compared on one axis (inside `expect(async () => …).toPass()` in TS/JS) — leave it as generated. When none was recorded, add that comparison on the changed axis (holds for `flex-direction` / `order` / `dir` / grid / reordered markup): wait for both elements, read each one's box (`const aBox = await a.boundingBox()`), then compare the boxes' `x` (left/right) or `y` (above/below), e.g. `expect(aBox.x).toBeLessThan(bBox.x)` for "a left of b" — a locator itself has no `.x`; `toHaveCSS('flex-direction', 'row-reverse')` only when the container is `display: flex` with an unconditional class.
 - Size: `toHaveCSS('width', <the computed width>)`. Name the value; never copy a `...` or `/…/` placeholder.
 
 A `toHaveScreenshot()` baseline is right only for a look no property expresses (image, gradient, chart) or to refresh an already-committed baseline (SKYR-4298) — never a new one for a colour, class or order change.

package/plugin/skills/fix-test-import-errors/SKILL.md

@@ -56,7 +56,7 @@ python3 -m robot <robot-file>.robot
 
 Inspect package.json before installing anything:
 
-- If a required package is already declared, install from the existing manifest without changing its version.
+- If a required package is already declared, install from the existing manifest without changing its version, unless `skyramp_execute_test` refuses the run over an older Skyramp SDK. Then do what the refusal says.
 - If no JavaScript/TypeScript manifest exists at the test project root, create `package.json` with only `{ "devDependencies": {} }` before adding the missing approved package.
 - If an approved package is missing, add it with the repository's package manager as a devDependency. For npm, use `npm install --save-dev --legacy-peer-deps <package>`.
 - Never add, upgrade, or downgrade Playwright or @playwright/test when either is already declared. If its version is incompatible with Skyramp, report the conflict.

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.