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

### 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.
    - 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](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>[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