Merge pull request #17 from ngallodev/feat/legacy-mcp-block-warning

feat(cli): warn about legacy codebase-memory-mcp instruction blocks

Author: ngallodev

docs/CONFIGURATION.md

@@ -195,7 +195,7 @@ not name is permitted.
 
 ## 5. Agent and Editor Integration Files
 
-The CLI-first `install` path can write Codebase Memory skills and durable CLI instructions for detected agents. Hooks are a separate explicit opt-in via `codebase-memory-cli install-hooks`. Neither lifecycle surface creates, migrates, adopts, or removes MCP registrations or MCP-owned assets; existing MCP state is treated as foreign for side-by-side safety.
+The CLI-first `install` path can write Codebase Memory skills and durable CLI instructions for detected agents. Hooks are a separate explicit opt-in via `codebase-memory-cli install-hooks`. Neither lifecycle surface creates, migrates, adopts, or removes MCP registrations or MCP-owned assets; existing MCP state is treated as foreign for side-by-side safety. Both `install` and `uninstall` warn when an instruction file still contains a legacy `codebase-memory-mcp` managed block from the upstream MCP tool, but they leave that block in place for you to remove by hand.
 
 Those target paths vary by tool and platform, so the easiest way to inspect the exact files for your machine is:
 

src/cli/cli.c

@@ -3229,6 +3229,40 @@ int cbm_remove_instructions(const char *path) {
                                                                                       : CLI_ERR;
 }
 
+/* Upstream codebase-memory-mcp wrote its own managed instruction blocks. The
+ * fork's CP78 side-by-side policy treats that MCP state as foreign, so install
+ * and uninstall never rewrite or remove it — but the block still points at MCP
+ * tools this CLI-only fork does not provide, so warn once per file. Read-only:
+ * this never modifies the file. */
+#define LEGACY_MCP_MARKER_START "<!-- codebase-memory-mcp:start -->"
+#define LEGACY_MCP_MARKER_END "<!-- codebase-memory-mcp:end -->"
+
+static bool cbm_file_has_legacy_mcp_block(const char *path) {
+    if (!path || !path[0]) {
+        return false;
+    }
+    char *content = read_file_str(path, NULL);
+    if (!content) {
+        return false;
+    }
+    const char *begin = strstr(content, LEGACY_MCP_MARKER_START);
+    bool complete = begin != NULL &&
+                    strstr(begin + strlen(LEGACY_MCP_MARKER_START), LEGACY_MCP_MARKER_END) != NULL;
+    free(content);
+    return complete;
+}
+
+static void cbm_warn_legacy_mcp_block(const char *path) {
+    if (!cbm_file_has_legacy_mcp_block(path)) {
+        return;
+    }
+    (void)fprintf(stderr,
+                  "  warning: %s still contains a legacy codebase-memory-mcp instruction block; "
+                  "it refers to MCP tools that codebase-memory-cli does not provide. Remove it "
+                  "manually if it is no longer wanted.\n",
+                  path);
+}
+
 /* ── Codex MCP config (TOML) ─────────────────────────────────── */
 
 #define CODEX_CMM_TABLE "mcp_servers.codebase-memory-mcp"
@@ -7816,13 +7850,17 @@ static bool install_generic_agent_config(const char *label, const char *instr_pa
     if (g_install_plan) {
         if (instr_path) {
             plan_record(label, "instructions", instr_path);
+            if (cbm_file_has_legacy_mcp_block(instr_path)) {
+                plan_record(label, "warning", instr_path);
+            }
         }
         return true;
     }
     printf("%s:\n", label);
     printf("  integration: CLI instructions only; hooks require `codebase-memory-cli "
            "install-hooks`\n");
     if (instr_path) {
+        cbm_warn_legacy_mcp_block(instr_path);
         if (!dry_run) {
             if (!prepare_config_parent(instr_path) ||
                 cbm_upsert_instructions(instr_path, agent_instructions_content) != CLI_OK) {
@@ -9518,6 +9556,7 @@ static char *cbm_build_install_plan_json_options(const char *home, const char *b
     yyjson_mut_val *agent_files = yyjson_mut_arr(doc);
     yyjson_mut_val *prompt_files = yyjson_mut_arr(doc);
     yyjson_mut_val *hooks = yyjson_mut_arr(doc);
+    yyjson_mut_val *warnings = yyjson_mut_arr(doc);
     for (int i = 0; i < plan.count; i++) {
         cbm_plan_entry_t *e = &plan.items[i];
         if (strcmp(e->kind, "config") == 0 || strcmp(e->kind, "mcp_config") == 0) {
@@ -9536,6 +9575,8 @@ static char *cbm_build_install_plan_json_options(const char *home, const char *b
         } else if (strcmp(e->kind, "prompt") == 0) {
             yyjson_mut_arr_add_strcpy(doc, prompt_files, e->path);
             yyjson_mut_arr_add_strcpy(doc, instrs, e->path);
+        } else if (strcmp(e->kind, "warning") == 0) {
+            yyjson_mut_arr_add_strcpy(doc, warnings, e->path);
         } else {
             yyjson_mut_arr_add_strcpy(doc, instrs, e->path);
         }
@@ -9546,6 +9587,7 @@ static char *cbm_build_install_plan_json_options(const char *home, const char *b
     yyjson_mut_obj_add_val(doc, root, "agent_files_planned", agent_files);
     yyjson_mut_obj_add_val(doc, root, "prompt_files_planned", prompt_files);
     yyjson_mut_obj_add_val(doc, root, "hooks_planned", hooks);
+    yyjson_mut_obj_add_val(doc, root, "warnings", warnings);
     yyjson_mut_obj_add_bool(doc, root, "writes_started", false);
     yyjson_mut_obj_add_bool(doc, root, "network_after_install", false);
     yyjson_mut_obj_add_str(doc, root, "next_safe_command",
@@ -10258,6 +10300,7 @@ static void uninstall_agent_mcp_instr(mcp_uninstall_args_t paths, bool dry_run,
     const char *instr_path = paths.instr_path;
     printf("%s: preserved MCP config by CP78 side-by-side policy\n", name);
     if (instr_path) {
+        cbm_warn_legacy_mcp_block(instr_path);
         if (!dry_run && cbm_remove_instructions(instr_path) != CLI_OK) {
             record_agent_config_error(true, name, "instructions_uninstall", instr_path);
         }

tests/test_cli.c

@@ -7349,6 +7349,99 @@ TEST(cli_codex_respects_codex_home) {
     PASS();
 }
 
+TEST(cli_install_warns_about_legacy_mcp_instruction_block) {
+    char tmpdir[256];
+    snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-codex-legacy-mcp-XXXXXX");
+    if (!cbm_mkdtemp(tmpdir))
+        FAIL("cbm_mkdtemp failed");
+
+    char codex_home[512];
+    char agents_path[640];
+    char binary_path[768];
+    snprintf(codex_home, sizeof(codex_home), "%s/.codex", tmpdir);
+    snprintf(agents_path, sizeof(agents_path), "%s/AGENTS.md", codex_home);
+#ifdef _WIN32
+    snprintf(binary_path, sizeof(binary_path), "%s/.local/bin/codebase-memory-cli.exe", tmpdir);
+#else
+    snprintf(binary_path, sizeof(binary_path), "%s/.local/bin/codebase-memory-cli", tmpdir);
+#endif
+    ASSERT_EQ(test_mkdirp(codex_home), 0);
+
+    const char *user_guidance = "# Personal Codex guidance\nKeep this byte-for-byte.\n";
+    const char *legacy_block = "<!-- codebase-memory-mcp:start -->\n"
+                               "Call search_graph and trace_path.\n"
+                               "<!-- codebase-memory-mcp:end -->\n";
+    char seeded[2048];
+    snprintf(seeded, sizeof(seeded), "%s%s", user_guidance, legacy_block);
+    ASSERT_EQ(write_test_file(agents_path, seeded), 0);
+
+    char *saved_home = save_test_env("HOME");
+    char *saved_path = save_test_env("PATH");
+    char *saved_codex = save_test_env("CODEX_HOME");
+    cbm_setenv("HOME", tmpdir, 1);
+    cbm_setenv("PATH", tmpdir, 1);
+    cbm_setenv("CODEX_HOME", codex_home, 1);
+
+    /* A dry run warns and writes nothing. */
+#ifndef _WIN32
+    cli_fd_capture_t dry_capture;
+    cli_fd_capture_begin(&dry_capture, stderr, STDERR_FILENO);
+#endif
+    int dry_rc = cbm_install_agent_configs(tmpdir, binary_path, false, true);
+#ifndef _WIN32
+    char *dry_err = cli_fd_capture_end(&dry_capture);
+#else
+    char *dry_err = NULL;
+#endif
+    char *after_dry = read_test_file_alloc(agents_path);
+    bool dry_preserved = after_dry && strcmp(after_dry, seeded) == 0;
+    bool dry_warned = true;
+#ifndef _WIN32
+    dry_warned =
+        dry_err && strstr(dry_err, agents_path) != NULL &&
+        strstr(dry_err, "still contains a legacy codebase-memory-mcp instruction block") != NULL;
+#endif
+    free(after_dry);
+    free(dry_err);
+
+    /* A real install warns, leaves the legacy bytes intact, and adds our block once. */
+#ifndef _WIN32
+    cli_fd_capture_t install_capture;
+    cli_fd_capture_begin(&install_capture, stderr, STDERR_FILENO);
+#endif
+    int install_rc = cbm_install_agent_configs(tmpdir, binary_path, false, false);
+#ifndef _WIN32
+    char *install_err = cli_fd_capture_end(&install_capture);
+#else
+    char *install_err = NULL;
+#endif
+    char *after = read_test_file_alloc(agents_path);
+    bool legacy_preserved = after && strstr(after, legacy_block) != NULL;
+    bool user_preserved = after && strstr(after, user_guidance) != NULL;
+    bool cli_block_added_once =
+        after && test_count_substring(after, test_cli_managed_block_start) == 1U;
+    bool install_warned = true;
+#ifndef _WIN32
+    install_warned =
+        install_err && strstr(install_err, agents_path) != NULL &&
+        strstr(install_err, "still contains a legacy codebase-memory-mcp instruction block") !=
+            NULL;
+#endif
+
+    free(after);
+    free(install_err);
+    restore_test_env("HOME", saved_home);
+    restore_test_env("PATH", saved_path);
+    restore_test_env("CODEX_HOME", saved_codex);
+    test_rmdir_r(tmpdir);
+
+    if (dry_rc != 0 || install_rc != 0 || !dry_preserved || !dry_warned || !legacy_preserved ||
+        !user_preserved || !cli_block_added_once || !install_warned)
+        FAIL("Codex install must warn about a legacy codebase-memory-mcp block in --dry-run and "
+             "on install, keep its bytes and the user's, and add one CLI managed block");
+    PASS();
+}
+
 TEST(cli_codex_install_manages_global_instruction_block_issue1689) {
     char tmpdir[256];
     snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-codex-agents-pointer-XXXXXX");
@@ -13533,6 +13626,7 @@ SUITE(cli) {
     RUN_TEST(cli_registry_installs_codebuddy_bob_and_pochi_durable_context);
     RUN_TEST(cli_openclaw_resolves_active_json5_workspace);
     RUN_TEST(cli_codex_respects_codex_home);
+    RUN_TEST(cli_install_warns_about_legacy_mcp_instruction_block);
     RUN_TEST(cli_grok_respects_grok_home);
     RUN_TEST(cli_codex_install_manages_global_instruction_block_issue1689);
     RUN_TEST(cli_gemini_session_hook_uses_json_for_all_sources);