Imports:
  - Types:
      - load_env
      - load_config
      - Config
    Usages:
      - environment
      - project-config
    From: swax/config

Usages:
  conventions: .goga/usages/conventions.md
  click: .goga/usages/cooks/click.md

Annotations: |
  CLI entry point. The top-level Click group loads the environment and initializes a
  `SwaxContext` for subcommands. Subcommands init, discover, and plan are registered lazily
  to keep the CODEMANIFEST contract acyclic (commands import from cli, not the reverse).
  Main and `SwaxContext` are exported as the cell's public API.

  Use `conventions` for code writing rules and testing.
  Use `click` for the entry-point group, the --env-file option, and the pass-object pattern.
  Use `environment` for `load_env` semantics.
  Use `project-config` for `load_config` and the `Config` shape exposed via SwaxContext.config.

---

"main(ctx: click.Context, env_file: pathlib.Path)":
  location: main.py
  annotations: |
    Top-level Click group with the --env-file option: loads the environment and initializes
    `SwaxContext` for subcommands.

    `ctx`: Click context object holding the `SwaxContext`.
    `env_file`: path to the environment file (default .env).

    Algorithm:
    1. Decorate with @click.group and the --env-file option (default .env).
    2. Decorate the callback with @click.pass_context.
    3. Call `load_env` with the resolved env_file.
    4. Set ctx.obj to a new `SwaxContext`.

    Requirements:
    - Registered as swax = "swax.cli.__main__:main" in [project.scripts].
    - Subcommands init, discover, and plan are registered in __main__.py, not in this callback.

    Constraints:
    - Do not raise on missing .env — `load_env` handles it.
    - Do not read SWAX_* variables here — validation happens lazily inside subcommands.

"SwaxContext(env_file: pathlib.Path)":
  location: swax_context.py
  annotations: |
    Click pass object carrying CLI parameters between `main` and its subcommands.

    `env_file`: path to the environment file, passed via --env-file.

    Requirements:
    - Constructed in the `main` group callback and stored as ctx.obj.
    - Subcommands receive it via @click.pass_obj.
    - The config cache starts as None — subcommands load configuration on demand via load_config.

  properties:
    "env_file -> pathlib.Path": |
      Path to the environment file. Read-only after construction — passed as input to `load_env`.
    "config -> Config | None": |
      Cached project configuration, defaults to None. Subcommands may populate it lazily via
      `load_config`; optional because init writes config rather than reading it.

---

Author: Goga
CreatedAt: 25/06/26
Description: |
  CLI entry point (Click group with --env-file) and SwaxContext pass object.
