feat: add initial helper methods

command.go

@@ -0,0 +1,83 @@
+package sdk
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+const (
+	cmdSeparator        = "::"
+	cmdPropertiesPrefix = " "
+)
+
+// CommandProperties is a named "map[string]string" type to hold key-value pairs
+// passed to an actions command.
+type CommandProperties map[string]string
+
+// String encodes the CommandProperties to a string as comma separated
+// 'key=value' pairs. The pairs are joined in a chronological order.
+func (props *CommandProperties) String() string {
+	l := make([]string, 0, len(*props))
+	for k, v := range *props {
+		l = append(l, fmt.Sprintf("%s=%s", k, escapeProperty(v)))
+	}
+
+	sort.Strings(l)
+	return strings.Join(l, ",")
+}
+
+// Command can be issued by a GitHub action by writing to `stdout` with
+// following format.
+//
+// ::name key=value,key=value::message
+//
+//	Examples:
+//	  ::warning::This is the message
+//	  ::set-env name=MY_VAR::some value
+type Command struct {
+	Name       string
+	Message    string
+	Properties CommandProperties
+}
+
+// String encodes the Command to a string in the following format:
+//
+// ::name key=value,key=value::message
+func (cmd *Command) String() string {
+	if cmd.Name == "" {
+		cmd.Name = "missing.command"
+	}
+
+	var builder strings.Builder
+	builder.WriteString(cmdSeparator)
+	builder.WriteString(cmd.Name)
+	if len(cmd.Properties) > 0 {
+		builder.WriteString(cmdPropertiesPrefix)
+		builder.WriteString(cmd.Properties.String())
+	}
+
+	builder.WriteString(cmdSeparator)
+	builder.WriteString(escapeData(cmd.Message))
+	return builder.String()
+}
+
+// escapeData escapes string values for presentation in the output of a command.
+// This is a not-so-well-documented requirement of commands that define a message.
+func escapeData(v string) string {
+	v = strings.ReplaceAll(v, "%", "%25")
+	v = strings.ReplaceAll(v, "\r", "%0D")
+	v = strings.ReplaceAll(v, "\n", "%0A")
+	return v
+}
+
+// escapeData escapes command property values for presentation in the output of
+// a command.
+func escapeProperty(v string) string {
+	v = strings.ReplaceAll(v, "%", "%25")
+	v = strings.ReplaceAll(v, "\r", "%0D")
+	v = strings.ReplaceAll(v, "\n", "%0A")
+	v = strings.ReplaceAll(v, ":", "%3A")
+	v = strings.ReplaceAll(v, ",", "%2C")
+	return v
+}