This commit is contained in:
2026-10-29 15:21:05 +01:00
parent bb85881cac
commit bc05b63083
36 changed files with 4654 additions and 5080 deletions

View File

@@ -94,23 +94,24 @@ with its original text, never guessed.
```bash
cd backend
npm run compile:cards # data/card-effects.json + data/card-effects.pseudo.txt
npm run compile:cards # data/card-effects.json + data/card-effects.js
npm test
```
`data/card-effects.pseudo.txt` is the human-readable pseudocode view. The
pseudocode is also an input format: the frontend editor saves one override file
per card under `backend/data/card-overrides/`, and `npm run compile:cards`
validates those files and uses them instead of generated output. See
[backend/docs/card-effects.md](backend/docs/card-effects.md) for the DSL,
`data/card-effects.js` is the human-readable card source. The source is also an
input format: the frontend editor saves one override file per card under
`backend/data/card-overrides/`, and `npm run compile:cards` validates those files
and uses them instead of generated output. Card source looks like JavaScript but
is evaluated by a safe interpreter with a fixed builder API, never by `eval`.
See [backend/docs/card-effects.md](backend/docs/card-effects.md) for the DSL,
current coverage, and how to add support for more cards.
The `/cards` page has an **Editor** view and a **Guide** view that summarizes the
pseudocode syntax. **Draft with AI** sends the selected card's oracle text to an
OpenRouter model and loads the returned pseudocode into the editor without
saving it. The model is instructed to answer with pseudocode only — no
explanations, Markdown or code fences — and the answer must parse before the API
returns it. Set `OPENROUTER_API_KEY` on the backend to enable the button;
source syntax. **Draft with AI** sends the selected card's oracle text to an
OpenRouter model and loads the returned source into the editor without saving
it. The model is instructed to answer with card source only — no explanations,
Markdown or code fences — and the answer must parse before the API returns it.
Set `OPENROUTER_API_KEY` on the backend to enable the button;
`OPENROUTER_MODEL` defaults to `google/gemini-2.5-flash-lite`.
## Game engine
@@ -160,7 +161,7 @@ The frontend has five pages:
- `/` — create a 2–4 player game, join an open lobby, and pick your playmat.
- `/decks` — build a deck, import a Moxfield/Archidekt/Arena text export, and
export it again. Decks are stored with your account.
- `/cards` — the existing card implementation editor and pseudocode guide.
- `/cards` — the existing card implementation editor and source guide.
- `/games/:id` — lobby and game board. The page can also be used as an invite
link; a player with no seat gets a join form.
@@ -208,7 +209,7 @@ image builds TypeScript and installs production dependencies only.
| `BACKEND_PORT` | `4000` | production | Host port for the API |
| `PORT` | `4000` | backend | Port the API listens on inside the container |
| `CARD_OVERRIDES_DIR` | `backend/data/card-overrides` | backend | Where manual implementations are stored |
| `OPENROUTER_API_KEY` | — | backend | Enables the editor's AI pseudocode draft |
| `OPENROUTER_API_KEY` | — | backend | Enables the editor's AI card-source draft |
| `OPENROUTER_MODEL` | `google/gemini-2.5-flash-lite` | backend | OpenRouter model used for translation |
When deploying to a real host, set `NUXT_PUBLIC_API_BASE` and `CORS_ORIGIN` to
@@ -220,15 +221,15 @@ your public URLs. Both values are applied at runtime in the production image.
.
├── backend/
│ ├── scripts/import-cards.ts # Scryfall bulk importer
│ ├── scripts/compile-cards.ts # oracle text -> effect AST + pseudocode
│ ├── scripts/compile-cards.ts # oracle text -> effect AST + card source
│ ├── src/cards.ts # card store, lookup, and search
│ ├── src/images.ts # on-disk cache for Scryfall card art
│ ├── src/effects/ # effect DSL, compiler, formatter, pseudocode parser
│ ├── src/effects/translate.ts # natural language -> pseudocode through OpenRouter
│ ├── src/effects/ # effect DSL, compiler, formatter, source interpreter
│ ├── src/effects/translate.ts # natural language -> card source through OpenRouter
│ ├── src/game/ # rules engine, commander rules, match manager
│ ├── src/accounts.ts # Mongo models, auth, decks, and preferences
│ ├── src/server.ts # Fastify entry point and game/deck routes
│ ├── test/ # compiler, pseudocode, engine, and commander tests
│ ├── test/ # compiler, source, engine, and commander tests
│ ├── docs/card-effects.md # DSL reference and coverage
│ ├── docs/game-engine.md # engine API, rules coverage, limitations
│ ├── data/cards.json # generated by npm run import:cards
@@ -246,7 +247,7 @@ your public URLs. Both values are applied at runtime in the production image.
│ ├── app/middleware/auth.ts # redirect signed-out visitors to /account
│ ├── app/utils/auth.ts # login token storage and headers
│ ├── app/utils/decks.ts # account deck API and validation
│ ├── app/components/PseudoGuide.vue # pseudocode guide view
│ ├── app/components/SourceGuide.vue # card source guide view
│ ├── nuxt.config.ts # runtime config (API base URL)
│ ├── Dockerfile # dev, build, and production stages
│ └── package.json
@@ -271,10 +272,10 @@ your public URLs. Both values are applied at runtime in the production image.
| `GET` | `/cards/:oracleId/art` | Wide card art crop used for playmats, cached on disk |
| `GET` | `/cards?status=needs-work` | Filter by `supported`, `partial`, `unsupported`, `needs-work`, `manual`, `all` |
| `GET` | `/cards?format=modern&color=U&type=creature&rarity=rare&cmcMin=1&cmcMax=3` | Format legality, color identity (`WUBRG` includes that color, `C` colorless, `M` multicolor), card type, rarity, and mana value filters |
| `GET` | `/cards/:oracleId/implementation` | Card, compiled AST, pseudocode source, manual flag |
| `GET` | `/cards/:oracleId/implementation` | Card, compiled AST, card source, manual flag |
| `PUT` | `/cards/:oracleId/implementation` | Validate `{ "source": "..." }` and save the override |
| `DELETE` | `/cards/:oracleId/implementation` | Delete the override and restore generated output |
| `POST` | `/cards/:oracleId/translate` | Ask OpenRouter for pseudocode from the card's oracle text |
| `POST` | `/cards/:oracleId/translate` | Ask OpenRouter for card source from the card's oracle text |
| `GET` | `/cards/:oracleId/override` | Raw override source, or `404` |
| `GET` | `/stats` | Supported, partial, unsupported, and manual counts |
| `POST` | `/auth/register` | Create an account with `{ username, password }`, returns `{ token, username }` |