contribs.sh 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hartman
+
+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.

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+# contribs.sh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A browser dashboard for your contribution history, merged across **multiple sources** —
+github.com accounts, GitHub Enterprise, and Forgejo/Gitea instances (e.g. Codeberg) — rendered
+with [`@json-render/react`](https://json-render.dev). It distinguishes genuine zero-activity days
+from days where no source has data (lost / pre-migration history), which render as a distinct
+hatched "no data" cell, and lets you annotate periods your work lived on another platform.
+
+## Make it your own
+
+Everything personal (which accounts to fetch, your lost/incomplete periods, tokens, generated data)
+is gitignored — the repo ships `.example` templates, so a fresh clone builds with neutral defaults.
+To run your own version:
+
+```bash
+git clone <your-fork-url> && cd contribs.sh
+npm install
+
+cp sources.example.json sources.json        # edit: your accounts (see "Configuring sources")
+cp lost-ranges.example.json lost-ranges.json # optional: periods on other platforms / lost history
+
+npm run fetch                                # pulls your data → public/data/contributions.json
+npm run dev                                  # open the printed localhost URL
+```
+
+**Prerequisites:** Node 18+ and either the [`gh` CLI](https://cli.github.com/) authenticated with your
+github.com account(s), or Personal Access Tokens for any source not in `gh` (see Tokens below).
+
+## Configuring sources
+
+`sources.json` (gitignored) lists the accounts to merge. Each entry:
+
+| field      | meaning                                                                 |
+| ---------- | ----------------------------------------------------------------------- |
+| `id`       | unique slug (used for the per-source file name)                         |
+| `label`    | display name in the UI                                                  |
+| `type`     | `github` (github.com or Enterprise) or `forgejo` (Codeberg/Gitea)       |
+| `host`     | `github.com`, your Enterprise host, or `codeberg.org`                   |
+| `username` | the account's login                                                     |
+| `tokenEnv` | name of the env var holding the token — **omit** for a github.com account managed by the `gh` CLI |
+| `enabled`  | set `false` to keep an entry without fetching it                        |
+
+**Tokens.** github.com accounts in your `gh` keyring need no token — the fetch script pulls one via
+`gh auth token --user <username>`. Every other source reads its token from an env var named by
+`tokenEnv`, loaded from a gitignored `.env` (see `.env.example`):
+
+- **GitHub Enterprise** — a PAT with `repo` + `read:org` on the Enterprise host.
+- **Codeberg / Forgejo** — an access token with `read:user`.
+- **A second github.com account** not in `gh` — a PAT with `repo` + `read:org`.
+
+Sources whose token can't be resolved are skipped with a warning, so the dashboard always builds
+with whatever credentials are available.
+
+## How it works
+
+- **`src/fetch/`** — `npm run fetch` reads `sources.json`, runs one adapter per source
+  (`adapters/github.ts` = GraphQL `contributionsCollection`; `adapters/forgejo.ts` = the
+  `/api/v1/users/{user}/heatmap` REST endpoint), then `merge.ts` sums per-day counts and unions
+  coverage windows into `public/data/contributions.json` (per-source files land in
+  `public/data/sources/`).
+- **`src/`** — the React app loads that JSON, exposes it via `contributionsContext`, and renders a
+  layout described by `dashboard.json` against the json-render catalog/registry in `catalog.tsx`.
+  Components (`YearHeatmap`, `StatsPanel`, `YearSelector`, `SourceLegend`) read the data from context.
+
+A day is **known** when at least one source's coverage window includes it; unknown days carry count 0
+and are excluded from streak/average stats so lost history never distorts the numbers.
+Coverage ends no later than the UTC fetch date. The full current-year grid remains visible:
+dates after today use a subdued outline and a "Future date" tooltip, contribute to no stats,
+and cannot receive lost-history annotations. Elapsed dates after the last fetch are "No data"
+until a refresh covers them. Future-date styling advances with the UTC date while the app is open.
+
+## Marking history lost to a migration
+
+Some real history (e.g. a Bitbucket → GitHub migration) no longer exists on any source. You can mark
+those days so they render in a distinct **gray "lost"** style with a hover note, instead of looking
+like zero-activity days. Edit the committed **`lost-ranges.json`**:
+
+```json
+{
+  "enabled": true,
+  "label": "Contribs lost due to Bitbucket migration",
+  "ranges": [
+    {
+      "id": "bitbucket-era",
+      "from": "2016-01-01",
+      "to": "2020-12-31",
+      "days": "weekdays",
+      "weekdays": [1, 2, 3, 4, 5],
+      "note": "Contribs lost due to Bitbucket migration",
+      "enabled": true
+    }
+  ]
+}
+```
+
+- `from` / `to` — inclusive ISO date range to mark.
+- `days` — `"weekdays"` (Mon–Fri), `"all"` (include weekends), or `"selective"` (use the `weekdays`
+  list; `0`=Sun … `6`=Sat).
+- `note` — optional hover text for this range; falls back to the top-level `label`.
+- `label` — optional short name shown in the legend; falls back to `id`.
+- `color` — optional cell color for this range's lost days (any CSS color); falls back to a neutral
+  gray. Use distinct colors to tell ranges apart at a glance.
+- Only **0-contribution** days in the range are colored — days that already have contributions stay
+  green. Each active range gets its own swatch in the legend.
+
+**Toggle:** the legend has a **"Lost / incomplete"** checkbox that shows/hides the overlay live (your
+choice is remembered in the browser). While it's on, each lost day counts as **1** toward **Total
+contributions**, **Active days**, and **Avg / active day** — but **never** toward **Longest** or
+**Current streak**, which always reflect real GitHub activity only. Turning it off reverts both the
+heatmap and the stats to GitHub-only numbers.
+
+**To remove a range entirely:** set its `"enabled": false` (or delete the entry), or flip the
+top-level `"enabled": false`. Config changes apply on reload — no re-fetch.
+
+`lost-ranges.example.json` ships a single **disabled** example range; copy it to `lost-ranges.json`,
+set your real window(s), and `"enabled": true`. If `lost-ranges.json` is absent the app falls back to
+the example, so the build never breaks.
+
+## Display settings
+
+`config.json` (committed — not personal) holds display preferences:
+
+| field         | meaning                                                                      |
+| ------------- | ---------------------------------------------------------------------------- |
+| `title`       | Site name — shown as the page heading and the browser tab title.             |
+| `recentYears` | In the "All years" view, how many recent years to show before the **"Show earlier years"** toggle (default `10`). Older years fade in when you expand them. |
+| `startYear` | Earliest year to display (currently `2007`). Takes effect on the next fetch; years without source coverage show "No data" and do not change contribution totals. Earlier source history is still retained. |
+
+The year filter at the top is a dropdown — jump straight to any year (including older, collapsed ones)
+or back to the all-years overview.
+
+The sticky legend's service buttons filter the heatmaps, tooltips, year totals, and stats.
+GitHub controls fetched activity from every GitHub source plus any lost range labelled `GitHub`;
+each other lost range (in `lost-ranges.json` order) gets its own button that toggles its
+annotations. The gray Lost / Incomplete checkbox controls all annotations without hiding real
+activity. Selections persist in the browser; No Data and Less–More are informational.
+
+## Scripts
+
+| script          | does                                            |
+| --------------- | ----------------------------------------------- |
+| `npm run fetch` | fetch + merge all sources → `public/data/`      |
+| `npm run dev`   | Vite dev server                                 |
+| `npm run build` | type-check (app + node) and production build    |
+| `npm run preview` | preview the production build                   |
+| `npm run banner -- ...` | render banner / card / Wrapped / poster images |
+| `npm run cli -- ...` | the `contribs-sh` CLI (`init`, `fetch`, `banner`, `scan`) |
+
+## Recovering history from local repos
+
+Commits that never reached a hosted forge (an old employer's GitLab, an SVN repo you converted with
+`git svn`, a Bitbucket repo you still have cloned) can be counted straight from disk:
+
+```bash
+npm run cli -- scan ~/code/old-work --email you@old-employer.example
+```
+
+`scan` lists commits per year and prints a `"type": "local"` source to paste into `sources.json`.
+Commits are de-duplicated by hash across repos. Anything you also pushed to GitHub is already in your
+GitHub graph, so set `from`/`to` to the period GitHub is missing. Recovered days are real data, so
+they replace the hand-drawn `lost-ranges.json` annotation for that period.
+
+## Exporting images
+
+The dashboard has an **Export image** panel. It renders the same SVG the CLI uses and downloads it
+as PNG or SVG:
+
+| preset     | size         | layout                                         |
+| ---------- | ------------ | ---------------------------------------------- |
+| `x`        | 1500×500     | banner; content kept right of the profile photo |
+| `linkedin` | 1584×396     | banner                                         |
+| `og`       | 1200×630     | card                                           |
+| `github`   | 1280×640     | card (repo social preview)                     |
+| `wrapped`  | 1080×1350    | year-in-review story with stats                |
+| `poster`   | 5400×7200    | every year, 18×24 in at 300 dpi                |
+
+From the command line (renders with `resvg`, no browser):
+
+```bash
+npm run banner -- --preset x                         # contribs-x.png
+npm run banner -- --preset wrapped --range 2026 --title "2026 in code"
+npm run banner -- --preset poster --theme light --out poster.png
+npm run banner -- --preset all --out banners/        # every preset, PNG + SVG
+```
+
+Options: `--range rolling|all|YEAR`, `--theme dark|light`, `--title`, `--scale`, `--no-stats`,
+`--no-mark`, `--transparent`. Lost ranges from `lost-ranges.json` are drawn in their colors.
+
+## CLI
+
+Install with `npx contribs.sh <command>` (or `npm i -g contribs.sh`; the binary is `contribs.sh`, with `contribs-sh` as an alias). Inside a clone, `npm run cli --` runs the same thing:
+
+```bash
+contribs.sh init [--ci]      # sources.json for your gh login; --ci adds the Pages workflow
+contribs.sh fetch            # same as npm run fetch
+contribs.sh banner [...]     # see above
+contribs.sh scan DIR...      # see "Recovering history from local repos"
+```
+
+## Self-hosting with GitHub Actions
+
+`.github/workflows/contribs.yml` refreshes the data daily, builds the dashboard, renders every banner
+preset, and publishes to GitHub Pages. It does nothing until configured, so forks are safe:
+
+1. Repo → Settings → Secrets → Actions: add `CONTRIBS_SOURCES` (your `sources.json`, with a
+   `tokenEnv` on every source), one secret per `tokenEnv` (e.g. `GH_MAIN_TOKEN`, a classic PAT with
+   `read:user`, `repo`, `read:org`), and optionally `CONTRIBS_LOST_RANGES`.
+2. Settings → Pages → Source: **GitHub Actions**.
+3. Run the workflow once from the Actions tab.
+
+Your banners are then at `https://<you>.github.io/<repo>/banners/x.png` (and `.svg`), ready to embed in
+a README or site. Add extra token secrets to the `env:` block of the "Fetch, build, render banners" step.
+
+## Deploying
+
+The app is a static site — the only runtime input is `public/data/contributions.json`, produced by
+`npm run fetch`. To publish:
+
+```bash
+npm run fetch     # refresh your data (needs gh/tokens; do this wherever you build)
+npm run build     # outputs dist/
+# deploy dist/ to GitHub Pages, Vercel, Netlify, Cloudflare Pages, etc.
+```
+
+Because `sources.json`, `lost-ranges.json`, and `public/data/` are gitignored, the simplest path is to
+**fetch + build + deploy from your own machine**. To deploy from CI instead, provide those files to the
+CI job (e.g. commit a token-free `lost-ranges.json`, recreate `sources.json` from a secret, and run
+`gh auth login` / set token env vars) before `npm run fetch`. Re-run `fetch` on a schedule to keep the
+graph current.

package/bin/contribs-sh.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from 'tsx/esm/api';
+
+register();
+await import('../src/cli/index.ts');

package/config.json

@@ -0,0 +1,5 @@
+{
+  "title": "contribs.sh",
+  "recentYears": 10,
+  "startYear": 2007
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "contribs.sh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.node.json && vite build",
+    "preview": "vite preview",
+    "fetch": "tsx src/fetch/fetch.ts",
+    "cli": "tsx src/cli/index.ts",
+    "banner": "tsx src/cli/index.ts banner"
+  },
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "tsx": "^4.19.2"
+  },
+  "devDependencies": {
+    "@json-render/core": "^0.19.0",
+    "@json-render/react": "^0.19.0",
+    "@types/node": "^22.10.1",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "^5.6.3",
+    "vite": "^6.0.3",
+    "zod": "^4.4.3"
+  },
+  "bin": {
+    "contribs.sh": "bin/contribs-sh.mjs",
+    "contribs-sh": "bin/contribs-sh.mjs"
+  },
+  "description": "Every contribution, every forge, one heatmap — merge GitHub, GitHub Enterprise, Forgejo and local git history, export banners for X, LinkedIn and more.",
+  "license": "MIT",
+  "homepage": "https://contribs.sh",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src/cli",
+    "src/render",
+    "src/data",
+    "src/fetch",
+    "src/config.ts",
+    "config.json"
+  ],
+  "keywords": [
+    "github",
+    "contributions",
+    "heatmap",
+    "banner",
+    "cli",
+    "forgejo",
+    "gitea"
+  ]
+}

package/src/cli/index.ts

@@ -0,0 +1,237 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import type { MergedData } from '../data/types';
+import { compileLost, EMPTY_LOST_CONFIG, type LostConfig } from '../data/lost';
+import { PRESETS, PRESET_IDS, renderSvg, type PresetId, type Range, type ThemeId } from '../render/svg';
+import { findRepos, localAdapter } from '../fetch/adapters/local';
+import { runFetch } from '../fetch/run';
+import { workflowYaml } from './workflow';
+
+const HELP = `contribs.sh — every contribution, every forge, one heatmap.
+
+Usage:
+  contribs.sh init [--ci]            create sources.json (and a GitHub Actions workflow with --ci)
+  contribs.sh fetch [--out DIR]      fetch + merge all sources (default DIR: public/data)
+  contribs.sh banner [options]       render an image from the merged data
+  contribs.sh scan DIR... [options]  recover history from local git repos on disk
+
+banner options:
+  --preset ID      ${PRESET_IDS.join(' | ')} | all   (default: x)
+  --range R        rolling | all | YEAR             (default depends on preset)
+  --theme T        dark | light                     (default: dark)
+  --title TEXT     heading for card / wrapped / poster layouts
+  --out PATH       .png or .svg file; a directory when --preset all (default: contribs-<preset>.png)
+  --data PATH      merged data (default: public/data/contributions.json; fetched if missing)
+  --scale N        PNG pixel ratio (default: 1)
+  --no-stats       hide totals and stats text
+  --no-mark        hide the contribs.sh mark
+  --transparent    no background fill
+
+scan options:
+  --email ADDR     author email to count (repeatable; default: git config user.email)
+  --depth N        directory levels to search (default: 4)
+  --from DATE      ignore commits before YYYY-MM-DD
+  --to DATE        ignore commits after YYYY-MM-DD
+`;
+
+const root = process.cwd();
+
+function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(path, 'utf8')) as T;
+}
+
+function loadLost(): LostConfig {
+  const path = resolve(root, 'lost-ranges.json');
+  return existsSync(path) ? readJson<LostConfig>(path) : EMPTY_LOST_CONFIG;
+}
+
+function gitEmail(): string | null {
+  try {
+    return execFileSync('git', ['config', 'user.email'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function ghLogin(): string | null {
+  try {
+    return execFileSync('gh', ['api', 'user', '-q', '.login'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function init(args: string[]) {
+  const { values } = parseArgs({ args, options: { ci: { type: 'boolean' } } });
+  const sourcesPath = resolve(root, 'sources.json');
+  if (existsSync(sourcesPath)) {
+    console.log('sources.json already exists — leaving it alone.');
+  } else {
+    const login = ghLogin();
+    const sources = {
+      sources: [
+        {
+          id: 'gh-main',
+          label: 'GitHub',
+          type: 'github',
+          host: 'github.com',
+          username: login ?? 'your-github-username',
+          ...(values.ci ? { tokenEnv: 'GH_MAIN_TOKEN' } : {}),
+          enabled: true,
+        },
+      ],
+    };
+    writeFileSync(sourcesPath, `${JSON.stringify(sources, null, 2)}\n`);
+    console.log(`Wrote sources.json${login ? ` for ${login}` : ' — edit "username"'}.`);
+  }
+  if (values.ci) {
+    const wf = resolve(root, '.github/workflows/contribs.yml');
+    if (existsSync(wf)) {
+      console.log('.github/workflows/contribs.yml already exists — leaving it alone.');
+    } else {
+      mkdirSync(dirname(wf), { recursive: true });
+      writeFileSync(wf, workflowYaml());
+      console.log('Wrote .github/workflows/contribs.yml. Add a GH_MAIN_TOKEN repo secret (classic PAT: read:user, repo, read:org)');
+      console.log('and a CONTRIBS_SOURCES secret holding your sources.json, then enable GitHub Pages → "GitHub Actions".');
+    }
+  }
+  console.log('Next: contribs.sh fetch && contribs.sh banner');
+}
+
+async function fetchCmd(args: string[]) {
+  const { values } = parseArgs({ args, options: { out: { type: 'string' } } });
+  await runFetch(root, resolve(root, values.out ?? 'public/data'));
+}
+
+async function toPng(svg: string, scale: number): Promise<Buffer> {
+  const { Resvg } = await import('@resvg/resvg-js');
+  const resvg = new Resvg(svg, {
+    fitTo: scale === 1 ? { mode: 'original' } : { mode: 'zoom', value: scale },
+    font: { loadSystemFonts: true, defaultFontFamily: 'Helvetica' },
+  });
+  return resvg.render().asPng();
+}
+
+async function banner(args: string[]) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      preset: { type: 'string', default: 'x' },
+      range: { type: 'string' },
+      theme: { type: 'string', default: 'dark' },
+      title: { type: 'string' },
+      out: { type: 'string' },
+      data: { type: 'string' },
+      scale: { type: 'string', default: '1' },
+      'no-stats': { type: 'boolean' },
+      'no-mark': { type: 'boolean' },
+      transparent: { type: 'boolean' },
+    },
+  });
+
+  const presets: PresetId[] = values.preset === 'all' ? PRESET_IDS : [values.preset as PresetId];
+  for (const p of presets) if (!PRESETS[p]) fail(`Unknown preset "${p}". Use one of: ${PRESET_IDS.join(', ')}, all`);
+  if (values.theme !== 'dark' && values.theme !== 'light') fail('--theme must be dark or light');
+  const range: Range | undefined = values.range === undefined ? undefined
+    : values.range === 'rolling' || values.range === 'all' ? values.range
+    : /^\d{4}$/.test(values.range) ? Number(values.range) : fail('--range must be rolling, all, or a year');
+  const scale = Number(values.scale);
+  if (!(scale > 0 && scale <= 4)) fail('--scale must be between 0 and 4');
+
+  const dataPath = resolve(root, values.data ?? 'public/data/contributions.json');
+  const data: MergedData = existsSync(dataPath)
+    ? readJson<MergedData>(dataPath)
+    : values.data ? fail(`No data at ${dataPath}`) : await runFetch(root, dirname(dataPath));
+
+  const lostFor = compileLost(loadLost());
+  for (const preset of presets) {
+    let out = values.out ?? `contribs-${preset}.png`;
+    if (presets.length > 1) {
+      const dir = resolve(root, values.out ?? 'banners');
+      mkdirSync(dir, { recursive: true });
+      out = join(dir, `${preset}.png`);
+    }
+    const svg = renderSvg(data, {
+      preset,
+      range,
+      theme: values.theme as ThemeId,
+      title: values.title,
+      stats: !values['no-stats'],
+      mark: !values['no-mark'],
+      transparent: values.transparent,
+      lostFor,
+    });
+    const target = resolve(root, out);
+    mkdirSync(dirname(target), { recursive: true });
+    if (extname(target).toLowerCase() === '.svg') {
+      writeFileSync(target, svg);
+    } else {
+      writeFileSync(target, await toPng(svg, scale));
+      if (presets.length > 1) writeFileSync(target.replace(/\.png$/, '.svg'), svg);
+    }
+    console.log(`Wrote ${target} (${PRESETS[preset].label})`);
+  }
+}
+
+async function scan(args: string[]) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      email: { type: 'string', multiple: true },
+      depth: { type: 'string', default: '4' },
+      from: { type: 'string' },
+      to: { type: 'string' },
+    },
+  });
+  if (positionals.length === 0) fail('Usage: contribs.sh scan DIR... [--email ADDR]');
+  const emails = values.email?.length ? values.email : [gitEmail()].filter((e): e is string => !!e);
+  if (emails.length === 0) fail('No author email: pass --email or set git config user.email');
+  const depth = Number(values.depth);
+
+  const repos = [...new Set(positionals.flatMap((p) => findRepos(p, depth)))];
+  console.log(`Found ${repos.length} repo(s) under ${positionals.join(', ')}; counting commits by ${emails.join(', ')}…`);
+  const result = await localAdapter({
+    id: 'local-scan', label: 'Local repos', type: 'local', host: '', username: '', token: '',
+    paths: positionals, emails, depth, from: values.from, to: values.to,
+  });
+
+  const byYear = new Map<string, number>();
+  for (const [date, count] of Object.entries(result.days)) byYear.set(date.slice(0, 4), (byYear.get(date.slice(0, 4)) ?? 0) + count);
+  const total = [...byYear.values()].reduce((a, b) => a + b, 0);
+  if (total === 0) {
+    console.log('No matching commits. Check the email(s) your old commits used: git log --format=%ae | sort -u');
+    return;
+  }
+  for (const [year, count] of [...byYear].sort()) console.log(`  ${year}  ${String(count).padStart(6)} commits`);
+  console.log(`  total ${String(total).padStart(6)} commits (${result.coverage.from} → ${result.coverage.to})\n`);
+  console.log('Add this to sources.json to merge it (set from/to to the years GitHub is missing):');
+  console.log(JSON.stringify({
+    id: 'local-history',
+    label: 'Recovered (local git)',
+    type: 'local',
+    paths: positionals,
+    emails,
+    from: values.from ?? result.coverage.from,
+    to: values.to ?? result.coverage.to,
+    enabled: true,
+  }, null, 2));
+}
+
+const commands: Record<string, (args: string[]) => Promise<void>> = { init, fetch: fetchCmd, banner, scan };
+
+const [command, ...rest] = process.argv.slice(2);
+if (!command || command === '-h' || command === '--help' || command === 'help') {
+  process.stdout.write(HELP);
+} else if (!commands[command]) {
+  fail(`Unknown command "${command}".\n\n${HELP}`);
+} else {
+  commands[command](rest).catch((err: unknown) => fail(err instanceof Error ? err.message : String(err)));
+}

package/src/cli/workflow.ts

@@ -0,0 +1,85 @@
+/** GitHub Actions workflow: daily fetch → build → banners → GitHub Pages. */
+export function workflowYaml(): string {
+  return `# contribs.sh — refresh your heatmap daily and publish it (plus banner images) to GitHub Pages.
+#
+# Setup (repo → Settings):
+#   1. Secrets and variables → Actions → New repository secret:
+#        CONTRIBS_SOURCES      contents of your sources.json (every source needs "tokenEnv")
+#        GH_MAIN_TOKEN         classic PAT with read:user, repo, read:org (one secret per tokenEnv)
+#        CONTRIBS_LOST_RANGES  optional: contents of your lost-ranges.json
+#   2. Pages → Build and deployment → Source: GitHub Actions
+#
+# Published files: index.html (dashboard), banners/<preset>.png|svg, data/contributions.json
+name: contribs
+
+on:
+  schedule:
+    - cron: '17 6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      configured: \${{ steps.check.outputs.configured }}
+    steps:
+      - id: check
+        env:
+          CONTRIBS_SOURCES: \${{ secrets.CONTRIBS_SOURCES }}
+        run: |
+          if [ -n "$CONTRIBS_SOURCES" ]; then echo configured=true >> "$GITHUB_OUTPUT"; else
+            echo "::notice::CONTRIBS_SOURCES secret not set — skipping. See the setup notes at the top of this workflow."
+            echo configured=false >> "$GITHUB_OUTPUT"; fi
+      - if: steps.check.outputs.configured == 'true'
+        uses: actions/checkout@v4
+      - if: steps.check.outputs.configured == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - if: steps.check.outputs.configured == 'true'
+        name: Write config from secrets
+        env:
+          CONTRIBS_SOURCES: \${{ secrets.CONTRIBS_SOURCES }}
+          CONTRIBS_LOST_RANGES: \${{ secrets.CONTRIBS_LOST_RANGES }}
+        run: |
+          printf '%s' "$CONTRIBS_SOURCES" > sources.json
+          if [ -n "$CONTRIBS_LOST_RANGES" ]; then printf '%s' "$CONTRIBS_LOST_RANGES" > lost-ranges.json; fi
+      - if: steps.check.outputs.configured == 'true'
+        name: Fetch, build, render banners
+        env:
+          GH_MAIN_TOKEN: \${{ secrets.GH_MAIN_TOKEN }}
+          # Add one line per extra "tokenEnv" in your sources.json, e.g.:
+          # GHE_TOKEN: \${{ secrets.GHE_TOKEN }}
+          # CODEBERG_TOKEN: \${{ secrets.CODEBERG_TOKEN }}
+        run: |
+          npm ci
+          npm run fetch
+          npm run build -- --base ./
+          npm run banner -- --preset all --out dist/banners
+      - if: steps.check.outputs.configured == 'true'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    if: needs.build.outputs.configured == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+`;
+}

package/src/config.ts

@@ -0,0 +1,20 @@
+import raw from '../config.json';
+
+/**
+ * Site/display settings. Committed (not personal data) — fork and edit freely.
+ * Personal config lives in the gitignored `sources.json` / `lost-ranges.json`.
+ */
+interface AppConfig {
+  /** Site name — shown as the page heading and the browser tab title. */
+  title: string;
+  /** How many of the most recent years to show before the "show earlier" toggle. */
+  recentYears: number;
+  /** Earliest year to include, even when sources have no coverage. */
+  startYear: number;
+}
+
+const config = raw as Partial<AppConfig>;
+
+export const title = config.title ?? 'contribs.sh';
+export const recentYears = config.recentYears ?? 10;
+export const startYear = config.startYear;