Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Filesystem-mutation primitives shared by the `--apply` modes on
//! `install-mcp`, `install-hooks`, `setup-agent`, and the new
//! `install-instructions`.
//!
//! Every write goes through [`apply_atomic`], which:
//!
//! 1. Resolves a symlink chain without replacing the link, then reads the
//! existing target file (or empty string if absent).
//! 2. Runs the caller-supplied mutator to compute the new content.
//! 3. If the new content equals the old, returns `NoOp` — never
//! touches the disk on a redundant call.
//! 4. Otherwise copies the existing file to `<path>.bak-<unix-ts>`
//! so the user has a recovery path ([`apply_atomic_with_backup`] can
//! put it in a private directory instead).
//! 5. Writes the new content via the canonical
//! [`ai_memory_wiki::write_atomic`] (sibling tempfile + fsync +
//! rename + parent-dir fsync).
//!
//! Every `--apply` mode (install-mcp, install-hooks, install-instructions, …)
//! routes through this function. The mutator decides the format (JSON /
//! TOML / markdown) and the idempotency rule; the I/O atomics live here.
use std::fs;
use std::path::{Path, PathBuf};
use anyhow::{Context, Result};
use jiff::Timestamp;
/// What the mutation did to the target file. Surfaced to the user
/// so they can tell a meaningful change from a redundant re-run.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ApplyOutcome {
/// File didn't exist; we created it.
Created,
/// File existed; our mutation changed it. A backup at
/// `<path>.bak-<ts>` records the prior content.
Updated,
/// File existed and our mutation produced the same content.
/// No write happened. No backup written.
NoOp,
}
impl ApplyOutcome {
/// Short verb for the CLI report line.
#[must_use]
pub const fn verb(self) -> &'static str {
match self {
Self::Created => "created",
Self::Updated => "updated",
Self::NoOp => "no-op",
}
}
}
/// Apply an idempotent mutation to `path`.
///
/// `mutator` receives the existing file content (`""` if absent) and
/// returns the desired new content. The atomicity, backup, and
/// no-op detection happen here.
///
/// # Errors
/// Propagates IO + mutator failures.
pub fn apply_atomic<F>(path: &Path, mutator: F) -> Result<ApplyOutcome>
where
F: FnOnce(&str) -> Result<String>,
{
apply_atomic_with_backup(path, None, mutator)
}
/// A backup kept away from the file it protects: `<dir>/<stem>-<unix-ts>`
/// plus the target's extension, owner-only on Unix. For a target inside a
/// checkout, where a sibling `.bak-<ts>` would show up untracked and could be
/// committed with whatever the file held.
#[derive(Debug, Clone)]
pub struct PrivateBackup {
/// Directory the backup is written to; created owner-only when missing.
pub dir: PathBuf,
/// File-name prefix that tells this target's backups apart in `dir`.
pub stem: String,
}
/// A [`PrivateBackup::stem`] naming a checkout: its directory flattened to
/// safe characters and bounded to the tail (the repository-name end), plus a
/// short hash of the full path so checkouts that flatten alike stay apart.
pub(crate) fn checkout_backup_stem(checkout: &Path) -> String {
use sha2::{Digest as _, Sha256};
let checkout = checkout.to_string_lossy();
let mut flat = String::with_capacity(checkout.len());
for c in checkout.chars() {
let c = if c.is_ascii_alphanumeric() || matches!(c, '.' | '_') {
c
} else {
'-'
};
if !(c == '-' && flat.ends_with('-')) {
flat.push(c);
}
}
let flat = flat.trim_matches('-');
let tail = &flat[flat.len().saturating_sub(64)..];
let digest = format!("{:x}", Sha256::digest(checkout.as_bytes()));
format!("{}-{}", tail.trim_start_matches('-'), &digest[..12])
}
/// [`apply_atomic`], writing the backup to `private_backup` instead of next
/// to `path` when one is given.
///
/// # Errors
/// Propagates IO + mutator failures.
pub fn apply_atomic_with_backup<F>(
path: &Path,
private_backup: Option<&PrivateBackup>,
mutator: F,
) -> Result<ApplyOutcome>
where
F: FnOnce(&str) -> Result<String>,
{
let write_target = resolve_write_target(path)?;
let existed = write_target.exists();
let original = if existed {
fs::read_to_string(&write_target).with_context(|| format!("reading {}", path.display()))?
} else {
String::new()
};
let new_content = mutator(&original)?;
if existed && new_content == original {
return Ok(ApplyOutcome::NoOp);
}
if let Some(parent) = write_target.parent()
&& !parent.as_os_str().is_empty()
{
fs::create_dir_all(parent)
.with_context(|| format!("ensuring parent directory {}", parent.display()))?;
}
if existed {
match private_backup {
None => {
let backup = backup_path_for(path);
fs::copy(&write_target, &backup).with_context(|| {
format!("backing up {} → {}", path.display(), backup.display())
})?;
}
Some(private) => write_private_backup(path, private, &original)?,
}
}
write_atomic(&write_target, &new_content)?;
Ok(if existed {
ApplyOutcome::Updated
} else {
ApplyOutcome::Created
})
}
/// Follow final-component symlinks to the path that an atomic rename should
/// replace. This also handles a dangling final target, which `canonicalize`
/// cannot resolve, without replacing the user's symlink itself.
fn resolve_write_target(path: &Path) -> Result<PathBuf> {
const MAX_SYMLINK_DEPTH: usize = 40;
let mut target = path.to_path_buf();
for _ in 0..MAX_SYMLINK_DEPTH {
match fs::symlink_metadata(&target) {
Ok(metadata) if metadata.file_type().is_symlink() => {
let destination = fs::read_link(&target)
.with_context(|| format!("resolving symlink {}", target.display()))?;
target = if destination.is_absolute() {
destination
} else {
target
.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.unwrap_or_else(|| Path::new("."))
.join(destination)
};
}
Ok(_) => return Ok(target),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(target),
Err(error) => {
return Err(error)
.with_context(|| format!("inspecting symlink {}", target.display()));
}
}
}
anyhow::bail!(
"refusing to write through a symlink chain deeper than {MAX_SYMLINK_DEPTH}: {}",
path.display()
)
}
fn backup_path_for(path: &Path) -> PathBuf {
let stamp = Timestamp::now().as_second();
let mut bak = path.as_os_str().to_owned();
bak.push(format!(".bak-{stamp}"));
PathBuf::from(bak)
}
fn write_private_backup(path: &Path, private: &PrivateBackup, original: &str) -> Result<()> {
let mut name = format!("{}-{}", private.stem, Timestamp::now().as_second());
if let Some(extension) = path.extension() {
name.push('.');
name.push_str(&extension.to_string_lossy());
}
let backup = private.dir.join(name);
let context = || format!("backing up {} → {}", path.display(), backup.display());
crate::commands::path_util::create_private_dir(&private.dir).with_context(context)?;
// Owner-only from creation: the content can carry machine-specific hook
// commands, and on Unix the mode is set before any byte is written.
let mut options = fs::OpenOptions::new();
options.write(true).create(true).truncate(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt as _;
options.mode(0o600);
}
let mut file = options.open(&backup).with_context(context)?;
std::io::Write::write_all(&mut file, original.as_bytes()).with_context(context)?;
Ok(())
}
/// Atomic write via the canonical [`ai_memory_wiki::write_atomic`]
/// (tempfile + fsync + rename + parent-dir fsync). The one wrinkle kept
/// here: the tempfile MUST land in the same directory as the resolved target so
/// `rename(2)` stays intra-filesystem — otherwise we get EXDEV
/// ("Invalid cross-device link"). A bare relative path like `CLAUDE.md`
/// has an *empty* parent, so treat it as `.` (current directory); a
/// `$TMPDIR` fallback would sit on a different filesystem than the
/// project in just about every realistic setup.
fn write_atomic(path: &Path, content: &str) -> Result<()> {
let path = match path.parent() {
Some(parent) if !parent.as_os_str().is_empty() => path.to_path_buf(),
_ => Path::new(".").join(path),
};
ai_memory_wiki::write_atomic(&path, content.as_bytes())
.with_context(|| format!("writing {}", path.display()))?;
Ok(())
}
// --------------------------------------------------------------------
// JSON mutation helpers
// --------------------------------------------------------------------
/// Parse `original` as JSON (or yield an empty object if blank),
/// hand the mutable object to `mutator`, and return the
/// pretty-printed result with a trailing newline.
///
/// Errors out with a clear "this file isn't JSON" message rather
/// than silently overwriting; the user gets a chance to investigate.
///
/// # Errors
/// Returns an error if the input is non-empty and not parseable as
/// a JSON object.
pub fn mutate_json<F>(original: &str, mutator: F) -> Result<String>
where
F: FnOnce(&mut serde_json::Map<String, serde_json::Value>) -> Result<()>,
{
let mut root: serde_json::Map<String, serde_json::Value> = if original.trim().is_empty() {
serde_json::Map::new()
} else {
let parsed: serde_json::Value = serde_json::from_str(original).with_context(|| {
"existing file isn't valid JSON; refusing to overwrite. Inspect by hand, \
rename it, or delete it before re-running --apply."
})?;
match parsed {
serde_json::Value::Object(m) => m,
_ => {
anyhow::bail!(
"existing file is JSON but not an object at the root \
(top-level array / string / number). Refusing to overwrite."
);
}
}
};
mutator(&mut root)?;
let mut out = serde_json::to_string_pretty(&serde_json::Value::Object(root))
.context("serialising merged JSON")?;
if !out.ends_with('\n') {
out.push('\n');
}
Ok(out)
}
/// Read-mutate-write for TOML files via `toml_edit` (preserves
/// comments + formatting from the original).
///
/// `mutator` receives the parsed `DocumentMut` and can use the full
/// `toml_edit` API to make changes. Returns the rendered TOML.
///
/// # Errors
/// Returns an error if the input is non-empty and not parseable.
pub fn mutate_toml<F>(original: &str, mutator: F) -> Result<String>
where
F: FnOnce(&mut toml_edit::DocumentMut) -> Result<()>,
{
let mut doc: toml_edit::DocumentMut = if original.trim().is_empty() {
toml_edit::DocumentMut::new()
} else {
original.parse().with_context(|| {
"existing file isn't valid TOML; refusing to overwrite. Inspect by hand, \
rename it, or delete it before re-running --apply."
})?
};
mutator(&mut doc)?;
Ok(doc.to_string())
}
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
#[test]
fn apply_to_missing_file_creates() {
let tmp = TempDir::new().unwrap();
let p = tmp.path().join("nested/dir/foo.json");
let outcome = apply_atomic(&p, |_| Ok("hello\n".into())).unwrap();
assert_eq!(outcome, ApplyOutcome::Created);
assert_eq!(fs::read_to_string(&p).unwrap(), "hello\n");
}
/// A private backup lands in its own directory, owner-only, and leaves
/// nothing next to the target; the default still backs up beside it.
#[test]
fn private_backup_lands_outside_the_target_directory() {
let tmp = TempDir::new().unwrap();
let checkout = tmp.path().join("checkout");
fs::create_dir_all(&checkout).unwrap();
let target = checkout.join("settings.local.json");
fs::write(&target, "old\n").unwrap();
let backups = tmp.path().join("data").join("backups");
let private = PrivateBackup {
dir: backups.clone(),
stem: "checkout-id".to_string(),
};
let outcome =
apply_atomic_with_backup(&target, Some(&private), |_| Ok("new\n".into())).unwrap();
assert_eq!(outcome, ApplyOutcome::Updated);
assert_eq!(fs::read_to_string(&target).unwrap(), "new\n");
let siblings: Vec<_> = fs::read_dir(&checkout)
.unwrap()
.flatten()
.map(|entry| entry.file_name())
.collect();
assert_eq!(siblings, ["settings.local.json"], "no backup beside it");
let saved: Vec<_> = fs::read_dir(&backups).unwrap().flatten().collect();
assert_eq!(saved.len(), 1);
let name = saved[0].file_name().to_string_lossy().into_owned();
assert!(
name.starts_with("checkout-id-") && name.ends_with(".json"),
"{name}"
);
assert_eq!(fs::read_to_string(saved[0].path()).unwrap(), "old\n");
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt as _;
let mode = saved[0].metadata().unwrap().permissions().mode() & 0o777;
assert_eq!(mode, 0o600);
}
// Control: without a private backup the copy sits next to the target.
apply_atomic(&target, |_| Ok("newer\n".into())).unwrap();
assert!(
fs::read_dir(&checkout)
.unwrap()
.flatten()
.any(|entry| entry.file_name().to_string_lossy().contains(".bak-"))
);
}
#[test]
fn apply_to_unchanged_file_is_noop_and_no_backup() {
let tmp = TempDir::new().unwrap();
let p = tmp.path().join("foo.json");
fs::write(&p, "same\n").unwrap();
let outcome = apply_atomic(&p, |_| Ok("same\n".into())).unwrap();
assert_eq!(outcome, ApplyOutcome::NoOp);
// No .bak-<ts> file should appear.
let backups: Vec<_> = fs::read_dir(tmp.path())
.unwrap()
.flatten()
.filter(|e| e.file_name().to_string_lossy().contains(".bak-"))
.collect();
assert!(backups.is_empty(), "no-op must not create a backup");
}
#[test]
fn apply_to_changed_file_backs_up_then_writes() {
let tmp = TempDir::new().unwrap();
let p = tmp.path().join("foo.json");
fs::write(&p, "old\n").unwrap();
let outcome = apply_atomic(&p, |_| Ok("new\n".into())).unwrap();
assert_eq!(outcome, ApplyOutcome::Updated);
assert_eq!(fs::read_to_string(&p).unwrap(), "new\n");
let backups: Vec<_> = fs::read_dir(tmp.path())
.unwrap()
.flatten()
.filter(|e| e.file_name().to_string_lossy().contains(".bak-"))
.collect();
assert_eq!(backups.len(), 1, "exactly one backup file expected");
let bak_content = fs::read_to_string(backups[0].path()).unwrap();
assert_eq!(bak_content, "old\n");
}
#[cfg(unix)]
#[test]
fn apply_through_symlink_updates_target_and_keeps_link() {
use std::os::unix::fs::symlink;
let tmp = TempDir::new().unwrap();
// A tracked "dotfiles" file, plus a symlink standing in for the config
// path the tool is pointed at (e.g. ~/.claude/settings.json).
let target = tmp.path().join("dotfiles/settings.json");
fs::create_dir_all(target.parent().unwrap()).unwrap();
fs::write(&target, "old\n").unwrap();
let link = tmp.path().join("settings.json");
symlink(&target, &link).unwrap();
let outcome = apply_atomic(&link, |_| Ok("new\n".into())).unwrap();
assert_eq!(outcome, ApplyOutcome::Updated);
// The link must survive as a link, not be replaced by a regular file.
assert!(
fs::symlink_metadata(&link)
.unwrap()
.file_type()
.is_symlink(),
"the symlink must survive the write"
);
// The write landed on the real file the link points at.
assert_eq!(fs::read_to_string(&target).unwrap(), "new\n");
assert_eq!(fs::read_to_string(&link).unwrap(), "new\n");
}
#[cfg(unix)]
#[test]
fn apply_through_dangling_relative_symlink_creates_target_and_keeps_link() {
use std::os::unix::fs::symlink;
let tmp = TempDir::new().unwrap();
let target_dir = tmp.path().join("dotfiles");
fs::create_dir(&target_dir).unwrap();
let target = target_dir.join("settings.json");
let link = tmp.path().join("settings.json");
symlink("dotfiles/settings.json", &link).unwrap();
let outcome = apply_atomic(&link, |_| Ok("new\n".into())).unwrap();
assert_eq!(outcome, ApplyOutcome::Created);
assert!(
fs::symlink_metadata(&link)
.unwrap()
.file_type()
.is_symlink()
);
assert_eq!(fs::read_to_string(&target).unwrap(), "new\n");
}
#[cfg(unix)]
#[test]
fn apply_rejects_a_symlink_loop_without_replacing_it() {
use std::os::unix::fs::symlink;
let tmp = TempDir::new().unwrap();
let link = tmp.path().join("settings.json");
symlink("settings.json", &link).unwrap();
let error = apply_atomic(&link, |_| Ok("new\n".into())).unwrap_err();
assert!(format!("{error:#}").contains("symlink chain deeper"));
assert!(
fs::symlink_metadata(&link)
.unwrap()
.file_type()
.is_symlink()
);
}
#[test]
fn json_mutator_preserves_user_keys() {
let original = r#"{"unrelated":"keep me","mcpServers":{"foo":{"url":"http://foo"}}}"#;
let out = mutate_json(original, |m| {
let servers = m
.entry("mcpServers")
.or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
.as_object_mut()
.unwrap();
servers.insert(
"ai-memory".into(),
serde_json::json!({"url": "http://homelab:49374/mcp"}),
);
Ok(())
})
.unwrap();
let parsed: serde_json::Value = serde_json::from_str(&out).unwrap();
// Unrelated key survives.
assert_eq!(parsed["unrelated"], "keep me");
// Sibling MCP server survives.
assert_eq!(parsed["mcpServers"]["foo"]["url"], "http://foo");
// Ours is added.
assert_eq!(
parsed["mcpServers"]["ai-memory"]["url"],
"http://homelab:49374/mcp"
);
}
#[test]
fn json_mutator_rejects_non_object_root() {
let err = mutate_json("[1,2,3]", |_| Ok(())).unwrap_err();
assert!(format!("{err:?}").contains("not an object"));
}
#[test]
fn json_mutator_rejects_invalid_json() {
let err = mutate_json("{not valid", |_| Ok(())).unwrap_err();
assert!(format!("{err:?}").contains("isn't valid JSON"));
}
#[test]
fn toml_mutator_preserves_comments_and_other_tables() {
let original = "# top comment kept\n\
[other]\n\
keep = \"this\"\n";
let out = mutate_toml(original, |doc| {
doc["mcp_servers"]["ai-memory"]["url"] = toml_edit::value("http://homelab:49374/mcp");
Ok(())
})
.unwrap();
assert!(out.contains("# top comment kept"));
assert!(out.contains("[other]"));
assert!(out.contains("keep = \"this\""));
assert!(out.contains("ai-memory"));
assert!(out.contains("http://homelab:49374/mcp"));
}
#[test]
fn idempotent_double_apply_second_is_noop() {
// The realistic flow: user runs --apply twice in a row,
// second call should be a clean no-op.
let tmp = TempDir::new().unwrap();
let p = tmp.path().join("settings.json");
let mutator = |s: &str| {
mutate_json(s, |m| {
m.insert("foo".into(), serde_json::json!("bar"));
Ok(())
})
};
let first = apply_atomic(&p, mutator).unwrap();
assert_eq!(first, ApplyOutcome::Created);
let second = apply_atomic(&p, mutator).unwrap();
assert_eq!(second, ApplyOutcome::NoOp);
}
}