cf-memory-mcp 3.27.0 → 3.29.0

package/bin/cf-memory-mcp.js

@@ -3778,7 +3778,12 @@ if (process.argv.includes('--version') || process.argv.includes('-v')) {
     process.exit(0);
 }
 
-if (process.argv.includes('--help') || process.argv.includes('-h')) {
+// Global --help only when no subcommand is present. With a subcommand, fall
+// through to the per-command help dispatch below.
+const SUBCOMMANDS = new Set(['resume', 'list', 'checkpoint', 'status', 'clean', 'export', 'import', 'doctor', 'completion']);
+const hasSubcommand = process.argv[2] && SUBCOMMANDS.has(process.argv[2]);
+
+if (!hasSubcommand && (process.argv.includes('--help') || process.argv.includes('-h'))) {
     console.log(`
 CF Memory MCP v${PACKAGE_VERSION}
 
@@ -3794,7 +3799,12 @@ Usage:
   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 completion bash Output shell completion script (bash|zsh|fish)
+  npx cf-memory-mcp <cmd> --help    Show flags for a specific command
   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
 
@@ -4000,6 +4010,234 @@ async function runListCli() {
     }
 }
 
+function runCompletionCli() {
+    const shell = process.argv[3] || 'bash';
+    const commands = ['resume', 'list', 'checkpoint', 'status', 'clean', 'export', 'import', 'doctor', 'completion'];
+    const flags = ['--json', '-j', '--limit', '-n', '--md', '--all', '--force', '-f', '--version', '-v', '--help', '-h', '--diagnose'];
+    if (shell === 'bash') {
+        process.stdout.write(`# cf-memory-mcp bash completion
+# Install: cf-memory-mcp completion bash > /usr/local/etc/bash_completion.d/cf-memory-mcp
+# Or for the current shell: source <(cf-memory-mcp completion bash)
+_cf_memory_mcp_complete() {
+    local cur prev words
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    if [ "\$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "${commands.join(' ')}" -- "\$cur") )
+        return 0
+    fi
+    case "\$cur" in
+        --*)
+            COMPREPLY=( $(compgen -W "${flags.filter(f => f.startsWith('--')).join(' ')}" -- "\$cur") )
+            ;;
+    esac
+}
+complete -F _cf_memory_mcp_complete cf-memory-mcp
+complete -F _cf_memory_mcp_complete cfm
+`);
+    } else if (shell === 'zsh') {
+        process.stdout.write(`# cf-memory-mcp zsh completion
+# Install: cf-memory-mcp completion zsh > "\${fpath[1]}/_cf-memory-mcp" && compinit
+# Or for the current shell: source <(cf-memory-mcp completion zsh)
+#compdef cf-memory-mcp cfm
+_cf_memory_mcp() {
+    local -a commands
+    commands=(
+        ${commands.map(c => `'${c}:${c} command'`).join('\n        ')}
+    )
+    if (( CURRENT == 2 )); then
+        _describe 'command' commands
+    else
+        case "\$words[2]" in
+            resume|export) _files ;;
+            import) _files -g '*.json' ;;
+        esac
+    fi
+}
+_cf_memory_mcp "\$@"
+`);
+    } else if (shell === 'fish') {
+        process.stdout.write(`# cf-memory-mcp fish completion
+# Install: cf-memory-mcp completion fish > ~/.config/fish/completions/cf-memory-mcp.fish
+${commands.map(c => `complete -c cf-memory-mcp -n '__fish_use_subcommand' -a '${c}' -d '${c} command'`).join('\n')}
+${commands.map(c => `complete -c cfm -n '__fish_use_subcommand' -a '${c}' -d '${c} command'`).join('\n')}
+complete -c cf-memory-mcp -l json -s j -d 'Emit JSON for scripts'
+complete -c cf-memory-mcp -l limit -s n -d 'Limit number of results'
+complete -c cf-memory-mcp -l md -d 'Write markdown to file'
+complete -c cf-memory-mcp -l force -s f -d 'Bypass duplicate detection'
+complete -c cf-memory-mcp -l help -s h -d 'Show help'
+complete -c cf-memory-mcp -l version -s v -d 'Show version'
+`);
+    } else {
+        process.stderr.write(`Unknown shell "${shell}". Supported: bash, zsh, fish.\n`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+
+// Per-command help texts. Used when "cf-memory-mcp <cmd> --help" is invoked.
+const PER_COMMAND_HELP = {
+    resume: `cf-memory-mcp resume [<session-id-prefix>] [--md path] [--json]
+  Print the prior resume handoff (markdown by default).
+    <session-id-prefix>   Optional: pick a specific session (>=8 char prefix or full UUID).
+    --md <path>           Write the markdown to a file instead of stdout.
+    --json, -j            Emit the full bootstrap payload as JSON for scripts.
+  Exit codes: 0 = handoff found, 3 = no handoff found.`,
+    list: `cf-memory-mcp list [--limit N] [--json]
+  List recent handoffs for the current cwd, status-ranked.
+    --limit N, -n N       Max number of entries (default 5, max 50).
+    --json, -j            Emit a JSON array for scripts.`,
+    checkpoint: `cf-memory-mcp checkpoint ["<goal>"] [--force] [--json]
+  Snapshot current state to a fresh handoff with keep_open:true. The
+  session stays active for future checkpoints. The final end_session (or
+  bridge shutdown) finalizes.
+    <goal>                Explicit goal string. Defaults to synthesized.
+    --force, -f           Bypass duplicate-session detection.
+    --json, -j            Emit a JSON status object.
+  Exit codes: 0 = saved, 2 = not stored, 4 = duplicate detected.`,
+    status: `cf-memory-mcp status [--json]
+  Show bridge + server state for the current cwd: version, repo/branch,
+  disk-cache age, server resume availability, and recent-handoff count.
+    --json, -j            Emit a JSON status object.`,
+    clean: `cf-memory-mcp clean [--all] [--json]
+  Delete the local disk cache for the current cwd.
+    --all                 Delete ALL cf-memory disk caches.
+    --json, -j            Emit a JSON list of removed paths.`,
+    export: `cf-memory-mcp export <session-id-or-prefix> [--md path]
+  Print a handoff as a JSON bundle to stdout (or write to file). For
+  backup or cross-machine sync.
+    <session-id>          Full UUID or short prefix (>=8 chars).
+    --md <path>           Write the JSON to a file.`,
+    import: `cf-memory-mcp import [<file>|-] [--json]
+  Restore a handoff bundle into a NEW session (keep_open). Cross-machine
+  sync. Use "-" to read from stdin.
+    <file>                Bundle file path; "-" for stdin.
+    --json, -j            Emit a JSON status object.`,
+    doctor: `cf-memory-mcp doctor [--json]
+  Diagnose common setup issues. Checks API key, git repo/branch, disk-
+  cache writability, worker reachability, project indexing, resume
+  availability. Exit nonzero if any check fails.
+    --json, -j            Emit a JSON list of checks.`,
+    completion: `cf-memory-mcp completion [bash|zsh|fish]
+  Output shell completion script. Pipe to your shell's completion dir.`,
+};
+
+function printPerCommandHelp(cmd) {
+    const help = PER_COMMAND_HELP[cmd];
+    if (help) {
+        process.stdout.write(help + '\n');
+        process.exit(0);
+    }
+}
+
+async function runDoctorCli() {
+    const { flags } = parseCliArgs(process.argv.slice(3));
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    const checks = [];
+    const add = (label, ok, detail, fix) => checks.push({ label, ok, detail, ...(fix && !ok ? { fix } : {}) });
+
+    // 1. API key set?
+    add('CF_MEMORY_API_KEY set', !!API_KEY,
+        API_KEY ? '(redacted)' : 'unset — most commands will fail',
+        'export CF_MEMORY_API_KEY=<your-key>  # get one at https://memcp.ai');
+
+    // 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',
+        'cd into a repo, or run: git init');
+    add('git branch detected', !!meta.branch,
+        meta.branch || 'detached HEAD or no commits',
+        meta.repo_path ? 'git checkout -b main  # or commit something first' : null);
+
+    // 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}`,
+                `chmod -R u+w ${path.dirname(cachePath)}  # or set CF_MEMORY_DISK_CACHE=off to disable`);
+        }
+    }
+    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`,
+            `curl -I ${BASE_URL}/health  # check the worker URL and your network`);
+
+        // 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',
+                'In your MCP client: call index_project({project_path:"' + (meta.repo_path || process.cwd()) + '"})');
+
+            // 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',
+                        'cf-memory-mcp checkpoint "what you are working on"  # or end_session({handoff:...}) in your MCP client');
+                } 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`);
+        if (!c.ok && c.fix) {
+            process.stdout.write(`      → ${c.fix}\n`);
+        }
+    }
+    process.stdout.write('\n');
+    process.stdout.write(anyFailed ? 'Some checks failed. See suggestions 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');
@@ -4288,12 +4526,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).
@@ -4354,6 +4641,13 @@ async function runCheckpointCli() {
     }
 }
 
+// Per-command --help: intercept BEFORE any subcommand dispatch so the
+// dispatched function doesn't see --help as a positional arg.
+if (process.argv[2] && process.argv.slice(3).some(a => a === '--help' || a === '-h')) {
+    printPerCommandHelp(process.argv[2]);
+    // If not a known command, fall through to general help.
+}
+
 if (process.argv[2] === 'resume') {
     runResumeCli();
     return;
@@ -4389,6 +4683,16 @@ if (process.argv[2] === 'import') {
     return;
 }
 
+if (process.argv[2] === 'doctor') {
+    runDoctorCli();
+    return;
+}
+
+if (process.argv[2] === 'completion') {
+    runCompletionCli();
+    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.27.0",
+	"version": "3.29.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"
 	},