claude-team-mcp 0.6.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

claude_team_mcp/config.py

@@ -0,0 +1,350 @@
+"""
+Configuration loading for Claude Team MCP.
+
+Defines dataclasses for the config schema and utilities for loading
+and validating JSON config files.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Literal
+
+CONFIG_VERSION = 1
+CONFIG_DIR = Path.home() / ".claude-team"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+AgentType = Literal["claude", "codex"]
+LayoutMode = Literal["auto", "new"]
+TerminalBackend = Literal["iterm", "tmux"]
+IssueTrackerName = Literal["beads", "pebbles"]
+
+
+class ConfigError(ValueError):
+    """Raised when the configuration file is invalid."""
+
+
+@dataclass
+class CommandsConfig:
+    """CLI command overrides for supported agent backends."""
+
+    claude: str | None = None
+    codex: str | None = None
+
+
+@dataclass
+class DefaultsConfig:
+    """Default values applied when spawn_workers fields are omitted."""
+
+    agent_type: AgentType = "claude"
+    skip_permissions: bool = False
+    use_worktree: bool = True
+    layout: LayoutMode = "auto"
+
+
+@dataclass
+class TerminalConfig:
+    """Terminal backend configuration."""
+
+    backend: TerminalBackend | None = None  # None = auto-detect
+
+
+@dataclass
+class EventsConfig:
+    """Event log rotation configuration."""
+
+    max_size_mb: int = 1
+    recent_hours: int = 24
+
+
+@dataclass
+class IssueTrackerConfig:
+    """Issue tracker configuration overrides."""
+
+    override: IssueTrackerName | None = None
+
+
+@dataclass
+class ClaudeTeamConfig:
+    """Top-level configuration container for claude-team."""
+
+    version: int = CONFIG_VERSION
+    commands: CommandsConfig = field(default_factory=CommandsConfig)
+    defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
+    terminal: TerminalConfig = field(default_factory=TerminalConfig)
+    events: EventsConfig = field(default_factory=EventsConfig)
+    issue_tracker: IssueTrackerConfig = field(default_factory=IssueTrackerConfig)
+
+
+def default_config() -> ClaudeTeamConfig:
+    """Return a new config instance with default values."""
+
+    return ClaudeTeamConfig()
+
+
+def load_config(config_path: Path | None = None) -> ClaudeTeamConfig:
+    """Load config from disk, creating defaults if missing."""
+
+    path = _resolve_config_path(config_path)
+    if not path.exists():
+        return default_config()
+
+    data = _read_json(path)
+    return _parse_config(data)
+
+
+def parse_config(data: dict) -> ClaudeTeamConfig:
+    """Parse and validate a config dictionary."""
+
+    return _parse_config(data)
+
+
+def save_config(config: ClaudeTeamConfig, config_path: Path | None = None) -> Path:
+    """Persist config to disk and return the path written."""
+
+    path = _resolve_config_path(config_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(asdict(config), indent=2, sort_keys=True)
+    path.write_text(payload + "\n")
+    return path
+
+
+def _resolve_config_path(config_path: Path | None) -> Path:
+    # Resolve the config path, using the default location if needed.
+    return (config_path or CONFIG_PATH).expanduser()
+
+
+def _read_json(path: Path) -> dict:
+    # Read the file contents first so we can surface IO errors cleanly.
+    try:
+        raw = path.read_text()
+    except OSError as exc:
+        raise ConfigError(f"Unable to read config file: {path}") from exc
+
+    # Decode JSON and enforce an object payload.
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Invalid JSON in config file: {path}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError("Config file must contain a JSON object")
+
+    return data
+
+
+def _parse_config(data: dict) -> ClaudeTeamConfig:
+    # Validate expected top-level keys before parsing sections.
+    _validate_keys(
+        data,
+        {"version", "commands", "defaults", "terminal", "events", "issue_tracker"},
+        "config",
+    )
+    version = _read_version(data.get("version"))
+    commands = _parse_commands(data.get("commands"))
+    defaults = _parse_defaults(data.get("defaults"))
+    terminal = _parse_terminal(data.get("terminal"))
+    events = _parse_events(data.get("events"))
+    issue_tracker = _parse_issue_tracker(data.get("issue_tracker"))
+    return ClaudeTeamConfig(
+        version=version,
+        commands=commands,
+        defaults=defaults,
+        terminal=terminal,
+        events=events,
+        issue_tracker=issue_tracker,
+    )
+
+
+def _read_version(value: object) -> int:
+    # Allow missing versions for backward compatibility with early configs.
+    if value is None:
+        return CONFIG_VERSION
+    if not isinstance(value, int):
+        raise ConfigError("config.version must be an integer")
+    if value != CONFIG_VERSION:
+        raise ConfigError(
+            f"Unsupported config version {value}; expected {CONFIG_VERSION}"
+        )
+    return value
+
+
+def _parse_commands(value: object) -> CommandsConfig:
+    # Parse CLI command overrides for each backend.
+    data = _ensure_dict(value, "commands")
+    _validate_keys(data, {"claude", "codex"}, "commands")
+    return CommandsConfig(
+        claude=_optional_str(data.get("claude"), "commands.claude"),
+        codex=_optional_str(data.get("codex"), "commands.codex"),
+    )
+
+
+def _parse_defaults(value: object) -> DefaultsConfig:
+    # Parse default spawn_workers fields with explicit validation.
+    data = _ensure_dict(value, "defaults")
+    _validate_keys(
+        data,
+        {"agent_type", "skip_permissions", "use_worktree", "layout"},
+        "defaults",
+    )
+    return DefaultsConfig(
+        agent_type=_optional_literal(
+            data.get("agent_type"),
+            {"claude", "codex"},
+            "defaults.agent_type",
+            DefaultsConfig.agent_type,
+        ),
+        skip_permissions=_optional_bool(
+            data.get("skip_permissions"),
+            "defaults.skip_permissions",
+            DefaultsConfig.skip_permissions,
+        ),
+        use_worktree=_optional_bool(
+            data.get("use_worktree"),
+            "defaults.use_worktree",
+            DefaultsConfig.use_worktree,
+        ),
+        layout=_optional_literal(
+            data.get("layout"),
+            {"auto", "new"},
+            "defaults.layout",
+            DefaultsConfig.layout,
+        ),
+    )
+
+
+def _parse_terminal(value: object) -> TerminalConfig:
+    # Parse terminal backend configuration.
+    data = _ensure_dict(value, "terminal")
+    _validate_keys(data, {"backend"}, "terminal")
+    return TerminalConfig(
+        backend=_optional_literal(
+            data.get("backend"),
+            {"iterm", "tmux"},
+            "terminal.backend",
+            None,
+        ),
+    )
+
+
+def _parse_events(value: object) -> EventsConfig:
+    # Parse event log rotation configuration.
+    data = _ensure_dict(value, "events")
+    _validate_keys(data, {"max_size_mb", "recent_hours"}, "events")
+    return EventsConfig(
+        max_size_mb=_optional_int(
+            data.get("max_size_mb"),
+            "events.max_size_mb",
+            EventsConfig.max_size_mb,
+            min_value=1,
+        ),
+        recent_hours=_optional_int(
+            data.get("recent_hours"),
+            "events.recent_hours",
+            EventsConfig.recent_hours,
+            min_value=0,
+        ),
+    )
+
+
+def _parse_issue_tracker(value: object) -> IssueTrackerConfig:
+    # Parse issue tracker overrides.
+    data = _ensure_dict(value, "issue_tracker")
+    _validate_keys(data, {"override"}, "issue_tracker")
+    return IssueTrackerConfig(
+        override=_optional_literal(
+            data.get("override"),
+            {"beads", "pebbles"},
+            "issue_tracker.override",
+            None,
+        )
+    )
+
+
+def _ensure_dict(value: object, path: str) -> dict:
+    # Ensure sections are JSON objects, defaulting to empty dicts.
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"{path} must be a JSON object")
+    return value
+
+
+def _validate_keys(data: dict, allowed: set[str], path: str) -> None:
+    # Reject unexpected keys for a config section.
+    unknown = set(data.keys()) - allowed
+    if unknown:
+        joined = ", ".join(sorted(unknown))
+        raise ConfigError(f"Unknown keys in {path}: {joined}")
+
+
+def _optional_str(value: object, path: str) -> str | None:
+    # Validate optional string fields.
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(f"{path} must be a string")
+    if not value.strip():
+        raise ConfigError(f"{path} cannot be empty")
+    return value
+
+
+def _optional_int(value: object, path: str, default: int, min_value: int = 1) -> int:
+    # Validate optional integer fields.
+    if value is None:
+        return default
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ConfigError(f"{path} must be an integer")
+    if value < min_value:
+        raise ConfigError(f"{path} must be at least {min_value}")
+    return value
+
+
+def _optional_bool(value: object, path: str, default: bool) -> bool:
+    # Validate optional boolean fields.
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        raise ConfigError(f"{path} must be a boolean")
+    return value
+
+
+def _optional_literal(
+    value: object,
+    allowed: set[str],
+    path: str,
+    default: str | None,
+) -> str | None:
+    # Validate optional string fields constrained to allowed values.
+    if value is None:
+        return default
+    if not isinstance(value, str):
+        raise ConfigError(f"{path} must be a string")
+    if value not in allowed:
+        joined = ", ".join(sorted(allowed))
+        raise ConfigError(f"{path} must be one of: {joined}")
+    return value
+
+
+__all__ = [
+    "AgentType",
+    "ClaudeTeamConfig",
+    "CommandsConfig",
+    "ConfigError",
+    "DefaultsConfig",
+    "EventsConfig",
+    "IssueTrackerConfig",
+    "LayoutMode",
+    "TerminalBackend",
+    "TerminalConfig",
+    "IssueTrackerName",
+    "CONFIG_DIR",
+    "CONFIG_PATH",
+    "CONFIG_VERSION",
+    "default_config",
+    "load_config",
+    "parse_config",
+    "save_config",
+]

claude_team_mcp/config_cli.py

@@ -0,0 +1,263 @@
+"""
+CLI helpers for claude-team configuration commands.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+from collections.abc import Callable, Mapping
+
+from . import config as config_module
+from .config import ClaudeTeamConfig, ConfigError, parse_config
+
+_ALLOWED_AGENT_TYPES = {"claude", "codex"}
+_ALLOWED_LAYOUTS = {"auto", "new"}
+_ALLOWED_TERMINAL_BACKENDS = {"iterm", "tmux"}
+_ALLOWED_ISSUE_TRACKERS = {"beads", "pebbles"}
+
+
+def init_config(
+    *,
+    force: bool = False,
+    config_path: Path | None = None,
+) -> Path:
+    """Write the default config file to disk and return the path."""
+
+    path = _resolve_config_path(config_path)
+    if path.exists() and not force:
+        raise ConfigError(f"Config file already exists: {path}")
+    config = config_module.default_config()
+    return config_module.save_config(config, path)
+
+
+def load_effective_config_data(
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+) -> dict:
+    """Load config data with environment overrides applied."""
+
+    config = config_module.load_config(config_path)
+    data = asdict(config)
+    _apply_env_overrides(data, env or os.environ)
+    return data
+
+
+def render_config_json(
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+) -> str:
+    """Render the effective config as formatted JSON."""
+
+    data = load_effective_config_data(env=env, config_path=config_path)
+    return json.dumps(data, indent=2, sort_keys=True)
+
+
+def get_config_value(
+    key: str,
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+) -> object:
+    """Return a single config value by dotted path."""
+
+    data = load_effective_config_data(env=env, config_path=config_path)
+    return _get_nested_value(data, key)
+
+
+def set_config_value(
+    key: str,
+    raw_value: str,
+    *,
+    config_path: Path | None = None,
+) -> ClaudeTeamConfig:
+    """Set a config value by dotted path, validate, and persist."""
+
+    config = config_module.load_config(config_path)
+    data = asdict(config)
+    parsed_value = _parse_cli_value(key, raw_value)
+    _set_nested_value(data, key, parsed_value)
+    updated = parse_config(data)
+    config_module.save_config(updated, _resolve_config_path(config_path))
+    return updated
+
+
+def format_value_json(value: object) -> str:
+    """Format a single config value as JSON."""
+
+    return json.dumps(value)
+
+
+def _resolve_config_path(config_path: Path | None) -> Path:
+    # Resolve the config path, defaulting to ~/.claude-team/config.json.
+    return (config_path or config_module.CONFIG_PATH).expanduser()
+
+
+def _apply_env_overrides(data: dict, env: Mapping[str, str]) -> None:
+    # Apply env overrides using the same precedence logic as runtime helpers.
+    command_override = env.get("CLAUDE_TEAM_COMMAND")
+    if command_override:
+        data["commands"]["claude"] = command_override
+
+    codex_override = env.get("CLAUDE_TEAM_CODEX_COMMAND")
+    if codex_override:
+        data["commands"]["codex"] = codex_override
+
+    # Terminal backend is a direct override (mirrors select_backend_id).
+    backend_override = env.get("CLAUDE_TEAM_TERMINAL_BACKEND")
+    if backend_override:
+        data["terminal"]["backend"] = backend_override.strip().lower()
+
+    # Issue tracker override mirrors detect_issue_tracker validation.
+    tracker_override = env.get("CLAUDE_TEAM_ISSUE_TRACKER")
+    if tracker_override:
+        normalized = tracker_override.strip().lower()
+        if normalized in _ALLOWED_ISSUE_TRACKERS:
+            data["issue_tracker"]["override"] = normalized
+
+    # Events overrides use integer parsing with graceful fallback.
+    max_size_override = env.get("CLAUDE_TEAM_EVENTS_MAX_SIZE_MB")
+    if max_size_override:
+        parsed = _parse_int_override(max_size_override)
+        if parsed is not None:
+            data["events"]["max_size_mb"] = parsed
+
+    recent_hours_override = env.get("CLAUDE_TEAM_EVENTS_RECENT_HOURS")
+    if recent_hours_override:
+        parsed = _parse_int_override(recent_hours_override)
+        if parsed is not None:
+            data["events"]["recent_hours"] = parsed
+
+
+def _parse_int_override(raw_value: str) -> int | None:
+    # Parse env overrides as integers; invalid values are ignored.
+    try:
+        return int(raw_value)
+    except ValueError:
+        return None
+
+
+def _parse_cli_value(key: str, raw_value: str) -> object:
+    # Parse CLI values according to the config schema.
+    parser = _FIELD_PARSERS.get(key)
+    if parser is None:
+        raise ConfigError(f"Unknown config key: {key}")
+    return parser(raw_value, key)
+
+
+def _parse_optional_string(raw_value: str, field: str) -> str | None:
+    # Parse optional string fields (allows null).
+    if _is_null(raw_value):
+        return None
+    if not raw_value.strip():
+        raise ConfigError(f"{field} cannot be empty")
+    return raw_value
+
+
+def _parse_bool(raw_value: str, field: str) -> bool:
+    # Parse boolean values in JSON-compatible form.
+    normalized = raw_value.strip().lower()
+    if normalized == "true":
+        return True
+    if normalized == "false":
+        return False
+    raise ConfigError(f"{field} must be a boolean")
+
+
+def _parse_int(raw_value: str, field: str) -> int:
+    # Parse integer values with minimum validation.
+    try:
+        value = int(raw_value.strip())
+    except ValueError as exc:
+        raise ConfigError(f"{field} must be an integer") from exc
+    if value < 1:
+        raise ConfigError(f"{field} must be at least 1")
+    return value
+
+
+def _parse_literal(raw_value: str, field: str, allowed: set[str]) -> str:
+    # Parse literal string values constrained to allowed sets.
+    value = raw_value.strip()
+    if value not in allowed:
+        joined = ", ".join(sorted(allowed))
+        raise ConfigError(f"{field} must be one of: {joined}")
+    return value
+
+
+def _parse_optional_literal(
+    raw_value: str,
+    field: str,
+    allowed: set[str],
+) -> str | None:
+    # Parse nullable literal values constrained to allowed sets.
+    if _is_null(raw_value):
+        return None
+    return _parse_literal(raw_value, field, allowed)
+
+
+def _is_null(raw_value: str) -> bool:
+    # Treat "null" as a request to clear optional fields.
+    return raw_value.strip().lower() == "null"
+
+
+def _get_nested_value(data: dict, key: str) -> object:
+    # Retrieve values by dotted path, validating against known keys.
+    if key not in _GET_KEYS:
+        raise ConfigError(f"Unknown config key: {key}")
+    parts = key.split(".")
+    current: object = data
+    for part in parts:
+        if not isinstance(current, dict) or part not in current:
+            raise ConfigError(f"Unknown config key: {key}")
+        current = current[part]
+    return current
+
+
+def _set_nested_value(data: dict, key: str, value: object) -> None:
+    # Assign values by dotted path, ensuring the key exists.
+    parts = key.split(".")
+    current: dict = data
+    for part in parts[:-1]:
+        if part not in current or not isinstance(current[part], dict):
+            raise ConfigError(f"Unknown config key: {key}")
+        current = current[part]
+    leaf = parts[-1]
+    if leaf not in current:
+        raise ConfigError(f"Unknown config key: {key}")
+    current[leaf] = value
+
+
+_FIELD_PARSERS: dict[str, Callable[[str, str], object]] = {
+    "commands.claude": _parse_optional_string,
+    "commands.codex": _parse_optional_string,
+    "defaults.agent_type": lambda value, field: _parse_literal(
+        value,
+        field,
+        _ALLOWED_AGENT_TYPES,
+    ),
+    "defaults.skip_permissions": _parse_bool,
+    "defaults.use_worktree": _parse_bool,
+    "defaults.layout": lambda value, field: _parse_literal(
+        value,
+        field,
+        _ALLOWED_LAYOUTS,
+    ),
+    "terminal.backend": lambda value, field: _parse_optional_literal(
+        value,
+        field,
+        _ALLOWED_TERMINAL_BACKENDS,
+    ),
+    "events.max_size_mb": _parse_int,
+    "events.recent_hours": _parse_int,
+    "issue_tracker.override": lambda value, field: _parse_optional_literal(
+        value,
+        field,
+        _ALLOWED_ISSUE_TRACKERS,
+    ),
+}
+
+_GET_KEYS = set(_FIELD_PARSERS.keys()) | {"version"}

claude_team_mcp/idle_detection.py

@@ -372,6 +372,7 @@ class SessionInfo:
 
     jsonl_path: Path
     session_id: str
+    agent_type: str = "claude"
 
 
 async def wait_for_any_idle(
@@ -403,7 +404,11 @@ async def wait_for_any_idle(
 
     while time.time() - start < timeout:
         for session in sessions:
-            if is_idle(session.jsonl_path, session.session_id):
+            if session.agent_type == "codex":
+                idle = is_codex_idle(session.jsonl_path)
+            else:
+                idle = is_idle(session.jsonl_path, session.session_id)
+            if idle:
                 return {
                     "idle_session_id": session.session_id,
                     "idle": True,
@@ -453,7 +458,11 @@ async def wait_for_all_idle(
         working_sessions = []
 
         for session in sessions:
-            if is_idle(session.jsonl_path, session.session_id):
+            if session.agent_type == "codex":
+                idle = is_codex_idle(session.jsonl_path)
+            else:
+                idle = is_idle(session.jsonl_path, session.session_id)
+            if idle:
                 idle_sessions.append(session.session_id)
             else:
                 working_sessions.append(session.session_id)
@@ -474,7 +483,11 @@ async def wait_for_all_idle(
     idle_sessions = []
     working_sessions = []
     for session in sessions:
-        if is_idle(session.jsonl_path, session.session_id):
+        if session.agent_type == "codex":
+            idle = is_codex_idle(session.jsonl_path)
+        else:
+            idle = is_idle(session.jsonl_path, session.session_id)
+        if idle:
             idle_sessions.append(session.session_id)
         else:
             working_sessions.append(session.session_id)