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            "pre-commit",
162            "SDD_PRE_COMMIT_BIN",
163            "pre-commit",
164            "pre-commit; the delivered gates run through it",
165            &["--version"],
166        ),
167    ]
168}
169
170/// A helper binary 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.
173fn tool(
174    id: &'static str,
175    env_override: &str,
176    default_bin: &str,
177    label: &str,
178    args: &[&str],
179) -> ProbeResult {
180    let bin = std::env::var(env_override).unwrap_or_else(|_| default_bin.to_owned());
181    match Command::new(&bin).args(args).output() {
182        Ok(out) if out.status.success() => {
183            ProbeResult::ok(id, ProbeClass::Soft, format!("{default_bin} runs"))
184        }
185        Ok(_) => ProbeResult::failed(
186            id,
187            ProbeClass::Soft,
188            format!("{default_bin} does not answer {}", args.join(" ")),
189            format!("repair {label}"),
190        ),
191        Err(_) => ProbeResult::failed(
192            id,
193            ProbeClass::Soft,
194            format!("{default_bin} is not on PATH"),
195            format!("install {label}"),
196        ),
197    }
198}
199
200/// The registry the release resolver reads is reachable.
201///
202/// Soft, because a host that cannot fetch is a constraint on a plan rather
203/// than a broken install: every default path reads the embedded release,
204/// and only a plan toward another release needs this. The probe reads the
205/// registry's own configuration, which is the smallest document the
206/// protocol defines, and writes nothing.
207fn registry() -> ProbeResult {
208    let id = "release-registry";
209    let url = format!("{}/config.json", crate::self_depend::registry::INDEX_ROOT);
210    // One variable turns the read off, for a host that is deliberately
211    // offline and for every test in this repository's own suite.
212    if crate::domain::paths::variable(OFFLINE_VAR).is_some() {
213        return ProbeResult::ok(
214            id,
215            ProbeClass::Soft,
216            "SDD_OFFLINE is set, so no release beyond the embedded one is planned",
217        );
218    }
219    // A probe's budget is not a fetch's budget: an unreachable registry
220    // must answer this question in seconds, not in the minute a bounded
221    // archive read is allowed.
222    let agent: ureq::Agent = ureq::Agent::config_builder()
223        .timeout_connect(Some(std::time::Duration::from_secs(3)))
224        .timeout_global(Some(std::time::Duration::from_secs(5)))
225        .user_agent(format!("sdd/{}", env!("CARGO_PKG_VERSION")))
226        .build()
227        .into();
228    match agent.get(&url).call() {
229        Ok(response) if response.status().as_u16() == 200 => {
230            ProbeResult::ok(id, ProbeClass::Soft, format!("{url} answers"))
231        }
232        Ok(response) => ProbeResult::failed(
233            id,
234            ProbeClass::Soft,
235            format!("{url} answered {}", response.status().as_u16()),
236            "plan toward the embedded release, or retry when the registry answers",
237        ),
238        Err(source) => ProbeResult::failed(
239            id,
240            ProbeClass::Soft,
241            format!("{url} could not be read: {source}"),
242            "plan toward the embedded release; only a plan toward another release needs the registry",
243        ),
244    }
245}
246
247/// The state root accepts writes; the receipt, the lock, and the journal
248/// live under it.
249fn state_root() -> ProbeResult {
250    let id = "state-root";
251    let Some(root) = resolved_state_root() else {
252        return ProbeResult::failed(
253            id,
254            ProbeClass::Hard,
255            "HOME is not set, so no state root resolves",
256            "export HOME",
257        );
258    };
259    let probe = root.join(format!(".probe-{}", std::process::id()));
260    let written = std::fs::create_dir_all(&root).and_then(|()| std::fs::write(&probe, b"probe"));
261    let _ = std::fs::remove_file(&probe);
262    match written {
263        Ok(()) => ProbeResult::ok(id, ProbeClass::Hard, format!("{root} is writable")),
264        Err(source) => ProbeResult::failed(
265            id,
266            ProbeClass::Hard,
267            format!("{root} is not writable: {source}"),
268            format!("make {root} writable"),
269        ),
270    }
271}
272
273/// The destinations `sdd skill install` writes accept writes: the two agent
274/// roots and the resolved state root.
275///
276/// A root can exist and still refuse, which is what a read-only bind of an
277/// agent directory produces, so what is tested is the nearest existing
278/// ancestor — the directory an install would actually have to write
279/// through. The probe creates nothing: a preview must still be able to
280/// report a root as absent, and a probe that made it exist would take that
281/// answer away.
282fn skill_roots() -> ProbeResult {
283    let id = SKILL_PROBES[0];
284    let Ok(home) = home() else {
285        return ProbeResult::failed(
286            id,
287            ProbeClass::Soft,
288            "HOME is not set, so no skill root resolves",
289            "export HOME",
290        );
291    };
292    let mut refused = Vec::new();
293    let mut roots = agent_roots();
294    roots.extend(resolved_state_root());
295    for root in roots {
296        let Some(existing) = nearest_existing(&root) else {
297            refused.push(format!("no ancestor of {root} exists"));
298            continue;
299        };
300        if let Err(source) = accepts_a_write(&existing) {
301            refused.push(format!("{existing} is not writable: {source}"));
302        }
303    }
304    if refused.is_empty() {
305        ProbeResult::ok(
306            id,
307            ProbeClass::Soft,
308            format!("the skill roots under {home} accept writes"),
309        )
310    } else {
311        ProbeResult::failed(
312            id,
313            ProbeClass::Soft,
314            refused.join("; "),
315            format!("make the skill roots under {home} writable"),
316        )
317    }
318}
319
320/// Every installed package carries the two gates it is told to read first.
321///
322/// This is the probe that answers the one failure a shared home produces. A
323/// container, a sandbox, or a sync that carries a `SKILL.md` without the
324/// `references/` beside it leaves the skill resolvable by name and unable
325/// to read the gates its first section names. A skill that cannot read them
326/// runs neither its pre-flight nor its plan phase, which is the whole
327/// reason they are files rather than prose.
328fn skill_gate() -> ProbeResult {
329    let id = SKILL_PROBES[1];
330    let Ok(home) = home() else {
331        return ProbeResult::failed(
332            id,
333            ProbeClass::Soft,
334            "HOME is not set, so no skill package resolves",
335            "export HOME",
336        );
337    };
338    let record = receipt();
339    // A skill's own reference files are the payload probe's to judge; this
340    // one answers for the shared gates every skill reads first.
341    let gates: Vec<String> = crate::embedded::shared_artifacts()
342        .into_iter()
343        .map(|(path, _)| path)
344        .collect();
345    let references: Vec<(Utf8PathBuf, &'static [u8])> = installed_packages()
346        .into_iter()
347        .filter(|(path, _)| {
348            path.parent()
349                .is_some_and(|parent| parent.file_name() == Some(SKILL_REFERENCES_DIR))
350                && path
351                    .file_name()
352                    .is_some_and(|name| gates.iter().any(|gate| gate == name))
353        })
354        // Only a package that landed is judged: an absent skill is the
355        // payload probe's finding, not this one's.
356        .filter(|(path, _)| {
357            path.parent()
358                .and_then(Utf8Path::parent)
359                .is_some_and(|package| package.join(SKILL_FILE).is_file())
360        })
361        .collect();
362    if references.is_empty() {
363        return ProbeResult::failed(
364            id,
365            ProbeClass::Soft,
366            format!("no installed skill package under {home} carries its gates"),
367            "sdd skill install --apply",
368        );
369    }
370    let found = judge(references, &record);
371    if let Some(first) = found.missing.first() {
372        // The remediation still honours what the rest of the set holds: an
373        // absence beside an edit the record cannot vouch for needs the
374        // force the edit needs, or the named command refuses.
375        return ProbeResult::failed(
376            id,
377            ProbeClass::Soft,
378            format!("a gate every skill reads before acting is not installed: {first}"),
379            reinstall(found.all_recorded),
380        );
381    }
382    if !found.differing.is_empty() {
383        return ProbeResult::failed(
384            id,
385            ProbeClass::Soft,
386            format!(
387                "{} installed gate reference(s) are not this binary's",
388                found.differing.len()
389            ),
390            reinstall(found.all_recorded),
391        );
392    }
393    if let Some(leftover) = retired_shared_leftover(&home, &record) {
394        return ProbeResult::failed(
395            id,
396            ProbeClass::Soft,
397            format!("the retired shared root holds a file no receipt vouches for: {leftover}"),
398            format!("read {leftover}, then remove it; every skill now carries its own gates"),
399        );
400    }
401    ProbeResult::ok(
402        id,
403        ProbeClass::Soft,
404        format!(
405            "{} installed gate reference(s) are this binary's",
406            found.matching
407        ),
408    )
409}
410
411/// A file under the retired shared root that no receipt accounts for.
412///
413/// A sweep takes back what the receipt vouches for. What it leaves is the
414/// operator's, and naming it is the only honest thing a probe can do with a
415/// file this tool refuses to delete.
416fn retired_shared_leftover(home: &Utf8Path, record: &SkillRecord) -> Option<Utf8PathBuf> {
417    let retired = home.join(LEGACY_SHARED_ROOT);
418    let mut found: Vec<Utf8PathBuf> = walkdir::WalkDir::new(retired.as_std_path())
419        .into_iter()
420        .filter_map(Result::ok)
421        .filter(|entry| entry.file_type().is_file())
422        .filter_map(|entry| Utf8PathBuf::from_path_buf(entry.into_path()).ok())
423        .filter(|path| {
424            !std::fs::read(path).is_ok_and(|held| record.wrote(path, &Sha256::of(&held)))
425        })
426        .collect();
427    found.sort();
428    found.into_iter().next()
429}
430
431/// The skills installed under this home are the ones this binary carries.
432///
433/// One binary serves every repository, so a skill under an agent root and
434/// the `sdd` on PATH are two artifacts that can be updated apart: a home
435/// shared with a container, a sandbox, or another machine can hold skills
436/// some other build installed. The probe names that drift rather than
437/// leaving an agent to follow instructions the binary no longer answers.
438fn skill_payload() -> ProbeResult {
439    let id = SKILL_PROBES[2];
440    let Ok(home) = home() else {
441        return ProbeResult::failed(
442            id,
443            ProbeClass::Soft,
444            "HOME is not set, so no agent root resolves",
445            "export HOME",
446        );
447    };
448    let record = receipt();
449    let planned = installed_packages();
450    if planned.is_empty() {
451        return ProbeResult::failed(
452            id,
453            ProbeClass::Soft,
454            format!("no agent skill root exists under {home}"),
455            "sdd skill install --apply",
456        );
457    }
458    let found = judge(planned, &record);
459    if let Some(first) = found.missing.first() {
460        // As in the gate probe: an absence beside an unvouched edit needs
461        // the force the edit needs, or the named command refuses.
462        return ProbeResult::failed(
463            id,
464            ProbeClass::Soft,
465            format!(
466                "{} of this binary's package files are not installed, the first at {first}",
467                found.missing.len()
468            ),
469            reinstall(found.all_recorded),
470        );
471    }
472    if !found.differing.is_empty() {
473        return ProbeResult::failed(
474            id,
475            ProbeClass::Soft,
476            format!(
477                "{} installed package file(s) are not this binary's; sdd is {}",
478                found.differing.len(),
479                env!("CARGO_PKG_VERSION")
480            ),
481            reinstall(found.all_recorded),
482        );
483    }
484    ProbeResult::ok(
485        id,
486        ProbeClass::Soft,
487        format!(
488            "{} installed skill destination(s) are this binary's",
489            found.matching
490        ),
491    )
492}
493
494/// What sits at each destination the payload names.
495struct Installed {
496    /// Destinations the payload names that hold no readable file.
497    missing: Vec<Utf8PathBuf>,
498    /// Destinations holding bytes that are not this binary's.
499    differing: Vec<Utf8PathBuf>,
500    /// How many destinations hold exactly this binary's bytes.
501    matching: usize,
502    /// Whether the record vouches for every differing destination, which
503    /// makes the difference a stale install rather than the operator's own
504    /// edit — and decides whether the fix needs `--force`.
505    all_recorded: bool,
506}
507
508/// Judge each destination the payload names against what sits on disk.
509fn judge(planned: Vec<(Utf8PathBuf, &'static [u8])>, record: &SkillRecord) -> Installed {
510    let mut found = Installed {
511        missing: Vec::new(),
512        differing: Vec::new(),
513        matching: 0,
514        all_recorded: true,
515    };
516    for (destination, bytes) in planned {
517        match std::fs::read(&destination) {
518            Ok(held) if held == bytes => found.matching += 1,
519            Ok(held) => {
520                if !record.wrote(&destination, &Sha256::of(&held)) {
521                    found.all_recorded = false;
522                }
523                found.differing.push(destination);
524            }
525            Err(_) => found.missing.push(destination),
526        }
527    }
528    found
529}
530
531/// The install that corrects a difference. Bytes the record vouches for are
532/// an older release's and go without asking; bytes it cannot account for are
533/// the operator's own, and overwriting those is what `--force` is.
534const fn reinstall(all_recorded: bool) -> &'static str {
535    if all_recorded {
536        "sdd skill install --apply"
537    } else {
538        "sdd skill install --apply --force"
539    }
540}
541
542/// The nearest ancestor of `path`, itself included, that exists as a
543/// directory.
544fn nearest_existing(path: &Utf8Path) -> Option<Utf8PathBuf> {
545    let mut current = Some(path);
546    while let Some(dir) = current {
547        if dir.is_dir() {
548            return Some(dir.to_owned());
549        }
550        current = dir.parent();
551    }
552    None
553}
554
555/// A directory accepts a write, leaving nothing behind.
556fn accepts_a_write(dir: &Utf8Path) -> std::io::Result<()> {
557    let probe = dir.join(format!(".sdd-probe-{}", std::process::id()));
558    let written = std::fs::write(&probe, b"probe");
559    let _ = std::fs::remove_file(&probe);
560    written
561}
562
563#[cfg(test)]
564mod tests {
565    #![allow(
566        clippy::unwrap_used,
567        reason = "a test panics as its failure signal, not as control flow"
568    )]
569
570    use super::*;
571
572    fn utf8(dir: &tempfile::TempDir) -> Utf8PathBuf {
573        Utf8PathBuf::from(dir.path().to_str().unwrap())
574    }
575
576    #[test]
577    fn nearest_existing_walks_up_to_the_first_directory() {
578        let dir = tempfile::tempdir().unwrap();
579        let root = utf8(&dir);
580        assert_eq!(nearest_existing(&root).as_deref(), Some(root.as_path()));
581        assert_eq!(
582            nearest_existing(&root.join("a/b/c")).as_deref(),
583            Some(root.as_path())
584        );
585    }
586
587    #[test]
588    fn a_write_probe_leaves_nothing_behind() {
589        let dir = tempfile::tempdir().unwrap();
590        let root = utf8(&dir);
591        accepts_a_write(&root).unwrap();
592        assert_eq!(std::fs::read_dir(dir.path()).unwrap().count(), 0);
593    }
594
595    /// The judge sorts every destination into exactly one bucket, and the
596    /// record decides whether a differing one still counts as the tool's.
597    #[test]
598    fn the_judge_tells_stale_bytes_from_the_users_own() {
599        let dir = tempfile::tempdir().unwrap();
600        let root = utf8(&dir);
601        let matching = root.join("matching.md");
602        let stale = root.join("stale.md");
603        let edited = root.join("edited.md");
604        let missing = root.join("missing.md");
605        std::fs::write(&matching, b"payload").unwrap();
606        std::fs::write(&stale, b"older release").unwrap();
607        std::fs::write(&edited, b"the user's own").unwrap();
608
609        let mut record = SkillRecord::new();
610        record
611            .written
612            .insert(stale.clone(), Sha256::of(b"older release"));
613
614        let planned: Vec<(Utf8PathBuf, &'static [u8])> = vec![
615            (matching, b"payload"),
616            (stale, b"payload"),
617            (missing.clone(), b"payload"),
618        ];
619        let found = judge(planned, &record);
620        assert_eq!(found.matching, 1);
621        assert_eq!(found.differing.len(), 1);
622        assert_eq!(found.missing, vec![missing]);
623        assert!(found.all_recorded, "the record vouches for the stale copy");
624
625        let planned: Vec<(Utf8PathBuf, &'static [u8])> = vec![(edited, b"payload")];
626        let found = judge(planned, &record);
627        assert!(
628            !found.all_recorded,
629            "bytes the record cannot account for are the user's"
630        );
631    }
632
633    #[test]
634    fn the_reinstall_needs_force_only_over_the_users_bytes() {
635        assert_eq!(reinstall(true), "sdd skill install --apply");
636        assert_eq!(reinstall(false), "sdd skill install --apply --force");
637    }
638}