milo-cli 0.1.0__py3-none-any.whl

milo/config.py

@@ -0,0 +1,250 @@
+"""Configuration system with deep merge, environment overlays, and origin tracking."""
+
+from __future__ import annotations
+
+import glob as globmod
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigSpec:
+    """Declarative configuration schema.
+
+    Describes where config comes from and how it merges::
+
+        cli.config_spec = ConfigSpec(
+            sources=("bengal.toml", "config/*.yaml"),
+            env_prefix="BENGAL_",
+            profiles={"writer": {"build.drafts": True}},
+            overlays={"production": "config/production.yaml"},
+        )
+    """
+
+    sources: tuple[str, ...] = ()
+    """File patterns to load (TOML via stdlib, YAML via optional pyyaml)."""
+
+    env_prefix: str = ""
+    """Environment variable prefix. BENGAL_BUILD_OUTPUT -> build.output."""
+
+    defaults: dict[str, Any] = field(default_factory=dict)
+    """Default values (lowest precedence)."""
+
+    profiles: dict[str, dict[str, Any]] = field(default_factory=dict)
+    """Named override sets, selected via --profile."""
+
+    overlays: dict[str, str] = field(default_factory=dict)
+    """Environment -> file path mapping for env-specific config."""
+
+
+class Config:
+    """Immutable, merged configuration with origin tracking.
+
+    Usage::
+
+        config = Config.load(spec, root=Path("."), profile="dev", overlay="production")
+        url = config.get("site.url", "http://localhost")
+        print(config.origin_of("site.url"))  # "file:config/site.yaml"
+    """
+
+    def __init__(self, data: dict[str, Any], origins: dict[str, str]) -> None:
+        self._data = data
+        self._origins = origins
+
+    @classmethod
+    def load(
+        cls,
+        spec: ConfigSpec,
+        *,
+        root: Path | None = None,
+        profile: str = "",
+        overlay: str = "",
+    ) -> Config:
+        """Load, merge, and freeze config from all sources.
+
+        Merge precedence (lowest to highest):
+        1. spec.defaults
+        2. File sources (in order)
+        3. Environment variables
+        4. Profile overrides
+        5. Overlay file
+        """
+        root = root or Path.cwd()
+        data: dict[str, Any] = {}
+        origins: dict[str, str] = {}
+
+        # 1. Defaults
+        if spec.defaults:
+            _deep_merge(data, spec.defaults, origins, origin="defaults")
+
+        # 2. File sources
+        for pattern in spec.sources:
+            matched = sorted(globmod.glob(str(root / pattern)))
+            for filepath in matched:
+                file_data = _load_file(filepath)
+                _deep_merge(data, file_data, origins, origin=f"file:{filepath}")
+
+        # 3. Environment variables
+        if spec.env_prefix:
+            env_data = _load_env_vars(spec.env_prefix)
+            _deep_merge(data, env_data, origins, origin="env")
+
+        # 4. Profile overrides
+        if profile and profile in spec.profiles:
+            profile_data = _expand_dotted(spec.profiles[profile])
+            _deep_merge(data, profile_data, origins, origin=f"profile:{profile}")
+
+        # 5. Overlay file
+        if overlay and overlay in spec.overlays:
+            overlay_path = root / spec.overlays[overlay]
+            if overlay_path.exists():
+                overlay_data = _load_file(str(overlay_path))
+                _deep_merge(data, overlay_data, origins, origin=f"overlay:{overlay}")
+
+        return cls(data, origins)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], origin: str = "dict") -> Config:
+        """Create a Config from a plain dictionary."""
+        origins: dict[str, str] = {}
+        _track_origins(data, origins, origin, prefix="")
+        return cls(data, origins)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Dot-notation access: ``config.get("site.url")``."""
+        parts = key.split(".")
+        current = self._data
+        for part in parts:
+            if not isinstance(current, dict) or part not in current:
+                return default
+            current = current[part]
+        return current
+
+    def origin_of(self, key: str) -> str:
+        """Return the source that contributed a key's value."""
+        return self._origins.get(key, "")
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a deep copy of the merged config."""
+        import copy
+
+        return copy.deepcopy(self._data)
+
+    def to_state(self) -> dict[str, Any]:
+        """Convert to a Store-compatible state dict."""
+        return self.as_dict()
+
+    def __contains__(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def __repr__(self) -> str:
+        return f"Config({list(self._data.keys())})"
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_file(filepath: str) -> dict[str, Any]:
+    """Load a TOML or YAML file."""
+    path = Path(filepath)
+    suffix = path.suffix.lower()
+
+    if suffix == ".toml":
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+
+    if suffix in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError as e:
+            msg = (
+                f"Cannot load {path.name}: PyYAML is required for YAML config files. "
+                "Install it with: pip install pyyaml"
+            )
+            raise ImportError(msg) from e
+        with open(path) as f:
+            return yaml.safe_load(f) or {}
+
+    if suffix == ".json":
+        import json
+
+        with open(path) as f:
+            return json.load(f)
+
+    msg = f"Unsupported config format: {suffix}"
+    raise ValueError(msg)
+
+
+def _load_env_vars(prefix: str) -> dict[str, Any]:
+    """Load environment variables with a given prefix into nested dict.
+
+    BENGAL_SITE_URL -> {"site": {"url": "value"}}
+    """
+    result: dict[str, Any] = {}
+    prefix_upper = prefix.upper()
+    for key, value in os.environ.items():
+        if not key.startswith(prefix_upper):
+            continue
+        # Strip prefix and convert to nested path
+        remainder = key[len(prefix_upper) :].lower()
+        parts = remainder.split("_")
+        # Build nested dict
+        current = result
+        for part in parts[:-1]:
+            current = current.setdefault(part, {})
+        current[parts[-1]] = value
+    return result
+
+
+def _deep_merge(
+    target: dict[str, Any],
+    source: dict[str, Any],
+    origins: dict[str, str],
+    origin: str,
+    prefix: str = "",
+) -> None:
+    """Deep merge source into target, tracking origins for leaf values."""
+    for key, value in source.items():
+        dotted = f"{prefix}{key}" if prefix else key
+        if key in target and isinstance(target[key], dict) and isinstance(value, dict):
+            _deep_merge(target[key], value, origins, origin, prefix=f"{dotted}.")
+        else:
+            target[key] = value
+            if isinstance(value, dict):
+                _track_origins(value, origins, origin, prefix=f"{dotted}.")
+            else:
+                origins[dotted] = origin
+
+
+def _track_origins(
+    data: dict[str, Any],
+    origins: dict[str, str],
+    origin: str,
+    prefix: str,
+) -> None:
+    """Recursively track origins for all keys in a dict."""
+    for key, value in data.items():
+        dotted = f"{prefix}{key}" if prefix else key
+        origins[dotted] = origin
+        if isinstance(value, dict):
+            _track_origins(value, origins, origin, prefix=f"{dotted}.")
+
+
+def _expand_dotted(flat: dict[str, Any]) -> dict[str, Any]:
+    """Expand dotted keys into nested dicts.
+
+    {"build.output": "_site"} -> {"build": {"output": "_site"}}
+    """
+    result: dict[str, Any] = {}
+    for key, value in flat.items():
+        parts = key.split(".")
+        current = result
+        for part in parts[:-1]:
+            current = current.setdefault(part, {})
+        current[parts[-1]] = value
+    return result

milo/context.py

@@ -0,0 +1,81 @@
+"""Execution context for CLI command handlers."""
+
+from __future__ import annotations
+
+import sys
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """Execution context available to all command handlers.
+
+    Handlers opt in by adding a ``ctx: Context`` parameter::
+
+        @cli.command("build", description="Build the site")
+        def build(output: str = "_site", ctx: Context = None) -> str:
+            ctx.log("Starting build...", level=1)  # verbose only
+            return f"Built to {output}"
+
+    The context is injected automatically by the CLI dispatcher and
+    excluded from argparse and MCP schemas.
+    """
+
+    verbosity: int = 0
+    """Verbosity level: -1=quiet, 0=normal, 1=verbose, 2=debug."""
+
+    format: str = "plain"
+    """Output format: plain, json, table."""
+
+    color: bool = True
+    """Whether color output is enabled."""
+
+    globals: dict[str, Any] = field(default_factory=dict)
+    """Values from user-defined global options."""
+
+    def log(self, message: str, *, level: int = 0) -> None:
+        """Print a message if verbosity is at or above *level*.
+
+        level 0 = normal (always shown unless quiet)
+        level 1 = verbose (shown with --verbose)
+        level 2 = debug (shown with -vv)
+        """
+        if self.verbosity >= level:
+            sys.stderr.write(message + "\n")
+            sys.stderr.flush()
+
+    @property
+    def quiet(self) -> bool:
+        """True when --quiet was passed."""
+        return self.verbosity < 0
+
+    @property
+    def verbose(self) -> bool:
+        """True when --verbose was passed."""
+        return self.verbosity >= 1
+
+    @property
+    def debug(self) -> bool:
+        """True when -vv (or higher) was passed."""
+        return self.verbosity >= 2
+
+
+_current_context: ContextVar[Context | None] = ContextVar("milo_context", default=None)
+
+
+def get_context() -> Context:
+    """Get the current execution context.
+
+    Returns a default Context if none has been set.
+    """
+    ctx = _current_context.get()
+    if ctx is None:
+        return Context()
+    return ctx
+
+
+def set_context(ctx: Context) -> None:
+    """Set the current execution context."""
+    _current_context.set(ctx)

milo/dev.py

@@ -0,0 +1,238 @@
+"""Hot-reload dev server with smart file watching."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import threading
+from pathlib import Path
+from typing import Any
+
+from milo._types import Action
+
+# ---------------------------------------------------------------------------
+# File watcher abstraction
+# ---------------------------------------------------------------------------
+
+_STYLE_EXTENSIONS = frozenset({".css", ".scss", ".sass", ".less"})
+
+
+class _FileWatcher:
+    """Base watcher interface."""
+
+    def __init__(
+        self,
+        dirs: tuple[Path, ...],
+        *,
+        extensions: frozenset[str] | None = None,
+        poll_interval: float = 0.5,
+    ) -> None:
+        self._dirs = dirs
+        self._extensions = extensions
+        self._poll_interval = poll_interval
+
+    def watch(self, callback: Any, stop_event: threading.Event) -> None:
+        raise NotImplementedError
+
+
+class _PollingWatcher(_FileWatcher):
+    """Polling-based watcher (stdlib only, no dependencies)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._mtimes: dict[Path, float] = {}
+
+    def watch(self, callback: Any, stop_event: threading.Event) -> None:
+        self._scan_mtimes()
+        while not stop_event.is_set():
+            stop_event.wait(self._poll_interval)
+            if stop_event.is_set():
+                break
+            changed = self._check_changes()
+            if changed:
+                callback(changed)
+
+    def _scan_mtimes(self) -> None:
+        for d in self._dirs:
+            if not d.exists():
+                continue
+            for p in d.rglob("*"):
+                if p.is_file() and self._matches(p):
+                    with contextlib.suppress(OSError):
+                        self._mtimes[p] = p.stat().st_mtime
+
+    def _check_changes(self) -> list[Path]:
+        changed: list[Path] = []
+        for d in self._dirs:
+            if not d.exists():
+                continue
+            for p in d.rglob("*"):
+                if not p.is_file() or not self._matches(p):
+                    continue
+                try:
+                    mtime = p.stat().st_mtime
+                except OSError:
+                    continue
+                if p in self._mtimes:
+                    if mtime > self._mtimes[p]:
+                        changed.append(p)
+                        self._mtimes[p] = mtime
+                else:
+                    self._mtimes[p] = mtime
+                    changed.append(p)
+        return changed
+
+    def _matches(self, path: Path) -> bool:
+        if self._extensions is None:
+            return True
+        return path.suffix in self._extensions
+
+
+class _WatchfilesWatcher(_FileWatcher):
+    """Rust-based watcher using the ``watchfiles`` package."""
+
+    def watch(self, callback: Any, stop_event: threading.Event) -> None:
+        import watchfiles  # type: ignore[import-untyped]
+
+        for changes in watchfiles.watch(
+            *self._dirs,
+            stop_event=stop_event,
+            poll_delay_ms=int(self._poll_interval * 1000),
+        ):
+            changed = [
+                Path(path)
+                for _change_type, path in changes
+                if self._extensions is None or Path(path).suffix in self._extensions
+            ]
+            if changed:
+                callback(changed)
+
+
+def _make_watcher(
+    dirs: tuple[Path, ...],
+    *,
+    extensions: frozenset[str] | None = None,
+    poll_interval: float = 0.5,
+) -> _FileWatcher:
+    """Try watchfiles first, fall back to polling."""
+    try:
+        import watchfiles  # type: ignore[import-untyped]  # noqa: F401
+
+        return _WatchfilesWatcher(dirs, extensions=extensions, poll_interval=poll_interval)
+    except ImportError:
+        return _PollingWatcher(dirs, extensions=extensions, poll_interval=poll_interval)
+
+
+# ---------------------------------------------------------------------------
+# Change batching / debounce
+# ---------------------------------------------------------------------------
+
+
+class _ChangeBatcher:
+    """Collects file changes and flushes them after a debounce window."""
+
+    def __init__(self, debounce: float = 0.1) -> None:
+        self._debounce = debounce
+        self._pending: list[Path] = []
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._flush_callback: Any = None
+
+    def set_callback(self, callback: Any) -> None:
+        self._flush_callback = callback
+
+    def add(self, paths: list[Path]) -> None:
+        with self._lock:
+            self._pending.extend(paths)
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(self._debounce, self._flush)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _flush(self) -> None:
+        with self._lock:
+            paths = list(self._pending)
+            self._pending.clear()
+            self._timer = None
+        if paths and self._flush_callback:
+            self._flush_callback(paths)
+
+
+# ---------------------------------------------------------------------------
+# DevServer
+# ---------------------------------------------------------------------------
+
+
+class DevServer:
+    """Watches templates and content, re-renders on change.
+
+    Tries ``watchfiles`` (Rust-based) for performance, falls back to
+    stdlib polling.  Dispatches smart reload actions:
+
+    - ``@@CSS_RELOAD`` for style-only changes
+    - ``@@HOT_RELOAD`` for everything else
+
+    Usage::
+
+        dev = DevServer(
+            app,
+            watch_dirs=("templates", "content", "static"),
+            debounce=0.15,
+        )
+        dev.run()
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        watch_dirs: tuple[str | Path, ...] = (),
+        extensions: frozenset[str] | None = None,
+        poll_interval: float = 0.5,
+        debounce: float = 0.1,
+    ) -> None:
+        self._app = app
+        self._watch_dirs = tuple(Path(d) for d in watch_dirs)
+        self._extensions = extensions
+        self._poll_interval = poll_interval
+        self._stop = threading.Event()
+        self._batcher = _ChangeBatcher(debounce=debounce)
+        self._batcher.set_callback(self._on_changes)
+
+    def run(self) -> Any:
+        """Run app with hot-reload enabled."""
+        watcher = _make_watcher(
+            self._watch_dirs,
+            extensions=self._extensions,
+            poll_interval=self._poll_interval,
+        )
+
+        thread = threading.Thread(
+            target=watcher.watch,
+            args=(self._batcher.add, self._stop),
+            daemon=True,
+        )
+        thread.start()
+
+        sys.stderr.write("[milo] dev server started, watching for changes\n")
+
+        try:
+            return self._app.run()
+        finally:
+            self._stop.set()
+
+    def _on_changes(self, paths: list[Path]) -> None:
+        """Dispatch appropriate reload action for changed files."""
+        style_only = all(p.suffix in _STYLE_EXTENSIONS for p in paths)
+        action_type = "@@CSS_RELOAD" if style_only else "@@HOT_RELOAD"
+
+        for path in paths:
+            sys.stderr.write(f"[milo] changed: {path.name}\n")
+
+        try:
+            if hasattr(self._app, "_store"):
+                filenames = [str(p) for p in paths]
+                self._app._store.dispatch(Action(action_type, payload=filenames))
+        except Exception as e:
+            sys.stderr.write(f"[milo] reload error: {e}\n")