Merge pull request #4 from d3varaja/feat/v1-finalise

Rename CLI and update documentation for gh-wrapped-2025

Author: d3varaja

.github/copilot-instructions.md

@@ -7,15 +7,16 @@ This file gives targeted, actionable guidance for an AI coding agent working on
 **Why this matters:** the app is a CLI + image-exporter that fetches GitHub data, analyzes it, renders a terminal UI (Ink) and optionally exports images (Satori → Sharp/Resvg). Many behaviors are implemented by coordinating multiple files (data fetch → analysis → UI → export worker).
 
 **Quick facts**
-- **Runtime:** ESM + TypeScript (built to run under Bun; Node used for the export worker)
-- **Preferred runner:** `bun` (recommended in `README.md`) — use `bun install`, `bun run build`, `bun run dev`, `bun start`
+- **Runtime:** ESM + TypeScript (built with Bun; Node required for running due to Playwright)
+- **Preferred workflow:** `bun` for dev/build, `node` for running — use `bun install`, `bun run build`, `bun run dev`, then `npm start` or `node dist/index.js`
 - **Key dirs/files:** `src/index.tsx`, `src/ui.tsx`, `src/github.ts`, `src/github-graphql*.ts`, `src/analytics.ts`, `src/export.ts`, `src/export-worker.mjs`, `src/types.ts`, `src/fonts/`
 
 **Commands**
 - Install deps: `bun install` (or `npm install`)
 - Dev (hot reload with Bun): `bun run dev`
-- Build: `bun run build`
-- Run locally: `bun start` or `bunx github-wrapped-2025`
+- Build: `bun run build` (use Bun - faster)
+- Run built version: `npm start` or `node dist/index.js` (IMPORTANT: use Node, not Bun - Playwright compatibility)
+- Run without installing: `bunx gh-wrapped-2025` or `npx gh-wrapped-2025`
 
 **Important runtime notes**
 - Exports use a Node worker (`src/export-worker.mjs`) invoked via file-based IPC (temp JSON files). This is intentional to avoid Bun + WASM and Windows pipe issues — do not replace this with a naive child pipe without handling the Windows case.
@@ -46,7 +47,7 @@ This file gives targeted, actionable guidance for an AI coding agent working on
 - Run app locally (recommended):
   - `bun install`
   - `bun run build`
-  - `bun start`
+  - `npm start` (or `node dist/index.js` - use Node, NOT Bun)
 
 - Run export worker directly for debugging:
   - `node src/export-worker.mjs /path/to/input.json /path/to/output.json`
@@ -61,7 +62,8 @@ This file gives targeted, actionable guidance for an AI coding agent working on
 - `src/export.ts` + `src/export-worker.mjs` — the export orchestration and worker contract
 
 **Testing & verification guidance**
-- Use `bun run dev` for iterating UI changes (fast). Use `bun run build` then `bun start` to replicate production behavior.
+- Use `bun run dev` for iterating UI changes (fast). Use `bun run build` then `npm start` (or `node dist/index.js`) to replicate production behavior.
 - For export changes, run the worker directly with `node` and a synthetic `input.json` containing a minimal `WrappedStats` object to validate Satori → Sharp rendering.
+- **IMPORTANT:** Never test with `bun start` - Playwright has compatibility issues with Bun runtime. Always use Node for running the built version.
 
 If anything in this guidance is unclear or you want more detail for a specific area (e.g., GraphQL queries, export fonts, or how achievements are calculated), tell me which part and I will expand or update this file.

.gitignore

@@ -57,3 +57,7 @@ test-results/
 
 # Bun
 bun.lockb
+bunfig.toml
+
+# Claude Code
+.claude/

README.md

@@ -12,12 +12,12 @@ A CLI tool that analyzes your GitHub activity for 2025 and generates beautiful s
 
 ### Using Bun (Recommended - 100x faster)
 ```bash
-bunx github-wrapped-2025
+bunx gh-wrapped-2025
 ```
 
 ### Using npm
 ```bash
-npx github-wrapped-2025
+npx gh-wrapped-2025
 ```
 
 1. Enter your GitHub username
@@ -40,23 +40,23 @@ npx github-wrapped-2025
 
 ### Run with bunx (Recommended - 100x faster!)
 ```bash
-bunx github-wrapped-2025
+bunx gh-wrapped-2025
 ```
 No installation needed! Just run it once and the app handles everything.
 
 ### Run with npx (Also works)
 ```bash
-npx github-wrapped-2025
+npx gh-wrapped-2025
 ```
 
 ### Install Globally
 ```bash
 # With Bun
-bun install -g github-wrapped-2025
+bun install -g gh-wrapped-2025
 github-wrapped
 
 # With npm
-npm install -g github-wrapped-2025
+npm install -g gh-wrapped-2025
 github-wrapped
 ```
 
@@ -65,17 +65,20 @@ github-wrapped
 git clone https://github.com/d3varaja/gh-wrapped-cli.git
 cd gh-wrapped-cli
 
-# Install with Bun (recommended)
-bun install
-bun run build
-bun start
+# Install dependencies
+bun install  # or npm install
 
-# Or with npm
-npm install
-npm run build
+# Build the project
+bun run build  # or npm run build
+
+# Run the built version (use Node, not Bun - see note below)
 npm start
+# or
+node dist/index.js
 ```
 
+**⚠️ Important:** Always use **Node** to run the built version (`npm start` or `node dist/index.js`), not `bun start`. The image export feature uses Playwright which has known compatibility issues with Bun's runtime, especially on Windows. Bun is great for development and building, but Node is required for running the final output.
+
 ## How It Works
 
 1. Fetches your public GitHub data via GitHub API
@@ -111,7 +114,7 @@ npm install
 
 ### Development mode
 ```bash
-# With Bun (hot reload)
+# With Bun (recommended - hot reload)
 bun run dev
 
 # Or with npm
@@ -120,13 +123,21 @@ npm run dev
 
 ### Build
 ```bash
-# With Bun (faster)
+# With Bun (recommended - faster)
 bun run build
 
 # Or with npm
 npm run build
 ```
 
+### Run built version
+```bash
+# IMPORTANT: Use Node, not Bun (Playwright compatibility)
+npm start
+# or
+node dist/index.js
+```
+
 ### Project Structure
 ```
 src/
@@ -143,7 +154,7 @@ src/
 You can also use this as a library:
 
 ```typescript
-import { GitHubClient } from 'github-wrapped-2025';
+import { GitHubClient } from 'gh-wrapped-2025';
 
 const client = new GitHubClient('username');
 const repos = await client.getRepositories();
@@ -188,7 +199,7 @@ If you're developing or running this locally, you can set a token beforehand:
 
 ```bash
 # Environment variable (one-time)
-GITHUB_TOKEN=your_token npx github-wrapped-2025
+GITHUB_TOKEN=your_token npx gh-wrapped-2025
 
 # Or create .env file in project directory
 echo "GITHUB_TOKEN=your_token" > .env

bunfig.toml

@@ -1,11 +1,11 @@
 {
-  "name": "github-wrapped-2025",
+  "name": "gh-wrapped-2025",
   "version": "1.0.3",
   "description": "Your GitHub year in review - in your terminal",
   "main": "dist/index.js",
   "bin": {
     "github-wrapped": "./dist/index.js",
-    "github-wrapped-2025": "./dist/index.js"
+    "gh-wrapped-2025": "./dist/index.js"
   },
   "type": "module",
   "files": [