kodelyth-ecc 2.24.9 → 2.24.11

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.11 — every docs page gets its own diagram (October 2026)
+
+Documentation and site only. No code change.
+
+The website renders a doc's `og_image` on the page now, not just in the social
+card, so the image a doc points at is something readers actually see above the
+content. Most docs pointed at shared generic cards — one card was doing duty for
+four unrelated pages — which is worse on-page than no image at all.
+
+Seventeen of the eighteen docs now carry a purpose-built 1200x630 diagram that
+teaches their own subject: the Arena's GOD-vs-EVIL loop, swarm's fan-out into
+isolated worktrees, the real RTK token ledger, the eight hook events sized by how
+many entries each carries, evolve's propose-then-you-review gate, the MCP tool
+surface, and so on. Each gains `hero_alt` describing the diagram's data, so it is
+legible to a screen reader and in the social card. The index hub keeps the main
+product card, which is the right image for a landing page.
+
+The diagrams live as static SVG in the website repo; this release carries the
+`og_image` / `hero_alt` frontmatter for the docs that ship from here.
+
+**693 tests across 44 files.**
+
+## 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

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/       → 690 passing tests across 44 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 | ✓ 690 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.9",
+  "version": "2.24.11",
   "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
     : {};