open-memex 0.5.0-alpha.4 → 0.5.0-alpha.5

package/AGENTS.md

@@ -64,6 +64,13 @@ previews keyword capture without writing, `open-memex doctor` runs health checks
 (node version, config, scope resolution, storage writability, MCP handshake).
 `open-memex init` with no --client auto-detects and wires every installed editor
 (`--yes` skips, scripts never prompt); `open-memex config set <key> <value>` edits settings after install.
+`open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]`
+reverses init — removes the MCP server entry / opencode plugin line / Copilot
+instructions section; memory data never touched (D48); no --client → auto-detect
+with an interactive confirm, explicit --client never prompts; `--yes` only skips
+that confirm; `--global` limits cleanup to user-level. Empty/whitespace-only
+config files parse as `{}` and are safely populated (D49); non-JSON (JSONC)
+files are left untouched with a printed manual snippet (D47).
 The published `open-memex` bin points at `dist/cli.js` (compiled at publish time).
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.

package/dist/init.js

@@ -170,6 +170,29 @@ export function printManualEntryHint(sectionKey, entry) {
     const pretty = JSON.stringify({ "open-memex": entry }, null, 2).replace(/\n/g, "\n    ");
     console.error(`    ${pretty}`);
 }
+/**
+ * Parse a JSON config file's raw text for merging. An empty or
+ * whitespace-only file counts as `{}` — there is nothing to preserve, so
+ * writers can safely populate it (an empty mcp.json is a normal first-run
+ * state, e.g. created by the editor, not a corrupt file). Returns null when
+ * the content is genuinely unparseable (e.g. JSONC comments) or not an
+ * object, in which case the caller leaves the file untouched and prints the
+ * manual step.
+ */
+export function parseJsonConfig(raw) {
+    if (raw.trim() === "")
+        return {};
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return null;
+    return doc;
+}
 /**
  * Read (or create) a JSON config file, merge the open-memex server entry, write
  * it back. Existing files are merged, never clobbered; invalid JSON is left
@@ -179,14 +202,13 @@ export function printManualEntryHint(sectionKey, entry) {
 function writeServerEntryFile(file, sectionKey, entry, force, mkdir) {
     let doc = {};
     if (fs.existsSync(file)) {
-        try {
-            doc = JSON.parse(fs.readFileSync(file, "utf8"));
-        }
-        catch {
+        const parsed = parseJsonConfig(fs.readFileSync(file, "utf8"));
+        if (parsed === null) {
             console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
             printManualEntryHint(sectionKey, entry);
             return null;
         }
+        doc = parsed;
     }
     const merged = mergeServerEntry(doc, sectionKey, entry, force);
     if (merged === "kept") {
@@ -282,10 +304,8 @@ function writeOpencodeMcpJson(root, force) {
     const file = path.join(root, "opencode.jsonc");
     let doc = {};
     if (fs.existsSync(file)) {
-        try {
-            doc = JSON.parse(fs.readFileSync(file, "utf8"));
-        }
-        catch {
+        const parsed = parseJsonConfig(fs.readFileSync(file, "utf8"));
+        if (parsed === null) {
             console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
             const mc = resolveMcpCommand();
             printManualEntryHint("mcp", {
@@ -295,6 +315,7 @@ function writeOpencodeMcpJson(root, force) {
             });
             return null;
         }
+        doc = parsed;
     }
     const section = (doc["mcp"] ??= {});
     if (section["open-memex"] && !force) {
@@ -323,10 +344,8 @@ function writeVisualStudioMcpJson(root, force) {
     const file = path.join(root, ".mcp.json");
     let doc = {};
     if (fs.existsSync(file)) {
-        try {
-            doc = JSON.parse(fs.readFileSync(file, "utf8"));
-        }
-        catch {
+        const parsed = parseJsonConfig(fs.readFileSync(file, "utf8"));
+        if (parsed === null) {
             console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
             const mc = resolveMcpCommand();
             printManualEntryHint("servers", {
@@ -696,11 +715,8 @@ export function removeInstructionsSection(text) {
 function removeServerEntryFile(file, sectionKey) {
     if (!fs.existsSync(file))
         return "absent";
-    let doc;
-    try {
-        doc = JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
+    const doc = parseJsonConfig(fs.readFileSync(file, "utf8"));
+    if (doc === null) {
         console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
         console.error(`    Delete the "open-memex" key under "${sectionKey}".`);
         return null;
@@ -716,11 +732,8 @@ function removeServerEntryFile(file, sectionKey) {
 function removeOpencodePluginFile(file) {
     if (!fs.existsSync(file))
         return "absent";
-    let doc;
-    try {
-        doc = JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
+    const doc = parseJsonConfig(fs.readFileSync(file, "utf8"));
+    if (doc === null) {
         console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
         console.error(`    Delete the open-memex URL from the "plugin" array.`);
         return null;

package/docs/V2-DESIGN.md

@@ -954,6 +954,19 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   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.*
+- **D49** — empty config files are no longer treated as corrupt (0.5.0-alpha.5).
+  Stone's real Windows run: his user-level `mcp.json` existed but was empty,
+  and `init` refused it with "not valid JSON — left untouched", because
+  `JSON.parse("")` throws. New `parseJsonConfig` helper: empty or
+  whitespace-only content parses as `{}` — there is nothing to preserve, so
+  writers safely populate it; genuinely unparseable content (JSONC comments)
+  or non-objects still return null and keep the D47 leave-untouched + manual
+  hint behavior. Applied to all five config file touch points: the three init
+  writers (vscode/cursor MCP, opencode `opencode.jsonc`, Visual Studio
+  `.mcp.json`) and the two uninstall removers (empty file = nothing to remove).
+  *Rationale: an empty file is the safest write target, not a corrupt file;
+  refusing it sent the user down a manual path for no reason. Triggered by
+  Stone's report 2026-09-29.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.5.0-alpha.4",
+  "version": "0.5.0-alpha.5",
   "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,7 +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";
+import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection } from "../src/init.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -431,6 +431,15 @@ 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"));
+// parseJsonConfig: empty/whitespace-only files are empty docs (safe to populate);
+// genuinely unparseable content (JSONC comments) or non-objects yield null.
+ok("empty file → {}", JSON.stringify(parseJsonConfig("")) === "{}");
+ok("whitespace-only file → {}", JSON.stringify(parseJsonConfig("  \n\t ")) === "{}");
+ok("valid JSON parses", (parseJsonConfig('{"servers":{}}') as Record<string, unknown>)["servers"] !== undefined);
+ok("JSONC comments → null", parseJsonConfig('{\n  // a comment\n}') === null);
+ok("trailing garbage → null", parseJsonConfig('{} trailing') === null);
+ok("array → null", parseJsonConfig("[1,2]") === null);
+ok("scalar → null", parseJsonConfig("42") === null);
 // 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"

package/src/init.ts

@@ -192,6 +192,27 @@ export function printManualEntryHint(sectionKey: string, entry: Record<string, u
   console.error(`    ${pretty}`);
 }
 
+/**
+ * Parse a JSON config file's raw text for merging. An empty or
+ * whitespace-only file counts as `{}` — there is nothing to preserve, so
+ * writers can safely populate it (an empty mcp.json is a normal first-run
+ * state, e.g. created by the editor, not a corrupt file). Returns null when
+ * the content is genuinely unparseable (e.g. JSONC comments) or not an
+ * object, in which case the caller leaves the file untouched and prints the
+ * manual step.
+ */
+export function parseJsonConfig(raw: string): Record<string, unknown> | null {
+  if (raw.trim() === "") return {};
+  let doc: unknown;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  return doc as Record<string, unknown>;
+}
+
 /**
  * Read (or create) a JSON config file, merge the open-memex server entry, write
  * it back. Existing files are merged, never clobbered; invalid JSON is left
@@ -207,13 +228,13 @@ function writeServerEntryFile(
 ): string | null {
   let doc: Record<string, unknown> = {};
   if (fs.existsSync(file)) {
-    try {
-      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
-    } catch {
+    const parsed = parseJsonConfig(fs.readFileSync(file, "utf8"));
+    if (parsed === null) {
       console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
       printManualEntryHint(sectionKey, entry);
       return null;
     }
+    doc = parsed;
   }
   const merged = mergeServerEntry(doc, sectionKey, entry, force);
   if (merged === "kept") {
@@ -316,9 +337,8 @@ function writeOpencodeMcpJson(root: string, force: boolean): string | null {
   const file = path.join(root, "opencode.jsonc");
   let doc: Record<string, unknown> = {};
   if (fs.existsSync(file)) {
-    try {
-      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
-    } catch {
+    const parsed = parseJsonConfig(fs.readFileSync(file, "utf8"));
+    if (parsed === null) {
       console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
       const mc = resolveMcpCommand();
       printManualEntryHint("mcp", {
@@ -328,6 +348,7 @@ function writeOpencodeMcpJson(root: string, force: boolean): string | null {
       });
       return null;
     }
+    doc = parsed;
   }
   const section = ((doc["mcp"] ??= {}) as Record<string, unknown>);
   if (section["open-memex"] && !force) {
@@ -357,9 +378,8 @@ function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
   const file = path.join(root, ".mcp.json");
   let doc: Record<string, unknown> = {};
   if (fs.existsSync(file)) {
-    try {
-      doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
-    } catch {
+    const parsed = parseJsonConfig(fs.readFileSync(file, "utf8"));
+    if (parsed === null) {
       console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
       const mc = resolveMcpCommand();
       printManualEntryHint("servers", {
@@ -761,10 +781,8 @@ export function removeInstructionsSection(text: string): string {
  */
 function removeServerEntryFile(file: string, sectionKey: string): "removed" | "absent" | null {
   if (!fs.existsSync(file)) return "absent";
-  let doc: Record<string, unknown>;
-  try {
-    doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
-  } catch {
+  const doc = parseJsonConfig(fs.readFileSync(file, "utf8"));
+  if (doc === null) {
     console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
     console.error(`    Delete the "open-memex" key under "${sectionKey}".`);
     return null;
@@ -780,10 +798,8 @@ function removeServerEntryFile(file: string, sectionKey: string): "removed" | "a
 /** Remove the open-memex plugin URL from one opencode user-level config file. */
 function removeOpencodePluginFile(file: string): "removed" | "absent" | null {
   if (!fs.existsSync(file)) return "absent";
-  let doc: Record<string, unknown>;
-  try {
-    doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
-  } catch {
+  const doc = parseJsonConfig(fs.readFileSync(file, "utf8"));
+  if (doc === null) {
     console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
     console.error(`    Delete the open-memex URL from the "plugin" array.`);
     return null;