Skip to main content

ask/
install.rs

1//! Lazy-first `ask install` orchestrator. Rust port of `install.ts`.
2//!
3//! Reads `ask.json`, resolves each library's version (github specs carry it in
4//! the spec; npm specs read the lockfile), and regenerates AGENTS.md + SKILL.md
5//! with lazy `ask src`/`ask docs` references. No docs are downloaded here —
6//! agents fetch on-demand through the lazy commands.
7
8use std::path::Path;
9
10use crate::agents::{generate_agents_md, LazyLibraryInfo};
11use crate::ask_json::AskJson;
12use crate::ignore_files::{manage_ignore_files, IgnoreMode};
13use crate::io::{get_ask_json_path, read_ask_json, write_ask_json};
14use crate::lockfiles::npm_ecosystem_read;
15use crate::skill::generate_skill;
16use crate::spec::{parse_spec, split_explicit_version, ParsedSpec};
17
18/// Options for [`run_install`].
19#[derive(Debug, Clone, Default)]
20pub struct RunInstallOptions {
21    /// Subset of libraries to install (by spec). `None` installs all.
22    pub only_specs: Option<Vec<String>>,
23}
24
25/// Outcome counts from a run.
26#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
27pub struct InstallSummary {
28    pub installed: usize,
29    pub skipped: usize,
30}
31
32pub fn run_install(
33    project_dir: &Path,
34    options: &RunInstallOptions,
35) -> anyhow::Result<InstallSummary> {
36    let Some(ask_json) = read_ask_json(project_dir)? else {
37        let empty = AskJson {
38            libraries: Vec::new(),
39        };
40        write_ask_json(project_dir, &empty)?;
41        eprintln!(
42            "Created empty {}. Add libraries with `ask add npm:<package>` or \
43             `ask add github:<owner>/<repo>@<ref>`.",
44            get_ask_json_path(project_dir).display()
45        );
46        return Ok(InstallSummary::default());
47    };
48
49    let targets: Vec<String> = ask_json
50        .libraries
51        .iter()
52        .map(|e| e.spec().to_string())
53        .filter(|spec| match &options.only_specs {
54            Some(only) => only.contains(spec),
55            None => true,
56        })
57        .collect();
58
59    let mut summary = InstallSummary::default();
60
61    if targets.is_empty() {
62        // Full install after the last library was removed still needs to strip
63        // the AGENTS.md block and ignore markers.
64        if options.only_specs.is_none() {
65            generate_agents_md(project_dir, &[])?;
66            manage_ignore_files(project_dir, IgnoreMode::Remove)?;
67        }
68        eprintln!("No libraries to install.");
69        return Ok(summary);
70    }
71
72    eprintln!(
73        "Resolving {} librar{}...",
74        targets.len(),
75        if targets.len() == 1 { "y" } else { "ies" }
76    );
77
78    let mut resolved: Vec<LazyLibraryInfo> = Vec::new();
79    for spec in &targets {
80        match resolve_one(project_dir, spec) {
81            Some(info) => {
82                generate_skill(project_dir, &info.name, &info.version)?;
83                resolved.push(info);
84                summary.installed += 1;
85            }
86            None => summary.skipped += 1,
87        }
88    }
89
90    // AGENTS.md reflects ALL resolved libraries. For a scoped install, re-resolve
91    // the full set; otherwise reuse this batch to avoid duplicate log output.
92    let all_resolved = if options.only_specs.is_some() {
93        resolve_all(project_dir)
94    } else {
95        resolved
96    };
97    generate_agents_md(project_dir, &all_resolved)?;
98    manage_ignore_files(project_dir, IgnoreMode::Install)?;
99
100    eprintln!(
101        "Install complete: {} resolved, {} skipped.",
102        summary.installed, summary.skipped
103    );
104    Ok(summary)
105}
106
107/// Resolve a single spec's version. `None` when unresolvable (missing lockfile
108/// entry, unsupported ecosystem).
109fn resolve_one(project_dir: &Path, spec: &str) -> Option<LazyLibraryInfo> {
110    let (spec_body, explicit) = split_explicit_version(spec);
111    match parse_spec(spec_body) {
112        ParsedSpec::Github { name, .. } => {
113            // github specs carry the version; strip a leading `v` so output uses
114            // "^14" not "^v14".
115            let version = explicit.unwrap_or("latest");
116            let version = version.strip_prefix('v').unwrap_or(version).to_string();
117            eprintln!("  {spec}: {name}@{version}");
118            Some(LazyLibraryInfo {
119                name,
120                version,
121                spec: spec.to_string(),
122            })
123        }
124        ParsedSpec::Npm { pkg, name } => {
125            let version = match explicit {
126                Some(v) => v.to_string(),
127                None => match npm_ecosystem_read(&pkg, project_dir) {
128                    Some(hit) => hit.version,
129                    None => {
130                        eprintln!("  Warning: {spec}: not found in any lockfile — skipping");
131                        return None;
132                    }
133                },
134            };
135            eprintln!("  {spec}: {name}@{version}");
136            Some(LazyLibraryInfo {
137                name,
138                version,
139                spec: spec.to_string(),
140            })
141        }
142        ParsedSpec::Unknown { .. } => {
143            eprintln!("  Warning: {spec}: unsupported ecosystem — skipping");
144            None
145        }
146    }
147}
148
149/// Resolve every library in `ask.json` (for AGENTS.md regeneration).
150fn resolve_all(project_dir: &Path) -> Vec<LazyLibraryInfo> {
151    let Ok(Some(ask_json)) = read_ask_json(project_dir) else {
152        return Vec::new();
153    };
154    ask_json
155        .libraries
156        .iter()
157        .filter_map(|entry| resolve_one(project_dir, entry.spec()))
158        .collect()
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164
165    fn write_ask(project: &Path, json: &str) {
166        std::fs::write(get_ask_json_path(project), json).unwrap();
167    }
168
169    #[test]
170    fn creates_empty_ask_json_when_missing() {
171        let dir = tempfile::tempdir().unwrap();
172        let summary = run_install(dir.path(), &RunInstallOptions::default()).unwrap();
173        assert_eq!(summary, InstallSummary::default());
174        assert!(get_ask_json_path(dir.path()).exists());
175    }
176
177    #[test]
178    fn resolves_github_spec_and_generates_outputs() {
179        let dir = tempfile::tempdir().unwrap();
180        // resolve_one reads the version from the spec string (spec-embedded
181        // `@v15.0.3`), stripping the leading `v` for the output.
182        write_ask(
183            dir.path(),
184            r#"{"libraries":["github:vercel/next.js@v15.0.3"]}"#,
185        );
186        let summary = run_install(dir.path(), &RunInstallOptions::default()).unwrap();
187        assert_eq!(summary.installed, 1);
188        // SKILL.md + AGENTS.md generated with the v-stripped version.
189        let skill = std::fs::read_to_string(
190            crate::skill::get_skill_dir(dir.path(), "next.js").join("SKILL.md"),
191        )
192        .unwrap();
193        assert!(skill.contains("next.js v15.0.3"));
194        let agents = std::fs::read_to_string(dir.path().join("AGENTS.md")).unwrap();
195        assert!(agents.contains("## next.js v15.0.3"));
196    }
197
198    #[test]
199    fn npm_spec_without_lockfile_is_skipped() {
200        let dir = tempfile::tempdir().unwrap();
201        write_ask(dir.path(), r#"{"libraries":["npm:acme"]}"#);
202        let summary = run_install(dir.path(), &RunInstallOptions::default()).unwrap();
203        assert_eq!(summary.installed, 0);
204        assert_eq!(summary.skipped, 1);
205    }
206
207    #[test]
208    fn npm_spec_resolves_from_package_json() {
209        let dir = tempfile::tempdir().unwrap();
210        write_ask(dir.path(), r#"{"libraries":["npm:acme"]}"#);
211        std::fs::write(
212            dir.path().join("package.json"),
213            r#"{"dependencies":{"acme":"3.4.5"}}"#,
214        )
215        .unwrap();
216        let summary = run_install(dir.path(), &RunInstallOptions::default()).unwrap();
217        assert_eq!(summary.installed, 1);
218        let agents = std::fs::read_to_string(dir.path().join("AGENTS.md")).unwrap();
219        assert!(agents.contains("## acme v3.4.5"));
220    }
221
222    #[test]
223    fn empty_libraries_strips_agents_block() {
224        let dir = tempfile::tempdir().unwrap();
225        write_ask(dir.path(), r#"{"libraries":[]}"#);
226        std::fs::write(
227            dir.path().join("AGENTS.md"),
228            "# Head\n\n<!-- BEGIN:ask-docs-auto-generated -->\nx\n<!-- END:ask-docs-auto-generated -->\n",
229        )
230        .unwrap();
231        run_install(dir.path(), &RunInstallOptions::default()).unwrap();
232        let agents = std::fs::read_to_string(dir.path().join("AGENTS.md")).unwrap();
233        assert!(!agents.contains("BEGIN:ask-docs"));
234    }
235}