@exodus/xqa 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# @exodus/xqa
+
+CLI for running AI-powered QA agents against Exodus mobile apps on iOS.
+
+## Prerequisites
+
+- Node >= 22
+- pnpm
+- An Anthropic API key
+
+## Installation
+
+From the monorepo root:
+
+```bash
+pnpm install
+```
+
+Then build and link the CLI globally:
+
+```bash
+pnpm build:link   # build + link `xqa` into PATH
+```
+
+For active development:
+
+```bash
+pnpm dev:link     # build, link, and watch for changes
+```
+
+## Setup
+
+Copy the example env file and fill in your values:
+
+```bash
+cp .env.example .env.local
+```
+
+`.env.local` is loaded automatically at startup.
+
+## Environment Variables
+
+| Variable                       | Required | Default          | Description                                                                                 |
+| ------------------------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`            | Yes      | —                | Anthropic API key                                                                           |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | No       | —                | Gemini key — enables video analysis; required for `xqa analyse`                             |
+| `QA_RUN_ID`                    | No       | auto-generated   | Fixed run ID; auto-incremented when omitted                                                 |
+| `QA_EXPLORE_TIMEOUT_SECONDS`   | No       | —                | Max wall-clock time for an explore or spec run                                              |
+| `QA_WALLET_MNEMONIC`           | No       | —                | Wallet mnemonic; agent restores wallet before exploring when set                            |
+| `QA_BUILD_ENV`                 | No       | `prod`           | `dev` or `prod`; `dev` mode ignores debug overlays                                          |
+| `QA_STARTUP_STATE`             | No       | —                | `portfolio`, `new-wallet`, or `restore-wallet`; unset means app starts in its current state |
+| `QA_DESIGNS_DIR`               | No       | `./.xqa/designs` | Design artboards directory; enables visual regression checks when set                       |
+
+## Commands
+
+### `xqa explore [prompt]`
+
+Runs the explorer agent against the live simulator. Without a prompt the agent sweeps the entire app. With a prompt it focuses on the described flow.
+
+```bash
+xqa explore
+xqa explore "Try to send Bitcoin to an external address"
+xqa explore --verbose
+```
+
+Startup state (`QA_STARTUP_STATE`) controls what the agent sees on launch:
+
+- `portfolio` — main assets screen (default)
+- `new-wallet` — onboarding screen; agent taps through setup
+- `restore-wallet` — onboarding screen; agent restores wallet using `QA_WALLET_MNEMONIC`
+
+When `GOOGLE_GENERATIVE_AI_API_KEY` is set, a Gemini video analyser runs automatically after the explorer finishes.
+
+### `xqa spec <spec-file>`
+
+Runs the explorer against a markdown spec file. The agent navigates to the entry point defined in the frontmatter and verifies each described step.
+
+```bash
+xqa spec path/to/send-flow.md
+xqa spec path/to/send-flow.md --verbose
+```
+
+Spec file format:
+
+```markdown
+---
+feature: Send Flow
+entry: Assets list
+max_steps: 40
+---
+
+Steps describing the flow to verify...
+```
+
+| Field       | Required | Description                                        |
+| ----------- | -------- | -------------------------------------------------- |
+| `feature`   | Yes      | Human-readable feature name                        |
+| `entry`     | Yes      | Screen name the agent navigates to before starting |
+| `max_steps` | No       | Maximum number of agent steps                      |
+
+### `xqa analyse <video-path>`
+
+Analyses a session recording with Gemini. Requires `GOOGLE_GENERATIVE_AI_API_KEY`. Prints findings as JSON to stdout.
+
+```bash
+xqa analyse .xqa/output/2026-04-10/0001/recording.mp4
+```
+
+### `xqa review [findings-path]`
+
+Interactive terminal session for reviewing findings and marking false positives. Requires a TTY. Dismissals are persisted to a dismissals store and excluded from future runs.
+
+```bash
+xqa review .xqa/output/2026-04-10/0001/findings.json
+
+# re-open the last reviewed findings file
+xqa review
+```
+
+### `xqa completion <shell>`
+
+Outputs a shell completion script.
+
+```bash
+xqa completion zsh >> ~/.zshrc
+xqa completion bash >> ~/.bashrc
+```
+
+## Process Behaviour
+
+Only one `xqa` instance runs at a time (PID lock). A second invocation while a run is active will exit immediately with an error.
+
+- `Ctrl+C` once: graceful shutdown — the current agent step completes, findings are written, then the process exits
+- `Ctrl+C` twice: force exit
+
+## Development
+
+```bash
+pnpm dev          # watch build
+pnpm build        # production build
+pnpm build:link   # build + link `xqa` globally
+pnpm dev:link     # watch build + link
+pnpm test         # run Vitest test suite
+pnpm typecheck    # TypeScript type check
+pnpm lint         # ESLint + Prettier check
+pnpm lint:fix     # ESLint + Prettier auto-fix
+pnpm check        # lint + typecheck + test (affected only)
+pnpm check:fix    # lint:fix + typecheck + test (affected only)
+```
+
+## Architecture
+
+```
+src/
+  index.ts                # CLI entry — registers all commands
+  config-schema.ts        # Zod schema for all environment variables
+  commands/
+    explore-command.ts    # xqa explore
+    spec-command.ts       # xqa spec
+    analyse-command.ts    # xqa analyse
+    review-command.ts     # xqa review
+    completion-command.ts # xqa completion
+  prompt-builder.ts       # builds the explorer system prompt from config
+```
+
+The CLI is a thin shell over `@qa-agents/pipeline`. It parses env vars, builds a `PipelineConfig`, and calls `runPipeline()`.