chesspal 0.0.1 → 0.1.0

package/dist/commands/study.js

@@ -0,0 +1,122 @@
+// A game to study (D-68): one that is over, played here or kept to study, and any position of it, by its moves as the analysis numbers them. While a game
+// goes on, nothing is studied: the analysis would help the game being played (D-60, D-62).
+import { z } from "zod";
+import { Game } from "../core/index.js";
+import { archivedGame, archivedGames, archivedName, endOf, keptGame, keptGames } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+import { colourName } from "./view.js";
+/** What look and position take to show any position of a game that is over. */
+export const studyInput = {
+    game: z.string().optional().describe("a game's name, as past_games, study_games or analyse_game writes it: one of its positions"),
+    move: z.string().optional().describe("the position after this move of a game over, as analyse_game numbers it: 12. for White's, 12... for Black's"),
+};
+/** The current game when it is over, or none; refused while it goes on, for every game: games are analysed once the one being played is over. */
+export function noGameGoingOn(context) {
+    const current = gameAt(gameFolder(context.home()), context.now());
+    if (current !== undefined && endOf(current.game) === undefined) {
+        throw new Error("A game is going on: games are analysed once it is over, this one and the others, and not by you from a PGN or a file either. Tell the player, and go "
+            + "over it when it ends. Nothing changed.");
+    }
+    return current;
+}
+/** The game played or kept to study by that name; without one, the current game over, or else the latest of the archive; refused while a game goes on. */
+export function gameToStudy(context, name) {
+    const current = noGameGoingOn(context);
+    const folder = gameFolder(context.home());
+    if (name !== undefined) {
+        return namedGame(context, name);
+    }
+    if (current !== undefined) {
+        // The archive's record, which keeps the AI's review (D-69).
+        const archived = archivedName(folder, current);
+        return archived === undefined ? { record: current.game.record } : { record: archivedGame(folder, archived), name: archived };
+    }
+    const [latest] = archivedGames(folder);
+    if (latest === undefined) {
+        throw new Error("There is no game to study: play one with new_game, or give analyse_game the PGN of a game played elsewhere.");
+    }
+    return { record: archivedGame(folder, latest), name: latest };
+}
+/** A game played or kept to study by its name as the lists write it, or without its folder or its .pgn; refused when it is not there. */
+export function namedGame(context, name) {
+    const folder = gameFolder(context.home());
+    const full = fullName(folder, name);
+    return { record: full.startsWith("study/") ? keptGame(folder, full) : archivedGame(folder, full), name: full };
+}
+/** The index of a move in the game's record, given as analyse_game numbers it: 12. for White's, 12... for Black's, 12...Kf8 too. */
+export function moveIndex(record, move) {
+    return plyOf(record, moveNumbers(record), move);
+}
+/** The number of each move of a game as the analysis writes it: 1. for White's first move, 1... for Black's. */
+export function moveNumbers(record) {
+    const start = new Game({ tags: record.tags, moves: [] }).position;
+    const blackFirst = start.turn === "black" ? 1 : 0;
+    return record.moves.map((_move, index) => {
+        const ply = index + blackFirst;
+        return `${start.moveNumber + Math.floor(ply / 2)}${ply % 2 === 0 ? "." : "..."}`;
+    });
+}
+/**
+ * The game as it stood after a move, given by its number (12. for White's, 12... for Black's) and, if wanted, the move itself (12...Kf8), which decides
+ * the side when the dots do not; after the last move without one.
+ */
+export function positionAfter(record, move) {
+    const numbers = moveNumbers(record);
+    const ply = move === undefined ? numbers.length - 1 : plyOf(record, numbers, move);
+    if (ply < 0) {
+        return { game: new Game(record) };
+    }
+    return { game: new Game({ ...record, moves: record.moves.slice(0, ply + 1) }), move: `${numbers[ply]}${record.moves[ply].san}` };
+}
+/** A tag PGN leaves unknown with ? or -, as nothing. */
+export function knownTag(tag) {
+    return tag === undefined || /^[?.\-\s]*$/.test(tag) ? undefined : tag;
+}
+/** Where a position of a game studied stands: After 12...Kf8 in games/2026-11-02-153012.pgn: White to move. */
+export function positionLine({ game, move }, name) {
+    const where = `${move === undefined ? "At the start" : `After ${move}`}${name === undefined ? "" : ` in ${name}`}`;
+    const { outcome, position } = game;
+    return `${where}: ${outcome.over ? `the board ends the game by ${outcome.ending}` : `${colourName(position.turn)} to move`}.`;
+}
+/**
+ * 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.
+ */
+function fullName(folder, name) {
+    const [, shelf, stem] = /^\s*(?:(games|study)\/)?(\d{4}-\d{2}-\d{2}-\d{6})(?:\.pgn)?\s*$/.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;
+}
+function plyOf(record, numbers, move) {
+    const [, number, dots, san] = movePattern.exec(move) ?? [];
+    if (number === undefined) {
+        throw new Error(`"${move}" is not a move of the game: give its number as analyse_game writes it, 12. for White's move and 12... for Black's, such as 12...Kf8.`);
+    }
+    if (numbers.length === 0) {
+        throw new Error("This game has no moves: look and position without move show its position.");
+    }
+    const white = numbers.indexOf(`${Number(number)}.`);
+    const black = numbers.indexOf(`${Number(number)}...`);
+    const plies = (dots === "..." || dots === "…" ? [black] : [white, black]).filter((ply) => ply >= 0);
+    const found = san === undefined ? plies[0] : plies.find((ply) => isMove(record, ply, san));
+    if (found === undefined) {
+        const played = [white, black].filter((ply) => ply >= 0).map((ply) => `${numbers[ply]}${record.moves[ply].san}`);
+        const there = played.length === 0 ? `its moves go from ${numbers[0]}${record.moves[0].san} to ${numbers.at(-1)}${record.moves.at(-1).san}` : `move ${number} is ${played.join(" ")}`;
+        throw new Error(`There is no ${move.trim()} in this game: ${there}.`);
+    }
+    return found;
+}
+/** Whether the move written is the one the game played at that ply, however it is written: Nf3, g1f3, Nf3+. */
+function isMove(record, ply, written) {
+    const played = new Game({ ...record, moves: record.moves.slice(0, ply) }).playRecorded(written);
+    return played.played && played.move.san === record.moves[ply].san;
+}
+const movePattern = /^\s*(\d+)\s*(\.\.\.|\.|…)?\s*(\S+)?\s*$/;

package/dist/commands/view.d.ts

@@ -0,0 +1,14 @@
+import type { Facts, Material, Side } from "../core/index.ts";
+/** The view after the player's move: the check, the pieces attacked, then what is at risk, the pins, the checks and the moves of each piece. */
+export declare function compactView(facts: Facts, turn: Side): string[];
+/** The view of a level without the tactical facts (D-60): the check and the legal moves by piece, which are the rules (D-17). */
+export declare function boardView(facts: Facts, turn: Side): string[];
+/** The whole view, for look: every piece with its attackers and defenders, then the same lines as the compact view. */
+export declare function fullView(facts: Facts, turn: Side): string[];
+/** What is at risk, in one line for a move of the analysis (D-68): undefended Black Nf6; by a cheaper piece White Qd1; outnumbered Black Pe5; none when nothing is. */
+export declare function riskLine(facts: Facts): string | undefined;
+export declare function colourName(side: Side): string;
+/** The material as the player sees it beside the board (D-59): who is ahead and by how much, and the pieces each side took. */
+export declare function materialText(material: Material): string;
+/** Who is ahead in material, and by how many pawns: White +2, or even. */
+export declare function balanceText(balance: number): string;

package/dist/commands/view.js

@@ -0,0 +1,125 @@
+/** The view after the player's move: the check, the pieces attacked, then what is at risk, the pins, the checks and the moves of each piece. */
+export function compactView(facts, turn) {
+    const names = namesOf(facts);
+    const attacked = officersOf(facts).filter((piece) => piece.attackers.length > 0);
+    const pieces = attacked.length === 0 ? ["Attacked pieces: none"] : ["Attacked pieces (attackers / defenders):", ...attacked.map((piece) => pieceLine(piece, names, true))];
+    return [...checkLines(facts, turn, names), ...pieces, ...tacticLines(facts, turn, names)];
+}
+/** The view of a level without the tactical facts (D-60): the check and the legal moves by piece, which are the rules (D-17). */
+export function boardView(facts, turn) {
+    const names = namesOf(facts);
+    return [...checkLines(facts, turn, names), ...legalLines(facts, names)];
+}
+/** The whole view, for look: every piece with its attackers and defenders, then the same lines as the compact view. */
+export function fullView(facts, turn) {
+    const names = namesOf(facts);
+    const sides = sidesInOrder.flatMap((side) => [
+        `${colourName(side)} pieces (attackers / defenders):`,
+        ...officersOf(facts).filter((piece) => piece.side === side).map((piece) => pieceLine(piece, names, false)),
+    ]);
+    return [...checkLines(facts, turn, names), ...sides, ...tacticLines(facts, turn, names)];
+}
+/** What is at risk, in one line for a move of the analysis (D-68): undefended Black Nf6; by a cheaper piece White Qd1; outnumbered Black Pe5; none when nothing is. */
+export function riskLine(facts) {
+    const names = namesOf(facts);
+    const kinds = [["undefended", facts.undefended], ["by a cheaper piece", facts.attackedByCheaper], ["outnumbered", facts.outnumbered]];
+    const text = kinds.filter(([, squares]) => squares.length > 0).map(([kind, squares]) => `${kind} ${bySide(facts, squares, names)}`).join("; ");
+    return text === "" ? undefined : text;
+}
+export function colourName(side) {
+    return side === "white" ? "White" : "Black";
+}
+/** The material as the player sees it beside the board (D-59): who is ahead and by how much, and the pieces each side took. */
+export function materialText(material) {
+    const ahead = balanceText(material.balance);
+    if (material.taken.white.length === 0 && material.taken.black.length === 0) {
+        return `${ahead}, nothing taken`;
+    }
+    return `${ahead} (White took ${takenText(material.taken.white)}, Black took ${takenText(material.taken.black)})`;
+}
+/** Who is ahead in material, and by how many pawns: White +2, or even. */
+export function balanceText(balance) {
+    return balance === 0 ? "even" : `${balance > 0 ? "White" : "Black"} +${Math.abs(balance)}`;
+}
+/** The pieces taken, counted by kind: Q 2R 7P. */
+function takenText(taken) {
+    const kinds = [...new Set(taken)];
+    return kinds.map((piece) => {
+        const count = taken.filter((other) => other === piece).length;
+        return count === 1 ? piece : `${count}${piece}`;
+    }).join(" ") || "nothing";
+}
+const sidesInOrder = ["white", "black"];
+/** The check the side to move is in, from which pieces; none when it is not. */
+function checkLines(facts, turn, names) {
+    return facts.checkedBy === undefined ? [] : [`${colourName(turn)} is in check from ${facts.checkedBy.map(names.piece).join(" and ")}.`];
+}
+/** What is at risk, loose and pinned, the checks of both sides, and the legal moves of the side to move by piece. */
+function tacticLines(facts, turn, names) {
+    const list = (squares) => bySide(facts, squares, names) || "none";
+    const atRisk = facts.undefended.length === 0 && facts.attackedByCheaper.length === 0 && facts.outnumbered.length === 0
+        ? "At risk: none"
+        : `Attacked and undefended: ${list(facts.undefended)}; defended, but attacked by a cheaper piece: ${list(facts.attackedByCheaper)}; `
+            + `attacked more times than defended: ${list(facts.outnumbered)}`;
+    const pins = facts.pins.map((pin) => `${names.sided(pin.square)} to ${names.piece(pin.to)} by ${names.piece(pin.by)}`);
+    return [
+        atRisk,
+        `Loose: ${list(facts.loose)}`,
+        `Pinned: ${pins.join(", ") || "none"}`,
+        ...checksLines(facts, turn),
+        ...legalLines(facts, names),
+    ];
+}
+/** The checks the side to move can give, and those the other side could give if it were to move; one line when neither has any. */
+function checksLines(facts, turn) {
+    if (facts.checks.length === 0 && facts.otherChecks?.length === 0) {
+        return ["Checks: none for either side"];
+    }
+    const other = colourName(turn === "white" ? "black" : "white");
+    const theirs = facts.otherChecks === undefined ? [] : [`Checks ${other} could give if it were to move: ${facts.otherChecks.join(" ") || "none"}`];
+    return [`Checks ${colourName(turn)} (to move) can give: ${facts.checks.join(" ") || "none"}`, ...theirs];
+}
+/** The legal moves of the side to move by piece, with how many, and its pieces that have none; nothing when it has no move, the game over. */
+function legalLines(facts, names) {
+    const mine = facts.pieces.filter((piece) => piece.moves !== undefined);
+    const moving = mine.filter((piece) => piece.moves.length > 0);
+    const stuck = mine.filter((piece) => piece.moves.length === 0).map((piece) => names.piece(piece.square));
+    const count = moving.reduce((total, piece) => total + piece.moves.length, 0);
+    if (count === 0) {
+        return [];
+    }
+    const byPiece = moving.map((piece) => `${names.piece(piece.square)} (${piece.moves.length}) ${piece.moves.join(" ")}`);
+    return [`Legal by piece (${count}): ${[...byPiece, ...(stuck.length === 0 ? [] : [`no moves: ${stuck.join(" ")}`])].join("; ")}`];
+}
+/** A piece with the pieces that attack it and those that defend it, the pieces lined up behind them in brackets: Pf7: Bc4 Ng5 / Ke8; Qd2(+Rd1). */
+function pieceLine(piece, names, withSide) {
+    const list = (squares) => squares.map((square) => `${names.piece(square)}${behindOf(piece, square, names)}`).join(" ") || "-";
+    const name = withSide ? names.sided(piece.square) : names.piece(piece.square);
+    return `${name}: ${list(piece.attackers)} / ${list(piece.defenders)}`;
+}
+function behindOf(piece, square, names) {
+    const behind = piece.behind?.[square];
+    return behind === undefined ? "" : `(+${behind.map(names.piece).join("+")})`;
+}
+/** Pieces by side, White's first: White Ra1 Pb2, Black Ra8. */
+function bySide(facts, squares, names) {
+    const sideAt = new Map(facts.pieces.map((piece) => [piece.square, piece.side]));
+    const groups = sidesInOrder.map((side) => [side, squares.filter((square) => sideAt.get(square) === side)]).filter(([, group]) => group.length > 0);
+    return groups.map(([side, group]) => `${colourName(side)} ${group.map(names.piece).join(" ")}`).join(", ");
+}
+/** The pieces but the kings: a king attacked is a check, said in its own line, and a king is never defended. */
+function officersOf(facts) {
+    return facts.pieces.filter((piece) => piece.piece !== "K");
+}
+function namesOf(facts) {
+    const pieces = new Map(facts.pieces.map((piece) => [piece.square, piece]));
+    const piece = (square) => {
+        const found = pieces.get(square);
+        return found === undefined ? square : `${found.piece}${square}`;
+    };
+    const sided = (square) => {
+        const found = pieces.get(square);
+        return found === undefined ? square : `${colourName(found.side)} ${found.piece}${square}`;
+    };
+    return { piece, sided };
+}

package/dist/core/board-text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The board of a FEN as text: White at the bottom, the pieces as Unicode figurines, the empty squares and the files as signs a browser draws as wide as the
+ * figurines and a terminal in one cell each, so that the columns stay in line in Claude's desktop app and in a terminal alike.
+ */
+export declare function boardText(fen: string): string;
+/** A move in SAN as the player is shown it, with the pieces' solid figurines for either side (D-86): Nxe4 is ♞xe4 and e8=Q is e8=♛. */
+export declare function figurinesOf(san: string): string;

package/dist/core/board-text.js

@@ -0,0 +1,18 @@
+// The board and the moves as text for the player in the chat (D-36), with the pieces' figurines (D-86): the moves for the AI to copy, never its view of the board (D-26).
+/**
+ * The board of a FEN as text: White at the bottom, the pieces as Unicode figurines, the empty squares and the files as signs a browser draws as wide as the
+ * figurines and a terminal in one cell each, so that the columns stay in line in Claude's desktop app and in a terminal alike.
+ */
+export function boardText(fen) {
+    const ranks = (fen.split(" ")[0] ?? "").split("/").map((rank) => rank.replace(/\d/g, (empty) => ".".repeat(Number(empty))));
+    const files = `  ${fileSigns.join(" ")}`;
+    return [files, ...ranks.map((rank, index) => `${8 - index} ${[...rank].map((square) => figurines[square] ?? emptySquare).join(" ")} ${8 - index}`), files].join("\n");
+}
+/** A move in SAN as the player is shown it, with the pieces' solid figurines for either side (D-86): Nxe4 is ♞xe4 and e8=Q is e8=♛. */
+export function figurinesOf(san) {
+    return san.replace(/^[KQRBN]|(?<==)[QRBN]/g, (letter) => figurines[letter.toLowerCase()] ?? letter);
+}
+// The pieces' figurines by their FEN letters; the black pawn's asks for its text form, since alone it shows as an emoji.
+const figurines = { K: "♔", Q: "♕", R: "♖", B: "♗", N: "♘", P: "♙", k: "♚", q: "♛", r: "♜", b: "♝", n: "♞", p: "♟︎" };
+const emptySquare = "⊙";
+const fileSigns = [..."ⓐⓑⓒⓓⓔⓕⓖⓗ"];