Node.js GitHub Repo Stats CLI

Project roadmap

1. 01

   Set up the command line

   ~1h

   Create a project with npm init, install @octokit/rest and commander, and add a bin entry so it can run as ghstats. Define the command ghstats OWNER/REPO with options --compare OTHER/REPO, --json and --no-cache. Read the token from the GITHUB_TOKEN environment variable (never from the command line), and explain how to create a fine-grained token with read-only access. Done when: ghstats --help shows the usage.

2. 02

   Fetch the repository data

   ~2h

   With Octokit, fetch the repository (stars, forks, open issues, license, default branch and dates), its languages, the latest release, the top contributors, and weekly commit activity from the statistics endpoint (which can return 202 while GitHub computes it, so retry a few times). Validate the OWNER/REPO format, and handle 404 (repository not found) and 401 (bad token) with clear messages. Done when: the tool fetches all the data for a real repository.

3. 03

   Format the output

   ~1.5h

   Print a summary with sections: overview (description, stars, forks, open issues and license), languages as percentages with small bars, the latest release with its date, the top 5 contributors, and a sparkline of weekly commits. Use a small color library and turn colors off when the output isn't a terminal. With --json, print all the data as JSON. Done when: the summary is easy to read for several real repositories.

4. 04

   Compare two repositories

   ~1h

   With --compare, fetch both repositories at the same time (with Promise.all) and print a side-by-side table of the main numbers, highlighting the higher value in each row. Done when: comparing two repositories shows an aligned table.

5. 05

   Cache responses

   ~1.5h

   Cache API responses on disk (in the user's cache folder) keyed by URL, keeping the ETag and sending If-None-Match next time; a 304 answer means the cached data is still valid and doesn't count against the rate limit. Skip the cache with --no-cache. Show the remaining rate limit at the end, and wait or explain clearly when it's used up. Done when: a second run is faster and uses almost no rate limit.

6. 06

   Test it

   ~1.5h

   Write tests with Node's test runner (or Vitest) and a mocked Octokit (or nock): formatting with saved responses, the 202 retry for statistics, 404 and 401 errors, the comparison table, and the cache with ETags. Done when: the tests pass without network access.

Resources

• DocsOctokit REST.js
• Docscommander.js
• DocsGitHub REST API: repositories
• DocsGitHub REST API: repository statistics
• DocsGitHub REST API: best practices (conditional requests)