@bugbug-io/cli 13.39.1

package/AGENTS.md

@@ -0,0 +1,103 @@
+# CLI Package Guide
+
+## Scope
+
+These instructions apply to `public-tools/packages/cli/`, the `@bugbug-io/cli` package. The root `public-tools/AGENTS.md` still applies; this file only adds CLI-specific rules. User-facing usage lives in `README.md`; the human developer guide lives in `DEVELOPMENT.md`.
+
+## Project Structure
+
+```
+packages/cli/
+├── bin/bugbug.mjs        # Published binary shim to built dist entrypoint
+├── src/
+│   ├── index.ts          # CLI entry: Commander setup, global options, command registration
+│   ├── instrument.ts     # Sentry bootstrap (imported first)
+│   ├── app/              # Ink TUI: Navigator, router, views, components, contexts, hooks
+│   ├── features/         # Feature commands, services, actions, formatters, types
+│   │   └── tui/          # Shared terminal UI primitives (shortcuts, layouts)
+│   ├── testUtils/        # Fake factories and test helpers
+│   └── utils/            # Auth, config, output, reporters, SDK wiring, startup routing
+├── docs/                 # CLI-facing docs/prompts
+├── scripts/              # Package-local validation helpers
+├── tsconfig.json
+├── tsup.config.ts
+└── vitest.config.ts
+```
+
+Command domains under `src/features/`: `auth`, `init`, `install`, `profiles`,
+`project`, `shorthands`, `suiteRuns`, `suites`, `testRuns`, `tests`, `tui`.
+
+## Architecture
+
+- `src/index.ts` owns global options, startup routing, and command registration.
+- `src/features/{feature}/{feature}.command.ts` registers Commander commands.
+- `src/features/{feature}/{feature}.service.ts` contains API orchestration through the SDK.
+- `src/features/{feature}/{feature}.tui.tsx` and `src/features/{feature}/*.actions.tsx` contain interactive terminal flows.
+- `src/features/{feature}/{feature}.formatters.tsx` contains plain/JSON/terminal presentation helpers.
+- `src/app/` owns the interactive no-args navigator (`Navigator.tsx`, `router.tsx`, `views/`); `src/features/tui/` owns shared terminal UI primitives.
+- `src/utils/startup.ts` detects the startup mode (navigator / help / commander / shorthand).
+- `src/utils/sdk.ts` is the SDK construction boundary. Do not instantiate SDK clients directly in feature modules.
+
+## Coding Rules
+
+- This package is TypeScript, ESM, Node `>=24`.
+- Use the `~/` alias for package-local imports. It resolves to this package's `src/` directory.
+- Do not end import specifiers or `vi.mock(...)` module strings with `.js`; keep local and alias imports extensionless.
+- Prefer named exports and small typed helpers.
+- Keep command parsing in command files, business/API behavior in services, and output rendering in formatters or TUI components.
+- Preserve existing global modes: `--json`, `--ci`, `--token`, and `--verbose`.
+- CLI output must remain usable in non-interactive CI. Do not force Ink rendering where plain output is expected.
+
+## Adding Commands
+
+- Add new features under `src/features/{feature}/`.
+- Register top-level command groups from `index.ts`.
+- For commands that start runs, respect reporter options, wait/no-wait behavior, timeout handling, and exit codes.
+- For list/get commands, support structured output through the existing output/render helpers.
+- Update `README.md` or docs when public command behavior changes.
+
+## Adding new global config params
+
+While adding a new global params, remember to handle it in many places.
+It could be always:
+
+- new `BUGBUG_` prefixed environment variable
+- new command-line flag
+- new config file field
+
+## Testing
+
+- Use Vitest from this package or the root workspace scripts.
+- Put tests beside the code or under the feature's `__tests__/` directory.
+- Test startup routing under `src/utils/__tests__/` when changing no-args, shorthand, help, CI, or JSON behavior.
+- Test names must start with `should ...` or `should not ...`; fakers use the `createFake*` prefix and live in `src/testUtils/`.
+- Test command registration and service behavior separately where possible.
+- Mock SDK/network boundaries. Normal CLI tests should not call live BugBug APIs.
+- For Ink/TUI components, use the existing component tests as the local pattern.
+
+## Scripts
+
+Run package-specific commands from `public-tools/`:
+
+- Build CLI: `npm run build:cli`
+- Test CLI: `npm run test:cli`
+- Start CLI from TypeScript: `npm run start:cli`
+
+Or from `public-tools/packages/cli/`:
+
+- Build: `npm run build`
+- Test: `npm run test`
+- Test (CI): `npm run test:ci`
+- Coverage: `npm run coverage`
+- Type check: `npm run typecheck`
+- Lint (oxfmt + oxlint): `npm run lint`
+- Lint auto-fix: `npm run lint:fix`
+- Lint (CI, no cache, `--max-warnings=0`): `npm run lint:ci`
+- Format check only: `npm run format:check`
+- Oxlint check only: `npm run oxlint:check`
+- Start built CLI: `npm start`
+
+## Security and Config
+
+- Load user project `.env` through the existing startup path; do not add ad hoc dotenv loading in feature files.
+- Pass API credentials through existing global state and SDK helpers.

package/README.md

@@ -0,0 +1,229 @@
+<div align="center">
+
+![BugBug Logo](https://bugbug.io/favicon-96x96.png)
+
+# BugBug CLI
+
+An enhanced command-line interface for [BugBug](https://bugbug.io) that provides better developer experience and extended capabilities for browser test automation.
+
+</div>
+
+## Features
+
+- **Rich Terminal UI**: Interactive navigator and readable error messages built with Ink
+- **Flexible Token Management**: Multiple ways to configure your API token (CLI flags, `bugbug.yaml`, environment variables, and `bugbug login`)
+- **Project Export & Import**: Export your entire project (tests, suites, profiles) to a ZIP archive and import it back
+- **Test & Suite Execution**: Run individual tests or entire test suites in the cloud, waiting for results by default
+- **Reporters**: Inline or JUnit XML reports for CI pipelines
+- **Verbose Logging**: Optional detailed HTTP request logging for debugging
+
+## Installation
+
+```bash
+npm install -g @bugbug-io/cli
+bugbug --help
+```
+
+Or run it without installing:
+
+```bash
+npx @bugbug-io/cli --help
+```
+
+## Requirements
+
+- Node.js v24 or higher
+- BugBug account or API token
+
+## Quick Start
+
+1. **Authenticate** (opens the browser and stores a user token in the global config):
+
+   ```bash
+   bugbug login
+   ```
+
+   Or pass a token explicitly with `--token`, `BUGBUG_API_TOKEN`, or `bugbug.yaml` (see [Authentication](#authentication)).
+
+2. **Export your project**:
+
+   ```bash
+   bugbug project export
+   ```
+
+3. **Run a test** (waits for completion by default):
+   ```bash
+   bugbug tests run <testId>
+   ```
+
+## Authentication
+
+The CLI resolves configuration from several layered sources. The first match wins:
+
+1. **Command line flag** (highest priority):
+
+   ```bash
+   bugbug project export --token YOUR_TOKEN
+   ```
+
+2. **Environment variable**:
+
+   ```bash
+   export BUGBUG_API_TOKEN=YOUR_TOKEN
+   ```
+
+3. **Local project config file** (`bugbug.yaml` in the current directory or an ancestor):
+
+   ```yaml
+   # bugbug.yaml
+   token: YOUR_TOKEN
+   projectId: YOUR_PROJECT_ID
+   apiUrl: https://app.bugbug.io/api/v2
+   ```
+
+4. **Environment file** (`.env`, or `.env.${NODE_ENV}`, walking up the directory tree):
+
+   ```bash
+   BUGBUG_API_TOKEN=YOUR_TOKEN
+   ```
+
+5. **Global config** (`~/.bugbug/config.yaml`), populated by `bugbug login`. The token is
+   looked up by `projectId` (falling back to the stored user token).
+
+Running `bugbug login` starts a local loopback callback, opens BugBug in the
+browser, completes the OAuth authorization-code flow, and stores the issued user
+token in the global config. `bugbug logout` clears it. Run `bugbug init` in a
+project directory to create a `bugbug.yaml` that links current directory/repository with selected BugBug project.
+
+## Environment Variables
+
+| Variable            | Description                                                           |
+| ------------------- | --------------------------------------------------------------------- |
+| `BUGBUG_API_TOKEN`  | API token used to authenticate requests                               |
+| `BUGBUG_PROJECT_ID` | Project ID (required for organization tokens in non-interactive mode) |
+| `BUGBUG_LOG_LEVEL`  | Log level; set to `debug` to enable verbose logging                   |
+| `BUGBUG_TELEMETRY`  | Set to `false` to disable telemetry                                   |
+| `DO_NOT_TRACK`      | Standard opt-out; set to `1`/`true` to disable telemetry              |
+| `CI`                | When `true`, forces plain (non-interactive) output                    |
+
+## Commands
+
+Run `bugbug` with no arguments for the interactive navigator, or `bugbug <command> --help`
+for details on any command.
+
+### Auth
+
+```bash
+bugbug login          # Authenticate and store a user token in the global config
+bugbug logout         # Clear the stored user token and current project
+```
+
+### Project
+
+```bash
+bugbug init                       # Create bugbug.yaml pinning this directory to a project
+bugbug project export             # Export project as a ZIP (bugbug-project-export-<timestamp>.zip)
+bugbug project export -o out.zip  # Export to a specific file
+bugbug project import out.zip     # Import a project from a ZIP archive
+```
+
+### Tests
+
+```bash
+bugbug tests list                 # List tests
+bugbug tests list -s "login"      # Filter tests by name
+bugbug tests show <testId>         # Show test details
+bugbug tests run <testId>          # Run a test (waits for completion by default)
+bugbug tests run <testId> --profile "Production"
+bugbug tests run <testId> --variable FOO=bar --variable BAZ=qux
+bugbug tests run <testId> --no-wait        # Queue the run and exit immediately
+bugbug tests run <testId> --reporter junit --output-path report.xml
+bugbug tests export <testId> --format yaml
+bugbug tests export <testId> --format zip -o test.zip
+bugbug tests import test.yaml             # Import a test from YAML or ZIP
+```
+
+### Test Runs
+
+```bash
+bugbug testruns show <runId>               # Show the result of a test run
+bugbug testruns logs <runId>               # Get logs for a test run
+bugbug testruns stop <runId>               # Stop a running test run
+bugbug testruns report <runId> -o out.xml  # Get the JUnit XML report
+```
+
+### Suites
+
+```bash
+bugbug suites list                # List suites
+bugbug suites list -s "checkout"  # Filter suites by name
+bugbug suites show <suiteId>       # Show suite details
+bugbug suites run <suiteId>        # Run a suite (waits for completion by default)
+bugbug suites run <suiteId> --profile "Production" --variable FOO=bar
+bugbug suites run <suiteId> --no-wait
+```
+
+### Suite Runs
+
+```bash
+bugbug suiteruns show <runId>              # Show the result of a suite run
+bugbug suiteruns stop <runId>              # Stop a running suite run
+bugbug suiteruns report <runId> -o out.xml # Get the JUnit XML report
+```
+
+### Profiles
+
+```bash
+bugbug profiles list              # List run profiles
+```
+
+### AI Clients (plugin: MCP + Skills)
+
+```bash
+bugbug plugin --agent=cursor      # Install skills + MCP into Cursor
+bugbug plugin --agent=codex --dry-run  # Show what would be installed, writing nothing
+```
+
+Supported `--agent` values: `cursor`, `claude`, `vscode`, `codex`, `windsurf`,
+`copilot`.
+Windsurf gets
+an MCP server config plus the BugBug skills written into the agent's skills
+directory.
+
+The token is resolved from your existing CLI auth (`bugbug login`, `--token`, or
+`BUGBUG_API_TOKEN`).
+
+### Shorthands
+
+Verb-first shorthands map onto the namespaced commands above:
+
+```bash
+bugbug run test <testId>
+bugbug run suite <suiteId>
+bugbug list test
+bugbug list suite
+bugbug list profile
+bugbug stop test <runId>
+bugbug stop suite <runId>
+bugbug report test <runId>
+bugbug report suite <runId>
+bugbug logs test <runId>
+bugbug export project
+bugbug export test <testId>
+bugbug import project export.zip
+bugbug import test test.yaml
+```
+
+## Global Options
+
+- `-t, --token <token>`: API token for BugBug (overrides config)
+- `-p, --project-id <projectId>`: Project ID (required only for organization tokens in non-interactive mode)
+- `-v, --verbose`: Enable verbose logging including HTTP requests
+- `--ci`: CI-friendly output (plain logs, no interactive UI, exit 1 on failure)
+- `--json`: Emit JSON output (implies non-interactive)
+- `--disable-telemetry`: Disable telemetry
+- `-h, --help`: Show help information
+
+## License
+
+MIT

package/bin/bugbug.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const entrypoint = new URL(`../dist/index.${'js'}`, import.meta.url);
+import(entrypoint.href);