forest-cli 0.1.0__py3-none-any.whl

forest/config.py

@@ -0,0 +1,286 @@
+"""Configuration models and loaders for forest.yaml and .forest/local.yaml."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+from forest.fsutil import atomic_write
+
+
+class ConfigError(Exception):
+    """Raised for configuration loading or validation errors."""
+
+
+LEGACY_TRANSPORT_WARNING = "transport: config is obsolete (rclone replaces backends); ignoring"
+_transport_warning_emitted = False
+
+
+class RemoteConfig(BaseModel):
+    """Configuration for a single named remote."""
+
+    url: str
+    region: str | None = None
+    endpoint: str | None = None
+    profile: str | None = None
+    key_file: str | None = None
+    known_hosts: str | None = None
+
+    @property
+    def remote_type(self) -> str:
+        """Infer remote type from URL pattern."""
+        if self.url.startswith("s3://"):
+            return "s3"
+        if self.url.startswith("sftp://"):
+            return "sftp"
+        if self.url.startswith("/"):
+            return "local"
+        if re.match(r"[^:@/]+@.+:.+", self.url):
+            return "sftp"
+        return "unknown"
+
+
+class StageConfig(BaseModel):
+    """Configuration for a single data stage."""
+
+    path: Path | None = None
+    remote_path: Path | None = None
+    schema_: str | None = Field(default=None, alias="schema")
+    sync_by: Literal["directory", "subdirectory", "file"] = "subdirectory"
+
+    model_config = {"populate_by_name": True}
+
+    @field_validator("path", mode="before")
+    @classmethod
+    def _coerce_path(cls, v: object) -> Path | None:
+        if v is None:
+            return None
+        return Path(str(v))
+
+    @field_validator("remote_path", mode="before")
+    @classmethod
+    def _coerce_remote_path(cls, v: object) -> Path | None:
+        if v is None:
+            return None
+        return Path(str(v))
+
+
+class ManifestConfig(BaseModel):
+    """Configuration for the manifest CSV."""
+
+    file: Path
+    id_column: str
+    stage_columns: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("file", mode="before")
+    @classmethod
+    def _coerce_file(cls, v: object) -> Path:
+        if v is None:
+            raise ValueError("Manifest file path must not be null")
+        return Path(str(v))
+
+
+class ProjectConfig(BaseModel):
+    """Top-level project configuration from forest.yaml."""
+
+    project: str
+    remotes: dict[str, RemoteConfig] = Field(default_factory=dict)
+    stages: dict[str, StageConfig]
+    manifest: ManifestConfig | None = None
+
+
+class LocalConfig(BaseModel):
+    """Local state from .forest/local.yaml."""
+
+    active_remote: str | None = None
+    stage_paths: dict[str, Path] = Field(default_factory=dict)
+
+    @field_validator("stage_paths", mode="before")
+    @classmethod
+    def _coerce_stage_paths(cls, v: object) -> object:
+        if v is None:
+            return {}
+        if not isinstance(v, dict):
+            return v
+
+        coerced: dict[str, Path] = {}
+        for name, path in v.items():
+            if path is None:
+                raise ValueError(f"Stage path for {name!r} must not be null")
+            if not isinstance(path, (str, Path)):
+                raise TypeError(f"Stage path for {name!r} must be a string path")
+            coerced[str(name)] = Path(path)
+        return coerced
+
+
+def _drop_legacy_transport_blocks(data: dict[str, object]) -> None:
+    """Drop obsolete per-remote ``transport`` blocks, warning once per process."""
+    remotes = data.get("remotes")
+    if not isinstance(remotes, dict):
+        return
+
+    found_legacy_transport = False
+    for remote_data in remotes.values():
+        if isinstance(remote_data, dict) and "transport" in remote_data:
+            remote_data.pop("transport", None)
+            found_legacy_transport = True
+
+    global _transport_warning_emitted
+    if found_legacy_transport and not _transport_warning_emitted:
+        print(LEGACY_TRANSPORT_WARNING, file=sys.stderr, flush=True)
+        _transport_warning_emitted = True
+
+
+def load_config(path: Path) -> ProjectConfig:
+    """Load and validate a forest.yaml configuration file.
+
+    Raises ConfigError with a clear message for missing files,
+    invalid YAML, or validation failures.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise ConfigError(f"Configuration file not found: {path}")
+
+    try:
+        raw = path.read_text()
+    except OSError as exc:
+        raise ConfigError(f"Cannot read configuration file {path}: {exc}") from None
+
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in {path}: {exc}") from None
+
+    if data is None:
+        raise ConfigError(f"Configuration file is empty: {path}")
+
+    if not isinstance(data, dict):
+        raise ConfigError(f"Expected a dict in {path}, got {type(data).__name__}")
+
+    _drop_legacy_transport_blocks(data)
+
+    try:
+        return ProjectConfig(**data)
+    except Exception as exc:
+        raise ConfigError(f"Invalid configuration in {path}: {exc}") from None
+
+
+def load_local_config(project_root: Path) -> LocalConfig:
+    """Load .forest/local.yaml from the project root.
+
+    Returns a LocalConfig with active_remote=None if the file doesn't exist.
+    Raises ConfigError for malformed content or validation failures.
+    """
+    local_path = Path(project_root) / ".forest" / "local.yaml"
+    return load_local_config_file(local_path)
+
+
+def load_local_config_file(local_path: Path) -> LocalConfig:
+    """Load a LocalConfig from an explicit local.yaml path."""
+    local_path = Path(local_path)
+    if not local_path.exists():
+        return LocalConfig()
+
+    try:
+        raw = local_path.read_text()
+    except OSError as exc:
+        raise ConfigError(f"Cannot read local config {local_path}: {exc}") from None
+
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in {local_path}: {exc}") from None
+
+    if data is None:
+        return LocalConfig()
+
+    if not isinstance(data, dict):
+        raise ConfigError(f"Expected a dict in {local_path}, got {type(data).__name__}")
+
+    try:
+        return LocalConfig(**data)
+    except Exception as exc:
+        raise ConfigError(f"Invalid local config in {local_path}: {exc}") from None
+
+
+def _remote_yaml_entry(remote: RemoteConfig) -> dict[str, str]:
+    """Serialize a RemoteConfig to its forest.yaml mapping, omitting unset fields."""
+    entry = {"url": remote.url}
+    optional_fields = {
+        "region": remote.region,
+        "endpoint": remote.endpoint,
+        "profile": remote.profile,
+        "key_file": remote.key_file,
+        "known_hosts": remote.known_hosts,
+    }
+    entry.update({key: value for key, value in optional_fields.items() if value is not None})
+    return entry
+
+
+def _stage_yaml_entry(stage: StageConfig, *, include_stage_paths: bool) -> dict[str, object]:
+    """Serialize a StageConfig to its forest.yaml mapping."""
+    s_data: dict[str, object] = {}
+    if include_stage_paths and stage.path is not None:
+        s_data["path"] = str(stage.path)
+    if stage.remote_path is not None:
+        s_data["remote_path"] = str(stage.remote_path)
+    s_data["schema"] = stage.schema_
+    if stage.sync_by != "subdirectory":
+        s_data["sync_by"] = stage.sync_by
+    return s_data
+
+
+def _manifest_yaml_entry(manifest: ManifestConfig) -> dict[str, object]:
+    """Serialize a ManifestConfig to its forest.yaml mapping."""
+    m_data: dict[str, object] = {
+        "file": str(manifest.file),
+        "id_column": manifest.id_column,
+    }
+    if manifest.stage_columns:
+        m_data["stage_columns"] = manifest.stage_columns
+    return m_data
+
+
+def save_config(config: ProjectConfig, path: Path, *, include_stage_paths: bool = True) -> None:
+    """Save ProjectConfig to a forest.yaml file.
+
+    Serializes the Pydantic model to a clean YAML representation,
+    converting Path objects to strings and using the 'schema' alias.
+    """
+    data: dict[str, object] = {"project": config.project}
+
+    if config.remotes:
+        data["remotes"] = {name: _remote_yaml_entry(remote) for name, remote in config.remotes.items()}
+
+    data["stages"] = {
+        name: _stage_yaml_entry(stage, include_stage_paths=include_stage_paths) for name, stage in config.stages.items()
+    }
+
+    if config.manifest is not None:
+        data["manifest"] = _manifest_yaml_entry(config.manifest)
+
+    atomic_write(Path(path), yaml.dump(data, default_flow_style=False, sort_keys=False))
+
+
+def save_local_config(config: LocalConfig, project_root: Path) -> None:
+    """Save LocalConfig to .forest/local.yaml in the project root.
+
+    Creates the .forest/ directory if it doesn't exist.
+    """
+    local_path = Path(project_root) / ".forest" / "local.yaml"
+    save_local_config_file(config, local_path)
+
+
+def save_local_config_file(config: LocalConfig, local_path: Path) -> None:
+    """Save LocalConfig to an explicit local.yaml path."""
+    data: dict[str, object] = {
+        "active_remote": config.active_remote,
+        "stage_paths": {name: str(path) for name, path in config.stage_paths.items()},
+    }
+
+    atomic_write(Path(local_path), yaml.dump(data, default_flow_style=False, sort_keys=False))

forest/flags.py

@@ -0,0 +1,20 @@
+"""Feature flags for forest, read from the ``FOREST_FLAGS`` environment variable.
+
+``FOREST_FLAGS`` is a comma-separated list of flag names, e.g.
+``FOREST_FLAGS=raw-logs``. Unknown names are harmless; unset means no flags.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def enabled_flags() -> frozenset[str]:
+    """Return the set of flag names enabled via ``FOREST_FLAGS``."""
+    raw = os.environ.get("FOREST_FLAGS", "")
+    return frozenset(name.strip() for name in raw.split(",") if name.strip())
+
+
+def is_enabled(name: str) -> bool:
+    """Return True when the named feature flag is enabled."""
+    return name in enabled_flags()

forest/flow.py

@@ -0,0 +1,157 @@
+"""Mermaid graph helpers for the ``forest flow`` command."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from forest.config import ProjectConfig, StageConfig
+
+
+@dataclass(frozen=True)
+class FlowNode:
+    """A Mermaid node."""
+
+    id: str
+    label: str
+
+
+@dataclass(frozen=True)
+class FlowEdge:
+    """A Mermaid edge."""
+
+    source: str
+    target: str
+    label: str | None = None
+
+
+def _add_node(nodes: dict[str, FlowNode], raw_id: str, label: str) -> str:
+    node_id = _node_id(raw_id)
+    nodes.setdefault(node_id, FlowNode(node_id, label))
+    return node_id
+
+
+def _add_stage_flow(
+    nodes: dict[str, FlowNode],
+    edges: list[FlowEdge],
+    config: ProjectConfig,
+    stage_name: str,
+    stage: StageConfig,
+    *,
+    project_id: str,
+    manifest_id: str | None,
+    state_id: str | None,
+    remote_ids: dict[str, str],
+    active_remote: str | None,
+    stage_outputs: dict[str, str],
+    stage_units: list[tuple[str, str | None, str | None]],
+) -> None:
+    """Add one stage's nodes and edges (manifest, sync, outputs, units)."""
+    stage_label = f"stage: {stage_name}\npath: {stage.path}\nschema: {stage.schema_ or 'none'}"
+    stage_id = _add_node(nodes, f"stage_{stage_name}", stage_label)
+    edges.append(FlowEdge(project_id, stage_id))
+
+    if manifest_id is not None and config.manifest is not None and stage_name in config.manifest.stage_columns:
+        edges.append(FlowEdge(manifest_id, stage_id, config.manifest.stage_columns[stage_name]))
+
+    if active_remote is not None and active_remote in remote_ids:
+        edges.append(FlowEdge(stage_id, remote_ids[active_remote], "sync"))
+        if state_id is not None:
+            edges.append(FlowEdge(stage_id, state_id, "records"))
+
+    for output_name, output_path in stage_outputs.items():
+        output_id = _add_node(nodes, f"output_{stage_name}_{output_name}", f"output: {output_name}\n{output_path}")
+        edges.append(FlowEdge(stage_id, output_id))
+
+    _add_stage_units(nodes, edges, stage_id, stage_name, stage_units)
+
+
+def _add_stage_units(
+    nodes: dict[str, FlowNode],
+    edges: list[FlowEdge],
+    stage_id: str,
+    stage_name: str,
+    stage_units: list[tuple[str, str | None, str | None]],
+) -> None:
+    for uid, local_path, remote_path in stage_units:
+        unit_id = _add_node(nodes, f"unit_{stage_name}_{uid}", f"unit: {uid}")
+        edges.append(FlowEdge(stage_id, unit_id))
+        if local_path is not None:
+            local_id = _add_node(nodes, f"local_{stage_name}_{uid}", f"local: {local_path}")
+            edges.append(FlowEdge(unit_id, local_id))
+        if remote_path is not None:
+            remote_path_id = _add_node(nodes, f"remote_path_{stage_name}_{uid}", f"remote: {remote_path}")
+            edges.append(FlowEdge(unit_id, remote_path_id))
+
+
+def build_graph(
+    config: ProjectConfig,
+    *,
+    active_remote: str | None = None,
+    has_state: bool = False,
+    expanded_units: dict[str, list[tuple[str, str | None, str | None]]] | None = None,
+    key_outputs: dict[str, dict[str, str]] | None = None,
+) -> tuple[list[FlowNode], list[FlowEdge]]:
+    """Build a project data-flow graph from resolved config state."""
+    nodes: dict[str, FlowNode] = {}
+    edges: list[FlowEdge] = []
+
+    project_id = _add_node(nodes, "project", f"project: {config.project}")
+
+    manifest_id: str | None = None
+    if config.manifest is not None:
+        manifest_id = _add_node(nodes, "manifest", f"manifest: {config.manifest.file}")
+        edges.append(FlowEdge(manifest_id, project_id, config.manifest.id_column))
+
+    state_id = _add_node(nodes, "sync_state", ".forest/sync_state.json") if has_state else None
+
+    remote_ids: dict[str, str] = {}
+    for name, remote in sorted(config.remotes.items()):
+        label = f"remote: {name}\n{remote.url}"
+        if name == active_remote:
+            label += "\nactive"
+        remote_ids[name] = _add_node(nodes, f"remote_{name}", label)
+
+    for stage_name, stage in sorted(config.stages.items()):
+        _add_stage_flow(
+            nodes,
+            edges,
+            config,
+            stage_name,
+            stage,
+            project_id=project_id,
+            manifest_id=manifest_id,
+            state_id=state_id,
+            remote_ids=remote_ids,
+            active_remote=active_remote,
+            stage_outputs=(key_outputs or {}).get(stage_name, {}),
+            stage_units=(expanded_units or {}).get(stage_name, []),
+        )
+
+    return list(nodes.values()), edges
+
+
+def render_mermaid(nodes: list[FlowNode], edges: list[FlowEdge], *, direction: str = "LR") -> str:
+    """Render Mermaid flowchart text."""
+    lines = [f"flowchart {direction}"]
+    for node in nodes:
+        lines.append(f'    {node.id}["{_escape_label(node.label)}"]')
+    for edge in edges:
+        label = f"|{_escape_label(edge.label)}|" if edge.label else ""
+        lines.append(f"    {edge.source} -->{label} {edge.target}")
+    return "\n".join(lines)
+
+
+def _node_id(value: str) -> str:
+    node_id = re.sub(r"[^0-9A-Za-z_]", "_", value).strip("_")
+    if not node_id:
+        return "node"
+    if node_id[0].isdigit():
+        return f"n_{node_id}"
+    return node_id
+
+
+def _escape_label(label: str | None) -> str:
+    if label is None:
+        return ""
+    return label.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "<br/>")

forest/fsutil.py

@@ -0,0 +1,36 @@
+"""Filesystem primitives shared across forest modules.
+
+Kept dependency-free (stdlib only) so ``config`` and ``sync_state`` can import
+``atomic_write`` at module top level without a circular import back through
+``checkout``.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+
+
+def atomic_write(path: str | Path, text: str) -> None:
+    """Atomically write text to *path* via same-directory temp file and os.replace."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    existing_mode = None
+    if target.exists():
+        existing_mode = target.stat().st_mode & 0o777
+    fd, temp_name = tempfile.mkstemp(prefix=f".{target.name}.", suffix=".tmp", dir=str(target.parent))
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if existing_mode is not None:
+            os.chmod(temp_path, existing_mode)
+        os.replace(temp_path, target)
+    except BaseException:
+        with suppress(FileNotFoundError):
+            temp_path.unlink()
+        raise

forest/logger.py

@@ -0,0 +1,197 @@
+"""Structured logging with run-scoped trace IDs for forest.
+
+Every CLI invocation gets a short ``run_id`` that is stamped onto every log
+record emitted anywhere in the package (see :class:`_RunIdFilter`), onto every
+metric sample (``forest.metrics``), and onto every alert/error report
+(``forest.monitoring``). Grep one run_id across all three sinks to follow a
+single invocation end to end, including through the rclone subprocess calls it
+spawned.
+
+Logging is silent by default so the click-based UX and stdout/stderr contracts
+stay untouched. It activates only through environment variables:
+
+- ``FOREST_LOG_FILE``: append logs to this file (JSON lines by default).
+- ``FOREST_LOG_FORMAT``: ``json`` or ``text``; setting it without
+  ``FOREST_LOG_FILE`` sends logs to stderr.
+- ``FOREST_LOG_LEVEL``: standard level name, default ``INFO``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+import uuid
+from contextvars import ContextVar
+from datetime import datetime, timezone
+from typing import Any
+
+from forest import flags
+
+_RUN_ID: ContextVar[str] = ContextVar("forest_run_id", default="")
+
+_ROOT_LOGGER_NAME = "forest"
+
+# LogRecord attributes that are not user-supplied "extra" fields.
+_STANDARD_RECORD_ATTRS = frozenset(vars(logging.LogRecord("", 0, "", 0, "", (), None)).keys()) | {
+    "message",
+    "asctime",
+    "taskName",
+}
+
+_REDACTED = "[REDACTED]"
+
+# Ordered secret-shaped substring patterns applied by scrub(). Order matters:
+# PEM blocks and URL credentials go first so the generic key=value rule never
+# mangles them halfway.
+_SECRET_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (
+        re.compile(
+            r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?(?:-----END [A-Z ]*PRIVATE KEY-----|\Z)",
+            re.DOTALL,
+        ),
+        "[REDACTED PRIVATE KEY]",
+    ),
+    # URL credentials, including sentry DSN key@host forms.
+    (re.compile(r"://[^/\s@]+@"), "://[REDACTED]@"),
+    (re.compile(r"(?i)\b(authorization|x-api-key)\b\s*[:=]\s*(?:basic |bearer )?\S+"), r"\1: [REDACTED]"),
+    (
+        re.compile(
+            r"(?i)\b(password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key(?:[_-]?id)?"
+            r"|session[_-]?token|private[_-]?key)\b\s*[=:]\s*\S+"
+        ),
+        r"\1=[REDACTED]",
+    ),
+    # Bare AWS access key ids.
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), _REDACTED),
+)
+
+_SECRET_KEY_RE = re.compile(
+    r"(?i)(password|passwd|secret|token|api[_-]?key|access[_-]?key|authorization|dsn|private[_-]?key|credential)"
+)
+
+
+def scrub(text: str) -> str:
+    """Redact secret-shaped substrings (keys, tokens, URL credentials) from text."""
+    for pattern, replacement in _SECRET_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def scrub_obj(value: Any) -> Any:
+    """Recursively scrub strings; redact dict values whose key looks secret."""
+    if isinstance(value, str):
+        return scrub(value)
+    if isinstance(value, dict):
+        return {
+            key: _REDACTED if isinstance(key, str) and _SECRET_KEY_RE.search(key) else scrub_obj(val)
+            for key, val in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [scrub_obj(item) for item in value]
+    return value
+
+
+def new_run_id() -> str:
+    """Create and activate a fresh trace ID for this invocation."""
+    run_id = uuid.uuid4().hex[:12]
+    _RUN_ID.set(run_id)
+    return run_id
+
+
+def get_run_id() -> str:
+    """Return the active trace ID, creating one lazily if needed."""
+    run_id = _RUN_ID.get()
+    if not run_id:
+        run_id = new_run_id()
+    return run_id
+
+
+class _RunIdFilter(logging.Filter):
+    """Stamp the active run_id onto every record so traces survive fan-out."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.run_id = get_run_id()
+        return True
+
+
+class _ScrubFilter(logging.Filter):
+    """Scrub the message and every string ``extra`` field on each record.
+
+    Known limitation: tracebacks rendered by the text formatter are not
+    scrubbed; the JSON formatter scrubs ``exc_info`` itself.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = scrub(record.getMessage())
+        record.args = None
+        for key, value in record.__dict__.items():
+            if key not in _STANDARD_RECORD_ATTRS and isinstance(value, str):
+                setattr(record, key, scrub(value))
+        return True
+
+
+class JsonFormatter(logging.Formatter):
+    """Render records as single-line JSON objects (one event per line)."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "event": record.getMessage(),
+            "run_id": getattr(record, "run_id", ""),
+        }
+        for key, value in record.__dict__.items():
+            if key in _STANDARD_RECORD_ATTRS or key in payload:
+                continue
+            payload[key] = value if isinstance(value, (str, int, float, bool, type(None))) else repr(value)
+        if record.exc_info:
+            payload["exc_info"] = scrub(self.formatException(record.exc_info))
+        return json.dumps(payload, default=str)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a logger under the ``forest`` hierarchy (e.g. ``forest.rclone``)."""
+    if name == _ROOT_LOGGER_NAME or name.startswith(_ROOT_LOGGER_NAME + "."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"{_ROOT_LOGGER_NAME}.{name}")
+
+
+def configure_logging(*, verbose: bool = False) -> None:
+    """(Re)configure the package logger from the environment. Idempotent.
+
+    Without ``FOREST_LOG_FILE`` or ``FOREST_LOG_FORMAT`` the logger stays on a
+    NullHandler: no output, no behavioral change for existing users or tests.
+    """
+    root = logging.getLogger(_ROOT_LOGGER_NAME)
+    root.propagate = False
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+        existing.close()
+
+    log_file = os.environ.get("FOREST_LOG_FILE")
+    log_format = os.environ.get("FOREST_LOG_FORMAT")
+    if not log_file and not log_format:
+        root.addHandler(logging.NullHandler())
+        return
+
+    handler: logging.Handler
+    handler = logging.FileHandler(log_file, encoding="utf-8") if log_file else logging.StreamHandler(sys.stderr)
+
+    if (log_format or "json").lower() == "text":
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s [%(run_id)s] %(message)s"))
+    else:
+        handler.setFormatter(JsonFormatter())
+    handler.addFilter(_RunIdFilter())
+    if not flags.is_enabled("raw-logs"):
+        handler.addFilter(_ScrubFilter())
+    root.addHandler(handler)
+
+    level_name: str | None = os.environ.get("FOREST_LOG_LEVEL")
+    if level_name:
+        root.setLevel(getattr(logging, level_name.upper(), logging.INFO))
+    else:
+        root.setLevel(logging.DEBUG if verbose else logging.INFO)