agentgear 0.1.1

Install and self-heal the plugin your Rust binary ships into Claude Code and 24 other coding agents, via a derive macro.
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
138
139
140
141
142
143
144
145

//! serde models for the JSON the crate reads (shipped `plugin.json`, `claude
//! plugin list --json`, `marketplace list --json`) and writes (the generated
//! `marketplace.json`). Every read model is tolerant: unknown fields are ignored
//! (serde default) and optional fields carry `#[serde(default)]`, so an additive
//! CLI-output change does not break parsing.

use serde::{Deserialize, Serialize};

#[cfg(feature = "claude")]
use crate::host::Scope;

/// A shipped `plugin.json`, read from the embedded tree at materialize time to
/// source the generated marketplace's `description` + `owner`. Name/version are
/// read elsewhere (the derive cross-checks name; build.rs enforces version), so
/// they are not modeled here.
#[derive(Debug, Clone, Deserialize)]
pub(crate) struct PluginManifest {
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default)]
    pub author: Option<AuthorField>,
}

/// `plugin.json` `author` is either a bare string or an object; `marketplace.json`
/// `owner` is always an object with a name. Normalize both into [`Person`].
#[derive(Debug, Clone, Deserialize)]
#[serde(untagged)]
pub(crate) enum AuthorField {
    Obj(Person),
    Str(String),
}

impl AuthorField {
    pub fn into_person(self) -> Person {
        match self {
            AuthorField::Obj(p) => p,
            AuthorField::Str(name) => Person { name, email: None, url: None },
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct Person {
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
}

/// The `marketplace.json` the crate generates. Carries no `version` field: CC
/// keys its cache on the `plugin.json` version, and setting a second version here
/// only masks drift (design §7 rule 1).
#[derive(Debug, Clone, Serialize)]
pub(crate) struct MarketplaceManifest {
    pub name: String,
    pub description: String,
    pub owner: Person,
    pub plugins: Vec<MarketplacePlugin>,
}

#[derive(Debug, Clone, Serialize)]
pub(crate) struct MarketplacePlugin {
    pub name: String,
    pub source: String,
    pub description: String,
}

/// One entry of `claude plugin list --json`.
#[cfg(feature = "claude")]
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub(crate) struct PluginEntry {
    /// `"<name>@<marketplace>"`.
    pub id: String,
    #[serde(default)]
    pub version: Option<String>,
    #[serde(default)]
    pub enabled: Option<bool>,
    /// Absolute path to the copied cache tree; a missing dir here means the entry
    /// is registered but its files are gone (a "broken" install).
    #[serde(default)]
    pub install_path: Option<String>,
    /// Load-time failures CC computed for this entry, e.g. a marketplace that no
    /// longer loads (`["Marketplace <mkt> failed to load: cache-miss"]`). CC
    /// registers 0 hooks and 0 MCP for such an entry while `installPath` still
    /// resolves, so a non-empty list is the one signal that a registration whose
    /// files exist is nonetheless dead (probed 2.1.241; the field is NOT persisted
    /// in `installed_plugins.json`, it is computed per `plugin list` invocation).
    #[serde(default)]
    pub errors: Option<Vec<String>>,
    /// `"user"` or `"project"`. Lookup filters on it so a user-scope op never
    /// reads a project entry first (design §self_heal, the scope-blind caveat).
    #[serde(default)]
    pub scope: Option<String>,
}

#[cfg(feature = "claude")]
impl PluginEntry {
    pub fn plugin_name(&self) -> &str {
        self.id.split_once('@').map_or(self.id.as_str(), |(n, _)| n)
    }

    pub fn marketplace(&self) -> Option<&str> {
        self.id.split_once('@').map(|(_, m)| m)
    }

    /// True when this entry is `<name>@<marketplace>`.
    pub fn matches(&self, name: &str, marketplace: &str) -> bool {
        self.plugin_name() == name && self.marketplace() == Some(marketplace)
    }

    /// True when this entry sits at `scope`. A missing `scope` field (tolerant
    /// serde, older CC) matches either, so a lookup never treats it as absent.
    pub fn at_scope(&self, scope: &Scope) -> bool {
        match self.scope.as_deref() {
            None => true,
            Some(s) => s == scope.as_cli(),
        }
    }
}

/// One entry of `claude plugin marketplace list --json`.
#[cfg(feature = "claude")]
#[derive(Debug, Clone, Deserialize)]
pub(crate) struct MarketplaceEntry {
    #[serde(default)]
    pub name: Option<String>,
    /// Source dir for a local-path marketplace; used to detect a dangling
    /// (moved/deleted) marketplace path.
    #[serde(default)]
    pub path: Option<String>,
    /// The entry's own source kind: `"directory"` or `"github"` (probed 2.1.241).
    /// Lets reconcile spot a github-registered entry under a local desired source
    /// — the migration case where `marketplace add <dir>` must re-point it — since
    /// such an entry carries no `path` to diverge on.
    #[serde(default)]
    pub source: Option<String>,
    /// The pinned git ref of a `source: "github"` entry (`known_marketplaces.json`
    /// stores it first-class; absent for a bare/non-github entry). Lets reconcile
    /// spot a drifted pin and re-point it, since `marketplace update` never moves a
    /// pin (design §ref-pinning ground truth).
    #[serde(default, rename = "ref")]
    pub ref_: Option<String>,
}