cf-memory-mcp 3.28.0 → 3.30.0

package/bin/cf-memory-mcp.js

@@ -3001,7 +3001,19 @@ class CFMemoryMCP {
                 cwd: process.env.CF_MEMORY_WATCH_PATH || process.cwd(),
                 response_text: text,
             };
-            fs.writeFileSync(p, JSON.stringify(entry, null, 2));
+            // Atomic write: serialize to a sibling .tmp then rename so a
+            // crash mid-write never leaves a corrupt JSON file. rename(2)
+            // is atomic on POSIX. On Windows it may fail if the target
+            // exists, so fall back to a direct write there.
+            const tmp = `${p}.tmp.${process.pid}`;
+            try {
+                fs.writeFileSync(tmp, JSON.stringify(entry, null, 2));
+                fs.renameSync(tmp, p);
+            } catch (renameErr) {
+                // Fallback: direct write. Best-effort cleanup of .tmp.
+                try { fs.unlinkSync(tmp); } catch (_) { /* ignore */ }
+                fs.writeFileSync(p, JSON.stringify(entry, null, 2));
+            }
             _mcpTrace('DISK_CACHE', `saved resume packet to ${p}`);
         } catch (err) {
             this.logDebug(`saveResumeToDisk failed: ${err && err.message}`);
@@ -3778,7 +3790,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}
 
@@ -3795,6 +3812,8 @@ Usage:
   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\`).
@@ -4003,20 +4022,147 @@ 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) => checks.push({ label, ok, detail });
+    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');
+    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');
-    add('git branch detected', !!meta.branch, meta.branch || 'detached HEAD or no commits');
+    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();
@@ -4030,7 +4176,8 @@ async function runDoctorCli() {
             fs.unlinkSync(probe);
             diskWritable = true;
         } catch (err) {
-            add('disk cache writable', false, `failed: ${err.message}`);
+            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));
@@ -4048,14 +4195,18 @@ async function runDoctorCli() {
             workerReachable = !res?.error;
             workerMs = Date.now() - t0;
         } catch (_) { /* unreachable */ }
-        add('worker reachable', workerReachable, workerReachable ? `${workerMs}ms` : `failed`);
+        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');
+            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) {
@@ -4073,7 +4224,8 @@ async function runDoctorCli() {
                     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');
+                            : 'none for this context',
+                        'cf-memory-mcp checkpoint "what you are working on"  # or end_session({handoff:...}) in your MCP client');
                 } catch (_) { /* skip */ }
             }
         }
@@ -4089,9 +4241,12 @@ async function runDoctorCli() {
         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 details above.\n' : 'All checks passed.\n');
+    process.stdout.write(anyFailed ? 'Some checks failed. See suggestions above.\n' : 'All checks passed.\n');
     process.exit(anyFailed ? 1 : 0);
 }
 
@@ -4498,6 +4653,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;
@@ -4538,6 +4700,11 @@ if (process.argv[2] === 'doctor') {
     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,6 +1,6 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.28.0",
+	"version": "3.30.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": {