ask-github 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f0e1e42270acf35d49dbe2b9ddacde65159b7aacc9812ec6936e663c32063e9
-  data.tar.gz: 95ab525daa2236b18f8eacf1bcf6ff1d9159a3616a2c2b0337575a57c29d7be0
+  metadata.gz: bd64129291b95815da38080f42a150a158ce4f9bfc154b243ad237c209bcd21c
+  data.tar.gz: 9a61c3deae1d9e1902e3c8cb379f1c17c44c6c58ddf9bed24fab10ad7da907bc
 SHA512:
-  metadata.gz: 93d4c3b6bcc51abdb61b6d2a088cf14184ccd8e6eb53a8bd7bf833611fb13cb6b5fb234568f4843aec0216feedffc7e9e6ffc1966552ce9d2c41c0be4d25ec31
-  data.tar.gz: e157ba7fe7bc3565eaca177cf26e5d46cbf96fee8fac978c2313c1efce784d703e2c2b8a4f78359826992e0387e127c6a623ee44bd1b157570a93a27678df45f
+  metadata.gz: 9a4e4598c8a7e4924b21d9fb4030c052b2efdb280dcee3c614515e59cf651f896a7320c5fc27d22c9af6509ce3c05c723606c37fe3b3e1a981f19489a8062239
+  data.tar.gz: d4d55c62f888a877a31c8b8fcc8523a5e073d5b4ec3f26d12f4936bd3bf3bd373b61bbd0b75aada7842bdbf60a031f8b38e3a1292adca5920a88faa7482f3748

data/CHANGELOG.md

@@ -4,6 +4,14 @@
 - Gemspec validation test. Infrastructure: rubocop, overcommit, bin/setup, CI matrix. VCR rake tasks for cassette freshness.
 # Changelog
 
+## [0.2.0] - 2026-08-16
+
+### Added
+
+- **client.rb** — `Ask::GitHub.client(token: nil)` accepts an explicit token (the connector path; token resolution still falls back to `Ask::Auth.resolve(:github_token)`).
+- **Content helpers** — `default_branch(repo)`, `tree(repo, branch:)`, `file(repo, path, branch:)`, and `license(repo)` for docs-as-code sources; 401s map to `Ask::Auth::InvalidCredential` like every other call.
+
+
 ## [0.1.2] - 2026-06-21
 
 ### Added

data/README.md

@@ -1,8 +1,12 @@
 # ask-github
 
-GitHub service context for AI agents in the ask-rb ecosystem.
+[![Gem Version](https://badge.fury.io/rb/ask-github.svg)](https://badge.fury.io/rb/ask-github)
 
-Provides an authenticated Octokit client, metadata constants for system prompts, and a structured error guide for common GitHub API issues.
+GitHub service context for AI agents in the ask-rb ecosystem. It provides an
+authenticated Octokit client for the GitHub REST API, metadata constants for
+system prompts, and a structured error guide for common GitHub API issues.
+
+## Installation
 
 ```ruby
 gem "ask-github"
@@ -10,8 +14,6 @@ gem "ask-github"
 
 ## Quick Start
 
-### Get an authenticated client
-
 ```ruby
 require "ask-github"
 
@@ -23,47 +25,42 @@ 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
+## Authentication
 
-Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) with the `repo` and `read:org` scopes.
+`Ask::GitHub.client` resolves a token via `Ask::Auth.resolve(:github_token)`.
+Set it in your environment:
 
-## Context Constants
+```bash
+export GITHUB_TOKEN=your_token_here
+```
 
-Use these constants to build system prompts for AI agents:
+Or add it to `~/.ask/credentials.yml`:
 
-| 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 |
+```yaml
+github_token: your_token_here
+```
 
-## Error Guide
+Credentials can also come from Rails credentials, a database, or an OAuth
+provider, depending on your `ask-auth` configuration. Generate a token at
+[github.com/settings/tokens](https://github.com/settings/tokens) with the
+`repo` and `read:org` scopes.
 
-`Ask::GitHub::Errors` provides structured knowledge for agents:
+## Key entry points
 
-```ruby
-Ask::GitHub::Errors.for("Octokit::NotFound")
-# => { message: "...", action: "..." }
+- `Ask::GitHub.client` - an authenticated `Octokit::Client` (auto-paginating,
+  `per_page: 100`, retry middleware). It is wrapped in a proxy that converts
+  `Octokit::Unauthorized` into `Ask::Auth::InvalidCredential`.
+- `Ask::GitHub::Errors` - structured error knowledge for agents: guidance by
+  exception class, HTTP status code descriptions, and rate limit info.
+- `Ask::GitHub::DESCRIPTION`, `DOCS_URL`, `AUTH_NAME`, `GEM_NAME`,
+  `GEM_VERSION`, and `QUICK_START` - metadata constants for system prompts.
 
-Ask::GitHub::Errors.status_code_description(404)
-# => "Not Found — Resource does not exist or is private."
+## Full documentation
 
-Ask::GitHub::Errors::RATE_LIMIT[:authenticated]
-# => "5,000 requests per hour"
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+[Services: GitHub](https://ask-rb.github.io/ask-docs/services/github) covers
+ask-github in depth, including the client, error guide, and constants.
+API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 

data/lib/ask/github/client.rb

@@ -5,27 +5,36 @@ require "ask/auth"
 
 module Ask
   module GitHub
-    # Returns an authenticated Octokit client configured for an AI agent.
+    # Returns an authenticated Octokit client configured for an AI agent
+    # or a content connector.
     #
-    # Resolves the GitHub token via +Ask::Auth.resolve(:github_token)+ and
-    # configures the client with sensible defaults:
+    # Resolves the GitHub token via +Ask::Auth.resolve(:github_token)+,
+    # or uses the +token:+ given explicitly (the connector path — the
+    # token comes from the host app's own credential store). 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+.
+    # +Octokit::Unauthorized+ into +Ask::Auth::InvalidCredential+, and
+    # exposes the repo-content helpers (+default_branch+, +tree+, +file+,
+    # +license+) for docs-as-code sources.
     #
     # @example
     #   client = Ask::GitHub.client
     #   client.issues("owner/repo")
     #
-    # @return [Octokit::Client] an authenticated client
+    # @example connector with an explicit token
+    #   client = Ask::GitHub.client(token: credential.token)
+    #   client.default_branch("owner/repo")
+    #
+    # @return [ClientProxy] 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)
+    def self.client(token: nil)
+      token ||= Ask::Auth.resolve(:github_token)
 
       client = Octokit::Client.new(access_token: token, auto_paginate: true, per_page: 100)
 
@@ -39,11 +48,78 @@ module Ask
       ClientProxy.new(client)
     end
 
-    # Proxies method calls to an +Octokit::Client+, converting authentication
-    # errors into +Ask::Auth::InvalidCredential+.
+    # The repo-content helpers: the raw pieces a docs-as-code connector
+    # needs (tree listing, raw file reads, the default branch, and the
+    # repo's license). Explicit methods, so connectors never poke at
+    # Octokit's full surface.
+    class Content
+      def initialize(client)
+        @client = client
+      end
+
+      # The repository's default branch name (e.g. "main").
+      def default_branch(repo)
+        call { @client.repo(repo).default_branch }
+      end
+
+      # The recursive file tree for a branch: [{path:, type:}] entries.
+      # GitHub truncates enormous trees; callers bound what they consume.
+      def tree(repo, branch: nil)
+        sha = branch || default_branch(repo)
+        call { @client.tree(repo, sha, recursive: true) }.tree.map do |entry|
+          {path: entry.path, type: entry.type}
+        end
+      end
+
+      # A file's raw content at a path, or nil when the path doesn't exist.
+      def file(repo, path, branch: nil)
+        call do
+          @client.contents(repo, path: path, ref: branch || default_branch(repo),
+            accept: "application/vnd.github.raw")
+        end
+      rescue ::Octokit::NotFound
+        nil
+      end
+
+      # The repo's SPDX license id (e.g. "mit"), or nil when unlicensed.
+      def license(repo)
+        call { @client.license(repo) }&.license&.spdx_id
+      rescue ::Octokit::NotFound
+        nil
+      end
+
+      private
+
+      def call
+        yield
+      rescue ::Octokit::Unauthorized
+        ::Kernel.raise ::Ask::Auth::InvalidCredential, :github_token
+      end
+    end
+
+    # Proxies method calls to an +Octokit::Client+, converting
+    # authentication errors into +Ask::Auth::InvalidCredential+, and
+    # exposing the content helpers.
     class ClientProxy < BasicObject
       def initialize(client)
         @client = client
+        @content = ::Ask::GitHub::Content.new(client)
+      end
+
+      def default_branch(repo)
+        @content.default_branch(repo)
+      end
+
+      def tree(repo, branch: nil)
+        @content.tree(repo, branch: branch)
+      end
+
+      def file(repo, path, branch: nil)
+        @content.file(repo, path, branch: branch)
+      end
+
+      def license(repo)
+        @content.license(repo)
       end
 
       def method_missing(name, ...)
@@ -52,9 +128,13 @@ module Ask
         ::Kernel.raise ::Ask::Auth::InvalidCredential, :github_token
       end
 
-      def respond_to_missing?(name, include_private = false)
-        @client.respond_to?(name, include_private) || super
+      # BasicObject has no +respond_to?+ — report the content helpers
+      # explicitly, forward everything else to the wrapped client.
+      def respond_to?(name, include_private = false)
+        CONTENT_METHODS.include?(name) || @client.respond_to?(name, include_private)
       end
+
+      CONTENT_METHODS = %i[default_branch tree file license].freeze
     end
   end
 end

data/lib/ask/github/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module GitHub
-    VERSION = "0.1.3"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-github
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: octokit
   requirement: !ruby/object:Gem::Requirement
@@ -160,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.18
 specification_version: 4
 summary: GitHub service context for the ask-rb ecosystem
 test_files: []