pi-mega-compact 0.7.8 → 0.8.0

package/src/store/sqlite/game-scores.test.ts

@@ -0,0 +1,132 @@
+/**
+ * game-scores.test.ts — S33 game_scores table round-trip + leaderboard ordering.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import {
+	recordScore,
+	leaderboard,
+	METRICS,
+	type GameMetric,
+} from "./game-scores.js";
+
+describe("game-scores (S33)", () => {
+	let dir: string;
+	before(() => {
+		dir = mkdtempSync(join(tmpdir(), "mc-gamescores-"));
+		process.env.MEGACOMPACT_STATE_DIR = dir;
+	});
+	after(() => {
+		closeStore(dir);
+		delete process.env.MEGACOMPACT_STATE_DIR;
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	it("records + reads back a cache score with parsed meta", () => {
+		recordScore(dir, {
+			repo_root: "/repo/a",
+			metric: "cache",
+			value: 42,
+			meta: { hits: 7, lookups: 10 },
+		});
+		const rows = leaderboard(dir, "cache", { repoRoot: "/repo/a" });
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].repo_root, "/repo/a");
+		assert.equal(rows[0].value, 42);
+		assert.deepEqual(rows[0].meta, { hits: 7, lookups: 10 });
+	});
+
+	it("cache leaderboard ranks by latest value per repo, descending", () => {
+		recordScore(dir, { repo_root: "/repo/a", metric: "cache", value: 10 });
+		recordScore(dir, { repo_root: "/repo/a", metric: "cache", value: 99 }); // latest wins
+		recordScore(dir, { repo_root: "/repo/b", metric: "cache", value: 50 });
+		recordScore(dir, { repo_root: "/repo/c", metric: "cache", value: 75 });
+		const rows = leaderboard(dir, "cache"); // all repos, default limit 10
+		assert.equal(rows.length, 3);
+		assert.deepEqual(
+			rows.map((r) => [r.repo_root, r.value]),
+			[["/repo/a", 99], ["/repo/c", 75], ["/repo/b", 50]],
+		);
+		const a = rows.find((r) => r.repo_root === "/repo/a")!;
+		assert.equal(a.value, 99); // not the older 10
+	});
+
+	it("turns leaderboard uses the latest value per repo", () => {
+		recordScore(dir, { repo_root: "/repo/a", metric: "turns", value: 3 });
+		recordScore(dir, { repo_root: "/repo/a", metric: "turns", value: 8 });
+		const rows = leaderboard(dir, "turns", { repoRoot: "/repo/a" });
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].value, 8);
+	});
+
+	it("dedupe leaderboard sums collapses per repo, descending", () => {
+		recordScore(dir, { repo_root: "/repo/a", metric: "dedupe", value: 2 });
+		recordScore(dir, { repo_root: "/repo/a", metric: "dedupe", value: 3 });
+		recordScore(dir, { repo_root: "/repo/b", metric: "dedupe", value: 10 });
+		const rows = leaderboard(dir, "dedupe");
+		assert.equal(rows.length, 2);
+		assert.deepEqual(
+			rows.map((r) => [r.repo_root, r.value]),
+			[["/repo/b", 10], ["/repo/a", 5]],
+		);
+	});
+
+	it("mega_cache leaderboard returns the max trophy per repo", () => {
+		recordScore(dir, {
+			repo_root: "/repo/a",
+			metric: "mega_cache",
+			value: 120,
+			meta: { peakPct: 120 },
+		});
+		recordScore(dir, {
+			repo_root: "/repo/a",
+			metric: "mega_cache",
+			value: 150,
+			meta: { peakPct: 150 },
+		});
+		const rows = leaderboard(dir, "mega_cache", { repoRoot: "/repo/a" });
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].value, 150);
+		assert.deepEqual(rows[0].meta, { peakPct: 150 });
+	});
+
+	it("repos leaderboard is the derived COUNT(DISTINCT repo_root)", () => {
+		recordScore(dir, { repo_root: "/repo/a", metric: "cache", value: 1 });
+		recordScore(dir, { repo_root: "/repo/b", metric: "cache", value: 1 });
+		recordScore(dir, { repo_root: "/repo/c", metric: "cache", value: 1 });
+		const rows = leaderboard(dir, "repos");
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].value, 3);
+	});
+
+	it("parameterizes repo_root (no SQL injection via repo path)", () => {
+		const evil = "x'); DROP TABLE game_scores; --";
+		recordScore(dir, { repo_root: evil, metric: "cache", value: 5 });
+		const rows = leaderboard(dir, "cache", { repoRoot: evil });
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].repo_root, evil);
+		// the table is intact: a normal insert still works
+		recordScore(dir, { repo_root: "/repo/z", metric: "cache", value: 1 });
+		assert.equal(leaderboard(dir, "cache", { repoRoot: "/repo/z" }).length, 1);
+	});
+
+	it("rejects an unknown metric", () => {
+		const bad = "bogus" as unknown as GameMetric;
+		assert.throws(() =>
+			recordScore(dir, { repo_root: "/r", metric: bad, value: 1 }),
+		);
+		assert.throws(() => leaderboard(dir, bad));
+	});
+
+	it("METRICS allow-list matches the schema CHECK set", () => {
+		assert.deepEqual(
+			[...METRICS].sort(),
+			["cache", "dedupe", "mega_cache", "repos", "turns"],
+		);
+	});
+});

package/src/store/sqlite/game-scores.ts

@@ -0,0 +1,168 @@
+/**
+ * game-scores.ts — `game_scores` table accessors (S33).
+ *
+ * Per-repo leaderboard metrics for game mode. One row per recorded event
+ * (turn_end / session_compact); leaderboard() derives rankings (latest / max /
+ * SUM / COUNT DISTINCT) per repo_root. 'repos' is derived (never recorded).
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (? placeholders, no string concat of user
+ *   data). The metric is validated against a fixed allow-list before use; the
+ *   only interpolated fragments are code-controlled constants (the aggregate
+ *   selector + the optional repo_root filter clause), never external input.
+ * Pi-agnostic: no pi runtime types (mirrors game-state.ts / meta.ts).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+import type { SQLInputValue } from "node:sqlite";
+import { GameMetric, METRICS } from "../../game/scoring.js";
+
+// Process-local monotonic sequence appended into the low 3 digits of `ts` so
+// back-to-back inserts within the same millisecond get distinct PK values
+// (Date.now()*1000 + seq%1000). Production turns are >1ms apart, so seq is
+// almost always 0; this only disambiguates the burst case. Without it,
+// OR REPLACE would drop the earlier same-ms row and break the dedupe SUM.
+let scoreSeq = 0;
+function nextTs(): number {
+	return Date.now() * 1000 + (scoreSeq++ % 1000);
+}
+
+export type { GameMetric } from "../../game/scoring.js";
+export { METRICS } from "../../game/scoring.js";
+
+/** A single recorded game-score event (as stored). */
+export interface ScoreRow {
+	repo_root: string;
+	metric: GameMetric;
+	ts: number;
+	value: number;
+	meta?: unknown;
+}
+
+/** A leaderboard row returned by leaderboard(). */
+export interface LeaderboardRow {
+	repo_root: string;
+	value: number;
+	ts: number;
+	meta: unknown;
+}
+
+/** Options for leaderboard(): optional repo filter + result limit. */
+export interface LeaderboardOpts {
+	repoRoot?: string;
+	limit?: number;
+}
+
+/**
+ * Record one game-score event. `ts` is set to Date.now() by the store. SQL is
+ * fully parameterized (PREVENT-002); the metric is validated against the fixed
+ * allow-list. Pi-agnostic. Never throws except on a genuinely unknown metric.
+ */
+export function recordScore(
+	stateDir: string = getStateDir(),
+	args: { repo_root: string; metric: GameMetric; value: number; meta?: unknown },
+): void {
+	if (!METRICS.includes(args.metric)) {
+		throw new Error(`recordScore: unknown game metric ${String(args.metric)}`);
+	}
+	const db = openStore(stateDir);
+	db.prepare(
+		`INSERT INTO game_scores (repo_root, metric, ts, value, meta)
+		 VALUES (?, ?, ?, ?, ?)`,
+	).run(
+		args.repo_root,
+		args.metric,
+		nextTs(),
+		args.value,
+		args.meta != null ? JSON.stringify(args.meta) : null,
+	);
+}
+
+/**
+ * Read the leaderboard for a metric:
+ *   - cache/turns: latest value per repo_root, sorted desc by value.
+ *   - mega_cache: the max value (trophy) per repo_root, sorted desc.
+ *   - dedupe: SUM(value) per repo_root (cumulative collapses), sorted desc.
+ *   - repos: COUNT(DISTINCT repo_root) — derived; returns a single synthesized
+ *     row (repo_root '*') with the distinct-repo count as `value`.
+ * The metric is validated against the allow-list. Pi-agnostic.
+ */
+export function leaderboard(
+	stateDir: string = getStateDir(),
+	metric: GameMetric,
+	opts: LeaderboardOpts = {},
+): LeaderboardRow[] {
+	if (!METRICS.includes(metric)) {
+		throw new Error(`leaderboard: unknown game metric ${String(metric)}`);
+	}
+	const db = openStore(stateDir);
+	const limit = Math.max(1, opts.limit ?? 10);
+	// Code-controlled filter clauses (never external input) — safe under PREVENT-002.
+	// Two variants: the dedupe query is single-table (unqualified repo_root);
+	// the cache/turns/mega_cache query self-JOINs (must qualify as g.repo_root).
+	const repoFilterDedupe = opts.repoRoot != null ? " AND repo_root = ?" : "";
+	const repoFilter = opts.repoRoot != null ? " AND g.repo_root = ?" : "";
+	const repoParam: SQLInputValue[] = opts.repoRoot != null ? [opts.repoRoot] : [];
+
+	if (metric === "repos") {
+		const row = db
+			.prepare(`SELECT COUNT(DISTINCT repo_root) AS value FROM game_scores`)
+			.get() as { value: number };
+		return [{ repo_root: "*", value: row.value, ts: 0, meta: null }];
+	}
+
+	if (metric === "dedupe") {
+		const sql = `SELECT repo_root, SUM(value) AS value, MAX(ts) AS ts, NULL AS meta
+					 FROM game_scores
+					 WHERE metric = ?${repoFilterDedupe}
+					 GROUP BY repo_root
+					 ORDER BY value DESC
+					 LIMIT ?`;
+		const rows = db.prepare(sql).all(metric, ...repoParam, limit) as Array<{
+			repo_root: string;
+			value: number;
+			ts: number;
+			meta: string | null;
+		}>;
+		return rows.map(toLeaderboardRow);
+	}
+
+	// cache / turns / mega_cache: pick the qualifying row per repo_root (latest
+	// ts, or max value for mega_cache), then rank by value desc. The interpolated
+	// `key`/`col` fragments are derived from the validated metric — code constants,
+	// not user data (PREVENT-002 safe).
+	const key = metric === "mega_cache" ? "MAX(value)" : "MAX(ts)";
+	const col = metric === "mega_cache" ? "value" : "ts";
+	const sql = `SELECT g.repo_root, g.value AS value, g.ts AS ts, g.meta AS meta
+					 FROM game_scores g
+					 JOIN (SELECT repo_root, ${key} AS k
+							 FROM game_scores WHERE metric = ? GROUP BY repo_root) m
+						ON m.repo_root = g.repo_root AND m.k = g.${col}
+					 WHERE g.metric = ?${repoFilter}
+					 ORDER BY g.value DESC
+					 LIMIT ?`;
+	const rows = db
+		.prepare(sql)
+		.all(metric, metric, ...repoParam, limit) as Array<{
+		repo_root: string;
+		value: number;
+		ts: number;
+		meta: string | null;
+	}>;
+	return rows.map(toLeaderboardRow);
+}
+
+/** Helper: coerce a raw row (meta as JSON text) into a LeaderboardRow. */
+function toLeaderboardRow(r: {
+	repo_root: string;
+	value: number;
+	ts: number;
+	meta: string | null;
+}): LeaderboardRow {
+	return {
+		repo_root: r.repo_root,
+		value: r.value,
+		ts: r.ts,
+		meta: r.meta != null ? JSON.parse(r.meta) : null,
+	};
+}

package/src/store/sqlite/game-state.test.ts

@@ -0,0 +1,89 @@
+/**
+ * game-state.test.ts — S30 game_state table round-trip + validation.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import {
+  getGameState,
+  setGameState,
+  DEFAULT_GAME_STATE,
+} from "./game-state.js";
+
+describe("game-state (S30)", () => {
+  let dir: string;
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), "mc-gamestate-"));
+    process.env.MEGACOMPACT_STATE_DIR = dir;
+  });
+  after(() => {
+    closeStore(dir);
+    delete process.env.MEGACOMPACT_STATE_DIR;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns DEFAULT_GAME_STATE on a fresh store", () => {
+    const s = getGameState();
+    assert.deepEqual(s, { ...DEFAULT_GAME_STATE });
+    assert.equal(s.game_mode_on, false);
+    assert.equal(s.theme, "transparent");
+    assert.equal(s.tui_display_mode, "full");
+  });
+
+  it("round-trips game_mode_on", () => {
+    setGameState({ game_mode_on: true });
+    assert.equal(getGameState().game_mode_on, true);
+    setGameState({ game_mode_on: false });
+    assert.equal(getGameState().game_mode_on, false);
+  });
+
+  it("round-trips a valid theme", () => {
+    setGameState({ theme: "retro" });
+    assert.equal(getGameState().theme, "retro");
+    setGameState({ theme: "cyan-neon" });
+    assert.equal(getGameState().theme, "cyan-neon");
+  });
+
+  it("rejects an unknown theme (keeps previous)", () => {
+    setGameState({ theme: "orange-bold" });
+    setGameState({ theme: "does-not-exist" as string });
+    assert.equal(getGameState().theme, "orange-bold");
+  });
+
+  it("round-trips tui_display_mode full|minimal", () => {
+    setGameState({ tui_display_mode: "minimal" });
+    assert.equal(getGameState().tui_display_mode, "minimal");
+    setGameState({ tui_display_mode: "full" });
+    assert.equal(getGameState().tui_display_mode, "full");
+  });
+
+  it("persists across a reopen (survives restart)", () => {
+    setGameState({ game_mode_on: true, theme: "amber-mono", tui_display_mode: "minimal" });
+    // evict + reopen the store to prove it hit disk
+    closeStore(dir);
+    const s = getGameState();
+    assert.equal(s.game_mode_on, true);
+    assert.equal(s.theme, "amber-mono");
+    assert.equal(s.tui_display_mode, "minimal");
+  });
+
+  it("setGameState is a partial merge (untouched fields preserved)", () => {
+    setGameState({ game_mode_on: true, theme: "grayscale", tui_display_mode: "minimal" });
+    const s = setGameState({ game_mode_on: false });
+    assert.equal(s.game_mode_on, false);
+    assert.equal(s.theme, "grayscale");
+    assert.equal(s.tui_display_mode, "minimal");
+  });
+
+  it("stays a single row (no duplicate id=1)", () => {
+    setGameState({ game_mode_on: true });
+    setGameState({ game_mode_on: false });
+    setGameState({ theme: "retro" });
+    const s = getGameState();
+    assert.ok(s); // single state, last-write-wins
+  });
+});

package/src/store/sqlite/game-state.ts

@@ -0,0 +1,87 @@
+/**
+ * game-state.ts — `game_state` table: the global game-mode toggle state (S30).
+ *
+ * Single row (id=1) holding: game_mode_on (bool), theme (one of THEME_IDS),
+ * tui_display_mode ('full'|'minimal'). Global — one choice across all repos.
+ * Survives restarts; editable from /mega-game (TUI) or the dashboard panel
+ * (S32), both reading/writing this same row so they stay in sync.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (@param / ? placeholders, no concat).
+ * Pi-agnostic: no pi runtime types (mirrors meta.ts / session-state.ts).
+ */
+import { DatabaseSync } from "node:sqlite";
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+import { DEFAULT_THEME, isValidTheme } from "../../config/themes.js";
+
+/** The persisted game-mode state. `theme` is always a valid THEME_IDS member
+ *  (callers may assume the invariant; setGameState validates). */
+export interface GameState {
+  game_mode_on: boolean;
+  theme: string;
+  tui_display_mode: "full" | "minimal";
+}
+
+export const DEFAULT_GAME_STATE: GameState = {
+  game_mode_on: false,
+  theme: DEFAULT_THEME,
+  tui_display_mode: "full",
+};
+
+/** Read the global game-mode state. Returns DEFAULT_GAME_STATE if the row is
+ *  absent (fresh install) or any column is unexpectedly null/invalid — never
+ *  throws, so the widget / command can call it on every render safely. */
+export function getGameState(stateDir: string = getStateDir()): GameState {
+  const db = openStore(stateDir);
+  return getGameStateRow(db);
+}
+
+/** Read the game state from an already-open connection (used by callers that
+ *  hold a db handle, e.g. within a transaction). Same defensive fallback. */
+export function getGameStateRow(db: DatabaseSync): GameState {
+  const row = db.prepare(
+    "SELECT game_mode_on, theme, tui_display_mode FROM game_state WHERE id = 1",
+  ).get() as { game_mode_on: number; theme: string; tui_display_mode: string } | undefined;
+  if (!row) return { ...DEFAULT_GAME_STATE };
+  const mode: "full" | "minimal" =
+    row.tui_display_mode === "minimal" ? "minimal" : "full";
+  return {
+    game_mode_on: row.game_mode_on === 1,
+    theme: isValidTheme(row.theme) ? row.theme : DEFAULT_THEME,
+    tui_display_mode: mode,
+  };
+}
+
+/** A partial update to the game state (omit fields you don't want to change). */
+export type GameStatePatch = Partial<GameState>;
+
+/** Upsert the game state row, applying `patch` on top of the current values.
+ *  Validates `theme` (keeps previous on an unknown id) and `tui_display_mode`
+ *  (coerces to 'full' on anything but 'minimal'). Parameterized (PREVENT-002).
+ *  Returns the post-write state. */
+export function setGameState(patch: GameStatePatch, stateDir: string = getStateDir()): GameState {
+  const db = openStore(stateDir);
+  return setGameStateRow(db, patch);
+}
+
+/** Upsert on an already-open connection (for transactional callers). */
+export function setGameStateRow(db: DatabaseSync, patch: GameStatePatch): GameState {
+  const cur = getGameStateRow(db);
+  const next: GameState = {
+    game_mode_on: patch.game_mode_on ?? cur.game_mode_on,
+    theme: patch.theme != null && isValidTheme(patch.theme) ? patch.theme : cur.theme,
+    tui_display_mode: patch.tui_display_mode ?? cur.tui_display_mode,
+  };
+  // Single-row upsert (id=1). INSERT ... ON CONFLICT(id) DO UPDATE keeps it
+  // one row whether the table is fresh or already seeded.
+  db.prepare(
+    `INSERT INTO game_state (id, game_mode_on, theme, tui_display_mode)
+     VALUES (1, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       game_mode_on = excluded.game_mode_on,
+       theme = excluded.theme,
+       tui_display_mode = excluded.tui_display_mode`,
+  ).run(next.game_mode_on ? 1 : 0, next.theme, next.tui_display_mode);
+  return next;
+}