@game-hub/game-argute

Argute™ (Indipro Games) for Game Hub — a suitless trick-taking card game for 2–7 players, scored on a wooden pegboard. Built in its own repository against the published @game-hub/kernel and @game-hub/ui-kit, exactly as a third-party game is, and shipping the four subpath exports every Game Hub game has: ./engine (pure rules), ./module (backend seam), ./client (UI seam), ./bot (AI).

The game in six lines

• 42 play cards — seven each of 0, 1, 2, 3, 4, 5. No suits. Six dealt to each player.
• Before a card is played, everyone secretly places a bid card: 0, 1, 2 or 3.
• A hand is three tricks, shrinking: three cards each, then two, then one — laid one card per turn, so a trick is that many passes around the table.
• The highest total takes the trick; on a tie, whoever's running total reached that number first. Spending your high cards early is therefore worth something: it wins the ties a late 5 forfeits.
• Bid exactly right → score the bid. Bid wrong, over or under → −1. A correct 0 is +0, not a miss.
• First to 6 or more and not tied wins. Tied at the top? Another hand.

The authoritative spec for this package is ROADMAP.md — §1 the rules digest, §2 the pegboard, §3 the numbered rulings R1–R13 for everything the source leaves open, §4 the engine design. There is no published rulebook PDF (see reference_materials/README.md), so code comments cite ROADMAP §1 where another game would cite a page number, and ruling R<n> for the decisions we had to make.

What is interesting about it

Argute is the platform's most hidden-information-heavy game so far, and the redaction is the reason most of the discipline in here exists:

• every seat's six cards are secret, and every seat's bid card is face-down until the hand is scored (ruling R2) — so the bid value is never written to the move log, only "this seat has bid";
• state carries a deckSeed from which every hand of the game is dealt (ruling R12). One number unlocks every hand, past and future, so it appears in no view, no log payload and no summary — there is a dedicated leak scanner (src/module/tests/leaks.test.ts) that plays a whole game and asserts it.

Layout

src/
  engine/     the pure rules core — no I/O, no Date, no Math.random. 100% coverage gate.
    core/       constants, types (compile-time only), the GameError subclass
    internal/   shared helpers: the kernel record()/seating bindings, the deal, the trick tie-break, scoring
    actions/    one file per mechanic (bid.ts, play.ts) + the Action union + applyAction + legalActions
    createGame.ts / view.ts    setup, and the per-viewer projection (redaction lives here)
    tests/      one file per concern
  module/     the backend seam — the GameModule: createGame wiring, parseAction, the error→HTTP map,
              summarize, the bot driver (botRunner.ts, a host binding, not under the bot gate) and the
              leak scanner test
  client/     the UI seam — the GameClient + the board
    Board.tsx     the pegboard, the trick, the hand and the bid cards, from ui-kit chrome
    Icon.tsx      the box-lid mark the host's picker shows (GameClient.Icon; { className }, currentColor)
    index.ts      the STANDARDIZED export surface: default client + named client + BoardProps + payload type
  bot/        the AI — an expected-score bid + a play policy. 90% coverage gate.
reference_materials/   where the rules provenance is recorded (the directory itself is gitignored)

Running it

Requires Node 22 (.nvmrc) and pnpm (the version is pinned in packageManager).

pnpm install         # resolves @game-hub/* from the public registry
pnpm test            # vitest + the coverage gates (engine 100%; bot 90%)
pnpm test:watch
pnpm typecheck       # strict TS across all four subpaths
pnpm lint            # ESLint 9 flat config — real hazards, not a second typecheck
pnpm format:check    # Prettier (hand-wrap Markdown; *.md is Prettier-ignored)
pnpm build           # tsc → dist/ (JS + .d.ts + inline-source maps), what publishConfig points at
pnpm pack:smoke      # pack, install outside this repo, play a game under plain node, typecheck a consumer

⚠️ Relative imports in the shipped sources carry an explicit .js extension ('../engine/index.js') — tsc emits them verbatim and Node ESM resolves neither extensions nor directories, so extensionless ones would produce a tarball that throws on a host's first import while every command above stayed green. pack:smoke is what catches it. Do not "tidy" the extensions away.

⚠️ Publish with pnpm publish, never npm publish — publishConfig.exports is applied by pnpm at pack time and ignored by npm, which would upload src-pointing exports inside a dist-only tarball. scripts/assert-pnpm-publish.mjs refuses the wrong one.

Hosting it

A host adds this game with two dependency lines (backend + ui, ^0.1.0), one games.config.ts entry, and pnpm generate — no Vite alias, no tsconfig include, no vitest entry. See the hub's docs/game-creation.md §6 for the host side.

Rules provenance

Game mechanics are not copyrightable; a publisher's text and illustrations are. This package implements and paraphrases the mechanics, ships none of the publisher's prose, and draws every illustration in ./client — the pegboard, the cards, the box-lid icon — fresh in SVG. See reference_materials/README.md for the source used and what it does and does not settle.

Licence

BSD-3-Clause (see LICENSE).