Usages:
  convention: .goga/usages/conventions.md

Annotations: |
  The `convention` practice is used for:
  - Working with the codebase
  - Organizing the REPL development cycle
  - Debugging and testing
  - Organizing the test infrastructure
  - Understanding the general principles and rules of development and testing in the project

  This cell is the single source of truth for detecting AI-agent credential files
  on the host filesystem. It exposes one pure routine that scans a fixed table of
  known credential paths and returns the ones that exist. The result drives
  read-only bind-mounts assembled by the consumers (goga/commands/build,
  goga/commands/pipeline).

---

"resolve_credential_mounts() -> mounts: list[tuple[str, str]]":
  location: resolve.py
  annotations: |
    Detect all AI-agent credential files present on the host filesystem and
    return them as host→container path pairs for read-only bind-mounting.

    `mounts`: list of (host_path, container_path) tuples for every credential
              file that exists on the host. Empty when none exist. Order matches
              the path table below.

    Apply the `convention` practice for docstring style and intra-package imports.

    Algorithm:
    1. For each row of the fixed credential path table below, expand the leading
       ~ to the current user's home and check the file exists on the host
    2. When the file exists, append the (host_path, container_path) pair to the
       result
    3. Return the result in the table order

    Credential path table (container paths mirror the host layout under
    /home/goga so the in-container CLI finds each file by the same code path):

    | agent    | host_path                                  | container_path                                     |
    |----------|--------------------------------------------|----------------------------------------------------|
    | claude   | ~/.claude/.credentials.json                | /home/goga/.claude/.credentials.json               |
    | codex    | ~/.codex/auth.json                         | /home/goga/.codex/auth.json                        |
    | opencode | ~/.local/share/opencode/auth.json          | /home/goga/.local/share/opencode/auth.json         |

    Requirements:
    - Detection is host-filesystem-only: read paths via Path.exists(); no content
      validation, no parsing
    - Container paths mirror the host layout under /home/goga so the in-container
      CLI locates each credential file through its native lookup logic
    - Return order is deterministic and matches the path table order
    - All three agents are checked unconditionally; detection does NOT depend on
      which agent a particular build/pipeline stage uses — pipeline stages may
      use different agents, and consumer-side filtering by agent would break
      multi-stage pipelines
    - The path table is a single constant source — updating one path is a one-line
      change

    Constraints:
    - Do not take an agent parameter — detection is agent-agnostic by design
    - Do not validate credential file contents (token format, expiry) — only
      existence
    - Do not whitelist, blacklist, or otherwise filter by agent name
    - Do not mutate the filesystem — detection is read-only
    - Do not surface missing credentials as an error — absence simply means the
      tuple is not returned; consumers tolerate an empty list
    - macOS Keychain caveat for claude: when web-login stores the token in
      Keychain, ~/.claude/.credentials.json is auto-deleted and detection
      returns no claude tuple. This is a known limitation; the user must create
      the file manually (or use ANTHROPIC_API_KEY env-var via the consumer's
      -e/--env option) to enable claude credential-mounting on macOS.

---

Author: Goga
CreatedAt: 07/07/26
Description: |
  Agent tooling area — credential file detection. Owns the routine that scans
  the host filesystem for known AI-agent credential files and returns the
  host→container path pairs consumed by host-side docker launchers.
