sticky-note-cli 2.9.1 → 3.0.0

package/templates/hooks/session-start.js

@@ -33,13 +33,82 @@ function _safeExit() {
   process.exit(0);
 }
 
+// Issue #12: warn (non-blocking) when the running CLI is below the project's
+// configured min_version. Returns "" when nothing to say. Also writes a
+// stderr banner so the user sees it directly even if the hook output is
+// swallowed by the host tool.
+function _parseSemver(v) {
+  if (typeof v !== "string") return null;
+  const m = v.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3] || 0)];
+}
+function _cmpSemver(a, b) {
+  const pa = _parseSemver(a), pb = _parseSemver(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+function _installedCliVersion() {
+  // Try the package.json shipped alongside this hook script's CLI.
+  try {
+    const candidates = [
+      path.join(__dirname, "..", "..", "package.json"),
+      path.join(__dirname, "..", "..", "..", "sticky-note-cli", "package.json"),
+    ];
+    for (const p of candidates) {
+      try {
+        const pkg = JSON.parse(require("fs").readFileSync(p, "utf-8"));
+        if (pkg && pkg.name === "sticky-note-cli" && pkg.version) return pkg.version;
+      } catch (_) { /* try next */ }
+    }
+  } catch (_) { /* ignore */ }
+  return null;
+}
+function formatVersionWarning(config) {
+  try {
+    const min = config && config.min_version;
+    if (!min) return "";
+    const installed = _installedCliVersion();
+    if (!installed) return "";
+    if (_cmpSemver(installed, min) >= 0) return "";
+    const msg =
+      `[STICKY-NOTE] ⚠️ Installed sticky-note-cli v${installed} is below ` +
+      `this project's min_version v${min}. Run \`npm i -D sticky-note-cli@latest\` ` +
+      `to update — features and schema may differ until you do.`;
+    try { process.stderr.write(msg + "\n"); } catch (_) { /* non-fatal */ }
+    return msg;
+  } catch (_) {
+    return "";
+  }
+}
+
 let utils;
 try {
   utils = require("./sticky-utils.js");
-} catch (_) {
+} catch (err) {
+  try {
+    process.stderr.write(
+      `[STICKY-NOTE] session-start hook error: failed to load sticky-utils.js — ${err.message}\n` +
+      `[STICKY-NOTE]   hint: re-run \`npx sticky-note init\` to restore .claude/hooks/.\n`
+    );
+  } catch (_) { /* ignore */ }
   _safeExit();
 }
 
+// Issue #13: self-heal stale absolute hook paths in .claude/settings.json
+// before doing anything else, so the next session loads cleanly even if some
+// other hook (e.g. on-stop, inject-context) was pointing at a path that no
+// longer exists. Failures here are non-fatal — we still want the rest of
+// session-start to run.
+try { utils.selfHealHookPaths && utils.selfHealHookPaths(); } catch (_) { /* non-fatal */ }
+
+// Non-fatal: data-branch sync is disabled if the module is missing.
+let dataBranch = null;
+try { dataBranch = require("./data-branch.js"); } catch (_) {}
+
 const {
   getMemoryPath,
   getConfigPath,
@@ -121,6 +190,59 @@ function autoCloseCopilotCliThreads(memory, autoCloseHours) {
 
 // ── Formatting helpers ────────────────────────────────────
 
+function formatStuckBanner(threads) {
+  const stuck = (threads || []).filter((t) => t && t.status === "stuck");
+  if (stuck.length === 0) return "";
+
+  const R = "\x1b[0m";
+  const Y = "\x1b[33m";
+  const BY = "\x1b[1;33m";
+  const BR = "\x1b[1;31m";
+  const B = "\x1b[1m";
+  const C = "\x1b[36m";
+  const D = "\x1b[2m";
+  const bar = "━".repeat(52);
+
+  const lines = [
+    "",
+    `${Y}${bar}${R}`,
+    `${BY}  ⚠️  STUCK THREADS${R}`,
+    `${Y}${bar}${R}`,
+  ];
+
+  for (const t of stuck.slice(0, 5)) {
+    const user = t.user || t.author || "unknown";
+    const branch = t.branch ? ` ${D}·${R} ${C}${t.branch}${R}` : "";
+    const files = (t.files_touched || []).slice(0, 3).join(", ");
+    const narrative = t.narrative || t.last_note || "";
+    const snip =
+      narrative.length > 80 ? narrative.substring(0, 80) + "…" : narrative;
+    const threadId = (t.id || "").substring(0, 8);
+    const failed = t.failed_approaches || [];
+
+    lines.push(
+      `${Y}  ┃${R}  ${BR}[STUCK]${R} ${B}${user}${R}${branch}`
+    );
+    if (files) lines.push(`${Y}  ┃${R}    Files: ${files}`);
+    if (snip) lines.push(`${Y}  ┃${R}    ${D}"${snip}"${R}`);
+    if (failed.length > 0) {
+      lines.push(
+        `${Y}  ┃${R}    ${BR}⚠️ ${failed.length} failed approach(es)${R}`
+      );
+    }
+    lines.push(
+      `${Y}  ┃${R}    → Resume: ${C}npx sticky-note resume ${threadId}${R}`
+    );
+  }
+
+  if (stuck.length > 5) {
+    lines.push(`${Y}  ┃${R}  ... and ${stuck.length - 5} more`);
+  }
+
+  lines.push(`${Y}${bar}${R}`, "");
+  return lines.join("\n") + "\n";
+}
+
 function formatThreadsForInjection(threads, maxThreads, maxTokens) {
   maxThreads = maxThreads || 10;
   maxTokens = maxTokens || 500;
@@ -251,7 +373,7 @@ function formatPresence(presenceData, threads) {
     try {
       const ts = new Date(lastSeen).getTime();
       if (isNaN(ts)) continue;
-      if (now - ts < 15 * 60 * 1000) {
+      if (now - ts < 60 * 60 * 1000) {
         const files = (info.active_files || []).slice(0, 3).join(", ");
         const thread = userThreads[user];
         let line = `- **${user}**`;
@@ -761,6 +883,47 @@ function ensureEnvironmentProvisioned() {
   if (debug) process.stderr.write("[sticky-note] environment provisioning complete\n");
 }
 
+// ── Data branch fetch-and-merge ───────────────────────────
+
+/**
+ * Fetches the remote sticky-note/data branch and merges into local memory.
+ * Also reads from the LOCAL data branch (fresh clones, offline, tests).
+ * Non-blocking — the session continues with local data on any failure.
+ */
+function fetchAndMergeDataBranch() {
+  if (!dataBranch) return;
+
+  const memPath = getMemoryPath();
+  const mergeFrom = (ref) => {
+    const content = dataBranch.readFileFromBranch(ref, "sticky-note.json");
+    if (content) {
+      dataBranch.mergeAndSaveFromRemote(memPath, content, loadJson, saveJson);
+    }
+  };
+
+  try {
+    const remote = dataBranch.getDefaultRemote();
+
+    if (remote) {
+      const fetchResult = dataBranch.fetchDataBranch(remote);
+      if (!fetchResult.ok) {
+        process.stderr.write(
+          "[STICKY-NOTE] offline — using local thread cache (" +
+            (fetchResult.error || "fetch failed") + ")\n"
+        );
+      } else if (fetchResult.remoteRef) {
+        mergeFrom(fetchResult.remoteRef);
+      }
+    }
+
+    mergeFrom(dataBranch.DATA_REF);
+  } catch (err) {
+    process.stderr.write(
+      "[STICKY-NOTE] offline — using local thread cache (" + err.message + ")\n"
+    );
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────
 
 function main() {
@@ -774,6 +937,9 @@ function main() {
     hookInput = {};
   }
 
+  // Fetch remote data branch and merge into local cache — before reading memory
+  fetchAndMergeDataBranch();
+
   let sessionId = getSessionId(hookInput);
   const aiTool = detectTool(hookInput);
   const isCopilotCli = aiTool === "copilot-cli" || process.argv.includes("--copilot-cli") || !!process.env.COPILOT_CLI;
@@ -911,6 +1077,7 @@ function main() {
   const overlapContext = formatOverlapWarnings(
     (memory.threads || []).filter(Boolean), getUser(), memory
   );
+  const versionWarning = formatVersionWarning(config);
 
   // V2.5: Mark eagerly-injected stuck threads so PreToolUse won't re-inject.
   // Skip for Copilot CLI — its sessionStart output is not surfaced to the AI,
@@ -930,6 +1097,41 @@ function main() {
 
   saveMemoryMerged(memoryPath, memory);
 
+  // ── Stuck threads startup banner ────────────────────────
+  // Write a visible banner to stderr so the user sees stuck threads
+  // immediately when the session starts, before any AI interaction.
+  const stuckThreads = (memory.threads || [])
+    .filter((t) => t && t.status === "stuck");
+  if (stuckThreads.length > 0) {
+    const fs = require("fs");
+    const bannerShownPath = path.join(
+      path.dirname(memoryPath),
+      ".sticky-banner-shown"
+    );
+    let showBanner = true;
+
+    // Copilot CLI fires sessionStart per-turn — only show once per session.
+    if (isCopilotCli) {
+      try {
+        const shown = fs.readFileSync(bannerShownPath, "utf-8").trim();
+        if (shown === sessionId) showBanner = false;
+      } catch (_) {
+        /* file doesn't exist yet */
+      }
+    }
+
+    if (showBanner) {
+      process.stderr.write(formatStuckBanner(stuckThreads));
+      if (isCopilotCli) {
+        try {
+          fs.writeFileSync(bannerShownPath, sessionId, "utf-8");
+        } catch (_) {
+          /* non-fatal */
+        }
+      }
+    }
+  }
+
   // ── Assemble output ───────────────────────────────────
   const parts = [];
 
@@ -1013,6 +1215,7 @@ function main() {
   }
 
   // Overlap warning comes first — most urgent signal
+  if (versionWarning) parts.push(versionWarning);
   if (overlapContext) parts.push(overlapContext);
 
   if (threadContext) parts.push(threadContext);
@@ -1028,6 +1231,8 @@ function main() {
 try {
   main();
 } catch (err) {
-  try { utils.logHookError("session-start", err); } catch (_) {}
+  try { utils.reportHookError("session-start", err); } catch (_) {
+    try { utils.logHookError("session-start", err); } catch (_) {}
+  }
   _safeExit();
 }

package/templates/hooks/sticky-utils.js

@@ -38,8 +38,16 @@ const FILE_PATH_PATTERN = /[\w./\\-]+\.\w{1,10}/g;
 // ── Path helpers ──────────────────────────────────────────
 
 function _stickyDir() {
-  const scriptDir = path.dirname(path.resolve(__filename));
-  return path.join(scriptDir, "..", "..", ".sticky-note");
+  try {
+    const gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return path.resolve(gitDir, "sticky-note");
+  } catch (_) {
+    // Fallback for non-git environments (e.g., unit tests without git init)
+    const scriptDir = path.dirname(path.resolve(__filename));
+    return path.join(scriptDir, "..", "..", ".sticky-note");
+  }
 }
 
 // ── Error logging ─────────────────────────────────────────
@@ -57,6 +65,101 @@ function logHookError(hookName, error) {
   }
 }
 
+// Issue #14: Surface hook failures to stderr so the host tool's generic
+// "<HookName> hook error" message has actionable detail next to it. Earlier
+// versions silently swallowed `require()` failures and top-level exceptions,
+// which made stale-path issues (#13) and other crashes impossible to diagnose
+// — particularly under UserPromptSubmit, which Claude Code reports without
+// a stack trace. This helper prefixes every line with `[STICKY-NOTE]` so the
+// user can spot it in mixed hook output.
+function reportHookError(hookName, error, hint) {
+  const msg = error instanceof Error ? (error.stack || error.message) : String(error);
+  const lines = [`[STICKY-NOTE] ${hookName} hook error: ${msg}`];
+  if (hint) lines.push(`[STICKY-NOTE]   hint: ${hint}`);
+  try { process.stderr.write(lines.join("\n") + "\n"); } catch (_) { /* ignore */ }
+  try { logHookError(hookName, error); } catch (_) { /* ignore */ }
+}
+
+// Issue #13: When a teammate copies `.claude/settings.json` from another
+// machine (or runs an older sticky-note-cli that wrote absolute paths), the
+// hook commands point at non-existent absolute paths and every hook fails
+// with MODULE_NOT_FOUND. Re-running `npx sticky-note init` fixes it, but
+// users typically don't know that — they just see "<Hook> hook error" each
+// session. This helper detects and rewrites those stale commands in-place
+// the first time any hook (e.g. session-start, inject-context) successfully
+// loads, so the next session starts clean.
+//
+// The rewritten command uses `npx sticky-note run-hook <basename>` which walks
+// up the directory tree to find `.claude/hooks/<basename>.js`, so it works even
+// when Claude Code is launched from a subdirectory of the project root.
+// We extract `<basename>` from the existing command so we never invent hook
+// scripts that don't exist.
+//
+// Returns the list of (hookEvent, oldCommand, newCommand) tuples that were
+// rewritten, or [] if nothing was stale.
+function selfHealHookPaths(settingsPath) {
+  const result = [];
+  try {
+    if (!settingsPath) {
+      settingsPath = path.join(process.cwd(), ".claude", "settings.json");
+    }
+    if (!fs.existsSync(settingsPath)) return result;
+
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    let settings;
+    try { settings = JSON.parse(raw); } catch (_) { return result; }
+    if (!settings || !settings.hooks) return result;
+
+    // Two stale patterns:
+    // 1. Absolute paths (written by older sticky-note-cli or copied from another machine)
+    // 2. Old relative form `node ".claude/hooks/foo.js"` — fails when Claude Code
+    //    launches from a subdirectory, because the path resolves relative to the
+    //    launch cwd, not the directory containing .claude/settings.json.
+    const STALE_ABSOLUTE = /["'][A-Za-z]:[\\/]|["']\/(?:Users|home|root|tmp)\/|\$\(git rev-parse/;
+    const STALE_RELATIVE = /^node\s+["']\.claude[\\/]hooks[\\/][^"']+\.js["']\s*$/;
+    // Match the script basename in either quoted or bare form.
+    const BASENAME = /([A-Za-z0-9_.-]+)\.(?:js|sh|cjs|mjs)(?:["'`\s]|$)/;
+
+    let changed = false;
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        for (const h of (entry && entry.hooks) || []) {
+          const cmd = h && h.command;
+          if (typeof cmd !== "string") continue;
+          const isStale = STALE_ABSOLUTE.test(cmd) || STALE_RELATIVE.test(cmd);
+          if (!isStale) continue;
+          const m = cmd.match(BASENAME);
+          if (!m) continue;
+          const basename = m[1];
+          const newCmd = `npx sticky-note run-hook ${basename}`;
+          result.push({ event, oldCommand: cmd, newCommand: newCmd });
+          h.command = newCmd;
+          changed = true;
+        }
+      }
+    }
+
+    if (!changed) return result;
+
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    try {
+      const summary =
+        `[STICKY-NOTE] ⚠️  Detected ${result.length} stale hook path(s) in ` +
+        `${path.relative(process.cwd(), settingsPath) || settingsPath} — rewrote to ` +
+        `"npx sticky-note run-hook <name>" so hooks work from any subdirectory. ` +
+        `Commit the change to share the fix with your team.`;
+      process.stderr.write(summary + "\n");
+      for (const { event, oldCommand, newCommand } of result.slice(0, 5)) {
+        process.stderr.write(`[STICKY-NOTE]   ${event}: ${oldCommand} → ${newCommand}\n`);
+      }
+    } catch (_) { /* non-fatal */ }
+  } catch (err) {
+    try { logHookError("selfHealHookPaths", err); } catch (_) { /* ignore */ }
+  }
+  return result;
+}
+
 const _paths = {
   memory: "sticky-note.json",
   config: "sticky-note-config.json",
@@ -947,6 +1050,8 @@ module.exports = {
   RETRY_PATTERNS,
   FILE_PATH_PATTERN,
   logHookError,
+  reportHookError,
+  selfHealHookPaths,
   getMemoryPath,
   getConfigPath,
   getAuditPath,
@@ -1018,5 +1123,10 @@ module.exports = {
   rotateBackup,
   acquireLock,
   releaseLock,
+  // Cloud sync stubs (feature not yet implemented — on-stop.js uses these)
+  useCloud: () => false,
+  cloudReadThreads: async () => null,
+  cloudWriteThread: async () => {},
+  cloudAppendAudit: async () => {},
 };
 // tier1 test

package/templates/hooks.json

@@ -4,43 +4,43 @@
     "sessionStart": [
       {
         "type": "command",
-        "bash": "COPILOT_CLI=1 node \"$(git rev-parse --show-toplevel)/.claude/hooks/session-start.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \"$(git rev-parse --show-toplevel)/.claude/hooks/session-start.js\" --copilot-cli"
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/session-start.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/session-start.js\" --copilot-cli"
       }
     ],
     "sessionEnd": [
       {
         "type": "command",
-        "bash": "COPILOT_CLI=1 node \"$(git rev-parse --show-toplevel)/.claude/hooks/session-end.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \"$(git rev-parse --show-toplevel)/.claude/hooks/session-end.js\" --copilot-cli"
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/session-end.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/session-end.js\" --copilot-cli"
       }
     ],
     "userPromptSubmitted": [
       {
         "type": "command",
-        "bash": "COPILOT_CLI=1 node \"$(git rev-parse --show-toplevel)/.claude/hooks/inject-context.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \"$(git rev-parse --show-toplevel)/.claude/hooks/inject-context.js\" --copilot-cli"
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/inject-context.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/inject-context.js\" --copilot-cli"
       }
     ],
     "preToolUse": [
       {
         "type": "command",
-        "bash": "COPILOT_CLI=1 node \"$(git rev-parse --show-toplevel)/.claude/hooks/pre-tool-use.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \"$(git rev-parse --show-toplevel)/.claude/hooks/pre-tool-use.js\" --copilot-cli"
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/pre-tool-use.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/pre-tool-use.js\" --copilot-cli"
       }
     ],
     "postToolUse": [
       {
         "type": "command",
-        "bash": "COPILOT_CLI=1 node \"$(git rev-parse --show-toplevel)/.claude/hooks/track-work.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \"$(git rev-parse --show-toplevel)/.claude/hooks/track-work.js\" --copilot-cli"
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/track-work.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/track-work.js\" --copilot-cli"
       }
     ],
     "errorOccurred": [
       {
         "type": "command",
-        "bash": "COPILOT_CLI=1 node \"$(git rev-parse --show-toplevel)/.claude/hooks/on-error.js\" --copilot-cli",
-        "powershell": "$env:COPILOT_CLI='1'; node \"$(git rev-parse --show-toplevel)/.claude/hooks/on-error.js\" --copilot-cli"
+        "bash": "COPILOT_CLI=1 node \".claude/hooks/on-error.js\" --copilot-cli",
+        "powershell": "$env:COPILOT_CLI='1'; node \".claude/hooks/on-error.js\" --copilot-cli"
       }
     ]
   }

package/templates/settings.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/session-start.js\""
+            "command": "npx sticky-note run-hook session-start"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/session-end.js\""
+            "command": "npx sticky-note run-hook session-end"
           }
         ]
       }
@@ -28,7 +28,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/inject-context.js\""
+            "command": "npx sticky-note run-hook inject-context"
           }
         ]
       }
@@ -39,7 +39,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/pre-tool-use.js\""
+            "command": "npx sticky-note run-hook pre-tool-use"
           }
         ]
       }
@@ -50,7 +50,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/track-work.js\""
+            "command": "npx sticky-note run-hook track-work"
           }
         ]
       }
@@ -61,7 +61,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/on-stop.js\""
+            "command": "npx sticky-note run-hook on-stop"
           }
         ]
       }
@@ -72,7 +72,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/on-error.js\""
+            "command": "npx sticky-note run-hook on-error"
           }
         ]
       }

package/templates/sticky-note-config.json

@@ -7,5 +7,6 @@
   "mcp_servers": [],
   "skills": [],
   "conventions": [],
-  "hook_version": "2.5.0"
+  "hook_version": "2.5.0",
+  "min_version": "2.9.1"
 }

package/templates/sticky-note.json

@@ -1,5 +1,5 @@
-{
-  "version": "2",
-  "project": "",
-  "threads": []
-}
+{
+  "version": "2",
+  "project": "",
+  "threads": []
+}