@qaping/cli 0.1.0

package/bin/qaping

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// qaping — automatic QA for game developers, as a thin brand wrapper over the
+// pingfusi kit (a real dependency; same accounts, credits, and service under
+// the hood). Every command resolves the installed kit and drives it with the
+// qaping wrapper options — MCP mount /api/mcp/qaping, MCP server key "qaping",
+// the qaping skill + always-loaded rule — so the customer only ever sees
+// qaping, and the kit's own pingfusi instruction surfaces are neither
+// installed nor swept (the vendored installer's --skip-instruction-surfaces
+// contract).
+//
+//   qaping setup [claude-code|cursor|codex] [--force]   one-command onboarding
+//   qaping remove|uninstall [--client <c>]              sweep ONLY qaping's state
+//   qaping publish-build <game.zip> --platform windows|macos
+//   qaping wait <ping_id> [--timeout <seconds>]
+//   qaping whoami | version | help
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+const { spawnSync } = require("child_process");
+
+const QPKG = path.resolve(__dirname, "..");
+
+// The kit is a normal npm dependency when qaping is installed, and a workspace
+// sibling in the monorepo checkout (where node_modules may not be linked yet)
+// — resolve the package, never a hardcoded install path.
+function resolveKitDir() {
+  try {
+    return path.dirname(require.resolve("pingfusi/package.json", { paths: [QPKG] }));
+  } catch {
+    const sibling = path.join(QPKG, "..", "kit");
+    try {
+      if (require(path.join(sibling, "package.json")).name === "pingfusi") return sibling;
+    } catch { /* fall through */ }
+    throw new Error("cannot resolve the pingfusi kit (a dependency of qaping) — reinstall: npm i -g qaping");
+  }
+}
+
+// The always-loaded rule (the qaping counterpart of the installer's RULE_BODY):
+// short, WHEN to reach for qaping; the skill owns the full loop. agent-setup
+// writes it to ~/.claude/rules/qaping.md and ~/.cursor/rules/qaping.mdc.
+const RULE_BODY = `This machine has qaping: automatic QA for games — real human playtesters play the developer's builds on their own hardware and report back, and the coding agent runs the whole loop.
+Whenever the user asks to set up QA for a game, run QA on a patch, check whether a change broke anything, or playtest a game or build, load the qaping skill and follow it — it owns authoring/maintaining QA-PLAN.md in the game repo and the per-patch run.
+Builds ship with \`qaping publish-build <game.zip> --platform windows|macos\`; the printed /b/<slug> URL is what a round is filed against (store-delivered games file with their Steam/TestFlight/App Store URL instead).
+The MCP tools are qaping_playtest (file a round with real human playtesters), qaping_results (fetch a finished round, free) and qaping_wait (continue a pending round — whenever a filing or wait returns pending, call qaping_wait again immediately; never report pending as the answer).
+Playtests are duration-billed at 2 credits per minute of play per playtester — state the estimated cost before filing. Windows rounds return a recording + questionnaire and no transcript; never promise one.
+`;
+
+// The wrapper object harness/setup.js's opts.wrapper API takes; also the one
+// source for the vendored installer's brand flags (spawned per command below).
+function qapingWrapper() {
+  return {
+    brand: "qaping",
+    // npm registry name ≠ bin name: the similarity rule blocks bare "qaping"
+    // (petition open, QAPING_PLAN §8), so the global install pulls @qaping/cli.
+    installPackage: "@qaping/cli",
+    appUrl: process.env.QAPING_APP_URL || undefined,
+    mcpPath: "/api/mcp/qaping",
+    serverKey: "qaping",
+    skipInstructionSurfaces: true,
+    skillRoot: path.join(QPKG, "skill"),
+    ruleAsset: { fileBaseName: "qaping", body: RULE_BODY },
+  };
+}
+
+function vendorFlags() {
+  const w = qapingWrapper();
+  return [
+    ...(w.appUrl ? ["--app-url", w.appUrl] : []),
+    "--mcp-path", w.mcpPath,
+    "--server-key", w.serverKey,
+    "--skip-instruction-surfaces",
+  ];
+}
+
+// One vendored-installer invocation per command, brand flags AFTER the
+// command/user args (the installer parses flags positionally-agnostic, but
+// `wait` takes the first non-flag arg as the ping id — user args stay first).
+function spawnVendor(args) {
+  const vendor = path.join(resolveKitDir(), "vendor", "pingfusi-review.mjs");
+  const r = spawnSync(process.execPath, [vendor, ...args, ...vendorFlags()], { stdio: "inherit" });
+  return r.status == null ? 1 : r.status;
+}
+
+// Running from the monorepo checkout (not an npm install): the repo root's
+// .git two levels up, and this file not under any node_modules. The plain
+// "..git two up" test alone would also match node_modules/qaping inside a
+// user's git project — that is an install, not a checkout.
+function isSourceCheckout() {
+  return !/node_modules/.test(QPKG) && fs.existsSync(path.join(QPKG, "..", "..", ".git"));
+}
+
+// Same io shape harness/setup.js's defaultIO builds (it isn't exported; the
+// kit-only steps a wrapper brand skips mean this needs no probe machinery
+// beyond the contract). npm/which route through the kit's proc.js — it owns
+// the Windows npm.cmd/where split.
+function defaultIO(kitDir) {
+  const { spawnNpmSync, whichSync } = require(path.join(kitDir, "harness", "proc.js"));
+  return {
+    isTTY: !!process.stdin.isTTY,
+    log: (...a) => console.log(...a),
+    run: (cmd, args) => (cmd === "npm"
+      ? spawnNpmSync(args, { stdio: "inherit" })
+      : spawnSync(cmd, args, { stdio: "inherit" })),
+    probe: (cmd, args) => {
+      try {
+        const r = spawnSync(cmd, args, { stdio: "pipe", timeout: 10_000 });
+        return !r.error && (r.status === 0 || !!((r.stdout && r.stdout.length) || (r.stderr && r.stderr.length)));
+      } catch { return false; }
+    },
+    which: (cmd) => whichSync(cmd),
+    ask: (q) =>
+      new Promise((res) => {
+        if (!process.stdin.isTTY) return res("");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(q, (a) => { rl.close(); res(a.trim().toLowerCase()); });
+      }),
+  };
+}
+
+const VALID_CLIENTS = ["claude-desktop", "claude-code", "cursor", "codex"];
+
+async function cmdSetup(argv) {
+  const kitDir = resolveKitDir();
+  const { setup } = require(path.join(kitDir, "harness", "setup.js"));
+  const { resolveToken } = require(path.join(kitDir, "harness", "review-qa.js"));
+  // accepts both the positional form (`setup cursor`) and `setup --client cursor`
+  const args = argv.filter((a) => a !== "--force");
+  const client = ((args[1] === "--client" ? args[2] : args[1]) || "").toLowerCase();
+  const r = await setup(defaultIO(kitDir), {
+    home: os.homedir(),
+    sourceCheckout: isSourceCheckout(),
+    resolveToken,
+    force: argv.includes("--force"),
+    dittoApiKey: false,
+    mcpClient: VALID_CLIENTS.includes(client) ? client : null,
+    wrapper: qapingWrapper(),
+  });
+  if (r.ok) {
+    console.log(`
+Ask your agent:
+   "Set up QA for my game."           (authors QA-PLAN.md in your repo)
+   "Run QA on this patch."            (builds, ships, files playtest rounds)
+   "Did this patch break anything?"   (the same loop, asked plainly)
+
+Playtest rounds are answered by real human playtesters on their own hardware;
+your agent files them, reads the results, and reports back.
+(re-run anytime: qaping setup)`);
+  }
+  process.exit(r.ok ? 0 : 1);
+}
+
+function cmdRemove(argv) {
+  const kitDir = resolveKitDir();
+  // The kit bin's client-scope parser: --client validation is a hard error
+  // BEFORE anything destructive runs, never a scope widening.
+  const { kitSkillClient } = require(path.join(kitDir, "bin", "pingfusi"));
+  let client;
+  try { client = kitSkillClient(argv); }
+  catch (e) { console.error(`✗ ${e.message}`); process.exit(2); }
+  if (client !== "claude-desktop") { // desktop has MCP config but no coding-agent skills
+    try {
+      const w = qapingWrapper();
+      const removed = require(path.join(kitDir, "harness", "agent-setup.js"))
+        .removeSkills(os.homedir(), client, { skillRoot: w.skillRoot, ruleAsset: w.ruleAsset });
+      if (removed.length) console.log(`✓ Removed qaping agent skill(s): ${removed.join(", ")}`);
+    } catch { /* best-effort — the installer's own removal still runs */ }
+  }
+  // The vendored remove with qaping's flags sweeps ONLY the qaping MCP entries
+  // and never touches the shared ~/.config/pingfusi login or pingfusi's own
+  // rule/skill files (--skip-instruction-surfaces + a non-pingfusi server key).
+  process.exit(spawnVendor(argv));
+}
+
+function cmdPublishBuild(argv) {
+  // Kit passthrough: harness/publish-build.js main() takes argv AFTER the
+  // command (argv[0] = the zip path) and owns its own exit codes. The brand
+  // seam keeps every printed command/tool name qaping's own: usage says
+  // `qaping publish-build`, and the next step names qaping_playtest — the
+  // tool the /api/mcp/qaping mount actually registers.
+  return require(path.join(resolveKitDir(), "harness", "publish-build.js"))
+    .main(argv.slice(1), { brandCommand: "qaping publish-build", nextStepToolName: "qaping_playtest" });
+}
+
+const HELP = `qaping — automatic QA for your game: real human playtesters, driven by your coding agent
+
+usage:
+  qaping setup [claude-code|cursor|codex] [--force]
+  qaping remove [--client <c>]        remove qaping's MCP entries, skill and rule
+  qaping publish-build <game.zip> --platform windows|macos
+  qaping wait <ping_id> [--timeout <seconds>]
+  qaping whoami
+  qaping version
+
+Then ask your agent: "Set up QA for my game." or "Run QA on this patch."`;
+
+function route(cmd) {
+  if (cmd === "version" || cmd === "--version" || cmd === "-v") return "version";
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") return "help";
+  if (cmd === "setup") return "setup";
+  if (cmd === "remove" || cmd === "uninstall") return "remove";
+  if (cmd === "wait" || cmd === "whoami") return "vendor";
+  if (cmd === "publish-build") return "publish-build";
+  return "unknown";
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  try {
+    switch (route(argv[0])) {
+      case "version": return console.log(require("../package.json").version);
+      case "help": return console.log(HELP);
+      case "setup": return void cmdSetup(argv).catch((e) => { console.error(`✗ ${(e && e.message) || e}`); process.exit(1); });
+      case "remove": return cmdRemove(argv);
+      // `wait` also names the wait tool the qaping mount registers — the
+      // vendored default (the stock mount's wait) is not on /api/mcp/qaping.
+      case "vendor": return process.exit(spawnVendor(argv[0] === "wait" ? [...argv, "--wait-tool", "qaping_wait"] : argv));
+      case "publish-build": return void cmdPublishBuild(argv);
+      default:
+        console.error(HELP);
+        process.exit(1);
+    }
+  } catch (e) {
+    // a clean message for sync failures (e.g. the kit dependency missing) —
+    // never a raw stack at the user
+    console.error(`✗ ${(e && e.message) || e}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+module.exports = { route, resolveKitDir, qapingWrapper, vendorFlags, isSourceCheckout, RULE_BODY, HELP };

package/docs/QA-PLAN-FORMAT.md

@@ -0,0 +1,71 @@
+# QA-PLAN.md — the format
+
+`QA-PLAN.md` lives at the GAME repo's root. The agent authors and maintains it;
+the developer owns it and approves every commit. Agents parse it by reading —
+keep it exactly this shape, nothing fancier.
+
+## Plan frontmatter
+
+YAML at the very top of the file:
+
+```yaml
+---
+game: Solar Drift
+build_command: ./scripts/package.sh --release   # the ONE command that produces a shippable build
+platforms: [windows]                            # windows | macos | ios
+input: XInput gamepad                           # optional; default keyboard+mouse
+---
+```
+
+`build_command` is recorded once at setup so every future run can build without
+asking. `input` declares the hardware the first-15-minutes check (and any check
+that needs it) is played on — rounds must ask playtesters to confirm what they
+actually used.
+
+## Checks
+
+One `##` section per check; the heading is the check's short name. The section
+opens with a fenced yaml block, then the steps as prose:
+
+```yaml
+id: save-loads            # stable slug — never reused, never renamed
+rung: human               # human | code
+origin: authored          # "authored", or the round id that minted/last changed it
+last_verified: 2026-08-25 # date or build tag of the last passing verification
+```
+
+- **Steps are prose for a person**: numbered, imperative, written so a
+  playtester who has never seen the game can follow them — they become the
+  round's instructions verbatim.
+- **Order the file critical-path first**: boots to menu, previous-version save
+  loads, first 15 minutes on the declared input hardware, core loop, settings
+  persist — then game-specific checks.
+- A `rung: code` check keeps its prose (it documents intent) and adds one
+  `test:` line naming the repo test that now asserts it, e.g.
+  `` test: `tests/save_compat.test.ts` ``.
+
+## Example section
+
+````markdown
+## A previous-version save loads
+
+```yaml
+id: save-loads
+rung: human
+origin: authored
+last_verified: 2026-08-25
+```
+
+1. From the main menu, choose Continue.
+2. Load the provided save "campaign-mid.sav" (made on the previous release).
+3. Confirm the game resumes in the desert outpost with the inventory intact.
+4. Play for one minute; note anything missing, corrupted, or visually wrong.
+````
+
+## Maintenance rules
+
+- Every run updates the run checks' `last_verified`; findings-driven edits
+  record the round id as `origin`.
+- New checks start `rung: human`, `origin: authored`.
+- Promotion (human → code) and any deletion/demotion happen only with the
+  developer's explicit agreement.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@qaping/cli",
+  "version": "0.1.0",
+  "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": [
+    "qaping",
+    "game-qa",
+    "playtest",
+    "regression",
+    "qa",
+    "agent"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "qaping": "bin/qaping"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "docs/"
+  ],
+  "engines": {
+    "node": "^20.17.0 || ^22.13.0 || >=23.5.0"
+  },
+  "dependencies": {
+    "pingfusi": "^0.16.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/qaping/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: qaping
+description: Run automatic QA for a game repo through qaping — real human playtesters play the developer's builds on their own hardware, and the agent runs the whole loop. Use when the user says "set up QA for my game", "run QA on this patch", "did this patch break anything", "playtest my game" or "playtest this build", or asks for regression checks, patch verification, or human playtesting of a game. Covers both halves of the product - authoring and maintaining QA-PLAN.md in the game repo, and the per-patch run (read the diff, build, publish-build, file qaping_playtest rounds, report on the PR, file issues, promote settled checks into repo code tests). Do not use for web apps, websites, or UI review of anything that is not a game build — the qaping tools test game builds only.
+---
+
+# qaping — the QA loop for a game repo
+
+Two jobs, one file. SETUP authors `QA-PLAN.md` — the committed list of checks
+this game must pass. RUN executes it per patch: pick the affected checks, build,
+ship the build to real human playtesters, report what they found. Over patches,
+checks migrate from human rounds to repo code tests, so QA gets cheaper. All
+service contact goes through three MCP tools — `qaping_playtest`,
+`qaping_results`, `qaping_wait` — plus `qaping publish-build` for hosting
+the build.
+
+## Ground rules (read before filing anything)
+
+- **Playtesters are real people.** A session takes real minutes to be claimed
+  and played. File, then `qaping_wait`; whenever a filing or wait returns
+  pending, immediately call `qaping_wait` again with the same ping_id. Never
+  report pending as the final answer, never file a duplicate round.
+- **Costs are duration-billed**: 2 credits per minute of play, per playtester
+  (`est_minutes × 2 × players`). State the estimate to the user BEFORE filing.
+- **Windows rounds return a recording + questionnaire and NO transcript**
+  (`transcript_status:'unavailable'`) — never promise one; plan to watch the
+  recording for timestamps. macOS and iOS rounds include an inline [mm:ss]
+  think-aloud transcript.
+- **Machine replay is not self-serve yet.** Never claim an automated replay ran.
+  The only automated rung you can run today is a `rung: code` test in the
+  dev's own repo/CI.
+- **QA-PLAN.md is the dev's file.** Commit it only with their approval; never
+  delete or demote a human check without them agreeing.
+
+## SETUP — author QA-PLAN.md (first run in a repo)
+
+1. Read the game repo: engine, how a shippable build is produced, save system,
+   settings, input devices the game supports.
+2. Ask the dev ONCE for their build command (the one command that produces a
+   shippable build) and which platforms they ship; record both in the plan's
+   frontmatter so every future run can build without asking again.
+3. Author `QA-PLAN.md` at the repo root, format per `docs/QA-PLAN-FORMAT.md`
+   (shipped with this package — read it first). Order checks critical-path
+   first, then game-specific ones:
+   1. the game boots to the main menu
+   2. a previous-version save loads
+   3. the first 15 minutes play clean on the declared input hardware
+   4. the core loop works (name it concretely — the thing this game is)
+   5. settings persist across a restart
+   Every check carries `{id, rung, origin, last_verified}`. New checks start
+   `rung: human`, `origin: authored`.
+4. Tell the dev how runs get triggered, honestly: for now the loop runs from
+   their own machine or agent — after a patch lands, they say "run QA on this
+   patch" and the RUN half below executes. Do NOT offer to wire a CI workflow
+   file: a plain CI runner has no qaping MCP connection and no login, so a
+   committed workflow could not run this loop today. A CI-triggered recipe is
+   a documented follow-up; until it ships, per-patch QA is an ask-your-agent
+   step.
+5. Show the dev the plan and commit only on their approval.
+
+## RUN — per patch
+
+1. **Select.** Read the diff (or PR). Pick the checks it can plausibly affect,
+   plus the always-run criticals (the critical-path block above). Tell the user
+   which checks run and why.
+2. **Build** via the recorded build command; zip the result.
+3. **Ship:** `qaping publish-build <game.zip> --platform windows|macos` →
+   prints a `/b/<slug>` URL (temporary hosting; filing a playtest extends the
+   build through the round; each publish mints a NEW URL). A store-delivered
+   game files with its Steam store page, TestFlight public link, or App Store
+   page as `url` instead.
+4. **File** ONE `qaping_playtest` per batch of human checks a single session
+   can cover, `est_minutes` an honest sum of the steps — the service accepts
+   5–30 minutes (10 is the standard session; outside that range the filing is
+   refused, not clamped), and the clock is play time: download/install happens
+   before it starts. The authored
+   `instructions` + `steps` must embed:
+   - the selected checks' steps, in play order (the plan's prose, verbatim
+     where possible);
+   - the previous round's findings as context — "last round reported X —
+     recheck" — so regressions get re-examined on every patch;
+   - the hardware-verification convention: when the game needs more than
+     keyboard+mouse, say so up front in `instructions` (playtesters self-select
+     before claiming) AND add an explicit step asking which input device was
+     actually used, with options — the answer comes back verified in
+     `steps_result`.
+   For a regression batch that knows exactly what it is testing, send
+   `questionnaire:'none'` so your steps are the only questions; leave the
+   standard questionnaire on for a first baseline round.
+5. **Wait:** `qaping_wait` until results arrive (see ground rules).
+6. **Report** from `qaping_results`:
+   - PR comment via `gh pr comment`: ONE verdict sentence first, then one line
+     per check — ✅/❌ with a recording timestamp ([mm:ss] from the transcript
+     where present; from watching the recording on Windows) — then credits
+     spent.
+   - One `gh issue create` per CONFIRMED bug: title, repro steps rebuilt from
+     the playtester's answers, a timestamp link into the recording. Issues are
+     drafts for the dev's own triage — never near-duplicates, never one issue
+     per symptom of the same bug.
+   - Update `QA-PLAN.md`: each run check's `last_verified` becomes this
+     build/date; a check changed because of this round records the round id as
+     `origin`.
+
+## PROMOTE — make the suite cheaper
+
+When a check has passed and is mechanically assertable — a save file loads, a
+config parses, an asset path resolves — offer to write a normal test in the
+repo's own test suite. On the dev's yes: write the test, flip the check's
+`rung` to `code`, keep the prose (it documents intent) and add a `test:` line
+naming the test file. `rung: code` checks then run in the dev's own CI for
+free — that is the point: every check starts human and gets cheaper over time.
+Checks about feel, difficulty, or ambiguous visuals stay `rung: human`
+permanently. Never delete or demote a human check without the dev agreeing.