77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
This project uses a `src/` layout:
|
|
- `src/lazy_enter/`: application code (`bridge.py`, `slack_handler.py`, `pty_manager.py`, `config.py`, `hooks.py`)
|
|
- `tests/`: `pytest` test suite (`test_*.py` files)
|
|
- `pyproject.toml`: packaging, lint, type-check, and test configuration
|
|
- `.env.example`: environment variable template for local setup
|
|
|
|
Use module boundaries intentionally: `bridge.py` orchestrates flow, while Slack, PTY, config, and hook parsing stay in their dedicated modules.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `pip install -e .`: install the package in editable mode for local development.
|
|
- `python -m lazy_enter` or `lazy-enter`: run the bridge locally.
|
|
- `pytest`: run all tests.
|
|
- `pytest tests/test_hooks.py -v`: run one test file with verbose output.
|
|
- `ruff check src/ tests/`: lint imports and code quality rules.
|
|
- `ruff format src/ tests/`: apply standard formatting.
|
|
- `mypy src/`: run strict static type checks.
|
|
|
|
## Coding Style & Naming Conventions
|
|
Target runtime is Python 3.10+ with 4-space indentation and type hints on public functions.
|
|
Follow `ruff` rules (`E`, `F`, `I`, `N`, `W`, `UP`) and keep imports sorted.
|
|
Naming patterns:
|
|
- modules/files: `snake_case.py`
|
|
- functions/variables: `snake_case`
|
|
- classes: `PascalCase`
|
|
- constants/env keys: `UPPER_SNAKE_CASE`
|
|
|
|
## Testing Guidelines
|
|
Use `pytest` with tests under `tests/` and names matching `test_*.py` (configured in `pyproject.toml`).
|
|
Prefer focused unit tests per module (see `tests/test_hooks.py`, `tests/test_config.py`).
|
|
For bug fixes, add or update a regression test in the matching test file before finalizing.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
Current git history is minimal (`Initial commit`), so enforce clear conventions now:
|
|
- Commit messages: imperative, concise subject (e.g., `Add Slack user/channel guard`).
|
|
- Keep commits scoped to one logical change.
|
|
- PRs should include: problem summary, what changed, test evidence (`pytest`, `ruff`, `mypy`), and linked issue/context.
|
|
- Include screenshots or log snippets when behavior changes are user-visible (for example, Slack message formatting).
|
|
|
|
## Security & Configuration Tips
|
|
Do not commit secrets. Copy `.env.example` to `.env` locally.
|
|
Restrict Slack access with `SLACK_ALLOWED_USER_ID` and `SLACK_ALLOWED_CHANNEL_ID` before running in shared workspaces.
|
|
|
|
## Git & Gitea Workflow Notes
|
|
Use `tea` (Gitea CLI), not `gh`.
|
|
|
|
Hard rule:
|
|
- Never implement changes, stage files, or commit on `main`.
|
|
- Always create/use a feature branch first, and merge via PR.
|
|
|
|
- Check login:
|
|
- `tea login ls`
|
|
- `tea whoami`
|
|
- Create/update feature branch:
|
|
- `git checkout -b <branch>` (or `git checkout <branch>`)
|
|
- `git add <files>`
|
|
- `git commit -m "<message>"`
|
|
- Push to Gitea:
|
|
- Normal: `git push -u origin <branch>`
|
|
- If HTTP username prompt fails in this environment, use the token from `~/.config/tea/config.yml`:
|
|
- `TOKEN=$(sed -n 's/^[[:space:]]*token: //p' ~/.config/tea/config.yml | head -n1)`
|
|
- `git push "http://agentson:${TOKEN}@localhost:3000/jihoson/LazyEnter.git" <branch>`
|
|
- After token-based push, ensure tracking is on `origin/<branch>` (not token URL):
|
|
- `git fetch origin <branch>:refs/remotes/origin/<branch>`
|
|
- `git branch --set-upstream-to=origin/<branch> <branch>`
|
|
- Create PR on Gitea:
|
|
- `tea pr create --base main --head <branch> --title "<title>" --description "<body>"`
|
|
- Sync local main:
|
|
- `git checkout main`
|
|
- `git pull --ff-only`
|
|
|
|
Safety:
|
|
- Do not commit or print tokens in logs/docs.
|
|
- Keep unrelated local files (for example `uv.lock`) out of PRs unless intentionally changed.
|