Lazy-validate AAI_AUTH_PORT to prevent import-time crashes

[alexkroman]

Summary

Refactor the loopback port configuration to validate AAI_AUTH_PORT lazily at call time rather than at module import time. This prevents malformed environment variables from crashing every CLI command (even --help) with a raw ValueError, instead surfacing clean CLIError exceptions only on the login path.

Key Changes

• aai_cli/auth/endpoints.py

  • Replace module-level LOOPBACK_PORT = int(os.environ.get(...)) with a loopback_port() function that validates on demand
  • Add _invalid_auth_port() helper to emit clean CLIError (exit code 2) with actionable suggestions
  • Validate port range (1–65535 inclusive); reject 0 and out-of-range values
  • Catch ValueError from non-integer input and re-raise as CLIError to avoid raw exceptions at import time
  • Update redirect_uri() to call loopback_port() instead of referencing the constant

• aai_cli/auth/loopback.py

  • Call loopback_port() once at the start of capture_callback() and reuse the result to avoid redundant validation

• tests/test_auth_endpoints.py

  • Add comprehensive validation tests:
    • test_loopback_port_rejects_non_integer() — typo'd port surfaces as clean CLIError
    • test_loopback_port_rejects_above_max() — reject 65536+
    • test_loopback_port_accepts_boundary_values() — accept 1 and 65535
    • test_loopback_port_rejects_zero() — reject OS-assigned port 0
  • Update test_env_override_changes_redirect_uri() to use monkeypatch.setenv() instead of direct attribute patching

• tests/test_auth_loopback.py

  • Replace monkeypatch.setattr(endpoints, "LOOPBACK_PORT", ...) with monkeypatch.setenv("AAI_AUTH_PORT", ...) throughout
  • Update all endpoints.LOOPBACK_PORT references to call endpoints.loopback_port()

• aai_cli/init/runner.py

  • Fix file descriptor leak in spawn(): close the log file handle immediately after Popen returns (the child process retains its own duplicate), preventing the fd from being held open for the process's entire lifetime

• tests/test_init_runner.py

  • Update assertions to verify the file is closed after spawn() returns, confirming the leak is fixed

Implementation Details

The lazy validation approach ensures that:

• Module import succeeds even with a malformed AAI_AUTH_PORT
• Only commands that actually call loopback_port() (i.e., aai login) trigger validation
• Invalid configuration surfaces as a user-friendly CLIError with exit code 2 and a suggestion, not a raw traceback
• The module sits on the CLI's hot import path, so this prevents every command from crashing on startup

https://claude.ai/code/session_01AsrPL95Kr31qCfvfb1Lkaz