cc-visual-walkthrough 0.2.0__tar.gz

cc_visual_walkthrough-0.2.0/.env.example

@@ -0,0 +1,5 @@
+# Env-var NAMES referenced by ccwalk.yaml live here as examples.
+# Real values go in your environment or an untracked .env.
+# Demo app credentials (throwaway, hardcoded in demo/app.py on purpose):
+CCWALK_DEMO_USER=demo
+CCWALK_DEMO_PASS=demo123

cc_visual_walkthrough-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.work/
+__pycache__/
+*.pyc
+.venv/
+reports/
+dist/
+.pytest_cache/
+.ruff_cache/

cc_visual_walkthrough-0.2.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to cc-visual-walkthrough. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow SemVer.
+
+## [0.2.0] - 2026-08-30
+
+Publish-readiness pass from an independent code review: the daemon
+pid-ownership check works without `/proc` (falls back to `ps`; when
+neither is available a live pid's pidfile is never auto-cleaned, so a
+daemon can't be orphaned on macOS); an occupied port produces a clean
+message naming `serve status`/`serve stop` instead of a traceback;
+`ccwalk report` re-renders no longer destroy a failed step's captured
+traceback (the `log` field survives the round-trip); `--capture-only`
+uses a fresh browser context per viewport x variant so a variant's
+persisted side effects (theme toggles, cookies) can't contaminate later
+captures; Markdown report alt text is escaped; sdist excludes the local
+serve log and dev docs; README links render on PyPI; the setup skill
+installs the CLI from the plugin root first (works before and after
+PyPI publication); version 0.2.0 everywhere with a test pinning
+pyproject/`__init__`/plugin.json agreement.
+
+## [0.1.0] - 2026-08-29
+
+Live manual-testing round (pre-release): `ccwalk serve` -- a local
+report server with a generated runs index at `/` (one row per run,
+newest first, PASS/WARN/FAIL counts, linked reports; `--daemon` /
+`serve stop` / `serve status`, pidfile-tracked, restart-on-start,
+`Cache-Control: no-store` everywhere). The setup skill now offers to
+start the server after the first verified run, the run skill hands back
+the served index URL when the server is up, and two new skills landed:
+`/ccwalk:serve` (start/restart/stop + link) and `/ccwalk:help` (live
+status + command reference). Skills also gained a stale-build guard:
+`ccwalk --version` is compared against the plugin's own version, with a
+reinstall-from-plugin-source remedy on mismatch.
+
+E2E dry-run polish (pre-release): local-checkout install path documented,
+`ccwalk install-browsers` reports success plainly, `doctor` auto-exempts
+the configured login page from auth (plus `--no-auth`), `ccwalk report
+--embed` writes `report_embedded.html` alongside `report.html` (use
+`--in-place` to overwrite), and the setup skill's port probe covers
+8500/8888 and defers to the project's own config first.
+
+Initial release, extracted and generalized from a larger private
+project's internal visual-testing system, then hardened by a five-agent
+adversarial review round (code review, real-project field test, release
+audit) before publish.
+
+### Added
+- Spec-driven Playwright walkthrough runner: Python `Step` specs,
+  per-group browser contexts and video segments, per-step screenshots,
+  non-fatal assertions (WARN, never abort), FAIL-with-error-screenshot,
+  blocked-step cascade when a group's step fails.
+- Auth strategies via `ccwalk.yaml`: form auto-login, localStorage,
+  cookie, header (header injection scoped to the app's origin only).
+- Reports: dark-theme HTML (escaped, video posters, notes callouts),
+  Markdown twin, extended `run_meta.json` (the agent triage interface,
+  including tracebacks for failed steps); `--embed` single-file mode;
+  `--mp4` Safari transcode.
+- `ccwalk` CLI: `init`, `run` (`--start-app` with imposter refusal and
+  process-group teardown, `--capture-only` design mode), `doctor`
+  (selector finder with interactive-element inventory and quote-safe
+  text selectors), `report` (re-render), `install-browsers`.
+- Claude Code plugin (`ccwalk`): `/ccwalk:setup` tailoring skill and
+  `/ccwalk:run` run-and-triage skill.
+- Bundled FastAPI + htmx demo app with a committed example report; CI
+  runs the real tour on every push and publishes it to GitHub Pages.
+- 99 unit tests (no browser required) plus the demo tour as the
+  browser-driving integration test.

cc_visual_walkthrough-0.2.0/LICENSE

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

cc_visual_walkthrough-0.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: cc-visual-walkthrough
+Version: 0.2.0
+Summary: Spec-driven Playwright walkthroughs for Claude Code: records and captures browser tours of your web app into shareable HTML reports with screenshots, video, and non-fatal regression assertions.
+Project-URL: Homepage, https://github.com/nickjrotundo/cc-visual-walkthrough
+Project-URL: Repository, https://github.com/nickjrotundo/cc-visual-walkthrough
+Project-URL: Issues, https://github.com/nickjrotundo/cc-visual-walkthrough/issues
+Project-URL: Changelog, https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/CHANGELOG.md
+Author: Nick Rotundo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,demo,playwright,screenshots,visual-testing,walkthrough
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: playwright>=1.40
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: demo
+Requires-Dist: fastapi>=0.110; extra == 'demo'
+Requires-Dist: python-multipart>=0.0.9; extra == 'demo'
+Requires-Dist: uvicorn>=0.27; extra == 'demo'
+Description-Content-Type: text/markdown
+
+# CC Visual Walkthrough
+
+[![CI](https://github.com/nickjrotundo/cc-visual-walkthrough/actions/workflows/ci.yml/badge.svg)](https://github.com/nickjrotundo/cc-visual-walkthrough/actions/workflows/ci.yml)
+
+Spec-driven visual walkthroughs for [Claude Code](https://claude.com/claude-code):
+records and captures browser tours of your web app into shareable HTML
+reports -- per-step screenshots, per-group video, and non-fatal regression
+assertions -- with Claude Code generating and maintaining the tour spec for
+you.
+
+Every visual testing tool on the market exists to *gate merges*: red
+builds, baseline approvals, pixel diffs. This one produces the artifact an
+AI-driven development loop actually needs instead: **evidence that the app
+works end-to-end after this iteration**, in a form both humans (HTML with
+embedded media) and the agent itself (Markdown twin + `run_meta.json`) can
+read. It is deliberately not a test framework -- if you need gating
+regression tests, use Playwright's own runner alongside it.
+
+## What a run produces
+
+```
+reports/walkthrough/<UTC timestamp>/
+  report.html        # dark-theme report: screenshots, video, PASS/WARN/FAIL badges
+  report.md          # same content as Markdown -- agent- and diff-friendly
+  run_meta.json      # machine-readable per-step results (the triage interface)
+  screenshots/*.png
+  videos/<group>.webm
+```
+
+Assertions never abort the tour: a failed assertion marks the step WARN
+and the run continues, because a transient timeout should not destroy an
+evidence-gathering pass. An action that *throws* (selector never appeared)
+marks the step FAIL, captures an error screenshot, and still continues.
+The process exits non-zero only on FAIL.
+
+## Install (Claude Code -- the supported path)
+
+```
+/plugin marketplace add nickjrotundo/cc-visual-walkthrough
+/plugin install ccwalk@cc-visual-walkthrough
+```
+
+Then, in the project you want toured:
+
+```
+/ccwalk:setup
+```
+
+The setup skill inspects your project, finds the dev server and routes,
+asks which flows matter, writes `ccwalk.yaml` and a tailored spec, runs a
+verification pass, and teaches your project's `CLAUDE.md` to regenerate
+the tour after each feature wave. After that:
+
+```
+/ccwalk:run
+```
+
+runs the tour and triages the results (real regression vs. flaky selector
+vs. environment hiccup).
+
+The plugin needs the `ccwalk` CLI on PATH (the setup skill checks and
+offers to do this):
+
+```bash
+uv tool install cc-visual-walkthrough           # from PyPI
+# or straight from the repo:
+#   uv tool install git+https://github.com/nickjrotundo/cc-visual-walkthrough
+# or from a local checkout, into a venv:
+#   uv pip install /path/to/cc-visual-walkthrough
+# one-time browser install (works for pip/uv tool/pipx installs alike):
+ccwalk install-browsers
+```
+
+> The `ccwalk` CLI can be driven by hand without Claude Code, but that
+> path is unsupported -- you are on your own.
+
+## Supported platforms
+
+Linux and WSL2 are tested. macOS should work (Playwright is
+cross-platform) but is untested and has no system-chromium fallback --
+use `ccwalk install-browsers`. Native Windows is unsupported:
+`--start-app` process management is POSIX-only.
+
+## Serving reports
+
+The built-in server is the browsing story -- especially on WSL2, ssh,
+or any headless box where "just open the HTML file" is not a thing:
+
+```bash
+ccwalk serve --daemon     # background server; prints the index URL
+ccwalk serve status       # running? where?
+ccwalk serve stop
+```
+
+It serves the report directory at `http://127.0.0.1:8378/` with a
+generated **runs index** at `/`: one row per run, newest first, with its
+PASS/WARN/FAIL counts, spec, git head, and duration -- click a run to
+open its report. Every response is `Cache-Control: no-store`, so the
+index is always current. `serve` (start) doubles as restart; localhost
+only unless you explicitly `--bind 0.0.0.0`. WSL2: localhost forwarding
+to the Windows browser usually works, but not always - if it doesn't,
+open the URL in a Linux browser (e.g. WSLg-launched Chrome). The setup
+skill offers to start this server after the first verified run, and
+`/ccwalk:serve` manages it any time.
+
+Alternatives still work: `report.html` opens fully from `file://` in
+Chromium-family browsers (images and webm play). For Safari/iOS you need
+both `--mp4` (webm does not play there) and a Range-capable server: the
+stdlib server (including `ccwalk serve` and `python3 -m http.server`)
+does NOT support Range requests and will not fix Safari video -- use
+`npx serve`, caddy, or nginx. `--embed` produces a single self-contained
+file you can attach to an email.
+
+## The pieces
+
+- **Spec** -- a Python module with a `STEPS: list[Step]`. Python, not
+  YAML: real tours need real control flow. Each `Step` has a name, a
+  `group` (steps in a group share one browser context and one video
+  segment), a list of action dicts, and optional non-fatal assertions.
+- **Actions** -- `goto`, `click`, `fill`, `press`, `hover`,
+  `select_option`, `upload_file`, `wait_for`, `wait_ms`, `set_viewport`,
+  `screenshot`, `scroll_into_view`, `login_form`, `override_session`,
+  `mock_route`, and `wait_for_condition` (screenshots a progress state
+  while polling -- how slow async work gets captured mid-flight).
+  App-specific verbs go in a `custom_actions` module.
+- **Auth** -- configured, not coded: `form` (auto-login per fresh
+  context), `localstorage`, `cookie`, `header`, or `none`. Credentials
+  are env-var *names* in config; values live in your environment or
+  `.env`. Use a disposable test account.
+- **Design capture mode** -- `ccwalk run --capture-only /page
+  --viewports 390,768,1440` screenshots one page across viewports (and
+  configured `capture_variants`, e.g. a dark-mode toggle) for design
+  review.
+- **Doctor** -- `ccwalk doctor /page --find "Submit"` prints stable
+  selector candidates (data-testid > id > role > text) for fixing a
+  failing step.
+- **Single-file report** -- `ccwalk report <run_dir> --embed` re-renders
+  a run into a self-contained `report_embedded.html` (all media inlined,
+  email-attachable); `--mp4` transcodes videos for Safari (needs
+  ffmpeg). `/ccwalk:help` gives a live status + command reference in a
+  Claude Code session.
+
+## Try the bundled demo
+
+```bash
+git clone https://github.com/nickjrotundo/cc-visual-walkthrough
+cd cc-visual-walkthrough && uv sync && uv run ccwalk install-browsers
+CCWALK_DEMO_USER=demo CCWALK_DEMO_PASS=demo123 \
+  uv run ccwalk run --config demo/ccwalk.yaml --start-app
+```
+
+This boots a tiny FastAPI + htmx notes app, tours it (login flow, CRUD,
+a deliberately slow "analyze" operation captured mid-progress, a mobile
+viewport), and writes the report to `reports/walkthrough/`. A committed
+example of the output lives in [`examples/`](https://github.com/nickjrotundo/cc-visual-walkthrough/tree/main/examples).
+
+## Documentation
+
+- [DESIGN.md](https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/DESIGN.md) -- positioning, architecture, and the design
+  decisions (most of them learned the hard way in the system this was
+  extracted from)
+- [ANALYSIS.md](https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/ANALYSIS.md) -- honest limitations and the v0.2 roadmap
+- [BUILD-LOG.md](https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/BUILD-LOG.md) -- how this repo was built with Claude
+  Code, as a worked example of AI-driven development
+
+## Support
+
+Questions and bugs: [GitHub Issues](https://github.com/nickjrotundo/cc-visual-walkthrough/issues).

cc_visual_walkthrough-0.2.0/README.md

@@ -0,0 +1,168 @@
+# CC Visual Walkthrough
+
+[![CI](https://github.com/nickjrotundo/cc-visual-walkthrough/actions/workflows/ci.yml/badge.svg)](https://github.com/nickjrotundo/cc-visual-walkthrough/actions/workflows/ci.yml)
+
+Spec-driven visual walkthroughs for [Claude Code](https://claude.com/claude-code):
+records and captures browser tours of your web app into shareable HTML
+reports -- per-step screenshots, per-group video, and non-fatal regression
+assertions -- with Claude Code generating and maintaining the tour spec for
+you.
+
+Every visual testing tool on the market exists to *gate merges*: red
+builds, baseline approvals, pixel diffs. This one produces the artifact an
+AI-driven development loop actually needs instead: **evidence that the app
+works end-to-end after this iteration**, in a form both humans (HTML with
+embedded media) and the agent itself (Markdown twin + `run_meta.json`) can
+read. It is deliberately not a test framework -- if you need gating
+regression tests, use Playwright's own runner alongside it.
+
+## What a run produces
+
+```
+reports/walkthrough/<UTC timestamp>/
+  report.html        # dark-theme report: screenshots, video, PASS/WARN/FAIL badges
+  report.md          # same content as Markdown -- agent- and diff-friendly
+  run_meta.json      # machine-readable per-step results (the triage interface)
+  screenshots/*.png
+  videos/<group>.webm
+```
+
+Assertions never abort the tour: a failed assertion marks the step WARN
+and the run continues, because a transient timeout should not destroy an
+evidence-gathering pass. An action that *throws* (selector never appeared)
+marks the step FAIL, captures an error screenshot, and still continues.
+The process exits non-zero only on FAIL.
+
+## Install (Claude Code -- the supported path)
+
+```
+/plugin marketplace add nickjrotundo/cc-visual-walkthrough
+/plugin install ccwalk@cc-visual-walkthrough
+```
+
+Then, in the project you want toured:
+
+```
+/ccwalk:setup
+```
+
+The setup skill inspects your project, finds the dev server and routes,
+asks which flows matter, writes `ccwalk.yaml` and a tailored spec, runs a
+verification pass, and teaches your project's `CLAUDE.md` to regenerate
+the tour after each feature wave. After that:
+
+```
+/ccwalk:run
+```
+
+runs the tour and triages the results (real regression vs. flaky selector
+vs. environment hiccup).
+
+The plugin needs the `ccwalk` CLI on PATH (the setup skill checks and
+offers to do this):
+
+```bash
+uv tool install cc-visual-walkthrough           # from PyPI
+# or straight from the repo:
+#   uv tool install git+https://github.com/nickjrotundo/cc-visual-walkthrough
+# or from a local checkout, into a venv:
+#   uv pip install /path/to/cc-visual-walkthrough
+# one-time browser install (works for pip/uv tool/pipx installs alike):
+ccwalk install-browsers
+```
+
+> The `ccwalk` CLI can be driven by hand without Claude Code, but that
+> path is unsupported -- you are on your own.
+
+## Supported platforms
+
+Linux and WSL2 are tested. macOS should work (Playwright is
+cross-platform) but is untested and has no system-chromium fallback --
+use `ccwalk install-browsers`. Native Windows is unsupported:
+`--start-app` process management is POSIX-only.
+
+## Serving reports
+
+The built-in server is the browsing story -- especially on WSL2, ssh,
+or any headless box where "just open the HTML file" is not a thing:
+
+```bash
+ccwalk serve --daemon     # background server; prints the index URL
+ccwalk serve status       # running? where?
+ccwalk serve stop
+```
+
+It serves the report directory at `http://127.0.0.1:8378/` with a
+generated **runs index** at `/`: one row per run, newest first, with its
+PASS/WARN/FAIL counts, spec, git head, and duration -- click a run to
+open its report. Every response is `Cache-Control: no-store`, so the
+index is always current. `serve` (start) doubles as restart; localhost
+only unless you explicitly `--bind 0.0.0.0`. WSL2: localhost forwarding
+to the Windows browser usually works, but not always - if it doesn't,
+open the URL in a Linux browser (e.g. WSLg-launched Chrome). The setup
+skill offers to start this server after the first verified run, and
+`/ccwalk:serve` manages it any time.
+
+Alternatives still work: `report.html` opens fully from `file://` in
+Chromium-family browsers (images and webm play). For Safari/iOS you need
+both `--mp4` (webm does not play there) and a Range-capable server: the
+stdlib server (including `ccwalk serve` and `python3 -m http.server`)
+does NOT support Range requests and will not fix Safari video -- use
+`npx serve`, caddy, or nginx. `--embed` produces a single self-contained
+file you can attach to an email.
+
+## The pieces
+
+- **Spec** -- a Python module with a `STEPS: list[Step]`. Python, not
+  YAML: real tours need real control flow. Each `Step` has a name, a
+  `group` (steps in a group share one browser context and one video
+  segment), a list of action dicts, and optional non-fatal assertions.
+- **Actions** -- `goto`, `click`, `fill`, `press`, `hover`,
+  `select_option`, `upload_file`, `wait_for`, `wait_ms`, `set_viewport`,
+  `screenshot`, `scroll_into_view`, `login_form`, `override_session`,
+  `mock_route`, and `wait_for_condition` (screenshots a progress state
+  while polling -- how slow async work gets captured mid-flight).
+  App-specific verbs go in a `custom_actions` module.
+- **Auth** -- configured, not coded: `form` (auto-login per fresh
+  context), `localstorage`, `cookie`, `header`, or `none`. Credentials
+  are env-var *names* in config; values live in your environment or
+  `.env`. Use a disposable test account.
+- **Design capture mode** -- `ccwalk run --capture-only /page
+  --viewports 390,768,1440` screenshots one page across viewports (and
+  configured `capture_variants`, e.g. a dark-mode toggle) for design
+  review.
+- **Doctor** -- `ccwalk doctor /page --find "Submit"` prints stable
+  selector candidates (data-testid > id > role > text) for fixing a
+  failing step.
+- **Single-file report** -- `ccwalk report <run_dir> --embed` re-renders
+  a run into a self-contained `report_embedded.html` (all media inlined,
+  email-attachable); `--mp4` transcodes videos for Safari (needs
+  ffmpeg). `/ccwalk:help` gives a live status + command reference in a
+  Claude Code session.
+
+## Try the bundled demo
+
+```bash
+git clone https://github.com/nickjrotundo/cc-visual-walkthrough
+cd cc-visual-walkthrough && uv sync && uv run ccwalk install-browsers
+CCWALK_DEMO_USER=demo CCWALK_DEMO_PASS=demo123 \
+  uv run ccwalk run --config demo/ccwalk.yaml --start-app
+```
+
+This boots a tiny FastAPI + htmx notes app, tours it (login flow, CRUD,
+a deliberately slow "analyze" operation captured mid-progress, a mobile
+viewport), and writes the report to `reports/walkthrough/`. A committed
+example of the output lives in [`examples/`](https://github.com/nickjrotundo/cc-visual-walkthrough/tree/main/examples).
+
+## Documentation
+
+- [DESIGN.md](https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/DESIGN.md) -- positioning, architecture, and the design
+  decisions (most of them learned the hard way in the system this was
+  extracted from)
+- [ANALYSIS.md](https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/ANALYSIS.md) -- honest limitations and the v0.2 roadmap
+- [BUILD-LOG.md](https://github.com/nickjrotundo/cc-visual-walkthrough/blob/main/BUILD-LOG.md) -- how this repo was built with Claude
+  Code, as a worked example of AI-driven development
+
+## Support
+
+Questions and bugs: [GitHub Issues](https://github.com/nickjrotundo/cc-visual-walkthrough/issues).