@datamoc/mw_games 0.16.0 → 0.17.1

package/tools/multiplayer-server.d.mts

@@ -0,0 +1,27 @@
+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;

package/tools/multiplayer-server.mjs

@@ -0,0 +1,195 @@
+#!/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);
+	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}`);
+}

package/tools/mwl.mjs

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';

package/tools/sbom.d.mts

@@ -0,0 +1,83 @@
+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 }>>;

package/tools/sbom.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const OUTPUT = 'sbom.cdx.json';
+/** this tool's own package, named in every document's `metadata.tools` whichever project it describes */
+const TOOL = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const SPEC_VERSION = '1.6';
+
+const HASH_ALGORITHMS = { sha512: 'SHA-512', sha384: 'SHA-384', sha256: 'SHA-256', sha1: 'SHA-1' };
+
+/** the RFC 4122 DNS namespace, undashed because it is only ever fed to the hash as bytes */
+const DNS_NAMESPACE = '6ba7b8109dad11d180b400c04fd430c8';
+
+/**
+ * Package URL for an npm package, the SBOM's `bom-ref` as well. A scoped name's `@` is
+ * percent-encoded but its `/` is not, which is what the purl spec's own npm examples do
+ * (`pkg:npm/%40angular/animation@12.3.1`).
+ */
+export function purlFor(name, version) {
+	const encoded = name.startsWith('@') ? `%40${name.slice(1)}` : name;
+	return `pkg:npm/${encoded}@${version}`;
+}
+
+/**
+ * npm's `integrity` field (`sha512-<base64>`, sometimes several space-separated) as CycloneDX
+ * hashes. CycloneDX carries a hash as lowercase hex, so the base64 is decoded and re-encoded.
+ */
+export function hashesFromIntegrity(integrity) {
+	if (typeof integrity !== 'string') return [];
+	const hashes = [];
+	for (const part of integrity.split(/\s+/)) {
+		const dash = part.indexOf('-');
+		if (dash < 0) continue;
+		const alg = HASH_ALGORITHMS[part.slice(0, dash).toLowerCase()];
+		if (alg === undefined) continue;
+		hashes.push({ alg, content: Buffer.from(part.slice(dash + 1), 'base64').toString('hex') });
+	}
+	return hashes;
+}
+
+/** an SPDX id stays an `id`; anything with spaces or an expression stays a `name` instead */
+function licenseFor(license) {
+	if (typeof license !== 'string' || license.trim() === '') return undefined;
+	const value = license.trim();
+	return /^[A-Za-z0-9.+-]+$/.test(value) ? { license: { id: value } } : { license: { name: value } };
+}
+
+/** the package a lockfile location holds: `node_modules/@scope/name` is `@scope/name` */
+function nameFromLocation(location) {
+	const marker = 'node_modules/';
+	return location.slice(location.lastIndexOf(marker) + marker.length);
+}
+
+/** node resolution over a lockfile: the nearest `node_modules/<name>` at or above `location` */
+function resolveDependency(packages, location, name) {
+	let dir = location;
+	for (;;) {
+		const candidate = dir === '' ? `node_modules/${name}` : `${dir}/node_modules/${name}`;
+		if (packages[candidate] !== undefined) return candidate;
+		if (dir === '') return undefined;
+		const marker = dir.lastIndexOf('/node_modules/');
+		dir = marker < 0 ? '' : dir.slice(0, marker);
+	}
+}
+
+function scopeOf(entry) {
+	if (entry.dev === true) return 'excluded';
+	if (entry.optional === true) return 'optional';
+	return 'required';
+}
+
+/** required beats optional beats excluded when one purl is reachable more than one way */
+const SCOPE_RANK = { required: 0, optional: 1, excluded: 2 };
+
+/**
+ * A version-5 (RFC 4122 name-based) UUID in the DNS namespace. The same name always hashes to the
+ * same UUID, which is what lets `serialNumber` below be derived instead of invented; twelve lines
+ * of SHA-1 beats a dependency for the one UUID this tool will ever need.
+ */
+function uuidv5(name) {
+	const bytes = createHash('sha1')
+		.update(Buffer.from(DNS_NAMESPACE, 'hex'))
+		.update(name, 'utf8')
+		.digest()
+		.subarray(0, 16);
+	bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+	bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+	const hex = bytes.toString('hex');
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Builds a CycloneDX document from `package.json` and `package-lock.json` alone, so the SBOM is
+ * reproducible and needs no network access. Every locked package is a component (dev-only ones
+ * marked `excluded`, since they are not part of a published install) and the lockfile's own
+ * resolution is turned into the dependency graph. Output is deterministic: components and edges
+ * are sorted and `serialNumber` is a UUID derived from the document's own content rather than
+ * from the clock, so the committed file can be checked for drift the way `API_REPORT.md` and
+ * `PROJECT_STATS.json` already are: two BOMs that share a serial are the same BOM, and any change
+ * to a component, a hash or an edge produces a new one.
+ *
+ * `metadata.timestamp` is deliberately absent. A generation time stamped into a committed file is
+ * either a drift-check failure on every run or one stale moment every later read is dated to,
+ * while `CHANGELOG.md` already dates each version.
+ *
+ * `type` is the described component's CycloneDX type: `'library'` for this framework,
+ * `'application'` for a game (`mwg-sbom` picks it from whether the project is `private`).
+ */
+export function buildSbom(packageJson, lockfile, { type = 'library' } = {}) {
+	const packages = lockfile.packages ?? {};
+	const rootPurl = purlFor(packageJson.name, packageJson.version);
+
+	const byPurl = new Map();
+	for (const [location, entry] of Object.entries(packages)) {
+		if (location === '' || entry.link === true || typeof entry.version !== 'string') continue;
+		const name = typeof entry.name === 'string' ? entry.name : nameFromLocation(location);
+		const purl = purlFor(name, entry.version);
+		const scope = scopeOf(entry);
+		const existing = byPurl.get(purl);
+		if (existing !== undefined) {
+			if (SCOPE_RANK[scope] < SCOPE_RANK[existing.scope]) existing.scope = scope;
+			continue;
+		}
+		const component = { type: 'library', 'bom-ref': purl, name, version: entry.version, purl, scope };
+		const hashes = hashesFromIntegrity(entry.integrity);
+		if (hashes.length > 0) component.hashes = hashes;
+		const licenses = licenseFor(entry.license);
+		if (licenses !== undefined) component.licenses = [licenses];
+		byPurl.set(purl, component);
+	}
+
+	const components = [...byPurl.values()].sort((a, b) => (a.purl < b.purl ? -1 : a.purl > b.purl ? 1 : 0));
+
+	const edges = new Map();
+	const addEdge = (from, to) => {
+		if (!edges.has(from)) edges.set(from, new Set());
+		edges.get(from).add(to);
+	};
+	for (const [location, entry] of Object.entries(packages)) {
+		if (location !== '' && (entry.link === true || typeof entry.version !== 'string')) continue;
+		const from =
+			location === ''
+				? rootPurl
+				: purlFor(typeof entry.name === 'string' ? entry.name : nameFromLocation(location), entry.version);
+		const declared = {
+			...(entry.dependencies ?? {}),
+			...(entry.devDependencies ?? {}),
+			...(entry.optionalDependencies ?? {}),
+			...(entry.peerDependencies ?? {}),
+		};
+		for (const name of Object.keys(declared)) {
+			const target = resolveDependency(packages, location, name);
+			const targetEntry = target === undefined ? undefined : packages[target];
+			if (targetEntry === undefined || typeof targetEntry.version !== 'string') continue;
+			const targetName = typeof targetEntry.name === 'string' ? targetEntry.name : nameFromLocation(target);
+			addEdge(from, purlFor(targetName, targetEntry.version));
+		}
+	}
+
+	const refs = [rootPurl, ...components.map((component) => component['bom-ref'])];
+	const dependencies = [...new Set(refs)]
+		.sort()
+		.map((ref) => ({ ref, dependsOn: [...(edges.get(ref) ?? [])].sort() }));
+
+	return document(packageJson, type, components, dependencies);
+}
+
+/** the envelope both builders share, with the content-derived serial */
+function document(packageJson, type, components, dependencies) {
+	const rootPurl = purlFor(packageJson.name, packageJson.version);
+	const rootLicenses = licenseFor(packageJson.license);
+	const metadata = {
+		tools: {
+			components: [{ type: 'application', group: 'datamoc', name: 'tools/sbom.mjs', version: TOOL.version }],
+		},
+		component: {
+			type,
+			'bom-ref': rootPurl,
+			name: packageJson.name,
+			version: packageJson.version,
+			purl: rootPurl,
+			...(typeof packageJson.description === 'string' ? { description: packageJson.description } : {}),
+			...(rootLicenses === undefined ? {} : { licenses: [rootLicenses] }),
+		},
+	};
+	return {
+		bomFormat: 'CycloneDX',
+		specVersion: SPEC_VERSION,
+		serialNumber: `urn:uuid:${uuidv5(JSON.stringify({ metadata, components, dependencies }))}`,
+		version: 1,
+		metadata,
+		components,
+		dependencies,
+	};
+}
+
+/**
+ * The package a bundled module came from: the last `node_modules/<name>` (or `<@scope/name>`) in
+ * its path, with the directory holding that package's `package.json`. Null for the game's own
+ * source and for bundler-virtual modules.
+ */
+export function packageOfModule(id) {
+	const path = id.replace(/^\0/, '').split('?')[0].split(sep).join('/');
+	const marker = path.lastIndexOf('/node_modules/');
+	if (marker < 0) return null;
+	const parts = path.slice(marker + '/node_modules/'.length).split('/');
+	const name = parts[0].startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
+	if (!name || name.startsWith('.')) return null;
+	return { name, dir: `${path.slice(0, marker)}/node_modules/${name}` };
+}
+
+/**
+ * The SBOM of what a build actually ships, rather than of `node_modules` (item 380): a game is
+ * one tree-shaken bundle, so the lockfile lists tooling that never reaches a player and cannot say
+ * which packages did. `modules` are the bundle's module ids (vite's module graph, collected by
+ * `mwgPage()`), each package they come from becomes a `required` library component with its
+ * version and licence read from its own `package.json`, and `files` are the shipped files as
+ * `file` components carrying their SHA-256.
+ *
+ * @param {{ packageJson: object, modules: string[], files: { path: string, sha256: string }[] }} input
+ */
+export function buildArtifactSbom({ packageJson, modules, files }) {
+	const packages = new Map();
+	for (const id of modules) {
+		const found = packageOfModule(id);
+		if (!found || packages.has(found.dir)) continue;
+		let manifest;
+		try {
+			manifest = JSON.parse(readFileSync(join(found.dir, 'package.json'), 'utf8'));
+		} catch {
+			continue;
+		}
+		packages.set(found.dir, {
+			name: manifest.name ?? found.name,
+			version: manifest.version,
+			license: manifest.license,
+		});
+	}
+	const libraries = new Map();
+	for (const { name, version, license } of packages.values()) {
+		if (typeof version !== 'string') continue;
+		const purl = purlFor(name, version);
+		const licenses = licenseFor(license);
+		libraries.set(purl, {
+			type: 'library',
+			'bom-ref': purl,
+			name,
+			version,
+			purl,
+			scope: 'required',
+			...(licenses === undefined ? {} : { licenses: [licenses] }),
+		});
+	}
+	const fileComponents = [...files]
+		.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+		.map(({ path, sha256 }) => ({
+			type: 'file',
+			'bom-ref': `file:${path}`,
+			name: path,
+			hashes: [{ alg: 'SHA-256', content: sha256 }],
+		}));
+	const components = [...[...libraries.values()].sort((a, b) => (a.purl < b.purl ? -1 : 1)), ...fileComponents];
+	const rootPurl = purlFor(packageJson.name, packageJson.version);
+	const dependencies = [{ ref: rootPurl, dependsOn: [...libraries.keys()].sort() }];
+	return document(packageJson, 'application', components, dependencies);
+}
+
+/** SHA-256 of every file under `dist` a player receives: precompressed siblings and the SBOM itself left out */
+export async function shippedFiles(dist) {
+	const { walk } = await import('./compile-resources.mjs');
+	const files = [];
+	for await (const file of walk(dist)) {
+		const path = relative(dist, file).split(sep).join('/');
+		if (/\.(gz|br|xz)$/.test(path) || path.endsWith('.cdx.json')) continue;
+		files.push({
+			path,
+			sha256: createHash('sha256')
+				.update(await readFile(file))
+				.digest('hex'),
+		});
+	}
+	return files;
+}
+
+/** the exact committed bytes: two-space JSON and a trailing newline */
+export function serialize(bom) {
+	return `${JSON.stringify(bom, null, 2)}\n`;
+}
+
+async function readJson(path) {
+	return JSON.parse(await readFile(path, 'utf8'));
+}
+
+/**
+ * `mwg-sbom [project folder] [--out=<file>] [--check]`: the lockfile SBOM of any npm project,
+ * this framework included (`npm run sbom` here). A `private` project is described as an
+ * `application`, anything else as a `library`. `--check` compares instead of writing, for CI.
+ */
+async function main(argv) {
+	const root = resolve(argv.find((arg) => !arg.startsWith('--')) ?? '.');
+	const out = resolve(root, argv.find((arg) => arg.startsWith('--out='))?.slice(6) ?? OUTPUT);
+	const packageJson = await readJson(join(root, 'package.json'));
+	const bom = buildSbom(packageJson, await readJson(join(root, 'package-lock.json')), {
+		type: packageJson.private === true ? 'application' : 'library',
+	});
+	const json = serialize(bom);
+	const name = relative(root, out) || out;
+	const summary = `CycloneDX ${SPEC_VERSION}, ${bom.components.length} components`;
+
+	if (argv.includes('--check')) {
+		const committed = await readFile(out, 'utf8').catch(() => undefined);
+		//CRLF is a Windows checkout's doing, not a difference in the BOM itself (and a missing
+		//file still reads as out of date: '' never equals the serialized BOM)
+		if ((committed ?? '').replace(/\r\n/g, '\n') !== json.replace(/\r\n/g, '\n')) {
+			console.error(`${name} is out of date with package-lock.json. Run "npm run sbom" and commit the result.`);
+			process.exitCode = 1;
+		} else {
+			console.log(`${name} matches package-lock.json (${summary}).`);
+		}
+	} else {
+		await writeFile(out, json, 'utf8');
+		console.log(`wrote ${name} (${summary})`);
+	}
+}
+
+//realpath, since an npm `bin` shim reaches this file through a symlink
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
+	await main(process.argv.slice(2));

package/tools/vendored/rgssad-wasm/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Nathaniel Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/tools/vendored/rgssad-wasm/README.md

@@ -0,0 +1,15 @@
+# rgssad-wasm (vendored)
+
+RGSSAD/RGSS2A archive decoder (RPG Maker XP / VX archives), compiled to
+WebAssembly. Used by `tools/extract-rgssad.mjs`.
+
+- Source: <https://github.com/nathaniel-daniel/rgssad-rs> (`rgssad-wasm`)
+- Licence: MIT (see `LICENSE-MIT`), © 2022 Nathaniel Daniel.
+  Upstream offers the crate under either MIT or Apache-2.0 at your option;
+  this project uses it under the MIT option.
+- Files vendored here: `rgssad_wasm.js`, `rgssad_wasm_bg.js`,
+  `rgssad_wasm_bg.wasm`, `rgssad_wasm.d.ts`, `rgssad_wasm_bg.wasm.d.ts`,
+  `package.json`.
+
+Nothing else in this repository is covered by this licence; `mwg` itself
+remains MPL-2.0 (see the root `LICENSE`).