matimo-github 0.1.0__py3-none-any.whl

matimo_github/__init__.py

@@ -0,0 +1,17 @@
+"""Matimo github provider — exposes the path to YAML tool definitions."""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+
+def get_tools_path() -> str:
+    """Return the absolute path to the bundled github tool definitions."""
+    try:
+        ref = importlib.resources.files("matimo_github") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+
+__all__ = ["get_tools_path"]

matimo_github/tools/add-collaborator/definition.yaml

@@ -0,0 +1,73 @@
+name: github-add-collaborator
+description: Add a user as a collaborator to a repository
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  username:
+    type: string
+    required: true
+    description: GitHub username to add
+  permission:
+    type: string
+    required: false
+    description: Permission level - pull, triage, push, maintain, or admin
+    default: push
+
+execution:
+  type: http
+  method: PUT
+  url: 'https://api.github.com/repos/{owner}/{repo}/collaborators/{username}'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    permission: '{permission}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Repository administration
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    invitee:
+      type: object
+    permissions:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Add collaborator with push access
+    params:
+      owner: myorg
+      repo: myrepo
+      username: newuser
+      permission: push
+  - name: Add collaborator with admin access
+    params:
+      owner: myorg
+      repo: myrepo
+      username: admin_user
+      permission: admin

matimo_github/tools/create-issue/definition.yaml

@@ -0,0 +1,96 @@
+name: github-create-issue
+description: Create a new issue in a repository
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  title:
+    type: string
+    required: true
+    description: Issue title
+  body:
+    type: string
+    required: false
+    description: Issue description (markdown supported)
+  assignees:
+    type: array
+    required: false
+    description: Array of github usernames to assign
+  labels:
+    type: array
+    required: false
+    description: Array of label names
+  milestone:
+    type: number
+    required: false
+    description: Milestone ID number
+
+execution:
+  type: http
+  method: POST
+  url: 'https://api.github.com/repos/{owner}/{repo}/issues'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    title: '{title}'
+    body: '{body}'
+    assignees: '{assignees}'
+    labels: '{labels}'
+    milestone: '{milestone}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Issues write
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    number:
+      type: number
+      description: Issue number in repository
+    title:
+      type: string
+    state:
+      type: string
+    html_url:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Create simple issue
+    params:
+      owner: myorg
+      repo: myrepo
+      title: Bug in login flow
+      body: Users cannot log in with SSO
+  - name: Create issue with labels
+    params:
+      owner: myorg
+      repo: myrepo
+      title: Add dark mode
+      body: Implement dark theme
+      labels:
+        - enhancement
+        - ui

matimo_github/tools/create-pull-request/definition.yaml

@@ -0,0 +1,103 @@
+name: github-create-pull-request
+description: Create a new pull request
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  title:
+    type: string
+    required: true
+    description: Pull request title
+  body:
+    type: string
+    required: false
+    description: Pull request description
+  head:
+    type: string
+    required: true
+    description: Head branch name or user:ref
+  base:
+    type: string
+    required: true
+    description: Base branch name
+  draft:
+    type: boolean
+    required: false
+    description: Whether PR is a draft
+    default: false
+  maintainer_can_modify:
+    type: boolean
+    required: false
+    description: Allow maintainers to edit PR
+    default: true
+
+execution:
+  type: http
+  method: POST
+  url: 'https://api.github.com/repos/{owner}/{repo}/pulls'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    title: '{title}'
+    body: '{body}'
+    head: '{head}'
+    base: '{base}'
+    draft: '{draft}'
+    maintainer_can_modify: '{maintainer_can_modify}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Pull requests write
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    number:
+      type: number
+    title:
+      type: string
+    state:
+      type: string
+    html_url:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Create pull request
+    params:
+      owner: myorg
+      repo: myrepo
+      title: Add new feature
+      body: This PR adds support for...
+      head: feature/new-feature
+      base: main
+  - name: Create draft PR
+    params:
+      owner: myorg
+      repo: myrepo
+      title: WIP - Feature in progress
+      head: feature/experimental
+      base: main
+      draft: true

matimo_github/tools/create-release/definition.yaml

@@ -0,0 +1,103 @@
+name: github-create-release
+description: Create a new release in a repository
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  tag_name:
+    type: string
+    required: true
+    description: Release tag name (e.g., v1.0.0)
+  name:
+    type: string
+    required: false
+    description: Release name
+  body:
+    type: string
+    required: false
+    description: Release notes/description
+  draft:
+    type: boolean
+    required: false
+    description: Create as draft release
+    default: false
+  prerelease:
+    type: boolean
+    required: false
+    description: Mark as prerelease
+    default: false
+  target_commitish:
+    type: string
+    required: false
+    description: Target branch or commit SHA
+
+execution:
+  type: http
+  method: POST
+  url: 'https://api.github.com/repos/{owner}/{repo}/releases'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    tag_name: '{tag_name}'
+    name: '{name}'
+    body: '{body}'
+    draft: '{draft}'
+    prerelease: '{prerelease}'
+    target_commitish: '{target_commitish}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Repository content write
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    tag_name:
+      type: string
+    name:
+      type: string
+    draft:
+      type: boolean
+    prerelease:
+      type: boolean
+    html_url:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Create release
+    params:
+      owner: myorg
+      repo: myrepo
+      tag_name: v1.0.0
+      name: Version 1.0.0
+      body: Initial release with core features
+  - name: Create prerelease
+    params:
+      owner: myorg
+      repo: myrepo
+      tag_name: v2.0.0-beta
+      prerelease: true
+      draft: true

matimo_github/tools/create-repository/definition.yaml

@@ -0,0 +1,112 @@
+name: github-create-repository
+description: Create a new repository in an organization or user account
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  org:
+    type: string
+    required: false
+    description: Organization name (omit for personal repos)
+  name:
+    type: string
+    required: true
+    description: Repository name
+  description:
+    type: string
+    required: false
+    description: Repository description
+  private:
+    type: boolean
+    required: false
+    description: Whether repo is private
+    default: false
+  has_issues:
+    type: boolean
+    required: false
+    description: Enable issues feature
+    default: true
+  has_wiki:
+    type: boolean
+    required: false
+    description: Enable wiki feature
+    default: true
+  has_downloads:
+    type: boolean
+    required: false
+    description: Enable downloads feature
+    default: true
+  auto_init:
+    type: boolean
+    required: false
+    description: Initialize with README, .gitignore, license
+    default: false
+  license_template:
+    type: string
+    required: false
+    description: License template (mit, apache-2.0, etc.)
+  gitignore_template:
+    type: string
+    required: false
+    description: Gitignore template (Node, Python, etc.)
+
+execution:
+  type: http
+  method: POST
+  url: 'https://api.github.com/orgs/{org}/repos'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+    Content-Type: application/json
+  body:
+    name: '{name}'
+    description: '{description}'
+    private: '{private}'
+    has_issues: '{has_issues}'
+    has_wiki: '{has_wiki}'
+    auto_init: '{auto_init}'
+    license_template: '{license_template}'
+    gitignore_template: '{gitignore_template}'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Repo write
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    name:
+      type: string
+    full_name:
+      type: string
+    private:
+      type: boolean
+    html_url:
+      type: string
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Create public repository
+    params:
+      org: myorg
+      name: new-project
+      description: My new project
+  - name: Create private repo with license
+    params:
+      org: myorg
+      name: private-tools
+      private: true
+      license_template: mit
+      auto_init: true

matimo_github/tools/delete-repository/definition.yaml

@@ -0,0 +1,51 @@
+name: github-delete-repository
+description: Delete a repository (requires admin access)
+version: '1.0.0'
+requires_approval: true
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+
+execution:
+  type: http
+  method: DELETE
+  url: 'https://api.github.com/repos/{owner}/{repo}'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+  timeout: 15000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    required: true
+    permission: Admin (repository deletion/destruction)
+    caution: This is a destructive operation and cannot be undone
+
+output_schema:
+  type: object
+  properties:
+    status:
+      type: number
+      description: HTTP 204 status code on success
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: Delete repository
+    params:
+      owner: myorg
+      repo: deprecated-project

matimo_github/tools/get-issue/definition.yaml

@@ -0,0 +1,70 @@
+name: github-get-issue
+description: Get details of a specific issue
+version: '1.0.0'
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+  issue_number:
+    type: number
+    required: true
+    description: Issue number
+
+execution:
+  type: http
+  method: GET
+  url: 'https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+  timeout: 10000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    optional: Public repos don't require authentication
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    number:
+      type: number
+    title:
+      type: string
+    body:
+      type: string
+    state:
+      type: string
+    assignees:
+      type: array
+    labels:
+      type: array
+    created_at:
+      type: string
+    updated_at:
+      type: string
+    html_url:
+      type: string
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: Get issue details
+    params:
+      owner: kubernetes
+      repo: kubernetes
+      issue_number: 12345

matimo_github/tools/get-repository/definition.yaml

@@ -0,0 +1,83 @@
+name: github-get-repository
+description: Get detailed information about a repository
+version: '1.0.0'
+
+parameters:
+  owner:
+    type: string
+    required: true
+    description: Repository owner username or organization
+  repo:
+    type: string
+    required: true
+    description: Repository name
+
+execution:
+  type: http
+  method: GET
+  url: 'https://api.github.com/repos/{owner}/{repo}'
+  headers:
+    Accept: application/vnd.github+json
+    Authorization: 'Bearer {GITHUB_TOKEN}'
+    X-GitHub-Api-Version: '2022-11-28'
+  timeout: 10000
+
+authentication:
+  type: bearer
+  location: header
+  notes:
+    env: GITHUB_TOKEN
+    optional: Public repos don't require authentication
+
+output_schema:
+  type: object
+  properties:
+    id:
+      type: number
+    name:
+      type: string
+    full_name:
+      type: string
+    owner:
+      type: object
+    private:
+      type: boolean
+    description:
+      type: string
+    fork:
+      type: boolean
+    created_at:
+      type: string
+    updated_at:
+      type: string
+    pushed_at:
+      type: string
+    homepage:
+      type: string
+    language:
+      type: string
+    stargazers_count:
+      type: number
+    watchers_count:
+      type: number
+    forks_count:
+      type: number
+    open_issues_count:
+      type: number
+    topics:
+      type: array
+    archived:
+      type: boolean
+    disabled:
+      type: boolean
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: Get repository info
+    params:
+      owner: kubernetes
+      repo: kubernetes