howzit 2.1.35 → 2.1.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33c0053826d6797da462f0fdfa4cb505f91fd16fbff68b1feebf4e30b2e20a67
-  data.tar.gz: e9251bd45bc5ef8dc59a25ce2be80850eba66a3c9fbe9c1786b2f5637d2946e6
+  metadata.gz: a934719a022ca2f6713474e797eb1a9662dc884a750c93648d4151506ae41571
+  data.tar.gz: f261e5e733bd2d695cc76ce36e74096d357983301156c6b5b2ce5757aa3637eb
 SHA512:
-  metadata.gz: 1c6e5cf35607d239357b4848b24893ae2091b04a4d264ed472c8ef0553c4c676c2e6417fb6af8d76e1333af2e5f9f050afd0fa8ec791a0a2ffe023297db63e59
-  data.tar.gz: d5af3431513b66d9f64b253ab1096470c67075780e893aae909b1991027358ea23ad7c759fc4e5dd0c23b95a4e8587879feb0b0964bb044b37fcfc3ce7354c8b
+  metadata.gz: 9d928971e7280979fbfba50eedadedfadcf10ee31a26a4f94169c2cfe987706342fd3b826d781d89f4e3882fd87885e38b070352eae4b5e7a38c7fe06828046c
+  data.tar.gz: 72cc6fcc43c31a8d1827a5e421ebe41f06120d1fb0c428bb0339daa3e5c39b8477e769830fc302552723804033502aea5354b62b2e914a4d2e2a8bca9ac7421b

data/CHANGELOG.md

@@ -1,3 +1,87 @@
+### 2.1.39
+
+2026-01-25 07:39
+
+#### IMPROVED
+
+- The --stack option is now negatable, allowing --no-stack to disable stacking even when :stack: true is set in the configuration file, giving users command-line control over stack mode behavior
+- Howzit.buildnote now always creates a new instance when a specific file is requested, preventing cache-related issues when different files need to be loaded
+
+#### FIXED
+
+- Template topics now have their template name prefixed to their title (e.g., "github:Update GitHub README"), allowing them to be distinguished from local topics and enabling @include directives to reference them using the template prefix format
+- Build note file selection now prioritizes buildnotes.md and howzit.md over other build note files, preventing test files or other build notes from being incorrectly selected when multiple build note files exist in the same directory
+- Explicit file arguments to BuildNote.new are now properly handled, ensuring that when a specific file is provided it is used correctly instead of falling back to file discovery logic, and stack mode is disabled when an explicit file is provided
+
+### 2.1.38
+
+2026-01-25 07:18
+
+#### NEW
+
+- Added --stack option to merge build notes from directory hierarchy up to root, with topics from closer directories taking precedence over parent directories
+- Metadata from all stacked build note files is now merged, with closer directories overriding parent values but parent directories filling in missing keys
+- Commands now execute from the directory where their build note file is located, automatically changing directory before execution and restoring original directory after completion
+- Menu display for multiple topic matches now shows abbreviated directory
+
+#### IMPROVED
+
+- Topic and Task classes now track source_file to enable directory-aware execution and abbreviated path display
+- Menu selection now handles both abbreviated and full path formats for backward compatibility when matching selected topics
+- Template topics are now explicitly loaded from the main build note (closest file) in stack mode to ensure they are always included
+- Source file paths are now always normalized to absolute paths for consistent directory handling
+- Task execution directory logic now only changes directory in stack mode and correctly identifies template files to avoid changing directory for template-based tasks
+
+#### FIXED
+
+- Template topics are now correctly loaded in both normal and stack modes, fixing an issue where templates were not appearing when using --stack option
+- Template topic filtering now checks against local topics array instead of instance @topics to prevent templates from being incorrectly filtered out when @topics already contains topics from parent directories
+- Build note file selection now prioritizes buildnotes.md and howzit.md over other build note files, preventing test files or other build notes from being incorrectly selected when multiple build note files exist in the same directory
+- Explicit file arguments to BuildNote.new are now properly handled, ensuring that when a specific file is provided it is used correctly instead of falling back to file discovery logic
+- Template topics now have their template name prefixed to their title (e.g., "github:Update GitHub README"), allowing them to be distinguished from local topics and enabling @include directives to reference them using the template prefix format
+
+### 2.1.37
+
+2026-01-25 07:14
+
+#### NEW
+
+- Added --stack option to merge build notes from directory hierarchy up to root, with topics from closer directories taking precedence over parent directories
+- Metadata from all stacked build note files is now merged, with closer directories overriding parent values but parent directories filling in missing keys
+- Commands now execute from the directory where their build note file is located, automatically changing directory before execution and restoring original directory after completion
+- Menu display for multiple topic matches now shows abbreviated directory
+
+#### IMPROVED
+
+- Topic and Task classes now track source_file to enable directory-aware execution and abbreviated path display
+- Menu selection now handles both abbreviated and full path formats for backward compatibility when matching selected topics
+- Template topics are now explicitly loaded from the main build note (closest file) in stack mode to ensure they are always included
+- Source file paths are now always normalized to absolute paths for consistent directory handling
+- Task execution directory logic now only changes directory in stack mode and correctly identifies template files to avoid changing directory for template-based tasks
+
+#### FIXED
+
+- Template topics are now correctly loaded in both normal and stack modes, fixing an issue where templates were not appearing when using --stack option
+- Template topic filtering now checks against local topics array instead of instance @topics to prevent templates from being incorrectly filtered out when @topics already contains topics from parent directories
+- Build note file selection now prioritizes buildnotes.md and howzit.md over other build note files, preventing test files or other build notes from being incorrectly selected when multiple build note files exist in the same directory
+- Explicit file arguments to BuildNote.new are now properly handled, ensuring that when a specific file is provided it is used correctly instead of falling back to file discovery logic
+
+### 2.1.36
+
+2026-01-25 06:46
+
+#### NEW
+
+- Added --stack option to merge build notes from directory hierarchy up to root, with topics from closer directories taking precedence over parent directories
+- Metadata from all stacked build note files is now merged, with closer directories overriding parent values but parent directories filling in missing keys
+- Commands now execute from the directory where their build note file is located, automatically changing directory before execution and restoring original directory after completion
+- Menu display for multiple topic matches now shows abbreviated directory
+
+#### IMPROVED
+
+- Topic and Task classes now track source_file to enable directory-aware execution and abbreviated path display
+- Menu selection now handles both abbreviated and full path formats for backward compatibility when matching selected topics
+
 ### 2.1.35
 
 2026-01-14 04:36

data/README.md

@@ -17,6 +17,8 @@ Howzit is a tool that allows you to keep Markdown-formatted notes about a projec
 - Use `@include()` to import another topic's tasks
 - Use fenced code blocks to include/run embedded scripts
 - Scripts can communicate back to Howzit, sending log messages and setting variables
+- Log helper functions output messages immediately with color-coded output (cyan for info, yellow for warn, red for error, dim for debug)
+- Log helper supports `-r`/`--report` flag (or `report` parameter) for delayed output via communication file
 - Conditional blocks (`@if`/`@unless`/`@elsif`/`@else`) for conditionally including content and tasks
 - String comparison operators including fuzzy match (`**=`) for flexible pattern matching
 - File contents conditions to check file contents in conditional blocks
@@ -25,6 +27,8 @@ Howzit is a tool that allows you to keep Markdown-formatted notes about a projec
 - Templates for easily including repeat tasks
 - Grep topics for pattern and choose from matches
 - Use positional and named variables when executing tasks
+- Topic display shows variable definitions with syntax highlighting (blue parentheses, bright white variable names, yellow defaults)
+- Variable placeholders in content are highlighted to show where substitution occurs
 
 ## Getting Started
 

data/bin/howzit

@@ -243,6 +243,10 @@ OptionParser.new do |opts|
 
   opts.separator("\n  Misc:\n\n") #=================================================================== MISC
 
+  opts.on('--[no-]stack', 'Stack build notes from current directory up to root, with closer files taking precedence') do |s|
+    Howzit.options[:stack] = s
+  end
+
   opts.on('-h', '--help', 'Display this screen') do
     Howzit::Util.page opts.to_s
     Process.exit 0

data/lib/howzit/buildnote.rb

@@ -13,7 +13,16 @@ module Howzit
     ## @param      file  [String] The path to the build note file
     ##
     def initialize(file: nil, meta: nil)
-      file ||= note_file
+      # Track if an explicit file was provided
+      @explicit_file = file ? File.expand_path(file) : nil
+
+      # Set @note_file if an explicit file was provided, before calling note_file getter
+      if file
+        @note_file = File.expand_path(file)
+        file = @note_file # Use expanded path for reading
+      else
+        file = note_file
+      end
 
       @topics = []
       create_note(prompt: true) if file.nil?
@@ -216,7 +225,11 @@ module Howzit
         next if s_out.empty?
 
         title = topic.title
-        title += " {dy}({xy}#{topic.named_args.keys.join(', ')}{dy}){x}" unless topic.named_args.empty?
+        # Show argument definitions with colorized formatting
+        unless topic.arg_definitions.nil? || topic.arg_definitions.empty?
+          formatted_args = topic.arg_definitions.map { |arg| topic.format_arg_definition(arg) }.join('{l}, '.c)
+          title += " {l}({x}#{formatted_args}{l}){x}".c
+        end
 
         output.push("- {g}#{title}{x}".c)
         output.push(s_out.join("\n"))
@@ -646,6 +659,9 @@ module Howzit
       template_topics.map do |topic|
         topic.parent = template
         topic.content = topic.content.render_template(@metadata)
+        # Prefix topic title with template name (e.g., "github:Update GitHub README")
+        # unless it already has a prefix
+        topic.instance_variable_set(:@title, "#{template}:#{topic.title}") unless topic.title.include?(':')
         topic
       end
     end
@@ -676,6 +692,46 @@ module Howzit
       buildnotes.reverse
     end
 
+    ##
+    ## Find all build note files from current directory up to root
+    ##
+    ## @return     [Array] Array of build note file paths, closest first
+    ##
+    def glob_stack
+      home = Dir.pwd
+      buildnotes = []
+      current_dir = home
+
+      while current_dir != '/' && (current_dir =~ %r{[A-Z]:/}).nil?
+        Dir.chdir(current_dir)
+        filename = glob_note
+        if filename
+          note = File.expand_path(filename)
+          buildnotes.push(note) if File.exist?(note)
+        end
+        current_dir = File.dirname(current_dir)
+      end
+
+      Dir.chdir(home)
+      buildnotes
+    end
+
+    ##
+    ## Get base topic name without variables (case-insensitive)
+    ##
+    ## @param      topic_title  [String] The topic title
+    ##
+    ## @return     [String] Base topic name in lowercase
+    ##
+    def base_topic_name(topic_title)
+      # Remove prefixes (e.g., "template:Topic Name" -> "Topic Name")
+      # Remove variable definitions in parentheses (e.g., "Deploy (increment:1)" -> "Deploy")
+      # Normalize to lowercase for case-insensitive matching
+      base = topic_title.to_s
+      base = base.sub(/^.+:/, '') if base.include?(':') # Remove prefix if present
+      base.sub(/ *\(.*?\) *$/, '').strip.downcase
+    end
+
     ##
     ## Glob current directory for valid build note filenames
     ## (must start with "build" or "howzit" and have
@@ -684,7 +740,15 @@ module Howzit
     ## @return     [String] file path
     ##
     def glob_note
-      Dir.glob('*.{txt,md,markdown}').select(&:build_note?).min
+      files = Dir.glob('*.{txt,md,markdown}').select(&:build_note?)
+      return nil if files.empty?
+
+      # Prioritize standard build note filenames
+      priority_files = files.select { |f| f =~ /^(buildnotes|howzit)\./i }
+      return priority_files.min unless priority_files.empty?
+
+      # Otherwise return first alphabetically
+      files.min
     end
 
     ##
@@ -798,13 +862,20 @@ module Howzit
           title = "#{short_path}:#{title}"
         end
 
-        topic = Topic.new(title, prefix + lines.join("\n").strip.render_template(@metadata), @metadata)
+        # 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)
 
         topics.push(topic)
       end
 
       template_topics.each do |topic|
-        topics.push(topic) unless find_topic(topic.title.sub(/^.+:/, '')).count.positive?
+        # 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
 
       topics
@@ -816,16 +887,149 @@ module Howzit
     ## @param      path  [String] The build note path
     ##
     def read_help(path = nil)
-      @topics = read_help_file(path)
-      return unless Howzit.options[:include_upstream]
+      # Stack mode only applies when reading the main build note
+      # When reading templates or included files, use normal mode to prevent recursion
+
+      # Check if this is a template file
+      is_template = false
+      if path && Howzit.config.respond_to?(:template_folder) && Howzit.config.template_folder
+        template_folder = File.expand_path(Howzit.config.template_folder)
+        file_path = File.expand_path(path)
+        is_template = file_path.start_with?(template_folder)
+      end
+
+      # Prevent recursion: if we're already processing stack mode, skip it
+      in_stack_mode = Howzit.instance_variable_defined?(:@in_stack_mode) && Howzit.instance_variable_get(:@in_stack_mode)
+
+      # Use stack mode only if:
+      # 1. Stack option is enabled
+      # 2. We're not already in stack mode (prevent recursion)
+      # 3. We're not reading a template file
+      # 4. We're reading the main build note (no specific path provided, or path matches the main note file)
+      # 5. An explicit file was not provided (explicit files should not use stack mode)
+      main_note = path.nil? || begin
+        main_file = note_file
+        main_file && File.expand_path(path) == File.expand_path(main_file)
+      rescue StandardError
+        false
+      end
+
+      # Don't use stack mode if an explicit file was provided
+      use_stack = Howzit.options[:stack] && !in_stack_mode && !is_template && main_note && @explicit_file.nil?
+
+      if use_stack
+        # Set flag to prevent recursive stack mode calls
+        Howzit.instance_variable_set(:@in_stack_mode, true)
+        begin
+          # Stack mode: read all build notes from current directory up to root
+          stack_files = glob_stack
+          @topics = []
+          existing_base_names = []
+
+          # Merge metadata from all stacked files
+          # Process from root to closest, with closer directories taking precedence
+          stacked_metadata = {}
+
+          # Read metadata from all files (root to closest)
+          # Process in reverse so closer files overwrite parent values
+          stack_files.reverse.each do |file|
+            file_content = Util.read_file(file)
+            next if file_content.nil? || file_content.empty?
+
+            file_meta = file_content.split(/^#/)[0].strip.metadata
+            # Merge metadata: closer directories overwrite parent directories
+            # Processing root to closest means closer files overwrite parent values
+            next unless file_meta.is_a?(Hash)
+
+            file_meta.each do |key, value|
+              stacked_metadata[key] = value
+            end
+          end
+
+          # Get global metadata
+          global_meta = {}
+          raw_global = Howzit.options[:metadata] || Howzit.options['metadata']
+          if raw_global.is_a?(Hash)
+            raw_global.each do |k, v|
+              global_meta[k.to_s.downcase] = v
+            end
+          end
 
-      unless Howzit.has_read_upstream
-        upstream_topics = read_upstream
+          # Get passed metadata (from meta argument in initialize)
+          # Store it before we rebuild @metadata
+          original_metadata = @metadata.dup if @metadata.is_a?(Hash)
 
-        upstream_topics.each do |topic|
-          @topics.push(topic) unless find_topic(topic.title.sub(/^.+:/, '')).count.positive?
+          # Merge order for final metadata (closest directory takes precedence):
+          # 1. Global config metadata (lowest precedence)
+          # 2. Stacked metadata from all directories (closer overwrites parent)
+          # 3. Metadata passed in via meta argument (e.g., templates) - highest precedence
+          final_metadata = global_meta.dup
+          final_metadata.merge!(stacked_metadata)
+
+          # Add back any passed metadata that was in the original @metadata
+          # These are keys that exist in original but not in global or stacked
+          original_metadata&.each do |key, value|
+            next if global_meta.key?(key) || stacked_metadata.key?(key)
+
+            final_metadata[key] = value
+          end
+
+          @metadata = final_metadata
+
+          # Set primary note file to the closest one (first in stack)
+          # But don't override if an explicit file was provided
+          @note_file = stack_files.first if stack_files.any? && @explicit_file.nil?
+
+          # Read topics from each file, closest first
+          stack_files.each do |file|
+            file_topics = read_help_file(file)
+            file_topics.each do |topic|
+              # Ensure topic has the correct source_file set (always absolute path)
+              abs_file = File.expand_path(file)
+              topic.instance_variable_set(:@source_file, abs_file) unless topic.source_file == abs_file
+              base_name = base_topic_name(topic.title)
+              # Only add if we haven't seen this base topic name yet
+              unless existing_base_names.include?(base_name)
+                @topics.push(topic)
+                existing_base_names.push(base_name)
+              end
+            end
+          end
+
+          # Load template topics from the main build note (closest file) only
+          # Templates should only be loaded once, from the main build note
+          if stack_files.any?
+            main_file = stack_files.first
+            main_content = Util.read_file(main_file)
+            if main_content
+              main_template_topics = get_template_topics(main_content)
+              main_template_topics.each do |topic|
+                # Check if a topic with this base name already exists
+                base_name = base_topic_name(topic.title)
+                unless existing_base_names.include?(base_name)
+                  @topics.push(topic)
+                  existing_base_names.push(base_name)
+                end
+              end
+            end
+          end
+        ensure
+          # Clear the flag when done
+          Howzit.instance_variable_set(:@in_stack_mode, false)
+        end
+      else
+        # Normal mode: read single build note file
+        @topics = read_help_file(path)
+        return unless Howzit.options[:include_upstream]
+
+        unless Howzit.has_read_upstream
+          upstream_topics = read_upstream
+
+          upstream_topics.each do |topic|
+            @topics.push(topic) unless find_topic(topic.title.sub(/^.+:/, '')).count.positive?
+          end
+          Howzit.has_read_upstream = true
         end
-        Howzit.has_read_upstream = true
       end
 
       return unless note_file && @topics.empty?
@@ -968,10 +1172,16 @@ module Howzit
         when :all
           topic_matches.concat(matches.sort_by(&:title))
         else
-          selected_titles = Prompt.choose(matches.map(&:title), height: :max, query: Howzit.options[:grep])
+          # Format titles with abbreviated paths for menu display
+          titles = matches.map { |topic| format_topic_title_for_menu(topic) }
+          selected_titles = Prompt.choose(titles, height: :max, query: Howzit.options[:grep])
           # Convert selected titles back to topic objects
           selected_titles.each do |title|
-            matched_topic = matches.find { |t| t.title == title }
+            # Match by formatted title or base title
+            matched_topic = matches.find do |t|
+              formatted = format_topic_title_for_menu(t)
+              formatted == title || t.title == title || t.title.sub(/^[^:]+:\s*/, '') == title.sub(/^[^:]+:\s*/, '')
+            end
             topic_matches.push(matched_topic) if matched_topic
           end
         end
@@ -1095,6 +1305,46 @@ module Howzit
       all_matches
     end
 
+    ##
+    ## Abbreviate a directory path for menu display
+    ##
+    ## @param      source_file  [String] Path to the source build note file
+    ## @param      current_dir  [String] Current working directory (default: Dir.pwd)
+    ##
+    ## @return     [String] Last directory name, or nil if same directory
+    ##
+    def abbreviate_path(source_file, current_dir = Dir.pwd)
+      return nil unless source_file
+
+      source_dir = File.dirname(File.expand_path(source_file))
+      current_dir = File.expand_path(current_dir)
+
+      # If same directory, return nil (no prefix needed)
+      return nil if source_dir == current_dir
+
+      # Return just the last directory name
+      File.basename(source_dir)
+    end
+
+    ##
+    ## Format topic title for menu display with abbreviated path
+    ##
+    ## @param      topic  [Topic] The topic to format
+    ##
+    ## @return     [String] Formatted title with abbreviated path prefix
+    ##
+    def format_topic_title_for_menu(topic)
+      return topic.title unless topic.source_file
+
+      abbrev = abbreviate_path(topic.source_file)
+      return topic.title if abbrev.nil?
+
+      # Extract base title (remove existing path prefix if present)
+      base_title = topic.title.sub(/^[^:]+:\s*/, '')
+
+      "#{abbrev}: #{base_title}"
+    end
+
     ##
     ## Resolve fuzzy matches for a search term
     ##
@@ -1116,11 +1366,16 @@ module Howzit
       when :all
         matches
       else
-        titles = matches.map(&:title)
+        # Format titles with abbreviated paths for menu display
+        titles = matches.map { |topic| format_topic_title_for_menu(topic) }
         res = Prompt.choose(titles, query: search_term)
         # Convert selected titles back to topic objects from the original matches
         res.flat_map do |title|
-          matched_topic = matches.find { |t| t.title == title }
+          # Match by formatted title or base title
+          matched_topic = matches.find do |t|
+            formatted = format_topic_title_for_menu(t)
+            formatted == title || t.title == title || t.title.sub(/^[^:]+:\s*/, '') == title.sub(/^[^:]+:\s*/, '')
+          end
           matched_topic || find_topic(title)[0]
         end.compact
 

data/lib/howzit/config.rb

@@ -14,6 +14,7 @@ module Howzit
       highlight: true,
       highlighter: 'auto',
       include_upstream: false,
+      stack: false,
       log_level: 1, # 0: debug, 1: info, 2: warn, 3: error
       matching: 'partial', # exact, partial, fuzzy, beginswith
       multiple_matches: 'choose',
@@ -68,7 +69,12 @@ module Howzit
     ## Initialize a config object
     ##
     def initialize
-      load_options
+      @initializing = true
+      begin
+        load_options
+      ensure
+        @initializing = false
+      end
     end
 
     ##
@@ -95,9 +101,28 @@ module Howzit
     ## @param      filename  The filename to test
     ##
     def should_ignore(filename)
-      return false unless File.exist?(ignore_file)
+      # Prevent recursion: if we're already loading ignore patterns, skip the check
+      return false if defined?(@loading_ignore_patterns) && @loading_ignore_patterns
+
+      # Don't check the ignore file itself - do this before any file operations
+      begin
+        ignore_file_path = ignore_file
+        return false if filename == ignore_file_path || File.expand_path(filename) == File.expand_path(ignore_file_path)
+      rescue StandardError
+        # If ignore_file access fails, skip the check to prevent recursion
+        return false
+      end
+
+      return false unless File.exist?(ignore_file_path)
+
+      begin
+        @loading_ignore_patterns = true
+        @ignore_patterns ||= YAML.load(Util.read_file(ignore_file_path))
+      ensure
+        @loading_ignore_patterns = false
+      end
 
-      @ignore_patterns ||= YAML.load(Util.read_file(ignore_file))
+      return false unless @ignore_patterns.is_a?(Array)
 
       ignore = false
 

data/lib/howzit/directive.rb

@@ -89,6 +89,9 @@ module Howzit
       Howzit.named_arguments ||= {}
       Howzit.named_arguments.merge!(parent.named_args) if parent.named_args
 
+      # Pass source_file from parent topic to task
+      task_data[:source_file] = parent.respond_to?(:source_file) ? parent.source_file : nil
+
       case task_type
       when :block
         # Block tasks need title rendering