claude-supervisor 0.1.0__py3-none-any.whl

claude_supervisor/__init__.py

@@ -0,0 +1,15 @@
+"""Claude Supervisor.
+
+A safe, human-in-control companion for Claude Code. It waits for legitimate
+usage resets, resumes the user's existing session, and can optionally automate
+repetitive permission prompts for the *currently active* task only.
+
+It never bypasses usage limits, authentication, or subscription requirements,
+and it never starts new work on its own.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

claude_supervisor/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface for Claude Supervisor."""
+
+from __future__ import annotations
+
+from claude_supervisor.cli.app import app, main
+
+__all__ = ["app", "main"]

claude_supervisor/cli/app.py

@@ -0,0 +1,386 @@
+"""Typer application exposing the supervisor's commands.
+
+Commands: ``version``, ``config``, ``doctor`` (diagnostics), ``start`` /
+``resume`` (supervise a session), and ``status`` / ``logs`` (inspect recorded
+sessions, statistics, and the log tail).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import platform
+import shutil
+import signal
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from claude_supervisor import __version__
+from claude_supervisor.config import (
+    ConfigError,
+    PermissionMode,
+    SupervisorConfig,
+    default_config_path,
+    effective_database,
+    effective_log_file,
+    load_config,
+    starter_config,
+)
+from claude_supervisor.core import RunStats, Supervisor, TranscriptWriter
+from claude_supervisor.logging import configure_logging
+from claude_supervisor.parser.patterns import PatternSetError, load_pattern_set
+from claude_supervisor.session import SessionManager
+from claude_supervisor.storage import SqliteStorage
+from claude_supervisor.terminal import TerminalError, terminal_factory
+
+app = typer.Typer(
+    name="claude-supervisor",
+    help="Safe, human-in-control companion for Claude Code.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+_console = Console()
+
+_MIN_PYTHON = (3, 12)
+
+
+def _config_option() -> Any:
+    """Return a reusable ``--config`` Typer option (an ``OptionInfo``)."""
+    return typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to config.yaml (defaults to the per-user location).",
+        show_default=False,
+    )
+
+
+def _require_config_exists(config_path: Path | None) -> None:
+    """Error out if an *explicitly provided* config file does not exist.
+
+    A missing default location is fine (defaults are used); a missing path the
+    user typed is almost always a mistake, so we surface it instead of silently
+    ignoring their config.
+    """
+    if config_path is not None and not config_path.exists():
+        _console.print(f"[red]Config error:[/red] file not found: {config_path}")
+        raise typer.Exit(code=1)
+
+
+def _load_config(config_path: Path | None) -> SupervisorConfig:
+    """Load config, exiting with a clear message on a missing or invalid file."""
+    _require_config_exists(config_path)
+    try:
+        return load_config(config_path)
+    except ConfigError as exc:
+        _console.print(f"[red]Config error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def version() -> None:
+    """Print the installed version."""
+    _console.print(f"claude-supervisor {__version__}")
+
+
+@app.command()
+def init(
+    config_path: Path | None = _config_option(),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing config file."),
+) -> None:
+    """Write a starter config file with sensible, validated defaults."""
+    target = Path(config_path) if config_path is not None else default_config_path()
+    if target.exists() and not force:
+        _console.print(
+            f"[yellow]Config already exists at {target}[/yellow] — use --force to overwrite."
+        )
+        raise typer.Exit(code=1)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(starter_config(), encoding="utf-8")
+    _console.print(f"[green]Wrote starter config to {target}[/green]")
+    _console.print("Edit it if your Claude setup differs, then run: claude-supervisor doctor")
+
+
+@app.command()
+def config(config_path: Path | None = _config_option()) -> None:
+    """Show the effective configuration (defaults merged with your file)."""
+    cfg = _load_config(config_path)
+    source = config_path or default_config_path()
+    exists = Path(source).exists()
+    _console.print(
+        f"[bold]Source:[/bold] {source} {'' if exists else '(not found; using defaults)'}"
+    )
+    _console.print_json(cfg.model_dump_json(indent=2))
+
+
+@app.command()
+def doctor(config_path: Path | None = _config_option()) -> None:
+    """Run environment and configuration health checks."""
+    table = Table(title="claude-supervisor doctor", show_lines=False)
+    table.add_column("Check", style="bold")
+    table.add_column("Result")
+    table.add_column("Detail", overflow="fold")
+
+    ok = True
+    _require_config_exists(config_path)
+
+    py_ok = sys.version_info[:2] >= _MIN_PYTHON
+    ok &= py_ok
+    table.add_row(
+        "Python >= 3.12",
+        _status(py_ok),
+        platform.python_version(),
+    )
+
+    # Config loads?
+    try:
+        cfg = load_config(config_path)
+        table.add_row("Config loads", _status(True), str(config_path or default_config_path()))
+    except ConfigError as exc:
+        ok = False
+        table.add_row("Config loads", _status(False), str(exc).splitlines()[0])
+        cfg = None
+
+    # Pattern rules compile?
+    rules_path = None
+    if cfg is not None and cfg.paths.pattern_rules is not None:
+        rules_path = cfg.paths.pattern_rules
+    try:
+        pattern_set = load_pattern_set(rules_path)
+        table.add_row(
+            "Parser rules compile",
+            _status(True),
+            f"{len(pattern_set)} patterns (v{pattern_set.version})",
+        )
+    except PatternSetError as exc:
+        ok = False
+        table.add_row("Parser rules compile", _status(False), str(exc).splitlines()[0])
+
+    # Claude CLI present? Informational — the tool itself is healthy without it,
+    # but you need it to actually supervise anything.
+    claude_exe = cfg.claude_command[0] if cfg is not None else "claude"
+    resolved = shutil.which(claude_exe)
+    if resolved:
+        table.add_row("Claude CLI on PATH", _status(True), resolved)
+    else:
+        table.add_row(
+            "Claude CLI on PATH",
+            "[yellow]MISSING[/yellow]",
+            f"'{claude_exe}' not found — install: npm install -g @anthropic-ai/claude-code",
+        )
+
+    _console.print(table)
+    if not ok:
+        raise typer.Exit(code=1)
+
+
+def _render_stats(stats: RunStats) -> None:
+    table = Table(title="run summary", show_header=False)
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+    for key, value in stats.as_dict().items():
+        table.add_row(key, str(value))
+    _console.print(table)
+
+
+def _run_supervisor(
+    config: SupervisorConfig,
+    argv: Sequence[str],
+    *,
+    task: str | None = None,
+    capture: Path | None = None,
+) -> RunStats:
+    """Set up logging + persistence + signals, run the supervisor, return stats."""
+    configure_logging(config.logging, log_file=effective_log_file(config), force=True)
+    factory = terminal_factory(cwd=os.getcwd())
+
+    transcript = TranscriptWriter(capture) if capture is not None else None
+    supervisor = Supervisor(config, factory, on_line=transcript)
+
+    storage = SqliteStorage(effective_database(config))
+    manager = SessionManager(storage)
+    session_id = manager.begin(
+        argv, started_at=supervisor.stats.started_at, machine=supervisor.machine
+    )
+
+    previous = signal.getsignal(signal.SIGINT)
+
+    def _on_sigint(_signum: int, _frame: object) -> None:
+        supervisor.request_stop("keyboard interrupt (SIGINT)")
+
+    signal.signal(signal.SIGINT, _on_sigint)
+    try:
+        return supervisor.run(argv, task=task)
+    finally:
+        signal.signal(signal.SIGINT, previous)
+        manager.end(session_id, supervisor.stats, supervisor.machine.state)
+        storage.close()
+        if transcript is not None:
+            transcript.close()
+            _console.print(f"[dim]Transcript written to {transcript.path}[/dim]")
+
+
+@app.command()
+def start(
+    task: str | None = typer.Option(
+        None, "--task", "-t", help="Task/prompt to run unattended.", show_default=False
+    ),
+    auto_approve: bool = typer.Option(
+        False,
+        "--auto-approve",
+        help="Auto-answer permission prompts for this run (active-task scope).",
+    ),
+    capture: Path | None = typer.Option(
+        None,
+        "--capture",
+        help="Write a transcript of Claude's output + detected events to this file.",
+        show_default=False,
+    ),
+    extra_args: list[str] | None = typer.Argument(
+        None, help="Extra arguments appended to the configured claude command."
+    ),
+    config_path: Path | None = _config_option(),
+) -> None:
+    """Launch and supervise a Claude Code session (optionally an unattended task)."""
+    config = _load_config(config_path)
+
+    if auto_approve:
+        config = config.model_copy(
+            update={
+                "auto_permissions": True,
+                "permission_mode": PermissionMode.ACTIVE_TASK_ONLY,
+            }
+        )
+
+    argv = [*config.claude_command, *(extra_args or [])]
+    try:
+        stats = _run_supervisor(config, argv, task=task, capture=capture)
+    except TerminalError as exc:
+        _console.print(f"[red]Terminal error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    _render_stats(stats)
+
+
+@app.command()
+def resume(config_path: Path | None = _config_option()) -> None:
+    """Resume an existing Claude Code session (waiting for a reset if needed)."""
+    config = _load_config(config_path)
+    try:
+        stats = _run_supervisor(config, config.resume_command)
+    except TerminalError as exc:
+        _console.print(f"[red]Terminal error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    _render_stats(stats)
+
+
+@app.command()
+def status(config_path: Path | None = _config_option()) -> None:
+    """Show the latest session and aggregate statistics."""
+    config = _load_config(config_path)
+
+    database = effective_database(config)
+    if not database.exists():
+        _console.print("No sessions recorded yet.")
+        return
+
+    with SqliteStorage(database) as storage:
+        manager = SessionManager(storage)
+        latest = manager.latest()
+        stats = manager.statistics()
+
+    if latest is None:
+        _console.print("No sessions recorded yet.")
+        return
+
+    session_table = Table(title="latest session", show_header=False)
+    session_table.add_column("Field", style="bold")
+    session_table.add_column("Value", overflow="fold")
+    session_table.add_row("id", str(latest.id))
+    session_table.add_row("command", " ".join(latest.command))
+    session_table.add_row("started_at", latest.started_at)
+    session_table.add_row("final_state", latest.final_state or "(running)")
+    session_table.add_row("completed", str(latest.completed))
+    session_table.add_row("resumes", str(latest.resumes))
+    session_table.add_row("approvals", str(latest.approvals))
+    session_table.add_row("stop_reason", latest.stop_reason or "-")
+    if latest.error:
+        session_table.add_row("error", latest.error)
+    _console.print(session_table)
+
+    stats_table = Table(title="statistics (all sessions)", show_header=False)
+    stats_table.add_column("Metric", style="bold")
+    stats_table.add_column("Value")
+    for key, value in stats.as_dict().items():
+        stats_table.add_row(key, str(value))
+    _console.print(stats_table)
+
+
+@app.command()
+def logs(
+    lines: int = typer.Option(40, "--lines", "-n", help="Number of trailing log lines to show."),
+    config_path: Path | None = _config_option(),
+) -> None:
+    """Show the tail of the supervisor log file."""
+    config = _load_config(config_path)
+    log_file = effective_log_file(config)
+    if not log_file.exists():
+        _console.print(f"No log file yet at {log_file}")
+        return
+
+    content = log_file.read_text(encoding="utf-8", errors="replace").splitlines()
+    tail = content[-lines:] if lines > 0 else content
+    _console.print("\n".join(tail))
+
+
+@app.command()
+def statusline() -> None:
+    """Emit a one-line status summary for Claude Code's status line.
+
+    Designed to be wired into Claude Code's ``statusLine`` setting. It reads the
+    session database and prints a single plain-text line, and is deliberately
+    defensive: any error yields a minimal line rather than a traceback, so it can
+    never disrupt the Claude Code UI.
+    """
+    # The line renders inside another program's UI (often UTF-8), but may also be
+    # printed to a legacy console (cp1252 on Windows). Force UTF-8 with replacement
+    # so the emoji never raises UnicodeEncodeError.
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        with contextlib.suppress(ValueError, OSError):
+            reconfigure(encoding="utf-8", errors="replace")
+
+    try:
+        config = load_config(None)
+        database = effective_database(config)
+        if not database.exists():
+            typer.echo("🛡 claude-supervisor · no runs yet")
+            return
+        with SqliteStorage(database) as storage:
+            stats = storage.statistics()
+        parts = [f"{stats.total_sessions} run" + ("s" if stats.total_sessions != 1 else "")]
+        if stats.resumes:
+            parts.append(f"{stats.resumes} resume" + ("s" if stats.resumes != 1 else ""))
+        if stats.hours_saved >= 0.05:
+            parts.append(f"{stats.hours_saved:.1f}h saved")
+        typer.echo("🛡 " + " · ".join(parts))
+    except Exception:  # pragma: no cover - never break the host UI
+        typer.echo("🛡 claude-supervisor")
+
+
+def _status(ok: bool) -> str:
+    return "[green]OK[/green]" if ok else "[red]FAIL[/red]"
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

claude_supervisor/config/__init__.py

@@ -0,0 +1,39 @@
+"""Configuration subsystem: typed, validated settings loaded from YAML."""
+
+from __future__ import annotations
+
+from claude_supervisor.config.loader import (
+    ConfigError,
+    default_config_path,
+    dump_config,
+    effective_database,
+    effective_log_file,
+    effective_state_dir,
+    load_config,
+    starter_config,
+)
+from claude_supervisor.config.models import (
+    CompletionMode,
+    LoggingConfig,
+    PathsConfig,
+    PermissionMode,
+    SupervisorConfig,
+    TaskDelivery,
+)
+
+__all__ = [
+    "CompletionMode",
+    "ConfigError",
+    "LoggingConfig",
+    "PathsConfig",
+    "PermissionMode",
+    "SupervisorConfig",
+    "TaskDelivery",
+    "default_config_path",
+    "dump_config",
+    "effective_database",
+    "effective_log_file",
+    "effective_state_dir",
+    "load_config",
+    "starter_config",
+]

claude_supervisor/config/loader.py

@@ -0,0 +1,160 @@
+"""Load and persist :class:`SupervisorConfig` from YAML.
+
+The loader is tolerant of the flat, spec-style config shown in the project
+specification (``log_level: INFO``) and transparently maps such keys onto the
+richer nested model, so users never have to migrate their file by hand.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from claude_supervisor.config.models import SupervisorConfig
+
+_APP_NAME = "claude-supervisor"
+
+# Flat spec-style keys that live under a nested section in the model.
+_FLAT_TO_NESTED: dict[str, tuple[str, str]] = {
+    "log_level": ("logging", "level"),
+}
+
+
+class ConfigError(RuntimeError):
+    """Raised when a configuration file cannot be read, parsed, or validated."""
+
+
+def default_config_dir() -> Path:
+    """Return the platform-appropriate config directory.
+
+    Honors ``CLAUDE_SUPERVISOR_HOME`` when set, else ``XDG_CONFIG_HOME`` on
+    POSIX and ``%APPDATA%`` on Windows, falling back to ``~/.config``.
+    """
+    override = os.environ.get("CLAUDE_SUPERVISOR_HOME")
+    if override:
+        return Path(override).expanduser()
+
+    if os.name == "nt":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / _APP_NAME
+        return Path.home() / "AppData" / "Roaming" / _APP_NAME
+
+    base = os.environ.get("XDG_CONFIG_HOME")
+    if base:
+        return Path(base) / _APP_NAME
+    return Path.home() / ".config" / _APP_NAME
+
+
+def default_config_path() -> Path:
+    """Return the default ``config.yaml`` path."""
+    return default_config_dir() / "config.yaml"
+
+
+def _migrate_flat_keys(raw: dict[str, Any]) -> dict[str, Any]:
+    """Fold flat spec-style keys into their nested homes without clobbering."""
+    data = dict(raw)
+    for flat_key, (section, field) in _FLAT_TO_NESTED.items():
+        if flat_key not in data:
+            continue
+        value = data.pop(flat_key)
+        section_data = dict(data.get(section) or {})
+        section_data.setdefault(field, value)
+        data[section] = section_data
+    return data
+
+
+def load_config(path: str | os.PathLike[str] | None = None) -> SupervisorConfig:
+    """Load configuration from ``path`` (or the default location).
+
+    A missing file yields a fully-defaulted config; that is a valid, supported
+    state rather than an error. Malformed YAML or values that fail validation
+    raise :class:`ConfigError` with a human-readable message.
+    """
+    resolved = Path(path) if path is not None else default_config_path()
+
+    if not resolved.exists():
+        return SupervisorConfig()
+
+    try:
+        text = resolved.read_text(encoding="utf-8")
+    except OSError as exc:  # pragma: no cover - platform/permission dependent
+        raise ConfigError(f"Could not read config file {resolved}: {exc}") from exc
+
+    try:
+        raw = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Config file {resolved} is not valid YAML: {exc}") from exc
+
+    if not isinstance(raw, dict):
+        raise ConfigError(
+            f"Config file {resolved} must contain a top-level mapping, got {type(raw).__name__}."
+        )
+
+    try:
+        return SupervisorConfig.model_validate(_migrate_flat_keys(raw))
+    except ValidationError as exc:
+        raise ConfigError(f"Config file {resolved} failed validation:\n{exc}") from exc
+
+
+_STARTER_CONFIG = """\
+# Claude Supervisor configuration.
+# Full reference: examples/config.yaml in the project repository.
+
+# How Claude is launched for an unattended task. `-p` (print/headless) runs
+# one-shot; the permission flag lets Claude use tools without prompting.
+# For broader access use "--dangerously-skip-permissions" instead (with care).
+claude_command: ["claude", "-p", "--permission-mode", "acceptEdits"]
+
+# How to resume after a usage-limit reset (continues the most recent session).
+resume_command: ["claude", "-p", "--continue", "--permission-mode", "acceptEdits"]
+
+# Wait for a legitimate reset and resume automatically.
+auto_resume: true
+
+# Fallback wait (hours) if Claude reports no reset time.
+default_reset_hours: 5
+
+# A completion marker OR a clean process exit counts as done; 'heuristic' also
+# stops when Claude goes idle. Headless `claude -p` exits cleanly when finished.
+completion_mode: heuristic
+"""
+
+
+def starter_config() -> str:
+    """Return the text of a sensible, validated starter config file."""
+    return _STARTER_CONFIG
+
+
+def effective_state_dir(config: SupervisorConfig) -> Path:
+    """Return the runtime state directory (``paths.state_dir`` or the default)."""
+    return config.paths.state_dir or default_config_dir()
+
+
+def effective_log_file(config: SupervisorConfig) -> Path:
+    """Return the resolved log-file path (``paths.log_file`` or a derived default)."""
+    return config.paths.log_file or (effective_state_dir(config) / "supervisor.log")
+
+
+def effective_database(config: SupervisorConfig) -> Path:
+    """Return the resolved SQLite path (``paths.database`` or a derived default)."""
+    return config.paths.database or (effective_state_dir(config) / "supervisor.db")
+
+
+def dump_config(config: SupervisorConfig, path: str | os.PathLike[str]) -> Path:
+    """Serialize ``config`` to ``path`` as YAML, creating parent dirs as needed.
+
+    Returns the path written to.
+    """
+    resolved = Path(path)
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    payload = config.model_dump(mode="json", exclude_none=True)
+    resolved.write_text(
+        yaml.safe_dump(payload, sort_keys=False, default_flow_style=False),
+        encoding="utf-8",
+    )
+    return resolved