Skip to main content

spec_driven_docs/
probes.rs

1//! The environment probe catalog.
2//!
3//! One catalog, read by every caller that needs to know whether this host
4//! is ready: `sdd doctor` runs it whole and reports by class. Each probe
5//! answers with a status, a message, and — on failure — the remediation
6//! printed verbatim wherever the probe is consulted. A probe failure is a
7//! result, not an error, so nothing here returns `Err`.
8
9use std::process::Command;
10
11use camino::{Utf8Path, Utf8PathBuf};
12use serde::Serialize;
13
14use crate::domain::ownership::Sha256;
15use crate::domain::paths::{
16    AgentId, LEGACY_SHARED_ROOT, OFFLINE_VAR, SKILL_FILE, SKILL_RECEIPT_FILE, SKILL_REFERENCES_DIR,
17    UserEnv,
18};
19use crate::domain::skill_record::SkillRecord;
20use crate::services::skill_installer::home;
21
22/// Every agent skill root under this home, resolved through the table.
23///
24/// The table is the one place that knows a variable moved a root, so a
25/// probe that joined the defaults instead would report a directory the
26/// install never writes.
27fn agent_roots() -> Vec<Utf8PathBuf> {
28    UserEnv::from_process()
29        .agent_roots(&[AgentId::Claude, AgentId::Agents])
30        .into_iter()
31        .map(|entry| entry.path)
32        .collect()
33}
34
35/// The state root this host resolves.
36fn resolved_state_root() -> Option<Utf8PathBuf> {
37    UserEnv::from_process().state_root().map(|entry| entry.path)
38}
39
40/// The receipt, read from the resolved path or the home-relative one.
41fn receipt() -> SkillRecord {
42    let env = UserEnv::from_process();
43    let Some(state) = env.state_root() else {
44        return SkillRecord::new();
45    };
46    let legacy = env
47        .legacy_state_root()
48        .map_or_else(|| state.path.clone(), |root| root.join(SKILL_RECEIPT_FILE));
49    SkillRecord::load_with_fallback(&state.path.join(SKILL_RECEIPT_FILE), &legacy)
50}
51
52/// Every installed package file this binary carries, under every agent root
53/// that exists.
54fn installed_packages() -> Vec<(Utf8PathBuf, &'static [u8])> {
55    let mut planned = Vec::new();
56    for root in agent_roots() {
57        // An absent agent root is a choice, not a defect: `--agent` selects
58        // one family and leaves the other's root untouched.
59        if !root.is_dir() {
60            continue;
61        }
62        for name in crate::embedded::skill_names() {
63            let Ok(package) = crate::embedded::skill_package(name) else {
64                continue;
65            };
66            for (relative, bytes) in package {
67                planned.push((root.join(name).join(relative), bytes));
68            }
69        }
70    }
71    planned
72}
73
74/// How a failure weighs at the doctor level.
75#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
76#[serde(rename_all = "kebab-case")]
77pub enum ProbeClass {
78    /// No install under the user's home can work without this.
79    Hard,
80    /// Needed only by some commands or some tasks.
81    Soft,
82}
83
84/// What a probe found.
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
86#[serde(rename_all = "kebab-case")]
87pub enum ProbeStatus {
88    /// The probe passed.
89    Ok,
90    /// The probe failed; the remediation says what fixes it.
91    Failed,
92}
93
94/// One probe's answer.
95#[derive(Debug, Serialize)]
96pub struct ProbeResult {
97    /// The probe's stable name.
98    pub id: &'static str,
99    /// How the failure weighs.
100    pub class: ProbeClass,
101    /// What was found.
102    pub status: ProbeStatus,
103    /// What was found, one line.
104    pub message: String,
105    /// The exact fix, when the probe failed.
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub remediation: Option<String>,
108}
109
110impl ProbeResult {
111    fn ok(id: &'static str, class: ProbeClass, message: impl Into<String>) -> Self {
112        Self {
113            id,
114            class,
115            status: ProbeStatus::Ok,
116            message: message.into(),
117            remediation: None,
118        }
119    }
120
121    fn failed(
122        id: &'static str,
123        class: ProbeClass,
124        message: impl Into<String>,
125        remediation: impl Into<String>,
126    ) -> Self {
127        Self {
128            id,
129            class,
130            status: ProbeStatus::Failed,
131            message: message.into(),
132            remediation: Some(remediation.into()),
133        }
134    }
135}
136
137/// The probes judging the skill installation itself, in catalog order.
138///
139/// Declared here rather than derived by running the catalog: the shared
140/// pre-flight gate must name each of these, and the test holding it to that
141/// must not have to write into the operator's home to learn what they are.
142pub const SKILL_PROBES: [&str; 3] = ["skill-roots", "skill-gate", "skill-payload"];
143
144/// Run the whole catalog, in its stable order.
145#[must_use]
146pub fn run_all() -> Vec<ProbeResult> {
147    vec![
148        state_root(),
149        skill_roots(),
150        skill_gate(),
151        skill_payload(),
152        registry(),
153        tool(
154            "git",
155            "SDD_GIT_BIN",
156            "git",
157            "git; retiring a migrated document is safe only where version control restores it",
158            &["--version"],
159        ),
160        tool(
161            "prek",
162            "SDD_PREK_BIN",
163            "prek",
164            "prek; the delivered gates run through it",
165            &["--version"],
166        ),
167    ]
168}
169
170/// A host tool answers its version call. `env_override` names the
171/// substitute, which is also what keeps tests hermetic; presence is the
172/// whole question, because the tools here take no configuration.
173///
174/// The probe only reports. No command reads its result to pick a tool or
175/// to skip a step: a command that needs the tool runs it, and fails where
176/// the host lacks it.
177fn tool(
178    id: &'static str,
179    env_override: &str,
180    default_bin: &str,
181    label: &str,
182    args: &[&str],
183) -> ProbeResult {
184    let bin = std::env::var(env_override).unwrap_or_else(|_| default_bin.to_owned());
185    match Command::new(&bin).args(args).output() {
186        Ok(out) if out.status.success() => {
187            ProbeResult::ok(id, ProbeClass::Soft, format!("{default_bin} runs"))
188        }
189        Ok(_) => ProbeResult::failed(
190            id,
191            ProbeClass::Soft,
192            format!("{default_bin} does not answer {}", args.join(" ")),
193            format!("repair {label}"),
194        ),
195        Err(_) => ProbeResult::failed(
196            id,
197            ProbeClass::Soft,
198            format!("{default_bin} is not on PATH"),
199            format!("install {label}"),
200        ),
201    }
202}
203
204/// The registry the release resolver reads is reachable.
205///
206/// Soft, because a host that cannot fetch is a constraint on a plan rather
207/// than a broken install: every default path reads the embedded release,
208/// and only a plan toward another release needs this. The probe reads the
209/// registry's own configuration, which is the smallest document the
210/// protocol defines, and writes nothing.
211fn registry() -> ProbeResult {
212    let id = "release-registry";
213    let url = format!("{}/config.json", crate::self_depend::registry::INDEX_ROOT);
214    // One variable turns the read off, for a host that is deliberately
215    // offline and for every test in this repository's own suite.
216    if crate::domain::paths::variable(OFFLINE_VAR).is_some() {
217        return ProbeResult::ok(
218            id,
219            ProbeClass::Soft,
220            "SDD_OFFLINE is set, so no release beyond the embedded one is planned",
221        );
222    }
223    // A probe's budget is not a fetch's budget: an unreachable registry
224    // must answer this question in seconds, not in the minute a bounded
225    // archive read is allowed.
226    let agent: ureq::Agent = ureq::Agent::config_builder()
227        .timeout_connect(Some(std::time::Duration::from_secs(3)))
228        .timeout_global(Some(std::time::Duration::from_secs(5)))
229        .user_agent(format!("sdd/{}", env!("CARGO_PKG_VERSION")))
230        .build()
231        .into();
232    match agent.get(&url).call() {
233        Ok(response) if response.status().as_u16() == 200 => {
234            ProbeResult::ok(id, ProbeClass::Soft, format!("{url} answers"))
235        }
236        Ok(response) => ProbeResult::failed(
237            id,
238            ProbeClass::Soft,
239            format!("{url} answered {}", response.status().as_u16()),
240            "plan toward the embedded release, or retry when the registry answers",
241        ),
242        Err(source) => ProbeResult::failed(
243            id,
244            ProbeClass::Soft,
245            format!("{url} could not be read: {source}"),
246            "plan toward the embedded release; only a plan toward another release needs the registry",
247        ),
248    }
249}
250
251/// The state root accepts writes; the receipt, the lock, and the journal
252/// live under it.
253fn state_root() -> ProbeResult {
254    let id = "state-root";
255    let Some(root) = resolved_state_root() else {
256        return ProbeResult::failed(
257            id,
258            ProbeClass::Hard,
259            "HOME is not set, so no state root resolves",
260            "export HOME",
261        );
262    };
263    let probe = root.join(format!(".probe-{}", std::process::id()));
264    let written = std::fs::create_dir_all(&root).and_then(|()| std::fs::write(&probe, b"probe"));
265    let _ = std::fs::remove_file(&probe);
266    match written {
267        Ok(()) => ProbeResult::ok(id, ProbeClass::Hard, format!("{root} is writable")),
268        Err(source) => ProbeResult::failed(
269            id,
270            ProbeClass::Hard,
271            format!("{root} is not writable: {source}"),
272            format!("make {root} writable"),
273        ),
274    }
275}
276
277/// The destinations `sdd skill install` writes accept writes: the two agent
278/// roots and the resolved state root.
279///
280/// A root can exist and still refuse, which is what a read-only bind of an
281/// agent directory produces, so what is tested is the nearest existing
282/// ancestor — the directory an install would actually have to write
283/// through. The probe creates nothing: a preview must still be able to
284/// report a root as absent, and a probe that made it exist would take that
285/// answer away.
286fn skill_roots() -> ProbeResult {
287    let id = SKILL_PROBES[0];
288    let Ok(home) = home() else {
289        return ProbeResult::failed(
290            id,
291            ProbeClass::Soft,
292            "HOME is not set, so no skill root resolves",
293            "export HOME",
294        );
295    };
296    let mut refused = Vec::new();
297    let mut roots = agent_roots();
298    roots.extend(resolved_state_root());
299    for root in roots {
300        let Some(existing) = nearest_existing(&root) else {
301            refused.push(format!("no ancestor of {root} exists"));
302            continue;
303        };
304        if let Err(source) = accepts_a_write(&existing) {
305            refused.push(format!("{existing} is not writable: {source}"));
306        }
307    }
308    if refused.is_empty() {
309        ProbeResult::ok(
310            id,
311            ProbeClass::Soft,
312            format!("the skill roots under {home} accept writes"),
313        )
314    } else {
315        ProbeResult::failed(
316            id,
317            ProbeClass::Soft,
318            refused.join("; "),
319            format!("make the skill roots under {home} writable"),
320        )
321    }
322}
323
324/// Every installed package carries the two gates it is told to read first.
325///
326/// This is the probe that answers the one failure a shared home produces. A
327/// container, a sandbox, or a sync that carries a `SKILL.md` without the
328/// `references/` beside it leaves the skill resolvable by name and unable
329/// to read the gates its first section names. A skill that cannot read them
330/// runs neither its pre-flight nor its plan phase, which is the whole
331/// reason they are files rather than prose.
332fn skill_gate() -> ProbeResult {
333    let id = SKILL_PROBES[1];
334    let Ok(home) = home() else {
335        return ProbeResult::failed(
336            id,
337            ProbeClass::Soft,
338            "HOME is not set, so no skill package resolves",
339            "export HOME",
340        );
341    };
342    let record = receipt();
343    // A skill's own reference files are the payload probe's to judge; this
344    // one answers for the shared gates every skill reads first.
345    let gates: Vec<String> = crate::embedded::shared_artifacts()
346        .into_iter()
347        .map(|(path, _)| path)
348        .collect();
349    let references: Vec<(Utf8PathBuf, &'static [u8])> = installed_packages()
350        .into_iter()
351        .filter(|(path, _)| {
352            path.parent()
353                .is_some_and(|parent| parent.file_name() == Some(SKILL_REFERENCES_DIR))
354                && path
355                    .file_name()
356                    .is_some_and(|name| gates.iter().any(|gate| gate == name))
357        })
358        // Only a package that landed is judged: an absent skill is the
359        // payload probe's finding, not this one's.
360        .filter(|(path, _)| {
361            path.parent()
362                .and_then(Utf8Path::parent)
363                .is_some_and(|package| package.join(SKILL_FILE).is_file())
364        })
365        .collect();
366    if references.is_empty() {
367        return ProbeResult::failed(
368            id,
369            ProbeClass::Soft,
370            format!("no installed skill package under {home} carries its gates"),
371            "sdd skill install --apply",
372        );
373    }
374    let found = judge(references, &record);
375    if let Some(first) = found.missing.first() {
376        // The remediation still honours what the rest of the set holds: an
377        // absence beside an edit the record cannot vouch for needs the
378        // force the edit needs, or the named command refuses.
379        return ProbeResult::failed(
380            id,
381            ProbeClass::Soft,
382            format!("a gate every skill reads before acting is not installed: {first}"),
383            reinstall(found.all_recorded),
384        );
385    }
386    if !found.differing.is_empty() {
387        return ProbeResult::failed(
388            id,
389            ProbeClass::Soft,
390            format!(
391                "{} installed gate reference(s) are not this binary's",
392                found.differing.len()
393            ),
394            reinstall(found.all_recorded),
395        );
396    }
397    if let Some(leftover) = retired_shared_leftover(&home, &record) {
398        return ProbeResult::failed(
399            id,
400            ProbeClass::Soft,
401            format!("the retired shared root holds a file no receipt vouches for: {leftover}"),
402            format!("read {leftover}, then remove it; every skill now carries its own gates"),
403        );
404    }
405    ProbeResult::ok(
406        id,
407        ProbeClass::Soft,
408        format!(
409            "{} installed gate reference(s) are this binary's",
410            found.matching
411        ),
412    )
413}
414
415/// A file under the retired shared root that no receipt accounts for.
416///
417/// A sweep takes back what the receipt vouches for. What it leaves is the
418/// operator's, and naming it is the only honest thing a probe can do with a
419/// file this tool refuses to delete.
420fn retired_shared_leftover(home: &Utf8Path, record: &SkillRecord) -> Option<Utf8PathBuf> {
421    let retired = home.join(LEGACY_SHARED_ROOT);
422    let mut found: Vec<Utf8PathBuf> = walkdir::WalkDir::new(retired.as_std_path())
423        .into_iter()
424        .filter_map(Result::ok)
425        .filter(|entry| entry.file_type().is_file())
426        .filter_map(|entry| Utf8PathBuf::from_path_buf(entry.into_path()).ok())
427        .filter(|path| {
428            !std::fs::read(path).is_ok_and(|held| record.wrote(path, &Sha256::of(&held)))
429        })
430        .collect();
431    found.sort();
432    found.into_iter().next()
433}
434
435/// The skills installed under this home are the ones this binary carries.
436///
437/// One binary serves every repository, so a skill under an agent root and
438/// the `sdd` on PATH are two artifacts that can be updated apart: a home
439/// shared with a container, a sandbox, or another machine can hold skills
440/// some other build installed. The probe names that drift rather than
441/// leaving an agent to follow instructions the binary no longer answers.
442fn skill_payload() -> ProbeResult {
443    let id = SKILL_PROBES[2];
444    let Ok(home) = home() else {
445        return ProbeResult::failed(
446            id,
447            ProbeClass::Soft,
448            "HOME is not set, so no agent root resolves",
449            "export HOME",
450        );
451    };
452    let record = receipt();
453    let planned = installed_packages();
454    if planned.is_empty() {
455        return ProbeResult::failed(
456            id,
457            ProbeClass::Soft,
458            format!("no agent skill root exists under {home}"),
459            "sdd skill install --apply",
460        );
461    }
462    let found = judge(planned, &record);
463    if let Some(first) = found.missing.first() {
464        // As in the gate probe: an absence beside an unvouched edit needs
465        // the force the edit needs, or the named command refuses.
466        return ProbeResult::failed(
467            id,
468            ProbeClass::Soft,
469            format!(
470                "{} of this binary's package files are not installed, the first at {first}",
471                found.missing.len()
472            ),
473            reinstall(found.all_recorded),
474        );
475    }
476    if !found.differing.is_empty() {
477        return ProbeResult::failed(
478            id,
479            ProbeClass::Soft,
480            format!(
481                "{} installed package file(s) are not this binary's; sdd is {}",
482                found.differing.len(),
483                env!("CARGO_PKG_VERSION")
484            ),
485            reinstall(found.all_recorded),
486        );
487    }
488    ProbeResult::ok(
489        id,
490        ProbeClass::Soft,
491        format!(
492            "{} installed skill destination(s) are this binary's",
493            found.matching
494        ),
495    )
496}
497
498/// What sits at each destination the payload names.
499struct Installed {
500    /// Destinations the payload names that hold no readable file.
501    missing: Vec<Utf8PathBuf>,
502    /// Destinations holding bytes that are not this binary's.
503    differing: Vec<Utf8PathBuf>,
504    /// How many destinations hold exactly this binary's bytes.
505    matching: usize,
506    /// Whether the record vouches for every differing destination, which
507    /// makes the difference a stale install rather than the operator's own
508    /// edit — and decides whether the fix needs `--force`.
509    all_recorded: bool,
510}
511
512/// Judge each destination the payload names against what sits on disk.
513fn judge(planned: Vec<(Utf8PathBuf, &'static [u8])>, record: &SkillRecord) -> Installed {
514    let mut found = Installed {
515        missing: Vec::new(),
516        differing: Vec::new(),
517        matching: 0,
518        all_recorded: true,
519    };
520    for (destination, bytes) in planned {
521        match std::fs::read(&destination) {
522            Ok(held) if held == bytes => found.matching += 1,
523            Ok(held) => {
524                if !record.wrote(&destination, &Sha256::of(&held)) {
525                    found.all_recorded = false;
526                }
527                found.differing.push(destination);
528            }
529            Err(_) => found.missing.push(destination),
530        }
531    }
532    found
533}
534
535/// The install that corrects a difference. Bytes the record vouches for are
536/// an older release's and go without asking; bytes it cannot account for are
537/// the operator's own, and overwriting those is what `--force` is.
538const fn reinstall(all_recorded: bool) -> &'static str {
539    if all_recorded {
540        "sdd skill install --apply"
541    } else {
542        "sdd skill install --apply --force"
543    }
544}
545
546/// The nearest ancestor of `path`, itself included, that exists as a
547/// directory.
548fn nearest_existing(path: &Utf8Path) -> Option<Utf8PathBuf> {
549    let mut current = Some(path);
550    while let Some(dir) = current {
551        if dir.is_dir() {
552            return Some(dir.to_owned());
553        }
554        current = dir.parent();
555    }
556    None
557}
558
559/// A directory accepts a write, leaving nothing behind.
560fn accepts_a_write(dir: &Utf8Path) -> std::io::Result<()> {
561    let probe = dir.join(format!(".sdd-probe-{}", std::process::id()));
562    let written = std::fs::write(&probe, b"probe");
563    let _ = std::fs::remove_file(&probe);
564    written
565}
566
567#[cfg(test)]
568mod tests {
569    #![allow(
570        clippy::unwrap_used,
571        reason = "a test panics as its failure signal, not as control flow"
572    )]
573
574    use super::*;
575
576    fn utf8(dir: &tempfile::TempDir) -> Utf8PathBuf {
577        Utf8PathBuf::from(dir.path().to_str().unwrap())
578    }
579
580    #[test]
581    fn nearest_existing_walks_up_to_the_first_directory() {
582        let dir = tempfile::tempdir().unwrap();
583        let root = utf8(&dir);
584        assert_eq!(nearest_existing(&root).as_deref(), Some(root.as_path()));
585        assert_eq!(
586            nearest_existing(&root.join("a/b/c")).as_deref(),
587            Some(root.as_path())
588        );
589    }
590
591    #[test]
592    fn a_write_probe_leaves_nothing_behind() {
593        let dir = tempfile::tempdir().unwrap();
594        let root = utf8(&dir);
595        accepts_a_write(&root).unwrap();
596        assert_eq!(std::fs::read_dir(dir.path()).unwrap().count(), 0);
597    }
598
599    /// The judge sorts every destination into exactly one bucket, and the
600    /// record decides whether a differing one still counts as the tool's.
601    #[test]
602    fn the_judge_tells_stale_bytes_from_the_users_own() {
603        let dir = tempfile::tempdir().unwrap();
604        let root = utf8(&dir);
605        let matching = root.join("matching.md");
606        let stale = root.join("stale.md");
607        let edited = root.join("edited.md");
608        let missing = root.join("missing.md");
609        std::fs::write(&matching, b"payload").unwrap();
610        std::fs::write(&stale, b"older release").unwrap();
611        std::fs::write(&edited, b"the user's own").unwrap();
612
613        let mut record = SkillRecord::new();
614        record
615            .written
616            .insert(stale.clone(), Sha256::of(b"older release"));
617
618        let planned: Vec<(Utf8PathBuf, &'static [u8])> = vec![
619            (matching, b"payload"),
620            (stale, b"payload"),
621            (missing.clone(), b"payload"),
622        ];
623        let found = judge(planned, &record);
624        assert_eq!(found.matching, 1);
625        assert_eq!(found.differing.len(), 1);
626        assert_eq!(found.missing, vec![missing]);
627        assert!(found.all_recorded, "the record vouches for the stale copy");
628
629        let planned: Vec<(Utf8PathBuf, &'static [u8])> = vec![(edited, b"payload")];
630        let found = judge(planned, &record);
631        assert!(
632            !found.all_recorded,
633            "bytes the record cannot account for are the user's"
634        );
635    }
636
637    #[test]
638    fn the_reinstall_needs_force_only_over_the_users_bytes() {
639        assert_eq!(reinstall(true), "sdd skill install --apply");
640        assert_eq!(reinstall(false), "sdd skill install --apply --force");
641    }
642}