windows-development-sandbox 1.18.4 → 1.23.0

package/dist/guest/toolchains/fivem/artifacts.js

@@ -1,7 +1,100 @@
 // FXServer builds (the Cfx.re artifacts): which build "recommended", "optional", "latest" or a number means, from
-// changelogs-live.fivem.net/api/changelog/versions/win32/server. No checksums are published: the download is refused
-// under downloads.requireChecksum unless FXServer.exe is signed. Not available yet.
+// changelogs-live.fivem.net/api/changelog/versions/win32/server (a pinned build that is no channel's is looked up on
+// the artifacts page). No checksums are published: under downloads.requireChecksum a build is used only when its
+// FXServer.exe carries a valid Authenticode signature from Rockstar Games (Cfx.re's owner); without that setting an
+// unsigned one is used with a warning. No runtime imports: the self-test loads this file.
+import { z } from 'zod';
+import { fetchJson, fetchText } from '../../../shared/download/index.js';
+export const VERSIONS_URL = 'https://changelogs-live.fivem.net/api/changelog/versions/win32/server';
+export const ARTIFACTS_PAGE = 'https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/';
+/** The subject of the signature on FXServer.exe (checked on build 35245, 2026-11). */
+export const FXSERVER_SIGNER = /^CN="?Rockstar Games, Inc\.?"?, O="?Rockstar Games, Inc\.?"?,/;
+export const CHANNELS = ['recommended', 'optional', 'latest', 'critical'];
+const BUILD = z.string().regex(/^\d{1,7}$/);
+const DOWNLOAD = z
+    .string()
+    .max(512)
+    .regex(/^https:\/\/runtime\.fivem\.net\/artifacts\/fivem\/build_server_windows\/[A-Za-z0-9_./-]+\.(zip|7z)$/);
+const TXADMIN = z.string().max(32).optional();
+/** The versions API's answer (its other fields, such as support_policy, are not needed). */
+export const VersionsSchema = z.object({
+    recommended: BUILD,
+    recommended_download: DOWNLOAD,
+    recommended_txadmin: TXADMIN,
+    optional: BUILD,
+    optional_download: DOWNLOAD,
+    optional_txadmin: TXADMIN,
+    latest: BUILD,
+    latest_download: DOWNLOAD,
+    latest_txadmin: TXADMIN,
+    critical: BUILD,
+    critical_download: DOWNLOAD,
+    critical_txadmin: TXADMIN,
+});
+/** Every channel's build, from the versions API's JSON (throws on any other shape). */
+export function parseVersions(json) {
+    const v = VersionsSchema.parse(json);
+    const one = (channel, build, url, txAdmin) => ({
+        build: Number(build),
+        url,
+        channel,
+        ...(txAdmin ? { txAdmin } : {}),
+    });
+    return {
+        recommended: one('recommended', v.recommended, v.recommended_download, v.recommended_txadmin),
+        optional: one('optional', v.optional, v.optional_download, v.optional_txadmin),
+        latest: one('latest', v.latest, v.latest_download, v.latest_txadmin),
+        critical: one('critical', v.critical, v.critical_download, v.critical_txadmin),
+    };
+}
+const MAX_PAGE = 4 * 1024 * 1024;
+/** The builds the artifacts page links to (newest first), as server.zip downloads. Reads at most 4 MB of it. */
+export function parseArtifactsPage(html) {
+    const seen = new Map();
+    for (const m of html.slice(0, MAX_PAGE).matchAll(/\b(\d{3,7})-([0-9a-f]{40})\/server\.(?:zip|7z)\b/g)) {
+        const build = Number(m[1]);
+        if (!seen.has(build))
+            seen.set(build, { build, url: ARTIFACTS_PAGE + m[1] + '-' + m[2] + '/server.zip' });
+    }
+    return [...seen.values()].sort((a, b) => b.build - a.build);
+}
+/** What a setting names: a channel, or a build number. */
+export function artifactSetting(setting) {
+    if (CHANNELS.includes(setting))
+        return setting;
+    return /^\d{1,7}$/.test(setting) ? Number(setting) : null;
+}
+/** The build a setting names among the channels and the page's builds, or null. */
+export function chooseArtifact(setting, channels, page = []) {
+    const want = artifactSetting(setting);
+    if (want === null)
+        return null;
+    if (typeof want === 'string')
+        return channels[want];
+    return Object.values(channels).find((a) => a.build === want) ?? page.find((a) => a.build === want) ?? null;
+}
+/** The channels from the versions API. */
+export async function fetchChannels(src = {}) {
+    return parseVersions(await (src.versions ?? (() => fetchJson(VERSIONS_URL)))());
+}
 /** The build an artifact setting names, or null when it cannot be told. */
-export async function pickArtifact(_setting) {
-    return null;
+export async function pickArtifact(setting, src = {}) {
+    const want = artifactSetting(setting);
+    if (want === null)
+        return null;
+    const channels = await fetchChannels(src);
+    const found = chooseArtifact(setting, channels);
+    if (found || typeof want === 'string')
+        return found;
+    return chooseArtifact(setting, channels, parseArtifactsPage(await (src.page ?? (() => fetchText(ARTIFACTS_PAGE)))()));
+}
+/**
+ * Whether a downloaded build may be used. The artifacts have no checksums: the Authenticode signature on FXServer.exe
+ * stands in for one, so downloads.requireChecksum refuses a build whose FXServer.exe is not validly signed by Rockstar
+ * Games; without that setting an unsigned one is used (with a warning).
+ */
+export function artifactTrust(requireChecksum, signerSubject) {
+    if (FXSERVER_SIGNER.test(signerSubject))
+        return 'signed';
+    return requireChecksum ? 'refused' : 'unsigned-allowed';
 }

package/dist/guest/toolchains/fivem/fivem.d.ts

@@ -1,4 +1,35 @@
 import type { Toolchains } from '../../../core/types.js';
+import { type Installed } from '../persisted.js';
 import type { ToolCtx } from '../step.js';
 import type { ToolEnv } from '../tool-env.js';
-export declare function setupFivem(env: ToolEnv, _config: Toolchains['fivem'], _ctx: ToolCtx): Promise<void>;
+import { type FivemArtifact } from './artifacts.js';
+export declare const ARTIFACTS_NAME = "fivem/artifacts";
+/** state\fivem: txData and the build chosen with sbx-fivem artifact use. */
+export declare function fivemStateDir(): string;
+export declare function txDataDir(): string;
+export declare function artifactDir(build: number): string;
+/** The secrets cfg FXServer +execs, when this boot handed a Cfx.re key over. */
+export declare function secretsCfg(): string | null;
+/** The build chosen with `sbx-fivem artifact use` (and the one it was then), or the setting. */
+export declare function chosenArtifact(setting: string): {
+    setting: string;
+    chosen: boolean;
+    build: number | null;
+};
+/** Remembers a choice for sbx-fivem serve and the next boots (null: back to toolchains.fivem.artifact). */
+export declare function rememberArtifact(choice: {
+    artifact: string;
+    build: number;
+} | null): void;
+/** The build sbx-fivem serve runs: the one chosen last, this boot's, or the newest installed. */
+export declare function servingBuildDir(): string | null;
+/** Builds installed in tools\fivem\artifacts (newest first). */
+export declare function installedBuilds(): number[];
+/**
+ * The build a setting names: looked up online at most once a day (offline: the one remembered, else the newest
+ * installed for a channel, the installed one for a number).
+ */
+export declare function resolveArtifact(setting: string, live?: boolean): Promise<FivemArtifact>;
+/** The build's folder, installed when it is not there yet. */
+export declare function installArtifact(a: FivemArtifact, keepVersions: number): Promise<Installed>;
+export declare function setupFivem(env: ToolEnv, config: Toolchains['fivem'], _ctx: ToolCtx): Promise<void>;

package/dist/guest/toolchains/fivem/fivem.js

@@ -1,4 +1,169 @@
-import { notAvailableYet } from '../not-yet.js';
-export async function setupFivem(env, _config, _ctx) {
-    notAvailableYet(env, 'FiveM server');
+// FiveM / RedM (toolchains.fivem): FXServer (txAdmin is bundled) into tools\fivem\artifacts\<build>, kept between
+// sandboxes (keepVersions of them), txData in state\fivem, and sbx-fivem to run it. Installs only once you accept the
+// Cfx.re terms (acceptLicense). The build comes from toolchains.fivem.artifact, or from `sbx-fivem artifact use`
+// (remembered in state\fivem\artifact.json). The artifacts have no checksums: see artifacts.ts for the signature rule.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { downloader, extractArchive } from '../../../shared/download/index.js';
+import { readValid, writeJsonAtomic } from '../../../shared/io/json.js';
+import { safeRemove } from '../../../shared/io/safe-remove.js';
+import { dryRun, toolsDir } from '../../runtime/paths.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { log, warn } from '../../runtime/log.js';
+import { stateDir } from '../../runtime/session.js';
+import { signatureOf } from '../signature.js';
+import { ensurePersisted, installRecords } from '../persisted.js';
+import { resolveCached } from '../version-cache.js';
+import { cfxSecretsFile } from '../../accounts/kinds/cfx.js';
+import { artifactSetting, artifactTrust, pickArtifact } from './artifacts.js';
+export const ARTIFACTS_NAME = 'fivem/artifacts';
+const MB = 1024 * 1024;
+/** Room a build needs while installing: the zip (~65 MB) and its unpacked copy (~200 MB). */
+const NEED_BYTES = 600 * MB;
+const LICENCE = 'The FiveM server is installed only with toolchains.fivem.acceptLicense = true: FXServer comes under the Cfx.re platform terms (https://fivem.net/terms) and its licence';
+const ArtifactSchema = z.strictObject({
+    build: z.number().int().positive(),
+    url: z.string().url().startsWith('https://runtime.fivem.net/'),
+    channel: z.enum(['recommended', 'optional', 'latest', 'critical']).optional(),
+    txAdmin: z.string().max(32).optional(),
+});
+const SelectionSchema = z.strictObject({
+    artifact: z.string().regex(/^(recommended|optional|latest|critical|\d{1,7})$/),
+    build: z.number().int().positive(),
+});
+/** state\fivem: txData and the build chosen with sbx-fivem artifact use. */
+export function fivemStateDir() {
+    return path.join(stateDir, 'fivem');
+}
+export function txDataDir() {
+    return path.join(fivemStateDir(), 'txData');
+}
+const selectionFile = () => path.join(fivemStateDir(), 'artifact.json');
+export function artifactDir(build) {
+    return path.join(toolsDir, ...ARTIFACTS_NAME.split('/'), String(build));
+}
+/** The secrets cfg FXServer +execs, when this boot handed a Cfx.re key over. */
+export function secretsCfg() {
+    const file = cfxSecretsFile();
+    return fs.existsSync(file) ? file : null;
+}
+/** The build chosen with `sbx-fivem artifact use` (and the one it was then), or the setting. */
+export function chosenArtifact(setting) {
+    const picked = readValid(SelectionSchema, selectionFile());
+    return picked
+        ? { setting: picked.artifact, chosen: true, build: picked.build }
+        : { setting, chosen: false, build: null };
+}
+/** Remembers a choice for sbx-fivem serve and the next boots (null: back to toolchains.fivem.artifact). */
+export function rememberArtifact(choice) {
+    if (choice === null) {
+        fs.rmSync(selectionFile(), { force: true });
+        return;
+    }
+    fs.mkdirSync(fivemStateDir(), { recursive: true });
+    writeJsonAtomic(selectionFile(), SelectionSchema.parse(choice));
+}
+/** The build sbx-fivem serve runs: the one chosen last, this boot's, or the newest installed. */
+export function servingBuildDir() {
+    const chosen = chosenArtifact('recommended').build;
+    const candidates = [
+        chosen === null ? null : artifactDir(chosen),
+        process.env.FXSERVER_DIR ?? null,
+        ...installedBuilds().map(artifactDir),
+    ];
+    return candidates.find((d) => d !== null && fs.existsSync(path.join(d, 'FXServer.exe'))) ?? null;
+}
+/** Builds installed in tools\fivem\artifacts (newest first). */
+export function installedBuilds() {
+    return installRecords()
+        .filter((r) => r.name === ARTIFACTS_NAME && /^\d+$/.test(r.version))
+        .map((r) => Number(r.version))
+        .filter((b) => fs.existsSync(path.join(artifactDir(b), 'FXServer.exe')))
+        .sort((a, b) => b - a);
+}
+/**
+ * The build a setting names: looked up online at most once a day (offline: the one remembered, else the newest
+ * installed for a channel, the installed one for a number).
+ */
+export async function resolveArtifact(setting, live = false) {
+    const want = artifactSetting(setting);
+    if (want === null)
+        throw new Error('"' + setting + '" is not a server build (recommended, optional, latest or a number)');
+    const lookup = async () => {
+        const found = await pickArtifact(setting);
+        if (!found)
+            throw new Error('there is no FXServer build ' + setting + ' for Windows');
+        return JSON.stringify(found);
+    };
+    try {
+        return ArtifactSchema.parse(JSON.parse(live ? await lookup() : await resolveCached('fivem:' + setting, lookup)));
+    }
+    catch (e) {
+        const installed = installedBuilds();
+        const fallback = typeof want === 'number' ? installed.find((b) => b === want) : installed[0];
+        if (fallback === undefined)
+            throw e;
+        warn('Could not look up FXServer ' + setting + ' (' + errMsg(e) + '); using installed build ' + fallback);
+        return { build: fallback, url: 'https://runtime.fivem.net/' };
+    }
+}
+/** Downloads and unpacks a build into `staging`; refuses it per artifactTrust. */
+async function installBuild(a, staging, temp) {
+    const zip = path.join(temp, 'server.zip');
+    const check = path.join(temp, 'check');
+    // requireChecksum: the signature on FXServer.exe stands in for the checksum Cfx.re does not publish.
+    const verify = async (file) => {
+        await extractArchive(file, check, ['FXServer.exe']);
+        const exe = path.join(check, 'FXServer.exe');
+        if (artifactTrust(true, fs.existsSync(exe) ? (signatureOf(exe)?.subject ?? '') : '') !== 'signed')
+            throw new Error('FXServer build ' +
+                a.build +
+                ': FXServer.exe is not validly signed by Rockstar Games, and downloads.requireChecksum is on (Cfx.re publishes no checksums)');
+        safeRemove(check, temp);
+    };
+    log('Downloading FXServer build ' + a.build + ' (~65 MB once) ...');
+    await downloader.file(a.url, zip, downloader.requireChecksum ? { verify } : null);
+    await extractArchive(zip, staging);
+    fs.rmSync(zip, { force: true });
+    const exe = path.join(staging, 'FXServer.exe');
+    const trust = artifactTrust(downloader.requireChecksum, fs.existsSync(exe) ? (signatureOf(exe)?.subject ?? '') : '');
+    if (trust === 'refused')
+        throw new Error('FXServer build ' + a.build + ' is not validly signed; not using it');
+    if (trust === 'unsigned-allowed')
+        warn('FXServer build ' +
+            a.build +
+            ': FXServer.exe has no valid Rockstar Games signature (used anyway: downloads.requireChecksum is off)');
+}
+/** The build's folder, installed when it is not there yet. */
+export async function installArtifact(a, keepVersions) {
+    return ensurePersisted({
+        name: ARTIFACTS_NAME,
+        version: String(a.build),
+        needBytes: NEED_BYTES,
+        marker: 'FXServer.exe',
+        what: 'FXServer build ' + a.build,
+        keepVersions,
+    }, (staging, temp) => installBuild(a, staging, temp), { log });
+}
+export async function setupFivem(env, config, _ctx) {
+    if (!config.acceptLicense)
+        throw new Error(LICENCE);
+    const { setting, chosen } = chosenArtifact(config.artifact);
+    if (dryRun) {
+        log('(dry run) would install FXServer ' + setting + ' into tools\\fivem\\artifacts');
+        return;
+    }
+    const artifact = await resolveArtifact(setting);
+    const installed = await installArtifact(artifact, config.keepVersions);
+    fs.mkdirSync(txDataDir(), { recursive: true });
+    env.vars.FXSERVER_DIR = installed.dir;
+    env.vars.FIVEM_GAME = config.game;
+    env.summary.push('fivem: FXServer build ' +
+        artifact.build +
+        ' (' +
+        (chosen ? setting + ', chosen with sbx-fivem artifact use' : setting) +
+        (config.game === 'rdr3' ? ', RedM' : '') +
+        '); start it with sbx-fivem serve' +
+        (secretsCfg() ? '' : ' (no Cfx.re key: sandbox account login cfx on your PC)'));
 }

package/dist/guest/toolchains/fivem/scaffold.d.ts

@@ -0,0 +1,35 @@
+export declare const RESOURCE_LANGS: readonly ["lua", "js", "ts", "cs"];
+export type ResourceLang = (typeof RESOURCE_LANGS)[number];
+export type FivemGame = 'gta5' | 'rdr3';
+/** Resource names FXServer takes in `ensure`: letters, digits, - and _. */
+export declare const RESOURCE_NAME: RegExp;
+/** sandbox\templates\fivem in the launch folder. */
+export declare function fivemTemplatesDir(): string;
+/** The manifest's game lines (RedM also needs its prerelease acknowledgement). */
+export declare function gameLines(game: FivemGame): string;
+/** A resource name as a C# namespace: my-cool_res -> MyCoolRes (a leading digit gets an R). */
+export declare function csNamespace(name: string): string;
+/** Fills {{key}} placeholders; unknown ones stay as they are. */
+export declare function renderTemplate(text: string, vars: Readonly<Record<string, string>>): string;
+export declare function templateVars(name: string, game: FivemGame): Record<string, string>;
+/** The template's files (relative paths), bounded; links are skipped. */
+export declare function templateFiles(dir: string): string[];
+export interface NewResource {
+    readonly templates: string;
+    readonly lang: ResourceLang;
+    readonly name: string;
+    /** The folder the resource folder goes in (resources\[local] of a server folder, or any folder). */
+    readonly into: string;
+    readonly game: FivemGame;
+}
+/** Makes <into>\<name> from the language's template; returns the folder and its files. */
+export declare function scaffoldResource(o: NewResource): {
+    dir: string;
+    files: string[];
+};
+/** server.cfg with `ensure <name>` added at the end, or null when it already ensures it. */
+export declare function withEnsure(cfg: string, name: string): string | null;
+/** Where `sbx-fivem new` puts a resource: resources\[local] when the folder is a server folder, else the folder. */
+export declare function resourceHome(folder: string): string;
+/** Writes server.cfg (when there is none) and resources\[local] into `dir`; returns what it wrote. */
+export declare function initServerFolder(templates: string, dir: string, name: string, game: FivemGame): string[];

package/dist/guest/toolchains/fivem/scaffold.js

@@ -0,0 +1,105 @@
+// New FiveM / RedM resources and server folders from sandbox\templates\fivem (`sbx-fivem new`, `sbx-fivem init`):
+// the template's files with {{name}}, {{namespace}}, {{game}} and {{gameLines}} filled in. Never overwrites anything.
+// No runtime imports: the self-test loads this file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { sandboxScriptsDir } from '../../../shared/scripts.js';
+export const RESOURCE_LANGS = ['lua', 'js', 'ts', 'cs'];
+/** Resource names FXServer takes in `ensure`: letters, digits, - and _. */
+export const RESOURCE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,47}$/;
+const MAX_TEMPLATE_FILES = 64;
+const MAX_TEMPLATE_BYTES = 256 * 1024;
+const RDR3_WARNING = "rdr3_warning 'I acknowledge that this is a prerelease build of RedM, and I am aware my resources *will* become incompatible once RedM ships.'";
+/** sandbox\templates\fivem in the launch folder. */
+export function fivemTemplatesDir() {
+    return path.join(sandboxScriptsDir(), 'templates', 'fivem');
+}
+/** The manifest's game lines (RedM also needs its prerelease acknowledgement). */
+export function gameLines(game) {
+    return game === 'rdr3' ? "game 'rdr3'\n" + RDR3_WARNING : "game 'gta5'";
+}
+/** A resource name as a C# namespace: my-cool_res -> MyCoolRes (a leading digit gets an R). */
+export function csNamespace(name) {
+    const pascal = name
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+    return /^[0-9]/.test(pascal) ? 'R' + pascal : pascal;
+}
+/** Fills {{key}} placeholders; unknown ones stay as they are. */
+export function renderTemplate(text, vars) {
+    return text.replace(/\{\{([A-Za-z]{1,20})\}\}/g, (all, key) => vars[key] ?? all);
+}
+export function templateVars(name, game) {
+    return { name, namespace: csNamespace(name), game, gameLines: gameLines(game) };
+}
+/** The template's files (relative paths), bounded; links are skipped. */
+export function templateFiles(dir) {
+    const out = [];
+    const walk = (current, depth) => {
+        for (const e of fs.readdirSync(current, { withFileTypes: true })) {
+            if (out.length >= MAX_TEMPLATE_FILES)
+                return;
+            const full = path.join(current, e.name);
+            if (e.isFile())
+                out.push(path.relative(dir, full));
+            else if (e.isDirectory() && depth < 4)
+                walk(full, depth + 1);
+        }
+    };
+    walk(dir, 0);
+    return out.sort();
+}
+function copyRendered(from, to, vars) {
+    const files = templateFiles(from);
+    for (const rel of files) {
+        const src = path.join(from, rel);
+        if (fs.statSync(src).size > MAX_TEMPLATE_BYTES)
+            throw new Error('template file too big: ' + rel);
+        const dest = path.join(to, rel);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, renderTemplate(fs.readFileSync(src, 'utf8'), vars), { flag: 'wx' });
+    }
+    return files;
+}
+/** Makes <into>\<name> from the language's template; returns the folder and its files. */
+export function scaffoldResource(o) {
+    if (!RESOURCE_NAME.test(o.name))
+        throw new Error('"' + o.name + '" is not a resource name: letters, digits, - and _ only (up to 48)');
+    const dir = path.join(o.into, o.name);
+    if (fs.existsSync(dir))
+        throw new Error(dir + ' already exists');
+    const files = copyRendered(path.join(o.templates, o.lang), dir, templateVars(o.name, o.game));
+    return { dir, files };
+}
+/** server.cfg with `ensure <name>` added at the end, or null when it already ensures it. */
+export function withEnsure(cfg, name) {
+    const line = new RegExp('^\\s*(ensure|start)\\s+' + name.replace(/[-]/g, '\\-') + '\\s*$', 'm');
+    if (line.test(cfg))
+        return null;
+    return cfg.replace(/\s*$/, '') + '\nensure ' + name + '\n';
+}
+/** Where `sbx-fivem new` puts a resource: resources\[local] when the folder is a server folder, else the folder. */
+export function resourceHome(folder) {
+    return fs.existsSync(path.join(folder, 'server.cfg')) || fs.existsSync(path.join(folder, 'resources'))
+        ? path.join(folder, 'resources', '[local]')
+        : folder;
+}
+/** Writes server.cfg (when there is none) and resources\[local] into `dir`; returns what it wrote. */
+export function initServerFolder(templates, dir, name, game) {
+    const wrote = [];
+    const cfg = path.join(dir, 'server.cfg');
+    if (!fs.existsSync(cfg)) {
+        const text = renderTemplate(fs.readFileSync(path.join(templates, 'server.cfg'), 'utf8'), templateVars(name, game));
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(cfg, text, { flag: 'wx' });
+        wrote.push('server.cfg');
+    }
+    const local = path.join(dir, 'resources', '[local]');
+    if (!fs.existsSync(local)) {
+        fs.mkdirSync(local, { recursive: true });
+        wrote.push('resources\\[local]');
+    }
+    return wrote;
+}

package/dist/guest/toolchains/fivem/serve-plan.d.ts

@@ -0,0 +1,34 @@
+import type { FivemGame } from './scaffold.js';
+export declare const GAME_PORT = 30120;
+export declare const TXADMIN_PORT = 40120;
+export interface ServeInput {
+    /** The FXServer build's folder (FXServer.exe, citizen\). */
+    readonly artifactDir: string;
+    /** The server folder (server.cfg, resources\). */
+    readonly serverDir: string;
+    readonly game: FivemGame;
+    readonly txAdmin: boolean;
+    /** The Cfx.re key's cfg, or null when no key was handed over. */
+    readonly secretsCfg: string | null;
+    readonly txData: string;
+    /** The port of the sandbox's MariaDB (databases.mysql), or null when it has none. */
+    readonly mysqlPort: number | null;
+}
+export interface OpenPort {
+    readonly port: number;
+    readonly protocol: 'TCP' | 'UDP' | 'Both';
+    readonly name: string;
+}
+export interface ServePlan {
+    readonly exe: string;
+    readonly args: string[];
+    readonly cwd: string;
+    /** Added to sbx-fivem's own environment. */
+    readonly env: Record<string, string>;
+    readonly ports: OpenPort[];
+}
+/** FXServer's exec takes forward slashes. */
+export declare function cfgPath(file: string): string;
+/** oxmysql's connection string for the sandbox's MariaDB (user root, no password, database "fivem"). */
+export declare function mysqlConnectionString(port: number): string;
+export declare function servePlan(i: ServeInput): ServePlan;

package/dist/guest/toolchains/fivem/serve-plan.js

@@ -0,0 +1,61 @@
+// How `sbx-fivem serve` starts FXServer: the program, its arguments and environment, and the ports the PC needs.
+// Plain: +exec the Cfx.re key's cfg (on the sandbox's own disk) and then the project's server.cfg, from the server
+// folder. txAdmin: no +exec (FXServer then starts txAdmin), its data in state\fivem\txData through TXHOST_*.
+// No runtime imports: the self-test loads this file.
+import path from 'node:path';
+export const GAME_PORT = 30120;
+export const TXADMIN_PORT = 40120;
+/** FXServer's exec takes forward slashes. */
+export function cfgPath(file) {
+    return file.split('\\').join('/');
+}
+/** oxmysql's connection string for the sandbox's MariaDB (user root, no password, database "fivem"). */
+export function mysqlConnectionString(port) {
+    return 'mysql://root@127.0.0.1:' + port + '/fivem?charset=utf8mb4';
+}
+export function servePlan(i) {
+    const exe = path.join(i.artifactDir, 'FXServer.exe');
+    const citizen = ['+set', 'citizen_dir', path.join(i.artifactDir, 'citizen')];
+    const game = i.game === 'rdr3' ? ['+set', 'gamename', 'rdr3'] : [];
+    if (i.txAdmin) {
+        const db = i.mysqlPort === null
+            ? {}
+            : {
+                TXHOST_DEFAULT_DBHOST: '127.0.0.1',
+                TXHOST_DEFAULT_DBPORT: String(i.mysqlPort),
+                TXHOST_DEFAULT_DBUSER: 'root',
+                TXHOST_DEFAULT_DBNAME: 'fivem',
+            };
+        return {
+            exe,
+            // RedM: txAdmin's recipes for it set gamename in the server.cfg they write.
+            args: citizen,
+            cwd: i.txData,
+            env: {
+                TXHOST_DATA_PATH: i.txData,
+                TXHOST_TXA_PORT: String(TXADMIN_PORT),
+                TXHOST_GAME_NAME: i.game === 'rdr3' ? 'redm' : 'fivem',
+                TXHOST_PROVIDER_NAME: 'Sandbox',
+                ...db,
+            },
+            ports: [
+                { port: GAME_PORT, protocol: 'Both', name: 'FiveM server' },
+                { port: TXADMIN_PORT, protocol: 'TCP', name: 'txAdmin' },
+            ],
+        };
+    }
+    return {
+        exe,
+        args: [
+            ...citizen,
+            ...game,
+            ...(i.mysqlPort === null ? [] : ['+set', 'mysql_connection_string', mysqlConnectionString(i.mysqlPort)]),
+            ...(i.secretsCfg ? ['+exec', cfgPath(i.secretsCfg)] : []),
+            '+exec',
+            'server.cfg',
+        ],
+        cwd: i.serverDir,
+        env: {},
+        ports: [{ port: GAME_PORT, protocol: 'Both', name: 'FiveM server' }],
+    };
+}

package/dist/guest/toolchains/installers.d.ts

@@ -1,12 +1,8 @@
-/** Who signs the installers the toolchains run (the subject of the signature). */
-export declare const SIGNERS: {
-    readonly microsoft: "CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US";
-    readonly valve: RegExp;
-    readonly unity: RegExp;
-};
-/** Whether a file's signature is the expected signer's. */
-export declare function signedBy(file: string, signer: string | RegExp): boolean;
+import { SIGNERS, type AppSigner } from '../../shared/signer.js';
+import { signedBy } from './signature.js';
+export { SIGNERS };
+export { signedBy };
 /** A downloader `verify` hook: refuses a file not signed by `signer` (it counts as integrity for requireChecksum). */
-export declare function signatureCheck(signer: string | RegExp, what: string): (file: string) => void;
+export declare function signatureCheck(signer: AppSigner, what: string): (file: string) => void;
 /** The installer at `file` (downloaded once from `url`), checked against its signer and, when given, its SHA-256. */
-export declare function signedInstaller(url: string, file: string, what: string, signer: string | RegExp, sha256?: string | null): Promise<string>;
+export declare function signedInstaller(url: string, file: string, what: string, signer: AppSigner, sha256?: string | null): Promise<string>;

package/dist/guest/toolchains/installers.js

@@ -5,18 +5,10 @@ import path from 'node:path';
 import { downloader } from '../../shared/download/index.js';
 import { exists, mkdirp } from '../runtime/fs.js';
 import { log } from '../runtime/log.js';
-import { MICROSOFT_SIGNER, signerOf } from './native/vcruntime.js';
-/** Who signs the installers the toolchains run (the subject of the signature). */
-export const SIGNERS = {
-    microsoft: MICROSOFT_SIGNER,
-    valve: /^CN="?Valve(,| Corp)/,
-    unity: /^CN="?Unity Technologies/,
-};
-/** Whether a file's signature is the expected signer's. */
-export function signedBy(file, signer) {
-    const subject = signerOf(file);
-    return typeof signer === 'string' ? subject === signer : signer.test(subject);
-}
+import { SIGNERS } from '../../shared/signer.js';
+import { signedBy } from './signature.js';
+export { SIGNERS };
+export { signedBy };
 /** A downloader `verify` hook: refuses a file not signed by `signer` (it counts as integrity for requireChecksum). */
 export function signatureCheck(signer, what) {
     return (file) => {

package/dist/guest/toolchains/languages/go.js

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { downloader, fetchJson } from '../../../shared/download/index.js';
 import { dryRun } from '../../runtime/paths.js';
-import { execAsync } from '../../runtime/process.js';
+import { execHeavy as execAsync } from '../../runtime/pools.js';
 import { exists } from '../../runtime/fs.js';
 import { log } from '../../runtime/log.js';
 import { arch, tool, versionOf } from '../tool-env.js';

package/dist/guest/toolchains/languages/node.js

@@ -5,7 +5,8 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { downloader, fetchJson, githubAsset } from '../../../shared/download/index.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
-import { copyNode, execAsync } from '../../runtime/process.js';
+import { copyNode } from '../../runtime/process.js';
+import { execHeavy as execAsync } from '../../runtime/pools.js';
 import { dryRun, hostToolsDir, localDir } from '../../runtime/paths.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
 import { log, warn } from '../../runtime/log.js';

package/dist/guest/toolchains/languages/php.d.ts

@@ -1,3 +1,5 @@
 import type { Toolchains } from '../../../core/types.js';
 import { type ToolEnv } from '../tool-env.js';
+/** Downloads PHP's zip ahead of the install (which unpacks it); nothing when PHP is there already. */
+export declare function fetchPhp(config: Toolchains['php']): Promise<void>;
 export declare function setupPhp(env: ToolEnv, config: Toolchains['php']): Promise<void>;