import { appendCallerPath } from "../filesystem/callerPath.js"; import { isClientConfigurationCleanupFailure, retryClientConfigurationCleanup, } from "./ClientConfigurationCleanup.js"; import { ClientConfigurationShapeError, clientConfigurationServersKey, parseClientConfiguration, serializeClientConfiguration, clientServerPath, legacyClientServerPath, shadowedClientServers, withClientServers, type ClientConfigurationDocument, } from "./ClientConfigurationDocument.js"; import { err, ok, type Result } from "../domain/result.js"; import { ConfigurationError } from "../domain/configurationErrors.js"; import { AnalysisError, type AnalysisCleanupObservation, } from "../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { copyFile, lstat, realpath, rm, rmdir } from "node:fs/promises"; import { constants as fsConstants } from "node:fs"; import { isDeepStrictEqual } from "node:util"; import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js"; import { basename, dirname } from "node:path"; import { defaultKunaCacheDirectory, hasParentTraversal, sameLexicalDirectory, withinLexicalDirectory, } from "../config/kunaCacheDirectory.js"; import { defaultDarwinHelperCacheDirectory } from "../process/DarwinHelperCache.js"; import { linuxHopperReleaseCacheDirectory } from "./LinuxHopperCacheDirectory.js"; import { ClientConfigurationPublication } from "./ClientConfigurationPublication.js"; import { effectiveClientConfiguration, type ClientConfigurationSource, } from "./ClientConfigurationFiles.js"; import { clientRegistrationOwnership } from "./ClientRegistration.js"; import { PRODUCT_IDENTITY } from "../identity.js"; import { isManagedSkillManifest, MANAGED_SKILL_FILES, readSkillFile, skillDestinationSelection, } from "./SetupSkill.js"; import { dshDocument } from "./DshCordisPatch.js"; import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js"; import { preserveCurrentRecoveryBackup, type RecoveryBackupPreservationOptions, } from "./SetupRecoveryBackup.js"; import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js"; import { InvalidUtf8FileError, readRegularFileText, bindRegularFileCleanup, } from "./RegularFileRead.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { appDataRedirection, clientOwnershipEvidencePaths, clientSharedRegistrationPaths, manualRegistrationRemediation, registrationWriteBlocker, supportedClients, type SetupClient, } from "./SupportedClients.js"; import { redirectedWriteBlocker, type MsixPackageView, } from "./MsixPackageStorage.js"; interface ManagedPathStats { readonly uid?: number; isFile?(): boolean; isDirectory?(): boolean; isSymbolicLink(): boolean; } /** Injectable filesystem operations used to prove uninstall failure recovery. */ export interface UninstallFileSystem { readText(path: string): Promise; readRegularText?(path: string): Promise; /** Preserve the first backup; reject an existing destination with EEXIST. */ copy(source: string, destination: string): Promise; publishConfiguration( path: string, contents: string, original: string, ): Promise< Pick< ClientConfigurationPublication, "path" | "verify" | "assertCurrent" | "restore" > >; stat(path: string): Promise; realpath?(path: string): Promise; remove(path: string, recursive?: boolean): Promise; /** Remove a directory only if it is empty; a non-empty one is kept. */ removeEmptyDirectory?(path: string): Promise; } const systemFileSystem = ( resources: ArtifactResourceScope, ): UninstallFileSystem => ({ readText: (path) => readRegularFileText(path, { resources }), readRegularText: (path) => readSkillFile(path, resources), copy: (source, destination) => copyFile(source, destination, fsConstants.COPYFILE_EXCL), publishConfiguration: (path, contents, original) => ClientConfigurationPublication.write(path, contents, original), stat: (path) => lstat(path), realpath: (path) => realpath(path), remove: (path, recursive = true) => rm(path, { recursive }), removeEmptyDirectory: (path) => rmdir(path), }); /** One completed or refused action, preserving its candidate configuration path. */ export interface UninstallAction { readonly status: "removed" | "retained" | "skipped" | "failed"; readonly detail: string; readonly configuration_path?: string; } /** One client summary with its constituent actions when multiple paths apply. */ export interface UninstallItem extends UninstallAction { readonly name: string; readonly actions?: readonly UninstallAction[]; } /** Structured, idempotent result of removing REA-owned state. */ export interface UninstallResult { readonly status: "complete" | "failed"; readonly items: readonly UninstallItem[]; readonly cleanup?: AnalysisCleanupObservation | undefined; } /** Applicability established once from product-specific discovery evidence. */ export interface UninstallClient extends SetupClient { readonly applicability?: "unverified"; /** Clients that load this same registration table as a fallback report the * owner's outcome without inspecting or editing the file again. */ readonly sharedWith?: readonly string[]; } /** Filesystem boundary used by the contained uninstall workflow. */ export interface UninstallHost { clients(): Promise; /** Report a configuration that cannot be read safely, before any removal. */ inspectClient(client: UninstallClient): Promise; removeClient(client: UninstallClient): Promise; inspectSkill?(): Promise; removeSkill(): Promise; purgeData(): Promise; close?(): Promise; } /** Preserve the resource owner's explicit retry capabilities through uninstall reporting. */ const uninstallCleanupError = (cause: unknown): AnalysisError => { if ( cause instanceof AnalysisError && (cause.cleanupIncomplete || cause.hasCleanupOwner || cause.cleanup !== undefined || cause instanceof ProviderCleanupError) ) return cause; const cleanup = ArtifactReaderFailure.cleanupObservation(cause, []); const error = new ProviderCleanupError( "uninstall", cleanup.resources, { reason: cleanup.reason }, { cause, cleanup, operation: "uninstall" }, ); bindRegularFileCleanup(cause, error); return error; }; /** * Remove only REA-owned registrations and managed files, optionally including * local state. A client configuration that cannot be read safely stops the * operation before anything is removed; one that fails during removal stops * the remaining removals. */ export const runUninstall = async ( purgeData: boolean, host: UninstallHost = systemUninstallHost(), ): Promise => { let result: UninstallResult | undefined; let primaryFailure: unknown; let failed = false; try { const clients = await host.clients(); const blocked: UninstallItem[] = []; for (const client of clients) { const blocking = await host.inspectClient(client); if (blocking !== undefined) blocked.push({ ...blocking, configuration_path: client.configPath }); } const skillBlocker = await host.inspectSkill?.(); if (skillBlocker !== undefined) blocked.push(skillBlocker); const items: UninstallItem[] = blocked.length > 0 ? [ ...blocked, item( "uninstall", "skipped", "No REA registration, skill, or data was removed. Repair each failed configuration, then rerun uninstall.", ), ] : await removeAll(clients, purgeData, host); items.push({ name: "analysis_engine", status: "retained", detail: "Hopper is not owned by REA uninstall.", }); const reported = collapseUninstallItems( projectSharedRegistrations(items, clients), ); result = { status: reported.some(({ status }) => status === "failed") ? "failed" : "complete", items: reported, }; } catch (cause: unknown) { failed = true; primaryFailure = cause; } let cleanupFailure: AnalysisError | undefined; try { const report = await host.close?.(); cleanupFailure = report === undefined ? undefined : uninstallCleanupError(report); } catch (cause: unknown) { cleanupFailure = uninstallCleanupError(cause); } if (cleanupFailure !== undefined && !cleanupFailure.cleanupIncomplete) cleanupFailure = undefined; if (failed) { if (cleanupFailure !== undefined) { if (primaryFailure instanceof AnalysisError) throw analysisErrorWithCleanupFailure( primaryFailure, cleanupFailure, "uninstall", ).bindCleanupDependencies([primaryFailure, cleanupFailure]); throw new AggregateError( [primaryFailure, cleanupFailure], "Uninstall failed and its resource cleanup remains incomplete.", { cause: primaryFailure }, ); } throw primaryFailure; } if (result === undefined) throw new Error("Uninstall result was not produced."); if (cleanupFailure === undefined) return result; const items = collapseUninstallItems([ ...result.items, item( "uninstall_cleanup", "failed", `Uninstall resource cleanup failed: ${cleanupFailure.cleanup?.reason ?? cleanupFailure.message}${cleanupFailure.cleanupResources.length === 0 ? "" : ` (${cleanupFailure.cleanupResources.join(", ")})`}`, ), ]); const retained = cleanupFailure; return { status: "failed", items, get cleanup() { return retained.cleanupIncomplete ? { reason: retained.cleanup?.reason ?? retained.message, resources: retained.cleanupResources, } : undefined; }, }; }; /** * Reread each client when editing and refuse detected changes before publication. * A client that fails still stops the remaining removals. */ const removeAll = async ( clients: readonly UninstallClient[], purgeData: boolean, host: UninstallHost, ): Promise => { const items: UninstallItem[] = []; const stopped = (): UninstallItem[] => [ ...items, item( "uninstall", "skipped", "Uninstall stopped at this failure; the items above report what changed. Repair the failed removal, then rerun uninstall.", ), ]; for (const client of clients) { const removed = await host.removeClient(client); items.push({ ...removed, configuration_path: client.configPath }); if (removed.status === "failed") return stopped(); } const skill = await host.removeSkill(); items.push(skill); if (skill.status === "failed") return stopped(); if (purgeData) items.push(...(await host.purgeData())); return items; }; /** * Report a shared file's single outcome under every client that loads it. The * owner edits the file once, so a fallback reader reports what happened to its * registration instead of finding it already absent. */ const projectSharedRegistrations = ( items: readonly UninstallItem[], clients: readonly UninstallClient[], ): UninstallItem[] => { const readersByRegistration = new Map(); for (const client of clients) if (client.sharedWith !== undefined && client.sharedWith.length > 0) readersByRegistration.set( JSON.stringify([client.name, client.configPath]), client.sharedWith, ); if (readersByRegistration.size === 0) return [...items]; return items.flatMap((next) => { const readers = next.configuration_path === undefined ? undefined : readersByRegistration.get( JSON.stringify([next.name, next.configuration_path]), ); if (readers === undefined) return [next]; const { name, ...action } = next; return [name, ...readers].map((reader) => ({ ...action, name: reader })); }); }; /** * Ownership is a readable, recognizable REA-owned row, never the shared * file's existence. An unrelated malformed file must not establish ownership; * it stays retained without blocking other removals. */ const hasOwnershipEvidence = async ( client: UninstallClient, fileSystem: UninstallFileSystem, ): Promise => { for (const path of clientOwnershipEvidencePaths(client)) { let original: string; try { original = await fileSystem.readText(path); } catch (cause: unknown) { // A close failure after a completed read still carries the exact text // in its retained outcome, and that text is the ownership fact: only a // read that never completed proves nothing. Preserve it, so later read // failures stay blocking instead of softening to retained. if (!(cause instanceof RegularFileCleanupFailure)) continue; if (cause.outcome.kind !== "completed") continue; const completed: unknown = cause.outcome.value; if (typeof completed !== "string") continue; original = completed; } let parsed: ClientConfigurationDocument; try { parsed = parseClientConfiguration(original, client.format); } catch { // Malformed shared data is retained, never ownership evidence. continue; } const removal = clientRegistrationRemoval(parsed, original, client); // Refusing the edit never retracts the owned-row fact: an effective // REA-owned row shadowed by a foreign duplicate still proves ownership, // so later read failures stay blocking instead of softening to retained. const owned = removal.ok ? removal.value : removal.error.owned; if (owned.removeNative || owned.legacyPath !== undefined) return true; } return false; }; /** Installation evidence for one probed path, never inferred from absence. */ interface DiscoveryProbe { readonly applicable: boolean; readonly unresolved: boolean; } /** A client's shared-storage applicability from its discovery paths: a hit * proves installation, a miss leaves it unproven, and any other probe failure * leaves it unresolved — never absence. */ const discoveryApplicability = async ( discoveryPaths: readonly string[] | undefined, fileSystem: UninstallFileSystem, ): Promise => { if (discoveryPaths === undefined) return { applicable: true, unresolved: false }; let applicable = false; let unresolved = false; for (const path of discoveryPaths) { try { // The product's own directory proves installation, not a leftover link // to it: `stat` is `lstat`, so a dangling profile link passes here even // though setup and doctor, which follow the target, reject it. Resolve // the link for the same answer, keeping `lstat` for removal safety. const stats = await fileSystem.stat(path); if (stats.isSymbolicLink() && fileSystem.realpath !== undefined) await fileSystem.realpath(path); return { applicable: true, unresolved: false }; } catch (cause: unknown) { // Absence keeps scanning until one discovery path exists; any // other probe failure leaves applicability unresolved. if (!isMissing(cause)) unresolved = true; } } return { applicable, unresolved }; }; /** One physical configuration path a client claims. */ interface ClientConfigClaim { readonly client: SetupClient; readonly configPath: string; /** The path is another product's storage this client falls back to. */ readonly fallback: boolean; } /** One physical file, the client whose configuration it is, and the other * clients that load it as a fallback. */ interface SharedConfigPath { readonly owner: ClientConfigClaim; readonly readers: readonly ClientConfigClaim[]; } /** * Resolve each physical configuration file to the clients that edit it. A * client's own configuration owns its registration row; a fallback view only * reports the owner's decision instead of racing it to "absent". Two clients * that each declare the same path as their own configuration keep their own * row, because they write different tables. */ const sharedConfigPaths = ( clients: readonly SetupClient[], ): readonly SharedConfigPath[] => { const claimsByPath = new Map(); for (const client of clients) for (const claim of [ ...uninstallConfigPaths(client).map((configPath) => ({ client, configPath, fallback: false, })), ...(client.zcodeFallbackPath === undefined ? [] : [ { client, configPath: client.zcodeFallbackPath, fallback: true, }, ]), ]) claimsByPath.set(claim.configPath, [ ...(claimsByPath.get(claim.configPath) ?? []), claim, ]); return [...claimsByPath.values()].flatMap((claims): SharedConfigPath[] => { const fallbacks = claims.filter((claim) => claim.fallback); const owners = claims.filter((claim) => !claim.fallback); // A fallback view can only report one client's row. OpenCode can be pointed // at FreeBuff's file through `OPENCODE_CONFIG`, and both then own the path // while writing different tables, so each keeps its own decision. if (owners.length > 0) return owners.map((owner) => { const format = owner.client.format; // ZCode's fallback reads mcpServers, never another table in the same // file (for example OpenCode's mcp table). Use the format owner's // mapping instead of reinterpreting table names here. const readers = format !== undefined && format !== "unsupported" && format !== "dsh" && clientConfigurationServersKey(format) === clientConfigurationServersKey("zcode_fallback") ? fallbacks : []; return { owner, readers }; }); const [only] = fallbacks; if (only === undefined) throw new Error("A configuration path has no claiming client."); return [{ owner: only, readers: [] }]; }); }; /** Create uninstall effects contained to detected client configs and REA-owned paths. */ export const systemUninstallHost = ( selectedHome: string | undefined = undefined, selectedFileSystem: UninstallFileSystem | undefined = undefined, environment: Readonly = process.env, platform: NodeJS.Platform = process.platform, ): UninstallHost => { const home = selectedHome ?? homeDirectoryFromEnvironment(environment, platform); const resources = new ArtifactResourceScope(); // Whole-operation admission must not share a gate with its nested file reads: // a peer's pending cleanup otherwise waits for the operation requesting it. const configurationOperations = new ArtifactResourceScope(); const fileSystem = selectedFileSystem ?? systemFileSystem(resources); const preflightOwnedClients = new WeakSet(); // Set with the client list: the package view that redirects this // process's AppData writes, if any. let redirection: MsixPackageView | undefined; const clientWriteBlocker = (client: SetupClient): string | undefined => registrationWriteBlocker(client, "uninstall") ?? redirectedWriteBlocker(redirection, [client.configPath], "uninstall"); const skillWriteBlocker = (path: string): string | undefined => redirectedWriteBlocker(redirection, [path], "uninstall"); return { clients: async () => { const supported = supportedClients(home, platform, environment); redirection = appDataRedirection(supported); // Shared configuration alone cannot establish product applicability. // Definitive absence leaves the shared paths unverified while owned // rows in a readable configuration can still be removed independently; // an unresolved probe is unknown, never absence. const probes = new Map(); for (const client of supported) probes.set( client.name, await discoveryApplicability(client.discoveryPaths, fileSystem), ); const paths = sharedConfigPaths(supported); const clients: UninstallClient[] = []; for (const client of supported) for (const path of paths) { if (path.owner.client !== client) continue; // A fallback reader constrains this file only while it may load it: // definitive absence leaves the file to its owner. A reader that may // load the owner's registration makes applicability one fact per // physical file, so its installed proof applies and its unresolved // probe keeps the file fail-closed. const readers = path.readers.filter(({ client: reader }) => { const probe = probes.get(reader.name); return probe?.applicable === true || probe?.unresolved === true; }); const probesForPath = [path.owner, ...readers].map( ({ client: participant }) => probes.get(participant.name) ?? { applicable: false, unresolved: false, }, ); // Only definitive absence may soften failures for storage REA does // not own: a denied or failed probe leaves applicability unresolved, // and unresolved applicability must not downgrade shared-config // failures to retained. A denied product-local path means an unknown // registration state, which must stop uninstall instead of reporting // success. const applicability: Pick = probesForPath.some(({ applicable }) => applicable) || probesForPath.some(({ unresolved }) => unresolved) || !clientSharedRegistrationPaths(client).has(path.owner.configPath) ? {} : { applicability: "unverified" }; clients.push({ ...client, configPath: path.owner.configPath, ...(path.owner.fallback ? { format: "zcode_fallback" as const } : {}), ...applicability, ...(readers.length === 0 ? {} : { sharedWith: readers.map(({ client: reader }) => reader.name), }), }); } return clients; }, inspectClient: (client) => configurationOperations.run(async () => { const ownershipEstablished = client.sharedRegistration === true && clientOwnershipEvidencePaths(client).length > 0 && (await hasOwnershipEvidence(client, fileSystem)); const read = await readClientConfiguration( client, fileSystem, resources, ownershipEstablished, ); if (read.kind === "item") return read.item.status === "failed" ? read.item : undefined; const removal = clientRegistrationRemoval( read.parsed, read.original, client, ); if (!removal.ok) return item(client.name, "failed", removal.error.detail); // ZCode switches the entire server table to its shared fallback once // the last native server disappears. Inspect the table it would load, // not just the REA row: unrelated servers may otherwise become active. if ( client.format === "zcode" && removal.value.removeNative && Object.keys(read.parsed.servers).length === 1 && client.zcodeFallbackPath !== undefined ) { const fallbackClient: UninstallClient = { ...client, configPath: client.zcodeFallbackPath, configPaths: [client.zcodeFallbackPath], format: "zcode_fallback", }; const fallback = await readClientConfiguration( fallbackClient, fileSystem, resources, true, ); if (fallback.kind === "item") { if (fallback.item.status !== "skipped") return fallback.item; } else { const fallbackRemoval = clientRegistrationRemoval( fallback.parsed, fallback.original, fallbackClient, ); if (!fallbackRemoval.ok) return item(client.name, "failed", fallbackRemoval.error.detail); const remaining = Object.keys(fallback.parsed.servers).filter( (name) => name !== PRODUCT_IDENTITY.mcpServerKey || !fallbackRemoval.value.removeNative, ); if (remaining.length > 0) return item( client.name, "failed", "Removing REA's last native ZCode server would activate retained fallback servers; no change was made. Review the fallback configuration, then rerun uninstall.", ); } } if ( client.format === "opencode" && (removal.value.removeNative || removal.value.legacyPath !== undefined) ) { const originalLayers: ClientConfigurationSource[] = []; const remainingLayers: ClientConfigurationSource[] = []; for (const configPath of client.configPaths ?? [client.configPath]) { const layer = configPath === client.configPath ? read : await readClientConfiguration( { ...client, configPath }, fileSystem, resources, ownershipEstablished, ); if (layer.kind === "item") { if (layer.item.status !== "skipped") return layer.item; continue; } const layerRemoval = clientRegistrationRemoval( layer.parsed, layer.original, client, ); if (!layerRemoval.ok) return item(client.name, "failed", layerRemoval.error.detail); originalLayers.push({ ...layer.parsed, sourcePath: configPath }); const servers = { ...layer.parsed.servers }; const legacyServers = { ...layer.parsed.legacyServers }; const name = PRODUCT_IDENTITY.mcpServerKey; if (layerRemoval.value.removeNative) delete servers[name]; if (layerRemoval.value.legacyPath !== undefined) delete legacyServers[name]; remainingLayers.push({ ...layer.parsed, servers, legacyServers, sourcePath: configPath, }); } const selected = effectiveClientConfiguration(originalLayers)?.servers[ PRODUCT_IDENTITY.mcpServerKey ]; const remaining = effectiveClientConfiguration(remainingLayers)?.servers[ PRODUCT_IDENTITY.mcpServerKey ]; const altersEffectiveRegistration = clientRegistrationOwnership(selected, client) === "owned" ? remaining !== undefined : !isDeepStrictEqual(selected, remaining); if (altersEffectiveRegistration) return item( client.name, "failed", "Removing REA's registration would activate or change an unowned OpenCode registration in another configuration layer, including a possible V1 fallback; no change was made. Remove or replace that registration manually, then rerun uninstall.", ); } if ( !removal.value.removeNative && removal.value.legacyPath === undefined ) return undefined; preflightOwnedClients.add(client); // A removal the running package would revert, or redirect into its // private storage, would leave the registration in place. const blocker = clientWriteBlocker(client); return blocker === undefined ? undefined : item(client.name, "failed", blocker); }), removeClient: (client) => configurationOperations.run(() => removeClient( client, fileSystem, resources, () => clientWriteBlocker(client), preflightOwnedClients.has(client), ), ), inspectSkill: async () => { const selection = skillDestinationSelection( home, undefined, environment, platform, ); if (selection.issues.length > 0) return item( "skill", "failed", selection.issues .map(({ path, detail }) => `${detail} (${path})`) .join(" "), ); for (const destination of selection.destinations) { const inspected = await inspectManagedSkill( destination.path, destination.client, fileSystem, ); if (inspected?.status === "failed") return inspected; if (inspected !== undefined) continue; const blocker = skillWriteBlocker(destination.path); if (blocker !== undefined) return item("skill", "failed", blocker); } return undefined; }, removeSkill: () => removeManagedSkills( home, fileSystem, environment, platform, skillWriteBlocker, ), purgeData: () => purgeSelectedData(home, environment, platform, fileSystem), close: async () => { try { await configurationOperations.close(); await resources.close(); return undefined; } catch (cause: unknown) { return uninstallCleanupError(cause); } }, }; }; /** * Every user file that can hold REA's registration for one client. An MSIX * package can read either its private copy or the AppData file, and earlier * setups wrote the AppData file, so both lose REA's entry. */ const uninstallConfigPaths = (client: SetupClient): readonly string[] => [ ...new Set([ ...(client.configPaths ?? [client.configPath]), ...(client.msixPackage === undefined ? [] : [ client.msixPackage.privateConfigPath, client.msixPackage.appDataConfigPath, ]), ]), ]; /** Whether removal would change this configuration. */ const registrationPresent = (parsed: ClientConfigurationDocument): boolean => { const name = PRODUCT_IDENTITY.mcpServerKey; return ( Object.hasOwn(parsed.servers, name) || // Beside a native OpenCode V2 table, OpenCode also loads a V1 `mcp.rea`. legacyClientServerPath(parsed, name) !== undefined || // Harness ownership is the stable entry id. A stale or malformed launcher // still belongs to that id, and so does a direct patch that projects no row. (parsed.dialect === "dsh" && dshDocument(parsed.document).carriesEntry) ); }; type ClientConfigurationRead = | { readonly kind: "item"; readonly item: UninstallItem } | { readonly kind: "configuration"; readonly transactionPath: string; readonly original: string; readonly parsed: ClientConfigurationDocument; }; /** The configuration text, or the outcome to report for a failed read. A * completed physical read is retained even when its handle fails to close: * that exact text still drives removal, so an owned row it proves stays * actionable instead of softening to retained. */ const readClientConfigurationText = async ( client: UninstallClient, transactionPath: string, io: { readonly fileSystem: UninstallFileSystem; readonly resources: ArtifactResourceScope; readonly configurationFailure: (detail: string) => ClientConfigurationRead; }, ): Promise => { try { return await io.fileSystem.readText(transactionPath); } catch (cause: unknown) { if (isClientConfigurationCleanupFailure(cause)) { const cleanup = await retryClientConfigurationCleanup( cause, io.resources, ); const detail = cleanup.primary instanceof InvalidUtf8FileError ? "Configuration is not valid UTF-8 and was not changed; its resources could not be released. Repair it, then rerun uninstall." : "Configuration could not be read or its resources could not be released. Check file permissions, then rerun uninstall."; // An unreleased handle is REA's own incomplete cleanup, never foreign- // storage uncertainty: it must stop removal outright, so later removals // and purge cannot outrun the failure that close() reports afterwards. if (cleanup.cleanup !== undefined) return itemRead(item(client.name, "failed", detail)); const completed: unknown = cause.outcome.kind === "completed" ? cause.outcome.value : undefined; if (typeof completed !== "string") return io.configurationFailure(detail); return completed; } return isMissing(cause) ? itemRead(item(client.name, "skipped", "Configuration does not exist.")) : io.configurationFailure( cause instanceof InvalidUtf8FileError ? "Configuration is not valid UTF-8 and was not changed. Repair it, then rerun uninstall." : "Configuration could not be read. Check file permissions, then rerun uninstall.", ); } }; const readClientConfiguration = async ( client: UninstallClient, fileSystem: UninstallFileSystem, resources: ArtifactResourceScope, ownershipEstablished: boolean, ): Promise => { const applicabilityUnverified = client.applicability === "unverified" && !ownershipEstablished; const configurationFailure = (detail: string): ClientConfigurationRead => itemRead( item( client.name, applicabilityUnverified ? "retained" : "failed", applicabilityUnverified ? `Product applicability could not be established. Shared configuration was retained without blocking other REA removals. ${detail}` : detail, ), ); if (client.configPathError !== undefined) return configurationFailure(client.configPathError); if (client.format === "unsupported") return itemRead( item( client.name, "skipped", manualRegistrationRemediation(client.name) ?? "This client has no documented local MCP configuration boundary.", ), ); const resolved = await resolveUninstallConfigPath(client, fileSystem); if (typeof resolved !== "string") return resolved.status === "failed" ? configurationFailure(resolved.detail) : itemRead(resolved); const transactionPath = resolved; const original = await readClientConfigurationText(client, transactionPath, { fileSystem, resources, configurationFailure, }); if (typeof original !== "string") return original; try { const parsed = parseClientConfiguration(original, client.format); return { kind: "configuration", transactionPath, original, parsed }; } catch (cause: unknown) { return configurationFailure( cause instanceof ClientConfigurationShapeError || cause instanceof ConfigurationError ? `Configuration was not changed: ${cause.message}. Repair it, then rerun uninstall.` : `Configuration is not valid ${client.format === "toml" || client.format === "grok" ? "TOML" : client.format === "opencode" ? "JSONC" : client.format === "hermes" || client.format === "dsh" ? "YAML" : "JSON"} and was not changed. Repair it, then rerun uninstall.`, ); } }; const itemRead = (result: UninstallItem): ClientConfigurationRead => ({ kind: "item", item: result, }); /** * Share the exact ownership and applicability decision with preflight. A * removable legacy entry carries its document path, so removal edits exactly * the entry this decision admitted. */ type RegistrationRemoval = { readonly removeNative: boolean; readonly legacyPath: readonly string[] | undefined; }; type RegistrationRemovalRefusal = { readonly kind: "shadowed_unowned_member" | "foreign_legacy_fallback"; readonly detail: string; /** The owned rows that motivated removal; refusing the edit keeps them. */ readonly owned: RegistrationRemoval; }; const clientRegistrationRemoval = ( parsed: ClientConfigurationDocument, original: string, client: SetupClient, ): Result => { const name = PRODUCT_IDENTITY.mcpServerKey; if ( parsed.dialect === "dsh" && dshDocument(parsed.document).hasUnknownStructure ) return ok({ removeNative: false, legacyPath: undefined }); const removeNative = (parsed.dialect === "dsh" && dshDocument(parsed.document).carriesEntry) || (Object.hasOwn(parsed.servers, name) && clientRegistrationOwnership(parsed.servers[name], client) === "owned"); const legacyPath = legacyClientServerPath(parsed, name); const removeLegacy = legacyPath !== undefined && clientRegistrationOwnership(parsed.legacyServers[name], client) === "owned"; const ownership: RegistrationRemoval = { removeNative, legacyPath: removeLegacy ? legacyPath : undefined, }; if (removeNative || removeLegacy) { const shadowed = shadowedClientServers(original, parsed, name); if ( (removeNative && shadowed.servers.some( (member) => clientRegistrationOwnership(member, client) !== "owned", )) || (removeLegacy && shadowed.legacyServers.some( (member) => clientRegistrationOwnership(member, client) !== "owned", )) ) return err({ kind: "shadowed_unowned_member", detail: SHADOWED_UNOWNED_MEMBER_DETAIL, owned: ownership, }); } if (removeNative && legacyPath !== undefined && !removeLegacy) return err({ kind: "foreign_legacy_fallback", detail: UNOWNED_LEGACY_FALLBACK_DETAIL, owned: ownership, }); return ok(ownership); }; const SHADOWED_UNOWNED_MEMBER_DETAIL = `Configuration repeats the "${PRODUCT_IDENTITY.mcpServerKey}" member, and an earlier duplicate is not REA-owned; removing the registration the client reads would activate an earlier duplicate, so no change was made. Remove the duplicate members manually, then rerun uninstall.`; const UNOWNED_LEGACY_FALLBACK_DETAIL = `OpenCode falls back to the V1 "mcp.${PRODUCT_IDENTITY.mcpServerKey}" entry, which is not REA-owned; removing REA's native registration would activate it, so no change was made. Remove or replace that V1 entry manually, then rerun uninstall.`; /** Preserve the bytes uninstall is about to edit and return the backup holding them. */ const backupClientConfiguration = async ( client: SetupClient, transactionPath: string, original: string, options: RecoveryBackupPreservationOptions, ): Promise => { const failed = (detail: string) => item( client.name, "failed", `Configuration could not be backed up, so no change was made. ${detail}`, ); try { const preserved = await preserveCurrentRecoveryBackup( `${client.configPath}.rea.backup`, transactionPath, original, options, ); if (preserved.ok) return preserved.value; if (preserved.error.kind === "occupied") return failed( `${preserved.error.detail}. Move that file aside, then rerun uninstall.`, ); } catch (cause: unknown) { // The resource scope retains a backup handle whose close failed. if (!(cause instanceof RegularFileCleanupFailure)) throw cause; } return failed("Check file permissions, then rerun uninstall."); }; const removeClient = async ( client: UninstallClient, fileSystem: UninstallFileSystem, resources: ArtifactResourceScope, writeBlocker?: () => string | undefined, preflightOwned = false, ): Promise => { const read = await readClientConfiguration( client, fileSystem, resources, preflightOwned, ); if (read.kind === "item") return read.item; const { transactionPath, original, parsed } = read; const name = PRODUCT_IDENTITY.mcpServerKey; if ( parsed.dialect === "dsh" && dshDocument(parsed.document).hasUnknownStructure ) return item( client.name, "retained", "A Cordis expression may produce registration rows, so the patch was retained without changes.", ); if (!registrationPresent(parsed)) return item(client.name, "skipped", "REA registration is absent."); const removal = clientRegistrationRemoval(parsed, original, client); if (!removal.ok) return item(client.name, "failed", removal.error.detail); const { removeNative, legacyPath } = removal.value; const removeLegacy = legacyPath !== undefined; if (!removeNative && !removeLegacy) return item( client.name, "retained", "The rea-named registration is not REA-owned.", ); const blocker = writeBlocker?.(); if (blocker !== undefined) return item(client.name, "failed", blocker); const remaining = { ...parsed.servers }; if (removeNative) delete remaining[name]; const document = withClientServers( parsed, remaining, removeLegacy ? name : undefined, ); const editedPaths = [ ...(removeNative ? [clientServerPath(parsed, name)] : []), ...(legacyPath === undefined ? [] : [legacyPath]), ]; let serialized: ReturnType; try { serialized = serializeClientConfiguration( document, client.format, original, editedPaths, // clientRegistrationRemoval admitted only names whose repeats REA owns. { removeShadowedMembersAt: editedPaths }, ); } catch { return item( client.name, "failed", "Configuration could not be updated, so no change was made. Repair the configuration, then rerun uninstall.", ); } if (!serialized.ok) return item( client.name, "failed", `Configuration repeats the member at ${JSON.stringify(serialized.error.path)}; removing the registration the client reads would activate an earlier duplicate, so no change was made. Remove the duplicate members manually, then rerun uninstall.`, ); const backupPath = await backupClientConfiguration( client, transactionPath, original, { copy: (source, destination) => fileSystem.copy(source, destination), resources, }, ); if (typeof backupPath !== "string") return backupPath; const manualRecovery = () => item( client.name, "failed", `Configuration could not be updated or restored. Restore the backup at ${backupPath} manually, then rerun uninstall.`, ); let publication: Awaited< ReturnType >; try { publication = await fileSystem.publishConfiguration( transactionPath, serialized.value, original, ); } catch (cause: unknown) { if (isClientConfigurationCleanupFailure(cause)) await retryClientConfigurationCleanup(cause, resources); return manualRecovery(); } try { return await publication.verify(async () => { try { const text = await fileSystem.readText(publication.path); await publication.assertCurrent(text); const readback = parseClientConfiguration(text, client.format); if ( (removeNative && Object.hasOwn(readback.servers, name)) || (readback.dialect === "dsh" && dshDocument(readback.document).carriesEntry) || (removeLegacy && Object.hasOwn(readback.legacyServers, name)) ) throw new Error("registration readback mismatch"); return item( client.name, "removed", `Removed registration from ${client.configPath}.`, ); } catch (cause: unknown) { if (isClientConfigurationCleanupFailure(cause)) await retryClientConfigurationCleanup(cause, resources); try { await publication.restore(original); } catch { return manualRecovery(); } return item( client.name, "failed", `Configuration could not be updated. The original was restored and its backup at ${backupPath} was retained. Repair the configuration or restore that backup, then rerun uninstall.`, ); } }); } catch (cause: unknown) { if (isClientConfigurationCleanupFailure(cause)) await retryClientConfigurationCleanup(cause, resources); return item( client.name, "failed", `Configuration verification or resource cleanup failed. The backup at ${backupPath} was retained. Check the configuration and rerun uninstall.`, ); } }; const resolveUninstallConfigPath = async ( client: SetupClient, fileSystem: UninstallFileSystem, ): Promise => { 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.", ) ); }; /** Purge the same default cache namespaces selected by their producers. */ const purgeSelectedData = async ( home: string, environment: Readonly, platform: NodeJS.Platform, fileSystem: UninstallFileSystem, ): Promise => { const items: UninstallItem[] = []; const directories: string[] = []; let custom: string | undefined; if (platform === "darwin" || platform === "linux") { const defaultCache = defaultKunaCacheDirectory(home, environment, platform); directories.push(defaultCache); custom = environment.REA_KUNA_CACHE_DIR; // Lexical spellings identify the default namespace for reporting. // Removal still uses the owned-path checks below. Other selections // remain separately reported without resolving symbolic links. if ( custom !== undefined && custom !== defaultCache && !sameLexicalDirectory(custom, defaultCache, platform) ) items.push( item( "kuna-custom-cache", "retained", `Caller-selected Kuna cache ${custom} was retained because purge does not establish ownership of that entire directory.`, ), ); else custom = undefined; } // The ownership helper cache has no caller-selected location to retain. if (platform === "darwin") directories.push(defaultDarwinHelperCacheDirectory(home)); if (platform === "linux") { const hopper = linuxHopperReleaseCacheDirectory(environment, home); if (hopper.ok) directories.push(hopper.value); else items.push(item("hopper-releases", "failed", hopper.error.message)); } // Resolve selections before a managed namespace removal can delete cwd. // A namespace that contains the caller-selected cache is kept whole, so // the retained report is true. const reaRoot = appendCallerPath(home, ".rea"); // A spelling with `..` is judged only where the filesystem resolves it, // because collapsing it lexically is wrong after a symbolic link. // `undefined` means the location could not be established. const resolve = async (path: string): Promise => { const resolved = await existingRealpath(fileSystem, path); return resolved === undefined ? undefined : [...(hasParentTraversal(path) ? [] : [path]), ...resolved]; }; const selections = custom === undefined ? [] : await resolve(custom); const purge = async (root: string, names: readonly string[]) => { const kept: { readonly name: string; readonly unknown: boolean }[] = []; for (const name of names) { const targets = await resolve(appendCallerPath(root, name)); // An unestablished selection or namespace may contain the selection, // so it is kept rather than treated as absent. const contains = custom !== undefined && (selections === undefined || targets === undefined || targets.some((target) => selections.some((selection) => withinLexicalDirectory(selection, target, platform), ), )); if (contains) kept.push({ name, unknown: selections === undefined || targets === undefined, }); } const keptItems = kept.map(({ name, unknown }) => item( name, "retained", unknown ? `${appendCallerPath(root, name)} was retained because purge could not establish whether it contains the caller-selected Kuna cache ${custom}.` : `${appendCallerPath(root, name)} was retained because it contains the caller-selected Kuna cache ${custom}, which purge does not remove.`, ), ); const owned = names.filter( (name) => !kept.some((entry) => entry.name === name), ); return async () => [ ...keptItems, ...(await purgeManagedData(root, fileSystem, owned)), ]; }; const reaPlan = await purge(reaRoot, ["cache", "state"]); const plans: (() => Promise)[] = []; for (const directory of directories) plans.push(await purge(dirname(directory), [basename(directory)])); items.unshift(...(await reaPlan())); for (const plan of plans) items.push(...(await plan())); return items; }; /** * Canonical spelling of an existing path, nothing when the path is absent, * or `undefined` when its location cannot be established (for example an * inaccessible parent, or `..` without a realpath to judge it). */ const existingRealpath = async ( fileSystem: UninstallFileSystem, path: string, ): Promise => { if (fileSystem.realpath === undefined) return hasParentTraversal(path) ? undefined : []; try { return [await fileSystem.realpath(path)]; } catch (error) { const code = (error as NodeJS.ErrnoException).code; return code === "ENOENT" || code === "ENOTDIR" ? [] : undefined; } }; const purgeManagedData = async ( root: string, fileSystem: UninstallFileSystem, names: readonly string[], ): Promise => { try { const stats = await fileSystem.stat(root); const linked = stats.isSymbolicLink(); if (linked || stats.isDirectory?.() !== true) return names.map((name) => item( name, "retained", `REA did not remove this item because its managed data root ${root} is ${linked ? "a symbolic link" : "not a directory"}. Verify the root before removing its data manually.`, ), ); } catch (cause: unknown) { return names.map((name) => isMissing(cause) ? item( name, "skipped", `${appendCallerPath(root, name)} does not exist.`, ) : item( name, "failed", `The managed data root ${root} could not be verified. Check its permissions, then rerun uninstall.`, ), ); } const items: UninstallItem[] = []; for (const name of names) items.push( await removeManagedPath(appendCallerPath(root, name), name, fileSystem), ); return items; }; const removeManagedPath = async ( path: string, name: string, fileSystem: UninstallFileSystem, ): Promise => { try { const stats = await fileSystem.stat(path); if (stats.isSymbolicLink()) return item( name, "retained", "REA did not remove this item because its managed path is a symbolic link. Verify the link target before removing it manually.", ); await fileSystem.remove(path); return item(name, "removed", `Removed ${path}.`); } catch (cause: unknown) { return isMissing(cause) ? item(name, "skipped", `${path} does not exist.`) : item( name, "failed", "This item could not be removed. Check file permissions, then rerun uninstall.", ); } }; const removeManagedSkills = async ( home: string, fileSystem: UninstallFileSystem, environment: Readonly, platform: NodeJS.Platform, writeBlocker?: (path: string) => string | undefined, ): Promise => { const selection = skillDestinationSelection( home, undefined, environment, platform, ); if (selection.issues.length > 0) return item( "skill", "failed", selection.issues .map(({ path, detail }) => `${detail} (${path})`) .join(" "), ); // Every destination shares one summary item; preserve both client and path. const results = await Promise.all( selection.destinations.map(({ client, path }) => removeManagedSkill(path, `${client} (${path})`, fileSystem, writeBlocker), ), ); const failed = results.find(({ status }) => status === "failed"); if (failed !== undefined) return item( "skill", "failed", results .map(({ name, status, detail }) => `${name}: ${status} (${detail})`) .join(" "), ); const status = results.some( ({ status: resultStatus }) => resultStatus === "removed", ) ? "removed" : results.some(({ status: resultStatus }) => resultStatus === "retained") ? "retained" : "skipped"; return item( "skill", status, results .map( ({ name, status: resultStatus, detail }) => `${name}: ${resultStatus} (${detail})`, ) .join(" "), ); }; const inspectManagedSkill = async ( path: string, name: string, fileSystem: UninstallFileSystem, ): Promise => { let root: ManagedPathStats; try { root = await fileSystem.stat(path); } catch (cause: unknown) { return isMissing(cause) ? item(name, "skipped", "Skill directory does not exist.") : item(name, "failed", "Skill directory could not be inspected."); } if (root.isSymbolicLink()) return item(name, "retained", "Skill directory is a symbolic link."); if (root.isDirectory?.() !== true) return item(name, "retained", "Skill path is not a directory."); const manifestPath = appendCallerPath(path, "SKILL.md"); try { const manifest = await fileSystem.stat(manifestPath); if (manifest.isSymbolicLink()) return item(name, "retained", "Skill manifest is a symbolic link."); if (manifest.isFile?.() !== true) return item(name, "retained", "Skill manifest is not a regular file."); } catch (cause: unknown) { return isMissing(cause) ? item(name, "retained", "Skill ownership could not be established.") : item(name, "failed", "Skill manifest could not be inspected."); } let content: string; try { content = await (fileSystem.readRegularText?.(manifestPath) ?? fileSystem.readText(manifestPath)); } catch (cause: unknown) { return isMissing(cause) ? item(name, "retained", "Skill ownership could not be established.") : item(name, "failed", "Skill manifest could not be read."); } if (!isManagedSkillManifest(content)) return item(name, "retained", "Skill manifest is not REA-owned."); return undefined; }; const removeManagedSkill = async ( path: string, name: string, fileSystem: UninstallFileSystem, writeBlocker?: (path: string) => string | undefined, ): Promise => { const inspection = await inspectManagedSkill(path, name, fileSystem); if (inspection !== undefined) return inspection; const blocker = writeBlocker?.(path); if (blocker !== undefined) return item(name, "failed", blocker); const manifestName = "SKILL.md"; const otherFiles = MANAGED_SKILL_FILES.filter( (relativePath) => relativePath !== manifestName, ); const results: UninstallItem[] = []; for (const relativePath of otherFiles) results.push( await removeManagedSkillFile(path, relativePath, name, fileSystem), ); if ( results.some(({ status }) => status === "failed" || status === "retained") ) results.push( item( name, "retained", "REA ownership manifest was retained because a managed file could not be safely removed.", ), ); else { const manifest = await removeManagedSkillFile( path, manifestName, name, fileSystem, ); results.push(manifest); const directories = manifest.status === "removed" ? await removeEmptyManagedDirectories(path, name, fileSystem) : undefined; if (directories !== undefined) results.push(directories); } const failed = results.find(({ status }) => status === "failed"); if (failed !== undefined) return item(name, "failed", results.map(({ detail }) => detail).join(" ")); if (results.some(({ status }) => status === "retained")) return item( name, "retained", [...new Set(results.map(({ detail }) => detail))].join(" "), ); const removed = results.some(({ status }) => status === "removed"); return item( name, removed ? "removed" : "skipped", "REA-managed skill files were removed; other files were preserved.", ); }; /** Directories setup creates for managed files, deepest first, then the root. */ const MANAGED_SKILL_DIRECTORIES = [ ...new Set( MANAGED_SKILL_FILES.map((relativePath) => relativePath.split("/").slice(0, -1).join("/"), ).filter((directory) => directory.length > 0), ), ].sort((left, right) => right.split("/").length - left.split("/").length); /** Remove managed directories left empty; any remaining user file keeps them. */ const removeEmptyManagedDirectories = async ( root: string, name: string, fileSystem: UninstallFileSystem, ): Promise => { if (fileSystem.removeEmptyDirectory === undefined) return undefined; for (const directory of [ ...MANAGED_SKILL_DIRECTORIES.map((relative) => appendCallerPath(root, relative), ), root, ]) { try { await fileSystem.removeEmptyDirectory(directory); } catch (cause: unknown) { // User files, an absent directory, or a non-directory keep it as is. if (!isKeptDirectory(cause)) return item( name, "failed", `Managed skill directory could not be removed: ${directory}.`, ); } } return undefined; }; const isKeptDirectory = (cause: unknown): boolean => cause instanceof Error && "code" in cause && ["ENOTEMPTY", "EEXIST", "ENOENT", "ENOTDIR"].includes(String(cause.code)); const removeManagedSkillFile = async ( root: string, relativePath: string, name: string, fileSystem: UninstallFileSystem, ): Promise => { const segments = relativePath.split(/[\\/]/u); let parent = root; for (const segment of segments.slice(0, -1)) { parent = appendCallerPath(parent, segment); try { const stats = await fileSystem.stat(parent); if (stats.isSymbolicLink() || stats.isDirectory?.() !== true) return item( name, "retained", `Managed path parent was retained: ${parent}.`, ); } catch (cause: unknown) { return isMissing(cause) ? item( name, "skipped", `${appendCallerPath(parent, segments.at(-1) ?? "")} does not exist.`, ) : item( name, "failed", `Managed path parent could not be inspected: ${parent}.`, ); } } const target = appendCallerPath(root, relativePath); let stats: ManagedPathStats; try { stats = await fileSystem.stat(target); } catch (cause: unknown) { return isMissing(cause) ? item(name, "skipped", `${target} does not exist.`) : item(name, "failed", `Managed file could not be inspected: ${target}.`); } if (stats.isSymbolicLink()) return item( name, "retained", `Managed file is a symbolic link: ${target}.`, ); if (stats.isFile?.() !== true) return item( name, "retained", `Managed path is not a regular file: ${target}.`, ); try { await fileSystem.remove(target, false); return item(name, "removed", `Removed ${target}.`); } catch (cause: unknown) { return isMissing(cause) ? item(name, "skipped", `${target} does not exist.`) : item(name, "failed", `Managed file could not be removed: ${target}.`); } }; const item = ( name: string, status: UninstallItem["status"], detail: string, ): UninstallItem => ({ name, status, detail }); /** * Layered clients are removed file by file, but callers look up one status by * client name. Aggregate status does not invalidate any constituent outcome. */ const collapseUninstallItems = ( items: readonly UninstallItem[], ): UninstallItem[] => { const grouped = new Map(); for (const next of items) { const { name, actions, ...action } = next; const group = grouped.get(name) ?? []; group.push( ...(actions !== undefined && actions.length > 0 ? actions : [action]), ); grouped.set(name, group); } return [...grouped].map(([name, actions]) => { const first = actions[0]; if (first === undefined) throw new Error("Uninstall outcome group has no actions."); if (actions.length === 1) return { name, ...first }; const status = actions.reduce( (selected, action) => uninstallStatusPriority(action.status) > uninstallStatusPriority(selected) ? action.status : selected, first.status, ); return { name, status, detail: [...new Set(actions.map(({ detail }) => detail))].join(" "), actions, }; }); }; const uninstallStatusPriority = (status: UninstallItem["status"]): number => { switch (status) { case "failed": return 3; case "removed": return 2; case "retained": return 1; case "skipped": return 0; default: { const exhaustive: never = status; throw new TypeError( `Unhandled uninstall item status: ${String(exhaustive)}`, ); } } }; const isMissing = (cause: unknown): boolean => cause instanceof Error && "code" in cause && cause.code === "ENOENT";