chesspal 0.1.0 → 0.2.1

package/dist/server/page/game.js

@@ -0,0 +1,381 @@
+import { analyseGame, answerDraw, bookPlies, ChatNotClear, DrawRefused, endGame, gameAt, gameToStudy, namedGame, newGame, offerDraw, playMove, samePosition, say, startNewGame, } from "../../commands/index.js";
+import { clockStarted, isReviewed, writePgn } from "../../core/index.js";
+import { aiModelOf, archiveName, coachShown, coachWords, drawOfferOf, endOf, gameInAnalysis, heardLines, loadGame, loadTableTalk, playerPgn, saveGame, startAnalysis, talkLimits, wakesTheChat, WordsRefused, } from "../../games/index.js";
+import { gameFolder, helpsIn } from "../../profiles/index.js";
+import { bodyOf, bytesOf, isJson, json, jsonOf, runRoute, send, textOf } from "./http.js";
+import { profilesShown } from "./profiles.js";
+/** Answers the page's requests about the game: true when the request was one. */
+export function answerGame(request, response, url, served) {
+    const route = routes[`${request.method ?? ""} ${url.pathname}`];
+    if (route === undefined) {
+        return false;
+    }
+    runRoute(response, () => route(request, response, served));
+    return true;
+}
+/** The chat calls a tool: when nobody heard the player before, the AI's clock, held since, starts now, with the time it was held given back. */
+export function chatCalls(served) {
+    const folder = gameFolder(served.context.home());
+    const current = loadGame(folder);
+    const held = current !== undefined && aiHeld(served, current);
+    if (served.bell.chatCalls() && held) {
+        saveGame(folder, { ...current, clock: { ...current.clock, since: served.context.now().toISOString() } });
+    }
+}
+const routes = {
+    "GET /api/game": (request, response, served) => sendGame(response, served),
+    "POST /api/move": moveFromPage,
+    "POST /api/message": messageFromPage,
+    "POST /api/new": newGameFromPage,
+    "POST /api/draw": drawFromPage,
+    "POST /api/resign": resignFromPage,
+    "POST /api/start": startFromPage,
+    "POST /api/study": studyFromPage,
+};
+/**
+ * The player's move from the page, with their words when they wrote some: played as player_move plays it (D-47) and saved with the words, refused in the
+ * player's words, and the doorbell rung for the chat.
+ */
+async function moveFromPage(request, response, served) {
+    // A form of another site can post text, never JSON without asking first: the type keeps it out, with the origin.
+    if (!isJson(request)) {
+        send(response, 415, json, JSON.stringify({ error: 'Send the move as JSON: {"move": "e2e4"}.' }));
+        return;
+    }
+    const body = jsonOf(await bodyOf(request));
+    const move = textOf(body?.move);
+    if (move === undefined || (body?.message !== undefined && typeof body.message !== "string")) {
+        send(response, 400, json, JSON.stringify({ error: 'Send the move as JSON, in SAN or as squares, with your words if you like: {"move": "e2e4", "message": "…"}.' }));
+        return;
+    }
+    const refused = refusalOf(served);
+    if (refused !== undefined) {
+        send(response, 409, json, JSON.stringify(refused));
+        return;
+    }
+    const message = textOf(body?.message);
+    let illegal = false;
+    try {
+        const now = served.context.now();
+        const refuse = (problem) => {
+            illegal = true;
+            return problem;
+        };
+        playMove(gameFolder(served.context.home()), now, "player", move, refuse, message === undefined ? {} : { said: { text: message, at: now } });
+    }
+    catch (error) {
+        // The game may have changed since the page read it: the move refused, the AI's turn, a flag fallen.
+        send(response, 409, json, JSON.stringify(refusalFrom(error, illegal ? "illegal" : refusalOf(served)?.refusal)));
+        return;
+    }
+    // The pages hear of the move from the watcher, as of every other.
+    served.bell.ring();
+    send(response, 200, json, JSON.stringify({ played: true }));
+}
+/** The player's words from the page, without a move: saved with the game as player_say saves them, refused in the player's words, the doorbell rung for the first. */
+async function messageFromPage(request, response, served) {
+    if (!isJson(request)) {
+        send(response, 415, json, JSON.stringify({ error: 'Send the message as JSON: {"text": "…"}.' }));
+        return;
+    }
+    const text = textOf(jsonOf(await bodyOf(request))?.text);
+    if (text === undefined) {
+        send(response, 400, json, JSON.stringify({ error: `Send the message as JSON, ${talkLimits.player} characters at most: {"text": "…"}.` }));
+        return;
+    }
+    let current;
+    try {
+        current = say(gameFolder(served.context.home()), "player", text, served.context.now());
+    }
+    catch (error) {
+        const noGame = refusalOf(served)?.refusal === "no-game";
+        send(response, 409, json, JSON.stringify(refusalFrom(error, noGame ? "no-game" : undefined)));
+        return;
+    }
+    // The first words of a move wake the chat, and between games the first since the AI spoke; the AI finds the rest at its next call (D-54, D-74).
+    if (wakesTheChat(current)) {
+        served.bell.ring();
+    }
+    send(response, 200, json, JSON.stringify({ said: true }));
+}
+/**
+ * A new game from the page, with the sides, the level and the clock the player chose: the sides and the level they leave out are as in the game
+ * before, and no clock means a game without one. One going on goes to the archive unfinished, and the doorbell tells the chat.
+ */
+async function newGameFromPage(request, response, served) {
+    const asked = 'Send the new game as JSON: {"ai_colour": "black", "level": "club", "clock": "10+5"}, each one optional; no clock for a game without one.';
+    const body = isJson(request) ? jsonOf(await bodyOf(request)) : undefined;
+    if (body === undefined) {
+        send(response, isJson(request) ? 400 : 415, json, JSON.stringify({ error: asked }));
+        return;
+    }
+    try {
+        const before = loadGame(gameFolder(served.context.home()));
+        const input = newGame.input.safeParse({ ai_colour: body.ai_colour ?? before?.ai ?? "black", level: body.level, clock: body.clock, replace: true });
+        if (!input.success) {
+            send(response, 400, json, JSON.stringify({ error: asked }));
+            return;
+        }
+        // The game starts from the page, open: its clocks wait for the player's Start there.
+        startNewGame(input.data, { ...served.context, pageOpen: () => true }, "page");
+    }
+    catch (error) {
+        send(response, 409, json, JSON.stringify(refusalFrom(error)));
+        return;
+    }
+    served.bell.ring();
+    send(response, 200, json, JSON.stringify({ started: true }));
+}
+/** The player's draw from the page (D-65): an offer on their turn, which rings the doorbell, or their answer to the AI's, which rings it when accepted. */
+async function drawFromPage(request, response, served) {
+    const asked = 'Send the draw as JSON: {"action": "offer"}, "accept" or "decline".';
+    if (!isJson(request)) {
+        send(response, 415, json, JSON.stringify({ error: asked }));
+        return;
+    }
+    const action = jsonOf(await bodyOf(request))?.action;
+    if (action !== "offer" && action !== "accept" && action !== "decline") {
+        send(response, 400, json, JSON.stringify({ error: asked }));
+        return;
+    }
+    try {
+        if (action === "offer") {
+            offerDraw(served.context);
+        }
+        else {
+            answerDraw(served.context, action === "accept");
+        }
+    }
+    catch (error) {
+        send(response, 409, json, JSON.stringify(refusalFrom(error, refusalOf(served)?.refusal)));
+        return;
+    }
+    if (action !== "decline") {
+        served.bell.ring();
+    }
+    send(response, 200, json, JSON.stringify({ done: true }));
+}
+/** The player starts the clocks from the page, which wait from the game's start; the doorbell wakes the chat when its move is first, waiting for this. */
+function startFromPage(request, response, served) {
+    if (!isJson(request)) {
+        send(response, 415, json, JSON.stringify({ error: "Send the request as JSON: {}." }));
+        return;
+    }
+    const folder = gameFolder(served.context.home());
+    const current = loadGame(folder);
+    if (current?.clock?.waiting !== true || endOf(current.game) !== undefined) {
+        send(response, 409, json, JSON.stringify({ error: "No clock waits to start: start a game with a clock first." }));
+        return;
+    }
+    saveGame(folder, { ...current, clock: clockStarted(current.clock, served.context.now()) });
+    if (current.game.position.turn === current.ai) {
+        served.bell.ring();
+    }
+    send(response, 200, json, JSON.stringify({ started: true }));
+}
+/** The player resigns from the page (D-65), whoever is to move: the game ends and goes to the archive, and the doorbell tells the chat. */
+function resignFromPage(request, response, served) {
+    if (!isJson(request)) {
+        send(response, 415, json, JSON.stringify({ error: "Send the request as JSON: {}." }));
+        return;
+    }
+    try {
+        endGame.run({ result: "player_resigns" }, served.context);
+    }
+    catch (error) {
+        send(response, 409, json, JSON.stringify(refusalFrom(error, refusalOf(served)?.refusal === "no-game" ? "no-game" : undefined)));
+        return;
+    }
+    served.bell.ring();
+    send(response, 200, json, JSON.stringify({ resigned: true }));
+}
+/**
+ * A game the player brings from elsewhere to analyse: kept to study and put in analysis as analyse_game does with a PGN, the page showing it at once,
+ * and the doorbell rung for the chat to go over it. Never while a game goes on.
+ */
+async function studyFromPage(request, response, served) {
+    const asked = 'Send the game as JSON: {"pgn": "[White \\"…\\"] … 1. e4 e5 …"}, one to open again by its name: {"game": "study/2026-11-04-153012.pgn"}, '
+        + 'or the game just over: {"last": true}.';
+    if (!isJson(request)) {
+        send(response, 415, json, JSON.stringify({ error: asked }));
+        return;
+    }
+    const body = jsonOf((await bytesOf(request, pgnLimit))?.toString("utf8"));
+    const pgn = textOf(body?.pgn);
+    const game = textOf(body?.game);
+    const last = body?.last === true;
+    // A game a link of the page opens is there to look at: the chat is not asked to go over it.
+    const look = body?.look === true;
+    if (pgn === undefined && game === undefined && !last) {
+        send(response, 400, json, JSON.stringify({ error: asked, refusal: "pgn-unreadable" }));
+        return;
+    }
+    if (refusalOf(served)?.refusal !== "no-game") {
+        send(response, 409, json, JSON.stringify({ error: "A game is going on: finish it before you bring another to analyse.", refusal: "game-going" }));
+        return;
+    }
+    let reviewed;
+    let brought;
+    try {
+        // Without what the chat was told: the analyst's instructions stay for the AI's own analyse_game.
+        const opened = last ? lastPlayed(served.context) : game === undefined ? kept(served, pgn) : namedGame(served.context, game);
+        reviewed = isReviewed(opened.record);
+        brought = !reviewed && !look;
+        // A game not yet reviewed is marked as brought, for status to ask the AI to go over it; one reviewed is ready, and the chat sleeps on.
+        startAnalysis(gameFolder(served.context.home()), opened.name, served.context.now(), brought);
+    }
+    catch (error) {
+        send(response, 400, json, JSON.stringify({ error: error.message, refusal: "pgn-unreadable" }));
+        return;
+    }
+    if (brought) {
+        served.bell.ring();
+    }
+    send(response, 200, json, JSON.stringify({ kept: true, reviewed }));
+}
+/**
+ * The game in progress or just ended, as the player may see it: its PGN without the AI's plans while it goes on, the AI's side, when it started, and the
+ * talk on the page, each line of the player's with how far it got (D-53), and the draw offer that stands (D-65); the AI's name and model (D-82); and the
+ * profiles.
+ */
+function sendGame(response, served) {
+    const folder = gameFolder(served.context.home());
+    const current = gameNow(served);
+    // With no game the page still shows the talk before the first (D-77).
+    const spoken = current ?? loadTableTalk(folder);
+    const heard = heardLines(spoken, served.context.given);
+    const talk = spoken.talk.map(({ who, text, ply }, index) => heard[index] === undefined ? { who, text, ply } : { who, text, ply, heard: heard[index] });
+    const offer = current === undefined ? undefined : drawOfferOf(current);
+    const coach = coachOn(folder, current);
+    const game = current === undefined ? null : {
+        pgn: playerPgn(folder, current),
+        ai: current.ai,
+        started: current.started,
+        // Its name in the archive, for the page's address.
+        name: archiveName(current),
+        talk,
+        // How many of its first moves are the book's: the page marks them while the game goes on, as the AI's review does after.
+        book: bookPlies(current.game.record),
+        ...(current.clock === undefined ? {} : { clock: current.clock }),
+        ...(offer === undefined ? {} : { drawOffer: offer }),
+        ...(coach === undefined ? {} : { coach }),
+    };
+    const analysis = current === undefined || endOf(current.game) !== undefined ? analysisShown(served) : undefined;
+    const aiModel = aiModelOf(folder);
+    const body = {
+        game,
+        ...(game === null && talk.length > 0 ? { talk } : {}),
+        ...(analysis === undefined ? {} : { analysis }),
+        opponent: served.opponent(),
+        ...(aiModel === undefined ? {} : { aiModel }),
+        listening: served.bell.listening,
+        ...thinkingShown(served, current),
+        ...(served.outdated ? { outdated: true } : {}),
+        ...profilesShown(served.context.home()),
+    };
+    send(response, 200, json, JSON.stringify(body));
+}
+/**
+ * What the AI thinks on now, for the page's sign: its move, while the chat is in a turn the doorbell woke it for or on the position it is to move in; the
+ * player's time, while the ponder agent thinks, before it waits for their move (D-72). Never the coach's, which is not the opponent (D-88).
+ */
+function thinkingShown(served, current) {
+    if (current === undefined || endOf(current.game) !== undefined) {
+        return {};
+    }
+    const position = { started: current.started, plies: current.game.record.moves.length };
+    if (current.game.position.turn === current.ai) {
+        const seen = served.context.positionSeen;
+        const onIt = served.bell.woke || (seen !== undefined && seen !== null && samePosition(seen, position));
+        return served.bell.inTurn && onIt ? { thinking: "move" } : {};
+    }
+    return served.pondering !== undefined && samePosition(served.pondering, position) ? { thinking: "ponder" } : {};
+}
+/**
+ * What the coach wrote that the player may see now, in a game going on with the helps on (D-88): its judgments, those whose note names a move they may still
+ * play once they have moved, its hint for the position it was given in, and who it saw ahead (D-90); none without anything. Once the game is over its
+ * PGN has the judgments and the leads.
+ */
+function coachOn(folder, current) {
+    if (current === undefined || endOf(current.game) !== undefined || !helpsIn(folder)) {
+        return undefined;
+    }
+    const shown = coachShown(coachWords(folder, current), current);
+    return shown.judgments.length === 0 && shown.hint === undefined && shown.leads === undefined ? undefined : shown;
+}
+/** The game in analysis, once no game goes on (D-69): its name and its PGN with the AI's review; none without one, or when it cannot be read. */
+function analysisShown(served) {
+    const analysis = gameInAnalysis(gameFolder(served.context.home()));
+    if (analysis === undefined) {
+        return undefined;
+    }
+    try {
+        const { name, record } = namedGame(served.context, analysis.game);
+        // How far the book goes, which the page cannot tell without the book's moves: its card names the opening on those moves.
+        return { name, pgn: writePgn(record), book: bookPlies(record) };
+    }
+    catch {
+        // A game gone from the archive is no longer shown.
+        return undefined;
+    }
+}
+/** The game just over, or else the last one played, as analyse_game takes it without a name: always one of the archive. */
+function lastPlayed(context) {
+    const { name, record } = gameToStudy(context);
+    if (name === undefined) {
+        throw new Error("The game just over is not in the archive yet: try again in a moment.");
+    }
+    return { name, record };
+}
+/** A game brought as a PGN, kept to study as analyse_game keeps it: the one already kept when it is the same game, with its review. */
+function kept(served, pgn) {
+    analyseGame.run({ pgn }, { ...served.context, told: undefined });
+    return namedGame(served.context, gameInAnalysis(gameFolder(served.context.home())).game);
+}
+/** The longest PGN the page brings: a long game with its clocks, and the comments a site adds, which go. */
+const pgnLimit = 256 * 1024;
+/** Why the player cannot move now; undefined when they can. */
+function refusalOf(served) {
+    try {
+        const current = gameNow(served);
+        if (current === undefined || endOf(current.game) !== undefined) {
+            return { error: "There is no game going on: start one in the chat.", refusal: "no-game" };
+        }
+        return current.game.position.turn === current.ai ? { error: "Wait for the AI's move.", refusal: "ai-to-move" } : undefined;
+    }
+    catch (error) {
+        return { error: error.message };
+    }
+}
+/** The refusal of an error thrown by a command, with its code when the error or the caller knows it. */
+function refusalFrom(error, refusal) {
+    const message = error.message;
+    if (error instanceof ChatNotClear) {
+        return { error: message, refusal: "clear-chat" };
+    }
+    if (error instanceof WordsRefused) {
+        return { error: message, refusal: `words-${error.reason}`, most: error.most };
+    }
+    if (error instanceof DrawRefused) {
+        return { error: message, refusal: `draw-${error.reason}` };
+    }
+    return refusal === undefined ? { error: message } : { error: message, refusal };
+}
+/** The game as the page reads it now: a flag that has fallen ends it (D-13), and the doorbell tells the chat, which hears how from status. */
+function gameNow(served) {
+    const folder = gameFolder(served.context.home());
+    const before = loadGame(folder);
+    // The AI's clock is held while nobody hears the player: its flag cannot fall before the chat is there to move.
+    if (before !== undefined && aiHeld(served, before)) {
+        return before;
+    }
+    const current = gameAt(folder, served.context.now());
+    if (before !== undefined && endOf(before.game) === undefined && current !== undefined && endOf(current.game) !== undefined) {
+        served.bell.ring();
+    }
+    return current;
+}
+/** Whether the AI's clock is held: a game with a clock, going on, the AI to move, and nobody hearing the player. */
+function aiHeld(served, current) {
+    return !served.bell.listening && current.clock !== undefined && endOf(current.game) === undefined && current.game.position.turn === current.ai;
+}

package/dist/server/{http.d.ts → page/http.d.ts}

@@ -1,9 +1,22 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DrawRefused } from "../../commands/index.ts";
+import type { WordsRefused } from "../../games/index.ts";
 export declare const json = "application/json; charset=utf-8";
+/**
+ * A request refused, as the page reads it: the server's words, and the code of a refusal the page says in the player's language, with the characters
+ * left for words too long; without a code, the page shows the words.
+ */
+export interface Refused {
+    readonly error: string;
+    readonly refusal?: "no-game" | "ai-to-move" | "illegal" | "clear-chat" | `words-${WordsRefused["reason"]}` | `draw-${DrawRefused["reason"]}` | "profile-game" | "game-going" | "pgn-unreadable";
+    readonly most?: number;
+}
 /** Answers a request, with nothing cached, sniffed or referred, and the page's policy unless the headers give another. */
 export declare function send(response: ServerResponse, status: number, type: string, body: string | Buffer, headers?: Record<string, string>): void;
 /** Answers with JSON. */
 export declare function sendJson(response: ServerResponse, status: number, body: unknown): void;
+/** Runs the answer to a request: an error it did not expect, such as a file that cannot be written, is told to the page, and the server goes on. */
+export declare function runRoute(response: ServerResponse, route: () => void | Promise<void>): void;
 /** Whether a request sends JSON: a form of another site can post text, never JSON without asking first. */
 export declare function isJson(request: IncomingMessage): boolean;
 /** An object from JSON; undefined for anything else. */

package/dist/server/{http.js → page/http.js}

@@ -15,6 +15,17 @@ export function send(response, status, type, body, headers = {}) {
 export function sendJson(response, status, body) {
     send(response, status, json, JSON.stringify(body));
 }
+/** Runs the answer to a request: an error it did not expect, such as a file that cannot be written, is told to the page, and the server goes on. */
+export function runRoute(response, route) {
+    Promise.resolve().then(route).catch((error) => {
+        if (response.headersSent) {
+            response.end();
+        }
+        else {
+            sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+}
 /** Whether a request sends JSON: a form of another site can post text, never JSON without asking first. */
 export function isJson(request) {
     return (request.headers["content-type"] ?? "").startsWith("application/json");

package/dist/server/{page.d.ts → page/page.d.ts}

@@ -1,14 +1,14 @@
 import { type ServerResponse } from "node:http";
-import type { Context } from "../commands/context.ts";
-import { DrawRefused } from "../commands/draw-offer.ts";
-import { WordsRefused } from "../games/index.ts";
-import { Bell } from "./bell.ts";
+import { type Context, type SeenPosition } from "../../commands/index.ts";
+import { Bell } from "../bell.ts";
 /** The page of a player's folder, served: its address, how to tell it the AI was given words, which change no file, and how to stop it. */
 export interface Page {
     readonly url: string;
     heard(): void;
     /** The chat calls a tool: the page hears it listens, and the AI's clock, held while nobody heard the player, starts now. */
     chatCalls(): void;
+    /** The AI starts thinking on the player's time, on a position, or is done (D-72): the page shows it. */
+    ponders(position: SeenPosition | undefined): void;
     /** Whether a browser has the page open now: one listens to the game's changes. */
     open(): boolean;
     /** Opens the New game window on every page open now, for the player to choose the game there: whether one was open. */
@@ -29,15 +29,10 @@ export interface Served {
     readonly bell: Bell;
     readonly watchers: Set<ServerResponse>;
     port: number;
-}
-/**
- * A request refused, as the page reads it: the server's words, and the code of a refusal the page says in the player's language (T-11), with the characters
- * left for words too long; without a code, the page shows the words.
- */
-export interface Refused {
-    readonly error: string;
-    readonly refusal?: "no-game" | "ai-to-move" | "illegal" | "clear-chat" | `words-${WordsRefused["reason"]}` | `draw-${DrawRefused["reason"]}` | "profile-game" | "game-going" | "pgn-unreadable";
-    readonly most?: number;
+    /** The folder was set up by an older init: the page asks the player to run it again. Read once, as init runs with the chat closed. */
+    readonly outdated: boolean;
+    /** The position the AI thinks on during the player's time (D-72), until it is done; none else. */
+    pondering?: SeenPosition | undefined;
 }
 /**
  * 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