castle-web-cli 0.4.228 → 0.4.230

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 (236) hide show
  1. package/dist/agent-prompts.d.ts +11 -3
  2. package/dist/agent-prompts.js +153 -53
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +43 -33
  5. package/dist/api.d.ts +47 -2
  6. package/dist/api.js +85 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +779 -3
  9. package/dist/castleJson.d.ts +59 -0
  10. package/dist/castleJson.js +267 -3
  11. package/dist/check.js +27 -1
  12. package/dist/cloudGit.d.ts +20 -1
  13. package/dist/cloudGit.js +267 -10
  14. package/dist/contentPack.d.ts +49 -0
  15. package/dist/contentPack.js +273 -0
  16. package/dist/devExperiments.d.ts +21 -0
  17. package/dist/devExperiments.js +139 -0
  18. package/dist/devHub.d.ts +55 -0
  19. package/dist/devHub.js +187 -0
  20. package/dist/devSessionChild.js +3 -1
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +229 -44
  23. package/dist/experimentAssignment.d.ts +15 -0
  24. package/dist/experimentAssignment.js +41 -0
  25. package/dist/importCheckHook.d.ts +40 -0
  26. package/dist/importCheckHook.js +171 -0
  27. package/dist/importRegression.d.ts +15 -0
  28. package/dist/importRegression.js +100 -0
  29. package/dist/importTrust.d.ts +2 -0
  30. package/dist/importTrust.js +27 -0
  31. package/dist/importUpdateHook.d.ts +18 -0
  32. package/dist/importUpdateHook.js +31 -8
  33. package/dist/importUpdateHookRunner.js +19 -7
  34. package/dist/imports.d.ts +16 -0
  35. package/dist/imports.js +145 -33
  36. package/dist/index.js +8 -1
  37. package/dist/init.d.ts +3 -0
  38. package/dist/init.js +125 -8
  39. package/dist/install.js +4 -1
  40. package/dist/localPaths.js +4 -0
  41. package/dist/login.js +2 -2
  42. package/dist/platformDoc.js +3 -8
  43. package/dist/playPagePolicy.js +3 -1
  44. package/dist/remix.js +5 -0
  45. package/dist/routerTaskReport.d.ts +28 -0
  46. package/dist/routerTaskReport.js +56 -0
  47. package/dist/save-deck.d.ts +18 -0
  48. package/dist/save-deck.js +145 -6
  49. package/dist/serve.d.ts +8 -0
  50. package/dist/serve.js +94 -13
  51. package/dist/serverBundle.d.ts +1 -1
  52. package/dist/serverBundle.js +5 -1
  53. package/dist/sourceLineage.d.ts +42 -0
  54. package/dist/sourceLineage.js +380 -0
  55. package/dist/webSourceSync.d.ts +11 -0
  56. package/dist/webSourceSync.js +26 -9
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +301 -52
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +6 -1
  64. package/kits/base/sdk/castle.js +3 -0
  65. package/kits/base/sdk/commands.d.ts +208 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +86 -6
  73. package/kits/base/sdk/multiplayer.js +157 -4
  74. package/kits/base/sdk/server/hub.d.ts +169 -0
  75. package/kits/base/sdk/server/hub.js +125 -0
  76. package/kits/base/sdk/server/platformHandle.d.ts +49 -2
  77. package/kits/base/sdk/server/storage.d.ts +55 -2
  78. package/kits/base/sdk/server/wrapper.d.ts +85 -6
  79. package/kits/base/sdk/server/wrapper.js +393 -30
  80. package/kits/base/sdk/transport.d.ts +2 -1
  81. package/kits/base/sdk/transport.js +13 -1
  82. package/kits/hub-game/.prettierrc +5 -0
  83. package/kits/hub-game/CLAUDE.md +146 -0
  84. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  88. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  89. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  90. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  91. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  92. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  93. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  94. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  95. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  96. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  97. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  98. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  99. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  100. package/kits/hub-game/castle.json +96 -0
  101. package/kits/hub-game/code/client/attention.js +133 -0
  102. package/kits/hub-game/code/client/avatar.js +288 -0
  103. package/kits/hub-game/code/client/cabinets.js +90 -0
  104. package/kits/hub-game/code/client/chat.js +135 -0
  105. package/kits/hub-game/code/client/chrome.js +1001 -0
  106. package/kits/hub-game/code/client/doorFrame.js +15 -0
  107. package/kits/hub-game/code/client/firstJoin.js +14 -0
  108. package/kits/hub-game/code/client/grab.js +241 -0
  109. package/kits/hub-game/code/client/hookLayer.js +230 -0
  110. package/kits/hub-game/code/client/idle.js +326 -0
  111. package/kits/hub-game/code/client/keys.js +48 -0
  112. package/kits/hub-game/code/client/pack.js +232 -0
  113. package/kits/hub-game/code/client/packFormat.js +397 -0
  114. package/kits/hub-game/code/client/say.js +127 -0
  115. package/kits/hub-game/code/client/sha256.js +80 -0
  116. package/kits/hub-game/code/client/sound.js +147 -0
  117. package/kits/hub-game/code/client/state.js +131 -0
  118. package/kits/hub-game/code/client/talk.js +259 -0
  119. package/kits/hub-game/code/client/together.js +365 -0
  120. package/kits/hub-game/code/client/wear.js +149 -0
  121. package/kits/hub-game/code/server/actors.js +627 -0
  122. package/kits/hub-game/code/server/blocks.js +103 -0
  123. package/kits/hub-game/code/server/cabinets.js +309 -0
  124. package/kits/hub-game/code/server/game.js +137 -0
  125. package/kits/hub-game/code/server/grab.js +247 -0
  126. package/kits/hub-game/code/server/history.js +96 -0
  127. package/kits/hub-game/code/server/hub.js +1904 -0
  128. package/kits/hub-game/code/server/idle.js +412 -0
  129. package/kits/hub-game/code/server/index.js +64 -0
  130. package/kits/hub-game/code/server/labels.js +59 -0
  131. package/kits/hub-game/code/server/manifest.js +527 -0
  132. package/kits/hub-game/code/server/npcs.js +745 -0
  133. package/kits/hub-game/code/server/party.js +381 -0
  134. package/kits/hub-game/code/server/place.js +43 -0
  135. package/kits/hub-game/code/server/say.js +83 -0
  136. package/kits/hub-game/code/server/wear.js +142 -0
  137. package/kits/hub-game/code/systems/hub.js +2230 -0
  138. package/kits/hub-game/docs/content-pack.md +151 -0
  139. package/kits/hub-game/docs/contract.md +1139 -0
  140. package/kits/hub-game/docs/style.md +137 -0
  141. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  142. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  143. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  144. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  145. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  146. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  147. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  148. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  149. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  150. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  151. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  152. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  153. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  154. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  155. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  156. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  157. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  158. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  159. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  160. package/kits/hub-game/eslint.config.js +20 -0
  161. package/kits/hub-game/fonts.generated.js +9 -0
  162. package/kits/hub-game/index.html +22 -0
  163. package/kits/hub-game/main.jsx +6 -0
  164. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  165. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  167. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  168. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  169. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  170. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  171. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  172. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  174. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  175. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  176. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  177. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  178. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  179. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  180. package/kits/hub-game/package-lock.json +365 -0
  181. package/kits/hub-game/package.json +32 -0
  182. package/kits/hub-game/scenes/main.scene +318 -0
  183. package/kits/hub-game/scripts/check.mjs +339 -0
  184. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  185. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  186. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  187. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  188. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  189. package/kits/hub-game/scripts/pack.mjs +192 -0
  190. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  191. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  192. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  193. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  194. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  195. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  196. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  197. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  198. package/kits/hub-game/scripts/test-door.mjs +56 -0
  199. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  200. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  201. package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -0
  202. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  203. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  204. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  205. package/kits/hub-game/scripts/test-manifest.mjs +224 -0
  206. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  207. package/kits/hub-game/scripts/test-npcs.mjs +714 -0
  208. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  209. package/kits/hub-game/scripts/test-party.mjs +286 -0
  210. package/kits/hub-game/scripts/test-say.mjs +149 -0
  211. package/kits/hub-game/scripts/test-together.mjs +183 -0
  212. package/kits/hub-game/theme.style +3 -0
  213. package/kits/multiplayer-3d/castle.json +5 -5
  214. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  215. package/kits/multiplayer-3d/code/server/players.js +4 -1
  216. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  217. package/kits/multiplayer-3d/code/server/world.js +20 -7
  218. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  219. package/kits/physics-2d/castle.json +2 -2
  220. package/kits/physics-2d/engine/art.js +13 -0
  221. package/kits/physics-2d/engine/assets.js +4 -2
  222. package/kits/physics-2d/engine/scene.js +25 -5
  223. package/kits/physics-3d/CLAUDE.md +6 -1
  224. package/kits/physics-3d/castle.json +3 -3
  225. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
  226. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  227. package/kits/physics-3d/engine3d/materials.js +29 -1
  228. package/kits/physics-3d/engine3d/world3d.js +65 -1
  229. package/kits/physics-3d/systems/physics3d.js +5 -2
  230. package/kits/real-time/castle.json +2 -2
  231. package/kits/real-time/code/client/connection.js +77 -7
  232. package/kits/real-time/code/client/gameHooks.js +63 -3
  233. package/kits/real-time/code/client/messages.js +7 -0
  234. package/kits/real-time/code/server/gameHooks.js +24 -0
  235. package/kits/real-time/code/server/session.js +390 -22
  236. package/package.json +2 -2
@@ -27,14 +27,44 @@ export interface CastleJson {
27
27
  tickRate?: number;
28
28
  maxPlayers?: number;
29
29
  destinations?: ServerDestinationConfig[];
30
+ worldNotifications?: ServerWorldNotificationsConfig;
30
31
  };
31
32
  voice?: {
32
33
  enabled?: boolean;
33
34
  };
34
35
  importWhenRemixed?: boolean;
35
36
  starterScene?: string;
37
+ starterFiles?: string[];
38
+ starterConfig?: Record<string, unknown>;
39
+ onCheck?: string;
40
+ onPack?: string;
41
+ devDecks?: Record<string, string>;
42
+ experiments?: Record<string, ExperimentConfig>;
43
+ devExperiments?: Record<string, string>;
36
44
  [key: string]: unknown;
37
45
  }
46
+ export interface ExperimentConfig {
47
+ variants: string[];
48
+ weights?: number[];
49
+ winner?: string;
50
+ }
51
+ export declare const EXPERIMENTS_CAP = 8;
52
+ export declare const EXPERIMENT_VARIANTS_MIN = 2;
53
+ export declare const EXPERIMENT_VARIANTS_CAP = 8;
54
+ export declare const EXPERIMENT_NAME: RegExp;
55
+ export declare const PLATFORM_EXPERIMENT_NAME: RegExp;
56
+ /**
57
+ * castle.json `experiments`, checked: the block as Castle stores it, or null
58
+ * when the deck declares none. Throws on a block Castle would refuse, naming
59
+ * the experiment and the rule.
60
+ */
61
+ export declare function validateExperiments(value: unknown): Record<string, ExperimentConfig> | null;
62
+ /**
63
+ * castle.json `devExperiments`, for `castle-web serve`: every `name: variant`
64
+ * pair that is one, with the rest reported to `log` and left out.
65
+ */
66
+ export declare function isPlatformExperimentName(value: unknown): boolean;
67
+ export declare function readDevExperiments(value: unknown, log?: (text: string) => void): Record<string, string>;
38
68
  export declare const DEFAULT_STARTER_SCENE = "scenes/main.scene";
39
69
  export declare const DEFAULT_SERVER_TICK_RATE = 20;
40
70
  export declare const DEFAULT_SERVER_MAX_PLAYERS = 8;
@@ -47,14 +77,43 @@ export interface ServerDestinationConfig {
47
77
  selection: 'exact' | 'find';
48
78
  persistence: 'transient' | 'world';
49
79
  characters?: 'shared';
80
+ worldTime?: {
81
+ advance: 'wallClock';
82
+ };
50
83
  maxPlayers: number;
51
84
  }
85
+ export interface ServerWorldNotificationTemplateConfig {
86
+ id: string;
87
+ text: string;
88
+ slots: string[];
89
+ timeSensitive?: boolean;
90
+ }
91
+ export interface ServerWorldNotificationsConfig {
92
+ version: 1;
93
+ templates: ServerWorldNotificationTemplateConfig[];
94
+ }
52
95
  export interface ResolvedServerConfig {
53
96
  entry: string;
54
97
  tickRate: number;
55
98
  maxPlayers: number;
56
99
  voiceEnabled: boolean;
57
100
  destinations?: ServerDestinationConfig[];
101
+ worldNotifications?: ServerWorldNotificationsConfig;
102
+ hub?: ServerHubConfig;
103
+ }
104
+ /**
105
+ * What ghost keeps of castle.json `hub` (the hub contract's place manifest): each
106
+ * place's title and declared result shape. Ghost normalizes and validates it and
107
+ * pins it to the place's sessions, so a session's results are checked against
108
+ * what was published rather than what its code says. Every other field of the
109
+ * block is the kit's and stays out of the bundle config.
110
+ */
111
+ export interface ServerHubPlaceConfig {
112
+ title?: unknown;
113
+ result?: unknown;
114
+ }
115
+ export interface ServerHubConfig extends ServerHubPlaceConfig {
116
+ places?: Record<string, ServerHubPlaceConfig>;
58
117
  }
59
118
  export declare function resolveServerConfig(dir: string): ResolvedServerConfig | null;
60
119
  export declare function deckStarterScene(dir: string): string;
@@ -25,6 +25,110 @@ export const IMPORTS_DIR = 'imports';
25
25
  // Defined here rather than in imports.ts so forks.ts can name it without a
26
26
  // cycle.
27
27
  export const IMPORT_VERSION_FILE = '.castle-import-version.json';
28
+ export const EXPERIMENTS_CAP = 8;
29
+ export const EXPERIMENT_VARIANTS_MIN = 2;
30
+ export const EXPERIMENT_VARIANTS_CAP = 8;
31
+ // Experiment names and variant names.
32
+ export const EXPERIMENT_NAME = /^[a-z0-9_]{1,32}$/;
33
+ // Names of an experiment Castle runs across decks, and of its variants.
34
+ export const PLATFORM_EXPERIMENT_NAME = /^[a-z0-9_]{1,64}$/;
35
+ // Fit the pattern, but read and write Object.prototype on a plain map, so
36
+ // Castle refuses them as an experiment name and as a variant name.
37
+ const RESERVED_EXPERIMENT_NAMES = ['__proto__', 'constructor'];
38
+ function isExperimentName(value, pattern = EXPERIMENT_NAME) {
39
+ return (typeof value === 'string' && pattern.test(value) && !RESERVED_EXPERIMENT_NAMES.includes(value));
40
+ }
41
+ const EXPERIMENT_NAME_RULE = 'must be 1 through 32 characters of a-z, 0-9 and _ (and not __proto__ or constructor)';
42
+ /**
43
+ * castle.json `experiments`, checked: the block as Castle stores it, or null
44
+ * when the deck declares none. Throws on a block Castle would refuse, naming
45
+ * the experiment and the rule.
46
+ */
47
+ export function validateExperiments(value) {
48
+ if (value === undefined || value === null)
49
+ return null;
50
+ if (!isPlainObject(value)) {
51
+ throw new Error('experiments must be an object keyed by experiment name.');
52
+ }
53
+ const names = Object.keys(value);
54
+ if (names.length > EXPERIMENTS_CAP) {
55
+ throw new Error(`experiments must declare at most ${EXPERIMENTS_CAP} experiments.`);
56
+ }
57
+ return Object.fromEntries(names.map((name) => {
58
+ if (!isExperimentName(name)) {
59
+ throw new Error(`experiments: the name "${name}" ${EXPERIMENT_NAME_RULE}.`);
60
+ }
61
+ return [name, validateExperiment(name, value[name])];
62
+ }));
63
+ }
64
+ function validateExperiment(name, value) {
65
+ if (!isPlainObject(value))
66
+ throw invalidExperiment(name, 'must be an object');
67
+ const unknown = Object.keys(value).find((key) => key !== 'variants' && key !== 'weights' && key !== 'winner');
68
+ if (unknown !== undefined) {
69
+ throw invalidExperiment(name, `has an unknown key "${unknown}" (use variants, weights, winner)`);
70
+ }
71
+ const variants = value.variants;
72
+ if (!Array.isArray(variants) ||
73
+ variants.length < EXPERIMENT_VARIANTS_MIN ||
74
+ variants.length > EXPERIMENT_VARIANTS_CAP) {
75
+ throw invalidExperiment(name, `variants must be an array of ${EXPERIMENT_VARIANTS_MIN} through ${EXPERIMENT_VARIANTS_CAP} names`);
76
+ }
77
+ for (const variant of variants) {
78
+ if (!isExperimentName(variant)) {
79
+ throw invalidExperiment(name, `variant ${JSON.stringify(variant)} ${EXPERIMENT_NAME_RULE}`);
80
+ }
81
+ }
82
+ if (new Set(variants).size !== variants.length) {
83
+ throw invalidExperiment(name, 'variants must not contain duplicates');
84
+ }
85
+ const weights = value.weights;
86
+ if (weights !== undefined) {
87
+ if (!Array.isArray(weights) ||
88
+ weights.length !== variants.length ||
89
+ weights.some((weight) => !Number.isInteger(weight) || weight < 0)) {
90
+ throw invalidExperiment(name, 'weights must be an array of non-negative integers, one per variant');
91
+ }
92
+ const total = weights.reduce((sum, weight) => sum + weight, 0);
93
+ if (total !== 100)
94
+ throw invalidExperiment(name, `weights must sum to 100 (they sum to ${total})`);
95
+ }
96
+ const winner = typeof value.winner === 'string' ? value.winner : undefined;
97
+ if (value.winner !== undefined && (winner === undefined || !variants.includes(winner))) {
98
+ throw invalidExperiment(name, `winner ${JSON.stringify(value.winner)} must be one of its variants`);
99
+ }
100
+ return {
101
+ variants: [...variants],
102
+ ...(weights === undefined ? {} : { weights: [...weights] }),
103
+ ...(winner === undefined ? {} : { winner }),
104
+ };
105
+ }
106
+ function invalidExperiment(name, message) {
107
+ return new Error(`experiments.${name} ${message}.`);
108
+ }
109
+ /**
110
+ * castle.json `devExperiments`, for `castle-web serve`: every `name: variant`
111
+ * pair that is one, with the rest reported to `log` and left out.
112
+ */
113
+ export function isPlatformExperimentName(value) {
114
+ return isExperimentName(value, PLATFORM_EXPERIMENT_NAME);
115
+ }
116
+ export function readDevExperiments(value, log) {
117
+ if (value === undefined)
118
+ return {};
119
+ if (!isPlainObject(value)) {
120
+ log?.('castle.json devExperiments must be an object of experiment name to variant');
121
+ return {};
122
+ }
123
+ return Object.fromEntries(Object.entries(value).filter((entry) => {
124
+ const [name, variant] = entry;
125
+ const valid = isExperimentName(name, PLATFORM_EXPERIMENT_NAME) &&
126
+ isExperimentName(variant, PLATFORM_EXPERIMENT_NAME);
127
+ if (!valid)
128
+ log?.(`castle.json devExperiments.${name} is not a variant name; it is ignored`);
129
+ return valid;
130
+ }));
131
+ }
28
132
  export const DEFAULT_STARTER_SCENE = 'scenes/main.scene';
29
133
  export const DEFAULT_SERVER_TICK_RATE = 20;
30
134
  export const DEFAULT_SERVER_MAX_PLAYERS = 8;
@@ -48,14 +152,43 @@ export function resolveServerConfig(dir) {
48
152
  DEFAULT_SERVER_ENTRIES.find((candidate) => fs.existsSync(path.join(dir, candidate)));
49
153
  if (!entry || !isSafeServerEntry(dir, entry))
50
154
  return null;
155
+ const destinations = server?.destinations === undefined
156
+ ? undefined
157
+ : validateServerDestinations(server.destinations);
158
+ const worldNotifications = server?.worldNotifications === undefined
159
+ ? undefined
160
+ : validateServerWorldNotifications(server.worldNotifications, destinations);
51
161
  return {
52
162
  entry,
53
163
  tickRate: clampNumber(server?.tickRate, DEFAULT_SERVER_TICK_RATE, 0, SERVER_TICK_RATE_CAP),
54
164
  maxPlayers: Math.floor(clampNumber(server?.maxPlayers, DEFAULT_SERVER_MAX_PLAYERS, 1, SERVER_MAX_PLAYERS_CAP)),
55
165
  voiceEnabled: castleJson?.voice?.enabled !== false,
56
- ...(server?.destinations === undefined
57
- ? {}
58
- : { destinations: validateServerDestinations(server.destinations) }),
166
+ ...(destinations === undefined ? {} : { destinations }),
167
+ ...(worldNotifications === undefined ? {} : { worldNotifications }),
168
+ ...(castleJson?.hub === undefined ? {} : { hub: serverHubConfig(castleJson.hub) }),
169
+ };
170
+ }
171
+ // Never throws: `serve` and `check` resolve this too, and the hub block is
172
+ // checked by the kit at publish and by ghost when it is saved. A block that is
173
+ // not the shape reduced here goes to ghost as written, for ghost to refuse.
174
+ function serverHubConfig(value) {
175
+ if (!isPlainObject(value))
176
+ return value;
177
+ const hub = hubPlaceConfig(value);
178
+ if (value.places !== undefined) {
179
+ hub.places = isPlainObject(value.places)
180
+ ? Object.fromEntries(Object.entries(value.places).map(([id, place]) => [
181
+ id,
182
+ isPlainObject(place) ? hubPlaceConfig(place) : place,
183
+ ]))
184
+ : value.places;
185
+ }
186
+ return hub;
187
+ }
188
+ function hubPlaceConfig(place) {
189
+ return {
190
+ ...(place.title === undefined ? {} : { title: place.title }),
191
+ ...(place.result === undefined ? {} : { result: place.result }),
59
192
  };
60
193
  }
61
194
  function validateServerDestinations(value) {
@@ -68,6 +201,17 @@ function validateServerDestinations(value) {
68
201
  throw invalidDestination(index, 'must be an object');
69
202
  }
70
203
  const route = candidate;
204
+ if (Object.keys(route).some((key) => ![
205
+ 'routeId',
206
+ 'access',
207
+ 'selection',
208
+ 'persistence',
209
+ 'maxPlayers',
210
+ 'characters',
211
+ 'worldTime',
212
+ ].includes(key))) {
213
+ throw invalidDestination(index, 'contains an unknown field');
214
+ }
71
215
  const routeId = route.routeId;
72
216
  if (typeof routeId !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(routeId)) {
73
217
  throw invalidDestination(index, 'routeId must match [A-Za-z0-9_-] and be 1 through 64 characters');
@@ -94,6 +238,20 @@ function validateServerDestinations(value) {
94
238
  (route.persistence !== 'world' || route.selection !== 'exact')) {
95
239
  throw invalidDestination(index, 'shared characters require selection "exact" and persistence "world"');
96
240
  }
241
+ let worldTime;
242
+ if (route.worldTime !== undefined) {
243
+ if (route.persistence !== 'world') {
244
+ throw invalidDestination(index, 'worldTime is only valid on a persistent world route');
245
+ }
246
+ if (!route.worldTime ||
247
+ typeof route.worldTime !== 'object' ||
248
+ Array.isArray(route.worldTime) ||
249
+ Object.keys(route.worldTime).some((key) => key !== 'advance') ||
250
+ route.worldTime.advance !== 'wallClock') {
251
+ throw invalidDestination(index, 'worldTime.advance must be wallClock');
252
+ }
253
+ worldTime = { advance: 'wallClock' };
254
+ }
97
255
  if (!Number.isInteger(route.maxPlayers) ||
98
256
  route.maxPlayers < 1 ||
99
257
  route.maxPlayers > SERVER_MAX_PLAYERS_CAP) {
@@ -105,10 +263,113 @@ function validateServerDestinations(value) {
105
263
  selection: route.selection,
106
264
  persistence: route.persistence,
107
265
  ...(route.characters === 'shared' ? { characters: 'shared' } : {}),
266
+ ...(worldTime === undefined ? {} : { worldTime }),
108
267
  maxPlayers: route.maxPlayers,
109
268
  };
110
269
  });
111
270
  }
271
+ const SERVER_WORLD_NOTIFICATION_TEMPLATES_CAP = 16;
272
+ const SERVER_WORLD_NOTIFICATION_SLOTS_CAP = 4;
273
+ const SAFE_WORLD_NOTIFICATION_KEY = /^[A-Za-z0-9_-]+$/;
274
+ const WORLD_NOTIFICATION_PLACEHOLDER = /\{([A-Za-z0-9_-]+)\}/g;
275
+ const WORLD_NOTIFICATION_URL = /(?:https?:\/\/|www\.|\b[a-z0-9-]+\.(?:app|com|dev|gg|io|net|org|xyz)\b)/i;
276
+ function worldNotificationCharacters(value) {
277
+ return Array.from(value).length;
278
+ }
279
+ function isWorldNotificationSafeKey(value) {
280
+ return typeof value === 'string' &&
281
+ worldNotificationCharacters(value) >= 1 &&
282
+ worldNotificationCharacters(value) <= 64 &&
283
+ SAFE_WORLD_NOTIFICATION_KEY.test(value);
284
+ }
285
+ function validateServerWorldNotifications(value, destinations) {
286
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
287
+ throw invalidWorldNotifications('must be an object');
288
+ }
289
+ const config = value;
290
+ if (Object.keys(config).some((key) => key !== 'version' && key !== 'templates')) {
291
+ throw invalidWorldNotifications('contains an unsupported field');
292
+ }
293
+ if (config.version !== 1)
294
+ throw invalidWorldNotifications('version must be 1');
295
+ if (!Array.isArray(config.templates) ||
296
+ config.templates.length > SERVER_WORLD_NOTIFICATION_TEMPLATES_CAP) {
297
+ throw invalidWorldNotifications(`templates must be an array of at most ${SERVER_WORLD_NOTIFICATION_TEMPLATES_CAP} templates`);
298
+ }
299
+ if (!destinations?.some((route) => route.persistence === 'world')) {
300
+ throw invalidWorldNotifications('requires at least one persistent world destination');
301
+ }
302
+ const templateIds = new Set();
303
+ const templates = config.templates.map((candidate, index) => {
304
+ if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
305
+ throw invalidWorldNotificationTemplate(index, 'must be an object');
306
+ }
307
+ const template = candidate;
308
+ if (Object.keys(template).some((key) => key !== 'id' && key !== 'text' && key !== 'slots' && key !== 'timeSensitive')) {
309
+ throw invalidWorldNotificationTemplate(index, 'contains an unsupported field');
310
+ }
311
+ if (!isWorldNotificationSafeKey(template.id)) {
312
+ throw invalidWorldNotificationTemplate(index, 'id must be a safe key of at most 64 characters');
313
+ }
314
+ if (templateIds.has(template.id)) {
315
+ throw invalidWorldNotificationTemplate(index, `id "${template.id}" is duplicated`);
316
+ }
317
+ templateIds.add(template.id);
318
+ if (typeof template.text !== 'string' ||
319
+ worldNotificationCharacters(template.text) < 1 ||
320
+ worldNotificationCharacters(template.text) > 120 ||
321
+ template.text.includes('\n') ||
322
+ template.text.includes('\r') ||
323
+ WORLD_NOTIFICATION_URL.test(template.text)) {
324
+ throw invalidWorldNotificationTemplate(index, 'text must be 1 through 120 characters on one line and contain no URL');
325
+ }
326
+ if (!Array.isArray(template.slots) || template.slots.length > SERVER_WORLD_NOTIFICATION_SLOTS_CAP) {
327
+ throw invalidWorldNotificationTemplate(index, `slots must be an array of at most ${SERVER_WORLD_NOTIFICATION_SLOTS_CAP} safe keys`);
328
+ }
329
+ const slots = template.slots.map((slot, slotIndex) => {
330
+ if (!isWorldNotificationSafeKey(slot)) {
331
+ throw invalidWorldNotificationTemplate(index, `slots[${slotIndex}] must be a safe key`);
332
+ }
333
+ return slot;
334
+ });
335
+ if (new Set(slots).size !== slots.length) {
336
+ throw invalidWorldNotificationTemplate(index, 'slots must not contain duplicates');
337
+ }
338
+ if (slots.includes('actor')) {
339
+ throw invalidWorldNotificationTemplate(index, 'slots cannot declare the reserved name actor');
340
+ }
341
+ const placeholders = new Set();
342
+ for (const match of template.text.matchAll(WORLD_NOTIFICATION_PLACEHOLDER)) {
343
+ const placeholder = match[1];
344
+ placeholders.add(placeholder);
345
+ }
346
+ const textWithoutPlaceholders = template.text.replace(WORLD_NOTIFICATION_PLACEHOLDER, '');
347
+ if (textWithoutPlaceholders.includes('{') || textWithoutPlaceholders.includes('}')) {
348
+ throw invalidWorldNotificationTemplate(index, 'text contains an invalid placeholder');
349
+ }
350
+ for (const placeholder of placeholders) {
351
+ if (!slots.includes(placeholder)) {
352
+ throw invalidWorldNotificationTemplate(index, `placeholder "${placeholder}" must appear in slots`);
353
+ }
354
+ }
355
+ if (template.timeSensitive !== undefined && typeof template.timeSensitive !== 'boolean') {
356
+ throw invalidWorldNotificationTemplate(index, 'timeSensitive must be a boolean when present');
357
+ }
358
+ return {
359
+ id: template.id,
360
+ text: template.text,
361
+ slots,
362
+ timeSensitive: template.timeSensitive === true,
363
+ };
364
+ });
365
+ return { version: 1, templates };
366
+ }
367
+ function invalidWorldNotifications(message) {
368
+ return new Error(`server.worldNotifications ${message}.`);
369
+ }
370
+ function invalidWorldNotificationTemplate(index, message) {
371
+ return new Error(`server.worldNotifications.templates[${index}] ${message}.`);
372
+ }
112
373
  function invalidDestination(index, message) {
113
374
  return new Error(`server.destinations[${index}] ${message}.`);
114
375
  }
@@ -158,3 +419,6 @@ export function readCastleJsonOrThrow(dir) {
158
419
  throw new Error(`Could not read ${file}: ${e instanceof Error ? e.message : String(e)}`);
159
420
  });
160
421
  }
422
+ function isPlainObject(value) {
423
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
424
+ }
package/dist/check.js CHANGED
@@ -1,8 +1,10 @@
1
1
  import * as fs from 'fs';
2
2
  import * as path from 'path';
3
3
  import { bundleProject } from './bundle.js';
4
- import { resolveServerConfig } from './castleJson.js';
4
+ import { readCastleJson, resolveServerConfig, validateExperiments } from './castleJson.js';
5
+ import { importChecksFailedMessage, runImportChecks } from './importCheckHook.js';
5
6
  import { buildServerBundle } from './serverBundle.js';
7
+ import { buildContentPack } from './contentPack.js';
6
8
  // `castle-web check` -- do this deck and its authoritative server still build?
7
9
  //
8
10
  // These are the gates that matter wherever a deck came from: they are the same
@@ -10,6 +12,11 @@ import { buildServerBundle } from './serverBundle.js';
10
12
  // broken. A kit adds its own lint and duplicate gates on top through its own
11
13
  // `check` script; a deck built on nothing has no lint config to run, and used to
12
14
  // have no way to answer the question at all.
15
+ //
16
+ // After both builds, every import's `onCheck` (and the deck's own) runs: the
17
+ // rules a kit holds the decks built on it to, which no bundler can see. Those
18
+ // gate `save-deck` the same way (importCheckHook.ts). Then the content pack, when
19
+ // an import exports one (contentPack.ts).
13
20
  export async function check(dir) {
14
21
  const deckDir = path.resolve(dir);
15
22
  if (!fs.existsSync(path.join(deckDir, 'index.html'))) {
@@ -25,6 +32,25 @@ export async function check(dir) {
25
32
  throw new Error('Server entry disappeared while bundling.');
26
33
  console.log('Server bundle OK.');
27
34
  }
35
+ // The same check `save-deck` makes before it publishes anything.
36
+ try {
37
+ if (validateExperiments(readCastleJson(deckDir)?.experiments))
38
+ console.log('Experiments OK.');
39
+ }
40
+ catch (e) {
41
+ throw new Error(`castle.json ${e instanceof Error ? e.message : String(e)}`);
42
+ }
43
+ const { outcomes, errors } = await runImportChecks(deckDir);
44
+ if (errors.length > 0)
45
+ throw new Error(importChecksFailedMessage(errors));
46
+ if (outcomes.length > 0) {
47
+ console.log(`Deck checks OK (${outcomes.map((o) => o.alias).join(', ')}).`);
48
+ }
49
+ // A deck that cannot pack would publish without its content, so it fails here.
50
+ const pack = await buildContentPack(deckDir);
51
+ if (pack) {
52
+ console.log(`Content pack OK (${pack.alias}): ${pack.summary ?? `${pack.bytes.byteLength} bytes`}, sha256 ${pack.sha256}.`);
53
+ }
28
54
  }
29
55
  catch (e) {
30
56
  console.error(e instanceof Error ? e.message : String(e));
@@ -15,6 +15,11 @@ export declare const EXIT_CONFLICT = 3;
15
15
  * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
16
16
  */
17
17
  export declare const EXIT_HISTORY_UNAVAILABLE = 4;
18
+ /**
19
+ * A first attach outran the caller's deadline and carries on in the background (see
20
+ * attachThroughChild). Not attached yet; the deck works without git until it is.
21
+ */
22
+ export declare const EXIT_ATTACH_CONTINUING = 5;
18
23
  export declare const HISTORY_UNAVAILABLE_CODE = "GIT_HISTORY_UNAVAILABLE";
19
24
  export declare class CloudGitError extends Error {
20
25
  readonly exitCode: number;
@@ -240,6 +245,16 @@ export declare const REHYDRATE_STATE_FILE: string;
240
245
  export declare const REHYDRATE_LOG_FILE: string;
241
246
  /** `off` stops commands from starting a background rehydrate (tests). */
242
247
  export declare const BACKGROUND_REHYDRATE_ENV = "CASTLE_GIT_BACKGROUND_REHYDRATE";
248
+ /** A file each rehydrate appends one JSON outcome line to. The sandbox image points it at the
249
+ * container's own stdout (/proc/1/fd/1), which the host ships to Loki; the log file above does
250
+ * not leave the container. Unset: no event. */
251
+ export declare const CONTAINER_EVENT_LOG_ENV = "CASTLE_CONTAINER_EVENT_LOG";
252
+ /** Held by the child a first attach runs in, for its whole run (see attachThroughChild). */
253
+ export declare const ATTACH_LOCK_FILE: string;
254
+ /** Where that child writes its output. */
255
+ export declare const ATTACH_LOG_FILE: string;
256
+ /** `1` in that child: it attaches in its own process, bound by no caller's deadline. */
257
+ export declare const BACKGROUND_ATTACH_ENV = "CASTLE_GIT_BACKGROUND_ATTACH";
243
258
  export declare const SNAPSHOT_CAP_BYTES: number;
244
259
  /** A smaller cap, for tests. */
245
260
  export declare const SNAPSHOT_CAP_ENV = "CASTLE_GIT_SNAPSHOT_CAP_BYTES";
@@ -346,8 +361,12 @@ export interface AttachOutcome {
346
361
  /** For `adopted`: where the cloud copy's differing files were saved, if any differed. */
347
362
  backup?: string;
348
363
  }
364
+ /** A first attach a child ran to the end within the caller's deadline: the child's own output. */
365
+ export interface ChildAttachOutcome {
366
+ output: string;
367
+ }
349
368
  /** `castle-web git attach <dir> --remote <url>`. */
350
- export declare function cloudAttach(dir: string, remoteUrl: string, deps: CloudGitDeps): Promise<AttachOutcome>;
369
+ export declare function cloudAttach(dir: string, remoteUrl: string, deps: CloudGitDeps): Promise<AttachOutcome | ChildAttachOutcome>;
351
370
  export type GitChangeKind = 'added' | 'changed' | 'deleted';
352
371
  export interface GitVersionEntry {
353
372
  id: string;