howzit 2.1.44 → 2.1.46

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 881188642b99f4be83a7697440251ec8890e6d847468c3984a72183939196857
-  data.tar.gz: c622b23318a075aa277a0a197e1ec93d8023e52e99018557e7eb6f8309c76927
+  metadata.gz: daae85713f05d780640619a8ada2291aaa69c0eb3f2d941f6fb9e2964c9247b4
+  data.tar.gz: 5773440b0a9718af5dd0b3e66929bfa74023061b99a85c61d65558b76ac57d4d
 SHA512:
-  metadata.gz: 219ae789410d1ec44619f3bfb00b7f8b539a33632e9b9d9e778f384205e03c653efa83a7a090d469dd769a2cdda53ae7026e40b495363879e59f24be38da09ae
-  data.tar.gz: d0c1dd2d03ab11923e93440fb9f04bfdfb0292d63522fd21483a38a7d2ca31c691dc64e4a894063944b586ef1b2af66fd8a4bd55ea132ce743b6e69e7fd812db
+  metadata.gz: 1f688d2e403997a3cf6f3b91c0ebd3746ed51b1d0bc4dfea2be5fd1297a22715d2a7b5672482b2f243dc26b38b56eee2880c9e57df98c55c16178b84eddeb8da
+  data.tar.gz: 934e5ef9e7b71bc0323475ae4c54596d7a6813f552d63fd08dd358f51805c6950780d4435b9cf830aed7712392a5a38d52077dfbcceb69293adf02f9b0970794

data/CHANGELOG.md

@@ -1,3 +1,51 @@
+### 2.1.46
+
+2026-09-27 12:52
+
+#### CHANGED
+
+- **Shell run blocks** (sh, bash, zsh, dash, ksh, or no hashbang) now receive Howzit variables as environment variables instead of having ${VAR} replaced in the script text, so scripts can use their own variables, parameter expansions, and ENV without Howzit clobbering them.
+- **Command-line arguments** after -- are passed to shell run blocks as script arguments, so $1, $#, and "$@" work like any shell script (including inside shell functions).
+
+#### NEW
+
+- **:shell_variables: config option** (env or substitute) to switch shell run blocks back to text substitution; defaults to env.
+- **$${VAR} escape** passes ${VAR} through to the shell untouched in @run, @copy, and text-substituted blocks.
+
+#### IMPROVED
+
+- **Howzit-style defaults** (${name:default}) in shell run blocks are converted to the shell's ${name:-default} so they keep working with environment variables.
+
+#### FIXED
+
+- **Shell parameter expansions** like ${VAR:-default}, ${VAR:=x}, ${VAR:+x}, ${VAR:?x}, and ${VAR:0:3} are no longer mangled into Howzit defaults when VAR isn't a Howzit variable.
+- **Positional placeholders** ($1, ${2}) without a matching argument are left intact instead of being replaced with an empty string, which broke shell functions and awk '{print $1}'.
+- **$@ and $*** are only replaced when arguments were passed after --, instead of always being replaced with an empty string.
+- **Default values containing colons** (e.g. ${url:http://localhost:3000}) are no longer cut off at the second colon.
+
+### 2.1.45
+
+2026-09-27 12:16
+
+#### CHANGED
+
+- **Multi-topic runs** (comma-separated topics or `default:` metadata) now stop after the first topic with a failed task and mark the remaining topics' tasks as skipped; use --force to run every topic.
+
+#### NEW
+
+- **Skipped tasks** in the run report: tasks that did not run because of an earlier failure are listed with a skipped marker and "(skipped)" label.
+- **Skipped @include tasks** are expanded to the included topic's individual tasks in the run report.
+
+#### IMPROVED
+
+- **Conditional topics** list remaining unconditional tasks as skipped after a failure; tasks inside unevaluated conditionals are omitted.
+
+#### FIXED
+
+- **Run report** now includes the task that failed and stopped a run, instead of omitting it and showing only the earlier successes.
+- **@include** directives now fail when a task in the included topic fails, so the including topic stops instead of continuing with its remaining tasks.
+- **Task totals for @include** reflect the included topic's actual successes and errors instead of counting every included task as a single result.
+
 ### 2.1.44
 
 2026-09-27 11:38

data/lib/howzit/buildnote.rb

@@ -1558,8 +1558,10 @@ module Howzit
         end
         topic_matches.compact! # Remove any nil values from failed matches
         # A matched subtopic is already output/run with its matched parent
-        top_level_topics(topic_matches).each do |topic_match|
+        selected = top_level_topics(topic_matches)
+        selected.each_with_index do |topic_match, idx|
           output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+          break if stop_after_failure?(selected[(idx + 1)..])
         end
       else
         top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
@@ -1599,7 +1601,7 @@ module Howzit
       end
 
       # Run each topic with its specific arguments
-      topic_specs.each do |topic_match, args|
+      topic_specs.each_with_index do |(topic_match, args), idx|
         # Set arguments if provided, otherwise clear them
         Howzit.arguments = if args && !args.empty?
                              args.split(/ *, */).map(&:render_arguments)
@@ -1607,10 +1609,29 @@ module Howzit
                              []
                            end
         output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+        break if stop_after_failure?(topic_specs[(idx + 1)..].map(&:first))
       end
       finalize_output(output)
     end
 
+    ##
+    ## After running a topic in a multi-topic run, check whether a task
+    ## failed. If so (and --force isn't set), log the remaining topics'
+    ## tasks as skipped.
+    ##
+    ## @param      remaining  [Array] Topics that haven't run yet
+    ##
+    ## @return     [Boolean] true if the run should stop
+    ##
+    def stop_after_failure?(remaining)
+      return false unless Howzit.options[:run]
+      return false if Howzit.options[:force]
+      return false unless Howzit.run_log.any? { |entry| !entry[:success] && !entry[:skipped] }
+
+      remaining.each { |topic| topic.log_skipped_tasks(topic.all_tasks) }
+      true
+    end
+
     ##
     ## Parse default metadata value into individual topic specifications
     ##

data/lib/howzit/config.rb

@@ -21,6 +21,7 @@ module Howzit
       output_title: false,
       pager: 'auto',
       paginate: true,
+      shell_variables: 'env', # env: pass variables to shell run blocks via ENV, substitute: replace ${VAR} in text
       show_all_code: false,
       show_all_on_error: false,
       wrap: 0

data/lib/howzit/run_report.rb

@@ -26,8 +26,20 @@ module Howzit
       output_lines.join("\n")
     end
 
+    def status_symbol(entry)
+      return '⏭️' if entry[:skipped]
+
+      entry[:success] ? '✅' : '❌'
+    end
+
+    def status_reason(entry)
+      return 'skipped' if entry[:skipped]
+
+      entry[:exit_status] ? "exit code #{entry[:exit_status]}" : 'failed'
+    end
+
     def format_line(entry, prefix_topic)
-      symbol = entry[:success] ? '✅' : '❌'
+      symbol = status_symbol(entry)
       parts = ["#{symbol} "]
       if prefix_topic && entry[:topic] && !entry[:topic].empty?
         # Escape braces and dollar signs in topic name to prevent color code interpretation
@@ -36,10 +48,11 @@ module Howzit
       end
       # Escape braces and dollar signs in task name to prevent color code interpretation
       task_escaped = entry[:task].gsub(/\{/, '\\{').gsub(/\}/, '\\}').gsub(/\$/, '\\$')
-      parts << "{by}#{task_escaped} {x}"
-      unless entry[:success]
-        reason = entry[:exit_status] ? "exit code #{entry[:exit_status]}" : 'failed'
-        parts << " {br}(#{reason}){x}"
+      if entry[:skipped]
+        parts << "{d}#{task_escaped} (skipped){x}"
+      else
+        parts << "{by}#{task_escaped} {x}"
+        parts << " {br}(#{status_reason(entry)}){x}" unless entry[:success]
       end
       parts.join.c
     end
@@ -76,7 +89,7 @@ module Howzit
     def format_row(entry, prefix_topic)
       # Use plain emoji without color codes - the emoji itself provides visual meaning
       # and complex ANSI codes interfere with mdless table rendering
-      symbol = entry[:success] ? '✅' : '❌'
+      symbol = status_symbol(entry)
 
       task_parts = []
       task_parts_plain = []
@@ -94,7 +107,7 @@ module Howzit
       task_parts_plain << entry[:task]
 
       unless entry[:success]
-        reason = entry[:exit_status] ? "exit code #{entry[:exit_status]}" : 'failed'
+        reason = status_reason(entry)
         task_parts << " {br}(#{reason}){x}"
         task_parts_plain << " (#{reason})"
       end

data/lib/howzit/script_support.rb

@@ -153,6 +153,35 @@ module Howzit
         end
       end
 
+      ##
+      ## Whether a run block is a POSIX-style shell script (sh, bash,
+      ## zsh, dash, ksh). Blocks without a hashbang run with sh.
+      ##
+      ## @param      script_content  [String] The script content
+      ##
+      ## @return     [Boolean]
+      ##
+      def shell_script?(script_content)
+        first_line = script_content.to_s.lines.first&.strip
+        return true unless first_line&.start_with?('#!')
+
+        first_line.match?(%r{\A#!\s*(?:/usr/bin/env\s+)?(?:\S*/)?(?:sh|bash|zsh|dash|ksh)(?:\s|\z)})
+      end
+
+      ##
+      ## Howzit variables as environment variables for shell run blocks
+      ##
+      ## @return     [Hash] name => string value
+      ##
+      def variables_env
+        (Howzit.named_arguments || {}).each_with_object({}) do |(key, value), env|
+          name = key.to_s
+          next if value.nil? || !name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+
+          env[name] = value.to_s
+        end
+      end
+
       ##
       ## Get the injection line for a given interpreter
       ##

data/lib/howzit/stringutils.rb

@@ -383,29 +383,64 @@ module Howzit
       str = dup
       str.render_named_placeholders
       str.render_numeric_placeholders
-      Howzit.arguments.nil? ? str : str.gsub(/\$[@*]/, Shellwords.join(Howzit.arguments))
+      args = Howzit.arguments
+      return str if args.nil? || args.empty?
+
+      str.gsub(/(?<!\$)\$[@*]/, Shellwords.join(args))
     end
 
+    ##
+    ## Replace ${NAME} and ${NAME:default} with Howzit variable
+    ## values. Names Howzit doesn't know, shell parameter
+    ## expansions (${VAR:-x}, ${VAR:=x}, ${VAR:0:3}, etc.), and
+    ## escaped $${NAME} placeholders are left for the shell.
+    ##
     def render_named_placeholders
-      gsub!(/\$\{(?<name>[A-Z0-9_]+(?::.*?)?)\}/i) do
+      gsub!(/(?<!\$)\$\{(?<name>[A-Z0-9_]+)(?<rest>:[^}]*)?\}/i) do
         m = Regexp.last_match
-        arg, default = m['name'].split(/:/).map(&:strip)
-        if Howzit.named_arguments&.key?(arg) && !Howzit.named_arguments[arg].nil?
-          Howzit.named_arguments[arg]
-        elsif default
-          default
+        original = m[0]
+        rest = m['rest'].to_s
+        value = placeholder_value(m['name'])
+
+        if rest.empty?
+          value.nil? ? original : value
+        elsif rest.start_with?(':-')
+          value.nil? || value.empty? || rest.include?('$') ? original : value
+        elsif rest.match?(/\A:[=+?\s\d]/)
+          original
         else
-          # Preserve the original ${VAR} syntax if variable is not defined and no default provided
-          m[0]
+          value.nil? ? rest[1..].strip : value
         end
       end
     end
 
     def render_numeric_placeholders
-      gsub!(/\$\{?(\d+)\}?/) do
-        arg, default = Regexp.last_match(1).split(/:/)
-        idx = arg.to_i - 1
-        Howzit.arguments.length > idx ? Howzit.arguments[idx] : default || Regexp.last_match(0)
+      gsub!(/(?<!\$)\$(?:\{(\d+)\}|(\d+))/) do
+        m = Regexp.last_match
+        placeholder_value(m[1] || m[2]) || m[0]
+      end
+    end
+
+    ##
+    ## Remove the escape from $${NAME} placeholders, leaving
+    ## ${NAME} for the shell. Applied right before execution.
+    ##
+    ## @return     [String] unescaped string
+    ##
+    def unescape_placeholders
+      gsub(/\$\$(?=\{)/, '$')
+    end
+
+    ##
+    ## Convert Howzit-style ${NAME:default} to the shell's
+    ## ${NAME:-default} so defaults work when variables are
+    ## passed to a shell script through the environment
+    ##
+    ## @return     [String] converted string
+    ##
+    def shellify_defaults
+      gsub(/(?<!\$)\$\{([A-Za-z_][A-Za-z0-9_]*|\d+):(?![-=+?\s\d$(])([^}]*)\}/) do
+        "${#{Regexp.last_match(1)}:-#{Regexp.last_match(2)}}"
       end
     end
 
@@ -560,6 +595,24 @@ module Howzit
         Color.template("\n\n#{title}#{tail}{x}\n\n")
       end
     end
+
+    private
+
+    ##
+    ## Look up a placeholder name: digits are positional
+    ## arguments, anything else is a named variable
+    ##
+    ## @return     [String, nil] value, or nil if not defined
+    ##
+    def placeholder_value(name)
+      if name.match?(/\A\d+\z/)
+        idx = name.to_i - 1
+        args = Howzit.arguments || []
+        return idx >= 0 && idx < args.length ? args[idx].to_s : nil
+      end
+
+      Howzit.named_arguments&.[](name)&.to_s
+    end
   end
 end
 

data/lib/howzit/task.rb

@@ -5,7 +5,8 @@ require 'English'
 module Howzit
   # Task object
   class Task
-    attr_reader :type, :title, :action, :arguments, :parent, :optional, :default, :last_status, :log_level, :source_file
+    attr_reader :type, :title, :action, :arguments, :parent, :optional, :default, :last_status, :log_level, :source_file,
+                :include_results
 
     ##
     ## Initialize a Task object
@@ -31,7 +32,8 @@ module Howzit
       @title = attributes[:title]&.to_s
       @parent = attributes[:parent] || nil
 
-      @action = attributes[:action].render_arguments || nil
+      action = attributes[:action]
+      @action = shell_env_block?(action) ? action : action.render_arguments
       @log_level = attributes[:log_level]
       # Get source_file from parent topic if available, or from attributes
       parent_obj = attributes[:parent]
@@ -60,15 +62,37 @@ module Howzit
       @title
     end
 
+    ##
+    ## Whether this is a shell run block that receives Howzit
+    ## variables through the environment instead of text substitution
+    ##
+    ## @param      content  [String] The block content
+    ##
+    def shell_env_block?(content = @action)
+      @type == :block &&
+        Howzit.options[:shell_variables].to_s != 'substitute' &&
+        ScriptSupport.shell_script?(content)
+    end
+
     ##
     ## Execute a block type
     ##
     def run_block
       Howzit.console.info "#{@prefix}{bg}Running block {bw}#{@title}{x}".c if Howzit.options[:log_level] < 2
       block = @action
+      env_mode = shell_env_block?(block)
       # Apply variable substitution to block content at execution time
       # (variables from previous run blocks are now available)
-      block = block.render_arguments if block && !block.empty?
+      if env_mode
+        block = block.shellify_defaults
+        env = ScriptSupport.variables_env
+        script_args = Howzit.arguments || []
+      else
+        block = block.render_arguments if block && !block.empty?
+        env = {}
+        script_args = []
+      end
+      block = block.unescape_placeholders
       script = Tempfile.new('howzit_script')
       comm_file = ScriptComm.setup
       old_log_level = apply_log_level
@@ -116,9 +140,9 @@ module Howzit
         cmd = ScriptSupport.execution_command_for(script.path, interpreter)
         # If interpreter is nil, execute directly (will respect hashbang)
         res = if interpreter.nil?
-                system(script.path)
+                system(env, script.path, *script_args)
               else
-                system(cmd)
+                system(env, [cmd, *script_args.map { |arg| Shellwords.escape(arg) }].join(' '))
               end
       ensure
         # Restore original directory
@@ -141,7 +165,7 @@ module Howzit
     ##
     ## Execute an include task
     ##
-    ## @return     [Array] [[Array] output, [Integer] number of tasks executed]
+    ## @return     [Array] [[Array] output, [Integer] number of tasks executed, [Boolean] all tasks succeeded]
     ##
     def run_include
       output = []
@@ -150,11 +174,13 @@ module Howzit
       matches = Howzit.buildnote.find_topic(action)
       raise "Topic not found: #{action}" if matches.empty?
 
-      Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{matches[0].title}{x}".c)
-      output.concat(matches[0].run(nested: true))
-      Howzit.console.info("{by}End include: #{matches[0].all_tasks.count} tasks{x}".c)
+      topic = matches[0]
+      Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{topic.title}{x}".c)
+      output.concat(topic.run(nested: true))
+      Howzit.console.info("{by}End include: #{topic.all_tasks.count} tasks{x}".c)
       @last_status = nil
-      [output, matches[0].all_tasks.count]
+      @include_results = topic.results.slice(:total, :success, :errors)
+      [output, @include_results[:total], @include_results[:errors].zero?]
     end
 
     ##
@@ -238,7 +264,7 @@ module Howzit
           Dir.chdir(expanded_exec_dir) if expanded_exec_dir != expanded_original
         end
 
-        res = system(@action)
+        res = system(@action.unescape_placeholders)
       ensure
         # Restore original directory
         if exec_dir && Dir.exist?(exec_dir)
@@ -271,7 +297,7 @@ module Howzit
                         @title && !@title.empty? ? @title : @action
                       end
       Howzit.console.info("#{@prefix}{bg}Copied {bw}#{display_title}{bg} to clipboard{x}".c)
-      Util.os_copy(@action)
+      Util.os_copy(@action.unescape_placeholders)
       @last_status = 0
       true
     end
@@ -287,7 +313,8 @@ module Howzit
             else
               case @type
               when :include
-                output, tasks = run_include
+                output, tasks, include_success = run_include
+                include_success
               when :run
                 run_run
               when :copy

data/lib/howzit/topic.rb

@@ -157,7 +157,11 @@ module Howzit
         Howzit.console.warn "{r}--run: No {br}@directive{xr} found in {bw}#{@title}{x}".c
       end
 
-      run_subtopics(output) unless halted?
+      if halted?
+        log_skipped_tasks(@subtopics.flat_map(&:all_tasks))
+      else
+        run_subtopics(output)
+      end
 
       if @results[:total].positive? || (all_tasks.any? && !sequential?)
         @results[:message] += results_message
@@ -225,37 +229,76 @@ module Howzit
     ## Run tasks without conditional evaluation
     ##
     def run_tasks(output)
-      @tasks.each do |task|
+      @tasks.each_with_index do |task, idx|
         next if (task.optional || Howzit.options[:ask]) && !ask_task(task)
 
         run_output, total, success = task.run
 
         output.concat(run_output)
+        record_task_result(task, total, success)
+        next unless halted?
+
+        log_skipped_tasks(@tasks[(idx + 1)..])
+        break
+      end
+      output
+    end
+
+    ##
+    ## Add a task's results to the topic totals and the run report
+    ##
+    ## @param      task     [Task] The task that ran
+    ## @param      total    [Integer] Number of tasks it represents
+    ## @param      success  [Boolean] Whether it succeeded
+    ##
+    def record_task_result(task, total, success)
+      if task.type == :include && task.include_results
+        %i[total success errors].each { |key| @results[key] += task.include_results[key] }
+      else
         @results[:total] += total
+        @results[success ? :success : :errors] += total
+      end
 
-        if success
-          @results[:success] += total
-        else
-          Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
+      log_task_result(task, success)
+      Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c unless success
+    end
 
-          @results[:errors] += total
+    ##
+    ## Log tasks that won't run because an earlier task failed.
+    ## Include tasks are expanded to the tasks of the included topic.
+    ##
+    ## @param      tasks  [Array] Task objects
+    ## @param      seen   [Array] Titles of included topics already expanded
+    ##
+    def log_skipped_tasks(tasks, seen = [])
+      return unless Howzit.options[:run]
 
-          break unless Howzit.options[:force]
+      Howzit.run_log ||= []
+      tasks.each do |task|
+        if task.type == :include
+          topic = Howzit.buildnote.find_topic(task.action)[0]
+          next if topic.nil? || seen.include?(topic.title)
+
+          topic.log_skipped_tasks(topic.all_tasks, seen + [topic.title])
+          next
         end
 
-        log_task_result(task, success)
+        topic_title = task.parent.is_a?(Topic) ? task.parent.title : @title
+        Howzit.run_log << { topic: topic_title, task: task_log_title(task), success: false, skipped: true }
       end
-      output
     end
 
     ##
     ## Run each subtopic in order, adding its results to this topic's
     ##
     def run_subtopics(output)
-      @subtopics.each do |sub|
+      @subtopics.each_with_index do |sub, idx|
         output.concat(sub.run(nested: true, as_subtopic: true))
         %i[total success errors].each { |key| @results[key] += sub.results[key] }
-        break if halted?
+        next unless halted?
+
+        log_skipped_tasks(@subtopics[(idx + 1)..].flat_map(&:all_tasks))
+        break
       end
       output
     end
@@ -538,22 +581,20 @@ module Howzit
       return if task.type == :include
 
       Howzit.run_log ||= []
-
-      title = (task.title || '').strip
-      if title.empty?
-        action = (task.action || '').strip
-        title = action.split(/\n/).first.to_s.strip
-      end
-      title = task.type.to_s.capitalize if title.nil? || title.empty?
-
       Howzit.run_log << {
         topic: @title,
-        task: title,
+        task: task_log_title(task),
         success: success ? true : false,
         exit_status: task.last_status
       }
     end
 
+    def task_log_title(task)
+      title = (task.title || '').strip
+      title = (task.action || '').strip.split(/\n/).first.to_s.strip if title.empty?
+      title.empty? ? task.type.to_s.capitalize : title
+    end
+
     def gather_tasks
       runnable = []
       # Process conditional blocks first
@@ -968,20 +1009,14 @@ module Howzit
         run_output, total, success = task.run
 
         output.concat(run_output)
-        @results[:total] += total
-
-        if success
-          @results[:success] += total
-        else
-          Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
-
-          @results[:errors] += total
-
-          break unless Howzit.options[:force]
+        record_task_result(task, total, success)
+        if halted?
+          # Tasks inside conditionals are omitted, since their conditions were never evaluated
+          remaining = @directives[directive_index..].select { |d| d.task? && (d.conditional_path || []).empty? }
+          log_skipped_tasks(remaining.filter_map { |d| d.to_task(self) })
+          break
         end
 
-        log_task_result(task, success)
-
         # Re-evaluate all open conditionals after task execution
         re_evaluate_conditionals(conditional_state, directive_index - 1, context)
       end

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.1.44'
+  VERSION = '2.1.46'
 end

data/spec/run_report_accuracy_spec.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'run report accuracy' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_run_report_test')) }
+  let(:buildnote) { Howzit::BuildNote.new }
+
+  before do
+    File.write(
+      File.join(temp_dir, 'buildnotes.md'),
+      <<~NOTE
+        # Run Report Project
+
+        ## Failing
+
+        @run(true) First
+        @run(false) Second
+        @run(true) Third
+
+        ## Release
+
+        @include(Failing)
+        @run(true) After include
+
+        ## Early Failure
+
+        @run(false) Fails first
+        @include(Failing)
+
+        ## Conditional
+
+        @if 1 == 1
+        @run(false) Conditional failure
+        @run(true) Conditional after
+        @end
+        @run(true) Unconditional after
+
+        ## Parent
+
+        @run(true) Parent task
+
+        ### Broken Child
+
+        @run(false) Child failure
+        @run(true) Child after
+
+        ### Later Child
+
+        @run(true) Later child task
+      NOTE
+    )
+
+    Dir.chdir(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, buildnote)
+    Howzit.options[:stack] = false
+    Howzit.options[:include_upstream] = false
+    Howzit.options[:run] = true
+    Howzit.options[:force] = false
+    Howzit.run_log = []
+  end
+
+  after do
+    Howzit.options[:run] = false
+    Howzit.options[:force] = false
+    Howzit.run_log = []
+    Dir.chdir(Dir.tmpdir)
+    FileUtils.rm_rf(temp_dir) if Dir.exist?(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, nil)
+  end
+
+  def report
+    Howzit.run_log.map do |entry|
+      status = if entry[:skipped]
+                 :skipped
+               else
+                 entry[:success] ? :ok : :failed
+               end
+      [entry[:task], status]
+    end
+  end
+
+  it 'logs the failed task and marks the rest as skipped' do
+    buildnote.find_topic('Failing')[0].run
+
+    expect(report).to eq([['First', :ok], ['Second', :failed], ['Third', :skipped]])
+    expect(Howzit.run_log[1][:exit_status]).to eq(1)
+  end
+
+  it 'treats a failed include as a failure and skips the rest of the including topic' do
+    topic = buildnote.find_topic('Release')[0]
+    topic.run
+
+    expect(report).to eq([['First', :ok], ['Second', :failed], ['Third', :skipped], ['After include', :skipped]])
+    expect(topic.results).to include(total: 2, success: 1, errors: 1)
+  end
+
+  it 'expands skipped includes into the included topic tasks' do
+    buildnote.find_topic('Early Failure')[0].run
+
+    expect(report).to eq([['Fails first', :failed], ['First', :skipped], ['Second', :skipped], ['Third', :skipped]])
+    expect(Howzit.run_log[1][:topic]).to eq('Failing')
+  end
+
+  it 'skips only unconditional tasks after a failure in a conditional topic' do
+    buildnote.find_topic('Conditional')[0].run
+
+    expect(report).to eq([['Conditional failure', :failed], ['Unconditional after', :skipped]])
+  end
+
+  it 'skips remaining subtopics after a subtopic fails' do
+    buildnote.find_topic('Parent')[0].run
+
+    expect(report).to eq([
+                           ['Parent task', :ok],
+                           ['Child failure', :failed],
+                           ['Child after', :skipped],
+                           ['Later child task', :skipped]
+                         ])
+    expect(Howzit.run_log.last[:topic]).to eq('Later Child')
+  end
+
+  it 'continues past failures with --force and logs every result' do
+    Howzit.options[:force] = true
+    topic = buildnote.find_topic('Release')[0]
+    topic.run
+
+    expect(report).to eq([['First', :ok], ['Second', :failed], ['Third', :ok], ['After include', :ok]])
+    expect(topic.results).to include(total: 4, success: 3, errors: 1)
+  end
+
+  describe 'multi-topic runs' do
+    before do
+      allow(buildnote).to receive(:finalize_output)
+    end
+
+    let(:topics) { ['Failing', 'Parent'].map { |title| buildnote.find_topic(title)[0] } }
+
+    it 'stops after a topic fails and skips the remaining topics' do
+      buildnote.send(:process_topic_matches, topics, [])
+
+      expect(report).to eq([
+                             ['First', :ok],
+                             ['Second', :failed],
+                             ['Third', :skipped],
+                             ['Parent task', :skipped],
+                             ['Child failure', :skipped],
+                             ['Child after', :skipped],
+                             ['Later child task', :skipped]
+                           ])
+    end
+
+    it 'runs every topic with --force' do
+      Howzit.options[:force] = true
+      buildnote.send(:process_topic_matches, topics, [])
+
+      expect(report.map(&:first)).to include('Parent task', 'Later child task')
+      expect(report.map(&:last)).not_to include(:skipped)
+    end
+  end
+
+  it 'formats skipped tasks in the report' do
+    buildnote.find_topic('Failing')[0].run
+    plain = Howzit::RunReport.format.uncolor
+
+    expect(plain).to include('❌ Second  (exit code 1)')
+    expect(plain).to include('⏭️ Third (skipped)')
+  end
+end

data/spec/shell_variables_spec.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'shell variable handling' do
+  before do
+    Howzit.arguments = []
+    Howzit.named_arguments = { 'file' => 'README.md', 'version' => '1.2.3' }
+  end
+
+  after do
+    Howzit.arguments = []
+    Howzit.named_arguments = {}
+  end
+
+  describe 'String#render_arguments' do
+    it 'substitutes Howzit variables' do
+      expect('v${version}'.render_arguments).to eq('v1.2.3')
+    end
+
+    it 'leaves unknown variables for the shell' do
+      expect('echo "${HOME}"'.render_arguments).to eq('echo "${HOME}"')
+    end
+
+    it 'uses Howzit-style defaults for undefined variables' do
+      expect('${missing:fallback}'.render_arguments).to eq('fallback')
+      expect('${url:http://localhost:3000}'.render_arguments).to eq('http://localhost:3000')
+    end
+
+    it 'leaves shell parameter expansions alone' do
+      %w[${OUT:-/tmp} ${OUT:=/tmp} ${OUT:+set} ${OUT:?missing} ${NAME:0:3} ${#NAME} ${NAME/a/b}].each do |expansion|
+        expect(expansion.render_arguments).to eq(expansion)
+      end
+    end
+
+    it 'substitutes a defined Howzit variable in ${VAR:-default}' do
+      expect('${version:-0.0.0}'.render_arguments).to eq('1.2.3')
+    end
+
+    it 'leaves positional placeholders without a matching argument' do
+      expect('f() { echo "$1 ${2}"; }'.render_arguments).to eq('f() { echo "$1 ${2}"; }')
+      expect("awk '{print $1}'".render_arguments).to eq("awk '{print $1}'")
+    end
+
+    it 'leaves $@ and $* alone when no arguments were passed' do
+      expect('run() { "$@"; }'.render_arguments).to eq('run() { "$@"; }')
+    end
+
+    it 'substitutes positional arguments when passed' do
+      Howzit.arguments = ['one', 'two words']
+      expect('$1 ${2} ${3:three}'.render_arguments).to eq('one two words three')
+      expect('cmd $@'.render_arguments).to eq("cmd one two\\ words")
+    end
+
+    it 'leaves escaped $${VAR} placeholders until execution' do
+      rendered = 'echo $${file}'.render_arguments
+      expect(rendered).to eq('echo $${file}')
+      expect(rendered.unescape_placeholders).to eq('echo ${file}')
+    end
+  end
+
+  describe 'String#shellify_defaults' do
+    it 'converts Howzit defaults to shell defaults' do
+      expect('${name:world} ${1:first}'.shellify_defaults).to eq('${name:-world} ${1:-first}')
+    end
+
+    it 'leaves shell expansions alone' do
+      %w[${name} ${name:-x} ${name:0:3} ${name:$offset} ${name: -2}].each do |expansion|
+        expect(expansion.shellify_defaults).to eq(expansion)
+      end
+    end
+  end
+
+  describe 'ScriptSupport.shell_script?' do
+    it 'detects shell scripts' do
+      expect(Howzit::ScriptSupport.shell_script?("echo hi\n")).to be true
+      expect(Howzit::ScriptSupport.shell_script?("#!/bin/bash\necho hi\n")).to be true
+      expect(Howzit::ScriptSupport.shell_script?("#!/usr/bin/env zsh\n")).to be true
+      expect(Howzit::ScriptSupport.shell_script?("#!/bin/sh -e\n")).to be true
+    end
+
+    it 'excludes other interpreters' do
+      expect(Howzit::ScriptSupport.shell_script?("#!/usr/bin/env ruby\n")).to be false
+      expect(Howzit::ScriptSupport.shell_script?("#!/usr/bin/env fish\n")).to be false
+      expect(Howzit::ScriptSupport.shell_script?("#!/usr/bin/env python3\n")).to be false
+    end
+  end
+
+  describe 'running blocks' do
+    let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_shell_vars_test')) }
+    let(:out_file) { File.join(temp_dir, 'out.txt') }
+
+    before do
+      File.write(
+        File.join(temp_dir, 'buildnotes.md'),
+        <<~NOTE
+          # Shell Variables
+
+          ## Shell Block (target:prod)
+
+          ```run
+          #!/bin/bash
+          greet() { echo "arg=$1"; }
+          for file in a.rb; do echo "loop=${file}"; done > "#{out_file}"
+          echo "howzit=${target}" >> "#{out_file}"
+          echo "default=${undefined_var:fallback}" >> "#{out_file}"
+          echo "shell_default=${UNSET_THING:-shellval}" >> "#{out_file}"
+          echo "env=${HOWZIT_SPEC_ENV}" >> "#{out_file}"
+          greet hello >> "#{out_file}"
+          echo "script_arg=${1:-none}" >> "#{out_file}"
+          ```
+
+          ## Escaped Run
+
+          @run(echo "$${HOWZIT_SPEC_ENV}" > "#{out_file}") Escaped
+        NOTE
+      )
+
+      ENV['HOWZIT_SPEC_ENV'] = 'from_env'
+      Dir.chdir(temp_dir)
+      Howzit.instance_variable_set(:@buildnote, nil)
+      Howzit.options[:stack] = false
+      Howzit.options[:include_upstream] = false
+      Howzit.options[:log_level] = 3
+      Howzit.named_arguments = { 'file' => 'README.md' }
+    end
+
+    after do
+      ENV.delete('HOWZIT_SPEC_ENV')
+      Howzit.options[:shell_variables] = 'env'
+      Howzit.options[:log_level] = 1
+      Dir.chdir(Dir.tmpdir)
+      FileUtils.rm_rf(temp_dir) if Dir.exist?(temp_dir)
+      Howzit.instance_variable_set(:@buildnote, nil)
+    end
+
+    def output_lines
+      File.read(out_file).lines.map(&:strip)
+    end
+
+    it 'passes Howzit variables to shell blocks through the environment' do
+      Howzit::BuildNote.new.find_topic('Shell Block')[0].run
+
+      expect(output_lines).to eq([
+                                   'loop=a.rb',
+                                   'howzit=prod',
+                                   'default=fallback',
+                                   'shell_default=shellval',
+                                   'env=from_env',
+                                   'arg=hello',
+                                   'script_arg=none'
+                                 ])
+    end
+
+    it 'passes positional arguments to the script' do
+      Howzit.arguments = ['cli_arg']
+      Howzit::BuildNote.new.find_topic('Shell Block')[0].run
+
+      expect(output_lines).to include('arg=hello', 'script_arg=cli_arg')
+    end
+
+    it 'uses text substitution when shell_variables is substitute' do
+      Howzit.options[:shell_variables] = 'substitute'
+      Howzit::BuildNote.new.find_topic('Shell Block')[0].run
+
+      expect(output_lines).to include('loop=README.md', 'howzit=prod')
+    end
+
+    it 'passes escaped placeholders to the shell in @run commands' do
+      Howzit::BuildNote.new.find_topic('Escaped Run')[0].run
+
+      expect(output_lines).to eq(['from_env'])
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.44
+  version: 2.1.46
 platform: ruby
 authors:
 - Brett Terpstra
@@ -324,10 +324,12 @@ files:
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
 - spec/ruby_gem_spec.rb
+- spec/run_report_accuracy_spec.rb
 - spec/run_report_spec.rb
 - spec/script_comm_spec.rb
 - spec/sequential_conditional_spec.rb
 - spec/set_var_spec.rb
+- spec/shell_variables_spec.rb
 - spec/spec_helper.rb
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
@@ -371,10 +373,12 @@ test_files:
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
 - spec/ruby_gem_spec.rb
+- spec/run_report_accuracy_spec.rb
 - spec/run_report_spec.rb
 - spec/script_comm_spec.rb
 - spec/sequential_conditional_spec.rb
 - spec/set_var_spec.rb
+- spec/shell_variables_spec.rb
 - spec/spec_helper.rb
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb