@roster-lock/match-agent 0.1.0 → 0.2.0

package/src/handle-room/version-1/game-launcher.ts

@@ -0,0 +1,263 @@
+import { randomUUID } from "node:crypto";
+import { ConnectionSetup, StartGameArgs, PlatformTarget } from "@roster-lock/types";
+import { GameLauncherLocalSettings } from "@roster-lock/plugin-runtime";
+import { jsonBody, HTTPRequestHandler, HTTPError } from "../../utils/http-router";
+import { V1Env } from "./globals/types";
+import { castLockConfig } from "./piece-sort";
+import z, { ZodType } from "zod";
+
+// One listing endpoint, mirroring /piece/sort-list/available - every installed
+// game-launcher plugin's full AvailableGameLauncher record in one response, rather
+// than splitting connection-mode support and gameConfigSchema into separate
+// per-plugin routes. Both are small, static JSON already computed by
+// listAvailable() from the plugin's own module fields, so there's no
+// fetch-cost reason to make a client ask for them separately, and nothing
+// else in this router splits a plugin's metadata that way either.
+export const listAvailableGameLaunchers: HTTPRequestHandler = async function(
+  this: V1Env, { res }
+){
+  const available = await this.pluginRuntime.gameLauncher.listAvailable();
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(available));
+}
+
+function requirePluginName(routeInfo: { params: Record<string, string | undefined> }): string {
+  const pluginName = routeInfo.params.pluginName;
+  if(!pluginName) throw new HTTPError(400, "Missing pluginName");
+  return pluginName;
+}
+
+async function requireBinaryLocation(env: V1Env, pluginName: string): Promise<string> {
+  const settings = await env.pluginRuntime.gameLauncher.getLocalSettings(pluginName);
+  if(!settings.binaryLocation){
+    throw new HTTPError(400, `Game launcher "${pluginName}" has no binaryLocation configured`);
+  }
+  return settings.binaryLocation;
+}
+
+// See docs/v2/binary-location.md - every GameLauncherPlugin function that
+// resolves a concrete binary out of a (possibly multi-platform) binaryLocation
+// bundle takes a required target, with no implicit "current host" default at
+// that layer. match-agent is what decides the target value: it defaults to
+// its own process.platform/process.arch (the ordinary case - a client asking
+// match-agent to run/inspect the game it's about to run on this same host),
+// but a caller can override either via query params for the deliberate
+// exception (e.g. forcing a win32-x64 build under Wine on a Linux host).
+function resolveTarget(routeInfo: { url: URL }): PlatformTarget {
+  const platform = routeInfo.url.searchParams.get("platform");
+  const arch = routeInfo.url.searchParams.get("arch");
+  return {
+    platform: (platform || process.platform) as PlatformTarget["platform"],
+    arch: (arch || process.arch) as PlatformTarget["arch"],
+  };
+}
+
+export const getGameLauncherSettings: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+  const settings = await this.pluginRuntime.gameLauncher.getLocalSettings(pluginName);
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(settings));
+}
+
+const localSettingsBodySchema: ZodType<GameLauncherLocalSettings> = z.object({
+  binaryLocation: z.string().optional(),
+  localConfig: z.unknown().optional(),
+}).strict();
+
+export const setGameLauncherSettings: HTTPRequestHandler = async function(
+  this: V1Env, { req, res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+  const body = await jsonBody(req);
+  const parseResult = localSettingsBodySchema.safeParse(body);
+  if(!parseResult.success) throw new HTTPError(400, "Bad Form", parseResult.error);
+
+  await this.pluginRuntime.gameLauncher.setLocalSettings(pluginName, parseResult.data);
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ ok: true }));
+}
+
+// Installs the plugin *package* itself (registry/manifest-based, via
+// PluginManager - distinct from updateBinary below, which fetches a newer
+// engine binary for a plugin that's already installed).
+export const installGameLauncherPlugin: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+
+  try {
+    await this.pluginRuntime.installPlugin(pluginName);
+  } catch(e){
+    throw new HTTPError(400, (e as Error).message);
+  }
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ ok: true }));
+}
+
+export const getGameLauncherVersion: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+  const binaryLocation = await requireBinaryLocation(this, pluginName);
+  const target = resolveTarget(routeInfo);
+
+  const [local, supported] = await Promise.all([
+    this.pluginRuntime.gameLauncher.getLocalVersion(pluginName, binaryLocation, target),
+    this.pluginRuntime.gameLauncher.getSupportedVersion(pluginName, binaryLocation),
+  ]);
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ local, supported }));
+}
+
+export const validateGameLauncherBinaryLocation: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+  const binaryLocation = await requireBinaryLocation(this, pluginName);
+  const target = resolveTarget(routeInfo);
+
+  const result = await this.pluginRuntime.gameLauncher.validateBinaryLocation(pluginName, binaryLocation, target);
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(result));
+}
+
+export const updateGameLauncherBinary: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+  const binaryLocation = await requireBinaryLocation(this, pluginName);
+  const target = resolveTarget(routeInfo);
+
+  try {
+    await this.pluginRuntime.gameLauncher.updateBinary(pluginName, binaryLocation, target);
+  } catch(e){
+    // updateBinary throws a plain Error when a plugin doesn't declare one at
+    // all (see GameLauncher.updateBinary) - that's a client-facing 400 ("this
+    // runner can't be updated in-app"), not a server fault.
+    throw new HTTPError(400, (e as Error).message);
+  }
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ ok: true }));
+}
+
+const coordinatorAddressSchema = z.object({ host: z.string(), port: z.number() }).strict();
+
+// This is what a caller sends match-agent, not what the plugin ends up
+// with - direct-tcp still carries a coordinator address here.
+// GameLauncher.startGame (plugin-runtime) resolves it into a ConnectionConfig
+// before ever invoking a plugin, so a plugin never has to know a coordinator
+// exists at all.
+const connectionSetupSchema: ZodType<ConnectionSetup> = z.union([
+  z.object({
+    type: z.literal("direct-tcp"), party: z.literal("host"), port: z.number(), coordinator: coordinatorAddressSchema,
+  }).strict(),
+  z.object({
+    type: z.literal("direct-tcp"), party: z.literal("client"), port: z.number(), coordinator: coordinatorAddressSchema,
+  }).strict(),
+  z.object({ type: z.literal("room"), version: z.string(), url: z.string() }).strict(),
+  z.object({ type: z.literal("internal") }).strict(),
+]);
+
+// Everything StartGameArgs needs except currentMachine.privateKeyFile (a
+// match-agent-managed temp file, not something a caller ever supplies) and
+// matchAgent (match-agent knows its own port/authCode - trusting a caller's
+// claim about either would let it point a plugin at a different match-agent
+// entirely). currentMachine's raw privateKey *is* client-supplied here: only
+// the browser holds it, and GameLauncher.startGame is what turns it into the
+// restrictive-permission temp file plugins actually receive.
+type StartGameBody = {
+  connectionConfig: ConnectionSetup,
+  currentMachine: { machineId: string, publicKey: string, privateKey: string },
+  allMachines: unknown,
+  selectionResult: unknown,
+  rosterConfig: unknown,
+  gameConfig: unknown,
+  relayRoomId: string,
+}
+
+const startGameBodySchema: ZodType<StartGameBody> = z.object({
+  connectionConfig: connectionSetupSchema,
+  currentMachine: z.object({
+    machineId: z.string(), publicKey: z.string(), privateKey: z.string(),
+  }).strict(),
+  allMachines: z.unknown(),
+  selectionResult: z.unknown(),
+  rosterConfig: z.unknown(),
+  gameConfig: z.unknown(),
+  relayRoomId: z.string(),
+}).strict();
+
+export const startGameLauncher: HTTPRequestHandler = async function(
+  this: V1Env, { req, res }, routeInfo
+){
+  const pluginName = requirePluginName(routeInfo);
+  const binaryLocation = await requireBinaryLocation(this, pluginName);
+  const target = resolveTarget(routeInfo);
+
+  const body = await jsonBody(req);
+  const parseResult = startGameBodySchema.safeParse(body);
+  if(!parseResult.success) throw new HTTPError(400, "Bad Form", parseResult.error);
+  const { connectionConfig, currentMachine, allMachines, selectionResult, gameConfig, relayRoomId } = parseResult.data;
+  const rosterConfig = castLockConfig(parseResult.data.rosterConfig);
+
+  const handle = await this.pluginRuntime.gameLauncher.startGame(pluginName, binaryLocation, target, connectionConfig, {
+    currentMachine,
+    allMachines: allMachines as StartGameArgs<unknown>["allMachines"],
+    selectionResult: selectionResult as StartGameArgs<unknown>["selectionResult"],
+    rosterConfig,
+    gameConfig,
+    relayRoomId,
+    matchAgent: { port: this.matchAgent.getPort(), authCode: this.matchAgent.authCode },
+  });
+
+  const handleId = randomUUID();
+  this.processHandles.set(handleId, { pluginName, handle });
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ handleId }));
+}
+
+export const getGameProcessStatus: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const handleId = routeInfo.params.handleId;
+  const entry = handleId ? this.processHandles.get(handleId) : undefined;
+  if(!entry) throw new HTTPError(404, "Unknown process handle");
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ exited: entry.handle.exited }));
+}
+
+// Every process this match-agent has started, across every game-launcher
+// plugin - backs pages/Game in match-agent-client, which shows one row per
+// entry regardless of which plugin launched it.
+export const listGameProcesses: HTTPRequestHandler = async function(
+  this: V1Env, { res }
+){
+  const processes = Array.from(this.processHandles.entries()).map(([handleId, entry]) => ({
+    handleId, pluginName: entry.pluginName, exited: entry.handle.exited,
+  }));
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(processes));
+}
+
+// Best-effort, same as GameProcessHandle.stop() itself - see that type's own
+// docs on why a plugin may not always be able to actually stop the game.
+export const stopGameProcess: HTTPRequestHandler = async function(
+  this: V1Env, { res }, routeInfo
+){
+  const handleId = routeInfo.params.handleId;
+  const entry = handleId ? this.processHandles.get(handleId) : undefined;
+  if(!entry) throw new HTTPError(404, "Unknown process handle");
+
+  await entry.handle.stop();
+
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ ok: true }));
+}

package/src/handle-room/version-1/globals/types.ts

@@ -1,7 +1,31 @@
 
 import { IFolderDB } from "./FolderDB";
 import { PluginManager } from "@roster-lock/plugin-runtime";
+import { GameProcessHandle } from "@roster-lock/types";
+
+// Known upfront (CLI --port) rather than read off a listening socket, so it's
+// a plain value in the common case - getPort() only needs to be lazy for
+// tests that bind an ephemeral port (0) and only learn the real one after
+// server.listen() resolves.
+export type MatchAgentSelfInfo = {
+  authCode: string,
+  getPort: () => number,
+}
+
+// pluginName is kept alongside the handle (not just the handleId key) so a
+// process can be listed/identified without a caller having to already know
+// which plugin started it - see game-launcher.ts's listGameProcesses.
+export type ProcessHandleEntry = {
+  pluginName: string,
+  handle: GameProcessHandle,
+}
+
 export type V1Env = {
   fileDB: IFolderDB,
   pluginRuntime: PluginManager,
+  matchAgent: MatchAgentSelfInfo,
+  // In-memory only - a match-agent restart loses track of processes it
+  // started before the restart (same best-effort tradeoff as GameProcessHandle
+  // itself; there's no persistent process-supervision story here).
+  processHandles: Map<string, ProcessHandleEntry>,
 }

package/src/handle-room/version-1/index.ts

@@ -7,11 +7,17 @@ import { httpHandler } from "./room-handler-bridge/http-handler";
 import { getFilesOfAsset, getPieceFileContents } from "./file-routes";
 import { ensurePieceDownloaded, ensurePieceDownloadedWs, listDownloadedPiecesDirect } from "./select";
 import { listAvailableSortPlugins, sortListPlugin, gameComplete } from "./piece-sort";
-import { IFolderDB, V1Env } from "./globals";
+import {
+  listAvailableGameLaunchers, getGameLauncherSettings, setGameLauncherSettings, getGameLauncherVersion,
+  validateGameLauncherBinaryLocation, updateGameLauncherBinary, startGameLauncher, getGameProcessStatus,
+  installGameLauncherPlugin, listGameProcesses, stopGameProcess,
+} from "./game-launcher";
+import { IFolderDB, V1Env, MatchAgentSelfInfo, ProcessHandleEntry } from "./globals";
 import { PluginManager } from "@roster-lock/plugin-runtime";
 
-export const createV1Routers = (fileDB: IFolderDB, pluginRuntime: PluginManager)=>{
-  const env: V1Env = { fileDB, pluginRuntime };
+export const createV1Routers = (fileDB: IFolderDB, pluginRuntime: PluginManager, matchAgent: MatchAgentSelfInfo)=>{
+  const processHandles = new Map<string, ProcessHandleEntry>();
+  const env: V1Env = { fileDB, pluginRuntime, matchAgent, processHandles };
   const httpRouter = new HTTPRouter();
   const wsRouter = new WebSocketRouter()
 
@@ -23,6 +29,20 @@ export const createV1Routers = (fileDB: IFolderDB, pluginRuntime: PluginManager)
   httpRouter.get("/piece/sort-list/available", listAvailableSortPlugins.bind(env));
   httpRouter.post("/piece/sort-list/plugin/:pluginName", sortListPlugin.bind(env));
   httpRouter.post("/game-complete", gameComplete.bind(env));
+  httpRouter.get("/game-launcher/available", listAvailableGameLaunchers.bind(env));
+  httpRouter.post("/game-launcher/:pluginName/install", installGameLauncherPlugin.bind(env));
+  httpRouter.get("/game-launcher/:pluginName/settings", getGameLauncherSettings.bind(env));
+  httpRouter.put("/game-launcher/:pluginName/settings", setGameLauncherSettings.bind(env));
+  httpRouter.get("/game-launcher/:pluginName/version", getGameLauncherVersion.bind(env));
+  httpRouter.get("/game-launcher/:pluginName/validate", validateGameLauncherBinaryLocation.bind(env));
+  httpRouter.post("/game-launcher/:pluginName/update", updateGameLauncherBinary.bind(env));
+  httpRouter.post("/game-launcher/:pluginName/start", startGameLauncher.bind(env));
+  httpRouter.get("/game-launcher/:pluginName/process/:handleId", getGameProcessStatus.bind(env));
+  httpRouter.post("/game-launcher/:pluginName/process/:handleId/stop", stopGameProcess.bind(env));
+  // Plugin-agnostic, unlike the routes above - lists every process this
+  // match-agent has started across every plugin (see pages/Game in
+  // match-agent-client), not just one plugin's.
+  httpRouter.get("/game-launcher/processes", listGameProcesses.bind(env));
 
 
   wsRouter.mount("/sync-dl", wsHandler.bind(env));

package/src/handle-room/version-1/piece-sort.ts

@@ -6,7 +6,7 @@ import { UserSelectionSchema } from "./schema/selected";
 import { V1Env } from "./globals/types";
 import z, { ZodType } from "zod";
 
-function castLockConfig(uncasted: unknown): RosterLockV1Config {
+export function castLockConfig(uncasted: unknown): RosterLockV1Config {
   const casted = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(uncasted, true);
   if(!casted.valid) throw new HTTPError(400, "Invalid lockConfig", casted.error);
   return casted.value;

package/src/index.ts

@@ -11,6 +11,7 @@ import { generateAuthCode, authMiddleware, validateAuthCode } from "./authentica
 import { corsMiddleware } from "./cors";
 import { createEditorV1Router } from "./editor-support";
 import { MatchAgentServer } from "./server";
+import { createDevClientHandler, createStaticClientHandler } from "./serve-client";
 import { program } from "commander";
 import { createV1Routers } from "./handle-room/version-1";
 import { getSQLite3FolderDB } from "./handle-room/version-1/globals/FolderDB";
@@ -55,8 +56,13 @@ program
     "config file to read/persist the auth code and folders from " +
     "(defaults to a config next to this executable, falling back to the home directory)"
   )
+  .option(
+    "--dev",
+    "serve the match-agent-client from its Vite dev server (live source, HMR) instead of the prebuilt client/dist",
+    false
+  )
   .action(async (options: {
-    port: string, authCode?: string, pieceFolder?: string, pluginFolder?: string, configFile?: string,
+    port: string, authCode?: string, pieceFolder?: string, pluginFolder?: string, configFile?: string, dev: boolean,
   }) => {
     const port = Number(options.port);
     if (!Number.isInteger(port) || port < 0 || port > 65535) {
@@ -84,7 +90,7 @@ program
     await mkdir(pieceFolder, { recursive: true });
     await mkdir(pluginFolder, { recursive: true });
 
-    startServer(port, authCode, pluginFolder, pieceFolder);
+    startServer(port, authCode, pluginFolder, pieceFolder, { dev: options.dev });
   });
 
 program
@@ -203,7 +209,10 @@ if (require.main === module) {
   program.parse();
 }
 
-export async function startServer(port: number, authCode: string, pluginFolder: string, piecesFolder: string){
+export async function startServer(
+  port: number, authCode: string, pluginFolder: string, piecesFolder: string,
+  options: { dev?: boolean } = {}
+){
   const pluginRuntime = await PluginManager.create(pluginFolder);
   const fileDB = getSQLite3FolderDB(piecesFolder, pluginRuntime);
 
@@ -211,13 +220,15 @@ export async function startServer(port: number, authCode: string, pluginFolder:
   // "{/*path}" = path-to-regexp v8 catch-all; a bare "/" only matches the
   // root exactly, which would skip CORS on every real route.
   server.httpRouter.use("{/*path}", corsMiddleware);
-  server.httpRouter.get("/", ({ res })=>{
+  server.httpRouter.get("/health", ({ res })=>{
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ "hello": "world" }));
   });
   server.httpRouter.post("/validate-authcode", validateAuthCode(authCode))
 
-  const { httpRouter: v1HttpRouter, wsRouter: v1WsRouter } = createV1Routers(fileDB, pluginRuntime);
+  const { httpRouter: v1HttpRouter, wsRouter: v1WsRouter } = createV1Routers(
+    fileDB, pluginRuntime, { authCode, getPort: () => port }
+  );
   server.httpRouter.use("/v1", authMiddleware(authCode), v1HttpRouter);
   server.wsRouter.use("/v1", authMiddleware(authCode), v1WsRouter);
 
@@ -225,6 +236,15 @@ export async function startServer(port: number, authCode: string, pluginFolder:
   // room protocol (/v1) can move to /v2 without dragging the editor API along.
   server.httpRouter.use("/editor/v1", authMiddleware(authCode), createEditorV1Router(pluginRuntime, fileDB));
 
+  // Mounted last so it only ever sees requests the routes above didn't
+  // claim - match-agent-client stays Vite's, this just puts it behind the
+  // same origin/port as the API instead of a separately-run `vite dev`.
+  // .all (not .use) - .use's prefix-mount semantics strip the matched
+  // portion off the pathname for nested routing, which for a "{/*path}"
+  // catch-all is the entire path, leaving the client handler unable to
+  // tell one route from another.
+  server.httpRouter.all("{/*path}", options.dev ? createDevClientHandler() : createStaticClientHandler());
+
   server.listen(port, () => {
     console.log(`match-agent listening on port ${port}`);
   });

package/src/serve-client.ts

@@ -0,0 +1,100 @@
+
+import { createReadStream } from "node:fs";
+import { stat as fsStat, readFile } from "node:fs/promises";
+import { join, resolve, normalize, sep } from "node:path";
+import { lookup as mimeLookup } from "mime-types";
+import { HTTPRequestHandler } from "./utils/http-router";
+
+// dist/serve-client.js and src/serve-client.ts sit at the same depth under
+// match-agent/, so this resolves the same way whether running compiled or
+// straight from source.
+export const CLIENT_DIR = resolve(__dirname, "../client");
+export const CLIENT_DIST_DIR = join(CLIENT_DIR, "dist");
+
+// Routes the client's SPA fallback must not swallow.
+const API_PATHS = ["/v1", "/editor/v1", "/validate-authcode", "/health"];
+function isApiPath(pathname: string): boolean {
+  return API_PATHS.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+
+// vite is ESM-only, dynamically imported so the dependency stays optional
+// for the prebuilt/static path. The type is inferred from that import
+// rather than named ("vite"'s CJS type stub - what a "require"-resolved
+// static `import type` would hit from this CommonJS package - is a bare
+// `any`; only its real ESM types describe ViteDevServer).
+function createViteDevServer(){
+  return import("vite").then(({ createServer }) => createServer({
+    root: CLIENT_DIR,
+    server: { middlewareMode: true },
+    appType: "custom",
+  }));
+}
+
+// Vite dev server is expensive to boot (it crawls the client's deps) and
+// middleware mode expects one long-lived instance, so it's created once and
+// reused across requests rather than per-request.
+let viteServerPromise: ReturnType<typeof createViteDevServer> | undefined;
+function getViteDevServer(){
+  if(!viteServerPromise) viteServerPromise = createViteDevServer();
+  return viteServerPromise;
+}
+
+// Live-source mode: proxies through Vite's own dev middleware (transforms,
+// HMR websocket upgrade, etc.) so the client keeps building from its Vite
+// config instead of a separately-built bundle.
+export function createDevClientHandler(): HTTPRequestHandler {
+  return async ({ req, res }, { url }, next) => {
+    if(isApiPath(url.pathname)) return next();
+    const vite = await getViteDevServer();
+    vite.middlewares(req, res, async (err?: unknown) => {
+      if(err) return next(err);
+      if((req.method || "GET").toUpperCase() !== "GET") return next();
+      try {
+        const rawHtml = await readFile(join(CLIENT_DIR, "index.html"), "utf-8");
+        const html = await vite.transformIndexHtml(url.pathname, rawHtml);
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(html);
+      } catch(e){
+        next(e);
+      }
+    });
+  };
+}
+
+// Prebuilt mode: serves client/dist as static files, falling back to
+// index.html for any unmatched GET so client-side routes resolve on refresh.
+export function createStaticClientHandler(distDir: string = CLIENT_DIST_DIR): HTTPRequestHandler {
+  return async ({ req, res }, { url }, next) => {
+    if(isApiPath(url.pathname)) return next();
+    if((req.method || "GET").toUpperCase() !== "GET") return next();
+
+    let requestedPath: string;
+    try {
+      requestedPath = normalize(join(distDir, decodeURIComponent(url.pathname)));
+    } catch(e){
+      return next(e);
+    }
+    if(requestedPath !== distDir && !requestedPath.startsWith(distDir + sep)){
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Bad path" }));
+      return;
+    }
+
+    const filePath = (await resolveExistingFile(requestedPath)) ?? join(distDir, "index.html");
+    try {
+      res.writeHead(200, { "Content-Type": mimeLookup(filePath) || "application/octet-stream" });
+      createReadStream(filePath).pipe(res);
+    } catch(e){
+      next(e);
+    }
+  };
+}
+
+async function resolveExistingFile(path: string): Promise<string | undefined> {
+  try {
+    const stat = await fsStat(path);
+    return stat.isFile() ? path : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/server.ts

@@ -33,7 +33,7 @@ export class MatchAgentServer {
     });
     this.httpServer.on('request', (req, res)=>{
       this.httpRouter.handleRequest({ req, res }, (err: unknown)=>{
-        debug && console.log("HTTP Error:", err);
+        debug && console.log("HTTP Error:", req.method, req.url, err);
         if(res.writableEnded){
           debug && console.warn("Router threw error and response ended")
           return;

package/tests/integration/game-launcher-list.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { startTestServer, TestServer } from "./helpers/server";
+import { makeTempFolder, cleanupFolder } from "./helpers/piece";
+import { createFixturePluginDir } from "./helpers/plugin-dir";
+
+describe("GET /v1/game-launcher/available", () => {
+  const cleanups: Array<() => Promise<void> | void> = [];
+  afterEach(async () => {
+    while (cleanups.length) await cleanups.pop()!();
+  });
+
+  function get(server: TestServer) {
+    return fetch(`${server.httpUrl}/v1/game-launcher/available`, {
+      headers: { Authorization: `Bearer ${server.authCode}` },
+    });
+  }
+
+  it("returns [] when no game-launcher plugins are installed", async () => {
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder);
+    cleanups.push(() => server.close());
+
+    const res = await get(server);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([]);
+  });
+
+  it("lists an installed game-launcher plugin with its connection/schema/engineSha metadata", async () => {
+    // "private": true on ikemen-go's package.json means it can't be resolved
+    // via npm - installPlugin takes a local folder path directly instead
+    // (arborist installs it same as `npm install <path>`), which is how this
+    // fixture, and every dl-*/piece-selection-sort-* fixture before it, gets
+    // installed for tests without publishing anything.
+    const fixture = await createFixturePluginDir(["@roster-lock/game-launcher-ikemen-go"]);
+    cleanups.push(fixture.cleanup);
+
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder, undefined, fixture.pluginDir);
+    cleanups.push(() => server.close());
+
+    const res = await get(server);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Array<Record<string, unknown>>;
+    expect(body).toHaveLength(1);
+
+    const [runner] = body;
+    expect(runner.pluginName).toBe("@roster-lock/game-launcher-ikemen-go");
+    expect(runner.publicInfo).toMatchObject({ title: expect.any(String), description: expect.any(String) });
+    expect(runner.supportedConnectionModes).toEqual(["direct-tcp"]);
+    expect(runner.supportedRoomVersions).toBeUndefined();
+    // A real sha256 hex digest, not a placeholder - proves engineSha survived
+    // the plugin's own module boundary (install -> import -> JSON response),
+    // not just that the field exists.
+    expect(runner.engineSha).toMatch(/^[0-9a-f]{64}$/);
+    expect(runner.gameConfigSchema).toMatchObject({ type: "object" });
+    expect(runner.localConfigSchema).toEqual({});
+  });
+
+  it("ignores plugins of other types", async () => {
+    const fixture = await createFixturePluginDir([
+      "@roster-lock/piece-selection-sort-most-used-locally",
+      "@roster-lock/dl-protocol-http",
+    ]);
+    cleanups.push(fixture.cleanup);
+
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder, undefined, fixture.pluginDir);
+    cleanups.push(() => server.close());
+
+    const res = await get(server);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([]);
+  });
+});