@roster-lock/match-agent 0.1.0

package/src/index.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+
+export * from "./handle-room/version-1";
+
+import { join as pathJoin, resolve as pathResolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+import {
+  CONFIG_FILE_NAME, DEFAULT_MATCH_CONIFG, getConfig, setConfig, configExists, resolveConfigFolders, findConfigFile,
+} from "./config";
+import { generateAuthCode, authMiddleware, validateAuthCode } from "./authentication";
+import { corsMiddleware } from "./cors";
+import { createEditorV1Router } from "./editor-support";
+import { MatchAgentServer } from "./server";
+import { program } from "commander";
+import { createV1Routers } from "./handle-room/version-1";
+import { getSQLite3FolderDB } from "./handle-room/version-1/globals/FolderDB";
+import {
+  PluginManager, createPluginCommands, syncPluginsToOfficialManifest, DEFAULT_REPO_URL, manifestUrlFromRepo,
+} from "@roster-lock/plugin-runtime";
+
+
+program
+  .name("rosterlock-match-agent")
+  .description("Runs the match-agent server");
+
+// Resolves the same way `listen` does (sibling config next to the executable,
+// falling back to home), so `plugin install` without -d/--plugin-dir lands
+// in the folder a mounted USB's config actually points at, instead of
+// silently defaulting to plugin-runtime's own ~/roster-lock/plugins.
+async function defaultPluginDirFromConfig(): Promise<string> {
+  const configFilePath = await findConfigFile();
+  const existingConfig = (await configExists(configFilePath)) ? await getConfig(configFilePath) : null;
+  return resolveConfigFolders(configFilePath, existingConfig ?? {}).pluginFolder;
+}
+
+// Plugin management (install/update/uninstall/list/priority), reused as-is
+// from plugin-runtime under its own `plugin` group - mainly here for testing
+// convenience, not meant to be the primary way plugins get managed.
+const pluginCommand = program
+  .command("plugin")
+  .description("Manage plugins (install/update/uninstall/list/priority)");
+for(const command of createPluginCommands({ getDefaultPluginDir: defaultPluginDirFromConfig })){
+  pluginCommand.addCommand(command);
+}
+
+program
+  .command("listen")
+  .description("Runs the match-agent server (leave this running while you play - it can serve multiple games/matches at once)")
+  .option("--port <port>", "port to listen on", "58732")
+  .option("--auth-code <string>", "authentication code required for access (overrides the config file)")
+  .option("--piece-folder <path>", "folder to store downloaded pieces in (overrides the config file)")
+  .option("--plugin-folder <path>", "folder to load plugins from (overrides the config file)")
+  .option(
+    "--config-file <path>",
+    "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)"
+  )
+  .action(async (options: {
+    port: string, authCode?: string, pieceFolder?: string, pluginFolder?: string, configFile?: string,
+  }) => {
+    const port = Number(options.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      throw new Error(`Invalid port: ${options.port}`);
+    }
+
+    const configFilePath = await findConfigFile(options.configFile);
+    const existingConfig = (await configExists(configFilePath)) ? await getConfig(configFilePath) : null;
+
+    const authCode = options.authCode || existingConfig?.authCode || generateAuthCode();
+    const resolvedFolders = resolveConfigFolders(configFilePath, existingConfig ?? {});
+    const pieceFolder = options.pieceFolder ? pathResolve(options.pieceFolder) : resolvedFolders.pieceFolder;
+    const pluginFolder = options.pluginFolder ? pathResolve(options.pluginFolder) : resolvedFolders.pluginFolder;
+
+    // Persist so the auth code stays stable across runs (and a first run
+    // against a fresh config writes one out) - keep the config's own
+    // relative pieceFolder/pluginFolder untouched so a CLI override on this
+    // run doesn't get baked in as this config's permanent setting.
+    await setConfig(configFilePath, {
+      authCode,
+      pieceFolder: existingConfig?.pieceFolder,
+      pluginFolder: existingConfig?.pluginFolder,
+    });
+
+    await mkdir(pieceFolder, { recursive: true });
+    await mkdir(pluginFolder, { recursive: true });
+
+    startServer(port, authCode, pluginFolder, pieceFolder);
+  });
+
+program
+  .command("mount-usb <path>")
+  .description(
+    "Scaffold a portable config at <path>: creates pieces/plugins folders and a " +
+    CONFIG_FILE_NAME + " next to where the match-agent executable will run from " +
+    "(e.g. a mounted USB drive), addressing the folders by relative path."
+  )
+  .option("--piece-folder <name>", "name of the pieces folder to create, relative to <path>", "pieces")
+  .option("--plugin-folder <name>", "name of the plugins folder to create, relative to <path>", "plugins")
+  .option("--auth-code <string>", "auth code to store in the config (a random one is generated if omitted)")
+  .option("--force", "overwrite an existing config at <path>, generating a new auth code unless --auth-code is given", false)
+  .option(
+    "--manifest-url <url>",
+    "if given, sync plugins to match the official manifest at this URL right after mounting"
+  )
+  .action(async (targetPath: string, options: {
+    pieceFolder: string, pluginFolder: string, authCode?: string, force: boolean, manifestUrl?: string,
+  }) => {
+    const mountFolder = pathResolve(targetPath);
+    await mkdir(mountFolder, { recursive: true });
+
+    const configFilePath = pathJoin(mountFolder, CONFIG_FILE_NAME);
+    const existingConfig = (await configExists(configFilePath)) ? await getConfig(configFilePath) : null;
+    if(existingConfig && !options.force){
+      throw new Error(`${configFilePath} already exists - pass --force to overwrite it`);
+    }
+
+    const pluginFolder = pathJoin(mountFolder, options.pluginFolder);
+    await mkdir(pathJoin(mountFolder, options.pieceFolder), { recursive: true });
+    await mkdir(pluginFolder, { recursive: true });
+
+    const authCode = options.authCode || existingConfig?.authCode || generateAuthCode();
+    await setConfig(configFilePath, {
+      authCode,
+      pieceFolder: options.pieceFolder,
+      pluginFolder: options.pluginFolder,
+    });
+
+    console.log(`Wrote ${configFilePath}`);
+
+    if(options.manifestUrl){
+      const { installed, priorityChanges } = await syncPluginsToOfficialManifest(pluginFolder, options.manifestUrl);
+      for(const p of installed) console.log(`Installed ${p.package}@${p.version}`);
+      for(const p of priorityChanges) console.log(`Set priority of ${p.package} to ${p.priority}`);
+      console.log(`Plugin sync complete - ${installed.length} plugin(s) installed/updated, ${priorityChanges.length} priority change(s) applied.`);
+    }
+  });
+
+program
+  .command("install <authCode>")
+  .description(
+    "Install match-agent for regular (non-USB) use: creates pieces/plugins folders and a " +
+    CONFIG_FILE_NAME + " at the default config location, stores the given auth code, and syncs " +
+    "plugins to the official manifest. Intended as the one-time setup step before `listen`."
+  )
+  .option(
+    "--config-file <path>",
+    "config file to write (defaults to the standard home-directory location)"
+  )
+  .option("--piece-folder <name>", "name of the pieces folder to create, relative to the config file", "pieces")
+  .option("--plugin-folder <name>", "name of the plugins folder to create, relative to the config file", "plugins")
+  .option("--force", "overwrite an existing config at the target location", false)
+  .option("--manifest-url <url>", "URL of the official plugin manifest to sync plugins against", manifestUrlFromRepo(DEFAULT_REPO_URL))
+  .action(async (authCode: string, options: {
+    configFile?: string, pieceFolder: string, pluginFolder: string, force: boolean, manifestUrl: string,
+  }) => {
+    const configFilePath = options.configFile ? pathResolve(options.configFile) : DEFAULT_MATCH_CONIFG;
+    const existingConfig = (await configExists(configFilePath)) ? await getConfig(configFilePath) : null;
+    if(existingConfig && !options.force){
+      throw new Error(`${configFilePath} already exists - pass --force to overwrite it`);
+    }
+
+    const resolvedFolders = resolveConfigFolders(configFilePath, {
+      pieceFolder: options.pieceFolder, pluginFolder: options.pluginFolder,
+    });
+    await mkdir(resolvedFolders.pieceFolder, { recursive: true });
+    await mkdir(resolvedFolders.pluginFolder, { recursive: true });
+
+    await setConfig(configFilePath, {
+      authCode,
+      pieceFolder: options.pieceFolder,
+      pluginFolder: options.pluginFolder,
+    });
+
+    console.log(`Wrote ${configFilePath}`);
+
+    const { installed, priorityChanges } = await syncPluginsToOfficialManifest(
+      resolvedFolders.pluginFolder, options.manifestUrl
+    );
+    for(const p of installed) console.log(`Installed ${p.package}@${p.version}`);
+    for(const p of priorityChanges) console.log(`Set priority of ${p.package} to ${p.priority}`);
+    console.log(`Plugin sync complete - ${installed.length} plugin(s) installed/updated, ${priorityChanges.length} priority change(s) applied.`);
+  });
+
+program
+  .command("set-auth-code <authCode>")
+  .description("Update the auth code stored in a config file (defaults to the same discovery rules as running the server)")
+  .option(
+    "--config-file <path>",
+    "config file to update (defaults to a config next to this executable, falling back to the home directory)"
+  )
+  .action(async (authCode: string, options: { configFile?: string }) => {
+    const configFilePath = await findConfigFile(options.configFile);
+    const existingConfig = (await configExists(configFilePath)) ? await getConfig(configFilePath) : null;
+    await setConfig(configFilePath, {
+      authCode,
+      pieceFolder: existingConfig?.pieceFolder,
+      pluginFolder: existingConfig?.pluginFolder,
+    });
+    console.log(`Updated auth code in ${configFilePath}`);
+  });
+
+if (require.main === module) {
+  program.parse();
+}
+
+export async function startServer(port: number, authCode: string, pluginFolder: string, piecesFolder: string){
+  const pluginRuntime = await PluginManager.create(pluginFolder);
+  const fileDB = getSQLite3FolderDB(piecesFolder, pluginRuntime);
+
+  const server = new MatchAgentServer();
+  // "{/*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 })=>{
+    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);
+  server.httpRouter.use("/v1", authMiddleware(authCode), v1HttpRouter);
+  server.wsRouter.use("/v1", authMiddleware(authCode), v1WsRouter);
+
+  // Config-editor support lives on its own version axis (/editor/v1) so the
+  // room protocol (/v1) can move to /v2 without dragging the editor API along.
+  server.httpRouter.use("/editor/v1", authMiddleware(authCode), createEditorV1Router(pluginRuntime, fileDB));
+
+  server.listen(port, () => {
+    console.log(`match-agent listening on port ${port}`);
+  });
+}

package/src/server.ts

@@ -0,0 +1,85 @@
+
+import { IncomingMessage, Server } from "http";
+import { WebSocketServer, WebSocket } from 'ws';
+import { Duplex } from "stream";
+import { WebSocketRouter, WSRequest } from "./utils/websocket-router";
+import { HTTPRouter, HTTPError } from "./utils/http-router";
+
+export class MatchAgentServer {
+  private httpServer: Server;
+  private wss: WebSocketServer;
+  public wsRouter = new WebSocketRouter();
+  public httpRouter = new HTTPRouter();
+  constructor(debug = true){
+    this.httpServer = new Server();
+    this.wss = new WebSocketServer({ noServer: true });
+    this.httpServer.on('upgrade', async (request, socket, head)=>{
+      const context = await (async ()=>{
+        try {
+          if(!request.url) throw new Error("No URL");
+          const url = new URL(request.url, "ws://localhost");
+          const ws = await handleUpgrade(this.wss, request, socket, head);
+          return { ws, req: request };
+        }catch(e){
+          console.log("Failed to upgrade connection", e);
+          socket.destroy();
+          throw e;
+        }
+      })()
+      this.wsRouter.handleRequest(context, (err)=>{
+        debug && console.log("WS Error:", err);
+        context.ws.terminate();
+      });
+    });
+    this.httpServer.on('request', (req, res)=>{
+      this.httpRouter.handleRequest({ req, res }, (err: unknown)=>{
+        debug && console.log("HTTP Error:", err);
+        if(res.writableEnded){
+          debug && console.warn("Router threw error and response ended")
+          return;
+        }
+        if(res.headersSent){
+          debug && console.warn("Router threw error and headers already sent")
+          res.destroy();
+          return;
+        }
+        const error: HTTPError = (()=>{
+          if(err instanceof HTTPError) return err;
+          if(!err){
+            return new HTTPError(404, "Not Found");
+          } else if(typeof err === "string"){
+            return new HTTPError(500, err);
+          } else if(err instanceof Error){
+            return new HTTPError(500, err.message);
+          } else if(typeof err !== "object" || err === null || Array.isArray(err)) {
+            return new HTTPError(500, "Unknown Error");
+          }
+          return new HTTPError(
+            "statusCode" in err && typeof err.statusCode === "number" ? err.statusCode : 500,
+            "message" in err && typeof err.message === "string" ? err.message : "Unknown Error"
+          );
+        })();
+
+        res.writeHead(error.statusCode, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+          error: error.message,
+          context: error.context,
+        }));
+      });
+    })
+  }
+  listen(...args: Parameters<Server["listen"]>){
+    return this.httpServer.listen(...args);
+  }
+  close(...args: Parameters<Server["close"]>){
+    return this.httpServer.close(...args);
+  }
+}
+
+function handleUpgrade(wss: WebSocketServer, request: IncomingMessage, socket: Duplex, head: Buffer){
+  return new Promise<WebSocket>((resolve, reject)=>{
+    wss.handleUpgrade(request, socket, head, function done(ws) {
+      resolve(ws);
+    });
+  });
+}

package/src/utils/fs.ts

@@ -0,0 +1,43 @@
+import { readdir, stat as getStat } from "fs/promises";
+import { join as pathJoin, sep as pathSep, extname } from "path";
+import { lookup as mimeLookup } from "mime-types";
+
+// getAssetsOfFiles matches file paths against each asset's glob (e.g.
+// "media/particles.json"), which is relative to the piece folder root -
+// so these must be yielded relative, not absolute.
+export async function* getFilesFromFolder(rootPath: string, relative: string = "./"): AsyncIterable<string> {
+  for(const file of await readdir(pathJoin(rootPath, relative))){
+    const stat = await getStat(pathJoin(rootPath, relative, file));
+    if(stat.isDirectory()){
+      yield* getFilesFromFolder(rootPath, pathJoin(relative, file))
+    } else {
+      yield pathJoin(relative, file).split(pathSep).join("/");
+    }
+  }
+}
+
+// Only extensions in this set get a real mimetype - mime-types resolves
+// its full table (mime-db) against ANY extension, including ones that
+// collide with engine-specific formats (.ts -> video/mp2t, .air -> Adobe
+// AIR installer), so gate lookups to formats we actually intend to serve
+// as their web mimetype. Everything else (.cns, .def, .sff, unknown) is
+// application/octet-stream - the engine reads it as raw bytes regardless.
+const WEB_SAFE_EXTENSIONS = new Set([
+  // images
+  "png", "jpg", "jpeg", "gif", "webp", "avif", "bmp", "ico", "svg",
+  // audio
+  "mp3", "wav", "ogg", "oga", "m4a", "flac", "aac",
+  // video
+  "mp4", "webm", "ogv",
+  // fonts
+  "woff", "woff2", "ttf", "otf",
+  // text/data
+  "json", "txt", "csv", "xml", "html", "css",
+]);
+
+export function mimeTypeFor(filePath: string): string {
+  const ext = extname(filePath).slice(1).toLowerCase();
+  if(!WEB_SAFE_EXTENSIONS.has(ext)) return "application/octet-stream";
+  return mimeLookup(filePath) || "application/octet-stream";
+}
+

package/src/utils/http-router.ts

@@ -0,0 +1,55 @@
+
+import { IncomingMessage, ServerResponse } from "http";
+import { GenericRouter, RouterConfig, GenericRouterCallbackArg, GenericHandlerCallback } from "@roster-lock/utils";
+
+export async function jsonBody(req: IncomingMessage){
+  const data: string = await new Promise((resolve, reject)=>{
+    let data = "";
+    req.on("data", (chunk)=>{data += chunk});
+    req.on("end", ()=>{resolve(data)});
+    req.on("error", reject);
+  })
+  return JSON.parse(data);
+}
+
+export type HTTPRequest = { req: IncomingMessage, res: ServerResponse };
+
+export type HTTPRequestHandler = GenericHandlerCallback<HTTPRequest>;
+
+export class HTTPRouter extends GenericRouter<HTTPRequest> {
+  constructor(config: RouterConfig  = {}){
+    super(
+      (request)=>new URL(request.req.url || "/", "ws://localhost:80"),
+      (request)=>((request.req.method || "GET").toUpperCase()),
+      config
+    );
+  }
+  get(path: string, ...callbacks: Array<GenericRouterCallbackArg<HTTPRequest>>){
+    return this.addHandler("GET", path, false, ...callbacks);
+  }
+  query(path: string, ...callbacks: Array<GenericRouterCallbackArg<HTTPRequest>>){
+    return this.addHandler("QUERY", path, false, ...callbacks);
+  }
+  post(path: string, ...callbacks: Array<GenericRouterCallbackArg<HTTPRequest>>){
+    return this.addHandler("POST", path, false, ...callbacks);
+  }
+  put(path: string, ...callbacks: Array<GenericRouterCallbackArg<HTTPRequest>>){
+    return this.addHandler("PUT", path, false, ...callbacks);
+  }
+  patch(path: string, ...callbacks: Array<GenericRouterCallbackArg<HTTPRequest>>){
+    return this.addHandler("PATCH", path, false, ...callbacks);
+  }
+  delete(path: string, ...callbacks: Array<GenericRouterCallbackArg<HTTPRequest>>){
+    return this.addHandler("DELETE", path, false, ...callbacks);
+  }
+}
+
+export class HTTPError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+    public context?: any,
+  ){
+    super(message);
+  }
+}

package/src/utils/pagination.ts

@@ -0,0 +1,17 @@
+import { HTTPError } from "./http-router";
+
+export function handlePagination(search: URLSearchParams){
+  const page = handleNumber(search, "page", 0);
+  if(page < 0) throw new HTTPError(400, "should be greater than or equal to 0", { key: "page" })
+  const limit = handleNumber(search, "limit", 200);
+  if(limit <= 0) throw new HTTPError(400, "should be greater than or equal to 0", { key: "limit" })
+  return { page, limit }
+}
+
+function handleNumber(search: URLSearchParams, key: string, defaultValue: number){
+  const value = search.get(key);
+  if(value === null) return defaultValue;
+  const numValue = Number.parseInt(value);
+  if(Number.isNaN(numValue)) throw new HTTPError(400, "invalid number", { key });
+  return numValue
+}

package/src/utils/websocket-router.ts

@@ -0,0 +1,23 @@
+
+import { IncomingMessage } from "http";
+import { WebSocket } from "ws";
+import { GenericRouter, RouterConfig, GenericRouterCallbackArg, GenericHandlerCallback } from "@roster-lock/utils";
+
+const WEBSOCKET_METHOD = "WebSocket";
+
+export type WSRequest = { req: IncomingMessage, ws: WebSocket };
+
+export type WebSocketHandlerCallback = GenericHandlerCallback<WSRequest>;
+export class WebSocketRouter extends GenericRouter<WSRequest> {
+  constructor(config: RouterConfig  = {}){
+    super(
+      ({ req })=>new URL(req.url || "/", "ws://localhost:80"),
+      (request)=>WEBSOCKET_METHOD,
+      config
+    );
+  }
+  mount(path: string, ...callbacks: Array<GenericRouterCallbackArg<WSRequest>>){
+    return this.addHandler(WEBSOCKET_METHOD, path, false, ...callbacks);
+  }
+}
+

package/tests/integration/editor-pieces-search.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { startTestServer, TestServer, errorBody } from "./helpers/server";
+import {
+  makeEngine, makePiece, makeTempFolder, seedCompletePiece, cleanupFolder, TEST_PIECE_TYPE,
+} from "./helpers/piece";
+import { RosterLockPiece } from "@roster-lock/types";
+
+type SearchResult = {
+  total: number,
+  items: Array<{
+    piece: (
+      & Pick<RosterLockPiece, "version" | "humanInfo" | "pathVariables">
+      & {
+        engineName: string,
+        pieceType: string,
+        downloadSources: Array<{
+          source: string,
+          lastTest: number | null,
+          success: boolean | null,
+          error?: string,
+        }>,
+      }
+    ),
+    completedAt: number | null,
+  }>,
+};
+
+describe("POST /editor/v1/pieces/search", () => {
+  let server: TestServer;
+  let folder: string;
+
+  beforeEach(async () => {
+    folder = await makeTempFolder();
+    server = await startTestServer(folder);
+  });
+  afterEach(async () => {
+    await server.close();
+    await cleanupFolder(folder);
+  });
+
+  const engine = makeEngine();
+
+  function search(body: unknown) {
+    return fetch(`${server.httpUrl}/editor/v1/pieces/search`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${server.authCode}`,
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  it("400s on a malformed body", async () => {
+    const res = await search({});
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Bad body");
+  });
+
+  it("returns completed pieces with their stored info and tested sources", async () => {
+    const complete = makePiece({ id: "downloaded-piece" });
+    const pending = makePiece({
+      id: "pending-piece",
+      version: { logic: "2.0.0", media: "1.0.0", docs: "1.0.0" },
+    });
+    await seedCompletePiece({
+      folder, engine, pieceType: TEST_PIECE_TYPE, piece: complete, folderName: "a", files: {},
+    });
+    await seedCompletePiece({
+      folder, engine, pieceType: TEST_PIECE_TYPE, piece: pending, folderName: "b", files: {}, complete: false,
+    });
+
+    const res = await search({ engineName: engine.name });
+    expect(res.status).toBe(200);
+    const body = await res.json() as SearchResult;
+    expect(body.total).toBe(1);
+    expect(body.items).toHaveLength(1);
+    // Everything the agent stores round-trips - version hashes, human info,
+    // path variables, and per-source test state.
+    expect(body.items[0].piece).toEqual({
+      engineName: engine.name,
+      pieceType: TEST_PIECE_TYPE,
+      version: complete.version,
+      humanInfo: complete.humanInfo,
+      pathVariables: complete.pathVariables,
+      downloadSources: [{
+        // The seeded download counts as this source's passed test.
+        source: complete.downloadSources[0],
+        lastTest: expect.any(Number),
+        success: true,
+      }],
+    });
+    expect(body.items[0].completedAt).toBeTypeOf("number");
+  });
+
+  it("filters by search text over human info and sources", async () => {
+    const ryu = makePiece({
+      id: "ryu",
+      version: { logic: "ryu-1", media: "1.0.0", docs: "1.0.0" },
+      humanInfo: { name: "Ryu", author: "capcom", url: "http://example.com" },
+    });
+    const ken = makePiece({
+      id: "ken",
+      version: { logic: "ken-1", media: "1.0.0", docs: "1.0.0" },
+      humanInfo: { name: "Ken", author: "capcom", url: "http://example.com" },
+    });
+    await seedCompletePiece({ folder, engine, pieceType: TEST_PIECE_TYPE, piece: ryu, folderName: "a", files: {} });
+    await seedCompletePiece({ folder, engine, pieceType: TEST_PIECE_TYPE, piece: ken, folderName: "b", files: {} });
+
+    const res = await search({ engineName: engine.name, search: "Ryu" });
+    const body = await res.json() as SearchResult;
+    expect(body.total).toBe(1);
+    expect(body.items[0].piece.version.logic).toBe("ryu-1");
+
+    const both = await search({ engineName: engine.name, search: "capcom" });
+    expect((await both.json() as SearchResult).total).toBe(2);
+
+    const bySource = await search({ engineName: engine.name, search: "example.com/download" });
+    expect((await bySource.json() as SearchResult).total).toBe(2);
+  });
+
+  it("paginates and filters by pieceType", async () => {
+    const pieces = ["a", "b", "c"].map((id, i) => makePiece({
+      id, version: { logic: `${id}-1`, media: "1.0.0", docs: "1.0.0" },
+    }));
+    for (const [i, piece] of pieces.entries()) {
+      await seedCompletePiece({
+        folder, engine, pieceType: TEST_PIECE_TYPE, piece, folderName: `folder-${i}`, files: {},
+      });
+    }
+
+    const page0 = await search({
+      engineName: engine.name, pieceType: TEST_PIECE_TYPE, page: 0, limit: 2,
+    });
+    const page0Body = await page0.json() as SearchResult;
+    expect(page0Body.total).toBe(3);
+    expect(page0Body.items).toHaveLength(2);
+
+    const page1 = await search({
+      engineName: engine.name, pieceType: TEST_PIECE_TYPE, page: 1, limit: 2,
+    });
+    expect((await page1.json() as SearchResult).items).toHaveLength(1);
+
+    const otherType = await search({ engineName: engine.name, pieceType: "not-a-type" });
+    expect((await otherType.json() as SearchResult).total).toBe(0);
+  });
+});

package/tests/integration/game-complete.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { startTestServer, TestServer, errorBody } from "./helpers/server";
+import { makeTempFolder, cleanupFolder } from "./helpers/piece";
+import { createFixturePluginDir } from "./helpers/plugin-dir";
+import { makeValidLockConfig, makeValidHeroSelection } from "./helpers/validLockConfig";
+
+describe("POST /v1/game-complete", () => {
+  const cleanups: Array<() => Promise<void> | void> = [];
+  afterEach(async () => {
+    while (cleanups.length) await cleanups.pop()!();
+  });
+
+  function post(server: TestServer, body: unknown) {
+    return fetch(`${server.httpUrl}/v1/game-complete`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${server.authCode}` },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async function makeServer(packageNames: Array<string> = []) {
+    const fixture = await createFixturePluginDir(packageNames);
+    cleanups.push(fixture.cleanup);
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder, undefined, fixture.pluginDir);
+    cleanups.push(() => server.close());
+    return { server, pluginDir: fixture.pluginDir };
+  }
+
+  it("400s on a malformed body", async () => {
+    const { server } = await makeServer();
+    const res = await post(server, {});
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Bad Form");
+  });
+
+  it("400s when lockConfig fails schema validation", async () => {
+    const { server } = await makeServer();
+    const res = await post(server, {
+      lockConfig: { not: "a valid config" }, localUsers: [], userSelections: {}, winners: [],
+    });
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Invalid lockConfig");
+  });
+
+  it("acks with no installed plugins to fan out to", async () => {
+    const { server } = await makeServer();
+    const res = await post(server, {
+      lockConfig: makeValidLockConfig(), localUsers: [], userSelections: {}, winners: [],
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it("fans out to every installed piece-selection-sort plugin, giving each its own dataDir", async () => {
+    const { server, pluginDir } = await makeServer(["@roster-lock/piece-selection-sort-highest-winrate-locally"]);
+
+    const res = await post(server, {
+      lockConfig: makeValidLockConfig(),
+      localUsers: ["pk-a"],
+      userSelections: { "pk-a": makeValidHeroSelection() },
+      winners: ["pk-a"],
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+
+    expect(existsSync(join(pluginDir, "data", "@roster-lock/piece-selection-sort-highest-winrate-locally"))).toBe(true);
+  });
+});