Skip to content

Commit 4c38c5a

Browse files
author
Martin Vogel
committed
feat(install): add install --plan machine-readable receipt (#388)
An installer that configures MCP entries, instruction files, Skills, and hooks across many agents should let callers see what it will mutate before it does. `--dry-run` already lists planned writes in human-readable form; this adds the machine-readable `agent.install.plan.v1` JSON receipt the issue asked for. `install --plan` runs the real install dispatch in record-only mode — a global g_install_plan recorder that each write-site function appends to (at the same point it would write) while all mutations are disabled — then emits JSON with agents_detected, config_files_planned, instruction_files_planned, hooks_planned, writes_started:false, network_after_install:false, and next_safe_command. Because the plan is recorded on the actual install code path, it cannot drift from real behavior. No config is written, no index deleted, no network used. cbm_build_install_plan_json is exposed for testing; the test asserts the receipt content AND that building it creates no config files.
1 parent 70e3ed7 commit 4c38c5a

3 files changed

Lines changed: 220 additions & 5 deletions

File tree

‎src/cli/cli.c‎

Lines changed: 176 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2768,6 +2768,45 @@ static void print_detected_agents(const cbm_detected_agents_t *a) {
27682768
}
27692769

27702770
/* Install Claude Code-specific configs (skills, MCP, hooks). */
2771+
/* ── Install plan recorder (issue #388) ────────────────────────────
2772+
* When g_install_plan != NULL, the install path runs as a dry-run and each
2773+
* write site records its planned target HERE — at the same point it would
2774+
* perform the write — so the emitted plan cannot drift from actual install
2775+
* behavior (it is the same code path with mutations disabled). */
2776+
typedef struct {
2777+
char agent[CLI_BUF_32];
2778+
char kind[CLI_BUF_32]; /* mcp_config | instructions | skills | hook */
2779+
char path[CLI_BUF_1K];
2780+
} cbm_plan_entry_t;
2781+
2782+
typedef struct {
2783+
cbm_plan_entry_t *items;
2784+
int count;
2785+
int cap;
2786+
} cbm_install_plan_t;
2787+
2788+
static cbm_install_plan_t *g_install_plan = NULL;
2789+
2790+
static void plan_record(const char *agent, const char *kind, const char *path) {
2791+
if (!g_install_plan || !path || !path[0]) {
2792+
return;
2793+
}
2794+
cbm_install_plan_t *pl = g_install_plan;
2795+
if (pl->count >= pl->cap) {
2796+
int ncap = pl->cap ? pl->cap * 2 : CLI_BUF_16;
2797+
cbm_plan_entry_t *ni = realloc(pl->items, (size_t)ncap * sizeof(*ni));
2798+
if (!ni) {
2799+
return;
2800+
}
2801+
pl->items = ni;
2802+
pl->cap = ncap;
2803+
}
2804+
cbm_plan_entry_t *e = &pl->items[pl->count++];
2805+
snprintf(e->agent, sizeof(e->agent), "%s", agent);
2806+
snprintf(e->kind, sizeof(e->kind), "%s", kind);
2807+
snprintf(e->path, sizeof(e->path), "%s", path);
2808+
}
2809+
27712810
static void install_claude_code_config(const char *home, const char *binary_path, bool force,
27722811
bool dry_run) {
27732812
char config_dir[CLI_BUF_1K];
@@ -2777,6 +2816,24 @@ static void install_claude_code_config(const char *home, const char *binary_path
27772816

27782817
char skills_dir[CLI_BUF_1K];
27792818
snprintf(skills_dir, sizeof(skills_dir), "%s/skills", config_dir);
2819+
2820+
/* Plan mode: record the planned writes and return without mutating (#388). */
2821+
if (g_install_plan) {
2822+
char p[CLI_BUF_1K];
2823+
plan_record("Claude Code", "skills", skills_dir);
2824+
snprintf(p, sizeof(p), "%s/.mcp.json", config_dir);
2825+
plan_record("Claude Code", "mcp_config", p);
2826+
snprintf(p, sizeof(p), "%s/.claude.json", user_root);
2827+
plan_record("Claude Code", "mcp_config", p);
2828+
snprintf(p, sizeof(p), "%s/settings.json", config_dir);
2829+
plan_record("Claude Code", "mcp_config", p);
2830+
snprintf(p, sizeof(p), "%s/hooks/%s", config_dir, CMM_HOOK_GATE_SCRIPT);
2831+
plan_record("Claude Code", "hook", p);
2832+
snprintf(p, sizeof(p), "%s/hooks/%s", config_dir, CMM_SESSION_REMINDER_SCRIPT);
2833+
plan_record("Claude Code", "hook", p);
2834+
return;
2835+
}
2836+
27802837
printf("Claude Code:\n");
27812838

27822839
int skill_count = cbm_install_skills(skills_dir, force, dry_run);
@@ -2831,6 +2888,14 @@ static void install_generic_agent_config(const char *label, const char *binary_p
28312888
const char *config_path, const char *instr_path,
28322889
bool dry_run,
28332890
int (*install_mcp)(const char *, const char *)) {
2891+
/* Plan mode: record planned writes, mutate nothing (#388). */
2892+
if (g_install_plan) {
2893+
plan_record(label, "mcp_config", config_path);
2894+
if (instr_path) {
2895+
plan_record(label, "instructions", instr_path);
2896+
}
2897+
return;
2898+
}
28342899
printf("%s:\n", label);
28352900
if (!dry_run) {
28362901
install_mcp(binary_path, config_path);
@@ -2853,6 +2918,9 @@ static void install_gemini_config(const char *home, const char *binary_path, boo
28532918
snprintf(ip, sizeof(ip), "%s/.gemini/GEMINI.md", home);
28542919
install_generic_agent_config("Gemini CLI", binary_path, cp, ip, dry_run,
28552920
cbm_install_editor_mcp);
2921+
if (g_install_plan) {
2922+
return; /* config recorded by install_generic_agent_config above */
2923+
}
28562924
if (!dry_run) {
28572925
cbm_upsert_gemini_hooks(cp);
28582926
}
@@ -2891,11 +2959,15 @@ static void install_cli_agent_configs(const cbm_detected_agents_t *agents, const
28912959
if (agents->aider) {
28922960
char ip[CLI_BUF_1K];
28932961
snprintf(ip, sizeof(ip), "%s/CONVENTIONS.md", home);
2894-
printf("Aider:\n");
2895-
if (!dry_run) {
2896-
cbm_upsert_instructions(ip, agent_instructions_content);
2962+
if (g_install_plan) {
2963+
plan_record("Aider", "instructions", ip);
2964+
} else {
2965+
printf("Aider:\n");
2966+
if (!dry_run) {
2967+
cbm_upsert_instructions(ip, agent_instructions_content);
2968+
}
2969+
printf(" instructions: %s\n", ip);
28972970
}
2898-
printf(" instructions: %s\n", ip);
28992971
}
29002972
}
29012973

@@ -2968,7 +3040,9 @@ static void install_editor_agent_configs(const cbm_detected_agents_t *agents, co
29683040
static void cbm_install_agent_configs(const char *home, const char *binary_path, bool force,
29693041
bool dry_run) {
29703042
cbm_detected_agents_t agents = cbm_detect_agents(home);
2971-
print_detected_agents(&agents);
3043+
if (!g_install_plan) {
3044+
print_detected_agents(&agents);
3045+
}
29723046

29733047
if (agents.claude_code) {
29743048
install_claude_code_config(home, binary_path, force, dry_run);
@@ -3027,17 +3101,98 @@ static void cbm_detect_self_path(char *buf, size_t buf_sz, const char *home) {
30273101
}
30283102
}
30293103

3104+
/* Build the agent.install.plan.v1 receipt (#388): a machine-readable list of
3105+
* the config / instruction / hook files `install` WOULD write, produced by
3106+
* running the real install dispatch in record-only mode (no mutation, no
3107+
* network). Returns a heap JSON string (caller frees) or NULL. */
3108+
char *cbm_build_install_plan_json(const char *home, const char *binary_path) {
3109+
if (!home || !binary_path) {
3110+
return NULL;
3111+
}
3112+
3113+
/* Same code path as a real install, but mutations disabled and every write
3114+
* site records into `plan` — so the receipt cannot drift from behavior. */
3115+
cbm_install_plan_t plan = {0};
3116+
g_install_plan = &plan;
3117+
cbm_install_agent_configs(home, binary_path, false, true);
3118+
g_install_plan = NULL;
3119+
3120+
cbm_detected_agents_t det = cbm_detect_agents(home);
3121+
struct {
3122+
bool flag;
3123+
const char *name;
3124+
} names[] = {
3125+
{det.claude_code, "claude-code"},
3126+
{det.codex, "codex"},
3127+
{det.gemini, "gemini"},
3128+
{det.zed, "zed"},
3129+
{det.opencode, "opencode"},
3130+
{det.antigravity, "antigravity"},
3131+
{det.aider, "aider"},
3132+
{det.kilocode, "kilocode"},
3133+
{det.vscode, "vscode"},
3134+
{det.cursor, "cursor"},
3135+
{det.openclaw, "openclaw"},
3136+
{det.kiro, "kiro"},
3137+
};
3138+
3139+
yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
3140+
yyjson_mut_val *root = yyjson_mut_obj(doc);
3141+
yyjson_mut_doc_set_root(doc, root);
3142+
yyjson_mut_obj_add_str(doc, root, "type", "agent.install.plan.v1");
3143+
3144+
yyjson_mut_val *agents = yyjson_mut_arr(doc);
3145+
for (size_t i = 0; i < sizeof(names) / sizeof(names[0]); i++) {
3146+
if (names[i].flag) {
3147+
yyjson_mut_arr_add_str(doc, agents, names[i].name);
3148+
}
3149+
}
3150+
yyjson_mut_obj_add_val(doc, root, "agents_detected", agents);
3151+
3152+
yyjson_mut_val *configs = yyjson_mut_arr(doc);
3153+
yyjson_mut_val *instrs = yyjson_mut_arr(doc);
3154+
yyjson_mut_val *hooks = yyjson_mut_arr(doc);
3155+
for (int i = 0; i < plan.count; i++) {
3156+
cbm_plan_entry_t *e = &plan.items[i];
3157+
if (strcmp(e->kind, "mcp_config") == 0) {
3158+
yyjson_mut_arr_add_strcpy(doc, configs, e->path);
3159+
} else if (strcmp(e->kind, "hook") == 0) {
3160+
yyjson_mut_val *h = yyjson_mut_obj(doc);
3161+
yyjson_mut_obj_add_strcpy(doc, h, "agent", e->agent);
3162+
yyjson_mut_obj_add_strcpy(doc, h, "path", e->path);
3163+
yyjson_mut_arr_add_val(hooks, h);
3164+
} else {
3165+
yyjson_mut_arr_add_strcpy(doc, instrs, e->path);
3166+
}
3167+
}
3168+
yyjson_mut_obj_add_val(doc, root, "config_files_planned", configs);
3169+
yyjson_mut_obj_add_val(doc, root, "instruction_files_planned", instrs);
3170+
yyjson_mut_obj_add_val(doc, root, "hooks_planned", hooks);
3171+
yyjson_mut_obj_add_bool(doc, root, "writes_started", false);
3172+
yyjson_mut_obj_add_bool(doc, root, "network_after_install", false);
3173+
yyjson_mut_obj_add_str(doc, root, "next_safe_command", "codebase-memory-mcp install -y");
3174+
3175+
char *json = yyjson_mut_write(doc, YYJSON_WRITE_PRETTY, NULL);
3176+
yyjson_mut_doc_free(doc);
3177+
free(plan.items);
3178+
return json; /* malloc'd; caller frees */
3179+
}
3180+
30303181
int cbm_cmd_install(int argc, char **argv) {
30313182
parse_auto_answer(argc, argv);
30323183
bool dry_run = false;
30333184
bool force = false;
3185+
bool plan = false;
30343186
for (int i = 0; i < argc; i++) {
30353187
if (strcmp(argv[i], "--dry-run") == 0) {
30363188
dry_run = true;
30373189
}
30383190
if (strcmp(argv[i], "--force") == 0) {
30393191
force = true;
30403192
}
3193+
if (strcmp(argv[i], "--plan") == 0) {
3194+
plan = true;
3195+
}
30413196
}
30423197

30433198
const char *home = cbm_get_home_dir();
@@ -3046,6 +3201,22 @@ int cbm_cmd_install(int argc, char **argv) {
30463201
return CLI_TRUE;
30473202
}
30483203

3204+
/* --plan: emit the machine-readable install receipt and exit WITHOUT
3205+
* mutating anything (no config writes, no index deletion, no network) so
3206+
* an agent can inspect exactly what install would touch first (#388). */
3207+
if (plan) {
3208+
char self_path[CLI_BUF_1K] = {0};
3209+
cbm_detect_self_path(self_path, sizeof(self_path), home);
3210+
char *json = cbm_build_install_plan_json(home, self_path);
3211+
if (!json) {
3212+
(void)fprintf(stderr, "error: failed to build install plan\n");
3213+
return CLI_TRUE;
3214+
}
3215+
printf("%s\n", json);
3216+
free(json);
3217+
return 0;
3218+
}
3219+
30493220
printf("codebase-memory-mcp install %s\n\n", CBM_VERSION);
30503221

30513222
int index_count = count_db_indexes(home);

‎src/cli/cli.h‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,4 +273,10 @@ int cbm_cmd_config(int argc, char **argv);
273273
* path returns 0 with no stdout output. */
274274
int cbm_cmd_hook_augment(void);
275275

276+
/* Build the agent.install.plan.v1 install receipt for <home> (issue #388):
277+
* a machine-readable JSON list of the config/instruction/hook files `install`
278+
* would write, produced WITHOUT mutating anything. Returns a heap JSON string
279+
* (caller frees) or NULL on error. Exposed for `install --plan` and testing. */
280+
char *cbm_build_install_plan_json(const char *home, const char *binary_path);
281+
276282
#endif /* CBM_CLI_H */

‎tests/test_cli.c‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1501,6 +1501,43 @@ TEST(cli_detect_agents_finds_cursor_issue222) {
15011501
PASS();
15021502
}
15031503

1504+
/* issue #388: `install --plan` must emit a machine-readable receipt of planned
1505+
* writes WITHOUT mutating any config (the pre-mutation trust primitive). */
1506+
TEST(cli_install_plan_receipt_no_mutation_issue388) {
1507+
char tmpdir[256];
1508+
snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-plan-XXXXXX");
1509+
if (!cbm_mkdtemp(tmpdir))
1510+
SKIP("cbm_mkdtemp failed");
1511+
1512+
/* Make Cursor + Codex "detected". */
1513+
char dir[512];
1514+
snprintf(dir, sizeof(dir), "%s/.cursor", tmpdir);
1515+
test_mkdirp(dir);
1516+
snprintf(dir, sizeof(dir), "%s/.codex", tmpdir);
1517+
test_mkdirp(dir);
1518+
1519+
char *json = cbm_build_install_plan_json(tmpdir, "/usr/local/bin/codebase-memory-mcp");
1520+
ASSERT_NOT_NULL(json);
1521+
ASSERT(strstr(json, "agent.install.plan.v1") != NULL);
1522+
ASSERT(strstr(json, "writes_started") != NULL);
1523+
ASSERT(strstr(json, "next_safe_command") != NULL);
1524+
ASSERT(strstr(json, "cursor") != NULL);
1525+
ASSERT(strstr(json, ".cursor/mcp.json") != NULL);
1526+
ASSERT(strstr(json, ".codex/config.toml") != NULL);
1527+
free(json);
1528+
1529+
/* Critical: building the plan must NOT have created any config file. */
1530+
char cfg[512];
1531+
struct stat st;
1532+
snprintf(cfg, sizeof(cfg), "%s/.cursor/mcp.json", tmpdir);
1533+
ASSERT(stat(cfg, &st) != 0); /* must not exist */
1534+
snprintf(cfg, sizeof(cfg), "%s/.codex/config.toml", tmpdir);
1535+
ASSERT(stat(cfg, &st) != 0); /* must not exist */
1536+
1537+
test_rmdir_r(tmpdir);
1538+
PASS();
1539+
}
1540+
15041541
TEST(cli_detect_agents_finds_gemini) {
15051542
char tmpdir[256];
15061543
snprintf(tmpdir, sizeof(tmpdir), "/tmp/cli-detect-XXXXXX");
@@ -2571,6 +2608,7 @@ SUITE(cli) {
25712608
RUN_TEST(cli_detect_agents_finds_claude_via_env);
25722609
RUN_TEST(cli_detect_agents_finds_codex);
25732610
RUN_TEST(cli_detect_agents_finds_cursor_issue222);
2611+
RUN_TEST(cli_install_plan_receipt_no_mutation_issue388);
25742612
RUN_TEST(cli_detect_agents_finds_gemini);
25752613
RUN_TEST(cli_detect_agents_finds_zed);
25762614
RUN_TEST(cli_detect_agents_finds_antigravity);

0 commit comments

Comments
 (0)