Skip to main content

tea_coding/resources/
mod.rs

1//! Trusted bounded declarative context, skill, and prompt-template discovery.
2
3mod context_files;
4mod frontmatter;
5mod prompts;
6mod skills;
7
8use std::path::{Path, PathBuf};
9
10use tea_context::{SkillMetadata, WorkspaceInstruction};
11
12pub use prompts::PromptTemplate;
13pub use skills::{DiscoveredSkill, LoadedSkill};
14
15use crate::{CodingError, ProjectAccess};
16
17/// Bounded safe diagnostic produced while optional resources are skipped.
18#[derive(Debug, Clone, PartialEq, Eq)]
19pub struct ResourceDiagnostic {
20    code: &'static str,
21    subject: String,
22}
23
24impl ResourceDiagnostic {
25    pub(crate) fn new(code: &'static str, subject: &str) -> Self {
26        Self {
27            code,
28            subject: subject.to_owned(),
29        }
30    }
31    /// Returns the machine-readable diagnostic code.
32    #[must_use]
33    pub const fn code(&self) -> &'static str {
34        self.code
35    }
36    /// Returns a bounded workspace-relative subject.
37    #[must_use]
38    pub fn subject(&self) -> &str {
39        &self.subject
40    }
41}
42
43/// Immutable deterministic catalog discovered for one workspace.
44#[derive(Debug, Clone)]
45pub struct ResourceCatalog {
46    context: Vec<WorkspaceInstruction>,
47    skills: Vec<DiscoveredSkill>,
48    prompts: Vec<PromptTemplate>,
49    diagnostics: Vec<ResourceDiagnostic>,
50}
51
52impl ResourceCatalog {
53    /// Discovers global resources and project resources only when trusted.
54    ///
55    /// # Errors
56    ///
57    /// Rejects malformed, duplicate, oversized, or escaping resources.
58    #[allow(clippy::too_many_arguments)]
59    pub fn discover(
60        boundary: &Path,
61        workspace: &Path,
62        access: ProjectAccess,
63        global_skill_roots: &[PathBuf],
64        project_skill_roots: &[PathBuf],
65        global_prompt_root: Option<&Path>,
66        project_prompt_root: Option<&Path>,
67    ) -> Result<Self, CodingError> {
68        let (context, diagnostics) = context_files::discover(boundary, workspace, access)?;
69        let mut skill_roots = global_skill_roots.to_vec();
70        if access == ProjectAccess::Trusted {
71            skill_roots.extend_from_slice(project_skill_roots);
72        }
73        let skills = skills::discover(&skill_roots)?;
74        let prompts = prompts::discover(
75            global_prompt_root,
76            (access == ProjectAccess::Trusted)
77                .then_some(project_prompt_root)
78                .flatten(),
79        )?;
80        Ok(Self {
81            context,
82            skills,
83            prompts,
84            diagnostics,
85        })
86    }
87
88    /// Adds explicit workspace-relative context files through the workspace capability.
89    ///
90    /// # Errors
91    ///
92    /// Rejects duplicate, escaping, non-UTF-8, oversized, changed, or unreadable files.
93    pub fn add_explicit_context_files(
94        &mut self,
95        workspace: &tea_coding_tools::WorkspaceRoot,
96        paths: &[String],
97    ) -> Result<(), CodingError> {
98        context_files::add_explicit(workspace, paths, &mut self.context)
99    }
100
101    /// Applies resolved resource feature switches without re-reading any source.
102    pub fn apply_settings(&mut self, context_files: bool, prompt_templates: bool) {
103        if !context_files {
104            self.context.clear();
105        }
106        if !prompt_templates {
107            self.prompts.clear();
108        }
109    }
110
111    /// Returns deterministic context instructions.
112    #[must_use]
113    pub fn context(&self) -> &[WorkspaceInstruction] {
114        &self.context
115    }
116    /// Returns discovered skills sorted by ID.
117    #[must_use]
118    pub fn skills(&self) -> &[DiscoveredSkill] {
119        &self.skills
120    }
121    /// Returns prompt templates sorted by name.
122    #[must_use]
123    pub fn prompts(&self) -> &[PromptTemplate] {
124        &self.prompts
125    }
126    /// Returns safe discovery diagnostics.
127    #[must_use]
128    pub fn diagnostics(&self) -> &[ResourceDiagnostic] {
129        &self.diagnostics
130    }
131    /// Projects skill metadata without loading skill bodies.
132    #[must_use]
133    pub fn skill_metadata(&self) -> Vec<SkillMetadata> {
134        self.skills
135            .iter()
136            .map(|skill| skill.metadata().clone())
137            .collect()
138    }
139    /// Loads an explicitly invoked skill.
140    ///
141    /// # Errors
142    ///
143    /// Rejects unknown or invalid invocation syntax.
144    pub fn invoke_skill(&self, invocation: &str) -> Result<LoadedSkill, CodingError> {
145        let name = invocation
146            .strip_prefix("/skill:")
147            .map(|remaining| {
148                remaining
149                    .split_once(' ')
150                    .map_or(remaining, |(name, _)| name)
151            })
152            .filter(|name| !name.is_empty())
153            .ok_or_else(|| {
154                crate::CodingError::new(
155                    crate::CodingErrorCode::InvalidInput,
156                    "skill invocation is invalid",
157                )
158            })?;
159        self.skills
160            .iter()
161            .find(|skill| skill.metadata().id().as_str() == name)
162            .ok_or_else(|| {
163                crate::CodingError::new(crate::CodingErrorCode::NotFound, "skill is not registered")
164            })?
165            .invoke(invocation)
166    }
167}