@amplitude/wizard 1.0.0-beta.1 → 1.0.0-beta.5

package/README.md

@@ -1,119 +1,216 @@
 # Amplitude Wizard
 
-An interactive CLI that guides developers through instrumenting their app with
-Amplitude analytics. It detects your framework, authenticates with your
-Amplitude account, runs a Claude-powered agent to set up the SDK and events, and
-walks you through your first chart and dashboard.
+Set up Amplitude analytics in your app — from zero to first chart — with one
+command.
 
-## How it works
+```bash
+npx @amplitude/wizard
+```
 
-The wizard keeps a persistent prompt open throughout the session — like Claude
-Code — so slash commands can be run at any time to switch org, switch project,
-re-authenticate, or trigger actions like opening a chart or interacting with the
-taxonomy agent.
+The wizard authenticates you, detects your framework, runs an AI agent to
+instrument the SDK and events, verifies data is flowing, and walks you through
+your first chart and dashboard. All from the terminal.
 
-On first run, the wizard:
+Requires Node.js >= 18.17.0.
 
-1. Checks for existing Amplitude credentials (`~/.ampli.json`)
-2. If not authenticated, walks through sign up or sign in (SUSI), org and
-   project selection
-3. Evaluates activation status — whether events are being ingested and the SDK
-   is configured
-4. If the project has no data yet, detects your framework and runs the agent to
-   instrument your app
-5. If the project already has data, offers options to explore your analytics or
-   set up a new project
-6. After instrumentation, guides you through the taxonomy agent, first chart,
-   and first dashboard
+## Supported frameworks
 
-See [`docs/flows.md`](./docs/flows.md) for detailed flow diagrams.
+| Web | Python | Mobile | Game Engines | Other |
+|-----|--------|--------|--------------|-------|
+| Next.js | Django | Swift (iOS) | Unity | Go |
+| Vue | Flask | React Native | Unreal | Java |
+| React Router | FastAPI | Android | | |
+| JavaScript (web) | Python (generic) | Flutter | | |
+| JavaScript (Node.js) | | | | |
 
-## Supported frameworks
+Unrecognized frameworks fall back to a generic integration.
 
-**Web / JavaScript:**
-Next.js, Vue, React Router, JavaScript (web), JavaScript (Node.js)
+## How it works
 
-**Python:**
-Django, Flask, FastAPI, Python (generic)
+```
+npx @amplitude/wizard
+
+  ✓ Welcome  ✓ Auth  ● Setup  ○ Verify  ○ Done
+  ─────────────────────────────────────────────
 
-**Mobile:**
-Swift (iOS), React Native, Android, Flutter
+  Detecting framework... Found Next.js 15
 
-**Game engines:**
-Unity, Unreal
+  The agent is setting up Amplitude in your project.
+  Current file: src/app/layout.tsx
+  Tasks: 3/5 complete · 42s elapsed
 
-**Other:**
-Go, Java
+  ❯ _
+
+  [/] Commands  [Tab] Ask a question
+```
 
-A generic fallback handles unrecognized frameworks.
+1. **Sign in** — authenticates with your Amplitude account (or creates one)
+2. **Detect** — identifies your framework and project structure
+3. **Instrument** — proposes an event plan for your review, then writes the code
+4. **Verify** — confirms events are flowing into Amplitude
+5. **Explore** — walks you through your first chart, dashboard, and taxonomy
 
-## Usage
+Type `/help` at any time to see available commands.
+
+## Running modes
+
+**Interactive** (default) — rich terminal UI with progress, slash commands, and
+inline guidance:
 
 ```bash
 npx @amplitude/wizard
 ```
 
-### CI mode
+**CI** — no prompts, no colors, for pipelines:
 
 ```bash
-npx @amplitude/wizard --ci --org <org> --project <project> --api-key <key> --install-dir <dir>
+npx @amplitude/wizard --ci --api-key <key> --install-dir .
 ```
 
-### Slash commands
-
-Available at any time during the wizard session:
+**Agent** — streams NDJSON for programmatic consumption:
 
-| Command      | Description                                                       |
-| ------------ | ----------------------------------------------------------------- |
-| `/region`    | Switch the data-center region (US or EU) — re-triggers data setup |
-| `/org`       | Switch the active org                                             |
-| `/project`   | Switch the active project                                         |
-| `/login`     | Re-authenticate                                                   |
-| `/logout`    | Clear credentials                                                 |
-| `/whoami`    | Show current user, org, and project                               |
-| `/overview`  | Open the project overview in the browser                          |
-| `/chart`     | Set up a new chart                                                |
-| `/dashboard` | Create a new dashboard                                            |
-| `/taxonomy`  | Interact with the taxonomy agent                                  |
-| `/slack`     | Connect your Amplitude project to Slack                           |
-| `/help`      | List available slash commands                                     |
+```bash
+npx @amplitude/wizard --agent --install-dir . --api-key <key>
+```
 
-## Development
+## Commands
+
+Available at any point during the wizard:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | List available commands |
+| `/whoami` | Show current user, org, project, and region |
+| `/org` | Switch the active org |
+| `/project` | Switch the active project |
+| `/region` | Switch data-center region (US / EU) |
+| `/login` | Re-authenticate |
+| `/logout` | Clear credentials |
+| `/chart` | Set up a new chart |
+| `/dashboard` | Create a new dashboard |
+| `/taxonomy` | Interact with the taxonomy agent |
+| `/overview` | Open the project overview in the browser |
+| `/slack` | Connect your Amplitude project to Slack |
+| `/feedback` | Send product feedback |
+
+## Session and credentials
+
+The wizard remembers your login, org, project, and region across runs. Expired
+sessions refresh silently — you won't be asked to re-authenticate unless
+necessary. If the wizard is interrupted, the next launch in the same directory
+picks up where you left off.
+
+Credentials are stored in `~/.ampli.json` with restricted permissions. Project
+settings live in `.ampli.json` in your project directory (safe to commit for
+team sharing). API keys use your OS keychain when available, otherwise
+`.env.local` (gitignored).
+
+## CLI reference
+
+<details>
+<summary>Flags and exit codes</summary>
+
+### Global options
+
+| Flag | Env var | Description |
+|------|---------|-------------|
+| `--debug` | `AMPLITUDE_WIZARD_DEBUG` | Enable verbose logging |
+| `--verbose` | `AMPLITUDE_WIZARD_VERBOSE` | Print diagnostic info to the log |
+| `--signup` | `AMPLITUDE_WIZARD_SIGNUP` | Create a new Amplitude account during setup |
+| `--local-mcp` | `AMPLITUDE_WIZARD_LOCAL_MCP` | Use local MCP server at `http://localhost:8787/mcp` |
+| `--ci` | `AMPLITUDE_WIZARD_CI` | Non-interactive execution |
+| `--api-key <key>` | `AMPLITUDE_WIZARD_API_KEY` | Amplitude API key (skips OAuth) |
+| `--project-id <id>` | `AMPLITUDE_WIZARD_PROJECT_ID` | Amplitude project ID |
+
+### Wizard options
+
+| Flag | Env var | Description |
+|------|---------|-------------|
+| `--install-dir <dir>` | `AMPLITUDE_WIZARD_INSTALL_DIR` | Directory to install in (required for CI/agent) |
+| `--agent` | `AMPLITUDE_WIZARD_AGENT` | Structured JSON output mode |
+| `--yes` / `-y` | — | Skip all prompts, same as `--ci` |
+| `--integration <name>` | — | Force a specific integration |
+| `--menu` | `AMPLITUDE_WIZARD_MENU` | Show framework selection menu |
+| `--force-install` | `AMPLITUDE_WIZARD_FORCE_INSTALL` | Install packages even if peer checks fail |
+| `--benchmark` | `AMPLITUDE_WIZARD_BENCHMARK` | Per-phase token tracking |
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Authentication required |
+| 4 | Network error |
+| 10 | Agent failed |
+| 130 | User cancelled |
+
+</details>
+
+---
+
+## For developers
+
+### Setup
 
 ```bash
 pnpm install
 pnpm build
-pnpm try
+pnpm try          # run the wizard from source (no build needed)
+```
+
+### Project structure
+
+| Path | Role |
+|------|------|
+| `bin.ts` | CLI entry point — yargs commands, flags, mode selection |
+| `src/run.ts` | Main wizard orchestration |
+| `src/ui/tui/` | Terminal UI — [Ink](https://github.com/vadimdemedes/ink) (React for CLIs) + nanostores |
+| `src/ui/agent-ui.ts` | Agent mode — NDJSON streaming, no TUI |
+| `src/lib/` | Core business logic — session, agent runner, framework configs |
+| `src/frameworks/` | Per-framework integration configs (Next.js, Django, Swift, etc.) |
+| `src/steps/` | Post-agent steps — MCP install, env upload, formatting |
+| `skills/` | Bundled markdown instructions the AI agent follows at runtime |
+
+See [CLAUDE.md](./CLAUDE.md) for full architecture documentation.
+
+### Testing
+
+```bash
+pnpm test             # unit tests (vitest)
+pnpm test:watch       # watch mode
+pnpm test:bdd         # BDD / Cucumber tests
+pnpm test:e2e         # end-to-end tests
+pnpm test:proxy       # LLM proxy health check
+pnpm lint             # prettier + eslint
+pnpm fix              # auto-fix lint issues
 ```
 
 ### Local LLM proxy
 
-The wizard routes Claude API calls through a Langley proxy instead of hitting
-Anthropic directly. For local development you need to run it alongside the wizard.
+The wizard routes API calls through a Langley proxy. For local development, run
+it alongside the wizard.
 
-**Prerequisites:** `aws-sso` with the `us-prod-dev` profile, and the
-`amplitude/javascript` repo checked out as a sibling directory (`../javascript`).
+**Prerequisites:** `aws-sso` with the `us-prod-dev` profile, and
+`amplitude/javascript` checked out as a sibling directory (`../javascript`).
 Override with `JS_REPO=/path/to/javascript`.
 
 ```bash
-# Terminal 1 — start the proxy
+# Terminal 1 — proxy
 pnpm proxy
 
-# Terminal 2 — run the wizard with dev bypass token
+# Terminal 2 — wizard
 WIZARD_PROXY_DEV_TOKEN=dev-token pnpm try
 ```
 
-Or use `pnpm dev` to start both in one terminal (builds first, then runs
-`build:watch` and the proxy in parallel).
-
-Override the javascript repo location: `JS_REPO=/path/to/javascript pnpm proxy`
-
-Validate the proxy is working: `pnpm test:proxy`
+Or `pnpm dev` to run both in one terminal.
 
-### Render flow diagrams
-
-```bash
-pnpm flows
-```
+### Documentation
 
-Renders all diagrams from `docs/flows.md` to PNGs in `docs/diagrams/`.
+| Doc | What it covers |
+|-----|---------------|
+| [Flow diagrams](./docs/flows.md) | Source of truth for UX flows |
+| [Architecture](./docs/architecture.md) | System design |
+| [Dual-mode architecture](./docs/dual-mode-architecture.md) | TUI, agent, and CI mode |
+| [Engineering patterns](./docs/engineering-patterns.md) | Async safety, retry, error classification |