From ba77de419742963a7c92981a62900d273141e5f6 Mon Sep 17 00:00:00 2001
From: atagen <boss@atagen.co>
Date: Sat, 30 May 2026 16:00:46 +1000
Subject: [PATCH] feat: add history + undo/redo

Co-authored-by: Amaan Qureshi <git@amaanq.com>
---
 Cargo.lock      |  11 +
 Cargo.toml      |   1 +
 src/cli.rs      |  20 ++
 src/commands.rs |  62 +++-
 src/history.rs  | 731 ++++++++++++++++++++++++++++++++++++++++++++++++
 src/main.rs     |  85 ++++--
 6 files changed, 888 insertions(+), 22 deletions(-)
 create mode 100644 src/history.rs

diff --git a/Cargo.lock b/Cargo.lock
index 3fb5963..42d4586 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -188,6 +188,16 @@ dependencies = [
  "windows-sys",
 ]
 
+[[package]]
+name = "etcetera"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de48cc4d1c1d97a20fd819def54b890cadde72ed3ad0c614822a0a433361be96"
+dependencies = [
+ "cfg-if",
+ "windows-sys",
+]
+
 [[package]]
 name = "fastrand"
 version = "2.4.1"
@@ -728,6 +738,7 @@ version = "0.1.1"
 dependencies = [
  "anyhow",
  "data-encoding",
+ "etcetera",
  "flate2",
  "git2",
  "lexopt",
diff --git a/Cargo.toml b/Cargo.toml
index 3973893..b42757a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -15,6 +15,7 @@ path = "src/main.rs"
 [dependencies]
 anyhow        = "1.0.102"
 data-encoding = "2.10.0"
+etcetera      = "0.11.0"
 flate2        = "1.1.9"
 git2          = "0.21"
 lexopt        = "0.3.2"
diff --git a/src/cli.rs b/src/cli.rs
index 6d9c77e..36e8336 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -44,6 +44,10 @@ pub enum Command {
         rm:       bool,
     },
     Dedup,
+    Undo {
+        list: bool,
+    },
+    Redo,
     Help,
 }
 
@@ -214,6 +218,22 @@ fn parse_parser(mut parser: lexopt::Parser) -> Result<Command> {
             }
             Ok(Command::Dedup)
         },
+        "undo" => {
+            let mut list = false;
+            while let Some(arg) = parser.next()? {
+                match arg {
+                    Long("list") => list = true,
+                    Short(_) | Long(_) | Value(_) => return Err(arg.unexpected().into()),
+                }
+            }
+            Ok(Command::Undo { list })
+        },
+        "redo" => {
+            if let Some(arg) = parser.next()? {
+                return Err(arg.unexpected().into());
+            }
+            Ok(Command::Redo)
+        },
         _ => Ok(Command::Help),
     }
 }
diff --git a/src/commands.rs b/src/commands.rs
index bc1ecad..8ecc37f 100644
--- a/src/commands.rs
+++ b/src/commands.rs
@@ -39,6 +39,7 @@ use crate::{
         BranchComparison,
         CompareStatus,
     },
+    history,
     lock,
     pins,
     pins::{
@@ -63,7 +64,7 @@ struct UpdateFetch {
     comparison: BranchComparison,
 }
 
-fn dir() -> PathBuf {
+pub fn dir() -> PathBuf {
     if let Some(dir) = env::var_os("TACK_DIR") {
         return PathBuf::from(dir);
     }
@@ -74,16 +75,16 @@ fn dir() -> PathBuf {
     cwd.join(".tack")
 }
 
-fn pins_path(dir: &Path) -> PathBuf {
+pub fn pins_path(dir: &Path) -> PathBuf {
     dir.join("pins.toml")
 }
-fn lock_path(dir: &Path) -> PathBuf {
+pub fn lock_path(dir: &Path) -> PathBuf {
     dir.join("pins.lock.json")
 }
 
 /// resolver is `default.nix` in the modern `.tack/` layout, or `inputs.nix`
 /// when the dir is a repo root carrying the legacy layout
-fn resolver_path(dir: &Path) -> PathBuf {
+pub fn resolver_path(dir: &Path) -> PathBuf {
     let legacy = dir.join("inputs.nix");
     if legacy.exists() {
         return legacy;
@@ -136,7 +137,7 @@ fn short(rev: &str) -> String {
     rev.chars().take(7).collect()
 }
 
-fn write_atomic(path: &Path, contents: &str) -> Result<()> {
+pub fn write_atomic(path: &Path, contents: &str) -> Result<()> {
     let mut tmp_str = path.as_os_str().to_owned();
     tmp_str.push(".tmp");
     let tmp = PathBuf::from(tmp_str);
@@ -1680,6 +1681,55 @@ fn pick_name(id: &str, aliases: &BTreeSet<String>) -> String {
         .unwrap_or_default()
 }
 
+pub fn undo(list: bool) -> Result<()> {
+    let dir = dir();
+    let store = history::store_dir(&dir);
+    if list {
+        match history::list(&store) {
+            Some(view) => render(&view, 0, view.rows.len().saturating_sub(1)),
+            None => println!("no history"),
+        }
+        return Ok(());
+    }
+    match history::undo(&dir, &store)? {
+        Some(view) => render_window(&view),
+        None => println!("nothing to undo"),
+    }
+    Ok(())
+}
+
+pub fn redo() -> Result<()> {
+    let dir = dir();
+    let store = history::store_dir(&dir);
+    match history::redo(&dir, &store)? {
+        Some(view) => render_window(&view),
+        None => println!("nothing to redo"),
+    }
+    Ok(())
+}
+
+/// a radius-1 window around the new cursor: the redo target, the live state,
+/// the undo target.
+fn render_window(view: &history::View) {
+    let lo = view.cursor.saturating_sub(1);
+    let hi = (view.cursor + 1).min(view.rows.len().saturating_sub(1));
+    render(view, lo, hi);
+}
+
+/// rows `lo..=hi` newest-first, relative times aligned, `>` marking the cursor
+fn render(view: &history::View, lo: usize, hi: usize) {
+    let now = history::now();
+    let times = (lo..=hi)
+        .map(|idx| history::rel_time(now, view.rows[idx].ts))
+        .collect::<Vec<String>>();
+    let width = times.iter().map(String::len).max().unwrap_or(0);
+    for idx in (lo..=hi).rev() {
+        let marker = if idx == view.cursor { '>' } else { ' ' };
+        let when = &times[idx - lo];
+        println!("{marker} {when:width$}  {}", view.rows[idx].label);
+    }
+}
+
 pub fn help() {
     println!(
         "tack: flake-like toml nix pins, lazily fetched and transformed
@@ -1694,6 +1744,8 @@ usage:
   tack rm <name>
   tack alias <name> <template> | tack alias --rm <name>
   tack dedup
+  tack undo [--list]
+  tack redo
 
 pin types: flake (default), fetch (source tree only), fixed (FOD)
 follows keys may be scoped flake:<name> or tack:<name> (no prefix implies both)
diff --git a/src/history.rs b/src/history.rs
new file mode 100644
index 0000000..1558654
--- /dev/null
+++ b/src/history.rs
@@ -0,0 +1,731 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+//! verbatim snapshots of `pins.toml`, `pins.lock.json`, and the resolver for
+//! `tack undo`/`redo`. those three files fully determine tack's state, so
+//! snapshotting their exact bytes is an exact undo. history is an editor-style
+//! list of states plus a cursor pointing at the live one.
+
+use std::{
+    collections::{
+        HashSet,
+        hash_map::DefaultHasher,
+    },
+    env,
+    fs,
+    hash::{
+        Hash as _,
+        Hasher as _,
+    },
+    path::{
+        Path,
+        PathBuf,
+    },
+    process,
+    time::{
+        SystemTime,
+        UNIX_EPOCH,
+    },
+};
+
+use anyhow::Result;
+use etcetera::{
+    BaseStrategy as _,
+    choose_base_strategy,
+};
+use serde_json::{
+    Value,
+    json,
+};
+
+use crate::commands;
+
+const MAX_LEVELS: usize = 20;
+const MAX_AGE: u64 = 30 * 24 * 60 * 60;
+
+/// verbatim bytes of the three state files: `(pins.toml, pins.lock.json,
+/// resolver)`.
+pub type State = (Option<String>, Option<String>, Option<String>);
+
+/// the state of the bytes of all three files, plus the command that produced it
+/// and when
+#[derive(Default)]
+struct Entry {
+    label:    String,
+    ts:       u64,
+    toml:     Option<String>,
+    lock:     Option<String>,
+    resolver: Option<String>,
+}
+
+impl Entry {
+    fn matches(&self, state: &State) -> bool {
+        self.toml == state.0 && self.lock == state.1 && self.resolver == state.2
+    }
+}
+
+struct History {
+    cursor:  usize,
+    entries: Vec<Entry>,
+}
+
+/// a label + timestamp pair
+pub struct Row {
+    pub label: String,
+    pub ts:    u64,
+}
+
+/// the post-move state of the history
+pub struct View {
+    pub cursor: usize,
+    pub rows:   Vec<Row>,
+}
+
+pub fn now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |dur| dur.as_secs())
+}
+
+/// read the current on-disk state of all three files
+pub fn snapshot(dir: &Path) -> State {
+    let toml = fs::read_to_string(commands::pins_path(dir)).ok();
+    let lock = fs::read_to_string(commands::lock_path(dir)).ok();
+    let resolver = fs::read_to_string(commands::resolver_path(dir)).ok();
+    (toml, lock, resolver)
+}
+
+/// record a `pre -> post` transition under `label`. a no-op appends nothing,
+/// and an edit made outside tack is captured as `(edited)` first (returning
+/// whether it was). errors are swallowed so recording never breaks a command.
+pub fn record(store: &Path, label: &str, pre: State, post: State) -> bool {
+    record_inner(store, label, pre, post).unwrap_or(false)
+}
+
+fn record_inner(store: &Path, label: &str, pre: State, post: State) -> Result<bool> {
+    // a command that left both files untouched is not worth an entry
+    if pre == post {
+        return Ok(false);
+    }
+    let ts = now();
+    let mut history = load(store);
+
+    let captured_edit = if history.entries.is_empty() {
+        history.entries.push(Entry {
+            label: "(initial)".to_owned(),
+            ts,
+            toml: pre.0,
+            lock: pre.1,
+            resolver: pre.2,
+        });
+        history.cursor = 0;
+        false
+    } else {
+        capture_external(&mut history, &pre, ts)
+    };
+
+    // a fresh mutation supersedes any redo branch
+    history.entries.truncate(history.cursor + 1);
+    // entries[cursor] now mirrors the on-disk pre-state, so append the result
+    if !history.entries[history.cursor].matches(&post) {
+        history.entries.push(Entry {
+            label: label.to_owned(),
+            ts,
+            toml: post.0,
+            lock: post.1,
+            resolver: post.2,
+        });
+        history.cursor += 1;
+    }
+
+    gc(&mut history, ts);
+    save(store, &history)?;
+    Ok(captured_edit)
+}
+
+/// capture the live `state` as an `(edited)` entry when it has diverged from
+/// the model (e.g. the user manually edited it), so undo/redo never drop it,
+/// truncating the redo branch like a fresh mutation.
+fn capture_external(history: &mut History, state: &State, ts: u64) -> bool {
+    if history.entries.is_empty() {
+        return false;
+    }
+    if history.entries[history.cursor].matches(state) {
+        return false;
+    }
+    // the live edit becomes the new tip, dropping any redo branch
+    history.entries.truncate(history.cursor + 1);
+    history.entries.push(Entry {
+        label: "(edited)".to_owned(),
+        ts,
+        toml: state.0.clone(),
+        lock: state.1.clone(),
+        resolver: state.2.clone(),
+    });
+    history.cursor += 1;
+    true
+}
+
+/// prune oldest entries first. two caps (count, age), both refusing to drop the
+/// live state or anything redoable
+fn gc(history: &mut History, now: u64) {
+    while history.entries.len() > MAX_LEVELS && history.cursor > 0 {
+        history.entries.remove(0);
+        history.cursor -= 1;
+    }
+    while history.cursor > 0 && now.saturating_sub(history.entries[0].ts) > MAX_AGE {
+        history.entries.remove(0);
+        history.cursor -= 1;
+    }
+}
+
+pub fn undo(project: &Path, store: &Path) -> Result<Option<View>> {
+    let mut history = load(store);
+    // capture any live edit before moving, so undo never drops it
+    let captured = capture_external(&mut history, &snapshot(project), now());
+    if !captured && history.cursor == 0 {
+        return Ok(None);
+    }
+    if history.cursor > 0 {
+        history.cursor -= 1;
+        restore(project, &history.entries[history.cursor])?;
+    }
+    save(store, &history)?;
+    Ok(Some(view(&history)))
+}
+
+pub fn redo(project: &Path, store: &Path) -> Result<Option<View>> {
+    let mut history = load(store);
+    // a live edit voids the redo future, so capture it, then report nothing
+    if capture_external(&mut history, &snapshot(project), now()) {
+        save(store, &history)?;
+        return Ok(None);
+    }
+    if history.entries.is_empty() || history.cursor + 1 >= history.entries.len() {
+        return Ok(None);
+    }
+    history.cursor += 1;
+    restore(project, &history.entries[history.cursor])?;
+    save(store, &history)?;
+    Ok(Some(view(&history)))
+}
+
+pub fn list(store: &Path) -> Option<View> {
+    let history = load(store);
+    if history.entries.is_empty() {
+        return None;
+    }
+    Some(view(&history))
+}
+
+fn view(history: &History) -> View {
+    View {
+        cursor: history.cursor,
+        rows:   history
+            .entries
+            .iter()
+            .map(|entry| {
+                Row {
+                    label: entry.label.clone(),
+                    ts:    entry.ts,
+                }
+            })
+            .collect(),
+    }
+}
+
+/// rewrite all three files from `entry` as one transaction. if any write fails,
+/// every file is rolled back to where it started. a [`None`] field means the
+/// file was absent in that state and is removed.
+fn restore(dir: &Path, entry: &Entry) -> Result<()> {
+    let specs = [
+        (commands::pins_path(dir), entry.toml.as_deref()),
+        (commands::lock_path(dir), entry.lock.as_deref()),
+        (commands::resolver_path(dir), entry.resolver.as_deref()),
+    ];
+    let tag = format!(
+        "{}.{}",
+        process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map(|dur| dur.as_nanos())
+            .unwrap_or_default()
+    );
+    let mut tx = RestoreTx::new();
+    for (path, content) in specs {
+        if let Err(err) = tx.stage(&path, content, &tag) {
+            tx.cleanup_staged();
+            return Err(err);
+        }
+    }
+    match tx.commit() {
+        Ok(()) => Ok(()),
+        Err(err) => {
+            tx.rollback();
+            Err(err)
+        },
+    }
+}
+
+/// one file in a [`RestoreTx`]: its staged replacement (`tmp`, [`None`] to
+/// remove), a backup of the prior bytes, and how far the commit got
+struct RestoreStep {
+    path:      PathBuf,
+    tmp:       Option<PathBuf>,
+    backup:    Option<PathBuf>,
+    backed_up: bool,
+    installed: bool,
+}
+
+/// stage every file as a sibling temp, then commit via renames so a mid-write
+/// failure leaves the tree untouched or rolled back
+struct RestoreTx {
+    steps: Vec<RestoreStep>,
+}
+
+impl RestoreTx {
+    const fn new() -> Self {
+        Self { steps: Vec::new() }
+    }
+
+    /// write `content` to a sibling temp, or stage a removal when [`None`]
+    fn stage(&mut self, path: &Path, content: Option<&str>, tag: &str) -> Result<()> {
+        let tmp = if let Some(text) = content {
+            let tmp = temp_path(path, tag, "tmp");
+            if let Err(err) = fs::write(&tmp, text) {
+                let _ = fs::remove_file(&tmp);
+                return Err(err.into());
+            }
+            Some(tmp)
+        } else {
+            None
+        };
+        self.steps.push(RestoreStep {
+            path: path.to_owned(),
+            tmp,
+            backup: Some(temp_path(path, tag, "bak")),
+            backed_up: false,
+            installed: false,
+        });
+        Ok(())
+    }
+
+    /// back up each existing file, swap in its staged temp, then drop backups
+    fn commit(&mut self) -> Result<()> {
+        for step in &mut self.steps {
+            if step.path.exists() {
+                let backup = step.backup.as_ref().expect("backup path");
+                if backup.exists() {
+                    fs::remove_file(backup)?;
+                }
+                fs::rename(&step.path, backup)?;
+                step.backed_up = true;
+            }
+            if let Some(tmp) = step.tmp.as_ref() {
+                fs::rename(tmp, &step.path)?;
+                step.installed = true;
+            }
+            step.tmp = None;
+        }
+        for step in &mut self.steps {
+            if let Some(backup) = step.backup.take()
+                && backup.exists()
+            {
+                let _ = fs::remove_file(backup);
+            }
+        }
+        Ok(())
+    }
+
+    /// undo a partial commit by dropping installed files and restoring backups,
+    /// newest step first
+    fn rollback(&mut self) {
+        for step in self.steps.iter_mut().rev() {
+            if step.installed && step.path.exists() {
+                let _ = fs::remove_file(&step.path);
+            }
+            if let Some(backup) = step.backup.take()
+                && step.backed_up
+                && backup.exists()
+            {
+                let _ = fs::rename(backup, &step.path);
+            }
+            if let Some(tmp) = step.tmp.take()
+                && tmp.exists()
+            {
+                let _ = fs::remove_file(tmp);
+            }
+        }
+    }
+
+    /// drop temps staged before a failure that aborted ahead of commit
+    fn cleanup_staged(&mut self) {
+        for step in &mut self.steps {
+            if let Some(tmp) = step.tmp.take()
+                && tmp.exists()
+            {
+                let _ = fs::remove_file(tmp);
+            }
+        }
+    }
+}
+
+fn temp_path(path: &Path, tag: &str, kind: &str) -> PathBuf {
+    let mut tmp_str = path.as_os_str().to_owned();
+    tmp_str.push(format!(".undo-{tag}.{kind}"));
+    PathBuf::from(tmp_str)
+}
+
+/// undo-history dir for `project`, under the XDG state dir so snapshots stay
+/// out of the repo
+pub fn store_dir(project: &Path) -> PathBuf {
+    // XDG state dir on Linux, falling back to the data dir where there is no
+    // state dir (e.g. on macOS, Windows)
+    let base = choose_base_strategy().map_or_else(
+        |_| PathBuf::from(".tack-state"),
+        |dirs| dirs.state_dir().unwrap_or_else(|| dirs.data_dir()),
+    );
+    base.join("tack").join(project_key(project))
+}
+
+fn project_key(project: &Path) -> String {
+    let abs = if project.is_absolute() {
+        project.to_path_buf()
+    } else {
+        env::current_dir().map_or_else(|_| project.to_path_buf(), |cwd| cwd.join(project))
+    };
+    content_key(&abs.to_string_lossy())
+}
+
+/// 128-bit hex digest of `text`, recomputed every save, so a hasher change
+/// across toolchains just rewrites the snapshot files once.
+fn content_key(text: &str) -> String {
+    let mut hi = DefaultHasher::new();
+    text.hash(&mut hi);
+    let mut lo = DefaultHasher::new();
+    0x9E37_79B9_7F4A_7C15_u64.hash(&mut lo);
+    text.hash(&mut lo);
+    format!("{:016x}{:016x}", hi.finish(), lo.finish())
+}
+
+fn manifest_path(store: &Path) -> PathBuf {
+    store.join("history.json")
+}
+
+fn snapshots_dir(store: &Path) -> PathBuf {
+    store.join("snapshots")
+}
+
+fn load(store: &Path) -> History {
+    let Ok(raw) = fs::read_to_string(manifest_path(store)) else {
+        return empty();
+    };
+    let Ok(json) = serde_json::from_str::<Value>(&raw) else {
+        return empty();
+    };
+    let Some(arr) = json.get("entries").and_then(Value::as_array) else {
+        return empty();
+    };
+    let snaps = snapshots_dir(store);
+    let mut entries = Vec::with_capacity(arr.len());
+    for value in arr {
+        // an unreadable ref means a corrupt store, so start fresh
+        let Some(entry) = parse_entry(&snaps, value) else {
+            return empty();
+        };
+        entries.push(entry);
+    }
+    let cursor = json
+        .get("cursor")
+        .and_then(Value::as_u64)
+        .and_then(|num| usize::try_from(num).ok())
+        .unwrap_or(0);
+
+    // clamp a possibly-corrupt cursor into range
+    let clamped = cursor.min(entries.len().saturating_sub(1));
+    History {
+        cursor: clamped,
+        entries,
+    }
+}
+
+const fn empty() -> History {
+    History {
+        cursor:  0,
+        entries: Vec::new(),
+    }
+}
+
+/// read one entry, resolving each file ref to its bytes. a missing key or null
+/// means the file was absent. an unreadable ref is corruption ([`None`])
+fn parse_entry(snaps: &Path, value: &Value) -> Option<Entry> {
+    let resolve = |key: &str| -> Option<Option<String>> {
+        let Some(field) = value.get(key) else {
+            return Some(None);
+        };
+        if field.is_null() {
+            return Some(None);
+        }
+        field
+            .as_str()
+            .and_then(|name| fs::read_to_string(snaps.join(name)).ok())
+            .map(Some)
+    };
+    Some(Entry {
+        label:    value
+            .get("label")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_owned(),
+        ts:       value.get("ts").and_then(Value::as_u64).unwrap_or(0),
+        toml:     resolve("toml")?,
+        lock:     resolve("lock")?,
+        resolver: resolve("resolver")?,
+    })
+}
+
+fn save(store: &Path, history: &History) -> Result<()> {
+    let snaps = snapshots_dir(store);
+    fs::create_dir_all(&snaps)?;
+
+    // content-addressed files, written only when absent, so a record writes
+    // just its own new snapshot instead of the whole history
+    let mut referenced = HashSet::new();
+    let mut entries = Vec::with_capacity(history.entries.len());
+    for entry in &history.entries {
+        entries.push(json!({
+            "label": entry.label,
+            "ts": entry.ts,
+            "toml": persist(&snaps, entry.toml.as_deref(), &mut referenced)?,
+            "lock": persist(&snaps, entry.lock.as_deref(), &mut referenced)?,
+            "resolver": persist(&snaps, entry.resolver.as_deref(), &mut referenced)?,
+        }));
+    }
+    let doc = json!({
+        "cursor": history.cursor,
+        "entries": entries,
+    });
+    let mut json = serde_json::to_string_pretty(&doc)?;
+    json.push('\n');
+
+    let path = manifest_path(store);
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    commands::write_atomic(&path, &json)?;
+    sweep(&snaps, &referenced);
+    Ok(())
+}
+
+/// write `content` to a hash-named file and return the name.
+fn persist(snaps: &Path, content: Option<&str>, referenced: &mut HashSet<String>) -> Result<Value> {
+    let Some(text) = content else {
+        return Ok(Value::Null);
+    };
+    let name = content_key(text);
+    let path = snaps.join(&name);
+    if !path.exists() {
+        commands::write_atomic(&path, text)?;
+    }
+    referenced.insert(name.clone());
+    Ok(Value::String(name))
+}
+
+/// drop snapshot files the manifest no longer references, after gc or a
+/// truncated redo branch. this is best-effort
+fn sweep(snaps: &Path, referenced: &HashSet<String>) {
+    let Ok(read) = fs::read_dir(snaps) else {
+        return;
+    };
+    for entry in read.flatten() {
+        let keep = entry
+            .file_name()
+            .to_str()
+            .is_some_and(|name| referenced.contains(name));
+        if !keep {
+            let _ = fs::remove_file(entry.path());
+        }
+    }
+}
+
+/// `just now`, `2m ago`, `1h ago`, `3d ago` from two epochs.
+pub fn rel_time(now: u64, ts: u64) -> String {
+    let delta = now.saturating_sub(ts);
+    if delta < 60 {
+        "just now".to_owned()
+    } else if delta < 3600 {
+        format!("{}m ago", delta / 60)
+    } else if delta < 86400 {
+        format!("{}h ago", delta / 3600)
+    } else {
+        format!("{}d ago", delta / 86400)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{
+        fs,
+        path::Path,
+    };
+
+    use super::{
+        Entry,
+        History,
+        MAX_AGE,
+        MAX_LEVELS,
+        gc,
+        list,
+        record,
+        redo,
+        snapshot,
+        undo,
+    };
+    use crate::commands;
+
+    fn write(dir: &Path, toml: &str) {
+        fs::write(commands::pins_path(dir), toml).unwrap();
+        fs::write(commands::lock_path(dir), "{}\n").unwrap();
+    }
+
+    fn read(dir: &Path) -> String {
+        fs::read_to_string(commands::pins_path(dir)).unwrap()
+    }
+
+    /// stand in for a recorded mutating command: snapshot, mutate, snapshot,
+    /// record. returns whether an external edit was captured.
+    fn run(dir: &Path, label: &str, toml: &str) -> bool {
+        let pre = snapshot(dir);
+        write(dir, toml);
+        let post = snapshot(dir);
+        record(dir, label, pre, post)
+    }
+
+    #[test]
+    fn undo_then_redo_round_trips_state() {
+        let tmp = tempfile::tempdir().unwrap();
+        let dir = tmp.path();
+        write(dir, "v1\n");
+        run(dir, "a", "v2\n");
+        run(dir, "b", "v3\n");
+        assert_eq!(read(dir), "v3\n");
+
+        undo(dir, dir).unwrap();
+        assert_eq!(read(dir), "v2\n");
+        undo(dir, dir).unwrap();
+        assert_eq!(read(dir), "v1\n");
+        assert!(undo(dir, dir).unwrap().is_none()); // at the initial state
+        assert_eq!(read(dir), "v1\n");
+
+        redo(dir, dir).unwrap();
+        assert_eq!(read(dir), "v2\n");
+        redo(dir, dir).unwrap();
+        assert_eq!(read(dir), "v3\n");
+        assert!(redo(dir, dir).unwrap().is_none());
+    }
+
+    #[test]
+    fn undo_captures_external_edit_rather_than_discarding() {
+        let tmp = tempfile::tempdir().unwrap();
+        let dir = tmp.path();
+        write(dir, "v1\n");
+        run(dir, "a", "v2\n");
+
+        // user hand-edits pins.toml outside tack, then undoes
+        write(dir, "manual\n");
+        undo(dir, dir).unwrap();
+        assert_eq!(read(dir), "v2\n"); // stepped back to the recorded state
+
+        // the manual edit must not be lost
+        redo(dir, dir).unwrap();
+        assert_eq!(read(dir), "manual\n");
+        assert!(
+            list(dir)
+                .unwrap()
+                .rows
+                .iter()
+                .any(|row| row.label == "(edited)")
+        );
+    }
+
+    #[test]
+    fn record_flags_an_external_edit() {
+        let tmp = tempfile::tempdir().unwrap();
+        let dir = tmp.path();
+        write(dir, "v1\n");
+        assert!(!run(dir, "a", "v2\n")); // nothing diverged yet
+
+        write(dir, "manual\n"); // unrecorded edit
+        assert!(run(dir, "b", "v3\n")); // recorder notices and captures it
+    }
+
+    #[test]
+    fn new_mutation_truncates_redo_branch() {
+        let tmp = tempfile::tempdir().unwrap();
+        let dir = tmp.path();
+        write(dir, "v1\n");
+        run(dir, "a", "v2\n");
+        run(dir, "b", "v3\n");
+        undo(dir, dir).unwrap(); // back to v2 with v3 redoable
+        assert_eq!(read(dir), "v2\n");
+
+        run(dir, "c", "v4\n"); // forks a new branch
+        assert_eq!(read(dir), "v4\n");
+        assert!(redo(dir, dir).unwrap().is_none()); // the v3 future is gone
+    }
+
+    #[test]
+    fn gc_caps_undo_depth_to_max_levels() {
+        let tmp = tempfile::tempdir().unwrap();
+        let dir = tmp.path();
+        write(dir, "s0\n");
+        for i in 1..=MAX_LEVELS + 5 {
+            run(dir, &format!("m{i}"), &format!("s{i}\n"));
+        }
+        assert!(list(dir).unwrap().rows.len() <= MAX_LEVELS);
+        assert_eq!(read(dir), format!("s{}\n", MAX_LEVELS + 5));
+    }
+
+    #[test]
+    fn gc_drops_aged_undo_entries_but_keeps_live() {
+        let now = MAX_AGE + 1000;
+        let aged = |label: &str| {
+            Entry {
+                label: label.to_owned(),
+                ..Default::default()
+            }
+        };
+        let mut history = History {
+            cursor:  3,
+            entries: vec![aged("0"), aged("1"), aged("2"), Entry {
+                label: "live".to_owned(),
+                ts: now,
+                ..Default::default()
+            }],
+        };
+        gc(&mut history, now);
+
+        // the three aged undo entries are pruned, but the live state survives
+        assert_eq!(history.entries.len(), 1);
+        assert_eq!(history.cursor, 0);
+        assert_eq!(history.entries[0].label, "live");
+    }
+
+    #[test]
+    fn undo_reverts_the_resolver_too() {
+        let tmp = tempfile::tempdir().unwrap();
+        let dir = tmp.path();
+        let resolver = commands::resolver_path(dir);
+        write(dir, "v1\n");
+        fs::write(&resolver, "resolver-v1\n").unwrap();
+        let pre = snapshot(dir);
+
+        // a resolver-only change, e.g. `tack init --resolver`
+        fs::write(&resolver, "resolver-v2\n").unwrap();
+        let post = snapshot(dir);
+        assert!(pre != post); // the 3-file snapshot notices the resolver change
+        record(dir, "init --resolver", pre, post);
+
+        undo(dir, dir).unwrap();
+        assert_eq!(fs::read_to_string(&resolver).unwrap(), "resolver-v1\n");
+    }
+}
diff --git a/src/main.rs b/src/main.rs
index f629d53..591e9b6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3,6 +3,7 @@
 mod cli;
 mod commands;
 mod fetch;
+mod history;
 mod lock;
 mod nar;
 mod pins;
@@ -32,9 +33,35 @@ fn run() -> anyhow::Result<()> {
             force,
             resolver,
             flake,
-        } => commands::init(force, resolver, flake),
-        Command::Update { names, accept } => commands::update(&names, accept),
+        } => {
+            let label = if resolver {
+                "init --resolver"
+            } else if flake {
+                "init --flake"
+            } else if force {
+                "init --force"
+            } else {
+                "init"
+            };
+            recorded(label, move || commands::init(force, resolver, flake))
+        },
         Command::Look { names, verbose } => commands::look(&names, verbose),
+        Command::Dedup => commands::dedup(),
+        Command::Undo { list } => commands::undo(list),
+        Command::Redo => commands::redo(),
+        Command::Help => {
+            commands::help();
+            Ok(())
+        },
+        // mutating commands snapshot before/after and record the diff
+        Command::Update { names, accept } => {
+            let label = if names.is_empty() {
+                "update".to_owned()
+            } else {
+                format!("update {}", names.join(" "))
+            };
+            recorded(&label, move || commands::update(&names, accept))
+        },
         Command::Add {
             name,
             url,
@@ -44,22 +71,32 @@ fn run() -> anyhow::Result<()> {
             submodules,
             follows,
         } => {
-            commands::add(
-                &name,
-                &url,
-                pin_type,
-                unpack,
-                dir.as_deref(),
-                submodules,
-                &follows,
-            )
+            let label = format!("add {name}");
+            recorded(&label, move || {
+                commands::add(
+                    &name,
+                    &url,
+                    pin_type,
+                    unpack,
+                    dir.as_deref(),
+                    submodules,
+                    &follows,
+                )
+            })
         },
-        Command::Rm { name } => commands::rm(&name),
-        Command::Alias { name, template, rm } => commands::alias(&name, template.as_deref(), rm),
-        Command::Dedup => commands::dedup(),
-        Command::Help => {
-            commands::help();
-            Ok(())
+        Command::Rm { name } => {
+            let label = format!("rm {name}");
+            recorded(&label, move || commands::rm(&name))
+        },
+        Command::Alias { name, template, rm } => {
+            let label = if rm {
+                format!("alias --rm {name}")
+            } else {
+                format!("alias {name}")
+            };
+            recorded(&label, move || {
+                commands::alias(&name, template.as_deref(), rm)
+            })
         },
     };
 
@@ -68,3 +105,17 @@ fn run() -> anyhow::Result<()> {
     }
     res
 }
+
+/// run a mutating command, recording the resulting file diff to undo history.
+/// records even on [`Err`], since a partial write is still recoverable.
+fn recorded(label: &str, run: impl FnOnce() -> anyhow::Result<()>) -> anyhow::Result<()> {
+    let dir = commands::dir();
+    let store = history::store_dir(&dir);
+    let pre = history::snapshot(&dir);
+    let res = run();
+    let post = history::snapshot(&dir);
+    if history::record(&store, label, pre, post) {
+        println!("captured external edit");
+    }
+    res
+}