chesspal 0.0.1 → 0.2.0

package/dist/games/talk.js

@@ -0,0 +1,131 @@
+// The talk on the board page (D-51): the player's words and the AI's answers, kept in game.json beside the PGN, or in talk.json with no game (D-77).
+import { endOf } from "./current-game.js";
+/** The most the player may write in a move, in all their lines, and the most a line of the AI's may hold (D-54); with the helps on, as an analyst's note (D-78). */
+export const talkLimits = { player: 200, ai: 300, aiHelps: 700 };
+/**
+ * A new line of the talk, said when the game has `ply` moves: refused when it is empty or too long. The player writes 200 characters a move in all, the
+ * words sent with the move included; the AI speaks once a move of theirs, on their time, and its agent's word leaves it an answer to what they write after (D-54, D-72).
+ */
+export function talkLine(current, sayer, text, at, ply = isGame(current) ? current.game.record.moves.length : 0, aiMost = talkLimits.ai) {
+    const who = sayer === "agent" ? "ai" : sayer;
+    const words = text.trim();
+    const most = who === "player" ? wordsLeft(current) : aiMost;
+    if (words === "") {
+        throw new WordsRefused("There is nothing to say: write the words first.", "empty");
+    }
+    if (who === "player" && most === 0) {
+        throw new WordsRefused(`You have written your ${talkLimits.player} characters until the AI's next move: write again after it.`, "spent");
+    }
+    if (words.length > most) {
+        const more = who === "player" && most < talkLimits.player;
+        throw new WordsRefused(`The words are ${words.length} characters long: write at most ${most}${more ? " more until the AI's next move" : ""}.`, more ? "longer-than-left" : "long", most);
+    }
+    if (who === "ai" && isGame(current)) {
+        refuseAiWords(current, sayer === "agent");
+    }
+    return { who, text: words, ply, at: at.toISOString(), ...(sayer === "agent" ? { agent: true } : {}) };
+}
+/** Words refused, and why, for the page to say it in the player's language: none, the move's characters spent, more than a line or what is left holds. */
+export class WordsRefused extends Error {
+    reason;
+    most;
+    constructor(message, reason, most = 0) {
+        super(message);
+        this.reason = reason;
+        this.most = most;
+    }
+}
+/** Whether the player's last line wakes the chat: the first of a move, and between games the first since the AI last spoke (D-54, D-74). */
+export function wakesTheChat(current) {
+    return going(current) ? playerLinesThisMove(current).length === 1 : unanswered(current).length === 1;
+}
+/** What the player said that the AI has not answered, but for the words whose keys are in `given`. */
+export function unheardWords(current, given) {
+    return unanswered(current).filter(({ key }) => !given.has(key)).map(({ key, line }) => ({ key, text: line.text }));
+}
+/** How far each line of the talk got: the player's by `Heard`, the AI's undefined (D-53). */
+export function heardLines(current, given) {
+    const waiting = new Set(unanswered(current).map(({ key }) => key));
+    return current.talk.map((line, index) => {
+        const key = keyOf(current, index);
+        return line.who === "ai" ? undefined : !waiting.has(key) ? "answered" : given.has(key) ? "read" : "sent";
+    });
+}
+/** The lines the player wrote since the AI's last move: those it answers with its next move, and the 200 characters of this move are counted on them. */
+function playerLinesThisMove(current) {
+    const since = sinceAiMoved(current);
+    return current.talk.filter((line) => line.who === "player" && line.ply >= since);
+}
+/** How many characters the player may still write for this move; between games a whole line each time, with no count (D-74). */
+function wordsLeft(current) {
+    if (!going(current)) {
+        return talkLimits.player;
+    }
+    return Math.max(talkLimits.player - playerLinesThisMove(current).reduce((sum, line) => sum + line.text.length, 0), 0);
+}
+/**
+ * The AI speaks apart from its move once a move of the player's, on their time, with something to say or to answer (D-72), and never while its move waits:
+ * it speaks in the move's comment then. Its agent speaks only first, when the player has written nothing to answer, and its word leaves the chat one answer
+ * to what they write after. Between games it talks freely, about the game just over or to start another (D-74).
+ */
+function refuseAiWords(current, byAgent) {
+    const { game, ai } = current;
+    const since = sinceAiMoved(current);
+    if (endOf(game) !== undefined) {
+        return;
+    }
+    if (game.position.turn === ai) {
+        throw new Error("It is your move: speak in ai_move's comment. Nothing changed.");
+    }
+    const spoken = current.talk.filter((line) => line.who === "ai" && line.ply >= since);
+    if (byAgent) {
+        refuseAgentWords(current, spoken);
+        return;
+    }
+    if (spoken.some((line) => line.agent !== true)) {
+        throw new Error("You have spoken once for this move: say the rest in ai_move's comment. Nothing changed.");
+    }
+    if (spoken.length > 0 && unanswered(current).length === 0) {
+        throw new Error("You have said a word on the player's time already: speak again only to answer them, else in ai_move's comment. Nothing changed.");
+    }
+}
+/** The agent's word on the player's time: one, and none once they have written, since the chat answers them. */
+function refuseAgentWords(current, spoken) {
+    if (spoken.length > 0) {
+        throw new Error("You have spoken for this move already: say nothing more. Nothing changed.");
+    }
+    if (unanswered(current).length > 0) {
+        throw new Error("The player has written to you, and the AI in the chat answers them: say nothing. Nothing changed.");
+    }
+}
+/** How many moves the game had just after the AI's last move, 0 before it: what is said since then waits for its next move. */
+function sinceAiMoved(current) {
+    const moves = current.game.record.moves.length;
+    // The last move is the AI's when the AI is not to move; else the AI's is the one before it.
+    const lastIsAi = current.game.position.turn !== current.ai;
+    return lastIsAi ? moves : moves >= 2 ? moves - 1 : 0;
+}
+/** The player's lines after the AI's last words and its last move, each with a key of its own across games. */
+function unanswered(current) {
+    const { talk } = current;
+    const lastSaid = talk.findLastIndex((line) => line.who === "ai");
+    return talk.flatMap((line, index) => index > lastSaid && line.who === "player" && !aiMovedSince(current, line.ply) ? [{ key: keyOf(current, index), line }] : []);
+}
+/** Whether the AI has moved since the game had `ply` moves: the last move is the AI's when the AI is not to move, and two moves on, one of them is. */
+function aiMovedSince(current, ply) {
+    if (!isGame(current)) {
+        return false;
+    }
+    const moves = current.game.record.moves.length;
+    return moves > ply + 1 || (moves === ply + 1 && current.game.position.turn !== current.ai);
+}
+function isGame(current) {
+    return "game" in current;
+}
+/** Whether a game goes on, with its limits to the talk; none with no game or once it is over. */
+function going(current) {
+    return isGame(current) && endOf(current.game) === undefined;
+}
+function keyOf(current, index) {
+    return `${current.started}#${index}`;
+}

package/dist/games/thoughts.d.ts

@@ -0,0 +1,15 @@
+import type { CurrentGame } from "./current-game.ts";
+/** The AI's answer to one reply of the player's: the reply and its move in SAN, and why in one sentence. */
+export interface Thought {
+    readonly reply: string;
+    readonly move: string;
+    readonly why: string;
+}
+/** The key of the position the player is to move in: the game, by its start, and how many moves it has. */
+export declare function thoughtKey(current: CurrentGame, ply?: number): string;
+/** Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. */
+export declare function keepThought(folder: string, key: string, thought: Thought): Thought[];
+/** The thought for the player's last move, when the AI is to move and thought of it on their time. */
+export declare function thoughtForLastMove(folder: string, current: CurrentGame): Thought | undefined;
+/** Since when the AI has waited for the player's move in a position: the first time it asked, `now` then, kept with its thoughts. */
+export declare function waitingSince(folder: string, key: string, now: Date): Date;

package/dist/games/thoughts.js

@@ -0,0 +1,60 @@
+// What the AI thought on the player's time (D-72): its answers to the player's likely replies, in thoughts.json beside game.json, hidden from the player
+// as its plan is (D-29), and kept only for the position they were thought on: the next position's replace them.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { writeAtomically } from "./files.js";
+/** The key of the position the player is to move in: the game, by its start, and how many moves it has. */
+export function thoughtKey(current, ply = current.game.record.moves.length) {
+    return `${current.started}#${ply}`;
+}
+/** Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. */
+export function keepThought(folder, key, thought) {
+    const kept = keptAt(folder, key);
+    const thoughts = [...kept.thoughts.filter((one) => one.reply !== thought.reply), thought];
+    if (thoughts.length > mostThoughts) {
+        throw new Error(`You have ${mostThoughts} thoughts for this position already: they are enough. Nothing changed.`);
+    }
+    write(folder, { ...kept, thoughts });
+    return thoughts;
+}
+/** The thought for the player's last move, when the AI is to move and thought of it on their time. */
+export function thoughtForLastMove(folder, current) {
+    const { moves } = current.game.record;
+    const last = moves.at(-1);
+    return last === undefined ? undefined : keptAt(folder, thoughtKey(current, moves.length - 1)).thoughts.find((thought) => thought.reply === last.san);
+}
+/** Since when the AI has waited for the player's move in a position: the first time it asked, `now` then, kept with its thoughts. */
+export function waitingSince(folder, key, now) {
+    const kept = keptAt(folder, key);
+    if (kept.since !== undefined) {
+        return new Date(kept.since);
+    }
+    write(folder, { ...kept, since: now.toISOString() });
+    return now;
+}
+/** The most thoughts kept for a position: a few likely replies, not every legal one. */
+const mostThoughts = 8;
+const fileName = "thoughts.json";
+const thoughtsFile = z.object({
+    key: z.string(),
+    thoughts: z.array(z.object({ reply: z.string(), move: z.string(), why: z.string() })),
+    since: z.iso.datetime().optional(),
+});
+/** What is kept for a position: nothing yet when the file is for another, or missing. */
+function keptAt(folder, key) {
+    const kept = read(folder);
+    return kept?.key === key ? kept : { key, thoughts: [] };
+}
+function read(folder) {
+    try {
+        return thoughtsFile.parse(JSON.parse(readFileSync(join(folder, fileName), "utf8")));
+    }
+    catch {
+        // None yet, or one Chesspal cannot read: thoughts are only a help, and the next one written replaces it.
+        return undefined;
+    }
+}
+function write(folder, kept) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(kept, null, 2)}\n`);
+}

package/dist/home/data-folder.d.ts

@@ -0,0 +1,12 @@
+/** What the data folder is found from: the environment, the system, the user's own folder, and where the system says Documents is. */
+export interface System {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly platform: string;
+    readonly home: string;
+    /** What `reg query` prints of Documents' place, or undefined when it cannot run. */
+    readonly registry: () => string | undefined;
+    /** A file's text, or undefined when it cannot be read: the XDG user dirs on Linux. */
+    readonly readText: (path: string) => string | undefined;
+}
+/** The player's data folder: CHESSPAL_HOME when set, else the system's Documents with Chesspal's folder in it. */
+export declare function dataFolder(system?: System): string;

package/dist/home/data-folder.js

@@ -0,0 +1,55 @@
+// The player's data folder (D-71): Documents\My Games\Chesspal on Windows, wherever the system keeps Documents, OneDrive too; Documents/Chesspal
+// elsewhere, where Linux's XDG user dirs put Documents; CHESSPAL_HOME in its place, for the tests and the playtests.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+/** The player's data folder: CHESSPAL_HOME when set, else the system's Documents with Chesspal's folder in it. */
+export function dataFolder(system = thisSystem()) {
+    const chosen = system.env.CHESSPAL_HOME?.trim();
+    const path = system.platform === "win32" ? win32 : posix;
+    if (chosen !== undefined && chosen !== "") {
+        return path.resolve(chosen);
+    }
+    if (system.platform === "win32") {
+        return win32.join(windowsDocuments(system), "My Games", "Chesspal");
+    }
+    return posix.join(system.platform === "darwin" ? posix.join(system.home, "Documents") : xdgDocuments(system), "Chesspal");
+}
+// Where Windows keeps Documents for this user, as Explorer's known folder does: the registry names it, with variables such as %USERPROFILE%.
+const shellFolders = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders";
+function thisSystem() {
+    return { env: process.env, platform: process.platform, home: homedir(), registry: readRegistry, readText };
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Documents as the XDG user dirs name it, in the system's language, such as ~/Documenti, as GLib reads them; ~/Documents when they say nothing usable. */
+function xdgDocuments({ env, home, readText }) {
+    const config = env.XDG_CONFIG_HOME?.startsWith("/") === true ? env.XDG_CONFIG_HOME : posix.join(home, ".config");
+    const named = /^\s*XDG_DOCUMENTS_DIR\s*=\s*"([^"]*)"/m.exec(readText(posix.join(config, "user-dirs.dirs")) ?? "")?.[1];
+    const filled = named?.replace(/^\$HOME(?=\/|$)/, home);
+    return filled !== undefined && posix.isAbsolute(filled) ? posix.normalize(filled) : posix.join(home, "Documents");
+}
+// About 40 ms, once a process: PowerShell would say the same in 270. reg writes in the console's code page, which breaks a folder with accents: UTF-8 first.
+function readRegistry() {
+    const command = `"chcp 65001 >nul & reg query "${shellFolders}" /v Personal"`;
+    const answer = spawnSync("cmd.exe", ["/d", "/s", "/c", command], { encoding: "utf8", windowsHide: true, windowsVerbatimArguments: true, timeout: 5_000 });
+    return answer.status === 0 ? answer.stdout : undefined;
+}
+/** Documents as the registry names it, with its variables filled in; the user's own Documents when the registry says nothing usable. */
+function windowsDocuments({ env, home, registry }) {
+    const named = /^\s*Personal\s+REG_(?:EXPAND_)?SZ\s+(.+?)\s*$/m.exec(registry() ?? "")?.[1];
+    const filled = named?.replace(/%([^%]+)%/g, (whole, name) => valueOf(env, name) ?? whole);
+    return filled !== undefined && win32.isAbsolute(filled) && !/[%�]/.test(filled) ? filled : win32.join(valueOf(env, "USERPROFILE") ?? home, "Documents");
+}
+// Windows's variables, whatever their case.
+function valueOf(env, name) {
+    const key = Object.keys(env).find((one) => one.toLowerCase() === name.toLowerCase());
+    return key === undefined ? undefined : env[key];
+}

package/dist/home/index.d.ts

@@ -0,0 +1,2 @@
+export { dataFolder, type System } from "./data-folder.ts";
+export { openFolder } from "./open-folder.ts";

package/dist/home/index.js

@@ -0,0 +1,3 @@
+// Where the player's data is (D-71): one folder for every chat, apart from the host's folder. Below the commands, beside the games and the profiles.
+export { dataFolder } from "./data-folder.js";
+export { openFolder } from "./open-folder.js";

package/dist/home/open-folder.d.ts

@@ -0,0 +1,2 @@
+/** Opens a folder in the system's file manager, without waiting for it to close: whether the manager started, for the page to say so when it did not. */
+export declare function openFolder(folder: string, platform: string): Promise<boolean>;

package/dist/home/open-folder.js

@@ -0,0 +1,14 @@
+// The data folder shown to the player in the system's own file manager: Explorer, Finder, or the Linux desktop's.
+import { spawn } from "node:child_process";
+/** Opens a folder in the system's file manager, without waiting for it to close: whether the manager started, for the page to say so when it did not. */
+export function openFolder(folder, platform) {
+    const manager = platform === "win32" ? "explorer.exe" : platform === "darwin" ? "open" : "xdg-open";
+    return new Promise((done) => {
+        const opened = spawn(manager, [folder], { detached: true, stdio: "ignore" });
+        opened.once("spawn", () => {
+            opened.unref();
+            done(true);
+        });
+        opened.once("error", () => done(false));
+    });
+}

package/dist/host-files/agents.d.ts

@@ -0,0 +1,20 @@
+import type { AiLevel } from "../core/index.ts";
+/** The agents that think for the AI, by their names. */
+export declare const ponderAgents: readonly string[];
+/** The coach's agent (D-88). */
+export declare const coachAgent = "chesspal-coach";
+/** The analyst's agent, which reviews a game over on the board page when the player wants it (D-89). */
+export declare const analystAgent = "chesspal-analyst";
+/** The agent that thinks for the AI at a level: on the quick model at the beginner and club levels, on the AI's own above. */
+export declare function ponderAgentFor(level: AiLevel): string;
+/** Whether the AI's thoughts on the player's time come from a quicker model than its own at a level. */
+export declare function onQuickModel(level: AiLevel): boolean;
+/** Whether the player's folder has the agent, as init writes it: a folder set up before it has none, and the AI then plays as before. */
+export declare function hasAgent(folder: string, agent: string): boolean;
+/** The agents' files, as Claude Code reads them from .claude/agents: Chesspal's whole, rewritten by init. */
+export declare function agentFiles(folder: string): {
+    path: string;
+    text: string;
+}[];
+/** Instructions for the AI, by their file's name in the package's instructions folder. */
+export declare function instructions(name: string): string;

package/dist/host-files/agents.js

@@ -0,0 +1,53 @@
+// The agents that work in the background in Claude Code: those that think for the opponent on the player's time (D-72), one on the host's quick model for the
+// lower levels, one on the AI's own for the higher; the coach, with the helps on (D-88), and the analyst of a game over (D-89), on the AI's own model.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const quickAgent = "chesspal-ponder-quick";
+const ownAgent = "chesspal-ponder";
+/** The agents that think for the AI, by their names. */
+export const ponderAgents = [quickAgent, ownAgent];
+/** The coach's agent (D-88). */
+export const coachAgent = "chesspal-coach";
+/** The analyst's agent, which reviews a game over on the board page when the player wants it (D-89). */
+export const analystAgent = "chesspal-analyst";
+/** The agent that thinks for the AI at a level: on the quick model at the beginner and club levels, on the AI's own above. */
+export function ponderAgentFor(level) {
+    return onQuickModel(level) ? quickAgent : ownAgent;
+}
+/** Whether the AI's thoughts on the player's time come from a quicker model than its own at a level. */
+export function onQuickModel(level) {
+    return level === "beginner" || level === "club";
+}
+/** Whether the player's folder has the agent, as init writes it: a folder set up before it has none, and the AI then plays as before. */
+export function hasAgent(folder, agent) {
+    return existsSync(agentPath(folder, agent));
+}
+/** The agents' files, as Claude Code reads them from .claude/agents: Chesspal's whole, rewritten by init. */
+export function agentFiles(folder) {
+    const ponder = instructions("ponder");
+    const thinking = "Chesspal's opponent thinking on the player's time. Started by the AI in the background after its move, as ai_move says.";
+    return [
+        { agent: quickAgent, model: "haiku", description: thinking, tools: ["ponder"], text: ponder },
+        { agent: ownAgent, model: "inherit", description: thinking, tools: ["ponder"], text: ponder },
+        // Its description tells the chat it starts the agent only as ai_move says, never to ask it about the game (Priya).
+        { agent: coachAgent, model: "inherit", description: "Chesspal's coach. Started only as Chesspal's answers say, in the background, never to answer the player.", tools: ["coach"], text: instructions("coach") },
+        {
+            agent: analystAgent,
+            model: "inherit",
+            description: "Chesspal's analyst. Started only as Chesspal's answers say, in the background, to review a game over on the board page; never to answer the player.",
+            tools: ["analyse_game", "annotate_game", "look", "position"],
+            text: `${instructions("analyst-agent")}\n${instructions("analysis")}`,
+        },
+    ].map(({ agent, model, description, tools, text }) => ({
+        path: agentPath(folder, agent),
+        // The tools it works with: Claude Code gives an agent its MCP tools loaded, with no search first (Priya).
+        text: ["---", `name: ${agent}`, `description: ${description}`, `tools: ${tools.map((tool) => `mcp__chesspal__${tool}`).join(", ")}`, `model: ${model}`, "---", "", text, ""].join("\n"),
+    }));
+}
+/** Instructions for the AI, by their file's name in the package's instructions folder. */
+export function instructions(name) {
+    return readFileSync(new URL(`../../instructions/${name}.md`, import.meta.url), "utf8").trim();
+}
+function agentPath(folder, agent) {
+    return join(folder, ".claude", "agents", `${agent}.md`);
+}

package/dist/host-files/host-files.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the opponent's instructions between
+ * Chesspal's marks, CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
+ * the files written.
+ */
+export declare function setUpHosts(folder: string, platform: string): string[];
+/**
+ * The files an older init wrote in a folder, or left out, that this version would write otherwise, by their paths in it: the AI and the page then ask the
+ * player to run init again. None in a folder init never set up.
+ */
+export declare function outdatedHostFiles(folder: string, platform: string): string[];
+/** Where Codex reads a folder's hooks, which it runs only once the player trusts them. */
+export declare function codexHooksPath(folder: string): string;
+/** The instructions of the AI opponent, read from the package wherever it is installed. */
+export declare function opponentInstructions(): string;

package/dist/host-files/host-files.js

@@ -0,0 +1,182 @@
+// What `chesspal init` writes in a player's folder for each AI host: the opponent's instructions, the MCP server, the hooks and the agents.
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { makeFolder, writeAtomically } from "../games/index.js";
+import { agentFiles, instructions } from "./agents.js";
+/**
+ * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the opponent's instructions between
+ * Chesspal's marks, CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
+ * the files written.
+ */
+export function setUpHosts(folder, platform) {
+    makeFolder(folder);
+    const written = hostChanges(folder, platform);
+    for (const { path, text } of written) {
+        makeFolder(join(path, ".."));
+        writeAtomically(path, text);
+    }
+    return written.map(({ path }) => path);
+}
+/**
+ * The files an older init wrote in a folder, or left out, that this version would write otherwise, by their paths in it: the AI and the page then ask the
+ * player to run init again. None in a folder init never set up.
+ */
+export function outdatedHostFiles(folder, platform) {
+    if (!markedBlock.test(textOf(join(folder, "AGENTS.md")) ?? "")) {
+        return [];
+    }
+    return hostChanges(folder, platform).map(({ path }) => relative(folder, path));
+}
+/** Where Codex reads a folder's hooks, which it runs only once the player trusts them. */
+export function codexHooksPath(folder) {
+    return join(folder, ".codex", "hooks.json");
+}
+/** The instructions of the AI opponent, read from the package wherever it is installed. */
+export function opponentInstructions() {
+    return instructions("opponent");
+}
+// The marks around Chesspal's lines in AGENTS.md: init rewrites what lies between them, and the player's own text stays around them.
+const startMark = "<!-- chesspal: these lines up to the end mark are Chesspal's, and chesspal init rewrites them; write your own after it. -->";
+const endMark = "<!-- chesspal: end -->";
+const markedBlock = /<!-- chesspal: (?!end)[^\n]*\n[\s\S]*?<!-- chesspal: end -->/;
+/** What init writes for each host, missing or changed: what the player wrote there stays. */
+function hostChanges(folder, platform) {
+    const changes = [mcpFile(folder, platform), agentsFile(folder), claudeFile(folder), claudeSettingsFile(folder), ...ponderAgentChanges(folder), codexConfigFile(folder, platform), codexHooksFile(folder)];
+    return changes.filter((change) => change !== undefined);
+}
+/** How a host starts the server: on Windows through cmd, which finds npm's shim. */
+function chesspalServer(platform) {
+    return platform === "win32" ? { command: "cmd", args: ["/c", "chesspal", "mcp"] } : { command: "chesspal", args: ["mcp"] };
+}
+/** Claude Code's agents that work on the player's time, thinking for the opponent and coaching, Chesspal's whole: written when they are missing or changed. */
+function ponderAgentChanges(folder) {
+    return agentFiles(folder).filter(({ path, text }) => textOf(path) !== text);
+}
+/** .mcp.json with the chesspal server, beside the servers already there, keeping the environment the player gave it, as CHESSPAL_HOME in a playtest. */
+function mcpFile(folder, platform) {
+    const path = join(folder, ".mcp.json");
+    const config = jsonOf(path);
+    const servers = isObject(config.mcpServers) ? config.mcpServers : {};
+    const before = isObject(servers.chesspal) ? servers.chesspal : {};
+    return changed(path, { ...config, mcpServers: { ...servers, chesspal: { ...chesspalServer(platform), ...(isObject(before.env) ? { env: before.env } : {}) } } });
+}
+/** AGENTS.md with the opponent's instructions between Chesspal's marks: rewritten when they changed, put first in a file that has none. */
+function agentsFile(folder) {
+    const path = join(folder, "AGENTS.md");
+    const before = textOf(path);
+    const block = [startMark, opponentInstructions(), endMark].join("\n");
+    if (before === undefined) {
+        return { path, text: `${block}\n` };
+    }
+    const text = markedBlock.test(before) ? before.replace(markedBlock, () => block) : `${block}\n\n${before}`;
+    return text === before ? undefined : { path, text };
+}
+/** CLAUDE.md, which Claude Code reads, importing AGENTS.md: the import put first in a file without it. */
+function claudeFile(folder) {
+    const path = join(folder, "CLAUDE.md");
+    const before = textOf(path);
+    if (before === undefined) {
+        return { path, text: "@AGENTS.md\n" };
+    }
+    return before.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md") ? undefined : { path, text: `@AGENTS.md\n${before}` };
+}
+/**
+ * Claude Code's settings: the chesspal server of .mcp.json approved and its tools allowed, so that the first chat asks for neither, and the doorbell of the
+ * moves on the page (D-47), and the note of how each chat starts (D-57); the player's own stay.
+ */
+function claudeSettingsFile(folder) {
+    const path = join(folder, ".claude", "settings.json");
+    const settings = jsonOf(path);
+    const permissions = isObject(settings.permissions) ? settings.permissions : {};
+    const hooks = isObject(settings.hooks) ? settings.hooks : {};
+    return changed(path, {
+        ...settings,
+        enabledMcpjsonServers: withItem(settings.enabledMcpjsonServers, "chesspal"),
+        permissions: { ...permissions, allow: withItem(permissions.allow, "mcp__chesspal") },
+        hooks: withHook(withHook(hooks, "Stop", bellHook), "SessionStart", chatHook),
+    });
+}
+/** The hooks with one of Chesspal's put back beside the player's own whenever it is missing; an event of theirs that is no list stays theirs. */
+function withHook(hooks, event, ours) {
+    const entries = hooks[event];
+    if (entries !== undefined && !Array.isArray(entries)) {
+        return hooks;
+    }
+    const list = (entries ?? []);
+    const there = list.some((entry) => isObject(entry) && Array.isArray(entry.hooks) && entry.hooks.some((hook) => isObject(hook) && hook.command === ours.command));
+    return there ? hooks : { ...hooks, [event]: [...list, { hooks: [ours] }] };
+}
+// Claude Code's Stop hook for the doorbell (D-47): it waits in the background from the end of each turn, and wakes the chat only when the player moves on
+// the page; a day at most, until the next turn starts another.
+const bellHook = { type: "command", command: "chesspal listen", asyncRewake: true, timeout: 86_400 };
+// Claude Code's SessionStart hook (D-57): it notes how each chat starts, so that a new game waits for a clean one.
+const chatHook = { type: "command", command: "chesspal chat" };
+/**
+ * Codex's settings, read once the player trusts the folder: the chesspal server with its tools approved, a table of Chesspal's rewritten but for the
+ * environment the player gave it, as CHESSPAL_HOME in a playtest; the rest stays.
+ */
+function codexConfigFile(folder, platform) {
+    const path = join(folder, ".codex", "config.toml");
+    const before = textOf(path) ?? "";
+    const { command, args } = chesspalServer(platform);
+    // The table runs up to the next one, or to the end; a header with a comment after it is the same table.
+    const ours = /^\s*\[mcp_servers\.chesspal\]\s*(#.*)?\r?\n[\s\S]*?(?=^\s*\[|(?![\s\S]))/m;
+    const environment = (ours.exec(before)?.[0].match(/^\s*env(?:_vars)?\s*=.*$/gm) ?? []).map((line) => `${line.trim()}\n`).join("");
+    const table = `[mcp_servers.chesspal]\ncommand = ${JSON.stringify(command)}\nargs = [${args.map((arg) => JSON.stringify(arg)).join(", ")}]\ndefault_tools_approval_mode = "approve"\n${environment}`;
+    const rest = before.replace(ours, "").trim();
+    const text = rest === "" ? table : `${rest}\n\n${table}`;
+    return text === before ? undefined : { path, text };
+}
+/** Codex's hooks, read once the player has trusted them: the doorbell of the moves on the page and how each chat starts, beside the player's own. */
+function codexHooksFile(folder) {
+    const path = codexHooksPath(folder);
+    const config = jsonOf(path);
+    const hooks = isObject(config.hooks) ? config.hooks : {};
+    return changed(path, { ...config, hooks: withHook(withHook(hooks, "Stop", codexBellHook), "SessionStart", codexChatHook) });
+}
+// Codex's Stop hook for the doorbell: it holds the turn until the player acts on the page, then Codex goes on; a day at most. On Windows Codex runs
+// it in PowerShell, where `chesspal` would be npm's .ps1 shim, which a strict execution policy stops.
+const codexBellHook = {
+    type: "command",
+    command: "chesspal listen --codex",
+    commandWindows: "chesspal.cmd listen --codex",
+    timeout: 86_400,
+    statusMessage: "Waiting for your move on the board page",
+};
+// Codex's SessionStart hook: it notes how each chat starts, as Claude Code's does (D-57).
+const codexChatHook = { type: "command", command: "chesspal chat", commandWindows: "chesspal.cmd chat" };
+/** A JSON file's new content, when it differs from what is there. */
+function changed(path, value) {
+    const text = `${JSON.stringify(value, null, 2)}\n`;
+    return textOf(path) === text ? undefined : { path, text };
+}
+/** A list with an item added when it is missing; a value that is no list becomes one. */
+function withItem(list, item) {
+    const items = Array.isArray(list) ? list : [];
+    return items.includes(item) ? items : [...items, item];
+}
+/** The object a JSON file holds, empty when there is no file; a file that is not a JSON object stops init with how to fix it. */
+function jsonOf(path) {
+    const text = textOf(path);
+    if (text === undefined) {
+        return {};
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = undefined;
+    }
+    if (!isObject(value)) {
+        throw new Error(`${path} is not a JSON object, so Chesspal cannot add itself to it: fix it or remove it, then run chesspal init again.`);
+    }
+    return value;
+}
+function textOf(path) {
+    // Windows PowerShell and Notepad may start a file with a byte order mark, which JSON.parse refuses.
+    return existsSync(path) ? readFileSync(path, "utf8").replace(/^/, "") : undefined;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/host-files/index.d.ts

@@ -0,0 +1,2 @@
+export { analystAgent, coachAgent, hasAgent, instructions, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.ts";
+export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts } from "./host-files.ts";

package/dist/host-files/index.js

@@ -0,0 +1,3 @@
+// The files through which an AI host finds Chesspal in the player's folder: the server, the opponent's instructions, the hosts' settings.
+export { analystAgent, coachAgent, hasAgent, instructions, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.js";
+export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts } from "./host-files.js";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type AnyCommand, type Command, commands, type Context } from "./commands/index.ts";
+export { version } from "./version.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+// Chesspal's public API: what a program that imports the package reaches.
+export { commands } from "./commands/index.js";
+export { version } from "./version.js";