feat: initial implementation of social preview generator

Node.js CLI tool that generates branded 1280x640 social preview images
for GitHub repositories using Satori and uploads via GitHub API.

Features:
- Stats sidebar (stars, forks, commits, contributors)
- Watermark background with full logo
- Calvin mascot avatar
- Repo name, description, topics as hashtags
- Full URL footer
- Single repo or batch org processing

Author: CalvinAllen

.github/workflows/build.yml

@@ -0,0 +1,51 @@
+name: Build
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - '__tests__/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - '.github/workflows/build.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - '__tests__/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - '.github/workflows/build.yml'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build

.gitignore

@@ -0,0 +1,38 @@
+# Dependency directory
+node_modules
+
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Coverage
+coverage
+*.lcov
+.nyc_output
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Build output
+dist
+
+# Environment
+.env
+.env.test
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea
+.vscode
+*.code-workspace
+
+# Test output
+__tests__/runner/*
+
+# Generated images (for local testing)
+*.generated.png
+test-preview.png

.node-version

@@ -0,0 +1 @@
+21.6.2

.prettierrc.json

@@ -0,0 +1,16 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": false,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "trailingComma": "none",
+  "bracketSpacing": true,
+  "bracketSameLine": true,
+  "arrowParens": "avoid",
+  "proseWrap": "always",
+  "htmlWhitespaceSensitivity": "css",
+  "endOfLine": "lf"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Calvin Allen / Coding With Calvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,93 @@
+# 🖼️ GH-SocialPreviewGenerator
+
+> ✨ Automagically generate stunning social preview images for all your GitHub repositories!
+
+Give every repo in your organization a polished, branded first impression. No more boring auto-generated previews!
+
+## 🎨 What It Does
+
+This CLI tool generates beautiful **1280x640** social preview images featuring:
+
+- 📊 **Live Stats** - Stars, forks, commits, and contributors
+- 📝 **Repo Info** - Name, description, and topics as hashtags
+- 🔗 **Full URL** - Easy to find your project
+- 🎭 **Custom Branding** - Your logo and mascot
+- 🌊 **Watermark Background** - Subtle branded backdrop
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Generate a preview (dry run)
+node dist/index.js generate CodingWithCalvin MyAwesomeRepo --dry-run
+
+# Generate and upload to GitHub
+node dist/index.js generate CodingWithCalvin MyAwesomeRepo --token ghp_xxx
+```
+
+## 📖 Usage
+
+### Single Repository
+
+```bash
+# Generate and upload
+node dist/index.js generate <owner> <repo> --token ghp_xxx
+
+# Dry run (save locally without uploading)
+node dist/index.js generate <owner> <repo> --dry-run
+
+# Specify output path
+node dist/index.js generate <owner> <repo> --dry-run --output preview.png
+```
+
+### All Repositories in Org 🏢
+
+```bash
+# Generate and upload all public repos
+node dist/index.js generate-all <owner> --token ghp_xxx
+
+# Dry run all
+node dist/index.js generate-all <owner> --dry-run --output-dir ./previews
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub token (alternative to `--token` flag) |
+
+### Token Permissions 🔐
+
+Your GitHub token needs the `admin:repo` scope to upload social previews.
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run all checks (format, lint, test, build)
+npm run all
+```
+
+## 🤖 Automated Updates
+
+A weekly workflow runs every **Sunday at midnight UTC** to refresh all social previews across the organization - keeping your stats up to date!
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+---
+
+Made with 💙 by [Coding With Calvin](https://codingwithcalvin.net)