chesspal 0.0.1 → 0.1.0

package/dist/server/profile-routes.js

@@ -0,0 +1,186 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, sep } from "node:path";
+import { chooseDrawnAvatar, GameGoingOn, newProfile, useProfile } from "../commands/profiles.js";
+import { inputProblems } from "../commands/registry.js";
+import { activeProfile, drawnAvatars, imageTypes, listProfiles, ownImage, ownImageStamp, profileSettings, saveOwnImage, saveProfileSettings, sentImageLimit, settingsOf } from "../profiles/index.js";
+import { bodyOf, bytesOf, isJson, jsonOf, 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(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;
+    }
+    Promise.resolve().then(() => route(request, response, served, url)).catch((error) => {
+        if (response.headersSent) {
+            response.end();
+        }
+        else {
+            sendJson(response, 500, { error: error.message });
+        }
+    });
+    return true;
+}
+const routes = {
+    "POST /api/profile/new": newProfileFromPage,
+    "POST /api/profile/use": useProfileFromPage,
+    "POST /api/profile/avatar": drawnAvatarFromPage,
+    "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 own image for the profile the page shows, as the page made it from their photo: a PNG, JPEG or WebP of 1 MB at most. */
+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 = profileInUse(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 (T-119): 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(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;
+}
+function shown(root, profile) {
+    const image = ownImageStamp(root, profile.id);
+    return image === undefined ? profile : { ...profile, image };
+}
+/** 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/analyst.md

@@ -0,0 +1,8 @@
+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.
+
+- 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.
+- 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, 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.
+- 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, and your word on the whole game. 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 your 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). Then answer their questions about the game with the same tools.

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.
+- 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; after their move, judge it with `ai_move`'s `badge` and `note` when it stands out, and show what you say with a longer comment and arrows and squares. "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. 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, write it with the pieces' figurines, as the tools show it (♝xf7+ for Bxf7+), for both sides and in every language.

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.1.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"
+  }
 }