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]
540 pub fn agent_roots(&self, selected: &[AgentId]) -> Vec<AgentRootEntry> {
541 let mut resolved: Vec<AgentRootEntry> = Vec::new();
542 for row in AGENT_ROOTS {
543 if !selected.contains(&row.id) {
544 continue;
545 }
546 let Some(entry) = self.agent_root(row.id) else {
547 continue;
548 };
549 if resolved.iter().any(|held| held.path == entry.path) {
550 continue;
551 }
552 resolved.push(entry);
553 }
554 resolved
555 }
556
557 #[must_use]
559 pub fn user_paths(&self) -> Option<UserPaths> {
560 let state = self.state_root()?;
561 let cache = self.cache_root()?;
562 Some(UserPaths {
563 skill_receipt: Some(PathEntry {
564 path: state.path.join(SKILL_RECEIPT_FILE),
565 source: state.source,
566 }),
567 agent_roots: self.agent_roots(&[AgentId::Claude, AgentId::Agents]),
568 state_root: state,
569 cache_root: cache,
570 })
571 }
572}
573
574#[must_use]
576pub fn instance_paths(docs_root: DocsRoot) -> InstancePaths {
577 let docs = Utf8PathBuf::from(docs_root.as_str());
578 let under = |leaf: &str| PathEntry {
579 path: docs.join(leaf),
580 source: PathSource::Profile,
581 };
582 InstancePaths {
583 instance_dir: PathEntry::default_at(INSTANCE_DIR),
584 manifest: PathEntry::default_at(MANIFEST_PATH),
585 declaration: PathEntry::default_at(CONFIG_PATH),
586 debt: PathEntry::default_at(DEBT_PATH),
587 legacy_debt: PathEntry::default_at(LEGACY_DEBT_PATH),
588 hooks_config: PathEntry::default_at(HOOKS_CONFIG_PATH),
589 agents_digest: PathEntry::default_at(AGENTS_DIGEST_PATH),
590 docs_root: PathEntry {
591 path: docs.clone(),
592 source: PathSource::Profile,
593 },
594 specs: under("specs"),
595 decisions: under("decisions"),
596 reference: under("reference"),
597 guides: under("guides"),
598 lint_config: under(markdownlint::CLI2_NAMES[0]),
599 lint_discovery: LintDiscovery {
600 repository_root: markdownlint::discovery_names()
601 .map(PathEntry::default_at)
602 .collect(),
603 refused_at_docs_root: markdownlint::LIBRARY_NAMES
604 .iter()
605 .map(|name| under(name))
606 .collect(),
607 refused_beneath: vec![under("specs"), under("decisions")],
608 },
609 }
610}
611
612#[must_use]
614pub fn recorded_paths(docs_root: DocsRoot) -> InstancePaths {
615 let mut paths = instance_paths(docs_root);
616 for entry in [
617 &mut paths.docs_root,
618 &mut paths.specs,
619 &mut paths.decisions,
620 &mut paths.reference,
621 &mut paths.guides,
622 &mut paths.lint_config,
623 ]
624 .into_iter()
625 .chain(&mut paths.lint_discovery.refused_at_docs_root)
626 .chain(&mut paths.lint_discovery.refused_beneath)
627 {
628 entry.source = PathSource::Recorded;
629 }
630 paths
631}
632
633#[must_use]
635pub fn candidates() -> BTreeMap<String, CandidatePaths> {
636 ProfileId::every()
637 .map(|profile| {
638 (
639 profile.as_str().to_string(),
640 CandidatePaths {
641 profile,
642 destinations: instance_paths(profile.profile().docs_root),
643 },
644 )
645 })
646 .collect()
647}
648
649#[must_use]
656pub fn docs_scratch_location(recorded: Option<&Utf8Path>, env: &UserEnv) -> ProjectLocation {
657 if env.docs_scratch.is_some() {
658 return ProjectLocation::Env {
659 variable: DOCS_SCRATCH_VAR,
660 value: env.docs_scratch.clone(),
661 };
662 }
663 let Some(path) = recorded else {
664 return ProjectLocation::None;
665 };
666 if path.is_absolute() || path.starts_with("..") {
667 return ProjectLocation::External {
668 path: path.to_owned(),
669 source: PathSource::Recorded,
670 };
671 }
672 ProjectLocation::Untracked {
673 path: path.to_owned(),
674 source: PathSource::Recorded,
675 }
676}
677
678pub const DOCS_SCRATCH_LEAVES: &[&str] = &[".docs-scratch", ".scratch"];
684
685pub fn proposals(env: &UserEnv, held: impl Fn(&Utf8Path) -> bool) -> Proposals {
691 let mut docs_scratch: Vec<LocationChoice> = Vec::new();
692 for leaf in DOCS_SCRATCH_LEAVES {
693 let candidate = Utf8PathBuf::from(*leaf);
694 if held(&candidate) {
695 docs_scratch.push(LocationChoice::Observed { path: candidate });
696 }
697 }
698 docs_scratch.push(LocationChoice::Env {
699 variable: DOCS_SCRATCH_VAR,
700 value: env.docs_scratch.clone(),
701 });
702 docs_scratch.push(LocationChoice::Operator);
703 docs_scratch.push(LocationChoice::None);
704
705 Proposals { docs_scratch }
706}
707
708#[cfg(test)]
709mod tests {
710 use super::*;
711
712 fn env(home: &str) -> UserEnv {
713 UserEnv {
714 home: Some(Utf8PathBuf::from(home)),
715 ..UserEnv::default()
716 }
717 }
718
719 #[test]
720 fn the_agent_root_table_has_two_rows_and_resolves_each_with_its_source() {
721 assert_eq!(AGENT_ROOTS.len(), 2);
722 let resolved = env("/h").agent_roots(&[AgentId::Claude, AgentId::Agents]);
723 assert_eq!(resolved.len(), 2);
724 assert_eq!(resolved[0].path, "/h/.claude/skills");
725 assert_eq!(resolved[0].source, PathSource::Default);
726 assert_eq!(resolved[0].variable, None);
727 assert_eq!(resolved[1].path, "/h/.agents/skills");
728 assert_eq!(resolved[1].id, AgentId::Agents);
729 }
730
731 #[test]
732 fn claude_config_dir_relocates_the_claude_root_and_nothing_else() {
733 let moved = UserEnv {
734 claude_config_dir: Some(Utf8PathBuf::from("/elsewhere/claude")),
735 ..env("/h")
736 };
737 let resolved = moved.agent_roots(&[AgentId::Claude, AgentId::Agents]);
738 assert_eq!(resolved[0].path, "/elsewhere/claude/skills");
739 assert_eq!(resolved[0].source, PathSource::Env);
740 assert_eq!(resolved[0].variable, Some(CLAUDE_CONFIG_DIR_VAR));
741 assert_eq!(resolved[1].path, "/h/.agents/skills");
742 assert_eq!(resolved[1].source, PathSource::Default);
743 }
744
745 #[test]
746 fn an_empty_claude_config_dir_is_treated_as_unset() {
747 let blank = UserEnv {
749 claude_config_dir: None,
750 ..env("/h")
751 };
752 assert_eq!(
753 blank.agent_root(AgentId::Claude).map(|root| root.path),
754 Some(Utf8PathBuf::from("/h/.claude/skills"))
755 );
756 }
757
758 #[test]
759 fn two_selected_roots_that_resolve_to_one_path_are_returned_once() {
760 let collided = UserEnv {
761 claude_config_dir: Some(Utf8PathBuf::from("/h/.agents")),
762 ..env("/h")
763 };
764 let resolved = collided.agent_roots(&[AgentId::Claude, AgentId::Agents]);
765 assert_eq!(resolved.len(), 1);
766 assert_eq!(resolved[0].path, "/h/.agents/skills");
767 assert_eq!(resolved[0].id, AgentId::Claude);
768 }
769
770 #[test]
771 fn the_cache_root_follows_xdg_cache_home_and_its_default() {
772 assert_eq!(
773 env("/h").cache_root(),
774 Some(PathEntry::default_at("/h/.cache/spec-driven-docs"))
775 );
776 let moved = UserEnv {
777 xdg_cache_home: Some(Utf8PathBuf::from("/c")),
778 ..env("/h")
779 };
780 assert_eq!(
781 moved.cache_root(),
782 Some(PathEntry::from_env("/c/spec-driven-docs"))
783 );
784 }
785
786 #[test]
787 fn the_state_root_follows_xdg_state_home_and_its_default() {
788 assert_eq!(
789 env("/h").state_root(),
790 Some(PathEntry::default_at("/h/.local/state/spec-driven-docs"))
791 );
792 let moved = UserEnv {
793 xdg_state_home: Some(Utf8PathBuf::from("/s")),
794 ..env("/h")
795 };
796 assert_eq!(
797 moved.state_root(),
798 Some(PathEntry::from_env("/s/spec-driven-docs"))
799 );
800 assert_eq!(
801 moved.legacy_state_root(),
802 Some(Utf8PathBuf::from("/h/.local/state/spec-driven-docs"))
803 );
804 }
805
806 #[test]
807 fn the_user_paths_hang_off_the_two_roots() {
808 let paths = env("/h").user_paths().unwrap();
809 assert_eq!(
810 paths.skill_receipt.unwrap().path,
811 "/h/.local/state/spec-driven-docs/skills.json"
812 );
813 }
814
815 #[test]
816 fn the_home_relative_constants_agree_with_the_resolved_roots() {
817 let paths = env("/h").user_paths().unwrap();
818 assert_eq!(
819 paths.skill_receipt.unwrap().path,
820 Utf8Path::new("/h").join(LEGACY_SKILL_RECEIPT_PATH)
821 );
822 }
823
824 #[test]
825 fn a_candidate_set_exists_for_every_profile() {
826 let candidates = candidates();
827 assert_eq!(candidates.len(), 2);
828 assert_eq!(candidates["codebase"].destinations.specs.path, "docs/specs");
829 assert_eq!(
830 candidates["knowledge-base"].destinations.specs.path,
831 "_docs/specs"
832 );
833 assert_eq!(
834 candidates["codebase"].destinations.declaration.source,
835 PathSource::Default
836 );
837 assert_eq!(
838 candidates["codebase"].destinations.specs.source,
839 PathSource::Profile
840 );
841 }
842
843 #[test]
844 fn a_recorded_location_reports_as_recorded_and_an_override_as_env() {
845 let overridden = UserEnv {
846 docs_scratch: Some("elsewhere".to_string()),
847 ..env("/h")
848 };
849 assert_eq!(
850 docs_scratch_location(Some(Utf8Path::new(".docs-scratch")), &overridden),
851 ProjectLocation::Env {
852 variable: DOCS_SCRATCH_VAR,
853 value: Some("elsewhere".to_string()),
854 }
855 );
856 }
857
858 #[test]
859 fn a_scratch_beside_the_checkout_reports_as_external() {
860 let plain = env("/h");
861 assert_eq!(
862 docs_scratch_location(Some(Utf8Path::new("../x.docs-scratch")), &plain),
863 ProjectLocation::External {
864 path: Utf8PathBuf::from("../x.docs-scratch"),
865 source: PathSource::Recorded,
866 }
867 );
868 assert_eq!(
869 docs_scratch_location(Some(Utf8Path::new(".docs-scratch")), &plain),
870 ProjectLocation::Untracked {
871 path: Utf8PathBuf::from(".docs-scratch"),
872 source: PathSource::Recorded,
873 }
874 );
875 assert_eq!(docs_scratch_location(None, &plain), ProjectLocation::None);
876 }
877
878 #[test]
879 fn a_proposal_carries_a_path_only_where_the_target_holds_one() {
880 let plain = env("/h");
881 let bare = proposals(&plain, |_| false);
882 assert!(
883 !bare
884 .docs_scratch
885 .iter()
886 .any(|choice| matches!(choice, LocationChoice::Observed { .. }))
887 );
888 assert_eq!(bare.docs_scratch.last(), Some(&LocationChoice::None));
889
890 let observed = proposals(&plain, |path| path == Utf8Path::new(".docs-scratch"));
891 assert_eq!(
892 observed.docs_scratch.first(),
893 Some(&LocationChoice::Observed {
894 path: Utf8PathBuf::from(".docs-scratch")
895 })
896 );
897 }
898}