forgedock 1.5.0 → 1.6.0

package/bin/forgedock.mjs

@@ -59,8 +59,8 @@ import {
   detectClaudeVersion,
   loadBreakpoints,
   hasFeature,
-  getPersistedHomeState,
   setPersistedHomeState,
+  getInstalledCommandsDriftStatus,
 } from "./registry.mjs";
 import { renderMark, ember } from "./cinema.mjs";
 import {
@@ -1513,6 +1513,51 @@ function resolveGlobalNpmForgedockDir() {
   }
 }
 
+/**
+ * Compare two already-`resolve()`d absolute paths for equality or containment
+ * (child equals parent, or sits strictly under it). On case-insensitive
+ * filesystems (win32/darwin) the same physical directory can resolve with
+ * differing letter casing (drive letter, path segments), so both operands are
+ * lowercased before comparing there; on Linux the comparison stays
+ * case-sensitive byte-for-byte (forge#2668). On the case-insensitive branch
+ * both operands are also Unicode-normalized to NFC: macOS APFS/HFS+ enumerate
+ * filenames NFD-normalized while CLI args/env vars typically arrive NFC, and
+ * `resolve()` preserves the input form — so without normalization two paths
+ * for the same physical directory containing accented characters can compare
+ * unequal (forge#2674). NFC is idempotent for pure-ASCII and pre-composed
+ * paths, so ASCII behavior is unchanged; win32 normalizes harmlessly. The
+ * `+ sep` boundary keeps `/foo-bar` from matching parent `/foo`. Callers pass
+ * paths that are already resolved — this helper deliberately does not
+ * re-resolve.
+ *
+ * Known limitation: `caseInsensitive` is gated on `process.platform`, an
+ * OS-level constant, not on the actual case-sensitivity of the volume
+ * FORGE_HOME/the npm global root live on. This is the correct assumption for
+ * the default filesystem format on each OS (NTFS on win32, APFS/HFS+ on
+ * darwin), but a volume explicitly formatted case-sensitive (e.g. opt-in
+ * case-sensitive APFS) would still be case-folded here, and two distinct
+ * directories differing only by case could be treated as equal. This is an
+ * accepted approximation, not a probe of real volume semantics — both call
+ * sites (`isGlobalNpmInstall`, `findSeparateGlobalInstall`) already fail
+ * closed / stay advisory-only, so a false match here degrades to their
+ * pre-existing "detection inconclusive" behavior rather than causing any
+ * destructive or incorrect action (forge#2675). Probing the actual volume
+ * (e.g. an `existsSync` case-twist check) is deliberately not done — the
+ * added complexity and syscall aren't warranted for a purely advisory path.
+ *
+ * @param {string} child - resolved absolute path being tested
+ * @param {string} parent - resolved absolute path of the candidate ancestor
+ * @returns {boolean}
+ */
+function samePathOrUnder(child, parent) {
+  const caseInsensitive =
+    process.platform === "win32" || process.platform === "darwin";
+  const fold = (p) => (caseInsensitive ? p.normalize("NFC").toLowerCase() : p);
+  const a = fold(child);
+  const b = fold(parent);
+  return a === b || a.startsWith(b + sep);
+}
+
 /**
  * Detect whether FORGE_HOME resolves inside npm's global install tree, i.e.
  * this process is running as a globally-installed `forgedock` package (not
@@ -1533,7 +1578,7 @@ function isGlobalNpmInstall() {
   const globalPkgDir = resolveGlobalNpmForgedockDir();
   if (!globalPkgDir) return false;
   const home = resolve(FORGE_HOME);
-  return home === globalPkgDir || home.startsWith(globalPkgDir + sep);
+  return samePathOrUnder(home, globalPkgDir);
 }
 
 /**
@@ -1558,7 +1603,7 @@ function findSeparateGlobalInstall() {
   const globalPkgDir = resolveGlobalNpmForgedockDir();
   if (!globalPkgDir) return null;
   const home = resolve(FORGE_HOME);
-  if (home === globalPkgDir || home.startsWith(globalPkgDir + sep)) {
+  if (samePathOrUnder(home, globalPkgDir)) {
     // Current FORGE_HOME already IS the global install — nothing separate.
     return null;
   }
@@ -1804,9 +1849,10 @@ async function update() {
           // dirty tree. HEAD is still never moved in either case.
           const cwdResolved = resolve(process.cwd());
           const forgeHomeResolved = resolve(FORGE_HOME);
-          const isSourceRepoSelf =
-            cwdResolved === forgeHomeResolved ||
-            cwdResolved.startsWith(forgeHomeResolved + sep);
+          const isSourceRepoSelf = samePathOrUnder(
+            cwdResolved,
+            forgeHomeResolved,
+          );
 
           if (isSourceRepoSelf) {
             console.log(
@@ -2694,27 +2740,16 @@ async function doctor(fix = false) {
             `incomplete (missing: ${missingDirs.join(", ")}). Run: npx forgedock install`,
           );
         } else {
-          // Prefer the version registry.mjs last recorded for this exact
-          // write (getPersistedHomeState()) — the single source of truth
-          // update()/install also write through — falling back to reading
-          // ~/.forge/version directly on disk when the registry has no entry
-          // (e.g. an older ForgeDock version wrote ~/.forge/ before #1943
-          // added registry tracking). Reading both keeps doctor() honest
-          // even if the registry ever drifts from what's actually on disk.
-          const recorded = getPersistedHomeState();
-          let persistedVersion = recorded?.version || "";
-          if (!persistedVersion) {
-            try {
-              persistedVersion = readFileSync(versionPath, "utf-8").trim();
-            } catch {
-              // version file missing/unreadable — reported below as "unknown"
-            }
-          }
-          const sourceVersion = getVersion();
-          if (persistedVersion && sourceVersion && compareVersions(persistedVersion, sourceVersion) < 0) {
+          // Package-vs-installed-commands drift comparison is factored into
+          // a single shared helper (bin/registry.mjs's
+          // getInstalledCommandsDriftStatus, forge#2719) so doctor, the
+          // `version` command, and the SessionStart hook all agree on one
+          // source of truth instead of re-deriving this logic independently.
+          const { persistedVersion, isStale, unknown } = getInstalledCommandsDriftStatus(FORGE_HOME);
+          if (!unknown && isStale) {
             warn(
               "Persisted toolset home (~/.forge)",
-              `v${persistedVersion} — source is v${sourceVersion}. Run: npx forgedock update`,
+              `v${persistedVersion} — source is v${getVersion()}. Run: npx forgedock update`,
             );
           } else {
             pass("Persisted toolset home (~/.forge)", `v${persistedVersion || "unknown"} at ${persistedHome}`);
@@ -3913,6 +3948,18 @@ switch (command) {
           `Run ${CYAN}npx forgedock update${RESET} to fetch it.`,
       );
     }
+
+    // forge#2719 — surface package-vs-installed-commands drift (previously
+    // only visible via `doctor` Check 5d). Uses the same shared helper doctor
+    // calls, so both surfaces agree. Silent when versions match or when
+    // either version is unknown (e.g. a git-clone dev install, which never
+    // persists to ~/.forge — see registry.mjs's getInstalledCommandsDriftStatus).
+    const driftStatus = getInstalledCommandsDriftStatus(FORGE_HOME);
+    if (!driftStatus.unknown && driftStatus.isStale) {
+      console.log(
+        `  ${YELLOW}Installed commands are stale (v${driftStatus.persistedVersion}) vs package v${driftStatus.sourceVersion}${RESET} — run: ${CYAN}npx forgedock update${RESET}`,
+      );
+    }
     break;
   }
   case "help":

package/bin/hooks/session-start.mjs

@@ -51,6 +51,8 @@ const FORGE_HOME = resolve(__dirname, "..", "..");
 let resolveState;
 let nudgeSeen;
 let markNudgeSeen;
+// Assigned alongside the other registry.mjs helpers below — see forge#2719.
+let getInstalledCommandsDriftStatus;
 
 // ---------------------------------------------------------------------------
 // forge-utils helpers — populated inside the try block to honour fail-open
@@ -88,7 +90,7 @@ try {
   // that import() rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.
   /** @type {import('../registry.mjs')} */
   (
-    { resolveState, nudgeSeen, markNudgeSeen } = await import(
+    { resolveState, nudgeSeen, markNudgeSeen, getInstalledCommandsDriftStatus } = await import(
       pathToFileURL(join(FORGE_HOME, "bin", "registry.mjs")).href
     )
   );
@@ -126,6 +128,25 @@ try {
   const cwd = process.cwd();
   const state = resolveState(cwd);
 
+  // Surface package-vs-installed-commands drift as a single non-fatal
+  // advisory line (forge#2719). Uses the same shared helper doctor's
+  // Check 5d and the `version` command call, so all three surfaces agree.
+  // Best-effort: any failure here must never block the session, and
+  // managed-optedout directories stay completely silent per this hook's
+  // existing contract for that state (see the switch below).
+  if (state !== "managed-optedout") {
+    try {
+      const driftStatus = getInstalledCommandsDriftStatus(FORGE_HOME);
+      if (!driftStatus.unknown && driftStatus.isStale) {
+        console.log(
+          `ForgeDock: installed commands are stale (v${driftStatus.persistedVersion}) vs package v${driftStatus.sourceVersion} — run: npx forgedock update`,
+        );
+      }
+    } catch {
+      // Fail open — never let a drift-check error affect session start.
+    }
+  }
+
   switch (state) {
     case "managed-active":
       await handleManagedActive(cwd);