1use 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
22fn 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
35fn resolved_state_root() -> Option<Utf8PathBuf> {
37 UserEnv::from_process().state_root().map(|entry| entry.path)
38}
39
40fn 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
52fn installed_packages() -> Vec<(Utf8PathBuf, &'static [u8])> {
55 let mut planned = Vec::new();
56 for root in agent_roots() {
57 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#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
76#[serde(rename_all = "kebab-case")]
77pub enum ProbeClass {
78 Hard,
80 Soft,
82}
83
84#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
86#[serde(rename_all = "kebab-case")]
87pub enum ProbeStatus {
88 Ok,
90 Failed,
92}
93
94#[derive(Debug, Serialize)]
96pub struct ProbeResult {
97 pub id: &'static str,
99 pub class: ProbeClass,
101 pub status: ProbeStatus,
103 pub message: String,
105 #[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
137pub const SKILL_PROBES: [&str; 3] = ["skill-roots", "skill-gate", "skill-payload"];
143
144#[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
170fn 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
204fn registry() -> ProbeResult {
212 let id = "release-registry";
213 let url = format!("{}/config.json", crate::self_depend::registry::INDEX_ROOT);
214 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 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
251fn 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
277fn 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
324fn 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 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 .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 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
415fn 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
435fn 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 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
498struct Installed {
500 missing: Vec<Utf8PathBuf>,
502 differing: Vec<Utf8PathBuf>,
504 matching: usize,
506 all_recorded: bool,
510}
511
512fn 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
535const 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
546fn 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
559fn 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 #[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}