harvester-ui-extension/AGENTS.md

This ./AGENTS.md file is generated by running yarn agents:generate. CLAUDE.md and GEMINI.md are symlinks to this file so Claude Code, GitHub Copilot and Gemini all read the same content.

Project Overview

The Harvester UI Extension is a Rancher extension that provides the user interface for Harvester within the Rancher Dashboard.

Note: This extension is available starting from Rancher 2.10.0. Ensure your Rancher version is 2.10.0 or later to access Harvester integration.

Personas

Software Developer

You are an expert Senior Software Engineer specializing in Vue.js and TypeScript. You have deep knowledge of Kubernetes and the Rancher ecosystem.

• Focus: Writing clean, maintainable, and performant code.
• Priorities: Adhering to the project's code style, ensuring type safety, and following best practices for component design.

Agents

Boundaries

• ✅ Always:
  • Write to .github, docs/, pkg/harvester, scripts/.
  • Make commits in a new branch (for a PR).
  • Run yarn lint:fix before commits.
    • Use conventional commit format:

    <type>: <description>
    

  • Follow existing naming conventions (PascalCase for components, camelCase for functions).
  • After changing a Vue, JS, or TS file, make sure it's automatically formatted with ESLint.
  • After updating files in docs/agents.md/, run yarn agents:generate to update root AGENTS.md.
• ⚠️ Ask first:
  • Adding dependencies
  • Upgrading dependencies
• 🚫 Never:
  • Commit or log secrets, .env, kubeconfig or any API keys.
  • Edit node_modules/.
  • Commit directly to main (use PRs).
  • Skip git hooks with --no-verify flag.

Tools

Prerequisites

• Node.js: >= 24.0.0 (see .nvmrc for the pinned version: 24)
• Package manager: yarn (v1 classic)

Common Commands

Command	Description
yarn install --frozen-lockfile	Install dependencies (CI-safe, no lockfile changes)
RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev	Start development server at https://127.0.0.1:8005
yarn build-pkg harvester	Build the Harvester extension package
yarn serve-pkgs	Serve the locally built extension for testing
yarn lint	Run ESLint (zero warnings allowed)
yarn lint:fix	Run ESLint with auto-fix
yarn test	Run the unit tests (Jest) in watch mode
yarn test:ci	Run the unit tests once, as CI does (silent)
yarn clean	Clean build artifacts
yarn agents:generate	Regenerate AGENTS.md from docs/agents.md/ sources

Development

• Start dev server:

  RANCHER_ENV=harvester API=https://your-harvester-ip yarn dev
  

  • API should point to a running Harvester cluster (e.g., https://x.x.x.x).
  • The dashboard will be available at https://127.0.0.1:8005.

Building

• Build extension package:

  yarn build-pkg harvester
  

• Serve locally built extension (for integration testing with a Rancher instance):

  yarn serve-pkgs
  

Linting

• Check (must pass with zero warnings):

  yarn lint
  

• Auto-fix:

  yarn lint:fix
  

• ESLint covers .js, .ts, and .vue files.
• Always run yarn lint:fix before committing.

Unit Tests

• Run:

  yarn test
  

  • yarn test starts Jest in watch mode (like in the Rancher dashboard) and only runs the tests related to changed files. It does not exit, so use yarn test:ci for a single run of all tests, e.g. in scripts.
• CI runs yarn test:ci on every pull request.
• See the Unit Tests section of the Contributors Guide for how the tests are set up.

Commit Conventions

• Commits are validated by commitlint via a Husky commit-msg hook.
• Follow Conventional Commits format (configured in commitlint.config.js).

Agent Documentation

• Source files live in docs/agents.md/ (agents, contributors, personas subdirectories).
• After editing any source file, regenerate the root AGENTS.md:

  yarn agents:generate
  

Contributors Guide

Getting Started

Please see the Harvester UI Extension README.

To get started, follow the Development Setup section.

Project Information

• Tech Stack:

  • Vue.js: Framework
  • Linting: ESLint
  • CSS: SCSS should be used
  • TypeScript: Primary language for logic.

• Code Style and Standards:

  • Language: TypeScript is preferred for new code.
  • Vue.js:
    • Composition API components are preferred over Options API.
    • Large pages with lots of code and styles should be avoided by breaking the page up into smaller Vue components.
    • Order the Single File Component blocks as <script>, then <template>, then <style>.
    • The <style> tag should include lang="scss" scoped.
  • Linting: Follow the ESLint configuration in the root.

• File Structure:

  • .github/: CI/CD workflows and Renovate config.
  • docs/: Documentation source for AGENTS.md generation.
  • scripts/: Bash scripts for build, CI and doc generation.
  • pkg/harvester/: Main extension source. Files are named after K8s resource types (e.g., kubevirt.io.virtualmachine, harvesterhci.io.volume).
    • index.ts: Plugin entry point — registers the product and auto-imports models/detail/edit views.
    • types.ts: HCI constant mapping 60+ K8s resource types to string identifiers.
    • components/: Reusable Vue components (VNC/serial console, settings panels, upgrade banners, filters).
    • config/: Constants — settings keys, table column definitions, feature flags, type mappings, doc links.
    • detail/: Read-only detail views per resource type. Complex resources use subdirectories with tabs.
    • dialog/: Modal dialogs for operations (VM clone/migrate/restart, backup/restore, device passthrough, etc.).
    • edit/: Create/edit forms. Complex resources (e.g., VM) split into subcomponents (CpuMemory, Network, Volume, CloudConfig, etc.).
    • formatters/: Table cell formatters — state badges, usage bars, resource references.
    • l10n/: Localization (en-us.yaml).
    • list/: List (table) views per resource type, mirroring detail/ and edit/ naming.
    • mixins/: Shared Vue mixins — VM helpers (harvester-vm/) and disk helpers (harvester-disk.js).
    • models/: Model classes extending SteveModel with computed properties and actions. Base class: harvester.js.
    • pages/: Route-level pages — dashboard, support, console, members, brand, alertmanager.
    • promptRemove/: Custom delete-confirmation dialogs (VM, backup).
    • routing/: Vue Router config — all product routes (CRUD, console, support, upgrade, etc.).
    • store/: Vuex modules — harvester-common.js for shared state; harvester-store/ for VM/resource creation actions with Steve integration.
    • styles/: Global SCSS files.
    • utils/: Helpers — VM volume templates, CPU/memory calc, cron parsing, regex validators, feature flags.
    • validators/: Form validation functions per resource type, pushing i18n error messages.

Harvester UI Extension Development Guide

Backward Compatibility

The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in pkg/harvester/config/ to ensure the UI matches the cluster's specific version.

Implementation Steps for New Features

To add a feature in a new release, follow these steps:

1. Register: Add a unique [Feature Name] to the corresponding release array in the configuration.

2. Check: Use the following getter to verify if the feature is enabled for the current version:

   computed: {
     newFeatureEnabled() {
       return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
     },
   },
   

3. Render: Use the result of the check to conditionally render the UI components.

E2E Tests (Cypress)

See https://github.com/harvester/harvester-ui-tests

Unit Tests (Jest)

Unit and component tests run with Jest. The setup follows the Rancher dashboard and the Rancher extension template (rancher/ui-plugin-examples), so both stay aligned.

• Run the tests in watch mode with yarn test, all tests once with yarn test:ci, a single file with yarn test <path>. CI runs yarn test:ci on every pull request.
• Test files live next to the code in __tests__ folders and are named <name>.test.js or <name>.test.ts.
• Configuration:
  • jest.config.js: environment, module aliases (@shell, @components, @pkg) and transforms.
  • jest.setup.js: global mocks (t, $store, common directives) and browser APIs that jsdom does not provide.
  • vue3JestRegisterTs.js: makes TypeScript available to the Vue compiler, otherwise .vue files with typed props fail to compile.
• Components are tested with the Vue Test Utils 2 API: use props and global.mocks, not the Vue 2 options propsData and mocks.
• Models and utils can be tested without mounting anything, see pkg/harvester/models/__tests__ for examples.

Node Dependencies

Dependencies are managed via package.json and yarn

• To install dependencies use yarn install. This will fail if dependencies and versions listed in package.json are out of step with the yarn.lock file
• To add a dependency use yarn run add:no-lock ... instead of yarn add
• To upgrade a dependency use yarn run upgrade:no-lock ... instead of yarn upgrade

Renovate automatically updates dependencies and opens upgrade PRs after 10:00 AM on Sundays (Asia/Taipei). For the Renovate config, see .github/renovate.json.

Milestone guidance

• All issues must first be resolved in the main branch
• If backports are needed they can be made via the backport bot
  • pull requests
    • comment @Mergifyio backport <target branch> e.g. @Mergifyio backport release-harvester-v1.8
    • All backported pull requests must link to a backported issue

Creating a branch

To resolve an issue

• Checkout the branch matching the milestone of the issue git checkout ${targetMilestoneBranch}. Replace ${targetMilestoneBranch} with the target milestone of the issue. For example
  • main for the latest unreleased minor version
  • release-harvester-v.X for release minor versions
    • release-harvester-v1.6
    • release-harvester-v1.7
    • release-harvester-v1.8
• Ensure you have the latest of that branch git pull --rebase
• Checkout the branch to commit the changes to git checkout issue-${issueNumber}. Replace ${issueNumber} with the issue number.

Creating a commit

• This project uses commit-lint with Conventional Commits to ensure consistent and meaningful commit messages.

Commit Message Format

All commit messages must follow the conventional commit format:

<type>: <description>

[optional body]

[optional footer(s)]

Supported Types

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes (formatting, missing semicolons, etc.)
• refactor: Code refactoring
• perf: Performance improvements
• test: Adding or updating tests
• build: Build system or external dependencies
• ci: CI/CD changes
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• wip: Work in progress
• deps: Dependency updates
• security: Security fixes

Creating a Pull Request

• Pull requests must come from forks
• Description should always have commit supported type prefix. E.g fix: XXX, feat: OOO
• A Pull Request will only be merged once
  • ALL CI gates have passed
  • At least one harvester/harvester-ui-extension code owners reviews and approves the PR