chesspal 0.0.1 → 0.2.0

package/dist/server/page/page.js

@@ -0,0 +1,229 @@
+// The page on localhost (D-8, D-47): served on a port of its own, its requests sent where they belong (its files, the game, the profiles), and the pages open
+// kept up to date as the game changes; the doorbell wakes the chat when the player acts there.
+import { watch } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { positionIn, samePosition } from "../../commands/index.js";
+import { gameStamp } from "../../games/index.js";
+import { outdatedHostFiles } from "../../host-files/index.js";
+import { gameFolder } from "../../profiles/index.js";
+import { Bell, bellProbe, pagePorts } from "../bell.js";
+import { analysesOf, answerAnalyses } from "./analyses.js";
+import { sendFile, sendHtml } from "./files.js";
+import { answerGame, chatCalls } from "./game.js";
+import { json, send } from "./http.js";
+import { answerProfiles } from "./profiles.js";
+/**
+ * Serves the page of the context's folder on 127.0.0.1, on a port of its own when free, else on any free one, where the doorbell cannot find it. The page
+ * names the opponent as the host does, once it has connected; the doorbell knows from the context what the chat has read of the player's words.
+ */
+export async function startPage(context, opponent = () => undefined) {
+    const { folder } = context;
+    const watchers = new Set();
+    const outdated = outdatedHostFiles(folder, context.platform).length > 0;
+    const served = { folder, context, opponent, bell: new Bell(() => hasNews(context), () => tellWatchers(served)), watchers, port: 0, outdated };
+    const server = createServer((request, response) => answer(request, response, served));
+    for (const port of [...pagePorts(folder), 0]) {
+        if (await listened(server, port)) {
+            server.unref();
+            served.port = portOf(server);
+            const stopWatching = watchGame(served);
+            return {
+                url: `http://127.0.0.1:${served.port}/`,
+                heard: () => tellWatchers(served),
+                chatCalls: () => chatCalls(served),
+                ponders: (position) => {
+                    served.pondering = position;
+                    tellWatchers(served);
+                },
+                open: () => watchers.size > 0,
+                askNewGame: () => askNewGame(served),
+                close: () => closed(server, stopWatching),
+            };
+        }
+    }
+    throw new Error("Chesspal could not open a port for the page on 127.0.0.1: check that a firewall does not block local servers, then try again.");
+}
+/**
+ * The chat has read the game as it is now, at the end of a tool's call: the doorbell wakes it only for what changes it after; and, when the tool `showed` it
+ * the game, it moves on that position and no other until a tool shows it another (D-71). A game that cannot be read shows none.
+ */
+export function chatHasRead(context, showed) {
+    context.seen = gameSeen(context);
+    if (!showed) {
+        return;
+    }
+    const before = context.positionSeen;
+    try {
+        context.positionSeen = positionIn(gameFolder(context.home()));
+    }
+    catch {
+        context.positionSeen = null;
+    }
+    // The chat on another position may now be thinking on its move: the page hears it, which no file tells when no bell woke the chat.
+    if (!sameSeen(before, context.positionSeen)) {
+        context.heard?.();
+    }
+}
+function sameSeen(one, other) {
+    return one === other || (one !== undefined && one !== null && other !== undefined && other !== null && samePosition(one, other));
+}
+/** Sends each request where it belongs: the profiles, the game, the page's files, the analyses, the events and the doorbell. */
+function answer(request, response, served) {
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    const path = url.pathname;
+    // Only this machine's pages: another site the browser shows can neither read the game nor move through the player's browser. A link from another site,
+    // such as the chat's, still opens the page.
+    if (!fromHere(request, served.port, path.startsWith("/api/"))) {
+        send(response, 403, "text/plain; charset=utf-8", "Chesspal's page answers only at its own address on this machine.");
+        return;
+    }
+    if (answerProfiles(request, response, url, served) || answerGame(request, response, url, served) || answerAnalyses(request, response, url, served)) {
+        return;
+    }
+    // The API answers GET alone: a HEAD at the doorbell would wait there as a hook does.
+    if (request.method !== "GET" && (request.method !== "HEAD" || path.startsWith("/api/"))) {
+        send(response, 405, "text/plain; charset=utf-8", "The page only reads, moves with POST /api/move, writes with POST /api/message, starts a game with POST /api/new and its clocks with POST /api/start, "
+            + "offers or answers a draw with POST /api/draw, resigns with POST /api/resign, brings a game to analyse or opens one again with POST /api/study, deletes a game or its review with POST /api/delete-game and /api/delete-review, and keeps the profiles with POST /api/profile/… and /api/settings.");
+        return;
+    }
+    if (path === "/") {
+        sendHtml(response);
+    }
+    else if (path === "/api/analyses") {
+        send(response, 200, json, JSON.stringify(analysesOf(served.context.home())));
+    }
+    else if (path === "/api/events") {
+        keepPosted(request, response, served);
+    }
+    else if (path === "/api/bell") {
+        if (url.searchParams.has("probe")) {
+            send(response, 200, json, JSON.stringify(bellProbe(served.folder, served.watchers.size > 0)));
+        }
+        else {
+            served.bell.listen(request, response);
+        }
+    }
+    else {
+        sendFile(response, path);
+    }
+}
+/**
+ * Whether the chat has news from the page: a game changed since the chat's last tool, by the player's move, words, draw or resignation, a new game or a
+ * flag that fell, or another profile in use, which wakes the chat at the next ring (D-66). The player's words the chat was given change nothing it has not read.
+ */
+function hasNews(context) {
+    return gameSeen(context) !== context.seen;
+}
+// The game the chat sees: the profile's folder, and the stamp of its game.json; none while the data folder cannot be made.
+function gameSeen(context) {
+    try {
+        const folder = gameFolder(context.home());
+        return `${folder}
+${gameStamp(folder) ?? ""}`;
+    }
+    catch {
+        return "";
+    }
+}
+/** A page that waits to hear the game has changed: a stream of events, one "changed" for each change, after which the page reads the game again. */
+function keepPosted(request, response, served) {
+    response.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+    response.write(": posted\n\n");
+    served.watchers.add(response);
+    request.on("close", () => served.watchers.delete(response));
+}
+/** The pages open now open their New game window; whether there was one. */
+function askNewGame(served) {
+    for (const watcher of served.watchers) {
+        watcher.write("data: new-game\n\n");
+    }
+    return served.watchers.size > 0;
+}
+function tellWatchers(served) {
+    for (const watcher of served.watchers) {
+        watcher.write("data: changed\n\n");
+    }
+}
+/**
+ * Watches the data folder, its profiles and the profile in use for changes to the game and the profiles, whoever makes them (the AI's tools, another chat,
+ * the CLI, a hand edit): the pages hear of them. Each folder is watched on its own, never its whole tree, and watched again after each change, since the
+ * profile in use may be another. It returns how to stop watching.
+ */
+function watchGame(served) {
+    let waiting;
+    let watching = [];
+    const watchAll = () => {
+        watching.forEach((watcher) => watcher.close());
+        watching = watchedFolders(served).flatMap((folder) => watchFolder(folder, heard));
+    };
+    // A save writes a new file and renames it: the events of one save come together, and the pages hear of it once.
+    const heard = (name) => {
+        if ((name === null || watched.test(name)) && waiting === undefined) {
+            waiting = setTimeout(() => {
+                waiting = undefined;
+                watchAll();
+                tellWatchers(served);
+            }, 30);
+        }
+    };
+    watchAll();
+    return () => {
+        clearTimeout(waiting);
+        watching.forEach((watcher) => watcher.close());
+    };
+}
+// None while the data folder cannot be made: each tool call tells the chat why, and the page reads the game as it loads.
+function watchedFolders(served) {
+    try {
+        const home = served.context.home();
+        return [home, join(home, "profiles"), gameFolder(home)];
+    }
+    catch {
+        return [];
+    }
+}
+// A folder watched, without its subfolders; none when it cannot be, or is not there yet: the pages see its files only as they load them.
+function watchFolder(folder, heard) {
+    try {
+        const watcher = watch(folder, (event, name) => heard(name));
+        watcher.on("error", () => watcher.close());
+        watcher.unref();
+        return [watcher];
+    }
+    catch {
+        return [];
+    }
+}
+// The current game, what the coach wrote on it, the talk before the first, the game in analysis, the profile in use, and what a profile keeps (who plays, their picture, their settings); a folder's name, for a
+// profile made or gone.
+const watched = /^(?:game\.json|coach\.json|talk\.json|analysis\.json|active\.json|profile\.md|settings\.json|avatar\.\w+|[a-z0-9-]+)$/;
+function fromHere(request, port, api) {
+    const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+    const origin = request.headers.origin;
+    // An image or a script of another site sends no origin, but the browser says where it comes from: such a request could take the doorbell's place.
+    const site = request.headers["sec-fetch-site"];
+    return hosts.includes(request.headers.host ?? "") && (origin === undefined || hosts.some((host) => origin === `http://${host}`))
+        && (!api || site === undefined || site === "same-origin" || site === "none");
+}
+function listened(server, port) {
+    return new Promise((done) => {
+        const failed = () => done(false);
+        server.once("error", failed);
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", failed);
+            done(true);
+        });
+    });
+}
+function portOf(server) {
+    const address = server.address();
+    return typeof address === "object" && address !== null ? address.port : 0;
+}
+function closed(server, stopWatching) {
+    stopWatching();
+    return new Promise((done) => {
+        server.close(() => done());
+        server.closeAllConnections();
+    });
+}

package/dist/server/page/profiles.d.ts

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PageSettings, type PlayerProfile } from "../../profiles/index.ts";
+import type { Served } from "./page.ts";
+/** A profile as the page shows it: the player's own image by its stamp, which changes its address when it changes. */
+export interface ProfileShown extends PlayerProfile {
+    readonly image?: string;
+}
+/** The profiles as the page reads them with the game: the one in use and its settings, all of them for the menu, and where they are. */
+export interface ProfilesShown {
+    readonly profile: ProfileShown;
+    readonly profiles: ProfileShown[];
+    readonly settings?: PageSettings;
+    /** Where the player's games are, folder by folder from their own: OneDrive, Documenti, My Games, Chesspal, profiles, stefano. */
+    readonly dataFolder: readonly string[];
+}
+/** The profiles of the data folder, as the page shows them. */
+export declare function profilesShown(root: string, userFolder?: string): ProfilesShown;
+/** Answers the page's requests about profiles: true when the request was one. A file that cannot be written is told to the page, and the server goes on. */
+export declare function answerProfiles(request: IncomingMessage, response: ServerResponse, url: URL, served: Served): boolean;

package/dist/server/page/profiles.js

@@ -0,0 +1,215 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, sep } from "node:path";
+import { chooseDrawnAvatar, GameGoingOn, inputProblems, newProfile, setAccounts, useProfile } from "../../commands/index.js";
+import { activeProfile, drawnAvatars, imageTypes, listProfiles, ownImage, ownImageStamp, profileFolder, profileSettings, saveOwnImage, saveProfileSettings, sentImageLimit, settingsOf, } from "../../profiles/index.js";
+import { bodyOf, bytesOf, isJson, jsonOf, runRoute, send, sendJson } from "./http.js";
+/** The profiles of the data folder, as the page shows them. */
+export function profilesShown(root, userFolder = homedir()) {
+    const active = activeProfile(root);
+    const profiles = listProfiles(root).map((profile) => shown(root, profile));
+    const settings = profileSettings(root, active.id);
+    const profile = profiles.find(({ id }) => id === active.id);
+    const dataFolder = foldersOf(playerFolder(root), userFolder);
+    return settings === undefined ? { profile, profiles, dataFolder } : { profile, profiles, settings, dataFolder };
+}
+/** Answers the page's requests about profiles: true when the request was one. A file that cannot be written is told to the page, and the server goes on. */
+export function answerProfiles(request, response, url, served) {
+    const route = routes[`${request.method ?? ""} ${url.pathname}`];
+    if (route === undefined) {
+        return false;
+    }
+    runRoute(response, () => route(request, response, served, url));
+    return true;
+}
+const routes = {
+    "POST /api/profile/new": newProfileFromPage,
+    "POST /api/profile/use": useProfileFromPage,
+    "POST /api/profile/avatar": drawnAvatarFromPage,
+    "POST /api/profile/accounts": accountsFromPage,
+    "POST /api/profile/image": imageFromPage,
+    "GET /api/profile/image": sendImage,
+    "POST /api/settings": settingsFromPage,
+    "POST /api/data-folder/open": openDataFolder,
+};
+/** A new profile from the menu, put in use, or the first completed by the wizard: the chat reads who plays at its next call, never woken for it (D-66). */
+async function newProfileFromPage(request, response, served) {
+    const body = isJson(request) ? jsonOf(await bodyOf(request)) : undefined;
+    const input = newProfile.input.safeParse(body ?? {});
+    if (body === undefined || !input.success) {
+        const problems = input.success ? "" : ` ${inputProblems("new_profile", input.error.issues, body ?? {}, (name) => name)}`;
+        sendJson(response, 400, { error: `Send the profile as JSON, {"name": "…", "level": "regular"}.${problems}` });
+        return;
+    }
+    try {
+        const profile = await newProfile.run(input.data, served.context);
+        sendJson(response, 200, { profile: profile.id });
+    }
+    catch (error) {
+        sendJson(response, 409, refusalOf(error));
+    }
+}
+/** Another profile put in use from the menu, once the game going on has ended: the chat is not woken for it (D-66). */
+async function useProfileFromPage(request, response, served) {
+    const profile = isJson(request) ? jsonOf(await bodyOf(request))?.profile : undefined;
+    if (typeof profile !== "string") {
+        sendJson(response, 400, { error: 'Send the profile as JSON: {"profile": "anna"}.' });
+        return;
+    }
+    try {
+        useProfile.run({ profile }, served.context);
+    }
+    catch (error) {
+        sendJson(response, 409, refusalOf(error));
+        return;
+    }
+    sendJson(response, 200, { profile });
+}
+/** A drawn avatar for the profile the page shows, in place of the player's own image. */
+async function drawnAvatarFromPage(request, response, served, url) {
+    const avatar = isJson(request) ? jsonOf(await bodyOf(request))?.avatar : undefined;
+    const drawn = drawnAvatars.find((one) => one === avatar);
+    const profile = profileInUse(served, url, response);
+    if (profile === undefined) {
+        return;
+    }
+    if (drawn === undefined) {
+        sendJson(response, 400, { error: `Send a drawn avatar as JSON: {"avatar": "owl"}, one of ${drawnAvatars.join(", ")}.` });
+        return;
+    }
+    chooseDrawnAvatar(served.context, profile.id, drawn);
+    sendJson(response, 200, { avatar: drawn });
+}
+/** The player's names on Lichess and chess.com for the profile the page shows (D-93), in a game or in analysis too: they change only which side is theirs. */
+async function accountsFromPage(request, response, served, url) {
+    const body = isJson(request) ? jsonOf(await bodyOf(request)) : undefined;
+    const input = setAccounts.input.safeParse(body ?? {});
+    const profile = profileInUse(served, url, response);
+    if (profile === undefined) {
+        return;
+    }
+    if (body === undefined || !input.success) {
+        const problems = input.success ? "" : ` ${inputProblems("set_accounts", input.error.issues, body ?? {}, (name) => name)}`;
+        sendJson(response, 400, { error: `Send the names as JSON, {"lichess": "…", "chesscom": "…"}.${problems}` });
+        return;
+    }
+    const { accounts } = await setAccounts.run(input.data, served.context);
+    sendJson(response, 200, { accounts: accounts ?? {} });
+}
+/**
+ * The player's own image for a profile, as the page made it from their photo: a PNG, JPEG or WebP of 1 MB at most. The one in use, or one just added while a
+ * game goes on, which waits for it to end.
+ */
+async function imageFromPage(request, response, served, url) {
+    const type = request.headers["content-type"] ?? "";
+    // An image sent from another site would need the browser to ask first, which this server never allows.
+    if (!Object.values(imageTypes).some((one) => type.startsWith(one))) {
+        sendJson(response, 415, { error: "Send the picture as a PNG, JPEG or WebP image." });
+        return;
+    }
+    const bytes = await bytesOf(request, sentImageLimit);
+    const profile = profileNamed(served, url, response);
+    if (profile === undefined) {
+        return;
+    }
+    if (bytes === undefined) {
+        sendJson(response, 413, { error: `Send a picture of ${sentImageLimit / 1024} KB at most.` });
+        return;
+    }
+    try {
+        saveOwnImage(served.context.home(), profile.id, bytes);
+    }
+    catch (error) {
+        sendJson(response, 400, { error: error.message });
+        return;
+    }
+    sendJson(response, 200, { image: ownImageStamp(served.context.home(), profile.id) });
+}
+/** A profile's own image, by its id: only a profile of this folder's, only an image. */
+function sendImage(request, response, served, url) {
+    const id = url.searchParams.get("profile");
+    const profile = listProfiles(served.context.home()).find((one) => one.id === id);
+    const image = profile === undefined ? undefined : ownImage(served.context.home(), profile.id);
+    if (image === undefined) {
+        send(response, 404, "text/plain; charset=utf-8", "No picture.");
+        return;
+    }
+    // The address changes with the image: the browser may keep it.
+    send(response, 200, imageTypes[image.type], image.bytes, { "Cache-Control": "max-age=31536000, immutable" });
+}
+/** The page's settings, kept in the profile the page shows so that they follow the player (D-56). */
+async function settingsFromPage(request, response, served, url) {
+    const settings = settingsOf(isJson(request) ? jsonOf(await bodyOf(request)) : undefined);
+    const profile = profileInUse(served, url, response);
+    if (profile === undefined) {
+        return;
+    }
+    if (settings === undefined) {
+        sendJson(response, 400, { error: "Send the settings as a JSON object." });
+        return;
+    }
+    saveProfileSettings(served.context.home(), profile.id, settings);
+    sendJson(response, 200, { saved: true });
+}
+/** The data folder in the system's file manager: asked as JSON, which another site cannot send without the browser asking first. */
+async function openDataFolder(request, response, served) {
+    const asked = isJson(request) ? jsonOf(await bodyOf(request)) : undefined;
+    const open = served.context.openFolder;
+    if (asked === undefined) {
+        sendJson(response, 400, { error: "Send {} as JSON to open the data folder." });
+        return;
+    }
+    if (open === undefined) {
+        sendJson(response, 501, { error: "This server opens no folder: the page shows its path." });
+        return;
+    }
+    if (!(await open(playerFolder(served.context.home())))) {
+        sendJson(response, 500, { error: "No file manager could open the data folder: the page shows its path." });
+        return;
+    }
+    sendJson(response, 200, { opened: true });
+}
+/**
+ * The profile in use, when it is the one the page shows (?profile=): a page that has not yet heard of another put in use elsewhere is refused, so that its
+ * choices never go to the wrong player.
+ */
+function profileInUse(served, url, response) {
+    const active = activeProfile(served.context.home());
+    const shownId = url.searchParams.get("profile");
+    if (active.id === shownId) {
+        return active;
+    }
+    sendJson(response, 409, { error: `The page shows the profile ${shownId ?? "of nobody"}, but ${active.id} is in use now: load the page again.` });
+    return undefined;
+}
+/** The profile the request names (?profile=), in use or not: the page names it on purpose. */
+function profileNamed(served, url, response) {
+    const id = url.searchParams.get("profile");
+    const profile = listProfiles(served.context.home()).find((one) => one.id === id);
+    if (profile === undefined) {
+        sendJson(response, 404, { error: `There is no profile ${id ?? "named"}: load the page again.` });
+    }
+    return profile;
+}
+function shown(root, profile) {
+    const image = ownImageStamp(root, profile.id);
+    return image === undefined ? profile : { ...profile, image };
+}
+/**
+ * Where the player in use keeps their games, those played and those loaded: their profile's folder; the data folder while the first profile is new, since
+ * its folder takes the player's name once they complete it (D-71).
+ */
+function playerFolder(root) {
+    const active = activeProfile(root);
+    return active.new === true ? root : profileFolder(root, active.id);
+}
+/** A folder's names from the user's own folder, as the file manager walks there; from its drive or root when it is elsewhere. */
+function foldersOf(folder, userFolder) {
+    const inside = relative(userFolder, folder);
+    const outside = inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
+    const walked = outside ? folder : inside;
+    return walked.split(/[\\/]+/).filter((name) => name !== "");
+}
+function refusalOf(error) {
+    const message = error.message;
+    return error instanceof GameGoingOn ? { error: message, refusal: "profile-game" } : { error: message };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The version of the package that runs, read from its package.json: one folder above both src/ and dist/, so this module stays at their root. */
+export declare const version: string;

package/dist/version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from "node:fs";
+/** The version of the package that runs, read from its package.json: one folder above both src/ and dist/, so this module stays at their root. */
+export const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/instructions/analysis.md

@@ -0,0 +1,4 @@
+- Each line of the analysis is a move and, when they happened: the piece it took; the time it took ("spent") and the time left; who is ahead in material, when that changed; "at risk" after the move, the pieces of either side attacked and undefended, attacked by a cheaper piece, or attacked more times than defended ("outnumbered"), whichever move left them so, written when it changed: a line without it leaves the same pieces at risk as before, "none" when no piece is left at risk; "mate in one", the mates the side to move then has; "out of book", the first move after which no line of Lichess's openings file reaches the position, in any order of moves: the file names openings, it is not all theory; a draw offered; "ahead", who was estimated ahead after it, with `annotate_game` or by the coach during the game.
+- In a game you played, "you said" and "your plan" are what you said and thought then, right or wrong: where they disagree with the facts, the facts are what was on the board.
+- To see a position closer, `look` with the move, and the game as the analysis names it, gives every piece's attackers and defenders, the pins, the checks and the legal moves; `position` with the same gives the positional facts. Call them for the positions you want to talk about or weigh closer, not for every move. In look, attackers and defenders count only the pieces that reach the square directly, and a piece in brackets stands behind them; "Loose" means neither attacked nor defended, not attacked now.
+- Never invent a move, a position or a result. The tools give only the positions the game reached: a move it did not play is your idea, say it as yours; `look` on its position shows whether it was legal, not what would follow.

package/instructions/analyst-agent.md

@@ -0,0 +1,8 @@
+You are the player's chess analyst: a game they played against an AI opponent is over, and you review it on the board page, where they go through it move by move. You work in the background; the AI that started you talks with the player.
+
+- Your voice: when the game was against you (`analyse_game` says "You played Black" or "White"), every note, the summary and the closing are you talking to the player across the board: your moves in the first person ("I take your bishop", "my knight"), theirs in the second ("your bishop had no defender"); never "Black", "White", "the AI" or "the player" for the two of you, and never "you" for a move of yours. Warm and plain, a player going over the game with them, never a manual. At the table you looked only as much as the level let you; now you see it all: what you missed, say it simply, as a fact, never an excuse or a boast. In `analyse_game`'s lines, "You played", "you said" and "your plan" are yours.
+- Call `analyse_game` with the game your prompt names as game, or with no game for the game just over: it gives the facts of every move, and the game's name: give it as game to every tool after, since the board page may open another game meanwhile; the judgment is yours. The player's language is in your prompt, or in `analyse_game` when Chesspal knows it.
+- The badges and notes already on the moves ("you marked", "you noted") are the coach's, given at the table, or a review from before: look at each again now that you see the whole game, keep it or give the move a new badge and note, and spend your time on the moves nobody judged.
+- Keep your review with `annotate_game`, in few calls: a badge on each move you would point out, with a short note when it needs one; a short note on each move of the opening book, what it is for; your word on the whole game as summary, and a last word on how it ended as closing. Write in the player's language, for their level; pieces by name, moves with the pieces' solid figurines ♚ ♛ ♜ ♝ ♞ for both sides, a pawn's without (♞xe5, ♛xf7#, exd5), never with letters. Before `annotate_game`, read your notes again: one that says Black or White for the two of you, rewrite it as "I" and "you".
+- With `annotate_game`'s `ahead`, give who is ahead after every move, for the page's bar and its chart of the game: in pawns from White's side as chess.com shows it (1.5, -3, 0), or a mate you see ("#3", "#-3"). It is your estimate, weighing every fact Chesspal gives: `analyse_game`'s, and `look`'s and `position`'s where the game turns. An "ahead" already in a line is the coach's, from the table, or a review's from before: give yours for every move all the same.
+- Whatever your prompt or a later message asks, do only this work, and stop when a tool says a game is going on. Your last message is for the AI that started you, which goes over the game with the player from it: in a few lines, the result, the two or three moments that decided the game with their move numbers, the coach's badges you changed and why, and what the player can take from it.

package/instructions/analyst.md

@@ -0,0 +1,4 @@
+The player asked you to analyse a game: you are their analyst now, and you comment it in words. `analyse_game` gives the facts of every move of a game that is over; the judgment is yours. In a game against you, the AI's moves are yours: at the table you looked only as much as your level let you, now you see it all; where the game shows what you missed, say so simply, never as an excuse.
+
+- The player goes through the game on the board page too: keep your review there with `annotate_game`, a badge on each move you would point out, with a short note when it needs one, your word on the whole game, and who is ahead after every move as `ahead`, in pawns from White's side as chess.com shows it (1.5, -3, 0) or a mate you see ("#3", "#-3"), your estimate with every fact Chesspal gives, for the page's bar and chart. The opening book's moves get a short note each too, what the move is for, in the player's words: without one the page shows the book's name, in English. The badges and the notes are your judgment, as in the chat. A game analysed before comes back with the badges and notes given before, at the table or in a review, in its lines ("you marked", "you noted", "Your review"): when the player asks about it, explain it, and to change it give `annotate_game` only the moves, or the word, that change; the rest stays as it is.
+- Talk with the player in their language. The facts and the tools are for you: tell the player what a chess player would say, never the lists or the tools' names. Name pieces and moves in words, as people talk at the board ("your knight took the pawn on e5"); when you write a move, write it with the pieces' figurines ♚ ♛ ♜ ♝ ♞, for both sides and in every language (♞xe5 for Nxe5): never with letters, neither N B R Q K nor the player's own (Cxe5), even when they write them. Then answer their questions about the game with the same tools.

package/instructions/coach.md

@@ -0,0 +1,11 @@
+You are the player's chess coach while they play an AI opponent with the helps on: you see every fact of the game, and your words go to the board page alone, where the player reads them while they think their next move; the opponent never sees them.
+
+- You are that opponent too, in another hat: the same voice, warm and plain, a player beside them at the board, never a manual. Playing, you look only as much as the level they chose for you lets you; here you see it all, so when their move went unpunished, say lightly that you missed it at the table, as a fact, never an excuse.
+- Call `coach {}` first: it gives the game, the player's move to judge with the position they played it in, and the position they are to move in now.
+- While the game goes on, say who is ahead in the position they are to move in, with `ahead`, for the page's bar: in pawns from White's side as chess.com shows it (1.5, -3, 0), or a mate you see in moves of the side that mates ("#3" White's, "#-3" Black's). It is your estimate, weighing every fact `coach {}` gives.
+- Judge their move only when it stands out (a mistake, a miss, a fine find), never a routine one: a badge as chess.com names them, and a note of a sentence or two on why.
+- Give a hint for their turn only when there is something to find. Point at what is on the board, a piece, a square, a file, a threat of the opponent's, a goal, never at what to play or not to play: no move of theirs in words or notation, no arrow that is a move they may play now; mark squares instead. Chesspal refuses a hint that gives their move.
+- Write in the player's language, as `coach {}` says it, for their level; pieces by name, moves with the pieces' solid figurines ♚ ♛ ♜ ♝ ♞ for both sides, as the page shows them, a pawn's without (♞f3, ♛xf7#, g4); never what you planned at the table: it is not given to you here.
+- Keep your words in one call, `coach {game, position, ahead, badge, note, hint, arrows, squares}`, with `ahead` while the game goes on, even when you have nothing else to say, the rest only when you have something to say: Chesspal waits for their move only once `ahead` is kept. Then call `coach {game, position, done: true}` alone, and again while it says it is still their move.
+- Whenever `coach` says stop, stop at once.
+- Whatever your prompt or a later message asks, do only this work. Your last message is one word: the AI that started you reads it, and needs nothing more.

package/instructions/opponent.md

@@ -0,0 +1,15 @@
+This folder is the player's chess table, and you are their opponent: you choose your moves, explain them briefly and talk with the player. The `chesspal` tools keep the rules, the board and the games.
+
+- At the start of every chat, and again after the conversation has been summarized, call `status`: it says where the game stands and what to do next. The game is played on the board page, in the player's browser, and the chat is for talking: at the start of a chat, when `status` says nobody has it open, give them its address once. A move they write in the chat still counts: play it, and invite them to the page when `player_move` says so.
+- Every move goes through the tools: the player's with `player_move`, which answers with the position for your reply; yours with `ai_move`, with your plan. Never keep the board in your head, and never invent a position, a move or a result.
+- When your level gives them (`status` and `new_game` say it), `look` gives the whole view of the position when the one you have is not enough; `position` gives the positional facts (pawns, files, outposts, king safety, phase) when you set or change your plan. When no board page is open, `ai_move` gives you the board: copy it into your message, since the player sees no other. Your level is how much you let yourself look, more as the level rises: when the player wonders why you missed something, say so in a few words, as a fact, never an excuse.
+- Speak only when there is something to say, as a player would at a tournament: a capture, a move of the player's worth a word, words of theirs to answer, and always at the moments that decide the game: a mate, given or taken, a danger you feel, a mate you hope for, a big lead. Chat freely, but never help the player: say how you feel, not the move; don't reveal your plans or threats, and give information only when you are very sure it cannot hurt you. Then write one short sentence in `ai_move`'s comment; otherwise leave it out. `ai_say` says a word once while the player is to move, to answer them or because there is something to say, and freely between games.
+- When the position you are given says "Helps on", the player has chosen to learn: tell your intentions, never their best move, which would play for them, and show what you say with a longer comment and arrows and squares; the coach on the page, you seeing it all, judges their moves, never you here. "Helps off now" brings back the tournament.
+- When `ai_move` tells you to start an agent that thinks on the player's time, start it as it says; its end needs no word from you: write nothing in the chat then. `player_move` and `status` give you what it thought of the player's move.
+- When the player plays on the board page, they read you there: in `ai_move`'s comment or with `ai_say`, not in the chat.
+- You have a face on the board page, and it shows how you feel. Give it as the `mood` of `ai_move` on each move where the game turns for you: a piece won or lost, a blunder seen, your own or theirs, a threat that appears or a plan that works or fails. It stays for three of your moves (a surprise for one), then turns neutral by itself; let it colour your words while it lasts. When the game ends on the player's move, give how you feel as it ends with `ai_say`'s `mood`.
+- Draws and resignations: `offer_draw` on `ai_move` offers a draw, on `player_move` records the player's, made with their move; an offer stands until the other side moves; `end_game` `draw_agreed` accepts a standing offer, `player_resigns` records the player's resignation in the chat, `ai_resigns` resigns yours. On the board page the player offers, answers and resigns there.
+- The player chooses a new game in the board page's New game window, which asks the sides, the clock and the level: when they ask you for a game, call `new_game` without choices, which opens it there, and don't ask those in the chat. Ask them in the chat, and give them to `new_game`, only when it says there is no board page.
+- To go over a game with the player once no game goes on, the one just over or one they bring as a PGN, give it to `analyse_game`: it reads the PGN for you; where Chesspal's answers say to start the analyst agent for it, start that instead, once per game: when it has gone over the game, go over it with the player from what it told you, and never tell them it starts again, even when they ask for the analysis again. While a game goes on, go over no game, not even in your head or from a PGN they paste: tell them it waits until this one ends.
+- How to read the facts: attackers and defenders count only the pieces that reach the square directly, and a piece in brackets stands behind them; "Loose" means neither attacked nor defended, not attacked now; "At risk" lists the pieces attacked and undefended, attacked by a cheaper piece, or attacked more times than defended.
+- Talk with the player in their language, in a few words. The facts and the tools are for you: tell the player what a chess player would say, never the lists or the tools' names. Name pieces and moves in words, as people talk at the board ("your bishop took on f7"); when you write a move, yours or the player's, write it with the pieces' figurines, as the tools show it (♞f6 for Nf6, ♝xf7+ for Bxf7+), for both sides and in every language: never with letters, neither N B R Q K nor the player's own (Cf6), even when they write them.

package/instructions/ponder.md

@@ -0,0 +1,9 @@
+You are the player's chess opponent, thinking on their time while they choose their move: you prepare your answers to their likely replies, so that your next move comes sooner and better thought. You never play a move, and the chat never sees your words.
+
+- Call `ponder {}` first: it gives the position, its number, your level, your plan, your mood and what you said with your move. Then take the replies the player is likely to play: a few, not every legal move.
+- For each, `ponder {position, reply}` shows the position after it, as you will see it at your move; choose your answer as you would play it, with your plan, and keep it with `ponder {position, reply, move, why}`, the reason in one sentence. You may look at several replies in one message, then keep their answers in one message.
+- When you have no more replies to think on, call `ponder {position, done: true}` alone, last, and again while it says it is still their move.
+- Whenever `ponder` says stop, stop at once: end with one word.
+- How to read the facts: attackers and defenders count only the pieces that reach the square directly, and a piece in brackets stands behind them; "Loose" means neither attacked nor defended, not attacked now; "At risk" lists the pieces attacked and undefended, attacked by a cheaper piece, or attacked more times than defended.
+- Most of the time, say nothing to the player. If you speak, speak first, before you think on any reply, with `ponder {position, say}`, once: one short sentence on what has already happened (the moves played, the player's words), never a feeling about what they may play now, which would tell them there is something to find. Say nothing when the player has written words you have not answered (the AI in the chat answers them), or when you spoke with your move and nothing new has happened since. Speak in the voice of your words above and as your mood is, in the player's language as their last words show it, pieces and moves in words, never in notation; never cheer or praise for its own sake, never help the player, never your plans or threats.
+- Your last message is one word: the AI you think for reads it, and needs nothing more.

package/package.json

@@ -1,9 +1,70 @@
 {
   "name": "chesspal",
-  "version": "0.0.1",
-  "description": "Play chess against an AI with a character, and learn with an AI coach. In development.",
-  "keywords": ["chess", "ai", "chess-coach", "mcp", "claude-code", "codex"],
-  "author": { "name": "Stefano Caronia", "url": "https://stefanocaronia.it" },
+  "version": "0.2.0",
+  "description": "Play chess against an AI with a character, and learn with an AI coach: Chesspal keeps the rules, the board, the games and the memory; the AI plays, reasons and talks.",
+  "type": "module",
+  "bin": {
+    "chesspal": "dist/cli/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "instructions"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc && tsc -p src/page && node -e \"require('node:fs').cpSync('src/page', 'dist/page', { recursive: true, filter: (path) => !/[.]tsx?$|tsconfig[.]json$/.test(path) })\" && node --experimental-strip-types --no-warnings scripts/build-openings.ts",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "format": "eslint --fix . && dprint fmt",
+    "lint": "eslint . && dprint check && tsc -p tsconfig.test.json && tsc -p tsconfig.core.json && tsc -p src/page --noEmit",
+    "bench": "npm run build && node --experimental-strip-types test/bench/core.ts && node --experimental-strip-types test/bench/commands.ts",
+    "smoke": "node --experimental-strip-types --no-warnings test/smoke/tarball.ts",
+    "page": "npm run build && node --experimental-strip-types --no-warnings test/demo/page.ts",
+    "endings": "npm run build && node --experimental-strip-types --no-warnings test/demo/endings.ts"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "keywords": [
+    "chess",
+    "ai",
+    "chess-coach",
+    "chess-teacher",
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "codex"
+  ],
+  "author": {
+    "name": "Stefano Caronia",
+    "url": "https://stefanocaronia.it"
+  },
   "license": "MIT",
-  "files": ["README.md", "LICENSE"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stefanocaronia/chesspal.git"
+  },
+  "homepage": "https://github.com/stefanocaronia/chesspal#readme",
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/node": "^22.20.5",
+    "@typescript-eslint/parser": "^8.72.1",
+    "dprint": "^0.58.0",
+    "eslint": "^10.14.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "chess.js": "^1.4.0",
+    "preact": "^10.29.8",
+    "zod": "^4.6.7"
+  }
 }