chore: enhance project maintenance and migrate to MUI v5 (#30)

This introduces several key enhancements to the project configuration and codebase, focusing on modernization and maintenance.

### Development
- Added a small configuration to launch both a mini-frontend and a mini-backend to ensure with `just start` the UI is working properly, without the need of a full blown backstage installation. This allows faster feedback loop with auto-reload of the changes.

### Refactor: MUI v5 Migration
- Migrated all UI components from **Material-UI v4** (`@material-ui/core`, `@material-ui/icons`) to **MUI v5** (`@mui/material`, `@mui/icons-material`).
- Updated `package.json` dependencies and component imports to reflect this change.
- Updated `AGENTS.md` documentation to reference the new styling library.

### Dependency Cleanup
- Removed unused `dependencies` and `devDependencies` from `package.json` to improve project hygiene and reduce install time.

### Tooling & CI Enhancements
- **Justfile**:
  - Added `audit` command (`yarn npm audit`) for security checks.
  - Updated `clean` command to ensure dependencies are installed first.
- **Pre-commit**: Updated hooks to utilize `just lint` and `just test`, ensuring consistency between local development and pre-commit checks.

Author: tembleking

.github/workflows/release.yaml

@@ -1,12 +1,31 @@
-name: release
+name: Release workflow
 on:
   push:
     branches:
       - main
-  workflow_dispatch: {}
 jobs:
+  check-changes:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2 # We only need the current and the previous commit
+
+      - name: Check if the package.version has changed
+        id: check_changes
+        run: |
+          if git diff --unified=0 HEAD^ package.json | grep '"version":'; then
+            echo "changes=detected" >> $GITHUB_OUTPUT
+          else
+            echo "changes=none" >> $GITHUB_OUTPUT
+          fi
+
+    outputs:
+      changes: ${{ steps.check_changes.outputs.changes }}
   release:
     runs-on: ubuntu-latest
+    if: needs.check-changes.outputs.changes == 'detected'
     defaults:
       run:
         shell: nix develop --command bash {0}
@@ -30,7 +49,6 @@ jobs:
       - name: Configure yarn for publishing
         run: |
           yarn config set -H 'npmAuthToken' "${{secrets.NPM_AUTH_TOKEN}}"
-          # yarn config set -H 'npmRegistries["//npm.pkg.github.com"].npmAuthToken' "${{secrets.GITHUB_TOKEN}}"
       - name: Release to GitHub releases
         run: errout=$(mktemp); gh release create $(cat  package.json | jq -r .version) -R $GITHUB_REPOSITORY -t $(cat  package.json | jq -r .version) --target $GITHUB_REF 2> $errout && true; exitcode=$?; if [ $exitcode -ne 0 ] && ! grep -q "Release.tag_name already exists" $errout; then cat $errout; exit $exitcode; fi
         env:

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+fail_fast: true
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files
+-   repo: local
+    hooks:
+      - id: lint
+        name: run linter
+        entry: just lint
+        language: system
+        pass_filenames: false
+      - id: test
+        name: run tests
+        entry: just test
+        language: system
+        pass_filenames: false

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

AGENTS.md

@@ -0,0 +1,68 @@
+# Repository Guidelines
+
+## Project Purpose & Structure
+This repository contains the **Sysdig Plugin for Backstage**, a frontend plugin that integrates Sysdig Secure vulnerability and posture reports into the Backstage service catalog.
+
+**Key Directories:**
+- **`src/`**: Source code root.
+  - **`api/`**: `SysdigApiClient` implementation using `fetchApi`.
+  - **`components/`**: React components.
+    - `SysdigComponent`: Main dashboard.
+    - `Sysdig*FetchComponent`: Individual data widgets (Runtime, Registry, Pipeline, Posture).
+  - **`lib/`**: Helpers, constants, and annotation definitions (`annotations.ts`).
+- **`dev/`**: Local development harness using `createDevApp` and mock data.
+- **`img/`**: Assets for documentation.
+
+**Tech Stack:** React, TypeScript, Backstage Plugin API, Material UI.
+**Package Manager:** Yarn.
+
+## Build, Test, & Development
+- **`just install`**: Install dependencies.
+- **`just start`**: Starts the local development server at `http://localhost:3000`. Uses `dev/index.tsx` for context. If address is still in use use `fuser -k 3000/tcp`.
+- **`just test`**: Runs unit tests using Jest.
+- **`just lint`**: Runs ESLint to check code quality.
+- **`just build`**: Builds the plugin for distribution.
+- **`just bump`**: Updates dependencies (requires Nix/Just).
+
+## Onboarding & Known Issues
+**Crucial setup details for new contributors:**
+1. **Package Manager**: Strictly use **Yarn** (wrapped via `just`).
+2. **Dev Dependencies**: If `just start` fails, ensure `react`, `react-dom`, and `react-router-dom` (v6) are explicitly in `devDependencies`.
+3. **Configuration**: `app-config.yaml` is not committed but required for `just start`. Create it with standard proxy settings if missing.
+4. **Entity Context**: The plugin crashes if run in isolation because it uses `useEntity`. The `dev/index.tsx` **must** wrap `SysdigPage` in an `<EntityProvider>` with a valid mock entity object.
+5. **Data & Auth**: Without `SYSDIG_SECURE_TOKEN`, requests fail. For UI work, override `sysdigApiRef` with a **Mock Client** in `dev/index.tsx` (see `dev/MockSysdigClient.ts`).
+6. **Test Execution**: `yarn test` defaults to watch mode and will hang indefinitely. **Always use `just test`** (or `yarn test --watchAll=false`) for a single-run execution.
+
+## Coding Style & Naming
+- **Language**: TypeScript (`.ts`, `.tsx`). Strict mode enabled.
+- **Components**: Functional components with Hooks (`useEntity`, `useAsync`, `useApi`).
+- **Styling**: Use Material UI (`@mui/material`) and Backstage core components (`@backstage/core-components`).
+- **Naming**: PascalCase for components (`SysdigComponent`), camelCase for functions/vars.
+- **Imports**: Prefer relative imports within `src/` but use strict package imports for external deps.
+
+## Testing Guidelines
+- **Framework**: Jest + React Testing Library + MSW (Mock Service Worker).
+- **Location**: Tests are co-located with source files (e.g., `SysdigComponent.test.tsx`).
+- **Requirement**: Components must be tested for rendering and error states. Use `setupRequestMockHandlers` for API mocking.
+
+## Commit & PR Guidelines
+- **Commits**: Follow **Conventional Commits** format:
+  - `feat(scope): description`
+  - `fix(scope): description`
+  - `chore: description`
+- **Pull Requests**:
+  - Title must match the commit format.
+  - Include screenshots for UI changes.
+  - Ensure `just test` and `just lint` pass before requesting review.
+
+## Release Process
+The release process is semi-automated:
+1.  **Manual Version Bump**: Before creating a release, the `version` field in `package.json` must be manually updated (e.g., from `1.3.2` to `1.3.3`).
+2.  **Automated Release**: Once the version is manually updated and pushed to the `main` branch, the GitHub Actions workflow (`.github/workflows/release.yaml`) automatically:
+    *   Creates a new GitHub Release with the updated version.
+    *   Publishes the package to NPM.
+
+## Documentation Maintenance
+- Keep `README.md` updated with new annotations or configuration options.
+- Maintain this `AGENTS.md` to reflect architectural changes.
+- **Agent Note**: If `src/lib/annotations.ts` changes, update the "How to annotate services" section in `README.md`.

README.md

@@ -22,7 +22,7 @@ Please refer to the [official documentation](https://docs.sysdig.com/en/docs/adm
 
 ### Install the package
 
-#### Via NPM
+#### Via Yarn
 
 ```bash
 # From your Backstage root directory
@@ -115,7 +115,7 @@ metadata:
 
     # VM Pipeline
     sysdigcloud.com/image-freetext: ghcr.io/sysdiglabs
-    
+
     # Posture
     sysdigcloud.com/resource-name: sock-shop-carts
     sysdigcloud.com/resource-type: "Deployment"

app-config.yaml

@@ -0,0 +1,23 @@
+app:
+  title: Sysdig Plugin Dev
+  baseUrl: http://localhost:3000
+
+backend:
+  baseUrl: http://localhost:7007
+  listen:
+    port: 7007
+
+proxy:
+  endpoints:
+    '/sysdig':
+      target: ${SYSDIG_SECURE_ENDPOINT}
+      changeOrigin: true
+      allowedMethods: ['GET']
+      headers:
+        "Authorization": "Bearer ${SYSDIG_SECURE_TOKEN}"
+        "Content-Type": "application/json"
+        "Accept": "application/json"
+        "X-Sysdig-Product": "SDS"
+
+sysdig:
+  endpoint: ${SYSDIG_SECURE_ENDPOINT}

dev/index.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { createDevApp } from '@backstage/dev-utils';
+import { sysdigPlugin, SysdigPage } from '../src/plugin';
+import { EntityProvider } from '@backstage/plugin-catalog-react';
+import { createApiFactory, configApiRef, fetchApiRef } from '@backstage/core-plugin-api';
+import { sysdigApiRef, SysdigApiClient } from '../src/api';
+
+const mockEntity = {
+  apiVersion: 'backstage.io/v1alpha1',
+  kind: 'Component',
+  metadata: {
+    name: 'sock-shop-carts',
+    annotations: {
+      // Un-comment to see different results in the UI
+      //
+      // 'sysdigcloud.com/kubernetes-cluster-name': 'sock-shop-cluster',
+      // 'sysdigcloud.com/kubernetes-namespace-name': 'sock-shop',
+      // 'sysdigcloud.com/kubernetes-workload-name': 'sock-shop-carts',
+      // 'sysdigcloud.com/kubernetes-workload-type': 'deployment',
+      // 'sysdigcloud.com/registry-vendor': 'harbor',
+      // 'sysdigcloud.com/registry-name': 'registry-harbor-registry.registry.svc.cluster.local:5443',
+      // 'sysdigcloud.com/image-freetext': 'ghcr.io/sysdiglabs',
+      // 'sysdigcloud.com/resource-name': 'sock-shop-carts',
+      // 'sysdigcloud.com/resource-type': 'Deployment',
+    },
+  },
+  spec: {
+    type: 'service',
+    lifecycle: 'experimental',
+    owner: 'team-c',
+  },
+};
+
+createDevApp()
+  .registerApi(
+    createApiFactory({
+      api: sysdigApiRef,
+      deps: { configApi: configApiRef, fetchApi: fetchApiRef },
+      factory: ({ configApi, fetchApi }) =>
+        new SysdigApiClient({ configApi, fetchApi }),
+    }),
+  )
+  .registerPlugin(sysdigPlugin)
+  .addPage({
+    element: (
+      <EntityProvider entity={mockEntity}>
+        <SysdigPage />
+      </EntityProvider>
+    ),
+    title: 'Sysdig',
+    path: '/sysdig',
+  })
+  .render();

dev/proxy-server.js

@@ -0,0 +1,51 @@
+/* eslint-disable no-console */
+const express = require('express');
+const { createProxyMiddleware } = require('http-proxy-middleware');
+
+const app = express();
+const PORT = 7007;
+
+// Configuration from environment variables
+const target = process.env.SYSDIG_SECURE_ENDPOINT;
+const token = process.env.SYSDIG_SECURE_TOKEN;
+
+if (!target || !token) {
+  console.error('\x1b[31m%s\x1b[0m', 'Error: SYSDIG_SECURE_ENDPOINT and SYSDIG_SECURE_TOKEN environment variables must be set.');
+  console.log('Usage: SYSDIG_SECURE_ENDPOINT=... SYSDIG_SECURE_TOKEN=... node dev/proxy-server.js');
+  process.exit(1);
+}
+
+// Enable CORS for the frontend (port 3000)
+app.use((req, res, next) => {
+  res.header("Access-Control-Allow-Origin", "http://localhost:3000");
+  res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Sysdig-Product");
+  res.header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+  next();
+});
+
+// Proxy Middleware
+app.use('/api/proxy/sysdig', createProxyMiddleware({
+  target: target,
+  changeOrigin: true,
+  pathRewrite: {
+    '^/api/proxy/sysdig': '', // Remove the prefix when forwarding
+  },
+  headers: {
+    "Authorization": `Bearer ${token}`,
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+    "X-Sysdig-Product": "SDS"
+  },
+  onProxyRes: (proxyRes, req, _res) => {
+     console.log(`[Proxy] ${req.method} ${req.path} -> ${target} [${proxyRes.statusCode}]`);
+  },
+  onError: (err, req, res) => {
+    console.error(`[Proxy Error] ${err.message}`);
+    res.status(500).send('Proxy Error');
+  }
+}));
+
+app.listen(PORT, () => {
+  console.log(`\x1b[32mSysdig Mock Backend running on http://localhost:${PORT}\x1b[0m`);
+  console.log(`Forwarding /api/proxy/sysdig to ${target}`);
+});

dev/start-dev.js

@@ -0,0 +1,38 @@
+/* eslint-disable no-console */
+const { spawn } = require('child_process');
+const path = require('path');
+
+console.log('\x1b[36m%s\x1b[0m', 'Starting Sysdig Plugin Dev Environment...');
+
+// 1. Start the Proxy Server
+const proxyPath = path.join(__dirname, 'proxy-server.js');
+const proxy = spawn('node', [proxyPath], {
+  stdio: 'inherit',
+  env: process.env
+});
+
+// 2. Start the Backstage Frontend
+// We use 'yarn backstage-cli' directly to ensure we use the local version
+const app = spawn('yarn', ['backstage-cli', 'package', 'start'], {
+  stdio: 'inherit',
+  env: process.env
+});
+
+// Handle cleanup
+const cleanup = () => {
+  console.log('\n\x1b[36m%s\x1b[0m', 'Shutting down processes...');
+  proxy.kill();
+  app.kill();
+  process.exit();
+};
+
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);
+
+// If one fails, kill the other?
+proxy.on('close', (code) => {
+  if (code !== 0 && code !== null) {
+    console.error(`Proxy server exited with code ${code}`);
+    cleanup();
+  }
+});

flake.nix

@@ -25,19 +25,23 @@
           devShells.default =
             with pkgs;
             mkShell {
-              packages =
-                [
-                  gh
-                  jq
-                  nodejs
-                  typescript
-                  yarn-berry
-                  (python3.withPackages (p: with p; [ gyp ]))
-                ]
-                ++ (with nodePackages; [
-                  typescript-language-server
-                  node-gyp
-                ]);
+              packages = [
+                gh
+                jq
+                just
+                nodejs
+                pre-commit
+                typescript
+                yarn-berry
+                (python3.withPackages (p: with p; [ gyp ]))
+              ]
+              ++ (with nodePackages; [
+                typescript-language-server
+                node-gyp
+              ]);
+              shellHook = ''
+                pre-commit install
+              '';
             };
 
           formatter = pkgs.nixfmt-rfc-style;