Adding AGENTS.md

.github/copilot-code-review.yml

@@ -0,0 +1,67 @@
+# Copyright 2026 The kpt Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Copilot code review configuration for kpt
+# kpt is a Kubernetes configuration package management and orchestration system
+
+review:
+  instructions:
+    # Linter overlap — these are already enforced by golangci-lint in CI
+    - "Do not comment on issues caught by: errcheck, govet, ineffassign, staticcheck, unused, nosprintfhostport, gofmt"
+    - "Do not comment on import ordering or formatting"
+
+    # Style — established project conventions
+    - "Do not comment on error wrapping style (this project uses fmt.Errorf with %w consistently)"
+    - "Do not suggest renaming variables, functions, or packages unless semantically misleading"
+    - "Do not suggest extracting single-use helper functions"
+    - "Do not suggest adding comments to exported symbols unless the function is non-obvious"
+
+    # Architecture context
+    - "This is a Kubernetes configuration management tool using kyaml/kustomize ecosystem"
+    - "Controllers and APIs follow kpt's Kptfile specification and package management patterns"
+    - "Do not flag intentional use of nil results in pkg operations (graceful fallback patterns)"
+    - "log.FromContext(ctx) is the logging convention — do not suggest alternatives"
+    - "Testing uses testutil setup patterns with git repositories and workspaces — do not refactor test helpers"
+
+    # What to actually review
+    - "Focus on: logic errors, race conditions, resource leaks, deadlocks, nil pointer dereferences"
+    - "Flag: missing context cancellation checks, unbounded goroutines, missing error handling in deferred Close calls"
+    - "Flag: incorrect kyaml/kustomize API usage, broken file system operations"
+    - "Flag: security issues (credential leaks, injection vulnerabilities, path traversal)"
+    - "Flag: incorrect Git/package handling (bad ref handling, missing upstream validation)"
+    - "Flag: potential issues with YAML/Kptfile parsing or manipulation"
+
+  path_instructions:
+    - path: "api/generated/**"
+      instructions: "Do not review — generated by k8s code-generator"
+    - path: "**/zz_generated*"
+      instructions: "Do not review — generated by controller-tools"
+    - path: "third_party/**"
+      instructions: "Do not review — vendored upstream code"
+    - path: "go.sum"
+      instructions: "Do not review"
+    - path: "go.mod"
+      instructions: "Only flag if a dependency looks suspicious or has a known CVE"
+    - path: "docs/**"
+      instructions: "Only flag factual errors or broken links. Do not comment on grammar or style"
+    - path: "site/**"
+      instructions: "Only flag factual errors. Do not suggest style/formatting changes to documentation"
+    - path: "**/*_test.go"
+      instructions: "Focus on correctness and flakiness risks. testify (assert/require) and table-driven tests are the standard. Do not suggest style changes or test refactoring"
+    - path: "test/**"
+      instructions: "Only flag correctness/security issues. testutil patterns are intentional — do not suggest refactoring. Note: golangci-lint excludes test/ from CI linting"
+    - path: ".github/**"
+      instructions: "Focus on security (pinned actions, minimal permissions, injection risks). Do not suggest cosmetic changes"
+    - path: "examples/**"
+      instructions: "Only flag correctness issues. These are tutorial configs — do not enforce strict linting"

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# GitHub Copilot Instructions for kpt
+
+[See AGENTS.md](../AGENTS.md) for information for agents in this project.

AGENTS.md

@@ -0,0 +1,291 @@
+# Cloud Agent Instructions for kpt
+
+For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or reviewing pull requests in this repository.
+
+## Generic rules
+
+### Coding
+
+* Never commit directly to this repository, always aim for a pull request
+* Always ask for a final review from a human before committing
+* Make sure that AI agent usage is attributed in the correct way
+
+### Reviewing PRs
+
+* When committing suggested changes, add a sign-off from the human author and add the `Assisted-by`
+  tag with the suggesting agent and its used model to the commit message
+* If a comment was not accepted and the Conversation was resolved do not make the same comment again
+
+
+## Repository Overview
+
+**kpt** is a package-centric toolchain that automates Kubernetes configuration editing and
+management. It enables declarative configuration authoring, automation, and delivery at scale
+through a "Configuration as Data" approach, supporting Kubernetes platforms and KRM-driven
+infrastructure (e.g., Config Connector, Crossplane).
+
+- **Language**: Go (version is defined in the [go.mod](./go.mod) file)
+- **License**: Apache 2.0
+- **Key Topics**: Kubernetes, configuration management, CLI tooling, GitOps, policy-as-code, KRM (Kubernetes Resource Model)
+
+## Quick Build & Test Commands
+
+**Trust these instructions first.** Only perform searches if you find this information incomplete or inaccurate.
+
+### Prerequisites
+- Go (version is specified in [go.mod](./go.mod))
+- Git (required and checked at runtime)
+- Docker or Podman (for `test-docker` and function runtime tests)
+- KinD (CI uses the version defined in `.github/workflows/e2eEnvironment.yml`)
+
+### Build
+
+```bash
+make build
+```
+This compiles kpt to `$(go env GOPATH)/bin/kpt` using LDFLAGS with git commit SHA.
+
+### Run All Checks (Build, Test, Lint)
+
+```bash
+make all
+```
+
+Runs: `fix vet fmt lint test build tidy` in sequence. *Always* run this before committing.
+
+### Unit Tests
+
+```bash
+make test
+```
+
+Runs Go tests with coverage. Set `KRM_FN_RUNTIME` to select function runtime (docker/podman, default uses system default).
+
+### Docker/Podman Runtime Tests
+
+```bash
+make test-docker
+```
+
+Requires Docker or Podman. Tests that need container runtime (e.g., pipeline tests). Respects `KRM_FN_RUNTIME` environment variable.
+
+### E2E Function Tests
+
+#### Render tests
+
+```bash
+make test-fn-render T=".*"
+```
+#### Eval tests
+
+```bash
+make test-fn-eval T=".*"
+```
+
+Use `T` parameter to filter tests by regex (e.g., `T=fnconfig` for function config tests). Set `KRM_FN_RUNTIME` to select runtime.
+
+### E2E Live Apply Tests
+
+```bash
+make test-live-apply
+```
+
+Requires KinD with Kubernetres versions defined in `jobs.kind.strategy.matrix.version` path of the
+[e2e test workflows](.github/workflows/live-e2e.yml) (specific SHAs pinned in CI). These tests use Kind
+internally. Timeout is 20 minutes.
+
+### Linting
+
+```bash
+make lint
+```
+
+Runs golangci-lint v2.11.4. If already installed locally with matching version, uses it; otherwise downloads and runs via `go run`.
+
+### Code Generation & Formatting
+
+```bash
+make fmt        # Run gofmt
+make fix        # Run go fix
+make vet        # Run go vet
+make tidy       # Run go mod tidy
+make generate   # Generate code from templates (mdtogo, copyright headers)
+make schema     # Generate schema
+```
+
+### Setting Up Git Config (Required for Tests)
+
+Many tests require git configuration:
+
+```bash
+git config --global user.email "you@example.com"
+git config --global user.name "Your Name"
+```
+
+## Project Layout
+
+### Root Level Files & Directories
+
+* **main.go**: CLI entry point; contains //go:generate directives for CLI documentation
+* **Makefile**: Primary build orchestration
+* **.golangci.yml**: Linting configuration (used golangci-lint version is defined in the `GOLANGCI_LINT_VERSION` variable of the [Makefile](./Makefile))
+* **go.mod / go.sum**: Dependency management
+* **CONTRIBUTING.md**: Contribution guidelines and code review requirements
+* **CODEOWNERS**: Default reviewers
+
+### Key Source Directories
+
+* **commands/**: CLI command implementations using Cobra framework
+* **run/**: Main CLI setup; contains GetMain() that initializes Cobra commands with environment setup
+* **pkg/**: Core library packages (business logic, utilities)
+* **internal/**: Internal packages; includes internal/docs/generated/ (generated from Markdown via mdtogo)
+* **mdtogo/**: Code generator tool that converts CLI documentation Markdown files to Go variables
+
+### Build & CI Configuration
+
+* **.github/workflows/go.yml**: Main CI workflow
+  * Runs on Linux (docker/podman matrix) and macOS
+  * Executes: `make all` + `make test-docker`
+  * Triggered on PRs (except changes limited to ignored paths like `**.md`) and pushes (pushes exclude dependabot branches)
+* **.github/workflows/e2eEnvironment.yml**: KinD-based e2e tests
+  * Tests Kubernetes versions defined in `jobs.kind.strategy.matrix.version` with KinD (KinD version in `jobs.kind.steps["Install KinD"].with.version`)
+  * Runs `./e2e/live/end-to-end-test.sh -k <K8S_VERSION>`
+* **.github/workflows/live-e2e.yml**: Live apply e2e tests
+  * Tests with pinned Kubernetes image SHAs
+  * Runs `make test-live-apply` with `K8S_VERSION` environment variable
+* **.github/workflows/release-api.yml**: Release the kpt API module
+  * Builds, tests and lints the kpt API module
+  * Runs `make api`
+
+### Documentation & Tests
+
+* **documentation/**: Hugo-based website published to kpt.dev
+  * Run `make serve` from `documentation/` (serves docs locally)
+  * Requires `npm install` first (run in `documentation/`)
+  * Documentation shold follow the [style guide for documentation](documentation/README.md#style-guide-for-documentation) 
+
+* **e2e/**: End-to-end test suites
+  * Contains testdata directories for function render/eval tests
+  * Live tests in `e2e/live/end-to-end-test.sh`
+
+### Other Notable Directories
+
+* **release/**: Release automation (GoReleaser config, Homebrew formula generation)
+* **hack/**: Miscellaneous development utilities
+* **healthcheck/**: Separate module for health checking (Go (Go version is defined in [healthcheck/go.mod](./healthcheck/go.mod)), local Makefile)
+* **thirdparty/**: Third-party code (excluded from linting)
+* **Formula/**: Homebrew package definition (generated by `go run ./release/formula/main.go VERSION`)
+
+## Linting Rules & Style
+
+### Linter Configuration
+
+* Linter configuration is defined in the [.golangci.yml](./.golangci.yml) file
+
+### Code Style Requirements (from CONTRIBUTING.md)
+
+* **Copyright Headers**: All files must have Apache 2.0 license header
+  * Use format: // Copyright YEAR The kpt Authors (or year range if modified)
+  * Year should match creation year, or creation-to-modification year range (see the [instructions in Porch for more details](https://porch.kpt.dev/docs/12_contributing/code-contribution/#update-copyright-on-files))
+* **Developer Certificate of Origin (DCO)**: Commits must be signed with -s flag
+* **Large Features**: Require reviewed and merged design document (use /docs/design-docs/00-template.md as template)
+* **AI Usage**: Must declare AI usage in the PR description; `Assisted-by: AGENT_NAME:MODEL_VERSION` attribution in
+  commit messages is recommended (see CONTRIBUTING.md).
+
+## Validation Checklist for PRs
+
+Before submitting a PR, verify:
+
+1. ✅ All tests pass: make all
+1. ✅ All linting passes: make lint
+1. ✅ Code formatted: make fmt
+1. ✅ Dependencies tidied: make tidy
+1. ✅ Copyright headers added/updated per CONTRIBUTING.md
+1. ✅ DCO sign-off: use git commit -s
+1. ✅ For CLI/API changes: design document reviewed and merged
+1. ✅ AI usage declared in PR description (if applicable)
+
+## Common Build Issues & Workarounds
+
+### Docker/Podman Not Available
+
+If `make test-docker` fails due to missing Docker/Podman:
+
+* Install Docker Desktop or Podman
+* For Podman: ensure it's on PATH and `podman version` runs successfully
+* Set `KRM_FN_RUNTIME=podman` if using Podman
+
+### KinD Setup Issues
+
+For e2e live tests (`make test-live-apply`):
+
+* KinD is auto-installed by CI workflow
+* Requires Docker running in background
+* Tests use specific Kubernetes image SHAs (see live-e2e.yml matrix)
+* Timeout is 20 minutes; allow sufficient time
+
+### Git Configuration
+
+Tests fail silently if git user not configured. Always run:
+
+```bash
+git config --global user.email "you@example.com"
+git config --global user.name "Your Name"
+```
+
+### Module Generation
+
+If changes modify CLI documentation in documentation/content/en/reference/cli/:
+
+* Run `make generate` to regenerate `internal/docs/generated/`
+* Commit generated files
+
+### Known CI Skips
+
+* Windows build currently disabled (see `.github/workflows/go.yml`, issue #3463)
+* Some linters disabled: `funlen`, `gosec` (marked TODO in `.golangci.yml`)
+
+## Environment Variables
+
+* **KRM_FN_RUNTIME**: Select function runtime for tests: `docker`, `podman` or `nerdctl`
+* **K8S_VERSION**: Kubernetes version for e2e live tests (used in CI with pinned SHAs)
+* **KPT_NO_PAGER_HELP**: Set to 1 to disable pager for help output
+* **PAGER**: Custom pager command (default: less -R)
+* **KPT_FN_WASM_RUNTIME**: WASM function runtime selection
+* **GOPATH**: Go workspace path (used in CI workflows)
+* **GOBIN**: Go binary installation directory
+
+## Key Dependencies
+
+* **Cobra**: CLI framework
+* **Kubernetes libraries (k8s.io/*)**: For Kubernetes resource handling
+* **sigs.k8s.io/cli-utils**: CLI utilities
+* **sigs.k8s.io/kustomize/kyaml**: YAML handling for Kubernetes
+* **sigs.k8s.io/controller-runtime**: Controller and reconciliation patterns
+* **wasmtime-go**: WebAssembly function runtime
+* **go-containerregistry**: Container image handling
+
+## Testing Strategy
+
+* **Unit Tests**: Run with `make test` (standard Go tests)
+* **Docker-based Tests**: Run with `make test-docker` (requires container runtime)
+* **Function E2E Tests**: Run with `make test-fn-render` / `make test-fn-eval` (testdata-driven)
+* **Live Apply E2E**: Run with `make test-live-apply` (KinD-based, 20-minute timeout)
+* **Example Verification**: Run with `make site-verify-examples` (verifies CLI examples in docs)
+
+## Implementation Notes for Code Changes
+
+* **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/content/en/reference/cli/` for documentation
+* **Library Code**: Place in `pkg/` for public APIs; use `internal/` for internal utilities
+* **Tests**: Colocate `*_test.go` files with source; use testdata directories for fixtures
+* **Generated Code**: Run `make generate` after modifying templates
+* **Linting Issues**: Address all `golangci-lint` findings; consult `.golangci.yml` for thresholds
+* **Git Flow**: Always create feature branches; use squash-merge preferred per repository settings
+* **Documentation**: Update Markdown in documentation/; run `make serve` to make sure that there are no errors
+
+Trust these instructions. They have been validated against the Makefile, GitHub workflows, go.mod,
+and contributing guidelines. Only search for additional details if:
+
+* Build or test commands fail with unexpected errors
+* Instructions reference non-existent paths or commands
+* New tool versions are released and compatibility is unclear