@typeonce/ritmo-devtools 0.15.0 → 0.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +51 -2
  2. package/README.md +7 -0
  3. package/dist/Desync.d.ts +6 -0
  4. package/dist/Desync.d.ts.map +1 -1
  5. package/dist/Desync.js.map +1 -1
  6. package/dist/Determinism.d.ts +3 -0
  7. package/dist/Determinism.d.ts.map +1 -1
  8. package/dist/Determinism.js.map +1 -1
  9. package/dist/Format.d.ts.map +1 -1
  10. package/dist/Format.js +3 -0
  11. package/dist/Format.js.map +1 -1
  12. package/dist/Fuzz.d.ts +7 -0
  13. package/dist/Fuzz.d.ts.map +1 -1
  14. package/dist/Fuzz.js +7 -0
  15. package/dist/Fuzz.js.map +1 -1
  16. package/dist/Invariant.d.ts +3 -0
  17. package/dist/Invariant.d.ts.map +1 -1
  18. package/dist/Invariant.js.map +1 -1
  19. package/dist/Lint.d.ts +11 -5
  20. package/dist/Lint.d.ts.map +1 -1
  21. package/dist/Lint.js.map +1 -1
  22. package/dist/PlaywrightEngine.d.ts.map +1 -1
  23. package/dist/PlaywrightEngine.js +3 -0
  24. package/dist/PlaywrightEngine.js.map +1 -1
  25. package/dist/Replay.d.ts +8 -2
  26. package/dist/Replay.d.ts.map +1 -1
  27. package/dist/Replay.js +6 -3
  28. package/dist/Replay.js.map +1 -1
  29. package/dist/ReplayNodeSink.d.ts.map +1 -1
  30. package/dist/ReplayNodeSink.js +4 -1
  31. package/dist/ReplayNodeSink.js.map +1 -1
  32. package/dist/ReplayVitePlugin.d.ts +1 -0
  33. package/dist/ReplayVitePlugin.d.ts.map +1 -1
  34. package/dist/ReplayVitePlugin.js.map +1 -1
  35. package/dist/Session.d.ts +11 -2
  36. package/dist/Session.d.ts.map +1 -1
  37. package/dist/Session.js +8 -1
  38. package/dist/Session.js.map +1 -1
  39. package/dist/Verify.d.ts +3 -0
  40. package/dist/Verify.d.ts.map +1 -1
  41. package/dist/Verify.js +3 -0
  42. package/dist/Verify.js.map +1 -1
  43. package/dist/cli.js +22 -9
  44. package/dist/cli.js.map +1 -1
  45. package/dist/internal/simulationCoverage.d.ts.map +1 -1
  46. package/dist/internal/simulationCoverage.js +2 -1
  47. package/dist/internal/simulationCoverage.js.map +1 -1
  48. package/dist/internal/skillLink.d.ts +14 -0
  49. package/dist/internal/skillLink.d.ts.map +1 -0
  50. package/dist/internal/skillLink.js +46 -0
  51. package/dist/internal/skillLink.js.map +1 -0
  52. package/dist/internal/version.d.ts +1 -1
  53. package/dist/internal/version.js +1 -1
  54. package/package.json +3 -3
  55. package/src/Desync.ts +6 -0
  56. package/src/Determinism.ts +3 -0
  57. package/src/Format.ts +2 -0
  58. package/src/Fuzz.ts +7 -0
  59. package/src/Invariant.ts +3 -0
  60. package/src/Lint.ts +11 -5
  61. package/src/PlaywrightEngine.ts +3 -0
  62. package/src/Replay.ts +13 -4
  63. package/src/ReplayNodeSink.ts +4 -1
  64. package/src/ReplayVitePlugin.ts +1 -0
  65. package/src/Session.ts +11 -2
  66. package/src/Verify.ts +3 -0
  67. package/src/cli.ts +20 -8
  68. package/src/internal/simulationCoverage.ts +2 -1
  69. package/src/internal/skillLink.ts +53 -0
  70. package/src/internal/version.ts +1 -1
package/src/Format.ts CHANGED
@@ -43,6 +43,8 @@ export const entity = (id: number, labels?: Labels): string => {
43
43
  }
44
44
 
45
45
  const formatNumber = (value: number): string => {
46
+ // String(-0) is "0": print the sign, so a -0 / 0 difference does not read "0 -> 0"
47
+ if (Object.is(value, -0)) return "-0"
46
48
  if (!Number.isFinite(value) || Number.isInteger(value)) return String(value)
47
49
  const rounded = Math.round(value * 1000) / 1000
48
50
  return String(rounded === 0 ? 0 : rounded)
package/src/Fuzz.ts CHANGED
@@ -33,6 +33,13 @@
33
33
  *
34
34
  * @example
35
35
  * ```ts
36
+ * const Input = Descriptor.Service<{ snapshot: () => { dx: number } }>()("Game/Input")
37
+ * declare const make: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root, { readonly setup: typeof setup; readonly update: typeof update }>
38
+ * const InsideArena = Invariant.fromInspector(Game.Inspector("inside arena", {
39
+ * queries: { bodies: Game.Query({ selection: { position: Game.Query.read(Position) } }) }
40
+ * }, ({ queries }) => queries.bodies.each().some(({ data }) => data.position.get().x < 0) ? "left the arena" : undefined))
41
+ * declare const sink: Replay.Sink
42
+ * // ---cut---
36
43
  * const Move = Fuzz.input(Input, {
37
44
  * generate: (random) => ({ dx: random.integer(-2, 3) }),
38
45
  * neutral: { dx: 0 }
package/src/Invariant.ts CHANGED
@@ -21,6 +21,9 @@
21
21
  *
22
22
  * @example
23
23
  * ```ts
24
+ * const WORLD_WIDTH = 800
25
+ * const hostClock = HostClock.test()
26
+ * // ---cut---
24
27
  * const PlayerInsideWorld = Invariant.fromInspector(Game.Inspector("player inside world", {
25
28
  * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
26
29
  * }, ({ queries }) => {
package/src/Lint.ts CHANGED
@@ -25,11 +25,17 @@
25
25
  *
26
26
  * @example
27
27
  * ```ts
28
- * // src/lint.ts
29
- * import { createSimulation } from "./simulation.ts"
30
- *
31
- * export const lintTarget = async (): Promise<Lint.Target<typeof Game.schema, typeof Game.schema>> => {
32
- * const { render } = await import("./render.ts")
28
+ * // The game's own modules: src/simulation.ts and src/render.ts.
29
+ * declare const createSimulation: (devices: { readonly keyboard: Keyboard.Actions<typeof bindings> }) => {
30
+ * readonly runtime: typeof runtime
31
+ * readonly setup: typeof setup
32
+ * readonly update: typeof update
33
+ * }
34
+ * declare const importRender: () => Promise<{ readonly render: typeof update }> // import("./render.ts")
35
+ * // ---cut---
36
+ * // src/lint.ts: render code loads only inside lintTarget, never in the simulation.
37
+ * export const lintTarget = async (): Promise<Lint.Target<typeof Game.schema, typeof Root>> => {
38
+ * const { render } = await importRender()
33
39
  * const sim = createSimulation({ keyboard: Keyboard.scripted(bindings, []) })
34
40
  * return { runtime: sim.runtime, schedules: { setup: sim.setup, update: sim.update }, describe: { render } }
35
41
  * }
@@ -24,6 +24,9 @@
24
24
  *
25
25
  * @example
26
26
  * ```ts
27
+ * declare const replayTarget: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root>
28
+ * declare const file: Replay.ReplayFile
29
+ * // ---cut---
27
30
  * const browsers = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit", "firefox"] })
28
31
  * const verified = await Verify.acrossEngines(replayTarget, file, { engines: browsers.engines })
29
32
  * await browsers.close()
package/src/Replay.ts CHANGED
@@ -12,7 +12,9 @@
12
12
  * of the schedule's input services returned from `snapshot()` each tick
13
13
  * (stored as changes from the previous tick), and every `runtime.send`.
14
14
  * Time and randomness live in the world, so that is everything the
15
- * simulation reads. `save(reason)` hands the file to a `Sink`.
15
+ * simulation reads. `save(reason)` hands the file to a `Sink`. For a
16
+ * playtester's "save replay" button, call `recorder.save(reason)` from a
17
+ * key or button handler in the host.
16
18
  * - `session(make, file, { invariants })` restores the start and replays
17
19
  * the ticks in a normal devtools `Session`; `verify` replays twice and compares the
18
20
  * checkpoint hashes to find nondeterminism; `extract` cuts a range of
@@ -34,6 +36,10 @@
34
36
  *
35
37
  * @example
36
38
  * ```ts
39
+ * declare const DeadAreGone: Invariant.Invariant
40
+ * declare const makeReplaySimulation: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root>
41
+ * declare const text: string
42
+ * // ---cut---
37
43
  * const recorder = Replay.recorder(runtime, {
38
44
  * schedule: simulate, name: "simulate", keep: 30, step: Clock.hz(30),
39
45
  * sink: ReplayViteSink.make({ fetch }), hostClock: HostClock.standard,
@@ -265,7 +271,8 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
265
271
  // A tick whose world a `"~encode"` rejects is no starting point; the window keeps the previous one.
266
272
  if (!snapshot.ok) return
267
273
  points.push({ tick, snapshot: snapshot.value, pendingCommands: runtime.debug.dump({ limit: 0 }).pendingCommands.length })
268
- checkpoints.push({ tick, hash: worldHash(runtime.checksum()) })
274
+ const checksum = runtime.checksum()
275
+ checkpoints.push({ tick, hash: worldHash(checksum) })
269
276
  const windowStart = tick - keepTicks
270
277
  let firstNeeded = -1
271
278
  for (let index = 0; index < points.length; index++) if (points[index]!.tick <= windowStart) firstNeeded = index
@@ -549,7 +556,8 @@ export const session = <
549
556
  })
550
557
  const send = target.runtime.send as (descriptor: { readonly kind: "event"; readonly name: string; readonly key: symbol }, value: unknown) => void
551
558
  const events = new Map(target.runtime.debug.describe().events.map(({ name }) => [name, { kind: "event" as const, name, key: Symbol.for(`ritmo/event/${name}`) }]))
552
- const hashes = new Map<number, string>([[ran, worldHash(target.runtime.checksum())]])
559
+ const startChecksum = target.runtime.checksum()
560
+ const hashes = new Map<number, string>([[ran, worldHash(startChecksum)]])
553
561
  const recorded = new Map(file.checkpoints.map(({ tick, hash }) => [tick, hash] as const))
554
562
  const last = file.ticks.at(-1)?.tick ?? file.start.tick
555
563
 
@@ -562,7 +570,8 @@ export const session = <
562
570
  // `until` runs after each frame: the tick is checked, and the next one's input set up before it runs.
563
571
  until: () => {
564
572
  ran += 1
565
- const hash = worldHash(target.runtime.checksum())
573
+ const checksum = target.runtime.checksum()
574
+ const hash = worldHash(checksum)
566
575
  hashes.set(ran, hash)
567
576
  const expected = recorded.get(ran)
568
577
  if (expected !== undefined && expected !== hash) diverged.push({ tick: ran, recorded: expected, replayed: hash })
@@ -7,7 +7,10 @@
7
7
  *
8
8
  * @example
9
9
  * ```ts
10
- * const recorder = Replay.recorder(runtime, { ..., sink: ReplayNodeSink.make({ directory: ".replays" }) })
10
+ * const recorder = Replay.recorder(runtime, {
11
+ * schedule: update, name: "update", keep: 30, step: Clock.hz(60),
12
+ * sink: ReplayNodeSink.make({ directory: ".replays" }), hostClock: HostClock.standard
13
+ * })
11
14
  * ```
12
15
  */
13
16
  import { mkdirSync, writeFileSync } from "node:fs"
@@ -13,6 +13,7 @@
13
13
  * ```ts
14
14
  * // vite.config.ts
15
15
  * import * as ReplayVitePlugin from "@typeonce/ritmo-devtools/ReplayVitePlugin"
16
+ * import { defineConfig } from "vite"
16
17
  * export default defineConfig({ plugins: [ReplayVitePlugin.plugin()] })
17
18
  * ```
18
19
  */
package/src/Session.ts CHANGED
@@ -40,9 +40,16 @@
40
40
  *
41
41
  * @example
42
42
  * ```ts
43
+ * const PlayerInsideWorld = Invariant.fromInspector(Game.Inspector("player inside world", {
44
+ * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
45
+ * }, ({ queries }) => queries.players.each().some(({ data }) => data.position.get().x < 0) ? "left the world" : undefined))
46
+ * const Labels = Game.Inspector("labels", {
47
+ * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
48
+ * }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
49
+ * // ---cut---
43
50
  * const session = Session.make(runtime, {
44
51
  * hostClock: HostClock.test(),
45
- * schedules: { setup: setupSchedule, update: updateSchedule },
52
+ * schedules: { setup, update },
46
53
  * invariants: [PlayerInsideWorld],
47
54
  * labels: Labels
48
55
  * })
@@ -123,7 +130,7 @@ export type ValidateInvariants<
123
130
  * const Labels = Game.Inspector("labels", {
124
131
  * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
125
132
  * }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
126
- * Session.make(runtime, { hostClock, schedules: { update }, labels: Labels })
133
+ * Session.make(runtime, { hostClock: HostClock.test(), schedules: { update }, labels: Labels })
127
134
  * ```
128
135
  */
129
136
  export type LabelsInspector<Root = any> = Inspector.InspectorDefinition<any, unknown, Root, any, any>
@@ -323,6 +330,8 @@ export interface JournalFilter<S extends Schema.Any> {
323
330
  *
324
331
  * @example
325
332
  * ```ts
333
+ * const session = Session.make(runtime, { hostClock: HostClock.test(), schedules: { update } })
334
+ * // ---cut---
326
335
  * session.why(12, Health, { depth: 3 })
327
336
  * // f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
328
337
  * // read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
package/src/Verify.ts CHANGED
@@ -28,6 +28,9 @@
28
28
  *
29
29
  * @example
30
30
  * ```ts
31
+ * declare const replayTarget: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root>
32
+ * declare const file: Replay.ReplayFile
33
+ * // ---cut---
31
34
  * const engines = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit"] })
32
35
  * const verified = await Verify.acrossEngines(replayTarget, file, { engines: engines.engines })
33
36
  * await engines.close()
package/src/cli.ts CHANGED
@@ -21,6 +21,11 @@
21
21
  * A missing or unreadable config, one with `extends`, or one that never turns
22
22
  * the rule on prints why the check was skipped and does not fail.
23
23
  *
24
+ * Last, it notes when the project does not link the Ritmo skill from the
25
+ * installed package (`.agents/skills/ritmo` or `.claude/skills/ritmo`, see
26
+ * `SETUP.md`), or holds a copy that goes stale on upgrade. The note never
27
+ * fails the lint.
28
+ *
24
29
  * `verify` imports `<entry>` (a module exporting `replayTarget`, the
25
30
  * `make(playback)` factory `Replay.session` takes), plays the replay file in
26
31
  * Node and in each listed browser engine, and prints the first tick whose
@@ -56,6 +61,7 @@ import { pathToFileURL } from "node:url"
56
61
 
57
62
  import * as DependencyScan from "./internal/dependencyScan.ts"
58
63
  import * as SimulationCoverage from "./internal/simulationCoverage.ts"
64
+ import * as SkillLink from "./internal/skillLink.ts"
59
65
  import * as Lint from "./Lint.ts"
60
66
  import * as Replay from "./Replay.ts"
61
67
  import * as Verify from "./Verify.ts"
@@ -107,14 +113,20 @@ const lint = async (entry: string): Promise<number> => {
107
113
  }
108
114
  const report = Lint.run(target)
109
115
  console.log(report.text)
110
- if (simulationModules === undefined) {
111
- console.log("simulation coverage not checked: needs Node 22.15 or later (module.registerHooks)")
112
- return report.data.ok ? 0 : 1
113
- }
114
- const coverage = SimulationCoverage.check(process.cwd(), resolve(entry), simulationModules)
115
- const text = SimulationCoverage.format(coverage)
116
- if (text !== "") console.log(text)
117
- return report.data.ok && (!coverage.checked || coverage.uncovered.length === 0) ? 0 : 1
116
+ const status = (() => {
117
+ if (simulationModules === undefined) {
118
+ console.log("simulation coverage not checked: needs Node 22.15 or later (module.registerHooks)")
119
+ return report.data.ok ? 0 : 1
120
+ }
121
+ const coverage = SimulationCoverage.check(process.cwd(), resolve(entry), simulationModules)
122
+ const text = SimulationCoverage.format(coverage)
123
+ if (text !== "") console.log(text)
124
+ return report.data.ok && (!coverage.checked || coverage.uncovered.length === 0) ? 0 : 1
125
+ })()
126
+ // A note only: it never changes the exit code.
127
+ const skill = SkillLink.format(SkillLink.check(process.cwd()))
128
+ if (skill !== "") console.log(skill)
129
+ return status
118
130
  }
119
131
 
120
132
  const engineNames = ["node", "chromium", "webkit", "firefox"] as const
@@ -132,5 +132,6 @@ export const format = (coverage: Coverage): string =>
132
132
  : coverage.uncovered.map((file) =>
133
133
  `uncovered-simulation-module ${file}\n`
134
134
  + ` The simulation loads this file, but the simulation rules in ${configName} do not cover it.\n`
135
- + ` Add it to the simulation override's "files", or stop importing values from it.`
135
+ + ` Add it to the simulation override's "files", or stop importing values from it.\n`
136
+ + ` A host module (render, input glue) imported at the top of the lint entry is loaded too: import it inside lintTarget instead.`
136
137
  ).join("\n")
@@ -0,0 +1,53 @@
1
+ /**
2
+ * The skill check for the `ritmo-devtools lint` CLI (Node only): whether the
3
+ * project links the Ritmo skill from the installed package, as `SETUP.md`
4
+ * step 2 says, so the game's agent reads the playbooks of the installed
5
+ * version. It is a note: it never fails the lint, since where an agent reads
6
+ * skills from is the project's choice.
7
+ */
8
+ import { lstatSync, realpathSync } from "node:fs"
9
+ import { join, sep } from "node:path"
10
+
11
+ /** The folders agents read skills from, relative to the working directory. */
12
+ const folders = [".agents/skills/ritmo", ".claude/skills/ritmo"] as const
13
+
14
+ export type SkillLink =
15
+ | { readonly _tag: "Linked"; readonly path: string }
16
+ | { readonly _tag: "Copied"; readonly path: string }
17
+ | { readonly _tag: "Missing" }
18
+
19
+ // A link into an installed `@typeonce/ritmo` package's skill: `node_modules/@typeonce/ritmo/skills/ritmo`, or pnpm's store path to it.
20
+ const isInstalledSkill = (path: string): boolean =>
21
+ path.includes(`${sep}node_modules${sep}`) && path.endsWith(join("@typeonce", "ritmo", "skills", "ritmo"))
22
+
23
+ /** Where the skill is in `cwd`: linked from the installed package, copied in, or missing. */
24
+ export const check = (cwd: string): SkillLink => {
25
+ let copied: string | undefined
26
+ for (const folder of folders) {
27
+ const path = join(cwd, folder)
28
+ try {
29
+ const stat = lstatSync(path)
30
+ if (stat.isSymbolicLink() && isInstalledSkill(realpathSync(path))) return { _tag: "Linked", path: folder }
31
+ copied ??= folder
32
+ } catch {
33
+ // Not there (or a dangling link): look at the next folder.
34
+ }
35
+ }
36
+ return copied === undefined ? { _tag: "Missing" } : { _tag: "Copied", path: copied }
37
+ }
38
+
39
+ /** The CLI text for a skill check: nothing when linked, a note otherwise. */
40
+ export const format = (link: SkillLink): string => {
41
+ switch (link._tag) {
42
+ case "Linked":
43
+ return ""
44
+ case "Missing":
45
+ return `note skill-not-linked\n`
46
+ + ` No ${folders.join(" or ")} links to node_modules/@typeonce/ritmo/skills/ritmo.\n`
47
+ + ` Link it (SETUP.md step 2) so your agent reads the playbooks for this Ritmo version.`
48
+ case "Copied":
49
+ return `note skill-copied ${link.path}\n`
50
+ + ` This is a copy of the Ritmo skill, or a link to somewhere else: it goes stale on the next upgrade.\n`
51
+ + ` Replace it with a link to node_modules/@typeonce/ritmo/skills/ritmo (SETUP.md step 2).`
52
+ }
53
+ }
@@ -3,4 +3,4 @@
3
3
  * `package.json` by `scripts/sync-version.ts` (run by \`pnpm version-packages\`)
4
4
  * and checked by a test.
5
5
  */
6
- export const libraryVersion = "0.15.0"
6
+ export const libraryVersion = "0.16.1"