from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Dict


@dataclass(frozen=True)
class StepContext:
    """
    Execution context passed to Python module step functions.

    Use `ctx.vars` for book vars, `ctx.env` for process environment, and
    `ctx.book_path`/`ctx.step_name`/`ctx.run_id` for run metadata.
    """

    vars: Dict[str, Any]
    env: Dict[str, str]
    book_path: str
    step_name: str
    run_id: str
    cwd: str
    refs: Dict[str, str] = field(default_factory=dict)

    def var(self, key: str, default: Any = None) -> Any:
        return self.vars.get(key, default)

    def require_var(self, key: str) -> Any:
        if key not in self.vars:
            raise KeyError(f"missing required var: {key}")
        return self.vars[key]


@dataclass(frozen=True)
class StepResult:
    """
    Optional structured return for Python step functions.
    """

    message: str = ""
    outputs: Dict[str, Any] = field(default_factory=dict)
