use serde::{Deserialize, Serialize};
use super::{detect_ecosystem, parse_ecosystem, REGISTRY_BASE_URL};
use crate::http::{encode_uri_component, HttpClient};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(
tag = "type",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
pub enum RegistrySource {
Npm {
package: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
path: Option<String>,
},
Github {
repo: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
branch: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
tag: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
path: Option<String>,
},
Web {
urls: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
max_depth: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
allowed_path_prefix: Option<String>,
},
LlmsTxt {
url: String,
},
}
impl RegistrySource {
pub fn type_name(&self) -> &'static str {
match self {
RegistrySource::Npm { .. } => "npm",
RegistrySource::Github { .. } => "github",
RegistrySource::Web { .. } => "web",
RegistrySource::LlmsTxt { .. } => "llms-txt",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct RegistryApiPackage {
pub name: String,
#[serde(default)]
pub description: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RegistryApiResponse {
pub name: String,
pub description: String,
pub repo: String,
#[serde(default)]
pub homepage: Option<String>,
#[serde(default)]
pub license: Option<String>,
#[serde(default)]
pub tags: Option<Vec<String>>,
pub resolved_name: String,
pub package: RegistryApiPackage,
pub sources: Vec<RegistrySource>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RegistryResolution {
pub ecosystem: String,
pub name: String,
pub version: String,
pub source: RegistrySource,
}
#[derive(Deserialize)]
struct StatusBody {
#[serde(rename = "statusMessage")]
status_message: Option<String>,
}
pub fn fetch_registry_entry(
client: &dyn HttpClient,
first: &str,
second: &str,
) -> Option<RegistryApiResponse> {
let url = format!(
"{REGISTRY_BASE_URL}/api/registry/{}/{}",
encode_uri_component(first),
encode_uri_component(second),
);
let response = match client.get(&url) {
Ok(r) => r,
Err(_) => return None,
};
if response.status == 404 {
return None;
}
if !response.ok() {
let message = serde_json::from_str::<StatusBody>(&response.body)
.ok()
.and_then(|b| b.status_message)
.unwrap_or_else(|| format!("HTTP {}", response.status));
eprintln!(
"Registry lookup for {first}/{second} returned {}: {message}",
response.status
);
return None;
}
serde_json::from_str::<RegistryApiResponse>(&response.body).ok()
}
pub fn resolve_from_registry(
client: &dyn HttpClient,
input: &str,
project_dir: &std::path::Path,
) -> Option<RegistryResolution> {
let (explicit_ecosystem, spec) = parse_ecosystem(input);
let (name, version) = match spec.rfind('@') {
Some(idx) if idx > 0 => (&spec[..idx], &spec[idx + 1..]),
_ => (spec, "latest"),
};
let ecosystem = explicit_ecosystem
.map(str::to_string)
.unwrap_or_else(|| detect_ecosystem(project_dir).to_string());
let entry = fetch_registry_entry(client, &ecosystem, name)?;
let Some(primary) = entry.sources.first() else {
eprintln!("Registry entry for {name} has no sources");
return None;
};
Some(RegistryResolution {
ecosystem,
name: entry.resolved_name.clone(),
version: version.to_string(),
source: primary.clone(),
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::http::mock::MockClient;
const BASE: &str = "https://ask-registry.pages.dev";
fn entry_json() -> &'static str {
r#"{
"name": "next.js",
"description": "The React Framework",
"repo": "vercel/next.js",
"resolvedName": "next",
"package": { "name": "next" },
"sources": [
{ "type": "npm", "package": "next", "path": "dist/docs" },
{ "type": "github", "repo": "vercel/next.js", "path": "docs" }
]
}"#
}
#[test]
fn source_discriminated_union_roundtrips() {
let src: RegistrySource =
serde_json::from_str(r#"{"type":"llms-txt","url":"https://x/llms.txt"}"#).unwrap();
assert_eq!(
src,
RegistrySource::LlmsTxt {
url: "https://x/llms.txt".into()
}
);
assert_eq!(src.type_name(), "llms-txt");
let web: RegistrySource = serde_json::from_str(
r#"{"type":"web","urls":["https://x"],"maxDepth":2,"allowedPathPrefix":"/docs"}"#,
)
.unwrap();
assert!(matches!(
web,
RegistrySource::Web {
max_depth: Some(2),
..
}
));
}
#[test]
fn fetch_entry_ok() {
let client =
MockClient::new().with(&format!("{BASE}/api/registry/npm/next"), 200, entry_json());
let entry = fetch_registry_entry(&client, "npm", "next").unwrap();
assert_eq!(entry.resolved_name, "next");
assert_eq!(entry.sources.len(), 2);
assert_eq!(entry.sources[0].type_name(), "npm");
}
#[test]
fn fetch_entry_scoped_name_is_url_encoded() {
let url = format!("{BASE}/api/registry/npm/%40mastra%2Fclient-js");
let client = MockClient::new().with(&url, 200, entry_json());
assert!(fetch_registry_entry(&client, "npm", "@mastra/client-js").is_some());
}
#[test]
fn fetch_entry_404_and_transport_error_are_none() {
let client = MockClient::new().with(&format!("{BASE}/api/registry/npm/missing"), 404, "");
assert!(fetch_registry_entry(&client, "npm", "missing").is_none());
assert!(fetch_registry_entry(&client, "npm", "never").is_none());
}
#[test]
fn fetch_entry_non_ok_warns_and_returns_none() {
let client = MockClient::new().with(
&format!("{BASE}/api/registry/mastra-ai/mastra"),
409,
r#"{"statusMessage":"Monorepo entry — use npm:@mastra/core"}"#,
);
assert!(fetch_registry_entry(&client, "mastra-ai", "mastra").is_none());
}
#[test]
fn resolve_splits_version_and_returns_primary_source() {
let client =
MockClient::new().with(&format!("{BASE}/api/registry/npm/next"), 200, entry_json());
let dir = tempfile::tempdir().unwrap();
let res = resolve_from_registry(&client, "npm:next@14.2.3", dir.path()).unwrap();
assert_eq!(res.ecosystem, "npm");
assert_eq!(res.name, "next");
assert_eq!(res.version, "14.2.3");
assert_eq!(res.source.type_name(), "npm");
}
#[test]
fn resolve_detects_ecosystem_from_project_when_prefix_absent() {
let client =
MockClient::new().with(&format!("{BASE}/api/registry/npm/next"), 200, entry_json());
let dir = tempfile::tempdir().unwrap();
std::fs::write(dir.path().join("package.json"), "{}").unwrap();
let res = resolve_from_registry(&client, "next", dir.path()).unwrap();
assert_eq!(res.ecosystem, "npm");
assert_eq!(res.version, "latest");
}
}