@cachly-dev/mcp-server 0.10.84 → 0.10.86

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.84';
+const CURRENT_VERSION = '0.10.86';
 // 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.
@@ -77,35 +77,92 @@ const PROVISION_TIMEOUT_MS = Number(process.env.CACHLY_PROVISION_TIMEOUT_MS ?? 9
 let _defaultInstanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
 // Timestamp of last failed fetch — retries after 30 s (not permanently blocked).
 let _defaultInstanceLastAttempt = 0;
+// In-flight resolution guard: a burst of parallel tool calls on startup must not
+// each list-and-provision (which would race and create duplicate instances).
+let _resolveInFlight = null;
+/**
+ * Auto-provision a Brain instance via the idempotent find-or-create endpoint.
+ * Returns the instance id, or '' on failure. Fires auto_provision_failed telemetry
+ * on a non-2xx response so the activation funnel can spot free-tier breakage.
+ */
+async function autoProvisionInstance() {
+    if (!JWT)
+        return '';
+    try {
+        const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(12000),
+        });
+        if (autoRes.ok) {
+            const body = await autoRes.json();
+            const id = body.instance?.id ?? body.instance_id;
+            if (id)
+                return id;
+        }
+        else {
+            void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${JWT}` },
+                body: JSON.stringify({ event: 'auto_provision_failed', status: autoRes.status, version: CURRENT_VERSION }),
+                signal: AbortSignal.timeout(3000),
+            }).catch(() => { });
+        }
+    }
+    catch { /* non-fatal — server unreachable */ }
+    return '';
+}
 async function resolveDefaultInstanceId() {
     if (_defaultInstanceId)
         return _defaultInstanceId;
     if (!JWT)
         return '';
+    // Coalesce concurrent resolutions so parallel tool calls share one round-trip.
+    if (_resolveInFlight)
+        return _resolveInFlight;
     // Cooldown: don't hammer the API on every tool call after a transient failure.
     const now = Date.now();
     if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 30_000)
         return '';
     _defaultInstanceLastAttempt = now;
-    try {
-        const res = await fetch(`${API_URL}/api/v1/instances`, {
-            headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
-            signal: AbortSignal.timeout(5000),
-        });
-        if (!res.ok)
-            return '';
-        const data = await res.json();
-        const instances = (data?.data ?? []);
-        // Prefer running, fall back to provisioning so the ID is resolved even during startup.
-        const best = instances.find(i => i.status === 'running') ?? instances.find(i => i.status === 'provisioning');
-        if (best) {
-            _defaultInstanceId = best.id;
-            _defaultInstanceLastAttempt = 0;
-            return _defaultInstanceId;
+    _resolveInFlight = (async () => {
+        try {
+            const res = await fetch(`${API_URL}/api/v1/instances`, {
+                headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (res.ok) {
+                const data = await res.json();
+                const instances = (data?.data ?? []);
+                // Prefer running, fall back to provisioning so the ID resolves even during startup.
+                const best = instances.find(i => i.status === 'running') ?? instances.find(i => i.status === 'provisioning');
+                if (best) {
+                    _defaultInstanceId = best.id;
+                    _defaultInstanceLastAttempt = 0;
+                    return _defaultInstanceId;
+                }
+                // Authenticated but zero instances → auto-provision so the user is never
+                // stuck. This self-heals the silent failure mode where device-flow
+                // provisioning failed once and every later tool call then ran with an
+                // empty instance_id (no recalls, never counted as an active instance).
+                const provisioned = await autoProvisionInstance();
+                if (provisioned) {
+                    _defaultInstanceId = provisioned;
+                    _defaultInstanceLastAttempt = 0;
+                    void persistInstanceIdToConfig(provisioned);
+                    return _defaultInstanceId;
+                }
+            }
         }
+        catch { /* transient error — will retry after cooldown */ }
+        return '';
+    })();
+    try {
+        return await _resolveInFlight;
+    }
+    finally {
+        _resolveInFlight = null;
     }
-    catch { /* transient error — will retry after cooldown */ }
-    return '';
 }
 // ── Self-Healing Auth ─────────────────────────────────────────────────────────
 // Prevents the silent "0 recalls because the token quietly died" failure mode.
@@ -151,6 +208,39 @@ async function persistApiKeyToConfig(apiKey) {
     }
     catch { /* non-critical — never break a tool call on a filesystem error */ }
 }
+/**
+ * Persist the resolved instance id to ~/.claude/mcp.json so restarts reuse it
+ * (avoids a list/provision round-trip on every startup). Only updates an
+ * existing cachly entry — does not create config from scratch.
+ */
+async function persistInstanceIdToConfig(instanceId) {
+    if (!instanceId)
+        return;
+    try {
+        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 ?? '';
+        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');
+        }
+    }
+    catch { /* non-critical */ }
+}
 /**
  * Exchange the current (still-valid) token for a fresh long-lived API key.
  * Returns true on success. Used by self-healing when a token is near expiry.
@@ -312,67 +402,13 @@ async function pollDeviceFlow(flow) {
             // Persist the API key to ~/.claude/mcp.json so subsequent MCP server restarts
             // keep the token. Without this, JWT is lost on restart and brain_recall_count
             // is never incremented (telemetry has no api_key → no tenant resolution).
-            void (async () => {
-                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 ?? '';
-                    if (!home)
-                        return;
-                    const configPath = resolve(home, '.claude', 'mcp.json');
-                    let cfg = {};
-                    if (existsSync(configPath)) {
-                        try {
-                            cfg = JSON.parse(await readFile(configPath, 'utf-8'));
-                        }
-                        catch { /* corrupt — start fresh */ }
-                    }
-                    cfg.mcpServers ??= {};
-                    const existing = cfg.mcpServers['cachly'];
-                    if (existing) {
-                        existing.env ??= {};
-                        existing.env['CACHLY_JWT'] = apiKey;
-                    }
-                    else {
-                        cfg.mcpServers['cachly'] = {
-                            command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'],
-                            env: { CACHLY_JWT: apiKey },
-                        };
-                    }
-                    await mkdir(dirname(configPath), { recursive: true });
-                    await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
-                }
-                catch { /* non-critical — don't break the flow on filesystem errors */ }
-            })();
-            // Auto-provision: find or create the user's brain instance.
+            void persistApiKeyToConfig(apiKey);
+            // Auto-provision: find or create the user's brain instance. resolveDefaultInstanceId
+            // now lists existing instances and auto-provisions when the account has none,
+            // so a single call covers both paths (and self-heals on every later tool call
+            // if provisioning is briefly unavailable here).
             _defaultInstanceLastAttempt = 0;
             await resolveDefaultInstanceId();
-            if (!_defaultInstanceId) {
-                try {
-                    const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
-                        method: 'POST',
-                        headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
-                        signal: AbortSignal.timeout(12000),
-                    });
-                    if (autoRes.ok) {
-                        const body = await autoRes.json();
-                        const id = body.instance?.id ?? body.instance_id;
-                        if (id)
-                            _defaultInstanceId = id;
-                    }
-                    else {
-                        // Log so telemetry can detect free-tier auto-provision failures
-                        void fetch(`${API_URL}/api/v1/telemetry/mcp`, {
-                            method: 'POST',
-                            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${JWT}` },
-                            body: JSON.stringify({ event: 'auto_provision_failed', status: autoRes.status, version: CURRENT_VERSION }),
-                            signal: AbortSignal.timeout(3000),
-                        }).catch(() => { });
-                    }
-                }
-                catch { /* non-fatal — server unreachable, getConnection will surface the error */ }
-            }
             // Give a provisioning instance a head-start so getConnection's wait is shorter.
             // The instance is almost always ready by the time the user's tool re-enters.
             if (_defaultInstanceId) {
@@ -405,37 +441,10 @@ async function pollDeviceFlow(flow) {
                 }
                 catch { /* non-fatal — getConnection will handle the wait if still provisioning */ }
             }
-            // Persist instance_id to ~/.claude/mcp.json after it's known.
-            // Without this, every restart loses CACHLY_BRAIN_INSTANCE_ID → resolveDefaultInstanceId
-            // makes an extra API call on every startup (with 30s cooldown on failure).
-            if (_defaultInstanceId) {
-                void (async () => {
-                    try {
-                        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 ?? '';
-                        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'] = _defaultInstanceId;
-                            await writeFile(configPath, JSON.stringify(cfg, null, 2), 'utf-8');
-                        }
-                    }
-                    catch { /* non-critical */ }
-                })();
-            }
+            // Persist instance_id to ~/.claude/mcp.json after it's known, so every
+            // restart reuses it instead of making an extra list call on startup.
+            if (_defaultInstanceId)
+                void persistInstanceIdToConfig(_defaultInstanceId);
             return 'done';
         }
         if (data.error === 'slow_down')
@@ -457,10 +466,16 @@ export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp,
 const pool = new Map();
 async function getConnection(instance_id) {
     if (!instance_id) {
-        throw new McpError(ErrorCode.InvalidRequest, 'No instance_id provided and no running instance could be resolved automatically.\n\n' +
+        // With auto-provisioning, this only happens when the API was briefly
+        // unreachable during resolution. The next tool call self-heals, so lead
+        // with "retry" rather than asking the user to configure anything.
+        throw new McpError(ErrorCode.InvalidRequest, '⏳ Your Brain instance is still being set up.\n\n' +
+            'This usually resolves in a few seconds — just call the tool again and it ' +
+            'will connect automatically.\n\n' +
+            'If it keeps happening:\n' +
+            '• Run `list_instances` to check your instances, or\n' +
             '• Set CACHLY_BRAIN_INSTANCE_ID in your MCP config, or\n' +
-            '• Pass instance_id explicitly to the tool, or\n' +
-            '• Run `list_instances` to see your available instances.');
+            '• Reach us at support@cachly.dev.');
     }
     if (pool.has(instance_id))
         return pool.get(instance_id);
@@ -732,7 +747,7 @@ async function handleTool(name, args) {
                 '',
                 'After sign-in: call **any tool again** — your Brain activates instantly.',
                 '',
-                '✨ Free forever · No credit card · 107 MCP tools · GDPR · EU servers',
+                '✨ Free forever · No credit card · 114 MCP tools · GDPR · EU servers',
             ].join('\n');
         }
         // Device flow unavailable (network issue) — fall back to manual setup
@@ -2056,8 +2071,9 @@ if (!process.argv[2] && process.stdout.isTTY) {
     console.log('  cachly gives it a permanent brain — pre-briefed every session.');
     console.log('');
     console.log('  \x1b[1mCommands:\x1b[0m');
-    console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest demo\x1b[0m     ← Start here (no account)');
-    console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest setup\x1b[0m    ← Wire up your AI editors');
+    console.log('  \x1b[1m\x1b[32m  npx @cachly-dev/mcp-server@latest autopilot\x1b[0m ← \x1b[1mOne command, fully ready\x1b[0m');
+    console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest demo\x1b[0m     ← Try it first (no account)');
+    console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest setup\x1b[0m    ← Interactive setup (pick editors)');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest health\x1b[0m   ← Check everything works');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest digest\x1b[0m   ← Weekly Brain summary');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest share\x1b[0m    ← Share your Brain stats');
@@ -2067,7 +2083,7 @@ if (!process.argv[2] && process.stdout.isTTY) {
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest upgrade\x1b[0m  ← Check for updates');
     console.log('');
     console.log('  \x1b[90mWorks with: Claude Code · Cursor · Windsurf · GitHub Copilot · Cline · Zed\x1b[0m');
-    console.log('  \x1b[90mFree forever · GDPR · German servers · 107 MCP tools\x1b[0m');
+    console.log('  \x1b[90mFree forever · GDPR · German servers · 114 MCP tools\x1b[0m');
     console.log('');
     process.exit(0);
 }
@@ -2483,7 +2499,11 @@ if (process.argv[2] === 'health') {
 }
 // ── CLI: cachly setup (interactive — no flags required) ───────────────────────
 // Usage: npx @cachly-dev/mcp-server setup
-if (process.argv[2] === 'setup') {
+// `autopilot` is the one-command entrypoint: it runs the exact same wizard as
+// `setup` but fully automatic (no prompts) — auth → instance → all editor
+// configs → CLAUDE.md → git/starter bootstrap → health, in a single shot.
+const _isAutopilotCli = process.argv[2] === 'autopilot';
+if (process.argv[2] === 'setup' || _isAutopilotCli) {
     const { writeFile, mkdir, readFile } = await import('node:fs/promises');
     const { existsSync } = await import('node:fs');
     const { resolve, dirname } = await import('node:path');
@@ -2502,8 +2522,12 @@ if (process.argv[2] === 'setup') {
     // a readline question against a non-TTY stdin never resolves and hangs the
     // wizard forever. Treat that exactly like --yes so we never block.
     const stdinIsInteractive = process.stdin.isTTY === true;
-    const nonInteractive = process.argv.includes('--yes') || process.argv.includes('-y') || !stdinIsInteractive;
-    if (!stdinIsInteractive && !process.argv.includes('--yes') && !process.argv.includes('-y')) {
+    // `autopilot` is always fully automatic — it IS the one-step onboarding.
+    const nonInteractive = _isAutopilotCli || process.argv.includes('--yes') || process.argv.includes('-y') || !stdinIsInteractive;
+    if (_isAutopilotCli) {
+        console.log('🤖 Autopilot — one-command setup (auth → instance → configs → Brain), zero prompts.\n');
+    }
+    else if (!stdinIsInteractive && !process.argv.includes('--yes') && !process.argv.includes('-y')) {
         console.log('ℹ️  Non-interactive terminal detected — running in automatic mode (no prompts).\n');
     }
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -2872,22 +2896,40 @@ if (process.argv[2] === 'setup') {
     // ── Step 5b: Bootstrap Brain from git history ─────────────────────────────
     // Pre-populates the Brain with real lessons so the first session_start shows
     // actual project knowledge instead of an empty brain.
+    JWT = token; // set global JWT so handleTool can authenticate
+    let gitLessonCount = 0;
     if (existsSync(resolve(cwd, '.git'))) {
         process.stdout.write('⏳ Bootstrapping Brain from git history (~10s)...');
         try {
-            JWT = token; // set global JWT so handleTool can authenticate
             const gitResult = await handleTool('brain_from_git', {
                 instance_id: instance.id,
                 repo_path: cwd,
                 limit: 100,
             });
             const match = gitResult.match(/(\d+) lesson/);
+            gitLessonCount = match ? parseInt(match[1], 10) : 0;
             console.log(` ✓  ${match ? match[1] + ' lessons' : 'done'} extracted from git history`);
         }
         catch (e) {
             console.log(` (skipped: ${e.message.slice(0, 80)})`);
         }
     }
+    // ── Step 5c: Seed the starter corpus when git yielded nothing ─────────────
+    // Closes the empty-brain gap: a fresh repo (no .git, shallow clone, or no
+    // fix-shaped commits) would otherwise leave the Brain empty and the very first
+    // smart_recall returning nothing. Seeding 16 curated universal lessons makes
+    // the single setup command produce an immediately-useful Brain — true 1-step
+    // onboarding. Idempotent; never overwrites real lessons.
+    if (gitLessonCount === 0) {
+        process.stdout.write('🌱 Seeding 16 universal engineering lessons (first recall works instantly)...');
+        try {
+            await handleTool('brain_seed_starter', { instance_id: instance.id });
+            console.log(' ✓');
+        }
+        catch (e) {
+            console.log(` (skipped: ${e.message.slice(0, 60)})`);
+        }
+    }
     // ── Step 6: Show Brain health (Aha moment) ────────────────────────────────
     // Fetch brain health from the API to show the user what their agent will see.
     process.stdout.write('\n⏳ Fetching your Brain health preview...');
@@ -3174,7 +3216,7 @@ if (!JWT) {
 //   • Editor as an MCP stdio server (non-TTY)  → ONE stderr hint, then KEEP RUNNING
 //     so tools/list works and the first tool call starts the browser sign-in.
 // Skip entirely for CLI subcommands that intentionally run without credentials.
-const _cliNoAuthCommands = ['demo', 'share', 'publish', 'health', 'setup', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade', 'tool-specs', 'openapi'];
+const _cliNoAuthCommands = ['demo', 'share', 'publish', 'health', 'setup', 'autopilot', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade', 'tool-specs', 'openapi'];
 if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '')) {
     const runningInTerminal = !process.argv[2] && process.stdout.isTTY === true && _isMain;
     if (runningInTerminal) {