chesspal 0.0.1 → 0.1.0

package/dist/commands/profiles.js

@@ -0,0 +1,129 @@
+// The players' profiles (D-23), on the command line and the board page: listed, made, put in use, with their picture (D-45). The AI reads only who plays.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { endOf } from "../games/index.js";
+import { activateProfile, activeProfile, createProfile, drawnAvatars, gameFolder, levels, listProfiles, nameLimit, ratingLimits, ratingSites, removeOwnImage, saveOwnImage, updateProfile, } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+import { defineCommand } from "./registry.js";
+/** A change of profile refused while a game goes on: the page says it in the player's language. */
+export class GameGoingOn extends Error {
+    constructor() {
+        super("A game is going on in this profile: finish it, or resign, before changing profile. Nothing changed.");
+    }
+}
+/** The profiles, the one in use first. */
+export const profiles = defineCommand({
+    name: "profiles",
+    description: "Lists the players' profiles, the one in use marked with *. Example: chesspal profiles.",
+    input: z.object({}),
+    cliOnly: true,
+    readOnly: true,
+    idempotent: true,
+    run: (_input, context) => ({ profiles: listProfiles(context.home()), active: activeProfile(context.home()).id }),
+    format: ({ profiles, active }) => profiles.map((profile) => `${profile.id === active ? "*" : " "} ${profile.id}: ${playerText(profile)}`).join("\n"),
+});
+/** A new profile, put in use once the game going on has ended; the one Chesspal made at the first start, while new, becomes it, game and all (D-71). */
+export const newProfile = defineCommand({
+    name: "new_profile",
+    description: "Makes a player's profile and puts it in use: their games, picture and page settings go in profiles/<id>/ of Chesspal's data folder; the "
+        + "profile Chesspal made at the first start becomes this one, its folder renamed, while nobody has completed it. Example: chesspal new_profile Anna --level regular "
+        + "--rating 1450 --site lichess.",
+    input: z.object({
+        name: z.string().trim().min(1).max(nameLimit).regex(/^[^\p{Cc}]+$/u, "one line of text").describe("the player's name"),
+        level: z.enum(levels).optional().describe("how they play: learning, casual, regular or tournament"),
+        rating: z.int().min(ratingLimits.lowest).max(ratingLimits.highest).optional().describe("their rating, with site"),
+        site: z.enum(ratingSites).optional().describe("where the rating comes from: lichess, chess.com or fide"),
+        avatar: z.enum(drawnAvatars).optional().describe(`a drawn avatar: ${drawnAvatars.join(", ")}`),
+    }),
+    cliOnly: true,
+    positionals: ["name"],
+    run: ({ name, level, rating, site, avatar }, context) => {
+        if ((rating === undefined) !== (site === undefined)) {
+            throw new Error("Give the rating and its site together, such as --rating 1450 --site lichess, or neither. Nothing changed.");
+        }
+        if (activeProfile(context.home()).new !== true) {
+            refuseWhilePlaying(context);
+        }
+        return createProfile(context.home(), {
+            name,
+            ...(level === undefined ? {} : { level }),
+            ...(rating === undefined || site === undefined ? {} : { rating: { value: rating, site } }),
+            ...(avatar === undefined ? {} : { avatar }),
+        });
+    },
+    format: (profile) => `Profile ${profile.id} made, and in use: ${playerText(profile)}.`,
+});
+/** Another profile put in use, once the game going on has ended. */
+export const useProfile = defineCommand({
+    name: "use_profile",
+    description: "Puts another player's profile in use, with its games; refused while a game is going on. Example: chesspal use_profile anna.",
+    input: z.object({ profile: z.string().min(1).describe("the profile, as chesspal profiles lists it") }),
+    cliOnly: true,
+    idempotent: true,
+    positionals: ["profile"],
+    run: ({ profile }, context) => {
+        const active = activeProfile(context.home());
+        if (active.id === profile) {
+            return active;
+        }
+        refuseWhilePlaying(context);
+        return activateProfile(context.home(), profile);
+    },
+    format: (profile) => `Profile ${profile.id} in use: ${playerText(profile)}.`,
+});
+/** The picture of the profile in use: a drawn avatar, or an image of the player's, which replaces any before. */
+export const setAvatar = defineCommand({
+    name: "set_avatar",
+    description: `Sets the picture of the profile in use: a drawn avatar (${drawnAvatars.join(", ")}) or the path of a PNG, JPEG or WebP image of `
+        + "1 MB at most. Example: chesspal set_avatar owl.",
+    input: z.object({ avatar: z.string().min(1).describe("a drawn avatar, or the path of an image") }),
+    cliOnly: true,
+    idempotent: true,
+    positionals: ["avatar"],
+    run: ({ avatar }, context) => {
+        const profile = activeProfile(context.home());
+        const drawn = drawnAvatars.find((one) => one === avatar);
+        if (drawn === undefined) {
+            saveOwnImage(context.home(), profile.id, imageFile(resolve(context.folder, avatar)));
+        }
+        else {
+            chooseDrawnAvatar(context, profile.id, drawn);
+        }
+        return { profile: profile.id, avatar };
+    },
+    format: ({ profile, avatar }) => `The picture of ${profile} is ${avatar}.`,
+});
+/** A drawn avatar chosen for a profile: the player's own image goes, or it would still show. */
+export function chooseDrawnAvatar(context, id, avatar) {
+    updateProfile(context.home(), id, { avatar });
+    removeOwnImage(context.home(), id);
+}
+/**
+ * Who plays, as the AI reads it in status and new_game: their name, how they play and their rating; nothing while the profile is new, named after the
+ * system's account until the player completes it (D-71).
+ */
+export function playerLine(context) {
+    const profile = activeProfile(context.home());
+    return profile.new === true ? undefined : `Player: ${playerText(profile)}.`;
+}
+/** Throws while a game goes on in the profile in use. */
+export function refuseWhilePlaying(context) {
+    const current = gameAt(gameFolder(context.home()), context.now());
+    if (current !== undefined && endOf(current.game) === undefined) {
+        throw new GameGoingOn();
+    }
+}
+const levelText = { learning: "has just learned", casual: "plays now and then", regular: "plays often", tournament: "plays tournaments" };
+const siteText = { "lichess": "Lichess", "chess.com": "Chess.com", "fide": "FIDE" };
+function playerText({ name, level, rating }) {
+    return [name, ...(level === undefined ? [] : [levelText[level]]), ...(rating === undefined ? [] : [`${siteText[rating.site]} ${rating.value}`])].join(", ");
+}
+function imageFile(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (error) {
+        throw new Error(`${path} cannot be read (${error.message}): give a drawn avatar's name, or the path of an image. Nothing changed.`, { cause: error });
+    }
+}

package/dist/commands/registry.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { Context } from "./context.ts";
+/** A command is defined once: the command line and the MCP server are generated from it (D-5), and later the page's actions. */
+export interface Command<Schema extends z.ZodObject = z.ZodObject, Result = unknown> {
+    name: string;
+    /** Written for an AI: what the command does (the first sentence, shown in the list of commands), when to use it, an example. */
+    description: string;
+    input: Schema;
+    /** The command changes nothing: hosts may run it without asking. */
+    readOnly?: boolean;
+    /** The command deletes or overwrites what the player keeps, such as a game: hosts may ask first. */
+    destructive?: boolean;
+    /** Calling the command again with the same input changes nothing more. */
+    idempotent?: boolean;
+    /** Hosts load the tool at once instead of on demand: for the ones the AI calls at the start of every chat. */
+    alwaysLoad?: boolean;
+    /** Its answer shows the chat the game as it is: the chat may move on it, and on no other (D-71). */
+    showsGame?: boolean;
+    /** An agent calls it apart from the chat, as ponder (D-72): the doorbell's record of what the chat has read stays as it was. */
+    byAgent?: boolean;
+    /** The only host the MCP server offers it to, by the client's name, as ponder to Claude Code: elsewhere its description would cost tokens for nothing. */
+    host?: string;
+    /** Only the command line has it, as init: the MCP server leaves it out, and its description costs the AI no tokens. */
+    cliOnly?: boolean;
+    /** Fields the command line takes as positional arguments, in order. */
+    positionals?: Extract<keyof Schema["shape"], string>[];
+    /** Returns a value, never prints: the MCP server speaks on stdout, and only the command line writes there. */
+    run(input: z.infer<Schema>, context: Context): Result | Promise<Result>;
+    /** Plain-text rendering of the result, for the AI and the terminal alike; the context, for a command that speaks to the player, as init. */
+    format(result: Result, context?: Context): string;
+}
+export type AnyCommand = Command<any, any>;
+/** Checks a command's types where it is written; the command is used as it is. */
+export declare function defineCommand<Schema extends z.ZodObject, Result>(command: Command<Schema, Result>): Command<Schema, Result>;
+/** One sentence of the AI's, kept in a PGN comment: no brackets or braces, which would break it. */
+export declare function sentence(most: number): z.ZodString;
+/**
+ * Why an input is refused, in words an AI can act on, the same on the command line and in MCP: one sentence for each problem, each parameter written as
+ * the caller writes it (colour, --colour).
+ */
+export declare function inputProblems(command: string, issues: readonly z.core.$ZodIssue[], given: Record<string, unknown>, written: (name: string) => string): string;
+/**
+ * What keeps a field of a command's input from being given on the command line: one named no-x, read as turning x off, or json, read as answering in JSON;
+ * undefined for any other. A positional is never an option, so json is its name freely.
+ */
+export declare function commandLineFieldProblem(command: string, name: string, positional: boolean): string | undefined;
+/** Whether a field of a command's input is a flag, true or false, as --hidden. */
+export declare function isBoolean(field: z.ZodType): boolean;
+/** A list option can be given more than once, as in --tag a --tag b. */
+export declare function isList(field: z.ZodType): boolean;
+/** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
+export declare function baseType(field: z.ZodType): string;
+/** Whether a field takes numbers, alone or in a list: the command line reads them as text and turns them into numbers. */
+export declare function takesNumbers(field: z.ZodType): boolean;

package/dist/commands/registry.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/** Checks a command's types where it is written; the command is used as it is. */
+export function defineCommand(command) {
+    return command;
+}
+/** One sentence of the AI's, kept in a PGN comment: no brackets or braces, which would break it. */
+export function sentence(most) {
+    return z.string().trim().min(1, "write one sentence").max(most, `write one sentence of ${most} characters at most`).regex(/^[^[\]{}]*$/, "write it without [ ] { }");
+}
+/**
+ * Why an input is refused, in words an AI can act on, the same on the command line and in MCP: one sentence for each problem, each parameter written as
+ * the caller writes it (colour, --colour).
+ */
+export function inputProblems(command, issues, given, written) {
+    return issues.map((issue) => inputIssue(command, issue, given, written)).join(" ");
+}
+function inputIssue(command, issue, given, written) {
+    const path = issue.path.map(String).join(".");
+    if (issue.code === "unrecognized_keys") {
+        return path === "" ? `${command} has no parameter ${issue.keys.map(written).join(", ")}.` : `${written(path)} has no ${issue.keys.join(", ")}.`;
+    }
+    // A parameter left out, whatever zod calls it.
+    if (issue.path.length === 1 && given[path] === undefined) {
+        return `${command} needs ${written(path)}.`;
+    }
+    return path === "" ? `${issue.message}.` : `${written(path)}: ${issue.message}.`;
+}
+/**
+ * What keeps a field of a command's input from being given on the command line: one named no-x, read as turning x off, or json, read as answering in JSON;
+ * undefined for any other. A positional is never an option, so json is its name freely.
+ */
+export function commandLineFieldProblem(command, name, positional) {
+    if (name.startsWith("no-")) {
+        return `${command} has a field named ${name}, and none may start with no-, which the command line reads as turning ${name.slice(3)} off: rename it.`;
+    }
+    return name === "json" && !positional ? `${command} has a field named json, which the command line reads as answering in JSON: rename it.` : undefined;
+}
+/** Whether a field of a command's input is a flag, true or false, as --hidden. */
+export function isBoolean(field) {
+    return baseDefinition(field).type === "boolean";
+}
+/** A list option can be given more than once, as in --tag a --tag b. */
+export function isList(field) {
+    return baseDefinition(field).type === "array";
+}
+/** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
+export function baseType(field) {
+    return baseDefinition(field).type;
+}
+/** Whether a field takes numbers, alone or in a list: the command line reads them as text and turns them into numbers. */
+export function takesNumbers(field) {
+    const definition = baseDefinition(field);
+    return definition.type === "number" || (definition.type === "array" && definition.element !== undefined && baseType(definition.element) === "number");
+}
+function baseDefinition(field) {
+    let definition = field.def;
+    while (definition.innerType && ["optional", "default", "nullable"].includes(definition.type)) {
+        definition = definition.innerType.def;
+    }
+    return definition;
+}

package/dist/commands/say.d.ts

@@ -0,0 +1,16 @@
+import { type Mood } from "../core/index.ts";
+import { type Sayer, type Talk, type Words } from "../games/index.ts";
+import type { Context } from "./context.ts";
+/**
+ * Adds a line to the talk of the current game, going on or just over, and saves it; the AI's mood once the game is over, which the archive keeps too (D-70).
+ * With no game the line goes in the talk before it (D-77). A line refused changes nothing: it throws, in words for whoever spoke.
+ */
+export declare function say(folder: string, who: Sayer, text: string, at: Date, mood?: Mood): Talk;
+/** What the player wrote on the board page that the AI has not been given in this chat, given now: each game tool gives it once. */
+export declare function newWords(context: Context): string[];
+/** Every word of the player's the AI has not answered, given again: status gives them all, for a chat that lost them in a summary. */
+export declare function unansweredWords(context: Context): string[];
+/** What the player wrote on the board page that the AI has not been given in this chat, still to give: the AI's move would count as its answer. */
+export declare function waitingWords(context: Context, given?: ReadonlySet<string>): Words[];
+/** Gives the words to the AI: from now on they count as given in this chat. Their text. */
+export declare function give(context: Context, words: readonly Words[]): string[];

package/dist/commands/say.js

@@ -0,0 +1,84 @@
+// The talk on the board page (D-51, T-65): a line of the player's or the AI's, saved with the game, and the player's words the AI has not been given yet.
+import { endWithMood } from "../core/index.js";
+import { archiveEnded, endOf, loadGame, loadTableTalk, saveGame, saveTableTalk, talkLimits, talkLine, unheardWords } from "../games/index.js";
+import { gameFolder, helpsIn } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+/**
+ * Adds a line to the talk of the current game, going on or just over, and saves it; the AI's mood once the game is over, which the archive keeps too (D-70).
+ * With no game the line goes in the talk before it (D-77). A line refused changes nothing: it throws, in words for whoever spoke.
+ */
+export function say(folder, who, text, at, mood) {
+    const current = gameAt(folder, at);
+    if (current === undefined) {
+        return sayAtTable(folder, who, text, at, mood);
+    }
+    if (mood !== undefined && endOf(current.game) === undefined) {
+        throw new Error("While the game goes on your mood comes with ai_move: say it without mood. Nothing changed.");
+    }
+    // With the helps on the AI writes as long as the analyst (D-78).
+    current.talk.push(talkLine(current, who, text, at, undefined, aiMost(folder, who, text)));
+    if (mood !== undefined) {
+        endWithMood(current.game, mood);
+    }
+    saveGame(folder, current);
+    if (mood !== undefined) {
+        archiveEnded(folder, current);
+    }
+    return current;
+}
+/** The most a line of the AI's may hold in the games of `folder`: an analyst's note with the helps on (D-78); a longer one with them off is refused. */
+function aiMost(folder, who, text) {
+    if (who !== "ai") {
+        return talkLimits.ai;
+    }
+    if (helpsIn(folder)) {
+        return talkLimits.aiHelps;
+    }
+    if (text.trim().length > talkLimits.ai) {
+        throw new Error(`The player has the helps off: write at most ${talkLimits.ai} characters. Nothing changed.`);
+    }
+    return talkLimits.ai;
+}
+/** What the player wrote on the board page that the AI has not been given in this chat, given now: each game tool gives it once. */
+export function newWords(context) {
+    return give(context, waitingWords(context));
+}
+/** Every word of the player's the AI has not answered, given again: status gives them all, for a chat that lost them in a summary. */
+export function unansweredWords(context) {
+    return give(context, waitingWords(context, new Set()));
+}
+/** What the player wrote on the board page that the AI has not been given in this chat, still to give: the AI's move would count as its answer. */
+export function waitingWords(context, given = context.given) {
+    try {
+        const folder = gameFolder(context.home());
+        return unheardWords(loadGame(folder) ?? loadTableTalk(folder), given);
+    }
+    catch {
+        // A game.json that cannot be read: the tool says so in its own words.
+        return [];
+    }
+}
+/** Gives the words to the AI: from now on they count as given in this chat. Their text. */
+export function give(context, words) {
+    const before = context.given.size;
+    for (const { key } of words) {
+        context.given.add(key);
+    }
+    if (context.given.size > before) {
+        context.heard?.();
+    }
+    return words.map(({ text }) => text);
+}
+/** A line of the talk with no game, which starts it the first time; no mood, which only the end of a game takes. */
+function sayAtTable(folder, who, text, at, mood) {
+    if (who === "agent") {
+        throw new Error("There is no game to think on. Nothing changed.");
+    }
+    if (mood !== undefined) {
+        throw new Error("There is no game: a mood goes with a game's end. Say it without mood. Nothing changed.");
+    }
+    const before = loadTableTalk(folder);
+    const table = { started: before.started === "" ? at.toISOString() : before.started, talk: [...before.talk, talkLine(before, who, text, at, undefined, aiMost(folder, who, text))] };
+    saveTableTalk(folder, table);
+    return table;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { type GameSummary, type Speech } from "./game-summary.ts";
+interface Status {
+    version: string;
+    folder: string;
+    /** The board page's address, where the player plays when the chat serves it. */
+    page?: string;
+    /** No browser has the board page open: the player needs its address first. */
+    pageClosed?: true;
+    /** Who plays, from the profile in use (D-23), once the player has completed it (D-71). */
+    player?: string;
+    /** The player's language when it is not English. */
+    speech?: Speech;
+    game?: GameSummary;
+    /** Why the game on disk cannot be read, when it cannot. */
+    problem?: string;
+    /** What the player wrote on the board page that the AI has not answered yet, all of it (T-65). */
+    words?: string[];
+    /** The game in analysis on the board page once none goes on (D-69), which the player may have brought there (T-92). */
+    analysis?: {
+        game: string;
+        brought?: true;
+    };
+    /** A game going on from before this chat, told once a chat: the player says whether to go on with it. */
+    fromBefore?: true;
+}
+/** What Chesspal sees now, the first call of a chat: a dashboard under 150 tokens while the player is to move, with the next step. */
+export declare const status: import("./registry.ts").Command<z.ZodObject<{}, z.core.$strip>, Status>;
+export {};

package/dist/commands/status.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { archivedName, cleanSince, endOf, gameInAnalysis, lastChatStart } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { version } from "../version.js";
+import { gameAt } from "./clock.js";
+import { closingLines, newGameStep, positionLines, sidesLine, speechLine, speechOf, summaryOf, withThought, wordLines } from "./game-summary.js";
+import { levelText } from "./levels.js";
+import { closedPage, pageGiven, pageLine } from "./page-link.js";
+import { playerLine } from "./profiles.js";
+import { defineCommand } from "./registry.js";
+import { unansweredWords } from "./say.js";
+/** What Chesspal sees now, the first call of a chat: a dashboard under 150 tokens while the player is to move, with the next step. */
+export const status = defineCommand({
+    name: "status",
+    description: "Shows what Chesspal sees now: its version, the profile's folder and the game, with your next step. Call it at the start of every chat, "
+        + "before anything else.",
+    input: z.object({}),
+    // Read only for the host: a flag that has fallen is written, as the time already decided.
+    readOnly: true,
+    alwaysLoad: true,
+    showsGame: true,
+    run: (_input, context) => {
+        // The folder is the profile's, in the data folder (D-71): the names of its games are relative to it.
+        const folder = gameFolder(context.home());
+        const player = playerLine(context);
+        const speech = speechOf(folder, context.language);
+        const status = { version, folder, ...(player === undefined ? {} : { player }), ...(speech === undefined ? {} : { speech }) };
+        if (context.page !== undefined) {
+            status.page = context.page;
+        }
+        if (closedPage(context) !== undefined) {
+            status.pageClosed = true;
+        }
+        const first = firstInChat(context);
+        try {
+            const current = gameAt(folder, context.now());
+            // With no game the player may have written before the first (D-77).
+            const words = unansweredWords(context);
+            if (words.length > 0) {
+                status.words = words;
+            }
+            if (current !== undefined) {
+                status.game = withThought(summaryOf(current, context.now(), archivedName(folder, current)), folder, current);
+                if (status.pageClosed === true) {
+                    pageGiven(context, current.started);
+                }
+                if (first && endOf(current.game) === undefined && fromBeforeChat(context, current.started)) {
+                    status.fromBefore = true;
+                }
+            }
+            const analysis = current === undefined || status.game?.end !== undefined ? gameInAnalysis(folder) : undefined;
+            if (analysis !== undefined) {
+                status.analysis = { game: analysis.game, ...(analysis.brought === true ? { brought: true } : {}) };
+            }
+        }
+        catch (error) {
+            status.problem = error.message;
+        }
+        return status;
+    },
+    format: ({ version, folder, page, pageClosed, player, speech, game, problem, words = [], analysis, fromBefore }) => [
+        `Chesspal ${version}. Folder: ${folder}`,
+        ...(page === undefined ? [] : [pageLine(page, pageClosed === true)]),
+        ...(player === undefined ? [] : [player]),
+        ...(speech === undefined ? [] : [speechLine(speech)]),
+        ...(fromBefore === true ? [fromBeforeLine] : []),
+        ...(problem !== undefined ? [problem] : gameLines(game, words, analysis?.brought === true)),
+        ...(analysis === undefined ? [] : [analysisLine(analysis)]),
+    ].join("\n"),
+});
+// The game going on as a chat starts: the player may have come back for it, or want another.
+const fromBeforeLine = "A game from before this chat is going on: ask the player whether to go on with it. For a new one, " + newGameStep;
+/**
+ * Whether this is the chat's first status: once a chat where the MCP server keeps what it told, again in a chat cleared or summarized, since its start keys
+ * it (D-57); never on the command line.
+ */
+function firstInChat(context) {
+    const key = `game before ${lastChatStart(context.folder)?.at ?? ""}`;
+    if (context.told === undefined || context.told.has(key)) {
+        return false;
+    }
+    context.told.add(key);
+    return true;
+}
+/** Whether a game began before the chat: one a summarized or resumed chat still holds is its own; without the host's word, any game is. */
+function fromBeforeChat(context, started) {
+    const start = lastChatStart(context.folder);
+    return start === undefined || cleanSince(start, started);
+}
+/** The game in analysis; the next step when the player has just brought it on the board page (T-92). */
+function analysisLine({ game, brought }) {
+    return brought === true
+        ? `The player brought ${game} on the board page to analyse it. Next: call analyse_game {"game": "${game}"}, then keep your review on that page with annotate_game, and go over it with them.`
+        : `In analysis on the board page: ${game}; analyse_game {"game": "${game}"} goes over it with the player.`;
+}
+/** The game's lines; a game the player brought to analyse takes the place of the next step (T-92). */
+function gameLines(game, words, brought) {
+    if (game === undefined) {
+        return ["No game.", ...(brought ? wordLines(words) : closingLines(game, words))];
+    }
+    const moves = game.lastMoves === "" ? [] : [`Moves: ${game.lastMoves}`];
+    return [`Game: ${sidesLine(game.ai)}, ${levelText(game.level)}.`, ...moves, ...positionLines(game), ...(brought ? wordLines(words) : closingLines(game, words))];
+}

package/dist/commands/study-games.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** The games kept to study, one line each, the latest kept first. */
+export declare const studyGames: import("./registry.ts").Command<z.ZodObject<{}, z.core.$strip>, {
+    games: string[];
+}>;

package/dist/commands/study-games.js

@@ -0,0 +1,40 @@
+// The games kept to study (D-68): played elsewhere and brought to analyse_game as a PGN, in the folder of the profile that brought them.
+import { z } from "zod";
+import { keptGame, keptGames } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { openingName } from "./opening-book.js";
+import { defineCommand } from "./registry.js";
+import { knownTag } from "./study.js";
+/** The games kept to study, one line each, the latest kept first. */
+export const studyGames = defineCommand({
+    name: "study_games",
+    description: "Lists the games kept to study, which the player brought from elsewhere, the latest kept first: who played, when, "
+        + "the result, the opening, how long, and its name. analyse_game with pgn keeps a game here; analyse_game, look and position take its name as game. "
+        + "Example: study_games {}.",
+    input: z.object({}),
+    readOnly: true,
+    idempotent: true,
+    run: (_input, context) => {
+        const folder = gameFolder(context.home());
+        return { games: keptGames(folder).flatMap((name) => studyLines(folder, name)) };
+    },
+    format: ({ games }) => (games.length === 0 ? "No game kept to study yet: analyse_game with the PGN of a game played elsewhere keeps it here." : games.join("\n")),
+});
+/** Ann vs Bob, 2026.10.01: 1-0, C23 Bishop's Opening, 4 moves. study/2026-11-04-153012.pgn; none for a game that cannot be read. */
+function studyLines(root, name) {
+    let record;
+    try {
+        record = keptGame(root, name);
+    }
+    catch {
+        // A game that cannot be read stays out of the list.
+        return [];
+    }
+    const { tags, moves } = record;
+    const date = knownTag(tags.Date);
+    const result = tags.Result === undefined || tags.Result === "*" ? "result unknown" : tags.Result;
+    const opening = openingName(record);
+    const count = Math.ceil(moves.length / 2);
+    const players = `${tags.White ?? "?"} vs ${tags.Black ?? "?"}${date === undefined ? "" : `, ${date}`}`;
+    return [`${players}: ${result}${opening === undefined ? "" : `, ${opening}`}, ${count} ${count === 1 ? "move" : "moves"}. ${name}`];
+}

package/dist/commands/study.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { Game, type GameRecord } from "../core/index.ts";
+import { type CurrentGame } from "../games/index.ts";
+import type { Context } from "./context.ts";
+/** What look and position take to show any position of a game that is over. */
+export declare const studyInput: {
+    game: z.ZodOptional<z.ZodString>;
+    move: z.ZodOptional<z.ZodString>;
+};
+/** A game to study: its record, and its name in the archive when it is there. */
+export interface Studied {
+    readonly record: GameRecord;
+    readonly name?: string;
+}
+/** A position of a game: the game as it stood after a move, and that move as the analysis writes it (12...Kf8); none at the start. */
+export interface StudiedPosition {
+    readonly game: Game;
+    readonly move?: string;
+}
+/** 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 declare function noGameGoingOn(context: Context): CurrentGame | undefined;
+/** 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 declare function gameToStudy(context: Context, name?: string): Studied;
+/** 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 declare function namedGame(context: Context, name: string): Required<Studied>;
+/** 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 declare function moveIndex(record: GameRecord, move: string): number;
+/** The number of each move of a game as the analysis writes it: 1. for White's first move, 1... for Black's. */
+export declare function moveNumbers(record: GameRecord): string[];
+/**
+ * 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 declare function positionAfter(record: GameRecord, move?: string): StudiedPosition;
+/** A tag PGN leaves unknown with ? or -, as nothing. */
+export declare function knownTag(tag: string | undefined): string | undefined;
+/** Where a position of a game studied stands: After 12...Kf8 in games/2026-11-02-153012.pgn: White to move. */
+export declare function positionLine({ game, move }: StudiedPosition, name?: string): string;