chesspal 0.2.4 → 0.3.1

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[]>;

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

@@ -0,0 +1,48 @@
+// The icon on Windows: a shortcut on the desktop and in the Start menu, made by PowerShell, the only tool every Windows has for it. It runs Node through
+// `conhost --headless`, the one way found that opens no console window.
+import { execFile } from "node:child_process";
+import { win32 } from "node:path";
+/** Makes the shortcuts, on the desktop and in the Start menu as Windows names them for this user, or in `places`: their paths. */
+export function windowsIcons(command, image, places) {
+    const env = {
+        ...process.env,
+        CHESSPAL_ICON_FOLDERS: places === undefined ? "" : `${places.desktop};${places.menu}`,
+        CHESSPAL_ICON_TARGET: win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "conhost.exe"),
+        CHESSPAL_ICON_ARGUMENTS: ["--headless", command.node, ...command.args].map(quoted).join(" "),
+        CHESSPAL_ICON_FOLDER: command.folder,
+        CHESSPAL_ICON_IMAGE: image,
+    };
+    return new Promise((done, failed) => {
+        execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", shortcuts], { env, windowsHide: true }, (error, stdout, stderr) => {
+            if (error === null) {
+                done(stdout.split(/\r?\n/).filter((line) => line.trim() !== ""));
+            }
+            else {
+                failed(new Error(`Windows did not make Chesspal's shortcuts: ${stderr.trim() || error.message}`));
+            }
+        });
+    });
+}
+// The values come in the environment, never in the script: a path may hold any character PowerShell reads. Its output in UTF-8, and an error as its
+// message alone, not in the system's language and code page around it.
+const shortcuts = `
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+trap { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }
+$ErrorActionPreference = 'Stop'
+$shell = New-Object -ComObject WScript.Shell
+$folders = if ($env:CHESSPAL_ICON_FOLDERS) { $env:CHESSPAL_ICON_FOLDERS -split ';' } else { [Environment]::GetFolderPath('Desktop'), [Environment]::GetFolderPath('Programs') }
+foreach ($folder in $folders) {
+    $link = $shell.CreateShortcut((Join-Path $folder 'Chesspal.lnk'))
+    $link.TargetPath = $env:CHESSPAL_ICON_TARGET
+    $link.Arguments = $env:CHESSPAL_ICON_ARGUMENTS
+    $link.WorkingDirectory = $env:CHESSPAL_ICON_FOLDER
+    $link.IconLocation = $env:CHESSPAL_ICON_IMAGE
+    $link.Description = 'Chesspal'
+    $link.Save()
+    $link.FullName
+}
+`;
+// An argument as Windows reads it from a command line: in quotes when it has a space; a Windows path never holds a quote.
+function quoted(argument) {
+    return /\s/.test(argument) ? `"${argument}"` : argument;
+}

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

@@ -0,0 +1,6 @@
+export { appBrowser, openedAddress } from "./browser.ts";
+export { hostLaunch, isHostName, playHost, terminalChats } from "./hosts/index.ts";
+export { iconAsked, type IconCommand, iconCommand, type IconPlaces, iconToRemake, makeIcons, noteIconAsked, noteIconMade } from "./icon/index.ts";
+export { noteOpenFailed, openTable, processLauncher, type TableLauncher } from "./launch.ts";
+export { attachTable, tableToJoin } from "./link.ts";
+export { isOlder, startTable, type Table, type TableTimes, tableTimes } from "./table.ts";

package/dist/server/table/index.js

@@ -0,0 +1,7 @@
+// The table (D-104): the board page in a process of its own, started by `chesspal` alone, with no chat. Above server/page, which serves the page in either process.
+export { appBrowser, openedAddress } from "./browser.js";
+export { hostLaunch, isHostName, playHost, terminalChats } from "./hosts/index.js";
+export { iconAsked, iconCommand, iconToRemake, makeIcons, noteIconAsked, noteIconMade } from "./icon/index.js";
+export { noteOpenFailed, openTable, processLauncher } from "./launch.js";
+export { attachTable, tableToJoin } from "./link.js";
+export { isOlder, startTable, tableTimes } from "./table.js";

package/dist/server/table/launch.d.ts

@@ -0,0 +1,19 @@
+import { type Context } from "../../commands/index.ts";
+/** What opening the table does outside this process: start the table apart, open the browser, wait. The tests give their own. */
+export interface TableLauncher {
+    /** Starts `chesspal table` apart from this process, which it outlives, in the data folder. */
+    start(home: string): void;
+    /** Opens the page in the browser: whether it could. */
+    open(url: string): Promise<boolean>;
+    wait(milliseconds: number): Promise<void>;
+}
+/**
+ * Opens the table's page in the browser, the table started first when none answers, or when the one that does is of another version, which is asked to
+ * quit; a table of this version another `chesspal` started meanwhile is as good. What to tell the player, in their language; a table that does not start
+ * within ten seconds throws.
+ */
+export declare function openTable(context: Context, launcher?: TableLauncher): Promise<string>;
+/** Notes why the icon could not open the table, whose console nobody sees, in open.log of the table's folder: the last of them. */
+export declare function noteOpenFailed(context: Context, message: string): void;
+/** The launcher of a real `chesspal`: the table started with the same Node and script, the page opened in the default browser. */
+export declare function processLauncher(platform: string, command?: string[]): TableLauncher;

package/dist/server/table/launch.js

@@ -0,0 +1,78 @@
+// `chesspal` alone (D-104): the table's page opened in the browser, the table started first, apart from the terminal, when none of this version answers.
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { styleText } from "node:util";
+import { speaksItalian } from "../../commands/index.js";
+import { tableFolder } from "../../home/index.js";
+import { version } from "../../version.js";
+import { openInBrowser } from "./browser.js";
+import { askToQuit, tableAt } from "./table.js";
+/**
+ * Opens the table's page in the browser, the table started first when none answers, or when the one that does is of another version, which is asked to
+ * quit; a table of this version another `chesspal` started meanwhile is as good. What to tell the player, in their language; a table that does not start
+ * within ten seconds throws.
+ */
+export async function openTable(context, launcher = processLauncher(context.platform)) {
+    const home = context.home();
+    const folder = tableFolder(home);
+    const words = speaksItalian(context.language) ? italian : english;
+    const deadline = context.now().getTime() + startWait;
+    const asked = new Set();
+    let started = false;
+    for (;;) {
+        const table = await tableAt(folder);
+        if (table?.version === version) {
+            return styleText(["bold", "green"], `♜ ${(await launcher.open(table.url)) ? words.opened(table.url) : words.notOpened(table.url)}`);
+        }
+        if (table !== undefined && !asked.has(table.port)) {
+            asked.add(table.port);
+            await askToQuit(table.port);
+        }
+        else if (table === undefined && !started) {
+            started = true;
+            launcher.start(home);
+        }
+        if (context.now().getTime() >= deadline) {
+            throw new Error(table === undefined ? words.notStarted : words.notQuit(table.url));
+        }
+        await launcher.wait(every);
+    }
+}
+/** Notes why the icon could not open the table, whose console nobody sees, in open.log of the table's folder: the last of them. */
+export function noteOpenFailed(context, message) {
+    try {
+        const folder = tableFolder(context.home());
+        mkdirSync(folder, { recursive: true });
+        writeFileSync(join(folder, "open.log"), `${context.now().toISOString()} ${message}\n`);
+    }
+    catch {
+        // A data folder that cannot be written has no other place for it.
+    }
+}
+/** The launcher of a real `chesspal`: the table started with the same Node and script, the page opened in the default browser. */
+export function processLauncher(platform, command = [...process.execArgv, process.argv[1] ?? ""]) {
+    return {
+        start: (home) => {
+            // Its own process group, with no console and nothing of this one's: the terminal can close, the table stays.
+            spawn(process.execPath, [...command, "table"], { cwd: home, detached: true, stdio: "ignore", windowsHide: true }).unref();
+        },
+        open: (url) => openInBrowser(url, platform),
+        wait: (milliseconds) => new Promise((done) => setTimeout(done, milliseconds)),
+    };
+}
+// A table answers within ten seconds of its start, an older one quitting first, looked for every tenth of a second.
+const startWait = 10_000;
+const every = 100;
+const english = {
+    opened: (url) => `Chesspal's table is open: ${url}`,
+    notOpened: (url) => `Chesspal's table is at ${url}: open it in your browser.`,
+    notStarted: "Chesspal's table did not start within ten seconds: run `chesspal table` to see why.",
+    notQuit: (url) => `The table of another Chesspal version, at ${url}, did not close: close its pages in the browser and wait five minutes, then run chesspal again.`,
+};
+const italian = {
+    opened: (url) => `Il tavolo di Chesspal è aperto: ${url}`,
+    notOpened: (url) => `Il tavolo di Chesspal è su ${url}: aprilo nel browser.`,
+    notStarted: "Il tavolo di Chesspal non è partito in dieci secondi: lancia `chesspal table` per vedere perché.",
+    notQuit: (url) => `Il tavolo di un'altra versione di Chesspal, su ${url}, non si è chiuso: chiudi le sue pagine nel browser, aspetta cinque minuti e lancia di nuovo chesspal.`,
+};

package/dist/server/table/link.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from "../../commands/index.ts";
+import type { Page } from "../page/page.ts";
+/**
+ * Attaches the chat to the table of its data folder, when one of its version answers and no other chat is at it: the page the chat then uses, whose `lost`
+ * is told once the table is gone or no longer knows the chat. An older table is asked to quit; with none, a newer one or another chat at it, none, and
+ * the chat serves its own page.
+ */
+export declare function attachTable(context: Context, lost: () => void): Promise<Page | undefined>;
+/** Whether a table of this version answers for the chat's data folder with no chat at it: a chat that serves its own page goes there at its next tool. */
+export declare function tableToJoin(context: Context): Promise<boolean>;

package/dist/server/table/link.js

@@ -0,0 +1,231 @@
+// A chat attached to the table (D-104): the board page is the table's, and the chat tells it over HTTP, on this machine, what a page it served itself would
+// read from it: that it calls a tool, a copy of what it saw after each, and that the New game window should open.
+import { Agent, request } from "node:http";
+import { aiHostOf, aiModelOf } from "../../games/index.js";
+import { tableFolder } from "../../home/index.js";
+import { outdatedHostFiles } from "../../host-files/index.js";
+import { gameFolder } from "../../profiles/index.js";
+import { version } from "../../version.js";
+import { jsonOf } from "../page/http.js";
+import { askToQuit, isOlder, tableAt } from "./table.js";
+/**
+ * Attaches the chat to the table of its data folder, when one of its version answers and no other chat is at it: the page the chat then uses, whose `lost`
+ * is told once the table is gone or no longer knows the chat. An older table is asked to quit; with none, a newer one or another chat at it, none, and
+ * the chat serves its own page.
+ */
+export async function attachTable(context, lost) {
+    const table = await tableOf(context);
+    if (table === undefined) {
+        return undefined;
+    }
+    if (table.version !== version) {
+        if (table.version === undefined || isOlder(table.version, version)) {
+            await askToQuit(table.port);
+        }
+        return undefined;
+    }
+    const link = new TableLink(table.port, context, lost);
+    return (await link.attach()) ? tablePage(link, table.url) : undefined;
+}
+/** Whether a table of this version answers for the chat's data folder with no chat at it: a chat that serves its own page goes there at its next tool. */
+export async function tableToJoin(context) {
+    const table = await tableOf(context);
+    return table !== undefined && table.version === version && table.chat === undefined;
+}
+/** The table of the chat's data folder, when one answers; none while the data folder cannot be made. */
+async function tableOf(context) {
+    try {
+        return await tableAt(tableFolder(context.home()));
+    }
+    catch {
+        return undefined;
+    }
+}
+// How long the table may take to answer the chat: it answers in a millisecond, so one that takes more than a second is stuck (Federico).
+const answerWait = 1_500;
+/** The page as the attached chat uses it: what a page of its own reads from the chat, the chat sends the table. */
+function tablePage(link, url) {
+    return {
+        url,
+        heard: () => link.copy(true),
+        chatCalls: () => link.calls(),
+        toolEnded: () => link.copy(false),
+        open: () => link.open,
+        inUse: () => true,
+        askNewGame: () => link.askNewGame(),
+        close: async () => link.leave(),
+    };
+}
+/** The chat's end of its place at the table: its token, whether a browser has the page open, and the copies it sends, in order, one at a time. */
+class TableLink {
+    /** Whether a browser had the page open at the table's last answer. */
+    open = false;
+    token = "";
+    attachment;
+    agent = new Agent({ keepAlive: true, maxSockets: 1 });
+    news = false;
+    copying = false;
+    left = false;
+    port;
+    context;
+    lost;
+    constructor(port, context, lost) {
+        this.port = port;
+        this.context = context;
+        this.lost = lost;
+    }
+    /** Attaches: whether the table took the chat. The answer then stays open for as long as both live; when it closes, the chat has lost the table. */
+    attach() {
+        return new Promise((done) => {
+            let text = "";
+            let attached = false;
+            // A table that takes the chat and then says nothing is no table: the chat serves its own page (Priya).
+            const silent = setTimeout(() => this.attachment?.destroy(), answerWait);
+            silent.unref();
+            this.attachment = request({ ...this.address("/api/chat"), agent: false }, (response) => {
+                response.setEncoding("utf8");
+                // The first line gives the chat its token; a table that refuses it answers with a status of its own and closes.
+                response.on("data", (chunk) => {
+                    if (attached) {
+                        return;
+                    }
+                    text += chunk;
+                    const line = text.indexOf("\n");
+                    if (line === -1) {
+                        return;
+                    }
+                    const answer = jsonOf(text.slice(0, line));
+                    clearTimeout(silent);
+                    if (response.statusCode === 200 && typeof answer?.token === "string") {
+                        attached = true;
+                        this.token = answer.token;
+                        this.open = answer.open === true;
+                    }
+                    else {
+                        this.attachment?.destroy();
+                    }
+                    done(attached);
+                });
+                response.on("close", () => {
+                    clearTimeout(silent);
+                    return attached ? this.leave() : done(false);
+                });
+            });
+            // The answer kept open never keeps the chat's process alive: it ends when its host goes.
+            this.attachment.on("socket", (socket) => socket.unref());
+            this.attachment.on("error", () => {
+                clearTimeout(silent);
+                done(false);
+            });
+            this.attachment.end(JSON.stringify(attachment(this.context)));
+        });
+    }
+    /** The chat calls a tool: the table hears it before the tool runs, which starts the AI's clock when nobody had heard the player. */
+    async calls() {
+        this.answered(await this.post("/api/chat/call", {}));
+    }
+    /** Sends a copy of what the chat saw once the call under way has ended, those asked meanwhile as one; with `news`, the pages hear of it. */
+    copy(news) {
+        this.news ||= news;
+        if (this.copying) {
+            return;
+        }
+        this.copying = true;
+        setImmediate(() => {
+            this.copying = false;
+            const body = { ...seenBy(this.context), news: this.news };
+            this.news = false;
+            void this.post("/api/chat/read", body).then((answer) => this.answered(answer));
+        });
+    }
+    /** Asks the pages open to show the New game window, without waiting: whether one was open, as the table last said. */
+    askNewGame() {
+        void this.post("/api/chat/new-game", {}).then((answer) => this.answered(answer));
+        return this.open;
+    }
+    /** Leaves the table, once: the chat's process ends, the table is gone, or no longer knows the chat. */
+    leave() {
+        if (!this.left) {
+            this.left = true;
+            this.attachment?.destroy();
+            this.agent.destroy();
+            this.lost();
+        }
+    }
+    // The table did not answer, or no longer knows the chat: it is lost. A request it failed alone changes nothing.
+    answered(answer) {
+        if (answer === "lost") {
+            this.leave();
+        }
+        else if (typeof answer?.open === "boolean") {
+            this.open = answer.open;
+        }
+    }
+    // A request to the table on the chat's own connection, kept alive, and once more on a new one when the table had just closed the one kept.
+    post(path, body, retry = true) {
+        if (this.left) {
+            return Promise.resolve("lost");
+        }
+        return new Promise((done) => {
+            const asked = request({ ...this.address(path), agent: this.agent }, (response) => {
+                const chunks = [];
+                response.on("data", (chunk) => chunks.push(chunk));
+                response.on("end", () => done(answerOf(response.statusCode, Buffer.concat(chunks).toString("utf8"))));
+                response.on("close", () => done("lost"));
+            });
+            // A table that stops answering would hold every tool of the chat's: it is lost, and the chat serves its own page (Priya).
+            asked.setTimeout(answerWait, () => asked.destroy(new Error("The table did not answer.")));
+            asked.on("error", (error) => {
+                // The table closes a connection idle for 5 s as Node reuses it: the request never reached it (Federico).
+                if (retry && asked.reusedSocket && error.code === "ECONNRESET") {
+                    void this.post(path, body, false).then(done);
+                }
+                else {
+                    done("lost");
+                }
+            });
+            asked.end(JSON.stringify({ ...body, token: this.token }));
+        });
+    }
+    address(path) {
+        return { host: "127.0.0.1", port: this.port, path, method: "POST", headers: { "Content-Type": "application/json" } };
+    }
+}
+/** A table that no longer knows the chat answers 409; another status is one request it failed, and the chat stays. */
+function answerOf(status, text) {
+    if (status === 409) {
+        return "lost";
+    }
+    return status === 200 ? jsonOf(text) : undefined;
+}
+/** What the chat says of itself as it attaches:its version, session and folder, its host, and whether its folder needs init again. */
+function attachment(context) {
+    return {
+        version,
+        session: process.env.CLAUDE_CODE_SESSION_ID ?? null,
+        folder: context.folder,
+        host: context.host?.(),
+        outdated: outdatedHostFiles(context.folder, context.platform).length > 0,
+    };
+}
+/** What the chat saw, for the table's copy: the game and the position, the words it was given, its host, and who played as the AI (D-82, D-97). */
+function seenBy(context) {
+    const folder = gameFolderOf(context);
+    return {
+        seen: context.seen,
+        positionSeen: context.positionSeen,
+        positionFirstSeen: context.positionFirstSeen,
+        given: [...context.given],
+        host: context.host?.(),
+        aiModel: folder === undefined ? undefined : aiModelOf(folder),
+        aiHost: folder === undefined ? undefined : aiHostOf(folder),
+    };
+}
+function gameFolderOf(context) {
+    try {
+        return gameFolder(context.home());
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { Context } from "../../commands/index.ts";
+import type { TableChats } from "../page/table.ts";
+/** A table served: its address, and how to close it. */
+export interface Table {
+    readonly url: string;
+    /** Settled once the table has closed: by itself, asked by another Chesspal version, or by close. */
+    readonly closed: Promise<void>;
+    close(): Promise<void>;
+}
+/** How long the table stays unused before it closes, and how often it looks, in milliseconds. */
+export interface TableTimes {
+    readonly idle: number;
+    readonly every: number;
+}
+/** Five minutes with no browser and no chat, looked at every fifteen seconds (D-104). */
+export declare const tableTimes: TableTimes;
+/** A table that answers on its ports: its address, port and version, and the folder of the chat attached to it, when one is. */
+export interface TableFound {
+    readonly url: string;
+    readonly port: number;
+    readonly version: string | undefined;
+    readonly chat: string | undefined;
+}
+/**
+ * Starts the table on the context's data folder, its folder set up as init does, its page opening chats through `chats`: undefined when another table
+ * started at the same time took a lower port, since a table's ports are its lock. It closes once no page has been open, no chat attached and no request
+ * come, for `times.idle`.
+ */
+export declare function startTable(context: Context, times?: TableTimes, chats?: TableChats): Promise<Table | undefined>;
+/** The table of a folder that answers on its ports, the lowest of them; its ports are asked together. */
+export declare function tableAt(folder: string): Promise<TableFound | undefined>;
+/** Asks the table at a port to quit; it answers before it goes, and a table that cannot be reached, or does not answer within a second or so, is let be. */
+export declare function askToQuit(port: number): Promise<void>;
+/** Whether a version is older than another, part by part: 0.2.4 is older than 0.10.0. */
+export declare function isOlder(one: string, other: string): boolean;