howzit 2.1.40 → 2.1.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8f040ba3e136aeb10470c40de3cc8272209d176841686aa242dffee1b9fb33f
-  data.tar.gz: a0e263004a627de3104cb52bb47a04aecacb7eab2389b34819d2ece891331c42
+  metadata.gz: 8916b2ac37cd920db8008fe7a9aa28a80b4c5265083b4b257fb8ea1113938efb
+  data.tar.gz: 9486d6ca52f82ea5059bffd0de58333b82eedfc623d03f6325817caf8c956d4f
 SHA512:
-  metadata.gz: 3d1ce1e58eb28518b0c977f5012436909100cc48fa56dfbf1cedf01389fb02a1ef32823d99b74f065456c07d105f54a1a9dc236a6c73050251ec6180f935af0b
-  data.tar.gz: e9197120a0dd16ca9aefae85f4dde9f09f06efe56d034faf65eee180aeb5fad02fbe158d8a59b17b007622acfaa44da9aa82312159bc488d49c2f61e5a57568c
+  metadata.gz: 5819786618c45538e42f21243102043b1ed408f516b0b946adaa9a2819d0080c2804cba47987f4ba0ed98b21ad7499d42cc825c2f89efb63cc4f6d8013bd743d
+  data.tar.gz: 2a90edf5e41602e1c6fc50ab21a6bfc3531b598f3a5cc381492f284bbb588b2590589fbc23da0f007a021605d46f7246e2908eed89895c175c24838b4755b285

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+### 2.1.42
+
+2026-06-29 06:52
+
+#### NEW
+
+- `includes:` metadata to pull topics from external build note files or project directories (comma-separated paths, optional `[topic | filter]` like templates); directory paths auto-detect the build note; included topics are prefixed by basename; local topics always win on duplicate names.
+
+#### FIXED
+
+- Paged build note output no longer opens with the first line scrolled off screen (pager receives the full buffer via IO.popen instead of starting on partial pipe input).
+
+### 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

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|

data/lib/howzit/buildnote.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Howzit
   # BuildNote Class
   class BuildNote
@@ -12,9 +14,11 @@ module Howzit
     ##
     ## @param      file  [String] The path to the build note file
     ##
-    def initialize(file: nil, meta: nil)
+    def initialize(file: nil, meta: nil, skip_includes: false, included_paths: nil)
       # Track if an explicit file was provided
       @explicit_file = file ? File.expand_path(file) : nil
+      @skip_includes = skip_includes
+      @included_paths = included_paths || Set.new
 
       # Set @note_file if an explicit file was provided, before calling note_file getter
       if file
@@ -653,7 +657,7 @@ module Howzit
     ## @return     [Array] extracted topics
     ##
     def read_template(template, file, subtopics = nil)
-      note = BuildNote.new(file: file, meta: @metadata)
+      note = BuildNote.new(file: file, meta: @metadata, skip_includes: true, included_paths: @included_paths)
 
       template_topics = subtopics.nil? ? note.topics : extract_subtopics(note, subtopics)
       template_topics.map do |topic|
@@ -751,6 +755,24 @@ module Howzit
       files.min
     end
 
+    ##
+    ## Glob a directory for a valid build note filename
+    ##
+    ## @param      dir  [String] Directory to search
+    ##
+    ## @return     [String, nil] Absolute path to build note file
+    ##
+    def glob_note_in(dir)
+      pattern = File.join(File.expand_path(dir), '*.{txt,md,markdown}')
+      files = Dir.glob(pattern).select { |f| File.basename(f).build_note? }
+      return nil if files.empty?
+
+      priority_files = files.select { |f| File.basename(f) =~ /^(buildnotes|howzit)\./i }
+      return priority_files.min unless priority_files.empty?
+
+      files.min
+    end
+
     ##
     ## Search for a valid build note, checking current
     ## directory, git top level directory, and parent
@@ -794,26 +816,117 @@ module Howzit
     end
 
     ##
-    ## Read a list of topics from an included template
+    ## Read a list of topics from included templates and includes: metadata
     ##
-    ## @param      content  [String] The template contents
+    ## @param      content  [String] The build note contents
     ##
     def get_template_topics(content)
       leader = content.split(/^#/)[0].strip
 
-      template_topics = []
+      external_topics = []
 
-      return template_topics if leader.empty?
+      return external_topics if leader.empty?
 
       data = leader.metadata
 
       if data.key?('template')
         templates = data['template'].strip.split(/\s*,\s*/)
 
-        template_topics.concat(gather_templates(templates))
+        external_topics.concat(gather_templates(templates))
       end
 
-      template_topics
+      if data.key?('includes') && !@skip_includes
+        includes = data['includes'].strip.split(/\s*,\s*/)
+
+        external_topics.concat(gather_includes(includes))
+      end
+
+      external_topics
+    end
+
+    ##
+    ## Resolve an includes: metadata entry to a label and build note file path
+    ##
+    ## @param      path_spec  [String] File path, directory, or ~ path
+    ##
+    ## @return     [Array, nil] [label, absolute_file_path] or nil if not found
+    ##
+    def resolve_include_path(path_spec)
+      path = File.expand_path(path_spec.to_s.strip)
+      return nil unless File.exist?(path)
+
+      if File.directory?(path)
+        note_path = glob_note_in(path)
+        return nil unless note_path
+
+        [File.basename(path), File.expand_path(note_path)]
+      elsif File.file?(path)
+        [File.basename(path, File.extname(path)), path]
+      end
+    end
+
+    ##
+    ## Read topics from an external build note referenced by includes: metadata
+    ##
+    def read_include(label, file, subtopics = nil)
+      note = BuildNote.new(file: file, meta: @metadata, skip_includes: true, included_paths: @included_paths)
+      included_topics = subtopics.nil? ? note.topics : extract_subtopics(note, subtopics)
+      included_topics.map do |topic|
+        topic.parent = label
+        topic.content = topic.content.render_template(@metadata)
+        topic.instance_variable_set(:@title, "#{label}:#{topic.title}") unless topic.title.include?(':')
+        topic
+      end
+    end
+
+    ##
+    ## Load topics from includes: metadata paths (comma-separated)
+    ##
+    def gather_includes(includes)
+      included_topics = []
+
+      includes.each do |spec|
+        spec = spec.strip
+        next if spec.empty?
+
+        path_spec, subtopics = detect_subtopics(spec.dup)
+        resolved = resolve_include_path(path_spec)
+        unless resolved
+          Howzit.console.warn "{br}WARNING:{xr} includes: path not found or has no build note: {bw}#{path_spec}{x}".c
+          next
+        end
+
+        label, file = resolved
+        abs_file = File.expand_path(file)
+        main_file = @note_file ? File.expand_path(@note_file) : nil
+
+        if main_file && abs_file == main_file
+          Howzit.console.warn "{br}WARNING:{xr} includes: skipping self-reference: {bw}#{path_spec}{x}".c
+          next
+        end
+
+        if @included_paths.include?(abs_file)
+          Howzit.console.warn "{br}WARNING:{xr} includes: already loaded, skipping: {bw}#{path_spec}{x}".c
+          next
+        end
+
+        @included_paths.add(abs_file)
+        included_topics.concat(read_include(label, abs_file, subtopics))
+      end
+
+      included_topics
+    end
+
+    ##
+    ## Merge external topics (templates, includes) into local topics; local wins on duplicate names
+    ##
+    def merge_external_topics(local_topics, external_topics)
+      external_topics.each do |topic|
+        base = base_topic_name(topic.title)
+        exists_in_local = local_topics.any? { |t| base_topic_name(t.title) == base }
+        local_topics.push(topic) unless exists_in_local
+      end
+      local_topics
     end
 
     # Read in the build notes file and output a hash of
@@ -870,13 +983,7 @@ module Howzit
         topics.push(topic)
       end
 
-      template_topics.each do |topic|
-        # Check against local topics array, not @topics, to avoid filtering out templates
-        # when @topics already has topics (e.g., in stack mode)
-        topic_base = topic.title.sub(/^.+:/, '').strip.downcase
-        exists_in_local = topics.any? { |t| t.title.sub(/^.+:/, '').strip.downcase == topic_base }
-        topics.push(topic) unless exists_in_local
-      end
+      merge_external_topics(topics, template_topics)
 
       topics
     end

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,24 @@ module Howzit
     end
 
     # Get named arguments from title
-    def arguments
+    # 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)
       @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 +59,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 +656,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 +679,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 +834,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 +876,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 +932,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[-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

@@ -123,42 +123,37 @@ module Howzit
           rescue Errno::EPIPE
             # Pipe closed, ignore
           end
-          return
+          return true
         end
 
-        read_io, write_io = IO.pipe
-
-        input = $stdin
-
-        pid = Kernel.fork do
-          write_io.close
-          input.reopen(read_io)
-          read_io.close
-
-          # Wait until we have input before we start the pager
-          IO.select [input]
-
-          pager = which_pager
-
+        pager = which_pager
+        if pager.nil?
           begin
-            exec(pager)
-          rescue SystemCallError => e
-            Howzit.console.error(e)
-            exit 1
+            puts text
+          rescue Errno::EPIPE
+            # Pipe closed, ignore
           end
+          return true
         end
 
-        read_io.close
-        begin
-          write_io.write(text)
+        # Write the full buffer to the pager stdin before closing it. The old
+        # fork + IO.select approach started less as soon as the first bytes
+        # arrived, which could leave the initial viewport scrolled past line 1.
+        IO.popen(pager, 'w') do |io|
+          io.write(text)
         rescue Errno::EPIPE
           # User quit pager before we finished writing, ignore
         end
-        write_io.close
 
-        _, status = Process.waitpid2(pid)
+        Process.last_status.success?
+      end
 
-        status.success?
+      # 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
@@ -180,7 +175,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.40'
+  VERSION = '2.1.42'
 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/cli_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'cli-test'
 
 # https://github.com/thoiberg/cli-test
 describe 'CLI' do

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'includes: metadata' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_includes_test')) }
+  let(:external_dir) { File.expand_path(File.join(temp_dir, 'external_project')) }
+  let(:main_dir) { File.expand_path(File.join(temp_dir, 'main_project')) }
+
+  before do
+    FileUtils.mkdir_p(external_dir)
+    FileUtils.mkdir_p(main_dir)
+
+    File.write(
+      File.join(external_dir, 'buildnotes.md'),
+      <<~NOTE
+        # External Project
+
+        ## Shared Topic
+
+        @run(echo external) External task
+
+        ## External Only
+
+        @run(echo only_external) Only in external
+      NOTE
+    )
+
+    File.write(
+      File.join(main_dir, 'buildnotes.md'),
+      <<~NOTE
+        includes: #{external_dir}
+
+        # Main Project
+
+        ## Shared Topic
+
+        @run(echo local) Local task wins
+
+        ## Main Only
+
+        @run(echo main) Main task
+      NOTE
+    )
+
+    Dir.chdir(main_dir)
+    Howzit.instance_variable_set(:@buildnote, nil)
+    Howzit.options[:stack] = false
+    Howzit.options[:include_upstream] = false
+  end
+
+  after do
+    Dir.chdir(Dir.tmpdir)
+    FileUtils.rm_rf(temp_dir) if Dir.exist?(temp_dir)
+    Howzit.instance_variable_set(:@buildnote, nil)
+  end
+
+  it 'loads topics from an included project directory' do
+    buildnote = Howzit::BuildNote.new
+    external = buildnote.find_topic('External Only')
+
+    expect(external).not_to be_empty
+    expect(external[0].title).to eq('external_project:External Only')
+  end
+
+  it 'prefers local topics over included topics with the same name' do
+    buildnote = Howzit::BuildNote.new
+    matches = buildnote.find_topic('Shared Topic')
+
+    expect(matches.length).to eq(1)
+    expect(matches[0].title).to eq('Shared Topic')
+    expect(matches[0].tasks.first.action).to include('local')
+  end
+
+  it 'includes topics from an explicit file path' do
+    shared_file = File.join(temp_dir, 'shared.md')
+    File.write(
+      shared_file,
+      <<~NOTE
+        # Shared file
+
+        ## From File
+
+        @run(echo from_file) From file
+      NOTE
+    )
+
+    File.write(
+      File.join(main_dir, 'buildnotes.md'),
+      <<~NOTE
+        includes: #{shared_file}
+
+        # Main
+
+        ## Local
+      NOTE
+    )
+
+    Howzit.instance_variable_set(:@buildnote, nil)
+    buildnote = Howzit::BuildNote.new
+    topic = buildnote.find_topic('From File')[0]
+
+    expect(topic.title).to eq('shared:From File')
+  end
+
+  it 'supports subtopic filters like templates' do
+    File.write(
+      File.join(main_dir, 'buildnotes.md'),
+      <<~NOTE
+        includes: #{external_dir}[External Only]
+
+        # Main
+      NOTE
+    )
+
+    Howzit.instance_variable_set(:@buildnote, nil)
+    buildnote = Howzit::BuildNote.new
+
+    expect(buildnote.find_topic('External Only')).not_to be_empty
+    expect(buildnote.find_topic('Shared Topic')).to be_empty
+  end
+end

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

@@ -8,7 +8,6 @@ unless ENV['CI'] == 'true'
 end
 
 require 'howzit'
-require 'cli-test'
 
 RSpec.configure do |c|
   c.expect_with(:rspec) { |e| e.syntax = :expect }
@@ -18,11 +17,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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.40
+  version: 2.1.42
 platform: ruby
 authors:
 - Brett Terpstra
@@ -320,6 +320,7 @@ files:
 - spec/condition_evaluator_spec.rb
 - spec/conditional_blocks_integration_spec.rb
 - spec/conditional_content_spec.rb
+- spec/includes_metadata_spec.rb
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
 - spec/ruby_gem_spec.rb
@@ -331,6 +332,7 @@ 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
@@ -354,7 +356,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.
@@ -364,6 +366,7 @@ test_files:
 - spec/condition_evaluator_spec.rb
 - spec/conditional_blocks_integration_spec.rb
 - spec/conditional_content_spec.rb
+- spec/includes_metadata_spec.rb
 - spec/log_level_spec.rb
 - spec/prompt_spec.rb
 - spec/ruby_gem_spec.rb
@@ -375,5 +378,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