@echomem/mcp 1.4.50 → 1.4.52

package/README.md

@@ -54,7 +54,7 @@ npx -y @echomem/mcp@latest init
 Windows PowerShell:
 
 ```powershell
-npx.cmd -y @echomem/mcp@latest init
+npx.cmd -y @echomem/mcp@latest connect
 ```
 
 The one-off `npx` command is the recommended install path; it stages a durable per-user runtime
@@ -63,7 +63,9 @@ Node if `npx.cmd` is not found.
 
 | Command | What it does |
 |---|---|
-| `npm i -g @echomem/mcp@latest && echomem-mcp init` | Legacy/headless setup for installed agents + login |
+| `npx -y @echomem/mcp@latest connect` | Open Connect Echo for account readiness, per-host setup, Doctor, repair, and uninstall (use `npx.cmd` in Windows PowerShell) |
+| `npx -y @echomem/mcp@latest init` | One-command setup for installed agents + login (use `npx.cmd` in Windows PowerShell) |
+| `npm i -g @echomem/mcp@latest`, then `echomem-mcp init` | Optional global install for a persistent CLI command |
 | `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and configure just the detected editor |
 | `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop\|claude-code\|codex]` | Write client config + log in |
@@ -75,8 +77,31 @@ Node if `npx.cmd` is not found.
 | `echomem-mcp lock` | Remove the local vault key while keeping the device login |
 | `echomem-mcp status` | Show token / key / detected clients, configured bridge versions, and update guidance |
 | `echomem-mcp doctor [--no-network]` | Diagnose configured client bridge versions |
+| `echomem-mcp control` / `manage` | Compatibility aliases for the returning-user Connect Echo page |
+| `echomem-mcp reconnect` | Clean-reinstall EchoMem's managed runtime, clear inactive runtime cache, and repair detected host entries |
+| `echomem-mcp uninstall --confirm` | Remove EchoMem MCP host entries/runtime while preserving login, vault credentials, and cloud memories |
 | `echomem-mcp logout` | Remove stored credentials |
 
+### Windows Connect Echo (no desktop app required)
+
+If you installed the optional global CLI, run this from PowerShell:
+
+```powershell
+echomem-mcp connect
+```
+
+For the recommended one-off install, launch the same local control page with:
+
+```powershell
+npx.cmd -y @echomem/mcp@latest connect
+```
+
+The page binds only to `127.0.0.1` and uses a per-launch nonce. It validates account/vault state,
+shows each detected MCP host independently, and provides Connect, Repair, Disconnect, Doctor, and
+clean Reconnect actions. **Uninstall MCP** stays under Advanced controls and removes only EchoMem-owned
+host entries, hooks, guidance, skills, and managed runtime files; it does not remove the local
+EchoMem credential store or any cloud memory. Restart each agent after configuration changes.
+
 The bridge reports its package version in MCP server instructions and in tool descriptions. It also
 checks npm for a newer published bridge using a cached, non-blocking check. Standalone installations
 stage compatible updates in the background under `~/.echomem/mcp-runtime` and atomically activate

package/dist/config-files.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function isErrno(error, code) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === code;
+}
+/**
+ * Read a user-owned JSON configuration without treating corruption as an empty file.
+ * Setup must fail closed here: replacing malformed JSON would destroy unrelated client settings.
+ */
+export function readJsonObjectFile(file, label = "configuration") {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return {};
+        throw new Error(`Could not read ${label} at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Could not safely update ${label} at ${file} because the existing file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Could not safely update ${label} at ${file} because the existing JSON root is not an object.`);
+    }
+    return parsed;
+}
+/** Write beside the destination and rename only after the complete replacement is durable locally. */
+export function atomicWriteTextFile(file, content) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true });
+    const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    let mode;
+    try {
+        mode = fs.statSync(file).mode;
+    }
+    catch {
+        /* A fresh file uses the process default mode. */
+    }
+    try {
+        fs.writeFileSync(temporary, content, mode === undefined ? undefined : { mode });
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch {
+            /* Preserve the original error. */
+        }
+        throw error;
+    }
+}
+export function atomicWriteJsonObject(file, value) {
+    atomicWriteTextFile(file, JSON.stringify(value, null, 2));
+}

package/dist/headless-runtime.js

@@ -173,28 +173,79 @@ function finishStaging(staging, destination, version) {
     fs.renameSync(staging, destination);
     return activateRuntime(destination, version);
 }
-export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION) {
+function pruneInactiveRuntimeVersions(activeVersion) {
+    const removed = [];
+    let entries = [];
+    try {
+        entries = fs.readdirSync(versionsRoot(), { withFileTypes: true });
+    }
+    catch {
+        return removed;
+    }
+    for (const entry of entries) {
+        // A dot-prefixed directory is another install's staging area. Never prune in-flight work.
+        if (entry.name === activeVersion || entry.name.startsWith("."))
+            continue;
+        try {
+            safeVersion(entry.name);
+        }
+        catch {
+            continue;
+        }
+        const target = path.join(versionsRoot(), entry.name);
+        try {
+            fs.rmSync(target, { recursive: true, force: true });
+            removed.push(entry.name);
+        }
+        catch {
+            /* Cache pruning is best effort; the active clean runtime is already safe. */
+        }
+    }
+    return removed;
+}
+export function installHeadlessRuntimeSync(targetVersion = MCP_PACKAGE_VERSION, options = {}) {
     const version = safeVersion(targetVersion);
     const existing = readHeadlessRuntimeInstallation();
-    if (existing?.version === version)
+    if (!options.force && existing?.version === version)
         return existing;
     const destination = path.join(versionsRoot(), version);
-    if (readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
-        return activateRuntime(destination, version);
+    if (!options.force && readPackageVersion(destination) === version && fs.existsSync(packageEntryForPrefix(destination))) {
+        const installation = activateRuntime(destination, version);
+        if (options.prune)
+            pruneInactiveRuntimeVersions(version);
+        return installation;
     }
-    const { staging } = prepareStaging(version);
-    const npm = resolveNpmInvocation();
+    const releaseLock = acquireUpdateLock();
+    if (!releaseLock)
+        throw new Error("Another EchoMem runtime update is already in progress. Retry reconnect in a moment.");
+    let staging = "";
     try {
+        staging = prepareStaging(version).staging;
+        const npm = resolveNpmInvocation();
         execFileSync(npm.command, [...npm.prefixArgs, ...npmInstallArguments(staging, version)], {
             stdio: "inherit",
             windowsHide: true,
         });
-        return finishStaging(staging, destination, version);
+        const installation = finishStaging(staging, destination, version);
+        if (options.prune)
+            pruneInactiveRuntimeVersions(version);
+        return installation;
     }
     catch (error) {
-        fs.rmSync(staging, { recursive: true, force: true });
+        if (staging)
+            fs.rmSync(staging, { recursive: true, force: true });
         throw new Error(`Could not stage ${MCP_PACKAGE_NAME}@${version}: ${error instanceof Error ? error.message : String(error)}`);
     }
+    finally {
+        releaseLock();
+    }
+}
+/** Remove only EchoMem's staged standalone runtime. Credentials and cloud data live elsewhere. */
+export function removeHeadlessRuntime() {
+    const root = headlessRuntimeRoot();
+    const removed = fs.existsSync(root);
+    fs.rmSync(root, { recursive: true, force: true });
+    return { removed, path: root };
 }
 function acquireUpdateLock() {
     const lock = path.join(headlessRuntimeRoot(), "update.lock");

package/dist/hud/hooks.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { atomicWriteJsonObject, readJsonObjectFile } from "../config-files.js";
 import { resolveDurableDistPath } from "../durable-entry.js";
 /**
  * Hook commands are persisted into another program's settings and must keep working long after this
@@ -45,17 +46,59 @@ export function installSourceSessionHooks(mode) {
     }
     return written;
 }
+/** Remove only EchoMem-owned lifecycle hook groups and preserve every unrelated user hook. */
+export function removeLifecycleHooks(mode) {
+    const files = [];
+    let removedGroups = 0;
+    const targets = [];
+    if (mode === "codex" || mode === "both" || mode === "auto") {
+        targets.push(path.join(profileDirectory("CODEX_HOME", ".codex"), "hooks.json"));
+    }
+    if (mode === "claude-code" || mode === "both" || mode === "auto") {
+        targets.push(path.join(profileDirectory("CLAUDE_CONFIG_DIR", ".claude"), "settings.json"));
+    }
+    for (const file of targets) {
+        if (!fs.existsSync(file))
+            continue;
+        const content = readHooksFile(file);
+        const hooks = content.hooks;
+        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+            continue;
+        let changed = false;
+        for (const [event, value] of Object.entries(hooks)) {
+            if (!Array.isArray(value))
+                continue;
+            const kept = value.filter((group) => !isEchoLifecycleGroup(group));
+            const removed = value.length - kept.length;
+            if (removed === 0)
+                continue;
+            removedGroups += removed;
+            changed = true;
+            if (kept.length > 0)
+                hooks[event] = kept;
+            else
+                delete hooks[event];
+        }
+        if (!changed)
+            continue;
+        if (Object.keys(hooks).length === 0)
+            delete content.hooks;
+        atomicWriteJsonObject(file, content);
+        files.push(file);
+    }
+    return { files, removedGroups };
+}
 function installCodexHooks() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const hookCommand = hookCommandFor("index.js", "summary --client codex --json");
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
-    content.hooks.PostToolUse = mergeHookGroup(content.hooks.PostToolUse, { matcher: "*", hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    content.hooks.PostCompact = mergeHookGroup(content.hooks.PostCompact, { hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    content.hooks.Stop = mergeHookGroup(content.hooks.Stop, { hooks: [{ type: "command", command: hookCommand, timeout: 5 }] });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    content.hooks.PostToolUse = mergeHookGroup(content.hooks.PostToolUse, { matcher: "*", hooks: [codexCommandHook(hookCommand, 5)] });
+    content.hooks.PostCompact = mergeHookGroup(content.hooks.PostCompact, { hooks: [codexCommandHook(hookCommand, 5)] });
+    content.hooks.Stop = mergeHookGroup(content.hooks.Stop, { hooks: [codexCommandHook(hookCommand, 5)] });
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function saveCheckpointCommand() {
@@ -65,24 +108,19 @@ function sourceSessionCommand() {
     return hookCommandFor(path.join("hud", "cli.js"), "bind-source-session");
 }
 function installCodexSourceSessionHook() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.SessionStart = mergeSourceSessionGroup(content.hooks.SessionStart, {
-        hooks: [{
-                type: "command",
-                command: sourceSessionCommand(),
-                timeout: 5,
-                statusMessage: "Binding EchoMem to this conversation",
-            }],
+        hooks: [codexCommandHook(sourceSessionCommand(), 5, "Binding EchoMem to this conversation")],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSourceSessionHook() {
-    const dir = path.join(os.homedir(), ".claude");
+    const dir = profileDirectory("CLAUDE_CONFIG_DIR", ".claude");
     const file = path.join(dir, "settings.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
@@ -95,28 +133,23 @@ function installClaudeCodeSourceSessionHook() {
                 statusMessage: "Binding EchoMem to this conversation",
             }],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installCodexSaveCheckpointHook() {
-    const dir = path.join(os.homedir(), ".codex");
+    const dir = profileDirectory("CODEX_HOME", ".codex");
     const file = path.join(dir, "hooks.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
     content.hooks = content.hooks || {};
     content.hooks.Stop = mergeSaveCheckpointGroup(content.hooks.Stop, {
-        hooks: [{
-                type: "command",
-                command: saveCheckpointCommand(),
-                timeout: 10,
-                statusMessage: "Checking whether completed work should be remembered",
-            }],
+        hooks: [codexCommandHook(saveCheckpointCommand(), 10, "Checking whether completed work should be remembered")],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSaveCheckpointHook() {
-    const dir = path.join(os.homedir(), ".claude");
+    const dir = profileDirectory("CLAUDE_CONFIG_DIR", ".claude");
     const file = path.join(dir, "settings.json");
     fs.mkdirSync(dir, { recursive: true });
     const content = readHooksFile(file);
@@ -129,22 +162,40 @@ function installClaudeCodeSaveCheckpointHook() {
                 statusMessage: "Checking whether completed work should be remembered",
             }],
     });
-    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    atomicWriteJsonObject(file, content);
     return file;
 }
 function installClaudeCodeSnippet() {
-    const dir = path.join(os.homedir(), ".claude", "echo-ctx");
+    const dir = path.join(profileDirectory("CLAUDE_CONFIG_DIR", ".claude"), "echo-ctx");
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
 function readHooksFile(file) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    return readJsonObjectFile(file, "agent hooks");
+}
+function profileDirectory(envKey, fallbackName) {
+    const home = os.homedir();
+    const configured = process.env[envKey]?.trim();
+    if (!configured)
+        return path.join(home, fallbackName);
+    if (configured === "~")
+        return home;
+    if (configured.startsWith("~/") || configured.startsWith("~\\")) {
+        return path.join(home, configured.slice(2));
     }
-    catch {
-        return {};
+    if (!path.isAbsolute(configured)) {
+        throw new Error(`${envKey} must be an absolute path or start with ~/`);
     }
+    return path.normalize(configured);
+}
+function codexCommandHook(command, timeout, statusMessage) {
+    return {
+        type: "command",
+        command,
+        commandWindows: command,
+        timeout,
+        ...(statusMessage ? { statusMessage } : {}),
+    };
 }
 function mergeHookGroup(existing, group) {
     const groups = Array.isArray(existing) ? existing.filter((item) => !isEchoHudGroup(item)) : [];
@@ -176,3 +227,6 @@ function isEchoSaveCheckpointGroup(value) {
         return false;
     return JSON.stringify(value).includes("save-checkpoint");
 }
+function isEchoLifecycleGroup(value) {
+    return isEchoHudGroup(value) || isEchoSourceSessionGroup(value) || isEchoSaveCheckpointGroup(value);
+}