agentgear 0.1.3

//! The opencode backend: a full translate into opencode's own config. MCP is
//! bespoke (opencode's `command` is a single array + `type:"local"`, not CC's
//! split `command`/`args`), written under the top-level `mcp` object of
//! `~/.config/opencode/opencode.json` via `confedit::json_edit`. Commands copy
//! through as markdown (opencode's command format is CC-shaped); agents translate
//! into opencode subagent markdown (injecting `mode: subagent`). The host's
//! always-loaded guidance ([`Plugin::instructions`]) is written to a dedicated
//! `<plugin>-instructions.md` and its path registered in opencode's top-level
//! `instructions` array. Every file we emit is plugin-name-prefixed and every mcp
//! key is our own server name, so `remove` is exact and a second reconcile is a
//! true `NoOp`.
//!
//! Skipped surfaces (see `docs/harness/opencode.md`): hooks (opencode has no
//! declarative shell-hook config — only an in-process JS/TS plugin API whose
//! CC-`UserPromptSubmit` analogue is unverified and version-volatile per the
//! brief), skills, and the CC `model` alias on agents (no reliable map to
//! opencode's `provider/model` ids).

use std::fmt::Write as _;
use std::fs;
use std::path::{Path, PathBuf};

use serde_json::{Map, Value};

use super::confedit::{json_edit, json_obj_at, json_prune_at, json_prune_obj, json_remove, remove_file_idem, write_file_idem, yaml_quote};
use super::report;
use super::{AgentBackend, BackendState};
use crate::components::{MarkdownDoc, McpKind, McpServer};
use crate::doctor::{CheckStatus, DoctorCheck, DoctorReport};
use crate::error::{Error, Result};
use crate::host::{Capabilities, Desired, Outcome, Plugin, Scope, Source};

pub(crate) struct OpencodeBackend;

impl AgentBackend for OpencodeBackend {
    fn id(&self) -> &'static str {
        "opencode"
    }

    fn detect(&self) -> bool {
        // `~/.config/opencode` is XDG-based, so a test redirecting `XDG_CONFIG_HOME`
        // (or `HOME`) redirects detection too; the `opencode` CLI on PATH is a bonus.
        which::which("opencode").is_ok() || dirs::config_dir().is_some_and(|c| c.join("opencode").is_dir())
    }

    fn capabilities(&self) -> Capabilities {
        // `hooks:false` — opencode's only hook surface is JS/TS plugins, not the
        // shell-command config CC-style hooks translate to (see the module doc).
        // mcp + commands + agents + instructions translate; hooks + skills are skipped.
        Capabilities {
            plugins: false,
            mcp: true,
            hooks: false,
            commands: true,
            agents: true,
            skills: false,
            instructions: true,
            scopes: &["user", "project"],
        }
    }

    fn probe(&self, plugin: &Plugin, scope: &Scope, source: &Source) -> Result<BackendState> {
        // Compose every surface (mcp + the command/agent markdown files), so a missing
        // command or agent file behind a healthy mcp map reads NeedsRepair. `probe_mcp`
        // still carries the Disabled classification for a user-flipped `enabled:false`.
        // `source` is the one self_heal resolved for this agent (rehydrated `--path`,
        // else the compile-time default), so probe and reconcile render identical bytes.
        let comp = plugin.components(source)?.with_client(self.id());
        let mcp =
            if comp.mcp_servers.iter().any(|s| s.is_portable()) { Some(probe_mcp(&config_file(scope)?, &comp.mcp_servers)?) } else { None };
        let base = surface_base(scope)?;
        let commands =
            report::probe_files(&expected_docs(&base, "commands", plugin.name, &comp.commands, |doc| doc.raw.clone()), |_, _| true)?;
        let agents = report::probe_files(
            &expected_docs(&base, "agents", plugin.name, &comp.agents, |doc| render_agent_md(doc).into_bytes()),
            |_, _| true,
        )?;
        // The instructions surface has two halves: the plugin-prefixed guidance file
        // (its own name is the ownership marker, so `is_ours` is unconditional like
        // commands/agents) and our path's membership in the shared `instructions[]`.
        let (instr_file, instr_reg) = match &plugin.instructions {
            Some(text) => (
                report::probe_files(&[(instructions_file(scope, plugin.name)?, render_instructions(text))], |_, _| true)?,
                report::probe_json_entries(
                    &config_file(scope)?,
                    &[(vec!["instructions".to_string()], Value::from(instructions_registration(scope, plugin.name)?))],
                )?,
            ),
            None => (None, None),
        };
        Ok(report::compose([mcp, commands, agents, instr_file, instr_reg].into_iter().flatten()))
    }

    fn reconcile(&self, plugin: &Plugin, desired: &Desired, scope: &Scope) -> Result<Outcome> {
        let comp = plugin.components(&desired.source)?.with_client(self.id());
        let config = config_file(scope)?;
        let base = surface_base(scope)?;

        let mut changed = false;
        changed |= reconcile_mcp(&config, &comp.mcp_servers, desired.reenable)?;
        // Commands are markdown + YAML frontmatter in both CC and opencode, so the
        // verbatim bytes are a valid opencode command (unknown CC keys are ignored).
        for doc in &comp.commands {
            changed |= write_file_idem(&doc_path(&base, "commands", plugin.name, doc), &doc.raw)?;
        }
        for doc in &comp.agents {
            changed |= write_file_idem(&doc_path(&base, "agents", plugin.name, doc), render_agent_md(doc).as_bytes())?;
        }
        if let Some(text) = &plugin.instructions {
            changed |= write_file_idem(&instructions_file(scope, plugin.name)?, &render_instructions(text))?;
            changed |= reconcile_instructions_entry(&config, &instructions_registration(scope, plugin.name)?)?;
        }
        Ok(if changed { Outcome::Installed } else { Outcome::NoOp })
    }

    fn remove(&self, plugin: &Plugin, scope: &Scope, source: &Source) -> Result<Outcome> {
        let comp = plugin.components(source)?.with_client(self.id());
        let config = config_file(scope)?;
        let base = surface_base(scope)?;

        let mut changed = false;
        changed |= remove_mcp(&config, &portable_names(&comp.mcp_servers))?;
        for doc in &comp.commands {
            changed |= remove_file_idem(&doc_path(&base, "commands", plugin.name, doc))?;
        }
        for doc in &comp.agents {
            changed |= remove_file_idem(&doc_path(&base, "agents", plugin.name, doc))?;
        }
        if plugin.instructions.is_some() {
            changed |= remove_file_idem(&instructions_file(scope, plugin.name)?)?;
            changed |= remove_instructions_entry(&config, &instructions_registration(scope, plugin.name)?)?;
        }
        Ok(if changed { Outcome::Removed } else { Outcome::NoOp })
    }

    fn report(&self, plugin: &Plugin, source: &Source) -> DoctorReport {
        DoctorReport::from_checks(report_checks(self, plugin, source))
    }
}

// --- paths -------------------------------------------------------------------

/// The user-scope `~/.config/opencode` dir (XDG-honoring). A missing config home
/// is a clear, actionable error rather than a silent skip.
fn opencode_config_dir() -> Result<PathBuf> {
    dirs::config_dir()
        .map(|c| c.join("opencode"))
        .ok_or_else(|| Error::Tree("no config directory (HOME and XDG_CONFIG_HOME unset); cannot locate ~/.config/opencode".into()))
}

/// The `opencode.json` we read-modify-write for a scope: `~/.config/opencode/
/// opencode.json` (user) or `<cwd>/opencode.json` (project — at the project root,
/// beside the `.opencode/` dir, per the brief).
fn config_file(scope: &Scope) -> Result<PathBuf> {
    match scope {
        Scope::User => Ok(opencode_config_dir()?.join("opencode.json")),
        Scope::Project { path } => Ok(path.join("opencode.json")),
    }
}

/// The base dir holding the `commands/` + `agents/` surface dirs: `~/.config/
/// opencode` (user) or `<cwd>/.opencode` (project). Note the project config file
/// sits at the root while its surface dirs live under `.opencode/`.
fn surface_base(scope: &Scope) -> Result<PathBuf> {
    match scope {
        Scope::User => opencode_config_dir(),
        Scope::Project { path } => Ok(path.join(".opencode")),
    }
}

/// The on-disk path for a translated doc under `<base>/<subdir>/`: plugin-name
/// prefixed and flattened (subdir separators -> `-`) into one file. opencode's own
/// scan of `commands`/`agents` recurses subdirectories, so a flat, prefixed name
/// stays discoverable there and identifiably ours.
fn doc_path(base: &Path, subdir: &str, plugin: &str, doc: &MarkdownDoc) -> PathBuf {
    let stem =
        doc.rel.strip_prefix(subdir).unwrap_or(&doc.rel).trim_start_matches('/').strip_suffix(".md").unwrap_or(&doc.rel).replace('/', "-");
    base.join(subdir).join(format!("{plugin}-{stem}.md"))
}

/// The `(path, rendered bytes)` files `probe` compares against disk for a surface
/// dir, keyed off the same `doc_path` + render `reconcile` writes.
fn expected_docs(
    base: &Path, subdir: &str, plugin: &str, docs: &[MarkdownDoc], render: impl Fn(&MarkdownDoc) -> Vec<u8>,
) -> Vec<(PathBuf, Vec<u8>)> {
    docs.iter().map(|doc| (doc_path(base, subdir, plugin, doc), render(doc))).collect()
}

/// Server names `reconcile_mcp` actually writes (non-portable ones are skipped).
/// `remove` keys off the same set so it never deletes a user server that happens
/// to share a name with one we declared but never wrote.
fn portable_names(servers: &[McpServer]) -> Vec<&str> {
    servers.iter().filter(|s| s.is_portable()).map(|s| s.name.as_str()).collect()
}

// --- mcp (bespoke) -----------------------------------------------------------

/// opencode's server body: `command` is a single array (`[cmd, ...args]`), `type`
/// is `local`/`remote` (not CC's `stdio`/`sse`/`http`). `enabled` is opencode's own
/// per-server on/off flag (unlike the shared json family, which has none) -
/// deterministic per `enabled` so a re-reconcile is byte-identical -> a true `NoOp`.
fn render_mcp_server(server: &McpServer, enabled: bool) -> Value {
    match &server.kind {
        McpKind::Stdio => {
            let mut command = Vec::with_capacity(1 + server.args.len());
            command.push(Value::from(server.command.clone()));
            command.extend(server.args.iter().map(|a| Value::from(a.clone())));
            let env: Map<String, Value> = server.env.iter().map(|(k, v)| (k.clone(), Value::from(v.clone()))).collect();
            let mut obj = Map::new();
            obj.insert("type".into(), Value::from("local"));
            obj.insert("command".into(), Value::Array(command));
            obj.insert("enabled".into(), Value::Bool(enabled));
            obj.insert("environment".into(), Value::Object(env));
            Value::Object(obj)
        }
        // opencode collapses SSE/HTTP into one `remote` type keyed by `url`.
        McpKind::Http { url } | McpKind::Sse { url } => {
            let mut obj = Map::new();
            obj.insert("type".into(), Value::from("remote"));
            obj.insert("url".into(), Value::from(url.clone()));
            obj.insert("enabled".into(), Value::Bool(enabled));
            Value::Object(obj)
        }
    }
}

/// Insert/update exactly our servers under the top-level `mcp` object, leaving
/// the user's own keys. Skips the write entirely (no empty `mcp` key) when the
/// plugin declares no portable server. `reenable=false` (self_heal) preserves an
/// existing explicit `enabled:false` on our own key instead of forcing it back on,
/// since opencode's `enabled` flag is a real per-server disable a user can set and
/// the foundation's never-re-enable invariant applies to it exactly like CC's.
/// `reenable=true` (an explicit install/update) always re-enables, mirroring
/// `claude.rs`'s `entry.enabled == Some(false)` handling.
fn reconcile_mcp(config: &Path, servers: &[McpServer], reenable: bool) -> Result<bool> {
    let portable: Vec<&McpServer> = servers.iter().filter(|s| s.is_portable()).collect();
    if portable.is_empty() {
        return Ok(false);
    }
    json_edit(config, |root| {
        let obj = json_obj_at(root, &["mcp"]);
        for server in &portable {
            let currently_disabled = obj.get(&server.name).and_then(|v| v.get("enabled")).and_then(Value::as_bool) == Some(false);
            let enabled = reenable || !currently_disabled;
            obj.insert(server.name.clone(), render_mcp_server(server, enabled));
        }
        Ok(())
    })
}

/// Remove exactly our server keys under `mcp`, leaving others. The `mcp` object goes
/// with our last key when our own removal is what emptied it, and the file goes with
/// an emptied root; a `mcp` the user had empty before us is untouched.
fn remove_mcp(config: &Path, names: &[&str]) -> Result<bool> {
    if !config.exists() || names.is_empty() {
        return Ok(false);
    }
    json_remove(config, |root| {
        json_prune_obj(root, &["mcp"], |obj| {
            for name in names {
                obj.remove(*name);
            }
            Ok(())
        })
        .map(|_| ())
    })
}

/// `Absent` if none of our servers are present; `Disabled` if all present
/// servers exactly match our render with `enabled:false` (a user's deliberate
/// opencode-level disable - self_heal must never flip it back, same invariant as
/// CC's plugin disable); `Healthy` if all present and byte-matching our enabled
/// render; `NeedsRepair` otherwise (drifted, or a mix of enabled/disabled/drifted
/// across multiple servers). `Healthy` (not `Absent`) when the plugin declares no
/// portable server, so a present marker is not dropped.
fn probe_mcp(config: &Path, servers: &[McpServer]) -> Result<BackendState> {
    let bytes = match fs::read(config) {
        Ok(b) => b,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(BackendState::Absent),
        Err(source) => return Err(Error::Io { context: format!("reading {}", config.display()), source }),
    };
    let root: Value =
        serde_json::from_slice(&bytes).map_err(|e| Error::Config { path: config.display().to_string(), detail: e.to_string() })?;

    let portable: Vec<&McpServer> = servers.iter().filter(|s| s.is_portable()).collect();
    if portable.is_empty() {
        return Ok(BackendState::Healthy);
    }
    let obj = root.get("mcp").and_then(Value::as_object);
    let mut present = 0usize;
    let mut enabled = 0usize;
    let mut disabled = 0usize;
    for server in &portable {
        if let Some(existing) = obj.and_then(|o| o.get(&server.name)) {
            present += 1;
            if *existing == render_mcp_server(server, true) {
                enabled += 1;
            } else if *existing == render_mcp_server(server, false) {
                disabled += 1;
            }
        }
    }
    Ok(if present == 0 {
        BackendState::Absent
    } else if disabled == portable.len() {
        BackendState::Disabled
    } else if enabled == portable.len() {
        BackendState::Healthy
    } else {
        BackendState::NeedsRepair
    })
}

// --- instructions ------------------------------------------------------------

/// The dedicated always-loaded guidance file we own, plugin-name-prefixed so it is
/// identifiably ours and `remove` is exact: `<base>/<plugin>-instructions.md`
/// (`~/.config/opencode` user, `<project>/.opencode` project).
fn instructions_file(scope: &Scope, plugin: &str) -> Result<PathBuf> {
    Ok(surface_base(scope)?.join(format!("{plugin}-instructions.md")))
}

/// The path string registered in opencode.json's `instructions[]`. User scope uses
/// the file's absolute path — the global config is per-user, never committed, so a
/// machine path is safe and resolves unambiguously wherever opencode runs. Project
/// scope uses the root-relative `.opencode/...` path so a committed project config
/// stays portable. Both `reconcile` and `probe` route through here (mirror-filter).
fn instructions_registration(scope: &Scope, plugin: &str) -> Result<String> {
    match scope {
        Scope::User => Ok(instructions_file(scope, plugin)?.to_string_lossy().into_owned()),
        Scope::Project { .. } => Ok(format!(".opencode/{plugin}-instructions.md")),
    }
}

/// The guidance file's bytes: the host text with a guaranteed trailing newline, the
/// exact render `probe` compares against disk.
fn render_instructions(text: &str) -> Vec<u8> {
    let mut out = text.to_string();
    if !out.ends_with('\n') {
        out.push('\n');
    }
    out.into_bytes()
}

/// Append our guidance file to opencode's top-level `instructions[]` if absent,
/// leaving the user's own entries. A non-array `instructions` value (malformed —
/// opencode's own schema rejects it too) is left untouched rather than clobbered; the
/// probe then reads that surface `Absent` and self_heal stays a benign `NoOp` (it
/// cannot force the key without clobbering a user value), never converging but never
/// churning either.
fn reconcile_instructions_entry(config: &Path, entry: &str) -> Result<bool> {
    json_edit(config, |root| {
        let obj = json_obj_at(root, &[]);
        let list = obj.entry("instructions".to_string()).or_insert_with(|| Value::Array(Vec::new()));
        if let Value::Array(arr) = list
            && !arr.iter().any(|e| e.as_str() == Some(entry))
        {
            arr.push(Value::from(entry));
        }
        Ok(())
    })
}

/// Strip exactly our path from `instructions[]`, keeping the user's entries. The key
/// follows our entry out when ours is what emptied the array, and the file follows an
/// emptied root — the same stance as `remove_mcp`; an array the user had empty before
/// us is untouched.
fn remove_instructions_entry(config: &Path, entry: &str) -> Result<bool> {
    if !config.exists() {
        return Ok(false);
    }
    json_remove(config, |root| {
        json_prune_at(root, &["instructions"], |list| {
            if let Some(arr) = list.as_array_mut() {
                arr.retain(|e| e.as_str() != Some(entry));
            }
            Ok(())
        })
        .map(|_| ())
    })
}

// --- agents ------------------------------------------------------------------

/// Render a CC agent doc as opencode subagent markdown. CC agents are always
/// subagents (invoked via the Task tool), so `mode: subagent` is injected;
/// opencode's own mode-less default is `all` (usable as both primary and
/// subagent), which would let the translated agent run standalone too. The CC
/// `model` alias (`sonnet`/`opus`) is dropped — it has no reliable map to
/// opencode's `provider/model` ids, so opencode's own default is used instead.
fn render_agent_md(doc: &MarkdownDoc) -> String {
    let mut out = String::from("---\n");
    if let Some(desc) = doc.frontmatter.get("description").and_then(Value::as_str) {
        let _ = writeln!(out, "description: {}", yaml_quote(desc));
    }
    out.push_str("mode: subagent\n---\n\n");
    out.push_str(doc.body.trim_start_matches(['\n', '\r']));
    if !out.ends_with('\n') {
        out.push('\n');
    }
    out
}

// --- report ------------------------------------------------------------------

fn report_checks(backend: &OpencodeBackend, plugin: &Plugin, source: &Source) -> Vec<DoctorCheck> {
    let mut checks = Vec::new();

    checks.push(if backend.detect() {
        DoctorCheck { name: "opencode detected", status: CheckStatus::Ok("`opencode` on PATH or ~/.config/opencode present".into()) }
    } else {
        DoctorCheck {
            name: "opencode detected",
            status: CheckStatus::Fail {
                problem: "opencode CLI not detected".into(),
                fix: "install it with `npm install -g opencode-ai`".into(),
            },
        }
    });

    let config = match config_file(&Scope::User) {
        Ok(config) => config,
        Err(e) => {
            checks.push(DoctorCheck { name: "config file", status: CheckStatus::Warn(e.to_string()) });
            return checks;
        }
    };

    let root = report::read_json_config(&mut checks, "config file", &config);

    let Some(comp) = report::components(&mut checks, plugin, source).map(|c| c.with_client(backend.id())) else {
        return checks;
    };

    checks.push(report::check_mcp_registered(
        &comp.mcp_servers,
        root.as_ref(),
        &["mcp"],
        "not under `mcp` in opencode.json",
        "run the host's `setup`",
    ));
    checks.push(report::check_mcp_command(&comp.mcp_servers));

    let base = match surface_base(&Scope::User) {
        Ok(base) => base,
        Err(e) => {
            checks.push(DoctorCheck { name: "translated files present", status: CheckStatus::Warn(e.to_string()) });
            return checks;
        }
    };
    checks.push(check_docs_present("translated commands present", &comp.commands, &base, "commands", plugin.name));
    checks.push(check_docs_present("translated agents present", &comp.agents, &base, "agents", plugin.name));

    if plugin.instructions.is_some() {
        checks.push(match instructions_file(&Scope::User, plugin.name) {
            Ok(f) if f.exists() => {
                DoctorCheck { name: "instructions file present", status: CheckStatus::Ok(format!("{} present", f.display())) }
            }
            Ok(f) => DoctorCheck {
                name: "instructions file present",
                status: CheckStatus::Fail { problem: format!("{} missing", f.display()), fix: "run the host's `setup`".into() },
            },
            Err(e) => DoctorCheck { name: "instructions file present", status: CheckStatus::Warn(e.to_string()) },
        });
        // The file is inert unless its path is in `instructions[]`; the registration is
        // the load-bearing half, so check it separately (mirrors the mcp-registered check).
        let name = "instructions registered";
        checks.push(match instructions_registration(&Scope::User, plugin.name) {
            Ok(reg) => {
                let registered = root
                    .as_ref()
                    .and_then(|r| r.get("instructions"))
                    .and_then(Value::as_array)
                    .is_some_and(|a| a.iter().any(|e| e.as_str() == Some(reg.as_str())));
                if registered {
                    DoctorCheck { name, status: CheckStatus::Ok("registered in opencode.json `instructions[]`".into()) }
                } else {
                    DoctorCheck {
                        name,
                        status: CheckStatus::Fail {
                            problem: "guidance file not registered in opencode.json `instructions[]`".into(),
                            fix: "run the host's `setup`".into(),
                        },
                    }
                }
            }
            Err(e) => DoctorCheck { name, status: CheckStatus::Warn(e.to_string()) },
        });
    }

    checks
}

fn check_docs_present(name: &'static str, docs: &[MarkdownDoc], base: &Path, subdir: &str, plugin: &str) -> DoctorCheck {
    if docs.is_empty() {
        return DoctorCheck { name, status: CheckStatus::Ok("nothing to translate".into()) };
    }
    let missing: Vec<String> =
        docs.iter().map(|doc| doc_path(base, subdir, plugin, doc)).filter(|p| !p.exists()).map(|p| p.display().to_string()).collect();
    if missing.is_empty() {
        DoctorCheck { name, status: CheckStatus::Ok(format!("{} file(s) present", docs.len())) }
    } else {
        DoctorCheck {
            name,
            status: CheckStatus::Fail { problem: format!("file(s) missing: {}", missing.join(", ")), fix: "run the host's `setup`".into() },
        }
    }
}