@felix-ayush/openhearth 2.1.0 → 2.2.0

package/README.md

@@ -37,9 +37,12 @@ openhearth audit USERNAME --month 2026-07
 # Full audit — PRs + issues + reviews
 openhearth audit Ayush7614 --month 2026-07
 
-# Quick report: repos likely hidden from your activity sidebar
+# Ranked report: repos likely hidden from your activity sidebar
 openhearth hidden Ayush7614 --month 2026-07
 
+# Check auth + Search API quota
+openhearth doctor
+
 # Export for spreadsheets or dashboards
 openhearth audit Ayush7614 --month 2026-07 --json report.json
 openhearth audit Ayush7614 --month 2026-07 --csv report.csv
@@ -50,7 +53,8 @@ openhearth audit Ayush7614 --month 2026-07 --csv report.csv
 | Command | Description |
 |---------|-------------|
 | `openhearth audit <user>` | Full PR + issue + review audit (default) |
-| `openhearth hidden <user>` | Hidden-repo report vs activity sidebar |
+| `openhearth hidden <user>` | Ranked likely-hidden repos vs activity sidebar |
+| `openhearth doctor` | Auth + GitHub rate-limit status |
 | `--month YYYY-MM` | Audit a calendar month |
 | `--from YYYY-MM-DD` | Custom range start |
 | `--to YYYY-MM-DD` | Custom range end |
@@ -59,19 +63,21 @@ openhearth audit Ayush7614 --month 2026-07 --csv report.csv
 | `--json [file]` | Export JSON (`stdout` if no file) |
 | `--csv [file]` | Export CSV |
 | `--quiet` | Minimal terminal output |
+| `-V, --version` | Print CLI version |
 
 ## What makes OpenHearth different
 
-- **Hidden repo detection** — estimates repos your profile sidebar truncates (~25 visible before “not shown”)
+- **Ranked hidden repos** — lower-activity repos past the ~25 sidebar cap, least activity first
+- **Clear rate-limit errors** — tells you to set `GITHUB_TOKEN` (or when quota resets)
+- **Doctor** — `openhearth doctor` checks auth and Search/Core API limits
+- **GitHub Action** — monthly/on-demand audits with JSON/CSV artifacts
 - **Full Search API pagination** — fetches all results, not just the first page
-- **Auto date-splitting** — when a month exceeds GitHub’s 1000-result search cap, splits the range automatically
-- **One-command full audit** — PRs, issues, and reviews together
-- **Insights** — merge rate, busiest day, top repositories
+- **Auto date-splitting** — when a month exceeds GitHub’s 1000-result search cap
 - **Export** — JSON and CSV for your own tooling
 
 ## Authentication (recommended)
 
-Without a token, the unauthenticated Search API is limited (~10 requests/minute).
+Without a token, the unauthenticated Search API is limited (~60 requests/hour).
 
 ```bash
 export GITHUB_TOKEN=ghp_your_token_here
@@ -80,6 +86,16 @@ openhearth audit USERNAME --month 2026-07
 
 A classic PAT with **public read** access is enough. The token is sent only to `api.github.com`.
 
+If you hit a limit, the CLI prints a fix hint — or run `openhearth doctor`.
+
+## GitHub Action
+
+This repository includes `.github/workflows/audit.yml`:
+
+- **workflow_dispatch** — pick username + month
+- **schedule** — 1st of each month (previous calendar month)
+- Uploads JSON/CSV artifacts from `audit` and `hidden`
+
 ## Example output
 
 ```
@@ -87,18 +103,17 @@ A classic PAT with **public read** access is enough. The token is sent only to `
 
   Summary · @Ayush7614 · 2026-07
 
-  Total contributions   412
-  Unique repositories   76
-  PR merge rate         84%
-  By kind               PRs 394 · Issues 12 · Reviews 6
+  Total contributions   494
+  Unique repositories   78
+  PR merge rate         51%
 
   ⚠ Hidden by activity feed
-  Feed shows ~25 repos; Search API found 76.
-  ~51 repositories may not appear on your profile sidebar.
+  Feed shows ~25 busiest repos; Search API found 78.
+  ~53 lower-activity repositories are likely truncated.
 
-  Top repositories
-  · KovaMD/Kova 38
-  · repowise-dev/repowise 33
+  Likely hidden repositories · least activity first
+  · small-org/side-project 1
+  · another/low-activity 2
   ...
 ```
 

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { readFileSync } from "node:fs";
 import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 
 // ../core/dist/github.js
 var ACTIVITY_FEED_REPO_CAP = 25;
@@ -10,7 +13,12 @@ function setAuthToken(token) {
   authToken = token.trim();
 }
 function getAuthToken() {
-  return authToken || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+  if (authToken)
+    return authToken;
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+  }
+  return "";
 }
 var lastRateLimit = {
   remaining: -1,
@@ -36,6 +44,22 @@ var GitHubApiError = class extends Error {
     this.status = status;
   }
 };
+function formatRateLimitHint() {
+  const hasToken = Boolean(getAuthToken());
+  const { remaining, limit, reset } = lastRateLimit;
+  const lines = [];
+  if (!hasToken) {
+    lines.push("Unauthenticated Search API is limited (~60 requests/hour).", "Set GITHUB_TOKEN or pass --token for ~5,000 requests/hour.", "Create a token: https://github.com/settings/tokens", "Then: export GITHUB_TOKEN=YOUR_TOKEN");
+  } else if (reset > 0) {
+    const resetAt = new Date(reset * 1e3).toISOString().replace(/\.\d{3}Z$/, "Z");
+    const quota = remaining >= 0 && limit > 0 ? `${remaining}/${limit} remaining` : "quota exhausted";
+    lines.push(`Authenticated rate limit: ${quota}. Resets at ${resetAt}.`);
+    lines.push("Wait for the reset, or retry with openhearth doctor to check status.");
+  } else {
+    lines.push("Set GITHUB_TOKEN or pass --token, then retry.");
+  }
+  return lines.map((l) => `  ${l}`).join("\n");
+}
 async function githubFetch(url) {
   const headers = {
     Accept: "application/vnd.github+json",
@@ -49,8 +73,10 @@ async function githubFetch(url) {
   updateRateLimit(res);
   if (res.status === 403 || res.status === 429) {
     const body = await res.json().catch(() => ({}));
-    const msg = body.message ?? "GitHub rate limit exceeded. Set GITHUB_TOKEN and try again.";
-    throw new GitHubApiError(msg, res.status);
+    const apiMsg = body.message ?? "GitHub rate limit exceeded.";
+    throw new GitHubApiError(`${apiMsg}
+
+${formatRateLimitHint()}`, res.status);
   }
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
@@ -59,6 +85,23 @@ async function githubFetch(url) {
   }
   return res;
 }
+async function checkRateLimit() {
+  const res = await githubFetch("https://api.github.com/rate_limit");
+  const data = await res.json();
+  return {
+    authenticated: Boolean(getAuthToken()),
+    core: {
+      remaining: data.resources.core.remaining,
+      limit: data.resources.core.limit,
+      reset: data.resources.core.reset
+    },
+    search: {
+      remaining: data.resources.search.remaining,
+      limit: data.resources.search.limit,
+      reset: data.resources.search.reset
+    }
+  };
+}
 async function searchIssuesPage(query, page) {
   const params = new URLSearchParams({
     q: query,
@@ -259,12 +302,22 @@ function buildInsights(pr, issue, review) {
   const uniqueRepos = repoTotals.size;
   const reposHiddenByFeed = Math.max(0, uniqueRepos - ACTIVITY_FEED_REPO_CAP);
   const reposVisibleOnFeed = Math.min(uniqueRepos, ACTIVITY_FEED_REPO_CAP);
-  const topRepos = [...repoTotals.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([repo, count]) => ({ repo, count }));
+  const ranked = [...repoTotals.entries()].sort((a, b) => {
+    if (b[1] !== a[1])
+      return b[1] - a[1];
+    return a[0].localeCompare(b[0]);
+  });
+  const topRepos = ranked.slice(0, 10).map(([repo, count]) => ({ repo, count }));
+  const likelyHiddenRepos = ranked.slice(ACTIVITY_FEED_REPO_CAP).map(([repo, count]) => ({ repo, count })).sort((a, b) => {
+    if (a.count !== b.count)
+      return a.count - b.count;
+    return a.repo.localeCompare(b.repo);
+  });
   const merged = pr.items.filter((i) => i.state === "merged").length;
   const mergeRate = pr.total > 0 ? Math.round(merged / pr.total * 100) : 0;
   let feedTruncationNote = "Activity feed likely shows all repos for this range.";
   if (reposHiddenByFeed > 0) {
-    feedTruncationNote = `GitHub's activity sidebar typically lists ~${ACTIVITY_FEED_REPO_CAP} repos before "N repositories not shown". Search API found ${uniqueRepos} repos \u2014 about ${reposHiddenByFeed} may be hidden on your profile feed.`;
+    feedTruncationNote = `GitHub's activity sidebar typically lists ~${ACTIVITY_FEED_REPO_CAP} busiest repos before "N repositories not shown". Search API found ${uniqueRepos} repos \u2014 about ${reposHiddenByFeed} lower-activity repos are likely hidden. Listed below as \u201Clikely hidden\u201D (least activity first).`;
   }
   return {
     totalContributions: pr.total + issue.total + review.total,
@@ -273,6 +326,7 @@ function buildInsights(pr, issue, review) {
     reposHiddenByFeed,
     feedTruncationNote,
     topRepos,
+    likelyHiddenRepos,
     busiestDay: busiestDay(allItems),
     mergeRate,
     byKind: { pr: pr.total, issue: issue.total, review: review.total }
@@ -395,22 +449,37 @@ function printInsights(insights, rangeLabel2) {
     console.log(amber("  \u26A0 Hidden by activity feed"));
     console.log(
       dim(
-        `  Feed shows ~${insights.reposVisibleOnFeed} repos; Search API found ${insights.uniqueRepos}.`
+        `  Feed shows ~${insights.reposVisibleOnFeed} busiest repos; Search API found ${insights.uniqueRepos}.`
       )
     );
     console.log(
-      dim(`  ~${insights.reposHiddenByFeed} repositories may not appear on your profile sidebar.`)
+      dim(`  ~${insights.reposHiddenByFeed} lower-activity repositories are likely truncated.`)
     );
     console.log("");
   }
   if (insights.topRepos.length > 0) {
-    console.log(bold("  Top repositories"));
+    console.log(bold("  Top repositories") + dim(" \xB7 likely visible on feed"));
     for (const { repo, count } of insights.topRepos.slice(0, 8)) {
       console.log(`  ${dim("\xB7")} ${repo} ${dim(String(count))}`);
     }
     console.log("");
   }
 }
+function printLikelyHidden(insights, limit = 20) {
+  if (insights.likelyHiddenRepos.length === 0) return;
+  console.log(
+    bold("  Likely hidden repositories") + dim(` \xB7 ${insights.likelyHiddenRepos.length} past the ~${insights.reposVisibleOnFeed} sidebar cap`)
+  );
+  console.log(dim("  Ranked least activity first (most likely truncated)."));
+  console.log("");
+  for (const { repo, count } of insights.likelyHiddenRepos.slice(0, limit)) {
+    console.log(`  ${dim("\xB7")} ${repo} ${dim(String(count))}`);
+  }
+  if (insights.likelyHiddenRepos.length > limit) {
+    console.log(dim(`  \u2026 and ${insights.likelyHiddenRepos.length - limit} more`));
+  }
+  console.log("");
+}
 function printAuditSection(title, result) {
   console.log(bold(`  ${title}`) + dim(` \xB7 ${result.total} across ${result.repos.length} repos`));
   if (result.repos.length === 0) {
@@ -433,6 +502,7 @@ function printAuditSection(title, result) {
 }
 function printFullReport(result, rangeLabel2) {
   printInsights(result.insights, `@${result.username} \xB7 ${rangeLabel2}`);
+  printLikelyHidden(result.insights, 12);
   printAuditSection("Pull requests", result.pullRequests);
   printAuditSection("Issues", result.issues);
   printAuditSection("Reviews", result.reviews);
@@ -440,15 +510,58 @@ function printFullReport(result, rangeLabel2) {
   console.log("");
 }
 function printError(message) {
-  console.error(red(`
-  Error: ${message}
-`));
+  const lines = message.split("\n");
+  console.error("");
+  console.error(red(`  Error: ${lines[0]}`));
+  for (const line of lines.slice(1)) {
+    console.error(line.length ? dim(`  ${line}`) : "");
+  }
+  console.error("");
 }
 function printProgress(message) {
   console.error(dim(`  ${message}`));
 }
+function formatReset(reset) {
+  if (!reset) return "unknown";
+  return new Date(reset * 1e3).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function printDoctor(report) {
+  printBanner();
+  console.log(bold("  Doctor") + dim(" \xB7 environment check"));
+  console.log("");
+  console.log(`  CLI version           ${report.version}`);
+  console.log(`  Node.js               ${report.node}`);
+  console.log(
+    `  Auth                  ${report.authenticated ? green(`yes (${report.tokenSource})`) : amber("no \u2014 unauthenticated")}`
+  );
+  console.log("");
+  console.log(bold("  Rate limits"));
+  console.log(
+    `  Core API              ${report.core.remaining}/${report.core.limit}  reset ${formatReset(report.core.reset)}`
+  );
+  console.log(
+    `  Search API            ${report.search.remaining}/${report.search.limit}  reset ${formatReset(report.search.reset)}`
+  );
+  console.log("");
+  if (!report.authenticated) {
+    console.log(amber("  Tip: export GITHUB_TOKEN=\u2026 before running audits."));
+    console.log(dim("  https://github.com/settings/tokens"));
+    console.log("");
+  }
+}
 
 // src/cli.ts
+function cliVersion() {
+  const injected = true ? "2.2.0" : "";
+  if (injected) return injected;
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
 function usage() {
   return `
 ${APP_NAME} \u2014 audit GitHub contributions the activity feed hides
@@ -456,10 +569,13 @@ ${APP_NAME} \u2014 audit GitHub contributions the activity feed hides
 Usage:
   openhearth audit <username> [options]
   openhearth hidden <username> [options]
+  openhearth doctor
+  openhearth --version
 
 Commands:
   audit     Full PR + issue + review audit (default)
-  hidden    Quick report: repos hidden from the activity sidebar
+  hidden    Hidden-repo report vs activity sidebar (ranked)
+  doctor    Check auth + GitHub rate-limit status
 
 Options:
   --month YYYY-MM     Audit a calendar month (e.g. 2026-07)
@@ -470,16 +586,18 @@ Options:
   --json [file]       Export JSON (stdout if no file)
   --csv [file]        Export CSV (stdout if no file)
   --quiet             Minimal output
+  -V, --version       Print CLI version
   -h, --help          Show help
 
 Examples:
   npx @felix-ayush/openhearth audit Ayush7614 --month 2026-07
   npx @felix-ayush/openhearth hidden Ayush7614 --month 2026-07
+  npx @felix-ayush/openhearth doctor
   npx @felix-ayush/openhearth audit torvalds --from 2026-01-01 --to 2026-01-31 --json report.json
 
 Unique features:
   \xB7 Finds ALL repos via Search API (not truncated like github.com activity)
-  \xB7 Reports how many repos the profile sidebar likely hides
+  \xB7 Ranks likely-hidden repos (lowest activity past the ~25 sidebar cap)
   \xB7 Auto-splits date ranges past GitHub's 1000-result search cap
   \xB7 Full audit: PRs + issues + reviews in one run
 `;
@@ -491,7 +609,9 @@ function parseArgs(argv) {
     kind: "all",
     quiet: false,
     hidden: false,
-    help: false
+    help: false,
+    version: false,
+    doctor: false
   };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
@@ -500,6 +620,10 @@ function parseArgs(argv) {
       opts.help = true;
       continue;
     }
+    if (arg === "-V" || arg === "--version") {
+      opts.version = true;
+      continue;
+    }
     if (arg === "--quiet") {
       opts.quiet = true;
       continue;
@@ -536,10 +660,11 @@ function parseArgs(argv) {
       positional.push(arg);
     }
   }
-  if (positional[0] === "audit" || positional[0] === "hidden") {
+  if (positional[0] === "audit" || positional[0] === "hidden" || positional[0] === "doctor") {
     opts.command = positional[0];
     opts.username = (positional[1] ?? "").replace(/^@/, "");
     if (opts.command === "hidden") opts.hidden = true;
+    if (opts.command === "doctor") opts.doctor = true;
   } else {
     opts.username = (positional[0] ?? "").replace(/^@/, "");
   }
@@ -569,13 +694,46 @@ function writeOutput(content, path) {
   writeFileSync(path, content, "utf8");
   console.error(`  Wrote ${path}`);
 }
+function tokenSourceLabel() {
+  if (process.env.GITHUB_TOKEN) return "GITHUB_TOKEN";
+  if (process.env.GH_TOKEN) return "GH_TOKEN";
+  return "--token";
+}
+async function runDoctor() {
+  const status = await checkRateLimit();
+  printDoctor({
+    version: cliVersion(),
+    node: process.version,
+    authenticated: status.authenticated,
+    tokenSource: status.authenticated ? tokenSourceLabel() : "none",
+    core: status.core,
+    search: status.search
+  });
+}
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
-  if (opts.help || !opts.username) {
+  if (opts.version) {
+    console.log(cliVersion());
+    process.exit(0);
+  }
+  if (opts.help) {
     console.log(usage());
-    process.exit(opts.help ? 0 : 1);
+    process.exit(0);
   }
   if (opts.token) setAuthToken(opts.token);
+  if (opts.doctor || opts.command === "doctor") {
+    try {
+      await runDoctor();
+    } catch (err) {
+      printError(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+    return;
+  }
+  if (!opts.username) {
+    console.log(usage());
+    process.exit(1);
+  }
   const range = resolveRange(opts);
   const label = rangeLabel(range, opts.month);
   const onProgress = opts.quiet ? void 0 : printProgress;
@@ -585,10 +743,12 @@ async function main() {
       const full = await runFullAudit(opts.username, range, runAudit, onProgress);
       if (!opts.quiet) {
         printInsights(full.insights, `@${opts.username} \xB7 ${label}`);
+        printLikelyHidden(full.insights);
         console.log(`  ${full.insights.feedTruncationNote}
 `);
       }
       if (opts.json) writeOutput(fullAuditToJson(full), opts.json);
+      if (opts.csv) writeOutput(fullAuditToCsv(full), opts.csv);
       return;
     }
     if (opts.kind === "all") {
@@ -611,6 +771,9 @@ async function main() {
     }
   } catch (err) {
     printError(err instanceof Error ? err.message : String(err));
+    if (!getAuthToken()) {
+      printProgress("Hint: run `openhearth doctor` after setting GITHUB_TOKEN.");
+    }
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felix-ayush/openhearth",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "CLI to audit every GitHub PR, issue, and review — find repos hidden from your activity feed (\"N repositories not shown\")",
   "type": "module",
   "bin": {
@@ -54,7 +54,7 @@
     "node": ">=20"
   },
   "devDependencies": {
-    "@felix-ayush/openhearth-core": "2.0.1",
+    "@felix-ayush/openhearth-core": "*",
     "@types/node": "^22.13.10",
     "esbuild": "^0.25.0",
     "typescript": "^5.8.2"