use std::path::{Path, PathBuf};
use crate::cli::harness::HarnessId;
use crate::cli::harness_apply::{BackupRecord, write_backup};
pub const CLAUDE_ADMIN_COMMAND_FILE: &str = "symforge-admin.md";
const CLAUDE_ADMIN_COMMAND_BODY: &str = "\
---
description: Open the SymForge operator dashboard (reuse a running server, or start one)
---
Run the SymForge admin verb to open the operator dashboard.
Execute this command in the project root:
```
symforge admin
```
`symforge admin` reuses a server already running on the remembered port, or
starts one on a verified-free port and opens the dashboard URL. If your
environment cannot run shell commands, use the `symforge-admin` MCP prompt
instead, which reports the running dashboard URL.
";
#[derive(Debug, Clone)]
pub enum CommandFileOutcome {
Installed {
id: HarnessId,
path: PathBuf,
backup: Option<BackupRecord>,
},
PromptOnly { id: HarnessId },
Failed { id: HarnessId, reason: String },
}
pub fn install_admin_command_file(home: &Path, id: HarnessId) -> CommandFileOutcome {
match id {
HarnessId::ClaudeCode => install_claude_admin_command_file(home),
HarnessId::ClaudeDesktop
| HarnessId::Codex
| HarnessId::Gemini
| HarnessId::KiloCode
| HarnessId::Cursor => CommandFileOutcome::PromptOnly { id },
}
}
fn install_claude_admin_command_file(home: &Path) -> CommandFileOutcome {
let id = HarnessId::ClaudeCode;
let path = claude_admin_command_path(home);
if let Some(parent) = path.parent()
&& let Err(e) = std::fs::create_dir_all(parent)
{
return CommandFileOutcome::Failed {
id,
reason: format!("creating {}: {e}", parent.display()),
};
}
let backup = if path.exists() {
match write_backup(&path) {
Ok(record) => Some(record),
Err(e) => {
return CommandFileOutcome::Failed {
id,
reason: format!("backing up {}: {e}", path.display()),
};
}
}
} else {
None
};
if let Err(e) = atomic_write(&path, CLAUDE_ADMIN_COMMAND_BODY.as_bytes()) {
return CommandFileOutcome::Failed {
id,
reason: format!("writing {}: {e}", path.display()),
};
}
CommandFileOutcome::Installed { id, path, backup }
}
fn claude_admin_command_path(home: &Path) -> PathBuf {
home.join(".claude")
.join("commands")
.join(CLAUDE_ADMIN_COMMAND_FILE)
}
fn atomic_write(path: &Path, content: &[u8]) -> std::io::Result<()> {
use std::io::Write;
let parent = path.parent().ok_or_else(|| {
std::io::Error::new(
std::io::ErrorKind::InvalidInput,
"command-file path has no parent directory",
)
})?;
let mut tmp = tempfile::NamedTempFile::new_in(parent)?;
tmp.write_all(content)?;
tmp.flush()?;
tmp.as_file().sync_all()?;
tmp.persist(path).map_err(|e| e.error)?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn installs_claude_code_command_file() {
let home = tempfile::tempdir().expect("temp home");
let outcome = install_admin_command_file(home.path(), HarnessId::ClaudeCode);
let path = match outcome {
CommandFileOutcome::Installed { path, backup, id } => {
assert_eq!(id, HarnessId::ClaudeCode);
assert!(backup.is_none(), "fresh install has no backup");
path
}
other => panic!("expected Installed, got {other:?}"),
};
assert_eq!(path, claude_admin_command_path(home.path()));
let body = std::fs::read_to_string(&path).expect("command file written");
assert!(
body.contains("symforge admin"),
"body invokes the verb: {body}"
);
assert!(
body.contains("description:"),
"body has slash-command front matter"
);
}
#[test]
fn reinstall_backs_up_existing_command_file() {
let home = tempfile::tempdir().expect("temp home");
let path = claude_admin_command_path(home.path());
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
let prior = "my custom symforge-admin command\n";
std::fs::write(&path, prior).unwrap();
let outcome = install_admin_command_file(home.path(), HarnessId::ClaudeCode);
let backup = match outcome {
CommandFileOutcome::Installed {
backup: Some(b), ..
} => b,
other => panic!("expected Installed with a backup, got {other:?}"),
};
let body = std::fs::read_to_string(&path).unwrap();
assert!(body.contains("symforge admin"));
assert_eq!(std::fs::read_to_string(&backup.backup).unwrap(), prior);
}
#[test]
fn no_format_harness_installs_nothing() {
let home = tempfile::tempdir().expect("temp home");
for id in [
HarnessId::Codex,
HarnessId::Gemini,
HarnessId::Cursor,
HarnessId::KiloCode,
HarnessId::ClaudeDesktop,
] {
let outcome = install_admin_command_file(home.path(), id);
match outcome {
CommandFileOutcome::PromptOnly { id: got } => assert_eq!(got, id),
other => panic!(
"{id:?} has no documented command-file format; \
expected PromptOnly, got {other:?}"
),
}
}
assert!(!home.path().join(".claude").exists());
}
}