howzit 2.1.41 → 2.1.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30837683e82b813fd1fd8ff3e2df3177cbee3c735fc5afb2cb3394f08fb341eb
-  data.tar.gz: 4a0113424a3e36169a0f7a66f31b6dcc3adc24785d9a1a54829db7d9d907c585
+  metadata.gz: 8916b2ac37cd920db8008fe7a9aa28a80b4c5265083b4b257fb8ea1113938efb
+  data.tar.gz: 9486d6ca52f82ea5059bffd0de58333b82eedfc623d03f6325817caf8c956d4f
 SHA512:
-  metadata.gz: 1c0245bdb6e801d1efb96e800c04a7ac1177a589e9d25753322bb70a6690ce22b738fdfdc12956aae216565e93ea23b7cdcc14b6f278937e329b116b8d40b5cd
-  data.tar.gz: 986c7c270fc4d8aa21c395fab7a1edaa5669c4a72e6160dede78e45c9c9b6065e69ca47c6c4253b1eae1ec2909d4e31224dee333ba74e6b392e937fe1f7f25ae
+  metadata.gz: 5819786618c45538e42f21243102043b1ed408f516b0b946adaa9a2819d0080c2804cba47987f4ba0ed98b21ad7499d42cc825c2f89efb63cc4f6d8013bd743d
+  data.tar.gz: 2a90edf5e41602e1c6fc50ab21a6bfc3531b598f3a5cc381492f284bbb588b2590589fbc23da0f007a021605d46f7246e2908eed89895c175c24838b4755b285

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+### 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/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/topic.rb

@@ -33,8 +33,9 @@ module Howzit
     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 =~ /\(.*?\) *$/
@@ -944,7 +945,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.42'
 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 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.41
+  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
@@ -365,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