chesspal 0.2.4 → 0.3.0

package/dist/server/table/hosts/hosts.js

@@ -0,0 +1,49 @@
+// The AI hosts the table opens a chat in (D-104): Claude Code and Codex, each with the start message, and the model and effort the player chose on the page
+// for the profile in use; "as the host" passes nothing, and the host's own settings stand.
+import { speaksItalian } from "../../../commands/index.js";
+/** The hosts the page offers, by their command's name. */
+export const hostNames = ["claude", "codex"];
+/**
+ * Each host's choices, as tried in each (Priya): a value outside them would fail only at the chat's first turn. Claude Code's are its aliases; Codex's, the
+ * models a ChatGPT account lists, which change with its releases.
+ */
+export const hostChoices = {
+    claude: { models: ["fable", "opus", "sonnet", "haiku"], efforts: ["low", "medium", "high", "xhigh", "max"] },
+    codex: { models: ["gpt-6.1-sol", "gpt-6-astra", "gpt-6.1-terra", "gpt-6-luna"], efforts: ["low", "medium", "high", "xhigh", "max"] },
+};
+/** Whether a word names a host the page offers. */
+export function isHostName(name) {
+    return hostNames.includes(name);
+}
+/** The message a chat opened by the table starts with, in the player's language: the AI answers it by calling status, as every chat does. */
+export function startMessage(language) {
+    return speaksItalian(language) ? "Giochiamo!" : "Let's play!";
+}
+/**
+ * The start message and the choices the host knows: first for Claude Code, whose options may take the word after; last for Codex, where "resume" is no
+ * subcommand, kept from its update screen, which an Enter would accept.
+ */
+export function hostArgs(host, message, choice = {}) {
+    const { model, effort } = offered(host, choice);
+    if (host === "claude") {
+        return [message, ...(model === undefined ? [] : ["--model", model]), ...(effort === undefined ? [] : ["--effort", effort])];
+    }
+    return ["-c", "check_for_update_on_startup=false", ...(model === undefined ? [] : ["-m", model]), ...(effort === undefined ? [] : ["-c", `model_reasoning_effort=${effort}`]), message];
+}
+/** The settings' keys that keep a host's choice in the profile: claudeModel, claudeEffort, codexModel, codexEffort. */
+export function choiceKeys(host) {
+    return { model: `${host}Model`, effort: `${host}Effort` };
+}
+/** A host's choice as the profile's settings keep it: the values the host offers alone, the rest is the host's own. */
+export function choiceIn(settings, host) {
+    const keys = choiceKeys(host);
+    const text = (value) => (typeof value === "string" ? value : undefined);
+    return offered(host, { model: text(settings?.[keys.model]), effort: text(settings?.[keys.effort]) });
+}
+// The choice kept to the values the host offers.
+function offered(host, choice) {
+    const { models, efforts } = hostChoices[host];
+    const model = choice.model !== undefined && models.includes(choice.model) ? choice.model : undefined;
+    const effort = choice.effort !== undefined && efforts.includes(choice.effort) ? choice.effort : undefined;
+    return { model, effort };
+}

package/dist/server/table/hosts/index.d.ts

@@ -0,0 +1,3 @@
+export { terminalChats } from "./chats.ts";
+export { isHostName } from "./hosts.ts";
+export { hostLaunch, playHost } from "./play.ts";

package/dist/server/table/hosts/index.js

@@ -0,0 +1,4 @@
+// The AI hosts a table opens a chat in (D-104): their choices, the terminal they open in, and `chesspal play`, which starts one there.
+export { terminalChats } from "./chats.js";
+export { isHostName } from "./hosts.js";
+export { hostLaunch, playHost } from "./play.js";

package/dist/server/table/hosts/play.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from "../../../commands/index.ts";
+import { type HostName } from "./hosts.ts";
+/** What `chesspal play` starts: the host's program, its arguments, folder and environment, and whether it needs cmd, as a .cmd shim does on Windows. */
+export interface HostLaunch {
+    readonly program: string;
+    readonly args: readonly string[];
+    readonly folder: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly shell: boolean;
+}
+/**
+ * Runs the host in the table's folder, in this terminal, until it ends: its exit code; started again, clean, when the table asks for a new game (D-57).
+ * Ctrl+C is the host's: this process ignores it, or the terminal would close with the chat.
+ */
+export declare function playHost(context: Context, host: HostName): Promise<number>;
+/**
+ * Runs the host until it ends, or until `again`, asked every half second, says to start it again: then it is ended with what it started, killed when it
+ * does not end. Its exit code, and whether to start it again.
+ */
+export declare function runHost(launch: HostLaunch, again: () => boolean, platform?: string, every?: number): Promise<{
+    code: number;
+    again: boolean;
+}>;
+/** How the host starts for the profile in use: found on the PATH, with its choice; it throws, saying how to install it, when it is not there. */
+export declare function hostLaunch(context: Context, host: HostName, env?: NodeJS.ProcessEnv, exists?: (path: string) => boolean): HostLaunch;

package/dist/server/table/hosts/play.js

@@ -0,0 +1,152 @@
+// `chesspal play claude` (D-104): the chat the table's button opens, in the terminal the table opened for it, or one the player typed it in: the host started
+// in the table's folder with the start message, and the model and effort chosen on the page for the profile in use; started again for a new game.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+import { tableFolder } from "../../../home/index.js";
+import { setUpHosts } from "../../../host-files/index.js";
+import { activeProfile, gameFolder, languageIn, profileSettings } from "../../../profiles/index.js";
+import { programPath } from "./find.js";
+import { choiceIn, hostArgs, startMessage } from "./hosts.js";
+import { askedAgain, leaveSeat, refreshSeat, seatTimes, takeSeat } from "./seat.js";
+import { cmdQuoted } from "./terminal.js";
+/**
+ * Runs the host in the table's folder, in this terminal, until it ends: its exit code; started again, clean, when the table asks for a new game (D-57).
+ * Ctrl+C is the host's: this process ignores it, or the terminal would close with the chat.
+ */
+export async function playHost(context, host) {
+    const folder = tableFolder(context.home());
+    takeSeat(folder, { pid: process.pid, host });
+    process.on("SIGINT", () => undefined);
+    // A window closed with its X ends this process without its finally: the seat goes first.
+    process.on("SIGHUP", () => {
+        leaveSeat(folder, process.pid);
+        process.exit(129);
+    });
+    const terminal = savedTerminal(context.platform);
+    let refreshed = Date.now();
+    const asked = () => {
+        if (Date.now() - refreshed >= seatTimes.refresh) {
+            refreshed = Date.now();
+            refreshSeat(folder, process.pid);
+        }
+        return askedAgain(folder, process.pid);
+    };
+    try {
+        for (;;) {
+            // A request left from a second click while the host before was ending is not for this one.
+            askedAgain(folder, process.pid);
+            const ran = await runHost(hostLaunch(context, host), asked, context.platform).catch((error) => {
+                throw new Error(`${hostTitle[host]} did not start: ${error.message}`);
+            });
+            if (!ran.again) {
+                return ran.code;
+            }
+            terminal.restore();
+            process.stdout.write(cleanScreen);
+        }
+    }
+    finally {
+        leaveSeat(folder, process.pid);
+    }
+}
+/**
+ * Runs the host until it ends, or until `again`, asked every half second, says to start it again: then it is ended with what it started, killed when it
+ * does not end. Its exit code, and whether to start it again.
+ */
+export function runHost(launch, again, platform = process.platform, every = 500) {
+    return new Promise((done, failed) => {
+        const words = [launch.program, ...launch.args];
+        const command = launch.shell ? [words.map(cmdQuoted).join(" ")] : words;
+        const chat = spawn(command[0], command.slice(1), { cwd: launch.folder, env: launch.env, stdio: "inherit", shell: launch.shell });
+        let ended = false;
+        let killing;
+        const watch = setInterval(() => {
+            if (!ended && again()) {
+                ended = true;
+                endTree(chat, platform);
+                killing = setTimeout(() => chat.kill("SIGKILL"), killAfter);
+            }
+        }, every);
+        const stop = () => {
+            clearInterval(watch);
+            clearTimeout(killing);
+        };
+        chat.once("error", (error) => {
+            stop();
+            failed(error);
+        });
+        chat.once("exit", (code) => {
+            stop();
+            done({ code: code ?? 1, again: ended || again() });
+        });
+    });
+}
+/** How the host starts for the profile in use: found on the PATH, with its choice; it throws, saying how to install it, when it is not there. */
+export function hostLaunch(context, host, env = process.env, exists) {
+    const home = context.home();
+    const folder = tableFolder(home);
+    const found = programPath(host, context.platform, env, exists);
+    if (found === undefined) {
+        throw new Error(`${hostTitle[host]} is not installed on this computer, or not on its PATH: install it (${installHint[host]}), then try again.`);
+    }
+    setUpHosts(folder, context.platform);
+    const choice = choiceIn(profileSettings(home, activeProfile(home).id), host);
+    const args = hostArgs(host, startMessage(languageIn(gameFolder(home), context.language)), choice);
+    // An effort the player set for every chat would win over the one chosen on the page: spawn leaves out a variable that is undefined.
+    const effort = host === "claude" && choice.effort !== undefined ? { CLAUDE_CODE_EFFORT_LEVEL: undefined } : {};
+    const childEnv = { ...env, ...Object.fromEntries(sessionMarks.map((name) => [name, undefined])), ...effort };
+    const script = npmScript(host, found, context.platform, exists ?? existsSync);
+    if (script !== undefined) {
+        return { program: process.execPath, args: [script, ...args], folder, env: childEnv, shell: false };
+    }
+    return { program: found, args, folder, env: childEnv, shell: context.platform === "win32" && /\.(cmd|bat)$/i.test(found) };
+}
+const hostTitle = { claude: "Claude Code", codex: "Codex" };
+// A host that has not ended this long after it was asked is killed.
+const killAfter = 3_000;
+// A host ended in the middle leaves the modes it set: colours, scroll region, synchronized output, bracketed paste, focus and mouse reports, kitty's
+// keyboard flags, its own screen, a hidden cursor (Priya). All off, and the screen cleared, as a new chat.
+const cleanScreen = "\x1b[0m\x1b[r\x1b[?2026l\x1b[?2004l\x1b[?1004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[<99u\x1b[?1049l\x1b[?25h\x1b[2J\x1b[3J\x1b[H";
+// The host and what it started, its MCP server among them: on Windows its whole tree, which taskkill ends, never the console (Priya); else the host,
+// which ends its own. A taskkill that failed leaves it to the kill that follows.
+function endTree(chat, platform) {
+    if (platform !== "win32" || chat.pid === undefined) {
+        chat.kill("SIGTERM");
+        return;
+    }
+    const taskkill = win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe");
+    const ended = spawnSync(taskkill, ["/T", "/F", "/PID", String(chat.pid)], { stdio: "ignore", windowsHide: true });
+    if (ended.status !== 0) {
+        chat.kill();
+    }
+}
+/**
+ * The terminal's settings before the first host, which one ended in the middle leaves raw, for the next to take as its own; stty keeps them on macOS and
+ * Linux, while on Windows each host sets the console's itself.
+ */
+function savedTerminal(platform) {
+    const saved = platform === "win32" || !process.stdin.isTTY ? undefined : spawnSync("stty", ["-g"], { stdio: ["inherit", "pipe", "ignore"], encoding: "utf8" });
+    const settings = saved?.status === 0 ? saved.stdout.trim() : undefined;
+    return {
+        restore: () => {
+            if (settings !== undefined) {
+                spawnSync("stty", [settings], { stdio: ["inherit", "ignore", "ignore"] });
+            }
+        },
+    };
+}
+// What marks a chat's own session, which a table started from inside a chat would hand down, and the host take for its own (Priya).
+const sessionMarks = ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_CHILD_SESSION", "CLAUDE_CODE_SESSION_ATTENDED", "CLAUDE_PID", "CLAUDE_EFFORT", "AI_AGENT", "TRACEPARENT"];
+const installHint = { claude: "https://claude.com/claude-code", codex: "npm install -g @openai/codex" };
+/**
+ * The script behind npm's Windows shim of Codex, which Node runs as the shim would, without cmd and its quoting of the start message (Priya); none for
+ * another program, or when it is not beside the shim.
+ */
+function npmScript(host, program, platform, exists) {
+    if (host !== "codex" || platform !== "win32" || !/\.cmd$/i.test(program)) {
+        return undefined;
+    }
+    const script = win32.join(win32.dirname(program), "node_modules", "@openai", "codex", "bin", "codex.js");
+    return exists(script) ? script : undefined;
+}

package/dist/server/table/hosts/seat.d.ts

@@ -0,0 +1,25 @@
+/** The play process in the seat: its process id and its host. */
+export interface Seat {
+    readonly pid: number;
+    readonly host: string;
+}
+/**
+ * Takes the seat for this play process, over a request left for one before it; it throws while another one holds it. A seat is held while its play
+ * refreshes it: one closed with its window, or stopped, lets it go within `heldFor`, whatever process takes its id after it.
+ */
+export declare function takeSeat(folder: string, seat: Seat, now?: Date): void;
+/** Tells the table this play process still holds the seat; nothing when it lost it. */
+export declare function refreshSeat(folder: string, pid: number, now?: Date): void;
+/** Leaves the seat, when this play process still holds it. */
+export declare function leaveSeat(folder: string, pid: number): void;
+/** Whether a play process holds the seat. */
+export declare function seatTaken(folder: string, now?: Date): boolean;
+/** Asks the play process in the seat to start its host again: whether one holds it, and was asked. */
+export declare function askAgain(folder: string, now?: Date): boolean;
+/** Whether the table asked this play process to start its host again; the request is taken. */
+export declare function askedAgain(folder: string, pid: number): boolean;
+/** How often a play process refreshes its seat, and how long the seat stays held without it. */
+export declare const seatTimes: {
+    refresh: number;
+    heldFor: number;
+};

package/dist/server/table/hosts/seat.js

@@ -0,0 +1,74 @@
+// The seat `chesspal play` takes at the table (D-104): the play process notes itself in the table's folder while its host runs, one at a time, and the table
+// asks it there to start its host again, a clean chat for a new game (D-57).
+import { mkdirSync, readFileSync, rmSync, statSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomically } from "../../../games/index.js";
+/**
+ * Takes the seat for this play process, over a request left for one before it; it throws while another one holds it. A seat is held while its play
+ * refreshes it: one closed with its window, or stopped, lets it go within `heldFor`, whatever process takes its id after it.
+ */
+export function takeSeat(folder, seat, now = new Date()) {
+    const held = seatHeld(folder, now);
+    if (held !== undefined && held.pid !== seat.pid) {
+        throw new Error(`A chat in ${held.host} already plays at the table, in another window: play there, or close it, then try again.`);
+    }
+    // chesspal play may come before the table has ever been opened.
+    mkdirSync(folder, { recursive: true });
+    rmSync(join(folder, againFile), { force: true });
+    writeAtomically(join(folder, seatFile), `${JSON.stringify(seat)}\n`);
+}
+/** Tells the table this play process still holds the seat; nothing when it lost it. */
+export function refreshSeat(folder, pid, now = new Date()) {
+    if (seatIn(folder)?.pid === pid) {
+        utimesSync(join(folder, seatFile), now, now);
+    }
+}
+/** Leaves the seat, when this play process still holds it. */
+export function leaveSeat(folder, pid) {
+    if (seatIn(folder)?.pid === pid) {
+        rmSync(join(folder, seatFile), { force: true });
+    }
+}
+/** Whether a play process holds the seat. */
+export function seatTaken(folder, now = new Date()) {
+    return seatHeld(folder, now) !== undefined;
+}
+/** Asks the play process in the seat to start its host again: whether one holds it, and was asked. */
+export function askAgain(folder, now = new Date()) {
+    const held = seatHeld(folder, now);
+    if (held === undefined) {
+        return false;
+    }
+    writeAtomically(join(folder, againFile), `${JSON.stringify({ pid: held.pid })}\n`);
+    return true;
+}
+/** Whether the table asked this play process to start its host again; the request is taken. */
+export function askedAgain(folder, pid) {
+    const asked = jsonIn(join(folder, againFile))?.pid === pid;
+    if (asked) {
+        rmSync(join(folder, againFile), { force: true });
+    }
+    return asked;
+}
+/** How often a play process refreshes its seat, and how long the seat stays held without it. */
+export const seatTimes = { refresh: 5_000, heldFor: 15_000 };
+const seatFile = "play.json";
+const againFile = "play-again.json";
+function seatHeld(folder, now) {
+    const seat = seatIn(folder);
+    // A file's time is finer than a Date's: it is compared to the millisecond, as the Date is.
+    const refreshed = statSync(join(folder, seatFile), { throwIfNoEntry: false })?.mtimeMs;
+    return seat !== undefined && refreshed !== undefined && now.getTime() - Math.floor(refreshed) < seatTimes.heldFor ? seat : undefined;
+}
+function seatIn(folder) {
+    const seat = jsonIn(join(folder, seatFile));
+    return typeof seat?.pid === "number" && typeof seat.host === "string" ? { pid: seat.pid, host: seat.host } : undefined;
+}
+function jsonIn(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server/table/hosts/terminal.d.ts

@@ -0,0 +1,6 @@
+/** Opens a terminal window in `folder` running `command`, apart from the table, which it outlives: whether a terminal started. */
+export declare function openTerminal(folder: string, command: readonly string[], platform: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** The terminals to try, in order, each as the program and its arguments; those not installed are left out. */
+export declare function terminals(folder: string, command: readonly string[], platform: string, env: NodeJS.ProcessEnv, exists?: (path: string) => boolean): string[][];
+/** A word for cmd.exe's line, in double quotes when it holds a space or & | < > ^ ( ); cmd reads % and ! even inside them, which our words never hold. */
+export declare function cmdQuoted(word: string): string;

package/dist/server/table/hosts/terminal.js

@@ -0,0 +1,63 @@
+// A terminal window the table opens for a chat (D-104), in a folder, running a command: Windows Terminal, else the console Windows starts; macOS's Terminal;
+// on Linux the terminal the desktop names, else a common one.
+import { spawn } from "node:child_process";
+import { programPath } from "./find.js";
+/** Opens a terminal window in `folder` running `command`, apart from the table, which it outlives: whether a terminal started. */
+export async function openTerminal(folder, command, platform, env = process.env) {
+    for (const [program, ...args] of terminals(folder, command, platform, env)) {
+        if (program !== undefined && await started(program, args, folder)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** The terminals to try, in order, each as the program and its arguments; those not installed are left out. */
+export function terminals(folder, command, platform, env, exists) {
+    const installed = (name) => programPath(name, platform, env, exists);
+    if (platform === "win32") {
+        const windowsTerminal = installed("wt");
+        // start takes its first quoted word as the window's title, an empty one; cmd gets its line verbatim, each word quoted where it holds & or a space.
+        const windowsConsole = ["cmd.exe", "/d", "/s", "/c", `"start "" /D ${[folder, ...command].map(cmdQuoted).join(" ")}"`];
+        // wt splits its command line at every ;, and reads \; as one.
+        const wtWords = [folder, ...command].map((word) => word.replaceAll(";", "\\;"));
+        return windowsTerminal === undefined ? [windowsConsole] : [[windowsTerminal, "-w", "new", "-d", wtWords[0], "--title", "Chesspal", ...wtWords.slice(1)], windowsConsole];
+    }
+    if (platform === "darwin") {
+        const script = `cd ${shellQuoted(folder)} && exec ${command.map(shellQuoted).join(" ")}`;
+        return [["osascript", "-e", `tell application "Terminal" to do script "${appleQuoted(script)}"`, "-e", `tell application "Terminal" to activate`]];
+    }
+    const linux = [
+        ["x-terminal-emulator", "-e", ...command],
+        ["gnome-terminal", `--working-directory=${folder}`, "--", ...command],
+        ["konsole", "--workdir", folder, "-e", ...command],
+        ["xfce4-terminal", `--working-directory=${folder}`, "-x", ...command],
+        ["xterm", "-e", ...command],
+    ];
+    return linux.flatMap(([name, ...args]) => {
+        const path = installed(name ?? "");
+        return path === undefined ? [] : [[path, ...args]];
+    });
+}
+/** A word for cmd.exe's line, in double quotes when it holds a space or & | < > ^ ( ); cmd reads % and ! even inside them, which our words never hold. */
+export function cmdQuoted(word) {
+    return /[\s&|<>^()!%]/.test(word) ? `"${word}"` : word;
+}
+// A program started apart from the table: whether it started. cmd's line is quoted already.
+function started(program, args, folder) {
+    return new Promise((done) => {
+        const opened = spawn(program, args, { cwd: folder, detached: true, stdio: "ignore", windowsVerbatimArguments: program === "cmd.exe" });
+        opened.once("spawn", () => {
+            opened.unref();
+            done(true);
+        });
+        opened.once("error", () => done(false));
+    });
+}
+// A word for the shell, in single quotes, a quote in it closed and escaped.
+function shellQuoted(word) {
+    return `'${word.replaceAll("'", "'\\''")}'`;
+}
+// Text inside an AppleScript string.
+function appleQuoted(text) {
+    return text.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}

package/dist/server/table/icon/index.d.ts

@@ -0,0 +1,32 @@
+/** What the icon starts: Node with the arguments of `chesspal` alone, in a folder. */
+export interface IconCommand {
+    readonly node: string;
+    readonly args: readonly string[];
+    readonly folder: string;
+}
+/** The folders the icon goes in: the desktop and the system's menu of applications; the tests give their own. */
+export interface IconPlaces {
+    readonly desktop: string;
+    readonly menu: string;
+}
+/**
+ * Puts Chesspal's icon on the desktop and in the menu, the system's own folders unless `places` gives others: the files made. It throws when the system
+ * refuses, with what went wrong.
+ */
+export declare function makeIcons(platform: string, command: IconCommand, places?: IconPlaces): Promise<string[]>;
+/**
+ * What the icon starts: the `chesspal` running now, the same Node and script, as `chesspal open`, in the data folder. Windows gives its hidden console a
+ * terminal, where `chesspal` alone could ask about the icon unseen; `open` never asks.
+ */
+export declare function iconCommand(home: string): IconCommand;
+/** Whether the command line asked already on this machine whether to put the icon there: once a machine, since the data folder may be on several. */
+export declare function iconAsked(home: string, machine?: string): boolean;
+/** Notes that the command line asked on this machine, whatever the answer. */
+export declare function noteIconAsked(home: string, machine?: string): void;
+/** Notes the icon made on this machine, its command and files, which asks no more there. */
+export declare function noteIconMade(home: string, command: IconCommand, files: readonly string[], machine?: string): void;
+/**
+ * Whether the icon made on this machine runs another Node or script than `command`, which a Node manager or an update may have taken away, and is still
+ * there: then it is made again. One the player removed stays removed.
+ */
+export declare function iconToRemake(home: string, command: IconCommand, machine?: string, exists?: (path: string) => boolean): boolean;

package/dist/server/table/icon/index.js

@@ -0,0 +1,83 @@
+// Chesspal's icon on the desktop and in the system's menu (D-104): it opens the table as `chesspal` alone does, with no console, on Windows, macOS and Linux.
+// The command line asks once a machine whether to put it there.
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeAtomically } from "../../../games/index.js";
+import { tableFolder } from "../../../home/index.js";
+import { linuxIcons } from "./linux.js";
+import { macIcons } from "./macos.js";
+import { windowsIcons } from "./windows.js";
+/**
+ * Puts Chesspal's icon on the desktop and in the menu, the system's own folders unless `places` gives others: the files made. It throws when the system
+ * refuses, with what went wrong.
+ */
+export function makeIcons(platform, command, places) {
+    if (platform === "win32") {
+        return windowsIcons(command, iconImage("ico"), places);
+    }
+    if (platform === "darwin") {
+        return Promise.resolve(macIcons(command, iconImage("icns"), places));
+    }
+    return Promise.resolve(linuxIcons(command, iconImage("png"), places));
+}
+/**
+ * What the icon starts: the `chesspal` running now, the same Node and script, as `chesspal open`, in the data folder. Windows gives its hidden console a
+ * terminal, where `chesspal` alone could ask about the icon unseen; `open` never asks.
+ */
+export function iconCommand(home) {
+    return { node: process.execPath, args: [...process.execArgv, process.argv[1] ?? "", "open"], folder: home };
+}
+/** Whether the command line asked already on this machine whether to put the icon there: once a machine, since the data folder may be on several. */
+export function iconAsked(home, machine = hostname()) {
+    return iconNotes(home).asked.includes(machine);
+}
+/** Notes that the command line asked on this machine, whatever the answer. */
+export function noteIconAsked(home, machine = hostname()) {
+    const notes = iconNotes(home);
+    if (!notes.asked.includes(machine)) {
+        writeIconNotes(home, { ...notes, asked: [...notes.asked, machine] });
+    }
+}
+/** Notes the icon made on this machine, its command and files, which asks no more there. */
+export function noteIconMade(home, command, files, machine = hostname()) {
+    const notes = iconNotes(home);
+    const asked = notes.asked.includes(machine) ? notes.asked : [...notes.asked, machine];
+    writeIconNotes(home, { asked, made: { ...notes.made, [machine]: { command: commandLine(command), files: [...files] } } });
+}
+/**
+ * Whether the icon made on this machine runs another Node or script than `command`, which a Node manager or an update may have taken away, and is still
+ * there: then it is made again. One the player removed stays removed.
+ */
+export function iconToRemake(home, command, machine = hostname(), exists = existsSync) {
+    const made = iconNotes(home).made[machine];
+    return made !== undefined && JSON.stringify(made.command) !== JSON.stringify(commandLine(command)) && made.files.some(exists);
+}
+/** The icon's image, as the build copies it beside the page's files. */
+function iconImage(kind) {
+    return fileURLToPath(new URL(`../../../page/layout/icon.${kind}`, import.meta.url));
+}
+function commandLine(command) {
+    return [command.node, ...command.args];
+}
+function notesFile(home) {
+    return join(tableFolder(home), "icon.json");
+}
+function writeIconNotes(home, notes) {
+    mkdirSync(tableFolder(home), { recursive: true });
+    writeAtomically(notesFile(home), `${JSON.stringify(notes, null, 2)}\n`);
+}
+// The notes kept; none when the file is missing or cannot be read, which only asks again.
+function iconNotes(home) {
+    const file = notesFile(home);
+    const texts = (value) => (Array.isArray(value) ? value.filter((text) => typeof text === "string") : []);
+    try {
+        const read = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+        const made = typeof read.made === "object" && read.made !== null ? read.made : {};
+        return { asked: texts(read.asked), made: Object.fromEntries(Object.entries(made).map(([machine, icon]) => [machine, { command: texts(icon?.command), files: texts(icon?.files) }])) };
+    }
+    catch {
+        return { asked: [], made: {} };
+    }
+}

package/dist/server/table/icon/linux.d.ts

@@ -0,0 +1,5 @@
+import type { IconCommand, IconPlaces } from "./index.ts";
+/** Makes chesspal.desktop in the user's applications and on the desktop, when there is one, or in `places`: their paths. */
+export declare function linuxIcons(command: IconCommand, image: string, places?: IconPlaces): string[];
+/** The desktop entry: Chesspal's name and icon, and the command it runs with no terminal. */
+export declare function desktopEntry(command: IconCommand, image: string): string;

package/dist/server/table/icon/linux.js

@@ -0,0 +1,47 @@
+// The icon on Linux: a desktop entry in the user's applications, which every desktop's menu lists, and a copy on the desktop, marked as trusted where GNOME
+// asks for it.
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Makes chesspal.desktop in the user's applications and on the desktop, when there is one, or in `places`: their paths. */
+export function linuxIcons(command, image, places = systemPlaces()) {
+    mkdirSync(places.menu, { recursive: true });
+    const entry = join(places.menu, "chesspal.desktop");
+    writeFileSync(entry, desktopEntry(command, image));
+    chmodSync(entry, 0o755);
+    if (!existsSync(places.desktop)) {
+        return [entry];
+    }
+    const onDesktop = join(places.desktop, "chesspal.desktop");
+    copyFileSync(entry, onDesktop);
+    chmodSync(onDesktop, 0o755);
+    // GNOME launches a desktop file on the desktop only once it is trusted; elsewhere gio may be missing, and nothing is lost.
+    spawnSync("gio", ["set", onDesktop, "metadata::trusted", "true"], { stdio: "ignore" });
+    return [onDesktop, entry];
+}
+/** The desktop entry: Chesspal's name and icon, and the command it runs with no terminal. */
+export function desktopEntry(command, image) {
+    return `[Desktop Entry]
+Type=Application
+Name=Chesspal
+Comment=Play chess against an AI, and learn with one
+Exec=${[command.node, ...command.args].map(quoted).join(" ")}
+Path=${command.folder}
+Icon=${image}
+Terminal=false
+Categories=Game;BoardGame;
+`;
+}
+// The desktop as the user's dirs name it, and the applications of XDG_DATA_HOME.
+function systemPlaces() {
+    const named = spawnSync("xdg-user-dir", ["DESKTOP"], { encoding: "utf8" });
+    const desktop = named.status === 0 && named.stdout.trim() !== "" ? named.stdout.trim() : join(homedir(), "Desktop");
+    const data = process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
+    return { desktop, menu: join(data, "applications") };
+}
+// An argument of Exec, in double quotes, with the characters the desktop entry spec escapes there, and % doubled, which Exec reads as a field code; then
+// every backslash doubled, as the spec reads a value's escapes before its quotes (Federico).
+function quoted(argument) {
+    return `"${argument.replace(/(["`$\\])/g, "\\$1").replaceAll("%", "%%")}"`.replaceAll("\\", "\\\\");
+}

package/dist/server/table/icon/macos.d.ts

@@ -0,0 +1,3 @@
+import type { IconCommand, IconPlaces } from "./index.ts";
+/** Makes Chesspal.app in ~/Applications, or in `places`' menu, with its image, and its link on the desktop: their paths. */
+export declare function macIcons(command: IconCommand, image: string, places?: IconPlaces): string[];

package/dist/server/table/icon/macos.js

@@ -0,0 +1,38 @@
+// The icon on macOS: a small application in the user's Applications, which Launchpad and Spotlight list, that runs `chesspal`; on the desktop, a link to it.
+import { chmodSync, copyFileSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Makes Chesspal.app in ~/Applications, or in `places`' menu, with its image, and its link on the desktop: their paths. */
+export function macIcons(command, image, places = { desktop: join(homedir(), "Desktop"), menu: join(homedir(), "Applications") }) {
+    const app = join(places.menu, "Chesspal.app");
+    const contents = join(app, "Contents");
+    const launcher = join(contents, "MacOS", "chesspal");
+    mkdirSync(dirname(launcher), { recursive: true });
+    mkdirSync(join(contents, "Resources"), { recursive: true });
+    copyFileSync(image, join(contents, "Resources", "chesspal.icns"));
+    writeFileSync(join(contents, "Info.plist"), infoList);
+    writeFileSync(launcher, `#!/bin/sh\ncd ${quoted(command.folder)} && exec ${[command.node, ...command.args].map(quoted).join(" ")}\n`);
+    chmodSync(launcher, 0o755);
+    const link = join(places.desktop, "Chesspal.app");
+    rmSync(link, { force: true });
+    symlinkSync(app, link);
+    return [link, app];
+}
+// LSUIElement: the launcher shows no icon in the Dock for the moment it runs.
+const infoList = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleName</key><string>Chesspal</string>
+    <key>CFBundleIdentifier</key><string>io.github.stefanocaronia.chesspal</string>
+    <key>CFBundleExecutable</key><string>chesspal</string>
+    <key>CFBundleIconFile</key><string>chesspal</string>
+    <key>CFBundlePackageType</key><string>APPL</string>
+    <key>LSUIElement</key><true/>
+</dict>
+</plist>
+`;
+// An argument for the shell, in single quotes, a quote in it closed and escaped.
+function quoted(argument) {
+    return `'${argument.replaceAll("'", "'\\''")}'`;
+}

package/dist/server/table/icon/windows.d.ts

@@ -0,0 +1,3 @@
+import type { IconCommand, IconPlaces } from "./index.ts";
+/** Makes the shortcuts, on the desktop and in the Start menu as Windows names them for this user, or in `places`: their paths. */
+export declare function windowsIcons(command: IconCommand, image: string, places?: IconPlaces): Promise<string[]>;