howzit 2.1.39 → 2.1.41

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a934719a022ca2f6713474e797eb1a9662dc884a750c93648d4151506ae41571
-  data.tar.gz: f261e5e733bd2d695cc76ce36e74096d357983301156c6b5b2ce5757aa3637eb
+  metadata.gz: 30837683e82b813fd1fd8ff3e2df3177cbee3c735fc5afb2cb3394f08fb341eb
+  data.tar.gz: 4a0113424a3e36169a0f7a66f31b6dcc3adc24785d9a1a54829db7d9d907c585
 SHA512:
-  metadata.gz: 9d928971e7280979fbfba50eedadedfadcf10ee31a26a4f94169c2cfe987706342fd3b826d781d89f4e3882fd87885e38b070352eae4b5e7a38c7fe06828046c
-  data.tar.gz: 72cc6fcc43c31a8d1827a5e421ebe41f06120d1fb0c428bb0339daa3e5c39b8477e769830fc302552723804033502aea5354b62b2e914a4d2e2a8bca9ac7421b
+  metadata.gz: 1c0245bdb6e801d1efb96e800c04a7ac1177a589e9d25753322bb70a6690ce22b738fdfdc12956aae216565e93ea23b7cdcc14b6f278937e329b116b8d40b5cd
+  data.tar.gz: 986c7c270fc4d8aa21c395fab7a1edaa5669c4a72e6160dede78e45c9c9b6065e69ca47c6c4253b1eae1ec2909d4e31224dee333ba74e6b392e937fe1f7f25ae

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+### 2.1.41
+
+2026-05-10 08:18
+
+#### NEW
+
+- `-z name` and `-n name` in `@if`/`@unless` conditions for shell-style empty and non-empty checks on named and positional variables.
+
+#### IMPROVED
+
+- `Util.show` strips safely when the default external encoding rejects multibyte content (fewer crashes under strict ASCII locale when piping or highlighting).
+
+#### FIXED
+
+- @set_var and @log_level inside @if/@else/@elsif so only the active branch runs; the previous behavior ran every branch and could overwrite variables set in another branch (for example ONLY_RUN set in @if then replaced by @else).
+- Topic title parameters from arguments after `--` so they no longer shift when another topic is parsed first with `@include(...[args])` (CLI positional snapshot kept separate from mutable Howzit.arguments during load).
+
+### 2.1.40
+
+2026-02-04 07:53
+
+#### NEW
+
+- Added a --test-search flag that exits 0 when a search term matches at least one topic and 1 otherwise, with no normal output, allowing shells and scripts to probe for howzit topics programmatically
+
+#### IMPROVED
+
+- Build note processing in test-search mode now short-circuits without auto-creating buildnotes and treats the absence of any note file as a clean non-match instead of an error
+
 ### 2.1.39
 
 2026-01-25 07:39

data/bin/howzit

@@ -9,6 +9,8 @@ Howzit::Color.coloring = $stdout.isatty
 parts = Shellwords.shelljoin(ARGV).split(/ -- /)
 args = parts[0] ? Shellwords.shellsplit(parts[0]) : []
 Howzit.arguments = parts[1] ? Shellwords.shellsplit(parts[1]) : []
+# Immutable snapshot for topic title (param): binding — gather_tasks/@include mutates Howzit.arguments while parsing earlier topics
+Howzit.cli_topic_positional_args = Howzit.arguments&.dup || []
 Howzit.named_arguments = {}
 
 OptionParser.new do |opts|
@@ -31,6 +33,10 @@ OptionParser.new do |opts|
 
   opts.on('-f', '--force', 'Continue executing after an error') { Howzit.options[:force] = true }
 
+  opts.on('--test-search TERM', 'Exit 0 if TERM matches any topic, 1 otherwise (no output)') do |term|
+    Howzit.options[:test_search] = term
+  end
+
   opts.on('-m', '--matching TYPE', MATCHING_OPTIONS,
           'Topics matching type', "(#{MATCHING_OPTIONS.join(', ').sub(/#{Howzit.options[:matching]}/, "*#{Howzit.options[:matching]}")})") do |c|
     Howzit.options[:matching] = c

data/fish/functions/howzit_command_not_found.fish

@@ -0,0 +1,15 @@
+function fish_command_not_found --description "Use howzit topics for unknown commands when available"
+    set cmd $argv[1]
+    set args $argv[2..-1]
+
+    # If a howzit topic matches the command name, run it instead
+    if howzit --test-search $cmd >/dev/null 2>&1
+        howzit -r $cmd $args
+        return $status
+    end
+
+    # Fall back to the default unknown-command message
+    echo "fish: Unknown command '$cmd'"
+    return 127
+end
+

data/lib/howzit/buildnote.rb

@@ -1126,6 +1126,15 @@ module Howzit
         Howzit.multi_topic_run = false
       end
 
+      # Test-search mode: do not auto-create a build note; just check for a match
+      if Howzit.options[:test_search]
+        term = Howzit.options[:test_search]
+        # If no note file can be found at all, treat as no match
+        Process.exit(1) unless note_file
+        matches = find_topic(term)
+        Process.exit(matches.any? ? 0 : 1)
+      end
+
       unless note_file
         Process.exit 0 if Howzit.options[:list_runnable_titles] || Howzit.options[:list_topic_titles]
 

data/lib/howzit/condition_evaluator.rb

@@ -35,6 +35,17 @@ module Howzit
       ## Evaluate a single condition (without negation)
       ##
       def evaluate_condition(condition, context)
+        # Shell-style empty / non-empty tests (bash -z / -n)
+        if (match = condition.match(/^-z\s+(.+)$/i))
+          name = match[1].strip
+          val = get_value(name, context)
+          return val.nil? || val.to_s.strip.empty?
+        elsif (match = condition.match(/^-n\s+(.+)$/i))
+          name = match[1].strip
+          val = get_value(name, context)
+          return !val.nil? && !val.to_s.strip.empty?
+        end
+
         # Handle special conditions FIRST to avoid false matches with comparison patterns
         # Check file contents before other patterns since it has arguments and operators
         if condition =~ /^file\s+contents\s+(.+?)\s+(\*\*=|\*=|\^=|\$=|==|!=|=~)\s*(.+)$/i

data/lib/howzit/topic.rb

@@ -25,7 +25,7 @@ module Howzit
       @named_args = {}
       @metadata = metadata
       @source_file = source_file
-      arguments
+      arguments(from_cli_snapshot: true)
 
       @directives = parse_directives_with_conditionals
       @tasks = gather_tasks
@@ -33,10 +33,23 @@ module Howzit
     end
 
     # Get named arguments from title
-    def arguments
+    # from_cli_snapshot: use Howzit.cli_topic_positional_args (set once from argv after ` -- `) so earlier topics' gather_tasks
+    # cannot clobber positional binding. Re-entrant calls (e.g. @include with [a,b]) pass false to use live Howzit.arguments.
+    def arguments(from_cli_snapshot: false)
       @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 || []
+                     else
+                       Howzit.cli_topic_positional_args
+                     end
+                   else
+                     Howzit.arguments || []
+                   end
+
       a = @title.match(/\((?<args>.*?)\) *$/)
       args = a['args'].split(/ *, */).each(&:strip)
 
@@ -45,8 +58,8 @@ module Howzit
         # Store original definition for display purposes
         @arg_definitions << (default ? "#{arg_name}:#{default}" : arg_name)
 
-        @named_args[arg_name] = if Howzit.arguments && Howzit.arguments.count >= idx + 1
-                                  Howzit.arguments[idx]
+        @named_args[arg_name] = if positional && positional.count >= idx + 1
+                                  positional[idx]
                                 else
                                   default
                                 end
@@ -642,6 +655,7 @@ module Howzit
         if line =~ /^@log_level\s*\(([^)]+)\)\s*$/i
           log_level = Regexp.last_match(1).strip
           conditional_path = conditional_stack.dup
+          conditional_path << current_branch_index if current_branch_index
           directives << Howzit::Directive.new(
             type: :log_level,
             log_level_value: log_level,
@@ -664,6 +678,7 @@ module Howzit
               # Remove quotes from value if present (handles both single and double quotes)
               var_value = Regexp.last_match(1) if var_value =~ /^["'](.+)["']$/
               conditional_path = conditional_stack.dup
+              conditional_path << current_branch_index if current_branch_index
               directives << Howzit::Directive.new(
                 type: :set_var,
                 var_name: var_name,
@@ -818,12 +833,16 @@ module Howzit
 
         # Handle @log_level directive (before task check)
         if directive.log_level?
+          next unless directive_in_active_branch?(directive, conditional_state)
+
           current_log_level = directive.log_level_value
           next
         end
 
         # Handle @set_var directive (before task check)
         if directive.set_var?
+          next unless directive_in_active_branch?(directive, conditional_state)
+
           # Set the variable in named_arguments
           Howzit.named_arguments ||= {}
           value = directive.var_value
@@ -856,34 +875,7 @@ module Howzit
         # Handle task directives
         next unless directive.task?
 
-        # Check if all parent conditionals are true
-        should_execute = true
-
-        # If path ends with an @elsif/@else, skip the parent @if index
-        # (the index right before the elsif/else in the path)
-        path_to_check = directive.conditional_path.dup
-        if path_to_check.length >= 2
-          last_idx = path_to_check.last
-          last_state = conditional_state[last_idx]
-          if last_state && %w[elsif else].include?(last_state[:directive_type])
-            # Skip the parent @if index (the one before the elsif/else)
-            parent_if_idx = path_to_check[path_to_check.length - 2]
-            parent_if_state = conditional_state[parent_if_idx]
-            if parent_if_state && %w[if unless].include?(parent_if_state[:directive_type])
-              path_to_check.delete(parent_if_idx)
-            end
-          end
-        end
-
-        path_to_check.each do |cond_idx|
-          cond_state = conditional_state[cond_idx]
-          if cond_state.nil? || !cond_state[:evaluated] || !cond_state[:result]
-            should_execute = false
-            break
-          end
-        end
-
-        next unless should_execute
+        next unless directive_in_active_branch?(directive, conditional_state)
 
         # Convert directive to task
         task = directive.to_task(self, current_log_level: current_log_level)
@@ -939,6 +931,38 @@ module Howzit
       output
     end
 
+    ##
+    ## Whether a directive nested under @if/@unless/@elsif/@else should run (same rules as tasks).
+    ##
+    def directive_in_active_branch?(directive, conditional_state)
+      path = directive.conditional_path || []
+      return true if path.empty?
+
+      should_execute = true
+      path_to_check = path.dup
+      if path_to_check.length >= 2
+        last_idx = path_to_check.last
+        last_state = conditional_state[last_idx]
+        if last_state && %w[elsif else].include?(last_state[:directive_type])
+          parent_if_idx = path_to_check[path_to_check.length - 2]
+          parent_if_state = conditional_state[parent_if_idx]
+          if parent_if_state && %w[if unless].include?(parent_if_state[:directive_type])
+            path_to_check.delete(parent_if_idx)
+          end
+        end
+      end
+
+      path_to_check.each do |cond_idx|
+        cond_state = conditional_state[cond_idx]
+        if cond_state.nil? || !cond_state[:evaluated] || !cond_state[:result]
+          should_execute = false
+          break
+        end
+      end
+
+      should_execute
+    end
+
     ##
     ## Find the index of the matching @if/@unless for an @elsif/@else/@end
     ##

data/lib/howzit/util.rb

@@ -161,6 +161,14 @@ module Howzit
         status.success?
       end
 
+      # Strip safely when external encoding rejects multibyte content (e.g. US-ASCII default).
+      def safe_strip(str)
+        s = str.to_s
+        s.strip
+      rescue Encoding::CompatibilityError
+        s.encode('UTF-8', invalid: :replace, undef: :replace).strip
+      end
+
       # print output to terminal
       def show(string, opts = {})
         options = {
@@ -180,7 +188,10 @@ module Howzit
           pipes = "|#{hl}" if hl
         end
 
-        output = `echo #{Shellwords.escape(string.strip)}#{pipes}`.strip
+        string = safe_strip(string)
+
+        raw_output = `echo #{Shellwords.escape(string)}#{pipes}`
+        output = safe_strip(raw_output)
 
         if options[:paginate] && Howzit.options[:paginate]
           page(output)

data/lib/howzit/version.rb

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

data/lib/howzit.rb

@@ -60,7 +60,7 @@ require 'tty/box'
 # Main module for howzit
 module Howzit
   class << self
-    attr_accessor :arguments, :named_arguments, :cli_args, :run_log, :multi_topic_run
+    attr_accessor :arguments, :named_arguments, :cli_topic_positional_args, :cli_args, :run_log, :multi_topic_run
 
     ##
     ## Holds a Configuration object with methods and a @settings hash

data/spec/condition_evaluator_spec.rb

@@ -122,6 +122,30 @@ describe Howzit::ConditionEvaluator do
         expect(described_class.evaluate('${env} == "production"', {})).to be true
         expect(described_class.evaluate('${var} == "other"', {})).to be false
       end
+
+      it 'evaluates -z (empty) for named arguments' do
+        Howzit.named_arguments = { 'option' => '', other: 'x' }
+        expect(described_class.evaluate('-z option', {})).to be true
+        expect(described_class.evaluate('-z other', {})).to be false
+      end
+
+      it 'evaluates -n (non-empty) for named arguments' do
+        Howzit.named_arguments = { 'option' => '', other: 'x' }
+        expect(described_class.evaluate('-n option', {})).to be false
+        expect(described_class.evaluate('-n other', {})).to be true
+      end
+
+      it 'treats undefined named argument as empty for -z / -n' do
+        Howzit.named_arguments = {}
+        expect(described_class.evaluate('-z missing', {})).to be true
+        expect(described_class.evaluate('-n missing', {})).to be false
+      end
+
+      it 'supports not -z and not -n' do
+        Howzit.named_arguments = { opt: 'yes' }
+        expect(described_class.evaluate('not -z opt', {})).to be true
+        expect(described_class.evaluate('not -n opt', {})).to be false
+      end
     end
 
     context 'with metadata' do

data/spec/sequential_conditional_spec.rb

@@ -317,4 +317,53 @@ describe 'Sequential Conditional Evaluation' do
       expect(Howzit.named_arguments['ALL']).to eq('123')
     end
   end
+
+  describe '@set_var under @if/@else' do
+    let(:branch_note) do
+      <<~EONOTE
+        # Test
+
+        ## Branch Topic (flag)
+
+        @if -n flag
+        @set_var(RESULT, "yes")
+        @else
+        @set_var(RESULT, "no")
+        @end
+
+        ```run Echo
+        #!/bin/bash
+        echo ok
+        ```
+      EONOTE
+    end
+
+    it 'only runs @set_var from the active branch when @if is true' do
+      File.open('builda.md', 'w') { |f| f.puts branch_note }
+      Howzit.arguments = ['present']
+      Howzit.cli_topic_positional_args = ['present']
+      Howzit.named_arguments = {}
+      Howzit.instance_variable_set(:@buildnote, nil)
+      topic = Howzit.buildnote('builda.md').find_topic('Branch Topic')[0]
+      allow(Howzit::Prompt).to receive(:yn).and_return(true)
+
+      topic.run
+
+      expect(Howzit.named_arguments['RESULT']).to eq('yes')
+    end
+
+    it 'only runs @set_var from the active branch when @else is taken' do
+      File.open('builda.md', 'w') { |f| f.puts branch_note }
+      Howzit.arguments = []
+      Howzit.cli_topic_positional_args = []
+      Howzit.named_arguments = {}
+      Howzit.instance_variable_set(:@buildnote, nil)
+      topic = Howzit.buildnote('builda.md').find_topic('Branch Topic')[0]
+      allow(Howzit::Prompt).to receive(:yn).and_return(true)
+
+      topic.run
+
+      expect(Howzit.named_arguments['RESULT']).to eq('no')
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -18,11 +18,19 @@ RSpec.configure do |c|
     save_buildnote
     # Reset buildnote cache to ensure fresh instance with updated file
     Howzit.instance_variable_set(:@buildnote, nil)
+    Howzit.arguments = []
+    Howzit.cli_topic_positional_args = nil
+    Howzit.named_arguments = {}
     Howzit.options[:include_upstream] = false
     Howzit.options[:stack] = false
     Howzit.options[:default] = true
     Howzit.options[:matching] = 'partial'
     Howzit.options[:multiple_matches] = 'choose'
+    # Point singleton at test fixture (repo may also contain buildnotes.md, etc.)
+    Howzit.instance_variable_set(
+      :@buildnote,
+      Howzit::BuildNote.new(file: File.expand_path('builda.md'))
+    )
     @hz = Howzit.buildnote
   end
 

data/spec/topic_positional_snapshot_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tempfile'
+
+describe 'Topic title positional args vs gather_tasks' do
+  it 'uses CLI positional snapshot so a prior topic @include […] does not shift later topic params' do
+    Howzit.arguments = ['from_cli']
+    Howzit.cli_topic_positional_args = ['from_cli']
+
+    Tempfile.create(['howzit-pos', '.md']) do |f|
+      f.write(<<~MD)
+        defined: snap
+
+        # Note
+
+        ## First Topic
+
+        @include(DoesNotNeedToExist[y])
+
+        ## Widget Topic (only:falafel)
+
+        ok
+      MD
+      f.flush
+
+      note = Howzit::BuildNote.new(file: f.path)
+      widget = note.topics.find { |t| t.title == 'Widget Topic' }
+      expect(widget).not_to be_nil
+      expect(widget.named_args['only']).to eq('from_cli')
+    end
+  end
+end

data/spec/topic_spec.rb

@@ -24,7 +24,7 @@ end
 
 describe Howzit::Topic do
   subject(:topic) do
-    bn = Howzit.buildnote
+    bn = Howzit.buildnote('builda.md')
     bn.find_topic('Topic Balogna')[0]
   end
 

data/zsh/howzit-command-not-found.zsh

@@ -0,0 +1,22 @@
+# howzit command-not-found handler for zsh
+#
+# When an unknown command is entered, this handler will check to see
+# if there is a howzit topic matching the command name. If so, it
+# runs `howzit -r <command> [args...]`. Otherwise, it falls back to
+# the standard "command not found" behavior.
+
+command_not_found_handler() {
+  local cmd="$1"
+  shift
+
+  # If a howzit topic matches the command name, run it instead
+  if howzit --test-search "$cmd" >/dev/null 2>&1; then
+    howzit -r "$cmd" "$@"
+    return $?
+  fi
+
+  # Fall back to the default unknown-command message
+  print "zsh: command not found: $cmd" >&2
+  return 127
+}
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.39
+  version: 2.1.41
 platform: ruby
 authors:
 - Brett Terpstra
@@ -294,6 +294,7 @@ files:
 - fish/completions/fisher.fish
 - fish/completions/howzit.fish
 - fish/functions/bld.fish
+- fish/functions/howzit_command_not_found.fish
 - howzit.gemspec
 - lib/howzit.rb
 - lib/howzit/buildnote.rb
@@ -330,10 +331,12 @@ files:
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
 - spec/task_spec.rb
+- spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb
 - spec/util_spec.rb
 - src/_README.md
 - update_readmes.rb
+- zsh/howzit-command-not-found.zsh
 homepage: https://github.com/ttscoff/howzit
 licenses:
 - MIT
@@ -352,7 +355,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Provides a way to access Markdown project notes by topic with query capabilities
   and the ability to execute the tasks it describes.
@@ -373,5 +376,6 @@ test_files:
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
 - spec/task_spec.rb
+- spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb
 - spec/util_spec.rb