🎉 fame-handler: Life is too short to be humble!

Celebrate your GitHub fame — from your first star to full-blown celebrity. 🌟

---

Source: ProgrammerHumor.io

fame-handler is a read-only GitHub repository intelligence toolkit for maintainers. It turns repository metadata into an explainable fame score, milestones, growth trends, and practical maintenance signals.

• Typed ESM SDK for Node.js
• fame-handler command-line interface
• Public repositories work without credentials
• Private repositories and higher API limits work with an optional GitHub token
• Local history is opt-in for the SDK and never stores credentials

Requirements and installation

Node.js 22.12.0 or later is required.

npm install fame-handler

For a one-off CLI invocation:

npx fame-handler report owner/repository

CLI

report fetches the current snapshot, prints an insight report, and records one local snapshot per UTC day by default.

# Explicit repository
fame-handler report vercel/next.js

# Infer owner/repository from the current directory's origin remote
fame-handler report

# Machine-readable reports never contain ANSI formatting
fame-handler report vercel/next.js --format json
fame-handler report vercel/next.js --format markdown

# Disable local snapshot history for this invocation
fame-handler report vercel/next.js --no-history

# Store history in a project-specific location
fame-handler report vercel/next.js --history-file .fame-handler/history.json
fame-handler history vercel/next.js --days 30 --format markdown

Accepted repository values are owner/repository, HTTPS URLs, and SSH remote URLs. Without a positional repository, the CLI runs git remote get-url origin and parses the result.

Authentication and GitHub Enterprise

Public GitHub repositories need no token. For private repositories or higher API limits, pass a fine-grained token explicitly or set GITHUB_TOKEN:

GITHUB_TOKEN=github_pat_example fame-handler report owner/private-repository
fame-handler report owner/private-repository --token github_pat_example
fame-handler report owner/repository --api-url https://github.example/api/v3

Use a least-privilege, read-only token with access to the target repository. fame-handler never logs or persists tokens, and it performs no GitHub writes.

The CLI exits with 0 on success, 1 for operational failures, and 2 for invalid usage. Diagnostics go to stderr; JSON and Markdown reports remain clean on stdout.

SDK

import { createFameTracker } from 'fame-handler';

const tracker = createFameTracker({
  token: process.env.GITHUB_TOKEN,
});

const report = await tracker.report('owner/repository');

console.log(report.score.value, report.score.label);
console.log(report.snapshot.metrics.stars);
console.log(report.insights);

The SDK does not read environment variables and does not write files unless you explicitly call track with a HistoryStore:

import { FileHistoryStore, createFameTracker } from 'fame-handler';

const tracker = createFameTracker();
const history = new FileHistoryStore('./data/fame-history.json');
const report = await tracker.track({ owner: 'owner', repo: 'repository' }, history);

Public API highlights:

• FameTracker / createFameTracker — fetch snapshots, create reports, and optionally track history
• RepositorySnapshot — normalized GitHub metadata and metrics
• FameReport — snapshot, score, trends, milestones, next milestone, and insights
• calculateFameScore, calculateTrend, calculateMilestones, createFameReport — pure analysis helpers
• FileHistoryStore and createDefaultHistoryStore — JSON-backed history stores
• FameHandlerError — stable error codes for authentication, missing repositories, rate limits, network/API, storage, and input failures

Scoring and insights

The 0–100 fame score is deterministic and includes its components in every report:

Component	Maximum	Rule
Reach	40	Log-scaled stars, capped at 1,000
Network	20	Log-scaled forks, capped at 100
Activity	20	Most recent push: 7/30/90-day freshness tiers
Delivery	20	Most recent published release: 7/30/90-day freshness tiers

Score bands are Newcomer, Rising, Established, Notable, and Iconic. Historical comparisons use the oldest available snapshot in the preceding 90 days. Milestone notifications are emitted only when a prior snapshot shows that the threshold was newly crossed.

The standard GitHub request sequence is intentionally small and serial: repository metadata, languages, and latest release. A repository without a published release is valid and represented as null.

History and privacy

The CLI's default history file lives in the platform data directory and retains the latest 400 daily snapshots per repository. Writes are atomic. Use --history-file to control the file location or --no-history to avoid local persistence.

History contains repository metadata and counts only. It contains no tokens, telemetry, webhook subscriptions, or background polling state.

Migrating from 0.x

The original celebrateStar, howToHandleFame, showConfetti, fameScore, and trackGithubFame exports remain available for compatibility. They are deprecated and continue their console-oriented behavior. New applications should use FameTracker and the structured report types.

Version 1 is ESM-only and requires Node.js 22.12.0 or later.

Development

npm ci
npm run format:check
npm run lint
npm run typecheck
npm run test:coverage
npm run build
npm run package:check

See CONTRIBUTING.md for local development and RELEASING.md for maintainership release steps.

License

MIT © Lucas Ho