# AGENTS.md

Guidance for coding agents working in this repository.

## Project at a glance
- Language: Python
- Package layout: `src/flow/`
- Tests: `tests/` with `pytest`
- Build backend: Hatchling (`pyproject.toml`)
- CLI entrypoint: `flow.cli:main` (`python3 -m flow`)
- Binary packaging: PyInstaller (`Makefile`)

## Build, test, and validation commands

### Setup
```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

### Run CLI locally
```bash
python3 -m flow --help
python3 -m flow --version
```

### Run all tests
```bash
python3 -m pytest
```

### Run a single test file
```bash
python3 -m pytest tests/test_cli.py
```

### Run a single test function
```bash
python3 -m pytest tests/test_cli.py::test_version
```

### Run a single test class
```bash
python3 -m pytest tests/test_commands.py::TestParseImageRef
```

### Run tests by keyword expression
```bash
python3 -m pytest -k "terminfo"
```

### Build standalone binary
```bash
make build
```

### Install local binary
```bash
make install-local
```

### Smoke-check built binary
```bash
make check-binary
```

### Clean build artifacts
```bash
make clean
```

### Lint/format/type-check status
- No dedicated lint/format/type-check commands are currently configured.
- There is no Ruff/Black/isort/mypy config in `pyproject.toml`.
- Agents must follow existing style and keep diffs readable.

## Code style conventions

### Imports
- Group imports as stdlib, third-party, then local (`flow.*`).
- Use explicit imports; avoid wildcard imports.
- Keep imports at module top unless a local import prevents a cycle or unnecessary load.

### Formatting
- Use 4 spaces for indentation.
- Keep lines readable; wrap long calls/literals across lines.
- Keep trailing commas in multiline calls/lists where helpful for cleaner diffs.
- Match local quoting style within each file (mostly double quotes).

### Typing
- Codebase uses gradual typing, not strict typing.
- Add type hints for new helpers, dataclasses, and public functions.
- Follow local module style (`Optional`, `Dict`, `List` vs builtin generics).

### Naming
- `snake_case` for functions, variables, module-level helpers.
- `PascalCase` for classes/dataclasses.
- `UPPER_SNAKE_CASE` for constants.
- Prefix private helpers with `_` when not part of module API.

### Command module patterns
- Each command module exposes `register(subparsers)`.
- Subcommands bind handlers via `set_defaults(handler=...)`.
- Runtime handler signature is typically `(ctx: FlowContext, args)`.
- Keep parse/plan/execute steps separated when logic grows.

### Error handling
- Use concise user-facing messages via `ctx.console.error(...)`.
- Use `sys.exit(1)` for expected CLI failures.
- Keep `KeyboardInterrupt` behavior as exit `130`.
- Raise `RuntimeError` in lower-level helpers for domain failures.
- Avoid noisy tracebacks for normal user mistakes.

### Subprocess safety
- Prefer `subprocess.run([...], check=True)` when possible.
- For shell strings, quote dynamic values (`shlex.quote`).
- Avoid passing unchecked external input into shell commands.
- Use `capture_output=True, text=True` when parsing command output.

### Filesystem and paths
- Prefer `pathlib.Path` for path-heavy logic.
- Expand `~` intentionally when required.
- Ensure parent dirs exist before write/link operations.

### Tests
- Add/update tests for behavior changes.
- Keep tests deterministic and host-independent when possible.
- Favor focused tests for parser/planner helper functions.

## Architecture notes
- `src/flow/cli.py`: parser wiring, context creation, top-level exception handling.
- `src/flow/commands/`: user-facing command implementations.
- `src/flow/core/`: shared primitives (`config`, `console`, `process`, `stow`, etc.).
- `FlowContext` holds config, manifest, platform info, and console logger.

## Behavior constraints to preserve
- Self-hosted config/manifest priority: dotfiles path first, local fallback.
- Manifest uses `profiles`; legacy `environments` is intentionally rejected.
- Dotfiles link state supports v2 format only (`linked.json`).

## Cursor/Copilot rule files
No repository-level rule files were found at the time of writing:
- `.cursorrules` not found
- `.cursor/rules/` not found
- `.github/copilot-instructions.md` not found

If these files are later added, treat them as authoritative and update this guide.

## Workspace hygiene
- Do not commit generated outputs: `build/`, `dist/`, `*.spec`.
- Do not commit Python bytecode/cache files: `__pycache__/`, `*.pyc`, `*.pyo`.
- Keep changes scoped; avoid unrelated refactors.
- Update tests/docs when user-facing behavior changes.

## Agent checklist before finishing
- Run targeted tests for touched behavior.
- Run full suite: `python3 -m pytest`.
- If packaging/build paths changed, run `make build`.
- Verify no generated artifacts are staged.
- Ensure errors are concise and actionable.