1use std::collections::BTreeMap;
16
17use camino::{Utf8Path, Utf8PathBuf};
18use serde::Serialize;
19
20use crate::domain::markdownlint;
21use crate::domain::profile::{DocsRoot, ProfileId};
22
23pub const HOME_VAR: &str = "HOME";
25pub const CLAUDE_CONFIG_DIR_VAR: &str = "CLAUDE_CONFIG_DIR";
27pub const XDG_STATE_HOME_VAR: &str = "XDG_STATE_HOME";
29pub const XDG_CACHE_HOME_VAR: &str = "XDG_CACHE_HOME";
31pub const OFFLINE_VAR: &str = "SDD_OFFLINE";
33pub const DOCS_SCRATCH_VAR: &str = "SDD_DOCS_SCRATCH";
35pub const SELF_DEPEND_OFF_VAR: &str = "SDD_SELF_DEPEND_OFF";
37pub const LINT_PROVE_RUNNER_VAR: &str = "SDD_LINT_PROVE_RUNNER";
40pub const CI_VAR: &str = "CI";
43pub const DIRENV_IN_ENVRC_VAR: &str = "DIRENV_IN_ENVRC";
48pub const HTTP_ORIGIN_VAR: &str = "SDD_HTTP_ORIGIN";
51
52pub const TOOL_DIR: &str = "spec-driven-docs";
54
55pub const INSTANCE_DIR: &str = ".spec-driven-docs";
57pub const MANIFEST_PATH: &str = ".spec-driven-docs/manifest.json";
59pub const CONFIG_PATH: &str = ".spec-driven-docs/config.yaml";
61pub const DEBT_PATH: &str = ".spec-driven-docs/debt.yaml";
63pub const LEGACY_DEBT_PATH: &str = ".spec-driven-docs/chapter-size-debt.txt";
65pub const HOOKS_CONFIG_PATH: &str = ".pre-commit-config.yaml";
67pub const AGENTS_DIGEST_PATH: &str = "AGENTS.md";
69
70pub const PRUNABLE_ROOTS: &[&str] = &[".spec-driven-docs/", ".claude/skills/", ".agents/skills/"];
72
73pub const STATE_ROOT: &str = ".local/state/spec-driven-docs";
75pub const CACHE_ROOT: &str = ".cache/spec-driven-docs";
77pub const SKILL_RECEIPT_FILE: &str = "skills.json";
79pub const SKILL_FILE: &str = "SKILL.md";
81pub const SKILL_REFERENCES_DIR: &str = "references";
83
84pub const SKILL_LOCK_FILE: &str = "skills.lock";
86pub const SELF_DEPEND_STAMP_DIR: &str = "self-depend";
88pub const SELF_DEPEND_CACHE_DIR: &str = "self-depend";
90pub const LEGACY_SKILL_RECEIPT_PATH: &str = ".local/state/spec-driven-docs/skills.json";
96pub const LEGACY_SHARED_ROOT: &str = ".local/state/spec-driven-docs/skills/shared";
102pub const CLAUDE_ROOT: &str = ".claude/skills";
104pub const AGENTS_ROOT: &str = ".agents/skills";
106
107#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
109#[serde(rename_all = "kebab-case")]
110pub enum AgentId {
111 Claude,
113 Agents,
115}
116
117impl AgentId {
118 #[must_use]
120 pub const fn as_str(self) -> &'static str {
121 match self {
122 Self::Claude => "claude",
123 Self::Agents => "agents",
124 }
125 }
126}
127
128impl std::fmt::Display for AgentId {
129 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
130 f.write_str(self.as_str())
131 }
132}
133
134#[derive(Debug, Clone, Copy, PartialEq, Eq)]
136pub struct AgentRoot {
137 pub id: AgentId,
139 pub default: &'static str,
141 pub config_env: Option<&'static str>,
143 pub relocated: &'static str,
145}
146
147const CLAUDE: AgentRoot = AgentRoot {
149 id: AgentId::Claude,
150 default: CLAUDE_ROOT,
151 config_env: Some(CLAUDE_CONFIG_DIR_VAR),
152 relocated: "skills",
153};
154
155const AGENTS: AgentRoot = AgentRoot {
157 id: AgentId::Agents,
158 default: AGENTS_ROOT,
159 config_env: None,
160 relocated: "skills",
161};
162
163pub const AGENT_ROOTS: &[AgentRoot] = &[CLAUDE, AGENTS];
170
171#[must_use]
173pub const fn agent_root(id: AgentId) -> &'static AgentRoot {
174 match id {
175 AgentId::Claude => &CLAUDE,
176 AgentId::Agents => &AGENTS,
177 }
178}
179
180#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
182#[serde(rename_all = "kebab-case")]
183pub enum PathSource {
184 Recorded,
186 Default,
188 Env,
190 Profile,
192 Proposal,
194}
195
196#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
198pub struct PathEntry {
199 pub path: Utf8PathBuf,
201 pub source: PathSource,
203}
204
205impl PathEntry {
206 #[must_use]
208 pub fn default_at(path: impl Into<Utf8PathBuf>) -> Self {
209 Self {
210 path: path.into(),
211 source: PathSource::Default,
212 }
213 }
214
215 #[must_use]
217 pub fn from_env(path: impl Into<Utf8PathBuf>) -> Self {
218 Self {
219 path: path.into(),
220 source: PathSource::Env,
221 }
222 }
223}
224
225#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
227pub struct AgentRootEntry {
228 pub id: AgentId,
230 pub path: Utf8PathBuf,
232 pub source: PathSource,
234 pub variable: Option<&'static str>,
236}
237
238#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
245#[serde(tag = "kind", rename_all = "kebab-case")]
246pub enum ProjectLocation {
247 Tracked {
249 path: Utf8PathBuf,
251 source: PathSource,
253 },
254 Untracked {
256 path: Utf8PathBuf,
258 source: PathSource,
260 },
261 External {
263 path: Utf8PathBuf,
265 source: PathSource,
267 },
268 Env {
270 variable: &'static str,
272 value: Option<String>,
274 },
275 None,
277}
278
279#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
285#[serde(tag = "kind", rename_all = "kebab-case")]
286pub enum LocationChoice {
287 Observed {
289 path: Utf8PathBuf,
291 },
292 Env {
294 variable: &'static str,
296 value: Option<String>,
298 },
299 Operator,
301 None,
303}
304
305#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
307pub struct Proposals {
308 pub docs_scratch: Vec<LocationChoice>,
310}
311
312#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
314pub struct UserPaths {
315 pub state_root: PathEntry,
317 pub cache_root: PathEntry,
319 #[serde(skip_serializing_if = "Option::is_none")]
322 pub skill_receipt: Option<PathEntry>,
323 #[serde(skip_serializing_if = "Vec::is_empty")]
326 pub agent_roots: Vec<AgentRootEntry>,
327}
328
329impl UserPaths {
330 #[must_use]
333 pub fn with_skill_entries_while_a_receipt_exists(mut self, legacy: Option<&Utf8Path>) -> Self {
334 let held = self
335 .skill_receipt
336 .as_ref()
337 .is_some_and(|receipt| receipt.path.is_file())
338 || legacy.is_some_and(Utf8Path::is_file);
339 if !held {
340 self.skill_receipt = None;
341 self.agent_roots.clear();
342 }
343 self
344 }
345}
346
347#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
349pub struct InstancePaths {
350 pub instance_dir: PathEntry,
352 pub manifest: PathEntry,
354 pub declaration: PathEntry,
356 pub debt: PathEntry,
358 pub legacy_debt: PathEntry,
360 pub hooks_config: PathEntry,
362 pub agents_digest: PathEntry,
364 pub docs_root: PathEntry,
366 pub specs: PathEntry,
368 pub decisions: PathEntry,
370 pub reference: PathEntry,
372 pub guides: PathEntry,
374 pub lint_config: PathEntry,
377 pub lint_discovery: LintDiscovery,
380}
381
382#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
388pub struct LintDiscovery {
389 pub repository_root: Vec<PathEntry>,
393 pub refused_at_docs_root: Vec<PathEntry>,
396 pub refused_beneath: Vec<PathEntry>,
399}
400
401#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
403pub struct ActivePaths {
404 pub profile: ProfileId,
406 pub destinations: InstancePaths,
408 pub docs_scratch: ProjectLocation,
410}
411
412#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
414pub struct CandidatePaths {
415 pub profile: ProfileId,
417 pub destinations: InstancePaths,
419}
420
421#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
423pub struct Paths {
424 pub user: Option<UserPaths>,
427 pub active: Option<ActivePaths>,
429 pub candidates: BTreeMap<String, CandidatePaths>,
431 pub proposals: Proposals,
433}
434
435#[derive(Debug, Clone, Default, PartialEq, Eq)]
437pub struct UserEnv {
438 pub home: Option<Utf8PathBuf>,
440 pub claude_config_dir: Option<Utf8PathBuf>,
442 pub xdg_state_home: Option<Utf8PathBuf>,
444 pub xdg_cache_home: Option<Utf8PathBuf>,
446 pub docs_scratch: Option<String>,
448}
449
450#[must_use]
456pub fn variable(name: &str) -> Option<String> {
457 std::env::var(name)
458 .ok()
459 .map(|value| value.trim().to_string())
460 .filter(|value| !value.is_empty())
461}
462
463impl UserEnv {
464 #[must_use]
466 pub fn from_process() -> Self {
467 let path = |name: &str| variable(name).map(Utf8PathBuf::from);
468 Self {
469 home: path(HOME_VAR),
470 claude_config_dir: path(CLAUDE_CONFIG_DIR_VAR),
471 xdg_state_home: path(XDG_STATE_HOME_VAR),
472 xdg_cache_home: path(XDG_CACHE_HOME_VAR),
473 docs_scratch: variable(DOCS_SCRATCH_VAR),
474 }
475 }
476
477 #[must_use]
479 pub fn state_root(&self) -> Option<PathEntry> {
480 if let Some(base) = self.xdg_state_home.as_ref() {
481 return Some(PathEntry::from_env(base.join(TOOL_DIR)));
482 }
483 self.home
484 .as_ref()
485 .map(|home| PathEntry::default_at(home.join(STATE_ROOT)))
486 }
487
488 #[must_use]
494 pub fn legacy_state_root(&self) -> Option<Utf8PathBuf> {
495 self.home.as_ref().map(|home| home.join(STATE_ROOT))
496 }
497
498 #[must_use]
500 pub fn cache_root(&self) -> Option<PathEntry> {
501 if let Some(base) = self.xdg_cache_home.as_ref() {
502 return Some(PathEntry::from_env(base.join(TOOL_DIR)));
503 }
504 self.home
505 .as_ref()
506 .map(|home| PathEntry::default_at(home.join(CACHE_ROOT)))
507 }
508
509 #[must_use]
511 pub fn agent_root(&self, id: AgentId) -> Option<AgentRootEntry> {
512 let row = agent_root(id);
513 let home = self.home.as_ref()?;
514 let relocated = match row.id {
515 AgentId::Claude => self.claude_config_dir.as_ref(),
516 AgentId::Agents => None,
517 };
518 Some(relocated.map_or_else(
519 || AgentRootEntry {
520 id: row.id,
521 path: home.join(row.default),
522 source: PathSource::Default,
523 variable: None,
524 },
525 |base| AgentRootEntry {
526 id: row.id,
527 path: base.join(row.relocated),
528 source: PathSource::Env,
529 variable: row.config_env,
530 },
531 ))
532 }
533
534 #[must_use]
541 pub fn agent_roots(&self, selected: &[AgentId]) -> Vec<AgentRootEntry> {
542 let mut resolved: Vec<AgentRootEntry> = Vec::new();
543 for row in AGENT_ROOTS {
544 if !selected.contains(&row.id) {
545 continue;
546 }
547 let Some(entry) = self.agent_root(row.id) else {
548 continue;
549 };
550 let reached = |path: &Utf8Path| {
553 std::fs::canonicalize(path).unwrap_or_else(|_| path.as_std_path().to_path_buf())
554 };
555 if resolved
556 .iter()
557 .any(|held| reached(&held.path) == reached(&entry.path))
558 {
559 continue;
560 }
561 resolved.push(entry);
562 }
563 resolved
564 }
565
566 #[must_use]
568 pub fn user_paths(&self) -> Option<UserPaths> {
569 let state = self.state_root()?;
570 let cache = self.cache_root()?;
571 Some(UserPaths {
572 skill_receipt: Some(PathEntry {
573 path: state.path.join(SKILL_RECEIPT_FILE),
574 source: state.source,
575 }),
576 agent_roots: self.agent_roots(&[AgentId::Claude, AgentId::Agents]),
577 state_root: state,
578 cache_root: cache,
579 })
580 }
581}
582
583#[must_use]
585pub fn instance_paths(docs_root: DocsRoot) -> InstancePaths {
586 let docs = Utf8PathBuf::from(docs_root.as_str());
587 let under = |leaf: &str| PathEntry {
588 path: docs.join(leaf),
589 source: PathSource::Profile,
590 };
591 InstancePaths {
592 instance_dir: PathEntry::default_at(INSTANCE_DIR),
593 manifest: PathEntry::default_at(MANIFEST_PATH),
594 declaration: PathEntry::default_at(CONFIG_PATH),
595 debt: PathEntry::default_at(DEBT_PATH),
596 legacy_debt: PathEntry::default_at(LEGACY_DEBT_PATH),
597 hooks_config: PathEntry::default_at(HOOKS_CONFIG_PATH),
598 agents_digest: PathEntry::default_at(AGENTS_DIGEST_PATH),
599 docs_root: PathEntry {
600 path: docs.clone(),
601 source: PathSource::Profile,
602 },
603 specs: under("specs"),
604 decisions: under("decisions"),
605 reference: under("reference"),
606 guides: under("guides"),
607 lint_config: under(markdownlint::CLI2_NAMES[0]),
608 lint_discovery: LintDiscovery {
609 repository_root: markdownlint::discovery_names()
610 .map(PathEntry::default_at)
611 .collect(),
612 refused_at_docs_root: markdownlint::LIBRARY_NAMES
613 .iter()
614 .map(|name| under(name))
615 .collect(),
616 refused_beneath: vec![under("specs"), under("decisions")],
617 },
618 }
619}
620
621#[must_use]
623pub fn recorded_paths(docs_root: DocsRoot) -> InstancePaths {
624 let mut paths = instance_paths(docs_root);
625 for entry in [
626 &mut paths.docs_root,
627 &mut paths.specs,
628 &mut paths.decisions,
629 &mut paths.reference,
630 &mut paths.guides,
631 &mut paths.lint_config,
632 ]
633 .into_iter()
634 .chain(&mut paths.lint_discovery.refused_at_docs_root)
635 .chain(&mut paths.lint_discovery.refused_beneath)
636 {
637 entry.source = PathSource::Recorded;
638 }
639 paths
640}
641
642#[must_use]
644pub fn candidates() -> BTreeMap<String, CandidatePaths> {
645 ProfileId::every()
646 .map(|profile| {
647 (
648 profile.as_str().to_string(),
649 CandidatePaths {
650 profile,
651 destinations: instance_paths(profile.profile().docs_root),
652 },
653 )
654 })
655 .collect()
656}
657
658#[must_use]
665pub fn docs_scratch_location(recorded: Option<&Utf8Path>, env: &UserEnv) -> ProjectLocation {
666 if env.docs_scratch.is_some() {
667 return ProjectLocation::Env {
668 variable: DOCS_SCRATCH_VAR,
669 value: env.docs_scratch.clone(),
670 };
671 }
672 let Some(path) = recorded else {
673 return ProjectLocation::None;
674 };
675 if path.is_absolute() || path.starts_with("..") {
676 return ProjectLocation::External {
677 path: path.to_owned(),
678 source: PathSource::Recorded,
679 };
680 }
681 ProjectLocation::Untracked {
682 path: path.to_owned(),
683 source: PathSource::Recorded,
684 }
685}
686
687pub const DOCS_SCRATCH_LEAVES: &[&str] = &[".docs-scratch", ".scratch"];
693
694pub fn proposals(env: &UserEnv, held: impl Fn(&Utf8Path) -> bool) -> Proposals {
700 let mut docs_scratch: Vec<LocationChoice> = Vec::new();
701 for leaf in DOCS_SCRATCH_LEAVES {
702 let candidate = Utf8PathBuf::from(*leaf);
703 if held(&candidate) {
704 docs_scratch.push(LocationChoice::Observed { path: candidate });
705 }
706 }
707 docs_scratch.push(LocationChoice::Env {
708 variable: DOCS_SCRATCH_VAR,
709 value: env.docs_scratch.clone(),
710 });
711 docs_scratch.push(LocationChoice::Operator);
712 docs_scratch.push(LocationChoice::None);
713
714 Proposals { docs_scratch }
715}
716
717#[cfg(test)]
718mod tests {
719 use super::*;
720
721 fn env(home: &str) -> UserEnv {
722 UserEnv {
723 home: Some(Utf8PathBuf::from(home)),
724 ..UserEnv::default()
725 }
726 }
727
728 #[test]
729 fn the_agent_root_table_has_two_rows_and_resolves_each_with_its_source() {
730 assert_eq!(AGENT_ROOTS.len(), 2);
731 let resolved = env("/h").agent_roots(&[AgentId::Claude, AgentId::Agents]);
732 assert_eq!(resolved.len(), 2);
733 assert_eq!(resolved[0].path, "/h/.claude/skills");
734 assert_eq!(resolved[0].source, PathSource::Default);
735 assert_eq!(resolved[0].variable, None);
736 assert_eq!(resolved[1].path, "/h/.agents/skills");
737 assert_eq!(resolved[1].id, AgentId::Agents);
738 }
739
740 #[test]
741 fn claude_config_dir_relocates_the_claude_root_and_nothing_else() {
742 let moved = UserEnv {
743 claude_config_dir: Some(Utf8PathBuf::from("/elsewhere/claude")),
744 ..env("/h")
745 };
746 let resolved = moved.agent_roots(&[AgentId::Claude, AgentId::Agents]);
747 assert_eq!(resolved[0].path, "/elsewhere/claude/skills");
748 assert_eq!(resolved[0].source, PathSource::Env);
749 assert_eq!(resolved[0].variable, Some(CLAUDE_CONFIG_DIR_VAR));
750 assert_eq!(resolved[1].path, "/h/.agents/skills");
751 assert_eq!(resolved[1].source, PathSource::Default);
752 }
753
754 #[test]
755 fn an_empty_claude_config_dir_is_treated_as_unset() {
756 let blank = UserEnv {
758 claude_config_dir: None,
759 ..env("/h")
760 };
761 assert_eq!(
762 blank.agent_root(AgentId::Claude).map(|root| root.path),
763 Some(Utf8PathBuf::from("/h/.claude/skills"))
764 );
765 }
766
767 #[test]
768 fn two_selected_roots_that_resolve_to_one_path_are_returned_once() {
769 let collided = UserEnv {
770 claude_config_dir: Some(Utf8PathBuf::from("/h/.agents")),
771 ..env("/h")
772 };
773 let resolved = collided.agent_roots(&[AgentId::Claude, AgentId::Agents]);
774 assert_eq!(resolved.len(), 1);
775 assert_eq!(resolved[0].path, "/h/.agents/skills");
776 assert_eq!(resolved[0].id, AgentId::Claude);
777 }
778
779 #[test]
780 fn the_cache_root_follows_xdg_cache_home_and_its_default() {
781 assert_eq!(
782 env("/h").cache_root(),
783 Some(PathEntry::default_at("/h/.cache/spec-driven-docs"))
784 );
785 let moved = UserEnv {
786 xdg_cache_home: Some(Utf8PathBuf::from("/c")),
787 ..env("/h")
788 };
789 assert_eq!(
790 moved.cache_root(),
791 Some(PathEntry::from_env("/c/spec-driven-docs"))
792 );
793 }
794
795 #[test]
796 fn the_state_root_follows_xdg_state_home_and_its_default() {
797 assert_eq!(
798 env("/h").state_root(),
799 Some(PathEntry::default_at("/h/.local/state/spec-driven-docs"))
800 );
801 let moved = UserEnv {
802 xdg_state_home: Some(Utf8PathBuf::from("/s")),
803 ..env("/h")
804 };
805 assert_eq!(
806 moved.state_root(),
807 Some(PathEntry::from_env("/s/spec-driven-docs"))
808 );
809 assert_eq!(
810 moved.legacy_state_root(),
811 Some(Utf8PathBuf::from("/h/.local/state/spec-driven-docs"))
812 );
813 }
814
815 #[test]
816 fn the_user_paths_hang_off_the_two_roots() {
817 let paths = env("/h").user_paths().unwrap();
818 assert_eq!(
819 paths.skill_receipt.unwrap().path,
820 "/h/.local/state/spec-driven-docs/skills.json"
821 );
822 }
823
824 #[test]
825 fn the_home_relative_constants_agree_with_the_resolved_roots() {
826 let paths = env("/h").user_paths().unwrap();
827 assert_eq!(
828 paths.skill_receipt.unwrap().path,
829 Utf8Path::new("/h").join(LEGACY_SKILL_RECEIPT_PATH)
830 );
831 }
832
833 #[test]
834 fn a_candidate_set_exists_for_every_profile() {
835 let candidates = candidates();
836 assert_eq!(candidates.len(), 2);
837 assert_eq!(candidates["codebase"].destinations.specs.path, "docs/specs");
838 assert_eq!(
839 candidates["knowledge-base"].destinations.specs.path,
840 "_docs/specs"
841 );
842 assert_eq!(
843 candidates["codebase"].destinations.declaration.source,
844 PathSource::Default
845 );
846 assert_eq!(
847 candidates["codebase"].destinations.specs.source,
848 PathSource::Profile
849 );
850 }
851
852 #[test]
853 fn a_recorded_location_reports_as_recorded_and_an_override_as_env() {
854 let overridden = UserEnv {
855 docs_scratch: Some("elsewhere".to_string()),
856 ..env("/h")
857 };
858 assert_eq!(
859 docs_scratch_location(Some(Utf8Path::new(".docs-scratch")), &overridden),
860 ProjectLocation::Env {
861 variable: DOCS_SCRATCH_VAR,
862 value: Some("elsewhere".to_string()),
863 }
864 );
865 }
866
867 #[test]
868 fn a_scratch_beside_the_checkout_reports_as_external() {
869 let plain = env("/h");
870 assert_eq!(
871 docs_scratch_location(Some(Utf8Path::new("../x.docs-scratch")), &plain),
872 ProjectLocation::External {
873 path: Utf8PathBuf::from("../x.docs-scratch"),
874 source: PathSource::Recorded,
875 }
876 );
877 assert_eq!(
878 docs_scratch_location(Some(Utf8Path::new(".docs-scratch")), &plain),
879 ProjectLocation::Untracked {
880 path: Utf8PathBuf::from(".docs-scratch"),
881 source: PathSource::Recorded,
882 }
883 );
884 assert_eq!(docs_scratch_location(None, &plain), ProjectLocation::None);
885 }
886
887 #[test]
888 fn a_proposal_carries_a_path_only_where_the_target_holds_one() {
889 let plain = env("/h");
890 let bare = proposals(&plain, |_| false);
891 assert!(
892 !bare
893 .docs_scratch
894 .iter()
895 .any(|choice| matches!(choice, LocationChoice::Observed { .. }))
896 );
897 assert_eq!(bare.docs_scratch.last(), Some(&LocationChoice::None));
898
899 let observed = proposals(&plain, |path| path == Utf8Path::new(".docs-scratch"));
900 assert_eq!(
901 observed.docs_scratch.first(),
902 Some(&LocationChoice::Observed {
903 path: Utf8PathBuf::from(".docs-scratch")
904 })
905 );
906 }
907}