snippet_cli 0.3.6 → 0.5.2

data/lib/snippet_cli/wizard_context.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  # Carries shared wizard configuration: which file to save to,
+  # which global var names are already declared in that file,
+  # and the pipe IO for structured output when stdout is redirected.
+  # Passed explicitly rather than communicated via global state.
+  WizardContext = Data.define(:global_var_names, :save_path, :pipe_output) do
+    def initialize(global_var_names: [], save_path: nil, pipe_output: nil)
+      super
+    end
+  end
+end

data/lib/snippet_cli/wizard_helpers/error_handler.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  module WizardHelpers
+    # Wraps a command body with standard error handling.
+    # Rescues WizardInterrupted (Ctrl+C) universally.
+    # Rescues typed error_classes passed by the caller, displaying their message via UI.error and exiting 1.
+    module ErrorHandler
+      def handle_errors(*error_classes)
+        yield
+      rescue *error_classes => e
+        UI.error(e.message)
+        exit 1
+      rescue WizardInterrupted
+        puts
+        UI.error('Interrupted, exiting snippet_cli.')
+      end
+    end
+  end
+end

data/lib/snippet_cli/wizard_helpers/match_file_selector.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'gum'
+require_relative 'prompt_helpers'
+
+module SnippetCli
+  module WizardHelpers
+    # Selects an Espanso match file for saving.
+    # Auto-selects when only one file exists; otherwise prompts via Gum.filter.
+    module MatchFileSelector
+      include PromptHelpers
+
+      # Returns [basename, full_path] of the chosen match file.
+      # Raises NoMatchFilesError when no files exist.
+      def pick_match_file
+        files = EspansoConfig.match_files
+        abort_no_match_files if files.empty?
+        return [File.basename(files.first), files.first] if files.size == 1
+
+        basenames = files.map { |f| File.basename(f) }
+        chosen = prompt!(Gum.filter(*basenames, header: 'Save to which match file?'))
+        [chosen, files.find { |f| File.basename(f) == chosen }]
+      end
+
+      private
+
+      def abort_no_match_files
+        raise NoMatchFilesError, 'No match files found in Espanso config.'
+      end
+    end
+  end
+end

data/lib/snippet_cli/wizard_helpers/prompt_helpers.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'gum'
+require_relative '../table_formatter'
+
+module SnippetCli
+  module WizardHelpers
+    # Gum prompt primitives with Ctrl+C detection via WizardInterrupted.
+    module PromptHelpers
+      # Returns the value if non-nil; raises WizardInterrupted otherwise.
+      # Gum.choose / .input / .filter / .write return nil on Ctrl+C.
+      def prompt!(value)
+        raise WizardInterrupted if value.nil?
+
+        value
+      rescue Interrupt
+        raise WizardInterrupted
+      end
+
+      # Wraps Gum.confirm and checks $?.exitstatus for 130 (Ctrl+C).
+      # Gum.confirm uses system() which swallows SIGINT and returns false,
+      # making it indistinguishable from the user answering "no" — except
+      # that $? records the child's exit code 130.
+      # SIGINT can also raise Interrupt in Ruby before $? is read.
+      def confirm!(text)
+        result = Gum.confirm(text, prompt_style: UI::PROMPT_STYLE)
+        raise WizardInterrupted if result.nil?
+        raise WizardInterrupted if $CHILD_STATUS.respond_to?(:exitstatus) && $CHILD_STATUS.exitstatus == 130
+
+        result
+      rescue Interrupt
+        raise WizardInterrupted
+      end
+
+      # Renders a table of collected items and asks a follow-up question, without a border.
+      def list_confirm!(label, rows, headers, question)
+        table = TableFormatter.render(rows, headers: headers)
+        confirm!("Current #{label}s:\n\n#{table}\n\n#{question}")
+      end
+
+      # Confirms a question then collects a value via the block, or returns nil if declined.
+      def optional_prompt(question)
+        yield if confirm!(question)
+      end
+
+      # Prompts for search terms via a multiline write block.
+      # Returns an empty array if the user declines.
+      def collect_search_terms
+        return [] unless confirm!('Add search terms?')
+
+        raw = prompt!(Gum.write(header: 'Put one search term per line', prompt_style: UI::PROMPT_STYLE, header_style: UI::PROMPT_STYLE))
+        raw.to_s.lines.map(&:chomp).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/snippet_cli/wizard_helpers/validation_loop.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  module WizardHelpers
+    # Loop-until-valid prompt abstractions.
+    module ValidationLoop
+      # General loop-until-valid primitive.
+      # The block must yield [value, error_or_nil].
+      # When error is a String, shows it as a transient warning.
+      # When error is a Callable (e.g. a lambda), uses it directly as the clear function.
+      # Loops until the block yields a nil error.
+      def prompt_until_valid
+        clear = nil
+        loop do
+          value, error = yield
+          clear&.call
+          return value if error.nil?
+
+          clear = error.respond_to?(:call) ? error : UI.transient_warning(error)
+        end
+      end
+
+      # Loops until the block yields a non-empty string.
+      # Shows warning_message as a transient warning on empty input.
+      def prompt_non_empty(warning_message, &prompt_block)
+        prompt_until_valid do
+          value = prompt_block.call
+          [value, value.strip.empty? ? warning_message : nil]
+        end
+      end
+    end
+  end
+end

data/lib/snippet_cli/wizard_helpers.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Convenience require — loads all focused WizardHelpers sub-modules.
+# Prefer requiring only the specific sub-module your class needs.
+require_relative 'wizard_helpers/prompt_helpers'
+require_relative 'wizard_helpers/validation_loop'
+require_relative 'wizard_helpers/match_file_selector'
+require_relative 'wizard_helpers/error_handler'

data/lib/snippet_cli/yaml_line_resolver.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'psych'
+
+module SnippetCli
+  # Resolves a JSON Pointer (e.g. "/matches/354") to a 1-based line number
+  # in a YAML file by navigating the Psych AST node tree.
+  module YamlLineResolver
+    # Returns the 1-based line number for the given JSON pointer, or nil if
+    # the pointer is empty, invalid, or cannot be resolved in the file.
+    def self.resolve(file, pointer)
+      return nil if pointer.to_s.empty?
+
+      segments = pointer.to_s.sub(%r{\A/}, '').split('/')
+      return nil if segments.empty?
+
+      tree = Psych.parse_file(file)
+      node = navigate(tree.root, segments)
+      node&.start_line&.+(1)
+    rescue StandardError
+      nil
+    end
+
+    def self.navigate(node, segments)
+      return node if segments.empty?
+
+      seg, *rest = segments
+      case node
+      when Psych::Nodes::Document  then navigate(node.root, segments)
+      when Psych::Nodes::Mapping   then navigate_mapping(node, seg, rest)
+      when Psych::Nodes::Sequence  then navigate(node.children[Integer(seg, 10)], rest)
+      end
+    rescue ArgumentError, TypeError
+      nil
+    end
+    private_class_method :navigate
+
+    def self.navigate_mapping(node, key, rest)
+      node.children.each_slice(2) do |k, v|
+        return navigate(v, rest) if k.value == key
+      end
+      nil
+    end
+    private_class_method :navigate_mapping
+  end
+end

data/lib/snippet_cli/yaml_loader.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'file_helper'
+
+module SnippetCli
+  # Shared YAML file loading with existence check and syntax-error handling.
+  module YamlLoader
+    # Loads and parses a YAML file.
+    # Raises FileMissingError if the file does not exist.
+    # Raises InvalidYamlError if the file contains invalid YAML syntax.
+    def self.load(path, permitted_classes: [Symbol])
+      FileHelper.ensure_readable!(path)
+      YAML.safe_load_file(path, permitted_classes: permitted_classes) || {}
+    rescue Psych::SyntaxError => e
+      raise InvalidYamlError, "Invalid YAML: #{e.message}"
+    end
+  end
+end

data/lib/snippet_cli/yaml_param_renderer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'yaml_scalar'
+
+module SnippetCli
+  # Renders variable param key/value pairs as YAML lines with proper indentation.
+  module YamlParamRenderer
+    def self.lines(key, val, indent)
+      case val
+      when Hash  then hash_lines(key, val, indent)
+      when Array then ["#{indent}#{key}:", *val.map { |item| "#{indent}  - #{YamlScalar.quote(item.to_s)}" }]
+      when true, false then ["#{indent}#{key}: #{val}"]
+      else scalar_lines(key, val.to_s, indent)
+      end
+    end
+
+    def self.hash_lines(key, hash, indent)
+      result = ["#{indent}#{key}:"]
+      hash.each { |k, v| result.concat(lines(k, v, "#{indent}  ")) }
+      result
+    end
+    private_class_method :hash_lines
+
+    def self.scalar_lines(key, str, indent)
+      if str.include?("\n")
+        indented = str.lines.map { |line| "#{indent}  #{line.chomp}" }.join("\n")
+        ["#{indent}#{key}: |", indented]
+      else
+        ["#{indent}#{key}: #{YamlScalar.quote(str)}"]
+      end
+    end
+  end
+end

data/lib/snippet_cli/yaml_scalar.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SnippetCli
+  # Helpers for quoting scalar values in hand-built YAML output.
+  module YamlScalar
+    class InvalidCharacterError < StandardError; end
+
+    BOOLEAN_LIKE = /\A(y|n|yes|no|true|false|on|off|null|~)\z/i
+    LEADING_SPECIAL = /\A[:#&*!|>"%@`{}\[\]]/
+    # Control characters that are invalid in YAML scalars (excludes tab \x09, newline \x0a, carriage return \x0d)
+    CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/
+
+    # Quote a scalar value for YAML output.
+    # Strategy (per yaml-multiline.info):
+    #   - string containing '  → normal-quoted with escaped inner content
+    #   - string matching special YAML patterns → normal-quoted
+    #   - all other strings → single-quoted
+    def self.quote(str)
+      return "''" if str.nil? || str.empty?
+
+      reject_control_chars!(str)
+
+      if str.include?("'")
+        escaped = str.gsub('\\', '\\\\\\\\').gsub('"', '\\"')
+        return "\"#{escaped}\""
+      end
+
+      return "\"#{str.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}\"" if needs_normal_quote?(str)
+
+      "'#{str}'"
+    end
+
+    def self.reject_control_chars!(str)
+      return unless CONTROL_CHARS.match?(str)
+
+      raise InvalidCharacterError, "String contains YAML-invalid control characters: #{str.inspect}"
+    end
+    private_class_method :reject_control_chars!
+
+    def self.needs_normal_quote?(str)
+      LEADING_SPECIAL.match?(str) ||
+        BOOLEAN_LIKE.match?(str) ||
+        str.include?(': ') ||
+        str.include?(' #')
+    end
+    private_class_method :needs_normal_quote?
+  end
+end

data/lib/snippet_cli.rb

@@ -1,4 +1,47 @@
-require "snippet_cli/version"
+# frozen_string_literal: true
+
+require 'dry/cli'
+require_relative 'snippet_cli/version'
+require_relative 'snippet_cli/commands/version'
+require_relative 'snippet_cli/commands/conflict'
+require_relative 'snippet_cli/commands/vars'
+require_relative 'snippet_cli/commands/new'
+require_relative 'snippet_cli/commands/check'
 
 module SnippetCli
+  # Raised when any Gum prompt is cancelled by Ctrl+C.
+  class WizardInterrupted < StandardError; end
+
+  # Raised by FileHelper when a required file does not exist.
+  class FileMissingError < StandardError; end
+
+  # Raised by YamlLoader when a file contains invalid YAML syntax.
+  class InvalidYamlError < StandardError; end
+
+  # Raised by TriggerResolver when mutually exclusive trigger flags are combined.
+  class InvalidFlagsError < StandardError; end
+
+  # Raised by WizardHelpers when no Espanso match files are found.
+  class NoMatchFilesError < StandardError; end
+
+  # Raised by VarBuilder::Params when collected params violate the type's schema.
+  class InvalidParamsError < StandardError; end
+
+  # When stdout is piped, holds the original stdout IO for structured output (YAML).
+  # All UI continues through $stdout (redirected to the terminal).
+  @pipe_output = nil
+
+  class << self
+    attr_accessor :pipe_output
+  end
+
+  module CLI
+    extend Dry::CLI::Registry
+
+    register 'version',  Commands::Version
+    register 'conflict', Commands::Conflict, aliases: ['c']
+    register 'vars',  Commands::Vars,  aliases: ['v']
+    register 'new',   Commands::New,   aliases: ['n']
+    register 'check', Commands::Check, aliases: ['k']
+  end
 end