@ijfw/install 1.6.0 → 1.6.2

package/dist/install.js

@@ -292,21 +292,42 @@ function prettyName(targetId) {
   };
   return map[targetId] || String(targetId);
 }
+function backupTimestamp() {
+  const d = /* @__PURE__ */ new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
 function readJsonOrEmpty(path3) {
   if (!existsSync3(path3)) return {};
+  let raw;
+  try {
+    raw = readFileSync2(path3, "utf8");
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    throw new Error(`cannot read existing config at ${path3} (${msg}) -- fix permissions and re-run.`);
+  }
+  if (raw.charCodeAt(0) === 65279) raw = raw.slice(1);
+  if (!raw || raw.trim() === "") return {};
   try {
-    const raw = readFileSync2(path3, "utf8");
-    if (!raw || raw.trim() === "") return {};
     const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
-    return parsed;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
   } catch {
-    return {};
   }
+  const bak = `${path3}.corrupt-${backupTimestamp()}.bak`;
+  try {
+    copyFileSync(path3, bak);
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    throw new Error(
+      `existing config at ${path3} is not valid JSON and a safety copy could not be written (${msg}) -- fix or move the file, then re-run.`
+    );
+  }
+  printWarn(`existing config at ${path3} is not valid JSON -- original saved to ${bak}; starting fresh with the IJFW entry only`);
+  return {};
 }
 function mergeJson(dst, serverJs, ts) {
   mkdirSync2(dirname3(dst), { recursive: true });
-  requireBackup(dst, ts);
+  requireBackup(dst, ts || backupTimestamp());
   const doc = readJsonOrEmpty(dst);
   if (!doc.mcpServers || typeof doc.mcpServers !== "object") doc.mcpServers = {};
   const isWin = IS_WIN;
@@ -334,7 +355,7 @@ function mergeJson(dst, serverJs, ts) {
 }
 function mergeToml(dst, serverJs, ts) {
   mkdirSync2(dirname3(dst), { recursive: true });
-  requireBackup(dst, ts);
+  requireBackup(dst, ts || backupTimestamp());
   let text = "";
   try {
     text = existsSync3(dst) ? readFileSync2(dst, "utf8") : "";
@@ -385,32 +406,6 @@ function stripTomlSection(text, sectionName) {
   }
   return out.join("\n");
 }
-function mergeYamlMcp(dst, serverJs, ts) {
-  mkdirSync2(dirname3(dst), { recursive: true });
-  if (ts) backup(dst, ts);
-  let text = "";
-  try {
-    text = existsSync3(dst) ? readFileSync2(dst, "utf8") : "";
-  } catch {
-    text = "";
-  }
-  text = stripSentinelBlock(text, "# IJFW-MCP-BEGIN ijfw-memory", "# IJFW-MCP-END ijfw-memory");
-  if (!/^mcp_servers:/m.test(text)) {
-    if (text && !text.endsWith("\n")) text += "\n";
-    text += "\nmcp_servers:\n";
-  }
-  const escaped = String(serverJs).replace(/"/g, '\\"');
-  let block = "";
-  if (!text.endsWith("\n")) block += "\n";
-  block += "# IJFW-MCP-BEGIN ijfw-memory\n";
-  block += "  ijfw-memory:\n";
-  block += '    command: "node"\n';
-  block += `    args: ["${escaped}"]
-`;
-  block += "    enabled: true\n";
-  block += "# IJFW-MCP-END ijfw-memory\n";
-  writeAtomic(dst, text + block, { mode: 384 });
-}
 function stripSentinelBlock(text, beginMark, endMark) {
   const lines = text.split("\n");
   const out = [];
@@ -500,7 +495,7 @@ function isIndentedEnabledLine(line) {
 }
 function opencodeMerge(dst, serverJs, ts) {
   mkdirSync2(dirname3(dst), { recursive: true });
-  if (ts) backup(dst, ts);
+  backup(dst, ts || backupTimestamp());
   const doc = readJsonOrEmpty(dst);
   if (!doc.mcp || typeof doc.mcp !== "object") doc.mcp = {};
   doc.mcp["ijfw-memory"] = { type: "local", command: ["node", serverJs] };
@@ -508,7 +503,7 @@ function opencodeMerge(dst, serverJs, ts) {
 }
 function openclawMerge(dst, serverJs, ts) {
   mkdirSync2(dirname3(dst), { recursive: true });
-  if (ts) backup(dst, ts);
+  backup(dst, ts || backupTimestamp());
   const doc = readJsonOrEmpty(dst);
   if (!doc.mcp || typeof doc.mcp !== "object") doc.mcp = {};
   if (!doc.mcp.servers || typeof doc.mcp.servers !== "object") doc.mcp.servers = {};
@@ -554,7 +549,7 @@ function clineMerge(serverJs, home, ts) {
   if (!userDir) userDir = osDefault;
   const dst = join3(userDir, "globalStorage", ext, "settings", "cline_mcp_settings.json");
   mkdirSync2(dirname3(dst), { recursive: true });
-  if (ts) backup(dst, ts);
+  backup(dst, ts || backupTimestamp());
   const doc = readJsonOrEmpty(dst);
   if (!doc.mcpServers || typeof doc.mcpServers !== "object") doc.mcpServers = {};
   doc.mcpServers["ijfw-memory"] = {
@@ -633,6 +628,9 @@ function ensureDir(p) {
   } catch {
   }
 }
+function stripBom(s) {
+  return s && s.charCodeAt(0) === 65279 ? s.slice(1) : s;
+}
 function copyIfAbsent(src, dst) {
   if (!existsSync4(src)) return false;
   if (existsSync4(dst)) return false;
@@ -716,13 +714,18 @@ async function installClaude(ctx) {
     "known_marketplaces.json"
   );
   ensureDir(join4(ctx.home, ".claude", "plugins"));
-  backup(claudeSettings, ctx.ts);
+  const settingsBak = requireBackup(claudeSettings, ctx.ts);
   let settings = {};
   if (existsSync4(claudeSettings)) {
     try {
-      settings = JSON.parse(readFileSync3(claudeSettings, "utf8") || "{}");
+      settings = JSON.parse(stripBom(readFileSync3(claudeSettings, "utf8")) || "{}");
     } catch {
-      settings = {};
+      ctx.log.warn("~/.claude/settings.json could not be parsed as JSON -- IJFW will not modify it.");
+      if (settingsBak) {
+        ctx.log.warn(`A copy of the current file was preserved at ${settingsBak}.`);
+      }
+      ctx.log.warn("Fix the JSON syntax error and re-run `ijfw install`.");
+      return { status: "noop" };
     }
   }
   if (!settings || typeof settings !== "object") settings = {};
@@ -736,7 +739,7 @@ async function installClaude(ctx) {
   let mp = {};
   if (existsSync4(claudeMarketplaces)) {
     try {
-      mp = JSON.parse(readFileSync3(claudeMarketplaces, "utf8") || "{}");
+      mp = JSON.parse(stripBom(readFileSync3(claudeMarketplaces, "utf8")) || "{}");
     } catch {
       mp = {};
     }
@@ -785,7 +788,7 @@ async function installCodex(ctx) {
   }
   const configToml = join4(ctx.home, ".codex", "config.toml");
   ensureDir(dirname4(configToml));
-  mergeToml(configToml, ctx.serverJsNative);
+  mergeToml(configToml, ctx.serverJsNative, ctx.ts);
   const hooksDst = join4(ctx.home, ".codex", "hooks.json");
   const hooksSrc = join4(ctx.repoRoot, "codex", ".codex", "hooks.json");
   const hooksBase = join4(ctx.home, ".codex", "hooks");
@@ -914,18 +917,41 @@ async function installGemini(ctx) {
   }
   const dst = join4(ctx.home, ".gemini", "settings.json");
   ensureDir(dirname4(dst));
-  mergeJson(dst, ctx.serverJsNative);
+  mergeJson(dst, ctx.serverJsNative, ctx.ts);
   const extDst = join4(ctx.home, ".gemini", "extensions", "ijfw");
   const extSrc = join4(ctx.repoRoot, "gemini", "extensions", "ijfw");
   for (const sub of ["hooks", "skills", "commands", "agents", "policies"]) {
     ensureDir(join4(extDst, sub));
   }
-  for (const rel of [
-    "gemini-extension.json",
-    "IJFW.md",
-    "hooks/hooks.json",
-    "policies/ijfw.toml"
-  ]) {
+  for (const rel of ["gemini-extension.json", "hooks/hooks.json"]) {
+    const srcFile = join4(extSrc, rel);
+    if (!existsSync4(srcFile)) continue;
+    let desired = "";
+    try {
+      desired = readFileSync3(srcFile, "utf8");
+    } catch {
+      continue;
+    }
+    desired = desired.split("{{extensionPath}}").join(extDst);
+    const dstFile = join4(extDst, rel);
+    let current = null;
+    try {
+      current = existsSync4(dstFile) ? readFileSync3(dstFile, "utf8") : null;
+    } catch {
+      current = null;
+    }
+    if (current === desired) continue;
+    if (current !== null) {
+      try {
+        copyFileSync2(dstFile, `${dstFile}.bak.${ctx.ts}`);
+      } catch {
+      }
+      ctx.log.note(`Updated ${rel} (previous copy backed up to ${rel}.bak.${ctx.ts})`);
+    }
+    ensureDir(dirname4(dstFile));
+    writeAtomic(dstFile, desired);
+  }
+  for (const rel of ["IJFW.md", "policies/ijfw.toml"]) {
     const dstFile = join4(extDst, rel);
     if (!existsSync4(dstFile)) {
       ensureDir(dirname4(dstFile));
@@ -1051,6 +1077,101 @@ function renderWaylandPluginToml(ctx) {
     ""
   ].join("\n");
 }
+function stripSentinelLines(text, beginMark, endMark) {
+  const lines = text.split("\n");
+  const out = [];
+  let skip = false;
+  for (const line of lines) {
+    if (line === beginMark) {
+      skip = true;
+      continue;
+    }
+    if (line === endMark) {
+      skip = false;
+      continue;
+    }
+    if (skip) continue;
+    out.push(line);
+  }
+  return out.join("\n");
+}
+function hermesMergeYamlMcp(ctx, dst, serverJs) {
+  ensureDir(dirname4(dst));
+  requireBackup(dst, ctx.ts);
+  let text = "";
+  try {
+    text = existsSync4(dst) ? stripBom(readFileSync3(dst, "utf8")) : "";
+  } catch {
+    text = "";
+  }
+  text = stripSentinelLines(text, HERMES_MCP_BEGIN, HERMES_MCP_END);
+  const escaped = String(serverJs).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const block = [
+    HERMES_MCP_BEGIN,
+    "  ijfw-memory:",
+    '    command: "node"',
+    `    args: ["${escaped}"]`,
+    "    enabled: true",
+    HERMES_MCP_END
+  ];
+  const lines = text.split("\n");
+  let anchorIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("mcp_servers:")) {
+      const rest = line.slice("mcp_servers:".length).trim();
+      if (rest === "" || rest.startsWith("#")) {
+        anchorIdx = i;
+        break;
+      }
+      const beforeComment = rest.split("#")[0].replace(/\s/g, "");
+      if (beforeComment === "{}") {
+        lines[i] = "mcp_servers:";
+        anchorIdx = i;
+        break;
+      }
+    }
+  }
+  let merged;
+  if (anchorIdx >= 0) {
+    lines.splice(anchorIdx + 1, 0, ...block);
+    merged = lines.join("\n");
+  } else if (/^mcp_servers:/m.test(text)) {
+    ctx.log.warn("Hermes config.yaml uses an inline mcp_servers map -- cannot merge safely.");
+    ctx.log.warn('Add an "ijfw-memory" entry to mcp_servers manually (command: node, args: [server.js path]).');
+    return false;
+  } else {
+    const prefix = text.trim() === "" ? "" : (text.endsWith("\n") ? text : `${text}
+`) + "\n";
+    merged = `${prefix}mcp_servers:
+${block.join("\n")}`;
+  }
+  if (!merged.endsWith("\n")) merged += "\n";
+  writeAtomic(dst, merged, { mode: 384 });
+  return true;
+}
+function hermesInlineEnabledHas(dst, pluginName) {
+  let text = "";
+  try {
+    text = existsSync4(dst) ? readFileSync3(dst, "utf8") : "";
+  } catch {
+    return false;
+  }
+  const esc = pluginName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const nameRe = new RegExp(`[\\[,]\\s*["']?${esc}["']?\\s*[,\\]]`);
+  let inPlugins = false;
+  for (const line of text.split("\n")) {
+    if (/^plugins:\s*$/.test(line)) {
+      inPlugins = true;
+      continue;
+    }
+    if (inPlugins && /^\S/.test(line) && line.trim() !== "") inPlugins = false;
+    if (inPlugins && /^\s+enabled:\s*\[.+\]\s*$/.test(line) && nameRe.test(line)) {
+      return true;
+    }
+  }
+  return false;
+}
 async function installHermes(ctx) {
   if (ctx.ijfwCustomDir) {
     return customDirNoop(
@@ -1062,7 +1183,7 @@ async function installHermes(ctx) {
   }
   const dst = join4(ctx.home, ".hermes", "config.yaml");
   ensureDir(dirname4(dst));
-  mergeYamlMcp(dst, ctx.serverJsNative);
+  hermesMergeYamlMcp(ctx, dst, ctx.serverJsNative);
   ensureDir(join4(ctx.home, ".hermes"));
   copyIfAbsent(
     join4(ctx.repoRoot, "hermes", "HERMES.md"),
@@ -1087,40 +1208,44 @@ async function installHermes(ctx) {
     }
     if (readdirErr) {
       ctx.log.warn(`Hermes plugin tree readdir failed: ${readdirErr.message || readdirErr}`);
-    }
-    const srcNames = new Set(entries.filter((n) => n !== "__pycache__"));
-    let dstEntries = [];
-    try {
-      dstEntries = readdirSync(pluginDst);
-    } catch {
-    }
-    for (const name of dstEntries) {
-      if (name === "__pycache__") continue;
-      if (!srcNames.has(name)) {
-        try {
-          rmSync(join4(pluginDst, name), { recursive: true, force: true });
-        } catch (err) {
-          ctx.log.warn(`Hermes plugin: could not remove stale ${name}: ${err.message || err}`);
+      ctx.log.warn("Leaving the installed Hermes plugin tree untouched.");
+    } else {
+      const srcNames = new Set(entries.filter((n) => n !== "__pycache__"));
+      let dstEntries = [];
+      try {
+        dstEntries = readdirSync(pluginDst);
+      } catch {
+      }
+      for (const name of dstEntries) {
+        if (name === "__pycache__") continue;
+        if (!srcNames.has(name)) {
+          try {
+            rmSync(join4(pluginDst, name), { recursive: true, force: true });
+          } catch (err) {
+            ctx.log.warn(`Hermes plugin: could not remove stale ${name}: ${err.message || err}`);
+          }
         }
       }
-    }
-    for (const name of entries) {
-      if (name === "__pycache__") continue;
-      const src = join4(pluginSrc, name);
-      const dstEntry = join4(pluginDst, name);
-      try {
-        const st = statSync2(src);
-        if (st.isDirectory()) {
-          cpSync(src, dstEntry, { recursive: true, force: true });
-        } else if (st.isFile()) {
-          copyFileSync2(src, dstEntry);
+      for (const name of entries) {
+        if (name === "__pycache__") continue;
+        const src = join4(pluginSrc, name);
+        const dstEntry = join4(pluginDst, name);
+        try {
+          const st = statSync2(src);
+          if (st.isDirectory()) {
+            cpSync(src, dstEntry, { recursive: true, force: true });
+          } else if (st.isFile()) {
+            copyFileSync2(src, dstEntry);
+          }
+        } catch {
         }
-      } catch {
       }
     }
   }
-  mergeYamlPluginsEnabled(dst, "ijfw");
-  mergeYamlHook(dst, "plugins/ijfw/hooks/pre_tool_use_extension_check.py", ctx.ts);
+  if (!hermesInlineEnabledHas(dst, "ijfw")) {
+    mergeYamlPluginsEnabled(dst, "ijfw");
+  }
+  mergeYamlHook(dst, "plugins/ijfw/hooks/pre_tool_use_extension_check.py");
   ctx.log.ok("Installed Hermes bundle: MCP + HERMES.md + skills + plugin + tier-2 hook");
   return { status: "ok" };
 }
@@ -1148,13 +1273,13 @@ async function installCursor(ctx) {
   }
   const dst = join4(cwd, ".cursor", "mcp.json");
   ensureDir(dirname4(dst));
-  mergeJson(dst, ctx.serverJsNative);
+  mergeJson(dst, ctx.serverJsNative, ctx.ts);
   const rulesDir = join4(cwd, ".cursor", "rules");
   ensureDir(rulesDir);
   const ruleSrc = join4(ctx.repoRoot, "cursor", ".cursor", "rules", "ijfw.mdc");
   if (existsSync4(ruleSrc)) {
     try {
-      copyFileSync2(ruleSrc, join4(rulesDir, "ijfw.mdc"));
+      installHook(ruleSrc, join4(rulesDir, "ijfw.mdc"), ctx.ts);
     } catch {
     }
   }
@@ -1172,7 +1297,7 @@ async function installWindsurf(ctx) {
   }
   const dst = join4(ctx.home, ".codeium", "windsurf", "mcp_config.json");
   ensureDir(dirname4(dst));
-  mergeJson(dst, ctx.serverJsNative);
+  mergeJson(dst, ctx.serverJsNative, ctx.ts);
   const cwd = ctx.cwd || process.cwd();
   if (!guardProjectWrite(cwd, ctx.home, {
     platformLabel: "Windsurf project rules (.windsurfrules)",
@@ -1198,9 +1323,12 @@ async function installWindsurf(ctx) {
   }
   return { status: "ok" };
 }
+var HERMES_MCP_BEGIN, HERMES_MCP_END;
 var init_install_targets_1_7 = __esm({
   "src/install-targets-1-7.js"() {
     init_install_helpers();
+    HERMES_MCP_BEGIN = "# IJFW-MCP-BEGIN ijfw-memory";
+    HERMES_MCP_END = "# IJFW-MCP-END ijfw-memory";
   }
 });
 
@@ -1230,6 +1358,30 @@ function commandExists(name) {
   const r = spawnSync(probeCmd, [name], { stdio: "ignore" });
   return r.status === 0;
 }
+function vscodeMcpMerge(dst, serverJs, ts) {
+  ensureDir2(path.dirname(dst));
+  requireBackup(dst, ts);
+  let doc = {};
+  try {
+    if (fs.existsSync(dst)) {
+      let raw = fs.readFileSync(dst, "utf8");
+      if (raw && raw.charCodeAt(0) === 65279) raw = raw.slice(1);
+      if (raw.trim() !== "") {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) doc = parsed;
+      }
+    }
+  } catch {
+    doc = {};
+  }
+  if (!doc.servers || typeof doc.servers !== "object") doc.servers = {};
+  if (doc.mcpServers && typeof doc.mcpServers === "object") {
+    delete doc.mcpServers["ijfw-memory"];
+    if (Object.keys(doc.mcpServers).length === 0) delete doc.mcpServers;
+  }
+  doc.servers["ijfw-memory"] = { type: "stdio", command: "node", args: [serverJs] };
+  writeAtomic(dst, JSON.stringify(doc, null, 2) + "\n", { mode: 384 });
+}
 function installCopilot(ctx) {
   if (ctx.ijfwCustomDir) {
     printInfo("Custom-dir install -- skipping Copilot project writes.");
@@ -1251,7 +1403,7 @@ function installCopilot(ctx) {
   }
   const dst = path.join(cwd, ".vscode", "mcp.json");
   ensureDir2(path.dirname(dst));
-  mergeJson(dst, ctx.serverJsNative || ctx.serverJs);
+  vscodeMcpMerge(dst, ctx.serverJsNative || ctx.serverJs, ctx.ts);
   const rulesDst = path.join(cwd, ".github", "copilot-instructions.md");
   const rulesSrc = path.join(ctx.repoRoot, "copilot", "copilot-instructions.md");
   const wroteRules = copyIfMissing(rulesSrc, rulesDst);
@@ -1270,7 +1422,7 @@ function installOpencode(ctx) {
   }
   const dst = path.join(ctx.home, ".config", "opencode", "opencode.json");
   ensureDir2(path.dirname(dst));
-  opencodeMerge(dst, ctx.serverJsNative || ctx.serverJs);
+  opencodeMerge(dst, ctx.serverJsNative || ctx.serverJs, ctx.ts);
   printOk(`Merged MCP into ${dst} (opencode mcp.local schema)`);
   return { status: "ok" };
 }
@@ -1282,7 +1434,7 @@ function installQwen(ctx) {
   }
   const dst = path.join(ctx.home, ".qwen", "settings.json");
   ensureDir2(path.dirname(dst));
-  mergeJson(dst, ctx.serverJsNative || ctx.serverJs);
+  mergeJson(dst, ctx.serverJsNative || ctx.serverJs, ctx.ts);
   printOk(`Merged MCP into ${dst}`);
   return { status: "ok" };
 }
@@ -1292,7 +1444,7 @@ function installCline(ctx) {
     printOk("Cline: real platform config left untouched.");
     return { status: "noop" };
   }
-  const dst = clineMerge(ctx.serverJsNative || ctx.serverJs, ctx.home);
+  const dst = clineMerge(ctx.serverJsNative || ctx.serverJs, ctx.home, ctx.ts);
   printOk(`Merged MCP into ${dst} (cline globalStorage schema)`);
   return { status: "ok" };
 }
@@ -1304,7 +1456,7 @@ function installKimi(ctx) {
   }
   const dst = path.join(ctx.home, ".kimi", "mcp.json");
   ensureDir2(path.dirname(dst));
-  mergeJson(dst, ctx.serverJsNative || ctx.serverJs);
+  mergeJson(dst, ctx.serverJsNative || ctx.serverJs, ctx.ts);
   printOk(`Merged MCP into ${dst}`);
   return { status: "ok" };
 }
@@ -1331,7 +1483,7 @@ function installOpenclaw(ctx) {
     }
   }
   ensureDir2(path.dirname(dst));
-  openclawMerge(dst, serverJs);
+  openclawMerge(dst, serverJs, ctx.ts);
   if (cliRegistered) {
     printOk(`Registered ijfw-memory via 'openclaw mcp set' AND file-write merge (${dst})`);
   } else {
@@ -1363,10 +1515,10 @@ function installAntigravity(ctx) {
   const serverJs = ctx.serverJsNative || ctx.serverJs;
   const ideDst = path.join(ctx.home, ".gemini", "antigravity", "mcp_config.json");
   ensureDir2(path.dirname(ideDst));
-  mergeJson(ideDst, serverJs);
+  mergeJson(ideDst, serverJs, ctx.ts);
   const cliDst = path.join(ctx.home, ".gemini", "config", "mcp_config.json");
   ensureDir2(path.dirname(cliDst));
-  mergeJson(cliDst, serverJs);
+  mergeJson(cliDst, serverJs, ctx.ts);
   printOk(`Merged MCP into ${ideDst} + ${cliDst} (Antigravity IDE + CLI)`);
   return { status: "ok" };
 }
@@ -1388,6 +1540,152 @@ var init_install_targets_8_14 = __esm({
   }
 });
 
+// src/install-ledger.js
+var install_ledger_exports = {};
+__export(install_ledger_exports, {
+  INSTALL_PLAN: () => INSTALL_PLAN,
+  PLATFORM_OWNED_DIRS: () => PLATFORM_OWNED_DIRS,
+  allOwnedDirs: () => allOwnedDirs,
+  isEmptyDir: () => isEmptyDir,
+  ledgerPath: () => ledgerPath,
+  readLedger: () => readLedger,
+  renderPlan: () => renderPlan,
+  snapshotPreExistingDirs: () => snapshotPreExistingDirs,
+  writeLedger: () => writeLedger
+});
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4, readdirSync as readdirSync2 } from "node:fs";
+import { join as join5 } from "node:path";
+function ledgerPath(ijfwHome) {
+  return join5(ijfwHome, "install-ledger.json");
+}
+function allOwnedDirs() {
+  const set = /* @__PURE__ */ new Set();
+  for (const dirs of Object.values(PLATFORM_OWNED_DIRS)) {
+    for (const d of dirs) set.add(d);
+  }
+  return [...set];
+}
+function snapshotPreExistingDirs(home) {
+  const pre = [];
+  for (const rel of allOwnedDirs()) {
+    if (existsSync5(join5(home, rel))) pre.push(rel);
+  }
+  return pre;
+}
+function writeLedger({ home, ijfwHome, preExisting }) {
+  const preSet = new Set(preExisting || []);
+  const owned = allOwnedDirs();
+  const created = [];
+  for (const rel of owned) {
+    if (!preSet.has(rel) && existsSync5(join5(home, rel))) created.push(rel);
+  }
+  const prev = readLedger(ijfwHome).createdDirs.filter(
+    (rel) => owned.includes(rel) && existsSync5(join5(home, rel))
+  );
+  const ledger = { version: 1, createdDirs: [.../* @__PURE__ */ new Set([...prev, ...created])] };
+  try {
+    mkdirSync4(ijfwHome, { recursive: true, mode: 448 });
+    writeFileSync4(ledgerPath(ijfwHome), JSON.stringify(ledger, null, 2) + "\n", { mode: 384 });
+  } catch {
+  }
+  return ledger;
+}
+function readLedger(ijfwHome) {
+  try {
+    const raw = readFileSync4(ledgerPath(ijfwHome), "utf8");
+    const doc = JSON.parse(raw);
+    if (doc && Array.isArray(doc.createdDirs)) return doc;
+  } catch {
+  }
+  return { version: 1, createdDirs: [] };
+}
+function isEmptyDir(p) {
+  try {
+    return existsSync5(p) && readdirSync2(p).length === 0;
+  } catch {
+    return false;
+  }
+}
+function renderPlan(targetList) {
+  const lines = [];
+  lines.push("IJFW install plan (dry run) -- nothing will be written.");
+  lines.push("  legend: [m]=merge into existing file  [c]=create  [./]=project-scoped");
+  lines.push("");
+  const emit = (title, rows) => {
+    if (!rows || rows.length === 0) return;
+    lines.push(title);
+    for (const [path3, kind, note] of rows) lines.push(`    [${kind}] ${path3}  -- ${note}`);
+  };
+  emit("  shared:", INSTALL_PLAN.shared);
+  for (const t of targetList) {
+    if (INSTALL_PLAN[t]) emit(`  ${t}:`, INSTALL_PLAN[t]);
+  }
+  lines.push("");
+  lines.push("  Run without --dry-run to apply. Use `ijfw-uninstall --purge` to reverse.");
+  return lines.join("\n");
+}
+var PLATFORM_OWNED_DIRS, INSTALL_PLAN;
+var init_install_ledger = __esm({
+  "src/install-ledger.js"() {
+    PLATFORM_OWNED_DIRS = {
+      codex: [".codex"],
+      gemini: [".gemini"],
+      hermes: [".hermes"],
+      wayland: [".wayland"],
+      openclaw: [".openclaw"],
+      qwen: [".qwen"],
+      kimi: [".kimi"],
+      opencode: [".config/opencode"],
+      pi: [".pi"]
+    };
+    INSTALL_PLAN = {
+      shared: [
+        ["~/.ijfw/", "c", "IJFW home (server symlink, scripts, index, logs, settings, ledger)"]
+      ],
+      claude: [
+        ["~/.claude/settings.json", "m", "mcpServers.ijfw-memory + enabledPlugins + marketplace"],
+        ["~/.claude/plugins/known_marketplaces.json", "m", "ijfw marketplace entry"]
+      ],
+      codex: [
+        ["~/.codex/config.toml", "m", "[mcp_servers.ijfw-memory]"],
+        ["~/.codex/hooks.json", "m", "IJFW hook entries"],
+        ["~/.codex/hooks/*.sh", "c", "lifecycle hook scripts"],
+        ["~/.codex/IJFW.md", "c", "context file"],
+        ["~/.codex/skills/, commands/", "c", "skills + command aliases"]
+      ],
+      gemini: [
+        ["~/.gemini/settings.json", "m", "mcpServers.ijfw-memory"],
+        ["~/.gemini/extensions/ijfw/", "c", "extension (hooks, skills, commands, agents)"]
+      ],
+      hermes: [
+        ["~/.hermes/config.yaml", "m", "mcp_servers.ijfw-memory + plugin + hook"],
+        ["~/.hermes/HERMES.md, skills/, plugins/ijfw/", "c", "context + skills + plugin tree"]
+      ],
+      wayland: [
+        ["~/.wayland/plugins/ijfw/", "c", "plugin.toml (MCP + hooks)"],
+        ["~/.wayland/WAYLAND.md, skills/", "c", "context + skills"]
+      ],
+      openclaw: [["~/.openclaw/openclaw.json", "m", "mcp.servers.ijfw-memory"]],
+      qwen: [["~/.qwen/settings.json", "m", "mcpServers.ijfw-memory"]],
+      kimi: [["~/.kimi/mcp.json", "m", "mcpServers.ijfw-memory"]],
+      opencode: [["~/.config/opencode/opencode.json", "m", "mcp.ijfw-memory"]],
+      cline: [["VS Code globalStorage <Code|VSCodium>/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json", "m", "mcpServers.ijfw-memory"]],
+      antigravity: [
+        ["~/.gemini/antigravity/mcp_config.json", "m", "mcpServers.ijfw-memory (IDE)"],
+        ["~/.gemini/config/mcp_config.json", "m", "mcpServers.ijfw-memory (CLI agy)"]
+      ],
+      pi: [["~/.pi/agent/AGENTS.md", "c", "context file (rules-only, no MCP)"]],
+      cursor: [["./.cursor/mcp.json + rules/ijfw.mdc", "mc", "project-scoped MCP + rule"]],
+      windsurf: [
+        ["~/.codeium/windsurf/mcp_config.json", "m", "mcpServers.ijfw-memory"],
+        ["./.windsurfrules", "c", "project-scoped rules"]
+      ],
+      copilot: [["./.vscode/mcp.json + .github/copilot-instructions.md", "mc", "project-scoped"]],
+      aider: [["~/.aider.conf.yml + ~/CONVENTIONS.md", "c", "home-level rule files"]]
+    };
+  }
+});
+
 // src/install-flow.js
 var install_flow_exports = {};
 __export(install_flow_exports, {
@@ -1927,6 +2225,7 @@ async function runInstall({
     });
   }
   pruneBackups({ home });
+  const preExistingDirs = snapshotPreExistingDirs(home);
   const live = [];
   const standby = [];
   const failed = [];
@@ -1981,6 +2280,7 @@ async function runInstall({
       standby.push(display);
     }
   }
+  writeLedger({ home, ijfwHome: resolvedIjfwHome, preExisting: preExistingDirs });
   printSummary({
     live,
     standby,
@@ -1996,6 +2296,7 @@ var init_install_flow = __esm({
     init_install_helpers();
     init_install_targets_1_7();
     init_install_targets_8_14();
+    init_install_ledger();
     CANONICAL_ORDER = [
       "claude",
       "codex",
@@ -2038,8 +2339,8 @@ var init_install_flow = __esm({
 
 // src/install.js
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync5, rmSync as rmSync2, mkdirSync as mkdirSync4, realpathSync as realpathSync2, renameSync as renameSync3, readdirSync as readdirSync2, cpSync as cpSync2 } from "node:fs";
-import { resolve as resolve4, join as join5, dirname as dirname5 } from "node:path";
+import { existsSync as existsSync6, rmSync as rmSync2, mkdirSync as mkdirSync5, realpathSync as realpathSync2, renameSync as renameSync3, readdirSync as readdirSync3, cpSync as cpSync2 } from "node:fs";
+import { resolve as resolve4, join as join6, dirname as dirname5, basename as basename2 } from "node:path";
 import { homedir as homedir3, platform as platform2 } from "node:os";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -2201,16 +2502,17 @@ function triggerColdScan(projectRoot, options = {}) {
 var DEFAULT_REPO = "https://github.com/FerroxLabs/ijfw.git";
 var DEFAULT_BRANCH = "main";
 function parseArgs(argv) {
-  const out = { yes: false, dir: null, noMarketplace: false, branch: DEFAULT_BRANCH, branchExplicit: false, purge: false };
+  const out = { yes: false, dir: null, noMarketplace: false, branch: DEFAULT_BRANCH, branchExplicit: false, purge: false, dryRun: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--yes" || a === "-y") out.yes = true;
-    else if (a === "--dir") out.dir = argv[++i];
+    else if (a === "--dir") out.dir = requireFlagValue("--dir", "a path", argv[++i]);
     else if (a === "--no-marketplace") out.noMarketplace = true;
     else if (a === "--branch") {
-      out.branch = argv[++i];
+      out.branch = requireFlagValue("--branch", "a name", argv[++i]);
       out.branchExplicit = true;
     } else if (a === "--purge") out.purge = true;
+    else if (a === "--dry-run" || a === "--print-plan") out.dryRun = true;
     else if (a === "--help" || a === "-h") {
       printHelp();
       process.exit(0);
@@ -2218,6 +2520,13 @@ function parseArgs(argv) {
   }
   return out;
 }
+function requireFlagValue(flag, what, value) {
+  if (value == null || value.startsWith("-")) {
+    console.error(`${flag} requires ${what} argument`);
+    process.exit(1);
+  }
+  return value;
+}
 function skipNetwork() {
   return process.env.IJFW_SKIP_NETWORK === "1";
 }
@@ -2257,10 +2566,11 @@ function resolveBranchOrTag({ branch, branchExplicit, _tagLookup, _logger } = {}
 }
 function printHelp() {
   console.log(`ijfw-install -- IJFW installer
-Usage: npx @ijfw/install [--dir <path>] [--branch <name>] [--no-marketplace] [--yes]
+Usage: npx @ijfw/install [--dir <path>] [--branch <name>] [--no-marketplace] [--yes] [--dry-run]
   --dir             install location (default: $IJFW_HOME or ~/.ijfw)
   --branch          git branch or tag (default: latest released tag)
   --no-marketplace  skip merging ~/.claude/settings.json
+  --dry-run         print every file/dir the install would touch, write nothing
   --yes             non-interactive
 `);
 }
@@ -2291,15 +2601,15 @@ function findBash() {
   const whereGit = spawnSync2("where", ["git"], { encoding: "utf8" });
   if (whereGit.status === 0) {
     const gitPath = (whereGit.stdout || "").split(/\r?\n/)[0].trim();
-    if (gitPath && existsSync5(gitPath)) {
+    if (gitPath && existsSync6(gitPath)) {
       const gitDir = dirname5(gitPath);
       const gitRoot = dirname5(gitDir);
       const candidates = [
-        join5(gitDir, "bash.exe"),
-        join5(gitRoot, "bin", "bash.exe"),
-        join5(gitRoot, "usr", "bin", "bash.exe")
+        join6(gitDir, "bash.exe"),
+        join6(gitRoot, "bin", "bash.exe"),
+        join6(gitRoot, "usr", "bin", "bash.exe")
       ];
-      for (const c of candidates) if (existsSync5(c)) return c;
+      for (const c of candidates) if (existsSync6(c)) return c;
     }
   }
   for (const c of [
@@ -2307,35 +2617,45 @@ function findBash() {
     "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
     "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
     "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe"
-  ]) if (existsSync5(c)) return c;
+  ]) if (existsSync6(c)) return c;
   if (hasBin2("bash")) return "bash";
   return null;
 }
 function resolveTarget(opt) {
   if (opt.dir) return resolve4(opt.dir);
   if (process.env.IJFW_HOME) return resolve4(process.env.IJFW_HOME);
-  return join5(homedir3(), ".ijfw");
+  return join6(homedir3(), ".ijfw");
 }
 function runCheck(cmd, args, opts) {
   const r = spawnSync2(cmd, args, { encoding: "utf8", ...opts });
   return { status: r.status, stdout: r.stdout || "", stderr: r.stderr || "", spawnError: r.error?.code, signal: r.signal };
 }
+function looksLikeIjfwInstall(dir) {
+  try {
+    if (basename2(resolve4(dir)) === ".ijfw") return true;
+    if (existsSync6(join6(dir, "install-ledger.json"))) return true;
+    if (existsSync6(join6(dir, "install-method"))) return true;
+    if (existsSync6(join6(dir, "mcp-server", "src", "server.js")) && existsSync6(join6(dir, "claude"))) return true;
+  } catch {
+  }
+  return false;
+}
 function cloneOrPull(dir, branch) {
   if (skipNetwork()) {
-    if (existsSync5(dir)) {
+    if (existsSync6(dir)) {
       return "skipped-network";
     }
     throw new Error(
       `IJFW_SKIP_NETWORK=1 set but cloneOrPull needs network: target directory ${dir} does not exist. Pre-seed the directory before setting IJFW_SKIP_NETWORK, or unset the env var.`
     );
   }
-  if (!existsSync5(dir)) {
-    mkdirSync4(dir, { recursive: true });
+  if (!existsSync6(dir)) {
+    mkdirSync5(dir, { recursive: true });
     const r = spawnSync2("git", ["clone", "--depth", "1", "--branch", branch, DEFAULT_REPO, dir], { stdio: "inherit" });
     if (r.status !== 0) throw new Error(`IJFW repo fetch did not complete (exit ${r.status}) -- check network access and retry.`);
     return "cloned";
   }
-  const hasGit = existsSync5(join5(dir, ".git"));
+  const hasGit = existsSync6(join6(dir, ".git"));
   if (hasGit) {
     const { status: remoteStatus, stdout, stderr: remoteStderr, spawnError: remoteSpawnError, signal: remoteSignal } = runCheck("git", ["-C", dir, "remote", "get-url", "origin"]);
     if (remoteSpawnError) console.warn(`  git spawn error (${remoteSpawnError}) -- check git is on PATH`);
@@ -2359,6 +2679,13 @@ function cloneOrPull(dir, branch) {
           console.log(`  origin migration: ${currentOrigin} -> ${DEFAULT_REPO}`);
         }
       }
+      const CANONICAL_PATTERN = /^https:\/\/github\.com\/ferroxlabs\/ijfw(\.git)?\/?$/i;
+      const isIjfwOrigin = CANONICAL_PATTERN.test(currentOrigin) || STALE_PATTERNS.some((re) => re.test(currentOrigin));
+      if (!isIjfwOrigin && !looksLikeIjfwInstall(dir)) {
+        throw new Error(
+          `Refusing to update ${dir}: it is a git checkout of "${currentOrigin}", not an IJFW install. Check your --dir / IJFW_HOME setting, or remove the directory and retry.`
+        );
+      }
       const fetch = spawnSync2("git", ["-C", dir, "fetch", "--depth", "1", "origin", branch], { stdio: "inherit" });
       if (fetch.status !== 0) throw new Error(`IJFW fetch did not complete (exit ${fetch.status}) -- check network access and retry.`);
       const co = spawnSync2("git", ["-C", dir, "checkout", "-f", "FETCH_HEAD"], { stdio: "inherit" });
@@ -2385,32 +2712,53 @@ function cloneOrPull(dir, branch) {
     ".ijfw"
     // internal — recall counter, indexes, layout version
   ];
+  if (!looksLikeIjfwInstall(dir)) {
+    let entries = null;
+    try {
+      entries = readdirSync3(dir);
+    } catch {
+    }
+    if (entries && entries.length === 0) {
+      const r = spawnSync2("git", ["clone", "--depth", "1", "--branch", branch, DEFAULT_REPO, dir], { stdio: "inherit" });
+      if (r.status !== 0) throw new Error(`IJFW repo fetch did not complete (exit ${r.status}) -- check network access and retry.`);
+      return "cloned";
+    }
+    throw new Error(
+      `Refusing to replace ${dir}: it exists but does not look like an IJFW install (no install ledger, install-method file, or IJFW checkout markers). Check your --dir / IJFW_HOME setting, or move the directory aside and retry.`
+    );
+  }
   const backupDir = dir + ".bak." + Date.now();
   renameSync3(dir, backupDir);
   try {
     const r = spawnSync2("git", ["clone", "--depth", "1", "--branch", branch, DEFAULT_REPO, dir], { stdio: "inherit" });
     if (r.status !== 0) throw new Error(`IJFW repo fetch did not complete (exit ${r.status}) -- check network access and retry.`);
-    let restoredCount = 0;
+    const restoredItems = [];
     for (const item of RESTORE_ALLOWLIST) {
-      const src = join5(backupDir, item);
-      if (existsSync5(src)) {
-        const dst = join5(dir, item);
-        if (existsSync5(dst)) rmSync2(dst, { recursive: true, force: true });
+      const src = join6(backupDir, item);
+      if (existsSync6(src)) {
+        const dst = join6(dir, item);
         try {
+          if (existsSync6(dst)) rmSync2(dst, { recursive: true, force: true });
           cpSync2(src, dst, { recursive: true, dereference: false });
-          rmSync2(src, { recursive: true, force: true });
-          restoredCount++;
+          restoredItems.push(item);
         } catch (cpErr) {
           const msg = cpErr && cpErr.message ? cpErr.message : String(cpErr);
           throw new Error(
-            `IJFW restore: cpSync failed for "${item}" (${msg}). Your data is still intact under: ${backupDir}. Move it back into ${dir} manually after diagnosing the copy failure.`
+            `IJFW restore: copy failed for "${item}" (${msg}). Your data is still intact under: ${backupDir}. The previous state of ${dir} will be restored from it.`
           );
         }
       }
     }
+    const restoredCount = restoredItems.length;
+    for (const item of restoredItems) {
+      try {
+        rmSync2(join6(backupDir, item), { recursive: true, force: true });
+      } catch {
+      }
+    }
     let backupResidual = [];
     try {
-      backupResidual = readdirSync2(backupDir);
+      backupResidual = readdirSync3(backupDir);
     } catch {
     }
     if (backupResidual.length === 0) {
@@ -2422,13 +2770,20 @@ function cloneOrPull(dir, branch) {
     }
     return "updated";
   } catch (err) {
-    if (existsSync5(dir)) rmSync2(dir, { recursive: true, force: true });
-    renameSync3(backupDir, dir);
+    try {
+      if (existsSync6(dir)) rmSync2(dir, { recursive: true, force: true });
+      renameSync3(backupDir, dir);
+    } catch (rollbackErr) {
+      const msg = rollbackErr && rollbackErr.message ? rollbackErr.message : String(rollbackErr);
+      console.error(
+        `  [!] rollback failed (${msg}). Your original data is preserved at: ${backupDir}. Move it back to ${dir} manually.`
+      );
+    }
     throw err;
   }
 }
 async function runInstallScript(dir) {
-  const canonicalDir = join5(homedir3(), ".ijfw");
+  const canonicalDir = join6(homedir3(), ".ijfw");
   const isCustomDir = resolve4(dir) !== canonicalDir;
   const { runInstall: runInstall2 } = await Promise.resolve().then(() => (init_install_flow(), install_flow_exports));
   await runInstall2({
@@ -2449,9 +2804,25 @@ async function main() {
     process.exit(1);
   }
   const target = resolveTarget(opts);
-  const createdThisRun = !existsSync5(target);
+  if (opts.dryRun) {
+    const { CANONICAL_ORDER: CANONICAL_ORDER2 } = await Promise.resolve().then(() => (init_install_flow(), install_flow_exports));
+    const { renderPlan: renderPlan2 } = await Promise.resolve().then(() => (init_install_ledger(), install_ledger_exports));
+    console.log(`IJFW install target: ${target}`);
+    console.log("");
+    console.log(renderPlan2(CANONICAL_ORDER2));
+    process.exit(0);
+  }
+  const createdThisRun = !existsSync6(target);
+  let platformConfigPhase = false;
   const sigint = () => {
-    if (createdThisRun && existsSync5(target)) {
+    if (platformConfigPhase) {
+      console.warn(
+        `
+  [!] install interrupted while platform configs were being written. Some platform configs may already reference ${target} -- the partial install was kept so they keep working. Rerun \`npx -p @ijfw/install ijfw-install\` to complete it, or \`ijfw-uninstall\` to remove IJFW from all platform configs.`
+      );
+      process.exit(130);
+    }
+    if (createdThisRun && existsSync6(target)) {
       try {
         rmSync2(target, { recursive: true, force: true });
       } catch (err) {
@@ -2470,9 +2841,10 @@ async function main() {
   console.log(`  version: ${ref}`);
   const action = cloneOrPull(target, ref);
   console.log(`  repo ${action}`);
+  platformConfigPhase = true;
   await runInstallScript(target);
   console.log("  platform configs applied");
-  const canonicalDir = join5(homedir3(), ".ijfw");
+  const canonicalDir = join6(homedir3(), ".ijfw");
   const isCustomDir = process.env.IJFW_CUSTOM_DIR === "1" || resolve4(target) !== canonicalDir;
   if (!opts.noMarketplace && !isCustomDir) {
     const settingsPath = claudeSettingsPath();
@@ -2510,5 +2882,6 @@ if (isDirectRun()) {
 }
 export {
   findBash,
+  looksLikeIjfwInstall,
   resolveBranchOrTag
 };