goga-tool-pybuggy 0.0.0__tar.gz

goga_tool_pybuggy-0.0.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    uses: qarium/ci/.github/workflows/library-publish.yml@0.0.x
+    with:
+      src-package: 'goga-tool-pybuggy'
+    secrets:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+      ZAI_TOKEN: ${{ secrets.ZAI_TOKEN }}

goga_tool_pybuggy-0.0.0/.gitignore

@@ -0,0 +1,231 @@
+# macOS
+.DS_Store
+.libs/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# AI
+.claude/
+.ralphex/
+#docs/tasks/
+#docs/plans/
+#docs/design/
+#docs/arch/
+docs/superpowers/

goga_tool_pybuggy-0.0.0/.goga/config.yml

@@ -0,0 +1,25 @@
+language: python
+image: qarium/goga-python-3.13:1.1
+
+.claude-env: &claude-env
+  ANTHROPIC_MODEL: opus
+  ANTHROPIC_BASE_URL: "https://api.z.ai/api/anthropic"
+
+build:
+  task_executor:
+    agent: claude
+    env:
+      <<: *claude-env
+      ANTHROPIC_DEFAULT_OPUS_MODEL: "glm-5.1"
+
+pipeline:
+  agent: claude
+  env:
+    <<: *claude-env
+    ANTHROPIC_DEFAULT_OPUS_MODEL: "glm-5.2[1m]"
+
+codemanifest:
+  usages:
+    conventions: .goga/usages/conventions.md
+  annotations: |
+    Use `conventions` for code writing rules and testing.

goga_tool_pybuggy-0.0.0/.goga/usages/conventions.md

@@ -0,0 +1,271 @@
+# General Conventions
+
+Mandatory rules for all Python code in this project. Strict deterministic specification.
+
+## Engineering Principles
+
+Code in this repository MUST prioritize:
+- readable, explicit code
+- predictable, straightforward control flow
+- stable abstractions
+- operational stability and maintainability
+
+---
+
+# Development
+
+## Constraints
+
+- Compatible with Python 3.10 and above only
+- Use `pyproject.toml` for configuration
+- Execute all code within a virtualenv environment — create it if missing
+
+## Imports
+
+RULES:
+1. Use relative imports for all intra-package references
+2. Use absolute imports only for stdlib and third-party packages
+
+```python
+# Valid: intra-package
+from .models import User
+from ..utils import helper
+
+# Valid: stdlib and third-party
+import logging
+from pydantic import BaseModel
+
+# Forbidden: absolute import within the same package
+from myapp.models import User
+```
+
+All subsequent import patterns MUST follow relative imports for intra-package references.
+
+## Data Models
+
+RULES:
+1. Use pydantic for all data models and request/response schemas
+2. All data model classes MUST use `kw_only=True` (Python 3.10+ syntax)
+3. Set empty defaults (empty string, zero, etc.) for all fields — use `None` only for fields that represent the explicit absence of a value
+
+## Logging
+
+RULES:
+1. Use `logging` as the default logging library
+2. Use `structlog` when structured logging is required across the service
+3. Use `loguru` only in single-file CLI utilities with a single entry point
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+```
+
+Operational logs **MUST**:
+- include contextual metadata
+- be machine-readable
+- support filtering and aggregation
+
+```python
+logger.info(
+    "user created",
+    extra={
+        "user_id": user.id,
+        "email": user.email,
+    },
+)
+```
+
+All log output MUST follow structured format with contextual metadata.
+
+Formatting:
+- lowercase messages
+- concise operational wording
+- stable log event names
+
+Log levels MUST reflect operational importance and required reaction.
+
+### DEBUG
+
+DEBUG is used for diagnostic information useful during development or incident investigation.
+
+Use DEBUG for:
+- intermediate state
+- request/response details
+- branch decisions
+- retries
+- external payload previews
+- performance diagnostics
+
+### INFO
+
+INFO is used for important normal business operations.
+
+INFO logs SHOULD describe:
+- lifecycle events
+- significant state transitions
+- externally observable operations
+
+### WARNING
+
+WARNING indicates abnormal but recoverable situations.
+The operation continues, but attention MAY be required.
+
+Use WARNING when:
+- fallback logic is activated
+- retryable failures occur
+- degraded behavior is detected
+- unexpected input is received
+
+### ERROR
+
+ERROR is used when an operation cannot be completed.
+
+Use ERROR when:
+- a request fails
+- data cannot be persisted
+- external dependency prevents operation completion
+- invariant violation affects functionality
+
+### CRITICAL
+
+CRITICAL is reserved for conditions requiring immediate operator intervention.
+
+Use CRITICAL only when:
+- the process cannot continue execution
+- data corruption is detected or imminent
+- core infrastructure dependencies are unreachable
+- manual operator intervention is required within minutes
+
+### Log Content Restrictions
+
+Log messages MUST contain only non-sensitive operational data. Exclude secrets, credentials, tokens, and personal sensitive data from all log output.
+
+## Code Formatting
+
+Inside function and method bodies, logical blocks are separated by **one blank line**:
+- Variable initialization is separated from conditional constructs and loops
+- Loops and conditions are separated by a blank line
+- Data preparation is separated from its processing
+- Processing is separated from returning the result
+
+## Docstrings
+
+All public functions, methods, and classes **MUST** have docstrings. Format — **Google style**:
+
+```python
+def function_name(param1: str, param2: int = 0) -> bool:
+    """Brief description of the function.
+
+    Detailed description when necessary.
+
+    Args:
+        param1: Description of the first parameter.
+        param2: Description of the second parameter.
+
+    Returns:
+        Description of the return value.
+
+    Raises:
+        ValueError: Condition that triggers this exception.
+    """
+```
+
+Docstring rules:
+- The first line is required, starts with a capital letter, ends with a period
+- Include `Args` section when the function accepts parameters
+- Include `Returns` section when the function returns a value
+- Include `Raises` section when the function raises exceptions beyond built-in types
+
+## Dependencies
+
+All third-party libraries **MUST** be added to `pyproject.toml`. Specify a minimum version for every dependency.
+
+---
+
+# Testing
+
+## Constraints
+
+- Test code must be compatible with Python 3.10 and above
+
+## Tools
+
+- pytest — running tests
+- ruff — linting and formatting test code
+- pytest-cov — coverage
+
+## Running Tests
+
+- Execute all tests within a virtualenv environment — create it if missing
+
+## Test Structure
+
+Tests mirror the source code structure **directly**, without an intermediate root package directory:
+- `<src>/module/file.py` → `tests/module/test_file.py`
+- The `tests/` directory contains subdirectories corresponding to nested packages of the root package
+- Tests for root package modules (`__main__.py`, `__init__.py`) are placed directly in `tests/` (e.g., `tests/test_main.py`)
+
+RULES:
+1. Each test directory MUST contain an `__init__.py`
+2. Place local fixtures in `tests/<package>/conftest.py`, shared fixtures in `tests/conftest.py`
+3. Place integration tests covering multiple packages directly in `tests/` (e.g., `tests/test_integration.py`)
+
+## Naming
+
+- Files: `test_<module>.py`
+- Functions: `test_<what>_<scenario>` (e.g., `test_complexity_with_empty_input`)
+- Grouping: `class Test<Component>:`
+
+## Test Types
+
+- **Unit** — every public function/method/class, main scenario and typical data
+- **Edge cases**:
+  - Empty inputs: `None`, `""`, `[]`, `{}`
+  - Boundary values: `0`, negative, very large
+  - Invalid types
+  - Expected exceptions via `pytest.raises`
+- **Integration** — only for interaction between modules/packages
+
+## REST API Testing
+
+Test endpoints by calling the handler function directly via Python call.
+
+## CLI Testing
+
+Test CLI commands by calling the command handler function directly via Python call.
+
+## Boundary Tests
+
+For thresholds, ranges, state transitions — use `@pytest.mark.parametrize` with a table of values including each boundary.
+
+## Mocks
+
+- Pure logic — write tests without mocks
+- File I/O — use the `tmp_path` fixture exclusively
+- Subprocesses — `mock.patch` the subprocess call
+- External dependencies — `mock.patch` at the import point
+
+Mock only at external boundaries. Keep business logic tests mock-free.
+
+## Miscellaneous
+
+- Use self-documenting test names. Keep comments minimal.
+- Skip integration tests with unavailable external dependencies via `pytest.mark.skipif`
+
+## Dependencies
+
+All test libraries **MUST** be added to `pyproject.toml` in the `[project.optional-dependencies]` section under the `test` key.
+
+---
+
+# Validation Commands
+
+All commands must run in a virtualenv environment. Python 3.10+ compatibility required.
+
+| Purpose                  | Command                                   |
+|--------------------------|-------------------------------------------|
+| Run all tests            | `pytest tests/ -x`                        |
+| Run a specific test      | `pytest tests/test_<name>.py -v`          |
+| Lint                     | `ruff check <src>/`                       |
+| Facade check             | `python -c "from package import Entity"`  |

goga_tool_pybuggy-0.0.0/.goga/usages/cooks/click.md

@@ -0,0 +1,96 @@
+# click — CLI-фасад (библиотека)
+
+## Предметная область
+
+`click` — библиотека для построения CLI в Python. Используется проектом для групп, подгрупп,
+команд, опций/аргументов и единообразного маппинга доменных ошибок в ненулевой exit.
+
+```python
+import click
+```
+
+Эта практика описывает только API `click`. Как проект собирает из этого свой CLI — в клеточных
+`.usages/` соответствующих ячеек (composition root, команды).
+
+---
+
+## Группы и подгруппы
+
+Группа (`@click.group`) — корень дерева команд. Подгруппа — отдельная группа, добавленная в
+родительскую через `add_command`. Так строятся вложенные команды `parent child ...`:
+
+```python
+@click.group()
+def parent():
+    """Root group."""
+
+
+@click.group("child", help="Child subgroup.")
+def child_group():
+    """Child subgroup."""
+
+
+parent.add_command(child_group)
+```
+
+- Имя группы — аргумент декоратора (`@click.group("child")`); без аргумента берётся имя функции.
+- `help` группы показывается в `--help`.
+
+---
+
+## Команды, опции, аргументы
+
+Команда (`@click.command`) — лист дерева. Опции — `@click.option`, позиционные аргументы —
+`@click.argument`. Имя декорированной функции — это имя команды, если не задано явно.
+
+```python
+@click.command("pull")
+@click.option("--spec", "spec_name", default=None, help="Filter by spec name.")
+def pull_cmd(spec_name):
+    """Pull specs."""
+    ...
+```
+
+- `@click.option("--flag", "dest", default=None, ...)` — опция; `dest` задаёт имя параметра в callback.
+- Булев флаг: `is_flag=True, default=False`.
+- Короткая форма: `@click.option("-s", "--spec", "spec_name", ...)`.
+- `@click.argument("endpoint_id")` — позиционный аргумент.
+
+---
+
+## Handler отделён от обёртки
+
+Click-декоратор только связывает опции/аргументы и вызывает чистую handler-функцию. Это позволяет
+тестировать логику **прямым вызовом** handler-а, без `CliRunner`:
+
+```python
+def run_pull(spec_name):
+    """Pure handler — callable directly from tests."""
+    ...
+
+
+@click.command("pull")
+@click.option("--spec", "spec_name", default=None)
+def pull_cmd(spec_name):
+    run_pull(spec_name)
+```
+
+---
+
+## Маппинг доменных ошибок — ClickException
+
+Доменные ошибки (не найдено, невалидный ввод, отказ внешней зависимости) маппятся в
+`click.ClickException`. Click печатает сообщение и завершает процесс с ненулевым exit —
+единообразное поведение для всех команд:
+
+```python
+if spec_name not in config.specs:
+    raise click.ClickException(f"spec not found: {spec_name}")
+```
+
+---
+
+## Тестирование CLI
+
+- Handler-функции тестируются **прямым вызовом** (см. `conventions`, раздел CLI Testing), без `CliRunner`.
+- git/FS — через `mock.patch`/`tmp_path`; чистая логика — без моков.