@rolepod/uiproof 0.4.0

package/skills/scaffold-e2e/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: scaffold-e2e
+description: Generate a runnable e2e test file (playwright-test, vitest+playwright, or pytest+selenium) from a scenario description plus an optional replay bundle from a prior /verify-ui run.
+---
+
+# /scaffold-e2e
+
+Single-backend skill. Calls **`rolepod_scaffold_e2e`** on the rolepod-uiproof
+MCP server. No fallback (D-024).
+
+## When to use
+
+- The user asks to generate an e2e test for a flow they just verified
+  interactively.
+- A replay bundle from `/verify-ui` exists and should be transcribed into
+  a real test file.
+
+## When NOT to use
+
+- A unit or integration test is sufficient — pick a closer framework
+  manually.
+- The scenario is too vague to scaffold — ask the user to clarify before
+  calling.
+
+## Inputs
+
+- `framework` — `playwright-test` | `vitest+playwright` | `pytest+selenium`.
+- `scenario_nl` — natural-language description of the scenario.
+- `url` — entry URL.
+- `recorded_bundle` *(optional)* — path to a replay bundle from a prior
+  `/verify-ui` run; when present, steps and expectations are transcribed.
+- `filename` *(optional)* — override the generated file name.
+
+## Outputs
+
+- `run_id` — folder under `./.rolepod-uiproof/artifacts/`.
+- `test_file_path` — path to the generated test file.
+- `language` — `typescript` | `python`.
+- `dependencies` — packages the user needs to install.
+- `setup_notes` — what to run after install.
+- `from_replay_bundle` — boolean indicating whether the file was
+  transcribed from a recorded run.
+
+## Process
+
+1. Build `rolepod_scaffold_e2e` input.
+2. Call the tool.
+3. Print the generated file path and the setup steps. Surface
+   `dependencies` as an install command.
+
+## If the tool is unavailable
+
+Surface plainly:
+
+> The `/scaffold-e2e` skill needs the **rolepod-uiproof** MCP server, which
+> is not currently available. Confirm the plugin is installed and try
+> again.
+
+Do not attempt another backend (D-024).
+
+## Examples
+
+### Transcribe a replay bundle to a Playwright Test file
+
+```json
+{
+  "framework": "playwright-test",
+  "scenario_nl": "user opens example.com and clicks Learn more",
+  "url": "https://example.com",
+  "recorded_bundle": ".rolepod-uiproof/artifacts/verify_…/replay.json"
+}
+```
+
+Returns:
+
+```json
+{
+  "run_id": "scaffold_…",
+  "test_file_path": ".rolepod-uiproof/artifacts/scaffold_…/user-opens-example-com-and-clicks-learn-more.spec.ts",
+  "language": "typescript",
+  "dependencies": ["@playwright/test"],
+  "setup_notes": "Install: npm i -D @playwright/test && npx playwright install. Run: npx playwright test.",
+  "from_replay_bundle": true
+}
+```

package/skills/verify-ui/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: verify-ui
+description: Drive a real browser session through steps and assert expected outcomes; save evidence under ./.rolepod-uiproof/artifacts/. Use when a diff changes visible behavior and code-level tests do not prove it. v0.1 web only.
+---
+
+# /verify-ui
+
+Single-backend skill. Calls **`rolepod_verify_ui_flow`** on the rolepod-uiproof
+MCP server and surfaces the structured result. No fallback (D-024) — if the
+tool is unavailable, this skill fails with a clear diagnostic so the caller
+(typically the user, or the parent `rolepod` plugin's `check-work` skill)
+can decide what to do next.
+
+## When to use
+
+- A diff changes user-visible behavior on a web target.
+- A URL is reachable (dev server is running, or the target is a deployed URL).
+- Code-level tests (unit, type-check, lint) do not prove the visible
+  outcome.
+
+## When NOT to use
+
+- Backend-only diffs (no UI change).
+- Doc, config, or build-tool changes with no behavior surface.
+- No dev server / target available — ask the user to spin one up first
+  before invoking.
+- iOS / Android targets — mobile ships in v0.3 (`platform: 'ios' | 'android'`).
+
+## Modes
+
+- `mode: 'assert'` (default) — the assertions describe what the **feature
+  should do**; pass = feature works.
+- `mode: 'reproduce'` — the assertions describe what the **bug looks like**;
+  pass = bug reproduces. When `minimize: true` (default) the tool then
+  removes steps one-by-one to find the shortest still-reproducing sequence
+  and writes a `replay-minimized.json` bundle next to `replay.json`.
+
+## Inputs
+
+- `target` — the URL to open (web only in v0.1).
+- `steps` — ordered UI actions. Each is one of:
+  - `{ kind: 'click', query: <accessible name substring> }`
+  - `{ kind: 'type', query: <accessible name substring>, text: <string>, clear_first?: boolean }`
+  - `{ kind: 'key', key: <e.g. 'Enter'> }`
+  - `{ kind: 'wait_for', condition: { kind, ... } }`
+  - `{ kind: 'navigate', url: <string> }`
+- `expect` — ordered assertions. Each is one of:
+  - `{ kind: 'text_visible', text: <string> }`
+  - `{ kind: 'text_absent', text: <string> }`
+  - `{ kind: 'url_matches', pattern: <regex string> }`
+  - `{ kind: 'ref_in_state', query: <accessible name substring>, state: 'visible' | 'enabled' | 'focused' }`
+- `capture` *(optional)* — defaults to `['screenshot']`. v0.1 only emits
+  screenshots and a replay bundle; HAR / console / video land in later
+  milestones.
+- `close_on_finish` *(optional)* — defaults to `true`.
+
+## Outputs
+
+- `run_id` — folder name under `./.rolepod-uiproof/artifacts/`.
+- `passed` — boolean.
+- `failed_at_step` *(when not passed)* — 0-based step index.
+- `failure_reason` *(when not passed)* — human-readable explanation.
+- `evidence_paths` — `{ screenshots: string[], replay_bundle?: string }`.
+- `final_url_or_screen` — page URL at the end of the run.
+
+## Process
+
+1. Construct a `rolepod_verify_ui_flow` input from the user's intent:
+   - `mode: 'assert'`
+   - `open: { platform: 'web', url: <target> }`
+   - `steps`, `expect`, `capture`, `close_on_finish` per inputs above.
+2. Call the tool.
+3. Report the structured result. If `passed: false`, include
+   `failed_at_step`, `failure_reason`, and the screenshot path so the user
+   can inspect the failure.
+
+## If the tool is unavailable
+
+The rolepod-uiproof MCP server is not registered or is not responding. Surface
+this plainly:
+
+> The `/verify-ui` skill needs the **rolepod-uiproof** MCP server, which is
+> not currently available. Confirm the plugin is installed and try again,
+> or check that `npx -y @rolepod/uiproof` is reachable.
+
+Do **not** attempt this work via Playwright MCP, Chrome DevTools MCP, or
+any other backend from inside this skill. Multi-backend routing is the
+job of the parent `rolepod` plugin's `check-work` / `debug-issue` skills
+(D-024).
+
+## Examples
+
+### Success — verify a search result on example.com
+
+User: "Verify that opening https://example.com shows the heading 'Example
+Domain' and links to iana.org."
+
+Skill invokes `rolepod_verify_ui_flow` with:
+
+```json
+{
+  "mode": "assert",
+  "open": { "platform": "web", "url": "https://example.com" },
+  "steps": [],
+  "expect": [
+    { "kind": "text_visible", "text": "Example Domain" },
+    { "kind": "text_visible", "text": "More information" }
+  ]
+}
+```
+
+Returns:
+
+```json
+{
+  "run_id": "verify_20260524T101512_a1b2c3d4",
+  "passed": true,
+  "evidence_paths": {
+    "screenshots": [".rolepod-uiproof/artifacts/verify_…/final.png"],
+    "replay_bundle": ".rolepod-uiproof/artifacts/verify_…/replay.json"
+  },
+  "final_url_or_screen": "https://example.com/"
+}
+```
+
+### Failure — MCP server not available
+
+The MCP server is not registered. The skill returns:
+
+> The `/verify-ui` skill needs the **rolepod-uiproof** MCP server, which is
+> not currently available. Confirm the plugin is installed and try again.
+
+No other backend is attempted. The caller decides whether to escalate to
+the parent rolepod plugin's `check-work` skill.

package/skills/visual-diff/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: visual-diff
+description: Capture a screenshot of the current UI and compare against a stored baseline under ./.rolepod-uiproof/baselines/. First capture for a baseline_id seeds the baseline; subsequent capture diffs it.
+---
+
+# /visual-diff
+
+Single-backend skill. Calls **`rolepod_visual_diff`** on the rolepod-uiproof
+MCP server. No fallback (D-024).
+
+## When to use
+
+- Detecting visual regressions against a known-good baseline.
+- Verifying a CSS / styling change does not perturb unrelated elements.
+
+## When NOT to use
+
+- No baseline exists yet AND the user is not OK with this run becoming
+  the baseline (the first call always seeds).
+- The page has highly dynamic content (rotating banners, timestamps,
+  animations) — the diff will be noisy. Either freeze the dynamic content
+  via a flag or pick a different verification approach.
+
+## Inputs
+
+- `target` — URL.
+- `baseline_id` — short stable name (e.g. `homepage-light`, `checkout-success`).
+- `viewport` — optional `{ width, height }` so the baseline and the current
+  capture share dimensions. Default uses the browser's natural viewport.
+- `threshold_pct` — tolerated diff fraction. Default `0.1` (= 10%).
+- `pixel_threshold` — pixelmatch sensitivity 0..1. Default `0.1`.
+
+## Outputs
+
+- `run_id` — folder under `./.rolepod-uiproof/artifacts/`.
+- `diff_pct` — fraction of differing pixels.
+- `passed` — `diff_pct <= threshold_pct`.
+- `baseline_path`, `current_path`, `diff_image_path`.
+
+## Process
+
+1. Build `rolepod_visual_diff` input from the user's intent.
+2. Call the tool.
+3. Report `diff_pct`, `passed`, and the three image paths. If the baseline
+   was just seeded, say so explicitly.
+
+## If the tool is unavailable
+
+Surface plainly:
+
+> The `/visual-diff` skill needs the **rolepod-uiproof** MCP server, which is
+> not currently available. Confirm the plugin is installed and try again.
+
+Do not attempt another backend (D-024).
+
+## Examples
+
+### Seed a baseline then diff
+
+First run:
+
+```json
+{
+  "open": { "platform": "web", "url": "https://example.com" },
+  "baseline_id": "example-home",
+  "viewport": { "width": 1280, "height": 720 }
+}
+```
+
+Returns `passed: true, diff_pct: 0, note: "Baseline did not exist…"`.
+
+Second run (after a CSS change) returns `passed: false, diff_pct: 0.18,
+diff_image_path: …diff.png`.