@downdraft/cli 0.0.0 → 0.1.1

package/src/scaffold-plugin.ts

@@ -0,0 +1,280 @@
+// ============================================================================
+// Plugin scaffold — generates a new plugin directory from a template.
+//
+// Usage: `dd plugin new <name> --format <format> --game <game> [options]`
+//        `dd mod new <name> --game <game> [options]`
+//
+// Generates:
+//   - mod.json (manifest, when --mod is used) or plugin.json (legacy)
+//   - package.json
+//   - src/index.ts (for worker-js/quickjs) or src/index.js (for quickjs)
+//   - README.md
+// ============================================================================
+
+import type { PluginFormat, PluginThread, PluginTier } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+
+const log = createLogger();
+
+export interface PluginScaffoldOptions {
+  /** Plugin id (kebab-case, e.g. "my-cool-plugin"). */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** Plugin format. */
+  format: PluginFormat;
+  /** Target game appId (e.g. "downdraft-overburden"). */
+  game: string;
+  /** Plugin version. */
+  version: string;
+  /** Author. */
+  author?: string;
+  /** Description. */
+  description?: string;
+  /** Target directory (the plugin will be created as a subdirectory). */
+  targetDir: string;
+  /** Overwrite if directory exists. */
+  force: boolean;
+  /** Generate a mod.json (pack format) instead of a legacy plugin.json. */
+  mod?: boolean;
+  /** Mod extension types to include (only with --mod). */
+  extensions?: Array<"assets" | "maps" | "physics" | "shader-postfx" | "shader-material">;
+}
+
+const FORMAT_DEFAULTS: Record<PluginFormat, { tier: PluginTier; thread: PluginThread; permissions: string[] }> = {
+  "worker-js": { tier: "native", thread: "own-worker", permissions: ["ecs", "events", "state", "tick", "log"] },
+  quickjs: { tier: "script", thread: "renderer", permissions: ["events", "state", "tick", "log"] },
+  wasm: { tier: "native", thread: "own-worker", permissions: ["events", "state", "log"] },
+  asset: { tier: "data", thread: "renderer", permissions: [] },
+};
+
+export async function scaffoldPlugin(opts: PluginScaffoldOptions): Promise<void> {
+  const defaults = FORMAT_DEFAULTS[opts.format];
+  const pluginDir = join(resolve(opts.targetDir), opts.id);
+
+  if (existsSync(pluginDir) && !opts.force) {
+    log.error("plugin", `Directory "${pluginDir}" already exists. Use --force to override.`);
+    process.exit(1);
+  }
+
+  mkdirSync(pluginDir, { recursive: true });
+  if (opts.format !== "asset" || (opts.mod && !opts.extensions?.includes("assets"))) {
+    mkdirSync(join(pluginDir, "src"), { recursive: true });
+  }
+
+  // ── Manifest: mod.json or plugin.json ──
+  const manifest: Record<string, unknown> = {
+    id: opts.id,
+    name: opts.name,
+    version: opts.version,
+    author: opts.author ?? "",
+    description: opts.description ?? "",
+    engineVersion: "^0.1.0",
+    game: opts.game,
+    format: opts.format,
+    tier: defaults.tier,
+    thread: defaults.thread,
+    permissions: defaults.permissions,
+    provides: [],
+    requires: [],
+    dependencies: [],
+  };
+
+  if (opts.format !== "asset") {
+    manifest.entry = opts.format === "quickjs" ? "./src/index.js" : "./src/index.ts";
+  } else {
+    manifest.assets = { files: {}, textures: [], audio: [], meshes: [], data: [] };
+  }
+
+  if (opts.format === "quickjs") {
+    manifest.quickjs = { instructionBudget: 500000 };
+  }
+
+  // ── Mod.json extensions ──
+  if (opts.mod) {
+    const extensions: Record<string, unknown> = {};
+    if (opts.extensions?.includes("assets")) {
+      extensions.assets = [];
+      mkdirSync(join(pluginDir, "assets"), { recursive: true });
+    }
+    if (opts.extensions?.includes("maps")) {
+      extensions.maps = [];
+      mkdirSync(join(pluginDir, "maps"), { recursive: true });
+    }
+    if (opts.extensions?.includes("physics")) {
+      extensions.physics = [];
+      mkdirSync(join(pluginDir, "physics"), { recursive: true });
+    }
+    if (opts.extensions?.includes("shader-postfx") || opts.extensions?.includes("shader-material")) {
+      extensions.shaders = {};
+      if (opts.extensions?.includes("shader-postfx")) {
+        (extensions.shaders as Record<string, unknown>).postfx = [];
+        mkdirSync(join(pluginDir, "shaders"), { recursive: true });
+      }
+      if (opts.extensions?.includes("shader-material")) {
+        (extensions.shaders as Record<string, unknown>).materials = [];
+        if (!existsSync(join(pluginDir, "shaders"))) mkdirSync(join(pluginDir, "shaders"), { recursive: true });
+      }
+    }
+    if (Object.keys(extensions).length > 0) manifest.extensions = extensions;
+    // For a mod.json, use `logic` instead of top-level entry/permissions when
+    // the format is code-bearing.
+    if (opts.format !== "asset") {
+      manifest.logic = {
+        format: opts.format,
+        thread: defaults.thread,
+        entry: manifest.entry,
+        permissions: defaults.permissions,
+      };
+    }
+    writeFileSync(join(pluginDir, "mod.json"), JSON.stringify(manifest, null, 2) + "\n");
+  } else {
+    writeFileSync(join(pluginDir, "plugin.json"), JSON.stringify(manifest, null, 2) + "\n");
+  }
+
+  // ── package.json ──
+  const pkgName = `@${opts.game.replace(/^downdraft-/, "")}/plugin-${opts.id}`;
+  const pkg = {
+    name: pkgName,
+    version: opts.version,
+    description: opts.description ?? `${opts.name} plugin`,
+    author: opts.author ?? "",
+    private: true,
+    type: "module",
+    dependencies: { "@downdraft/engine": "workspace:*" },
+  };
+  writeFileSync(join(pluginDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  // ── Entry file ──
+  if (opts.format === "worker-js") {
+    writeFileSync(join(pluginDir, "src/index.ts"), WORKER_JS_TEMPLATE(opts));
+  } else if (opts.format === "quickjs") {
+    writeFileSync(join(pluginDir, "src/index.js"), QUICKJS_TEMPLATE(opts));
+  } else if (opts.format === "wasm") {
+    writeFileSync(join(pluginDir, "src/plugin.wat"), WAT_TEMPLATE(opts));
+  } else if (opts.format === "asset") {
+    mkdirSync(join(pluginDir, "assets"), { recursive: true });
+    writeFileSync(join(pluginDir, "assets/README.md"), "# Assets\nPlace your plugin assets here.\n");
+  }
+
+  // ── README.md ──
+  writeFileSync(join(pluginDir, "README.md"), README_TEMPLATE(opts));
+
+  log.info("plugin", `
+  ╔══════════════════════════════════════════╗
+  ║   DownDraft Engine — Plugin Scaffold     ║
+  ╚══════════════════════════════════════════╝
+  `);
+  log.info("plugin", `  Plugin:    ${opts.id}`);
+  log.info("plugin", `  Format:    ${opts.format}`);
+  log.info("plugin", `  Tier:      ${defaults.tier}`);
+  log.info("plugin", `  Thread:    ${defaults.thread}`);
+  log.info("plugin", `  Game:      ${opts.game}`);
+  log.info("plugin", `  Manifest:  ${opts.mod ? "mod.json" : "plugin.json"}`);
+  if (opts.mod && opts.extensions?.length) {
+    log.info("plugin", `  Extensions: ${opts.extensions.join(", ")}`);
+  }
+  log.info("plugin", `  Target:    ${pluginDir}`);
+  log.info("plugin", "");
+  log.info("plugin", `Next steps:`);
+  log.info("plugin", `  1. Edit ${opts.mod ? "mod.json" : "plugin.json"} to declare provides/requires/permissions`);
+  log.info("plugin", `  2. Implement the plugin entry in src/`);
+  log.info("plugin", `  3. Add the plugin to your game's GameModule.plugins config`);
+}
+
+function WORKER_JS_TEMPLATE(opts: PluginScaffoldOptions): string {
+  return `import type { NativePluginContext, PluginEntry } from "@downdraft/engine";
+
+const plugin: PluginEntry<NativePluginContext> = {
+  register(ctx: NativePluginContext) {
+    ctx.log.info("${opts.id} plugin registered.");
+    ctx.onDispose(() => {
+      ctx.log.debug("${opts.id} plugin unloading.");
+    });
+  },
+};
+
+export default plugin;
+`;
+}
+
+function QUICKJS_TEMPLATE(opts: PluginScaffoldOptions): string {
+  return `function register(dd) {
+  dd.log.info("${opts.id} plugin registered.");
+
+  dd.onDispose(function() {
+    dd.log.debug("${opts.id} plugin unloading.");
+  });
+}
+`;
+}
+
+function WAT_TEMPLATE(opts: PluginScaffoldOptions): string {
+  return `;; ${opts.id} — WASM plugin (ABI v3)
+;; v3 adds host-call imports (spawn_prop, set_physics, apply_impulse, etc.)
+;; and the on_host_call_result export. v2 imports (log/state/events) are unchanged.
+(module
+  (memory (export "memory") 1)
+  (global $heap (mut i32) (i32.const 1024))
+
+  (func (export "alloc") (param $size i32) (result i32)
+    (local $ptr i32)
+    (local.set $ptr (global.get $heap))
+    (global.set $heap (i32.add (global.get $heap) (local.get $size)))
+    (local.get $ptr)
+  )
+
+  (func (export "register")
+    ;; Initialize plugin state
+  )
+
+  (func (export "tick") (param $dt f32) (param $elapsed f32)
+    ;; Per-tick logic
+  )
+
+  (func (export "dispose")
+    ;; Cleanup
+  )
+
+  (func (export "on_event") (param $sub_id i32) (param $data_ptr i32) (param $data_len i32)
+    ;; Handle events
+  )
+
+  ;; v3: Called when a host-call completes. request_id matches the id returned
+  ;; by the host-call import. result_ptr/len point to a JSON result string
+  ;; (or 0,0 for void). error_ptr/len point to an error string (or 0,0 on success).
+  (func (export "on_host_call_result")
+    (param $req i32) (param $rptr i32) (param $rlen i32) (param $eptr i32) (param $elen i32)
+    ;; Handle host-call results
+  )
+)
+`;
+}
+
+function README_TEMPLATE(opts: PluginScaffoldOptions): string {
+  const manifestFile = opts.mod ? "mod.json" : "plugin.json";
+  const extList = opts.mod && opts.extensions?.length
+    ? `\n- **Extensions:** ${opts.extensions.join(", ")}`
+    : "";
+  return `# ${opts.name}
+
+${opts.description ?? "A user-authored plugin for the Downdraft Engine."}
+
+- **Format:** \`${opts.format}\`
+- **Tier:** \`${FORMAT_DEFAULTS[opts.format].tier}\`
+- **Thread:** \`${FORMAT_DEFAULTS[opts.format].thread}\`
+- **Game:** \`${opts.game}\`${extList}
+
+## Getting started
+
+1. Edit \`${manifestFile}\` to declare your \`provides\`, \`requires\`, and \`permissions\`.
+2. Implement the plugin entry in \`src/\`.
+3. Add the plugin to your game's \`GameModule.plugins\` config.
+
+## Built with
+
+Generated by \`dd ${opts.mod ? "mod" : "plugin"} new\` — the Downdraft Engine CLI scaffold.
+`;
+}

package/src/scaffold.ts

@@ -0,0 +1,207 @@
+import { confinePath, createLogger } from "@downdraft/engine";
+import { Eta } from "eta";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { basename, dirname, join, relative, resolve } from "path";
+
+const log = createLogger();
+
+const TEMPLATES_DIR = resolve(import.meta.dir, "../templates");
+
+export interface ScaffoldOptions {
+  template: string;
+  name: string;
+  description?: string;
+  author?: string;
+  version: string;
+  aiCompanion: boolean;
+  force: boolean;
+}
+
+export function listTemplates(): string[] {
+  if (!existsSync(TEMPLATES_DIR)) return [];
+  const entries = readdirSync(TEMPLATES_DIR);
+  const templates: string[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.startsWith("_")) continue;
+    const fullPath = join(TEMPLATES_DIR, entry);
+    if (statSync(fullPath).isDirectory()) {
+      templates.push(entry);
+    }
+  }
+  return templates;
+}
+
+function createEtaInstance(templateDir: string): Eta {
+  const eta = new Eta({
+    views: templateDir,
+    autoEscape: false,
+    useWith: true,
+    functionHeader: `
+      const kebabCase = (s) => s.replace(/([a-z])([A-Z])/g, '$1-$2').replace(/\\s+/g, '-').toLowerCase();
+      const pascalCase = (s) => s.replace(/(^|[-\\s])(.)/g, (_, __, c) => c.toUpperCase());
+      const camelCase = (s) => { const p = pascalCase(s); return p.charAt(0).toLowerCase() + p.slice(1); };
+      const titleCase = (s) => s.replace(/(^|[-\\s])(.)/g, (_, __, c) => ' ' + c.toUpperCase()).trim();
+    `,
+  });
+  return eta;
+}
+
+export async function scaffold(targetPath: string, opts: ScaffoldOptions): Promise<void> {
+  // Validate template name to prevent path traversal via the template parameter.
+  // Template names must be relative, non-traversing identifiers confined to the templates dir.
+  confinePath(TEMPLATES_DIR, opts.template);
+
+  const templateDir = join(TEMPLATES_DIR, opts.template);
+  if (!existsSync(templateDir)) {
+    log.error("scaffold", `Template "${opts.template}" not found at ${templateDir}`);
+    log.info("scaffold", `Available templates: ${listTemplates().join(", ")}`);
+    process.exit(1);
+  }
+
+  // Validate the target path to prevent path traversal outside the current working directory.
+  const absTarget = confinePath(process.cwd(), targetPath);
+
+  if (existsSync(absTarget)) {
+    const entries = readdirSync(absTarget);
+    if (entries.length > 0 && !opts.force) {
+      log.error("scaffold", `Target directory "${absTarget}" is not empty. Use --force to override.`);
+      process.exit(1);
+    }
+  }
+
+  mkdirSync(absTarget, { recursive: true });
+
+  const eta = createEtaInstance(TEMPLATES_DIR);
+
+  const templateData = {
+    name: opts.name,
+    description: opts.description,
+    author: opts.author,
+    version: opts.version,
+    aiCompanion: opts.aiCompanion,
+    template: opts.template,
+    plugins: getPluginsForTemplate(opts.template),
+  };
+
+  log.info("scaffold", `  Template:  ${opts.template}`);
+  log.info("scaffold", `  Name:       ${opts.name}`);
+  log.info("scaffold", `  Version:    ${opts.version}`);
+  if (opts.description) log.info("scaffold", `  Description: ${opts.description}`);
+  if (opts.author) log.info("scaffold", `  Author:     ${opts.author}`);
+  log.info("scaffold", `  AI Companion: ${opts.aiCompanion ? "yes" : "no"}`);
+  log.info("scaffold", `  Target:     ${absTarget}`);
+
+  const files = collectTemplateFiles(templateDir);
+  let createdCount = 0;
+
+  for (let i = 0; i < files.length; i++) {
+    const relPath = files[i];
+    const srcFile = join(templateDir, relPath);
+    const srcBasename = basename(relPath);
+    if (srcBasename === ".eta") {
+      const dirPath = join(absTarget, dirname(relPath));
+      mkdirSync(dirPath, { recursive: true });
+      continue;
+    }
+
+    const destRel = relPath.replace(/\.eta$/, "");
+    const destFile = join(absTarget, destRel);
+
+    mkdirSync(dirname(destFile), { recursive: true });
+
+    const content = readFileSync(srcFile, "utf-8");
+
+    let rendered: string;
+    try {
+      rendered = await eta.renderStringAsync(content, templateData);
+    } catch (err) {
+      log.error("scaffold", `Failed to render template: ${relPath}`);
+      throw err;
+    }
+
+    writeFileSync(destFile, rendered);
+    createdCount++;
+  }
+
+  if (opts.aiCompanion) {
+    const aiCompanionDir = join(TEMPLATES_DIR, "_shared", "ai-companion");
+    if (existsSync(aiCompanionDir)) {
+      const aiFiles = collectTemplateFiles(aiCompanionDir);
+      for (let i = 0; i < aiFiles.length; i++) {
+        const relPath = aiFiles[i];
+        const srcFile = join(aiCompanionDir, relPath);
+        const content = readFileSync(srcFile, "utf-8");
+
+        let rendered: string;
+        try {
+          rendered = await eta.renderStringAsync(content, templateData);
+        } catch (err) {
+          log.error("scaffold", `Failed to render AI companion template: ${relPath}`);
+          throw err;
+        }
+
+        const destMap: Record<string, string> = {
+          "devin-config.eta": ".devin/config.json",
+          "logging-rule.eta": ".devin/rules/logging.md",
+          "loops-rule.eta": ".devin/rules/loops.md",
+          "engine-prompt.eta": "engine-prompt.md",
+        };
+
+        const baseName = basename(relPath);
+        const destRel = destMap[baseName];
+        if (!destRel) continue;
+
+        const destFile = join(absTarget, destRel);
+        mkdirSync(dirname(destFile), { recursive: true });
+        writeFileSync(destFile, rendered);
+        createdCount++;
+      }
+    }
+  }
+
+  log.info("scaffold", `Created ${createdCount} files`);
+  log.info("scaffold", `Project scaffolded at: ${absTarget}`);
+  log.info("scaffold", ``);
+  log.info("scaffold", `Next steps:`);
+  log.info("scaffold", `  cd ${relative(process.cwd(), absTarget) || "."}`);
+  log.info("scaffold", `  bun install`);
+  log.info("scaffold", `  draft dev`);
+}
+
+function collectTemplateFiles(dir: string, base: string = dir): string[] {
+  const results: string[] = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir);
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      results.push(...collectTemplateFiles(fullPath, base));
+    } else {
+      const rel = relative(base, fullPath);
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+function getPluginsForTemplate(template: string): string[] {
+  switch (template) {
+    case "minimal":
+      return [];
+    case "physics":
+      return ["physics-rapier"];
+    case "full":
+      return ["physics-rapier", "water", "marching-cubes", "models", "devtools"];
+    case "gamemodule":
+      // GameModule-based scaffold — uses the declarative startGame() API.
+      // No plugins pre-wired; the developer adds EngineLibrary descriptors
+      // and feature plugins in their GameModule.
+      return [];
+    default:
+      return [];
+  }
+}

package/src/test.ts

@@ -0,0 +1,187 @@
+import { createLogger } from "@downdraft/engine";
+import { spawn } from "child_process";
+import { existsSync } from "node:fs";
+import { createServer } from "node:net";
+import { basename, resolve } from "node:path";
+import { parseArgs, print, renderHelp } from "./args";
+import { findMonorepoRoot, resolveGameDir } from "./paths";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+type Renderer = "gpu" | "cpu";
+
+/** Grab an OS-assigned free TCP port so e2e runs don't collide with a
+ *  running dev instance on the old pinned port (9976). */
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      srv.close(() => (port ? resolve(port) : reject(new Error("no port assigned"))));
+    });
+    srv.on("error", reject);
+  });
+}
+
+interface TestArgs {
+  game: string;
+  mcpPort: number;
+  spec: string | null;
+  renderer: Renderer;
+  deterministic: boolean;
+  headed: boolean;
+  verbose: boolean;
+}
+
+function parseTestArgs(args: string[]): TestArgs {
+  const entry = getCommand("test")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    process.exit(0);
+  }
+  const port = parsed.flags.port as number;
+  return {
+    game: parsed.flags.game as string,
+    mcpPort: port,
+    spec: (parsed.flags.spec as string) || null,
+    renderer: parsed.flags.renderer as Renderer,
+    deterministic: !(parsed.flags["no-deterministic"] as boolean),
+    headed: parsed.flags.headed as boolean,
+    verbose: parsed.flags.verbose as boolean,
+  };
+}
+
+/**
+ * Check whether xvfb-run is available on the system.
+ */
+function hasXvfb(): boolean {
+  try {
+    return existsSync("/usr/bin/xvfb-run") || existsSync("/usr/local/bin/xvfb-run");
+  } catch {
+    return false;
+  }
+}
+
+
+
+export async function runTest(args: string[]): Promise<void> {
+  const opts = parseTestArgs(args);
+  const monorepoRoot = findMonorepoRoot();
+  const gameDir = resolveGameDir(opts.game || undefined);
+
+  if (!opts.game && gameDir) {
+    opts.game = basename(gameDir);
+  }
+  if (!opts.game) {
+    log.error("test", `No game specified and none could be inferred from "${process.cwd()}".`);
+    log.error("test", `Run "draft test --game=<name>" or pass --spec=<path>.`);
+    process.exit(1);
+  }
+
+  // Default spec: <monorepo>/tests/e2e/<game>-smoke.spec.ts, or the standalone
+  // game's own tests/e2e dir. When neither exists, require --spec.
+  let specPath = opts.spec ? resolve(opts.spec) : null;
+  if (!specPath) {
+    const candidates = [
+      monorepoRoot ? resolve(monorepoRoot, "tests", "e2e", `${opts.game}-smoke.spec.ts`) : null,
+      gameDir ? resolve(gameDir, "tests", "e2e", `${opts.game}-smoke.spec.ts`) : null,
+    ].filter((p): p is string => !!p);
+    specPath = candidates.find((p) => existsSync(p)) ?? candidates[0];
+  }
+  if (!specPath || !existsSync(specPath)) {
+    log.error("test", `No test spec found for game "${opts.game}".`);
+    log.error("test", `Looked in: tests/e2e/${opts.game}-smoke.spec.ts`);
+    log.error("test", `Pass --spec=<path> to specify a spec file.`);
+    process.exit(1);
+  }
+
+  if (!opts.mcpPort) {
+    opts.mcpPort = await findFreePort();
+  }
+
+  log.info("test", `
+  ╔══════════════════════════════════════════╗
+  ║   DownDraft Engine — E2E Test Runner     ║
+  ╚══════════════════════════════════════════╝
+  `);
+
+  log.info("test", `  Game:          ${opts.game}`);
+  log.info("test", `  Spec:          ${specPath}`);
+  log.info("test", `  MCP port:      ${opts.mcpPort}`);
+  log.info("test", `  Renderer:      ${opts.renderer === "cpu" ? "SwiftShader (software)" : "hardware GPU"}`);
+  log.info("test", `  Deterministic: ${opts.deterministic}`);
+  log.info("test", `  Headed:        ${opts.headed}`);
+  if (opts.verbose) log.info("test", `  Verbose:       on`);
+  log.info("test", "");
+
+  const env: Record<string, string> = {
+    ...process.env,
+    MCP_PORT: String(opts.mcpPort),
+    MCP_TIMEOUT_MS: "120000",
+  };
+
+  if (opts.renderer === "cpu") {
+    env.DOWNDRAFT_GPU = "swiftshader";
+  } else {
+    env.DOWNDRAFT_GPU = "hardware";
+  }
+  if (opts.deterministic) {
+    env.DOWNDRAFT_DETERMINISTIC = "1";
+  }
+  if (opts.headed) {
+    // Show the window instead of running headless.
+    env.DOWNDRAFT_HEADED = "1";
+  }
+
+  // If no display is available, wrap in xvfb-run (common in CI).
+  let cmd = "bun";
+  let cmdArgs = ["test", specPath];
+  const noDisplay = !env.DISPLAY;
+  if (noDisplay && hasXvfb()) {
+    log.info("test", "No DISPLAY detected — wrapping in xvfb-run");
+    cmd = "xvfb-run";
+    cmdArgs = ["-a", "--", "bun", "test", specPath];
+  } else if (noDisplay) {
+    log.warn("test", "No DISPLAY and xvfb-run not found — the native window may fail to start.");
+    log.warn("test", "Install xvfb with: sudo apt install xvfb");
+  }
+
+  const child = spawn(cmd, cmdArgs, {
+    cwd: monorepoRoot ?? gameDir ?? process.cwd(),
+    stdio: "inherit",
+    env,
+  });
+
+  const shutdown = () => {
+    try { child.kill("SIGINT"); } catch {}
+    setTimeout(() => {
+      try { process.kill(-child.pid!, "SIGKILL"); } catch {}
+      process.exit(130);
+    }, 2000);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // Await the child process so `draft test` blocks until the spec (and the
+  // spawned game) fully finishes + cleans up. Without this, the async
+  // function resolves immediately after spawning while the game is still
+  // booting, and the next sequential e2e run starts concurrently — colliding
+  // on the MCP port.
+  const exitCode = await new Promise<number>((resolve) => {
+    child.on("exit", (code) => resolve(code ?? 1));
+    child.on("error", (err) => {
+      log.error("test", `Failed to spawn test process: ${err.message}`);
+      resolve(1);
+    });
+  });
+
+  if (exitCode === 0) {
+    log.info("test", "All tests passed.");
+  } else {
+    log.error("test", `Tests failed with exit code ${exitCode}.`);
+  }
+  process.exit(exitCode);
+}