WIP: add ttrpg-encounter-builder skill + server-mode API docs

UNTESTED work in progress. Do not assume correct. Scope: SERVER BACKEND ONLY (SQLite/Express, REACT_APP_STORAGE=server). Does NOT work with Firebase SDK mode — no HTTP backend there, different transport/auth. Skill + doc explicitly call this out. - .agents/skills/ttrpg-encounter-builder/: harness-agnostic skill (pi/claude/codex via .agents/skills + symlinks). SKILL.md + helper script that batch-writes encounters via REST, rolls initiative, verifies. - docs/ENCOUNTER_BUILDER.md: add Path normalization section, Build flow (API/scripts) section with REST endpoint table, object templates, recipe. Server-mode-only caveat noted. Helper script syntax-checked + campaign lookup verified against running instance, but full seed flow not regression-tested against test suite.
2026-07-07 15:42:02 -04:00
parent 907484fc7f
commit 43b1f6ce41
3 changed files with 551 additions and 0 deletions
@@ -0,0 +1,294 @@
 ---
 name: ttrpg-encounter-builder
 description: |
  Seeds D&D encounter rosters into the TTRPG Initiative Tracker via its REST API
  (no UI clicking). Use when the user asks to "set up encounters", "build
  encounters", "add participants to a campaign", "seed this encounter list",
  or provides a statblock list (name + HP + init) for a campaign running on a
  self-hosted tracker instance running in SERVER MODE (bundled Express
  backend). NOT for Firebase SDK mode — that has no HTTP backend; write path
  differs entirely. Harness-agnostic: pi, Claude Code, and Codex all run the
  same script + curl recipes.
 ---
 # TTRPG Encounter Builder
 Build encounter rosters directly via the tracker REST API. No UI clicking, no
 browser automation. One batch write per session, then verify.
 ## When to use
 User provides a campaign name + a list of encounters, each with named
 participants carrying HP and initiative modifiers (or rolled initiative).
 Examples:
 - "set up these encounters in the 2026 D&D campaign on bee.icantclick.org:8080"
 - "build encounter: Barrowdeep 1 - Ankheg HP 45 Init +0"
 - "seed these statblocks into my tracker"
 Do NOT use for: starting combat, rolling HP mid-fight, editing live combat
 state, or driving the player display. Those are in-combat ops, not build ops.
 ## Prerequisites
 - A running tracker instance in **SERVER MODE** (`REACT_APP_STORAGE=server`,
  bundled Express backend mounted). Reachable over HTTP.
  - **Firebase SDK mode NOT supported.** No `/api/*` endpoints exist; data
    lives in Firestore via the in-browser SDK with different auth + write
    paths. This skill cannot reach it. If the user is on firebase mode, tell
    them: switch to server mode, or build encounters via the UI / a
    firebase-admin script (out of scope here).
 - Node.js 18+ (for `fetch` + `crypto.randomUUID`). Helper script uses only
  builtins — no `npm install`.
 - Campaign must already exist (created via UI or `POST /api/collection`).
  This skill adds encounters to an existing campaign.
 Confirm host reachable + server mode before building:
 ```bash
 curl -s <HOST>/api/collection?path=campaigns | head -c 200
 ```
 Returns JSON array of campaign docs = server mode confirmed. HTML (SPA shell)
 = firebase mode OR backend not mounted. Either way, this skill won't work —
 tell the user.
 ## Data model (read this before writing)
 Three nested entities, all opaque JSON docs in a path-keyed KV store:
 ```
 Campaign        campaigns/{campaignId}
  └─ Encounter  campaigns/{campaignId}/encounters/{encounterId}
       └─ Participant  (inline array item on the encounter doc)
 ```
 **Participants are inline.** There is NO `participants` sub-collection. A
 `participants` path returns empty. Each encounter doc carries its full roster
 in a `participants[]` array.
 ### Path normalization (gotcha)
 App code uses firebase-prefixed paths (`artifacts/{APP_ID}/public/data/campaigns/...`).
 The REST API uses **bare canonical** paths (`campaigns/...`). The adapter
 strips the prefix server-side.
 - REST / scripts / direct DB → bare: `campaigns/{cid}/encounters/{eid}`
 - If `GET /api/collection?path=artifacts/.../campaigns` returns `[]`, you used
  the prefixed form. Drop the prefix.
 ### Encounter doc shape
 ```js
 {
  name: 'Barrowdeep 1 - Antechamber',
  createdAt: new Date().toISOString(),
  participants: [],                  // inline roster
  round: 0,
  currentTurnParticipantId: null,
  isStarted: false,
  isPaused: false,
  ruleset: '5e',
 }
 ```
 Build encounters with `round: 0`, `isStarted: false`. Starting combat is a
 separate in-combat op (UI Start button or a later skill).
 ### Participant object shape
 ```js
 {
  id: <uuid>,                        // crypto.randomUUID(), client-generated
  name: 'Ankheg',
  type: 'monster',                   // 'monster' | 'npc' | 'character'
  originalCharacterId: null,         // set only if type === 'character'
  initiative: <int>,                 // rolled ONCE at add; stored, not re-derived
  maxHp: 45,
  currentHp: 45,                     // start at full
  conditions: [],
  isActive: true,
  status: 'conscious',
  deathSaveSuccesses: 0,             // character/npc only
  deathSaveFailures: 0,              // character/npc only
 }
 ```
 ### type field
 - `monster` — DM-controlled, dead at 0 HP (auto-inactive). Default.
 - `npc` — DM-controlled but keeps death saves (revivable). Use for named
  allies/villains the DM runs.
 - `character` — player character. Requires `originalCharacterId` linking to a
  campaign roster entry. For build-from-statblock, use `monster` or `npc`,
  not `character`.
 ### Initiative semantics
 - Default: `initiative = rollD20() + initMod` (d20 ∈ [1,20], rolled fresh per
  participant).
 - Manual override: set `initiative` directly (pre-rolled values), skip the
  roll. `initMod` is NOT stored on the participant — only the final
  `initiative` value persists.
 - Fixed at add time. Never re-derived after.
 ### id format
 `generateId()` = `crypto.randomUUID()` (fallback `id_{Date.now()}_{rand10}`).
 Generate participant ids client-side so they're stable across batch writes.
 Server `POST /api/collection` auto-generates a UUID for the doc id — fine for
 campaigns/encounters, but for inline participants you generate them yourself.
 ## REST endpoints
 All paths bare canonical.
 | Method | Path | Body / Query | Action |
 |---|---|---|---|
 | `GET` | `/api/doc` | `?path=` | read one doc |
 | `PUT` | `/api/doc` | `{path, data}` | replace doc |
 | `PATCH` | `/api/doc` | `{path, patch}` | shallow merge, create-on-miss |
 | `DELETE` | `/api/doc` | `?path=` | delete one doc |
 | `GET` | `/api/collection` | `?path=` | list docs under collection |
 | `POST` | `/api/collection` | `{path, data}` | addDoc: auto-id under collection |
 | `POST` | `/api/batch` | `{ops:[{type, path, data?}]}` | atomic multi-write |
 `POST /api/batch` is the workhorse for seeding. One batch, all encounters,
 atomic.
 ## Build flow
 ### 1. Parse the user's request
 Extract:
 - **Host** — the running tracker URL (e.g. `http://bee.icantclick.org:8080`).
  If omitted, ask. Do not guess.
 - **Campaign name** — must match an existing campaign doc's `name` field.
 - **Encounters** — list of `{name, participants:[{name, type?, maxHp, initMod?|initiative?}]}`.
 A statblock line like `Ankheg - HP 45 - Init +0` parses to:
 `{name:"Ankheg", type:"monster", maxHp:45, initMod:0}`.
 ### 2. Resolve the campaign id
 Campaigns are keyed by id, not name. Look up by name:
 ```bash
 curl -s "<HOST>/api/collection?path=campaigns" \
  | jq -r '.[] | select(.name=="<CAMPAIGN NAME>") | .id'
 ```
 Exactly one match expected. Zero → campaign doesn't exist (tell user to create
 it first). Multiple → ambiguous name, ask user which id.
 ### 3. Write encounters (two options)
 #### Option A — helper script (recommended)
 `scripts/build-encounters.js` handles id gen, initiative rolling, batch write,
 and verification. Reads a spec file or stdin.
 Spec format (JSON array):
 ```json
 [
  {
    "name": "Optional Road/Trail Ankheg",
    "participants": [
      { "name": "Ankheg", "type": "monster", "maxHp": 45, "initMod": 0 }
    ]
  },
  {
    "name": "Barrowdeep 2 - Minor Burial Chamber",
    "participants": [
      { "name": "Cult Fanatic", "type": "monster", "maxHp": 39, "initMod": 2 },
      { "name": "Cultist 1", "type": "monster", "maxHp": 9, "initMod": 2 },
      { "name": "Cultist 2", "type": "monster", "maxHp": 9, "initMod": 2 }
    ]
  }
 ]
 ```
 Run (resolve script path relative to this skill dir):
 ```bash
 node scripts/build-encounters.js <HOST> "<CAMPAIGN NAME>" spec.json
 # or stdin:
 cat spec.json | node scripts/build-encounters.js <HOST> "<CAMPAIGN NAME>" -
 ```
 Script prints each encounter id + participant init rolls, then verifies.
 #### Option B — raw curl (any harness, no node)
 Build the batch payload inline. Generate UUIDs and roll initiative yourself.
 One `POST /api/batch` writes everything:
 ```bash
 curl -s -X POST "<HOST>/api/batch" \
  -H 'Content-Type: application/json' \
  -d '{
    "ops": [
      {
        "type": "set",
        "path": "campaigns/CID/encounters/EID1",
        "data": {
          "name": "Optional Road/Trail Ankheg",
          "createdAt": "2026-07-07T00:00:00.000Z",
          "participants": [
            { "id": "UUID1", "name": "Ankheg", "type": "monster", "originalCharacterId": null, "initiative": 15, "maxHp": 45, "currentHp": 45, "conditions": [], "isActive": true, "status": "conscious", "deathSaveSuccesses": 0, "deathSaveFailures": 0 }
          ],
          "round": 0, "currentTurnParticipantId": null, "isStarted": false, "isPaused": false, "ruleset": "5e"
        }
      }
    ]
  }'
 ```
 Response: `{"ok":true}`. If you get an error, check path is bare (no
 `artifacts/` prefix) and JSON is valid.
 ### 4. Verify
 Always verify after write. Don't trust the batch `ok` alone.
 ```bash
 curl -s "<HOST>/api/collection?path=campaigns/CID/encounters" \
  | jq '.[] | {name, participants: (.participants|length), started: .isStarted}'
 ```
 Expect one object per encounter with correct participant count and
 `started: false`.
 ### 5. Report back to user
 Tell the user:
 - Host + campaign name resolved
 - Per encounter: name, id, participant count, rolled initiatives
 - Verification result (counts matched)
 - That combat is NOT started (encounters sit at `round: 0, isStarted: false`).
  User starts combat via the UI Start button when ready.
 ## Common mistakes
 | Symptom | Cause | Fix |
 |---|---|---|
 | `GET /api/collection?path=artifacts/.../campaigns` returns `[]` | used firebase-prefixed path | drop `artifacts/{APP_ID}/public/data/` prefix, use bare `campaigns` |
 | `GET /health` or collection returns HTML (SPA shell) | server in firebase mode, or backend not mounted | confirm `REACT_APP_STORAGE=server` + backend running on the instance |
 | Batch returns `ok` but encounter missing | wrong campaign id, or path typo | re-resolve campaign id by name; check path segments |
 | Participant count mismatch on verify | participant objects malformed / dropped in JSON | validate each has all required fields; use script to avoid hand-JSON errors |
 | Initiative looks wrong | forgot `initiative` is stored value, not re-derived | roll `d20 + initMod` once at build, store the int. No `initMod` field on participant. |
 | Duplicate cultist names across encounters | fine — names need only be unique WITHIN an encounter, not across | no fix needed |
 ## Out of scope
 - Creating campaigns (use UI or `POST /api/collection` with a campaign doc)
 - Starting combat / advancing turns / HP damage / death saves (in-combat ops)
 - Player display control (`activeDisplay/status`)
 - Firebase SDK mode (this skill is server-mode REST only)
 - Campaign roster characters (`players[]` on campaign doc) — those are
  templates; this skill adds inline combatants, not roster entries
 ## Reference
 Full entity model, combat flow, and storage paths: `docs/ENCOUNTER_BUILDER.md`
 in the repo root. REST + DB internals: `docs/DEVELOPMENT.md` and
 `server/index.js`.
@@ -0,0 +1,149 @@
 // build-encounters.js — seed TTRPG encounters via REST API.
 // Cross-harness: pi, claude, codex all call same script.
 // No deps beyond node builtins. Reads spec JSON, writes batch, verifies.
 //
 // Usage:
 //   node build-encounters.js <host> <campaignName> <specFile>
 //   cat spec.json | node build-encounters.js <host> <campaignName> -
 //
 // specFile = JSON array of encounters:
 // [
 //   {
 //     "name": "Barrowdeep 1 - Antechamber",
 //     "participants": [
 //       { "name": "Ankheg", "type": "monster", "maxHp": 45, "initMod": 0 },
 //       { "name": "Boss",   "type": "npc",     "maxHp": 39, "initMod": 2, "initiative": 15 }
 //     ]
 //   }
 // ]
 //
 // type: 'monster' | 'npc' | 'character'. Default 'monster'.
 // initiative: optional manual override. If omitted, rolled d20 + initMod.
 // initMod default 0. maxHp default 10.
 //
 // Output: written encounter ids + rolled initiatives. Exit 0 on success.
 'use strict';
 const crypto = require('crypto');
 const genId = () =>
  (typeof crypto !== 'undefined' && crypto.randomUUID)
    ? crypto.randomUUID()
    : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 const rollD20 = () => Math.floor(Math.random() * 20) + 1;
 function makeParticipant(spec) {
  const type = spec.type || 'monster';
  const maxHp = spec.maxHp || 10;
  const initMod = spec.initMod || 0;
  const manual = spec.initiative !== undefined && spec.initiative !== null;
  return {
    id: genId(),
    name: spec.name,
    type,
    originalCharacterId: spec.originalCharacterId || null,
    initiative: manual ? Number(spec.initiative) : rollD20() + initMod,
    maxHp,
    currentHp: maxHp,
    conditions: [],
    isActive: true,
    status: 'conscious',
    deathSaveSuccesses: 0,
    deathSaveFailures: 0,
  };
 }
 async function getJson(url) {
  const r = await fetch(url);
  if (!r.ok) throw new Error(`GET ${url} -> ${r.status}: ${await r.text()}`);
  return r.json();
 }
 async function postJson(url, body) {
  const r = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!r.ok) throw new Error(`POST ${url} -> ${r.status}: ${await r.text()}`);
  return r.json();
 }
 async function findCampaignId(host, name) {
  const list = await getJson(`${host}/api/collection?path=campaigns`);
  const matches = list.filter(c => c.name === name);
  if (matches.length === 0) {
    console.error(`No campaign named "${name}". Existing:`);
    list.forEach(c => console.error(`  ${c.name}`));
    process.exit(2);
  }
  if (matches.length > 1) {
    console.error(`Multiple campaigns named "${name}". Use unique name or pass id.`);
    matches.forEach(c => console.error(`  ${c.id}  ${c.name}`));
    process.exit(2);
  }
  return matches[0].id;
 }
 async function main() {
  const [host, campaignName, specArg] = process.argv.slice(2);
  if (!host || !campaignName || !specArg) {
    console.error('Usage: node build-encounters.js <host> <campaignName> <specFile|->');
    process.exit(1);
  }
  const specRaw = specArg === '-'
    ? require('fs').readFileSync(0, 'utf8')
    : require('fs').readFileSync(specArg, 'utf8');
  const encounters = JSON.parse(specRaw);
  if (!Array.isArray(encounters)) throw new Error('spec must be a JSON array of encounters');
  const cid = await findCampaignId(host, campaignName);
  console.log(`campaign: "${campaignName}" -> ${cid}`);
  const encPath = `campaigns/${cid}/encounters`;
  const now = new Date().toISOString();
  const ops = [];
  const summary = [];
  for (const enc of encounters) {
    const id = genId();
    const path = `${encPath}/${id}`;
    const parts = (enc.participants || []).map(makeParticipant);
    ops.push({
      type: 'set',
      path,
      data: {
        name: enc.name,
        createdAt: now,
        participants: parts,
        round: 0,
        currentTurnParticipantId: null,
        isStarted: false,
        isPaused: false,
        ruleset: enc.ruleset || '5e',
      },
    });
    summary.push({ name: enc.name, id, parts });
  }
  const res = await postJson(`${host}/api/batch`, { ops });
  if (!res.ok) throw new Error(`batch failed: ${JSON.stringify(res)}`);
  console.log(`batch: ${ops.length} encounter(s) written\n`);
  // Verify
  const written = await getJson(`${host}/api/collection?path=${encPath}`);
  const byId = new Map(written.map(e => [e.id, e]));
  for (const s of summary) {
    const got = byId.get(s.id);
    const ok = got && got.name === s.name && (got.participants || []).length === s.parts.length;
    console.log(`${ok ? '✓' : '✗'} ${s.name}`);
    console.log(`  id: ${s.id}`);
    if (!ok) { console.log(`  VERIFY FAILED: got ${JSON.stringify(got && { name: got.name, n: (got.participants || []).length })}`); continue; }
    s.parts.forEach(p => {
      const i = p.initiative >= 0 ? `+${p.initiative}` : `${p.initiative}`;
      console.log(`    - ${p.name} (${p.type}, hp ${p.maxHp}, init ${i})`);
    });
  }
  console.log('\nDone.');
 }
 main().catch(e => { console.error('FAIL:', e.message); process.exit(1); });
@@ -64,6 +64,15 @@ Object in `encounter.participants[]`:
 | `deathSaveSuccesses` | int | character/NPC only, 0-3 successes |
 | `deathSaveFailures` | int | character/NPC only, 0-3 failures |
 ## Path normalization
 App passes firebase-prefixed paths (`artifacts/{APP_ID}/public/data/campaigns/...`). Server-mode adapter `norm()` strips prefix → bare canonical (`campaigns/...`).
 - **UI / app code** → prefixed paths (`getPath.*` helpers)
 - **REST API / direct DB / scripts** → bare canonical paths (`campaigns/...`)
 Mixing = empty results. If `GET /api/collection?path=artifacts/.../campaigns` returns `[]`, you used the prefixed form. Drop the prefix.
 ## Build flow (UI)
 Admin view at `/`. Steps:
@@ -121,6 +130,101 @@ Pre-combat only (`!isStarted || isPaused`). Drag handles shown for **tied initia
 During active combat, cross-current-pointer drag is blocked to avoid skip/double-act ambiguity. Paused combat can reorder same-initiative ties freely.
 ## Build flow (API / scripts)
 Same logical steps as UI, via REST. For LLM agents or seed scripts.
 **Server mode only.** REST endpoints (`/api/*`) exist only when tracker runs
 with `REACT_APP_STORAGE=server` (bundled Express backend mounted). Firebase
 SDK mode has no HTTP backend — data lives in Firestore via in-browser SDK,
 different auth + write paths. This section does not apply to firebase mode.
 Confirm server mode before scripting:
 ```bash
 curl -s <HOST>/api/collection?path=campaigns | head -c 200
 ```
 JSON array = server mode. HTML (SPA shell) = firebase mode or backend not
 mounted — API path won't work.
 ### REST endpoints
 | Method | Path | Body / Query | Action |
 |---|---|---|---|
 | `GET` | `/api/doc` | `?path=` | read one doc |
 | `PUT` | `/api/doc` | `{path, data}` | replace doc |
 | `PATCH` | `/api/doc` | `{path, patch}` | shallow merge, create-on-miss |
 | `DELETE` | `/api/doc` | `?path=` | delete one doc |
 | `GET` | `/api/collection` | `?path=` | list docs under collection |
 | `POST` | `/api/collection` | `{path, data}` | addDoc: auto-id under collection |
 | `POST` | `/api/batch` | `{ops:[{type:'set'\|'update'\|'delete', path, data?}]}` | atomic multi-write |
 All paths bare canonical (no `artifacts/...` prefix).
 ### id format
 `generateId()` = `crypto.randomUUID()` (fallback `id_{Date.now()}_{rand10}`). Use either. Server `POST /api/collection` generates its own UUID — fine for campaigns/encounters. Participants are inline array items; generate their ids client-side so they're stable across batch writes.
 ### Object templates
 Encounter doc (full, for `PUT` / batch `set`):
 ```js
 {
  name: 'Barrowdeep 1 - Antechamber',
  createdAt: new Date().toISOString(),
  participants: [],          // inline, NOT a sub-collection
  round: 0,
  currentTurnParticipantId: null,
  isStarted: false,
  isPaused: false,
  ruleset: '5e',
 }
 ```
 Participant object (item in `encounter.participants[]`):
 ```js
 {
  id: generateId(),
  name: 'Ankheg',
  type: 'monster',            // 'character' | 'npc' | 'monster'
  originalCharacterId: null,  // set only if type==='character'
  initiative: rollD20() + initMod,  // rolled ONCE at add; stored, not re-derived
  maxHp: 45,
  currentHp: 45,              // start at full
  conditions: [],
  isActive: true,
  status: 'conscious',
  deathSaveSuccesses: 0,      // character/npc only
  deathSaveFailures: 0,       // character/npc only
 }
 ```
 ### Initiative semantics
 - Default: `initiative = rollD20() + initMod` (d20 ∈ [1,20], roll fresh per participant).
 - Manual override (e.g. pre-rolled values): set `initiative` directly, skip the roll.
 - Fixed at add time. NOT re-derived from `initMod` after — `initMod` is not stored on participant.
 ### Recipe: build encounters for a campaign
 1. **Find campaign id by name:**
 ```bash
 curl -s "$HOST/api/collection?path=campaigns" \
  | jq -r '.[] | select(.name=="2026 D&D") | .id'
 ```
 2. **Build encounter docs + participants client-side** (object templates above), roll initiative per participant.
 3. **Write all encounters in one batch:**
 ```bash
 curl -s -X POST "$HOST/api/batch" \
  -H 'Content-Type: application/json' \
  -d '{"ops":[{"type":"set","path":"campaigns/CID/encounters/EID1","data":{...}},{"type":"set","path":"campaigns/CID/encounters/EID2","data":{...}}]}'
 ```
 4. **Verify:**
 ```bash
 curl -s "$HOST/api/collection?path=campaigns/CID/encounters" | jq '.[] | {name, count: (.participants|length)}'
 ```
 Participants go inline in the encounter doc — there is no `participants` sub-collection. A single batch `set` per encounter writes the whole roster atomically.
 ## Combat flow (UI)
 InitiativeControls panel (sticky, right side).
@@ -198,6 +302,8 @@ No re-sort after `startEncounter`.
 ## Storage paths quick reference
 Bare canonical (server mode). App code prefixes these with `artifacts/{APP_ID}/public/data/` — adapter strips it.
 ```
 campaigns/{cid}                              campaign doc
 campaigns/{cid}/encounters/{eid}             encounter doc (participants[])
@@ -206,6 +312,8 @@ activeDisplay/status                         player display control
 logs/{logId}                                 action log entry
 ```
 REST mapping: `campaigns/{cid}` doc → `GET/PUT/PATCH/DELETE /api/doc?path=campaigns/{cid}`. Collection parent (`campaigns`, `campaigns/{cid}/encounters`) → `GET/POST /api/collection?path=...`.
 ## DM tips
 - Initiative rolled ONCE at add time. Stored. Edit via EditParticipantModal to override.