wythe 0.1.0__tar.gz

wythe-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+*.db
+*.sqlite3
+
+# Node / Next.js
+node_modules/
+.next/
+out/
+coverage/
+next-env.d.ts
+*.tsbuildinfo
+
+# OS / Local state
+.DS_Store
+.local/
+.env
+.env.*
+!.env.example

wythe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Montgomery
+
+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.

wythe-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: wythe
+Version: 0.1.0
+Summary: Why -> Therefore: 3-tier architecture verifier, cross-boundary lineage solver, and 3D WebGL atlas.
+Project-URL: Homepage, https://github.com/Euda1mon1a/wythe
+Project-URL: Repository, https://github.com/Euda1mon1a/wythe
+Project-URL: Issues, https://github.com/Euda1mon1a/wythe/issues
+Author: Aaron Montgomery
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,architecture,lineage,mcp,openapi,sarif,static-analysis,three-tier
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: alembic>=1.14.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: psycopg[binary]>=3.2.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: sqlalchemy>=2.0.35
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Requires-Dist: tree-sitter-go>=0.23.0; extra == 'dev'
+Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'dev'
+Requires-Dist: tree-sitter-rust>=0.23.0; extra == 'dev'
+Requires-Dist: tree-sitter-typescript>=0.23.0; extra == 'dev'
+Requires-Dist: tree-sitter>=0.23.0; extra == 'dev'
+Provides-Extra: treesitter
+Requires-Dist: tree-sitter-go>=0.23.0; extra == 'treesitter'
+Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'treesitter'
+Requires-Dist: tree-sitter-rust>=0.23.0; extra == 'treesitter'
+Requires-Dist: tree-sitter-typescript>=0.23.0; extra == 'treesitter'
+Requires-Dist: tree-sitter>=0.23.0; extra == 'treesitter'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="docs/icon/icon-light.svg">
+    <img src="docs/icon/icon-dark.svg" width="96" height="96" alt="Wythe icon — three architectural wythe bars mortised by a Why (?) triskelion and Therefore (∴) core">
+  </picture>
+</p>
+
+# Wythe
+
+**Why (`?`) → Therefore (`∴`)** — Generalizable 3-tier architecture verifier, cross-boundary lineage solver, interactive 3D WebGL latticework visualizer, and fail-closed CI gate built around three masonry wythe invariants:
+
+1. **Database holds truth** — Relational schemas (`PostgreSQL`, `MySQL`, `SQLite` via `SQLAlchemy 2.0` + `Alembic`, `Prisma`, `Drizzle ORM`, `Django ORM`, Rust `sqlx`/`Diesel`/`SeaORM`, or raw SQL DDL/`sqlc` + optional read-only catalog probes) own domain policy, thresholds, temporal validity, and write-lane guards, while `Redis` keyspaces and worker queues are modeled explicitly as ephemeral stores/lanes rather than durable shadow truth.
+2. **Backend manipulates truth** — Services, background workers, solvers, and routers (`Python/FastAPI`, `TypeScript/Node/Express/Hono/Fastify/NestJS/Next.js/SvelteKit`, `Python/Django/DRF/Ninja`, `Go net/http/chi/gin/echo`, `Rust axum/actix-web/rocket/Tauri`) execute mechanisms over database rows behind explicit transactional service/SQL doors without embedding shadow policy literals or host-clock drift.
+3. **Frontend displays truth** — UI surfaces (`Next.js`, `React/Vite/TanStack Router/Remix`, `Vue 3/Nuxt`, `Svelte 5/SvelteKit`, `Rust WASM Leptos/Dioxus/Yew` + Tauri `invoke()`) bind to typed contracts, centralized clock utilities, and WCAG-accessible markup without inventing client-side policy maps or unbacked HTTP/IPC calls.
+
+Wythe supports **18 full-stack profiles** out of the box via `--profile auto`, pairs Python's native `ast` with an optional **Tree-sitter CST grammar engine** (`wythe[treesitter]` for TypeScript/TSX, JavaScript, Rust, and Go), traces background worker & scheduled beat queues (`Celery` / `Beat`, `BullMQ`, `Asynq`), enforces **WCAG accessibility semantics** (`DISP-005`), renders both **Simple Solids** and **120 fps Breathing Atomic Wythe Polyhedra** (with adaptive `System | Dark | Light` polarity and custom user palettes), and **self-dogfoods** its own 3-tier codebase (`wythe gate --strict wythe` passes with zero blocking and zero warning findings).
+
+---
+
+## Instant Usage (`uvx` / `uv`)
+
+Run Wythe directly against any repository without polluting project dependencies (add `[treesitter]` to enable prebuilt Tree-sitter CST wheels for TS/TSX, JS, Rust, and Go):
+
+```bash
+# Instant CLI gate & lineage scan from PyPI (once published) or directly from GitHub
+uvx "wythe[treesitter]" gate --strict /path/to/repo
+uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe scan /path/to/repo
+uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe gate --strict /path/to/repo
+
+# Launch single-port API + interactive 3D WebGL UI on http://127.0.0.1:8780 (no Node.js runtime needed)
+uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe serve /path/to/repo
+
+# Or install persistently as an isolated CLI tool
+uv tool install "git+https://github.com/Euda1mon1a/wythe[treesitter]"
+wythe serve .
+```
+
+### GitHub Actions Integration
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: Euda1mon1a/wythe@main
+  with:
+    mode: diff
+    base-ref: origin/main
+    sarif-file: wythe.sarif.json
+```
+
+---
+
+## Persisted Rule Catalog (`atlas_rule_policies`)
+
+Rule severity, enablement, gate-blocking behavior, and effective-date windows live in database truth (`atlas_rule_policies`) and round-trip cleanly to Git via `.wythe/governance.json`:
+
+| Code | Tier | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `TRUTH-001` | `truth` | Warning | Persisted input table has zero verified backend readers |
+| `TRUTH-002` | `truth` | Blocking | ORM model, `schema.sql`/migrations, or live DB catalog table drift |
+| `TRUTH-003` | `truth` | Blocking | Table or Redis store mutated directly inside HTTP route without service/DB door |
+| `TRUTH-004` | `truth` | Warning | Unbounded Redis `SET`/`HSET` write without TTL risks volatile shadow truth |
+| `MANIP-001` | `manipulate` | Blocking | Mutable domain policy/threshold constant hardcoded in code (`atlas_policy_vocabularies`) |
+| `MANIP-002` | `manipulate` | Blocking | Direct host `date.today()` or naive `datetime.utcnow()` call |
+| `MANIP-003` | `manipulate` | Warning | Service/solver module has zero verified inbound route, CLI, or worker callers |
+| `DISP-001` | `display` | Blocking | Display tier defines domain policy threshold shadows in frontend code |
+| `DISP-002` | `display` | Blocking | Raw `new Date()` or UTC `.toISOString().slice(0, 10)` date slicing |
+| `DISP-003` | `display` | Warning | Frontend API client omits `api-generated` OpenAPI/schema types |
+| `DISP-004` | `display` | Blocking | Frontend HTTP/IPC call targets a path absent from backend router graph |
+| `DISP-005` | `display` | Warning | Display markup violates core WCAG semantics (missing `alt`, unlabeled form input, nameless icon button, non-keyboard `<div onClick>`) |
+
+---
+
+## CLI Commands
+
+```bash
+# Scan any supported full-stack repository (--profile auto)
+wythe scan /path/to/repo --json report.json --sarif report.sarif.json
+
+# Optional metadata-only live DB & Redis keyspace probes (zero row or value reads)
+wythe scan /path/to/repo \
+  --dsn "postgresql://readonly@127.0.0.1:5432/appdb" \
+  --redis-dsn "redis://127.0.0.1:6379/0"
+
+# PR diff gate & directional 3-tier blast-radius slice
+wythe diff /path/to/repo --base origin/main --sarif diff.sarif.json
+
+# Git-portable governance bundle (.wythe/governance.json) for CI runners
+wythe export-config /path/to/repo
+wythe gate --sync-config /path/to/repo
+
+# Single-port API + 3D WebGL UI (auto-registers target directory on startup)
+wythe serve /path/to/repo --host 127.0.0.1 --port 8780
+```
+
+---
+
+## First-Class LLM & Human ↔ Vision/MCP Bridge (On-Device AI, Streamable HTTP MCP, OpenAPI & WebMCP)
+
+Full JSON scans on large repositories span megabytes; Wythe exposes five zero-copy-paste Human ↔ LLM surfaces spanning bare-minimum on-device models through remote Tailnet agents:
+
+1. **Zero-Setup On-Device AI (`Ask AI [A]` / `⌘J`, `/api/v1/ask`)** — Zero-cloud, zero-API-key cascade with real-time Three.js camera-frustum & screen-color telemetry, `1024px` WebP vision frames, and rolling multi-turn sessions across:
+   - **Apple Intelligence (`apple`)**: macOS 26+/27 native `FoundationModels` helper (`arm64-apple-macos26.0`, serialized with `modelmanagerd` backoff).
+   - **Chrome Built-In (`chrome`)**: Client-side browser `LanguageModel` (Gemini Nano via Prompt API, including 1-click download and multimodal WebGL `<canvas>` vision when enabled).
+   - **Local OpenAI `/v1` (`local`)**: Auto-probes browser-host & server loopback `/v1/models` & `/v1/chat/completions` (`:8080`/`:8084`/`:8083` MLX, `:11434` Ollama, `:1234` LM Studio) without triggering weight reloads.
+2. **Streamable HTTP MCP (`POST /api/v1/mcp` & `GET /api/v1/mcp`) + Stdio MCP (`wythe mcp`)** — Connect local or remote Tailnet coding agents (`http://<host>:8780/api/v1/mcp`) with zero local install.
+3. **OpenAPI 3.1 (`/openapi.json`) + Remote CLI (`wythe focus --remote <url>`)** — Universal HTTP tool/Actions compatibility plus cross-host CLI X-Ray inspection.
+4. **In-Tab WebMCP (`navigator.modelContext` & `window.wythe`)** — Exposes `whatIsThis()`, `getLineageCone(query)`, `selectNode(nodeId)`, and `ask(question)` directly to browser agents and extensions.
+5. **Token-Budgeted `llms.txt` & Lineage Cone Slicer** — Deterministic ~2,000-token repo maps and ~300-token 3-tier cones.
+
+```bash
+# 1. Token-budgeted llms.txt pointer map (~2,000 tokens regardless of repo size)
+wythe llms /path/to/repo --max-tokens 2200 --out llms-wythe.txt
+
+# 2. Surgical ~300-token 3-tier Lineage Cone around any table, file, route, or queue
+wythe context /path/to/repo audit_exports
+wythe context /path/to/repo /api/v1/scans --json
+
+# 3. Zero-copy-paste Human <-> LLM Bridge (local state or remote private/Tailnet server)
+wythe focus
+wythe focus --remote http://100.64.0.10:8780
+
+# 4. Zero-dependency read-only stdio MCP server (or connect directly to http://127.0.0.1:8780/api/v1/mcp)
+wythe mcp
+```
+
+MCP client configuration (Stdio or Streamable HTTP — exposes `wythe_what_is_this`, `wythe_list_targets`, `wythe_overview`, `wythe_lineage_cone`, `wythe_blast_radius`, `wythe_findings`):
+
+```json
+{
+  "mcpServers": {
+    "wythe-http": {
+      "url": "http://127.0.0.1:8780/api/v1/mcp"
+    },
+    "wythe-stdio": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/Euda1mon1a/wythe[treesitter]", "wythe", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Supported Multi-Language & Multi-DB Adapters
+
+| Stratum | Adapter Key | Stack Coverage |
+| :--- | :--- | :--- |
+| **Tier 1 (Truth)** | `postgres-sqlalchemy` | SQLAlchemy 2.0 + Alembic + `schema.sql` + PG/MySQL/SQLite live catalog |
+| **Tier 1 (Truth)** | `prisma-schema` | Prisma `schema.prisma` (`@@map`) + `prisma/migrations/*.sql` |
+| **Tier 1 (Truth)** | `drizzle-orm` | Drizzle `pgTable`/`mysqlTable`/`sqliteTable` + Drizzle SQL migrations |
+| **Tier 1 (Truth)** | `django-orm` | Django `models.Model` (`Meta.db_table`) + `migrations/*.py` |
+| **Tier 1 (Truth)** | `sql-ddl` | Multi-dialect SQL DDL + `golang-migrate`/`goose`/`Flyway` + `sqlc` |
+| **Tier 1 (Truth)** | `rust-sql` | Rust `sqlx` (`migrations/*.sql`, `query_file!`), `Diesel` (`table!`), `SeaORM` entities |
+| **Tier 1 (Ephemeral)** | `redis-ephemeral` | Cross-language Redis keyspaces + `Celery`/`Beat`, `BullMQ`, & `Asynq` named queues |
+| **Tier 2 (Manipulate)** | `python-fastapi` | FastAPI routers, Python services/workers/CLI, SQLAlchemy/SQL AST |
+| **Tier 2 (Manipulate)** | `typescript-node` | Next.js `route.ts`, SvelteKit `+page.server.ts`/`+server.ts`, Express, Hono, Fastify, NestJS |
+| **Tier 2 (Manipulate)** | `python-django` | Django `urls.py` (`path`/`re_path`), DRF `ViewSet`/routers, Django Ninja + `Model.objects` |
+| **Tier 2 (Manipulate)** | `go-http` | Go 1.22+ `net/http`, `chi`, `gin`, `echo` (nested router groups) + `sqlc`/GORM/SQL |
+| **Tier 2 (Manipulate)** | `rust-http` | Rust Cargo workspaces, `axum`, `actix-web`, `rocket`, Tauri `#[tauri::command]` + `sqlx`/Diesel/SeaORM |
+| **Tier 3 (Display)** | `typescript-nextjs` | Next.js App & Pages Router + custom fetch/RTK Query + Tauri `invoke()` + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `typescript-react` | React SPA, Vite, React Router, TanStack Router, Remix + barrel exports + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `vue-sfc` | Vue 3 & Nuxt 3 `.vue` SFCs + composables (`$fetch`, `useFetch`) + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `sveltekit` | Svelte 5 & SvelteKit `+page.svelte`, `+page.ts`, `$lib` + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `rust-wasm` | Rust WASM `Leptos`, `Dioxus`, `Yew` (`gloo-net` / `reqwest` / Tauri WASM) + WCAG `DISP-005` |
+
+### Architecture & Ecosystem Docs
+- [`docs/architecture/ecosystem-and-positioning.md`](docs/architecture/ecosystem-and-positioning.md) — Ecosystem comparison (`tach`, `import-linter`, `dependency-cruiser`, `sqllineage`, `OpenLineage`, `CodeCharta`, `Semgrep`) and pairing `tach` + Wythe in CI.
+- [`docs/architecture/multi-language-extensibility.md`](docs/architecture/multi-language-extensibility.md) — Language-neutral intermediate contract, adapter matrix, read-only DB/Redis probes, and `--profile auto` detection.
+
+---
+
+## Local Development
+
+```bash
+make types      # Export OpenAPI 3.1 -> generate TypeScript schema types -> run tsc --noEmit
+make build-ui   # Build static Next.js export into backend/app/ui_dist
+make lint       # Run ruff check
+make test       # Run serial pytest suite
+make gate       # Run strict self-dogfood 3-tier + WCAG gate
+make package    # Build standalone wheel & sdist containing bundled 3D WebGL UI
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

wythe-0.1.0/README.md

@@ -0,0 +1,186 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="docs/icon/icon-light.svg">
+    <img src="docs/icon/icon-dark.svg" width="96" height="96" alt="Wythe icon — three architectural wythe bars mortised by a Why (?) triskelion and Therefore (∴) core">
+  </picture>
+</p>
+
+# Wythe
+
+**Why (`?`) → Therefore (`∴`)** — Generalizable 3-tier architecture verifier, cross-boundary lineage solver, interactive 3D WebGL latticework visualizer, and fail-closed CI gate built around three masonry wythe invariants:
+
+1. **Database holds truth** — Relational schemas (`PostgreSQL`, `MySQL`, `SQLite` via `SQLAlchemy 2.0` + `Alembic`, `Prisma`, `Drizzle ORM`, `Django ORM`, Rust `sqlx`/`Diesel`/`SeaORM`, or raw SQL DDL/`sqlc` + optional read-only catalog probes) own domain policy, thresholds, temporal validity, and write-lane guards, while `Redis` keyspaces and worker queues are modeled explicitly as ephemeral stores/lanes rather than durable shadow truth.
+2. **Backend manipulates truth** — Services, background workers, solvers, and routers (`Python/FastAPI`, `TypeScript/Node/Express/Hono/Fastify/NestJS/Next.js/SvelteKit`, `Python/Django/DRF/Ninja`, `Go net/http/chi/gin/echo`, `Rust axum/actix-web/rocket/Tauri`) execute mechanisms over database rows behind explicit transactional service/SQL doors without embedding shadow policy literals or host-clock drift.
+3. **Frontend displays truth** — UI surfaces (`Next.js`, `React/Vite/TanStack Router/Remix`, `Vue 3/Nuxt`, `Svelte 5/SvelteKit`, `Rust WASM Leptos/Dioxus/Yew` + Tauri `invoke()`) bind to typed contracts, centralized clock utilities, and WCAG-accessible markup without inventing client-side policy maps or unbacked HTTP/IPC calls.
+
+Wythe supports **18 full-stack profiles** out of the box via `--profile auto`, pairs Python's native `ast` with an optional **Tree-sitter CST grammar engine** (`wythe[treesitter]` for TypeScript/TSX, JavaScript, Rust, and Go), traces background worker & scheduled beat queues (`Celery` / `Beat`, `BullMQ`, `Asynq`), enforces **WCAG accessibility semantics** (`DISP-005`), renders both **Simple Solids** and **120 fps Breathing Atomic Wythe Polyhedra** (with adaptive `System | Dark | Light` polarity and custom user palettes), and **self-dogfoods** its own 3-tier codebase (`wythe gate --strict wythe` passes with zero blocking and zero warning findings).
+
+---
+
+## Instant Usage (`uvx` / `uv`)
+
+Run Wythe directly against any repository without polluting project dependencies (add `[treesitter]` to enable prebuilt Tree-sitter CST wheels for TS/TSX, JS, Rust, and Go):
+
+```bash
+# Instant CLI gate & lineage scan from PyPI (once published) or directly from GitHub
+uvx "wythe[treesitter]" gate --strict /path/to/repo
+uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe scan /path/to/repo
+uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe gate --strict /path/to/repo
+
+# Launch single-port API + interactive 3D WebGL UI on http://127.0.0.1:8780 (no Node.js runtime needed)
+uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe serve /path/to/repo
+
+# Or install persistently as an isolated CLI tool
+uv tool install "git+https://github.com/Euda1mon1a/wythe[treesitter]"
+wythe serve .
+```
+
+### GitHub Actions Integration
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: Euda1mon1a/wythe@main
+  with:
+    mode: diff
+    base-ref: origin/main
+    sarif-file: wythe.sarif.json
+```
+
+---
+
+## Persisted Rule Catalog (`atlas_rule_policies`)
+
+Rule severity, enablement, gate-blocking behavior, and effective-date windows live in database truth (`atlas_rule_policies`) and round-trip cleanly to Git via `.wythe/governance.json`:
+
+| Code | Tier | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `TRUTH-001` | `truth` | Warning | Persisted input table has zero verified backend readers |
+| `TRUTH-002` | `truth` | Blocking | ORM model, `schema.sql`/migrations, or live DB catalog table drift |
+| `TRUTH-003` | `truth` | Blocking | Table or Redis store mutated directly inside HTTP route without service/DB door |
+| `TRUTH-004` | `truth` | Warning | Unbounded Redis `SET`/`HSET` write without TTL risks volatile shadow truth |
+| `MANIP-001` | `manipulate` | Blocking | Mutable domain policy/threshold constant hardcoded in code (`atlas_policy_vocabularies`) |
+| `MANIP-002` | `manipulate` | Blocking | Direct host `date.today()` or naive `datetime.utcnow()` call |
+| `MANIP-003` | `manipulate` | Warning | Service/solver module has zero verified inbound route, CLI, or worker callers |
+| `DISP-001` | `display` | Blocking | Display tier defines domain policy threshold shadows in frontend code |
+| `DISP-002` | `display` | Blocking | Raw `new Date()` or UTC `.toISOString().slice(0, 10)` date slicing |
+| `DISP-003` | `display` | Warning | Frontend API client omits `api-generated` OpenAPI/schema types |
+| `DISP-004` | `display` | Blocking | Frontend HTTP/IPC call targets a path absent from backend router graph |
+| `DISP-005` | `display` | Warning | Display markup violates core WCAG semantics (missing `alt`, unlabeled form input, nameless icon button, non-keyboard `<div onClick>`) |
+
+---
+
+## CLI Commands
+
+```bash
+# Scan any supported full-stack repository (--profile auto)
+wythe scan /path/to/repo --json report.json --sarif report.sarif.json
+
+# Optional metadata-only live DB & Redis keyspace probes (zero row or value reads)
+wythe scan /path/to/repo \
+  --dsn "postgresql://readonly@127.0.0.1:5432/appdb" \
+  --redis-dsn "redis://127.0.0.1:6379/0"
+
+# PR diff gate & directional 3-tier blast-radius slice
+wythe diff /path/to/repo --base origin/main --sarif diff.sarif.json
+
+# Git-portable governance bundle (.wythe/governance.json) for CI runners
+wythe export-config /path/to/repo
+wythe gate --sync-config /path/to/repo
+
+# Single-port API + 3D WebGL UI (auto-registers target directory on startup)
+wythe serve /path/to/repo --host 127.0.0.1 --port 8780
+```
+
+---
+
+## First-Class LLM & Human ↔ Vision/MCP Bridge (On-Device AI, Streamable HTTP MCP, OpenAPI & WebMCP)
+
+Full JSON scans on large repositories span megabytes; Wythe exposes five zero-copy-paste Human ↔ LLM surfaces spanning bare-minimum on-device models through remote Tailnet agents:
+
+1. **Zero-Setup On-Device AI (`Ask AI [A]` / `⌘J`, `/api/v1/ask`)** — Zero-cloud, zero-API-key cascade with real-time Three.js camera-frustum & screen-color telemetry, `1024px` WebP vision frames, and rolling multi-turn sessions across:
+   - **Apple Intelligence (`apple`)**: macOS 26+/27 native `FoundationModels` helper (`arm64-apple-macos26.0`, serialized with `modelmanagerd` backoff).
+   - **Chrome Built-In (`chrome`)**: Client-side browser `LanguageModel` (Gemini Nano via Prompt API, including 1-click download and multimodal WebGL `<canvas>` vision when enabled).
+   - **Local OpenAI `/v1` (`local`)**: Auto-probes browser-host & server loopback `/v1/models` & `/v1/chat/completions` (`:8080`/`:8084`/`:8083` MLX, `:11434` Ollama, `:1234` LM Studio) without triggering weight reloads.
+2. **Streamable HTTP MCP (`POST /api/v1/mcp` & `GET /api/v1/mcp`) + Stdio MCP (`wythe mcp`)** — Connect local or remote Tailnet coding agents (`http://<host>:8780/api/v1/mcp`) with zero local install.
+3. **OpenAPI 3.1 (`/openapi.json`) + Remote CLI (`wythe focus --remote <url>`)** — Universal HTTP tool/Actions compatibility plus cross-host CLI X-Ray inspection.
+4. **In-Tab WebMCP (`navigator.modelContext` & `window.wythe`)** — Exposes `whatIsThis()`, `getLineageCone(query)`, `selectNode(nodeId)`, and `ask(question)` directly to browser agents and extensions.
+5. **Token-Budgeted `llms.txt` & Lineage Cone Slicer** — Deterministic ~2,000-token repo maps and ~300-token 3-tier cones.
+
+```bash
+# 1. Token-budgeted llms.txt pointer map (~2,000 tokens regardless of repo size)
+wythe llms /path/to/repo --max-tokens 2200 --out llms-wythe.txt
+
+# 2. Surgical ~300-token 3-tier Lineage Cone around any table, file, route, or queue
+wythe context /path/to/repo audit_exports
+wythe context /path/to/repo /api/v1/scans --json
+
+# 3. Zero-copy-paste Human <-> LLM Bridge (local state or remote private/Tailnet server)
+wythe focus
+wythe focus --remote http://100.64.0.10:8780
+
+# 4. Zero-dependency read-only stdio MCP server (or connect directly to http://127.0.0.1:8780/api/v1/mcp)
+wythe mcp
+```
+
+MCP client configuration (Stdio or Streamable HTTP — exposes `wythe_what_is_this`, `wythe_list_targets`, `wythe_overview`, `wythe_lineage_cone`, `wythe_blast_radius`, `wythe_findings`):
+
+```json
+{
+  "mcpServers": {
+    "wythe-http": {
+      "url": "http://127.0.0.1:8780/api/v1/mcp"
+    },
+    "wythe-stdio": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/Euda1mon1a/wythe[treesitter]", "wythe", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Supported Multi-Language & Multi-DB Adapters
+
+| Stratum | Adapter Key | Stack Coverage |
+| :--- | :--- | :--- |
+| **Tier 1 (Truth)** | `postgres-sqlalchemy` | SQLAlchemy 2.0 + Alembic + `schema.sql` + PG/MySQL/SQLite live catalog |
+| **Tier 1 (Truth)** | `prisma-schema` | Prisma `schema.prisma` (`@@map`) + `prisma/migrations/*.sql` |
+| **Tier 1 (Truth)** | `drizzle-orm` | Drizzle `pgTable`/`mysqlTable`/`sqliteTable` + Drizzle SQL migrations |
+| **Tier 1 (Truth)** | `django-orm` | Django `models.Model` (`Meta.db_table`) + `migrations/*.py` |
+| **Tier 1 (Truth)** | `sql-ddl` | Multi-dialect SQL DDL + `golang-migrate`/`goose`/`Flyway` + `sqlc` |
+| **Tier 1 (Truth)** | `rust-sql` | Rust `sqlx` (`migrations/*.sql`, `query_file!`), `Diesel` (`table!`), `SeaORM` entities |
+| **Tier 1 (Ephemeral)** | `redis-ephemeral` | Cross-language Redis keyspaces + `Celery`/`Beat`, `BullMQ`, & `Asynq` named queues |
+| **Tier 2 (Manipulate)** | `python-fastapi` | FastAPI routers, Python services/workers/CLI, SQLAlchemy/SQL AST |
+| **Tier 2 (Manipulate)** | `typescript-node` | Next.js `route.ts`, SvelteKit `+page.server.ts`/`+server.ts`, Express, Hono, Fastify, NestJS |
+| **Tier 2 (Manipulate)** | `python-django` | Django `urls.py` (`path`/`re_path`), DRF `ViewSet`/routers, Django Ninja + `Model.objects` |
+| **Tier 2 (Manipulate)** | `go-http` | Go 1.22+ `net/http`, `chi`, `gin`, `echo` (nested router groups) + `sqlc`/GORM/SQL |
+| **Tier 2 (Manipulate)** | `rust-http` | Rust Cargo workspaces, `axum`, `actix-web`, `rocket`, Tauri `#[tauri::command]` + `sqlx`/Diesel/SeaORM |
+| **Tier 3 (Display)** | `typescript-nextjs` | Next.js App & Pages Router + custom fetch/RTK Query + Tauri `invoke()` + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `typescript-react` | React SPA, Vite, React Router, TanStack Router, Remix + barrel exports + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `vue-sfc` | Vue 3 & Nuxt 3 `.vue` SFCs + composables (`$fetch`, `useFetch`) + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `sveltekit` | Svelte 5 & SvelteKit `+page.svelte`, `+page.ts`, `$lib` + WCAG `DISP-005` |
+| **Tier 3 (Display)** | `rust-wasm` | Rust WASM `Leptos`, `Dioxus`, `Yew` (`gloo-net` / `reqwest` / Tauri WASM) + WCAG `DISP-005` |
+
+### Architecture & Ecosystem Docs
+- [`docs/architecture/ecosystem-and-positioning.md`](docs/architecture/ecosystem-and-positioning.md) — Ecosystem comparison (`tach`, `import-linter`, `dependency-cruiser`, `sqllineage`, `OpenLineage`, `CodeCharta`, `Semgrep`) and pairing `tach` + Wythe in CI.
+- [`docs/architecture/multi-language-extensibility.md`](docs/architecture/multi-language-extensibility.md) — Language-neutral intermediate contract, adapter matrix, read-only DB/Redis probes, and `--profile auto` detection.
+
+---
+
+## Local Development
+
+```bash
+make types      # Export OpenAPI 3.1 -> generate TypeScript schema types -> run tsc --noEmit
+make build-ui   # Build static Next.js export into backend/app/ui_dist
+make lint       # Run ruff check
+make test       # Run serial pytest suite
+make gate       # Run strict self-dogfood 3-tier + WCAG gate
+make package    # Build standalone wheel & sdist containing bundled 3D WebGL UI
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

wythe-0.1.0/backend/app/__init__.py

@@ -0,0 +1,3 @@
+"""Truth Atlas backend package."""
+
+__version__ = "0.1.0"

wythe-0.1.0/backend/app/adapters/__init__.py

@@ -0,0 +1,50 @@
+"""Default adapter registry factory with multi-language 3-tier adapters."""
+
+from __future__ import annotations
+
+from app.adapters.base import AdapterRegistry
+from app.adapters.django_truth import DjangoOrmAdapter
+from app.adapters.drizzle_truth import DrizzleOrmAdapter
+from app.adapters.go_http import GoHttpAdapter
+from app.adapters.postgres_sqlalchemy import PostgresSqlAlchemyAdapter
+from app.adapters.prisma_truth import PrismaSchemaAdapter
+from app.adapters.python_django import PythonDjangoAdapter
+from app.adapters.python_fastapi import PythonFastApiAdapter
+from app.adapters.rust_http import RustHttpAdapter
+from app.adapters.rust_sql_truth import RustSqlTruthAdapter
+from app.adapters.rust_wasm_display import RustWasmDisplayAdapter
+from app.adapters.sql_ddl_truth import SqlDdlTruthAdapter
+from app.adapters.sveltekit_display import SvelteKitDisplayAdapter
+from app.adapters.typescript_nextjs import TypeScriptNextJsAdapter
+from app.adapters.typescript_node import TypeScriptNodeAdapter
+from app.adapters.typescript_react import TypeScriptReactSpaAdapter
+from app.adapters.vue_sfc import VueSfcDisplayAdapter
+
+
+def build_default_registry() -> AdapterRegistry:
+    """Instantiate an AdapterRegistry populated with all implemented 3-tier adapters."""
+    registry = AdapterRegistry()
+
+    # Tier 1: Database & Schema/ORM Truth
+    registry.register_truth(PostgresSqlAlchemyAdapter())
+    registry.register_truth(PrismaSchemaAdapter())
+    registry.register_truth(DrizzleOrmAdapter())
+    registry.register_truth(DjangoOrmAdapter())
+    registry.register_truth(SqlDdlTruthAdapter())
+    registry.register_truth(RustSqlTruthAdapter())
+
+    # Tier 2: Backend Manipulation
+    registry.register_manipulator(PythonFastApiAdapter())
+    registry.register_manipulator(TypeScriptNodeAdapter())
+    registry.register_manipulator(PythonDjangoAdapter())
+    registry.register_manipulator(GoHttpAdapter())
+    registry.register_manipulator(RustHttpAdapter())
+
+    # Tier 3: Frontend Display
+    registry.register_display(TypeScriptNextJsAdapter())
+    registry.register_display(TypeScriptReactSpaAdapter())
+    registry.register_display(VueSfcDisplayAdapter())
+    registry.register_display(SvelteKitDisplayAdapter())
+    registry.register_display(RustWasmDisplayAdapter())
+
+    return registry

wythe-0.1.0/backend/app/adapters/a11y_inspect.py

@@ -0,0 +1,134 @@
+"""Tier 3 Accessibility (`DISP-005`) static markup inspector for JSX/TSX, Vue, Svelte, and Rust WASM."""
+
+from __future__ import annotations
+
+import re
+
+from app.adapters.base import RawCandidateFinding
+
+# Match opening tags (<img ...>, <div ...>, <span ...>, <input ...>) without stopping early on JSX `=>` arrows
+_IMG_TAG_RE = re.compile(r"<img\b(?P<attrs>(?:=>|[^>\"']|\"[^\"]*\"|'[^']*')*)>", re.IGNORECASE)
+_NON_INTERACTIVE_CLICK_RE = re.compile(
+    r"<(?P<tag>div|span)\b(?P<attrs>(?:=>|[^>\"']|\"[^\"]*\"|'[^']*'){0,500}?"
+    r"\b(?:onClick|on:click|@click|onclick)\s*=[\s\S]{0,240}?)>",
+)
+_INPUT_TAG_RE = re.compile(
+    r"<(?P<tag>input|select|textarea)\b(?P<attrs>(?:=>|[^>\"']|\"[^\"]*\"|'[^']*')*)>",
+)
+_EMPTY_BUTTON_RE = re.compile(
+    r"<button\b(?P<attrs>(?:=>|[^>\"']|\"[^\"]*\"|'[^']*')*)>\s*"
+    r"(?:<[A-Z][A-Za-z0-9_.]*\b[^>]*/\s*>\s*|<(?:svg|i)\b[\s\S]{0,400}?/\s*>\s*|<(?:svg|i)\b[\s\S]{0,400}?</(?:svg|i)>\s*)+"
+    r"</button>",
+)
+_LABEL_FOR_RE = re.compile(r"""<label\b[^>]*?\b(?:htmlFor|for)\s*=\s*(?:['"](?P<id>[^'"]+)['"]|\{(?P<expr>[^}]+)\})""")
+_WRAPPING_LABEL_RE = re.compile(r"<label\b(?:(?!</label>)[\s\S]){0,1500}?</label>")
+_ID_ATTR_RE = re.compile(r"""\bid\s*=\s*(?:['"](?P<id>[^'"]+)['"]|\{(?P<expr>[^}]+)\})""")
+_HIDDEN_INPUT_RE = re.compile(r"""\btype\s*=\s*['"](?:hidden|submit|reset|button)['"]""", re.IGNORECASE)
+
+
+def scan_a11y_markup_findings(
+    raw_source: str,
+    node_id: str,
+    rel_repo: str,
+) -> list[RawCandidateFinding]:
+    """Inspect raw UI template/JSX/RSX markup for deterministic WCAG (`DISP-005`) violations."""
+    findings: list[RawCandidateFinding] = []
+    seen_lines: set[tuple[int, str]] = set()
+
+    def emit(lineno: int, kind: str, title: str, detail: str, remediation: str) -> None:
+        if (lineno, kind) in seen_lines or len(findings) >= 15:
+            return
+        seen_lines.add((lineno, kind))
+        findings.append(
+            RawCandidateFinding(
+                rule_code="DISP-005",
+                node_id=node_id,
+                source_file=rel_repo,
+                line=lineno,
+                title=title,
+                detail=detail,
+                remediation=remediation,
+            )
+        )
+
+    # 1. <img> without alt attribute (unless decorative aria-hidden="true" or role="presentation"/"none")
+    for m in _IMG_TAG_RE.finditer(raw_source):
+        attrs = m.group("attrs")
+        if re.search(r"\balt\s*=", attrs) or re.search(r"""\baria-hidden\s*=\s*['"]true['"]""", attrs):
+            continue
+        if re.search(r"""\brole\s*=\s*['"](?:presentation|none)['"]""", attrs):
+            continue
+        if "{..." in attrs:
+            continue
+        lineno = raw_source.count("\n", 0, m.start()) + 1
+        emit(
+            lineno,
+            "img_alt",
+            "Image element `<img>` missing `alt` text (`WCAG 1.1.1`)",
+            f"{rel_repo}:{lineno} renders `<img>` without an `alt` attribute (use `alt=\"\"` if purely decorative).",
+            "Provide descriptive `alt` text or `alt=\"\"` with `aria-hidden=\"true\"` for decorative images.",
+        )
+
+    # 2. Click handlers on non-interactive <div>/<span> without role + keyboard focusability
+    for m in _NON_INTERACTIVE_CLICK_RE.finditer(raw_source):
+        tag = m.group("tag")
+        attrs = m.group("attrs")
+        if re.search(r"""\baria-hidden\s*=\s*['"]true['"]""", attrs):
+            continue
+        has_role = bool(re.search(r"\brole\s*=", attrs))
+        has_tab = bool(re.search(r"\btab[Ii]ndex\s*=", attrs))
+        if has_role and has_tab:
+            continue
+        lineno = raw_source.count("\n", 0, m.start()) + 1
+        emit(
+            lineno,
+            "div_click",
+            f"Non-interactive `<{tag}>` has click handler without keyboard/ARIA semantics (`WCAG 2.1.1`)",
+            f"{rel_repo}:{lineno} attaches a click handler to `<{tag}>` without `role` and `tabIndex`.",
+            "Replace with a semantic `<button>` element, or add `role=\"button\"`, `tabIndex={0}`, and `onKeyDown`.",
+        )
+
+    # 3. Icon-only <button> without aria-label / aria-labelledby / title
+    for m in _EMPTY_BUTTON_RE.finditer(raw_source):
+        attrs = m.group("attrs")
+        if re.search(r"\b(?:aria-label|aria-labelledby|title)\s*=", attrs) or "{..." in attrs:
+            continue
+        lineno = raw_source.count("\n", 0, m.start()) + 1
+        emit(
+            lineno,
+            "icon_btn",
+            "Icon-only `<button>` missing accessible name (`WCAG 4.1.2`)",
+            f"{rel_repo}:{lineno} renders an icon-only `<button>` with no `aria-label`, `aria-labelledby`, or visible text.",
+            "Add `aria-label=\"...\"` or visually-hidden `<span className=\"sr-only\">` text inside the button.",
+        )
+
+    # 4. Orphaned form controls (<input>/<select>/<textarea> without label[for], wrapping <label>, or aria-label)
+    labeled_ids = {
+        (lm.group("id") or lm.group("expr") or "").strip()
+        for lm in _LABEL_FOR_RE.finditer(raw_source)
+    }
+    wrapped_spans = [wm.span() for wm in _WRAPPING_LABEL_RE.finditer(raw_source)]
+    for m in _INPUT_TAG_RE.finditer(raw_source):
+        tag = m.group("tag")
+        attrs = m.group("attrs")
+        if _HIDDEN_INPUT_RE.search(attrs) or "{..." in attrs:
+            continue
+        if re.search(r"\b(?:aria-label|aria-labelledby|title)\s*=", attrs):
+            continue
+        if any(ws <= m.start() and m.end() <= we for ws, we in wrapped_spans):
+            continue
+        idm = _ID_ATTR_RE.search(attrs)
+        if idm:
+            id_val = (idm.group("id") or idm.group("expr") or "").strip()
+            if id_val and id_val in labeled_ids:
+                continue
+        lineno = raw_source.count("\n", 0, m.start()) + 1
+        emit(
+            lineno,
+            "orphan_input",
+            f"Form control `<{tag}>` lacks associated `<label>` or `aria-label` (`WCAG 1.3.1`)",
+            f"{rel_repo}:{lineno} renders `<{tag}>` without a matching `<label htmlFor=...>` or `aria-label`.",
+            "Associate a `<label htmlFor=\"...\">`, wrap in `<label>`, or add `aria-label=\"...\"`.",
+        )
+
+    return findings