@downdraft/cli 0.0.0 → 0.1.0

package/src/build-games.ts

@@ -0,0 +1,45 @@
+// ============================================================================
+// draft build-games — [DEPRECATED] alias for `draft release --games=<csv>`
+// ============================================================================
+//
+// Native packaging produces a single compiled binary per desktop target —
+// the legacy `platform:format` specs collapse to plain targets
+// (win | linux | mac); android/ios hard-error in `release`.
+
+import { createLogger } from "@downdraft/engine";
+import { ArgError, parseArgs as parseArgv, print, renderHelp } from "./args";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+export async function buildGames(argv: string[]): Promise<void> {
+  const entry = getCommand("build-games")!;
+  // Check for --help before parsing (parseArgv validates required flags).
+  if (argv.includes("--help") || argv.includes("-h")) {
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  log.warn("build-games", "`draft build-games` is deprecated — use `draft release --games=<csv> --target=<csv>` instead.");
+  log.warn("build-games", "Delegating to `release`...");
+
+  const parsed = parseArgv(argv, entry.schema);
+  const games = ((parsed.flags.games as string) ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const platforms = ((parsed.flags.platforms as string) ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (games.length === 0 || platforms.length === 0) {
+    throw new ArgError("Usage: draft build-games --games=<g1,g2> --platforms=<p1,p2>");
+  }
+
+  // Legacy specs carry a format suffix (win:portable, linux:AppImage) — native
+  // packaging has a single artifact per platform, so only the target matters.
+  const targets = [...new Set(platforms.map((s) => s.split(":")[0]))];
+
+  const releaseArgs: string[] = [
+    `--games=${games.join(",")}`,
+    `--target=${targets.join(",")}`,
+  ];
+  if (argv.includes("--verbose") || argv.includes("-v")) releaseArgs.push("--verbose");
+
+  const { release } = await import("./release");
+  await release(releaseArgs);
+}

package/src/build.ts

@@ -0,0 +1,40 @@
+// ============================================================================
+// draft build — [DEPRECATED] alias for `draft release --stage=build`
+// ============================================================================
+//
+// The old `draft build` was a naive file-copy; the native pipeline compiles
+// src/native-entry.ts via scripts/package-native.mjs. This module remains as
+// a backward-compat alias that delegates to `release` with a warning.
+
+import { createLogger } from "@downdraft/engine";
+import { parseArgs, print, renderHelp } from "./args";
+import { release } from "./release";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+export async function build(args: string[]): Promise<void> {
+  const entry = getCommand("build")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  log.warn("build", "`draft build` is deprecated — use `draft release --stage=build` instead.");
+  log.warn("build", "Delegating to `release`...");
+
+  // Map old build args → release args.
+  const gameArg = parsed.flags.game as string | undefined;
+  const target = parsed.flags.target as string;
+  const mode = parsed.flags.mode as string;
+
+  // Build the release argv from the old build args.
+  const releaseArgs: string[] = ["--stage=build", `--mode=${mode}`];
+  if (gameArg) releaseArgs.push(`--game=${gameArg}`);
+  // Map build target → release target (skip "current" — release defaults to all desktop).
+  if (target && target !== "current") releaseArgs.push(`--target=${target}`);
+  if (parsed.flags.verbose as boolean) releaseArgs.push("--verbose");
+
+  await release(releaseArgs);
+}

package/src/bun-env.d.ts

@@ -0,0 +1,6 @@
+// The CLI runs under Bun, which extends ImportMeta with `dir`/`path`/`file`.
+// Declared locally rather than pulling in all of bun-types so the CLI stays
+// typecheckable without exposing Bun globals to the rest of the repo.
+interface ImportMeta {
+  readonly dir: string;
+}

package/src/debug.ts

@@ -0,0 +1,56 @@
+import { createLogger } from "@downdraft/engine";
+import { parseArgs, print, renderHelp } from "./args";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+export async function debug(args: string[]): Promise<void> {
+  const entry = getCommand("debug")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  const projectPath = parsed.positionals[0] ?? ".";
+  const verbose = parsed.flags.verbose as boolean;
+  const noDevtools = parsed.flags["no-devtools"] as boolean;
+  const inspector = parsed.flags.inspector as boolean;
+
+  // Wire --no-devtools to the runtime env var so the engine picks it up.
+  if (noDevtools) {
+    process.env.DOWNDRAFT_DISABLE_DEVTOOLS = "1";
+  }
+
+  log.info("debug", `
+  ╔══════════════════════════════════════════╗
+  ║   DownDraft Engine — Debug Mode          ║
+  ╚══════════════════════════════════════════╝
+  `);
+
+  log.info("debug", `  Project:  ${projectPath}`);
+  log.info("debug", `  Mode:     debug`);
+  log.info("debug", `  DevTools: ${noDevtools ? "disabled" : "enabled"}`);
+  log.info("debug", `  Verbose:  ${verbose ? "on" : "off"}`);
+  log.info("debug", `  Inspector: ${inspector ? "on" : "off"}`);
+
+  log.info("debug", "Telemetry enabled:");
+  log.info("debug", "  - Frame time tracking");
+  log.info("debug", "  - CPU/GPU timing");
+  log.info("debug", "  - Memory usage");
+  log.info("debug", "  - System-level profiling");
+
+  log.info("debug", "Debug engine ready. Press Ctrl+C to stop.");
+
+  if (inspector) {
+    log.info("debug", "Inspector mode: attach to the engine process's inspector endpoint.");
+  }
+
+  // Keep process alive
+  await new Promise<void>((resolve) => {
+    process.on("SIGINT", () => {
+      log.info("debug", "Shutting down...");
+      resolve();
+    });
+  });
+}

package/src/dev.ts

@@ -0,0 +1,231 @@
+import { createLogger } from "@downdraft/engine";
+import { spawn } from "child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, print, renderHelp } from "./args";
+import { formatGamesList } from "./list-games";
+import { buildCwd, findMonorepoRoot } from "./paths";
+import { killProcessTree } from "./process-utils";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+const GAME_CONFIG = "downdraft.config.json";
+const NATIVE_ENTRY = "src/native-entry.ts";
+
+/**
+ * Exit code the dev shell uses to request a clean process restart
+ * (Tier-5: dev-shell/loader/config changes, unrecoverable teardown failure).
+ * Duplicated from platform-native's dev-constants.mjs — the CLI cannot import
+ * engine package internals at type-check time in every layout, so keep the
+ * literal in sync.
+ */
+const DD_RESTART_EXIT = 75;
+
+/** Resolve packages/platform-native/src/dev/ — via package resolution first
+ *  (standalone installs), then the monorepo layout. */
+function resolveDevShellDir(): string {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgJson = req.resolve("@downdraft/platform-native/package.json");
+    const dir = join(dirname(pkgJson), "src", "dev");
+    if (existsSync(join(dir, "dev-shell.mjs"))) return dir;
+  } catch { /* fall through to monorepo guess */ }
+  const root = findMonorepoRoot();
+  if (root) return join(root, "packages/platform-native/src/dev");
+  return join(dirname(fileURLToPath(import.meta.url)), "../../platform-native/src/dev");
+}
+
+/**
+ * Resolve the game directory by walking up from `process.cwd()` looking for
+ * `downdraft.config.json`, falling back to `src/native-entry.ts` presence.
+ * This lets games run `draft dev` from their own directory (the scaffolded
+ * `package.json` already sets `"dev": "draft dev"`).
+ *
+ * Returns `{ game, gameDir }` or `null` if no game could be found.
+ */
+function resolveGameDir(): { game: string; gameDir: string } | null {
+  let dir = process.cwd();
+  for (;;) {
+    if (existsSync(resolve(dir, GAME_CONFIG)) || existsSync(resolve(dir, NATIVE_ENTRY))) {
+      return { game: basename(dir), gameDir: dir };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+export async function dev(args: string[]): Promise<void> {
+  const entry = getCommand("dev")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  return devNative(parsed);
+}
+
+/**
+ * Native dev mode — runs the game with winit + wgpu under Bun, Node, or Deno.
+ * Looks for `src/native-entry.ts` in the game directory.
+ */
+async function devNative(parsed: any): Promise<void> {
+  const resolved = resolveGameDir();
+  if (!resolved) {
+    log.error("DownDraft", `No game directory found (looking for downdraft.config.json or src/native-entry.ts from "${process.cwd()}").`);
+    log.error("DownDraft", `Run "draft dev" from a game directory.`);
+    print(formatGamesList(findMonorepoRoot() ?? process.cwd()));
+    process.exit(1);
+  }
+
+  const { game, gameDir } = resolved;
+  const nativeEntry = resolve(gameDir, NATIVE_ENTRY);
+
+  if (!existsSync(nativeEntry)) {
+    log.error("DownDraft", `No native entry point found at "${nativeEntry}".`);
+    log.error("DownDraft", `The game "${game}" needs a src/native-entry.ts to run on the native runtime.`);
+    process.exit(1);
+  }
+
+  const verbose = parsed.flags.verbose as boolean;
+  const noHmr = parsed.flags["no-hmr"] as boolean;
+
+  const env = { ...process.env };
+  const port = parsed.flags.port as number;
+  if (port) env.MCP_PORT = String(port);
+
+  // Signal handling lives outside the respawn loop — each spawn registers
+  // itself as the current child so SIGINT/SIGTERM always hit the live one.
+  let currentChild: import("child_process").ChildProcess | null = null;
+  let shuttingDown = false;
+  const onSignal = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    log.info("DownDraft", "Shutting down...");
+    const child = currentChild;
+    try { child?.kill("SIGINT"); } catch {}
+    if (child?.pid) {
+      try { process.kill(-child.pid, "SIGTERM"); } catch {}
+    }
+    setTimeout(() => {
+      if (child?.pid) {
+        try { process.kill(-child.pid, "SIGKILL"); } catch {}
+        killProcessTree(child.pid);
+      }
+      process.exit(130);
+    }, 2000);
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  process.on("SIGHUP", onSignal);
+
+  // ── Legacy path: --no-hmr spawns the entry directly under Bun (no watcher,
+  //    no ModuleRunner — the pre-HMR behavior, kept as an escape hatch). ──
+  if (noHmr) {
+    log.info("DownDraft", "Starting in native mode — direct spawn, no HMR (--no-hmr)...");
+    log.info("DownDraft", `  Game: ${game}`);
+    log.info("DownDraft", `  Entry: ${nativeEntry}`);
+    const code = await spawnAndForward("bun", ["run", nativeEntry], buildCwd(gameDir), env, {
+      onChild: (c) => { currentChild = c; },
+    });
+    if (!shuttingDown) process.exit(code);
+    return;
+  }
+
+  // ── HMR path: spawn the dev shell under the selected JS runtime. ──
+  const devDir = resolveDevShellDir();
+  const devShell = join(devDir, "dev-shell.mjs");
+  if (!existsSync(devShell)) {
+    log.error("DownDraft", `Dev shell not found at "${devShell}".`);
+    log.error("DownDraft", "Is @downdraft/platform-native installed? Try `draft dev --no-hmr` for the legacy path.");
+    process.exit(1);
+  }
+
+  // Runtime detection is delegated to the dev package (it owns the matrix).
+  const { detectRuntime, spawnArgsFor, findDenoConfig } =
+    await import(resolve(devDir, "runtime-detect.mjs"));
+
+  const requested = (parsed.flags.runtime as string | undefined) ?? process.env.DD_RUNTIME;
+  const runtime = detectRuntime(requested);
+  if (!runtime) {
+    if (requested) {
+      log.error("DownDraft", `Requested runtime "${requested}" is not available on PATH.`);
+    } else {
+      log.error("DownDraft", "No JS runtime found — need one of: bun, node, deno.");
+    }
+    process.exit(1);
+  }
+
+  env.DD_GAME_DIR = gameDir;
+  env.DD_ENTRY = nativeEntry;
+  env.DD_RUNTIME = runtime;
+  env.DD_HMR = "1";
+  env.DOWNDRAFT_DEV = "1";
+  if (verbose) env.DD_VERBOSE = "1";
+  const repoRoot = findMonorepoRoot();
+  if (repoRoot) env.DD_REPO_ROOT = repoRoot;
+
+  const { cmd, args } = spawnArgsFor(runtime, devShell, {
+    configPath: runtime === "deno" ? findDenoConfig(gameDir, repoRoot) : undefined,
+  });
+
+  log.info("DownDraft", `Starting in native mode (${runtime} + SDL + wgpu-native, HMR on)...`);
+  log.info("DownDraft", `  Game: ${game}`);
+  log.info("DownDraft", `  Entry: ${nativeEntry}`);
+  log.info("DownDraft", `  Runtime: ${cmd} ${args.join(" ")}`);
+  if (verbose) log.info("DownDraft", "  Verbose: on");
+
+  // Respawn loop: the dev shell exits with DD_RESTART_EXIT when a changed
+  // file affects the loader/config layer (Tier-5) — respawn in place.
+  for (;;) {
+    const code = await spawnAndForward(cmd, args, buildCwd(gameDir), env, {
+      onChild: (c) => { currentChild = c; },
+    });
+    if (shuttingDown) return; // signal handler already owns exit
+    if (code === DD_RESTART_EXIT) {
+      log.info("DownDraft", "Restarting dev shell (infrastructure change)...");
+      continue;
+    }
+    process.exit(code);
+  }
+}
+
+/** Spawn `cmd args`, forward stdio, resolve the exit code (signal exits are
+ *  mapped to 128+n so the caller's respawn loop can distinguish them). */
+function spawnAndForward(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  opts: { onChild?: (child: import("child_process").ChildProcess) => void } = {},
+): Promise<number> {
+  const child = spawn(cmd, args, {
+    cwd,
+    stdio: ["inherit", "pipe", "pipe"],
+    env,
+    detached: true,
+  });
+  opts.onChild?.(child);
+
+  child.stdout?.on("data", (data: Buffer) => process.stdout.write(data));
+  child.stderr?.on("data", (data: Buffer) => process.stderr.write(data));
+
+  return new Promise<number>((resolvePromise, reject) => {
+    child.on("error", (err) => {
+      log.error("DownDraft", `Failed to spawn ${cmd}: ${err.message}`);
+      reject(err);
+    });
+
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        resolvePromise(128 + (signal === "SIGINT" ? 2 : signal === "SIGTERM" ? 15 : 1));
+        return;
+      }
+      resolvePromise(code ?? 0);
+    });
+  });
+}

package/src/dist.ts

@@ -0,0 +1,36 @@
+// ============================================================================
+// draft dist — [DEPRECATED] alias for `draft release --stage=package`
+// ============================================================================
+//
+// Desktop packaging is native: `draft release` compiles the game's
+// src/native-entry.ts into a standalone Bun binary via the
+// package-native.mjs script shipped in this package. This command delegates
+// to `release` with a deprecation warning.
+
+import { createLogger } from "@downdraft/engine";
+import { parseArgs, print, renderHelp } from "./args";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+export async function dist(args: string[]): Promise<void> {
+  const entry = getCommand("dist")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  log.warn("dist", "`draft dist` is deprecated — use `draft release --stage=package` instead.");
+  log.warn("dist", "Delegating to `release`...");
+
+  const releaseArgs: string[] = ["--stage=package"];
+  const game = parsed.flags.game as string | undefined;
+  const target = parsed.flags.target as string | undefined;
+  if (game) releaseArgs.push(`--game=${game}`);
+  if (target) releaseArgs.push(`--target=${target}`);
+  if (parsed.flags.verbose as boolean) releaseArgs.push("--verbose");
+
+  const { release } = await import("./release");
+  await release(releaseArgs);
+}

package/src/export.ts

@@ -0,0 +1,38 @@
+// ============================================================================
+// draft export — [DEPRECATED] alias for `draft release --stage=package`
+// ============================================================================
+//
+// The old `draft export` copied a Vite `dist/` tree into per-platform
+// launcher folders. Native packaging produces a single compiled binary +
+// staged runtime tree instead — this command delegates to `release`.
+
+import { createLogger } from "@downdraft/engine";
+import { parseArgs, print, renderHelp } from "./args";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+export async function exportGame(args: string[]): Promise<void> {
+  const entry = getCommand("export")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  log.warn("export", "`draft export` is deprecated — use `draft release --stage=package` instead.");
+  log.warn("export", "Delegating to `release`...");
+
+  const releaseArgs: string[] = ["--stage=package"];
+  const target = parsed.flags.target as string | undefined;
+  if (target) releaseArgs.push(`--target=${target}`);
+  if (parsed.flags.verbose as boolean) releaseArgs.push("--verbose");
+
+  const { basename } = await import("node:path");
+  const projectPath = parsed.positionals[0] ?? ".";
+  const gameName = basename(projectPath);
+  if (gameName && gameName !== ".") releaseArgs.push(`--game=${gameName}`);
+
+  const { release } = await import("./release");
+  await release(releaseArgs);
+}

package/src/index.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+import { createLogger } from "@downdraft/engine";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ArgError, print, renderHelp } from "./args";
+import { assets } from "./assets";
+import { build } from "./build";
+import { buildGames } from "./build-games";
+import { debug } from "./debug";
+import { dev } from "./dev";
+import { dist } from "./dist";
+import { exportGame } from "./export";
+import { mcp } from "./mcp";
+import { newProject } from "./new";
+import { pluginCommand } from "./plugin-command";
+import { release } from "./release";
+import { runTest } from "./test";
+import { getCommand, renderTopLevelHelp } from "./usage";
+
+const log = createLogger();
+
+// Read the CLI package version for --version output.
+function getCliVersion(): string {
+  try {
+    const pkgPath = resolve(import.meta.dir, "../package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+const command = process.argv[2];
+
+async function main() {
+  // Global flags handled before command dispatch.
+  if (command === "--version" || command === "-V") {
+    print(`draft ${getCliVersion()}`);
+    return;
+  }
+  if (command === "--help" || command === "-h" || command === undefined) {
+    print(renderTopLevelHelp(getCliVersion()));
+    if (command === undefined) process.exit(1);
+    return;
+  }
+
+  // `help [command]` action.
+  if (command === "help") {
+    const target = process.argv[3];
+    if (!target) {
+      print(renderTopLevelHelp(getCliVersion()));
+      return;
+    }
+    const entry = getCommand(target);
+    if (!entry) {
+      log.error("CLI", `Unknown command: ${target}`);
+      log.info("CLI", `Run 'draft --help' for the list of commands.`);
+      process.exit(1);
+    }
+    print(renderHelp(entry.usage, entry.schema));
+    return;
+  }
+
+  try {
+    switch (command) {
+      case "new":
+        await newProject(process.argv.slice(3));
+        break;
+      case "release":
+        await release(process.argv.slice(3));
+        break;
+      case "dev":
+        await dev(process.argv.slice(3));
+        break;
+      case "debug":
+        await debug(process.argv.slice(3));
+        break;
+      case "build":
+        await build(process.argv.slice(3));
+        break;
+      case "build-games":
+        await buildGames(process.argv.slice(3));
+        break;
+      case "dist":
+        await dist(process.argv.slice(3));
+        break;
+      case "export":
+        await exportGame(process.argv.slice(3));
+        break;
+      case "mobile":
+        log.error("CLI", "`draft mobile` is removed — the Capacitor WebView shell was dormant and has been deleted. Mobile support returns with a native (winit+wgpu) port.");
+        process.exit(1);
+      case "assets":
+        await assets(process.argv.slice(3));
+        break;
+      case "test":
+        await runTest(process.argv.slice(3));
+        break;
+      case "mcp":
+        await mcp(process.argv.slice(3));
+        break;
+      case "plugin":
+        await pluginCommand(process.argv.slice(3));
+        break;
+      case "mod":
+        // `dd mod` is an alias for `dd plugin` but defaults to mod.json format.
+        await pluginCommand(["--mod", ...process.argv.slice(3)]);
+        break;
+      default:
+        print(renderTopLevelHelp(getCliVersion()));
+        process.exit(1);
+    }
+  } catch (err) {
+    if (err instanceof ArgError) {
+      log.error("CLI", err.message);
+      const entry = getCommand(command);
+      if (entry) {
+        print("");
+        print(renderHelp(entry.usage, entry.schema));
+      }
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+main().then(() => {
+  // Explicit exit — the logger may hold open stream handles that keep
+  // the event loop alive after main() returns.
+  process.exit(0);
+});

package/src/list-games.ts

@@ -0,0 +1,37 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { GAME_CONFIG_FILE } from "./paths";
+
+/**
+ * List available game names from the monorepo `games/` directory.
+ * A directory counts as a game if it contains `downdraft.config.json` or
+ * `src/native-entry.ts` (same predicate as `isGameDir` in paths.ts).
+ * Returns an empty array if the `games/` directory doesn't exist.
+ */
+export function listGames(repoRoot: string): string[] {
+  const gamesDir = resolve(repoRoot, "games");
+  if (!existsSync(gamesDir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(gamesDir)) {
+    const dir = resolve(gamesDir, entry);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    if (existsSync(resolve(dir, GAME_CONFIG_FILE)) || existsSync(resolve(dir, "src/native-entry.ts"))) {
+      out.push(entry);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Format the available-games list for an error message.
+ */
+export function formatGamesList(repoRoot: string): string {
+  const games = listGames(repoRoot);
+  if (games.length === 0) return "  (no games found in games/)";
+  return games.map((g) => `  - ${g}`).join("\n");
+}