chesspal 0.2.4 → 0.3.1

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

@@ -0,0 +1,34 @@
+import { tableFolder } from "../../../home/index.js";
+import { samePath } from "../../bell.js";
+import { programPath } from "./find.js";
+import { hostChoices, hostNames, isHostName } from "./hosts.js";
+import { askAgain, seatHeld } from "./seat.js";
+import { openTerminal } from "./terminal.js";
+/**
+ * The chats of a real table: the hosts installed, looked for again once a while has passed, since the player may install one with the page open; a
+ * terminal opened with `chesspal play`, run by `chesspal`, the same Node and script as the table's.
+ */
+export function terminalChats(context, chesspal = [process.execPath, ...process.execArgv, process.argv[1] ?? ""], env = process.env) {
+    let found;
+    return {
+        hosts: () => {
+            const now = context.now().getTime();
+            if (found === undefined || now - found.at >= lookAgain) {
+                found = { hosts: hostNames.map((name) => chatHost(name, context.platform, env)), at: now };
+            }
+            return found.hosts;
+        },
+        open: async (host) => isHostName(host) && await openTerminal(tableFolder(context.home()), [...chesspal, "play", host], context.platform, env),
+        // Only a chat in the table's folder can be the one chesspal play holds.
+        held: (folder) => {
+            const seat = samePath(folder, tableFolder(context.home())) ? seatHeld(folder, context.now()) : undefined;
+            return seat === undefined ? undefined : { model: seat.model, effort: seat.effort };
+        },
+        relaunch: (folder, host) => samePath(folder, tableFolder(context.home())) && askAgain(folder, context.now(), host === undefined ? {} : { host }),
+    };
+}
+// Looking on the PATH takes a few milliseconds, and the page asks at every change of the game.
+const lookAgain = 10_000;
+function chatHost(name, platform, env) {
+    return { name, installed: programPath(name, platform, env) !== undefined, ...hostChoices[name], command: `chesspal play ${name}` };
+}

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

@@ -0,0 +1,2 @@
+/** The program's path on the PATH of `env`, the first found; none when it is not installed there. */
+export declare function programPath(name: string, platform: string, env: NodeJS.ProcessEnv, exists?: (path: string) => boolean): string | undefined;

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

@@ -0,0 +1,20 @@
+// A program found on the PATH, as a shell would find it: on Windows with the extensions of PATHEXT, which npm's shims (.cmd) and installers (.exe) use.
+import { existsSync, lstatSync } from "node:fs";
+import { posix, win32 } from "node:path";
+/** The program's path on the PATH of `env`, the first found; none when it is not installed there. */
+export function programPath(name, platform, env, exists = present) {
+    const windows = platform === "win32";
+    const path = windows ? win32 : posix;
+    const folders = (env.PATH ?? env.Path ?? "").split(windows ? ";" : ":").filter((folder) => folder.trim() !== "");
+    const extensions = windows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter((extension) => extension !== "").map((extension) => extension.toLowerCase()) : [""];
+    return folders.flatMap((folder) => extensions.map((extension) => path.join(folder.trim(), `${name}${extension}`))).find(exists);
+}
+// Windows' app execution aliases, such as wt.exe in WindowsApps, are links that stat cannot follow: existsSync calls them missing, lstat finds them.
+function present(path) {
+    try {
+        return existsSync(path) || lstatSync(path, { throwIfNoEntry: false }) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,34 @@
+/** The hosts the page offers, by their command's name. */
+export declare const hostNames: readonly ["claude", "codex"];
+export type HostName = typeof hostNames[number];
+/** The models and efforts the player may choose for a host, as its command line names them: aliases, which follow the host's newest models. */
+export interface HostChoices {
+    readonly models: readonly string[];
+    readonly efforts: readonly string[];
+}
+/** What the player chose for a host on the page: none of either keeps the host's own. */
+export interface HostChoice {
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
+/**
+ * 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 declare const hostChoices: Readonly<Record<HostName, HostChoices>>;
+/** Whether a word names a host the page offers. */
+export declare function isHostName(name: unknown): name is HostName;
+/** 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 declare function startMessage(language: string | undefined): string;
+/**
+ * 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 declare function hostArgs(host: HostName, message: string, choice?: HostChoice): string[];
+/** The settings' keys that keep a host's choice in the profile: claudeModel, claudeEffort, codexModel, codexEffort. */
+export declare function choiceKeys(host: HostName): {
+    model: string;
+    effort: string;
+};
+/** 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 declare function choiceIn(settings: Readonly<Record<string, unknown>> | undefined, host: HostName): HostChoice;

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,29 @@
+import type { Context } from "../../../commands/index.ts";
+import { type HostChoice, type HostName } from "./hosts.ts";
+/**
+ * What `chesspal play` starts: the host's program, its arguments, folder and environment, whether it needs cmd, as a .cmd shim does on Windows, and the
+ * model and effort it is given, which the seat notes for the page (D-107).
+ */
+export interface HostLaunch {
+    readonly program: string;
+    readonly args: readonly string[];
+    readonly folder: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly shell: boolean;
+    readonly choice: HostChoice;
+}
+/**
+ * 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),
+ * or for another model or host, which then takes its place (D-107). 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,180 @@
+// `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, isHostName, 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),
+ * or for another model or host, which then takes its place (D-107). 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 playing = host;
+    let next = host;
+    // The host before one asked in its place, until that one has started: it goes on when the other does not start.
+    let before;
+    let refreshed = Date.now();
+    const asked = () => {
+        if (Date.now() - refreshed >= seatTimes.refresh) {
+            refreshed = Date.now();
+            refreshSeat(folder, process.pid);
+        }
+        const again = askedAgain(folder, process.pid);
+        next = again?.host !== undefined && isHostName(again.host) ? again.host : playing;
+        return again !== undefined;
+    };
+    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 started(context, playing, asked).catch((error) => {
+                if (before === undefined) {
+                    throw error;
+                }
+                process.stderr.write(`${error.message} ${hostTitle[before]} goes on.\n`);
+                return undefined;
+            });
+            if (ran === undefined) {
+                playing = before ?? playing;
+                before = undefined;
+                continue;
+            }
+            before = undefined;
+            if (!ran.again) {
+                return ran.code;
+            }
+            if (next !== playing) {
+                before = playing;
+                playing = next;
+            }
+            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, choice };
+    }
+    return { program: found, args, folder, env: childEnv, shell: context.platform === "win32" && /\.(cmd|bat)$/i.test(found), choice };
+}
+const hostTitle = { claude: "Claude Code", codex: "Codex" };
+// Runs the host as runHost does, the seat noting the model and effort it is given; one not installed, or that could not start, fails saying so.
+async function started(context, host, again) {
+    const launch = hostLaunch(context, host);
+    takeSeat(launch.folder, { pid: process.pid, host, ...launch.choice });
+    return runHost(launch, again, context.platform).catch((error) => {
+        throw new Error(`${hostTitle[host]} did not start: ${error.message}`);
+    });
+}
+// 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,33 @@
+/** The play process in the seat: its process id, its host, and the model and effort it started that host with, none for the host's own. */
+export interface Seat {
+    readonly pid: number;
+    readonly host: string;
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
+/**
+ * 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;
+/** The play process that holds the seat, with the model and effort it started its host with; none when no one holds it. */
+export declare function seatHeld(folder: string, now?: Date): Seat | undefined;
+/** Asks the play process in the seat to start its host again, or `again.host` in its place: whether one holds it, and was asked. */
+export declare function askAgain(folder: string, now?: Date, again?: Again): boolean;
+/** What the table asks the play process in the seat: to start its host again, or the host named in its place (D-107). */
+export interface Again {
+    readonly host?: string;
+}
+/** What the table asked this play process, when it asked it to start its host again; the request is taken. */
+export declare function askedAgain(folder: string, pid: number): Again | undefined;
+/** 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,80 @@
+// 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;
+}
+/** The play process that holds the seat, with the model and effort it started its host with; none when no one holds it. */
+export function seatHeld(folder, now = new Date()) {
+    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;
+}
+/** Asks the play process in the seat to start its host again, or `again.host` in its place: whether one holds it, and was asked. */
+export function askAgain(folder, now = new Date(), again = {}) {
+    const held = seatHeld(folder, now);
+    if (held === undefined) {
+        return false;
+    }
+    writeAtomically(join(folder, againFile), `${JSON.stringify({ pid: held.pid, ...again })}\n`);
+    return true;
+}
+/** What the table asked this play process, when it asked it to start its host again; the request is taken. */
+export function askedAgain(folder, pid) {
+    const asked = jsonIn(join(folder, againFile));
+    if (asked?.pid !== pid) {
+        return undefined;
+    }
+    rmSync(join(folder, againFile), { force: true });
+    return typeof asked.host === "string" ? { host: asked.host } : {};
+}
+/** 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 seatIn(folder) {
+    const seat = jsonIn(join(folder, seatFile));
+    if (typeof seat?.pid !== "number" || typeof seat.host !== "string") {
+        return undefined;
+    }
+    const text = (value) => (typeof value === "string" ? value : undefined);
+    return { pid: seat.pid, host: seat.host, model: text(seat.model), effort: text(seat.effort) };
+}
+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;