JIRA.txt

## Cleanup Work
[ ] Get rid of front-end module, make it a single module project

[ ] Remove the idea of an "opponent", games can have anywhere from 1-6 players
[ ] (think) get rid of CardId?
[ ] Separate the Application layer from the Domain
    [ ] Move PORT to application
    [ ] Split out card shuffle (RandomCardShuffler) into PORT and ADAPTER
    [ ] Pull in ArchUnit

## Game Layout

Per Game:
* TILEs
* ACTION CARD DECK
* ACTION CARD DISCARD PILE
* TEST RESULTS DECK
* TEST RESULTS DISCARD PILE
* 6-SIDED DIE

Per Player:
* PAWN (indicates which TILE they're on)
* HAND
* PLAY AREA
* TECH NEGLECT AREA
* COMMIT TRACKER
* RISK TRACKER

Player's "State Machine":
    Player's "TURN" is complete when either: play/discard 3 cards OR explicitly END TURN

## Board Layout

1. One large images vs. individual Hex Tiles: leaning towards individual tiles, easier to determine pawn placement and more flexible

### Hex Tiles

Workspace1: belongs to a single player, or group of players

exit(Workspace1): moves pawn from Tile 1 to Tile 2
exit(Workspace1): moves pawn from Tile 2 to Tile 3
exit(Workspace1): moves pawn from Tile 3 to Tile 4
skip(Workspace1): moves pawn from tile 4 to Tile 7

Ensemble Mode:   Player <4:1> Workspace <1..4:1> Tile
Pairing Mode:    Player <2:1> Workspace <1..4:1> Tile
Individual Mode: Player <1:1> Workspace <1..4:1> Tile

Board has Map<WorkspaceId, BoardTile>, BoardTile is an Enum? Record? There are two "types" of tiles: those with Exit-Only and those with Exit+Skip

?? Do we want a reverse multi-map? <BoardTile, List<WorkspaceId>>

Exit: via Discard, play Write Code card, or Successful Prediction
Skip: Tile has "canSkip()" query and throws exception if "skip()" for tile that can't be skipped. Otherwise skip() associates the new Tile with the Player

### Pawns

* Associate players with their pawns via colors (except when in Ensemble Game Mode, then use a separate color?

    ?? In Ensemble Mode: Does the pawn retain its own color, or does it take on the color of the current "Driver" (player whose turn it is)

* Turn indicator

* ?? Where to place pawn tokens on each hex tile: define 4 locations where pawns can appear

* [Later] Tap/click on item (hex tile or card) to zoom in

* Player-Pawn is 1:1, except when playing as a group/cooperative game ("Ensemble Game Mode")

## Need

[ ] Structure for the BOARD as 9 separate TILEs,
    [ ] PLAYER is ON a TILE (has a game state machine)
    [ ] player's COMMAND causes change, potentially transition to new TILE
        [ ] MOVE PAWN - moves the player to a new tile
        [ ] DRAW CARD (and DRAW FULL)
        [ ] DISCARD CARD (often causes a transition)
        [ ] PLAY CARD
        [ ] END TURN

## Ubiquitous Language
* Game (deck, card, tile, etc.)
    * Competitive: every member for themselves (1:1 player:pawn)
    * Co-op (mob programming): working together to move pawn forward (N:1 player:pawn)
* Player - ties an Account/Member to a specific game ("player in game")
* Host - part of a Team, they created an instance of a game
* Team - which is an "account-based" thing: who can "see" each other's games and join
* Group - set of players currently playing a specific game (they have all JOINed a specific GAME or are members of the game)
    * one/many PAWN <-> one/many PLAYER (premature)
    * Support variation where GROUP controls single PAWN
* Coach - can observe the game without playing, can control/manipulate game elements
    * "Attached" to one or more TEAMs
* Win Condition (when is the game over)
    * First to 5 commits (or 3 commits, whatever)
    * Timeboxed: most commits within a period of time (duration)
* Game Master view: can see state of game(s) that have been created/in-progress
    * Admin version of this allows manipulation of elements for any reason (not sure if this is different from coach role)
    * Admin can see any game any time
    * Coach can only see games for the TEAMs to which they're attached


## Behavior

1. Host Creates Game (defines competitive or co-op)
2. Player Joins (existing) Game
     * Invited by host, or
     * Chooses available game from team/group
     * If Host wants to play, they have to join too
3. Start Game
    * Decks are shuffled
    * Cards are dealt: 5 to each Player
    * Pawns placed at first TILE
    * Commit tracker set to 0
    * Risk tracker set to 0/0
    * Starting player chosen (proceeds clockwise)
4. Player 1 plays...

## Interaction

[X] 1. Ask for name for new game (start with competitive)
[X] 2. Create game -> provide identifier/link (handle)
[X] 3. Member joins game with human-readable "Handle" (via typing it in, not link)
        [X] Member becomes Player when joined the game
        [X] Multiple different Members can join the same game
        [X] Constraint: A Member can not join the same game twice, i.e., can't represent TWO Players
            * If a Member joins a game where they are already a player, that is "rejoining" (reconnecting)
        [X] Constraint: 4 players maximum per game (rejoins don't count, of course)
[ ] 4. Waiting for game to start (once at least 1 member has joined the game)
    [X] Receive notification when additional players are added
    [ ] Can only start game at this point by calling .start()
[ ] 5. "start game" is Triggered
    [ ] Add guard to ensure game can't be started unless at least 1 player has joined
    [ ] Action Card deck shuffled, 5 cards dealt to each Player, etc.
        [X] Create ActionCard, Deck container, able to draw and replenish from discard
        [X] Nullable-ize the Deck with Embedded Stub for configuring response to "give me shuffled deck"
        [X] Player draws to full hand from Action Card deck as part of start game
            [X] 5 events generated: 1 for each of 5 cards drawn
            [X] State of player's Hand: has 5 cards

        [X] Deck event-sourcing
            [X] Draw (with no replenish) generates events
            [X] Draw event projects state change in Deck
            [X] Replenish generates events
            [X] Applying replenish to deck

        [X] Player discards card, which adds to Discard Pile

        [ ] Display the hex board with pawns for each player

    [X] The association of Member (and their logged-in username) vs. the Player's name in the context of a Game needs to be resolved. When we're sending Player-tailored HTML, we need to know: for which `Player` we're generating the HTML (we know this because we iterate through all Players from the Game, i.e., game.players()), and THEN, we need to send that HTML to the correct WebSocketSession, which has to be associated (mapped) with the Game + PlayerId.

        [X] PlayerConnections needs to have a sendTo(GameId, PlayerId, HTML): the Game that the Player is in, used to identify the target websocket to which we send the customized HTML

        When we get a connection through the WebSocketInboundHandler, we need to know which game this is from (we get this via the "join:gameHandle" message), and we ALSO NEED the PlayerId (we get this via the security principal's name)

        [X] PlayerConnector will collaborate with the new ForTrackingPlayerMessageSenders Port interface (which is implemented by the MessageSendersForPlayers class)

        [ ] Start Game starts the game:
            [X] The modal goes away (via broadcasting `hx-swap-oob="delete"`)
            [ ] If the game is not already started, call .start() (and persist this state change)
                [ ] Implement this from the GameTest
            [X] Broadcast Players' cards (WebSocketBroadcaster.gameUpdate)
                [X] Player has cards in the "Your Hand" area
                [X] Deal cards to all players
                [X] Shuffle the ActionCardDeck
                [X] Show other players' cards in their areas:
                    [X] Update game.html to only have the <div class="all-other-players-container">, which will be empty, and filled in only once the game starts
                        (This is because when the game.html loads, we don't yet know how many players are in the game)
                    [X] In WebSocketBroadcaster, when we do a gameUpdate(), send the same "other players' cards" HTML content to everyone

                [X] Convert PlayerViewComponentTest to be structural instead of raw string comparisons

                [X] Display cards in "Your Hand" as Images instead of words
                [X] Display cards in Other Players' hands as Images instead of words


            [ ] HTML element hierarchy cleanup
                [ ] Stop using Text HtmlComponent for H2 and other tags, by creating a generic HtmlTag component, and then escape the text
                [ ] Move childComponents down to NormalElement (only NormalElement can have children)

            [ ] Popup menu for Card actions
                [X] Generalize NormalElement to accept arbitrary list of HtmlAttributes
                [X] Change "your hand" cards from DIV to BUTTON
                [X] Add htmx support to hand BUTTON:
                         hx-get="/game/{game handle}/card-menu/{card name}"
                         hx-on::after-settle="document.querySelector('dialog').showModal()"
                         hx-swap="none"
                [X] Implement GET request that returns HTMX:
                    @GetMapping("/game/{gameHandle}/card-menu/{cardName}")
                    @ResponseBody
                   """
                   <swap hx-swap-oob="innerHTML" id="dialog">
                       <div>
                           <button autofocus
                                hx-post="/game/%s/cards/play/%s"
                                hx-on::before-request="document.querySelector('dialog').close()">
                               Play Card into Workspace
                           </button>
                       </div>
                       <div>
                           <button hx-post="/game/%s/cards/discard/%s"
                                 hx-on::before-request="document.querySelector('dialog').close()">
                               Discard Card to Discard Pile
                           </button>
                       </div>
                   </swap>
                   """.formatted(gameHandle, cardName, gameHandle, cardName);

                [X] Implement POST request to handle DISCARD command
                    [X] Create POST endpoint
                    [X] Wire the endpoint to the Use Case command
                    [X] Broadcast updated hand view now that the card has been discarded

                [X] Display Action Card deck draw and discard piles
                    [X] HTML+CSS for the draw/discard piles
                    [X] Broadcast deck state changes to everyone
                        [X] DRAW PILE: Display a back of card if it's not empty
                            <swap id="action-card-draw-pile"> <img src="/action-card-back.png"> </swap>
                        [X] DISCARD PILE: Display most recently discarded card if it's not empty
                            <swap id="action-card-discard-pile"> <img src=discarded card> </swap>
                        [X] If either pile is empty, the <swap> will be empty

            [X] Refreshing the page should trigger a refresh of the state from the back-end
                [X] Should happen upon the Websocket's "handleMessage" "connect" command
            [X] Kick user back to the lobby if they have a stale game page

            [ ] Handle pawn placement
                [X] Figure out how to display pawn in/on correct tile
                    [ ] Pawn Icon: Use hexagon with player's number inside, or allow player to pick a "pawn" from a set of icons
                [X] At start of game, set all pawns to first hex tile via the Workspace
                    [X] in Game#createPlayer(), create a Workspace and pass it into the Player's constructor (Workspace's ID matches the Player's ID--until we get to Workspace sharing)
                    [X] In Workspace constructor, assign the WhatShouldItDo[HexTile] to its currentHexTile field
                [X] Render Workspace: for each workspace:
                    [X] Delete (any existing) pawn: swap="delete" for id="workspace1-pawn" (or whatever the workspace ID is)
                    [X] Render the pawn on the currentHexTile (e.g., id="what-should-it-do-hex-tile"), do a swap with "beforeend"
                    [X] Render using the "real" Workspace object instead of faking it with Player's ID

                [X] Discard card causes Pawn to move

            [X] Implement POST request to handle PLAY card command
                [X] Create "play" endpoint
                [X] Implement the PLAY command
                [X] Show played cards in the Workspace for "You"
                    Player has "In-Play" area (for WRITE CODE, LESS CODE, PREDICT)
                [X] Show played card in Workspace for "other players"

            [ ] Draw Action Card from the deck's draw pile: Player clicks on Draw Pile to initiate DRAW CARD action
                [X] POST handler for DRAW CARD from ACTION CARD DRAW PILE: player (via Principal) and game (via Game Handle)
                [X] Implement Use Case for Draw Action Card via test-driving PlayingGameControllerTest, and then GamePlay
                [X] If Player draws a "tech neglect" card, move it to Tech Neglect area (with a new PlayerEvent)
                    [X] Generates correct event(s)
                    [X] Updates state from event(s)
                    [X] When the Game starts, all Player Hands must have 5 cards: if they drew a Tech Neglect card, that gets placed into the Workspace, and the Player must get more cards until their hand is full
                [X] Display "Tech Neglect" cards in the Workspace's Tech Neglect area for YOU
                [X] Display Other Players' "Tech Neglect" cards in their workspace views

    [ ] Predict with Test Results Cards Feature
        [ ] Make Deck handle all Cards: ActionCard and TestResultsCard
            [X] Generalize code in Deck to use Card instead of ActionCard
                [X] Generalize Card events
            [X] Create TestResultCard enums
            [X] Write some TestResultsDeck tests

WE ARE HERE ===>>

            [ ] Render the Test Result deck's draw and discard piles
        [ ] (start implementing the sequence diagram)
            [ ] Refactor HexTile from enums to classes with state
                [ ] Base class for similar tile behaviors
                    [ ] Composite for behaviors, since some tiles have "skip to exit" AND "predict to exit" while others just have "predict to exit", and "skip" can be combined with "WRITE CODE card to exit"


            [ ] Change the way we configure the Action Card deck so that instead of hacking the cards via the Shuffler, provide a way to specify the cards that go into the Discard Pile along with an "identity" shuffler that moves them to the Draw Pile in a predictable way

            [ ] Create Workspace Scoring+Risk display
                [ ] Track Risk added when Player uses the "escape hatch"
                    [ ] How does Player indicate they want to skip and take on risk? Probably click on your pawn and choose option.
                [ ] Evaluate risk level, die roll, etc., to determine if the player's commit succeeded
                [ ] Increment Commit counter once past last tile

            [ ] Remove Tailwind

            [X] Handle WebSocket disconnect
            [X] Handle reconnection and re-joining of the game

            [ ] When player disconnects, show the "disconnected" overlay on that player's container
                [ ] Show a "toast" message when they disconnect
                [ ] Show a toast when they're reconnected
                [ ] Show a "connected" status indicator in the player's container

            [ ] HtmlElement.Forest currently indents its children, but it shouldn't as the Forest isn't really a container element

            [ ] Replace List<HtmlAttribute> with HtmlAttributes that can render itself (fixes Primitive [Collection] Obsession)
                e.g.: HtmlAttributes.id(targetId).hxSwap("afterbegin")

            [ ] Split the Broadcaster interface into two:
                (1) All events before the game has started (e.g., announce player joined)
                (2) All events while the game is being played
                [ ] Maybe split further into: events during START vs. events while game is being played, or put the "clear modal" into the pre-start game interface

    [ ] (Temporary) Constraint: players can't join once game is started

# Nice-To-Have (Not Required for Minimum-Lovable Game)

    [ ] Card menu should reflect current legal actions
        [ ] Only show PLAY option when available, which depends on:
            * The card you selected AND:
                * The Hex Tile you're on (e.g., can't play WRITE CODE when on "Predict Test Will Fail to Compile", nor "REFACTOR" when on a non-Green tile)
                * Cards already played in the Workspace

    [ ] Draw pile card button displays message if Player can't draw a card because their hand is already full
        [ ] Nice to have: it's not the player's turn, or the player isn't at the end of their turn

    [ ] Show Player Turn indicators
        [ ] Highlight player in some way: for other players, change the other player area background color and scale their pawn and add a "thinking emoji" (h/t basebleem)
        [ ] For your turn, show a dismissible modal "Your Turn"


# Refactoring/Design Changes

    [ ] Add clearFreshEvents() to EventSourcedAggregate, but ensure that ArchUnit test exists to enforce that only tests can call that method

    [ ] Move the JSON annotations (@JsonCreator/@JsonValue) in ActionCard to a separate class (perhaps EventDto?)
        [ ] Check if we could then change the ActionCard parameter in PlayerDrewTechNeglectCard to the more specific TechNeglectCard

    [ ] Reorganize the ViewComponents to have a more direct relationship to where their contents appear on the page, e.g.:
        * WorkspaceViewComponent contains InPlayViewComponent, which contains CardViewComponents
            * Constructor might take list of Workspaces (instead of Players)?
        * HandViewComponent contains CardViewComponents
        * BoardViewComponent contains HexTileViewComponents, with PawnViewComponents
        * Pull all of these as children of a GameViewComponent
            --> this will let us create a "mini" test server for evaluating HTML layout and playing with HTMX OOB swaps
            --> moves us to a single source of truth for the HTML

    [ ] HexTiles to class hierarchy, that holds internal state machines for PREDICT, and share similar behavior for discard/play cards
        * WhatShouldItDo and HowDoYouKnowItDidIt have exactly the same behavior, only difference is their display title
        * WriteCodeForTest and WriteCodeSoTestCompiles both require the Write Code card to be played in order to exit to the next tile
            * Exit via "skip & add risk" are very similar, only differ on how much risk is added
        * PredictTest... tiles also have the same behavior, with an internal smaller state machine for determining what cards can be played and how to exit to next tile

    [ ] Test Data Builder for Game at both the Domain and Use Case layers
        [ ] Domain: create a game, easily push it to different (legal) states
        [X] Use Case: same as above, but uses a GameStore to persist

    [ ] Test Data Builder for Player, which can be "embedded" in the Game TDB
        [ ] Look at PlayerViewComponentTest

    [ ] Test Data Builder for Action Card Deck
        [ ] See PlayingGameControllerTest.writeCodeInWorkspaceWhenWriteCodeCardPlayedOnWriteCodeForTestTile

[X] Inbound HTTP Adapter
    [X] Host create game: numeric-only textbox and "Create Game" button does POST
        [X] MVC part
        [X] Test to make sure hostNewGame has Game created and stored
    [X] Lobby shows games available with handles for each
    [X] Person join game: textbox (for handle) and "Join Game" button does POST
        [X] MVC test for /join endpoint
        [X] PostMapping that does:
            [X] Creates Player in the Game for the Person
            [X] Redirects to page that shows the game page
    [X] Game-in-progress page: show "modal"
        [X] Show other players as they join -- via WebSockets (htmx)
            [X] Associate logged-in user (username?) with a MemberId for joining, by looking up that username in MemberStore
            [X] Get first name from the Player (their in-game name)

        [X] Show "Start Game" button (might have constraints on when this button shows up later)
            [X] Create standard action deck when starting the game


[ ] Outbound (Notifier) WebSocket Adapter
    [ ] Display name of game, all players, decks, pawns, etc.


## Event-Sourcing Game Persistence
>>> Commands -> Events -> State
[X] EventSourcedAggregate<GameEvent>
[X] Static method for creating initial game
[X] GameEvent interface, with subclasses for each event type
[X] Fix the Game.join() method to not return the Player, but instead provide method to obtain the Player based on the PersonId

    Using in-memory persistence for Game
    [X] Use case to use load (from Repository), modify, save (to Repository) pattern
    [X] GameStore in-memory implementation
        [X] Make it use the event-source storage model (so freshEvents is clear upon reconstitution, i.e., when findBy happens)

    [ ] GameViewLoader implementation using the GameRepository

    Real Database
    [ ] Truly unique ID for Game (instead of Game's "handle")
    [ ] Repository Adapter for JDBC
    [ ] JDBC concrete implementation


## Tooling

[ ] Add HexArchTest
    [ ] Add rule that Production code must not call nullable methods (createNull) and only call constructors

[ ] Create custom AssertJ assertions, e.g.:
    [ ] Find a specific event in a list of events and assert on its properties
        e.g.:
        ```
        assertThat(game.freshEvents())
                .forEvent(ActionCardDeckCreated.class)
                .hasOne()
                .extracting(ActionCardDeckCreated::actionCards)
                .hasSize(63);
        ```

## Naming

[X] Come up with a name other than Person(Id) that's easier to differentiate from Player(Id), hopefully something other than "Account" or "User"
    Perhaps "Member"?


## Future Features

[ ] Person's own page showing their profile, active games they're in, past games they've played, etc.


## Open Questions

[ ] Do we allow non-Players to see the Game page?
    [ ] If so, who is allowed to observe?
    [ ] If they can, they must not be able to click on any buttons, etc.