kodelyth-ecc 2.24.8 → 2.24.9

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.9 — a malformed Claude config was silently replaced on install (October 2026)
+
+**Data-loss fix. Upgrade before running an install on a machine whose
+`~/.claude.json` may have been hand-edited.**
+
+MCP self-registration read the user's Claude config, merged ECC's server entry in,
+and wrote it back:
+
+```js
+const existing = readJson(file) || {};
+const next = { ...existing, mcpServers: servers };
+writeJson(file, next);
+```
+
+`readJson` returned `null` for **every** failure. So a config that merely failed to
+parse — one trailing comma from a hand-edit, a half-written file, a bad mount —
+was indistinguishable from a config that did not exist, and `|| {}` turned it into
+an empty object. The merge then wrote that back.
+
+Measured on a realistic config with two other MCP servers, a `projects` block with
+history, and user settings: **366 bytes in, 140 bytes out**. Every other MCP
+server, every project entry, the theme and `autoUpdates` — gone. No error, no
+warning, no backup.
+
+This runs automatically during install. So `npx kodelyth-ecc` on a machine whose
+`.claude.json` had any syntax error destroyed the user's Claude configuration.
+
+### What changed
+
+`readConfig` now returns one of three states instead of a nullable value:
+
+| state | meaning | action |
+|---|---|---|
+| `absent` | missing, empty, or whitespace-only | safe to treat as `{}` and create |
+| `present` | parsed to an object | merge normally |
+| `unreadable` | exists but will not parse, or is not an object | **refuse** |
+
+Refusing is the point: there is no safe way to merge into a file whose contents
+cannot be reconstructed. The file is left byte-identical and the error names it
+along with the parse failure. `unregisterInFile` applies the same rule on the way
+out — removing an entry from a file we cannot read means writing a file we cannot
+reconstruct.
+
+Writes now go through `safeFs.replaceFilePreservingMode`: atomic via
+temp-and-rename, so a crash or a full disk partway through cannot truncate the
+config — the same data loss by a different route — and the file keeps its existing
+permissions rather than having them widened.
+
+### Two mistakes caught while fixing it
+
+The first version of the fix called `replaceFileAtomic` without its `mode`
+argument, which threw on **every** path including valid configs. Testing the happy
+path, not just the bug, is what surfaced it; verifying only that the refusal
+worked would have shipped an installer that never registered anything.
+
+The mode-preservation test then asserted `mode === 0o600` and failed Windows CI
+with `438 !== 384`. Windows has no POSIX permission bits, so `chmod` there is close
+to a no-op and node reports `0666` regardless. The property worth testing was never
+the literal value but that the write does not *change* the mode, which is true on
+every platform.
+
+Eight tests, where this file previously had none: the three read states,
+preservation of unrelated config on a valid merge, byte-identical refusal across
+four kinds of malformed input, creation from absent and empty, idempotence,
+unregister's refusal, mode preservation, and no stray temp files.
+
+**690 tests across 44 files.**
+
 ## v2.24.8 — adversarial pass: swarm, dashboard, supply-chain (October 2026)
 
 Three defects found by attacking the remaining unprobed surfaces rather than

package/CLAUDE.md

@@ -26,7 +26,7 @@ scripts/     → Node.js utilities: MCP server, dashboard, swarm, replay, router
 bundles/     → 3 power bundles (indie-hacker, red-team, enterprise)
 actions/     → GitHub Action (CI/CD integration for PR review)
 docs/        → Feature docs (arena.md, mcp.md, dashboard.md, swarm.md, replay.md, evolve.md, supply-chain.md)
-tests/       → 682 passing tests across 43 test files
+tests/       → 690 passing tests across 44 test files
 ```
 
 ## Running Tests

package/README.md

@@ -118,7 +118,7 @@ Most "AI agent kits" are folders of markdown files you have to remember the name
 | Quality hooks | ✓ 44 | Some | ✗ | ✗ |
 | IDE platforms | **11** (Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI) | 1-2 | 1 | Varies |
 | Telemetry | **None** | Varies | None | Varies |
-| Test coverage | ✓ 682 tests | ✗ | ✗ | ✗ |
+| Test coverage | ✓ 690 tests | ✗ | ✗ | ✗ |
 | Distributed via | `npx`, curl, clone | Manual | Manual | Manual |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.24.8",
+  "version": "2.24.9",
   "description": "Production-grade AI coding toolkit — 70 agents (incl. devil-mode adversarial crew), 196 skills, 103 commands, parallel multi-agent commands, semantic intent routing, self-learning memory, and a built-in MCP server (16 tools / 6 prompts / 377 resources) that bridges to Claude Desktop, LangGraph, AutoGen, CrewAI, and OpenAI Agents SDK. Works on macOS, Linux and Windows with Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, RooCode, Aider, Kimi, and Gemini CLI.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",

package/scripts/mcp/register-self.js

@@ -7,6 +7,7 @@
 'use strict';
 
 const fs   = require('fs');
+const safeFs = require('../lib/safe-fs');
 const os   = require('os');
 const path = require('path');
 
@@ -24,13 +25,48 @@ function claudeDesktopConfigPath() {
   return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
 }
 
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+// Reading this file has THREE outcomes, and collapsing them is destructive.
+//
+// readJson used to return null for every failure, and the caller did
+// `readJson(file) || {}`. So a config that merely failed to parse — one trailing
+// comma from a hand-edit, a half-written file, a bad mount — was treated as an
+// empty config, and the merge wrote it back containing only ECC's own entry.
+// Measured on a realistic config: 366 bytes in, 140 bytes out, with every other
+// MCP server, every project entry and every setting gone. Silently, during an
+// install the user did not think was risky.
+//
+// Absent is safe to treat as empty. Unreadable is not.
+function readConfig(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { state: 'absent', data: {} };
+    return { state: 'unreadable', reason: err.message };
+  }
+  // An empty or whitespace-only file is effectively absent; JSON.parse would
+  // throw on it and we would otherwise refuse to ever register.
+  if (raw.trim() === '') return { state: 'absent', data: {} };
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      return { state: 'unreadable', reason: 'top-level value is not an object' };
+    }
+    return { state: 'present', data };
+  } catch (err) {
+    return { state: 'unreadable', reason: err.message };
+  }
 }
 
 function writeJson(file, obj) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, JSON.stringify(obj, null, 2));
+  // Atomic: write a temp file and rename. A crash or a full disk partway through
+  // a plain writeFileSync leaves the user with a truncated config, which is the
+  // same data loss by a different route.
+  // PreservingMode rather than Atomic: this is the user's own config file and it
+  // may carry permissions they chose. It keeps the existing mode when the file is
+  // already there and falls back to 0644 when creating it.
+  safeFs.replaceFilePreservingMode(file, JSON.stringify(obj, null, 2) + '\n');
 }
 
 function serverEntry() {
@@ -42,7 +78,15 @@ function serverEntry() {
 }
 
 function registerInFile(file, opts = {}) {
-  const existing = readJson(file) || {};
+  const cfg = readConfig(file);
+  if (cfg.state === 'unreadable') {
+    // Refusing is the whole point. Overwriting would destroy whatever is in there.
+    throw new Error(
+      `refusing to modify ${file}: it exists but could not be parsed (${cfg.reason}). ` +
+      `Fix or move the file, then re-run. Nothing was written.`
+    );
+  }
+  const existing = cfg.data;
   const servers = existing.mcpServers || {};
   const already = servers[SERVER_NAME];
   const desired = serverEntry();
@@ -56,7 +100,10 @@ function registerInFile(file, opts = {}) {
 }
 
 function unregisterInFile(file) {
-  const existing = readJson(file);
+  const cfg = readConfig(file);
+  // Same rule on the way out: an unparseable config is left exactly as it is.
+  if (cfg.state === 'unreadable') return { file, action: 'skipped-unreadable', reason: cfg.reason };
+  const existing = cfg.data;
   if (!existing || !existing.mcpServers || !existing.mcpServers[SERVER_NAME]) {
     return { file, action: 'not-present' };
   }
@@ -113,4 +160,7 @@ module.exports = {
   registerAll,
   unregisterAll,
   statusAll,
+  // Exported for tests: these must be exercisable without writing to a real
+  // ~/.claude.json, and the whole point of the fix is what they refuse to do.
+  _internals: { readConfig, registerInFile, unregisterInFile },
 };