@dreamboard-games/cli 0.1.30-alpha.1 → 0.1.30-alpha.11

package/skills/dreamboard/references/rule-authoring.md

@@ -0,0 +1,147 @@
+<!-- Generated by apps/dreamboard-cli/scripts/sync-skill-docs.ts. -->
+<!-- Source: docs/reference/rule-authoring.mdx -->
+
+# Rule authoring
+
+Reference for authoring Dreamboard rule.md files.
+
+`rule.md` is the game-design source of intent for a Dreamboard project. Use it
+to describe the rules in plain language before you commit to reducer state,
+manifest, or UI details.
+
+## Responsibility
+
+Use `rule.md` for:
+
+- the game objective and match shape
+- setup, turn flow, scoring, and victory rules
+- player actions and their legality constraints
+- visibility rules and information flow
+- edge cases and deterministic tie-break rules
+
+## Recommended structure
+
+Use the same section order for every `rule.md`.
+
+### `Overview`
+
+State the core promise of the game in one short section.
+
+- supported player count
+- objective
+- expected match length
+- one-paragraph summary of how a turn feels
+
+### `Components`
+
+List the components the rules assume exist.
+
+- cards, zones, boards, pieces, dice, and resources
+- public versus hidden information
+- per-player versus shared components
+- hard limits such as hand size, stock limits, or caps
+
+### `Setup`
+
+Describe the initial state in ordered steps.
+
+- how players are seated
+- which player acts first
+- which components start in which locations
+- any setup options or setup-profile differences
+
+### `Gameplay`
+
+Describe the game loop in the order the reducer should implement it.
+
+For each phase, name:
+
+- who is allowed to act
+- which actions are legal
+- what input each action requires
+- what ends the phase
+- which phase follows next
+
+When a game has repeated rounds, document the round loop explicitly instead of
+implying it.
+
+### `Scoring and progression`
+
+Describe how players gain or lose progress.
+
+- points, tracks, resources, or thresholds
+- when scoring happens
+- round-end or trick-end resolution
+- tie-breakers for intermediate rankings
+
+### `Winning conditions`
+
+State the exact end trigger and winner resolution rule.
+
+- when the game ends
+- how the winner is chosen
+- how ties are broken
+- what happens if multiple end conditions become true at once
+
+### `Special rules and edge cases`
+
+List rules that are easy to miss during implementation.
+
+- simultaneous actions
+- empty-deck or empty-pool behavior
+- no-op or invalid actions
+- forced actions versus optional actions
+- what happens when a player cannot act
+
+## Example template
+
+```markdown
+# <Game name>
+
+## Overview
+
+- Players: <min-max> (optimal: <n>)
+- Objective: <how a player wins>
+- Duration: <target minutes>
+
+## Components
+
+- Shared components:
+- Per-player components:
+- Public information:
+- Hidden information:
+
+## Setup
+
+1. ...
+2. ...
+3. ...
+
+## Gameplay
+
+### Phase 1: <name>
+
+- Acting player(s):
+- Allowed actions:
+- Validation:
+- Completion:
+- Next phase:
+
+### Phase 2: <name>
+
+- ...
+
+## Scoring and progression
+
+- ...
+
+## Winning conditions
+
+- End trigger:
+- Winner determination:
+- Tie-breaker:
+
+## Special rules and edge cases
+
+- ...
+```

package/skills/dreamboard/references/testing.md

@@ -0,0 +1,249 @@
+<!-- Generated by apps/dreamboard-cli/scripts/sync-skill-docs.ts. -->
+<!-- Source: docs/reference/testing.mdx -->
+
+# Testing
+
+Reference for Dreamboard's reducer-native test framework.
+
+Dreamboard's scaffolded test workspace is reducer-native. It uses typed base
+definitions and typed scenarios that run against your compiled reducer and
+generated contracts.
+
+## Responsibility
+
+Use the scaffolded test workspace for:
+
+- reusable seeded base states
+- reducer and view assertions
+- happy-path coverage
+- rejection and turn-gating coverage
+- deterministic regression testing in CI or local development
+
+## Workspace layout
+
+The current scaffold uses these paths:
+
+- `test/README.md`
+- `test/bases/*.base.ts`
+- `test/scenarios/*.scenario.ts`
+- `test/testing-types.ts`
+- `test/generated/*`
+
+Generated files under `test/generated/*` are owned by Dreamboard and should not
+be edited manually.
+
+## Command flow
+
+Generate reducer-native test artifacts:
+
+```bash
+dreamboard test generate
+```
+
+Run all scenarios:
+
+```bash
+dreamboard test run
+```
+
+Run one scenario:
+
+```bash
+dreamboard test run --scenario test/scenarios/win-the-game.scenario.ts
+```
+
+Re-run `dreamboard test generate` after changes that affect the runtime shape of
+the game, including:
+
+- `manifest.json`
+- reducer code under `app/`
+- setup-profile behavior
+- generated contract output
+
+## Base definitions
+
+A base is a named, seeded checkpoint that scenarios can reuse.
+
+Use `defineBase(...)` from `test/testing-types.ts`.
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `id` | Yes | Stable base identifier referenced by scenarios |
+| `seed` | Yes | Deterministic random seed |
+| `players` | Yes | Player count used for that base |
+| `setup` | Yes | Async setup callback that prepares the checkpoint |
+
+```ts
+import { defineBase } from "../testing-types";
+
+export default defineBase({
+  id: "initial-turn",
+  seed: 1337,
+  players: 2,
+  setup: async ({ game }) => {
+    await game.start();
+  },
+});
+```
+
+The base `seed` drives runtime-owned randomness. Effects such as
+`effects.rollDie(...)`, `effects.randomInt(...)`, `effects.sample(...)`, and
+`effects.shuffleSharedZone(...)` consume the seeded reducer RNG, so repeated
+test runs with the same base seed are reproducible.
+
+Use bases for:
+
+- opening-state invariants
+- post-setup checkpoints shared by many scenarios
+- seeded states that would be noisy to rebuild inline
+
+Keep bases small and composable. A base should represent one meaningful
+checkpoint, not a full playthrough.
+
+## Scenario definitions
+
+Scenarios are typed files under `test/scenarios/*.scenario.ts`.
+
+Use `defineScenario(...)` from `test/testing-types.ts`.
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `id` | Yes | Scenario identifier |
+| `description` | No | Short human-readable summary |
+| `from` | Yes | Base ID from `test/bases/*.base.ts` |
+| `runners` | No | Defaults to reducer runner |
+| `when` | Yes | Async action flow |
+| `then` | Yes | Assertions over state, view, and history |
+
+```ts
+import { defineScenario } from "../testing-types";
+
+export default defineScenario({
+  id: "player-two-wins",
+  description: "The deterministic roll sequence lets player 2 reach ten first",
+  from: "initial-turn",
+  when: async ({ game }) => {
+    await game.action("player-1", "rollDie", {});
+    await game.action("player-2", "rollDie", {});
+    await game.action("player-1", "rollDie", {});
+    await game.action("player-2", "rollDie", {});
+    await game.action("player-1", "rollDie", {});
+    await game.action("player-2", "rollDie", {});
+  },
+  then: ({ publicState, view, expect, history }) => {
+    const state = publicState();
+
+    expect(state.lastRoll).toBe(6);
+    expect(state.scores["player-1"]).toBe(9);
+    expect(state.scores["player-2"]).toBe(12);
+    expect(state.winnerPlayerId).toBe("player-2");
+    expect(view("player-2").winnerPlayerId).toBe("player-2");
+    expect(history().accepted().length).toBe(6);
+  },
+});
+```
+
+## Scenario context
+
+`when(...)` and `then(...)` receive typed helpers from `test/testing-types.ts`.
+
+### `game`
+
+`game` is the typed scenario driver.
+
+Use it to:
+
+- `start()` the game inside base setup
+- `action(playerId, actionType, params)` for reducer actions
+- `action(playerId, command)` for generated command objects
+- `respond(...)` for prompts
+- `windowAction(...)` for reducer-owned window actions
+- `expectPrompt(...)` and `expectWindow(...)` when testing prompt/window flow
+
+### Shared state helpers
+
+Use these in `when(...)` and `then(...)`:
+
+| Helper | Notes |
+| --- | --- |
+| `phase()` | Current reducer phase name |
+| `publicState()` | Current shared reducer state |
+| `view(playerId)` | Projected player view |
+| `runtime()` | Runtime metadata |
+| `history()` | Accepted and rejected inputs |
+| `expect(...)` | Built-in assertion API |
+
+`then(...)` also exposes `hiddenState()` unless the active runner omits hidden
+state access.
+
+## Generated testing types
+
+The scaffold writes `test/testing-types.ts` as the test-facing import surface.
+
+It re-exports:
+
+- `defineBase(...)`
+- `defineScenario(...)`
+- `phaseCommands`
+- `windowCommands`
+- reducer-derived types such as `GameState`, `GameView`, `ActionName`, and
+  `PromptId`
+
+Import from `../testing-types` instead of reaching into `test/generated/*`
+directly.
+
+## Recommended coverage
+
+Every game should have at least:
+
+- one opening-state scenario that asserts the initial phase, active player, and
+  starting view
+- one happy-path scenario that completes a typical turn or round
+- one winning-condition scenario
+- one rejection scenario for out-of-turn or otherwise illegal input
+
+When the game uses prompts or windows, add at least one scenario that exercises
+that continuation path end to end.
+
+## Rejection-path coverage
+
+Rejection scenarios are part of the main test harness, not a separate workflow.
+
+Prefer direct reducer-native assertions for:
+
+- wrong player acting out of turn
+- wrong action for the current phase
+- invalid parameters
+- action attempts after game end
+- repeated submission of one-time actions
+
+Typical checks:
+
+```ts
+then: ({ phase, history, expect, publicState }) => {
+  expect(history().rejected().length).toBe(1);
+  expect(history().accepted().length).toBe(0);
+  expect(phase()).toBe("takeTurn");
+  expect(publicState().winnerPlayerId).toBe(null);
+};
+```
+
+## Failure and staleness signals
+
+If the generated test artifacts no longer match the compiled game, refresh them:
+
+- `dreamboard test generate`
+
+Common symptoms:
+
+- generated files missing under `test/generated/*`
+- type errors caused by stale generated contracts
+- scenario runs using an outdated runtime shape after reducer or manifest edits
+
+## Related workflows
+
+This page documents the scaffolded reducer-native test workspace.
+
+If you also use `dreamboard run` for manual debugging or operational inspection,
+treat that as a separate workflow. It is useful for ad hoc runtime exploration,
+but it is not the primary authored test surface for a new Dreamboard project.

package/skills/dreamboard/scripts/events-extract.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+import { access, readFile } from "node:fs/promises";
+
+const DEFAULT_EVENTS_PATH = ".dreamboard/run/events.ndjson";
+
+function printHelp() {
+  console.log(`Extract fields from dreamboard run artifacts.
+
+Usage:
+  node .agents/skills/dreamboard/scripts/events-extract.mjs [options]
+
+Options:
+  --file, -f <path>       NDJSON file path (default: ${DEFAULT_EVENTS_PATH})
+  --type <eventType>      Filter by event type (repeatable)
+  --field <path>          Dot path to extract (e.g. message.reason)
+  --player <playerId>     Filter by player ID across common message fields
+  --limit <number>        Limit output records
+  --no-index              Omit line index in output
+  --help, -h              Show this help
+
+Examples:
+  node .agents/skills/dreamboard/scripts/events-extract.mjs --type YOUR_TURN
+  node .agents/skills/dreamboard/scripts/events-extract.mjs --type ACTION_REJECTED --field message.reason
+  node .agents/skills/dreamboard/scripts/events-extract.mjs --player player-2 --field message.availableActions
+`);
+}
+
+function parseCliArgs(argv) {
+  const options = {
+    filePath: DEFAULT_EVENTS_PATH,
+    types: new Set(),
+    includeIndex: true,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const nextToken = argv[index + 1];
+
+    if (token === "--help" || token === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+    if (token === "--no-index") {
+      options.includeIndex = false;
+      continue;
+    }
+    if (token === "--file" || token === "-f") {
+      if (!nextToken) {
+        throw new Error("--file requires a value");
+      }
+      options.filePath = nextToken;
+      index += 1;
+      continue;
+    }
+    if (token === "--type") {
+      if (!nextToken) {
+        throw new Error("--type requires a value");
+      }
+      options.types.add(nextToken);
+      index += 1;
+      continue;
+    }
+    if (token === "--field") {
+      if (!nextToken) {
+        throw new Error("--field requires a value");
+      }
+      options.fieldPath = nextToken;
+      index += 1;
+      continue;
+    }
+    if (token === "--player") {
+      if (!nextToken) {
+        throw new Error("--player requires a value");
+      }
+      options.playerId = nextToken;
+      index += 1;
+      continue;
+    }
+    if (token === "--limit") {
+      if (!nextToken) {
+        throw new Error("--limit requires a value");
+      }
+      const parsed = Number.parseInt(nextToken, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("--limit must be a positive integer");
+      }
+      options.limit = parsed;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return options;
+}
+
+function getByPath(value, path) {
+  const segments = path.split(".").filter(Boolean);
+  let current = value;
+
+  for (const segment of segments) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    if (typeof current !== "object") {
+      return undefined;
+    }
+    current = current[segment];
+  }
+
+  return current;
+}
+
+function extractPlayerCandidates(record) {
+  const message = record.message ?? {};
+  const players = new Set();
+
+  const singleCandidates = [
+    message.playerId,
+    message.targetPlayer,
+    message.toUser,
+  ];
+  for (const candidate of singleCandidates) {
+    if (typeof candidate === "string") {
+      players.add(candidate);
+    }
+  }
+
+  const listCandidates = [
+    message.activePlayers,
+    message.previousPlayers,
+    message.currentPlayers,
+    message.controllablePlayerIds,
+    message.eligiblePlayerIds,
+  ];
+  for (const candidate of listCandidates) {
+    if (!Array.isArray(candidate)) {
+      continue;
+    }
+    for (const item of candidate) {
+      if (typeof item === "string") {
+        players.add(item);
+      }
+    }
+  }
+
+  return [...players];
+}
+
+function toOutputRecord(record, lineIndex, options) {
+  const output = {};
+
+  if (options.includeIndex) {
+    output.index = lineIndex;
+  }
+  output.observedAt = record.observedAt ?? null;
+  output.sessionId = record.sessionId ?? null;
+  output.eventId = record.eventId ?? null;
+  output.type = record.type ?? null;
+
+  if (options.fieldPath) {
+    output.field = options.fieldPath;
+    output.value = getByPath(record, options.fieldPath);
+  } else {
+    output.message = record.message ?? null;
+  }
+
+  return output;
+}
+
+async function main() {
+  const options = parseCliArgs(process.argv.slice(2));
+  await access(options.filePath);
+
+  const text = await readFile(options.filePath, "utf8");
+  const lines = text
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  let emitted = 0;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex];
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (options.types.size > 0 && !options.types.has(record.type ?? "")) {
+      continue;
+    }
+
+    if (options.playerId) {
+      const players = extractPlayerCandidates(record);
+      if (!players.includes(options.playerId)) {
+        continue;
+      }
+    }
+
+    const output = toOutputRecord(record, lineIndex + 1, options);
+    console.log(JSON.stringify(output));
+    emitted += 1;
+
+    if (options.limit !== undefined && emitted >= options.limit) {
+      break;
+    }
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`events-extract failed: ${message}`);
+  process.exit(1);
+});

package/dist/agent-verifier/chunk-54TAYXUD.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-
-// ../../node_modules/.pnpm/@dreamboard-games+sdk@0.4.0-alpha.0_@types+react-dom@19.2.3_@types+react@19.2.17__@type_b74cbe125b074769500a56e94fa7f664/node_modules/@dreamboard-games/sdk/dist/chunk-PZ5AY32C.js
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-export {
-  __export
-};