@felix-ayush/openhearth 2.0.0 → 2.2.0

package/README.md

@@ -0,0 +1,132 @@
+# OpenHearth
+
+**Find every GitHub contribution your profile activity feed hides.**
+
+OpenHearth is a CLI that audits pull requests, issues, and reviews via the GitHub Search API — then reports what GitHub’s truncated activity sidebar doesn’t show (“51 repositories not shown”).
+
+Built for heavy open-source contributors in the AI era, when monthly PR counts can hit hundreds across dozens of repos.
+
+## The problem
+
+GitHub’s profile **Contribution activity** is not a complete ledger:
+
+- Repos are grouped and truncated (“**N repositories not shown**”)
+- The green graph counts commits, not PRs across repos
+- Search shows lists; it doesn’t audit or compare against the feed
+
+OpenHearth gives you the **full inventory** — grouped by repo, with merged / open / closed counts and export.
+
+## Install
+
+```bash
+npx @felix-ayush/openhearth audit USERNAME --month 2026-07
+```
+
+Or install globally:
+
+```bash
+npm install -g @felix-ayush/openhearth
+openhearth audit USERNAME --month 2026-07
+```
+
+**Requires Node.js 20+**
+
+## Quick start
+
+```bash
+# Full audit — PRs + issues + reviews
+openhearth audit Ayush7614 --month 2026-07
+
+# 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
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `openhearth audit <user>` | Full PR + issue + review audit (default) |
+| `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 |
+| `--kind pr\|issue\|review\|all` | Filter by contribution type |
+| `--token TOKEN` | GitHub PAT (or use `GITHUB_TOKEN` env) |
+| `--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
+
+- **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
+- **Export** — JSON and CSV for your own tooling
+
+## Authentication (recommended)
+
+Without a token, the unauthenticated Search API is limited (~60 requests/hour).
+
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+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
+
+```
+  OpenHearth · contribution audit
+
+  Summary · @Ayush7614 · 2026-07
+
+  Total contributions   494
+  Unique repositories   78
+  PR merge rate         51%
+
+  ⚠ Hidden by activity feed
+  Feed shows ~25 busiest repos; Search API found 78.
+  ~53 lower-activity repositories are likely truncated.
+
+  Likely hidden repositories · least activity first
+  · small-org/side-project 1
+  · another/low-activity 2
+  ...
+```
+
+## Links
+
+- **Website & docs:** [ayush7614.github.io/OpenHearth](https://ayush7614.github.io/OpenHearth/)
+- **Source:** [github.com/Ayush7614/OpenHearth](https://github.com/Ayush7614/OpenHearth)
+- **Issues:** [github.com/Ayush7614/OpenHearth/issues](https://github.com/Ayush7614/OpenHearth/issues)
+
+## Author
+
+**Ayush Kumar** — [@Ayush7614](https://github.com/Ayush7614)
+
+## License
+
+MIT

package/dist/cli.js

@@ -1,18 +1,581 @@
 #!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync } from "node:fs";
 import { writeFileSync } from "node:fs";
-import { APP_NAME, auditToCsv, auditToJson, fullAuditToCsv, fullAuditToJson, parseMonth, runAudit, runFullAudit, setAuthToken, } from "@felix-ayush/openhearth-core";
-import { printAuditSection, printBanner, printError, printFullReport, printInsights, printProgress, } from "./format.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// ../core/dist/github.js
+var ACTIVITY_FEED_REPO_CAP = 25;
+var authToken = "";
+function setAuthToken(token) {
+  authToken = token.trim();
+}
+function getAuthToken() {
+  if (authToken)
+    return authToken;
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+  }
+  return "";
+}
+var lastRateLimit = {
+  remaining: -1,
+  limit: -1,
+  reset: 0
+};
+function updateRateLimit(res) {
+  const remaining = res.headers.get("X-RateLimit-Remaining");
+  const limit = res.headers.get("X-RateLimit-Limit");
+  const reset = res.headers.get("X-RateLimit-Reset");
+  if (remaining != null)
+    lastRateLimit.remaining = Number(remaining);
+  if (limit != null)
+    lastRateLimit.limit = Number(limit);
+  if (reset != null)
+    lastRateLimit.reset = Number(reset);
+}
+var GitHubApiError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "GitHubApiError";
+    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",
+    "X-GitHub-Api-Version": "2022-11-28"
+  };
+  const token = getAuthToken();
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  const res = await fetch(url, { headers });
+  updateRateLimit(res);
+  if (res.status === 403 || res.status === 429) {
+    const body = await res.json().catch(() => ({}));
+    const apiMsg = body.message ?? "GitHub rate limit exceeded.";
+    throw new GitHubApiError(`${apiMsg}
+
+${formatRateLimitHint()}`, res.status);
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    const msg = body.message ?? `GitHub API error (${res.status})`;
+    throw new GitHubApiError(msg, res.status);
+  }
+  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,
+    per_page: "100",
+    page: String(page),
+    sort: "created",
+    order: "desc"
+  });
+  const res = await githubFetch(`https://api.github.com/search/issues?${params.toString()}`);
+  return await res.json();
+}
+async function searchIssuesAll(query, onProgress) {
+  const first = await searchIssuesPage(query, 1);
+  const total = first.total_count;
+  const items = [...first.items];
+  onProgress?.(items.length, Math.min(total, 1e3));
+  if (total === 0) {
+    return { items, total_count: 0 };
+  }
+  const pagesNeeded = Math.min(Math.ceil(Math.min(total, 1e3) / 100), 10);
+  for (let page = 2; page <= pagesNeeded; page++) {
+    const next = await searchIssuesPage(query, page);
+    items.push(...next.items);
+    onProgress?.(items.length, Math.min(total, 1e3));
+  }
+  return { items, total_count: total };
+}
+function repoFullNameFromUrl(repositoryUrl) {
+  const parts = repositoryUrl.replace(/\/$/, "").split("/");
+  const name = parts.pop() ?? "";
+  const owner = parts.pop() ?? "";
+  return `${owner}/${name}`;
+}
+
+// ../core/dist/queries.js
+function pad(n) {
+  return String(n).padStart(2, "0");
+}
+function formatDate(d) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+function monthRange(year, month) {
+  const from = new Date(year, month - 1, 1);
+  const to = new Date(year, month, 0);
+  return { from: formatDate(from), to: formatDate(to) };
+}
+function parseMonth(value) {
+  const match = /^(\d{4})-(\d{2})$/.exec(value.trim());
+  if (!match) {
+    throw new Error(`Invalid month "${value}". Use YYYY-MM (e.g. 2026-07).`);
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  if (month < 1 || month > 12) {
+    throw new Error(`Invalid month "${value}". Month must be 01\u201312.`);
+  }
+  return monthRange(year, month);
+}
+function buildSearchQuery(username, kind, range) {
+  const created = `created:${range.from}..${range.to}`;
+  switch (kind) {
+    case "pr":
+      return `author:${username} is:pr ${created}`;
+    case "issue":
+      return `author:${username} is:issue ${created}`;
+    case "review":
+      return `reviewed-by:${username} is:pr ${created}`;
+  }
+}
+function splitRange(range) {
+  const start = /* @__PURE__ */ new Date(range.from + "T00:00:00");
+  const end = /* @__PURE__ */ new Date(range.to + "T00:00:00");
+  const midMs = start.getTime() + Math.floor((end.getTime() - start.getTime()) / 2);
+  const mid = new Date(midMs);
+  const midNext = new Date(mid);
+  midNext.setDate(midNext.getDate() + 1);
+  return [
+    { from: formatDate(start), to: formatDate(mid) },
+    { from: formatDate(midNext), to: formatDate(end) }
+  ];
+}
+function rangeDayCount(range) {
+  const start = /* @__PURE__ */ new Date(range.from + "T00:00:00");
+  const end = /* @__PURE__ */ new Date(range.to + "T00:00:00");
+  return Math.round((end.getTime() - start.getTime()) / 864e5) + 1;
+}
+
+// ../core/dist/aggregate.js
+function classifyState(item, kind) {
+  if (kind === "pr" || kind === "review") {
+    if (item.pull_request?.merged_at)
+      return "merged";
+    if (item.state === "open")
+      return "open";
+    return "closed";
+  }
+  return item.state === "open" ? "open" : "closed";
+}
+function toContribution(item, kind) {
+  return {
+    id: item.id,
+    number: item.number,
+    title: item.title,
+    url: item.html_url,
+    state: classifyState(item, kind),
+    createdAt: item.created_at,
+    closedAt: item.closed_at,
+    repo: repoFullNameFromUrl(item.repository_url)
+  };
+}
+function aggregateByRepo(items) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    let bucket = map.get(item.repo);
+    if (!bucket) {
+      bucket = { repo: item.repo, open: 0, merged: 0, closed: 0, items: [] };
+      map.set(item.repo, bucket);
+    }
+    bucket.items.push(item);
+    if (item.state === "open")
+      bucket.open++;
+    else if (item.state === "merged")
+      bucket.merged++;
+    else
+      bucket.closed++;
+  }
+  return [...map.values()].sort((a, b) => b.items.length - a.items.length);
+}
+async function fetchAllForRange(username, kind, range, onProgress) {
+  const query = buildSearchQuery(username, kind, range);
+  onProgress?.(`Searching: ${query}`);
+  const { items, total_count } = await searchIssuesAll(query, (fetched, capped) => {
+    onProgress?.(`Fetched ${fetched} / ${capped}`);
+  });
+  if (total_count <= 1e3) {
+    return items;
+  }
+  if (rangeDayCount(range) < 2) {
+    onProgress?.(`Warning: ${total_count} results in one day; only first 1000 returned for ${range.from}`);
+    return items;
+  }
+  const [left, right] = splitRange(range);
+  onProgress?.(`Over 1000 results (${total_count}). Splitting ${range.from}..${range.to}`);
+  const leftItems = await fetchAllForRange(username, kind, left, onProgress);
+  const rightItems = await fetchAllForRange(username, kind, right, onProgress);
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const item of [...leftItems, ...rightItems]) {
+    if (seen.has(item.id))
+      continue;
+    seen.add(item.id);
+    merged.push(item);
+  }
+  return merged;
+}
+async function runAudit(username, kind, range, onProgress) {
+  const raw = await fetchAllForRange(username, kind, range, onProgress);
+  const items = raw.map((i) => toContribution(i, kind));
+  items.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  const repos = aggregateByRepo(items);
+  return {
+    kind,
+    username,
+    range,
+    total: items.length,
+    repos,
+    items
+  };
+}
+
+// ../core/dist/insights.js
+function countByDay(items) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const day = item.createdAt.slice(0, 10);
+    map.set(day, (map.get(day) ?? 0) + 1);
+  }
+  return map;
+}
+function busiestDay(items) {
+  const map = countByDay(items);
+  let best = null;
+  let bestCount = 0;
+  for (const [day, count] of map) {
+    if (count > bestCount) {
+      best = day;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+function buildInsights(pr, issue, review) {
+  const allItems = [...pr.items, ...issue.items, ...review.items];
+  const repoTotals = /* @__PURE__ */ new Map();
+  for (const item of allItems) {
+    repoTotals.set(item.repo, (repoTotals.get(item.repo) ?? 0) + 1);
+  }
+  const uniqueRepos = repoTotals.size;
+  const reposHiddenByFeed = Math.max(0, uniqueRepos - ACTIVITY_FEED_REPO_CAP);
+  const reposVisibleOnFeed = Math.min(uniqueRepos, ACTIVITY_FEED_REPO_CAP);
+  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} 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,
+    uniqueRepos,
+    reposVisibleOnFeed,
+    reposHiddenByFeed,
+    feedTruncationNote,
+    topRepos,
+    likelyHiddenRepos,
+    busiestDay: busiestDay(allItems),
+    mergeRate,
+    byKind: { pr: pr.total, issue: issue.total, review: review.total }
+  };
+}
+async function runFullAudit(username, range, runAuditFn, onProgress) {
+  onProgress?.(`Auditing pull requests for @${username}\u2026`);
+  const pullRequests = await runAuditFn(username, "pr", range, onProgress);
+  onProgress?.(`Auditing issues for @${username}\u2026`);
+  const issues = await runAuditFn(username, "issue", range, onProgress);
+  onProgress?.(`Auditing reviews for @${username}\u2026`);
+  const reviews = await runAuditFn(username, "review", range, onProgress);
+  const insights = buildInsights(pullRequests, issues, reviews);
+  return {
+    username,
+    range,
+    pullRequests,
+    issues,
+    reviews,
+    insights
+  };
+}
+
+// ../core/dist/export.js
+function escapeCsv(value) {
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+function auditToJson(result) {
+  return JSON.stringify({
+    username: result.username,
+    kind: result.kind,
+    range: result.range,
+    total: result.total,
+    repoCount: result.repos.length,
+    repos: result.repos.map((r) => ({
+      repo: r.repo,
+      open: r.open,
+      merged: r.merged,
+      closed: r.closed,
+      count: r.items.length
+    })),
+    items: result.items
+  }, null, 2);
+}
+function fullAuditToJson(result) {
+  return JSON.stringify({
+    username: result.username,
+    range: result.range,
+    insights: result.insights,
+    pullRequests: {
+      total: result.pullRequests.total,
+      repos: result.pullRequests.repos.length
+    },
+    issues: { total: result.issues.total, repos: result.issues.repos.length },
+    reviews: { total: result.reviews.total, repos: result.reviews.repos.length },
+    pullRequestsItems: result.pullRequests.items,
+    issuesItems: result.issues.items,
+    reviewsItems: result.reviews.items
+  }, null, 2);
+}
+function auditToCsv(result) {
+  const header = ["repo", "number", "title", "state", "created_at", "closed_at", "url"];
+  const rows = result.items.map((item) => [
+    item.repo,
+    String(item.number),
+    item.title,
+    item.state,
+    item.createdAt,
+    item.closedAt ?? "",
+    item.url
+  ].map(escapeCsv).join(","));
+  return [header.join(","), ...rows].join("\n");
+}
+function fullAuditToCsv(result) {
+  const header = ["kind", "repo", "number", "title", "state", "created_at", "closed_at", "url"];
+  const rows = [];
+  for (const [kind, audit] of [
+    ["pr", result.pullRequests],
+    ["issue", result.issues],
+    ["review", result.reviews]
+  ]) {
+    for (const item of audit.items) {
+      rows.push([kind, item.repo, String(item.number), item.title, item.state, item.createdAt, item.closedAt ?? "", item.url].map(escapeCsv).join(","));
+    }
+  }
+  return [header.join(","), ...rows].join("\n");
+}
+
+// ../core/dist/index.js
+var APP_NAME = "OpenHearth";
+
+// src/format.ts
+var dim = (s) => `\x1B[2m${s}\x1B[0m`;
+var bold = (s) => `\x1B[1m${s}\x1B[0m`;
+var amber = (s) => `\x1B[33m${s}\x1B[0m`;
+var green = (s) => `\x1B[32m${s}\x1B[0m`;
+var red = (s) => `\x1B[31m${s}\x1B[0m`;
+function printBanner() {
+  console.log("");
+  console.log(bold("  OpenHearth") + dim(" \xB7 contribution audit"));
+  console.log("");
+}
+function printInsights(insights, rangeLabel2) {
+  console.log(bold("  Summary") + dim(` \xB7 ${rangeLabel2}`));
+  console.log("");
+  console.log(`  Total contributions   ${bold(String(insights.totalContributions))}`);
+  console.log(`  Unique repositories   ${bold(String(insights.uniqueRepos))}`);
+  console.log(`  PR merge rate         ${bold(`${insights.mergeRate}%`)}`);
+  console.log(
+    `  By kind               PRs ${insights.byKind.pr} \xB7 Issues ${insights.byKind.issue} \xB7 Reviews ${insights.byKind.review}`
+  );
+  if (insights.busiestDay) {
+    console.log(`  Busiest day           ${insights.busiestDay}`);
+  }
+  console.log("");
+  if (insights.reposHiddenByFeed > 0) {
+    console.log(amber("  \u26A0 Hidden by activity feed"));
+    console.log(
+      dim(
+        `  Feed shows ~${insights.reposVisibleOnFeed} busiest repos; Search API found ${insights.uniqueRepos}.`
+      )
+    );
+    console.log(
+      dim(`  ~${insights.reposHiddenByFeed} lower-activity repositories are likely truncated.`)
+    );
+    console.log("");
+  }
+  if (insights.topRepos.length > 0) {
+    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) {
+    console.log(dim("  (none)"));
+    console.log("");
+    return;
+  }
+  for (const repo of result.repos.slice(0, 6)) {
+    const parts = [
+      repo.merged ? green(`${repo.merged} merged`) : "",
+      repo.open ? `${repo.open} open` : "",
+      repo.closed ? dim(`${repo.closed} closed`) : ""
+    ].filter(Boolean);
+    console.log(`  ${dim("\u25B8")} ${repo.repo} ${dim(parts.join(" \xB7 "))}`);
+  }
+  if (result.repos.length > 6) {
+    console.log(dim(`  \u2026 and ${result.repos.length - 6} more repositories`));
+  }
+  console.log("");
+}
+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);
+  console.log(dim(`  ${result.insights.feedTruncationNote}`));
+  console.log("");
+}
+function printError(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} — audit GitHub contributions the activity feed hides
+  return `
+${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)
@@ -23,155 +586,195 @@ 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:
-  · Finds ALL repos via Search API (not truncated like github.com activity)
-  · Reports how many repos the profile sidebar likely hides
-  · Auto-splits date ranges past GitHub's 1000-result search cap
-  · Full audit: PRs + issues + reviews in one run
+  \xB7 Finds ALL repos via Search API (not truncated like github.com activity)
+  \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
 `;
 }
 function parseArgs(argv) {
-    const opts = {
-        command: "audit",
-        username: "",
-        kind: "all",
-        quiet: false,
-        hidden: false,
-        help: false,
-    };
-    const positional = [];
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "-h" || arg === "--help") {
-            opts.help = true;
-            continue;
-        }
-        if (arg === "--quiet") {
-            opts.quiet = true;
-            continue;
-        }
-        if (arg === "--month" && argv[i + 1]) {
-            opts.month = argv[++i];
-            continue;
-        }
-        if (arg === "--from" && argv[i + 1]) {
-            opts.from = argv[++i];
-            continue;
-        }
-        if (arg === "--to" && argv[i + 1]) {
-            opts.to = argv[++i];
-            continue;
-        }
-        if (arg === "--token" && argv[i + 1]) {
-            opts.token = argv[++i];
-            continue;
-        }
-        if (arg === "--kind" && argv[i + 1]) {
-            opts.kind = argv[++i];
-            continue;
-        }
-        if (arg === "--json") {
-            opts.json = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : "-";
-            continue;
-        }
-        if (arg === "--csv") {
-            opts.csv = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : "-";
-            continue;
-        }
-        if (!arg.startsWith("-")) {
-            positional.push(arg);
-        }
-    }
-    if (positional[0] === "audit" || positional[0] === "hidden") {
-        opts.command = positional[0];
-        opts.username = (positional[1] ?? "").replace(/^@/, "");
-        if (opts.command === "hidden")
-            opts.hidden = true;
-    }
-    else {
-        opts.username = (positional[0] ?? "").replace(/^@/, "");
-    }
-    return opts;
-}
-function resolveRange(opts) {
-    if (opts.month) {
-        return parseMonth(opts.month);
+  const opts = {
+    command: "audit",
+    username: "",
+    kind: "all",
+    quiet: false,
+    hidden: false,
+    help: false,
+    version: false,
+    doctor: false
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      opts.help = true;
+      continue;
     }
-    if (opts.from && opts.to) {
-        return { from: opts.from, to: opts.to };
+    if (arg === "-V" || arg === "--version") {
+      opts.version = true;
+      continue;
     }
-    const now = new Date();
-    const year = now.getFullYear();
-    const month = now.getMonth() + 1;
-    return parseMonth(`${year}-${String(month).padStart(2, "0")}`);
+    if (arg === "--quiet") {
+      opts.quiet = true;
+      continue;
+    }
+    if (arg === "--month" && argv[i + 1]) {
+      opts.month = argv[++i];
+      continue;
+    }
+    if (arg === "--from" && argv[i + 1]) {
+      opts.from = argv[++i];
+      continue;
+    }
+    if (arg === "--to" && argv[i + 1]) {
+      opts.to = argv[++i];
+      continue;
+    }
+    if (arg === "--token" && argv[i + 1]) {
+      opts.token = argv[++i];
+      continue;
+    }
+    if (arg === "--kind" && argv[i + 1]) {
+      opts.kind = argv[++i];
+      continue;
+    }
+    if (arg === "--json") {
+      opts.json = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : "-";
+      continue;
+    }
+    if (arg === "--csv") {
+      opts.csv = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : "-";
+      continue;
+    }
+    if (!arg.startsWith("-")) {
+      positional.push(arg);
+    }
+  }
+  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(/^@/, "");
+  }
+  return opts;
+}
+function resolveRange(opts) {
+  if (opts.month) {
+    return parseMonth(opts.month);
+  }
+  if (opts.from && opts.to) {
+    return { from: opts.from, to: opts.to };
+  }
+  const now = /* @__PURE__ */ new Date();
+  const year = now.getFullYear();
+  const month = now.getMonth() + 1;
+  return parseMonth(`${year}-${String(month).padStart(2, "0")}`);
 }
 function rangeLabel(range, month) {
-    if (month)
-        return month;
-    return `${range.from} → ${range.to}`;
+  if (month) return month;
+  return `${range.from} \u2192 ${range.to}`;
 }
 function writeOutput(content, path) {
-    if (!path || path === "-") {
-        console.log(content);
-        return;
-    }
-    writeFileSync(path, content, "utf8");
-    console.error(`  Wrote ${path}`);
+  if (!path || path === "-") {
+    console.log(content);
+    return;
+  }
+  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) {
-        console.log(usage());
-        process.exit(opts.help ? 0 : 1);
-    }
-    if (opts.token)
-        setAuthToken(opts.token);
-    const range = resolveRange(opts);
-    const label = rangeLabel(range, opts.month);
-    const onProgress = opts.quiet ? undefined : printProgress;
-    if (!opts.quiet)
-        printBanner();
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.version) {
+    console.log(cliVersion());
+    process.exit(0);
+  }
+  if (opts.help) {
+    console.log(usage());
+    process.exit(0);
+  }
+  if (opts.token) setAuthToken(opts.token);
+  if (opts.doctor || opts.command === "doctor") {
     try {
-        if (opts.hidden || opts.command === "hidden") {
-            const full = await runFullAudit(opts.username, range, runAudit, onProgress);
-            if (!opts.quiet) {
-                printInsights(full.insights, `@${opts.username} · ${label}`);
-                console.log(`  ${full.insights.feedTruncationNote}\n`);
-            }
-            if (opts.json)
-                writeOutput(fullAuditToJson(full), opts.json);
-            return;
-        }
-        if (opts.kind === "all") {
-            const full = await runFullAudit(opts.username, range, runAudit, onProgress);
-            if (opts.json)
-                writeOutput(fullAuditToJson(full), opts.json);
-            if (opts.csv)
-                writeOutput(fullAuditToCsv(full), opts.csv);
-            if (!opts.quiet && !opts.json && !opts.csv) {
-                printFullReport(full, label);
-            }
-            return;
-        }
-        const result = await runAudit(opts.username, opts.kind, range, onProgress);
-        if (opts.json)
-            writeOutput(auditToJson(result), opts.json);
-        if (opts.csv)
-            writeOutput(auditToCsv(result), opts.csv);
-        if (!opts.quiet && !opts.json && !opts.csv) {
-            printAuditSection(opts.kind === "pr" ? "Pull requests" : opts.kind === "issue" ? "Issues" : "Reviews", result);
-        }
-    }
-    catch (err) {
-        printError(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+      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;
+  if (!opts.quiet) printBanner();
+  try {
+    if (opts.hidden || opts.command === "hidden") {
+      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") {
+      const full = await runFullAudit(opts.username, range, runAudit, onProgress);
+      if (opts.json) writeOutput(fullAuditToJson(full), opts.json);
+      if (opts.csv) writeOutput(fullAuditToCsv(full), opts.csv);
+      if (!opts.quiet && !opts.json && !opts.csv) {
+        printFullReport(full, label);
+      }
+      return;
+    }
+    const result = await runAudit(opts.username, opts.kind, range, onProgress);
+    if (opts.json) writeOutput(auditToJson(result), opts.json);
+    if (opts.csv) writeOutput(auditToCsv(result), opts.csv);
+    if (!opts.quiet && !opts.json && !opts.csv) {
+      printAuditSection(
+        opts.kind === "pr" ? "Pull requests" : opts.kind === "issue" ? "Issues" : "Reviews",
+        result
+      );
+    }
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+    if (!getAuthToken()) {
+      printProgress("Hint: run `openhearth doctor` after setting GITHUB_TOKEN.");
     }
+    process.exit(1);
+  }
 }
 main();

package/package.json

@@ -1,31 +1,47 @@
 {
   "name": "@felix-ayush/openhearth",
-  "version": "2.0.0",
-  "description": "CLI to audit every GitHub PR, issue, and review — including what the activity feed hides",
+  "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": {
     "openhearth": "./dist/cli.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "build": "node build.mjs",
+    "dev": "node build.mjs && node dist/cli.js",
     "start": "node dist/cli.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
     "github",
+    "github-contributions",
     "contributions",
     "pull-requests",
+    "issues",
+    "code-review",
     "open-source",
+    "oss",
     "audit",
-    "cli"
+    "cli",
+    "developer-tools",
+    "activity-feed",
+    "contribution-graph",
+    "search-api",
+    "openhearth"
   ],
   "license": "MIT",
-  "author": "Ayush Kumar",
+  "author": {
+    "name": "Ayush Kumar",
+    "url": "https://github.com/Ayush7614"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Ayush7614/OpenHearth.git"
+    "url": "git+https://github.com/Ayush7614/OpenHearth.git",
+    "directory": "packages/cli"
   },
   "homepage": "https://ayush7614.github.io/OpenHearth/",
   "publishConfig": {
@@ -37,11 +53,10 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "@felix-ayush/openhearth-core": "2.0.0"
-  },
   "devDependencies": {
+    "@felix-ayush/openhearth-core": "*",
     "@types/node": "^22.13.10",
+    "esbuild": "^0.25.0",
     "typescript": "^5.8.2"
   }
 }