@cachly-dev/mcp-server 0.10.86 → 0.10.88

package/dist/src/index.d.ts

@@ -1,3 +1,13 @@
 #!/usr/bin/env node
 import { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS, katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP } from './search.js';
 export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS, katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP };
+export declare const EDITOR_FILES: Record<string, string>;
+export declare const CLAUDE_MD_MARKER_START = "<!-- cachly-brain-start -->";
+export declare const CLAUDE_MD_MARKER_END = "<!-- cachly-brain-end -->";
+export declare function buildServerEnv(apiKey: string, instanceId: string): Record<string, string>;
+export declare function buildMcpConfig(apiKey: string, instanceId: string, editor: string): string;
+export declare function mergeMcpConfig(configPath: string, apiKey: string, instanceId: string, editor: string, fsOps: {
+    readFile: (p: string, enc: BufferEncoding) => Promise<string>;
+    existsSync: (p: string) => boolean;
+}): Promise<string>;
+export declare function buildClaudeMdBlock(instanceId: string): string;

package/dist/src/index.js

@@ -65,7 +65,7 @@ import { Redis } from 'ioredis';
 let API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const _EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.10.86';
+const CURRENT_VERSION = '0.10.88';
 // Max time to wait for a freshly-provisioned instance to become "running" before
 // giving up. Free-tier provisioning in high-latency regions can take 45–90s, so the
 // old hard-coded 25s caused spurious "instance_not_reachable" on first run.
@@ -109,7 +109,15 @@ async function autoProvisionInstance() {
             }).catch(() => { });
         }
     }
-    catch { /* non-fatal — server unreachable */ }
+    catch {
+        // Network unreachable — fire telemetry so silent provision failures are visible in the funnel.
+        void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ event: 'auto_provision_failed', status: 0, reason: 'network_error', version: CURRENT_VERSION }),
+            signal: AbortSignal.timeout(3000),
+        }).catch(() => { });
+    }
     return '';
 }
 async function resolveDefaultInstanceId() {
@@ -174,20 +182,24 @@ let _authHealAttemptedAt = 0;
 const AUTH_HEAL_COOLDOWN_MS = 60_000;
 // Surfaced in session_start / get_api_status so the user is never left guessing.
 let _authDegradedNotice = '';
-/** Persist a (possibly refreshed) API key to ~/.claude/mcp.json so restarts keep it. */
+/** Persist a (possibly refreshed) API key to ~/.claude/mcp.json so restarts keep it.
+ * Also updates CACHLY_JWT in Cursor and Windsurf configs when they already have a cachly entry,
+ * so users who auth via one editor don't lose their session in the others.
+ */
 async function persistApiKeyToConfig(apiKey) {
     try {
         const { writeFile, mkdir, readFile } = await import('node:fs/promises');
         const { existsSync } = await import('node:fs');
         const { resolve, dirname } = await import('node:path');
-        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.env.APPDATA ?? '';
         if (!home)
             return;
-        const configPath = resolve(home, '.claude', 'mcp.json');
+        // Primary config: create or update ~/.claude/mcp.json
+        const claudePath = resolve(home, '.claude', 'mcp.json');
         let cfg = {};
-        if (existsSync(configPath)) {
+        if (existsSync(claudePath)) {
             try {
-                cfg = JSON.parse(await readFile(configPath, 'utf-8'));
+                cfg = JSON.parse(await readFile(claudePath, 'utf-8'));
             }
             catch { /* corrupt — start fresh */ }
         }
@@ -203,8 +215,28 @@ async function persistApiKeyToConfig(apiKey) {
                 env: { CACHLY_JWT: apiKey },
             };
         }
-        await mkdir(dirname(configPath), { recursive: true });
-        await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
+        await mkdir(dirname(claudePath), { recursive: true });
+        await writeFile(claudePath, JSON.stringify(cfg, null, 2), 'utf-8');
+        // Secondary configs: update CACHLY_JWT wherever cachly is already configured.
+        // Never create from scratch — only update existing entries (the user set these up).
+        const secondaryPaths = [
+            resolve(home, '.cursor', 'mcp.json'),
+            resolve(home, '.codeium', 'windsurf', 'mcp_config.json'),
+        ];
+        await Promise.allSettled(secondaryPaths.map(async (p) => {
+            if (!existsSync(p))
+                return;
+            try {
+                const raw = await readFile(p, 'utf-8');
+                const sc = JSON.parse(raw);
+                const entry = sc?.mcpServers?.['cachly'];
+                if (entry?.env) {
+                    entry.env['CACHLY_JWT'] = apiKey;
+                    await writeFile(p, JSON.stringify(sc, null, 2), 'utf-8');
+                }
+            }
+            catch { /* corrupt or unwriteable — skip */ }
+        }));
     }
     catch { /* non-critical — never break a tool call on a filesystem error */ }
 }
@@ -220,24 +252,27 @@ async function persistInstanceIdToConfig(instanceId) {
         const { writeFile, readFile } = await import('node:fs/promises');
         const { existsSync } = await import('node:fs');
         const { resolve } = await import('node:path');
-        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.env.APPDATA ?? '';
         if (!home)
             return;
-        const configPath = resolve(home, '.claude', 'mcp.json');
-        if (!existsSync(configPath))
-            return;
-        let cfg = {};
-        try {
-            cfg = JSON.parse(await readFile(configPath, 'utf-8'));
-        }
-        catch {
-            return;
-        }
-        const entry = cfg.mcpServers?.['cachly'];
-        if (entry?.env) {
-            entry.env['CACHLY_BRAIN_INSTANCE_ID'] = instanceId;
-            await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
-        }
+        const configPaths = [
+            resolve(home, '.claude', 'mcp.json'),
+            resolve(home, '.cursor', 'mcp.json'),
+            resolve(home, '.codeium', 'windsurf', 'mcp_config.json'),
+        ];
+        await Promise.allSettled(configPaths.map(async (p) => {
+            if (!existsSync(p))
+                return;
+            try {
+                const cfg = JSON.parse(await readFile(p, 'utf-8'));
+                const entry = cfg?.mcpServers?.['cachly'];
+                if (entry?.env) {
+                    entry.env['CACHLY_BRAIN_INSTANCE_ID'] = instanceId;
+                    await writeFile(p, JSON.stringify(cfg, null, 2), 'utf-8');
+                }
+            }
+            catch { /* corrupt or unwriteable — skip */ }
+        }));
     }
     catch { /* non-critical */ }
 }
@@ -708,6 +743,7 @@ async function handleTool(name, args) {
                 return handleTool(name, args);
             }
             if (result === 'expired') {
+                sendFunnelEvent('device_flow_failed', { reason: 'timeout' });
                 _deviceFlow = null;
                 return '⌛ **Authentication timed out.** Please call any tool again to restart the sign-in flow.';
             }
@@ -828,12 +864,26 @@ async function handleTool(name, args) {
                         // Append bootstrap summary to the session_start briefing.
                         // brainResult is always a string here (handleBrainTool returns string for session_start).
                         const bootstrapText = String(gitBootstrap);
-                        if (bootstrapText || starterText) {
-                            return String(brainResult) + '\n---\n' + bootstrapText + starterText;
+                        // Show a concrete count so the user knows what was seeded (the WOW moment).
+                        const totalSeeded = _lastBrainFromGitCounts?.total ?? 0;
+                        const seedBanner = totalSeeded > 0
+                            ? `\n✅ **Brain bootstrapped from git — ${totalSeeded} lesson${totalSeeded === 1 ? '' : 's'} loaded.** Your AI already knows your history.`
+                            : '';
+                        if (bootstrapText || starterText || seedBanner) {
+                            return String(brainResult) + seedBanner + '\n---\n' + bootstrapText + starterText;
                         }
                     }
                 }
-                catch { /* git bootstrap errors must never break session_start */ }
+                catch (gitErr) {
+                    // Bootstrap failed — fire telemetry so we can investigate and tell the user
+                    // what happened (don't leave them wondering why the brain is empty).
+                    sendFunnelEvent('brain_from_git_failed', { ...telemetryExtra,
+                        reason: gitErr instanceof Error ? gitErr.message.slice(0, 120) : 'unknown' });
+                    return String(brainResult) +
+                        '\n\n> ⚠️ **Auto-bootstrap from git history failed** — your Brain is live but starts empty.\n' +
+                        '> Run `brain_from_git(instance_id="' + instanceId + '", repo_path="' + String(args.workspace_path) + '")` manually to seed it.\n' +
+                        '> Or try `brain_seed_starter` to load 16 universal engineering lessons instantly.';
+                }
             }
         }
         else if (name === 'session_end') {
@@ -1163,7 +1213,7 @@ process.on('unhandledRejection', (reason) => {
     process.stderr.write(`[cachly-mcp] unhandledRejection: ${msg}\n`);
 });
 // ── CLI helpers ───────────────────────────────────────────────────────────────
-const EDITOR_FILES = {
+export const EDITOR_FILES = {
     claude: '.mcp.json',
     cursor: '.cursor/mcp.json',
     windsurf: '.windsurf/mcp.json',
@@ -1172,8 +1222,8 @@ const EDITOR_FILES = {
     cline: '.vscode/mcp.json', // Cline respects VS Code project MCP config
     zed: '.zed/settings.json', // Zed project-level context_servers
 };
-const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
-const CLAUDE_MD_MARKER_END = '<!-- cachly-brain-end -->';
+export const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
+export const CLAUDE_MD_MARKER_END = '<!-- cachly-brain-end -->';
 const DEFAULT_API_URL = 'https://api.cachly.dev';
 // Build the env block written into an editor's MCP config. Self-hosting is
 // first-class: if the operator runs setup/init against their own backend
@@ -1181,13 +1231,13 @@ const DEFAULT_API_URL = 'https://api.cachly.dev';
 // the editor-launched server talks to the self-hosted instance — not api.cachly.dev.
 // For the default cloud backend we OMIT CACHLY_API_URL to keep configs clean (the
 // binary already defaults to it).
-function buildServerEnv(apiKey, instanceId) {
+export function buildServerEnv(apiKey, instanceId) {
     const env = { CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId };
     if (API_URL && API_URL !== DEFAULT_API_URL)
         env.CACHLY_API_URL = API_URL;
     return env;
 }
-function buildMcpConfig(apiKey, instanceId, editor) {
+export function buildMcpConfig(apiKey, instanceId, editor) {
     if (editor === 'continue') {
         return JSON.stringify({
             experimental: {
@@ -1224,7 +1274,7 @@ function buildMcpConfig(apiKey, instanceId, editor) {
 }
 // mergeMcpConfig reads an existing config file (if any), merges the cachly entry,
 // and returns the updated JSON string — preserving all other MCP servers and settings.
-async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsOps) {
+export async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsOps) {
     const cachlyEntry = {
         command: 'npx',
         args: ['-y', '@cachly-dev/mcp-server@latest'],
@@ -1270,7 +1320,7 @@ async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsOps) {
     existing['mcpServers'] = servers;
     return JSON.stringify(existing, null, 2);
 }
-function buildClaudeMdBlock(instanceId) {
+export function buildClaudeMdBlock(instanceId) {
     return `${CLAUDE_MD_MARKER_START}
 ## Cachly AI Brain — Always Active
 
@@ -2849,6 +2899,10 @@ if (process.argv[2] === 'setup' || _isAutopilotCli) {
     // Uses mergeMcpConfig to preserve all existing MCP servers — only adds/updates
     // the cachly entry without touching filesystem, github, or other servers.
     const { existsSync: exSetup } = await import('node:fs');
+    // Track config-write failures so the final summary tells the truth instead of
+    // always claiming "Brain is ready" even when a config never got written.
+    const configWriteFailures = [];
+    let configWriteSuccesses = 0;
     for (const editor of editorsToSetup) {
         const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
         const configPath = resolve(cwd, configFile);
@@ -2858,10 +2912,13 @@ if (process.argv[2] === 'setup' || _isAutopilotCli) {
             const merged = await mergeMcpConfig(configPath, token, instance.id, editor, { readFile, existsSync: exSetup });
             await writeFile(configPath, merged, 'utf-8');
             console.log(`✅ ${wasExisting ? 'Updated' : 'Written'}: ${configFile}`);
+            configWriteSuccesses++;
         }
         catch (writeErr) {
-            console.log(`⚠️  Could not write ${configFile}: ${writeErr.message}`);
+            const reason = writeErr.message;
+            console.log(`⚠️  Could not write ${configFile}: ${reason}`);
             console.log(`   Fix permissions or run with sudo, then re-run setup.`);
+            configWriteFailures.push({ file: configFile, reason });
         }
     }
     // ── Step 4b: Write global Claude Code config (~/.claude/mcp.json) ─────────
@@ -2885,9 +2942,12 @@ if (process.argv[2] === 'setup' || _isAutopilotCli) {
         };
         await writeFile(globalClaudePath, JSON.stringify(globalConfig, null, 2), 'utf-8');
         console.log(`✅ Written: ~/.claude/mcp.json  (global — works in every project)`);
+        configWriteSuccesses++;
     }
     catch (e) {
-        console.log(`⚠️  Could not write ~/.claude/mcp.json: ${e.message}`);
+        const reason = e.message;
+        console.log(`⚠️  Could not write ~/.claude/mcp.json: ${reason}`);
+        configWriteFailures.push({ file: '~/.claude/mcp.json', reason });
     }
     // ── Step 5: CLAUDE.md (always — idempotent) ───────────────────────────────
     const mdResult = await writeClaudeMd(cwd, instance.id);
@@ -3085,15 +3145,51 @@ if (process.argv[2] === 'setup' || _isAutopilotCli) {
         }
     }
     catch { /* non-critical */ }
-    // Setup reached the end successfully — close the funnel.
+    // Setup reached the end — close the funnel. Report config-write outcome so the
+    // weekly funnel can spot permission/path problems blocking activation.
     JWT = token;
     const setupElapsedS = Math.round((Date.now() - setupStartMs) / 1000);
-    sendFunnelEvent('setup_completed', { instance_id: instance.id, elapsed_s: setupElapsedS });
+    if (configWriteFailures.length > 0) {
+        sendFunnelEvent('setup_config_write_failed', {
+            instance_id: instance.id,
+            failed: configWriteFailures.length,
+            succeeded: configWriteSuccesses,
+        });
+    }
+    sendFunnelEvent('setup_completed', {
+        instance_id: instance.id,
+        elapsed_s: setupElapsedS,
+        config_failures: configWriteFailures.length,
+    });
+    if (configWriteFailures.length > 0 && configWriteSuccesses === 0) {
+        // Nothing got written — be honest, this is NOT "ready".
+        console.log('\n╔══════════════════════════════════════════════════════╗');
+        console.log('║  ⚠️   Setup incomplete — no editor config was written ║');
+        console.log('╚══════════════════════════════════════════════════════╝');
+        console.log('\n   Your Brain instance exists, but no editor knows about it yet.');
+        console.log('   Failed writes:');
+        for (const f of configWriteFailures)
+            console.log(`     • ${f.file} — ${f.reason}`);
+        console.log('\n   Fix the permissions above and re-run, or configure manually:');
+        console.log(`     CACHLY_JWT=${token.slice(0, 12)}… CACHLY_BRAIN_INSTANCE_ID=${instance.id}`);
+        console.log(`   Docs: https://cachly.dev/docs/mcp\n`);
+        rl.close();
+        await new Promise(r => setTimeout(r, 300));
+        process.exit(1);
+    }
     console.log('\n╔══════════════════════════════════════════════════════╗');
     console.log('║  🚀  Brain is ready.                                 ║');
     console.log(`║  ⏱️   Setup completed in ${String(setupElapsedS + 's').padEnd(5)} — restart your editor  ║`);
     console.log('║      and your AI arrives pre-briefed every session.  ║');
-    console.log('╚══════════════════════════════════════════════════════╝\n');
+    console.log('╚══════════════════════════════════════════════════════╝');
+    if (configWriteFailures.length > 0) {
+        // Partial success — some editors configured, some not. Tell the truth.
+        console.log('\n   ⚠️  Some editor configs could not be written (others succeeded):');
+        for (const f of configWriteFailures)
+            console.log(`     • ${f.file} — ${f.reason}`);
+        console.log('   Fix the permissions above and re-run setup to configure them too.');
+    }
+    console.log('');
     rl.close();
     // Give the fire-and-forget telemetry a moment to flush before exit.
     await new Promise(r => setTimeout(r, 300));