@rolepod/uiproof 0.4.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "rolepod-uiproof",
+  "interface": {
+    "displayName": "Rolepod UIProof",
+    "shortDescription": "UI verification, a11y audits, visual diff, e2e scaffolding for AI coding agents.",
+    "developerName": "nuttaruj",
+    "websiteURL": "https://github.com/nuttaruj/rolepod-uiproof"
+  },
+  "plugins": [
+    {
+      "name": "rolepod-uiproof",
+      "source": {
+        "source": "local",
+        "path": "./plugins/rolepod-uiproof"
+      },
+      "policy": {
+        "installation": "AVAILABLE"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "rolepod-uiproof",
+  "description": "Multi-platform UI / mobile automation MCP server + 4 shipped skills (verify-ui, audit-a11y, visual-diff, scaffold-e2e) for AI coding agents.",
+  "owner": {
+    "name": "nuttaruj",
+    "url": "https://github.com/nuttaruj"
+  },
+  "plugins": [
+    {
+      "name": "rolepod-uiproof",
+      "source": "./",
+      "description": "15 MCP tools (10 atomic browser/mobile primitives + 5 composite workflows) + 4 user-invocable skills. Web production-ready via Playwright; mobile (iOS/Android) via Appium scaffolded — see `rolepod-uiproof doctor` for readiness.",
+      "version": "0.4.0",
+      "author": {
+        "name": "nuttaruj"
+      },
+      "homepage": "https://github.com/nuttaruj/rolepod-uiproof",
+      "repository": "https://github.com/nuttaruj/rolepod-uiproof",
+      "license": "MIT",
+      "category": "productivity",
+      "tags": [
+        "mcp",
+        "ui-automation",
+        "playwright",
+        "appium",
+        "accessibility",
+        "visual-regression",
+        "e2e",
+        "ai-agents"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "rolepod-uiproof",
+  "version": "0.4.0",
+  "description": "Multi-platform UI/mobile automation for AI agents — 4 shipped skills (verify-ui, audit-a11y, visual-diff, scaffold-e2e) + MCP server with 15 tools. v0.3 adds AppiumEngine scaffolding for iOS/Android, scope={ref} audit, replay CLI, ddmin minimization, doctor + install:mobile.",
+  "author": {
+    "name": "nuttaruj",
+    "url": "https://github.com/nuttaruj"
+  },
+  "homepage": "https://github.com/nuttaruj/rolepod-uiproof",
+  "repository": "https://github.com/nuttaruj/rolepod-uiproof.git",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "playwright",
+    "ui-automation",
+    "claude-code",
+    "verify-ui"
+  ],
+  "mcpServers": {
+    "rolepod-uiproof": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/uiproof"],
+      "env": {}
+    }
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,45 @@
+{
+  "name": "rolepod-uiproof",
+  "version": "0.4.0",
+  "description": "Multi-platform UI/mobile automation for AI agents — 4 shipped skills (verify-ui, audit-a11y, visual-diff, scaffold-e2e) + MCP server with 15 tools. v0.3 adds AppiumEngine scaffolding for iOS/Android; web is production-ready via Playwright.",
+  "author": {
+    "name": "nuttaruj",
+    "url": "https://github.com/nuttaruj"
+  },
+  "homepage": "https://github.com/nuttaruj/rolepod-uiproof",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nuttaruj/rolepod-uiproof"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "ui-automation",
+    "playwright",
+    "appium",
+    "axe-core",
+    "visual-regression"
+  ],
+  "skills": "./skills/",
+  "mcp_servers": {
+    "rolepod-uiproof": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/uiproof"],
+      "env": {}
+    }
+  },
+  "interface": {
+    "displayName": "Rolepod UIProof",
+    "shortDescription": "UI verification, a11y audits, visual diff, e2e scaffolding — for AI coding agents.",
+    "longDescription": "rolepod-uiproof ships an MCP server with 15 tools (10 atomic + 5 composite) and 4 user-invocable skills (/verify-ui, /audit-a11y, /visual-diff, /scaffold-e2e). Web is fully supported via Playwright; mobile (iOS/Android via Appium) lands in v0.3.",
+    "developerName": "nuttaruj",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write", "Bash"],
+    "websiteURL": "https://github.com/nuttaruj/rolepod-uiproof",
+    "defaultPrompt": [
+      "Use /verify-ui to drive a real browser through the change I just made and prove it works.",
+      "Use /audit-a11y to scan the page for WCAG-AA issues.",
+      "Use /scaffold-e2e to convert this verify run into a runnable Playwright test."
+    ]
+  }
+}

package/.cursor/mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "rolepod-uiproof": {
+      "command": "npx",
+      "args": ["-y", "@rolepod/uiproof"],
+      "env": {}
+    }
+  }
+}

package/.cursor-plugin/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "rolepod-uiproof",
+  "owner": {
+    "name": "nuttaruj"
+  },
+  "metadata": {
+    "description": "Multi-platform UI / mobile automation MCP server + 4 shipped skills for AI coding agents.",
+    "version": "0.4.0"
+  },
+  "plugins": [
+    {
+      "name": "rolepod-uiproof",
+      "source": ".",
+      "description": "15 MCP tools + 4 skills. Web (Playwright) production-ready; mobile (iOS/Android via Appium) scaffolded.",
+      "version": "0.4.0",
+      "author": {
+        "name": "nuttaruj"
+      },
+      "homepage": "https://github.com/nuttaruj/rolepod-uiproof",
+      "repository": "https://github.com/nuttaruj/rolepod-uiproof",
+      "license": "MIT",
+      "keywords": [
+        "mcp",
+        "ui-automation",
+        "playwright",
+        "appium",
+        "accessibility",
+        "ai-agents"
+      ]
+    }
+  ]
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "rolepod-uiproof",
+  "displayName": "Rolepod UIProof",
+  "version": "0.4.0",
+  "description": "Multi-platform UI / mobile automation MCP server + 4 shipped skills (verify-ui, audit-a11y, visual-diff, scaffold-e2e) for AI coding agents. Web production-ready via Playwright; mobile (iOS/Android via Appium) scaffolded.",
+  "author": {
+    "name": "nuttaruj"
+  },
+  "homepage": "https://github.com/nuttaruj/rolepod-uiproof",
+  "repository": "https://github.com/nuttaruj/rolepod-uiproof",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "ui-automation",
+    "playwright",
+    "appium",
+    "accessibility",
+    "visual-regression",
+    "e2e",
+    "cursor"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,310 @@
+# Changelog
+
+All notable changes to this project are recorded here. Versions follow
+[Semantic Versioning](https://semver.org/). The schema-stability promise
+begins at **v1.0**; until then, breaking changes are possible at any
+release.
+
+## [Unreleased]
+
+## [0.4.0] — 2026-05-24
+
+**Breaking: project renamed `rolepod-mcp` → `rolepod-uiproof`.**
+
+Reason: `rolepod-mcp` was too generic for the planned ecosystem
+(`rolepod-uiproof`, `rolepod-apiproof`, `rolepod-perfproof`,
+`rolepod-secproof` — each a focused "proof of X" MCP). Locking the
+generic `-mcp` suffix on the UI/mobile project blocked sibling
+naming. Done now while public adoption is effectively zero
+(<6 hours since first publish).
+
+### Renamed
+
+| Surface | Before | After |
+|---|---|---|
+| npm package | `@rolepod/mcp` | `@rolepod/uiproof` |
+| GitHub repo | `nuttaruj/rolepod-mcp` | `nuttaruj/rolepod-uiproof` |
+| Plugin name | `rolepod-mcp` | `rolepod-uiproof` |
+| Marketplace name | `rolepod-mcp` | `rolepod-uiproof` |
+| Display name | `Rolepod MCP` | `Rolepod UIProof` |
+| CLI bin | `rolepod-mcp` | `rolepod-uiproof` |
+| Artifact dir | `./.rolepod-mcp/` | `./.rolepod-uiproof/` |
+| Server name constant | `rolepod-mcp` | `rolepod-uiproof` |
+
+### Unchanged (deliberate)
+
+- **MCP tool names stay `rolepod_*`** — these are the org namespace
+  (per the project's tool-naming convention), not the project name.
+  Sibling MCPs will register their own sub-namespaces (`rolepod_api_*`,
+  `rolepod_perf_*`) without collisions.
+- The 4 shipped skills' slugs stay `/verify-ui`, `/audit-a11y`,
+  `/visual-diff`, `/scaffold-e2e`.
+- All input/output schemas unchanged.
+
+### Migration
+
+**npm consumers:**
+
+```bash
+npm uninstall @rolepod/mcp
+npm install @rolepod/uiproof
+```
+
+`@rolepod/mcp@0.3.x` is deprecated on npm with a pointer to
+`@rolepod/uiproof`. Existing installs continue to work but will print
+a deprecation notice.
+
+**Claude Code marketplace:**
+
+```bash
+claude plugin uninstall rolepod-mcp@rolepod-mcp
+claude plugin marketplace remove rolepod-mcp
+claude plugin marketplace add nuttaruj/rolepod-uiproof
+claude plugin install rolepod-uiproof@rolepod-uiproof
+```
+
+**Codex CLI:**
+
+```bash
+codex plugin remove rolepod-mcp@rolepod-mcp
+codex plugin marketplace remove rolepod-mcp
+codex plugin marketplace add nuttaruj/rolepod-uiproof
+codex plugin add rolepod-uiproof@rolepod-uiproof
+```
+
+**Cursor workspace MCP** — re-pull `.cursor/mcp.json`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nuttaruj/rolepod-uiproof/main/.cursor/mcp.json -o .cursor/mcp.json
+```
+
+**Artifact baselines** — if you have `./.rolepod-mcp/baselines/<id>.png`
+files from earlier runs, move them under the new path so visual_diff
+finds them:
+
+```bash
+mv .rolepod-mcp .rolepod-uiproof
+```
+
+**GitHub URLs** — `nuttaruj/rolepod-mcp` returns a permanent 301
+redirect to the new URL; existing clones continue to work but should
+update their remote:
+
+```bash
+git remote set-url origin https://github.com/nuttaruj/rolepod-uiproof.git
+```
+
+## [0.3.1] — 2026-05-24
+
+First **live mobile smoke** completed end-to-end against a real iOS
+Simulator (iPhone 17, iOS 26.5) via Appium 3.4.2 + xcuitest driver
+11.7.1. Settings.app session opened, snapshot parsed to 161-node
+A11yNode tree (`application > navigationbar "Settings" > ...`),
+session closed cleanly. Doctor reports green for every check that
+matters on this host.
+
+### Fixed
+
+- `parseXcuiTestTree` + `parseUiAutomator2Tree`: skip XML declaration
+  (`<?xml ... ?>`) and processing instructions when picking the first
+  tag. Previously the declaration leaked into the tree as a synthetic
+  `?xml` node (e1) alongside the real `AppiumAUT` wrapper.
+
+### Verified live
+
+- `AppiumEngine.open()` against `com.apple.Preferences` on iOS
+  Simulator
+- `AppiumEngine.snapshot()` → `parseXcuiTestTree()` → 161 typed nodes
+- `AppiumEngine.close()` clean teardown
+
+### Notes
+
+- WebDriverAgent first-build takes 3-5 min via xcodebuild; subsequent
+  sessions reuse the cached WDA (~5s startup).
+- Appium daemon must run with `DEVELOPER_DIR` pointed at the full
+  Xcode app (not `/Library/Developer/CommandLineTools`) so the
+  iphonesimulator SDK is locatable. `rolepod-mcp install:mobile`
+  documents this.
+- Android UIAutomator2 smoke still pending — same fix applies to the
+  uiautomator2 parser preemptively.
+
+## [0.3.0] — 2026-05-24
+
+Mobile scaffolding + CLI + governance. Web surface unchanged. Mobile
+code paths compile and the AT normalizers are unit-tested against
+fixture XML; real iOS/Android runs require a local Appium server +
+simulator and are gated by `npx rolepod-mcp doctor`.
+
+### Added
+
+- **AppiumEngine** (`src/engine/AppiumEngine.ts`) — full `Engine`
+  interface implementation backed by webdriverio + Appium 2.x.
+  Routes `platform: 'ios'` to XCUITest, `platform: 'android'` to
+  UIAutomator2. webdriverio is lazy-loaded as an
+  `optionalDependency`, so web-only installs skip it.
+- **Mobile AT normalizers** (`src/engine/a11y/xcuitest.ts`,
+  `uiautomator2.ts`) — inspired by alumnium (MIT) per D-005 and
+  `UPSTREAM_TRACKING.md`. Original implementations using
+  `fast-xml-parser`. Unit tests pass against fixture XML.
+- **`audit_a11y` scope={ref}** — tags the resolved element with a
+  temporary `data-rolepod-axe-scope` attribute so axe-core can
+  include it. Cleans up the tag in `finally`.
+- **`rolepod-mcp doctor`** — health check covering Node version,
+  Playwright Chromium install, webdriverio availability, Appium
+  server reachability, Xcode (macOS), Android SDK, artifact dir.
+- **`rolepod-mcp install:mobile`** — prints the iOS + Android setup
+  checklist with environment overrides.
+- **`rolepod-mcp replay <bundle.json>`** — re-runs a verify_ui_flow
+  replay bundle deterministically without an agent in the loop.
+  Exit code reflects pass/fail. Brings the v0.4 replay-execution
+  feature forward.
+- **`ddmin` minimization** (`src/replay/minimize.ts`) — classic
+  Zeller-Hildebrandt delta debugging. Replaces the v0.2 linear pass
+  inside `verify_ui_flow` reproduce mode.
+- **Per-CLI manifests** — `.cursor/mcp.json` (verified against
+  [cursor.com/docs/mcp](https://cursor.com/docs/mcp)) and
+  `.codex-plugin/plugin.json` (matches parent `rolepod`'s pattern).
+  Gemini deferred until the official schema is published.
+- **Governance documents** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`
+  (Contributor Covenant 2.1, fetched canonically from
+  EthicalSource), `SECURITY.md` (responsible disclosure via GitHub
+  Security Advisories).
+- **`.github/` templates** — bug + feature issue forms (verified
+  against the GitHub Issue Forms schema), PR template, CI workflow
+  for Node 20/22 × ubuntu/macos/windows running typecheck + tests +
+  build + smoke handshake.
+- **Public docs** — `docs/sessions.md`, `docs/artifacts.md`, plus
+  three recipes in `docs/recipes/`.
+- **`UPSTREAM_TRACKING.md`** — records the alumnium commit SHA
+  referenced (`94dea1e69…`), the inspired-by vs. literal-fork
+  decision, and the quarterly cherry-pick policy.
+
+### Changed
+
+- `SessionRegistry` now tracks `platform` per `session_id`
+  authoritatively via `platformOf(sessionId)`. Atomic tools and
+  composites consult it instead of hardcoding `'web'`.
+- `bin/rolepod-mcp` dispatches subcommands (`serve` default,
+  `doctor`, `install:mobile`, `replay`, `--version`, `--help`).
+- `factory.ts` splits `createWebEngine` + `createMobileEngine`;
+  `createEngine` is kept as a back-compat alias for v0.1 callers.
+
+### Not yet verified — mapped to later milestones
+
+- **Mobile end-to-end runs** — same Appium contract as alumnium;
+  needs a local Appium daemon + iOS Simulator (or Android Emulator,
+  or real device). `npx rolepod-mcp doctor` reports readiness.
+  Code paths compile and AT normalizers are unit-tested against
+  fixture XML; live simulator smoke is the v0.3.x test-maturity
+  task. Scope: still **v0.3**.
+- **SeleniumEngine** — deferred to **v0.4** (legacy Selenium grid
+  support, opt-in via `ROLEPOD_MCP_WEB_ENGINE=selenium`). Not
+  implemented because verifying it needs a running grid we don't
+  have access to in this session.
+- **Replay execution beyond what v0.4 specifies** — recording +
+  ddmin minimization shipped in v0.3 (the `rolepod-mcp replay`
+  CLI re-runs a bundle without an agent in the loop). Full
+  replay-determinism guarantees, schema freeze of the bundle
+  format, and forward-compat across versions are still **v0.4**
+  scope.
+- **Docs site, blog post, MCP server directory submission, npm
+  publish, GitHub publish** — these are **v0.5** open-source
+  launch tasks. They require user action (account ownership,
+  registration, narrative writing) and are not in-session
+  deliverables.
+- **Adoption metrics** (1k weekly downloads, 3+ external
+  contributors, third-party integration documented) — **v1.0**
+  exit criteria. Time and market dependent; cannot be produced
+  inside an implementation session.
+
+## [0.2.0] — 2026-05-24
+
+Web surface complete. Mobile still deferred to v0.3.
+
+### Added
+
+- **Atomic tools (5 new, 10 total):** `rolepod_browser_key`,
+  `rolepod_browser_scroll`, `rolepod_browser_wait_for`,
+  `rolepod_browser_screenshot`, `rolepod_browser_navigate`.
+- **Composite tools (4 new, 5 total):** `rolepod_audit_a11y` (via
+  `@axe-core/playwright`), `rolepod_visual_diff` (via `pixelmatch` +
+  `pngjs`), `rolepod_scaffold_e2e` (playwright-test / vitest+playwright
+  / pytest+selenium codegen), `rolepod_extract_ui_state` (internal
+  helper — no LLM).
+- **`verify_ui_flow` mode='reproduce'** with linear-pass step
+  minimization (D-025).
+- **3 new shipped skills:** `/audit-a11y`, `/visual-diff`,
+  `/scaffold-e2e`. All single-backend with no fallback (D-024).
+- **Schema export:** `npm run build:schemas` emits
+  `dist/schemas/tools.json` (JSON-Schema 2019-09) for every
+  `rolepod_*` tool.
+- **Skill lint:** `tests/lint/skills.test.ts` enforces frontmatter,
+  required body sections, single-backend tool reference, and absence of
+  fallback markers.
+
+### Changed
+
+- `ArtifactStore` now also writes report files (`.json`/`.md`) and raw
+  bytes, and exposes `baselineDir` for `visual_diff`.
+- `PlaywrightEngine` exposes `getPageForSession()` as an escape hatch
+  for web-only composites that need raw Page APIs.
+- `SessionRegistry.open` throws `unsupported_platform` (was
+  `unknown_session`) when no engine is registered for the requested
+  platform.
+
+### Notes
+
+- `mode='reproduce'` evaluates `expect` exactly the same way as
+  `mode='assert'` — the user phrases assertions in terms of the bug
+  surfacing. Minimization is a naive linear pass; ddmin is deferred to
+  v0.3.
+- `audit_a11y` currently supports `scope: 'page'` only;
+  `scope: { ref }` is scheduled for v0.3 (returns
+  `not_implemented_in_v02`).
+- `extract_ui_state` returns the AT subtree and matched refs; the Lead
+  interprets the answer. No LLM is invoked inside the MCP server
+  (D-004).
+- The `alumnium` driver fork (D-005) is still **not** in this release.
+  Web continues to rely on Playwright's built-in `ariaSnapshot({mode:
+  'ai'})` + `aria-ref` locator. The fork lands with mobile in v0.3.
+
+## [0.1.0] — 2026-05-24
+
+Proof of concept. Single composite, single engine, single platform.
+
+### Added
+
+- Plugin manifest for Claude Code (`.claude-plugin/plugin.json`) with
+  `mcpServers` declaration (verified against
+  [docs](https://code.claude.com/docs/en/plugins-reference)).
+- MCP server skeleton via `@modelcontextprotocol/sdk@1.29.0` with
+  stdio transport.
+- `Engine` interface (`src/engine/Engine.ts`) and `PlaywrightEngine`
+  implementation (web only).
+- A11y normalization via Playwright 1.60's
+  `page.ariaSnapshot({mode:'ai'})` + `aria-ref=eN` locator. (Note:
+  Playwright 1.60 removed `page.accessibility`, hence the migration.)
+- 5 atomic MCP tools: `rolepod_browser_open` / `_close` / `_snapshot`
+  / `_click` / `_type`.
+- 1 composite tool: `rolepod_verify_ui_flow` (mode='assert' only;
+  mode='reproduce' deferred to v0.2 per D-025).
+- 1 shipped skill: `/verify-ui` (single-backend, no fallback per
+  D-024).
+- `ArtifactStore` writing under `./.rolepod-mcp/artifacts/{run_id}/`
+  per D-026 (renamed from `./.rolepod/`).
+- `SessionRegistry` with per-platform engine routing and idle-timeout
+  cleanup.
+- `bin/rolepod-mcp` stdio entry; `npx rolepod-mcp` launches the
+  server.
+- Vitest smoke suite (`tests/smoke/example_com.test.ts`) — 6 tests
+  against `https://example.com`.
+- Manual MCP handshake smoke (`tests/smoke/mcp_handshake.mjs`).
+- MIT license; `THIRD_PARTY.md` notes the future alumnium fork plan
+  and runtime dependency licenses.
+
+### Known limitations
+
+- Web only. Mobile (iOS / Android via Appium) lands in v0.3.
+- `mode='reproduce'` not implemented (handler returns
+  `not_implemented_in_v01`).
+- No alumnium driver fork yet — see v0.2 notes above.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nuttaruj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.