feat: added site pruning logic (#427)

<!--

Describe in detail the changes you are proposing, and the rationale.

-->

<!--

Link all GitHub issues fixed by this PR, and add references to prior
related PRs.

-->

Fixes #

### NEW FEATURES | UPGRADE NOTES | ENHANCEMENTS | BUG FIXES |
EXPERIMENTS

<!--

Write a short description of your changes. Examples:

- Fixed a bug
- Added a new feature
- Updated documentation

--> 

-

Author: demeyerthom

.changes/unreleased/Added-20250919-155624.yaml

@@ -0,0 +1,3 @@
+kind: Added
+body: Added options for filtering of nodes as replacement for site and component targeting
+time: 2025-09-19T15:56:24.62356674+02:00

docs/src/howto/cli/filtering-commands.md

@@ -0,0 +1,28 @@
+# Filtering commands
+
+> For site-component targeting with `--filter` the deployment type of the component must be marked as `site-component`!
+
+By default, mach composer cli will run all nodes in the configuration in the order inferred from the configuration. You
+can filter which nodes to run by using one or more `--filter` flags on the commands that support it. With this you can
+more selectively target specific nodes in your configuration.
+
+The filter expression is a simple string that is matched against the node names:
+
+- Run a component: `mach-composer apply --filter component-1`
+- Run a site: `mach-composer apply --filter site-1`
+- Run a specific component in a specific site: `mach-composer apply --filter site-1/component-1`
+
+Some additional microsyntaxes are available to further define which nodes to run:
+
+- `site-1...` will run site-1 and all dependent components
+- `site-1/component-1...` will run component-1 in site-1 and all its dependencies
+
+Syntaxes can also be combined by using multiple `--filter` flags. Note that when multiple filters are provided that
+could match the same node, priority is given to the most generic filter. This means that any less generic filters are
+ignored:
+
+- Ignores `site-1/component-1` because `site-1...` already matches it:
+  `mach-composer apply --filter site-1... --filter site-1/component-1`
+
+
+

docs/src/reference/cli/mach-composer.md

@@ -18,18 +18,18 @@ MACH composer is a framework that you use to orchestrate and extend modern digit
 
 ### SEE ALSO
 
-* [mach-composer apply](mach-composer_apply.md)	 - Apply the configuration.
+* [mach-composer apply](mach-composer_apply.md)	 - Apply the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer cloud](mach-composer_cloud.md)	 - Manage your Mach Composer Cloud
 * [mach-composer components](mach-composer_components.md)	 - List all components.
 * [mach-composer generate](mach-composer_generate.md)	 - Generate the Terraform files.
 * [mach-composer graph](mach-composer_graph.md)	 - Print the execution graph for this project
-* [mach-composer init](mach-composer_init.md)	 - Initialize site directories Terraform files.
-* [mach-composer plan](mach-composer_plan.md)	 - Plan the configuration.
+* [mach-composer init](mach-composer_init.md)	 - Initialize site directories Terraform files. See [the documentation](/howto/cli/filtering-commands) for filtering options.
+* [mach-composer plan](mach-composer_plan.md)	 - Plan the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer schema](mach-composer_schema.md)	 - Generate a JSON schema for your config based on the plugins.
-* [mach-composer show-plan](mach-composer_show-plan.md)	 - Show the planned configuration.
+* [mach-composer show-plan](mach-composer_show-plan.md)	 - Show the planned configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer sites](mach-composer_sites.md)	 - List all sites.
-* [mach-composer terraform](mach-composer_terraform.md)	 - Execute terraform commands directly
+* [mach-composer terraform](mach-composer_terraform.md)	 - Execute terraform commands directly. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer update](mach-composer_update.md)	 - Update all (or a given) component.
-* [mach-composer validate](mach-composer_validate.md)	 - Validate the generated terraform configuration.
+* [mach-composer validate](mach-composer_validate.md)	 - Validate the generated terraform configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 * [mach-composer version](mach-composer_version.md)	 - Return version information of the mach-composer cli
 

docs/src/reference/cli/mach-composer_apply.md

@@ -1,6 +1,6 @@
 ## mach-composer apply
 
-Apply the configuration.
+Apply the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer apply [flags]
@@ -14,6 +14,7 @@ mach-composer apply [flags]
   -c, --component stringArray     
       --destroy                   Destroy option is a convenient way to destroy all remote objects managed by this mach config
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression
       --force-init                Force terraform initialization. By default mach-composer will reuse existing terraform resources
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for apply

docs/src/reference/cli/mach-composer_init.md

@@ -1,6 +1,6 @@
 ## mach-composer init
 
-Initialize site directories Terraform files.
+Initialize site directories Terraform files. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer init [flags]
@@ -11,6 +11,7 @@ mach-composer init [flags]
 ```
   -b, --buffer               Whether logs should be buffered and printed at the end of the run
   -f, --file string          YAML file to parse. (default "main.yml")
+      --filter stringArray   Run only nodes matching the filter expression
   -g, --github               Whether logs should be decorated with github-specific formatting
   -h, --help                 help for init
       --ignore-version       Skip MACH composer version check

docs/src/reference/cli/mach-composer_plan.md

@@ -1,6 +1,6 @@
 ## mach-composer plan
 
-Plan the configuration.
+Plan the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer plan [flags]
@@ -12,6 +12,7 @@ mach-composer plan [flags]
   -b, --buffer                    Whether logs should be buffered and printed at the end of the run
   -c, --component stringArray     
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression
       --force-init                Force terraform initialization. By default mach-composer will reuse existing terraform resources
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for plan

docs/src/reference/cli/mach-composer_show-plan.md

@@ -1,6 +1,6 @@
 ## mach-composer show-plan
 
-Show the planned configuration.
+Show the planned configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer show-plan [flags]
@@ -11,6 +11,7 @@ mach-composer show-plan [flags]
 ```
   -b, --buffer                    Whether logs should be buffered and printed at the end of the run
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression.
       --force-init                Force terraform initialization. By default mach-composer will reuse existing terraform resources
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for show-plan

docs/src/reference/cli/mach-composer_terraform.md

@@ -1,6 +1,6 @@
 ## mach-composer terraform
 
-Execute terraform commands directly
+Execute terraform commands directly. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ```
 mach-composer terraform [flags]
@@ -11,6 +11,7 @@ mach-composer terraform [flags]
 ```
   -b, --buffer                    Whether logs should be buffered and printed at the end of the run
   -f, --file string               YAML file to parse. (default "main.yml")
+      --filter stringArray        Run only nodes matching the filter expression
   -g, --github                    Whether logs should be decorated with github-specific formatting
   -h, --help                      help for terraform
       --ignore-change-detection   Ignore change detection to run even if the components are considered up to date. Per default the proxy will ignore change detection (default true)

docs/src/reference/cli/mach-composer_validate.md

@@ -1,6 +1,6 @@
 ## mach-composer validate
 
-Validate the generated terraform configuration.
+Validate the generated terraform configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.
 
 ### Synopsis
 
@@ -19,6 +19,7 @@ mach-composer validate [flags]
 ```
   -b, --buffer                   Whether logs should be buffered and printed at the end of the run
   -f, --file string              YAML file to parse. (default "main.yml")
+      --filter stringArray       Run only nodes matching the filter expression
   -g, --github                   Whether logs should be decorated with github-specific formatting
   -h, --help                     help for validate
       --ignore-version           Skip MACH composer version check

internal/cmd/apply.go

@@ -18,13 +18,14 @@ var applyFlags struct {
 	github                bool
 	bufferLogs            bool
 	components            []string
+	filters               []string
 	numWorkers            int
 	ignoreChangeDetection bool
 }
 
 var applyCmd = &cobra.Command{
 	Use:   "apply",
-	Short: "Apply the configuration.",
+	Short: "Apply the configuration. See [the documentation](/howto/cli/filtering-commands) for filtering options.",
 	PreRun: func(cmd *cobra.Command, args []string) {
 		preprocessCommonFlags(cmd)
 	},
@@ -39,6 +40,7 @@ func init() {
 	applyCmd.Flags().BoolVarP(&applyFlags.forceInit, "force-init", "", false, "Force terraform initialization. By default mach-composer will reuse existing terraform resources")
 	applyCmd.Flags().BoolVarP(&applyFlags.autoApprove, "auto-approve", "", false, "Suppress a terraform init for improved speed (not recommended for production usage)")
 	applyCmd.Flags().BoolVarP(&applyFlags.destroy, "destroy", "", false, "Destroy option is a convenient way to destroy all remote objects managed by this mach config")
+	applyCmd.Flags().StringArrayVarP(&applyFlags.filters, "filter", "", nil, "Run only nodes matching the filter expression")
 	applyCmd.Flags().StringArrayVarP(&applyFlags.components, "component", "c", nil, "")
 	applyCmd.Flags().BoolVarP(&applyFlags.ignoreChangeDetection, "ignore-change-detection", "", false, "Ignore change detection to run even if the components are considered up to date")
 	applyCmd.Flags().BoolVarP(&applyFlags.github, "github", "g", false, "Whether logs should be decorated with github-specific formatting")
@@ -47,7 +49,7 @@ func init() {
 
 func applyFunc(cmd *cobra.Command, _ []string) error {
 	if len(applyFlags.components) > 0 {
-		log.Warn().Msgf("Components option not implemented")
+		log.Warn().Msgf("Component option is deprecated. Please use `--filter your-component-name instead.")
 	}
 
 	if applyFlags.github && !applyFlags.bufferLogs {
@@ -84,5 +86,6 @@ func applyFunc(cmd *cobra.Command, _ []string) error {
 		IgnoreChangeDetection: applyFlags.ignoreChangeDetection,
 		BufferLogs:            applyFlags.bufferLogs,
 		Github:                applyFlags.github,
+		Filters:               applyFlags.filters,
 	})
 }