@downdraft/cli 0.0.0 → 0.1.0

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);
+}

package/src/usage.ts

@@ -0,0 +1,255 @@
+// ============================================================================
+// usage.ts — per-command usage strings + schema registry
+// ============================================================================
+//
+// Single source of truth for every `draft` subcommand's synopsis, flags, and
+// positionals. `index.ts` generates the top-level help from this registry;
+// each command module imports its schema + usage string for `--help` output.
+//
+
+import type { CommandSchema } from "./args";
+
+export interface CommandEntry {
+  /** Command name as typed on the CLI (e.g. `"new"`). */
+  name: string;
+  /** One-line synopsis shown after `Usage:`. */
+  usage: string;
+  /** Short description for the top-level command list. */
+  summary: string;
+  /** Argument schema (flags + positionals). */
+  schema: CommandSchema;
+}
+
+// ---------------------------------------------------------------------------
+// Desktop target vocabulary (normalized): win | linux | mac | all
+// Mobile target vocabulary: android | ios | all
+// ---------------------------------------------------------------------------
+
+const DESKTOP_TARGETS = ["win", "linux", "mac", "all"] as const;
+const BUILD_TARGETS = ["current", "win", "linux", "mac"] as const;
+const RELEASE_TARGETS = ["win", "linux", "mac", "android", "all"] as const;
+const RELEASE_STAGES = ["build", "package", "release"] as const;
+const RENDERER_TARGETS = ["gpu", "cpu"] as const;
+const BUILD_MODES = ["dev", "debug", "prod"] as const;
+
+// ---------------------------------------------------------------------------
+// Command registry
+// ---------------------------------------------------------------------------
+
+export const COMMANDS: CommandEntry[] = [
+  {
+    name: "release",
+    usage: "draft release [options]",
+    summary: "Native build + package pipeline — compiles the game to a standalone binary via scripts/package-native.mjs",
+    schema: {
+      flags: [
+        { name: "game", alias: "g", type: "string", description: "Game to release (games/<game>). For multiple games, use --games. If omitted, infers from the current directory, or defaults to the only game in games/." },
+        { name: "games", type: "string", description: "Comma-separated game names (e.g. sandjongg,to-the-ocean)" },
+        { name: "target", alias: "t", type: "string", default: "all", enum: [...RELEASE_TARGETS], description: "Target platform(s): win, linux, mac, android, or all (android can't mix with desktop targets)" },
+        { name: "format", type: "string", description: "Deprecated no-op — native packaging produces a single binary + staged tree" },
+        { name: "stage", type: "string", default: "release", enum: [...RELEASE_STAGES], description: "Stage: build, package, or release (all compile the native binary)" },
+        { name: "mode", type: "string", default: "prod", enum: [...BUILD_MODES], description: "Build mode" },
+        { name: "abi", type: "string", default: "arm64-v8a", description: "Android ABI(s): arm64-v8a, x86_64, or all (android target only)" },
+        { name: "min-sdk", type: "string", description: "Android minimum SDK (default 30; android target only)" },
+        { name: "node-flavor", type: "string", description: "Embedded Node build flavor: full (default) or lite — lite drops intl/inspector/sqlite/amaro (android target only)" },
+        { name: "libs", type: "string", description: "Force-include optional engine cdylibs, comma-separated (android target only)" },
+        { name: "exclude-libs", type: "string", description: "Exclude optional engine cdylibs, comma-separated (android target only)" },
+        { name: "no-strip", type: "boolean", description: "Keep debug info/symtab in packaged .so's for native debugging (android target only)" },
+        { name: "out", type: "string", default: "release", description: "Artifact output directory" },
+        { name: "skip-build", type: "boolean", description: "Alias for --stage=package" },
+        { name: "build-only", type: "boolean", description: "Alias for --stage=build" },
+        { name: "mcp", type: "boolean", description: "Retain the MCP automation endpoint in the packaged binary" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "new",
+    usage: "draft new [path] [options]",
+    summary: "Scaffold a new game project",
+    schema: {
+      positionals: [{ name: "path", description: "Target directory (default: current dir)" }],
+      flags: [
+        { name: "template", type: "string", default: "minimal", description: "Project template (minimal | physics | full | gamemodule)" },
+        { name: "name", type: "string", description: "Project name (defaults to directory basename)" },
+        { name: "description", type: "string", description: "Project description" },
+        { name: "author", type: "string", description: "Author name (written as { name } in package.json)" },
+        { name: "version", type: "string", default: "0.1.0", description: "Initial version" },
+        { name: "ai-companion", type: "boolean", description: "Scaffold .devin/ config + engine-prompt.md" },
+        { name: "force", type: "boolean", description: "Scaffold into a non-empty directory" },
+        { name: "list-templates", type: "boolean", description: "List available templates and exit" },
+      ],
+    },
+  },
+  {
+    name: "dev",
+    usage: "draft dev [options]",
+    summary: "Start the game on the native runtime (winit + wgpu; Bun, Node, or Deno host — see --runtime). Run from a game directory (cwd inference).",
+    schema: {
+      flags: [
+        { name: "entry", type: "string", description: "Game entrypoint file (defaults to src/native-entry.ts)" },
+        { name: "port", type: "number", description: "MCP HTTP port (default: auto-assign)" },
+        { name: "runtime", type: "string", enum: ["bun", "node", "deno"], description: "JS runtime hosting the dev shell (default: bun → node → deno auto-detect)" },
+        { name: "watch", type: "boolean", description: "Back-compat no-op — the HMR dev shell always watches" },
+        { name: "no-hmr", type: "boolean", description: "Disable HMR — spawn the entry directly (bun run), no dev shell" },
+        { name: "native", type: "boolean", description: "Back-compat alias — native is the default runtime" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "debug",
+    usage: "draft debug [path] [options]",
+    summary: "Run the engine in debug mode with profiling/visualization",
+    schema: {
+      positionals: [{ name: "path", description: "Project path (default: current dir)" }],
+      flags: [
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+        { name: "no-devtools", type: "boolean", description: "Disable the devtools overlay (sets DOWNDRAFT_DISABLE_DEVTOOLS=1)" },
+        { name: "inspector", type: "boolean", description: "Enable the Node inspector (chrome://inspect)" },
+      ],
+    },
+  },
+  {
+    name: "build",
+    usage: "draft build [path] [options]",
+    summary: "Build a game for a target platform",
+    schema: {
+      positionals: [{ name: "path", description: "Project path (default: current dir)" }],
+      flags: [
+        { name: "game", alias: "g", type: "string", description: "Game to build (resolves games/<game>; overrides path)" },
+        { name: "target", type: "string", default: "current", enum: [...BUILD_TARGETS], description: "Target platform" },
+        { name: "mode", type: "string", default: "prod", enum: [...BUILD_MODES], description: "Build mode" },
+        { name: "out", type: "string", default: "dist", description: "Output directory" },
+        { name: "no-minify", type: "boolean", description: "Disable minification" },
+        { name: "sourcemap", type: "boolean", description: "Generate source maps (on by default in non-prod modes)" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "build-games",
+    usage: "draft build-games --games=<csv> --platforms=<csv>",
+    summary: "Deprecated alias for `draft release --games=<csv>` (VSCode task)",
+    schema: {
+      flags: [
+        { name: "games", type: "string", required: true, description: "Comma-separated game directory names (e.g. sandjongg)" },
+        { name: "platforms", type: "string", required: true, description: "Comma-separated desktop targets (win | linux | mac; legacy :format suffixes are ignored)" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "dist",
+    usage: "draft dist [options]",
+    summary: "Package a game for distribution (deprecated alias for `draft release`)",
+    schema: {
+      flags: [
+        { name: "game", alias: "g", type: "string", required: true, description: "Game to package (games/<game>)" },
+        { name: "target", alias: "t", type: "string", default: "all", enum: [...DESKTOP_TARGETS], description: "Target platform" },
+        { name: "config", alias: "c", type: "string", description: "Explicit path to a build.config.ts / config file" },
+        { name: "project-dir", type: "string", description: "Override the project directory (default: repo root)" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "export",
+    usage: "draft export [path] [options]",
+    summary: "Package a built game for distribution (per-platform launchers)",
+    schema: {
+      positionals: [{ name: "path", description: "Project path (default: current dir)" }],
+      flags: [
+        { name: "target", type: "string", default: "all", enum: [...DESKTOP_TARGETS], description: "Target platform" },
+        { name: "out", type: "string", default: "export", description: "Output directory" },
+        { name: "no-compress", type: "boolean", description: "Disable compression" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "assets",
+    usage: "draft assets <command> [project] [options]",
+    summary: "Manage remote asset packs (pull, push, list, init, add, add-store)",
+    schema: {
+      positionals: [
+        { name: "command", required: true, description: "init | add-store | add | pull | push | list" },
+        { name: "project", description: "Project path (default: current dir)" },
+      ],
+      flags: [
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "mcp",
+    usage: "draft mcp <action> [args] [options]",
+    summary: "Call MCP automation tools on a running game (instances | tools | call | screenshot | stdio | run)",
+    schema: {
+      positionals: [
+        { name: "action", required: true, description: "instances | tools | call | screenshot | stdio | run" },
+        { name: "args", variadic: true, description: "Action args: <tool> [json] | <file.png> | <script> [script-args]" },
+      ],
+      flags: [
+        { name: "app", type: "string", description: "Select instance by appId" },
+        { name: "pid", type: "number", description: "Select instance by PID" },
+        { name: "url", type: "string", description: "Explicit MCP HTTP URL (skips PID-file discovery)" },
+        { name: "token", type: "string", description: "Bearer token (auto-read from <pid>.token otherwise)" },
+        { name: "json", type: "boolean", description: "Print the raw result envelope (image data elided to {bytes} unless --out)" },
+        { name: "out", type: "string", description: "Write image/binary result blocks to file(s)" },
+        { name: "max-bytes", type: "number", description: "Cap printed output in bytes (default 262144)" },
+        { name: "schema", type: "string", description: "tools action: print one tool's inputSchema JSON" },
+        { name: "game", alias: "g", type: "string", description: "run action: game name (games/<name>)" },
+        { name: "entry", type: "string", description: "run action: explicit native entry file" },
+        { name: "headed", type: "boolean", description: "run action: show the game window" },
+        { name: "gpu", type: "string", enum: ["auto", "hardware", "swiftshader"], description: "run action: WebGPU backend (default: swiftshader)" },
+        { name: "deterministic", type: "boolean", description: "run action: DOWNDRAFT_DETERMINISTIC=1 (fixed seed, paused render loop)" },
+        { name: "port", alias: "p", type: "number", description: "run action: pin the MCP port (default: auto)" },
+        { name: "timeout", type: "number", description: "Per-request timeout ms; readiness budget for run" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+  {
+    name: "test",
+    usage: "draft test [options]",
+    summary: "Run e2e tests via bun:test (SwiftShader + deterministic by default; default specs use the in-game MCP RPC harness)",
+    schema: {
+      flags: [
+        { name: "game", alias: "g", type: "string", required: true, description: "Game to test (games/<game>)" },
+        { name: "spec", alias: "s", type: "string", description: "Spec file to run (default: tests/e2e/<game>-smoke.spec.ts)" },
+        { name: "port", alias: "p", type: "number", default: 0, description: "MCP port (0 = auto-assign a free port)" },
+        { name: "renderer", alias: "r", type: "string", default: "cpu", enum: [...RENDERER_TARGETS], description: "WebGPU backend: cpu=SwiftShader, gpu=hardware" },
+        { name: "no-deterministic", type: "boolean", description: "Disable fixed seed / render loop pause" },
+        { name: "headed", type: "boolean", description: "Show the window instead of running headless" },
+        { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
+      ],
+    },
+  },
+];
+
+/** Look up a command entry by name. */
+export function getCommand(name: string): CommandEntry | undefined {
+  return COMMANDS.find((c) => c.name === name);
+}
+
+/** Render the top-level `draft` help string from the registry. */
+export function renderTopLevelHelp(version: string): string {
+  const lines: string[] = [];
+  lines.push(`DownDraft Engine CLI v${version}`);
+  lines.push("");
+  lines.push("Usage: draft <command> [options]");
+  lines.push("");
+  lines.push("Commands:");
+  const maxName = Math.max(...COMMANDS.map((c) => c.name.length));
+  COMMANDS.forEach((c) => {
+    lines.push(`  ${c.name.padEnd(maxName + 2)} ${c.summary}`);
+  });
+  lines.push("");
+  lines.push("Global options:");
+  lines.push("  -h, --help     Show help for a command (draft <cmd> --help)");
+  lines.push("  -V, --version  Print the CLI version and exit");
+  lines.push("");
+  lines.push("Run `draft help <command>` for command-specific details.");
+  return lines.join("\n");
+}

package/templates/_shared/ai-companion/devin-config.eta

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "downdraft": {
+      "command": "bun",
+      "args": ["run", "src/main.ts"],
+      "env": {
+        "DOWNDRAFT_MCP": "1"
+      }
+    }
+  }
+}