@datamoc/mw_games 0.44.2 → 0.45.0

package/tools/multiplayer-server.d.mts

@@ -1,27 +1 @@
-import type { WebSocketServer } from 'ws';
-
-export interface LockstepServerOptions {
-	port?: number;
-	/** the address to listen on; every interface when omitted (the `mwg-lockstep-server` command defaults to 127.0.0.1) */
-	host?: string;
-	tickTimeoutMs?: number;
-	/** the room seed sent in every `welcome` */
-	seed?: number;
-	/** the JSON-safe state every peer starts from, sent in every `welcome` */
-	initialState?: unknown;
-	/** returning `false` or a reason rejects an input */
-	validateInput?: (payload: unknown) => boolean | string;
-	/** largest client message accepted, in bytes; defaults to 64 KB */
-	maxMessageBytes?: number;
-	/** further connections to a full room are closed with 1013; defaults to 64 */
-	maxClientsPerRoom?: number;
-}
-
-export interface LockstepServer {
-	wss: WebSocketServer;
-	ready: Promise<void>;
-	address: () => ReturnType<WebSocketServer['address']>;
-	close: () => Promise<void>;
-}
-
-export function createLockstepServer(options?: LockstepServerOptions): LockstepServer;
+export * from '@datamoc/mwg/tools/multiplayer-server';

package/tools/multiplayer-server.mjs

@@ -1,199 +1 @@
-#!/usr/bin/env node
-import { existsSync, realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-//the inbound pipeline every client-side reader uses: the TypeScript source inside this
-//repository, the built `dist` inside an installed package, which ships no `src`
-const { parseInbound } = await import(
-	existsSync(new URL('../src/core/Sanitize.ts', import.meta.url))
-		? '../src/core/Sanitize.ts'
-		: '../dist/core/index.js'
-);
-
-/** `ws`, an optional peer of the published package: only a game running this server needs it */
-const { WebSocketServer } = await import('ws').catch(() => {
-	throw new Error('the lockstep server needs ws: npm install ws');
-});
-
-/** a room name a client can choose: short, printable, so one client cannot mint unbounded keys */
-const ROOM_NAME = /^[\w-]{1,64}$/;
-
-/**
- * A reference lockstep server for `core.LockstepClient` (item 129 of ROADMAP.md).
- *
- * `mwg` ships no backend anywhere else - `FeedbackClient`/`NewsClient`/`SaveSyncClient` all
- * assume a game brings its own - but real-time multiplayer has no one-shot request/response
- * shape to hide a server behind, so this is a genuine exception, not a precedent for the rest
- * of the project: a game using this either runs it as-is or replaces it with its own server
- * speaking the same three-message protocol (`welcome`/`input`/`tick`).
- *
- * Model: each `room` (a `?room=` query string, default `"default"`) advances one shared tick
- * counter. A client's `{type: 'input', payload}` is buffered for the room's current tick; once
- * every currently-connected client in the room has submitted one, the server broadcasts
- * `{type: 'tick', tick, inputs}` (every client id mapped to its input, or `null` for anyone
- * who missed the deadline) and starts the next tick. A per-room timer also forces the
- * broadcast after `tickTimeoutMs` regardless of who has submitted, so one slow or dropped
- * client cannot stall everyone else forever - the reconciliation rule item 129 asked for,
- * kept as simple as a rule can be while still being real: nothing here guesses a missing
- * input, it is reported as `null` and left to the game's own rules to interpret (skip that
- * actor's turn, repeat its last input, whatever the game decides).
- */
-export function createLockstepServer(options = {}) {
-	const {
-		port = 0,
-		host,
-		tickTimeoutMs = 200,
-		seed,
-		initialState,
-		validateInput,
-		maxMessageBytes = 64 * 1024,
-		maxClientsPerRoom = 64,
-	} = options;
-	//ws accepts 100 MiB messages unless told otherwise; an input is a few bytes
-	const wss = new WebSocketServer({ port, host, maxPayload: maxMessageBytes });
-
-	const rooms = new Map();
-	let nextId = 1;
-
-	function room(name) {
-		let entry = rooms.get(name);
-		if (!entry) {
-			//submittedCount tracks how many of entry.clients currently have hasSubmitted set,
-			//kept in step by every place that changes hasSubmitted, rather than counting the
-			//whole client map on every single input message (checked on every message, not
-			//just once per tick, so it is worth not being O(clients) each time)
-			entry = { clients: new Map(), tick: 0, timer: null, submittedCount: 0 };
-			rooms.set(name, entry);
-		}
-		return entry;
-	}
-
-	function scheduleTimeout(entry) {
-		if (entry.timer) clearTimeout(entry.timer);
-		entry.timer = entry.clients.size > 0 ? setTimeout(() => advance(entry), tickTimeoutMs) : null;
-	}
-
-	function advance(entry) {
-		const inputs = {};
-		const checksums = {};
-		for (const [id, client] of entry.clients) {
-			inputs[id] = client.hasSubmitted ? client.pendingInput : null;
-			if (client.hasSubmitted && Number.isSafeInteger(client.pendingChecksum))
-				checksums[id] = client.pendingChecksum;
-			client.pendingInput = null;
-			client.pendingChecksum = null;
-			client.hasSubmitted = false;
-		}
-		entry.submittedCount = 0;
-		const message = JSON.stringify({
-			type: 'tick',
-			tick: entry.tick,
-			inputs,
-			...(Object.keys(checksums).length === 0 ? {} : { checksums }),
-		});
-		for (const client of entry.clients.values()) client.socket.send(message);
-		entry.tick += 1;
-		scheduleTimeout(entry);
-	}
-
-	function maybeAdvanceEarly(entry) {
-		if (entry.clients.size > 0 && entry.submittedCount === entry.clients.size) advance(entry);
-	}
-
-	wss.on('connection', (socket, request) => {
-		const url = new URL(request.url ?? '/', 'http://localhost');
-		const roomName = url.searchParams.get('room') ?? 'default';
-		if (!ROOM_NAME.test(roomName)) return socket.close(1008, 'invalid room name');
-		if ((rooms.get(roomName)?.clients.size ?? 0) >= maxClientsPerRoom) return socket.close(1013, 'room is full');
-		const id = `p${nextId++}`;
-		const entry = room(roomName);
-		entry.clients.set(id, { socket, pendingInput: null, hasSubmitted: false });
-
-		socket.send(
-			JSON.stringify({
-				type: 'welcome',
-				id,
-				...(seed === undefined ? {} : { seed }),
-				...(initialState === undefined ? {} : { initialState }),
-			}),
-		);
-		if (!entry.timer) scheduleTimeout(entry);
-
-		//ws reports an oversized or malformed frame as an 'error' event and closes the socket itself;
-		//with no listener, that event would throw and stop the whole server, every room with it
-		socket.on('error', () => {});
-
-		socket.on('message', (raw) => {
-			let message;
-			try {
-				message = parseInbound(String(raw), { maxBytes: maxMessageBytes, label: 'lockstep input' });
-			} catch {
-				return; //malformed input from one client must not take the room down
-			}
-			if (message?.type !== 'input') return;
-			const client = entry.clients.get(id);
-			if (!client) return;
-			const validation = validateInput?.(message.payload);
-			if (validation === false || typeof validation === 'string') {
-				socket.send(
-					JSON.stringify({
-						type: 'rejected',
-						reason: validation === false ? 'input rejected by server validation' : validation,
-					}),
-				);
-				return;
-			}
-			client.pendingInput = message.payload ?? null;
-			client.pendingChecksum = message.checksum;
-			if (!client.hasSubmitted) {
-				client.hasSubmitted = true;
-				entry.submittedCount += 1;
-			}
-			maybeAdvanceEarly(entry);
-		});
-
-		socket.on('close', () => {
-			const client = entry.clients.get(id);
-			if (client?.hasSubmitted) entry.submittedCount -= 1;
-			entry.clients.delete(id);
-			if (entry.clients.size === 0) {
-				if (entry.timer) clearTimeout(entry.timer);
-				rooms.delete(roomName);
-			} else {
-				maybeAdvanceEarly(entry);
-			}
-		});
-	});
-
-	return {
-		wss,
-		/** resolves once the server is actually listening; `address().port` is only valid after this */
-		ready: new Promise((resolve) => wss.once('listening', resolve)),
-		address: () => wss.address(),
-		close: () =>
-			new Promise((resolve) => {
-				for (const entry of rooms.values()) if (entry.timer) clearTimeout(entry.timer);
-				wss.close(() => resolve());
-			}),
-	};
-}
-
-/**
- * `mwg-lockstep-server [port] [--host=<address>]`: listens on 127.0.0.1 unless `--host` names
- * another address, so running it never exposes a port by accident. It speaks plain `ws:`, and
- * `LockstepClient` refuses `ws:` to anything but this machine: a deployment puts it behind a TLS
- * reverse proxy and connects with `wss:`.
- */
-//realpath, since an npm `bin` shim reaches this file through a symlink
-if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
-	const args = process.argv.slice(2);
-	if (args.includes('--help') || args.includes('-h')) {
-		console.log('usage: mwg-lockstep-server [port] [--host=<address>]');
-		process.exit(0);
-	}
-	const port = Number(args.find((arg) => !arg.startsWith('--')) ?? 8787);
-	const host = args.find((arg) => arg.startsWith('--host='))?.slice(7) ?? '127.0.0.1';
-	const server = createLockstepServer({ port, host });
-	await server.ready;
-	console.log(`mwg reference lockstep server listening on ws://${host}:${server.address().port}`);
-}
+export * from '@datamoc/mwg/tools/multiplayer-server';

package/tools/play-uci.d.mts

@@ -1,26 +1 @@
-import type { ChessMove } from '../src/board/chess.ts';
-import type { OpeningBook } from '../src/board/openings.ts';
-import type { LoadedEnding } from '../src/board/tablebase.ts';
-
-export interface UciSessionOptions {
-	/** plies when `go` names no depth */
-	depth?: number;
-	/** compiled opening book, probed before anything thinks */
-	book?: OpeningBook | null;
-	/** loaded tablebase endings, probed before the search */
-	tables?: Record<string, LoadedEnding>;
-}
-
-export interface UciSession {
-	/** one input line in, zero or more output lines out; never throws */
-	input(line: string): string[];
-}
-
-/** a move in UCI coordinates (`e2e4`, `e7e8q`). */
-export function uciString(move: ChessMove): string;
-
-/**
- * One stateful UCI conversation over the tournament engine: book, then
- * tablebase, then `searchTourney`. Feed it input lines, read back output lines.
- */
-export function createUciSession(options?: UciSessionOptions): UciSession;
+export * from '@datamoc/mwg/tools/play-uci';

package/tools/play-uci.mjs

@@ -1,205 +1 @@
-#!/usr/bin/env node
-import { fileURLToPath } from 'node:url';
-import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
-import { join, extname } from 'node:path';
-import { createInterface } from 'node:readline';
-//the framework's own modules: the TypeScript sources inside this repository, the built `dist` inside an
-//installed package, which ships no `src`
-const fromSource = existsSync(new URL('../src/board/chess.ts', import.meta.url));
-const load = (path) => import(fromSource ? `../src/${path}.ts` : `../dist/${path}.js`);
-const { applyMove, cloneChess, legalMoves, parseFen, squareName, startingChess } = await load('board/chess');
-const { parseUciMove, probeBook } = await load('board/openings');
-const { searchTourney } = await load('board/tourney');
-const { loadTablebaseEnding, probeTablebase } = await load('board/tablebase');
-
-/**
- * A UCI adapter over the tournament engine: `position`/`go` on stdin, `bestmove`
- * on stdout, the way a GUI expects. Move choice runs book first, then tablebase,
- * then `searchTourney`, so each layer only pays when the earlier ones miss.
- *
- * This is a Node tool, never part of the browser bundle: it reads files and
- * stdio, which a `file://` page cannot do. `info score` is centipawns from the
- * side to move's view (documented because GUIs vary); `bestmove 0000` answers
- * a position with no legal moves, per the UCI convention.
- *
- * usage: node tools/play-uci.mjs [--book <book.json>] [--tables <dir>] [--depth N]
- */
-
-const PROMOTION_LETTER = { queen: 'q', rook: 'r', bishop: 'b', knight: 'n' };
-
-export function uciString(move) {
-	return squareName(move.from) + squareName(move.to) + (move.promotion ? PROMOTION_LETTER[move.promotion] : '');
-}
-
-/**
- * One stateful conversation: feed it input lines, read back output lines. Pure
- * except for the injected search, book and tables, so tests drive transcripts
- * without spawning anything.
- */
-export function createUciSession(options = {}) {
-	const book = options.book ?? null;
-	const tables = options.tables ?? {};
-	const fallbackDepth = options.depth ?? 4;
-	let state = startingChess();
-	let halfmove = 0;
-
-	const findMove = (token) => {
-		let parsed;
-		try {
-			parsed = parseUciMove(token);
-		} catch {
-			return null;
-		}
-		return (
-			legalMoves(state).find(
-				(move) =>
-					move.from === parsed.from &&
-					move.to === parsed.to &&
-					(parsed.promotion === undefined
-						? move.promotion === undefined
-						: move.promotion === parsed.promotion),
-			) ?? null
-		);
-	};
-
-	const play = (move) => {
-		const target = move.to === state.enPassant && state.board[move.from]?.kind === 'pawn';
-		const capture = target || state.board[move.to] !== null;
-		const pawn = state.board[move.from]?.kind === 'pawn';
-		applyMove(state, move);
-		halfmove = pawn || capture ? 0 : halfmove + 1;
-	};
-
-	const tablebest = () => {
-		const ids = Object.keys(tables);
-		if (!ids.length) return null;
-		let best = null;
-		let complete = true;
-		for (const move of legalMoves(state)) {
-			const next = cloneChess(state);
-			applyMove(next, move);
-			const probe = probeTablebase(tables, next, halfmove);
-			if (!probe) {
-				complete = false;
-				continue;
-			}
-			const score =
-				probe.outcome === 'loss' ? 100000 - probe.dtm : probe.outcome === 'draw' ? 0 : -(100000 - probe.dtm);
-			if (best === null || score > best.score) best = { move, score };
-		}
-		//a forced mate beats any unprobed capture line; otherwise every successor
-		//must probe, or the search (which sees captures) takes the move instead
-		if (best !== null && (best.score > 90000 || complete)) return best;
-		return null;
-	};
-
-	const go = (args) => {
-		let depth = fallbackDepth;
-		let maxNodes;
-		let timeMs;
-		for (let i = 0; i < args.length; i++) {
-			if (args[i] === 'depth' && args[i + 1] !== undefined) depth = Math.max(1, Math.floor(Number(args[i + 1])));
-			if (args[i] === 'nodes' && args[i + 1] !== undefined)
-				maxNodes = Math.max(1, Math.floor(Number(args[i + 1])));
-			if (args[i] === 'movetime' && args[i + 1] !== undefined)
-				timeMs = Math.max(1, Math.floor(Number(args[i + 1])));
-		}
-		if (!Number.isInteger(depth)) depth = fallbackDepth;
-		const moves = legalMoves(state);
-		if (!moves.length) return ['bestmove 0000'];
-		const entry = book ? probeBook(book, state) : null;
-		if (entry?.moves.length) return ['info string book', `bestmove ${entry.moves[0]}`];
-		const tabled = tablebest();
-		if (tabled) return ['info string tablebase', `bestmove ${uciString(tabled.move)}`];
-		const result = searchTourney(state, { depth, maxNodes, timeMs });
-		if (!result.move) return ['bestmove 0000'];
-		return [
-			`info depth ${result.depth} score cp ${result.score} nodes ${result.nodes}`,
-			`bestmove ${uciString(result.move)}`,
-		];
-	};
-
-	const position = (args) => {
-		const movesAt = args.indexOf('moves');
-		const head = movesAt === -1 ? args : args.slice(0, movesAt);
-		const tail = movesAt === -1 ? [] : args.slice(movesAt + 1);
-		if (head[0] === 'startpos') {
-			state = startingChess();
-			halfmove = 0;
-		} else if (head[0] === 'fen') {
-			try {
-				const fen = head.slice(1).join(' ');
-				state = parseFen(fen);
-				const parts = fen.split(' ');
-				halfmove = parts[4] !== undefined && /^\d+$/.test(parts[4]) ? Number(parts[4]) : 0;
-			} catch {
-				return [`info string bad fen: ${head.slice(1).join(' ')}`];
-			}
-		} else {
-			return [`info string unknown position: ${head[0] ?? ''}`];
-		}
-		for (const token of tail) {
-			const move = findMove(token);
-			if (!move) return [`info string illegal move: ${token}`];
-			play(move);
-		}
-		return [];
-	};
-
-	return {
-		input(line) {
-			const parts = line
-				.trim()
-				.split(/\s+/)
-				.filter((part) => part.length);
-			if (!parts.length) return [];
-			const [command, ...args] = parts;
-			if (command === 'uci') return ['id name mwg tourney', 'uciok'];
-			if (command === 'isready') return ['readyok'];
-			if (command === 'ucinewgame') {
-				state = startingChess();
-				halfmove = 0;
-				return [];
-			}
-			if (command === 'position') return position(args);
-			if (command === 'go') return go(args);
-			if (command === 'quit') return [];
-			return [`info string unknown command: ${command}`];
-		},
-	};
-}
-
-//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
-//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
-const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
-
-if (isMain) {
-	const args = process.argv.slice(2);
-	if (args.includes('--help') || args.includes('-h')) {
-		console.log('usage: mwg-uci [--book <book.json>] [--tables <dir>] [--depth N]');
-		process.exit(0);
-	}
-	const flag = (name) => {
-		const at = args.indexOf(name);
-		return at === -1 ? undefined : args[at + 1];
-	};
-	const bookPath = flag('--book');
-	const tablesDir = flag('--tables');
-	const depth = flag('--depth') === undefined ? 4 : Math.max(1, Math.floor(Number(flag('--depth'))));
-	const book = bookPath ? JSON.parse(readFileSync(bookPath, 'utf8')) : null;
-	if (book && book.version !== 1) throw new Error(`${bookPath}: unknown opening-book version`);
-	const tables = {};
-	if (tablesDir) {
-		for (const file of readdirSync(tablesDir)) {
-			if (extname(file) !== '.json') continue;
-			const ending = loadTablebaseEnding(JSON.parse(readFileSync(join(tablesDir, file), 'utf8')));
-			tables[ending.id] = ending;
-		}
-	}
-	const session = createUciSession({ book, tables, depth });
-	const lines = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
-	for await (const line of lines) {
-		if (line.trim() === 'quit') break;
-		for (const out of session.input(line)) console.log(out);
-	}
-}
+export * from '@datamoc/mwg/tools/play-uci';

package/tools/sbom.d.mts

@@ -1,83 +1 @@
-export interface CycloneDxHash {
-	alg: string;
-	content: string;
-}
-
-export interface CycloneDxLicense {
-	license: { id?: string; name?: string };
-}
-
-export interface CycloneDxComponent {
-	type: 'library' | 'application' | 'file';
-	'bom-ref': string;
-	name: string;
-	/** absent on a `file` component, which is identified by its hash */
-	version?: string;
-	purl?: string;
-	scope?: 'required' | 'optional' | 'excluded';
-	hashes?: CycloneDxHash[];
-	licenses?: CycloneDxLicense[];
-	description?: string;
-}
-
-export interface CycloneDxBom {
-	bomFormat: 'CycloneDX';
-	specVersion: string;
-	serialNumber: string;
-	version: number;
-	metadata: {
-		tools: { components: CycloneDxComponent[] };
-		component: CycloneDxComponent;
-	};
-	components: CycloneDxComponent[];
-	dependencies: Array<{ ref: string; dependsOn: string[] }>;
-}
-
-export interface LockfilePackage {
-	version?: string;
-	integrity?: string;
-	license?: string;
-	name?: string;
-	dev?: boolean;
-	optional?: boolean;
-	link?: boolean;
-	dependencies?: Record<string, string>;
-	devDependencies?: Record<string, string>;
-	optionalDependencies?: Record<string, string>;
-	peerDependencies?: Record<string, string>;
-}
-
-export interface Lockfile {
-	packages?: Record<string, LockfilePackage>;
-}
-
-export interface PackageJson {
-	name: string;
-	version: string;
-	description?: string;
-	license?: string;
-	private?: boolean;
-}
-
-export function purlFor(name: string, version: string): string;
-export function hashesFromIntegrity(integrity: unknown): CycloneDxHash[];
-/** `type`: `'library'` (the default) or `'application'` for a game */
-export function buildSbom(
-	packageJson: PackageJson,
-	lockfile: Lockfile,
-	options?: { type?: 'library' | 'application' },
-): CycloneDxBom;
-export function serialize(bom: CycloneDxBom): string;
-
-/** the npm package a bundled module id belongs to, or null for the game's own source */
-export function packageOfModule(id: string): { name: string; dir: string } | null;
-
-/** the SBOM of what a build ships: the packages its modules came from, and its files with their SHA-256 */
-export function buildArtifactSbom(input: {
-	packageJson: PackageJson;
-	modules: string[];
-	files: Array<{ path: string; sha256: string }>;
-}): CycloneDxBom;
-
-/** SHA-256 of every shipped file under `dist`, precompressed siblings and SBOMs left out */
-export function shippedFiles(dist: string): Promise<Array<{ path: string; sha256: string }>>;
+export * from '@datamoc/mwg/tools/sbom';