Prototype (v1alpha2)

.cursor/rules/api-codegen.mdc

@@ -0,0 +1,17 @@
+---
+description: API codegen rules for kubebuilder/controller-gen and generated files hygiene. Apply when adding/modifying API types or kubebuilder markers under api/v*/, and when deciding whether regeneration is required. Apply when editing relevant files, and when reasoning/planning/answering questions where this rule could influence code decisions (even if matching files are not currently open).
+globs: api/v*/**/*.go
+alwaysApply: false
+---
+
+- Kubebuilder markers & API changes (MUST):
+  - If I add a new API object/type or modify an existing one in `api/` (especially changes to `// +kubebuilder:*` markers, validation markers, printcolumns, subresources, etc.), I MUST run code generation and include the regenerated outputs in the same change.
+  - In this repo, run generation from the repository root:
+    - `bash hack/generate_code.sh`
+  - If I am intentionally doing an **API-only refactor stage** where changes outside `api/` are temporarily forbidden/undesired (e.g. the rest of the repo is not yet refactored and will not compile), then:
+    - It is acceptable to **defer CRD regeneration** (outputs under `crds/`) until the stage when cross-repo refactor is allowed.
+    - I MUST still keep `api/v1alpha1` internally consistent and compilable; prefer running **object/deepcopy generation only** when possible, instead of editing generated files by hand.
+
+- Generated files (MUST NOT edit by hand):
+  - Do NOT edit `zz_generated*` files (e.g. `api/v1alpha1/zz_generated.deepcopy.go`) manually.
+  - If a generated file needs to change, update the source types/markers and re-run generation instead.

.cursor/rules/api-conditions.mdc

@@ -0,0 +1,56 @@
+---
+description: API condition Type/Reason constants naming, ordering, comments, and stability rules. Apply when editing api/v*/**/*_conditions.go, and when deciding how to name/add conditions for API objects. Apply when editing relevant files, and when reasoning/planning/answering questions where this rule could influence code decisions (even if matching files are not currently open).
+globs: api/v*/**/*_conditions.go
+alwaysApply: false
+---
+
+- Condition constants naming:
+  - Every API object `Status` MUST expose `.status.conditions` (`[]metav1.Condition`) (see `types_rules.mdc`).
+  - Any API object that has at least one standardized/used condition MUST have its own condition type/reason constants scoped by object name.
+  - If the API type exposes `.status.conditions` but there are **no** standardized/used conditions yet:
+    - The `Conditions` field MUST remain in the API (it is part of the contract).
+    - The `<objprefix>_conditions.go` file MAY be absent.
+    - Do NOT create placeholder/empty condition constants “just in case”.
+  - Current API types that expose `.status.conditions` in this repo:
+    - `ReplicatedVolume`
+    - `ReplicatedVolumeReplica`
+    - `ReplicatedVolumeAttachment`
+    - `ReplicatedStorageClass`
+    - `ReplicatedStoragePool`
+
+- Condition Type constants MUST be named:
+  - `<ObjName>Cond<CondTypeName>Type`
+  - `CondTypeName` MUST match the string value of `.Type`.
+  - Examples:
+    - `ReplicatedVolumeCondIOReadyType = "IOReady"`
+    - `ReplicatedVolumeReplicaCondDataInitializedType = "DataInitialized"`
+    - `ReplicatedVolumeAttachmentCondReplicaIOReadyType = "ReplicaIOReady"`
+
+- Condition Reason constants MUST be named:
+  - `<ObjName>Cond<CondTypeName>Reason<ReasonName>`
+  - `CondTypeName` MUST match the string value of the condition type (the `.Type` string).
+  - `ReasonName` MUST match the string value of `.Reason`.
+  - Examples:
+    - `ReplicatedVolumeReplicaCondScheduledReasonReplicaScheduled = "ReplicaScheduled"`
+    - `ReplicatedVolumeCondQuorumReasonQuorumLost = "QuorumLost"`
+    - `ReplicatedVolumeAttachmentCondAttachedReasonSettingPrimary = "SettingPrimary"`
+
+- Conditions grouping (MUST):
+  - Keep each condition type and **all of its reasons in a single `const (...)` block**.
+  - Conditions MUST be ordered alphabetically by condition type name within the file/package.
+  - Reasons within a condition MUST be ordered alphabetically by reason constant name.
+
+- Conditions comments (MUST):
+  - Avoid controller-specific comments like “managed by X” in API packages.
+  - Add short English docs: what the condition represents and what the reasons mean.
+
+- Value stability (MUST):
+  - Do NOT change string values of `.Type` and `.Reason` constants.
+  - Only rename Go identifiers when reorganizing/clarifying.
+
+- Scoping & duplication (MUST):
+  - Do NOT use generic `ConditionType*` / `Reason*` constants.
+  - If the same reason string is used by multiple conditions, create separate constants per condition type, even if the string is identical.
+    - Example: `"NodeNotReady"`:
+      - `ReplicatedVolumeReplicaCondOnlineReasonNodeNotReady = "NodeNotReady"`
+      - `ReplicatedVolumeReplicaCondIOReadyReasonNodeNotReady = "NodeNotReady"`

.cursor/rules/api-file-structure.mdc

@@ -0,0 +1,21 @@
+---
+description: API package conventions: object prefixes and per-object/common file naming rules under api/. Apply when creating/renaming/editing Go files under api/v*/, and when deciding where API code should live. Apply when editing relevant files, and when reasoning/planning/answering questions where this rule could influence code decisions (even if matching files are not currently open).
+globs: api/v*/**/*.go
+alwaysApply: false
+---
+
+- Object prefixes (MUST):
+  - Use short prefixes: `rv`, `rvr`, `rva`, `rsc`, `rsp`.
+
+- File naming per object (MUST):
+  - `<objprefix>_types.go`: API types (kubebuilder tags), object/spec/status structs, adapters for interfaces (e.g. GetConditions/SetConditions) and tightly coupled constants/types and pure set/get/has helpers (no I/O, no external context).
+  - `<objprefix>_conditions.go`: condition Type/Reason constants for the object.
+    - MAY be absent if the API object exposes `.status.conditions` but there are no standardized/used conditions yet (do not create empty placeholder constants).
+  - `<objprefix>_custom_logic_that_should_not_be_here.go`: non-trivial/domain logic helpers (everything that does not fit `*_types.go`).
+
+- Common file naming (MUST):
+  - `common_types.go`: shared types/enums/constants for the API package.
+  - `common_helpers.go`: shared pure helpers used across API types.
+  - `labels.go`: well-known label keys (constants).
+  - `finalizers.go`: module finalizer constants.
+  - `register.go`: scheme registration.

.cursor/rules/api-kubebuilder-markers.mdc

@@ -0,0 +1,108 @@
+---
+description: Kubebuilder marker hygiene rules for CEL expressions, gofmt smart quote avoidance, and typographic character detection. Apply when writing or editing kubebuilder markers (especially XValidation with CEL), when reviewing API types under api/v*/, and when debugging unexpected character transformations in comments. Apply when editing relevant files, and when reasoning/planning/answering questions where this rule could influence code decisions (even if matching files are not currently open).
+globs: api/v*/**/*.go
+alwaysApply: true
+---
+
+Normative keywords used in this document are defined in `rfc-like-mdc.mdc`.
+
+# Kubebuilder markers and gofmt smart quote issue
+
+## Background
+
+Since Go 1.19, `gofmt` reformats doc comments (comments immediately preceding `type`, `func`, `var`, `const` declarations) for improved documentation rendering. One side effect is that `gofmt` converts two consecutive single quotes (`''`) into a typographic RIGHT DOUBLE QUOTATION MARK (`"`, U+201D) in doc comments.
+
+This behavior breaks kubebuilder `XValidation` markers that contain CEL expressions, because CEL uses single quotes for string literals (`'hello'`), and an empty string in CEL is `''`.
+
+**References:**
+- Stack Overflow: https://stackoverflow.com/questions/79734115/why-does-gofmt-replace-two-single-quotes-with-a-single-double-quote-in-my-go-com
+- Go 1.19 release notes (comment formatting): https://go.dev/doc/go1.19#go-doc
+
+## Empty string comparison in CEL (MUST)
+
+When writing CEL expressions in `// +kubebuilder:validation:XValidation` markers, you MUST NOT use `''` (two single quotes) for empty string comparison.
+
+**Bad (will be corrupted by gofmt):**
+```go
+// +kubebuilder:validation:XValidation:rule="self.field != ''",message="field must not be empty"
+```
+
+**After gofmt, this becomes (broken):**
+```go
+// +kubebuilder:validation:XValidation:rule="self.field != "",message="field must not be empty"
+```
+
+### Solution 1: Use `size()` function (RECOMMENDED)
+
+Use the CEL `size()` function instead of comparing to an empty string:
+
+| Instead of | Use |
+|------------|-----|
+| `field != ''` | `size(field) > 0` |
+| `field == ''` | `size(field) == 0` |
+
+**Good:**
+```go
+// +kubebuilder:validation:XValidation:rule="size(self.field) > 0",message="field must not be empty"
+```
+
+### Solution 2: Tab indentation (alternative)
+
+Adding a tab character before the `+` in the marker causes `gofmt` to treat the line as a preformatted code block, which disables smart quote conversion:
+
+```go
+//	+kubebuilder:validation:XValidation:rule="self.field != ''",message="field must not be empty"
+```
+
+Note: The tab character is between `//` and `+`. This approach is less preferred because it is subtle and easy to lose during edits.
+
+## Detecting typographic characters (MUST)
+
+When reviewing or debugging kubebuilder markers, you MUST check for typographic/Unicode characters that should not be present in code:
+
+| Bad character | Unicode | Hex bytes (UTF-8) | Should be |
+|---------------|---------|-------------------|-----------|
+| `"` (left double) | U+201C | `e2 80 9c` | `"` (0x22) |
+| `"` (right double) | U+201D | `e2 80 9d` | `"` (0x22) |
+| `'` (left single) | U+2018 | `e2 80 98` | `'` (0x27) |
+| `'` (right single) | U+2019 | `e2 80 99` | `'` (0x27) |
+| `–` (en dash) | U+2013 | `e2 80 93` | `-` (0x2d) |
+| `—` (em dash) | U+2014 | `e2 80 94` | `--` or `-` |
+
+### How to detect
+
+Use `xxd` or `hexdump` to inspect suspicious lines:
+
+```bash
+sed -n '<line>p' <file> | xxd | grep -E "e2 80"
+```
+
+If you see `e2 80 9c`, `e2 80 9d`, `e2 80 98`, or `e2 80 99` in the output, the file contains typographic quotes that will cause problems.
+
+### How to fix
+
+Replace typographic characters with their ASCII equivalents. For CEL empty string comparisons, use `size()` as described above.
+
+## Sources of typographic characters
+
+Typographic quotes are often introduced when:
+
+1. **Copying from documents** (Word, Google Docs, PDF, Notion)
+2. **Copying from web pages** with "smart quotes" enabled
+3. **macOS keyboard** with "Use smart quotes and dashes" enabled
+4. **AI assistants** (ChatGPT, Claude, etc.) that sometimes generate typographic quotes
+5. **Running gofmt** on code that contains `''` in doc comments
+
+## Validation timing
+
+CEL expression syntax is NOT validated by:
+- Go compiler (`go build`)
+- `gofmt` / `gopls`
+- `controller-gen`
+- `golangci-lint`
+
+CEL syntax errors are only detected at runtime when:
+1. The CRD is applied to a Kubernetes cluster
+2. A resource is created/updated and Kubernetes validates it against the CEL rule
+
+Therefore, you SHOULD manually verify CEL expressions before committing.

.cursor/rules/api-labels-and-finalizers.mdc

@@ -0,0 +1,42 @@
+---
+description: API naming rules for label keys (labels.go) and finalizer constants (finalizers.go): naming, value formats, and stability. Apply when editing api/v*/**/labels.go or api/v*/**/finalizers.go, and when deciding label/finalizer names/values. Apply when editing relevant files, and when reasoning/planning/answering questions where this rule could influence code decisions (even if matching files are not currently open).
+globs: api/v*/**/finalizers.go,api/v*/**/labels.go
+alwaysApply: false
+---
+
+## Label keys (`labels.go`)
+
+- **Constant naming (MUST)**:
+  - Label key constants MUST end with `LabelKey`.
+    - Good: `ReplicatedVolumeLabelKey`, `NodeNameLabelKey`
+    - Bad: `LabelReplicatedVolume`, `NodeLabel`, `LabelNodeName`
+
+- **Prefix constant (MUST)**:
+  - The label prefix constant MUST be private and named `labelPrefix` (unless there is a proven need to export it).
+  - The prefix value MUST be the module-scoped prefix:
+    - `sds-replicated-volume.deckhouse.io/`
+
+- **Value format (MUST)**:
+  - Label key values MUST be built as `labelPrefix + "<suffix>"`.
+  - The `<suffix>` part MUST be lowercase-kebab-case, without repeating the module name.
+    - Good: `labelPrefix + "replicated-volume"`
+    - Bad: `labelPrefix + "sds-replicated-volume-replicated-volume"`
+
+- **Layout (MUST)**:
+  - Keep all exported `...LabelKey` constants in a single `const (...)` block.
+  - Avoid commented-out placeholder constants; prefer adding constants only when actually needed.
+
+## Finalizers (`finalizers.go`)
+
+- **Constant naming (MUST)**:
+  - Finalizer constants MUST end with `Finalizer`.
+    - Good: `ControllerFinalizer`, `AgentFinalizer`
+    - Bad: `FinalizerController`, `ControllerFinalizerName`
+
+- **Value format (MUST)**:
+  - Finalizer values MUST be module-scoped and stable:
+    - `sds-replicated-volume.deckhouse.io/<component>`
+  - `<component>` MUST be lowercase and short (e.g. `controller`, `agent`).
+
+- **Stability (MUST)**:
+  - Do NOT change existing finalizer string values (this would break cleanup semantics).