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**:
  ```bash
  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**:
  ```bash
  yarn build-pkg harvester
  ```
- **Serve locally built extension** (for integration testing with a Rancher instance):
  ```bash
  yarn serve-pkgs
  ```

### Linting

- **Check** (must pass with zero warnings):
  ```bash
  yarn lint
  ```
- **Auto-fix**:
  ```bash
  yarn lint:fix
  ```
- ESLint covers `.js`, `.ts`, and `.vue` files.
- Always run `yarn lint:fix` before committing.

### Unit Tests

- **Run**:
  ```bash
  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](https://commitlint.js.org/) via a Husky `commit-msg` hook.
- Follow [Conventional Commits](https://www.conventionalcommits.org/) 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`:
  ```bash
  yarn agents:generate
  ```

# Contributors Guide

## Getting Started

Please see the [Harvester UI Extension README](https://github.com/harvester/harvester-ui-extension).

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:

   ```js
   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](https://jestjs.io/). The setup follows the Rancher dashboard and the Rancher extension template ([rancher/ui-plugin-examples](https://github.com/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](https://www.conventionalcommits.org/en/v1.0.0/) 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