2.3 KiB

Raw Blame History

Repository Guidelines

Project Structure & Module Organization

src/smarttools/ contains the core Python package (CLI entry point, tool model, runner, providers, UI backends).
tests/ holds pytest suites.
docs/ includes installation, provider setup, examples, and design notes.
examples/ provides sample tools and an installer script.
wiki/ contains additional reference material.

Architecture Overview

cli.py routes subcommands like list, create, run, test, ui, and refresh.
tool.py defines tool/step models and handles YAML config loading and wrapper generation.
runner.py executes steps and performs {input}/argument variable substitution.
providers.py shells out to configured AI provider CLIs (or the mock provider).
ui_urwid.py and ui_snack.py provide the TUI implementations, selected by ui.py.

Build, Test, and Development Commands

pip install -e ".[dev]" installs SmartTools in editable mode with dev dependencies.
pytest runs the full test suite.
pytest tests/test.py::test_name runs a focused test.
python -m smarttools.cli runs the CLI module directly.
smarttools ui launches the TUI (requires urwid or python-newt).
docker-compose build builds the dev container image.
docker-compose run --rm test runs tests inside Docker.

Coding Style & Naming Conventions

Python code uses 4-space indentation and module/variable names in snake_case.
Keep CLI command names and tool IDs lowercase with hyphens (e.g., fix-grammar, json-extract).
Prefer small, composable functions that mirror the Unix pipe flow described in README.md.

Testing Guidelines

Framework: pytest (configured in pyproject.toml).
Place new tests under tests/ and name files test_*.py.
For provider-dependent logic, prefer the built-in mock provider to avoid network calls.

Commit & Pull Request Guidelines

Commit messages follow short, imperative, sentence-case subjects (e.g., "Improve provider error messages").
PRs should include a clear summary, test results (or rationale if tests are skipped), and screenshots when UI behavior changes.

Security & Configuration Tips

Provider credentials live in ~/.smarttools/providers.yaml; avoid committing secrets.
User tool configs live in ~/.smarttools/<toolname>/config.yaml and should not be added to the repo.