rpg-engine 0.4.1 → 0.6.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 (231) hide show
  1. package/README.md +1 -1
  2. package/dist/campaign/settings.d.ts +1 -0
  3. package/dist/campaign/settings.js +6 -5
  4. package/dist/command-line.js +12 -5
  5. package/dist/commands/advance.js +1 -1
  6. package/dist/commands/ask.d.ts +37 -2
  7. package/dist/commands/ask.js +106 -35
  8. package/dist/commands/change.js +28 -17
  9. package/dist/commands/config.d.ts +1 -1
  10. package/dist/commands/config.js +69 -21
  11. package/dist/commands/effect.js +42 -23
  12. package/dist/commands/find.js +1 -1
  13. package/dist/commands/game-adventures.js +2 -2
  14. package/dist/commands/game-catalog.d.ts +13 -0
  15. package/dist/commands/game-catalog.js +26 -2
  16. package/dist/commands/game-checks.js +23 -21
  17. package/dist/commands/{game-hit-dice.d.ts → game-dice-pool.d.ts} +3 -3
  18. package/dist/commands/{game-hit-dice.js → game-dice-pool.js} +7 -7
  19. package/dist/commands/game-effects.d.ts +12 -4
  20. package/dist/commands/game-effects.js +21 -13
  21. package/dist/commands/game-examples.d.ts +22 -0
  22. package/dist/commands/game-examples.js +72 -0
  23. package/dist/commands/game-extension-list.d.ts +31 -3
  24. package/dist/commands/game-extension-list.js +94 -6
  25. package/dist/commands/game-images.d.ts +1 -1
  26. package/dist/commands/game-images.js +3 -2
  27. package/dist/commands/game-library.d.ts +3 -0
  28. package/dist/commands/game-library.js +2 -2
  29. package/dist/commands/game-mode.js +1 -1
  30. package/dist/commands/game-package-code.d.ts +87 -0
  31. package/dist/commands/game-package-code.js +648 -0
  32. package/dist/commands/game-package-hooks.d.ts +37 -0
  33. package/dist/commands/game-package-hooks.js +116 -0
  34. package/dist/commands/game-recipes.js +2 -2
  35. package/dist/commands/game-reminders.d.ts +5 -2
  36. package/dist/commands/game-reminders.js +7 -4
  37. package/dist/commands/game-rules.d.ts +4 -1
  38. package/dist/commands/game-rules.js +7 -1
  39. package/dist/commands/game-upkeep.js +3 -3
  40. package/dist/commands/game-view-place.d.ts +8 -20
  41. package/dist/commands/game-view-place.js +16 -35
  42. package/dist/commands/game-widgets.d.ts +42 -8
  43. package/dist/commands/game-widgets.js +182 -31
  44. package/dist/commands/game-world.d.ts +32 -3
  45. package/dist/commands/game-world.js +113 -24
  46. package/dist/commands/image.js +1 -1
  47. package/dist/commands/init.js +2 -2
  48. package/dist/commands/mode.d.ts +1 -1
  49. package/dist/commands/package.d.ts +15 -1
  50. package/dist/commands/package.js +96 -24
  51. package/dist/commands/progression.d.ts +2 -0
  52. package/dist/commands/progression.js +7 -2
  53. package/dist/commands/roll.d.ts +2 -0
  54. package/dist/commands/roll.js +50 -24
  55. package/dist/commands/rules.js +6 -4
  56. package/dist/commands/scene.d.ts +2 -2
  57. package/dist/commands/scene.js +13 -10
  58. package/dist/commands/sheet.js +10 -1
  59. package/dist/commands/status.d.ts +1 -0
  60. package/dist/commands/status.js +14 -4
  61. package/dist/commands/trade.js +6 -4
  62. package/dist/commands/translate.js +2 -2
  63. package/dist/commands/travel.js +1 -1
  64. package/dist/commands/validate.js +2 -2
  65. package/dist/commands/view.d.ts +12 -4
  66. package/dist/commands/view.js +11 -8
  67. package/dist/commands/worked-out.js +11 -5
  68. package/dist/commands/write.d.ts +8 -1
  69. package/dist/commands/write.js +84 -25
  70. package/dist/core/command-reference.js +3 -2
  71. package/dist/core/consents.d.ts +18 -0
  72. package/dist/core/consents.js +93 -0
  73. package/dist/core/context.d.ts +68 -27
  74. package/dist/core/context.js +3 -1
  75. package/dist/core/examples.d.ts +25 -0
  76. package/dist/core/examples.js +19 -0
  77. package/dist/core/files.d.ts +2 -0
  78. package/dist/core/files.js +10 -1
  79. package/dist/core/package-api.d.ts +388 -0
  80. package/dist/core/package-declarations.d.ts +102 -0
  81. package/dist/core/package-declarations.js +81 -0
  82. package/dist/core/registry.d.ts +4 -0
  83. package/dist/core/text.d.ts +5 -0
  84. package/dist/core/text.js +12 -0
  85. package/dist/dashboard/acts.js +31 -24
  86. package/dist/dashboard/address.js +4 -1
  87. package/dist/dashboard/api.js +65 -3
  88. package/dist/dashboard/app.js +222 -98
  89. package/dist/dashboard/ask-card.js +169 -0
  90. package/dist/dashboard/asked-dice.js +57 -0
  91. package/dist/dashboard/dice/tray.js +6 -4
  92. package/dist/dashboard/extension-widgets.js +136 -16
  93. package/dist/dashboard/faces.js +6 -4
  94. package/dist/dashboard/help.js +10 -3
  95. package/dist/dashboard/i18n/ar.json +34 -29
  96. package/dist/dashboard/i18n/cs.json +34 -29
  97. package/dist/dashboard/i18n/da.json +34 -29
  98. package/dist/dashboard/i18n/de.json +34 -29
  99. package/dist/dashboard/i18n/el.json +34 -29
  100. package/dist/dashboard/i18n/es.json +34 -29
  101. package/dist/dashboard/i18n/fi.json +34 -29
  102. package/dist/dashboard/i18n/fr.json +34 -29
  103. package/dist/dashboard/i18n/he.json +34 -29
  104. package/dist/dashboard/i18n/hi.json +34 -29
  105. package/dist/dashboard/i18n/hu.json +34 -29
  106. package/dist/dashboard/i18n/is.json +34 -29
  107. package/dist/dashboard/i18n/it.json +34 -29
  108. package/dist/dashboard/i18n/ja.json +34 -29
  109. package/dist/dashboard/i18n/ko.json +34 -29
  110. package/dist/dashboard/i18n/nb.json +34 -29
  111. package/dist/dashboard/i18n/nl.json +34 -29
  112. package/dist/dashboard/i18n/pl.json +34 -29
  113. package/dist/dashboard/i18n/pt.json +34 -29
  114. package/dist/dashboard/i18n/ro.json +34 -29
  115. package/dist/dashboard/i18n/ru.json +34 -29
  116. package/dist/dashboard/i18n/sv.json +34 -29
  117. package/dist/dashboard/i18n/tr.json +34 -29
  118. package/dist/dashboard/i18n/uk.json +34 -29
  119. package/dist/dashboard/i18n/zh.json +34 -29
  120. package/dist/dashboard/icons.js +4 -1
  121. package/dist/dashboard/kit.js +35 -0
  122. package/dist/dashboard/labels.js +1 -0
  123. package/dist/dashboard/pack-card.js +97 -0
  124. package/dist/dashboard/package-page.js +50 -0
  125. package/dist/dashboard/packages.js +180 -24
  126. package/dist/dashboard/page-code.js +248 -0
  127. package/dist/dashboard/party.js +13 -14
  128. package/dist/dashboard/people.js +4 -0
  129. package/dist/dashboard/person-panel.js +110 -0
  130. package/dist/dashboard/place-map-view.js +11 -6
  131. package/dist/dashboard/rolls.js +2 -2
  132. package/dist/dashboard/scene.js +12 -9
  133. package/dist/dashboard/settings.js +55 -9
  134. package/dist/dashboard/sheet.js +21 -13
  135. package/dist/dashboard/status.js +69 -15
  136. package/dist/dashboard/style.css +859 -574
  137. package/dist/dashboard/top.js +75 -25
  138. package/dist/dashboard/turns.js +34 -13
  139. package/dist/dashboard/widgets.js +9 -2
  140. package/dist/dashboard-server.js +246 -11
  141. package/dist/dice/roll-dice.js +1 -1
  142. package/dist/effects/effect.d.ts +7 -4
  143. package/dist/effects/effect.js +12 -9
  144. package/dist/extensions/engine.d.ts +4 -0
  145. package/dist/extensions/engine.js +74 -0
  146. package/dist/extensions/extension.d.ts +28 -33
  147. package/dist/extensions/extension.js +37 -46
  148. package/dist/extensions/index.d.ts +4 -3
  149. package/dist/extensions/index.js +5 -2
  150. package/dist/extensions/packages.d.ts +14 -0
  151. package/dist/extensions/packages.js +148 -12
  152. package/dist/extensions/words.d.ts +2 -1
  153. package/dist/extensions/words.js +5 -4
  154. package/dist/index.d.ts +1 -3
  155. package/dist/mcp-server.js +52 -15
  156. package/dist/page-words.d.ts +4 -0
  157. package/dist/page-words.js +4 -4
  158. package/dist/page.d.ts +218 -0
  159. package/dist/page.js +2 -0
  160. package/dist/pages/index.d.ts +1 -1
  161. package/dist/pages/index.js +1 -1
  162. package/dist/pages/load.d.ts +7 -1
  163. package/dist/pages/load.js +10 -5
  164. package/dist/pages/page-file.js +1 -1
  165. package/dist/pages/stack-writes.js +5 -4
  166. package/dist/pages/standard-fields.d.ts +2 -0
  167. package/dist/pages/standard-fields.js +8 -1
  168. package/dist/pages/world.d.ts +8 -0
  169. package/dist/pages/world.js +9 -2
  170. package/dist/systems/game-system.d.ts +61 -30
  171. package/dist/systems/game-system.js +159 -50
  172. package/dist/systems/index.d.ts +3 -3
  173. package/dist/systems/index.js +3 -3
  174. package/dist/systems/system-code.d.ts +29 -88
  175. package/dist/systems/system-code.js +68 -23
  176. package/dist/systems/words.d.ts +2 -0
  177. package/dist/systems/words.js +11 -0
  178. package/dist/testing.d.ts +76 -0
  179. package/dist/testing.js +197 -0
  180. package/instructions/combat.md +2 -2
  181. package/instructions/core.md +2 -2
  182. package/instructions/dashboard.md +1 -1
  183. package/instructions/mentor-tutorial.md +1 -1
  184. package/instructions/play.md +2 -2
  185. package/instructions/setup.md +1 -1
  186. package/package.json +15 -2
  187. package/systems/5e/LICENSE.md +13 -3
  188. package/systems/5e/dist/dying.js +83 -16
  189. package/systems/5e/dist/index.js +2 -2
  190. package/systems/5e/dist/page-style.js +634 -0
  191. package/systems/5e/dist/page.js +166 -0
  192. package/systems/5e/dist/shown.js +23 -0
  193. package/systems/5e/instructions/combat.md +1 -0
  194. package/systems/5e/package.json +4 -2
  195. package/systems/5e/system.yaml +35 -7
  196. package/systems/5e/versions/srd-5.1/system.yaml +2 -0
  197. package/systems/5e/words/ar.yaml +30 -0
  198. package/systems/5e/words/cs.yaml +30 -0
  199. package/systems/5e/words/da.yaml +30 -0
  200. package/systems/5e/words/de.yaml +30 -0
  201. package/systems/5e/words/el.yaml +30 -0
  202. package/systems/5e/words/es.yaml +30 -0
  203. package/systems/5e/words/fi.yaml +30 -0
  204. package/systems/5e/words/fr.yaml +30 -0
  205. package/systems/5e/words/he.yaml +30 -0
  206. package/systems/5e/words/hi.yaml +30 -0
  207. package/systems/5e/words/hu.yaml +30 -0
  208. package/systems/5e/words/is.yaml +30 -0
  209. package/systems/5e/words/it.yaml +30 -0
  210. package/systems/5e/words/ja.yaml +30 -0
  211. package/systems/5e/words/ko.yaml +30 -0
  212. package/systems/5e/words/nb.yaml +30 -0
  213. package/systems/5e/words/nl.yaml +30 -0
  214. package/systems/5e/words/pl.yaml +30 -0
  215. package/systems/5e/words/pt.yaml +30 -0
  216. package/systems/5e/words/ro.yaml +30 -0
  217. package/systems/5e/words/ru.yaml +30 -0
  218. package/systems/5e/words/sv.yaml +30 -0
  219. package/systems/5e/words/tr.yaml +30 -0
  220. package/systems/5e/words/uk.yaml +30 -0
  221. package/systems/5e/words/zh.yaml +30 -0
  222. package/dist/commands/game-extensions.d.ts +0 -34
  223. package/dist/commands/game-extensions.js +0 -182
  224. package/dist/commands/game-system-code.d.ts +0 -25
  225. package/dist/commands/game-system-code.js +0 -172
  226. package/dist/dashboard/death-save.js +0 -67
  227. package/dist/dashboard/dying.js +0 -46
  228. package/dist/dashboard/save-outcome.js +0 -42
  229. package/dist/dashboard/spend.js +0 -115
  230. package/dist/extensions/api.d.ts +0 -155
  231. /package/dist/{extensions/api.js → core/package-api.js} +0 -0
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { withExamples } from "./examples.js";
2
3
  import { firstSentence } from "./text.js";
3
4
  const generatedNotice = "<!-- Generated from the definitions of the commands: do not edit it by hand. After changing a command, run npm run docs. -->";
4
5
  /**
@@ -15,10 +16,10 @@ function commandSection(command) {
15
16
  const required = schema.required ?? [];
16
17
  const parameters = Object.entries(schema.properties ?? {}).map(([name, field]) => parameterLine(name, field, required.includes(name)));
17
18
  const positionals = command.positionals?.length ? ` Positional parameters: ${command.positionals.map(code).join(", ")}.` : "";
18
- return [`### ${command.name}`, firstSentence(command.description), `Read-only: ${command.readOnly ? "yes" : "no"}.${positionals}`, parameters.length > 0 ? parameters.join("\n") : "No parameters."].join("\n\n");
19
+ return [`### ${command.name}`, firstSentence(withExamples(command.description)), `Read-only: ${command.readOnly ? "yes" : "no"}.${positionals}`, parameters.length > 0 ? parameters.join("\n") : "No parameters."].join("\n\n");
19
20
  }
20
21
  function parameterLine(name, field, required) {
21
- const description = typeof field === "object" && field.description ? `: ${field.description}` : "";
22
+ const description = typeof field === "object" && field.description ? `: ${withExamples(field.description)}` : "";
22
23
  return `- ${code(name)} (${code(typeText(field))}, ${required ? "required" : "optional"})${description}`;
23
24
  }
24
25
  /** The type of a parameter from its JSON Schema, such as string | string[]. */
@@ -0,0 +1,18 @@
1
+ /** The npm scope of the packages RPG Engine publishes, verified: their code runs without a yes (D-441). */
2
+ export declare const ourScope = "@rpgengine/";
3
+ /**
4
+ * Whether the code of the package in this folder may run (D-478, D-511): one the engine ships, outside npm's folders; one of ours from npm; one installed from
5
+ * a folder or a file of the player's; or another's the player said yes to, at this version and with these files.
6
+ */
7
+ export declare function packageCodeMayRun(folder: string): boolean;
8
+ /**
9
+ * The fingerprint of a package's files as installed: every file but those npm or git keep beside them, by its path and its bytes. Worked out again only when
10
+ * a file's size or time changed: it is asked at each load of the package's code.
11
+ */
12
+ export declare function packageFingerprint(folder: string): string;
13
+ /** Records the player's yes to a package installed in a folder of npm's packages: its version and its files as they are now. */
14
+ export declare function recordConsent(folder: string, name: string, version: string): void;
15
+ /** Takes the player's yes to a package away, as when it leaves this computer. */
16
+ export declare function dropConsent(folder: string, name: string): void;
17
+ /** Whether the player said yes to this package's code as it is installed now: its name, its version and its files. */
18
+ export declare function hasConsent(folder: string, name: string, version: string): boolean;
@@ -0,0 +1,93 @@
1
+ // The player's yes to the code of a package not ours, an extension's or a game system's (D-478, D-510, D-511): kept on this computer beside the packages npm
2
+ // installed, never in a campaign, for the package, its version and the fingerprint of its files; any other version, or a file changed since, has no yes.
3
+ import { createHash } from "node:crypto";
4
+ import { readdirSync, readFileSync, statSync } from "node:fs";
5
+ import { dirname, join, relative, sep } from "node:path";
6
+ import { installedFromFolder } from "./files.js";
7
+ import { files } from "./store.js";
8
+ /** The file of the yeses, beside the folder of the packages npm installed. */
9
+ const consentsFile = "consents.json";
10
+ /** The npm scope of the packages RPG Engine publishes, verified: their code runs without a yes (D-441). */
11
+ export const ourScope = "@rpgengine/";
12
+ /**
13
+ * Whether the code of the package in this folder may run (D-478, D-511): one the engine ships, outside npm's folders; one of ours from npm; one installed from
14
+ * a folder or a file of the player's; or another's the player said yes to, at this version and with these files.
15
+ */
16
+ export function packageCodeMayRun(folder) {
17
+ let manifest;
18
+ try {
19
+ manifest = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"));
20
+ }
21
+ catch {
22
+ return false;
23
+ }
24
+ const name = typeof manifest.name === "string" ? manifest.name : "";
25
+ const linked = installedFromFolder(folder);
26
+ return consentsPath(folder) === undefined || linked || name.startsWith(ourScope) || hasConsent(folder, name, typeof manifest.version === "string" ? manifest.version : "");
27
+ }
28
+ /**
29
+ * The fingerprint of a package's files as installed: every file but those npm or git keep beside them, by its path and its bytes. Worked out again only when
30
+ * a file's size or time changed: it is asked at each load of the package's code.
31
+ */
32
+ export function packageFingerprint(folder) {
33
+ const paths = packageFiles(folder);
34
+ const signature = paths.map((path) => {
35
+ const stat = statSync(path);
36
+ return `${path}|${stat.size}|${stat.mtimeMs}`;
37
+ }).join("\n");
38
+ const known = fingerprints.get(folder);
39
+ if (known?.signature === signature) {
40
+ return known.fingerprint;
41
+ }
42
+ const hash = createHash("sha256");
43
+ for (const path of paths) {
44
+ hash.update(`${relative(folder, path).split(sep).join("/")}\0`).update(readFileSync(path)).update("\0");
45
+ }
46
+ const fingerprint = hash.digest("hex");
47
+ fingerprints.set(folder, { signature, fingerprint });
48
+ return fingerprint;
49
+ }
50
+ const fingerprints = new Map();
51
+ /** Records the player's yes to a package installed in a folder of npm's packages: its version and its files as they are now. */
52
+ export function recordConsent(folder, name, version) {
53
+ const file = consentsPath(folder);
54
+ if (file !== undefined) {
55
+ files().write(file, `${JSON.stringify({ ...readConsents(file), [name]: { version, fingerprint: packageFingerprint(folder) } }, null, 2)}\n`);
56
+ }
57
+ }
58
+ /** Takes the player's yes to a package away, as when it leaves this computer. */
59
+ export function dropConsent(folder, name) {
60
+ const file = consentsPath(folder);
61
+ const kept = file === undefined ? {} : readConsents(file);
62
+ if (file !== undefined && Object.hasOwn(kept, name)) {
63
+ files().write(file, `${JSON.stringify(Object.fromEntries(Object.entries(kept).filter(([one]) => one !== name)), null, 2)}\n`);
64
+ }
65
+ }
66
+ /** Whether the player said yes to this package's code as it is installed now: its name, its version and its files. */
67
+ export function hasConsent(folder, name, version) {
68
+ const file = consentsPath(folder);
69
+ const given = file === undefined ? undefined : readConsents(file)[name];
70
+ return given !== undefined && given.version === version && given.fingerprint === packageFingerprint(folder);
71
+ }
72
+ /** The file of the yeses for a package in a folder of npm's packages, as node_modules/@scope/name; undefined for one elsewhere. */
73
+ function consentsPath(folder) {
74
+ const parts = folder.split(/[\\/]/);
75
+ const at = parts.lastIndexOf("node_modules");
76
+ return at < 0 ? undefined : join(dirname(parts.slice(0, at + 1).join(sep)), consentsFile);
77
+ }
78
+ function readConsents(file) {
79
+ try {
80
+ const read = JSON.parse(files().text(file) ?? "{}");
81
+ return typeof read === "object" && read !== null && !Array.isArray(read) ? read : {};
82
+ }
83
+ catch {
84
+ return {};
85
+ }
86
+ }
87
+ /** A package's own files, in a fixed order: not those npm or git keep beside them. */
88
+ function packageFiles(folder) {
89
+ return readdirSync(folder, { withFileTypes: true })
90
+ .filter((entry) => !["node_modules", ".git"].includes(entry.name))
91
+ .sort((first, second) => (first.name < second.name ? -1 : first.name > second.name ? 1 : 0))
92
+ .flatMap((entry) => (entry.isDirectory() ? packageFiles(join(folder, entry.name)) : entry.isFile() ? [join(folder, entry.name)] : []));
93
+ }
@@ -23,24 +23,32 @@ export interface Context {
23
23
  /** The folders that hold the installed game systems, nearest first (SYS-1). */
24
24
  systemFolders: string[];
25
25
  /**
26
- * The code of the systems that bring some, by name, loaded as the command line, the MCP server or the dashboard starts (D-448): its hooks, which the
27
- * systems module types, or what kept it from loading.
26
+ * The code of the systems that bring some, by name, loaded as the command line, the MCP server or the dashboard starts (D-448): what it gives, a package's
27
+ * code (D-514), or what kept it from loading, as another's code without the player's yes (D-511) or one made for another API.
28
28
  */
29
- systemCode?: Record<string, {
30
- hooks: object;
29
+ systemCode?: Record<string, ({
30
+ code: object;
31
31
  } | {
32
32
  problem: string;
33
+ } | {
34
+ refused: string;
35
+ }) & {
36
+ version?: string;
33
37
  }>;
34
38
  /** The folders that hold the installed extensions, each a package folder or npm's node_modules (D-436); none where missing. */
35
39
  extensionFolders?: string[];
36
40
  /** The AI app the MCP server serves, by the name it gives itself, such as claude-code; missing on the command line. */
37
41
  host?: () => string | undefined;
42
+ /** The packages the player said no to in a window in this session, by the name npm describes: never asked again until the server starts again (D-510). */
43
+ declined?: Set<string>;
38
44
  /** The chat the MCP server serves, as the dashboard needs it for the player's sentences (D-495); missing on the command line. */
39
45
  chat?: ChatState;
40
46
  /** The command was typed by the player in their own terminal: their own hands, as the yes to a package not ours needs (D-441). */
41
47
  terminal?: boolean;
42
48
  /** npm on this computer, which installs the packages in the engine's own folder (D-436); missing where nothing installs, as in most tests. */
43
49
  packages?: PackageManager;
50
+ /** rpg-engine itself on npm, which the player updates from the dashboard, never the master (D-515 (3)); missing outside the game's server, and in tests. */
51
+ engine?: EngineUpdater;
44
52
  /** A window of the player's operating system, for a yes the master cannot give (D-478); only where a player sits, never in the tests. */
45
53
  confirm?: Confirm;
46
54
  /** Downloads a file over https, at most `most` bytes (ADV-1); missing where nothing reaches the web, as in the tests. */
@@ -100,6 +108,11 @@ export interface PackageInfo {
100
108
  code?: boolean;
101
109
  /** Whether it needs other packages, which npm installs beside it. */
102
110
  dependencies?: boolean;
111
+ /** Its latest version, when that one needs a newer rpg-engine than this one and this is the newest this one reads (D-515 (2)): with the first engine that reads it. */
112
+ newer?: {
113
+ version: string;
114
+ engine?: string;
115
+ };
103
116
  }
104
117
  /** What the window of the player's operating system said: yes, no, or none when it could not be shown. */
105
118
  export type Confirmed = "yes" | "no" | "none";
@@ -126,6 +139,30 @@ export interface PackageManager {
126
139
  failed: string;
127
140
  }>;
128
141
  }
142
+ /** How this rpg-engine is installed (D-515 (3)): globally by npm, which updates it; as npm link of a folder in development; or any other way, from that folder. */
143
+ export type EngineInstall = {
144
+ how: "global";
145
+ } | {
146
+ how: "link";
147
+ folder: string;
148
+ } | {
149
+ how: "other";
150
+ folder: string;
151
+ };
152
+ /** rpg-engine itself on npm (D-515 (3)): its latest version, how this one is installed, and its update to a version, as it was installed. */
153
+ export interface EngineUpdater {
154
+ /** The latest version npm has; why not when npm cannot be asked. */
155
+ latest(): Promise<{
156
+ version: string;
157
+ } | {
158
+ failed: string;
159
+ }>;
160
+ installed(): Promise<EngineInstall>;
161
+ /** The version in its folder now, which a chat started after an update runs, the running one being read as the server starts. */
162
+ onDisk(): string;
163
+ /** Installs that version globally with npm: undefined once it is installed, else why not. */
164
+ update(version: string): Promise<string | undefined>;
165
+ }
129
166
  /** A program of this computer that writes and draws outside the chat, with the player's own login (D-424). */
130
167
  export type HelperName = "codex" | "claude";
131
168
  /** How a helper program stands: not on this computer, there without the player's login, signed in with an API key, which the engine never uses, or ready. */
@@ -220,31 +257,29 @@ export interface PictureMaker {
220
257
  export interface Said {
221
258
  said: string;
222
259
  }
223
- /** Whose sheet a roll's checks read, and by button the field each one rolls, for the page to light that row of the sheet (ASK-12); a death save, what it is. */
260
+ /** Whose sheet a roll's checks read, and by button the field each one rolls, for the page to light that row of the sheet (ASK-12). */
224
261
  export interface Rows {
225
262
  who: string;
226
263
  fields: (string | null)[];
227
- save?: SaveAsked;
264
+ /** By button, its name and the note under it when a package words it, as Reroll and 3 left (D-507). */
265
+ buttons?: ({
266
+ name: string;
267
+ note?: string;
268
+ } | null)[];
269
+ /** The rule under the buttons, in a line. */
270
+ rule?: string;
271
+ card?: CardAsked;
272
+ /** The roll is forced (D-507): no button turns it down, and no words of the player's take its place. */
273
+ forced?: true;
228
274
  }
229
- /** A death save the question asks (DIE-4, D-460): its die, the total that succeeds, its counters as they stand, and what the lowest and highest faces do. */
230
- export interface SaveAsked {
231
- sides: number;
232
- atLeast: number;
233
- successes: {
234
- field: string;
235
- value: number;
236
- most: number;
237
- };
238
- failures: {
239
- field: string;
240
- value: number;
241
- most: number;
242
- };
243
- lowest?: number;
244
- highest?: {
245
- field: string;
246
- value: number;
247
- };
275
+ /**
276
+ * The card of a package's widget a question is asked in (D-507): the widget, by its package's name and its own, as lockpicking.lock, and which attempt it is;
277
+ * what it shows, read when it is asked for, never in the way of the question.
278
+ */
279
+ export interface CardAsked {
280
+ widget: string;
281
+ key: string;
282
+ shows(): Promise<unknown>;
248
283
  }
249
284
  /** A square of a place's map the player touched, by its name, such as E4 (ASK-11). */
250
285
  export interface Picked {
@@ -276,6 +311,8 @@ export interface SpendAsked {
276
311
  adds: number;
277
312
  total: number;
278
313
  }[];
314
+ /** A package's rule under the dice (D-514). */
315
+ rule?: string;
279
316
  }
280
317
  /**
281
318
  * The dice of a rest as a page asks them (ASK-14): what it shows now, a die of a counter spent, or why not, and what the master hears of the dice spent when
@@ -290,11 +327,15 @@ export interface Player {
290
327
  choose(question: string, title: string, labels: string[], signal?: AbortSignal, rows?: Rows): Promise<number | Said | undefined | "unavailable" | "absent">;
291
328
  /** Asks where a player character, who, moves on the map of its place (ASK-11): the square, the change of mind as its one button (0), or the player's words; only a page can. */
292
329
  chooseSquare?(question: string, title: string, change: string, who: string, signal?: AbortSignal): Promise<Picked | 0 | Said | undefined | "absent">;
293
- /** Asks the player to spend the dice of a rest one at a time (ASK-14), until the button that ends it (0); only a page can. */
294
- spendDice?(question: string, title: string, done: string, spending: Spending, signal?: AbortSignal): Promise<0 | undefined | "absent">;
330
+ /** Asks the player to spend the dice of a rest one at a time (ASK-14), until the button that ends it (0), maybe in a package's card (D-514); only a page can. */
331
+ spendDice?(question: string, title: string, done: string, spending: Spending, signal?: AbortSignal, card?: CardAsked): Promise<0 | undefined | "absent">;
295
332
  /** Whether a question waits for the player there now, as on the dashboard's page; a form does not say. */
296
333
  asking?(): boolean;
334
+ /** As the call whose questions were asked in a card ends: the card as it is after the last dice (D-507). */
335
+ cardEnded?(card: CardAsked): void;
297
336
  }
298
337
  export declare function defaultContext(folder?: string): Context;
338
+ /** The folder of the game systems the engine ships, from src/core/ and from dist/core/ alike two levels up: those it brings without npm (D-171). */
339
+ export declare const engineSystemsFolder: string;
299
340
  /** Where the engine installs the packages, with npm, on this computer (D-436): the player's local data, beside the programs it installs (D-425). */
300
341
  export declare function packagesFolder(): string;
@@ -12,7 +12,7 @@ export function defaultContext(folder = process.cwd()) {
12
12
  actor: "master",
13
13
  platform: process.platform,
14
14
  // From src/core/ and from dist/core/ alike, the package's systems/ folder is two levels up; then those npm installed (D-485).
15
- systemFolders: [fileURLToPath(new URL("../../systems/", import.meta.url)), join(packagesFolder(), "node_modules")],
15
+ systemFolders: [engineSystemsFolder, join(packagesFolder(), "node_modules")],
16
16
  extensionFolders: [join(packagesFolder(), "node_modules")],
17
17
  home: userDataFolder(),
18
18
  bookIndex: join(dirname(packagesFolder()), "library"),
@@ -20,6 +20,8 @@ export function defaultContext(folder = process.cwd()) {
20
20
  pageFolder: fileURLToPath(new URL("../../dist/dashboard/", import.meta.url)),
21
21
  };
22
22
  }
23
+ /** The folder of the game systems the engine ships, from src/core/ and from dist/core/ alike two levels up: those it brings without npm (D-171). */
24
+ export const engineSystemsFolder = fileURLToPath(new URL("../../systems/", import.meta.url));
23
25
  /** Where the engine installs the packages, with npm, on this computer (D-436): the player's local data, beside the programs it installs (D-425). */
24
26
  export function packagesFolder() {
25
27
  const home = homedir();
@@ -0,0 +1,25 @@
1
+ /** What the descriptions' examples name, by placeholder. */
2
+ export interface Examples {
3
+ /** The counter damage takes from, as hp. */
4
+ counter: string;
5
+ /** A roll of a number of the sheet, as 1d20+str-save. */
6
+ roll: string;
7
+ /** Two checks of ask, each with its name and its dice, as Atletica 1d20+athletics. */
8
+ check: string;
9
+ otherCheck: string;
10
+ /** A coin and a smaller one, as gp and sp. */
11
+ coin: string;
12
+ smallCoin: string;
13
+ /** Three uses of a turn, as action, bonus action, reaction. */
14
+ uses: string;
15
+ /** A rest, as long rest. */
16
+ rest: string;
17
+ /** A counter of a pool of dice spent in a rest, as hit-dice-d6. */
18
+ pool: string;
19
+ /** A field an effect adds to, as bonus-ac. */
20
+ bonus: string;
21
+ }
22
+ /** The examples of a game without a system, or with one that does not name them. */
23
+ export declare const neutralExamples: Examples;
24
+ /** A description with its {{placeholders}} filled from the examples; one the examples lack stays as written. */
25
+ export declare function withExamples(text: string, examples?: Examples): string;
@@ -0,0 +1,19 @@
1
+ // The examples in the commands' descriptions (D-518): a description writes {{counter}} where an example names a game's thing, filled with the names of the
2
+ // campaign's system where the MCP server runs in one, else with neutral names, as the command line and the reference have them.
3
+ /** The examples of a game without a system, or with one that does not name them. */
4
+ export const neutralExamples = {
5
+ counter: "health",
6
+ roll: "2d6+wits",
7
+ check: "Forza 2d6+strength",
8
+ otherCheck: "Agilità 2d6+agility",
9
+ coin: "gold",
10
+ smallCoin: "silver",
11
+ uses: "action, move, reaction",
12
+ rest: "night's rest",
13
+ pool: "stamina-d6",
14
+ bonus: "bonus-armor",
15
+ };
16
+ /** A description with its {{placeholders}} filled from the examples; one the examples lack stays as written. */
17
+ export function withExamples(text, examples = neutralExamples) {
18
+ return text.replace(/\{\{(\w+)\}\}/g, (whole, name) => (Object.hasOwn(examples, name) ? examples[name] : whole));
19
+ }
@@ -7,6 +7,8 @@ export declare function filesIn(folder: string, keep: (name: string) => boolean)
7
7
  * installed from a folder (D-441); never followed further.
8
8
  */
9
9
  export declare function packageFoldersIn(folders: string[]): string[];
10
+ /** A path by the folders it really is in, through any link on the way, as Node resolves a module; as given when it is not there. */
11
+ export declare function realPath(path: string): string;
10
12
  /**
11
13
  * Whether a package of npm's folder came from a folder or a file of this computer, never from npm (D-441, D-452): npm's package.json names it as file:, or it
12
14
  * is a link to the folder. Such a package is never verified, whatever its name.
@@ -1,5 +1,5 @@
1
1
  // The files of a folder and of the folders inside it, listed one folder at a time: listing a whole tree at once looks at every file again on Windows (D-194).
2
- import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
2
+ import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
3
3
  import { basename, join, relative, resolve, sep } from "node:path";
4
4
  /** The full paths of `folder` and of the folders inside it, however deep; none when there is no such folder. */
5
5
  export function foldersIn(folder) {
@@ -57,6 +57,15 @@ function chosenPackages(folder) {
57
57
  return undefined;
58
58
  }
59
59
  }
60
+ /** A path by the folders it really is in, through any link on the way, as Node resolves a module; as given when it is not there. */
61
+ export function realPath(path) {
62
+ try {
63
+ return realpathSync(path);
64
+ }
65
+ catch {
66
+ return path;
67
+ }
68
+ }
60
69
  /**
61
70
  * Whether a package of npm's folder came from a folder or a file of this computer, never from npm (D-441, D-452): npm's package.json names it as file:, or it
62
71
  * is a link to the folder. Such a package is never verified, whatever its name.