ai-heatmap 1.0.0

package/.github/workflows/deploy.yml

@@ -0,0 +1,50 @@
+name: Deploy AI Heatmap
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - "public/data.json"
+      - "src/**"
+      - "index.html"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - run: npm ci
+
+      - name: Generate static SVG from data.json
+        run: npm run generate:svg
+
+      - run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/README.md

@@ -0,0 +1,208 @@
+# AI Heatmap
+
+GitHub-style heatmap for your AI usage costs. Powered by [ccusage](https://github.com/ryoppippi/ccusage) + [react-activity-calendar](https://github.com/grubersjoe/react-activity-calendar).
+
+## Preview
+
+<!-- Replace YOUR_VERCEL_DOMAIN with your actual Vercel deployment URL -->
+![AI Heatmap](https://YOUR_VERCEL_DOMAIN/api/heatmap)
+
+### Variations
+
+```markdown
+<!-- Dark mode with full stats -->
+![](https://YOUR_VERCEL_DOMAIN/api/heatmap?colorScheme=dark)
+
+<!-- Blue theme, heatmap + stats only -->
+![](https://YOUR_VERCEL_DOMAIN/api/heatmap?theme=blue&weekday=false)
+
+<!-- Heatmap only (clean embed) -->
+![](https://YOUR_VERCEL_DOMAIN/api/heatmap?stats=false&weekday=false)
+
+<!-- Custom date range -->
+![](https://YOUR_VERCEL_DOMAIN/api/heatmap?start=2026-01-01&end=2026-02-18)
+```
+
+## Quick Start
+
+```bash
+# Generate data from local ccusage logs
+npx ai-heatmap generate
+
+# Init a new GitHub Pages repo
+npx ai-heatmap init my-ai-heatmap
+
+# Push data to repo
+npx ai-heatmap push --repo owner/my-ai-heatmap
+
+# Generate + push in one step
+npx ai-heatmap update --repo owner/my-ai-heatmap
+```
+
+## SVG API (Vercel)
+
+Deploy this repo to Vercel for a dynamic SVG endpoint. Embed it in any README:
+
+```markdown
+![AI Heatmap](https://your-app.vercel.app/api/heatmap)
+```
+
+The SVG is generated on each request from `public/data.json`, so you can control the output with query parameters.
+
+### SVG API Options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `colorScheme` | `light` | Color scheme: `light`, `dark` |
+| `theme` | same as `colorScheme` | Theme override: `light`, `dark`, `blue`, `orange`, `pink` |
+| `blockSize` | `16` | Size of each day block in pixels |
+| `blockMargin` | `4` | Gap between blocks in pixels |
+| `blockRadius` | `3` | Border radius of blocks in pixels |
+| `bg` | auto | Background color (e.g. `%23ffffff`). Auto: transparent (light) / `#0d1117` (dark) |
+| `textColor` | auto | Text color. Auto: `#24292f` (light) / `#c9d1d9` (dark) |
+| `start` | - | Filter start date (`YYYY-MM-DD`) |
+| `end` | - | Filter end date (`YYYY-MM-DD`) |
+| `stats` | `true` | Show stats section (daily avg, weekly avg, peak, active days) |
+| `weekday` | `true` | Show average-by-weekday bar chart |
+
+### SVG API Examples
+
+```
+# Default light theme with all sections
+/api/heatmap
+
+# Dark theme
+/api/heatmap?colorScheme=dark
+
+# Pink theme, heatmap only
+/api/heatmap?theme=pink&stats=false&weekday=false
+
+# Custom block size
+/api/heatmap?blockSize=12&blockMargin=3&blockRadius=2
+
+# Date range filter
+/api/heatmap?start=2026-01-01&end=2026-02-18
+```
+
+## GitHub Pages (Interactive)
+
+The interactive version with tooltips is deployed via GitHub Pages. Tooltips show cost, tokens, cache hit rate, and per-model breakdown.
+
+### GitHub Pages Options
+
+All options are controlled via query string:
+
+```
+https://owner.github.io/my-ai-heatmap/?colorScheme=dark&blockSize=14
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `colorScheme` | `light` | Color scheme: `light`, `dark` |
+| `blockSize` | `12` | Size of each day block in pixels |
+| `blockMargin` | `3` | Gap between blocks in pixels |
+| `blockRadius` | `2` | Border radius of blocks in pixels |
+| `fontSize` | `12` | Font size in pixels |
+| `hideColorLegend` | `false` | Hide the color legend |
+| `hideMonthLabels` | `false` | Hide month labels |
+| `hideTotalCount` | `false` | Hide total count label |
+| `showWeekdayLabels` | `true` | Show weekday labels (Mon, Wed, Fri) |
+| `weekStart` | `0` | First day of week (0 = Sunday, 1 = Monday) |
+| `start` | - | Filter start date (`YYYY-MM-DD`) |
+| `end` | - | Filter end date (`YYYY-MM-DD`) |
+
+### Available Themes (SVG API)
+
+| Theme | Colors |
+|-------|--------|
+| `light` | `#ebedf0` `#c6e48b` `#7bc96f` `#239a3b` `#196127` |
+| `dark` | `#161b22` `#0e4429` `#006d32` `#26a641` `#39d353` |
+| `blue` | `#ebedf0` `#c0ddf9` `#73b3f3` `#3886e1` `#1b4f91` |
+| `orange` | `#ebedf0` `#ffdf80` `#ffa742` `#e87d2f` `#ac5219` |
+| `pink` | `#ebedf0` `#ffc0cb` `#ff69b4` `#ff1493` `#c71585` |
+
+## Configuration
+
+Customize the static SVG output by editing `heatmap.config.json` in the project root:
+
+```json
+{
+  "colorScheme": "light",
+  "theme": "",
+  "blockSize": 16,
+  "blockMargin": 4,
+  "blockRadius": 3,
+  "bg": "",
+  "textColor": "",
+  "start": "",
+  "end": "",
+  "stats": true,
+  "weekday": true
+}
+```
+
+This config is used by `npm run generate:svg` to build `public/heatmap.svg`. Empty strings (`""`) use auto defaults.
+
+For the Vercel dynamic API, use query parameters instead (they override config).
+
+## Data Update
+
+`ccusage` reads Claude Code usage logs from your **local machine**, so data must be generated locally and pushed to the repo.
+
+```bash
+# Generate + push in one step
+npx ai-heatmap update --repo owner/my-ai-heatmap
+
+# Or manually
+npx ai-heatmap generate
+git add public/data.json && git commit -m "update data" && git push
+```
+
+For automated updates, use a local cron job or macOS LaunchAgent:
+
+```bash
+# crontab -e (runs daily at midnight)
+0 0 * * * cd /path/to/ai-heatmap && npx ai-heatmap update --repo owner/my-ai-heatmap
+```
+
+## Deployment
+
+### GitHub Pages
+
+1. Enable GitHub Pages (Settings > Pages > Source: GitHub Actions)
+2. Push `data.json` to `main` to trigger the first deploy
+3. Manual deploy: Actions tab > "Deploy AI Heatmap" > "Run workflow"
+
+### Vercel
+
+1. Import this repo on [vercel.com](https://vercel.com)
+2. Deploy (zero config — `vercel.json` included)
+3. Use the deployed URL for dynamic SVG embeds
+
+## Local Development
+
+```bash
+npm install
+npm run generate              # Generate data.json from ccusage
+npm run dev                   # Vite dev server (interactive heatmap)
+node scripts/serve-svg.mjs    # Local SVG API on :3333
+```
+
+## Project Structure
+
+```
+ai-heatmap/
+  api/heatmap.ts              # Vercel serverless SVG endpoint
+  bin/cli.mjs                 # CLI entrypoint
+  bin/init.mjs                # Repo scaffolding
+  bin/push.mjs                # Push data to GitHub
+  scripts/generate.mjs        # ccusage -> data.json
+  scripts/generate-svg.mjs    # data.json -> static heatmap.svg
+  scripts/serve-svg.mjs       # Local SVG dev server
+  src/App.tsx                 # React interactive heatmap
+  public/data.json            # Generated activity data
+```
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+const [command, ...args] = process.argv.slice(2);
+
+const HELP = `
+ai-heatmap - AI usage cost heatmap
+
+Commands:
+  init [repo-name]        Create a new heatmap GitHub Pages repo
+  generate [options]      Generate data.json from ccusage
+  push --repo <owner/repo>  Push data.json to target repo
+  update --repo <owner/repo>  generate + push combined
+
+Generate options:
+  --since YYYYMMDD        Start date
+  --until YYYYMMDD        End date
+
+Examples:
+  npx ai-heatmap init my-ai-heatmap
+  npx ai-heatmap generate --since 20260101
+  npx ai-heatmap push --repo seunggabi/my-ai-heatmap
+  npx ai-heatmap update --repo seunggabi/my-ai-heatmap
+`;
+
+switch (command) {
+  case "init": {
+    const script = resolve(__dirname, "init.mjs");
+    execSync(`node ${script} ${args.join(" ")}`, { stdio: "inherit" });
+    break;
+  }
+  case "generate": {
+    const script = resolve(root, "scripts/generate.mjs");
+    execSync(`node ${script} ${args.join(" ")}`, { stdio: "inherit" });
+    break;
+  }
+  case "push": {
+    const script = resolve(__dirname, "push.mjs");
+    execSync(`node ${script} ${args.join(" ")}`, { stdio: "inherit" });
+    break;
+  }
+  case "update": {
+    const genScript = resolve(root, "scripts/generate.mjs");
+    const pushScript = resolve(__dirname, "push.mjs");
+    const genArgs = args.filter(
+      (a) => a.startsWith("--since") || a.startsWith("--until"),
+    );
+    const pushArgs = args.filter((a) => a.startsWith("--repo"));
+    execSync(`node ${genScript} ${genArgs.join(" ")}`, { stdio: "inherit" });
+    execSync(`node ${pushScript} ${pushArgs.join(" ")}`, { stdio: "inherit" });
+    break;
+  }
+  default:
+    console.log(HELP);
+}

package/bin/init.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import { mkdirSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templateRoot = resolve(__dirname, "..");
+const repoName = process.argv[2] || "ai-heatmap";
+const targetDir = resolve(process.cwd(), repoName);
+
+if (existsSync(targetDir)) {
+  console.error(`Error: ${targetDir} already exists`);
+  process.exit(1);
+}
+
+console.log(`Creating ${repoName}...`);
+mkdirSync(targetDir, { recursive: true });
+
+// package.json
+const pkg = {
+  name: repoName,
+  version: "1.0.0",
+  type: "module",
+  scripts: {
+    generate: "npx ai-heatmap generate",
+    dev: "vite",
+    build: "vite build",
+    preview: "vite preview",
+    update: `npx ai-heatmap update --repo OWNER/${repoName}`,
+  },
+  dependencies: {
+    react: "^19.2.4",
+    "react-activity-calendar": "^3.1.1",
+    "react-dom": "^19.2.4",
+    "react-tooltip": "^5.30.0",
+  },
+  devDependencies: {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.4",
+    typescript: "^5.9.3",
+    vite: "^7.3.1",
+  },
+};
+writeFileSync(
+  resolve(targetDir, "package.json"),
+  JSON.stringify(pkg, null, 2),
+);
+
+// Copy template files
+const filesToCopy = [
+  "index.html",
+  "vite.config.ts",
+  "tsconfig.json",
+  ".gitignore",
+];
+for (const f of filesToCopy) {
+  copyFileSync(resolve(templateRoot, f), resolve(targetDir, f));
+}
+
+// Copy src/
+mkdirSync(resolve(targetDir, "src"), { recursive: true });
+const srcFiles = ["main.tsx", "App.tsx", "App.css", "vite-env.d.ts"];
+for (const f of srcFiles) {
+  copyFileSync(
+    resolve(templateRoot, "src", f),
+    resolve(targetDir, "src", f),
+  );
+}
+
+// Create public/
+mkdirSync(resolve(targetDir, "public"), { recursive: true });
+
+// GitHub Actions workflow
+const workflowDir = resolve(targetDir, ".github/workflows");
+mkdirSync(workflowDir, { recursive: true });
+copyFileSync(
+  resolve(templateRoot, ".github/workflows/deploy.yml"),
+  resolve(workflowDir, "deploy.yml"),
+);
+
+// Git init
+execSync("git init", { cwd: targetDir, stdio: "inherit" });
+execSync("git add -A", { cwd: targetDir, stdio: "inherit" });
+execSync('git commit -m "Initial commit: ai-heatmap"', {
+  cwd: targetDir,
+  stdio: "inherit",
+});
+
+// Try to create GitHub repo
+try {
+  execSync(`gh repo create ${repoName} --public --source=. --push`, {
+    cwd: targetDir,
+    stdio: "inherit",
+  });
+  console.log(`\nRepo created: https://github.com/$(gh api user -q .login)/${repoName}`);
+
+  // Enable GitHub Pages
+  try {
+    execSync(
+      `gh api repos/{owner}/{repo}/pages -X POST -f build_type=workflow 2>/dev/null || true`,
+      { cwd: targetDir, stdio: "inherit" },
+    );
+  } catch {
+    // Pages may need manual setup
+  }
+} catch {
+  console.log("\nGitHub repo creation skipped (gh CLI not available or auth needed)");
+  console.log("Push manually: git remote add origin <url> && git push -u origin main");
+}
+
+console.log(`
+Done! Next steps:
+  cd ${repoName}
+  npm install
+  npm run generate        # Generate data from ccusage
+  npm run dev             # Preview locally
+  git push                # Deploy to GitHub Pages
+`);

package/bin/push.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+const args = process.argv.slice(2);
+const repoIdx = args.indexOf("--repo");
+const repo = repoIdx !== -1 ? args[repoIdx + 1] : null;
+
+if (!repo) {
+  console.error("Usage: ai-heatmap push --repo <owner/repo>");
+  console.error("Example: ai-heatmap push --repo seunggabi/my-ai-heatmap");
+  process.exit(1);
+}
+
+const dataPath = resolve(root, "public/data.json");
+if (!existsSync(dataPath)) {
+  console.error("data.json not found. Run 'ai-heatmap generate' first.");
+  process.exit(1);
+}
+
+const content = readFileSync(dataPath, "utf-8");
+const base64 = Buffer.from(content).toString("base64");
+
+console.log(`Pushing data.json to ${repo}...`);
+
+// Get current file SHA if it exists (needed for update)
+let sha = "";
+try {
+  sha = execSync(
+    `gh api repos/${repo}/contents/public/data.json --jq .sha 2>/dev/null`,
+    { encoding: "utf-8" },
+  ).trim();
+} catch {
+  // File doesn't exist yet, that's fine
+}
+
+const payload = {
+  message: `Update heatmap data (${new Date().toISOString().slice(0, 10)})`,
+  content: base64,
+};
+if (sha) payload.sha = sha;
+
+const payloadStr = JSON.stringify(JSON.stringify(payload));
+
+try {
+  execSync(
+    `echo ${payloadStr} | gh api repos/${repo}/contents/public/data.json -X PUT --input -`,
+    { stdio: ["pipe", "inherit", "inherit"] },
+  );
+  console.log(`Updated public/data.json in ${repo}`);
+} catch (e) {
+  console.error("Push failed. Check gh auth and repo permissions.");
+  process.exit(1);
+}

package/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AI Heatmap</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ai-heatmap",
+  "version": "1.0.0",
+  "description": "AI usage cost heatmap powered by ccusage + react-activity-calendar",
+  "type": "module",
+  "bin": {
+    "ai-heatmap": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/",
+    "public/",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json",
+    ".github/"
+  ],
+  "scripts": {
+    "generate": "node scripts/generate.mjs",
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "generate:svg": "node scripts/generate-svg.mjs",
+    "deploy": "npm run generate && npm run generate:svg && npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "react": "^19.2.4",
+    "react-activity-calendar": "^3.1.1",
+    "react-dom": "^19.2.4",
+    "react-tooltip": "^5.30.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vercel/node": "^5.6.4",
+    "@vitejs/plugin-react": "^5.1.4",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  }
+}