cf-memory-mcp 3.26.0 → 3.28.0

package/bin/cf-memory-mcp.js

@@ -3792,7 +3792,12 @@ Usage:
   npx cf-memory-mcp status          Show bridge state + server resume availability
   npx cf-memory-mcp clean           Delete local disk cache for current cwd
   npx cf-memory-mcp clean --all     Delete ALL local disk caches
+  npx cf-memory-mcp export <id>     Print a session's handoff as JSON bundle (backup)
+  npx cf-memory-mcp import <file>   Restore a handoff bundle (cross-machine sync); use "-" for stdin
+  npx cf-memory-mcp doctor          Diagnose common setup issues
   npx cf-memory-mcp --version       Show version
+
+Short alias: \`cfm\` works as a drop-in for \`cf-memory-mcp\` (e.g., \`cfm resume\`).
   npx cf-memory-mcp --help          Show this help
   npx cf-memory-mcp --diagnose      Test connectivity and report issues
 
@@ -3998,6 +4003,245 @@ async function runListCli() {
     }
 }
 
+async function runDoctorCli() {
+    const { flags } = parseCliArgs(process.argv.slice(3));
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    const checks = [];
+    const add = (label, ok, detail) => checks.push({ label, ok, detail });
+
+    // 1. API key set?
+    add('CF_MEMORY_API_KEY set', !!API_KEY, API_KEY ? '(redacted)' : 'unset — most commands will fail');
+
+    // 2. Cwd is in a git repo?
+    const meta = server.getRepoMetadata();
+    add('git repo detected', !!meta.repo_path, meta.repo_path || 'no .git in cwd; resume metadata will be empty');
+    add('git branch detected', !!meta.branch, meta.branch || 'detached HEAD or no commits');
+
+    // 3. Disk cache writable?
+    const cachePath = server.getDiskCachePath();
+    let diskWritable = false;
+    if (cachePath) {
+        try {
+            const dir = path.dirname(cachePath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            const probe = path.join(dir, '.doctor-probe');
+            fs.writeFileSync(probe, 'ok');
+            fs.unlinkSync(probe);
+            diskWritable = true;
+        } catch (err) {
+            add('disk cache writable', false, `failed: ${err.message}`);
+        }
+    }
+    if (diskWritable) add('disk cache writable', true, path.dirname(cachePath));
+
+    // 4. Worker reachable?
+    if (API_KEY) {
+        const t0 = Date.now();
+        let workerReachable = false;
+        let workerMs = null;
+        try {
+            const res = await server.makeRequestOnce({
+                jsonrpc: '2.0', id: `doctor-${Date.now()}`,
+                method: 'tools/call', params: { name: 'health_check', arguments: {} },
+            });
+            workerReachable = !res?.error;
+            workerMs = Date.now() - t0;
+        } catch (_) { /* unreachable */ }
+        add('worker reachable', workerReachable, workerReachable ? `${workerMs}ms` : `failed`);
+
+        // 5. Project indexed?
+        if (workerReachable) {
+            const fake = { params: { name: 'retrieve_context', arguments: {} } };
+            await server.maybeFillProjectId(fake);
+            const pid = fake.params.arguments.project_id;
+            add('project indexed', !!pid, pid || 'no project matched cwd — run index_project to enable retrieve_context');
+
+            // 6. Resume handoff available?
+            if (meta.repo_path) {
+                const probeArgs = { resume: true, repo_path: meta.repo_path };
+                if (meta.branch) probeArgs.branch = meta.branch;
+                if (pid) probeArgs.project_id = pid;
+                try {
+                    const probeRes = await server.makeRequestOnce({
+                        jsonrpc: '2.0', id: `doctor-resume-${Date.now()}`,
+                        method: 'tools/call', params: { name: 'get_context_bootstrap', arguments: probeArgs },
+                    });
+                    const probeText = probeRes?.result?.content?.[0]?.text;
+                    const probePayload = JSON.parse(probeText || '{}');
+                    const hasHandoff = !!probePayload.resume_handoff;
+                    add('resume handoff available', hasHandoff,
+                        hasHandoff
+                            ? `${(probePayload.resume_handoff.session_id||'').slice(0,8)} (${probePayload.resume_handoff.handoff_age_minutes}m old)`
+                            : 'none for this context');
+                } catch (_) { /* skip */ }
+            }
+        }
+    }
+
+    if (flags.json) {
+        process.stdout.write(JSON.stringify({ checks }, null, 2) + '\n');
+        process.exit(checks.every(c => c.ok) ? 0 : 1);
+    }
+    process.stdout.write(`cf-memory-mcp v${PACKAGE_VERSION} — doctor\n\n`);
+    let anyFailed = false;
+    for (const c of checks) {
+        const mark = c.ok ? '✓' : '✗';
+        if (!c.ok) anyFailed = true;
+        process.stdout.write(`  ${mark} ${c.label.padEnd(28)} ${c.detail || ''}\n`);
+    }
+    process.stdout.write('\n');
+    process.stdout.write(anyFailed ? 'Some checks failed. See details above.\n' : 'All checks passed.\n');
+    process.exit(anyFailed ? 1 : 0);
+}
+
+async function runExportCli() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const { positional, flags } = parseCliArgs(process.argv.slice(3));
+    const sessionArg = positional[0];
+    if (!sessionArg) {
+        console.error('Usage: cf-memory-mcp export <session-id-or-prefix> [--md path]');
+        process.exit(1);
+    }
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    try {
+        const args = { resume: true, session_id_hint: sessionArg };
+        const response = await server.makeRequest({
+            jsonrpc: '2.0',
+            id: `cli-export-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'get_context_bootstrap', arguments: args },
+        });
+        const text = response?.result?.content?.[0]?.text;
+        const payload = JSON.parse(text || '{}');
+        const envelope = payload.resume_handoff;
+        if (!envelope?.handoff) {
+            process.stderr.write((payload.empty_hint || `No handoff found for "${sessionArg}".`) + '\n');
+            process.exit(3);
+        }
+        // Build an exportable bundle: enough to fully reconstruct via import.
+        const bundle = {
+            kind: 'cf-memory-handoff',
+            version: 1,
+            exported_at: new Date().toISOString(),
+            session_id: envelope.session_id,
+            started_at: envelope.started_at,
+            ended_at: envelope.ended_at,
+            handoff: envelope.handoff,
+        };
+        const output = JSON.stringify(bundle, null, 2);
+        if (flags.md_path) {
+            fs.writeFileSync(flags.md_path, output);
+            process.stdout.write(`Wrote ${output.length} bytes to ${flags.md_path}\n`);
+        } else {
+            process.stdout.write(output + '\n');
+        }
+        process.exit(0);
+    } catch (err) {
+        console.error('export command failed:', err.message);
+        process.exit(1);
+    }
+}
+
+async function runImportCli() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const { positional, flags } = parseCliArgs(process.argv.slice(3));
+    const sourcePath = positional[0];
+    let raw;
+    try {
+        if (sourcePath === '-' || sourcePath === undefined) {
+            // Read from stdin so `cat handoff.json | cf-memory-mcp import` works.
+            raw = fs.readFileSync(0, 'utf8'); // fd 0 = stdin
+        } else {
+            raw = fs.readFileSync(sourcePath, 'utf8');
+        }
+    } catch (err) {
+        console.error('import: cannot read input:', err.message);
+        process.exit(1);
+    }
+    let bundle;
+    try { bundle = JSON.parse(raw); } catch (err) {
+        console.error('import: input is not valid JSON:', err.message);
+        process.exit(1);
+    }
+    if (bundle.kind !== 'cf-memory-handoff' || !bundle.handoff) {
+        console.error('import: input is not a cf-memory-handoff bundle (expected kind="cf-memory-handoff" + handoff field).');
+        process.exit(1);
+    }
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    try {
+        // Imports always create a fresh session and write the imported
+        // handoff to it. The original session_id is preserved in
+        // handoff.notes so the link to the source isn't lost.
+        const meta = server.getRepoMetadata();
+        const startArgs = { context: 'main' };
+        if (meta.repo_path) startArgs.repo_path = meta.repo_path;
+        if (meta.branch) startArgs.branch = meta.branch;
+        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+        await server.maybeFillProjectId(fake);
+        if (fake.params.arguments.project_id) startArgs.project_id = fake.params.arguments.project_id;
+
+        const startRes = await server.makeRequest({
+            jsonrpc: '2.0', id: `cli-import-start-${Date.now()}`,
+            method: 'tools/call', params: { name: 'start_session', arguments: startArgs },
+        });
+        const startText = startRes?.result?.content?.[0]?.text;
+        const startPayload = JSON.parse(startText || '{}');
+        const newSessionId = startPayload.session_id;
+        if (!newSessionId) {
+            console.error('import: failed to create new session:', startText);
+            process.exit(1);
+        }
+
+        // Build the handoff: take the imported one, append import note.
+        const importNote = `[imported from session ${bundle.session_id} on ${new Date().toISOString()}; originally started ${bundle.started_at}]`;
+        const handoff = { ...bundle.handoff };
+        handoff.notes = handoff.notes ? `${handoff.notes}\n\n${importNote}` : importNote;
+        // Fill repo metadata from current context if the imported handoff
+        // didn't specify (cross-machine sync use case).
+        if (!handoff.repo_path && meta.repo_path) handoff.repo_path = meta.repo_path;
+        if (!handoff.branch && meta.branch) handoff.branch = meta.branch;
+        if (!handoff.project_id && fake.params.arguments.project_id) handoff.project_id = fake.params.arguments.project_id;
+
+        const endRes = await server.makeRequest({
+            jsonrpc: '2.0', id: `cli-import-end-${Date.now()}`,
+            method: 'tools/call', params: { name: 'end_session', arguments: {
+                session_id: newSessionId,
+                keep_open: true,
+                handoff,
+            } },
+        });
+        const endText = endRes?.result?.content?.[0]?.text;
+        const endPayload = JSON.parse(endText || '{}');
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({
+                imported_from: bundle.session_id,
+                new_session_id: newSessionId,
+                short_id: newSessionId.slice(0, 8),
+                handoff_stored: !!endPayload.handoff_stored,
+                resume_command: `npx cf-memory-mcp resume ${newSessionId.slice(0, 8)}`,
+            }, null, 2) + '\n');
+        } else {
+            process.stdout.write(`Imported handoff into session ${newSessionId.slice(0, 8)} (kept_open).\n`);
+            process.stdout.write(`Original: ${bundle.session_id}\n`);
+            process.stdout.write(`Goal: ${handoff.goal}\n`);
+            process.stdout.write(`To resume: npx cf-memory-mcp resume ${newSessionId.slice(0, 8)}\n`);
+        }
+        process.exit(endPayload.handoff_stored ? 0 : 2);
+    } catch (err) {
+        console.error('import command failed:', err.message);
+        process.exit(1);
+    }
+}
+
 async function runCleanCli() {
     const { flags, positional } = parseCliArgs(process.argv.slice(3));
     const all = positional.includes('--all') || process.argv.includes('--all');
@@ -4139,12 +4383,61 @@ async function runCheckpointCli() {
         process.exit(1);
     }
     const { positional, flags } = parseCliArgs(process.argv.slice(3));
+    const force = process.argv.includes('--force') || process.argv.includes('-f');
     const server = new CFMemoryMCP();
     server.logDebug = () => {};
     server.logError = (...a) => process.stderr.write(a.join(' ') + '\n');
     try {
         // Optional positional goal argument: `cf-memory-mcp checkpoint "<goal text>"`
-        const goalArg = positional.join(' ').trim();
+        const goalArg = positional.filter(p => p !== '--force' && p !== '-f').join(' ').trim();
+
+        // Duplicate detection: before creating a new implicit session,
+        // check if there's a recent in_progress handoff for the same
+        // repo/branch. If so, suggest resuming it instead of churning a
+        // new one. Skipped with --force.
+        if (!force) {
+            const meta = server.getRepoMetadata();
+            if (meta.repo_path) {
+                const probeArgs = { resume: true, repo_path: meta.repo_path, status_filter: 'in_progress', max_age_minutes: 60 };
+                if (meta.branch) probeArgs.branch = meta.branch;
+                try {
+                    const probeRes = await server.makeRequest({
+                        jsonrpc: '2.0',
+                        id: `cli-checkpoint-probe-${Date.now()}`,
+                        method: 'tools/call',
+                        params: { name: 'get_context_bootstrap', arguments: probeArgs },
+                    });
+                    const probeText = probeRes?.result?.content?.[0]?.text;
+                    const probePayload = JSON.parse(probeText || '{}');
+                    const recent = probePayload.resume_handoff;
+                    // Same-cwd implicit session won't be in the worker yet
+                    // unless someone called start_session — we look for
+                    // OTHER active threads on the same repo.
+                    if (recent) {
+                        const shortId = (recent.session_id || '').slice(0, 8);
+                        const ageMin = recent.handoff_age_minutes ?? '?';
+                        const status = recent.handoff?.status || '?';
+                        if (flags.json) {
+                            process.stdout.write(JSON.stringify({
+                                duplicate_detected: true,
+                                existing_session_id: recent.session_id,
+                                existing_short_id: shortId,
+                                existing_age_minutes: ageMin,
+                                existing_status: status,
+                                existing_goal: recent.handoff?.goal,
+                                hint: `Resume the existing in_progress session instead: cf-memory-mcp resume ${shortId}. Re-run with --force to create a new session anyway.`,
+                            }, null, 2) + '\n');
+                            process.exit(4);
+                        }
+                        process.stderr.write(`There's already an in_progress handoff for this repo:\n`);
+                        process.stderr.write(`  ${shortId}  ${status}  ${ageMin}m ago — "${recent.handoff?.goal || '(no goal)'}"\n`);
+                        process.stderr.write(`Resume it: cf-memory-mcp resume ${shortId}\n`);
+                        process.stderr.write(`Or re-run with --force to create a new session anyway.\n`);
+                        process.exit(4);
+                    }
+                } catch (_) { /* probe failure is non-fatal */ }
+            }
+        }
         const meta = server.getRepoMetadata();
         // Need a session to attach the handoff to. Use or create the
         // implicit session for this cwd (creates a new one if no implicit).
@@ -4230,6 +4523,21 @@ if (process.argv[2] === 'clean') {
     return;
 }
 
+if (process.argv[2] === 'export') {
+    runExportCli();
+    return;
+}
+
+if (process.argv[2] === 'import') {
+    runImportCli();
+    return;
+}
+
+if (process.argv[2] === 'doctor') {
+    runDoctorCli();
+    return;
+}
+
 if (process.argv.includes('--diagnose')) {
     (async () => {
         console.log(`CF Memory MCP v${PACKAGE_VERSION} - Diagnostics`);

package/package.json

@@ -1,10 +1,11 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.26.0",
+	"version": "3.28.0",
 	"description": "Cloudflare-hosted MCP server for code indexing, retrieval, and assistant memory with a direct remote MCP endpoint and local stdio bridge.",
 	"main": "bin/cf-memory-mcp.js",
 	"bin": {
 		"cf-memory-mcp": "bin/cf-memory-mcp.js",
+		"cfm": "bin/cf-memory-mcp.js",
 		"cf-memory-index": "bin/cf-memory-mcp-indexer.js",
 		"cf-memory-watch": "bin/cf-memory-mcp-indexer.js"
 	},