zeroclaw_runtime/skillforge/
integrate.rs

1//! Integrator — generates ZeroClaw-standard SKILL.toml + SKILL.md from scout results.
2
3use std::fs;
4use std::path::PathBuf;
5
6use anyhow::{Context, Result, bail};
7use chrono::Utc;
8
9use super::scout::ScoutResult;
10
11// ---------------------------------------------------------------------------
12// Integrator
13// ---------------------------------------------------------------------------
14
15pub struct Integrator {
16    output_dir: PathBuf,
17}
18
19impl Integrator {
20    pub fn new(output_dir: String) -> Self {
21        Self {
22            output_dir: PathBuf::from(output_dir),
23        }
24    }
25
26    /// Write SKILL.toml and SKILL.md for the given candidate.
27    pub fn integrate(&self, candidate: &ScoutResult) -> Result<PathBuf> {
28        let safe_name = sanitize_path_component(&candidate.name)?;
29        let skill_dir = self.output_dir.join(&safe_name);
30        fs::create_dir_all(&skill_dir).with_context(|| {
31            format!("Failed to create dir: {}", skill_dir.display().to_string())
32        })?;
33
34        let toml_path = skill_dir.join("SKILL.toml");
35        let md_path = skill_dir.join("SKILL.md");
36
37        let toml_content = self.generate_toml(candidate);
38        let md_content = self.generate_md(candidate);
39
40        fs::write(&toml_path, &toml_content)
41            .with_context(|| format!("Failed to write {}", toml_path.display().to_string()))?;
42        fs::write(&md_path, &md_content)
43            .with_context(|| format!("Failed to write {}", md_path.display().to_string()))?;
44
45        ::zeroclaw_log::record!(INFO, ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Note).with_attrs(::serde_json::json!({"skill": candidate.name.as_str(), "path": skill_dir.display().to_string()})), "Integrated skill");
46
47        Ok(skill_dir)
48    }
49
50    // -- Generators ---------------------------------------------------------
51
52    fn generate_toml(&self, c: &ScoutResult) -> String {
53        let lang = c.language.as_deref().unwrap_or("unknown");
54        let updated = c
55            .updated_at
56            .map(|d| d.format("%Y-%m-%d").to_string())
57            .unwrap_or_else(|| "unknown".into());
58
59        // Emit `[forge]` as a sibling top-level table, not nested under `[skill]`.
60        // `[skill]` is the canonical skill-identity contract enforced by
61        // `SkillMeta` (deny_unknown_fields). SkillForge provenance (source,
62        // owner, stars, etc.) lives in its own namespace so the runtime
63        // schema stays decoupled from the integrator's emit format. See
64        // #6210 / FND-001 §4.2 for the architectural rationale.
65        format!(
66            r#"# Auto-generated by SkillForge on {now}
67
68[skill]
69name = "{name}"
70version = "0.1.0"
71description = "{description}"
72
73[forge]
74source = "{url}"
75owner = "{owner}"
76language = "{lang}"
77license = {license}
78stars = {stars}
79updated_at = "{updated}"
80
81[forge.requirements]
82runtime = "zeroclaw >= 0.1"
83
84[forge.metadata]
85auto_integrated = true
86forge_timestamp = "{now}"
87"#,
88            now = Utc::now().format("%Y-%m-%dT%H:%M:%SZ"),
89            name = escape_toml(&c.name),
90            description = escape_toml(&c.description),
91            url = escape_toml(&c.url),
92            owner = escape_toml(&c.owner),
93            lang = lang,
94            license = if c.has_license { "true" } else { "false" },
95            stars = c.stars,
96            updated = updated,
97        )
98    }
99
100    fn generate_md(&self, c: &ScoutResult) -> String {
101        let lang = c.language.as_deref().unwrap_or("unknown");
102        format!(
103            r#"# {name}
104
105> Auto-generated by SkillForge
106
107## Overview
108
109- **Source**: [{url}]({url})
110- **Owner**: {owner}
111- **Language**: {lang}
112- **Stars**: {stars}
113- **License**: {license}
114
115## Description
116
117{description}
118
119## Usage
120
121```toml
122# Add to your ZeroClaw config:
123[skills.{name}]
124enabled = true
125```
126
127## Notes
128
129This manifest was auto-generated from repository metadata.
130Review before enabling in production.
131"#,
132            name = c.name,
133            url = c.url,
134            owner = c.owner,
135            lang = lang,
136            stars = c.stars,
137            license = if c.has_license { "yes" } else { "unknown" },
138            description = c.description,
139        )
140    }
141}
142
143/// Escape special characters for TOML basic string values.
144fn escape_toml(s: &str) -> String {
145    s.replace('\\', "\\\\")
146        .replace('"', "\\\"")
147        .replace('\n', "\\n")
148        .replace('\r', "\\r")
149        .replace('\t', "\\t")
150        .replace('\u{08}', "\\b")
151        .replace('\u{0C}', "\\f")
152}
153
154/// Sanitize a string for use as a single path component.
155/// Rejects empty names, "..", and names containing path separators or NUL.
156fn sanitize_path_component(name: &str) -> Result<String> {
157    let trimmed = name.trim().trim_matches('.');
158    if trimmed.is_empty() {
159        bail!("Skill name is empty or only dots after sanitization");
160    }
161    let sanitized: String = trimmed
162        .chars()
163        .map(|c| match c {
164            '/' | '\\' | '\0' => '_',
165            _ => c,
166        })
167        .collect();
168    if sanitized == ".." || sanitized.contains('/') || sanitized.contains('\\') {
169        bail!("Skill name '{}' is unsafe as a path component", name);
170    }
171    Ok(sanitized)
172}
173
174// ---------------------------------------------------------------------------
175// Tests
176// ---------------------------------------------------------------------------
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181    use crate::skillforge::scout::{ScoutResult, ScoutSource};
182    use std::fs;
183
184    fn sample_candidate() -> ScoutResult {
185        ScoutResult {
186            name: "test-skill".into(),
187            url: "https://github.com/user/test-skill".into(),
188            description: "A test skill for unit tests".into(),
189            stars: 42,
190            language: Some("Rust".into()),
191            updated_at: Some(Utc::now()),
192            source: ScoutSource::GitHub,
193            owner: "user".into(),
194            has_license: true,
195        }
196    }
197
198    #[tokio::test]
199    async fn integrate_creates_files() {
200        let tmp = std::env::temp_dir().join("zeroclaw-test-integrate");
201        let _ = fs::remove_dir_all(&tmp);
202
203        let integrator = Integrator::new(tmp.to_string_lossy().into_owned());
204        let c = sample_candidate();
205        let path = integrator.integrate(&c).unwrap();
206
207        assert!(path.join("SKILL.toml").exists());
208        assert!(path.join("SKILL.md").exists());
209
210        let toml = tokio::fs::read_to_string(path.join("SKILL.toml"))
211            .await
212            .unwrap();
213        assert!(toml.contains("name = \"test-skill\""));
214        assert!(toml.contains("stars = 42"));
215        // Guard: SkillForge provenance must be emitted under a top-level
216        // `[forge]` table, not inside `[skill]`. See #6210.
217        assert!(
218            toml.contains("[forge]"),
219            "integrator must emit a top-level [forge] table; got:\n{toml}"
220        );
221
222        let md = tokio::fs::read_to_string(path.join("SKILL.md"))
223            .await
224            .unwrap();
225        assert!(md.contains("# test-skill"));
226        assert!(md.contains("A test skill for unit tests"));
227
228        let _ = fs::remove_dir_all(&tmp);
229    }
230
231    /// Schema decoupling guard: the emitted TOML must not place SkillForge
232    /// provenance keys (`source`, `owner`, `language`, `license`, `stars`,
233    /// `updated_at`) inside `[skill]`. The runtime's `SkillMeta` struct
234    /// uses `deny_unknown_fields` and would silently fail to load such a
235    /// file at the swallow site (see #6210, FND-001 §4.2).
236    #[tokio::test]
237    async fn integrate_does_not_emit_provenance_inside_skill_block() {
238        let tmp = std::env::temp_dir().join("zeroclaw-test-integrate-shape");
239        let _ = fs::remove_dir_all(&tmp);
240
241        let integrator = Integrator::new(tmp.to_string_lossy().into_owned());
242        let c = sample_candidate();
243        let path = integrator.integrate(&c).unwrap();
244
245        let toml = tokio::fs::read_to_string(path.join("SKILL.toml"))
246            .await
247            .unwrap();
248
249        // Find the [skill] section and the [forge] section, then assert
250        // the provenance keys live in [forge], not in [skill].
251        let skill_start = toml.find("[skill]").expect("[skill] table must exist");
252        let forge_start = toml.find("[forge]").expect("[forge] table must exist");
253        assert!(
254            skill_start < forge_start,
255            "[skill] must precede [forge] in the emit"
256        );
257        let skill_block = &toml[skill_start..forge_start];
258        for forbidden in [
259            "source =",
260            "owner =",
261            "language =",
262            "license =",
263            "stars =",
264            "updated_at =",
265        ] {
266            assert!(
267                !skill_block.contains(forbidden),
268                "[skill] block must not contain '{forbidden}'; got:\n{skill_block}"
269            );
270        }
271        // Sub-tables `[skill.requirements]` and `[skill.metadata]` would
272        // also leak into SkillMeta — guard against them too.
273        assert!(
274            !toml.contains("[skill.requirements]"),
275            "must not emit [skill.requirements]; provenance lives in [forge.requirements]"
276        );
277        assert!(
278            !toml.contains("[skill.metadata]"),
279            "must not emit [skill.metadata]; provenance lives in [forge.metadata]"
280        );
281
282        let _ = fs::remove_dir_all(&tmp);
283    }
284
285    #[test]
286    fn escape_toml_handles_quotes_and_control_chars() {
287        assert_eq!(escape_toml(r#"say "hello""#), r#"say \"hello\""#);
288        assert_eq!(escape_toml(r"back\slash"), r"back\\slash");
289        assert_eq!(escape_toml("line\nbreak"), "line\\nbreak");
290        assert_eq!(escape_toml("tab\there"), "tab\\there");
291        assert_eq!(escape_toml("cr\rhere"), "cr\\rhere");
292    }
293
294    #[test]
295    fn sanitize_rejects_traversal() {
296        assert!(sanitize_path_component("..").is_err());
297        assert!(sanitize_path_component("...").is_err());
298        assert!(sanitize_path_component("").is_err());
299        assert!(sanitize_path_component("  ").is_err());
300    }
301
302    #[test]
303    fn sanitize_replaces_separators() {
304        let s = sanitize_path_component("foo/bar\\baz\0qux").unwrap();
305        assert!(!s.contains('/'));
306        assert!(!s.contains('\\'));
307        assert!(!s.contains('\0'));
308        assert_eq!(s, "foo_bar_baz_qux");
309    }
310
311    #[test]
312    fn sanitize_trims_dots() {
313        let s = sanitize_path_component(".hidden.").unwrap();
314        assert_eq!(s, "hidden");
315    }
316}
zeroclaw_runtime/skillforge/integrate.rs

zeroclaw_runtime/skillforge/
integrate.rs
