fix(cli/help): show deprecation notice properly for flags (#7904)

cli/help.go

@@ -135,6 +135,31 @@ var usageTemplate = template.Must(
 			"isDeprecated": func(opt clibase.Option) bool {
 				return len(opt.UseInstead) > 0
 			},
+			"useInstead": func(opt clibase.Option) string {
+				var sb strings.Builder
+				for i, s := range opt.UseInstead {
+					if i > 0 {
+						if i == len(opt.UseInstead)-1 {
+							_, _ = sb.WriteString(" and ")
+						} else {
+							_, _ = sb.WriteString(", ")
+						}
+					}
+					if s.Flag != "" {
+						_, _ = sb.WriteString("--")
+						_, _ = sb.WriteString(s.Flag)
+					} else if s.FlagShorthand != "" {
+						_, _ = sb.WriteString("-")
+						_, _ = sb.WriteString(s.FlagShorthand)
+					} else if s.Env != "" {
+						_, _ = sb.WriteString("$")
+						_, _ = sb.WriteString(s.Env)
+					} else {
+						_, _ = sb.WriteString(s.Name)
+					}
+				}
+				return sb.String()
+			},
 			"formatLong": func(long string) string {
 				// We intentionally don't wrap here because it would misformat
 				// examples, where the new line would start without the prior

cli/help.tpl

@@ -43,7 +43,7 @@ Usage: {{.FullUsage}}
         {{- with $option.Description }}
             {{- $desc := $option.Description }}
 {{ indent $desc 10 }}
-{{- if isDeprecated $option }} DEPRECATED {{ end }}
+{{- if isDeprecated $option }}{{ indent (printf "DEPRECATED: Use %s instead." (useInstead $option)) 10 }}{{ end }}
         {{- end -}}
     {{- end }}
 {{- end }}

cli/testdata/coder_ssh_--help.golden

@@ -28,7 +28,8 @@ Start a shell into a workspace
           Enter workspace immediately after the agent has connected. This is the
           default if the template has configured the agent startup script
           behavior as non-blocking.
- DEPRECATED 
+          DEPRECATED: Use --wait instead.
+
       --stdio bool, $CODER_SSH_STDIO
           Specifies whether to emit SSH output over stdin/stdout.