2025-11-10: Unified Context Handling Design

Date: 2025-11-10 | Issue: #78 | JIRA: DEVAI-402

Deprecated: .env file storage

This design note describes the original implementation using .env files for credential storage. As of v0.4.0, tdx uses the system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for secure credential storage instead. The .env file approach is deprecated.

Summary

The unified context system provides a predictable, layered approach to configuration that reduces repeated command flags, eliminates hidden state, and provides a consistent user experience.

Context Resolution Order

1. CLI flags (--database, --parent-segment, --llm-project, etc.)
2. Session context (PID-scoped; set via `tdx use ...`)
3. Project config (tdx.json in project root)
4. Profile config (~/.config/tdx/profiles/<name>/tdx.json)
5. Global config (~/.config/tdx/tdx.json)
6. Built-in defaults

Profiles

Long-lived account settings stored at:

~/.config/tdx/profiles/<name>/tdx.json  (configuration)
~/.config/tdx/profiles/<name>/.env      (credentials - 0600 permissions)

Profile Configuration

{
  "site": "us01",
  "database": "customer360",
  "llm_project": "Analytics",
  "llm_agent": "DataAnalyst"
}

Project Config

Per-project defaults in project/tdx.json:

{
  "database": "customer360",
  "parent_segment": "blue_users",
  "llm_project": "CustomerAnalytics"
}

Security

Project config files should NEVER contain API keys.

Session Context

PID-based session stored at ~/.config/tdx/sessions/<ppid>.json:

tdx use database analytics
tdx use parent_segment vip_users
tdx use llm_project Growth

Credential Resolution

When --profile is specified:

1. TDX_API_KEY_<PROFILE> environment variable
2. Profile keychain credential
3. TDX_API_KEY environment variable
4. TD_API_KEY environment variable (deprecated)

When no profile:

1. TDX_API_KEY environment variable
2. Default keychain credential
3. TD_API_KEY environment variable (deprecated)

Profile name normalization

Profile names are normalized for environment variable names: converted to uppercase with non-alphanumeric characters replaced by underscores. For example, my-test-profile becomes MY_TEST_PROFILE.

Commands

# Show current context
tdx use

# Show resolution sources
tdx use --debug

# Set session values
tdx use database <name>
tdx use profile <name>

# Clear session
tdx use --clear

# List profiles
tdx profiles

File Structure

~/.config/tdx/
  tdx.json                  # Global config
  .env                      # Global credentials

  profiles/
    production/
      tdx.json
      .env
    development/
      tdx.json
      .env

  sessions/
    12345.json              # PID-based session