✨ Refactor sampleexternalplugin to be a valid reference implementation

Transform the sample external plugin from mock scaffolding to a realistic
working example that demonstrates best practices for external plugin development.

Changes:
- Replace mock init/create api/webhook commands with meaningful edit command
- Add Prometheus ServiceMonitor scaffolding for operator monitoring
- Implement PROJECT config reading to align with internal plugin patterns
- Add local source replace directive for contributor testing
- Update documentation to reflect realistic plugin usage

The plugin now serves as a proper reference for:
- Reading PROJECT config in external plugins
- Scaffolding real, production-ready configurations
- Testing plugins against local Kubebuilder source
- Adding optional features via the edit subcommand

Fixes #4824

Author: nerdeveloper

docs/book/src/plugins/extending/external-plugins.md

@@ -30,13 +30,13 @@ structures.
 
 `PluginRequest` contains the data collected from the CLI and any previously executed plugins. Kubebuilder sends this data as a JSON object to the external plugin via `stdin`.
 
-**Example `PluginRequest` (triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`):**
+**Example `PluginRequest` (triggered by `kubebuilder edit --plugins sampleexternalplugin/v1`):**
 
 ```json
 {
   "apiVersion": "v1alpha1",
-  "args": ["--domain", "my.domain"],
-  "command": "init",
+  "args": [],
+  "command": "edit",
   "universe": {}
 }
 ```
@@ -49,13 +49,14 @@ structures.
 ```json
 {
   "apiVersion": "v1alpha1",
-  "command": "init",
+  "command": "edit",
   "metadata": {
-    "description": "The `init` subcommand initializes a project via Kubebuilder. It scaffolds a single file: `initFile`.",
-    "examples": "kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain"
+    "description": "The `edit` subcommand adds Prometheus ServiceMonitor configuration for monitoring your operator.",
+    "examples": "kubebuilder edit --plugins sampleexternalplugin/v1"
   },
   "universe": {
-    "initFile": "A file created with the `init` subcommand."
+    "config/prometheus/monitor.yaml": "# Prometheus ServiceMonitor manifest...",
+    "config/prometheus/kustomization.yaml": "resources:\n  - monitor.yaml\n"
   },
   "error": false,
   "errorMsgs": []
@@ -120,26 +121,15 @@ Otherwise, Kubebuilder would search for the plugins in a default path based on y
 You can now use it by calling the CLI commands:
 
 ```sh
-# Initialize a new project with the external plugin named `sampleplugin`
-kubebuilder init --plugins sampleplugin/v1
+# Update the project configuration with the sample external plugin
+# The sampleexternalplugin adds Prometheus ServiceMonitor configuration
+kubebuilder edit --plugins sampleexternalplugin/v1
 
-# Display help information of the `init` subcommand of the external plugin
-kubebuilder init --plugins sampleplugin/v1 --help
+# Display help information for the edit subcommand
+kubebuilder edit --plugins sampleexternalplugin/v1 --help
 
-# Create a new API with the above external plugin with a customized flag `number`
-kubebuilder create api --plugins sampleplugin/v1 --number 2
-
-# Create a webhook with the above external plugin with a customized flag `hooked`
-kubebuilder create webhook --plugins sampleplugin/v1 --hooked
-
-# Update the project configuration with the above external plugin
-kubebuilder edit --plugins sampleplugin/v1
-
-# Create new APIs with external plugins v1 and v2 by respecting the plugin chaining order
-kubebuilder create api --plugins sampleplugin/v1,sampleplugin/v2
-
-# Create new APIs with the go/v4 plugin and then pass those files to the external plugin by respecting the plugin chaining order
-kubebuilder create api --plugins go/v4,sampleplugin/v1
+# Plugin chaining example: Use go/v4 plugin first, then apply external plugin
+kubebuilder edit --plugins go/v4,sampleexternalplugin/v1
 ```
 
 ## Further resources

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/cmd.go

@@ -59,19 +59,10 @@ func Run() {
 
 	// Run logic depending on the command that is requested by Kubebuilder
 	switch pluginRequest.Command {
-	// the `init` subcommand is often used when initializing a new project
-	case "init":
-		response = scaffolds.InitCmd(pluginRequest)
-	// the `create api` subcommand is often used after initializing a project
-	// with the `init` subcommand to create a controller and CRDs for a
-	// provided group, version, and kind
-	case "create api":
-		response = scaffolds.ApiCmd(pluginRequest)
-	// the `create webhook` subcommand is often used after initializing a project
-	// with the `init` subcommand to create a webhook for a provided
-	// group, version, and kind
-	case "create webhook":
-		response = scaffolds.WebhookCmd(pluginRequest)
+	// the `edit` subcommand is used to add optional features to an existing project
+	// This is a realistic use case for external plugins - adding optional monitoring
+	case "edit":
+		response = scaffolds.EditCmd(pluginRequest)
 	// the `flags` subcommand is used to customize the flags that
 	// the Kubebuilder cli will bind for use with this plugin
 	case "flags":

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/flags.go

@@ -37,12 +37,8 @@ func flagsCmd(pr *external.PluginRequest) external.PluginResponse {
 	}
 
 	switch pr.Command {
-	case "init":
-		pluginResponse.Flags = scaffolds.InitFlags
-	case "create api":
-		pluginResponse.Flags = scaffolds.ApiFlags
-	case "create webhook":
-		pluginResponse.Flags = scaffolds.WebhookFlags
+	case "edit":
+		pluginResponse.Flags = scaffolds.EditFlags
 	default:
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/metadata.go

@@ -39,9 +39,7 @@ func metadataCmd(pr *external.PluginRequest) external.PluginResponse {
 
 	// Here is an example of parsing multiple flags from a Kubebuilder external plugin request
 	flagsToParse := pflag.NewFlagSet("flagsFlags", pflag.ContinueOnError)
-	flagsToParse.Bool("init", false, "sets the init flag to true")
-	flagsToParse.Bool("api", false, "sets the api flag to true")
-	flagsToParse.Bool("webhook", false, "sets the webhook flag to true")
+	flagsToParse.Bool("edit", false, "sets the edit flag to true")
 
 	if err := flagsToParse.Parse(pr.Args); err != nil {
 		pluginResponse.Error = true
@@ -51,22 +49,14 @@ func metadataCmd(pr *external.PluginRequest) external.PluginResponse {
 		return pluginResponse
 	}
 
-	initFlag, _ := flagsToParse.GetBool("init")
-	apiFlag, _ := flagsToParse.GetBool("api")
-	webhookFlag, _ := flagsToParse.GetBool("webhook")
+	editFlag, _ := flagsToParse.GetBool("edit")
 
 	// The Phase 2 Plugins implementation will only ever pass a single boolean flag
-	// argument in the JSON request `args` field. The flag will be `--init` if it is
-	// attempting to get the flags for the `init` subcommand, `--api` for `create api`,
-	// `--webhook` for `create webhook`, and `--edit` for `edit`
-	if initFlag {
+	// argument in the JSON request `args` field. The flag will be `--edit` for `edit`
+	if editFlag {
 		// Populate the JSON response `metadata` field with a description
-		// and examples for the `init` subcommand
-		pluginResponse.Metadata = scaffolds.InitMeta
-	} else if apiFlag {
-		pluginResponse.Metadata = scaffolds.ApiMeta
-	} else if webhookFlag {
-		pluginResponse.Metadata = scaffolds.WebhookMeta
+		// and examples for the `edit` subcommand
+		pluginResponse.Metadata = scaffolds.EditMeta
 	} else {
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.mod

@@ -5,11 +5,16 @@ go 1.24.5
 require (
 	github.com/spf13/pflag v1.0.10
 	sigs.k8s.io/kubebuilder/v4 v4.9.0
+	sigs.k8s.io/yaml v1.6.0
 )
 
+replace sigs.k8s.io/kubebuilder/v4 => ../../../../../../../
+
 require (
 	github.com/gobuffalo/flect v1.0.3 // indirect
+	github.com/kr/text v0.2.0 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	golang.org/x/mod v0.28.0 // indirect
 	golang.org/x/sync v0.17.0 // indirect
 	golang.org/x/text v0.29.0 // indirect

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.sum

@@ -1,5 +1,6 @@
 github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
 github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -13,12 +14,18 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6 h1:EEHtgt9IwisQ2AZ4pIsMjahcegHh6rmhqxzIRQIyepY=
 github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6/go.mod h1:I6V7YzU0XDpsHqbsyrghnFZLO1gwK6NPTNvmetQIk9U=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/onsi/ginkgo/v2 v2.25.3 h1:Ty8+Yi/ayDAGtk4XxmmfUy4GabvM+MegeB4cDLRi6nw=
 github.com/onsi/ginkgo/v2 v2.25.3/go.mod h1:43uiyQC4Ed2tkOzLsEYm7hnrb7UJTWHYNsuy3bG/snE=
 github.com/onsi/gomega v1.38.2 h1:eZCjf2xjZAqe+LeWvKb5weQ+NcPwX84kqJ0cZNxok2A=
 github.com/onsi/gomega v1.38.2/go.mod h1:W2MJcYxRGV63b418Ai34Ud0hEdTVXq9NW9+Sx6uXf3k=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
@@ -49,10 +56,10 @@ golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
 golang.org/x/tools v0.37.0 h1:DVSRzp7FwePZW356yEAChSdNcQo6Nsp+fex1SUW09lE=
 golang.org/x/tools v0.37.0/go.mod h1:MBN5QPQtLMHVdvsbtarmTNukZDdgwdwlO5qGacAzF0w=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-sigs.k8s.io/kubebuilder/v4 v4.9.0 h1:9e9LnQy/wQ24IZDIqye6iZZFOB9aKNyNfjnfsy3S8cw=
-sigs.k8s.io/kubebuilder/v4 v4.9.0/go.mod h1:Xql7wLeyXBQ4lJJdi1Pl8T/DeV4UXpA1kaOEumN0pzY=
 sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
 sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=