@downdraft/cli 0.0.0 → 0.1.0

package/src/release.ts

@@ -0,0 +1,374 @@
+// ============================================================================
+// draft release — native build + package pipeline
+// ============================================================================
+//
+// Replaces the separate `build`, `dist`, `export`, `mobile`, and
+// `build-games` commands with a single pipeline:
+//
+//   draft release [--game=<name>] [--target=<csv>]
+//                 (auto-detects the game from cwd or games/ when --game is omitted)
+//                 [--stage=<build|package|release>] [--games=<csv>]
+//                 [--mode=<dev|debug|prod>] [--out=<dir>]
+//                 [--mcp] [--verbose]
+//
+// Stages (all stages produce the same artifact — a compiled Bun binary plus
+// the staged native/ + dd-assets/ tree — via scripts/package-native.mjs):
+//   build   = compile only
+//   package = package an existing build (for native: same compile step)
+//   release = build + package + collect to release/  (default)
+//
+// Targets: win | linux | mac | all
+//
+// The old commands remain as backward-compat aliases that delegate here with
+// a deprecation warning.
+//
+
+import { createLogger } from "@downdraft/engine";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, print, renderHelp } from "./args";
+import { formatGamesList, listGames } from "./list-games";
+import { findGameDirUpward, findMonorepoRoot, resolveGameDir } from "./paths";
+import { getCommand } from "./usage";
+
+const log = createLogger();
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type Stage = "build" | "package" | "release";
+
+interface ReleaseArgs {
+  game: string | null;
+  games: string[];
+  target: string;
+  stage: Stage;
+  mode: string;
+  abi: string;
+  minSdk: string | null;
+  nodeFlavor: string | null;
+  libs: string | null;
+  excludeLibs: string | null;
+  noStrip: boolean;
+  out: string;
+  retainMcp: boolean;
+  verbose: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+function parseReleaseArgs(args: string[]): ReleaseArgs {
+  const entry = getCommand("release")!;
+  const parsed = parseArgs(args, entry.schema);
+  if (parsed.help) {
+    print(renderHelp(entry.usage, entry.schema));
+    process.exit(0);
+  }
+
+  const game = (parsed.flags.game as string) || null;
+  const gamesFlag = (parsed.flags.games as string) || "";
+  const games = gamesFlag
+    ? gamesFlag.split(",").map((s) => s.trim()).filter(Boolean)
+    : game ? [game] : [];
+
+  const stageFlag = (parsed.flags.stage as string) || "release";
+  // --skip-build and --build-only are convenience aliases for --stage.
+  const skipBuild = parsed.flags["skip-build"] as boolean;
+  const buildOnly = parsed.flags["build-only"] as boolean;
+  let stage: Stage = stageFlag as Stage;
+  if (buildOnly) stage = "build";
+  else if (skipBuild) stage = "package";
+
+  if (parsed.flags.format) {
+    log.warn("release", "--format is gone — native packaging produces a single binary + staged tree.");
+  }
+
+  return {
+    game,
+    games,
+    target: parsed.flags.target as string,
+    stage,
+    mode: (parsed.flags.mode as string) || "prod",
+    abi: (parsed.flags.abi as string) || "arm64-v8a",
+    minSdk: (parsed.flags["min-sdk"] as string) || null,
+    nodeFlavor: (parsed.flags["node-flavor"] as string) || null,
+    libs: (parsed.flags.libs as string) || null,
+    excludeLibs: (parsed.flags["exclude-libs"] as string) || null,
+    noStrip: parsed.flags["no-strip"] as boolean,
+    out: (parsed.flags.out as string) || "release",
+    retainMcp: parsed.flags.mcp as boolean,
+    verbose: parsed.flags.verbose as boolean,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Game resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the game(s) to release when neither --game nor --games is given.
+ *
+ * Resolution order:
+ *  1. Explicit flags (--game / --games) — handled by the caller before this.
+ *  2. cwd inference — walk up from `process.cwd()` looking for
+ *     `downdraft.config.json` or `src/native-entry.ts`. Lets games run
+ *     `draft release` from their own directory (the scaffolded
+ *     `package.json` sets `"release": "draft release"`).
+ *  3. Single-game fallback — if `games/` contains exactly one game, use it.
+ *
+ * Returns the detected game name, or `null` if none could be determined.
+ */
+function detectGame(monorepoRoot: string | null): string | null {
+  // 2. Cwd inference: walk up looking for the game-dir markers.
+  const upward = findGameDirUpward();
+  if (upward) return basename(upward);
+
+  // 3. Single-game fallback (monorepo only).
+  if (monorepoRoot) {
+    const games = listGames(monorepoRoot);
+    if (games.length === 1) {
+      log.info("release", `No game specified — defaulting to the only game found: ${games[0]}`);
+      return games[0];
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Target classification
+// ---------------------------------------------------------------------------
+
+const DESKTOP_TARGETS = new Set(["win", "linux", "mac"]);
+const MOBILE_TARGETS = new Set(["android"]);
+
+function classifyTargets(target: string): string[] {
+  if (target === "all") {
+    return ["win", "linux", "mac"];
+  }
+  const parts = target.split(",").map((s) => s.trim()).filter(Boolean);
+  parts.forEach((t) => {
+    if (t === "ios") {
+      log.error("release", `iOS is not implemented yet — the native mobile port currently supports android only.`);
+      process.exit(1);
+    }
+    if (!DESKTOP_TARGETS.has(t) && !MOBILE_TARGETS.has(t)) {
+      log.error("release", `Unknown target: ${t}. Use win, linux, mac, android, or all.`);
+      process.exit(1);
+    }
+  });
+  if (parts.some((t) => MOBILE_TARGETS.has(t)) && parts.some((t) => DESKTOP_TARGETS.has(t))) {
+    log.error("release", `Can't mix mobile and desktop targets in one release — run android separately.`);
+    process.exit(1);
+  }
+  return parts;
+}
+
+// ---------------------------------------------------------------------------
+// Game info resolution
+// ---------------------------------------------------------------------------
+
+function getGameInfo(gameDir: string, game: string): { productName: string; appId: string; version: string } {
+  const pkgPath = resolve(gameDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { productName: game, appId: `com.downdraft.${game}`, version: "0.0.0" };
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const productName = pkg.productName ?? pkg.build?.productName ??
+      String(pkg.name ?? game).replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+    const appId = pkg.build?.appId ?? `com.downdraft.${game}`;
+    const version = pkg.version ?? "0.0.0";
+    return { productName, appId, version };
+  } catch {
+    return { productName: game, appId: `com.downdraft.${game}`, version: "0.0.0" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Native packaging — scripts/package-native.mjs
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile the game's native entry into a standalone Bun binary plus the
+ * staged runtime tree (<out>/<game>-<target> + sibling native/ + dd-assets/).
+ * One compile covers both the build and package stages — the binary IS the
+ * artifact.
+ */
+function packageNative(
+  game: string,
+  gameDir: string,
+  targets: string[],
+  opts: ReleaseArgs,
+  info: { productName: string; appId: string; version: string },
+): boolean {
+  const entry = resolve(gameDir, "src/native-entry.ts");
+  if (!existsSync(entry)) {
+    log.error("release:package", `No src/native-entry.ts in ${gameDir} — the game has no native entry.`);
+    return false;
+  }
+  // The packaging script ships inside @downdraft/cli (files: ["scripts"]) so
+  // standalone game repos resolve it through the installed package, not the
+  // engine monorepo.
+  const script = fileURLToPath(new URL("../scripts/package-native.mjs", import.meta.url));
+  // cwd is the relativization root for staged assets — the monorepo root
+  // when present (engine sources relativize cleanly), else the game dir.
+  const cwd = findMonorepoRoot(gameDir) ?? gameDir;
+  let ok = true;
+  targets.forEach((target) => {
+    const outfile = resolve(opts.out, `${game}-${target}`);
+    const argv = [
+      script,
+      `--target=${target}`,
+      `--mode=${opts.mode}`,
+      `--product-name=${info.productName}`,
+      `--product-version=${info.version}`,
+      ...(opts.retainMcp ? ["--mcp"] : []),
+      entry,
+      outfile,
+    ];
+    log.info("release:package", `bun ${argv.map((a) => basename(a)).join(" ")}`);
+    const result = spawnSync("bun", argv, {
+      cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+    if (result.status !== 0) {
+      log.error("release:package", `Native packaging failed for ${game} (${target})`);
+      ok = false;
+    }
+  });
+  return ok;
+}
+
+// ---------------------------------------------------------------------------
+// Android packaging — scripts/package-mobile.mjs
+// ---------------------------------------------------------------------------
+
+/**
+ * Bundle the game + native libs + embedded libnode into an APK. Single
+ * target ("android") produces lib/<abi>/ entries for --abi (default
+ * arm64-v8a). Unlike the desktop path the artifact is the APK itself.
+ */
+function packageAndroid(
+  game: string,
+  gameDir: string,
+  opts: ReleaseArgs,
+  info: { productName: string; appId: string; version: string },
+): boolean {
+  const entry = resolve(gameDir, "src/native-entry.ts");
+  if (!existsSync(entry)) {
+    log.error("release:package", `No src/native-entry.ts in ${gameDir} — the game has no native entry.`);
+    return false;
+  }
+  const script = fileURLToPath(new URL("../scripts/package-mobile.mjs", import.meta.url));
+  const cwd = findMonorepoRoot(gameDir) ?? gameDir;
+  const outfile = resolve(opts.out, `${game}-android.apk`);
+  const argv = [
+    script,
+    `--mode=${opts.mode}`,
+    `--abi=${opts.abi}`,
+    `--app-id=${info.appId}`,
+    `--app-name=${info.productName}`,
+    `--version=${info.version}`,
+    ...(opts.minSdk ? [`--min-sdk=${opts.minSdk}`] : []),
+    ...(opts.nodeFlavor ? [`--node-flavor=${opts.nodeFlavor}`] : []),
+    ...(opts.libs ? [`--libs=${opts.libs}`] : []),
+    ...(opts.excludeLibs ? [`--exclude-libs=${opts.excludeLibs}`] : []),
+    ...(opts.noStrip ? ["--no-strip"] : []),
+    ...(opts.retainMcp ? ["--mcp"] : []),
+    entry,
+    outfile,
+  ];
+  log.info("release:package", `bun ${argv.map((a) => basename(a)).join(" ")}`);
+  const result = spawnSync("bun", argv, { cwd, stdio: "inherit", env: process.env });
+  if (result.status !== 0) {
+    log.error("release:package", `Android packaging failed for ${game}`);
+    return false;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function release(args: string[]): Promise<void> {
+  const opts = parseReleaseArgs(args);
+  // Monorepo root when running inside the engine repo; null for standalone
+  // game repos (the game directory itself is the project root).
+  const monorepoRoot = findMonorepoRoot();
+
+  // Auto-detect the game when neither --game nor --games is given.
+  let games = opts.games;
+  if (games.length === 0) {
+    const detected = detectGame(monorepoRoot);
+    if (detected) {
+      games = [detected];
+      opts.game = detected;
+    } else {
+      log.error("release", "No game specified and none could be auto-detected.");
+      log.error("release", "Run \"draft release\" from a game directory, or use \"--game <name>\" / \"--games <csv>\" from the engine root.");
+      log.error("release", "Available games:");
+      print(formatGamesList(monorepoRoot ?? process.cwd()));
+      process.exit(1);
+    }
+  }
+
+  const targets = classifyTargets(opts.target);
+
+  log.info("release", `
+  ╔══════════════════════════════════════════╗
+  ║   DownDraft Engine — Release             ║
+  ╚══════════════════════════════════════════╝
+  `);
+
+  log.info("release", `  Game(s):     ${games.join(", ")}`);
+  log.info("release", `  Target:      ${opts.target}`);
+  log.info("release", `  Stage:       ${opts.stage}`);
+  log.info("release", `  Mode:        ${opts.mode}`);
+  log.info("release", `  Output:      ${opts.out}`);
+  if (opts.verbose) log.info("release", `  Verbose:     on`);
+  log.info("release", "");
+
+  let fail = 0;
+
+  for (let _i = 0, _it = games, _n = _it.length; _i < _n; _i++) { const game = _it[_i];
+    const gameDir = resolveGameDir(game) ?? resolve(monorepoRoot ?? process.cwd(), "games", game);
+    const { productName, appId, version } = getGameInfo(gameDir, game);
+    log.info("release", `Game: ${game} | Product: "${productName}" | AppId: ${appId} | v${version}`);
+    log.info("release", "");
+
+    // Native packaging is a single compile step — build/package/release
+    // all produce the same artifact.
+    const isAndroid = targets.every((t) => MOBILE_TARGETS.has(t));
+    log.info("release", `[package] Compiling ${game} (${targets.join(", ")})...`);
+    const ok = isAndroid
+      ? packageAndroid(game, gameDir, opts, { productName, appId, version })
+      : packageNative(game, gameDir, targets, opts, { productName, appId, version });
+    if (!ok) {
+      log.error("release", `Packaging failed for ${game} — skipping.`);
+      fail = 1;
+      continue;
+    }
+
+    log.info("release", `${game} done.`);
+    log.info("release", "");
+  }
+
+  // Summary
+  log.info("release", "");
+  if (fail) {
+    log.error("release", "One or more games failed — see output above.");
+  } else {
+    log.info("release", "All selected games processed successfully.");
+  }
+  log.info("release", `Artifacts: ${opts.out}/`);
+
+  process.exit(fail);
+}

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.
+`;
+}