flow/AGENTS.md

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

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Run CLI locally

python3 -m flow --help
python3 -m flow --version

Run all tests

python3 -m pytest

Run a single test file

python3 -m pytest tests/test_cli.py

Run a single test function

python3 -m pytest tests/test_cli.py::test_version

Run a single test class

python3 -m pytest tests/test_commands.py::TestParseImageRef

Run tests by keyword expression

python3 -m pytest -k "terminfo"

Build standalone binary

make build

Install local binary

make install-local

Smoke-check built binary

make check-binary

Clean build artifacts

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.