Skip to content

AGENTS.md

Latest commit

 

History

History
148 lines (113 loc) · 5.3 KB

AGENTS.md

File metadata and controls

148 lines (113 loc) · 5.3 KB

AI Agents Guide

Basic guardrails and quick-start for AI coding agents contributing to this repository.

Overview

  • This repo is an OpenShift Console dynamic plugin for the OpenShift Lightspeed (OLS) chat UI
  • See README.md for general project instructions

Architecture

This plugin adds an AI chat assistant (OpenShift Lightspeed) to the OpenShift web console. It runs as a dynamic plugin, meaning the console discovers and loads it at runtime. The main UI is a floating popover chat window that appears over any console page.

Entry points: console-extensions.json declares the OpenShift web console extensions used by this plugin.

API proxy: All requests to the OLS backend API go through the console's built-in plugin proxy at /api/proxy/plugin/lightspeed-console-plugin/ols. This avoids CORS issues and leverages the console's authentication.

Data flow

The user types a prompt and optionally attaches context from the Kubernetes resource they are currently viewing (YAML, logs, events). The prompt is sent as a streaming request to the OLS backend API via the console's API proxy. Tokens are streamed back and rendered incrementally in the chat window.

All conversation state (chat history, attachments, etc.) is managed in Redux.

Code structure

  • Frontend React code lives in src/ (TypeScript/React)
    • React components in src/components/
    • React hooks in src/hooks/
    • Redux code in src/
  • Put images and other assets in src/assets/
  • Modules and extensions exposed by the plugin are added to console-extensions.json
  • End-to-end tests live in tests/ and cypress/
  • Unit tests live in unit-tests/

Coding style

  • Use TypeScript and ES6 syntax for all code
  • Prefer meaningful, descriptive names and early returns
  • Prefer functional coding patterns
  • Avoid excessive comments that add little value
  • End lines with semicolons
  • Prefer single quotes for strings
  • Further coding style details are defined in .eslintrc.yml and .prettierrc.yml

Linting

  • ALWAYS use npm run lint-fix instead of npm run lint. The lint-fix command automatically fixes most ESLint, Prettier, and Stylelint issues
  • Only use npm run lint if you specifically need to check for errors without fixing them

CSS

  • Stylelint is used for CSS linting
  • Use class names prefixed with ols-plugin__ for all styling rules
    • Strictly limiting all CSS to styling ols-plugin__* classes avoids any conflicts with the default PatternFly and web console styles
  • We disallow hex colors because PatternFly design tokens should be used instead
  • CSS lint rules are defined in .stylelintrc.yaml

i18n

  • We use the react-i18next internationalization framework
  • i18n JSON files are in locales/
  • Use i18n for all user-facing strings by wrapping them in t('...') translation calls
  • All translations should use the namespace plugin__lightspeed-console-plugin
  • After adding or changing UI text, update locale files by running npm run i18n

Running

  • Dependencies are installed by running npm install
  • To run the project locally:
    • Run npm run start in one terminal
      • Starts the dev server for the plugin on port 9001
    • Run npm run start-console in a second terminal
      • Run the OpenShift web console container connected to your current cluster
      • Requires prior oc login
  • For local development and testing, the lightspeed-service is expected to be running on http://localhost:8080
    • The start-console.sh script includes a proxy configuration that routes requests through the console, avoiding CORS issues

End-to-end tests (Cypress)

  • To run all tests: npm run test-headless
  • To run just some tests filtered by tag: npm run test-headless -- --expose grepTags="@attach"
  • See tests/README.md for full details and environment variables

Unit tests

  • Unit tests live in unit-tests/ and use Node's built-in test runner
  • To run: npm run test:unit

Do not commit

  • Secrets or tokens (e.g., OLS_API_BEARER_TOKEN)
  • node_modules/, build artifacts in dist/, or test output in gui_test_screenshots/

PR checklist

  • Apply lint rules: npm run lint-fix
  • Update i18n strings: npm run i18n
  • Ensure build works: npm run build
  • Ensure unit tests pass: npm run test:unit
  • Ensure tests pass: npm run test-headless

Git and PR Workflow

Commit Messages

  • Start with the Jira ticket reference: OLS-XXXX description
  • Keep the first line under 72 characters
  • Use imperative mood

Pull Requests

This repo uses a fork-based workflow:

  1. Push to your fork, not to origin (openshift/lightspeed-console)
  2. Create the PR against origin/main using your fork's branch: 
    git push <your-fork-remote> <branch>
gh pr create --repo openshift/lightspeed-console --head <your-github-user>:<branch> --base main
  3. PR title must start with the Jira reference: OLS-XXXX description
  4. Squash commits before pushing -- one logical commit per PR unless the PR explicitly tracks multiple independent changes

Branch Completion

When finishing a development branch:

  1. Remove any process artifacts (design docs, plans in docs/superpowers/)
  2. Squash commits with the Jira-prefixed message
  3. Push to the contributor's fork remote (not origin)
  4. Create the PR against origin/main using --head <user>:<branch>