Skip to main content

dekopon_config/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg_attr(test, allow(clippy::unwrap_used))]
3#![cfg_attr(
4    test,
5    allow(
6        clippy::disallowed_methods,
7        clippy::disallowed_types,
8        reason = "tests spawn, join and drain freely; production sites carry their own expectation"
9    )
10)]
11use std::{
12    collections::BTreeMap,
13    env, fmt, fs, io,
14    path::{Path, PathBuf},
15    str::FromStr,
16};
17
18use dekopon_core::{AgentId, IdentifierError};
19use dekopon_protocol::{Agent, ApiVersion};
20use serde::Deserialize;
21use serde_yaml::Value;
22use thiserror::Error;
23
24mod projection;
25pub mod skill;
26
27pub use projection::{Projection, ProjectionError};
28pub use skill::{Skill, SkillError, SkillResource, load_skill};
29
30pub const CONFIG_ENV: &str = "DEKOPON_CONFIG";
31pub const MAX_INSTRUCTIONS_BYTES: usize = 256 * 1024;
32
33#[derive(Clone, Debug)]
34pub struct LocalCatalog {
35    source: PathBuf,
36    agents: BTreeMap<AgentId, Agent>,
37    skills: BTreeMap<AgentId, Vec<Skill>>,
38    files: Vec<(PathBuf, String)>,
39}
40
41impl LocalCatalog {
42    pub fn load(path: impl AsRef<Path>) -> Result<Self, ConfigError> {
43        let path = path.as_ref();
44        let read = |file: &Path| {
45            fs::read_to_string(file).map_err(|source| ConfigError::Read {
46                path: file.display().to_string(),
47                source,
48            })
49        };
50        if !fs::metadata(path).is_ok_and(|metadata| metadata.is_dir()) {
51            return Self::from_str(path, &read(path)?);
52        }
53        let entries = fs::read_dir(path).map_err(|source| ConfigError::Read {
54            path: path.display().to_string(),
55            source,
56        })?;
57        let mut files = Vec::new();
58        for entry in entries {
59            let entry = entry.map_err(|source| ConfigError::Read {
60                path: path.display().to_string(),
61                source,
62            })?;
63            let file = entry.path();
64            if file
65                .extension()
66                .is_some_and(|extension| extension == "yaml")
67            {
68                files.push(file);
69            }
70        }
71        files.sort();
72        let sources = files
73            .iter()
74            .map(|file| Ok((file.clone(), read(file)?)))
75            .collect::<Result<Vec<_>, ConfigError>>()?;
76        Self::from_sources(path, sources)
77    }
78
79    pub fn from_str(source: impl AsRef<Path>, contents: &str) -> Result<Self, ConfigError> {
80        let source = source.as_ref();
81        Self::from_sources(source, vec![(source.to_path_buf(), contents.to_owned())])
82    }
83
84    #[expect(
85        clippy::wildcard_enum_match_arm,
86        reason = "reshaped by the unit that next rewrites this"
87    )]
88    fn from_sources(source: &Path, files: Vec<(PathBuf, String)>) -> Result<Self, ConfigError> {
89        let source = source.to_path_buf();
90        let source_name = source.display().to_string();
91        let many = files.len() > 1;
92        let mut resources = Vec::new();
93
94        for (file, contents) in &files {
95            let file_name = file
96                .file_name()
97                .map(|name| name.to_string_lossy().into_owned())
98                .unwrap_or_default();
99            let prefix = if many {
100                format!("{file_name} ")
101            } else {
102                String::new()
103            };
104            for (document_index, document) in
105                serde_yaml::Deserializer::from_str(contents).enumerate()
106            {
107                let document_number = document_index + 1;
108                let value = Value::deserialize(document).map_err(|error| {
109                    let location = error.location().map_or_else(String::new, |location| {
110                        format!(" at line {}, column {}", location.line(), location.column())
111                    });
112                    ConfigError::Parse {
113                        path: file.display().to_string(),
114                        origin: format!("document {document_number}{location}"),
115                        source: error,
116                    }
117                })?;
118
119                match value {
120                    Value::Null => {}
121                    Value::Sequence(items) => {
122                        for (item_index, item) in items.into_iter().enumerate() {
123                            resources.push((
124                                format!(
125                                    "{prefix}document {document_number}, item {}",
126                                    item_index + 1
127                                ),
128                                item,
129                            ));
130                        }
131                    }
132                    other => resources.push((format!("{prefix}document {document_number}"), other)),
133                }
134            }
135        }
136
137        if resources.is_empty() {
138            return Err(ConfigError::Empty { path: source_name });
139        }
140
141        let mut agents = ResourceSet::<Agent>::default();
142        let mut problems = Vec::new();
143
144        for (origin, value) in resources {
145            let outcome = match string_field(&value, "kind").map(str::to_owned) {
146                Some(kind) => match kind.as_str() {
147                    Agent::KIND => agents.insert(&origin, value),
148                    _ => Err(CatalogProblem::UnsupportedKind { origin, kind }),
149                },
150                None => Err(CatalogProblem::MissingKind { origin }),
151            };
152            if let Err(problem) = outcome {
153                problems.push(problem);
154            }
155        }
156        let base = if many || source.is_dir() {
157            source.clone()
158        } else {
159            source.parent().map(Path::to_path_buf).unwrap_or_default()
160        };
161        let skills = load_agent_skills(&agents, &base, &mut problems);
162        let mut agents = agents.into_map();
163        for (id, agent) in &mut agents {
164            let Some(file) = agent.spec.instructions_file.clone() else {
165                continue;
166            };
167            if agent.spec.instructions.is_some() {
168                problems.push(CatalogProblem::InstructionsTwice {
169                    agent: id.to_string(),
170                });
171                continue;
172            }
173            let resolved = if file.is_absolute() {
174                file.clone()
175            } else {
176                base.join(&file)
177            };
178            // Read like the catalog yaml beside it: a ConfigMap mount makes every key a symlink.
179            match fs::read_to_string(&resolved) {
180                Ok(text) if text.len() > MAX_INSTRUCTIONS_BYTES => {
181                    problems.push(CatalogProblem::InstructionsTooLarge {
182                        agent: id.to_string(),
183                        length: text.len(),
184                        maximum: MAX_INSTRUCTIONS_BYTES,
185                    });
186                }
187                Ok(text) => agent.spec.instructions = Some(text),
188                Err(source) => problems.push(CatalogProblem::Instructions {
189                    agent: id.to_string(),
190                    path: file.display().to_string(),
191                    source,
192                }),
193            }
194        }
195
196        if !problems.is_empty() {
197            return Err(ConfigError::Invalid {
198                path: source_name,
199                problems,
200            });
201        }
202
203        Ok(Self {
204            source,
205            agents,
206            skills,
207            files,
208        })
209    }
210
211    #[must_use]
212    pub fn source(&self) -> &Path {
213        &self.source
214    }
215
216    pub fn agents(&self) -> impl ExactSizeIterator<Item = &Agent> {
217        self.agents.values()
218    }
219
220    #[must_use]
221    pub fn agent(&self, id: &AgentId) -> Option<&Agent> {
222        self.agents.get(id)
223    }
224
225    #[must_use]
226    pub fn agent_skills(&self, id: &AgentId) -> &[Skill] {
227        self.skills.get(id).map_or(&[], Vec::as_slice)
228    }
229
230    #[must_use]
231    pub fn files(&self) -> &[(PathBuf, String)] {
232        &self.files
233    }
234}
235
236fn string_field<'a>(value: &'a Value, field: &str) -> Option<&'a str> {
237    value
238        .as_mapping()?
239        .get(Value::String(field.to_owned()))
240        .and_then(Value::as_str)
241}
242
243trait Resource: Sized + for<'de> Deserialize<'de> {
244    type Id: FromStr<Err = IdentifierError> + Ord + fmt::Display;
245
246    const KIND: &'static str;
247
248    fn name(&self) -> &str;
249}
250
251impl Resource for Agent {
252    type Id = AgentId;
253    const KIND: &'static str = "Agent";
254
255    fn name(&self) -> &str {
256        &self.metadata.name
257    }
258}
259
260struct ResourceSet<T: Resource> {
261    entries: BTreeMap<T::Id, (String, T)>,
262}
263
264impl<T: Resource> Default for ResourceSet<T> {
265    fn default() -> Self {
266        Self {
267            entries: BTreeMap::new(),
268        }
269    }
270}
271
272impl<T: Resource> ResourceSet<T> {
273    fn insert(&mut self, origin: &str, value: Value) -> Result<(), CatalogProblem> {
274        if let Some(version) = string_field(&value, "apiVersion")
275            && version != ApiVersion::V1Alpha1.to_string()
276        {
277            return Err(CatalogProblem::UnsupportedApiVersion {
278                origin: origin.to_owned(),
279                version: version.to_owned(),
280            });
281        }
282
283        let resource =
284            serde_yaml::from_value::<T>(value).map_err(|source| CatalogProblem::Decode {
285                origin: origin.to_owned(),
286                kind: T::KIND,
287                source,
288            })?;
289        let id =
290            resource
291                .name()
292                .parse::<T::Id>()
293                .map_err(|source| CatalogProblem::InvalidName {
294                    origin: origin.to_owned(),
295                    kind: T::KIND,
296                    name: resource.name().to_owned(),
297                    source: Box::new(source),
298                })?;
299        if let Some((first, _)) = self.entries.get(&id) {
300            return Err(CatalogProblem::DuplicateResource {
301                kind: T::KIND,
302                name: id.to_string(),
303                first: first.clone(),
304                duplicate: origin.to_owned(),
305            });
306        }
307        self.entries.insert(id, (origin.to_owned(), resource));
308        Ok(())
309    }
310
311    fn iter(&self) -> impl Iterator<Item = (&T::Id, &T)> {
312        self.entries
313            .iter()
314            .map(|(id, (_, resource))| (id, resource))
315    }
316
317    fn into_map(self) -> BTreeMap<T::Id, T> {
318        self.entries
319            .into_iter()
320            .map(|(id, (_, resource))| (id, resource))
321            .collect()
322    }
323}
324
325fn load_agent_skills(
326    agents: &ResourceSet<Agent>,
327    base: &Path,
328    problems: &mut Vec<CatalogProblem>,
329) -> BTreeMap<AgentId, Vec<Skill>> {
330    let mut mounted = BTreeMap::new();
331    for (agent_id, agent) in agents.iter() {
332        if agent.spec.skills.is_empty() {
333            continue;
334        }
335        let mut skills = Vec::with_capacity(agent.spec.skills.len());
336        let mut names = BTreeMap::new();
337        for path in &agent.spec.skills {
338            let resolved = if path.is_absolute() {
339                path.clone()
340            } else {
341                base.join(path)
342            };
343            let skill = match skill::load_skill(&resolved) {
344                Ok(skill) => skill,
345                Err(source) => {
346                    problems.push(CatalogProblem::Skill {
347                        agent: agent_id.to_string(),
348                        path: path.display().to_string(),
349                        source: Box::new(source),
350                    });
351                    continue;
352                }
353            };
354            // Two skill directories sharing one name would give a model two indistinguishable read
355            // targets, so the second is refused rather than shadowing the first.
356            if let Some(first) = names.insert(skill.name().clone(), path.display().to_string()) {
357                problems.push(CatalogProblem::DuplicateSkill {
358                    agent: agent_id.to_string(),
359                    name: skill.name().to_string(),
360                    first,
361                    duplicate: path.display().to_string(),
362                });
363                continue;
364            }
365            skills.push(skill);
366        }
367        mounted.insert(agent_id.clone(), skills);
368    }
369    mounted
370}
371
372#[derive(Clone, Debug, Eq, PartialEq)]
373pub struct DiscoveryContext {
374    explicit: Option<PathBuf>,
375    environment: Option<PathBuf>,
376    xdg_config_home: Option<PathBuf>,
377    home: Option<PathBuf>,
378    current_directory: PathBuf,
379}
380
381impl DiscoveryContext {
382    pub fn from_process(explicit: Option<PathBuf>) -> Result<Self, ConfigError> {
383        Ok(Self {
384            explicit,
385            environment: env::var_os(CONFIG_ENV)
386                .filter(|value| !value.is_empty())
387                .map(PathBuf::from),
388            xdg_config_home: env::var_os("XDG_CONFIG_HOME")
389                .filter(|value| !value.is_empty())
390                .map(PathBuf::from),
391            home: env::var_os("HOME")
392                .filter(|value| !value.is_empty())
393                .map(PathBuf::from),
394            current_directory: env::current_dir().map_err(ConfigError::CurrentDirectory)?,
395        })
396    }
397
398    #[must_use]
399    pub fn new(
400        explicit: Option<PathBuf>,
401        environment: Option<PathBuf>,
402        xdg_config_home: Option<PathBuf>,
403        home: Option<PathBuf>,
404        current_directory: PathBuf,
405    ) -> Self {
406        Self {
407            explicit,
408            environment,
409            xdg_config_home,
410            home,
411            current_directory,
412        }
413    }
414
415    pub fn resolve(&self) -> Result<PathBuf, ConfigError> {
416        if let Some(path) = &self.explicit {
417            return Ok(path.clone());
418        }
419        if let Some(path) = &self.environment {
420            return Ok(path.clone());
421        }
422
423        let mut searched = Vec::new();
424        if let Some(root) = &self.xdg_config_home {
425            searched.push(root.join("dekopon/config.yaml"));
426        }
427        if let Some(home) = &self.home {
428            searched.push(home.join(".config/dekopon/config.yaml"));
429        }
430        searched.push(self.current_directory.join("dekopon.yaml"));
431
432        for path in &searched {
433            match fs::metadata(path) {
434                Ok(metadata) if metadata.is_file() => return Ok(path.clone()),
435                Ok(_) => {}
436                Err(error) if error.kind() == io::ErrorKind::NotFound => {}
437                // A permission or traversal error might be hiding a higher-precedence config, so
438                // this refuses rather than silently falling through to a lower-precedence file.
439                Err(source) => {
440                    return Err(ConfigError::Candidate {
441                        path: path.display().to_string(),
442                        source,
443                    });
444                }
445            }
446        }
447
448        Err(ConfigError::NotFound {
449            searched: searched
450                .iter()
451                .map(|path| path.display().to_string())
452                .collect::<Vec<_>>()
453                .join(", "),
454        })
455    }
456}
457
458pub fn load_discovered(explicit: Option<PathBuf>) -> Result<LocalCatalog, ConfigError> {
459    let path = DiscoveryContext::from_process(explicit)?.resolve()?;
460    LocalCatalog::load(path)
461}
462
463#[derive(Debug, Error)]
464pub enum ConfigError {
465    #[error("failed to read configuration {path}: {source}")]
466    Read {
467        path: String,
468        #[source]
469        source: io::Error,
470    },
471    #[error("{path}: {origin}: invalid YAML or JSON: {source}")]
472    Parse {
473        path: String,
474        origin: String,
475        #[source]
476        source: serde_yaml::Error,
477    },
478    #[error("{path}: {origin}: invalid {kind}: {source}")]
479    Decode {
480        path: String,
481        origin: String,
482        kind: String,
483        #[source]
484        source: serde_yaml::Error,
485    },
486    #[error("{path}: configuration contains no resources")]
487    Empty { path: String },
488    #[error("{path}: {}", render_problems(.problems))]
489    Invalid {
490        path: String,
491        problems: Vec<CatalogProblem>,
492    },
493    #[error("failed to examine configuration candidate {path}: {source}")]
494    Candidate {
495        path: String,
496        #[source]
497        source: io::Error,
498    },
499    #[error("no Dekopon configuration found; searched: {searched}")]
500    NotFound { searched: String },
501    #[error("could not resolve the current directory: {0}")]
502    CurrentDirectory(#[source] io::Error),
503}
504
505fn render_problems(problems: &[CatalogProblem]) -> String {
506    let mut rendered = format!(
507        "{} validation problem{} found:",
508        problems.len(),
509        if problems.len() == 1 { "" } else { "s" }
510    );
511    for problem in problems {
512        rendered.push_str("\n  - ");
513        rendered.push_str(&problem.to_string());
514    }
515    rendered
516}
517
518#[derive(Debug, Error)]
519pub enum CatalogProblem {
520    #[error("{origin}: resource is missing string field `kind`")]
521    MissingKind { origin: String },
522    #[error("{origin}: unsupported resource kind {kind:?}")]
523    UnsupportedKind { origin: String, kind: String },
524    #[error("agent {agent} sets both instructions and instructionsFile")]
525    InstructionsTwice { agent: String },
526    #[error("agent {agent} instructionsFile {path}: {source}")]
527    Instructions {
528        agent: String,
529        path: String,
530        #[source]
531        source: io::Error,
532    },
533    #[error("agent {agent} instructionsFile is {length} bytes; maximum is {maximum}")]
534    InstructionsTooLarge {
535        agent: String,
536        length: usize,
537        maximum: usize,
538    },
539    #[error("{origin}: unsupported API version {version:?}")]
540    UnsupportedApiVersion { origin: String, version: String },
541    #[error("{origin}: invalid {kind}: {source}")]
542    Decode {
543        origin: String,
544        kind: &'static str,
545        #[source]
546        source: serde_yaml::Error,
547    },
548    #[error("{origin}: invalid {kind} name {name:?}: {source}")]
549    InvalidName {
550        origin: String,
551        kind: &'static str,
552        name: String,
553        #[source]
554        source: Box<IdentifierError>,
555    },
556    #[error("duplicate {kind} {name:?} at {duplicate}; first declared at {first}")]
557    DuplicateResource {
558        kind: &'static str,
559        name: String,
560        first: String,
561        duplicate: String,
562    },
563    #[error("agent {agent:?} mounts skill {path:?}, which could not be loaded: {source}")]
564    Skill {
565        agent: String,
566        path: String,
567        #[source]
568        source: Box<SkillError>,
569    },
570    #[error(
571        "agent {agent:?} mounts skill {name:?} twice, at {first:?} and {duplicate:?}; a model could not tell them apart"
572    )]
573    DuplicateSkill {
574        agent: String,
575        name: String,
576        first: String,
577        duplicate: String,
578    },
579}
580
581#[cfg(test)]
582mod tests;