# Libraries and Dependencies

This document explains why `awspipe` depends on its current runtime libraries and what to watch out for when changing them.

## Core Runtime Dependencies

### `typer`

- Defines the CLI command tree.
- Good fit for a small command-oriented app with typed options.
- Changes here affect command names, help output, and test expectations in `tests/test_cli.py`.

### `rich`

- Handles formatted console output, tables, JSON display, and error panels.
- Useful because the project is CLI-first and needs readable human output.
- Output formatting changes can break CLI tests and should stay predictable.

### `prompt_toolkit`

- Powers the interactive shell.
- Isolated mostly to `awspipe.repl`.
- If replaced, the dot-command workflow needs to remain intact.

### `duckdb`

- Executes SQL and stores the local cache.
- Central to `awspipe.backend` and indirectly to the whole query path.
- Important caveats:
  - file locking can appear when multiple processes share one cache file
  - schema and DDL choices should stay simple enough that a future backend abstraction is still realistic

### `sqlglot`

- Parses SQL and extracts referenced table names.
- Used to avoid fetching every provider on every query.
- Any parser change must preserve current CTE handling and supported query shapes.

### `platformdirs`

- Determines the default cache location.
- Works with `awspipe.paths`, which also includes a local fallback for restricted Windows environments.

## AWS Dependencies

### `boto3`

- Main AWS SDK entrypoint.
- Used for session creation and service clients.
- Credential resolution behavior is inherited from the botocore stack.

### `botocore`

- Underlies credential loading and AWS API behavior.
- Important because profile support details and auth exceptions come from here.
- Changes here can affect live validation even when application code is unchanged.

### `awscrt`

- Required for `login_session`-based AWS profiles.
- This is not optional in practice for this repo because live validation already depends on it.
- If removed, login-backed profiles will fail during credential resolution.

## Test Dependency

### `pytest`

- Main test runner.
- The repo config pins `--basetemp=.pytest_tmp` because default temp resolution can fail in restricted Windows environments.

## Dependency Policy

- Prefer small, well-scoped libraries over custom framework layers.
- Do not add a dependency when an existing project dependency already covers the need.
- If a new dependency changes runtime assumptions, document it in `README.md`, `AGENTS.md`, and this file.
- If a dependency is needed only for a specific AWS profile or runtime edge case, note that explicitly so later cleanup does not break live testing.

## Review Checklist for Dependency Changes

- Does the new dependency alter installation or authentication expectations?
- Does it affect Windows support?
- Does it require doc changes in more than one place?
- Does it change CLI output or cache behavior enough to require test updates?
