mirror of
https://github.com/Second-Hand-Friends/kleinanzeigen-bot.git
synced 2026-07-09 20:51:05 +02:00
eda06334d1
## ℹ️ Description - Link to the related issue(s): N/A - Keeps the README Usage command block in sync with the CLI help by generating it as part of the artifact pipeline. ## 📋 Changes Summary - Added a README Usage generator that renders normalized English CLI help between explicit README markers. - Added `generate-readme-commands` and wired it into `generate-artifacts`. - Extended generated artifact checks to detect README Usage drift without mutating files. - Added focused unit tests for marker replacement, locale/executable normalization, ANSI stripping, and command coverage. - No dependency changes introduced. ### ⚙️ Type of Change Select the type(s) of change(s) included in this pull request: - [ ] 🐞 Bug fix (non-breaking change which fixes an issue) - [x] ✨ New feature (adds new functionality without breaking existing usage) - [ ] 💥 Breaking change (changes that might break existing user setups, scripts, or configurations) ## ✅ Checklist Before requesting a review, confirm the following: - [x] I have reviewed my changes to ensure they meet the project's standards. - [x] I have tested my changes and ensured that all tests pass (`pdm run test`). - [x] I have formatted the code (`pdm run format`). - [x] I have verified that linting passes (`pdm run lint`). - [x] I have updated documentation where necessary. By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Kept the README “Usage” section automatically synchronized with the app’s CLI help. * Added a new `--preserve-local-settings` option to the CLI help output. * **Bug Fixes** * Improved and clarified CLI command/option descriptions (notably around `verify`, `extend`, and `update` behavior). * CI now fails early if the generated README “Usage” content is out of date. * **Documentation** * Regenerated the README “Usage” console block to reflect the latest help text and command details. * Updated agent guidance to match the expanded README generation behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
112 lines
4.8 KiB
Markdown
112 lines
4.8 KiB
Markdown
# Agent Playbook
|
|
|
|
Local operating guide for contributors and AI agents working on `kleinanzeigen-bot`.
|
|
|
|
Prefer tracked repo files and CI as the source of truth. If this file conflicts with them, the tracked docs/workflows win. Make minimal, focused changes that match existing patterns.
|
|
|
|
## Read First
|
|
|
|
Before making non-trivial changes, review:
|
|
|
|
- `README.md`
|
|
- `CONTRIBUTING.md`
|
|
- `docs/TESTING.md`
|
|
- `.github/PULL_REQUEST_TEMPLATE.md`
|
|
- `.github/workflows/build.yml`
|
|
- `.github/workflows/validate-pr-title.yml`
|
|
|
|
## Hard Repo Rules
|
|
|
|
- Never hit `kleinanzeigen.de` in tests.
|
|
- Write code, comments, and contributor-facing docs in English by default.
|
|
- For runtime/user-facing output, follow the translation rules in `CONTRIBUTING.md` and update translations when messages change.
|
|
- Keep log message strings in plain English; do **not** wrap `LOG.*`/`logger.*` strings with `_()`, because logging messages are translated by `TranslatingLogger`.
|
|
- New Python files need the full SPDX header block from `CONTRIBUTING.md`.
|
|
- Use full type hints (Python 3.10+ syntax).
|
|
- Catch `TimeoutError` in browser automation paths.
|
|
- Never hardcode credentials or secrets.
|
|
- Prefer small, simple changes over speculative abstractions.
|
|
|
|
## Project Contract
|
|
|
|
`kleinanzeigen-bot` is a CLI application, not a supported Python library API.
|
|
|
|
Keep stable from a user perspective:
|
|
|
|
- CLI commands, options, and exit behavior
|
|
- Config files and config defaults
|
|
- Generated YAML behavior and persisted ad file mutations
|
|
- Runtime/user-facing messages and translation behavior
|
|
- Browser workflows and automation outcomes
|
|
|
|
Do not preserve accidental internal compatibility:
|
|
|
|
- Package-root imports for helpers, models, or extracted modules
|
|
- Monkeypatch paths in tests
|
|
- Compatibility aliases for internal helpers
|
|
- Wrapper methods or re-exports whose only purpose is preserving old internal import paths
|
|
|
|
## Repo Patterns
|
|
|
|
- Browser automation: follow existing `WebScrapingMixin` patterns and use `ensure()` for validation.
|
|
- Logging: use `loggers.get_logger(__name__)`.
|
|
- Config and file paths: prefer `pathlib.Path` and existing file helpers.
|
|
- For Windows-specific cross-platform path logic, prefer `pathlib.PureWindowsPath` when relevant.
|
|
- Keep browser-independent domain logic in top-level `src/kleinanzeigen_bot/*.py` modules; reserve `src/kleinanzeigen_bot/utils/` for generic infrastructure helpers.
|
|
- Pydantic models belong in `src/kleinanzeigen_bot/model/`.
|
|
- Tests belong in `tests/unit/`, `tests/integration/`, or `tests/smoke/`.
|
|
- Use the repo's registered pytest markers.
|
|
|
|
## Testing Guidance
|
|
|
|
Add or update tests when changing observable behavior, business logic, error handling, or fixing bugs.
|
|
|
|
Tests may be skipped for:
|
|
|
|
- log-only wording changes
|
|
- diagnostic-only changes with no behavior impact
|
|
- trivial wrappers already covered elsewhere
|
|
|
|
Testing rules:
|
|
|
|
- Test behavior, not implementation details.
|
|
- Prefer extending existing tests over adding duplicates.
|
|
- If you touch nearby tests, clean up obvious stale or duplicate coverage when it is cheap and in scope.
|
|
- For smoke tests, prefer simple fakes/dummies over mocks and patching.
|
|
|
|
`docs/TESTING.md` is the authority for test types, execution, and smoke-test conventions.
|
|
|
|
## Validation Before Work Is Done
|
|
|
|
Run in this order:
|
|
|
|
1. `pdm run format`
|
|
2. `pdm run lint` — run the repo's configured lint/type-check suite. Use `pdm run lint:fix` first for auto-fixable ruff issues.
|
|
3. `pdm run test`
|
|
|
|
When changing models, config defaults, schema-affecting validators, or `create-config` output, also regenerate committed artifacts:
|
|
|
|
- `pdm run generate-schemas` — regenerates `schemas/*.json`
|
|
- `pdm run generate-config` — regenerates `docs/config.default.yaml`
|
|
- `pdm run generate-artifacts` — runs schemas, config, and README usage regeneration
|
|
|
|
CI and workflows are the source of truth for the exact required checks, coverage gates, generated-artifact verification, and PR title validation.
|
|
|
|
## PR Expectations
|
|
|
|
- PR titles must follow the semantic format enforced by `.github/workflows/validate-pr-title.yml`.
|
|
- Branch names should use the same conventional type prefix as the PR title, e.g. `docs/update-agent-playbook`, `fix/browser-timeout`, or `feat/price-logging`.
|
|
- PR descriptions should use `.github/PULL_REQUEST_TEMPLATE.md` and complete its required sections and checklist.
|
|
- Do not open a PR with placeholder sections, missing checklist decisions, or a non-semantic title; fix the title/body before publishing.
|
|
|
|
## Completion Checklist
|
|
|
|
- [ ] Change is minimal and focused
|
|
- [ ] Tests were added or updated if behavior changed
|
|
- [ ] Translations were updated if needed
|
|
- [ ] Generated artifacts (`schemas/*.json`, `docs/config.default.yaml`) were updated if models or config defaults changed
|
|
- [ ] `pdm run format` passes
|
|
- [ ] `pdm run lint` passes
|
|
- [ ] `pdm run test` passes
|
|
- [ ] No unrelated issues introduced
|