Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(setup): preserve client config symlinks
N0zoM1z0df87544a5dce
diff --git a/src/application/ClientConfigPath.ts b/src/application/ClientConfigPath.tsnew file mode 100644index 000000000..34b2cf349--- /dev/null+++ b/src/application/ClientConfigPath.ts@@ -0,0 +1,53 @@+import { lstat, realpath } from "node:fs/promises";++interface ClientConfigPathStats {+ readonly uid?: number;+ isFile?(): boolean;+ isSymbolicLink(): boolean;+}++interface ClientConfigPathFileSystem {+ lstat(path: string): Promise<ClientConfigPathStats>;+ realpath?(path: string): Promise<string>;+}++const systemFileSystem: ClientConfigPathFileSystem = { lstat, realpath };++/**+ * Resolve an existing, user-owned config symlink to one stable transaction+ * path. Missing regular paths remain eligible for first-run creation.+ */+export const resolveClientConfigTransactionPath = async (+ requestedPath: string,+ fileSystem: ClientConfigPathFileSystem = systemFileSystem,+): Promise<string | undefined> => {+ let requestedStats: ClientConfigPathStats;+ try {+ requestedStats = await fileSystem.lstat(requestedPath);+ } catch (cause: unknown) {+ return isMissing(cause) ? requestedPath : undefined;+ }+ if (!requestedStats.isSymbolicLink()) return requestedPath;++ const currentUid =+ typeof process.getuid === "function" ? process.getuid() : undefined;+ if (+ currentUid === undefined ||+ requestedStats.uid !== currentUid ||+ fileSystem.realpath === undefined+ )+ return undefined;++ try {+ const canonicalPath = await fileSystem.realpath(requestedPath);+ const targetStats = await fileSystem.lstat(canonicalPath);+ return targetStats.isFile?.() === true && targetStats.uid === currentUid+ ? canonicalPath+ : undefined;+ } catch {+ return undefined;+ }+};++const isMissing = (cause: unknown): boolean =>+ cause instanceof Error && "code" in cause && cause.code === "ENOENT";diff --git a/src/application/Setup.ts b/src/application/Setup.tsindex 639f71d72..523f6a682 100644--- a/src/application/Setup.ts+++ b/src/application/Setup.ts@@ -3,7 +3,6 @@ import {copyFile,mkdir,readFile,- rename,rm,writeFile,} from "node:fs/promises";@@ -15,6 +14,7 @@ import { parse as parseToml, stringify as stringifyToml } from "smol-toml";import { PRODUCT_IDENTITY } from "../identity.js";import { supportsNodeVersion } from "../domain/runtimeVersion.js";+import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";import { runDoctor, systemDoctorHost } from "./Doctor.js";import {installLinuxHopper,@@ -49,7 +49,7 @@ export type ClientConfigurationResult =}| {readonly status: "failed";- readonly reason: "backup" | "write" | "readback";+ readonly reason: "path" | "backup" | "write" | "readback";};/*** Effects required by the idempotent setup workflow.@@ -288,10 +288,15 @@ export const configureJsonClient = async ("mcp",],): Promise<ClientConfigurationResult> => {+ const transactionPath = await resolveClientConfigTransactionPath(+ client.configPath,+ );+ if (transactionPath === undefined)+ return { status: "failed", reason: "path" };let document: Record<string, unknown> = {};let original: string | undefined;try {- original = await readFile(client.configPath, "utf8");+ original = await readFile(transactionPath, "utf8");document = parseObject(original);} catch (cause: unknown) {if (!isMissing(cause)) return { status: "failed", reason: "readback" };@@ -318,7 +323,7 @@ export const configureJsonClient = async (if (original !== undefined) {backupPath = `${client.configPath}.rea.backup`;try {- await copyFile(client.configPath, backupPath);+ await copyFile(transactionPath, backupPath);} catch {return { status: "failed", reason: "backup" };}@@ -328,26 +333,26 @@ export const configureJsonClient = async ([PRODUCT_IDENTITY.mcpServerKey]: desired,};const encoded = `${JSON.stringify(document, null, 2)}\n`;- const temporary = `${client.configPath}.rea.tmp`;try {await mkdir(dirname(client.configPath), { recursive: true });- await writeFile(temporary, encoded, { encoding: "utf8", mode: 0o600 });- await rename(temporary, client.configPath);+ await writeFileAtomic(transactionPath, encoded, {+ encoding: "utf8",+ mode: 0o600,+ });} catch {- await rm(temporary, { force: true }).catch(() => undefined);return { status: "failed", reason: "write" };}try {- const readback = parseObject(await readFile(client.configPath, "utf8"));+ const readback = parseObject(await readFile(transactionPath, "utf8"));const value = parseOptionalObject(readback.mcpServers)[PRODUCT_IDENTITY.mcpServerKey];if (JSON.stringify(value) !== JSON.stringify(desired)) {- await restoreConfig(client.configPath, original);+ await restoreConfig(transactionPath, original);return { status: "failed", reason: "readback" };}} catch {- await restoreConfig(client.configPath, original);+ await restoreConfig(transactionPath, original);return { status: "failed", reason: "readback" };}return {@@ -367,10 +372,15 @@ export const configureTomlClient = async ("mcp",],): Promise<ClientConfigurationResult> => {+ const transactionPath = await resolveClientConfigTransactionPath(+ client.configPath,+ );+ if (transactionPath === undefined)+ return { status: "failed", reason: "path" };let document: Record<string, unknown> = {};let original: string | undefined;try {- original = await readFile(client.configPath, "utf8");+ original = await readFile(transactionPath, "utf8");document = objectSchema.parse(parseToml(original));} catch (cause: unknown) {if (!isMissing(cause)) return { status: "failed", reason: "readback" };@@ -396,7 +406,7 @@ export const configureTomlClient = async (const backupPath =original === undefined ? undefined : `${client.configPath}.rea.backup`;try {- if (backupPath !== undefined) await copyFile(client.configPath, backupPath);+ if (backupPath !== undefined) await copyFile(transactionPath, backupPath);} catch {return { status: "failed", reason: "backup" };}@@ -406,12 +416,12 @@ export const configureTomlClient = async (};try {await mkdir(dirname(client.configPath), { recursive: true });- await writeFileAtomic(client.configPath, stringifyToml(document), {+ await writeFileAtomic(transactionPath, stringifyToml(document), {encoding: "utf8",mode: 0o600,});const readback = objectSchema.parse(- parseToml(await readFile(client.configPath, "utf8")),+ parseToml(await readFile(transactionPath, "utf8")),);if (JSON.stringify(@@ -422,7 +432,7 @@ export const configureTomlClient = async ()throw new Error("TOML readback mismatch");} catch {- await restoreConfig(client.configPath, original);+ await restoreConfig(transactionPath, original);return { status: "failed", reason: "readback" };}return {diff --git a/src/application/SetupClients.ts b/src/application/SetupClients.tsindex bcaca48e0..d8f1eab62 100644--- a/src/application/SetupClients.ts+++ b/src/application/SetupClients.ts@@ -5,8 +5,10 @@ import type {} from "./Setup.js";const failedConfigurationMessage = (- reason: "backup" | "write" | "readback",+ reason: "path" | "backup" | "write" | "readback",): string => {+ if (reason === "path")+ return "Agent configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun setup.";if (reason === "backup")return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";if (reason === "write")diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.tsindex d9a15f7b9..efe3c9329 100644--- a/src/application/Uninstall.ts+++ b/src/application/Uninstall.ts@@ -1,4 +1,4 @@-import { copyFile, lstat, readFile, rm } from "node:fs/promises";+import { copyFile, lstat, readFile, realpath, rm } from "node:fs/promises";import { homedir } from "node:os";import { basename, isAbsolute, join } from "node:path";@@ -7,9 +7,12 @@ import writeFileAtomic from "write-file-atomic";import { z } from "zod";import { PRODUCT_IDENTITY } from "../identity.js";+import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";import { supportedClients, type SetupClient } from "./SupportedClients.js";interface ManagedPathStats {+ readonly uid?: number;+ isFile?(): boolean;isSymbolicLink(): boolean;}@@ -19,6 +22,7 @@ export interface UninstallFileSystem {copy(source: string, destination: string): Promise<void>;writeText(path: string, contents: string): Promise<void>;stat(path: string): Promise<ManagedPathStats>;+ realpath?(path: string): Promise<string>;remove(path: string): Promise<void>;}@@ -28,6 +32,7 @@ const systemFileSystem: UninstallFileSystem = {writeText: (path, contents) =>writeFileAtomic(path, contents, { encoding: "utf8" }),stat: (path) => lstat(path),+ realpath: (path) => realpath(path),remove: (path) => rm(path, { recursive: true }),};@@ -104,9 +109,12 @@ const removeClient = async ("skipped","This client has no documented local MCP configuration boundary.",);+ const resolved = await resolveUninstallConfigPath(client, fileSystem);+ if (typeof resolved !== "string") return resolved;+ const transactionPath = resolved;let original: string;try {- original = await fileSystem.readText(client.configPath);+ original = await fileSystem.readText(transactionPath);} catch (cause: unknown) {return isMissing(cause)? item(client.name, "skipped", "Configuration does not exist.")@@ -146,7 +154,7 @@ const removeClient = async (document[key] = remaining;const backupPath = `${client.configPath}.rea.backup`;try {- await fileSystem.copy(client.configPath, backupPath);+ await fileSystem.copy(transactionPath, backupPath);} catch {return item(client.name,@@ -159,11 +167,11 @@ const removeClient = async (client.format === "toml"? stringifyToml(document): `${JSON.stringify(document, null, 2)}\n`;- await fileSystem.writeText(client.configPath, encoded);+ await fileSystem.writeText(transactionPath, encoded);const readback = objectSchema.parse(client.format === "toml"- ? parseToml(await fileSystem.readText(client.configPath))- : JSON.parse(await fileSystem.readText(client.configPath)),+ ? parseToml(await fileSystem.readText(transactionPath))+ : JSON.parse(await fileSystem.readText(transactionPath)),);if (PRODUCT_IDENTITY.mcpServerKey in optionalObject(readback[key]))throw new Error("registration readback mismatch");@@ -174,7 +182,7 @@ const removeClient = async ();} catch {try {- await fileSystem.writeText(client.configPath, original);+ await fileSystem.writeText(transactionPath, original);} catch {return item(client.name,@@ -190,6 +198,26 @@ const removeClient = async (}};+const resolveUninstallConfigPath = async (+ client: SetupClient,+ fileSystem: UninstallFileSystem,+): Promise<string | UninstallItem> => {+ const path = await resolveClientConfigTransactionPath(+ client.configPath,+ fileSystem.realpath === undefined+ ? { lstat: fileSystem.stat }+ : { lstat: fileSystem.stat, realpath: fileSystem.realpath },+ );+ return (+ path ??+ item(+ client.name,+ "failed",+ "Configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun uninstall.",+ )+ );+};+/** Ownership rule for persistent MCP registrations created by REA setup. */const isOwnedRegistration = (value: unknown): boolean => {const parsed = registrationSchema.safeParse(value);diff --git a/tests/setup.test.ts b/tests/setup.test.tsindex 11c79dfb1..2635be5ed 100644--- a/tests/setup.test.ts+++ b/tests/setup.test.ts@@ -274,6 +274,10 @@ describe("setup workflow", () => {});it.each([+ [+ "path",+ "Agent configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun setup.",+ ],["backup","Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.",diff --git a/tests/setupConfig.test.ts b/tests/setupConfig.test.tsindex d5467df7a..9dd9516ed 100644--- a/tests/setupConfig.test.ts+++ b/tests/setupConfig.test.ts@@ -1,8 +1,16 @@-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";+import {+ lstat,+ mkdtemp,+ readFile,+ rm,+ symlink,+ writeFile,+} from "node:fs/promises";import { tmpdir } from "node:os";import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";+import { resolveClientConfigTransactionPath } from "../src/application/ClientConfigPath.js";import { configureJsonClient } from "../src/application/Setup.js";let directory: string | undefined;@@ -13,6 +21,25 @@ afterEach(async () => {});describe("JSON client configuration transaction", () => {+ it("rejects a symlink target not owned by the current user", async () => {+ if (typeof process.getuid !== "function") return;+ const currentUid = process.getuid();+ let statCalls = 0;+ expect(+ await resolveClientConfigTransactionPath("/config", {+ lstat: () => {+ statCalls += 1;+ return Promise.resolve({+ uid: statCalls === 1 ? currentUid : currentUid + 1,+ isFile: () => statCalls > 1,+ isSymbolicLink: () => statCalls === 1,+ });+ },+ realpath: () => Promise.resolve("/target"),+ }),+ ).toBeUndefined();+ });+it("preserves existing keys, creates a backup, and reads back the MCP entry", async () => {directory = await mkdtemp(join(tmpdir(), "rea-setup-"));const configPath = join(directory, "mcp.json");@@ -34,6 +61,48 @@ describe("JSON client configuration transaction", () => {});});+ it("updates a symlink target without replacing the JSON config symlink", async () => {+ directory = await mkdtemp(join(tmpdir(), "rea-setup-"));+ const targetPath = join(directory, "managed.json");+ const configPath = join(directory, "mcp.json");+ const original = '{"theme":"dark"}\n';+ await writeFile(targetPath, original);+ await symlink(targetPath, configPath);++ expect(+ await configureJsonClient({ name: "cursor", configPath }),+ ).toMatchObject({ status: "configured" });+ expect((await lstat(configPath)).isSymbolicLink()).toBe(true);+ expect(await readFile(`${configPath}.rea.backup`, "utf8")).toBe(original);+ expect(JSON.parse(await readFile(targetPath, "utf8"))).toMatchObject({+ theme: "dark",+ mcpServers: {+ rea: {+ command: "npx",+ args: ["-y", "rea-agents", "mcp"],+ },+ },+ });+ expect(await configureJsonClient({ name: "cursor", configPath })).toEqual({+ status: "unchanged",+ });+ });++ it("fails before mutation when a JSON config symlink is dangling", async () => {+ directory = await mkdtemp(join(tmpdir(), "rea-setup-"));+ const configPath = join(directory, "mcp.json");+ await symlink(join(directory, "missing.json"), configPath);++ expect(await configureJsonClient({ name: "cursor", configPath })).toEqual({+ status: "failed",+ reason: "path",+ });+ expect((await lstat(configPath)).isSymbolicLink()).toBe(true);+ await expect(+ readFile(`${configPath}.rea.backup`, "utf8"),+ ).rejects.toThrow();+ });+it("performs no write or second backup when configuration already matches", async () => {directory = await mkdtemp(join(tmpdir(), "rea-setup-"));const configPath = join(directory, "mcp.json");diff --git a/tests/setupLifecycle.test.ts b/tests/setupLifecycle.test.tsindex 65a8c625d..06ba37dc2 100644--- a/tests/setupLifecycle.test.ts+++ b/tests/setupLifecycle.test.ts@@ -4,7 +4,9 @@ import {mkdtemp,mkdir,readFile,+ realpath,rm,+ symlink,writeFile,} from "node:fs/promises";import { tmpdir } from "node:os";@@ -92,6 +94,44 @@ describe("agent lifecycle", () => {).toEqual({ status: "unchanged" });});+ it("updates a symlink target without replacing the TOML config symlink", async () => {+ const home = await mkdtemp(join(tmpdir(), "rea-toml-symlink-"));+ roots.push(home);+ const configPath = join(home, ".codex/config.toml");+ const targetPath = join(home, "managed-config.toml");+ const original = 'model = "gpt-5"\n';+ await mkdir(dirname(configPath), { recursive: true });+ await writeFile(targetPath, original);+ await symlink(targetPath, configPath);++ expect(+ await configureTomlClient(+ { name: "codex", configPath, format: "toml" },+ undefined,+ ["rea", "mcp"],+ ),+ ).toMatchObject({ status: "configured" });+ expect((await lstat(configPath)).isSymbolicLink()).toBe(true);+ expect(await readFile(`${configPath}.rea.backup`, "utf8")).toBe(original);+ expect(await readFile(targetPath, "utf8")).toContain("[mcp_servers.rea]");+ });++ it("fails before mutation when a TOML config symlink is dangling", async () => {+ const home = await mkdtemp(join(tmpdir(), "rea-toml-symlink-"));+ roots.push(home);+ const configPath = join(home, ".codex/config.toml");+ await mkdir(dirname(configPath), { recursive: true });+ await symlink(join(home, "missing-config.toml"), configPath);++ expect(+ await configureTomlClient({ name: "codex", configPath, format: "toml" }),+ ).toEqual({ status: "failed", reason: "path" });+ expect((await lstat(configPath)).isSymbolicLink()).toBe(true);+ await expect(+ readFile(`${configPath}.rea.backup`, "utf8"),+ ).rejects.toThrow();+ });+it("uninstalls only owned entries and refuses purge symlinks", async () => {const home = await mkdtemp(join(tmpdir(), "rea-uninstall-"));roots.push(home);@@ -131,6 +171,52 @@ describe("agent lifecycle", () => {);});+ it("removes an owned entry through a symlink without replacing it", async () => {+ const home = await mkdtemp(join(tmpdir(), "rea-uninstall-symlink-"));+ roots.push(home);+ const configPath = join(home, ".cursor/mcp.json");+ const targetPath = join(home, "managed-mcp.json");+ const original = JSON.stringify({+ mcpServers: {+ rea: { command: "rea", args: ["mcp"] },+ other: { command: "other" },+ },+ });+ await mkdir(dirname(configPath), { recursive: true });+ await writeFile(targetPath, original);+ await symlink(targetPath, configPath);++ expect((await runUninstall(false, systemUninstallHost(home))).status).toBe(+ "complete",+ );+ expect((await lstat(configPath)).isSymbolicLink()).toBe(true);+ expect(await readFile(`${configPath}.rea.backup`, "utf8")).toBe(original);+ expect(JSON.parse(await readFile(targetPath, "utf8"))).toEqual({+ mcpServers: { other: { command: "other" } },+ });+ });++ it("fails before mutation when an uninstall config symlink is dangling", async () => {+ const home = await mkdtemp(join(tmpdir(), "rea-uninstall-symlink-"));+ roots.push(home);+ const configPath = join(home, ".cursor/mcp.json");+ await mkdir(dirname(configPath), { recursive: true });+ await symlink(join(home, "missing-mcp.json"), configPath);++ const result = await runUninstall(false, systemUninstallHost(home));+ expect(result.status).toBe("failed");+ expect(result.items).toContainEqual({+ name: "cursor",+ status: "failed",+ detail:+ "Configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun uninstall.",+ });+ expect((await lstat(configPath)).isSymbolicLink()).toBe(true);+ await expect(+ readFile(`${configPath}.rea.backup`, "utf8"),+ ).rejects.toThrow();+ });+it("fails closed on malformed client configuration", async () => {const home = await mkdtemp(join(tmpdir(), "rea-uninstall-bad-"));roots.push(home);@@ -228,6 +314,7 @@ const testFileSystem: UninstallFileSystem = {copy: (source, destination) => copyFile(source, destination),writeText: (path, contents) => writeFile(path, contents),stat: (path) => lstat(path),+ realpath: (path) => realpath(path),remove: (path) => rm(path, { recursive: true }),};