harvester-ui-extension/AGENTS.md

This ./AGENTS.md file is generated by running yarn agents:generate.

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

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.
    • Place source tag above template above style.
    • style tag should contain 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

1. 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/config/feature-flags to ensure the UI matches the cluster's specific version.

2. Implementation Steps for New Features To add a feature in a new release, follow these steps:

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

   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]');
     },
   },
   

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

E2E Tests (Cypress)

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

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>[optional scope]: <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