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 in the background)
---
Run the SymForge admin verb to open the operator dashboard.
Execute this command in the project root:
```
symforge admin
```
If a dashboard is already running on the remembered port, `symforge admin` prints
its URL and returns immediately. If none is running it STARTS a new server and
serves it IN THE FOREGROUND until you stop it (Ctrl-C) — so if you are an agent
running this in a shell tool, launch it as a background/detached process (e.g.
append `&` or run it detached) and then read the printed dashboard URL, or the
tool call blocks until it times out and kills the fresh server.
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());
}
}