vs_plugin_api/
model.rs

1use std::collections::BTreeMap;
2use std::path::{Path, PathBuf};
3
4use serde::{Deserialize, Serialize};
5
6/// Supported plugin backend implementations.
7#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
8#[serde(rename_all = "kebab-case")]
9pub enum PluginBackendKind {
10    /// Lua-compatible plugin backend.
11    Lua,
12    /// Native plugin backend modeled after a WASI component contract.
13    Wasi,
14}
15
16/// Registry metadata for a plugin.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18pub struct PluginManifest {
19    /// Stable plugin identifier.
20    pub name: String,
21    /// Runtime backend used to execute hooks.
22    pub backend: PluginBackendKind,
23    /// Local source directory of the plugin.
24    pub source: PathBuf,
25    /// Optional human readable description.
26    #[serde(default)]
27    pub description: Option<String>,
28    /// Alternative names accepted by the CLI.
29    #[serde(default)]
30    pub aliases: Vec<String>,
31    /// Plugin runtime version.
32    #[serde(default)]
33    pub version: Option<String>,
34    /// Plugin homepage or repository.
35    #[serde(default)]
36    pub homepage: Option<String>,
37    /// Plugin update URL.
38    #[serde(default)]
39    pub update_url: Option<String>,
40    /// Plugin manifest URL.
41    #[serde(default)]
42    pub manifest_url: Option<String>,
43    /// Minimum runtime version required by the plugin.
44    #[serde(default)]
45    pub min_runtime_version: Option<String>,
46    /// Additional plugin notes.
47    #[serde(default)]
48    pub notes: Vec<String>,
49    /// Legacy file names handled by the plugin.
50    #[serde(default)]
51    pub legacy_filenames: Vec<String>,
52}
53
54/// A version published by a plugin.
55#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
56pub struct AvailableVersion {
57    /// Version string as understood by the plugin.
58    pub version: String,
59    /// Optional human-readable note.
60    #[serde(default)]
61    pub note: Option<String>,
62    /// Additional packages associated with the version.
63    #[serde(default)]
64    pub additions: Vec<AvailableAddition>,
65}
66
67/// An additional package listed next to an available version.
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69pub struct AvailableAddition {
70    /// Package name.
71    pub name: String,
72    /// Package version.
73    pub version: String,
74    /// Optional note.
75    #[serde(default)]
76    pub note: Option<String>,
77}
78
79/// An environment key emitted by a plugin.
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81pub struct EnvKey {
82    /// Environment variable name.
83    pub key: String,
84    /// Environment variable value.
85    pub value: String,
86}
87
88/// A checksum used to verify a downloaded artifact.
89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
90pub struct Checksum {
91    /// Checksum algorithm.
92    pub algorithm: String,
93    /// Checksum value.
94    pub value: String,
95}
96
97/// An artifact source referenced by an install plan.
98#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
99#[serde(tag = "kind", rename_all = "kebab-case")]
100pub enum InstallSource {
101    /// A local directory that should be copied recursively.
102    Directory { path: PathBuf },
103    /// A local file that may be moved or extracted.
104    File { path: PathBuf },
105    /// A remote URL that should be downloaded.
106    Url {
107        url: String,
108        #[serde(default)]
109        headers: BTreeMap<String, String>,
110    },
111}
112
113/// An artifact returned by a plugin install hook.
114#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
115pub struct InstallArtifact {
116    /// Artifact name.
117    pub name: String,
118    /// Artifact version.
119    pub version: String,
120    /// Artifact source.
121    pub source: InstallSource,
122    /// Optional note.
123    #[serde(default)]
124    pub note: Option<String>,
125    /// Optional checksum.
126    #[serde(default)]
127    pub checksum: Option<Checksum>,
128}
129
130/// Installation plan returned by a plugin.
131#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
132pub struct InstallPlan {
133    /// Plugin name used for diagnostics.
134    pub plugin: String,
135    /// Version that will be installed.
136    pub version: String,
137    /// Primary runtime artifact.
138    pub main: InstallArtifact,
139    /// Additional artifacts.
140    #[serde(default)]
141    pub additions: Vec<InstallArtifact>,
142    /// Legacy file names understood by the plugin.
143    #[serde(default)]
144    pub legacy_filenames: Vec<String>,
145}
146
147/// An installed artifact on disk.
148#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
149pub struct InstalledArtifact {
150    /// Artifact name.
151    pub name: String,
152    /// Artifact version.
153    pub version: String,
154    /// Installed path.
155    pub path: PathBuf,
156    /// Optional note.
157    #[serde(default)]
158    pub note: Option<String>,
159}
160
161/// Fully installed runtime layout for a plugin version.
162#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
163pub struct InstalledRuntime {
164    /// Plugin identifier.
165    pub plugin: String,
166    /// Installed version.
167    pub version: String,
168    /// Version root directory.
169    pub root_dir: PathBuf,
170    /// Main installed artifact.
171    pub main: InstalledArtifact,
172    /// Additional installed artifacts.
173    #[serde(default)]
174    pub additions: Vec<InstalledArtifact>,
175}
176
177impl InstalledRuntime {
178    /// Returns the main runtime path.
179    pub fn main_path(&self) -> &Path {
180        &self.main.path
181    }
182}
vs_plugin_api/model.rs

vs_plugin_api/
model.rs
