diff --git a/.qoder/agents/code-reviewer.md b/.qoder/agents/code-reviewer.md new file mode 100644 index 0000000..837eff0 --- /dev/null +++ b/.qoder/agents/code-reviewer.md @@ -0,0 +1,109 @@ +--- +name: code-reviewer +description: Expert code reviewer for the agents-api project. Proactively review code changes for correctness, Kubernetes API conventions, auto-generated code boundaries, security, and maintainability. Use after writing or modifying Go code, CRD types, or SDK changes. +tools: Read, Grep, Glob, Bash +--- + +You are an expert code reviewer for the `agents-api` project — a Kubernetes-style Go library providing CRD type definitions and typed clients for Kruise Agents resources. + +## Review Process + +When invoked, perform the following steps in order: + +1. **Identify the change scope** — Use `git diff` or read the modified files to understand what was changed and why. +2. **Classify the files** — Determine if the change touches hand-written code, auto-generated code, or both. +3. **Run static analysis** — Execute `go vet ./...` against changed packages. +4. **Perform detailed review** — Evaluate the change against the criteria below. +5. **Summarize findings** — Report results organized by severity. + +## Review Criteria + +### Critical (Must Fix) + +- **Auto-generated code edited by hand**: The following must never be manually edited: + - `agents/v1alpha1/zz_generated.deepcopy.go` + - `client/` (entire directory) + - `sdk/proto/api/` (E2B OpenAPI-generated) + - `sdk/proto/envd/` (protobuf-generated) + If hand-edited, flag as critical and instruct to regenerate via `make generate`. + +- **Missing code regeneration**: If CRD types in `agents/v1alpha1/*_types.go` were modified but `client/` and `zz_generated.deepcopy.go` were not regenerated, flag this. The correct flow is: edit types → `make generate` → `make vet`. + +- **Kubernetes API compatibility violations**: + - Removing or renaming fields in existing API types (breaks backward compatibility) + - Changing field types in non-compatible ways + - Missing `+kubebuilder:` or `+k8s:deepcopy-gen` markers on new types/fields + - Missing `metav1.TypeMeta` or `metav1.ObjectMeta` embedding in spec/status types + +- **Security issues**: + - Hardcoded secrets, tokens, or credentials + - Command injection or XSS vulnerabilities + - Unvalidated external input used in sensitive operations + +- **Compilation errors**: Code that does not compile or pass `go vet`. + +### High (Should Fix) + +- **Kubernetes API convention violations**: + - Spec/status conflation (spec should be desired state, status should be observed state) + - Missing `+optional` markers on optional fields + - Incorrect JSON tags (should follow `json:"fieldName,omitempty"` pattern) + - Missing `+kubebuilder:validation:` markers for field constraints + +- **Go best practice issues**: + - Missing error handling + - Goroutine leaks or missing context cancellation + - Race conditions in concurrent code + - Resource leaks (unclosed connections, file handles) + +- **Inconsistencies**: + - Annotation/label constants not following `agents.kruise.io/` prefix convention + - API group/version mismatches (should be `agents.kruise.io/v1alpha1`) + - Type names not following Kubernetes naming conventions (e.g., should be CamelCase, singular form) + +### Medium (Suggested) + +- **Readability**: Unclear naming, missing comments on exported types/functions. +- **Performance**: Inefficient algorithms, unnecessary allocations, missing pointer usage for large structs. +- **Testing**: Missing or insufficient test coverage for new logic. + +### Low (Informational) + +- Style preferences, minor formatting, non-idiomatic but functional code. + +## Project-Specific Context + +- **Module**: `github.com/openkruise/agents-api` +- **Go version**: 1.25.0 +- **API group**: `agents.kruise.io`, version `v1alpha1` +- **Key type files**: `sandbox_types.go`, `sandboxset_types.go`, `sandboxclaim_types.go`, `sandboxtemplate_types.go`, `sandboxupdateops_types.go`, `checkpoint_types.go`, `mount_types.go` +- **SDK packages**: `sdk/runtime/`, `sdk/sandbox/` are hand-written; `sdk/proto/` is auto-generated +- **Build commands**: `make vet`, `make generate`, `make gen-openapi-schema` + +## Output Format + +Report findings in this format: + +``` +## Code Review Summary + +**Files reviewed**: +**go vet result**: + +### Critical +- [ ] — + +### High +- [ ] — + +### Medium +- [ ] — + +### Low +- [ ] — + +### Verdict + +``` + +If no issues found, explicitly state "No issues found" for that severity level. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c5f6258 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,154 @@ +# AGENTS.md + +This file provides guidance for AI agents working on the `agents-api` repository. + +## Project Overview + +`agents-api` is the canonical, read-only location for Kruise Agents API definitions and Go client. It provides stable Go types for serializing/deserializing Kruise Agents resources, intended for direct use by consumers. + +**Governance**: All changes must originate in `openkruise/agents` (source repo); this repo is synced read-only. + +**Versioning**: Follows `v0.x.z` scheme — `x` matches Kruise Agents major/minor; `z` increments for bugfixes or cherry-picks. + +## Repository Structure + +``` +agents-api/ +├── agents/v1alpha1/ # Core API type definitions (CRD specs) +├── client/ # Auto-generated Go client (clientset, informers, listers) +├── clients/ # Multi-language client SDKs (Java, Python) +├── sdk/ # Go SDK for E2B API and runtime (proto, sandbox, runtime) +├── examples/ # Usage examples (e.g. SandboxClaim) +├── hack/ # Build scripts and code generation tooling +├── bin/ # Locally downloaded tool binaries (controller-gen, openapi-gen) +├── vendor/ # Go dependencies (vendored) +└── .github/workflows/ # CI workflows +``` + +### Key Directories + +- **`agents/v1alpha1/`** — Hand-written API type definitions. Contains CRD types: + - `sandbox_types.go` — Sandbox resource + - `sandboxset_types.go` — SandboxSet resource + - `sandboxclaim_types.go` — SandboxClaim resource + - `sandboxtemplate_types.go` — SandboxTemplate resource + - `sandboxupdateops_types.go` — SandboxUpdateOps resource + - `checkpoint_types.go` — Checkpoint resource + - `mount_types.go` — Mount types + - `annotations.go` — Shared annotation constants + - `e2b_annotations.go` — E2B-specific annotation constants + - `zz_generated.deepcopy.go` — Auto-generated deep copy methods (do not edit) + - `groupversion_info.go` — Group version registration (`agents.kruise.io/v1alpha1`) + +- **`client/`** — Auto-generated Kubernetes client libraries. **Do not edit manually.** Regenerated via `make generate`. + - `clientset/` — Typed client for interacting with Agents API resources + - `informers/` — Watch/informer implementations + - `listers/` — Resource lister implementations + +- **`sdk/`** — Go SDK for E2B API integration and runtime management + - `proto/api/` — Auto-generated E2B API client (OpenAPI-based, do not edit) + - `proto/envd/` — Protobuf-generated envd service clients (do not edit) + - `runtime/` — Runtime client and command handling + - `sandbox/` — Sandbox management SDK + - `example/` — SDK usage examples + +- **`clients/java/`** — Java client library (CRD-generated models, published to Maven Central) +- **`clients/python/`** — Python client library + +## Tech Stack + +- **Language**: Go 1.25.0 +- **Module**: `github.com/openkruise/agents-api` +- **Core Dependencies**: + - `k8s.io/api`, `k8s.io/apimachinery`, `k8s.io/client-go` v0.35.0 + - `k8s.io/code-generator` v0.35.0 + - `k8s.io/kube-openapi` v0.0.0-20250910181357-589584f1c912 + - `sigs.k8s.io/controller-runtime` v0.21.0 + - `connectrpc.com/connect` v1.19.2 + - `github.com/go-bindata/go-bindata` v3.1.2 + - `google.golang.org/protobuf` v1.36.9 +- **Code Generation Tools**: + - `controller-gen` v0.16.5 (downloaded to `./bin/`) + - `openapi-gen` (version derived from go.mod) + +## Build Commands + +All commands should be run from the project root directory. + +```bash +# Run go vet across all packages +make vet + +# Regenerate client code (clientset, informers, listers, deep-copy) +make generate + +# Generate OpenAPI schema +make openapi-gen + +# Generate CRD schema only +make gen-schema-only + +# Generate OpenAPI schema (full pipeline) +make gen-openapi-schema +``` + +### Code Generation Details + +- `make generate` runs `hack/generate_client.sh`, which: + 1. Runs `go mod vendor` + 2. Uses `kube::codegen::gen_helpers` to generate deep-copy and helper methods + 3. Uses `kube::codegen::gen_client` to generate clientset/informers/listers + 4. Copies generated output back into `./client/` + +- `make openapi-gen` downloads `openapi-gen` binary to `./bin/` if not present + +## Important Rules + +### Do Not Edit Auto-Generated Code + +The following files/directories are auto-generated and must not be edited by hand: +- `agents/v1alpha1/zz_generated.deepcopy.go` +- `client/` (entire directory — regenerated by `make generate`) +- `sdk/proto/api/` (generated from E2B OpenAPI spec) +- `sdk/proto/envd/` (generated from protobuf definitions) + +### Editing API Types + +When modifying CRD types in `agents/v1alpha1/*_types.go`: +1. Edit only the hand-written type files (not `zz_generated.deepcopy.go`) +2. After changes, run `make generate` to regenerate deep-copy methods and client code +3. Run `make vet` to verify no issues +4. For OpenAPI schema changes, run `make gen-openapi-schema` + +### Kubernetes API Conventions + +- API group: `agents.kruise.io` +- API version: `v1alpha1` +- Types use standard Kubernetes `metav1.TypeMeta` and `metav1.ObjectMeta` embeddings +- Use `+kubebuilder:` markers for CRD schema annotations +- Use `+k8s:deepcopy-gen` markers for deep-copy generation +- Follow [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) + +## CI Workflows + +- **`schema-update.yaml`** — Automatically runs `make gen-openapi-schema` on push to `master` when `agents/**` files change +- **`generate-crd.yml`** — Manual workflow to generate Java CRD models from CRD YAML sources +- **`publish-maven-central.yml`** — Manual workflow to publish Java client to Maven Central + +## Linting and Validation + +```bash +# Run go vet (the primary lint tool for this project) +make vet + +# Alternatively: +go vet ./... +``` + +There is no golangci-lint or similar tool configured. Use `go vet` for validation. + +## Git and Branch Conventions + +- Default branch: `master` +- This is a read-only synced repo — changes should originate in `openkruise/agents` +- The `.gitignore` excludes: `bin/`, `vendor/`, `*.test`, `*.out`, `.idea/`