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>"
- If PR body includes backticks (`), slash commands, or markdown that can be shell-expanded, do not pass it directly in double quotes.
- Preferred safe flow:
  - cat > /tmp/pr_body.md <<'EOF' ... EOF
  - tea pr create --base main --head <branch> --title "<title>" --description "$(cat /tmp/pr_body.md)"
- If the body is malformed after creation, patch it with API:
  - tea api -X PATCH repos/{owner}/{repo}/pulls/<number> -F body=@/tmp/pr_body.md
Sync local main:
- git checkout main
- git pull --ff-only
- When user confirms the PR is merged, always run this sync immediately to keep local main up to date before any next task.

Safety:

Do not commit or print tokens in logs/docs.
Keep unrelated local files (for example uv.lock) out of PRs unless intentionally changed.

4.2 KiB Raw Permalink Blame History