@rmdes/indiekit-endpoint-github 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# @rmdes/indiekit-endpoint-github
+
+A GitHub activity endpoint plugin for [Indiekit](https://getindiekit.com). Display your GitHub commits, stars, contributions, and featured repositories in your Indiekit admin dashboard, with a public JSON API for use in your static site.
+
+## Features
+
+- **Featured Projects**: Showcase specific repositories with recent commits
+- **Recent Commits**: Display your latest commits across repositories
+- **Starred Repositories**: Show repos you've recently starred
+- **PRs & Issues**: Track your open source contributions
+- **Public API**: JSON endpoints for integrating with static site generators
+
+## Installation
+
+```bash
+npm install @rmdes/indiekit-endpoint-github
+```
+
+## Configuration
+
+Add the plugin to your Indiekit configuration:
+
+```javascript
+export default {
+  plugins: [
+    "@rmdes/indiekit-endpoint-github",
+    // ... other plugins
+  ],
+
+  "@rmdes/indiekit-endpoint-github": {
+    // Required: Your GitHub username
+    username: "your-username",
+
+    // Optional: GitHub personal access token for higher rate limits
+    // and access to private repos (set via GITHUB_TOKEN env var)
+    token: process.env.GITHUB_TOKEN,
+
+    // Optional: Mount path for the endpoint (default: "/github")
+    mountPath: "/github-api",
+
+    // Optional: Cache duration in milliseconds (default: 15 minutes)
+    cacheTtl: 900_000,
+
+    // Optional: Limits for each section
+    limits: {
+      commits: 10,
+      stars: 20,
+      contributions: 10,
+      repos: 10,
+    },
+
+    // Optional: Featured repositories to showcase with commits
+    featuredRepos: [
+      "owner/repo-name",
+      "owner/another-repo",
+    ],
+  },
+};
+```
+
+## Endpoints
+
+### Protected (require authentication)
+
+- `GET /github-api/` - Dashboard view with all sections
+- `GET /github-api/commits` - Recent commits page
+- `GET /github-api/stars` - Starred repositories page
+- `GET /github-api/contributions` - PRs & Issues page
+- `GET /github-api/activity` - Activity feed page
+
+### Public API (no authentication)
+
+- `GET /github-api/api/commits` - JSON: Recent commits
+- `GET /github-api/api/stars` - JSON: Starred repositories
+- `GET /github-api/api/activity` - JSON: Activity feed
+- `GET /github-api/api/featured` - JSON: Featured repositories with commits
+
+## Using the Public API
+
+The public API endpoints return JSON and can be used by your static site generator (Eleventy, Hugo, etc.) to display GitHub activity on your public site.
+
+Example Eleventy data file:
+
+```javascript
+import EleventyFetch from "@11ty/eleventy-fetch";
+
+export default async function() {
+  const url = "https://your-site.com/github-api/api/featured";
+
+  const data = await EleventyFetch(url, {
+    duration: "15m",
+    type: "json",
+  });
+
+  return data.featured || [];
+}
+```
+
+## Environment Variables
+
+- `GITHUB_TOKEN` - Optional GitHub personal access token for:
+  - Higher API rate limits (5000/hour vs 60/hour)
+  - Access to private repository information
+
+## License
+
+MIT

package/assets/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96">
+  <path fill="#24292f" d="M0 0h96v96H0z"/>
+  <path fill="#fff" d="M48 16c-17.7 0-32 14.3-32 32 0 14.1 9.2 26.1 21.9 30.4 1.6.3 2.2-.7 2.2-1.5v-5.3c-8.9 1.9-10.8-4.3-10.8-4.3-1.5-3.7-3.6-4.7-3.6-4.7-2.9-2 .2-2 .2-2 3.2.2 4.9 3.3 4.9 3.3 2.9 4.9 7.5 3.5 9.3 2.7.3-2.1 1.1-3.5 2-4.3-7.1-.8-14.6-3.6-14.6-15.8 0-3.5 1.2-6.3 3.3-8.6-.3-.8-1.4-4.1.3-8.5 0 0 2.7-.9 8.8 3.3 2.6-.7 5.3-1.1 8-1.1s5.5.4 8 1.1c6.1-4.1 8.8-3.3 8.8-3.3 1.7 4.4.7 7.7.3 8.5 2 2.3 3.3 5.1 3.3 8.6 0 12.3-7.5 15-14.6 15.8 1.1 1 2.2 2.9 2.2 5.9v8.7c0 .8.6 1.8 2.2 1.5C70.8 74.1 80 62.1 80 48c0-17.7-14.3-32-32-32z"/>
+</svg>

package/assets/styles.css

@@ -0,0 +1,245 @@
+/* GitHub endpoint styles */
+
+/* Section spacing */
+.github-section {
+  margin-block-end: var(--space-xl);
+}
+
+.github-section h2 {
+  margin-block-end: var(--space-m);
+}
+
+.github-profile {
+  align-items: center;
+  display: flex;
+  gap: var(--space-m);
+  margin-block-end: var(--space-l);
+}
+
+.github-profile__avatar {
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.github-profile__info {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2xs);
+}
+
+.github-profile__info p {
+  color: var(--color-text-secondary);
+  margin: 0;
+}
+
+.github-profile__link {
+  font-size: var(--step--1);
+}
+
+/* GitHub list */
+.github-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-s);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.github-list--compact {
+  gap: var(--space-2xs);
+}
+
+.github-list--grid {
+  display: grid;
+  gap: var(--space-m);
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+}
+
+.github-list__item {
+  align-items: baseline;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-xs);
+}
+
+/* Activity styles */
+.github-activity {
+  align-items: center;
+}
+
+.github-activity__avatar {
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.github-activity__content {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-xs);
+}
+
+.github-activity__detail {
+  color: var(--color-text-secondary);
+}
+
+/* Commit styles (in main list) */
+.github-commit__message {
+  flex: 1;
+  min-inline-size: 200px;
+}
+
+/* Commit list styles (inside featured repos) */
+.github-commit-list {
+  display: flex;
+  flex-direction: column;
+  font-size: var(--step--1);
+  gap: var(--space-xs);
+  list-style: none;
+  margin: var(--space-s) 0 0;
+  padding: 0;
+}
+
+.github-commit-list code {
+  background: var(--color-background);
+  border-radius: var(--radius-s);
+  padding: var(--space-3xs) var(--space-2xs);
+}
+
+.github-commit-list li {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-xs);
+}
+
+.github-commit-list small {
+  color: var(--color-text-secondary);
+}
+
+/* Featured repos styles */
+.github-featured {
+  display: grid;
+  gap: var(--space-l);
+  grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+  margin-block-end: var(--space-xl);
+}
+
+.github-featured__commits {
+  border-block-start: 1px solid var(--color-border);
+  margin-block-start: var(--space-s);
+  padding-block-start: var(--space-s);
+}
+
+.github-featured__commits summary {
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  font-size: var(--step--1);
+}
+
+.github-featured__desc {
+  color: var(--color-text-secondary);
+  font-size: var(--step--1);
+  margin: 0 0 var(--space-s);
+}
+
+.github-featured__meta {
+  color: var(--color-text-secondary);
+  display: flex;
+  font-size: var(--step--1);
+  gap: var(--space-s);
+  margin-block-end: var(--space-s);
+}
+
+.github-featured__name {
+  font-size: var(--step-0);
+  margin: 0 0 var(--space-xs);
+}
+
+.github-featured__repo {
+  background: var(--color-offset);
+  border-radius: var(--radius-m);
+  padding: var(--space-m);
+}
+
+/* Language indicator */
+.github-lang {
+  margin-inline-end: var(--space-xs);
+}
+
+/* Metadata */
+.github-meta {
+  color: var(--color-text-secondary);
+  font-size: var(--step--1);
+}
+
+/* Repo card styles */
+.github-repo {
+  flex-direction: column;
+}
+
+.github-repo__desc {
+  color: var(--color-text-secondary);
+  font-size: var(--step--1);
+  margin: 0;
+}
+
+.github-repo__forks,
+.github-repo__stars {
+  margin-inline-start: var(--space-xs);
+}
+
+.github-repo__name {
+  font-weight: var(--font-weight-semibold);
+}
+
+/* SHA badge styles */
+.github-sha {
+  background: var(--color-offset);
+  border-radius: var(--radius-s);
+  font-size: var(--step--1);
+  padding-block: var(--space-3xs);
+  padding-inline: var(--space-2xs);
+}
+
+/* Star styles */
+.github-star {
+  flex-direction: column;
+}
+
+.github-star__count {
+  margin-inline-start: var(--space-xs);
+}
+
+.github-star__desc {
+  color: var(--color-text-secondary);
+  font-size: var(--step--1);
+  margin: 0;
+}
+
+.github-star__name {
+  font-weight: var(--font-weight-semibold);
+}
+
+/*
+ * Link styles - grouped by specificity (ascending)
+ * Non-pseudo selectors first, then pseudo selectors
+ */
+
+/* Specificity: 0,1,1 (one class, one element) */
+.github-featured__name a {
+  text-decoration: none;
+}
+
+.github-sha a {
+  text-decoration: none;
+}
+
+/* Specificity: 0,1,2 (one class, two elements) */
+.github-commit-list code a {
+  text-decoration: none;
+}
+
+/* Pseudo-class selectors */
+.github-featured__name a:hover {
+  text-decoration: underline;
+}

package/includes/@indiekit-endpoint-github-commits.njk

@@ -0,0 +1,13 @@
+{# Commits partial for embedding in other templates #}
+{% if commits and commits.length > 0 %}
+<ul class="github-list github-list--compact">
+  {% for commit in commits %}
+  {% if loop.index <= 5 %}
+  <li class="github-list__item">
+    <code class="github-sha"><a href="{{ commit.url }}" target="_blank" rel="noopener">{{ commit.sha }}</a></code>
+    <span class="github-commit__message">{{ commit.message }}</span>
+  </li>
+  {% endif %}
+  {% endfor %}
+</ul>
+{% endif %}

package/includes/@indiekit-endpoint-github-stars.njk

@@ -0,0 +1,13 @@
+{# Stars partial for embedding in other templates #}
+{% if stars and stars.length > 0 %}
+<ul class="github-list github-list--compact">
+  {% for star in stars %}
+  {% if loop.index <= 5 %}
+  <li class="github-list__item">
+    <a href="{{ star.url }}" target="_blank" rel="noopener">{{ star.name }}</a>
+    <small class="github-meta">{{ star.stars }} stars</small>
+  </li>
+  {% endif %}
+  {% endfor %}
+</ul>
+{% endif %}

package/includes/@indiekit-endpoint-github-widget.njk

@@ -0,0 +1,12 @@
+{% call widget({
+  title: __("github.title")
+}) %}
+  <p class="prose">{{ __("github.widget.description") }}</p>
+  <div class="button-grid">
+    {{ button({
+      classes: "button--secondary-on-offset",
+      href: application.githubEndpoint or "/github-api",
+      text: __("github.widget.view")
+    }) }}
+  </div>
+{% endcall %}

package/index.js

@@ -0,0 +1,98 @@
+import express from "express";
+
+import { activityController } from "./lib/controllers/activity.js";
+import { commitsController } from "./lib/controllers/commits.js";
+import { contributionsController } from "./lib/controllers/contributions.js";
+import { dashboardController } from "./lib/controllers/dashboard.js";
+import { featuredController } from "./lib/controllers/featured.js";
+import { starsController } from "./lib/controllers/stars.js";
+
+// Module-level routers (matching Indiekit's endpoint pattern)
+const protectedRouter = express.Router();
+const publicRouter = express.Router();
+
+const defaults = {
+  mountPath: "/github",
+  username: "",
+  token: process.env.GITHUB_TOKEN,
+  cacheTtl: 900_000, // 15 minutes in ms
+  limits: {
+    commits: 10,
+    stars: 20,
+    contributions: 10,
+    activity: 20,
+    repos: 10,
+  },
+  repos: [], // Empty = all repos, or specify ['owner/repo', ...] for filtering activity
+  featuredRepos: [], // Repos to showcase with commits, e.g. ['owner/repo', ...]
+};
+
+export default class GitHubEndpoint {
+  name = "GitHub activity endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get environment() {
+    return ["GITHUB_TOKEN"];
+  }
+
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "github.title",
+      requiresDatabase: false,
+    };
+  }
+
+  get shortcutItems() {
+    return {
+      url: this.options.mountPath,
+      name: "github.activity",
+      iconName: "syndicate",
+      requiresDatabase: false,
+    };
+  }
+
+  /**
+   * Protected routes (require authentication)
+   * HTML pages for admin dashboard
+   */
+  get routes() {
+    // Dashboard
+    protectedRouter.get("/", dashboardController.get);
+
+    // Individual sections (HTML pages)
+    protectedRouter.get("/commits", commitsController.get);
+    protectedRouter.get("/stars", starsController.get);
+    protectedRouter.get("/contributions", contributionsController.get);
+    protectedRouter.get("/activity", activityController.get);
+    protectedRouter.get("/featured", featuredController.get);
+
+    return protectedRouter;
+  }
+
+  /**
+   * Public routes (no authentication required)
+   * JSON API endpoints for Eleventy widgets
+   */
+  get routesPublic() {
+    // JSON API for widgets - publicly accessible
+    publicRouter.get("/api/commits", commitsController.api);
+    publicRouter.get("/api/stars", starsController.api);
+    publicRouter.get("/api/activity", activityController.api);
+    publicRouter.get("/api/featured", featuredController.api);
+
+    return publicRouter;
+  }
+
+  init(Indiekit) {
+    Indiekit.addEndpoint(this);
+
+    // Store GitHub config in application for controller access
+    Indiekit.config.application.githubConfig = this.options;
+    Indiekit.config.application.githubEndpoint = this.mountPath;
+  }
+}

package/lib/controllers/activity.js

@@ -0,0 +1,124 @@
+import { GitHubClient } from "../github-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Display activity on user's repositories from others
+ * @type {import("express").RequestHandler}
+ */
+export const activityController = {
+  async get(request, response, next) {
+    try {
+      const { username, token, cacheTtl, limits, repos } =
+        request.app.locals.application.githubConfig;
+
+      if (!username) {
+        return response.render("activity", {
+          title: response.locals.__("github.activity.title"),
+          error: { message: response.locals.__("github.error.noUsername") },
+        });
+      }
+
+      const client = new GitHubClient({ token, cacheTtl });
+
+      let activity = [];
+
+      try {
+        if (repos.length > 0) {
+          // Fetch events for specific repos
+          const repoEventPromises = repos.map(async (repoPath) => {
+            const [owner, repo] = repoPath.split("/");
+            try {
+              return await client.getRepoEvents(owner, repo, 30);
+            } catch {
+              return [];
+            }
+          });
+
+          const repoEvents = await Promise.all(repoEventPromises);
+          const allEvents = repoEvents.flat();
+          activity = utils.extractRepoActivity(allEvents, username);
+        } else {
+          // Use received events (events on user's repos)
+          const events = await client.fetch(
+            `/users/${username}/received_events?per_page=${limits.activity * 2}`,
+          );
+          activity = utils.extractRepoActivity(events, username);
+        }
+      } catch (apiError) {
+        console.error("GitHub API error:", apiError);
+        return response.render("activity", {
+          title: response.locals.__("github.activity.title"),
+          actions: [],
+          parent: {
+            href: request.baseUrl,
+            text: response.locals.__("github.title"),
+          },
+          error: { message: apiError.message || "Failed to fetch activity" },
+        });
+      }
+
+      activity = activity.slice(0, limits.activity);
+
+      response.render("activity", {
+        title: response.locals.__("github.activity.title"),
+        actions: [],
+        parent: {
+          href: request.baseUrl,
+          text: response.locals.__("github.title"),
+        },
+        activity,
+        username,
+        mountPath: request.baseUrl,
+      });
+    } catch (error) {
+      next(error);
+    }
+  },
+
+  async api(request, response, next) {
+    try {
+      const { username, token, cacheTtl, limits, repos } =
+        request.app.locals.application.githubConfig;
+
+      if (!username) {
+        return response.status(400).json({ error: "No username configured" });
+      }
+
+      const client = new GitHubClient({ token, cacheTtl });
+
+      let activity = [];
+
+      try {
+        if (repos.length > 0) {
+          const repoEventPromises = repos.map(async (repoPath) => {
+            const [owner, repo] = repoPath.split("/");
+            try {
+              return await client.getRepoEvents(owner, repo, 20);
+            } catch {
+              return [];
+            }
+          });
+
+          const repoEvents = await Promise.all(repoEventPromises);
+          const allEvents = repoEvents.flat();
+          activity = utils.extractRepoActivity(allEvents, username);
+        } else {
+          const events = await client.fetch(
+            `/users/${username}/received_events?per_page=${limits.activity}`,
+          );
+          activity = utils.extractRepoActivity(events, username);
+        }
+      } catch (apiError) {
+        return response
+          .status(apiError.status || 500)
+          .json({ error: apiError.message });
+      }
+
+      activity = activity.slice(0, limits.activity);
+
+      response.json({ activity });
+    } catch (error) {
+      next(error);
+    }
+  },
+};

package/lib/controllers/commits.js

@@ -0,0 +1,84 @@
+import { GitHubClient } from "../github-client.js";
+import * as utils from "../utils.js";
+
+/**
+ * Display commits list
+ * @type {import("express").RequestHandler}
+ */
+export const commitsController = {
+  async get(request, response, next) {
+    try {
+      const { username, token, cacheTtl, limits } =
+        request.app.locals.application.githubConfig;
+
+      if (!username) {
+        return response.render("commits", {
+          title: response.locals.__("github.commits.title"),
+          error: { message: response.locals.__("github.error.noUsername") },
+        });
+      }
+
+      const client = new GitHubClient({ token, cacheTtl });
+
+      let events = [];
+      try {
+        events = await client.getUserEvents(username, 100);
+      } catch (apiError) {
+        console.error("GitHub API error:", apiError);
+        return response.render("commits", {
+          title: response.locals.__("github.commits.title"),
+          actions: [],
+          parent: {
+            href: request.baseUrl,
+            text: response.locals.__("github.title"),
+          },
+          error: { message: apiError.message || "Failed to fetch commits" },
+        });
+      }
+
+      const commits = utils.extractCommits(events).slice(0, limits.commits * 3);
+
+      response.render("commits", {
+        title: response.locals.__("github.commits.title"),
+        actions: [],
+        parent: {
+          href: request.baseUrl,
+          text: response.locals.__("github.title"),
+        },
+        commits,
+        username,
+        mountPath: request.baseUrl,
+      });
+    } catch (error) {
+      next(error);
+    }
+  },
+
+  async api(request, response, next) {
+    try {
+      const { username, token, cacheTtl, limits } =
+        request.app.locals.application.githubConfig;
+
+      if (!username) {
+        return response.status(400).json({ error: "No username configured" });
+      }
+
+      const client = new GitHubClient({ token, cacheTtl });
+
+      let events = [];
+      try {
+        events = await client.getUserEvents(username, 50);
+      } catch (apiError) {
+        return response
+          .status(apiError.status || 500)
+          .json({ error: apiError.message });
+      }
+
+      const commits = utils.extractCommits(events).slice(0, limits.commits);
+
+      response.json({ commits });
+    } catch (error) {
+      next(error);
+    }
+  },
+};