use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::sync::OnceLock;
use include_dir::{include_dir, Dir};
use crate::model::{
Capability, CapabilityTerms, PackageManifest, Skill, SkillFrontmatter, TemplateMeta, Workflow,
};
use crate::search_index::{self, SearchIndex};
use crate::RegistryError;
static EMBEDDED_REGISTRY: OnceLock<Registry> = OnceLock::new();
static EMBEDDED: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/registry");
pub const REGISTRY_DIR_ENV: &str = "OFFLINE_REGISTRY_DIR";
#[derive(Debug, Clone)]
pub enum RegistrySource {
Embedded,
Dir(PathBuf),
}
#[derive(Clone)]
pub struct Registry {
pub(crate) packages: BTreeMap<String, PackageManifest>,
pub(crate) workflows: BTreeMap<String, Workflow>,
pub(crate) skills: BTreeMap<String, Skill>,
pub(crate) templates: BTreeMap<String, TemplateMeta>,
pub(crate) capability_terms: BTreeMap<String, CapabilityTerms>,
source: RegistrySource,
pub(crate) search_index: SearchIndex,
pub(crate) aggregated_capabilities: Vec<Capability>,
}
impl Registry {
pub fn load_default() -> Result<Self, RegistryError> {
match std::env::var_os(REGISTRY_DIR_ENV) {
Some(dir) => Self::load_from_dir(Path::new(&dir)),
None => {
if let Some(registry) = EMBEDDED_REGISTRY.get() {
return Ok(registry.clone());
}
let registry = Self::load_embedded()?;
let _ = EMBEDDED_REGISTRY.set(registry.clone());
Ok(registry)
}
}
}
pub fn load_embedded() -> Result<Self, RegistryError> {
let mut packages = BTreeMap::new();
let mut workflows = BTreeMap::new();
let mut skills = BTreeMap::new();
let mut templates = BTreeMap::new();
let mut capability_terms = BTreeMap::new();
ingest_metadata_embedded(&EMBEDDED, &mut |rel, data| {
ingest_metadata_bytes(
rel,
data,
&mut packages,
&mut workflows,
&mut skills,
&mut templates,
&mut capability_terms,
)
})?;
let mut registry = Self {
packages,
workflows,
skills,
templates,
capability_terms,
source: RegistrySource::Embedded,
search_index: SearchIndex::default(),
aggregated_capabilities: Vec::new(),
};
registry.validate()?;
registry.finalize_indexes();
Ok(registry)
}
pub fn load_from_dir(root: &Path) -> Result<Self, RegistryError> {
if !root.is_dir() {
return Err(RegistryError::SourceNotFound(root.display().to_string()));
}
let mut packages = BTreeMap::new();
let mut workflows = BTreeMap::new();
let mut skills = BTreeMap::new();
let mut templates = BTreeMap::new();
let mut capability_terms = BTreeMap::new();
for rel in metadata_paths_under(root)? {
let abs = root.join(&rel);
let data =
std::fs::read(&abs).map_err(|e| RegistryError::Io(abs.display().to_string(), e))?;
ingest_metadata_bytes(
&rel.to_string_lossy().replace('\\', "/"),
&data,
&mut packages,
&mut workflows,
&mut skills,
&mut templates,
&mut capability_terms,
)?;
}
let mut registry = Self {
packages,
workflows,
skills,
templates,
capability_terms,
source: RegistrySource::Dir(root.to_path_buf()),
search_index: SearchIndex::default(),
aggregated_capabilities: Vec::new(),
};
registry.validate()?;
registry.finalize_indexes();
Ok(registry)
}
fn finalize_indexes(&mut self) {
self.aggregated_capabilities = search_index::build_capabilities(self);
self.search_index = SearchIndex::build(self, &self.aggregated_capabilities);
}
fn validate(&self) -> Result<(), RegistryError> {
for wf in self.workflows.values() {
for pkgs in wf.packages.values() {
for p in pkgs {
if !self.packages.contains_key(p) {
return Err(RegistryError::Validation(format!(
"workflow `{}` references unknown package `{p}`",
wf.name
)));
}
}
}
for skill in &wf.skills {
if !self.skills.contains_key(skill) {
return Err(RegistryError::Validation(format!(
"workflow `{}` references unknown skill `{skill}`",
wf.name
)));
}
}
for tpl in wf.templates.values() {
if !self.templates.contains_key(tpl) {
return Err(RegistryError::Validation(format!(
"workflow `{}` references unknown template `{tpl}`",
wf.name
)));
}
}
}
for pkg in self.packages.values() {
if !KNOWN_PACKAGE_REGISTRIES.contains(&pkg.registry.as_str()) {
return Err(RegistryError::Validation(format!(
"package `{}` ships on unknown registry `{}` (expected one of: {})",
pkg.name,
pkg.registry,
KNOWN_PACKAGE_REGISTRIES.join(", ")
)));
}
match &pkg.install {
None if matches!(
pkg.registry.as_str(),
"swiftpm" | "maven" | "github-release" | "source" | "rubygems"
) =>
{
return Err(RegistryError::Validation(format!(
"package `{}` on `{}` needs an `install` instruction",
pkg.name, pkg.registry
)));
}
Some(install) if !install.contains(&pkg.version) => {
return Err(RegistryError::Validation(format!(
"package `{}` install instruction does not name version {}",
pkg.name, pkg.version
)));
}
_ => {}
}
for platform in &pkg.platforms {
if !KNOWN_PLATFORMS.contains(&platform.as_str()) {
return Err(RegistryError::Validation(format!(
"package `{}` lists unknown platform `{platform}`",
pkg.name
)));
}
}
for req in &pkg.requires {
if !self.packages.contains_key(req) {
return Err(RegistryError::Validation(format!(
"package `{}` requires unknown package `{req}`",
pkg.name
)));
}
}
for skill in &pkg.skills {
if !self.skills.contains_key(skill) {
return Err(RegistryError::Validation(format!(
"package `{}` references unknown skill `{skill}`",
pkg.name
)));
}
}
}
let known: std::collections::BTreeSet<&str> = self
.packages
.values()
.flat_map(|p| p.capabilities.iter())
.chain(self.workflows.values().flat_map(|w| w.capabilities.iter()))
.map(String::as_str)
.collect();
for (name, terms) in &self.capability_terms {
if !known.contains(name.as_str()) {
return Err(RegistryError::Validation(format!(
"capabilities.json lists `{name}`, which no package or workflow provides"
)));
}
for skill in &terms.skills {
if !self.skills.contains_key(skill) {
return Err(RegistryError::Validation(format!(
"capabilities.json maps `{name}` to unknown skill `{skill}`"
)));
}
}
}
Ok(())
}
pub fn source(&self) -> &RegistrySource {
&self.source
}
pub fn packages(&self) -> impl Iterator<Item = &PackageManifest> {
self.packages.values()
}
pub fn package(&self, name: &str) -> Option<&PackageManifest> {
self.packages.get(name)
}
pub fn workflows(&self) -> impl Iterator<Item = &Workflow> {
self.workflows.values()
}
pub fn workflow(&self, name: &str) -> Option<&Workflow> {
self.workflows.get(name)
}
pub fn skills(&self) -> impl Iterator<Item = &Skill> {
self.skills.values()
}
pub fn skill(&self, name: &str) -> Option<&Skill> {
self.skills.get(name)
}
pub fn templates(&self) -> impl Iterator<Item = &TemplateMeta> {
self.templates.values()
}
pub fn template(&self, name: &str) -> Option<&TemplateMeta> {
self.templates.get(name)
}
pub fn template_files(&self, name: &str) -> Result<Vec<(PathBuf, Vec<u8>)>, RegistryError> {
if !self.templates.contains_key(name) {
return Err(RegistryError::NotFound(format!("template `{name}`")));
}
let prefix = format!("templates/{name}/files");
match &self.source {
RegistrySource::Embedded => {
let dir = EMBEDDED.get_dir(&prefix).ok_or_else(|| {
RegistryError::NotFound(format!("template files for `{name}`"))
})?;
let mut out = Vec::new();
collect_embedded(dir, &mut out);
let out = out
.into_iter()
.map(|(p, d)| {
let rel = p
.strip_prefix(&prefix)
.expect("embedded template paths start with prefix")
.to_path_buf();
(rel, d)
})
.collect();
Ok(out)
}
RegistrySource::Dir(root) => {
let base = root.join(&prefix);
if !base.is_dir() {
return Err(RegistryError::NotFound(format!(
"template files for `{name}` at {}",
base.display()
)));
}
let mut out = Vec::new();
for entry in walkdir::WalkDir::new(&base)
.into_iter()
.filter_map(Result::ok)
.filter(|e| e.file_type().is_file())
{
let rel = entry
.path()
.strip_prefix(&base)
.expect("walkdir yields paths under base")
.to_path_buf();
let data = std::fs::read(entry.path())
.map_err(|e| RegistryError::Io(entry.path().display().to_string(), e))?;
out.push((rel, data));
}
Ok(out)
}
}
}
}
pub(crate) fn man_key(package_name: &str) -> String {
package_name
.rsplit('/')
.next()
.unwrap_or(package_name)
.to_string()
}
const KNOWN_PACKAGE_REGISTRIES: &[&str] = &[
"npm",
"crates",
"pypi",
"swiftpm",
"maven",
"github-release",
"source",
"rubygems",
];
const KNOWN_PLATFORMS: &[&str] = &[
"react-native",
"nextjs",
"react-vite",
"web",
"rust",
"python",
"ios-native",
"android-native",
"embedded",
"flutter",
"java",
"c",
"ruby",
"csharp",
];
const CAPABILITIES_FILE: &str = "capabilities.json";
fn is_metadata_path(rel: &str) -> bool {
let rel = rel.replace('\\', "/");
if rel == CAPABILITIES_FILE {
return true;
}
if let Some(rest) = rel.strip_prefix("packages/") {
return rest.ends_with(".json") && !rest.contains('/');
}
if let Some(rest) = rel.strip_prefix("workflows/") {
return rest.ends_with(".json") && !rest.contains('/');
}
if let Some(rest) = rel.strip_prefix("skills/") {
return rest.ends_with(".md") && !rest.contains('/');
}
if let Some(rest) = rel.strip_prefix("templates/") {
let parts: Vec<&str> = rest.split('/').collect();
return parts.len() == 2 && parts[1] == "template.json";
}
false
}
fn metadata_paths_under(root: &Path) -> Result<Vec<PathBuf>, RegistryError> {
let mut out = Vec::new();
if root.join(CAPABILITIES_FILE).is_file() {
out.push(PathBuf::from(CAPABILITIES_FILE));
}
for (subdir, suffix) in [
("packages", ".json"),
("workflows", ".json"),
("skills", ".md"),
] {
let dir = root.join(subdir);
if !dir.is_dir() {
continue;
}
for entry in
std::fs::read_dir(&dir).map_err(|e| RegistryError::Io(dir.display().to_string(), e))?
{
let entry = entry.map_err(|e| RegistryError::Io(dir.display().to_string(), e))?;
let path = entry.path();
if !path.is_file() {
continue;
}
let name = entry.file_name();
let name = name.to_string_lossy();
if name.ends_with(suffix) {
out.push(PathBuf::from(subdir).join(name.as_ref()));
}
}
}
let templates_dir = root.join("templates");
if templates_dir.is_dir() {
for entry in std::fs::read_dir(&templates_dir)
.map_err(|e| RegistryError::Io(templates_dir.display().to_string(), e))?
{
let entry =
entry.map_err(|e| RegistryError::Io(templates_dir.display().to_string(), e))?;
if !entry.path().is_dir() {
continue;
}
let name = entry.file_name();
let meta = entry.path().join("template.json");
if meta.is_file() {
out.push(PathBuf::from("templates").join(name).join("template.json"));
}
}
}
Ok(out)
}
type MetadataVisitor<'a> = dyn FnMut(&str, &[u8]) -> Result<(), RegistryError> + 'a;
fn ingest_metadata_embedded(
dir: &Dir<'_>,
visit: &mut MetadataVisitor<'_>,
) -> Result<(), RegistryError> {
for file in dir.files() {
let rel_str = file.path().to_string_lossy().replace('\\', "/");
if is_metadata_path(&rel_str) {
visit(&rel_str, file.contents())?;
}
}
for sub in dir.dirs() {
ingest_metadata_embedded(sub, visit)?;
}
Ok(())
}
fn ingest_metadata_bytes(
rel_str: &str,
data: &[u8],
packages: &mut BTreeMap<String, PackageManifest>,
workflows: &mut BTreeMap<String, Workflow>,
skills: &mut BTreeMap<String, Skill>,
templates: &mut BTreeMap<String, TemplateMeta>,
capability_terms: &mut BTreeMap<String, CapabilityTerms>,
) -> Result<(), RegistryError> {
if rel_str == CAPABILITIES_FILE {
*capability_terms = serde_json::from_slice(data)
.map_err(|e| RegistryError::Parse(rel_str.to_string(), e.to_string()))?;
} else if let Some(name) = rel_str
.strip_prefix("packages/")
.and_then(|f| f.strip_suffix(".json"))
{
let manifest: PackageManifest = serde_json::from_slice(data)
.map_err(|e| RegistryError::Parse(rel_str.to_string(), e.to_string()))?;
if man_key(&manifest.name) != name {
return Err(RegistryError::Validation(format!(
"package file `{rel_str}` declares name `{}`; expected file name `{}.json`",
manifest.name,
man_key(&manifest.name)
)));
}
packages.insert(manifest.name.clone(), manifest);
} else if let Some(name) = rel_str
.strip_prefix("workflows/")
.and_then(|f| f.strip_suffix(".json"))
{
let wf: Workflow = serde_json::from_slice(data)
.map_err(|e| RegistryError::Parse(rel_str.to_string(), e.to_string()))?;
if wf.name != name {
return Err(RegistryError::Validation(format!(
"workflow file `{rel_str}` declares name `{}`",
wf.name
)));
}
workflows.insert(wf.name.clone(), wf);
} else if let Some(name) = rel_str
.strip_prefix("skills/")
.and_then(|f| f.strip_suffix(".md"))
{
let text = std::str::from_utf8(data)
.map_err(|e| RegistryError::Parse(rel_str.to_string(), e.to_string()))?;
let skill = parse_skill(text).map_err(|e| RegistryError::Parse(rel_str.to_string(), e))?;
if skill.name != name {
return Err(RegistryError::Validation(format!(
"skill file `{rel_str}` declares name `{}`",
skill.name
)));
}
skills.insert(skill.name.clone(), skill);
} else if rel_str.starts_with("templates/") && rel_str.ends_with("/template.json") {
let meta: TemplateMeta = serde_json::from_slice(data)
.map_err(|e| RegistryError::Parse(rel_str.to_string(), e.to_string()))?;
templates.insert(meta.name.clone(), meta);
}
Ok(())
}
fn collect_embedded(dir: &Dir<'_>, out: &mut Vec<(PathBuf, Vec<u8>)>) {
for file in dir.files() {
out.push((file.path().to_path_buf(), file.contents().to_vec()));
}
for sub in dir.dirs() {
collect_embedded(sub, out);
}
}
fn parse_skill(text: &str) -> Result<Skill, String> {
let rest = text
.strip_prefix("---")
.ok_or("skill must start with `---` frontmatter")?;
let end = rest
.find("\n---")
.ok_or("unterminated frontmatter (missing closing `---`)")?;
let frontmatter = &rest[..end];
let body = rest[end + 4..].trim_start_matches('\n').to_string();
let fm: SkillFrontmatter =
serde_saphyr::from_str(frontmatter).map_err(|e| format!("invalid frontmatter: {e}"))?;
Ok(Skill {
name: fm.name,
title: fm.title,
description: fm.description,
use_when: fm.use_when,
packages: fm.packages,
platforms: fm.platforms,
body,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn is_metadata_path_selects_manifests_only() {
assert!(is_metadata_path("packages/mesh-sdk.json"));
assert!(is_metadata_path("workflows/offline-social-network.json"));
assert!(is_metadata_path("skills/mesh-chat.md"));
assert!(is_metadata_path(
"templates/react-native-mesh/template.json"
));
assert!(!is_metadata_path(
"templates/react-native-mesh/files/App.tsx"
));
assert!(!is_metadata_path(
"templates/react-native-mesh/files/package.json"
));
assert!(is_metadata_path("capabilities.json"));
assert!(!is_metadata_path("README.md"));
assert!(!is_metadata_path("packages/nested/extra.json"));
}
}