ldap-cli 0.2.0__py3-none-any.whl

.kiro/specs/ldap-cli/tasks.md

@@ -0,0 +1,246 @@
+# Implementation Plan: ldap-cli
+
+## Overview
+
+Implement `ldapc`, a Python CLI tool for querying LDAP directories. The implementation follows the workspace conventions (hatchling build, module-per-command, pytest testing) and builds incrementally: project scaffolding → config layer → LDAP client → formatter → CLI wiring → integration tests.
+
+## Tasks
+
+- [x] 1. Set up project structure and scaffolding
+  - [x] 1.1 Create project directory and `pyproject.toml`
+    - Create `ldapc/` project root directory
+    - Create `pyproject.toml` with hatchling build backend, project metadata, dependencies (`ldap3`, `keyring`, `pyyaml`), dev dependencies (`pytest`, `pytest-cov`, `hypothesis`, `ruff`, `mypy`, `bandit`), and `[project.scripts]` entry for `ldapc = "ldapc.cli:main"`
+    - Create `ldapc/ldapc/__init__.py` with package-level imports
+    - Create `ldapc/ldapc/_version.py` with version extraction from CHANGELOG.md
+    - Create `ldapc/CHANGELOG.md` with initial `[Unreleased]` section and `[0.1.0]` entry
+    - Create `ldapc/README.md` with project description, installation, and usage
+    - Create `ldapc/LICENSE` with MIT license
+    - Create `ldapc/docs/README.md` as documentation index
+    - Create `ldapc/.gitignore` for Python projects
+    - _Requirements: 1.1, 1.3_
+
+  - [x] 1.2 Create exceptions module
+    - Create `ldapc/ldapc/exceptions.py` with `LdapcError`, `ConfigError`, `ConnectionError`, and `AuthenticationError` exception classes
+    - All exceptions inherit from `LdapcError`
+    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5_
+
+  - [x] 1.3 Create test scaffolding
+    - Create `ldapc/tests/__init__.py`
+    - Create `ldapc/tests/conftest.py` with shared fixtures (tmp config directory, mock keyring, mock LDAP server)
+    - Create `ldapc/pytest.ini` with coverage settings, smoke marker registration, and minimum 80% coverage threshold
+    - _Requirements: (testing infrastructure)_
+
+- [x] 2. Implement configuration module
+  - [x] 2.1 Implement `LdapcConfig` dataclass and YAML serialization
+    - Create `ldapc/ldapc/config.py` with `LdapcConfig` dataclass (host, username, base_dn)
+    - Implement `config_to_yaml()` to serialize config to YAML string
+    - Implement `yaml_to_config()` to parse YAML string into config object, raising `ConfigError` on invalid input
+    - Implement `load_config()` to read from `~/.ldapc/config.yaml`, raising `ConfigError` if missing or invalid
+    - Implement `save_config()` to write config with 0600 permissions, creating `~/.ldapc/` directory if needed
+    - All functions must have type hints and Google-style docstrings
+    - _Requirements: 2.1, 2.2, 2.4, 2.6, 2.7, 3.1, 3.2, 3.3, 3.5_
+
+  - [x] 2.2 Write property test: Configuration round-trip (Property 1)
+    - **Property 1: Configuration round-trip**
+    - Generate random `LdapcConfig` objects with hypothesis `@st.composite`
+    - Assert `yaml_to_config(config_to_yaml(config))` produces equivalent object
+    - Tag: `# Feature: ldap-cli, Property 1: Configuration round-trip`
+    - Create `ldapc/tests/test_config_properties.py`
+    - **Validates: Requirements 2.4, 3.1, 3.3, 3.4**
+
+  - [x] 2.3 Write property test: Invalid YAML produces descriptive error (Property 2)
+    - **Property 2: Invalid YAML produces a descriptive error**
+    - Generate random non-YAML strings and YAML missing required fields
+    - Assert `yaml_to_config()` raises `ConfigError` with non-empty message
+    - Tag: `# Feature: ldap-cli, Property 2: Invalid YAML produces a descriptive error`
+    - Add to `ldapc/tests/test_config_properties.py`
+    - **Validates: Requirements 3.2**
+
+  - [x] 2.4 Implement keyring credential storage
+    - Implement `store_password(username, password)` using `keyring.set_password` with service name `ldapc`
+    - Implement `retrieve_password(username)` using `keyring.get_password`, raising `ConfigError` if not found
+    - _Requirements: 4.1, 4.2, 4.3, 4.4_
+
+  - [x] 2.5 Write property test: Password never written to disk (Property 3)
+    - **Property 3: Password is never written to disk**
+    - Generate random passwords, run `save_config`, assert password does not appear in any file under `~/.ldapc/`
+    - Tag: `# Feature: ldap-cli, Property 3: Password is never written to disk`
+    - Add to `ldapc/tests/test_config_properties.py`
+    - **Validates: Requirements 4.4**
+
+  - [x] 2.6 Write unit tests for configuration module
+    - Create `ldapc/tests/test_configure.py`
+    - Test: load_config with valid file, missing file, invalid YAML
+    - Test: save_config creates directory, sets permissions
+    - Test: store_password and retrieve_password with mocked keyring
+    - Test: ConfigError raised when keychain has no stored password
+    - _Requirements: 2.1, 2.2, 2.4, 2.6, 2.7, 3.1, 3.2, 3.5, 4.1, 4.2, 4.3_
+
+- [x] 3. Checkpoint - Ensure configuration tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 4. Implement LDAP client module
+  - [x] 4.1 Implement `LdapClient` class with connection management
+    - Create `ldapc/ldapc/ldap_client.py` with `LdapEntry` dataclass and `LdapClient` class
+    - Implement `__init__` to establish TLS connection with 10-second timeout
+    - Implement `search_users(search_term, base_dn)` to search by cn and uid
+    - Implement `search_groups(search_term, base_dn)` to search by cn
+    - Implement `close()` to unbind and close connection
+    - Handle connection errors, timeouts, TLS failures, and auth errors by raising appropriate exceptions
+    - Use context manager pattern (`__enter__`/`__exit__`) for automatic cleanup
+    - _Requirements: 5.1, 5.3, 5.4, 5.5, 6.1, 6.3, 6.4, 6.5, 8.1, 8.2, 8.3, 8.4_
+
+  - [x] 4.2 Write unit tests for LDAP client
+    - Create `ldapc/tests/test_ldap_client.py`
+    - Test: successful user search returns LdapEntry list (mocked ldap3)
+    - Test: successful group search returns LdapEntry list (mocked ldap3)
+    - Test: connection timeout raises ConnectionError
+    - Test: TLS failure raises ConnectionError
+    - Test: invalid credentials raises AuthenticationError
+    - Test: close() unbinds connection
+    - _Requirements: 5.1, 5.3, 5.4, 5.5, 6.1, 6.3, 6.4, 6.5, 8.1, 8.2, 8.3, 8.4_
+
+- [x] 5. Implement formatter module
+  - [x] 5.1 Implement search filter builders and output formatters
+    - Create `ldapc/ldapc/formatter.py`
+    - Implement `build_user_filter(search_term)` to construct LDAP filter matching cn and uid
+    - Implement `build_group_filter(search_term)` to construct LDAP filter matching cn
+    - Implement `format_user_entries(entries)` for aligned key-value text output with delimiters between entries
+    - Implement `format_group_entries(entries)` for aligned key-value text output with delimiters between entries
+    - Implement `format_entries_json(entries)` for valid JSON output
+    - _Requirements: 5.1, 5.2, 6.1, 6.2, 7.1, 7.2, 7.3_
+
+  - [x] 5.2 Write property test: User search filter construction (Property 4)
+    - **Property 4: User search filter construction**
+    - Generate random non-empty search term strings
+    - Assert `build_user_filter(term)` produces filter containing both `cn` and `uid` references and the search term
+    - Tag: `# Feature: ldap-cli, Property 4: User search filter construction`
+    - Create `ldapc/tests/test_search_properties.py`
+    - **Validates: Requirements 5.1**
+
+  - [x] 5.3 Write property test: Group search filter construction (Property 5)
+    - **Property 5: Group search filter construction**
+    - Generate random non-empty search term strings
+    - Assert `build_group_filter(term)` produces filter containing `cn` reference and the search term
+    - Tag: `# Feature: ldap-cli, Property 5: Group search filter construction`
+    - Add to `ldapc/tests/test_search_properties.py`
+    - **Validates: Requirements 6.1**
+
+  - [x] 5.4 Write property test: Entry formatting contains all required fields (Property 6)
+    - **Property 6: Entry formatting contains all required fields**
+    - Generate random `LdapEntry` objects with required attributes
+    - Assert formatted output contains DN and all attribute values
+    - Tag: `# Feature: ldap-cli, Property 6: Entry formatting contains all required fields`
+    - Create `ldapc/tests/test_formatter_properties.py`
+    - **Validates: Requirements 5.2, 6.2, 7.1**
+
+  - [x] 5.5 Write property test: JSON output is valid and round-trips (Property 7)
+    - **Property 7: JSON output is valid and round-trips**
+    - Generate random lists of `LdapEntry` objects
+    - Assert `format_entries_json(entries)` produces valid JSON that deserializes to equivalent data
+    - Tag: `# Feature: ldap-cli, Property 7: JSON output is valid and round-trips`
+    - Add to `ldapc/tests/test_formatter_properties.py`
+    - **Validates: Requirements 7.3**
+
+  - [x] 5.6 Write unit tests for formatter module
+    - Create `ldapc/tests/test_formatter.py`
+    - Test: format_user_entries with single and multiple entries
+    - Test: format_group_entries with single and multiple entries
+    - Test: format_entries_json produces valid JSON
+    - Test: multiple entries separated by delimiter
+    - _Requirements: 5.2, 6.2, 7.1, 7.2, 7.3_
+
+- [x] 6. Checkpoint - Ensure all module tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 7. Implement CLI entry point and command wiring
+  - [x] 7.1 Implement argument parser and main entry point
+    - Create `ldapc/ldapc/cli.py` with `build_parser()` and `main()` functions
+    - Register `--configure`, `--user`, `--group`, `--version`, `--help`, `--json` flags
+    - Display help when invoked without arguments
+    - Map exception types to exit codes in `main()`: `ConfigError` → 2, `ConnectionError` → 1, `AuthenticationError` → 1
+    - Write errors to stderr, results to stdout
+    - _Requirements: 1.1, 1.2, 1.3, 1.4, 7.4, 9.1, 9.2, 9.3, 9.4, 9.5_
+
+  - [x] 7.2 Implement configure command flow
+    - In `cli.py`, implement the `--configure` handler that prompts for host, username, and password
+    - Use `getpass.getpass()` for password input
+    - Call `save_config()` and `store_password()` to persist settings
+    - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7_
+
+  - [x] 7.3 Implement user search command flow
+    - In `cli.py`, implement the `--user` handler
+    - Load config, retrieve password from keychain, create LdapClient, execute search, format and print results
+    - Handle no-results case with informative message
+    - Close LDAP connection in `finally` block
+    - Support `--json` flag for JSON output
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 7.3, 8.2_
+
+  - [x] 7.4 Implement group search command flow
+    - In `cli.py`, implement the `--group` handler
+    - Load config, retrieve password from keychain, create LdapClient, execute search, format and print results
+    - Handle no-results case with informative message
+    - Close LDAP connection in `finally` block
+    - Support `--json` flag for JSON output
+    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 7.3, 8.2_
+
+  - [x] 7.5 Write unit tests for CLI module
+    - Create `ldapc/tests/test_cli.py`
+    - Test: `--help` displays help text and exits 0
+    - Test: `--version` displays version string and exits 0
+    - Test: no arguments displays help
+    - Test: `--user` with mocked LDAP returns formatted results
+    - Test: `--group` with mocked LDAP returns formatted results
+    - Test: `--json` flag produces JSON output
+    - Test: connection error exits with code 1
+    - Test: config error exits with code 2
+    - Test: errors written to stderr, results to stdout
+    - _Requirements: 1.1, 1.2, 1.3, 1.4, 7.4, 9.1, 9.2, 9.3, 9.4, 9.5_
+
+  - [x] 7.6 Write smoke tests
+    - Create `ldapc/tests/test_smoke.py`
+    - Mark all tests with `@pytest.mark.smoke`
+    - Test: `ldapc --help` exits 0
+    - Test: `ldapc --version` exits 0
+    - Test: `ldapc --user test` without config exits 2
+    - _Requirements: 1.1, 1.2, 1.3, 9.4, 9.5_
+
+- [x] 8. Checkpoint - Ensure full test suite passes
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 9. Integration tests and final wiring
+  - [x] 9.1 Write integration tests for keyring flow
+    - Create `ldapc/tests/test_keyring_integration.py`
+    - Test: full configure → store → retrieve password flow with mocked keyring backend
+    - Test: retrieve fails gracefully when no password stored
+    - _Requirements: 4.1, 4.2, 4.3_
+
+  - [x] 9.2 Write integration tests for LDAP connection lifecycle
+    - Create `ldapc/tests/test_ldap_integration.py`
+    - Test: connect → search → unbind lifecycle with mocked ldap3 server
+    - Test: connection is always closed even on error (finally block)
+    - _Requirements: 8.1, 8.2, 8.3, 8.4_
+
+  - [x] 9.3 Write exit code tests
+    - Create `ldapc/tests/test_exit_codes.py`
+    - Test: successful query exits 0
+    - Test: no results exits 0
+    - Test: connection error exits 1
+    - Test: auth error exits 1
+    - Test: config error exits 2
+    - Test: invalid argument exits 2
+    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5_
+
+- [x] 10. Final checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for faster MVP
+- Each task references specific requirements for traceability
+- Checkpoints ensure incremental validation
+- Property tests validate universal correctness properties from the design document
+- Unit tests validate specific examples and edge cases
+- The project follows workspace conventions: hatchling build, pytest, hypothesis for PBT
+- Python 3.10+ with type hints on all functions and Google-style docstrings
+- Virtual environment at `/Users/topazb/python/py314/`

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-05-12
+
+### Added
+
+- Subcommand-based CLI: `list`, `search`, `get`, `add`, `delete`, `user add group`, `user remove group`
+- `ldapc list users` / `ldapc list groups` to list all entries
+- `ldapc search user|group <term>` for case-insensitive substring search
+- `ldapc get user|group <name>` for exact lookup
+- `ldapc add user|group <name>` to create entries
+- `ldapc delete user|group <name>` to remove entries
+- `ldapc user add group <user> <group>` to add user to group
+- `ldapc user remove group <user> <group>` to remove user from group
+- `--yaml` flag for simplified YAML output (extracts cn from group DNs)
+- `--skip-ssl-verify` can now be set via `LDAPC_SKIP_SSL_VERIFY` environment variable
+- `--debug` flag for verbose logging output to stderr
+- `--docs` flag to browse and view bundled documentation (rich text or markdown, with optional paging)
+- All `.md` files (README, CHANGELOG, docs/) are now included in the wheel
+- `rich` added as a runtime dependency for documentation rendering
+- LDAP filter input escaping (RFC 4515) to prevent filter injection
+
+### Changed
+
+- CLI switched from flat flags (`--user`, `--group`) to subcommand structure
+- `--skip-ssl-verify` defaults to the value of `LDAPC_SKIP_SSL_VERIFY` env var (1/true/yes)
+- LDAP search filters now include objectClass constraints for precision
+- User/group container OUs are now configurable via `users_ou` and `groups_ou` in config
+- Project description updated to reflect full management capabilities
+
+## [0.1.0] - 2025-01-01
+
+### Added
+
+- Initial project scaffolding
+- CLI entry point (`ldapc`)
+- Configuration module with YAML persistence and keyring credential storage
+- LDAP client module with user and group search
+- Output formatter with text and JSON modes
+- Property-based tests for correctness properties

README.md

@@ -0,0 +1,145 @@
+# ldapc
+
+A Python CLI tool for querying and managing LDAP directories. Provides a simple subcommand interface to list, search, get, add, and delete users and groups, with persistent configuration and secure credential storage via the OS keychain.
+
+## Features
+
+- List all users or groups
+- Search users by name/uid, groups by name (case-insensitive substring)
+- Get detailed info on a specific user or group
+- Add and delete users and groups
+- Manage group membership (add/remove users from groups)
+- Text, JSON, and YAML output formats
+- Persistent configuration in `~/.ldapc/config.yaml`
+- Secure credential storage via OS keychain
+- TLS-secured connections with optional certificate verification skip
+- Debug logging for troubleshooting
+
+## Installation
+
+```bash
+# From PyPI
+pip install ldap-cli
+
+# From source (editable, with dev deps)
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Configure (host, base DN, bind DN, password)
+ldapc configure
+
+# List all users
+ldapc list users
+
+# Search for a user
+ldapc search user john
+
+# Get user details in YAML
+ldapc get user jdoe --yaml
+
+# Skip SSL verification (self-signed certs)
+ldapc list users --skip-ssl-verify
+```
+
+## Usage
+
+### Configure
+
+```bash
+ldapc configure
+```
+
+Prompts for LDAP host URL, base DN, bind DN, and password. Config is stored in `~/.ldapc/config.yaml`; password goes to the OS keychain.
+
+### List
+
+```bash
+ldapc list users          # all users
+ldapc list groups         # all groups
+```
+
+### Search
+
+```bash
+ldapc search user john    # users matching "john" (case-insensitive)
+ldapc search group admin  # groups matching "admin"
+```
+
+### Get
+
+```bash
+ldapc get user jdoe       # exact user lookup
+ldapc get group devs      # exact group lookup
+```
+
+### Add / Delete
+
+```bash
+ldapc add user newuser
+ldapc add group newgroup
+ldapc delete user olduser
+ldapc delete group oldgroup
+```
+
+### Group Membership
+
+```bash
+ldapc user add group jdoe developers      # add user to group
+ldapc user remove group jdoe developers   # remove user from group
+```
+
+### Output Formats
+
+```bash
+ldapc list users --json   # JSON output
+ldapc list users --yaml   # YAML output (simplified, human-friendly)
+```
+
+### Global Flags
+
+These flags can appear after any subcommand:
+
+| Flag | Env Var | Description |
+|------|---------|-------------|
+| `--debug` | — | Enable debug logging to stderr |
+| `--skip-ssl-verify` | `LDAPC_SKIP_SSL_VERIFY=1` | Skip TLS certificate verification |
+| `--json` | — | Output as JSON |
+| `--yaml` | — | Output as simplified YAML |
+
+### Help
+
+```bash
+ldapc --help          # top-level help
+ldapc get --help      # subcommand help
+ldapc --version       # show version
+```
+
+### Documentation
+
+```bash
+ldapc --docs                          # list available doc files
+ldapc --docs README.md                # render README as rich text
+ldapc --docs README.md --page         # render with paging
+ldapc --docs README.md --markdown     # output raw markdown
+ldapc --docs docs/README.md --page    # view docs/README.md with paging
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest tests/ -v
+```
+
+With coverage:
+
+```bash
+python3 -m pytest tests/ --cov=ldapc --cov-report=term-missing
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

docs/reference.md

@@ -0,0 +1,198 @@
+# ldapc Documentation
+
+## Contents
+
+- [Commands](#commands) — Full command reference
+- [Configuration](#configuration) — Config file and credential storage
+- [Output Formats](#output-formats) — Text, JSON, and YAML
+- [Environment Variables](#environment-variables) — Env var reference
+- [Development](#development) — Contributing, testing, project conventions
+
+## Overview
+
+`ldapc` is a Python CLI tool for querying and managing LDAP directories. It uses a subcommand structure for all operations.
+
+## Commands
+
+### configure
+
+```bash
+ldapc configure
+```
+
+Interactive setup. Prompts for:
+- **LDAP host URL** — e.g. `ldaps://ldap.example.com:636`
+- **Base DN** — e.g. `dc=ldap,dc=example,dc=com`
+- **Bind DN** — e.g. `uid=admin,cn=users,dc=ldap,dc=example,dc=com`
+- **Bind password** — stored in OS keychain
+
+Config saved to `~/.ldapc/config.yaml` (mode 0600).
+
+### list
+
+```bash
+ldapc list users    # list all users
+ldapc list groups   # list all groups
+```
+
+### search
+
+```bash
+ldapc search user <term>    # case-insensitive substring match on cn/uid
+ldapc search group <term>   # case-insensitive substring match on cn
+```
+
+### get
+
+```bash
+ldapc get user <name>    # exact match on uid or cn
+ldapc get group <name>   # exact match on cn
+```
+
+Returns exit code 1 if not found.
+
+### add
+
+```bash
+ldapc add user <name>    # creates inetOrgPerson under ou=users
+ldapc add group <name>   # creates posixGroup under ou=groups
+```
+
+### delete
+
+```bash
+ldapc delete user <name>
+ldapc delete group <name>
+```
+
+### user (group membership)
+
+```bash
+ldapc user add group <user> <group>      # add user to group
+ldapc user remove group <user> <group>   # remove user from group
+```
+
+## Output Formats
+
+### Default (text)
+
+Aligned key-value format:
+
+```
+DN        : uid=jdoe,ou=users,dc=example,dc=com
+CN        : John Doe
+Email     : john@example.com
+Groups    : cn=developers,ou=groups,dc=example,dc=com
+```
+
+### JSON (`--json`)
+
+```json
+[
+  {
+    "dn": "uid=jdoe,ou=users,dc=example,dc=com",
+    "attributes": {
+      "cn": ["John Doe"],
+      "mail": ["john@example.com"],
+      "memberOf": ["cn=developers,ou=groups,dc=example,dc=com"]
+    }
+  }
+]
+```
+
+### YAML (`--yaml`)
+
+Simplified, human-friendly format. Group DNs are reduced to just the cn value:
+
+```yaml
+---
+cn: John Doe
+email: john@example.com
+groups:
+- developers
+```
+
+## Global Flags
+
+These flags work with any subcommand and can appear anywhere after the subcommand name:
+
+| Flag | Description |
+|------|-------------|
+| `--debug` | Enable debug logging (connection details, search filters, result counts) to stderr |
+| `--skip-ssl-verify` | Skip TLS certificate verification |
+| `--json` | Output results as JSON |
+| `--yaml` | Output results as simplified YAML |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LDAPC_SKIP_SSL_VERIFY` | Set to `1`, `true`, or `yes` to skip TLS cert verification by default |
+
+## Configuration
+
+### File location
+
+`~/.ldapc/config.yaml` (created by `ldapc configure`)
+
+### Format
+
+```yaml
+host: ldaps://ldap.example.com:636
+username: uid=admin,cn=users,dc=ldap,dc=example,dc=com
+base_dn: dc=ldap,dc=example,dc=com
+```
+
+### Credentials
+
+Password is stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) under service name `ldapc`.
+
+## Installation
+
+```bash
+# From PyPI
+pip install ldap-cli
+
+# From source (editable, with dev deps)
+pip install -e ".[dev]"
+```
+
+## Development
+
+### Running tests
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest tests/ -v
+```
+
+### Coverage
+
+```bash
+python3 -m pytest tests/ --cov=ldapc --cov-report=term-missing
+```
+
+### Project structure
+
+```
+ldapc/
+  __init__.py        # Package init, exports __version__
+  _version.py        # Version extraction from CHANGELOG.md
+  cli.py             # CLI entry point with subcommand parser
+  config.py          # Config file and keyring management
+  ldap_client.py     # LdapClient class (connect, search, CRUD)
+  formatter.py       # Output formatting (text, JSON, YAML)
+  exceptions.py      # Exception hierarchy
+tests/               # Unit tests (pytest + hypothesis)
+docs/                # This documentation
+```
+
+### Adding a new subcommand
+
+1. Add the subparser in `build_parser()` in `cli.py`
+2. Create a `_handle_<command>()` function
+3. Add dispatch in `main()`
+4. Add corresponding method(s) to `LdapClient` if needed
+5. Add tests in `tests/test_cli.py`
+6. Update this documentation
+7. Add changelog entry under `[Unreleased]`