53 lines
1.9 KiB
Markdown
53 lines
1.9 KiB
Markdown
# Repository Guidelines
|
|
|
|
> **Note**: See CLAUDE.md for comprehensive project documentation. This file provides a quick reference for common patterns.
|
|
|
|
## Project Structure
|
|
|
|
- `src/cmdforge/` - Core Python package (CLI, tool model, runner, providers, GUI)
|
|
- `tests/` - Pytest test suites
|
|
- `docs/` - Infrastructure and deployment documentation
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
pip install -e ".[dev]" # Install in dev mode
|
|
pytest tests/ -m "not integration" # Run unit tests
|
|
cmdforge # Launch GUI
|
|
cf # Interactive tool picker
|
|
```
|
|
|
|
## Architecture Quick Reference
|
|
|
|
- `cli/` - Routes all subcommands (list, create, run, test, providers, registry, collections, deps, install, etc.)
|
|
- `tool.py` - Tool/step dataclasses, YAML loading, wrapper generation
|
|
- `runner.py` - Step execution, variable substitution (`{input}`, `{varname}`)
|
|
- `providers.py` - AI provider abstraction (calls CLI tools via subprocess)
|
|
- `gui/` - PySide6 desktop GUI with page-based navigation
|
|
- `web/` - Flask web UI and forum
|
|
- `registry/` - Flask registry API (search, publish, moderation)
|
|
|
|
## Coding Style
|
|
|
|
- Python: 4-space indentation, `snake_case` for modules/variables
|
|
- CLI tools: lowercase with hyphens (e.g., `fix-grammar`, `json-extract`)
|
|
- Follow Unix pipe philosophy: composable tools with stdin/stdout
|
|
|
|
## Testing
|
|
|
|
- Framework: `pytest` (see `pyproject.toml`)
|
|
- Test files: `tests/test_*.py`
|
|
- Use `mock` provider or `--dry-run` to avoid network calls
|
|
- Integration tests require `@pytest.mark.integration` decorator
|
|
|
|
## Commit Guidelines
|
|
|
|
- Short, imperative, sentence-case subjects (e.g., "Add provider validation")
|
|
- Include test results or rationale if skipped
|
|
- Add screenshots for UI changes
|
|
|
|
## Security
|
|
|
|
- Provider configs: `~/.cmdforge/providers.yaml` (never commit)
|
|
- Tool configs: `~/.cmdforge/<toolname>/config.yaml` (user data, never commit)
|