feat(cli): add CLI support for listing presets (#18910)

## Description 

This PR introduces a new `list presets` command to display the presets
associated with a given template.
By default, it displays the presets for the template's active version,
unless a `--template-version` flag is provided.

## Changes

* Added a new `list presets` command under `coder templates presets` to
display presets associated with a template.
* By default, the command lists presets from the template’s active
version.
* Users can override the default behavior by providing the
`--template-version` flag to target a specific version.

```
> coder templates versions presets list --help

USAGE:
  coder templates presets list [flags] <template>

  List all presets of the specified template. Defaults to the active template version.

OPTIONS:
  -O, --org string, $CODER_ORGANIZATION
          Select which organization (uuid or name) to use.

  -c, --column [name|parameters|default|desired prebuild instances] (default: name,parameters,default,desired prebuild instances)
          Columns to display in table output.

  -o, --output table|json (default: table)
          Output format.

      --template-version string
          Specify a template version to list presets for. Defaults to the active version.
```

Related PR: https://github.com/coder/coder/pull/18912 - please consider
both PRs together as they’re part of the same workflow
Relates to issue: https://github.com/coder/coder/issues/16594

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added CLI commands to manage and list presets for specific template
versions, supporting tabular and JSON output.
* Introduced a new CLI subcommand group for template version presets,
including detailed help and documentation.
* Added support for displaying and managing the desired number of
prebuild instances for presets in CLI, API, and UI.

* **Documentation**
* Updated and expanded CLI and API documentation to describe new
commands, options, and the desired prebuild instances field in presets.
* Added new help output and reference files for template version presets
commands.

* **Bug Fixes**
* Ensured correct handling and display of the desired prebuild instances
property for presets across CLI, API, and UI.

* **Tests**
* Introduced end-to-end tests for listing template version presets,
covering scenarios with and without presets.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

cli/templatepresets.go

@@ -0,0 +1,168 @@
+package cli
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) templatePresets() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:     "presets",
+		Short:   "Manage presets of the specified template",
+		Aliases: []string{"preset"},
+		Long: FormatExamples(
+			Example{
+				Description: "List presets for the active version of a template",
+				Command:     "coder templates presets list my-template",
+			},
+			Example{
+				Description: "List presets for a specific version of a template",
+				Command:     "coder templates presets list my-template --template-version my-template-version",
+			},
+		),
+		Handler: func(inv *serpent.Invocation) error {
+			return inv.Command.HelpHandler(inv)
+		},
+		Children: []*serpent.Command{
+			r.templatePresetsList(),
+		},
+	}
+
+	return cmd
+}
+
+func (r *RootCmd) templatePresetsList() *serpent.Command {
+	defaultColumns := []string{
+		"name",
+		"parameters",
+		"default",
+		"desired prebuild instances",
+	}
+	formatter := cliui.NewOutputFormatter(
+		cliui.TableFormat([]templatePresetRow{}, defaultColumns),
+		cliui.JSONFormat(),
+	)
+	client := new(codersdk.Client)
+	orgContext := NewOrganizationContext()
+
+	var templateVersion string
+
+	cmd := &serpent.Command{
+		Use: "list <template>",
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(1),
+			r.InitClient(client),
+		),
+		Short: "List all presets of the specified template. Defaults to the active template version.",
+		Options: serpent.OptionSet{
+			{
+				Name:        "template-version",
+				Description: "Specify a template version to list presets for. Defaults to the active version.",
+				Flag:        "template-version",
+				Value:       serpent.StringOf(&templateVersion),
+			},
+		},
+		Handler: func(inv *serpent.Invocation) error {
+			organization, err := orgContext.Selected(inv, client)
+			if err != nil {
+				return xerrors.Errorf("get current organization: %w", err)
+			}
+
+			template, err := client.TemplateByName(inv.Context(), organization.ID, inv.Args[0])
+			if err != nil {
+				return xerrors.Errorf("get template by name: %w", err)
+			}
+
+			// If a template version is specified via flag, fetch that version by name
+			var version codersdk.TemplateVersion
+			if len(templateVersion) > 0 {
+				version, err = client.TemplateVersionByName(inv.Context(), template.ID, templateVersion)
+				if err != nil {
+					return xerrors.Errorf("get template version by name: %w", err)
+				}
+			} else {
+				// Otherwise, use the template's active version
+				version, err = client.TemplateVersion(inv.Context(), template.ActiveVersionID)
+				if err != nil {
+					return xerrors.Errorf("get active template version: %w", err)
+				}
+			}
+
+			presets, err := client.TemplateVersionPresets(inv.Context(), version.ID)
+			if err != nil {
+				return xerrors.Errorf("get template versions presets by template version: %w", err)
+			}
+
+			if len(presets) == 0 {
+				cliui.Infof(
+					inv.Stdout,
+					"No presets found for template %q and template-version %q.\n", template.Name, version.Name,
+				)
+				return nil
+			}
+
+			cliui.Infof(
+				inv.Stdout,
+				"Showing presets for template %q and template version %q.\n", template.Name, version.Name,
+			)
+			rows := templatePresetsToRows(presets...)
+			out, err := formatter.Format(inv.Context(), rows)
+			if err != nil {
+				return xerrors.Errorf("render table: %w", err)
+			}
+
+			_, err = fmt.Fprintln(inv.Stdout, out)
+			return err
+		},
+	}
+
+	orgContext.AttachOptions(cmd)
+	formatter.AttachOptions(&cmd.Options)
+	return cmd
+}
+
+type templatePresetRow struct {
+	// For json format:
+	TemplatePreset codersdk.Preset `table:"-"`
+
+	// For table format:
+	Name                     string `json:"-" table:"name,default_sort"`
+	Parameters               string `json:"-" table:"parameters"`
+	Default                  bool   `json:"-" table:"default"`
+	DesiredPrebuildInstances string `json:"-" table:"desired prebuild instances"`
+}
+
+func formatPresetParameters(params []codersdk.PresetParameter) string {
+	var paramsStr []string
+	for _, p := range params {
+		paramsStr = append(paramsStr, fmt.Sprintf("%s=%s", p.Name, p.Value))
+	}
+	return strings.Join(paramsStr, ",")
+}
+
+// templatePresetsToRows converts a list of presets to a list of rows
+// for outputting.
+func templatePresetsToRows(presets ...codersdk.Preset) []templatePresetRow {
+	rows := make([]templatePresetRow, len(presets))
+	for i, preset := range presets {
+		prebuildInstances := "-"
+		if preset.DesiredPrebuildInstances != nil {
+			prebuildInstances = strconv.Itoa(*preset.DesiredPrebuildInstances)
+		}
+		rows[i] = templatePresetRow{
+			Name:                     preset.Name,
+			Parameters:               formatPresetParameters(preset.Parameters),
+			Default:                  preset.Default,
+			DesiredPrebuildInstances: prebuildInstances,
+		}
+	}
+
+	return rows
+}