chesspal 0.0.1 → 0.2.0

package/dist/core/review.d.ts

@@ -0,0 +1,80 @@
+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. */
+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;
+/** Whether the analyst has reviewed a game: its word on the whole game or on how it ended. The badges given during the game with the helps on are not a review (D-78). */
+export declare function isReviewed(record: GameRecord): boolean;
+/** 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 record without the AI's review (D-92): the badges with the NAGs they wrote, the notes, drawings and estimates of who is ahead on the moves, the word on
+ * the game and who signed it. What the comments held besides stays, as do the NAGs of moves without a badge and the Annotator of a game it never reviewed.
+ */
+export declare function unreviewed(record: GameRecord): GameRecord;
+/** 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;
+export {};

package/dist/core/review.js

@@ -0,0 +1,146 @@
+// 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. */
+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;
+}
+/** Whether the analyst has reviewed a game: its word on the whole game or on how it ended. The badges given during the game with the helps on are not a review (D-78). */
+export function isReviewed(record) {
+    return gameReviewOf(record) !== undefined || closingOf(record) !== 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 record without the AI's review (D-92): the badges with the NAGs they wrote, the notes, drawings and estimates of who is ahead on the moves, the word on
+ * the game and who signed it. What the comments held besides stays, as do the NAGs of moves without a badge and the Annotator of a game it never reviewed.
+ */
+export function unreviewed(record) {
+    const moves = record.moves.map((move) => {
+        const nags = badgePattern.test(move.comment ?? "") ? (move.nags ?? []).filter((nag) => !judgmentNags.has(nag)) : move.nags;
+        return recordedMove(move.san, nags, withoutReview(move.comment).replace(/\s*\[%lead [^\]]*\]/g, "").trim());
+    });
+    const comment = withoutReview(record.comment);
+    // The signature is the AI's only on a game it reviewed: a game from elsewhere keeps its own Annotator.
+    const signedByAi = isReviewed(record) || record.moves.some((move) => reviewMark.test(move.comment ?? ""));
+    const tags = signedByAi ? Object.fromEntries(Object.entries(record.tags).filter(([name]) => name !== "Annotator" && name !== effortTag)) : record.tags;
+    return comment === "" ? { tags, moves } : { tags, comment, moves };
+}
+/** 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 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 };
+}
+// 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 }) };
+}
+/** Whether a word is one of the badges. */
+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 reviewMark = /\[%(badge|review) /;
+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. */
+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,63 @@
+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;
+/** Whether the game over still in game.json is this one of the archive, named as listed; a game.json Chesspal cannot read is no game. */
+export declare function isOverOnTable(folder: string, name: string): boolean;
+/**
+ * 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;
+};
+/**
+ * Writes the coach's judgments into a game over already in the archive, beside what the analyst may have written there since (Federico);
+ * archives the game when it is not there.
+ */
+export declare function archiveCoached(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;
+/** Deletes a game of a profile, played or kept to study, by its name as listed (D-92), its review with it. */
+export declare function deleteGame(folder: string, name: string): void;
+/** The time a game's name holds, 2026-11-02-153012, wherever it is in the text; undefined when there is none. */
+export declare function gameStemOf(name: string): string | undefined;
+/** Whether a text is a game's name as the lists write it, games/2026-11-02-153012.pgn, with or without its folder. */
+export declare function isGameName(text: string): boolean;
+/**
+ * A game's name as the lists write it, from a name without its folder or its .pgn too: 2026-11-04-173054 is games/2026-11-04-173054.pgn, or the game kept
+ * to study by that name when no game played has it; any other name as it is, for the archive to refuse.
+ */
+export declare function listedName(folder: string, name: string): string;
+/** The game as PGN for the player: while it goes on, without the AI's plans (D-29); once over, with the coach's judgments too (D-88). */
+export declare function playerPgn(folder: string, current: CurrentGame): string;
+/** The game as PGN with its moves alone, without comments or plans, for Lichess or chess.com. */
+export declare function movesPgn(current: CurrentGame): string;

package/dist/games/archive.js

@@ -0,0 +1,242 @@
+// 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, rmSync } 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 { coachWords, withCoach } from "./coach.js";
+import { endOf, loadGame } 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));
+}
+/** Whether the game over still in game.json is this one of the archive, named as listed; a game.json Chesspal cannot read is no game. */
+export function isOverOnTable(folder, name) {
+    try {
+        const current = loadGame(folder);
+        return current !== undefined && endOf(current.game) !== undefined && archiveName(current) === name;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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(folder, 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.` };
+    }
+}
+/**
+ * Writes the coach's judgments into a game over already in the archive, beside what the analyst may have written there since (Federico);
+ * archives the game when it is not there.
+ */
+export function archiveCoached(folder, current) {
+    const name = archivedName(folder, current);
+    if (name === undefined) {
+        return archiveEnded(folder, current);
+    }
+    try {
+        writeAtomically(join(folder, name), writePgn(withCoach(archivedGame(folder, name), coachWords(folder, current))));
+        return { archive: name };
+    }
+    catch (error) {
+        return { warning: `Chesspal could not write the coach's words into ${name}: ${error.message}` };
+    }
+}
+/** 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 stem = gameStemOf(name);
+    return stem === undefined ? name : `${stem.slice(0, 10)} ${stem.slice(11, 13)}:${stem.slice(13, 15)}`;
+}
+/**
+ * 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 path = listedPath(folder, name, "to write again");
+    try {
+        writeAtomically(path, writePgn(record));
+    }
+    catch (error) {
+        throw new Error(`Chesspal could not write ${name}: ${error.message}`, { cause: error });
+    }
+}
+/** Deletes a game of a profile, played or kept to study, by its name as listed (D-92), its review with it. */
+export function deleteGame(folder, name) {
+    const path = listedPath(folder, name, "to delete");
+    try {
+        rmSync(path);
+    }
+    catch (error) {
+        throw new Error(`Chesspal could not delete ${name}: ${error.message}`, { cause: error });
+    }
+}
+/** The file of a game by its name as listed, games/… or study/…; refused when there is none, saying what it was wanted for. */
+function listedPath(folder, name, wanted) {
+    const [, shelf, file] = /^(games|study)\/(.*)$/.exec(name) ?? [];
+    if (shelf === undefined || !namePattern.test(file ?? "") || !existsSync(join(folder, name))) {
+        throw new Error(`There is no ${name} ${wanted}: give a game's name as past_games or study_games writes it.`);
+    }
+    return join(folder, name);
+}
+const shelves = { games: { what: "of the archive", list: "past_games" }, study: { what: "kept to study", list: "study_games" } };
+// A game's name is the time it started, 2026-11-02-153012, with .pgn, in its shelf's folder (D-41): the only place that writes the format.
+const stemPattern = /\d{4}-\d{2}-\d{2}-\d{6}/;
+const namePattern = new RegExp(`^${stemPattern.source}\\.pgn$`);
+const listedPattern = new RegExp(`^\\s*(?:(games|study)/)?(${stemPattern.source})(\\.pgn)?\\s*$`);
+/** The time a game's name holds, 2026-11-02-153012, wherever it is in the text; undefined when there is none. */
+export function gameStemOf(name) {
+    return stemPattern.exec(name)?.[0];
+}
+/** Whether a text is a game's name as the lists write it, games/2026-11-02-153012.pgn, with or without its folder. */
+export function isGameName(text) {
+    return new RegExp(listedPattern.source, "i").exec(text)?.[3] !== undefined;
+}
+/**
+ * A game's name as the lists write it, from a name without its folder or its .pgn too: 2026-11-04-173054 is games/2026-11-04-173054.pgn, or the game kept
+ * to study by that name when no game played has it; any other name as it is, for the archive to refuse.
+ */
+export function listedName(folder, name) {
+    const [, shelf, stem] = listedPattern.exec(name) ?? [];
+    if (stem === undefined) {
+        return name;
+    }
+    if (shelf !== undefined) {
+        return `${shelf}/${stem}.pgn`;
+    }
+    const played = `games/${stem}.pgn`;
+    const kept = `study/${stem}.pgn`;
+    return !archivedGames(folder).includes(played) && keptGames(folder).includes(kept) ? kept : played;
+}
+/** The game as PGN for the player: while it goes on, without the AI's plans (D-29); once over, with the coach's judgments too (D-88). */
+export function playerPgn(folder, current) {
+    return writePgn(endOf(current.game) === undefined ? withoutPlans(current.game.record) : endedRecord(folder, current));
+}
+/** The game as PGN with its moves alone, without comments or plans, for Lichess or chess.com. */
+export function movesPgn(current) {
+    const { record, outcome } = current.game;
+    return writePgn(movesOnly(endOf(current.game) === undefined ? record : withTermination(record, outcome)));
+}
+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;
+}
+/** 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 of a game over with the coach's judgments (D-88), and its Termination tag when the board ended the game and the tag is missing. */
+function endedRecord(folder, current) {
+    const { record, outcome } = current.game;
+    return withTermination(withCoach(record, coachWords(folder, current)), outcome);
+}
+function withTermination(record, outcome) {
+    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";