test(setup): run the shared JSON registration contract for CodeBuddy, Droid, FreeBuff and Trae (#12716)

Share the mcpServers upsert, create-table, empty-file, and uninstall cases
through jsonClientRegistrationContract. Trae and FreeBuff pass a location
resolver because their paths are not join(home, directory, filename).

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
This commit is contained in:
morlutoandCursor Agent authored and GitHub committed 2026-11-19 23:04:24 -05:00
1 parent e1218b0388
commit fa918a35f5
5 files changed
+135 -442

No files matched your search

@@ -1,20 +1,12 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { readClientRegistrationStatuses } from "../../../src/application/ClientRegistrationStatus.js";
import { currentClientRegistrationCommand } from "../../../src/application/ClientRegistrationIdentity.js";
import { configureClientConfiguration } from "../../../src/application/SetupClientConfiguration.js";
import { skillDestinations } from "../../../src/application/SetupSkill.js";
import { supportedClients } from "../../../src/application/SupportedClients.js";
import { systemUninstallHost } from "../../../src/application/Uninstall.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";
const command = currentClientRegistrationCommand({
platform: process.platform,
});
import { jsonClientRegistrationContract } from "../../support/jsonClientRegistrationContract.js";
beforeEach(clearClientLocationEnvironment);
afterEach(() => vi.unstubAllEnvs());
@@ -56,97 +48,11 @@ describe("CodeBuddy configuration paths", () => {
});
});
describe("CodeBuddy JSON registration", () => {
const codebuddyClient = async () => {
const home = await createTestTempDirectory("rea-codebuddy-");
const client = codebuddyPath(home, process.platform);
if (client?.markerPath === undefined)
throw new Error("missing CodeBuddy client");
await mkdir(client.markerPath, { recursive: true });
return { home, client };
};
it("upserts rea into mcpServers while preserving unrelated settings", async () => {
const { home, client } = await codebuddyClient();
await writeFile(
client.configPath,
`{
"mcpServers": {
"other": { "command": "other-server" }
}
}`,
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
expect(await configureClientConfiguration(client, {}, command)).toEqual({
status: "unchanged",
});
expect(
(
await readClientRegistrationStatuses(home, undefined, {
platform: process.platform,
environment: {},
})
).find(({ client }) => client === "codebuddy"),
).toMatchObject({ state: "aligned", command });
});
it("creates the mcpServers table in an existing mcp.json without servers", async () => {
const { client } = await codebuddyClient();
await writeFile(
client.configPath,
JSON.stringify({ unrelated: { setting: true } }, null, 2),
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.unrelated).toEqual({ setting: true });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("registers into an empty mcp.json", async () => {
const { client } = await codebuddyClient();
await writeFile(client.configPath, "");
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("removes only the rea entry on uninstall", async () => {
const { home, client } = await codebuddyClient();
await writeFile(
client.configPath,
JSON.stringify(
{ mcpServers: { other: { command: "other-server" } } },
null,
2,
),
);
await configureClientConfiguration(client, {}, command);
expect((await systemUninstallHost(home).removeClient(client)).status).toBe(
"removed",
);
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.rea).toBeUndefined();
});
jsonClientRegistrationContract({
clientName: "codebuddy",
displayName: "CodeBuddy",
directory: ".codebuddy",
filename: "mcp.json",
initialSettings: {},
settingsWithoutServers: { unrelated: { setting: true } },
});
@@ -1,25 +1,12 @@
import { currentClientRegistrationCommand } from "../../../src/application/ClientRegistrationIdentity.js";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { readClientRegistrationStatuses } from "../../../src/application/ClientRegistrationStatus.js";
import { configureClientConfiguration } from "../../../src/application/SetupClientConfiguration.js";
import { skillDestinations } from "../../../src/application/SetupSkill.js";
import { supportedClients } from "../../../src/application/SupportedClients.js";
import { systemUninstallHost } from "../../../src/application/Uninstall.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";
/**
* The registration command setup writes on the host running the tests. Windows
* wraps it in `cmd.exe /d /c`, so the expected entry follows the host too.
*/
const command = currentClientRegistrationCommand({
platform: process.platform,
});
import { jsonClientRegistrationContract } from "../../support/jsonClientRegistrationContract.js";
beforeEach(clearClientLocationEnvironment);
afterEach(() => vi.unstubAllEnvs());
@@ -79,115 +66,23 @@ describe("Factory Droid configuration paths", () => {
});
});
describe("Factory Droid JSON registration", () => {
const droidClient = async () => {
const home = await createTestTempDirectory("rea-droid-");
const client = droidPath(home, process.platform);
if (client?.markerPath === undefined)
throw new Error("missing Factory Droid client");
await mkdir(client.markerPath, { recursive: true });
return { home, client };
};
it("upserts rea into mcpServers while preserving unrelated servers and permissions", async () => {
const { home, client } = await droidClient();
await writeFile(
client.configPath,
`{
"mcpServers": {
"other": {
"type": "stdio",
"command": "other",
"args": [],
"disabled": false
}
jsonClientRegistrationContract({
clientName: "droid",
displayName: "Factory Droid",
directory: ".factory",
filename: "mcp.json",
initialSettings: {
persistentPermissions: {
servers: {
other: { approvedAt: "2026-01-01T00:00:00.000Z" },
},
},
},
settingsWithoutServers: { persistentPermissions: { servers: {} } },
unrelatedServer: {
type: "stdio",
command: "other",
args: [],
disabled: false,
},
"persistentPermissions": {
"servers": {
"other": { "approvedAt": "2026-01-01T00:00:00.000Z" }
}
}
}`,
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({
type: "stdio",
command: "other",
args: [],
disabled: false,
});
expect(parsed.persistentPermissions).toEqual({
servers: { other: { approvedAt: "2026-01-01T00:00:00.000Z" } },
});
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
expect(await configureClientConfiguration(client, {}, command)).toEqual({
status: "unchanged",
});
expect(
(
await readClientRegistrationStatuses(home, undefined, {
platform: process.platform,
environment: {},
})
).find(({ client }) => client === "droid"),
).toMatchObject({ state: "aligned", command });
});
it("creates the mcpServers table in an existing config file without servers", async () => {
const { client } = await droidClient();
await writeFile(
client.configPath,
JSON.stringify({ persistentPermissions: { servers: {} } }, null, 2),
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.persistentPermissions).toEqual({ servers: {} });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("registers into an empty config file", async () => {
const { client } = await droidClient();
await writeFile(client.configPath, "");
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("removes only the rea entry on uninstall", async () => {
const { home, client } = await droidClient();
await writeFile(
client.configPath,
JSON.stringify(
{ mcpServers: { other: { command: "other-server" } } },
null,
2,
),
);
await configureClientConfiguration(client, {}, command);
expect((await systemUninstallHost(home).removeClient(client)).status).toBe(
"removed",
);
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.rea).toBeUndefined();
});
});
@@ -33,6 +33,8 @@ import {
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";
import { jsonClientRegistrationContract } from "../../support/jsonClientRegistrationContract.js";
/**
* The registration command setup writes on the host running the tests. Windows
* wraps it in `cmd.exe /d /c`, so the expected entry follows the host too.
@@ -162,7 +164,18 @@ describe("FreeBuff configuration paths", () => {
});
});
describe("FreeBuff JSON registration", () => {
jsonClientRegistrationContract({
clientName: "freebuff",
displayName: "FreeBuff",
resolveLocation: (home) => ({
markerPath: join(home, ".config", "freebuff-desktop"),
configPath: join(home, ".agents", "mcp.json"),
}),
initialSettings: { agents: { discoverSkills: true } },
settingsWithoutServers: { agents: { discoverSkills: true } },
});
describe("FreeBuff shared-row activation", () => {
const freebuffClient = async () => {
const home = await createTestTempDirectory("rea-freebuff-");
const client = freebuffPath(home, process.platform);
@@ -172,42 +185,6 @@ describe("FreeBuff JSON registration", () => {
return { home, client };
};
it("upserts rea into mcpServers while preserving unrelated settings", async () => {
const { home, client } = await freebuffClient();
await writeFile(
client.configPath,
`{
"mcpServers": {
"other": { "command": "other-server" }
},
"agents": { "discoverSkills": true }
}`,
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.agents).toEqual({ discoverSkills: true });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
expect(await configureClientConfiguration(client, {}, command)).toEqual({
status: "unchanged",
});
expect(
(
await readClientRegistrationStatuses(home, undefined, {
platform: process.platform,
environment: {},
})
).find(({ client }) => client === "freebuff"),
).toMatchObject({ state: "aligned", command });
});
it("preserves a shared-row enable:false while repairing FreeBuff", async () => {
// The shared file doubles as ZCode's fallback: its `enable: false` binds
// every reader, so a FreeBuff repair must not silently re-enable the row
@@ -265,56 +242,6 @@ describe("FreeBuff JSON registration", () => {
manual_conflict: "shared_disabled_activation",
});
});
it("creates the mcpServers table in an existing file without servers", async () => {
const { client } = await freebuffClient();
await writeFile(
client.configPath,
JSON.stringify({ agents: { discoverSkills: true } }, null, 2),
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.agents).toEqual({ discoverSkills: true });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("registers into an empty settings file", async () => {
const { client } = await freebuffClient();
await writeFile(client.configPath, "");
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("removes only the rea entry on uninstall", async () => {
const { home, client } = await freebuffClient();
await writeFile(
client.configPath,
JSON.stringify(
{ mcpServers: { other: { command: "other-server" } } },
null,
2,
),
);
await configureClientConfiguration(client, {}, command);
expect((await systemUninstallHost(home).removeClient(client)).status).toBe(
"removed",
);
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.rea).toBeUndefined();
});
});
describe("uninstall applicability for shared FreeBuff storage", () => {
@@ -1,25 +1,12 @@
import { currentClientRegistrationCommand } from "../../../src/application/ClientRegistrationIdentity.js";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join, win32 } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { readClientRegistrationStatuses } from "../../../src/application/ClientRegistrationStatus.js";
import { configureClientConfiguration } from "../../../src/application/SetupClientConfiguration.js";
import { skillDestinations } from "../../../src/application/SetupSkill.js";
import { supportedClients } from "../../../src/application/SupportedClients.js";
import { systemUninstallHost } from "../../../src/application/Uninstall.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";
/**
* The registration command setup writes on the host running the tests. Windows
* wraps it in `cmd.exe /d /c`, so the expected entry follows the host too.
*/
const command = currentClientRegistrationCommand({
platform: process.platform,
});
import { jsonClientRegistrationContract } from "../../support/jsonClientRegistrationContract.js";
beforeEach(clearClientLocationEnvironment);
afterEach(() => vi.unstubAllEnvs());
@@ -87,97 +74,18 @@ describe("Trae configuration paths", () => {
});
});
describe("Trae JSON registration", () => {
const traeClient = async () => {
const home = await createTestTempDirectory("rea-trae-");
const client = traePath(home, process.platform);
if (client?.markerPath === undefined)
throw new Error("missing Trae client");
await mkdir(client.markerPath, { recursive: true });
return { home, client };
};
it("upserts rea into mcpServers while preserving unrelated settings", async () => {
const { home, client } = await traeClient();
await writeFile(
client.configPath,
`{
"mcpServers": {
"other": { "command": "other-server" }
}
}`,
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
expect(await configureClientConfiguration(client, {}, command)).toEqual({
status: "unchanged",
});
expect(
(
await readClientRegistrationStatuses(home, undefined, {
platform: process.platform,
environment: {},
})
).find(({ client }) => client === "trae"),
).toMatchObject({ state: "aligned", command });
});
it("creates the mcpServers table in an existing mcp.json without servers", async () => {
const { client } = await traeClient();
await writeFile(
client.configPath,
JSON.stringify({ unrelated: { setting: true } }, null, 2),
);
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.unrelated).toEqual({ setting: true });
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("registers into an empty mcp.json", async () => {
const { client } = await traeClient();
await writeFile(client.configPath, "");
expect(
(await configureClientConfiguration(client, {}, command)).status,
).toBe("configured");
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
});
});
it("removes only the rea entry on uninstall", async () => {
const { home, client } = await traeClient();
await writeFile(
client.configPath,
JSON.stringify(
{ mcpServers: { other: { command: "other-server" } } },
null,
2,
),
);
await configureClientConfiguration(client, {}, command);
expect((await systemUninstallHost(home).removeClient(client)).status).toBe(
"removed",
);
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.rea).toBeUndefined();
});
jsonClientRegistrationContract({
clientName: "trae",
displayName: "Trae",
resolveLocation: (home, platform) => {
const markerPath =
platform === "darwin"
? join(home, "Library", "Application Support", "Trae", "User")
: platform === "win32"
? join(home, "AppData", "Roaming", "Trae", "User")
: join(home, ".config", "Trae", "User");
return { markerPath, configPath: join(markerPath, "mcp.json") };
},
initialSettings: {},
settingsWithoutServers: { unrelated: { setting: true } },
});
+79 -22
View File
@@ -1,5 +1,5 @@
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { dirname, join } from "node:path";
import { describe, expect, it } from "vitest";
@@ -10,25 +10,77 @@ import { supportedClients } from "../../src/application/SupportedClients.js";
import { systemUninstallHost } from "../../src/application/Uninstall.js";
import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
/** Marker and config paths the registration cases write and read. */
type JsonClientLocation = {
readonly markerPath: string;
readonly configPath: string;
};
const defaultUnrelatedServer = { command: "other-server" } as const;
type JsonClientRegistrationContractInput = {
readonly clientName:
| "codebuddy"
| "droid"
| "freebuff"
| "qoder"
| "trae"
| "workbuddy";
readonly displayName: string;
readonly initialSettings: Record<string, unknown>;
readonly settingsWithoutServers: Record<string, unknown>;
/**
* Sibling server left beside `rea`. Defaults to `{ command: "other-server" }`.
* A caller passes its own object when that object is the preserved caller data.
*/
readonly unrelatedServer?: Record<string, unknown>;
} & (
| {
readonly directory: string;
readonly filename: string;
readonly resolveLocation?: undefined;
}
| {
/**
* Expected paths when they are not `join(home, directory, filename)`.
* Trae's directory follows the platform, and FreeBuff's marker and
* config file live in different roots.
*/
readonly resolveLocation: (
home: string,
platform: NodeJS.Platform,
) => JsonClientLocation;
readonly directory?: undefined;
readonly filename?: undefined;
}
);
/** Run the JSON registration contract against each client's independently supplied location. */
export const jsonClientRegistrationContract = ({
clientName,
displayName,
directory,
filename,
initialSettings,
settingsWithoutServers,
}: {
clientName: "qoder" | "workbuddy";
displayName: string;
directory: string;
filename: string;
initialSettings: Record<string, unknown>;
settingsWithoutServers: Record<string, unknown>;
}): void => {
export const jsonClientRegistrationContract = (
options: JsonClientRegistrationContractInput,
): void => {
const {
clientName,
displayName,
initialSettings,
settingsWithoutServers,
unrelatedServer = defaultUnrelatedServer,
} = options;
const command = currentClientRegistrationCommand({
platform: process.platform,
});
const expectedLocation = (home: string): JsonClientLocation => {
if (options.resolveLocation !== undefined)
return options.resolveLocation(home, process.platform);
if (options.directory === undefined || options.filename === undefined)
throw new Error(
`${displayName} JSON registration needs a directory and filename or a location resolver`,
);
return {
markerPath: join(home, options.directory),
configPath: join(home, options.directory, options.filename),
};
};
describe(`${displayName} JSON registration`, () => {
const createClient = async () => {
@@ -38,9 +90,12 @@ export const jsonClientRegistrationContract = ({
);
if (client?.markerPath === undefined)
throw new Error(`missing ${displayName} client`);
expect(client.markerPath).toBe(join(home, directory));
expect(client.configPath).toBe(join(home, directory, filename));
await mkdir(client.markerPath, { recursive: true });
const location = expectedLocation(home);
expect(client.markerPath).toBe(location.markerPath);
expect(client.configPath).toBe(location.configPath);
// The marker and the config file can live in different directories.
await mkdir(location.markerPath, { recursive: true });
await mkdir(dirname(location.configPath), { recursive: true });
return { home, client };
};
@@ -50,7 +105,7 @@ export const jsonClientRegistrationContract = ({
client.configPath,
JSON.stringify({
...initialSettings,
mcpServers: { other: { command: "other-server" } },
mcpServers: { other: unrelatedServer },
}),
);
expect(
@@ -59,7 +114,7 @@ export const jsonClientRegistrationContract = ({
const parsed = JSON.parse(await readFile(client.configPath, "utf8"));
for (const [key, value] of Object.entries(initialSettings))
expect(parsed[key]).toEqual(value);
expect(parsed.mcpServers.other).toEqual({ command: "other-server" });
expect(parsed.mcpServers.other).toEqual(unrelatedServer);
expect(parsed.mcpServers.rea).toEqual({
command: command[0],
args: command.slice(1),
@@ -112,7 +167,9 @@ export const jsonClientRegistrationContract = ({
const { home, client } = await createClient();
await writeFile(
client.configPath,
JSON.stringify({ mcpServers: { other: { command: "other-server" } } }),
JSON.stringify({
mcpServers: { other: { command: "other-server" } },
}),
);
await configureClientConfiguration(client, {}, command);
expect(