From ecd92970a4feb43a3ad90850ae837662ce013761 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 12 Oct 2026 04:34:29 +0000 Subject: [PATCH] fix(setup): retain only registration fields doctor can parse Setup kept malformed startup_timeout_sec and tools values that doctor rejects, and the approval plan restated retention rules by client name. Both now use the registration schema and the entry the writer builds. --- docs/installation.md | 5 +- .../ClientConfigurationDocument.ts | 62 ++++++++++++++++--- src/application/ClientRegistrationShape.ts | 56 +++++++++++++++++ src/application/ClientRegistrationStatus.ts | 15 +---- src/application/Setup.planning.test.ts | 34 ++++++++-- src/application/SetupClientConfiguration.ts | 21 +++---- src/application/SetupPlan.ts | 34 +++++----- .../clientRegistrationFields.test.ts | 26 ++++++++ 8 files changed, 192 insertions(+), 61 deletions(-) create mode 100644 src/application/ClientRegistrationShape.ts diff --git a/docs/installation.md b/docs/installation.md index 55c922a7b..5d3ecf387 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -66,8 +66,9 @@ Other fields you added to that entry, such as OMP's `timeout` or Codex's client-specific keys. It removes remote-server keys such as `url`, `headers`, `oauth_resource`, and `tcp` that contradict the local command, and an entry-level `enabled: false` or (outside Grok Build) `disabled: true`, so the registration -is active. A non-boolean `enabled` or `disabled` value is removed too, because -registration status accepts only booleans. An existing entry without a +is active. A registration field that does not parse, including a non-boolean +`enabled` or `disabled` and a malformed `startup_timeout_sec` or `tools`, is +removed too. 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 diff --git a/src/application/ClientConfigurationDocument.ts b/src/application/ClientConfigurationDocument.ts index f3adc7835..bd15cab6c 100644 --- a/src/application/ClientConfigurationDocument.ts +++ b/src/application/ClientConfigurationDocument.ts @@ -23,7 +23,9 @@ import { } from "jsonc-parser"; import { z } from "zod"; +import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js"; import { PRODUCT_IDENTITY } from "../identity.js"; +import { registrationFieldAccepted } from "./ClientRegistrationShape.js"; import type { SetupClient } from "./SupportedClients.js"; import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js"; @@ -1530,14 +1532,16 @@ const REGISTRATION_REMOTE_KEYS: Readonly> = { tcp: true, }; +/** Grok registration status ignores the entry `disabled` flag. */ +const keepsGrokDisabledFlag = (dialect: ClientRegistrationDialect): boolean => + dialect === "grok"; + /** * 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. - * Non-boolean `enabled` or `disabled` values are removed as well: registration - * status requires booleans, and retaining a string would leave doctor invalid - * after setup reports success. Grok Build's boolean entry `disabled` is kept, - * matching registration status, which reads only Grok's root - * `disabled_mcp_servers` list. + * A registration-status field that does not parse is removed as well, using + * the same schemas doctor uses, so setup cannot report success for a value + * doctor will reject. Grok Build's boolean entry `disabled` is kept. */ const registrationManagedKey = ( dialect: ClientRegistrationDialect, @@ -1546,9 +1550,9 @@ const registrationManagedKey = ( ): boolean => Object.hasOwn(REGISTRATION_LAUNCHER_KEYS, key) || Object.hasOwn(REGISTRATION_REMOTE_KEYS, key) || - ((key === "enabled" || key === "disabled") && typeof value !== "boolean") || + !registrationFieldAccepted(key, value) || (key === "enabled" && value === false) || - (key === "disabled" && value === true && dialect !== "grok"); + (key === "disabled" && value === true && !keepsGrokDisabledFlag(dialect)); /** * Apply REA's new entry over an existing local command entry. REA's keys take @@ -1576,6 +1580,50 @@ export const retainClientRegistrationFields = ( return { ...retained, ...registration }; }; +/** Codex and Grok Build always receive REA's startup timeout. */ +export const applyRegistrationStartupTimeout = ( + clientName: string, + registration: Readonly>, +): Record => + clientName === "codex" || clientName === "grok_build" + ? { + ...registration, + startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds, + } + : { ...registration }; + +/** + * Approval-plan text for the retention rules above. Rewritten keys are the + * ones the fresh entry sets beyond its launcher, so the sentence cannot name + * a field the writer does not replace. + */ +export const describeClientRegistrationRetention = ( + clientName: string, + dialect: ClientRegistrationDialect, +): string => { + const replaced = Object.entries( + applyRegistrationStartupTimeout( + clientName, + clientRegistrationEntry(dialect, ["rea", "mcp"], {}), + ), + ) + .filter(([key]) => !Object.hasOwn(REGISTRATION_LAUNCHER_KEYS, key)) + .sort(([left], [right]) => left.localeCompare(right)) + .map(([key, value]) => `${key} with ${JSON.stringify(value)}`); + const removed = keepsGrokDisabledFlag(dialect) + ? "Remote-server keys, an enabled: false switch, and registration fields that do not parse are removed. A boolean disabled value is kept." + : "Remote-server keys, switches that turn the server off, and registration fields that do not parse are removed."; + const replacement = + replaced.length === 0 + ? removed + : `Setup replaces ${replaced.join(" and ")}. ${removed}`; + const legacy = + clientName === "opencode" + ? " A legacy OpenCode entry moved into the native server table keeps only its environment." + : ""; + return `On an existing local command entry, other user fields are kept. ${replacement} When that entry is remote, its other fields are replaced.${legacy}`; +}; + /** Parse one Gemini policy at its source boundary before consolidating scopes. */ export const parseGeminiMcpPolicy = (parsed: ClientConfigurationDocument) => z diff --git a/src/application/ClientRegistrationShape.ts b/src/application/ClientRegistrationShape.ts new file mode 100644 index 000000000..981c422ec --- /dev/null +++ b/src/application/ClientRegistrationShape.ts @@ -0,0 +1,56 @@ +import { z } from "zod"; + +/** + * Optional fields `registration status` parses on every client. User fields + * outside this set, such as OMP `timeout`, are not registration-status fields. + * Setup and doctor share these schemas so a retained value cannot be one + * doctor will reject. + */ +const registrationFields = { + startup_timeout_sec: z.number().positive(), + type: z.string(), + transport: z.string(), + serverName: z.string(), + tools: z.array(z.string()), + disabled: z.boolean(), + enabled: z.boolean(), +} as const; + +export const registrationSchema = z + .object({ + command: z.string().min(1), + args: z.array(z.string()).default([]), + startup_timeout_sec: registrationFields.startup_timeout_sec.optional(), + type: registrationFields.type.optional(), + transport: registrationFields.transport.optional(), + serverName: registrationFields.serverName.optional(), + tools: registrationFields.tools.optional(), + disabled: registrationFields.disabled.optional(), + enabled: registrationFields.enabled.optional(), + }) + .passthrough(); + +/** Whether a retained entry value is one registration status can parse. */ +export const registrationFieldAccepted = ( + key: string, + value: unknown, +): boolean => { + switch (key) { + case "startup_timeout_sec": + return registrationFields.startup_timeout_sec.safeParse(value).success; + case "type": + return registrationFields.type.safeParse(value).success; + case "transport": + return registrationFields.transport.safeParse(value).success; + case "serverName": + return registrationFields.serverName.safeParse(value).success; + case "tools": + return registrationFields.tools.safeParse(value).success; + case "disabled": + return registrationFields.disabled.safeParse(value).success; + case "enabled": + return registrationFields.enabled.safeParse(value).success; + default: + return true; + } +}; diff --git a/src/application/ClientRegistrationStatus.ts b/src/application/ClientRegistrationStatus.ts index e2696e088..4c2d2debc 100644 --- a/src/application/ClientRegistrationStatus.ts +++ b/src/application/ClientRegistrationStatus.ts @@ -13,6 +13,7 @@ import { resolve } from "node:path"; import { z } from "zod"; +import { registrationSchema } from "./ClientRegistrationShape.js"; import { PRODUCT_IDENTITY } from "../identity.js"; import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js"; import { @@ -60,20 +61,6 @@ export type UnhealthyClientRegistrationStatus = Exclude< { readonly state: "aligned" } >; -const registrationSchema = z - .object({ - command: z.string().min(1), - args: z.array(z.string()).default([]), - startup_timeout_sec: z.number().positive().optional(), - type: z.string().optional(), - transport: z.string().optional(), - serverName: z.string().optional(), - tools: z.array(z.string()).optional(), - disabled: z.boolean().optional(), - enabled: z.boolean().optional(), - }) - .passthrough(); - /** Inspect supported client registrations without reading their environment. */ export const readClientRegistrationStatuses = async ( home: string, diff --git a/src/application/Setup.planning.test.ts b/src/application/Setup.planning.test.ts index cddaa2264..f4c92be7f 100644 --- a/src/application/Setup.planning.test.ts +++ b/src/application/Setup.planning.test.ts @@ -154,10 +154,10 @@ describe("setup workflow", () => { "configure_client:codex", ]); expect(result.plannedActions[0]?.detail).toContain( - `startup_timeout_sec, which setup sets to ${String(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)}`, + `startup_timeout_sec with ${JSON.stringify(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)}`, ); expect(result.plannedActions[0]?.detail).toContain( - "non-boolean enabled or disabled values, which are removed", + "registration fields that do not parse are removed", ); expect(host.hopperInstalls).toBe(0); expect(host.configurations).toBe(0); @@ -202,6 +202,7 @@ describe("setup approval disclosure", () => { name: "grok_build", displayName: "Grok Build", configPath: "/grok.toml", + format: "grok", }, ]; @@ -211,10 +212,10 @@ describe("setup approval disclosure", () => { ); expect(result.plannedActions[0]?.detail).toContain( - `startup_timeout_sec, which setup sets to ${String(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)}`, + `startup_timeout_sec with ${JSON.stringify(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)}`, ); expect(result.plannedActions[0]?.detail).toContain( - "A boolean entry disabled flag is kept.", + "A boolean disabled value is kept.", ); }); @@ -227,6 +228,7 @@ describe("setup approval disclosure", () => { name: "copilot_cli", displayName: "GitHub Copilot CLI", configPath: "/copilot.json", + format: "copilot_cli", }, ]; @@ -236,7 +238,29 @@ describe("setup approval disclosure", () => { ); expect(result.plannedActions[0]?.detail).toContain( - "tools, which setup sets to every tool", + `tools with ${JSON.stringify(["*"])}`, + ); + }); + + it("discloses that a legacy OpenCode entry keeps only its environment", async () => { + const host = new FakeSetupHost(); + host.hopper = "/Applications/Hopper"; + host.skill = "unchanged"; + host.clients = [ + { + name: "opencode", + displayName: "OpenCode", + configPath: "/opencode.json", + }, + ]; + + const result = await runSetup( + { ...options(false), dryRun: true, clientIds: ["opencode"] }, + host, + ); + + expect(result.plannedActions[0]?.detail).toContain( + "A legacy OpenCode entry moved into the native server table keeps only its environment.", ); }); }); diff --git a/src/application/SetupClientConfiguration.ts b/src/application/SetupClientConfiguration.ts index 5b31174c9..b63bb2929 100644 --- a/src/application/SetupClientConfiguration.ts +++ b/src/application/SetupClientConfiguration.ts @@ -5,6 +5,7 @@ import { } from "./ClientConfigurationFiles.js"; import { err, ok, type Result } from "../domain/result.js"; import { + applyRegistrationStartupTimeout, clientRegistrationEntry, clientConfigurationValuesEqual, clientServerListedDisabled, @@ -27,7 +28,6 @@ import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.j import { PRODUCT_IDENTITY } from "../identity.js"; import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js"; -import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js"; import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js"; import { readRegularFileText, @@ -525,24 +525,17 @@ const clientConfigurationDesired = ( providerEnvironment, ); if (!environment.ok) throw environment.error; - const registration = clientRegistrationEntry( - format, - launcher, - environment.value, + const registration = applyRegistrationStartupTimeout( + client.name, + clientRegistrationEntry(format, launcher, environment.value), ); // 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. + // environment, because its other fields belong to the V1 shape. The approval + // plan states that exception through describeClientRegistrationRetention. return retainClientRegistrationFields( format, parsed?.servers[PRODUCT_IDENTITY.mcpServerKey], - { - ...registration, - ...(client.name === "codex" || client.name === "grok_build" - ? { - startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds, - } - : {}), - }, + registration, ); }; diff --git a/src/application/SetupPlan.ts b/src/application/SetupPlan.ts index 6643c3bce..f87760642 100644 --- a/src/application/SetupPlan.ts +++ b/src/application/SetupPlan.ts @@ -1,6 +1,6 @@ import { join } from "node:path"; -import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js"; +import { describeClientRegistrationRetention } from "./ClientConfigurationDocument.js"; import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js"; import { linuxHopperInstallDisclosure, @@ -263,6 +263,7 @@ const setupPlan = (input: { { name: client.name, label: client.displayName ?? client.name, + format: client.format, }, input.command, input.providerEnvironment, @@ -307,7 +308,11 @@ const majorVersion = (version: string): number => Number.parseInt(version.split(".")[0] ?? "0", 10); const clientConfigurationDetail = ( - client: { readonly name: string; readonly label: string }, + client: { + readonly name: string; + readonly label: string; + readonly format: SetupClient["format"]; + }, command: readonly string[], environment: SetupProviderEnvironment, installHopper: boolean, @@ -315,7 +320,14 @@ const clientConfigurationDetail = ( const entries = Object.entries(environment) .sort(([left], [right]) => compareUnicodeCodePoints(left, right)) .map(([name, value]) => `${name}=${value}`); - const retainedFields = localEntryDisclosure(client.name); + const dialect = + client.format === undefined || client.format === "unsupported" + ? "json" + : client.format; + const retainedFields = describeClientRegistrationRetention( + client.name, + dialect, + ); const environmentDetail = entries.length === 0 ? ` No additional provider environment variables. Existing server environment overrides are retained. ${retainedFields}` @@ -327,19 +339,3 @@ const clientConfigurationDetail = ( : ""; return `Add the REA MCP registration for ${client.label}; preserve unrelated configuration. Command: ${command.map((part) => JSON.stringify(part)).join(" ")}.${environmentDetail}${hopperDetail}`; }; - -/** Say which entry fields setup rewrites, removes, or keeps before approval. */ -const localEntryDisclosure = (clientName: string): string => { - const rewritten = - clientName === "codex" || clientName === "grok_build" - ? `startup_timeout_sec, which setup sets to ${String(MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)}, ` - : clientName === "copilot_cli" - ? "tools, which setup sets to every tool, " - : ""; - const removed = - clientName === "grok_build" - ? "remote-server keys, an enabled: false switch, and non-boolean enabled or disabled values, which are removed. A boolean entry disabled flag is kept." - : "remote-server keys, switches that turn the server off, and non-boolean enabled or disabled values, which are removed."; - const exceptions = rewritten === "" ? removed : `${rewritten}and ${removed}`; - return `On an existing local command entry, user fields are kept except ${exceptions} When that entry is remote, its other fields are replaced.`; -}; diff --git a/tests/boundary/filesystem/clientRegistrationFields.test.ts b/tests/boundary/filesystem/clientRegistrationFields.test.ts index 8dab99100..e82e0a8ef 100644 --- a/tests/boundary/filesystem/clientRegistrationFields.test.ts +++ b/tests/boundary/filesystem/clientRegistrationFields.test.ts @@ -138,6 +138,32 @@ it("drops Codex oauth_resource from a local command entry", async () => { }); }); +it("drops malformed registration fields from a local command entry", async () => { + const root = await createTestTempDirectory("rea-registration-schema-"); + const configPath = join(root, "mcp.json"); + const client: SetupClient = { name: "cursor", format: "json", configPath }; + const existing = { + ...clientRegistrationEntry("json", ["rea-old", "mcp"], environment), + timeout: 600000, + startup_timeout_sec: "30", + tools: "*", + }; + await writeFile( + configPath, + serializeClientConfiguration(configurationWith("json", existing), "json"), + ); + expect(await configureClientConfiguration(client, {}, command)).toMatchObject( + { status: "configured" }, + ); + expect( + parseClientConfiguration(await readFile(configPath, "utf8"), "json").servers + .rea, + ).toEqual({ + ...clientRegistrationEntry("json", command, environment), + timeout: 600000, + }); +}); + it("drops malformed activation switches from a local command entry", async () => { const root = await createTestTempDirectory("rea-registration-switches-"); const configPath = join(root, "mcp.json");