markdown_exec 3.5.2 → 3.6.0

data/lib/hash_delegator.rb

@@ -217,7 +217,7 @@ module HashDelegatorSelf
   #
   # @example Basic execution without export
   #   result, exportable, new_lines = execute_bash_script_lines(
-  #     code_lines: ["echo 'Hello'", "echo 'World'"],
+  #     transient_code: ["echo 'Hello'", "echo 'World'"],
   #     export: nil,
   #     force: false
   #   )
@@ -226,14 +226,14 @@ module HashDelegatorSelf
   # @example Execution with export
   #   export = OpenStruct.new(name: "MY_VAR", exportable: true)
   #   result, exportable, new_lines = execute_bash_script_lines(
-  #     code_lines: ["echo 'Hello World'"],
+  #     transient_code: ["echo 'Hello World'"],
   #     export: export,
   #     force: true
   #   )
   #   # => [CommandResult, true, [{name: "MY_VAR", force: true, text: "Hello World\n"}]]
   #
   def execute_bash_script_lines(
-    code_lines: [],
+    transient_code: [],
     export: nil,
     export_name:,
     force: false,
@@ -243,7 +243,7 @@ module HashDelegatorSelf
     archive_time_format: nil # @delegate_object[:archive_time_format]
   )
     Tempfile.create('script_exec') do |temp_file|
-      temp_file.write(join_code_lines(code_lines))
+      temp_file.write(join_code_lines(transient_code))
       temp_file.close # Close the file before chmod and execution
       File.chmod(0o755, temp_file.path)
 
@@ -282,20 +282,20 @@ module HashDelegatorSelf
         exit_status: tsc.exit_code,
         exportable: exportable_success,
         new_lines: new_lines,
-        script: code_lines,
+        script: transient_code,
         stdout: tsc.transformed_output,
         transformed_shell_command: tsc
       )
     end
   rescue StandardError
-    wwe $!, 'code_lines:', code_lines, 'export:', export
+    wwe $!, 'transient_code:', transient_code, 'export:', export
     # warn "Error executing script: #{err.message}"
     # return failure result
     CommandResult.new(
       exit_status: CommandResult::EXIT_STATUS_FAIL,
       exportable: false,
       new_lines: [],
-      script: code_lines,
+      script: transient_code,
       stdout: ''
     )
   end
@@ -781,7 +781,7 @@ module MarkdownExec
 
       @process_mutex = Mutex.new
       @process_cv = ConditionVariable.new
-      @dml_link_state = Struct.new(:document_filename, :inherited_lines)
+      @dml_link_state = Struct.new(:document_filename, :context_code)
                               .new(@delegate_object[:filename], [])
       @dml_menu_blocks = []
       @fcb_store = [] # all fcbs created
@@ -850,7 +850,7 @@ module MarkdownExec
       add_inherited_lines(
         link_state: link_state,
         menu_blocks: menu_blocks
-      ) if @delegate_object[:menu_with_inherited_lines]
+      ) if @delegate_object[:menu_with_context_code]
 
       # back before exit
       add_back_option(
@@ -969,10 +969,10 @@ module MarkdownExec
     # @param menu_blocks [Array] The array of menu block elements.
     # @param position [Symbol] The position to insert the divider (:initial or :final).
     def append_inherited_lines(link_state:, menu_blocks:, position: top)
-      return unless link_state.inherited_lines_present?
+      return unless link_state.context_code_present?
 
       insert_at_top = @delegate_object[:menu_inherited_lines_at_top]
-      chrome_blocks = link_state.inherited_lines_map do |line|
+      chrome_blocks = link_state.context_code_map do |line|
         formatted = format(@delegate_object[:menu_inherited_lines_format],
                            { line: line })
         persist_fcb(
@@ -1190,7 +1190,7 @@ module MarkdownExec
       occurrence_expressions: nil
     )
       evaluate_shell_expressions(
-        (link_state&.inherited_lines_block || ''),
+        (link_state&.context_code_block || ''),
         commands,
         initial_code_required: initial_code_required,
         occurrence_expressions: occurrence_expressions
@@ -1209,7 +1209,7 @@ module MarkdownExec
           exts: '.out.txt',
           saved_asset_format:
             shell_escape_asset_format(
-              code_lines: @dml_link_state.inherited_lines,
+              transient_code: @dml_link_state.context_code,
               shell: ShellType::BASH
             )
         ).generate_name
@@ -1264,8 +1264,8 @@ module MarkdownExec
     end
 
     # return code resulting from evaluating all automatic blocks in order
-    def code_from_auto_blocks(
-      all_blocks, mdoc: nil, default_only: true, inherited_lines: []
+    def inherited_lines_from_auto_blocks(
+      all_blocks, mdoc: nil, default_only: true, context_code: []
     )
       shell_block_name = @delegate_object[:document_load_shell_block_name]
       vars_block_name = @delegate_object[:document_load_vars_block_name]
@@ -1287,18 +1287,18 @@ module MarkdownExec
           if read_shell
             # collect code from shell block
             code = if mdoc
-                     reqinfo = mdoc.collect_recursively_required_code(
+                     required_code = mdoc.collect_recursively_required_code(
                        anyname: fcb.id,
                        label_format_above:
                          @delegate_object[:shell_code_label_format_above],
                        label_format_below:
                          @delegate_object[:shell_code_label_format_below],
                        block_source: block_source,
-                       inherited_lines: inherited_lines
+                       context_code: context_code
                      )
-                     block_inherit = reqinfo[:inherit]
+                     block_inherit = required_code[:context_code]
 
-                     reqinfo[:code]
+                     required_code[:transient_code]
                    else
                      fcb.body
                    end
@@ -1339,48 +1339,11 @@ module MarkdownExec
         all_inherit += block_inherit
       end
 
-      [all_code, all_inherit].tap { wwr _1 }
+      all_code.tap { wwr _1 }
     rescue StandardError
       wwe $!, 'all_blocks.count:', all_blocks.count
     end
 
-    # return code resulting from evaluating all UX blocks in order
-    def code_from_auto_ux_blocks(
-      all_blocks,
-      mdoc
-    )
-      # do not reload the most recent filename
-      unless @ux_most_recent_filename != @delegate_object[:filename]
-        return
-      end
-
-      @ux_most_recent_filename = @delegate_object[:filename]
-
-      # select all UX blocks, rejecting non-primary split
-      blocks = select_automatic_ux_blocks(
-        all_blocks.reject(&:is_split_rest?)
-      )
-      return if blocks.empty?
-
-      # collect code from all ux blocks
-      (blocks.each.with_object([]) do |block, merged_options|
-        command_result_w_e_t_nl =
-          code_from_ux_block_to_set_environment_variables(
-            block,
-            mdoc,
-            force: @delegate_object[:ux_auto_load_force_default],
-            only_default: true,
-            silent: true
-          )
-        if command_result_w_e_t_nl.failure?
-          # if a block fails, proceed with next block
-          merged_options
-        else
-          merged_options.push(command_result_w_e_t_nl.new_lines)
-        end
-      end).to_a
-    end
-
     # return code resulting from evaluating all automatic VARS blocks in order
     def code_from_auto_vars_blocks(
       all_blocks,
@@ -1415,91 +1378,97 @@ module MarkdownExec
     # set ENV value for the variable and return code lines for the same
     # for BlockType::UX
     def code_from_ux_block_to_set_environment_variables(
-      selected, mdoc, inherited_code: nil, force: true, only_default: false,
-      required: nil, silent:
+      selected, mdoc, context_code: nil, force: true, only_default: false,
+      required: OpenStruct.new(context_code: [], transient_code: []),
+      silent:
     )
       wwt :fcb, 'selected:', selected
-      wwt :inherited_code, inherited_code
+      wwt :context_code, context_code
       ret_command_result = nil
       exit_prompt = @delegate_object[:prompt_filespec_back]
 
-      required ||= mdoc.collect_recursively_required_code(
+      wwt :required, required
+      required_code = mdoc&.collect_recursively_required_code(
         anyname: selected_id_name(selected),
         label_format_above: @delegate_object[:shell_code_label_format_above],
         label_format_below: @delegate_object[:shell_code_label_format_below],
         block_source: block_source,
-        inherited_lines: inherited_code
+        context_code: context_code
       )
-      wwt :required, required
+      wwt :required_code, required_code
       # new_inherited_lines = []
 
       # process each ux block in sequence, setting ENV and collecting lines
       concatenated_code_from_required_blocks = []
-      required[:blocks]&.each do |block|
-        next if block.type != BlockType::UX
-
-        wwt :fcb, 'a required block', block
-
-        body1 = block.raw_body || block.body
-        case data = safe_yaml_load(body1.join("\n"))
-        when Hash
-          export = parse_yaml_of_ux_block(
-            data,
-            prompt: @delegate_object[:prompt_ux_enter_a_value],
-            validate: '^(?<name>[^ ].*)$'
-          )
-          block.export = export
-          block.export_act = FCB.act_source(export)
-          block.export_init = FCB.init_source(export)
-
-          # required are variable names that must be set before the UX block is executed.
-          # if any precondition is not set, the sequence is aborted.
-          required_variables = []
-          export.required&.each do |precondition|
-            required_variables.push "[[ -z $#{precondition} ]] && exit #{CommandResult::EXIT_STATUS_REQUIRED_EMPTY}"
-          end
-          wwt :required_variables, 'required_variables',
-              required_variables
-
-          eval_code = join_array_of_arrays(
-            inherited_code, # inherited code
-            concatenated_code_from_required_blocks, # current block requirements
-            required_variables, # test conditions
-            required[:code] # required by selected
-          )
-          wwt :eval_code, 'eval_code:', eval_code
-          if only_default
-            command_result_w_e_t_nl =
-              ux_block_export_automatic(eval_code, export)
-            # do not display warnings on initializing call
-            return command_result_w_e_t_nl if command_result_w_e_t_nl.failure?
+      if required_code # exclude for tests
+        required_code[:blocks]&.each do |block|
+          next if block.type != BlockType::UX
+
+          wwt :fcb, 'a required block', block
+
+          body1 = block.raw_body || block.body
+          case data = safe_yaml_load(body1.join("\n"))
+          when Hash
+            export = parse_yaml_of_ux_block(
+              data,
+              prompt: @delegate_object[:prompt_ux_enter_a_value],
+              validate: '^(?<name>[^ ].*)$'
+            )
+            block.export = export
+            block.export_act = FCB.act_source(export)
+            block.export_init = FCB.init_source(export)
+
+            # required_code are variable names that must be set before the UX block is executed.
+            # if any precondition is not set, the sequence is aborted.
+            required_variables = []
+            export.required&.each do |precondition|
+              required_variables.push "[[ -z $#{precondition} ]] && exit #{CommandResult::EXIT_STATUS_REQUIRED_EMPTY}"
+            end
+            wwt :required_variables, 'required_variables',
+                required_variables
+
+            eval_code = join_array_of_arrays(
+              required[:context_code],
+              context_code, # inherited code
+              concatenated_code_from_required_blocks, # current block requirements
+              required_variables, # test conditions
+              required[:transient_code],
+              required_code[:transient_code] # required by selected
+            )
+            wwt :eval_code, 'eval_code:', eval_code
+            if only_default
+              command_result_w_e_t_nl =
+                ux_block_export_automatic(eval_code, export)
+              # do not display warnings on initializing call
+              return command_result_w_e_t_nl if command_result_w_e_t_nl.failure?
 
-          else
-            command_result_w_e_t_nl =
-              ux_block_export_activated(eval_code, export, exit_prompt)
-            if command_result_w_e_t_nl.failure?
-              if command_result_w_e_t_nl.warning&.present? && !silent
-                warn command_result_w_e_t_nl.warning
+            else
+              command_result_w_e_t_nl =
+                ux_block_export_activated(eval_code, export, exit_prompt)
+              if command_result_w_e_t_nl.failure?
+                if command_result_w_e_t_nl.warning&.present? && !silent
+                  warn command_result_w_e_t_nl.warning
+                end
+                return command_result_w_e_t_nl
               end
-              return command_result_w_e_t_nl
             end
-          end
-          return command_result_w_e_t_nl if command_result_w_e_t_nl.failure?
+            return command_result_w_e_t_nl if command_result_w_e_t_nl.failure?
 
-          # update the required lines for this and subsequent blocks
-          command_result_w_e_t_nl.new_lines =
-            process_command_result_lines(command_result_w_e_t_nl, export,
-                                         concatenated_code_from_required_blocks)
-          concatenated_code_from_required_blocks.concat(command_result_w_e_t_nl.new_lines)
+            # update the required lines for this and subsequent blocks
+            command_result_w_e_t_nl.new_lines =
+              process_command_result_lines(command_result_w_e_t_nl, export,
+                                           concatenated_code_from_required_blocks)
+            concatenated_code_from_required_blocks.concat(command_result_w_e_t_nl.new_lines)
 
-          concatenated_code_from_required_blocks = annotate_required_lines(
-            'blk:UX', concatenated_code_from_required_blocks, block_name: selected.id
-          )
+            concatenated_code_from_required_blocks = annotate_required_lines(
+              'blk:UX', concatenated_code_from_required_blocks, block_name: selected.id
+            )
 
-          command_result_w_e_t_nl.new_lines = concatenated_code_from_required_blocks
-          ret_command_result = command_result_w_e_t_nl
-        else
-          raise "Invalid data type: #{data.inspect}"
+            command_result_w_e_t_nl.new_lines = concatenated_code_from_required_blocks
+            ret_command_result = command_result_w_e_t_nl
+          else
+            raise "Invalid data type: #{data.inspect}"
+          end
         end
       end
       wwt :concatenated_code_from_required_blocks,
@@ -1513,19 +1482,19 @@ module MarkdownExec
         wwt :cr, ret, caller.deref
       end
     rescue StandardError
-      wwe $!, 'selected:', selected, 'required:', required, 'block:', block,
+      wwe $!, 'selected:', selected, 'required_code:', required_code, 'block:', block,
           'data:', data
     end
 
     # def
     # sets ENV
     def code_from_vars_block_to_set_environment_variables(selected)
-      code_lines = []
+      transient_code = []
       case data = YAML.load(selected.body.join("\n"))
       when Hash
         data.each do |key, value|
           EnvInterface.set(key, value.to_s)
-          code_lines << assign_key_value_in_bash(key, value)
+          transient_code << assign_key_value_in_bash(key, value)
 
           next unless @delegate_object[:menu_vars_set_format].present?
 
@@ -1537,10 +1506,10 @@ module MarkdownExec
           print string_send_color(formatted_string, :menu_vars_set_color)
         end
       end
-      annotate_required_lines('blk:VARS', code_lines, block_name: selected.id)
+      annotate_required_lines('blk:VARS', transient_code, block_name: selected.id)
     rescue StandardError
       wwe 'selected:', selected, 'data:', data, 'key:', key, 'value:', value,
-          'code_lines:', code_lines, 'formatted_string:', formatted_string
+          'transient_code:', transient_code, 'formatted_string:', formatted_string
     end
 
     # make a single line of shell code to assign an escaped value to a variable
@@ -1597,7 +1566,8 @@ module MarkdownExec
       else
         @run_state.in_own_window = false
         command_execute_in_process(
-          args: args, command: command,
+          args: args,
+          command: command,
           erls: erls,
           filename: @delegate_object[:filename],
           shell: shell
@@ -1679,8 +1649,7 @@ module MarkdownExec
     #  containing code blocks.
     # @param selected [Hash] The selected item from the menu
     #  to be executed.
-    # @return [LoadFileLinkState] An object indicating whether to load
-    #  the next block or reuse the current one.
+    # @return [Array] context_code
     def compile_execute_and_trigger_reuse(
       mdoc:, selected:, block_source:, link_state:
     )
@@ -1697,18 +1666,18 @@ module MarkdownExec
                    end
                  end
 
-      required_lines = execute_block_type_port_code_lines(
+      required_code = execute_block_type_port_code_lines(
         mdoc: mdoc, selected: selected,
         link_state: link_state, block_source: block_source
       )
       output_or_approval = @delegate_object[:output_script] ||
                            @delegate_object[:user_must_approve]
       if output_or_approval
-        display_required_code(required_lines: required_lines)
+        display_required_code(required_lines: required_code[:transient_code])
       end
       allow_execution = if @delegate_object[:user_must_approve]
                           prompt_for_user_approval(
-                            required_lines: required_lines,
+                            required_lines: required_code[:transient_code],
                             selected: selected
                           )
                         else
@@ -1716,16 +1685,28 @@ module MarkdownExec
                         end
 
       if allow_execution
+        script_lines = ( #HashDelegator.join_code_lines(
+          # ['# prior context'] +
+          (link_state&.context_code || []) +
+          # ['# new context'] +
+          required_code[:context_code] +
+          # ['# new transient'] +
+          required_code[:transient_code]
+        )
         execute_required_lines(
           blockname: selected_id_name(selected),
           erls: { play_bin: play_bin,
                   shell: selected_shell(selected.shell) },
-          required_lines: required_lines,
+          script_lines: script_lines,
           shell: selected_shell(selected.shell)
         )
       end
 
       link_state.block_name = nil
+
+      required_code[:context_code]
+    rescue StandardError
+      wwe $!
     end
 
     # Check if the expression contains wildcard characters
@@ -2036,6 +2017,8 @@ module MarkdownExec
       # filter block if selected in menu
       return true if @run_state.source.block_name_from_cli
 
+      return true if @delegate_object[:block_name].empty?
+
       # return false if @prior_execution_block == @delegate_object[:block_name]
       if @prior_execution_block == @delegate_object[:block_name]
         return @allowed_execution_block == @prior_execution_block ||
@@ -2212,10 +2195,10 @@ module MarkdownExec
         warn format_and_highlight_lines(link_state.inherited_dependencies,
                                         label: 'inherited_dependencies')
       end
-      return unless @delegate_object[:dump_inherited_lines]
+      return unless @delegate_object[:dump_context_code]
 
-      warn format_and_highlight_lines(link_state.inherited_lines,
-                                      label: 'inherited_lines')
+      warn format_and_highlight_lines(link_state.context_code,
+                                      label: 'context_code')
     end
 
     # Opens text in an editor for user modification and
@@ -2301,7 +2284,7 @@ module MarkdownExec
         vux_edit_inherited
         return :break if pause_user_exit
 
-        next_state_append_code(selected, link_state, [])
+        next_state_append_code(selected, link_state, context_code: [])
 
       elsif selected.type == BlockType::HISTORY
         debounce_reset
@@ -2314,23 +2297,25 @@ module MarkdownExec
 
       elsif selected.type == BlockType::LINK
         debounce_reset
-        execute_block_type_link_with_state(link_block_body: selected.body,
-                                           mdoc: mdoc,
-                                           selected: selected,
-                                           link_state: link_state,
-                                           block_source: block_source)
+        execute_block_type_link_with_state(
+          link_block_body: selected.body,
+          mdoc: mdoc,
+          selected: selected,
+          link_state: link_state,
+          block_source: block_source
+        )
 
       elsif selected.type == BlockType::LOAD
         debounce_reset
         load_result = execute_block_type_load_code_lines(selected)
-        next_state_append_code(selected, link_state, load_result.code,
-                               mode: load_result.mode)
+        next_state_append_code(selected, link_state, context_code: load_result.code,
+                                                     mode: load_result.mode)
 
       elsif selected.type == BlockType::SAVE
         debounce_reset
 
         execute_block_type_save(
-          code_lines: link_state&.inherited_lines,
+          transient_code: link_state&.context_code,
           selected: selected
         )
 
@@ -2352,7 +2337,7 @@ module MarkdownExec
 
       elsif selected.type == BlockType::OPTS
         debounce_reset
-        code_lines = []
+        transient_code = []
         options_state = read_show_options_and_trigger_reuse(
           link_state: link_state,
           mdoc: @dml_mdoc,
@@ -2361,7 +2346,7 @@ module MarkdownExec
         update_menu_base(options_state.options)
 
         link_state = LinkState.new
-        next_state_append_code(selected, link_state, code_lines)
+        next_state_append_code(selected, link_state, context_code: transient_code)
 
       elsif selected.type == BlockType::PORT
         debounce_reset
@@ -2370,22 +2355,22 @@ module MarkdownExec
           selected: selected,
           link_state: link_state,
           block_source: block_source
-        )
-        next_state_append_code(selected, link_state, required_lines)
+        )[:context_code]
+        next_state_append_code(selected, link_state, context_code: required_lines)
 
       elsif selected.type == BlockType::UX
         debounce_reset
         command_result_w_e_t_nl = code_from_ux_block_to_set_environment_variables(
           selected,
           @dml_mdoc,
-          inherited_code: @dml_link_state.inherited_lines,
+          context_code: @dml_link_state.context_code,
           only_default: false,
           silent: true
         )
         next_state_append_code(
           selected,
           link_state,
-          command_result_w_e_t_nl.failure? ? [] : command_result_w_e_t_nl.new_lines
+          context_code: command_result_w_e_t_nl.failure? ? [] : command_result_w_e_t_nl.new_lines
         )
 
       elsif selected.type == BlockType::VARS
@@ -2393,7 +2378,7 @@ module MarkdownExec
         next_state_append_code(
           selected,
           link_state,
-          code_from_vars_block_to_set_environment_variables(selected)
+          context_code: code_from_vars_block_to_set_environment_variables(selected)
         )
 
       elsif COLLAPSIBLE_TYPES.include?(selected.type)
@@ -2403,11 +2388,13 @@ module MarkdownExec
 
       elsif debounce_allows
         # SHELL type
-        compile_execute_and_trigger_reuse(mdoc: mdoc,
-                                          selected: selected,
-                                          link_state: link_state,
-                                          block_source: block_source)
-        LoadFileLinkState.new(LoadFile::REUSE, link_state)
+        context_code = compile_execute_and_trigger_reuse(
+          mdoc: mdoc,
+          selected: selected,
+          link_state: link_state,
+          block_source: block_source
+        )
+        next_state_set_code(selected, link_state, context_code)
 
       else
         LoadFileLinkState.new(LoadFile::REUSE, link_state)
@@ -2501,30 +2488,31 @@ module MarkdownExec
       ## collect blocks specified by block
       #
       if mdoc
-        code_info = mdoc.collect_recursively_required_code(
+        required_code = mdoc.collect_recursively_required_code(
           anyname: selected_id_name(selected),
           block_source: block_source,
           label_format_above: @delegate_object[:shell_code_label_format_above],
           label_format_below: @delegate_object[:shell_code_label_format_below],
-          inherited_lines: link_state&.inherited_lines || []
+          context_code: link_state&.context_code || []
         )
-        code_lines = annotate_required_lines(
-          'blk:LINK', code_info[:code], block_name: selected.id
+
+        context_code = annotate_required_lines(
+          'blk:LINK', required_code[:context_code], block_name: selected.id
         )
-        block_names = code_info[:block_names]
-        dependencies = code_info[:dependencies]
+        block_names = required_code[:block_names]
+        dependencies = required_code[:dependencies]
       else
         block_names = []
-        code_lines = []
+        context_code = []
         dependencies = {}
       end
 
       # load key and values from link block into current environment
       #
       if link_block_data[LinkKeys::VARS]
-        code_lines << BashCommentFormatter.format_comment(selected.pub_name)
+        context_code << BashCommentFormatter.format_comment(selected.pub_name)
         link_block_data[LinkKeys::VARS].each do |key, value|
-          code_lines << assign_key_value_in_bash(key, value)
+          context_code << assign_key_value_in_bash(key, value)
           EnvInterface.set(key, value.to_s)
         end
       end
@@ -2535,20 +2523,20 @@ module MarkdownExec
         load_filespec = load_filespec_from_expression(load_expr)
         if load_filespec
           begin
-            code_lines += File.readlines(load_filespec,
-                                         chomp: true)
+            context_code += File.readlines(load_filespec,
+                                           chomp: true)
           rescue Errno::ENOENT
             report_error($ERROR_INFO)
           end
         end
       end
 
-      # if an eval link block, evaluate code_lines and return its standard output
+      # if an eval link block, evaluate context_code and return its standard output
       #
       if link_block_data.fetch(LinkKeys::EVAL, false) ||
          link_block_data.fetch(LinkKeys::EXEC, false)
-        code_lines = link_block_data_eval(
-          link_state, code_lines, selected, link_block_data,
+        context_code = link_block_data_eval(
+          link_state, context_code, selected, link_block_data,
           block_source: block_source,
           shell: @delegate_object[:block_type_default]
         )
@@ -2563,13 +2551,16 @@ module MarkdownExec
         nil
       ) || link_block_data.fetch(LinkKeys::BLOCK, nil) || ''
 
-      code_lines = annotate_required_lines(
-        'blk:LINK', code_lines, block_name: selected.id
+      context_code = annotate_required_lines(
+        'blk:LINK', context_code, block_name: selected.id
+      )
+      context_code = annotate_required_lines(
+        'blk:LINK', context_code, block_name: selected.id
       )
 
       if link_block_data[LinkKeys::RETURN]
         pop_add_current_code_to_head_and_trigger_load(
-          link_state, block_names, code_lines,
+          link_state, block_names, context_code,
           dependencies, selected, next_block_name: next_block_name
         )
 
@@ -2582,8 +2573,8 @@ module MarkdownExec
             ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
           inherited_dependencies:
             (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
-          inherited_lines: HashDelegator.flatten_and_compact_arrays(
-            link_state&.inherited_lines, code_lines
+          context_code: HashDelegator.flatten_and_compact_arrays(
+            link_state&.context_code, context_code
           ),
           keep_code: link_state&.keep_code,
           next_block_name: next_block_name,
@@ -2680,32 +2671,34 @@ module MarkdownExec
     #
     # @param mdoc [YourMDocClass] An instance of the MDoc class.
     # @param selected [Hash] The selected block.
-    # @return [Array<String>] Required code blocks as an array of lines.
+    # @return [OpenStruct] context and transient code
     def execute_block_type_port_code_lines(mdoc:, selected:, block_source:,
                                            link_state: LinkState.new)
-      required = mdoc.collect_recursively_required_code(
+      required_code = mdoc.collect_recursively_required_code(
         anyname: selected_id_name(selected),
         label_format_above: @delegate_object[:shell_code_label_format_above],
         label_format_below: @delegate_object[:shell_code_label_format_below],
         block_source: block_source,
-        inherited_lines: link_state&.inherited_lines || []
-      ) # !!t 'required'
+        context_code: link_state&.context_code || []
+      ) # !!t 'required_code'
       dependencies = (
         link_state&.inherited_dependencies || {}
-      ).merge(required[:dependencies] || {})
-      required[:unmet_dependencies] = (
-        required[:unmet_dependencies] || []
+      ).merge(required_code[:dependencies] || {})
+
+      required_code[:unmet_dependencies] = (
+        required_code[:unmet_dependencies] || []
       ) - (link_state&.inherited_block_names || [])
-      if required[:unmet_dependencies].present?
+
+      if required_code[:unmet_dependencies].present?
         ### filter against link_state.inherited_block_names
 
         warn format_and_highlight_dependencies(
-          dependencies, highlight: required[:unmet_dependencies]
+          dependencies, highlight: required_code[:unmet_dependencies]
         )
         runtime_exception(
           :runtime_exception_error_level,
           'unmet_dependencies, flag: runtime_exception_error_level',
-          required[:unmet_dependencies]
+          required_code[:unmet_dependencies]
         )
       elsif @delegate_object[:dump_dependencies]
         warn format_and_highlight_dependencies(
@@ -2716,8 +2709,11 @@ module MarkdownExec
 
       if selected[:type] == BlockType::OPTS
         # body of blocks is returned as a list of lines to be read an YAML
-        HashDelegator.flatten_and_compact_arrays(
-          required[:blocks].map(&:body).flatten(1)
+        OpenStruct.new(
+          context_code: HashDelegator.flatten_and_compact_arrays(
+            required_code[:blocks].map(&:body).flatten(1)
+          ),
+          transient_code: []
         )
       else
         # code from the selected VARS block
@@ -2727,31 +2723,41 @@ module MarkdownExec
                       []
                     end
 
-        # activate UX blocks in the required list
+        # activate UX blocks in the required_code list
         command_result_w_e_t_nl = code_from_ux_block_to_set_environment_variables(
           selected,
           @dml_mdoc,
-          inherited_code: vars_code,
+          context_code: required_code[:context_code] + required_code[:transient_code],
           only_default: false,
-          required: required,
+          required:
+            OpenStruct.new(context_code: [], transient_code: vars_code),
           silent: false
         )
         ux_code = command_result_w_e_t_nl.failure? ? [] : command_result_w_e_t_nl.new_lines
 
-        HashDelegator.flatten_and_compact_arrays(
-          link_state&.inherited_lines,
-          annotate_required_lines(
-            'blk:PORT',
-            required[:code] + vars_code + ux_code,
-            block_name: selected.id
+        OpenStruct.new(
+          context_code: HashDelegator.flatten_and_compact_arrays(
+            link_state&.context_code,
+            annotate_required_lines(
+              'blk:PORT',
+              (required_code[:context_code] || []) + vars_code + ux_code,
+              block_name: selected.id
+            )
+          ),
+          transient_code: HashDelegator.flatten_and_compact_arrays(
+            annotate_required_lines(
+              'blk:PORT',
+              required_code[:transient_code],
+              block_name: selected.id
+            )
           )
         )
       end
     rescue StandardError
-      wwe(required[:code], ux_code, { error: $!, callback: $@[0] })
+      wwe(required_code, ux_code, { error: $!, callback: $@[0] })
     end
 
-    def execute_block_type_save(code_lines:, selected:)
+    def execute_block_type_save(transient_code:, selected:)
       block_data = HashDelegator.parse_yaml_data_from_body(selected.body)
       directory_glob = if block_data['directory']
                          File.join(
@@ -2772,7 +2778,7 @@ module MarkdownExec
             end
 
             File.write(save_filespec,
-                       HashDelegator.join_code_lines(code_lines))
+                       HashDelegator.join_code_lines(transient_code))
           rescue Errno::ENOENT
             report_error($ERROR_INFO)
           end
@@ -2867,14 +2873,14 @@ module MarkdownExec
     end
 
     def execute_inherited_save(
-      code_lines: @dml_link_state.inherited_lines
+      transient_code: @dml_link_state.context_code
     )
       return unless (save_filespec = save_filespec_from_expression(
         document_name_in_glob_as_file_name
       ))
 
       unless write_file_with_directory_creation(
-        content: HashDelegator.join_code_lines(code_lines),
+        content: HashDelegator.join_code_lines(transient_code),
         filespec: save_filespec
       )
         :break
@@ -2885,14 +2891,14 @@ module MarkdownExec
       @menu_user_clicked_back_link = true
 
       keep_code = @dml_link_state.keep_code
-      inherited_lines = keep_code ? @dml_link_state.inherited_lines_block : nil
+      context_code = keep_code ? @dml_link_state.context_code_block : nil
 
       @dml_link_state = pop_link_history_new_state
 
       {
         block_name: @dml_link_state.block_name,
         document_filename: @dml_link_state.document_filename,
-        inherited_lines: inherited_lines,
+        context_code: context_code,
         keep_code: keep_code
       }
     end
@@ -2908,23 +2914,25 @@ module MarkdownExec
     def execute_required_lines(
       blockname: '',
       erls: {},
-      required_lines: [],
+      script_lines: [],
       shell:
     )
       if @delegate_object[:save_executed_script]
         write_command_file(blockname: blockname,
-                           required_lines: required_lines,
+                           required_lines: script_lines,
                            shell: selected_shell(shell))
       end
       if @dml_block_state
         calc_logged_stdout_filename(block_name: @dml_block_state.block.oname)
       end
       format_and_execute_command(
-        code_lines: required_lines,
+        script_lines: script_lines,
         erls: erls,
         shell: selected_shell(shell)
       )
       post_execution_process
+    rescue StandardError
+      wwe $!
     end
 
     def expand_blocks_with_replacements(
@@ -3039,7 +3047,7 @@ module MarkdownExec
       case export_string
       when String, Integer, Float, TrueClass, FalseClass
         command_result = HashDelegator.execute_bash_script_lines(
-          code_lines: join_array_of_arrays(
+          transient_code: join_array_of_arrays(
             bash_script_lines,
             printf_expand ? expander.call(export_string) : [export_string]
           ),
@@ -3080,7 +3088,7 @@ module MarkdownExec
         # each item in the hash is a variable name and value
         export_string.each do |name, expression|
           command_result = HashDelegator.execute_bash_script_lines(
-            code_lines: join_array_of_arrays(
+            transient_code: join_array_of_arrays(
               bash_script_lines,
               required_lines,
               printf_expand ? expander.call(expression) : [expression]
@@ -3211,11 +3219,11 @@ module MarkdownExec
     end
 
     def format_and_execute_command(
-      code_lines:,
+      script_lines:,
       erls:,
       shell:
     )
-      formatted_command = code_lines.flatten.join("\n")
+      formatted_command = script_lines.flatten.join("\n")
       @fout.fout fetch_color(data_sym: :script_execution_head,
                              color_sym: :script_execution_frame_color)
 
@@ -3484,7 +3492,7 @@ module MarkdownExec
         wwt :iterlines, 'nested_line:', nested_line
         update_line_and_block_state(
           nested_line, state, selected_types,
-          source_id: "ItrBlkFrmNstFls:#{index}¤#{nested_line.filename}:#{nested_line.index}",
+          source_id: "IBNF:#{index}¤#{nested_line.filename}:#{nested_line.index}",
           &block
         )
 
@@ -3524,10 +3532,10 @@ module MarkdownExec
       end.compact.flatten(1)
     end
 
-    def link_block_data_eval(link_state, code_lines, selected, link_block_data,
+    def link_block_data_eval(link_state, transient_code, selected, link_block_data,
                              block_source:, shell:)
       all_code = HashDelegator.flatten_and_compact_arrays(
-        link_state&.inherited_lines, code_lines
+        link_state&.context_code, transient_code
       )
       output_lines = []
 
@@ -3546,34 +3554,34 @@ module MarkdownExec
             output_lines.push(line) if line
           end
 
-          if link_block_data.fetch(LinkKeys::EVAL, true)
-            # eval: true
-
-            ## select output_lines that look like assignment or match other specs
-            #
-            output_lines = process_string_array(
-              output_lines,
-              begin_pattern: @delegate_object.fetch(:output_assignment_begin,
-                                                    nil),
-              end_pattern: @delegate_object.fetch(:output_assignment_end, nil),
-              scan1: @delegate_object.fetch(:output_assignment_match, nil),
-              format1: @delegate_object.fetch(:output_assignment_format, nil),
-              name: ''
-            )
+          output_lines = if link_block_data.fetch(LinkKeys::EVAL, true)
+                           # eval: true
+
+                           ## select output_lines that look like assignment or match other specs
+                           #
+                           process_string_array(
+                             output_lines,
+                             begin_pattern: @delegate_object.fetch(:output_assignment_begin,
+                                                                   nil),
+                             end_pattern: @delegate_object.fetch(:output_assignment_end, nil),
+                             scan1: @delegate_object.fetch(:output_assignment_match, nil),
+                             format1: @delegate_object.fetch(:output_assignment_format, nil),
+                             name: ''
+                           )
 
-          else
-            # eval: false
-
-            ## select all output_lines
-            #
-            output_lines = process_string_array(
-              output_lines,
-              begin_pattern: @delegate_object.fetch(:output_assignment_begin,
-                                                    nil),
-              end_pattern: @delegate_object.fetch(:output_assignment_end, nil),
-              name: ''
-            )
-          end
+                         else
+                           # eval: false
+
+                           ## select all output_lines
+                           #
+                           process_string_array(
+                             output_lines,
+                             begin_pattern: @delegate_object.fetch(:output_assignment_begin,
+                                                                   nil),
+                             end_pattern: @delegate_object.fetch(:output_assignment_end, nil),
+                             name: ''
+                           )
+                         end
         else
           output_lines = `bash #{file.path}`.split("\n")
         end
@@ -3620,7 +3628,7 @@ module MarkdownExec
 
     def link_history_push_and_next(
       curr_block_name:, curr_document_filename:,
-      inherited_block_names:, inherited_dependencies:, inherited_lines:,
+      inherited_block_names:, inherited_dependencies:, context_code:,
       keep_code:,
       next_block_name:, next_document_filename:,
       next_keep_code:,
@@ -3632,7 +3640,7 @@ module MarkdownExec
           document_filename: curr_document_filename,
           inherited_block_names: inherited_block_names,
           inherited_dependencies: inherited_dependencies,
-          inherited_lines: inherited_lines,
+          context_code: context_code,
           keep_code: keep_code
         )
       )
@@ -3643,7 +3651,7 @@ module MarkdownExec
           document_filename: next_document_filename,
           inherited_block_names: inherited_block_names,
           inherited_dependencies: inherited_dependencies,
-          inherited_lines: inherited_lines,
+          context_code: context_code,
           keep_code: next_keep_code
         )
       )
@@ -3833,27 +3841,27 @@ module MarkdownExec
         reload_blocks = true
       end
 
-      link_state_inherited_lines = link_state&.inherited_lines || []
+      link_state_context_code = link_state&.context_code || []
 
       # return code resulting from evaluating all SHELL, UX, VARS blocks;
       # each set in sequence; with its own order
       #
-      if (code_lines, _inherit_lines = code_from_auto_blocks(
+      if (transient_code = inherited_lines_from_auto_blocks(
         all_blocks,
         default_only: true,
         mdoc: mdoc,
-        inherited_lines: link_state_inherited_lines
+        context_code: link_state_context_code
       ))&.select_by(:empty?, false)&.compact&.count&.positive?
-        wwt :code_lines, 'code_lines:', code_lines
+        wwt :transient_code, 'transient_code:', transient_code
 
-        # prepend inherited lines to new code lines
-        new_code = link_state_inherited_lines + code_lines
+        # prepend context code to new transient code
+        new_code = link_state_context_code + transient_code
         next_state_set_code(nil, link_state, new_code)
-        link_state.inherited_lines = new_code
+        link_state.context_code = new_code
 
         reload_blocks = true
       else
-        link_state&.inherited_lines
+        link_state&.context_code
       end
 
       if reload_blocks
@@ -4040,19 +4048,19 @@ module MarkdownExec
       list[(index + 1) % list.size] # Get the next item, wrap around if at the end
     end
 
-    def next_state_append_code(selected, link_state, code_lines,
+    def next_state_append_code(selected, link_state, context_code:,
                                mode: LoadMode::APPEND)
       next_state_set_code(
         selected,
         link_state,
         HashDelegator.flatten_and_compact_arrays(
-          mode == LoadMode::APPEND ? link_state&.inherited_lines : [],
-          code_lines.is_a?(Array) ? code_lines : [] # no code for :ux_exec_prohibited
+          mode == LoadMode::APPEND ? link_state&.context_code : [],
+          context_code.is_a?(Array) ? context_code : [] # no code for :ux_exec_prohibited
         )
       )
     end
 
-    def next_state_set_code(selected, link_state, code_lines)
+    def next_state_set_code(selected, link_state, context_code)
       block_names = []
       dependencies = {}
       link_history_push_and_next(
@@ -4062,7 +4070,7 @@ module MarkdownExec
           ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
         inherited_dependencies:
           (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
-        inherited_lines: HashDelegator.flatten_and_compact_arrays(code_lines),
+        context_code: HashDelegator.flatten_and_compact_arrays(context_code),
         keep_code: link_state&.keep_code,
         next_block_name: '',
         next_document_filename: @delegate_object[:filename],
@@ -4127,7 +4135,7 @@ module MarkdownExec
     end
 
     def pop_add_current_code_to_head_and_trigger_load(
-      link_state, block_names, code_lines,
+      link_state, block_names, transient_code,
       dependencies, selected, next_block_name: nil
     )
       pop = @link_history.pop # updatable
@@ -4139,9 +4147,9 @@ module MarkdownExec
            (pop.inherited_block_names + block_names).sort.uniq,
           inherited_dependencies:
            dependencies.merge(pop.inherited_dependencies || {}), ### merge, not replace, key data
-          inherited_lines:
-           HashDelegator.flatten_and_compact_arrays(pop.inherited_lines,
-                                                    code_lines)
+          context_code:
+           HashDelegator.flatten_and_compact_arrays(pop.context_code,
+                                                    transient_code)
         )
         @link_history.push(next_state)
 
@@ -4157,9 +4165,9 @@ module MarkdownExec
            ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
           inherited_dependencies:
            (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
-          inherited_lines:
+          context_code:
            HashDelegator.flatten_and_compact_arrays(
-             link_state&.inherited_lines, code_lines
+             link_state&.context_code, transient_code
            ),
           keep_code: link_state&.keep_code,
           next_block_name: next_block_name,
@@ -4184,7 +4192,7 @@ module MarkdownExec
         document_filename: pop.document_filename,
         inherited_block_names: peek.inherited_block_names,
         inherited_dependencies: peek.inherited_dependencies,
-        inherited_lines: peek.inherited_lines
+        context_code: peek.context_code
       )
     end
 
@@ -4560,11 +4568,13 @@ module MarkdownExec
       obj = {}
 
       # concatenated body of all required blocks loaded a YAML
+
+      rc = execute_block_type_port_code_lines(
+        mdoc: mdoc, selected: selected,
+        link_state: link_state, block_source: {}
+      )
       data = (YAML.load(
-        execute_block_type_port_code_lines(
-          mdoc: mdoc, selected: selected,
-          link_state: link_state, block_source: {}
-        ).join("\n")
+        rc[:context_code].join("\n")
       ) || {}).transform_keys(&:to_sym)
 
       if selected.type == BlockType::OPTS
@@ -4764,7 +4774,7 @@ module MarkdownExec
         filename: filename,
         saved_asset_format:
           shell_escape_asset_format(
-            code_lines: link_state&.inherited_lines,
+            transient_code: link_state&.context_code,
             shell: selected_shell(@delegate_object[:shell])
           )
       ).generate_name
@@ -4933,7 +4943,7 @@ module MarkdownExec
     end
 
     def shell_escape_asset_format(
-      code_lines:,
+      transient_code:,
       enable: @delegate_object[:shell_parameter_expansion],
       raw: @delegate_object[:saved_asset_format],
       shell:
@@ -4948,7 +4958,7 @@ module MarkdownExec
 
       marker = Random.new.rand.to_s
 
-      code = (code_lines || []) + ["echo -n \"#{marker}#{raw}\""]
+      code = (transient_code || []) + ["echo -n \"#{marker}#{raw}\""]
       File.write filespec, HashDelegator.join_code_lines(code)
       File.chmod 0o755, filespec
 
@@ -5484,10 +5494,10 @@ module MarkdownExec
     end
 
     def vux_edit_inherited
-      edited = edit_text(@dml_link_state.inherited_lines_block)
+      edited = edit_text(@dml_link_state.context_code_block)
       return unless edited
 
-      @dml_link_state.inherited_lines =
+      @dml_link_state.context_code =
         annotate_required_lines(
           'blk:EDIT', edited.split("\n"), block_name: 'EDIT'
         )
@@ -5707,7 +5717,7 @@ module MarkdownExec
     def vux_load_code_files_into_state
       return unless @menu_base_options[:load_code].present?
 
-      @dml_link_state.inherited_lines =
+      @dml_link_state.context_code =
         @menu_base_options[:load_code].split(':').map do |path|
           File.readlines(path, chomp: true)
         end.flatten(1)
@@ -5718,7 +5728,7 @@ module MarkdownExec
 
       pop_add_current_code_to_head_and_trigger_load(
         @dml_link_state, inherited_block_names,
-        code_lines, inherited_dependencies, selected
+        transient_code, inherited_dependencies, selected
       )
     end
 
@@ -5727,7 +5737,7 @@ module MarkdownExec
         document_name_in_glob_as_file_name
       ))
 
-      @dml_link_state.inherited_lines_append(
+      @dml_link_state.context_code_append(
         File.readlines(filespec, chomp: true)
       )
     end
@@ -5886,7 +5896,7 @@ module MarkdownExec
       files = document_glob ? Dir.glob(document_glob) : []
       @doc_saved_lines_files = files.count.positive? ? files : []
 
-      lines_count = @dml_link_state.inherited_lines_count
+      lines_count = @dml_link_state.context_code_count
 
       # add menu items (glob, load, save) and enable selectively
       if files.count.positive? || lines_count.positive?
@@ -6011,7 +6021,7 @@ module MarkdownExec
     end
 
     def vux_view_inherited(stream:)
-      stream.puts @dml_link_state.inherited_lines_block
+      stream.puts @dml_link_state.context_code_block
     end
 
     def wait_for_stream_processing
@@ -6104,7 +6114,7 @@ module MarkdownExec
           prefix: @delegate_object[:saved_script_filename_prefix],
           saved_asset_format:
             shell_escape_asset_format(
-              code_lines: @dml_link_state.inherited_lines,
+              transient_code: @dml_link_state.context_code,
               shell: shell
             ),
           time: time_now
@@ -6163,7 +6173,7 @@ module MarkdownExec
         if save_filespec.present?
           File.write(
             save_filespec,
-            HashDelegator.join_code_lines(link_state&.inherited_lines)
+            HashDelegator.join_code_lines(link_state&.context_code)
           )
           @delegate_object[:filename]
         else
@@ -6346,7 +6356,7 @@ module MarkdownExec
         LinkState.new(block_name: 'sample_block',
                       document_filename: 'sample_file',
                       inherited_dependencies: {},
-                      inherited_lines: ['# ', 'KEY="VALUE"'])
+                      context_code: ['# ', 'KEY="VALUE"'])
       )
       assert_equal expected_result,
                    @hd.execute_block_type_link_with_state(
@@ -6522,12 +6532,43 @@ module MarkdownExec
     def test_execute_block_type_port_code_lines_with_vars
       YAML.stubs(:load).returns({ 'key' => 'value' })
       @mdoc.stubs(:collect_recursively_required_code)
-           .returns({ code: ['code line'] })
+           .returns({ context_code: [], transient_code: ['code line'] })
       result = @hd.execute_block_type_port_code_lines(
         mdoc: @mdoc, selected: @selected, block_source: {}
       )
 
-      assert_equal ['code line', 'key="value"'], result
+      assert_equal ['key="value"'], result[:context_code]
+      assert_equal ['code line'], result[:transient_code]
+    end
+
+    def test_transient_code_parameter_usage
+      # Test that transient_code parameter is used correctly in execute_bash_script_lines
+      transient_code = ["echo 'test'", "echo 'transient'"]
+      export = OpenStruct.new(exportable: false, validate: //, transform: ->(x) { x })
+      result = HashDelegator.execute_bash_script_lines(
+        transient_code: transient_code,
+        export: export,
+        export_name: 'TEST',
+        shell: '/bin/bash'
+      )
+
+      assert result.is_a?(CommandResult)
+      assert_equal transient_code, result.script
+    end
+
+    def test_transient_code_vs_context_code_separation
+      # Test that transient_code is separate from context_code
+      context_code = ['CONTEXT_VAR="context_value"']
+      transient_code = ['TRANSIENT_VAR="transient_value"']
+
+      # Simulate combining them
+      all_code = HashDelegator.flatten_and_compact_arrays(
+        context_code, transient_code
+      )
+
+      assert_equal 2, all_code.length
+      assert_includes all_code, 'CONTEXT_VAR="context_value"'
+      assert_includes all_code, 'TRANSIENT_VAR="transient_value"'
     end
   end