bga-dev-skill 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# bga-assist
+
+## What This Is
+This repository gives you two things for BGA development with Claude Code: a ready-to-use skill file and a local testing harness. The skill file (`SKILL.md`) teaches Claude Code the project conventions and generation patterns, while the harness provides PHP and JS test scaffolding so generated logic can be validated locally. Use the skill alone if you only want better code generation, or use the full harness if you also want runnable tests.
+
+## Installation
+
+### Skill Only (No Testing Infrastructure)
+
+1. Clone or download this repository.
+2. Add `SKILL.md` to your Claude Code workspace instructions.
+
+### Full Harness
+
+1. Clone this repo into your BGA game's development dependencies.
+2. Install PHP support:
+
+```bash
+composer require --dev thebgllc/bga-assist
+```
+
+3. Install JS support:
+
+```bash
+npm install --save-dev bga-assist
+```
+
+4. Extend `BgaGameTestCase` in your PHPUnit tests.
+
+## Using with Claude Code
+
+These prompts are designed to map directly to the tested patterns in `SampleGameTest.php`:
+
+1. "What happens if the active player submits only 2 cards?"
+2. "Write tests for the _checkValidSet function"
+3. "Generate a states.inc.php for a game with a bidding phase and a resolution phase"
+4. "I'm getting a PHP error in my action method - what's wrong?"
+5. "How do I notify only the active player when they draw a card?"
+
+## Running Tests
+
+```bash
+# PHP
+./vendor/bin/phpunit
+
+# JS
+npm test
+```
+
+## Scope Boundaries
+
+This v1 repo intentionally does not include:
+
+- MCP server setup
+- SFTP deployment tooling
+- Studio log tailing
+- Playwright live Studio E2E tests
+- BGA Studio API integration
+- Game-specific production implementations

package/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: bga-dev-skill
+description: Instructions for Claude Code to generate BGA-compatible server code and tests using this repository's implemented harness and patterns.
+---
+
+# BGA Development Instructions
+
+## 1) Your Role
+Act like a senior BGA gameplay engineer who writes production-style server logic and runnable tests. Use only APIs that exist in this repository's harness and tested examples, prefer deterministic game logic, and generate tests in the fluent style used by the provided base test case.
+
+## 2) Framework Version Detection
+Before writing code, detect project style and stay consistent:
+
+- Legacy-style indicators: root-level game files, Dojo module frontend, notifyAllPlayers and notifyPlayer usage.
+- Modern-style indicators: namespaced PHP classes and different notification/action APIs.
+
+If the project is mixed or unclear, stop and ask which framework version to target. Do not mix APIs from different versions in one patch.
+
+## 3) PHP Server - Critical Rules
+These are enforced by implemented harness behavior and passing example tests:
+
+- Use only harness-supported DB methods in game logic:
+  - DbQuery
+  - getCollectionFromDB
+  - getObjectFromDB
+  - getUniqueValueFromDB
+  - getIntFromDB
+- Validate player actions with checkAction before mutating state.
+- Use throwUserError for gameplay validation failures.
+- Use throwVisibleSystemError for server/system failures.
+- Drive state changes through:
+  - gamestate_nextState
+  - gamestate_changeActivePlayer
+  - gamestate_setAllPlayersMultiactive
+  - gamestate_setPlayerNonMultiactive
+- Keep notification payload keys stable and explicit; use the same key names end-to-end.
+- Do not use raw PDO directly in game classes.
+- Do not use superglobals in action logic.
+- Do not invent framework methods that are not present in the harness.
+
+## 4) PHP Server - Common Patterns
+Use these concrete patterns from the implemented sample game and harness:
+
+- Setup/deal flow:
+  - Create required tables if missing.
+  - Seed baseline data if empty.
+  - Deal cards by moving records between locations.
+  - Set initial state and game-state values.
+- Action flow:
+  - checkAction
+  - validate input
+  - load from DB
+  - run pure validation logic
+  - write DB changes
+  - send notifications
+  - transition state
+- Scoring flow:
+  - Update score in DB.
+  - Update card locations in DB.
+  - Notify with result payload.
+- Multi-active flow:
+  - mark all players multiactive.
+  - mark each player non-multiactive as they complete.
+  - transition when all are done.
+
+## 5) Testing - Generating Tests from Natural Language
+When asked "what happens when...", generate PHPUnit tests using BgaGameTestCase fluent helpers and preserve this pattern:
+
+- Given:
+  - givenActivePlayer
+  - givenCurrentPlayer when actor mismatch matters
+  - givenState
+  - givenDatabaseRows
+  - givenGameStateValue
+- When:
+  - whenAction(method, args)
+- Then:
+  - result->assertSucceeded() or result->assertFailedWith(code)
+  - thenStateShouldBe
+  - thenNotificationSent or thenNotificationNotSent
+  - thenPlayerNotifiedWith when target-specific behavior matters
+  - thenDatabaseHas or thenDatabaseCount
+
+Use these scenario templates from the sample tests:
+
+- happy path
+- invalid input with explicit error code
+- wrong player acting
+- endgame transition condition
+- pure logic function test with direct assertions
+
+Keep the CC PATTERN comment style in generated example-heavy tests because it is intentional teaching content.
+
+## 6) Testing - What Can and Cannot Be Tested
+Can test locally with this harness:
+
+- server action validation
+- state transitions
+- DB writes/reads
+- notification emission and payload subsets
+- pure gameplay logic methods
+
+Cannot test with this harness alone:
+
+- Studio rendering behavior
+- animation timing in live client
+- real network transport behavior
+- full end-to-end Studio integration
+
+## 7) Sub-Skill References
+When work touches these topics, consult these files and follow their guidance:
+
+- State machine patterns: skills/state-machine.md
+- Database patterns: skills/database-patterns.md
+- JS Dojo patterns: skills/js-dojo-patterns.md
+- Notifications contract: skills/notifications.md
+- Scaffold templates: skills/scaffold-templates.md

package/composer.json

@@ -0,0 +1,13 @@
+{
+  "name": "your-handle/bga-dev-skill",
+  "description": "CC skill and testing harness for BoardGameArena game development",
+  "require-dev": {
+    "phpunit/phpunit": "^10.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "BgaHarness\\": "harness/php/",
+      "BgaExample\\": "harness/example/"
+    }
+  }
+}

package/harness/example/SampleGame.php

@@ -0,0 +1,160 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BgaExample;
+
+use BgaHarness\BgaStubs;
+
+class SampleGame extends BgaStubs
+{
+    public function __construct()
+    {
+        parent::__construct();
+
+        $this->_setAllowedActions([
+            'playerTurn' => ['action_playSet', 'action_pass'],
+        ]);
+
+        $this->_setTransitions([
+            'playerTurn' => [
+                'nextPlayer' => 'playerTurn',
+                'endGame' => 'endGame',
+            ],
+        ]);
+    }
+
+    public function setupNewGame(): void
+    {
+        $this->DbQuery(
+            "CREATE TABLE IF NOT EXISTS card (" .
+            "card_id INTEGER PRIMARY KEY, " .
+            "card_type TEXT, " .
+            "card_number INTEGER, " .
+            "card_shading TEXT, " .
+            "card_location TEXT, " .
+            "card_location_arg INTEGER)"
+        );
+
+        $existingCards = $this->getIntFromDB('SELECT COUNT(*) FROM card');
+        if ($existingCards === 0) {
+            $types = ['red', 'green', 'blue'];
+            $numbers = [1, 2, 3];
+            $shadings = ['solid', 'striped', 'open'];
+            $cardId = 1;
+
+            for ($i = 0; $i < 3; $i++) {
+                foreach ($types as $type) {
+                    foreach ($numbers as $number) {
+                        foreach ($shadings as $shading) {
+                            $this->DbQuery(sprintf(
+                                "INSERT INTO card (card_id, card_type, card_number, card_shading, card_location, card_location_arg) VALUES (%d, '%s', %d, '%s', 'deck', 0)",
+                                $cardId,
+                                $type,
+                                $number,
+                                $shading
+                            ));
+                            $cardId++;
+                        }
+                    }
+                }
+            }
+        }
+
+        $players = $this->getCollectionFromDB('SELECT player_id FROM player');
+        foreach ($players as $player) {
+            $playerId = (int) ($player['player_id'] ?? 0);
+            if ($playerId <= 0) {
+                continue;
+            }
+
+            $cardsToDeal = $this->getCollectionFromDB('SELECT card_id FROM card WHERE card_location = "deck" ORDER BY card_id LIMIT 3');
+            foreach ($cardsToDeal as $card) {
+                $this->DbQuery(sprintf(
+                    "UPDATE card SET card_location = 'hand', card_location_arg = %d WHERE card_id = %d",
+                    $playerId,
+                    (int) $card['card_id']
+                ));
+            }
+        }
+
+        $this->_setState('playerTurn');
+        $this->_setGameStateValue('cards_remaining', $this->getIntFromDB("SELECT COUNT(*) FROM card WHERE card_location = 'deck'"));
+    }
+
+    public function action_playSet(array $cardIds): void
+    {
+        $this->checkAction('action_playSet');
+
+        if (count($cardIds) !== 3) {
+            $this->throwUserError('invalidSet');
+        }
+
+        $cards = [];
+        foreach ($cardIds as $cardId) {
+            $row = $this->getObjectFromDB('SELECT * FROM card WHERE card_id = ' . (int) $cardId);
+            if ($row === null) {
+                $this->throwUserError('invalidSet');
+            }
+            $cards[] = [
+                'type' => (string) ($row['card_type'] ?? ''),
+                'number' => (int) ($row['card_number'] ?? 1),
+                'shading' => (string) ($row['card_shading'] ?? 'solid'),
+            ];
+        }
+
+        if (!$this->_checkValidSet($cards)) {
+            $this->throwUserError('invalidSet');
+        }
+
+        $this->_scoreSet($this->getActivePlayerId(), $cardIds);
+
+        $remaining = $this->incGameStateValue('cards_remaining', -3);
+        if ($remaining <= 0) {
+            $this->gamestate_nextState('endGame');
+
+            return;
+        }
+
+        $this->gamestate_nextState('nextPlayer');
+    }
+
+    public function action_pass(): void
+    {
+        $this->checkAction('action_pass');
+        $this->notifyAllPlayers('playerPassed', '', ['player_id' => $this->getActivePlayerId()]);
+        $this->gamestate_nextState('nextPlayer');
+    }
+
+    public function _checkValidSet(array $cards): bool
+    {
+        if (count($cards) !== 3) {
+            return false;
+        }
+
+        foreach (['type', 'number', 'shading'] as $field) {
+            $values = array_map(static fn (array $card): mixed => $card[$field] ?? null, $cards);
+            $unique = count(array_unique($values));
+            if ($unique !== 1 && $unique !== 3) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    public function _scoreSet(int $playerId, array $cards): void
+    {
+        $this->DbQuery('UPDATE player SET player_score = player_score + 1 WHERE player_id = ' . $playerId);
+        foreach ($cards as $cardId) {
+            $this->DbQuery("UPDATE card SET card_location = 'discard' WHERE card_id = " . (int) $cardId);
+        }
+
+        $score = (int) $this->getUniqueValueFromDB('SELECT player_score FROM player WHERE player_id = ' . $playerId);
+        $this->notifyAllPlayers('setPlayed', '', [
+            'player_id' => $playerId,
+            'score' => $score,
+            'card_ids' => $cards,
+        ]);
+    }
+}

package/harness/example/SampleGameTest.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BgaExample;
+
+use BgaHarness\BgaGameTestCase;
+use BgaHarness\BgaStubs;
+
+class SampleGameTest extends BgaGameTestCase
+{
+    protected function createGame(): BgaStubs
+    {
+        $game = new SampleGame();
+        $game->_setState('playerTurn');
+        $game->_setGameStateValue('cards_remaining', 12);
+        $game->_getDb()->seedTable('player', [
+            ['player_id' => 1, 'player_name' => 'Alice', 'player_score' => 0],
+            ['player_id' => 2, 'player_name' => 'Bob', 'player_score' => 0],
+        ]);
+
+        return $game;
+    }
+
+    public function test_valid_set_scores_and_advances_state(): void
+    {
+        // CC PATTERN: happy path — given setup -> when action -> then state + notification
+        $this->givenActivePlayer(1)
+            ->givenState('playerTurn')
+            ->givenDatabaseRows('card', [
+                ['card_id' => 1, 'card_type' => 'red', 'card_number' => 1, 'card_shading' => 'solid', 'card_location' => 'hand', 'card_location_arg' => 1],
+                ['card_id' => 2, 'card_type' => 'green', 'card_number' => 2, 'card_shading' => 'striped', 'card_location' => 'hand', 'card_location_arg' => 1],
+                ['card_id' => 3, 'card_type' => 'blue', 'card_number' => 3, 'card_shading' => 'open', 'card_location' => 'hand', 'card_location_arg' => 1],
+            ]);
+
+        $result = $this->whenAction('action_playSet', ['card_ids' => [1, 2, 3]]);
+
+        $result->assertSucceeded();
+        $this->thenNotificationSent('setPlayed', ['player_id' => 1, 'score' => 1]);
+        $this->thenDatabaseHas('card', ['card_location' => 'discard', 'card_id' => 1]);
+        $this->thenStateShouldBe('playerTurn');
+    }
+
+    public function test_invalid_set_rejected_with_error(): void
+    {
+        // CC PATTERN: invalid action — assert specific BGA error code thrown
+        $this->givenActivePlayer(1)
+            ->givenState('playerTurn')
+            ->givenDatabaseRows('card', [
+                ['card_id' => 1, 'card_type' => 'red', 'card_number' => 1, 'card_shading' => 'solid'],
+                ['card_id' => 2, 'card_type' => 'red', 'card_number' => 2, 'card_shading' => 'striped'],
+                ['card_id' => 3, 'card_type' => 'blue', 'card_number' => 3, 'card_shading' => 'open'],
+            ]);
+
+        $result = $this->whenAction('action_playSet', ['card_ids' => [1, 2, 3]]);
+
+        $result->assertFailedWith('invalidSet');
+        $this->thenNotificationNotSent('setPlayed');
+        $this->thenStateShouldBe('playerTurn');
+    }
+
+    public function test_inactive_player_cannot_play(): void
+    {
+        // CC PATTERN: wrong actor — checkAction should block this
+        $this->givenActivePlayer(1)
+            ->givenCurrentPlayer(2)
+            ->givenState('playerTurn');
+
+        $result = $this->whenAction('action_playSet', ['card_ids' => [4, 5, 6]]);
+
+        $result->assertFailedWith('notYourTurn');
+    }
+
+    public function test_last_set_triggers_endgame(): void
+    {
+        // CC PATTERN: state transition — verify the right transition fires
+        $this->givenGameStateValue('cards_remaining', 3)
+            ->givenActivePlayer(1)
+            ->givenDatabaseRows('card', [
+                ['card_id' => 1, 'card_type' => 'red', 'card_number' => 1, 'card_shading' => 'solid', 'card_location' => 'hand', 'card_location_arg' => 1],
+                ['card_id' => 2, 'card_type' => 'green', 'card_number' => 2, 'card_shading' => 'striped', 'card_location' => 'hand', 'card_location_arg' => 1],
+                ['card_id' => 3, 'card_type' => 'blue', 'card_number' => 3, 'card_shading' => 'open', 'card_location' => 'hand', 'card_location_arg' => 1],
+            ]);
+
+        $this->whenAction('action_playSet', ['card_ids' => [1, 2, 3]]);
+
+        $this->thenStateShouldBe('endGame');
+    }
+
+    public function test_set_validation_logic(): void
+    {
+        // CC PATTERN: pure function — no given/when/then needed, just call directly
+        $validSet = [
+            ['type' => 'red', 'number' => 1, 'shading' => 'solid'],
+            ['type' => 'green', 'number' => 2, 'shading' => 'striped'],
+            ['type' => 'blue', 'number' => 3, 'shading' => 'open'],
+        ];
+        $this->assertTrue($this->game->_checkValidSet($validSet));
+
+        $invalidSet = $validSet;
+        $invalidSet[2]['type'] = 'red';
+        $this->assertFalse($this->game->_checkValidSet($invalidSet));
+    }
+}

package/harness/example/sampleUtils.test.js

@@ -0,0 +1,53 @@
+const { isValidSet, calculateScore, getLegalMoves } = require('../../src/setgame.utils.js');
+
+describe('isValidSet', () => {
+  test('all same color is valid', () => {
+    const cards = [
+      { color: 'red', number: 1, shading: 'solid' },
+      { color: 'red', number: 2, shading: 'striped' },
+      { color: 'red', number: 3, shading: 'open' }
+    ];
+    expect(isValidSet(cards)).toBe(true);
+  });
+
+  test('all different colors is valid', () => {
+    const cards = [
+      { color: 'red', number: 1, shading: 'solid' },
+      { color: 'green', number: 2, shading: 'striped' },
+      { color: 'blue', number: 3, shading: 'open' }
+    ];
+    expect(isValidSet(cards)).toBe(true);
+  });
+
+  test('two same one different is invalid', () => {
+    const cards = [
+      { color: 'red', number: 1, shading: 'solid' },
+      { color: 'red', number: 2, shading: 'striped' },
+      { color: 'blue', number: 3, shading: 'open' }
+    ];
+    expect(isValidSet(cards)).toBe(false);
+  });
+});
+
+describe('calculateScore', () => {
+  test('base score for standard set', () => {
+    expect(calculateScore(1, 0)).toBe(1);
+  });
+
+  test('bonus multiplier for 3-in-a-row', () => {
+    expect(calculateScore(2, 3)).toBe(4);
+  });
+});
+
+describe('getLegalMoves', () => {
+  test('finds at least one legal set', () => {
+    const cards = [
+      { color: 'red', number: 1, shading: 'solid' },
+      { color: 'green', number: 2, shading: 'striped' },
+      { color: 'blue', number: 3, shading: 'open' },
+      { color: 'red', number: 1, shading: 'solid' }
+    ];
+
+    expect(getLegalMoves(cards).length).toBeGreaterThan(0);
+  });
+});

package/harness/js/bgaStubs.js

@@ -0,0 +1,32 @@
+global.dojo = {
+  place: jest.fn(),
+  query: jest.fn(() => ({ forEach: jest.fn(), length: 0 })),
+  style: jest.fn(),
+  addClass: jest.fn(),
+  removeClass: jest.fn(),
+  connect: jest.fn(),
+  on: jest.fn(),
+  animateProperty: jest.fn(() => ({ play: jest.fn() })),
+  require: jest.fn()
+};
+
+global.gameui = {
+  player_id: 1,
+  gamedatas: {},
+  addTooltip: jest.fn(),
+  ajaxcall: jest.fn(),
+  showMessage: jest.fn()
+};
+
+const notificationHandlers = {};
+
+global.bgaNotification = {
+  register: (type, handler) => {
+    notificationHandlers[type] = handler;
+  },
+  trigger: (type, args) => {
+    if (notificationHandlers[type]) {
+      notificationHandlers[type]({ args });
+    }
+  }
+};

package/harness/js/testHelpers.js

@@ -0,0 +1,9 @@
+function expectSubset(actual, subset) {
+  for (const [key, value] of Object.entries(subset)) {
+    expect(actual[key]).toEqual(value);
+  }
+}
+
+module.exports = {
+  expectSubset
+};