diff --git a/CHANGELOG.md b/CHANGELOG.md index b4049ca..c7a0c61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ All notable changes to Wirehouse are listed here. The format follows ## [Unreleased] ### Changed +- **A README for the public launch** (2026-10-18) + - Summary: The README opens with the new demo, a "Why Wirehouse" section of what the tool guarantees + (evidence for each connection, one offline file, any agent or none, safe to share), a comparison + with hand-drawn and Mermaid diagrams, and a gallery of eight features; the safety section says what + happens when you scan a repository you did not write. + - Why: the README is the first thing a visitor sees, and it explained what Wirehouse draws more than + why that is worth having. +- **Demo pictures of the 0.3.0 viewer** (2026-10-18) + - Summary: `docs/assets` has a new animated demo and MP4, nine screenshots and a share card of the + 0.3.0 viewer on the demo map, plus `one-map-two-readers.png` (`wirehouse export` next to the + warehouse). They are rendered frame by frame on a virtual clock, so motion is smooth without a GPU. + - Why: every picture still showed the 0.2.0 viewer. - **The improvement log records Pass 2** (2026-10-18) - Summary: IMPROVEMENT_LOG.md has a Pass 2 entry: areas covered, findings by severity, the menu, what was done with its measured effect, what was deferred and the next pass's focus. @@ -18,6 +30,12 @@ All notable changes to Wirehouse are listed here. The format follows - Why: the published demo was drawn by the 0.2.0 viewer, without the Checks panel, change review or any of the Pass 1 and Pass 2 fixes, and its enrichment could not be reproduced. +### Fixed +- **README images show on PyPI** (2026-10-18) + - Summary: Images and links in the README use absolute GitHub URLs. + - Why: PyPI renders the README as the project description but cannot resolve paths inside the + repository, so every picture was broken there. + ## [0.3.0] - 2026-10-18 ### Added diff --git a/README.md b/README.md index 0742e82..c38a108 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,110 @@

- - Wirehouse: walk through your codebase like a warehouse. + + Wirehouse: walk through your codebase like a warehouse.

- Wirehouse turns a repository into a 3D warehouse you can walk around: services are shipping - containers, databases are silos, auth is a security gate, and every pipe is a real connection - found in the code. Trace where a request goes, take a guided tour, and share it all as - one offline HTML file. Built for your agents. + See how your codebase really fits together, and prove it.
+ Wirehouse maps a repository from its code and turns it into a 3D warehouse you can walk: + services are shipping containers, databases are silos, auth is a security gate, and every pipe is + a connection found in the code, with the file and line that prove it. Trace where a request goes, + take a guided tour, and share it all as one offline HTML file.

CI Python 3.11+ - MIT License + MIT License One offline HTML file - Built for your agents + Works with any coding agent

Try the live demo · Quick start · + Why Wirehouse · How to use · - How it works · - Contributing + How it works

- Walking through the warehouse of fastapi/full-stack-fastapi-template: tracing what the backend reaches, walking a request from the user to PostgreSQL, entering the backend, the schema diagram, the floor plan and the Clipboard of tours and quests + The warehouse of fastapi/full-stack-fastapi-template: a downstream trace ripples out from the backend, the worker walks the route from Users to PostgreSQL, enters the backend's app folder, switches to the day shift, opens the PostgreSQL schema diagram and the floor plan
- The warehouse of fastapi/full-stack-fastapi-template, described by a coding agent. Open it yourself (one 1 MB HTML file) · MP4 with full-speed walking. + The warehouse of fastapi/full-stack-fastapi-template, described by a coding agent. + Open it yourself (one 1.2 MB HTML file) · + MP4

- + + +## Why Wirehouse + +Architecture diagrams go stale the day they are drawn, and reading a new codebase file by file tells +you *what* is there but not *how it fits together*. Wirehouse rebuilds the map from the code every +time, and holds it to one rule: **nothing is drawn that the code does not show.** + +- **A map you can check.** Every connection found in the code carries the file and line it was found + at, linked to your code host at the exact commit that was scanned. What an agent adds must cite real code or it + is left out, inferred links say so, and a **Checks** panel lists anything that was dropped and why. +- **Current in seconds, not a drawing to maintain.** Re-run it after a change; descriptions are + cached by a hash of the code, so only what changed is described again. `--against` shows exactly + which blocks, connections and files a change touched. +- **One file, nothing to host.** The page is a single offline HTML file with everything inlined: + no server, no account, no telemetry, no network loads. Email it, attach it to a pull request, or + publish it on GitHub Pages. +- **Answers real questions.** *What does this service reach?* Trace it, with hop counts. + *How does a request get to the database?* Walk the route stop by stop. *Where do I start?* Take + the tour, then go find things with quests. +- **Your agent, or no agent.** The `/wirehouse` skill uses the open `SKILL.md` format and works with + Claude Code, Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot and any agent that reads files. Without + one, the CLI still draws the full map with rule-based descriptions. +- **Safe to share.** Real `.env` files are never read, credential-looking text is cut from every + output, and `--share` removes your local paths before you publish. -## Why - -Architecture diagrams go stale the day they are drawn, and reading a new codebase file by file -tells you *what* is there but not *how it fits together*. Wirehouse builds the map from the code -every time, and makes exploring it feel like walking a well-run warehouse instead of reading a -wall of boxes and arrows: +

+ Left: architecture.md from wirehouse export, a table of connections with the file and line of each. Right: the same map as a 3D warehouse, with a downstream trace from the backend lit up. +
+ The same map as text for your agent or your pull request (wirehouse export), and as a place to walk. +

-- **New teammate?** Take the guided tour, then go find things on your own with quests. -- **Reviewing a change?** Trace what a service reaches before you touch it. -- **Explaining the system?** Walk the route from the user to the database and share the link. +### How it compares -Everything you see comes from evidence: each pipe lists the file and line it was found in, and -anything your agent adds has to cite real code or it is left out. +| | Hand-drawn diagram | Mermaid in the docs | Wirehouse | +|---|:---:|:---:|:---:| +| Built from the code | no | no | **yes** | +| File and line behind each connection | no | no | **yes** | +| Stays current without redrawing | no | no | **yes** | +| Follows env vars, compose, Terraform and CI, not just imports | by hand | by hand | **yes** | +| Shows what a change touched | no | in the diff | **yes** (`--against`) | +| Guided tours and traces for newcomers | no | no | **yes** | +| Text for a README or pull request | no | yes | **yes** (`wirehouse export`) | ## What you can do - - + + + + + + - - + + - - + +
Downstream trace from the backend, with rings and hop counts
Trace everything a block leads to, or everything that leads to it, with hop counts. File precise.
The worker walking the route from Users to PostgreSQL
Walk a route from A to B, hop by hop, with the code behind each step.
Downstream trace from the backend, with rings and hop counts
Trace everything a block leads to, or everything that leads to it, with hop counts. File precise.
The worker walking the route from Users to PostgreSQL, at stop 3 of 4
Walk a route from A to B, hop by hop, with the code behind each step.
A tour stop at useAuth.ts on a rack of frontend hooks
Guided tours and quests written by your agent from the real code, stop by stop with file and line.
Inside the backend's app folder: folders as crates, connections leaving through wall ports
Walk into any block. Folders are crates, files sit on racks with aisle signs, connections leave through wall ports.
Inside the backend: folders as crates, files on shelving racks
Walk into any block. Folders are crates, files sit on racks, connections leave through wall ports.
A guided tour stop
Guided tours and quests written by your agent from the real code, with your progress kept in the browser.
Schema diagram of the PostgreSQL database
Database rooms with columns, keys and a schema diagram.
2D floor plan with the backend selected
Floor plan in 2D for a quick overview, fully keyboard accessible.
Schema diagram of the PostgreSQL database
Database rooms with columns, keys and a schema diagram.
2D floor plan
Floor plan in 2D for a quick overview, fully keyboard accessible.
The Clipboard with the first-shift checklist, tours and quests
The Clipboard: a first-shift checklist, tours, quests and what you have inspected so far.
The main floor on the night shift
Night and day shift lighting; the page adapts its resolution to keep slower laptops responsive.
-Also: night and day shift lighting, search that walks you to anything, links that reopen the exact -view, commit-pinned links to GitHub, GitLab, Bitbucket and Azure DevOps, and pictures or -1200 × 630 share cards of what you are looking at. +Also: search that walks you to anything, links that reopen the exact view, commit-pinned links to +GitHub, GitLab, Bitbucket and Azure DevOps, pictures or 1200 × 630 share cards of what you are looking +at, and optional sound. ## Quick start @@ -139,8 +174,8 @@ change only asks the agent about what changed. Add `wirehouse-out/` to your `.gi ### 2. Walk around - - Web apps are kiosks, services are shipping containers, databases are silos, queues are conveyor belts, auth is a security gate, third-party APIs are the loading dock. + + Web apps are kiosks, services are shipping containers, databases are silos, queues are conveyor belts, auth is a security gate, third-party APIs are the loading dock. The floor is laid out from the entrance to the back: **Clients**, **Gateway and auth** (shown even @@ -318,8 +353,12 @@ Missing your stack? [Tell us where the map is wrong](https://github.com/creyes-g - Never reads real `.env` files. Env values, passwords, connection strings, column defaults and credentials inside git remotes are never written to the output. - Text written by the agent is checked for credential-looking strings, which are removed. +- Scanning a repository you did not write is safe: the scan never follows links out of the project, + never runs commands named by the repository's own git config, and an `enrichment.json` that came + with the repository is applied only with a warning, with every block or connection it removes + listed under **Checks**. -See [SECURITY.md](SECURITY.md) to report a problem. +See [SECURITY.md](https://github.com/creyes-git/wirehouse/blob/main/SECURITY.md) to report a problem. ## Limits @@ -343,8 +382,8 @@ Ideas welcome in [Discussions](https://github.com/creyes-git/wirehouse/discussio ## Contributing Contributions are welcome, and the most useful one is a project where the map is wrong. See -[CONTRIBUTING.md](CONTRIBUTING.md) for setup, the ground rules and where things live, and please -follow the [Code of Conduct](CODE_OF_CONDUCT.md). +[CONTRIBUTING.md](https://github.com/creyes-git/wirehouse/blob/main/CONTRIBUTING.md) for setup, the ground rules and where things live, and please +follow the [Code of Conduct](https://github.com/creyes-git/wirehouse/blob/main/CODE_OF_CONDUCT.md). ```bash pip install -e ".[dev]" && python -m pytest @@ -361,4 +400,4 @@ pip install -e ".[dev]" && python -m pytest ## License -[MIT](LICENSE) © Carlos Reyes +[MIT](https://github.com/creyes-git/wirehouse/blob/main/LICENSE) © Carlos Reyes diff --git a/TODO.md b/TODO.md index 5fa8cca..7b83ecf 100644 --- a/TODO.md +++ b/TODO.md @@ -50,9 +50,6 @@ suggested fix. Fixed items move to [CHANGELOG.md](CHANGELOG.md); the reasoning b Entity Framework Core edge from its code exists. · **Where:** `wirehouse/build.py` around the dependency-only edges (about lines 649-665 before Pass 2). · **Suggested fix:** drop the "no import found" label when any code edge between the same pair exists. -- **Date:** 2026-10-18 · **What:** README images use relative paths, which break on PyPI. - · **Where:** `README.md`. · **Suggested fix:** use absolute `raw.githubusercontent.com` URLs pinned to - `main`, or a separate PyPI long description. - **Date:** 2026-10-18 · **What:** An `--against` file that is JSON with `nodes` but no `edges` prints a traceback (`KeyError: 'edges'`). · **Where:** `wirehouse/cli.py` `_load_map`, `wirehouse/delta.py`. · **Suggested fix:** require `edges` to be a list in `_load_map`, with the same clear error. diff --git a/docs/assets/demo.mp4 b/docs/assets/demo.mp4 index fa04e4b..cd7a758 100644 Binary files a/docs/assets/demo.mp4 and b/docs/assets/demo.mp4 differ diff --git a/docs/assets/demo.webp b/docs/assets/demo.webp index fc0f213..501380a 100644 Binary files a/docs/assets/demo.webp and b/docs/assets/demo.webp differ diff --git a/docs/assets/one-map-two-readers.png b/docs/assets/one-map-two-readers.png new file mode 100644 index 0000000..b76396b Binary files /dev/null and b/docs/assets/one-map-two-readers.png differ diff --git a/docs/assets/screenshot-clipboard.png b/docs/assets/screenshot-clipboard.png index 8aca338..006cb72 100644 Binary files a/docs/assets/screenshot-clipboard.png and b/docs/assets/screenshot-clipboard.png differ diff --git a/docs/assets/screenshot-night.png b/docs/assets/screenshot-night.png index 7312073..ccd6ffa 100644 Binary files a/docs/assets/screenshot-night.png and b/docs/assets/screenshot-night.png differ diff --git a/docs/assets/screenshot-plan.png b/docs/assets/screenshot-plan.png index 3e33327..2793507 100644 Binary files a/docs/assets/screenshot-plan.png and b/docs/assets/screenshot-plan.png differ diff --git a/docs/assets/screenshot-room.png b/docs/assets/screenshot-room.png index 60f6c91..713707f 100644 Binary files a/docs/assets/screenshot-room.png and b/docs/assets/screenshot-room.png differ diff --git a/docs/assets/screenshot-route.png b/docs/assets/screenshot-route.png index c8e2cab..85a2d82 100644 Binary files a/docs/assets/screenshot-route.png and b/docs/assets/screenshot-route.png differ diff --git a/docs/assets/screenshot-schema.png b/docs/assets/screenshot-schema.png index 4979517..62c99ba 100644 Binary files a/docs/assets/screenshot-schema.png and b/docs/assets/screenshot-schema.png differ diff --git a/docs/assets/screenshot-tour.png b/docs/assets/screenshot-tour.png index f8b0826..f7e508f 100644 Binary files a/docs/assets/screenshot-tour.png and b/docs/assets/screenshot-tour.png differ diff --git a/docs/assets/screenshot-trace.png b/docs/assets/screenshot-trace.png index db43167..3f63448 100644 Binary files a/docs/assets/screenshot-trace.png and b/docs/assets/screenshot-trace.png differ diff --git a/docs/assets/screenshot-welcome.png b/docs/assets/screenshot-welcome.png index 367e538..601a2b5 100644 Binary files a/docs/assets/screenshot-welcome.png and b/docs/assets/screenshot-welcome.png differ diff --git a/docs/assets/share-card.png b/docs/assets/share-card.png index f8647a0..25bd542 100644 Binary files a/docs/assets/share-card.png and b/docs/assets/share-card.png differ