kestrel-feature-github 0.1.0__tar.gz

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

@@ -0,0 +1,147 @@
+name: kestrel-feature-github CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/*'
+      - 'fix/*'
+      - 'release/*'
+      - 'codex/*'
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Tag or commit to test'
+        required: false
+        type: string
+
+env:
+  PYTHON_VERSION: "3.13"
+
+jobs:
+  lint-and-imports:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install ${{ env.PYTHON_VERSION }}
+      - name: Install package + test extras
+        run: |
+          uv venv --python ${{ env.PYTHON_VERSION }} .venv
+          . .venv/bin/activate
+          uv pip install -e '.[test]'
+      - name: Validate package imports
+        run: |
+          . .venv/bin/activate
+          python -c "
+          from kestrel_feature_github import GitHubFeature
+          import importlib.metadata as md
+          eps = md.entry_points(group='kestrel_sovereign.features')
+          names = [e.name for e in eps]
+          assert 'GitHubFeature' in names, f'Entry-point not registered: {names}'
+          print('kestrel_feature_github imports OK; feature class:', GitHubFeature.__name__)
+          "
+        timeout-minutes: 3
+
+  build-check:
+    runs-on: ubuntu-latest
+    needs: lint-and-imports
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install ${{ env.PYTHON_VERSION }}
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Inspect wheel contents
+        run: |
+          set -e
+          WHEEL=$(ls dist/*.whl | head -1)
+          echo "Inspecting $WHEEL"
+          uv run --no-project python -c "
+          import sys, zipfile
+          z = zipfile.ZipFile('$WHEEL')
+          names = z.namelist()
+          forbidden = [n for n in names if n.startswith('kestrel_sovereign/') or n.startswith('kestrel_sdk/')]
+          if forbidden:
+              print('ERROR: wheel contains framework/SDK content:', forbidden, file=sys.stderr)
+              sys.exit(1)
+          required = [
+              'kestrel_feature_github/__init__.py',
+              'kestrel_feature_github/feature.py',
+              'kestrel_feature_github/client.py',
+              'kestrel_feature_github/models.py',
+              'kestrel_feature_github/cache.py',
+              'kestrel_feature_github/ast_analyzer.py',
+          ]
+          missing = [m for m in required if m not in names]
+          if missing:
+              print('ERROR: wheel missing expected files:', missing, file=sys.stderr)
+              sys.exit(1)
+          print(f'Wheel OK ({len(names)} entries)')
+          "
+
+  install-check:
+    runs-on: ubuntu-latest
+    needs: build-check
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Clean install + smoke test
+        run: |
+          uv venv --python ${{ matrix.python-version }} .venv-test
+          . .venv-test/bin/activate
+          uv pip install .
+          python -c "
+          from kestrel_feature_github import GitHubFeature
+          import importlib.metadata as md
+          eps = md.entry_points(group='kestrel_sovereign.features')
+          names = [e.name for e in eps]
+          assert 'GitHubFeature' in names, f'Entry-point not registered: {names}'
+          print(f'kestrel-feature-github installs + entry-point OK on Python ${{ matrix.python-version }}')
+          "
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint-and-imports
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install ${{ env.PYTHON_VERSION }}
+      - name: Install + run pytest
+        run: |
+          uv venv --python ${{ env.PYTHON_VERSION }} .venv
+          . .venv/bin/activate
+          uv pip install -e '.[test]'
+          uv run --no-sync pytest tests/ -v --tb=short
+        timeout-minutes: 10

kestrel_feature_github-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v[0-9]+.[0-9]+.[0-9]+']
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Tag or commit to publish (e.g. v0.1.0)'
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: CI gate
+    uses: ./.github/workflows/ci.yml
+    with:
+      ref: ${{ inputs.ref || github.ref }}
+    secrets: inherit
+
+  build:
+    name: Build sdist + wheel
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build
+        run: uv build
+      - name: Verify the version metadata matches the tag
+        if: startsWith(inputs.ref, 'v') || startsWith(github.ref, 'refs/tags/v')
+        env:
+          INPUT_REF: ${{ inputs.ref }}
+        run: |
+          if [ -n "$INPUT_REF" ]; then
+            TAG_NAME="$INPUT_REF"
+          else
+            TAG_NAME="$GITHUB_REF_NAME"
+          fi
+          TAG_VERSION="${TAG_NAME#v}"
+          PKG_VERSION=$(uv run --no-project python -c "import tomllib; print(tomllib.loads(open('pyproject.toml').read())['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::tag $TAG_NAME does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+          echo "tag $TAG_NAME matches pyproject.toml version $PKG_VERSION"
+      - name: Show artifacts
+        run: ls -la dist/
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish via OIDC trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

kestrel_feature_github-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

kestrel_feature_github-0.1.0/AGENTS.md

@@ -0,0 +1,41 @@
+# kestrel-feature-github — Agent Instructions
+
+See [README.md](README.md) for package overview.
+
+## Package Structure
+
+```
+kestrel-feature-github/
+├── pyproject.toml
+├── README.md
+└── kestrel_feature_github/
+    ├── __init__.py
+    ├── SKILL.md
+    ├── feature.py         # GitHubFeature entry point
+    ├── client.py          # GitHub API client
+    ├── models.py          # Data models
+    ├── ast_analyzer.py    # AST analysis utilities
+    └── cache.py           # Response caching
+```
+
+## Entry Points
+
+- `kestrel_sovereign.features`: `GitHubFeature = "kestrel_feature_github:GitHubFeature"`
+
+## Key Files to Read First
+
+1. `kestrel_feature_github/feature.py` — Main feature class and tool registration
+2. `kestrel_feature_github/client.py` — GitHub API client implementation
+3. `kestrel_feature_github/SKILL.md` — Full skill/command reference
+
+## Running Tests
+
+```bash
+uv run pytest
+```
+
+## Agent-Specific Instructions
+
+- Imports are from `kestrel_feature_github`
+- Requires `GITHUB_TOKEN` environment variable for API access
+- API responses are cached via `cache.py` to reduce rate limiting

kestrel_feature_github-0.1.0/LICENSE

@@ -0,0 +1,106 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable patent license to make,
+have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES
+OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort, contract, or otherwise, unless required by applicable law, shall any
+Contributor be liable to You for damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer support, warranty,
+indemnity, or other liability obligations. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility.

kestrel_feature_github-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: kestrel-feature-github
+Version: 0.1.0
+Summary: Kestrel GitHub integration feature
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: kestrel-sovereign-sdk<1,>=0.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# kestrel-feature-github
+
+GitHub integration for Kestrel Sovereign agents — manage issues, pull requests, and repositories directly from agent conversations.
+
+## Installation
+
+```bash
+uv pip install kestrel-feature-github
+```
+
+## Dependencies
+
+- `kestrel-sovereign-sdk`
+- `httpx`
+- `pyyaml`
+- `aiosqlite`
+
+## Usage
+
+Once installed, the `GitHubFeature` is automatically discovered by kestrel-sovereign via the `kestrel_sovereign.features` entry point.
+
+See [SKILL.md](SKILL.md) for the full skill reference.
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token with repo access |
+
+## Development
+
+```bash
+uv sync --extra test
+uv run --extra test pytest
+```

kestrel_feature_github-0.1.0/README.md

@@ -0,0 +1,35 @@
+# kestrel-feature-github
+
+GitHub integration for Kestrel Sovereign agents — manage issues, pull requests, and repositories directly from agent conversations.
+
+## Installation
+
+```bash
+uv pip install kestrel-feature-github
+```
+
+## Dependencies
+
+- `kestrel-sovereign-sdk`
+- `httpx`
+- `pyyaml`
+- `aiosqlite`
+
+## Usage
+
+Once installed, the `GitHubFeature` is automatically discovered by kestrel-sovereign via the `kestrel_sovereign.features` entry point.
+
+See [SKILL.md](SKILL.md) for the full skill reference.
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token with repo access |
+
+## Development
+
+```bash
+uv sync --extra test
+uv run --extra test pytest
+```

kestrel_feature_github-0.1.0/kestrel_feature_github/SKILL.md

@@ -0,0 +1,101 @@
+# GitHubFeature
+
+> GitHub integration for issues, PRs, repository access, and code introspection.
+
+## Skills
+
+### read_github_file
+- **Description**: Read a file from a GitHub repository
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository in 'owner/repo' format, or 'self'
+  - `path` (string, required): Path to file within the repository
+  - `ref` (string, optional): Branch, tag, or commit SHA (default: main)
+
+### list_github_files
+- **Description**: List files in a GitHub repository directory
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository in 'owner/repo' format, or 'self'
+  - `path` (string, optional): Directory path (empty for root)
+  - `ref` (string, optional): Branch, tag, or commit SHA
+  - `recursive` (boolean, optional): If true, list all files recursively
+
+### search_github_code
+- **Description**: Search for code in GitHub repositories
+- **Category**: data_access
+- **Parameters**:
+  - `query` (string, required): Search query
+  - `repo` (string, optional): Limit to specific repo
+  - `path` (string, optional): Limit to path prefix
+  - `extension` (string, optional): Limit to file extension
+  - `max_results` (integer, optional): Maximum results (default 20)
+
+### get_code_definition
+- **Description**: Get a function or class definition from a Python file using AST
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository or 'self'
+  - `path` (string, required): Path to Python file
+  - `name` (string, required): Function or class name
+  - `ref` (string, optional): Branch, tag, or commit SHA
+
+### list_code_definitions
+- **Description**: List all functions and classes in a Python file
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository or 'self'
+  - `path` (string, required): Path to Python file
+  - `ref` (string, optional): Branch, tag, or commit SHA
+
+### get_self_repo_info
+- **Description**: Get information about the agent's own source repository
+- **Category**: data_access
+
+### list_source_components
+- **Description**: List all feature components in the agent's source code
+- **Category**: data_access
+- **Parameters**:
+  - `include_files` (boolean, optional): Include file listings for each component
+
+### get_component_source
+- **Description**: Get all source files for a specific feature component
+- **Category**: data_access
+- **Parameters**:
+  - `component` (string, required): Component name
+  - `include_content` (boolean, optional): Include file contents
+
+### invalidate_github_cache
+- **Description**: Invalidate cached GitHub content to force fresh fetch
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository to invalidate (or 'self')
+  - `path` (string, optional): Specific path to invalidate
+
+### list_github_issues
+- **Description**: List issues in a GitHub repository
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, optional): Repository or 'self' (default: self)
+  - `state` (string, optional): Issue state filter (default: open)
+  - `labels` (string, optional): Comma-separated label names
+  - `max_results` (integer, optional): Maximum results (default 30)
+
+### get_github_issue
+- **Description**: Get details of a specific GitHub issue
+- **Category**: data_access
+- **Parameters**:
+  - `issue_number` (integer, required): Issue number
+  - `repo` (string, optional): Repository or 'self' (default: self)
+
+### get_github_issue_comments
+- **Description**: Get comments on a specific GitHub issue
+- **Category**: data_access
+- **Parameters**:
+  - `issue_number` (integer, required): Issue number
+  - `repo` (string, optional): Repository or 'self' (default: self)
+  - `max_results` (integer, optional): Maximum comments (default 30)
+
+## Dependencies
+
+- Requires: kestrel-sovereign, httpx, pyyaml, aiosqlite

kestrel_feature_github-0.1.0/kestrel_feature_github/__init__.py

@@ -0,0 +1,4 @@
+"""Kestrel Feature: GitHub integration for issues, PRs, and repository management."""
+from .feature import GitHubFeature
+
+__all__ = ["GitHubFeature"]