snippet_cli 0.3.6 → 0.5.2

data/lib/snippet_cli/hash_utils.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  # Shared hash-manipulation utilities used across validators.
+  module HashUtils
+    # Recursively converts symbol keys to string keys so the JSON schema
+    # validator can match property names. Symbol values are also stringified.
+    def self.stringify_keys_deep(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_keys_deep(v) }
+      when Array
+        obj.map { |item| stringify_keys_deep(item) }
+      when Symbol
+        obj.to_s
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/snippet_cli/match_file_writer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'file_helper'
+require_relative 'file_writer'
+require_relative 'string_helper'
+
+module SnippetCli
+  # Appends a generated snippet YAML string to an Espanso match file.
+  # Uses string-level append (not YAML round-trip) to preserve formatting.
+  module MatchFileWriter
+    # Appends the snippet to the given file, indenting it by 2 spaces
+    # to sit under the top-level `matches:` key.
+    def self.append(file_path, snippet_yaml)
+      existing = FileHelper.read_or_empty(file_path)
+      indented = snippet_yaml.lines.map { |line| "  #{line}" }.join
+      content = build_content(existing, indented)
+      FileWriter.write(file_path, content)
+    end
+
+    def self.build_content(existing, indented)
+      prefix = existing.strip.empty? ? "matches:\n" : StringHelper.ensure_trailing_newline(existing)
+      StringHelper.ensure_trailing_newline("#{prefix}#{indented}")
+    end
+    private_class_method :build_content
+  end
+end

data/lib/snippet_cli/match_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'hash_utils'
+require_relative 'schema_validator'
+
+module SnippetCli
+  # Validates an Espanso match entry (as a Ruby hash) against the vendored
+  # merged schema at vendor/espanso-schema-json/schemas/Espanso_Merged_Matchfile_Schema.json.
+  # Uses json_schemer which supports JSON Schema draft-07 (required for
+  # the if/then conditionals used in the Espanso match schema).
+  module MatchValidator
+    # Returns true if the data is valid against the Espanso match schema.
+    # Accepts symbol or string keys — keys are stringified before validation.
+    # The merged schema validates a full matchfile, so the entry is wrapped in
+    # a { "matches" => [...] } envelope before validation.
+    def self.valid?(data)
+      SchemaValidator.valid?(wrap(HashUtils.stringify_keys_deep(data)))
+    end
+
+    # Returns an array of human-readable error strings.
+    # Empty array means the data is valid.
+    def self.errors(data)
+      SchemaValidator.validate(wrap(HashUtils.stringify_keys_deep(data))).map do |error|
+        error['error'] || error.fetch('type', 'validation error')
+      end
+    end
+
+    def self.wrap(entry)
+      { 'matches' => [entry] }
+    end
+    private_class_method :wrap
+  end
+end

data/lib/snippet_cli/new_workflow.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'var_builder'
+require_relative 'snippet_builder'
+require_relative 'ui'
+require_relative 'wizard_helpers/match_file_selector'
+require_relative 'wizard_helpers/error_handler'
+require_relative 'wizard_context'
+require_relative 'trigger_resolver'
+require_relative 'replacement_wizard'
+require_relative 'espanso_config'
+require_relative 'match_file_writer'
+require_relative 'global_vars_writer'
+
+module SnippetCli
+  # Thin orchestrator for the new-snippet wizard.
+  # Sequences collaborators (TriggerResolver, ReplacementWizard, SnippetBuilder)
+  # but contains no Gum/UI calls or business rules itself.
+  class NewWorkflow
+    include WizardHelpers::MatchFileSelector
+    include WizardHelpers::ErrorHandler
+    include TriggerResolver
+
+    def run(opts)
+      handle_errors(ValidationError, EspansoConfigError, YamlScalar::InvalidCharacterError, NoMatchFilesError) do
+        context = prepare_context(opts)
+        yaml, summary_clear = build_snippet(opts, context)
+        deliver_snippet(yaml, context, summary_clear)
+      end
+    end
+
+    private
+
+    def prepare_context(opts)
+      pipe_output = SnippetCli.pipe_output
+      return WizardContext.new(pipe_output: pipe_output) unless opts[:save]
+
+      chosen, save_path = pick_match_file
+      @file_note_clear = UI.transient_note("Using #{chosen}") if EspansoConfig.match_files.size == 1
+      global_var_names = GlobalVarsWriter.read_names(save_path)
+      WizardContext.new(save_path: save_path, global_var_names: global_var_names, pipe_output: pipe_output)
+    end
+
+    def build_snippet(opts, context)
+      resolution = resolve_triggers(opts)
+      @file_note_clear&.call
+      replacement_hash, summary_clear = resolve_replacement(
+        no_vars: opts[:no_vars], bare: opts[:bare], global_var_names: context.global_var_names
+      )
+      [assemble_yaml(resolution, replacement_hash), summary_clear]
+    end
+
+    def assemble_yaml(resolution, replacement_hash)
+      SnippetBuilder.build(
+        triggers: resolution.list,
+        is_regex: resolution.is_regex,
+        single_trigger: resolution.single_trigger,
+        **replacement_hash
+      )
+    end
+
+    def resolve_replacement(no_vars: false, bare: false, global_var_names: [])
+      wizard = ReplacementWizard.new
+      if bare
+        [{ replace: wizard.collect_plain_replace, vars: [], label: nil, comment: nil }, nil]
+      elsif no_vars
+        [collect_no_vars_replacement(wizard, global_var_names: global_var_names), nil]
+      else
+        collect_full_replacement(wizard, global_var_names: global_var_names)
+      end
+    end
+
+    def collect_no_vars_replacement(wizard, global_var_names: [])
+      replacement = wizard.collect([], global_var_names: global_var_names)
+      advanced = wizard.collect_advanced_options
+      { vars: [] }.merge(advanced).merge(replacement)
+    end
+
+    def collect_full_replacement(wizard, global_var_names: [])
+      result = VarBuilder.run
+      vars, summary_clear = result.values_at(:vars, :summary_clear)
+      replacement = wizard.collect(vars, global_var_names: global_var_names)
+      advanced = wizard.collect_advanced_options
+      [{ vars: vars }.merge(advanced).merge(replacement), summary_clear]
+    end
+
+    def deliver_snippet(yaml, context, summary_clear)
+      summary_clear&.call
+      write_save(yaml, context.save_path) if context.save_path
+      UI.deliver(yaml, label: 'Snippet', context: context)
+    end
+
+    def write_save(yaml, save_path)
+      MatchFileWriter.append(save_path, yaml)
+      UI.success("Saved to #{File.basename(save_path)}")
+    end
+  end
+end

data/lib/snippet_cli/replacement_text_collector.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'wizard_helpers/prompt_helpers'
+require_relative 'wizard_helpers/validation_loop'
+
+module SnippetCli
+  # Collects replacement text from interactive Gum prompts.
+  # Handles plain-text (single and multi-line) and alt-type (markdown, html, image_path) inputs.
+  module ReplacementTextCollector
+    include WizardHelpers::PromptHelpers
+    include WizardHelpers::ValidationLoop
+
+    EMPTY_REPLACE_WARNING = 'Replace value is empty. Continue with no replacement text?'
+
+    private
+
+    def collect_replace(_vars)
+      loop do
+        value = prompt!(gum_replace_input(confirm!('Multi-line replacement?')))
+        next if value.strip.empty? && !confirm!(EMPTY_REPLACE_WARNING)
+
+        return value
+      end
+    end
+
+    def gum_replace_input(multiline)
+      style = UI::PROMPT_STYLE
+      if multiline
+        Gum.write(header: 'Replacement', placeholder: 'Type expansion text...',
+                  prompt_style: style, header_style: style)
+      else
+        Gum.input(placeholder: 'Replacement text', prompt_style: style, header_style: style)
+      end
+    end
+
+    def collect_alt_value(type)
+      prompt_non_empty_replace { prompt_alt_input(type) }
+    end
+
+    def prompt_alt_input(type)
+      style = UI::PROMPT_STYLE
+      if type == :image_path
+        prompt!(Gum.input(placeholder: '/path/to/image.png', prompt_style: style, header_style: style))
+      else
+        prompt!(Gum.write(header: type.to_s.capitalize, placeholder: "Enter #{type}...",
+                          prompt_style: style, header_style: style))
+      end
+    end
+
+    def prompt_non_empty_replace(&)
+      prompt_non_empty('Replacement cannot be empty. Please enter replacement text.', &)
+    end
+  end
+end

data/lib/snippet_cli/replacement_validator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'ui'
+require_relative 'var_usage_checker'
+require_relative 'wizard_helpers/prompt_helpers'
+
+module SnippetCli
+  # Validates replacement data against declared vars.
+  # Returns a clear lambda when the user wants to retry, nil when they accept or there are no issues.
+  module ReplacementValidator
+    include WizardHelpers::PromptHelpers
+
+    private
+
+    def var_error_clear(vars, replacement, global_var_names: [])
+      result = VarUsageChecker.match_warnings(vars, replacement, global_var_names: global_var_names)
+      return nil if result[:unused].empty? && result[:undeclared].empty?
+
+      display_var_warnings(result)
+      return nil if confirm!('Are you sure you want to continue?')
+
+      -> {}
+    end
+
+    def display_var_warnings(result)
+      result[:unused].each do |name|
+        UI.warning("Variable '#{name}' is declared but unused — add {{#{name}}} to the replacement text.")
+      end
+      result[:undeclared].each do |name|
+        UI.warning("'{{#{name}}}' appears in the replacement but was not declared as a variable. " \
+                   "Remove {{#{name}}} from the replacement.")
+      end
+    end
+  end
+end

data/lib/snippet_cli/replacement_wizard.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'ui'
+require_relative 'wizard_helpers/prompt_helpers'
+require_relative 'wizard_helpers/validation_loop'
+require_relative 'replacement_text_collector'
+require_relative 'replacement_validator'
+
+module SnippetCli
+  # Handles all interactive replacement collection for the new-snippet wizard.
+  # Keeps Gum/UI calls out of NewWorkflow so orchestration and domain logic
+  # can be read and tested without UI concerns.
+  class ReplacementWizard
+    include WizardHelpers::PromptHelpers
+    include WizardHelpers::ValidationLoop
+    include ReplacementTextCollector
+    include ReplacementValidator
+
+    # Collects a replacement hash (type + value) with var validation.
+    # Returns e.g. { replace: '...' } or { markdown: '...' } or { image_path: '...', vars: [] }.
+    def collect(vars, global_var_names: [])
+      collect_replacement(vars, global_var_names: global_var_names)
+    end
+
+    # Collects advanced snippet options (label, comment, search_terms, word, propagate_case).
+    # Returns a hash with all keys present (nil/false/[] for declined options).
+    def collect_advanced_options
+      return { label: nil, comment: nil, search_terms: [] } unless confirm!('Show advanced options?')
+
+      advanced_options_hash
+    end
+
+    # Collects plain replacement text only (used for --bare mode).
+    def collect_plain_replace
+      collect_replace([])
+    end
+
+    private
+
+    def advanced_options_hash
+      {
+        label: optional_label,
+        comment: optional_comment,
+        search_terms: collect_search_terms,
+        word: (true if confirm!('Word trigger?')),
+        propagate_case: (true if confirm!('Propagate case?'))
+      }
+    end
+
+    def optional_label
+      optional_prompt('Add a label?') do
+        prompt!(Gum.input(placeholder: 'Label', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE))
+      end
+    end
+
+    def optional_comment
+      optional_prompt('Add a comment?') do
+        prompt!(Gum.input(placeholder: 'Comment', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE))
+      end
+    end
+
+    def collect_replacement(vars, global_var_names: [])
+      if confirm!('Use a non-plaintext replacement type?')
+        select_alt_type(vars, global_var_names: global_var_names)
+      else
+        collect_with_check(vars, global_var_names: global_var_names) { { replace: collect_replace(vars) } }
+      end
+    end
+
+    def select_alt_type(vars, global_var_names: [])
+      type = prompt!(Gum.filter('markdown', 'html', 'image_path', limit: 1, header: 'Replacement type'))
+      return select_alt_type(vars, global_var_names: global_var_names) if image_path_discard_declined?(type, vars)
+
+      if type == 'image_path'
+        collect_alt_with_check(:image_path, [], global_var_names: global_var_names).merge(vars: [])
+      else
+        collect_alt_with_check(type.to_sym, vars, global_var_names: global_var_names)
+      end
+    end
+
+    def image_path_discard_declined?(type, vars)
+      return false unless type == 'image_path' && vars.any?
+
+      UI.info('image_path does not support vars — they will be dropped.')
+      !confirm!('Drop vars and continue with image_path?')
+    end
+
+    def collect_alt_with_check(type, vars, global_var_names: [])
+      collect_with_check(vars, global_var_names: global_var_names) { { type => collect_alt_value(type) } }
+    end
+
+    def collect_with_check(vars, global_var_names: [])
+      prompt_until_valid do
+        replacement = yield
+        [replacement, var_error_clear(vars, replacement, global_var_names: global_var_names)]
+      end
+    end
+  end
+end

data/lib/snippet_cli/schema_validator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'json_schemer'
+
+module SnippetCli
+  # Loads the vendored Espanso merged matchfile schema once and exposes
+  # valid?/validate for use by MatchValidator and FileValidator.
+  # Callers are responsible for stringifying keys before passing data.
+  module SchemaValidator
+    SCHEMA_PATH = File.expand_path(
+      'Espanso_Merged_Matchfile_Schema.json', __dir__
+    ).freeze
+
+    def self.valid?(data)
+      schemer.valid?(data)
+    end
+
+    def self.validate(data)
+      schemer.validate(data)
+    end
+
+    def self.schemer
+      @schemer ||= JSONSchemer.schema(Pathname.new(SCHEMA_PATH))
+    end
+    private_class_method :schemer
+  end
+end

data/lib/snippet_cli/snippet_builder.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'match_validator'
+require_relative 'vars_block_renderer'
+require_relative 'yaml_param_renderer'
+require_relative 'yaml_scalar'
+
+module SnippetCli
+  # Raised when the match data fails schema validation.
+  class ValidationError < StandardError; end
+
+  module SnippetBuilder
+    # Builds an Espanso match YAML entry from the given parameters.
+    # Validates against the Espanso match JSON schema before generating YAML.
+    # Raises ValidationError on failure.
+    def self.build(**opts)
+      validate!(opts)
+      render_yaml(opts)
+    end
+
+    def self.validate!(opts)
+      schema_errors = MatchValidator.errors(to_match_hash(opts))
+      return if schema_errors.empty?
+
+      raise ValidationError, "Schema validation failed:\n#{schema_errors.map { |err| "  - #{err}" }.join("\n")}"
+    end
+    private_class_method :validate!
+
+    def self.render_yaml(opts)
+      lines = trigger_lines(opts[:triggers], opts[:is_regex], opts[:single_trigger])
+      lines.concat(vars_lines(opts[:vars])) if opts[:vars]&.any?
+      lines.concat(replacement_lines(opts))
+      append_optional_fields(lines, opts)
+      "#{lines.join("\n")}\n"
+    end
+    private_class_method :render_yaml
+
+    def self.replacement_lines(opts)
+      return replace_lines(opts[:replace]) if opts[:replace]
+      return ["  image_path: #{YamlScalar.quote(opts[:image_path])}"] if opts[:image_path]
+      return block_scalar_lines('html', opts[:html]) if opts[:html]
+      return block_scalar_lines('markdown', opts[:markdown]) if opts[:markdown]
+
+      []
+    end
+    private_class_method :replacement_lines
+
+    def self.block_scalar_lines(key, val)
+      YamlParamRenderer.scalar_lines(key, val, '  ')
+    end
+    private_class_method :block_scalar_lines
+
+    def self.append_optional_fields(lines, opts)
+      append_label_and_comment(lines, opts)
+      append_search_terms(lines, opts[:search_terms])
+      append_trigger_modifiers(lines, opts)
+    end
+    private_class_method :append_optional_fields
+
+    def self.append_label_and_comment(lines, opts)
+      lines << "  label: #{YamlScalar.quote(opts[:label])}" if opts[:label]&.then { !it.empty? }
+      lines << "  comment: #{YamlScalar.quote(opts[:comment])}" if opts[:comment]&.then { !it.empty? }
+    end
+    private_class_method :append_label_and_comment
+
+    def self.append_trigger_modifiers(lines, opts)
+      return if opts[:image_path]
+
+      lines << '  word: true' if opts[:word]
+      lines << '  propagate_case: true' if opts[:propagate_case]
+    end
+    private_class_method :append_trigger_modifiers
+
+    def self.append_search_terms(lines, terms)
+      return unless terms&.any?
+
+      lines << '  search_terms:'
+      terms.each { |t| lines << "    - #{YamlScalar.quote(t)}" }
+    end
+    private_class_method :append_search_terms
+
+    def self.trigger_lines(triggers, is_regex, single_trigger)
+      if is_regex
+        ["- regex: #{YamlScalar.quote(triggers.first)}"]
+      elsif single_trigger
+        ["- trigger: #{YamlScalar.quote(triggers.first)}"]
+      else
+        ['- triggers:'] + triggers.map { |t| "    - #{YamlScalar.quote(t)}" }
+      end
+    end
+    private_class_method :trigger_lines
+
+    def self.vars_lines(vars)
+      VarsBlockRenderer.render(vars, indent: '  ')
+    end
+    private_class_method :vars_lines
+
+    def self.replace_lines(str)
+      block_scalar_lines('replace', str)
+    end
+    private_class_method :replace_lines
+
+    def self.to_match_hash(opts)
+      hash = build_trigger_hash(opts)
+      merge_optional(hash, opts, :replace, :image_path, :html, :markdown, :vars, :label, :comment, :search_terms)
+      merge_optional(hash, opts, :word, :propagate_case) unless opts[:image_path]
+      hash
+    end
+    private_class_method :to_match_hash
+
+    def self.merge_optional(hash, opts, *keys)
+      keys.each { |key| hash[key] = opts[key] unless skip_key?(key, opts[key]) }
+      hash
+    end
+    private_class_method :merge_optional
+
+    def self.skip_key?(key, val)
+      val.nil? || (val.is_a?(Array) && val.empty?) || (val.is_a?(String) && val.empty? && key != :replace)
+    end
+    private_class_method :skip_key?
+
+    def self.build_trigger_hash(opts)
+      if opts[:is_regex]
+        { regex: opts[:triggers].first }
+      elsif opts[:single_trigger]
+        { trigger: opts[:triggers].first }
+      else
+        { triggers: opts[:triggers] }
+      end
+    end
+    private_class_method :build_trigger_hash
+  end
+end

data/lib/snippet_cli/string_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  # Utility methods for string manipulation.
+  module StringHelper
+    # Returns str with a trailing newline, appending one if not already present.
+    def self.ensure_trailing_newline(str)
+      str.end_with?("\n") ? str : "#{str}\n"
+    end
+  end
+end

data/lib/snippet_cli/table_formatter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  module TableFormatter
+    def self.render(rows, headers:)
+      widths = column_widths(rows, headers)
+      lines = [
+        border_line(widths, left: '╭', mid: '┬', right: '╮'),
+        data_line(headers, widths),
+        border_line(widths, left: '├', mid: '┼', right: '┤'),
+        *rows.map { |row| data_line(row, widths) },
+        border_line(widths, left: '╰', mid: '┴', right: '╯')
+      ]
+      lines.map { |line| colorize(line) }.join("\n")
+    end
+
+    def self.column_widths(rows, headers)
+      headers.each_with_index.map { |h, i| [h.length, *rows.map { |r| r[i].to_s.length }].max }
+    end
+    private_class_method :column_widths
+
+    def self.border_line(widths, left:, mid:, right:)
+      "#{left}#{widths.map { |w| '─' * (w + 2) }.join(mid)}#{right}"
+    end
+    private_class_method :border_line
+
+    def self.data_line(cells, widths)
+      "│#{cells.each_with_index.map { |cell, i| " #{cell.to_s.ljust(widths[i])} " }.join('│')}│"
+    end
+    private_class_method :data_line
+
+    def self.colorize(line)
+      "\e[97m#{line}\e[0m"
+    end
+    private_class_method :colorize
+  end
+end

data/lib/snippet_cli/trigger_resolver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'ui'
+require_relative 'wizard_helpers/prompt_helpers'
+require_relative 'wizard_helpers/validation_loop'
+
+module SnippetCli
+  # Resolves trigger input from CLI flags or interactive prompts.
+  module TriggerResolver
+    TriggerResolution = Struct.new(:list, :is_regex, :single_trigger)
+
+    include WizardHelpers::PromptHelpers
+    include WizardHelpers::ValidationLoop
+
+    RUST_REGEX_GUIDANCE = "Espanso uses Rust Regex syntax. Ensure this is a valid Rust regex.\n" \
+                          'https://docs.rs/regex/1.1.8/regex/#syntax'
+
+    private
+
+    def resolve_triggers(opts)
+      resolve_triggers_interactively(opts)
+    end
+
+    def resolve_triggers_interactively(_opts)
+      type = prompt!(Gum.choose('regular', 'regex', header: "Trigger type?\n", header_style: UI::PROMPT_STYLE))
+      list, is_regex = collect_triggers(type)
+      TriggerResolution.new(list, is_regex, false)
+    end
+
+    def collect_triggers(type)
+      if type == 'regex'
+        UI.info(RUST_REGEX_GUIDANCE)
+        puts
+        trigger = prompt_non_empty_trigger('r"^(hello|bye)$"')
+        return [[trigger], true]
+      end
+
+      [prompt_trigger_loop, false]
+    end
+
+    def prompt_non_empty_trigger(placeholder, header: nil)
+      prompt_non_empty('Trigger cannot be empty. Please enter a trigger string.') do
+        prompt!(Gum.input(**trigger_input_opts(placeholder, header)))
+      end
+    end
+
+    def multi_trigger_header
+      "Multiple triggers can share one replacement.\nEnter them one at a time.\n"
+    end
+
+    def trigger_input_opts(placeholder, header)
+      opts = { placeholder: placeholder, prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE }
+      opts[:header] = header if header
+      opts
+    end
+
+    def prompt_trigger_loop
+      triggers = []
+      loop do
+        header = triggers.empty? ? multi_trigger_header : nil
+        triggers << prompt_non_empty_trigger(':trigger', header: header)
+        break unless list_confirm!('trigger', triggers.map { |t| [t] }, ['Trigger'], 'Add another trigger?')
+      end
+      triggers
+    end
+  end
+end