feat: added a description field to instructions (#2147)

## Description

The description field can be used instead of the full instruction while
outputting to the end user

In the CLI this can be accessed using `--description`;

api/golang/core/lib/binding_constructors/binding_constructors.go

@@ -263,13 +263,14 @@ func NewStarlarkRunResponseLineFromRunSuccessEvent(serializedOutputObject string
 	}
 }
 
-func NewStarlarkInstruction(position *kurtosis_core_rpc_api_bindings.StarlarkInstructionPosition, name string, executableInstruction string, arguments []*kurtosis_core_rpc_api_bindings.StarlarkInstructionArg, isSkipped bool) *kurtosis_core_rpc_api_bindings.StarlarkInstruction {
+func NewStarlarkInstruction(position *kurtosis_core_rpc_api_bindings.StarlarkInstructionPosition, name string, executableInstruction string, arguments []*kurtosis_core_rpc_api_bindings.StarlarkInstructionArg, isSkipped bool, description string) *kurtosis_core_rpc_api_bindings.StarlarkInstruction {
 	return &kurtosis_core_rpc_api_bindings.StarlarkInstruction{
 		InstructionName:       name,
 		Position:              position,
 		ExecutableInstruction: executableInstruction,
 		Arguments:             arguments,
 		IsSkipped:             isSkipped,
+		Description:           description,
 	}
 }
 

api/protobuf/core/api_container_service.proto

@@ -256,6 +256,8 @@ message StarlarkInstruction {
   string executable_instruction = 4;
 
   bool is_skipped = 5;
+
+  string description = 6;
 }
 
 message StarlarkInstructionResult {

api/rust/src/api_container_api.rs

@@ -308,6 +308,8 @@ pub struct StarlarkInstruction {
     pub executable_instruction: ::prost::alloc::string::String,
     #[prost(bool, tag = "5")]
     pub is_skipped: bool,
+    #[prost(string, tag = "6")]
+    pub description: ::prost::alloc::string::String,
 }
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]

api/typescript/src/core/kurtosis_core_rpc_api_bindings/api_container_service_pb.d.ts

@@ -502,6 +502,9 @@ export class StarlarkInstruction extends jspb.Message {
   getIsSkipped(): boolean;
   setIsSkipped(value: boolean): StarlarkInstruction;
 
+  getDescription(): string;
+  setDescription(value: string): StarlarkInstruction;
+
   serializeBinary(): Uint8Array;
   toObject(includeInstance?: boolean): StarlarkInstruction.AsObject;
   static toObject(includeInstance: boolean, msg: StarlarkInstruction): StarlarkInstruction.AsObject;
@@ -517,6 +520,7 @@ export namespace StarlarkInstruction {
     argumentsList: Array<StarlarkInstructionArg.AsObject>,
     executableInstruction: string,
     isSkipped: boolean,
+    description: string,
   }
 }
 

api/typescript/src/core/kurtosis_core_rpc_api_bindings/api_container_service_pb.js

@@ -3972,7 +3972,8 @@ proto.api_container_api.StarlarkInstruction.toObject = function(includeInstance,
     argumentsList: jspb.Message.toObjectList(msg.getArgumentsList(),
     proto.api_container_api.StarlarkInstructionArg.toObject, includeInstance),
     executableInstruction: jspb.Message.getFieldWithDefault(msg, 4, ""),
-    isSkipped: jspb.Message.getBooleanFieldWithDefault(msg, 5, false)
+    isSkipped: jspb.Message.getBooleanFieldWithDefault(msg, 5, false),
+    description: jspb.Message.getFieldWithDefault(msg, 6, "")
   };
 
   if (includeInstance) {
@@ -4031,6 +4032,10 @@ proto.api_container_api.StarlarkInstruction.deserializeBinaryFromReader = functi
       var value = /** @type {boolean} */ (reader.readBool());
       msg.setIsSkipped(value);
       break;
+    case 6:
+      var value = /** @type {string} */ (reader.readString());
+      msg.setDescription(value);
+      break;
     default:
       reader.skipField();
       break;
@@ -4097,6 +4102,13 @@ proto.api_container_api.StarlarkInstruction.serializeBinaryToWriter = function(m
       f
     );
   }
+  f = message.getDescription();
+  if (f.length > 0) {
+    writer.writeString(
+      6,
+      f
+    );
+  }
 };
 
 
@@ -4229,6 +4241,24 @@ proto.api_container_api.StarlarkInstruction.prototype.setIsSkipped = function(va
 };
 
 
+/**
+ * optional string description = 6;
+ * @return {string}
+ */
+proto.api_container_api.StarlarkInstruction.prototype.getDescription = function() {
+  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 6, ""));
+};
+
+
+/**
+ * @param {string} value
+ * @return {!proto.api_container_api.StarlarkInstruction} returns this
+ */
+proto.api_container_api.StarlarkInstruction.prototype.setDescription = function(value) {
+  return jspb.Message.setProto3StringField(this, 6, value);
+};
+
+
 
 
 

api/typescript/src/core/kurtosis_core_rpc_api_bindings/connect/api_container_service_pb.d.ts

@@ -653,6 +653,11 @@ export declare class StarlarkInstruction extends Message<StarlarkInstruction> {
    */
   isSkipped: boolean;
 
+  /**
+   * @generated from field: string description = 6;
+   */
+  description: string;
+
   constructor(data?: PartialMessage<StarlarkInstruction>);
 
   static readonly runtime: typeof proto3;

api/typescript/src/core/kurtosis_core_rpc_api_bindings/connect/api_container_service_pb.js

@@ -226,6 +226,7 @@ export const StarlarkInstruction = proto3.makeMessageType(
     { no: 3, name: "arguments", kind: "message", T: StarlarkInstructionArg, repeated: true },
     { no: 4, name: "executable_instruction", kind: "scalar", T: 9 /* ScalarType.STRING */ },
     { no: 5, name: "is_skipped", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+    { no: 6, name: "description", kind: "scalar", T: 9 /* ScalarType.STRING */ },
   ],
 );
 

cli/cli/command_args/run/verbosity.go

@@ -8,4 +8,5 @@ const (
 	Detailed
 	Executable
 	OutputOnly
+	Description
 )

cli/cli/commands/run/run.go

@@ -140,7 +140,7 @@ var StarlarkRunCmd = &engine_consuming_kurtosis_command.EngineConsumingKurtosisC
 		},
 		{
 			Key:       verbosityFlagKey,
-			Usage:     fmt.Sprintf("The verbosity of the command output: %s. If unset, it defaults to `brief` for a concise and explicit output. Use `detailed` to display the exhaustive list of arguments for each command. `executable` will generate executable Starlark instructions.", strings.Join(command_args_run.VerbosityStrings(), ", ")),
+			Usage:     fmt.Sprintf("The verbosity of the command output: %s. If unset, it defaults to `brief` for a concise and explicit output. Use `detailed` to display the exhaustive list of arguments for each command. `executable` will generate executable Starlark instructions. `description` will just print a description of what is about to happen without any details", strings.Join(command_args_run.VerbosityStrings(), ", ")),
 			Type:      flags.FlagType_String,
 			Shorthand: "v",
 			Default:   defaultVerbosity,

cli/cli/helpers/output_printers/kurtosis_instruction_printer.go

@@ -189,6 +189,8 @@ func formatInfo(infoMessage string) string {
 func formatInstruction(instruction *kurtosis_core_rpc_api_bindings.StarlarkInstruction, verbosity run.Verbosity) string {
 	var serializedInstruction string
 	switch verbosity {
+	case run.Description:
+		serializedInstruction = instruction.Description
 	case run.Brief:
 		serializedInstruction = formatInstructionToReadableString(instruction, false)
 	case run.Detailed:

cli/cli/helpers/output_printers/kurtosis_instruction_printer_test.go

@@ -27,7 +27,8 @@ func testInstruction() *kurtosis_core_rpc_api_bindings.StarlarkInstruction {
 			binding_constructors.NewStarlarkInstructionKwarg("serviceA", "kwarg1", true),
 			binding_constructors.NewStarlarkInstructionKwarg(`struct(bonjour=42, hello="world")`, "kwarg2", false),
 		},
-		isSkipped)
+		isSkipped,
+		"description")
 }
 
 func TestFormatInstruction_Executable(t *testing.T) {
@@ -74,7 +75,8 @@ func TestFormatInstruction_FormattingFail(t *testing.T) {
 		// This has issues with the quotes not being escaped
 		`print("UNSUPPORTED_TYPE['ModuleOutput(grafana_info=GrafanaInfo(dashboard_path="/d/QdTOwy-nz/eth2-merge-kurtosis-module-dashboard?orgId=1", user="admin", password="admin"))']")`,
 		[]*kurtosis_core_rpc_api_bindings.StarlarkInstructionArg{},
-		isSkipped)
+		isSkipped,
+		"description")
 	formattedInstruction := formatInstruction(instruction, run.Executable)
 	// failure to format -> the instruction is returned with no formatting applied
 	expectedResult := `# from dummyFile[12:4]

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

@@ -231,6 +231,10 @@ 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())
+}
+
 func validateAndConvertConfigAndReadyCondition(
 	serviceNetwork service_network.ServiceNetwork,
 	rawConfig starlark.Value,

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

@@ -353,6 +353,19 @@ func (builtin *AddServicesCapabilities) allServicesReadinessCheck(
 	return failedServiceChecksRegularMap
 }
 
+func (builtin *AddServicesCapabilities) Description() string {
+	return fmt.Sprintf("Adding '%v' services with names '%v'", len(builtin.serviceConfigs), getNamesAsCommaSeparatedList(builtin.serviceConfigs))
+}
+
+func getNamesAsCommaSeparatedList(serviceConfigs map[service.ServiceName]*service.ServiceConfig) string {
+	var serviceNames []string
+	serviceNameSeparator := ","
+	for serviceName := range serviceConfigs {
+		serviceNames = append(serviceNames, string(serviceName))
+	}
+	return strings.Join(serviceNames, serviceNameSeparator)
+}
+
 func (builtin *AddServicesCapabilities) runServiceReadinessCheck(
 	ctx context.Context,
 	wg *sync.WaitGroup,

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

@@ -189,6 +189,10 @@ func (builtin *ExecCapabilities) FillPersistableAttributes(builder *enclave_plan
 	builder.SetType(ExecBuiltinName)
 }
 
+func (builtin *ExecCapabilities) Description() string {
+	return fmt.Sprintf("Executing command on service '%v'", builtin.serviceName)
+}
+
 func (builtin *ExecCapabilities) isAcceptableCode(recipeResult map[string]starlark.Comparable) bool {
 	isAcceptableCode := false
 	for _, acceptableCode := range builtin.acceptableCodes {

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

@@ -99,3 +99,7 @@ func (builtin *PrintCapabilities) TryResolveWith(instructionsAreEqual bool, _ *e
 func (builtin *PrintCapabilities) FillPersistableAttributes(builder *enclave_plan_persistence.EnclavePlanInstructionBuilder) {
 	builder.SetType(PrintBuiltinName)
 }
+
+func (builtin *PrintCapabilities) Description() string {
+	return "Printing a message"
+}

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

@@ -101,3 +101,7 @@ func (builtin *RemoveServiceCapabilities) FillPersistableAttributes(builder *enc
 		builtin.serviceName,
 	)
 }
+
+func (builtin *RemoveServiceCapabilities) Description() string {
+	return fmt.Sprintf("Removing service '%v'", builtin.serviceName)
+}

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

@@ -168,6 +168,10 @@ 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)
+}
+
 func parseTemplatesAndData(templatesAndData *starlark.Dict) (map[string]*render_templates.TemplateData, *startosis_errors.InterpretationError) {
 	templateAndDataByDestRelFilepath := make(map[string]*render_templates.TemplateData)
 	for _, relPathInFilesArtifactKey := range templatesAndData.Keys() {

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

@@ -2,6 +2,7 @@ package request
 
 import (
 	"context"
+	"fmt"
 	"github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_interface/objects/service"
 	"github.com/kurtosis-tech/kurtosis/core/server/api_container/server/service_network"
 	"github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/enclave_plan_persistence"
@@ -201,6 +202,10 @@ func (builtin *RequestCapabilities) FillPersistableAttributes(builder *enclave_p
 	builder.SetType(RequestBuiltinName)
 }
 
+func (builtin *RequestCapabilities) Description() string {
+	return fmt.Sprintf("Running '%v' request on service '%v'", builtin.httpRequestRecipe.RequestType(), builtin.serviceName)
+}
+
 func (builtin *RequestCapabilities) isAcceptableCode(recipeResult map[string]starlark.Comparable) bool {
 	isAcceptableCode := false
 	for _, acceptableCode := range builtin.acceptableCodes {

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

@@ -97,3 +97,7 @@ func (builtin *StartServiceCapabilities) FillPersistableAttributes(builder *encl
 		builtin.serviceName,
 	)
 }
+
+func (builtin *StartServiceCapabilities) Description() string {
+	return fmt.Sprintf("Starting service '%v'", builtin.serviceName)
+}

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

@@ -97,3 +97,7 @@ func (builtin *StopServiceCapabilities) FillPersistableAttributes(builder *encla
 		builtin.serviceName,
 	)
 }
+
+func (builtin *StopServiceCapabilities) Description() string {
+	return fmt.Sprintf("Stopping service '%v'", builtin.serviceName)
+}

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

@@ -171,3 +171,7 @@ func (builtin *StoreServiceFilesCapabilities) FillPersistableAttributes(builder
 		builtin.artifactName, nil,
 	)
 }
+
+func (builtin *StoreServiceFilesCapabilities) Description() string {
+	return fmt.Sprintf("Storing files from service '%v' at path '%v' to files artifact with name '%v'", builtin.serviceName, builtin.src, builtin.artifactName)
+}

core/server/api_container/server/startosis_engine/kurtosis_instruction/tasks/run_python.go

@@ -321,6 +321,10 @@ func (builtin *RunPythonCapabilities) FillPersistableAttributes(builder *enclave
 	builder.SetType(RunPythonBuiltinName)
 }
 
+func (builtin *RunPythonCapabilities) Description() string {
+	return "Running a one time python script"
+}
+
 func setupRequiredPackages(ctx context.Context, builtin *RunPythonCapabilities) (*exec_result.ExecResult, error) {
 	if len(builtin.packages) == 0 {
 		return nil, nil

core/server/api_container/server/startosis_engine/kurtosis_instruction/tasks/run_sh.go

@@ -266,6 +266,10 @@ func (builtin *RunShCapabilities) FillPersistableAttributes(builder *enclave_pla
 	builder.SetType(RunShBuiltinName)
 }
 
+func (builtin *RunShCapabilities) Description() string {
+	return "Running a one time bash script"
+}
+
 func getCommandToRun(builtin *RunShCapabilities) (string, error) {
 	// replace future references to actual strings
 	maybeSubCommandWithRuntimeValues, err := magic_string_helper.ReplaceRuntimeValueInString(builtin.run, builtin.runtimeValueStore)

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

@@ -213,3 +213,7 @@ func (builtin *UploadFilesCapabilities) FillPersistableAttributes(builder *encla
 		builtin.artifactName, builtin.filesArtifactMd5,
 	)
 }
+
+func (builtin *UploadFilesCapabilities) Description() string {
+	return fmt.Sprintf("Uploading file '%v' to files articact '%v'", builtin.src, builtin.artifactName)
+}

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

@@ -155,6 +155,10 @@ func (builtin *VerifyCapabilities) FillPersistableAttributes(builder *enclave_pl
 	builder.SetType(VerifyBuiltinName)
 }
 
+func (builtin *VerifyCapabilities) Description() string {
+	return fmt.Sprintf("Verifying whether two values meet a certain condition '%v'", builtin.assertion)
+}
+
 // Verify verifies whether the currentValue matches the targetValue w.r.t. the assertion operator
 // TODO: This and ValidateVerificationToken below are used by both verify and wait. Refactor it to a better place
 func Verify(currentValue starlark.Comparable, assertion string, targetValue starlark.Comparable) error {

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

@@ -288,3 +288,7 @@ func (builtin *WaitCapabilities) TryResolveWith(instructionsAreEqual bool, _ *en
 func (builtin *WaitCapabilities) FillPersistableAttributes(builder *enclave_plan_persistence.EnclavePlanInstructionBuilder) {
 	builder.SetType(WaitBuiltinName)
 }
+
+func (builtin *WaitCapabilities) Description() string {
+	return fmt.Sprintf("Waiting for at most '%v' for service '%v' to reach a certain state", builtin.timeout, builtin.serviceName)
+}

core/server/api_container/server/startosis_engine/kurtosis_starlark_framework/kurtosis_plan_instruction/kurtosis_plan_instruction_capabilities.go

@@ -22,4 +22,7 @@ type KurtosisPlanInstructionCapabilities interface {
 	// FillPersistableAttributes adds to the builder the attributes of the instruction that needs to be persisted to the
 	// enclave database to power idempotent runs.
 	FillPersistableAttributes(builder *enclave_plan_persistence.EnclavePlanInstructionBuilder)
+
+	// Description Brief description of the instruction based on its contents
+	Description() string
 }

core/server/api_container/server/startosis_engine/kurtosis_starlark_framework/kurtosis_plan_instruction/kurtosis_plan_instruction_internal.go

@@ -46,7 +46,7 @@ func (builtin *kurtosisPlanInstructionInternal) GetCanonicalInstruction(isSkippe
 		}
 		args[idx] = binding_constructors.NewStarlarkInstructionKwarg(builtin_argument.StringifyArgumentValue(value), name, shouldBeDisplayed)
 	}
-	return binding_constructors.NewStarlarkInstruction(builtin.GetPosition().ToAPIType(), builtin.GetName(), builtin.String(), args, isSkipped)
+	return binding_constructors.NewStarlarkInstruction(builtin.GetPosition().ToAPIType(), builtin.GetName(), builtin.String(), args, isSkipped, builtin.capabilities.Description())
 }
 
 // GetPositionInOriginalScript is here to implement the KurtosisInstruction interface. Remove it when it's not needed anymore