proof-artifacts 0.1.0-preview.0

package/README.md

@@ -0,0 +1,94 @@
+# proof-artifacts
+
+Proof artifacts for coding agents using isolated Linux desktops.
+
+This project focuses on one first version: give each agent an isolated Linux desktop it can use to visually verify app changes and produce screenshots or videos as proof.
+
+## Quick Start
+
+Agent-first use is the intended path: install the skill, then ask the agent to visually test your app on the VPS. The skill tells the agent to check whether `proof-artifacts` is installed, install it from npm after publish or from the source repo before publish, run `doctor`/`smoke`, and produce a report.
+
+```sh
+npm install -g . # from this repo until the npm package is published
+proof-artifacts doctor
+proof-artifacts detect
+proof-artifacts install-skill
+proof-artifacts smoke
+proof-artifacts start --name demo --project . --url https://example.com --fullscreen
+proof-artifacts open https://example.com --name demo
+proof-artifacts screenshot --name demo --label example
+proof-artifacts record start --name demo --label walkthrough
+proof-artifacts record stop --name demo
+proof-artifacts report --name demo
+proof-artifacts status --name demo
+proof-artifacts list
+proof-artifacts stop --name demo
+```
+
+The noVNC desktop is bound to `127.0.0.1` with a Docker-assigned port by default. The CLI prints the exact URL and writes it to the session manifest.
+If your app is running on the VPS host at `localhost`, pass the URL when starting and the CLI will infer host networking:
+
+```sh
+proof-artifacts start --name demo --project . --url http://127.0.0.1:3000 --fullscreen
+proof-artifacts open http://127.0.0.1:3000 --name demo
+proof-artifacts doctor --name demo --url http://127.0.0.1:3000
+```
+
+On VPSes where Docker bridge-to-host traffic is blocked, this avoids the `host.docker.internal` trap by using `--network host` automatically for localhost URLs.
+
+## Agent Experience
+
+Once the skill is installed, the user should be able to ask:
+
+```txt
+Use proof-artifacts to run my app, visually test it, record a short walkthrough, and give me the report.
+```
+
+The agent should then:
+
+- Verify or install the CLI.
+- Check Docker with `proof-artifacts doctor`.
+- Run `proof-artifacts smoke` on new machines.
+- Run the project dev server from the detected package scripts or project docs when testing a web app.
+- Start an isolated desktop for the task.
+- Capture screenshots and recordings.
+- Return the generated `report.html` path and use the report summary/failure section to explain what worked or broke.
+
+## Requirements
+
+- Linux VPS or cloud VM
+- Node.js 18+
+- Docker Engine
+
+## What v0 Provides
+
+- Dockerized Linux desktop per session
+- Xvfb virtual display
+- Chromium browser
+- Fullscreen browser mode for cleaner visual proof
+- noVNC viewer
+- PNG screenshots
+- MP4 recordings
+- `smoke` end-to-end VPS verification
+- Versioned session manifests and HTML/JSON reports with summary cards, artifact counts, durations, and failure context
+- `list` and `status` commands for session lifecycle visibility
+- Automatic localhost noVNC port assignment for parallel sessions
+- `start --url` network inference for VPS localhost apps
+- Host-app URL diagnostics and runtime checks with `doctor --url`, `doctor --name`, and `doctor --deep`
+- Project type hints with `detect`
+- Linux desktop app launching with `launch`
+- Piped desktop automation scripts with `exec --stdin`
+- Conservative cleanup for stale containers, `stop --all` for managed containers, and artifact deletion opt-in
+- Codex skill installer
+
+## Still Planned
+
+- Publishing a public prebuilt runtime image from CI.
+- More project-type detectors and runtime images for common Linux desktop dependencies.
+- An MCP server that wraps the stable CLI lifecycle.
+
+## Design
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+For VPS setup and SSH tunneling, see [docs/VPS.md](docs/VPS.md).