howzit 2.1.41 → 2.1.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30837683e82b813fd1fd8ff3e2df3177cbee3c735fc5afb2cb3394f08fb341eb
-  data.tar.gz: 4a0113424a3e36169a0f7a66f31b6dcc3adc24785d9a1a54829db7d9d907c585
+  metadata.gz: 881188642b99f4be83a7697440251ec8890e6d847468c3984a72183939196857
+  data.tar.gz: c622b23318a075aa277a0a197e1ec93d8023e52e99018557e7eb6f8309c76927
 SHA512:
-  metadata.gz: 1c0245bdb6e801d1efb96e800c04a7ac1177a589e9d25753322bb70a6690ce22b738fdfdc12956aae216565e93ea23b7cdcc14b6f278937e329b116b8d40b5cd
-  data.tar.gz: 986c7c270fc4d8aa21c395fab7a1edaa5669c4a72e6160dede78e45c9c9b6065e69ca47c6c4253b1eae1ec2909d4e31224dee333ba74e6b392e937fe1f7f25ae
+  metadata.gz: 219ae789410d1ec44619f3bfb00b7f8b539a33632e9b9d9e778f384205e03c653efa83a7a090d469dd769a2cdda53ae7026e40b495363879e59f24be38da09ae
+  data.tar.gz: d0c1dd2d03ab11923e93440fb9f04bfdfb0292d63522fd21483a38a7d2ca31c691dc64e4a894063944b586ef1b2af66fd8a4bd55ea132ce743b6e69e7fd812db

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+### 2.1.44
+
+2026-09-27 11:38
+
+#### CHANGED
+
+- **Task failures** in a parent or subtopic stop the remaining subtopics from running unless --force is used.
+- **@after blocks** on a parent are shown after the parent and all of its subtopics finish.
+
+#### NEW
+
+- **Subtopics**: deeper headers (### under ##, #### under ###, etc.) are now nested under the preceding shallower topic.
+- **Displaying a parent topic** shows all of its subtopics after it, with subtopic headers drawn in a lighter style (cyan title, dotted rule).
+- **Running a parent topic** runs its own tasks, then every subtopic's tasks in order (depth-first), with a single combined "Ran N tasks" summary.
+
+#### IMPROVED
+
+- **Showing all topics** (howzit with no arguments, or howzit -r with no default) only outputs top-level topics so subtopics are not repeated.
+- **Selecting both a parent and its subtopic** outputs/runs the subtopic only once, as part of the parent.
+- **Topic lists** (howzit -l and the runnable topics list) indent subtopics under their parents.
+- **@include(Topic)** on a parent runs the parent and all of its subtopics, and task counts in include notes and menus now count subtopic tasks.
+
+#### FIXED
+
+- **Parent topics with no tasks of their own** no longer warn "No @directive found" when their subtopics contain tasks.
+
+### 2.1.43
+
+2026-09-27 11:35
+
+#### CHANGED
+
+- **Task failures** in a parent or subtopic stop the remaining subtopics from running unless --force is used.
+- **@after blocks** on a parent are shown after the parent and all of its subtopics finish.
+
+#### NEW
+
+- **Subtopics**: deeper headers (### under ##, #### under ###, etc.) are now nested under the preceding shallower topic.
+- **Displaying a parent topic** shows all of its subtopics after it, with subtopic headers drawn in a lighter style (cyan title, dotted rule).
+- **Running a parent topic** runs its own tasks, then every subtopic's tasks in order (depth-first), with a single combined "Ran N tasks" summary.
+
+#### IMPROVED
+
+- **Showing all topics** (howzit with no arguments, or howzit -r with no default) only outputs top-level topics so subtopics are not repeated.
+- **Selecting both a parent and its subtopic** outputs/runs the subtopic only once, as part of the parent.
+- **Topic lists** (howzit -l and the runnable topics list) indent subtopics under their parents.
+- **@include(Topic)** on a parent runs the parent and all of its subtopics, and task counts in include notes and menus now count subtopic tasks.
+
+#### FIXED
+
+- **Parent topics with no tasks of their own** no longer warn "No @directive found" when their subtopics contain tasks.
+
+### 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

data/Rakefile

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# rspec, rubocop plugins, and the .rubocop_todo.yml cops depend on the locked bundle
+exec('bundle', 'exec', 'rake', *ARGV) unless ENV['BUNDLE_GEMFILE']
+
 # require 'bump/tasks'
 require 'English'
 require 'bundler/gem_tasks'

data/howzit.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.6.0'
 
-  spec.add_development_dependency 'bundler', '~> 2.2'
+  spec.add_development_dependency 'bundler', '>= 2.2'
   spec.add_development_dependency 'rake', '~> 13.0'
 
   spec.add_development_dependency 'guard', '~> 2.11'

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
@@ -165,11 +169,37 @@ module Howzit
       output = []
       output.push("{bg}Topics:{x}\n".c)
       @topics.each do |topic|
-        output.push("- {bw}#{topic.title}{x}".c)
+        output.push("#{subtopic_indent(topic)}- {bw}#{topic.title}{x}".c)
       end
       output.join("\n")
     end
 
+    ##
+    ## Indentation for a topic in list output, based on
+    ## how many of its parent topics are in the list
+    ##
+    ## @param      topic  [Topic] The topic
+    ##
+    ## @return     [String] leading whitespace
+    ##
+    def subtopic_indent(topic)
+      '  ' * topic.ancestors.count { |parent| @topics.any? { |t| t.equal?(parent) } }
+    end
+
+    ##
+    ## Topics that aren't nested under another topic in
+    ## the build note (subtopics are output with their parent)
+    ##
+    ## @param      topics  [Array] Topics to filter, defaults to all topics
+    ##
+    ## @return     [Array] array of Topics
+    ##
+    def top_level_topics(topics = @topics)
+      topics.reject do |topic|
+        topic.ancestors.any? { |parent| topics.any? { |t| t.equal?(parent) } }
+      end
+    end
+
     ##
     ## Return an array of topic titles
     ##
@@ -200,7 +230,7 @@ module Howzit
     def list_runnable_completions
       output = []
       @topics.each do |topic|
-        next unless topic.tasks.count.positive?
+        next unless topic.all_tasks.any?
 
         output.push(topic.title)
       end
@@ -218,11 +248,10 @@ module Howzit
       output.push(%({bg}"Runnable" Topics:{x}\n).c)
 
       find_topic(Howzit.options[:for_topic]).each do |topic|
-        s_out = []
+        next if topic.all_tasks.empty?
 
-        topic.tasks.each { |task| s_out.push(task.to_list) }
-
-        next if s_out.empty?
+        indent = subtopic_indent(topic)
+        s_out = topic.tasks.map { |task| "#{indent}#{task.to_list}" }
 
         title = topic.title
         # Show argument definitions with colorized formatting
@@ -231,8 +260,8 @@ module Howzit
           title += " {l}({x}#{formatted_args}{l}){x}".c
         end
 
-        output.push("- {g}#{title}{x}".c)
-        output.push(s_out.join("\n"))
+        output.push("#{indent}- {g}#{title}{x}".c)
+        output.push(s_out.join("\n")) unless s_out.empty?
       end
 
       output.join("\n")
@@ -653,7 +682,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 +780,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 +841,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
@@ -843,11 +981,13 @@ module Howzit
 
       template_topics = get_template_topics(help)
 
-      split = help.split(/^##+/)
-      split.slice!(0)
-      split.each do |sect|
-        next if sect.strip.empty?
+      sections = help.split(/^(##+)/)
+      sections.shift
+      parent_stack = []
+      sections.each_slice(2) do |marks, sect|
+        next if sect.nil? || sect.strip.empty?
 
+        level = marks.length
         lines = sect.split(/\n/)
         title = lines.slice!(0).strip
         prefix = ''
@@ -865,18 +1005,17 @@ module Howzit
         # Ensure source_file is always an absolute path
         source_file = path || note_file
         source_file = File.expand_path(source_file) if source_file
-        topic = Topic.new(title, prefix + lines.join("\n").strip.render_template(@metadata), @metadata, source_file: source_file)
+        topic = Topic.new(title, prefix + lines.join("\n").strip.render_template(@metadata), @metadata,
+                          source_file: source_file, level: level)
+
+        parent_stack.pop while parent_stack.any? && parent_stack.last.level >= level
+        parent_stack.last&.add_subtopic(topic)
+        parent_stack.push(topic)
 
         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
@@ -1266,13 +1405,13 @@ module Howzit
           process_default_metadata(output)
         else
           Howzit.run_log = []
-          Howzit.multi_topic_run = topics.length > 1
-          topics.each { |k| output.push(process_topic(k, false, single: false)) }
+          Howzit.multi_topic_run = top_level_topics.length > 1
+          top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
           finalize_output(output)
         end
       else
         # Show all topics
-        topics.each { |k| output.push(process_topic(k, false, single: false)) }
+        top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
         finalize_output(output)
       end
     end
@@ -1418,9 +1557,12 @@ module Howzit
           end
         end
         topic_matches.compact! # Remove any nil values from failed matches
-        topic_matches.each { |topic_match| output.push(process_topic(topic_match, Howzit.options[:run], single: true)) }
+        # A matched subtopic is already output/run with its matched parent
+        top_level_topics(topic_matches).each do |topic_match|
+          output.push(process_topic(topic_match, Howzit.options[:run], single: true))
+        end
       else
-        topics.each { |k| output.push(process_topic(k, false, single: false)) }
+        top_level_topics.each { |k| output.push(process_topic(k, false, single: false)) }
       end
 
       finalize_output(output)

data/lib/howzit/task.rb

@@ -152,9 +152,9 @@ module Howzit
 
       Howzit.console.info("#{@prefix}{by}Running tasks from {bw}#{matches[0].title}{x}".c)
       output.concat(matches[0].run(nested: true))
-      Howzit.console.info("{by}End include: #{matches[0].tasks.count} tasks{x}".c)
+      Howzit.console.info("{by}End include: #{matches[0].all_tasks.count} tasks{x}".c)
       @last_status = nil
-      [output, matches[0].tasks.count]
+      [output, matches[0].all_tasks.count]
     end
 
     ##

data/lib/howzit/topic.rb

@@ -5,9 +5,10 @@ module Howzit
   class Topic
     attr_writer :parent
 
-    attr_accessor :content
+    attr_accessor :content, :parent_topic
 
-    attr_reader :title, :tasks, :prereqs, :postreqs, :results, :named_args, :directives, :arg_definitions, :source_file
+    attr_reader :title, :tasks, :prereqs, :postreqs, :results, :named_args, :directives, :arg_definitions, :source_file,
+                :level, :subtopics
 
     ##
     ## Initialize a topic object
@@ -16,11 +17,15 @@ module Howzit
     ## @param      content     [String] The raw topic content
     ## @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.)
     ##
-    def initialize(title, content, metadata = nil, source_file: nil)
+    def initialize(title, content, metadata = nil, source_file: nil, level: 2)
       @title = title
       @content = content
       @parent = nil
+      @parent_topic = nil
+      @subtopics = []
+      @level = level
       @nest_level = 0
       @named_args = {}
       @metadata = metadata
@@ -32,9 +37,44 @@ module Howzit
       @results = { total: 0, success: 0, errors: 0, message: ''.c }
     end
 
+    ##
+    ## Nest a topic under this one (a deeper header following this topic)
+    ##
+    ## @param      topic  [Topic] The subtopic
+    ##
+    def add_subtopic(topic)
+      topic.parent_topic = self
+      @subtopics << topic
+    end
+
+    ##
+    ## Tasks from this topic and all nested subtopics, in run order
+    ##
+    ## @return     [Array] Array of Task objects
+    ##
+    def all_tasks
+      @tasks + @subtopics.flat_map(&:all_tasks)
+    end
+
+    ##
+    ## Parent topics from nearest to outermost
+    ##
+    ## @return     [Array] Array of Topic objects
+    ##
+    def ancestors
+      list = []
+      node = @parent_topic
+      while node
+        list << node
+        node = node.parent_topic
+      end
+      list
+    end
+
     # Get named arguments from title
-    # 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.
+    # 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 =~ /\(.*?\) *$/
@@ -79,7 +119,7 @@ module Howzit
 
     def ask_task(task)
       note = if task.type == :include
-               task_count = Howzit.buildnote.find_topic(task.action)[0].tasks.count
+               task_count = Howzit.buildnote.find_topic(task.action)[0].all_tasks.count
                " (#{task_count} tasks)"
              else
                ''
@@ -94,80 +134,129 @@ module Howzit
       60
     end
 
-    # Handle run command, execute directives in topic
-    def run(nested: false)
+    ##
+    ## Handle run command, execute directives in topic, then in each subtopic
+    ##
+    ## @param      nested       [Boolean] Suppress the summary message (topic is being included)
+    ## @param      as_subtopic  [Boolean] Topic is being run as part of a parent topic
+    ##
+    ## @return     [Array] output lines
+    ##
+    def run(nested: false, as_subtopic: false)
+      @results = { total: 0, success: 0, errors: 0, message: ''.c }
       output = []
-
       cols = check_cols
 
-      # Use sequential processing if we have directives with conditionals
-      if @directives && @directives.any?(&:conditional?)
-        return run_sequential(nested: nested, output: output, cols: cols)
+      confirm_prereqs(cols) if !@prereqs.empty? && (all_tasks.any? || sequential?)
+
+      if sequential?
+        run_sequential(output: output)
+      elsif @tasks.any?
+        run_tasks(output)
+      elsif all_tasks.empty? && !as_subtopic && !directives?
+        Howzit.console.warn "{r}--run: No {br}@directive{xr} found in {bw}#{@title}{x}".c
       end
 
-      # Fall back to old behavior for backward compatibility
-      # Note: @set_var directives are already processed in gather_tasks for non-sequential path
-      # This section is kept for backward compatibility but shouldn't be needed
+      run_subtopics(output) unless halted?
 
-      if @tasks.count.positive?
-        unless @prereqs.empty?
-          begin
-            puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
-          rescue Errno::EPIPE
-            # Pipe closed, ignore
-          end
-          res = Prompt.yn('Have the above prerequisites been met?', default: true)
-          Process.exit 1 unless res
+      if @results[:total].positive? || (all_tasks.any? && !sequential?)
+        @results[:message] += results_message
+        output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
+      end
 
-        end
+      show_postreqs(cols)
 
-        @tasks.each do |task|
-          next if (task.optional || Howzit.options[:ask]) && !ask_task(task)
+      output
+    end
 
-          run_output, total, success = task.run
+    ##
+    ## Whether the topic contains conditional directives and must be run sequentially
+    ##
+    def sequential?
+      @directives&.any?(&:conditional?) || false
+    end
 
-          output.concat(run_output)
-          @results[:total] += total
+    ##
+    ## Whether this topic or any subtopic contains directives,
+    ## including non-task directives like @set_var and @log_level
+    ##
+    def directives?
+      @directives&.any? || @subtopics.any?(&:directives?)
+    end
 
-          if success
-            @results[:success] += total
-          else
-            Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
+    def halted?
+      @results[:errors].positive? && !Howzit.options[:force]
+    end
 
-            @results[:errors] += total
+    def confirm_prereqs(cols)
+      begin
+        puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
+      rescue Errno::EPIPE
+        # Pipe closed, ignore
+      end
+      res = Prompt.yn('Have the above prerequisites been met?', default: true)
+      Process.exit 1 unless res
+    end
 
-            break unless Howzit.options[:force]
-          end
+    def show_postreqs(cols)
+      return if @postreqs.empty?
 
-          log_task_result(task, success)
-        end
+      # Apply variable substitution to postreqs content, then wrap each line individually to preserve structure
+      postreqs_content = @postreqs.join("\n\n").render_arguments
+      wrapped_content = postreqs_content.split(/\n/).map { |line| line.wrap(cols - 4) }.join("\n")
+      puts TTY::Box.frame("{bw}#{wrapped_content}{x}".c, width: cols)
+    rescue Errno::EPIPE
+      # Pipe closed, ignore
+    end
 
-        total = "{bw}#{@results[:total]}{by} #{@results[:total] == 1 ? 'task' : 'tasks'}".c
-        errors = "{bw}#{@results[:errors]}{by} #{@results[:errors] == 1 ? 'error' : 'errors'}".c
-        @results[:message] += if @results[:errors].zero?
-                                "{bg}\u{2713} {by}Ran #{total}{x}".c
-                              elsif Howzit.options[:force]
-                                "{br}\u{2715} {by}Completed #{total} with #{errors}{x}".c
-                              else
-                                "{br}\u{2715} {by}Ran #{total}, terminated due to error{x}".c
-                              end
+    def results_message
+      total = "{bw}#{@results[:total]}{by} #{@results[:total] == 1 ? 'task' : 'tasks'}".c
+      errors = "{bw}#{@results[:errors]}{by} #{@results[:errors] == 1 ? 'error' : 'errors'}".c
+      if @results[:errors].zero?
+        "{bg}\u{2713} {by}Ran #{total}{x}".c
+      elsif Howzit.options[:force]
+        "{br}\u{2715} {by}Completed #{total} with #{errors}{x}".c
       else
-        Howzit.console.warn "{r}--run: No {br}@directive{xr} found in {bw}#{@title}{x}".c
+        "{br}\u{2715} {by}Ran #{total}, terminated due to error{x}".c
       end
+    end
+
+    ##
+    ## Run tasks without conditional evaluation
+    ##
+    def run_tasks(output)
+      @tasks.each do |task|
+        next if (task.optional || Howzit.options[:ask]) && !ask_task(task)
 
-      output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
+        run_output, total, success = task.run
+
+        output.concat(run_output)
+        @results[:total] += total
+
+        if success
+          @results[:success] += total
+        else
+          Howzit.console.warn %({bw}\u{2297} {br}Error running task {bw}"#{task.title}"{x}).c
 
-      unless @postreqs.empty?
-        begin
-          # Apply variable substitution to postreqs content, then wrap each line individually to preserve structure
-          postreqs_content = @postreqs.join("\n\n").render_arguments
-          wrapped_content = postreqs_content.split(/\n/).map { |line| line.wrap(cols - 4) }.join("\n")
-          puts TTY::Box.frame("{bw}#{wrapped_content}{x}".c, width: cols)
-        rescue Errno::EPIPE
-          # Pipe closed, ignore
+          @results[:errors] += total
+
+          break unless Howzit.options[:force]
         end
+
+        log_task_result(task, success)
       end
+      output
+    end
 
+    ##
+    ## Run each subtopic in order, adding its results to this topic's
+    ##
+    def run_subtopics(output)
+      @subtopics.each do |sub|
+        output.concat(sub.run(nested: true, as_subtopic: true))
+        %i[total success errors].each { |key| @results[key] += sub.results[key] }
+        break if halted?
+      end
       output
     end
 
@@ -177,7 +266,7 @@ module Howzit
     end
 
     def colored_option(color, topic, keys)
-      if topic.tasks.empty?
+      if topic.all_tasks.empty?
         ''
       else
         optional = keys[:optional] =~ /[?!]+/ ? true : false
@@ -301,7 +390,8 @@ module Howzit
           formatted_args = @arg_definitions.map { |arg| format_arg_definition(arg) }.join('{l}, '.c)
           header_title += " {l}({x}#{formatted_args}{l}){x}".c
         end
-        output.push(header_title.format_header)
+        header_opts = opt[:subtopic] ? { color: '{bc}', hr: "\u{2508}" } : {}
+        output.push(header_title.format_header(header_opts))
         output.push('')
       end
       # Process conditional blocks first
@@ -332,6 +422,8 @@ module Howzit
       end
       Howzit.named_arguments = @named_args
       output.push('')
+      @subtopics.each { |sub| output.concat(sub.print_out(opt.merge(header: true, subtopic: true))) }
+      output
     end
 
     ##
@@ -726,7 +818,7 @@ module Howzit
     ##
     ## Run directives sequentially with conditional re-evaluation
     ##
-    def run_sequential(nested: false, output: [], cols: 80)
+    def run_sequential(output: [])
       # Initialize conditional state
       conditional_state = {} # { index => { evaluated: bool, result: bool, matched_chain: bool } }
       directive_index = 0
@@ -736,16 +828,6 @@ module Howzit
       Howzit.named_arguments ||= {}
       Howzit.named_arguments.merge!(@named_args) if @named_args
 
-      unless @prereqs.empty?
-        begin
-          puts TTY::Box.frame("{by}#{@prereqs.join("\n\n").wrap(cols - 4)}{x}".c, width: cols)
-        rescue Errno::EPIPE
-          # Pipe closed, ignore
-        end
-        res = Prompt.yn('Have the above prerequisites been met?', default: true)
-        Process.exit 1 unless res
-      end
-
       # Process directives sequentially
       while directive_index < @directives.length
         directive = @directives[directive_index]
@@ -904,30 +986,6 @@ module Howzit
         re_evaluate_conditionals(conditional_state, directive_index - 1, context)
       end
 
-      if @results[:total].positive?
-        total = "{bw}#{@results[:total]}{by} #{@results[:total] == 1 ? 'task' : 'tasks'}".c
-        errors = "{bw}#{@results[:errors]}{by} #{@results[:errors] == 1 ? 'error' : 'errors'}".c
-        @results[:message] += if @results[:errors].zero?
-                                "{bg}\u{2713} {by}Ran #{total}{x}".c
-                              elsif Howzit.options[:force]
-                                "{br}\u{2715} {by}Completed #{total} with #{errors}{x}".c
-                              else
-                                "{br}\u{2715} {by}Ran #{total}, terminated due to error{x}".c
-                              end
-        output.push(@results[:message]) if Howzit.options[:log_level] < 2 && !nested && !Howzit.options[:run]
-      end
-
-      unless @postreqs.empty?
-        begin
-          # Apply variable substitution to postreqs content, then wrap each line individually to preserve structure
-          postreqs_content = @postreqs.join("\n\n").render_arguments
-          wrapped_content = postreqs_content.split(/\n/).map { |line| line.wrap(cols - 4) }.join("\n")
-          puts TTY::Box.frame("{bw}#{wrapped_content}{x}".c, width: cols)
-        rescue Errno::EPIPE
-          # Pipe closed, ignore
-        end
-      end
-
       output
     end
 
@@ -944,7 +1002,7 @@ module Howzit
         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_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)

data/lib/howzit/util.rb

@@ -123,42 +123,29 @@ 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)
 
-        status.success?
+        Process.last_status.success?
       end
 
       # Strip safely when external encoding rejects multibyte content (e.g. US-ASCII default).

data/lib/howzit/version.rb

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

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/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/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 }

data/spec/subtopics_spec.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'tmpdir'
+
+describe 'subtopics' do
+  let(:temp_dir) { File.expand_path(Dir.mktmpdir('howzit_subtopics_test')) }
+  let(:buildnote) { Howzit::BuildNote.new }
+  let(:parent) { buildnote.find_topic('Parent')[0] }
+
+  before do
+    File.write(
+      File.join(temp_dir, 'buildnotes.md'),
+      <<~NOTE
+        # Subtopic Project
+
+        ## Parent
+
+        Parent content
+
+        @run(echo parent) Parent task
+
+        ### Child One
+
+        @run(echo child1) Child one task
+
+        #### Grandchild
+
+        @run(echo grand) Grandchild task
+
+        ### Child Two
+
+        @run(echo child2) Child two task
+
+        ## Sibling
+
+        @run(echo sibling) Sibling task
+      NOTE
+    )
+
+    Dir.chdir(temp_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
+
+  def topic_named(title)
+    buildnote.topics.find { |t| t.title == title }
+  end
+
+  it 'nests deeper headers under the preceding shallower header' do
+    expect(parent.subtopics.map(&:title)).to eq(['Child One', 'Child Two'])
+    expect(topic_named('Child One').subtopics.map(&:title)).to eq(['Grandchild'])
+    expect(topic_named('Grandchild').ancestors.map(&:title)).to eq(['Child One', 'Parent'])
+    expect(topic_named('Sibling').parent_topic).to be_nil
+  end
+
+  it 'keeps subtopics selectable on their own' do
+    expect(buildnote.find_topic('Child Two')[0].title).to eq('Child Two')
+  end
+
+  it 'collects tasks from subtopics in order' do
+    expect(parent.all_tasks.map(&:title)).to eq(['Parent task', 'Child one task', 'Grandchild task', 'Child two task'])
+  end
+
+  it 'displays subtopics with the parent topic' do
+    output = parent.print_out.join("\n").uncolor
+
+    expect(output).to include('Parent content')
+    expect(output).to include('Child One')
+    expect(output).to include('Grandchild')
+    expect(output).to include('echo child2')
+    expect(output).not_to include('Sibling')
+  end
+
+  it 'only outputs top-level topics when showing all topics' do
+    expect(buildnote.top_level_topics.map(&:title)).to eq(%w[Parent Sibling])
+  end
+
+  it 'indents subtopics in the topic list' do
+    list = buildnote.list.uncolor
+
+    expect(list).to include("\n- Parent")
+    expect(list).to include("\n  - Child One")
+    expect(list).to include("\n    - Grandchild")
+  end
+
+  describe 'running a parent topic' do
+    let(:ran) { [] }
+
+    it 'runs its own tasks followed by all subtopic tasks' do
+      ran_titles = ran
+      allow_any_instance_of(Howzit::Task).to receive(:run) do |task|
+        ran_titles << task.title
+        [[], 1, true]
+      end
+
+      parent.run
+
+      expect(ran).to eq(['Parent task', 'Child one task', 'Grandchild task', 'Child two task'])
+      expect(parent.results[:total]).to eq(4)
+    end
+
+    it 'stops running subtopics after an error' do
+      ran_titles = ran
+      allow_any_instance_of(Howzit::Task).to receive(:run) do |task|
+        ran_titles << task.title
+        [[], 1, task.title != 'Child one task']
+      end
+
+      parent.run
+
+      expect(ran).to eq(['Parent task', 'Child one task'])
+      expect(parent.results[:errors]).to eq(1)
+    end
+
+    it 'continues past errors with --force' do
+      Howzit.options[:force] = true
+      ran_titles = ran
+      allow_any_instance_of(Howzit::Task).to receive(:run) do |task|
+        ran_titles << task.title
+        [[], 1, task.title != 'Child one task']
+      end
+
+      parent.run
+
+      expect(ran).to eq(['Parent task', 'Child one task', 'Grandchild task', 'Child two task'])
+    ensure
+      Howzit.options[:force] = false
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.41
+  version: 2.1.44
 platform: ruby
 authors:
 - Brett Terpstra
@@ -13,14 +13,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
 - !ruby/object:Gem::Dependency
@@ -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
@@ -330,6 +331,7 @@ files:
 - spec/spec_helper.rb
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
+- spec/subtopics_spec.rb
 - spec/task_spec.rb
 - spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb
@@ -355,7 +357,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.18
 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.
@@ -365,6 +367,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,6 +378,7 @@ test_files:
 - spec/spec_helper.rb
 - spec/stack_mode_spec.rb
 - spec/stringutils_spec.rb
+- spec/subtopics_spec.rb
 - spec/task_spec.rb
 - spec/topic_positional_snapshot_spec.rb
 - spec/topic_spec.rb