chesspal 0.0.1 → 0.1.0

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

@@ -0,0 +1,10 @@
+/**
+ * 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[];
+/** Where Codex reads a folder's hooks, which it runs only once the player allows them in /hooks (T-125). */
+export declare function codexHooksPath(folder: string): string;
+/** The instructions of the AI opponent, read from the package wherever it is installed (T-8). */
+export declare function opponentInstructions(): string;

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

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { makeFolder, writeAtomically } from "../games/index.js";
+import { ponderAgentFiles } from "./ponder-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 changes = [mcpFile(folder, platform), agentsFile(folder), claudeFile(folder), claudeSettingsFile(folder), ...ponderAgentChanges(folder), codexConfigFile(folder, platform), codexHooksFile(folder)];
+    const written = changes.filter((change) => change !== undefined);
+    for (const { path, text } of written) {
+        makeFolder(join(path, ".."));
+        writeAtomically(path, text);
+    }
+    return written.map(({ path }) => path);
+}
+/** Where Codex reads a folder's hooks, which it runs only once the player allows them in /hooks (T-125). */
+export function codexHooksPath(folder) {
+    return join(folder, ".codex", "hooks.json");
+}
+/** The instructions of the AI opponent, read from the package wherever it is installed (T-8). */
+export function opponentInstructions() {
+    return readFileSync(new URL("../../instructions/opponent.md", import.meta.url), "utf8").trim();
+}
+// 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 -->/;
+/** 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 think on the player's time, Chesspal's whole: written when they are missing or changed. */
+function ponderAgentChanges(folder) {
+    return ponderAgentFiles(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 reviewed them in /hooks: the doorbell of the moves on the page (T-62) and how each chat starts (T-104), 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 (T-62): 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 (T-104): 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 { codexHooksPath, opponentInstructions, setUpHosts } from "./host-files.ts";
+export { hasPonderAgent, onQuickModel, ponderAgentFor } from "./ponder-agents.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 (T-7): the server, the opponent's instructions, the hosts' settings.
+export { codexHooksPath, opponentInstructions, setUpHosts } from "./host-files.js";
+export { hasPonderAgent, onQuickModel, ponderAgentFor } from "./ponder-agents.js";

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

@@ -0,0 +1,12 @@
+import type { AiLevel } from "../core/index.ts";
+/** 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 hasPonderAgent(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 ponderAgentFiles(folder: string): {
+    path: string;
+    text: string;
+}[];

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

@@ -0,0 +1,40 @@
+// The agents that think on the player's time in Claude Code (D-72): one on the host's quick model for the lower levels, one on the AI's own for the higher.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** 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 hasPonderAgent(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 ponderAgentFiles(folder) {
+    const instructions = readFileSync(new URL("../../instructions/ponder.md", import.meta.url), "utf8").trim();
+    return [{ agent: quickAgent, model: "haiku" }, { agent: ownAgent, model: "inherit" }].map(({ agent, model }) => ({
+        path: agentPath(folder, agent),
+        text: [
+            "---",
+            `name: ${agent}`,
+            "description: Chesspal's opponent thinking on the player's time. Started by the AI in the background after its move, as ai_move says.",
+            `tools: ${tools.join(", ")}`,
+            `model: ${model}`,
+            "---",
+            "",
+            instructions,
+            "",
+        ].join("\n"),
+    }));
+}
+const quickAgent = "chesspal-ponder-quick";
+const ownAgent = "chesspal-ponder";
+// The one tool it works with: Claude Code gives an agent its MCP tools loaded, with no search first (Priya, round of T-109).
+const tools = ["mcp__chesspal__ponder"];
+function agentPath(folder, agent) {
+    return join(folder, ".claude", "agents", `${agent}.md`);
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,2 @@
+export { commands } from "./commands/index.js";
+export { version } from "./version.js";