"""GitHub App permissions and webhook events reference.

Required GitHub App Permissions:
  Repository:
    - contents:      read & write  (push commits, read files, create branches)
    - pull_requests:  read & write  (create/merge PRs, read PR status)
    - metadata:       read          (repo info, branches, tags)
    - webhooks:       read          (verify delivery)
    - actions:        read          (workflow run status for CI feedback)

  Organization (if using org-level install):
    - members:        read          (verify org membership if needed)

Webhook Events to Subscribe:
  - push                 Triggered on any push to a branch. P2HS uses this to:
                         - Detect external commits and create platform revisions
                         - Sync repo state after codegen pushes
                         - Track branch HEAD for preview environments

  - pull_request         Triggered on PR open/close/merge/sync. P2HS uses this to:
                         - Track PR-based codegen results
                         - Auto-create preview environments for PRs
                         - Update codegen run status when PR is merged

  - workflow_run         Triggered when GitHub Actions workflows complete. P2HS uses this to:
                         - Track CI/CD build status
                         - Gate deployments on passing checks
                         - Report build failures to the user

  - installation         Triggered when the GitHub App is installed/uninstalled. P2HS uses this to:
                         - Record installation IDs for new orgs/users
                         - Clean up on uninstall

  - installation_repositories  Triggered when repos are added/removed from install. P2HS uses this to:
                         - Track which repos are managed by P2HS
"""

REQUIRED_PERMISSIONS = {
    "contents": "write",
    "pull_requests": "write",
    "metadata": "read",
    "actions": "read",
    "secrets": "write",   # required to inject CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID into repos
}

# Events that must be explicitly subscribed in GitHub App settings and appear
# in the GET /app response. Implicit app-level events (installation,
# installation_repositories) are NOT listed here — GitHub delivers them
# automatically without a subscription and they never appear in the events array.
SUBSCRIBED_EVENTS = [
    "push",
    "pull_request",
    "workflow_run",   # REQUIRED: enables deploy failure auto-fix and preview gating
    "workflow_job",   # optional: job-level observability
]

# Implicit events — delivered automatically by GitHub to every App.
# Listed here for documentation only; do not check against GET /app events.
IMPLICIT_EVENTS = [
    "installation",
    "installation_repositories",
]