issuer 0.1.0

data/examples/advanced-stub-example.yml

@@ -0,0 +1,50 @@
+# Advanced example showing stub functionality and tag logic
+$meta:
+  proj: docops/advanced-project
+  defaults:
+    vrsn: 2.0.0
+    user: team-lead
+    tags: [needs-review, +auto-generated]  # + prefix = append to all
+    stub: true
+    head: |
+      ## 🤖 Auto-Generated Issue
+      This issue was created by the issuer CLI tool.
+      
+      ---
+    body: |
+      This is a placeholder. Please update with specific requirements
+      and assign to the appropriate team member.
+    tail: |
+      ---
+      
+      **Created by**: issuer CLI  
+      **Project**: Advanced Features Demo
+
+issues:
+  # Scalar string issues (get all defaults + stub processing)
+  - Implement advanced search functionality
+  - Add real-time notifications
+  - Create user dashboard
+  
+  # Issue with custom content but stub enabled
+  - summ: Database performance optimization
+    stub: true
+    body: |
+      The current database queries are slow for large datasets.
+      Need to implement proper indexing and query optimization.
+    tags: [performance, database]
+    user: db-specialist
+    
+  # Issue with stub disabled (no header/footer added)
+  - summ: Critical security vulnerability fix
+    stub: false
+    body: |
+      URGENT: Security vulnerability discovered in authentication module.
+      Immediate fix required.
+    tags: [critical, security, +urgent]  # + prefix = append even with explicit tags
+    user: security-team
+    vrsn: 1.9.1
+    
+  # Issue with only append tags (gets default tags too)
+  - summ: Code refactoring initiative
+    tags: [+refactoring, +technical-debt]

data/examples/basic-example.yml

@@ -0,0 +1,33 @@
+# Basic example demonstrating core IMYML features
+$meta:
+  proj: myorg/myproject
+  defaults:
+    vrsn: 1.0.0
+    user: project-manager
+    tags: [enhancement]
+
+issues:
+  - summ: Add user authentication
+    body: |
+      Implement secure login and registration functionality.
+      
+      Requirements:
+      - Password hashing
+      - Session management
+      - Two-factor authentication support
+    tags: [security, authentication]
+    user: backend-dev
+
+  - summ: Fix responsive design issues
+    body: |
+      The current layout breaks on mobile devices.
+      Need to ensure proper responsive behavior.
+    tags: [bug, ui, mobile]
+    user: frontend-dev
+
+  - summ: Create API documentation
+    body: |
+      Generate comprehensive API documentation for developers.
+      Include examples and authentication details.
+    vrsn: 1.1.0
+    tags: [documentation, api]

data/examples/minimal-example.yml

@@ -0,0 +1,9 @@
+# Minimal example for quick testing
+$meta:
+  proj: test/repo
+
+issues:
+  - summ: First test issue
+    body: Simple test issue for validation
+  - summ: Second test issue  
+  - Quick issue from string

data/examples/new-project-issues.yml

@@ -0,0 +1,162 @@
+# New Project Bootstrap Issues
+# Common tasks for setting up a new software project
+
+$meta:
+  proj: myorg/new-project
+  defaults:
+    vrsn: 0.1.0
+    user: project-lead
+    tags: [project-setup, +new-project]
+    stub: true
+    head: |
+      ## 🚀 Project Bootstrap Task
+      This is a foundational task for setting up the new project.
+      
+      ---
+    body: |
+      Please complete this task as part of the initial project setup.
+      Assign to the appropriate team member and update with specific requirements.
+    tail: |
+      ---
+      
+      **Priority**: Foundation work - should be completed early
+      **Created by**: Project bootstrap automation
+
+issues:
+  # Repository and Infrastructure Setup
+  - summ: Initialize repository structure
+    stub: false
+    body: |
+      Set up the basic repository structure and initial files.
+      
+      **Tasks:**
+      - Create main branch protection rules
+      - Set up .gitignore file
+      - Add initial directory structure
+      - Configure repository settings and permissions
+    tags: [infrastructure, repository]
+    user: devops-lead
+
+  - summ: Add project README and documentation
+    body: |
+      Create comprehensive project documentation.
+      
+      **Requirements:**
+      - Project overview and purpose
+      - Installation instructions
+      - Usage examples
+      - Contributing guidelines
+      - API documentation (if applicable)
+    tags: [documentation, +high-priority]
+    user: tech-writer
+
+  - summ: Set up CI/CD pipeline
+    body: |
+      Configure automated testing and deployment.
+      
+      **Components:**
+      - GitHub Actions / Jenkins / CircleCI setup
+      - Automated testing on pull requests
+      - Code quality checks (linting, formatting)
+      - Deployment automation for staging/production
+    tags: [infrastructure, ci-cd, automation]
+    user: devops-lead
+
+  # Development Environment
+  - summ: Configure development environment setup
+    body: |
+      Create reproducible development environment.
+      
+      **Deliverables:**
+      - Docker configuration or development containers
+      - Local setup instructions
+      - Environment variable documentation
+      - IDE/editor configuration files
+    tags: [development, environment]
+    user: senior-dev
+
+  - summ: Set up code quality tools
+    body: |
+      Implement code quality and consistency tools.
+      
+      **Tools to configure:**
+      - Linters (ESLint, RuboCop, Pylint, etc.)
+      - Code formatters (Prettier, Black, etc.)
+      - Pre-commit hooks
+      - Code coverage reporting
+    tags: [development, code-quality]
+    user: senior-dev
+
+  # Testing Infrastructure
+  - summ: Implement testing framework
+    body: |
+      Set up comprehensive testing infrastructure.
+      
+      **Test types:**
+      - Unit tests
+      - Integration tests
+      - End-to-end tests (if applicable)
+      - Performance/load tests (if needed)
+    tags: [testing, framework]
+    user: qa-lead
+
+  # Security and Compliance
+  - summ: Configure security scanning and policies
+    body: |
+      Implement security best practices from the start.
+      
+      **Security measures:**
+      - Dependency vulnerability scanning
+      - Static code analysis for security issues
+      - Secrets management setup
+      - Security policy documentation
+    tags: [security, compliance, +critical]
+    user: security-team
+
+  # Project Management
+  - summ: Set up project tracking and issue management
+    body: |
+      Configure project management tools and workflows.
+      
+      **Setup tasks:**
+      - Issue templates and labels
+      - Project boards/milestones
+      - Sprint planning tools
+      - Team communication channels
+    tags: [project-management, workflow]
+    user: project-manager
+
+  # Basic Implementation Tasks
+  - Create initial project architecture
+  - Implement basic routing/navigation structure  
+  - Set up database schema and migrations
+  - Create user authentication system
+  - Implement basic API endpoints
+  - Add logging and monitoring setup
+
+  # Deployment and Operations
+  - summ: Configure staging environment
+    body: |
+      Set up staging environment for testing.
+      
+      **Requirements:**
+      - Mirror production configuration
+      - Automated deployment from main branch
+      - Test data seeding
+      - Monitoring and logging
+    tags: [infrastructure, staging, deployment]
+    user: devops-lead
+    vrsn: 0.2.0
+
+  - summ: Prepare production deployment strategy
+    body: |
+      Plan and document production deployment.
+      
+      **Planning items:**
+      - Infrastructure requirements
+      - Deployment rollback procedures
+      - Performance monitoring setup
+      - Disaster recovery plan
+    tags: [infrastructure, production, deployment]
+    user: devops-lead
+    vrsn: 1.0.0

data/examples/validation-test.yml

@@ -0,0 +1,8 @@
+issues:
+  - summ: Test milestone validation
+    desc: This issue has a milestone that probably doesn't exist
+    vrsn: test-milestone-v1.0
+    tags: [test-label-1, existing-bug]
+  - summ: Test label validation  
+    desc: This issue has labels that probably don't exist
+    tags: [test-label-2, test-label-3, enhancement]

data/exe/issuer

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "issuer"
+
+Issuer::CLI.start(ARGV)

data/issuer.gemspec

@@ -0,0 +1,43 @@
+require_relative 'lib/issuer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "issuer"
+  spec.version       = Issuer::VERSION
+  spec.authors       = ["DocOps Lab"]
+  spec.email         = ["codewriter@protonmail.com"]
+
+  spec.summary       = "Bulk GitHub issue creator from YAML definitions"
+  spec.description   = "CLI tool for creating multiple GitHub issues from a single YAML file (IMYML format). Define all your issues in one place, apply defaults, and post them to GitHub in bulk."
+  spec.homepage      = "https://github.com/DocOps/issuer"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/DocOps/issuer"
+  spec.metadata["changelog_uri"] = "https://github.com/DocOps/issuer/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[test/ spec/ features/ .git .circleci appveyor Gemfile pkg/]) ||
+        f.match?(/\.gem$/) ||
+        f.match?(/test_.*\.rb$/)
+    end
+  end
+  
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "octokit", "~> 8.0"
+  spec.add_dependency "thor", "~> 1.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "asciidoctor", "~> 2.0"
+end

data/lib/issuer/apis/github/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'octokit'
+
+module Issuer
+  module APIs
+    module GitHub
+      class Client
+        def initialize token: nil, token_env_var: nil
+          @token = token || detect_github_token(token_env_var)
+
+          unless @token
+            env_vars = [token_env_var, *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 create_issue repo, 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(repo, issue_params[:milestone])
+            params[:milestone] = milestone.number if milestone
+          end
+
+          @client.create_issue(repo, params[:title], params[:body], params)
+        rescue Octokit::Error => e
+          raise Issuer::Error, "GitHub API error: #{e.message}"
+        end
+
+        def find_milestone repo, milestone_title
+          milestones = @client.milestones(repo, state: 'all')
+          milestones.find { |m| m.title == milestone_title.to_s }
+        rescue Octokit::Error => e
+          raise Issuer::Error, "Error fetching milestones: #{e.message}"
+        end
+
+        def create_milestone repo, title, description: nil
+          @client.create_milestone(repo, title, description: description)
+        rescue Octokit::Error => e
+          raise Issuer::Error, "Error creating milestone '#{title}': #{e.message}"
+        end
+
+        def find_label repo, label_name
+          labels = @client.labels(repo)
+          labels.find { |l| l.name == label_name.to_s }
+        rescue Octokit::Error => e
+          raise Issuer::Error, "Error fetching labels: #{e.message}"
+        end
+
+        def create_label repo, name, color: 'f29513', description: nil
+          @client.add_label(repo, name, color, description: description)
+        rescue Octokit::Error => e
+          raise Issuer::Error, "Error creating label '#{name}': #{e.message}"
+        end
+
+        def get_milestones repo
+          @client.milestones(repo, state: 'all')
+        rescue Octokit::Error => e
+          raise Issuer::Error, "Error fetching milestones: #{e.message}"
+        end
+
+        def get_labels repo
+          @client.labels(repo)
+        rescue Octokit::Error => e
+          raise Issuer::Error, "Error fetching labels: #{e.message}"
+        end
+
+        def test_connection
+          @client.user
+          true
+        rescue Octokit::Error => e
+          raise Issuer::Error, "GitHub connection test failed: #{e.message}"
+        end
+
+        def rate_limit
+          @client.rate_limit
+        end
+
+        private
+
+        def default_token_env_vars
+          %w[ISSUER_API_TOKEN ISSUER_GITHUB_TOKEN GITHUB_ACCESS_TOKEN GITHUB_TOKEN]
+        end
+
+        def detect_github_token(custom_env_var)
+          # 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
+      end
+    end
+  end
+end

data/lib/issuer/cache.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'digest'
+require 'securerandom'
+require 'time'
+
+module Issuer
+  module Cache
+    module_function
+
+    # Directory and file management
+    def cache_dir
+      if ENV['ISSUER_CONFIG_DIR']
+        File.expand_path(ENV['ISSUER_CONFIG_DIR'])
+      elsif ENV['XDG_CONFIG_HOME']
+        File.join(ENV['XDG_CONFIG_HOME'], 'issuer')
+      else
+        File.expand_path('~/.config/issuer')
+      end
+    rescue ArgumentError
+      # Fallback if home directory issues
+      File.expand_path('.issuer', Dir.pwd)
+    end
+
+    def logs_dir
+      File.join(cache_dir, 'logs')
+    end
+
+    def ensure_cache_directories
+      FileUtils.mkdir_p(logs_dir) unless Dir.exist?(logs_dir)
+    end
+
+    def run_log_file(run_id)
+      File.join(logs_dir, "#{run_id}.json")
+    end
+
+    def generate_run_id
+      timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+      random_suffix = SecureRandom.hex(4)
+      "run_#{timestamp}_#{random_suffix}"
+    end
+
+    # Run tracking
+    def start_run(metadata = {})
+      ensure_cache_directories
+
+      run_id = generate_run_id
+      run_data = {
+        run_id: run_id,
+        started_at: Time.now.iso8601,
+        status: 'in_progress',
+        metadata: metadata,
+        artifacts: {
+          issues: [],
+          milestones: [],
+          labels: []
+        },
+        summary: {
+          issues_created: 0,
+          milestones_created: 0,
+          labels_created: 0
+        }
+      }
+
+      save_run_log(run_id, run_data)
+      run_id
+    end
+
+    def complete_run(run_id, issues_processed = nil)
+      run_data = load_run_log(run_id)
+      return unless run_data
+
+      # Handle both symbol and string keys
+      completed_key = run_data.key?(:completed_at) ? :completed_at : 'completed_at'
+      status_key = run_data.key?(:status) ? :status : 'status'
+
+      run_data[completed_key] = Time.now.iso8601
+      run_data[status_key] = 'completed'
+
+      # Update issues processed if provided
+      if issues_processed
+        summary_key = run_data.key?(:summary) ? :summary : 'summary'
+        processed_key = 'issues_processed'
+        run_data[summary_key][processed_key] = issues_processed
+      end
+
+      save_run_log(run_id, run_data)
+    end
+
+    def fail_run(run_id, error_message)
+      run_data = load_run_log(run_id)
+      return unless run_data
+
+      # Handle both symbol and string keys
+      failed_key = run_data.key?(:failed_at) ? :failed_at : 'failed_at'
+      status_key = run_data.key?(:status) ? :status : 'status'
+      error_key = run_data.key?(:error) ? :error : 'error'
+
+      run_data[failed_key] = Time.now.iso8601
+      run_data[status_key] = 'failed'
+      run_data[error_key] = error_message
+      save_run_log(run_id, run_data)
+    end
+
+    # Artifact tracking
+    def log_issue_created(run_id, issue_data)
+      log_artifact(run_id, :issues, issue_data)
+    end
+
+    def log_milestone_created(run_id, milestone_data)
+      log_artifact(run_id, :milestones, milestone_data)
+    end
+
+    def log_label_created(run_id, label_data)
+      log_artifact(run_id, :labels, label_data)
+    end
+
+    def log_artifact(run_id, type, artifact_data)
+      run_data = load_run_log(run_id)
+      return unless run_data
+
+      # Handle both symbol and string keys (since JSON loading converts symbols to strings)
+      artifacts_key = run_data.key?(:artifacts) ? :artifacts : 'artifacts'
+      summary_key = run_data.key?(:summary) ? :summary : 'summary'
+      type_key = run_data[artifacts_key].key?(type) ? type : type.to_s
+
+      run_data[artifacts_key][type_key] << artifact_data
+
+      # Increment the appropriate counter (use proper plural-to-singular mapping)
+      counter_key = case type.to_s
+                   when 'issues' then 'issues_created'
+                   when 'milestones' then 'milestones_created'  
+                   when 'labels' then 'labels_created'
+                   else "#{type}_created"
+                   end
+
+      summary_section = run_data[summary_key]
+      if summary_section.key?(counter_key.to_sym)
+        summary_section[counter_key.to_sym] += 1
+      elsif summary_section.key?(counter_key)
+        summary_section[counter_key] += 1
+      else
+        # Fallback - create the key as string
+        summary_section[counter_key] = 1
+      end
+
+      save_run_log(run_id, run_data)
+    end
+
+    # Data persistence
+    def save_run_log(run_id, data)
+      File.write(run_log_file(run_id), JSON.pretty_generate(data))
+    end
+
+    def load_run_log(run_id)
+      log_file = run_log_file(run_id)
+      return nil unless File.exist?(log_file)
+
+      JSON.parse(File.read(log_file), symbolize_names: true)
+    rescue JSON::ParserError => e
+      puts "⚠️  Warning: Could not parse run log file #{log_file}: #{e.message}"
+      nil
+    end
+
+    # Query and listing
+    def list_runs(status: nil, limit: nil)
+      ensure_cache_directories
+
+      log_files = Dir.glob(File.join(logs_dir, '*.json'))
+                     .sort_by { |f| File.mtime(f) }
+                     .reverse
+
+      runs = log_files.map do |file|
+        begin
+          data = JSON.parse(File.read(file), symbolize_names: true)
+          next if status && data[:status] != status.to_s
+          data
+        rescue JSON::ParserError
+          nil
+        end
+      end.compact
+
+      limit ? runs.take(limit) : runs
+    end
+
+    def get_run(run_id)
+      load_run_log(run_id)
+    end
+
+    def delete_run_log(run_id)
+      log_file = run_log_file(run_id)
+      File.delete(log_file) if File.exist?(log_file)
+    end
+  end
+end