headreel 1.0.0

package/LICENSE

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

@@ -0,0 +1,174 @@
+# headreel
+
+[![npm](https://img.shields.io/npm/v/headreel)](https://www.npmjs.com/package/headreel)
+[![CI](https://github.com/arifszn/headreel/actions/workflows/ci.yml/badge.svg)](https://github.com/arifszn/headreel/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+An animated banner for your GitHub profile, made from your own GitHub activity.
+
+![Contribution City banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/contribution-city.gif)
+
+headreel turns your contributions into a looping GIF. You can use it in two ways:
+
+- **One command on your computer.** Run `npx headreel` and get your banner. You do not install or set up anything. It works on macOS, Windows, and Linux.
+- **A GitHub Action that keeps it current.** Add one workflow file, and your banner updates every day by itself.
+
+Every style works on both light and dark GitHub themes.
+
+## Make your banner now
+
+Run this command. Replace `octocat` with your GitHub username.
+
+```bash
+npx headreel --style contribution-city --user octocat
+```
+
+The command saves your banner as `headreel.gif` in the current folder. The first run downloads headreel. After that, a banner takes a few seconds.
+
+Add your tagline and website:
+
+```bash
+npx headreel --style contribution-city --user octocat \
+  --tagline "Open source maintainer" \
+  --website https://example.com
+```
+
+You need [Node.js](https://nodejs.org) 22 (22.22.2 or later), 24 (24.15.0 or later), or 26 and later. You also need a GitHub token. If you use the [GitHub CLI](https://cli.github.com), log in with `gh auth login`, and headreel finds the token. For other ways, see [Command options](#command-options).
+
+To put the banner on your profile, add `headreel.gif` to your profile repository. Then add this line to its `README.md`:
+
+```markdown
+![My GitHub activity](headreel.gif)
+```
+
+## Keep it updated with the GitHub Action
+
+A banner that you make on your computer does not change. The Action makes a new banner every day.
+
+Your profile repository has the same name as your username, for example `octocat/octocat`. Do these steps in that repository.
+
+1. Create the file `.github/workflows/headreel.yml` with this content:
+
+   ```yaml
+   name: headreel
+
+   on:
+     schedule:
+       - cron: '0 0 * * *' # every day at 00:00 UTC
+     workflow_dispatch: # lets you run it from the Actions tab
+
+   permissions:
+     contents: write
+
+   jobs:
+     banner:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v7
+         - uses: arifszn/headreel@v1
+           with:
+             style: contribution-city
+             tagline: Senior Software Engineer · Distributed Systems
+             website: https://example.com
+   ```
+
+2. Open the **Actions** tab of the repository. Select **headreel**, then select **Run workflow**.
+3. Wait for the run to finish. The workflow adds `headreel.gif` to the repository.
+4. Add this line to your `README.md`:
+
+   ```markdown
+   ![My GitHub activity](headreel.gif)
+   ```
+
+> [!NOTE]
+> The workflow makes a commit only when the banner changes. Your contribution count changes most days, so expect about one commit each day.
+
+## Action inputs
+
+| Input            | Default                         | Description                                                        |
+| ---------------- | ------------------------------- | ------------------------------------------------------------------ |
+| `style`          | (required)                      | The banner style. See [Styles](#styles).                           |
+| `username`       | repository owner                | The GitHub user to show.                                           |
+| `tagline`        | empty                           | One line under your name. Empty means no tagline.                  |
+| `website`        | empty                           | Your website, for example `https://example.com`. Empty means none. |
+| `handle`         | empty                           | A handle, for styles that show one.                                |
+| `options`        | empty                           | Style settings, one `key: value` on each line.                     |
+| `output`         | `headreel.gif`                  | The path of the banner in your repository.                         |
+| `commit_to`      | the checked-out branch          | The branch that gets the banner.                                   |
+| `commit_message` | `chore: update headreel banner` | The commit message for each update.                                |
+| `token`          | `github.token`                  | The token that reads your contribution data.                       |
+
+Your name comes from your GitHub profile. If your profile has no name, the banner shows your username.
+
+## Styles
+
+### Contribution City
+
+`style: contribution-city`
+
+Each day of the last 12 months is one building. A taller building means more contributions on that day. A light beam moves across the city, and beacons glow on your busiest days.
+
+The banner shows your name, your tagline, your total contributions, and your website.
+
+| Option    | Default | Description                                        |
+| --------- | ------- | -------------------------------------------------- |
+| `beacons` | `8`     | The number of busiest days with a beacon, 0 to 10. |
+
+Example:
+
+```yaml
+- uses: arifszn/headreel@v1
+  with:
+    style: contribution-city
+    options: |
+      beacons: 5
+```
+
+## Command options
+
+| Option                 | Description                                           |
+| ---------------------- | ----------------------------------------------------- |
+| `--style <id>`         | The banner style (required). See [Styles](#styles).   |
+| `--user <login>`       | Your GitHub username (required).                      |
+| `--out <file>`         | Where to save the GIF. The default is `headreel.gif`. |
+| `--tagline <text>`     | One line under your name.                             |
+| `--website <url>`      | Your website.                                         |
+| `--handle <text>`      | A handle, for styles that show one.                   |
+| `--option <key=value>` | A style setting. Use it again for each setting.       |
+| `--config <file>`      | A JSON file with your settings.                       |
+| `--token <token>`      | A GitHub token. See the token order below.            |
+
+headreel needs a GitHub token to read your contributions. It looks for a token in this order:
+
+1. The `--token` option.
+2. The `GITHUB_TOKEN` environment variable.
+3. The [GitHub CLI](https://cli.github.com), if you are logged in with `gh auth login`.
+
+You can keep your settings in a JSON file:
+
+```json
+{
+  "style": "contribution-city",
+  "user": "octocat",
+  "tagline": "Open source maintainer",
+  "website": "https://example.com",
+  "options": { "beacons": 5 }
+}
+```
+
+```bash
+npx headreel --config headreel.json
+```
+
+Options on the command line replace the values in the file. To see all options, run `npx headreel --help`.
+
+## Troubleshooting
+
+**The workflow fails with "Permission denied" or a 403 error.**
+Make sure that the workflow file contains `permissions: contents: write`.
+
+**The workflow fails with "Could not resolve to a User".**
+Check the `username` input. It must be a GitHub username.
+
+**The command fails with "No GitHub token found".**
+Log in with `gh auth login`, or set the `GITHUB_TOKEN` environment variable.

package/assets/fonts/OFL-JetBrainsMono.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/OFL-SpaceGrotesk.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/cli/args.js

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+export const USAGE = `Usage: headreel --style <style> --user <login> [options]
+
+Renders an animated GitHub profile banner.
+
+Options:
+  --style <id>          Banner style (required). Available: {styles}
+  --user <login>        GitHub login (required unless --fixture is used)
+  --out <file>          Output GIF path (default: headreel.gif)
+  --tagline <text>      One line under your name
+  --website <url>       Website shown on the banner
+  --handle <text>       Handle shown on the banner, if the style uses it
+  --option <key=value>  Style option; repeat for more than one
+  --options <text>      Style options as "key: value" lines
+  --config <file>       JSON file with any of the settings above
+  --token <token>       GitHub token (default: GITHUB_TOKEN, then \`gh auth token\`)
+  --fixture <file>      Render from a saved data file instead of the GitHub API
+  -h, --help            Show this help
+  -v, --version         Show the version`;
+const configSchema = z
+    .object({
+    style: z.string(),
+    user: z.string(),
+    out: z.string(),
+    tagline: z.string(),
+    website: z.string(),
+    handle: z.string(),
+    fixture: z.string(),
+    options: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+})
+    .partial()
+    .strict();
+/** Parses "key: value" lines. Blank lines and lines starting with # are ignored. */
+export function parseOptionLines(text) {
+    const out = {};
+    for (const [i, raw] of text.split(/\r?\n/).entries()) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const sep = line.indexOf(':');
+        if (sep <= 0)
+            throw new Error(`Invalid option on line ${i + 1}: "${line}". Use "key: value".`);
+        out[line.slice(0, sep).trim()] = line.slice(sep + 1).trim();
+    }
+    return out;
+}
+function parseOptionPairs(pairs) {
+    const out = {};
+    for (const pair of pairs) {
+        const sep = pair.indexOf('=');
+        if (sep <= 0)
+            throw new Error(`Invalid --option "${pair}". Use key=value.`);
+        out[pair.slice(0, sep).trim()] = pair.slice(sep + 1).trim();
+    }
+    return out;
+}
+async function readConfig(path) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Cannot read config ${path}: ${err.message}`);
+    }
+    const parsed = configSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`Invalid config ${path}:\n${z.prettifyError(parsed.error)}`);
+    return parsed.data;
+}
+/** Treats empty strings as unset, so empty Action inputs fall through to defaults. */
+function value(v) {
+    const trimmed = v?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/** Resolves flags and the optional config file. Flags override config values. */
+export async function parseCommand(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            style: { type: 'string' },
+            user: { type: 'string' },
+            out: { type: 'string' },
+            tagline: { type: 'string' },
+            website: { type: 'string' },
+            handle: { type: 'string' },
+            option: { type: 'string', multiple: true },
+            options: { type: 'string' },
+            config: { type: 'string' },
+            token: { type: 'string' },
+            fixture: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+        strict: true,
+        allowPositionals: false,
+    });
+    if (values.help)
+        return { kind: 'help' };
+    if (values.version)
+        return { kind: 'version' };
+    const configPath = value(values.config);
+    const config = configPath ? await readConfig(configPath) : {};
+    const configOptions = Object.fromEntries(Object.entries(config.options ?? {}).map(([k, v]) => [k, String(v)]));
+    const style = value(values.style) ?? config.style;
+    if (!style)
+        throw new Error('Missing --style.');
+    const settings = {
+        style,
+        out: value(values.out) ?? config.out ?? 'headreel.gif',
+        options: {
+            ...configOptions,
+            ...parseOptionLines(values.options ?? ''),
+            ...parseOptionPairs(values.option ?? []),
+        },
+    };
+    const optional = {
+        user: value(values.user) ?? config.user,
+        tagline: value(values.tagline) ?? config.tagline,
+        website: value(values.website) ?? config.website,
+        handle: value(values.handle) ?? config.handle,
+        token: value(values.token),
+        fixture: value(values.fixture) ?? config.fixture,
+    };
+    for (const [key, v] of Object.entries(optional)) {
+        if (v)
+            settings[key] = v;
+    }
+    if (!settings.user && !settings.fixture)
+        throw new Error('Missing --user.');
+    return { kind: 'render', settings };
+}

package/dist/cli/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+process.exitCode = await run(process.argv.slice(2), {
+    log: (line) => console.log(line),
+    warn: (line) => console.error(line),
+    now: () => new Date(),
+});

package/dist/cli/run.js

@@ -0,0 +1,83 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { createGraphQLClient } from '../core/data/graphql.js';
+import { loadFixture } from '../core/data/fixture.js';
+import { fetchProfile } from '../core/data/profile.js';
+import { resolveToken } from '../core/data/token.js';
+import { parseOptions, renderBanner } from '../core/pipeline.js';
+import { styles } from '../styles/index.js';
+import { parseCommand, USAGE } from './args.js';
+const MiB = 1024 * 1024;
+/** GitHub warns on pushed files over 50 MiB and blocks files over 100 MiB. */
+const WARN_BYTES = 50 * MiB;
+const MAX_BYTES = 100 * MiB;
+async function version() {
+    const pkg = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+}
+async function render(settings, io) {
+    const style = styles[settings.style];
+    if (!style) {
+        throw new Error(`Unknown style "${settings.style}". Available: ${Object.keys(styles).join(', ')}.`);
+    }
+    if (extname(settings.out).toLowerCase() !== '.gif') {
+        throw new Error(`Output must be a .gif file, got "${settings.out}".`);
+    }
+    // Fail on bad options before any API call.
+    parseOptions(style, settings.options);
+    let login;
+    let name;
+    let data;
+    if (settings.fixture) {
+        const fixture = await loadFixture(settings.fixture, style.data.schema);
+        ({ login, name } = fixture.profile);
+        data = fixture.data;
+    }
+    else {
+        const client = createGraphQLClient({ token: resolveToken({ flag: settings.token }) });
+        const user = settings.user;
+        const [profile, fetched] = await Promise.all([
+            fetchProfile(client, user),
+            style.data.fetch(client, user, io.now()),
+        ]);
+        ({ login, name } = profile);
+        data = fetched;
+    }
+    const identity = { name };
+    if (settings.tagline)
+        identity.tagline = settings.tagline;
+    if (settings.website)
+        identity.website = settings.website;
+    if (settings.handle)
+        identity.handle = settings.handle;
+    const gif = await renderBanner(style, { login, data, identity, options: settings.options });
+    if (gif.length > MAX_BYTES) {
+        throw new Error(`Banner is ${(gif.length / MiB).toFixed(1)} MiB; GitHub rejects files over 100 MiB.`);
+    }
+    if (gif.length > WARN_BYTES) {
+        io.warn(`Banner is ${(gif.length / MiB).toFixed(1)} MiB; GitHub warns on files over 50 MiB.`);
+    }
+    await mkdir(dirname(settings.out), { recursive: true });
+    await writeFile(settings.out, gif);
+    io.log(`Wrote ${settings.out} (${(gif.length / MiB).toFixed(2)} MiB) for @${login}.`);
+}
+/** Runs the CLI and returns the process exit code. */
+export async function run(argv, io) {
+    try {
+        const command = await parseCommand(argv);
+        if (command.kind === 'help') {
+            io.log(USAGE.replace('{styles}', Object.keys(styles).join(', ')));
+        }
+        else if (command.kind === 'version') {
+            io.log(await version());
+        }
+        else {
+            await render(command.settings, io);
+        }
+        return 0;
+    }
+    catch (err) {
+        io.warn(`headreel: ${err.message}`);
+        return 1;
+    }
+}

package/dist/core/canvas.js

@@ -0,0 +1,2 @@
+/** Fixed banner size (SPEC decision 13). */
+export const CANVAS = { width: 1280, height: 400 };

package/dist/core/data/contributions.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+const QUERY = /* GraphQL */ `
+  query Contributions($login: String!, $from: DateTime!, $to: DateTime!) {
+    user(login: $login) {
+      contributionsCollection(from: $from, to: $to) {
+        contributionCalendar {
+          totalContributions
+          weeks {
+            contributionDays {
+              date
+              weekday
+              contributionCount
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+const daySchema = z.object({
+    /** YYYY-MM-DD */
+    date: z.iso.date(),
+    /** 0 = Sunday ... 6 = Saturday */
+    weekday: z.number().int().min(0).max(6),
+    count: z.number().int().min(0),
+});
+export const contributionsSchema = z.object({
+    /** First and last day of the window, YYYY-MM-DD, inclusive. */
+    from: z.iso.date(),
+    to: z.iso.date(),
+    total: z.number().int().min(0),
+    /** Calendar columns, oldest first. First and last weeks may be partial. */
+    weeks: z.array(z.array(daySchema)),
+});
+const DAY_MS = 86_400_000;
+/**
+ * The 365 days ending on `now` (UTC), matching GitHub's profile calendar.
+ * GitHub rejects spans over one year, so the window is 364 days back plus today.
+ */
+export function contributionWindow(now) {
+    const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    return {
+        from: new Date(today - 364 * DAY_MS).toISOString().slice(0, 10),
+        to: new Date(today).toISOString().slice(0, 10),
+    };
+}
+export async function fetchContributions(client, login, now) {
+    const { from, to } = contributionWindow(now);
+    const { user } = await client(QUERY, {
+        login,
+        from: `${from}T00:00:00Z`,
+        to: `${to}T23:59:59Z`,
+    });
+    const calendar = user.contributionsCollection.contributionCalendar;
+    return {
+        from,
+        to,
+        total: calendar.totalContributions,
+        weeks: calendar.weeks.map((week) => week.contributionDays
+            .map((d) => ({ date: d.date, weekday: d.weekday, count: d.contributionCount }))
+            .sort((a, b) => a.date.localeCompare(b.date))),
+    };
+}