howzit 2.1.29 → 2.1.31

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c70619dce51a18faa84ba9516cf1e48bb2b3028f88e22397a8690e75ae65fff
-  data.tar.gz: 5f28a55772ca45c4f7a755b545c7fbf532460fee20533ff0714a304ea87d6799
+  metadata.gz: 937df7e90ef8641e22098de3ddba521506992d561bf29a225c3028fc8bbd8430
+  data.tar.gz: 0540d9f6a17567ca59627a64617c7f65148a0313c4d406df127fd01e50b4472d
 SHA512:
-  metadata.gz: 73247bd6dfbc7dc0b777f88825673dc1fa36575582d29b57c8d3a2a1996d985ad01e72917b8ac3e6626119e9a1182cddad2a166850d9e1cb5bb7aa01e68ffb93
-  data.tar.gz: 53aa254ba30a35a78880dcb7e9431d354ee4304e8244b290fb6d046dc29c60eb2becb023565ad4072e17c6af69ed5ec6faf062a15a407d87a293d7a67a14ad84
+  metadata.gz: bbcc5f97374ac62c822c5e0aec4d064dbe8635aabcb261cad9fe1a0ec92c1f4cf61bac0dcc2d8e330efac2dcdf141ea0e5e19ad8af307caa4782b14de1175f9a
+  data.tar.gz: 388f39ce1b755bf214b843ecc958bbe6058107004485be7e1aae8376177a8be720dc0c26fc863405fa0d0b6758d1bce7972a090f446b1879e1391f76cea1eed5

data/CHANGELOG.md

@@ -1,3 +1,98 @@
+### 2.1.31
+
+2026-01-06 04:57
+
+#### CHANGED
+
+- Updated Howzit to use XDG_CONFIG_HOME/howzit (or ~/.config/howzit if XDG_CONFIG_HOME is not set) for all configuration files, templates, themes, and script support files instead of ~/.local/share/howzit.
+
+#### NEW
+
+- Added automatic migration prompt that detects existing ~/.local/share/howzit directory and offers to migrate all files to the new config location, merging contents and overwriting existing files in the new location while preserving files that only exist in the new location.
+- Added --migrate flag to explicitly trigger migration of legacy ~/.local/share/howzit directory to the new config location.
+
+#### IMPROVED
+
+- Migration prompt now appears during config initialization to catch legacy directories before creating new config files, preventing confusion about file locations.
+
+#### FIXED
+
+- Fixed ArgumentError when topic titles were longer than terminal width by ensuring horizontal rule width calculation never goes negative, clamping to zero when title exceeds available space.
+
+### 2.1.30
+
+2026-01-06 03:55
+
+#### CHANGED
+
+- Updated rubocop from version 0.93.1 to 1.82.1 for Ruby 3.4.4 compatibility
+- Updated .rubocop.yml to use plugins syntax instead of require for rubocop extensions
+- Updated .rubocop.yml to inherit from .rubocop_todo.yml and removed Max settings that were overriding todo file limits
+- Added Security/YAMLLoad exception to .rubocop.yml to allow YAML.load usage (intentionally not using safe_load)
+- Added Layout/LineLength exceptions for files with intentionally long lines (bin/howzit, task.rb, util.rb, stringutils.rb, buildnote.rb)
+- Run blocks now execute scripts using appropriate interpreter commands instead of always using /bin/sh
+- Moved @log_level and @set_var directive processing before task check in sequential execution to ensure they are processed correctly.
+
+#### NEW
+
+- Scripts can now communicate back to Howzit by writing to a communication file specified in HOWZIT_COMM_FILE environment variable, allowing scripts to send log messages (LOG:level:message) and set variables (VAR:KEY=value) that are available for subsequent tasks and conditional logic
+- Added ScriptComm module to handle bidirectional communication between scripts and Howzit
+- Added @if and @unless conditional blocks that allow content and tasks to be conditionally included or excluded based on evaluated conditions, with support for nested blocks
+- Conditional blocks support string comparisons (==, =~ /regex/, *= contains, ^= starts with, $= ends with) and numeric comparisons (==, !=, >, >=, <, <=)
+- Conditions can test against metadata keys, environment variables, positional arguments ($1, $2, etc.), named arguments, and script-set variables
+- Added special condition checks: git dirty/clean, file exists <path>, dir exists <path>, topic exists <name>, and cwd/working directory
+- Conditions support negation with 'not' or '!' prefix
+- Added @elsif directive for alternative conditions in @if/@unless blocks, allowing multiple conditional branches
+- Added @else directive for fallback branches in conditional blocks when all previous conditions are false
+- Conditional blocks now support chaining multiple @elsif statements between @if/@unless and @else
+- @elsif and @else work correctly with nested conditional blocks
+- Added **= fuzzy match operator for string comparisons that matches if search string characters appear in order within the target string (e.g., "fluffy" **= "ffy" matches)
+- Added file contents condition that reads file contents and performs string comparisons using any comparison operator (e.g., file contents VERSION.txt ^= 0.)
+- File contents condition supports file paths as variables from metadata, named arguments, or environment variables
+- ScriptSupport module provides helper functions (log_info, log_warn, log_error, log_debug, set_var) for bash, zsh, fish, ruby, python, perl, and node scripts in run blocks
+- Automatic interpreter detection from hashbang lines in scripts
+- Helper script injection into run blocks based on detected interpreter
+- Support directory installation at ~/.local/share/howzit/support with language-specific helper scripts
+- Add sequential conditional evaluation: @if/@unless blocks are now evaluated after each task runs, allowing variables set by scripts to affect subsequent conditional blocks in the same topic
+- Add @log_level(LEVEL) directive to set log level for subsequent tasks in a topic
+- Add log_level parameter to @run directives (e.g., @run(script.sh, log_level=debug))
+- Add HOWZIT_LOG_LEVEL environment variable support for global log level configuration
+- Add emoji and color indicators for log messages (debug, info, warn, error)
+- Add comprehensive test coverage for sequential conditional evaluation including @if/@unless/@elsif/@else blocks with variables from run blocks
+- Add comprehensive test coverage for log level configuration including @log_level directive, log_level parameter in @run directives, and HOWZIT_LOG_LEVEL environment variable
+- Added @set_var directive to set variables in build notes. Takes two comma-separated arguments: variable name (alphanumeric, dashes, underscores only) and value. Variables are available as ${VAR} in subsequent @run directives, run blocks, and @if/@else conditional blocks.
+- Added command substitution support to @set_var directive. Values can use backticks (`command`) or $() syntax ($(command)) to execute commands and use their output as the variable value. Commands can reference other variables using ${VAR} syntax.
+- Added @set_var directive to set variables directly in build notes, making them available as ${VAR} in subsequent @run directives, run blocks, and @if/@else conditional blocks.
+- Added command substitution support to @set_var so values can come from backtick commands (`command`) or $() syntax ($(command)), with command output (whitespace stripped) used as the variable value and ${VAR} substitutions applied inside the command.
+
+#### IMPROVED
+
+- Auto-corrected rubocop style offenses including string literals, redundant self, parentheses, and other correctable issues
+- Fixed Lint/Void issue in buildnote.rb by simplifying conditional logic
+- Cwd and working directory can now be used with string comparison operators (==, =~, *=, ^=, $=) to check the current directory path
+- Conditions now support ${var} syntax in addition to var for consistency with variable substitution syntax
+- String comparison operators (*=, ^=, $=) now treat unquoted strings that aren't found as variables as literal strings, allowing simpler syntax like template *= gem instead of template *= "gem"
+- Log messages from scripts now display with visual indicators: debug messages show with magnifying glass emoji and dark color, info with info emoji and cyan, warnings with warning emoji and yellow, errors with X emoji and red
+- Log level filtering now properly applies to script-to-howzit communication messages, showing only messages at or above the configured level
+- Conditional blocks (@if/@unless/@elsif/@else) now re-evaluate after each task execution, enabling dynamic conditional flow based on variables set by preceding tasks
+- Improve task directive parsing by refactoring to use unless/next pattern for better code organization and fixing @log_level directive handling
+- Improve Directive#to_task to properly handle title rendering with variable substitution, argument parsing for include tasks, and action escaping for copy tasks
+- Processed @set_var directives before task creation in topics without conditionals so variable substitution in @run actions works as expected even in the non-sequential execution path.
+
+#### FIXED
+
+- Resolved NameError for 'white' color method by generating escape codes directly from configured_colors hash instead of calling dynamically generated methods
+- Fixed infinite recursion in ConsoleLogger by using $stderr.puts directly instead of calling warn method recursively
+- Color template method now properly respects coloring? setting and returns empty strings when coloring is disabled
+- Resolved test failures caused by Howzit.buildnote caching stale instances by resetting @buildnote in spec_helper before each test
+- Fixed bug where @end statements failed to close conditional blocks when conditions evaluated to false, preventing subsequent conditional blocks from working correctly
+- Fixed issue where named arguments from topic titles were not available when evaluating conditions in conditional blocks
+- Suppressed EPIPE errors that occur when writing to stdout/stderr after pipes are closed, preventing error messages from appearing in terminal output
+- Fix @elsif and @else conditional blocks not executing tasks when parent @if condition is false by correctly tracking branch indices and skipping parent @if index in conditional path evaluation
+- Fix clipboard copy test failing due to cached console logger instance not updating when log_level option changes
+- Fixed variable persistence issue in sequential execution where Howzit.named_arguments was being reset on each iteration, causing @set_var variables to be lost.
+- Ensured variables set by @set_var and helper scripts persist correctly across sequential conditional evaluation by merging topic named arguments into Howzit.named_arguments instead of overwriting them.
+
 ### 2.1.29
 
 2026-01-01 06:55

data/README.md

@@ -4,11 +4,11 @@
 [![Gem](https://img.shields.io/gem/v/howzit.svg)](https://rubygems.org/gems/howzit)
 [![GitHub license](https://img.shields.io/github/license/ttscoff/howzit.svg)](./LICENSE.txt)
 
+
 A command-line reference tool for tracking project build systems
 
 Howzit is a tool that allows you to keep Markdown-formatted notes about a project's tools and procedures. It functions as an easy lookup for notes about a particular task, as well as a task runner to automatically execute appropriate commands.
 
-
 ## Features
 
 - Match topic titles with any portion of title
@@ -16,6 +16,10 @@ Howzit is a tool that allows you to keep Markdown-formatted notes about a projec
 - Use `@run()`, `@copy()`, and `@open()` to perform actions within a build notes file
 - 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
+- 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
 - Sets iTerm 2 marks on topic titles for navigation when paging is disabled
 - Inside of git repositories, howzit will work from subdirectories, assuming build notes are in top level of repo
 - Templates for easily including repeat tasks

data/Rakefile

@@ -46,9 +46,15 @@ task :ver do
   puts "changelog: #{cver}"
 end
 
+desc 'Version.rb check'
+task :vver do
+  res = `grep VERSION lib/howzit/version.rb`
+  print res.match(/VERSION *= *['"](\d+\.\d+\.\d+(\w+)?)/)[1]
+end
+
 desc 'Changelog version check'
 task :cver do
-  puts IO.read(File.join(File.dirname(__FILE__), 'CHANGELOG.md')).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
+  print IO.read(File.join(File.dirname(__FILE__), 'CHANGELOG.md')).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
 end
 
 desc 'Run tests in Docker'

data/bin/howzit

@@ -248,6 +248,11 @@ OptionParser.new do |opts|
     Process.exit 0
   end
 
+  opts.on('--migrate', 'Migrate legacy files from ~/.local/share/howzit to the new config location') do
+    Howzit::ScriptSupport.migrate_legacy_support(early_init: false)
+    Process.exit 0
+  end
+
   opts.on('-v', '--version', 'Display version number') do
     puts "#{File.basename(__FILE__)} v#{Howzit::VERSION}"
     Process.exit 0

data/lib/howzit/buildnote.rb

@@ -21,9 +21,31 @@ module Howzit
       content = Util.read_file(file)
       raise "{br}No content found in build note (#{file}){x}".c if content.nil? || content.empty?
 
+      # Global metadata from config (e.g. ~/.config/howzit/howzit.yml)
+      # Expecting something like:
+      # metadata:
+      #   author: Brett Terpstra
+      #   license: MIT
+      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
+
+      # Metadata defined in the build note itself (before the first heading)
       this_meta = content.split(/^#/)[0].strip.metadata
 
-      @metadata = meta.nil? ? this_meta : meta.merge(this_meta)
+      # Merge order:
+      # 1. Global config metadata (lowest precedence)
+      # 2. Metadata passed in via meta argument (e.g. templates)
+      # 3. Build note metadata (highest precedence)
+      combined_meta = global_meta.dup
+      combined_meta.merge!(meta) if meta
+      combined_meta.merge!(this_meta) if this_meta
+
+      @metadata = combined_meta
 
       read_help(file)
     end

data/lib/howzit/config.rb

@@ -194,6 +194,19 @@ module Howzit
       config = load_config
       load_theme
       @options = flags.merge(config)
+
+      # Check for HOWZIT_LOG_LEVEL environment variable
+      return unless ENV['HOWZIT_LOG_LEVEL']
+
+      level_str = ENV['HOWZIT_LOG_LEVEL'].downcase
+      level_map = {
+        'debug' => 0,
+        'info' => 1,
+        'warn' => 2,
+        'warning' => 2,
+        'error' => 3
+      }
+      @options[:log_level] = level_map[level_str] || level_str.to_i
     end
 
     ##
@@ -238,6 +251,14 @@ module Howzit
     ## @param      default     [Hash] default configuration to write
     ##
     def create_config(default)
+      # If a legacy ~/.local/share/howzit directory exists, offer to migrate it
+      # into the new config root before creating any new files to avoid confusion
+      # about where Howzit stores its configuration.
+      # Use early_init=true since we're called during config initialization and can't access Howzit.options yet
+      if defined?(Howzit::ScriptSupport) && File.directory?(File.expand_path(Howzit::ScriptSupport::LEGACY_SUPPORT_DIR))
+        Howzit::ScriptSupport.migrate_legacy_support(early_init: true)
+      end
+
       unless File.directory?(config_dir)
         Howzit::ConsoleLogger.new(1).info "Creating config directory at #{config_dir}"
         FileUtils.mkdir_p(config_dir)

data/lib/howzit/console_logger.rb

@@ -31,6 +31,50 @@ module Howzit
       @log_level = Howzit.options[:log_level]
     end
 
+    ##
+    ## Get emoji for log level
+    ##
+    ## @param      level  [Symbol] The level
+    ##
+    ## @return     [String] Emoji for the level
+    ##
+    def emoji_for_level(level)
+      case level
+      when :debug
+        '🔍'
+      when :info
+        'ℹ️'
+      when :warn
+        '⚠️'
+      when :error
+        '❌'
+      else
+        ''
+      end
+    end
+
+    ##
+    ## Get color prefix for log level
+    ##
+    ## @param      level  [Symbol] The level
+    ##
+    ## @return     [String] Color template string
+    ##
+    def color_for_level(level)
+      case level
+      when :debug
+        '{d}'
+      when :info
+        '{c}'
+      when :warn
+        '{y}'
+      when :error
+        '{r}'
+      else
+        ''
+      end
+    end
+
     ##
     ## Write a message to the console based on the urgency
     ## level and user's log level setting
@@ -41,8 +85,16 @@ module Howzit
     def write(msg, level = :info)
       return unless LOG_LEVELS[level] >= @log_level
 
+      emoji = emoji_for_level(level)
+      color = color_for_level(level)
+      formatted_msg = if emoji && color
+                        "#{emoji} #{color}#{msg}{x}".c
+                      else
+                        msg
+                      end
+
       begin
-        $stderr.puts msg
+        $stderr.puts formatted_msg
       rescue Errno::EPIPE
         # Pipe closed, ignore
       end
@@ -74,8 +126,16 @@ module Howzit
     def warn(msg)
       return unless LOG_LEVELS[:warn] >= @log_level
 
+      emoji = emoji_for_level(:warn)
+      color = color_for_level(:warn)
+      formatted_msg = if emoji && color
+                        "#{emoji} #{color}#{msg}{x}".c
+                      else
+                        msg
+                      end
+
       begin
-        $stderr.puts msg
+        $stderr.puts formatted_msg
       rescue Errno::EPIPE
         # Pipe closed, ignore
       end

data/lib/howzit/directive.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Howzit
+  # Directive class
+  # Represents a parsed directive from topic content (tasks, conditionals, etc.)
+  class Directive
+    attr_reader :type, :content, :condition, :directive_type, :optional, :default, :line_number, :conditional_path,
+                :log_level_value, :var_name, :var_value
+
+    ##
+    ## Initialize a Directive
+    ##
+    ## @param      type            [Symbol] :task, :if, :unless, :elsif, :else, :end, :log_level
+    ## @param      content         [String] The directive content (action, block, etc.)
+    ## @param      condition       [String, nil] Condition string for conditionals
+    ## @param      directive_type  [String, nil] 'if', 'unless', 'elsif', 'else' for conditionals
+    ## @param      optional        [Boolean] Whether task requires confirmation
+    ## @param      default         [Boolean] Default response for confirmation
+    ## @param      line_number     [Integer] Line number in original content
+    ## @param      conditional_path [Array] Array of conditional indices this directive is nested in
+    ## @param      log_level_value [String, nil] Log level value for @log_level directives
+    ## @param      var_name        [String, nil] Variable name for @set_var directives
+    ## @param      var_value       [String, nil] Variable value for @set_var directives
+    ##
+    def initialize(type:, content: nil, condition: nil, directive_type: nil, optional: false, default: true,
+                   line_number: nil, conditional_path: [], log_level_value: nil, var_name: nil, var_value: nil)
+      @type = type
+      @content = content
+      @condition = condition
+      @directive_type = directive_type
+      @optional = optional
+      @default = default
+      @line_number = line_number
+      @conditional_path = conditional_path || []
+      @log_level_value = log_level_value
+      @var_name = var_name
+      @var_value = var_value
+    end
+
+    ##
+    ## Is this a conditional directive?
+    ##
+    def conditional?
+      %i[if unless elsif else end].include?(@type)
+    end
+
+    ##
+    ## Is this a task directive?
+    ##
+    def task?
+      @type == :task
+    end
+
+    ##
+    ## Is this a log_level directive?
+    ##
+    def log_level?
+      @type == :log_level
+    end
+
+    ##
+    ## Is this a set_var directive?
+    ##
+    def set_var?
+      @type == :set_var
+    end
+
+    ##
+    ## Convert directive to a Task object (only works for task directives)
+    ##
+    ## @param      parent        [Topic] The parent topic
+    ## @param      current_log_level [String, nil] Current log level to apply to task
+    ##
+    ## @return     [Task] Task object
+    ##
+    def to_task(parent, current_log_level: nil)
+      return nil unless task?
+
+      task_data = @content.dup
+      task_type = task_data[:type]
+
+      # Apply current log level if set and task doesn't have its own
+      task_data[:log_level] = current_log_level if current_log_level && !task_data[:log_level]
+
+      # Set named_arguments before processing titles for variable substitution
+      Howzit.named_arguments = parent.named_args
+
+      case task_type
+      when :block
+        # Block tasks are already properly formatted
+        task_data[:parent] = parent
+        Howzit::Task.new(task_data, optional: @optional, default: @default)
+      when :run
+        # Run tasks need title rendering (similar to define_task_args)
+        title = task_data[:title]
+        title = title.render_arguments if title && !title.empty?
+        task_data[:title] = title
+        task_data[:parent] = parent
+        Howzit::Task.new(task_data, optional: @optional, default: @default)
+      when :copy
+        # Copy tasks need title rendering and action escaping
+        title = task_data[:title]
+        title = title.render_arguments if title && !title.empty?
+        task_data[:title] = title
+        task_data[:action] = Shellwords.escape(task_data[:action])
+        task_data[:parent] = parent
+        Howzit::Task.new(task_data, optional: @optional, default: @default)
+      when :open
+        # Open tasks need title rendering
+        title = task_data[:title]
+        title = title.render_arguments if title && !title.empty?
+        task_data[:title] = title
+        task_data[:parent] = parent
+        Howzit::Task.new(task_data, optional: @optional, default: @default)
+      when :include
+        # Include tasks need special handling (title processing, arguments, etc.)
+        title = task_data[:title]
+        if title =~ /\[(.*?)\] *$/
+          args = Regexp.last_match(1).split(/ *, */).map(&:render_arguments)
+          Howzit.arguments = args
+          parent.arguments
+          title.sub!(/ *\[.*?\] *$/, '')
+        end
+        title = title.render_arguments if title && !title.empty?
+        task_data[:title] = title
+        task_data[:parent] = parent
+        task_data[:arguments] = Howzit.named_arguments
+        Howzit::Task.new(task_data, optional: @optional, default: @default)
+      else
+        task_data[:parent] = parent
+        Howzit::Task.new(task_data, optional: @optional, default: @default)
+      end
+    end
+  end
+end