@datamoc/mw_games 0.42.0 → 0.44.2

package/tools/find-chrome.mjs

@@ -17,9 +17,11 @@ async function playwright() {
 /**
  * The browser to drive: the platform's usual Chrome (or, on Windows, Edge), then a Chromium that
  * Playwright itself installed (`PLAYWRIGHT_BROWSERS_PATH`, common in CI images and containers),
- * then whatever is on PATH. `CHROME_PATH` overrides all of them in `launchChrome`.
+ * then whatever is on PATH. `CHROME_PATH` or `CHROME` overrides all of them.
  */
 export async function findChrome() {
+	const override = process.env.CHROME_PATH || process.env.CHROME;
+	if (override) return override;
 	const candidates =
 		process.platform === 'win32'
 			? [
@@ -93,7 +95,7 @@ async function playwrightChromium() {
  * page setup and assertions; this is the launch they all had in common.
  */
 export async function launchChrome({ argsEnv = 'MWG_BENCHMARK_CHROME_ARGS' } = {}) {
-	const executablePath = process.env.CHROME_PATH ?? (await findChrome());
+	const executablePath = await findChrome();
 	const extraArgs = (process.env[argsEnv] ?? '').split(' ').filter(Boolean);
 	const { chromium } = await playwright();
 	return chromium.launch({

package/tools/init.mjs

@@ -26,7 +26,13 @@ export function initFiles(name) {
 					private: true,
 					version: '0.0.0',
 					type: 'module',
-					scripts: { dev: 'vite', build: 'vite build', check: 'tsc --noEmit' },
+					scripts: {
+						dev: 'vite',
+						build: 'vite build',
+						check: 'tsc --noEmit',
+						test: 'node --test',
+						'hooks:install': 'git config core.hooksPath .githooks',
+					},
 					dependencies: { '@datamoc/mw_games': `^${PACKAGE_VERSION}`, 'pixi.js': '^8.20.1' },
 					devDependencies: { typescript: '^7.0.2', vite: '^8.2.2' },
 				},
@@ -101,7 +107,9 @@ export function initFiles(name) {
 			'',
 		].join('\n'),
 		'assets/.gitkeep': '',
-		'README.md': `# ${name}\n\n\`npm install\`, then \`npm run dev\` to play it while you edit, \`npm run build\` to write \`dist/\`.\nOpen \`dist/index.html\` (or \`dist/standalone.html\`) by double-clicking it: no server needed.\n\nPut images and sounds under \`assets/\`; the build compiles them into the page. An \`assets/credits.json\`\n(\`[{ "name": "...", "license": "...", "author": "...", "url": "..." }]\`) becomes \`dist/CREDITS.txt\`.\n`,
+		'.gitignore': 'node_modules/\ndist/\n.opencode/\n.coord-session\n',
+		'.githooks/pre-commit': '#!/bin/sh\nset -e\nnpm run check\nnpm test\n',
+		'README.md': `# ${name}\n\n\`npm install\`, then \`npm run dev\` to play it while you edit, \`npm run build\` to write \`dist/\`.\nOpen \`dist/index.html\` (or \`dist/standalone.html\`) by double-clicking it: no server needed.\n\nPut images and sounds under \`assets/\`; the build compiles them into the page. An \`assets/credits.json\`\n(\`[{ "name": "...", "license": "...", "author": "...", "url": "..." }]\`) becomes \`dist/CREDITS.txt\`.\n\nAfter \`git init\`, run \`npm run hooks:install\` to enable the included pre-commit hook.\nIt runs \`npm run check\` and \`npm test\`; add your tests under \`tests/\`.\n`,
 	};
 }
 
@@ -121,7 +129,7 @@ export function initProject(folder) {
 	)) {
 		const file = join(target, path);
 		mkdirSync(dirname(file), { recursive: true });
-		writeFileSync(file, content, 'utf8');
+		writeFileSync(file, content, { encoding: 'utf8', mode: path === '.githooks/pre-commit' ? 0o755 : 0o644 });
 		written.push(path);
 	}
 	return { folder: target, files: written };

package/tools/mwl.mjs

@@ -8,15 +8,24 @@ import {
 	collectHookReferences,
 	compile,
 	compileAndEmitSources,
+	compilePackages,
 	compileSources,
 	contentReport,
+	decodePackage,
+	emitArtifacts,
 	emitHooksDeclaration,
 	emitModule,
+	encodePackage,
 	extractCatalog,
+	generateCredits,
+	loadPackage,
+	mergePackage,
+	packageContent,
 	parse,
 	preprocess,
 	validate,
 	validateHookReferences,
+	verifyPackage,
 } from '../dist/mwl/index.js';
 
 /**
@@ -54,6 +63,9 @@ const commands = [
 	'ci',
 	'hooks',
 	'build',
+	'pack',
+	'unpack',
+	'verify',
 ];
 const [command, input] = args;
 const outputFlag = args.indexOf('-o');
@@ -67,16 +79,18 @@ const target = targetFlag === -1 ? undefined : args[targetFlag + 1];
 
 if (args.includes('--help') || args.includes('-h')) {
 	console.log(
-		'usage: mwg-mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build> input.mwl [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory]',
+		'usage: mwg-mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build|pack|unpack|verify> input.mwl|input.mwp|directory [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory] [--audio-converter module] [--allow capabilities] [--json]',
 	);
 	process.exit(0);
 }
 
 if (!command || !input || !commands.includes(command)) {
 	console.error(
-		'Usage: mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build> input.mwl [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory]',
+		'Usage: mwl <validate|compile|format|migrate|extract-i18n|assets|report|diagnostics|ci|hooks|build|pack|unpack|verify> input.mwl|input.mwp|directory [-o output] [--to 1.0] [--manifest hooks.json] [--asset-root directory] [--audio-converter module] [--allow capabilities] [--json]',
 	);
 	process.exitCode = 2;
+} else if (command === 'pack' || command === 'unpack' || command === 'verify' || /.mwp$/i.test(input)) {
+	process.exitCode = await packageCommand();
 } else {
 	const files = fs.statSync(input).isDirectory()
 		? collectSources(input)
@@ -322,3 +336,131 @@ async function hooks(files) {
 		fs.rmSync(entryFile, { force: true });
 	}
 }
+
+/**
+ * `pack <dir> -o x.mwp` writes a folder (`content.mwl` plus its media) as one package, refusing to
+ * write one that `verify` would reject. `unpack x.mwp -o dir` writes the files back. `verify x.mwp`
+ * checks digests, limits, schema, references, licences, ROM images and the capabilities requested
+ * (`--allow audio,script` applies a game policy, `--json` prints the report). Any other command
+ * given a `.mwp` runs on the content the package's characters expand to.
+ *
+ * Audio conversion to MWA belongs to the retro-audio package, not to mwg: `--audio-converter module`
+ * names an ES module whose default export is `(path, bytes) => { path, data } | undefined`, called
+ * for chip-music files (.ym .vgm .nsf .sid .dro .imf .cmf). Without it those files are packed as
+ * they are, with a warning.
+ */
+async function packageCommand() {
+	const flag = (name) => {
+		const at = args.indexOf(name);
+		return at === -1 ? undefined : args[at + 1];
+	};
+	if (command === 'pack') {
+		const root = path.resolve(input);
+		const converter = flag('--audio-converter');
+		const convert = converter ? (await import(pathToFileURL(path.resolve(converter)).href)).default : undefined;
+		if (converter && typeof convert !== 'function') throw new Error(`${converter} must default-export a function`);
+		const files = [];
+		const visit = (directory) => {
+			for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+				if (entry.name.startsWith('.')) continue;
+				const full = path.join(directory, entry.name);
+				if (entry.isDirectory()) visit(full);
+				else
+					files.push({
+						path: path.relative(root, full).split(path.sep).join('/'),
+						data: new Uint8Array(fs.readFileSync(full)),
+					});
+			}
+		};
+		visit(root);
+		const chip = /.(?:ym|vgm|nsf|sid|dro|imf|cmf)$/i;
+		const packed = [];
+		for (const file of files) {
+			if (!chip.test(file.path)) {
+				packed.push(file);
+				continue;
+			}
+			if (!convert)
+				console.error(`warning: ${file.path} is packed as it is; pass --audio-converter to store it as MWA`);
+			packed.push((convert && (await convert(file.path, file.data))) || file);
+		}
+		const bytes = await encodePackage(packed, { main: flag('--main') });
+		const report = await verifyPackage(bytes);
+		for (const warning of report.warnings) console.error(`warning: ${warning}`);
+		if (!report.ok) {
+			for (const error of report.errors) console.error(`error: ${error}`);
+			console.error('nothing was written');
+			return 1;
+		}
+		const target = path.resolve(output ?? `${root}.mwp`);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, bytes);
+		console.log(`packed ${packed.length} file(s) into ${target} (${report.ref})`);
+		return 0;
+	}
+	const bytes = new Uint8Array(fs.readFileSync(input));
+	if (command === 'verify') {
+		const allow = flag('--allow');
+		const report = await verifyPackage(
+			bytes,
+			allow === undefined ? {} : { policy: { allow: allow.split(',').filter(Boolean) } },
+		);
+		if (args.includes('--json')) console.log(JSON.stringify(report, null, '	'));
+		else {
+			for (const warning of report.warnings) console.error(`warning: ${warning}`);
+			for (const error of report.errors) console.error(`error: ${error}`);
+			if (report.ok)
+				console.log(
+					`${input}: valid package ${report.ref} (capabilities: ${report.capabilities.join(', ') || 'none'})`,
+				);
+		}
+		return report.ok ? 0 : 1;
+	}
+	if (command === 'unpack') {
+		const decoded = await decodePackage(bytes);
+		const target = path.resolve(output ?? input.replace(/.mwp$/i, ''));
+		for (const file of decoded.files) {
+			const destination = path.resolve(target, file.path);
+			if (!destination.startsWith(target + path.sep))
+				throw new Error(`${file.path} escapes the output directory`);
+			fs.mkdirSync(path.dirname(destination), { recursive: true });
+			fs.writeFileSync(destination, file.data);
+		}
+		console.log(`unpacked ${decoded.files.length} file(s) into ${target}`);
+		return 0;
+	}
+	if (!['validate', 'compile', 'extract-i18n', 'assets', 'report', 'build'].includes(command)) {
+		console.error(`mwl ${command} does not take a package; unpack it first`);
+		return 2;
+	}
+	const loaded = await loadPackage(bytes);
+	const set = mergePackage(loaded);
+	const game = compilePackages(set);
+	if (command === 'validate') {
+		console.log(`${input}: valid package`);
+		return 0;
+	}
+	if (command === 'build') {
+		const directory = path.resolve(output ?? 'generated');
+		fs.mkdirSync(directory, { recursive: true });
+		const content = JSON.stringify(packageContent(set), null, '	');
+		for (const artifact of emitArtifacts(game, {
+			artifacts: {
+				'package-content.json': `${content}
+`,
+			},
+		}))
+			fs.writeFileSync(path.join(directory, artifact.name), artifact.content);
+		const credits = generateCredits([loaded.document]);
+		if (credits) fs.writeFileSync(path.join(directory, 'CREDITS.txt'), credits);
+		console.log(`built package ${loaded.document.meta.id} into ${directory}`);
+		return 0;
+	}
+	const values =
+		command === 'extract-i18n' ? extractCatalog(game) : command === 'assets' ? game.assets : contentReport(game);
+	const text = `${JSON.stringify(values, null, '	')}
+`;
+	if (output) fs.writeFileSync(output, text);
+	else process.stdout.write(text);
+	return 0;
+}

package/tools/play-uci.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'node:url';
-import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { join, extname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { applyMove, cloneChess, legalMoves, parseFen, squareName, startingChess } from '../src/board/chess.ts';
-import { parseUciMove, probeBook } from '../src/board/openings.ts';
-import { searchTourney } from '../src/board/tourney.ts';
-import { loadTablebaseEnding, probeTablebase } from '../src/board/tablebase.ts';
+//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`

package/tools/vite.mjs

@@ -80,7 +80,15 @@ export function mwgPage(options = {}) {
 			const { assets: _assets, sbom = true, ...emitOptions } = options;
 			const source = assets ? resolve(root, assets) : undefined;
 			const dist = resolve(root, outDir);
-			await emitPage({ ...emitOptions, dist, assets: source && existsSync(source) ? source : undefined });
+			const page = await emitPage({
+				...emitOptions,
+				dist,
+				assets: source && existsSync(source) ? source : undefined,
+			});
+			if (page.unusedAssets.length > 0)
+				console.warn(
+					`mwg-page: ${page.unusedAssets.length} embedded asset(s) are never named in the game code: ${page.unusedAssets.join(', ')}`,
+				);
 			if (sbom) {
 				const manifest = join(root, 'package.json');
 				const packageJson = existsSync(manifest)

package/tools.md

@@ -13,7 +13,7 @@ by double-clicking. Run from the repo root.
 | `soundfonts` | Picks a SoundFont other than the bundled `microgm-opt` (WTFPL, 2.6 MB, the default). `list` prints the catalogue (`data/soundfont-catalog.json`, a licence-classified snapshot of the marmooo free-soundfonts collection: public domain, MIT and CC-BY fonts fetch freely, share-alike, copyleft and unclear ones need `--accept-licence`); `fetch <font>` downloads only the instruments the game's MIDI files use (`--midi`) or a list (`--programs 0,24,128:0`), and merges them into one SoundFont 3 (the compressed samples untouched, no decoding, no `ffmpeg`) beside a `.credits.txt` that keeps the licence with the file; the game decodes it where it runs with `loadSoundFont`. `fetch --sf2` and `convert <in.sf3> <out.sf2>` decode to a plain SoundFont 2 instead, about eight times larger, which needs `ffmpeg` on PATH (developer machines only). The result goes in the asset folder, where the build subsets it to the programs the game plays | `npx mwg-soundfonts list`, `npx mwg-soundfonts fetch GeneralUser_GS_v2.0.3 --midi assets/*.mid --accept-licence`, or `fetchSoundFont` from `@datamoc/mw_games/tools/soundfonts` |
 | `extract-rgssad` | Decrypts an RPG Maker XP/VX archive to plain files (vendored MIT decoder, developer-side only); an entry whose name would land outside `outDir` is refused (item 389) | `npm run extract:rgssad -- <archive.rgssad> <outDir>` here; `npx mwg-extract-rgssad <archive> <outDir>` or `extractRgssad` from `@datamoc/mw_games/tools/extract-rgssad` in a game |
 | `multiplayer-server` | The reference lockstep server for `core.LockstepClient`: rooms, one shared tick, `null` for a missed input, messages capped at `maxMessageBytes` (64 KB) and read through `parseInbound`, room names bounded, `maxClientsPerRoom` (64). Speaks `ws:`, so a deployment puts it behind a TLS proxy (items 129, 385) | `npx mwg-lockstep-server [port] [--host=]` (127.0.0.1 unless `--host`), or `createLockstepServer(options)` from `@datamoc/mw_games/tools/multiplayer-server`; needs the optional peer `ws` |
-| `mwl` | Compiles MWL content (`[game]`/`[scenario]`/`[side]`/`[unit]`/`[event]`/`[campaign]`) into a game-data module, an i18n catalog and an asset manifest | `npm run mwl -- build <contentDir> -o <outDir>`, or `node node_modules/@datamoc/mw_games/tools/mwl.mjs build <contentDir> -o <outDir>` from an install. It is a command line, not an importable module (it dispatches when loaded), so it has no package subpath; script against the typed library instead: `@datamoc/mw_games/mwl` |
+| `mwl` | Compiles MWL content (`[game]`/`[scenario]`/`[side]`/`[unit]`/`[event]`/`[campaign]`) into a game-data module, an i18n catalog and an asset manifest. Also packs a folder (`content.mwl` plus media) into one `.mwp` content package (`pack`), unpacks it, and verifies it (`verify`: digests, limits, schema, licences, instrument ROM refusal, requested capabilities); `build`, `validate`, `extract-i18n` and `assets` accept a `.mwp` in place of a folder. `pack --audio-converter <module>` is the hook for converting chip music to MWA, which lives in the retro-audio package | `npm run mwl -- build <contentDir> -o <outDir>`, or `node node_modules/@datamoc/mw_games/tools/mwl.mjs build <contentDir> -o <outDir>` from an install. It is a command line, not an importable module (it dispatches when loaded), so it has no package subpath; script against the typed library instead: `@datamoc/mw_games/mwl` |
 | `extract-html` | Splits the resources embedded in an HTML file (scripts, CSS, images) back out into files | `npm run extract:html -- <page.html> -o <outDir>`, or `extractHtml` from `@datamoc/mw_games/tools/extract-html` |
 | `compile-openings` | Compiles opening tables (`eco`, `name`, `pgn` TSV rows) into a position-keyed book JSON a game checks in beside its own code: SAN resolved against the real move generator, every position keeping its continuations, the longest line ending there naming it. Rows are vendored CC0 data (`data/openings/`), never fetched | `node tools/compile-openings.mjs <tsv folder> <book.json>`, or `npx mwg-openings <tsv folder> <book.json>` in a game |
 | `build-tablebases` | Solves pawnless white-extras-against-lone-king endings by retrograde analysis and ships them compiled as Huffman-coded JSON under `data/tablebases` (3-piece: `KQK KRK KBK KNK`; 4-piece like `KBNK KBBK` generate the same way but stay a tool run away, full 4-piece tables are tens of megabytes each). One `threads.spawn` task per ending over capped lanes (4-piece lanes stay narrow: hundreds of megabytes of arrays each); captures convert into the already-solved smaller tables, so 3-piece endings solve first. Golden counts: KQK 0/200896/99448/223944, KRK 0/201700/98644/223944, KBK/KNK all draws, KBBK 0/5628080/21071792/6854560, KBNK 0/11188168/8816020/13550244 (unknown/loss/draw/win) | `node tools/build-tablebases.mjs <outDir> [ending ...] [--jobs=N]`, or `npx mwg-tablebases <outDir> [ending ...]` in a game |
@@ -201,6 +201,7 @@ same build.
 | --- | --- | --- |
 | `roadmap-progress` | Reports CLOSED.md + ROADMAP.md completion: numbered items in batches of 25, plus the 1.0 exit checklist on its own row (checks to run, not capabilities, so they stay out of the numbered totals), optionally in a browser | `npm run roadmap:progress` |
 | `build-webpage-examples` / `build-webpage-docs` | Generate the live examples and Documentation page under `webpage/` (`REFERENCE.md` guide + TypeDoc under `documentation/api/` + the examples index) | `npm run webpage:examples`, `npm run webpage:docs` |
+| `build-bridge-tutorial` / `bins-smoke` | `build-bridge-tutorial` writes `webpage/tutorials/bridge/index.html` from `tools/templates/bridge-tutorial.html`, quoting the code blocks of `examples/bridge` so a test can check them. `bins-smoke` packs the project, installs the tarball in an empty folder and runs every `mwg-*` bin with `--help` on the Node that runs it; CI runs it on Node 20.19.0. Repository tools, not shipped | `npm run build:bridge-tutorial`, `npm run bins:smoke` |
 | `build-example-index` | Writes `documentation/examples.html`, read from source text (no typedoc, no renderer): for each public module the symbols that carry an `@example`, each linked to its typedoc page when one exists, with the runnable `examples/` that import the module. Part of `webpage:docs`; a repository tool, not shipped (item 430) | `npm run webpage:docs`, or `node tools/build-example-index.mjs [outFile]` |
 | `make-example-diagrams` / `make-architecture-diagrams` | Rebuild the generated diagrams under `webpage/assets` (never hand-drawn) | `npm run webpage:diagrams` |
 | `api-report` | Regenerates `API_REPORT.md` from the built declarations; `--check` compares instead. A CI gate | `npm run api:report`, `npm run api:check` |