use std::collections::BTreeMap;
use std::fs;
use std::io::{self, Read};
use std::os::unix::fs::PermissionsExt;
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use crate::agent::{self, AgentInventoryWarning, AgentRecord};
use crate::error::DaloResult;
use crate::plugin::{
self, PluginInventory, PluginInventoryWarning, PluginRecord, ToolAvailability, ToolCapability,
ToolInputType, ToolRuntime,
};
use crate::store::ApprovalRecord;
const SKILL_FILE: &str = "SKILL.md";
pub const MAX_SLOT_NAME_LENGTH: usize = 120;
const DELIVERY_FILE: &str = "DELIVERY.toml";
const MAX_FRONTMATTER_BYTES: usize = 64 * 1024;
pub(crate) const MAX_SKILL_METADATA_BYTES: usize = MAX_FRONTMATTER_BYTES + 16;
const MAX_FRONTMATTER_FLOW_DEPTH: usize = 64;
const MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES: usize = 16;
const MAX_SOURCE_SCAN_DEPTH: usize = 64;
const MAX_SOURCE_SCAN_DIRECTORIES: usize = 100_000;
const MAX_SOURCE_SCAN_ENTRIES: usize = 250_000;
const MAX_SOURCE_SCAN_ENTRIES_PER_DIRECTORY: usize = 25_000;
const MAX_FINGERPRINT_DEPTH: usize = 64;
const MAX_FINGERPRINT_ENTRIES: usize = 25_000;
const MAX_FINGERPRINT_FILE_BYTES: u64 = 1024 * 1024 * 1024;
const MAX_FINGERPRINT_TOTAL_BYTES: u64 = 8 * 1024 * 1024 * 1024;
const FINGERPRINT_READ_BUFFER_BYTES: usize = 64 * 1024;
pub const REQUIRES_COMMANDS_METADATA_KEY: &str = "dalo.requires-commands";
const MAX_COMMAND_NAME_LENGTH: usize = 128;
#[derive(Debug, Clone, Serialize)]
pub struct SourceInventory {
pub source_id: String,
pub skills: Vec<SkillRecord>,
pub agents: Vec<AgentRecord>,
pub plugins: Vec<PluginRecord>,
pub warnings: Vec<InventoryWarning>,
pub agent_warnings: Vec<AgentInventoryWarning>,
pub plugin_warnings: Vec<PluginInventoryWarning>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SkillRecord {
pub source_id: String,
pub source_ref: String,
pub id: Option<String>,
pub slot_name: String,
pub path: PathBuf,
pub skill_file: PathBuf,
pub delivery: SkillDelivery,
pub description: Option<String>,
pub requires: Vec<String>,
pub owners: Vec<String>,
pub tags: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub compatibility: Option<String>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub metadata: BTreeMap<String, String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub binaries: Vec<crate::binary::BinaryRecord>,
}
impl SkillRecord {
#[must_use]
pub fn required_commands(&self) -> Vec<String> {
let Some(value) = self.metadata.get(REQUIRES_COMMANDS_METADATA_KEY) else {
return Vec::new();
};
let mut commands: Vec<String> = Vec::new();
for token in value
.split_ascii_whitespace()
.filter(|token| is_command_name(token))
{
if !commands.iter().any(|command| command == token) {
commands.push(token.to_owned());
}
}
commands
}
}
fn is_command_name(token: &str) -> bool {
!token.is_empty()
&& token.len() <= MAX_COMMAND_NAME_LENGTH
&& !token.starts_with(['-', '.'])
&& token
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'+' | b'-'))
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct SkillCommandCheck {
pub(crate) source_ref: String,
pub(crate) compatibility: Option<String>,
pub(crate) declared: Vec<String>,
pub(crate) missing: Vec<String>,
}
pub(crate) fn check_declared_commands<'a>(
active_skills: &[crate::resolver::ResolvedSkill],
inventories: impl IntoIterator<Item = &'a SourceInventory>,
) -> Vec<SkillCommandCheck> {
let records = inventories
.into_iter()
.flat_map(|inventory| &inventory.skills)
.map(|record| (record.source_ref.as_str(), record))
.collect::<BTreeMap<_, _>>();
active_skills
.iter()
.filter_map(|skill| {
let record = records.get(skill.source_ref.as_str())?;
let declared = record.required_commands();
if declared.is_empty() {
return None;
}
let missing = declared
.iter()
.filter(|command| !crate::tool::executable_on_path(command))
.cloned()
.collect();
Some(SkillCommandCheck {
source_ref: record.source_ref.clone(),
compatibility: record.compatibility.clone(),
declared,
missing,
})
})
.collect()
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum SkillDelivery {
Direct,
Prebuilt {
providers: BTreeMap<String, PrebuiltSkillArtifact>,
universal_fallback: bool,
#[serde(skip_serializing_if = "Option::is_none")]
fallback_fingerprint: Option<String>,
manifest_path: PathBuf,
},
Generated {
generator: String,
generator_contract_hash: String,
output_input: String,
providers: BTreeMap<String, PathBuf>,
recipe_hash: String,
manifest_path: PathBuf,
#[serde(skip_serializing_if = "Option::is_none")]
source_commit: Option<String>,
recipe_approved: bool,
generator_approved: bool,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
output_fingerprints: BTreeMap<String, String>,
#[serde(skip_serializing_if = "Option::is_none")]
derivation_hash: Option<String>,
},
}
impl SkillDelivery {
#[must_use]
pub fn artifact_for(&self, target_id: &str, direct_path: &Path) -> Option<SkillArtifact> {
match self {
Self::Direct => Some(SkillArtifact {
path: direct_path.to_path_buf(),
fingerprint: None,
mode: SkillDeliveryMode::Direct,
provider: None,
}),
Self::Prebuilt {
providers,
universal_fallback,
fallback_fingerprint,
..
} => providers.get(target_id).map_or_else(
|| {
universal_fallback.then(|| SkillArtifact {
path: direct_path.to_path_buf(),
fingerprint: fallback_fingerprint.clone(),
mode: SkillDeliveryMode::Prebuilt,
provider: Some("universal".to_owned()),
})
},
|artifact| {
Some(SkillArtifact {
path: artifact.path.clone(),
fingerprint: Some(artifact.fingerprint.clone()),
mode: SkillDeliveryMode::Prebuilt,
provider: Some(target_id.to_owned()),
})
},
),
Self::Generated { .. } => None,
}
}
#[must_use]
pub const fn mode(&self) -> SkillDeliveryMode {
match self {
Self::Direct => SkillDeliveryMode::Direct,
Self::Prebuilt { .. } => SkillDeliveryMode::Prebuilt,
Self::Generated { .. } => SkillDeliveryMode::Generated,
}
}
pub fn bind_generated_approvals(
&mut self,
source_ref: &str,
stable_ref: &str,
source_commit: Option<String>,
approvals: &[ApprovalRecord],
) {
let Self::Generated {
generator,
generator_contract_hash,
recipe_hash,
source_commit: bound_commit,
recipe_approved,
generator_approved,
..
} = self
else {
return;
};
*bound_commit = source_commit;
*recipe_approved = bound_commit.as_deref().is_some_and(|commit| {
let value = generated_approval_value(source_ref, stable_ref, commit, recipe_hash);
approvals
.iter()
.any(|record| record.scope == "delivery" && record.value == value)
});
let tool_value = format!("{generator}@sha256:{generator_contract_hash}");
*generator_approved = approvals
.iter()
.any(|record| record.scope == "tool" && record.value == tool_value);
}
#[must_use]
pub fn generated_approval_value(&self, source_ref: &str, stable_ref: &str) -> Option<String> {
let Self::Generated {
recipe_hash,
source_commit: Some(source_commit),
..
} = self
else {
return None;
};
Some(generated_approval_value(
source_ref,
stable_ref,
source_commit,
recipe_hash,
))
}
}
fn generated_approval_value(
source_ref: &str,
stable_ref: &str,
source_commit: &str,
recipe_hash: &str,
) -> String {
format!("{source_ref}@id:{stable_ref}@{source_commit}@sha256:{recipe_hash}")
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SkillArtifact {
pub path: PathBuf,
pub fingerprint: Option<String>,
pub mode: SkillDeliveryMode,
pub provider: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SkillDeliveryMode {
Direct,
Prebuilt,
Generated,
}
impl SkillDeliveryMode {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Direct => "direct",
Self::Prebuilt => "prebuilt",
Self::Generated => "generated",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PrebuiltSkillArtifact {
pub path: PathBuf,
pub fingerprint: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct InventoryWarning {
pub code: InventoryWarningCode,
pub path: PathBuf,
pub message: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum InventoryWarningCode {
MalformedFrontmatter,
InvalidSlotName,
DuplicateSlotName,
UnreadablePath,
SkippedSymlink,
InvalidDelivery,
InvalidBinaryDeclaration,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct DeliveryManifest {
schema_version: u32,
kind: String,
#[serde(default)]
universal_fallback: bool,
#[serde(default)]
providers: BTreeMap<String, PathBuf>,
generator: Option<String>,
output_input: Option<String>,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
struct SkillFrontmatter {
id: Option<String>,
name: Option<String>,
description: Option<String>,
requires: Vec<String>,
owners: Vec<String>,
tags: Vec<String>,
#[serde(deserialize_with = "deserialize_compatibility")]
compatibility: Option<yaml_serde::Value>,
#[serde(deserialize_with = "deserialize_metadata")]
metadata: BTreeMap<String, yaml_serde::Value>,
#[serde(default, deserialize_with = "deserialize_binaries")]
binaries: Option<yaml_serde::Value>,
}
fn deserialize_binaries<'de, D>(deserializer: D) -> Result<Option<yaml_serde::Value>, D::Error>
where
D: serde::Deserializer<'de>,
{
yaml_serde::Value::deserialize(deserializer).map(Some)
}
pub fn scan_source(source_id: &str, source_root: &Path) -> DaloResult<SourceInventory> {
let plugin_inventory = plugin::scan_source_plugins(source_id, source_root);
scan_source_with_plugin_inventory(source_id, source_root, plugin_inventory)
}
pub fn scan_source_with_plugin_inventory(
source_id: &str,
source_root: &Path,
plugin_inventory: PluginInventory,
) -> DaloResult<SourceInventory> {
let mut inventory =
scan_source_candidates_with_plugin_inventory(source_id, source_root, plugin_inventory)?;
inventory
.skills
.dedup_by(|left, right| left.slot_name == right.slot_name);
Ok(inventory)
}
pub(crate) fn scan_catalog_source(
source_id: &str,
source_root: &Path,
) -> DaloResult<SourceInventory> {
let plugins = plugin::scan_source_plugins(source_id, source_root);
scan_source_candidates_with_plugin_inventory(source_id, source_root, plugins)
}
pub(crate) fn scan_configured_source(
source: &crate::source::SourceConfig,
source_root: &Path,
) -> DaloResult<SourceInventory> {
let plugins = plugin::scan_source_plugins(&source.id, source_root);
scan_configured_source_with_plugin_inventory(source, source_root, plugins)
}
pub(crate) fn scan_configured_source_with_plugin_inventory(
source: &crate::source::SourceConfig,
source_root: &Path,
plugins: PluginInventory,
) -> DaloResult<SourceInventory> {
let mut inventory =
scan_source_candidates_with_plugin_inventory(&source.id, source_root, plugins)?;
if source.kind == crate::source::SourceKind::Catalog {
inventory.skills.sort_by(|left, right| {
left.slot_name
.cmp(&right.slot_name)
.then_with(|| {
let selected = |skill: &SkillRecord| {
crate::catalog::skill_is_selected(skill, &source.selection, source_root)
};
selected(right).cmp(&selected(left))
})
.then_with(|| left.path.cmp(&right.path))
});
}
inventory
.skills
.dedup_by(|left, right| left.slot_name == right.slot_name);
Ok(inventory)
}
fn scan_source_candidates_with_plugin_inventory(
source_id: &str,
source_root: &Path,
plugin_inventory: PluginInventory,
) -> DaloResult<SourceInventory> {
let agent_inventory = agent::scan_source_agents(source_id, source_root);
let mut warnings = Vec::new();
let skill_dirs = find_skill_dirs(source_root, &mut warnings)?;
let mut skills = Vec::new();
for skill_dir in skill_dirs {
match scan_skill(
source_id,
source_root,
&skill_dir,
&plugin_inventory.plugins,
) {
Ok((skill, mut skill_warnings)) => {
if let Some(skill) = skill {
skills.push(skill);
}
warnings.append(&mut skill_warnings);
}
Err(error) => warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: skill_dir.join(SKILL_FILE),
message: error.to_string(),
}),
}
}
let provider_artifact_paths = skills
.iter()
.flat_map(|skill| match &skill.delivery {
SkillDelivery::Prebuilt { providers, .. } => providers
.values()
.map(|artifact| artifact.path.clone())
.collect::<Vec<_>>(),
SkillDelivery::Direct | SkillDelivery::Generated { .. } => Vec::new(),
})
.collect::<std::collections::BTreeSet<_>>();
skills.retain(|skill| !provider_artifact_paths.contains(&skill.path));
warnings.retain(|warning| {
!provider_artifact_paths
.iter()
.any(|artifact| warning.path.starts_with(artifact))
});
skills.sort_by(|left, right| {
left.slot_name
.cmp(&right.slot_name)
.then_with(|| left.source_ref.cmp(&right.source_ref))
.then_with(|| left.path.cmp(&right.path))
});
warnings.extend(duplicate_slot_warnings(source_id, &skills));
warnings.sort_by(|left, right| {
left.path
.cmp(&right.path)
.then_with(|| warning_code_name(left.code).cmp(warning_code_name(right.code)))
});
Ok(SourceInventory {
source_id: source_id.to_owned(),
skills,
agents: agent_inventory.agents,
plugins: plugin_inventory.plugins,
warnings,
agent_warnings: agent_inventory.warnings,
plugin_warnings: plugin_inventory.warnings,
})
}
fn find_skill_dirs(
source_root: &Path,
warnings: &mut Vec<InventoryWarning>,
) -> DaloResult<Vec<PathBuf>> {
find_skill_dirs_with_limits(
source_root,
warnings,
SourceTraversalLimits {
max_depth: MAX_SOURCE_SCAN_DEPTH,
max_directories: MAX_SOURCE_SCAN_DIRECTORIES,
max_entries: MAX_SOURCE_SCAN_ENTRIES,
max_entries_per_directory: MAX_SOURCE_SCAN_ENTRIES_PER_DIRECTORY,
},
)
}
#[derive(Clone, Copy)]
struct SourceTraversalLimits {
max_depth: usize,
max_directories: usize,
max_entries: usize,
max_entries_per_directory: usize,
}
fn find_skill_dirs_with_limits(
source_root: &Path,
warnings: &mut Vec<InventoryWarning>,
limits: SourceTraversalLimits,
) -> DaloResult<Vec<PathBuf>> {
let mut found = Vec::new();
let mut pending = vec![(source_root.to_path_buf(), 0_usize)];
let plugins_root = source_root.join("plugins");
let canonical_source_root = fs::canonicalize(source_root).ok();
let mut inspected_directories = 0_usize;
let mut inspected_entries = 0_usize;
while let Some((dir, depth)) = pending.pop() {
if dir == plugins_root {
continue;
}
if dir.file_name().is_some_and(|name| name == ".git") {
continue;
}
if inspected_directories >= limits.max_directories {
source_traversal_limit_warning(
source_root,
&dir,
warnings,
format!(
"the {}-directory source scan limit was reached",
limits.max_directories
),
);
break;
}
inspected_directories += 1;
let skill_file = dir.join(SKILL_FILE);
match fs::symlink_metadata(&skill_file) {
Ok(metadata) if metadata.file_type().is_symlink() => {
if canonical_source_root.as_ref().is_some_and(|source_root| {
skill_file
.canonicalize()
.is_ok_and(|target| target.starts_with(source_root))
}) {
if skill_file.is_file() {
found.push(dir);
continue;
}
warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: skill_file,
message: "SKILL.md must resolve to a regular file".to_owned(),
});
} else {
warnings.push(InventoryWarning {
code: InventoryWarningCode::SkippedSymlink,
path: skill_file,
message:
"skipped symlinked SKILL.md whose target is outside the source checkout"
.to_owned(),
});
}
}
Ok(metadata) if metadata.is_file() => {
found.push(dir);
continue;
}
Ok(_) => warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: skill_file,
message: "SKILL.md must be a regular file".to_owned(),
}),
Err(error) if error.kind() != io::ErrorKind::NotFound => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: skill_file,
message: error.to_string(),
});
}
Err(_) => {}
}
let entries = match fs::read_dir(&dir) {
Ok(entries) => entries,
Err(error) => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: dir,
message: error.to_string(),
});
continue;
}
};
let mut children = Vec::new();
let mut directory_entry_count = 0;
let mut entry_limit_reason = None;
for entry in entries {
if directory_entry_count >= limits.max_entries_per_directory {
entry_limit_reason = Some(format!(
"a directory exceeded its {}-entry limit",
limits.max_entries_per_directory
));
break;
}
if inspected_entries.saturating_add(directory_entry_count) >= limits.max_entries {
entry_limit_reason = Some(format!(
"the source scan exceeded its {}-entry total limit",
limits.max_entries
));
break;
}
directory_entry_count += 1;
match entry {
Ok(entry) => children.push(entry),
Err(error) => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: dir.clone(),
message: error.to_string(),
});
}
}
}
if let Some(reason) = entry_limit_reason {
source_traversal_limit_warning(source_root, &dir, warnings, reason);
break;
}
inspected_entries = inspected_entries.saturating_add(directory_entry_count);
children.sort_by_key(fs::DirEntry::file_name);
let mut child_directories = Vec::new();
let mut depth_limit_reached = false;
for entry in children {
let file_type = match entry.file_type() {
Ok(file_type) => file_type,
Err(error) => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: entry.path(),
message: error.to_string(),
});
continue;
}
};
if file_type.is_symlink() {
if fs::metadata(entry.path()).is_ok_and(|metadata| metadata.is_file()) {
continue;
}
warnings.push(InventoryWarning {
code: InventoryWarningCode::SkippedSymlink,
path: entry.path(),
message: "skipped symlink to keep the source scan bounded".to_owned(),
});
} else if file_type.is_dir() && !is_adoption_staging_dir_name(&entry.file_name()) {
if depth >= limits.max_depth {
depth_limit_reached = true;
} else {
child_directories.push(entry.path());
}
}
}
if depth_limit_reached {
source_traversal_limit_warning(
source_root,
&dir,
warnings,
format!(
"the {}-level source scan depth limit was reached",
limits.max_depth
),
);
break;
}
child_directories.sort();
pending.extend(
child_directories
.into_iter()
.rev()
.map(|child| (child, depth + 1)),
);
}
found.sort();
Ok(found)
}
fn source_traversal_limit_warning(
source_root: &Path,
stopped_at: &Path,
warnings: &mut Vec<InventoryWarning>,
reason: String,
) {
warnings.push(InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: source_root.to_path_buf(),
message: format!(
"source inventory is incomplete: {reason} at `{}`; skills later in this source may be omitted. Reduce or split the source tree, then run `dalo sync`",
stopped_at.display()
),
});
}
fn is_adoption_staging_dir_name(name: &std::ffi::OsStr) -> bool {
let name = name.to_string_lossy();
let Some(rest) = name.strip_prefix('.') else {
return false;
};
rest.rsplit_once(".dalo-adopting-")
.is_some_and(|(skill_name, suffix)| !skill_name.is_empty() && !suffix.is_empty())
}
fn scan_skill(
source_id: &str,
source_root: &Path,
skill_dir: &Path,
plugins: &[PluginRecord],
) -> DaloResult<(Option<SkillRecord>, Vec<InventoryWarning>)> {
let skill_file = skill_dir.join(SKILL_FILE);
let (skill_markdown, metadata_truncated) = match read_skill_metadata(&skill_file) {
Ok(metadata) => metadata,
Err(error) => {
return Ok((
None,
vec![InventoryWarning {
code: InventoryWarningCode::UnreadablePath,
path: skill_file,
message: error.to_string(),
}],
));
}
};
let (frontmatter, mut warnings) =
parse_frontmatter(&skill_markdown, &skill_file, metadata_truncated);
let Some(frontmatter) = frontmatter else {
return Ok((None, warnings));
};
let folder_name = skill_dir
.file_name()
.map(|name| name.to_string_lossy().into_owned())
.unwrap_or_else(|| source_id.to_owned());
let Some(slot_name) = select_slot_name(&frontmatter, &folder_name, &skill_file, &mut warnings)
else {
return Ok((None, warnings));
};
let source_ref = format!("{source_id}:{slot_name}");
let delivery = match scan_delivery(
source_id,
&source_ref,
frontmatter.id.as_deref(),
source_root,
skill_dir,
plugins,
) {
Ok(delivery) => delivery,
Err(message) => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::InvalidDelivery,
path: skill_dir.join(DELIVERY_FILE),
message,
});
return Ok((None, warnings));
}
};
let binaries = match frontmatter.binaries.as_ref() {
None => Vec::new(),
Some(declarations) => match crate::binary::parse_declarations(&source_ref, declarations) {
Ok(binaries) => binaries,
Err(message) => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::InvalidBinaryDeclaration,
path: skill_file,
message,
});
return Ok((None, warnings));
}
},
};
Ok((
Some(SkillRecord {
source_id: source_id.to_owned(),
source_ref,
id: frontmatter.id,
slot_name,
path: skill_dir.to_path_buf(),
skill_file,
delivery,
description: frontmatter.description,
requires: frontmatter.requires,
owners: frontmatter.owners,
tags: frontmatter.tags,
compatibility: compatibility_text(frontmatter.compatibility),
metadata: string_metadata(frontmatter.metadata),
binaries,
}),
warnings,
))
}
fn compatibility_text(value: Option<yaml_serde::Value>) -> Option<String> {
match value {
Some(yaml_serde::Value::String(text)) if !text.trim().is_empty() => Some(text),
_ => None,
}
}
fn string_metadata(entries: BTreeMap<String, yaml_serde::Value>) -> BTreeMap<String, String> {
entries
.into_iter()
.filter_map(|(key, value)| match value {
yaml_serde::Value::String(text) => Some((key, text)),
_ => None,
})
.collect()
}
fn deserialize_compatibility<'de, D>(deserializer: D) -> Result<Option<yaml_serde::Value>, D::Error>
where
D: serde::Deserializer<'de>,
{
Ok(match FrontmatterNode::deserialize(deserializer)? {
FrontmatterNode::Text(text) => Some(yaml_serde::Value::String(text)),
FrontmatterNode::Mapping(_) | FrontmatterNode::Other => None,
})
}
fn deserialize_metadata<'de, D>(
deserializer: D,
) -> Result<BTreeMap<String, yaml_serde::Value>, D::Error>
where
D: serde::Deserializer<'de>,
{
Ok(match FrontmatterNode::deserialize(deserializer)? {
FrontmatterNode::Mapping(entries) => entries
.into_iter()
.filter_map(|entry| match entry {
(FrontmatterNode::Text(key), FrontmatterNode::Text(text)) => {
Some((key, yaml_serde::Value::String(text)))
}
_ => None,
})
.collect(),
FrontmatterNode::Text(_) | FrontmatterNode::Other => BTreeMap::new(),
})
}
enum FrontmatterNode {
Text(String),
Mapping(Vec<(FrontmatterNode, FrontmatterNode)>),
Other,
}
impl<'de> Deserialize<'de> for FrontmatterNode {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
deserializer.deserialize_any(FrontmatterNodeVisitor)
}
}
struct FrontmatterNodeVisitor;
impl<'de> serde::de::Visitor<'de> for FrontmatterNodeVisitor {
type Value = FrontmatterNode;
fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
formatter.write_str("any YAML value")
}
fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Text(value.to_owned()))
}
fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Text(value))
}
fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
where
A: serde::de::MapAccess<'de>,
{
let mut entries = Vec::new();
while let Some(entry) = map.next_entry::<FrontmatterNode, FrontmatterNode>()? {
entries.push(entry);
}
Ok(FrontmatterNode::Mapping(entries))
}
fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
where
A: serde::de::SeqAccess<'de>,
{
while seq.next_element::<serde::de::IgnoredAny>()?.is_some() {}
Ok(FrontmatterNode::Other)
}
fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
where
A: serde::de::EnumAccess<'de>,
{
let (_tag, contents) = data.variant::<String>()?;
serde::de::VariantAccess::newtype_variant::<serde::de::IgnoredAny>(contents)?;
Ok(FrontmatterNode::Other)
}
fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
where
D: serde::Deserializer<'de>,
{
deserializer.deserialize_any(self)
}
fn visit_bool<E>(self, _value: bool) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_i64<E>(self, _value: i64) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_u64<E>(self, _value: u64) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_i128<E>(self, _value: i128) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_u128<E>(self, _value: u128) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_f64<E>(self, _value: f64) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_unit<E>(self) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
fn visit_none<E>(self) -> Result<Self::Value, E>
where
E: serde::de::Error,
{
Ok(FrontmatterNode::Other)
}
}
fn scan_delivery(
source_id: &str,
source_ref: &str,
skill_id: Option<&str>,
source_root: &Path,
skill_dir: &Path,
plugins: &[PluginRecord],
) -> Result<SkillDelivery, String> {
let manifest_path = skill_dir.join(DELIVERY_FILE);
if !manifest_path.exists() {
return Ok(SkillDelivery::Direct);
}
let manifest_metadata = fs::symlink_metadata(&manifest_path)
.map_err(|error| format!("cannot inspect delivery manifest: {error}"))?;
if !manifest_metadata.is_file() || manifest_metadata.file_type().is_symlink() {
return Err("delivery manifest must be a regular file".to_owned());
}
let content = fs::read_to_string(&manifest_path)
.map_err(|error| format!("cannot read delivery manifest: {error}"))?;
let manifest: DeliveryManifest = toml::from_str(&content)
.map_err(|error| format!("cannot parse delivery manifest: {error}"))?;
if manifest.schema_version != 1 {
return Err(format!(
"unsupported delivery schema version {} (supported: 1)",
manifest.schema_version
));
}
match manifest.kind.as_str() {
"prebuilt" => scan_prebuilt_delivery(source_root, skill_dir, manifest_path, manifest),
"generated" => scan_generated_delivery(
source_id,
source_ref,
skill_id,
manifest_path,
manifest,
plugins,
),
kind => Err(format!(
"unsupported delivery kind `{kind}` (supported: prebuilt, generated)"
)),
}
}
fn scan_prebuilt_delivery(
source_root: &Path,
skill_dir: &Path,
manifest_path: PathBuf,
manifest: DeliveryManifest,
) -> Result<SkillDelivery, String> {
if manifest.generator.is_some() || manifest.output_input.is_some() {
return Err("prebuilt delivery must not declare generator fields".to_owned());
}
if manifest.providers.is_empty() {
return Err("prebuilt delivery requires at least one provider mapping".to_owned());
}
let canonical_source = fs::canonicalize(source_root)
.map_err(|error| format!("cannot resolve source checkout: {error}"))?;
let canonical_skill = fs::canonicalize(skill_dir)
.map_err(|error| format!("cannot resolve logical skill directory: {error}"))?;
let mut providers: BTreeMap<String, PrebuiltSkillArtifact> = BTreeMap::new();
for (provider, relative_path) in manifest.providers {
if provider == "universal" {
return Err(
"provider target ID `universal` is reserved for universal_fallback".to_owned(),
);
}
if !valid_provider_id(&provider) {
return Err(format!("invalid provider target ID `{provider}`"));
}
if relative_path.is_absolute()
|| relative_path.components().any(|component| {
matches!(
component,
std::path::Component::ParentDir
| std::path::Component::RootDir
| std::path::Component::Prefix(_)
)
})
{
return Err(format!(
"provider `{provider}` path must be relative and stay inside the source checkout"
));
}
let artifact_path = source_root.join(&relative_path);
let canonical_artifact = fs::canonicalize(&artifact_path).map_err(|error| {
format!(
"provider `{provider}` artifact `{}` cannot be resolved: {error}",
relative_path.display()
)
})?;
if !canonical_artifact.starts_with(&canonical_source) {
return Err(format!(
"provider `{provider}` artifact must stay inside the source checkout"
));
}
if canonical_artifact == canonical_skill {
return Err(format!(
"provider `{provider}` artifact must differ from the logical skill; use universal_fallback for the canonical directory"
));
}
if !canonical_artifact.join(SKILL_FILE).is_file() {
return Err(format!(
"provider `{provider}` artifact `{}` does not contain SKILL.md",
relative_path.display()
));
}
let fingerprint = fingerprint_directory(&artifact_path).map_err(|error| {
format!("provider `{provider}` artifact cannot be fingerprinted: {error}")
})?;
providers.insert(
provider,
PrebuiltSkillArtifact {
path: artifact_path,
fingerprint,
},
);
}
let fallback_fingerprint = manifest
.universal_fallback
.then(|| {
fingerprint_directory(skill_dir)
.map_err(|error| format!("universal fallback cannot be fingerprinted: {error}"))
})
.transpose()?;
Ok(SkillDelivery::Prebuilt {
providers,
universal_fallback: manifest.universal_fallback,
fallback_fingerprint,
manifest_path,
})
}
fn scan_generated_delivery(
source_id: &str,
source_ref: &str,
skill_id: Option<&str>,
manifest_path: PathBuf,
manifest: DeliveryManifest,
plugins: &[PluginRecord],
) -> Result<SkillDelivery, String> {
if skill_id.is_none() {
return Err("generated delivery requires a stable skill frontmatter `id`".to_owned());
}
if manifest.universal_fallback {
return Err("generated delivery does not support universal_fallback".to_owned());
}
if manifest.providers.is_empty() {
return Err("generated delivery requires at least one provider output mapping".to_owned());
}
let generator = manifest
.generator
.ok_or_else(|| "generated delivery requires `generator`".to_owned())?;
if !generator.starts_with(&format!("{source_id}:")) {
return Err("generated delivery generator must be a tool from the same source".to_owned());
}
let (plugin, tool) = plugins
.iter()
.find_map(|plugin| {
plugin
.tools
.iter()
.find(|tool| tool.source_ref == generator)
.map(|tool| (plugin, tool))
})
.ok_or_else(|| format!("generated delivery references unknown tool `{generator}`"))?;
if tool.runtime != ToolRuntime::Executable {
return Err(format!(
"generator `{generator}` must use the executable runtime so sync never selects an interpreter from ambient PATH"
));
}
if tool.env.iter().any(|name| name == "PATH") {
return Err(format!(
"generator `{generator}` must not admit ambient PATH into generated delivery execution"
));
}
validate_generated_entry(&generator, &plugin.path.join(&tool.entry))?;
let output_input = manifest
.output_input
.ok_or_else(|| "generated delivery requires `output_input`".to_owned())?;
let input = tool
.inputs
.iter()
.find(|input| input.name == output_input)
.ok_or_else(|| {
format!("generator `{generator}` does not declare output input `{output_input}`")
})?;
if input.kind != ToolInputType::Path || !input.required {
return Err(format!(
"generator output input `{output_input}` must be a required path"
));
}
if let Some(other) = tool
.inputs
.iter()
.find(|input| input.required && input.name != output_input)
{
return Err(format!(
"generator `{generator}` has unsupported required input `{}`; generated delivery v1 supplies only `{output_input}`",
other.name
));
}
let placeholder = format!("${{input.{output_input}}}");
if !tool.argv.iter().any(|value| value == &placeholder) {
return Err(format!(
"generator `{generator}` argv must include `{placeholder}`"
));
}
if !tool.capabilities.contains(&ToolCapability::FilesystemWrite) {
return Err(format!(
"generator `{generator}` must declare the filesystem_write capability"
));
}
if tool.availability != ToolAvailability::Required {
return Err(format!(
"generator `{generator}` must declare required availability"
));
}
let mut providers: BTreeMap<String, PathBuf> = BTreeMap::new();
for (provider, relative_path) in manifest.providers {
if provider == "universal" || !valid_provider_id(&provider) {
return Err(format!("invalid generated provider target ID `{provider}`"));
}
validate_relative_generated_path(&provider, &relative_path)?;
if let Some((other_provider, other_path)) = providers.iter().find(|(_, other_path)| {
relative_path.starts_with(other_path) || other_path.starts_with(&relative_path)
}) {
return Err(format!(
"generated provider outputs `{provider}` ({}) and `{other_provider}` ({}) must not overlap",
relative_path.display(),
other_path.display()
));
}
providers.insert(provider, relative_path);
}
let recipe_hash = generated_recipe_hash(
source_ref,
&generator,
&tool.contract_hash,
&output_input,
&providers,
);
Ok(SkillDelivery::Generated {
generator,
generator_contract_hash: tool.contract_hash.clone(),
output_input,
providers,
recipe_hash,
manifest_path,
source_commit: None,
recipe_approved: false,
generator_approved: false,
output_fingerprints: BTreeMap::new(),
derivation_hash: None,
})
}
fn validate_generated_entry(generator: &str, entry: &Path) -> Result<(), String> {
let bytes = fs::read(entry)
.map_err(|error| format!("cannot inspect generator `{generator}` entry: {error}"))?;
let Some(shebang) = bytes.strip_prefix(b"#!") else {
return Ok(());
};
let line = shebang
.split(|byte| *byte == b'\n')
.next()
.unwrap_or_default();
let interpreter = line
.split(|byte| byte.is_ascii_whitespace())
.find(|part| !part.is_empty())
.and_then(|part| std::str::from_utf8(part).ok())
.unwrap_or_default();
if !interpreter.starts_with('/') || interpreter == "/usr/bin/env" {
return Err(format!(
"generator `{generator}` executable entry must use an absolute shebang and must not select an interpreter through /usr/bin/env"
));
}
Ok(())
}
fn validate_relative_generated_path(provider: &str, path: &Path) -> Result<(), String> {
if path.as_os_str().is_empty()
|| path == Path::new(".")
|| path.is_absolute()
|| path.components().any(|component| {
matches!(
component,
std::path::Component::ParentDir
| std::path::Component::RootDir
| std::path::Component::Prefix(_)
)
})
{
return Err(format!(
"generated provider `{provider}` output must be a non-empty relative path inside the staging root"
));
}
Ok(())
}
fn generated_recipe_hash(
source_ref: &str,
generator: &str,
generator_contract_hash: &str,
output_input: &str,
providers: &BTreeMap<String, PathBuf>,
) -> String {
let mut hash = Sha256::new();
for value in [
"dalo-generated-delivery-v1",
source_ref,
generator,
generator_contract_hash,
output_input,
] {
hash.update((value.len() as u64).to_be_bytes());
hash.update(value.as_bytes());
}
for (provider, path) in providers {
hash.update((provider.len() as u64).to_be_bytes());
hash.update(provider.as_bytes());
let path = path.as_os_str().as_encoded_bytes();
hash.update((path.len() as u64).to_be_bytes());
hash.update(path);
}
hash.finalize()
.iter()
.map(|byte| format!("{byte:02x}"))
.collect()
}
fn valid_provider_id(value: &str) -> bool {
!value.is_empty()
&& value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
}
pub(crate) struct DirectoryFingerprint {
pub(crate) fingerprint: String,
pub(crate) catalog_hash: String,
}
pub(crate) fn fingerprint_directory(root: &Path) -> Result<String, String> {
fingerprint_directory_snapshot(root).map(|snapshot| snapshot.fingerprint)
}
pub(crate) fn fingerprint_directory_snapshot(root: &Path) -> Result<DirectoryFingerprint, String> {
fingerprint_directory_snapshot_with(root, |path| {
fs::File::open(path)
.map(|file| Box::new(file) as Box<dyn Read>)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))
})
}
#[derive(Clone, Copy)]
struct FingerprintLimits {
max_depth: usize,
max_entries: usize,
max_file_bytes: u64,
max_total_bytes: u64,
}
const DEFAULT_FINGERPRINT_LIMITS: FingerprintLimits = FingerprintLimits {
max_depth: MAX_FINGERPRINT_DEPTH,
max_entries: MAX_FINGERPRINT_ENTRIES,
max_file_bytes: MAX_FINGERPRINT_FILE_BYTES,
max_total_bytes: MAX_FINGERPRINT_TOTAL_BYTES,
};
struct FingerprintEntry {
relative: PathBuf,
kind: u8,
mode: u32,
content_len: u64,
}
fn fingerprint_directory_snapshot_with<R>(
root: &Path,
open_file: R,
) -> Result<DirectoryFingerprint, String>
where
R: FnMut(&Path) -> Result<Box<dyn Read>, String>,
{
fingerprint_directory_snapshot_with_limits(root, open_file, DEFAULT_FINGERPRINT_LIMITS)
}
fn fingerprint_directory_snapshot_with_limits<R>(
root: &Path,
mut open_file: R,
limits: FingerprintLimits,
) -> Result<DirectoryFingerprint, String>
where
R: FnMut(&Path) -> Result<Box<dyn Read>, String>,
{
let metadata = fs::symlink_metadata(root)
.map_err(|error| format!("cannot inspect `{}`: {error}", root.display()))?;
if metadata.file_type().is_symlink() || !metadata.is_dir() {
return Err(format!("`{}` must be a real directory", root.display()));
}
let mut entries = Vec::new();
collect_fingerprint_entries(root, root, 0, &mut entries, limits)?;
entries.sort_by(|left, right| left.relative.cmp(&right.relative));
let mut expected_total_bytes = 0_u64;
for entry in &entries {
if entry.kind != b'f' {
continue;
}
if entry.content_len > limits.max_file_bytes {
return Err(format!(
"file `{}` exceeds the {}-byte per-file fingerprint limit; remove large generated content or split the skill",
entry.relative.display(),
limits.max_file_bytes
));
}
expected_total_bytes = expected_total_bytes
.checked_add(entry.content_len)
.ok_or_else(|| "directory fingerprint byte total overflowed".to_owned())?;
if expected_total_bytes > limits.max_total_bytes {
return Err(format!(
"directory fingerprint exceeds the {}-byte total content limit; remove large generated content or split the skill",
limits.max_total_bytes
));
}
}
let mut hash = Sha256::new();
let mut catalog_hash = Sha256::new();
let mut total_bytes_read = 0_u64;
for entry in entries {
let relative = entry.relative.as_os_str().as_encoded_bytes();
hash.update(relative);
hash.update([0]);
hash.update([entry.kind]);
hash.update(entry.mode.to_be_bytes());
hash.update(entry.content_len.to_be_bytes());
if entry.kind == b'f' {
catalog_hash.update((relative.len() as u64).to_le_bytes());
catalog_hash.update(relative);
catalog_hash.update(*b"F");
catalog_hash.update(entry.mode.to_le_bytes());
catalog_hash.update(entry.content_len.to_le_bytes());
let path = root.join(&entry.relative);
let mut file = open_file(&path)?;
let mut file_bytes_read = 0_u64;
let mut buffer = [0_u8; FINGERPRINT_READ_BUFFER_BYTES];
loop {
let bytes_read = file
.read(&mut buffer)
.map_err(|error| format!("cannot read `{}`: {error}", path.display()))?;
if bytes_read == 0 {
break;
}
let bytes_read = bytes_read as u64;
if file_bytes_read.saturating_add(bytes_read) > entry.content_len {
return Err(format!(
"file `{}` changed while fingerprinting; it grew beyond its recorded {}-byte size",
entry.relative.display(),
entry.content_len
));
}
if total_bytes_read.saturating_add(bytes_read) > limits.max_total_bytes {
return Err(format!(
"directory fingerprint exceeds the {}-byte total content limit while reading `{}`",
limits.max_total_bytes,
entry.relative.display()
));
}
hash.update(&buffer[..bytes_read as usize]);
catalog_hash.update(&buffer[..bytes_read as usize]);
file_bytes_read += bytes_read;
total_bytes_read += bytes_read;
}
if file_bytes_read != entry.content_len {
return Err(format!(
"file `{}` changed while fingerprinting; expected {} bytes but read {file_bytes_read}",
entry.relative.display(),
entry.content_len
));
}
}
}
let digest = hash.finalize();
let hex = digest
.iter()
.map(|byte| format!("{byte:02x}"))
.collect::<String>();
let catalog_hash = catalog_hash
.finalize()
.iter()
.map(|byte| format!("{byte:02x}"))
.collect();
Ok(DirectoryFingerprint {
fingerprint: format!("sha256:{hex}"),
catalog_hash,
})
}
fn collect_fingerprint_entries(
root: &Path,
directory: &Path,
depth: usize,
entries: &mut Vec<FingerprintEntry>,
limits: FingerprintLimits,
) -> Result<(), String> {
let children = fs::read_dir(directory)
.map_err(|error| format!("cannot read `{}`: {error}", directory.display()))?;
for child in children {
let child = child.map_err(|error| {
format!("cannot read entry below `{}`: {error}", directory.display())
})?;
let path = child.path();
let relative = path
.strip_prefix(root)
.expect("descendant must stay below fingerprint root")
.to_path_buf();
let child_depth = depth + 1;
if child_depth > limits.max_depth {
return Err(format!(
"directory fingerprint exceeds the {}-level depth limit; flatten the skill directory structure",
limits.max_depth
));
}
let metadata = fs::symlink_metadata(&path)
.map_err(|error| format!("cannot inspect `{}`: {error}", path.display()))?;
if metadata.file_type().is_symlink() {
return Err(format!("symlink `{}` is not allowed", relative.display()));
}
if metadata.is_dir() {
push_fingerprint_entry(
entries,
limits,
FingerprintEntry {
relative,
kind: b'd',
mode: 0,
content_len: 0,
},
)?;
collect_fingerprint_entries(root, &path, child_depth, entries, limits)?;
} else if metadata.is_file() {
push_fingerprint_entry(
entries,
limits,
FingerprintEntry {
relative,
kind: b'f',
mode: metadata.permissions().mode() & 0o111,
content_len: metadata.len(),
},
)?;
} else {
return Err(format!(
"special filesystem entry `{}` is not allowed",
relative.display()
));
}
}
Ok(())
}
fn push_fingerprint_entry(
entries: &mut Vec<FingerprintEntry>,
limits: FingerprintLimits,
entry: FingerprintEntry,
) -> Result<(), String> {
if entries.len() >= limits.max_entries {
return Err(format!(
"directory fingerprint exceeds the {}-entry limit; remove large generated trees or split the skill",
limits.max_entries
));
}
entries.push(entry);
Ok(())
}
pub(crate) fn invalid_slot_name_warning(skill_dir: &Path) -> DaloResult<Option<InventoryWarning>> {
let (_, warnings) = scan_skill("adopt", skill_dir, skill_dir, &[])?;
Ok(warnings
.into_iter()
.find(|warning| warning.code == InventoryWarningCode::InvalidSlotName))
}
pub(crate) fn read_skill_metadata(path: &Path) -> io::Result<(String, bool)> {
let file = fs::File::open(path)?;
let metadata_truncated = file.metadata()?.len() > MAX_SKILL_METADATA_BYTES as u64;
let mut bytes = Vec::with_capacity(MAX_SKILL_METADATA_BYTES);
file.take(MAX_SKILL_METADATA_BYTES as u64)
.read_to_end(&mut bytes)?;
let markdown = match String::from_utf8(bytes) {
Ok(markdown) => markdown,
Err(error) if metadata_truncated && error.utf8_error().error_len().is_none() => {
let valid_up_to = error.utf8_error().valid_up_to();
let mut bytes = error.into_bytes();
bytes.truncate(valid_up_to);
String::from_utf8(bytes).expect("validated UTF-8 prefix should remain valid")
}
Err(error) => return Err(io::Error::new(io::ErrorKind::InvalidData, error)),
};
Ok((markdown, metadata_truncated))
}
fn parse_frontmatter(
markdown: &str,
path: &Path,
metadata_truncated: bool,
) -> (Option<SkillFrontmatter>, Vec<InventoryWarning>) {
let mut warnings = Vec::new();
let opened = markdown
.strip_prefix("---\n")
.or_else(|| markdown.strip_prefix("---\r\n"));
let Some(rest) = opened else {
return (Some(SkillFrontmatter::default()), warnings);
};
let Some(end_index) = frontmatter_end_index(rest) else {
warnings.push(InventoryWarning {
code: InventoryWarningCode::MalformedFrontmatter,
path: path.to_path_buf(),
message: if metadata_truncated {
format!("frontmatter exceeds the {MAX_FRONTMATTER_BYTES}-byte safety limit")
} else {
"frontmatter start marker has no matching end marker".to_owned()
},
});
return (None, warnings);
};
let frontmatter = &rest[..end_index];
if frontmatter.len() > MAX_FRONTMATTER_BYTES {
warnings.push(InventoryWarning {
code: InventoryWarningCode::MalformedFrontmatter,
path: path.to_path_buf(),
message: format!("frontmatter exceeds the {MAX_FRONTMATTER_BYTES}-byte safety limit"),
});
return (None, warnings);
}
if frontmatter_flow_depth_exceeds(frontmatter, MAX_FRONTMATTER_FLOW_DEPTH) {
warnings.push(InventoryWarning {
code: InventoryWarningCode::MalformedFrontmatter,
path: path.to_path_buf(),
message: format!(
"frontmatter flow nesting exceeds the {MAX_FRONTMATTER_FLOW_DEPTH}-level safety limit"
),
});
return (None, warnings);
}
if frontmatter_anchor_or_alias_references_exceed(
frontmatter,
MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES,
) {
warnings.push(InventoryWarning {
code: InventoryWarningCode::MalformedFrontmatter,
path: path.to_path_buf(),
message: format!(
"frontmatter anchor/alias references exceed the {MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES}-reference safety limit"
),
});
return (None, warnings);
}
match yaml_serde::from_str(frontmatter) {
Ok(frontmatter) => (Some(frontmatter), warnings),
Err(error) => {
warnings.push(InventoryWarning {
code: InventoryWarningCode::MalformedFrontmatter,
path: path.to_path_buf(),
message: error.to_string(),
});
(None, warnings)
}
}
}
pub(crate) enum RawFrontmatter {
Missing,
Malformed(String),
Mapping {
fields: yaml_serde::Mapping,
body_line_count: usize,
},
}
pub(crate) fn raw_frontmatter(markdown: &str, metadata_truncated: bool) -> RawFrontmatter {
let opened = markdown
.strip_prefix("---\n")
.or_else(|| markdown.strip_prefix("---\r\n"));
let Some(rest) = opened else {
return RawFrontmatter::Missing;
};
let Some(end_index) = frontmatter_end_index(rest) else {
return RawFrontmatter::Malformed(if metadata_truncated {
format!("frontmatter exceeds the {MAX_FRONTMATTER_BYTES}-byte safety limit")
} else {
"frontmatter start marker has no matching end marker".to_owned()
});
};
let frontmatter = &rest[..end_index];
if frontmatter.len() > MAX_FRONTMATTER_BYTES {
return RawFrontmatter::Malformed(format!(
"frontmatter exceeds the {MAX_FRONTMATTER_BYTES}-byte safety limit"
));
}
if frontmatter_flow_depth_exceeds(frontmatter, MAX_FRONTMATTER_FLOW_DEPTH) {
return RawFrontmatter::Malformed(format!(
"frontmatter flow nesting exceeds the {MAX_FRONTMATTER_FLOW_DEPTH}-level safety limit"
));
}
if frontmatter_anchor_or_alias_references_exceed(
frontmatter,
MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES,
) {
return RawFrontmatter::Malformed(format!(
"frontmatter anchor/alias references exceed the {MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES}-reference safety limit"
));
}
match yaml_serde::from_str::<yaml_serde::Value>(frontmatter) {
Ok(yaml_serde::Value::Mapping(fields)) => RawFrontmatter::Mapping {
fields,
body_line_count: rest[end_index..].lines().skip(1).count(),
},
Ok(_) => RawFrontmatter::Malformed("frontmatter is not a mapping".to_owned()),
Err(error) => RawFrontmatter::Malformed(error.to_string()),
}
}
fn frontmatter_flow_depth_exceeds(frontmatter: &str, limit: usize) -> bool {
let structural_frontmatter = frontmatter_without_block_scalar_bodies(frontmatter);
let mut chars = structural_frontmatter.chars().peekable();
let mut depth = 0_usize;
let mut in_single_quote = false;
let mut in_double_quote = false;
let mut escaped = false;
let mut in_comment = false;
let mut previous = None;
while let Some(character) = chars.next() {
if in_comment {
if character == '\n' {
in_comment = false;
}
previous = Some(character);
continue;
}
if in_single_quote {
if character == '\'' {
if chars.peek() == Some(&'\'') {
chars.next();
} else {
in_single_quote = false;
}
}
previous = Some(character);
continue;
}
if in_double_quote {
if escaped {
escaped = false;
} else if character == '\\' {
escaped = true;
} else if character == '"' {
in_double_quote = false;
}
previous = Some(character);
continue;
}
match character {
'#' if previous.is_none_or(char::is_whitespace) => in_comment = true,
'\'' => in_single_quote = true,
'"' => in_double_quote = true,
'[' | '{' => {
depth += 1;
if depth > limit {
return true;
}
}
']' | '}' => depth = depth.saturating_sub(1),
_ => {}
}
previous = Some(character);
}
false
}
fn frontmatter_anchor_or_alias_references_exceed(frontmatter: &str, limit: usize) -> bool {
let structural_frontmatter = frontmatter_without_block_scalar_bodies(frontmatter);
let mut chars = structural_frontmatter.chars().peekable();
let mut references = 0_usize;
let mut in_single_quote = false;
let mut in_double_quote = false;
let mut escaped = false;
let mut in_comment = false;
let mut scalar_can_start = true;
let mut flow_depth = 0_usize;
let mut previous = None;
let mut at_line_start = true;
let mut line_indent = 0_usize;
let mut plain_scalar_indent = None;
let mut plain_scalar_sequence_mapping_indent = None;
let mut line_starts_sequence_item = false;
let mut plain_scalar_may_be_mapping_key = false;
let mut mapping_key_property_prefix = false;
let mut pending_mapping_key_references = 0_usize;
let mut in_tag_property = false;
let mut in_anchor_property = false;
while let Some(character) = chars.next() {
if at_line_start && character == ' ' {
line_indent += 1;
previous = Some(character);
continue;
}
if at_line_start && character != '\n' {
at_line_start = false;
line_starts_sequence_item =
character == '-' && chars.peek().is_some_and(|next| next.is_whitespace());
if !in_comment && !in_single_quote && !in_double_quote {
if plain_scalar_indent.is_some_and(|indent| line_indent > indent) {
scalar_can_start = false;
if plain_scalar_sequence_mapping_indent
.is_some_and(|sequence_indent| line_indent > sequence_indent)
{
plain_scalar_may_be_mapping_key = true;
mapping_key_property_prefix = true;
}
} else if plain_scalar_indent == Some(line_indent) {
if same_indent_line_starts_with_quoted_mapping_key(character, &chars) {
scalar_can_start = true;
} else {
scalar_can_start = false;
plain_scalar_may_be_mapping_key = true;
mapping_key_property_prefix = true;
}
} else {
plain_scalar_indent = None;
scalar_can_start = true;
}
}
}
if in_tag_property {
if character == '\n' {
in_tag_property = false;
at_line_start = true;
line_indent = 0;
} else if character.is_whitespace() {
in_tag_property = false;
}
previous = Some(character);
continue;
}
if in_anchor_property {
if character == '\n' {
in_anchor_property = false;
plain_scalar_indent = None;
scalar_can_start = true;
at_line_start = true;
line_indent = 0;
} else if character.is_whitespace() {
in_anchor_property = false;
}
previous = Some(character);
continue;
}
if in_comment {
if character == '\n' {
in_comment = false;
scalar_can_start = true;
at_line_start = true;
line_indent = 0;
}
previous = Some(character);
continue;
}
if in_single_quote {
if character == '\'' {
if chars.peek() == Some(&'\'') {
chars.next();
} else {
in_single_quote = false;
scalar_can_start = false;
}
}
previous = Some(character);
continue;
}
if in_double_quote {
if escaped {
escaped = false;
} else if character == '\\' {
escaped = true;
} else if character == '"' {
in_double_quote = false;
scalar_can_start = false;
}
previous = Some(character);
continue;
}
match character {
'#' if previous.is_none_or(char::is_whitespace) => in_comment = true,
'\'' if scalar_can_start => in_single_quote = true,
'"' if scalar_can_start => in_double_quote = true,
'&' if (scalar_can_start || plain_scalar_may_be_mapping_key)
&& yaml_anchor_or_alias_starts(previous, chars.peek().copied()) =>
{
if plain_scalar_may_be_mapping_key {
if mapping_key_property_prefix {
pending_mapping_key_references += 1;
}
} else {
in_anchor_property = true;
references += 1;
if references > limit {
return true;
}
}
}
'*' if (scalar_can_start || plain_scalar_may_be_mapping_key)
&& yaml_anchor_or_alias_starts(previous, chars.peek().copied()) =>
{
if plain_scalar_may_be_mapping_key {
if mapping_key_property_prefix {
pending_mapping_key_references += 1;
}
} else {
plain_scalar_indent = Some(line_indent);
references += 1;
if references > limit {
return true;
}
}
}
'\n' => {
line_starts_sequence_item = false;
plain_scalar_may_be_mapping_key = false;
mapping_key_property_prefix = false;
pending_mapping_key_references = 0;
scalar_can_start = true;
at_line_start = true;
line_indent = 0;
}
'[' | '{' | ',' => {
flow_depth += matches!(character, '[' | '{') as usize;
plain_scalar_indent = None;
scalar_can_start = true;
}
']' | '}' => {
flow_depth = flow_depth.saturating_sub(1);
plain_scalar_indent = None;
scalar_can_start = false;
}
':' if flow_depth > 0 || chars.peek().is_some_and(|next| next.is_whitespace()) => {
references += pending_mapping_key_references;
if references > limit {
return true;
}
plain_scalar_may_be_mapping_key = false;
mapping_key_property_prefix = false;
pending_mapping_key_references = 0;
plain_scalar_indent = None;
scalar_can_start = true;
}
'!' if scalar_can_start
|| (plain_scalar_may_be_mapping_key && mapping_key_property_prefix) =>
{
in_tag_property = true;
}
'-' | '?'
if (scalar_can_start || plain_scalar_may_be_mapping_key)
&& chars.peek().is_some_and(|next| next.is_whitespace()) =>
{
plain_scalar_may_be_mapping_key = false;
mapping_key_property_prefix = false;
pending_mapping_key_references = 0;
plain_scalar_indent = None;
scalar_can_start = true;
}
character if !character.is_whitespace() => {
if plain_scalar_may_be_mapping_key {
mapping_key_property_prefix = false;
}
if scalar_can_start {
plain_scalar_indent = Some(line_indent);
plain_scalar_sequence_mapping_indent =
line_starts_sequence_item.then_some(line_indent);
}
scalar_can_start = false;
}
_ => {}
}
previous = Some(character);
}
false
}
fn yaml_anchor_or_alias_starts(previous: Option<char>, next: Option<char>) -> bool {
previous.is_none_or(|character| {
character.is_whitespace() || matches!(character, '[' | '{' | ',' | ':' | '?')
}) && next.is_some_and(|character| {
!character.is_whitespace() && !matches!(character, '[' | ']' | '{' | '}' | ',')
})
}
fn same_indent_line_starts_with_quoted_mapping_key(
opening_quote: char,
chars: &std::iter::Peekable<std::str::Chars<'_>>,
) -> bool {
if !matches!(opening_quote, '\'' | '"') {
return false;
}
let mut chars = chars.clone();
let mut escaped = false;
while let Some(character) = chars.next() {
if opening_quote == '\'' && character == '\'' && chars.peek() == Some(&'\'') {
chars.next();
continue;
}
if opening_quote == '"' && !escaped && character == '\\' {
escaped = true;
continue;
}
if character == opening_quote && !escaped {
while chars
.peek()
.is_some_and(|character| character.is_whitespace())
{
chars.next();
}
return chars.next() == Some(':')
&& chars
.peek()
.is_none_or(|character| character.is_whitespace());
}
escaped = false;
}
false
}
fn frontmatter_without_block_scalar_bodies(frontmatter: &str) -> String {
let mut structural = String::with_capacity(frontmatter.len());
let mut block_scalar_indent = None;
for line in frontmatter.split_inclusive('\n') {
let content = line.strip_suffix('\n').unwrap_or(line);
let content = content.strip_suffix('\r').unwrap_or(content);
let trimmed = content.trim_start_matches(' ');
let indent = content.len() - trimmed.len();
if let Some(header_indent) = block_scalar_indent {
if trimmed.is_empty() || indent > header_indent {
if line.ends_with('\n') {
structural.push('\n');
}
continue;
}
block_scalar_indent = None;
}
structural.push_str(line);
if is_block_scalar_header(trimmed) {
block_scalar_indent = Some(indent);
}
}
structural
}
fn is_block_scalar_header(line: &str) -> bool {
if line.starts_with('#') {
return false;
}
let value = if let Some(sequence_value) = line.strip_prefix('-')
&& sequence_value
.chars()
.next()
.is_some_and(char::is_whitespace)
{
sequence_value.trim_start()
} else if let Some((_, mapping_value)) = line.split_once(':') {
mapping_value.trim_start()
} else {
return false;
};
let Some(indicator) = value.chars().next() else {
return false;
};
if !matches!(indicator, '|' | '>') {
return false;
}
value[indicator.len_utf8()..]
.split('#')
.next()
.is_some_and(|suffix| {
suffix
.trim()
.chars()
.all(|character| matches!(character, '+' | '-' | '1'..='9'))
})
}
fn frontmatter_end_index(rest: &str) -> Option<usize> {
let mut offset = 0;
for line in rest.split_inclusive('\n') {
let line_without_newline = line.strip_suffix('\n').unwrap_or(line);
let line_without_cr = line_without_newline
.strip_suffix('\r')
.unwrap_or(line_without_newline);
if line_without_cr == "---" {
return Some(offset);
}
offset += line.len();
}
None
}
fn select_slot_name(
frontmatter: &SkillFrontmatter,
folder_name: &str,
path: &Path,
warnings: &mut Vec<InventoryWarning>,
) -> Option<String> {
if let Some(name) = frontmatter.name.as_deref() {
let trimmed = name.trim();
if is_valid_slot_name(trimmed) {
return Some(trimmed.to_owned());
}
warnings.push(InventoryWarning {
code: InventoryWarningCode::InvalidSlotName,
path: path.to_path_buf(),
message: format!("frontmatter name `{name}` is not a valid slot name"),
});
}
if is_valid_slot_name(folder_name) {
return Some(folder_name.to_owned());
}
warnings.push(InventoryWarning {
code: InventoryWarningCode::InvalidSlotName,
path: path.to_path_buf(),
message: format!("folder name `{folder_name}` is not a valid slot name"),
});
None
}
pub(crate) fn is_valid_slot_name(value: &str) -> bool {
if value.is_empty()
|| value.len() > MAX_SLOT_NAME_LENGTH
|| value == "."
|| value == ".."
|| value.starts_with('.')
|| value.ends_with('.')
|| is_windows_reserved_basename(value)
{
return false;
}
value.chars().all(|character| {
character.is_ascii_lowercase()
|| character.is_ascii_digit()
|| character == '-'
|| character == '_'
|| character == '.'
})
}
fn is_windows_reserved_basename(value: &str) -> bool {
let basename = value.split('.').next().unwrap_or(value);
matches!(
basename,
"con"
| "prn"
| "aux"
| "nul"
| "com1"
| "com2"
| "com3"
| "com4"
| "com5"
| "com6"
| "com7"
| "com8"
| "com9"
| "lpt1"
| "lpt2"
| "lpt3"
| "lpt4"
| "lpt5"
| "lpt6"
| "lpt7"
| "lpt8"
| "lpt9"
)
}
fn duplicate_slot_warnings(source_id: &str, skills: &[SkillRecord]) -> Vec<InventoryWarning> {
let mut paths_by_slot: BTreeMap<&str, Vec<&Path>> = BTreeMap::new();
for skill in skills {
paths_by_slot
.entry(&skill.slot_name)
.or_default()
.push(&skill.path);
}
paths_by_slot
.into_iter()
.filter(|(_, paths)| paths.len() > 1)
.flat_map(|(slot_name, paths)| {
paths.into_iter().map(move |path| InventoryWarning {
code: InventoryWarningCode::DuplicateSlotName,
path: path.to_path_buf(),
message: format!(
"source `{source_id}` contains multiple skills with slot name `{slot_name}`"
),
})
})
.collect()
}
fn warning_code_name(code: InventoryWarningCode) -> &'static str {
match code {
InventoryWarningCode::MalformedFrontmatter => "malformed_frontmatter",
InventoryWarningCode::InvalidSlotName => "invalid_slot_name",
InventoryWarningCode::DuplicateSlotName => "duplicate_slot_name",
InventoryWarningCode::UnreadablePath => "unreadable_path",
InventoryWarningCode::SkippedSymlink => "skipped_symlink",
InventoryWarningCode::InvalidDelivery => "invalid_delivery",
InventoryWarningCode::InvalidBinaryDeclaration => "invalid_binary_declaration",
}
}
impl std::fmt::Display for InventoryWarningCode {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(warning_code_name(*self))
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::cell::Cell;
use std::io::Read as IoRead;
use std::rc::Rc;
use proptest::prelude::*;
fn write_generator_plugin(root: &Path) {
let package = root.join("plugins/builder");
fs::create_dir_all(package.join("bin")).unwrap();
let entry = package.join("bin/build.sh");
fs::write(&entry, "#!/bin/sh\nprintf 'not executed\\n'\n").unwrap();
fs::set_permissions(&entry, fs::Permissions::from_mode(0o755)).unwrap();
fs::write(
package.join("PLUGIN.toml"),
r#"schema_version = 1
[plugin]
name = "builder"
description = "Inert generator fixture"
[[tool]]
schema_version = 1
id = "build"
entry = "bin/build.sh"
runtime = "executable"
platforms = ["macos", "linux"]
argv = ["${input.output_dir}"]
cwd = "tool_root"
capabilities = ["filesystem_write"]
availability = "required"
[[tool.inputs]]
name = "output_dir"
type = "path"
required = true
"#,
)
.unwrap();
}
#[test]
fn directory_snapshot_should_read_each_file_once_and_preserve_both_hashes() {
let temporary = tempfile::tempdir().expect("tempdir should be created");
let root = temporary.path().join("provider");
fs::create_dir_all(root.join("nested")).expect("fixture directories should be created");
fs::write(root.join("SKILL.md"), "# Generated\n").expect("skill should be written");
fs::write(root.join("nested/config.json"), "{}\n").expect("config should be written");
let mut reads = BTreeMap::new();
let snapshot = fingerprint_directory_snapshot_with(&root, |path| {
*reads.entry(path.to_path_buf()).or_insert(0_usize) += 1;
fs::File::open(path)
.map(|file| Box::new(file) as Box<dyn Read>)
.map_err(|error| error.to_string())
})
.expect("snapshot should succeed");
assert_eq!(reads.len(), 2);
assert!(reads.values().all(|count| *count == 1));
assert_eq!(
snapshot.fingerprint,
fingerprint_directory(&root).expect("legacy fingerprint should remain stable")
);
assert_eq!(
snapshot.fingerprint,
"sha256:70b233d5939b9f8189a4dd4b8789dcf07f87f77788b73c98bce6006ef73cd132"
);
assert_eq!(
snapshot.catalog_hash,
crate::catalog::hash_directory(&root).expect("audit hash input should remain stable")
);
}
#[test]
fn directory_fingerprint_should_stream_large_files_in_bounded_chunks() {
struct ZeroReader {
remaining: u64,
largest_buffer: Rc<Cell<usize>>,
}
impl IoRead for ZeroReader {
fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
self.largest_buffer
.set(self.largest_buffer.get().max(buffer.len()));
let count = self.remaining.min(buffer.len() as u64) as usize;
buffer[..count].fill(0);
self.remaining -= count as u64;
Ok(count)
}
}
let temporary = tempfile::tempdir().expect("tempdir should be created");
let root = temporary.path().join("large-skill");
fs::create_dir_all(root.join("nested")).expect("skill directories should be created");
let large_file = root.join("nested/large.dat");
let file_size = 32 * 1024 * 1024_u64;
fs::File::create(&large_file)
.expect("large file should be created")
.set_len(file_size)
.expect("large file should be sparse");
let largest_buffer = Rc::new(Cell::new(0));
let opened_files = Rc::new(Cell::new(0));
let snapshot = fingerprint_directory_snapshot_with(&root, {
let largest_buffer = Rc::clone(&largest_buffer);
let opened_files = Rc::clone(&opened_files);
move |_| {
opened_files.set(opened_files.get() + 1);
Ok(Box::new(ZeroReader {
remaining: file_size,
largest_buffer: Rc::clone(&largest_buffer),
}) as Box<dyn Read>)
}
})
.expect("large file should be fingerprinted through bounded reads");
assert_eq!(opened_files.get(), 1);
assert_eq!(largest_buffer.get(), FINGERPRINT_READ_BUFFER_BYTES);
assert_eq!(
snapshot.fingerprint,
fingerprint_directory(&root).expect("production reader should stream the large file")
);
}
#[test]
fn directory_fingerprint_should_reject_entry_overflow_before_opening_files() {
let temporary = tempfile::tempdir().expect("tempdir should be created");
let root = temporary.path().join("many-files");
fs::create_dir_all(&root).expect("skill directory should be created");
fs::write(root.join("one.txt"), "one").expect("file should be written");
fs::write(root.join("two.txt"), "two").expect("file should be written");
let error = fingerprint_directory_snapshot_with_limits(
&root,
|_| panic!("entry overflow must be detected before opening file content"),
FingerprintLimits {
max_depth: 4,
max_entries: 1,
max_file_bytes: u64::MAX,
max_total_bytes: u64::MAX,
},
)
.err()
.expect("more entries than the configured limit should be rejected");
assert!(error.contains("1-entry limit"), "{error}");
assert!(error.contains("split the skill"), "{error}");
}
#[test]
fn source_traversal_should_report_a_degraded_partial_inventory_at_its_limit() {
let temporary = tempfile::tempdir().expect("tempdir should be created");
let root = temporary.path();
for name in ["a-first", "z-later"] {
let skill = root.join(name);
fs::create_dir_all(&skill).expect("skill directory should be created");
fs::write(skill.join(SKILL_FILE), "# Skill\n").expect("skill file should be written");
}
let mut warnings = Vec::new();
let found = find_skill_dirs_with_limits(
root,
&mut warnings,
SourceTraversalLimits {
max_depth: 4,
max_directories: 2,
max_entries: 20,
max_entries_per_directory: 20,
},
)
.expect("bounded traversal should return its discovered paths");
assert_eq!(found, vec![root.join("a-first")]);
assert_eq!(warnings.len(), 1, "{warnings:?}");
assert_eq!(warnings[0].code, InventoryWarningCode::UnreadablePath);
assert!(warnings[0].message.contains("inventory is incomplete"));
assert!(
warnings[0]
.message
.contains("skills later in this source may be omitted")
);
let inventory = SourceInventory {
source_id: "test".to_owned(),
skills: Vec::new(),
agents: Vec::new(),
plugins: Vec::new(),
warnings,
agent_warnings: Vec::new(),
plugin_warnings: Vec::new(),
};
assert!(crate::resolver::inventory_degrades_source_for_removal(
&inventory
));
}
const BINARY_DIGEST: &str = "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210";
fn page_engine_document(digest: &str) -> String {
format!(
"---\nname: page-engine\ndescription: Audit pages\nbinaries:\n impeccino:\n source: github-release\n repo: sebastian-software/impeccino\n tag: engine-v0.2.0\n assets:\n linux-x64:\n asset: impeccino-linux-x64\n sha256: \"{digest}\"\n---\n# Page engine\n"
)
}
fn write_page_engine(root: &Path, document: &str) {
let skill = root.join("skills/page-engine");
fs::create_dir_all(&skill).unwrap();
fs::write(skill.join(SKILL_FILE), document).unwrap();
}
#[test]
fn skill_with_a_valid_binary_declaration_is_discovered_with_its_record() {
let temp = tempfile::tempdir().unwrap();
write_page_engine(temp.path(), &page_engine_document(BINARY_DIGEST));
let inventory = scan_source("team", temp.path()).unwrap();
assert!(inventory.warnings.is_empty(), "{:?}", inventory.warnings);
assert_eq!(inventory.skills.len(), 1);
let binaries = &inventory.skills[0].binaries;
assert_eq!(binaries.len(), 1);
assert_eq!(binaries[0].source_ref, "team:page-engine#binary:impeccino");
}
#[test]
fn skill_with_an_invalid_binary_digest_is_dropped_with_one_named_warning() {
let temp = tempfile::tempdir().unwrap();
write_page_engine(temp.path(), &page_engine_document(&BINARY_DIGEST[..63]));
let inventory = scan_source("team", temp.path()).unwrap();
assert!(inventory.skills.is_empty());
assert_eq!(inventory.warnings.len(), 1, "{:?}", inventory.warnings);
let warning = &inventory.warnings[0];
assert_eq!(warning.code, InventoryWarningCode::InvalidBinaryDeclaration);
assert!(warning.message.contains("impeccino"), "{}", warning.message);
assert!(warning.path.ends_with(SKILL_FILE));
}
#[test]
fn duplicate_keys_inside_binaries_fail_the_frontmatter_closed() {
let temp = tempfile::tempdir().unwrap();
let document = page_engine_document(BINARY_DIGEST).replace(
" repo: sebastian-software/impeccino\n",
" repo: sebastian-software/impeccino\n repo: example/other\n",
);
write_page_engine(temp.path(), &document);
let inventory = scan_source("team", temp.path()).unwrap();
assert!(inventory.skills.is_empty());
assert_eq!(inventory.warnings.len(), 1, "{:?}", inventory.warnings);
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
}
#[test]
fn scan_source_should_validate_generated_recipe_without_creating_outputs() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/impeccable");
fs::create_dir_all(&logical).unwrap();
fs::write(
logical.join(SKILL_FILE),
"---\nid: impeccable.skill\n---\n# Impeccable\n",
)
.unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"output_dir\"\n\n[providers]\ncodex = \"codex/impeccable\"\nclaude = \"claude/impeccable\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
let SkillDelivery::Generated {
generator,
generator_contract_hash,
providers,
recipe_hash,
recipe_approved,
generator_approved,
..
} = &inventory.skills[0].delivery
else {
panic!("logical skill should retain an inert generated recipe");
};
assert_eq!(generator, "company:builder#tool:build");
assert_eq!(generator_contract_hash.len(), 64);
assert_eq!(providers["codex"], PathBuf::from("codex/impeccable"));
assert_eq!(recipe_hash.len(), 64);
assert!(!recipe_approved);
assert!(!generator_approved);
assert!(!temp_dir.path().join("codex/impeccable").exists());
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_reject_generated_recipe_without_bounded_output_input() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("review");
fs::create_dir_all(&logical).unwrap();
fs::write(
logical.join(SKILL_FILE),
"---\nid: review.skill\n---\n# Review\n",
)
.unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"missing\"\n\n[providers]\ncodex = \"codex/review\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning
.message
.contains("does not declare output input `missing`")
}));
}
#[test]
fn scan_source_should_reject_generated_recipe_without_stable_skill_id() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("review");
fs::create_dir_all(&logical).unwrap();
fs::write(logical.join(SKILL_FILE), "# Review\n").unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"output_dir\"\n\n[providers]\ncodex = \"codex/review\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning
.message
.contains("requires a stable skill frontmatter `id`")
}));
}
#[test]
fn scan_source_should_reject_overlapping_generated_provider_outputs() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/review");
fs::create_dir_all(&logical).unwrap();
fs::write(
logical.join(SKILL_FILE),
"---\nid: review.skill\n---\n# Review\n",
)
.unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"output_dir\"\n\n[providers]\ncodex = \"shared\"\nclaude = \"shared/review\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("must not overlap")
}));
}
#[test]
fn scan_source_should_reject_generated_runtime_selected_from_path() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/review");
fs::create_dir_all(&logical).unwrap();
fs::write(
logical.join(SKILL_FILE),
"---\nid: review.skill\n---\n# Review\n",
)
.unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"output_dir\"\n\n[providers]\ncodex = \"codex/review\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let manifest = temp_dir.path().join("plugins/builder/PLUGIN.toml");
let content = fs::read_to_string(&manifest)
.unwrap()
.replace("runtime = \"executable\"", "runtime = \"python\"");
fs::write(manifest, content).unwrap();
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("ambient PATH")
}));
}
#[test]
fn scan_source_should_reject_generated_ambient_path() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/review");
fs::create_dir_all(&logical).unwrap();
fs::write(
logical.join(SKILL_FILE),
"---\nid: review.skill\n---\n# Review\n",
)
.unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"output_dir\"\n\n[providers]\ncodex = \"codex/review\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let manifest = temp_dir.path().join("plugins/builder/PLUGIN.toml");
let content = fs::read_to_string(&manifest).unwrap().replace(
"cwd = \"tool_root\"",
"cwd = \"tool_root\"\nenv = [\"PATH\"]",
);
fs::write(manifest, content).unwrap();
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("must not admit ambient PATH")
}));
}
#[test]
fn scan_source_should_reject_env_shebang_for_generated_entry() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/review");
fs::create_dir_all(&logical).unwrap();
fs::write(
logical.join(SKILL_FILE),
"---\nid: review.skill\n---\n# Review\n",
)
.unwrap();
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"generated\"\ngenerator = \"company:builder#tool:build\"\noutput_input = \"output_dir\"\n\n[providers]\ncodex = \"codex/review\"\n",
)
.unwrap();
write_generator_plugin(temp_dir.path());
let entry = temp_dir.path().join("plugins/builder/bin/build.sh");
fs::write(&entry, "#!/usr/bin/env sh\nprintf 'unsafe\\n'\n").unwrap();
fs::set_permissions(&entry, fs::Permissions::from_mode(0o755)).unwrap();
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("must not select an interpreter")
}));
}
#[test]
fn scan_source_should_resolve_prebuilt_provider_artifacts_once() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/impeccable");
let codex = temp_dir.path().join("builds/codex/impeccable");
let claude = temp_dir.path().join("builds/claude/impeccable");
for directory in [&logical, &codex, &claude] {
fs::create_dir_all(directory).expect("skill directory should be created");
fs::write(directory.join(SKILL_FILE), "# Impeccable\n")
.expect("skill file should be written");
}
fs::write(
claude.join(SKILL_FILE),
"---\nprovider-specific: [frontmatter\n---\n# Claude Impeccable\n",
)
.expect("provider-specific skill file should be written");
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"prebuilt\"\n\n[providers]\ncodex = \"builds/codex/impeccable\"\nclaude = \"builds/claude/impeccable\"\n",
)
.expect("delivery manifest should be written");
let inventory = scan_source("catalog", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
let SkillDelivery::Prebuilt { providers, .. } = &inventory.skills[0].delivery else {
panic!("logical skill should use prebuilt delivery");
};
assert_eq!(providers["codex"].path, codex);
assert_eq!(providers["claude"].path, claude);
assert!(providers["codex"].fingerprint.starts_with("sha256:"));
assert!(inventory.warnings.is_empty());
}
#[test]
fn prebuilt_fingerprint_limit_should_produce_an_actionable_inventory_warning() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("skills/review");
let provider = temp_dir.path().join("builds/codex/review");
for directory in [&logical, &provider] {
fs::create_dir_all(directory).expect("skill directory should be created");
fs::write(directory.join(SKILL_FILE), "# Review\n")
.expect("skill file should be written");
}
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"prebuilt\"\n\n[providers]\ncodex = \"builds/codex/review\"\n",
)
.expect("delivery manifest should be written");
fs::File::create(provider.join("large-generated-data.bin"))
.expect("large sparse file should be created")
.set_len(MAX_FINGERPRINT_FILE_BYTES + 1)
.expect("large sparse file length should be set");
let (skill, warnings) = scan_skill("team", temp_dir.path(), &logical, &[])
.expect("skill scan should return a diagnostic");
assert!(skill.is_none());
assert!(warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("per-file fingerprint limit")
&& warning.message.contains("remove large generated content")
}));
}
#[test]
fn scan_source_should_fail_closed_for_unsafe_prebuilt_artifact() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let outside = tempfile::tempdir().expect("outside tempdir should be created");
let logical = temp_dir.path().join("review");
fs::create_dir_all(&logical).expect("skill directory should be created");
fs::write(logical.join(SKILL_FILE), "# Review\n").expect("skill should be written");
fs::write(outside.path().join(SKILL_FILE), "# Outside\n")
.expect("outside skill should be written");
std::os::unix::fs::symlink(outside.path(), temp_dir.path().join("escaped"))
.expect("escape symlink should be created");
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"prebuilt\"\n\n[providers]\ncodex = \"escaped\"\n",
)
.expect("delivery manifest should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("inside the source checkout")
}));
}
#[test]
fn scan_source_should_reject_a_non_regular_delivery_manifest_without_opening_it() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("review");
fs::create_dir_all(logical.join(DELIVERY_FILE))
.expect("directory-shaped manifest should be created");
fs::write(logical.join(SKILL_FILE), "# Review\n").expect("skill should be written");
let inventory = scan_source("local", temp_dir.path()).expect("scan should complete");
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::InvalidDelivery
&& warning.message.contains("must be a regular file")
}));
}
#[test]
fn delivery_manifest_should_reserve_universal_for_the_fallback_artifact() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let logical = temp_dir.path().join("review");
let universal = temp_dir.path().join("builds/universal/review");
for directory in [&logical, &universal] {
fs::create_dir_all(directory).expect("skill directory should be created");
fs::write(directory.join(SKILL_FILE), "# Review\n").expect("skill should be written");
}
fs::write(
logical.join(DELIVERY_FILE),
"schema_version = 1\nkind = \"prebuilt\"\nuniversal_fallback = true\n\n[providers]\nuniversal = \"builds/universal/review\"\n",
)
.expect("delivery manifest should be written");
let error = scan_delivery(
"local",
"local:review",
None,
temp_dir.path(),
&logical,
&[],
)
.expect_err("the fallback identity must not collide with a provider mapping");
assert!(error.contains("`universal` is reserved"));
}
#[test]
fn scan_source_should_find_skill_with_frontmatter() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("copy-editing");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nid: team.copy-editing\nname: copy-editing\ndescription: Edit copy\nrequires:\n - style-guide\nowners:\n - docs\ntags:\n - writing\n---\n# Copy Editing\n",
)
.expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
let skill = &inventory.skills[0];
assert_eq!(skill.source_ref, "company:copy-editing");
assert_eq!(skill.id.as_deref(), Some("team.copy-editing"));
assert_eq!(skill.requires, ["style-guide".to_owned()]);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_parse_yaml_frontmatter_and_preserve_dependencies() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("app");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nid: example.app\nname: app\ndescription: >-\n A valid folded YAML description.\nrequires: [missing-base]\nowners:\n - \"team docs\"\nextra:\n nested: accepted\n---\n# App\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills[0].id.as_deref(), Some("example.app"));
assert_eq!(inventory.skills[0].requires, ["missing-base"]);
assert_eq!(
inventory.skills[0].description.as_deref(),
Some("A valid folded YAML description.")
);
}
#[test]
fn scan_source_should_parse_yaml_description_scalar_styles() {
let cases = [
("literal", "|", "First line.\nSecond line.\n"),
("folded", ">", "First line. Second line.\n"),
("stripped", ">-", "First line. Second line."),
];
for (name, style, expected) in cases {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join(name);
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: {name}\ndescription: {style}\n First line.\n Second line.\n---\n# Skill\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills[0].description.as_deref(), Some(expected));
assert!(inventory.warnings.is_empty());
}
}
#[test]
fn scan_source_should_parse_plain_and_quoted_description_scalars() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
for (name, description) in [("plain", "Plain text"), ("quoted", "\"Quoted text\"")] {
let skill_dir = temp_dir.path().join(name);
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
format!("---\nname: {name}\ndescription: {description}\n---\n# Skill\n"),
)
.expect("skill file should be written");
}
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(
inventory.skills[0].description.as_deref(),
Some("Plain text")
);
assert_eq!(
inventory.skills[1].description.as_deref(),
Some("Quoted text")
);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_warn_when_a_skill_directory_is_symlinked() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
let shared_skill = temp_dir.path().join("shared-review");
fs::create_dir_all(&source_root).expect("source root should be created");
fs::create_dir_all(&shared_skill).expect("shared skill should be created");
fs::write(
shared_skill.join(SKILL_FILE),
"---\nname: review\n---\n# Review\n",
)
.expect("skill file should be written");
std::os::unix::fs::symlink(&shared_skill, source_root.join("review"))
.expect("skill directory should be linked");
let inventory = scan_source("team", &source_root).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(inventory.warnings.len(), 1);
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::SkippedSymlink
);
}
#[test]
fn scan_source_should_ignore_regular_file_symlinks() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
fs::create_dir_all(source_root.join("skills/review"))
.expect("skill directory should be created");
fs::write(source_root.join("AGENTS.md"), "# Instructions\n")
.expect("instruction file should be written");
std::os::unix::fs::symlink("AGENTS.md", source_root.join("CLAUDE.md"))
.expect("instruction alias should be linked");
fs::write(source_root.join("skills/review/SKILL.md"), "# Review\n")
.expect("skill file should be written");
let inventory = scan_source("team", &source_root).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_skip_invalid_utf8_skill_metadata_and_keep_valid_siblings() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let valid = temp_dir.path().join("skills/valid");
let invalid = temp_dir.path().join("skills/invalid");
fs::create_dir_all(&valid).expect("valid skill directory should be created");
fs::create_dir_all(&invalid).expect("invalid skill directory should be created");
fs::write(valid.join(SKILL_FILE), "# Valid\n").expect("valid skill should be written");
fs::write(invalid.join(SKILL_FILE), b"# Invalid\n\xff")
.expect("invalid metadata should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should complete");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].slot_name, "valid");
assert_eq!(inventory.warnings.len(), 1);
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::UnreadablePath
);
assert_eq!(inventory.warnings[0].path, invalid.join(SKILL_FILE));
assert!(inventory.warnings[0].message.contains("invalid utf-8"));
}
#[cfg(unix)]
#[test]
fn scan_source_should_fail_closed_for_special_skill_metadata() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let valid = temp_dir.path().join("skills/valid");
let special = temp_dir.path().join("skills/special");
fs::create_dir_all(&valid).expect("valid skill directory should be created");
fs::create_dir_all(&special).expect("special skill directory should be created");
fs::write(valid.join(SKILL_FILE), "# Valid\n").expect("valid skill should be written");
let _socket = std::os::unix::net::UnixListener::bind(special.join(SKILL_FILE))
.expect("special metadata socket should be created");
let inventory = scan_source("team", temp_dir.path()).expect("scan should complete");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].slot_name, "valid");
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::UnreadablePath
&& warning.path == special.join(SKILL_FILE)
&& warning.message == "SKILL.md must be a regular file"
}));
}
#[cfg(unix)]
#[test]
fn scan_source_should_skip_unreadable_skill_metadata_when_permissions_are_enforced() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("skills/review");
fs::create_dir_all(&skill_dir).expect("skill directory should be created");
let skill_file = skill_dir.join(SKILL_FILE);
fs::write(&skill_file, "# Review\n").expect("skill should be written");
let mode = fs::metadata(&skill_file)
.expect("metadata should be readable")
.permissions()
.mode()
& 0o777;
fs::set_permissions(&skill_file, fs::Permissions::from_mode(0o000))
.expect("permissions should be changed");
let inaccessible = fs::File::open(&skill_file).is_err();
let inventory = scan_source("team", temp_dir.path()).expect("scan should complete");
fs::set_permissions(&skill_file, fs::Permissions::from_mode(mode))
.expect("permissions should be restored");
if inaccessible {
assert!(inventory.skills.is_empty());
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::UnreadablePath && warning.path == skill_file
}));
} else {
assert_eq!(inventory.skills.len(), 1);
}
}
#[test]
fn scan_source_should_warn_when_skill_metadata_symlink_escapes_source() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
let external_skill = temp_dir.path().join("external-review");
fs::create_dir_all(source_root.join("skills/review"))
.expect("skill directory should be created");
fs::create_dir_all(&external_skill).expect("external skill directory should be created");
fs::write(
external_skill.join(SKILL_FILE),
"---\nname: external-review\n---\n# External Review\n",
)
.expect("external skill file should be written");
std::os::unix::fs::symlink(
external_skill.join(SKILL_FILE),
source_root.join("skills/review").join(SKILL_FILE),
)
.expect("skill metadata symlink should be created");
let inventory = scan_source("team", &source_root).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(inventory.warnings.len(), 1);
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::SkippedSymlink
);
assert_eq!(
inventory.warnings[0].path,
source_root.join("skills/review").join(SKILL_FILE)
);
}
#[cfg(unix)]
#[test]
fn scan_source_should_continue_below_a_broken_skill_metadata_symlink() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let parent = temp_dir.path().join("skills/parent");
let nested = parent.join("nested");
fs::create_dir_all(&nested).expect("nested skill directory should be created");
std::os::unix::fs::symlink("missing.md", parent.join(SKILL_FILE))
.expect("broken skill metadata symlink should be created");
fs::write(nested.join(SKILL_FILE), "# Nested\n").expect("nested skill should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should complete");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].slot_name, "nested");
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::SkippedSymlink
&& warning.path == parent.join(SKILL_FILE)
}));
}
#[test]
fn scan_source_should_allow_skill_metadata_symlink_inside_source() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
let metadata = source_root.join("metadata/review.md");
let skill_dir = source_root.join("skills/review");
fs::create_dir_all(metadata.parent().expect("metadata should have a parent"))
.expect("metadata directory should be created");
fs::create_dir_all(&skill_dir).expect("skill directory should be created");
fs::write(&metadata, "---\nname: review\n---\n# Review\n")
.expect("metadata should be written");
std::os::unix::fs::symlink(&metadata, skill_dir.join(SKILL_FILE))
.expect("skill metadata symlink should be created");
let inventory = scan_source("team", &source_root).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_warn_when_a_skill_symlink_is_broken() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
fs::create_dir_all(&source_root).expect("source root should be created");
std::os::unix::fs::symlink(
temp_dir.path().join("missing-review"),
source_root.join("review"),
)
.expect("broken skill symlink should be created");
let inventory = scan_source("team", &source_root).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(inventory.warnings.len(), 1);
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::SkippedSymlink
);
assert_eq!(inventory.warnings[0].path, source_root.join("review"));
}
#[test]
fn scan_source_should_ignore_hidden_adoption_debris() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
for directory in ["review", ".review.dalo-adopting-interrupted"] {
let skill_dir = source_root.join(directory);
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: review\n---\n# Review\n",
)
.expect("skill file should be written");
}
let inventory = scan_source("local", &source_root).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].path, source_root.join("review"));
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_allow_skills_in_hidden_directories() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let source_root = temp_dir.path().join("checkout");
let skill_dir = source_root.join("tools/.review");
fs::create_dir_all(&skill_dir).expect("hidden skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: review\n---\n# Review\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", &source_root).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].path, skill_dir);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_skip_malformed_frontmatter() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("app");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: [unterminated\n---\n# App\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
}
#[test]
fn compatibility_text_should_keep_only_non_blank_strings_verbatim() {
assert_eq!(
compatibility_text(Some(yaml_serde::Value::String(" Needs git ".to_owned()))),
Some(" Needs git ".to_owned())
);
assert_eq!(
compatibility_text(Some(yaml_serde::Value::String(" ".to_owned()))),
None
);
assert_eq!(
compatibility_text(Some(
yaml_serde::from_str("[git]").expect("sequence should parse")
)),
None
);
assert_eq!(compatibility_text(None), None);
}
#[test]
fn string_metadata_should_keep_only_string_values() {
let entries: BTreeMap<String, yaml_serde::Value> = yaml_serde::from_str(
"dalo.requires-commands: git\nowner:\n team: docs\nattempts: 3\n",
)
.expect("metadata should parse");
assert_eq!(
string_metadata(entries),
BTreeMap::from([("dalo.requires-commands".to_owned(), "git".to_owned())])
);
}
#[test]
fn scan_source_should_carry_compatibility_and_string_metadata() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("page-scan");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: page-scan\ncompatibility: \"Needs agent-browser on PATH.\"\nmetadata:\n dalo.requires-commands: agent-browser\n---\n# Page scan\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(
inventory.skills[0].compatibility.as_deref(),
Some("Needs agent-browser on PATH.")
);
assert_eq!(
inventory.skills[0].metadata,
BTreeMap::from([(
"dalo.requires-commands".to_owned(),
"agent-browser".to_owned()
)])
);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_drop_unexpected_compatibility_and_metadata_shapes_silently() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let nested = temp_dir.path().join("nested");
let scalar = temp_dir.path().join("scalar");
let empty = temp_dir.path().join("empty");
let blank = temp_dir.path().join("blank");
for dir in [&nested, &scalar, &empty, &blank] {
fs::create_dir_all(dir).expect("skill dir should be created");
}
fs::write(
nested.join(SKILL_FILE),
"---\nname: nested\ncompatibility:\n - python\n - git\nmetadata:\n owner:\n team: docs\n dalo.requires-commands: git\n attempts: 3\n---\n# Nested\n",
)
.expect("skill file should be written");
fs::write(
scalar.join(SKILL_FILE),
"---\nname: scalar\nmetadata: not-a-mapping\n---\n# Scalar\n",
)
.expect("skill file should be written");
fs::write(
empty.join(SKILL_FILE),
"---\nname: empty\nmetadata:\n---\n# Empty\n",
)
.expect("skill file should be written");
fs::write(
blank.join(SKILL_FILE),
"---\nname: blank\ncompatibility: \"\"\n---\n# Blank\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
let skill = |slot: &str| {
inventory
.skills
.iter()
.find(|skill| skill.slot_name == slot)
.unwrap_or_else(|| panic!("skill `{slot}` should still be discovered"))
};
assert_eq!(inventory.skills.len(), 4);
assert_eq!(skill("nested").compatibility, None);
assert_eq!(
skill("nested").metadata,
BTreeMap::from([("dalo.requires-commands".to_owned(), "git".to_owned())])
);
assert!(skill("scalar").metadata.is_empty());
assert!(skill("empty").metadata.is_empty());
assert_eq!(skill("blank").compatibility, None);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_tolerate_128_bit_integers_in_compatibility_and_metadata() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("wide");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: wide\ncompatibility: -99999999999999999999999\nmetadata:\n big: 99999999999999999999999\n dalo.requires-commands: git\n---\n# Wide\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].compatibility, None);
assert_eq!(
inventory.skills[0].metadata,
BTreeMap::from([("dalo.requires-commands".to_owned(), "git".to_owned())])
);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_not_fail_on_duplicate_metadata_keys() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("duplicated");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: duplicated\nmetadata:\n &key dalo.requires-commands: git\n *key: gh\n---\n# Duplicated\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_reject_oversized_frontmatter_before_parsing() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("oversized");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: oversized\ndescription: {}\n---\n# Oversized\n",
"x".repeat(MAX_FRONTMATTER_BYTES)
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(inventory.warnings[0].message.contains("byte safety limit"));
}
#[test]
fn raw_frontmatter_should_apply_the_parser_guards_with_the_same_messages() {
let flow = format!(
"---\nvalue: {}{}\n---\n# Flow\n",
"[".repeat(MAX_FRONTMATTER_FLOW_DEPTH + 1),
"]".repeat(MAX_FRONTMATTER_FLOW_DEPTH + 1)
);
let aliases = format!(
"---\nvalue: [&tag bounded, {}*tag]\n---\n# Aliases\n",
"*tag, ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES)
);
let oversized = format!(
"---\nname: oversized\ndescription: {}\n---\n",
"x".repeat(MAX_FRONTMATTER_BYTES)
);
for (markdown, metadata_truncated, expected) in [
(
"---\nname: review\n",
false,
"frontmatter start marker has no matching end marker",
),
("---\nname: review\n", true, "byte safety limit"),
(oversized.as_str(), false, "byte safety limit"),
(flow.as_str(), false, "flow nesting exceeds"),
(aliases.as_str(), false, "anchor/alias references exceed"),
(
"---\n- review\n---\n",
false,
"frontmatter is not a mapping",
),
] {
match raw_frontmatter(markdown, metadata_truncated) {
RawFrontmatter::Malformed(message) => {
assert!(
message.contains(expected),
"{message} should contain {expected}"
);
}
RawFrontmatter::Missing | RawFrontmatter::Mapping { .. } => {
panic!("{markdown:?} should be malformed")
}
}
}
assert!(matches!(
raw_frontmatter("# No frontmatter\n", false),
RawFrontmatter::Missing
));
}
#[test]
fn raw_frontmatter_should_keep_unknown_fields_and_count_body_lines_after_crlf_fences() {
let RawFrontmatter::Mapping {
fields,
body_line_count,
} = raw_frontmatter(
"---\r\nname: review\r\nfoo: bar\r\n---\r\none\r\ntwo\r\n",
false,
)
else {
panic!("frontmatter should parse as a mapping");
};
assert_eq!(fields.len(), 2);
assert_eq!(body_line_count, 2);
}
#[test]
fn scan_source_should_not_read_skill_body_beyond_the_metadata_window() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("bounded");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let mut markdown = b"---\nname: bounded\n---\n# Bounded\n".to_vec();
markdown.extend("€".repeat(MAX_SKILL_METADATA_BYTES).as_bytes());
markdown.push(0xff);
fs::write(skill_dir.join(SKILL_FILE), markdown).expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].slot_name, "bounded");
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_reject_deep_flow_nesting_before_parsing() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("nested");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let nesting = MAX_FRONTMATTER_FLOW_DEPTH + 1;
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: nested\ntags: {}value{}\n---\n# Nested\n",
"[".repeat(nesting),
"]".repeat(nesting)
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(
inventory.warnings[0]
.message
.contains("flow nesting exceeds")
);
}
#[test]
fn scan_source_should_allow_bounded_frontmatter_anchors_and_aliases() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("alias-safe");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: &skill alias-safe\ndescription: *skill\nrequires: &dependencies [setup]\nowners: *dependencies\ntags: *dependencies\n---\n# Alias Safe\n",
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
let skill = &inventory.skills[0];
assert_eq!(skill.slot_name, "alias-safe");
assert_eq!(skill.description.as_deref(), Some("alias-safe"));
assert_eq!(skill.requires, ["setup".to_owned()]);
assert_eq!(skill.owners, ["setup".to_owned()]);
assert_eq!(skill.tags, ["setup".to_owned()]);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_reject_excessive_frontmatter_anchor_alias_references_before_parsing() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("alias-bomb");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let aliases = "*tag, ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: alias-bomb\ndescription: &tag bounded\ntags: [{aliases}*tag]\n---\n# Alias Bomb\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(
inventory.warnings[0]
.message
.contains("anchor/alias references exceed")
);
}
#[test]
fn scan_source_should_reject_excessive_references_after_plain_scalar_quote_text() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("plain-quote-alias-bomb");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let aliases = "*tag, ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: plain-quote-alias-bomb\ndescription: plain\"text\ntags: [&tag bounded, {aliases}*tag]\n---\n# Plain Quote Alias Bomb\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(
inventory.warnings[0]
.message
.contains("anchor/alias references exceed")
);
}
#[test]
fn frontmatter_anchor_alias_guard_should_count_nested_sequence_mapping_keys() {
let anchors = (0..8)
.map(|index| format!(" &anchor-{index} anchor-key-{index}: anchor-value-{index}\n"))
.collect::<String>();
let aliases = (0..9)
.map(|index| format!(" *anchor-{index}: alias-value-{index}\n"))
.collect::<String>();
let frontmatter =
format!("name: nested\nmetadata:\n - description: plain\n{anchors}{aliases}");
assert!(frontmatter_anchor_or_alias_references_exceed(
&frontmatter,
MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES
));
}
#[test]
fn scan_source_should_reject_excessive_references_after_same_indent_plain_scalar_quote_text() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("same-indent-plain-quote-alias-bomb");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let aliases = "*tag, ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES - 1);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: same-indent-plain-quote-alias-bomb\ndescription:\n plain\n \"quote\ntags: [&tag bounded, {aliases}*tag]\n---\n# Same Indent Plain Quote Alias Bomb\n"
),
)
.expect("alias-bomb skill should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(
inventory.warnings[0]
.message
.contains("anchor/alias references exceed")
);
}
#[test]
fn scan_source_should_ignore_anchor_alias_text_in_same_indent_plain_scalar_continuations() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("same-indent-plain-scalar-literals");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let literal_references = " &anchor *alias\n".repeat(9);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: same-indent-plain-scalar-literals\ndescription:\n plain\n{literal_references}---\n# Same Indent Plain Scalar Literals\n"
),
)
.expect("literal-text skill should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert!(inventory.skills[0].description.is_some());
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_ignore_anchor_alias_text_in_quoted_unknown_sibling_key() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("quoted-unknown-sibling");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let indicators = "&anchor *alias ".repeat(9);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: quoted-unknown-sibling\ndescription: plain\n\"{indicators}\": ignored\n---\n# Quoted Unknown Sibling\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].description.as_deref(), Some("plain"));
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_reject_excessive_references_after_tag_property_anchor() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("tag-property-alias-bomb");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let aliases = "*tag, ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES - 1);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: tag-property-alias-bomb\ndescription: !!str &tag bounded\ntags: [{aliases}*tag]\n---\n# Tag Property Alias Bomb\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(
inventory.warnings[0]
.message
.contains("anchor/alias references exceed")
);
}
#[test]
fn scan_source_should_allow_references_at_limit_in_anchor_decorated_multiline_collection() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("bounded-multiline-aliases");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let aliases = " - *tag\n".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES - 2);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: bounded-multiline-aliases\ntags: &root\n - &tag bounded\n{aliases}---\n# Bounded Multiline Aliases\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(
inventory.skills[0].tags,
vec!["bounded"; MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES - 1]
);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_reject_references_over_limit_in_anchor_decorated_multiline_collection() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("excessive-multiline-aliases");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let aliases = " - *tag\n".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES - 1);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: excessive-multiline-aliases\ntags: &root\n - &tag bounded\n{aliases}---\n# Excessive Multiline Aliases\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::MalformedFrontmatter
);
assert!(
inventory.warnings[0]
.message
.contains("anchor/alias references exceed")
);
}
#[test]
fn scan_source_should_allow_anchor_alias_text_in_indented_quoted_scalar() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("indented-quoted-scalar");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let indicators = "&anchor *alias ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES + 1);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: indented-quoted-scalar\ndescription:\n \"{indicators}\"\n---\n# Indented Quoted Scalar\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_ignore_anchor_and_alias_text_in_sequence_block_scalars() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("sequence-block-scalar");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let indicators = "&anchor *alias ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES + 1);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: sequence-block-scalar\ntags:\n - |-\n {indicators}\n---\n# Sequence Block Scalar\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].tags.len(), 1);
assert!(inventory.skills[0].tags[0].contains("&anchor *alias"));
assert!(inventory.warnings.is_empty());
}
#[test]
fn frontmatter_anchor_alias_guard_should_ignore_quotes_comments_and_block_scalars() {
let indicators = "&anchor *alias ".repeat(MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES + 1);
let frontmatter = format!(
"description: \"{indicators}\"\nowner: '{indicators}'\n# {indicators}\nnotes: |-\n {indicators}\n"
);
assert!(!frontmatter_anchor_or_alias_references_exceed(
&frontmatter,
MAX_FRONTMATTER_ANCHOR_OR_ALIAS_REFERENCES
));
}
#[test]
fn frontmatter_flow_depth_guard_should_ignore_quotes_and_comments() {
let delimiters = "[".repeat(MAX_FRONTMATTER_FLOW_DEPTH + 1);
let frontmatter =
format!("description: \"{delimiters}\"\nowner: '{delimiters}'\n# {delimiters}\n");
assert!(!frontmatter_flow_depth_exceeds(
&frontmatter,
MAX_FRONTMATTER_FLOW_DEPTH
));
}
#[test]
fn scan_source_should_allow_flow_delimiters_in_block_scalar_text() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("block-scalar");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
let delimiters = "[".repeat(MAX_FRONTMATTER_FLOW_DEPTH + 1);
fs::write(
skill_dir.join(SKILL_FILE),
format!(
"---\nname: block-scalar\ndescription: |-\n {delimiters}\n---\n# Block Scalar\n"
),
)
.expect("skill file should be written");
let inventory = scan_source("team", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(
inventory.skills[0].description.as_deref(),
Some(delimiters.as_str())
);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_require_frontmatter_end_fence_line() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("workflow");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: workflow\nrequires:\n - setup\nnotes: |\n --- divider\n ---- not a fence\nowners:\n - team\n---\n# Workflow\n",
)
.expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
let skill = &inventory.skills[0];
assert_eq!(skill.requires, ["setup".to_owned()]);
assert_eq!(skill.owners, ["team".to_owned()]);
assert!(inventory.warnings.is_empty());
}
#[test]
fn scan_source_should_fallback_to_folder_name_when_frontmatter_name_is_invalid() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("release-notes.local");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: release notes\n---\n# Release Notes\n",
)
.expect("skill file should be written");
let inventory = scan_source("local", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills[0].slot_name, "release-notes.local");
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::InvalidSlotName
);
}
#[test]
fn scan_source_should_deduplicate_duplicate_slot_names_before_resolution() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
for dir_name in ["second", "first"] {
let skill_dir = temp_dir.path().join(dir_name);
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: shared\n---\n# Shared\n",
)
.expect("skill file should be written");
}
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
let duplicate_warnings = inventory
.warnings
.iter()
.filter(|warning| warning.code == InventoryWarningCode::DuplicateSlotName)
.count();
assert_eq!(duplicate_warnings, 2);
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].path, temp_dir.path().join("first"));
let source = crate::source::SourceConfig {
id: "company".to_owned(),
kind: crate::source::SourceKind::Local,
path: temp_dir.path().to_path_buf(),
subpath: None,
priority: 0,
namespace: None,
enabled: true,
trusted: false,
url: None,
branch: None,
update_policy: None,
selection: Vec::new(),
declared_by: None,
declared_ref: None,
};
let resolution = crate::resolver::resolve(&crate::resolver::ResolutionInput {
sources: std::slice::from_ref(&source),
inventories: vec![inventory],
approvals: Vec::new(),
});
assert_eq!(resolution.active_skills.len(), 1);
assert!(resolution.unlinked_skills.is_empty());
assert!(resolution.diagnostics.iter().all(|diagnostic| {
diagnostic.code != crate::resolver::ResolutionDiagnosticCode::Shadowed
}));
}
#[test]
fn scan_source_should_treat_supporting_files_as_part_of_one_skill() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("review");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(skill_dir.join(SKILL_FILE), "# Review\n").expect("skill file should be written");
fs::write(skill_dir.join("guide.md"), "supporting").expect("guide should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills.len(), 1);
assert_eq!(inventory.skills[0].source_ref, "company:review");
}
#[test]
fn is_valid_slot_name_should_reject_dot_segments() {
assert!(!is_valid_slot_name("."));
assert!(!is_valid_slot_name(".."));
assert!(!is_valid_slot_name(".config"));
assert!(!is_valid_slot_name("review."));
}
#[test]
fn is_valid_slot_name_should_reject_non_portable_names() {
let invalid_names = [
"Review",
"review copy",
"review\ncopy",
"caf\u{e9}",
"cafe\u{301}",
"con",
"con.skill",
"aux",
"nul",
"com1",
"lpt9",
];
for name in invalid_names {
assert!(!is_valid_slot_name(name), "{name} should be invalid");
}
}
#[test]
fn is_valid_slot_name_should_reject_values_that_exceed_the_portable_bound() {
assert!(!is_valid_slot_name(&"a".repeat(MAX_SLOT_NAME_LENGTH + 1)));
}
#[test]
fn is_valid_slot_name_should_accept_cross_platform_tokens() {
for name in ["review", "release-notes.local", "copy_editing", "skill.123"] {
assert!(is_valid_slot_name(name), "{name} should be valid");
}
}
proptest! {
#[test]
fn valid_slot_names_should_stay_portable(value in "\\PC{0,64}") {
if is_valid_slot_name(&value) {
prop_assert!(!value.is_empty());
prop_assert_ne!(value.as_str(), ".");
prop_assert_ne!(value.as_str(), "..");
prop_assert!(!value.starts_with('.'));
prop_assert!(!value.ends_with('.'));
prop_assert!(!is_windows_reserved_basename(&value));
let portable = value.chars().all(|character| {
character.is_ascii_lowercase()
|| character.is_ascii_digit()
|| character == '-'
|| character == '_'
|| character == '.'
});
prop_assert!(portable);
}
}
}
#[test]
fn scan_source_should_skip_skill_when_folder_name_is_invalid() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("bad name");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(skill_dir.join(SKILL_FILE), "# No Frontmatter Name\n")
.expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::InvalidSlotName
);
}
#[test]
fn scan_source_should_name_skill_file_when_metadata_is_unreadable() {
use std::os::unix::fs::PermissionsExt;
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("skills/review");
fs::create_dir_all(&skill_dir).expect("skill directory should be created");
let skill_file = skill_dir.join(SKILL_FILE);
fs::write(&skill_file, "# Review\n").expect("skill should be written");
let mode = fs::metadata(&skill_file).unwrap().permissions().mode() & 0o777;
fs::set_permissions(&skill_file, fs::Permissions::from_mode(0o000)).unwrap();
let inventory = scan_source("team", temp_dir.path()).expect("scan should complete");
fs::set_permissions(&skill_file, fs::Permissions::from_mode(mode)).unwrap();
assert!(inventory.warnings.iter().any(|warning| {
warning.code == InventoryWarningCode::UnreadablePath && warning.path == skill_file
}));
}
#[test]
fn scan_source_should_skip_uppercase_folder_name() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("Review");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(skill_dir.join(SKILL_FILE), "# Review\n").expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::InvalidSlotName
);
assert!(inventory.warnings[0].message.contains("Review"));
}
#[test]
fn scan_source_should_skip_unicode_folder_name() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("caf\u{e9}");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(skill_dir.join(SKILL_FILE), "# Cafe\n").expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert!(inventory.skills.is_empty());
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::InvalidSlotName
);
}
#[test]
fn select_slot_name_should_return_none_when_folder_name_is_invalid() {
let frontmatter = SkillFrontmatter::default();
let mut warnings = Vec::new();
let slot_name = select_slot_name(
&frontmatter,
"bad name",
Path::new("/tmp/bad name/SKILL.md"),
&mut warnings,
);
assert!(slot_name.is_none());
assert_eq!(warnings[0].code, InventoryWarningCode::InvalidSlotName);
}
#[test]
fn scan_source_should_fallback_when_frontmatter_name_has_case_collision_risk() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("review");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\nname: Review\n---\n# Review\n",
)
.expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills[0].slot_name, "review");
assert_eq!(
inventory.warnings[0].code,
InventoryWarningCode::InvalidSlotName
);
}
#[test]
fn scan_source_should_reject_traversal_frontmatter_name() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("legit");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(skill_dir.join(SKILL_FILE), "---\nname: ..\n---\n# Legit\n")
.expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills[0].slot_name, "legit");
}
#[test]
fn scan_source_should_parse_crlf_frontmatter() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let skill_dir = temp_dir.path().join("copy-editing");
fs::create_dir_all(&skill_dir).expect("skill dir should be created");
fs::write(
skill_dir.join(SKILL_FILE),
"---\r\nname: copy-editing\r\nid: team.copy-editing\r\n---\r\n# Copy Editing\r\n",
)
.expect("skill file should be written");
let inventory = scan_source("company", temp_dir.path()).expect("scan should succeed");
assert_eq!(inventory.skills[0].id.as_deref(), Some("team.copy-editing"));
}
fn skill_with_requires_commands(value: Option<&str>) -> SkillRecord {
let mut metadata = BTreeMap::new();
if let Some(value) = value {
metadata.insert(REQUIRES_COMMANDS_METADATA_KEY.to_owned(), value.to_owned());
}
SkillRecord {
source_id: "team".to_owned(),
source_ref: "team:page-scan".to_owned(),
id: None,
slot_name: "page-scan".to_owned(),
path: PathBuf::from("skills/page-scan"),
skill_file: PathBuf::from("skills/page-scan/SKILL.md"),
delivery: SkillDelivery::Direct,
description: None,
requires: Vec::new(),
owners: Vec::new(),
tags: Vec::new(),
compatibility: None,
metadata,
binaries: Vec::new(),
}
}
#[test]
fn required_commands_should_keep_valid_names_in_declaration_order() {
let skill = skill_with_requires_commands(Some("agent-browser jq\tnode3.1_x+y"));
assert_eq!(
skill.required_commands(),
vec!["agent-browser", "jq", "node3.1_x+y"]
);
}
#[test]
fn required_commands_should_remove_duplicates_keeping_first_occurrence() {
let skill = skill_with_requires_commands(Some("jq rg jq agent-browser rg"));
assert_eq!(skill.required_commands(), vec!["jq", "rg", "agent-browser"]);
}
#[test]
fn required_commands_should_skip_paths_flags_and_dot_prefixed_tokens() {
let skill = skill_with_requires_commands(Some("../evil /usr/bin/jq -x .hidden fake-tool"));
assert_eq!(skill.required_commands(), vec!["fake-tool"]);
}
#[test]
fn required_commands_should_bound_name_length_at_128_characters() {
let longest = "b".repeat(128);
let too_long = "c".repeat(129);
let skill = skill_with_requires_commands(Some(&format!("{too_long} {longest}")));
assert_eq!(skill.required_commands(), vec![longest]);
}
#[test]
fn required_commands_should_be_empty_without_the_metadata_key() {
assert!(
skill_with_requires_commands(None)
.required_commands()
.is_empty()
);
}
}