opencode-qa

# opencode QA

QA the opencode coding agent itself. This skill maps each QA need to a tested
helper script and a deep reference. Every script ships a `--self-test` that
asserts its scenario against the live machine, so the scripts are both the QA
tools and their own regression checks.

Verified against opencode v1.15.13 (bun 1.3.12, macOS). Confirm the installed
version with `opencode --version`; the surface is stable but always sanity
check a flag with `opencode <cmd> --help`.

## Golden rules (read before running anything)

- READS of the live DB are safe and intended. Investigating sessions (Case D)
  only reads `~/.local/share/opencode/opencode.db`.
- Anything that SPAWNS opencode (serve, run, the TUI) must use an isolated XDG
  sandbox so QA never writes junk sessions into the real DB. The bundled
  scripts already do this; if you run opencode by hand for QA, set
  `XDG_DATA_HOME` / `XDG_CONFIG_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` to
  temp dirs first.
- Global text search over the `part` table is a multi-GB scan. Always scope it
  (`--session`, `--recent`, or `--since`). The text script refuses an
  unbounded scan on purpose.
- The opencode source repo (`packages/opencode`) tests itself with `bun test`
  and CANNOT run tests from the repo root. See `references/testing-harness.md`.

## Setup

Scripts live next to this file under `scripts/`. Invoke them from this skill
directory (or with their absolute path):

```bash
cd <this-skill-dir>                        # .agents/skills/opencode-qa
bash scripts/lib/common.sh --self-check    # confirm the harness + deps
```

`common.sh` provides the shared harness (DB path, SQL escaping, isolated XDG
sandbox, free port, server start/stop, and an EXIT-trap cleanup). It requires
`opencode`, `sqlite3`, `curl`, `jq`, and `tmux` on PATH.

## Router: pick your case

| You want to... | Case | Script | Reference |
|---|---|---|---|
| Run opencode non-interactively / check a CLI command | A | `opencode run --format json` (inline) | `references/cli-commands.md` |
| Find a session by its id | D | `scripts/db-session-by-id.sh <ses_id>` | `references/db-investigation.md` |
| Find sessions by title/name | D | `scripts/db-session-by-name.sh "<text>"` | `references/db-investigation.md` |
| Find sessions by message text | D | `scripts/db-session-by-text.sh --recent N "<text>"` | `references/db-investigation.md` |
| Export a whole session as JSON | D | `scripts/export-roundtrip.sh <ses_id>` | `references/db-investigation.md` |
| Check the HTTP server / an endpoint | B | `scripts/server-smoke.sh` | `references/server-api.md` |
| Prove a hook / action / event fired | B | `scripts/sse-hook-probe.sh` | `references/events-hooks.md` |
| Prove serve-topology wake runner-split (reproduced/fixed) | B | `scripts/serve-wake-split-probe.sh --expect reproduced\|fixed --evidence-dir DIR` (self-test: `--self-test`; fake LLM: `scripts/lib/fake-openai-server.mjs`) | `references/events-hooks.md` |
| Smoke-test the TUI | C | `scripts/tui-smoke.sh` | `references/tui-tmux.md` |
| Write/run a test in the opencode source | - | (bun test) | `references/testing-harness.md` |
| Drive opencode from a Bun/TS script | - | (SDK) | `references/sdk.md` |

## Case A: CLI / terminal works

The canonical scriptable, non-interactive entry is `opencode run`. JSON mode
emits one event per line so you can assert on it.

```bash
# stream structured events (types: text, tool_use, step_start, step_finish, reasoning, error)
opencode run "list files in src" --format json
# run a slash command
opencode run --command commit
# resume the last session
opencode run -c "continue"
# target an already-running server instead of booting one
opencode run "explain auth" --attach http://127.0.0.1:4096 -p "$OPENCODE_SERVER_PASSWORD"
```

Other QA-useful commands: `opencode db path`, `opencode debug paths`,
`opencode session list --format json`, `opencode models --verbose`. Full flag
detail in `references/cli-commands.md`.

## Case B: a specific hook, action, or event

opencode publishes lifecycle events over Server-Sent Events at `GET /event`.
Plugins observe the same events via the `event` hook, so seeing an event on the
wire proves a hook would fire.

```bash
# prove the SSE plumbing works (isolated server, asserts server.connected)
bash scripts/sse-hook-probe.sh --self-test

# watch a REAL server for a specific event while you trigger an action
bash scripts/sse-hook-probe.sh --attach http://127.0.0.1:4096 \
  --password "$OPENCODE_SERVER_PASSWORD" --directory "$PWD" \
  --event message.part.updated --timeout 30
```

Trigger an action over HTTP (fire-and-forget so the stream is not blocked):

```bash
curl -X POST -u opencode:$OPENCODE_SERVER_PASSWORD -H 'Content-Type: application/json' \
  -d '{"parts":[{"type":"text","text":"say hi"}]}' \
  "http://127.0.0.1:4096/session/<ses_id>/prompt_async?directory=$PWD"
```

A real prompt needs a configured provider, so run the watch-and-trigger pattern
against your real server, not the isolated sandbox. Event-type catalog, the 21
plugin hook points, and how to load a local plugin: `references/events-hooks.md`.
Server start, auth, and routes: `references/server-api.md`.

## Case C: the TUI

```bash
bash scripts/tui-smoke.sh --self-test
```

This launches the TUI under tmux in an isolated sandbox, confirms it renders
(`capture-pane`), confirms `send-keys` reaches the composer, tears the tmux
session down, and verifies the real DB session count is unchanged.

Honest verdict: tmux is fine for SMOKE (did it boot, render, accept a key) but
fragile for asserting conversation output (the TUI is a 60fps full-screen app).
For real behavior assertions use Case A (`opencode run`), Case B (server API +
SSE), or the TUI control HTTP API (`POST /tui/append-prompt`,
`POST /tui/submit-prompt`, `POST /tui/execute-command`). Details and the manual
tmux recipe: `references/tui-tmux.md`.

## Case D: investigate sessions in the DB

Read-only against the live SQLite DB. The `session` table i