@echomem/mcp 1.4.50 → 1.4.51

package/dist/setup.js

@@ -32,10 +32,13 @@ import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
 import { resolveClaudeCoworkSessionRoots, resolveClaudeDesktopSupportRoots, resolveClaudeProjectsDir, resolveCodexSessionRoots, } from "./local-data-paths.js";
 import { isEphemeralNpxPath, reexecFromDurableRuntime, resolveDurableDistPath, resolveGlobalEntry } from "./durable-entry.js";
-import { installSaveCheckpointHooks, installSourceSessionHooks } from "./hud/hooks.js";
+import { installSaveCheckpointHooks, installSourceSessionHooks, removeLifecycleHooks } from "./hud/hooks.js";
+import { atomicWriteJsonObject, atomicWriteTextFile, readJsonObjectFile } from "./config-files.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
-import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, } from "./headless-runtime.js";
+import { startMcpControlServer } from "./mcp-control.js";
+import { loadHudDiagnostics } from "./hud/diagnostics.js";
+import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, removeHeadlessRuntime, } from "./headless-runtime.js";
 // The setup dashboard, account login, and encryption passphrase entry are all served by this
 // localhost bridge. The hosted API only sends OTP email, verifies the code, and mints a device token.
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
@@ -408,13 +411,38 @@ export function writeCodexConfig(configPath, entry, options = {}) {
         if (lines.slice(start, end).join("\n").trimEnd() === block)
             return "exists"; // already correct
         const next = [...lines.slice(0, start), ...block.split("\n"), ...lines.slice(end)];
-        fs.writeFileSync(configPath, next.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
+        atomicWriteTextFile(configPath, next.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, ""));
         return "wrote"; // replaced a stale entry → caller tells the user to restart Codex
     }
     const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
-    fs.appendFileSync(configPath, sep + block + "\n");
+    atomicWriteTextFile(configPath, content + sep + block + "\n");
     return "wrote";
 }
+/** Remove only EchoMem's TOML section and preserve every other Codex setting. */
+export function removeCodexConfig(configPath) {
+    let content;
+    try {
+        content = fs.readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.echomem\]\s*$/.test(line));
+    if (start < 0)
+        return false;
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end]))
+        end += 1;
+    const next = [...lines.slice(0, start), ...lines.slice(end)]
+        .join("\n")
+        .replace(/^\n+/, "")
+        .replace(/\n{3,}/g, "\n\n");
+    atomicWriteTextFile(configPath, next);
+    return true;
+}
 /**
  * Write the EchoMem guidance block into the agent's GLOBAL memory file (~/.codex/AGENTS.md,
  * ~/.claude/CLAUDE.md) so the agent treats EchoMem as its core memory tool without the tool
@@ -469,13 +497,35 @@ export function writeAgentsMemoryGuidance(filePath) {
         const current = content.slice(start, end + AGENTS_MD_END.length);
         if (current === block)
             return "exists";
-        fs.writeFileSync(filePath, content.slice(0, start) + block + content.slice(end + AGENTS_MD_END.length));
+        atomicWriteTextFile(filePath, content.slice(0, start) + block + content.slice(end + AGENTS_MD_END.length));
         return "updated";
     }
     const sep = content ? (content.endsWith("\n") ? "\n" : "\n\n") : "";
-    fs.appendFileSync(filePath, sep + block + "\n");
+    atomicWriteTextFile(filePath, content + sep + block + "\n");
     return "wrote";
 }
+/** Remove EchoMem's marker-owned guidance block without touching user-authored content. */
+export function removeAgentsMemoryGuidance(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    const start = content.indexOf(AGENTS_MD_BEGIN);
+    const end = content.indexOf(AGENTS_MD_END);
+    if (start < 0 || end <= start)
+        return false;
+    const next = (content.slice(0, start) + content.slice(end + AGENTS_MD_END.length))
+        .replace(/^\s*\n/, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd();
+    atomicWriteTextFile(filePath, next ? `${next}\n` : "");
+    return true;
+}
 /**
  * Refresh marker-owned guidance for users upgrading an existing standalone MCP install.
  * This intentionally does not create global memory files: setup owns first installation,
@@ -507,32 +557,30 @@ export function refreshInstalledMemoryGuidance() {
 }
 /** Merge the EchoMem entry into a JSON client's `mcpServers` map without clobbering siblings. */
 export function writeJsonClientConfig(configPath, entry, options = {}) {
-    let config = {};
-    try {
-        config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    }
-    catch {
-        /* fresh config */
-    }
-    config.mcpServers = config.mcpServers || {};
-    if (!options.forceHeadless && validDesktopManagedEntry(config.mcpServers.echomem)) {
+    const config = readJsonObjectFile(configPath, "MCP client configuration");
+    const servers = objectRecord(config.mcpServers) ?? {};
+    config.mcpServers = servers;
+    if (!options.forceHeadless && validDesktopManagedEntry(servers.echomem)) {
         return "desktop-managed";
     }
-    config.mcpServers.echomem = entry;
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    servers.echomem = entry;
+    atomicWriteJsonObject(configPath, config);
     return "wrote";
 }
+/** Remove only the EchoMem server entry from a JSON MCP client configuration. */
+export function removeJsonClientConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return false;
+    const config = readJsonObjectFile(configPath, "MCP client configuration");
+    const servers = objectRecord(config.mcpServers);
+    if (!servers || !("echomem" in servers))
+        return false;
+    delete servers.echomem;
+    atomicWriteJsonObject(configPath, config);
+    return true;
+}
 function readClaudeCodeConfigFile(configPath) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : {};
-    }
-    catch {
-        return {};
-    }
+    return readJsonObjectFile(configPath, "Claude Code user configuration");
 }
 function echoMemEntryFromServers(value) {
     return objectRecord(objectRecord(value)?.echomem);
@@ -866,6 +914,36 @@ export function writeClaudeCodeConfig(entry, options = {}) {
         usedDirectWrite,
     };
 }
+/** Remove EchoMem at Claude Code user/project scope while preserving account and sibling config. */
+export function removeClaudeCodeConfig(configPath = home(".claude.json")) {
+    if (!fs.existsSync(configPath))
+        return { removedUserEntry: false, removedProjectEntries: [] };
+    const config = readClaudeCodeConfigFile(configPath);
+    let changed = false;
+    let removedUserEntry = false;
+    const userServers = objectRecord(config.mcpServers);
+    if (userServers && "echomem" in userServers) {
+        delete userServers.echomem;
+        removedUserEntry = true;
+        changed = true;
+    }
+    const removedProjectEntries = [];
+    const projects = objectRecord(config.projects);
+    if (projects) {
+        for (const [projectPath, value] of Object.entries(projects)) {
+            const project = objectRecord(value);
+            const servers = objectRecord(project?.mcpServers);
+            if (!servers || !("echomem" in servers))
+                continue;
+            delete servers.echomem;
+            removedProjectEntries.push(projectPath);
+            changed = true;
+        }
+    }
+    if (changed)
+        atomicWriteJsonObject(configPath, config);
+    return { removedUserEntry, removedProjectEntries };
+}
 function readJsonClientEntry(configPath) {
     try {
         const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
@@ -3695,6 +3773,293 @@ function cmdLock() {
     store.clearKey();
     console.log("🔒 EchoMem vault locked on this device. Your login remains connected.");
 }
+export async function collectMcpDoctorReport(options = {}) {
+    const updateStatus = options.noNetwork
+        ? readCachedUpdateStatus()
+        : await checkLatestUpdateStatus({ force: true });
+    const desiredVersion = updateStatus?.latestVersion ?? MCP_PACKAGE_VERSION;
+    const runtime = readHeadlessRuntimeInstallation();
+    const store = new KeyStore();
+    const token = store.getToken();
+    const key = store.getKey();
+    let account = token
+        ? { state: options.noNetwork ? "not_checked" : "unreachable", detail: options.noNetwork ? "Account validation skipped." : "Account validation did not finish." }
+        : { state: "not_connected", detail: "Connect this Windows profile to an Echo account." };
+    let vault = key
+        ? { state: options.noNetwork ? "not_checked" : "unknown", detail: options.noNetwork ? "Vault validation skipped." : "Checking the saved vault key." }
+        : { state: token ? "unknown" : "locked", detail: token ? "Vault state has not been checked." : "Connect the account before checking the vault." };
+    let lastSearch;
+    if (token && !options.noNetwork) {
+        const diagnostics = await loadHudDiagnostics();
+        if (diagnostics.account.state === "connected") {
+            account = {
+                state: "connected",
+                plan: diagnostics.account.plan,
+                detail: diagnostics.account.plan
+                    ? `${diagnostics.account.plan} account verified.`
+                    : "Echo account verified.",
+            };
+        }
+        else if (diagnostics.accountRequest.httpStatus === 401 || diagnostics.accountRequest.httpStatus === 403) {
+            account = { state: "invalid", detail: "The saved Echo credential is no longer valid. Reconnect the account." };
+        }
+        else {
+            account = { state: "unreachable", detail: diagnostics.account.error || "Echo account validation is temporarily unavailable." };
+        }
+        if (diagnostics.lastSearch) {
+            lastSearch = {
+                at: diagnostics.lastSearch.at,
+                ok: diagnostics.lastSearch.ok,
+                httpStatus: diagnostics.lastSearch.httpStatus,
+                latencyMs: diagnostics.lastSearch.latencyMs,
+            };
+        }
+        if (account.state === "connected") {
+            try {
+                const encryption = await fetchEncryptionConfig(authedAxios(token));
+                if (!encryption.enabled) {
+                    vault = { state: "unencrypted", detail: "This account does not require a local vault key." };
+                }
+                else if (!key) {
+                    vault = { state: "locked", detail: "The encrypted vault is locked on this Windows profile." };
+                }
+                else if (await verifyKeyB64(key, encryption)) {
+                    vault = { state: "unlocked", detail: "The local vault key is valid." };
+                }
+                else {
+                    vault = { state: "invalid", detail: "The saved vault key does not match this account. Reconnect and unlock again." };
+                }
+            }
+            catch (error) {
+                vault = { state: "unknown", detail: `Vault validation unavailable: ${formatVerificationError(error)}` };
+            }
+        }
+        else if (!key) {
+            vault = { state: "unknown", detail: "Vault state cannot be verified until the account reconnects." };
+        }
+    }
+    const wsl = process.platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+    const clients = inspectClientConfigs(desiredVersion).map((client) => {
+        const health = !client.configured
+            ? "not_configured"
+            : client.state === "ok" || client.state === "newer"
+                ? "ready"
+                : client.state === "stale" || client.state === "missing"
+                    ? "repair"
+                    : "attention";
+        return {
+            ...client,
+            detected: true,
+            health,
+            recommendedAction: health === "not_configured" ? "connect" : health === "repair" || health === "attention" ? "repair" : "none",
+        };
+    });
+    return {
+        packageVersion: MCP_PACKAGE_VERSION,
+        publishedLatest: updateStatus?.latestVersion,
+        platform: process.platform,
+        credentialsPresent: Boolean(token),
+        vaultKeyPresent: Boolean(key),
+        runtime: runtime ? { version: runtime.version, launcher: runtime.launcher } : undefined,
+        account,
+        vault,
+        environment: {
+            windowsNative: process.platform === "win32",
+            wsl,
+            detail: wsl
+                ? "This is WSL. Native Windows agents use a separate EchoMem installation and configuration."
+                : process.platform === "win32"
+                    ? "Native Windows profile. WSL installations are managed separately."
+                    : "This Connect Echo page is running outside native Windows.",
+        },
+        lastSearch,
+        clients,
+    };
+}
+/**
+ * Remove standalone EchoMem MCP integration without deleting login/vault credentials or cloud data.
+ * Every user-owned config is edited narrowly and atomically; malformed files fail closed.
+ */
+export function uninstallStandaloneMcp() {
+    const store = new KeyStore();
+    const report = {
+        removedClients: [],
+        removedGuidance: [],
+        removedSkills: [],
+        removedHookGroups: 0,
+        removedRuntime: false,
+        credentialsPreserved: Boolean(store.getToken() || store.getKey()),
+        errors: [],
+    };
+    for (const client of knownClients()) {
+        try {
+            if (client.kind === "json") {
+                if (removeJsonClientConfig(client.configPath))
+                    report.removedClients.push(client.label);
+            }
+            else if (client.kind === "command") {
+                if (removeCodexConfig(client.configPath))
+                    report.removedClients.push(client.label);
+            }
+            else {
+                const removed = removeClaudeCodeConfig();
+                if (removed.removedUserEntry || removed.removedProjectEntries.length > 0)
+                    report.removedClients.push(client.label);
+            }
+        }
+        catch (error) {
+            report.errors.push(`${client.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        const hooks = removeLifecycleHooks("both");
+        report.removedHookGroups = hooks.removedGroups;
+    }
+    catch (error) {
+        report.errors.push(`Lifecycle hooks: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const file of [path.join(codexHome(), "AGENTS.md"), path.join(claudeConfigHome(), "CLAUDE.md")]) {
+        try {
+            if (removeAgentsMemoryGuidance(file))
+                report.removedGuidance.push(file);
+        }
+        catch (error) {
+            report.errors.push(`Guidance ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    for (const skillName of CODEX_SKILL_NAMES) {
+        const directory = path.join(codexHome(), "skills", skillName);
+        try {
+            if (!fs.existsSync(directory))
+                continue;
+            fs.rmSync(directory, { recursive: true, force: true });
+            report.removedSkills.push(skillName);
+        }
+        catch (error) {
+            report.errors.push(`Codex skill ${skillName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        report.removedRuntime = removeHeadlessRuntime().removed;
+    }
+    catch (error) {
+        report.errors.push(`Managed runtime: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return report;
+}
+function requireClient(clientId) {
+    const client = knownClients().find((candidate) => candidate.id === clientId);
+    if (!client)
+        throw new Error(`Unsupported MCP host: ${clientId}`);
+    return client;
+}
+export async function connectStandaloneMcpHost(clientId, options = {}) {
+    requireClient(clientId);
+    const updateStatus = await checkLatestUpdateStatus({ force: true });
+    const targetVersion = updateStatus?.latestVersion ?? MCP_PACKAGE_VERSION;
+    installHeadlessRuntimeSync(targetVersion, {
+        force: options.repair === true,
+        prune: options.repair === true,
+    });
+    await cmdSetup({
+        client: clientId,
+        "skip-login": true,
+        "skip-runtime-install": true,
+        "continue-on-client-error": true,
+    });
+    return collectMcpDoctorReport({ noNetwork: true });
+}
+export async function disconnectStandaloneMcpHost(clientId) {
+    const client = requireClient(clientId);
+    if (client.kind === "json") {
+        removeJsonClientConfig(client.configPath);
+    }
+    else if (client.kind === "command") {
+        removeCodexConfig(client.configPath);
+    }
+    else {
+        removeClaudeCodeConfig();
+    }
+    if (client.id === "codex") {
+        removeLifecycleHooks("codex");
+        removeAgentsMemoryGuidance(path.join(codexHome(), "AGENTS.md"));
+        for (const skillName of CODEX_SKILL_NAMES) {
+            fs.rmSync(path.join(codexHome(), "skills", skillName), { recursive: true, force: true });
+        }
+    }
+    if (client.id === "claude-code")
+        removeLifecycleHooks("claude-code");
+    if (client.id === "claude-code" || client.id === "claude-desktop") {
+        const otherId = client.id === "claude-code" ? "claude-desktop" : "claude-code";
+        const other = requireClient(otherId);
+        const otherReport = inspectClientConfig(other, MCP_PACKAGE_VERSION);
+        if (!otherReport?.configured)
+            removeAgentsMemoryGuidance(path.join(claudeConfigHome(), "CLAUDE.md"));
+    }
+    return collectMcpDoctorReport({ noNetwork: true });
+}
+async function cleanReconnectStandaloneMcp() {
+    const updateStatus = await checkLatestUpdateStatus({ force: true });
+    const targetVersion = updateStatus?.latestVersion ?? MCP_PACKAGE_VERSION;
+    console.log(`Installing a clean ${MCP_PACKAGE_NAME}@${targetVersion} runtime…`);
+    installHeadlessRuntimeSync(targetVersion, { force: true, prune: true });
+    await cmdSetup({
+        all: true,
+        "skip-login": true,
+        "skip-runtime-install": true,
+        "continue-on-client-error": true,
+    });
+    return collectMcpDoctorReport({ noNetwork: true });
+}
+async function cmdControl() {
+    const control = await startMcpControlServer({
+        doctor: () => collectMcpDoctorReport(),
+        connectHost: (clientId, repair) => connectStandaloneMcpHost(clientId, { repair }),
+        disconnectHost: (clientId) => disconnectStandaloneMcpHost(clientId),
+        reconnect: () => cleanReconnectStandaloneMcp(),
+        uninstall: () => uninstallStandaloneMcp(),
+    });
+    console.log("Connect Echo is running locally.");
+    console.log(control.url);
+    console.log("Close this terminal or press Ctrl+C when you are finished.");
+    openBrowser(control.url);
+}
+async function cmdConnect(flags) {
+    if (flags["skip-login"] !== true) {
+        const current = await collectMcpDoctorReport();
+        const accountNeedsLogin = current.account.state === "not_connected" || current.account.state === "invalid";
+        const vaultNeedsUnlock = current.account.state === "connected"
+            && (current.vault.state === "locked" || current.vault.state === "invalid");
+        if (accountNeedsLogin || vaultNeedsUnlock) {
+            const connected = await cmdLogin({ ...flags, force: true });
+            if (!connected)
+                return;
+        }
+    }
+    await cmdControl();
+}
+async function cmdReconnect(flags) {
+    const report = await cleanReconnectStandaloneMcp();
+    const configured = report.clients.filter((client) => client.configured).length;
+    console.log(`Clean reconnect complete: ${configured} MCP host${configured === 1 ? "" : "s"} configured.`);
+    console.log("Start a new session in each MCP host to load the clean runtime.");
+}
+function cmdUninstall(flags) {
+    if (flags.confirm !== true) {
+        console.error("Uninstall requires explicit confirmation: echomem-mcp uninstall --confirm");
+        console.error("This preserves EchoMem login, vault credentials, and cloud memories.");
+        process.exitCode = 1;
+        return;
+    }
+    const report = uninstallStandaloneMcp();
+    console.log(`Removed EchoMem MCP from ${report.removedClients.length} host configuration${report.removedClients.length === 1 ? "" : "s"}.`);
+    console.log(`Managed runtime: ${report.removedRuntime ? "removed" : "not installed"}.`);
+    console.log("EchoMem login, vault credentials, and cloud memories were preserved.");
+    if (report.errors.length > 0) {
+        console.error(`Some components could not be removed:\n${report.errors.map((error) => `- ${error}`).join("\n")}`);
+        process.exitCode = 1;
+    }
+}
 async function cmdStatus(flags = {}) {
     const store = new KeyStore();
     const token = store.getToken();
@@ -3815,6 +4180,7 @@ function cmdLogout() {
 const HELP = `EchoMem MCP — local memory bridge
 
 Usage:
+  echomem-mcp connect               Open Connect Echo; authenticate if needed, then manage MCP hosts
   echomem-mcp init                  Legacy/headless setup: configure agents + login + local-history onboarding
   echomem-mcp                       Run the MCP server (stdio; default — used by your editor)
   echomem-mcp setup [--client X]    Detect editor, write its MCP config, then connect this device
@@ -3829,6 +4195,9 @@ Usage:
   echomem-mcp lock                  Remove the local vault key while keeping the device login
   echomem-mcp status                Show token/key/clients
   echomem-mcp doctor [--no-network] Diagnose configured client bridge versions
+  echomem-mcp control               Alias for the returning-user Connect Echo control page
+  echomem-mcp reconnect             Clean-reinstall the managed runtime and repair detected hosts
+  echomem-mcp uninstall --confirm   Remove MCP integration but preserve credentials and cloud memories
   echomem-mcp logout                Remove stored credentials
   echomem-mcp migrate [--since D]   Import your existing Codex/Claude history into your memory
   echomem-mcp migrate --estimate    Estimate migration size/time metadata without uploading transcripts
@@ -3863,6 +4232,9 @@ export async function runCli(argv) {
         }
     }
     switch (cmd) {
+        case "connect":
+            await cmdConnect(flags);
+            return true;
         case "init":
             await cmdInit(flags);
             return true;
@@ -3887,6 +4259,17 @@ export async function runCli(argv) {
         case "doctor":
             cmdDoctor();
             return true;
+        case "control":
+        case "manage":
+            await cmdControl();
+            return true;
+        case "reconnect":
+        case "repair":
+            await cmdReconnect(flags);
+            return true;
+        case "uninstall":
+            cmdUninstall(flags);
+            return true;
         case "logout":
             cmdLogout();
             return true;