harvester-ui-extension/AGENTS.md

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 that provides the user interface for Harvester (a hyperconverged infrastructure platform) within 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

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):

RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev

# Or define variables in a .env file, then:
yarn dev

.env file example:

RANCHER_ENV=harvester
VUE_APP_SERVER_VERSION=v1.5.0
API=https://192.168.1.123

Rancher integration mode:

API=https://<rancher-ip> yarn dev

Build

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

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

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. 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:

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.