@seriousgaming/sdk-tools 1.5.0 → 1.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent/guidance.md +350 -0
- package/dist/bundling/ui-bundler.d.ts +12 -0
- package/dist/cli-25RWY5BQ.js +41 -0
- package/dist/cli-2BH7FX27.js +52 -0
- package/dist/cli-2GZYGRVL.js +36 -0
- package/dist/cli-2NU2LPEE.js +97 -0
- package/dist/cli-3BRC32CP.js +132 -0
- package/dist/cli-3D3ZXWOV.js +111 -0
- package/dist/cli-3ZKWV3PN.js +96 -0
- package/dist/cli-45OCBG53.js +60 -0
- package/dist/cli-4LKXZQ2B.js +48 -0
- package/dist/cli-4PXNOJQX.js +81 -0
- package/dist/cli-4SIWLHQO.js +717 -0
- package/dist/cli-4UWFQNGF.js +54 -0
- package/dist/cli-4VFZHLDG.js +202 -0
- package/dist/cli-4YB3ROVR.js +78 -0
- package/dist/cli-5ACDPCXI.js +21 -0
- package/dist/cli-5IAW3LIF.js +38 -0
- package/dist/cli-5SM367K7.js +30 -0
- package/dist/cli-64AB62PM.js +25 -0
- package/dist/cli-6K3VQQUS.js +307 -0
- package/dist/cli-6QB2VFPY.js +80 -0
- package/dist/cli-6SGCYEEC.js +649 -0
- package/dist/cli-6UTPHWRQ.js +207 -0
- package/dist/cli-6VNKQ3OX.js +391 -0
- package/dist/cli-72XDEFU3.js +61 -0
- package/dist/cli-7A6MKCUJ.js +463 -0
- package/dist/cli-7XLHO2FE.js +226 -0
- package/dist/cli-AV2FYC5G.js +225 -0
- package/dist/cli-B6YHEKIJ.js +248 -0
- package/dist/cli-BJMS3VX3.js +1837 -0
- package/dist/cli-BUQI5UU4.js +43 -0
- package/dist/cli-BWX5E7TQ.js +23 -0
- package/dist/cli-BYCHKSSH.js +1331 -0
- package/dist/cli-C3CMJSNL.js +89 -0
- package/dist/cli-C47GJATR.js +42 -0
- package/dist/cli-C5QOJJWX.js +46 -0
- package/dist/cli-C6ZLPK2U.js +124 -0
- package/dist/cli-CD5CIJZI.js +72 -0
- package/dist/cli-DDJYUKQG.js +36 -0
- package/dist/cli-DFBTZEBX.js +167 -0
- package/dist/cli-DOXRQ3S5.js +60 -0
- package/dist/cli-EVI36HEM.js +79 -0
- package/dist/cli-F2D4GGUA.js +549 -0
- package/dist/cli-FQRVFGN6.js +0 -0
- package/dist/cli-FWFRKQNE.js +11 -0
- package/dist/cli-G6CANSPL.js +88 -0
- package/dist/cli-GFNDW2DL.js +124 -0
- package/dist/cli-HCRTYQQS.js +16 -0
- package/dist/cli-HFX3YPUL.js +76 -0
- package/dist/cli-HKORECAG.js +53 -0
- package/dist/cli-HOE3WLFH.js +73 -0
- package/dist/cli-HSIHDN6K.js +187 -0
- package/dist/cli-HW53ICZC.js +89 -0
- package/dist/cli-IDVUHGKG.js +218 -0
- package/dist/cli-IEMKI7J7.js +1387 -0
- package/dist/cli-ILFDANBR.js +101 -0
- package/dist/cli-ILKCQNM6.js +8 -0
- package/dist/cli-IP4RXGHM.js +2847 -0
- package/dist/cli-IUS2YCD3.js +31 -0
- package/dist/cli-J4DKUUTK.js +138 -0
- package/dist/cli-J4UBELKF.js +37 -0
- package/dist/cli-JJSWBW4H.js +89 -0
- package/dist/cli-JVI24FI6.js +68 -0
- package/dist/cli-JZCLIT3O.js +135 -0
- package/dist/cli-JZOZOEZM.js +131 -0
- package/dist/cli-KGM6RRQW.js +185 -0
- package/dist/cli-KGT5L7VZ.js +13641 -0
- package/dist/cli-KOGRWFN7.js +89 -0
- package/dist/cli-KSGB2ZLK.js +101 -0
- package/dist/cli-L7VYSXQK.js +243 -0
- package/dist/cli-LK3V4RI5.js +36 -0
- package/dist/cli-LQOHATY2.js +126 -0
- package/dist/cli-MJUYJIEP.js +13 -0
- package/dist/cli-MJV47HKI.js +143 -0
- package/dist/cli-MMN4BPO4.js +145 -0
- package/dist/cli-MOPSZ3CS.js +88 -0
- package/dist/cli-MU5LB43S.js +136 -0
- package/dist/cli-MYJGMA6U.js +40 -0
- package/dist/cli-N24OHSAN.js +36 -0
- package/dist/cli-N45DREM4.js +99 -0
- package/dist/cli-N6H6T2E2.js +616 -0
- package/dist/cli-NROTDF5Y.js +182 -0
- package/dist/cli-O5ABH2WK.js +226 -0
- package/dist/cli-OMWC75CC.js +256 -0
- package/dist/cli-OXAUOWCN.js +50 -0
- package/dist/cli-PGCIHPU7.js +143 -0
- package/dist/cli-Q6ZBZYK2.js +35 -0
- package/dist/cli-QUNIRH7A.js +57 -0
- package/dist/cli-QUSCIUOM.js +142 -0
- package/dist/cli-QVASWX2A.js +187 -0
- package/dist/cli-QWQMPCL6.js +253 -0
- package/dist/cli-QY5NZAR7.js +97 -0
- package/dist/cli-R2MUZQE2.js +62 -0
- package/dist/cli-RCIWBCXD.js +36 -0
- package/dist/cli-RLEGRWFM.js +81 -0
- package/dist/cli-RSW6EBBD.js +89 -0
- package/dist/cli-RZITKPJX.js +367 -0
- package/dist/cli-S5IVGDDD.js +32 -0
- package/dist/cli-SRHBXZCN.js +159 -0
- package/dist/cli-TDSQSCX4.js +131 -0
- package/dist/cli-TIDQ4WUE.js +257 -0
- package/dist/cli-TT36JCU5.js +370 -0
- package/dist/cli-TTKICM5P.js +100 -0
- package/dist/cli-TTMBBEJC.js +131 -0
- package/dist/cli-UMEBPAZQ.js +16 -0
- package/dist/cli-UNAJ2OTE.js +15 -0
- package/dist/cli-UZZFNXRX.js +226 -0
- package/dist/cli-VDBW23SS.js +81 -0
- package/dist/cli-VL2P354N.js +46 -0
- package/dist/cli-VPRRICZA.js +304 -0
- package/dist/cli-VQ6HVQW4.js +4010 -0
- package/dist/cli-WR3NOY74.js +36 -0
- package/dist/cli-WU43JT4T.js +52 -0
- package/dist/cli-XAT25PRU.js +117 -0
- package/dist/cli-XOTNXEJA.js +124 -0
- package/dist/cli-XSLNH5PR.js +6417 -0
- package/dist/cli-XSVGKI3R.js +39 -0
- package/dist/cli-XZCJIKIV.js +124 -0
- package/dist/cli-Y3DDNMPX.js +97 -0
- package/dist/cli-Y3O5F4JN.js +90 -0
- package/dist/cli-YOTGR3NB.js +82 -0
- package/dist/cli-Z56ZIVA6.js +97 -0
- package/dist/cli-ZBN5KAIB.js +59 -0
- package/dist/cli-ZDOTXEKL.js +31 -0
- package/dist/cli-ZDUADFBY.js +88 -0
- package/dist/cli-ZJFQ7EEA.js +131 -0
- package/dist/cli-ZTWOE3ZT.js +65 -0
- package/dist/cli.js +148 -43093
- package/dist/client/build-surfaces.d.ts +33 -0
- package/dist/client/dev-server.d.ts +6 -0
- package/dist/client/index.d.ts +1 -0
- package/dist/client/playwright.d.ts +62 -0
- package/dist/client.js +228 -48
- package/dist/core/session.d.ts +15 -1
- package/dist/dev/console/assets/{index-BVF8exas.js → index-CuMOOH9m.js} +1 -1
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/shell.d.ts +19 -0
- package/dist/dev/surfaces.d.ts +7 -0
- package/dist/docs/ai-agents.md +1 -1
- package/dist/docs/api/index.md +14 -12
- package/dist/docs/api/sdk-tools-client.md +29 -0
- package/dist/docs/api/sdk-tools-playwright.md +104 -0
- package/dist/docs/changelog.md +34 -0
- package/dist/docs/cli-and-dev-server.md +21 -0
- package/dist/docs/cli-reference.md +45 -31
- package/dist/docs/environment-variables.md +6 -0
- package/dist/docs/getting-started.md +1 -1
- package/dist/docs/guides/designing-a-game.md +29 -4
- package/dist/docs/guides/starter-game.md +3 -3
- package/dist/docs/guides/testing.md +33 -18
- package/dist/docs/guides/upgrading.md +19 -2
- package/dist/docs/page-index.md +10 -9
- package/dist/docs/recipes/e2e-testing.md +19 -20
- package/dist/playwright.js +32232 -0
- package/dist/templates/package/CLAUDE.md.template +7 -346
- package/dist/templates/package/claude/rules/workflow-create-engine.md +2 -2
- package/dist/templates/package/claude/rules/workflow-create-guide.md +2 -2
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
- package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +3 -3
- package/dist/templates/package/global-setup.ts.template +7 -18
- package/dist/templates/package/playwright.config.ts.liquid +8 -11
- package/dist/templates/starter-game/playwright.config.ts +8 -11
- package/dist/templates/starter-game/testing/e2e/game.spec.ts +1 -1
- package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
- package/dist/utils/prompt.d.ts +5 -5
- package/dist/utils/resource-scan.d.ts +39 -0
- package/package.json +7 -3
|
@@ -1,350 +1,11 @@
|
|
|
1
|
-
|
|
1
|
+
@node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The line above imports the Serious Gaming SDK's guidance for the version this package has installed. If your tool does not follow `@` imports, read `node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md` before anything else (run `pnpm install` first if it is missing).
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## This game
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **Declare `reads`, `writes`, `settings` and `uses`.** A resource receives exactly what it declares; a write or a service outside them is refused
|
|
9
|
-
- **Await every `setData`**, through `useMutationReporter`, so a refusal reaches the person. Never retry a write automatically
|
|
10
|
-
- **Never start `pnpm start`, `pnpm run sdk dev` or watch-mode `pnpm test`.** The user starts long-running processes
|
|
11
|
-
- **No host globals in logic.** `meta.now`, not `Date.now()`; `meta.seed` with `deriveSeed` and `seededRandom`, not `Math.random()`; no `fetch`, timers or Node built-ins
|
|
12
|
-
- **Use `update`, not `new`, for a slot that is already filled** (`engine`, `ui`, `session`, …). Change bundles through the CLI, not by hand
|
|
13
|
-
- **Never edit a generated `types.ts`, and never use `any`**
|
|
14
|
-
- **Never publish, and never `pnpm add`, unless the user asks**
|
|
7
|
+
Everything below is this package's own, and the SDK never rewrites it. Describe the game here as it takes shape, so every agent starts from it:
|
|
15
8
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- `capabilities/`: `.claude/rules/workflow-create-capability.md`
|
|
21
|
-
- `engine/`: `.claude/rules/workflow-create-engine.md`
|
|
22
|
-
- `ui/`, `session/`, `waiting_room/`, `setup/`, `scenario_editor/`: `.claude/rules/workflow-create-user-interface.md`
|
|
23
|
-
- `endpoints/`: `.claude/rules/workflow-create-endpoint.md`
|
|
24
|
-
- `guide/`: `.claude/rules/workflow-create-guide.md`
|
|
25
|
-
- `presentation/`: `.claude/rules/workflow-create-presentation.md`
|
|
26
|
-
- Any `*.test.ts` or `*.test.tsx`: `.claude/rules/workflow-test-engine-or-ui.md`
|
|
27
|
-
- `package.json` and an SDK upgrade: `.claude/rules/workflow-update-sdk-version.md`
|
|
28
|
-
- Publishing: `.claude/rules/workflow-publish-package.md`
|
|
29
|
-
|
|
30
|
-
## Documentation
|
|
31
|
-
|
|
32
|
-
The SDK's documentation ships inside it, so it describes the version installed here. **Read the recipe before you start a task; do not guess.**
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
pnpm run --silent sdk docs view # the documentation tree
|
|
36
|
-
pnpm run --silent sdk docs view page-index.md # every page: summary and length
|
|
37
|
-
pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
|
|
38
|
-
pnpm run --silent sdk docs view recipes/create-hook.md # one document
|
|
39
|
-
pnpm run --silent sdk docs view guides/session.md --outline # the headings of a page, with section lengths
|
|
40
|
-
pnpm run --silent sdk docs view guides/session.md --section 'Building the session UI' # one section
|
|
41
|
-
pnpm run --silent sdk docs view cli-reference.md # every command and flag
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Some guides run past 50,000 characters, more than one read may show you. Before reading a long page whole, find it in `page-index.md`, list its headings with `--outline`, and read the section you need with `--section`.
|
|
45
|
-
|
|
46
|
-
The same files are on disk in `node_modules/@seriousgaming/sdk-tools/dist/docs/`, so you can search them with `grep -rn`. Start from `recipes/` for a task, `guides/` for a whole subject, and `concepts/` for the model.
|
|
47
|
-
|
|
48
|
-
`pnpm run sdk docs export` copies them into the package, for a tool that cannot read `node_modules`. The same docs for the newest release are at https://sdk.seriousgaming.com/llms.txt; prefer the installed copy, which matches the version this package runs.
|
|
49
|
-
|
|
50
|
-
## This package
|
|
51
|
-
|
|
52
|
-
Unless it was created with `--empty`, this package holds a complete, playable starter game: a lemonade stand, run for 10 days. Each morning a team decides how many lemonades, iced teas, and cookies to make. Whatever they make they pay for, whatever is left at closing is poured away, and anyone who wanted something that ran out simply leaves.
|
|
53
|
-
|
|
54
|
-
Read it before you change it. It is the reference for four things that are easy to get wrong and expensive to retrofit:
|
|
55
|
-
|
|
56
|
-
- **State keyed so participants cannot overwrite each other.** `plan.Make` is keyed by menu item, and `hooks/assignproducts/` puts each participant in charge of one item, so two people changing two numbers write two different keys
|
|
57
|
-
- **A validator on the one thing they share.** Two changes can each fit while the merged plan exceeds the stall's capacity, so `validators/capacity/` checks the merged result and refuses it out loud
|
|
58
|
-
- **Awaited writes.** Every `setData` in `ui/` goes through the one mutation reporter in `ui/src/writes.ts`
|
|
59
|
-
- **Teams run their own days.** The game is in independent mode; the facilitator watches from `session/` and can undo
|
|
60
|
-
|
|
61
|
-
Replace the model freely. Keep the shape. `pnpm run --silent sdk docs view guides/starter-game.md` walks through every file, and `recipes/start-from-an-empty-package.md` picks up an empty package.
|
|
62
|
-
|
|
63
|
-
### Mental model
|
|
64
|
-
|
|
65
|
-
A game works like a **reactive spreadsheet**:
|
|
66
|
-
|
|
67
|
-
- **Capabilities**: column headers (named groups of variables, schema only)
|
|
68
|
-
- **Settings**: read-only parameters, each property with a default, overridden by scenarios
|
|
69
|
-
- **The engine**: the formulas (`Init` sets up, `Run` computes one tick)
|
|
70
|
-
- **User interfaces**: charts and input cells (`ui/` for participants, `session/` for the facilitator, `waiting_room/` before play, `setup/` and `scenario_editor/` for settings)
|
|
71
|
-
- **Validators**: data validation on input cells (reject a write, never change it), and an optional `Scenario` gate that refuses a scenario breaking the game's rules
|
|
72
|
-
- **Hooks**: handlers that run outside the tick on a signal such as `participantJoin`
|
|
73
|
-
- **Endpoints**: server-side functions a surface, or with `visibility: "external"` a caller outside the game, calls by identifier
|
|
74
|
-
- **Guide and presentation**: the facilitator's run-sheet and slide deck
|
|
75
|
-
|
|
76
|
-
Data flows: surfaces write decisions with `setData`, a tick runs the engine, and surfaces show the results.
|
|
77
|
-
|
|
78
|
-
### Layout
|
|
79
|
-
|
|
80
|
-
```
|
|
81
|
-
.
|
|
82
|
-
├── seriousgaming.sdk.json # The package identifier, locales, maxTicks and teams
|
|
83
|
-
├── engine/ # THE engine: Init and Run
|
|
84
|
-
├── ui/ # THE participant interface
|
|
85
|
-
├── session/ # THE facilitator's screen
|
|
86
|
-
├── waiting_room/ # THE holding screen
|
|
87
|
-
├── setup/ # THE settings form at session creation (sdk new setup)
|
|
88
|
-
├── scenario_editor/ # THE scenario authoring screen (sdk new scenario_editor)
|
|
89
|
-
├── presentation/ # THE slide deck the facilitator projects
|
|
90
|
-
├── tick_controller/ # THE timer, for timed rounds (sdk new tick_controller)
|
|
91
|
-
├── guide/ # THE facilitator guide (markdown per locale, plus assets)
|
|
92
|
-
├── capabilities/<name>/ # Data definitions
|
|
93
|
-
├── settings/<name>/ # Read-only parameters
|
|
94
|
-
├── endpoints/<name>/ # Server-side functions
|
|
95
|
-
├── hooks/<name>/ # Lifecycle handlers
|
|
96
|
-
├── validators/<name>/ # Reject-only gates on writes and tick requests
|
|
97
|
-
├── scenarios/<name>/ # Settings overrides, plus assets
|
|
98
|
-
├── testing/engine/ # Whole-game tests (createTestSession)
|
|
99
|
-
└── testing/e2e/ # Playwright specs, and the global setup that starts their server
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
A game holds one of each slot resource, so it lives in its slot and carries no name. Everything else sits at `<plural>/<name>/` and is named by its directory: `"identifier": "sales"` makes `capabilities/sales/`, `context.sales`, and `"sales"` in `reads`. A name is lowercase letters, digits, and underscores, starting with a letter. Only the package carries a dotted reverse-DNS identifier, and its game is that identifier with `.game` appended. There is no list to keep in step: a package declares whatever is on disk.
|
|
103
|
-
|
|
104
|
-
## The loop: edit, validate, test
|
|
105
|
-
|
|
106
|
-
Pass `--json` to any command (or set `SERIOUSGAMING_JSON=1`) and it prints exactly one JSON document on stdout, success or failure, with progress on stderr. Always invoke it as `pnpm run --silent sdk …`, so no pnpm banner precedes the JSON.
|
|
107
|
-
|
|
108
|
-
```json
|
|
109
|
-
{ "ok": true, "command": "tick", "data": { "completedTicks": 1 }, "diagnostics": [], "warnings": [] }
|
|
110
|
-
{ "ok": false, "command": "build", "error": { "code": "PACKAGE_INVALID", "message": "…", "hint": "…" }, "diagnostics": [{ "severity": "error", "code": "SETTINGS_UNKNOWN_KEY", "file": "scenarios/hard/scenario.sdk.json", "pointer": "/definition/settings/engine/BaseDemnd", "hint": "Did you mean 'BaseDemand'?", "message": "…" }], "warnings": [] }
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
After every change, run these in order and stop at the first that fails:
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
pnpm run --silent sdk build --validate-only --json # the package: bundles, references, settings
|
|
117
|
-
pnpm run typecheck # tsc over the whole package
|
|
118
|
-
pnpm run lint # oxlint, warnings included
|
|
119
|
-
pnpm test:run # unit and component tests beside each resource
|
|
120
|
-
pnpm test:engine # whole games, in-process
|
|
121
|
-
pnpm run --silent sdk tick --no-server --json # one tick in the restricted production runtime
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Branch on `ok`, the exit code and `error.code`, never on the message:
|
|
125
|
-
|
|
126
|
-
| Exit | Meaning | What to do |
|
|
127
|
-
| ---- | ------------------- | -------------------------------------------------------------------------- |
|
|
128
|
-
| 0 | Success | |
|
|
129
|
-
| 1 | A bug in the CLI | Report it; do not retry blindly |
|
|
130
|
-
| 2 | Usage error | Fix the command: a flag, an argument, or input you did not pass |
|
|
131
|
-
| 3 | Invalid package | Fix the package: `diagnostics` says which file and where |
|
|
132
|
-
| 4 | Refused by the game | The game said no (`REFUSED_VALIDATION`, `TICK_FAILED`, …): read the reason |
|
|
133
|
-
| 5 | Environment | No session, a port in use, the platform unreachable: fix the environment |
|
|
134
|
-
|
|
135
|
-
**On a failure, read `diagnostics[]` first.** `file` is relative to the package root; `pointer` is an RFC 6901 pointer into that JSON file (`/definition/reads/0` is the bundle's first read), and `line` and `column` locate a TypeScript file instead. Open it there, apply the `hint`, and rerun the same command. Branch on each diagnostic's `code` (`SCHEMA_INVALID`, `REFERENCE_UNKNOWN`, `SETTINGS_UNKNOWN_KEY`, `REMOVED_FIELD`, `LOGIC_ERROR`, …). Logic that throws during `init`, `tick` or `endpoint call` exits 4 with a `LOGIC_ERROR` naming the source line, `tick` and `team`. Warnings do not fail a command, but are usually worth fixing.
|
|
136
|
-
|
|
137
|
-
The CLI never prompts without a terminal: a command that would ask fails with `PROMPT_REQUIRED` (exit 2). Pass definitions as an argument, with `--file`, or on stdin, and pass `--yes` to `delete`. `pnpm run --silent sdk docs view recipes/check-a-package-from-a-script.md` has the whole contract.
|
|
138
|
-
|
|
139
|
-
## Commands
|
|
140
|
-
|
|
141
|
-
### Resources
|
|
142
|
-
|
|
143
|
-
```bash
|
|
144
|
-
pnpm run sdk new capability --help # every type prints its JSON format with --help
|
|
145
|
-
pnpm run sdk new capability '{...}' # likewise hook, validator, endpoint, settings, scenario
|
|
146
|
-
pnpm run sdk new setup '{...}' # an empty slot: setup, scenario_editor, presentation, tick_controller
|
|
147
|
-
pnpm run sdk update engine --patch '[{"op":"add","path":"/definition/writes/-","value":"results"}]'
|
|
148
|
-
pnpm run sdk update capability plan '{...}' # full replacement
|
|
149
|
-
pnpm run sdk update package --patch '[{"op":"replace","path":"/maxTicks","value":12}]'
|
|
150
|
-
pnpm run sdk delete capability plan --yes
|
|
151
|
-
pnpm run generate # regenerate types after a hand edit (new and update already do)
|
|
152
|
-
pnpm run build # validate, generate and bundle into dist/
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
A slot command takes no identifier. The starter game fills every slot but `setup`, `scenario_editor` and `tick_controller`, and `new` refuses a filled slot. `update package` changes the manifest, which takes no identifier either.
|
|
156
|
-
|
|
157
|
-
### Playing the game from the CLI
|
|
158
|
-
|
|
159
|
-
```bash
|
|
160
|
-
pnpm run --silent sdk init # start the session, or rebuild it at tick 0
|
|
161
|
-
pnpm run --silent sdk tick --patch '[{"op":"replace","path":"/plan/Make/lemonade","value":70}]'
|
|
162
|
-
pnpm run --silent sdk patch '[{"op":"replace","path":"/plan/Make/cookies","value":0}]'
|
|
163
|
-
pnpm run --silent sdk view # the current state (--full for the whole projection)
|
|
164
|
-
pnpm run --silent sdk undo # undo the last tick
|
|
165
|
-
pnpm run --silent sdk reset # back to tick 0
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
Patch paths start at the capability. `--team N` picks the team in a game with several. `pnpm run sdk configure '{"menu":{"Capacity":60}}'` overrides settings for the session, keyed by settings identifier, and restarts a running session on the new values.
|
|
169
|
-
|
|
170
|
-
**Know which session a command touches:**
|
|
171
|
-
|
|
172
|
-
- **If a dev server is running**, session commands act on its session, which is what the user is watching
|
|
173
|
-
- **If none is running**, they start one in the background and say so on stderr
|
|
174
|
-
- **With `--no-server`**, they run in-process against a fresh session and leave nothing behind; each starts again at tick 0
|
|
175
|
-
|
|
176
|
-
Edits to logic and bundles reach a running dev server from its next tick, without a reset. Prefer `--no-server` and `pnpm test:engine` for your own checks. Use the shared session only when the user wants to watch. `pnpm run sdk dev status` says whether a server is running; never stop one you did not start. `pnpm test:e2e` starts an isolated server of its own on free ports, beside the user's.
|
|
177
|
-
|
|
178
|
-
## How things work
|
|
179
|
-
|
|
180
|
-
### Reads, writes and what the runtime owns
|
|
181
|
-
|
|
182
|
-
Every resource declares its data flow as arrays of capability identifiers: `reads` for what it consumes, `writes` for what it produces (a capability may appear in both). A capability you forgot to declare is absent from `context` (or a surface's `data`), and the generated `Context` says so. A game holds one engine; a simulation with several steps calls them as plain functions from its `Run`.
|
|
183
|
-
|
|
184
|
-
Do not rebuild runtime concerns in context:
|
|
185
|
-
|
|
186
|
-
- **Ticks**: no `CurrentRound` variable; read `meta.tick`, the tick being run
|
|
187
|
-
- **Time**: `meta.now`, the instant the operation started, which a re-run sees again
|
|
188
|
-
- **Who is on a team**: the read-only `participants` argument, not a roster kept from hooks
|
|
189
|
-
- **Lifecycle**: set `maxTicks` in `seriousgaming.sdk.json`, or return `complete: true` from `Run`. A tick controller is for timed rounds, or ending on a participant's write between ticks
|
|
190
|
-
- **Undo and reset**: built in
|
|
191
|
-
- **Parameters**: a settings resource (`settings/<name>/settings.sdk.json`, a default on every property), read by each resource that lists it in `settings`
|
|
192
|
-
|
|
193
|
-
`setData` updates context immediately, and other surfaces see it at once; the engine's `Run` sees it on the next tick.
|
|
194
|
-
|
|
195
|
-
### Logic
|
|
196
|
-
|
|
197
|
-
Every logic function is async, takes one args object, and returns what it writes under `capabilities`, always by spreading:
|
|
198
|
-
|
|
199
|
-
```typescript
|
|
200
|
-
import type { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
|
|
201
|
-
import type { Context, Settings } from './types';
|
|
202
|
-
|
|
203
|
-
export const Init: InitializationFunction<Context, Settings> = async ({ context, settings }) => ({
|
|
204
|
-
capabilities: { ...context },
|
|
205
|
-
});
|
|
206
|
-
|
|
207
|
-
export const Run: RunFunction<Context, Settings> = async ({ context, meta }) => ({
|
|
208
|
-
capabilities: {
|
|
209
|
-
...context,
|
|
210
|
-
results: { ...context.results, Day: meta.tick }, // never context.results.Day = …
|
|
211
|
-
},
|
|
212
|
-
});
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
- The args are `{ context, settings, callbacks, meta, participants }`, plus `state` for an engine. `settings` is keyed by settings identifier and already resolved for the session; `guides/settings.md` has the order
|
|
216
|
-
- Hooks, aggregate engines (`{ shared: { capabilities }, teams: [{ capabilities }] }`) and writing endpoints (`{ response, capabilities }`) return the same way. A flat return fails the call
|
|
217
|
-
- **To remove a key**, return its path in `deletes` beside `capabilities` (`deletes: [['orders', 'Open', id]]`), under a capability in `writes`. Leaving a key out never removes it
|
|
218
|
-
- `Init` is optional: without it each team starts from the capabilities' defaults
|
|
219
|
-
- `Run` may return `complete: true` to end the game, and an engine may return `state` beside `capabilities` for private memory between ticks (type it with `RunFunction`'s fourth parameter)
|
|
220
|
-
- A step of a split engine is a `StepFunction<Context, Settings>`: steps pass the context flat, and only the exported function wraps the result
|
|
221
|
-
|
|
222
|
-
### The logic runtime: ECMAScript intrinsics only
|
|
223
|
-
|
|
224
|
-
Engine, hook, validator, endpoint, and tick controller logic runs in a **bare V8 isolate** in production. `process`, `require`, `fetch`, timers, `structuredClone`, `Buffer`, `TextEncoder`, `URL`, `crypto`, `atob`, `window`, `document` and `localStorage` are absent and throw at tick time. `console.log` is fine.
|
|
225
|
-
|
|
226
|
-
| Instead of | Use |
|
|
227
|
-
| ----------------------------- | -------------------------------------------------------------- |
|
|
228
|
-
| `structuredClone(v)` | `JSON.parse(JSON.stringify(v))` |
|
|
229
|
-
| `TextEncoder`, `TextDecoder` | `encodeUtf8`, `decodeUtf8` from `@seriousgaming/sdk` |
|
|
230
|
-
| `fetch(...)` | The injected `callbacks`, or an endpoint |
|
|
231
|
-
| `setTimeout(...)` | Nothing: ticks are the scheduling primitive |
|
|
232
|
-
| `process.env.X` | The `settings` argument |
|
|
233
|
-
| `Math.random()` for kept data | `deriveSeed` and `seededRandom` from the SDK, from `meta.seed` |
|
|
234
|
-
| `Date.now()`, `new Date()` | `meta.now` |
|
|
235
|
-
|
|
236
|
-
Importing a Node built-in (`node:fs`, `path`, `os`, …), directly or through a library, fails `build`, `dev` and `tick` with `LOGIC_NODE_BUILTIN`. `pnpm run lint` refuses the globals above as errors in every logic file, and fails on any warning, so run it before you call logic done. It cannot see `globalThis.fetch`, and it is off for tests, which run in Node: **a green unit test does not prove logic is portable**, so finish with `tick --no-server`.
|
|
237
|
-
|
|
238
|
-
### Type safety
|
|
239
|
-
|
|
240
|
-
`variablesSchema` and `settingsSchema` are full JSON Schema 7 objects, and the generated types are only as precise as they are:
|
|
241
|
-
|
|
242
|
-
- **Wrap every schema**: `type: 'object'`, `properties`, `additionalProperties: false` (and `required` in a `variablesSchema`)
|
|
243
|
-
- **Type every field.** Never a string holding JSON; give an object its `properties` and an array its `items`
|
|
244
|
-
- **Key collections by id** where several people write at once (`additionalProperties` with a schema): two writes to two keys cannot collide, and an entry leaves through `deletes`. See `recipes/design-state-for-concurrent-writes.md`
|
|
245
|
-
- **A `default` must satisfy its own schema**: `build --validate-only` fails one that does not
|
|
246
|
-
|
|
247
|
-
```json
|
|
248
|
-
{
|
|
249
|
-
"definition": {
|
|
250
|
-
"identifier": "market",
|
|
251
|
-
"variablesSchema": {
|
|
252
|
-
"type": "object",
|
|
253
|
-
"properties": {
|
|
254
|
-
"Competitors": {
|
|
255
|
-
"type": "object",
|
|
256
|
-
"properties": {
|
|
257
|
-
"count": { "type": "number", "minimum": 1 },
|
|
258
|
-
"priceList": {
|
|
259
|
-
"type": "array",
|
|
260
|
-
"items": { "type": "number", "minimum": 0 }
|
|
261
|
-
}
|
|
262
|
-
},
|
|
263
|
-
"required": ["count", "priceList"],
|
|
264
|
-
"additionalProperties": false,
|
|
265
|
-
"default": { "count": 5, "priceList": [10, 15, 20] }
|
|
266
|
-
}
|
|
267
|
-
},
|
|
268
|
-
"required": ["Competitors"],
|
|
269
|
-
"additionalProperties": false
|
|
270
|
-
}
|
|
271
|
-
}
|
|
272
|
-
}
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
Every resource with logic or a surface has a generated `types.ts` beside it: `Context` holds exactly the capabilities it declares, `Settings` the settings resources it lists, and `Callbacks` the services in its `uses`. Import from `./types` (or `../types` from a `logic/` directory), never edit it or `defaults.ts`, and never write your own. `pnpm run --silent sdk docs view guides/type-safety.md` has the rest.
|
|
276
|
-
|
|
277
|
-
### Testing logic
|
|
278
|
-
|
|
279
|
-
Call a logic function with `logicArgs` from `@seriousgaming/sdk/testing`, which fills `meta`, the roster and offline stub callbacks around what you name; pass the generated `defaultSettings`. A whole game runs in `createTestSession<Context, SharedContext>` (`testing/engine/`), whose `setData` and `requestTick` act as a participant, so validators judge them. Never cast an argument or a context:
|
|
280
|
-
|
|
281
|
-
```ts
|
|
282
|
-
const result = await Run(
|
|
283
|
-
logicArgs.run({ context: defaultContext, settings: defaultSettings, meta: { tick: 3 } })
|
|
284
|
-
);
|
|
285
|
-
|
|
286
|
-
const session = await createTestSession<Context, SharedContext>({ packagePath });
|
|
287
|
-
await session.setData(0, { plan: { Make: { lemonade: 28 } } });
|
|
288
|
-
await session.tick();
|
|
289
|
-
expect(session.team(0).context.results.Day).toBe(1);
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
## User interfaces
|
|
293
|
-
|
|
294
|
-
- **Default to MUI** (`@mui/material`), as the starter game does. Build each surface's theme with `createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), { ...your shapes })`, as `ui/src/theme.ts` does: it applies the host's colours, their `contrastText`, and the brand's fonts. Another library must integrate with `useUserInterfaceTheme` the same way, so colours and dark mode work, and text on a theme colour uses that colour's `contrastText` (`colors.contrastText.primary`)
|
|
295
|
-
- **Honour the host's brand.** A white-label host may send a logo and fonts; `useBrandLogo()` gives the logo for the current mode, or nothing, as `ui/src/HostLogo.tsx` shows, and `useBrandIcon()` the square mark. Do not hard-code a platform's logo in its place: the host's brand is the host's to send. For join sheets, open the host's `'print-sheets'` overlay where it offers one rather than drawing your own
|
|
296
|
-
- **Await writes.** `setData` rejects when the host refuses the write. Route writes through `useMutationReporter`, as `ui/src/writes.ts` does; on a `conflict`, offer `failure.retry` behind a 'Try again' button
|
|
297
|
-
- **Endpoint calls fail typed.** `callbacks.endpoints['<name>'](request)` rejects with an `EndpointError` whose `kind` says why; a non-empty `applied` means some effects landed. Never retry one automatically
|
|
298
|
-
- **A viewer's own choices** (a tab, a collapsed panel) go in `useViewerStorage(key, initial)`, never `localStorage`, which collides across sessions
|
|
299
|
-
- **Assets and history through the hooks.** `useAssetUrl(ref)` for a `src`, `useAsset(ref, { as })` to read a file (it finds the locale's copy in `<dir>/<locale>/<file>`), and `usePastState(query)` for past rounds, rather than hand-rolled effects. The wrapper already sets `lang`, `dir` and `color-scheme` on the document
|
|
300
|
-
- **Every string** goes through `src/i18n.ts`
|
|
301
|
-
- **The facilitator's screen** is `session/`: rendered full-bleed beneath a thin band of host chrome, it owns teams, participants and game controls (`guides/session.md`)
|
|
302
|
-
|
|
303
|
-
### Testing a surface
|
|
304
|
-
|
|
305
|
-
Every surface but the presentation scaffolds an `App.test.tsx`; the starter game's own tests are worked examples, and `pnpm run --silent sdk docs view guides/testing.md` is the reference. A deck is tested through what its slides show, kept in plain functions (`presentation/src/stalls.test.ts`), and a Playwright spec that it opens.
|
|
306
|
-
|
|
307
|
-
- **Render through the helper**: `renderUserInterface()` from `@seriousgaming/sdk/ui/testing` (or `renderSessionUserInterface<SessionData>()`, or `renderSettingsEditor()` for setup and the scenario editor). It supplies every provider the host does; pass `data`, `settings`, `callbacks` and the rest as options
|
|
308
|
-
- **Never `vi.mock` the SDK, and never wire its providers by hand**
|
|
309
|
-
- **Use `fireEvent.change` on controlled inputs**: the mock `setData` does not update the value between `userEvent.type` keystrokes
|
|
310
|
-
- **Look at every screen you change**, at phone and desktop size: `pnpm run --silent sdk screenshot /team/1/player/1 --width 390 --height 844 --json`, then again with `--width 1280 --height 800`. Open each PNG, fix text that is cut off, overlaps or is hard to read, and clear the `consoleErrors`, `failedRequests` and `uncaughtExceptions` it lists. Reach the state first with `sdk tick` (`recipes/screenshot-a-surface.md`)
|
|
311
|
-
|
|
312
|
-
## Presentations
|
|
313
|
-
|
|
314
|
-
The `presentation/` slot holds the facilitator's slide deck, built with `@seriousgaming/deck` at the SDK's version. It reads every team's state and writes nothing. The starter game's deck is a worked example: a title, a slide a day, and the results. A facilitator exports it to PDF or PowerPoint and edits the copy, so:
|
|
315
|
-
|
|
316
|
-
- **Use the building blocks** (`Heading`, `Text`, `Bullets`, `Table`) for anything a facilitator might edit; anything else exports as a picture
|
|
317
|
-
- **Render with `session === null`**, showing labelled sample figures where results would go
|
|
318
|
-
- **Branch on settings, not the scenario name**, and draw a custom animation's end state when `useSlide().mode` is `'static'`
|
|
319
|
-
- **Route every word through i18n**, and keep one element per slide
|
|
320
|
-
|
|
321
|
-
## LLM integration
|
|
322
|
-
|
|
323
|
-
Logic calls `callbacks.generateText()` only if its bundle lists `generateText` in `uses`; once listed it is always present on the generated `Callbacks`, so call it without `?.`. A surface reaches an LLM only through an endpoint. The dev server needs `SERIOUSGAMING_API_KEY` in the environment or `.env`, and `createTestSession` stubs it offline. See `guides/llm-integration.md`.
|
|
324
|
-
|
|
325
|
-
## Keeping the SDK up to date
|
|
326
|
-
|
|
327
|
-
```bash
|
|
328
|
-
pnpm run --silent sdk version # the installed version
|
|
329
|
-
pnpm run sdk docs view changelog.md # newest first: read every entry above your version
|
|
330
|
-
pnpm run sdk docs view guides/upgrading.md # a step for each breaking change
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
Upgrade only when the user asks, or when the changelog has a fix the task needs, and then follow `.claude/rules/workflow-update-sdk-version.md`: it bumps the SDK, its tools and the deck together, and adopts the newer scaffold guidance without overwriting yours.
|
|
334
|
-
|
|
335
|
-
## Troubleshooting
|
|
336
|
-
|
|
337
|
-
| Problem | Solution |
|
|
338
|
-
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
339
|
-
| Types not updating | `pnpm run generate` |
|
|
340
|
-
| A capability is missing in code | Add it to the resource's `reads` or `writes`; `update` regenerates the types |
|
|
341
|
-
| A surface's write is refused | Add the capability to that surface's `writes` |
|
|
342
|
-
| Build failing | `pnpm run --silent sdk build --validate-only --json`, then read `diagnostics` |
|
|
343
|
-
| Edit not showing, or `SETTINGS_STALE` | A setting, `teams` or a capability's scope applies only at init: `sdk init` |
|
|
344
|
-
| A hook reads empty data in a surface | Two copies of a package with React context: add it to `resolve.dedupe` in `vite.config.ts` |
|
|
345
|
-
| Anything else | `pnpm run --silent sdk docs view troubleshooting.md` |
|
|
346
|
-
|
|
347
|
-
Keep `DESIGN.md` up to date as the game changes, and hold to two habits for every surface:
|
|
348
|
-
|
|
349
|
-
- **Brief first.** Before you build or redesign a screen, write its brief under 'User interfaces' in `DESIGN.md`: who uses it and on what device, its one main action, its layout, the states it must handle, and the game's identity
|
|
350
|
-
- **Check, then go round once more.** Once it is built, check every screen at phone and desktop size against `pnpm run --silent sdk docs view guides/designing-screens.md`, fix what you find, and check again
|
|
9
|
+
- What the game is about, who plays it, and for how long
|
|
10
|
+
- What a team decides each round, and what the engine works out from it
|
|
11
|
+
- Rules of this game that an agent must not break, and anything here that departs from the SDK's guidance
|
|
@@ -13,8 +13,8 @@ The engine runs each tick. It reads from capabilities and returns the ones it wr
|
|
|
13
13
|
```bash
|
|
14
14
|
pnpm run --silent sdk docs view recipes/create-engine.md
|
|
15
15
|
```
|
|
16
|
-
2. **Confirm the capabilities exist.** An engine reads and writes capabilities by their short names (`
|
|
17
|
-
3. **Change or create the bundle.**
|
|
16
|
+
2. **Confirm the capabilities exist.** An engine reads and writes capabilities by their short names (for example `decisions`, `results`). Create any that are missing first (see the create-capability workflow).
|
|
17
|
+
3. **Change or create the bundle.** If `engine/` already exists (a starter game has one), change it with `pnpm run sdk update engine --patch '[...]'` (or a full `update engine '{ ... }'`); `new engine` refuses while `engine/` exists. Otherwise, `pnpm run sdk new engine '{ ... }'`. Declare every capability the engine reads or writes in `reads` / `writes`, and every settings resource it reads in `settings`. A tunable value belongs in a settings resource (`pnpm run sdk new settings`): a full JSON Schema 7 object, with a `default` on every property.
|
|
18
18
|
4. **Implement `Init` and `Run`** in `engine/logic.ts`. Both are async, both take `{ context, settings, callbacks, meta }`, and both return `{ capabilities: Context }`. Never mutate `context`: always spread. Optionally, return `state` beside `capabilities` for memory only the engine needs between ticks (it comes back as `state`; type it with `RunFunction`'s fourth parameter), and return `complete: true` from `Run` to end the game for that team. A simulation with several steps calls them as plain functions from its one `Run`: type each as `StepFunction<Context, Settings>`, pass the context along flat, and wrap only the final one.
|
|
19
19
|
5. **Check the types.** `new` and `update` regenerate `engine/types.ts`; run `pnpm run generate` yourself only after editing the bundle by hand.
|
|
20
20
|
6. **Test it.** Unit tests go in `engine/logic.test.ts`, covering at least the happy path and every branch in `Run`. Whole-game behaviour across several ticks goes in `testing/engine/` and runs with `pnpm test:engine`.
|
|
@@ -13,7 +13,7 @@ Facilitator guides are content, not code: per-locale markdown chapters plus shar
|
|
|
13
13
|
```bash
|
|
14
14
|
pnpm run --silent sdk docs view recipes/create-guide.md
|
|
15
15
|
```
|
|
16
|
-
2. **Create or change the guide.**
|
|
16
|
+
2. **Create or change the guide.** If `guide/` already exists (a starter game has one), edit its chapters directly and change its bundle with `pnpm run sdk update guide`; `new guide` refuses while `guide/` exists. Otherwise, `pnpm run sdk new guide '{ ... }'`. Declare every locale up front: the scaffold creates a chapter skeleton per declared locale, and the per-locale `name` is the title the host renders.
|
|
17
17
|
3. **Write the chapters** in `guide/content/<locale>/`. Chapters are ordered by file name (number them `01-`, `02-`, …) and file names must be identical across locales.
|
|
18
18
|
4. **Validate**: `pnpm run sdk build --validate-only`. This warns on missing translations and fails on malformed video blocks, or image or video references that do not resolve. There is nothing to wire: a `guide/` directory beside `seriousgaming.sdk.json` is served.
|
|
19
19
|
|
|
@@ -43,5 +43,5 @@ Facilitator guides are content, not code: per-locale markdown chapters plus shar
|
|
|
43
43
|
- Chapter file names differing between locales: the runtime matches chapters by file name, so a renamed translation is treated as missing and falls back
|
|
44
44
|
- Invalid YouTube ids: the id must match the 11-character format exactly; anything else renders an inert error block
|
|
45
45
|
- Writing HTML for layout: it will appear as escaped text. Tables, admonitions, and images cover the supported layouts
|
|
46
|
-
- Breaking the structure `guide/guide.test.ts` checks
|
|
46
|
+
- Breaking the structure a `guide/guide.test.ts` checks, where the package has one (the starter game does): run `pnpm test:run` after editing chapters
|
|
47
47
|
- A guide a new facilitator could not run the session from alone: if a step lives only in the designer's head, write it down
|
|
@@ -14,7 +14,7 @@ A user interface is a React app that reads game state and (optionally) sends dec
|
|
|
14
14
|
pnpm run --silent sdk docs view recipes/create-user-interface.md
|
|
15
15
|
```
|
|
16
16
|
2. **Confirm the capabilities exist.** A UI reads (and optionally writes) capabilities by their short names. Create any that are missing first.
|
|
17
|
-
3. **Change or create the bundle.**
|
|
17
|
+
3. **Change or create the bundle.** If `ui/` already exists (a starter game has one), change it with `pnpm run sdk update ui --patch '[...]'`; `new ui` refuses while `ui/` exists. Otherwise, `pnpm run sdk new ui '{ ... }'`. Declare every capability the UI shows in `reads`, and add `writes` only for the ones it sends back via `setData`. A UI receives exactly what it declares.
|
|
18
18
|
4. **Implement the components** under `ui/src/` (the entry component is `App.tsx`), with `useUserInterfaceData()` for `data`, `settings`, `setData` and `completedTicks`. Default to MUI; another library must integrate with `useUserInterfaceTheme` so dark mode and colour palettes work, and text on a theme colour uses that colour's `contrastText`. Remember a viewer's own choices with `useViewerStorage`, never `localStorage`. Put every string in `src/i18n.ts`. `pnpm run --silent sdk docs view guides/ui.md` is the reference for every hook, with the topic pages it links.
|
|
19
19
|
5. **Await every write.** `setData` returns a promise that rejects when the host refuses the write. Route writes through `useMutationReporter`, as the starter game's `ui/src/writes.ts` does, so the participant sees the refusal. Never retry a write automatically: on a `conflict` the host has already retried and given up, so offer `failure.retry` behind a 'Try again' button instead.
|
|
20
20
|
6. **Add a test** beside the component (`App.test.tsx`), rendered with `renderUserInterface()` (or `renderSessionUserInterface<SessionData>()`, `renderSettingsEditor()`) from `@seriousgaming/sdk/ui/testing`, as the starter game's tests do. `pnpm run --silent sdk docs view guides/testing.md` has the harness.
|
|
@@ -18,7 +18,7 @@ Unit and component tests live next to the source they cover: the engine's `engin
|
|
|
18
18
|
2. **For logic**, call `Init`, `Run`, a hook, an endpoint or a validator directly with arguments built by `logicArgs` from `@seriousgaming/sdk/testing` (`logicArgs.run({ context, settings: defaultSettings })`), and assert on the returned `capabilities`. For behaviour across several ticks, hooks, validators, endpoints, participants, undo or automatic ticks, use `createTestSession<Context, SharedContext>` in `testing/engine/`: it runs the session the dev server runs, in-process, with offline stubs for `generateText`, `generateSpeech` and `extractText`. The references are `pnpm run --silent sdk docs view guides/testing.md` and `guides/engine-testing.md`.
|
|
19
19
|
3. **For UI components**, render with `renderUserInterface()` (or `renderSessionUserInterface()`, or `renderSettingsEditor()` for setup and the scenario editor) from `@seriousgaming/sdk/ui/testing`, which supplies every provider the host does. Never `vi.mock` the SDK contexts, and never wire the providers by hand. For a session UI, pass the generated types: `renderSessionUserInterface<SessionData>()`, with fixtures from `createMockTeamState<TeamContext>()` and `createMockSharedState<SharedContext>()`, so a shared capability left on a team fixture fails to compile.
|
|
20
20
|
4. **Cover the branches.** One test per code path: the happy path plus each failure mode, each option flag, each conditional in `Run`.
|
|
21
|
-
5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server
|
|
21
|
+
5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server for each Playwright worker on free ports, beside any the user has running, and serves them surfaces built once by `testing/e2e/global-setup.ts`. Import `test` from `@seriousgaming/sdk-tools/playwright` in a spec, not from `@playwright/test`.
|
|
22
22
|
|
|
23
23
|
## Things that almost always go wrong
|
|
24
24
|
|
|
@@ -27,10 +27,10 @@ The SDK ships as three npm packages: `@seriousgaming/sdk` (runtime), `@seriousga
|
|
|
27
27
|
4. **Regenerate types**: `pnpm run generate`. New schema fields, renames, or removed fields all surface through the generated `types.ts` files.
|
|
28
28
|
5. **Build and address breakages**: `pnpm run build`. Work through type errors and address each Breaking Changes entry from step 2.
|
|
29
29
|
6. **Run the test suites**: `pnpm test:run` and `pnpm test:engine`.
|
|
30
|
-
7. **Adopt updated scaffold guidance**.
|
|
30
|
+
7. **Adopt updated scaffold guidance**. The SDK's own guidance ships in `node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md`, and `CLAUDE.md` imports it with its first line, so it updates with the version you just installed and needs no merging. The `.claude/rules/` files are copied into the package, so it keeps whatever it was scaffolded with. The new version ships its templates inside the installed package, so both sides of the diff are on disk. Check three places and fold in anything relevant:
|
|
31
31
|
1. The changelog entries between the old and new version (from step 2): anything mentioning scaffold, guidance, rules, or `CLAUDE.md` is a candidate to adopt.
|
|
32
32
|
2. The shipped rules in `node_modules/@seriousgaming/sdk-tools/dist/templates/package/claude/rules/` against the local `.claude/rules/`: copy rule files that don't exist locally; for rules that do exist, diff the two and incorporate new guidance while keeping local edits.
|
|
33
|
-
3. The
|
|
33
|
+
3. The first line of the local `CLAUDE.md`. If it is not `@node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md`, the package predates the import: replace the SDK's text in `CLAUDE.md` (everything copied from the old template) with the first three lines of `node_modules/@seriousgaming/sdk-tools/dist/templates/package/CLAUDE.md.template`, and keep what the package wrote about itself below them. There is no command that refreshes it.
|
|
34
34
|
|
|
35
35
|
The templates are the source of new guidance; the local files are the source of local truth. Propose the merge as a normal reviewable change, skip anything that isn't relevant to this package, and never overwrite local content wholesale. The goal is adoption, not a reset.
|
|
36
36
|
|
|
@@ -40,4 +40,4 @@ The SDK ships as three npm packages: `@seriousgaming/sdk` (runtime), `@seriousga
|
|
|
40
40
|
- Skipping the changelog read: breaking changes silently corrupt resources or fail validation later
|
|
41
41
|
- Forgetting `pnpm run generate` after the upgrade: types stay stale and downstream code compiles against the old shape
|
|
42
42
|
- Leaving `package.json` scripts, `pnpm-workspace.yaml`, or the config files behind: the new version's `dist/templates/package/` holds the current copies to compare against
|
|
43
|
-
- Skipping the scaffold guidance check: the package quietly stays on outdated
|
|
43
|
+
- Skipping the scaffold guidance check: the package quietly stays on outdated rules, or on a copied `CLAUDE.md` that never gains the SDK's newer guidance
|
|
@@ -1,21 +1,10 @@
|
|
|
1
|
-
import { dirname } from 'path';
|
|
2
|
-
|
|
3
|
-
import type { FullConfig } from '@playwright/test';
|
|
4
|
-
import { startDevServer } from '@seriousgaming/sdk-tools/client';
|
|
5
|
-
|
|
6
1
|
/**
|
|
7
|
-
*
|
|
2
|
+
* Build the game's surfaces once, before any test runs, and remove the build
|
|
3
|
+
* after the last.
|
|
8
4
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
* which a run cannot hang on.
|
|
5
|
+
* Every worker's dev server then serves the build as files, so a page loads at
|
|
6
|
+
* once instead of each server compiling the same surfaces through Vite. Set
|
|
7
|
+
* SERIOUSGAMING_BUILT_SURFACES=dist to serve the output of your own
|
|
8
|
+
* `pnpm run sdk build` instead, and build nothing here.
|
|
14
9
|
*/
|
|
15
|
-
export
|
|
16
|
-
const server = await startDevServer({
|
|
17
|
-
packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
|
|
18
|
-
});
|
|
19
|
-
process.env.SERIOUSGAMING_DEV_URL = server.url;
|
|
20
|
-
return () => server.stop();
|
|
21
|
-
}
|
|
10
|
+
export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
|
|
@@ -2,18 +2,15 @@ import { defineConfig } from '@playwright/test';
|
|
|
2
2
|
|
|
3
3
|
export default defineConfig({
|
|
4
4
|
testDir: './testing/e2e',
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
// SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
|
|
5
|
+
// Builds the game's surfaces once for the run, so every worker's dev
|
|
6
|
+
// server serves them as files rather than compiling them again.
|
|
8
7
|
globalSetup: './testing/e2e/global-setup.ts',
|
|
9
|
-
//
|
|
10
|
-
//
|
|
11
|
-
//
|
|
12
|
-
|
|
8
|
+
// Every worker starts its own isolated dev server (the `test` the specs
|
|
9
|
+
// import from `@seriousgaming/sdk-tools/playwright`), so tests in
|
|
10
|
+
// different workers never share a session and can run side by side. Tests
|
|
11
|
+
// that land in the same worker share its server one after another, which
|
|
12
|
+
// is why each spec starts the session again in `beforeEach`.
|
|
13
|
+
fullyParallel: true,
|
|
13
14
|
// A stray `test.only` passes locally and silently skips the rest on CI.
|
|
14
15
|
forbidOnly: !!process.env.CI,
|
|
15
|
-
use: {
|
|
16
|
-
// Read again in each worker, after the global setup has set it.
|
|
17
|
-
baseURL: process.env.SERIOUSGAMING_DEV_URL,
|
|
18
|
-
},
|
|
19
16
|
});
|
|
@@ -2,18 +2,15 @@ import { defineConfig } from '@playwright/test';
|
|
|
2
2
|
|
|
3
3
|
export default defineConfig({
|
|
4
4
|
testDir: './testing/e2e',
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
// SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
|
|
5
|
+
// Builds the game's surfaces once for the run, so every worker's dev
|
|
6
|
+
// server serves them as files rather than compiling them again.
|
|
8
7
|
globalSetup: './testing/e2e/global-setup.ts',
|
|
9
|
-
//
|
|
10
|
-
//
|
|
11
|
-
//
|
|
12
|
-
|
|
8
|
+
// Every worker starts its own isolated dev server (the `test` the specs
|
|
9
|
+
// import from `@seriousgaming/sdk-tools/playwright`), so tests in
|
|
10
|
+
// different workers never share a session and can run side by side. Tests
|
|
11
|
+
// that land in the same worker share its server one after another, which
|
|
12
|
+
// is why each spec starts the session again in `beforeEach`.
|
|
13
|
+
fullyParallel: true,
|
|
13
14
|
// A stray `test.only` passes locally and silently skips the rest on CI.
|
|
14
15
|
forbidOnly: !!process.env.CI,
|
|
15
|
-
use: {
|
|
16
|
-
// Read again in each worker, after the global setup has set it.
|
|
17
|
-
baseURL: process.env.SERIOUSGAMING_DEV_URL,
|
|
18
|
-
},
|
|
19
16
|
});
|
|
@@ -1,21 +1,10 @@
|
|
|
1
|
-
import { dirname } from 'path';
|
|
2
|
-
|
|
3
|
-
import type { FullConfig } from '@playwright/test';
|
|
4
|
-
import { startDevServer } from '@seriousgaming/sdk-tools/client';
|
|
5
|
-
|
|
6
1
|
/**
|
|
7
|
-
*
|
|
2
|
+
* Build the game's surfaces once, before any test runs, and remove the build
|
|
3
|
+
* after the last.
|
|
8
4
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
* which a run cannot hang on.
|
|
5
|
+
* Every worker's dev server then serves the build as files, so a page loads at
|
|
6
|
+
* once instead of each server compiling the same surfaces through Vite. Set
|
|
7
|
+
* SERIOUSGAMING_BUILT_SURFACES=dist to serve the output of your own
|
|
8
|
+
* `pnpm run sdk build` instead, and build nothing here.
|
|
14
9
|
*/
|
|
15
|
-
export
|
|
16
|
-
const server = await startDevServer({
|
|
17
|
-
packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
|
|
18
|
-
});
|
|
19
|
-
process.env.SERIOUSGAMING_DEV_URL = server.url;
|
|
20
|
-
return () => server.stop();
|
|
21
|
-
}
|
|
10
|
+
export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
|
package/dist/utils/prompt.d.ts
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
*
|
|
10
10
|
* Import prompts from here, never from `@inquirer/prompts` directly.
|
|
11
11
|
*/
|
|
12
|
-
import * as
|
|
12
|
+
import type * as Inquirer from '@inquirer/prompts';
|
|
13
13
|
export declare function canPrompt(): boolean;
|
|
14
14
|
/** For tests that drive the prompts through a mock: force the gate open or shut. */
|
|
15
15
|
export declare function setInteractiveOverride(value: boolean | null): void;
|
|
@@ -20,11 +20,11 @@ export declare function setAssumeYes(value: boolean): void;
|
|
|
20
20
|
* prompt is refused.
|
|
21
21
|
*/
|
|
22
22
|
export declare function setPromptUsage(value: string | undefined): void;
|
|
23
|
-
export declare const input: typeof
|
|
24
|
-
export declare const select: typeof
|
|
25
|
-
export declare const checkbox: typeof
|
|
23
|
+
export declare const input: typeof Inquirer.input;
|
|
24
|
+
export declare const select: typeof Inquirer.select;
|
|
25
|
+
export declare const checkbox: typeof Inquirer.checkbox;
|
|
26
26
|
/** A yes/no question that is part of the input, such as 'Add another property?'. */
|
|
27
|
-
export declare const confirm: typeof
|
|
27
|
+
export declare const confirm: typeof Inquirer.confirm;
|
|
28
28
|
/**
|
|
29
29
|
* 'Are you sure?': a confirmation `--yes` answers. Without a terminal and
|
|
30
30
|
* without `--yes` it is a usage error, so a script never deletes by accident
|