Module shared 

Cross-installer helpers.

Responsibilities

• Resolve ~ and well-known directories without pulling external crates (std::env::var("HOME")).
• Atomic JSON read/modify/write with timestamped backup files.
• Merge a single mcpServers entry while preserving sibling clients (proxyman, pencil, …) untouched.

Atomicity model

• We always read the full JSON document, mutate in-memory, then write a sibling <file>.spool-tmp and rename to the destination.
• We snapshot the previous bytes to <file>.bak-spool-<unix-ts> BEFORE writing — never overwriting an existing backup. The backup is created at most once per install call.

Why not serde_json::Value::as_object_mut directly?

We keep the surrounding object as serde_json::Value to preserve every key the user (or another tool) may have set. We never re-emit the document with to_string — we use serde_json::to_string_pretty to keep diffs readable.

Enums

McpMergeOutcome

Outcome of merge_mcp_entry.

McpRemoveOutcome

Outcome of remove_mcp_entry.

SettingsHookOutcome

Result of upsert_settings_hook_command.

Functions

backup_file

Snapshot path to <path>.bak-spool-<ts>. Returns the backup path or None when the source file does not exist (fresh install).

build_mcp_entry

Build the canonical spool mcpServers entry.

claude_config_path

Path to the Claude Code top-level config (~/.claude.json).

claude_settings_path

Path to the Claude Code settings file (~/.claude/settings.json).

default_cargo_binary_path

Default spool-mcp install path under ~/.cargo/bin/.

ensure_config_exists

home_dir

Returns the absolute home directory by reading $HOME.

merge_mcp_entry

Merge desired into doc.mcpServers.{client_id}.

purge_settings_hook_entries

Remove every spool-* entry from doc.hooks.{event}. An entry is considered “spool-managed” when any of its inner hooks[].command strings contains the marker marker_substring (typically spool-). We drop the entire wrapper entry to keep the structure tidy; sibling tools’ entries are not touched.

read_json_or_empty

Read a JSON document from disk; missing files yield an empty object.

remove_mcp_entry

Drop doc.mcpServers.{client_id} if it exists.

upsert_settings_hook_command

Ensure doc.hooks.{event} contains an entry referencing command_path. Returns whether the document was mutated.

write_json_atomic

Write JSON to path atomically: write to <path>.spool-tmp then rename. The parent directory MUST exist.