ask-github 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81872d8db5d4f3e8a63eed5fb7bb856daa386f447f522331d8c30b97400ad0a5
+  data.tar.gz: d86d708a8e4fbaac994a2cedaab52458434fae36b08f9c7cae98d8b70b9ae079
+SHA512:
+  metadata.gz: 925160b0799b93e9c2665429c319594913a9346ab461ca9d14ba90809a7e264715c729f5513365681845f48f247ab468f6a91169361089f6346e52c910cf58e1
+  data.tar.gz: 0f44993f6e054c65512ddbed2a2ea0b2cef9e0436093e9edf0d224b55fbe94872964606ab0099eb0476036eb3adaa6a747e873f9cb2e3736d413f4eac2881c68

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial release of `ask-github` — GitHub service context for the ask-rb ecosystem.
+- **context.rb** — Metadata constants for AI system prompts: `DESCRIPTION`, `DOCS_URL`, `OPENAPI_URL`, `AUTH_NAME`, `AUTH_HOW`, `GEM_NAME`, `GEM_VERSION`, `GEM_DOCS`, `QUICK_START`
+- **client.rb** — `Ask::GitHub.client` returns an authenticated Octokit client via `Ask::Auth.resolve(:github_token)`. Wraps client in `ClientProxy` to convert `Octokit::Unauthorized` to `Ask::Auth::InvalidCredential`.
+- **error_guide.rb** — `Ask::GitHub::Errors` with rate limit info, HTTP status code descriptions, and exception guidance map for agents.
+- **Dependencies:** `ask-auth ~> 0.1`, `octokit ~> 9.0`
+- **Testing:** 26 tests, 69 assertions covering context constants, client auth flow, and error guide lookups.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# ask-github
+
+GitHub service context for AI agents in the ask-rb ecosystem.
+
+Provides an authenticated Octokit client, metadata constants for system prompts, and a structured error guide for common GitHub API issues.
+
+```ruby
+gem "ask-github"
+```
+
+## Quick Start
+
+### Get an authenticated client
+
+```ruby
+require "ask-github"
+
+client = Ask::GitHub.client
+client.issues("owner/repo")
+client.create_issue("owner/repo", "Title", "Body")
+client.pull_requests("owner/repo")
+client.contents("owner/repo", path: "Gemfile")
+client.search_issues("query")
+```
+
+The client is an `Octokit::Client` wrapped in a proxy that converts `Octokit::Unauthorized` into `Ask::Auth::InvalidCredential` with actionable error messages.
+
+### Authentication
+
+The client resolves a GitHub token via `Ask::Auth.resolve(:github_token)`. Tokens can be provided through any configured auth provider:
+
+1. **Environment variable:** `GITHUB_TOKEN`
+2. **Credentials file:** `~/.ask/credentials.yml`
+3. **Rails credentials:** `Rails.application.credentials.github_token`
+4. **OAuth / Database:** Custom providers
+
+Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) with the `repo` and `read:org` scopes.
+
+## Context Constants
+
+Use these constants to build system prompts for AI agents:
+
+| Constant | Value |
+|---|---|
+| `Ask::GitHub::DESCRIPTION` | "GitHub — code hosting, issues, pull requests, actions, packages" |
+| `Ask::GitHub::DOCS_URL` | https://docs.github.com/en/rest |
+| `Ask::GitHub::OPENAPI_URL` | https://api.github.com/openapi.json |
+| `Ask::GitHub::AUTH_NAME` | `:github_token` |
+| `Ask::GitHub::GEM_NAME` | `"octokit"` |
+| `Ask::GitHub::GEM_VERSION` | `"~> 9.0"` |
+| `Ask::GitHub::QUICK_START` | Copy-paste Ruby code snippet |
+
+## Error Guide
+
+`Ask::GitHub::Errors` provides structured knowledge for agents:
+
+```ruby
+Ask::GitHub::Errors.for("Octokit::NotFound")
+# => { message: "...", action: "..." }
+
+Ask::GitHub::Errors.status_code_description(404)
+# => "Not Found — Resource does not exist or is private."
+
+Ask::GitHub::Errors::RATE_LIMIT[:authenticated]
+# => "5,000 requests per hour"
+```
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/github/client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "octokit"
+require "ask/auth"
+
+module Ask
+  module GitHub
+    # Returns an authenticated Octokit client configured for an AI agent.
+    #
+    # Resolves the GitHub token via +Ask::Auth.resolve(:github_token)+ and
+    # configures the client with sensible defaults:
+    #
+    # - +auto_paginate+: +true+ (collects all pages automatically)
+    # - +per_page+: +100+ (maximum items per page)
+    # - +middleware+: Faraday retry middleware (3 retries, exponential backoff)
+    #
+    # The client is wrapped in a +ClientProxy+ that converts
+    # +Octokit::Unauthorized+ into +Ask::Auth::InvalidCredential+.
+    #
+    # @example
+    #   client = Ask::GitHub.client
+    #   client.issues("owner/repo")
+    #
+    # @return [Octokit::Client] an authenticated client
+    # @raise [Ask::Auth::MissingCredential] if no GitHub token is configured
+    # @raise [Ask::Auth::InvalidCredential] if the token is rejected (401)
+    def self.client
+      token = Ask::Auth.resolve(:github_token)
+
+      client = Octokit::Client.new(access_token: token, auto_paginate: true, per_page: 100)
+
+      # Configure Faraday retry middleware for transient failures
+      client.middleware = Faraday::RackBuilder.new do |builder|
+        builder.request :retry, max: 3, interval: 1, backoff_factor: 2,
+                                retry_statuses: [429, 500, 502, 503]
+        builder.adapter Faraday.default_adapter
+      end
+
+      ClientProxy.new(client)
+    end
+
+    # Proxies method calls to an +Octokit::Client+, converting authentication
+    # errors into +Ask::Auth::InvalidCredential+.
+    class ClientProxy < BasicObject
+      def initialize(client)
+        @client = client
+      end
+
+      def method_missing(name, ...)
+        @client.public_send(name, ...)
+      rescue ::Octokit::Unauthorized
+        ::Kernel.raise ::Ask::Auth::InvalidCredential, :github_token
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/ask/github/context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ask
+  module GitHub
+    # Human-readable description of the GitHub service context.
+    DESCRIPTION = "GitHub — code hosting, issues, pull requests, actions, packages"
+
+    # Base URL for GitHub REST API documentation.
+    DOCS_URL = "https://docs.github.com/en/rest"
+
+    # URL for the GitHub OpenAPI specification.
+    OPENAPI_URL = "https://api.github.com/openapi.json"
+
+    # Credential name used with Ask::Auth.resolve.
+    AUTH_NAME = :github_token
+
+    # Instructions for obtaining a GitHub personal access token.
+    AUTH_HOW = "https://github.com/settings/tokens — scopes: repo, read:org"
+
+    # Gem name for the GitHub API client.
+    GEM_NAME = "octokit"
+
+    # Required gem version constraint.
+    GEM_VERSION = "~> 9.0"
+
+    # URL for Octokit Ruby library documentation.
+    GEM_DOCS = "https://octokit.github.io/octokit.rb"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      client = Ask::GitHub.client
+      client.issues("owner/repo")
+      client.create_issue("owner/repo", "Title", "Body")
+      client.pull_requests("owner/repo")
+      client.contents("owner/repo", path: "Gemfile")
+      client.search_issues("query")
+    RUBY
+  end
+end

data/lib/ask/github/error_guide.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Ask
+  module GitHub
+    # Structured error knowledge for AI agents working with the GitHub API.
+    #
+    # Provides human-readable guidance for common HTTP status codes, rate
+    # limiting, pagination, and authentication errors encountered when
+    # using the Octokit client.
+    module Errors
+      # Rate limit information.
+      #
+      # - Authenticated requests: 5,000 requests per hour
+      # - Unauthenticated requests: 60 requests per hour
+      #
+      # When rate-limited, +Octokit::TooManyRequests+ is raised. The agent
+      # should wait for the reset time and retry.
+      RATE_LIMIT = {
+        authenticated: "5,000 requests per hour (using personal access token)",
+        anonymous: "60 requests per hour (no authentication)",
+        error_class: "Octokit::TooManyRequests",
+        action: "Wait for the rate limit reset window, then retry the request."
+      }.freeze
+
+      # Common HTTP status codes returned by the GitHub API and how to handle them.
+      STATUS_CODES = {
+        200 => "OK — Request succeeded.",
+        201 => "Created — Resource was created successfully.",
+        202 => "Accepted — Request accepted for processing (async operations).",
+        204 => "No Content — Request succeeded, no response body.",
+        301 => "Moved Permanently — The resource URL has changed; update your reference.",
+        304 => "Not Modified — Cached response is still valid (conditional request).",
+        401 => "Unauthorized — Token is missing, invalid, or revoked. Re-authenticate.",
+        403 => "Forbidden — Token lacks required scopes. Check token permissions.",
+        404 => "Not Found — Resource does not exist or is private.",
+        409 => "Conflict — Resource state conflict (e.g., merge conflict).",
+        410 => "Gone — Resource was removed permanently.",
+        422 => "Unprocessable Entity — Validation failed. Check request parameters.",
+        429 => "Too Many Requests — Rate limit exceeded. Wait before retrying.",
+        500 => "Internal Server Error — GitHub server issue. Retry with backoff.",
+        502 => "Bad Gateway — GitHub upstream issue. Retry with backoff.",
+        503 => "Service Unavailable — GitHub is down for maintenance. Retry later."
+      }.freeze
+
+      # Pagination guidance for large result sets.
+      PAGINATION = {
+        auto_paginate: "Octokit::Client is configured with auto_paginate: true by default.",
+        per_page: "Maximum items per page is 100. The default client uses 100.",
+        link_header: "GitHub uses Link headers for pagination. Octokit handles this automatically.",
+        max_results: "For very large queries, iterate pages or use GitHub's search API."
+      }.freeze
+
+      # Map of Octokit exception classes to human-readable guidance.
+      EXCEPTIONS = {
+        "Octokit::Unauthorized" => {
+          message: "Your GitHub token is invalid or has been revoked.",
+          action: "Generate a new token at https://github.com/settings/tokens with the 'repo' and 'read:org' scopes."
+        },
+        "Octokit::Forbidden" => {
+          message: "Your token lacks the required permissions for this operation.",
+          action: "Check your token scopes at https://github.com/settings/tokens. You may need additional scopes."
+        },
+        "Octokit::NotFound" => {
+          message: "The requested repository, issue, or resource does not exist or is private.",
+          action: "Verify the owner/repo name and that the repository is accessible with your token."
+        },
+        "Octokit::TooManyRequests" => {
+          message: "GitHub API rate limit exceeded.",
+          action: "Check X-RateLimit-Reset header, wait until that timestamp, then retry. Authenticated requests get 5,000/hr."
+        },
+        "Octokit::UnprocessableEntity" => {
+          message: "The request body failed validation.",
+          action: "Check required fields, data types, and constraints. GitHub returns detailed error messages in the response body."
+        },
+        "Octokit::ServerError" => {
+          message: "GitHub encountered a server error.",
+          action: "Retry with exponential backoff. If the issue persists, check https://www.githubstatus.com."
+        },
+        "Octokit::InvalidRepository" => {
+          message: "The repository name format is invalid.",
+          action: "Use the format 'owner/repo' (e.g., 'octocat/hello-world')."
+        }
+      }.freeze
+
+      # Look up guidance for an exception class name.
+      #
+      # @param exception_class [String] The exception class name (e.g., "Octokit::NotFound")
+      # @return [Hash, nil] A hash with +:message+ and +:action+ keys, or nil if unknown
+      def self.for(exception_class)
+        EXCEPTIONS[exception_class]
+      end
+
+      # Describe an HTTP status code.
+      #
+      # @param code [Integer] HTTP status code
+      # @return [String, nil] Description of the status code
+      def self.status_code_description(code)
+        STATUS_CODES[code]
+      end
+    end
+  end
+end

data/lib/ask/github/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module GitHub
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask-github.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ask/github/version"
+require_relative "ask/github/context"
+require_relative "ask/github/client"
+require_relative "ask/github/error_guide"

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: ask-github
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: octokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides authenticated Octokit client, context metadata, and error guide
+  for AI agents.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-github.rb
+- lib/ask/github/client.rb
+- lib/ask/github/context.rb
+- lib/ask/github/error_guide.rb
+- lib/ask/github/version.rb
+homepage: https://github.com/ask-rb/ask-github
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-github
+  source_code_uri: https://github.com/ask-rb/ask-github
+  changelog_uri: https://github.com/ask-rb/ask-github/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: GitHub service context for the ask-rb ecosystem
+test_files: []