use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::Command;
use astrs_coordinator::CoordinatorError;
use astrs_coordinator::hub_index::{self, IndexPackage};
use serde::Deserialize;
use crate::error::CliError;
pub const CONFIG_FILE_NAME: &str = "config.toml";
const INDEX_README: &str = "\
# AstRS package index
A minimal, git-hosted index for `hub:` manifest sources (blueprint §22).
## Layout
packages/<name>.json
Each file is one package:
```json
{
\"name\": \"yolo-detector\",
\"description\": \"A YOLO-family object detector node.\",
\"versions\": [
{ \"version\": \"v0.3.0\", \"git\": \"https://example.invalid/yolo\", \"rev\": \"a1b2c3d\" },
{ \"version\": \"v0.3.1\", \"git\": \"https://example.invalid/yolo\", \"rev\": \"d4e5f6a\", \"subdir\": \"nodes/yolo\" }
]
}
```
`versions` is append-only, oldest first: publishing a new version means
appending an entry, never rewriting one already there. `hub: <name>` with
no `@rev` resolves to the last (newest) entry; `hub: <name>@<version>`
must match a `version` string exactly.
`rev` is the exact git commit/tag/branch that `version` resolves to —
always required, so a published version stays reproducible even if a
branch it once pointed at moves on. `subdir` is optional: the package's
own directory within `git`, for a repository that hosts more than one
package. Leave it out when the whole repository *is* the package.
## Publishing
Add or edit a `packages/<name>.json` file, commit, and push. Anyone
running `astrs hub update` against this repository's URL picks up the
change on their next update.
";
#[must_use]
pub fn default_config_path() -> PathBuf {
if let Some(xdg) = non_empty_var("XDG_CONFIG_HOME") {
return PathBuf::from(xdg).join("astrs").join(CONFIG_FILE_NAME);
}
if let Some(home) = non_empty_var("HOME") {
return PathBuf::from(home)
.join(".config")
.join("astrs")
.join(CONFIG_FILE_NAME);
}
std::env::temp_dir().join(format!("astrs-{CONFIG_FILE_NAME}"))
}
fn non_empty_var(name: &str) -> Option<String> {
std::env::var(name).ok().filter(|value| !value.is_empty())
}
#[derive(Debug, Default, Deserialize)]
struct ConfigFile {
#[serde(default)]
hub: Option<HubConfigSection>,
}
#[derive(Debug, Default, Deserialize)]
struct HubConfigSection {
#[serde(default)]
index: Option<String>,
}
fn read_config_index(path: &Path) -> Result<Option<String>, CliError> {
let text = match std::fs::read_to_string(path) {
Ok(text) => text,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(source) => return Err(CliError::io(path, source)),
};
let config: ConfigFile = toml::from_str(&text).map_err(|source| {
CoordinatorError::invalid(format!("`{}` is not valid TOML: {source}", path.display()))
})?;
Ok(config.hub.and_then(|hub| hub.index))
}
pub fn resolve_index_url(explicit: Option<&str>, config_path: &Path) -> Result<String, CliError> {
if let Some(explicit) = explicit {
return Ok(explicit.to_owned());
}
if let Ok(env) = std::env::var(hub_index::ENV_HUB_INDEX)
&& !env.trim().is_empty()
{
return Ok(env);
}
if let Some(from_config) = read_config_index(config_path)? {
return Ok(from_config);
}
Ok(hub_index::DEFAULT_INDEX_URL.to_owned())
}
fn run_git(working_dir: Option<&Path>, args: &[&str]) -> Result<String, CliError> {
let mut command = Command::new("git");
command.args(args);
if let Some(dir) = working_dir {
command.current_dir(dir);
}
let output = command.output().map_err(|source| {
CoordinatorError::invalid(format!(
"could not run the system `git` binary (is it installed and on `PATH`?): {source}"
))
})?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
return Err(CoordinatorError::invalid(format!(
"`git {}` failed: {}",
args.join(" "),
stderr.trim()
))
.into());
}
Ok(String::from_utf8_lossy(&output.stdout).into_owned())
}
fn count_packages(cache_dir: &Path) -> usize {
std::fs::read_dir(cache_dir.join("packages"))
.map(|entries| {
entries
.filter_map(Result::ok)
.filter(|entry| {
entry.path().extension().and_then(std::ffi::OsStr::to_str) == Some("json")
})
.count()
})
.unwrap_or(0)
}
#[derive(Debug, Clone, Default)]
pub struct UpdateArgs {
pub index: Option<String>,
pub cache_dir: Option<PathBuf>,
pub config_path: Option<PathBuf>,
pub json: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UpdateReport {
pub index_url: String,
pub cache_dir: PathBuf,
pub cloned: bool,
pub package_count: usize,
}
pub fn update(out: &mut dyn Write, args: &UpdateArgs) -> Result<UpdateReport, CliError> {
let cache_dir = args
.cache_dir
.clone()
.unwrap_or_else(hub_index::cache_dir_from_env);
let config_path = args.config_path.clone().unwrap_or_else(default_config_path);
let index_url = resolve_index_url(args.index.as_deref(), &config_path)?;
let cloned = !cache_dir.join(".git").is_dir();
if cloned {
if let Some(parent) = cache_dir.parent()
&& !parent.as_os_str().is_empty()
{
std::fs::create_dir_all(parent).map_err(|source| CliError::io(parent, source))?;
}
let cache_dir_text = cache_dir.display().to_string();
run_git(None, &["clone", &index_url, &cache_dir_text])?;
} else {
run_git(Some(&cache_dir), &["pull", "--ff-only"])?;
}
let report = UpdateReport {
index_url,
package_count: count_packages(&cache_dir),
cache_dir,
cloned,
};
print_update_report(out, args.json, &report);
Ok(report)
}
fn print_update_report(out: &mut dyn Write, json: bool, report: &UpdateReport) {
if json {
emit_json(
out,
&serde_json::json!({
"index_url": report.index_url,
"cache_dir": report.cache_dir.display().to_string(),
"cloned": report.cloned,
"package_count": report.package_count,
}),
);
return;
}
let verb = if report.cloned { "cloned" } else { "updated" };
let _ = writeln!(
out,
"{verb} {} into {} ({} package{})",
report.index_url,
report.cache_dir.display(),
report.package_count,
if report.package_count == 1 { "" } else { "s" }
);
let _ = out.flush();
}
#[derive(Debug, Clone)]
pub struct SearchArgs {
pub term: String,
pub cache_dir: Option<PathBuf>,
pub json: bool,
}
pub fn search(out: &mut dyn Write, args: &SearchArgs) -> Result<Vec<IndexPackage>, CliError> {
let cache_dir = args
.cache_dir
.clone()
.unwrap_or_else(hub_index::cache_dir_from_env);
let hits = hub_index::search(&cache_dir, &args.term).map_err(CoordinatorError::from)?;
print_search_results(out, args.json, &args.term, &hits);
Ok(hits)
}
fn print_search_results(out: &mut dyn Write, json: bool, term: &str, hits: &[IndexPackage]) {
if json {
emit_json(
out,
&serde_json::json!({
"term": term,
"results": hits.iter().map(package_summary_json).collect::<Vec<_>>(),
}),
);
return;
}
if hits.is_empty() {
let _ = writeln!(out, "no packages match `{term}`");
} else {
for package in hits {
let latest = package
.versions
.last()
.map_or("(no versions)", |v| v.version.as_str());
let _ = writeln!(
out,
"{:<24} {latest:<10} {}",
package.name, package.description
);
}
}
let _ = out.flush();
}
fn package_summary_json(package: &IndexPackage) -> serde_json::Value {
serde_json::json!({
"name": package.name,
"description": package.description,
"latest_version": package.versions.last().map(|v| v.version.clone()),
"version_count": package.versions.len(),
})
}
#[derive(Debug, Clone)]
pub struct InfoArgs {
pub name: String,
pub cache_dir: Option<PathBuf>,
pub json: bool,
}
pub fn info(out: &mut dyn Write, args: &InfoArgs) -> Result<IndexPackage, CliError> {
let cache_dir = args
.cache_dir
.clone()
.unwrap_or_else(hub_index::cache_dir_from_env);
let package =
hub_index::read_package(&cache_dir, &args.name).map_err(CoordinatorError::from)?;
print_package_info(out, args.json, &package);
Ok(package)
}
fn print_package_info(out: &mut dyn Write, json: bool, package: &IndexPackage) {
if json {
emit_json(
out,
&serde_json::json!({
"name": package.name,
"description": package.description,
"versions": package.versions.iter().map(|v| serde_json::json!({
"version": v.version,
"git": v.git,
"rev": v.rev,
"subdir": v.subdir,
})).collect::<Vec<_>>(),
}),
);
return;
}
let _ = writeln!(out, "{}", package.name);
let _ = writeln!(out, " {}", package.description);
let _ = writeln!(out, " versions (oldest first):");
for version in &package.versions {
match &version.subdir {
Some(subdir) => {
let _ = writeln!(
out,
" {:<10} {} @ {} (subdir: {subdir})",
version.version, version.git, version.rev
);
}
None => {
let _ = writeln!(
out,
" {:<10} {} @ {}",
version.version, version.git, version.rev
);
}
}
}
let _ = out.flush();
}
#[derive(Debug, Clone)]
pub struct InitArgs {
pub dir: PathBuf,
pub force: bool,
pub json: bool,
}
pub fn init(out: &mut dyn Write, args: &InitArgs) -> Result<PathBuf, CliError> {
if args.dir.exists() && !args.force {
let non_empty = std::fs::read_dir(&args.dir)
.map(|mut entries| entries.next().is_some())
.unwrap_or(false);
if non_empty {
return Err(CliError::TargetExists {
path: args.dir.display().to_string(),
});
}
}
let packages_dir = args.dir.join("packages");
std::fs::create_dir_all(&packages_dir).map_err(|source| CliError::io(&packages_dir, source))?;
std::fs::write(packages_dir.join(".gitkeep"), b"")
.map_err(|source| CliError::io(&packages_dir, source))?;
let readme_path = args.dir.join("README.md");
std::fs::write(&readme_path, INDEX_README)
.map_err(|source| CliError::io(&readme_path, source))?;
run_git(Some(&args.dir), &["init", "--quiet"])?;
if args.json {
emit_json(
out,
&serde_json::json!({ "initialized": args.dir.display().to_string() }),
);
} else {
let _ = writeln!(out, "initialized a package index at {}", args.dir.display());
let _ = writeln!(
out,
" add packages under packages/<name>.json, then `git add -A && git commit`"
);
let _ = out.flush();
}
Ok(args.dir.clone())
}
fn emit_json(out: &mut dyn Write, value: &serde_json::Value) {
let _ = writeln!(
out,
"{}",
serde_json::to_string_pretty(value).unwrap_or_else(|_| "{}".to_owned())
);
let _ = out.flush();
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
fn scratch(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("astrs-cli-hub-{}-{name}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
fn run(dir: &Path, args: &[&str]) {
let status = Command::new("git")
.args(args)
.current_dir(dir)
.status()
.unwrap();
assert!(status.success(), "git {args:?} failed in {}", dir.display());
}
fn build_index_repo(dir: &Path) {
std::fs::create_dir_all(dir.join("packages")).unwrap();
std::fs::write(
dir.join("packages").join("yolo-detector.json"),
serde_json::to_string(&IndexPackage {
name: "yolo-detector".to_owned(),
description: "A YOLO-family object detector node.".to_owned(),
versions: vec![
hub_index::IndexVersion {
version: "v0.3.0".to_owned(),
git: "https://example.invalid/yolo".to_owned(),
rev: "a1b2c3d".to_owned(),
subdir: None,
},
hub_index::IndexVersion {
version: "v0.3.1".to_owned(),
git: "https://example.invalid/yolo".to_owned(),
rev: "d4e5f6a".to_owned(),
subdir: None,
},
],
})
.unwrap(),
)
.unwrap();
run(dir, &["init", "--quiet", "--initial-branch=main"]);
run(dir, &["config", "user.email", "test@astrs.invalid"]);
run(dir, &["config", "user.name", "astrs-cli tests"]);
run(dir, &["add", "-A"]);
run(dir, &["commit", "--quiet", "-m", "seed index"]);
}
fn file_url(dir: &Path) -> String {
format!("file://{}", dir.display())
}
#[test]
fn update_clones_a_fresh_index_and_then_pulls_it() {
let origin = scratch("update-origin");
build_index_repo(&origin);
let cache = scratch("update-cache");
std::fs::remove_dir_all(&cache).unwrap();
let mut out = Vec::new();
let report = update(
&mut out,
&UpdateArgs {
index: Some(file_url(&origin)),
cache_dir: Some(cache.clone()),
config_path: Some(scratch("update-config-unused").join("config.toml")),
json: false,
},
)
.unwrap();
assert!(report.cloned);
assert_eq!(report.package_count, 1);
assert!(cache.join("packages").join("yolo-detector.json").is_file());
assert!(
String::from_utf8(out).unwrap().contains("cloned"),
"human report should say it cloned"
);
std::fs::write(
origin.join("packages").join("lidar-slam.json"),
serde_json::to_string(&IndexPackage {
name: "lidar-slam".to_owned(),
description: "SLAM from a spinning lidar.".to_owned(),
versions: vec![hub_index::IndexVersion {
version: "v1".to_owned(),
git: "https://example.invalid/slam".to_owned(),
rev: "abc".to_owned(),
subdir: None,
}],
})
.unwrap(),
)
.unwrap();
run(&origin, &["add", "-A"]);
run(&origin, &["commit", "--quiet", "-m", "add lidar-slam"]);
let mut out = Vec::new();
let report = update(
&mut out,
&UpdateArgs {
index: Some(file_url(&origin)),
cache_dir: Some(cache.clone()),
config_path: None,
json: false,
},
)
.unwrap();
assert!(!report.cloned, "the second update pulls, it does not clone");
assert_eq!(report.package_count, 2);
assert!(cache.join("packages").join("lidar-slam.json").is_file());
}
#[test]
fn update_against_a_nonexistent_repository_is_a_clear_error() {
let cache = scratch("update-missing-remote");
std::fs::remove_dir_all(&cache).unwrap();
let nowhere = scratch("update-missing-remote-origin");
std::fs::remove_dir_all(&nowhere).unwrap();
let error = update(
&mut Vec::new(),
&UpdateArgs {
index: Some(file_url(&nowhere)),
cache_dir: Some(cache),
config_path: Some(scratch("update-missing-remote-config").join("config.toml")),
json: false,
},
)
.unwrap_err();
assert!(matches!(error, CliError::Coordinator(_)), "{error}");
assert!(!error.to_string().is_empty());
}
#[test]
fn search_and_info_read_the_freshly_updated_cache() {
let origin = scratch("search-info-origin");
build_index_repo(&origin);
let cache = scratch("search-info-cache");
std::fs::remove_dir_all(&cache).unwrap();
update(
&mut Vec::new(),
&UpdateArgs {
index: Some(file_url(&origin)),
cache_dir: Some(cache.clone()),
config_path: Some(scratch("search-info-config").join("config.toml")),
json: false,
},
)
.unwrap();
let mut out = Vec::new();
let hits = search(
&mut out,
&SearchArgs {
term: "yolo".to_owned(),
cache_dir: Some(cache.clone()),
json: false,
},
)
.unwrap();
assert_eq!(hits.len(), 1);
assert_eq!(hits[0].name, "yolo-detector");
assert!(String::from_utf8(out).unwrap().contains("yolo-detector"));
let mut out = Vec::new();
let package = info(
&mut out,
&InfoArgs {
name: "yolo-detector".to_owned(),
cache_dir: Some(cache),
json: false,
},
)
.unwrap();
assert_eq!(package.versions.len(), 2);
let printed = String::from_utf8(out).unwrap();
assert!(printed.contains("v0.3.0"));
assert!(printed.contains("v0.3.1"));
}
#[test]
fn search_before_any_update_names_the_update_command() {
let cache = scratch("search-no-update");
std::fs::remove_dir_all(&cache).unwrap();
let error = search(
&mut Vec::new(),
&SearchArgs {
term: String::new(),
cache_dir: Some(cache),
json: false,
},
)
.unwrap_err();
assert!(error.to_string().contains("astrs hub update"), "{error}");
}
#[test]
fn info_on_an_unknown_package_names_search_and_update() {
let origin = scratch("info-unknown-origin");
build_index_repo(&origin);
let cache = scratch("info-unknown-cache");
std::fs::remove_dir_all(&cache).unwrap();
update(
&mut Vec::new(),
&UpdateArgs {
index: Some(file_url(&origin)),
cache_dir: Some(cache.clone()),
config_path: Some(scratch("info-unknown-config").join("config.toml")),
json: false,
},
)
.unwrap();
let error = info(
&mut Vec::new(),
&InfoArgs {
name: "does-not-exist".to_owned(),
cache_dir: Some(cache),
json: false,
},
)
.unwrap_err();
let message = error.to_string();
assert!(message.contains("astrs hub search"), "{message}");
assert!(message.contains("astrs hub update"), "{message}");
}
#[test]
fn init_scaffolds_a_layout_update_can_then_clone_from() {
let repo_dir = scratch("init-then-clone-repo");
std::fs::remove_dir_all(&repo_dir).unwrap();
init(
&mut Vec::new(),
&InitArgs {
dir: repo_dir.clone(),
force: false,
json: false,
},
)
.unwrap();
assert!(repo_dir.join("packages").is_dir());
assert!(repo_dir.join("README.md").is_file());
assert!(repo_dir.join(".git").is_dir());
std::fs::write(
repo_dir.join("packages").join("yolo-detector.json"),
serde_json::to_string(&IndexPackage {
name: "yolo-detector".to_owned(),
description: "detector".to_owned(),
versions: vec![hub_index::IndexVersion {
version: "v1".to_owned(),
git: "https://example.invalid/yolo".to_owned(),
rev: "cafe".to_owned(),
subdir: None,
}],
})
.unwrap(),
)
.unwrap();
run(&repo_dir, &["config", "user.email", "test@astrs.invalid"]);
run(&repo_dir, &["config", "user.name", "astrs-cli tests"]);
run(&repo_dir, &["add", "-A"]);
run(&repo_dir, &["commit", "--quiet", "-m", "add yolo-detector"]);
let cache = scratch("init-then-clone-cache");
std::fs::remove_dir_all(&cache).unwrap();
let report = update(
&mut Vec::new(),
&UpdateArgs {
index: Some(file_url(&repo_dir)),
cache_dir: Some(cache),
config_path: Some(scratch("init-then-clone-config").join("config.toml")),
json: false,
},
)
.unwrap();
assert_eq!(report.package_count, 1);
}
#[test]
fn init_refuses_a_nonempty_directory_without_force() {
let dir = scratch("init-nonempty");
std::fs::write(dir.join("keep.txt"), b"pre-existing").unwrap();
let error = init(
&mut Vec::new(),
&InitArgs {
dir: dir.clone(),
force: false,
json: false,
},
)
.unwrap_err();
assert!(matches!(error, CliError::TargetExists { .. }), "{error}");
init(
&mut Vec::new(),
&InitArgs {
dir,
force: true,
json: false,
},
)
.unwrap();
}
#[test]
fn resolve_index_url_prefers_explicit_then_env_then_config_then_default() {
let config_dir = scratch("resolve-index-url");
let config_path = config_dir.join("config.toml");
assert_eq!(
resolve_index_url(None, &config_path).unwrap(),
hub_index::DEFAULT_INDEX_URL
);
std::fs::write(
&config_path,
"[hub]\nindex = \"https://example.invalid/from-config\"\n",
)
.unwrap();
assert_eq!(
resolve_index_url(None, &config_path).unwrap(),
"https://example.invalid/from-config"
);
assert_eq!(
resolve_index_url(Some("https://example.invalid/explicit"), &config_path).unwrap(),
"https://example.invalid/explicit"
);
}
#[test]
fn a_malformed_config_file_is_a_clear_error() {
let config_dir = scratch("resolve-index-url-malformed");
let config_path = config_dir.join("config.toml");
std::fs::write(&config_path, "not = [valid toml").unwrap();
let error = resolve_index_url(None, &config_path).unwrap_err();
assert!(matches!(error, CliError::Coordinator(_)), "{error}");
}
#[test]
fn json_output_carries_the_same_fields_as_the_report() {
let origin = scratch("json-output-origin");
build_index_repo(&origin);
let cache = scratch("json-output-cache");
std::fs::remove_dir_all(&cache).unwrap();
let mut out = Vec::new();
let report = update(
&mut out,
&UpdateArgs {
index: Some(file_url(&origin)),
cache_dir: Some(cache),
config_path: Some(scratch("json-output-config").join("config.toml")),
json: true,
},
)
.unwrap();
let value: serde_json::Value = serde_json::from_slice(&out).unwrap();
assert_eq!(value["index_url"], report.index_url);
assert_eq!(value["package_count"], 1);
assert_eq!(value["cloned"], true);
}
}