public/harvester-ui-extension
1
0
Fork 0
mirror of https://github.com/harvester/harvester-ui-extension.git synced 2026-05-14 06:51:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add AGENTS.md for AI agent guidance

Browse Source 
Agent-Logs-Url: https://github.com/harvester/harvester-ui-extension/sessions/0fbfe9e7-4362-4af1-abfe-09bdcae85917

Co-authored-by: a110605 <5744158+a110605@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot] 2026-03-31 02:34:53 +00:00 committed by GitHub
parent 9d698b1230
commit fe11c7099e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 241 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
AGENTS.md Normal file
View File

@ -0,0 +1,241 @@
# AGENTS.md
This document provides guidance for AI coding agents (GitHub Copilot, Claude, etc.) working in this repository.
## Project Overview
**harvester-ui-extension** is a [Rancher UI Extension](https://extensions.rancher.io/) that provides the user interface for [Harvester](https://harvesterhci.io) (a hyperconverged infrastructure platform) within [Rancher Dashboard](https://github.com/rancher/dashboard).
- Requires Rancher **2.10.0** or later
- Available as both a Rancher extension and a standalone UI bundle
- Manages virtual machines, volumes, storage, networking, backups, and monitoring
## Technology Stack
| Layer | Technology |
|---|---|
| Language | TypeScript + JavaScript |
| Framework | Vue 3 (via `@rancher/shell`) |
| Build tool | Vue CLI Service (Webpack) |
| Package manager | Yarn |
| Node version | ≥ 20.0.0 (see `.nvmrc`) |
| Linter | ESLint |
| Commit linting | commitlint (conventional commits) |
| Git hooks | Husky |
Key dependencies: `@rancher/shell`, `@vue-flow/*` (graph visualisation), `vue-draggable-next`, `elkjs`, `yaml`.
## Repository Structure
```
harvester-ui-extension/
├── pkg/harvester/ # Main extension source
│ ├── index.ts # Plugin entry point (registers routes, stores, components)
│ ├── types.ts # TypeScript definitions for ~50 HCI resource types
│ ├── routing/
│ │ └── harvester-routing.ts # Route definitions for all pages and resources
│ ├── config/
│ │ ├── harvester.ts # Core constants and configuration
│ │ ├── harvester-cluster.js # Product/cluster configuration
│ │ ├── settings.ts # Settings definitions
│ │ ├── table-headers.js # Column definitions for list views
│ │ └── feature-flags.js # Feature flag definitions
│ ├── models/ # Kubernetes resource model classes (~40+ files)
│ │ │ # Naming: <group>.<domain>.<resource>.js
│ │ └── harvesterhci.io.virtualmachine.js # (example)
│ ├── components/ # Reusable Vue components
│ ├── pages/ # Full-page list/overview components
│ ├── detail/ # Resource detail/view pages
│ ├── edit/ # Resource create/edit form pages
│ ├── dialog/ # Modal and dialog components
│ ├── list/ # List view templates
│ ├── store/ # Vuex store modules
│ │ ├── harvester-common.js # Common state
│ │ └── harvester-store/ # Feature-specific store modules
│ ├── utils/ # Shared utility functions
│ ├── validators/ # Form validation logic
│ ├── formatters/ # UI value formatters
│ ├── mixins/ # Vue mixins
│ ├── styles/ # SCSS/CSS
│ ├── l10n/
│ │ └── en-us.yaml # All UI strings (i18n)
│ ├── package.json # Package-level metadata
│ ├── tsconfig.json # TypeScript config (package level)
│ └── vue.config.js # Vue CLI config (package level)
├── scripts/ # Build and release helper scripts
├── .github/
│ ├── actions/
│ │ ├── setup/ # Node/Yarn setup reusable action
│ │ └── lint/ # Lint reusable action
│ └── workflows/ # CI/CD pipelines
├── .eslintrc.js # ESLint config (extends .eslintrc.default.js)
├── .eslintrc.default.js # Default ESLint rules
├── .eslintignore # ESLint ignore patterns
├── commitlint.config.js # Commit message validation rules
├── tsconfig.json # Root TypeScript config
├── vue.config.js # Root Vue CLI config
├── babel.config.js # Babel config
└── package.json # Root package (Yarn workspaces / scripts)
```
## Development Commands
### Install dependencies
```bash
yarn install
```
Husky git hooks are set up automatically during `yarn install` via the `prepare` script.
### Run in development mode
**Standalone mode** (recommended for UI development, hot reload at `https://localhost:8005`):
```bash
RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev
# Or define variables in a .env file, then:
yarn dev
```
**.env file example:**
```env
RANCHER_ENV=harvester
VUE_APP_SERVER_VERSION=v1.5.0
API=https://192.168.1.123
```
**Rancher integration mode:**
```bash
API=https://<rancher-ip> yarn dev
```
### Build
```bash
yarn build # Production build → dist/
yarn clean # Remove build artifacts
yarn build-pkg # Build as Helm package for Rancher extension
yarn serve-pkgs # Serve packages locally for Rancher extension development
yarn publish-pkgs # Publish packages
```
### Lint
```bash
yarn lint # Report lint errors/warnings (0 warnings allowed — fails on any warning)
yarn lint:fix # Auto-fix lint issues
```
Always run `yarn lint` after making changes to `.js`, `.ts`, or `.vue` files.
### Validate commit messages manually
```bash
yarn commitlint # Validate the last commit
npx commitlint --from <hash> # From a specific commit
npx commitlint --from <start> --to <end> # Range
```
## Commit Message Format
This project enforces [Conventional Commits](https://www.conventionalcommits.org/). Commit messages **must** follow this format:
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
**Rules:**
- `type` must be one of: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`, `wip`, `deps`, `security`
- `scope` (optional) must be kebab-case
- `type` must be lower-case
- `description` must not end with a period
- Body and footer lines must not exceed 100 characters
- A blank line is required between body and footer
- Merge/revert commits are exempt
**Examples:**
```bash
git commit -m "feat: add new virtual machine creation wizard"
git commit -m "fix(vm): resolve memory leak in console component"
git commit -m "docs: update installation instructions"
git commit -m "feat!: change API endpoint structure
BREAKING CHANGE: /api/v1/vms replaced with /api/v2/vms"
```
## Code Style
ESLint with Vue 3 recommended rules and TypeScript support is enforced. Key rules:
- **Indentation:** 2 spaces
- **Quotes:** Single quotes (`'`), template literals allowed
- **Semicolons:** Required
- **Vue components:** Multi-word names required; no `v-html`
- **Max warnings:** 0 — any ESLint warning fails the build
The pre-commit Husky hook runs ESLint automatically before every commit.
## Naming Conventions
| Context | Convention |
|---|---|
| Variables / functions | camelCase |
| Constants | UPPER_CASE |
| Classes / Vue components | PascalCase |
| Vue component files | `PascalCase.vue` (e.g. `HarvesterUpgrade.vue`) |
| Model files | `<group>.<domain>.<resource>.js` (e.g. `harvesterhci.io.virtualmachine.js`) |
| Route/URL slugs | kebab-case |
| Commit scopes | kebab-case |
## Adding / Modifying Resource Models
Resource models live in `pkg/harvester/models/`. Each file exports a class that extends a Rancher shell base class and represents a Kubernetes CRD or resource type. The file name format is `<api-group>.<resource-kind>.js` (dots separate the group segments and the kind).
Resource types (string constants) are defined in `pkg/harvester/types.ts` under the `HCI` object.
## Localization
All user-visible strings must be added to `pkg/harvester/l10n/en-us.yaml`. Use the i18n utilities from `@rancher/shell` to render them in components.
## Branching Model
| Branch | Purpose |
|---|---|
| `main` | Main development branch |
| `release-harvester-vX.Y` | Stable release branch per version series |
| `vX.Y-head` | Auto-generated testing branch (kept in sync with release branch) |
## CI/CD
Workflows are in `.github/workflows/`. Key pipelines:
| Workflow | Trigger | Purpose |
|---|---|---|
| `run-lint.yaml` | Push/PR to `main`, `release-*` | ESLint + commitlint validation |
| `build-extension-on-merge.yml` | Push to `main`/`release-harvester-v*` | Build and publish extension Helm charts |
| `build-standalone-on-merge.yaml` | Push/PR merge | Build standalone UI bundle |
| `build-extension-on-release.yml` | Release published | Create release extension artifacts |
| `build-standalone-on-release.yaml` | Release published | Create release standalone artifacts |
| `build-extension-catalog.yml` | Dispatch / release | Build Docker catalog image |
| `backport-request.yaml` | PR labeled | Create backport PR |
## Testing
There is no automated unit/integration test suite. Validation is done by:
1. Running `yarn lint` — ensures code quality.
2. Manual testing via **standalone mode** (see Development Commands above).
3. Manual testing via **Rancher extension** (register via Rancher UI Repositories).
For testing a specific release series, use the corresponding `vX.Y-head` branch as the Rancher extension repository URL.
## TypeScript Path Aliases
| Alias | Resolves to |
|---|---|
| `~/` or `@/` | Project root |
| `@shell/` | `@rancher/shell` modules |
## License
Apache License 2.0. Copyright (c) 2014–2026 SUSE, LLC.