symforge 8.8.3

SymForge — in-memory code intelligence MCP server for Claude Code, Codex, and Gemini CLI
Documentation
//! Per-harness `symforge-admin` command-file install (009 US3, D2).
//!
//! Installs a `symforge-admin` command file where the harness supports one (e.g.
//! Claude Code `~/.claude/commands/symforge-admin.md`); harnesses without a
//! command-file convention rely on the universal MCP prompt instead (no guessed
//! or broken file — the MCP prompt is the floor). Reuses the restorable-backup
//! write path (FR-016).
//!
//! The universal affordance is the MCP prompt `symforge-admin` (registered in
//! `protocol::prompts`); this module is the *convenience layer* — a one-keystroke
//! slash-command for harnesses that document a command-file format. Across the
//! live [`HarnessId`] set, only **Claude Code** documents one (markdown
//! slash-commands under `~/.claude/commands/`); the rest (Codex, Gemini, Cursor,
//! KiloCode, Claude Desktop) get the MCP prompt only — guessing a format we
//! cannot verify would ship a broken affordance (a nonworking feature, D2).

use std::path::{Path, PathBuf};

use crate::cli::harness::HarnessId;
use crate::cli::harness_apply::{BackupRecord, write_backup};

/// On-disk filename for the Claude Code `symforge-admin` slash-command file
/// installed under `~/.claude/commands/`.
pub const CLAUDE_ADMIN_COMMAND_FILE: &str = "symforge-admin.md";

/// Markdown body of the Claude Code `/symforge-admin` slash-command. Invoking it
/// runs the `symforge admin` CLI verb, which reuses a running operator server or
/// starts one and opens the dashboard (contracts/command-file.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.
";

/// Whether a harness got a command file installed, and where — or why it did not.
///
/// Returned per harness from [`install_admin_command_file`] so the caller can
/// report exactly which harness got the one-keystroke command vs which rely on
/// the universal MCP prompt (no harness silently gets nothing — the MCP prompt is
/// the floor for all of them).
///
/// `PartialEq`/`Eq` are intentionally not derived: the `Installed` variant holds
/// a [`BackupRecord`] (a `005` type that does not implement them, and whose
/// timestamped backup path is not a meaningful equality key). Callers match on
/// the variant instead.
#[derive(Debug, Clone)]
pub enum CommandFileOutcome {
    /// A command file was written at `path` (with `backup` if it pre-existed).
    Installed {
        id: HarnessId,
        path: PathBuf,
        backup: Option<BackupRecord>,
    },
    /// The harness documents no command-file format; it relies on the MCP prompt
    /// only. No file was written (no guessed/broken affordance).
    PromptOnly { id: HarnessId },
    /// Writing the command file failed; the harness still has the MCP prompt.
    Failed { id: HarnessId, reason: String },
}

/// Install the `symforge-admin` command file for a single harness under `home`.
///
/// - **Claude Code**: writes `<home>/.claude/commands/symforge-admin.md`, backing
///   up any pre-existing file first (restorable-backup path, FR-016) and writing
///   atomically.
/// - **Any other harness**: writes nothing and returns
///   [`CommandFileOutcome::PromptOnly`] — these harnesses use the MCP prompt
///   (D2, no guessed format).
///
/// `home` is injected (a TempDir in tests, the operator home in production) so no
/// real config is touched in tests (FR-018).
pub fn install_admin_command_file(home: &Path, id: HarnessId) -> CommandFileOutcome {
    match id {
        HarnessId::ClaudeCode => install_claude_admin_command_file(home),
        // No documented command-file format → the MCP prompt is the affordance.
        HarnessId::ClaudeDesktop
        | HarnessId::Codex
        | HarnessId::Gemini
        | HarnessId::KiloCode
        | HarnessId::Cursor => CommandFileOutcome::PromptOnly { id },
    }
}

/// Install the Claude Code command file under `<home>/.claude/commands/`,
/// backing up an existing file first (restorable-backup path) and writing
/// atomically.
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()),
        };
    }

    // Back up any pre-existing command file before overwriting (restorable
    // backup, FR-016) so an operator's custom command is never lost unbacked.
    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 }
}

/// The Claude Code `symforge-admin` command-file path under `home`.
fn claude_admin_command_path(home: &Path) -> PathBuf {
    home.join(".claude")
        .join("commands")
        .join(CLAUDE_ADMIN_COMMAND_FILE)
}

/// Atomically write `content` to `path` (temp file in the same dir + rename),
/// mirroring `harness_apply::atomic_write` (private to that module) and
/// `operator_profile::atomic_write_in`.
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()?;
    // rename(2) on Unix / MoveFileExW(MOVEFILE_REPLACE_EXISTING) on Windows.
    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:?}"),
        };

        // The new body is in place; the prior body is preserved byte-exact in the
        // backup (restorable).
        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:?}"
                ),
            }
        }
        // No `.claude` tree was created for the no-format harnesses (the Claude
        // Code path is the only writer).
        assert!(!home.path().join(".claude").exists());
    }
}