# bugzar-server

A small Node.js server for storing [Bugzar](https://github.com/classtinginc/bugzar) QA session
reports, organized by project, with a dashboard for triage (status tracking, comments) and an MCP
server so an AI agent can query and update reports directly.

Bugzar's SDK exports each captured session as a **self-contained, offline-playable HTML file** — the
whole viewer is inlined, so this server doesn't need to render reports itself. It just needs to store
that file, track metadata (project, status, comments) about it, and serve it back at a stable URL.

## Quick start

```bash
pnpm install
cp .env.example .env   # set DASHBOARD_PASSWORD and SESSION_SECRET to real values
pnpm dev                # http://localhost:3000
```

For production: `pnpm build && pnpm start`.

## Concepts

- **Project** — a namespace with its own API key. Create one from the dashboard (`/`) after logging
  in with `DASHBOARD_PASSWORD`; the API key is shown once at creation time.
- **Report** — one ingested Bugzar HTML export, belonging to a project. Has a 3-state workflow:
  `open` → `in_progress` → `resolved`.
- **Share link** — every report is reachable at `{PUBLIC_BASE_URL}/r/:reportId`, unauthenticated
  (the id is the access control, same trust model as the offline HTML file itself). Opening it serves
  the exact stored HTML, which is already the full interactive replay/console/network viewer.

## HTTP API

| Method & Path | Auth | Purpose |
|---|---|---|
| `POST /api/projects` | dashboard session | create a project → `{ id, name, slug, apiKey }` (key shown once) |
| `GET /api/projects` | dashboard session | list projects |
| `POST /api/projects/:projectId/reports` | `Authorization: Bearer <api_key>` | ingest a report — `multipart/form-data` with a `file` field → `{ id, url }` |
| `GET /api/projects/:projectId/reports` | session or matching key | list reports, `?status=`, `?limit=`, `?cursor=` |
| `GET /api/reports/:reportId` | session or matching key | report + comments |
| `PATCH /api/reports/:reportId/status` | session or matching key | `{ status }` |
| `POST /api/reports/:reportId/comments` | session or matching key | `{ body, author? }` |
| `GET /r/:reportId` | none (public) | the shareable link — raw report HTML |
| `GET /reports/:reportId/:asset.json` | none (public) | one of the 10 report asset slots (`meta`, `events`, `console`, `network`, `storage`, `resources`, `state`, `vitals`, `system`, `design`) — matches `@bugzar/viewer`'s remote-fetch contract |

## SDK integration

See [docs/sdk-integration.md](docs/sdk-integration.md) for wiring `@bugzar/sdk`'s `onExport` callback
to this server.

## MCP server

Mounted at `/mcp` (Streamable HTTP transport), authenticated the same way as ingestion —
`Authorization: Bearer <project_api_key>`. All calls are scoped to that project only.

Tools:
- `list_reports`, `get_report_summary`, `get_repro_steps`, `get_console_errors`,
  `get_failed_requests`, `get_network_request`, `get_system_info`, `get_ai_context` — read/query
- `update_report_status`, `add_report_comment` — AI can directly triage a report (mark it resolved,
  leave an investigation note)

Add it to an MCP-capable client pointed at `http://<host>/mcp` with the `Authorization` header set to
`Bearer <project_api_key>` (check your client's docs for how it configures custom headers on a remote
HTTP MCP server — e.g. Claude Code's `claude mcp add --transport http`).

## Development

```bash
pnpm test          # vitest — vendor extractor, ingestion summary, HTTP routes, MCP tools
pnpm build         # tsc -> dist/
pnpm smoke         # after building: spawns the real server, ingests a real fixture report,
                   # and round-trips a real MCP client against it end-to-end
pnpm check         # biome lint/format
```

## Project layout

```
src/
├── index.ts / app.ts     # entrypoint / Hono app assembly
├── config.ts             # env var loading
├── db/                   # better-sqlite3 client, migrations, hand-written repos
├── vendor/                # copied from @bugzar/shared (private/unpublished) — report HTML extractor + types
├── ingest/                # storage (filesystem), ingestion pipeline, summary derivation
├── auth/                  # API key + dashboard session
├── routes/                # REST API
├── mcp/                   # MCP tool definitions + Streamable HTTP route
└── dashboard/              # server-rendered Hono JSX pages
```