bga-dev-skill 0.1.0

package/harness/php/BgaStubs.php

@@ -0,0 +1,244 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BgaHarness;
+
+require_once __DIR__ . '/BgaExceptionTypes.php';
+
+abstract class BgaStubs
+{
+    protected BgaDatabaseFake $db;
+    protected BgaNotificationSpy $notifications;
+
+    private int $activePlayerId = 0;
+    private int $currentPlayerId = 0;
+    private array $players = [];
+    private string $currentState = 'gameSetup';
+    private array $gameStateValues = [];
+    private array $allowedActions = [];
+    private array $transitionMap = [];
+    private array $multiactivePlayers = [];
+
+    public function __construct()
+    {
+        $this->db = new BgaDatabaseFake();
+        $this->notifications = new BgaNotificationSpy();
+    }
+
+    protected function getActivePlayerId(): int
+    {
+        return $this->activePlayerId;
+    }
+
+    protected function getActivePlayerName(): string
+    {
+        return $this->getPlayerNameById($this->activePlayerId);
+    }
+
+    protected function getPlayerNameById(int $playerId): string
+    {
+        return $this->players[$playerId]['player_name'] ?? 'Unknown';
+    }
+
+    protected function getCurrentPlayerId(): int
+    {
+        return $this->currentPlayerId;
+    }
+
+    protected function gamestate_nextState(string $transition): void
+    {
+        if (isset($this->transitionMap[$this->currentState][$transition])) {
+            $this->currentState = $this->transitionMap[$this->currentState][$transition];
+        }
+    }
+
+    protected function gamestate_changeActivePlayer(int $playerId): void
+    {
+        $this->activePlayerId = $playerId;
+        $this->currentPlayerId = $playerId;
+    }
+
+    protected function gamestate_setAllPlayersMultiactive(): void
+    {
+        $this->multiactivePlayers = array_keys($this->players);
+    }
+
+    protected function gamestate_setPlayerNonMultiactive(int $playerId, string $nextState): void
+    {
+        $this->multiactivePlayers = array_values(
+            array_filter(
+                $this->multiactivePlayers,
+                static fn (int $id): bool => $id !== $playerId
+            )
+        );
+
+        if ($this->multiactivePlayers === []) {
+            $this->currentState = $nextState;
+        }
+    }
+
+    protected function checkAction(string $actionName): bool
+    {
+        if ($this->currentPlayerId !== $this->activePlayerId) {
+            $this->throwUserError('notYourTurn');
+        }
+
+        $allowed = $this->allowedActions[$this->currentState] ?? [];
+        if ($allowed !== [] && !in_array($actionName, $allowed, true)) {
+            $this->throwUserError('actionNotAllowed');
+        }
+
+        return true;
+    }
+
+    protected function DbQuery(string $sql): void
+    {
+        $this->db->DbQuery($sql);
+    }
+
+    protected function getCollectionFromDB(string $sql, bool $bUniqueValue = false): array
+    {
+        return $this->db->getCollectionFromDB($sql, $bUniqueValue);
+    }
+
+    protected function getObjectFromDB(string $sql): ?array
+    {
+        return $this->db->getObjectFromDB($sql);
+    }
+
+    protected function getUniqueValueFromDB(string $sql): mixed
+    {
+        return $this->db->getUniqueValueFromDB($sql);
+    }
+
+    protected function getIntFromDB(string $sql): int
+    {
+        return $this->db->getIntFromDB($sql);
+    }
+
+    protected function notifyAllPlayers(string $type, string $msg, array $data): void
+    {
+        $this->notifications->notifyAllPlayers($type, $msg, $data);
+    }
+
+    protected function notifyPlayer(int $id, string $type, string $msg, array $data): void
+    {
+        $this->notifications->notifyPlayer($id, $type, $msg, $data);
+    }
+
+    protected function getGameStateValue(string $name): int
+    {
+        return (int) ($this->gameStateValues[$name] ?? 0);
+    }
+
+    protected function setGameStateValue(string $name, int $value): void
+    {
+        $this->gameStateValues[$name] = $value;
+    }
+
+    protected function incGameStateValue(string $name, int $increment): int
+    {
+        $next = $this->getGameStateValue($name) + $increment;
+        $this->setGameStateValue($name, $next);
+
+        return $next;
+    }
+
+    protected function createDeck(string $deckId): BgaDeckStub
+    {
+        return new BgaDeckStub($deckId);
+    }
+
+    protected function throwUserError(string $errorCode): never
+    {
+        throw new BgaUserException($errorCode);
+    }
+
+    protected function throwVisibleSystemError(string $message): never
+    {
+        throw new BgaVisibleSystemException($message);
+    }
+
+    public function _setActivePlayer(int $playerId): void
+    {
+        $this->activePlayerId = $playerId;
+    }
+
+    public function _setCurrentPlayer(int $playerId): void
+    {
+        $this->currentPlayerId = $playerId;
+    }
+
+    public function _setPlayers(array $players): void
+    {
+        $this->players = $players;
+        $this->multiactivePlayers = [];
+        if ($this->activePlayerId === 0 && $players !== []) {
+            $first = (int) array_key_first($players);
+            $this->activePlayerId = $first;
+            $this->currentPlayerId = $first;
+        }
+    }
+
+    public function _setState(string $stateName): void
+    {
+        $this->currentState = $stateName;
+    }
+
+    public function _setAllowedActions(array $byState): void
+    {
+        $this->allowedActions = $byState;
+    }
+
+    public function _setTransitions(array $map): void
+    {
+        $this->transitionMap = $map;
+    }
+
+    public function _setGameStateValue(string $name, int $value): void
+    {
+        $this->setGameStateValue($name, $value);
+    }
+
+    public function _getState(): string
+    {
+        return $this->currentState;
+    }
+
+    public function _getDb(): BgaDatabaseFake
+    {
+        return $this->db;
+    }
+
+    public function _getNotifications(): BgaNotificationSpy
+    {
+        return $this->notifications;
+    }
+}
+
+class BgaDeckStub
+{
+    private string $deckId;
+    private array $cards = [];
+
+    public function __construct(string $deckId)
+    {
+        $this->deckId = $deckId;
+    }
+
+    public function addCard(array $card): void
+    {
+        $this->cards[] = $card;
+    }
+
+    public function count(): int
+    {
+        return count($this->cards);
+    }
+
+    public function getDeckId(): string
+    {
+        return $this->deckId;
+    }
+}

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  testEnvironment: 'node',
+  setupFiles: ['./harness/js/bgaStubs.js'],
+  testMatch: ['**/*.test.js']
+};

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "bga-dev-skill",
+  "version": "0.1.0",
+  "private": false,
+  "scripts": {
+    "test": "jest"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  }
+}

package/skills/database-patterns.md

@@ -0,0 +1,143 @@
+# Database Patterns
+
+Use only the database vocabulary implemented in the harness. Do not use raw PDO in game classes.
+
+## Method Vocabulary
+
+Use these methods exactly:
+
+- `DbQuery(string $sql): void`
+- `getCollectionFromDB(string $sql, bool $bUniqueValue = false): array`
+- `getObjectFromDB(string $sql): ?array`
+- `getUniqueValueFromDB(string $sql): mixed`
+- `getIntFromDB(string $sql): int`
+
+## Pattern: Write with DbQuery
+
+Use `DbQuery` for INSERT/UPDATE/DELETE and DDL.
+
+```php
+$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)"
+);
+```
+
+```php
+$this->DbQuery("UPDATE card SET card_location = 'discard' WHERE card_id = " . (int) $cardId);
+```
+
+## Pattern: Read many rows
+
+Use `getCollectionFromDB` for list queries.
+
+```php
+$cards = $this->getCollectionFromDB(
+    "SELECT card_id, card_type, card_number, card_shading FROM card WHERE card_location = 'deck' ORDER BY card_id LIMIT 3"
+);
+```
+
+If you need key => value shape and query returns two columns, use `bUniqueValue = true`.
+
+```php
+$counts = $this->getCollectionFromDB(
+    "SELECT card_location_arg, COUNT(*) FROM card WHERE card_location = 'hand' GROUP BY card_location_arg",
+    true
+);
+```
+
+## Pattern: Read one row
+
+Use `getObjectFromDB` when one row is expected.
+
+```php
+$row = $this->getObjectFromDB('SELECT * FROM card WHERE card_id = ' . (int) $cardId);
+if ($row === null) {
+    $this->throwUserError('invalidSet');
+}
+```
+
+## Pattern: Read one scalar
+
+Use `getUniqueValueFromDB` for scalar values and cast explicitly when needed.
+
+```php
+$score = (int) $this->getUniqueValueFromDB('SELECT player_score FROM player WHERE player_id = ' . $playerId);
+```
+
+Use `getIntFromDB` for count/int-only reads.
+
+```php
+$remaining = $this->getIntFromDB("SELECT COUNT(*) FROM card WHERE card_location = 'deck'");
+```
+
+## Pattern: Dealing cards from deck to hand
+
+```php
+$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']
+    ));
+}
+```
+
+## Deck Component Methods (Harness)
+
+In this harness, deck usage is intentionally minimal:
+
+- `createDeck(string $deckId): BgaDeckStub`
+- `BgaDeckStub::addCard(array $card): void`
+- `BgaDeckStub::count(): int`
+- `BgaDeckStub::getDeckId(): string`
+
+Use this stub only for in-memory deck behavior in tests or simplified examples.
+
+## Numeric Cast Pattern
+
+DB values can arrive as strings. Cast numeric fields before arithmetic/comparison.
+
+```php
+$players = $this->getCollectionFromDB("SELECT player_id id, player_score score FROM player");
+foreach ($players as $id => $player) {
+    foreach ($player as $key => $value) {
+        if (preg_match('/^-?\\d+$/', (string) $value)) {
+            $players[$id][$key] = (int) $value;
+        }
+    }
+}
+```
+
+## SQL Injection Warning
+
+Never concatenate unsanitized user input into SQL strings.
+
+Rules:
+- Cast numeric IDs with `(int)` before interpolation.
+- Validate string inputs against a known allow-list before interpolation.
+- If a freeform string must be interpolated, sanitize first (`addslashes`) and document why.
+
+Bad:
+
+```php
+$this->getCollectionFromDB("SELECT * FROM card WHERE card_type = '$type'");
+```
+
+Good:
+
+```php
+if (!in_array($type, ['red', 'green', 'blue'], true)) {
+    $this->throwUserError('invalidType');
+}
+$this->getCollectionFromDB("SELECT * FROM card WHERE card_type = '$type'");
+```

package/skills/js-dojo-patterns.md

@@ -0,0 +1,89 @@
+# JS Patterns
+
+Use this file as direct coding instructions for frontend behavior. The harness includes test stubs for legacy globals (`dojo`, `gameui`), while real modern projects can use `bga.*` APIs.
+
+## What Is Implemented in This Repo
+
+From harness files:
+
+- `harness/js/bgaStubs.js` provides test doubles for:
+  - `dojo.*`
+  - `gameui.*`
+  - notification registration/triggering
+- `harness/example/sampleUtils.test.js` demonstrates Jest tests for pure utility functions.
+
+Use this to keep UI-independent logic testable.
+
+## Modern Game Class Pattern
+
+When targeting modern framework projects, generate:
+
+```javascript
+export class Game {
+  constructor(bga) {
+    this.bga = bga;
+    // bga.states.register('actionPlay', new PlayState(this, bga));
+  }
+
+  setup(gamedatas) {
+    this.gamedatas = gamedatas;
+    this.bga.notifications.setupPromiseNotifications();
+  }
+}
+```
+
+## State Handler Class Shape
+
+```javascript
+export class PlayState {
+  constructor(game, bga) {
+    this.game = game;
+    this.bga = bga;
+  }
+
+  onEnteringState(args, isCurrentPlayerActive) {}
+  onLeavingState() {}
+  onPlayerActivationChange(args, isCurrentPlayerActive) {}
+}
+```
+
+## Action Dispatch Pattern
+
+Use framework actions instead of ad-hoc network code:
+
+```javascript
+this.bga.actions.performAction('actPlaySet', { card_ids: [1, 2, 3] });
+```
+
+## Notifications Pattern
+
+- Call `bga.notifications.setupPromiseNotifications()` during setup.
+- Implement handlers as `async notif_*` when they include async UI work.
+
+```javascript
+async notif_setPlayed(args) {
+  // update local state
+  // await animation or delay if needed
+}
+```
+
+## Preferences Pattern
+
+Use `bga.userPreferences` for user settings in modern projects.
+
+```javascript
+const value = this.bga.userPreferences.get(prefId);
+this.bga.userPreferences.set(prefId, nextValue);
+```
+
+## Testability Rule
+
+Keep core gameplay calculations in pure utility functions and test with Jest.
+
+Pattern from repo:
+
+- `isValidSet(cards)`
+- `calculateScore(setCount, streak)`
+- `getLegalMoves(cards)`
+
+Write tests using deterministic input/output only; avoid DOM/network in unit tests.