@evergreen-dev/backstage-plugin-backend 0.0.0-stage → 0.1.0

package/config.d.ts

@@ -0,0 +1,13 @@
+export interface Config {
+  /**
+   * Evergreen developer-portal integration.
+   * The backend only reads a published `evergreen.portal.v1` export; it never scans.
+   */
+  evergreen?: {
+    /**
+     * HTTP(S) URL or absolute filesystem path of the portal export JSON
+     * produced by `evergreen export --format portal`.
+     */
+    portalExportSource: string;
+  };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@evergreen-dev/backstage-plugin-backend",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Backstage backend module that serves Evergreen portal-export lifecycle summaries. Does not scan repositories.",
+  "license": "Apache-2.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "backstage": {
+    "role": "backend-plugin",
+    "pluginId": "evergreen",
+    "pluginPackages": [
+      "@evergreen-dev/backstage-plugin",
+      "@evergreen-dev/backstage-plugin-backend",
+      "@evergreen-dev/backstage-plugin-common"
+    ]
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean"
+  },
+  "dependencies": {
+    "@evergreen-dev/backstage-plugin-common": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@backstage/backend-plugin-api": "^1.0.0",
+    "@backstage/config": "^1.0.0",
+    "@backstage/errors": "^1.0.0",
+    "express": "^4.18.0 || ^5.0.0",
+    "express-promise-router": "^4.1.0"
+  },
+  "devDependencies": {
+    "@backstage/backend-plugin-api": "^1.0.0",
+    "@backstage/cli": "^0.30.0",
+    "@backstage/config": "^1.0.0",
+    "@backstage/errors": "^1.0.0",
+    "@types/express": "^4.17.21",
+    "express": "^4.21.0",
+    "express-promise-router": "^4.1.1"
+  },
+  "files": [
+    "src",
+    "config.d.ts"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { evergreenPlugin as default } from "./plugin";
+export { createRouter } from "./router";
+export { loadPortalCatalog } from "./loadPortal";
+export {
+  PORTAL_SCHEMA_VERSION,
+  SERVICE_PATH_ANNOTATION,
+  findService,
+  parsePortalCatalog,
+} from "@evergreen-dev/backstage-plugin-common";

package/src/loadPortal.ts

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+import { parsePortalCatalog, type PortalCatalog } from "@evergreen-dev/backstage-plugin-common";
+
+/**
+ * Load an `evergreen.portal.v1` catalog from a URL or a local file path
+ * (CI artifact on disk, object-store URL, or Pages URL).
+ */
+export async function loadPortalCatalog(
+  source: string,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<PortalCatalog> {
+  const trimmed = source.trim();
+  if (!trimmed) {
+    throw new Error("evergreen.portalExportSource must be a non-empty string");
+  }
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    if (typeof fetchImpl !== "function") {
+      throw new Error("fetch is not available to load a remote portal export");
+    }
+    const response = await fetchImpl(trimmed);
+    if (!response.ok) {
+      throw new Error(`failed to fetch portal export from ${trimmed}: HTTP ${response.status}`);
+    }
+    return parsePortalCatalog(await response.json());
+  }
+
+  const fileUrl = trimmed.startsWith("file:") ? trimmed : pathToFileURL(trimmed).href;
+  const text = await readFile(new URL(fileUrl), "utf8");
+  return parsePortalCatalog(JSON.parse(text));
+}

package/src/plugin.ts

@@ -0,0 +1,37 @@
+import {
+  coreServices,
+  createBackendPlugin,
+} from "@backstage/backend-plugin-api";
+
+import { createRouter } from "./router";
+
+/**
+ * Backend plugin that exposes the Evergreen portal export to the frontend card.
+ * Reads a published `evergreen.portal.v1` JSON file or URL. Never scans a repository.
+ */
+export const evergreenPlugin = createBackendPlugin({
+  pluginId: "evergreen",
+  register(env) {
+    env.registerInit({
+      deps: {
+        httpRouter: coreServices.httpRouter,
+        logger: coreServices.logger,
+        config: coreServices.rootConfig,
+      },
+      async init({ httpRouter, logger, config }) {
+        const portalExportSource = config.getString("evergreen.portalExportSource");
+        httpRouter.use(
+          await createRouter({
+            logger,
+            portalExportSource,
+          }),
+        );
+        httpRouter.addAuthPolicy({
+          path: "/health",
+          allow: "unauthenticated",
+        });
+        logger.info(`Evergreen portal export source: ${portalExportSource}`);
+      },
+    });
+  },
+});

package/src/router.ts

@@ -0,0 +1,53 @@
+import type { LoggerService } from "@backstage/backend-plugin-api";
+import { InputError, NotFoundError } from "@backstage/errors";
+import express from "express";
+import Router from "express-promise-router";
+
+import { findService, type PortalCatalog } from "@evergreen-dev/backstage-plugin-common";
+import { loadPortalCatalog } from "./loadPortal";
+
+export interface RouterOptions {
+  logger: LoggerService;
+  /** Absolute path or http(s) URL of the portal export. */
+  portalExportSource: string;
+  /** Optional fetch override for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+export async function createRouter(options: RouterOptions): Promise<express.Router> {
+  const { logger, portalExportSource, fetchImpl } = options;
+  const router = Router();
+  router.use(express.json());
+
+  async function catalog(): Promise<PortalCatalog> {
+    try {
+      return await loadPortalCatalog(portalExportSource, fetchImpl);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`Failed to load Evergreen portal export: ${message}`);
+      throw error;
+    }
+  }
+
+  router.get("/health", (_req, res) => {
+    res.json({ status: "ok" });
+  });
+
+  router.get("/catalog", async (_req, res) => {
+    res.json(await catalog());
+  });
+
+  router.get("/services", async (req, res) => {
+    const servicePath = typeof req.query.path === "string" ? req.query.path : undefined;
+    if (!servicePath || servicePath.trim() === "") {
+      throw new InputError("query parameter path is required");
+    }
+    const match = findService(await catalog(), servicePath);
+    if (!match) {
+      throw new NotFoundError(`no Evergreen portal service matches path ${JSON.stringify(servicePath)}`);
+    }
+    res.json(match);
+  });
+
+  return router;
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+export type {
+  PortalCatalog,
+  PortalService,
+  PortalSeverityCounts,
+  Severity,
+} from "@evergreen-dev/backstage-plugin-common";
+
+export {
+  PORTAL_SCHEMA_VERSION,
+  SERVICE_PATH_ANNOTATION,
+  SEVERITIES,
+  findService,
+  highestSeverity,
+  parsePortalCatalog,
+  totalFindings,
+} from "@evergreen-dev/backstage-plugin-common";

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.