@forgeportal/plugin-github-insights 1.3.0

package/src/api-client.ts

@@ -0,0 +1,120 @@
+import type {
+  GHRepo,
+  GHPR,
+  GHCommit,
+  GHContributor,
+  GHWorkflowRun,
+  GitHubInsightsConfig,
+  CacheEntry,
+} from './types.js';
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Minimal GitHub REST API client with in-process TTL cache.
+ * Uses the standard GitHub token from config (falls back to SCM_GITHUB_TOKEN).
+ * Respects Retry-After headers to avoid secondary rate limit penalties.
+ */
+export class GitHubInsightsClient {
+  private readonly token:   string;
+  private readonly ttlMs:   number;
+  private readonly cache    = new Map<string, CacheEntry<unknown>>();
+
+  constructor(config: GitHubInsightsConfig) {
+    this.token = config.token;
+    this.ttlMs = config.cacheTTLSeconds * 1000;
+  }
+
+  private async get<T>(path: string): Promise<T> {
+    const cacheKey = path;
+
+    if (this.ttlMs > 0) {
+      const hit = this.cache.get(cacheKey);
+      if (hit && Date.now() < hit.expiresAt) return hit.data as T;
+    }
+
+    const res = await (fetch as (url: string, init: Record<string, unknown>) => Promise<Response>)(
+      `${GITHUB_API}${path}`,
+      {
+        headers: {
+          Authorization:        `Bearer ${this.token}`,
+          Accept:               'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      },
+    );
+
+    if (res.status === 403 || res.status === 429) {
+      const retryAfter = res.headers.get('Retry-After');
+      throw new Error(
+        `GitHub rate limit hit (${res.status}).${retryAfter ? ` Retry after ${retryAfter}s.` : ''}`,
+      );
+    }
+
+    if (res.status === 404) {
+      throw new Error(`GitHub resource not found: ${path}`);
+    }
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new Error(`GitHub API ${res.status}: ${body || res.statusText}`);
+    }
+
+    const data = await res.json() as T;
+
+    if (this.ttlMs > 0) {
+      this.cache.set(cacheKey, { data, expiresAt: Date.now() + this.ttlMs });
+    }
+
+    return data;
+  }
+
+  /** GET /repos/{owner}/{repo} */
+  getRepo(owner: string, repo: string): Promise<GHRepo> {
+    return this.get<GHRepo>(`/repos/${owner}/${repo}`);
+  }
+
+  /** GET /repos/{owner}/{repo}/pulls?state=open&per_page=25 */
+  getOpenPRs(owner: string, repo: string): Promise<GHPR[]> {
+    return this.get<GHPR[]>(
+      `/repos/${owner}/${repo}/pulls?state=open&per_page=25&sort=updated&direction=desc`,
+    );
+  }
+
+  /** GET /repos/{owner}/{repo}/commits?per_page=20 */
+  getRecentCommits(owner: string, repo: string): Promise<GHCommit[]> {
+    return this.get<GHCommit[]>(
+      `/repos/${owner}/${repo}/commits?per_page=20`,
+    );
+  }
+
+  /** GET /repos/{owner}/{repo}/contributors?per_page=10&anon=false */
+  getContributors(owner: string, repo: string): Promise<GHContributor[]> {
+    return this.get<GHContributor[]>(
+      `/repos/${owner}/${repo}/contributors?per_page=10&anon=false`,
+    );
+  }
+
+  /** GET /repos/{owner}/{repo}/actions/runs?per_page=10 */
+  getWorkflowRuns(owner: string, repo: string): Promise<{ workflow_runs: GHWorkflowRun[] }> {
+    return this.get<{ workflow_runs: GHWorkflowRun[] }>(
+      `/repos/${owner}/${repo}/actions/runs?per_page=10`,
+    );
+  }
+}
+
+/**
+ * Parses a GitHub repo URL and returns { owner, repo } or null.
+ * Handles: https://github.com/owner/repo and github.com/owner/repo
+ */
+export function parseGitHubUrl(url: string): { owner: string; repo: string } | null {
+  try {
+    const parsed = new URL(url.startsWith('http') ? url : `https://${url}`);
+    if (!parsed.hostname.endsWith('github.com')) return null;
+    const parts = parsed.pathname.replace(/^\//, '').replace(/\.git$/, '').split('/');
+    if (parts.length < 2 || !parts[0] || !parts[1]) return null;
+    return { owner: parts[0], repo: parts[1] };
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+import type { ForgeBackendPluginSDK } from '@forgeportal/plugin-sdk';
+import type { GitHubInsightsConfig } from './types.js';
+import { createRoutes } from './routes.js';
+
+/**
+ * Backend entry point for the GitHub Insights plugin.
+ * Called by the ForgePortal plugin loader at startup.
+ *
+ * Configuration (forgeportal.yaml -> plugins.github-insights.config):
+ *   cacheTTLSeconds: number (default: 300)
+ *
+ * Token resolution (first match wins):
+ *   1. FORGEPORTAL_PLUGIN_GITHUB_INSIGHTS_TOKEN env var (dedicated token)
+ *   2. SCM_GITHUB_TOKEN env var (shared SCM token)
+ */
+export function registerBackendPlugin(sdk: ForgeBackendPluginSDK): void {
+  const token =
+    process.env['FORGEPORTAL_PLUGIN_GITHUB_INSIGHTS_TOKEN'] ??
+    process.env['SCM_GITHUB_TOKEN'] ??
+    '';
+
+  const cacheTTLSeconds = sdk.config.get<number>('cacheTTLSeconds') ?? 300;
+
+  if (!token) {
+    sdk.logger.warn(
+      'github-insights plugin: no GitHub token found. ' +
+      'Set FORGEPORTAL_PLUGIN_GITHUB_INSIGHTS_TOKEN or SCM_GITHUB_TOKEN. ' +
+      'API calls will fail for private repos.',
+    );
+  } else {
+    sdk.logger.info(
+      `github-insights plugin: ready (cache TTL: ${cacheTTLSeconds}s)`,
+    );
+  }
+
+  const config: GitHubInsightsConfig = { token, cacheTTLSeconds };
+
+  sdk.registerBackendRoute({
+    path:    '',
+    handler: createRoutes(config),
+  });
+}

package/src/routes.ts

@@ -0,0 +1,151 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { GitHubInsightsClient } from './api-client.js';
+import type { GitHubInsightsConfig } from './types.js';
+
+interface EntityParams  { entityId: string }
+interface RepoQuery     { owner: string; repo: string }
+
+/**
+ * Creates Fastify route handlers for the GitHub Insights plugin.
+ * All routes mounted under /api/v1/plugins/github-insights/ by the plugin loader.
+ *
+ * Routes:
+ *   GET  entities/:entityId/overview      — repo info + open PR count + latest commit
+ *   GET  entities/:entityId/prs           — paginated open PRs
+ *   GET  entities/:entityId/commits       — last 20 commits
+ *   GET  entities/:entityId/contributors  — top contributors
+ */
+export function createRoutes(config: GitHubInsightsConfig) {
+  const client = new GitHubInsightsClient(config);
+
+  return async function handler(fastify: FastifyInstance): Promise<void> {
+    function requireOwnerRepo(
+      request: FastifyRequest<{ Params: EntityParams; Querystring: RepoQuery }>,
+      reply: FastifyReply,
+    ): { owner: string; repo: string } | null {
+      const { owner, repo } = request.query;
+      if (!owner || !repo) {
+        void reply.status(400).send({
+          error:   'Bad Request',
+          message: 'Query parameters "owner" and "repo" are required.',
+        });
+        return null;
+      }
+      return { owner, repo };
+    }
+
+    /**
+     * GET /entities/:entityId/overview?owner=&repo=
+     * Returns: repo metadata + open PR count + latest commit.
+     */
+    fastify.get(
+      'entities/:entityId/overview',
+      async (
+        request: FastifyRequest<{ Params: EntityParams; Querystring: RepoQuery }>,
+        reply:   FastifyReply,
+      ) => {
+        const ref = requireOwnerRepo(request, reply);
+        if (!ref) return;
+
+        try {
+          const [repoData, prs, commits] = await Promise.allSettled([
+            client.getRepo(ref.owner, ref.repo),
+            client.getOpenPRs(ref.owner, ref.repo),
+            client.getRecentCommits(ref.owner, ref.repo),
+          ]);
+
+          const repo        = repoData.status === 'fulfilled' ? repoData.value : null;
+          const openPRCount = prs.status === 'fulfilled' ? prs.value.length : 0;
+          const latestCommit = commits.status === 'fulfilled' ? (commits.value[0] ?? null) : null;
+
+          if (!repo) {
+            const err = repoData.status === 'rejected' ? repoData.reason : new Error('Unknown');
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('not found')) {
+              return reply.status(404).send({ error: 'Not Found', message });
+            }
+            return reply.status(502).send({ error: 'Bad Gateway', message });
+          }
+
+          return reply.send({ data: { repo, openPRCount, latestCommit } });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'github-insights: getOverview failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * GET /entities/:entityId/prs?owner=&repo=
+     * Returns up to 25 open pull requests.
+     */
+    fastify.get(
+      'entities/:entityId/prs',
+      async (
+        request: FastifyRequest<{ Params: EntityParams; Querystring: RepoQuery }>,
+        reply:   FastifyReply,
+      ) => {
+        const ref = requireOwnerRepo(request, reply);
+        if (!ref) return;
+
+        try {
+          const prs = await client.getOpenPRs(ref.owner, ref.repo);
+          return reply.send({ data: prs });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'github-insights: getPRs failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * GET /entities/:entityId/commits?owner=&repo=
+     * Returns the last 20 commits.
+     */
+    fastify.get(
+      'entities/:entityId/commits',
+      async (
+        request: FastifyRequest<{ Params: EntityParams; Querystring: RepoQuery }>,
+        reply:   FastifyReply,
+      ) => {
+        const ref = requireOwnerRepo(request, reply);
+        if (!ref) return;
+
+        try {
+          const commits = await client.getRecentCommits(ref.owner, ref.repo);
+          return reply.send({ data: commits });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'github-insights: getCommits failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * GET /entities/:entityId/contributors?owner=&repo=
+     * Returns top contributors by commit count.
+     */
+    fastify.get(
+      'entities/:entityId/contributors',
+      async (
+        request: FastifyRequest<{ Params: EntityParams; Querystring: RepoQuery }>,
+        reply:   FastifyReply,
+      ) => {
+        const ref = requireOwnerRepo(request, reply);
+        if (!ref) return;
+
+        try {
+          const contributors = await client.getContributors(ref.owner, ref.repo);
+          return reply.send({ data: contributors.slice(0, 5) });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'github-insights: getContributors failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+  };
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+// ─── GitHub API response shapes (minimal subset) ────────────────────────────
+
+export interface GHRepo {
+  full_name:        string;
+  description:      string | null;
+  default_branch:   string;
+  language:         string | null;
+  stargazers_count: number;
+  forks_count:      number;
+  open_issues_count: number;
+  html_url:         string;
+  private:          boolean;
+}
+
+export interface GHPRLabel { name: string; color: string }
+
+export interface GHPR {
+  number:     number;
+  title:      string;
+  html_url:   string;
+  state:      string;
+  created_at: string;
+  updated_at: string;
+  user:       { login: string; avatar_url: string };
+  labels:     GHPRLabel[];
+  draft:      boolean;
+  head:       { ref: string };
+  base:       { ref: string };
+}
+
+export interface GHCommitAuthor {
+  name:  string;
+  email: string;
+  date:  string;
+}
+
+export interface GHCommit {
+  sha:       string;
+  html_url:  string;
+  commit: {
+    message:   string;
+    author:    GHCommitAuthor;
+    committer: GHCommitAuthor;
+  };
+  author:    { login: string; avatar_url: string } | null;
+}
+
+export interface GHContributor {
+  login:        string;
+  avatar_url:   string;
+  html_url:     string;
+  contributions: number;
+}
+
+export interface GHWorkflowRun {
+  id:           number;
+  name:         string | null;
+  display_title: string;
+  status:       string | null;
+  conclusion:   string | null;
+  html_url:     string;
+  created_at:   string;
+  head_branch:  string | null;
+}
+
+// ─── Aggregated overview ─────────────────────────────────────────────────────
+
+export interface GitHubOverview {
+  repo:           GHRepo;
+  openPRCount:    number;
+  latestCommit:   GHCommit | null;
+}
+
+// ─── Plugin config ────────────────────────────────────────────────────────────
+
+export interface GitHubInsightsConfig {
+  token:          string;
+  cacheTTLSeconds: number;
+}
+
+// ─── Cache entry ─────────────────────────────────────────────────────────────
+
+export interface CacheEntry<T> {
+  data:      T;
+  expiresAt: number;
+}

package/src/ui.ts

@@ -0,0 +1,18 @@
+import type { ForgePluginSDK } from '@forgeportal/plugin-sdk';
+import { GitHubInsightsTab } from './GitHubInsightsTab.js';
+
+/**
+ * UI entry point for the GitHub Insights plugin.
+ * Called by the ForgePortal UI shell at startup.
+ *
+ * Registration in apps/ui/src/plugins/index.ts:
+ *   import { registerPlugin as registerGitHubInsights } from '@forgeportal/plugin-github-insights/ui';
+ *   registerPluginById('github-insights', registerGitHubInsights);
+ */
+export function registerPlugin(sdk: ForgePluginSDK): void {
+  sdk.registerEntityTab({
+    id:        'github-insights-tab',
+    title:     'GitHub',
+    component: GitHubInsightsTab,
+  });
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir":         "dist",
+    "rootDir":        "src",
+    "jsx":            "react-jsx",
+    "declaration":    true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+}