Add cobra hooks, document options

docs/customization/upgrade-notice/index.md

@@ -19,13 +19,13 @@ The upgrade notice is disabled by default. You can easily enable it based on you
 
 - Cobra CLI
 
-      ```go
-      extension.NewVersionCobraCmd(
-          // 2. Explict turn on upgrade notice
-          extension.WithUpgradeNotice("mszostok", "codeowners-validator"),
-      ),
-      ```
-   It prints the notice on standard error channel ([`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr))). As a result, output processing, such as executing `<cli> version -ojson | jq .gitCommit`, works properly even if the upgrade notice is displayed.
+    ```go
+    extension.NewVersionCobraCmd(
+        // 2. Explict turn on upgrade notice
+        extension.WithUpgradeNotice("mszostok", "codeowners-validator"),
+    ),
+    ```
+    It prints the notice on standard error channel ([`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr))). As a result, output processing, such as executing `<cli> version -ojson | jq .gitCommit`, works properly even if the upgrade notice is displayed.
 
 - Standalone
 

docs/get-started/usage/cobra.md

@@ -4,3 +4,40 @@ examples/cobra/main.go
 dff
 --8<--
 ```
+
+You can customize almost all aspects:
+
+- Enable upgrade notice:
+
+    ```go
+    extension.NewVersionCobraCmd(
+        // 2. Explict turn on upgrade notice
+        extension.WithUpgradeNotice("mszostok", "codeowners-validator"),
+    ),
+    ```
+    It prints the notice on standard error channel ([`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr))). As a result, output processing, such as executing `<cli> version -ojson | jq .gitCommit`, works properly even if the upgrade notice is displayed.
+
+- Define pre-hook function:
+
+    ```go
+    extension.WithPreHook(func(ctx context.Context) error {
+     // function body
+    })
+    ```
+
+- Define post-hook function:
+
+    !!! note ""
+         It's executed only if version print was successful.
+
+    ```go
+    extension.WithPostHook(func(ctx context.Context) error {
+     // function body
+    })
+    ```
+
+- Define custom aliases:
+
+    ```go
+    extension.WithAliasesOptions("v", "vv"),
+    ```

extension/cobra.go

@@ -34,7 +34,21 @@ func NewVersionCobraCmd(opts ...CobraOption) *cobra.Command {
 		Example: strings.ReplaceAll(example, "<cli>", version.Get().Meta.CLIName),
 		Aliases: options.Aliases,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return verPrinter.Print(cmd.OutOrStdout())
+			if options.PreHook != nil {
+				if err := options.PreHook(cmd.Context()); err != nil {
+					return err
+				}
+			}
+
+			if err := verPrinter.Print(cmd.OutOrStdout()); err != nil {
+				return err
+			}
+
+			if options.PostHook != nil {
+				return options.PostHook(cmd.Context())
+			}
+
+			return nil
 		},
 	}
 

extension/opts.go

@@ -1,6 +1,8 @@
 package extension
 
 import (
+	"context"
+
 	"go.szostok.io/version/printer"
 	"go.szostok.io/version/upgrade"
 )
@@ -22,7 +24,12 @@ type (
 	CobraOptions struct {
 		PrinterOptions []printer.ContainerOption
 		Aliases        []string
+		PreHook        HookFunc
+		PostHook       HookFunc
 	}
+
+	// HookFunc represents post execution function signature.
+	HookFunc func(ctx context.Context) error
 )
 
 // CustomPrinterOptions provides an option to set a custom printer related options across multiple constructors.
@@ -92,3 +99,37 @@ func WithAliasesOptions(aliases ...string) *AliasesOptions {
 func (c *AliasesOptions) ApplyToCobraOption(options *CobraOptions) {
 	options.Aliases = c.aliases
 }
+
+// PostHook provides an option to set post execution function across multiple constructors.
+type PostHook struct {
+	fn HookFunc
+}
+
+// WithPostHook sets post execution function.
+func WithPostHook(fn HookFunc) *PostHook {
+	return &PostHook{
+		fn: fn,
+	}
+}
+
+// ApplyToCobraOption sets a given option for Cobra.
+func (c *PostHook) ApplyToCobraOption(options *CobraOptions) {
+	options.PostHook = c.fn
+}
+
+// PreHook provides an option to set pre execution function across multiple constructors.
+type PreHook struct {
+	fn HookFunc
+}
+
+// WithPreHook sets pre execution function.
+func WithPreHook(fn HookFunc) *PreHook {
+	return &PreHook{
+		fn: fn,
+	}
+}
+
+// ApplyToCobraOption sets a given option for Cobra.
+func (c *PreHook) ApplyToCobraOption(options *CobraOptions) {
+	options.PreHook = c.fn
+}

magefiles/target/format-docs.go

@@ -21,6 +21,7 @@ var excludedFromFormatting = []string{
 	"docs/customization/upgrade-notice/index.md",
 	"docs/customization/upgrade-notice/layout.md",
 	"docs/get-started/upgrade-notice.md",
+	"docs/get-started/usage/cobra.md",
 }
 
 func FmtDocs(onlyCheck bool) error {