@downdraft/engine 0.0.0 → 0.1.1

package/app/src/shared/feature-log.ts

@@ -0,0 +1,71 @@
+// ============================================================================
+// Host-process feature log — collects OS/CPU/RAM/runtime/flags/GPU identity
+// ============================================================================
+//
+// Synchronous collector for the `dd-host|...` startup line — used by the
+// native host bridge. GPU identity is passed in by the caller (wgpu adapter
+// info); otherwise the fields are omitted and the renderer's WebGPU adapter
+// line carries GPU identity.
+// ============================================================================
+
+import { ENGINE_VERSION, condenseText, formatBytesShort, type FeatureLogData } from "@downdraft/engine";
+import os from "node:os";
+
+export interface CollectHostFeatureLogOptions {
+  isDev: boolean;
+  deterministic: boolean;
+  /** Applied host flag names (e.g. native shim options). */
+  flags: string[];
+  /** GPU device name (best-effort). Omitted when unknown. */
+  gpuDevice?: string | null;
+  /** GPU driver version (best-effort). Omitted when unknown. */
+  gpuDriverVersion?: string | null;
+  /** Runtime tag — "bun", "node", "deno". Defaults from process. */
+  runtime?: string;
+  /** Scope label — the single-process native runtime (dd-host|...). */
+  scope?: "host";
+}
+
+/**
+ * Collect the host-process feature log data. Synchronous; safe to call at
+ * startup. Returns the data (callers cache it if they want to serve it later).
+ */
+export function collectHostFeatureLog(opts: CollectHostFeatureLogOptions): FeatureLogData {
+  const { isDev, deterministic, flags } = opts;
+  const versions = process.versions;
+  const cpus = os.cpus();
+  const cpuModel = cpus.length > 0 ? cpus[0]!.model : "";
+
+  const data: FeatureLogData = {
+    sv: 1,
+    scope: opts.scope ?? "host",
+    v: ENGINE_VERSION,
+    mode: deterministic ? "deterministic" : isDev ? "dev" : "packaged",
+    os: process.platform,
+    osRel: os.release(),
+    arch: process.arch,
+    cpu: condenseText(cpuModel, 48),
+    cpuCores: cpus.length,
+    mem: formatBytesShort(os.totalmem()),
+    node: versions.node,
+    v8: versions.v8,
+    sw: flags.length > 0 ? flags.join(",") : undefined,
+  };
+
+  // GPU identity (best-effort, provided by the caller).
+  if (opts.gpuDevice) data.gpu = condenseText(opts.gpuDevice, 48);
+  if (opts.gpuDriverVersion) data.drv = condenseText(opts.gpuDriverVersion, 32);
+
+  // Runtime tag — distinguishes bun/node/deno hosts in combined views.
+  data.rt = opts.runtime ?? runtimeTag();
+
+  return data;
+}
+
+/** Detect the JS runtime for the feature log's `rt` field. */
+function runtimeTag(): string {
+  const p = process as unknown as Record<string, unknown>;
+  if (typeof p.bun !== "undefined" || (process.versions as Record<string, string>).bun) return "bun";
+  if ((globalThis as unknown as Record<string, unknown>).Deno) return "deno";
+  return "node";
+}

package/app/src/shared/gpu-info.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// GPU system info helpers for the native (Bun/Node) host bridge.
+//
+// nvidia-smi is queried via child_process; Vulkan validation
+// status reads environment variables. Importable from any process — the only
+// hard requirement is that `nvidia-smi` exists on PATH (returns null when it
+// does not, e.g. non-NVIDIA systems).
+// ============================================================================
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { GPUSystemInfo, VulkanValidationStatus } from "./types";
+
+const execFileAsync = promisify(execFile);
+
+let cachedGpuInfo: { data: GPUSystemInfo | null; ts: number } | null = null;
+const GPU_INFO_CACHE_MS = 1000;
+
+/**
+ * Query GPU utilization/memory/temperature via `nvidia-smi`. Cached for 1s.
+ * Returns null when nvidia-smi is absent or errors (AMD/Intel GPUs, CI).
+ */
+export async function queryNvidiaSmi(): Promise<GPUSystemInfo | null> {
+  const now = Date.now();
+  if (cachedGpuInfo && now - cachedGpuInfo.ts < GPU_INFO_CACHE_MS) {
+    return cachedGpuInfo.data;
+  }
+
+  try {
+    const gpuQuery = "utilization.gpu,memory.used,memory.total,temperature.gpu,power.draw,clocks.sm,clocks.mem,name,driver_version";
+    const { stdout: output } = await execFileAsync("nvidia-smi", [
+      "--query-gpu", gpuQuery,
+      "--format", "csv,noheader,nounits",
+    ], { timeout: 3000, encoding: "utf-8" });
+
+    const labels = gpuQuery.split(",").map(l => l.replace(/\./g, "_"));
+    const gpus = (output as string).trim().split("\n").map((line: string) => {
+      const vals = line.trim().split(",").map((v: string) => v.trim());
+      const obj: Record<string, string | number> = {};
+      for (let i = 0; i < labels.length && i < vals.length; i++) {
+        const num = parseFloat(vals[i]);
+        obj[labels[i]] = isNaN(num) ? vals[i] : num;
+      }
+      return obj;
+    });
+
+    let processes: Array<{ pid: number; processName: string; usedMemoryMB: number }> = [];
+    try {
+      const { stdout: procOutput } = await execFileAsync("nvidia-smi", [
+        "--query-compute-apps", "pid,process_name,used_memory",
+        "--format", "csv,noheader,nounits",
+      ], { timeout: 3000, encoding: "utf-8" });
+      const procStr = (procOutput as string).trim();
+      if (procStr) {
+        processes = procStr.split("\n").map((line: string) => {
+          const vals = line.trim().split(",").map((v: string) => v.trim());
+          return {
+            pid: parseInt(vals[0]) || 0,
+            processName: vals[1] || "",
+            usedMemoryMB: parseFloat(vals[2]) || 0,
+          };
+        });
+      }
+    } catch {
+      // nvidia-smi process query not available
+    }
+
+    const data: GPUSystemInfo = { gpus, processes, source: "nvidia-smi", timestamp: Date.now() };
+    cachedGpuInfo = { data, ts: Date.now() };
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether Vulkan validation layers were requested via env. */
+export function getVulkanValidationStatus(): VulkanValidationStatus {
+  const enabled = process.env.VK_LAYER_KHRONOS_validation === "1" ||
+    process.env.VK_LAYER_KHRONOS_validation === "true" ||
+    process.env.ENABLE_VULKAN_VALIDATION === "1";
+  return { enabled, envVar: process.env.VK_LAYER_KHRONOS_VALIDATION ?? null };
+}

package/app/src/shared/import-cache-store.ts

@@ -0,0 +1,142 @@
+// ============================================================================
+// Import cache store — SQLite-backed cache for resolved ImportSettings
+// ============================================================================
+//
+// Storage layer used by the native host bridge. Uses node:sqlite (stable in
+// Node 24+, implemented by Bun ≥1.1). If node:sqlite is unavailable, falls
+// back to an in-memory Map (no persistence across restarts).
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import type { ImportCacheEntry } from "./types";
+
+const log = createLogger("info");
+
+interface CacheRow {
+  path: string;
+  source_mtime: number;
+  sidecar_mtime: number;
+  settings_json: string;
+  updated_at: number;
+}
+
+/** Minimal shape of `node:sqlite`'s `DatabaseSync` used by this store. */
+interface DatabaseSyncLike {
+  exec(sql: string): void;
+  prepare(sql: string): { get(...params: unknown[]): unknown; run(...params: unknown[]): void };
+  close(): void;
+}
+
+export interface ImportCacheStore {
+  get(modelPath: string): ImportCacheEntry | null;
+  set(modelPath: string, entry: ImportCacheEntry): void;
+  invalidate(modelPath: string): void;
+  close(): void;
+}
+
+/**
+ * Open (or create) the import cache at `dbPath`. Falls back to an in-memory
+ * store when node:sqlite is unavailable.
+ */
+export function createImportCacheStore(dbPath: string): ImportCacheStore {
+  let db: DatabaseSyncLike | null = null;
+  let memoryFallback: Map<string, CacheRow> | null = null;
+
+  try {
+    // Dynamic require to avoid bundler issues with node:sqlite
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { DatabaseSync } = require("node:sqlite");
+    const database: DatabaseSyncLike = new DatabaseSync(dbPath);
+    db = database;
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS import_cache (
+        path TEXT PRIMARY KEY,
+        source_mtime INTEGER NOT NULL,
+        sidecar_mtime INTEGER NOT NULL,
+        settings_json TEXT NOT NULL,
+        updated_at REAL NOT NULL
+      )
+    `);
+    log.info("import-cache", `SQLite cache opened at ${dbPath}`);
+  } catch (err) {
+    log.warn("import-cache", `node:sqlite unavailable, using in-memory fallback: ${err}`);
+    memoryFallback = new Map();
+  }
+
+  return {
+    get(modelPath: string): ImportCacheEntry | null {
+      try {
+        if (memoryFallback) {
+          const row = memoryFallback.get(modelPath);
+          if (!row) return null;
+          return {
+            settings: JSON.parse(row.settings_json),
+            sourceMtime: row.source_mtime,
+            sidecarMtime: row.sidecar_mtime,
+            updatedAt: row.updated_at,
+          };
+        }
+        if (!db) return null;
+        const stmt = db.prepare("SELECT * FROM import_cache WHERE path = ?");
+        const row = stmt.get(modelPath) as CacheRow | undefined;
+        if (!row) return null;
+        return {
+          settings: JSON.parse(row.settings_json),
+          sourceMtime: row.source_mtime,
+          sidecarMtime: row.sidecar_mtime,
+          updatedAt: row.updated_at,
+        };
+      } catch (err) {
+        log.error("import-cache", `GET failed for ${modelPath}: ${err}`);
+        return null;
+      }
+    },
+
+    set(modelPath: string, entry: ImportCacheEntry): void {
+      try {
+        const settingsJson = JSON.stringify(entry.settings);
+        if (memoryFallback) {
+          memoryFallback.set(modelPath, {
+            path: modelPath,
+            source_mtime: entry.sourceMtime,
+            sidecar_mtime: entry.sidecarMtime,
+            settings_json: settingsJson,
+            updated_at: entry.updatedAt,
+          });
+          return;
+        }
+        if (!db) return;
+        const stmt = db.prepare(`
+          INSERT OR REPLACE INTO import_cache (path, source_mtime, sidecar_mtime, settings_json, updated_at)
+          VALUES (?, ?, ?, ?, ?)
+        `);
+        stmt.run(modelPath, entry.sourceMtime, entry.sidecarMtime, settingsJson, entry.updatedAt);
+      } catch (err) {
+        log.error("import-cache", `SET failed for ${modelPath}: ${err}`);
+      }
+    },
+
+    invalidate(modelPath: string): void {
+      try {
+        if (memoryFallback) {
+          memoryFallback.delete(modelPath);
+          return;
+        }
+        if (!db) return;
+        const stmt = db.prepare("DELETE FROM import_cache WHERE path = ?");
+        stmt.run(modelPath);
+      } catch (err) {
+        log.error("import-cache", `INVALIDATE failed for ${modelPath}: ${err}`);
+      }
+    },
+
+    close(): void {
+      if (db) {
+        try { db.close(); } catch { /* ignore */ }
+        db = null;
+      }
+      memoryFallback?.clear();
+      memoryFallback = null;
+    },
+  };
+}

package/app/src/shared/index.ts

@@ -0,0 +1,6 @@
+// ============================================================================
+// @downdraft/engine/app/shared — HostAPI contract types (host + engine)
+// ============================================================================
+
+export * from "./types";
+

package/app/src/shared/mcp-discovery.ts

@@ -0,0 +1,47 @@
+// ============================================================================
+// MCP instance discovery — PID-file based. Lets the stdio bridge
+// auto-discover running game instances.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const log = createLogger("info");
+
+/**
+ * Directory holding one PID file per running downdraft game instance.
+ * Each file is named `<pid>` and contains the bound MCP HTTP port (string).
+ * The stdio bridge reads this directory to auto-discover running instances;
+ * dead-PID files are pruned on read. Best-effort cleanup on process exit.
+ */
+export function mcpPortDir(): string {
+  return join(homedir(), ".downdraft", "port");
+}
+
+/**
+ * Write `~/.downdraft/port/<pid>` containing the bound port, so the stdio
+ * bridge (and other local clients) can discover this instance. Also writes
+ * `<pid>.token` holding the transport's bearer token — clients that opt into
+ * auth (`mcp.requireAuth` / `MCP_AUTH=1`) read it and send the token via the
+ * `Authorization: Bearer <token>` or `X-Downdraft-Token` header. The port
+ * file format stays a bare number for backward compatibility with existing
+ * bridges. Returns a cleanup function that removes both files (best-effort).
+ */
+export function writeMcpPidFile(port: number, token: string): () => void {
+  const dir = mcpPortDir();
+  const pidFile = join(dir, String(process.pid));
+  const tokenFile = `${pidFile}.token`;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(pidFile, String(port));
+    writeFileSync(tokenFile, token, { mode: 0o600 });
+  } catch (e) {
+    log.warn("MCP", `Failed to write PID file ${pidFile}: ${(e as Error).message}`);
+  }
+  return () => {
+    try { unlinkSync(pidFile); } catch { /* already gone */ }
+    try { unlinkSync(tokenFile); } catch { /* already gone */ }
+  };
+}

package/app/src/shared/mcp-proxy.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// MCP proxy-handler factory — merges "host-side" tools with the renderer
+// harness's tools behind a single JSON-RPC proxy handler.
+//
+// The caller provides `forwardToRenderer` — on the native host it's a
+// direct function call into the handler registered via
+// `downdraft.onMcpRequest`.
+// ============================================================================
+
+import type { ToolRegistration } from "@downdraft/engine/mcp";
+import type { McpProxyHandler } from "@downdraft/engine/mcp/http-transport";
+import { createLogger } from "@downdraft/engine/util/logger";
+
+const log = createLogger("info");
+
+/**
+ * Create a proxy handler that:
+ *  - dispatches `tools/call` to host-side tools by name (no renderer hop),
+ *  - merges host tool defs with renderer tool defs in `tools/list`,
+ *  - forwards everything else to `forwardToRenderer`.
+ */
+export function createMcpProxyHandler(
+  hostTools: ToolRegistration[],
+  forwardToRenderer: (request: { method: string; params?: Record<string, unknown> }) => Promise<unknown>,
+): McpProxyHandler {
+  const hostToolMap = new Map<string, ToolRegistration>();
+  hostTools.forEach((t) => { hostToolMap.set(t.def.name, t);; });
+
+  return async (request) => {
+    const { method, params = {} } = request;
+
+    // --- Host-side tool dispatch ---
+    if (method === "tools/call") {
+      const name = params.name as string;
+      if (hostToolMap.has(name)) {
+        const tool = hostToolMap.get(name)!;
+        const args = (params.arguments as Record<string, unknown>) ?? {};
+        try {
+          return await tool.handler(args);
+        } catch (e) {
+          return {
+            content: [{ type: "text", text: `Tool "${name}" failed: ${(e as Error).message}` }],
+            isError: true,
+          };
+        }
+      }
+      // Not a host tool — fall through to renderer.
+    }
+
+    // --- tools/list: merge host tool defs with renderer's ---
+    if (method === "tools/list") {
+      let rendererTools: unknown[] = [];
+      try {
+        const rendererResult = await forwardToRenderer({ method, params });
+        const r = rendererResult as { tools?: unknown[]; error?: unknown };
+        if ("error" in r && r.error) {
+          log.warn("MCP", `tools/list renderer error: ${JSON.stringify(r.error)} (returning host tools only)`);
+        } else {
+          rendererTools = (r as { tools?: unknown[] }).tools ?? [];
+        }
+      } catch (e) {
+        log.warn("MCP", `tools/list renderer unavailable: ${(e as Error).message} (returning host tools only)`);
+      }
+      const hostDefs = hostTools.map((t) => ({
+        name: t.def.name,
+        description: t.def.description,
+        inputSchema: t.def.inputSchema,
+      }));
+      // tools/call prefers host tools by name — the list must match that
+      // dispatch order or clients see a tool that never actually runs (e.g.
+      // the renderer's own capture_screenshot loses to the host's).
+      const hostNames = new Set(hostToolMap.keys());
+      const deduped = (rendererTools as Array<{ name?: string }>).filter(
+        (t) => !t?.name || !hostNames.has(t.name),
+      );
+      return { tools: [...hostDefs, ...deduped] };
+    }
+
+    // --- All other methods: forward to renderer ---
+    return forwardToRenderer({ method, params });
+  };
+}