authsome AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, Copilot, etc.) when working with this repository.

Commands

Always use uv run to execute commands — do not use python, python3, pip, or bare tool names directly.

# Install in editable mode (required before running anything)
uv pip install -e ".[dev]"

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/test_client.py

# Run a single test by name
uv run pytest tests/test_client.py::test_login_pkce -v

# Run tests with coverage
uv run pytest --cov=authsome

Run linting and type checks:

# Lint and auto-fix
uv run ruff check --fix src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run ty check src/

The CLI entry point after install:

uv run authsome onboard
uv run authsome login github
uv run authsome provider list

Engineering principles

For the full set of contribution guidelines, design principles, and AI-assisted development practices, see CONTRIBUTING.md. Everything in that document applies to AI agents as well as human contributors.

These rules govern all changes to this codebase — apply them without exception.

YAGNI. Implement only what the current task demands. Don't build for hypothetical future requirements.

Use trusted libraries over reinventing. Reach for a well-maintained dependency before writing your own crypto, HTTP client, or token parser.

Deep modules over shallow ones. Prefer a small surface area with rich internals over many thin wrappers. More files is not more modular.

Composition over inheritance. Prefer small collaborators wired together through explicit dependencies over inheritance hierarchies. Use inheritance only when there is a real subtype relationship and composition would make the design less clear.

Single responsibility and separation of concerns. Auth authenticates. Vault stores credentials. CLI presents output. A flow must not write to storage; storage must not know about OAuth. If a function is hard to name, it's doing too many things.