chesspal 0.1.0 → 0.2.1

package/dist/core/review.js

@@ -4,7 +4,7 @@ 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" };
+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];
@@ -36,6 +36,10 @@ export function gameReviewOf(record) {
 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];
@@ -49,6 +53,21 @@ export function reviewed(move, 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(",");
@@ -72,6 +91,36 @@ export function annotatorOf(record) {
 export function aiModelIn(record) {
     return signerOf(record.tags, ["AIModel", "AIEffort"]);
 }
+/** The record with the host the AI played it in (D-97); with none known, as it is. */
+export function withAiHost(record, host) {
+    const named = host?.trim();
+    return named === undefined || named === "" ? record : { ...record, tags: { ...record.tags, AIHost: named } };
+}
+/** The host the AI played the game in, as its tags say (D-97); undefined without one. */
+export function aiHostIn(record) {
+    const host = record.tags.AIHost?.trim();
+    return host === undefined || host === "" ? undefined : host;
+}
+/**
+ * The AI's name from its host: Claude Code and the desktop app are Claude, Codex is Codex; without a host it names, from the model, a Claude model is
+ * Claude (D-97). Undefined otherwise.
+ */
+export function aiNameOf(host, model) {
+    if (/claude/i.test(host ?? "")) {
+        return "Claude";
+    }
+    if (/codex/i.test(host ?? "")) {
+        return "Codex";
+    }
+    return /^claude/i.test(model?.trim() ?? "") ? "Claude" : 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 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. */
@@ -88,15 +137,8 @@ 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) {
+function isBadge(word) {
     return badges.includes(word ?? "");
 }
 // The NAGs that judge a move ($1 to $6): a new badge takes their place.
@@ -104,6 +146,7 @@ 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 ([^\]]*)\]/;

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

@@ -3,3 +3,7 @@ import type { AiModel } from "../core/index.ts";
 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;
+/** Notes the host the AI plays in for the games of a folder, after its move (D-97), as the model. */
+export declare function noteAiHost(folder: string, host: string): void;
+/** The host the AI played its last move in, for the games of a folder in this process; none on the command line, or before the AI's first move. */
+export declare function aiHostOf(folder: string): string | undefined;

package/dist/games/ai-model.js

@@ -11,5 +11,14 @@ export function noteAiModel(folder, noted) {
 export function aiModelOf(folder) {
     return models.get(folder);
 }
+/** Notes the host the AI plays in for the games of a folder, after its move (D-97), as the model. */
+export function noteAiHost(folder, host) {
+    hosts.set(folder, host);
+}
+/** The host the AI played its last move in, for the games of a folder in this process; none on the command line, or before the AI's first move. */
+export function aiHostOf(folder) {
+    return hosts.get(folder);
+}
 // By the game's folder, the profile's, where the games are archived.
 const models = new Map();
+const hosts = new Map();

package/dist/games/analysis.d.ts

@@ -1,4 +1,4 @@
-/** 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). */
+/** 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;

package/dist/games/archive.d.ts

@@ -2,13 +2,15 @@ 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
+ * Writes the game to the archive, with the plans, how it ended and the AI's model and host last noted (D-82, D-97), and gives its name; the same game again rewrites the
  * same file.
  */
 export declare function archiveGame(folder: string, current: CurrentGame): string;
@@ -17,6 +19,14 @@ 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. */
@@ -36,7 +46,18 @@ export declare function archivedWhen(name: string): string;
 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). */
+/** 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

@@ -1,15 +1,26 @@
 // 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 { 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 { endOf } from "./current-game.js";
+import { movesOnly, pgnDate, readPgn, withAiHost, withAiModel, writePgn } from "../core/index.js";
+import { aiHostOf, 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.
@@ -23,7 +34,7 @@ export function startOfNewGame(folder, now, before) {
     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
+ * Writes the game to the archive, with the plans, how it ended and the AI's model and host last noted (D-82, D-97), and gives its name; the same game again rewrites the
  * same file.
  */
 export function archiveGame(folder, current) {
@@ -31,7 +42,7 @@ export function archiveGame(folder, current) {
     const path = join(folder, name);
     try {
         makeFolder(dirname(path));
-        writeAtomically(path, writePgn(withAiModel(endedRecord(current), aiModelOf(folder))));
+        writeAtomically(path, writePgn(withAiHost(withAiModel(endedRecord(folder, current), aiModelOf(folder)), aiHostOf(folder))));
     }
     catch (error) {
         throw new Error(`Chesspal could not archive the game: ${error.message}`, { cause: error });
@@ -47,6 +58,23 @@ export function archiveEnded(folder, current) {
         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) {
@@ -73,8 +101,8 @@ export function keptGame(root, 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}`;
+    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`:
@@ -103,19 +131,70 @@ export function keepToStudy(root, record, now) {
 }
 /** 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.`);
-    }
+    const path = listedPath(folder, name, "to write again");
     try {
-        writeAtomically(join(folder, name), writePgn(record));
+        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" } };
-const namePattern = /^\d{4}-\d{2}-\d{2}-\d{6}\.pgn$/;
+// 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}`);
@@ -144,14 +223,6 @@ function gameNamed(folder, shelf, name) {
     }
     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)]);
@@ -161,8 +232,11 @@ 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;
+/** 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/coach.d.ts

@@ -0,0 +1,57 @@
+import { type Badge, type DrawnArrow, type DrawnSquare, type GameRecord, type Lead } from "../core/index.ts";
+import type { CurrentGame } from "./current-game.ts";
+/** The coach's word on a move of the player's: the move by the plies up to it, its badge and note, and the moves of theirs its note names. */
+export interface CoachJudgment {
+    readonly ply: number;
+    readonly badge?: Badge;
+    readonly note?: string;
+    /** The moves in SAN its note names that the player could play: the page shows it only once none is legal on their turn (Anatolij). */
+    readonly held?: string[];
+    /** Only as shown, never kept: a held note the player's last move let go, which the card shows now (Zoe). */
+    readonly released?: true;
+}
+/** The coach's hint for the player's turn, for the position it was given in, with what it draws on the board to show it. */
+export interface CoachHint {
+    readonly position: number;
+    readonly text: string;
+    readonly arrows?: DrawnArrow[];
+    readonly squares?: DrawnSquare[];
+}
+/** Who the coach sees ahead in a position the player was to move in (D-90), by the plies up to it. */
+export interface CoachLead {
+    readonly position: number;
+    readonly lead: Lead;
+}
+/** What the coach wrote in a game. */
+export interface CoachWords {
+    readonly judgments: readonly CoachJudgment[];
+    readonly hint?: CoachHint;
+    readonly leads?: readonly CoachLead[];
+}
+/** What the coach wrote in the game going on: nothing when the file is another game's, or missing. */
+export declare function coachWords(folder: string, current: CurrentGame): CoachWords;
+/** Keeps the coach's word on a move of the player's, in place of one it wrote on the same move. */
+export declare function keepJudgment(folder: string, current: CurrentGame, judgment: CoachJudgment): void;
+/** Keeps the coach's hint for the player's turn, in place of the one before. */
+export declare function keepHint(folder: string, current: CurrentGame, hint: CoachHint): void;
+/** Keeps who the coach sees ahead in a position, in place of what it said there before. */
+export declare function keepLead(folder: string, current: CurrentGame, { position, lead }: CoachLead): void;
+/** Since when the coach has waited for the player's move in a position: the first time it asked, `now` then. */
+export declare function coachWaitingSince(folder: string, current: CurrentGame, position: number, now: Date): Date;
+/** Whether a coach has started on the game as it is now: until one has, the chat is told again to start it (Priya). */
+export declare function coachStarted(folder: string, current: CurrentGame): boolean;
+/** Notes that a coach starts on the game as it is now: true for the first, false for another the chat started on it too, which stops. */
+export declare function startCoach(folder: string, current: CurrentGame): boolean;
+/** Forgets the coach's words on the game over, when its review is deleted (D-92): they would go back into its PGN. */
+export declare function forgetCoach(folder: string): void;
+/**
+ * What the player may see of it in the game as it is: the judgments but those that name a move the player may play, held while the opponent is to move
+ * too (Anatolij), and the hint only in its own position. A held one that the last pair of moves let go is marked, for the card to show it
+ * now, however far back its move (Zoe).
+ */
+export declare function coachShown({ judgments, hint, leads }: CoachWords, { game, ai }: CurrentGame): CoachWords;
+/**
+ * The record with the coach's judgments in the comments of the moves they judge, as the analyst writes its own: for the game over. A move the analyst has
+ * reviewed already keeps its review (Federico); the book's badge alone is no review, and stays under a note alone, as annotate_game keeps it.
+ */
+export declare function withCoach(record: GameRecord, { judgments, leads }: CoachWords): GameRecord;

package/dist/games/coach.js

@@ -0,0 +1,144 @@
+// What the coach writes during a game with the helps on (D-88): its judgments of the player's moves, its hint for their turn and who it sees ahead (D-90),
+// in coach.json beside game.json, where no command of the opponent's reads them; the judgments and the leads go into the game's PGN once it is over.
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { badges, Game, leadOf, leadText, readLead, reviewed, reviewOf, withLead } from "../core/index.js";
+import { writeAtomically } from "./files.js";
+/** What the coach wrote in the game going on: nothing when the file is another game's, or missing. */
+export function coachWords(folder, current) {
+    const { judgments, hint, leads = [] } = keptFor(folder, current);
+    const read = leads.flatMap(({ position, lead }) => {
+        const known = readLead(lead);
+        return known === undefined ? [] : [{ position, lead: known }];
+    });
+    return { judgments, ...(hint === undefined ? {} : { hint }), ...(read.length === 0 ? {} : { leads: read }) };
+}
+/** Keeps the coach's word on a move of the player's, in place of one it wrote on the same move. */
+export function keepJudgment(folder, current, judgment) {
+    const kept = keptFor(folder, current);
+    const judgments = [...kept.judgments.filter((one) => one.ply !== judgment.ply), judgment].sort((one, other) => one.ply - other.ply);
+    write(folder, { ...kept, judgments });
+}
+/** Keeps the coach's hint for the player's turn, in place of the one before. */
+export function keepHint(folder, current, hint) {
+    write(folder, { ...keptFor(folder, current), hint });
+}
+/** Keeps who the coach sees ahead in a position, in place of what it said there before. */
+export function keepLead(folder, current, { position, lead }) {
+    const kept = keptFor(folder, current);
+    const leads = [...(kept.leads ?? []).filter((one) => one.position !== position), { position, lead: leadText(lead) }].sort((one, other) => one.position - other.position);
+    write(folder, { ...kept, leads });
+}
+/** Since when the coach has waited for the player's move in a position: the first time it asked, `now` then. */
+export function coachWaitingSince(folder, current, position, now) {
+    const kept = keptFor(folder, current);
+    if (kept.waiting?.position === position) {
+        return new Date(kept.waiting.since);
+    }
+    write(folder, { ...kept, waiting: { position, since: now.toISOString() } });
+    return now;
+}
+/** Whether a coach has started on the game as it is now: until one has, the chat is told again to start it (Priya). */
+export function coachStarted(folder, current) {
+    return keptFor(folder, current).begun === current.game.record.moves.length;
+}
+/** Notes that a coach starts on the game as it is now: true for the first, false for another the chat started on it too, which stops. */
+export function startCoach(folder, current) {
+    const kept = keptFor(folder, current);
+    const plies = current.game.record.moves.length;
+    if (kept.begun === plies) {
+        return false;
+    }
+    write(folder, { ...kept, begun: plies });
+    return true;
+}
+/** Forgets the coach's words on the game over, when its review is deleted (D-92): they would go back into its PGN. */
+export function forgetCoach(folder) {
+    rmSync(join(folder, fileName), { force: true });
+}
+/**
+ * What the player may see of it in the game as it is: the judgments but those that name a move the player may play, held while the opponent is to move
+ * too (Anatolij), and the hint only in its own position. A held one that the last pair of moves let go is marked, for the card to show it
+ * now, however far back its move (Zoe).
+ */
+export function coachShown({ judgments, hint, leads = [] }, { game, ai }) {
+    const plies = game.record.moves.length;
+    const legal = game.position.turn === ai ? undefined : legalMoves(game);
+    const shown = judgments.filter(({ held }) => held === undefined || (legal !== undefined && !names(held, legal)));
+    const before = legal === undefined || plies < 2 || shown.every(({ held }) => held === undefined)
+        ? undefined
+        : legalMoves(new Game({ tags: game.record.tags, moves: game.record.moves.slice(0, plies - 2) }));
+    const marked = before === undefined ? shown : shown.map((judgment) => judgment.held !== undefined && names(judgment.held, before) ? { ...judgment, released: true } : judgment);
+    return { judgments: marked, ...(hint === undefined || hint.position !== plies ? {} : { hint }), ...(leads.length === 0 ? {} : { leads }) };
+}
+/**
+ * The record with the coach's judgments in the comments of the moves they judge, as the analyst writes its own: for the game over. A move the analyst has
+ * reviewed already keeps its review (Federico); the book's badge alone is no review, and stays under a note alone, as annotate_game keeps it.
+ */
+export function withCoach(record, { judgments, leads = [] }) {
+    if (judgments.length === 0 && leads.length === 0) {
+        return record;
+    }
+    const moves = record.moves.map((move, index) => {
+        const judgment = judgments.find((one) => one.ply === index + 1);
+        const review = reviewOf(move.comment);
+        if (judgment === undefined || (review !== undefined && (review.badge !== "book" || review.note !== undefined))) {
+            return move;
+        }
+        const badge = judgment.badge ?? review?.badge;
+        return reviewed(move, { ...(badge === undefined ? {} : { badge }), ...(judgment.note === undefined ? {} : { note: judgment.note }) });
+    });
+    return { ...record, moves: withLeads(moves, leads) };
+}
+/** The moves with who the coach saw ahead after each (D-90), where nobody has said it there since: on the move that led to the position it was given in. */
+function withLeads(moves, leads) {
+    return moves.map((move, index) => {
+        const lead = leads.find((one) => one.position === index + 1)?.lead;
+        return lead === undefined || leadOf(move.comment) !== undefined ? move : withLead(move, lead);
+    });
+}
+/** The legal moves in a position, without their checks. */
+function legalMoves(game) {
+    return new Set(game.legalMoves().map((move) => withoutCheck(move.san)));
+}
+/** Whether a note's moves name one of the legal moves. */
+function names(held, legal) {
+    return held.some((san) => legal.has(withoutCheck(san)));
+}
+/** A move in SAN without its check or mate, which the position it is played in decides: Qxf7# then is Qxf7+ now. */
+function withoutCheck(san) {
+    return san.replace(/[+#]$/, "");
+}
+const fileName = "coach.json";
+const colours = ["green", "red", "yellow", "blue"];
+const coachFile = z.object({
+    started: z.string(),
+    judgments: z.array(z.object({ ply: z.int().min(1), badge: z.enum(badges).optional(), note: z.string().optional(), held: z.array(z.string()).optional() })),
+    leads: z.array(z.object({ position: z.int().min(0), lead: z.string() })).optional(),
+    hint: z.object({
+        position: z.int().min(0),
+        text: z.string(),
+        arrows: z.array(z.object({ colour: z.enum(colours), from: z.string(), to: z.string() })).optional(),
+        squares: z.array(z.object({ colour: z.enum(colours), square: z.string() })).optional(),
+    }).optional(),
+    waiting: z.object({ position: z.int().min(0), since: z.iso.datetime() }).optional(),
+    begun: z.int().min(0).optional(),
+});
+/** What is kept for a game, by when it started: nothing yet when the file is another game's, or missing. */
+function keptFor(folder, current) {
+    const kept = read(folder);
+    return kept?.started === current.started ? kept : { started: current.started, judgments: [] };
+}
+function read(folder) {
+    try {
+        return coachFile.parse(JSON.parse(readFileSync(join(folder, fileName), "utf8")));
+    }
+    catch {
+        // None yet, or one Chesspal cannot read: the coach's words are only a help, and the next one written replaces it.
+        return undefined;
+    }
+}
+function write(folder, kept) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(kept, null, 2)}\n`);
+}

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

@@ -41,6 +41,8 @@ export declare function drawOfferOf(current: CurrentGame): Speaker | undefined;
 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;
+/** Removes game.json, when the game over it holds is deleted from the archive (D-92): a new game would archive it again. */
+export declare function removeGame(folder: string): void;
 /** A line of the talk as game.json and talk.json keep it. */
 export declare const savedLine: z.ZodObject<{
     who: z.ZodEnum<{

package/dist/games/current-game.js

@@ -1,6 +1,6 @@
 // The player's current game on disk (D-27, D-41): game.json, its PGN and the talk on the board page inside, written whole at every change, and kept in
 // memory while nobody else changes it.
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { Game, readPgn, writePgn } from "../core/index.js";
@@ -65,6 +65,12 @@ export function bothSidesMoved(game) {
 export function gameStamp(folder) {
     return stampOf(join(folder, fileName));
 }
+/** Removes game.json, when the game over it holds is deleted from the archive (D-92): a new game would archive it again. */
+export function removeGame(folder) {
+    const path = join(folder, fileName);
+    kept.delete(path);
+    rmSync(path, { force: true });
+}
 const fileName = "game.json";
 /** A line of the talk as game.json and talk.json keep it. */
 export const savedLine = z.object({ who: z.enum(["player", "ai"]), text: z.string(), ply: z.int().min(0), at: z.iso.datetime(), agent: z.literal(true).optional() });

package/dist/games/files.js

@@ -1,3 +1,4 @@
+// Writing the player's files safely: whole or not at all, with failures that say what to do (D-27).
 import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 /** Writes a file whole or not at all: a temporary file beside it, then renamed over it (D-27). A failure says what to do about it. */
 export function writeAtomically(path, text) {

package/dist/games/index.d.ts

@@ -1,10 +1,11 @@
-export { aiModelOf, noteAiModel } from "./ai-model.ts";
+export { aiHostOf, aiModelOf, noteAiHost, noteAiModel } from "./ai-model.ts";
 export { type Analysis, endAnalysis, gameInAnalysis, startAnalysis } from "./analysis.ts";
-export { archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, keepToStudy, keptGame, keptGames, movesPgn, playerPgn, rewriteGame, startOfNewGame } from "./archive.ts";
+export { archiveCoached, archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, gameStemOf, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.ts";
 export { type ChatStart, cleanSince, lastChatStart, saveChatStart } from "./chat-start.ts";
-export { bothSidesMoved, type CurrentGame, drawOfferOf, endOf, type GameEnd, gameStamp, loadGame, saveGame, type Speaker, type TalkLine } from "./current-game.ts";
+export { type CoachHint, type CoachJudgment, type CoachLead, coachShown, coachStarted, coachWaitingSince, type CoachWords, coachWords, forgetCoach, keepHint, keepJudgment, keepLead, startCoach, withCoach } from "./coach.ts";
+export { bothSidesMoved, type CurrentGame, drawOfferOf, endOf, type GameEnd, gameStamp, loadGame, removeGame, saveGame, type Speaker, type TalkLine } from "./current-game.ts";
 export { makeFolder, renameOver, writeAtomically } from "./files.ts";
 export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.ts";
 export { endTableTalk, loadTableTalk, saveTableTalk, type TableTalk } from "./table-talk.ts";
-export { type Heard, heardLines, playerLinesThisMove, type Sayer, type Talk, talkLimits, talkLine, unheardWords, wakesTheChat, type Words, WordsRefused } from "./talk.ts";
+export { type Heard, heardLines, type Sayer, type Talk, talkLimits, talkLine, unheardWords, wakesTheChat, type Words, WordsRefused } from "./talk.ts";
 export { keepThought, type Thought, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.ts";