feat: allow users to set descriptions (#2239)

- [x] needs docs!

core/server/api_container/server/startosis_engine/kurtosis_instruction/add_service/add_service.go

@@ -26,6 +26,8 @@ const (
 
 	ServiceNameArgName   = "name"
 	ServiceConfigArgName = "config"
+
+	addServiceDescriptionFormatStr = "Adding service with name '%v' and image '%v'"
 )
 
 func NewAddService(
@@ -78,6 +80,7 @@ func NewAddService(
 				readyCondition: nil, // populated at interpretation time
 
 				interpretationTimeValueStore: interpretationTimeValueStore,
+				description:                  "", // populated at interpretation time
 			}
 		},
 
@@ -103,7 +106,8 @@ type AddServiceCapabilities struct {
 
 	interpretationTimeValueStore *interpretation_time_value_store.InterpretationTimeValueStore
 
-	resultUuid string
+	resultUuid  string
+	description string
 }
 
 func (builtin *AddServiceCapabilities) Interpret(locatorOfModuleInWhichThisBuiltInIsBeingCalled string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -136,6 +140,8 @@ func (builtin *AddServiceCapabilities) Interpret(locatorOfModuleInWhichThisBuilt
 		return nil, startosis_errors.WrapWithInterpretationError(err, "Unable to create runtime value to hold '%v' command return values", AddServiceBuiltinName)
 	}
 
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(addServiceDescriptionFormatStr, builtin.serviceName, builtin.serviceConfig.GetContainerImageName()))
+
 	returnValue, interpretationErr := makeAddServiceInterpretationReturnValue(serviceName, builtin.serviceConfig, builtin.resultUuid)
 	if interpretationErr != nil {
 		return nil, interpretationErr
@@ -243,7 +249,7 @@ func (builtin *AddServiceCapabilities) FillPersistableAttributes(builder *enclav
 }
 
 func (builtin *AddServiceCapabilities) Description() string {
-	return fmt.Sprintf("Adding service with name '%v' and image '%v'", builtin.serviceName, builtin.serviceConfig.GetContainerImageName())
+	return builtin.description
 }
 
 func validateAndConvertConfigAndReadyCondition(

core/server/api_container/server/startosis_engine/kurtosis_instruction/add_service/add_services.go

@@ -29,6 +29,8 @@ const (
 	AddServicesBuiltinName = "add_services"
 
 	ConfigsArgName = "configs"
+
+	addServicesDescriptionFormatStr = "Adding '%v' services with names '%v'"
 )
 
 func NewAddServices(
@@ -71,6 +73,7 @@ func NewAddServices(
 
 				resultUuids:     map[service.ServiceName]string{}, // populated at interpretation time
 				readyConditions: nil,                              // populated at interpretation time
+				description:     "",                               // populated at interpretation time
 			}
 		},
 
@@ -95,6 +98,7 @@ type AddServicesCapabilities struct {
 	readyConditions map[service.ServiceName]*service_config.ReadyCondition
 
 	resultUuids map[service.ServiceName]string
+	description string
 }
 
 func (builtin *AddServicesCapabilities) Interpret(locatorOfModuleInWhichThisBuiltInIsBeingCalled string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -116,6 +120,8 @@ func (builtin *AddServicesCapabilities) Interpret(locatorOfModuleInWhichThisBuil
 	builtin.serviceConfigs = serviceConfigs
 	builtin.readyConditions = readyConditions
 
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(addServicesDescriptionFormatStr, len(builtin.serviceConfigs), getNamesAsCommaSeparatedList(builtin.serviceConfigs)))
+
 	resultUuids, returnValue, interpretationErr := makeAndPersistAddServicesInterpretationReturnValue(builtin.serviceConfigs, builtin.runtimeValueStore, builtin.interpretationTimeValueStore)
 	if interpretationErr != nil {
 		return nil, interpretationErr
@@ -358,7 +364,7 @@ func (builtin *AddServicesCapabilities) allServicesReadinessCheck(
 }
 
 func (builtin *AddServicesCapabilities) Description() string {
-	return fmt.Sprintf("Adding '%v' services with names '%v'", len(builtin.serviceConfigs), getNamesAsCommaSeparatedList(builtin.serviceConfigs))
+	return builtin.description
 }
 
 func getNamesAsCommaSeparatedList(serviceConfigs map[service.ServiceName]*service.ServiceConfig) string {

core/server/api_container/server/startosis_engine/kurtosis_instruction/exec/exec.go

@@ -35,6 +35,7 @@ const (
 
 const (
 	defaultSkipCodeCheck = false
+	descriptionFormatStr = "Executing command on service '%v'"
 )
 
 func NewExec(serviceNetwork service_network.ServiceNetwork, runtimeValueStore *runtime_value_store.RuntimeValueStore) *kurtosis_plan_instruction.KurtosisPlanInstruction {
@@ -81,6 +82,7 @@ func NewExec(serviceNetwork service_network.ServiceNetwork, runtimeValueStore *r
 				resultUuid:      "",    // will be populated at interpretation time
 				acceptableCodes: nil,   // will be populated at interpretation time
 				skipCodeCheck:   false, // will be populated at interpretation time
+				description:     "",    // populated at interpretation time
 			}
 		},
 
@@ -100,6 +102,7 @@ type ExecCapabilities struct {
 	resultUuid      string
 	acceptableCodes []int64
 	skipCodeCheck   bool
+	description     string
 }
 
 func (builtin *ExecCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -147,6 +150,8 @@ func (builtin *ExecCapabilities) Interpret(_ string, arguments *builtin_argument
 	builtin.acceptableCodes = acceptableCodes
 	builtin.skipCodeCheck = skipCodeCheck
 
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.serviceName))
+
 	returnValue, interpretationErr := builtin.execRecipe.CreateStarlarkReturnValue(builtin.resultUuid)
 	if interpretationErr != nil {
 		return nil, startosis_errors.WrapWithInterpretationError(err, "An error occurred while generating return value for %v instruction", ExecBuiltinName)
@@ -190,7 +195,7 @@ func (builtin *ExecCapabilities) FillPersistableAttributes(builder *enclave_plan
 }
 
 func (builtin *ExecCapabilities) Description() string {
-	return fmt.Sprintf("Executing command on service '%v'", builtin.serviceName)
+	return builtin.description
 }
 
 func (builtin *ExecCapabilities) isAcceptableCode(recipeResult map[string]starlark.Comparable) bool {

core/server/api_container/server/startosis_engine/kurtosis_instruction/get_service/get_service.go

@@ -18,6 +18,8 @@ import (
 const (
 	GetServiceBuiltinName = "get_service"
 	ServiceNameArgName    = "name"
+
+	descriptionFormatStr = "Fetching service '%v'"
 )
 
 func NewGetService(interpretationTimeStore *interpretation_time_value_store.InterpretationTimeValueStore) *kurtosis_plan_instruction.KurtosisPlanInstruction {
@@ -37,7 +39,11 @@ func NewGetService(interpretationTimeStore *interpretation_time_value_store.Inte
 			Deprecation: nil,
 		},
 		Capabilities: func() kurtosis_plan_instruction.KurtosisPlanInstructionCapabilities {
-			return &GetServiceCapabilities{interpretationTimeStore: interpretationTimeStore, serviceName: ""}
+			return &GetServiceCapabilities{
+				interpretationTimeStore: interpretationTimeStore,
+				serviceName:             "",
+				description:             "", // populated at interpretation time
+			}
 		},
 		DefaultDisplayArguments: map[string]bool{
 			ServiceNameArgName: true,
@@ -48,6 +54,7 @@ func NewGetService(interpretationTimeStore *interpretation_time_value_store.Inte
 type GetServiceCapabilities struct {
 	interpretationTimeStore *interpretation_time_value_store.InterpretationTimeValueStore
 	serviceName             service.ServiceName
+	description             string
 }
 
 func (builtin *GetServiceCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -58,6 +65,7 @@ func (builtin *GetServiceCapabilities) Interpret(_ string, arguments *builtin_ar
 	serviceName := service.ServiceName(serviceNameArgumentValue.GoString())
 
 	builtin.serviceName = serviceName
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.serviceName))
 
 	serviceStarlarkValue, err := builtin.interpretationTimeStore.GetService(serviceName)
 	if err != nil {
@@ -95,5 +103,5 @@ func (builtin *GetServiceCapabilities) FillPersistableAttributes(builder *enclav
 }
 
 func (builtin *GetServiceCapabilities) Description() string {
-	return fmt.Sprintf("Fetched service '%v'", builtin.serviceName)
+	return builtin.description
 }

core/server/api_container/server/startosis_engine/kurtosis_instruction/kurtosis_print/kurtosis_print.go

@@ -20,6 +20,8 @@ const (
 	PrintBuiltinName = "print"
 
 	PrintArgName = "msg"
+
+	descriptionFormatStr = "Printing a message"
 )
 
 func NewPrint(serviceNetwork service_network.ServiceNetwork, runtimeValueStore *runtime_value_store.RuntimeValueStore) *kurtosis_plan_instruction.KurtosisPlanInstruction {
@@ -42,7 +44,8 @@ func NewPrint(serviceNetwork service_network.ServiceNetwork, runtimeValueStore *
 				serviceNetwork:    serviceNetwork,
 				runtimeValueStore: runtimeValueStore,
 
-				msg: nil, // populated at interpretation time
+				msg:         nil, // populated at interpretation time
+				description: "",  // populated at interpretation time
 			}
 		},
 
@@ -56,7 +59,8 @@ type PrintCapabilities struct {
 	serviceNetwork    service_network.ServiceNetwork
 	runtimeValueStore *runtime_value_store.RuntimeValueStore
 
-	msg starlark.Value
+	msg         starlark.Value
+	description string
 }
 
 func (builtin *PrintCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -65,6 +69,7 @@ func (builtin *PrintCapabilities) Interpret(_ string, arguments *builtin_argumen
 		return nil, startosis_errors.WrapWithInterpretationError(err, "Unable to extract value for '%s' argument", PrintArgName)
 	}
 	builtin.msg = msg
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, descriptionFormatStr)
 	return starlark.None, nil
 }
 
@@ -101,5 +106,5 @@ func (builtin *PrintCapabilities) FillPersistableAttributes(builder *enclave_pla
 }
 
 func (builtin *PrintCapabilities) Description() string {
-	return "Printing a message"
+	return builtin.description
 }

core/server/api_container/server/startosis_engine/kurtosis_instruction/remove_service/remove_service.go

@@ -19,7 +19,8 @@ import (
 const (
 	RemoveServiceBuiltinName = "remove_service"
 
-	ServiceNameArgName = "name"
+	ServiceNameArgName   = "name"
+	descriptionFormatStr = "Removing service '%v'"
 )
 
 func NewRemoveService(serviceNetwork service_network.ServiceNetwork) *kurtosis_plan_instruction.KurtosisPlanInstruction {
@@ -45,6 +46,7 @@ func NewRemoveService(serviceNetwork service_network.ServiceNetwork) *kurtosis_p
 				serviceNetwork: serviceNetwork,
 
 				serviceName: "", // populated at interpretation time
+				description: "", // populated at interpretation time
 			}
 		},
 
@@ -58,6 +60,7 @@ type RemoveServiceCapabilities struct {
 	serviceNetwork service_network.ServiceNetwork
 
 	serviceName service.ServiceName
+	description string
 }
 
 func (builtin *RemoveServiceCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -67,6 +70,7 @@ func (builtin *RemoveServiceCapabilities) Interpret(_ string, arguments *builtin
 	}
 
 	builtin.serviceName = service.ServiceName(serviceName.GoString())
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.serviceName))
 	return starlark.None, nil
 }
 
@@ -103,5 +107,5 @@ func (builtin *RemoveServiceCapabilities) FillPersistableAttributes(builder *enc
 }
 
 func (builtin *RemoveServiceCapabilities) Description() string {
-	return fmt.Sprintf("Removing service '%v'", builtin.serviceName)
+	return builtin.description
 }

core/server/api_container/server/startosis_engine/kurtosis_instruction/render_templates/render_templates.go

@@ -33,6 +33,7 @@ const (
 	templateDataFieldKey    = "data"
 	jsonParsingThreadName   = "Unused thread name"
 	jsonParsingModuleId     = "Unused module id"
+	descriptionFormatStr    = "Rendering a template to a files artifact with name '%v'"
 )
 
 func NewRenderTemplatesInstruction(serviceNetwork service_network.ServiceNetwork, runtimeValueStore *runtime_value_store.RuntimeValueStore) *kurtosis_plan_instruction.KurtosisPlanInstruction {
@@ -63,6 +64,7 @@ func NewRenderTemplatesInstruction(serviceNetwork service_network.ServiceNetwork
 
 				artifactName:                      "",  // will be populated at interpretation time
 				templatesAndDataByDestRelFilepath: nil, // will be populated at interpretation time
+				description:                       "",  // populated at interpretation time
 			}
 		},
 
@@ -79,6 +81,8 @@ type RenderTemplatesCapabilities struct {
 	templatesAndDataByDestRelFilepath map[string]*render_templates.TemplateData
 
 	runtimeValueStore *runtime_value_store.RuntimeValueStore
+
+	description string
 }
 
 func (builtin *RenderTemplatesCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -105,6 +109,7 @@ func (builtin *RenderTemplatesCapabilities) Interpret(_ string, arguments *built
 		return nil, interpretationErr
 	}
 	builtin.templatesAndDataByDestRelFilepath = templatesAndDataByDestRelFilepath
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.artifactName))
 	return starlark.String(builtin.artifactName), nil
 }
 
@@ -169,7 +174,7 @@ func (builtin *RenderTemplatesCapabilities) FillPersistableAttributes(builder *e
 }
 
 func (builtin *RenderTemplatesCapabilities) Description() string {
-	return fmt.Sprintf("Rendering a template to a files artifact with name '%v'", builtin.artifactName)
+	return builtin.description
 }
 
 func parseTemplatesAndData(templatesAndData *starlark.Dict) (map[string]*render_templates.TemplateData, *startosis_errors.InterpretationError) {

core/server/api_container/server/startosis_engine/kurtosis_instruction/request/request.go

@@ -35,6 +35,7 @@ var defaultAcceptableCodes = []int64{
 
 const (
 	defaultSkipCodeCheck = false
+	descriptionFormatStr = "Running '%v' request on service '%v'"
 )
 
 const (
@@ -91,6 +92,7 @@ func NewRequest(serviceNetwork service_network.ServiceNetwork, runtimeValueStore
 				resultUuid:        "",    // populated at interpretation time
 				acceptableCodes:   nil,   // populated at interpretation time
 				skipCodeCheck:     false, // populated at interpretation time
+				description:       "",    // populated at interpretation time
 			}
 		},
 
@@ -109,6 +111,8 @@ type RequestCapabilities struct {
 	resultUuid        string
 	acceptableCodes   []int64
 	skipCodeCheck     bool
+
+	description string
 }
 
 func (builtin *RequestCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -155,6 +159,7 @@ func (builtin *RequestCapabilities) Interpret(_ string, arguments *builtin_argum
 	builtin.resultUuid = resultUuid
 	builtin.acceptableCodes = acceptableCodes
 	builtin.skipCodeCheck = skipCodeCheck
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.httpRequestRecipe.RequestType(), builtin.serviceName))
 
 	returnValue, interpretationErr := builtin.httpRequestRecipe.CreateStarlarkReturnValue(builtin.resultUuid)
 	if interpretationErr != nil {
@@ -203,7 +208,7 @@ func (builtin *RequestCapabilities) FillPersistableAttributes(builder *enclave_p
 }
 
 func (builtin *RequestCapabilities) Description() string {
-	return fmt.Sprintf("Running '%v' request on service '%v'", builtin.httpRequestRecipe.RequestType(), builtin.serviceName)
+	return builtin.description
 }
 
 func (builtin *RequestCapabilities) isAcceptableCode(recipeResult map[string]starlark.Comparable) bool {

core/server/api_container/server/startosis_engine/kurtosis_instruction/start_service/start_service.go

@@ -22,6 +22,10 @@ const (
 	ServiceNameArgName = "name"
 )
 
+const (
+	descriptionFormatStr = "Starting service '%v'"
+)
+
 func NewStartService(serviceNetwork service_network.ServiceNetwork) *kurtosis_plan_instruction.KurtosisPlanInstruction {
 	return &kurtosis_plan_instruction.KurtosisPlanInstruction{
 		KurtosisBaseBuiltin: &kurtosis_starlark_framework.KurtosisBaseBuiltin{
@@ -45,6 +49,7 @@ func NewStartService(serviceNetwork service_network.ServiceNetwork) *kurtosis_pl
 				serviceNetwork: serviceNetwork,
 
 				serviceName: "", // populated at interpretation time
+				description: "", // populated at interpretation time
 			}
 		},
 
@@ -58,6 +63,8 @@ type StartServiceCapabilities struct {
 	serviceNetwork service_network.ServiceNetwork
 
 	serviceName service.ServiceName
+
+	description string
 }
 
 func (builtin *StartServiceCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
@@ -67,6 +74,7 @@ func (builtin *StartServiceCapabilities) Interpret(_ string, arguments *builtin_
 	}
 
 	builtin.serviceName = service.ServiceName(serviceName.GoString())
+	builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.serviceName))
 	return starlark.None, nil
 }
 
@@ -99,5 +107,5 @@ func (builtin *StartServiceCapabilities) FillPersistableAttributes(builder *encl
 }
 
 func (builtin *StartServiceCapabilities) Description() string {
-	return fmt.Sprintf("Starting service '%v'", builtin.serviceName)
+	return builtin.description
 }