issuer 0.1.0

data/lib/issuer/cli.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'thor'
+
+module Issuer
+  class CLI < Thor
+    # Silence Thor deprecation warning
+    def self.exit_on_failure?
+      true
+    end
+
+    # Define class-level options for access in help
+    class_option :file, type: :string, desc: 'IMYML file path (alternative to positional argument)'
+    class_option :proj, type: :string, desc: 'Override $meta.proj (org/repo)'
+    class_option :vrsn, type: :string, desc: 'Default version for all issues'
+    class_option :user, type: :string, desc: 'Default assignee (GitHub username)'
+    class_option :tags, type: :string, desc: 'Comma-separated extra labels for all issues'
+    class_option :stub, type: :boolean, desc: 'Enable stub mode for all issues'
+    class_option :dry, type: :boolean, default: false, desc: 'Print issues, don\'t post'
+    class_option :tokenv, type: :string, desc: 'Name of environment variable containing GitHub token'
+
+    # Resource automation options
+    class_option :auto_versions, type: :boolean, aliases: ['--auto-milestones'], desc: 'Automatically create missing versions/milestones without prompting'
+    class_option :auto_tags, type: :boolean, aliases: ['--auto-labels'], desc: 'Automatically create missing tags/labels without prompting'
+    class_option :auto_metadata, type: :boolean, desc: 'Automatically create all missing metadata (versions and tags) without prompting'
+
+    class_option :help, type: :boolean, aliases: ['-h'], desc: 'Show help message'
+    class_option :version, type: :boolean, aliases: ['-v'], desc: 'Show version'
+
+    # Handle special options first
+    def self.start given_args=ARGV, config={}
+      # Handle --version option
+      if given_args.include?('--version') || given_args.include?('-v')
+        puts "Issuer version #{Issuer::VERSION}"
+        exit 0
+      end
+
+      # Handle --help option
+      if given_args.include?('--help') || given_args.include?('-h') || given_args.empty?
+        show_help
+        exit 0
+      end
+
+      # For all other cases, treat first argument as file and process as main command
+      given_args.unshift('main') unless given_args[0] == 'main'
+      super(given_args, config)
+    end
+
+    desc 'main [IMYML_FILE]', 'Create GitHub issues from an IMYML YAML file', hide: true
+
+    def main file=nil
+      # Handle options that should exit early
+      if options[:help]
+        self.class.show_help
+        return
+      end
+
+      if options[:version]
+        puts "Issuer version #{Issuer::VERSION}"
+        return
+      end
+
+      # Determine file path: --file option takes precedence over positional argument
+      file_path = options[:file] || file
+      if file_path.nil?
+        abort "Error: No IMYML file specified. Use 'issuer FILE' or 'issuer --file FILE'"
+      end
+
+      unless File.exist?(file_path)
+        abort "Error: File not found: #{file_path}"
+      end
+
+      begin
+        raw = File.open(file_path) { |f| YAML.load(f) }
+      rescue => e
+        abort "Error: Could not parse YAML file: #{file_path}\n#{e.message}"
+      end
+
+      if raw.nil?
+        abort "Error: YAML file appears to be empty: #{file_path}"
+      end
+
+      meta = raw['$meta'] || {}
+      issues_data = raw['issues'] || raw # fallback if no $meta
+
+      unless issues_data.is_a?(Array)
+        abort 'Error: No issues array found (root or under "issues")'
+      end
+
+      # Build defaults merging: CLI > $meta.defaults > issue
+      defaults = (meta['defaults'] || {}).dup
+      defaults['proj'] = meta['proj'] if meta['proj']
+      defaults['vrsn'] = options[:vrsn] if options[:vrsn]
+      defaults['user'] = options[:user] if options[:user]
+      defaults['stub'] = options[:stub] if !options[:stub].nil?
+
+      # Determine target repository
+      repo = options[:proj] || meta['proj'] || ENV['ISSUER_REPO'] || ENV['ISSUER_PROJ']
+      if repo.nil? && !options[:dry]
+        abort 'No target repo set. Use --proj, $meta.proj, or ENV[ISSUER_REPO].'
+      end
+
+      # Process issues with new Ops module
+      issues = Issuer::Ops.process_issues_data(issues_data, defaults)
+
+      # Apply tag logic (append vs default behavior)
+      issues = Issuer::Ops.apply_tag_logic(issues, options[:tags])
+
+      # Apply stub logic with head/tail/body composition
+      issues = Issuer::Ops.apply_stub_logic(issues, defaults)
+
+      # Separate valid and invalid issues
+      valid_issues = issues.select(&:valid?)
+      invalid_issues = issues.reject(&:valid?)
+
+      # Report invalid issues
+      invalid_issues.each_with_index do |issue, idx|
+        puts "Skipping issue ##{find_original_index(issues, issue) + 1}: #{issue.validation_errors.join(', ')}"
+      end
+
+      if options[:dry]
+        perform_dry_run(valid_issues, repo)
+      else
+        # Use Sites architecture for validation and posting
+        site_options = {}
+        site_options[:token_env_var] = options[:tokenv] if options[:tokenv]
+        site = Issuer::Sites::Factory.create('github', **site_options)
+        automation_options = {
+          auto_versions: options[:auto_versions] || options[:auto_metadata],
+          auto_tags: options[:auto_tags] || options[:auto_metadata]
+        }
+
+        # Start run tracking for live operations
+        require_relative 'cache'
+        run_id = Issuer::Cache.start_run(issues_planned: valid_issues.length)
+        puts "🏃 Started run #{run_id} - tracking #{valid_issues.length} issues"
+
+        begin
+          Issuer::Ops.validate_and_prepare_resources(site, repo, valid_issues, automation_options, run_id) unless valid_issues.empty?
+          processed_count = site.post_issues(repo, valid_issues, run_id)
+
+          # Complete the run successfully
+          Issuer::Cache.complete_run(run_id, processed_count)
+          puts "✅ Run #{run_id} completed successfully - #{processed_count} issues created"
+        rescue => e
+          # Mark run as failed
+          Issuer::Cache.fail_run(run_id, e.message)
+          puts "❌ Run #{run_id} failed: #{e.message}"
+          raise
+        end
+      end
+
+      print_summary(valid_issues.length, invalid_issues.length, options[:dry])
+    end
+
+    private
+
+    def self.show_help
+      puts <<~HELP
+      Issuer: Bulk GitHub issue creator from YAML definitions
+
+      Usage:
+        issuer IMYML_FILE [options]
+        issuer --file IMYML_FILE [options]
+
+      Issue Default Options:
+        --vrsn VERSION           #{self.class_options[:vrsn].description}
+        --user USERNAME          #{self.class_options[:user].description}
+        --tags tag1,tag2         #{self.class_options[:tags].description}
+        --stub                   #{self.class_options[:stub].description}
+
+      Site Options:
+        --proj org/repo          #{self.class_options[:proj].description}
+        --tokenv VAR_NAME        #{self.class_options[:tokenv].description}
+
+      Mode Options:
+        --dry                    #{self.class_options[:dry].description}
+        --auto-versions          #{self.class_options[:auto_versions].description}
+        --auto-milestones        (alias for --auto-versions)
+        --auto-tags              #{self.class_options[:auto_tags].description}
+        --auto-labels            (alias for --auto-tags)
+        --auto-metadata          #{self.class_options[:auto_metadata].description}
+
+      Info:
+        -h, --help               #{self.class_options[:help].description}
+        -v, --version            #{self.class_options[:version].description}
+
+      Examples:
+        issuer issues.yml --dry
+        issuer issues.yml --proj myorg/myrepo
+        issuer --file issues.yml --proj myorg/myrepo --dry
+        issuer issues.yml --vrsn 1.1.2
+        issuer --version
+        issuer --help
+
+      Authentication:
+      Set GITHUB_TOKEN environment variable with your GitHub personal access token
+      Or use --tokenv to specify a custom environment variable name
+
+      HELP
+    end
+
+    def find_original_index issues_array, target_issue
+      issues_array.find_index(target_issue) || 0
+    end
+
+    def perform_dry_run issues, repo
+      # Create site instance for parameter conversion in dry-run mode
+      site_options = { token: 'dry-run-token' }
+      site_options[:token_env_var] = options[:tokenv] if options[:tokenv]
+      site = Issuer::Sites::Factory.create('github', **site_options)
+
+      issues.each do |issue|
+        print_issue_summary(issue, repo, site)
+      end
+      
+      # Add project summary at the end
+      if repo
+        project_term = site.field_mappings[:project_name] || 'project'
+        puts "Would process #{issues.length} issues for #{project_term}: #{repo}"
+      end
+    end
+
+    def print_summary valid_count, invalid_count, dry_run
+      if dry_run
+        puts "\nDry run complete (use without --dry to actually post)"
+        puts "Would process #{valid_count} issues, skip #{invalid_count}"
+      else
+        puts "\n✅ Completed: #{valid_count} issues processed, #{invalid_count} skipped"
+        puts "Run ID: #{Issuer::Cache.current_run_id}" if Issuer::Cache.current_run_id
+      end
+      
+    end
+
+    def print_issue_summary issue, repo, site
+      # Use the new formatted output method from the Issue class
+      puts issue.formatted_output(site, repo)
+    end
+  end
+end

data/lib/issuer/issue.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+module Issuer
+  ##
+  # Represents a single issue in the IMYML format.
+  #
+  # The Issue class is the core data model that represents individual work items.
+  # It handles validation, default application, and processing of IMYML properties
+  # like stub composition and tag logic.
+  #
+  # == IMYML Properties
+  #
+  # +summ+:: (Required) Issue title/summary
+  # +body+:: Issue description/body text
+  # +tags+:: Array of labels to apply
+  # +user+:: Assignee username
+  # +vrsn+:: Milestone/version
+  # +stub+:: Whether to apply stub text composition
+  #
+  # == Tag Logic
+  #
+  # Tags support special prefix notation:
+  # * Regular tags (e.g., +"bug"+) are only applied if the issue has no existing tags
+  # * Append tags (e.g., +"+urgent"+) are always applied to all issues
+  #
+  # == Stub Composition
+  #
+  # When +stub+ is true, the final body is composed from:
+  # 1. +head+ text (if provided in defaults)
+  # 2. Issue +body+ or default +body+ 
+  # 3. +tail+ text (if provided in defaults)
+  #
+  # @example Creating an issue from IMYML data
+  #   data = {
+  #     'summ' => 'Fix authentication bug',
+  #     'body' => 'Users cannot log in',
+  #     'tags' => ['bug', '+urgent'],
+  #     'user' => 'developer1',
+  #     'vrsn' => '1.0.0'
+  #   }
+  #   issue = Issuer::Issue.new(data)
+  #   issue.valid? # => true
+  #
+  # @example Applying defaults
+  #   defaults = { 'user' => 'default-user', 'tags' => ['needs-triage'] }
+  #   issue = Issuer::Issue.new(minimal_data, defaults)
+  #
+  # @example Processing multiple issues
+  #   issues = Issuer::Issue.from_array(array_of_data, defaults)
+  #   valid_issues = Issuer::Issue.valid_issues_from_array(array_of_data, defaults)
+  #
+  class Issue
+    attr_reader :summ, :tags, :user, :vrsn, :raw_data
+    attr_accessor :body, :stub
+
+    ##
+    # Create a new Issue instance from IMYML data
+    #
+    # @param issue_data [Hash, String] The issue data from IMYML. If String, treated as +summ+.
+    # @param defaults [Hash] Default values to apply when issue data is missing properties
+    #
+    def initialize issue_data, defaults={}
+      @raw_data = issue_data || {}
+      @merged_data = defaults.merge(@raw_data)
+
+      @summ = @merged_data['summ']
+      @body = @merged_data['body'] || @merged_data['desc'] || '' # Support both body and desc (legacy)
+      @tags = Array(@merged_data['tags'])
+      @user = @merged_data['user']
+      @vrsn = @merged_data['vrsn']
+      @stub = @merged_data['stub']
+    end
+
+    ##
+    # Check if this issue has the minimum required data
+    #
+    # @return [Boolean] True if the issue has a non-empty +summ+ (title)
+    #
+    def valid?
+      !summ.nil? && !summ.strip.empty?
+    end
+
+    ##
+    # Get validation error messages for this issue
+    #
+    # @return [Array<String>] Array of error messages, empty if valid
+    #
+    def validation_errors
+      errors = []
+      errors << "missing required 'summ' field" if summ.nil? || summ.strip.empty?
+      errors
+    end
+
+    ##
+    # Add additional tags to this issue
+    #
+    # @param additional_tags [Array<String>, String] Tags to add, duplicates removed
+    # @return [Array<String>] The updated tags array
+    #
+    def add_tags additional_tags
+      @tags = (@tags + Array(additional_tags)).uniq
+    end
+
+    def summary_description
+      truncated_body = body.strip[0..50].gsub(/\n.*/m, '…')
+      {
+        summ: summ,
+        body_preview: truncated_body,
+        tags: tags,
+        user: user,
+        vrsn: vrsn
+      }
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Issue)
+
+      summ == other.summ &&
+        body == other.body &&
+        tags.sort == other.tags.sort &&
+        user == other.user &&
+        vrsn == other.vrsn
+    end
+
+    def self.from_array issues_array, defaults={}
+      issues_array.map { |issue_data| new(issue_data, defaults) }
+    end
+
+    def self.valid_issues_from_array issues_array, defaults={}
+      from_array(issues_array, defaults).select(&:valid?)
+    end
+
+    def self.invalid_issues_from_array issues_array, defaults={}
+      from_array(issues_array, defaults).reject(&:valid?)
+    end
+
+    # Apply tag logic (append vs default behavior)
+    def self.apply_tag_logic issues, cli_tags
+      # Parse CLI tags for append (+) vs default-only behavior
+      cli_append_tags, cli_default_tags = parse_tag_logic(cli_tags)
+
+      issues.each do |issue|
+        issue.apply_tag_logic(cli_append_tags, cli_default_tags)
+      end
+
+      issues
+    end
+
+    # Apply stub logic with head/tail/body composition
+    def self.apply_stub_logic issues, defaults
+      issues.each do |issue|
+        issue.apply_stub_logic(defaults)
+      end
+
+      issues
+    end
+
+    # Apply tag logic for this issue
+    # 
+    # Processes existing tags with + prefix as append tags, combines them with
+    # CLI-provided tags, and determines final tag set based on precedence rules.
+    # 
+    # @param cli_append_tags [Array<String>] Tags to always append from CLI
+    # @param cli_default_tags [Array<String>] Default tags from CLI (used when no regular tags exist)
+    # @return [void] Sets @tags instance variable
+    # 
+    # @example
+    #   # Issue has tags: ['+urgent', 'bug']
+    #   issue.apply_tag_logic(['cli-tag'], ['default-tag'])
+    #   # Result: ['urgent', 'cli-tag', 'bug']
+    def apply_tag_logic cli_append_tags, cli_default_tags
+      # Parse existing tags for + prefix
+      existing_tags = tags || []
+      append_tags = []
+      regular_tags = []
+
+      existing_tags.each do |tag|
+        if tag.to_s.start_with?('+')
+          append_tags << tag.to_s[1..] # Remove + prefix
+        else
+          regular_tags << tag.to_s
+        end
+      end
+
+      # Start with append tags (always applied)
+      final_tags = append_tags + cli_append_tags
+
+      # Add regular tags if the issue has them, otherwise add CLI default tags
+      if !regular_tags.empty?
+        final_tags.concat(regular_tags)
+      else
+        final_tags.concat(cli_default_tags)
+      end
+
+      # Set the final tags (removing duplicates)
+      @tags = final_tags.uniq
+    end
+
+    # Apply stub logic for this issue
+    # 
+    # Composes issue body by combining head, body, and tail components
+    # from defaults when stub application is enabled.
+    # 
+    # @param defaults [Hash] Default values containing 'head', 'body', 'tail', and 'stub' keys
+    # @return [void] Sets @body instance variable with composed content
+    # 
+    # @example
+    #   defaults = {'head' => 'Header', 'body' => 'Default body', 'tail' => 'Footer'}
+    #   issue.apply_stub_logic(defaults)
+    #   # Composes body as "Header\nIssue body\nFooter"
+    def apply_stub_logic defaults
+      return unless should_apply_stub?(defaults)
+
+      # Build body with stub components
+      body_parts = []
+
+      # Add head if present
+      if defaults['head'] && !defaults['head'].to_s.strip.empty?
+        body_parts << defaults['head'].to_s.strip
+      end
+
+      # Add main body (issue body or default body)
+      main_body = body
+      if main_body.nil? || main_body.to_s.strip.empty?
+        main_body = defaults['body'] if defaults['body']
+      end
+      body_parts << main_body.to_s.strip if main_body
+
+      # Add tail if present
+      if defaults['tail'] && !defaults['tail'].to_s.strip.empty?
+        body_parts << defaults['tail'].to_s.strip
+      end
+
+      # Set the composed body
+      @body = body_parts.join("\n")
+    end
+
+    # Parse tag logic from a comma-separated string
+    # 
+    # Separates tags with + prefix (append tags) from regular tags (default tags).
+    # Tags with + prefix are always applied, while regular tags are only used
+    # when the issue has no existing regular tags.
+    # 
+    # @param tags_string [String] Comma-separated tag string
+    # @return [Array<Array<String>>] Two-element array: [append_tags, default_tags]
+    # 
+    # @example
+    #   Issue.parse_tag_logic("+urgent,bug,+critical")
+    #   # => [['urgent', 'critical'], ['bug']]
+    def self.parse_tag_logic tags_string
+      return [[], []] if tags_string.nil? || tags_string.strip.empty?
+
+      tags = tags_string.split(',').map(&:strip).reject(&:empty?)
+      append_tags = []
+      default_tags = []
+
+      tags.each do |tag|
+        if tag.start_with?('+')
+          # Remove + prefix and add to append list
+          append_tags << tag[1..]
+        else
+          # Add to default-only list
+          default_tags << tag
+        end
+      end
+
+      [append_tags, default_tags]
+    end
+
+    # Generate formatted output for dry-run display
+    # 
+    # This method produces a standardized format for displaying issues during dry runs.
+    # Process: IMYML properties → site-specific parameters → display labels
+    # 
+    # 1. convert_issue_to_site_params() converts IMYML (summ→title, vrsn→milestone, etc.)
+    # 2. field_mappings() provides display labels for those converted parameters
+    # 
+    # @param site [Issuer::Sites::Base] The target site/platform
+    # @param repo [String] The repository identifier
+    # @return [String] Formatted issue display
+    # 
+    # @example Output format
+    #   ------
+    #   title:      "Fix authentication bug"
+    #   body:
+    #               Users cannot log in properly after the recent update.
+    #               This affects all user accounts.
+    #   
+    #   repo:       myorg/myproject
+    #   milestone:  1.0.0
+    #   labels:
+    #     - bug
+    #     - urgent
+    #   assignee:   developer1
+    #   ------
+    def formatted_output(site, repo)
+      # Get site-specific field mappings
+      field_map = site.field_mappings
+      
+      # Convert to site-specific parameters
+      site_params = site.convert_issue_to_site_params(self, repo, dry_run: true)
+      
+      output = [""]
+      
+      # Title (always present)
+      title_field = field_map[:title] || 'title'
+      output << sprintf("%-12s%s", "#{title_field}:", site_params[:title].inspect)
+      
+      # Body (with special formatting if present)
+      if site_params[:body] && !site_params[:body].strip.empty?
+        body_field = field_map[:body] || 'body'
+        output << "#{body_field}:"
+        # Indent body content
+        body_lines = site_params[:body].strip.split("\n")
+        body_lines.each do |line|
+          output << "            #{line}"
+        end
+        output << ""  # Empty line after body
+      end
+      
+      # Repository
+      repo_field = field_map[:repo] || 'repo'
+      output << sprintf("%-12s%s", "#{repo_field}:", repo) if repo
+      
+      # Milestone/Version
+      if site_params[:milestone]
+        milestone_field = field_map[:milestone] || 'milestone'
+        output << sprintf("%-12s%s", "#{milestone_field}:", site_params[:milestone])
+      end
+      
+      # Labels/Tags
+      if site_params[:labels] && !site_params[:labels].empty?
+        labels_field = field_map[:labels] || 'labels'
+        output << "#{labels_field}:"
+        site_params[:labels].each do |label|
+          output << "            - #{label}"
+        end
+      end
+      
+      # Assignee/User
+      if site_params[:assignee]
+        assignee_field = field_map[:assignee] || 'assignee'
+        output << sprintf("%-12s%s", "#{assignee_field}:", site_params[:assignee])
+      end
+      
+      output << "------"
+      output << ""  # Empty line after each issue
+      
+      output.join("\n")
+    end
+
+    private
+
+    # Determine if stub logic should be applied to this issue
+    # 
+    # Checks issue-level stub property first, then falls back to defaults.
+    # Converts various truthy values to boolean.
+    # 
+    # @param defaults [Hash] Default configuration containing 'stub' key
+    # @return [Boolean] True if stub should be applied, false otherwise
+    # 
+    # @example
+    #   issue.stub = 'yes'
+    #   issue.should_apply_stub?({'stub' => false}) # => true (issue-level wins)
+    def should_apply_stub? defaults
+      # Check if stub should be applied:
+      # 1. Issue-level stub property takes precedence
+      # 2. Falls back to defaults stub setting
+      # 3. Defaults to false if not specified
+
+      issue_stub = stub
+      default_stub = defaults['stub']
+
+      if issue_stub.nil?
+        # Use default stub setting (convert to boolean)
+        case default_stub
+        when true, 'true', 'yes', '1'
+          true
+        else
+          false
+        end
+      else
+        # Use issue-level setting (convert to boolean)
+        case issue_stub
+        when true, 'true', 'yes', '1'
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end