githuh 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e93141a03f0e5928c713b604064e96959c05e46da042a8122fd354169f6c4e
-  data.tar.gz: a7e2a02d760f6a1e886f3fdd2086387e4e46b33404fd3c4158a929698867a40b
+  metadata.gz: 5be0fa7f06e1d9ed6a7b203eb14841bc8b1db665c83fe84cf4822719c4acea37
+  data.tar.gz: '06938db523d0837c4de403f2b3720cb624576dacaa905a2e416c6423a239f0a5'
 SHA512:
-  metadata.gz: '0816ce0ad4649b24bb3f339bd953e11ca532b0e17858d96eedf6a783b41f47ff9e0279fea5ff35f37e2542d5e96ec464e74136fe03d730303956ce2b8d120e93'
-  data.tar.gz: faec900a0a5f38501bd2929ced73cf4840dc86a07fcaa5318ff98e59e5e69460c66a6b32139af648f72f5b5a62bb39a5f2840e3735ea7b01b3413878a615d7a8
+  metadata.gz: 66e5a49df88c46b9a17c91bae2280281eb046e32768b17666dedd07d770b32a7673bd50da23474977142810786080a649eacda7dc3cba27826170d16a321de46
+  data.tar.gz: '07319b21a6dd6c2e3118d46aa4c77db37ed9b6e9be75572427de3b896bde6b646ab3aff4fe22c191a4c7e5be461f7df9583330d2bdb78c18cc92c64e73bc228f'

data/.github/workflows/ruby.yml

@@ -8,7 +8,5 @@ jobs:
     steps:
     - uses: actions/checkout@v6
     - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: '4.0' # Not needed with a .ruby-version, .tool-versions or mise.toml
     - run: bundle install -j 4
     - run: bundle exec rspec --format documentation

data/.gitignore

@@ -21,7 +21,6 @@ pkg
 
 ## PROJECT::SPECIFIC
 .yardoc
-.ruby-version
 *.csv
 .envrc.local
 .env

data/.ruby-version

@@ -0,0 +1 @@
+4.0.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    githuh (0.4.0)
+    githuh (0.4.1)
       activesupport
       colored2 (~> 3)
       csv
@@ -246,7 +246,7 @@ CHECKSUMS
   faraday-retry (2.4.0) sha256=7b79c48fb7e56526faf247b12d94a680071ff40c9fda7cf1ec1549439ad11ebe
   ffi (1.17.4) sha256=bcd1642e06f0d16fc9e09ac6d49c3a7298b9789bcb58127302f934e437d60acf
   ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
-  githuh (0.4.0)
+  githuh (0.4.1)
   hashie (5.1.0) sha256=c266471896f323c446ea8207f8ffac985d2718df0a0ba98651a3057096ca3870
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   json (2.19.4) sha256=670a7d333fb3b18ca5b29cb255eb7bef099e40d88c02c80bd42a3f30fe5239ac

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

@@ -26,7 +26,7 @@ end
 task build: :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb exe/*.rb - README.adoc LICENSE.txt WARRANTY.md CHANGELOG.md]
+  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

data/lib/githuh/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Githuh
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: githuh
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -178,12 +178,13 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- ".ruby-version"
 - ".secrets.baseline"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.adoc
+- README.md
 - Rakefile
 - WARRANTY.md
 - codecov.yml

data/README.adoc

@@ -1,181 +0,0 @@
-:doctype: book
-:toc:
-:toclevels: 4
-:sectnums:
-image:https://github.com/kigster/githuh/workflows/Ruby/badge.svg[Ruby,link=https://github.com/kigster/githuh/actions?query=workflow%3ARuby] 
-image:docs/img/badge.svg[Coverage]
-
-= Githuh -- GitHub API client
-
-As in... *git? huh?*.
-
-Github API client wrapper on top of Octokit, that provides extensible command pattern for wrapping Github functionality.
-
-At the moment two features are implemented:
-
-* Generating a list of org's (or personal) repositories and rending in either markdown or JSON
-* Printing info of the logged in user.
-
-== Using `githuh`
-
-Add your Github Token to the global config:
-
-[source,bash]
-----
-git config --global --set user.token <token>
-----
-
-After that:
-
-[source,bash]
-----
-❯ be exe/githuh -h
-
-Githuh CLI 0.2.1 — API client for Github.com.
-© 2020 Konstantin Gredeskoul, All rights reserved.  MIT License.
-
-Commands:
-  githuh issue   [SUBCOMMAND]
-  githuh repo    [SUBCOMMAND]
-  githuh user    [SUBCOMMAND]
-  githuh version                   # Print version, no subcommands
-----
-
-Githuh is invoked by using one of its commands and sub-commands.
-
-
-=== `issue export`
-
-Use this command to export all issues for a given repo into either a raw JSON format (using `--format=json`) or into a https://www.pivotaltracker.com/help/articles/csv_import_export[Pivotal Tracker-compatible CSV format] (the default output format).
-
-[source,bash]
-----
-❯ be exe/githuh issue export -h
-
-Githuh CLI 0.2.1 — API client for Github.com.
-© 2020 Konstantin Gredeskoul, All rights reserved.  MIT License.
-
-Command:
-  githuh issue export
-
-Usage:
-  githuh issue export REPO
-
-Description:
-  Export Repo issues into a CSV or JSON format
-  Default output file is <username>.<repo>.issues.<format>
-
-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 a 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 Mappings
-
-The export suppots a configurable mapping of Github labels to Pivotal Tracker points. To use this feature, create a YAML file similar to the xref:config/label-mapping.yml[config/label-mapping.yml] provided:
-
-[source,yaml]
-----
----
-label-to-estimates:
-  Large: 5
-  Medium: 3
-  Small: 1
-----
-
-Then add `--mapping=<filename>` argument to the export command.
-
-==== Example
-
-Eg, to export all issues of this repo into Pivotal Tracker compatibel CSV:
-
-[source,bash]
-----
-# export into Pivotal Tracker CSV format
-githuh issue export kigster/githuh -v -i --api-token=XXXX
-----
-
-You should see an output similar to the following:
-
-image::docs/img/githuh-issue-export.png[issue export,width=60%,border=1]
-
-
-=== `repo list`
-
-==== Motivation
-
-This functionality was born out of the need to generate a brief but comprehensive, well-formatted list of prior inventions for a typical employment contract.
-
-NOTE: nothing in this library constitutes a legal advice. Use it at your own risk. For more information, please see xref:WARANTY.adoc[WARRANTY].
-
-Please watch the following Ascii Screen cast to see this command in action:
-
-image::https://asciinema.org/a/CW8NbYfu9RsifQJVU6tKRtRkU.svg[asciicast,link=https://asciinema.org/a/CW8NbYfu9RsifQJVU6tKRtRkU]
-
-==== Usage
-
-[source,bash]
-----
-❯ githuh repo list --help
-
-Githuh CLI 0.1.2 — API client for Github.com.
-© 2020 Konstantin Gredeskoul, All rights reserved.  MIT License.
-
-Usage:
-  githuh repo list
-
-Description:
-  List owned repositories and render the output in markdown or JSON
-  Default output file is <username>.repositories.<format>
-
-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 a 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
-  --help, -h          # Print this help
-----
-
-==== Example
-
-For instance, to generate a markdown list of all of your *public* repos that are also *not forks*, run the following:
-
-[source,bash]
-----
-$ githuh repo list --format=markdown --no-private --forks=exclude --file=repos.md
-----
-
-=== `user info`
-
-This command prints the info about currently authenticated user.
-
-[source,bash]
-----
-❯ githuh user info
-{
-                  :login => "kigster",
-                    :url => "https://api.github.com/users/kigster",
-               :html_url => "https://github.com/kigster",
-               ..............
-----
-
-== Contributing
-
-Please submit a pull request at https://github.com/kigster/githuh/pulls
-
-== License
-
-&copy; 2020 Konstantin Gredeskoul, link:LICENSE[MIT License]