Skip to content

armgit / agtx

Public Imported from GitHub
0

πŸ„πŸΌβ€β™‚οΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.

40.6 KB
Raw Blame
use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};

/// Global configuration (stored in ~/.config/agtx/)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GlobalConfig {
    /// Default agent for new tasks
    #[serde(default = "default_agent")]
    pub default_agent: String,

    /// Per-phase agent overrides
    #[serde(default)]
    pub agents: PhaseAgentsConfig,

    /// Worktree settings
    #[serde(default)]
    pub worktree: WorktreeConfig,

    /// UI theme/colors
    #[serde(default)]
    pub theme: ThemeConfig,

    /// Whether to automatically fullscreen-attach to the tmux session when opening a task popup
    #[serde(default)]
    pub fullscreen_on_enter: bool,

    /// Write agent lifecycle-hook configs into worktrees so agents report their
    /// own phase status. When false, agtx falls back to inferring liveness from
    /// tmux pane output.
    #[serde(default = "default_agent_hooks")]
    pub agent_hooks: bool,
    /// Answer agents' trust and permission-bypass prompts on the user's behalf.
    ///
    /// Off by default: those prompts ask the user to vouch for a directory or to
    /// accept unattended tool execution, and that is their decision. With this
    /// off a task whose agent is waiting on one shows as `Blocked` with the reason
    /// on the card, and the user answers in the agent's own pane.
    ///
    /// Turning it on restores the historical behaviour β€” agtx reads the pane and
    /// sends the answer β€” which is what unattended runs want. It is already
    /// effectively on inside the Docker sandbox and the benchmark, where the
    /// container is disposable and pre-accepting is the documented policy.
    ///
    /// Most users never need it: trust is inherited from the project root for
    /// claude, codex and gemini, `--trust` covers cursor and grok, opencode never
    /// asks, and antigravity's per-worktree entry is seeded from the consent the
    /// user already gave the project (see `agent::trust`).
    #[serde(default)]
    pub auto_trust: bool,

    /// Check GitHub once a day for a newer agtx release and show a notice in
    /// the header. Set false to never ask; `AGTX_NO_UPDATE_CHECK=1` is the
    /// per-invocation equivalent, for CI and containers.
    #[serde(default = "default_update_check")]
    pub update_check: bool,
}

fn default_update_check() -> bool {
    true
}

fn default_agent_hooks() -> bool {
    true
}

impl Default for GlobalConfig {
    fn default() -> Self {
        Self {
            default_agent: default_agent(),
            agents: PhaseAgentsConfig::default(),
            worktree: WorktreeConfig::default(),
            theme: ThemeConfig::default(),
            fullscreen_on_enter: false,
            agent_hooks: default_agent_hooks(),
            auto_trust: false,
            update_check: default_update_check(),
        }
    }
}

/// Theme configuration with hex colors
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThemeConfig {
    /// Border color for selected elements (hex, e.g. "#FFFF00")
    #[serde(default = "default_color_selected")]
    pub color_selected: String,

    /// Border color for normal/unselected elements (hex, e.g. "#00FFFF")
    #[serde(default = "default_color_normal")]
    pub color_normal: String,

    /// Border color for dimmed/inactive elements (hex, e.g. "#666666")
    #[serde(default = "default_color_dimmed")]
    pub color_dimmed: String,

    /// Text color for titles (hex, e.g. "#FFFFFF")
    #[serde(default = "default_color_text")]
    pub color_text: String,

    /// Accent color for highlights (hex, e.g. "#00FFFF")
    #[serde(default = "default_color_accent")]
    pub color_accent: String,

    /// Color for task descriptions (hex, e.g. "#FFB6C1")
    #[serde(default = "default_color_description")]
    pub color_description: String,

    /// Color for column headers when not selected (hex, e.g. "#AAAAAA")
    #[serde(default = "default_color_column_header")]
    pub color_column_header: String,

    /// Color for popup borders (hex, e.g. "#00FF00")
    #[serde(default = "default_color_popup_border")]
    pub color_popup_border: String,

    /// Background color for popup headers (hex, e.g. "#00FFFF")
    #[serde(default = "default_color_popup_header")]
    pub color_popup_header: String,
}

impl Default for ThemeConfig {
    fn default() -> Self {
        Self {
            color_selected: default_color_selected(),
            color_normal: default_color_normal(),
            color_dimmed: default_color_dimmed(),
            color_text: default_color_text(),
            color_accent: default_color_accent(),
            color_description: default_color_description(),
            color_column_header: default_color_column_header(),
            color_popup_border: default_color_popup_border(),
            color_popup_header: default_color_popup_header(),
        }
    }
}

fn default_color_selected() -> String {
    "#ead49a".to_string() // Yellow
}

fn default_color_normal() -> String {
    "#5cfff7".to_string() // Cyan
}

fn default_color_dimmed() -> String {
    "#9C9991".to_string() // Dark Gray
}

fn default_color_text() -> String {
    "#f2ece6".to_string() // Light Rose
}

fn default_color_accent() -> String {
    "#5cfff7".to_string() // Cyan
}

fn default_color_description() -> String {
    "#C4B0AC".to_string() // Rose (dimmed 80%)
}

fn default_color_column_header() -> String {
    "#a0d2fa".to_string() // Light Blue Gray
}

fn default_color_popup_border() -> String {
    "#9ffcf8".to_string() // Light Cyan
}

fn default_color_popup_header() -> String {
    "#69fae7".to_string() // Light Cyan
}

impl ThemeConfig {
    /// Parse a hex color string to RGB tuple
    pub fn parse_hex(hex: &str) -> Option<(u8, u8, u8)> {
        let hex = hex.trim_start_matches('#');
        if hex.len() != 6 {
            return None;
        }
        let r = u8::from_str_radix(&hex[0..2], 16).ok()?;
        let g = u8::from_str_radix(&hex[2..4], 16).ok()?;
        let b = u8::from_str_radix(&hex[4..6], 16).ok()?;
        Some((r, g, b))
    }
}

fn default_agent() -> String {
    "claude".to_string()
}

/// Per-phase agent overrides
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct PhaseAgentsConfig {
    pub research: Option<String>,
    pub planning: Option<String>,
    pub running: Option<String>,
    pub review: Option<String>,
}

/// Worktree configuration
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorktreeConfig {
    /// Whether to use git worktrees for task isolation
    #[serde(default = "default_true")]
    pub enabled: bool,

    /// Automatically clean up worktrees after merge/reject
    #[serde(default = "default_true")]
    pub auto_cleanup: bool,

    /// Base branch to create worktrees from (empty = auto-detect main/master)
    #[serde(default)]
    pub base_branch: String,

    /// Directory (relative to project root) where worktrees are created
    #[serde(default = "default_worktree_dir")]
    pub worktree_dir: String,

    /// Prefix for branch names (e.g. "user/name" β†’ "user/name/slug")
    #[serde(default = "default_branch_prefix")]
    pub branch_prefix: String,
}

impl Default for WorktreeConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            auto_cleanup: true,
            base_branch: String::new(),
            worktree_dir: default_worktree_dir(),
            branch_prefix: default_branch_prefix(),
        }
    }
}

fn default_worktree_dir() -> String {
    crate::git::DEFAULT_WORKTREE_DIR.to_string()
}

fn default_branch_prefix() -> String {
    "task".to_string()
}

fn default_true() -> bool {
    true
}

/// Project-specific configuration (stored in .agtx/config.toml)
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ProjectConfig {
    /// Override default agent for this project
    pub default_agent: Option<String>,

    /// Per-phase agent overrides for this project
    pub agents: Option<PhaseAgentsConfig>,

    /// Override base branch for this project
    pub base_branch: Option<String>,

    /// GitHub URL for this project
    pub github_url: Option<String>,

    /// Directory (relative to project root) where worktrees are created
    pub worktree_dir: Option<String>,

    /// Comma-separated list of files to copy from project root into worktrees
    pub copy_files: Option<String>,

    /// Shell command to run inside the worktree after creation and file copying
    pub init_script: Option<String>,

    /// Shell command to run inside the worktree before removal
    pub cleanup_script: Option<String>,

    /// Workflow plugin name (e.g. "gsd", "spec-kit")
    pub workflow_plugin: Option<String>,

    /// Override branch prefix for this project (e.g. "user/name")
    pub branch_prefix: Option<String>,

    /// Skip git worktree creation β€” agent works directly in the project root.
    /// Useful when the repo is already an isolated environment (e.g. Docker container).
    pub skip_worktree: Option<bool>,
}

/// Serialise `value` over the TOML already at `path`, keeping everything agtx
/// did not put there.
///
/// The rule: *agtx rewrites the values of keys it knows, never deletes a key it
/// does not recognise, and removes a key it manages when that field becomes
/// unset.* `managed` names the keys that may be removed β€” the optional ones,
/// since a required key is always re-emitted. Everything else in the file
/// survives untouched, formatting and comments included.
///
/// Serialising the struct alone would not do: it emits a pristine document and
/// so drops every comment and unrecognised key the user wrote.
fn write_toml_preserving(path: &Path, value: &impl Serialize, managed: &ManagedKeys) -> Result<()> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)?;
    }

    let mut rendered = toml_edit::ser::to_document(value).context("Failed to serialize config")?;
    // serde renders a nested struct as an *inline* table (`worktree = { .. }`).
    // Normalising to real tables keeps the user's `[worktree]` section on its
    // own lines with its comments, and keeps a fresh file in the documented
    // format.
    expand_inline_tables(rendered.as_table_mut());

    // A file that does not parse cannot be merged into, so start clean. The
    // alternative β€” refusing to save β€” leaves the user unable to fix it from
    // inside agtx.
    let mut doc = std::fs::read_to_string(path)
        .ok()
        .and_then(|text| text.parse::<toml_edit::DocumentMut>().ok())
        .unwrap_or_default();

    merge_table(doc.as_table_mut(), rendered.as_table(), managed);
    std::fs::write(path, doc.to_string())?;
    Ok(())
}

/// Remove `key`, moving any comments above it onto the key that follows.
///
/// A comment belongs to the *next* key's decor, so removing the first key in a
/// file would take the file's header comment with it. Erring toward keeping the
/// user's text leaves a comment that really was about the removed key slightly
/// orphaned, which is visible and fixable where deletion is not.
///
/// A comment above the *last* key in a table has nothing to move onto and is
/// dropped.
fn remove_key_keeping_comments(table: &mut toml_edit::Table, key: &str) {
    if !table.contains_key(key) {
        return;
    }
    let prefix = table
        .key(key)
        .and_then(|k| k.leaf_decor().prefix())
        .and_then(|p| p.as_str())
        .unwrap_or_default()
        .to_string();

    let successor = table
        .iter()
        .map(|(k, _)| k.to_string())
        .skip_while(|k| k != key)
        .nth(1);

    table.remove(key);

    if !prefix.contains('#') {
        return;
    }
    if let Some(next) = successor {
        if let Some(mut next_key) = table.key_mut(&next) {
            let decor = next_key.leaf_decor_mut();
            let existing = decor.prefix().and_then(|p| p.as_str()).unwrap_or("");
            decor.set_prefix(format!("{prefix}{existing}"));
        }
    }
}

/// Turn every inline table into a `[section]`, recursively.
fn expand_inline_tables(table: &mut toml_edit::Table) {
    let inline_keys: Vec<String> = table
        .iter()
        .filter(|(_, item)| item.is_inline_table())
        .map(|(key, _)| key.to_string())
        .collect();
    for key in inline_keys {
        if let Some(item) = table.get_mut(&key) {
            let expanded = std::mem::replace(item, toml_edit::Item::None)
                .into_table()
                .unwrap_or_else(|original| {
                    // Cannot happen for an inline table, but losing the value
                    // would be worse than an odd-looking one.
                    let mut fallback = toml_edit::Table::new();
                    fallback.insert(&key, original);
                    fallback
                });
            *item = toml_edit::Item::Table(expanded);
        }
    }
    for (_, item) in table.iter_mut() {
        if let Some(sub) = item.as_table_mut() {
            expand_inline_tables(sub);
        }
    }
}

/// The keys a writer is allowed to delete, per table. See
/// `write_toml_preserving`.
struct ManagedKeys {
    /// Deletable keys at the top level.
    root: &'static [&'static str],
    /// Deletable keys inside a named sub-table.
    nested: &'static [(&'static str, &'static [&'static str])],
}

impl ManagedKeys {
    fn for_table(&self, table: Option<&str>) -> &'static [&'static str] {
        match table {
            None => self.root,
            Some(name) => self
                .nested
                .iter()
                .find(|(t, _)| *t == name)
                .map(|(_, keys)| *keys)
                .unwrap_or(&[]),
        }
    }
}

fn merge_table(target: &mut toml_edit::Table, source: &toml_edit::Table, managed: &ManagedKeys) {
    merge_table_named(target, source, managed, None);
}

fn merge_table_named(
    target: &mut toml_edit::Table,
    source: &toml_edit::Table,
    managed: &ManagedKeys,
    name: Option<&str>,
) {
    for (key, item) in source.iter() {
        match (
            item.as_table(),
            target.get_mut(key).and_then(|i| i.as_table_mut()),
        ) {
            // Both sides are tables: recurse, so the sub-table's own comments
            // and layout survive too.
            (Some(sub_source), Some(sub_target)) => {
                merge_table_named(sub_target, sub_source, managed, Some(key));
            }
            _ => match target.get_mut(key) {
                // Replacing an existing value keeps the decor around it, which
                // is where a trailing `# comment` on that line lives.
                Some(existing) => {
                    let decor = existing.as_value().map(|v| v.decor().clone());
                    *existing = item.clone();
                    if let (Some(decor), Some(value)) = (decor, existing.as_value_mut()) {
                        *value.decor_mut() = decor;
                    }
                }
                // An empty table is nothing but a header. Writing one into a
                // file that had no `[agents]` only appends noise β€” and appends
                // it *after* whatever sections the user wrote.
                None if item.as_table().is_some_and(|t| t.is_empty()) => {}
                None => {
                    target.insert(key, item.clone());
                }
            },
        }
    }

    // An optional field the user cleared has to actually leave the file.
    for key in managed.for_table(name) {
        if !source.contains_key(key) {
            remove_key_keeping_comments(target, key);
        }
    }

    // Recurse into managed sub-tables the serialization omitted entirely, so a
    // cleared `[agents]` still drops its keys.
    for (table_name, _) in managed.nested {
        if source.contains_key(table_name) {
            continue;
        }
        if let Some(sub) = target.get_mut(table_name).and_then(|i| i.as_table_mut()) {
            for key in managed.for_table(Some(table_name)) {
                remove_key_keeping_comments(sub, key);
            }
        }
    }
}

/// Optional keys on `GlobalConfig`. Everything else it writes is required, so
/// it is always re-emitted and can never need deleting.
const GLOBAL_MANAGED: ManagedKeys = ManagedKeys {
    root: &[],
    nested: &[("agents", &["research", "planning", "running", "review"])],
};

/// `ProjectConfig` is optional all the way down: every field can be cleared.
const PROJECT_MANAGED: ManagedKeys = ManagedKeys {
    root: &[
        // `agents` is itself optional here, so clearing it must drop the whole
        // `[agents]` section rather than leaving an empty header behind.
        "agents",
        "default_agent",
        "base_branch",
        "github_url",
        "worktree_dir",
        "copy_files",
        "init_script",
        "cleanup_script",
        "workflow_plugin",
        "branch_prefix",
        "skip_worktree",
    ],
    nested: &[("agents", &["research", "planning", "running", "review"])],
};

impl GlobalConfig {
    /// Load global config from default location
    pub fn load() -> Result<Self> {
        let config_path = Self::config_path()?;

        if config_path.exists() {
            let content = std::fs::read_to_string(&config_path)
                .with_context(|| format!("Failed to read config from {:?}", config_path))?;
            toml::from_str(&content).context("Failed to parse global config")
        } else {
            Ok(Self::default())
        }
    }

    /// Save global config to its default location, keeping the user's comments
    /// and any keys agtx does not recognise. See `write_toml_preserving`.
    pub fn save(&self) -> Result<()> {
        write_toml_preserving(&Self::config_path()?, self, &GLOBAL_MANAGED)
    }

    /// Get the path to the global config file.
    ///
    /// Always `~/.config/agtx/` on every platform β€” see the config-path split
    /// note in CLAUDE.md. Honours `AGTX_CONFIG_DIR` like `TrustStore::path`, so
    /// a test exercising the writer cannot overwrite the real user's
    /// `config.toml`.
    pub fn config_path() -> Result<PathBuf> {
        if let Ok(dir) = std::env::var("AGTX_CONFIG_DIR") {
            if !dir.is_empty() {
                return Ok(PathBuf::from(dir).join("config.toml"));
            }
        }
        let home = std::env::var("HOME").context("Could not determine home directory")?;
        Ok(PathBuf::from(home)
            .join(".config")
            .join("agtx")
            .join("config.toml"))
    }

    /// Get the path to the global data directory
    ///
    /// Honours `AGTX_DATA_DIR` like `Database::data_root`, so a test or smoke run
    /// that redirects the databases also redirects the first-run probe that looks
    /// for `index.db` beside them.
    pub fn data_dir() -> Result<PathBuf> {
        if let Ok(dir) = std::env::var("AGTX_DATA_DIR") {
            if !dir.is_empty() {
                return Ok(PathBuf::from(dir));
            }
        }
        let dirs = directories::ProjectDirs::from("", "", "agtx")
            .context("Could not determine data directory")?;
        Ok(dirs.data_dir().to_path_buf())
    }
}

impl ProjectConfig {
    /// Load project config from a project directory
    pub fn load(project_path: &Path) -> Result<Self> {
        let config_path = project_path.join(".agtx").join("config.toml");

        if config_path.exists() {
            let content = std::fs::read_to_string(&config_path)
                .with_context(|| format!("Failed to read config from {:?}", config_path))?;
            toml::from_str(&content).context("Failed to parse project config")
        } else {
            Ok(Self::default())
        }
    }

    /// Save project config, keeping the user's comments and any keys agtx does
    /// not recognise. See `write_toml_preserving`.
    ///
    /// Note this invalidates the project's trust hash β€” see
    /// `TrustStore::retrust_after_agtx_write`, which every in-agtx caller of
    /// this must go through.
    pub fn save(&self, project_path: &Path) -> Result<()> {
        let config_path = project_path.join(".agtx").join("config.toml");
        write_toml_preserving(&config_path, self, &PROJECT_MANAGED)
    }
}

/// Action to take on first run based on config/data state.
#[derive(Debug, PartialEq)]
pub enum FirstRunAction {
    /// Config file already exists β€” nothing to do
    ConfigExists,
    /// Old config was found and migrated to new location
    Migrated,
    /// Existing user (has database) but no config file β€” save defaults silently
    ExistingUserSaveDefaults,
    /// New user β€” prompt for agent selection
    NewUserPrompt,
}

/// Determine what first-run action to take.
/// Pure logic β€” no side effects β€” so it's easily testable.
pub fn determine_first_run_action(
    config_exists: bool,
    migrated: bool,
    db_exists: bool,
) -> FirstRunAction {
    if config_exists {
        return FirstRunAction::ConfigExists;
    }
    if migrated {
        return FirstRunAction::Migrated;
    }
    if db_exists {
        return FirstRunAction::ExistingUserSaveDefaults;
    }
    FirstRunAction::NewUserPrompt
}

/// Merged configuration (global + project)
#[derive(Debug, Clone)]
pub struct MergedConfig {
    pub default_agent: String,
    pub phase_agents: PhaseAgentsConfig,
    pub worktree_enabled: bool,
    pub skip_worktree: bool,
    pub auto_cleanup: bool,
    pub base_branch: String,
    pub worktree_dir: String,
    pub github_url: Option<String>,
    pub theme: ThemeConfig,
    pub copy_files: Option<String>,
    pub init_script: Option<String>,
    pub cleanup_script: Option<String>,
    pub workflow_plugin: Option<String>,
    pub fullscreen_on_enter: bool,
    pub branch_prefix: String,
    pub agent_hooks: bool,
    pub auto_trust: bool,
    /// Global-only: a project does not get to decide whether the user is told
    /// about agtx releases.
    pub update_check: bool,
}

impl MergedConfig {
    /// Create merged config from global and project configs
    pub fn merge(global: &GlobalConfig, project: &ProjectConfig) -> Self {
        let project_agents = project.agents.clone().unwrap_or_default();
        Self {
            default_agent: project
                .default_agent
                .clone()
                .unwrap_or_else(|| global.default_agent.clone()),
            phase_agents: PhaseAgentsConfig {
                research: project_agents.research.or(global.agents.research.clone()),
                planning: project_agents.planning.or(global.agents.planning.clone()),
                running: project_agents.running.or(global.agents.running.clone()),
                review: project_agents.review.or(global.agents.review.clone()),
            },
            worktree_enabled: global.worktree.enabled,
            skip_worktree: project.skip_worktree.unwrap_or(!global.worktree.enabled),
            auto_cleanup: global.worktree.auto_cleanup,
            base_branch: project
                .base_branch
                .clone()
                .unwrap_or_else(|| global.worktree.base_branch.clone()),
            worktree_dir: project
                .worktree_dir
                .clone()
                .unwrap_or_else(|| global.worktree.worktree_dir.clone()),
            github_url: project.github_url.clone(),
            theme: global.theme.clone(),
            copy_files: project.copy_files.clone(),
            init_script: project.init_script.clone(),
            cleanup_script: project.cleanup_script.clone(),
            workflow_plugin: project.workflow_plugin.clone(),
            fullscreen_on_enter: global.fullscreen_on_enter,
            agent_hooks: global.agent_hooks,
            auto_trust: global.auto_trust,
            update_check: global.update_check,
            branch_prefix: project
                .branch_prefix
                .clone()
                .unwrap_or_else(|| global.worktree.branch_prefix.clone()),
        }
    }

    /// Get the agent name for a given phase.
    /// Falls back to default_agent if no phase-specific override is set.
    pub fn agent_for_phase(&self, phase: &str) -> &str {
        self.explicit_agent_for_phase(phase)
            .unwrap_or(&self.default_agent)
    }

    /// Get the explicitly configured agent for a phase, if any.
    /// Returns None when no phase-specific override is set (no fallback).
    pub fn explicit_agent_for_phase(&self, phase: &str) -> Option<&str> {
        match phase {
            "research" => self.phase_agents.research.as_deref(),
            "planning" | "planning_with_research" => self.phase_agents.planning.as_deref(),
            "running" | "running_with_research_or_planning" => self.phase_agents.running.as_deref(),
            "review" => self.phase_agents.review.as_deref(),
            _ => None,
        }
    }
}

/// Workflow plugin configuration loaded from plugin.toml
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkflowPlugin {
    pub name: String,
    pub description: Option<String>,
    pub init_script: Option<String>,
    /// List of supported agent names (e.g. ["claude", "codex", "gemini", "opencode"]).
    /// If empty or omitted, all agents are assumed supported.
    #[serde(default)]
    pub supported_agents: Vec<String>,
    #[serde(default)]
    pub artifacts: PluginArtifacts,
    #[serde(default)]
    pub commands: PluginCommands,
    #[serde(default)]
    pub prompts: PluginPrompts,
    #[serde(default)]
    pub prompt_triggers: PluginPromptTriggers,
    /// Extra directories to copy from project root to worktrees (e.g. [".specify"]).
    #[serde(default)]
    pub copy_dirs: Vec<String>,
    /// Individual files to copy from project root to worktrees (e.g. ["PROJECT.md"]).
    /// Merged with project-level copy_files during worktree setup.
    #[serde(default)]
    pub copy_files: Vec<String>,
    /// When true, enables Review β†’ Planning transition for multi-phase workflows.
    #[serde(default)]
    pub cyclic: bool,
    /// When true, send a "clear context" command (agent-specific) before the
    /// phase skill and prompt on phase transitions. Currently honored only for
    /// Claude Code (`/clear`); other agents fall through to normal send.
    #[serde(default)]
    pub clear_context_on_advance: bool,
    /// Files/dirs to copy from worktree back to project root after a phase completes.
    /// Keyed by phase name (e.g. { research = ["PROJECT.md", ".planning"] }).
    #[serde(default)]
    pub copy_back: std::collections::HashMap<String, Vec<String>>,
    /// Auto-dismiss rules for interactive prompts that appear before the prompt trigger.
    /// Each rule specifies patterns to detect and keystrokes to send in response.
    #[serde(default)]
    pub auto_dismiss: Vec<AutoDismiss>,
}

/// Rule for auto-dismissing interactive prompts in the tmux pane.
/// When all `detect` patterns are present in the pane content (AND logic),
/// the `response` keystrokes are sent automatically.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct AutoDismiss {
    /// All patterns must be present in pane content for the rule to trigger.
    pub detect: Vec<String>,
    /// Newline-separated keystrokes to send (e.g. "2\nEnter").
    pub response: String,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginArtifacts {
    #[serde(default)]
    pub preresearch: Vec<String>,
    pub research: Option<String>,
    pub planning: Option<String>,
    pub running: Option<String>,
    pub review: Option<String>,
}

/// Slash commands to invoke per phase (sent via tmux send_keys as real interactive commands).
/// e.g. "/gsd:plan-phase 1" or "/speckit.plan"
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginCommands {
    /// Command to run before research artifacts exist (e.g. "/gsd:new-project").
    /// Used only when no research artifacts are found in the project root.
    /// Falls back to `research` if not set.
    pub preresearch: Option<String>,
    pub research: Option<String>,
    pub planning: Option<String>,
    pub running: Option<String>,
    pub review: Option<String>,
}

/// Task content prompts per phase (sent after the command).
/// Should contain just the task description, not slash commands.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginPrompts {
    pub research: Option<String>,
    pub planning: Option<String>,
    pub planning_with_research: Option<String>,
    pub running: Option<String>,
    /// Prompt for Running after research or planning. Usually empty β€” prior phase provides context.
    pub running_with_research_or_planning: Option<String>,
    pub review: Option<String>,
}

/// Text patterns to wait for before sending the prompt for each phase.
/// When set, the system polls the tmux pane for this text before sending the prompt.
/// Useful for interactive commands like /gsd:new-project that ask questions.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginPromptTriggers {
    pub research: Option<String>,
    pub planning: Option<String>,
    pub running: Option<String>,
    pub review: Option<String>,
}

impl WorkflowPlugin {
    /// Check if a phase's command or prompt contains `{task}`, meaning the phase
    /// can receive task context directly and can be entered from Backlog.
    /// If neither command nor prompt has `{task}`, the phase depends on a prior phase.
    /// If no command AND no prompt exist at all (e.g. void plugin), the phase is ungated.
    pub fn phase_accepts_task(&self, phase: &str) -> bool {
        let cmd = match phase {
            "planning" => self.commands.planning.as_deref(),
            "running" => self.commands.running.as_deref(),
            _ => None,
        };

        let prompt = match phase {
            "planning" => self.prompts.planning.as_deref(),
            "running" => self.prompts.running.as_deref(),
            _ => None,
        };

        // No command and no prompt β†’ ungated (e.g. void plugin)
        if cmd.is_none() && prompt.is_none() {
            return true;
        }

        cmd.map_or(false, |c| c.contains("{task}") || c.contains("{task_id}"))
            || prompt.map_or(false, |p| p.contains("{task}") || p.contains("{task_id}"))
    }

    /// Check if the given agent is supported by this plugin.
    /// Returns true if supported_agents is empty (all agents allowed) or contains the agent.
    pub fn supports_agent(&self, agent_name: &str) -> bool {
        self.supported_agents.is_empty() || self.supported_agents.iter().any(|a| a == agent_name)
    }

    /// Validate that a plugin name is safe for use in filesystem paths.
    /// Rejects names containing path separators, traversal sequences, or
    /// characters outside [a-zA-Z0-9_-].
    pub fn validate_plugin_name(name: &str) -> Result<()> {
        if name.is_empty() {
            anyhow::bail!("Plugin name must not be empty");
        }
        if name.contains('.') || name.contains('/') || name.contains('\\') {
            anyhow::bail!(
                "Plugin name '{}' contains invalid characters (., /, \\)",
                name
            );
        }
        if !name
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
        {
            anyhow::bail!(
                "Plugin name '{}' contains invalid characters (only a-z, A-Z, 0-9, -, _ allowed)",
                name
            );
        }
        Ok(())
    }

    /// Directory holding global (user-level) plugins: `~/.config/agtx/plugins`.
    pub fn global_plugins_dir() -> Option<PathBuf> {
        let home = std::env::var("HOME").ok()?;
        Some(
            PathBuf::from(home)
                .join(".config")
                .join("agtx")
                .join("plugins"),
        )
    }

    /// Directory holding a project's local plugins: `{project}/.agtx/plugins`.
    pub fn project_plugins_dir(project_path: &Path) -> PathBuf {
        project_path.join(".agtx").join("plugins")
    }

    /// Load a plugin by name, checking project-local then global directories
    pub fn load(name: &str, project_path: Option<&Path>) -> Result<Self> {
        Self::validate_plugin_name(name)?;
        // 1. Check project-local
        if let Some(pp) = project_path {
            let local_path = Self::project_plugins_dir(pp).join(name).join("plugin.toml");
            if local_path.exists() {
                let content = std::fs::read_to_string(&local_path)?;
                return toml::from_str(&content).context("Failed to parse plugin.toml");
            }
        }
        // 2. Check global
        let global_path = Self::global_plugins_dir()
            .context("Could not determine home directory")?
            .join(name)
            .join("plugin.toml");
        if global_path.exists() {
            let content = std::fs::read_to_string(&global_path)?;
            return toml::from_str(&content).context("Failed to parse plugin.toml");
        }
        anyhow::bail!("Plugin '{}' not found", name)
    }

    /// Get the plugin directory path (for reading skill files)
    pub fn plugin_dir(name: &str, project_path: Option<&Path>) -> Option<PathBuf> {
        if Self::validate_plugin_name(name).is_err() {
            return None;
        }
        // Same lookup order: project-local first, then global
        if let Some(pp) = project_path {
            let local = Self::project_plugins_dir(pp).join(name);
            if local.join("plugin.toml").exists() {
                return Some(local);
            }
        }
        let global = Self::global_plugins_dir()?.join(name);
        if global.join("plugin.toml").exists() {
            return Some(global);
        }
        None
    }
}

/// Trust-on-first-use store for project configs.
///
/// Tracks SHA-256 hashes of `.agtx/config.toml` contents keyed by canonical project path.
/// When a project's config hash doesn't match the stored value, dangerous fields
/// (`init_script`, `copy_files`) are suppressed until the user explicitly trusts the project.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct TrustStore {
    #[serde(default)]
    pub projects: std::collections::HashMap<String, String>,
}

impl TrustStore {
    /// Load the trust store from the platform config directory (e.g. `~/.config/agtx/trusted_projects.toml` on Linux, `~/Library/Application Support/agtx/` on macOS).
    pub fn load() -> Result<Self> {
        let path = Self::path()?;
        if path.exists() {
            let content = std::fs::read_to_string(&path)?;
            Ok(toml::from_str(&content)?)
        } else {
            Ok(Self::default())
        }
    }

    /// Persist the trust store to disk.
    pub fn save(&self) -> Result<()> {
        let path = Self::path()?;
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        std::fs::write(&path, toml::to_string_pretty(self)?)?;
        Ok(())
    }

    /// Where `trusted_projects.toml` lives.
    ///
    /// Honours `AGTX_CONFIG_DIR` like `Database::data_root` honours
    /// `AGTX_DATA_DIR`: `App::new` reads this store and several paths write it,
    /// so without a redirect the test suite would append temp-dir entries to
    /// the real user's file.
    fn path() -> Result<PathBuf> {
        if let Ok(dir) = std::env::var("AGTX_CONFIG_DIR") {
            if !dir.is_empty() {
                return Ok(PathBuf::from(dir).join("trusted_projects.toml"));
            }
        }
        let dirs = directories::ProjectDirs::from("", "", "agtx")
            .context("Could not determine config directory")?;
        Ok(dirs.config_dir().join("trusted_projects.toml"))
    }

    /// Compute SHA-256 of a project's `.agtx/config.toml` content.
    pub fn hash_config(project_path: &Path) -> Option<String> {
        let config_path = project_path.join(".agtx").join("config.toml");
        let content = std::fs::read(&config_path).ok()?;
        use sha2::{Digest, Sha256};
        let hash = Sha256::digest(&content);
        Some(format!("{:x}", hash))
    }

    /// Check if a project's config is trusted (hash matches stored value).
    pub fn is_trusted(&self, project_path: &Path) -> bool {
        let canonical = project_path
            .canonicalize()
            .unwrap_or_else(|_| project_path.to_path_buf());
        let key = canonical.to_string_lossy().to_string();
        match (self.projects.get(&key), Self::hash_config(project_path)) {
            (Some(stored), Some(current)) => stored == &current,
            (None, None) => true, // No .agtx/config.toml β€” nothing to distrust
            _ => false,
        }
    }

    /// Mark a project's current config as trusted.
    pub fn trust_project(&mut self, project_path: &Path) -> Result<()> {
        let canonical = project_path
            .canonicalize()
            .unwrap_or_else(|_| project_path.to_path_buf());
        let key = canonical.to_string_lossy().to_string();
        if let Some(hash) = Self::hash_config(project_path) {
            self.projects.insert(key, hash);
            self.save()?;
        }
        Ok(())
    }

    /// Re-record trust after **agtx itself** rewrote `.agtx/config.toml`.
    ///
    /// Trust is a hash of that file, so every write agtx makes on the user's
    /// behalf invalidates it: the project would show the untrusted banner on
    /// the next launch and silently lose its `init_script`, `cleanup_script`
    /// and `copy_files` β€” over a change the user made in agtx's own UI, to a
    /// field (`workflow_plugin`) that is not one of the dangerous three.
    ///
    /// `was_trusted` is the state read *before* the write, and it is the whole
    /// safety of this: a project the user has never approved must not become
    /// trusted just because agtx touched its config, or an `init_script` they
    /// never vouched for starts running on the next worktree. This restores a
    /// prior decision; it never makes one.
    pub fn retrust_after_agtx_write(project_path: &Path, was_trusted: bool) -> Result<()> {
        if !was_trusted {
            return Ok(());
        }
        let mut store = Self::load()?;
        store.trust_project(project_path)
    }
}

#[cfg(test)]
mod managed_keys_tests {
    use super::*;

    /// The managed-key lists say what a save may *delete*. A field missing from
    /// them survives being cleared: the value goes on living in the file after
    /// the user removed it.
    ///
    /// Both literals below are exhaustive on purpose, so adding a field to the
    /// struct fails to compile here until someone has looked at this list.
    #[test]
    fn project_managed_keys_covers_every_optional_field() {
        let config = ProjectConfig {
            default_agent: Some("claude".into()),
            agents: Some(PhaseAgentsConfig {
                research: Some("claude".into()),
                planning: Some("claude".into()),
                running: Some("codex".into()),
                review: Some("claude".into()),
            }),
            base_branch: Some("main".into()),
            github_url: Some("https://example.invalid".into()),
            worktree_dir: Some(".agtx/worktrees".into()),
            copy_files: Some(".env".into()),
            init_script: Some("true".into()),
            cleanup_script: Some("true".into()),
            workflow_plugin: Some("gsd".into()),
            branch_prefix: Some("task".into()),
            skip_worktree: Some(false),
        };
        let mut doc = toml_edit::ser::to_document(&config).unwrap();
        // The writer expands inline tables before merging, so the guard has to
        // look at the same shape it will.
        expand_inline_tables(doc.as_table_mut());
        for (key, item) in doc.as_table().iter() {
            if item.is_table() {
                // Sub-tables need both: `nested` so their own keys can be
                // cleared, and `root` when the whole section is optional.
                assert!(
                    PROJECT_MANAGED.nested.iter().any(|(t, _)| *t == key),
                    "sub-table `{key}` is not in PROJECT_MANAGED.nested"
                );
            }
            assert!(
                PROJECT_MANAGED.root.contains(&key),
                "`{key}` can be cleared but PROJECT_MANAGED would not remove it"
            );
        }

        let agents = doc["agents"].as_table().unwrap();
        for (key, _) in agents.iter() {
            assert!(
                PROJECT_MANAGED.for_table(Some("agents")).contains(&key),
                "`agents.{key}` can be cleared but would not be removed"
            );
        }
    }

    /// `GlobalConfig`'s only optional fields are the four phase agents; every
    /// other key is required and therefore always re-emitted.
    #[test]
    fn global_managed_keys_covers_the_phase_agents() {
        let agents = PhaseAgentsConfig {
            research: Some("claude".into()),
            planning: Some("claude".into()),
            running: Some("codex".into()),
            review: Some("claude".into()),
        };
        let mut doc = toml_edit::ser::to_document(&agents).unwrap();
        expand_inline_tables(doc.as_table_mut());
        for (key, _) in doc.as_table().iter() {
            assert!(
                GLOBAL_MANAGED.for_table(Some("agents")).contains(&key),
                "`agents.{key}` can be cleared but would not be removed"
            );
        }
    }
}