agr 0.1.1

agr — install agent artifacts from the public registry into a project
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! `agr.lock` — the record of what was installed. Versioned TOML with stable
//! ordering so diffs are reviewable. Format documented in
//! `docs/registry/LOCKFILE.md`.

use std::path::Path;

use serde::{Deserialize, Serialize};

use crate::Result;

/// Current lockfile schema version.
pub const LOCKFILE_VERSION: u32 = 1;

/// The whole `agr.lock`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Lockfile {
    pub version: u32,
    #[serde(default, rename = "artifact")]
    pub artifacts: Vec<LockEntry>,
}

impl Default for Lockfile {
    fn default() -> Self {
        Self {
            version: LOCKFILE_VERSION,
            artifacts: Vec::new(),
        }
    }
}

/// One installed artifact.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LockEntry {
    pub handle: String,
    pub version: String,
    pub target: String,
    /// sha256 over the concatenated installed file bytes.
    pub content_hash: String,
    /// Destination paths (relative to the install dir), sorted.
    pub files: Vec<String>,
}

impl Lockfile {
    /// Load from `path`, or a default empty lockfile if it does not exist.
    pub fn load(path: &Path) -> Result<Self> {
        match std::fs::read_to_string(path) {
            Ok(text) => Ok(toml::from_str(&text)?),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Self::default()),
            Err(e) => Err(e.into()),
        }
    }

    /// Write to `path` with stable (handle, target) ordering.
    pub fn save(&self, path: &Path) -> Result<()> {
        let mut sorted = self.clone();
        sorted
            .artifacts
            .sort_by(|a, b| (&a.handle, &a.target).cmp(&(&b.handle, &b.target)));
        let text = toml::to_string_pretty(&sorted)?;
        std::fs::write(path, text)?;
        Ok(())
    }

    /// Insert or replace an entry keyed on `(handle, target)`.
    pub fn upsert(&mut self, mut entry: LockEntry) {
        entry.files.sort();
        match self
            .artifacts
            .iter_mut()
            .find(|e| e.handle == entry.handle && e.target == entry.target)
        {
            Some(existing) => *existing = entry,
            None => self.artifacts.push(entry),
        }
    }

    /// Drop the entry keyed on `(handle, target)`. Returns whether one existed.
    pub fn remove(&mut self, handle: &str, target: &str) -> bool {
        let before = self.artifacts.len();
        self.artifacts
            .retain(|e| !(e.handle == handle && e.target == target));
        before != self.artifacts.len()
    }

    /// Look up an entry by `(handle, target)`.
    pub fn get(&self, handle: &str, target: &str) -> Option<&LockEntry> {
        self.artifacts
            .iter()
            .find(|e| e.handle == handle && e.target == target)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn entry(handle: &str, target: &str, version: &str) -> LockEntry {
        LockEntry {
            handle: handle.into(),
            version: version.into(),
            target: target.into(),
            content_hash: "h".into(),
            files: vec!["b".into(), "a".into()],
        }
    }

    #[test]
    fn upsert_replaces_and_sorts_files() {
        let mut lf = Lockfile::default();
        lf.upsert(entry("@a/x", "claude", "v1"));
        lf.upsert(entry("@a/x", "claude", "v2"));
        assert_eq!(lf.artifacts.len(), 1);
        assert_eq!(lf.artifacts[0].version, "v2");
        assert_eq!(lf.artifacts[0].files, vec!["a", "b"]);
    }

    #[test]
    fn remove_only_drops_the_matching_target() {
        let mut lf = Lockfile::default();
        lf.upsert(entry("@a/x", "claude", "v1"));
        lf.upsert(entry("@a/x", "cursor", "v1"));
        assert!(lf.remove("@a/x", "claude"));
        assert_eq!(lf.artifacts.len(), 1);
        assert_eq!(lf.artifacts[0].target, "cursor");
        assert!(!lf.remove("@a/x", "claude"), "second remove is a no-op");
    }

    #[test]
    fn roundtrips_through_toml() {
        let mut lf = Lockfile::default();
        lf.upsert(entry("@a/x", "claude", "v1"));
        let text = toml::to_string_pretty(&lf).unwrap();
        let back: Lockfile = toml::from_str(&text).unwrap();
        assert_eq!(back.version, LOCKFILE_VERSION);
        assert_eq!(back.artifacts, lf.artifacts);
    }
}