chesspal 0.0.1 → 0.2.0

package/dist/commands/position.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { type Profile } from "../core/index.ts";
+/** The positional profile of a position: of a game studied, with where it stands. */
+type Described = Profile & {
+    where?: string;
+};
+/** The positional profile of the game in progress (D-19), or of any position of a game over (D-68): separate facts, never a score. */
+export declare const position: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    move: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Described>;
+/** The profile as lines for the AI, White's facts before Black's; a line with nothing to say is left out. */
+export declare function profileLines(profile: Profile): string[];
+export {};

package/dist/commands/position.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import {} from "../core/index.js";
+import { analystAgent } from "../host-files/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+import { refuseUnseen } from "./levels.js";
+import { defineCommand } from "./registry.js";
+import { gameToStudy, positionAfter, positionLine, studyInput } from "./study.js";
+import { colourName, materialText } from "./view.js";
+/** The positional profile of the game in progress (D-19), or of any position of a game over (D-68): separate facts, never a score. */
+export const position = defineCommand({
+    name: "position",
+    description: "Shows the positional facts of the position, from the strong level up and at every level once the game is over: material, pawns (isolated, doubled, backward, passed, islands), open files, rooks and queens on the seventh, bishops, "
+        + "outposts, centre, space, control, mobility, development and castling, king safety, the phase, the draw rules and, with only kings and pawns, "
+        + "the rule of the square and the opposition. Facts only, never a score: weigh them yourself. Call it when you set or change your plan: out of "
+        + "the opening, after a big exchange, in the endgame; not at every move. With move, and game for a game of the archive, the facts of any position of a "
+        + 'game over, to analyse it. Example: position {}, position {move: "24."}.',
+    input: z.object(studyInput),
+    readOnly: true,
+    idempotent: true,
+    sharedWith: [analystAgent],
+    run: ({ game, move }, context) => {
+        if (game !== undefined || move !== undefined) {
+            const studied = gameToStudy(context, game);
+            const at = positionAfter(studied.record, move);
+            return { ...at.game.profile, where: positionLine(at, studied.name) };
+        }
+        const current = gameAt(gameFolder(context.home()), context.now());
+        if (current === undefined) {
+            throw new Error("There is no game to describe: start one with new_game.");
+        }
+        refuseUnseen(current, "strategy", "position");
+        return current.game.profile;
+    },
+    format: (described) => [...(described.where === undefined ? [] : [described.where]), ...profileLines(described)].join("\n"),
+});
+/** The profile as lines for the AI, White's facts before Black's; a line with nothing to say is left out. */
+export function profileLines(profile) {
+    const sides = [["white", profile.white], ["black", profile.black]];
+    const perSide = (line) => sides.map(([side, facts]) => {
+        const text = line(facts);
+        return text === undefined ? undefined : `${colourName(side)} ${text}`;
+    }).filter((text) => text !== undefined).join("; ");
+    const lines = [
+        `Phase: ${profile.phase}`,
+        `Material: ${materialText(profile.material)}`,
+        ...sides.map(([side, facts]) => pawnLine(side, facts)),
+        filesLine(profile),
+        seventhLine(perSide((side) => joined(side.onSeventh))),
+        bishopsLine(profile),
+        `Outposts: ${perSide((side) => joined(side.outposts.map((outpost) => (outpost.piece === undefined ? outpost.square : `${outpost.piece}${outpost.square}`)))) || "none"}`,
+        `Centre (White/Black pieces reaching it): ${profile.centre.map(centreText).join(", ")}`,
+        `Space (squares of the other half attacked): White ${profile.white.space}, Black ${profile.black.space}`,
+        `Control: only White ${profile.controlled.white}, only Black ${profile.controlled.black}, both ${profile.controlled.contested}`,
+        `Mobility: ${perSide((side) => (side.mobility === undefined ? undefined : mobilityText(side.mobility)))}`,
+        `Development: ${perSide(developmentText)}`,
+        ...sides.flatMap(([side, facts]) => (facts.king === undefined ? [] : [kingLine(side, facts.king)])),
+        drawLine(profile),
+        ...endingLines(profile),
+    ];
+    return lines.filter((line) => line !== "");
+}
+const pieceOrder = ["K", "Q", "R", "B", "N", "P"];
+function pawnLine(side, { pawns }) {
+    const kinds = [["isolated", pawns.isolated], ["doubled", pawns.doubled], ["backward", pawns.backward], ["passed", pawns.passed]];
+    const named = kinds.filter(([, squares]) => squares.length > 0).map(([kind, squares]) => `${kind} ${squares.join(" ")}`);
+    return `${colourName(side)} pawns: ${[...named, `islands ${pawns.islands.join(", ") || "none"}`].join("; ")}`;
+}
+function filesLine(profile) {
+    const parts = [
+        profile.openFiles.length === 0 ? "" : `open ${profile.openFiles.join(" ")}`,
+        ...["white", "black"].map((side) => {
+            const files = profile[side].halfOpenFiles;
+            return files.length === 0 ? "" : `half-open for ${colourName(side)} ${files.join(" ")}`;
+        }),
+        ...["white", "black"].map((side) => {
+            const heavy = profile[side].heavyOnFiles;
+            return heavy.length === 0 ? "" : `${colourName(side)} heavy pieces on them ${heavy.join(" ")}`;
+        }),
+    ].filter((part) => part !== "");
+    return `Files: ${parts.join("; ") || "no open or half-open file"}`;
+}
+function seventhLine(pieces) {
+    return pieces === "" ? "" : `Rooks and queens on the seventh rank (the second for Black): ${pieces}`;
+}
+function bishopsLine(profile) {
+    const parts = ["white", "black"].flatMap((side) => {
+        const facts = profile[side];
+        const each = facts.bishops.map((bishop) => `B${bishop.square} ${bishop.pawnsOnColour}/${bishop.pawns}`);
+        return each.length === 0 ? [] : [`${colourName(side)}${facts.bishopPair ? " (pair)" : ""} ${each.join(", ")}`];
+    });
+    return parts.length === 0 ? "" : `Bishops (own pawns on its colour/all): ${parts.join("; ")}${profile.oppositeBishops ? "; opposite-coloured" : ""}`;
+}
+function centreText({ square, piece, white, black }) {
+    const on = piece === undefined ? "" : ` ${colourName(piece.side)} ${piece.letter}`;
+    return `${square}${on} ${white}/${black}`;
+}
+function mobilityText(mobility) {
+    const total = Object.values(mobility).reduce((sum, count) => sum + count, 0);
+    return total === 0 ? "0" : `${total} (${pieceOrder.filter((letter) => mobility[letter] !== undefined).map((letter) => `${letter}${mobility[letter]}`).join(" ")})`;
+}
+function developmentText(side) {
+    const castled = side.castled === undefined ? "" : side.castled === "no" ? "not castled" : `castled ${side.castled}`;
+    const rights = side.castlingRights.length === 0 ? "" : `may castle ${side.castlingRights.join(" ")}`;
+    const home = side.undeveloped.length === 0 ? "" : `at home ${side.undeveloped.join(" ")}`;
+    return [castled, rights, home].filter((part) => part !== "").join(", ") || "nothing to say";
+}
+function kingLine(side, king) {
+    const files = king.openFiles.length === 0 ? "" : `, no own pawn on ${king.openFiles.join(" ")}`;
+    return `${colourName(side)} K${king.square}: shield ${king.shield.join(" ") || "none"}${files}, enemy attacks around it ${king.attacksNear}`;
+}
+function drawLine({ draw }) {
+    const parts = [
+        draw.repetitions > 1 ? `position seen ${draw.repetitions} times` : "",
+        draw.fiftyMovesLeft <= 20 ? `${draw.fiftyMovesLeft} half-moves left before the fifty-move draw` : "",
+        draw.insufficient ? "material insufficient to mate" : "",
+    ].filter((part) => part !== "");
+    return parts.length === 0 ? "" : `Draw rules: ${parts.join("; ")}`;
+}
+function endingLines({ pawnEnding }) {
+    if (pawnEnding === undefined) {
+        return [];
+    }
+    const squares = pawnEnding.squares.map((square) => `${square.pawn} ${square.caught ? "inside" : "outside"} the enemy king's square`);
+    const opposition = pawnEnding.opposition === undefined ? "nobody" : colourName(pawnEnding.opposition);
+    return [`Pawn ending: ${[...squares, `opposition: ${opposition}`].join("; ")}`];
+}
+function joined(items) {
+    return items.length === 0 ? undefined : items.join(" ");
+}

package/dist/commands/profiles.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { type DrawnAvatar, type PlayerProfile } from "../profiles/index.ts";
+import type { Context } from "./context.ts";
+/** A change of profile refused while a game goes on: the page says it in the player's language. */
+export declare class GameGoingOn extends Error {
+    constructor();
+}
+/** The profiles, the one in use first. */
+export declare const profiles: import("./registry.ts").Command<z.ZodObject<{}, z.core.$strip>, {
+    profiles: PlayerProfile[];
+    active: string;
+}>;
+/**
+ * A new profile, put in use unless asked not to; while a game goes on it is made all the same and waits, the player in use staying. The one Chesspal made at
+ * the first start, while new, becomes it, game and all (D-71).
+ */
+export declare const newProfile: import("./registry.ts").Command<z.ZodObject<{
+    name: z.ZodString;
+    level: z.ZodOptional<z.ZodEnum<{
+        learning: "learning";
+        casual: "casual";
+        regular: "regular";
+        tournament: "tournament";
+    }>>;
+    rating: z.ZodOptional<z.ZodInt>;
+    site: z.ZodOptional<z.ZodEnum<{
+        lichess: "lichess";
+        "chess.com": "chess.com";
+        fide: "fide";
+    }>>;
+    avatar: z.ZodOptional<z.ZodEnum<{
+        "short-hair": "short-hair";
+        bun: "bun";
+        glasses: "glasses";
+        beanie: "beanie";
+        beard: "beard";
+        curls: "curls";
+        moustache: "moustache";
+        "silver-bob": "silver-bob";
+        cat: "cat";
+        owl: "owl";
+    }>>;
+    use: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, PlayerProfile & {
+    readonly inUse: boolean;
+}>;
+/** Another profile put in use, once the game going on has ended. */
+export declare const useProfile: import("./registry.ts").Command<z.ZodObject<{
+    profile: z.ZodString;
+}, z.core.$strip>, PlayerProfile>;
+/** The picture of the profile in use: a drawn avatar, or an image of the player's, which replaces any before. */
+export declare const setAvatar: import("./registry.ts").Command<z.ZodObject<{
+    avatar: z.ZodString;
+}, z.core.$strip>, {
+    profile: string;
+    avatar: string;
+}>;
+/** The player's names on Lichess and chess.com, by which the games they load are theirs (D-93): each one given is written, an empty one goes. */
+export declare const setAccounts: import("./registry.ts").Command<z.ZodObject<{
+    lichess: z.ZodOptional<z.ZodString>;
+    chesscom: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, PlayerProfile>;
+/** A drawn avatar chosen for a profile: the player's own image goes, or it would still show. */
+export declare function chooseDrawnAvatar(context: Context, id: string, avatar: DrawnAvatar): void;
+/**
+ * Who plays, as the AI reads it in status and new_game: their name, how they play and their rating; nothing while the profile is new, named after the
+ * system's account until the player completes it (D-71).
+ */
+export declare function playerLine(context: Context): string | undefined;

package/dist/commands/profiles.js

@@ -0,0 +1,163 @@
+// The players' profiles (D-23), on the command line and the board page: listed, made, put in use, with their picture (D-45). The AI reads only who plays.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { endOf } from "../games/index.js";
+import { activateProfile, activeProfile, createProfile, drawnAvatars, gameFolder, levels, listProfiles, nameLimit, ratingLimits, ratingSites, removeOwnImage, saveOwnImage, updateProfile, } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+import { defineCommand } from "./registry.js";
+/** A change of profile refused while a game goes on: the page says it in the player's language. */
+export class GameGoingOn extends Error {
+    constructor() {
+        super("A game is going on in this profile: finish it, or resign, before changing profile. Nothing changed.");
+    }
+}
+/** The profiles, the one in use first. */
+export const profiles = defineCommand({
+    name: "profiles",
+    description: "Lists the players' profiles, the one in use marked with *. Example: chesspal profiles.",
+    input: z.object({}),
+    cliOnly: true,
+    readOnly: true,
+    idempotent: true,
+    run: (input, context) => ({ profiles: listProfiles(context.home()), active: activeProfile(context.home()).id }),
+    format: ({ profiles, active }) => profiles.map((profile) => `${profile.id === active ? "*" : " "} ${profile.id}: ${playerText(profile)}`).join("\n"),
+});
+/**
+ * A new profile, put in use unless asked not to; while a game goes on it is made all the same and waits, the player in use staying. The one Chesspal made at
+ * the first start, while new, becomes it, game and all (D-71).
+ */
+export const newProfile = defineCommand({
+    name: "new_profile",
+    description: "Makes a player's profile and puts it in use, unless --use false or a game is going on: their games, picture and page settings go in "
+        + "profiles/<id>/ of Chesspal's data folder; the profile Chesspal made at the first start becomes this one, its folder renamed, while nobody has completed "
+        + "it. Example: chesspal new_profile Anna --level regular --rating 1450 --site lichess.",
+    input: z.object({
+        name: z.string().trim().min(1).max(nameLimit).regex(/^[^\p{Cc}]+$/u, "one line of text").describe("the player's name"),
+        level: z.enum(levels).optional().describe("how they play: learning, casual, regular or tournament"),
+        rating: z.int().min(ratingLimits.lowest).max(ratingLimits.highest).optional().describe("their rating, with site"),
+        site: z.enum(ratingSites).optional().describe("where the rating comes from: lichess, chess.com or fide"),
+        avatar: z.enum(drawnAvatars).optional().describe(`a drawn avatar: ${drawnAvatars.join(", ")}`),
+        use: z.boolean().optional().describe("false to make it without putting it in use"),
+    }),
+    cliOnly: true,
+    positionals: ["name"],
+    run: ({ name, level, rating, site, avatar, use }, context) => {
+        if ((rating === undefined) !== (site === undefined)) {
+            throw new Error("Give the rating and its site together, such as --rating 1450 --site lichess, or neither. Nothing changed.");
+        }
+        const first = activeProfile(context.home()).new === true;
+        const inUse = first || (use !== false && !isPlaying(context));
+        const profile = createProfile(context.home(), {
+            name,
+            ...(level === undefined ? {} : { level }),
+            ...(rating === undefined || site === undefined ? {} : { rating: { value: rating, site } }),
+            ...(avatar === undefined ? {} : { avatar }),
+        }, inUse);
+        return { ...profile, inUse };
+    },
+    format: (profile) => `Profile ${profile.id} made${profile.inUse ? ", and in use" : ", not in use"}: ${playerText(profile)}.`,
+});
+/** Another profile put in use, once the game going on has ended. */
+export const useProfile = defineCommand({
+    name: "use_profile",
+    description: "Puts another player's profile in use, with its games; refused while a game is going on. Example: chesspal use_profile anna.",
+    input: z.object({ profile: z.string().min(1).describe("the profile, as chesspal profiles lists it") }),
+    cliOnly: true,
+    idempotent: true,
+    positionals: ["profile"],
+    run: ({ profile }, context) => {
+        const active = activeProfile(context.home());
+        if (active.id === profile) {
+            return active;
+        }
+        refuseWhilePlaying(context);
+        return activateProfile(context.home(), profile);
+    },
+    format: (profile) => `Profile ${profile.id} in use: ${playerText(profile)}.`,
+});
+/** The picture of the profile in use: a drawn avatar, or an image of the player's, which replaces any before. */
+export const setAvatar = defineCommand({
+    name: "set_avatar",
+    description: `Sets the picture of the profile in use: a drawn avatar (${drawnAvatars.join(", ")}) or the path of a PNG, JPEG or WebP image of `
+        + "1 MB at most. Example: chesspal set_avatar owl.",
+    input: z.object({ avatar: z.string().min(1).describe("a drawn avatar, or the path of an image") }),
+    cliOnly: true,
+    idempotent: true,
+    positionals: ["avatar"],
+    run: ({ avatar }, context) => {
+        const profile = activeProfile(context.home());
+        const drawn = drawnAvatars.find((one) => one === avatar);
+        if (drawn === undefined) {
+            saveOwnImage(context.home(), profile.id, imageFile(resolve(context.folder, avatar)));
+        }
+        else {
+            chooseDrawnAvatar(context, profile.id, drawn);
+        }
+        return { profile: profile.id, avatar };
+    },
+    format: ({ profile, avatar }) => `The picture of ${profile} is ${avatar}.`,
+});
+/** The player's names on Lichess and chess.com, by which the games they load are theirs (D-93): each one given is written, an empty one goes. */
+export const setAccounts = defineCommand({
+    name: "set_accounts",
+    description: "Sets the player's names on Lichess and chess.com in the profile in use, by which a game loaded from there is theirs; an empty name removes it. "
+        + "Example: chesspal set_accounts --lichess anna_k --chesscom AnnaK.",
+    input: z.object({
+        lichess: accountName().optional().describe("the player's name on Lichess"),
+        chesscom: accountName().optional().describe("the player's name on chess.com"),
+    }),
+    cliOnly: true,
+    idempotent: true,
+    run: (names, context) => {
+        const profile = activeProfile(context.home());
+        const lichess = names.lichess ?? profile.accounts?.lichess ?? "";
+        const chesscom = names.chesscom ?? profile.accounts?.chesscom ?? "";
+        return updateProfile(context.home(), profile.id, { accounts: { ...(lichess === "" ? {} : { lichess }), ...(chesscom === "" ? {} : { chesscom }) } });
+    },
+    format: (profile) => `${profile.id} is ${accountsText(profile.accounts)}.`,
+});
+/** A drawn avatar chosen for a profile: the player's own image goes, or it would still show. */
+export function chooseDrawnAvatar(context, id, avatar) {
+    updateProfile(context.home(), id, { avatar });
+    removeOwnImage(context.home(), id);
+}
+/**
+ * Who plays, as the AI reads it in status and new_game: their name, how they play and their rating; nothing while the profile is new, named after the
+ * system's account until the player completes it (D-71).
+ */
+export function playerLine(context) {
+    const profile = activeProfile(context.home());
+    return profile.new === true ? undefined : `Player: ${playerText(profile)}.`;
+}
+/** Throws while a game goes on in the profile in use. */
+function refuseWhilePlaying(context) {
+    if (isPlaying(context)) {
+        throw new GameGoingOn();
+    }
+}
+function isPlaying(context) {
+    const current = gameAt(gameFolder(context.home()), context.now());
+    return current !== undefined && endOf(current.game) === undefined;
+}
+const levelText = { learning: "has just learned", casual: "plays now and then", regular: "plays often", tournament: "plays tournaments" };
+const siteText = { "lichess": "Lichess", "chess.com": "Chess.com", "fide": "FIDE" };
+function playerText({ name, level, rating }) {
+    return [name, ...(level === undefined ? [] : [levelText[level]]), ...(rating === undefined ? [] : [`${siteText[rating.site]} ${rating.value}`])].join(", ");
+}
+/** A name on Lichess or chess.com: their letters, digits, underscores and hyphens; empty to remove it. */
+function accountName() {
+    return z.string().trim().max(nameLimit).regex(/^[\w-]*$/, "A name on Lichess or chess.com has only letters, digits, underscores and hyphens.");
+}
+function accountsText(accounts) {
+    const named = [...(accounts?.lichess === undefined ? [] : [`${accounts.lichess} on Lichess`]), ...(accounts?.chesscom === undefined ? [] : [`${accounts.chesscom} on chess.com`])];
+    return named.length === 0 ? "on neither Lichess nor chess.com" : named.join(" and ");
+}
+function imageFile(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (error) {
+        throw new Error(`${path} cannot be read (${error.message}): give a drawn avatar's name, or the path of an image. Nothing changed.`, { cause: error });
+    }
+}

package/dist/commands/registry.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import type { Context } from "./context.ts";
+/** A command is defined once: the command line and the MCP server are generated from it (D-5); the page's routes call the same commands. */
+export interface Command<Schema extends z.ZodObject = z.ZodObject, Result = unknown> {
+    name: string;
+    /** Written for an AI: what the command does (the first sentence, shown in the list of commands), when to use it, an example. */
+    description: string;
+    input: Schema;
+    /** The command changes nothing: hosts may run it without asking. */
+    readOnly?: boolean;
+    /** The command deletes or overwrites what the player keeps, such as a game: hosts may ask first. */
+    destructive?: boolean;
+    /** Calling the command again with the same input changes nothing more. */
+    idempotent?: boolean;
+    /** Hosts load the tool at once instead of on demand: for the ones the AI calls at the start of every chat. */
+    alwaysLoad?: boolean;
+    /** Its answer shows the chat the game as it is: the chat may move on it, and on no other (D-71). */
+    showsGame?: boolean;
+    /**
+     * The agents that call it apart from the chat, as ponder (D-72), by their names: the doorbell's record of what the chat has read stays as it was, and the
+     * server refuses it to the chat and to other agents (Priya).
+     */
+    byAgents?: readonly string[];
+    /** The agents that call it besides the chat, as the analyst analyse_game (D-89): their calls leave the doorbell's record of what the chat has read as it was. */
+    sharedWith?: readonly string[];
+    /** The only host the MCP server offers it to, by the client's name, as ponder to Claude Code: elsewhere its description would cost tokens for nothing. */
+    host?: string;
+    /** Only the command line has it, as init: the MCP server leaves it out, and its description costs the AI no tokens. */
+    cliOnly?: boolean;
+    /** Fields the command line takes as positional arguments, in order. */
+    positionals?: Extract<keyof Schema["shape"], string>[];
+    /** Returns a value, never prints: the MCP server speaks on stdout, and only the command line writes there. */
+    run(input: z.infer<Schema>, context: Context): Result | Promise<Result>;
+    /** Plain-text rendering of the result, for the AI and the terminal alike; the context, for a command that speaks to the player, as init. */
+    format(result: Result, context?: Context): string;
+}
+export type AnyCommand = Command<any, any>;
+/** Checks a command's types where it is written; the command is used as it is. */
+export declare function defineCommand<Schema extends z.ZodObject, Result>(command: Command<Schema, Result>): Command<Schema, Result>;
+/** One sentence of the AI's, kept in a PGN comment: no brackets or braces, which would break it. */
+export declare function sentence(most: number): z.ZodString;
+/**
+ * Why an input is refused, in words an AI can act on, the same on the command line and in MCP: one sentence for each problem, each parameter written as
+ * the caller writes it (colour, --colour).
+ */
+export declare function inputProblems(command: string, issues: readonly z.core.$ZodIssue[], given: Record<string, unknown>, written: (name: string) => string): string;
+/**
+ * What keeps a field of a command's input from being given on the command line: one named no-x, read as turning x off, or json, read as answering in JSON;
+ * undefined for any other. A positional is never an option, so json is its name freely.
+ */
+export declare function commandLineFieldProblem(command: string, name: string, positional: boolean): string | undefined;
+/** Whether a field of a command's input is a flag, true or false, as --hidden. */
+export declare function isBoolean(field: z.ZodType): boolean;
+/** A list option can be given more than once, as in --tag a --tag b. */
+export declare function isList(field: z.ZodType): boolean;
+/** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
+export declare function baseType(field: z.ZodType): string;
+/** Whether a field takes numbers, alone or in a list: the command line reads them as text and turns them into numbers. */
+export declare function takesNumbers(field: z.ZodType): boolean;

package/dist/commands/registry.js

@@ -0,0 +1,62 @@
+// What a command is, and the reading of its input schema that the command line and the MCP server share.
+import { z } from "zod";
+/** Checks a command's types where it is written; the command is used as it is. */
+export function defineCommand(command) {
+    return command;
+}
+/** One sentence of the AI's, kept in a PGN comment: no brackets or braces, which would break it. */
+export function sentence(most) {
+    return z.string().trim().min(1, "write one sentence").max(most, `write one sentence of ${most} characters at most`).regex(/^[^[\]{}]*$/, "write it without [ ] { }");
+}
+/**
+ * Why an input is refused, in words an AI can act on, the same on the command line and in MCP: one sentence for each problem, each parameter written as
+ * the caller writes it (colour, --colour).
+ */
+export function inputProblems(command, issues, given, written) {
+    return issues.map((issue) => inputIssue(command, issue, given, written)).join(" ");
+}
+/**
+ * What keeps a field of a command's input from being given on the command line: one named no-x, read as turning x off, or json, read as answering in JSON;
+ * undefined for any other. A positional is never an option, so json is its name freely.
+ */
+export function commandLineFieldProblem(command, name, positional) {
+    if (name.startsWith("no-")) {
+        return `${command} has a field named ${name}, and none may start with no-, which the command line reads as turning ${name.slice(3)} off: rename it.`;
+    }
+    return name === "json" && !positional ? `${command} has a field named json, which the command line reads as answering in JSON: rename it.` : undefined;
+}
+/** Whether a field of a command's input is a flag, true or false, as --hidden. */
+export function isBoolean(field) {
+    return baseDefinition(field).type === "boolean";
+}
+/** A list option can be given more than once, as in --tag a --tag b. */
+export function isList(field) {
+    return baseDefinition(field).type === "array";
+}
+/** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
+export function baseType(field) {
+    return baseDefinition(field).type;
+}
+/** Whether a field takes numbers, alone or in a list: the command line reads them as text and turns them into numbers. */
+export function takesNumbers(field) {
+    const definition = baseDefinition(field);
+    return definition.type === "number" || (definition.type === "array" && definition.element !== undefined && baseType(definition.element) === "number");
+}
+function inputIssue(command, issue, given, written) {
+    const path = issue.path.map(String).join(".");
+    if (issue.code === "unrecognized_keys") {
+        return path === "" ? `${command} has no parameter ${issue.keys.map(written).join(", ")}.` : `${written(path)} has no ${issue.keys.join(", ")}.`;
+    }
+    // A parameter left out, whatever zod calls it.
+    if (issue.path.length === 1 && given[path] === undefined) {
+        return `${command} needs ${written(path)}.`;
+    }
+    return path === "" ? `${issue.message}.` : `${written(path)}: ${issue.message}.`;
+}
+function baseDefinition(field) {
+    let definition = field.def;
+    while (definition.innerType && ["optional", "default", "nullable"].includes(definition.type)) {
+        definition = definition.innerType.def;
+    }
+    return definition;
+}

package/dist/commands/say.d.ts

@@ -0,0 +1,16 @@
+import { type Mood } from "../core/index.ts";
+import { type Sayer, type Talk, type Words } from "../games/index.ts";
+import type { Context } from "./context.ts";
+/**
+ * Adds a line to the talk of the current game, going on or just over, and saves it; the AI's mood once the game is over, which the archive keeps too (D-70).
+ * With no game the line goes in the talk before it (D-77). A line refused changes nothing: it throws, in words for whoever spoke.
+ */
+export declare function say(folder: string, who: Sayer, text: string, at: Date, mood?: Mood): Talk;
+/** What the player wrote on the board page that the AI has not been given in this chat, given now: each game tool gives it once; never to an agent (D-89). */
+export declare function newWords(context: Context): string[];
+/** Every word of the player's the AI has not answered, given again: status gives them all, for a chat that lost them in a summary. */
+export declare function unansweredWords(context: Context): string[];
+/** What the player wrote on the board page that the AI has not been given in this chat, still to give: the AI's move would count as its answer. */
+export declare function waitingWords(context: Context, given?: ReadonlySet<string>): Words[];
+/** Gives the words to the AI: from now on they count as given in this chat. Their text. */
+export declare function give(context: Context, words: readonly Words[]): string[];

package/dist/commands/say.js

@@ -0,0 +1,84 @@
+// The talk on the board page (D-51): a line of the player's or the AI's, saved with the game, and the player's words the AI has not been given yet.
+import { endWithMood } from "../core/index.js";
+import { archiveEnded, endOf, loadGame, loadTableTalk, saveGame, saveTableTalk, talkLimits, talkLine, unheardWords } from "../games/index.js";
+import { gameFolder, helpsIn } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+/**
+ * Adds a line to the talk of the current game, going on or just over, and saves it; the AI's mood once the game is over, which the archive keeps too (D-70).
+ * With no game the line goes in the talk before it (D-77). A line refused changes nothing: it throws, in words for whoever spoke.
+ */
+export function say(folder, who, text, at, mood) {
+    const current = gameAt(folder, at);
+    if (current === undefined) {
+        return sayAtTable(folder, who, text, at, mood);
+    }
+    if (mood !== undefined && endOf(current.game) === undefined) {
+        throw new Error("While the game goes on your mood comes with ai_move: say it without mood. Nothing changed.");
+    }
+    // With the helps on the AI writes as long as the analyst (D-78).
+    current.talk.push(talkLine(current, who, text, at, undefined, aiMost(folder, who, text)));
+    if (mood !== undefined) {
+        endWithMood(current.game, mood);
+    }
+    saveGame(folder, current);
+    if (mood !== undefined) {
+        archiveEnded(folder, current);
+    }
+    return current;
+}
+/** What the player wrote on the board page that the AI has not been given in this chat, given now: each game tool gives it once; never to an agent (D-89). */
+export function newWords(context) {
+    return context.agent === undefined ? give(context, waitingWords(context)) : [];
+}
+/** Every word of the player's the AI has not answered, given again: status gives them all, for a chat that lost them in a summary. */
+export function unansweredWords(context) {
+    return give(context, waitingWords(context, new Set()));
+}
+/** What the player wrote on the board page that the AI has not been given in this chat, still to give: the AI's move would count as its answer. */
+export function waitingWords(context, given = context.given) {
+    try {
+        const folder = gameFolder(context.home());
+        return unheardWords(loadGame(folder) ?? loadTableTalk(folder), given);
+    }
+    catch {
+        // A game.json that cannot be read: the tool says so in its own words.
+        return [];
+    }
+}
+/** Gives the words to the AI: from now on they count as given in this chat. Their text. */
+export function give(context, words) {
+    const before = context.given.size;
+    for (const { key } of words) {
+        context.given.add(key);
+    }
+    if (context.given.size > before) {
+        context.heard?.();
+    }
+    return words.map(({ text }) => text);
+}
+/** The most a line of the AI's may hold in the games of `folder`: an analyst's note with the helps on (D-78); a longer one with them off is refused. */
+function aiMost(folder, who, text) {
+    if (who !== "ai") {
+        return talkLimits.ai;
+    }
+    if (helpsIn(folder)) {
+        return talkLimits.aiHelps;
+    }
+    if (text.trim().length > talkLimits.ai) {
+        throw new Error(`The player has the helps off: write at most ${talkLimits.ai} characters. Nothing changed.`);
+    }
+    return talkLimits.ai;
+}
+/** A line of the talk with no game, which starts it the first time; no mood, which only the end of a game takes. */
+function sayAtTable(folder, who, text, at, mood) {
+    if (who === "agent") {
+        throw new Error("There is no game to think on. Nothing changed.");
+    }
+    if (mood !== undefined) {
+        throw new Error("There is no game: a mood goes with a game's end. Say it without mood. Nothing changed.");
+    }
+    const before = loadTableTalk(folder);
+    const table = { started: before.started === "" ? at.toISOString() : before.started, talk: [...before.talk, talkLine(before, who, text, at, undefined, aiMost(folder, who, text))] };
+    saveTableTalk(folder, table);
+    return table;
+}

package/dist/commands/speech.d.ts

@@ -0,0 +1,8 @@
+/** The player's language by its English name when it is not English. */
+export interface Speech {
+    language: string;
+}
+/** The player's speech, from the page's settings or the system's language; undefined in English, which the AI speaks unless told. */
+export declare function speechOf(folder: string, systemLanguage: string | undefined): Speech | undefined;
+/** What the AI is told of the player's speech once a chat (Priya); the moves are SAN in every language (D-87). */
+export declare function speechLine({ language }: Speech): string;

package/dist/commands/speech.js

@@ -0,0 +1,20 @@
+// The player's language, which the AI is told once a chat when it is not English: the moves stay in SAN (D-87).
+import { languageIn } from "../profiles/index.js";
+/** The player's speech, from the page's settings or the system's language; undefined in English, which the AI speaks unless told. */
+export function speechOf(folder, systemLanguage) {
+    const language = languageName(languageIn(folder, systemLanguage));
+    return language === undefined ? undefined : { language };
+}
+/** What the AI is told of the player's speech once a chat (Priya); the moves are SAN in every language (D-87). */
+export function speechLine({ language }) {
+    return `The player speaks ${language}.`;
+}
+/** A language by its English name when it is not English (Italian), from the way the system or the page names it (it-IT, it). */
+function languageName(language) {
+    const code = language?.split(/[-_]/)[0]?.toLowerCase() ?? "";
+    if (!/^[a-z]{2,3}$/.test(code) || code === "en" || code === "und") {
+        return undefined;
+    }
+    const name = new Intl.DisplayNames(["en"], { type: "language" }).of(code);
+    return name === undefined || name === code ? undefined : name;
+}