windows-development-sandbox 1.20.0 → 1.23.1

package/dist/selftest/fivem.test.js

@@ -1,7 +1,253 @@
+// FiveM / RedM: server builds from the versions API (a saved copy of its answer), the signature rule that stands in
+// for checksums, the Cfx.re key's cfg on the sandbox's own disk, how sbx-fivem serve starts FXServer (RedM, txAdmin,
+// oxmysql), the resource scaffolds, the toolchain hints and the modding apps.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fakeIO } from '../app/kernel/index.js';
+import { importServiceFlow, loginServiceFlow } from '../app/features/accounts/index.js';
+import { DEFAULTS } from '../core/config/index.js';
+import { isKindReady, isToolchainReady } from '../shared/readiness.js';
+import { HOST_SOURCES, ServiceAccountStore } from '../host/accounts/index.js';
+import { fivemHints } from '../host/launch/hints/fivem.js';
+import { SecretStore } from '../host/secrets/index.js';
+import { applyServiceAccounts, readDelivered } from '../guest/accounts/apply.js';
+import { accountsRoot } from '../guest/accounts/adapter.js';
+import { cfxAdapter, cfxSecretsFile, cfxSecretsText } from '../guest/accounts/kinds/cfx.js';
+import { ARTIFACTS_PAGE, artifactSetting, artifactTrust, chooseArtifact, parseArtifactsPage, parseVersions, pickArtifact, } from '../guest/toolchains/fivem/artifacts.js';
+import { csNamespace, initServerFolder, RESOURCE_LANGS, resourceHome, scaffoldResource, templateFiles, withEnsure, } from '../guest/toolchains/fivem/scaffold.js';
+import { GAME_PORT, mysqlConnectionString, servePlan, TXADMIN_PORT } from '../guest/toolchains/fivem/serve-plan.js';
+import { APPS } from '../shared/apps/index.js';
+import { MODDING_APPS } from '../shared/apps/catalogue-modding.js';
+import { Downloader } from '../shared/download/index.js';
+const KEY = 'cfxk_PlantedFivemKey_0123456789abcdef';
+const STEAM = '0123456789ABCDEF0123456789ABCDEF';
+const ROCKSTAR = 'CN="Rockstar Games, Inc.", O="Rockstar Games, Inc.", L=New York, S=New York, C=US';
+const allFiles = (dir) => fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir, { recursive: true, encoding: 'utf8' })
+        .map((f) => path.join(dir, f))
+        .filter((f) => fs.statSync(f).isFile())
+    : [];
 export const fivemSuite = {
     name: 'fivem',
-    title: 'FiveM / RedM: server builds, the Cfx.re key, sbx-fivem (not available yet)',
-    run: (t) => {
-        t.check(true, 'fivem: not available yet');
+    title: 'FiveM / RedM: server builds, the Cfx.re key, sbx-fivem serve, scaffolds, hints, modding apps',
+    run: async (t) => {
+        const fixtures = path.join(t.packageRoot, 'src', 'selftest', 'fixtures', 'fivem');
+        const versionsJson = JSON.parse(fs.readFileSync(path.join(fixtures, 'versions.json'), 'utf8'));
+        const pageHtml = fs.readFileSync(path.join(fixtures, 'artifacts-page.txt'), 'utf8');
+        t.check(isToolchainReady('fivem') && isKindReady('cfx') && isKindReady('perplexity') && isKindReady('comet'), 'FiveM, the Cfx.re key and the Perplexity sign-ins are written: settings and accounts list them');
+        t.section('server builds (versions API)');
+        const channels = parseVersions(versionsJson);
+        t.check(channels.recommended.build === 35245 &&
+            channels.latest.build === 38182 &&
+            channels.optional.build === 7290 &&
+            channels.critical.build === 7290 &&
+            channels.recommended.url.endsWith('/35245-6efb47dff473c0e2a12fb50b08d74c0eb24a50d5/server.zip') &&
+            channels.recommended.txAdmin === '8.1.1' &&
+            channels.latest.txAdmin === '8.1.2', 'the versions API gives each channel its build, its server.zip and its txAdmin');
+        await t.throws(() => parseVersions({
+            ...versionsJson,
+            latest_download: 'https://evil.example/38182/server.zip',
+        }), '', 'a download anywhere but runtime.fivem.net is refused');
+        await t.throws(() => parseVersions({ recommended: '1' }), '', 'an answer of another shape is refused');
+        const page = parseArtifactsPage(pageHtml);
+        t.check(page.length === 4 &&
+            page[0].build === 38182 &&
+            page.every((a) => a.url.startsWith(ARTIFACTS_PAGE) && a.url.endsWith('/server.zip')) &&
+            page.some((a) => a.build === 38164 && a.url.includes('38164-c7a8db730dbaaf1519221ac63e179e2f3af48d55')), 'the artifacts page gives the Windows builds (newest first, as server.zip), not Linux or other servers', JSON.stringify(page));
+        t.check(artifactSetting('recommended') === 'recommended' &&
+            artifactSetting('38164') === 38164 &&
+            artifactSetting('newest') === null &&
+            artifactSetting('1e3') === null, 'a setting is a channel or a build number');
+        t.check(chooseArtifact('recommended', channels)?.build === 35245 &&
+            chooseArtifact('latest', channels)?.build === 38182 &&
+            chooseArtifact('optional', channels)?.build === 7290 &&
+            chooseArtifact('7290', channels)?.url === channels.optional.url &&
+            chooseArtifact('38164', channels) === null &&
+            chooseArtifact('38164', channels, page)?.build === 38164, 'recommended / latest / optional pick their channel; a pinned build is a channel build or one on the page');
+        let pageAsked = 0;
+        const sources = {
+            versions: () => Promise.resolve(versionsJson),
+            page: () => {
+                pageAsked++;
+                return Promise.resolve(pageHtml);
+            },
+        };
+        const rec = await pickArtifact('recommended', sources);
+        const pinned = await pickArtifact('38164', sources);
+        const unknown = await pickArtifact('12', sources);
+        t.check(rec?.build === 35245 && pinned?.build === 38164 && unknown === null && pageAsked === 2, 'pickArtifact reads the page only for a pinned build that no channel names; an unknown build is null');
+        t.equal(await pickArtifact('soon', sources), null, 'a setting that names nothing is null');
+        t.section('no checksums: the signature rule');
+        t.equal(artifactTrust(true, ROCKSTAR), 'signed', 'requireChecksum on: a valid Rockstar Games signature passes');
+        t.equal(artifactTrust(false, ROCKSTAR), 'signed', 'and without it too');
+        t.equal(artifactTrust(true, ''), 'refused', 'requireChecksum on: unsigned (or tampered) is refused');
+        t.equal(artifactTrust(false, ''), 'unsigned-allowed', 'requireChecksum off: unsigned is used with a warning');
+        t.equal(artifactTrust(true, 'CN="Rockstar Games, Inc. Mods", O=Somebody Else, C=US'), 'refused', 'a look-alike signer is not Rockstar Games');
+        t.equal(artifactTrust(true, 'CN=Valve Corp., O=Valve Corp., C=US'), 'refused', 'another vendor is not enough');
+        const strict = new Downloader();
+        strict.requireChecksum = true;
+        await t.throws(() => strict.file(channels.recommended.url, t.at('fivem-dl', 'server.zip'), null), 'requireChecksum', 'requireChecksum: a build without the signature check is refused before anything downloads');
+        t.check(!fs.existsSync(t.at('fivem-dl', 'server.zip')), 'and nothing is written');
+        t.section('the Cfx.re key');
+        const parsed = HOST_SOURCES.cfx.fromAnswers({ licenseKey: KEY, steamWebApiKey: STEAM.toLowerCase() });
+        t.check(parsed.licenseKey === KEY && parsed.steamWebApiKey === STEAM, 'typed: the key and the Steam Web API key (upper-cased)');
+        t.check(!HOST_SOURCES.cfx.fromPc && HOST_SOURCES.cfx.fromFile !== undefined && HOST_SOURCES.cfx.fromAnswers !== undefined, 'the key is typed or read from a server.cfg (nothing on the PC to take it from)');
+        const cfg = [
+            '# my server',
+            'sv_licenseKey "cfxk_OldKey_000" // old',
+            'endpoint_add_tcp "0.0.0.0:30120"',
+            '// setr steam_webApiKey "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"',
+            'sets tags "a#b"',
+            'setr steam_webApiKey "' + STEAM.toLowerCase() + '"',
+            'set sv_licenseKey ' + KEY + ' # the real one',
+        ].join('\r\n');
+        const fromCfg = HOST_SOURCES.cfx.fromFile(Buffer.from(cfg, 'utf8'), {});
+        t.check(fromCfg.licenseKey === KEY && fromCfg.steamWebApiKey === STEAM, 'server.cfg: comments and quotes handled, setr works, the last key wins, the Steam key is upper-cased');
+        await t.throws(() => HOST_SOURCES.cfx.fromFile(Buffer.from('# sv_licenseKey cfxk_x\nendpoint_add_tcp "0.0.0.0:30120"', 'utf8'), {}), 'no sv_licenseKey', 'a commented-out key is not a key');
+        t.check(!(HOST_SOURCES.cfx.summary(fromCfg) ?? '').includes(KEY), 'the summary of an imported key never holds it');
+        const cfgFile = t.write(t.at('fivem-cfg', 'server.cfg'), cfg);
+        const cfgStore = new ServiceAccountStore(t.dir('fivem-cfg-store'), SecretStore.memory());
+        const cfgIO = fakeIO([true]);
+        const pcNone = { localAppData: '', appData: '', programData: '' };
+        const imported = await importServiceFlow(cfgIO.io, 'cfx', cfgFile, { store: cfgStore, pc: pcNone, share: false });
+        t.check(cfgStore.read('cfx')?.licenseKey === KEY &&
+            cfgIO.seen.questions.length === 1 &&
+            !JSON.stringify(cfgIO.seen).includes(KEY) &&
+            !imported.message.includes(KEY), 'import cfx --from server.cfg asks only to confirm (no fields), saves it, never shows it');
+        const big = t.write(t.at('fivem-cfg', 'big.cfg'), '#'.repeat(256 * 1024 + 1));
+        await t.throws(() => importServiceFlow(fakeIO([true]).io, 'cfx', big, { store: cfgStore, pc: pcNone, share: false }), 'Cannot read', 'a server.cfg over 256 KB is refused');
+        await t.throws(() => HOST_SOURCES.cfx.fromAnswers({ licenseKey: 'cfxk_x" +exec evil.cfg "' }), 'not a Cfx.re server key', 'a key with quotes or spaces is refused (it could not break out of its cfg line anyway)');
+        const summary = HOST_SOURCES.cfx.summary(parsed) ?? '';
+        t.check(!summary.includes(KEY) && !summary.includes(STEAM), 'the summary never holds the key');
+        const store = new ServiceAccountStore(t.dir('fivem-store'), SecretStore.memory());
+        const saved = await loginServiceFlow(fakeIO([KEY, '']).io, 'cfx', { store, share: false });
+        t.check(store.read('cfx')?.licenseKey === KEY &&
+            !saved.message.includes(KEY) &&
+            saved.message.includes('Share with sandboxes'), 'sandbox account login cfx saves it sealed, says how to share it, never shows it');
+        const oldLocal = process.env.LOCALAPPDATA;
+        const local = t.dir('fivem-local');
+        const project = t.dir('fivem-project');
+        const data = t.dir('fivem-data');
+        process.env.LOCALAPPDATA = local;
+        try {
+            const env = await applyServiceAccounts({ cfx: { licenseKey: KEY, steamWebApiKey: STEAM } }, { root: accountsRoot() });
+            const cfg = cfxSecretsFile();
+            const text = fs.existsSync(cfg) ? fs.readFileSync(cfg, 'utf8') : '';
+            t.check(cfg === path.join(local, 'AgentSandbox', 'accounts', 'cfx', 'server-secrets.cfg') &&
+                text.includes('sv_licenseKey "' + KEY + '"') &&
+                text.includes('set steam_webApiKey "' + STEAM + '"'), "boot writes the key to a cfg in the sandbox's own folder (%LOCALAPPDATA%\\AgentSandbox\\accounts\\cfx)", cfg);
+            const leaks = [...allFiles(project), ...allFiles(data), ...allFiles(path.join(local, 'AgentSandbox'))].filter((f) => f !== cfg && fs.readFileSync(f, 'utf8').includes(KEY));
+            t.check(!leaks.length && !Object.values(env).some((v) => v.includes(KEY)), 'the key is nowhere else: not in the project, the data folder, delivered.json or the agent environment', leaks.join(', '));
+            t.check(!JSON.stringify(readDelivered(accountsRoot())).includes(KEY), 'delivered.json holds only a fingerprint');
+            t.check((await cfxAdapter.apply({ licenseKey: KEY })).summary.includes('sbx-fivem serve') &&
+                !fs.readFileSync(cfg, 'utf8').includes('steam_webApiKey'), 'without a Steam Web API key its line is left out');
+            t.check(cfxSecretsText({ licenseKey: KEY })
+                .split('\r\n')
+                .filter((l) => l && !l.startsWith('#')).length === 1, 'the cfg is one setting per line, nothing else');
+        }
+        finally {
+            if (oldLocal === undefined)
+                delete process.env.LOCALAPPDATA;
+            else
+                process.env.LOCALAPPDATA = oldLocal;
+        }
+        t.section('sbx-fivem serve');
+        const secrets = 'C:\\Users\\WDAGUtilityAccount\\AppData\\Local\\AgentSandbox\\accounts\\cfx\\server-secrets.cfg';
+        const base = {
+            artifactDir: 'C:\\AgentData\\tools\\fivem\\artifacts\\35245',
+            serverDir: 'C:\\Workspace\\server',
+            game: 'gta5',
+            txAdmin: false,
+            secretsCfg: secrets,
+            txData: 'C:\\AgentData\\state\\fivem\\txData',
+            mysqlPort: null,
+        };
+        const plain = servePlan(base);
+        const execs = plain.args.flatMap((a, i) => (a === '+exec' ? [plain.args[i + 1]] : []));
+        t.check(plain.exe === 'C:\\AgentData\\tools\\fivem\\artifacts\\35245\\FXServer.exe' &&
+            plain.cwd === base.serverDir &&
+            execs.join('|') === secrets.split('\\').join('/') + '|server.cfg' &&
+            plain.args.includes('citizen_dir') &&
+            !plain.args.includes('gamename') &&
+            !plain.args.join(' ').includes('cfxk_'), "plain: FXServer by its full path, +exec the key's cfg first and then server.cfg, from the server folder", JSON.stringify(plain.args));
+        t.equal(plain.ports, [{ port: GAME_PORT, protocol: 'Both', name: 'FiveM server' }], 'plain: opens 30120 (TCP and UDP) in the sandbox firewall');
+        const redm = servePlan({ ...base, game: 'rdr3' });
+        const g = redm.args.indexOf('gamename');
+        t.check(g > 0 && redm.args[g - 1] === '+set' && redm.args[g + 1] === 'rdr3', 'RedM: +set gamename rdr3');
+        t.check(redm.args.indexOf('gamename') < redm.args.indexOf('+exec'), 'and before the cfgs (they can still change it)');
+        const noKey = servePlan({ ...base, secretsCfg: null });
+        t.check(noKey.args.filter((a) => a === '+exec').length === 1, 'no key handed over: only server.cfg');
+        const withDb = servePlan({ ...base, mysqlPort: 3307 });
+        const m = withDb.args.indexOf('mysql_connection_string');
+        t.check(m > 0 &&
+            withDb.args[m + 1] === mysqlConnectionString(3307) &&
+            withDb.args[m + 1] === 'mysql://root@127.0.0.1:3307/fivem?charset=utf8mb4' &&
+            m < withDb.args.indexOf('+exec'), "oxmysql: mysql_connection_string points at the sandbox's MariaDB, set before server.cfg (a line there wins)");
+        const tx = servePlan({ ...base, txAdmin: true, game: 'rdr3', mysqlPort: 3306 });
+        t.check(!tx.args.includes('+exec') &&
+            tx.env.TXHOST_DATA_PATH === base.txData &&
+            tx.env.TXHOST_TXA_PORT === String(TXADMIN_PORT) &&
+            tx.env.TXHOST_GAME_NAME === 'redm' &&
+            tx.env.TXHOST_DEFAULT_DBPORT === '3306' &&
+            !Object.keys(tx.env).includes('TXHOST_DEFAULT_CFXKEY') &&
+            tx.ports.some((p) => p.port === TXADMIN_PORT && p.protocol === 'TCP') &&
+            tx.ports.some((p) => p.port === GAME_PORT), 'txAdmin: no +exec, txData in state\\fivem through TXHOST_*, RedM recipes, the database, ports 30120 and 40120; the key is never prefilled', JSON.stringify(tx));
+        t.section('scaffolds');
+        const templates = path.join(t.packageRoot, 'sandbox', 'templates', 'fivem');
+        const server = t.dir('fivem-server');
+        t.equal(initServerFolder(templates, server, 'myserver', 'gta5'), ['server.cfg', 'resources\\[local]'], 'init writes server.cfg and resources\\[local]');
+        const cfgText = fs.readFileSync(path.join(server, 'server.cfg'), 'utf8');
+        t.check(!/^\s*(sv_licenseKey|set\s+steam_webApiKey)/m.test(cfgText) &&
+            cfgText.includes('endpoint_add_udp "0.0.0.0:30120"') &&
+            !cfgText.includes('{{'), 'the server.cfg template sets no key (only comments name it) and listens on 30120');
+        t.equal(initServerFolder(templates, server, 'myserver', 'gta5'), [], 'init again changes nothing');
+        t.equal(resourceHome(server), path.join(server, 'resources', '[local]'), 'resources go in resources\\[local]');
+        t.equal(resourceHome(project), project, 'outside a server folder: in the folder itself');
+        for (const lang of RESOURCE_LANGS) {
+            const made = scaffoldResource({ templates, lang, name: 'my-' + lang, into: resourceHome(server), game: 'gta5' });
+            const texts = made.files.map((f) => fs.readFileSync(path.join(made.dir, f), 'utf8'));
+            const manifest = fs.readFileSync(path.join(made.dir, 'fxmanifest.lua'), 'utf8');
+            t.check(made.files.length >= 3 &&
+                texts.every((x) => !x.includes('{{')) &&
+                manifest.includes("game 'gta5'") &&
+                manifest.includes("name 'my-" + lang + "'") &&
+                !manifest.includes('rdr3_warning'), lang + ': a resource with its manifest, every placeholder filled', made.files.join(', '));
+        }
+        const cs = fs.readFileSync(path.join(resourceHome(server), 'my-cs', 'Client', 'ClientMain.cs'), 'utf8');
+        t.check(cs.includes('namespace MyCs.Client') &&
+            fs.readFileSync(path.join(resourceHome(server), 'my-cs', 'fxmanifest.lua'), 'utf8').includes('.net.dll'), 'C#: a namespace from the name, and a manifest that loads the *.net.dll builds');
+        t.check(templateFiles(path.join(templates, 'ts')).includes(path.join('src', 'client', 'client.ts')), 'TypeScript: client and server sources with a build script');
+        const red = scaffoldResource({ templates, lang: 'lua', name: 'redres', into: project, game: 'rdr3' });
+        const redManifest = fs.readFileSync(path.join(red.dir, 'fxmanifest.lua'), 'utf8');
+        t.check(redManifest.includes("game 'rdr3'") && redManifest.includes('rdr3_warning'), "RedM: game 'rdr3' and its prerelease acknowledgement");
+        await t.throws(() => scaffoldResource({ templates, lang: 'lua', name: 'redres', into: project, game: 'rdr3' }), 'already exists', 'an existing resource is never overwritten');
+        await t.throws(() => scaffoldResource({ templates, lang: 'lua', name: '..\\escape', into: project, game: 'gta5' }), 'not a resource name', 'a name with a path in it is refused');
+        t.equal(csNamespace('9lives_mod-x'), 'R9livesModX', 'C# namespaces never start with a digit');
+        const ensured = withEnsure('ensure chat\n', 'my-lua');
+        t.check(ensured === 'ensure chat\nensure my-lua\n' &&
+            withEnsure(ensured, 'my-lua') === null &&
+            withEnsure('ensure my-luax', 'my-lua') !== null, 'new adds ensure <name> to server.cfg once');
+        t.section('hints');
+        const hinted = t.dir('fivem-hints');
+        t.write(path.join(hinted, 'resources', '[local]', 'shop', 'fxmanifest.lua'), "fx_version 'cerulean'\nclient_script 'client.lua'\n");
+        const settings = structuredClone(DEFAULTS.toolchains);
+        const h1 = fivemHints(hinted, settings);
+        t.check((h1.fivem ?? '').includes('resources/[local]/shop/fxmanifest.lua') && h1.dotnet === undefined, 'a resource 3 folders down turns fivem on (a Lua one not dotnet)', JSON.stringify(h1));
+        t.write(path.join(hinted, 'resources', '[local]', 'bank', 'fxmanifest.lua'), "fx_version 'cerulean'\nclient_script 'Client/bin/Release/**/publish/*.net.dll'\n");
+        t.check((fivemHints(hinted, settings).dotnet ?? '').includes('C#'), 'a manifest loading *.net.dll turns dotnet on');
+        const csproj = t.dir('fivem-hints-cs');
+        t.write(path.join(csproj, 'res', '__resource.lua'), "resource_manifest_version '44febabe-d386-4d18-afbe-5e627f4af937'\n");
+        t.write(path.join(csproj, 'res', 'Server', 'Server.csproj'), '<Project />');
+        t.check(Boolean(fivemHints(csproj, settings).dotnet), 'so does a .csproj in the resource (or one folder below)');
+        const deep = t.dir('fivem-hints-deep');
+        t.write(path.join(deep, 'a', 'b', 'c', 'd', 'fxmanifest.lua'), '');
+        t.write(path.join(deep, 'node_modules', 'x', 'fxmanifest.lua'), '');
+        t.equal(fivemHints(deep, settings), {}, 'deeper than 3 folders, or under node_modules: no hint');
+        t.equal(fivemHints(hinted, { ...settings, fivem: { ...settings.fivem, enabled: false } }), {}, 'fivem off: no hints');
+        t.section('modding apps');
+        t.check(['lua-language-server', 'stylua', 'selene'].every((id) => APPS.some((a) => a.id === id)) &&
+            MODDING_APPS.every((a) => 'github' in a.source && a.cli === true) &&
+            !APPS.some((a) => a.id === 'codewalker'), 'lua-language-server, StyLua and selene are in the catalogue (GitHub releases with their published SHA-256); CodeWalker is not (no download to check)');
     },
 };

package/dist/selftest/github.test.js

@@ -2,20 +2,28 @@
 // one-shot secrets file), the shared-core operations, the project-file rules, and the gh commands the sandbox runs.
 import fs from 'node:fs';
 import path from 'node:path';
-import { deleteGithubTokenFlow, githubPage, githubTokenRowOf, saveGithubTokenFlow, } from '../app/features/github/index.js';
+import { deleteGithubTokenFlow, expiryOf, githubItem, githubPage, newTokenUrl, tokenUrlFor, githubTokenRowOf, saveGithubTokenFlow, } from '../app/features/github/index.js';
 import { fakeIO } from '../app/kernel/index.js';
 import { runDefinition } from '../app/registry.js';
 import { pageLines } from '../cli/output/index.js';
 import { DEFAULTS } from '../core/config/index.js';
 import { applyOverrides, normalizeOverrides } from '../core/local-config/index.js';
 import { ConfigSchema, LocalOverridesSchema } from '../core/schema/index.js';
-import { checkGithubToken, GithubToken, githubTokenAllowed, prepareGithubToken } from '../host/github/index.js';
+import { checkGithubToken, GithubToken, githubTokenAllowed, prepareGithubToken, verifyGithubToken, } from '../host/github/index.js';
+import { UserError } from '../core/util/index.js';
+import { report } from '../cli/report.js';
+import { toWireError, fromWireError } from '../app/kernel/index.js';
+import { accountsPage } from '../app/features/accounts/index.js';
 import { generateSandbox } from '../host/launch/index.js';
 import { insideSandbox } from '../host/sandbox/platform.js';
 import { clearSecrets, SecretStore } from '../host/secrets/index.js';
 import { RunDir } from '../shared/channel/index.js';
 import { SecretsFileSchema } from '../shared/channel/secrets.js';
 import { ghLoginCommand, ghOutputText, ghSetupGitCommand, githubTokenProblem } from '../shared/github/index.js';
+const okVerdict = () => Promise.resolve({
+    kind: 'ok',
+    check: { login: 'josh', expiresAt: '2027-02-03T10:00:00.000Z', repos: { count: 2, sample: ['josh/a', 'josh/b'] } },
+});
 const FINE = 'github_pat_' + 'PlantedFine0123456789'.repeat(3);
 const CLASSIC = 'ghp_' + 'PlantedClassic0123456789ab';
 const OAUTH = 'gho_' + 'PlantedOauth0123456789abcd';
@@ -86,7 +94,7 @@ export const githubSuite = {
         t.equal(prepareGithubToken(config, config.storage.root, tokens), { notes: [] }, 'off: nothing, and nothing said');
         config.github.shareToken = true;
         const none = prepareGithubToken(config, config.storage.root, tokens);
-        t.check(none.token === undefined && none.notes.some((n) => n.includes('sandbox github login')), 'on without a saved token: not sent, and it says how to save one');
+        t.check(none.token === undefined && none.notes.some((n) => n.includes('Save one')), 'on without a saved token: not sent, and it says how to save one');
         tokens.save(FINE);
         for (const access of ['readonly', 'none']) {
             const strict = structuredClone(config);
@@ -173,15 +181,15 @@ export const githubSuite = {
         t.section('the shared-core operations');
         const featureStore = new GithubToken(t.dir('github-feature'), SecretStore.memory());
         const { io: loginIO, seen: loginSeen } = fakeIO([FINE]);
-        const saved = await saveGithubTokenFlow(loginIO, featureStore);
+        const saved = await saveGithubTokenFlow(loginIO, featureStore, okVerdict);
         t.check(loginSeen.questions.length === 1 &&
             loginSeen.questions[0].kind === 'secret' &&
             featureStore.state() === 'saved' &&
-            loginSeen.logs.some((l) => l.text.includes('personal-access-tokens/new')) &&
+            loginSeen.logs.some((l) => l.text.includes('Make a new token')) &&
             loginSeen.logs.some((l) => l.text.includes('agent in the sandbox can read')), 'login shows the steps, asks exactly one hidden question, saves, and warns the agent can read it', JSON.stringify(loginSeen.questions));
         t.check(!JSON.stringify(saved).includes(FINE) && !JSON.stringify(loginSeen).includes(FINE.slice(12)), 'nothing it returns or logs holds the token');
         const { io: retryIO, seen: retrySeen } = fakeIO([OAUTH, CLASSIC]);
-        await saveGithubTokenFlow(retryIO, featureStore);
+        await saveGithubTokenFlow(retryIO, featureStore, okVerdict);
         t.check(retrySeen.questions.length === 2 &&
             featureStore.kind() === 'classic' &&
             !JSON.stringify(retrySeen).includes(OAUTH.slice(4)) &&
@@ -198,11 +206,14 @@ export const githubSuite = {
             token: 'saved',
             kind: 'classic',
             savedAt: '2026-10-18T10:00:00.000Z',
+            login: null,
+            expiresAt: null,
+            repoCount: null,
+            checkedAt: null,
+            tokenUrl: 'https://github.com/settings/personal-access-tokens/new',
         };
         const lines = pageLines(githubPage(sample)).join('\n');
-        t.check(lines.includes('saved (encrypted)') &&
-            lines.includes('only handed over with "full"') &&
-            lines.includes('classic'), 'the status page says saved, the git access it needs, and the kind', lines);
+        t.check(lines.includes('saved') && lines.includes('only handed over with "full"') && lines.includes('classic'), 'the status page says saved, the git access it needs, and the kind', lines);
         t.equal(githubTokenRowOf({ ...sample, token: 'none' }).hint, 'not saved', 'the Settings row says not saved');
         const { io: logoutIO, seen: logoutSeen } = fakeIO([true]);
         const out = await deleteGithubTokenFlow(logoutIO, featureStore);
@@ -220,6 +231,80 @@ export const githubSuite = {
             await t.throws(() => runDefinition('github.login', {}, {}, io), 'inside the sandbox already', 'github login refuses inside the sandbox');
             t.check(seen.questions.length === 0, 'and asks no question first');
         }
+        t.section('GitHub: the pre-filled link, the check after saving, the expiry');
+        const url = new URL(newTokenUrl({ name: 'Windows Sandbox PC', days: 90, permissions: { contents: 'write', metadata: 'read' } }));
+        t.check(url.origin + url.pathname === 'https://github.com/settings/personal-access-tokens/new' &&
+            url.searchParams.get('name') === 'Windows Sandbox PC' &&
+            url.searchParams.get('expires_in') === '90' &&
+            url.searchParams.get('contents') === 'write' &&
+            url.searchParams.get('metadata') === 'read' &&
+            !url.search.includes('+') &&
+            new URL(tokenUrlFor('BOX')).searchParams.get('workflows') === 'write', 'the new-token link carries the name, days and permissions GitHub documents (and nothing else)');
+        const answer = (status, body, headers = {}) => (u) => Promise.resolve({
+            status,
+            header: (n) => headers[n.toLowerCase()] ?? null,
+            text: u.includes('/user/repos')
+                ? JSON.stringify([{ full_name: 'josh/a' }, { full_name: 'josh/b' }])
+                : JSON.stringify(body),
+        });
+        const good = await verifyGithubToken(FINE, answer(200, { login: 'josh' }, { 'github-authentication-token-expiration': '2027-02-03 10:00:00 UTC' }));
+        t.check(good.kind === 'ok' &&
+            good.check.login === 'josh' &&
+            good.check.expiresAt === '2027-02-03T10:00:00.000Z' &&
+            good.check.repos.count === 2 &&
+            !JSON.stringify(good).includes(FINE), 'a token GitHub accepts: who, when it ends, how many repositories (never the token)');
+        t.equal((await verifyGithubToken(FINE, answer(401, { message: 'Bad credentials' }))).kind, 'refused', 'a 401 is a refusal');
+        const big = () => Promise.reject(new Error('The answer from api.github.com is too big.'));
+        const tooBig = await verifyGithubToken(FINE, big);
+        t.check(tooBig.kind === 'unreachable' && tooBig.reason.includes('too big'), 'an oversize answer is refused, the token is not blamed');
+        const refusedStore = new GithubToken(t.dir('github-refused'), SecretStore.memory());
+        await t.throws(() => saveGithubTokenFlow(fakeIO([FINE]).io, refusedStore, () => Promise.resolve({ kind: 'refused', status: 401 })), 'GitHub refused this token', 'a refused token is not saved');
+        t.check(refusedStore.state() === 'none', 'nothing was written');
+        const checkedStore = new GithubToken(t.dir('github-checked'), SecretStore.memory());
+        await saveGithubTokenFlow(fakeIO([FINE]).io, checkedStore, okVerdict);
+        t.check(checkedStore.check()?.login === 'josh' &&
+            checkedStore.check()?.repoCount === 2 &&
+            !fs.readFileSync(path.join(t.dir('github-checked'), 'github', 'token.json'), 'utf8').includes(FINE), 'what GitHub said is kept beside the sealed token');
+        const now = Date.parse('2027-02-01T00:00:00.000Z');
+        t.equal([
+            expiryOf('2027-02-03T10:00:00.000Z', now)?.tone,
+            expiryOf('2027-04-03T10:00:00.000Z', now)?.tone,
+            expiryOf('2027-01-01T10:00:00.000Z', now)?.tone,
+            expiryOf(null, now),
+        ], ['warn', 'ok', 'danger', null], 'expiry tones: warn under 14 days, danger when expired');
+        const soon = githubItem({ ...sample, token: 'saved', expiresAt: '2027-02-03T10:00:00.000Z', login: 'josh', repoCount: 2 }, now);
+        t.check(soon.badges?.[0].text === 'expires soon' &&
+            (soon.details ?? []).some((d) => d.startsWith('Expires 3 Feb 2027 (in ')), 'the card says "expires soon" and when');
+        const withGithub = accountsPage({ agent: 'claude', agents: [], services: [] }, { services: [] }, { ...sample, token: 'saved' });
+        t.check(withGithub.sections.some((sec) => sec.id === 'github'), 'the Accounts page has a GitHub section');
+        const expiring = new GithubToken(t.dir('github-expiring'), SecretStore.memory());
+        expiring.save(FINE, {
+            login: 'josh',
+            expiresAt: '2027-02-03T10:00:00.000Z',
+            repoCount: 1,
+            checkedAt: '2027-01-01T00:00:00.000Z',
+        });
+        const shareOn = f.makeConfig();
+        shareOn.github.shareToken = true;
+        t.check(prepareGithubToken(shareOn, shareOn.storage.root, expiring, [], Date.parse('2027-01-30T00:00:00.000Z')).notes.some((n) => n.includes('expires in 5 days')) &&
+            !prepareGithubToken(shareOn, shareOn.storage.root, expiring, [], Date.parse('2026-12-01T00:00:00.000Z')).notes.some((n) => n.includes('expires')), 'a launch mentions a token that ends within 7 days, and only then');
+        t.section('errors with an action');
+        const fixable = new UserError('Broke.', 'Do it.', { op: 'sandbox.stop', label: 'Stop it', cli: 'sandbox stop' });
+        const wire = toWireError(fixable);
+        t.check(wire.action?.op === 'sandbox.stop' &&
+            wire.action.label === 'Stop it' &&
+            !JSON.stringify(wire).includes('sandbox stop') &&
+            fromWireError(wire) instanceof UserError, 'the wire error carries the action without the command line');
+        const printed = [];
+        const saveErr = console.error;
+        console.error = (m) => void printed.push(String(m));
+        try {
+            report(fixable);
+        }
+        finally {
+            console.error = saveErr;
+        }
+        t.check(printed.some((l) => l.includes('Run:') && l.includes('sandbox stop')), 'the command line prints "Run: <command>"');
         t.section('gh in the sandbox: the token on stdin only');
         const base = {
             PATH: 'C:\\x',

package/dist/selftest/guest-boot.test.js

@@ -32,6 +32,9 @@ export const guestBootSuite = {
             'would provision uv',
             'would provision Git for Windows from this PC',
         ];
+        const headers = [1, 2, 3, 4, 5, 6, 7, 8, 9].map((n) => boot.out.indexOf('[' + n + '/9] '));
+        t.check(headers.every((at, i) => at >= 0 && (i === 0 || at > headers[i - 1])), 'the boot prints its nine stages, [1/9] to [9/9], in order', headers.join(', '));
+        t.check(boot.out.includes('Boot ready in ') && boot.out.includes('] Developer tools: done in '), 'the boot says how long it took and how long each task took');
         t.equal(steps.filter((s) => !boot.out.includes(s)), [], 'the guest provisions every enabled toolchain');
         t.check(boot.out.includes('AgentSandbox-Block-Private') &&
             boot.out.includes('remoteport=1-52,54-65535') &&

package/dist/selftest/health.test.js

@@ -490,7 +490,7 @@ async function sharedCore(t) {
     const logged = fake.seen.logs.map((l) => l.text).join('\n');
     t.includes(logged, '  [ok] Windows: p1 is fine', 'ioEvents writes a line per result, like the printer');
     t.includes(logged, 'What it means: it hurts', 'ioEvents says what a problem means');
-    t.includes(logged, 'Fix: sandbox repair will mend the cracks', 'ioEvents says what repair would do');
+    t.includes(logged, 'Fix: repair will mend the cracks', 'ioEvents says what repair would do');
     t.includes(logged, 'Repair will change:', 'ioEvents lists the changes before they are made');
     t.includes(logged, '[fixed] Cracks: mended the cracks', 'ioEvents reports a fix on its own line');
     t.equal(featureSummaryText({ total: 9, ok: 6, fixed: 1, warn: 1, needsYou: 1, skipped: 0, fixable: 0 }), '6 ok, 1 fixed, 1 needs you, 1 warning', 'summaryText moved to the feature and reads the same');

package/dist/selftest/index.js

@@ -20,6 +20,7 @@ import { unitySuite } from './unity.test.js';
 import { fivemSuite } from './fivem.test.js';
 import { androidSuite } from './android.test.js';
 import { mobileSuite } from './mobile.test.js';
+import { agentsWebSuite } from './agents-web.test.js';
 import { credentialsSuite } from './credentials.test.js';
 import { vpnSuite } from './vpn.test.js';
 import { githubSuite } from './github.test.js';
@@ -75,7 +76,10 @@ import { workspaceViewSuite } from './workspace-view.test.js';
 import { liveNetworkSuite } from './live-network.test.js';
 import { liveTerminalSuite } from './live-terminal.test.js';
 import { appSuite } from './app.test.js';
+import { uiTextSuite } from './ui-text.test.js';
+import { menuCoverageSuite } from './menu-coverage.test.js';
 import { auditSuite } from './audit.test.js';
+import { bootRunnerSuite } from './boot-runner.test.js';
 import { layoutSuite } from './layout.test.js';
 import { menuSuite } from './menu.test.js';
 import { menuPerfSuite } from './menu-perf.test.js';
@@ -128,6 +132,7 @@ export const SUITES = [
     testGuardSuite,
     // pure helpers and the command line
     layoutSuite,
+    bootRunnerSuite,
     toolchainsSuite,
     persistedInstallsSuite,
     steamSuite,
@@ -136,6 +141,7 @@ export const SUITES = [
     fivemSuite,
     androidSuite,
     mobileSuite,
+    agentsWebSuite,
     detectSuite,
     networkSuite,
     personalizationSuite,
@@ -147,6 +153,8 @@ export const SUITES = [
     repairSuite,
     healthSuite,
     appSuite,
+    uiTextSuite,
+    menuCoverageSuite,
     cliSuite,
     menuSuite,
     menuPerfSuite,

package/dist/selftest/layout.test.js

@@ -15,7 +15,12 @@ const PORTABLE_CORE = [
 const PURE_GUEST = [
     'guest/git/decision.js',
     'guest/setup/git-rules.js',
+    'guest/boot/guide-lines.js',
     'guest/boot/project-env.js',
+    'guest/boot/runner.js',
+    'guest/boot/graph.js',
+    'guest/toolchains/split.js',
+    'guest/toolchains/step-scheduler.js',
     'guest/audit/parse.js',
     'guest/sessions/cmdline.js',
     'guest/agents/agent-files.js',

package/dist/selftest/menu-coverage.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './support/suite.js';
+export declare const menuCoverageSuite: Suite;

package/dist/selftest/menu-coverage.test.js

@@ -0,0 +1,46 @@
+// "All features and config need to be in the cli menu": every command has a place in the menu (or a reason it cannot),
+// every operation and query that skips the menu says why in cli/menu/coverage-exempt.ts, and every setting of the
+// schema is a row of the menu's Settings page.
+import path from 'node:path';
+import { DEFINITIONS } from '../app/features/defs.js';
+import { ConfigFile, settingsOf } from '../app/features/settings/index.js';
+import { exemption } from '../app/kernel/index.js';
+import { COMMANDS } from '../cli/manifest.js';
+import { COMMAND_PLACES, MENU_EXEMPT, SETTING_PLACES } from '../cli/menu/coverage-exempt.js';
+import { SECTION_LABELS } from '../cli/menu/shell.js';
+import { isToolchainReady } from '../shared/readiness.js';
+export const menuCoverageSuite = {
+    name: 'menu-coverage',
+    title: 'menu coverage: every command, operation and setting has a place in the menu, or a written reason',
+    run: (t) => {
+        t.section('commands');
+        const names = COMMANDS.map((c) => c.name);
+        t.equal(names.filter((n) => !(n in COMMAND_PLACES)), [], 'every command has a menu place or an exemption in cli/menu/coverage-exempt.ts');
+        t.equal(Object.keys(COMMAND_PLACES).filter((n) => !names.includes(n)), [], 'the list names no command that is gone');
+        const badPlaces = Object.entries(COMMAND_PLACES).flatMap(([name, p]) => 'place' in p
+            ? SECTION_LABELS.some((s) => p.place.startsWith(s))
+                ? []
+                : [name + ': ' + p.place + ' is not a menu section']
+            : p.exempt.trim().length >= 10
+                ? []
+                : [name + ': the reason is too short']);
+        t.equal(badPlaces, [], 'a place starts with a menu section, an exemption gives a reason');
+        t.section('operations and queries');
+        const exempt = DEFINITIONS.filter((d) => exemption(d, 'menu')?.trim()).map((d) => d.id);
+        t.equal(exempt.filter((id) => !(id in MENU_EXEMPT)), [], 'every definition that skips the menu is on the allow-list with its reason');
+        t.equal(Object.keys(MENU_EXEMPT).filter((id) => !exempt.includes(id)), [], 'the allow-list names no definition that is in the menu or gone');
+        t.section('settings');
+        const file = ConfigFile.user(path.join(t.dir('menu-coverage'), 'config.json'));
+        const rows = new Set(settingsOf(file).map((s) => s.key.join('.')));
+        const placed = (key) => rows.has(key) ||
+            [...rows].some((r) => key.startsWith(r + '.')) ||
+            Object.keys(SETTING_PLACES).some((p) => key === p || (p.endsWith('.') && key.startsWith(p)));
+        const missing = file.schema
+            .leaves()
+            .map((l) => l.key.join('.'))
+            // A toolchain that is not finished is hidden everywhere (shared/readiness.ts), the Settings page included.
+            .filter((key) => !(key.startsWith('toolchains.') && !isToolchainReady(key.split('.')[1])))
+            .filter((key) => !placed(key));
+        t.equal(missing, [], 'every setting of the config schema is a row of the Settings page (or on the allow-list)');
+    },
+};

package/dist/selftest/menu-screens.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Draft } from '../cli/menu/settings/draft.js';
 import { ConfigFile } from '../app/features/settings/index.js';
+import { SERVICE_SPECS } from '../shared/accounts/index.js';
 import { accountsOptions } from '../cli/menu/pages/accounts-page.js';
 import { appsOptions, stageTicks } from '../cli/menu/pages/apps-page.js';
 import { maintenanceOptions } from '../cli/menu/pages/maintenance-page.js';
@@ -34,7 +35,42 @@ const DATA_FOLDER_ROW = [
 ];
 const ACCOUNTS = {
     agent: 'claude',
-    services: [],
+    services: [
+        {
+            kind: 'perplexity',
+            label: SERVICE_SPECS.perplexity.label,
+            share: true,
+            state: 'saved',
+            source: 'pc',
+            savedAt: '2026-10-14T10:00:00Z',
+            summary: 'pplx-...wxyz',
+            heldBy: null,
+            usedBy: ['perplexity'],
+            usedFor: 'the Perplexity MCP app',
+            warnings: [...SERVICE_SPECS.perplexity.warnings],
+            canImport: true,
+            canLogin: true,
+            needsFile: false,
+            ready: true,
+        },
+        {
+            kind: 'comet',
+            label: SERVICE_SPECS.comet.label,
+            share: false,
+            state: 'none',
+            source: null,
+            savedAt: null,
+            summary: null,
+            heldBy: null,
+            usedBy: ['comet'],
+            usedFor: 'the Comet app',
+            warnings: [...SERVICE_SPECS.comet.warnings],
+            canImport: false,
+            canLogin: false,
+            needsFile: false,
+            ready: true,
+        },
+    ],
     agents: [
         {
             name: 'claude',