githuh 0.3.0 → 0.4.1

data/README.md

@@ -0,0 +1,351 @@
+# Githuh — GitHub API Client
+
+[![Ruby](https://github.com/kigster/githuh/workflows/Ruby/badge.svg)](https://github.com/kigster/githuh/actions?query=workflow%3ARuby)
+![Coverage](docs/img/badge.svg)
+
+As in... *git? huh?*
+
+Githuh is a GitHub API client wrapper built on top of [Octokit](https://github.com/octokit/octokit.rb), using an extensible `dry-cli` command pattern. It is designed as a batteries-included CLI for tasks that are tedious to do through the GitHub web UI — exporting issues, generating repository listings, and (now) LLM-summarizing READMEs into human-readable descriptions.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Commands](#commands)
+  - [`githuh version`](#githuh-version)
+  - [`githuh user info`](#githuh-user-info)
+  - [`githuh repo list`](#githuh-repo-list)
+  - [`githuh issue export`](#githuh-issue-export)
+- [Global Options](#global-options)
+- [LLM Support](#llm-support)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Repository listing** in Markdown or JSON, with fork/private filtering
+- **LLM-generated descriptions** — fetch each repo's README and summarize it into a flowing 5–6 sentence blurb using either Anthropic (Claude) or OpenAI
+- **Issue export** to JSON or [Pivotal Tracker-compatible CSV](https://www.pivotaltracker.com/help/articles/csv_import_export), with configurable label → point mapping
+- **User info** for the currently-authenticated GitHub user
+- **In-process architecture** — every command is also runnable inside another Ruby process for scripting and testing (~89% test coverage via Aruba in-process)
+
+## Installation
+
+```bash
+gem install githuh
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem 'githuh'
+```
+
+## Authentication
+
+Githuh reads your GitHub token, in priority order, from:
+
+1. The `--api-token=<token>` CLI flag
+1. The `GITHUB_TOKEN` environment variable
+1. `user.token` in your global git config
+
+To set the token globally in git (recommended):
+
+```bash
+git config --global --add user.token <your-github-pat>
+```
+
+To set it for a single session:
+
+```bash
+export GITHUB_TOKEN=<your-github-pat>
+```
+
+Alternatively, use a local `.env` file (see [LLM Support](#llm-support) below — Githuh auto-loads `.env` from the current directory and from `$HOME`).
+
+## Commands
+
+All invocations assume `githuh` is on your `PATH`. If running from a source checkout use `bundle exec exe/githuh` instead.
+
+### `githuh version`
+
+Print the current version string (no color, no banner — scriptable):
+
+```bash
+githuh version
+# => 0.4.0
+```
+
+Aliases: `githuh v`, `githuh -v`, `githuh --version`.
+
+______________________________________________________________________
+
+### `githuh user info`
+
+Print information about the currently authenticated user.
+
+```
+Command:
+  githuh user info
+
+Options:
+  --api-token=VALUE   # Github API token; if not given, user.token is read from ~/.gitconfig
+  --per-page=VALUE    # Pagination page size for Github API, default: 20
+  --[no-]info         # Print UI elements, like the progress bar, default: true
+  --[no-]verbose      # Print additional debugging info, default: false
+  --help, -h          # Print this help
+```
+
+#### Examples
+
+```bash
+# Default invocation (uses token from git config or GITHUB_TOKEN)
+githuh user info
+
+# Supply the token explicitly
+githuh user info --api-token=ghp_XXXXXXXXXXXXXXXXXXXX
+
+# Suppress the summary box (handy for piping)
+githuh user info --no-info
+
+# Verbose, for debugging auth/permissions issues
+githuh user info --verbose
+```
+
+______________________________________________________________________
+
+### `githuh repo list`
+
+List the authenticated user's owned repositories and render them as Markdown or JSON. The default output file is `<username>.repositories.<format>`.
+
+```
+Command:
+  githuh repo list
+
+Options:
+  --api-token=VALUE   # Github API token; if not given, user.token is read from ~/.gitconfig
+  --per-page=VALUE    # Pagination page size for Github API, default: 20
+  --[no-]info         # Print UI elements, like the progress bar, default: true
+  --[no-]verbose      # Print additional debugging info, default: false
+  --file=VALUE        # Output file, overrides <username>.repositories.<format>
+  --format=VALUE      # Output format: (markdown/json), default: "markdown"
+  --forks=VALUE       # Include or exclude forks: (exclude/include/only), default: "exclude"
+  --[no-]private      # If specified, returns only private repos for true, public for false
+  --[no-]llm          # Use LLM (ANTHROPIC_API_KEY or OPENAI_API_KEY) to summarize README, default: false
+  --help, -h          # Print this help
+```
+
+#### Examples
+
+Default Markdown output with forks excluded, saved to `<username>.repositories.md`:
+
+```bash
+githuh repo list
+```
+
+Public repos only, custom output file:
+
+```bash
+githuh repo list --no-private --file=my-public-repos.md
+```
+
+JSON output for programmatic consumption:
+
+```bash
+githuh repo list --format=json --file=repos.json
+```
+
+Only forks — useful for auditing what you've forked vs. maintained:
+
+```bash
+githuh repo list --forks=only
+```
+
+Include everything, private + public + forks:
+
+```bash
+githuh repo list --forks=include --private
+```
+
+Bump the API page size (GitHub allows up to 100):
+
+```bash
+githuh repo list --per-page=100
+```
+
+Quiet mode (no progress bars, for scripting):
+
+```bash
+githuh repo list --no-info --no-verbose
+```
+
+LLM-summarized descriptions (see [LLM Support](#llm-support)):
+
+```bash
+githuh repo list --llm
+```
+
+All options combined — public repos, Markdown format, LLM summaries, verbose:
+
+```bash
+githuh repo list \
+  --format=markdown \
+  --no-private \
+  --forks=exclude \
+  --llm \
+  --verbose \
+  --file=portfolio.md
+```
+
+______________________________________________________________________
+
+### `githuh issue export`
+
+Export issues for a given repository into JSON or [Pivotal Tracker-compatible CSV](https://www.pivotaltracker.com/help/articles/csv_import_export). The default output file is `<username>.<repo>.issues.<format>`.
+
+```
+Command:
+  githuh issue export REPO
+
+Arguments:
+  REPO                 # REQUIRED Name of the repo, eg "rails/rails"
+
+Options:
+  --api-token=VALUE    # Github API token; if not given, user.token is read from ~/.gitconfig
+  --per-page=VALUE     # Pagination page size for Github API, default: 20
+  --[no-]info          # Print UI elements, like the progress bar, default: true
+  --[no-]verbose       # Print additional debugging info, default: false
+  --file=VALUE         # Output file, overrides <username>.<repo>.issues.<format>
+  --format=VALUE       # Output format: (json/csv), default: "csv"
+  --mapping=VALUE      # YAML file with label to estimates mapping
+  --help, -h           # Print this help
+```
+
+#### Label-to-Estimate Mapping
+
+When exporting to Pivotal Tracker CSV, GitHub labels can be mapped to point estimates. Create a YAML file like this:
+
+```yaml
+---
+label-to-estimates:
+  Large: 5
+  Medium: 3
+  Small: 1
+```
+
+…and pass it via `--mapping=<path>`. Any label listed in the file is converted to its numeric estimate; other labels pass through unchanged in the `Labels` column.
+
+#### Examples
+
+Export all open issues from `rails/rails` as CSV:
+
+```bash
+githuh issue export rails/rails
+```
+
+Explicit format and output file:
+
+```bash
+githuh issue export rails/rails --format=json --file=rails-issues.json
+```
+
+Pivotal Tracker CSV with a label mapping:
+
+```bash
+githuh issue export kigster/githuh --mapping=config/label-mapping.yml
+```
+
+Quiet, scripted invocation with an explicit token:
+
+```bash
+githuh issue export kigster/githuh \
+  --api-token=ghp_XXXXXXXXXXXXXXXXXXXX \
+  --no-info \
+  --no-verbose \
+  --file=issues.csv
+```
+
+______________________________________________________________________
+
+## Global Options
+
+The following options are available on every subcommand (`user info`, `repo list`, `issue export`):
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--api-token=VALUE` | _(from env / git config)_ | GitHub personal access token |
+| `--per-page=VALUE` | `20` | Pagination page size for the GitHub API |
+| `--[no-]info` | `true` | Print UI elements like the progress bar and info boxes |
+| `--[no-]verbose` | `false` | Print additional debugging info |
+| `--help, -h` | — | Print contextual help and exit |
+
+## LLM Support
+
+When you pass `--llm` to `repo list`, Githuh fetches each repo's README via the GitHub API and asks an LLM to summarize it into a 5–6 sentence description. This is far more informative than GitHub's single-line description field, especially for portfolios or internal directories.
+
+### Configuration
+
+Set one of the following in your environment or in a `.env` file at the project root or `$HOME`:
+
+```bash
+# Preferred (uses claude-haiku-4-5-20251001)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Fallback (uses gpt-4o-mini)
+OPENAI_API_KEY=sk-...
+```
+
+If both are set, Anthropic is preferred. If `--llm` is set but neither key is available, the command exits with a clear error.
+
+A `.env` parser is built in (no `dotenv` gem required). `.env` is also in `.gitignore` by default to keep secrets out of commits.
+
+### Behavior
+
+On `repo list --llm` you will see:
+
+1. An info box announcing LLM summarization (provider + model)
+1. The regular `Format / File / Forks` info box
+1. The pagination progress bar (magenta)
+1. An LLM progress bar — **yellow for Anthropic**, **green for OpenAI** — advancing once per repo
+1. A success box with the total record count
+
+Each repo's description in the output is replaced with the LLM-generated summary. On any per-repo failure (README fetch error, LLM timeout, auth failure, etc.) the command falls back silently to GitHub's original description — use `--verbose` to see why.
+
+### Cost & Performance
+
+For 30–50 repos, expect:
+
+- **Wall-clock**: ~45–90 seconds (sequential — one README fetch + one LLM call per repo)
+- **Cost**: roughly $0.01–$0.05 per run with the default models
+
+### Example
+
+```bash
+# Complete portfolio run
+githuh repo list \
+  --format=markdown \
+  --no-private \
+  --forks=exclude \
+  --llm \
+  --file=portfolio.md
+```
+
+## Contributing
+
+Pull requests welcome at <https://github.com/kigster/githuh/pulls>.
+
+Development setup:
+
+```bash
+git clone git@github.com:kigster/githuh.git
+cd githuh
+bundle install
+just test      # run the rspec suite
+just lint      # run rubocop
+just format    # auto-correct rubocop offenses
+```
+
+## License
+
+© 2020–present Konstantin Gredeskoul, released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'timeout'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
+require "yard"
 
 def shell(*args)
   puts "running: #{args.join(' ')}"
-  system(args.join(' '))
+  system(args.join(" "))
 end
 
 task :clean do
-  shell('rm -rf pkg/ tmp/ coverage/ doc/ ' )
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
 end
 
 task gem: [:build] do
-  shell('gem install pkg/*')
+  shell("gem install pkg/*")
 end
 
 task permissions: [:clean] do
@@ -24,6 +25,12 @@ end
 
 task build: :permissions
 
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt WARRANTY.md CHANGELOG.md]
+  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
+  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
+end
+
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec

data/docs/img/badge.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#97CA00" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">89%</text>
+    <text x="80" y="14">89%</text>
+  </g>
+</svg>

data/docs/img/coverage.svg

@@ -11,7 +11,7 @@
   <g fill="#fff" text-anchor="middle" font-weight="500" font-family="Consolas,DejaVu Sans,Verdana,Geneva,sans-serif" font-size="10">
     <text x="40.5" y="15" fill="#010101" fill-opacity=".3">COVERAGE</text>
     <text x="41.5" y="14">COVERAGE</text>
-    <text x="105.5" y="15" fill="#010101" fill-opacity=".3">68%</text>
-    <text x="106.5" y="14">68%</text>
+    <text x="105.5" y="15" fill="#010101" fill-opacity=".3">0%</text>
+    <text x="106.5" y="14">0%</text>
   </g>
 </svg>

data/githuh.gemspec

@@ -22,24 +22,19 @@ Gem::Specification.new do |spec|
   spec.bindir                = 'exe'
   spec.executables           = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths         = ['lib']
-  spec.required_ruby_version = '>= 2.3'
+  spec.required_ruby_version = '~> 4.0'
 
   spec.add_dependency 'activesupport'
   spec.add_dependency 'colored2', '~> 3'
-  spec.add_dependency 'dry-cli', '~> 0.6'
+  spec.add_dependency 'csv'
+  spec.add_dependency 'dry-cli'
+  spec.add_dependency 'faraday'
+  spec.add_dependency 'faraday-retry'
   spec.add_dependency 'hashie'
-  spec.add_dependency 'octokit', '~> 4'
+  spec.add_dependency 'octokit'
   spec.add_dependency 'tty-box'
   spec.add_dependency 'tty-progressbar'
   spec.add_dependency 'tty-screen'
 
-  spec.add_development_dependency 'aruba', '= 1.0.0'
-  spec.add_development_dependency 'awesome_print', '~> 1'
-  spec.add_development_dependency 'bundler', '~> 2'
-  spec.add_development_dependency 'rake', '~> 13'
-  spec.add_development_dependency 'rspec', '~> 3'
-  spec.add_development_dependency 'rspec-its', '~> 1'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'simplecov-formatter-badge'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/justfile

@@ -0,0 +1,57 @@
+set shell := ["bash", "-lc"]
+
+rbenv := 'eval "$(rbenv init -)"'
+
+[no-exit-message]
+recipes:
+    @just --choose
+
+# Sync all dependencies
+install:
+    {{rbenv}} && bundle install -j 12
+
+upgrade:
+    {{rbenv}} && bundle update --bundler
+    {{rbenv}} && bundle update
+
+# Lint and reformat files
+lint-fix *args:
+    {{rbenv}} && bundle exec rubocop -a
+    {{rbenv}} && bundle exec rubocop --auto-gen-config
+    git add .
+
+alias format := lint-fix
+
+# Lint and reformat files
+lint:
+    {{rbenv}} && bundle exec rubocop
+
+# Run all the tests
+test *args: 
+    #!/usr/bin/env bash
+    {{rbenv}} && RAILS_ENV=test GITHUB_TOKEN=$(git config user.token) bundle exec rspec {{args}}
+
+# Run tests with coverage
+test-coverage: test
+    open coverage/index.html
+
+doc:
+    {{rbenv}} && bundle exec rake doc
+    open doc/index.html
+    
+clean:
+    #!/usr/bin/env bash
+    find . -name .DS_Store -delete -print || true
+    rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+ci:
+    {{rbenv}} && lefthook run pre-commit --all-files
+
+changelog:
+    #!/usr/bin/env bash
+    export CHANGELOG_GITHUB_TOKEN=$(git config user.token)
+    command -v github_changelog_generator >/dev/null || brew install github_changelog_generator
+    github_changelog_generator --user kigster --repo githuh
+
+

data/lefthook.yml

@@ -0,0 +1,35 @@
+output:
+  - summary
+  - failure
+
+pre-commit:
+  parallel: true
+  jobs:
+    - name: lint
+      run: bundle exec rubocop -c .rubocop.yml {staged_files}
+      glob: "*.{rb,Gemfile}"
+      stage_fixed: true
+
+    - name: check for conflict markers and whitespace issues
+      run: git --no-pager diff --check
+
+    # If tests take >1 second, move this (or just the long-running tests) to pre-push.
+    - name: run tests
+      run: just test
+
+    - name: fix rubocop formatting issues
+      run: bundle exec rubocop -a {staged_files}
+      glob: "*.{rb,Gemfile,gemspec}"
+      stage_fixed: true
+
+    - name: spell check
+      run: codespell {staged_files}
+      glob: "*.{rb,md,gemspec}"
+
+    - name: format markdown
+      run: mdformat {staged_files}
+      glob: "*.md"
+      stage_fixed: true
+
+    - name: scan for secrets
+      run: detect-secrets-hook --baseline .secrets.baseline

data/lib/githuh/cli/commands/base.rb

@@ -34,19 +34,18 @@ module Githuh
                  per_page: DEFAULT_PAGE_SIZE,
                  verbose: false,
                  info: true)
-
           self.context  = Githuh
           self.verbose  = verbose
           self.info     = info
           self.token    = api_token || determine_github_token
-          self.per_page = per_page.to_i || DEFAULT_PAGE_SIZE
+          self.per_page = per_page.to_i
 
-          if info
-            begin
-              print_userinfo
-            rescue StandardError
-              nil
-            end
+          return unless info
+
+          begin
+            print_userinfo
+          rescue StandardError
+            nil
           end
         end
 
@@ -56,12 +55,12 @@ module Githuh
 
         protected
 
-        def puts(*args)
-          stdout.puts(*args)
+        def puts(*)
+          stdout.puts(*)
         end
 
-        def warn(*args)
-          stderr.puts(*args)
+        def warn(*)
+          stderr.puts(*)
         end
 
         def user_info
@@ -93,7 +92,7 @@ module Githuh
         end
 
         def determine_github_token
-          @github_token ||= (ENV['GITHUB_TOKEN'] || `git config --global --get user.token`.chomp)
+          @github_token ||= ENV['GITHUB_TOKEN'] || `git config --global --get user.token`.chomp
 
           return @github_token unless @github_token.empty?
 
@@ -108,15 +107,18 @@ module Githuh
         def print_userinfo
           duration = DateTime.now - DateTime.parse(user_info[:created_at].to_s)
           years    = (duration / 365).to_i
-          months   = ((duration - years * 365) / 30).to_i
-          days     = (duration - years * 365 - months * 30).to_i
+          months   = ((duration - (years * 365)) / 30).to_i
+          days     = (duration - (years * 365) - (months * 30)).to_i
 
           lines = []
-          lines << sprintf("  Github API Token: %s", h("#{token[0..9]}#{'.' * 20}#{token[-11..-1]}"))
+          lines << sprintf("  Github API Token: %s", h("#{token[0..9]}#{'.' * 20}#{token[-11..]}"))
           lines << sprintf("      Current User: %s", h(user_info.login))
           lines << sprintf("      Public Repos: %s", h(user_info.public_repos.to_s))
           lines << sprintf("         Followers: %s", h(user_info.followers.to_s))
-          lines << sprintf("        Member For: %s", h(sprintf("%d years, %d months, %d days", years, months, days)))
+          lines << sprintf(
+            "        Member For: %s",
+            h("%<years>d years, %<months>d months, %<days>d days" % { years:, months:, days: })
+          )
 
           self.box = TTY::Box.frame(*lines,
                                     padding: 0,