kagan 0.1.0__tar.gz

kagan-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: "🐛 Bug Report"
+about: Report a reproducible bug or unexpected behavior
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Bug Description
+
+<!-- A clear and concise description of the bug -->
+
+## Environment
+
+- **Kagan Version**: <!-- e.g., 0.1.0 -->
+- **Python Version**: <!-- e.g., 3.12.1 -->
+- **OS**: <!-- e.g., macOS 14.0, Ubuntu 22.04 -->
+- **Terminal**: <!-- e.g., iTerm2, Alacritty, Terminal.app -->
+
+<!-- Optional: Include output of `uv --version` and `python --version` -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen? -->
+
+## Actual Behavior
+
+<!-- What actually happens? -->
+
+## Screenshots/Logs
+
+<!-- If applicable, add screenshots or terminal output to help explain the problem -->
+
+## Additional Context
+
+<!-- Any other context about the problem, such as:
+- Does this happen consistently or intermittently?
+- Any recent changes to your setup?
+- Relevant configuration from your environment?
+-->

kagan-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Discussions
+    url: https://github.com/aorumbayev/kagan/discussions
+    about: Ask questions and discuss ideas with the community
+  - name: 📖 Documentation
+    url: https://aorumbayev.github.io/kagan
+    about: Browse the documentation

kagan-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: "✨ Feature Request"
+about: Suggest a new feature or enhancement for Kagan
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+<!-- What problem are you trying to solve? What's missing or could be improved? -->
+
+## Proposed Solution
+
+<!-- Describe your ideal solution in detail -->
+
+## Alternative Solutions
+
+<!-- Have you considered any alternative approaches? -->
+
+## Use Case
+
+<!-- Describe how this feature would be used. Who would benefit from it? -->
+
+## Implementation Ideas
+
+<!-- Optional: Any thoughts on how this could be implemented? -->
+
+## Additional Context
+
+<!-- Any other context, screenshots, or examples that help explain the feature request -->

kagan-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,66 @@
+## Description
+
+<!-- Describe your changes in detail -->
+
+## Type of Change
+
+<!-- Put an `x` in the boxes that apply -->
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📝 Documentation update
+- [ ] 🎨 Style/UI update (no functional changes)
+- [ ] ♻️ Code refactoring (no functional changes)
+- [ ] ⚡ Performance improvement
+- [ ] ✅ Test update
+- [ ] 🔧 Configuration/build update
+
+## Related Issues
+
+<!-- Link related issues here using #issue-number -->
+
+Fixes #
+Relates to #
+
+## Changes Made
+
+<!-- List the specific changes made in this PR -->
+
+-
+-
+-
+
+## Testing
+
+<!-- Describe how you tested your changes -->
+
+- [ ] All existing tests pass (`uv run poe check`)
+- [ ] Added new tests for new functionality
+- [ ] Tested manually in the TUI
+
+### Manual Testing Steps
+
+1.
+2.
+3.
+
+## Screenshots/Demo
+
+<!-- If applicable, add screenshots or a demo of the changes -->
+
+## Checklist
+
+- [ ] My code follows the project's style guidelines
+- [ ] I have run `uv run poe fix` to format my code
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+
+## Additional Notes
+
+<!-- Any additional information that reviewers should know -->

kagan-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,13 @@
+# GitHub Copilot Instructions
+
+Read and strictly follow all guidelines defined in the [AGENTS.md](../AGENTS.md) file at the repository root.
+
+This file contains comprehensive instructions for:
+
+- Build and development commands
+- Project structure
+- Code style and conventions
+- Testing patterns
+- Git commit rules
+
+All rules in AGENTS.md are mandatory and must be followed without exception.

kagan-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      all:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

kagan-0.1.0/.github/workflows/cd.yaml

@@ -0,0 +1,132 @@
+name: Continuous Delivery
+
+run-name: ${{ inputs.docs_only && 'Docs Only' || (inputs.production_release && 'Production Release' || 'Beta Release') }}
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+  workflow_dispatch:
+    inputs:
+      production_release:
+        description: "Production release?"
+        type: boolean
+        required: true
+        default: false
+      docs_only:
+        description: "Publish docs only (skip release and PyPI)?"
+        type: boolean
+        required: true
+        default: false
+
+concurrency: release
+
+permissions:
+  contents: write
+  packages: read
+
+jobs:
+  release:
+    name: Semantic Release
+    # Skip release job when docs_only flag is set
+    if: ${{ !inputs.docs_only }}
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: mandatory for trusted publishing and GitHub releases
+      id-token: write
+      contents: write
+      packages: read
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.BOT_ID }}
+          private-key: ${{ secrets.BOT_SK }}
+
+      - uses: actions/checkout@v4
+        with:
+          # Fetch entire repository history so we can determine version number from it
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests and quality checks
+        run: |
+          set -o pipefail
+          uv run poe check
+
+      - name: Get branch name
+        shell: bash
+        run: echo "branch=${GITHUB_REF#refs/heads/}" >> $GITHUB_OUTPUT
+        id: get_branch
+
+      - name: Python Semantic Release - Beta (non-prod)
+        id: release-beta
+        if: steps.get_branch.outputs.branch == 'main' && !inputs.production_release
+        uses: python-semantic-release/python-semantic-release@v10.3.1
+        with:
+          github_token: ${{ steps.app-token.outputs.token }}
+          prerelease: true
+
+      - name: Python Semantic Release - Production
+        id: release-prod
+        if: steps.get_branch.outputs.branch == 'main' && inputs.production_release
+        uses: python-semantic-release/python-semantic-release@v10.3.1
+        with:
+          github_token: ${{ steps.app-token.outputs.token }}
+
+      - name: Publish to PyPI
+        if: (steps.release-beta.outputs.released == 'true') || (steps.release-prod.outputs.released == 'true')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+
+  publish-docs:
+    name: Publish Documentation
+    # Conditionally depend on release job (only when not docs_only mode)
+    needs: release
+    # Run docs publishing in two scenarios:
+    # 1. After a successful production release on main branch
+    # 2. When docs_only flag is set (on main branch only)
+    # Note: docs_only takes precedence if both flags are set
+    if: always() && !cancelled() && github.ref == 'refs/heads/main' && (needs.release.result == 'success' || needs.release.result == 'skipped') && (inputs.production_release || inputs.docs_only)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

kagan-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    paths:
+      - "**.py"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/ci.yml"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - run: uv sync --dev
+
+      - run: uv run poe check

kagan-0.1.0/.gitignore

@@ -0,0 +1,170 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+*.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/
+
+# 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
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.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/
+
+# UV specific
+.uv/
+uv.lock
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific
+.kagan/
+
+references/
+
+snapshot_report.html
+
+# Kagan MCP config (auto-generated)
+.mcp.json

kagan-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+repos:
+  # Pre-commit default hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+        exclude: ^(tests/__snapshots__/|CNAME$)
+      - id: trailing-whitespace
+        exclude: ^tests/__snapshots__/
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+        exclude: ^tests/__snapshots__/
+
+  # Markdown formatter
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        exclude: ^(\.github/|README\.md$|CNAME$|CHANGELOG\.md$)
+        additional_dependencies:
+          - mdformat-gfm
+          - mdformat-ruff
+
+  # UV lock file sync
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.26
+    hooks:
+      - id: uv-lock
+
+  # Local hooks using uv and poe tasks
+  - repo: local
+    hooks:
+      - id: lint
+        name: ruff lint
+        entry: uv run poe lint
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: format
+        name: ruff format
+        entry: uv run poe format
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: typecheck
+        name: pyrefly typecheck
+        entry: uv run poe typecheck
+        language: system
+        types: [python]
+        pass_filenames: false