chesspal 0.0.1 → 0.1.0

package/dist/core/review.d.ts

@@ -0,0 +1,74 @@
+import { type GameRecord, type RecordedMove } from "./record.ts";
+/** The badges of a move, as chess.com has them, from the best to the worst. */
+export declare const badges: readonly ["brilliant", "great", "best", "excellent", "good", "book", "inaccuracy", "mistake", "miss", "blunder"];
+/** A move's badge. */
+export type Badge = (typeof badges)[number];
+/** The colours the AI draws with on the board, by the letters PGN's [%cal] and [%csl] write them with. */
+export declare const drawColours: {
+    readonly G: "green";
+    readonly R: "red";
+    readonly Y: "yellow";
+    readonly B: "blue";
+};
+/** A colour the AI draws with. */
+export type DrawColour = (typeof drawColours)[keyof typeof drawColours];
+/** An arrow the AI draws to show its note: from a square to another, in a colour. */
+export interface DrawnArrow {
+    readonly colour: DrawColour;
+    readonly from: string;
+    readonly to: string;
+}
+/** A square the AI colours to show its note. */
+export interface DrawnSquare {
+    readonly colour: DrawColour;
+    readonly square: string;
+}
+/** The AI's word on a move: its badge, its note, or both, and the arrows and squares it draws to show it. */
+export interface MoveReview {
+    readonly badge?: Badge;
+    readonly note?: string;
+    readonly arrows?: readonly DrawnArrow[];
+    readonly squares?: readonly DrawnSquare[];
+}
+/** The review a move's comment carries: a badge, a note or both, with the arrows and squares drawn to show it; none without a badge or a note. */
+export declare function reviewOf(comment: string | undefined): MoveReview | undefined;
+/** The arrows and squares a move's comment carries, as the AI draws them with its move when the helps are on (D-78); none without any. */
+export declare function drawingsIn(comment: string | undefined): Pick<MoveReview, "arrows" | "squares">;
+/** An arrow as PGN's [%cal] writes it, a colour's letter and two squares (Gf6e4); none when it is not one. */
+export declare function arrowOf(text: string): DrawnArrow | undefined;
+/** A square as PGN's [%csl] writes it, a colour's letter and the square (Rf2); none when it is not one. */
+export declare function squareOf(text: string): DrawnSquare | undefined;
+/** What the AI wrote about the whole game, when it wrote something; its points start with " • ". */
+export declare function gameReviewOf(record: GameRecord): string | undefined;
+/** The AI's last word on how the game ended, when it wrote one. */
+export declare function closingOf(record: GameRecord): string | undefined;
+/** The move with the AI's review in place of the one it had: the NAG of its badge, and its badge and note in the comment, beside what the comment held. */
+export declare function reviewed(move: RecordedMove, review: MoveReview): RecordedMove;
+/** The arrows and squares as PGN's [%cal] and [%csl] write them, for a comment; empty without any. */
+export declare function drawingsText({ arrows, squares }: Pick<MoveReview, "arrows" | "squares">): string;
+/** The record with who reviewed it (D-81): the model, else the host, as PGN's Annotator, and the effort only when known; an effort no longer known goes. */
+export declare function withAnnotator(record: GameRecord, { annotator, effort }: {
+    annotator: string;
+    effort?: string;
+}): GameRecord;
+/** The AI's model, as the host writes it, and its effort when the host gives it (D-82). */
+export interface AiModel {
+    readonly model: string;
+    readonly effort?: string;
+}
+/** The record with the model the AI played it with (D-82), and the effort only when known; with none known, as it is. */
+export declare function withAiModel(record: GameRecord, played: AiModel | undefined): GameRecord;
+/** Who reviewed the game, as its tags say: the Annotator, and the effort when known; undefined without an Annotator. */
+export declare function annotatorOf(record: GameRecord): {
+    annotator: string;
+    effort?: string;
+} | undefined;
+/** The model the AI played the game with, as its tags say (D-82), and the effort when known; undefined without one. */
+export declare function aiModelIn(record: GameRecord): AiModel | undefined;
+/** The record with the AI's word on the whole game, or its last word on the ending, in place of the one it had: each only when given. */
+export declare function withGameReview(record: GameRecord, { summary, closing }: {
+    summary?: string;
+    closing?: string;
+}): GameRecord;
+/** Whether a word is one of the badges. */
+export declare function isBadge(word: string | undefined): word is Badge;

package/dist/core/review.js

@@ -0,0 +1,126 @@
+// The AI's review of a game (D-69): a badge and a note on the moves that matter, as chess.com marks them, and its word on the whole game. They ride in the
+// comments as [%badge …] and [%review …], beside the NAG of the badges that have one, which other programs show.
+import { recordedMove } from "./record.js";
+/** The badges of a move, as chess.com has them, from the best to the worst. */
+export const badges = ["brilliant", "great", "best", "excellent", "good", "book", "inaccuracy", "mistake", "miss", "blunder"];
+/** The colours the AI draws with on the board, by the letters PGN's [%cal] and [%csl] write them with. */
+export const drawColours = { G: "green", R: "red", Y: "yellow", B: "blue" };
+/** The review a move's comment carries: a badge, a note or both, with the arrows and squares drawn to show it; none without a badge or a note. */
+export function reviewOf(comment) {
+    const found = badgePattern.exec(comment ?? "")?.[1];
+    const badge = isBadge(found) ? found : undefined;
+    const note = notePattern.exec(comment ?? "")?.[1]?.trim() || undefined;
+    return badge === undefined && note === undefined ? undefined : { ...(badge === undefined ? {} : { badge }), ...(note === undefined ? {} : { note }), ...drawingsIn(comment) };
+}
+/** The arrows and squares a move's comment carries, as the AI draws them with its move when the helps are on (D-78); none without any. */
+export function drawingsIn(comment) {
+    const arrows = drawn(arrowPattern, comment, arrowOf);
+    const squares = drawn(squarePattern, comment, squareOf);
+    return { ...(arrows.length === 0 ? {} : { arrows }), ...(squares.length === 0 ? {} : { squares }) };
+}
+/** An arrow as PGN's [%cal] writes it, a colour's letter and two squares (Gf6e4); none when it is not one. */
+export function arrowOf(text) {
+    const [, colour, from, to] = /^([GRYB])([a-h][1-8])([a-h][1-8])$/.exec(text.trim()) ?? [];
+    return colour === undefined || from === undefined || to === undefined || from === to ? undefined : { colour: drawColours[colour], from, to };
+}
+/** A square as PGN's [%csl] writes it, a colour's letter and the square (Rf2); none when it is not one. */
+export function squareOf(text) {
+    const [, colour, square] = /^([GRYB])([a-h][1-8])$/.exec(text.trim()) ?? [];
+    return colour === undefined || square === undefined ? undefined : { colour: drawColours[colour], square };
+}
+/** What the AI wrote about the whole game, when it wrote something; its points start with " • ". */
+export function gameReviewOf(record) {
+    return notePattern.exec(record.comment ?? "")?.[1]?.trim() || undefined;
+}
+/** The AI's last word on how the game ended, when it wrote one. */
+export function closingOf(record) {
+    return closingPattern.exec(record.comment ?? "")?.[1]?.trim() || undefined;
+}
+/** The move with the AI's review in place of the one it had: the NAG of its badge, and its badge and note in the comment, beside what the comment held. */
+export function reviewed(move, review) {
+    const nag = review.badge === undefined ? undefined : nagOfBadge[review.badge];
+    const nags = (move.nags ?? []).filter((one) => !judgmentNags.has(one));
+    const note = review.note === undefined ? "" : noteText(review.note);
+    const comment = [
+        withoutReview(move.comment),
+        review.badge === undefined ? "" : `[%badge ${review.badge}]`,
+        note === "" ? "" : `[%review ${note}]`,
+        drawingsText(review),
+    ].filter((part) => part !== "").join(" ");
+    return recordedMove(move.san, nag === undefined ? nags : [nag, ...nags], comment);
+}
+/** The arrows and squares as PGN's [%cal] and [%csl] write them, for a comment; empty without any. */
+export function drawingsText({ arrows = [], squares = [] }) {
+    const arrowList = arrows.map(({ colour, from, to }) => `${letterOf(colour)}${from}${to}`).join(",");
+    const squareList = squares.map(({ colour, square }) => `${letterOf(colour)}${square}`).join(",");
+    return [arrowList === "" ? "" : `[%cal ${arrowList}]`, squareList === "" ? "" : `[%csl ${squareList}]`].filter((part) => part !== "").join(" ");
+}
+/** The record with who reviewed it (D-81): the model, else the host, as PGN's Annotator, and the effort only when known; an effort no longer known goes. */
+export function withAnnotator(record, { annotator, effort }) {
+    return { ...record, tags: signed(record.tags, ["Annotator", effortTag], annotator, effort) };
+}
+/** The record with the model the AI played it with (D-82), and the effort only when known; with none known, as it is. */
+export function withAiModel(record, played) {
+    return played === undefined ? record : { ...record, tags: signed(record.tags, ["AIModel", "AIEffort"], played.model, played.effort) };
+}
+/** Who reviewed the game, as its tags say: the Annotator, and the effort when known; undefined without an Annotator. */
+export function annotatorOf(record) {
+    const found = signerOf(record.tags, ["Annotator", effortTag]);
+    return found === undefined ? undefined : { annotator: found.model, ...(found.effort === undefined ? {} : { effort: found.effort }) };
+}
+/** The model the AI played the game with, as its tags say (D-82), and the effort when known; undefined without one. */
+export function aiModelIn(record) {
+    return signerOf(record.tags, ["AIModel", "AIEffort"]);
+}
+// The effort has no tag of its own in PGN: Chesspal's sits beside the Annotator.
+const effortTag = "AnnotatorEffort";
+/** A model and its effort as the tags say, each only when not blank; undefined without the model. */
+function signerOf(tags, [modelTag, modelEffortTag]) {
+    const model = tags[modelTag]?.trim();
+    const effort = tags[modelEffortTag]?.trim();
+    if (model === undefined || model === "") {
+        return undefined;
+    }
+    return effort === undefined || effort === "" ? { model } : { model, effort };
+}
+/** The tags with a model and its effort, last: an effort no longer known goes. */
+function signed(tags, [modelTag, modelEffortTag], model, effort) {
+    const others = Object.entries(tags).filter(([name]) => name !== modelTag && name !== modelEffortTag);
+    return { ...Object.fromEntries(others), [modelTag]: model, ...(effort === undefined ? {} : { [modelEffortTag]: effort }) };
+}
+/** The record with the AI's word on the whole game, or its last word on the ending, in place of the one it had: each only when given. */
+export function withGameReview(record, { summary, closing }) {
+    const summed = summary === undefined ? gameReviewOf(record) : noteText(summary);
+    const closed = closing === undefined ? closingOf(record) : noteText(closing);
+    const comment = [withoutReview(record.comment), summed ? `[%review ${summed}]` : "", closed ? `[%closing ${closed}]` : ""].filter((part) => part !== "").join(" ");
+    return comment === "" ? { tags: record.tags, moves: record.moves } : { tags: record.tags, comment, moves: record.moves };
+}
+/** Whether a word is one of the badges. */
+export function isBadge(word) {
+    return badges.includes(word ?? "");
+}
+// The NAGs that judge a move ($1 to $6): a new badge takes their place.
+const judgmentNags = new Set([1, 2, 3, 4, 5, 6]);
+// The badges PGN has a NAG for: !! ! ?! ? ??.
+const nagOfBadge = { brilliant: 3, great: 1, inaccuracy: 6, mistake: 2, blunder: 4 };
+const badgePattern = /\[%badge (\w+)\]/;
+const notePattern = /\[%review ([^\]]*)\]/;
+const closingPattern = /\[%closing ([^\]]*)\]/;
+const arrowPattern = /\[%cal ([^\]]*)\]/;
+const squarePattern = /\[%csl ([^\]]*)\]/;
+/** A comment without the review it carried, its drawings with it. */
+function withoutReview(comment) {
+    return (comment ?? "").replace(/\s*\[%(badge|review|closing|cal|csl) [^\]]*\]/g, "").trim();
+}
+/** The drawings of one kind a comment carries, those that read. */
+function drawn(pattern, comment, read) {
+    return (pattern.exec(comment ?? "")?.[1] ?? "").split(",").map(read).filter((one) => one !== undefined);
+}
+/** A colour's letter in [%cal] and [%csl]. */
+function letterOf(colour) {
+    return Object.entries(drawColours).find(([, name]) => name === colour)[0];
+}
+/** A note as a comment's command can hold it: on one line, without brackets or braces, a point of a list starting with " • ". */
+function noteText(text) {
+    return text.replace(/[[\]{}]/g, "").replace(/^[ \t]*[-*•][ \t]+/gm, " • ").replace(/\s+/g, " ").trim();
+}

package/dist/games/ai-model.d.ts

@@ -0,0 +1,5 @@
+import type { AiModel } from "../core/index.ts";
+/** Notes the AI's model for the games of a folder, after its move: a change shows from the next move. Whether it changed. */
+export declare function noteAiModel(folder: string, noted: AiModel): boolean;
+/** The AI's model last noted for the games of a folder in this process; none on the command line, or before the AI's first move. */
+export declare function aiModelOf(folder: string): AiModel | undefined;

package/dist/games/ai-model.js

@@ -0,0 +1,15 @@
+/** Notes the AI's model for the games of a folder, after its move: a change shows from the next move. Whether it changed. */
+export function noteAiModel(folder, noted) {
+    const known = models.get(folder);
+    if (known?.model === noted.model && known.effort === noted.effort) {
+        return false;
+    }
+    models.set(folder, noted);
+    return true;
+}
+/** The AI's model last noted for the games of a folder in this process; none on the command line, or before the AI's first move. */
+export function aiModelOf(folder) {
+    return models.get(folder);
+}
+// By the game's folder, the profile's, where the games are archived.
+const models = new Map();

package/dist/games/analysis.d.ts

@@ -0,0 +1,12 @@
+/** The game in analysis: its name as the lists write it, when the analysis last changed it, and whether the player brought it on the page and the AI has not gone over it yet (T-92). */
+export interface Analysis {
+    readonly game: string;
+    readonly at: string;
+    readonly brought?: true;
+}
+/** Names the game in analysis, over the one before; written again each time its review changes, so the page hears of it. */
+export declare function startAnalysis(folder: string, game: string, now: Date, brought?: boolean): void;
+/** The game in analysis, or none when there is none, or analysis.json cannot be read. */
+export declare function gameInAnalysis(folder: string): Analysis | undefined;
+/** Ends the analysis, when a new game starts. */
+export declare function endAnalysis(folder: string): void;

package/dist/games/analysis.js

@@ -0,0 +1,26 @@
+// The game in analysis (D-69): analysis.json, in the folder of the profile's games, names the game analyse_game and annotate_game went over last, for the
+// board page to show it once no game goes on; a new game ends it.
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomically } from "./files.js";
+/** Names the game in analysis, over the one before; written again each time its review changes, so the page hears of it. */
+export function startAnalysis(folder, game, now, brought = false) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify({ game, at: now.toISOString(), ...(brought ? { brought } : {}) }, null, 2)}\n`);
+}
+/** The game in analysis, or none when there is none, or analysis.json cannot be read. */
+export function gameInAnalysis(folder) {
+    try {
+        const analysis = JSON.parse(readFileSync(join(folder, fileName), "utf8"));
+        return typeof analysis.game === "string" && typeof analysis.at === "string"
+            ? { game: analysis.game, at: analysis.at, ...(analysis.brought === true ? { brought: true } : {}) }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ends the analysis, when a new game starts. */
+export function endAnalysis(folder) {
+    rmSync(join(folder, fileName), { force: true });
+}
+const fileName = "analysis.json";

package/dist/games/archive.d.ts

@@ -0,0 +1,42 @@
+import { type GameRecord } from "../core/index.ts";
+import { type CurrentGame } from "./current-game.ts";
+/** Where the game goes in the archive, in the player's folder: named by when it started, in the player's time, games/2026-11-02-153012.pgn. */
+export declare function archiveName(current: CurrentGame): string;
+/**
+ * When a new game starts: now, or the first second after it whose name in the archive is free and is not the game before's, which goes there later. Two
+ * games started in the same second, when summer time ends or with the clock set back would otherwise share a name.
+ */
+export declare function startOfNewGame(folder: string, now: Date, before?: CurrentGame): Date;
+/**
+ * Writes the game to the archive, with the plans, how it ended and the AI's model last noted (D-82), and gives its name; the same game again rewrites the
+ * same file.
+ */
+export declare function archiveGame(folder: string, current: CurrentGame): string;
+/** Archives a game that has ended: its name in the archive or, when that fails, a warning, since the game is saved in game.json all the same. */
+export declare function archiveEnded(folder: string, current: CurrentGame): {
+    archive?: string;
+    warning?: string;
+};
+/** The name of a game over in the archive, when it is there. */
+export declare function archivedName(folder: string, current: CurrentGame): string | undefined;
+/** The names of the games in the archive, the latest first: games/2026-11-02-153012.pgn. */
+export declare function archivedGames(folder: string): string[];
+/** A game of the archive by its name, as listed; refused when it is not there, or cannot be read. */
+export declare function archivedGame(folder: string, name: string): GameRecord;
+/** The names of the games kept to study in a profile's folder, the latest kept first: study/2026-11-04-153012.pgn. */
+export declare function keptGames(root: string): string[];
+/** A game kept to study by its name, as listed; refused when it is not there, or cannot be read. */
+export declare function keptGame(root: string, name: string): GameRecord;
+/** When an archived game started, from its name, in the player's time: 2026-11-02 15:30. */
+export declare function archivedWhen(name: string): string;
+/**
+ * Keeps a game played elsewhere to study (D-68) in a profile's folder, apart from the games played here, and gives its name, by `now`:
+ * study/2026-11-04-153012.pgn; the same game again keeps the name it has.
+ */
+export declare function keepToStudy(root: string, record: GameRecord, now: Date): string;
+/** Writes again a game of a profile, played or kept to study, by its name as listed: with the AI's review (D-69). */
+export declare function rewriteGame(folder: string, name: string, record: GameRecord): void;
+/** The game as PGN for the player: while it goes on, without the AI's plans (D-29). */
+export declare function playerPgn(current: CurrentGame): string;
+/** The game as PGN with its moves alone, without comments or plans, for Lichess or chess.com (T-59). */
+export declare function movesPgn(current: CurrentGame): string;

package/dist/games/archive.js

@@ -0,0 +1,168 @@
+// The finished games, as PGN in games/ (D-9, D-41), with the AI's plans for the analyst (D-21); and the games played elsewhere, kept to study in study/ (D-68).
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { movesOnly, pgnDate, readPgn, withAiModel, writePgn } from "../core/index.js";
+import { aiModelOf } from "./ai-model.js";
+import { endOf } from "./current-game.js";
+import { makeFolder, writeAtomically } from "./files.js";
+import { withoutPlans } from "./plans.js";
+/** Where the game goes in the archive, in the player's folder: named by when it started, in the player's time, games/2026-11-02-153012.pgn. */
+export function archiveName(current) {
+    return nameAt(new Date(current.started));
+}
+/**
+ * When a new game starts: now, or the first second after it whose name in the archive is free and is not the game before's, which goes there later. Two
+ * games started in the same second, when summer time ends or with the clock set back would otherwise share a name.
+ */
+export function startOfNewGame(folder, now, before) {
+    const taken = before === undefined ? undefined : archiveName(before);
+    let start = now;
+    while (nameAt(start) === taken || existsSync(join(folder, nameAt(start)))) {
+        start = new Date(start.getTime() + 1_000);
+    }
+    return start;
+}
+/**
+ * Writes the game to the archive, with the plans, how it ended and the AI's model last noted (D-82), and gives its name; the same game again rewrites the
+ * same file.
+ */
+export function archiveGame(folder, current) {
+    const name = archiveName(current);
+    const path = join(folder, name);
+    try {
+        makeFolder(dirname(path));
+        writeAtomically(path, writePgn(withAiModel(endedRecord(current), aiModelOf(folder))));
+    }
+    catch (error) {
+        throw new Error(`Chesspal could not archive the game: ${error.message}`, { cause: error });
+    }
+    return name;
+}
+/** Archives a game that has ended: its name in the archive or, when that fails, a warning, since the game is saved in game.json all the same. */
+export function archiveEnded(folder, current) {
+    try {
+        return { archive: archiveGame(folder, current) };
+    }
+    catch (error) {
+        return { warning: `${error.message} The game is saved in game.json: it goes to the archive when a new game starts.` };
+    }
+}
+/** The name of a game over in the archive, when it is there. */
+export function archivedName(folder, current) {
+    if (endOf(current.game) === undefined) {
+        return undefined;
+    }
+    const name = archiveName(current);
+    return existsSync(join(folder, name)) ? name : undefined;
+}
+/** The names of the games in the archive, the latest first: games/2026-11-02-153012.pgn. */
+export function archivedGames(folder) {
+    return gameNames(folder, "games");
+}
+/** A game of the archive by its name, as listed; refused when it is not there, or cannot be read. */
+export function archivedGame(folder, name) {
+    return gameNamed(folder, "games", name);
+}
+/** The names of the games kept to study in a profile's folder, the latest kept first: study/2026-11-04-153012.pgn. */
+export function keptGames(root) {
+    return gameNames(root, "study");
+}
+/** A game kept to study by its name, as listed; refused when it is not there, or cannot be read. */
+export function keptGame(root, name) {
+    return gameNamed(root, "study", name);
+}
+/** When an archived game started, from its name, in the player's time: 2026-11-02 15:30. */
+export function archivedWhen(name) {
+    const [, day, hour, minute] = /(\d{4}-\d{2}-\d{2})-(\d{2})(\d{2})/.exec(name) ?? [];
+    return day === undefined ? name : `${day} ${hour}:${minute}`;
+}
+/**
+ * Keeps a game played elsewhere to study (D-68) in a profile's folder, apart from the games played here, and gives its name, by `now`:
+ * study/2026-11-04-153012.pgn; the same game again keeps the name it has.
+ */
+export function keepToStudy(root, record, now) {
+    const text = writePgn(record);
+    // The same game, whatever the review and the book's badges written on it since.
+    const [written] = readPgn(text);
+    const kept = keptGames(root).find((name) => sameGame(readPgn(readFileSync(join(root, name), "utf8"))[0], written));
+    if (kept !== undefined) {
+        return kept;
+    }
+    let name = nameAt(now, "study");
+    for (let second = 1; existsSync(join(root, name)); second++) {
+        name = nameAt(new Date(now.getTime() + second * 1_000), "study");
+    }
+    try {
+        makeFolder(join(root, "study"));
+        writeAtomically(join(root, name), text);
+    }
+    catch (error) {
+        throw new Error(`Chesspal could not keep the game to study: ${error.message}`, { cause: error });
+    }
+    return name;
+}
+/** Writes again a game of a profile, played or kept to study, by its name as listed: with the AI's review (D-69). */
+export function rewriteGame(folder, name, record) {
+    const [, shelf, file] = /^(games|study)\/(.*)$/.exec(name) ?? [];
+    if (shelf === undefined || !namePattern.test(file ?? "") || !existsSync(join(folder, name))) {
+        throw new Error(`There is no ${name} to write again: give a game's name as past_games or study_games writes it.`);
+    }
+    try {
+        writeAtomically(join(folder, name), writePgn(record));
+    }
+    catch (error) {
+        throw new Error(`Chesspal could not write ${name}: ${error.message}`, { cause: error });
+    }
+}
+const shelves = { games: { what: "of the archive", list: "past_games" }, study: { what: "kept to study", list: "study_games" } };
+const namePattern = /^\d{4}-\d{2}-\d{2}-\d{6}\.pgn$/;
+function gameNames(folder, shelf) {
+    try {
+        return readdirSync(join(folder, shelf)).filter((name) => namePattern.test(name)).sort().reverse().map((name) => `${shelf}/${name}`);
+    }
+    catch {
+        return [];
+    }
+}
+function gameNamed(folder, shelf, name) {
+    // The name as listed, or without its folder or its .pgn.
+    const file = `${(name.startsWith(`${shelf}/`) ? name.slice(shelf.length + 1) : name).trim().replace(/\.pgn$/, "")}.pgn`;
+    const { what, list } = shelves[shelf];
+    if (!namePattern.test(file)) {
+        throw new Error(`${name} is no game ${what}: give a name as ${list} writes it, such as ${shelf}/2026-11-02-153012.pgn.`);
+    }
+    let text;
+    try {
+        text = readFileSync(join(folder, shelf, file), "utf8");
+    }
+    catch {
+        throw new Error(`There is no ${name} among the games ${what}: give a name as ${list} writes it.`);
+    }
+    const [record] = readPgn(text);
+    if (record === undefined) {
+        throw new Error(`${name} holds no game Chesspal can read.`);
+    }
+    return record;
+}
+/** The game as PGN for the player: while it goes on, without the AI's plans (D-29). */
+export function playerPgn(current) {
+    return writePgn(endOf(current.game) === undefined ? withoutPlans(current.game.record) : endedRecord(current));
+}
+/** The game as PGN with its moves alone, without comments or plans, for Lichess or chess.com (T-59). */
+export function movesPgn(current) {
+    return writePgn(movesOnly(endOf(current.game) === undefined ? current.game.record : endedRecord(current)));
+}
+/** Whether two records are the same game: the same tags and the same moves, whatever their comments say. */
+function sameGame(one, other) {
+    const shape = (record) => JSON.stringify([record?.tags, record?.moves.map((move) => move.san)]);
+    return one !== undefined && shape(one) === shape(other);
+}
+function nameAt(date, shelf = "games") {
+    const time = date.toTimeString().slice(0, 8).replaceAll(":", "");
+    return `${shelf}/${pgnDate(date).replaceAll(".", "-")}-${time}.pgn`;
+}
+/** The record with its Termination tag, when the board ended the game and the tag is missing. */
+function endedRecord({ game }) {
+    const { record, outcome } = game;
+    return outcome.over && record.tags.Termination === undefined ? { ...record, tags: { ...record.tags, Termination: outcome.ending } } : record;
+}

package/dist/games/chat-start.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How a chat started, as the host's SessionStart hook says it: new, cleared, resumed or compacted; when, as an ISO date; its session, for the logs; and the
+ * file where the host writes the chat, where Claude Code tells which model made each tool call (D-81).
+ */
+export interface ChatStart {
+    readonly source: string;
+    readonly at: string;
+    readonly session?: string;
+    readonly transcript?: string;
+}
+/** Writes how the chat started, over the last one. */
+export declare function saveChatStart(folder: string, start: ChatStart): void;
+/** How the chat last started, or undefined when no hook wrote it, or what it wrote cannot be read. */
+export declare function lastChatStart(folder: string): ChatStart | undefined;
+/** Whether the chat started clean (new or cleared) after a moment: a resumed or compacted one still holds what came before. */
+export declare function cleanSince(start: ChatStart | undefined, moment: string): boolean;

package/dist/games/chat-start.js

@@ -0,0 +1,26 @@
+// How the player's chat last started (D-57): chat.json, written by the host's hook when a chat starts, is cleared or resumed; a new game asks for a clean one.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomically } from "./files.js";
+/** Writes how the chat started, over the last one. */
+export function saveChatStart(folder, start) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(start, null, 2)}\n`);
+}
+/** How the chat last started, or undefined when no hook wrote it, or what it wrote cannot be read. */
+export function lastChatStart(folder) {
+    try {
+        const start = JSON.parse(readFileSync(join(folder, fileName), "utf8"));
+        if (typeof start.source !== "string" || typeof start.at !== "string") {
+            return undefined;
+        }
+        return { source: start.source, at: start.at, ...(typeof start.transcript === "string" ? { transcript: start.transcript } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the chat started clean (new or cleared) after a moment: a resumed or compacted one still holds what came before. */
+export function cleanSince(start, moment) {
+    return start !== undefined && (start.source === "startup" || start.source === "clear") && Date.parse(start.at) > Date.parse(moment);
+}
+const fileName = "chat.json";

package/dist/games/current-game.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { type Clock, Game, type Side } from "../core/index.ts";
+/** The player's current game, going on or over: the live game, and what game.json keeps beside its PGN. */
+export interface CurrentGame {
+    readonly game: Game;
+    /** The side the AI plays. */
+    readonly ai: Side;
+    /** When the game started, as an ISO date: it names the game in the archive. */
+    readonly started: string;
+    /** What the player and the AI said on the board page, beside the PGN and never in the archive (D-51). */
+    readonly talk: TalkLine[];
+    /** The clock, in a game with a time control (D-13). */
+    readonly clock?: Clock;
+    /** Who offered a draw, while the offer stands: until the other side accepts it, declines it or moves (D-65). */
+    readonly drawOffer?: Speaker;
+}
+/** Who speaks on the board page. */
+export type Speaker = "player" | "ai";
+/** A line said on the board page: who said it, its words, how many moves the game had then, and when, as an ISO date; the AI's agent on the player's time (D-72). */
+export interface TalkLine {
+    readonly who: Speaker;
+    readonly text: string;
+    readonly ply: number;
+    readonly at: string;
+    readonly agent?: true;
+}
+/** How a game ended: its result, and why when the record says it or the board decided it. */
+export interface GameEnd {
+    readonly result: string;
+    readonly termination?: string;
+}
+/** The current game of a folder, as it is on disk, or undefined when there is none. A game.json Chesspal cannot read throws: nothing overwrites it. */
+export declare function loadGame(folder: string): CurrentGame | undefined;
+/** Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. */
+export declare function saveGame(folder: string, current: CurrentGame): void;
+/** How the game ended, or undefined while it goes on: by the board, or by what the record says, such as a resignation. */
+export declare function endOf(game: Game): GameEnd | undefined;
+/** The draw offer that stands: none once the game is over (D-65). */
+export declare function drawOfferOf(current: CurrentGame): Speaker | undefined;
+/** Whether each side has made a move in the game, before which no draw is agreed (FIDE 5.2.3, D-65). */
+export declare function bothSidesMoved(game: Game): boolean;
+/** A stamp of the folder's game.json that changes whenever it is written, whoever writes it; undefined when there is none. */
+export declare function gameStamp(folder: string): string | undefined;
+/** A line of the talk as game.json and talk.json keep it. */
+export declare const savedLine: z.ZodObject<{
+    who: z.ZodEnum<{
+        player: "player";
+        ai: "ai";
+    }>;
+    text: z.ZodString;
+    ply: z.ZodInt;
+    at: z.ZodISODateTime;
+    agent: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;