@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-assist/a11y_assist/schemas/assist.response.schema.v0.1.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a11y-assist.dev/schemas/assist.response.schema.v0.1.json",
+  "title": "assist.response.v0.1",
+  "description": "Response schema for a11y-assist with optional audit metadata",
+  "type": "object",
+  "required": ["confidence", "safest_next_step", "plan"],
+  "properties": {
+    "anchored_id": {
+      "type": ["string", "null"],
+      "description": "Error ID this assist is anchored to, if found"
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["High", "Medium", "Low"],
+      "description": "Confidence level of the assist"
+    },
+    "safest_next_step": {
+      "type": "string",
+      "description": "Single safest next action to take"
+    },
+    "plan": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Ordered list of steps to resolve the issue"
+    },
+    "next_safe_commands": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "SAFE-only commands that can be run"
+    },
+    "notes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Additional notes and context"
+    },
+    "methods_applied": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 0,
+      "description": "Stable method identifiers applied to produce this assist output (audit-only)"
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["field", "source"],
+        "properties": {
+          "field": {
+            "type": "string",
+            "description": "Which output field this evidence supports (e.g., safest_next_step, plan[0])"
+          },
+          "source": {
+            "type": "string",
+            "description": "Source anchor (e.g., cli.error.fix[1], cli.error.why[0], raw_text:Fix:2)"
+          },
+          "note": {
+            "type": "string",
+            "description": "Optional short note clarifying the mapping"
+          }
+        },
+        "additionalProperties": false
+      },
+      "minItems": 0,
+      "description": "Trace anchors mapping assist content back to input (audit-only)"
+    }
+  },
+  "additionalProperties": false
+}

package/src/a11y-assist/a11y_assist/schemas/cli.error.schema.v0.1.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a11y-lint.dev/schemas/cli.error.schema.v0.1.json",
+  "title": "CLI Ground Truth Message",
+  "description": "Schema for accessible CLI error messages with What/Why/Fix structure",
+  "type": "object",
+  "required": ["level", "code", "what"],
+  "properties": {
+    "level": {
+      "type": "string",
+      "enum": ["OK", "WARN", "ERROR"],
+      "description": "Severity level of the message"
+    },
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]{1,3}[0-9]{3}$",
+      "description": "Unique error code (e.g., A11Y001, CLI002)",
+      "examples": ["A11Y001", "CLI002", "FMT003"]
+    },
+    "id": {
+      "type": "string",
+      "description": "Alternate ID field (NAMESPACE.CATEGORY.DETAIL format)"
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-readable title"
+    },
+    "what": {
+      "oneOf": [
+        { "type": "string", "minLength": 1, "maxLength": 200 },
+        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      ],
+      "description": "Brief description of what happened or was checked"
+    },
+    "why": {
+      "oneOf": [
+        { "type": "string", "minLength": 1, "maxLength": 500 },
+        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      ],
+      "description": "Explanation of why this matters for accessibility"
+    },
+    "fix": {
+      "oneOf": [
+        { "type": "string", "minLength": 1, "maxLength": 500 },
+        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      ],
+      "description": "Actionable suggestion for how to fix the issue"
+    },
+    "location": {
+      "type": "object",
+      "description": "Location of the issue in the source",
+      "properties": {
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 },
+        "context": { "type": "string", "maxLength": 200 }
+      }
+    },
+    "rule": {
+      "type": "string",
+      "description": "Name of the accessibility rule that was checked"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional rule-specific metadata",
+      "additionalProperties": true
+    }
+  },
+  "if": {
+    "properties": {
+      "level": { "const": "ERROR" }
+    }
+  },
+  "then": {
+    "required": ["level", "code", "what", "why", "fix"]
+  },
+  "additionalProperties": true
+}

package/src/a11y-assist/a11y_assist/storage.py

@@ -0,0 +1,31 @@
+"""Storage for last.log capture."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def default_state_dir() -> Path:
+    """Get the default state directory (~/.a11y-assist)."""
+    home = Path.home()
+    return home / ".a11y-assist"
+
+
+def last_log_path() -> Path:
+    """Get the path to last.log."""
+    return default_state_dir() / "last.log"
+
+
+def write_last_log(text: str) -> None:
+    """Write text to last.log, creating directory if needed."""
+    p = last_log_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(text, encoding="utf-8", errors="replace")
+
+
+def read_last_log() -> str:
+    """Read last.log, returning empty string if not found."""
+    p = last_log_path()
+    if not p.exists():
+        return ""
+    return p.read_text(encoding="utf-8", errors="replace")

package/src/a11y-assist/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a11y-assist"
+version = "0.2.1"
+description = "Low-vision-first assistant for CLI failures (additive, deterministic)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "mcp-tool-shop", email = "64996768+mcp-tool-shop@users.noreply.github.com"}
+]
+keywords = [
+    "accessibility",
+    "a11y",
+    "cli",
+    "assistant",
+    "low-vision",
+    "provenance",
+    "safe"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: User Interfaces",
+]
+dependencies = [
+  "click>=8.1.7",
+  "jsonschema>=4.22.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/mcp-tool-shop-org/a11y-assist"
+Repository = "https://github.com/mcp-tool-shop-org/a11y-assist"
+Issues = "https://github.com/mcp-tool-shop-org/a11y-assist/issues"
+Changelog = "https://github.com/mcp-tool-shop-org/a11y-assist/blob/main/RELEASE_NOTES.md"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "ruff>=0.6.0",
+]
+
+[project.scripts]
+a11y-assist = "a11y_assist.cli:main"
+assist-run = "a11y_assist.cli:assist_run"
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/src/a11y-assist/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for a11y-assist."""

package/src/a11y-assist/tests/fixtures/base_inputs/cli_error_high.json

@@ -0,0 +1,18 @@
+{
+  "level": "ERROR",
+  "code": "NET001",
+  "id": "DEMO.NETWORK.TIMEOUT",
+  "title": "Request timed out",
+  "what": [
+    "The HTTP request did not complete within 30 seconds."
+  ],
+  "why": [
+    "The server did not respond before the timeout limit.",
+    "This may indicate network congestion or server overload."
+  ],
+  "fix": [
+    "Check your network connection.",
+    "Verify the server is reachable: ping api.example.com",
+    "Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run"
+  ]
+}

package/src/a11y-assist/tests/fixtures/base_inputs/cli_error_medium.json

@@ -0,0 +1,16 @@
+{
+  "level": "WARN",
+  "code": "CFG001",
+  "id": "DEMO.CONFIG.DEPRECATED",
+  "title": "Deprecated configuration",
+  "what": [
+    "The 'timeout' field in config.json is deprecated."
+  ],
+  "why": [
+    "This field will be removed in v2.0."
+  ],
+  "fix": [
+    "Use 'request_timeout_ms' instead.",
+    "Re-run: demo-cli validate config.json --dry-run"
+  ]
+}

package/src/a11y-assist/tests/fixtures/base_inputs/raw_text_low.txt

@@ -0,0 +1,3 @@
+Error: Connection refused
+The server at 192.168.1.100:8080 is not responding.
+Please check the service is running.

package/src/a11y-assist/tests/fixtures/cli_error_good.json

@@ -0,0 +1,9 @@
+{
+  "level": "ERROR",
+  "code": "PAY001",
+  "id": "PAY.EXPORT.SFTP.AUTH",
+  "title": "Payment export failed",
+  "what": ["Could not upload the file."],
+  "why": ["Credentials were rejected."],
+  "fix": ["Verify credentials.", "Re-run: payroll export --batch 2026-01-26 --dry-run"]
+}

package/src/a11y-assist/tests/fixtures/cli_error_missing_id.json

@@ -0,0 +1,7 @@
+{
+  "level": "ERROR",
+  "title": "Payment export failed",
+  "what": ["Could not upload the file."],
+  "why": ["Credentials were rejected."],
+  "fix": ["Verify credentials."]
+}

package/src/a11y-assist/tests/fixtures/cli_error_string_format.json

@@ -0,0 +1,7 @@
+{
+  "level": "ERROR",
+  "code": "CFG001",
+  "what": "Configuration file missing",
+  "why": "The app cannot start without config.yaml",
+  "fix": "Create config.yaml in the project root"
+}

package/src/a11y-assist/tests/fixtures/expected/cognitive_load_high.txt

@@ -0,0 +1,20 @@
+ASSIST (Cognitive Load):
+- Anchored to: DEMO.NETWORK.TIMEOUT
+- Confidence: High
+
+Goal: Get back to a known-good state.
+
+Safest next step:
+  Start by confirming the cause described under 'Why'.
+
+Plan:
+  First: Check your network connection.
+  Next: Verify the server is reachable: ping api.example.com.
+  Last: Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run.
+
+Next (SAFE):
+  Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run
+
+Notes:
+  - Original title: Request timed out
+  - This assist block is additive; it does not replace the tool's output.

package/src/a11y-assist/tests/fixtures/expected/dyslexia_high.txt

@@ -0,0 +1,20 @@
+ASSIST (Dyslexia):
+
+Anchored ID: DEMO.NETWORK.TIMEOUT
+
+Confidence: High
+
+Safest next step:
+  Start by confirming the cause described under 'Why', then apply the first Fix step.
+
+Plan:
+  - Step 1: Check your network connection.
+  - Step 2: Verify the server is reachable: ping api.example.com
+  - Step 3: Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run
+
+Next safe command:
+  Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run
+
+Notes:
+  - Original title: Request timed out
+  - This assist block is additive; it does not replace the tool's output.

package/src/a11y-assist/tests/fixtures/expected/lowvision_high.txt

@@ -0,0 +1,18 @@
+ASSIST (Low Vision):
+- Anchored to: DEMO.NETWORK.TIMEOUT
+- Confidence: High
+
+Safest next step:
+  Start by confirming the cause described under 'Why', then apply the first Fix step.
+
+Plan:
+  1) Check your network connection.
+  2) Verify the server is reachable: ping api.example.com
+  3) Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run
+
+Next (SAFE):
+  Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run
+
+Notes:
+  - Original title: Request timed out
+  - This assist block is additive; it does not replace the tool's output.

package/src/a11y-assist/tests/fixtures/expected/plain_language_high.txt

@@ -0,0 +1,14 @@
+ASSIST (Plain Language)
+ID: DEMO.NETWORK.TIMEOUT
+Confidence: High
+
+What to do next:
+  Start by confirming the cause described under 'Why', then apply the first Fix step.
+
+Steps:
+  1. Check your network connection.
+  2. Verify the server is reachable: ping api.example.com.
+  3. Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run.
+
+Safe command:
+  Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run

package/src/a11y-assist/tests/fixtures/expected/screen_reader_high.txt

@@ -0,0 +1,19 @@
+ASSIST. Profile: Screen reader.
+Anchored I D: DEMO.NETWORK.TIMEOUT.
+Confidence: High.
+
+Summary: Request timed out.
+
+Safest next step: Start by confirming the cause described under 'Why', then apply the first Fix step.
+
+Steps:
+Step 1: Check your network connection.
+Step 2: Verify the server is reachable: ping api.example.com.
+Step 3: Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run.
+
+Next safe command:
+Re-run with increased timeout: demo-cli network-timeout --timeout 60 --dry-run
+
+Notes:
+Original title: Request timed out.
+This assist block is additive.

package/src/a11y-assist/tests/fixtures/golden_screen_reader_cli_error.txt

@@ -0,0 +1,16 @@
+ASSIST. Profile: Screen reader.
+Anchored I D: PAY.EXPORT.SFTP.AUTH.
+Confidence: High.
+
+Summary: Payment export failed.
+
+Safest next step: Confirm the cause described under Why.
+
+Steps:
+Step 1: Verify credentials.
+Step 2: Re-run: payroll export to batch 2026-01-26 to dry-run.
+
+Next safe command:
+payroll export --batch 2026-01-26 --dry-run
+
+Note: Original title: Payment export failed.

package/src/a11y-assist/tests/fixtures/golden_screen_reader_raw_no_id.txt

@@ -0,0 +1,14 @@
+ASSIST. Profile: Screen reader.
+Anchored I D: none.
+Confidence: Low.
+
+Summary: The input did not include a stable error identifier.
+
+Safest next step: Follow the tool's Fix steps.
+
+Steps:
+Step 1: Re-run the command with increased verbosity/logging.
+Step 2: Update the tool to emit I D and What/Why/Fix blocks.
+Step 3: If this is your tool.
+
+Note: No I D found.

package/src/a11y-assist/tests/fixtures/golden_screen_reader_raw_with_id.txt

@@ -0,0 +1,14 @@
+ASSIST. Profile: Screen reader.
+Anchored I D: PAY.EXPORT.SFTP.AUTH.
+Confidence: Medium.
+
+Summary: An error was detected with partial information.
+
+Safest next step: Follow the tool's Fix steps.
+
+Steps:
+Step 1: Verify username/password or S S H key.
+Step 2: Re-run: payroll export to batch 2026-01-26 to dry-run.
+
+Next safe command:
+payroll export --batch 2026-01-26 --dry-run

package/src/a11y-assist/tests/fixtures/raw_good.txt

@@ -0,0 +1,11 @@
+[ERROR] Payment export failed (ID: PAY.EXPORT.SFTP.AUTH)
+
+What:
+  Could not upload the NACHA file.
+
+Why:
+  Credentials were rejected.
+
+Fix:
+  Verify username/password or SSH key.
+  Re-run: payroll export --batch 2026-01-26 --dry-run

package/src/a11y-assist/tests/fixtures/raw_no_id.txt

@@ -0,0 +1,2 @@
+ERROR: It failed
+Please try again