Add project README, mock data, and onboarding findings

- Replace template README with plugin-specific content
- Add mock-analysis-result.yaml for cluster testing without Lightspeed
- Add ONBOARDING-FINDINGS.md documenting API mismatches and dev setup
- Updated Helm Charts
- Update locales
- Update getAnalysisDataFromResult to support arrays

Author: jhadvig

README.md

@@ -1,230 +1,119 @@
-# OpenShift console plugin template
-
-This project is a minimal template for writing a new OpenShift Console dynamic
-plugin.
-
-[Openshift console plugins](https://github.com/openshift/console/tree/main/frontend/packages/console-dynamic-plugin-sdk)
-allow you to extend the [OpenShift web console](https://github.com/openshift/console)
-at runtime, adding custom pages and other extensions. They are based on
-[webpack module federation](https://webpack.js.org/concepts/module-federation/).
-Plugins are registered with console using the `ConsolePlugin` custom resource
-and enabled in the console operator config by a cluster administrator.
-
-The `main` branch of this repository contains an example plugin which works
-with the latest version. To see an example of a plugin which works with an older
-version, visit the appropriate `release-4.x` branch.
-
-[Node.js](https://nodejs.org/en/) and [yarn](https://yarnpkg.com) are required
-to build and run the example. To run OpenShift console in a container, either
-[Docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io) and
-[oc](https://console.redhat.com/openshift/downloads) are required.
-
-## Getting started
-
-> [!IMPORTANT]
-> To use this template, **DO NOT FORK THIS REPOSITORY**! Click **Use this template**, then select
-> [**Create a new repository**](https://github.com/new?template_name=console-plugin-template&template_owner=openshift)
-> to create a new repository.
->
-> ![A screenshot showing where the "Use this template" button is located](https://i.imgur.com/AhaySbU.png)
->
-> **Forking this repository** for purposes outside of contributing to this repository
-> **will cause issues**, as users cannot have more than one fork of a template repository
-> at a time. This could prevent future users from forking and contributing to your plugin.
->
-> Your fork would also behave like a template repository, which might be confusing for
-> contributiors, because it is not possible for repositories generated from a template
-> repository to contribute back to the template.
-
-After cloning your instantiated repository, you must update the plugin metadata, such as the
-plugin name in the `consolePlugin` declaration of [package.json](package.json).
+# Cluster Update Console Plugin
 
-```json
-"consolePlugin": {
-  "name": "console-plugin-template",
-  "version": "0.0.1",
-  "displayName": "My Plugin",
-  "description": "Enjoy this shiny, new console plugin!",
-  "exposedModules": {
-    "ExamplePage": "./components/ExamplePage"
-  },
-  "dependencies": {
-    "@console/pluginAPI": "*"
-  }
-}
-```
-
-The template adds a single example page in the Home navigation section. The
-extension is declared in the [console-extensions.json](console-extensions.json)
-file and the React component is declared in
-[src/components/ExamplePage.tsx](src/components/ExamplePage.tsx).
-
-You can run the plugin using a local development environment or build an image
-to deploy it to a cluster.
-
-## Development
-
-### Option 1: Local
+An OpenShift Console dynamic plugin that provides an AI-driven cluster update experience. It integrates with [OpenShift Lightspeed](https://github.com/openshift/lightspeed-operator) proposals (via the `agentic.openshift.io` API) to assess upgrade readiness, show OLM operator compatibility, and let users approve or reject AI-generated update plans.
 
-In one terminal window, run:
+## Features
 
-1. `yarn install`
-2. `yarn run start`
+- **Update Plan** — Shows the active AI-generated update proposal with risk assessment, readiness checks, OLM operator compatibility, API deprecation checks, and approve/deny actions.
+- **Active Update Plans** — Lists all non-terminal Lightspeed proposals.
+- **Update History** — Shows the ClusterVersion update history.
+- **Graceful Degradation** — Works without the Lightspeed Proposal CRD installed. The Update History tab is always functional; AI features show a warning banner when unavailable.
 
-In another terminal window, run:
+## Prerequisites
 
-1. `oc login` (requires [oc](https://console.redhat.com/openshift/downloads) and an [OpenShift cluster](https://console.redhat.com/openshift/create))
-2. `yarn run start-console` (requires [Docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io))
+- OpenShift 4.22+ (uses ConsolePlugin CRD v1 API, Console SDK 4.22)
+- [Node.js](https://nodejs.org/en/) 18+ and [Yarn](https://yarnpkg.com) 4.x
+- [oc](https://console.redhat.com/openshift/downloads) CLI
+- [Docker](https://www.docker.com) or [podman 3.2.0+](https://podman.io) (for running the console locally)
 
-This will run the OpenShift console in a container connected to the cluster
-you've logged into. The plugin HTTP server runs on port 9001 with CORS enabled.
-Navigate to <http://localhost:9000/example> to see the running plugin.
+## Development
 
-#### Running start-console with Apple silicon and podman
+### Local development
 
-If you are using podman on a Mac with Apple silicon, `yarn run start-console`
-might fail since it runs an amd64 image. You can workaround the problem with
-[qemu-user-static](https://github.com/multiarch/qemu-user-static) by running
-these commands:
+In one terminal:
 
 ```bash
-podman machine ssh
-sudo -i
-rpm-ostree install qemu-user-static
-systemctl reboot
+yarn install
+yarn start
 ```
 
-### Option 2: Docker + VSCode Remote Container
-
-Make sure the
-[Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
-extension is installed. This method uses Docker Compose where one container is
-the OpenShift console and the second container is the plugin. It requires that
-you have access to an existing OpenShift cluster. After the initial build, the
-cached containers will help you start developing in seconds.
-
-1. Create a `dev.env` file inside the `.devcontainer` folder with the correct values for your cluster:
+In another terminal:
 
 ```bash
-OC_PLUGIN_NAME=console-plugin-template
-OC_URL=https://api.example.com:6443
-OC_USER=kubeadmin
-OC_PASS=<password>
+oc login  # log into your OpenShift cluster
+yarn start-console
 ```
 
-2. `(Ctrl+Shift+P) => Remote Containers: Open Folder in Container...`
-3. `yarn run start`
-4. Navigate to <http://localhost:9000/example>
+Navigate to <http://localhost:9000/administration/cluster-update>.
 
-## Docker image
+The plugin dev server runs on port 9001 with CORS enabled. The console bridge runs on port 9000.
 
-Before you can deploy your plugin on a cluster, you must build an image and
-push it to an image registry.
+### Testing with mock data
 
-1. Build the image:
+Without the Lightspeed agentic operator installed, Proposals have no analysis data. To test with mock data:
 
-   ```sh
-   docker build -t quay.io/my-repository/my-plugin:latest .
+1. Verify CVO-created Proposals exist:
+   ```bash
+   oc -n openshift-lightspeed get proposals.agentic.openshift.io
    ```
 
-2. Run the image:
-
-   ```sh
-   docker run -it --rm -d -p 9001:80 quay.io/my-repository/my-plugin:latest
+2. Get the Proposal UID:
+   ```bash
+   oc -n openshift-lightspeed get proposals.agentic.openshift.io -o custom-columns=NAME:.metadata.name,UID:.metadata.uid
    ```
 
-3. Push the image:
-
-   ```sh
-   docker push quay.io/my-repository/my-plugin:latest
+3. Update `mock-analysis-result.yaml` with the correct Proposal name and UID in `ownerReferences`, then apply:
+   ```bash
+   oc apply -f mock-analysis-result.yaml
    ```
 
-NOTE: If you have a Mac with Apple silicon, you will need to add the flag
-`--platform=linux/amd64` when building the image to target the correct platform
-to run in-cluster.
+4. Patch the Proposal status to reference the AnalysisResult (see comments in `mock-analysis-result.yaml` for the full command).
+
+5. Patch the AnalysisResult status subresource with options data (the `status` field is a subresource, so `oc apply` won't set it — use `oc patch --subresource status`).
 
-## Deployment on cluster
+### Code quality
 
-A [Helm](https://helm.sh) chart is available to deploy the plugin to an OpenShift environment.
+```bash
+yarn lint    # eslint + prettier + stylelint (with --fix)
+yarn test    # Jest unit tests
+```
 
-The following Helm parameters are required:
+### Styling rules
 
-`plugin.image`: The location of the image containing the plugin that was previously pushed
+The `.stylelintrc.yaml` enforces strict rules to prevent breaking console:
 
-Additional parameters can be specified if desired. Consult the chart [values](charts/openshift-console-plugin/values.yaml) file for the full set of supported parameters.
+- No hex colors — use PatternFly CSS variables
+- No naked element selectors (`table`, `div`, etc.)
+- No `.pf-` or `.co-` prefixed classes
+- Prefix all custom classes with `cluster-update-plugin__`
 
-### Installing the Helm Chart
+## Building and deploying
 
-Install the chart using the name of the plugin as the Helm release name into a new namespace or an existing namespace as specified by the `plugin_console-plugin-template` parameter and providing the location of the image within the `plugin.image` parameter by using the following command:
+### Build the image
 
-```shell
-helm upgrade -i  my-plugin charts/openshift-console-plugin -n my-namespace --create-namespace --set plugin.image=my-plugin-image-location
+```bash
+docker build -t quay.io/my-repository/cluster-update-console-plugin:latest .
+# For Apple Silicon: add --platform=linux/amd64
 ```
 
-NOTE: When deploying on OpenShift 4.10, it is recommended to add the parameter `--set plugin.securityContext.enabled=false` which will omit configurations related to Pod Security.
+### Deploy via Helm
 
-NOTE: When defining i18n namespace, adhere `plugin__<name-of-the-plugin>` format. The name of the plugin should be extracted from the `consolePlugin` declaration within the [package.json](package.json) file.
+```bash
+helm upgrade -i cluster-update-console-plugin charts/openshift-console-plugin \
+  -n cluster-update-console-plugin \
+  --create-namespace \
+  --set plugin.image=quay.io/my-repository/cluster-update-console-plugin:latest
+```
 
 ## i18n
 
-The plugin template demonstrates how you can translate messages in with [react-i18next](https://react.i18next.com/). The i18n namespace must match
-the name of the `ConsolePlugin` resource with the `plugin__` prefix to avoid
-naming conflicts. For example, the plugin template uses the
-`plugin__console-plugin-template` namespace. You can use the `useTranslation` hook
-with this namespace as follows:
+The i18n namespace is `plugin__cluster-update-console-plugin`. Use the `useTranslation` hook:
 
 ```tsx
-const Header: React.FC = () => {
-  const { t } = useTranslation('plugin__console-plugin-template');
-  return <h1>{t('Hello, World!')}</h1>;
-};
+import { I18N_NAMESPACE } from '../utils/constants';
+const { t } = useTranslation(I18N_NAMESPACE);
 ```
 
-For labels in `console-extensions.json`, you can use the format
-`%plugin__console-plugin-template~My Label%`. Console will replace the value with
-the message for the current language from the `plugin__console-plugin-template`
-namespace. For example:
-
+For labels in `console-extensions.json`:
 ```json
-  {
-    "type": "console.navigation/section",
-    "properties": {
-      "id": "admin-demo-section",
-      "perspective": "admin",
-      "name": "%plugin__console-plugin-template~Plugin Template%"
-    }
-  }
+"name": "%plugin__cluster-update-console-plugin~Cluster Update%"
 ```
 
-Running `yarn i18n` updates the JSON files in the `locales` folder of the
-plugin template when adding or changing messages.
-
-## Linting
-
-This project adds prettier, eslint, and stylelint. Linting can be run with
-`yarn run lint`.
-
-The stylelint config disallows defining colors since these cause problems with dark
-mode. Use [PatternFly semantic tokens](https://www.patternfly.org/tokens/all-patternfly-tokens)
-for colors instead.
-
-The stylelint config also disallows naked element selectors like `table` and
-`.pf-` or `.co-` prefixed classes. This prevents plugins from accidentally
-overwriting default console styles, breaking the layout of existing pages. The
-best practice is to prefix your CSS class names with your plugin name to avoid
-conflicts. Please don't disable these rules without understanding how they can
-break console styles!
-
-## Reporting
-
-Steps to generate reports
-
-1. In command prompt, navigate to root folder and execute the command `yarn run cypress-merge`
-2. Then execute command `yarn run cypress-generate`
-The cypress-report.html file is generated and should be in (/integration-tests/screenshots) directory.
+Run `yarn i18n` after adding or changing messages to update locale files.
 
 ## References
 
-- [Console Plugin SDK README](https://github.com/openshift/console/tree/main/frontend/packages/console-dynamic-plugin-sdk)
-- [Customization Plugin Example](https://github.com/spadgett/console-customization-plugin)
+- [Console Plugin SDK](https://github.com/openshift/console/tree/main/frontend/packages/console-dynamic-plugin-sdk)
+- [PatternFly React](https://www.patternfly.org/get-started/develop)
+- [Lightspeed Operator](https://github.com/openshift/lightspeed-operator)
 - [Dynamic Plugin Enhancement Proposal](https://github.com/openshift/enhancements/blob/master/enhancements/console/dynamic-plugins.md)

charts/openshift-console-plugin/Chart.yaml

@@ -1,5 +1,5 @@
 apiVersion: v2
-name: openshift-console-plugin
+name: cluster-update-console-plugin
 description: A Helm chart for Kubernetes
 type: application
 version: 0.1.0

locales/en/plugin__cluster-update-console-plugin.json

@@ -70,4 +70,4 @@
   "View pod logs": "View pod logs",
   "Yes": "Yes",
   "z-stream": "z-stream"
-}
+}

src/models/proposal.ts

@@ -218,10 +218,17 @@ export const getAnalysisDataFromResult = (
     return { components: [] };
   }
   const option = result.status.options[0];
-  const raw = (option.components as AnalysisDataPayload)?.analysisData;
+  const comp = option.components;
 
-  // analysisData can be an array of typed components (PR 1379 format)
-  // or a flat object (legacy format)
+  // components is an array of typed adapter components directly
+  if (Array.isArray(comp)) {
+    return {
+      components: comp as AdapterComponent[],
+    };
+  }
+
+  // components is an object — check for nested analysisData key
+  const raw = (comp as AnalysisDataPayload)?.analysisData;
   if (Array.isArray(raw)) {
     return {
       components: raw as AdapterComponent[],