@skyf0xx/hedgehog 4.3.6 → 4.4.0

package/bin/cli.mjs

@@ -50,6 +50,7 @@ import { rebuildDb } from '../src/db/rebuild.mjs';
 import { loadOverrides, addOverride, orphanedOverrides, OVERRIDES_DIR } from '../src/db/overrides.mjs';
 import { HOSTS, HOST_FLAGS, DEFAULT_HOST, availableHosts } from '../src/hosts/index.mjs';
 import { recordHosts, installedHosts } from '../src/hosts/installed.mjs';
+import { recordVersion, checkForUpdate, installedVersion } from '../src/hosts/version.mjs';
 
 const AUTHORED_CORE_PATH = '.hedgehog/core.yaml';
 
@@ -65,6 +66,12 @@ const DEST_ROOT = process.cwd();
 const CORES_ROOT = join(PKG_ROOT, 'src/golden-cores');
 const DEFAULT_CORE = 'full-stack-app';
 
+// The version of the payload this CLI carries — what `init` and
+// `update` stamp into the project they write to.
+const PKG_VERSION = JSON.parse(
+  await readFile(join(PKG_ROOT, 'package.json'), 'utf8'),
+).version;
+
 // One install flag per core, named for what a user is asking to build
 // rather than the internal src/golden-cores/<name> directory — the two
 // diverge deliberately so the CLI's public surface can stay stable
@@ -384,6 +391,7 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --all-hosts          install for every supported coding agent
   npx @skyf0xx/hedgehog init --force              overwrite existing files
   npx @skyf0xx/hedgehog update                    refresh the installed agents + skills
+  npx @skyf0xx/hedgehog update --check            report whether a newer release is published
   npx @skyf0xx/hedgehog db init                   create .hedgehog/hedgehog.db if absent
   npx @skyf0xx/hedgehog db rebuild                re-derive the build graph from committed intents + git history
   npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies
@@ -449,6 +457,15 @@ those directories. The instructions file, the build graph, the core
 workspace, and vendor-skills/BMAD and vendor-skills/GSAP stay as they
 are — those are project-specific or updated deliberately, not by this
 command.
+
+Both ${bold('init')} and ${bold('update')} stamp the version they wrote into
+.hedgehog/version.json. ${bold('update --check')} compares that stamp against
+the newest published release and exits 1 when a newer one exists, without
+writing anything. The same comparison rides on ${bold('status')} and
+${bold('next')} as a one-line notice, from a once-a-day cached lookup, so a
+stale project surfaces itself; set HEDGEHOG_NO_UPDATE_CHECK=1 to silence it.
+Run ${bold('npx @skyf0xx/hedgehog@latest update')} to pull a newer release —
+the @latest tag matters, since a bare npx may reuse a cached older CLI.
 `);
 }
 
@@ -500,6 +517,7 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
   // Recorded before anything is written: the routing doc is generated
   // from this list, so it has to already name the host being installed.
   await recordHosts(DEST_ROOT, [host]);
+  await recordVersion(DEST_ROOT, PKG_VERSION);
 
   let written = 0;
   let overwritten = 0;
@@ -588,6 +606,42 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
   }
 }
 
+// `update --check` answers the question without acting on it: what's
+// installed, what's published, and whether they differ. Exit code 0 when
+// current or unknown, 1 when an update is available, so a script or a
+// host's own tooling can branch on it without parsing the output.
+async function updateCheck() {
+  const { installed, latest, stale } = await checkForUpdate(DEST_ROOT, {
+    force: true,
+  });
+
+  if (!installed) {
+    console.log(
+      `${yellow('Installed version unknown.')} ${dim(
+        'This project predates version stamping — run `hedgehog update` to refresh and stamp it.',
+      )}\n`,
+    );
+    return;
+  }
+  if (!latest) {
+    console.log(
+      `Installed: ${bold(installed)}\n${dim(
+        "Couldn't reach the npm registry — no update check performed.",
+      )}\n`,
+    );
+    return;
+  }
+  if (stale) {
+    console.log(
+      `${yellow(bold('Update available.'))} installed ${bold(installed)} → latest ${bold(latest)}\n\n` +
+        `  Run ${bold('npx @skyf0xx/hedgehog@latest update')} to refresh this project's agents and skills.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`${green('Up to date.')} ${dim(`installed ${installed}, latest ${latest}`)}\n`);
+}
+
 async function update({ hosts }) {
   const targets = hosts?.length ? hosts : await installedHosts(DEST_ROOT);
 
@@ -614,10 +668,19 @@ async function update({ hosts }) {
     }
   }
 
+  // Stamped after the writes land, so the recorded version always
+  // describes the payload actually on disk.
+  const previous = await installedVersion(DEST_ROOT);
+  await recordVersion(DEST_ROOT, PKG_VERSION);
+
   const label = targets.map((h) => HOSTS[h].label).join(', ');
+  const versionNote =
+    previous && previous !== PKG_VERSION
+      ? `${previous} → ${PKG_VERSION}`
+      : PKG_VERSION;
   console.log(
     `\n${green(bold('Hedgehog agents/skills updated.'))} ${dim(
-      `${written} files written for ${label}`,
+      `${versionNote} — ${written} files written for ${label}`,
     )}\n`,
   );
   console.log('Next steps:');
@@ -1104,6 +1167,34 @@ function warnSingularModuleIdsAtPlan(core, db) {
   );
 }
 
+// The passive half of update detection. Printed to stderr, after a
+// command's real output, on the commands every host's loop runs anyway —
+// so a stale project surfaces itself without anyone thinking to ask.
+//
+// This lives in the CLI rather than in any one host's hook because every
+// host drives the same binary: Claude Code, Cursor, and Gemini CLI all
+// reach it through `hedgehog next`, and one implementation here covers
+// all of them.
+//
+// Never throws and never blocks: the answer comes from a day-long cache,
+// a missing or unreachable registry reads as "no news", and the notice is
+// skipped entirely when output isn't a terminal so it can't corrupt
+// anything parsing stdout.
+async function noteAvailableUpdate() {
+  if (process.env.HEDGEHOG_NO_UPDATE_CHECK) return;
+  try {
+    const { installed, latest, stale } = await checkForUpdate(DEST_ROOT);
+    if (!stale) return;
+    console.error(
+      `\n${yellow(bold('Hedgehog update available.'))} ${dim(
+        `${installed} → ${latest}. Run \`npx @skyf0xx/hedgehog@latest update\` to refresh this project's agents and skills.`,
+      )}`,
+    );
+  } catch {
+    // Advisory only — a failed check is never worth failing a command over.
+  }
+}
+
 async function nextCommand() {
   await ensureDb();
 
@@ -1140,6 +1231,7 @@ async function nextCommand() {
       return;
     }
     console.log(`${dim('No ready task.')} Nothing is planned with all dependencies complete.\n`);
+    await noteAvailableUpdate();
     return;
   }
 
@@ -1156,6 +1248,7 @@ async function nextCommand() {
   }
 
   console.log(formatNext(packet, await resolveCoreId(), packetExists));
+  await noteAvailableUpdate();
 }
 
 function printStalledTasks(stalled) {
@@ -1825,6 +1918,8 @@ async function statusCommand() {
 
   const warningLines = await coreWarningLines();
   if (warningLines.length > 0) console.log(warningLines.join('\n'));
+
+  await noteAvailableUpdate();
 }
 
 // `hedgehog ready` — read-only preview of what a `hedgehog claim` call
@@ -2441,6 +2536,10 @@ async function main() {
   }
 
   if (cmd === 'update') {
+    if (args.includes('--check')) {
+      await updateCheck();
+      return;
+    }
     await update({ hosts });
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "4.3.6",
+  "version": "4.4.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/hosts/version.mjs

@@ -0,0 +1,154 @@
+// What version of the payload a project has, and whether a newer one exists.
+//
+// `init` and `update` stamp the version they wrote into
+// `.hedgehog/version.json`. Without that stamp a project's installed
+// agents and skills are indistinguishable from any other release's, so
+// staleness can only be discovered by reading the files themselves.
+//
+// The registry lookup is cached and best-effort: a project that can't
+// reach npm, or is offline entirely, gets no answer rather than an error.
+// Nothing here is on the path of any command that has real work to do.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+const VERSION_PATH = '.hedgehog/version.json';
+const REGISTRY_URL = 'https://registry.npmjs.org/@skyf0xx/hedgehog/latest';
+
+// How long a registry answer stays good. The payload ships daily, so a
+// once-a-day question matches how often the answer can actually change,
+// and keeps a session that runs many commands to a single network call.
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+// The check is advisory — it must never delay a command that has real
+// work to do, so a registry that hangs is treated the same as one that
+// says nothing.
+const FETCH_TIMEOUT_MS = 1500;
+
+/**
+ * Record the payload version now installed in `root`. Called by both
+ * `init` and `update`, so the stamp tracks the payload on disk rather
+ * than whichever release first landed.
+ */
+export async function recordVersion(root, version) {
+  const path = join(root, VERSION_PATH);
+  const prior = await readVersionFile(root);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(
+    path,
+    `${JSON.stringify({ ...prior, version, installedAt: new Date().toISOString() }, null, 2)}\n`,
+  );
+  return version;
+}
+
+async function readVersionFile(root) {
+  try {
+    return JSON.parse(await readFile(join(root, VERSION_PATH), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The payload version installed in `root`, or null for a project
+ * installed before the stamp existed.
+ */
+export async function installedVersion(root) {
+  const { version } = await readVersionFile(root);
+  return typeof version === 'string' ? version : null;
+}
+
+/**
+ * Compare two semver strings. Returns true when `a` is strictly newer
+ * than `b`. Prerelease tags sort before their release, matching semver;
+ * anything unparseable compares as equal so a malformed version can
+ * never fabricate an update prompt.
+ */
+export function isNewer(a, b) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v ?? '').trim());
+    return m
+      ? { nums: [+m[1], +m[2], +m[3]], pre: m[4] ?? null }
+      : null;
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i];
+  }
+  // Equal release numbers: a release outranks its own prereleases.
+  if (pa.pre === pb.pre) return false;
+  if (pa.pre === null) return true;
+  if (pb.pre === null) return false;
+  return pa.pre > pb.pre;
+}
+
+/**
+ * The newest published version, from cache when it's fresh and from the
+ * registry otherwise. Returns null on any failure — offline, timeout,
+ * rate limit, malformed response. A null answer means "don't know", and
+ * every caller treats that as "say nothing".
+ */
+export async function latestVersion(root, { force = false } = {}) {
+  const cached = await readVersionFile(root);
+  if (!force && cached.checkedAt && cached.latest) {
+    const age = Date.now() - Date.parse(cached.checkedAt);
+    if (age >= 0 && age < CACHE_TTL_MS) return cached.latest;
+  }
+
+  const latest = await fetchLatest();
+  if (!latest) return null;
+
+  // Cache alongside the install stamp rather than in a separate file, so
+  // one read answers both halves of the question.
+  const path = join(root, VERSION_PATH);
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(
+      path,
+      `${JSON.stringify({ ...cached, latest, checkedAt: new Date().toISOString() }, null, 2)}\n`,
+    );
+  } catch {
+    // A read-only or missing .hedgehog just means no caching; the
+    // answer we fetched is still good for this call.
+  }
+  return latest;
+}
+
+async function fetchLatest() {
+  try {
+    // No `accept` header. The abbreviated-metadata type
+    // (application/vnd.npm.install-v1+json) is only valid on the
+    // packument root — sending it to /latest returns 406, which this
+    // function would swallow as "no answer" and the check would
+    // silently never fire. Plain /latest returns just the one version
+    // object, which is also far smaller than the full packument.
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const { version } = await res.json();
+    return typeof version === 'string' ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The full staleness picture for a project: what's installed, what's
+ * published, and whether the gap is worth telling anyone about.
+ *
+ * `stale` is true only when both versions are known and the published
+ * one is newer — an unknown on either side reads as "no", so a project
+ * installed before stamping and an offline machine both stay quiet.
+ */
+export async function checkForUpdate(root, { force = false } = {}) {
+  const installed = await installedVersion(root);
+  const latest = await latestVersion(root, { force });
+  return {
+    installed,
+    latest,
+    stale: Boolean(installed && latest && isNewer(latest, installed)),
+  };
+}