open-memex 0.4.1 → 0.5.0-alpha.4

package/docs/V2-DESIGN.md

@@ -882,6 +882,24 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   cannot confirm what the real run will do; and a destructive-path failure must
   speak in user terms. Shipped as 0.4.1 hotfix on the stable line. Approved
   2026-09-29.*
+- **D45** — `init --global` (0.5.0-alpha.1): one-time user-level MCP wiring for
+  VS Code / Cursor. Writes the open-memex server entry to the editor's
+  user-level `mcp.json` (`%APPDATA%\Code\User\mcp.json` on Windows,
+  `~/Library/Application Support/Code/User/mcp.json` on macOS,
+  `~/.config/Code/User/mcp.json` on Linux; `~/.cursor/mcp.json` for Cursor)
+  instead of the project's `.vscode/mcp.json` — init once, the server starts
+  in every project. The entry keeps `cwd: "${workspaceFolder}"` so VS Code
+  substitutes it per window and project-scope resolution keeps working;
+  a per-project config still wins when present. Merge semantics are shared
+  with project-level init (merge, never clobber; `--force` overwrites).
+  Interactive `init` now asks per-project vs user-level for vscode/cursor
+  (default: per-project, preserving old behavior); `--global` skips the
+  question. For opencode, `--global` is a no-op that prints the native-plugin
+  one-liner (already global, and strictly more capable than plain-MCP mode);
+  Visual Studio stays solution-level by design. *Rationale: per-project init
+  is a paper cut that compounds — the data layer already needs zero per-project
+  setup (scope is derived from cwd), so the editor wiring should be able to
+  match. Approved 2026-09-29.*
 - **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
   (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
   `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,
@@ -893,6 +911,49 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   is deliberately broader than `incident`: a postmortem's shape (timeline, root
   cause, actions) is a template concern, not a type. Code
   `MEMORY_TYPE_TAXONOMY` updated to match. Approved 2026-09-28.*
+- **D46** — `init` with no `--client` auto-detects installed editors and wires
+  them all (0.5.0-alpha.2). Detection: VS Code via `code` on `PATH`, well-known
+  install locations, or an existing user-level `mcp.json`; Cursor via `cursor`
+  on `PATH` or `~/.cursor`; opencode via `opencode` on `PATH` or its global
+  config dir; Visual Studio only when the project has a `.sln` (solution-scoped
+  by design). Auto mode always wires user-level where the editor supports it —
+  VS Code / Cursor MCP entry (D45), and for opencode the native plugin entry is
+  now *actually merged* into `~/.config/opencode/opencode.json` (replacing D45's
+  hint-only `--global`), so one init covers every editor and every project.
+  A config file with comments (JSONC) is never rewritten — init prints the
+  manual one-liner instead. Interactive `init` shows the detected editors and
+  confirms wiring all of them (declining falls back to the single-editor
+  prompt); non-interactive (`--yes`) wires all detected with no prompts.
+  An explicit `--client` keeps the old single-editor behavior, including the
+  per-project default for vscode/cursor. *Rationale: Stone's two hats — he
+  writes code in several editors himself, and new users / pilot colleagues
+  should not have to learn `--client` to get started. The help text already
+  promised "default: auto-detect"; D46 makes the code keep that promise.
+  Approved 2026-09-29.*
+- **D47** — when `init` refuses to touch a config file that isn't valid JSON
+  (usually JSONC with comments — VS Code / Cursor / opencode all accept them),
+  it now prints the exact snippet to add by hand: the section key plus the
+  `"open-memex"` entry, pretty-printed. Covers all three MCP-writing paths —
+  vscode/cursor (user + project level), opencode project-level `opencode.jsonc`,
+  and Visual Studio `.mcp.json` — matching the manual hint the opencode
+  `--global` plugin path already printed (D46). The file is still never
+  rewritten; the hint just makes "fix it manually" actionable. Triggered by
+  Stone's real Windows run: his user-level `mcp.json` had comments, init
+  correctly left it alone, but the old message gave him nothing to paste.
+  *Rationale: a refusal without a remedy is a dead end; the entry shape is
+  already computed, so printing it costs nothing. Approved 2026-09-29.*
+- **D48** — new `open-memex uninstall` command, the reverse of `init`
+  (0.5.0-alpha.4). Removes the MCP server entry / opencode native plugin line /
+  Copilot instructions section that `init` wrote; memory data is never touched.
+  Client resolution mirrors `init` (explicit `--client`, else auto-detect with
+  an interactive confirm). Without `--global` it cleans both project-level and
+  user-level files — init may have written either, and a leftover entry at the
+  other level would be a surprise; `--global` restricts to user-level. Empty
+  sections/arrays are pruned; an instructions file that only held the
+  open-memex section is deleted. Non-JSON (JSONC) configs are left untouched
+  with the manual step, same D47 treatment as the init write path.
+  *Rationale: Stone asked "有 uninstall 吗" while testing init on Windows —
+  every write deserves an undo. Approved 2026-09-29.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.1",
+  "version": "0.5.0-alpha.4",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/smoke-pure.ts

@@ -8,6 +8,7 @@ import { DEFAULT_CONFIG } from "../src/config.ts";
 import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "../src/scope.ts";
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
+import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath, printManualEntryHint, removeServerEntry, removePluginEntry, removeInstructionsSection } from "../src/init.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -376,5 +377,108 @@ const near = similarity(
 ok(`similarity near-dup ${near.toFixed(2)} >= ${NEAR_DUP_THRESHOLD}`, near >= NEAR_DUP_THRESHOLD);
 ok("similarity empty → 0", similarity("", "anything") === 0);
 
+console.log("== init --global: userMcpConfigPath / mergeServerEntry ==");
+// D45: user-level MCP config locations, per platform (platform param is injectable).
+ok("vscode win32", userMcpConfigPath("vscode", "win32").endsWith(path.join("Code", "User", "mcp.json")));
+ok("vscode darwin", userMcpConfigPath("vscode", "darwin").includes(path.join("Library", "Application Support", "Code", "User", "mcp.json")));
+ok("vscode linux", userMcpConfigPath("vscode", "linux").endsWith(path.join(".config", "Code", "User", "mcp.json")));
+ok("cursor is ~/.cursor/mcp.json on every platform",
+  (["win32", "darwin", "linux"] as const).every((p) =>
+    userMcpConfigPath("cursor", p).endsWith(path.join(".cursor", "mcp.json"))));
+// mergeServerEntry: pure merge semantics.
+const doc1: Record<string, unknown> = {};
+ok("merge into empty doc adds", mergeServerEntry(doc1, "servers", { command: "x" }, false) === "added");
+ok("entry landed under section", (doc1["servers"] as Record<string, unknown>)["open-memex"] !== undefined);
+ok("existing entry kept without force", mergeServerEntry(doc1, "servers", { command: "y" }, false) === "kept");
+ok("kept entry untouched", ((doc1["servers"] as Record<string, unknown>)["open-memex"] as Record<string, unknown>)["command"] === "x");
+ok("force overwrites", mergeServerEntry(doc1, "servers", { command: "y" }, true) === "added");
+ok("forced entry applied", ((doc1["servers"] as Record<string, unknown>)["open-memex"] as Record<string, unknown>)["command"] === "y");
+const doc2: Record<string, unknown> = { servers: { other: { command: "z" } } };
+ok("merge preserves sibling entries", mergeServerEntry(doc2, "servers", { command: "x" }, false) === "added"
+  && (doc2["servers"] as Record<string, unknown>)["other"] !== undefined);
+
+console.log("== init D46: auto-detect + opencode global plugin ==");
+// opencodeGlobalConfigPath: user-level location, XDG-aware.
+const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), "memex-smoke-"));
+ok("opencode global config under ~/.config/opencode",
+  opencodeGlobalConfigPath(fakeHome).endsWith(path.join(".config", "opencode", "opencode.json")));
+ok("opencode global config honors XDG_CONFIG_HOME", (() => {
+  const prev = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = path.join(fakeHome, "xdg");
+  try {
+    return opencodeGlobalConfigPath(fakeHome).startsWith(path.join(fakeHome, "xdg"));
+  } finally {
+    if (prev === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = prev;
+  }
+})());
+// mergePluginEntry: pure merge semantics.
+const pdoc: Record<string, unknown> = {};
+ok("plugin merge creates array", mergePluginEntry(pdoc, "file:///x", false) === "added"
+  && JSON.stringify(pdoc["plugin"]) === JSON.stringify(["file:///x"]));
+ok("plugin merge dup kept", mergePluginEntry(pdoc, "file:///x", false) === "kept");
+ok("plugin merge force on dup adds nothing twice", mergePluginEntry(pdoc, "file:///x", true) === "added"
+  && (pdoc["plugin"] as unknown[]).length === 1);
+const pdoc2: Record<string, unknown> = { plugin: ["file:///other"], theme: "dark" };
+ok("plugin merge preserves siblings", mergePluginEntry(pdoc2, "file:///x", false) === "added"
+  && (pdoc2["plugin"] as unknown[]).length === 2 && pdoc2["theme"] === "dark");
+// printManualEntryHint: the invalid-JSON bail-out must show the exact snippet to add by hand.
+const hintLines: string[] = [];
+const origErr = console.error;
+console.error = (msg?: unknown) => { hintLines.push(String(msg)); };
+printManualEntryHint("servers", { type: "stdio", command: "open-memex", args: ["mcp"] });
+console.error = origErr;
+const hintText = hintLines.join("\n");
+ok("manual hint names the section", hintText.includes('"servers"'));
+ok("manual hint contains the entry", hintText.includes('"open-memex"') && hintText.includes("stdio"));
+// removeServerEntry: pure removal semantics.
+const rdoc: Record<string, unknown> = { servers: { "open-memex": { command: "x" }, other: { command: "y" } }, untouched: 1 };
+ok("remove deletes the entry", removeServerEntry(rdoc, "servers") === "removed"
+  && !("open-memex" in (rdoc["servers"] as Record<string, unknown>))
+  && "other" in (rdoc["servers"] as Record<string, unknown>));
+ok("remove absent when entry already gone", removeServerEntry(rdoc, "servers") === "absent"
+  && "servers" in rdoc); // sibling kept, section kept
+const rdoc2: Record<string, unknown> = { servers: { "open-memex": { command: "x" } } };
+ok("remove prunes empty section", removeServerEntry(rdoc2, "servers") === "removed" && !("servers" in rdoc2));
+ok("remove absent when no entry", removeServerEntry({ servers: {} }, "servers") === "absent");
+ok("remove absent when no section", removeServerEntry({}, "servers") === "absent");
+// removePluginEntry: removes any open-memex URL, prunes empty array.
+const rpdoc: Record<string, unknown> = { plugin: ["file:///x/open-memex/src/index.ts", "other-plugin"], theme: "dark" };
+ok("plugin remove by substring", removePluginEntry(rpdoc, "open-memex") === "removed"
+  && JSON.stringify(rpdoc["plugin"]) === JSON.stringify(["other-plugin"]));
+const rpdoc3: Record<string, unknown> = { plugin: ["file:///open-memex/y"] };
+ok("plugin remove prunes empty array", removePluginEntry(rpdoc3, "open-memex") === "removed" && !("plugin" in rpdoc3));
+ok("plugin remove absent", removePluginEntry({ plugin: ["other"] }, "open-memex") === "absent");
+// removeInstructionsSection: cuts MARKER..end, "" when nothing remains.
+ok("instructions remove keeps prior content",
+  removeInstructionsSection("# mine\n\n<!-- open-memex -->\n# OpenMemex memory\n") === "# mine\n");
+ok("instructions remove returns empty when wholesale",
+  removeInstructionsSection("<!-- open-memex -->\n# OpenMemex memory\n") === "");
+ok("instructions remove no-op without marker",
+  removeInstructionsSection("# mine\n") === "# mine\n");
+// detectInstalledClients with a fully fake env.
+const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "memex-bin-"));
+fs.writeFileSync(path.join(binDir, "code"), "#!/bin/sh\n");
+const detHome = fs.mkdtempSync(path.join(os.tmpdir(), "memex-home-"));
+fs.mkdirSync(path.join(detHome, ".cursor"), { recursive: true });
+fs.mkdirSync(path.join(detHome, ".config", "opencode"), { recursive: true });
+const detRoot = fs.mkdtempSync(path.join(os.tmpdir(), "memex-root-"));
+const detEnv = { pathEnv: binDir, home: detHome, platform: "linux" as const, root: detRoot, xdgConfigHome: path.join(detHome, ".config") };
+const det = detectInstalledClients(detEnv);
+ok("detects vscode via PATH", det.includes("vscode"));
+ok("detects cursor via ~/.cursor", det.includes("cursor"));
+ok("detects opencode via config dir", det.includes("opencode"));
+ok("no visualstudio without .sln", !det.includes("visualstudio"));
+fs.writeFileSync(path.join(detRoot, "app.sln"), "");
+ok("visualstudio detected with .sln", detectInstalledClients(detEnv).includes("visualstudio"));
+const emptyHome = fs.mkdtempSync(path.join(os.tmpdir(), "memex-empty-"));
+const detEmpty = detectInstalledClients({ pathEnv: "", home: emptyHome, platform: "linux", root: emptyHome, xdgConfigHome: path.join(emptyHome, ".config") });
+ok("empty env detects nothing", detEmpty.length === 0);
+const winBin = fs.mkdtempSync(path.join(os.tmpdir(), "memex-winbin-"));
+fs.writeFileSync(path.join(winBin, "code.cmd"), "@echo off\n");
+ok("win32 detects vscode via code.cmd",
+  detectInstalledClients({ pathEnv: winBin, home: emptyHome, platform: "win32", root: emptyHome, xdgConfigHome: path.join(emptyHome, ".config") }).includes("vscode"));
+for (const d of [fakeHome, binDir, detHome, detRoot, emptyHome, winBin]) fs.rmSync(d, { recursive: true, force: true });
+
 console.log(fails === 0 ? "\nALL PASS" : `\n${fails} FAILURES`);
 process.exit(fails === 0 ? 0 : 1);

package/src/cli.ts

@@ -279,18 +279,40 @@ Examples:
 agent memory instructions. Existing files are merged, never clobbered.
 
 Usage: open-memex init [--client vscode|cursor|opencode|visualstudio]
-              [--instructions personal|project] [--force] [--yes]
+              [--instructions personal|project] [--global] [--force] [--yes]
 
 Flags:
-  --client        editor to configure (default: auto-detect)
+  --client        editor to configure (default: auto-detect all installed editors)
   --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
+  --global        write the MCP server entry to the editor's user-level config
+                  (VS Code / Cursor) — init once, works in every project.
+                  For opencode, --global wires the native plugin at user level
+                  (~/.config/opencode/opencode.json) — no per-project init needed.
   --force         overwrite existing config
   --yes           accept all defaults, never prompt
 
 Examples:
   open-memex init
+  open-memex init --client vscode --global --yes
   open-memex init --client cursor --yes`,
 
+  uninstall: `Remove the editor wiring that \`init\` wrote: the MCP server entry,
+the opencode native plugin line, and the Copilot instructions section.
+Your memories are never touched.
+
+Usage: open-memex uninstall [--client vscode|cursor|opencode|visualstudio]
+              [--global] [--yes]
+
+Flags:
+  --client   editor to unwire (default: auto-detect all installed editors)
+  --global   only the user-level config; without it, both project-level and
+             user-level wiring are removed (init may have written either)
+  --yes      accept all defaults, never prompt
+
+Examples:
+  open-memex uninstall
+  open-memex uninstall --client vscode --yes`,
+
   config: `Show config, or set a key.
 
 Usage: open-memex config [set <key> <value>]
@@ -346,6 +368,8 @@ Usage:
   open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
   open-memex init [--client vscode|cursor|opencode|visualstudio]
               [--instructions personal|project] [--force] [--yes]
+  open-memex uninstall [--client vscode|cursor|opencode|visualstudio]
+              [--global] [--yes]
   open-memex config [set <key> <value>]
   open-memex capture --dry-run "text"
   open-memex doctor
@@ -353,16 +377,19 @@ Usage:
 Every command has its own help with description and examples:
   open-memex <command> --help   (or -h)
 
-One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) writes
-the MCP config for your editor (\`.vscode/mcp.json\`, \`.cursor/mcp.json\`,
-\`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) — no copy-paste
-needed. The Copilot memory instructions default to your user-level
+One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) detects
+your installed editors and wires them all — user-level where the editor supports it
+(VS Code / Cursor MCP config, opencode native plugin), so one init covers every project;
+Visual Studio is included when the project has a solution file (its \`.mcp.json\`
+stays solution-level by design). \`--client\` picks a single editor instead, and a
+single-editor opencode init writes the per-project plain-MCP \`opencode.jsonc\`.
+The Copilot memory instructions default to your user-level
 \`~/.copilot/copilot-instructions.md\` (all projects, never checked into a repo);
 \`--instructions project\` writes \`.github/copilot-instructions.md\` instead for
 teams where everyone uses open-memex.
 Existing files are merged, never clobbered; re-running is safe. On a terminal it
-asks which editor to set up and a couple of settings (keyword capture, first-turn
-injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
+confirms the detected editors and asks a couple of settings (keyword capture,
+first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
 \`open-memex config set <key> <value>\` changes those settings after install.
 
 Once installed globally (\`npm i -g open-memex@alpha\`) the \`open-memex\` command is
@@ -595,7 +622,7 @@ async function main() {
   }
 
   // `init` is a pure file operation (§17 adoption path) — no DB needed.
-  // Interactive when on a TTY (asks editor + settings); --yes skips prompts.
+  // Interactive when on a TTY (confirms detected editors + settings); --yes skips prompts.
   if (cmd === "init") {
     const flags = parseFlags(rest);
     const { initProject } = await import("./init.ts");
@@ -604,6 +631,20 @@ async function main() {
       force: flags["force"] === "true",
       yes: flags["yes"] === "true",
       instructions: flags["instructions"],
+      global: flags["global"] === "true",
+    });
+    return;
+  }
+
+  // `uninstall` reverses `init` — removes the editor wiring; never touches data.
+  // No DB needed (pure file operation, like init).
+  if (cmd === "uninstall") {
+    const flags = parseFlags(rest);
+    const { uninstallProject } = await import("./init.ts");
+    await uninstallProject({
+      client: flags["client"],
+      global: flags["global"] === "true",
+      yes: flags["yes"] === "true",
     });
     return;
   }