@rmdes/indiekit-endpoint-github 1.2.6 → 1.2.8

package/index.js

@@ -2,6 +2,8 @@ import express from "express";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 
+import { waitForReady } from "@rmdes/indiekit-startup-gate";
+
 import { activityController } from "./lib/controllers/activity.js";
 import { changelogController } from "./lib/controllers/changelog.js";
 import { commitsController } from "./lib/controllers/commits.js";
@@ -10,6 +12,8 @@ import { dashboardController } from "./lib/controllers/dashboard.js";
 import { featuredController } from "./lib/controllers/featured.js";
 import { starsController } from "./lib/controllers/stars.js";
 import { starredController } from "./lib/controllers/starred.js";
+import { reposController } from "./lib/controllers/repos.js";
+import { GITHUB_BLOCKS } from "./lib/blocks.js";
 
 // Module-level routers (matching Indiekit's endpoint pattern)
 const protectedRouter = express.Router();
@@ -64,6 +68,10 @@ export default class GitHubEndpoint {
     };
   }
 
+  get blocks() {
+    return GITHUB_BLOCKS;
+  }
+
   /**
    * Protected routes (require authentication)
    * HTML pages for admin dashboard
@@ -97,6 +105,7 @@ export default class GitHubEndpoint {
     publicRouter.get("/api/changelog", changelogController.api);
     publicRouter.get("/api/starred/all", starredController.all);
     publicRouter.get("/api/starred/recent", starredController.recent);
+    publicRouter.get("/api/repos", reposController.api);
 
     return publicRouter;
   }
@@ -115,13 +124,22 @@ export default class GitHubEndpoint {
 
     // Start background sync for starred repos (if token + DB available)
     if (this.options.token && Indiekit.database) {
-      import("./lib/starred-sync.js")
-        .then(({ startStarredSync }) => {
-          startStarredSync(Indiekit, this.options);
-        })
-        .catch((error) => {
-          console.error("[GitHub Stars] Sync scheduler failed to start:", error.message);
-        });
+      this._stopGate = waitForReady(
+        () => {
+          import("./lib/starred-sync.js")
+            .then(({ startStarredSync }) => {
+              startStarredSync(Indiekit, this.options);
+            })
+            .catch((error) => {
+              console.error("[GitHub Stars] Sync scheduler failed to start:", error.message);
+            });
+        },
+        { label: "GitHub" },
+      );
     }
   }
+
+  destroy() {
+    this._stopGate?.();
+  }
 }

package/lib/blocks.js

@@ -0,0 +1,36 @@
+/**
+ * GitHub v2 block declaration (Phase 7c — plugin block ownership).
+ *
+ * The `github-repos` sidebar widget was a site-config BUILTIN_BLOCKS seed
+ * (requiresPlugin null). Declaring it here makes site-config's scanPlugins stamp
+ * `sourcePlugin` → `requiresPlugin` ("GitHub activity endpoint"), so the block is
+ * properly plugin-gated (theme ENDPOINT_SLUGS maps it to the `github` loadout
+ * slug). scanPlugins precedence is `built-in < plugin blocks`, so this entry
+ * OVERWRITES the builtin seed where the plugin is loaded; the seed itself is
+ * removed from site-config in Phase 7d alongside the legacy-map bridge.
+ *
+ * `source:"api"` is honest: the widget fetches the plugin's JSON API LIVE
+ * client-side (commits/featured/contributions/repos) — no rebuild needed for
+ * fresh data. As of 7c the Repos tab also routes through this plugin
+ * (/api/repos) instead of hitting api.github.com directly from the browser, so
+ * the plugin is the single source of truth. Bespoke template: the theme owns
+ * `components/widgets/github-repos.njk` + `js/widgets/github-repos.js`.
+ *
+ * @module lib/blocks
+ */
+
+/** @type {Array<object>} */
+export const GITHUB_BLOCKS = [
+  {
+    id: "github-repos",
+    version: 1,
+    label: "GitHub Projects",
+    description: "GitHub repositories and activity",
+    icon: "github",
+    category: "social",
+    placement: { regions: ["sidebar"], surfaces: ["homepage"] },
+    multiple: false,
+    data: { source: "api" },
+    schema: { type: "object", additionalProperties: false, properties: {} },
+  },
+];

package/lib/controllers/activity.js

@@ -109,16 +109,16 @@ export const activityController = {
           activity = utils.extractRepoActivity(events, username);
         }
       } catch (apiError) {
-        console.error("[Activity] API error:", apiError.message);
-        return response.json({ activity: [], error: "GitHub API temporarily unavailable" });
+        return response
+          .status(apiError.status || 500)
+          .json({ error: apiError.message });
       }
 
       activity = activity.slice(0, limits.activity);
 
       response.json({ activity });
     } catch (error) {
-      console.error("[Activity] Controller error:", error.message);
-      response.json({ activity: [], error: "GitHub API temporarily unavailable" });
+      next(error);
     }
   },
 };

package/lib/controllers/changelog.js

@@ -206,16 +206,7 @@ export const changelogController = {
         generatedAt: new Date().toISOString(),
       });
     } catch (error) {
-      console.error("[Changelog] API error:", error.message);
-      response.json({
-        commits: [],
-        categories: {},
-        commitCategories: {},
-        totalCommits: 0,
-        days: daysValue || 30,
-        generatedAt: new Date().toISOString(),
-        error: "GitHub API temporarily unavailable",
-      });
+      next(error);
     }
   },
 };

package/lib/controllers/repos.js

@@ -0,0 +1,57 @@
+import { GitHubClient } from "../github-client.js";
+
+/**
+ * Public JSON API for the user's own repositories (Phase 7c).
+ *
+ * The sidebar widget's "Repos" tab previously fetched api.github.com DIRECTLY
+ * from the browser (sort=updated, type=owner) and filtered fork/private
+ * client-side — bypassing this plugin, so the GitHub token never protected the
+ * call (rate limits, no auth). This endpoint moves that fetch server-side: the
+ * plugin (GitHubClient + token + 15-min cache) is now the single source of truth.
+ *
+ * Returns a SLIM shape using the RAW GitHub field names the widget template
+ * already reads (html_url/name/description/language/stargazers_count/updated_at),
+ * so github-repos.njk needs no change — only the widget's fetch URL moves to
+ * /api/repos.
+ * @type {import("express").RequestHandler}
+ */
+export const reposController = {
+  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 raw = [];
+      try {
+        // Fetch extra (×2) so the fork/private filter still yields enough.
+        raw = await client.getUserRepos(username, (limits.repos || 10) * 2, "updated");
+      } catch (apiError) {
+        return response
+          .status(apiError.status || 500)
+          .json({ error: apiError.message });
+      }
+
+      const repos = (Array.isArray(raw) ? raw : [])
+        .filter((r) => r && !r.fork && !r.private)
+        .slice(0, limits.repos || 10)
+        .map((r) => ({
+          name: r.name,
+          html_url: r.html_url,
+          description: r.description,
+          language: r.language,
+          stargazers_count: r.stargazers_count,
+          updated_at: r.updated_at,
+        }));
+
+      response.json({ repos });
+    } catch (error) {
+      next(error);
+    }
+  },
+};

package/lib/controllers/stars.js

@@ -69,16 +69,16 @@ export const starsController = {
       try {
         starred = await client.getUserStarred(username, limits.stars);
       } catch (apiError) {
-        console.error("[Stars] API error:", apiError.message);
-        return response.json({ stars: [], error: "GitHub API temporarily unavailable" });
+        return response
+          .status(apiError.status || 500)
+          .json({ error: apiError.message });
       }
 
       const stars = utils.formatStarred(starred);
 
       response.json({ stars });
     } catch (error) {
-      console.error("[Stars] Controller error:", error.message);
-      response.json({ stars: [], error: "GitHub API temporarily unavailable" });
+      next(error);
     }
   },
 };

package/lib/github-client.js

@@ -22,7 +22,7 @@ export class GitHubClient {
   async fetch(endpoint) {
     const url = `${BASE_URL}${endpoint}`;
 
-    // Check cache first — return fresh data immediately
+    // Check cache first
     const cached = this.cache.get(url);
     if (cached && Date.now() - cached.timestamp < this.cacheTtl) {
       return cached.data;
@@ -37,40 +37,28 @@ export class GitHubClient {
       headers.Authorization = `Bearer ${this.token}`;
     }
 
-    try {
-      const response = await fetch(url, { headers });
-
-      if (!response.ok) {
-        // Only use fromFetch for JSON error responses; GitHub sometimes returns
-        // HTML error pages (e.g., 502 Bad Gateway) which cause SyntaxError noise
-        const contentType = response.headers.get("content-type") || "";
-        if (contentType.includes("json")) {
-          throw await IndiekitError.fromFetch(response);
-        }
-
-        throw new IndiekitError(response.statusText, {
-          status: response.status,
-          code: response.statusText,
-        });
+    const response = await fetch(url, { headers });
+
+    if (!response.ok) {
+      // Only use fromFetch for JSON error responses; GitHub sometimes returns
+      // HTML error pages (e.g., 502 Bad Gateway) which cause SyntaxError noise
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("json")) {
+        throw await IndiekitError.fromFetch(response);
       }
 
-      const data = await response.json();
+      throw new IndiekitError(response.statusText, {
+        status: response.status,
+        code: response.statusText,
+      });
+    }
 
-      // Cache result
-      this.cache.set(url, { data, timestamp: Date.now() });
+    const data = await response.json();
 
-      return data;
-    } catch (error) {
-      // Stale-while-error: if we have stale cached data, return it
-      if (cached) {
-        console.warn(
-          `[GitHub] API error for ${endpoint}: ${error.message}. Serving stale cache (age: ${Math.round((Date.now() - cached.timestamp) / 60_000)}min)`,
-        );
-        return cached.data;
-      }
+    // Cache result
+    this.cache.set(url, { data, timestamp: Date.now() });
 
-      throw error;
-    }
+    return data;
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmdes/indiekit-endpoint-github",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "GitHub activity endpoint for Indiekit. Display commits, stars, contributions, and featured repositories.",
   "keywords": [
     "indiekit",
@@ -40,6 +40,7 @@
   ],
   "dependencies": {
     "@indiekit/error": "^1.0.0-beta.25",
+    "@rmdes/indiekit-startup-gate": "^1.0.0",
     "express": "^5.0.0"
   },
   "peerDependencies": {