diff --git a/AGENTS.md b/AGENTS.md index 90a8a67f2e3..257310b6f7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,15 +19,18 @@ All AI assistants reference these files to understand: ```bash # Clone & install git clone https://github.com/openshift/console.git && cd console -make install # yarn + go deps +cd frontend && yarn install # Development server -make start +cd frontend && yarn dev # Core commands -make lint # ESLint + Prettier -make test # Jest unit + Cypress E2E -make build # Production build +cd frontend && yarn lint # ESLint + Prettier +cd frontend && yarn test # Jest unit tests +./build-frontend.sh # Production build + +# Full build (frontend + backend) +./build.sh ``` ### Frontend Development Commands @@ -57,16 +60,19 @@ make build # Production build **REQUIRED FOR ALL CODING AGENTS: Before generating or modifying code, always consult the relevant file(s) to ensure full compliance. These files are the single source of truth for architecture, coding standards, and testing.** - +**General:** - **[ARCHITECTURE.md](ARCHITECTURE.md)** - **[CONVENTIONS.md](CONVENTIONS.md)** - **[TESTING.md](TESTING.md)** - **[README.md](README.md)** - **[CONTRIBUTING.md](CONTRIBUTING.md)** -- **[STYLEGUIDE.md](STYLEGUIDE.md)** -- **[INTERNATIONALIZATION.md](INTERNATIONALIZATION.md)** +- **[STYLEGUIDE.md](STYLEGUIDE.md)** +- **[INTERNATIONALIZATION.md](INTERNATIONALIZATION.md)** + +**Plugin Development:** +- **[frontend/packages/console-dynamic-plugin-sdk/README.md](frontend/packages/console-dynamic-plugin-sdk/README.md)** - Comprehensive dynamic plugin SDK documentation **Tool-specific:** -- Claude → [CLAUDE.md](CLAUDE.md) and `.claude/` -- Cursor → `.cursor/context.md` +- Claude → [CLAUDE.md](CLAUDE.md) and `.claude/` +- Cursor → `.cursor/context.md` - CodeRabbit → [coderabbit.yaml](coderabbit.yaml) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index bc0facd028c..2778e3bdc33 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -5,56 +5,30 @@ The `console-dynamic-plugin-sdk` is a key part of this repository - it's the public API that enables OpenShift Console's extensibility. ## Key Packages & Areas + +**Core Packages:** - **console-dynamic-plugin-sdk**: Public API for external plugins (⚠️ breaking changes require careful vetting) -- **dev-console**: Developer perspective, topology, add flows -- **pipelines-plugin**: Tekton pipelines integration -- **knative-plugin**: Serverless/Knative support -- **helm-plugin**: Helm chart management -- **topology**: Application topology views +- **console-app**: Main application that loads all plugins - **console-shared**: Shared utilities and components +- **console-internal**: Core UI and Kubernetes integration + +**Dynamic Plugins:** +For the complete list of console plugins, see `console-app/package.json` dependencies. Static plugins (built-in) may be deprecated or extracted over time. - **Extension Points System**: 25+ extension types (NavItem, Page, ResourceListPage, DashboardsCard, etc.) - **Module Federation**: Runtime plugin loading via Webpack Module Federation - **Type Safety**: Comprehensive TypeScript definitions for all extension points - **Code References**: Lazy loading with `$codeRef` for performance -### Key Extension Types (reference) - -| Category | Types | Purpose | -|----------------|------------------------------------------------------------|----------------------------------| -| Navigation | NavItem, HrefNavItem, Separator | Sidebar / top nav | -| Pages | Page, RoutePage, StandaloneRoutePage | Full or nested pages | -| Resources | ModelDefinition, ResourceListPage, ResourceDetailsPage | CRUD views | -| Actions | ActionGroup, ResourceActionProvider | Kebab / row menus | -| Dashboards | DashboardsCard, DashboardsTab | Overview health cards | -| Catalog | CatalogItemType, CatalogItemProvider | Operator / Helm catalog | -| Perspectives | Perspective, PerspectiveContext | Top-level views | - - -### Plugin Structure -```typescript -// GOOD – Dynamic extensions (runtime-loaded) -export const plugin: Plugin = [ - { - type: 'Page', - properties: { - exact: true, - path: '/my-plugin-page', - component: { $codeRef: 'MyPluginPage' }, // Lazy-load reference - }, - }, - { - type: 'NavItem', - properties: { - section: 'home', - componentProps: { name: 'My Plugin', href: '/my-plugin-page' }, - }, - }, -]; - -// BAD – Static (avoid—breaks extensibility) -export const staticPlugin = { extensions: [...] }; -``` +### Official Extension Types & API Documentation + +OpenShift Console provides 75+ extension types for plugin integration. **For comprehensive documentation, see [frontend/packages/console-dynamic-plugin-sdk/README.md](frontend/packages/console-dynamic-plugin-sdk/README.md).** + +**Before working with extensions or the plugin API, you MUST read:** +- **[Extension Types Reference](frontend/packages/console-dynamic-plugin-sdk/docs/console-extensions.md)** - Complete extension type definitions, naming conventions (`console.*`), and deprecation notices +- **[Console API Documentation](frontend/packages/console-dynamic-plugin-sdk/docs/api.md)** - React components, hooks, utilities, and TypeScript types exported by the SDK + +Common extension categories include navigation, pages, resources, actions, dashboards, catalog, and perspectives. ### Critical Considerations - **⚠️ BREAKING CHANGES REQUIRE EXTREME CARE**: This is a public API consumed by external plugins @@ -64,28 +38,15 @@ export const staticPlugin = { extensions: [...] }; - **Type Safety**: Strong TypeScript support prevents runtime errors ### ⚠️ Public API Sources - Breaking Change Risk -The dynamic plugin SDK re-exports APIs from multiple Console packages. **Changing these source modules could inadvertently break the public API**: -#### APIs Re-exported from `@console/shared` -- **Dashboard Components**: `ActivityItem`, `ActivityBody`, `RecentEventsBody`, `OngoingActivityBody`, `AlertsBody`, `AlertItem`, `HealthItem`, `HealthBody`, `ResourceInventoryItem`, `UtilizationItem`, `UtilizationBody`, `UtilizationDurationDropdown`, `VirtualizedGrid`, `LazyActionMenu` -- **UI Components**: `Overview`, `OverviewGrid`, `InventoryItem`, `InventoryItemTitle`, `InventoryItemBody`, `InventoryItemStatus`, `InventoryItemLoading`, `StatusPopupSection`, `StatusPopupItem`, `DocumentTitle`, `Timestamp`, `ActionServiceProvider`, `ErrorBoundaryFallbackPage`, `QueryBrowser` -- **Hooks**: `useUtilizationDuration`, `useDashboardResources`, `useUserSettings`, `useAnnotationsModal`, `useDeleteModal`, `useLabelsModal`, `useActiveNamespace`, `useQuickStartContext` -- **Other**: `PaneBody` (via `ListPageBody`) +The dynamic plugin SDK re-exports APIs from multiple Console packages: +- **`@console/shared`** - Dashboard components, UI components, hooks +- **`@console/internal`** - Core UI, editors, hooks, K8s utilities +- **`@console/plugin-sdk`** - Extension system, plugin infrastructure +- **`@console/app`** - Application context +- **`@console/topology`** - Topology components, data transforms, graph views -#### APIs Re-exported from `@console/internal` -- **Core UI**: `HorizontalNav`, `VirtualizedTable`, `TableData`, `ListPageHeader`, `ListPageCreate`, `ListPageCreateLink`, `ListPageCreateButton`, `ListPageCreateDropdown`, `ListPageFilter`, `ResourceLink`, `ResourceIcon`, `ResourceEventStream`, `NamespaceBar` -- **Editors**: `YAMLEditor`, `CodeEditor`, `ResourceYAMLEditor` -- **Hooks**: `useActiveColumns`, `useListPageFilter`, `usePrometheusPoll`, `useURLPoll` -- **K8s Utilities**: Redux store access, HTTP utilities - -#### APIs Re-exported from `@console/plugin-sdk` -- **Extension System**: `useExtensions` (via `useResolvedExtensions`) -- **Plugin Infrastructure**: Plugin loading, subscription services, store management - -#### APIs Re-exported from `@console/app` -- **Application Context**: `QuickStartsLoader`, `useLastNamespace` - -**Before modifying any of these source packages, verify impact on the dynamic plugin SDK public API.** +**BEFORE MODIFYING ANYTHING IN THESE OR OTHER PACKAGES:** Verify SDK re-exports by checking `frontend/packages/console-dynamic-plugin-sdk/src/api/internal-*.ts` files to avoid breaking the public API. ### SDK Utilities - **Resource Hooks**: `useK8sWatchResource`, `useActivePerspective`, `useActiveNamespace` @@ -93,8 +54,10 @@ The dynamic plugin SDK re-exports APIs from multiple Console packages. **Changin - **Build Integration**: `ConsoleRemotePlugin` for Webpack Module Federation ### Development Guidelines + +**SDK-Specific:** - Always consider impact on external plugin developers -- Extensive testing required for any API changes -- Clear deprecation paths with version-based removal +- Maintain backward compatibility as it's a public API - Comprehensive documentation for all public APIs -- Performance monitoring for plugin loading \ No newline at end of file + +**For detailed plugin API review guidelines and workflow, see [.claude/commands/plugin-api-review.md](.claude/commands/plugin-api-review.md)** \ No newline at end of file diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 5c91a51dae7..2255c77ba31 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -12,10 +12,10 @@ - **Routing**: Plugin routes go in plugin-specific route files - **Extensions**: Use console extension points for plugin integration - **Types**: Check existing types in `console-shared` before creating new ones -- **Dynamic Plugins**: Prefer implementing new features using the console dynamic plugin SDK (`frontend/packages/console-dynamic-plugin-sdk/`) for extensibility +- **Dynamic Plugins**: Use console extension points for plugin integration. The dynamic plugin SDK is a re-export layer - implement new features in source packages (`@console/shared`, `@console/internal`, etc.) first, refine them internally, then consider re-exporting to the SDK after stabilization - **Plugin SDK Changes**: Any updates to `console-dynamic-plugin-sdk` must maintain backward compatibility as it's a public API - **Styling**: SCSS modules co-located with components, PatternFly design system components -- **i18n**: Use `useTranslation()` hook with `%namespace~key%` format for translation keys +- **i18n**: Use `useTranslation('namespace')` hook with `key` format for translation keys - **Error Handling**: Use ErrorBoundary components and graceful degradation patterns - **File Naming**: PascalCase for components, kebab-case for utilities, `*.spec.ts(x)` for tests @@ -35,7 +35,7 @@ - **Interfaces**: Define clear interfaces for testability and dependency injection ### Code Quality -- **Use modern JavaScript** +- **Use modern JavaScript (ES6+):** Prefer const/let, arrow functions, async/await, destructuring, template literals, optional chaining, and array methods - **Add comments for complex logic** ### Performance