use std::collections::BTreeMap;
use std::env;
use std::fs;
use std::path::{Path, PathBuf};
use serde::Serialize;
use crate::error::{DaloError, DaloResult};
use crate::store::{self, StateFile, StorePaths, TargetState};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum TargetSupport {
Supported,
Experimental,
}
impl TargetSupport {
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
Self::Supported => "supported",
Self::Experimental => "experimental",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TargetRegistryEntry {
pub id: &'static str,
pub name: &'static str,
pub default_path: Option<&'static str>,
pub support: TargetSupport,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct TargetDetection {
pub id: String,
pub name: String,
pub support: TargetSupport,
pub path: Option<PathBuf>,
pub exists: bool,
pub linked: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct TargetDetectReport {
pub targets: Vec<TargetDetection>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct InstructionFileDestination {
pub logical_targets: Vec<String>,
pub path: PathBuf,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum TargetLinkStatus {
Planned,
Linked,
Updated,
Existing,
}
impl TargetLinkStatus {
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
Self::Planned => "planned",
Self::Linked => "linked",
Self::Updated => "updated",
Self::Existing => "existing",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct TargetLinkReport {
pub target_id: String,
pub path: PathBuf,
pub canonical_path: PathBuf,
pub status: TargetLinkStatus,
pub created_dir: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum TargetUnlinkStatus {
Planned,
Unlinked,
Missing,
}
impl TargetUnlinkStatus {
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
Self::Planned => "planned",
Self::Unlinked => "unlinked",
Self::Missing => "missing",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct TargetUnlinkReport {
pub target_id: String,
pub status: TargetUnlinkStatus,
}
pub const LINK_HINT_TARGETS: &str = "codex|claude|cursor|openclaw|hermes|opencode|generic";
#[must_use]
pub fn registry() -> &'static [TargetRegistryEntry] {
&[
TargetRegistryEntry {
id: "codex",
name: "Codex",
default_path: Some("~/.agents/skills"),
support: TargetSupport::Supported,
},
TargetRegistryEntry {
id: "claude",
name: "Claude Code",
default_path: Some("~/.claude/skills"),
support: TargetSupport::Supported,
},
TargetRegistryEntry {
id: "cursor",
name: "Cursor",
default_path: Some("~/.cursor/skills"),
support: TargetSupport::Supported,
},
TargetRegistryEntry {
id: "openclaw",
name: "OpenClaw",
default_path: Some("~/.agents/skills"),
support: TargetSupport::Supported,
},
TargetRegistryEntry {
id: "hermes",
name: "Hermes",
default_path: Some("~/.hermes/skills"),
support: TargetSupport::Supported,
},
TargetRegistryEntry {
id: "opencode",
name: "OpenCode",
default_path: Some("~/.config/opencode/skills"),
support: TargetSupport::Supported,
},
TargetRegistryEntry {
id: "generic",
name: "Generic folder",
default_path: None,
support: TargetSupport::Supported,
},
]
}
pub fn resolve_instruction_files(
target_ids: &[String],
) -> DaloResult<Vec<InstructionFileDestination>> {
let default_config_dir = |name: &str| {
env::var_os("HOME")
.map(PathBuf::from)
.map(|home| home.join(name))
.ok_or_else(|| DaloError::StateError {
reason: "HOME is required to resolve native instruction files".to_owned(),
})
};
let mut destinations = BTreeMap::<PathBuf, Vec<String>>::new();
for target_id in target_ids {
registry_entry(target_id)?;
let path = match target_id.as_str() {
"codex" => match env::var_os("CODEX_HOME") {
Some(path) => PathBuf::from(path),
None => default_config_dir(".codex")?,
}
.join("AGENTS.md"),
"claude" => match env::var_os("CLAUDE_CONFIG_DIR") {
Some(path) => PathBuf::from(path),
None => default_config_dir(".claude")?,
}
.join("CLAUDE.md"),
_ => {
return Err(DaloError::InvalidArgument {
reason: format!(
"target `{target_id}` has no verified native instruction-file mapping; use an explicit file instead"
),
});
}
};
let path = store::comparable_path(&store::absolute_path(&path)?);
destinations
.entry(path)
.or_default()
.push(target_id.clone());
}
Ok(destinations
.into_iter()
.map(|(path, mut logical_targets)| {
logical_targets.sort();
logical_targets.dedup();
InstructionFileDestination {
logical_targets,
path,
}
})
.collect())
}
#[must_use = "the target detection report should be rendered or inspected"]
pub fn detect_targets(store_root: &Path) -> DaloResult<TargetDetectReport> {
let paths = StorePaths::new(store_root.to_path_buf());
let state = read_state_if_initialized(&paths)?;
let targets = registry()
.iter()
.map(|entry| detect_entry(entry, state.as_ref()))
.collect::<DaloResult<Vec<_>>>()?;
Ok(TargetDetectReport { targets })
}
pub fn link_target(
store_root: &Path,
target_id: &str,
path_override: Option<&Path>,
dry_run: bool,
) -> DaloResult<TargetLinkReport> {
let entry = registry_entry(target_id)?;
let path = target_path(entry, path_override)?;
let existed_before = fs::symlink_metadata(&path).is_ok();
let paths = StorePaths::new(store_root.to_path_buf());
let mut state = if dry_run {
None
} else {
Some(store::read_state(&paths)?)
};
let canonical_path = canonicalize_target_path(&path);
let status = if dry_run {
TargetLinkStatus::Planned
} else {
let state = state
.as_mut()
.expect("state is loaded before non-dry-run target link");
let status = upsert_target_state(state, entry.id, &path, &canonical_path)?;
let created_dirs = if existed_before {
if !fs::metadata(&path).is_ok_and(|metadata| metadata.is_dir()) {
return Err(std::io::Error::new(
std::io::ErrorKind::NotADirectory,
format!("target path `{}` is not a directory", path.display()),
)
.into());
}
Vec::new()
} else {
create_target_directories(&path)?
};
if let Err(error) = store::write_state(&paths, state) {
remove_created_target_directories(&created_dirs);
return Err(error);
}
status
};
Ok(TargetLinkReport {
target_id: entry.id.to_owned(),
path,
canonical_path,
status,
created_dir: !existed_before && !dry_run,
})
}
fn missing_target_directories(path: &Path) -> Vec<PathBuf> {
let mut missing = Vec::new();
let mut current = Some(path);
while let Some(candidate) = current.filter(|path| !path.as_os_str().is_empty()) {
if fs::symlink_metadata(candidate).is_ok() {
break;
}
missing.push(candidate.to_path_buf());
current = candidate.parent();
}
missing.reverse();
missing
}
fn create_target_directories(path: &Path) -> DaloResult<Vec<PathBuf>> {
let mut created = Vec::new();
for candidate in missing_target_directories(path) {
match fs::create_dir(&candidate) {
Ok(()) => created.push(candidate),
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
Err(error) => {
remove_created_target_directories(&created);
return Err(error.into());
}
}
}
if !fs::metadata(path).is_ok_and(|metadata| metadata.is_dir()) {
remove_created_target_directories(&created);
return Err(std::io::Error::new(
std::io::ErrorKind::NotADirectory,
format!("target path `{}` is not a directory", path.display()),
)
.into());
}
Ok(created)
}
fn remove_created_target_directories(created: &[PathBuf]) {
for path in created.iter().rev() {
if fs::remove_dir(path).is_err() {
break;
}
}
}
pub fn unlink_target(
store_root: &Path,
target_id: &str,
dry_run: bool,
) -> DaloResult<TargetUnlinkReport> {
registry_entry(target_id)?;
let paths = StorePaths::new(store_root.to_path_buf());
let mut state = store::read_state(&paths)?;
let original_len = state.targets.len();
let linked = state.targets.iter().any(|target| target.id == target_id);
let status = if dry_run {
if linked {
TargetUnlinkStatus::Planned
} else {
TargetUnlinkStatus::Missing
}
} else {
state.targets.retain(|target| target.id != target_id);
state.rebuild_materialization_dirs_for_removal()?;
store::write_state(&paths, &state)?;
if state.targets.len() == original_len {
TargetUnlinkStatus::Missing
} else {
TargetUnlinkStatus::Unlinked
}
};
Ok(TargetUnlinkReport {
target_id: target_id.to_owned(),
status,
})
}
fn detect_entry(
entry: &TargetRegistryEntry,
state: Option<&StateFile>,
) -> DaloResult<TargetDetection> {
let linked_target = state.and_then(|state| {
state
.targets
.iter()
.find(|target| target.id == entry.id && target.enabled)
});
let path = if let Some(target) = linked_target {
Some(target.path.clone())
} else {
entry
.default_path
.map(PathBuf::from)
.map(|path| store::expand_user_path(&path))
.transpose()?
};
let exists = path.as_ref().is_some_and(|path| path.exists());
let linked = linked_target.is_some();
Ok(TargetDetection {
id: entry.id.to_owned(),
name: entry.name.to_owned(),
support: entry.support,
path,
exists,
linked,
})
}
fn read_state_if_initialized(paths: &StorePaths) -> DaloResult<Option<StateFile>> {
if paths.state_file.exists() {
Ok(Some(store::read_state(paths)?))
} else {
Ok(None)
}
}
fn registry_entry(target_id: &str) -> DaloResult<&'static TargetRegistryEntry> {
registry()
.iter()
.find(|entry| entry.id == target_id)
.ok_or_else(|| {
DaloError::unknown_target(
target_id,
registry().iter().map(|entry| entry.id.to_owned()).collect(),
)
})
}
fn target_path(entry: &TargetRegistryEntry, path_override: Option<&Path>) -> DaloResult<PathBuf> {
if let Some(path) = path_override {
return store::expand_user_path(path);
}
let Some(default_path) = entry.default_path else {
return Err(DaloError::TargetPathRequired {
target: entry.id.to_owned(),
});
};
store::expand_user_path(Path::new(default_path))
}
fn canonicalize_target_path(path: &Path) -> PathBuf {
if let Ok(canonical) = path.canonicalize() {
return canonical;
}
match (path.parent(), path.file_name()) {
(Some(parent), Some(file_name)) => match parent.canonicalize() {
Ok(canonical_parent) => canonical_parent.join(file_name),
Err(_) => path.to_path_buf(),
},
_ => path.to_path_buf(),
}
}
fn upsert_target_state(
state: &mut StateFile,
target_id: &str,
path: &Path,
canonical_path: &Path,
) -> DaloResult<TargetLinkStatus> {
let existing = state
.targets
.iter_mut()
.find(|target| target.id == target_id);
let status = if let Some(target) = existing {
if target.path == path && target.canonical_path == canonical_path && target.enabled {
TargetLinkStatus::Existing
} else {
target.path = path.to_path_buf();
target.canonical_path = canonical_path.to_path_buf();
target.enabled = true;
TargetLinkStatus::Updated
}
} else {
state.targets.push(TargetState {
id: target_id.to_owned(),
path: path.to_path_buf(),
canonical_path: canonical_path.to_path_buf(),
enabled: true,
extra: Default::default(),
});
TargetLinkStatus::Linked
};
state.rebuild_materialization_dirs()?;
Ok(status)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn registry_should_include_v1_targets() {
let ids = registry().iter().map(|entry| entry.id).collect::<Vec<_>>();
assert_eq!(
ids,
[
"codex", "claude", "cursor", "openclaw", "hermes", "opencode", "generic",
]
);
}
#[test]
fn cursor_target_should_use_the_verified_user_skill_directory() {
let entry = registry_entry("cursor").expect("Cursor should be a built-in target");
assert_eq!(entry.name, "Cursor");
assert_eq!(entry.default_path, Some("~/.cursor/skills"));
assert_eq!(entry.support, TargetSupport::Supported);
}
#[test]
fn link_hint_should_name_every_builtin() {
let ids = registry().iter().map(|entry| entry.id).collect::<Vec<_>>();
assert_eq!(
LINK_HINT_TARGETS,
ids.join("|"),
"the target link hint fell behind the registry"
);
assert!(
crate::cli::AFTER_LONG_HELP
.contains(&format!("dalo target link <{LINK_HINT_TARGETS}> [path]")),
"the CLI long help fell behind the registry"
);
}
#[test]
fn registry_should_ship_only_verified_targets() {
for entry in registry() {
assert_eq!(
entry.support,
TargetSupport::Supported,
"target `{}` ships an unverified support level",
entry.id
);
}
}
#[test]
fn registry_should_give_every_agent_target_a_default_path() {
for entry in registry().iter().filter(|entry| entry.id != "generic") {
assert!(
entry.default_path.is_some(),
"target `{}` ships without a default skill path",
entry.id
);
}
}
#[test]
fn link_target_should_dedupe_shared_physical_directory() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
let shared_target = temp_dir.path().join("skills");
store::init_store(store_root.clone(), false).expect("init should succeed");
link_target(&store_root, "codex", Some(&shared_target), false)
.expect("codex link should succeed");
link_target(&store_root, "openclaw", Some(&shared_target), false)
.expect("openclaw link should succeed");
let state =
store::read_state(&StorePaths::new(store_root)).expect("state should be readable");
assert_eq!(state.targets.len(), 2);
assert_eq!(state.materialization_dirs.len(), 1);
assert_eq!(
state.materialization_dirs[0].logical_targets,
["codex".to_owned(), "openclaw".to_owned()]
);
}
#[test]
fn link_target_should_report_stable_canonical_path_between_dry_run_and_real_run() {
use std::os::unix::fs as unix_fs;
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
store::init_store(store_root.clone(), false).expect("init should succeed");
let real_parent = temp_dir.path().join("real");
std::fs::create_dir_all(&real_parent).expect("real parent should be created");
let linked_parent = temp_dir.path().join("linked");
unix_fs::symlink(&real_parent, &linked_parent).expect("symlink should be created");
let target = linked_parent.join("skills");
let planned = link_target(&store_root, "codex", Some(&target), true)
.expect("dry-run link should succeed");
let applied = link_target(&store_root, "codex", Some(&target), false)
.expect("real link should succeed");
assert_eq!(planned.canonical_path, applied.canonical_path);
}
#[test]
fn link_target_should_read_store_before_creating_target_dir() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("missing-store");
let target = temp_dir.path().join("skills");
let error = link_target(&store_root, "codex", Some(&target), false)
.expect_err("link should require an initialized store");
assert!(matches!(error, DaloError::StoreNotInitialized { .. }));
assert!(!target.exists());
}
#[test]
fn link_target_should_not_create_directory_when_metadata_merge_fails() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
let shared_target = temp_dir.path().join("shared-skills");
store::init_store(store_root.clone(), false).expect("init should succeed");
let paths = StorePaths::new(store_root.clone());
let state = conflicting_future_directory_state(temp_dir.path(), &shared_target);
store::write_state(&paths, &state).expect("conflicting future state should be written");
let error = link_target(&store_root, "codex", Some(&shared_target), false)
.expect_err("lossy metadata merge should block link");
assert!(matches!(error, DaloError::StateMetadataConflict { .. }));
assert!(!shared_target.exists());
assert_eq!(
store::read_state(&paths).expect("state should remain readable"),
state
);
}
#[test]
fn link_target_cleanup_should_remove_new_empty_ancestors_only() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let existing_parent = temp_dir.path().join("existing");
let target = existing_parent.join("new/deep/skills");
fs::create_dir_all(&existing_parent).expect("existing parent should be created");
let created = missing_target_directories(&target);
fs::create_dir_all(&target).expect("target hierarchy should be created");
remove_created_target_directories(&created);
assert!(existing_parent.is_dir());
assert!(!target.exists());
assert!(!existing_parent.join("new").exists());
}
#[test]
fn link_target_should_reject_a_broken_symlink_without_recording_state() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
let target = temp_dir.path().join("broken-skills");
store::init_store(store_root.clone(), false).expect("init should succeed");
std::os::unix::fs::symlink(temp_dir.path().join("missing"), &target)
.expect("broken target symlink should be created");
let error = link_target(&store_root, "codex", Some(&target), false)
.expect_err("broken target symlink should be rejected");
assert!(error.to_string().contains("not a directory"));
assert!(
store::read_state(&StorePaths::new(store_root))
.expect("state should remain readable")
.targets
.is_empty()
);
}
#[test]
fn unlink_target_should_drop_unrelated_conflicting_directory_metadata() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
let shared_target = temp_dir.path().join("shared-skills");
store::init_store(store_root.clone(), false).expect("init should succeed");
let paths = StorePaths::new(store_root.clone());
let state = conflicting_future_directory_state(temp_dir.path(), &shared_target);
store::write_state(&paths, &state).expect("conflicting future state should be written");
let report = unlink_target(&store_root, "codex", false)
.expect("unrelated metadata must not wedge target removal");
let updated = store::read_state(&paths).expect("updated state should be readable");
assert_eq!(report.status, TargetUnlinkStatus::Unlinked);
assert!(updated.targets.iter().all(|target| target.id != "codex"));
assert_eq!(updated.materialization_dirs.len(), 1);
assert_eq!(updated.materialization_dirs[0].path, shared_target);
assert_eq!(
updated.materialization_dirs[0].logical_targets,
["claude".to_owned(), "openclaw".to_owned()]
);
assert!(
!updated.materialization_dirs[0]
.extra
.contains_key("future_directory_field")
);
}
#[test]
fn unlink_target_dry_run_should_report_missing_for_unlinked_target() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
store::init_store(store_root.clone(), false).expect("init should succeed");
let report =
unlink_target(&store_root, "codex", true).expect("dry-run unlink should inspect state");
assert_eq!(report.status, TargetUnlinkStatus::Missing);
}
#[test]
fn link_generic_should_require_path() {
let temp_dir = tempfile::tempdir().expect("tempdir should be created");
let store_root = temp_dir.path().join("store");
store::init_store(store_root.clone(), false).expect("init should succeed");
let error = link_target(&store_root, "generic", None, false)
.expect_err("generic should require a path");
assert_eq!(
error.to_string(),
"target `generic` requires an explicit path"
);
}
fn conflicting_future_directory_state(root: &Path, shared_target: &Path) -> StateFile {
let mut state = StateFile::empty();
state.targets = vec![
TargetState {
id: "codex".to_owned(),
path: root.join("old-codex"),
canonical_path: root.join("old-codex"),
enabled: true,
extra: Default::default(),
},
TargetState {
id: "claude".to_owned(),
path: root.join("old-claude"),
canonical_path: root.join("old-claude"),
enabled: true,
extra: Default::default(),
},
TargetState {
id: "openclaw".to_owned(),
path: root.join("old-openclaw"),
canonical_path: root.join("old-openclaw"),
enabled: true,
extra: Default::default(),
},
];
state
.rebuild_materialization_dirs()
.expect("initial directories should rebuild");
for (target_id, value) in [("claude", "claude value"), ("openclaw", "openclaw value")] {
state
.materialization_dirs
.iter_mut()
.find(|directory| directory.logical_targets == [target_id.to_owned()])
.expect("target directory should exist")
.extra
.insert(
"future_directory_field".to_owned(),
toml::Value::String(value.to_owned()),
);
}
for target in state
.targets
.iter_mut()
.filter(|target| target.id != "codex")
{
target.path = shared_target.to_path_buf();
target.canonical_path = shared_target.to_path_buf();
}
state
}
}