@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.
- package/CHANGELOG.md +51 -2
- package/README.md +7 -0
- package/dist/Desync.d.ts +6 -0
- package/dist/Desync.d.ts.map +1 -1
- package/dist/Desync.js.map +1 -1
- package/dist/Determinism.d.ts +3 -0
- package/dist/Determinism.d.ts.map +1 -1
- package/dist/Determinism.js.map +1 -1
- package/dist/Format.d.ts.map +1 -1
- package/dist/Format.js +3 -0
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +7 -0
- package/dist/Fuzz.d.ts.map +1 -1
- package/dist/Fuzz.js +7 -0
- package/dist/Fuzz.js.map +1 -1
- package/dist/Invariant.d.ts +3 -0
- package/dist/Invariant.d.ts.map +1 -1
- package/dist/Invariant.js.map +1 -1
- package/dist/Lint.d.ts +11 -5
- package/dist/Lint.d.ts.map +1 -1
- package/dist/Lint.js.map +1 -1
- package/dist/PlaywrightEngine.d.ts.map +1 -1
- package/dist/PlaywrightEngine.js +3 -0
- package/dist/PlaywrightEngine.js.map +1 -1
- package/dist/Replay.d.ts +8 -2
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +6 -3
- package/dist/Replay.js.map +1 -1
- package/dist/ReplayNodeSink.d.ts.map +1 -1
- package/dist/ReplayNodeSink.js +4 -1
- package/dist/ReplayNodeSink.js.map +1 -1
- package/dist/ReplayVitePlugin.d.ts +1 -0
- package/dist/ReplayVitePlugin.d.ts.map +1 -1
- package/dist/ReplayVitePlugin.js.map +1 -1
- package/dist/Session.d.ts +11 -2
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +8 -1
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +3 -0
- package/dist/Verify.d.ts.map +1 -1
- package/dist/Verify.js +3 -0
- package/dist/Verify.js.map +1 -1
- package/dist/cli.js +22 -9
- package/dist/cli.js.map +1 -1
- package/dist/internal/simulationCoverage.d.ts.map +1 -1
- package/dist/internal/simulationCoverage.js +2 -1
- package/dist/internal/simulationCoverage.js.map +1 -1
- package/dist/internal/skillLink.d.ts +14 -0
- package/dist/internal/skillLink.d.ts.map +1 -0
- package/dist/internal/skillLink.js +46 -0
- package/dist/internal/skillLink.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +3 -3
- package/src/Desync.ts +6 -0
- package/src/Determinism.ts +3 -0
- package/src/Format.ts +2 -0
- package/src/Fuzz.ts +7 -0
- package/src/Invariant.ts +3 -0
- package/src/Lint.ts +11 -5
- package/src/PlaywrightEngine.ts +3 -0
- package/src/Replay.ts +13 -4
- package/src/ReplayNodeSink.ts +4 -1
- package/src/ReplayVitePlugin.ts +1 -0
- package/src/Session.ts +11 -2
- package/src/Verify.ts +3 -0
- package/src/cli.ts +20 -8
- package/src/internal/simulationCoverage.ts +2 -1
- package/src/internal/skillLink.ts +53 -0
- 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/
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
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
|
* }
|
package/src/PlaywrightEngine.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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 })
|
package/src/ReplayNodeSink.ts
CHANGED
|
@@ -7,7 +7,10 @@
|
|
|
7
7
|
*
|
|
8
8
|
* @example
|
|
9
9
|
* ```ts
|
|
10
|
-
* const recorder = Replay.recorder(runtime, {
|
|
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"
|
package/src/ReplayVitePlugin.ts
CHANGED
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
|
|
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
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
+
}
|
package/src/internal/version.ts
CHANGED