feat: add GitHub repository showcase with proxy and fallback data

Author: markhazleton

.documentation/specs/001-github-repo-showcase/spec.md

@@ -11,7 +11,7 @@ required_gates: checklist, analyze, critic
 
 **Feature Branch**: `001-github-repo-showcase`  
 **Created**: 2026-04-16  
-**Status**: Draft  
+**Status**: In Progress  
 **Input**: User description: "Create a MarkHazleton GitHub Repository app that showcases data from the generated repositories dataset in github-stats-spark, with strong Bootstrap flair and a world-class presentation similar in spirit to the existing Projects and Articles experiences."
 
 ## Rationale Summary

.documentation/specs/001-github-repo-showcase/tasks.md

@@ -22,10 +22,10 @@ description: "Executable task list for the GitHub Repository Showcase feature"
 
 **Purpose**: Prepare the repository showcase file structure and feature-specific test surfaces.
 
-- [ ] T001 Create repository model and service scaffolds in `src/models/Repository.ts` and `src/services/RepositoryService.ts`
-- [ ] T002 [P] Create repository page and route test scaffolds in `src/components/Repositories.tsx` and `tests/integration/repositories/RepositoriesPage.test.tsx`
-- [ ] T003 [P] Create repository proxy scaffolds in `api/proxy-repositories/function.json`, `api/proxy-repositories/index.js`, and `api/proxy-repositories/package.json`
-- [ ] T004 [P] Create repository data and test scaffolds in `src/data/repositories.json`, `tests/unit/models/Repository.test.ts`, `tests/unit/services/RepositoryService.test.ts`, and `tests/contract/repositories/repositoryFeed.contract.test.ts`
+- [X] T001 Create repository model and service scaffolds in `src/models/Repository.ts` and `src/services/RepositoryService.ts`
+- [X] T002 [P] Create repository page and route test scaffolds in `src/components/Repositories.tsx` and `tests/integration/repositories/RepositoriesPage.test.tsx`
+- [X] T003 [P] Create repository proxy scaffolds in `api/proxy-repositories/function.json`, `api/proxy-repositories/index.js`, and `api/proxy-repositories/package.json`
+- [X] T004 [P] Create repository data and test scaffolds in `src/data/repositories.json`, `tests/unit/models/Repository.test.ts`, `tests/unit/services/RepositoryService.test.ts`, and `tests/contract/repositories/repositoryFeed.contract.test.ts`
 
 ---
 
@@ -35,16 +35,15 @@ description: "Executable task list for the GitHub Repository Showcase feature"
 
 **⚠️ CRITICAL**: No user story work should start until this phase is complete.
 
-- [ ] T005 Implement Zod schemas and typed repository feed exports in `src/models/Repository.ts`
-- [ ] T005 Implement Zod schemas and typed repository feed exports, including explicit `FeedMetadata` fields for freshness and schema compatibility, in `src/models/Repository.ts`
-- [ ] T006 [P] Add the embedded repository fallback snapshot in `src/data/repositories.json`
-- [ ] T007 Implement repository fetch, validation, cache metadata, private-repository exclusion, curated-first featured selection with automatic fallback ranking, and fallback mapping in `src/services/RepositoryService.ts`
-- [ ] T008 [P] Add the development proxy route for `/api/repositories` in `vite.config.ts`
-- [ ] T009 Implement the production repository proxy in `api/proxy-repositories/index.js`
-- [ ] T010 [P] Configure the repository proxy function metadata and dependencies in `api/proxy-repositories/function.json` and `api/proxy-repositories/package.json`
-- [ ] T011 Add contract coverage for the feed shape, explicit metadata fields, and minimum required repository fields in `tests/contract/repositories/repositoryFeed.contract.test.ts`
-- [ ] T012 Add unit coverage for schema parsing, view-model derivation, and invalid feed rejection in `tests/unit/models/Repository.test.ts`
-- [ ] T013 Add unit coverage for remote, cache, and local fallback behavior, private-repository exclusion, and retry-ready failure handling in `tests/unit/services/RepositoryService.test.ts`
+- [X] T005 Implement Zod schemas and typed repository feed exports, including explicit `FeedMetadata` fields for freshness and schema compatibility, in `src/models/Repository.ts`
+- [X] T006 [P] Add the embedded repository fallback snapshot in `src/data/repositories.json`
+- [X] T007 Implement repository fetch, validation, cache metadata, private-repository exclusion, curated-first featured selection with automatic fallback ranking, and fallback mapping in `src/services/RepositoryService.ts`
+- [X] T008 [P] Add the development proxy route for `/api/repositories` in `vite.config.ts`
+- [X] T009 Implement the production repository proxy in `api/proxy-repositories/index.js`
+- [X] T010 [P] Configure the repository proxy function metadata and dependencies in `api/proxy-repositories/function.json` and `api/proxy-repositories/package.json`
+- [X] T011 Add contract coverage for the feed shape, explicit metadata fields, and minimum required repository fields in `tests/contract/repositories/repositoryFeed.contract.test.ts`
+- [X] T012 Add unit coverage for schema parsing, view-model derivation, and invalid feed rejection in `tests/unit/models/Repository.test.ts`
+- [X] T013 Add unit coverage for remote, cache, and local fallback behavior, private-repository exclusion, and retry-ready failure handling in `tests/unit/services/RepositoryService.test.ts`
 
 **Checkpoint**: Repository data can be loaded, validated, cached, and served through both development and production integration paths.
 
@@ -58,15 +57,15 @@ description: "Executable task list for the GitHub Repository Showcase feature"
 
 ### Tests for User Story 1
 
-- [ ] T014 [P] [US1] Add route and first-render integration coverage for hero metrics, recent activity context, and featured spotlight rendering in `tests/integration/repositories/RepositoriesPage.test.tsx`
+- [X] T014 [P] [US1] Add route and first-render integration coverage for hero metrics, recent activity context, and featured spotlight rendering in `tests/integration/repositories/RepositoriesPage.test.tsx`
 
 ### Implementation for User Story 1
 
-- [ ] T015 [US1] Register the lazy-loaded repository route in `src/App.tsx`
-- [ ] T016 [US1] Add the repository showcase entry to the Apps navigation and generated sitemap route list in `src/components/Header.tsx` and `src/utils/generateSitemap.ts`
-- [ ] T017 [US1] Implement the repository page shell, hero metrics, recent activity summary, source-status messaging, retry-capable error state, and featured spotlight section in `src/components/Repositories.tsx`
-- [ ] T018 [US1] Connect the repository page to `RepositoryService` and render the base repository collection in `src/components/Repositories.tsx`
-- [ ] T019 [US1] Add page-level SEO copy and accessible section structure in `src/components/Repositories.tsx`
+- [X] T015 [US1] Register the lazy-loaded repository route in `src/App.tsx`
+- [X] T016 [US1] Add the repository showcase entry to the Apps navigation and generated sitemap route list in `src/components/Header.tsx` and `src/utils/generateSitemap.ts`
+- [X] T017 [US1] Implement the repository page shell, hero metrics, recent activity summary, source-status messaging, retry-capable error state, and featured spotlight section in `src/components/Repositories.tsx`
+- [X] T018 [US1] Connect the repository page to `RepositoryService` and render the base repository collection in `src/components/Repositories.tsx`
+- [X] T019 [US1] Add page-level SEO copy and accessible section structure in `src/components/Repositories.tsx`
 
 **Checkpoint**: User Story 1 is independently functional and demoable as the MVP.
 
@@ -205,6 +204,10 @@ Task: "T026 [US3] Enrich repository cards with summary text, activity badges, an
 - The requirements checklist exists and is complete.
 - No existing `analyze.md`, `critic.md`, or other gate findings were present when tasks were generated.
 
+## Gate Acknowledgements
+
+- 2026-04-17: User approved proceeding with implementation despite unresolved `analyze` and `critic` gate artifacts.
+
 ---
 
 ## Notes

.gitignore

@@ -45,6 +45,7 @@ local.settings.json
 
 # Build artifacts
 /build
+/.build
 /.next
 /out
 coverage/

api/proxy-repositories/function.json

@@ -0,0 +1,16 @@
+{
+  "bindings": [
+    {
+      "authLevel": "anonymous",
+      "type": "httpTrigger",
+      "direction": "in",
+      "name": "req",
+      "methods": ["get", "options"]
+    },
+    {
+      "type": "http",
+      "direction": "out",
+      "name": "res"
+    }
+  ]
+}

api/proxy-repositories/index.js

@@ -0,0 +1,69 @@
+const axios = require("axios");
+
+const ALLOWED_ORIGINS = [
+  "https://bootstrapspark.markhazleton.com",
+  "https://markhazleton.github.io",
+  "http://localhost:3000",
+  "http://127.0.0.1:3000",
+];
+
+const REPOSITORY_SOURCE_URL = "https://markhazleton.com/repositories.json";
+
+module.exports = async function (context, req) {
+  context.log("Processing repositories proxy request");
+
+  const origin = req.headers.origin || req.headers.referer;
+  const allowedOrigin = ALLOWED_ORIGINS.includes(origin) ? origin : ALLOWED_ORIGINS[0];
+
+  const baseHeaders = {
+    "Access-Control-Allow-Origin": allowedOrigin,
+    "Access-Control-Allow-Methods": "GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+    "Access-Control-Allow-Credentials": "false",
+    "Content-Type": "application/json",
+  };
+
+  if (req.method === "OPTIONS") {
+    context.res = {
+      status: 200,
+      headers: baseHeaders,
+    };
+    return;
+  }
+
+  try {
+    const response = await axios.get(REPOSITORY_SOURCE_URL, {
+      timeout: 8000,
+      headers: {
+        "User-Agent": "BootstrapSpark/1.0 Repository-Proxy",
+        Accept: "application/json",
+      },
+    });
+
+    const payload = response.data;
+    const hasMinimumShape =
+      payload && payload.profile && Array.isArray(payload.repositories) && payload.metadata;
+
+    if (!hasMinimumShape) {
+      throw new Error("Repository feed does not contain profile/repositories/metadata");
+    }
+
+    context.res = {
+      status: 200,
+      headers: baseHeaders,
+      body: payload,
+    };
+  } catch (error) {
+    context.log.error("Error fetching repositories:", error.message);
+
+    context.res = {
+      status: 502,
+      headers: baseHeaders,
+      body: {
+        error: "Failed to retrieve repository feed",
+        message: error.message,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+};

api/proxy-repositories/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "proxy-repositories",
+  "version": "1.0.0",
+  "description": "Azure Function to proxy repository showcase feed requests",
+  "main": "index.js",
+  "dependencies": {
+    "axios": "^1.15.0"
+  }
+}

package.json

@@ -8,14 +8,15 @@
     "dev": "concurrently \"vite\" \"npm run watch-css\"",
     "dev:swa": "swa start",
     "dev:debug": "vite --debug",
-    "build": "npm run clean && npm run build-css && tsc -b && npm run generate-seo-files && vite build --mode production",
+    "build": "npm run clean && npm run build-css && npm run sync:repositories-data && tsc -b && npm run generate-seo-files && vite build --mode production",
     "build:analyze": "npm run build && npx vite-bundle-analyzer docs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "preview": "vite preview",
     "preview:swa": "swa start docs --run \"vite preview\"",
     "clean": "rimraf docs && rimraf node_modules/.vite",
     "sync:bootswatch-themes": "node ./scripts/sync-bootswatch-themes.mjs",
+    "sync:repositories-data": "node ./scripts/sync-repositories-data.mjs",
     "build-css": "sass --load-path=node_modules --quiet-deps src/scss/styles.scss src/css/styles.css",
     "watch-css": "sass --load-path=node_modules --quiet-deps --watch src/scss/styles.scss:src/css/styles.css",
     "generate-sitemap": "node --import tsx ./src/utils/generateSitemap.ts",

scripts/sync-repositories-data.mjs

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const workspaceRoot = process.cwd();
+const outputPath = path.join(workspaceRoot, ".build", "data", "repositories.json");
+const sourceUrl = process.env.REPOSITORIES_FEED_URL || "https://markhazleton.com/repositories.json";
+
+const isValidFeed = (payload) => {
+  if (!payload || typeof payload !== "object") {
+    return false;
+  }
+
+  if (!payload.profile || typeof payload.profile !== "object") {
+    return false;
+  }
+
+  if (!Array.isArray(payload.repositories)) {
+    return false;
+  }
+
+  if (!payload.metadata || typeof payload.metadata !== "object") {
+    return false;
+  }
+
+  return true;
+};
+
+const run = async () => {
+  console.log(`Syncing repositories data from ${sourceUrl}`);
+
+  const response = await fetch(sourceUrl, {
+    headers: {
+      Accept: "application/json",
+      "Cache-Control": "no-cache",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch repositories feed: ${response.status} ${response.statusText}`);
+  }
+
+  const payload = await response.json();
+
+  if (!isValidFeed(payload)) {
+    throw new Error("Fetched repositories feed is missing required profile/repositories/metadata shape.");
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  console.log(`Wrote fresh repositories build artifact to ${outputPath}`);
+};
+
+run().catch((error) => {
+  console.error("Repository sync failed:", error.message);
+  process.exit(1);
+});

src/App.tsx

@@ -19,6 +19,7 @@ import "./utils/imageUtils";
 const Hero = lazy(() => import("./components/Hero"));
 const About = lazy(() => import("./components/About"));
 const Projects = lazy(() => import("./components/Projects"));
+const Repositories = lazy(() => import("./components/Repositories"));
 const Articles = lazy(() => import("./components/Articles"));
 const Joke = lazy(() => import("./components/Joke"));
 const WeatherForecast = lazy(() => import("./components/WeatherForecast"));
@@ -64,6 +65,7 @@ const AppWithVersionCheck: React.FC = () => {
                   <Route path="/" element={<Hero />} />
                   <Route path="/about" element={<About />} />
                   <Route path="/projects" element={<Projects />} />
+                  <Route path="/repositories" element={<Repositories />} />
                   <Route path="/joke" element={<Joke />} />
                   <Route path="/articles" element={<Articles />} />
                   <Route path="/weather" element={<WeatherForecast />} />

src/components/Header.tsx

@@ -3,6 +3,7 @@ import {
   House,
   Person,
   Briefcase,
+  Github,
   JournalText,
   EmojiLaughing,
   Cloud,
@@ -39,6 +40,7 @@ const Header: React.FC = () => {
 
   const isAppsActive =
     location.pathname === "/projects" ||
+    location.pathname === "/repositories" ||
     location.pathname === "/articles" ||
     location.pathname === "/joke" ||
     location.pathname === "/weather" ||
@@ -113,6 +115,15 @@ const Header: React.FC = () => {
                       <Briefcase className="me-2" /> Projects
                     </Link>
                   </li>
+                  <li>
+                    <Link
+                      className="dropdown-item"
+                      to="/repositories"
+                      aria-label="Repositories page"
+                    >
+                      <Github className="me-2" /> Repositories
+                    </Link>
+                  </li>
                   <li>
                     <Link className="dropdown-item" to="/articles" aria-label="Articles page">
                       <JournalText className="me-2" /> Articles