howzit 2.1.45 → 2.1.46

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b5d2120c8484147d2d3cb8f8844073ca027e7a54655385749ee721f645d05a5
-  data.tar.gz: 3cef9cda18bf1b43b28d9288e9eda81d30b07fc9ac2505dd932e508240abf86b
+  metadata.gz: daae85713f05d780640619a8ada2291aaa69c0eb3f2d941f6fb9e2964c9247b4
+  data.tar.gz: 5773440b0a9718af5dd0b3e66929bfa74023061b99a85c61d65558b76ac57d4d
 SHA512:
-  metadata.gz: 4dc4af7fce8a375a33a3dfee3ed2e6f9d914ea3069601aa3426ae552f4c5488d5aafa332522c4eef0a6b4318bd63afef20eda2d638e9c6fd09ce9784c5e6a434
-  data.tar.gz: fe60529771944221e4f7acd4bd9883669782f413c5a367ae3c03c8c7d8ce0a0e0413fcf4e086e37584868c58bbea10bb4e24ab49c28583521d901166404146be
+  metadata.gz: 1f688d2e403997a3cf6f3b91c0ebd3746ed51b1d0bc4dfea2be5fd1297a22715d2a7b5672482b2f243dc26b38b56eee2880c9e57df98c55c16178b84eddeb8da
+  data.tar.gz: 934e5ef9e7b71bc0323475ae4c54596d7a6813f552d63fd08dd358f51805c6950780d4435b9cf830aed7712392a5a38d52077dfbcceb69293adf02f9b0970794

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+### 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/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/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

@@ -32,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]
@@ -61,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
@@ -117,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
@@ -241,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)
@@ -274,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

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.46'
 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.46
 platform: ruby
 authors:
 - Brett Terpstra
@@ -314,7 +314,6 @@ 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
@@ -330,6 +329,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
@@ -378,6 +378,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`.