@forgeportal/plugin-argocd 1.3.0

package/src/__tests__/api-client.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ArgocdApiClient } from '../api-client.js';
+import type { ArgocdConfig } from '../types.js';
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+const CONFIG: ArgocdConfig = {
+  url:      'https://argocd.test.internal',
+  token:    'test-token',
+  insecure: false,
+};
+
+const APP_FIXTURE = {
+  metadata: { name: 'payments-api', namespace: 'default' },
+  spec:     { source: { repoURL: 'https://github.com/acme/payments', path: 'k8s', targetRevision: 'HEAD' } },
+  status: {
+    sync:   { status: 'Synced',   revision: 'abc1234' },
+    health: { status: 'Healthy' },
+    reconciledAt: '2026-02-20T10:00:00Z',
+    history: [
+      { id: 0, revision: 'old123', deployedAt: '2026-02-18T08:00:00Z' },
+      { id: 1, revision: 'abc1234', deployedAt: '2026-02-20T10:00:00Z' },
+    ],
+  },
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function mockFetch(body: unknown, status = 200): ReturnType<typeof vi.fn> {
+  const mock = vi.fn().mockResolvedValue({
+    ok:         status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    json:       () => Promise.resolve(body),
+    text:       () => Promise.resolve(JSON.stringify(body)),
+  });
+  vi.stubGlobal('fetch', mock);
+  return mock;
+}
+
+beforeEach(() => vi.restoreAllMocks());
+afterEach(() => vi.unstubAllGlobals());
+
+// ── Constructor ───────────────────────────────────────────────────────────────
+
+describe('ArgocdApiClient constructor', () => {
+  it('strips trailing slash from baseUrl', async () => {
+    const client = new ArgocdApiClient({ ...CONFIG, url: 'https://argocd.test.internal/' });
+    const fetchMock = mockFetch(APP_FIXTURE);
+    await client.getApp('payments-api');
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toBe('https://argocd.test.internal/api/v1/applications/payments-api');
+  });
+});
+
+// ── getApp ────────────────────────────────────────────────────────────────────
+
+describe('ArgocdApiClient.getApp', () => {
+  const client = new ArgocdApiClient(CONFIG);
+
+  it('fetches app status and returns the response', async () => {
+    mockFetch(APP_FIXTURE);
+    const app = await client.getApp('payments-api');
+    expect(app.status.sync.status).toBe('Synced');
+    expect(app.status.health.status).toBe('Healthy');
+  });
+
+  it('URL-encodes the app name', async () => {
+    const fetchMock = mockFetch(APP_FIXTURE);
+    await client.getApp('my app/with spaces');
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain('my%20app%2Fwith%20spaces');
+  });
+
+  it('sends Bearer token in Authorization header', async () => {
+    const fetchMock = mockFetch(APP_FIXTURE);
+    await client.getApp('payments-api');
+    const [, init] = fetchMock.mock.calls[0] as [string, Record<string, Record<string, string>>];
+    expect(init.headers['Authorization']).toBe('Bearer test-token');
+  });
+
+  it('throws with status code on non-ok response', async () => {
+    mockFetch({ message: 'Not Found' }, 404);
+    await expect(client.getApp('ghost')).rejects.toThrow('404');
+  });
+
+  it('throws on 403 Forbidden', async () => {
+    mockFetch({ message: 'permission denied' }, 403);
+    await expect(client.getApp('payments-api')).rejects.toThrow('403');
+  });
+});
+
+// ── getHistory ────────────────────────────────────────────────────────────────
+
+describe('ArgocdApiClient.getHistory', () => {
+  const client = new ArgocdApiClient(CONFIG);
+
+  it('returns history entries in reverse chronological order', async () => {
+    mockFetch(APP_FIXTURE);
+    const history = await client.getHistory('payments-api');
+    expect(history).toHaveLength(2);
+    // reversed — most recent first
+    expect(history[0]?.revision).toBe('abc1234');
+    expect(history[1]?.revision).toBe('old123');
+  });
+
+  it('returns empty array when history is absent', async () => {
+    const noHistory = { ...APP_FIXTURE, status: { ...APP_FIXTURE.status, history: undefined } };
+    mockFetch(noHistory);
+    const history = await client.getHistory('payments-api');
+    expect(history).toHaveLength(0);
+  });
+
+  it('limits history to 10 entries', async () => {
+    const manyHistory = Array.from({ length: 15 }, (_, i) => ({
+      id: i, revision: `rev${i}`, deployedAt: '2026-01-01T00:00:00Z',
+    }));
+    mockFetch({ ...APP_FIXTURE, status: { ...APP_FIXTURE.status, history: manyHistory } });
+    const history = await client.getHistory('payments-api');
+    expect(history).toHaveLength(10);
+  });
+});
+
+// ── syncApp ───────────────────────────────────────────────────────────────────
+
+describe('ArgocdApiClient.syncApp', () => {
+  const client = new ArgocdApiClient(CONFIG);
+
+  it('sends a POST request to the sync endpoint', async () => {
+    const fetchMock = mockFetch({}, 200);
+    await client.syncApp('payments-api');
+    const [url, init] = fetchMock.mock.calls[0] as [string, Record<string, unknown>];
+    expect(url).toContain('/applications/payments-api/sync');
+    expect(init.method).toBe('POST');
+  });
+
+  it('throws on ArgoCD error response', async () => {
+    mockFetch({ message: 'application is being synced' }, 409);
+    await expect(client.syncApp('payments-api')).rejects.toThrow('409');
+  });
+});
+
+// ── rollbackApp ───────────────────────────────────────────────────────────────
+
+describe('ArgocdApiClient.rollbackApp', () => {
+  const client = new ArgocdApiClient(CONFIG);
+
+  it('sends a POST request with the history ID', async () => {
+    const fetchMock = mockFetch({}, 200);
+    await client.rollbackApp('payments-api', 0);
+    const [url, init] = fetchMock.mock.calls[0] as [string, Record<string, unknown>];
+    expect(url).toContain('/applications/payments-api/rollback');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body as string)).toEqual({ id: 0 });
+  });
+});

package/src/actions.ts

@@ -0,0 +1,118 @@
+import type { ActionProvider } from '@forgeportal/plugin-sdk';
+import type { ArgocdConfig } from './types.js';
+import { ArgocdApiClient } from './api-client.js';
+
+/**
+ * argocd.syncApp@v1
+ *
+ * Triggers a manual sync of an ArgoCD application.
+ * Usable in templates and scorecard fix actions.
+ *
+ * Input:
+ *   - appName: string (required) — ArgoCD application name
+ */
+export function createSyncAppAction(config: ArgocdConfig): ActionProvider {
+  return {
+    id:      'argocd.syncApp',
+    version: 'v1',
+    schema: {
+      input: {
+        type:       'object',
+        required:   ['appName'],
+        properties: {
+          appName: {
+            type:        'string',
+            title:       'Application Name',
+            description: 'Name of the ArgoCD application to sync.',
+          },
+        },
+      },
+      output: {
+        type: 'object',
+        properties: {
+          syncTriggeredAt: { type: 'string', description: 'ISO timestamp when sync was triggered.' },
+        },
+      },
+    },
+
+    async handler(ctx, input) {
+      const appName = input['appName'] as string;
+      ctx.logger.info(`Triggering ArgoCD sync for application "${appName}"`);
+
+      const client = new ArgocdApiClient(config);
+      await client.syncApp(appName);
+
+      const syncTriggeredAt = new Date().toISOString();
+      ctx.logger.info(`Sync triggered for "${appName}" at ${syncTriggeredAt}`);
+
+      return {
+        status:  'success',
+        outputs: { syncTriggeredAt },
+        links: [
+          { title: `Open ${appName} in ArgoCD`, url: `${config.url}/applications/${appName}` },
+        ],
+      };
+    },
+  };
+}
+
+/**
+ * argocd.rollbackApp@v1
+ *
+ * Rolls back an ArgoCD application to a specific history entry.
+ *
+ * Input:
+ *   - appName:   string (required)
+ *   - historyId: number (required) — history entry ID from the app history
+ */
+export function createRollbackAppAction(config: ArgocdConfig): ActionProvider {
+  return {
+    id:      'argocd.rollbackApp',
+    version: 'v1',
+    schema: {
+      input: {
+        type:       'object',
+        required:   ['appName', 'historyId'],
+        properties: {
+          appName: {
+            type:        'string',
+            title:       'Application Name',
+            description: 'Name of the ArgoCD application to roll back.',
+          },
+          historyId: {
+            type:        'number',
+            title:       'History ID',
+            description: 'History entry ID to roll back to (from the sync history list).',
+          },
+        },
+      },
+      output: {
+        type: 'object',
+        properties: {
+          rolledBackAt: { type: 'string', description: 'ISO timestamp of the rollback trigger.' },
+        },
+      },
+    },
+
+    async handler(ctx, input) {
+      const appName   = input['appName'] as string;
+      const historyId = input['historyId'] as number;
+
+      ctx.logger.info(`Rolling back ArgoCD application "${appName}" to history entry ${historyId}`);
+
+      const client = new ArgocdApiClient(config);
+      await client.rollbackApp(appName, historyId);
+
+      const rolledBackAt = new Date().toISOString();
+      ctx.logger.info(`Rollback triggered for "${appName}" at ${rolledBackAt}`);
+
+      return {
+        status:  'success',
+        outputs: { rolledBackAt },
+        links: [
+          { title: `Open ${appName} in ArgoCD`, url: `${config.url}/applications/${appName}` },
+        ],
+      };
+    },
+  };
+}

package/src/api-client.ts

@@ -0,0 +1,90 @@
+import type {
+  ArgocdApp,
+  ArgocdHistoryItem,
+  ArgocdConfig,
+  ArgocdResourceTree,
+} from './types.js';
+
+/**
+ * Thin HTTP client for the ArgoCD REST API v1.
+ * Authenticates with a Bearer token (service-account or user token).
+ */
+export class ArgocdApiClient {
+  private readonly baseUrl: string;
+  private readonly token:   string;
+  private readonly rejectUnauthorized: boolean;
+
+  constructor(config: ArgocdConfig) {
+    this.baseUrl             = config.url.replace(/\/$/, '');
+    this.token               = config.token;
+    this.rejectUnauthorized  = !config.insecure;
+  }
+
+  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const res = await (fetch as (url: string, init: Record<string, unknown>) => Promise<Response>)(url, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        'Content-Type': 'application/json',
+        ...(options.headers as Record<string, string> | undefined),
+      },
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new Error(`ArgoCD API ${res.status}: ${body || res.statusText}`);
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  /**
+   * GET /api/v1/applications/{appName}
+   */
+  async getApp(appName: string): Promise<ArgocdApp> {
+    return this.request<ArgocdApp>(`/applications/${encodeURIComponent(appName)}`);
+  }
+
+  /**
+   * GET /api/v1/applications/{appName}/revisions
+   * Returns the last 10 sync history entries.
+   */
+  async getHistory(appName: string): Promise<ArgocdHistoryItem[]> {
+    const app = await this.getApp(appName);
+    // History is embedded in the application status
+    const history = (app as unknown as { status: { history?: ArgocdHistoryItem[] } })
+      .status?.history ?? [];
+    return history.slice(-10).reverse();
+  }
+
+  /**
+   * GET /api/v1/applications/{appName}/resource-tree
+   */
+  async getResourceTree(appName: string): Promise<ArgocdResourceTree> {
+    return this.request<ArgocdResourceTree>(
+      `/applications/${encodeURIComponent(appName)}/resource-tree`,
+    );
+  }
+
+  /**
+   * POST /api/v1/applications/{appName}/sync
+   */
+  async syncApp(appName: string): Promise<void> {
+    await this.request(`/applications/${encodeURIComponent(appName)}/sync`, {
+      method: 'POST',
+      body:   JSON.stringify({}),
+    });
+  }
+
+  /**
+   * POST /api/v1/applications/{appName}/rollback
+   * Rolls back to a specific history entry by id.
+   */
+  async rollbackApp(appName: string, historyId: number): Promise<void> {
+    await this.request(`/applications/${encodeURIComponent(appName)}/rollback`, {
+      method: 'POST',
+      body:   JSON.stringify({ id: historyId }),
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import type { ForgeBackendPluginSDK } from '@forgeportal/plugin-sdk';
+import type { ArgocdConfig } from './types.js';
+import { createRoutes } from './routes.js';
+import { createSyncAppAction, createRollbackAppAction } from './actions.js';
+
+/**
+ * Backend entry point for the ArgoCD plugin.
+ * Called by the ForgePortal plugin loader at startup.
+ *
+ * Configuration (forgeportal.yaml -> plugins.argocd.config):
+ *   url:      string  — ArgoCD server URL (e.g. https://argocd.internal)
+ *   insecure: boolean — skip TLS verification (default: false)
+ *
+ * Token comes from the environment:
+ *   FORGEPORTAL_PLUGIN_ARGOCD_TOKEN
+ */
+export function registerBackendPlugin(sdk: ForgeBackendPluginSDK): void {
+  const url      = sdk.config.get<string>('url');
+  const insecure = sdk.config.get<boolean>('insecure') ?? false;
+  const token    = process.env['FORGEPORTAL_PLUGIN_ARGOCD_TOKEN'] ?? '';
+
+  if (!url) {
+    sdk.logger.error(
+      'argocd plugin: "url" is required in plugins.argocd.config. Plugin disabled.',
+    );
+    return;
+  }
+
+  if (!token) {
+    sdk.logger.warn(
+      'argocd plugin: FORGEPORTAL_PLUGIN_ARGOCD_TOKEN env var is not set. API calls will fail.',
+    );
+  }
+
+  const config: ArgocdConfig = { url, token, insecure };
+
+  sdk.logger.info(`argocd plugin: connected to ${url} (insecure=${insecure})`);
+
+  sdk.registerBackendRoute({
+    path:    '',
+    handler: createRoutes(config),
+  });
+
+  sdk.registerActionProvider(createSyncAppAction(config));
+  sdk.registerActionProvider(createRollbackAppAction(config));
+}

package/src/routes.ts

@@ -0,0 +1,127 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import type { ArgocdConfig }     from './types.js';
+import { ArgocdApiClient } from './api-client.js';
+
+interface EntityParams { entityId: string }
+interface SyncBody     { appName: string }
+
+/**
+ * Creates Fastify route handlers for the ArgoCD plugin.
+ * All routes are mounted under /api/v1/plugins/argocd/ by the plugin loader.
+ *
+ * Routes:
+ *   GET  entities/:entityId/app           — app summary (status, health, revision)
+ *   GET  entities/:entityId/history       — last 10 sync operations
+ *   POST entities/:entityId/sync          — trigger sync
+ */
+export function createRoutes(config: ArgocdConfig) {
+  const client = new ArgocdApiClient(config);
+
+  return async function handler(fastify: FastifyInstance): Promise<void> {
+    /**
+     * GET /entities/:entityId/app?appName=<override>
+     *
+     * Returns the ArgoCD application summary: sync status, health, revision, operation state.
+     * The app name is read from the query param or entity annotations.
+     */
+    fastify.get(
+      'entities/:entityId/app',
+      async (
+        request: FastifyRequest<{
+          Params:      EntityParams;
+          Querystring: { appName?: string };
+        }>,
+        reply: FastifyReply,
+      ) => {
+        const appName = request.query.appName;
+
+        if (!appName) {
+          return reply.status(400).send({
+            error:   'Bad Request',
+            message: 'Query parameter "appName" is required, or set the forgeportal.dev/argocd-app-name annotation.',
+          });
+        }
+
+        try {
+          const app = await client.getApp(appName);
+          return reply.send({ data: app });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'argocd plugin: getApp failed');
+          if (message.includes('404')) {
+            return reply.status(404).send({ error: 'Not Found', message: `ArgoCD app "${appName}" not found.` });
+          }
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * GET /entities/:entityId/history?appName=<override>
+     *
+     * Returns the last 10 sync history entries for the ArgoCD application.
+     */
+    fastify.get(
+      'entities/:entityId/history',
+      async (
+        request: FastifyRequest<{
+          Params:      EntityParams;
+          Querystring: { appName?: string };
+        }>,
+        reply: FastifyReply,
+      ) => {
+        const appName = request.query.appName;
+
+        if (!appName) {
+          return reply.status(400).send({
+            error:   'Bad Request',
+            message: 'Query parameter "appName" is required.',
+          });
+        }
+
+        try {
+          const history = await client.getHistory(appName);
+          return reply.send({ data: history });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'argocd plugin: getHistory failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+
+    /**
+     * POST /entities/:entityId/sync
+     *
+     * Body: { appName: string }
+     * Triggers a manual sync of the ArgoCD application.
+     */
+    fastify.post(
+      'entities/:entityId/sync',
+      async (
+        request: FastifyRequest<{ Params: EntityParams; Body: SyncBody }>,
+        reply:   FastifyReply,
+      ) => {
+        const { appName } = request.body ?? {};
+
+        if (!appName) {
+          return reply.status(400).send({
+            error:   'Bad Request',
+            message: 'Body field "appName" is required.',
+          });
+        }
+
+        try {
+          await client.syncApp(appName);
+          return reply.status(202).send({
+            data: { appName, syncTriggeredAt: new Date().toISOString() },
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          request.log.error({ err }, 'argocd plugin: syncApp failed');
+          return reply.status(502).send({ error: 'Bad Gateway', message });
+        }
+      },
+    );
+  };
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+// ─── ArgoCD API response shapes ──────────────────────────────────────────────
+
+export interface ArgocdAppStatus {
+  sync: {
+    status:   'Synced' | 'OutOfSync' | 'Unknown';
+    revision: string;
+  };
+  health: {
+    status: 'Healthy' | 'Degraded' | 'Progressing' | 'Suspended' | 'Missing' | 'Unknown';
+  };
+  operationState?: {
+    phase:     string;
+    message?:  string;
+    startedAt: string;
+    finishedAt?: string;
+  };
+  reconciledAt?: string;
+}
+
+export interface ArgocdApp {
+  metadata: {
+    name:      string;
+    namespace: string;
+  };
+  spec: {
+    project: string;
+    source?: {
+      repoURL:        string;
+      targetRevision: string;
+      path?:          string;
+    };
+    destination: {
+      server:    string;
+      namespace: string;
+    };
+  };
+  status: ArgocdAppStatus;
+}
+
+export interface ArgocdHistoryItem {
+  id:         number;
+  revision:   string;
+  deployedAt: string;
+  initiatedBy?: { username?: string; automated?: boolean };
+}
+
+export interface ArgocdResourceNode {
+  kind:       string;
+  name:       string;
+  namespace?: string;
+  status?:    string;
+  health?:    { status: string };
+}
+
+export interface ArgocdResourceTree {
+  nodes: ArgocdResourceNode[];
+}
+
+// ─── Plugin-internal config ───────────────────────────────────────────────────
+
+export interface ArgocdConfig {
+  url:      string;
+  token:    string;
+  insecure: boolean;
+}

package/src/ui.ts

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

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"]
+}