@seriousgaming/sdk-tools 1.10.0 → 1.12.0

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.
Files changed (219) hide show
  1. package/dist/agent/guidance.md +35 -23
  2. package/dist/{cli-F2D4GGUA.js → cli-2BKEIIA3.js} +66 -0
  3. package/dist/{cli-NQSL2CIH.js → cli-2QGTDHRX.js} +21 -21
  4. package/dist/{cli-33MZSPPK.js → cli-2SDG3SZ7.js} +21 -21
  5. package/dist/{cli-CLO7HKEQ.js → cli-2VXP34R5.js} +5 -3
  6. package/dist/{cli-P3NUTOPK.js → cli-2W4B6PD5.js} +1 -1
  7. package/dist/{cli-SOO6SEIS.js → cli-2X7DKSXN.js} +28 -25
  8. package/dist/{cli-LNEZ6KDW.js → cli-2ZP4N7HK.js} +19 -19
  9. package/dist/{cli-5O7XENQY.js → cli-3GJYZH4C.js} +5 -5
  10. package/dist/{cli-NAZTYKZT.js → cli-3GO3M2MX.js} +30 -14
  11. package/dist/{cli-YZJBFKRI.js → cli-3LDLUNME.js} +17 -17
  12. package/dist/{cli-J42N4PJG.js → cli-3WY6L2WP.js} +31 -29
  13. package/dist/{cli-WG7MAOCS.js → cli-44MBABRD.js} +25 -25
  14. package/dist/{cli-MGZYQDCH.js → cli-4IO7MKLR.js} +20 -20
  15. package/dist/{cli-HNDFANQG.js → cli-4U2PY7W3.js} +1 -1
  16. package/dist/{cli-4JNF3O5N.js → cli-4WI4LTBI.js} +2 -2
  17. package/dist/{cli-OTBCA54D.js → cli-55EIGGZK.js} +1 -1
  18. package/dist/{cli-5TKPT3CY.js → cli-5AQV6FTL.js} +18 -18
  19. package/dist/{cli-KNXY43YV.js → cli-5CW7BEU7.js} +3 -3
  20. package/dist/{cli-5V4N4BR4.js → cli-5JUVHNZF.js} +12 -12
  21. package/dist/{cli-F3YJKP6D.js → cli-5KERL6HV.js} +9 -4
  22. package/dist/{cli-HN442ZVK.js → cli-5KSA24NQ.js} +24 -24
  23. package/dist/{cli-5VZBFMCK.js → cli-5PIFO3EN.js} +8 -0
  24. package/dist/{cli-IQBY7Z7Q.js → cli-5QN2Z43X.js} +20 -20
  25. package/dist/cli-5XSPAA5X.js +69 -0
  26. package/dist/{cli-QW7VXL2V.js → cli-62KAYGXO.js} +20 -20
  27. package/dist/{cli-TDLIPYKT.js → cli-6IMV5ZZU.js} +26 -26
  28. package/dist/{cli-UULZSQBV.js → cli-6KWCIAN2.js} +764 -66
  29. package/dist/{cli-2ANX6E3A.js → cli-6NWETIX5.js} +20 -20
  30. package/dist/{cli-EXUPHPDJ.js → cli-774W3MN5.js} +26 -26
  31. package/dist/cli-7BUD3VAD.js +16 -0
  32. package/dist/{cli-7NUFHMGE.js → cli-7KEP57S7.js} +12 -12
  33. package/dist/{cli-6CYAOUYT.js → cli-7OYFJMA6.js} +18 -18
  34. package/dist/{cli-ILHHJR2S.js → cli-7ZNEDQ3G.js} +20 -20
  35. package/dist/{cli-5RRPUL6V.js → cli-AFK6OUID.js} +12 -12
  36. package/dist/{cli-A3AJQZEN.js → cli-AIYQFWXN.js} +25 -25
  37. package/dist/{cli-B5DWKRZ4.js → cli-ARAAEWIQ.js} +2 -2
  38. package/dist/cli-AVQYV3N4.js +36 -0
  39. package/dist/{cli-35GV2F6R.js → cli-B54Z6CXH.js} +16 -16
  40. package/dist/{cli-467VRXGP.js → cli-B5TC4MEL.js} +5 -5
  41. package/dist/{cli-5Z4D3F6Y.js → cli-BCXGOLU3.js} +3 -3
  42. package/dist/{cli-G2GLW5Z4.js → cli-BHAODVTZ.js} +1 -1
  43. package/dist/{cli-XR3O2YTV.js → cli-BPS2JG74.js} +20 -20
  44. package/dist/{cli-W3RG2MRI.js → cli-BVO55SR2.js} +2 -2
  45. package/dist/{cli-PYAST3G5.js → cli-CFH3JZP5.js} +21 -21
  46. package/dist/{cli-VZVHS5AP.js → cli-CTK2OIK6.js} +20 -20
  47. package/dist/{cli-ATWJCB2G.js → cli-CW5MV4VX.js} +4 -4
  48. package/dist/{cli-TCQJL2GY.js → cli-D5VOSJZ7.js} +1 -1
  49. package/dist/{cli-KIZTASLL.js → cli-DAEPMK7A.js} +5 -5
  50. package/dist/{cli-44CM2AH2.js → cli-DAHR7PKB.js} +1 -1
  51. package/dist/{cli-XW3JLRSA.js → cli-DWDSBTYL.js} +1 -1
  52. package/dist/cli-DYSDPGXW.js +95 -0
  53. package/dist/{cli-GRSQRFRG.js → cli-DZCLRZXJ.js} +9 -2
  54. package/dist/{cli-RSF5R3HC.js → cli-EJ47IE45.js} +28 -25
  55. package/dist/{cli-QDBYFITU.js → cli-EK4OSJHA.js} +2 -2
  56. package/dist/{cli-GO64NABP.js → cli-FCJHNXDA.js} +1 -1
  57. package/dist/{cli-ZNQBF4Z3.js → cli-FNESSE3L.js} +1 -1
  58. package/dist/{cli-MUOLHQNL.js → cli-FTLH4WCE.js} +17 -17
  59. package/dist/{cli-JHLWBRXB.js → cli-FYV77YS2.js} +18 -18
  60. package/dist/cli-GMJX6Q4Q.js +36 -0
  61. package/dist/{cli-7JUNA74L.js → cli-GRBVNGDW.js} +1 -1
  62. package/dist/{cli-XKAIDYIE.js → cli-HAFCFY77.js} +33 -19
  63. package/dist/{cli-OXLOGXT3.js → cli-HCJLYI24.js} +3 -3
  64. package/dist/{cli-HHRP6FP6.js → cli-HCXS5EXU.js} +25 -25
  65. package/dist/cli-HEUNNHDH.js +36 -0
  66. package/dist/{cli-36GABN2A.js → cli-HNUTIWDZ.js} +19 -19
  67. package/dist/{cli-JXQLHJO2.js → cli-HXT25ETJ.js} +244 -243
  68. package/dist/{cli-5EH4WTH4.js → cli-IGEL7UJQ.js} +5 -5
  69. package/dist/{cli-JMNPMDXH.js → cli-IO32YA5N.js} +26 -26
  70. package/dist/cli-IPTGZDBB.js +36 -0
  71. package/dist/{cli-L54SXUK6.js → cli-J25TYFKB.js} +19 -19
  72. package/dist/{cli-CQ4ZR3ZQ.js → cli-J7XYMEMX.js} +20 -20
  73. package/dist/{cli-5DWR7RPQ.js → cli-JC5OJRID.js} +2 -2
  74. package/dist/{cli-25SJZI7N.js → cli-JD563OF4.js} +126 -27
  75. package/dist/{cli-JAVMRERQ.js → cli-JRJF2WHU.js} +20 -20
  76. package/dist/{cli-UQC46YSV.js → cli-JTFLIMIG.js} +3 -3
  77. package/dist/{cli-2AH6D32V.js → cli-K2BSJ2PK.js} +2 -2
  78. package/dist/{cli-XB5PI2XT.js → cli-K4QTYMN2.js} +25 -25
  79. package/dist/{cli-5SHG2M7E.js → cli-KFJDD4C4.js} +20 -20
  80. package/dist/{cli-WW54THXN.js → cli-KVQ2JPVD.js} +1 -1
  81. package/dist/{cli-O5WYATAI.js → cli-L6AHMW2Z.js} +4 -2
  82. package/dist/{cli-IKSLPAZN.js → cli-LCYUBCVY.js} +4 -4
  83. package/dist/{cli-HGCOEL5T.js → cli-LEWSCDH5.js} +4 -4
  84. package/dist/{cli-HNG6PZW2.js → cli-LI6G7GND.js} +27 -27
  85. package/dist/{cli-2AVPNSAX.js → cli-LU2GCWIU.js} +21 -21
  86. package/dist/{cli-UEQMK4WX.js → cli-M3Z2KOEB.js} +1 -1
  87. package/dist/{cli-226ZJ72R.js → cli-M6E3E3I2.js} +170 -3
  88. package/dist/{cli-OXU6TTEN.js → cli-MCRPA4Z6.js} +20 -20
  89. package/dist/{cli-BQ36DV5C.js → cli-MI2DEDMA.js} +3 -3
  90. package/dist/{cli-6O7YCK2M.js → cli-MITZ6SE7.js} +3 -3
  91. package/dist/{cli-VALLLE6Y.js → cli-MTIYD3BX.js} +26 -26
  92. package/dist/{cli-5M6KDNVX.js → cli-MTZUJGBK.js} +2 -2
  93. package/dist/{cli-GSOV26O5.js → cli-NCLMUXLC.js} +14 -14
  94. package/dist/{cli-Z3DITVBE.js → cli-NLS3DKWH.js} +26 -26
  95. package/dist/{cli-AH6AMAIB.js → cli-NMDGS7IE.js} +1 -1
  96. package/dist/cli-O3DJO2CS.js +30 -0
  97. package/dist/{cli-BC67QHD5.js → cli-O47D5BFN.js} +2 -2
  98. package/dist/{cli-MDVC5ZNM.js → cli-OBRZ36VP.js} +14 -14
  99. package/dist/{cli-267QJ2DS.js → cli-OMG4E53H.js} +20 -20
  100. package/dist/{cli-C32Q5E5I.js → cli-P6V3NSU4.js} +1 -1
  101. package/dist/{cli-PBSLPO6G.js → cli-PAMQMTHK.js} +21 -21
  102. package/dist/{cli-RUEPTOWG.js → cli-PKTHOCT3.js} +26 -26
  103. package/dist/{cli-PTXOKO2Y.js → cli-QK7QAP5H.js} +18 -18
  104. package/dist/cli-QQ432JEN.js +36 -0
  105. package/dist/{cli-YFLQ7XOO.js → cli-QVNDPTBU.js} +20 -20
  106. package/dist/{cli-KJA6GLZI.js → cli-R2DFD6ZZ.js} +15 -15
  107. package/dist/{cli-6BLVI2JM.js → cli-RMVJMOWU.js} +111 -7
  108. package/dist/{cli-M6AZFIMV.js → cli-RQISHMJF.js} +88 -23
  109. package/dist/{cli-X64BNBQH.js → cli-RVZH462G.js} +585 -8
  110. package/dist/{cli-LLJQI2QP.js → cli-SEEOQVUL.js} +12 -12
  111. package/dist/{cli-QTCTWYCM.js → cli-SO354HPI.js} +3 -3
  112. package/dist/{cli-URCHZDTS.js → cli-T76HDH7F.js} +90 -5
  113. package/dist/{cli-ZJW6HQ6N.js → cli-TIS7DWRR.js} +7 -7
  114. package/dist/{cli-WOFYI7HZ.js → cli-TY3B6XS7.js} +21 -21
  115. package/dist/{cli-4FJL3KQZ.js → cli-UKEZJFIT.js} +2 -2
  116. package/dist/cli-VQAMW4RF.js +95 -0
  117. package/dist/{cli-4A7RWFNO.js → cli-W4LMRVZT.js} +78 -47
  118. package/dist/cli-W7I5KGIB.js +84 -0
  119. package/dist/{cli-B3EFE7ZF.js → cli-WXGJFA4F.js} +1 -1
  120. package/dist/{cli-IPTHJT3J.js → cli-XCG33I77.js} +28 -25
  121. package/dist/{cli-WLSACMYA.js → cli-YHLSG5HB.js} +30 -28
  122. package/dist/cli-YNH5DTHY.js +36 -0
  123. package/dist/cli-YPMJWPDA.js +69 -0
  124. package/dist/{cli-PXQYY6KM.js → cli-YSXIR7EM.js} +0 -0
  125. package/dist/cli-ZPFWO4VW.js +85 -0
  126. package/dist/cli.js +53 -53
  127. package/dist/client/index.d.ts +1 -1
  128. package/dist/client/test-session.d.ts +44 -6
  129. package/dist/client.js +1934 -286
  130. package/dist/core/assessment-moves.d.ts +32 -0
  131. package/dist/core/assessment-reports.d.ts +38 -0
  132. package/dist/core/assessment-settings.d.ts +15 -0
  133. package/dist/core/benchmark-samples.d.ts +28 -0
  134. package/dist/core/session-host.d.ts +4 -0
  135. package/dist/core/session-roster.d.ts +6 -0
  136. package/dist/core/session-timers.d.ts +40 -0
  137. package/dist/core/session.d.ts +14 -1
  138. package/dist/core/tick-timer.d.ts +18 -0
  139. package/dist/dev/console/assets/{index-Ch6HHb2T.js → index-zd--5H1f.js} +26 -26
  140. package/dist/dev/console/index.html +1 -1
  141. package/dist/dev/shell.d.ts +8 -0
  142. package/dist/dev/view/commands.d.ts +3 -1
  143. package/dist/docs/api/index.md +4 -2
  144. package/dist/docs/api/sdk-commands.md +29 -0
  145. package/dist/docs/api/sdk-e2e.md +30 -0
  146. package/dist/docs/api/sdk-projection.md +5 -0
  147. package/dist/docs/api/sdk-tools-client.md +68 -6
  148. package/dist/docs/api/sdk-tools-vite.md +21 -0
  149. package/dist/docs/api/sdk-ui.md +7 -0
  150. package/dist/docs/api/sdk.md +834 -19
  151. package/dist/docs/changelog.md +67 -0
  152. package/dist/docs/cli-error-codes.md +5 -1
  153. package/dist/docs/cli-reference.md +76 -2
  154. package/dist/docs/concepts/index.md +2 -0
  155. package/dist/docs/concepts/terminology.md +12 -0
  156. package/dist/docs/guides/assessments.md +248 -0
  157. package/dist/docs/guides/benchmarks.md +241 -0
  158. package/dist/docs/guides/endpoints.md +1 -1
  159. package/dist/docs/guides/engine-testing.md +49 -14
  160. package/dist/docs/guides/engine.md +10 -2
  161. package/dist/docs/guides/index.md +2 -0
  162. package/dist/docs/guides/presentation.md +11 -9
  163. package/dist/docs/guides/session-hooks.md +24 -22
  164. package/dist/docs/guides/testing.md +3 -8
  165. package/dist/docs/guides/tick-controller.md +22 -1
  166. package/dist/docs/guides/ui.md +24 -0
  167. package/dist/docs/guides/upgrading.md +36 -0
  168. package/dist/docs/page-index.md +18 -13
  169. package/dist/docs/recipes/create-assessment.md +124 -0
  170. package/dist/docs/recipes/create-benchmark.md +115 -0
  171. package/dist/docs/recipes/create-game.md +1 -1
  172. package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
  173. package/dist/docs/recipes/index.md +2 -0
  174. package/dist/execution/context-composition.d.ts +39 -4
  175. package/dist/execution/engine-state.d.ts +13 -0
  176. package/dist/execution/executor.d.ts +16 -0
  177. package/dist/execution/logic-result.d.ts +13 -2
  178. package/dist/help-examples.d.ts +12 -0
  179. package/dist/host/adapter.d.ts +24 -1
  180. package/dist/host/protocol.d.ts +115 -1
  181. package/dist/host.js +29 -1
  182. package/dist/oxlint/logic.json +184 -0
  183. package/dist/playwright.js +1928 -280
  184. package/dist/runtime/index.d.ts +3 -1
  185. package/dist/runtime/manifest-version.d.ts +1 -1
  186. package/dist/runtime.js +298 -16
  187. package/dist/schema.json +189 -0
  188. package/dist/templates/package/README.md.liquid +1 -0
  189. package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
  190. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  191. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  192. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
  193. package/dist/templates/package/claude/settings.json.template +1 -0
  194. package/dist/templates/package/oxfmtrc.json.template +8 -1
  195. package/dist/templates/package/oxlintrc.json.template +1 -180
  196. package/dist/templates/package/package.json.liquid +1 -0
  197. package/dist/templates/package/vite.config.ts.liquid +2 -8
  198. package/dist/templates/package/vitest.config.ts.liquid +2 -8
  199. package/dist/templates/starter-game/package.json +2 -1
  200. package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
  201. package/dist/templates/starter-game/vite.config.ts +2 -8
  202. package/dist/templates/starter-game/vitest.config.ts +4 -3
  203. package/dist/templating/resource-metadata.d.ts +1 -1
  204. package/dist/utils/error-codes.d.ts +9 -1
  205. package/dist/utils/resource-scan.d.ts +5 -0
  206. package/dist/validation/assessment-validation.d.ts +34 -0
  207. package/dist/validation/benchmark-validation.d.ts +20 -0
  208. package/dist/validation/schema-validation.d.ts +4 -0
  209. package/dist/vite/index.d.ts +30 -0
  210. package/dist/vite.js +12 -0
  211. package/package.json +12 -4
  212. package/dist/cli-27Z5T52R.js +0 -30
  213. package/dist/cli-5XE4OMFL.js +0 -36
  214. package/dist/cli-BB6CU4ZC.js +0 -36
  215. package/dist/cli-FGP6YYM7.js +0 -36
  216. package/dist/cli-I3ZAZYWP.js +0 -36
  217. package/dist/cli-RFAPPYXK.js +0 -36
  218. package/dist/cli-WZNIW6ZO.js +0 -16
  219. package/dist/cli-XEEOJGBL.js +0 -36
@@ -18,7 +18,7 @@ A user interface is a React app that reads game state and (optionally) sends dec
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.
21
- 7. **Verify**: `pnpm run build` and `pnpm test:run`. A running dev server hot-reloads the UI. The user starts the dev server (`pnpm run sdk dev`) when they want to see it; never start it yourself.
21
+ 7. **Verify**: `pnpm check`, then `pnpm run build`. A running dev server hot-reloads the UI. The user starts the dev server (`pnpm run sdk dev`) when they want to see it; never start it yourself.
22
22
 
23
23
  ## Things that almost always go wrong
24
24
 
@@ -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 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`.
21
+ 5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`, or `pnpm check` for both after validating, typechecking and linting. `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
 
@@ -26,9 +26,9 @@ The SDK ships as three npm packages: `@seriousgaming/sdk` (runtime), `@seriousga
26
26
  The package also lists `@seriousgaming/sdk` under `peerDependencies`; move that range to match.
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
- 6. **Run the test suites**: `pnpm test:run` and `pnpm test:engine`.
29
+ 6. **Run the checks**: `pnpm check`, or `pnpm test:run` and `pnpm test:engine` in a package that has no `check` script yet.
30
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
- 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.
31
+ 1. The **Scaffold changes** section of every release between the old and new version (from step 2; releases from 1.11 carry one whenever a scaffolded file, a shipped rule or the guidance changed). Each line names a file, says what changed and why, and ends with `Adopt:` and whether to. Work through them in order, oldest release first, applying each `Adopt: yes` to the local file and weighing each `Adopt: optional`. For a release before 1.11, read its entries for anything mentioning scaffold, guidance, rules, or `CLAUDE.md`.
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
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
 
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "permissions": {
3
3
  "allow": [
4
+ "Bash(pnpm check)",
4
5
  "Bash(pnpm run generate)",
5
6
  "Bash(pnpm run --silent sdk build --validate-only:*)",
6
7
  "Bash(pnpm run --silent sdk view:*)",
@@ -1,6 +1,13 @@
1
1
  {
2
2
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
3
- "ignorePatterns": ["**/*.sdk.json", "seriousgaming.sdk.json", "**/types.ts"],
3
+ "ignorePatterns": [
4
+ "**/*.sdk.json",
5
+ "seriousgaming.sdk.json",
6
+ "**/types.ts",
7
+ "lib/",
8
+ "test-results/",
9
+ "playwright-report/"
10
+ ],
4
11
  "semi": true,
5
12
  "trailingComma": "es5",
6
13
  "singleQuote": true,
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "$schema": "./node_modules/oxlint/configuration_schema.json",
3
+ "extends": ["./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json"],
3
4
  "plugins": null,
4
5
  "categories": {},
5
6
  "rules": {
@@ -41,186 +42,6 @@
41
42
  "globals": {},
42
43
  "ignorePatterns": ["**/types.ts"],
43
44
  "overrides": [
44
- {
45
- "files": [
46
- "engine/**/*.ts",
47
- "tick_controller/**/*.ts",
48
- "**/hooks/*/logic/**/*.ts",
49
- "**/validators/*/logic/**/*.ts",
50
- "**/endpoints/*/logic/**/*.ts"
51
- ],
52
- "rules": {
53
- "no-restricted-globals": [
54
- "error",
55
- {
56
- "name": "structuredClone",
57
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Context is JSON-serialisable, so JSON.parse(JSON.stringify(value)) is the portable equivalent."
58
- },
59
- {
60
- "name": "TextEncoder",
61
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Import encodeUtf8 from @seriousgaming/sdk instead."
62
- },
63
- {
64
- "name": "TextDecoder",
65
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Import decodeUtf8 from @seriousgaming/sdk instead."
66
- },
67
- {
68
- "name": "fetch",
69
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Reach external services through the injected callbacks, or through an endpoint."
70
- },
71
- {
72
- "name": "XMLHttpRequest",
73
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Reach external services through the injected callbacks, or through an endpoint."
74
- },
75
- {
76
- "name": "setTimeout",
77
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
78
- },
79
- {
80
- "name": "setInterval",
81
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
82
- },
83
- {
84
- "name": "setImmediate",
85
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
86
- },
87
- {
88
- "name": "queueMicrotask",
89
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
90
- },
91
- {
92
- "name": "process",
93
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Settings reach logic through the `settings` argument."
94
- },
95
- {
96
- "name": "Buffer",
97
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Use Uint8Array, with the SDK's encodeUtf8 / decodeUtf8 for string conversion."
98
- },
99
- {
100
- "name": "URL",
101
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Build asset URLs from the references and callbacks the runtime injects."
102
- },
103
- {
104
- "name": "clearTimeout",
105
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
106
- },
107
- {
108
- "name": "clearInterval",
109
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
110
- },
111
- {
112
- "name": "clearImmediate",
113
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
114
- },
115
- {
116
- "name": "URLSearchParams",
117
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
118
- },
119
- {
120
- "name": "crypto",
121
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
122
- },
123
- {
124
- "name": "atob",
125
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
126
- },
127
- {
128
- "name": "btoa",
129
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
130
- },
131
- {
132
- "name": "performance",
133
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
134
- },
135
- {
136
- "name": "ReadableStream",
137
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
138
- },
139
- {
140
- "name": "WritableStream",
141
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
142
- },
143
- {
144
- "name": "TransformStream",
145
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
146
- },
147
- {
148
- "name": "Blob",
149
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
150
- },
151
- {
152
- "name": "File",
153
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
154
- },
155
- {
156
- "name": "FormData",
157
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
158
- },
159
- {
160
- "name": "Headers",
161
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
162
- },
163
- {
164
- "name": "Request",
165
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
166
- },
167
- {
168
- "name": "Response",
169
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
170
- },
171
- {
172
- "name": "AbortController",
173
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
174
- },
175
- {
176
- "name": "EventTarget",
177
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
178
- },
179
- {
180
- "name": "WebSocket",
181
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
182
- },
183
- {
184
- "name": "localStorage",
185
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
186
- },
187
- {
188
- "name": "sessionStorage",
189
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
190
- },
191
- {
192
- "name": "window",
193
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
194
- },
195
- {
196
- "name": "document",
197
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
198
- },
199
- {
200
- "name": "navigator",
201
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
202
- },
203
- {
204
- "name": "require",
205
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
206
- },
207
- {
208
- "name": "__dirname",
209
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
210
- },
211
- {
212
- "name": "__filename",
213
- "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
214
- }
215
- ]
216
- }
217
- },
218
- {
219
- "files": ["**/*.test.ts", "**/*.spec.ts"],
220
- "rules": {
221
- "no-restricted-globals": "off"
222
- }
223
- },
224
45
  {
225
46
  "files": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/testing/**"],
226
47
  "rules": {
@@ -11,6 +11,7 @@
11
11
  "scripts": {
12
12
  "generate": "pnpm run sdk generate",
13
13
  "build": "pnpm run sdk build",
14
+ "check": "pnpm run --silent sdk build --validate-only && pnpm run --silent typecheck && pnpm run --silent lint && pnpm run --silent test:run --passWithNoTests && pnpm run --silent test:engine --passWithNoTests",
14
15
  "start": "pnpm run sdk dev",
15
16
  "test": "vitest",
16
17
  "test:run": "vitest run",
@@ -1,3 +1,4 @@
1
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
1
2
  import { defineConfig } from 'vite';
2
3
 
3
4
  export default defineConfig({
@@ -7,13 +8,6 @@ export default defineConfig({
7
8
  // hook reads empty data: React's "Invalid hook call" when MUI bundles
8
9
  // its own React, or an SDK hook in a shared package of yours that
9
10
  // finds none of the providers the host set up.
10
- dedupe: [
11
- 'react',
12
- 'react-dom',
13
- '@emotion/react',
14
- '@emotion/styled',
15
- '@seriousgaming/sdk',
16
- '@seriousgaming/deck',
17
- ],
11
+ dedupe: [...REACT_CONTEXT_PACKAGES],
18
12
  },
19
13
  });
@@ -1,17 +1,11 @@
1
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
1
2
  import { defineConfig } from 'vitest/config';
2
3
 
3
4
  export default defineConfig({
4
5
  resolve: {
5
6
  // The same single copies vite.config.ts asks for, so a test renders
6
7
  // with the providers the component reads.
7
- dedupe: [
8
- 'react',
9
- 'react-dom',
10
- '@emotion/react',
11
- '@emotion/styled',
12
- '@seriousgaming/sdk',
13
- '@seriousgaming/deck',
14
- ],
8
+ dedupe: [...REACT_CONTEXT_PACKAGES],
15
9
  },
16
10
  esbuild: {
17
11
  jsx: 'automatic',
@@ -13,6 +13,7 @@
13
13
  "scripts": {
14
14
  "generate": "pnpm run sdk generate",
15
15
  "build": "pnpm run sdk build",
16
+ "check": "pnpm run --silent sdk build --validate-only && pnpm run --silent typecheck && pnpm run --silent lint && pnpm run --silent test:run --passWithNoTests && pnpm run --silent test:engine --passWithNoTests",
16
17
  "start": "pnpm run sdk dev",
17
18
  "test": "vitest",
18
19
  "test:run": "vitest run",
@@ -22,7 +23,7 @@
22
23
  "lint:fix": "oxlint --fix",
23
24
  "format": "oxfmt",
24
25
  "format:check": "oxfmt --check",
25
- "typecheck": "tsc --noEmit",
26
+ "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsc/typecheck.tsbuildinfo",
26
27
  "sdk": "vite-node node_modules/@seriousgaming/sdk-tools/cli/cli.ts",
27
28
  "test:e2e": "playwright test"
28
29
  },
@@ -12,29 +12,25 @@
12
12
  * Run with: pnpm test:engine
13
13
  */
14
14
 
15
+ import { readdirSync } from 'fs';
16
+ import { join } from 'path';
15
17
  import { fileURLToPath } from 'url';
16
18
 
17
19
  import { createTestSession, type TestSession } from '@seriousgaming/sdk-tools/client';
18
20
  import { afterEach, beforeEach, describe, expect, it } from 'vitest';
19
21
 
20
- const PACKAGE_PATH = fileURLToPath(new URL('../..', import.meta.url));
21
-
22
- type Context = Record<string, unknown>;
23
-
24
- /** The context is untyped here, so each read says what it expects to find. */
25
- const cap = (context: Context, key: string) => context[key] as Record<string, unknown>;
26
-
27
- const numberField = (context: Context, key: string, field: string) =>
28
- cap(context, key)[field] as number;
22
+ // The engine's generated `Context` holds the capabilities the engine reads and
23
+ // writes, which are the ones these tests play. A capability only a hook or a
24
+ // surface writes is in the team's context too, and not in this type.
25
+ import type { Context } from '../../engine/types';
29
26
 
30
- const mapField = (context: Context, key: string, field: string) =>
31
- cap(context, key)[field] as Record<string, number>;
27
+ const PACKAGE_PATH = fileURLToPath(new URL('../..', import.meta.url));
32
28
 
33
29
  describe('Lemonade Stand', () => {
34
- let game: TestSession;
30
+ let game: TestSession<Context>;
35
31
 
36
32
  beforeEach(async () => {
37
- game = await createTestSession({ packagePath: PACKAGE_PATH });
33
+ game = await createTestSession<Context>({ packagePath: PACKAGE_PATH });
38
34
  });
39
35
 
40
36
  afterEach(async () => {
@@ -52,8 +48,14 @@ describe('Lemonade Stand', () => {
52
48
 
53
49
  /** Open the stall for a day, and fail loudly if the session refused. */
54
50
  const tick = async (): Promise<Context> => {
55
- const result = await game.send({ type: 'tick' });
56
- if (!result.ok) throw new Error(`The day was refused: ${JSON.stringify(result.outcome)}`);
51
+ const result = await game.tick();
52
+ if (!result.ok) {
53
+ // When the engine threw, the result says where: the same file,
54
+ // line, tick and team `sdk tick` reports.
55
+ const at = result.logicError;
56
+ const where = at ? ` at ${at.file}:${at.line} (tick ${at.tick})` : '';
57
+ throw new Error(`The day was refused: ${result.outcome.kind}${where}`);
58
+ }
57
59
  return stall();
58
60
  };
59
61
 
@@ -67,11 +69,10 @@ describe('Lemonade Stand', () => {
67
69
  expect(result.ok).toBe(true);
68
70
  };
69
71
 
70
- const lines = (context: Context) =>
71
- cap(context, 'results').Lines as Record<string, Record<string, number>>;
72
+ const lines = (context: Context) => context.results.Lines;
72
73
 
73
74
  it('starts every item on the menu at a number the stall can make', () => {
74
- const plan = mapField(stall(), 'plan', 'Make');
75
+ const plan = stall().plan.Make;
75
76
 
76
77
  expect(Object.keys(plan).sort()).toEqual(['cookies', 'icedtea', 'lemonade']);
77
78
  expect(Object.values(plan).reduce((sum, count) => sum + count, 0)).toBeLessThanOrEqual(120);
@@ -79,8 +80,8 @@ describe('Lemonade Stand', () => {
79
80
 
80
81
  it('opens with nothing traded and a forecast for the first day', () => {
81
82
  expect(day()).toBe(0);
82
- expect(numberField(stall(), 'results', 'Day')).toBe(0);
83
- expect(['sunny', 'cloudy', 'rainy']).toContain(cap(stall(), 'weather').Today);
83
+ expect(stall().results.Day).toBe(0);
84
+ expect(['sunny', 'cloudy', 'rainy']).toContain(stall().weather.Today);
84
85
  });
85
86
 
86
87
  it('sells what it made, and turns the rest away', async () => {
@@ -98,32 +99,30 @@ describe('Lemonade Stand', () => {
98
99
 
99
100
  expect(lines(context).cookies!.PouredAway).toBeGreaterThan(0);
100
101
  // 100 cookies at 25p, whatever the day did.
101
- expect(numberField(context, 'results', 'Spent')).toBe(100 * 25);
102
- expect(numberField(context, 'results', 'Profit')).toBeLessThan(0);
102
+ expect(context.results.Spent).toBe(100 * 25);
103
+ expect(context.results.Profit).toBeLessThan(0);
103
104
  });
104
105
 
105
106
  it('makes more money matching the forecast than ignoring it', async () => {
106
- await make(mapField(stall(), 'weather', 'Expected'));
107
+ await make(stall().weather.Expected);
107
108
  for (let round = 0; round < 5; round += 1) await tick();
108
- const matched = numberField(stall(), 'results', 'Purse');
109
+ const matched = stall().results.Purse;
109
110
 
110
111
  expect((await game.send({ type: 'reinitialise' })).ok).toBe(true);
111
112
  await make({ lemonade: 0, icedtea: 0, cookies: 0 });
112
113
  for (let round = 0; round < 5; round += 1) await tick();
113
- const nothing = numberField(stall(), 'results', 'Purse');
114
+ const nothing = stall().results.Purse;
114
115
 
115
116
  expect(matched).toBeGreaterThan(nothing);
116
117
  });
117
118
 
118
119
  it('keeps a running purse across days', async () => {
119
- await make(mapField(stall(), 'weather', 'Expected'));
120
+ await make(stall().weather.Expected);
120
121
 
121
122
  const first = await tick();
122
123
  const second = await tick();
123
124
 
124
- expect(numberField(second, 'results', 'Purse')).toBe(
125
- numberField(first, 'results', 'Profit') + numberField(second, 'results', 'Profit')
126
- );
125
+ expect(second.results.Purse).toBe(first.results.Profit + second.results.Profit);
127
126
  });
128
127
 
129
128
  it('labels each day with its own number', async () => {
@@ -131,31 +130,31 @@ describe('Lemonade Stand', () => {
131
130
  await tick();
132
131
  await tick();
133
132
 
134
- expect(numberField(stall(), 'results', 'Day')).toBe(3);
133
+ expect(stall().results.Day).toBe(3);
135
134
  });
136
135
 
137
136
  it('plays the day it forecast, not a different one', async () => {
138
- const forecastForDayOne = cap(stall(), 'weather').Today;
137
+ const forecastForDayOne = stall().weather.Today;
139
138
 
140
139
  const context = await tick();
141
140
 
142
- expect(cap(context, 'results').Weather).toBe(forecastForDayOne);
141
+ expect(context.results.Weather).toBe(forecastForDayOne);
143
142
  // And it has moved on to forecasting day two.
144
- expect(['sunny', 'cloudy', 'rainy']).toContain(cap(context, 'weather').Today);
143
+ expect(['sunny', 'cloudy', 'rainy']).toContain(context.weather.Today);
145
144
  });
146
145
 
147
146
  it('leaves the plan alone, so yesterday carries into today', async () => {
148
147
  await make({ lemonade: 44, icedtea: 0, cookies: 0 });
149
148
  const context = await tick();
150
149
 
151
- expect(cap(context, 'plan').Make).toEqual({ lemonade: 44, icedtea: 0, cookies: 0 });
150
+ expect(context.plan.Make).toEqual({ lemonade: 44, icedtea: 0, cookies: 0 });
152
151
  });
153
152
 
154
153
  it('trades its ten days', async () => {
155
154
  for (let round = 0; round < 10; round += 1) await tick();
156
155
 
157
156
  expect(day()).toBe(10);
158
- expect(numberField(stall(), 'results', 'Day')).toBe(10);
157
+ expect(stall().results.Day).toBe(10);
159
158
  });
160
159
 
161
160
  it('undo takes back the last day', async () => {
@@ -165,7 +164,33 @@ describe('Lemonade Stand', () => {
165
164
  expect((await game.send({ type: 'undo' })).ok).toBe(true);
166
165
 
167
166
  expect(day()).toBe(0);
168
- expect(numberField(stall(), 'results', 'Purse')).toBe(0);
169
- expect(numberField(stall(), 'results', 'Day')).toBe(0);
167
+ expect(stall().results.Purse).toBe(0);
168
+ expect(stall().results.Day).toBe(0);
169
+ });
170
+ });
171
+
172
+ /**
173
+ * Every scenario has to start and play a day. A scenario overrides settings,
174
+ * and a value the engine cannot work with (a menu with no items, a demand of
175
+ * zero it divides by) only shows when the game is played on it. Read from disk
176
+ * rather than listed, so a new scenario is covered the day it is added.
177
+ */
178
+ describe('every scenario', () => {
179
+ const scenarios = readdirSync(join(PACKAGE_PATH, 'scenarios'), { withFileTypes: true })
180
+ .filter((entry) => entry.isDirectory())
181
+ .map((entry) => entry.name);
182
+
183
+ it('is a set this test can see', () => {
184
+ expect(scenarios.length).toBeGreaterThan(0);
185
+ });
186
+
187
+ it.each(scenarios)('%s starts and plays a day', async (scenarioId) => {
188
+ const game = await createTestSession<Context>({ packagePath: PACKAGE_PATH, scenarioId });
189
+ try {
190
+ expect(await game.tick()).toMatchObject({ ok: true });
191
+ expect(game.team(0).context.results.Day).toBe(1);
192
+ } finally {
193
+ await game.close();
194
+ }
170
195
  });
171
196
  });
@@ -1,3 +1,4 @@
1
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
1
2
  import { defineConfig } from 'vite';
2
3
 
3
4
  export default defineConfig({
@@ -7,13 +8,6 @@ export default defineConfig({
7
8
  // hook reads empty data: React's "Invalid hook call" when MUI bundles
8
9
  // its own React, or an SDK hook in a shared package of yours that
9
10
  // finds none of the providers the host set up.
10
- dedupe: [
11
- 'react',
12
- 'react-dom',
13
- '@emotion/react',
14
- '@emotion/styled',
15
- '@seriousgaming/sdk',
16
- '@seriousgaming/deck',
17
- ],
11
+ dedupe: [...REACT_CONTEXT_PACKAGES],
18
12
  },
19
13
  });
@@ -1,10 +1,11 @@
1
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
1
2
  import { defineConfig } from 'vitest/config';
2
3
 
3
4
  export default defineConfig({
4
5
  resolve: {
5
- // Ensure a single React instance is used across the project and
6
- // file:// SDK dependency, preventing "Invalid hook call" errors.
7
- dedupe: ['react', 'react-dom'],
6
+ // The same single copies vite.config.ts asks for, so a test renders
7
+ // with the providers the component reads.
8
+ dedupe: [...REACT_CONTEXT_PACKAGES],
8
9
  },
9
10
  test: {
10
11
  // Exclude engine tests (node env, separate config) and Playwright specs
@@ -45,7 +45,7 @@ export interface ReferenceSite {
45
45
  }
46
46
  export type ResourceKind = 'logic' | 'ui' | 'composition' | 'content';
47
47
  /** Every registered resource type, so a stale type name is a compile error. */
48
- export declare const RESOURCE_TYPES: readonly ["capability", "engine", "ui", "session", "waiting_room", "presentation", "setup", "scenario_editor", "scenario", "guide", "tick_controller", "hook", "validator", "endpoint", "settings"];
48
+ export declare const RESOURCE_TYPES: readonly ["capability", "benchmark", "assessment", "engine", "ui", "session", "waiting_room", "presentation", "setup", "scenario_editor", "scenario", "guide", "tick_controller", "hook", "validator", "endpoint", "settings"];
49
49
  export type ResourceType = (typeof RESOURCE_TYPES)[number];
50
50
  /**
51
51
  * Where a resource's code sits inside its own directory, and what the
@@ -149,6 +149,14 @@ export declare const ERROR_CODES: {
149
149
  readonly category: "package";
150
150
  readonly description: "The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing.";
151
151
  };
152
+ readonly BENCHMARK_UNWRITTEN: {
153
+ readonly category: "package";
154
+ readonly description: "A benchmark is not in the engine's `benchmarks`, so nothing writes it and it never holds a value. A warning.";
155
+ };
156
+ readonly ASSESSMENT_UNWRITTEN: {
157
+ readonly category: "package";
158
+ readonly description: "An assessment is not in the engine's `assessments`, so nothing scores it and it never holds a result. A warning.";
159
+ };
152
160
  readonly REFERENCE_UNKNOWN: {
153
161
  readonly category: "package";
154
162
  readonly description: "A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare.";
@@ -372,7 +380,7 @@ export type ErrorCode = keyof typeof ERROR_CODES;
372
380
  * failure's `error.code` says what kind of failure it was; its diagnostics say
373
381
  * what was found and where. LOGIC_ERROR is only ever a diagnostic.
374
382
  */
375
- export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "FEATURE_UNDECLARED", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "SCENARIO_EDITOR_UNREACHABLE", "SCENARIO_REFUSED", "SCENARIO_WARNING", "SETTINGS_UNGATED", "SETUP_NOTES_UNCONFIGURED", "EDITOR_SETTINGS_CONFIGURED", "EDITOR_ENDPOINT_NOT_SCENARIO", "SCENARIO_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
383
+ export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "FEATURE_UNDECLARED", "BENCHMARK_UNWRITTEN", "ASSESSMENT_UNWRITTEN", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "SCENARIO_EDITOR_UNREACHABLE", "SCENARIO_REFUSED", "SCENARIO_WARNING", "SETTINGS_UNGATED", "SETUP_NOTES_UNCONFIGURED", "EDITOR_SETTINGS_CONFIGURED", "EDITOR_ENDPOINT_NOT_SCENARIO", "SCENARIO_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
376
384
  export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
377
385
  export declare function categoryOf(code: ErrorCode): ErrorCategory;
378
386
  export declare function exitCodeOf(code: ErrorCode): number;
@@ -37,3 +37,8 @@ export declare function resourceNames(packagePath: string, meta: ResourceMeta):
37
37
  export declare function bundlePaths(packagePath: string, meta: ResourceMeta): string[];
38
38
  /** The absolute path to one resource's bundle, or undefined when it is absent. */
39
39
  export declare function findBundleFile(packagePath: string, type: ResourceType, identifier?: string): string | undefined;
40
+ /**
41
+ * What to tell someone who named a resource that is not there: the ones of
42
+ * that type the package does hold, or how to make the first.
43
+ */
44
+ export declare function existingResourcesHint(packagePath: string, type: ResourceType): string;