@mcptoolshop/accessibility-suite 0.1.0 → 0.2.0

package/README.md

@@ -1,37 +1,216 @@
-# accessibility-suite
+<p align="center">
+  <img src="logo.png" width="200" alt="accessibility-suite">
+</p>
 
-Unified monorepo for accessibility testing, evidence generation, and compliance tooling.
+<h1 align="center">accessibility-suite</h1>
+
+<p align="center">
+  Six tools. One mission: make accessibility testing verifiable, automated, and hard to ignore.
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/accessibility-suite/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
+  <a href="https://mcptoolshop.com"><img src="https://img.shields.io/badge/part%20of-MCP%20Tool%20Shop-black" alt="Part of MCP Tool Shop"></a>
+</p>
+
+---
+
+## At a Glance
+
+Most accessibility tools stop at "you have 12 violations." The Accessibility Suite goes further: it captures tamper-evident evidence of what was tested, gates your CI pipeline on regressions, and surfaces fix guidance tuned for low-vision, screen-reader, dyslexia, and cognitive-load profiles.
+
+The suite spans the full lifecycle -- lint CLI output for accessible patterns, scan HTML for WCAG violations with cryptographic provenance, enforce quality gates in CI, and expose everything through MCP so AI assistants can participate in the remediation loop.
+
+**Key principles:**
+
+- **Evidence over assertions** -- every finding is backed by a prov-spec provenance record with SHA-256 integrity digests
+- **Low-vision-first output** -- all CLI tools use the `[OK]/[WARN]/[FAIL] + What/Why/Fix` contract
+- **Deterministic** -- same input always produces identical output; no network calls, no randomness
+- **CI-native** -- exit codes, scorecard JSON, and PR comments designed for automated pipelines
+
+---
 
 ## Projects
 
-| Project | Description | Tech |
-|---------|-------------|------|
-| `src/a11y-assist/` | Accessibility testing assistant | Python |
-| `src/a11y-ci/` | CI/CD integration for accessibility checks | Python |
-| `src/a11y-lint/` | Accessibility linter | Python |
-| `src/a11y-evidence-engine/` | Evidence generation and reporting | Node.js |
-| `src/a11y-mcp-tools/` | MCP server tools for accessibility | Node.js |
-| `examples/a11y-demo-site/` | Demo site for testing | HTML |
-| `docs/prov-spec/` | Provenance specification | Spec |
+| Project | Description | Stack | Package |
+|---------|-------------|-------|---------|
+| [a11y-lint](src/a11y-lint/) | Accessibility linter for CLI output -- validates error messages follow accessible patterns | Python 3.10+ | [PyPI](https://pypi.org/project/a11y-lint/) |
+| [a11y-ci](src/a11y-ci/) | CI gate for accessibility scorecards with regression detection and allowlists | Python 3.10+ | [PyPI](https://pypi.org/project/a11y-ci/) / [npm](https://www.npmjs.com/package/@mcptoolshop/a11y-ci) |
+| [a11y-assist](src/a11y-assist/) | Low-vision-first CLI assistant with five accessibility profiles | Python 3.10+ | [PyPI](https://pypi.org/project/a11y-assist/) |
+| [a11y-evidence-engine](src/a11y-evidence-engine/) | Headless HTML scanner with prov-spec provenance records | Node.js 18+ | [npm](https://www.npmjs.com/package/@mcptoolshop/a11y-evidence-engine) |
+| [a11y-mcp-tools](src/a11y-mcp-tools/) | MCP server for accessibility evidence capture and diagnosis | Node.js 18+ | [npm](https://www.npmjs.com/package/@mcptoolshop/a11y-mcp-tools) |
+| [a11y-demo-site](examples/a11y-demo-site/) | Demo site with intentional violations for end-to-end testing | HTML | -- |
+
+---
 
 ## Quick Start
 
+### Lint CLI output for accessible patterns
+
+```bash
+pip install a11y-lint
+a11y-lint scan output.txt
+```
+
+### Gate your CI on accessibility regressions
+
+```bash
+pip install a11y-ci
+a11y-lint scan . --artifact-dir .a11y_artifacts
+a11y-ci gate --artifact-dir .a11y_artifacts
+```
+
+### Scan HTML and capture provenance
+
+```bash
+npm install -g @mcptoolshop/a11y-evidence-engine
+a11y-engine scan ./html --out ./results
+```
+
+### Get fix guidance for a CLI failure
+
+```bash
+pip install a11y-assist
+a11y-assist explain --json error.json --profile screen-reader
+```
+
+### Capture evidence and diagnose via MCP
+
+```bash
+npm install -g @mcptoolshop/a11y-mcp-tools
+a11y evidence --target page.html --dom-snapshot --out evidence.json
+a11y diagnose --bundle evidence.json --verify-provenance --fix
+```
+
+### Run the demo site end-to-end
+
 ```bash
-# Clone
-git clone https://github.com/mcp-tool-shop-org/accessibility-suite.git
-cd accessibility-suite
+cd examples/a11y-demo-site
+./scripts/a11y.sh
+```
+
+---
+
+## Architecture
+
+The six tools form a pipeline from detection through remediation:
+
+```
+                        CLI output                HTML files
+                            |                         |
+                    +-------v-------+        +--------v---------+
+                    |   a11y-lint   |        | a11y-evidence-   |
+                    | (scan & score)|        | engine (scan +   |
+                    +-------+-------+        | provenance)      |
+                            |                +--------+---------+
+                  scorecard.json                      |
+                            |               evidence bundle
+                    +-------v-------+                 |
+                    |    a11y-ci    |        +---------v---------+
+                    |  (CI gate +  |        |  a11y-mcp-tools   |
+                    |  PR comment) |        | (MCP evidence +   |
+                    +-------+-------+        |  diagnosis)      |
+                            |                +---------+---------+
+                    pass / fail                        |
+                            |                  findings + fixes
+                    +-------v-------+                 |
+                    |  a11y-assist  |<----------------+
+                    | (fix guidance |
+                    |  5 profiles)  |
+                    +---------------+
+```
+
+**Data flow:**
+
+1. **a11y-lint** scans CLI text for accessible error message patterns and produces a scorecard
+2. **a11y-evidence-engine** scans HTML files and emits findings with prov-spec provenance records
+3. **a11y-ci** consumes scorecards, enforces thresholds, detects regressions, and generates PR comments
+4. **a11y-mcp-tools** wraps evidence capture and diagnosis as MCP tools for AI assistant integration
+5. **a11y-assist** takes findings (structured JSON or raw text) and generates fix guidance in five accessibility profiles
+6. **a11y-demo-site** ties it all together as a runnable example with intentional violations
+
+**Shared contracts:**
+
+- `cli.error.schema.v0.1.json` -- structured error format across all Python tools
+- `evidence.bundle.schema.v0.1.json` -- evidence bundles with provenance chains
+- `.a11y_artifacts/` -- unified artifact directory for CI pipelines
+- prov-spec method IDs -- stable, versioned identifiers for every provenance step
+
+---
+
+## MCP Client Configuration
+
+To connect a11y-mcp-tools to your MCP client (Claude Desktop, Cursor, VS Code, etc.):
 
-# Python tools (a11y-assist, a11y-ci, a11y-lint)
-cd src/a11y-lint
-pip install -e .
-a11y-lint --help
+```json
+{
+  "mcpServers": {
+    "a11y": {
+      "command": "npx",
+      "args": ["-y", "@mcptoolshop/a11y-mcp-tools"]
+    }
+  }
+}
+```
+
+Or if installed globally:
 
-# Node.js tools (a11y-evidence-engine, a11y-mcp-tools)
-cd src/a11y-evidence-engine
-npm install
-npm test
+```json
+{
+  "mcpServers": {
+    "a11y": {
+      "command": "a11y-mcp"
+    }
+  }
+}
 ```
 
+The server exposes two tools:
+
+| Tool | Description |
+|------|-------------|
+| `a11y.evidence` | Capture tamper-evident evidence bundles from HTML, CLI logs, or other inputs |
+| `a11y.diagnose` | Run WCAG rule checks over evidence bundles with provenance verification |
+
+---
+
+## CI Integration (GitHub Actions)
+
+```yaml
+jobs:
+  accessibility:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Scan code
+        run: |
+          pip install a11y-lint
+          mkdir .a11y_artifacts
+          a11y-lint scan . --artifact-dir .a11y_artifacts
+
+      - uses: mcp-tool-shop-org/accessibility-suite/.github/actions/a11y-ci@main
+        with:
+          artifact-dir: .a11y_artifacts
+          fail-on: serious
+```
+
+See [GETTING_STARTED.md](GETTING_STARTED.md) for Azure DevOps examples and troubleshooting.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [HANDBOOK.md](HANDBOOK.md) | Architecture deep dive, integration patterns, and development guide |
+| [GETTING_STARTED.md](GETTING_STARTED.md) | Three-command local setup, CI templates, and troubleshooting |
+| [CHANGELOG.md](CHANGELOG.md) | Release history in Keep a Changelog format |
+| [docs/unified-artifacts.md](docs/unified-artifacts.md) | Unified artifact directory strategy |
+| [docs/prov-spec/](docs/prov-spec/) | Provenance specification |
+
+---
+
 ## License
 
-MIT
+[MIT](LICENSE)

package/docs/handbooks/A11Y-ASSIST.md

@@ -0,0 +1,31 @@
+# a11y-assist Handbook
+
+Deterministic assistance for fixing accessibility failures. Think: “given a known failure signature, suggest safe remediation steps.”
+
+## Quickstart
+
+**Install**
+```bash
+pip install -e src/a11y-assist
+```
+
+**Run**
+```bash
+a11y-assist help --rule "aria-required"
+```
+
+**Output**
+* Markdown remediation guide (stdout)
+
+## How it fits
+
+* `a11y-ci` tells you what failed and links to `docs/hints`
+* `a11y-assist` can turn that into guided remediation (rules-based, deterministic)
+
+## Recommended workflow
+
+1. Run `a11y-ci gate` and inspect `report.txt`
+2. Use `help_url` / `help_hint` fields to locate the rule
+3. Use `a11y-assist` for structured guidance (when available)
+
+**(More detail to be added once CLI is confirmed)**

package/docs/handbooks/A11Y-CI.md

@@ -0,0 +1,71 @@
+# a11y-ci Handbook
+
+The policy gate. It turns findings into a pass/fail decision, detects regressions, supports waivers, and produces evidence + PR comments.
+
+## Quickstart
+
+**Install**
+```bash
+pip install -e src/a11y-ci
+```
+
+**Run**
+```bash
+a11y-ci gate --artifact-dir .a11y_artifacts
+```
+
+**Output**
+* `.a11y_artifacts/gate-result.json`
+* `.a11y_artifacts/report.txt`
+* `.a11y_artifacts/evidence.json`
+
+**Common Failures**
+* `A11Y.CI.Schema.Invalid` (Exit 2): Scorecard JSON is mangled
+* `A11Y.CI.Gate.Failed` (Exit 3): Open violations found
+
+## Options
+
+### Set the severity threshold
+
+```bash
+a11y-ci gate --artifact-dir .a11y_artifacts --fail-on serious
+```
+
+### Use a baseline
+If `.a11y_artifacts/baseline.scorecard.json` exists, it is automatically used (unless overridden).
+
+### Use an allowlist (waivers)
+If `.a11y_artifacts/allowlist.json` exists, it is automatically used.
+
+**Allowlist supports:**
+* `owner` (required)
+* `expires` (required)
+* `ticket` (optional)
+* suppression identity via `id` or `fingerprint` (best)
+
+## Output formats
+
+### Human report
+`.a11y_artifacts/report.txt` is optimized for quick reading and low-vision clarity.
+
+### Machine report
+`.a11y_artifacts/gate-result.json` is stable and parseable.
+
+### Evidence bundle (MCP)
+`.a11y_artifacts/evidence.json` includes traceability metadata + hashes.
+
+### PR comments
+Generate from evidence (recommended):
+
+```bash
+a11y-ci comment --mcp .a11y_artifacts/evidence.json --platform github --top 10 > .a11y_artifacts/comment.md
+```
+
+## Error IDs and exit codes
+
+* `0`: PASS
+* `2`: Input error (schema, missing required file, etc.)
+* `3`: Gate failed (policy violation / regression / expired waiver)
+* `1`: Internal tool error
+
+Error IDs are standardized (grep-friendly). If you see an error, copy the ID into issues/PR discussions.

package/docs/handbooks/A11Y-DEMO-SITE.md

@@ -0,0 +1,29 @@
+# a11y-demo-site Handbook
+
+An end-to-end demo details page.
+
+## Quickstart
+
+**Install**
+```bash
+npm install
+```
+
+**Run**
+```bash
+npm run dev
+```
+
+**Output**
+* Localhost demo URL (e.g. `http://localhost:3000`)
+
+## What this is
+
+* See how evidence is generated
+* See how gates fail/pass
+* See PR comments
+
+## How to use it
+
+* Use it as the “golden tutorial”
+* Use it to validate new workflows or rules without touching production repos

package/docs/handbooks/A11Y-EVIDENCE-ENGINE.md

@@ -0,0 +1,31 @@
+# a11y-evidence-engine Handbook
+
+A headless engine that generates traceable, structured accessibility evidence (often beyond “a list of findings”), suitable for audits and verification.
+
+## Quickstart
+
+**Install**
+```bash
+pip install -e src/a11y-evidence-engine
+```
+
+**Run**
+```bash
+(Pending CLI finalization)
+```
+
+**Output**
+* Screenshots (`.png`)
+* DOM snapshots (`.html`)
+* `.a11y_artifacts/evidence-manifest.json`
+
+## Where it fits
+
+* `a11y-lint`: findings
+* `a11y-ci`: policy + regression + waivers
+* `a11y-evidence-engine`: traceable “proof artifacts” (screenshots, DOM snapshots), depending on what it supports
+
+## Best practice
+
+* Store evidence artifacts under `.a11y_artifacts/` (or a subfolder like `.a11y_artifacts/evidence/`)
+* Reference them from `evidence.json` so everything is linked and hashable

package/docs/handbooks/A11Y-LINT.md

@@ -0,0 +1,62 @@
+# a11y-lint Handbook
+
+The scanner/linter that produces accessibility findings and writes the canonical scorecard used by `a11y-ci`.
+
+## Quickstart
+
+**Install**
+```bash
+pip install -e src/a11y-lint
+```
+
+**Run**
+```bash
+a11y-lint scan docs --artifact-dir .a11y_artifacts
+```
+
+**Output**
+* `.a11y_artifacts/current.scorecard.json`
+* `.a11y_artifacts/result.json`
+
+**Common Failures**
+* `A11Y.SCAN.IO`: Input path does not exist
+* `A11Y.SCAN.SCHEMA`: Output directory not writable
+
+## Install
+
+**Source-of-truth:** Lives in `accessibility-suite` (standalone `a11y-lint` repo may be deprecated).
+**Recommended dev install:** Editable install from monorepo (e.g., `pip install -e src/a11y-lint`).
+
+## Usage
+
+### Standard mode (recommended)
+
+Writes outputs to `.a11y_artifacts/`:
+
+```bash
+a11y-lint scan --artifact-dir .a11y_artifacts
+```
+
+**Expected outputs:**
+* `.a11y_artifacts/current.scorecard.json`
+* `.a11y_artifacts/result.json`
+
+### Using a custom output directory
+
+```bash
+a11y-lint scan --artifact-dir path/to/output
+```
+
+## Output: scorecard schema
+
+`current.scorecard.json` follows the locked schema:
+
+* required `meta` object (tool, version)
+* required `findings[]`
+  * each finding: `id`, `severity`, `message` (+ optional `location`)
+
+## Troubleshooting
+
+If `a11y-ci` rejects your scorecard, validate that you’re writing:
+* `meta.tool`, `meta.version`
+* `findings[].id`, `findings[].severity`, `findings[].message`

package/docs/handbooks/A11Y-MCP-TOOLS.md

@@ -0,0 +1,34 @@
+# a11y-mcp-tools Handbook
+
+An MCP server/tooling layer for capturing and transporting accessibility evidence bundles.
+
+## Quickstart
+
+**Install**
+```bash
+pip install -e src/a11y-mcp-tools
+```
+
+**Run**
+```bash
+mcp-server-a11y --evidence-dir .a11y_artifacts
+```
+
+**Input**
+* `.a11y_artifacts/evidence.json`
+
+**Output**
+* MCP Resources (`a11y://evidence/...`)
+* MCP Prompts
+
+## Integration model
+
+Treat `evidence.json` as the “source packet”:
+* Store, index, or attach it to PR build artifacts
+* **Prefer hash-verified artifacts** (`a11y-ci` includes SHA256 hashes)
+
+## In practice
+
+Most teams:
+1. upload `.a11y_artifacts/` as CI artifacts
+2. optionally forward `evidence.json` to MCP tools for aggregation

package/docs/handbooks/ACCESSIBILITY-SUITE.md

@@ -0,0 +1,51 @@
+# Accessibility Suite Handbook
+
+This is the authoritative source for the entire suite. Most “standalone” repos are migrated here.
+
+**Handbooks track main. For released versions, refer to tagged docs.**
+
+**Also see:**
+* [Universal Concepts](COMMON-CONCEPTS.md)
+* [a11y-lint](A11Y-LINT.md)
+* [a11y-ci](A11Y-CI.md)
+* [a11y-mcp-tools](A11Y-MCP-TOOLS.md)
+* [a11y-assist](A11Y-ASSIST.md)
+* [a11y-evidence-engine](A11Y-EVIDENCE-ENGINE.md)
+* [a11y-demo-site](A11Y-DEMO-SITE.md)
+* [ally-demo-python](ALLY-DEMO-PYTHON.md)
+* [CursorAssist](CURSORASSIST.md)
+
+## Install (developer)
+
+Typical dev loop:
+
+1. Clone `mcp-tool-shop-org/accessibility-suite`
+2. Install tool packages from `src/…` (editable installs are preferred)
+
+If your tools are Python packages (likely for `a11y-ci`, `a11y-lint`):
+
+```bash
+# Install per-package from monorepo
+pip install -e src/<tool>
+```
+
+## Run (suite convention)
+
+From the repo root:
+
+```bash
+a11y-lint scan --artifact-dir .a11y_artifacts
+a11y-ci gate --artifact-dir .a11y_artifacts
+a11y-ci comment --mcp .a11y_artifacts/evidence.json --platform github > .a11y_artifacts/comment.md
+```
+
+## CI
+
+* **GitHub Actions:** `.github/workflows/a11y-gate.yml`
+* **Baseline update:** `.github/workflows/update-baseline.yml`
+* **Golden integration tests:** `.github/workflows/test-a11y-action.yml`
+
+## Where to add docs
+
+* **Suite-wide conventions:** `docs/unified-artifacts.md`
+* **Rule remediation index:** `docs/rules.md`

package/docs/handbooks/ALLY-DEMO-PYTHON.md

@@ -0,0 +1,23 @@
+# ally-demo-python Handbook
+
+A reference integration for Python showing how to consume or integrate the toolchain (“Ally” stack).
+
+## Quickstart
+
+**Run**
+```bash
+python examples/integrate_gate.py
+```
+
+**Output**
+* Console logs demonstrating API usage
+* `.a11y_artifacts/` generated by example calls
+
+## Typical use
+
+Learn how to integrate:
+
+* scorecard generation
+* gate execution
+* evidence bundling
+* parsing the `gate-result.json`

package/docs/handbooks/COMMON-CONCEPTS.md

@@ -0,0 +1,24 @@
+# Common Concepts
+
+## The Golden Folder: `.a11y_artifacts/`
+
+All tools agree on a shared artifact directory:
+
+```plaintext
+.a11y_artifacts/
+  current.scorecard.json     # produced by a11y-lint (or scanners)
+  baseline.scorecard.json    # optional, stored/managed by CI baseline workflow
+  allowlist.json             # optional, expiring suppressions (waivers)
+  gate-result.json           # produced by a11y-ci (structured report)
+  report.txt                 # produced by a11y-ci (human report)
+  evidence.json              # produced by a11y-ci (MCP evidence bundle)
+  comment.md                 # produced by a11y-ci (PR comment markdown)
+  result.json                # produced by a11y-lint (scanner result details)
+```
+
+## Typical pipeline flow
+
+1. **Scan** → `a11y-lint` writes `current.scorecard.json`
+2. **Gate** → `a11y-ci` gate reads it, compares baseline/allowlist, emits reports
+3. **Evidence** → `evidence.json` is produced for traceability/MCP
+4. **Comment** → `comment.md` generated for PR systems (GitHub/ADO)

package/docs/handbooks/CURSORASSIST.md

@@ -0,0 +1,18 @@
+# CursorAssist Handbook
+
+Assistive cursor control and UI benchmarking. It’s adjacent to accessibility, but it’s more in the “motor assistance + UX measurement” lane.
+
+## Quickstart
+
+**Run**
+```bash
+cursor-assist --monitor
+```
+
+**Output**
+* Cursor metrics CSV
+
+## How it fits
+
+* Can produce usability evidence/benchmarks that complement strict WCAG-style findings.
+* If it emits structured outputs, it can be wrapped into `.a11y_artifacts/` as an additional evidence source.

package/docs/handbooks/README.md

@@ -0,0 +1,20 @@
+# Accessibility Suite Handbooks
+
+These handbooks are the authoritative documentation for the Accessibility Suite. The monorepo is the source of truth for all tools.
+
+**Standalone repos contain redirects only.**
+
+## Start Here
+* [Universal Concepts](COMMON-CONCEPTS.md) - **Read this first.** Explains `.a11y_artifacts`, the pipeline flow, and shared conventions.
+
+## Core Toolchain
+1. [a11y-lint](A11Y-LINT.md) - The scanner.
+2. [a11y-ci](A11Y-CI.md) - The policy gate.
+3. [a11y-mcp-tools](A11Y-MCP-TOOLS.md) - The integration layer.
+
+## Reference & Ecosystem
+* [a11y-assist](A11Y-ASSIST.md)
+* [a11y-evidence-engine](A11Y-EVIDENCE-ENGINE.md)
+* [a11y-demo-site](A11Y-DEMO-SITE.md)
+* [ally-demo-python](ALLY-DEMO-PYTHON.md)
+* [CursorAssist](CURSORASSIST.md)

package/docs/prov-spec/SETUP.md

@@ -70,7 +70,7 @@ Third-party engines declare support using a capability manifest:
 
 ```json
 {
-  "schema": "mcp-tool-shop/prov-capabilities@v0.1",
+  "schema": "mcp-tool-shop-org/prov-capabilities@v0.1",
   "engine": {
     "name": "example-engine",
     "version": "1.0.0"