sticky-note-cli 2.9.2 → 3.1.0

package/bin/mcp-server.js

@@ -3,9 +3,10 @@
  * sticky-note MCP server — stdio-based
  *
  * Implements Model Context Protocol (JSON-RPC 2.0 over stdin/stdout)
- * with 8 tools for AI assistants:
+ * with 9 tools for AI assistants:
  *
  *   get_session_context(id)              — full thread payload by ID
+ *   get_full_transcript(id)              — full verbatim session transcript(s) for a thread
  *   get_stuck_threads()                  — all stuck threads
  *   search_threads(query)               — keyword search across threads
  *   get_audit_trail(...)                — query per-user JSONL audit logs
@@ -23,6 +24,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { execFileSync } = require("child_process");
 
 // ──────────────────────────────────────────────
 // Project root resolution
@@ -36,8 +38,113 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
+let _cachedStickyDir = null;
 function stickyDir() {
-  return path.join(PROJECT_ROOT, ".sticky-note");
+  if (_cachedStickyDir) return _cachedStickyDir;
+
+  // V3 default storage lives at <git-dir>/sticky-note (the sticky-note/data
+  // orphan branch's local working copy), not in the project's working tree.
+  // Try that first; fall back to the legacy in-tree .sticky-note/ for repos
+  // that haven't migrated (or aren't git repos at all).
+  try {
+    const gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"], cwd: PROJECT_ROOT,
+    }).trim();
+    const dataBranchDir = path.join(gitDir, "sticky-note");
+    if (fs.existsSync(path.join(dataBranchDir, "sticky-note.json"))) {
+      _cachedStickyDir = dataBranchDir;
+      return _cachedStickyDir;
+    }
+  } catch (_) {
+    // not a git repo, or git unavailable — fall through to legacy path
+  }
+
+  _cachedStickyDir = path.join(PROJECT_ROOT, ".sticky-note");
+  return _cachedStickyDir;
+}
+
+function getTranscriptPath(threadId) {
+  return path.join(stickyDir(), "transcripts", threadId + ".jsonl");
+}
+
+// ──────────────────────────────────────────────
+// Cloud config (V3 optional backend)
+// ──────────────────────────────────────────────
+
+function readEnvSticky() {
+  const envPath = path.join(PROJECT_ROOT, ".env.sticky");
+  const result = {};
+  if (!fs.existsSync(envPath)) return result;
+  for (const line of fs.readFileSync(envPath, "utf-8").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("STICKY_URL=")) result.STICKY_URL = trimmed.slice("STICKY_URL=".length);
+    if (trimmed.startsWith("STICKY_API_KEY=")) result.STICKY_API_KEY = trimmed.slice("STICKY_API_KEY=".length);
+  }
+  return result;
+}
+
+function getCloudConfig() {
+  const envFile = readEnvSticky();
+  return {
+    url: process.env.STICKY_URL || envFile.STICKY_URL || "",
+    apiKey: process.env.STICKY_API_KEY || envFile.STICKY_API_KEY || "",
+  };
+}
+
+function getProjectName() {
+  try {
+    const remote = execFileSync("git", ["remote", "get-url", "origin"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"], cwd: PROJECT_ROOT,
+    }).trim();
+    const match = remote.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (match) return match[1];
+  } catch (_) {}
+  return "default";
+}
+
+let _cloudThreads = null;
+let _cloudPresence = null;
+let _cloudPresenceMap = null;
+
+function buildPresenceMap(presence) {
+  const map = {};
+  for (const entry of presence) {
+    if (entry.user) map[entry.user] = { active_files: entry.active_files || [], last_seen: entry.last_seen };
+  }
+  return map;
+}
+
+async function initCloudCache() {
+  const { url, apiKey } = getCloudConfig();
+  if (!url) return;
+
+  const headers = { "X-Sticky-Project": getProjectName() };
+  if (apiKey) headers["X-Sticky-API-Key"] = apiKey;
+
+  function timedFetch(endpoint) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), 5000);
+    return fetch(`${url}${endpoint}`, { headers, signal: controller.signal })
+      .finally(() => clearTimeout(t));
+  }
+
+  try {
+    const [threadsRes, presenceRes] = await Promise.all([
+      timedFetch("/threads"),
+      timedFetch("/presence"),
+    ]);
+    if (threadsRes.ok) {
+      const data = await threadsRes.json();
+      _cloudThreads = data.threads || [];
+    }
+    if (presenceRes.ok) {
+      const data = await presenceRes.json();
+      _cloudPresence = data.presence || [];
+      _cloudPresenceMap = buildPresenceMap(_cloudPresence);
+    }
+  } catch (_) {
+    process.stderr.write("[sticky-note] Cloud unreachable — using local data\n");
+  }
 }
 
 // ──────────────────────────────────────────────
@@ -69,6 +176,7 @@ function getConfig() {
 }
 
 function getThreads() {
+  if (_cloudThreads !== null) return _cloudThreads;
   return getMemory().threads || [];
 }
 
@@ -77,10 +185,11 @@ function getThreads() {
  * Returns { username: { active_files, last_seen } }
  */
 function getAllPresence() {
+  if (_cloudPresenceMap !== null) return _cloudPresenceMap;
+
   const presenceDir = path.join(stickyDir(), "presence");
   const result = {};
   if (!fs.existsSync(presenceDir)) return result;
-
   for (const file of fs.readdirSync(presenceDir)) {
     if (!file.endsWith(".json")) continue;
     const user = file.replace(".json", "");
@@ -156,6 +265,60 @@ function toolGetSessionContext(params) {
   return { thread };
 }
 
+/**
+ * Return the full verbatim transcript(s) captured for a thread — one entry
+ * per contributing session (a resumed thread may have several). Secrets
+ * are redacted before storage (see redactSecrets in sticky-utils.js) unless
+ * a team has disabled redact_transcripts.
+ */
+function toolGetFullTranscript(params) {
+  const { id } = params;
+  if (!id) {
+    return { error: "Missing required parameter: id" };
+  }
+
+  const threads = getThreads();
+  const thread = threads.find((t) => t.id === id || t.id.startsWith(id) || t.session_id === id);
+  if (!thread) {
+    return { error: `No thread found with id: ${id}` };
+  }
+
+  const filePath = getTranscriptPath(thread.id);
+  if (!fs.existsSync(filePath)) {
+    return {
+      thread_id: thread.id,
+      transcript_captured: !!thread.transcript_captured,
+      sessions: [],
+      note: "No transcript captured for this thread — it may predate transcript capture, or capture_transcripts is disabled for this team.",
+    };
+  }
+
+  const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter((l) => l.trim());
+  const sessions = [];
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    sessions.push({
+      session_id: entry.session_id,
+      tool: entry.tool,
+      user: entry.user,
+      captured_at: entry.captured_at,
+      redacted: !!entry.redacted,
+      transcript: entry.transcript,
+    });
+  }
+
+  return {
+    thread_id: thread.id,
+    session_count: sessions.length,
+    sessions,
+  };
+}
+
 function toolGetStuckThreads() {
   const threads = getThreads();
   const stuck = threads.filter((t) => t.status === "stuck");
@@ -515,6 +678,21 @@ const TOOLS = {
     },
     handler: toolGetSessionContext,
   },
+  get_full_transcript: {
+    description:
+      "Get the full verbatim transcript(s) captured for a thread by ID — one entry per contributing session. Secrets are redacted before storage unless a team disabled redact_transcripts. Returns an empty sessions array if no transcript was captured (e.g. capture_transcripts is off, or the thread predates this feature).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Thread ID or session ID to look up",
+        },
+      },
+      required: ["id"],
+    },
+    handler: toolGetFullTranscript,
+  },
   get_stuck_threads: {
     description:
       "Get all threads with status 'stuck'. Returns full payloads including failed approaches and last notes. Call at session start to check for team blockers.",
@@ -634,7 +812,7 @@ const TOOLS = {
 
 const SERVER_INFO = {
   name: "sticky-note",
-  version: "3.0.0",
+  version: "3.1.0",
 };
 
 const CAPABILITIES = {
@@ -746,43 +924,47 @@ function handleRequest(msg) {
 // stdio transport
 // ──────────────────────────────────────────────
 
-let buffer = "";
+(async () => {
+  await initCloudCache();
 
-process.stdin.setEncoding("utf-8");
-process.stdin.on("data", (chunk) => {
-  buffer += chunk;
+  let buffer = "";
 
-  let newlineIdx;
-  while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
-    const line = buffer.slice(0, newlineIdx).trim();
-    buffer = buffer.slice(newlineIdx + 1);
+  process.stdin.setEncoding("utf-8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
 
-    if (!line) continue;
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim();
+      buffer = buffer.slice(newlineIdx + 1);
 
-    let msg;
-    try {
-      msg = JSON.parse(line);
-    } catch {
-      const errResp = {
-        jsonrpc: "2.0",
-        id: null,
-        error: { code: -32700, message: "Parse error" },
-      };
-      process.stdout.write(JSON.stringify(errResp) + "\n");
-      continue;
-    }
+      if (!line) continue;
 
-    const response = handleRequest(msg);
-    if (response) {
-      process.stdout.write(JSON.stringify(response) + "\n");
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        const errResp = {
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32700, message: "Parse error" },
+        };
+        process.stdout.write(JSON.stringify(errResp) + "\n");
+        continue;
+      }
+
+      const response = handleRequest(msg);
+      if (response) {
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
     }
-  }
-});
+  });
 
-process.stdin.on("end", () => {
-  process.exit(0);
-});
+  process.stdin.on("end", () => {
+    process.exit(0);
+  });
 
-process.on("uncaughtException", (err) => {
-  process.stderr.write(`sticky-note MCP server error: ${err.message}\n`);
-});
+  process.on("uncaughtException", (err) => {
+    process.stderr.write(`sticky-note MCP server error: ${err.message}\n`);
+  });
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sticky-note-cli",
-  "version": "2.9.2",
+  "version": "3.1.0",
   "description": "Human-to-human handoff for AI coding assistants. Git-backed shared memory for Claude Code and Copilot CLI.",
   "license": "MIT",
   "bin": {

package/templates/CLAUDE.md

@@ -33,6 +33,7 @@ cat .sticky-note/sticky-note.json
 | `resumed_by`       | Most recent user to resume this thread (V2.5) |
 | `resumed_at`       | ISO timestamp of most recent resume (V2.5) |
 | `resume_history`   | Full resume chain: user, timestamp, session (V2.5) |
+| `transcript_captured` | Whether a full verbatim session transcript exists for this thread (V3.1) |
 
 ### Status icons
 
@@ -107,6 +108,24 @@ approaches, prompts). Read and present this context to the user immediately —
 do NOT tell them to start a new session. The inject-context hook will also
 pick up the resumed thread on subsequent prompts.
 
+### Full transcript capture (V3.1)
+
+By default, each session's complete verbatim transcript is captured — not
+just the narrative summary — keyed by thread ID and stored alongside audit
+logs and presence data. Secrets are redacted before anything is written
+(best-effort pattern matching, not a guarantee).
+
+- A thread's `transcript_captured` field is `true` once at least one
+  session's transcript has been persisted.
+- Retrieve it with `npx sticky-note transcript <thread-id>` (add `--raw` for
+  the untouched JSONL) or the `get_full_transcript(id)` MCP tool.
+- A team can turn this off with `"capture_transcripts": false` in
+  `sticky-note-config.json` — e.g. for a repo where sessions routinely
+  touch especially sensitive material.
+- When a user asks "what did we actually discuss in that session" (as
+  opposed to "what was the summary"), prefer the transcript over
+  `narrative`/`prompts` — those are truncated summaries, not the full record.
+
 ### File attribution (V2.5)
 
 To see which threads are related to a specific file:
@@ -245,6 +264,10 @@ You have access to a `sticky-note` MCP server. Use it:
 4. **For audit history**: Call `get_audit_trail(file)` to understand who
    changed a file and when.
 
+5. **For the full conversation, not just the summary**: Call
+   `get_full_transcript(id)` to get the verbatim session transcript(s) for
+   a thread, when `narrative` or `prompts` aren't enough detail.
+
 These tools are the primary way sticky-note communicates with you.
 Hook-injected context supplements but does not replace MCP tool calls.
 

package/templates/gitignore-additions.txt

@@ -1,3 +1,6 @@
+# Sticky Note - data moved to sticky-note/data branch (.git/sticky-note/ cache)
+.sticky-note/
+
 # Sticky Note - local overrides
 .claude/settings.local.json
 

package/templates/hooks/data-branch.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * data-branch.js — Git plumbing for the sticky-note/data orphan branch.
+ *
+ * Reads/writes files via git plumbing (hash-object, update-index, write-tree,
+ * commit-tree, update-ref). No working-tree checkout is ever performed.
+ * All operations are synchronous; callers receive result objects on failure.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
+
+const DATA_BRANCH = "sticky-note/data";
+const DATA_REF = "refs/heads/" + DATA_BRANCH;
+
+const GIT_OPTS = { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] };
+
+// ── Git helpers ───────────────────────────────────────────
+
+function getDefaultRemote() {
+  try {
+    const out = execFileSync("git", ["remote"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return out.split(/\r?\n/)[0] || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Returns file content from a git ref as a string, or null if not found. */
+function readFileFromBranch(ref, filePath) {
+  try {
+    return execFileSync("git", ["show", ref + ":" + filePath], GIT_OPTS);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Commit { relativePath: content } to a branch using git plumbing.
+ * Does not touch the working tree or the main index. Returns the new commit SHA.
+ */
+function commitFilesToBranch(branchName, fileMap) {
+  const branchRef = "refs/heads/" + branchName;
+  const tmpIndex = path.join(
+    os.tmpdir(),
+    "sticky-idx-" + process.pid + "-" + crypto.randomBytes(4).toString("hex")
+  );
+
+  try {
+    let parentSha = null;
+    try {
+      parentSha = execFileSync("git", ["rev-parse", "--verify", branchRef], {
+        encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (_) {
+      // Branch doesn't exist yet — first commit creates it as orphan
+    }
+
+    const indexEnv = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+
+    if (parentSha) {
+      execFileSync("git", ["read-tree", parentSha], {
+        timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+        env: indexEnv,
+      });
+    }
+
+    for (const [filePath, content] of Object.entries(fileMap)) {
+      const blobSha = execFileSync("git", ["hash-object", "-w", "--stdin"], {
+        input: content,
+        encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+
+      execFileSync(
+        "git",
+        ["update-index", "--add", "--cacheinfo", "100644," + blobSha + "," + filePath],
+        { timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv }
+      );
+    }
+
+    const treeSha = execFileSync("git", ["write-tree"], {
+      encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+      env: indexEnv,
+    }).trim();
+
+    const commitArgs = ["commit-tree", treeSha, "-m", "chore(sticky-note): sync thread data"];
+    if (parentSha) {
+      commitArgs.push("-p", parentSha);
+    }
+
+    const commitSha = execFileSync("git", commitArgs, GIT_OPTS).trim();
+
+    execFileSync("git", ["update-ref", branchRef, commitSha], {
+      timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    return commitSha;
+  } finally {
+    try { fs.unlinkSync(tmpIndex); } catch (_) {}
+  }
+}
+
+// ── Fetch ─────────────────────────────────────────────────
+
+/**
+ * Fetch the remote data branch into a local remote-tracking ref.
+ * Returns { ok, sha, error, remoteRef }.
+ */
+function fetchDataBranch(remote, branchName) {
+  branchName = branchName || DATA_BRANCH;
+  remote = remote || getDefaultRemote();
+  if (!remote) return { ok: false, sha: null, error: "no remote configured", remoteRef: null };
+
+  const remoteRef = "refs/remotes/" + remote + "/" + branchName;
+  try {
+    execFileSync(
+      "git",
+      ["fetch", remote, branchName + ":" + remoteRef],
+      { timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
+    );
+    let sha = null;
+    try {
+      sha = execFileSync("git", ["rev-parse", "--verify", remoteRef], {
+        encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (_) {}
+    return { ok: true, sha, error: null, remoteRef };
+  } catch (err) {
+    return { ok: false, sha: null, error: err.message, remoteRef };
+  }
+}
+
+// ── Push with retry ────────────────────────────────────────
+
+/**
+ * Push the local data branch to the remote, retrying on rejection.
+ * On non-fast-forward rejection, fetches and merges before retrying.
+ * Returns { ok, error }.
+ */
+function pushDataBranch(remote, branchName, maxRetries, localMemPath, loadJsonFn, saveJsonFn) {
+  branchName = branchName || DATA_BRANCH;
+  remote = remote || getDefaultRemote();
+  maxRetries = maxRetries || 3;
+  if (!remote) return { ok: false, error: "no remote configured" };
+
+  const pushSpec = DATA_REF + ":" + DATA_REF;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      execFileSync("git", ["push", remote, pushSpec], {
+        timeout: 30000, stdio: ["pipe", "pipe", "pipe"],
+      });
+      return { ok: true, error: null };
+    } catch (err) {
+      if (attempt === maxRetries) {
+        return { ok: false, error: err.message };
+      }
+
+      // Fetch, merge, and re-commit so the next push attempt advances the ref
+      try {
+        const fetchResult = fetchDataBranch(remote, branchName);
+        if (fetchResult.ok && fetchResult.remoteRef && localMemPath) {
+          const remoteContent = readFileFromBranch(fetchResult.remoteRef, "sticky-note.json");
+          if (remoteContent) {
+            mergeAndSaveFromRemote(localMemPath, remoteContent, loadJsonFn, saveJsonFn);
+            const mergedContent = fs.readFileSync(localMemPath, "utf-8");
+            commitFilesToBranch(branchName, { "sticky-note.json": mergedContent });
+          }
+        }
+      } catch (_) {}
+
+      // Brief exponential backoff (busy-wait — synchronous context)
+      const end = Date.now() + Math.pow(2, attempt) * 300;
+      while (Date.now() < end) {}
+    }
+  }
+  return { ok: false, error: "max retries exceeded" };
+}
+
+// ── Thread merge ──────────────────────────────────────────
+
+function _mostRecentTimestamp(thread) {
+  return thread.last_activity_at || thread.updated_at || thread.created_at || "";
+}
+
+/**
+ * Merge two thread arrays, preferring the more-recently-active copy
+ * when both contain the same thread ID.
+ */
+function mergeThreadArrays(localThreads, remoteThreads) {
+  const merged = new Map();
+
+  for (const t of (localThreads || [])) {
+    if (t && t.id) merged.set(t.id, t);
+  }
+
+  for (const t of (remoteThreads || [])) {
+    if (!t || !t.id) continue;
+    const existing = merged.get(t.id);
+    if (!existing || _mostRecentTimestamp(t) > _mostRecentTimestamp(existing)) {
+      merged.set(t.id, t);
+    }
+  }
+
+  return Array.from(merged.values());
+}
+
+const EMPTY_MEMORY = { version: "2", project: "", threads: [] };
+
+/**
+ * Merge remote sticky-note.json content into the local memory file.
+ * Uses loadJsonFn/saveJsonFn when provided, otherwise reads/writes directly.
+ */
+function mergeAndSaveFromRemote(localMemPath, remoteContent, loadJsonFn, saveJsonFn) {
+  let remoteMemory;
+  try {
+    remoteMemory = JSON.parse(remoteContent);
+  } catch (_) {
+    return; // corrupt remote — skip
+  }
+
+  const localMemory = loadJsonFn
+    ? loadJsonFn(localMemPath, { ...EMPTY_MEMORY })
+    : { ...EMPTY_MEMORY };
+
+  const localThreads = Array.isArray(localMemory.threads) ? localMemory.threads.filter(Boolean) : [];
+  const remoteThreads = Array.isArray(remoteMemory.threads) ? remoteMemory.threads.filter(Boolean) : [];
+  localMemory.threads = mergeThreadArrays(localThreads, remoteThreads);
+
+  if (saveJsonFn) {
+    saveJsonFn(localMemPath, localMemory);
+  } else {
+    fs.mkdirSync(path.dirname(localMemPath), { recursive: true });
+    fs.writeFileSync(localMemPath, JSON.stringify(localMemory, null, 2) + "\n", "utf-8");
+  }
+}
+
+// ── Exports ───────────────────────────────────────────────
+
+module.exports = {
+  DATA_BRANCH,
+  DATA_REF,
+  getDefaultRemote,
+  readFileFromBranch,
+  commitFilesToBranch,
+  fetchDataBranch,
+  pushDataBranch,
+  mergeThreadArrays,
+  mergeAndSaveFromRemote,
+};