zsh/extensions/pkg/
resolver.rs

1//! Resolve a user-supplied source spec into a staged plugin directory.
2//! Adapted from strykelang's `pkg/resolver.rs`, trimmed to the three source
3//! forms zshrs plugins ship as (no semver/registry graph — global model).
4//!
5//! Source forms accepted by `znative add <SOURCE>`:
6//! - `owner/repo` or `github:owner/repo` → `git clone https://github.com/owner/repo`
7//! - `git+URL`, or any URL ending in `.git` → `git clone URL`
8//! - `path:DIR`, an absolute path, or `./rel`, `../rel` → a local directory
9//!
10//! `@REF` may be appended to a git/github source to pin a branch/tag/commit
11//! (`owner/repo@v1.2.0`). The resolver clones into `$ZSHRS_HOME/pkg/git/` and
12//! returns the working tree; the caller copies the loadable subset into the
13//! content-addressed store.
14
15use std::path::{Path, PathBuf};
16use std::process::Command;
17
18use super::store::Store;
19use super::{PkgError, PkgResult};
20
21/// A staged source ready to install into the store.
22pub struct Staged {
23    /// Working directory containing the plugin tree.
24    pub dir: PathBuf,
25    /// Inferred plugin name (repo/dir basename).
26    pub name: String,
27    /// Provenance label recorded in the index: `github:owner/repo`,
28    /// `git+URL`, or `path+file://DIR`.
29    pub source: String,
30}
31
32/// Resolve `spec` into a [`Staged`] tree. Clones (git/github) land under
33/// `store.git_dir()`; local paths are used in place.
34pub fn resolve(spec: &str, store: &Store) -> PkgResult<Staged> {
35    let (base, git_ref) = split_ref(spec);
36
37    // Local path forms.
38    if let Some(p) = local_path(base) {
39        let dir = p
40            .canonicalize()
41            .map_err(|e| PkgError::Resolve(format!("path {}: {}", p.display(), e)))?;
42        if !dir.is_dir() {
43            return Err(PkgError::Resolve(format!(
44                "path {} is not a directory",
45                dir.display()
46            )));
47        }
48        let name = basename(&dir);
49        let source = format!("path+file://{}", dir.display());
50        return Ok(Staged { dir, name, source });
51    }
52
53    // Git / GitHub forms.
54    let (url, label, name) = git_url(base)?;
55    store
56        .ensure_layout()
57        .map_err(|e| PkgError::Resolve(e.to_string()))?;
58    let dir = store.git_dir().join(&name);
59    if dir.exists() {
60        std::fs::remove_dir_all(&dir)
61            .map_err(|e| PkgError::Io(format!("clear {}: {}", dir.display(), e)))?;
62    }
63    git_clone(&url, &dir, git_ref)?;
64    Ok(Staged {
65        dir,
66        name,
67        // Record the pinned ref in the source so `update` re-fetches the SAME
68        // version and `load owner/repo@REF` matches only that pin.
69        source: label_with_ref(label, git_ref),
70    })
71}
72
73/// Append `@REF` to a provenance label when a version/ref was pinned, so the
74/// recorded source round-trips back through `resolve`/`split_ref`.
75fn label_with_ref(label: String, git_ref: Option<&str>) -> String {
76    match git_ref {
77        Some(r) => format!("{}@{}", label, r),
78        None => label,
79    }
80}
81
82/// The provenance label a `spec` WOULD receive, computed WITHOUT cloning or
83/// network access. Used by `znative load <spec>` to check whether a source is
84/// already installed (the index keys on this label, since a repo's basename
85/// often differs from its `znative.toml` plugin name — e.g. `zshrs-forgit` →
86/// `forgit`). Returns `None` for a bare plugin name (not a source form).
87pub fn source_label(spec: &str) -> Option<String> {
88    let (base, git_ref) = split_ref(spec);
89    if let Some(p) = local_path(base) {
90        // Match the `path+file://<canonical>` the installer records.
91        let dir = p.canonicalize().ok()?;
92        return Some(format!("path+file://{}", dir.display()));
93    }
94    git_url(base)
95        .ok()
96        .map(|(_url, label, _name)| label_with_ref(label, git_ref))
97}
98
99/// Split a trailing `@REF` (branch/tag/commit) off a spec. Only splits on the
100/// LAST `@` so `git@host:...` SSH URLs keep their `@`.
101fn split_ref(spec: &str) -> (&str, Option<&str>) {
102    // A leading path or scheme with an early `@` (SSH) should not be treated as
103    // a ref; only accept `@` after the last `/`.
104    if let Some(at) = spec.rfind('@') {
105        let after_slash = spec.rfind('/').map(|s| at > s).unwrap_or(true);
106        if after_slash && at + 1 < spec.len() {
107            return (&spec[..at], Some(&spec[at + 1..]));
108        }
109    }
110    (spec, None)
111}
112
113/// Recognize local-path forms; returns the path when `spec` is one.
114fn local_path(spec: &str) -> Option<PathBuf> {
115    if let Some(rest) = spec.strip_prefix("path:") {
116        return Some(PathBuf::from(rest));
117    }
118    if spec.starts_with('/') || spec.starts_with("./") || spec.starts_with("../") || spec.starts_with('~')
119    {
120        let expanded = if let Some(rest) = spec.strip_prefix("~/") {
121            if let Some(home) = std::env::var_os("HOME") {
122                PathBuf::from(home).join(rest)
123            } else {
124                PathBuf::from(spec)
125            }
126        } else {
127            PathBuf::from(spec)
128        };
129        return Some(expanded);
130    }
131    None
132}
133
134/// Map a non-local spec to `(clone_url, provenance_label, name)`.
135fn git_url(spec: &str) -> PkgResult<(String, String, String)> {
136    if let Some(rest) = spec.strip_prefix("git+") {
137        let name = repo_basename(rest);
138        return Ok((rest.to_string(), format!("git+{}", rest), name));
139    }
140    if let Some(rest) = spec.strip_prefix("github:") {
141        let url = format!("https://github.com/{}", rest.trim_end_matches(".git"));
142        let name = repo_basename(&url);
143        return Ok((url, format!("github:{}", rest.trim_end_matches(".git")), name));
144    }
145    if spec.ends_with(".git") || spec.contains("://") {
146        let name = repo_basename(spec);
147        return Ok((spec.to_string(), format!("git+{}", spec), name));
148    }
149    // `owner/repo` shorthand → GitHub.
150    if spec.split('/').count() == 2 && !spec.contains(' ') {
151        let owner_repo = spec.trim_end_matches(".git");
152        let url = format!("https://github.com/{}", owner_repo);
153        let name = repo_basename(&url);
154        return Ok((url, format!("github:{}", owner_repo), name));
155    }
156    Err(PkgError::Resolve(format!(
157        "unrecognized source '{}': expected owner/repo, github:owner/repo, \
158         git+URL, or a local path",
159        spec
160    )))
161}
162
163/// `git clone --depth 1 [--branch REF] URL DIR` — shallow for speed.
164fn git_clone(url: &str, dir: &Path, git_ref: Option<&str>) -> PkgResult<()> {
165    let mut cmd = Command::new("git");
166    cmd.arg("clone").arg("--depth").arg("1");
167    if let Some(r) = git_ref {
168        cmd.arg("--branch").arg(r);
169    }
170    cmd.arg(url).arg(dir);
171    let out = cmd
172        .output()
173        .map_err(|e| PkgError::Resolve(format!("git clone: {} (is git installed?)", e)))?;
174    if !out.status.success() {
175        // Retry without --branch: a REF that's a commit sha can't be used with
176        // `--branch` on a shallow clone. Fall back to a full clone + checkout.
177        if git_ref.is_some() {
178            return git_clone_checkout(url, dir, git_ref.unwrap());
179        }
180        return Err(PkgError::Resolve(format!(
181            "git clone {} failed: {}",
182            url,
183            String::from_utf8_lossy(&out.stderr).trim()
184        )));
185    }
186    Ok(())
187}
188
189/// Full clone + `git checkout REF` — the fallback when a shallow `--branch`
190/// clone can't reach an arbitrary commit.
191fn git_clone_checkout(url: &str, dir: &Path, git_ref: &str) -> PkgResult<()> {
192    if dir.exists() {
193        let _ = std::fs::remove_dir_all(dir);
194    }
195    let out = Command::new("git")
196        .arg("clone")
197        .arg(url)
198        .arg(dir)
199        .output()
200        .map_err(|e| PkgError::Resolve(format!("git clone: {}", e)))?;
201    if !out.status.success() {
202        return Err(PkgError::Resolve(format!(
203            "git clone {} failed: {}",
204            url,
205            String::from_utf8_lossy(&out.stderr).trim()
206        )));
207    }
208    let out = Command::new("git")
209        .current_dir(dir)
210        .arg("checkout")
211        .arg(git_ref)
212        .output()
213        .map_err(|e| PkgError::Resolve(format!("git checkout: {}", e)))?;
214    if !out.status.success() {
215        return Err(PkgError::Resolve(format!(
216            "git checkout {} failed: {}",
217            git_ref,
218            String::from_utf8_lossy(&out.stderr).trim()
219        )));
220    }
221    Ok(())
222}
223
224/// Basename of a directory path, sans trailing separators.
225fn basename(p: &Path) -> String {
226    p.file_name()
227        .map(|s| s.to_string_lossy().into_owned())
228        .unwrap_or_else(|| "plugin".into())
229}
230
231/// Repo name from a clone URL: strip `.git`, take the last path segment.
232fn repo_basename(url: &str) -> String {
233    url.trim_end_matches('/')
234        .trim_end_matches(".git")
235        .rsplit(['/', ':'])
236        .next()
237        .unwrap_or("plugin")
238        .to_string()
239}
240
241#[cfg(test)]
242mod tests {
243    use super::*;
244
245    #[test]
246    fn split_ref_only_after_last_slash() {
247        assert_eq!(split_ref("o/r@v1"), ("o/r", Some("v1")));
248        assert_eq!(split_ref("o/r"), ("o/r", None));
249        // SSH URL @ must not split.
250        assert_eq!(split_ref("git@github.com:o/r.git"), ("git@github.com:o/r.git", None));
251    }
252
253    #[test]
254    fn git_url_forms() {
255        let (u, l, n) = git_url("owner/repo").unwrap();
256        assert_eq!(u, "https://github.com/owner/repo");
257        assert_eq!(l, "github:owner/repo");
258        assert_eq!(n, "repo");
259        let (u, _, n) = git_url("github:a/b").unwrap();
260        assert_eq!(u, "https://github.com/a/b");
261        assert_eq!(n, "b");
262        let (u, l, _) = git_url("git+https://x.com/y.git").unwrap();
263        assert_eq!(u, "https://x.com/y.git");
264        assert_eq!(l, "git+https://x.com/y.git");
265        assert!(git_url("not a source").is_err());
266    }
267
268    #[test]
269    fn local_path_forms() {
270        assert!(local_path("path:/tmp/x").is_some());
271        assert!(local_path("/abs").is_some());
272        assert!(local_path("./rel").is_some());
273        assert!(local_path("owner/repo").is_none());
274    }
275}
zsh/extensions/pkg/resolver.rs

zsh/extensions/pkg/
resolver.rs
