43 lines
2.3 KiB
Markdown
43 lines
2.3 KiB
Markdown
# 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.
|