okf_core/
scaffold.rs

1//! Scaffolding and initialization utilities for OKF bundles and concept documents.
2//!
3//! - [`init_bundle`] initializes a compliant OKF bundle structure (`index.md`,
4//!   `log.md`, and an optional sample concept).
5//! - [`create_concept`] generates a new concept `.md` document with appropriate
6//!   frontmatter and markdown structure.
7
8use crate::date::{Date, DateTime};
9use crate::document::Document;
10use crate::frontmatter::Frontmatter;
11use crate::trust::Status;
12use crate::yaml::{Mapping, Value};
13use std::fs;
14use std::io;
15use std::path::{Path, PathBuf};
16
17/// Options for initializing a new OKF bundle.
18#[derive(Clone, Debug, PartialEq, Eq)]
19pub struct BundleInitOptions {
20    /// Bundle title for the root index.
21    pub title: String,
22    /// Whether to create a sample concept (e.g. `overview.md`).
23    pub create_sample: bool,
24    /// The name/id of the sample concept (default "overview").
25    pub sample_name: String,
26    /// Author attribution for generated frontmatter (e.g. "human:alice").
27    pub author: Option<String>,
28    /// Whether to overwrite existing files if they already exist.
29    pub force: bool,
30}
31
32impl Default for BundleInitOptions {
33    fn default() -> Self {
34        Self {
35            title: "Knowledge Base".to_string(),
36            create_sample: true,
37            sample_name: "overview".to_string(),
38            author: None,
39            force: false,
40        }
41    }
42}
43
44/// Options for creating a new concept document.
45#[derive(Clone, Debug, PartialEq, Eq)]
46pub struct ConceptOptions {
47    /// Concept type (e.g. "Concept", "Metric", "Attested Computation", "Playbook").
48    pub type_: String,
49    /// Concept title (default derived from file name).
50    pub title: Option<String>,
51    /// Concept description.
52    pub description: Option<String>,
53    /// Lifecycle status.
54    pub status: Status,
55    /// Author attribution (e.g. "human:alice").
56    pub author: Option<String>,
57    /// Whether this concept is an Attested Computation contract.
58    pub attested: bool,
59    /// Optional tags.
60    pub tags: Vec<String>,
61    /// Whether to overwrite existing file if it already exists.
62    pub force: bool,
63}
64
65impl Default for ConceptOptions {
66    fn default() -> Self {
67        Self {
68            type_: "Concept".to_string(),
69            title: None,
70            description: None,
71            status: Status::Draft,
72            author: None,
73            attested: false,
74            tags: Vec::new(),
75            force: false,
76        }
77    }
78}
79
80/// Returns a default author actor string based on system user environment
81/// variables or `"human:author"`.
82#[must_use]
83pub fn default_author() -> String {
84    if let Ok(author) = std::env::var("OKF_AUTHOR")
85        && !author.trim().is_empty()
86    {
87        return author.trim().to_string();
88    }
89    for env_key in &["USER", "USERNAME", "LOGNAME"] {
90        if let Ok(user) = std::env::var(env_key) {
91            let clean: String = user
92                .chars()
93                .filter(|c| c.is_alphanumeric() || *c == '_' || *c == '-')
94                .collect();
95            if !clean.is_empty() {
96                return format!("human:{clean}");
97            }
98        }
99    }
100    "human:author".to_string()
101}
102
103/// Capitalizes and formats a file stem into a display title.
104#[must_use]
105pub fn title_from_name(name: &str) -> String {
106    let name = name.trim_end_matches(".md");
107    let mut words = Vec::new();
108    for part in name.split(['_', '-']) {
109        if part.is_empty() {
110            continue;
111        }
112        let mut chars = part.chars();
113        let first = chars.next().unwrap_or_default().to_uppercase().to_string();
114        words.push(format!("{first}{}", chars.as_str()));
115    }
116    if words.is_empty() {
117        "Untitled".to_string()
118    } else {
119        words.join(" ")
120    }
121}
122
123/// Formats the current UTC instant as an ISO-8601 string.
124#[must_use]
125pub fn current_iso_timestamp() -> String {
126    DateTime::now_utc().map_or_else(
127        || "2026-01-01T00:00:00Z".to_string(),
128        |dt| {
129            let clean = DateTime {
130                date: dt.date,
131                hour: dt.hour,
132                minute: dt.minute,
133                second: dt.second,
134                nanosecond: 0,
135                offset_minutes: Some(0),
136                has_time: true,
137            };
138            clean.to_string()
139        },
140    )
141}
142
143/// Builds a scaffolded [`Document`] matching the provided options.
144#[must_use]
145pub fn build_concept_document(options: &ConceptOptions, title: &str) -> Document {
146    let mut fm = Frontmatter::new();
147
148    let is_attested =
149        options.attested || options.type_ == crate::computation::ATTESTED_COMPUTATION_TYPE;
150    let actual_type = if is_attested {
151        crate::computation::ATTESTED_COMPUTATION_TYPE
152    } else {
153        options.type_.as_str()
154    };
155    fm.set("type", Value::String(actual_type.to_string()));
156    fm.set("title", Value::String(title.to_string()));
157
158    let desc = options
159        .description
160        .as_deref()
161        .filter(|d| !d.trim().is_empty())
162        .map_or_else(
163            || format!("Overview and details for {title}."),
164            ToString::to_string,
165        );
166    fm.set("description", Value::String(desc));
167    fm.set("status", Value::String(options.status.to_string()));
168
169    let author = options.author.clone().unwrap_or_else(default_author);
170    let mut gen_map = Mapping::new();
171    gen_map.insert("by", Value::String(author));
172    gen_map.insert("at", Value::String(current_iso_timestamp()));
173    fm.set("generated", Value::Mapping(gen_map));
174
175    if !options.tags.is_empty() {
176        let tag_values: Vec<Value> = options
177            .tags
178            .iter()
179            .map(|t| Value::String(t.clone()))
180            .collect();
181        fm.set("tags", Value::Sequence(tag_values));
182    }
183
184    if is_attested {
185        fm.set("runtime", Value::String("python".to_string()));
186
187        let mut param_map = Mapping::new();
188        param_map.insert("name", Value::String("input_data".to_string()));
189        param_map.insert("type", Value::String("string".to_string()));
190        param_map.insert("required", Value::Bool(true));
191        fm.set(
192            "parameters",
193            Value::Sequence(vec![Value::Mapping(param_map)]),
194        );
195
196        let mut exec_map = Mapping::new();
197        exec_map.insert(
198            "resource",
199            Value::String("references/skills/run.md".to_string()),
200        );
201        exec_map.insert(
202            "receipt",
203            Value::Sequence(vec![Value::String("result".to_string())]),
204        );
205        fm.set("executor", Value::Mapping(exec_map));
206
207        let mut att_map = Mapping::new();
208        att_map.insert(
209            "resource",
210            Value::String("references/attesters/verify.py".to_string()),
211        );
212        fm.set("attester", Value::Mapping(att_map));
213
214        let body = format!(
215            "# {title}\n\n# Computation\n\n```python\n# Sanctioned computation logic\n```\n"
216        );
217        Document::new(fm, body)
218    } else {
219        let body = format!("# {title}\n\nDescribe {title} here.\n");
220        Document::new(fm, body)
221    }
222}
223
224/// Creates a new concept markdown file with proper frontmatter and heading.
225///
226/// # Errors
227///
228/// Returns an [`io::Error`] if the file already exists (and `force` is false),
229/// or if writing to disk fails.
230pub fn create_concept(path: impl AsRef<Path>, options: &ConceptOptions) -> io::Result<PathBuf> {
231    let mut path = path.as_ref().to_path_buf();
232    if path.extension().is_none() {
233        path.set_extension("md");
234    }
235
236    if path.exists() && !options.force {
237        return Err(io::Error::new(
238            io::ErrorKind::AlreadyExists,
239            format!("concept file already exists: {}", path.display()),
240        ));
241    }
242
243    if let Some(parent) = path.parent()
244        && !parent.as_os_str().is_empty()
245    {
246        fs::create_dir_all(parent)?;
247    }
248
249    let file_stem = path
250        .file_stem()
251        .and_then(|s| s.to_str())
252        .unwrap_or("concept");
253    let title = options
254        .title
255        .clone()
256        .unwrap_or_else(|| title_from_name(file_stem));
257
258    let doc = build_concept_document(options, &title);
259    fs::write(&path, doc.serialize())?;
260    Ok(path)
261}
262
263/// Initializes a new OKF bundle at `root` with `index.md`, `log.md`, and
264/// optionally an initial concept.
265///
266/// Returns the list of created file paths on success.
267///
268/// # Errors
269///
270/// Returns an [`io::Error`] if `index.md` or `log.md` already exists (and
271/// `force` is false), or if writing to disk fails.
272pub fn init_bundle(
273    root: impl AsRef<Path>,
274    options: &BundleInitOptions,
275) -> io::Result<Vec<PathBuf>> {
276    let root = root.as_ref();
277    fs::create_dir_all(root)?;
278
279    let index_path = root.join("index.md");
280    let log_path = root.join("log.md");
281
282    if !options.force {
283        if index_path.exists() {
284            return Err(io::Error::new(
285                io::ErrorKind::AlreadyExists,
286                format!("index.md already exists: {}", index_path.display()),
287            ));
288        }
289        if log_path.exists() {
290            return Err(io::Error::new(
291                io::ErrorKind::AlreadyExists,
292                format!("log.md already exists: {}", log_path.display()),
293            ));
294        }
295    }
296
297    let mut created = Vec::new();
298
299    let sample_rel = if options.create_sample {
300        let sample_stem = if options.sample_name.trim().is_empty() {
301            "overview"
302        } else {
303            options.sample_name.trim().trim_end_matches(".md")
304        };
305        let sample_path = root.join(format!("{sample_stem}.md"));
306        let title = title_from_name(sample_stem);
307        let desc = format!("Initial {} concept for this bundle.", title.to_lowercase());
308        let concept_opts = ConceptOptions {
309            type_: "Concept".to_string(),
310            title: Some(title.clone()),
311            description: Some(desc.clone()),
312            status: Status::Draft,
313            author: options.author.clone(),
314            attested: false,
315            tags: Vec::new(),
316            force: options.force,
317        };
318        create_concept(&sample_path, &concept_opts)?;
319        created.push(sample_path);
320        Some((title, format!("{sample_stem}.md"), desc))
321    } else {
322        None
323    };
324
325    // Build index.md
326    let index_text = if let Some((title, link, desc)) = sample_rel {
327        format!(
328            "---\nokf_version: \"{}\"\n---\n\n# Concept\n\n* [{title}]({link}) - {desc}\n",
329            crate::OKF_VERSION
330        )
331    } else {
332        format!(
333            "---\nokf_version: \"{}\"\n---\n\n# {}\n",
334            crate::OKF_VERSION,
335            options.title
336        )
337    };
338    fs::write(&index_path, index_text)?;
339    created.push(index_path);
340
341    // Build log.md
342    let today = Date::today_utc().unwrap_or(Date {
343        year: 2026,
344        month: 1,
345        day: 1,
346    });
347    let log_text = format!("# Update Log\n\n## {today}\n* **Creation**: Initialized OKF bundle.\n");
348    fs::write(&log_path, log_text)?;
349    created.push(log_path);
350
351    Ok(created)
352}
okf_core/scaffold.rs

okf_core/
scaffold.rs
