@cachly-dev/mcp-server 0.10.118 → 0.10.120

package/README.md

@@ -266,7 +266,7 @@ npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git
 ```
 
 > **Tip — auto-learn on every merged PR:** run `learn-git` in CI via the
-> [cachly-brain-setup GitHub Action](https://github.com/cachly-dev/cachly/tree/main/sdk/github-action)
+> [cachly-brain-setup GitHub Action](https://github.com/cachly-dev/cachly-action)
 > with `mode: learn`. Each merged PR teaches your Brain automatically.
 
 ---
@@ -282,6 +282,10 @@ known cause. Ready-to-paste templates live in
   outcome to your Brain. Requires `CACHLY_JWT` + `CACHLY_BRAIN_INSTANCE_ID` secrets.
 - **GitLab CI** — copy [`brain-from-ci-gitlab.yml`](./src/ci-integration/brain-from-ci-gitlab.yml)
   into your pipeline: two `.post` jobs (`on_success` / `on_failure`) with `allow_failure: true`.
+  Want more than outcome pushes? The full GitLab template
+  [`cachly.gitlab-ci.yml`](https://github.com/cachly-dev/cachly-action/blob/main/templates/cachly.gitlab-ci.yml)
+  adds hidden jobs for `learn` / `scan` / `confirm` — pull it in with
+  `include: remote:` (it is an includable template, not a CI/CD Catalog component).
 - **Anything else** — [`push-ci-outcome.mjs`](./src/ci-integration/push-ci-outcome.mjs) is a
   standalone Node.js helper with zero dependencies. It always exits 0 — your CI never
   fails because of a Brain push.
@@ -291,7 +295,7 @@ MCP tool — bulk-ingests past outcomes the same way `brain_from_git` ingests co
 
 ---
 
-## MCP Tools (140 total)
+## MCP Tools (126 total)
 
 The full tool catalog is generated from `sdk/mcp/src/tools.ts`. Cross-surface
 coverage is tracked in [`../../docs/generated/surface-parity.md`](../../docs/generated/surface-parity.md),
@@ -551,7 +555,7 @@ keep talking to your backend on every editor launch. All data stays in your infr
 | Feature | Tool | What it does |
 |---|---|---|
 | Autonomous hygiene | `brain_hygiene` | Sweeps stale lessons, flags provisional, archives orphans |
-| PR risk scan | `brain_plan` + `cachly-action scan` | Predicts CI failures before they run, posts PR comment |
+| PR risk scan | `cachly-action` `scan` / `predict` modes | Matches PR title, body and changed files against Brain lessons via the `/scan` API — posts a PR comment with risk score before CI runs |
 | Multi-agent arbitration | `brain_conflicts` · `brain_resolve_conflict` | Detects + resolves conflicting lessons across agents |
 | Plans dashboard | `brain_plan` | Persistent plans in the UI with step tracking and brain-viz overlay |
 | Privacy federation | `brain_contribute_signal` · `brain_import_meta` | Share patterns without sharing data — k-anonymous global commons |

package/dist/src/editor.d.ts

@@ -0,0 +1,9 @@
+export type Editor = 'claude' | 'cursor' | 'windsurf' | 'copilot' | 'vscode' | 'jetbrains' | 'zed' | 'unknown';
+type Env = Record<string, string | undefined>;
+/**
+ * Best-effort host detection. Order matters: forks of VS Code (Cursor,
+ * Windsurf) also set TERM_PROGRAM=vscode, so their fork-specific signals are
+ * checked BEFORE the generic vscode fallback.
+ */
+export declare function detectEditor(env?: Env): Editor;
+export {};

package/dist/src/editor.js

@@ -0,0 +1,63 @@
+// Editor / host detection for telemetry attribution.
+//
+// The evening funnel report showed `unknown: 345` vs `claude: 96` / `vscode: 25`
+// — the largest bucket was unattributed. The old detector only checked four
+// env vars (CURSOR_TRACE_ID, WINDSURF_SESSION_ID, GITHUB_COPILOT_WORKSPACE,
+// CLAUDE_CODE_ENTRYPOINT), so every other host — VS Code running the server as
+// a native MCP stdio child, JetBrains, Zed, plain terminals — fell through to
+// "unknown". This widens detection to the stable signals each host actually
+// sets, ordered most-specific first, and stays a pure function of the env so it
+// is exhaustively unit-testable.
+/**
+ * Best-effort host detection. Order matters: forks of VS Code (Cursor,
+ * Windsurf) also set TERM_PROGRAM=vscode, so their fork-specific signals are
+ * checked BEFORE the generic vscode fallback.
+ */
+export function detectEditor(env = process.env) {
+    const has = (k) => typeof env[k] === 'string' && env[k] !== '';
+    // ── Claude Code ─────────────────────────────────────────────────────────
+    // CLAUDE_CODE_ENTRYPOINT is the long-standing signal; CLAUDECODE=1 is set by
+    // newer builds. Either identifies the Claude Code host.
+    if (has('CLAUDE_CODE_ENTRYPOINT') || env.CLAUDECODE === '1')
+        return 'claude';
+    // ── VS Code forks (must precede the generic vscode check) ────────────────
+    if (has('CURSOR_TRACE_ID') || env.TERM_PROGRAM === 'cursor')
+        return 'cursor';
+    if (has('WINDSURF_SESSION_ID') || env.TERM_PROGRAM === 'windsurf')
+        return 'windsurf';
+    // ── GitHub Copilot (agent workspace) ─────────────────────────────────────
+    if (has('GITHUB_COPILOT_WORKSPACE') || has('COPILOT_AGENT_ID'))
+        return 'copilot';
+    // ── Zed ──────────────────────────────────────────────────────────────────
+    if (env.TERM_PROGRAM === 'zed' || has('ZED_TERM'))
+        return 'zed';
+    // ── JetBrains (IntelliJ/PyCharm/GoLand/… integrated terminal) ────────────
+    if (env.TERMINAL_EMULATOR === 'JetBrains-JediTerm' ||
+        has('__INTELLIJ_COMMAND_HISTFILE__') ||
+        has('IDEA_INITIAL_DIRECTORY')) {
+        return 'jetbrains';
+    }
+    // ── VS Code (generic — after the forks above) ────────────────────────────
+    // TERM_PROGRAM=vscode covers the integrated terminal; the macOS bundle id
+    // and VSCODE_* handshake vars cover the native MCP stdio child (no terminal).
+    if (env.TERM_PROGRAM === 'vscode' ||
+        has('VSCODE_PID') ||
+        has('VSCODE_CWD') ||
+        has('VSCODE_IPC_HOOK') ||
+        has('VSCODE_IPC_HOOK_CLI') ||
+        has('VSCODE_GIT_IPC_HANDLE') ||
+        isVSCodeBundle(env.__CFBundleIdentifier)) {
+        return 'vscode';
+    }
+    return 'unknown';
+}
+/** macOS sets __CFBundleIdentifier to the launching app's bundle id. */
+function isVSCodeBundle(bundle) {
+    if (!bundle)
+        return false;
+    return (bundle === 'com.microsoft.VSCode' ||
+        bundle === 'com.microsoft.VSCodeInsiders' ||
+        bundle === 'com.visualstudio.code.oss' ||
+        bundle.startsWith('com.microsoft.VSCode'));
+}
+//# sourceMappingURL=editor.js.map

package/dist/src/editor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.js","sourceRoot":"","sources":["../../src/editor.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,iFAAiF;AACjF,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,gFAAgF;AAChF,iCAAiC;AAcjC;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAW,OAAO,CAAC,GAAG;IACjD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IAEvE,2EAA2E;IAC3E,6EAA6E;IAC7E,wDAAwD;IACxD,IAAI,GAAG,CAAC,wBAAwB,CAAC,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC;IAE7E,4EAA4E;IAC5E,IAAI,GAAG,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC7E,IAAI,GAAG,CAAC,qBAAqB,CAAC,IAAI,GAAG,CAAC,YAAY,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IAErF,4EAA4E;IAC5E,IAAI,GAAG,CAAC,0BAA0B,CAAC,IAAI,GAAG,CAAC,kBAAkB,CAAC;QAAE,OAAO,SAAS,CAAC;IAEjF,4EAA4E;IAC5E,IAAI,GAAG,CAAC,YAAY,KAAK,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAEhE,4EAA4E;IAC5E,IACE,GAAG,CAAC,iBAAiB,KAAK,oBAAoB;QAC9C,GAAG,CAAC,+BAA+B,CAAC;QACpC,GAAG,CAAC,wBAAwB,CAAC,EAC7B,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,8EAA8E;IAC9E,IACE,GAAG,CAAC,YAAY,KAAK,QAAQ;QAC7B,GAAG,CAAC,YAAY,CAAC;QACjB,GAAG,CAAC,YAAY,CAAC;QACjB,GAAG,CAAC,iBAAiB,CAAC;QACtB,GAAG,CAAC,qBAAqB,CAAC;QAC1B,GAAG,CAAC,uBAAuB,CAAC;QAC5B,cAAc,CAAC,GAAG,CAAC,oBAAoB,CAAC,EACxC,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,wEAAwE;AACxE,SAAS,cAAc,CAAC,MAA0B;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,CACL,MAAM,KAAK,sBAAsB;QACjC,MAAM,KAAK,8BAA8B;QACzC,MAAM,KAAK,2BAA2B;QACtC,MAAM,CAAC,UAAU,CAAC,sBAAsB,CAAC,CAC1C,CAAC;AACJ,CAAC"}

package/dist/src/funnel-milestones.d.ts

@@ -0,0 +1,5 @@
+export declare function defaultMilestonePath(): string;
+/** True when this milestone was already sent from this machine. */
+export declare function milestoneSent(name: string, path?: string): boolean;
+/** Record a milestone (idempotent). Never throws. */
+export declare function markMilestoneSent(name: string, path?: string): void;

package/dist/src/funnel-milestones.js

@@ -0,0 +1,48 @@
+// Persistent once-per-machine funnel milestones.
+//
+// Milestones like first_call_success were guarded by an in-memory flag only —
+// but ambient hooks spawn a FRESH server process per prompt, so every hook
+// invocation re-sent "first call" and the backend saw 66 "first" calls from
+// one user (and Telegram pinged the founder on every one). Persisting the
+// marker in ~/.cachly/ makes "first" mean first-on-this-machine across
+// process restarts. Best-effort: any filesystem problem degrades to the old
+// in-memory behaviour (the backend now dedupes too), never throws.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function defaultMilestonePath() {
+    return join(homedir(), '.cachly', 'funnel-milestones.json');
+}
+function readAll(path) {
+    try {
+        if (!existsSync(path))
+            return {};
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {}; // corrupt file → treat as empty, next mark rewrites it
+    }
+}
+/** True when this milestone was already sent from this machine. */
+export function milestoneSent(name, path = defaultMilestonePath()) {
+    return name in readAll(path);
+}
+/** Record a milestone (idempotent). Never throws. */
+export function markMilestoneSent(name, path = defaultMilestonePath()) {
+    try {
+        const all = readAll(path);
+        if (name in all)
+            return;
+        all[name] = new Date().toISOString();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(all, null, 2) + '\n', 'utf-8');
+    }
+    catch {
+        /* best-effort — the server-side dedup is the safety net */
+    }
+}
+//# sourceMappingURL=funnel-milestones.js.map

package/dist/src/funnel-milestones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel-milestones.js","sourceRoot":"","sources":["../../src/funnel-milestones.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,uEAAuE;AACvE,4EAA4E;AAC5E,mEAAmE;AAEnE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,wBAAwB,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAY,CAAC;QAClE,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACnE,OAAO,MAAgC,CAAC;QAC1C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,uDAAuD;IACpE,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,OAAe,oBAAoB,EAAE;IAC/E,OAAO,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAe,oBAAoB,EAAE;IACnF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,IAAI,IAAI,GAAG;YAAE,OAAO;QACxB,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;AACH,CAAC"}

package/dist/src/handlers/brain.js

@@ -7,8 +7,15 @@ import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _i
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.115';
+const MCP_VERSION = '0.10.119';
 const WHATS_NEW = {
+    '0.10.119': [
+        `🔍 **Explainable briefings — provenance in every warning**`,
+        `  📎 \`/briefing\` warnings now carry \`outcome\`, \`author\`, \`learned_at\` and \`matched_on\` (the context tokens that triggered the warning) — editors can show WHY a fix hint fired, not just what it claims.`,
+        `  🧰 VS Code 0.12.0 uses this: severity + confidence in the toast, full lesson card with provenance, "Not helpful" per-file suppression, reviewable CLS auto-learns.`,
+        `  🧹 CI docs now describe exactly what ships: scan mode uses the REST \`/scan\` endpoint, the GitLab template covers learn/scan/confirm.`,
+        `  📊 126 MCP tools`,
+    ],
     '0.10.115': [
         `🔧 **\`brain_get_pref\` + \`brain_set_pref\` — persistent Brain preferences**`,
         `  📖 \`brain_get_pref\` reads back any stored preference (omit key to list all).`,