feat(x2a): add x2a-list-modules MCP tool (#2838)

* feat(x2a): add x2a-list-modules MCP tool

Signed-off-by: Marek Libra <marek.libra@gmail.com>

* Add MCP tool output schema documentation

* Sanitize MCP tools output

* fix ISO time format

---------

Signed-off-by: Marek Libra <marek.libra@gmail.com>

Author: mareklibra

workspaces/x2a/.changeset/wet-tigers-try.md

@@ -0,0 +1,7 @@
+---
+'@red-hat-developer-hub/backstage-plugin-x2a-backend': patch
+'@red-hat-developer-hub/backstage-plugin-x2a-mcp-extras': patch
+'@red-hat-developer-hub/backstage-plugin-x2a-node': patch
+---
+
+Added x2a-list-modules MCP tool listing modules by projectId.

workspaces/x2a/app-config.yaml

@@ -121,6 +121,7 @@ auth:
         clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
         signIn:
           resolvers:
+            - resolver: emailMatchingUserEntityProfileEmail
             - resolver: usernameMatchingUserEntityName
     bitbucket:
       # Follow https://backstage.io/docs/auth/bitbucket/provider/

workspaces/x2a/plugins/x2a-backend/src/router/common.test.ts

@@ -29,8 +29,6 @@ import {
   isUserOfAdminViewPermission,
   isUserOfAdminWritePermission,
   isUserOfX2AUserPermission,
-  removeSensitiveFromJob,
-  UnsecureJob,
   useEnforceProjectPermissions,
   useEnforceX2APermissions,
 } from './common';
@@ -78,64 +76,6 @@ describe('common', () => {
     credentials: jest.fn().mockResolvedValue(mockCredentials.user(userRef)),
   });
 
-  describe('removeSensitiveFromJob', () => {
-    it('returns undefined when job is undefined', () => {
-      expect(removeSensitiveFromJob(undefined)).toBeUndefined();
-    });
-
-    it('returns undefined when job is null', () => {
-      expect(removeSensitiveFromJob(null as any)).toBeUndefined();
-    });
-
-    it('removes callbackToken from job', () => {
-      const job: UnsecureJob = {
-        id: 'job-1',
-        projectId: 'proj-1',
-        moduleId: 'module-1',
-        phase: 'init' as const,
-        status: 'pending' as const,
-        callbackToken: 'secret-token',
-        startedAt: new Date(),
-        k8sJobName: 'job-1',
-      };
-      const result = removeSensitiveFromJob(job);
-      expect(result).toBeDefined();
-      expect(result).not.toHaveProperty('callbackToken');
-      expect(result).toMatchObject({
-        id: 'job-1',
-        projectId: 'proj-1',
-        phase: 'init',
-        status: 'pending',
-      });
-    });
-
-    it('returns job unchanged when it has no callbackToken', () => {
-      const job = {
-        id: 'job-1',
-        projectId: 'proj-1',
-        moduleId: 'module-1',
-        phase: 'analyze' as const,
-        status: 'success' as const,
-        startedAt: new Date(),
-        k8sJobName: 'job-1',
-      };
-      const result = removeSensitiveFromJob(job);
-      expect(result).toEqual(job);
-    });
-
-    it('does not mutate the original job object', () => {
-      const job = {
-        id: 'job-1',
-        callbackToken: 'secret',
-        startedAt: new Date(),
-        k8sJobName: 'job-1',
-      } as UnsecureJob;
-      const result = removeSensitiveFromJob(job);
-      expect(job).toHaveProperty('callbackToken', 'secret');
-      expect(result).not.toHaveProperty('callbackToken');
-    });
-  });
-
   describe('getGroupsOfUser', () => {
     it('returns empty array when user entity is null', async () => {
       const catalog = getCatalogMock();

workspaces/x2a/plugins/x2a-backend/src/router/common.ts

@@ -27,7 +27,6 @@ import {
   BasicPermission,
 } from '@backstage/plugin-permission-common';
 import {
-  Job,
   Project,
   x2aAdminViewPermission,
   x2aAdminWritePermission,
@@ -47,8 +46,11 @@ export {
   getGroupsOfUser,
   reconcileJobStatus,
   generateCallbackToken,
+  removeSensitiveFromJob,
 } from '@red-hat-developer-hub/backstage-plugin-x2a-node';
 
+export type { UnsecureJob } from '@red-hat-developer-hub/backstage-plugin-x2a-node';
+
 /**
  * Checks if the user has the x2aAdminViewPermission.
  */
@@ -232,14 +234,3 @@ export const useEnforceProjectPermissions = async (
     canWriteAll,
   };
 };
-
-export type UnsecureJob = Job & { callbackToken?: string };
-export const removeSensitiveFromJob = (job?: UnsecureJob): Job | undefined => {
-  if (!job) {
-    return undefined;
-  }
-
-  const newJob: UnsecureJob = { ...job };
-  delete newJob.callbackToken;
-  return newJob;
-};

workspaces/x2a/plugins/x2a-backend/src/router/modules.ts

@@ -18,33 +18,17 @@ import { z } from 'zod';
 import express from 'express';
 import { InputError, NotFoundError } from '@backstage/errors';
 
-import type { Module } from '@red-hat-developer-hub/backstage-plugin-x2a-common';
-
 import type { RouterDeps } from './types';
 import {
   generateCallbackToken,
   reconcileJobStatus,
   useEnforceProjectPermissions,
 } from './common';
-import { calculateModuleStatus } from '../services/X2ADatabaseService/status';
-
-/**
- * Reconcile any pending/running phase jobs on a module against K8s state.
- * Mutates the module in-place and returns it.
- */
-async function reconcileModuleJobs(
-  module: Module,
-  deps: Pick<RouterDeps, 'kubeService' | 'x2aDatabase' | 'logger'>,
-): Promise<Module> {
-  const phases = ['analyze', 'migrate', 'publish'] as const;
-  for (const phase of phases) {
-    const job = module[phase];
-    if (job && ['pending', 'running'].includes(job.status)) {
-      module[phase] = await reconcileJobStatus(job, deps);
-    }
-  }
-  return module;
-}
+import {
+  calculateModuleStatus,
+  listModulesWithReconciledStatuses,
+  reconcileModuleJobs,
+} from '@red-hat-developer-hub/backstage-plugin-x2a-node';
 
 export function registerModuleRoutes(
   router: express.Router,
@@ -76,26 +60,12 @@ export function registerModuleRoutes(
       catalog,
     });
 
-    // List modules
     const modules = await x2aDatabase.listModules({ projectId });
-
-    // Reconcile any pending/running jobs against K8s
-    await Promise.all(
-      modules.map(m =>
-        reconcileModuleJobs(m, { kubeService, x2aDatabase, logger }),
-      ),
-    );
-
-    // Recalculate status for each module after reconciliation
-    for (const m of modules) {
-      const { status, errorDetails } = calculateModuleStatus({
-        analyze: m.analyze,
-        migrate: m.migrate,
-        publish: m.publish,
-      });
-      m.status = status;
-      m.errorDetails = errorDetails;
-    }
+    await listModulesWithReconciledStatuses(modules, {
+      kubeService,
+      x2aDatabase,
+      logger,
+    });
 
     res.json(modules);
   });

workspaces/x2a/plugins/x2a-backend/src/services/X2ADatabaseService/index.ts

@@ -39,6 +39,8 @@ import {
 } from '@red-hat-developer-hub/backstage-plugin-x2a-common';
 import {
   x2aDatabaseServiceRef,
+  removeSensitiveFromJob,
+  calculateModuleStatus,
   type X2ADatabaseServiceApi,
   type CreateJobInput,
 } from '@red-hat-developer-hub/backstage-plugin-x2a-node';
@@ -47,11 +49,10 @@ import { JobOperations } from './jobOperations';
 import { ModuleOperations } from './moduleOperations';
 import { ProjectOperations } from './projectOperations';
 import { isNonDbSortField } from './queryHelpers';
-import { removeSensitiveFromJob } from '../../router/common';
 import { MAX_CONCURRENT_ENRICHMENT_JOBS } from '../constants';
 import { migrate } from '../dbMigrate';
 import { maxConcurrency } from '../../utils';
-import { calculateModuleStatus, calculateProjectStatus } from './status';
+import { calculateProjectStatus } from './projectStatus';
 
 export class X2ADatabaseService implements X2ADatabaseServiceApi {
   readonly #logger: LoggerService;