Imports:
  - Types:
      - Config
      - load_config
    Usages:
      - configuration
    From: goga/config

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

Annotations: |
  The `conventions` practice is used for:
  - working with the codebase
  - organizing the REPL development cycle
  - debugging and testing
  - organizing test infrastructure
  - understanding general development and testing principles/rules in the project
  Use the `click` practice to create the command.
  The command runs goga.build inside a Docker container.

---

"build(plan: str)":
  location: build.py
  annotations: |
    CLI wrapper for the build command. Runs python -m goga.build inside a Docker container.

    `plan`: path to the plan file

    CLI options (via click):
    - --dry-run, --worktree, --skip-finalize, --skip-manifest-check
    - --session-timeout, --idle-timeout, --wait
    - --max-iterations, --review-patience
    - -e / --env KEY=VALUE (multiple) — pass environment variables to the container

    Algorithm:
    0. (pre-check) Verify docker availability via _check_docker()
       If docker is not found — ClickException error
    1. Load configuration via `load_config` (practice `configuration`) → get `Config`
    2. Collect cli_flags from click parameters
    3. Read git config (user.name, user.email):
       - Execute git config user.name and git config user.email
       - On success — return dict with GIT_AUTHOR_NAME/EMAIL, GIT_COMMITTER_NAME/EMAIL
       - On error or absence of git — return empty dict (do not block the build)
    4. Write env-file:
       - env = task_executor.env + git_env (git_env does not overwrite task_executor.env)
       - + extra_env from CLI
       - File with 0600 permissions in a temporary directory
    5. Check config.build.image:
       If None — ClickException error("image in .goga/config.yml is not set")
    6. Generate container_name: "goga-build-{pid}"
    7. Set SIGTERM handler: on signal — SystemExit(128 + signum)
    8. Assemble Docker command:
       - docker run --rm --name container_name --entrypoint python3
       - Mount CWD as /workspace
       - --env-file for passing variables
       - If ~/.codex/auth.json exists — mount read-only as /home/goga/.codex/auth.json
       - Image from `Config`.build.image
       - Arguments: -m goga.build <plan> + CLI flags
    9. On dry_run: exit 0 (without running the container)
    10. Run Docker via subprocess.Popen, wait for exit code via .wait()
    11. In finally:
        a. Delete env-file
        b. Execute docker kill container_name (suppress errors)
        c. Restore previous SIGTERM handler

---

Author: Goga
CreatedAt: 20/05/26

Description: |
  CLI wrapper for the goga build command