From b478a8b011782835128861fa9c1cc98e2d793eb6 Mon Sep 17 00:00:00 2001 From: xeropresence <3128949+xeropresence@users.noreply.github.com> Date: Sun, 11 Oct 2026 00:34:44 -0400 Subject: [PATCH] fix(setup): preserve user fields on an existing REA client entry --- docs/installation.md | 9 ++ .../ClientConfigurationDocument.ts | 68 +++++++++ src/application/SetupClientConfiguration.ts | 24 ++-- src/application/SetupPlan.ts | 4 +- .../clientRegistrationFields.test.ts | 136 ++++++++++++++++++ .../filesystem/ompClientConfiguration.test.ts | 45 ++++++ 6 files changed, 276 insertions(+), 10 deletions(-) create mode 100644 tests/boundary/filesystem/clientRegistrationFields.test.ts diff --git a/docs/installation.md b/docs/installation.md index 02ae1c0af..a10003ce3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -60,6 +60,15 @@ uninstall retain an existing `.rea.backup` rather than replacing the first snaps Setup also retains valid environment overrides in REA's existing server entry, such as `REA_MCP_INPUT_SCHEMA_PROFILE` and `REA_MCP_MAX_RESPONSE_BYTES`. Detected provider settings replace only matching environment keys. +Other fields you added to that entry, such as OMP's `timeout` or Codex's +`tool_timeout_sec`, are kept. Setup rewrites only the launch keys (`command`, +`args`, `type` or `transport`, and the environment map) and REA's +client-specific keys. It removes remote-server keys such as `url` and `headers` +that contradict the local command, and an entry-level `enabled: false` or +(outside Grok Build) `disabled: true`, so the registration is active. An +existing entry without a `command` is a remote server and is replaced whole. A +legacy OpenCode entry moved into the native `mcp.servers` table keeps only its +environment. Setup and doctor report a malformed REA environment map or invalid runtime setting before setup writes files. Repair the named setting in the client configuration; setup does not silently discard the rest of the map. diff --git a/src/application/ClientConfigurationDocument.ts b/src/application/ClientConfigurationDocument.ts index b32df3fd0..c5960cd26 100644 --- a/src/application/ClientConfigurationDocument.ts +++ b/src/application/ClientConfigurationDocument.ts @@ -1498,6 +1498,74 @@ export const clientRegistrationEntry = ( } }; +/** + * Launcher and transport keys REA owns in its entry. A key absent from REA's + * new entry is removed, so a stale `type: "http"` cannot outlive the stdio + * registration and an emptied environment map is not left behind. + */ +const REGISTRATION_LAUNCHER_KEYS: Readonly> = { + command: true, + args: true, + env: true, + environment: true, + type: true, + transport: true, +}; + +/** Remote-server keys that contradict the local command entry REA writes. */ +const REGISTRATION_REMOTE_KEYS: Readonly> = { + url: true, + httpUrl: true, + serverUrl: true, + headers: true, + http_headers: true, + env_http_headers: true, + bearer_token_env_var: true, + oauth: true, +}; + +/** + * Whether setup replaces or removes an existing entry key. Setup registers an + * active server, so entry-level switches that turn it off are removed too. + * Grok Build's entry `disabled` is kept, matching registration status, which + * reads only Grok's root `disabled_mcp_servers` list. + */ +const registrationManagedKey = ( + dialect: ClientRegistrationDialect, + key: string, + value: unknown, +): boolean => + Object.hasOwn(REGISTRATION_LAUNCHER_KEYS, key) || + Object.hasOwn(REGISTRATION_REMOTE_KEYS, key) || + (key === "enabled" && value === false) || + (key === "disabled" && value === true && dialect !== "grok"); + +/** + * Apply REA's new entry over an existing local command entry. REA's keys take + * their new values in place, and every other key the user added (for example + * OMP `timeout` or Codex `tool_timeout_sec`) is kept. An existing entry without + * a `command` is a remote server, which REA replaces whole. + */ +export const retainClientRegistrationFields = ( + dialect: ClientRegistrationDialect, + existing: unknown, + registration: Readonly>, +): Record => { + const current = objectSchema.safeParse(existing); + if (!current.success || !Object.hasOwn(current.data, "command")) + return { ...registration }; + const retained = Object.fromEntries( + Object.entries(current.data).flatMap(([key, value]): [string, unknown][] => + Object.hasOwn(registration, key) + ? [[key, registration[key]]] + : registrationManagedKey(dialect, key, value) + ? [] + : [[key, value]], + ), + ); + return { ...retained, ...registration }; +}; + /** Parse one Gemini policy at its source boundary before consolidating scopes. */ export const parseGeminiMcpPolicy = (parsed: ClientConfigurationDocument) => z diff --git a/src/application/SetupClientConfiguration.ts b/src/application/SetupClientConfiguration.ts index bfab80cbf..5b31174c9 100644 --- a/src/application/SetupClientConfiguration.ts +++ b/src/application/SetupClientConfiguration.ts @@ -13,6 +13,7 @@ import { OMP_DISABLED_SERVERS_KEY, parseClientConfiguration, parseZcodeFallbackConfiguration, + retainClientRegistrationFields, serializeClientConfiguration, withClientServers, type ClientConfigurationDocument, @@ -529,12 +530,19 @@ const clientConfigurationDesired = ( launcher, environment.value, ); - return { - ...registration, - ...(client.name === "codex" || client.name === "grok_build" - ? { - startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds, - } - : {}), - }; + // Keep fields the user added to REA's own entry, such as OMP `timeout`. A + // legacy OpenCode V1 entry migrating into a V2 table keeps only its + // environment, because its other fields belong to the V1 shape. + return retainClientRegistrationFields( + format, + parsed?.servers[PRODUCT_IDENTITY.mcpServerKey], + { + ...registration, + ...(client.name === "codex" || client.name === "grok_build" + ? { + startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds, + } + : {}), + }, + ); }; diff --git a/src/application/SetupPlan.ts b/src/application/SetupPlan.ts index 83402d1a4..aab48bd63 100644 --- a/src/application/SetupPlan.ts +++ b/src/application/SetupPlan.ts @@ -313,8 +313,8 @@ const clientConfigurationDetail = ( .map(([name, value]) => `${name}=${value}`); const environmentDetail = entries.length === 0 - ? " No additional provider environment variables. Existing server environment overrides are retained." - : ` Detected provider environment: ${entries.join(", ")}. Existing server environment overrides are retained; detected values replace matching keys.`; + ? " No additional provider environment variables. Existing server environment overrides are retained, as are other fields on REA's existing entry." + : ` Detected provider environment: ${entries.join(", ")}. Existing server environment overrides are retained; detected values replace matching keys. Other fields on REA's existing entry are retained.`; const hopperDetail = installHopper ? environment.HOPPER_LAUNCHER_PATH === undefined ? " If this plan installs Hopper, REA will add HOPPER_LAUNCHER_PATH using the launcher path reported by that installation." diff --git a/tests/boundary/filesystem/clientRegistrationFields.test.ts b/tests/boundary/filesystem/clientRegistrationFields.test.ts new file mode 100644 index 000000000..a70c7f700 --- /dev/null +++ b/tests/boundary/filesystem/clientRegistrationFields.test.ts @@ -0,0 +1,136 @@ +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect, it } from "vitest"; + +import { + clientRegistrationEntry, + parseClientConfiguration, + serializeClientConfiguration, + type ClientRegistrationDialect, +} from "../../../src/application/ClientConfigurationDocument.js"; +import { + clientConfigurationAligned, + configureClientConfiguration, + inspectClientConfiguration, +} from "../../../src/application/SetupClientConfiguration.js"; +import type { SetupClient } from "../../../src/application/SupportedClients.js"; +import { MCP_STARTUP_POLICY } from "../../../src/mcpStartupPolicy.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +const command = ["rea", "mcp"]; +const environment = { REA_MCP_INPUT_SCHEMA_PROFILE: "compact" }; + +/** Wrap an entry in the server table each dialect reads. */ +const configurationWith = ( + dialect: ClientRegistrationDialect, + entry: unknown, +): Record => { + switch (dialect) { + case "opencode": + return { mcp: { rea: entry } }; + case "opencode_v2": + return { mcp: { servers: { rea: entry } } }; + case "vscode": + return { servers: { rea: entry } }; + case "toml": + case "grok": + case "hermes": + return { mcp_servers: { rea: entry } }; + default: + return { mcpServers: { rea: entry } }; + } +}; + +it.each([ + ["cursor", "json", "json", { timeout: 600000, trust: true }], + ["vscode", "vscode", "vscode", { envFile: ".env" }], + [ + "omp", + "omp", + "omp", + { timeout: 0, enabled: true, instructions: "Use for binaries." }, + ], + ["pi", "pi", "pi", { timeout: 0 }], + ["copilot_cli", "copilot_cli", "copilot_cli", { timeout: 120000 }], + ["commandcode", "commandcode", "commandcode", { timeout: 300 }], + ["opencode", "opencode", "opencode", { timeout: 600000 }], + ["opencode", "opencode", "opencode_v2", { timeout: 600000 }], + [ + "codex", + "toml", + "toml", + { tool_timeout_sec: 900, enabled_tools: ["analyze_function"] }, + ], + ["grok_build", "grok", "grok", { tool_timeout_sec: 900 }], + ["hermes", "hermes", "hermes", { timeout: 600, connect_timeout: 60 }], +] as const)( + "keeps %s fields REA does not manage (%s, %s entry)", + async (name, format, dialect, extras) => { + const root = await createTestTempDirectory("rea-registration-fields-"); + const configPath = join(root, "config"); + const client: SetupClient = { name, format, configPath }; + const existing = { + ...clientRegistrationEntry(dialect, ["rea-old", "mcp"], environment), + ...extras, + // Remote and disabling keys contradict the active stdio entry REA writes. + url: "https://stale.example/mcp", + ...(Object.hasOwn(extras, "enabled") ? {} : { enabled: false }), + }; + await writeFile( + configPath, + serializeClientConfiguration( + configurationWith(dialect, existing), + format, + ), + ); + expect(await inspectClientConfiguration(client, {}, command)).toMatchObject( + { status: "update" }, + ); + expect( + await configureClientConfiguration(client, {}, command), + ).toMatchObject({ status: "configured" }); + const configured = await readFile(configPath, "utf8"); + expect(parseClientConfiguration(configured, format).servers.rea).toEqual({ + ...clientRegistrationEntry(dialect, command, environment), + ...(name === "codex" || name === "grok_build" + ? { + startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds, + } + : {}), + ...extras, + }); + expect(await clientConfigurationAligned(client, {}, command)).toBe(true); + expect(await inspectClientConfiguration(client, {}, command)).toEqual({ + status: "already_current", + }); + expect(await configureClientConfiguration(client, {}, command)).toEqual({ + status: "unchanged", + }); + expect(await readFile(configPath, "utf8")).toBe(configured); + }, +); + +it("replaces a remote server entry instead of merging its fields", async () => { + const root = await createTestTempDirectory("rea-registration-remote-"); + const configPath = join(root, "mcp.json"); + const client: SetupClient = { name: "cursor", format: "json", configPath }; + await writeFile( + configPath, + JSON.stringify({ + mcpServers: { + rea: { + url: "https://stale.example/mcp", + headers: { Authorization: "Bearer stale" }, + timeout: 5000, + }, + }, + }), + ); + expect(await configureClientConfiguration(client, {}, command)).toMatchObject( + { status: "configured" }, + ); + expect( + parseClientConfiguration(await readFile(configPath, "utf8"), "json").servers + .rea, + ).toEqual(clientRegistrationEntry("json", command, {})); +}); diff --git a/tests/boundary/filesystem/ompClientConfiguration.test.ts b/tests/boundary/filesystem/ompClientConfiguration.test.ts index bb5928a8d..b43e1af6c 100644 --- a/tests/boundary/filesystem/ompClientConfiguration.test.ts +++ b/tests/boundary/filesystem/ompClientConfiguration.test.ts @@ -168,4 +168,49 @@ describe("OMP disabledServers denylist", () => { expect(await status()).toMatchObject({ state: "invalid" }); expect(join(home, ".omp", "agent", "mcp.json")).toBe(client.configPath); }); + + it("keeps the entry's timeout through setup and reports it aligned", async () => { + const { home, client } = await ompClient(); + const entry = resolve("scripts/rea.mjs"); + const current = [process.execPath, entry, "mcp"]; + const env = { REA_MCP_INPUT_SCHEMA_PROFILE: "compact" }; + await writeFile( + client.configPath, + JSON.stringify({ + mcpServers: { + rea: { + type: "stdio", + command: join(home, "old", "bun"), + args: [join(home, "old", "rea.mjs"), "mcp"], + env, + timeout: 0, + }, + }, + }), + ); + expect( + (await configureClientConfiguration(client, {}, current)).status, + ).toBe("configured"); + const configured = await readFile(client.configPath, "utf8"); + expect(parseJsonc(configured)).toEqual({ + mcpServers: { + rea: { + type: "stdio", + command: process.execPath, + args: [entry, "mcp"], + env, + timeout: 0, + }, + }, + }); + expect(await configureClientConfiguration(client, {}, current)).toEqual({ + status: "unchanged", + }); + expect(await readFile(client.configPath, "utf8")).toBe(configured); + expect( + ( + await readClientRegistrationStatuses(home, entry, { environment: {} }) + ).find(({ client: name }) => name === "omp"), + ).toMatchObject({ state: "aligned", remediation: null }); + }); });