ask-github 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ae01ffdb62eea1500c1e9544915704dbcc34d18f27124a82f3a3ee59c93e92b
-  data.tar.gz: 03a155f16c3e4409ea7383b7b071f0c55d7bd729ec553c70d8e92020e9b72d8f
+  metadata.gz: bd64129291b95815da38080f42a150a158ce4f9bfc154b243ad237c209bcd21c
+  data.tar.gz: 9a61c3deae1d9e1902e3c8cb379f1c17c44c6c58ddf9bed24fab10ad7da907bc
 SHA512:
-  metadata.gz: d40f074e53dd7d58e15dce513200921f23ac344fd2f1b505efb36a9d871b407993920dcfe39cf6ee925b7b67465aba444c24a156722bc2226614cd7e241df817
-  data.tar.gz: 03210c203eff7072f09d372ec8cf536cdf06ea013eb5f479728b35d08a23f1b96bff56a884eeee8a5d244a4409db41553955732479b2026262f09bc5605915c1
+  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/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.4"
+    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.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Kaka Ruto