@joystack/cli 0.0.0-stage → 0.1.43

package/lib/replay-cmd.mjs

@@ -0,0 +1,426 @@
+// `joystack replay list`, `joystack replay export` and `joystack replay profile` — the
+// sessions a game has recorded, and each one on disk as tables.
+//
+// This is the CLI's half: find the game, resolve the engine it is pinned to,
+// hand both to the exporter or the profiler, and then say enough about what
+// came out that the next step is obvious. The tables' shape and every decision
+// about them live in replay-export.mjs and replay-profile.mjs; nothing here
+// knows what a column is.
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { realpathSync, statSync } from 'node:fs';
+import { findProject } from './project.mjs';
+import { streamDir } from './replay-store.mjs';
+import { isGameFilePath, gitIgnored } from './game-files.mjs';
+import { listSessions } from './replay-list.mjs';
+import { ensureEngine } from './engine.mjs';
+import { exportSession } from './replay-export.mjs';
+import { parseTickRange, profileSession } from './replay-profile.mjs';
+import { stateDir } from './legacy-names.mjs';
+
+export const EXPORTS_DIR = ['.joystack', 'exports'];
+const PROFILE_ENOUGH_SAMPLES = 300;
+
+export const REPLAY_HELP = `joystack replay — work with the sessions this game has recorded
+
+Usage:
+  joystack replay list    [--json]
+  joystack replay export  [<session>] [--out <dir>]
+  joystack replay profile [<session>] --ticks <a-b> [--repeat <n>] [--out <dir>]
+
+  <session>  Which recording. Defaults to the most recent one.
+  --out      Where the tables go. Defaults to .joystack/exports/. Anywhere outside
+             the game works; inside it, only a folder that is not part of the
+             game (under .joystack/, or one your .gitignore excludes).
+  --json     \`list\` prints its facts as JSON.
+  --ticks    Which ticks \`profile\` re-runs: 1195-1228, or one tick.
+  --repeat   How many times \`profile\` runs those ticks, summing the samples.
+
+\`list\` says what each recorded session is, without replaying it: when and for
+how long, how many players, the device each measuring browser ran on (and
+whether automation drove it), how many of its frames were late and where its
+worst stutter in play was, and which code recorded it — the engine version,
+the code fingerprint (the shape of the simulation), and the build id (the
+exact game files, with the git commit they came from). A session whose build
+is not the one in the folder now was played on other code. Sessions under a
+second are left out; --json lists every one.
+
+\`export\` writes the session as four Parquet tables on the same tick axis,
+and a fifth that says what the state table's columns are:
+
+  <session>.state.parquet    one row per tick per entity, every declared field
+                             a column (tick/id/def/owner lead)
+  <session>.inputs.parquet   one row per input a player sent
+  <session>.perf.parquet     what it cost on each device that played: one row
+                             per frame, per second, per kind per second and
+                             per long frame (only when the session was measured)
+  <session>.info.parquet     the session itself: its span, each player, each
+                             browser's device, and the ticks where a table
+                             cannot be taken at its word — not measured, or
+                             replayed into a world nobody played
+  <session>.fields.parquet   one row per state column and per channel: the
+                             kind, the trait behind it, and its source file
+                             and line (a field adds its name, type, default;
+                             a channel, who sends on it)
+
+A recording holds what was PRESSED, not what happened — so the export replays
+the session through your game to work out where everything was, then writes it
+down. That costs a while once; every question asked of the tables afterwards
+is SQL.
+
+\`profile\` re-runs the ticks you name under a CPU profiler and writes which
+handlers, functions and lines spent the time: each tick's and channel
+handler's share, each function credited to the handler and to the game
+function it ran under, and each line samples landed on —
+<session>.profile.<a>-<b>.parquet. Its shares are this machine's, never the
+device's milliseconds — the perf table says what the ticks cost where they
+were played; the profile says what ran in them.
+
+Why a session stuttered, question by question, and the perf, info and profile
+tables column by column:
+  node_modules/@joystack/engine/shared/docs/debugging.md
+The state, inputs and fields tables, for measuring how someone played:
+  node_modules/@joystack/engine/shared/docs/replay-export.md
+
+  duckdb -c "SELECT def, count(*) FROM '.joystack/exports/<session>.state.parquet' GROUP BY def"
+`;
+
+/**
+ * Split `joystack replay …`'s arguments into the verb, the session, and the flags.
+ *
+ * A flag's VALUE is a positional-looking word, so dropping only the tokens that
+ * start with `--` leaves `tables` from `--out tables` sitting in the session
+ * slot — and the export then reports it cannot find a recording the creator
+ * never named. The same trap is why `--help` has to be answered before any of
+ * this is used as an id.
+ */
+// The flags that take no value. A flag's value looks positional, so the filter
+// below skips the token after a flag — which would swallow the session id that
+// follows a value-less one. Every value-less flag has to be listed here.
+const BOOLEAN_FLAGS = new Set(['--help', '--json']);
+
+// Which commands read each flag. An unknown verb is left to its own error.
+const KNOWN_VERBS = new Set(['list', 'export', 'profile']);
+const FLAG_VERBS = { ticks: ['profile'], repeat: ['profile'], json: ['list'], out: ['export', 'profile'] };
+
+export function parseReplayArgs(argv = []) {
+  // A flag's value is the next word, or follows `=` in the same one.
+  const flag = (name) => {
+    const joined = argv.find((a) => a.startsWith(`--${name}=`));
+    if (joined !== undefined) return joined.slice(name.length + 3);
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const has = (name) => argv.some((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+  const positional = argv.filter((a, i) => {
+    if (a.startsWith('-')) return false;
+    const before = argv[i - 1];
+    return !(before?.startsWith('--') && !before.includes('=') && !BOOLEAN_FLAGS.has(before));
+  });
+  const [verb, id] = positional;
+  const help = !verb || verb === 'help' || argv.includes('--help') || argv.includes('-h');
+  // Help is answered before any value is judged: `profile --ticks --help` asks
+  // how to write the ticks.
+  if (help) return { verb, id, help };
+  // A flag given to a command that does not read it is refused: ignored, it
+  // would look as though it had been obeyed.
+  for (const [name, verbs] of Object.entries(FLAG_VERBS)) {
+    if (has(name) && KNOWN_VERBS.has(verb) && !verbs.includes(verb)) {
+      throw new Error(`--${name} is for ${verbs.map((v) => `\`joystack replay ${v}\``).join(' and ')}, not \`${verb}\``);
+    }
+  }
+  return {
+    verb,
+    id,
+    out: flag('out'),
+    ticks: has('ticks') ? parseTickRange(flag('ticks')) : undefined,
+    json: argv.includes('--json'),
+    repeat: has('repeat') ? parseRepeat(flag('repeat')) : undefined,
+    help,
+  };
+}
+
+// `--repeat 5`: how many times `profile` runs the ticks.
+function parseRepeat(text) {
+  const n = /^\s*\d+\s*$/.test(String(text ?? '')) ? Number(text) : NaN;
+  if (!Number.isSafeInteger(n) || n < 1 || n > 1000) {
+    throw new Error(`--repeat takes how many times to run the ticks, like 5, and ${JSON.stringify(String(text ?? ''))} is not one`);
+  }
+  return n;
+}
+
+// A table's path as the creator would type it: relative inside the game
+// folder, where commands run, and in full anywhere else.
+function shownPath(dir, file) {
+  const rel = relative(dir, file);
+  return rel && !rel.startsWith('..') && !isAbsolute(rel) ? rel : file;
+}
+
+// A path with every link resolved: the deepest part that exists is resolved
+// on disk, and the rest, not yet created, is appended to it.
+function realPathOf(p) {
+  const rest = [];
+  let at = resolve(p);
+  for (;;) {
+    try {
+      return join(realpathSync(at), ...rest.reverse());
+    } catch {
+      const up = dirname(at);
+      if (up === at) return resolve(p);
+      rest.push(basename(at));
+      at = up;
+    }
+  }
+}
+
+// Where the tables go. Anywhere outside the game folder is the creator's
+// business. Inside it, only where they do not become game files: a plain
+// folder in the game is uploaded by `joystack publish` and counted in the game's
+// build id, and tens of megabytes of tables are neither. `.joystack/`, any
+// dot-folder and anything the game's .gitignore excludes are not game files.
+function outDirFor(projectDir, out) {
+  const outDir = out ? resolve(projectDir, out) : join(stateDir(projectDir), 'exports');
+  // Compared as the disk sees them: through any link, and without case where
+  // the disk ignores it, so a second spelling of a folder in the game is
+  // still in the game.
+  const root = realPathOf(projectDir);
+  const target = realPathOf(outDir);
+  const fold = (p) => (process.platform === 'darwin' || process.platform === 'win32' ? p.toLowerCase() : p);
+  if (fold(target) === fold(root) || fold(target).startsWith(fold(`${root}${sep}`))) {
+    const inner = target.slice(root.length).split(sep).filter(Boolean);
+    const probe = [...inner, 'x.parquet'].join('/');
+    if (isGameFilePath(probe) && !gitIgnored(root, [probe]).has(probe)) {
+      throw new Error(`--out ${out ?? ''}: tables written there would become part of your game — published with it, `
+        + "and counted in its build id. Use a folder under .joystack/, one the .gitignore of your git repository excludes, or one outside the game.");
+    }
+  }
+  return outDir;
+}
+
+// What reaches the terminal from a replay includes the replayer's own lines,
+// which quote the recording (an event's kind, a tuned key), and a recording is
+// not first-party text: an escape sequence in one would repaint the screen of
+// whoever runs the command. Every line is printed without control characters.
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+const clean = (log) => (msg) => log(String(msg).replace(CONTROL, ''));
+
+// How many times a replay drifted and over which ticks, as a sentence: one
+// drift is one range of ticks, however many checksums failed inside it.
+// `drifts` comes from the info table's `diverged` rows; without it, only the
+// count of failed checks is known.
+function driftSummary({ drifts = [], divergences = 0 }) {
+  const n = drifts.length || divergences;
+  const times = n === 1 ? 'once' : n === 2 ? 'twice' : `${n} times`;
+  const plural = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
+  const ranges = drifts.slice(0, 3).map((d) => {
+    const how = d.via === 'keyframe' ? 'no checksum ran into it; a keyframe put it back'
+      : Number.isSafeInteger(d.checks) ? plural(d.checks, 'failed checksum') : null;
+    return `ticks ${d.from}–${d.to}${how ? ` (${how})` : ''}`;
+  });
+  if (drifts.length > 3) ranges.push(`and ${drifts.length - 3} more`);
+  return `the replay drifted from the recording ${times}${ranges.length ? `: ${ranges.join(', ')}` : ''}`;
+}
+
+const mb = (file) => `${(statSync(file).size / 1024 / 1024).toFixed(1)} MB`;
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.stream] - which recording; defaults to the most recent
+ * @param {string} [opts.out] - where the tables go
+ * @param {(msg: string) => void} [opts.log]
+ * @param {(dir: string, o: object) => Promise<object>} [opts.ensureEngineImpl]
+ * @param {(o: object) => Promise<object>} [opts.exportImpl]
+ */
+export async function replayExport({
+  cwd = process.cwd(), stream, out, log: rawLog = console.log,
+  ensureEngineImpl = ensureEngine, exportImpl = exportSession,
+} = {}) {
+  const log = clean(rawLog);
+  const project = findProject(cwd);
+  // The id is about to become a path to read from AND a filename to write. Every
+  // other door into the store runs one through `streamDir`, which refuses rather
+  // than sanitizes; this one is no different for being typed by hand.
+  if (stream) streamDir(project.dir, stream);
+  const outDir = outDirFor(project.dir, out);
+  const engine = await ensureEngineImpl(project.dir, { log });
+
+  const started = Date.now();
+  const res = await exportImpl({
+    dir: project.dir, stream, outDir, sharedDir: engine.sharedDir,
+    engineVersion: engine.version, log,
+  });
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
+
+  const rel = (f) => shownPath(project.dir, f);
+  log(`exported ${res.stream} in ${secs}s`);
+  log(`  ${rel(res.stateFile)}   ${res.rows.toLocaleString()} rows x ${res.columns} columns  (${mb(res.stateFile)})`);
+  log(`  ${rel(res.inputFile)}  ${res.inputs.toLocaleString()} inputs  (${mb(res.inputFile)})`);
+  if (res.perfFile) {
+    log(`  ${rel(res.perfFile)}   ${res.perfRows.toLocaleString()} cost rows  (${mb(res.perfFile)})`);
+  } else {
+    log('  (no performance track: this session was recorded with measuring switched off)');
+  }
+  if (res.infoFile) log(`  ${rel(res.infoFile)}   ${res.infoRows.toLocaleString()} session info rows`);
+  if (res.fieldsFile) log(`  ${rel(res.fieldsFile)} ${res.fieldsRows.toLocaleString()} fields and channels, each with the trait and line behind it`);
+  // Three different ways the tables can describe a world that is not the one
+  // that was played. None of them is buried: an export that looks clean and is
+  // not is worse than one that failed, because the answers it gives are wrong
+  // and confident. The info table says exactly which ticks each covers; these
+  // lines only say that there are some, and where to look.
+  if (res.divergences) {
+    // The cause is named only as far as the export knows it. A drift of the
+    // same build is a determinism fault, and blaming an edit there sends the
+    // reader to look for one that does not exist.
+    let cause;
+    if (res.codeChanged) {
+      cause = 'The game has changed since the session was recorded, and a replay runs the code as it is now.';
+    } else if (res.buildChanged === true) {
+      cause = "The game's files have changed since the session was recorded, and a replay runs the code as it is now.";
+    } else if (res.buildChanged === false) {
+      cause = 'This is the same build that recorded it, so something in the game did not replay the same way twice.';
+    } else {
+      cause = "The simulation's shape has not changed since, but this recording has no build id, so an edit "
+        + 'inside a tick cannot be ruled out.';
+    }
+    log(`  ⚠ ${driftSummary(res)}. In those ticks (the info table's \`diverged\` rows) the state is this `
+      + "run's world, not the one that was played. " + cause);
+  }
+  if (res.gaps) {
+    log(`  ⚠ the recording is missing ${res.gaps} segment(s) — the inputs in them were never stored `
+      + "(the info table's `missing_segment` rows)");
+  }
+  if (res.unsupported) {
+    log(`  ⚠ ${res.unsupported} recorded event(s) cannot be reproduced by a replay, a live tune say — `
+      + "the world after each one is not the one that was played (the info table's `unsupported` rows)");
+  }
+  // Repeated from before the replay. That is the right place to say it first —
+  // the answer is known and the replay is the slow part — but a big export puts
+  // screens of output in between, so the line deciding whether to trust the
+  // table would be the one line scrolled off. Costs nothing; both values are
+  // already on the result.
+  if (res.recordedEngine && res.runningEngine && res.recordedEngine !== res.runningEngine) {
+    log(`  ⚠ recorded by engine ${res.recordedEngine}, replayed on ${res.runningEngine}`);
+  }
+  if (res.codeChanged) {
+    log('  ⚠ the game has changed since this session was recorded');
+  } else if (res.buildChanged === true) {
+    log(`  ⚠ the game's files have changed since this session was recorded (build ${res.recordedBuild}, now ${res.runningBuild})`);
+  }
+  if (res.undoubleable) {
+    log(`  note: ${res.undoubleable} numeric cell(s) held NaN or ±Infinity, which Parquet has no double `
+      + 'for, and read as null — the same as a field the entity kind does not declare');
+  }
+  log('');
+  log(`Ask it something:  duckdb -c "SELECT def, count(*) FROM '${rel(res.stateFile)}' GROUP BY def"`);
+  return res;
+}
+
+/**
+ * `joystack replay profile` — which functions ran in a stretch of a recorded
+ * session, re-run here under a CPU profiler and written as a table.
+ *
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.stream] - which recording; defaults to the most recent
+ * @param {{from: number, to: number}} [opts.ticks] - the ticks to re-run
+ * @param {string} [opts.out] - where the table goes
+ * @param {(msg: string) => void} [opts.log]
+ */
+export async function replayProfile({
+  cwd = process.cwd(), stream, ticks, out, repeat = 1, log: rawLog = console.log,
+  ensureEngineImpl = ensureEngine, profileImpl = profileSession,
+} = {}) {
+  const log = clean(rawLog);
+  const project = findProject(cwd);
+  if (stream) streamDir(project.dir, stream);
+  const outDir = outDirFor(project.dir, out);
+  const engine = await ensureEngineImpl(project.dir, { log });
+  const res = await profileImpl({ dir: project.dir, stream, ticks, outDir, sharedDir: engine.sharedDir, repeat, log });
+  const rel = shownPath(project.dir, res.file);
+  const runs = res.repeat > 1 ? `, run ${res.repeat} times` : '';
+  log(`profiled ${res.stream} ticks ${res.fromTick}–${res.toTick}${runs}: ${res.samples.toLocaleString()} samples`);
+  log(`  ${rel}`);
+  log('  shares of THIS machine\'s samples, not the device\'s time');
+  // Below a few hundred samples one sample is most of a percent, and a
+  // ranking of functions is mostly noise.
+  if (res.samples < PROFILE_ENOUGH_SAMPLES) {
+    log(`  ⚠ only ${res.samples.toLocaleString()} samples: too few for the shares to mean much. Widen --ticks, `
+      + 'or run the same ticks again with --repeat 5.');
+  }
+  return res;
+}
+
+// A session's start as the person who played it would read it: local time,
+// to the minute.
+const localTime = (iso) => {
+  const d = new Date(iso ?? NaN);
+  if (Number.isNaN(d.getTime())) return 'unknown start';
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+};
+
+/**
+ * `joystack replay list` — every recorded session, newest first, with what it is:
+ * when and how long, who played, which browsers measured it on what device,
+ * and which engine, code and build recorded it. Nothing is replayed.
+ *
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {boolean} [opts.json] - print the facts as JSON instead
+ * @param {(msg: string) => void} [opts.log]
+ * @param {Function} [opts.listImpl] - seam for tests
+ */
+export async function replayList({ cwd = process.cwd(), json = false, log: rawLog = console.log, listImpl = listSessions } = {}) {
+  const log = clean(rawLog);
+  const project = findProject(cwd);
+  const sessions = listImpl(project.dir);
+  if (json) {
+    log(JSON.stringify(sessions, null, 2));
+    return sessions;
+  }
+  if (!sessions.length) {
+    log('no recorded sessions in .joystack/replays/ — `joystack dev` records every session played while it runs');
+    return sessions;
+  }
+  // A session under a second is a page opened and closed — a reload, a test
+  // booting the game — and never the one a question is about. `--json` still
+  // lists it.
+  const shown = sessions.filter((s) => s.seconds == null || s.seconds >= 1);
+  const short = sessions.length - shown.length;
+  log(`${shown.length} recorded session(s), newest first:`);
+  let unstamped = false;
+  for (const s of shown) {
+    const who = `${s.players} player${s.players === 1 ? '' : 's'}`;
+    const len = s.seconds == null ? 'unknown length' : `${s.seconds} s`;
+    log('');
+    log(`${s.stream}  ${localTime(s.startedAt)}  ${len}  ${who}${s.watchable ? '' : '  (not watchable yet)'}${s.kept ? '  kept' : ''}`);
+    if (!s.measured) log('  not measured');
+    for (const d of s.measured ? s.devices : []) {
+      const bits = [d.cores != null ? `${d.cores} cores` : null, d.touch ? 'touch' : null, d.viewport].filter(Boolean);
+      log(`  measured on ${d.device ?? 'unknown device'}${bits.length ? ` (${bits.join(', ')})` : ''}`
+        + `${d.automated ? ', driven by automation, not a person' : ''}`);
+      if (d.frames && d.budgetMs == null) {
+        log(`    ${d.frames.toLocaleString('en-US')} frames, late frames unknown: none has an interval to set a budget by`);
+      } else if (d.frames) {
+        const w = d.worstStutter;
+        const worst = w ? `; worst stutter in play: ${Math.round(w.overMs)} ms over, ${w.frames} frame${w.frames === 1 ? '' : 's'}`
+          + `, ${w.fromS === w.toS ? w.fromS : `${w.fromS}–${w.toS}`} s (ticks ${w.tickFrom}–${w.tickTo})` : '';
+        log(`    ${d.late.toLocaleString('en-US')} of ${d.frames.toLocaleString('en-US')} frames late`
+          + `${d.budgetMs != null ? ` (budget ${d.budgetMs} ms)` : ''}${worst}`
+          + `${d.partial ? ' — over the start of its track only; the track is larger than the list reads' : ''}`);
+      }
+    }
+    if (!s.build) unstamped = true;
+    const build = s.build
+      ? `build ${s.build}${s.buildIsCurrent === true ? ' (the build in this folder now)' : s.buildIsCurrent === false ? ' (not the build in this folder now)' : ''}`
+      : 'build unknown';
+    const commit = s.commit ? ` · commit ${s.commit.slice(0, 10)}${s.uncommitted ? ' + uncommitted changes' : ''}` : '';
+    log(`  engine ${s.engine ?? 'unknown'} · code ${s.code ?? 'unknown'} · ${build}${commit}`);
+  }
+  log('');
+  if (unstamped) log('build unknown: the session has no build stamp — recorded by an older joystack, or copied in without one.');
+  if (short) log(`${short} session${short === 1 ? '' : 's'} under a second not shown (--json lists them).`);
+  log('Late frames and stutters are counted as the debugging docs\' recorded-session method counts them.');
+  log('Export one:  joystack replay export <session>');
+  return sessions;
+}