Files
dbx/crates/dbx-cli/src/agent_skill.rs
T

525 lines
20 KiB
Rust

use std::{
collections::BTreeMap,
fs,
io::Write,
path::{Component, Path, PathBuf},
};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use crate::{json_string, CliError, OutputFormat};
const SKILL_NAME: &str = "dbx";
const SKILL_VERSION: &str = "1.1.0";
const STATE_FILE_NAME: &str = ".dbx-managed.json";
const STATE_SCHEMA_VERSION: u8 = 1;
struct EmbeddedFile {
relative_path: &'static str,
contents: &'static str,
}
const EMBEDDED_FILES: &[EmbeddedFile] = &[
EmbeddedFile { relative_path: "SKILL.md", contents: include_str!("../../../skills/dbx/SKILL.md") },
EmbeddedFile {
relative_path: "references/commands.md",
contents: include_str!("../../../skills/dbx/references/commands.md"),
},
EmbeddedFile {
relative_path: "references/safety.md",
contents: include_str!("../../../skills/dbx/references/safety.md"),
},
EmbeddedFile {
relative_path: "references/workflows.md",
contents: include_str!("../../../skills/dbx/references/workflows.md"),
},
];
#[derive(Debug, Clone, PartialEq, Eq)]
enum InstallationStatus {
NotInstalled,
UpToDate,
UpdateAvailable,
Unmanaged,
Modified,
}
impl InstallationStatus {
fn as_str(&self) -> &'static str {
match self {
Self::NotInstalled => "not_installed",
Self::UpToDate => "up_to_date",
Self::UpdateAvailable => "update_available",
Self::Unmanaged => "unmanaged",
Self::Modified => "modified",
}
}
}
#[derive(Debug)]
struct Inspection {
status: InstallationStatus,
installed_version: Option<String>,
managed: bool,
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
struct ManagedState {
schema_version: u8,
skill_name: String,
skill_version: String,
files: BTreeMap<String, String>,
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct AgentSkillReport {
action: String,
status: String,
skill_name: String,
bundled_version: String,
#[serde(skip_serializing_if = "Option::is_none")]
installed_version: Option<String>,
managed: bool,
path: String,
}
pub fn run(args: &[String], format: OutputFormat, skills_dir: Option<&Path>, force: bool) -> Result<String, CliError> {
if format == OutputFormat::Csv {
return Err(CliError::new("INVALID_OPTION", "CSV format is not supported for dbx agent commands."));
}
if args.len() != 2 {
return Err(CliError::new("INVALID_ARGUMENT", "Usage: dbx agent <setup|status> [--json]"));
}
let root = resolve_skills_dir(skills_dir)?;
let target = root.join(SKILL_NAME);
match args[1].as_str() {
"setup" => setup(&target, force, format),
"status" => {
if force {
return Err(CliError::new("INVALID_OPTION", "--force is only supported by dbx agent setup."));
}
let inspection = inspect(&target)?;
render_report(report("status", &target, inspection), format)
}
command => Err(CliError::new(
"INVALID_ARGUMENT",
format!("Unknown agent command: {command}. Use dbx agent setup or dbx agent status."),
)),
}
}
fn setup(target: &Path, force: bool, format: OutputFormat) -> Result<String, CliError> {
reject_symlink(target)?;
let inspection = inspect(target)?;
let action = match inspection.status {
InstallationStatus::NotInstalled => "installed",
InstallationStatus::UpToDate => {
write_state(target)?;
"unchanged"
}
InstallationStatus::UpdateAvailable => "updated",
InstallationStatus::Unmanaged | InstallationStatus::Modified if !force => {
return Err(CliError::new(
"SKILL_MODIFIED",
format!(
"The DBX Agent Skill at {} is unmanaged or has local changes. Re-run with --force to replace DBX-managed files.",
target.display()
),
));
}
InstallationStatus::Unmanaged | InstallationStatus::Modified => "replaced",
};
if action != "unchanged" {
write_embedded_files(target)?;
write_state(target)?;
}
let inspection = inspect(target)?;
render_report(report(action, target, inspection), format)
}
fn resolve_skills_dir(override_dir: Option<&Path>) -> Result<PathBuf, CliError> {
if let Some(path) = override_dir {
return Ok(path.to_path_buf());
}
dirs::home_dir()
.map(|home| home.join(".agents").join("skills"))
.ok_or_else(|| CliError::new("HOME_NOT_FOUND", "Unable to determine the user home directory."))
}
fn inspect(target: &Path) -> Result<Inspection, CliError> {
reject_symlink(target)?;
let skill_path = target.join("SKILL.md");
let state = read_state(target);
if !skill_path.exists() {
let has_other_embedded_files = EMBEDDED_FILES
.iter()
.filter(|embedded| embedded.relative_path != "SKILL.md")
.any(|embedded| target.join(embedded.relative_path).exists());
return Ok(match state {
Some(state) => Inspection {
status: InstallationStatus::Modified,
installed_version: Some(state.skill_version),
managed: true,
},
None if has_other_embedded_files => {
Inspection { status: InstallationStatus::Unmanaged, installed_version: None, managed: false }
}
None => Inspection { status: InstallationStatus::NotInstalled, installed_version: None, managed: false },
});
}
reject_symlink(&skill_path)?;
let skill_contents = read_file(&skill_path)?;
let installed_version =
state.as_ref().map(|state| state.skill_version.clone()).or_else(|| frontmatter_version(&skill_contents));
if embedded_files_match(target)? {
return Ok(Inspection {
status: InstallationStatus::UpToDate,
installed_version: Some(SKILL_VERSION.to_string()),
managed: state.is_some(),
});
}
match state {
Some(state) if managed_files_unchanged(target, &state)? => {
Ok(Inspection { status: InstallationStatus::UpdateAvailable, installed_version, managed: true })
}
Some(_) => Ok(Inspection { status: InstallationStatus::Modified, installed_version, managed: true }),
None => Ok(Inspection { status: InstallationStatus::Unmanaged, installed_version, managed: false }),
}
}
fn embedded_files_match(target: &Path) -> Result<bool, CliError> {
for embedded in EMBEDDED_FILES {
let path = safe_join(target, embedded.relative_path)?;
if !path.exists() {
return Ok(false);
}
reject_symlink(&path)?;
if read_file(&path)? != embedded.contents {
return Ok(false);
}
}
Ok(true)
}
fn managed_files_unchanged(target: &Path, state: &ManagedState) -> Result<bool, CliError> {
if state.schema_version != STATE_SCHEMA_VERSION || state.skill_name != SKILL_NAME {
return Ok(false);
}
for (relative_path, expected_hash) in &state.files {
let path = safe_join(target, relative_path)?;
if !path.exists() {
return Ok(false);
}
reject_symlink(&path)?;
if content_hash(read_file(&path)?.as_bytes()) != *expected_hash {
return Ok(false);
}
}
for embedded in EMBEDDED_FILES {
if state.files.contains_key(embedded.relative_path) {
continue;
}
let path = safe_join(target, embedded.relative_path)?;
if path.exists() {
reject_symlink(&path)?;
if read_file(&path)? != embedded.contents {
return Ok(false);
}
}
}
Ok(true)
}
fn write_embedded_files(target: &Path) -> Result<(), CliError> {
fs::create_dir_all(target).map_err(|error| io_error("SKILL_WRITE_FAILED", target, error))?;
reject_symlink(target)?;
for embedded in EMBEDDED_FILES {
let path = safe_join(target, embedded.relative_path)?;
reject_symlink(&path)?;
write_atomic(&path, embedded.contents.as_bytes())?;
}
Ok(())
}
fn write_state(target: &Path) -> Result<(), CliError> {
fs::create_dir_all(target).map_err(|error| io_error("SKILL_WRITE_FAILED", target, error))?;
let state = bundled_state();
let contents = serde_json::to_vec_pretty(&state).map_err(|error| CliError::new("ERROR", error.to_string()))?;
write_atomic(&target.join(STATE_FILE_NAME), &contents)
}
fn bundled_state() -> ManagedState {
let files = EMBEDDED_FILES
.iter()
.map(|embedded| (embedded.relative_path.to_string(), content_hash(embedded.contents.as_bytes())))
.collect();
ManagedState {
schema_version: STATE_SCHEMA_VERSION,
skill_name: SKILL_NAME.to_string(),
skill_version: SKILL_VERSION.to_string(),
files,
}
}
fn read_state(target: &Path) -> Option<ManagedState> {
let path = target.join(STATE_FILE_NAME);
reject_symlink(&path).ok()?;
let contents = fs::read_to_string(path).ok()?;
serde_json::from_str(&contents).ok()
}
fn read_file(path: &Path) -> Result<String, CliError> {
fs::read_to_string(path).map_err(|error| io_error("SKILL_READ_FAILED", path, error))
}
fn write_atomic(path: &Path, contents: &[u8]) -> Result<(), CliError> {
reject_symlink(path)?;
let parent = path.parent().ok_or_else(|| CliError::new("SKILL_WRITE_FAILED", "Skill path has no parent."))?;
fs::create_dir_all(parent).map_err(|error| io_error("SKILL_WRITE_FAILED", parent, error))?;
let mut temporary =
tempfile::NamedTempFile::new_in(parent).map_err(|error| io_error("SKILL_WRITE_FAILED", parent, error))?;
temporary
.write_all(contents)
.and_then(|_| temporary.as_file().sync_all())
.map_err(|error| io_error("SKILL_WRITE_FAILED", path, error))?;
temporary.persist(path).map_err(|error| io_error("SKILL_WRITE_FAILED", path, error.error))?;
Ok(())
}
fn reject_symlink(path: &Path) -> Result<(), CliError> {
match fs::symlink_metadata(path) {
Ok(metadata) if metadata.file_type().is_symlink() => Err(CliError::new(
"SKILL_PATH_UNSAFE",
format!("Refusing to write through symbolic link {}.", path.display()),
)),
Ok(_) => Ok(()),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(error) => Err(io_error("SKILL_READ_FAILED", path, error)),
}
}
fn safe_join(root: &Path, relative_path: &str) -> Result<PathBuf, CliError> {
let relative = Path::new(relative_path);
if relative.is_absolute() || relative.components().any(|component| !matches!(component, Component::Normal(_))) {
return Err(CliError::new("SKILL_PATH_UNSAFE", "Managed skill metadata contains an unsafe path."));
}
Ok(root.join(relative))
}
fn content_hash(contents: &[u8]) -> String {
format!("{:x}", Sha256::digest(contents))
}
fn frontmatter_version(contents: &str) -> Option<String> {
let mut lines = contents.lines();
if lines.next()? != "---" {
return None;
}
for line in lines {
if line == "---" {
break;
}
if let Some(value) = line.strip_prefix("version:") {
return Some(value.trim().trim_matches(['\'', '"']).to_string());
}
}
None
}
fn report(action: &str, target: &Path, inspection: Inspection) -> AgentSkillReport {
AgentSkillReport {
action: action.to_string(),
status: inspection.status.as_str().to_string(),
skill_name: SKILL_NAME.to_string(),
bundled_version: SKILL_VERSION.to_string(),
installed_version: inspection.installed_version,
managed: inspection.managed,
path: target.display().to_string(),
}
}
fn render_report(report: AgentSkillReport, format: OutputFormat) -> Result<String, CliError> {
if format == OutputFormat::Json {
return json_string(&report);
}
Ok(format!(
"DBX Agent Skill\nAction: {}\nStatus: {}\nBundled version: {}\nInstalled version: {}\nManaged: {}\nPath: {}\n",
report.action,
report.status,
report.bundled_version,
report.installed_version.as_deref().unwrap_or("not installed"),
if report.managed { "yes" } else { "no" },
report.path
))
}
fn io_error(code: &'static str, path: &Path, error: std::io::Error) -> CliError {
CliError::new(code, format!("{}: {error}", path.display()))
}
#[cfg(test)]
mod tests {
use super::*;
fn args(values: &[&str]) -> Vec<String> {
values.iter().map(|value| (*value).to_string()).collect()
}
#[test]
fn embedded_skill_version_matches_frontmatter() {
let main = EMBEDDED_FILES.iter().find(|file| file.relative_path == "SKILL.md").unwrap();
assert_eq!(frontmatter_version(main.contents).as_deref(), Some(SKILL_VERSION));
}
#[test]
fn embedded_command_reference_covers_the_cli_surface() {
let commands =
EMBEDDED_FILES.iter().find(|file| file.relative_path == "references/commands.md").unwrap().contents;
for command in [
"dbx doctor",
"dbx capabilities",
"dbx agent setup",
"dbx agent status",
"dbx connections list",
"dbx schema list",
"dbx schema describe",
"dbx query",
"dbx context",
"dbx dbml",
"dbx docs",
"dbx open",
] {
assert!(commands.contains(command), "command reference is missing {command}");
}
}
#[test]
fn setup_installs_and_reports_the_bundled_skill() {
let directory = tempfile::tempdir().unwrap();
let output = run(&args(&["agent", "setup"]), OutputFormat::Json, Some(directory.path()), false).unwrap();
let output: serde_json::Value = serde_json::from_str(&output).unwrap();
assert_eq!(output["action"], "installed");
assert_eq!(output["status"], "up_to_date");
assert_eq!(output["bundledVersion"], SKILL_VERSION);
assert!(directory.path().join("dbx/SKILL.md").exists());
assert!(directory.path().join("dbx/references/commands.md").exists());
assert!(directory.path().join(format!("dbx/{STATE_FILE_NAME}")).exists());
}
#[test]
fn repeated_setup_is_idempotent() {
let directory = tempfile::tempdir().unwrap();
run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap();
let output = run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap();
assert!(output.contains("Action: unchanged"));
}
#[test]
fn setup_preserves_an_unmanaged_skill_without_force() {
let directory = tempfile::tempdir().unwrap();
let target = directory.path().join("dbx");
fs::create_dir_all(&target).unwrap();
fs::write(target.join("SKILL.md"), "custom skill").unwrap();
let error = run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap_err();
assert_eq!(error.code, "SKILL_MODIFIED");
assert_eq!(fs::read_to_string(target.join("SKILL.md")).unwrap(), "custom skill");
}
#[test]
fn force_replaces_managed_paths_but_keeps_extra_files() {
let directory = tempfile::tempdir().unwrap();
let target = directory.path().join("dbx");
fs::create_dir_all(&target).unwrap();
fs::write(target.join("SKILL.md"), "custom skill").unwrap();
fs::write(target.join("notes.md"), "keep me").unwrap();
let output = run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), true).unwrap();
assert!(output.contains("Action: replaced"));
assert_eq!(fs::read_to_string(target.join("SKILL.md")).unwrap(), EMBEDDED_FILES[0].contents);
assert_eq!(fs::read_to_string(target.join("notes.md")).unwrap(), "keep me");
}
#[test]
fn status_reports_locally_modified_managed_skill() {
let directory = tempfile::tempdir().unwrap();
run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap();
fs::write(directory.path().join("dbx/SKILL.md"), "edited").unwrap();
let output = run(&args(&["agent", "status"]), OutputFormat::Json, Some(directory.path()), false).unwrap();
let output: serde_json::Value = serde_json::from_str(&output).unwrap();
assert_eq!(output["status"], "modified");
assert_eq!(output["managed"], true);
}
#[test]
fn status_reports_a_managed_update_without_overwriting_it() {
let directory = tempfile::tempdir().unwrap();
let target = directory.path().join("dbx");
fs::create_dir_all(&target).unwrap();
fs::write(target.join("SKILL.md"), "old managed skill").unwrap();
let mut files = BTreeMap::new();
files.insert("SKILL.md".to_string(), content_hash(b"old managed skill"));
let old_state = ManagedState {
schema_version: STATE_SCHEMA_VERSION,
skill_name: SKILL_NAME.to_string(),
skill_version: "1.0.0".to_string(),
files,
};
fs::write(target.join(STATE_FILE_NAME), serde_json::to_vec(&old_state).unwrap()).unwrap();
let output = run(&args(&["agent", "status"]), OutputFormat::Json, Some(directory.path()), false).unwrap();
let output: serde_json::Value = serde_json::from_str(&output).unwrap();
assert_eq!(output["status"], "update_available");
assert_eq!(output["installedVersion"], "1.0.0");
assert_eq!(fs::read_to_string(target.join("SKILL.md")).unwrap(), "old managed skill");
}
#[test]
fn setup_updates_an_unchanged_managed_skill() {
let directory = tempfile::tempdir().unwrap();
let target = directory.path().join("dbx");
fs::create_dir_all(&target).unwrap();
fs::write(target.join("SKILL.md"), "old managed skill").unwrap();
let mut files = BTreeMap::new();
files.insert("SKILL.md".to_string(), content_hash(b"old managed skill"));
let old_state = ManagedState {
schema_version: STATE_SCHEMA_VERSION,
skill_name: SKILL_NAME.to_string(),
skill_version: "1.0.0".to_string(),
files,
};
fs::write(target.join(STATE_FILE_NAME), serde_json::to_vec(&old_state).unwrap()).unwrap();
let output = run(&args(&["agent", "setup"]), OutputFormat::Json, Some(directory.path()), false).unwrap();
let output: serde_json::Value = serde_json::from_str(&output).unwrap();
assert_eq!(output["action"], "updated");
assert_eq!(output["status"], "up_to_date");
assert_eq!(output["installedVersion"], SKILL_VERSION);
}
#[test]
fn missing_main_file_is_treated_as_a_local_modification() {
let directory = tempfile::tempdir().unwrap();
run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap();
fs::remove_file(directory.path().join("dbx/SKILL.md")).unwrap();
let error = run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap_err();
assert_eq!(error.code, "SKILL_MODIFIED");
}
#[cfg(unix)]
#[test]
fn setup_rejects_a_symlinked_skill_directory() {
use std::os::unix::fs::symlink;
let directory = tempfile::tempdir().unwrap();
let outside = tempfile::tempdir().unwrap();
symlink(outside.path(), directory.path().join("dbx")).unwrap();
let error = run(&args(&["agent", "setup"]), OutputFormat::Table, Some(directory.path()), false).unwrap_err();
assert_eq!(error.code, "SKILL_PATH_UNSAFE");
}
}