@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/kms_scheduler.py

@@ -0,0 +1,143 @@
+"""
+KMS Auto-Rotation Scheduler.
+
+Background daemon thread that checks daily for KMS keys whose
+``next_rotation_at`` timestamp is in the past and rotates them
+automatically.
+
+Rotation policy (stored in key metadata):
+    service keys — every 30 days
+    team keys    — every 90 days
+
+On each rotation the scheduler:
+    1. Calls ``KeyStore.rotate_key`` with reason='scheduled-auto-rotation'
+    2. Sends a desktop notification via notify-send (best-effort)
+    3. Stores a memory entry tagged ``key-rotation`` in the agent memory
+
+The scheduler thread is a daemon thread and exits when the MCP server
+process terminates. Call ``start()`` once from ``mcp_server._run_server()``.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import threading
+from pathlib import Path
+
+logger = logging.getLogger("skcapstone.kms_scheduler")
+
+# How often to check for due keys (86400 s = 24 h).
+_CHECK_INTERVAL = 86_400
+
+
+class KMSRotationScheduler:
+    """Daemon thread that auto-rotates KMS service/team keys on schedule.
+
+    Args:
+        home: Agent home directory (~/.skcapstone).
+    """
+
+    def __init__(self, home: Path) -> None:
+        self._home = home
+        self._thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+
+    def start(self) -> None:
+        """Start the scheduler background thread (idempotent)."""
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._loop,
+            name="kms-rotation-scheduler",
+            daemon=True,
+        )
+        self._thread.start()
+        logger.info("KMS rotation scheduler started (check interval: %ds)", _CHECK_INTERVAL)
+
+    def stop(self) -> None:
+        """Signal the scheduler to stop after the current sleep."""
+        self._stop_event.set()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _loop(self) -> None:
+        """Main scheduler loop — runs until stop() is called."""
+        while not self._stop_event.is_set():
+            try:
+                self._check_and_rotate()
+            except Exception:
+                logger.exception("Unhandled error during KMS rotation check")
+            # Sleep for the check interval, but wake immediately if stopped.
+            self._stop_event.wait(timeout=_CHECK_INTERVAL)
+
+    def _check_and_rotate(self) -> None:
+        """Rotate all keys whose next_rotation_at is in the past."""
+        from .kms import KeyStore
+
+        store = KeyStore(self._home)
+        store.initialize()
+
+        due = store.get_due_for_rotation()
+        if not due:
+            logger.debug("KMS rotation check: no keys due")
+            return
+
+        logger.info("KMS rotation check: %d key(s) due for rotation", len(due))
+        for key in due:
+            try:
+                new_key = store.rotate_key(key.key_id, reason="scheduled-auto-rotation")
+                logger.info(
+                    "Auto-rotated %s key '%s' → v%d",
+                    key.key_type.value,
+                    key.label,
+                    new_key.version,
+                )
+                self._send_notification(key.label, key.key_type.value, new_key.version)
+                self._store_memory(key.label, key.key_type.value, new_key.version)
+            except Exception:
+                logger.exception(
+                    "Failed to auto-rotate key '%s' (%s)", key.label, key.key_id
+                )
+
+    def _send_notification(self, label: str, key_type: str, new_version: int) -> None:
+        """Send a desktop notification (best-effort, never raises)."""
+        try:
+            subprocess.run(
+                [
+                    "notify-send",
+                    "--urgency", "normal",
+                    "KMS Key Auto-Rotated",
+                    f"{key_type} key '{label}' rotated to v{new_version}",
+                ],
+                check=False,
+                timeout=5,
+                capture_output=True,
+            )
+        except Exception:
+            pass  # Notification failure must never interrupt rotation
+
+    def _store_memory(self, label: str, key_type: str, new_version: int) -> None:
+        """Persist a memory entry tagged key-rotation (best-effort)."""
+        try:
+            from .memory_engine import store as memory_store
+
+            content = (
+                f"KMS auto-rotation: {key_type} key '{label}' rotated to "
+                f"v{new_version} via scheduled rotation policy "
+                f"({30 if key_type == 'service' else 90}-day interval)."
+            )
+            memory_store(
+                home=self._home,
+                content=content,
+                tags=["key-rotation", "kms", "security"],
+                source="kms-scheduler",
+                importance=0.6,
+            )
+        except Exception:
+            logger.warning(
+                "Failed to store key-rotation memory for '%s'", label, exc_info=True
+            )

package/src/skcapstone/log_config.py

@@ -0,0 +1,135 @@
+"""Structured JSON logging with rotation for the skcapstone daemon."""
+
+from __future__ import annotations
+
+import json
+import logging
+import logging.handlers
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Attributes present on every LogRecord — excluded from JSON extra-field pass-through.
+_LOG_RECORD_BUILTIN_ATTRS: frozenset[str] = frozenset(
+    {
+        "args",
+        "created",
+        "exc_info",
+        "exc_text",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "message",
+        "module",
+        "msecs",
+        "msg",
+        "name",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "thread",
+        "threadName",
+        "taskName",
+    }
+)
+
+# Module-level guard so configure_logging() is idempotent.
+_CONFIGURED: bool = False
+
+
+class JsonFormatter(logging.Formatter):
+    """Format log records as single-line JSON objects.
+
+    Mandatory fields in every record:
+
+    - ``ts``     — ISO-8601 UTC timestamp
+    - ``level``  — log level name (e.g. ``"INFO"``)
+    - ``logger`` — logger name
+    - ``msg``    — rendered log message
+
+    Optional fields appended when present:
+
+    - ``exc``    — formatted exception traceback
+    - ``stack``  — formatted stack info
+    - any ``extra=`` keys passed to the logger call
+    """
+
+    def format(self, record: logging.LogRecord) -> str:  # noqa: A003
+        entry: dict = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            entry["exc"] = self.formatException(record.exc_info)
+        if record.stack_info:
+            entry["stack"] = self.formatStack(record.stack_info)
+        # Merge any extra fields injected via `extra={...}` on the log call.
+        for key, val in record.__dict__.items():
+            if key not in _LOG_RECORD_BUILTIN_ATTRS and not key.startswith("_"):
+                entry[key] = val
+        return json.dumps(entry, default=str)
+
+
+def configure_logging(
+    log_file: "Path | str",
+    *,
+    file_level: int = logging.DEBUG,
+    console_level: int = logging.INFO,
+    max_bytes: int = 10 * 1024 * 1024,
+    backup_count: int = 5,
+) -> None:
+    """Configure structured JSON logging for the daemon.
+
+    Sets up two handlers on the root logger:
+
+    - **RotatingFileHandler** — writes JSON lines to *log_file*
+      (rotates at *max_bytes*, keeps *backup_count* backups).
+    - **StreamHandler** — writes human-readable lines to stderr
+      at *console_level* (default ``INFO``).
+
+    This function is idempotent: subsequent calls are no-ops.
+
+    Args:
+        log_file: Path to the daemon log file.
+            The parent directory is created automatically.
+        file_level: Minimum level for the file handler (default ``DEBUG``).
+        console_level: Minimum level for the console handler (default ``INFO``).
+        max_bytes: Maximum file size before rotation (default 10 MiB).
+        backup_count: Number of rotated backup files to retain (default 5).
+    """
+    global _CONFIGURED
+    if _CONFIGURED:
+        return
+
+    log_path = Path(log_file).expanduser()
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    root = logging.getLogger()
+    root.setLevel(logging.DEBUG)  # handlers filter independently
+
+    # Rotating JSON file handler
+    file_handler = logging.handlers.RotatingFileHandler(
+        log_path,
+        maxBytes=max_bytes,
+        backupCount=backup_count,
+        encoding="utf-8",
+    )
+    file_handler.setLevel(file_level)
+    file_handler.setFormatter(JsonFormatter())
+
+    # Human-readable console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(console_level)
+    console_handler.setFormatter(
+        logging.Formatter("%(asctime)s [%(name)s] %(levelname)s: %(message)s")
+    )
+
+    root.addHandler(file_handler)
+    root.addHandler(console_handler)
+
+    _CONFIGURED = True

package/src/skcapstone/mcp_launcher.py

@@ -0,0 +1,239 @@
+"""
+Cross-platform MCP server launcher for SKCapstone.
+Task: e5f81637
+
+Detects the correct Python environment, sets required environment variables,
+and launches the MCP server via stdio transport. Works on Linux, macOS, and
+Windows without requiring shell-specific launcher scripts.
+
+Usage:
+    python -m skcapstone.mcp_launcher          # auto-detect everything
+    python -m skcapstone.mcp_launcher --venv /path/to/venv
+    python -m skcapstone.mcp_launcher --log-level DEBUG
+
+Can also be imported and called programmatically:
+    from skcapstone.mcp_launcher import launch
+    launch()
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Python / venv detection
+# ---------------------------------------------------------------------------
+
+def _skenv_dir() -> Path:
+    """Return the platform-appropriate skenv directory."""
+    if sys.platform == "win32":
+        local_app = os.environ.get("LOCALAPPDATA")
+        if local_app:
+            return Path(local_app) / "skenv"
+        return Path.home() / ".skenv"
+    return Path.home() / ".skenv"
+
+
+def _python_in_venv(venv: Path) -> Path | None:
+    """Return the python executable inside a venv, or None."""
+    if sys.platform == "win32":
+        candidate = venv / "Scripts" / "python.exe"
+    else:
+        candidate = venv / "bin" / "python"
+    return candidate if candidate.is_file() else None
+
+
+def _has_skcapstone(python: Path | str) -> bool:
+    """Check if a Python interpreter has skcapstone importable."""
+    try:
+        result = subprocess.run(
+            [str(python), "-c", "import skcapstone"],
+            capture_output=True,
+            timeout=10,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False
+
+
+def find_python(explicit_venv: str | None = None) -> str:
+    """Locate the best Python interpreter with skcapstone installed.
+
+    Search order:
+        1. Explicit venv path (parameter or SKCAPSTONE_VENV env var)
+        2. ~/.skenv (or %LOCALAPPDATA%/skenv on Windows)
+        3. Project-local .venv
+        4. The currently running interpreter (sys.executable)
+        5. System python3 / python
+
+    Args:
+        explicit_venv: Optional path to a virtualenv to use.
+
+    Returns:
+        Absolute path to a Python executable.
+
+    Raises:
+        RuntimeError: If no suitable Python is found.
+    """
+    # 1. Explicit override
+    venv_path = explicit_venv or os.environ.get("SKCAPSTONE_VENV")
+    if venv_path:
+        py = _python_in_venv(Path(venv_path))
+        if py and py.is_file():
+            logger.info("Using explicit venv: %s", py)
+            return str(py)
+        logger.warning(
+            "SKCAPSTONE_VENV=%s set but python not found there, falling back.",
+            venv_path,
+        )
+
+    # 2. Standard skenv
+    skenv = _skenv_dir()
+    py = _python_in_venv(skenv)
+    if py and _has_skcapstone(py):
+        logger.info("Using skenv: %s", py)
+        return str(py)
+
+    # 3. Project-local .venv
+    project_dir = Path(__file__).resolve().parent.parent.parent  # src/../..
+    for venv_name in (".venv", "venv"):
+        local_venv = project_dir / venv_name
+        py = _python_in_venv(local_venv)
+        if py and _has_skcapstone(py):
+            logger.info("Using project venv: %s", py)
+            return str(py)
+
+    # 4. Current interpreter
+    if _has_skcapstone(sys.executable):
+        logger.info("Using current interpreter: %s", sys.executable)
+        return sys.executable
+
+    # 5. System python
+    for cmd in ("python3", "python"):
+        path = shutil.which(cmd)
+        if path and _has_skcapstone(path):
+            logger.info("Using system python: %s", path)
+            return path
+
+    raise RuntimeError(
+        "Could not find a Python interpreter with skcapstone installed.\n"
+        "Install with: bash scripts/install.sh (Linux/macOS) or "
+        ".\\scripts\\install.ps1 (Windows)\n"
+        "Or set SKCAPSTONE_VENV=/path/to/venv"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Environment setup
+# ---------------------------------------------------------------------------
+
+def _setup_environment() -> None:
+    """Set required environment variables if not already present."""
+    home = Path.home()
+    skcapstone_home = home / ".skcapstone"
+
+    os.environ.setdefault("SKCAPSTONE_HOME", str(skcapstone_home))
+    os.environ.setdefault("SKMEMORY_HOME", str(skcapstone_home / "memory"))
+
+    # Ensure src/ is on PYTHONPATH for importability
+    src_dir = str(Path(__file__).resolve().parent.parent)
+    python_path = os.environ.get("PYTHONPATH", "")
+    if src_dir not in python_path.split(os.pathsep):
+        os.environ["PYTHONPATH"] = (
+            f"{src_dir}{os.pathsep}{python_path}" if python_path else src_dir
+        )
+
+
+# ---------------------------------------------------------------------------
+# Launch
+# ---------------------------------------------------------------------------
+
+def launch(
+    venv: str | None = None,
+    log_level: str = "WARNING",
+    extra_args: list[str] | None = None,
+) -> int:
+    """Launch the MCP server, optionally in a subprocess.
+
+    If the current interpreter already has skcapstone and is the best match,
+    the server is launched in-process. Otherwise, a subprocess is spawned
+    with the detected Python interpreter.
+
+    Args:
+        venv: Optional explicit venv path.
+        log_level: Logging level for the MCP server.
+        extra_args: Additional arguments to pass through.
+
+    Returns:
+        Exit code (0 on success).
+    """
+    logging.basicConfig(
+        level=getattr(logging, log_level.upper(), logging.WARNING),
+        format="%(name)s: %(message)s",
+    )
+
+    _setup_environment()
+
+    python = find_python(explicit_venv=venv)
+
+    # If the best Python IS us, run in-process
+    if os.path.realpath(python) == os.path.realpath(sys.executable):
+        logger.info("Launching MCP server in-process.")
+        from skcapstone.mcp_server import main as mcp_main
+        mcp_main()
+        return 0
+
+    # Otherwise, exec into the correct interpreter
+    logger.info("Launching MCP server via: %s", python)
+    cmd = [python, "-m", "skcapstone.mcp_server"]
+    if extra_args:
+        cmd.extend(extra_args)
+
+    if sys.platform != "win32":
+        # On Unix, replace the current process
+        os.execv(python, cmd)
+        # execv does not return
+        return 1  # unreachable, but satisfies type checker
+    else:
+        # On Windows, os.execv has quirks; use subprocess
+        result = subprocess.run(cmd)
+        return result.returncode
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """CLI entry point with argument parsing."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Cross-platform SKCapstone MCP server launcher.",
+        prog="skcapstone-mcp-launcher",
+    )
+    parser.add_argument(
+        "--venv",
+        help="Path to a virtualenv to use (overrides auto-detection).",
+    )
+    parser.add_argument(
+        "--log-level",
+        default=os.environ.get("SKCAPSTONE_LOG_LEVEL", "WARNING"),
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Logging level (default: WARNING).",
+    )
+    args, extra = parser.parse_known_args()
+
+    rc = launch(venv=args.venv, log_level=args.log_level, extra_args=extra)
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()