npm package: @mightbeandrew/devcard
Description: Generate a beautiful developer trading card from your GitHub profile
Author: mightbeandrew
Latest version: 1.1.0

# devcard

> Generate a beautiful developer trading card from any GitHub profile — one command, zero setup.

[![npm version](https://badge.fury.io/js/%40mightbeandrew%2Fdevcard.svg)](https://www.npmjs.com/package/@mightbeandrew/devcard)
[![CI](https://github.com/Andrew-most-likely/devcard/actions/workflows/ci.yml/badge.svg)](https://github.com/Andrew-most-likely/devcard/actions)
[![npm downloads](https://img.shields.io/npm/dm/%40mightbeandrew%2Fdevcard)](https://www.npmjs.com/package/@mightbeandrew/devcard)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Quick Start

```bash
npx @mightbeandrew/devcard YOUR_GITHUB_USERNAME
```

That's it. No install, no config. A PNG is saved to your current directory.

## Example

```bash
npx @mightbeandrew/devcard torvalds
```

Generates `devcard-torvalds.png` — a full trading card with stats, top repos, and languages.

## Features

- **Trading card aesthetic** — HP, ATK, DEF, SPD, LVL stats mapped from real GitHub data
- **Rarity system** — Common → Uncommon → Rare → Ultra Rare → Secret Rare → Legendary
- **Auto-themed** — card color scheme matches your dominant language (JS = Electric, Python = Fire, etc.)
- **Terminal preview** — see a rich terminal preview before the PNG saves
- **Zero config** — works with any public GitHub profile, no auth required
- **Fast** — 4 API calls, 1-hour local cache

## Themes

| Theme | Auto-detected for |
|-------|------------------|
| `electric` | JavaScript, TypeScript |
| `fire` | Python, Ruby |
| `water` | Go, Kotlin, Swift, Java |
| `earth` | C, C++, Rust, Assembly |
| `psychic` | Haskell, Scala, Clojure, Elixir |
| `dark` | Default / C#, PHP, Shell |
| `light` | Light mode |
| `holo` | Holographic (force with `--theme holo`) |

## Options

```
npx @mightbeandrew/devcard <username> [options]

Options:
  -o, --output <path>    Output file path (default: devcard-<username>.png)
  -t, --theme <theme>    Force a theme (auto|dark|light|holo|fire|water|electric|psychic|earth)
  --token <token>        GitHub token for higher rate limits (or set GITHUB_TOKEN)
  --no-preview           Skip terminal preview
  --open                 Auto-open the PNG after saving
  --no-cache             Bypass the 1-hour local cache
  --copy                 Copy file path to clipboard
  -v, --version          Show version
  -h, --help             Show help
```

## Stat Mapping

| Card Stat | GitHub Data | Formula |
|-----------|------------|---------|
| ❤ HP | Total stars | log scale (max 50k) |
| ⚔ ATK | Total commits (approx) | log scale (max 100k) |
| 🛡 DEF | Followers | log scale (max 100k) |
| 📅 SPD | Account age | linear (max 15 years) |
| 📦 LVL | Public repos | log scale (max 1000) |

## Rarity Tiers

| Tier | Criteria |
|------|---------|
| COMMON | < 100 followers & < 50 stars |
| UNCOMMON | < 1k followers & < 500 stars |
| RARE | Default for active developers |
| ULTRA RARE ✦ | > 10k followers or > 5k stars |
| SECRET RARE ✦✦ | > 100k followers or > 50k stars |
| LEGENDARY ✦✦✦ | > 150k followers or > 100k stars |

## GitHub Profile README

After generating your card, add it to your profile README:

```markdown
![My DevCard](https://raw.githubusercontent.com/YOUR_USERNAME/YOUR_USERNAME/main/devcard-YOUR_USERNAME.png)
```

1. Run `npx devcard YOUR_USERNAME`
2. Commit `devcard-YOUR_USERNAME.png` to your profile repo
3. Add the markdown above to your `README.md`

## Rate Limits

Without a token: 60 requests/hour (1 card per run = 4 requests — plenty for normal use).

For higher limits: `npx devcard username --token YOUR_TOKEN` or set `GITHUB_TOKEN` env var.

Get a token (no scopes needed for public data): https://github.com/settings/tokens

## Share

Post your card with **#devcard** on Twitter/X or LinkedIn!

## License

MIT