import { createRequire } from "node:module"; import { mkdir, writeFile } from "node:fs/promises"; import { delimiter, join } from "node:path"; import { pathToFileURL } from "node:url"; import { Ajv2020 } from "ajv/dist/2020.js"; import { beforeAll, expect, it } from "vitest"; import { z } from "zod"; import { mcpRegistrationReportSchema } from "./contracts/mcpRegistration.js"; import { createTestWorkspace, removeTestWorkspace, } from "../tests/support/workspace/workspaceFixture.js"; import { createTestProcessRegistry } from "../tests/support/process/processFixture.js"; const require = createRequire(import.meta.url); const CHILD_PROGRAM = ` import { homedir } from 'node:os'; import { join, relative, isAbsolute, delimiter } from 'node:path'; import { mkdir, writeFile, readFile, readdir, realpath, stat } from 'node:fs/promises'; const ambient = process.env.HOME; if (!ambient || await realpath(ambient) !== await realpath(homedir())) throw Error('Actual temporary HOME was not selected before importing writers.'); const root = process.env.REA_REGISTRATION_FIXTURE_ROOT; const inside = (parent, path) => { const part = relative(parent, path); if (part.startsWith('..') || isAbsolute(part)) throw Error('Fixture path escaped owned root.'); }; inside(root, ambient); for (const key of ['USERPROFILE','XDG_CONFIG_HOME','XDG_DATA_HOME','XDG_CACHE_HOME','XDG_STATE_HOME','APPDATA','LOCALAPPDATA']) inside(ambient, process.env[key]); const project = join(root, 'project'); await mkdir(project); process.chdir(project); const bin = join(root, 'bin'); await mkdir(bin); const helperLog = join(root, 'helper-invocations'); const witness = join(bin, 'acquisition.cjs'); await writeFile(witness, "require('node:fs').appendFileSync(process.env.REA_REGISTRATION_HELPER_LOG, 'unexpected acquisition\\n'); process.exit(79);\\n"); for (const runner of ['npx','pnpx','bunx']) { if (process.platform === 'win32') await writeFile(join(bin, runner + '.cmd'), '@"' + process.execPath + '" "' + witness + '"\\r\\n'); else await writeFile(join(bin, runner), '#!' + process.execPath + '\\nrequire(' + JSON.stringify(witness) + ');\\n', { mode: 0o700 }); } const { createCliShell } = await import(${JSON.stringify(new URL("./cli/cliShell.ts", import.meta.url).href)}); const { closeCliResources } = await import(${JSON.stringify(new URL("./cli/cliResources.ts", import.meta.url).href)}); await import(${JSON.stringify(new URL("./cli/mcpRegistration.ts", import.meta.url).href)}); const { resolveMcpRegistrationClients } = await import(${JSON.stringify(new URL("./application/McpRegistrationCatalog.ts", import.meta.url).href)}); const { ArtifactResourceScope } = await import(${JSON.stringify(new URL("./resources/ArtifactResourceScope.ts", import.meta.url).href)}); const preflightResources = new ArtifactResourceScope(); const { parse: parseToml } = await import(${JSON.stringify(pathToFileURL(require.resolve("smol-toml")).href)}); const { parse: parseYaml } = await import(${JSON.stringify(pathToFileURL(require.resolve("yaml")).href)}); const environmentFor = async (name) => { const home = join(root, name); await mkdir(home); const environment = { ...process.env, HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: join(home,'config'), XDG_DATA_HOME: join(home,'data'), XDG_CACHE_HOME: join(home,'cache'), XDG_STATE_HOME: join(home,'state'), APPDATA: join(home,'appdata'), LOCALAPPDATA: join(home,'localappdata'), PATH: bin + delimiter + process.env.PATH, REA_REGISTRATION_HELPER_LOG: helperLog, REA_TEST_CALLER_VISIBLE: 'fixture-only' }; for (const key of ['HOME','USERPROFILE','XDG_CONFIG_HOME','XDG_DATA_HOME','XDG_CACHE_HOME','XDG_STATE_HOME','APPDATA','LOCALAPPDATA']) inside(home, environment[key]); return environment; }; const clis = new WeakMap(); const cliFor = (environment) => { let cli = clis.get(environment); if (!cli) { cli = createCliShell({ selectedEnvironment: environment, registrations: [] }); clis.set(environment, cli); } return cli; }; const serve = async (environment, arguments_) => { let output = '', exitCode = 0; await cliFor(environment).serve(arguments_, { stdout(text) { output += text; }, exit(code) { exitCode = code; } }); const document = JSON.parse(output); if (Array.isArray(document.clients)) for (const client of document.clients) { inside(environment.HOME, client.config_path); if (client.backup_path) inside(environment.HOME, client.backup_path); } return { exitCode, document }; }; const invoke = async (environment, agents, command, global = true) => { // Check the producing paths before granting the public handler any write authority. const targets = await resolveMcpRegistrationClients({ agents, global, cwd: project, home: environment.HOME, platform: process.platform, environment }, preflightResources); if (targets.ok) for (const target of targets.value) inside(global ? environment.HOME : project, target.configPath); return serve(environment, ['mcp','add', ...agents.flatMap(agent => ['--agent', agent]), ...(command === undefined ? [] : ['--command',command]), ...(global ? [] : ['--no-global']), '--json']); }; const exists = async (path) => readFile(path,'utf8').then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; }); const tree = async (path) => (await readdir(path,{recursive:true})).sort(); const command = '"/fixture/server path" "" --mcp'; let result; try { const defaultsEnvironment = await environmentFor('defaults'); const schema = await serve(defaultsEnvironment, ['mcp','add','--schema','--json']); const all = await invoke(defaultsEnvironment, [], undefined); const native = []; for (const client of all.document.clients ?? []) { const text = await readFile(client.config_path, 'utf8'); const parsed = ['codex','grok-build'].includes(client.client) ? parseToml(text) : client.client === 'hermes' ? parseYaml(text,{version:'1.1'}) : client.client === 'goose' ? parseYaml(text,{version:'1.2'}) : JSON.parse(text); const key = client.client === 'amp' ? 'amp.mcpServers' : ['codex','grok-build','hermes'].includes(client.client) ? 'mcp_servers' : ['kilo-code','opencode'].includes(client.client) ? 'mcp' : client.client === 'goose' ? 'extensions' : client.client === 'zed' ? 'context_servers' : client.client === 'vscode' ? 'servers' : 'mcpServers'; const entry = parsed[key]?.rea; const words = client.client === 'goose' ? [entry?.cmd,...entry?.args ?? []] : Array.isArray(entry?.command) ? entry.command : [entry?.command,...entry?.args ?? []]; native.push({ client: client.client, command: words[0], args: words.slice(1), ambientPersisted: Object.values(entry ?? {}).some(value => value && typeof value === 'object' && value.REA_TEST_CALLER_VISIBLE !== undefined) }); } const repeatedAll = await invoke(defaultsEnvironment, [], undefined); const mixedEnvironment = await environmentFor('mixed'); const cursorPath = join(mixedEnvironment.HOME,'.cursor','mcp.json'); const ampPath = join(mixedEnvironment.HOME,'.config','amp','settings.json'); const cursorOriginal = JSON.stringify({mcpServers:{rea:{command:'old',args:['old'],env:{KEEP:'fixture'},disabled:true,custom:{policy:'retained'}},peer:{command:'peer'}},theme:'dark'}) + '\\n'; const ampOriginal = JSON.stringify({'amp.mcpServers':{rea:{command:'old',args:['old'],env:{KEEP:'amp-fixture'},disabled:false},peer:{command:'peer'}},theme:'dark'}) + '\\n'; await mkdir(join(mixedEnvironment.HOME,'.cursor'),{recursive:true}); await writeFile(cursorPath,cursorOriginal); await mkdir(join(mixedEnvironment.HOME,'.config','amp'),{recursive:true}); await writeFile(ampPath,ampOriginal); const mixed = await invoke(mixedEnvironment,['cursor','amp'],command); const mixedBytes = [await readFile(cursorPath,'utf8'),await readFile(ampPath,'utf8')]; const inodeBefore = [(await stat(cursorPath)).ino,(await stat(ampPath)).ino]; const mixedRepeat = await invoke(mixedEnvironment,['cursor','amp'],command); const inodeAfter = [(await stat(cursorPath)).ino,(await stat(ampPath)).ino]; const mixedChecks = { cursor:JSON.parse(mixedBytes[0]),amp:JSON.parse(mixedBytes[1]),backupsMatch:(await readFile(cursorPath+'.rea.backup','utf8'))===cursorOriginal && (await readFile(ampPath+'.rea.backup','utf8'))===ampOriginal, inodePreserved:JSON.stringify(inodeBefore)===JSON.stringify(inodeAfter), backupFiles:(await tree(mixedEnvironment.HOME)).filter(path=>path.includes('.rea.backup')) }; const failureEnvironment = await environmentFor('partial'); const broken = join(failureEnvironment.HOME,'.cursor','mcp.json'); await mkdir(join(failureEnvironment.HOME,'.cursor')); await writeFile(broken,'{"mcpServers":[]}'); const failedThenSuccess = await invoke(failureEnvironment,['cursor','amp'],command); const successThenFailed = await invoke(failureEnvironment,['amp','cursor'],'"/fixture/server path" "" --changed'); const malformedRetained = await readFile(broken,'utf8'); const runnerEnvironment = await environmentFor('runner-launchers'); const runners = []; for (const runner of ['npx','pnpx','bunx']) { const invocation = await invoke(runnerEnvironment,['cursor'],runner + ' "" package --mcp'); const entry = JSON.parse(await readFile(join(runnerEnvironment.HOME,'.cursor','mcp.json'),'utf8')).mcpServers.rea; runners.push({runner,invocation,entry}); } const refusedEnvironment = await environmentFor('refused'); const refusedBefore = await tree(refusedEnvironment.HOME); const refused = []; for (const agents of [['cursor','goose'],['cursor','amp'],[]]) refused.push(await invoke(refusedEnvironment,agents,command,false)); const refusedAfter = await tree(refusedEnvironment.HOME); const remoteEnvironment = await environmentFor('remote-refused'); const remoteBefore = await tree(remoteEnvironment.HOME); const remote = []; for (const source of ['https://fixture.invalid/mcp','https://fixture-user:fixture-secret@fixture.invalid/mcp']) remote.push(await invoke(remoteEnvironment,['cursor'],source)); const remoteDidNotWrite = JSON.stringify(remoteBefore) === JSON.stringify(await tree(remoteEnvironment.HOME)); result = { remote,remoteDidNotWrite, schema,all,native,repeatedAll,mixed,mixedRepeat,mixedChecks,failedThenSuccess,successThenFailed,malformedRetained,runners,refused,refusalDidNotWrite:JSON.stringify(refusedBefore)===JSON.stringify(refusedAfter),ambientUnchanged:(await tree(ambient)).length===0,helperAcquisition:await exists(helperLog),expectedDefault:{command:process.execPath,args:[process.argv[1],'mcp']} }; } finally { await closeCliResources(); await preflightResources.close(); } console.log(JSON.stringify(result)); `; const invocationSchema = z.object({ exitCode: z.number(), document: z.unknown(), }); const observationsSchema = z.object({ schema: invocationSchema, all: invocationSchema, repeatedAll: invocationSchema, mixed: invocationSchema, mixedRepeat: invocationSchema, failedThenSuccess: invocationSchema, successThenFailed: invocationSchema, native: z.array( z.object({ client: z.string(), command: z.string(), args: z.array(z.string()), ambientPersisted: z.boolean(), }), ), expectedDefault: z.object({ command: z.string(), args: z.array(z.string()) }), mixedChecks: z.object({ cursor: z.unknown(), amp: z.unknown(), backupsMatch: z.boolean(), inodePreserved: z.boolean(), backupFiles: z.array(z.string()), }), runners: z.array( z.object({ runner: z.enum(["npx", "pnpx", "bunx"]), invocation: invocationSchema, entry: z.unknown(), }), ), malformedRetained: z.string(), refused: z.array(invocationSchema), remote: z.array(invocationSchema), remoteDidNotWrite: z.boolean(), refusalDidNotWrite: z.boolean(), ambientUnchanged: z.boolean(), helperAcquisition: z.boolean(), }); const captureRegistration = async () => { const { root } = await createTestWorkspace("rea-cli-registration-matrix-"); const processes = createTestProcessRegistry(); try { const home = join(root, "ambient"); await mkdir(home); const entry = join(root, "entry.mjs"); await writeFile(entry, CHILD_PROGRAM); const child = await processes.run( process.execPath, ["--import", "tsx", entry], { timeoutMs: 20_000, env: { PATH: join(root, "bin") + delimiter + process.env.PATH, SystemRoot: process.env.SystemRoot, WINDIR: process.env.WINDIR, TMPDIR: process.env.TMPDIR, TMP: process.env.TMP, TEMP: process.env.TEMP, HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: join(home, "config"), XDG_DATA_HOME: join(home, "data"), XDG_CACHE_HOME: join(home, "cache"), XDG_STATE_HOME: join(home, "state"), APPDATA: join(home, "appdata"), LOCALAPPDATA: join(home, "localappdata"), REA_REGISTRATION_FIXTURE_ROOT: root, REA_LOG_LEVEL: "silent", }, }, ); expect(child.exitCode, child.stderr).toBe(0); return observationsSchema.parse(JSON.parse(child.stdout)); } finally { await processes.shutdown(); await removeTestWorkspace(root); } }; let observed: z.infer; beforeAll(async () => { observed = await captureRegistration(); }, 30_000); it("validates named input/output schemas against every registration report", () => { const schemas = z .object({ inputSchema: z.record(z.string(), z.unknown()), outputSchema: z.record(z.string(), z.unknown()), }) .parse(observed.schema.document); expect(observed.schema.exitCode).toBe(0); const ajv = new Ajv2020({ strict: true, allErrors: true }); const input = ajv.compile(schemas.inputSchema); const output = ajv.compile(schemas.outputSchema); expect( input({ agent: ["cursor", "amp"], command: '"/fixture/server path" "" --mcp', }), JSON.stringify(input.errors), ).toBe(true); expect(input({ agent: "amp" })).toBe(false); for (const invocation of [ observed.all, observed.repeatedAll, observed.mixed, observed.mixedRepeat, observed.failedThenSuccess, observed.successThenFailed, ...observed.runners.map(({ invocation }) => invocation), ]) expect(output(invocation.document), JSON.stringify(output.errors)).toBe( true, ); }); it("preserves default and mixed launcher facts, metadata, backups and no-op identity", () => { const all = mcpRegistrationReportSchema.parse(observed.all.document); expect(observed.all.exitCode).toBe(0); expect(all.ok).toBe(true); expect(all.clients).toHaveLength(26); expect(all.clients.every((client) => client.status === "configured")).toBe( true, ); expect({ command: all.command, args: all.args }).toEqual( observed.expectedDefault, ); for (const native of observed.native) { expect( { command: native.command, args: native.args }, native.client, ).toEqual(observed.expectedDefault); expect(native.ambientPersisted, native.client).toBe(false); } expect(observed.native).toHaveLength(26); const repeated = mcpRegistrationReportSchema.parse( observed.repeatedAll.document, ); expect(observed.repeatedAll.exitCode).toBe(0); expect( repeated.clients.every((client) => client.status === "unchanged"), ).toBe(true); const mixed = mcpRegistrationReportSchema.parse(observed.mixed.document); expect(observed.mixed.exitCode).toBe(0); expect({ command: mixed.command, args: mixed.args }).toEqual({ command: "/fixture/server path", args: ["", "--mcp"], }); expect( mixed.clients.map((client) => ({ client: client.client, status: client.status, })), ).toEqual([ { client: "cursor", status: "configured" }, { client: "amp", status: "configured" }, ]); expect(observed.mixedChecks.cursor).toMatchObject({ mcpServers: { rea: { command: "/fixture/server path", args: ["", "--mcp"], env: { KEEP: "fixture" }, disabled: true, custom: { policy: "retained" }, }, peer: { command: "peer" }, }, theme: "dark", }); expect(observed.mixedChecks.amp).toMatchObject({ "amp.mcpServers": { rea: { command: "/fixture/server path", args: ["", "--mcp"], env: { KEEP: "amp-fixture" }, disabled: false, }, peer: { command: "peer" }, }, theme: "dark", }); expect(observed.mixedChecks.backupsMatch).toBe(true); expect(observed.mixedChecks.inodePreserved).toBe(true); expect(observed.mixedChecks.backupFiles).toHaveLength(2); expect( mcpRegistrationReportSchema .parse(observed.mixedRepeat.document) .clients.every((client) => client.status === "unchanged"), ).toBe(true); }); it("retains actionable failures and completed siblings in either order", () => { const firstFailure = mcpRegistrationReportSchema.parse( observed.failedThenSuccess.document, ); const lastFailure = mcpRegistrationReportSchema.parse( observed.successThenFailed.document, ); expect(observed.failedThenSuccess.exitCode).toBe(1); expect(firstFailure.ok).toBe(false); expect(firstFailure.clients.map((client) => client.status)).toEqual([ "failed", "configured", ]); expect(observed.successThenFailed.exitCode).toBe(1); expect(lastFailure.ok).toBe(false); expect(lastFailure.clients.map((client) => client.status)).toEqual([ "configured", "failed", ]); expect(observed.malformedRetained).toBe('{"mcpServers":[]}'); for (const client of [...firstFailure.clients, ...lastFailure.clients]) if (client.status === "failed") expect(client.error.reason).toContain(".cursor"); }); it("refuses remote transport and project-scope escalation before writes", () => { for (const invocation of observed.remote) { expect(invocation.exitCode).toBe(1); expect(invocation.document).toMatchObject({ code: "VALIDATION_ERROR", fieldErrors: [ expect.objectContaining({ code: "unsupported_transport", path: "command", }), ], }); expect(JSON.stringify(invocation.document)).not.toContain("fixture-secret"); expect(JSON.stringify(invocation.document)).not.toContain("fixture-user"); } expect(observed.remoteDidNotWrite).toBe(true); for (const refused of observed.refused) { expect(refused.exitCode).toBe(1); expect(refused.document).toMatchObject({ code: "VALIDATION_ERROR" }); } expect(observed.refusalDidNotWrite).toBe(true); }); it("preserves runner launcher data without acquisition or ambient writes", () => { for (const { runner, invocation, entry } of observed.runners) { expect(invocation.exitCode).toBe(0); const report = mcpRegistrationReportSchema.parse(invocation.document); expect({ command: report.command, args: report.args }).toEqual({ command: runner, args: ["", "package", "--mcp"], }); expect(entry).toMatchObject({ command: runner, args: ["", "package", "--mcp"], }); } expect(observed.ambientUnchanged).toBe(true); expect(observed.helperAcquisition).toBe(false); });