feat(schema): catalog system + schema meta fields — Phase 3.4 complete. Add optional $schema, description, tags, license to RulesetMeta (types + Zod + JSON Schema). Fix JSON Schema bugs: add missing custom deck preset, initialVariables, tieCondition, autoEndTurnCondition. Update all 5 rulesets with catalog metadata. Create scripts/validate-rulesets.ts and scripts/build-catalog.ts for CLI validation and catalog generation. Add .github/workflows/catalog.yml (oven/bun:slim container) for CI validation + GitHub Pages deploy. Deduplicate cardgame.v1.schema.json (remove stale copy from shared). 15 new schema validation tests. 913 tests green (804 shared + 15 schema + 94 host)

Author: faluciano

.github/workflows/catalog.yml

@@ -0,0 +1,65 @@
+name: Validate & Catalog Rulesets
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "rulesets/**"
+      - "packages/schema/**"
+  workflow_dispatch:
+
+jobs:
+  validate-and-catalog:
+    runs-on: ubuntu-latest
+    container: oven/bun:slim
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Validate rulesets
+        run: bun run scripts/validate-rulesets.ts
+
+      - name: Build catalog
+        run: bun run scripts/build-catalog.ts
+
+      - name: Upload catalog artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: catalog
+          path: catalog.json
+
+  deploy-pages:
+    needs: validate-and-catalog
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    container: oven/bun:slim
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build catalog
+        run: bun run scripts/build-catalog.ts
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -35,3 +35,6 @@ ios/
 
 # CouchKit bundled client assets (build artifact)
 packages/host/src/www-manifest.json
+
+# Generated catalog (build artifact)
+catalog.json

README.md

@@ -42,6 +42,8 @@ card-game-engine/
 ├── packages/
 │   ├── shared/        @card-engine/shared   — game engine core (types, expression
 │   │                                          evaluator, interpreter, PRNG)
+│   ├── schema/        @card-engine/schema   — JSON Schema, Zod validation, types
+│   │                                          (card, ruleset, state)
 │   ├── host/          @card-engine/host     — Android TV app (Expo + CouchKit host
 │   │                                          + expo-file-system storage)
 │   └── client/        @card-engine/client   — phone controller (Vite + React +
@@ -53,7 +55,8 @@ card-game-engine/
 
 | Package | Runtime | Key Dependencies |
 |---------|---------|------------------|
-| `shared` | Pure TypeScript, zero framework deps | Zod |
+| `schema` | Pure TypeScript | Zod |
+| `shared` | Pure TypeScript, zero framework deps | @card-engine/schema, Zod |
 | `host` | Expo + React Native | CouchKit host, expo-file-system |
 | `client` | Vite + React 18 | CouchKit client |
 
@@ -83,14 +86,14 @@ bun run dev:client
 
 ### Testing
 
-Tests live in the shared and host packages and use Vitest:
+Tests live in the shared, schema, and host packages and use Vitest:
 
 ```sh
 cd packages/shared
 bunx vitest run
 ```
 
-898 tests across 16 test files cover the engine core (expression evaluator, builtins, interpreter, PRNG, schema validation, player views, game phases, integration scenarios, host bridge) and the host package (storage, importers). The client package is verified via `tsc` type-checking and Vite production build.
+913 tests across the shared (804), schema (15), and host (94) packages cover the engine core (expression evaluator, builtins, interpreter, PRNG, schema validation, player views, game phases, integration scenarios), schema meta fields, and the host package (storage, importers). The client package is verified via `tsc` type-checking and Vite production build.
 
 ### Build and Deploy
 
@@ -113,6 +116,18 @@ Type-check the shared and client packages:
 bun run typecheck
 ```
 
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun run dev:client` | Start the client Vite dev server with HMR |
+| `bun run build:client` | TypeScript check + Vite production build |
+| `bun run bundle:client` | Bundle client dist into host's Android assets |
+| `bun run build:android` | Bundle client + Expo Android build |
+| `bun run typecheck` | Type-check shared and client packages |
+| `bun run validate` | Validate all rulesets against the JSON Schema |
+| `bun run catalog` | Generate `catalog.json` from all rulesets' metadata |
+
 ## Rulesets
 
 A `.cardgame.json` file declaratively defines everything the engine needs to run a card game: metadata, deck composition, zones, roles, phases (FSM), scoring, visibility rules, and UI hints.
@@ -125,18 +140,21 @@ The [`rulesets/`](rulesets/) directory contains example rulesets:
 - **`ninety-nine.cardgame.json`** — an accumulation game demonstrating custom variables (`get_var`, `set_var`, `inc_var`), conditional card effects with `if()`, and turn reversal
 - **`uno.cardgame.json`** — a shedding game demonstrating `play_card` action effects, custom variables for color choice, declare with params, Skip/Reverse/Draw Two effects, and multi-phase Wild card flow
 
+Rulesets support optional catalog fields (`description`, `tags`, `license`) in their `meta` block. Run `bun run catalog` to generate a `catalog.json` index of all rulesets for browsing and discovery. Run `bun run validate` to validate all rulesets against the schema.
+
 See the [Ruleset Authoring Guide](docs/ruleset-authoring.md) for the full format specification, expression language reference, and annotated examples. The [Engine API Reference](packages/shared/README.md) documents all public functions and builtins.
 
 ## Project Status
 
-All four implementation phases are **complete** with **898 passing tests** across 16 test files.
+All four implementation phases are **complete** with **913 passing tests** across shared (804), schema (15), and host (94) packages.
 
 | Phase | Status | Tests |
 |-------|--------|-------|
 | Phase 1 — Engine Core | ✅ Complete | 804 |
 | Phase 1.5 — Documentation | ✅ Complete | — |
 | Phase 2 — Storage & Import | ✅ Complete | 94 |
 | Phase 3 — Host Screens & CouchKit Integration | ✅ Complete | — |
+| Phase 3.4 — Schema Package & Catalog | ✅ Complete | 15 |
 | Phase 4 — Client Controller App | ✅ Complete | — |
 
 The app builds and deploys to Android TV via `bun run build:android`. The host runs an HTTP+WebSocket server via CouchKit; phones connect by scanning a QR code displayed on the TV.

bun.lock

@@ -55,6 +55,7 @@ sections:
 
 ```json
 {
+  "$schema": "../packages/schema/src/schema/cardgame.v1.schema.json",
   "meta": {
     "name": "string",
     "slug": "string (lowercase, hyphens only)",
@@ -63,10 +64,13 @@ sections:
     "players": {
       "min": "number (integer >= 1)",
       "max": "number (integer >= 1)"
-    }
+    },
+    "description": "string (optional — short description of the game)",
+    "tags": ["string (optional — searchable tags for catalog browsing)"],
+    "license": "string (optional — license identifier, e.g. MIT, public-domain)"
   },
   "deck": {
-    "preset": "standard_52 | standard_54 | uno_108",
+    "preset": "standard_52 | standard_54 | uno_108 | custom",
     "copies": "number (integer >= 1)",
     "cardValues": { "...rank-to-value mappings" }
   },
@@ -87,25 +91,34 @@ sections:
 }
 ```
 
-All sections are required. The schema enforces this at load time.
+| Field | Required | Description |
+|---|---|---|
+| `$schema` | No | Root-level field referencing the JSON Schema for editor validation and autocompletion. |
+| `meta` | Yes | Metadata block (see below). |
+| `deck` … `ui` | Yes | All other top-level sections are required. The schema enforces this at load time. |
 
 For the blackjack ruleset, the `meta` block looks like this:
 
 ```json
 {
+  "$schema": "../packages/schema/src/schema/cardgame.v1.schema.json",
   "meta": {
     "name": "Blackjack",
     "slug": "blackjack",
     "version": "1.0.0",
     "author": "card-engine",
-    "players": { "min": 1, "max": 6 }
+    "players": { "min": 1, "max": 6 },
+    "description": "Classic casino banking game — beat the dealer without going over 21.",
+    "tags": ["casino", "banking", "classic"],
+    "license": "public-domain"
   }
 }
 ```
 
 - `slug` must be lowercase alphanumeric with hyphens only (regex: `^[a-z0-9-]+$`).
 - `version` must be a valid semver string (regex: `^\d+\.\d+\.\d+$`).
 - `players.min` must be less than or equal to `players.max`.
+- `description`, `tags`, and `license` are optional catalog fields used by the `bun run catalog` script to generate a browsable `catalog.json`.
 
 ---
 
@@ -1175,14 +1188,14 @@ A JSON Schema (draft-07) is also available for editor autocompletion and
 pre-commit validation:
 
 ```
-packages/shared/src/schema/cardgame.v1.schema.json
+packages/schema/src/schema/cardgame.v1.schema.json
 ```
 
 You can reference it in your `.cardgame.json` files for editor support:
 
 ```json
 {
-  "$schema": "../packages/shared/src/schema/cardgame.v1.schema.json",
+  "$schema": "../packages/schema/src/schema/cardgame.v1.schema.json",
   "meta": { "..." }
 }
 ```

docs/ruleset-authoring.md

@@ -9,6 +9,8 @@
     "bundle:client": "cd packages/host && bunx couch-kit bundle --source ../client --output ./android/app/src/main/assets/www --manifest ./src/www-manifest.json",
     "build:android": "bun run bundle:client && cd packages/host && npx expo run:android",
     "typecheck": "cd packages/shared && bunx tsc && cd ../client && bunx tsc --noEmit",
-    "build": "bun run typecheck && bun run build:client && bun run bundle:client"
+    "build": "bun run typecheck && bun run build:client && bun run bundle:client",
+    "validate": "bun run scripts/validate-rulesets.ts",
+    "catalog": "bun run scripts/build-catalog.ts"
   }
 }

package.json

@@ -5,12 +5,15 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "typescript": "~5.9.2"
+    "typescript": "~5.9.2",
+    "vitest": "^3.2.1"
   }
 }