refactor: centralize and validate environment configuration

[francoischalifour]

Context

Environment-variable handling was distributed across authentication, profiles, endpoint resolution, OAuth, HTTP test hooks, updater behavior, shell completion, terminal styling, and filesystem configuration.

Each caller accessed process.env independently and interpreted values locally. This created several risks:

• Environment-variable names were untyped string literals and could be misspelled without compiler feedback.
• Boolean, enum, and numeric values were parsed inconsistently.
• Invalid values could silently fall back to defaults, hiding configuration mistakes.
• Secret-bearing variables depended on manually maintained masking logic.
• Updater environment names were maintained in a separate catalog.
• New direct process.env reads could bypass validation and redaction conventions.
• Misspelled ALTERTABLE_* variables were silently ignored, potentially causing the CLI to use stored credentials or default endpoints unexpectedly.

Proposed solution

Introduce a single typed environment schema in cli/src/lib/env.ts and route all production environment access through it.

The schema uses canonical environment-variable names directly as typed keys:

readEnv("ALTERTABLE_API_KEY");
readEnv("ALTERTABLE_API_BASE");
readEnv("ALTERTABLE_UPDATE_INSTALLER");

This avoids an additional alias vocabulary and makes code search, autocomplete, error messages, and public documentation use the same names.

The centralized API provides:

• readEnv() for live, typed reads from process.env
• readEnvFrom() for typed reads from injected environments
• setEnv() and unsetEnv() for validated mutations
• copyProcessEnv() for callers that must pass through the complete environment
• validateEnvironment() for startup validation
• isSecretEnv() for safe diagnostic rendering

Reads remain lazy so existing tests and commands that mutate the environment during a process continue to behave correctly.

Validation behavior

The schema defines parsers for each supported value shape:

• Strict booleans accept true, false, 1, or 0.
• Enum variables accept only their documented values.
• ALTERTABLE_OAUTH_REDIRECT_PORT must be an integer between 0 and 65535.
• Empty optional variables are treated as unset.
• Invalid values raise ConfigurationError and retain the CLI’s stable configuration exit code, 10.

The CLI now validates every configured ALTERTABLE_* value during startup. Unknown names are rejected as well, so a typo such as ALTERTABLE_API_KEI cannot silently fall back to another credential source.

Repository and CI passthrough variables, including mock-server and Docker credentials, are explicitly registered so shared execution environments remain supported.

Secret safety

Secret metadata now lives alongside each schema definition.

Variables whose names end in credential-bearing suffixes such as _KEY, _TOKEN, _PASSWORD, or _SECRET must explicitly declare secret: true. A schema assertion runs when the module loads and throws if a credential-looking variable is added without secret metadata.

This prevents future environment variables from accidentally appearing unmasked in profile diagnostics.

Migration scope

This branch migrates environment access across:

• Management and lakehouse authentication
• Profile selection, inspection, and environment-config mode
• Management and data-plane endpoint resolution
• OAuth configuration and callback ports
• HTTP mocks and request logging
• Secret backend selection
• Configuration and XDG paths
• Shell completion installation paths
• Terminal color and hyperlink behavior
• Pager subprocess environments
• Updater source, installer, registry, and automatic-check settings

Architectural guardrails

A new test scans production modules and fails if direct process.env access is introduced outside env.ts.

Additional tests cover:

• Canonical typed environment names
• Optional-value handling
• Strict boolean parsing
• Enum validation
• OAuth port boundaries
• Unknown ALTERTABLE_* names
• Startup-wide validation
• Secret classification
• Rejection of credential-looking variables without secret metadata
• Updated strict updater behavior

Compatibility and behavior changes

Valid existing configurations retain their precedence and behavior.

Intentional changes:

• Misspelled ALTERTABLE_* names now fail with a configuration error.
• Invalid boolean, enum, and port values now fail instead of being ignored.
• Invalid updater source or installer overrides no longer silently use defaults.
• Credential-looking schema entries must be explicitly marked as secret.