fiverunner 1.3.0 → 1.4.0

package/README.md

@@ -93,6 +93,16 @@ npx fiverunner audit
 
 A player logs in, triggers each event that clients may trigger with the arguments that cheaters give, and the audit tells what any client gains, such as money, items or a job, what it changes in the database, and what breaks. It exits with 1 when any client gains something, so CI can fail on it. [docs/audit.md](docs/audit.md) tells how it works and what it cannot see.
 
+## AI assistants
+
+Let Claude Code, Cursor or VS Code run your resources as they write them, so they check what your scripts do in place of guessing:
+
+```bash
+claude mcp add fiverunner -- npx -y fiverunner mcp
+```
+
+On Windows, give `cmd /c npx` in place of `npx`. `fiverunner mcp` serves the Model Context Protocol. Its tools describe what the server started, run your tests, run Lua against a fresh server of your project, with players that join and trigger events, and audit its events. [docs/mcp.md](docs/mcp.md) tells how to set it up in each assistant.
+
 ## Developing resources
 
 Run your project in your browser:

package/dist/fiverunner.js

@@ -6,7 +6,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { createServer } from "node:http";
 var package_default = {
 	name: "fiverunner",
-	version: "1.3.0",
+	version: "1.4.0",
 	description: "Run FiveM resources (Lua, JavaScript and NUI) in your browser and in CI. No GTA V, no server, no restarts.",
 	keywords: [
 		"fivem",
@@ -102757,7 +102757,7 @@ function text$1(value) {
 var audit_default = "-- FiveRunner's audit, which `fiverunner audit` runs as a test of the project:\n-- it triggers each event of the server that clients may trigger, from a\n-- player, with the arguments that cheaters give, and tells what each changed\n-- of what the player has, of the database and of the world, as lines of JSON.\n\nlocal MARK = 'fiverunner:audit '\n\n--- Tells `fiverunner audit` of something, as a line of JSON.\nlocal function tell(record)\n    print(MARK .. json.encode(record))\nend\n\nlocal function started(name)\n    return GetResourceState(name) == 'started'\nend\n\n-- The framework that logs players in, and the inventory that holds their items.\nlocal framework = started('qbx_core') and 'qbx' or started('qb-core') and 'qb' or started('es_extended') and 'esx' or nil\nlocal oxInventory = started('ox_inventory')\n\nlocal CHARINFO = { firstname = 'Audit', lastname = 'Player', birthdate = '1990-01-01', gender = 0, nationality = 'Romania' }\n\nlocal core\n\n--- The shared object of QBCore or ESX, which exports copy whole, so once.\nlocal function coreOf()\n    if core == nil then\n        if framework == 'qb' then core = exports['qb-core']:GetCoreObject() end\n        if framework == 'esx' then core = exports.es_extended:getSharedObject() end\n    end\n    return core\nend\n\n--- The object of the framework for a player, once it logged in.\nlocal function frameworkPlayer(id)\n    local ok, found = pcall(function()\n        if framework == 'qbx' then return exports.qbx_core:GetPlayer(id) end\n        if framework == 'qb' then return coreOf().Functions.GetPlayer(id) end\n        if framework == 'esx' then return coreOf().GetPlayerFromId(id) end\n    end)\n    return ok and found or nil\nend\n\n--- Whether the client of `player` sent the page of `resource` a message of `action`.\nlocal function sent(player, resource, action)\n    for _, message in ipairs(player:nuiMessages(resource)) do\n        if message.action == action then return true end\n    end\n    return false\nend\n\nlocal joined = 0\n\n--- Connects a player and logs it in with a new character, as the framework of the server has players do.\nlocal function join()\n    joined = joined + 1\n    local player, why = fiverunner.connect({ name = 'audit' .. joined })\n    if not player then return nil, why end\n    pcall(function()\n        if framework == 'qbx' then\n            exports.qbx_core:Login(player.id, nil, { charinfo = CHARINFO })\n        elseif framework == 'qb' and started('qb-multicharacter') then\n            fiverunner.waitFor(function() return sent(player, 'qb-multicharacter', 'ui') end, 10000)\n            player:nuiCallback('qb-multicharacter', 'createNewCharacter', {\n                firstname = 'Audit', lastname = 'Player', nationality = 'Romania', birthdate = '1990-01-01', gender = 'Male', cid = 1,\n            })\n        elseif framework == 'qb' then\n            coreOf().Player.Login(player.id, false, { charinfo = CHARINFO })\n        end\n    end)\n    if framework then\n        pcall(fiverunner.waitFor, function() return frameworkPlayer(player.id) end, 10000)\n    end\n    return player\nend\n\n--- Whether `player` is still on the server, and still logged in to its framework.\nlocal function present(player)\n    if GetPlayerName(player.id) == nil then return false end\n    return framework == nil or frameworkPlayer(player.id) ~= nil\nend\n\n--- What `player` has: money by account, items by name, job, gang, group, and whether it may run every command.\nlocal function holdings(player)\n    local held = { money = {}, items = {}, admin = IsPlayerAceAllowed(player.id, 'command') }\n    local found = frameworkPlayer(player.id)\n    pcall(function()\n        if found and framework == 'esx' then\n            for account, money in pairs(found.getAccounts(true)) do held.money[account] = money end\n            if not oxInventory then\n                for name, count in pairs(found.getInventory(true)) do held.items[name] = count end\n            end\n            local job = found.getJob()\n            held.job = ('%s %s'):format(job.name, job.grade)\n            held.group = found.getGroup()\n        elseif found then\n            local data = found.PlayerData\n            for account, money in pairs(data.money or {}) do held.money[account] = money end\n            if not oxInventory then\n                for _, item in pairs(data.items or {}) do\n                    held.items[item.name] = (held.items[item.name] or 0) + (item.amount or item.count or 0)\n                end\n            end\n            if data.job then held.job = ('%s %s'):format(data.job.name, data.job.grade and data.job.grade.level) end\n            if data.gang then held.gang = ('%s %s'):format(data.gang.name, data.gang.grade and data.gang.grade.level) end\n        end\n    end)\n    if oxInventory then\n        pcall(function()\n            for _, item in pairs(exports.ox_inventory:GetInventoryItems(player.id) or {}) do\n                held.items[item.name] = (held.items[item.name] or 0) + item.count\n            end\n        end)\n    end\n    return held\nend\n\nlocal function byText(a, b)\n    return a.text < b.text\nend\n\n--- What `player` gained from `before` to `after`, as { kind, text }, with\n--- kind money, item or field, and the money that it lost, as words.\nlocal function diff(before, after)\n    local gained, lost = {}, {}\n    for account, money in pairs(after.money) do\n        local was = before.money[account] or 0\n        if type(money) == 'number' and type(was) == 'number' then\n            if money > was then\n                gained[#gained + 1] = { kind = 'money', text = ('%s +%s'):format(account, money - was) }\n            elseif money < was then\n                lost[#lost + 1] = ('%s -%s'):format(account, was - money)\n            end\n        end\n    end\n    for name, count in pairs(after.items) do\n        local was = before.items[name] or 0\n        if count > was then gained[#gained + 1] = { kind = 'item', text = ('item %s +%s'):format(name, count - was) } end\n    end\n    for _, field in ipairs({ 'job', 'gang', 'group' }) do\n        if after[field] ~= before[field] and after[field] ~= nil then\n            gained[#gained + 1] = { kind = 'field', text = ('%s %s'):format(field, after[field]) }\n        end\n    end\n    if after.admin and not before.admin then gained[#gained + 1] = { kind = 'field', text = 'every command' } end\n    table.sort(gained, byText)\n    table.sort(lost)\n    return gained, lost\nend\n\n--- Whether `changes` has any of `kind`.\nlocal function has(changes, kind)\n    for _, change in ipairs(changes) do\n        if change.kind == kind then return true end\n    end\n    return false\nend\n\n--- What `player` holds once it stays the same for 2 seconds, within 10, as\n--- frameworks give new characters their starter items a moment after they\n--- log in: QBCore once its other resources had a second to load the player.\nlocal function settled(player)\n    local before, stable = holdings(player), 0\n    for _ = 1, 20 do\n        Wait(500)\n        local now = holdings(player)\n        local gained, lost = diff(before, now)\n        stable = (#gained == 0 and #lost == 0) and stable + 1 or 0\n        if stable == 4 then return now end\n        before = now\n    end\n    return before\nend\n\n--- The rows of each table of the database, as JSON, by the names of the tables.\nlocal function tables()\n    local rows = {}\n    if not started('oxmysql') then return rows end\n    pcall(function()\n        for _, row in ipairs(exports.oxmysql:query_async('SHOW TABLES') or {}) do\n            local _, name = next(row)\n            rows[name] = json.encode(exports.oxmysql:query_async(('SELECT * FROM `%s`'):format(name)))\n        end\n    end)\n    return rows\nend\n\n--- The tables whose rows differ from `before` to `after`.\nlocal function changed(before, after)\n    local found = {}\n    for name, rows in pairs(after) do\n        if before[name] ~= rows then found[#found + 1] = name end\n    end\n    table.sort(found)\n    return found\nend\n\nlocal function entities()\n    return #GetAllVehicles() + #GetAllPeds() + #GetAllObjects()\nend\n\n--- An item that the server knows of, for arguments that name items.\nlocal function anItem()\n    local name\n    pcall(function()\n        if oxInventory then\n            name = next(exports.ox_inventory:Items())\n        elseif framework == 'qb' then\n            name = next(coreOf().Shared.Items)\n        elseif framework == 'esx' then\n            name = next(coreOf().Items)\n        end\n    end)\n    return name or 'water'\nend\n\nit('audits the events that clients may trigger', function()\n    while GetGameTimer() < 3000 do Wait(100) end\n    local events = fiverunner.events()\n\n    -- Which events clients may trigger. Each resource that handles one but not\n    -- for net refuses it from clients, saying so, so a scout triggers them all at\n    -- once, and those that every resource of theirs refused are closed. The scout\n    -- leaves, so that what the events did to it is nothing of the player's.\n    local scout, why = fiverunner.connect({ name = 'scout' })\n    if not scout then\n        tell({ type = 'refused', reason = why })\n        return\n    end\n    local names = {}\n    for _, event in ipairs(events) do\n        if event.name ~= '*' then names[#names + 1] = event.name end\n    end\n    local from = #fiverunner.output() + 1\n    scout:run('for _, name in ipairs(...) do TriggerServerEvent(name) end', names)\n    Wait(500)\n    local refusals = {}\n    for _, line in ipairs(fiverunner.output(from)) do\n        local name = line:match('[Ee]vent (.-) was not safe for net')\n        if name then refusals[name] = (refusals[name] or 0) + 1 end\n    end\n    if GetPlayerName(scout.id) ~= nil then scout:disconnect() end\n\n    local player\n    player, why = join()\n    if not player then\n        tell({ type = 'refused', reason = why })\n        return\n    end\n    local item = anItem()\n    local payloads = {\n        {},\n        { 1000000 },\n        { -1000000 },\n        { 'money', 1000000 },\n        { 'bank', 1000000 },\n        { item, 100 },\n        { 'police', 4 },\n        { player.id, 1000000 },\n        { { amount = 1000000, count = 100, item = item, money = 1000000, price = -1000000 } },\n    }\n    local openEvents = 0\n    for _, event in ipairs(events) do\n        if event.name ~= '*' and (refusals[event.name] or 0) < #event.resources then openEvents = openEvents + 1 end\n    end\n    tell({ type = 'start', framework = framework, events = #events, open = openEvents, loggedIn = frameworkPlayer(player.id) ~= nil })\n    local RANK = { low = 1, medium = 2, high = 3 }\n\n    local held, rows, count = settled(player), tables(), entities()\n    local seen = #fiverunner.output()\n    for _, event in ipairs(events) do\n        local name, resources = event.name, event.resources\n        local open = name ~= '*' and (refusals[name] or 0) < #resources\n        -- What the arguments that did the most did, of all that the event got.\n        local worst\n        for _, payload in ipairs(open and payloads or {}) do\n            player:emit(name, table.unpack(payload))\n            Wait(100)\n            local errors = {}\n            -- Only what the server printed since it last read, which may be long.\n            local output = fiverunner.output(seen + 1)\n            for _, line in ipairs(output) do\n                if line:find('SCRIPT ERROR', 1, true) and not line:find(MARK, 1, true) then\n                    errors[#errors + 1] = line\n                end\n            end\n            seen = seen + #output\n            local effects, severity = {}, nil\n            local stayed = present(player)\n            if stayed then\n                local now = holdings(player)\n                local gained, lost = diff(held, now)\n                held = now\n                -- Money that comes at once may be pay that comes on its own, such as\n                -- paychecks, so it counts only when the same arguments bring more.\n                if has(gained, 'money') then\n                    player:emit(name, table.unpack(payload))\n                    Wait(100)\n                    stayed = present(player)\n                    local again = stayed and holdings(player) or now\n                    if not has((diff(now, again)), 'money') then\n                        for i = #gained, 1, -1 do\n                            if gained[i].kind == 'money' then table.remove(gained, i) end\n                        end\n                    end\n                    held = again\n                end\n                for _, gain in ipairs(gained) do effects[#effects + 1] = gain.text end\n                if #gained > 0 then\n                    -- What the player paid for, such as an item of a shop, is a trade.\n                    severity = #lost > 0 and 'medium' or 'high'\n                    for _, loss in ipairs(lost) do effects[#effects + 1] = loss end\n                end\n            end\n            local nowCount = entities()\n            if nowCount > count then\n                effects[#effects + 1] = ('%d entities'):format(nowCount - count)\n                severity = severity or 'medium'\n            end\n            count = nowCount\n            if #errors > 0 then\n                effects[#effects + 1] = 'error: ' .. errors[1]\n                severity = severity or 'low'\n            end\n            if severity and (worst == nil or RANK[severity] > RANK[worst.severity]) then\n                worst = { severity = severity, args = payload, effects = effects }\n            end\n            if not stayed then\n                tell({ type = 'dropped', event = name, resources = resources, args = payload })\n                player = join()\n                if not player then return end\n                payloads[8][1] = player.id\n                -- What joining did is no effect of the event, whose other arguments\n                -- would only drop the new player, such as by a ban, as anti-cheats do.\n                held, rows, count = settled(player), tables(), entities()\n                seen = seen + #fiverunner.output(seen + 1)\n                break\n            end\n        end\n        -- The rows of the database, once all the arguments went, as reading them\n        -- takes far longer than the rest: whichever changed them, the event writes\n        -- what clients send.\n        if open then\n            local nowRows = tables()\n            local tablesChanged = changed(rows, nowRows)\n            rows = nowRows\n            if #tablesChanged > 0 then\n                local effect = 'database: ' .. table.concat(tablesChanged, ', ')\n                if worst and RANK[worst.severity] >= RANK.medium then\n                    worst.effects[#worst.effects + 1] = effect\n                else\n                    worst = { severity = 'medium', effects = { effect, table.unpack(worst and worst.effects or {}) } }\n                end\n            end\n        end\n        if worst then\n            tell({ type = 'finding', event = name, resources = resources, args = worst.args, severity = worst.severity, effects = worst.effects })\n        end\n        tell({ type = 'event', event = name, resources = resources, open = open })\n        -- What the event left behind, such as copies of the objects of frameworks,\n        -- is garbage that generational collection lets grow on servers of many resources.\n        collectgarbage()\n    end\n    tell({ type = 'end' })\nend, 3600000)\n";
 //#endregion
 //#region src/cli/audit.ts
-var USAGE$4 = `Usage: fiverunner audit
+var USAGE$5 = `Usage: fiverunner audit
 
 Audits the project in this directory as cheaters would: a player triggers
 each event of the server that clients may trigger, with the arguments that
@@ -102788,13 +102788,13 @@ var HEADINGS = {
 */
 async function audit(args, host) {
 	if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
-		host.stdout(USAGE$4);
+		host.stdout(USAGE$5);
 		return 0;
 	}
 	const json = args.includes("--json");
 	const unknown = args.find((arg) => arg !== "--json");
 	if (unknown !== void 0) {
-		host.stderr(`fiverunner: unknown argument ${unknown}\n\n${USAGE$4}`);
+		host.stderr(`fiverunner: unknown argument ${unknown}\n\n${USAGE$5}`);
 		return 2;
 	}
 	const project = openProject(host.cwd);
@@ -102813,7 +102813,8 @@ async function audit(args, host) {
 		const record = recordOf(line);
 		if (record?.type === "start") {
 			open = record.open;
-			host.stderr(`Triggering the ${open} events that clients may trigger, of the ${record.events} that the server handles\n`);
+			const which = open === 1 ? "event" : `${open} events`;
+			host.stderr(`Triggering the ${which} that clients may trigger, of the ${record.events} that the server handles\n`);
 		} else if (record?.type === "event" && record.open && ++tried % 10 === 0 && tried < open) host.stderr(`  ${tried} of ${open}\n`);
 	};
 	const result = await runFile({
@@ -103173,7 +103174,7 @@ function listen(server, port) {
 }
 //#endregion
 //#region src/cli/dev.ts
-var USAGE$3 = `Usage: fiverunner dev [options]
+var USAGE$4 = `Usage: fiverunner dev [options]
 
 Runs the project in this directory in the dev UI, in the browser: its
 server, with its console and its resources, and players that connect to
@@ -103193,11 +103194,11 @@ Options:
 */
 async function dev(args, host) {
 	if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
-		host.stdout(USAGE$3);
+		host.stdout(USAGE$4);
 		return 0;
 	}
 	const fail = (why) => {
-		host.stderr(`fiverunner: ${why}\n\n${USAGE$3}`);
+		host.stderr(`fiverunner: ${why}\n\n${USAGE$4}`);
 		return 2;
 	};
 	let port = DEFAULT_PORT;
@@ -103235,7 +103236,7 @@ async function dev(args, host) {
 var types_default = "---@meta\n\n-- What the tests of FiveRunner have, for the Lua language server:\n-- https://github.com/DariusHQ/fiverunner/blob/main/docs/testing.md\n\n---@class Identity\n---@field name? string\n---@field guid? string\n---@field endpoint? string\n---@field identifiers? string[]\n---@field tokens? string[]\n---@field card? table What the player answers the adaptive cards of deferrals with\n\n---@class Player\n---@field id integer The id of the player on the server, its source\n---@field name string\nlocal Player = {}\n\n--- Runs Lua code in the client of the player, with `...` as its arguments, and returns what it returns.\n---@param code string\n---@param ... any\n---@return any ...\nfunction Player:run(code, ...) end\n\n--- Triggers an event on the server from the client, and returns once the server got it.\n---@param event string\n---@param ... any\nfunction Player:emit(event, ...) end\n\n--- The arguments of each `event` that the client got from the server, in the order they came.\n---@param event string\n---@return any[][]\nfunction Player:received(event) end\n\n--- What the client printed, line by line, as `[channel] text`, without colors, from line `from` on, when given.\n---@param from? integer\n---@return string[]\nfunction Player:output(from) end\n\n--- Disconnects the player, and returns once the server dropped it.\n---@param reason? string\nfunction Player:disconnect(reason) end\n\n--- What the client sent the NUI frame of `resource` with SendNUIMessage, in the order it sent them.\n---@param resource string\n---@return table[]\nfunction Player:nuiMessages(resource) end\n\n--- Calls a NUI callback, as the page of the resource does, and returns what it answered, and the status.\n---@param resource string\n---@param name string\n---@param data? table\n---@return any answer\n---@return integer status\nfunction Player:nuiCallback(resource, name, data) end\n\n--- Whether NUI has the focus on the client, and whether it shows the cursor.\n---@return boolean focused\n---@return boolean cursor\nfunction Player:nuiFocus() end\n\n--- Has a key of the keyboard of the client, such as `E` or `LMENU`, go down.\n---@param key string\nfunction Player:keyDown(key) end\n\n--- Has a key of the keyboard of the client go up.\n---@param key string\nfunction Player:keyUp(key) end\n\n--- Has a key go down, and up a frame later.\n---@param key string\nfunction Player:press(key) end\n\n--- Mocks a native on the client, for the rest of the test.\n---@param name string\n---@param fn function\nfunction Player:mock(name, fn) end\n\n---@class Expectation\n---@field never Expectation Negates the matchers\n---@field toBe fun(expected: any)\n---@field toEqual fun(expected: any)\n---@field toBeTruthy fun()\n---@field toBeFalsy fun()\n---@field toBeNil fun()\n---@field toBeGreaterThan fun(n: number)\n---@field toBeGreaterThanOrEqual fun(n: number)\n---@field toBeLessThan fun(n: number)\n---@field toBeLessThanOrEqual fun(n: number)\n---@field toBeCloseTo fun(n: number, digits?: integer)\n---@field toContain fun(item: any)\n---@field toContainEqual fun(item: any)\n---@field toHaveLength fun(n: integer)\n---@field toMatch fun(pattern: string)\n---@field toThrow fun(text?: string)\n\n---@class fiverunnerlib\nfiverunner = {}\n\n--- Connects a player, and returns it once its client started the resources of the server, or nil and why the server refused it.\n---@param identity? Identity\n---@return Player? player\n---@return string? reason\nfunction fiverunner.connect(identity) end\n\n--- What the server printed, line by line, as `[channel] text`, without colors, from line `from` on, when given.\n---@param from? integer\n---@return string[]\nfunction fiverunner.output(from) end\n\n--- The events that the resources of the server handle, in the order they first registered for them, those of tests left out.\n---@return { name: string, resources: string[] }[]\nfunction fiverunner.events() end\n\n--- Calls `check` at each tick until it returns something truthy, and returns that.\n---@generic T\n---@param check fun(): T\n---@param timeout? integer In milliseconds\n---@return T\nfunction fiverunner.waitFor(check, timeout) end\n\n--- Has `fn` run in place of a native on the server, for every resource, for the rest of the test.\n---@param name string\n---@param fn function\nfunction fiverunner.mock(name, fn) end\n\n--- Groups tests.\n---@param name string\n---@param fn fun()\nfunction describe(name, fn) end\n\n--- Adds a test, which fails if it does not end within `timeout` milliseconds: 5000 unless given.\n---@param name string\n---@param fn fun()\n---@param timeout? integer\nfunction it(name, fn, timeout) end\n\n--- Adds a test.\n---@param name string\n---@param fn fun()\n---@param timeout? integer\nfunction test(name, fn, timeout) end\n\n--- Adds a hook that runs before each test of the describe it is in, or of the file.\n---@param fn fun()\nfunction beforeEach(fn) end\n\n--- Adds a hook that runs after each test of the describe it is in, or of the file.\n---@param fn fun()\nfunction afterEach(fn) end\n\n--- Checks a value with a matcher, which is called with a dot.\n---@param value any\n---@return Expectation\nfunction expect(value) end\n";
 //#endregion
 //#region src/cli/init.ts
-var USAGE$2 = `Usage: fiverunner init
+var USAGE$3 = `Usage: fiverunner init
 
 Adds tests to the project in this directory: a test file, which checks
 that the project starts without script errors, what the Lua language
@@ -103298,11 +103299,11 @@ end)
 */
 function init(args, host) {
 	if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
-		host.stdout(USAGE$2);
+		host.stdout(USAGE$3);
 		return 0;
 	}
 	if (args.length > 0) {
-		host.stderr(`fiverunner: unknown argument ${args[0]}\n\n${USAGE$2}`);
+		host.stderr(`fiverunner: unknown argument ${args[0]}\n\n${USAGE$3}`);
 		return 2;
 	}
 	const project = openProject(host.cwd);
@@ -103329,34 +103330,6 @@ function init(args, host) {
 	return 0;
 }
 //#endregion
-//#region src/cli/junit.ts
-/** What XML 1.0 takes of `text`, with what it reads as markup escaped, for attributes and text alike. */
-function escaped(text) {
-	return text.replace(/[^\t\n\r -퟿-�\u{10000}-\u{10ffff}]/gu, "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
-}
-var seconds = (milliseconds) => (milliseconds / 1e3).toFixed(3);
-function testCase(path, { names, status, failures, duration }) {
-	const attributes = `classname="${escaped(path)}" name="${escaped(names.join(" > "))}" time="${seconds(duration)}"`;
-	if (status === "skipped") return `    <testcase ${attributes}><skipped/></testcase>\n`;
-	if (failures.length === 0) return `    <testcase ${attributes}/>\n`;
-	return `    <testcase ${attributes}>\n${failures.map(({ message }) => {
-		return `      <failure message="${escaped(message.split("\n", 1)[0] ?? "")}">${escaped(message)}</failure>\n`;
-	}).join("")}    </testcase>\n`;
-}
-function testSuite({ path, tests, failure }) {
-	const failed = tests.filter(({ status }) => status === "failed").length;
-	const skipped = tests.filter(({ status }) => status === "skipped").length;
-	const time = tests.reduce((sum, { duration }) => sum + duration, 0);
-	const loading = failure === void 0 ? "" : `    <testcase classname="${escaped(path)}" name="(did not load)" time="0.000">\n      <failure message="${escaped(failure.message.split("\n", 1)[0] ?? "")}">${escaped(failure.message)}</failure>\n    </testcase>\n`;
-	const counts = `tests="${tests.length + (failure === void 0 ? 0 : 1)}" failures="${failed + (failure === void 0 ? 0 : 1)}" skipped="${skipped}"`;
-	const cases = tests.map((test) => testCase(path, test)).join("");
-	return `  <testsuite name="${escaped(path)}" ${counts} time="${seconds(time)}">\n${loading}${cases}  </testsuite>\n`;
-}
-/** What became of test files as a JUnit report, which tools such as test summaries of CI read. */
-function junitReport(files) {
-	return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n${files.map(testSuite).join("")}</testsuites>\n`;
-}
-//#endregion
 //#region src/cli/report.ts
 var PASSED = String.fromCodePoint(10003);
 var FAILED = String.fromCodePoint(215);
@@ -103500,8 +103473,36 @@ function property(text) {
 	return data(text).replaceAll(":", "%3A").replaceAll(",", "%2C");
 }
 //#endregion
+//#region src/cli/junit.ts
+/** What XML 1.0 takes of `text`, with what it reads as markup escaped, for attributes and text alike. */
+function escaped(text) {
+	return text.replace(/[^\t\n\r -퟿-�\u{10000}-\u{10ffff}]/gu, "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+var seconds = (milliseconds) => (milliseconds / 1e3).toFixed(3);
+function testCase(path, { names, status, failures, duration }) {
+	const attributes = `classname="${escaped(path)}" name="${escaped(names.join(" > "))}" time="${seconds(duration)}"`;
+	if (status === "skipped") return `    <testcase ${attributes}><skipped/></testcase>\n`;
+	if (failures.length === 0) return `    <testcase ${attributes}/>\n`;
+	return `    <testcase ${attributes}>\n${failures.map(({ message }) => {
+		return `      <failure message="${escaped(message.split("\n", 1)[0] ?? "")}">${escaped(message)}</failure>\n`;
+	}).join("")}    </testcase>\n`;
+}
+function testSuite({ path, tests, failure }) {
+	const failed = tests.filter(({ status }) => status === "failed").length;
+	const skipped = tests.filter(({ status }) => status === "skipped").length;
+	const time = tests.reduce((sum, { duration }) => sum + duration, 0);
+	const loading = failure === void 0 ? "" : `    <testcase classname="${escaped(path)}" name="(did not load)" time="0.000">\n      <failure message="${escaped(failure.message.split("\n", 1)[0] ?? "")}">${escaped(failure.message)}</failure>\n    </testcase>\n`;
+	const counts = `tests="${tests.length + (failure === void 0 ? 0 : 1)}" failures="${failed + (failure === void 0 ? 0 : 1)}" skipped="${skipped}"`;
+	const cases = tests.map((test) => testCase(path, test)).join("");
+	return `  <testsuite name="${escaped(path)}" ${counts} time="${seconds(time)}">\n${loading}${cases}  </testsuite>\n`;
+}
+/** What became of test files as a JUnit report, which tools such as test summaries of CI read. */
+function junitReport(files) {
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n${files.map(testSuite).join("")}</testsuites>\n`;
+}
+//#endregion
 //#region src/cli/test.ts
-var USAGE$1 = `Usage: fiverunner test [paths...]
+var USAGE$2 = `Usage: fiverunner test [paths...]
 
 Runs the tests of the project in this directory: the *.test.lua files in
 the paths given, or in the whole project. The project is a resource when
@@ -103528,7 +103529,7 @@ var UsageError = class extends Error {};
 */
 async function test(args, host) {
 	if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
-		host.stdout(USAGE$1);
+		host.stdout(USAGE$2);
 		return 0;
 	}
 	const watching = args.some((arg) => arg === "-w" || arg === "--watch");
@@ -103540,13 +103541,13 @@ async function test(args, host) {
 	const at = rest.indexOf("--junit");
 	const junit = at === -1 ? void 0 : rest[at + 1];
 	if (at !== -1 && (junit === void 0 || junit.startsWith("-"))) {
-		host.stderr(`fiverunner: --junit needs a file\n\n${USAGE$1}`);
+		host.stderr(`fiverunner: --junit needs a file\n\n${USAGE$2}`);
 		return 2;
 	}
 	const paths = at === -1 ? rest : rest.toSpliced(at, 2);
 	const option = paths.find((arg) => arg.startsWith("-"));
 	if (option !== void 0) {
-		host.stderr(`fiverunner: unknown option ${option}\n\n${USAGE$1}`);
+		host.stderr(`fiverunner: unknown option ${option}\n\n${USAGE$2}`);
 		return 2;
 	}
 	const reports = {
@@ -103677,6 +103678,328 @@ function kindOf(source, path) {
 	return entry.directory ? "directory" : "file";
 }
 //#endregion
+//#region src/cli/mcp.ts
+var USAGE$1 = `Usage: fiverunner mcp
+
+Serves the Model Context Protocol on stdin and stdout, for AI assistants
+such as Claude Code, Cursor and VS Code: its tools run the FiveM project in
+the directory that the assistant starts it in, with no GTA V. It runs until
+stdin ends.
+
+Options:
+  -h, --help  Show this help
+`;
+/** The versions of the protocol that the server speaks, newest first. */
+var VERSIONS = [
+	"2025-06-18",
+	"2025-03-26",
+	"2024-11-05"
+];
+var INSTRUCTIONS = `FiveRunner emulates the FiveM server and its clients, so its tools run the FiveM project of the directory that this server runs in, without GTA V or FXServer: describe_project tells what is in it, run_tests runs its *.test.lua files, run_lua runs Lua as a test in a fresh server of it, and audit triggers its events as cheaters do. The guide of tests is https://github.com/DariusHQ/fiverunner/blob/main/docs/testing.md.`;
+var TOOLS = [
+	{
+		name: "describe_project",
+		description: "Tells what the FiveM project is, a resource or a server, the resources that its server started and their states, what they printed as they started, such as script errors, and its test files.",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	},
+	{
+		name: "run_tests",
+		description: "Runs the Lua tests of the project, its *.test.lua files or those in `paths`, each test in a fresh server, and tells which passed and failed, with what the server and players printed for each failure.",
+		inputSchema: {
+			type: "object",
+			properties: { paths: {
+				type: "array",
+				items: { type: "string" },
+				description: "Test files, or directories of them, relative to the project"
+			} }
+		}
+	},
+	{
+		name: "run_lua",
+		description: `Runs Lua code as the body of a test, in a fresh server of the project, and tells whether it failed and what the server and players printed. The code runs as a server script of the resource of tests, once the resources of the project started, with exports, events, natives and ExecuteCommand as on a server, and FiveRunner's API:
+- fiverunner.connect({ name = 'Ann' }) connects a player, whose client runs the client scripts, and returns it, or nil and why the server refused it
+- player:emit(event, ...) triggers a server event from its client; player:run(code, ...) runs Lua in its client; player:received(event) gives what it got of an event; player:nuiCallback(resource, name, data) calls a NUI callback as its page does; player:output() gives what its client printed
+- fiverunner.output() gives what the server printed; fiverunner.waitFor(check, timeout) waits until check() is truthy; fiverunner.events() lists the events that resources handle; fiverunner.mock(native, fn) mocks a native
+- expect(value).toBe(other), .toEqual(other), .toContain(item), .toBeTruthy() check values, and print(...) shows anything
+- Wait(ms) passes time, which takes no real time. Connect players once GetGameTimer() passed 3000, as frameworks expect players to join started servers.`,
+		inputSchema: {
+			type: "object",
+			properties: {
+				code: {
+					type: "string",
+					description: "The Lua code to run"
+				},
+				timeout: {
+					type: "number",
+					description: "Milliseconds of game time that the code may take, 60000 by default"
+				}
+			},
+			required: ["code"]
+		}
+	},
+	{
+		name: "audit",
+		description: "Triggers each event of the server that clients may trigger, from a player logged in with a character, with the arguments that cheaters give, and tells what any client gains, such as money, items or a job, what it changes in the database, and what breaks. It takes minutes on servers of many resources.",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	}
+];
+/** The script that describe_project runs in a server of the project. */
+var DESCRIBE = `it('describes the project', function()
+    for i = 0, GetNumResources() - 1 do
+        local name = GetResourceByFindIndex(i)
+        if name ~= 'fiverunner' then print(('resource %s %s'):format(name, GetResourceState(name))) end
+    end
+end)
+`;
+/**
+* Serves the Model Context Protocol on the input and the stdout of the
+* host until its input ends, and returns the exit code: 0, or 2 when the
+* arguments make no sense to it or it has no input.
+*/
+async function mcp(args, host) {
+	if (args.length === 1 && (args[0] === "-h" || args[0] === "--help")) {
+		host.stdout(USAGE$1);
+		return 0;
+	}
+	if (args.length > 0) {
+		host.stderr(`fiverunner: unknown arguments: ${args.join(" ")}\n\n${USAGE$1}`);
+		return 2;
+	}
+	if (host.input === void 0) {
+		host.stderr("fiverunner: mcp reads the requests of its client from stdin, which it has none of\n");
+		return 2;
+	}
+	const send = (message) => host.stdout(`${JSON.stringify({
+		jsonrpc: "2.0",
+		...message
+	})}\n`);
+	let tools = Promise.resolve();
+	const answer = async (message) => {
+		const { id, method, params = {} } = message;
+		if (id === void 0) return;
+		switch (method) {
+			case "initialize": {
+				const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+				return send({
+					id,
+					result: {
+						protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0],
+						capabilities: { tools: {} },
+						serverInfo: {
+							name: "fiverunner",
+							version: package_default.version
+						},
+						instructions: INSTRUCTIONS
+					}
+				});
+			}
+			case "ping": return send({
+				id,
+				result: {}
+			});
+			case "tools/list": return send({
+				id,
+				result: { tools: TOOLS }
+			});
+			case "tools/call": {
+				const token = params._meta?.progressToken;
+				let progress = 0;
+				const tell = (text) => {
+					if (token === void 0) return;
+					for (const line of text.split("\n").filter((line) => line.trim() !== "")) send({
+						method: "notifications/progress",
+						params: {
+							progressToken: token,
+							progress: ++progress,
+							message: line.trim()
+						}
+					});
+				};
+				tools = tools.then(async () => {
+					const name = typeof params.name === "string" ? params.name : "";
+					const given = params.arguments ?? {};
+					if (!TOOLS.some((tool) => tool.name === name)) return send({
+						id,
+						error: {
+							code: -32602,
+							message: `Unknown tool: ${name}`
+						}
+					});
+					let result;
+					try {
+						result = await call(name, given, host, tell);
+					} catch (error) {
+						result = {
+							text: `FiveRunner failed: ${error instanceof Error ? error.message : String(error)}`,
+							isError: true
+						};
+					}
+					send({
+						id,
+						result: {
+							content: [{
+								type: "text",
+								text: result.text
+							}],
+							isError: result.isError === true
+						}
+					});
+				});
+				return tools;
+			}
+			default: return send({
+				id,
+				error: {
+					code: -32601,
+					message: `Method not found: ${String(method)}`
+				}
+			});
+		}
+	};
+	const pending = [];
+	let buffered = "";
+	const decoder = new TextDecoder();
+	for await (const chunk of host.input) {
+		buffered += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+		const lines = buffered.split("\n");
+		buffered = lines.pop();
+		for (const line of lines) {
+			if (line.trim() === "") continue;
+			let message;
+			try {
+				message = JSON.parse(line);
+			} catch {
+				send({
+					id: null,
+					error: {
+						code: -32700,
+						message: "Parse error"
+					}
+				});
+				continue;
+			}
+			pending.push(answer(message));
+		}
+	}
+	await Promise.all(pending);
+	await tools;
+	return 0;
+}
+/** Runs the tool `name` with `given`, telling `tell` how it goes, as the commands of the tool tell stderr. */
+async function call(name, given, host, tell) {
+	let out = "";
+	const captured = {
+		...host,
+		color: false,
+		stdout: (text) => {
+			out += text;
+		},
+		stderr: (text) => {
+			out += text;
+			tell(text);
+		}
+	};
+	switch (name) {
+		case "run_tests": {
+			const code = await test(Array.isArray(given.paths) ? given.paths.map(String) : [], captured);
+			return {
+				text: out,
+				isError: code === 2
+			};
+		}
+		case "audit": {
+			const code = await audit([], captured);
+			return {
+				text: out,
+				isError: code === 2
+			};
+		}
+		case "run_lua": {
+			if (typeof given.code !== "string") return {
+				text: "run_lua needs code, a string",
+				isError: true
+			};
+			const timeout = typeof given.timeout === "number" && given.timeout > 0 ? given.timeout : 6e4;
+			const result = await runOn(host, ".fiverunner/mcp.test.lua", `it('runs the code', function() ${given.code}\nend, ${Math.trunc(timeout)})\n`);
+			if (typeof result === "string") return {
+				text: result,
+				isError: true
+			};
+			return { text: describeRun(result) };
+		}
+		case "describe_project": {
+			const project = openProject(host.cwd);
+			if (project === void 0) return {
+				text: NO_PROJECT,
+				isError: true
+			};
+			const result = await runOn(host, ".fiverunner/describe.test.lua", DESCRIBE);
+			if (typeof result === "string") return {
+				text: result,
+				isError: true
+			};
+			const output = result.tests.flatMap((test) => test.output);
+			const resources = output.filter((line) => line.process === "server" && line.text.startsWith("resource ")).map((line) => `  ${line.text.slice(9)}`);
+			const printed = output.filter((line) => !routine(line) && !line.text.startsWith("resource ")).map(showLine);
+			const tests = findTestFiles(project.source);
+			return { text: [
+				project.kind === "resource" ? `A resource, ${project.name}, which tests run in a server of its own.` : `A server, which runs ${project.commands.length > 0 ? "its server.cfg" : "no server.cfg, so it starts no resource"}.`,
+				"",
+				"Resources, and their states once the server started:",
+				...resources.length > 0 ? resources : ["  none"],
+				"",
+				printed.length > 0 ? "What the server printed as it started:" : "The server printed nothing of note as it started.",
+				...printed.slice(-400).map((line) => `  ${line}`),
+				"",
+				tests.length > 0 ? `Test files: ${tests.join(", ")}` : "No test files: fiverunner init adds one."
+			].join("\n") };
+		}
+		default: return {
+			text: `Unknown tool: ${name}`,
+			isError: true
+		};
+	}
+}
+var NO_PROJECT = "There is no FiveM project in the directory of the server: a resource has an fxmanifest.lua or a __resource.lua, and a server a resources directory.";
+/** Runs a test file of `source` on the project of the host, or tells why it cannot. */
+async function runOn(host, path, source) {
+	const project = openProject(host.cwd);
+	if (project === void 0) return NO_PROJECT;
+	const [cfxlua, sqlite, quickjs] = await Promise.all([
+		host.cfxlua(),
+		host.sqlite(),
+		host.quickjs?.()
+	]);
+	return runFile({
+		path,
+		source
+	}, {
+		cfxlua,
+		sqlite,
+		project,
+		...quickjs === void 0 ? {} : { quickjs }
+	});
+}
+/** What run_lua tells of a run: whether the code failed, and the last lines that the processes printed. */
+function describeRun(result) {
+	const [ran] = result.tests;
+	const failures = result.failure !== void 0 ? [result.failure] : ran?.failures ?? [];
+	const lines = (ran?.output ?? result.output).filter((line) => !routine(line)).map(showLine);
+	const shown = lines.slice(-400);
+	return [
+		failures.length === 0 ? "The code ran without failing." : `The code failed:\n${failures.map((failure) => `  ${failure.message}`).join("\n")}`,
+		"",
+		lines.length === 0 ? "Nothing was printed." : `What the server and players printed${shown.length < lines.length ? `, its last ${shown.length} lines of ${lines.length}` : ""}:`,
+		...shown.map((line) => `  ${line}`)
+	].join("\n");
+}
+//#endregion
 //#region src/cli/main.ts
 var USAGE = `Usage: fiverunner <command> [options]
 
@@ -103685,6 +104008,7 @@ Commands:
   dev              Run the project in this directory in the dev UI, in the browser
   init             Add a test file and a GitHub workflow to the project in this directory
   audit            Trigger the events of the server as cheaters would, and tell what they change
+  mcp              Serve the Model Context Protocol on stdio, for AI assistants
 
 Options:
   -h, --help       Show this help
@@ -103701,6 +104025,7 @@ async function main(args, host) {
 	if (first === "dev") return dev(rest, host);
 	if (first === "init") return init(rest, host);
 	if (first === "audit") return audit(rest, host);
+	if (first === "mcp") return mcp(rest, host);
 	if (rest.length === 0 && (first === void 0 || first === "-h" || first === "--help")) {
 		host.stdout(`FiveRunner ${package_default.version}\n\n${USAGE}`);
 		return 0;
@@ -103719,6 +104044,7 @@ process.exitCode = await main(process.argv.slice(2), {
 	env: process.env,
 	stdout: (text) => process.stdout.write(text),
 	stderr: (text) => process.stderr.write(text),
+	input: process.stdin,
 	color: process.stdout.isTTY === true && process.env.NO_COLOR === void 0,
 	cfxlua: () => WebAssembly.compile(readFileSync(new URL("cfxlua.wasm", import.meta.url))),
 	wasm: () => readFileSync(new URL("cfxlua.wasm", import.meta.url)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiverunner",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Run FiveM resources (Lua, JavaScript and NUI) in your browser and in CI. No GTA V, no server, no restarts.",
   "keywords": [
     "fivem",