kodelyth-ecc 2.24.8 → 2.24.10

package/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.10 — the same config-destroying read, now on settings.json (October 2026)
+
+**Data-loss fix.** 2.24.9 fixed a nullable JSON read coalesced to `{}` in
+`register-self.js`, which destroyed `~/.claude.json`. Grepping the codebase for
+that pattern found it a second time, in `register-hooks.js`, on a file that
+matters more.
+
+```js
+const settings = readJsonOrNull(settingsPath) || {};
+// …
+const body = JSON.stringify({ ...settings, hooks: merged }, null, 2);
+```
+
+Same shape, same consequence: a `settings.json` that merely failed to parse was
+indistinguishable from one that did not exist, so the merge wrote it back
+carrying only the hooks block. Measured on a realistic file: **477 bytes in, 106
+bytes out** — losing `permissions.allow` and `.deny`, `env`, `model`,
+`statusLine`, and the user's *own* hook entries. Losing permissions silently
+re-prompts them for every tool; losing hooks silently stops their quality gates.
+
+Worth recording how it survived review: the **write** here was already hardened to
+preserve the file's mode, with a comment explaining that an installer has no
+business changing a user config's permissions. Someone thought carefully about the
+write and not at all about the read.
+
+### What changed
+
+`readSettings` now returns `absent` / `present` / `unreadable`, and an unreadable
+config returns status `unreadable-settings` with the parse reason, writing
+nothing. The existing `readJsonOrNull` is kept for ECC's own shipped `hooks.json`,
+where null on failure is correct — that is a file we ship, not one a user can
+hand-edit into a broken state.
+
+### A documented behaviour was deliberately reversed
+
+A test existed for this case: *"a corrupt settings.json does not lose the hooks"*,
+asserting status `ok` with ECC's three hook events written. The intent — don't
+lose ECC's hooks over a broken config — sounds right until it is priced. The only
+way to write into a file that will not parse is to discard everything else in it.
+
+ECC's hooks not installing is recoverable: fix the JSON, re-run. The user's
+permissions and env are not. The test is rewritten rather than deleted, asserting
+the opposite contract with the trade-off stated in the test body.
+
+**693 tests across 44 files.**
+
+### Also: brand art pointed at the wrong site
+
+Four ECC cards printed `kodelyth.com` — the parent company site — rather than
+`ecc.kodelyth.com`, where ECC actually lives. `og-image`, `github-social-preview`
+and `fb-post-launch` all advertise ECC, so anyone reading the card and typing the
+URL landed somewhere else. `section-author` keeps the parent domain, since that
+one is about the company rather than the product.
+
+## 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/       → 693 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 | ✓ 693 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.10",
   "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/install/register-hooks.js

@@ -36,6 +36,10 @@ const path = require('path');
 const { mergeHookEntries } = require('../lib/install/apply.js');
 const { replaceFilePreservingMode } = require('../lib/safe-fs.js');
 
+// ECC's OWN shipped hooks.json. Null on failure is right here: it is a file we
+// ship, a caller cannot have hand-edited it into existence, and the
+// 'invalid-hooks-config' status below is the correct response to it being wrong.
+// The user's settings.json is a different matter — see readSettings.
 function readJsonOrNull(file) {
   try {
     const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -45,6 +49,40 @@ function readJsonOrNull(file) {
   }
 }
 
+// Reading settings.json has THREE outcomes, and collapsing them destroys data.
+//
+// This used to be readJsonOrNull() returning null for every failure, with the
+// caller writing `|| {}`. A settings.json that merely failed to parse — one
+// trailing comma from a hand-edit — was therefore indistinguishable from one that
+// did not exist, and the merge wrote it back carrying only the hooks block.
+// Measured on a realistic file: 477 bytes in, 106 bytes out, losing
+// permissions.allow and .deny, env, model, statusLine, and the user's OWN hook
+// entries. Losing permissions silently re-prompts them for every tool; losing
+// hooks silently stops their quality gates.
+//
+// This is the same defect fixed in scripts/mcp/register-self.js for ~/.claude.json.
+// Note the write below was already hardened to preserve file mode — the write was
+// careful and the read was not, which is how it survived review.
+function readSettings(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 };
+  }
+  if (raw.trim() === '') return { state: 'absent', data: {} };
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { state: 'unreadable', reason: 'top-level value is not an object' };
+    }
+    return { state: 'present', data: parsed };
+  } catch (err) {
+    return { state: 'unreadable', reason: err.message };
+  }
+}
+
 /**
  * @param {string} targetRoot      e.g. ~/.claude
  * @param {string} [hooksJsonPath] defaults to <targetRoot>/hooks/hooks.json
@@ -67,7 +105,21 @@ function registerHooks(targetRoot, hooksJsonPath) {
   }
 
   const settingsPath = path.join(targetRoot, 'settings.json');
-  const settings = readJsonOrNull(settingsPath) || {};
+  const read = readSettings(settingsPath);
+  if (read.state === 'unreadable') {
+    // Refuse rather than merge. There is no safe way to write a file whose current
+    // contents cannot be reconstructed, and "best effort" here means discarding
+    // whatever did not parse.
+    return {
+      status: 'unreadable-settings',
+      reason: read.reason,
+      events: 0,
+      added: 0,
+      total: 0,
+      settingsPath,
+    };
+  }
+  const settings = read.data;
   const existing = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
     ? settings.hooks
     : {};

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 },
 };