howzit 2.1.45 → 2.1.47

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b5d2120c8484147d2d3cb8f8844073ca027e7a54655385749ee721f645d05a5
-  data.tar.gz: 3cef9cda18bf1b43b28d9288e9eda81d30b07fc9ac2505dd932e508240abf86b
+  metadata.gz: 477bc94918f7906d52412423ee73992f2d255279d757f36d0feed85f74c1f454
+  data.tar.gz: 926727bfe69e059367fa75d4b55b095786663487cdc8f311b13ee92dd44d15e0
 SHA512:
-  metadata.gz: 4dc4af7fce8a375a33a3dfee3ed2e6f9d914ea3069601aa3426ae552f4c5488d5aafa332522c4eef0a6b4318bd63afef20eda2d638e9c6fd09ce9784c5e6a434
-  data.tar.gz: fe60529771944221e4f7acd4bd9883669782f413c5a367ae3c03c8c7d8ce0a0e0413fcf4e086e37584868c58bbea10bb4e24ab49c28583521d901166404146be
+  metadata.gz: 8f4c4228bc522c7608f77d0ab4e7f4f802753e71c7f37d2f41d9f81e01764a8b0b285aaed8bc5bad6a9ccaa0544d83007bde4c7aea7c0e41bc2fc834bb8304d7
+  data.tar.gz: a24505c7b3f22f7d4bb52eb91372f44d0ef200285faf4006bb8a93588bdb63318063d26b5571026374f8f67b648678d0bd4edf4223c5561c39ad625ec2a08a69

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+### 2.1.47
+
+2026-09-27 13:20
+
+#### IMPROVED
+
+- **Included topics** receive their bracketed arguments as positional arguments ($1, $2) in shell run blocks for the duration of the include
+
+#### FIXED
+
+- **default: metadata** now splits topics only on commas outside of brackets, so `default: Build, Deploy[prod, fast], Test` passes both arguments to Deploy
+- **Bracketed arguments in default:** (e.g. `Deploy[prod]`) are now bound to the topic's title parameters, so `${target}` and friends render in @run commands instead of coming out empty
+- **@include bracketed arguments** (e.g. `@include(Deploy [staging])`) now bind to the included topic's parameters, and including the same topic multiple times with different arguments works
+- **Unspecified bracketed arguments** fall back to the topic's parameter defaults
+- **Topics that use @include with arguments** no longer lose their own argument definitions
+
+### 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

data/lib/howzit/buildnote.rb

@@ -1608,7 +1608,7 @@ module Howzit
                            else
                              []
                            end
-        output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+        output.push(process_topic(topic_match.with_arguments(Howzit.arguments), Howzit.options[:run], single: true))
         break if stop_after_failure?(topic_specs[(idx + 1)..].map(&:first))
       end
       finalize_output(output)
@@ -1640,7 +1640,8 @@ module Howzit
     ## @return     [Array] Array of topic specification strings
     ##
     def parse_default_metadata(default_value)
-      default_value.strip.split(/\s*,\s*/).map(&:strip).reject(&:empty?)
+      # Commas inside [bracketed arguments] separate arguments, not topics
+      default_value.strip.split(/\s*,\s*(?![^\[]*\])/).map(&:strip).reject(&:empty?)
     end
 
     ##

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/directive.rb

@@ -138,7 +138,7 @@ module Howzit
         if title =~ /\[(.*?)\] *$/
           args = Regexp.last_match(1).split(/ *, */).map(&:render_arguments)
           Howzit.arguments = args
-          parent.arguments
+          task_data[:include_args] = args
           title.sub!(/ *\[.*?\] *$/, '')
         end
         title = title.render_arguments if title && !title.empty?

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

@@ -27,12 +27,14 @@ module Howzit
       @prefix = "{bw}\u{25B7}\u{25B7} {x}"
       # arrow = "{bw}\u{279F}{x}"
       @arguments = attributes[:arguments] || []
+      @include_args = attributes[:include_args]
 
       @type = attributes[:type] || :run
       @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]
@@ -61,15 +63,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
@@ -117,9 +141,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
@@ -148,18 +172,35 @@ module Howzit
       output = []
       action = @action
 
-      matches = Howzit.buildnote.find_topic(action)
+      matches = Howzit.buildnote.find_topic(action.sub(/ *\[.*?\] *$/, ''))
       raise "Topic not found: #{action}" if matches.empty?
 
-      topic = matches[0]
+      topic = matches[0].with_arguments(@include_args)
       Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{topic.title}{x}".c)
-      output.concat(topic.run(nested: true))
+      output.concat(with_positional_arguments(@include_args) { topic.run(nested: true) })
       Howzit.console.info("{by}End include: #{topic.all_tasks.count} tasks{x}".c)
       @last_status = nil
       @include_results = topic.results.slice(:total, :success, :errors)
       [output, @include_results[:total], @include_results[:errors].zero?]
     end
 
+    ##
+    ## Temporarily set Howzit.arguments (e.g. $1 in included shell blocks)
+    ##
+    ## @param      args  [Array] Positional values, or nil to leave unchanged
+    ##
+    def with_positional_arguments(args)
+      return yield if args.nil? || args.empty?
+
+      previous = Howzit.arguments
+      Howzit.arguments = args
+      begin
+        yield
+      ensure
+        Howzit.arguments = previous
+      end
+    end
+
     ##
     ## Apply log level for this task
     ##
@@ -241,7 +282,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)
@@ -274,7 +315,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

data/lib/howzit/topic.rb

@@ -18,8 +18,11 @@ module Howzit
     ## @param      metadata    [Hash] Optional metadata hash
     ## @param      source_file [String] Optional path to the build note file this topic came from
     ## @param      level       [Integer] Markdown header level (2 for ##, 3 for ###, etc.)
+    ## @param      positional  [Array] Values to bind to the title's (arguments),
+    ##                         overriding CLI arguments
     ##
-    def initialize(title, content, metadata = nil, source_file: nil, level: 2)
+    def initialize(title, content, metadata = nil, source_file: nil, level: 2, positional: nil)
+      @raw_title = title
       @title = title
       @content = content
       @parent = nil
@@ -30,7 +33,7 @@ module Howzit
       @named_args = {}
       @metadata = metadata
       @source_file = source_file
-      arguments(from_cli_snapshot: true)
+      arguments(from_cli_snapshot: positional.nil?, positional: positional)
 
       @directives = parse_directives_with_conditionals
       @tasks = gather_tasks
@@ -71,24 +74,43 @@ module Howzit
       list
     end
 
+    ##
+    ## A copy of this topic with bracketed arguments (e.g.
+    ## `@include(Deploy [prod])` or `default: Deploy[prod]`) bound to the
+    ## title's (arguments). Tasks are rebuilt so commands render with them.
+    ##
+    ## @param      args  [Array] Positional values
+    ##
+    ## @return     [Topic] a new Topic, or self if no args given
+    ##
+    def with_arguments(args)
+      return self if args.nil? || args.empty?
+
+      topic = Topic.new(@raw_title, @content, @metadata, source_file: @source_file, level: @level, positional: args)
+      topic.parent = @parent
+      topic.parent_topic = @parent_topic
+      topic.subtopics.concat(@subtopics)
+      topic
+    end
+
     # Get named arguments from title
     # from_cli_snapshot: use Howzit.cli_topic_positional_args (argv after `--`) so earlier
-    # topics' gather_tasks cannot clobber positional binding. Re-entrant @include [a,b]
-    # calls pass false to use live Howzit.arguments.
-    def arguments(from_cli_snapshot: false)
+    # topics' gather_tasks cannot clobber positional binding. positional: binds
+    # bracketed arguments from @include [a,b] and default: (see #with_arguments).
+    def arguments(from_cli_snapshot: false, positional: nil)
       @arg_definitions = []
       return unless @title =~ /\(.*?\) *$/
 
-      positional = if from_cli_snapshot
-                     # Specs / non-CLI: leave unset to keep using Howzit.arguments
-                     if Howzit.cli_topic_positional_args.nil?
-                       Howzit.arguments || []
+      positional ||= if from_cli_snapshot
+                       # Specs / non-CLI: leave unset to keep using Howzit.arguments
+                       if Howzit.cli_topic_positional_args.nil?
+                         Howzit.arguments || []
+                       else
+                         Howzit.cli_topic_positional_args
+                       end
                      else
-                       Howzit.cli_topic_positional_args
+                       Howzit.arguments || []
                      end
-                   else
-                     Howzit.arguments || []
-                   end
 
       a = @title.match(/\((?<args>.*?)\) *$/)
       args = a['args'].split(/ *, */).each(&:strip)
@@ -538,7 +560,7 @@ module Howzit
         if title =~ /\[(.*?)\] *$/
           args = Regexp.last_match(1).split(/ *, */).map(&:render_arguments)
           Howzit.arguments = args
-          arguments
+          task_args[:include_args] = args
           title.sub!(/ *\[.*?\] *$/, '')
         end
         # Apply variable substitution to title after bracket processing

data/lib/howzit/version.rb

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

data/spec/default_metadata_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'default: metadata' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_default_test')) }
+  let(:out_file) { File.join(temp_dir, 'out.txt') }
+  let(:default_line) { 'default: Build, Deploy[prod, fast], Test' }
+  let(:buildnote) do
+    note = Howzit::BuildNote.new
+    allow(note).to receive(:finalize_output)
+    note
+  end
+
+  before do
+    File.write(
+      File.join(temp_dir, 'buildnotes.md'),
+      <<~NOTE
+        #{default_line}
+
+        # Default Project
+
+        ## Build
+
+        @run(echo "build" >> "#{out_file}") Build it
+
+        ## Deploy (target, speed:slow)
+
+        @run(echo "deploy ${target} ${speed}" >> "#{out_file}") Deploy it
+
+        ## Test
+
+        @run(echo "test" >> "#{out_file}") Test it
+
+        ## Broken
+
+        @run(false) Fail
+
+        ## Release
+
+        @include(Deploy [staging])
+        @include(Deploy [prod, fast])
+      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.options[:log_level] = 3
+    Howzit.cli_args = []
+    Howzit.run_log = []
+  end
+
+  after do
+    Howzit.options[:run] = false
+    Howzit.options[:log_level] = 1
+    Howzit.cli_args = []
+    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 output_lines
+    File.read(out_file).lines.map(&:strip)
+  end
+
+  describe 'parsing' do
+    it 'splits topics on commas outside of brackets' do
+      expect(buildnote.send(:parse_default_metadata, 'Build, Deploy[prod, fast],Test')).to eq(
+        ['Build', 'Deploy[prod, fast]', 'Test']
+      )
+    end
+
+    it 'separates bracketed arguments from the topic name' do
+      expect(buildnote.send(:parse_topic_with_args, 'Deploy[prod, fast]')).to eq(['Deploy', 'prod, fast'])
+      expect(buildnote.send(:parse_topic_with_args, 'Build')).to eq(['Build', nil])
+    end
+  end
+
+  describe 'running' do
+    it 'runs the default topics in order with howzit -r' do
+      buildnote.run
+
+      expect(output_lines).to eq(['build', 'deploy prod fast', 'test'])
+    end
+
+    it 'runs the default topics with howzit -r default' do
+      Howzit.cli_args = ['default']
+      buildnote.run
+
+      expect(output_lines).to eq(['build', 'deploy prod fast', 'test'])
+    end
+
+    context 'with fewer arguments than the topic accepts' do
+      let(:default_line) { 'default: Deploy[prod]' }
+
+      it 'uses the topic defaults for the rest' do
+        buildnote.run
+
+        expect(output_lines).to eq(['deploy prod slow'])
+      end
+    end
+
+    context 'with a missing topic' do
+      let(:default_line) { 'default: Build, Nonexistent, Test' }
+
+      it 'runs the topics that match' do
+        buildnote.run
+
+        expect(output_lines).to eq(%w[build test])
+      end
+    end
+
+    context 'with a failing topic' do
+      let(:default_line) { 'default: Build, Broken, Test' }
+
+      it 'stops after the failure and skips the remaining topics' do
+        buildnote.run
+
+        expect(output_lines).to eq(['build'])
+        expect(Howzit.run_log.map { |e| [e[:task], e[:skipped] ? :skipped : e[:success]] }).to eq(
+          [['Build it', true], ['Fail', false], ['Test it', :skipped]]
+        )
+      end
+    end
+  end
+
+  describe '@include with bracketed arguments' do
+    it 'binds the arguments to the included topic for each include' do
+      Howzit.cli_args = ['release']
+      buildnote.run
+
+      expect(output_lines).to eq(['deploy staging slow', 'deploy prod fast'])
+    end
+  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.45
+  version: 2.1.47
 platform: ruby
 authors:
 - Brett Terpstra
@@ -314,13 +314,13 @@ files:
 - lib/howzit/topic.rb
 - lib/howzit/util.rb
 - lib/howzit/version.rb
-- nested-topics-for-howzit.md
 - scripts/runtests.sh
 - spec/buildnote_spec.rb
 - spec/cli_spec.rb
 - spec/condition_evaluator_spec.rb
 - spec/conditional_blocks_integration_spec.rb
 - spec/conditional_content_spec.rb
+- spec/default_metadata_spec.rb
 - spec/includes_metadata_spec.rb
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
@@ -330,6 +330,7 @@ files:
 - 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
@@ -369,6 +370,7 @@ test_files:
 - spec/condition_evaluator_spec.rb
 - spec/conditional_blocks_integration_spec.rb
 - spec/conditional_content_spec.rb
+- spec/default_metadata_spec.rb
 - spec/includes_metadata_spec.rb
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
@@ -378,6 +380,7 @@ test_files:
 - 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

data/nested-topics-for-howzit.md

@@ -1,100 +0,0 @@
----
-title: Nested topics for Howzit
-layout: post
-tags: [howzit, ruby, markdown, cli, automation]
-categories: [Blog,Code]
-post_class: 'code'
-comments: true
----
-[Howzit](https://github.com/ttscoff/howzit) has always split build notes into topics using Markdown headers. What it didn't do was care *which* header level you used. An `##` and a `###` were both just "a topic," and they all got flattened into one long list. As of version 2.1.44, that's changed: deeper headers now nest under the header above them, and that nesting affects both how notes display and what happens when you run them.
-
-### The short version
-
-A `###` following a `##` is now a subtopic of that `##`. A `####` under the `###` is a subtopic of the `###`, and so on down. The next header at the same level (or shallower) closes out the parent.
-
-```markdown
-## Deploy
-
-@run(./scripts/preflight.sh) Preflight checks
-
-### Build assets
-
-@run(gulp) Build
-
-### Upload
-
-@run(gulp sync) Sync to server
-
-## Package management
-```
-
-Here "Build assets" and "Upload" belong to "Deploy." "Package management" is back at the top level.
-
-### Viewing a parent topic
-
-When you pull up a parent topic, you now get the whole thing: the parent, followed by all of its subtopics.
-
-```console
-$ howzit deploy
-```
-
-Subtopic headers get a slightly lighter treatment (a dotted rule and a cyan title) so you can see where the nesting happens without it getting noisy. You can still ask for a subtopic directly:
-
-```console
-$ howzit upload
-```
-
-...and you'll get just that section.
-
-### Running a parent topic
-
-This is the part I actually wanted. Running a parent now runs everything under it:
-
-```console
-$ howzit -r deploy
-```
-
-That runs Deploy's own tasks first, then each subtopic's tasks in order, depth-first. So the example above runs preflight, then the build, then the sync. You get one combined summary at the end instead of a "Ran 1 task" line for every section.
-
-A few details worth knowing:
-
-- **Errors stop the run.** If a task fails, the remaining subtopics are skipped. Add `--force` if you want it to push through anyway.
-- **`@before` and `@after` still work per topic.** Each topic shows its prerequisites before its own tasks run. A parent's `@after` block shows up once the parent *and* all of its subtopics are done, which is usually where you want that "don't forget to..." reminder.
-- **Parents don't need tasks of their own.** A parent that's just an umbrella for a few subtopics runs fine, and it won't complain about "No @directive found."
-- **Subtopics still run on their own.** `howzit -r upload` runs just the upload step.
-
-### Includes get the whole tree too
-
-If another topic does `@include(Deploy)`, it now runs Deploy and all of its subtopics, same as running it directly. Task counts in include notes and menus reflect the full tree, so you're not surprised by how much is about to happen.
-
-### Listing and "show everything"
-
-Running `howzit` with no arguments shows every topic. It now only prints top-level topics, since subtopics come along with their parents. No more seeing the same section twice.
-
-`howzit -l` indents subtopics under their parents, so the list reflects the structure of your note:
-
-```console
-$ howzit -l
-Topics:
-
-- Deploy
-  - Build assets
-  - Upload
-- Package management
-```
-
-Shell completions stay flat, so you can still tab-complete straight to a subtopic.
-
-### One thing to check in your notes
-
-If you've been using `###` headers under `##` purely as visual formatting, those are now real subtopics. Viewing the parent will include them (probably what you wanted anyway), and running the parent will run their tasks too. If you had a `###` section with tasks you *don't* want run as part of its parent, bump it up to `##`.
-
-### Grab it
-
-It's in 2.1.44:
-
-```console
-$ gem install howzit
-```
-
-The details are in the [build notes anatomy page](https://github.com/ttscoff/howzit/wiki/Anatomy-of-a-build-notes-file#subtopics) on the wiki. I've already started restructuring a few of my own notes around this. Having a single "Release" topic that fans out into build, test, and publish steps is a lot nicer than keeping them all at the same level and chaining them together with `@include`.