kodelyth-ecc 2.23.2 → 2.24.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.0 — the update notice now tells you why (October 2026)
+
+The CLI has always polled npm for new versions and cached the answer for 24
+hours. That monthly touchpoint was spent on almost nothing: the result surfaced
+only in the interactive menu, as a version number and an install command.
+
+```
+Update to v2.23.2
+npm i -g kodelyth-ecc  (installs new version)
+```
+
+A version number is a nag. It states a fact and gives no reason to act on it.
+
+### It now links what changed
+
+```
+Update to v2.24.0
+what changed: github.com/sifxprime/kodelyth-ecc/releases/tag/v2.24.0
+```
+
+`check()` returns a `releaseNotes` URL alongside the version, so every consumer
+gets it without doing its own string building.
+
+### doctor surfaces it too
+
+A second natural touchpoint — `doctor` is run deliberately, usually when
+somebody is already paying attention:
+
+```
+! version — v2.23.2 installed, v2.24.0 available
+    → npm i -g kodelyth-ecc    what changed: .../releases/tag/v2.24.0
+```
+
+### Cache-only, on purpose
+
+The new `cachedCheck()` reads the 24-hour cache and never touches the network.
+`doctor` is the command people reach for when something is **already** wrong, so
+it must not wait on the registry — and an unreachable npm is not a fact about
+the health of your install. A cold or stale cache yields nothing and the row is
+simply absent, rather than reported as a warning. A check that fires on "I could
+not reach the network" teaches people to ignore the output.
+
+`run()` stays synchronous and takes the result as a parameter, so it remains
+testable and `doctor` adds no latency.
+
+Verified across every state: a newer version warns with the link, being current
+passes, a stale cache is ignored, a corrupt cache leaves `doctor` working on its
+11 checks, and a cold cache omits the row.
+
+### What this does not do
+
+No nagging on every command. Nothing auto-updates. Nothing blocks.
+
+**647 tests passing.**
+
 ## v2.23.2 — the README leads with the product, not the badges (October 2026)
 
 No change to the toolkit. The README **is** the npm landing page, and npm only

package/VERSION

@@ -1 +1 @@
-2.23.2
+2.24.0

package/bin/kodelyth-ecc.js

@@ -707,7 +707,23 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
 
 if (args[0] === 'doctor') {
   const { run, PASS, WARN, FAIL } = require(path.join(ROOT, 'scripts', 'doctor-health.js'));
-  const report = run();
+
+  // Cache-only, deliberately. doctor is what people run when something is
+  // already wrong, so it must not wait on the registry — and an unreachable npm
+  // is not a fact about the health of their install. The cache is warmed by the
+  // interactive menu; a cold one yields null and the version row is simply
+  // absent.
+  let update;
+  try {
+    const { cachedCheck } = require(path.join(ROOT, 'scripts', 'cli', 'update-check.js'));
+    const vf = path.join(ROOT, 'VERSION');
+    const current = fs.existsSync(vf)
+      ? fs.readFileSync(vf, 'utf8').trim()
+      : require(path.join(ROOT, 'package.json')).version;
+    update = cachedCheck(current) || undefined;
+  } catch { /* never let a version hint break the health check */ }
+
+  const report = run({ update });
   if (args.includes('--json')) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
     process.exit(report.summary.fail > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.23.2",
+  "version": "2.24.0",
   "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/cli/menu.js

@@ -47,7 +47,9 @@ async function buildOptions({ ROOT }) {
   if (update.updateAvailable) {
     opts.push({
       label: `Update to v${update.latest}`,
-      hint:  'npm i -g kodelyth-ecc  (installs new version)',
+      // Say what it is AND where to read what changed. A version number alone
+      // is a nag; a reason is an invitation.
+      hint:  `what changed: ${update.releaseNotes || 'github.com/sifxprime/kodelyth-ecc/releases'}`,
       run:   () => runUpdate(),
       badge: 'NEW',
     });

package/scripts/cli/update-check.js

@@ -54,7 +54,19 @@ function cmpVersion(a, b) {
   return 0;
 }
 
-// Public: returns { current, latest, updateAvailable, cached } or nulls on failure.
+/**
+ * Where to read what actually changed in a given version.
+ *
+ * "update available: v2.23.2" is a nag — it tells you a number and no reason.
+ * A link to the release notes turns the same notice into something worth acting
+ * on, which is the whole point of owning a monthly touchpoint.
+ */
+function releaseNotesUrl(version) {
+  if (!version) return null;
+  return `https://github.com/sifxprime/kodelyth-ecc/releases/tag/v${version}`;
+}
+
+// Public: returns { current, latest, updateAvailable, cached, releaseNotes } or nulls on failure.
 async function check({ current, force = false } = {}) {
   if (!force) {
     const c = readCache();
@@ -63,6 +75,7 @@ async function check({ current, force = false } = {}) {
         current, latest: c.latest,
         updateAvailable: c.latest && cmpVersion(c.latest, current) > 0,
         cached: true,
+        releaseNotes: releaseNotesUrl(c.latest),
       };
     }
   }
@@ -72,7 +85,30 @@ async function check({ current, force = false } = {}) {
     current, latest,
     updateAvailable: !!(latest && cmpVersion(latest, current) > 0),
     cached: false,
+    releaseNotes: releaseNotesUrl(latest),
+  };
+}
+
+/**
+ * Cache-only read. No network, no promise, no timeout — safe to call from a
+ * synchronous command.
+ *
+ * doctor uses this rather than check(): it is the command people run when
+ * something is already wrong, so it must never wait on the registry. The cache
+ * is warmed by the interactive menu, which does hit the network. A cold cache
+ * simply yields null and the version row does not appear, which is correct —
+ * "I could not reach npm" is not a fact about the health of your install.
+ */
+function cachedCheck(current) {
+  const c = readCache();
+  if (!c || !c.latest) return null;
+  return {
+    current,
+    latest: c.latest,
+    updateAvailable: cmpVersion(c.latest, current) > 0,
+    cached: true,
+    releaseNotes: releaseNotesUrl(c.latest),
   };
 }
 
-module.exports = { check, cmpVersion };
+module.exports = { check, cachedCheck, cmpVersion, releaseNotesUrl };

package/scripts/doctor-health.js

@@ -155,7 +155,29 @@ function checkCodebaseGraph() {
 
 // ── Runner ───────────────────────────────────────────────────────────────────
 
-function run() {
+/**
+ * Whether the installed version is current.
+ *
+ * Takes a pre-fetched result rather than doing its own network call, so run()
+ * stays synchronous and testable, and doctor never blocks on the registry. When
+ * nothing was fetched — offline, timed out, caller did not bother — this is
+ * silently absent rather than a warning. "Could not reach npm" is not a health
+ * problem with the user's install, and reporting it as one trains people to
+ * ignore the output.
+ */
+function checkVersion(update) {
+  if (!update || !update.latest) return null;
+  if (!update.updateAvailable) {
+    return { status: PASS, detail: `v${update.current} is the latest` };
+  }
+  return {
+    status: WARN,
+    detail: `v${update.current} installed, v${update.latest} available`,
+    fix: `npm i -g kodelyth-ecc    what changed: ${update.releaseNotes || 'github.com/sifxprime/kodelyth-ecc/releases'}`,
+  };
+}
+
+function run({ update } = {}) {
   const checks = [
     check('binaries',            checkBinaries),
     check('install-target',      checkInstallTarget),
@@ -169,6 +191,11 @@ function run() {
     check('terse',               checkTerse),
     check('codebase-graph',      checkCodebaseGraph),
   ];
+
+  // Appended rather than inlined: it is the only check that depends on the
+  // network, and it drops out entirely when no result was supplied.
+  const version = checkVersion(update);
+  if (version) checks.push({ id: 'version', ...version });
   const summary = {
     total: checks.length,
     pass: checks.filter(c => c.status === PASS).length,
@@ -178,4 +205,4 @@ function run() {
   return { checks, summary };
 }
 
-module.exports = { run, PASS, WARN, FAIL };
+module.exports = { run, checkVersion, PASS, WARN, FAIL };