issuer 0.1.0

data/lib/issuer/ops.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Issuer
+  # The Ops module provides high-level operations for processing collections of issues,
+  # including data normalization, tag and stub logic application, and resource validation.
+  # This module serves as an orchestrator that delegates specific behaviors to the Issue class.
+  module Ops
+    module_function
+
+    # Processes raw issue data into normalized Issue objects.
+    # 
+    # This method converts scalar strings to proper issue hashes and creates Issue objects
+    # with enhanced defaults processing. It handles both string and hash inputs gracefully.
+    #
+    # @param issues_data [Array<String, Hash>] Raw issue data - can be strings or hashes
+    # @param defaults [Hash] Default values to apply to all issues
+    # @return [Array<Issuer::Issue>] Array of processed Issue objects
+    #
+    # @example
+    #   issues_data = ["Fix login bug", {"summ" => "Add feature", "tags" => ["enhancement"]}]
+    #   defaults = {"assignee" => "admin", "priority" => "normal"}
+    #   issues = Ops.process_issues_data(issues_data, defaults)
+    def self.process_issues_data issues_data, defaults
+      # Convert scalar strings to issue objects
+      normalized_data = self.normalize_issue_records(issues_data)
+
+      # Create Issue objects with enhanced defaults processing
+      issues = Issuer::Issue.from_array(normalized_data, defaults)
+
+      issues
+    end
+
+    # Applies tag logic to a collection of issues, typically based on CLI-provided tags.
+    # 
+    # This method delegates to the Issue class for consistency and to avoid code duplication.
+    # Tags can be applied based on various conditions or merged with existing issue tags.
+    #
+    # @param issues [Array<Issuer::Issue>] Collection of issues to process
+    # @param cli_tags [Array<String>] Tags provided via CLI arguments
+    # @return [Array<Issuer::Issue>] Issues with updated tag logic applied
+    #
+    # @example
+    #   issues = [issue1, issue2]
+    #   cli_tags = ["urgent", "frontend"]
+    #   Ops.apply_tag_logic(issues, cli_tags)
+    def self.apply_tag_logic issues, cli_tags
+      # Delegate to Issue class method for consistency
+      Issuer::Issue.apply_tag_logic(issues, cli_tags)
+    end
+
+    # Applies stub logic to a collection of issues based on provided defaults.
+    # 
+    # This method delegates to the Issue class for consistency and to avoid code duplication.
+    # Stub logic determines whether to create stub issues or apply certain transformations.
+    #
+    # @param issues [Array<Issuer::Issue>] Collection of issues to process
+    # @param defaults [Hash] Default values and configuration for stub logic
+    # @return [Array<Issuer::Issue>] Issues with updated stub logic applied
+    #
+    # @example
+    #   issues = [issue1, issue2]
+    #   defaults = {"stub_enabled" => true, "stub_prefix" => "[STUB]"}
+    #   Ops.apply_stub_logic(issues, defaults)
+    def self.apply_stub_logic issues, defaults
+      # Delegate to Issue class method for consistency
+      Issuer::Issue.apply_stub_logic(issues, defaults)
+    end
+
+    # Validates and prepares resources (versions/milestones and tags/labels) needed for issues.
+    # 
+    # This method ensures that all versions and tags referenced by issues exist in the target
+    # project. It can interactively prompt for creation of missing resources or auto-create
+    # them based on automation options.
+    #
+    # @param site [Object] Site connector object (e.g., GitHub, GitLab, Jira)
+    # @param proj [String] Project identifier (repository name, project key, etc.)
+    # @param issues [Array<Issuer::Issue>] Issues that will be created
+    # @param automation_options [Hash] Options for automatic resource creation
+    # @option automation_options [Boolean] :auto_versions Auto-create missing versions
+    # @option automation_options [Boolean] :auto_tags Auto-create missing tags
+    # @param run_id [String] Optional run identifier for tracking created resources
+    # @return [void]
+    #
+    # @example
+    #   automation = {auto_versions: true, auto_tags: false}
+    #   Ops.validate_and_prepare_resources(github_site, "my-repo", issues, automation, "run123")
+    def self.validate_and_prepare_resources site, proj, issues, automation_options = {}, run_id = nil
+      return if issues.empty?
+
+      # Step 1: Collect all unique versions and tags from issues
+      required_versions, required_tags = self.collect_required_resources(issues)
+
+      return if required_versions.empty? && required_tags.empty?
+
+      # Get site-specific terminology
+      version_term, tag_term = self.get_site_terminology(site)
+
+      puts "🔍 Checking #{site.site_name} project for existing #{version_term} and #{tag_term}..."
+
+      # Step 2: Check what exists vs what's missing
+      missing_versions, missing_tags = self.check_missing_resources(site, proj, required_versions, required_tags)
+
+      if missing_versions.empty? && missing_tags.empty?
+        puts "✅ All #{version_term} and #{tag_term} already exist in project"
+        return
+      end
+
+      puts "⚠️  Found missing #{version_term} (vrsn entries) and/or #{tag_term} (tags) that need to be created:"
+
+      # Step 3: Interactive or automatic creation of missing resources
+      auto_versions = automation_options[:auto_versions] || false
+      auto_tags = automation_options[:auto_tags] || false
+
+      self.create_missing_versions(site, proj, missing_versions, version_term, auto_versions, run_id) unless missing_versions.empty?
+      self.create_missing_tags(site, proj, missing_tags, tag_term, auto_tags, run_id) unless missing_tags.empty?
+
+      puts ""
+      puts "✅ Resource validation complete. Proceeding with issue creation..."
+    rescue => e
+      puts "❌ Error during validation: #{e.message}"
+      puts "Proceeding anyway, but some issues might fail to create..."
+    end
+
+    private
+
+    def self.get_site_terminology site
+      case site.site_name.downcase
+      when 'github'
+        ['milestones', 'labels']
+      when 'jira'
+        ['versions', 'labels']
+      when 'gitlab'
+        ['milestones', 'labels']
+      else
+        ['versions', 'tags']
+      end
+    end
+
+    def self.normalize_issue_records issues_data
+      issues_data.map do |item|
+        if item.is_a?(String)
+          # Convert scalar string to hash with summ property
+          { 'summ' => item }
+        else
+          # Already a hash, return as-is
+          item
+        end
+      end
+    end
+
+    def self.collect_required_resources issues
+      versions = Set.new
+      tags = Set.new
+
+      issues.each do |issue|
+        # Collect version (vrsn in IMYML)
+        if issue.vrsn && !issue.vrsn.to_s.strip.empty?
+          versions << issue.vrsn.to_s.strip
+        end
+
+        # Collect tags (tags in IMYML)
+        issue.tags.each do |tag|
+          tag_name = tag.to_s.strip
+          tags << tag_name unless tag_name.empty?
+        end
+      end
+
+      [versions.to_a, tags.to_a]
+    end
+
+    def self.check_missing_resources site, proj, required_versions, required_tags
+      existing_versions = site.get_versions(proj).map(&:title)
+      existing_tags = site.get_tags(proj).map(&:name)
+
+      missing_versions = required_versions - existing_versions
+      missing_tags = required_tags - existing_tags
+
+      [missing_versions, missing_tags]
+    end
+
+    def self.create_missing_versions site, proj, missing_versions, version_term = 'versions', auto_create = false, run_id = nil
+      missing_versions.each do |version_name|
+        puts ""
+        puts "📋 #{version_term.capitalize.chomp('s')} '#{version_name}' does not exist in project '#{proj}'"
+
+        if auto_create
+          puts "Auto-creating #{version_term.chomp('s').downcase}: #{version_name}"
+          result = site.create_version(proj, version_name)
+          puts "✅ #{version_term.capitalize.chomp('s')} '#{version_name}' created successfully"
+
+          # Log the created milestone if tracking is enabled
+          if run_id && result.is_a?(Hash) && result[:tracking_data]
+            require_relative 'cache'
+            Issuer::Cache.log_milestone_created(run_id, result[:tracking_data])
+          end
+        else
+          print "Create #{version_term.chomp('s').downcase} '#{version_name}'? [Y/n/q]: "
+
+          response = STDIN.gets.chomp.downcase
+          case response
+          when '', 'y', 'yes'
+            puts "Creating #{version_term.chomp('s').downcase}: #{version_name}"
+            result = site.create_version(proj, version_name)
+            puts "✅ #{version_term.capitalize.chomp('s')} '#{version_name}' created successfully"
+
+            # Log the created milestone if tracking is enabled
+            if run_id && result.is_a?(Hash) && result[:tracking_data]
+              require_relative 'cache'
+              Issuer::Cache.log_milestone_created(run_id, result[:tracking_data])
+            end
+          when 'q', 'quit'
+            puts "❌ Exiting - please resolve missing #{version_term} and try again"
+            exit 1
+          else
+            puts "⚠️  Skipping #{version_term.chomp('s').downcase} creation. Issues with this #{version_term.chomp('s').downcase} may fail to create."
+          end
+        end
+      end
+    end
+
+    def self.create_missing_tags site, proj, missing_tags, tag_term = 'tags', auto_create = false, run_id = nil
+      missing_tags.each do |tag_name|
+        puts ""
+        puts "🏷️  #{tag_term.capitalize.chomp('s')} '#{tag_name}' does not exist in project '#{proj}'"
+
+        if auto_create
+          puts "Auto-creating #{tag_term.chomp('s').downcase}: #{tag_name}"
+          result = site.create_tag(proj, tag_name)
+          puts "✅ #{tag_term.capitalize.chomp('s')} '#{tag_name}' created successfully"
+
+          # Log the created label if tracking is enabled
+          if run_id && result.is_a?(Hash) && result[:tracking_data]
+            require_relative 'cache'
+            Issuer::Cache.log_label_created(run_id, result[:tracking_data])
+          end
+        else
+          print "Create #{tag_term.chomp('s').downcase} '#{tag_name}' with default color? [Y/n/c/q]: "
+
+          response = STDIN.gets.chomp.downcase
+          case response
+          when '', 'y', 'yes'
+            puts "Creating #{tag_term.chomp('s').downcase}: #{tag_name}"
+            result = site.create_tag(proj, tag_name)
+            puts "✅ #{tag_term.capitalize.chomp('s')} '#{tag_name}' created successfully"
+
+            # Log the created label if tracking is enabled
+            if run_id && result.is_a?(Hash) && result[:tracking_data]
+              require_relative 'cache'
+              Issuer::Cache.log_label_created(run_id, result[:tracking_data])
+            end
+          when 'c', 'custom'
+            print "Enter hex color (without #, e.g. 'f29513'): "
+            color = STDIN.gets.chomp
+            color = 'f29513' if color.empty?
+
+            print "Enter description (optional): "
+            description = STDIN.gets.chomp
+            description = nil if description.empty?
+
+            puts "Creating #{tag_term.chomp('s').downcase}: #{tag_name} with color ##{color}"
+            result = site.create_tag(proj, tag_name, color: color, description: description)
+            puts "✅ #{tag_term.capitalize.chomp('s')} '#{tag_name}' created successfully"
+
+            # Log the created label if tracking is enabled
+            if run_id && result.is_a?(Hash) && result[:tracking_data]
+              require_relative 'cache'
+              Issuer::Cache.log_label_created(run_id, result[:tracking_data])
+            end
+          when 'q', 'quit'
+            puts "❌ Exiting - please resolve missing #{tag_term} and try again"
+            exit 1
+          else
+            puts "⚠️  Skipping #{tag_term.chomp('s').downcase} creation. Issues with this #{tag_term.chomp('s').downcase} may not be tagged properly."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/issuer/sites/base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Issuer
+  module Sites
+    class Base
+      # Site identification
+      def site_name
+        raise NotImplementedError, "Subclasses must implement site_name"
+      end
+
+      # Field display labels for dry-run output formatting
+      # Maps site-specific parameter names to user-friendly display labels
+      def field_mappings
+        raise NotImplementedError, "Subclasses must implement field_mappings"
+      end
+
+      # Resource validation and preparation
+      def validate_and_prepare_resources proj, issues
+        raise NotImplementedError, "Subclasses must implement validate_and_prepare_resources"
+      end
+
+      # Issue creation
+      def create_issue proj, issue_params
+        raise NotImplementedError, "Subclasses must implement create_issue"
+      end
+
+      # Resource queries for validation
+      def get_versions proj
+        raise NotImplementedError, "Subclasses must implement get_versions"
+      end
+
+      def get_tags proj
+        raise NotImplementedError, "Subclasses must implement get_tags"
+      end
+
+      # Resource creation for validation
+      def create_version proj, version_name, options={}
+        raise NotImplementedError, "Subclasses must implement create_version"
+      end
+
+      def create_tag proj, tag_name, options={}
+        raise NotImplementedError, "Subclasses must implement create_tag"
+      end
+
+      # Resource cleanup methods for caching/undo functionality
+      def close_issue proj, issue_number
+        raise NotImplementedError, "Subclasses must implement close_issue"
+      end
+
+      def delete_milestone proj, milestone_number
+        raise NotImplementedError, "Subclasses must implement delete_milestone"
+      end
+
+      def delete_label proj, label_name
+        raise NotImplementedError, "Subclasses must implement delete_label"
+      end
+
+      # Convert IMYML issue to site-specific parameters
+      def convert_issue_to_site_params issue, proj, dry_run: false
+        raise NotImplementedError, "Subclasses must implement convert_issue_to_site_params"
+      end
+
+      # Issue posting
+      def post_issues proj, issues, run_id = nil
+        processed_count = 0
+
+        issues.each do |issue|
+          begin
+            # Convert IMYML issue to site-specific parameters
+            site_params = convert_issue_to_site_params(issue, proj)
+            result = create_issue(proj, site_params)
+
+            # Extract the created issue object (for backwards compatibility)
+            created_issue = result.is_a?(Hash) ? result[:object] : result
+
+            puts "✅ Created issue ##{created_issue.number}: #{issue.summ}"
+            puts "   URL: #{created_issue.html_url}" if created_issue.respond_to?(:html_url)
+            processed_count += 1
+
+            # Log the created issue if tracking is enabled
+            if run_id && result.is_a?(Hash) && result[:tracking_data]
+              require_relative '../cache'
+              Issuer::Cache.log_issue_created(run_id, result[:tracking_data])
+            end
+
+            # Rate limiting courtesy
+            sleep(1) if processed_count % 10 == 0
+          rescue => e
+            puts "❌ Failed to create issue '#{issue.summ}': #{e.message}"
+          end
+        end
+
+        processed_count
+      end
+
+      protected
+
+      # Site-specific configuration validation
+      def validate_configuration
+        raise NotImplementedError, "Subclasses must implement validate_configuration"
+      end
+
+      # Site-specific authentication
+      def authenticate
+        raise NotImplementedError, "Subclasses must implement authenticate"
+      end
+    end
+  end
+end

data/lib/issuer/sites/factory.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Issuer
+  module Sites
+    class Factory
+      SUPPORTED_SITES = {
+        'github' => 'Issuer::Sites::GitHub'
+      }.freeze
+
+      def self.create site_name, **options
+        site_name = site_name.to_s.downcase
+
+        unless SUPPORTED_SITES.key?(site_name)
+          available = SUPPORTED_SITES.keys.join(', ')
+          raise Issuer::Error, "Unsupported site '#{site_name}'. Available sites: #{available}"
+        end
+
+        site_class = Object.const_get(SUPPORTED_SITES[site_name])
+        site_class.new(**options)
+      end
+
+      def self.supported_sites
+        SUPPORTED_SITES.keys
+      end
+
+      def self.default_site
+        'github'
+      end
+    end
+  end
+end

data/lib/issuer/sites/github.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'octokit'
+require_relative 'base'
+
+module Issuer
+  module Sites
+    class GitHub < Base
+      def initialize token: nil, token_env_var: nil
+        @token = token || self.class.detect_github_token(custom_env_var: token_env_var)
+
+        # Skip authentication validation for dry-run mode
+        if @token == 'dry-run-token'
+          @client = nil
+          return
+        end
+
+        unless @token
+          env_vars = [token_env_var, *self.class.default_token_env_vars].compact.uniq
+          raise Issuer::Error, "GitHub token not found. Set #{env_vars.join(', ')} environment variable."
+        end
+
+        @client = Octokit::Client.new(access_token: @token)
+        @client.auto_paginate = true
+      end
+
+      def site_name
+        'github'
+      end
+
+      # Return field display labels for dry-run output
+      # Maps site-specific parameter names to user-friendly display labels
+      # Note: Issue properties are already converted by convert_issue_to_site_params
+      def field_mappings
+        {
+          title: 'title',        # site_params[:title] displays as "title:"
+          body: 'body',          # site_params[:body] displays as "body:"
+          repo: 'repo',          # repo displays as "repo:"
+          milestone: 'milestone', # site_params[:milestone] displays as "milestone:"
+          labels: 'labels',      # site_params[:labels] displays as "labels:"
+          assignee: 'assignee',  # site_params[:assignee] displays as "assignee:"
+          project_name: 'repo'   # For summary messages: "repo: owner/name"
+        }
+      end
+
+      def validate_and_prepare_resources proj, issues
+        Issuer::Ops.validate_and_prepare_resources(self, proj, issues)
+      end
+
+      def create_issue proj, issue_params
+        # Validate required fields
+        unless issue_params[:title] && !issue_params[:title].strip.empty?
+          raise Issuer::Error, "Issue title is required"
+        end
+
+        # Prepare issue creation parameters
+        params = {
+          title: issue_params[:title],
+          body: issue_params[:body] || ''
+        }
+
+        # Handle labels
+        if issue_params[:labels] && !issue_params[:labels].empty?
+          params[:labels] = issue_params[:labels].map(&:strip).reject(&:empty?)
+        end
+
+        # Handle assignee
+        if issue_params[:assignee] && !issue_params[:assignee].strip.empty?
+          params[:assignee] = issue_params[:assignee].strip
+        end
+
+        # Handle milestone - only if milestone exists
+        if issue_params[:milestone]
+          milestone = find_milestone(proj, issue_params[:milestone])
+          params[:milestone] = milestone.number if milestone
+        end
+
+        created_issue = @client.create_issue(proj, params[:title], params[:body], params)
+
+        # Extract relevant data for potential cleanup tracking
+        issue_data = {
+          number: created_issue.number,
+          title: created_issue.title,
+          url: created_issue.html_url,
+          created_at: created_issue.created_at,
+          repository: proj
+        }
+
+        # Return both the created issue and tracking data
+        { object: created_issue, tracking_data: issue_data }
+      rescue Octokit::Error => e
+        raise Issuer::Error, "GitHub API error: #{e.message}"
+      end
+
+      def get_versions proj
+        @client.milestones(proj, state: 'all')
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to fetch milestones: #{e.message}"
+      end
+
+      def get_tags proj
+        @client.labels(proj)
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to fetch labels: #{e.message}"
+      end
+
+      def create_version proj, version_name, options={}
+        description = options[:description] || "Created by issuer CLI"
+
+        # Call create_milestone with proper parameters
+        created_milestone = @client.create_milestone(proj, version_name, description: description)
+
+        # Return tracking data
+        {
+          object: created_milestone,
+          tracking_data: {
+            number: created_milestone.number,
+            title: created_milestone.title,
+            url: created_milestone.html_url,
+            created_at: created_milestone.created_at,
+            repository: proj
+          }
+        }
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to create milestone '#{version_name}': #{e.message}"
+      end
+
+      def create_tag proj, tag_name, options={}
+        color = options[:color] || 'f29513'
+        description = options[:description]
+
+        # Call add_label with proper parameters
+        created_label = @client.add_label(proj, tag_name, color, description: description)
+
+        # Return tracking data
+        {
+          object: created_label,
+          tracking_data: {
+            name: created_label.name,
+            color: created_label.color,
+            description: created_label.description,
+            url: created_label.url,
+            repository: proj
+          }
+        }
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to create label '#{tag_name}': #{e.message}"
+      end
+
+      # Cleanup methods
+      def close_issue proj, issue_number
+        @client.close_issue(proj, issue_number)
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to close issue ##{issue_number}: #{e.message}"
+      end
+
+      def delete_milestone proj, milestone_number
+        @client.delete_milestone(proj, milestone_number)
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to delete milestone ##{milestone_number}: #{e.message}"
+      end
+
+      def delete_label proj, label_name
+        @client.delete_label!(proj, label_name)
+      rescue Octokit::Error => e
+        raise Issuer::Error, "Failed to delete label '#{label_name}': #{e.message}"
+      end
+
+      def validate_configuration
+        # Test API access
+        @client.user
+        true
+      rescue Octokit::Error => e
+        raise Issuer::Error, "GitHub authentication failed: #{e.message}"
+      end
+
+      def authenticate
+        validate_configuration
+      end
+
+      # Convert IMYML issue to GitHub-specific parameters
+      def convert_issue_to_site_params issue, proj, dry_run: false
+        params = {
+          title: issue.summ,
+          body: issue.body || ''
+        }
+
+        # Handle tags -> labels
+        if issue.tags && !issue.tags.empty?
+          params[:labels] = issue.tags.map(&:strip).reject(&:empty?)
+        end
+
+        # Handle user -> assignee
+        if issue.user && !issue.user.strip.empty?
+          params[:assignee] = issue.user.strip
+        end
+
+        # Handle vrsn -> milestone
+        if issue.vrsn
+          if dry_run
+            # In dry-run mode, just show the milestone name without API lookup
+            params[:milestone] = issue.vrsn
+          else
+            # In normal mode, resolve milestone name to number
+            milestone = find_milestone(proj, issue.vrsn)
+            params[:milestone] = milestone.number if milestone
+          end
+        end
+
+        params
+      end
+
+      protected
+
+      # Class method to get standard GitHub token environment variable names
+      def self.default_token_env_vars
+        %w[ISSUER_API_TOKEN ISSUER_GITHUB_TOKEN GITHUB_ACCESS_TOKEN GITHUB_TOKEN]
+      end
+
+      # Class method to detect GitHub token from environment
+      # @param custom_env_var [String, nil] Custom environment variable name to check first
+      # @return [String, nil] The token value or nil if not found
+      def self.detect_github_token(custom_env_var: nil)
+        # Check custom env var first if provided
+        return ENV[custom_env_var] if custom_env_var && ENV[custom_env_var]
+
+        # Fall back to standard env vars
+        default_token_env_vars.each do |env_var|
+          token = ENV[env_var]
+          return token if token
+        end
+
+        nil
+      end
+
+      private
+
+      def detect_github_token
+        self.class.detect_github_token
+      end
+
+      def find_milestone proj, milestone_name
+        milestones = get_versions(proj)
+        milestones.find { |m| m.title == milestone_name.to_s }
+      end
+    end
+  end
+end

data/lib/issuer/version.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Issuer
+  unless defined?(VERSION)
+    # Read version from README.adoc (source repo only)
+    readme_path = File.join(File.dirname(__FILE__), '..', '..', 'README.adoc')
+    
+    if File.exist?(readme_path)
+      # Parse README.adoc to find :this_prod_vrsn: attribute
+      File.foreach(readme_path) do |line|
+        if line.match(/^:this_prod_vrsn:\s*(.+)$/)
+          VERSION = $1.strip
+          break
+        end
+      end
+    end
+    
+    # Fallback if README.adoc not found or version not found
+    VERSION ||= '0.0.0'
+  end
+end