@vibemancer/core 0.1.0

package/src/engine/sandbox-compile.ts

@@ -0,0 +1,197 @@
+/**
+ * VIBEMANCER — SANDBOX COMPILATION
+ *
+ * Compiles match bundles using esbuild. Extracted from sandbox.ts so that
+ * compilation can be used independently of isolated-vm (e.g., in the CLI
+ * dev server or for browser Web Worker sandboxes).
+ *
+ * This file has NO isolated-vm dependency — only esbuild + Node.js builtins.
+ */
+
+import {build} from 'esbuild';
+import path from 'node:path';
+import fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {PROTOTYPE_FREEZE_BANNER, generateManualMatchEntryPoint, generateMatchEntryPoint} from './sandbox-harness.js';
+
+const currentFilename = fileURLToPath(import.meta.url);
+const currentDirname = path.dirname(currentFilename);
+
+/**
+ * Find the src/engine/ directory. Works from src/, dist/engine/, or dist/ (tsup bundle).
+ * esbuild needs TypeScript source files, so we look for the src/ tree.
+ */
+export function getEngineDir(): string
+{
+	// When running from src/engine/ (dev/test), currentDirname is already src/engine/
+	const directPath = path.resolve(currentDirname);
+	if (fs.existsSync(path.join(directPath, 'simulation.ts')))
+	{
+		return directPath;
+	}
+
+	// When running from dist/engine/ (individual files), package root is 2 levels up
+	const packageRoot2 = path.resolve(currentDirname, '..', '..');
+	const srcEngine2 = path.join(packageRoot2, 'src', 'engine');
+	if (fs.existsSync(path.join(srcEngine2, 'simulation.ts')))
+	{
+		return srcEngine2;
+	}
+
+	// When running from dist/ (tsup bundle), package root is 1 level up
+	const packageRoot1 = path.resolve(currentDirname, '..');
+	const srcEngine1 = path.join(packageRoot1, 'src', 'engine');
+	if (fs.existsSync(path.join(srcEngine1, 'simulation.ts')))
+	{
+		return srcEngine1;
+	}
+
+	throw new Error('Could not find engine source directory (src/engine/simulation.ts)');
+}
+
+/**
+ * A compiled bot ready for sandboxed execution.
+ * Stores the source path and export name — actual compilation
+ * happens when creating a MatchSandbox or calling compileMatchBundle.
+ */
+export class BotBundle
+{
+	readonly sourcePath: string;
+	readonly exportName: string;
+
+	constructor(sourcePath: string, exportName: string)
+	{
+		if (!sourcePath || typeof sourcePath !== 'string')
+		{
+			throw new Error('sourcePath must be a non-empty string');
+		}
+		if (!exportName || typeof exportName !== 'string')
+		{
+			throw new Error('exportName must be a non-empty string');
+		}
+		this.sourcePath = path.resolve(sourcePath);
+		this.exportName = exportName;
+	}
+}
+
+/**
+ * Options for esbuild compilation. Allows the caller to add esbuild
+ * aliases (e.g., resolving @vibemancer/core to the TypeScript source).
+ */
+export interface CompileOptions
+{
+	/** Additional esbuild alias entries (e.g., {'@vibemancer/core': '/path/to/src/index.ts'}). */
+	alias?: Record<string, string>;
+	/** Additional modules to treat as external (not bundled). */
+	external?: string[];
+}
+
+/**
+ * Compile a match bundle using esbuild. Bundles both bots + simulation engine
+ * into a single self-contained IIFE with prototype freezing banner.
+ *
+ * No isolated-vm dependency — returns a plain JS string.
+ */
+export async function compileMatchBundle(
+	bot1: BotBundle,
+	bot2: BotBundle,
+	options?: CompileOptions,
+): Promise<string>
+{
+	const engineDir = getEngineDir();
+	const entryPoint = generateMatchEntryPoint(
+		bot1.sourcePath,
+		bot1.exportName,
+		bot2.sourcePath,
+		bot2.exportName,
+		engineDir,
+	);
+
+	const result = await build({
+		stdin: {
+			contents: entryPoint,
+			resolveDir: engineDir,
+			loader: 'ts',
+		},
+		bundle: true,
+		write: false,
+		format: 'iife',
+		platform: 'neutral',
+		target: 'es2022',
+		banner: {
+			js: PROTOTYPE_FREEZE_BANNER,
+		},
+		// Suppress warnings about top-level this in ESM
+		logLevel: 'error',
+		// Match bundles run in sandboxed environments (Web Workers / isolated-vm)
+		// and should never include Node.js native modules
+		external: [
+			'isolated-vm', 'esbuild', 'node:path', 'node:fs', 'node:url',
+			'node:worker_threads', 'node:crypto', 'node:os', 'node:child_process',
+			...(options?.external ?? []),
+		],
+		...(options?.alias ? {alias: options.alias} : {}),
+	});
+
+	if (!result.outputFiles?.[0])
+	{
+		throw new Error('esbuild produced no output');
+	}
+
+	return result.outputFiles[0].text;
+}
+
+/**
+ * Compile a manual-play sandbox bundle. Bundles ONE opponent bot + ManualMatch
+ * + simulation engine into a self-contained IIFE. The "player" wizard is a
+ * worker-local stub that reads from `__latestHumanActions` (set per-step by
+ * the host).
+ *
+ * Returns a plain JS string that, when loaded into a Web Worker, exposes the
+ * `__manualMatchInit`, `__manualMatchStep`, `__manualMatchHijack`,
+ * `__manualMatchRelease`, `__manualMatchSetInvincible`,
+ * `__manualMatchGetState`, `__manualMatchGetResult`, and `__manualMatchDispose`
+ * globals on the worker's globalThis.
+ */
+export async function compileManualMatchBundle(
+	opponent: BotBundle,
+	options?: CompileOptions,
+): Promise<string>
+{
+	const engineDir = getEngineDir();
+	const entryPoint = generateManualMatchEntryPoint(
+		opponent.sourcePath,
+		opponent.exportName,
+		engineDir,
+	);
+
+	const result = await build({
+		stdin: {
+			contents: entryPoint,
+			resolveDir: engineDir,
+			loader: 'ts',
+		},
+		bundle: true,
+		write: false,
+		format: 'iife',
+		platform: 'neutral',
+		target: 'es2022',
+		banner: {
+			js: PROTOTYPE_FREEZE_BANNER,
+		},
+		logLevel: 'error',
+		external: [
+			'isolated-vm', 'esbuild', 'node:path', 'node:fs', 'node:url',
+			'node:worker_threads', 'node:crypto', 'node:os', 'node:child_process',
+			...(options?.external ?? []),
+		],
+		...(options?.alias ? {alias: options.alias} : {}),
+	});
+
+	if (!result.outputFiles?.[0])
+	{
+		throw new Error('esbuild produced no output');
+	}
+
+	return result.outputFiles[0].text;
+}

package/src/engine/sandbox-harness.ts

@@ -0,0 +1,367 @@
+/**
+ * VIBEMANCER — SANDBOX HARNESS
+ *
+ * Generates the entry point code that runs inside an isolated-vm isolate.
+ * The harness bundles both bots + the simulation engine into a single IIFE
+ * via esbuild, then exposes __fight and __simulate on globalThis.
+ *
+ * The prototype freeze banner runs before any module code, preventing
+ * prototype pollution attacks between bots sharing the same isolate.
+ */
+
+/**
+ * JavaScript code injected as esbuild banner — runs before the IIFE bundle.
+ *
+ * 1. Freezes all built-in prototypes to prevent cross-bot sabotage via prototype
+ *    pollution. This does NOT prevent calling existing methods (e.g. Array.push
+ *    still works), it only prevents reassigning them.
+ *
+ * 2. Blocks all IO/network capabilities. Web Workers have fetch, XMLHttpRequest,
+ *    WebSocket, importScripts, etc. Bot code must not be able to make network
+ *    calls or load external scripts. Uses Object.defineProperty to make the block
+ *    irrecoverable (non-writable, non-configurable). In isolated-vm, these globals
+ *    don't exist — the try-catch makes the deletes a harmless no-op.
+ */
+export const PROTOTYPE_FREEZE_BANNER = `
+Object.freeze(Object.prototype);
+Object.freeze(Array.prototype);
+Object.freeze(Function.prototype);
+Object.freeze(String.prototype);
+Object.freeze(Number.prototype);
+Object.freeze(Boolean.prototype);
+Object.freeze(RegExp.prototype);
+Object.freeze(Date.prototype);
+Object.freeze(Error.prototype);
+Object.freeze(Map.prototype);
+Object.freeze(Set.prototype);
+Object.freeze(Math);
+Object.freeze(JSON);
+(function() {
+	var g = typeof globalThis !== 'undefined' ? globalThis : typeof self !== 'undefined' ? self : {};
+	var blocked = [
+		'fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource',
+		'importScripts', 'Worker', 'SharedWorker',
+		'Request', 'Response', 'Headers',
+		'navigator', 'BroadcastChannel',
+		'indexedDB', 'caches'
+	];
+	for (var i = 0; i < blocked.length; i++) {
+		try { Object.defineProperty(g, blocked[i], {value: undefined, writable: false, configurable: false}); }
+		catch(e) {}
+	}
+})();
+`;
+
+/**
+ * Generate the TypeScript entry point for a match sandbox.
+ *
+ * This entry point imports both bots and the simulation engine, then
+ * exposes __fight and __simulate on globalThis. esbuild bundles this
+ * + all transitive imports into a single self-contained IIFE.
+ *
+ * @param bot1SourcePath - Absolute path to bot 1's TypeScript source file
+ * @param bot1ExportName - Named export of bot 1's WizardFunction
+ * @param bot2SourcePath - Absolute path to bot 2's TypeScript source file
+ * @param bot2ExportName - Named export of bot 2's WizardFunction
+ * @param engineDir - Absolute path to the engine directory (src/engine/)
+ */
+export function generateMatchEntryPoint(
+	bot1SourcePath: string,
+	bot1ExportName: string,
+	bot2SourcePath: string,
+	bot2ExportName: string,
+	engineDir: string,
+): string
+{
+	// Use forward slashes for esbuild compatibility (works on all platforms)
+	const enginePath = engineDir.replace(/\\/g, '/');
+	const bot1Path = bot1SourcePath.replace(/\\/g, '/');
+	const bot2Path = bot2SourcePath.replace(/\\/g, '/');
+
+	// All imports use the engineDir's parent (= packages/core/src/) as root.
+	// When user bots alias @vibemancer/core → src/index-browser.ts, esbuild
+	// deduplicates these with the bot's imports since they resolve to the same files.
+	// This ensures the hooks runtime global state is shared between harness and bot.
+	const srcPath = enginePath.replace(/\/engine\/?$/, '');
+
+	return `
+import {${bot1ExportName} as __RawBot1} from '${bot1Path}';
+import {${bot2ExportName} as __RawBot2} from '${bot2Path}';
+import {fight, simulate} from '${srcPath}/engine/simulation.ts';
+import {wrapWithParams} from '${srcPath}/engine/params-runtime.ts';
+import {wrapNewBot} from '${srcPath}/hooks/bot-wrapper.ts';
+
+// Auto-detect new-style bots (hooks API) and wrap them for the simulation engine.
+// New-style: uses hooks, returns FinalAction (has _toAction method).
+// Old-style: accepts ({state, config, random}), returns WizardActions directly.
+// We detect by doing a dry-run call — if the result has _toAction, it's new-style.
+//
+// Detection is deferred until the first fight/simulate call so that malicious
+// bots (infinite loops, memory bombs) time out during fight(), not during
+// sandbox creation. __resolveBots memoizes the wrapped functions.
+function __wrap(bot) {
+	if (bot.length > 0) return bot; // Old-style: has parameters
+	// 0-param function could be either style. Try calling it to check return type.
+	try {
+		var result = bot();
+		if (result && typeof result._toAction === 'function') {
+			return wrapNewBot(bot);
+		}
+	} catch(e) {
+		// If it throws (e.g. hooks not initialized), it must be new-style
+		return wrapNewBot(bot);
+	}
+	return bot;
+}
+
+var __Bot1 = null;
+var __Bot2 = null;
+function __resolveBots() {
+	if (__Bot1 === null) __Bot1 = __wrap(__RawBot1);
+	if (__Bot2 === null) __Bot2 = __wrap(__RawBot2);
+}
+
+globalThis.__fight = function __fight(options) {
+	__resolveBots();
+	const result = fight(__Bot1, __Bot2, options);
+	return result;
+};
+
+globalThis.__simulate = function __simulate(options) {
+	__resolveBots();
+	const {params1, params2, ...simOptions} = options;
+	const bot1 = params1 ? wrapWithParams(__Bot1, params1) : __Bot1;
+	const bot2 = params2 ? wrapWithParams(__Bot2, params2) : __Bot2;
+	const result = simulate(bot1, bot2, simOptions);
+	return result;
+};
+`;
+}
+
+/**
+ * Generate the entry point for a Manual Play sandbox bundle.
+ *
+ * Unlike the fight/simulate entry point (which exposes one-shot batch APIs),
+ * the manual-match entry point holds a single long-lived ManualMatch instance
+ * inside the worker and exposes per-tick step/rewind/hijack APIs.
+ *
+ * The "player" wizard is a worker-local stub that returns whatever
+ * `__latestHumanActions` is set to — this avoids the can't-postMessage-functions
+ * problem (the function lives entirely worker-side, only data crosses the
+ * boundary). Hijacked missiles use a similar pattern via
+ * `__latestHumanMissileTargets[projectileId]`.
+ *
+ * @param opponentSourcePath - Absolute path to opponent bot's TypeScript source
+ * @param opponentExportName - Named export of the opponent's WizardFunction
+ * @param engineDir - Absolute path to src/engine/
+ */
+export function generateManualMatchEntryPoint(
+	opponentSourcePath: string,
+	opponentExportName: string,
+	engineDir: string,
+): string
+{
+	const opponentPath = opponentSourcePath.replace(/\\/g, '/');
+	return generateManualMatchEntryPointInner(
+		`import {${opponentExportName} as __RawOpponent} from '${opponentPath}';`,
+		engineDir,
+	);
+}
+
+/**
+ * Browser-friendly variant — the opponent is injected at runtime via
+ * globalThis.__injectedBot1 (set by prepending the player's bot bundle to
+ * the compiled output of this template). Used by the web client for manual
+ * play against uploaded wizards.
+ */
+export function generateBrowserManualMatchEntryPoint(engineDir: string): string
+{
+	const opponentImport = 'var __RawOpponent = globalThis.__injectedBot1;\n'
+		+ 'if (!__RawOpponent) throw new Error("Opponent not injected (set globalThis.__injectedBot1)");';
+	return generateManualMatchEntryPointInner(opponentImport, engineDir);
+}
+
+function generateManualMatchEntryPointInner(opponentImport: string, engineDir: string): string
+{
+	const enginePath = engineDir.replace(/\\/g, '/');
+	const srcPath = enginePath.replace(/\/engine\/?$/, '');
+
+	return `
+${opponentImport}
+import {ManualMatch} from '${srcPath}/engine/manual-match.ts';
+import {wrapNewBot} from '${srcPath}/hooks/bot-wrapper.ts';
+
+// Worker-local state — the player AI and hijacked-missile AIs read from these.
+var __latestHumanActions = {move: {x: 0, y: 0}};
+var __latestHumanMissileTargets = {};
+var __manualMatch = null;
+
+function __wrap(bot) {
+	if (bot.length > 0) return bot;
+	try {
+		var result = bot();
+		if (result && typeof result._toAction === 'function') {
+			return wrapNewBot(bot);
+		}
+	} catch(e) {
+		return wrapNewBot(bot);
+	}
+	return bot;
+}
+
+function __playerStub() {
+	return __latestHumanActions;
+}
+
+function __makeHijackStub(projectileId) {
+	return function(props) {
+		var target = __latestHumanMissileTargets[projectileId];
+		if (!target) return {};
+		return {turnToward: target};
+	};
+}
+
+function __ensureMatch() {
+	if (!__manualMatch) throw new Error('ManualMatch not initialized — call manualMatchInit first');
+	return __manualMatch;
+}
+
+globalThis.__manualMatchInit = function(options) {
+	if (__manualMatch) {
+		__manualMatch.dispose();
+		__manualMatch = null;
+	}
+	__latestHumanActions = (options && options.initialHumanActions) || {move: {x: 0, y: 0}};
+	__latestHumanMissileTargets = {};
+	var opponent = __wrap(__RawOpponent);
+	__manualMatch = new ManualMatch(__playerStub, opponent, options || {});
+	return __manualMatch.getGameState();
+};
+
+globalThis.__manualMatchStep = function(options) {
+	var match = __ensureMatch();
+	if (options) {
+		if (options.humanActions) __latestHumanActions = options.humanActions;
+		if (options.humanMissileTargets) {
+			// Merge — the host may only update specific projectiles per call
+			for (var k in options.humanMissileTargets) {
+				__latestHumanMissileTargets[k] = options.humanMissileTargets[k];
+			}
+		}
+	}
+	var count = (options && options.count) || 1;
+	return match.step(count);
+};
+
+globalThis.__manualMatchHijack = function(options) {
+	var match = __ensureMatch();
+	var id = options && options.projectileId;
+	if (!id) return {ok: false, reason: 'missing projectileId'};
+	match.replaceMissileAI(id, __makeHijackStub(id));
+	return {ok: true};
+};
+
+globalThis.__manualMatchRelease = function(options) {
+	var match = __ensureMatch();
+	var id = options && options.projectileId;
+	if (!id) return {ok: false, reason: 'missing projectileId'};
+	match.restoreMissileAI(id);
+	delete __latestHumanMissileTargets[id];
+	return {ok: true};
+};
+
+globalThis.__manualMatchSetInvincible = function(options) {
+	var match = __ensureMatch();
+	var idx = (options && options.wizardIndex) || 0;
+	var on = !!(options && options.on);
+	match.setInvincible(idx, on);
+	return {ok: true};
+};
+
+globalThis.__manualMatchGetState = function() {
+	var match = __ensureMatch();
+	return match.getGameState();
+};
+
+globalThis.__manualMatchGetResult = function() {
+	var match = __ensureMatch();
+	return match.getResult();
+};
+
+globalThis.__manualMatchDispose = function() {
+	if (__manualMatch) {
+		__manualMatch.dispose();
+		__manualMatch = null;
+	}
+	__latestHumanActions = {move: {x: 0, y: 0}};
+	__latestHumanMissileTargets = {};
+	return {ok: true};
+};
+`;
+}
+
+/**
+ * Generate an alternate entry point where __fight/__simulate accept and return
+ * JSON strings instead of structured objects. Used by the benchmark to compare
+ * JSON serialization vs V8 structured clone performance.
+ */
+export function generateMatchEntryPointJSON(
+	bot1SourcePath: string,
+	bot1ExportName: string,
+	bot2SourcePath: string,
+	bot2ExportName: string,
+	engineDir: string,
+): string
+{
+	const enginePath = engineDir.replace(/\\/g, '/');
+	const bot1Path = bot1SourcePath.replace(/\\/g, '/');
+	const bot2Path = bot2SourcePath.replace(/\\/g, '/');
+	const srcPath = enginePath.replace(/\/engine\/?$/, '');
+
+	return `
+import {${bot1ExportName} as __RawBot1} from '${bot1Path}';
+import {${bot2ExportName} as __RawBot2} from '${bot2Path}';
+import {fight, simulate} from '${srcPath}/engine/simulation.ts';
+import {wrapWithParams} from '${srcPath}/engine/params-runtime.ts';
+import {wrapNewBot} from '${srcPath}/hooks/bot-wrapper.ts';
+
+function __wrap(bot) {
+	if (bot.length > 0) return bot;
+	try {
+		var result = bot();
+		if (result && typeof result._toAction === 'function') {
+			return wrapNewBot(bot);
+		}
+	} catch(e) {
+		return wrapNewBot(bot);
+	}
+	return bot;
+}
+
+// Detection is deferred until the first fight/simulate call so that malicious
+// bots time out during fight(), not during sandbox creation.
+var __Bot1 = null;
+var __Bot2 = null;
+function __resolveBots() {
+	if (__Bot1 === null) __Bot1 = __wrap(__RawBot1);
+	if (__Bot2 === null) __Bot2 = __wrap(__RawBot2);
+}
+
+globalThis.__fightJSON = function __fightJSON(optionsJSON) {
+	__resolveBots();
+	const options = JSON.parse(optionsJSON);
+	const result = fight(__Bot1, __Bot2, options);
+	return JSON.stringify(result);
+};
+
+globalThis.__simulateJSON = function __simulateJSON(optionsJSON) {
+	__resolveBots();
+	const options = JSON.parse(optionsJSON);
+	const {params1, params2, ...simOptions} = options;
+	const bot1 = params1 ? wrapWithParams(__Bot1, params1) : __Bot1;
+	const bot2 = params2 ? wrapWithParams(__Bot2, params2) : __Bot2;
+	const result = simulate(bot1, bot2, simOptions);
+	return JSON.stringify(result);
+};
+`;
+}