chesspal 0.0.1 → 0.1.0

package/dist/commands/analyse-game.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { type AiLevel, type MoveReview, type PieceLetter, type Side } from "../core/index.ts";
+/** A move as the analysis gives it: what happened, never how good it was (D-6). */
+interface MoveFacts {
+    /** The move, numbered: 12...Nxe5. */
+    move: string;
+    /** The piece it took. */
+    took?: PieceLetter;
+    /** The time it took and the time left after it, in milliseconds, where the record has the clock. */
+    spent?: number;
+    left?: number;
+    /** Who is ahead in material after it, when it changed: White +1. */
+    material?: string;
+    /** After it, the pieces at risk of either side when they changed from the line before ("none" once no piece is), and the mates the side to move has; none once the board ends the game. */
+    atRisk?: string;
+    mates?: readonly string[];
+    /** The first move the opening book does not know. */
+    outOfBook?: true;
+    drawOffer?: true;
+    /** In a game played here, what the AI said with its move, and the plan it wrote. */
+    said?: string;
+    plan?: string;
+    /** The badge and note the AI gave it with annotate_game (D-69). */
+    review?: MoveReview;
+}
+/** A game as the analysis gives it. */
+interface Analysis {
+    /** How to analyse, the first time in a chat (D-68). */
+    instructions?: string;
+    white: string;
+    black: string;
+    /** In a game played here: the side the AI played, and its level. */
+    ai?: Side;
+    level?: AiLevel;
+    /** In a game played elsewhere: the side whose name is the player's profile's. */
+    player?: Side;
+    date?: string;
+    timeControl?: string;
+    result?: string;
+    termination?: string;
+    opening?: string;
+    /** Whether the game stayed in the opening book to its last move. */
+    inBook?: true;
+    /** The last move the opening book knows, the end of the moves with the book's badge. */
+    bookTo?: string;
+    /** The game's name in the archive, a game brought as a PGN too. */
+    name?: string;
+    /** In a game from a position: that position, and what is at risk and the mates in one there. */
+    start?: Omit<MoveFacts, "move"> & {
+        fen: string;
+    };
+    moves: MoveFacts[];
+    /** The AI's word on the whole game, from annotate_game. */
+    review?: string;
+}
+/** A game over move by move, for the analyst (D-68): the current one, one of the archive or kept to study, or one the player brings as a PGN, kept to study. */
+export declare const analyseGame: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    pgn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Analysis>;
+export {};

package/dist/commands/analyse-game.js

@@ -0,0 +1,238 @@
+// The analyst's tool (D-21, D-68): a game over, move by move in one call, facts only and never a judgment, with the analyst's instructions once in a chat.
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { clockOfComment, clockText, closingOf, Game, gameReviewOf, levelOf, materialOf, readPgn, reviewed, reviewOf, timeControlOfTag, timeControlText, withGameReview, } from "../core/index.js";
+import { keepToStudy, lastChatStart, planOf, rewriteGame, startAnalysis } from "../games/index.js";
+import { activeProfile, gameFolder } from "../profiles/index.js";
+import { bookOpening, bookReaches } from "./opening-book.js";
+import { defineCommand } from "./registry.js";
+import { gameToStudy, knownTag, moveNumbers, namedGame, noGameGoingOn } from "./study.js";
+import { balanceText, colourName, riskLine } from "./view.js";
+// The analyst's instructions, read at the first analysis.
+let instructions;
+/** A game over move by move, for the analyst (D-68): the current one, one of the archive or kept to study, or one the player brings as a PGN, kept to study. */
+export const analyseGame = defineCommand({
+    name: "analyse_game",
+    description: "Gives a game that is over move by move, to comment it with the player: each move with what it took and the time it took, the material "
+        + "when it changes, the pieces at risk and the mates in one after it, where the game left the opening book, and your comments and plans. Facts "
+        + "only: the judgment is yours. Without game or pgn, the game just over, or else the last one played; game: a name as past_games or study_games "
+        + "writes it; pgn: a game the player brings from elsewhere, kept to study in the profile. Never while a game goes on. The first time in a chat "
+        + "it also says how to analyse. annotate_game then keeps your badges and notes for the board page. Example: analyse_game {}.",
+    input: z.object({
+        game: z.string().optional().describe("a game's name, as past_games, study_games or analyse_game writes it"),
+        pgn: z.string().optional().describe("a game played elsewhere, in PGN: its tags and its moves, with their [%clk] and a review exported from the board page if it has them; other comments and evals can go"),
+    }),
+    run: ({ game, pgn }, context) => {
+        if (game !== undefined && pgn !== undefined) {
+            throw new Error("Give game or pgn, not both: game names a game of the archive, pgn brings one played elsewhere.");
+        }
+        const studied = pgn === undefined ? gameToStudy(context, game) : importedGame(context, pgn);
+        const analysis = analysisOf(studied, activeProfile(context.home()).name);
+        if (studied.name !== undefined) {
+            markBook(context, { record: studied.record, name: studied.name }, analysis.moves);
+            startAnalysis(gameFolder(context.home()), studied.name, context.now());
+        }
+        const told = analystInstructions(context);
+        return told === undefined ? analysis : { instructions: told, ...analysis };
+    },
+    format: (analysis) => [...(analysis.instructions === undefined ? [] : [analysis.instructions, ""]), ...headLines(analysis), ...analysis.moves.map(moveLine)].join("\n"),
+});
+/** A game the player brings as a PGN, checked move by move and kept to study with its clock and Chesspal's own review: no other comment, no engine's evaluation (D-6). */
+function importedGame(context, pgn) {
+    noGameGoingOn(context);
+    if (/\.pgn\s*$/i.test(pgn)) {
+        throw new Error(`"${pgn.trim()}" is a file's name, not a game: pgn takes a game's text, its tags and its moves. A game played here or kept to study goes in game, by `
+            + "its name, such as games/2026-11-02-153012.pgn.");
+    }
+    const records = readPgn(pgn);
+    if (records.length !== 1) {
+        throw new Error(records.length === 0 ? "The PGN holds no game: give it whole, its tags and its moves." : `The PGN holds ${records.length} games: give one at a time.`);
+    }
+    const [{ tags, moves }] = records;
+    // A game analysed here and exported comes back with its review (T-106): Chesspal's own marks stay, as the clock; any other comment goes.
+    const brought = {
+        tags,
+        moves: moves.map(({ san, comment }) => {
+            const clock = /\[%clk [^\]]*\]/.exec(comment ?? "")?.[0];
+            const move = clock === undefined ? { san } : { san, comment: clock };
+            const review = reviewOf(comment);
+            return review === undefined ? move : reviewed(move, review);
+        }),
+    };
+    const summary = gameReviewOf(records[0]);
+    const closing = closingOf(records[0]);
+    const record = summary === undefined && closing === undefined
+        ? brought
+        : withGameReview(brought, { ...(summary === undefined ? {} : { summary }), ...(closing === undefined ? {} : { closing }) });
+    // A game brought again is the one already kept, with the review written on it since.
+    return namedGame(context, keepToStudy(gameFolder(context.home()), record, context.now()));
+}
+/**
+ * The opening book's moves marked as such in the game kept (D-69): a fact, not a judgment, so Chesspal puts the badge itself on each move from the start to the
+ * last one the book knows, where the AI gave none; a game from another position has none.
+ */
+function markBook(context, { record, name }, moves) {
+    const inBook = bookPlies(record, moves);
+    const unmarked = record.moves.slice(0, inBook).some((move) => reviewOf(move.comment)?.badge === undefined);
+    if (!unmarked) {
+        return;
+    }
+    const marked = record.moves.map((move, ply) => {
+        const review = reviewOf(move.comment);
+        return ply < inBook && review?.badge === undefined ? reviewed(move, { ...review, badge: "book" }) : move;
+    });
+    rewriteGame(gameFolder(context.home()), name, { ...record, moves: marked });
+}
+/** How many plies from the start the opening book knows: to the move before the first out of it; none from another position. */
+function bookPlies(record, moves) {
+    const firstOut = moves.findIndex((move) => move.outOfBook);
+    return record.tags.FEN !== undefined ? 0 : firstOut >= 0 ? firstOut : moves.length;
+}
+function analysisOf({ record, name }, playerName) {
+    const { tags } = record;
+    const ai = sideNamed(record, "AI");
+    const control = timeControlOfTag(tags.TimeControl ?? "");
+    const { start, moves, outcome } = movesOf(record, ai);
+    // The board's end before the tags': a record may say what the board does not.
+    const ended = outcome.over ? { result: outcome.result, termination: outcome.ending } : tags.Result !== undefined && tags.Result !== "*" ? { result: tags.Result, termination: tags.Termination } : undefined;
+    const opening = bookOpening(record);
+    return {
+        white: tags.White ?? "?",
+        black: tags.Black ?? "?",
+        ai,
+        level: ai === undefined ? undefined : levelOf(record),
+        player: ai === undefined && playerName !== undefined ? sideNamed(record, playerName) : undefined,
+        date: knownTag(tags.Date),
+        timeControl: control === undefined ? knownTag(tags.TimeControl) : timeControlText(control),
+        result: ended?.result,
+        termination: ended?.termination,
+        opening: opening === undefined ? undefined : `${opening.eco} ${opening.name}`,
+        inBook: opening !== undefined && !moves.some((move) => move.outOfBook) ? true : undefined,
+        bookTo: opening === undefined ? undefined : moves[bookPlies(record, moves) - 1]?.move,
+        review: [gameReviewOf(record), closingOf(record)].filter((word) => word !== undefined).join(" ") || undefined,
+        name,
+        start: tags.FEN === undefined ? undefined : { fen: tags.FEN, ...start },
+        moves,
+    };
+}
+/** The facts of every move, from a replay of the game: the facts after each move are those before the next. */
+function movesOf(record, ai) {
+    const numbers = moveNumbers(record);
+    const game = new Game({ tags: record.tags, moves: [] });
+    const increment = timeControlOfTag(record.tags.TimeControl ?? "")?.increment;
+    // The time each side had left after its last move: the first move of each side spends no time it can tell, as the sites start their clocks apart.
+    const left = {};
+    let inBook = record.tags.FEN === undefined && bookReaches(game.position.fen);
+    let before = game.facts;
+    let balance = materialOf(game.position.fen).balance;
+    const start = { atRisk: riskLine(before), mates: matesOf(before) };
+    // What was at risk on the line before: a move tells it only when it changed.
+    let risk = start.atRisk;
+    const moves = record.moves.map(({ san, comment }, ply) => {
+        const side = game.position.turn;
+        const played = game.playRecorded(san);
+        if (!played.played) {
+            throw new Error(`The game's move ${numbers[ply]}${san} cannot be played: ${played.message} Fix the game's PGN.`);
+        }
+        const outOfBook = inBook && !bookReaches(game.position.fen);
+        inBook &&= !outOfBook;
+        const facts = game.facts;
+        const over = game.outcome.over;
+        const now = materialOf(game.position.fen).balance;
+        const clock = clockOfComment(comment ?? "");
+        const previous = left[side];
+        const risks = riskLine(facts);
+        const move = {
+            move: `${numbers[ply]}${san}`,
+            took: before.pieces.find((piece) => piece.square === played.move.to)?.piece ?? (san.includes("x") ? "P" : undefined),
+            spent: clock === undefined || previous === undefined || increment === undefined ? undefined : Math.max(0, previous - clock + increment),
+            left: clock,
+            material: now === balance ? undefined : balanceText(now),
+            atRisk: over || risks === risk ? undefined : (risks ?? "none"),
+            mates: over ? undefined : matesOf(facts),
+            outOfBook: outOfBook ? true : undefined,
+            drawOffer: comment?.includes("(=)") === true ? true : undefined,
+            said: side === ai ? saidIn(comment) : undefined,
+            review: reviewOf(comment),
+            plan: side === ai ? planOf(comment) : undefined,
+        };
+        if (clock !== undefined) {
+            left[side] = clock;
+        }
+        before = facts;
+        balance = now;
+        risk = risks;
+        return move;
+    });
+    return { start, moves, outcome: game.outcome };
+}
+/** The head of the analysis: who played, when and how fast, how it ended, the opening, and the game's name for look and position. */
+function headLines(analysis) {
+    const { ai, level, player } = analysis;
+    const named = (side) => `${side === "white" ? analysis.white : analysis.black}${side === player ? " (the player)" : ""}`;
+    const players = ai === undefined
+        ? `White: ${named("white")}; Black: ${named("black")}.`
+        : `You played ${colourName(ai)} at the ${level} level, the player ${colourName(ai === "white" ? "black" : "white")}.`;
+    const when = [analysis.date, analysis.timeControl === undefined ? undefined : `time control ${analysis.timeControl}`].filter((part) => part !== undefined).join(", ");
+    const count = Math.ceil(analysis.moves.length / 2);
+    const result = analysis.result === undefined ? "unknown" : `${analysis.result}${analysis.termination === undefined ? "" : ` (${analysis.termination})`}`;
+    const book = analysis.bookTo === undefined ? "" : analysis.inBook ? ", in the book to the end" : `, in the book to ${analysis.bookTo}`;
+    const badged = analysis.bookTo === undefined || analysis.name === undefined ? "" : ": those moves have the book badge, unless you give another";
+    const opening = analysis.opening === undefined ? [] : [`Opening: ${analysis.opening}${book}${badged}`];
+    const name = analysis.name === undefined ? 'Look and position take a move alone, such as move "12..."' : `Look and position take it as game "${analysis.name}"`;
+    const start = analysis.start === undefined ? [] : [moveLine({ ...analysis.start, move: `Start, ${analysis.start.fen}` })];
+    const head = `${players}${when === "" ? "" : ` ${when[0].toUpperCase()}${when.slice(1)}.`} Result: ${result}, after ${count} ${count === 1 ? "move" : "moves"}.`;
+    const review = analysis.review === undefined ? [] : [`Your review: ${analysis.review}`];
+    return [head, ...opening, ...review, `${name}.`, ...start];
+}
+/** 12...Nxe5: took P; spent 0:12, 4:32 left; material White +1; at risk: undefended Black Nf6; mate in one: Qh7#; out of book; you said "…"; your plan: … */
+function moveLine(move) {
+    const left = move.left === undefined ? undefined : `${clockText(move.left)} left`;
+    const parts = [
+        move.took === undefined ? undefined : `took ${move.took}`,
+        move.spent === undefined ? left : `spent ${clockText(move.spent)}, ${left}`,
+        move.material === undefined ? undefined : `material ${move.material}`,
+        move.atRisk === undefined ? undefined : `at risk: ${move.atRisk}`,
+        move.mates === undefined ? undefined : `mate in one: ${move.mates.join(" ")}`,
+        move.outOfBook ? "out of book" : undefined,
+        move.drawOffer ? "offers a draw" : undefined,
+        move.said === undefined ? undefined : `you said "${move.said}"`,
+        move.plan === undefined ? undefined : `your plan: ${move.plan}`,
+        // The book's badge alone is Chesspal's, not the AI's word: the line says the move left the book where it did.
+        move.review === undefined || (move.review.badge === "book" && move.review.note === undefined) ? undefined : reviewLine(move.review),
+    ].filter((part) => part !== undefined);
+    return parts.length === 0 ? move.move : `${move.move}: ${parts.join("; ")}`;
+}
+/**
+ * The analyst's instructions, the first time in a chat where the MCP server keeps what it told: again in a chat cleared or summarized, since its start
+ * keys them (D-57); never on the command line, where no analyst reads.
+ */
+function analystInstructions(context) {
+    const key = `analyst ${lastChatStart(context.folder)?.at ?? ""}`;
+    if (context.told === undefined || context.told.has(key)) {
+        return undefined;
+    }
+    context.told.add(key);
+    instructions ??= readFileSync(new URL("../../instructions/analyst.md", import.meta.url), "utf8").trim();
+    return instructions;
+}
+/** The mates in one the side to move has; none when it has none. */
+function matesOf(facts) {
+    const mates = facts.checks.filter((check) => check.endsWith("#"));
+    return mates.length === 0 ? undefined : mates;
+}
+/** The side a name plays, by the White and Black tags, whatever its case; none when neither is that name. */
+function sideNamed({ tags }, name) {
+    const same = (tag) => tag?.trim().toLowerCase() === name.trim().toLowerCase();
+    return same(tags.White) ? "white" : same(tags.Black) ? "black" : undefined;
+}
+/** The words of a move's comment, without the commands PGN hides in it ([%clk], [%plan]) and the draw offer. */
+function saidIn(comment) {
+    const words = (comment ?? "").replace(/\[%[^\]]*\]/g, "").replace("(=)", "").replace(/\s+/g, " ").trim();
+    return words === "" ? undefined : words;
+}
+/** What the AI kept on a move with annotate_game: you marked blunder: "note", or you noted "note". */
+function reviewLine({ badge, note }) {
+    const quoted = note === undefined ? "" : `"${note}"`;
+    return badge === undefined ? `you noted ${quoted}` : `you marked ${badge}${quoted === "" ? "" : `: ${quoted}`}`;
+}

package/dist/commands/annotate-game.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+/** What the review kept: the game's name, how many moves it marked, and whether it holds a word on the whole game. */
+interface Annotated {
+    game: string;
+    marked: number;
+    summary: boolean;
+    closing: boolean;
+    /** The opening book's moves still without a note of the AI's, as analyse_game numbers them. */
+    bookUnnoted: string[];
+}
+/** The AI's badges and notes on a game over, and its word on the whole game, written into the game's PGN (D-69). */
+export declare const annotateGame: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        move: z.ZodString;
+        badge: z.ZodOptional<z.ZodEnum<{
+            brilliant: "brilliant";
+            great: "great";
+            best: "best";
+            excellent: "excellent";
+            good: "good";
+            book: "book";
+            inaccuracy: "inaccuracy";
+            mistake: "mistake";
+            miss: "miss";
+            blunder: "blunder";
+        }>>;
+        note: z.ZodOptional<z.ZodString>;
+        arrows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        squares: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    summary: z.ZodOptional<z.ZodString>;
+    closing: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Annotated>;
+export {};

package/dist/commands/annotate-game.js

@@ -0,0 +1,78 @@
+// The AI's review of a game over (D-69): a badge on each move that matters, as chess.com marks them, with a note when it needs one, and its word on the
+// whole game, kept in the game's PGN for the board page. The judgment is the AI's alone: Chesspal gives no criteria (D-6, D-43).
+import { z } from "zod";
+import { annotatorOf, badges, reviewed, reviewOf, withAnnotator, withGameReview } from "../core/index.js";
+import { gameInAnalysis, rewriteGame, startAnalysis } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.js";
+import { defineCommand } from "./registry.js";
+import { moveIndex, moveNumbers, namedGame, noGameGoingOn } from "./study.js";
+const summaryLimit = 1500;
+const closingLimit = 400;
+/** The AI's badges and notes on a game over, and its word on the whole game, written into the game's PGN (D-69). */
+export const annotateGame = defineCommand({
+    name: "annotate_game",
+    description: "Keeps your review of a game that is over for the board page: on each move that matters a badge, as chess.com has them, with a short note "
+        + "when it needs one, or a note alone on a move worth a word without a badge; your word on the whole game; and a last short word on how it ended, "
+        + "its win or loss. The judgment is yours: mark the moves you would point out, not every move. A note can draw arrows and colour squares on the board to show what it says. The opening book's moves have their book badge already: give each a short note too, what it is for, in the player's words; without one the page shows the opening's name from the book, in English. A move marked again takes its new badge and note. Notes in the player's language and in words, as in the chat; **two asterisks** put the few words that matter in bold, a square or a file too (**g7**, the **h** pawn). Without game, the game analyse_game gave last. Never "
+        + 'while a game goes on. Example: annotate_game {notes: [{move: "12...", badge: "blunder", note: "leaves the queen to the knight"}], summary: "…", closing: "…"}.',
+    input: z.object({
+        game: z.string().optional().describe("the game's name, as analyse_game writes it; without it, the game analysed last"),
+        notes: z.array(z.object({
+            move: z.string().describe("the move, as analyse_game numbers it: 12. for White's, 12... for Black's"),
+            badge: z.enum(badges).optional(),
+            note: noteInput.optional().describe("why, in a few sentences, with the better move when there was one"),
+            arrows: arrowsInput,
+            squares: squaresInput,
+        })).optional().describe("the moves that matter, each with its badge, its note, or both"),
+        summary: z.string().max(summaryLimit).optional().describe("your word on the whole game: a short paragraph, with a few points as lines starting with - if it helps; the moves have their own notes"),
+        closing: z.string().max(closingLimit).optional().describe("your last word on how the game ended, its win or loss, in a sentence or two: the page shows it at the end"),
+    }),
+    run: async ({ game, notes = [], summary, closing }, context) => {
+        noGameGoingOn(context);
+        if (notes.length === 0 && summary === undefined && closing === undefined) {
+            throw new Error("Give notes on the moves that matter, your word on the whole game as summary, your last word on the ending as closing, or all of them. Nothing changed.");
+        }
+        const studied = game === undefined ? gameAnalysed(context) : namedGame(context, game);
+        // Every move is checked before the game is written: all or nothing.
+        const moves = [...studied.record.moves];
+        for (const { move, badge, note, arrows = [], squares = [] } of notes) {
+            if (badge === undefined && note === undefined) {
+                throw new Error(`Give ${move} a badge, a note, or both: arrows and squares go with them. Nothing changed.`);
+            }
+            const index = moveIndex(studied.record, move);
+            // A note alone on a move of the book keeps its book badge: a fact Chesspal put there, not the AI's judgment.
+            const kept = badge ?? (reviewOf(moves[index].comment)?.badge === "book" ? "book" : undefined);
+            moves[index] = reviewed(moves[index], { ...(kept === undefined ? {} : { badge: kept }), ...(note === undefined ? {} : { note }), ...drawingsOf(arrows, squares) });
+        }
+        // Who reviewed it, as far as the host says it for certain (D-81): on the command line, or by a host that names no model over one that did, as it was.
+        const caller = await context.caller?.();
+        const kept = caller === undefined || (caller.hostOnly === true && annotatorOf(studied.record) !== undefined);
+        const marked = { ...(kept ? studied.record : withAnnotator(studied.record, caller)), moves };
+        rewriteGame(gameFolder(context.home()), studied.name, summary === undefined && closing === undefined ? marked : withGameReview(marked, { ...(summary === undefined ? {} : { summary }), ...(closing === undefined ? {} : { closing }) }));
+        startAnalysis(gameFolder(context.home()), studied.name, context.now());
+        const numbers = moveNumbers(marked);
+        const bookUnnoted = moves.flatMap((move, index) => {
+            const review = reviewOf(move.comment);
+            return review?.badge === "book" && review.note === undefined ? [numbers[index]] : [];
+        });
+        return { game: studied.name, marked: notes.length, summary: summary !== undefined, closing: closing !== undefined, bookUnnoted };
+    },
+    format: ({ game, marked, summary, closing, bookUnnoted }) => {
+        const kept = [marked === 0 ? undefined : `${marked} ${marked === 1 ? "move" : "moves"} marked`, summary ? "your word on the game" : undefined, closing ? "your last word" : undefined].filter((part) => part !== undefined);
+        const book = bookUnnoted.length === 0
+            ? []
+            : [
+                `${bookUnnoted.length === 1 ? "The book's move" : "The book's moves"} ${bookUnnoted.join(" ")} ${bookUnnoted.length === 1 ? "has" : "have"} no note of yours: `
+                    + "the page shows the book's English name there. A short note on each, in the player's words, takes its place.",
+            ];
+        return [`Kept in ${game}: ${[kept.slice(0, -1).join(", "), kept.at(-1)].filter((part) => part !== "").join(" and ")}. The board page shows them.`, ...book].join("\n");
+    },
+});
+function gameAnalysed(context) {
+    const analysis = gameInAnalysis(gameFolder(context.home()));
+    if (analysis === undefined) {
+        throw new Error("No game is in analysis: call analyse_game first, or give the game's name as game. Nothing changed.");
+    }
+    return namedGame(context, analysis.game);
+}

package/dist/commands/clock.d.ts

@@ -0,0 +1,15 @@
+import { type Side } from "../core/index.ts";
+import { type CurrentGame } from "../games/index.ts";
+/** What the AI reads of the clock: the time control, and the time each side has left when the command ran, in milliseconds. */
+export interface ClockSummary {
+    control: string;
+    left: Record<Side, number>;
+    /** The clocks wait for the player to start them. */
+    waiting?: true;
+}
+/** The current game of a folder `now`, or undefined: a game whose side to move has run out of time is over, saved and archived first. */
+export declare function gameAt(folder: string, now: Date): CurrentGame | undefined;
+/** The clock of a game `now`, as the AI reads it; none in a game without one. */
+export declare function clockSummaryOf(current: CurrentGame, now: Date): ClockSummary | undefined;
+/** The clock's line: Clock: you 4:32, player 5:01 (10+5), and whether the clocks still wait for the player. */
+export declare function clockLine({ control, left, waiting }: ClockSummary, ai: Side): string;

package/dist/commands/clock.js

@@ -0,0 +1,45 @@
+// The clock in the commands (D-13): a flag that falls ends the game as soon as a command reads it, and the clock's line for the AI.
+import { canMate, clockText, Game, timeControlText, timeLeft } from "../core/index.js";
+import { archiveEnded, endOf, loadGame, saveGame } from "../games/index.js";
+import { colourName } from "./view.js";
+/** The current game of a folder `now`, or undefined: a game whose side to move has run out of time is over, saved and archived first. */
+export function gameAt(folder, now) {
+    const current = loadGame(folder);
+    if (current?.clock === undefined || endOf(current.game) !== undefined) {
+        return current;
+    }
+    const { turn } = current.game.position;
+    if (timeLeft(current.clock, turn, now)[turn] > 0) {
+        return current;
+    }
+    const ended = outOfTime(current, turn, now);
+    saveGame(folder, ended);
+    // An archive that cannot be written leaves the game in game.json, where status shows it, until a new game archives it.
+    archiveEnded(folder, ended);
+    return ended;
+}
+/** The clock of a game `now`, as the AI reads it; none in a game without one. */
+export function clockSummaryOf(current, now) {
+    const { clock, game } = current;
+    if (clock === undefined) {
+        return undefined;
+    }
+    const left = endOf(game) === undefined ? timeLeft(clock, game.position.turn, now) : { ...clock.left };
+    return { control: timeControlText(clock.control), left, ...(clock.waiting === true && endOf(game) === undefined ? { waiting: true } : {}) };
+}
+/** The clock's line: Clock: you 4:32, player 5:01 (10+5), and whether the clocks still wait for the player. */
+export function clockLine({ control, left, waiting }, ai) {
+    const player = ai === "white" ? "black" : "white";
+    const line = `Clock: you ${clockText(left[ai])}, player ${clockText(left[player])} (${control}).`;
+    return waiting === true ? `${line} The clocks wait: they start with the player's first move, or with Start on the board page when your move is first.` : line;
+}
+/** The game lost on time by `loser`, or drawn when the other side could not mate with any series of legal moves (FIDE 6.9). */
+function outOfTime(current, loser, now) {
+    const winner = loser === "white" ? "black" : "white";
+    const ending = canMate(current.game.position.fen, winner)
+        ? { Result: loser === "white" ? "0-1" : "1-0", Termination: `${colourName(loser)} lost on time` }
+        : { Result: "1/2-1/2", Termination: `${colourName(loser)} ran out of time and ${colourName(winner)} cannot mate` };
+    const { record } = current.game;
+    const clock = { ...current.clock, left: { ...current.clock.left, [loser]: 0 }, since: now.toISOString() };
+    return { ...current, game: new Game({ ...record, tags: { ...record.tags, ...ending } }), clock };
+}

package/dist/commands/context.d.ts

@@ -0,0 +1,56 @@
+import type { Position } from "./play-move.ts";
+/** What a command runs with, besides its input: given by the command line or the MCP server, and by the tests. */
+export interface Context {
+    /** The folder Chesspal runs in: the player's, where the AI host started it, which keeps only the host's files (D-71). */
+    folder: string;
+    /** The player's data folder (D-71), with a profile in it: the profiles, their games and the games kept to study, the same for every chat. */
+    home: () => string;
+    /** A number from 0 to 1, as Math.random gives: the colour drawn for the AI. */
+    random: () => number;
+    /** The time now: when a game starts. */
+    now: () => Date;
+    /** Waits a while, in milliseconds: a tool that waits for the player, as ponder does; the tests move their clock instead. */
+    pause?: (milliseconds: number) => Promise<void>;
+    /** The operating system, as process.platform names it: how a host starts the server. */
+    platform: string;
+    /** The player's language, as the system names it (it-IT): the command line's words to the player, in English when none or another. */
+    language?: string;
+    /** The address of the board page, when the MCP server serves it (D-47). */
+    page?: string;
+    /** Whether a browser has the board page open now, when the MCP server serves it. */
+    pageOpen?: () => boolean;
+    /** Opens a folder in the system's file manager: the data folder, from the board page (T-119); whether it could; none in the tests. */
+    openFolder?: (folder: string) => Promise<boolean>;
+    /** Opens the New game window on the board pages open now, where the player chooses the game: whether one was open. */
+    askNewGame?: () => boolean;
+    /** The AI host, as it names itself to the MCP server: claude-code, which notes how each chat starts (D-57); none on the command line. */
+    host?: () => string | undefined;
+    /** The player's words on the board page given to the AI in this process, by line: each comes once (T-65). */
+    readonly given: Set<string>;
+    /** Told when the board page has news that no file holds: words the AI was given, which it shows read (D-53), and the AI's model (D-82). */
+    heard?: () => void;
+    /** Told when the chat calls a tool, before it runs: the board page hears the chat listens, and the AI's clock, held while nobody did, starts. */
+    calls?: () => void;
+    /** The game the chat saw when its last tool ended, its folder and its stamp: the doorbell wakes it only for a game changed since. */
+    seen?: string | undefined;
+    /**
+     * The position the last tool that showed the game showed the chat: its moves are refused on a game changed since, by another chat or on the page
+     * (D-71); null in a chat no tool has shown the game yet, none outside a chat.
+     */
+    positionSeen?: Position | null | undefined;
+    /** The instructions the MCP server gave in this chat, by their name and the chat's start: each comes once a chat (D-68); none on the command line. */
+    told?: Set<string>;
+    /** Who makes this tool call, as far as the host ties it to the call (D-81); none on the command line. */
+    caller?: () => Promise<Caller | undefined>;
+}
+/** Who made a tool call: the model, else the host's name, never what the AI says of itself; the effort only when the host gives it (T-113). */
+export interface Caller {
+    readonly annotator: string;
+    readonly effort?: string;
+    /** The annotator is the host's name: the model is not known. */
+    readonly hostOnly?: boolean;
+}
+/** The context of a process started in the player's folder: the data folder is found at the first command that needs it, once. */
+export declare function defaultContext(): Context;
+/** A data folder with a profile in it, the first made when there is none, named after the system's account (D-71). */
+export declare function withProfile(folder: string, account: string): string;

package/dist/commands/context.js

@@ -0,0 +1,36 @@
+import { userInfo } from "node:os";
+import { dataFolder, openFolder } from "../home/index.js";
+import { ensureProfile } from "../profiles/index.js";
+/** The context of a process started in the player's folder: the data folder is found at the first command that needs it, once. */
+export function defaultContext() {
+    let found;
+    const home = () => withProfile(found ??= dataFolder(), accountName());
+    return {
+        folder: process.cwd(),
+        home,
+        random: Math.random,
+        now: () => new Date(),
+        platform: process.platform,
+        language: systemLanguage(),
+        given: new Set(),
+        openFolder: (folder) => openFolder(folder, process.platform),
+    };
+}
+/** A data folder with a profile in it, the first made when there is none, named after the system's account (D-71). */
+export function withProfile(folder, account) {
+    ensureProfile(folder, account);
+    return folder;
+}
+/** The name the system knows the user by, for the first profile: Player when it has none. */
+function accountName() {
+    try {
+        return userInfo().username.trim() || "Player";
+    }
+    catch {
+        return "Player";
+    }
+}
+/** The system's language, as Node reads it: the user's locale on Windows, LANG and LC_ALL elsewhere. */
+function systemLanguage() {
+    return Intl.DateTimeFormat().resolvedOptions().locale;
+}

package/dist/commands/draw-offer.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from "./context.ts";
+/** A draw offer or answer refused, and why, for the page to say it in the player's language: one stands already, none stands, or no side has moved yet. */
+export declare class DrawRefused extends Error {
+    readonly reason: "offered" | "none" | "early";
+    constructor(message: string, reason: DrawRefused["reason"]);
+}
+/** The player offers a draw on their turn, once each side has moved: it stands until the AI accepts it or moves, and one stands at a time. */
+export declare function offerDraw(context: Context): void;
+/** The player's answer to the AI's draw offer: accepted, the game ends drawn by agreement; declined, it goes on. */
+export declare function answerDraw(context: Context, accept: boolean): void;

package/dist/commands/draw-offer.js

@@ -0,0 +1,43 @@
+// The draw offers of the board page (D-65): the player's, made on their turn as on Lichess, and their answer to the AI's, which ai_move makes with its move.
+import { bothSidesMoved, drawOfferOf, saveGame } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { endGame } from "./end-game.js";
+import { gameGoingOn } from "./game-summary.js";
+/** A draw offer or answer refused, and why, for the page to say it in the player's language: one stands already, none stands, or no side has moved yet. */
+export class DrawRefused extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** The player offers a draw on their turn, once each side has moved: it stands until the AI accepts it or moves, and one stands at a time. */
+export function offerDraw(context) {
+    const folder = gameFolder(context.home());
+    const current = gameGoingOn(folder, context.now());
+    const offer = drawOfferOf(current);
+    if (current.game.position.turn === current.ai) {
+        throw new Error("Offer a draw on your turn: wait for the AI's move. Nothing changed.");
+    }
+    if (!bothSidesMoved(current.game)) {
+        throw new DrawRefused("A draw can be offered once each side has made a move. Nothing changed.", "early");
+    }
+    if (offer !== undefined) {
+        throw new DrawRefused(offer === "player" ? "You have offered a draw already: it stands until the AI's move. Nothing changed." : "The AI offers a draw: accept it or decline it. Nothing changed.", "offered");
+    }
+    saveGame(folder, { ...current, drawOffer: "player" });
+}
+/** The player's answer to the AI's draw offer: accepted, the game ends drawn by agreement; declined, it goes on. */
+export function answerDraw(context, accept) {
+    const folder = gameFolder(context.home());
+    const current = gameGoingOn(folder, context.now());
+    if (drawOfferOf(current) !== "ai") {
+        throw new DrawRefused("The AI offers no draw to answer. Nothing changed.", "none");
+    }
+    if (accept) {
+        endGame.run({ result: "draw_agreed" }, context);
+    }
+    else {
+        saveGame(folder, { ...current, drawOffer: undefined });
+    }
+}

package/dist/commands/drawings.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { type DrawnArrow, type DrawnSquare } from "../core/index.ts";
+/** The most a note of the AI's on a move may hold: a few sentences. */
+export declare const noteLimit = 700;
+/** A note of the AI's on a move, as its input reads it: on one line of commands, so without brackets or braces. */
+export declare const noteInput: z.ZodString;
+/** The arrows the AI draws, as their input reads them. */
+export declare const arrowsInput: z.ZodOptional<z.ZodArray<z.ZodString>>;
+/** The squares the AI marks, as their input reads them. */
+export declare const squaresInput: z.ZodOptional<z.ZodArray<z.ZodString>>;
+/** The arrows and squares drawn, those that read; none of either left out. */
+export declare function drawingsOf(arrows?: readonly string[], squares?: readonly string[]): {
+    arrows?: DrawnArrow[];
+    squares?: DrawnSquare[];
+};