akili-specs 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -10,6 +10,10 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.5.1] - 2026-07-19
+
+### Added
+- **`akili update` now shows what changed:** After updating the npm package and reinstalling files, `akili update` prints a `What changed (<old> → <new>)` summary sourced from the installed package's `CHANGELOG.md`, listing every version section between the previously installed version and the new one. If the package was already up to date, it says so instead.
 ## [2.5.0] - 2026-07-19
 
 ### Added

package/bin/akili.js

@@ -78,7 +78,7 @@ Usage:
 
 Commands:
   install   Install commands, skills, and helper resources
-  update    Update npm package to latest version and reinstall files
+  update    Update npm package to latest version, reinstall files, and show what changed
   doctor    Check whether expected files are installed
   list      List packaged commands, skills, and helper resources
   help      Show this help
@@ -398,6 +398,107 @@ function detectInstallType() {
   return "npx";
 }
 
+// Resolve the installed akili-specs package directory (global or local) after an update.
+// Returns the absolute path to the package root, or null if it cannot be found.
+function resolveInstalledPackageDir(installType) {
+  try {
+    const root = execSync(
+      installType === "global" ? "npm root -g 2>/dev/null" : "npm root 2>/dev/null",
+      { encoding: "utf8" }
+    ).trim();
+    if (root) {
+      const dir = path.join(root, "akili-specs");
+      if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+    }
+  } catch (e) {}
+  return null;
+}
+
+// Read the version from an installed package's package.json.
+function readInstalledVersion(packageDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8")).version;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Parse CHANGELOG.md and return the raw text of every version section strictly
+// newer than `fromVersion` up to and including `toVersion`. Sections look like
+// `## [X.Y.Z] - date`. Returns an array of { version, body } newest-first.
+function changelogSectionsBetween(changelogPath, fromVersion, toVersion) {
+  let text;
+  try {
+    text = fs.readFileSync(changelogPath, "utf8");
+  } catch (e) {
+    return [];
+  }
+
+  const lines = text.split("\n");
+  const sections = [];
+  let current = null;
+
+  const isNewer = (a, b) =>
+    a.localeCompare(b, undefined, { numeric: true, sensitivity: "base" }) > 0;
+
+  for (const line of lines) {
+    const match = line.match(/^##\s+\[([^\]]+)\]/);
+    if (match) {
+      if (current) sections.push(current);
+      current = { version: match[1], bodyLines: [] };
+    } else if (current) {
+      current.bodyLines.push(line);
+    }
+  }
+  if (current) sections.push(current);
+
+  return sections
+    .filter((s) => /^\d+\.\d+\.\d+/.test(s.version)) // skip "Unreleased"
+    .filter((s) => {
+      const newerThanFrom = !fromVersion || isNewer(s.version, fromVersion);
+      const notNewerThanTo = !toVersion || !isNewer(s.version, toVersion);
+      return newerThanFrom && notNewerThanTo;
+    })
+    .map((s) => ({ version: s.version, body: s.bodyLines.join("\n").trim() }));
+}
+
+// Print a concise summary of what changed between two versions, sourced from the
+// installed package's CHANGELOG.md.
+function printUpdateChangeSummary(packageDir, fromVersion, toVersion) {
+  if (!packageDir || !fromVersion || !toVersion) return;
+
+  if (fromVersion === toVersion) {
+    console.log(
+      `\n${colors.cyan}Already on the latest version (${toVersion}). No changelog to show.${colors.reset}`
+    );
+    return;
+  }
+
+  const changelogPath = path.join(packageDir, "CHANGELOG.md");
+  const sections = changelogSectionsBetween(changelogPath, fromVersion, toVersion);
+
+  console.log(
+    `\n${colors.cyan}What changed (${fromVersion} → ${toVersion}):${colors.reset}`
+  );
+
+  if (sections.length === 0) {
+    console.log(`  (No changelog entries found for this range.)`);
+    return;
+  }
+
+  for (const section of sections) {
+    console.log(`\n${colors.green}v${section.version}${colors.reset}`);
+    const body = section.body || "  (No details recorded.)";
+    // Indent each line slightly for readability.
+    console.log(
+      body
+        .split("\n")
+        .map((l) => (l.length ? `  ${l}` : l))
+        .join("\n")
+    );
+  }
+}
+
 function runUpdate(args) {
   const installType = detectInstallType();
 
@@ -410,6 +511,9 @@ function runUpdate(args) {
     return;
   }
 
+  // Capture the version before updating so we can show what changed afterward.
+  const versionBefore = currentVersion;
+
   console.log(`\n${colors.yellow}Updating npm package...${colors.reset}`);
 
   try {
@@ -428,6 +532,13 @@ function runUpdate(args) {
   console.log(`\n${colors.yellow}Reinstalling files with --force...${colors.reset}`);
   args.force = true;
   runInstall(args);
+
+  // After reinstalling, read the freshly installed version and show the changelog
+  // between the old and new versions. The running process still has the old code
+  // loaded, so we read version + CHANGELOG from the installed package on disk.
+  const packageDir = resolveInstalledPackageDir(installType);
+  const versionAfter = packageDir ? readInstalledVersion(packageDir) : null;
+  printUpdateChangeSummary(packageDir, versionBefore, versionAfter);
 }
 
 function runInstall(args) {

package/docs/cli.md

@@ -51,7 +51,7 @@ akili install --tool both --local
 |---|---|
 | `akili init` | Interactive setup wizard for installation |
 | `akili install` | Install commands, skills, and helper resources |
-| `akili update` | Reinstall packaged commands, skills, and helper resources |
+| `akili update` | Update the npm package to the latest version, reinstall files, and print a changelog summary of what changed |
 | `akili list` | List packaged commands, skills, and helper resources |
 | `akili doctor` | Check whether expected files are installed |
 | `akili help` | Show help |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {