Merge pull request #219 from ronlavi2412/contextification

Add project documentation and rewrite README

Author: openshift-merge-bot[bot]

.coderabbit.yaml

@@ -0,0 +1,56 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.yaml
+
+language: en-US
+tone_instructions: >
+  Be concise and direct. Focus on correctness, SDK compatibility, and PatternFly
+  best practices. This is an OpenShift console dynamic plugin — flag any direct
+  K8s API calls, missing i18n (must use useNMStateTranslation hook or Trans
+  component), or incorrect extension registration.
+
+reviews:
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: true
+  path_instructions:
+    - path: "src/views/**/manifest.ts"
+      instructions: >
+        These files register plugin extensions with the OpenShift console.
+        Verify that EncodedExtension types match the extension type string,
+        ExposedModules paths resolve to real files, and nav items include
+        both admin and virtualization perspectives where appropriate.
+    - path: "src/console-models/**"
+      instructions: >
+        K8s model definitions. Verify apiGroup, apiVersion, kind, and plural
+        are correct for the CRD. Ensure GroupVersionKind and Ref exports exist
+        and the model is re-exported from index.ts.
+    - path: "src/views/**/*.tsx"
+      instructions: >
+        React components must use PatternFly 6 components and PF utility classes,
+        functional components with FC typing, and useNMStateTranslation() for
+        simple user-visible strings or the Trans component for strings with
+        embedded HTML. No hardcoded English text in JSX. Each file should contain
+        only a single component.
+    - path: "src/utils/components/**/*.tsx"
+      instructions: >
+        Shared React components must use PatternFly 6 components and PF utility
+        classes, functional components with FC typing, and useNMStateTranslation()
+        for simple user-visible strings or the Trans component for strings with
+        embedded HTML. No hardcoded English text in JSX. Each file should contain
+        only a single component.
+    - path: "src/utils/resources/**"
+      instructions: >
+        Resource utilities must use SDK hooks (useK8sWatchResource) and SDK
+        mutation functions (k8sCreate, k8sPatch, k8sDelete). No direct fetch
+        calls to the K8s API.
+  path_filters:
+    - "!package-lock.json"
+    - "!locales/**"
+    - "!src/nmstate-types/crds/**"
+    - "!dist/**"
+    - "!node_modules/**"
+    - "!i18n-scripts/**"
+  auto_review:
+    enabled: true
+    drafts: false

.cursor/rules/nmstate-console-plugin.mdc

@@ -0,0 +1,27 @@
+---
+description: AI context for nmstate-console-plugin — OpenShift console dynamic plugin for kubernetes-nmstate
+globs:
+alwaysApply: true
+---
+
+# nmstate-console-plugin
+
+OpenShift console dynamic plugin for kubernetes-nmstate. Provides UI views for policies, states, physical networks, and topology visualization.
+
+## Key Context Files
+
+- [AGENTS.md](../../AGENTS.md) — repo structure, key patterns, conventions, review guidelines
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — system design, plugin registration, data flow, dependencies
+- [CONTRIBUTING.md](../../CONTRIBUTING.md) — coding standards, linting rules, PR process
+
+## Conventions
+
+- **Components:** functional only, typed with `FC`, use PatternFly 6, default export for pages
+- **i18n:** `useNMStateTranslation()` or `Trans` component for all user-visible strings, never hardcode English
+- **Imports:** sorted by `eslint-plugin-simple-import-sort` — React → external packages → internal `src/` → `@kubevirt-ui` → `@openshift-console` → `@patternfly` → CSS
+- **Path aliases:** `@utils/*`, `@models`, `@images/*`
+- **K8s data:** SDK hooks only (`useK8sWatchResource`, `k8sCreate`, `k8sPatch`) — no direct API calls
+- **Models:** one file per K8s resource in `src/console-models/`, export `GroupVersionKind` + `Ref`, re-export from `index.ts`
+- **Views:** each view has `manifest.ts` with `ExposedModules` + `Extensions`, aggregated in `plugin-manifest.ts`
+- **Linting:** ESLint + Prettier, single quotes, trailing commas, 100-char width, `simple-import-sort`
+- **Testing:** Jest (`npm test`), Cypress e2e (`npm run cypress`), mock SDK + i18n via `src/__mocks__/`

AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md
+
+AI-specific guidance for working with the nmstate-console-plugin codebase.
+
+## Project Overview
+
+This is an OpenShift console dynamic plugin for kubernetes-nmstate. It provides UI views for managing node network configuration policies, states, physical networks, and topology visualization.
+
+**Stack:** React 18, TypeScript, PatternFly 6, OpenShift Dynamic Plugin SDK, Webpack, i18next
+
+## Repository Structure
+
+```text
+src/
+├── console-models/          # K8s resource model definitions (K8sModel objects)
+├── nmstate-types/            # NMState CRD types and custom models
+├── utils/
+│   ├── components/           # Shared UI components (Loading, HelpTextIcon, etc.)
+│   ├── hooks/                # Shared React hooks (useNMStateTranslation, etc.)
+│   ├── flags/                # Feature flag detection (NMState operator presence)
+│   ├── resources/            # K8s resource fetching utilities
+│   └── telemetry/            # Usage tracking
+├── views/
+│   ├── policies/             # NodeNetworkConfigurationPolicy CRUD
+│   │   ├── manifest.ts       # Plugin extension registration
+│   │   ├── list/             # List page component
+│   │   ├── details/          # Details page component
+│   │   ├── new/              # Create/edit form
+│   │   ├── actions/          # Action menu items
+│   │   └── components/       # Policy-specific UI components
+│   ├── states/               # NodeNetworkState list + details
+│   ├── physical-networks/    # Physical network overview
+│   └── nodenetworkconfiguration/  # Topology visualization (PatternFly Topology)
+├── __mocks__/                # Jest mocks for SDK and i18n
+└── plugin-manifest.ts        # Root plugin metadata and extension aggregation
+```
+
+## Key Patterns
+
+### Plugin extension registration
+
+Each view has a `manifest.ts` that exports:
+- `{View}ExposedModules` — maps module names to file paths for code splitting
+- `{View}Extensions` — array of `EncodedExtension` objects defining console nav items, pages, and templates
+
+These are aggregated in the root `plugin-manifest.ts`.
+
+### K8s resource models
+
+Models live in `src/console-models/` as individual files exporting `K8sModel` objects. Each model defines `apiGroup`, `apiVersion`, `kind`, `plural`, and a `GroupVersionKind` constant. Import models via `@models` path alias.
+
+### Path aliases
+
+Defined in `tsconfig.json`:
+- `@images/*` → `images/*`
+- `@utils/*` → `src/utils/*`
+- `@models` → `src/console-models/index.ts`
+
+### React components & i18n
+
+For coding standards (component rules, PatternFly usage, i18n, linting), see [CONTRIBUTING.md](CONTRIBUTING.md#coding-standards).
+
+Key details for code generation:
+- Translation keys use the `plugin__nmstate-console-plugin~` prefix
+- In manifest files, use `%plugin__nmstate-console-plugin~Label%` syntax for nav item names
+- Shared hooks (used in 2+ components) live in `src/utils/hooks/`; single-use hooks must be co-located with the component that uses them — do not add to shared utils
+- One component per file — utility functions, types (aside from props), and constants go in a `utils/` folder within the component's directory
+- Prefer PatternFly utility classes (e.g., `pf-v6-u-mt-md`) over custom CSS for spacing and layout
+
+### State management
+
+- No global state library — uses OpenShift SDK's `useK8sWatchResource` for K8s data
+- Local component state via React `useState`/`useReducer`
+
+## Conventions
+
+For full coding standards, linting rules, testing, and PR process, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### File & directory naming
+- React components: `PascalCase.tsx`
+- Utilities, hooks, constants: `camelCase.ts`
+- Directories for components use PascalCase, directories for hooks use camelCase, all other directories use kebab-case
+- Each view directory has a `manifest.ts`, `constants.ts`, and optionally `utils.ts`
+
+### Deployment
+- Webpack builds the plugin as a dynamic console remote module
+- Deployed via Helm chart (`deployment/nmstate-console-plugin/`) or OpenShift templates (`oc-manifest.yaml`)
+- Container images published to `quay.io/nmstate/nmstate-console-plugin`
+
+## Review Guidelines
+
+When reviewing changes to this codebase:
+
+1. **SDK compatibility** — verify that `@openshift-console/dynamic-plugin-sdk` APIs are used correctly; the SDK version must match the target release branch (e.g., `release-4.22` uses SDK 4.22.x)
+2. **i18n** — all user-visible strings must use the `useNMStateTranslation` hook or the `Trans` component; never hardcode English text
+3. **PatternFly** — use PatternFly components and PF utility classes instead of custom HTML/CSS; follow PatternFly 6 patterns
+4. **Type safety** — `strict` is `false` in tsconfig, but new code should use explicit types
+5. **Model consistency** — new K8s resources need a model in `console-models/`, a manifest entry, and registration in `plugin-manifest.ts`
+6. **No direct K8s API calls** — use the OpenShift SDK hooks (`useK8sWatchResource`, `k8sCreate`, `k8sPatch`, etc.)
+7. **Component isolation** — one component per file; single-use hooks stay co-located with their component, not in shared `utils/hooks/`
+8. **Naming conventions** — new resource utility files should use `selectors.ts` (not `getters.ts`); some older directories still use `getters.ts` but the project is migrating to the `selectors` naming