@qaping/cli 0.1.5 → 0.3.0

package/docs/COMMANDS.md

@@ -0,0 +1,122 @@
+# qaping — CLI commands
+
+Everything the `qaping` binary does. Your agent runs most of these for you;
+`setup`, `builds` and `rounds` are the ones you will type yourself.
+
+```
+qaping setup [claude-code|cursor|codex] [--force]
+qaping remove [--client <c>]
+qaping publish-build <game.zip> --platform windows|macos
+qaping builds
+qaping builds rm <slug>
+qaping publish <built-dir>
+qaping wait <ping_id> [--timeout <seconds>]
+qaping results <ping_id> [--json]
+qaping rounds [--json] [--offline] [--file <path>]
+qaping rounds add <ping_id> [--platform windows|macos|ios] [--build <url>]
+                            [--minutes N] [--deadline-seconds N]
+                            [--game <slug>] [--checks a,b,c]
+                            [--note "<patch>"] [--json]
+qaping rounds rm <ping_id> [--json]
+qaping issues <game> [--json] [--status open|fixed|verified|closed]
+qaping whoami
+qaping version
+```
+
+## Getting in and out
+
+### `qaping setup [claude-code|cursor|codex] [--force]`
+
+Registers the qaping MCP server with your coding agent, installs the `qaping`
+skill and its rule, and signs you in (a browser window opens once). With no
+client name it detects what is installed. `--force` rewrites an existing
+entry.
+
+### `qaping remove [--client <c>]`
+
+Removes qaping's MCP entry, skill and rule from the client. It touches only
+qaping's own state — nothing else you have installed, and not your login.
+
+### `qaping whoami`
+
+Which account this machine is signed in as. Results are scoped to the account
+that filed the round, so check this before deciding a round is gone.
+
+### `qaping version`
+
+Prints the installed version.
+
+## Hosting a build
+
+### `qaping publish-build <game.zip> --platform windows|macos`
+
+Uploads a zipped native build and prints the `/b/<slug>` URL a round is filed
+against. You hold a small number of hosted builds at a time; the oldest is
+listed first by `qaping builds`.
+
+### `qaping builds` / `qaping builds rm <slug>`
+
+Lists the hosted builds you hold, or deletes one now to free its slot.
+
+### `qaping publish <built-dir>`
+
+Hosts a browser-playable game's built output and prints the public URL. Web
+rounds are filed with that URL and no platform.
+
+## Rounds
+
+### `qaping wait <ping_id> [--timeout <seconds>]`
+
+Waits on a filed round, renewing the lease that keeps it visible to new
+playtesters, and prints the results when they land. The agent normally runs
+this in a background task.
+
+### `qaping results <ping_id> [--json]`
+
+One passive fetch, no waiting. Exit code `0` means results are in, `2` means
+still pending, `1` anything else (expired, not yours, unreachable).
+
+### `qaping rounds`
+
+The parked rounds this repo is owed, read from `qa-open-rounds.json` at the
+repo root, each with its live status. `--offline` skips the status lookup;
+`--file` points at another ledger.
+
+### `qaping rounds add <ping_id> …`
+
+Records a round the agent chose to park — an overnight run, a slow native
+claim — so a later session collects it instead of filing a duplicate. Add
+`--build`, `--minutes`, `--deadline-seconds`, `--game`, `--checks` and
+`--note` so the record explains itself; `--game` is the QA plan's
+`game_slug`, so the session that collects the round knows which issue board
+it moved.
+
+### `qaping rounds rm <ping_id>`
+
+Forgets a parked round once it is collected or expired.
+
+## The issue board
+
+### `qaping issues <game> [--json]`
+
+Prints the game's issue board: every bug that outlived a round, with its
+status — open, fixed (you claim it is fixed), verified (a playtester
+confirmed it is gone), closed. `--status` prints one status only; `--json`
+prints the machine-readable rows.
+
+Read-only, on purpose. Your agent files, claims, closes and reopens issues
+through the `qaping_issues` MCP tool while it runs the loop; this is the
+window you read it through. Nothing on the board costs credits — only rounds
+do — and nothing turns *verified* except a playtester answering "Gone" on a
+round filed after the fix was claimed.
+
+## Files qaping leaves in your repo
+
+| file | what it is | commit it? |
+|---|---|---|
+| `QA-PLAN.md` | the checks this game must pass; the agent authors, you own | yes — see [the format](QA-PLAN-FORMAT.md) |
+| `qa-rounds.jsonl` | append-only history, one line per finished round | yes |
+| `qa-open-rounds.json` | rounds filed and not yet collected | no — gitignore it |
+
+The issue board is not a file: it lives on the service, one board per game,
+and `qaping issues <game>` reads it. The plan's `game_slug` is what names it.

package/docs/QA-PLAN-FORMAT.md

@@ -11,12 +11,19 @@ YAML at the very top of the file:
 ```yaml
 ---
 game: Solar Drift
+game_slug: solar-drift                          # the issue board's id — minted ONCE, never renamed
 build_command: ./scripts/package.sh --release   # the ONE command that produces a shippable build
 platforms: [windows]                            # windows | macos | ios | web
 input: XInput gamepad                           # optional; default keyboard+mouse
 ---
 ```
 
+`game_slug` is minted once from the game name — lowercase, every run of
+non-alphanumerics collapsed to a single `-`, no leading or trailing `-`, ≤64
+characters — and is then permanent, exactly like a check id: it names the
+game's issue board, and renaming it orphans every issue filed under the old
+one. Every playtest round is filed with it as `game`.
+
 `build_command` is recorded once at setup so every future run can build without
 asking. `platforms: [web]` means a browser-playable game — its "build" is a
 static directory, not a zip. `input` declares the hardware the
@@ -88,6 +95,26 @@ setup: "?save=campaign-mid"
    anything missing, corrupted, or visually wrong.
 ````
 
+## Bugs live on the issue board; checks live here
+
+A check is what the game must ALWAYS do — it belongs in this file, forever. A
+bug is what the game does wrong right now — it belongs on the game's issue
+board (`qaping issues <game_slug>`, moved by the agent through the
+`qaping_issues` tool), where it is numbered, carried across rounds, and
+retired when it is gone. Do not write bugs into `QA-PLAN.md`: a check written
+to describe one bug ("the shop does not close when you press B twice") ages
+into a puzzle the moment the bug is fixed.
+
+The board is what makes a fix provable. The agent may CLAIM a fix (with the
+exact build URL the next round will play); only a playtester answering
+"Gone" on a round filed after that claim turns the issue *verified*, and a
+"Still here" on a claimed fix regresses it. Because every round is filed with
+`game`, the board's open and claimed-fixed issues ride it as the playtester's
+checklist — no step budget spent, no bug forgotten between patches.
+
+A check and the bug that came from it stay linked through the issue's
+`check_id`: the same id this file gives the check.
+
 ## The round ledger — qa-rounds.jsonl
 
 Beside the plan, at the game repo root, sits `qa-rounds.jsonl`: one JSON line
@@ -96,6 +123,8 @@ appended per round, committed alongside the plan updates —
 ```json
 {"round_id": "…", "report_url": "…", "build": "<sha or hosted url>",
  "evidence_grade": "…", "checks": [{"id": "…", "outcome": "…"}],
+ "issues": {"game": "solar-drift", "verified": [3], "regressed": [5],
+  "new": [7], "still_open": [2]},
  "verdict": "…", "credits": 20, "follow_ups": ["…"]}
 ```
 
@@ -106,8 +135,30 @@ page (what the results tool returns), never a PR or issue link. There is no
 evidence-link field, deliberately: signed recording URLs expire in days.
 The ledger is the machine truth of what was asked and answered, per check,
 per round; the plan's `last_verified` and `state` are derived from it and
-stay the dev-readable contract. Open `follow_ups` are what the next filing
-must carry forward.
+stay the dev-readable contract. `issues` is what this round did to the issue
+board, by number (omitted when the round carried no `game`). `follow_ups` is
+NON-BUG follow-ups only — a check to add, a build affordance to write, a
+question to settle; bugs go on the board, where they are numbered and
+re-checked. Open `follow_ups` are what the next filing must carry forward.
+
+## Rounds still open — qa-open-rounds.json
+
+A playtest may run for many hours, so a round the agent cannot sit through is
+PARKED: filed with an explicit long deadline, then recorded in
+`qa-open-rounds.json` (same directory) so a LATER session collects it —
+
+```json
+{"rounds": [{"ping_id": "<uuid>", "filed_at": "<ISO>", "platform": "windows",
+  "build": "<the hosted or store URL>", "est_minutes": 10,
+  "deadline_seconds": 86400, "game": "solar-drift",
+  "checks": ["<check ids>"], "note": "<the patch this round covers>"}]}
+```
+
+`qaping rounds` lists it with each round's live status, `qaping rounds add`
+(with `--game` for the board this round carries) records one,
+`qaping rounds rm` drops it once collected. This file is the
+opposite of the ledger and never merges with it: mutable OPEN state, one entry
+per round still owed, emptied as rounds land. It is not history — gitignore it.
 
 ## Maintenance rules
 

package/docs/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64"><rect x="4" y="4" width="56" height="56" rx="14" fill="#FF7A45"/><path d="M20 33.5l8 8 16-17" fill="none" stroke="#fff" stroke-width="6.5" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaping/cli",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "homepage": "https://qaping.dev",
   "description": "qaping: automatic QA for your game. Your coding agent authors and maintains the QA plan, ships each patch's build to real human playtesters, and reports what broke.",
   "keywords": [
@@ -25,7 +25,7 @@
     "node": "^20.17.0 || ^22.13.0 || >=23.5.0"
   },
   "dependencies": {
-    "pingfusi": "^0.16.0"
+    "pingfusi": "^0.17.1"
   },
   "publishConfig": {
     "access": "public"

package/skill/SHIPPED-HASHES.json

@@ -0,0 +1,19 @@
+{
+  "note": "sha256 of every SKILL.md version this package has shipped (LF-normalized). setup refreshes an installed skill whose hash is listed here — it is ours — and preserves anything else as a local edit. APPEND-ONLY; regenerate with: node scripts/gen-skill-hashes.js [<skill-root>...]",
+  "skills": {
+    "qaping": [
+      "184aa97ba0d529eea36be3c6eb4a5f4c1db8e2a65a0230e03814276a18a92354",
+      "217ffcc582e068424eefbb69376825ac71433fa92f34e3546bd02d8521ef008c",
+      "2fe5cafeef48146d8c9cc263ae1aaef764720027d17c0af3ab879e6853cf4a26",
+      "38cdc3289db6a544bc0cc828f4981a3f4ed6b39036ce81eebbaf4cbe9c47a5d0",
+      "490ff02895fdc6a2eb3a0b671628a8d4eee3efd906782eb45d99eac40bf59846",
+      "5462b858f58d183a020a5b2fa214dd1da6856e71a238316641f13d70eb0f0df4",
+      "5d0751c023af0a1cf69f152ba587b10c34087c7d5299f2d4b0e782f1ad0d66b0",
+      "6d0a5a1b430a8a0fd1c7c06b726de657e7fe82ac37ce69c9446539065d2ce751",
+      "71e64cd2b58996236c7fd3375a324ca2ae7b3e4028f7b358a389c562464c8bf3",
+      "8d817af568154734cd893122ce2e40ef2cd20cb725abbf318f134318157e5b6c",
+      "966bd642f1ee052691c7974a186e9f8f50644bce0ea010b6f0b444931879dbad",
+      "b9d08318e69290759bf31e149d64207b9d186faac9ccd01bc1db3ffcff29506c"
+    ]
+  }
+}