snippet_cli 0.3.6 → 0.5.2

data/lib/snippet_cli/ui.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'cursor_helper'
+
+module SnippetCli
+  module UI
+    BASE_FLAGS = ['--border=rounded', '--padding=0 4'].freeze
+    PROMPT_STYLE = { padding: '0 1', margin: '0' }.freeze
+
+    STYLE_FLAGS = {
+      info: [],
+      hint: ['--border-foreground=220'],
+      success: ['--border-foreground=46', '--bold'],
+      warning: ['--border-foreground=220', '--foreground=220', '--bold'],
+      error: ['--border-foreground=196', '--foreground=196', '--bold'],
+      preview: []
+    }.freeze
+
+    def self.note(text)
+      puts "\e[38;5;231m#{text}\e[0m"
+    end
+
+    def self.info(text)    = gum_style(text, *STYLE_FLAGS[:info])
+    def self.hint(text)    = gum_style(text, *STYLE_FLAGS[:hint])
+    def self.success(text) = gum_style(text, *STYLE_FLAGS[:success])
+    def self.warning(text) = gum_style(text, *STYLE_FLAGS[:warning])
+    def self.error(text)   = gum_style(text, *STYLE_FLAGS[:error])
+    def self.preview(text) = gum_style(text, *STYLE_FLAGS[:preview])
+
+    # Renders a warning and returns a lambda that erases it via line-count tracking.
+    # The warning is always rendered; the clear lambda is a no-op when not a TTY.
+    def self.transient_note(text)
+      puts "\e[38;5;231m #{text}\e[0m"
+      puts
+      erase_lambda(2)
+    end
+
+    def self.transient_warning(text)
+      warning(text)
+      erase_lambda(text.lines.count + 2)
+    end
+
+    def self.transient_error(text)
+      error(text)
+      erase_lambda(text.lines.count + 2)
+    end
+
+    # Renders an info box and returns a lambda that erases it via line-count tracking.
+    # The info box is always rendered; the clear lambda is a no-op when not a TTY.
+    def self.transient_info(text)
+      info(text)
+      erase_lambda(text.lines.count + 2)
+    end
+
+    def self.erase_lambda(line_count)
+      CursorHelper.build_erase_lambda(line_count)
+    end
+    private_class_method :erase_lambda
+
+    def self.format_code(text, language: 'yaml')
+      Gum::Command.run_display_only('format', '--type=code', "--language=#{language}", input: text)
+      puts
+    rescue Gum::Error
+      puts text
+      puts
+    end
+
+    # Delivers YAML output: pipes to stdout if piped, or displays with a label if interactive.
+    # context must respond to #pipe_output (nil = interactive mode).
+    def self.deliver(yaml, label:, context: nil)
+      pipe = context&.pipe_output
+      if pipe
+        pipe.print yaml
+      else
+        info("#{label} YAML below.")
+        format_code(yaml)
+      end
+    end
+
+    # Pass text via stdin instead of as a positional CLI argument.
+    # Gum's arg parser interprets leading `-` characters (e.g. YAML list
+    # markers like `- triggers:`) as unknown flags when passed positionally.
+    def self.gum_style(text, *extra_flags)
+      result = Gum::Command.run_non_interactive('style', *BASE_FLAGS, *extra_flags, input: text)
+      puts result
+    end
+    private_class_method :gum_style
+  end
+end

data/lib/snippet_cli/var_builder/form_fields.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative '../ui'
+require_relative '../form_field_parser'
+
+module SnippetCli
+  module VarBuilder
+    # Collects field-level configuration for form variable layouts.
+    module FormFields
+      FIELD_TYPES = [
+        'Single-line text box',
+        'Multi-line text box',
+        'Choice box',
+        'List box'
+      ].freeze
+
+      def self.collect(builder, layout)
+        field_names = FormFieldParser.extract(layout)
+        fields = {}
+        field_names.each do |name|
+          type = builder.prompt!(
+            Gum.filter(*FIELD_TYPES, limit: 1, header: "[[#{name}]] field type")
+          )
+          config = field_config(builder, name, type)
+          fields[name.to_sym] = config if config
+        end
+        fields
+      end
+
+      def self.field_config(builder, name, type)
+        case type
+        when 'Multi-line text box'
+          { multiline: true }
+        when 'Choice box'
+          { type: :choice, values: collect_values(builder, name) }
+        when 'List box'
+          { type: :list, values: collect_values(builder, name) }
+        end
+      end
+      private_class_method :field_config
+
+      def self.collect_values(builder, field_name)
+        loop do
+          values = Params.collect_list(builder, "#{field_name} value")
+          return values if values.length >= 2
+
+          UI.warning("Provide at least 2 values for [[#{field_name}]].")
+        end
+      end
+      private_class_method :collect_values
+    end
+  end
+end

data/lib/snippet_cli/var_builder/name_collector.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../ui'
+require_relative '../wizard_helpers/prompt_helpers'
+require_relative '../wizard_helpers/validation_loop'
+
+module SnippetCli
+  module VarBuilder
+    # Handles the interactive name-collection loop: prompts for a variable
+    # name, validates it (non-empty, no prohibited chars, no duplicates), and
+    # returns the accepted name or nil when a duplicate is detected.
+    class NameCollector
+      include WizardHelpers::PromptHelpers
+      include WizardHelpers::ValidationLoop
+
+      def initialize(existing)
+        @existing = existing
+      end
+
+      # Returns the validated name string, or nil for a duplicate.
+      # Raises WizardInterrupted on Ctrl+C / nil input.
+      FIRST_VAR_HEADER = "One replacement may use multiple variables.\nEnter names one at a time.\n"
+
+      def collect
+        first = @existing.empty?
+        name = prompt_until_valid do
+          n, first = prompt_name(first)
+          [n, name_validation_error(n)]
+        end
+        return nil if duplicate?(name)
+
+        name
+      end
+
+      private
+
+      def prompt_name(first)
+        opts = { placeholder: 'Your variable name', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE }
+        opts[:header] = FIRST_VAR_HEADER if first
+        [prompt!(Gum.input(**opts)), false]
+      end
+
+      def name_validation_error(name)
+        return 'Variable name cannot be empty. Please enter a name.' if name.strip.empty?
+        return prohibited_char_message(name) if prohibited_char?(name)
+
+        nil
+      end
+
+      def duplicate?(name)
+        return false unless @existing.any? { |v| v[:name] == name }
+
+        warn "Variable '#{name}' already defined — skipping"
+        true
+      end
+
+      def prohibited_char?(name)
+        PROHIBITED_CHARS.any? { |char| name.include?(char) }
+      end
+
+      def prohibited_char_message(name)
+        prohibited = PROHIBITED_CHARS.map { |c| "'#{c}'" }.join(', ')
+        "Variable name '#{name}' contains a prohibited character " \
+          "(#{prohibited}) — use only letters, digits, and underscores"
+      end
+    end
+    private_constant :NameCollector
+  end
+end

data/lib/snippet_cli/var_builder/param_schema.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  module VarBuilder
+    # Pure data layer: describes what params are valid for each var type.
+    # No Gum/UI calls — independently testable.
+    module ParamSchema
+      SCHEMAS = {
+        'echo' => {
+          required: [:echo],
+          optional: [],
+          field_types: { echo: :string }
+        },
+        'random' => {
+          required: [:choices],
+          optional: [],
+          field_types: { choices: :string_array }
+        },
+        'choice' => {
+          required: [:values],
+          optional: [],
+          field_types: { values: :string_array }
+        },
+        'date' => {
+          required: [:format],
+          optional: %i[offset locale tz],
+          field_types: { format: :string, offset: :integer, locale: :string, tz: :string }
+        },
+        'shell' => {
+          required: %i[cmd shell],
+          optional: %i[debug trim],
+          field_types: { cmd: :string, shell: :string, debug: :boolean, trim: :boolean }
+        },
+        'script' => {
+          required: [:args],
+          optional: [:trim],
+          field_types: { args: :string_array, trim: :boolean }
+        },
+        'form' => {
+          required: [:layout],
+          optional: [:fields],
+          field_types: { layout: :string, fields: :any }
+        },
+        'clipboard' => {
+          required: [],
+          optional: [],
+          field_types: {}
+        }
+      }.freeze
+
+      def self.known_type?(type)
+        SCHEMAS.key?(type)
+      end
+
+      def self.schema_for(type)
+        SCHEMAS[type]
+      end
+
+      # Returns true if params hash contains all required fields and no unknown fields.
+      # Pure method — no UI calls.
+      def self.valid_params?(type, params)
+        schema = SCHEMAS[type]
+        return false unless schema
+
+        allowed = schema[:required] + schema[:optional]
+        schema[:required].all? { |f| params.key?(f) } &&
+          params.keys.all? { |k| allowed.include?(k) }
+      end
+    end
+  end
+end

data/lib/snippet_cli/var_builder/params.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'param_schema'
+require_relative 'form_fields'
+
+module SnippetCli
+  module VarBuilder
+    # Interactive collection of Espanso `params` hashes per variable type.
+    module Params
+      COLLECTORS = {
+        'echo' => lambda { |b|
+          { echo: b.prompt!(Gum.input(placeholder: 'echo value', prompt_style: UI::PROMPT_STYLE,
+                                      header_style: UI::PROMPT_STYLE)) }
+        },
+        'random' => lambda { |b|
+          raw = b.prompt!(Gum.write(header: 'Put one random choice per line', prompt_style: UI::PROMPT_STYLE,
+                                    header_style: UI::PROMPT_STYLE))
+          { choices: raw.to_s.lines.map(&:chomp).reject(&:empty?) }
+        },
+        'choice' => lambda { |b|
+          raw = b.prompt!(Gum.write(header: 'Put one choice per line', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE))
+          { values: raw.to_s.lines.map(&:chomp).reject(&:empty?) }
+        }
+      }.freeze
+
+      def self.collect(builder, type)
+        params = collect_raw(builder, type)
+        validate!(type, params)
+        params
+      end
+
+      def self.validate!(type, params)
+        return unless ParamSchema.known_type?(type)
+        return if ParamSchema.valid_params?(type, params)
+
+        raise SnippetCli::InvalidParamsError,
+              "Invalid params #{params.inspect} for var type '#{type}'"
+      end
+
+      def self.collect_raw(builder, type)
+        collector = COLLECTORS[type]
+        return collector.call(builder) if collector
+
+        case type
+        when 'date'      then date(builder)
+        when 'shell'     then shell(builder)
+        when 'script'    then script(builder)
+        when 'form'      then form(builder)
+        else {}
+        end
+      end
+
+      def self.collect_list(builder, item_name)
+        raw = builder.prompt!(Gum.write(header: "Put one #{item_name} per line", prompt_style: UI::PROMPT_STYLE,
+                                        header_style: UI::PROMPT_STYLE))
+        raw.to_s.lines.map(&:chomp).reject(&:empty?)
+      end
+
+      def self.shell(builder)
+        sh = builder.prompt!(Gum.filter(*builder.platform_shells, limit: 1, header: 'Select shell'))
+        cmd = builder.prompt!(Gum.input(placeholder: 'shell command', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE))
+        debug_trim(builder, cmd: cmd, shell: sh)
+      end
+
+      def self.script(builder)
+        gum = Gum.write(header: 'Script args — one per line',
+                        placeholder: '/path/to/script', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE)
+        raw = builder.prompt!(gum)
+        params = { args: raw.to_s.lines.map(&:chomp).reject(&:empty?) }
+        params[:trim] = true if builder.confirm!('Trim whitespace from output?')
+        params
+      end
+
+      def self.date(builder)
+        params = { format: builder.prompt!(Gum.input(placeholder: 'date format (e.g. %Y-%m-%d)',
+                                                     prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE)) }
+        date_optional_params(builder, params)
+      end
+
+      DATE_OPT_FIELDS = [
+        [:offset, 'Add an offset?', 'offset in seconds (e.g. 86400)', :to_i],
+        [:locale, 'Add a locale?', 'BCP47 locale (e.g. en-US, ja-JP)', nil],
+        [:tz,     'Add a timezone?', 'IANA timezone (e.g. America/New_York)', nil]
+      ].freeze
+
+      def self.date_optional_params(builder, params)
+        style = UI::PROMPT_STYLE
+        DATE_OPT_FIELDS.each do |key, prompt, ph, conv|
+          next unless builder.confirm!(prompt)
+
+          val = builder.prompt!(Gum.input(placeholder: ph, prompt_style: style, header_style: style))
+          params[key] = conv ? val.public_send(conv) : val
+        end
+        params
+      end
+
+      def self.form(builder)
+        layout = form_layout(builder)
+        fields = FormFields.collect(builder, layout)
+        params = { layout: layout }
+        params[:fields] = fields if fields.any?
+        params
+      end
+
+      def self.form_layout(builder)
+        ps = UI::PROMPT_STYLE
+        ph = 'Form layout (use [[field_name]] for fields)'
+        gum = if builder.confirm!('Multi-line form?')
+                Gum.write(header: ph, prompt_style: ps, header_style: ps)
+              else
+                Gum.input(placeholder: ph, prompt_style: ps, header_style: ps)
+              end
+        builder.prompt!(gum)
+      end
+
+      def self.debug_trim(builder, params)
+        params[:debug] = true if builder.confirm!('Enable debug mode?')
+        params[:trim] = true if builder.confirm!('Trim whitespace from output?')
+        params
+      end
+
+      private_class_method :collect_raw, :shell, :script, :date,
+                           :date_optional_params, :form, :form_layout, :debug_trim
+    end
+  end
+end

data/lib/snippet_cli/var_builder.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'wizard_helpers/prompt_helpers'
+require_relative 'var_summary_renderer'
+require_relative 'var_builder/name_collector'
+require_relative 'var_builder/params'
+
+module SnippetCli
+  module VarBuilder
+    extend WizardHelpers::PromptHelpers
+
+    VAR_TYPES = %w[echo shell date random choice script form clipboard].freeze
+
+    # Characters that break variable-to-mapping resolution. Add more here as needed.
+    PROHIBITED_CHARS = %w[-].freeze
+
+    SHELLS_BY_PLATFORM = {
+      macos: %w[sh bash pwsh nu],
+      linux: %w[sh bash pwsh nu],
+      windows: %w[cmd powershell pwsh wsl nu]
+    }.freeze
+
+    # Collects Espanso variable definitions interactively. Raises WizardInterrupted on cancel.
+    # skip_initial_prompt: true skips "Add a variable?" and goes straight to collecting the first var.
+    # Returns { vars: Array, summary_clear: Proc }.
+    def self.run(skip_initial_prompt: false)
+      interactive_session(skip_initial_prompt: skip_initial_prompt)
+    rescue Interrupt
+      raise WizardInterrupted
+    end
+
+    def self.platform_shells
+      case RUBY_PLATFORM
+      when /darwin/             then SHELLS_BY_PLATFORM[:macos]
+      when /mswin|mingw|cygwin/ then SHELLS_BY_PLATFORM[:windows]
+      else SHELLS_BY_PLATFORM[:linux]
+      end
+    end
+
+    def self.collect_one_var(existing)
+      name = NameCollector.new(existing).collect
+      return nil if name.nil?
+
+      type = prompt!(Gum.filter(*VAR_TYPES, limit: 1, header: 'Variable type'))
+      { name: name, type: type, params: Params.collect(self, type) }
+    end
+    private_class_method :collect_one_var
+
+    def self.interactive_session(skip_initial_prompt: false)
+      vars = []
+      loop do
+        break unless confirm_next?(vars, skip_initial_prompt)
+
+        append_var!(vars)
+      end
+      reorder_vars!(vars)
+      summary_clear = vars.empty? ? -> {} : VarSummaryRenderer.show(vars)
+      { vars: vars, summary_clear: summary_clear }
+    end
+    private_class_method :interactive_session
+
+    def self.reorder_vars!(vars)
+      return if vars.size < 2
+      return unless confirm!('Reorder variables for evaluation order?')
+
+      loop do
+        selection = choose_var_to_move(vars)
+        break if selection.start_with?('Done')
+
+        move_var!(vars, selection)
+      end
+    end
+    private_class_method :reorder_vars!
+
+    def self.choose_var_to_move(vars)
+      choices = vars.each_with_index.map { |v, i| "#{i + 1}. #{v[:name]} (#{v[:type]})" }
+      choices << 'Done — keep this order'
+      prompt!(Gum.choose(*choices, header: 'Select a variable to move:', header_style: UI::PROMPT_STYLE))
+    end
+    private_class_method :choose_var_to_move
+
+    def self.move_var!(vars, selection)
+      from_idx = selection.match(/^(\d+)\./)[1].to_i - 1
+      item = vars.delete_at(from_idx)
+      vars.insert(choose_target_position(vars, item[:name]), item)
+    end
+    private_class_method :move_var!
+
+    def self.choose_target_position(vars, name)
+      positions = vars.each_with_index.map { |v, i| "#{i + 1}. Before #{v[:name]}" }
+      positions << "#{vars.size + 1}. At end"
+      result = prompt!(Gum.choose(*positions, header: "Move \"#{name}\" to:", header_style: UI::PROMPT_STYLE))
+      result.match(/^(\d+)\./)[1].to_i - 1
+    end
+    private_class_method :choose_target_position
+
+    def self.confirm_next?(vars, skip_initial_prompt)
+      return true if vars.empty? && skip_initial_prompt
+
+      question = confirm_question(vars, skip_initial_prompt)
+      if vars.empty?
+        confirm!(question)
+      else
+        list_confirm!('variable', VarSummaryRenderer.rows(vars), %w[Name Type], question)
+      end
+    end
+    private_class_method :confirm_next?
+
+    def self.confirm_question(vars, skip_initial_prompt)
+      return 'Add a variable?' if vars.empty? && !skip_initial_prompt
+
+      'Add another variable?'
+    end
+    private_class_method :confirm_question
+
+    def self.append_var!(vars)
+      var = collect_one_var(vars)
+      return if var.nil?
+
+      vars << var
+    end
+    private_class_method :append_var!
+  end
+end

data/lib/snippet_cli/var_summary_renderer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'ui'
+require_relative 'cursor_helper'
+require_relative 'form_field_parser'
+
+module SnippetCli
+  # Pure display/formatting logic for the VarBuilder summary screen.
+  # Handles row computation, UI.note output, Gum.table rendering, and cursor erase lambda.
+  module VarSummaryRenderer
+    # Returns display rows for the given vars array.
+    # Form vars are expanded into dot-notation field rows; all others are [name, type].
+    def self.rows(vars)
+      vars.flat_map do |var|
+        if var[:type] == 'form'
+          form_field_names(var[:params][:layout]).map { |field| ["#{var[:name]}.#{field}", 'form field'] }
+        else
+          [[var[:name], var[:type]]]
+        end
+      end
+    end
+
+    # Renders the summary note + table. Returns a lambda that erases the output.
+    def self.show(vars)
+      display_rows = rows(vars)
+      names = display_rows.map { |name, _type| "{{#{name}}}" }.join(', ')
+      text = "Reference your variables in the replacement using {{var}} syntax:\n#{names}"
+      UI.note(text)
+      puts
+      Gum.table(display_rows, columns: %w[Name Type], print: true)
+      puts
+      build_erase(text, display_rows)
+    end
+
+    def self.form_field_names(layout)
+      FormFieldParser.extract(layout)
+    end
+    private_class_method :form_field_names
+
+    def self.build_erase(text, display_rows)
+      # UI.note lines + blank + table (top border + header + separator + data rows + bottom border) + blank
+      total = text.lines.count + 1 + display_rows.length + 4 + 1
+      CursorHelper.build_erase_lambda(total)
+    end
+    private_class_method :build_erase
+  end
+end

data/lib/snippet_cli/var_usage_checker.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'form_field_parser'
+
+module SnippetCli
+  # Checks variable usage in a single snippet match.
+  # Detects declared-but-unused vars and used-but-undeclared {{refs}}.
+  module VarUsageChecker
+    VAR_REF_PATTERN = /\{\{(\w+(?:\.\w+)?)\}\}/
+    REPLACEMENT_KEYS = %i[replace html markdown image_path].freeze
+
+    # Returns a hash { unused: [...], undeclared: [...] } of variable name arrays.
+    # vars: array of var hashes (symbol or string keyed)
+    # replacement: hash with one of :replace, :html, :markdown, :image_path
+    def self.match_warnings(vars, replacement, global_var_names: [])
+      declared = extract_names(vars)
+      used     = extract_refs(replacement)
+      known    = declared + Array(global_var_names)
+      {
+        unused: declared - used,
+        undeclared: used - known
+      }
+    end
+
+    def self.extract_names(vars)
+      Array(vars).flat_map do |v|
+        name = v[:name] || v['name']
+        next [] unless name
+
+        (v[:type] || v['type']).to_s == 'form' ? form_field_refs(name, v) : [name]
+      end
+    end
+    private_class_method :extract_names
+
+    def self.form_field_refs(name, var)
+      params = var[:params] || var['params'] || {}
+      layout = params[:layout] || params['layout'] || ''
+      FormFieldParser.extract(layout).map { |field| "#{name}.#{field}" }
+    end
+    private_class_method :form_field_refs
+
+    def self.extract_refs(replacement)
+      text = REPLACEMENT_KEYS.filter_map { |k| replacement[k] }.join
+      text.scan(VAR_REF_PATTERN).flatten.uniq
+    end
+    private_class_method :extract_refs
+  end
+end

data/lib/snippet_cli/var_yaml_renderer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'yaml_param_renderer'
+
+module SnippetCli
+  # Renders a single Espanso var entry as YAML lines.
+  # Used by SnippetBuilder and commands/vars to share a consistent rendering strategy.
+  module VarYamlRenderer
+    # Returns an array of YAML lines for one var hash ({ name:, type:, params: }).
+    def self.var_lines(var)
+      lines = ["  - name: #{var[:name]}", "    type: #{var[:type]}"]
+      params = var[:params]
+      return lines unless params&.any?
+
+      lines << '    params:'
+      params.each { |key, val| lines.concat(YamlParamRenderer.lines(key, val, '      ')) }
+      lines
+    end
+  end
+end

data/lib/snippet_cli/vars_block_renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'var_yaml_renderer'
+
+module SnippetCli
+  # Builds the vars: block as an array of YAML lines.
+  # indent: is prepended only to the vars: header; VarYamlRenderer owns var-entry indentation.
+  module VarsBlockRenderer
+    def self.render(vars, indent: '')
+      lines = ["#{indent}vars:"]
+      vars.each { |var| lines.concat(VarYamlRenderer.var_lines(var)) }
+      lines
+    end
+  end
+end

data/lib/snippet_cli/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module SnippetCli
-  VERSION = "0.3.6"
+  VERSION = '0.5.2'
 end