@nospt/plugin-dev-ai-hub-backend 0.1.0

package/src/plugin.ts

@@ -0,0 +1,84 @@
+import {
+  coreServices,
+  createBackendPlugin,
+} from '@backstage/backend-plugin-api';
+import {
+  devAiHubProviderExtensionPoint,
+  type AiAssetProvider,
+} from '@nospt/plugin-dev-ai-hub-node';
+import { AiAssetStore } from './database/AiAssetStore';
+import { AiAssetSyncService } from './service/AiAssetSyncService';
+import { createRouter } from './router';
+import type { ProviderConfig } from './types';
+
+export const devAiHubPlugin = createBackendPlugin({
+  pluginId: 'dev-ai-hub',
+  register(env) {
+    const externalProviders: AiAssetProvider[] = [];
+
+    env.registerExtensionPoint(devAiHubProviderExtensionPoint, {
+      addProvider(provider) {
+        externalProviders.push(provider);
+      },
+    });
+
+    env.registerInit({
+      deps: {
+        config: coreServices.rootConfig,
+        logger: coreServices.logger,
+        database: coreServices.database,
+        scheduler: coreServices.scheduler,
+        httpRouter: coreServices.httpRouter,
+        urlReader: coreServices.urlReader,
+      },
+      async init({ config, logger, database, scheduler, httpRouter, urlReader }) {
+        const store = await AiAssetStore.create({ database });
+
+        const providers: ProviderConfig[] = (
+          config.getOptionalConfigArray('devAiHub.providers') ?? []
+        ).map(p => ({
+          id: p.getString('id'),
+          type: p.getString('type') as ProviderConfig['type'],
+          target: p.getString('target'),
+          branch: p.getOptionalString('branch') ?? 'main',
+          schedule: {
+            frequency: {
+              minutes: p.getOptionalNumber('schedule.frequency.minutes'),
+              hours: p.getOptionalNumber('schedule.frequency.hours'),
+            },
+            timeout: {
+              minutes: p.getOptionalNumber('schedule.timeout.minutes'),
+              hours: p.getOptionalNumber('schedule.timeout.hours'),
+            },
+          },
+          filters: p.has('filters')
+            ? {
+                tools: p.getOptionalStringArray('filters.tools'),
+                types: p.getOptionalStringArray('filters.types'),
+              }
+            : undefined,
+        }));
+
+        const syncService = new AiAssetSyncService({
+          logger,
+          store,
+          scheduler,
+          urlReader,
+          providers,
+          externalProviders,
+        });
+
+        await syncService.start();
+
+        const router = createRouter({ logger, store, syncService, providers });
+
+        httpRouter.use(router);
+
+        httpRouter.addAuthPolicy({ path: '/assets', allow: 'unauthenticated' });
+        httpRouter.addAuthPolicy({ path: '/providers', allow: 'unauthenticated' });
+        httpRouter.addAuthPolicy({ path: '/stats', allow: 'unauthenticated' });
+        httpRouter.addAuthPolicy({ path: '/mcp', allow: 'unauthenticated' });
+      },
+    });
+  },
+});

package/src/router.ts

@@ -0,0 +1,338 @@
+import { randomUUID } from 'crypto';
+import express from 'express';
+import archiver from 'archiver';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { LoggerService } from '@backstage/backend-plugin-api';
+import type { AiAssetStore } from './database/AiAssetStore';
+import type { AiAssetSyncService } from './service/AiAssetSyncService';
+import { createMcpServer } from './service/McpServerService';
+import type { ProviderConfig, AssetListFilter } from './types';
+import type { AssetType } from '@nospt/plugin-dev-ai-hub-common';
+
+interface RouterOptions {
+  logger: LoggerService;
+  store: AiAssetStore;
+  syncService: AiAssetSyncService;
+  providers: ProviderConfig[];
+}
+
+export function createRouter(options: RouterOptions): express.Router {
+  const { store, syncService, providers } = options;
+  const router = express.Router();
+
+  /** Active MCP sessions: sessionId → transport */
+  const mcpSessions = new Map<string, StreamableHTTPServerTransport>();
+
+  router.use(express.json());
+
+  // ── Assets ────────────────────────────────────────────────────────────────
+
+  router.get('/assets', async (req, res) => {
+    try {
+      const filter: AssetListFilter = {
+        type: req.query.type as AssetType | undefined,
+        tool: req.query.tool as string | undefined,
+        providerId: req.query.provider as string | undefined,
+        search: req.query.search as string | undefined,
+        tags: req.query.tags
+          ? (req.query.tags as string).split(',').filter(Boolean)
+          : undefined,
+        page: req.query.page ? Number(req.query.page) : 1,
+        pageSize: req.query.pageSize ? Number(req.query.pageSize) : 20,
+      };
+
+      const { items, totalCount } = await store.listAssets(filter);
+
+      res.json({
+        items,
+        totalCount,
+        page: filter.page,
+        pageSize: filter.pageSize,
+      });
+    } catch (err) {
+      options.logger.error('GET /assets failed', err as Error);
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  router.get('/assets/:id', async (req, res) => {
+    try {
+      const asset = await store.getAsset(req.params.id);
+      if (!asset) return res.status(404).json({ error: 'Asset not found' });
+      return res.json(asset);
+    } catch (err) {
+      options.logger.error('GET /assets/:id failed', err as Error);
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  /** Returns the pure markdown content of the asset */
+  router.get('/assets/:id/raw', async (req, res) => {
+    try {
+      const asset = await store.getAsset(req.params.id);
+      if (!asset) return res.status(404).json({ error: 'Asset not found' });
+      res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+      return res.send(asset.content);
+    } catch (err) {
+      options.logger.error('GET /assets/:id/raw failed', err as Error);
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  /**
+   * For skills: returns a zip with the markdown + metadata about bundled resources.
+   * For other types: returns the markdown as a text file.
+   */
+  router.get('/assets/:id/download', async (req, res) => {
+    try {
+      const asset = await store.getAsset(req.params.id);
+      if (!asset) return res.status(404).json({ error: 'Asset not found' });
+
+      const filename = `${asset.name.replace(/\s+/g, '-').toLowerCase()}`;
+
+      if (asset.type === 'skill') {
+        res.setHeader('Content-Type', 'application/zip');
+        res.setHeader(
+          'Content-Disposition',
+          `attachment; filename="${filename}.zip"`,
+        );
+        const archive = archiver('zip');
+        archive.pipe(res);
+        archive.append(asset.content, { name: 'SKILL.md' });
+        if (asset.resourcesContent) {
+          for (const [resourcePath, resourceContent] of Object.entries(asset.resourcesContent)) {
+            archive.append(resourceContent, { name: resourcePath });
+          }
+        }
+        await archive.finalize();
+      } else {
+        res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+        res.setHeader(
+          'Content-Disposition',
+          `attachment; filename="${filename}.md"`,
+        );
+        return res.send(asset.content);
+      }
+
+      return undefined;
+    } catch (err) {
+      options.logger.error('GET /assets/:id/download failed', err as Error);
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  router.post('/assets/:id/track-install', async (req, res) => {
+    try {
+      const asset = await store.getAsset(req.params.id);
+      if (!asset) return res.status(404).json({ error: 'Asset not found' });
+      await store.incrementInstallCount(req.params.id);
+      return res.status(204).send();
+    } catch (err) {
+      options.logger.error('POST /assets/:id/track-install failed', err as Error);
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  // ── Providers ─────────────────────────────────────────────────────────────
+
+  router.get('/providers', async (_req, res) => {
+    try {
+      const statuses = await store.getAllSyncStatuses();
+      const statusMap = new Map(statuses.map(s => [s.providerId, s]));
+
+      const result = providers.map(p => {
+        const status = statusMap.get(p.id);
+        return {
+          id: p.id,
+          type: p.type,
+          target: p.target,
+          branch: p.branch,
+          lastSync: status?.lastSync,
+          lastCommit: status?.lastCommit,
+          status: status?.status ?? 'idle',
+          error: status?.error,
+          assetCount: status?.assetCount ?? 0,
+        };
+      });
+
+      res.json(result);
+    } catch (err) {
+      options.logger.error('GET /providers failed', err as Error);
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  router.get('/providers/:id/status', async (req, res) => {
+    try {
+      const provider = providers.find(p => p.id === req.params.id);
+      if (!provider) return res.status(404).json({ error: 'Provider not found' });
+
+      const status = await store.getSyncStatus(req.params.id);
+      return res.json(
+        status ?? {
+          providerId: req.params.id,
+          status: 'idle',
+          assetCount: 0,
+        },
+      );
+    } catch (err) {
+      options.logger.error('GET /providers/:id/status failed', err as Error);
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  router.post('/providers/:id/sync', async (req, res) => {
+    try {
+      const provider = providers.find(p => p.id === req.params.id);
+      if (!provider) return res.status(404).json({ error: 'Provider not found' });
+
+      // Fire and forget — respond immediately, sync runs in background
+      setImmediate(() => syncService.syncProvider(provider));
+
+      return res.json({ message: 'Sync triggered', providerId: provider.id });
+    } catch (err) {
+      options.logger.error('POST /providers/:id/sync failed', err as Error);
+      return res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  // ── Stats ─────────────────────────────────────────────────────────────────
+
+  router.get('/stats', async (_req, res) => {
+    try {
+      const stats = await store.getStats();
+      res.json(stats);
+    } catch (err) {
+      options.logger.error('GET /stats failed', err as Error);
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  // ── MCP — StreamableHTTP transport ────────────────────────────────────────
+  //
+  // Clients connect to /mcp?tool=<ai-tool-name> using the MCP HTTP protocol.
+  // The `tool` query parameter filters assets to those compatible with that
+  // AI tool. Each session is stateful: the tool filter is captured at
+  // initialization time and reused for the session lifetime.
+  //
+  // Client configuration example (.mcp.json / mcp_settings.json):
+  //
+  //   {
+  //     "mcpServers": {
+  //       "dev-ai-hub": {
+  //         "type": "http",
+  //         "url": "http://<backstage-host>:7007/api/dev-ai-hub/mcp?tool=claude-code"
+  //       }
+  //     }
+  //   }
+  //
+  // Set AI_HUB_TOOL in your environment and substitute it into the URL, or
+  // hard-code the tool name per workspace.
+
+  /**
+   * POST /mcp — Initialize a new MCP session or handle an existing one.
+   * On first request (no mcp-session-id header), a new session is created
+   * and its ID is returned in the response header.
+   */
+  router.post('/mcp', async (req, res) => {
+    try {
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+      if (sessionId) {
+        const transport = mcpSessions.get(sessionId);
+        if (!transport) {
+          res.status(404).json({ error: 'MCP session not found' });
+          return;
+        }
+        await transport.handleRequest(req, res, req.body);
+        return;
+      }
+
+      // New session — extract filters from query params or headers
+      const toolFilter =
+        (req.query.tool as string | undefined) ??
+        (req.headers['x-ai-hub-tool'] as string | undefined) ??
+        '';
+      const providerFilter =
+        (req.query.provider as string | undefined) ??
+        (req.headers['x-ai-hub-provider'] as string | undefined) ??
+        '';
+      // proactive defaults to false; pass ?proactive=true to enable check_for_assets + suggest_assets
+      const proactiveEnabled =
+        ((req.query.proactive as string | undefined) ??
+         (req.headers['x-ai-hub-proactive'] as string | undefined) ??
+         'false') === 'true';
+
+      const newSessionId = randomUUID();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => newSessionId,
+        onsessioninitialized: id => {
+          mcpSessions.set(id, transport);
+          options.logger.debug(
+            `dev-ai-hub MCP: session ${id} opened (tool="${toolFilter || 'all'}", provider="${providerFilter || 'all'}", proactive=${proactiveEnabled})`,
+          );
+        },
+      });
+
+      transport.onclose = () => {
+        mcpSessions.delete(newSessionId);
+        options.logger.debug(`dev-ai-hub MCP: session ${newSessionId} closed`);
+      };
+
+      const server = createMcpServer(store, toolFilter, providerFilter, providers, proactiveEnabled);
+      await server.connect(transport);
+
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      options.logger.error('POST /mcp failed', err as Error);
+      if (!res.headersSent) res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  /**
+   * GET /mcp — SSE stream for server-to-client notifications on an existing session.
+   */
+  router.get('/mcp', async (req, res) => {
+    try {
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+      if (!sessionId) {
+        res.status(400).json({ error: 'mcp-session-id header required' });
+        return;
+      }
+      const transport = mcpSessions.get(sessionId);
+      if (!transport) {
+        res.status(404).json({ error: 'MCP session not found' });
+        return;
+      }
+      await transport.handleRequest(req, res);
+    } catch (err) {
+      options.logger.error('GET /mcp failed', err as Error);
+      if (!res.headersSent) res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  /**
+   * DELETE /mcp — Terminate an existing MCP session.
+   */
+  router.delete('/mcp', async (req, res) => {
+    try {
+      const sessionId = req.headers['mcp-session-id'] as string | undefined;
+      if (!sessionId) {
+        res.status(400).json({ error: 'mcp-session-id header required' });
+        return;
+      }
+      const transport = mcpSessions.get(sessionId);
+      if (!transport) {
+        res.status(404).json({ error: 'MCP session not found' });
+        return;
+      }
+      await transport.handleRequest(req, res);
+      mcpSessions.delete(sessionId);
+    } catch (err) {
+      options.logger.error('DELETE /mcp failed', err as Error);
+      if (!res.headersSent) res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  return router;
+}

package/src/service/AiAssetSyncService.ts

@@ -0,0 +1,267 @@
+import type {
+  LoggerService,
+  SchedulerService,
+  UrlReaderService,
+} from '@backstage/backend-plugin-api';
+import type { AiAssetStore } from '../database/AiAssetStore';
+import type { ProviderConfig } from '../types';
+import type { AiAssetProvider } from '@nospt/plugin-dev-ai-hub-node';
+import { AssetParser } from './AssetParser';
+
+interface Options {
+  logger: LoggerService;
+  store: AiAssetStore;
+  scheduler: SchedulerService;
+  urlReader: UrlReaderService;
+  providers: ProviderConfig[];
+  externalProviders: AiAssetProvider[];
+}
+
+export class AiAssetSyncService {
+  constructor(private readonly options: Options) {}
+
+  async start(): Promise<void> {
+    const { scheduler, logger, providers, externalProviders } = this.options;
+
+    if (providers.length === 0 && externalProviders.length === 0) {
+      logger.warn(
+        'dev-ai-hub: no providers configured under devAiHub.providers',
+      );
+      return;
+    }
+
+    for (const provider of providers) {
+      const { frequency, timeout } = provider.schedule;
+      const frequencyDuration = frequency.minutes
+        ? { minutes: frequency.minutes }
+        : { hours: frequency.hours ?? 1 };
+      const timeoutDuration = timeout.minutes
+        ? { minutes: timeout.minutes }
+        : { hours: timeout.hours ?? 1 };
+
+      await scheduler.scheduleTask({
+        id: `dev-ai-hub-sync-${provider.id}`,
+        frequency: frequencyDuration,
+        timeout: timeoutDuration,
+        initialDelay: { seconds: 15 },
+        fn: async () => {
+          await this.syncProvider(provider);
+        },
+      });
+
+      logger.info(
+        `dev-ai-hub: scheduled sync for provider "${provider.id}" every ${JSON.stringify(frequencyDuration)}`,
+      );
+    }
+
+    for (const extProvider of externalProviders) {
+      await scheduler.scheduleTask({
+        id: `dev-ai-hub-sync-external-${extProvider.id}`,
+        frequency: { minutes: 60 },
+        timeout: { minutes: 5 },
+        initialDelay: { seconds: 15 },
+        fn: async () => {
+          await this.syncExternalProvider(extProvider);
+        },
+      });
+
+      logger.info(
+        `dev-ai-hub: scheduled sync for external provider "${extProvider.id}"`,
+      );
+    }
+  }
+
+  async syncProvider(provider: ProviderConfig): Promise<void> {
+    const { logger, urlReader, store } = this.options;
+
+    logger.info(`dev-ai-hub: starting sync for provider "${provider.id}"`);
+
+    await store.upsertSyncStatus({
+      providerId: provider.id,
+      status: 'syncing',
+      assetCount: 0,
+    });
+
+    try {
+      const treeUrl = buildTreeUrl(provider);
+      const tree = await urlReader.readTree(treeUrl);
+      const files = await tree.files();
+
+      const fileMap = new Map<
+        string,
+        { content(): Promise<Buffer>; path: string }
+      >();
+      for (const file of files) {
+        fileMap.set(normalizePath(file.path), file);
+      }
+
+      const syncedIds: string[] = [];
+
+      for (const [filePath, file] of fileMap) {
+        if (!filePath.endsWith('.yaml')) continue;
+        if (!AssetParser.isAssetFile(filePath)) continue;
+
+        const yamlContent = (await file.content()).toString('utf-8');
+        const parsed = AssetParser.parseYaml(yamlContent, filePath);
+
+        if (!parsed) {
+          logger.warn(
+            `dev-ai-hub: skipping invalid YAML at ${filePath} (provider ${provider.id})`,
+          );
+          continue;
+        }
+
+        if (
+          provider.filters?.types &&
+          !provider.filters.types.includes(parsed.meta.type)
+        ) {
+          continue;
+        }
+        if (provider.filters?.tools) {
+          const hasMatchingTool = parsed.meta.tools.some(t =>
+            provider.filters!.tools!.includes(t),
+          );
+          if (!hasMatchingTool) continue;
+        }
+
+        const mdFile = fileMap.get(normalizePath(parsed.mdPath));
+        if (!mdFile) {
+          logger.warn(
+            `dev-ai-hub: .md not found for ${filePath} (expected ${parsed.mdPath}), skipping`,
+          );
+          continue;
+        }
+
+        const mdContent = (await mdFile.content()).toString('utf-8');
+
+        // For skills: read bundled resource files and store their content
+        let resourcesContent: Record<string, string> | undefined;
+        const resourcePaths = parsed.meta.resources;
+        if (resourcePaths && resourcePaths.length > 0) {
+          resourcesContent = {};
+          const yamlDir = filePath.split('/').slice(0, -1).join('/');
+          for (const resourcePath of resourcePaths) {
+            const fullPath = normalizePath(
+              yamlDir ? `${yamlDir}/${resourcePath}` : resourcePath,
+            );
+            const resourceFile = fileMap.get(fullPath);
+            if (resourceFile) {
+              resourcesContent[resourcePath] = (await resourceFile.content()).toString('utf-8');
+            } else {
+              logger.warn(
+                `dev-ai-hub: resource file not found: ${fullPath} (asset ${filePath})`,
+              );
+            }
+          }
+          if (Object.keys(resourcesContent).length === 0) resourcesContent = undefined;
+        }
+
+        const asset = AssetParser.buildAsset(
+          parsed,
+          mdContent,
+          provider.id,
+          provider.target,
+          provider.branch,
+          filePath,
+          resourcesContent,
+        );
+
+        await store.upsertAsset(asset);
+        syncedIds.push(asset.id);
+      }
+
+      await store.deleteAssetsNotIn(provider.id, syncedIds);
+
+      await store.upsertSyncStatus({
+        providerId: provider.id,
+        lastSync: new Date().toISOString(),
+        status: 'idle',
+        assetCount: syncedIds.length,
+      });
+
+      logger.info(
+        `dev-ai-hub: sync complete for provider "${provider.id}" — ${syncedIds.length} assets`,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.options.logger.error(
+        `dev-ai-hub: sync failed for provider "${provider.id}": ${message}`,
+      );
+      await store.upsertSyncStatus({
+        providerId: provider.id,
+        status: 'error',
+        error: message,
+        assetCount: 0,
+      });
+    }
+  }
+
+  private async syncExternalProvider(provider: AiAssetProvider): Promise<void> {
+    const { logger, store } = this.options;
+
+    logger.info(`dev-ai-hub: syncing external provider "${provider.id}"`);
+
+    await store.upsertSyncStatus({
+      providerId: provider.id,
+      status: 'syncing',
+      assetCount: 0,
+    });
+
+    try {
+      const assets = await provider.getAssets();
+      const syncedIds: string[] = [];
+
+      for (const assetData of assets) {
+        const id = AssetParser.buildId(provider.id, assetData.yamlPath);
+        await store.upsertAsset({ ...assetData, id });
+        syncedIds.push(id);
+      }
+
+      await store.deleteAssetsNotIn(provider.id, syncedIds);
+
+      await store.upsertSyncStatus({
+        providerId: provider.id,
+        lastSync: new Date().toISOString(),
+        status: 'idle',
+        assetCount: syncedIds.length,
+      });
+
+      logger.info(
+        `dev-ai-hub: external sync complete for "${provider.id}" — ${syncedIds.length} assets`,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(
+        `dev-ai-hub: external sync failed for "${provider.id}": ${message}`,
+      );
+      await store.upsertSyncStatus({
+        providerId: provider.id,
+        status: 'error',
+        error: message,
+        assetCount: 0,
+      });
+    }
+  }
+}
+
+function normalizePath(p: string): string {
+  return p.replace(/\\/g, '/').replace(/^\//, '');
+}
+
+function buildTreeUrl(provider: ProviderConfig): string {
+  const base = provider.target.replace(/\.git$/, '');
+  const { branch, type } = provider;
+
+  switch (type) {
+    case 'gitlab':
+      return `${base}/-/tree/${branch}/`;
+    case 'bitbucket':
+      return `${base}/src/${branch}/`;
+    case 'azure-devops':
+      return `${base}?version=GB${branch}`;
+    case 'github':
+    case 'git':
+    default:
+      return `${base}/tree/${branch}/`;
+  }
+}