issuer 0.1.0

data/lib/issuer.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require_relative "issuer/version"
+require_relative "issuer/issue"
+require_relative "issuer/apis/github/client"
+require_relative "issuer/sites/base"
+require_relative "issuer/sites/github"
+require_relative "issuer/sites/factory"
+require_relative "issuer/ops"
+require_relative "issuer/cache"
+require_relative "issuer/cli"
+
+##
+# = Issuer: Bulk GitHub Issue Creator
+#
+# Issuer is a Ruby gem that allows you to define all your work tickets in one place
+# using the IMYML (Issue Management YAML-based Modeling Language) format, apply defaults,
+# and post them to GitHub Issues (and other platforms) in bulk.
+#
+# == Features
+#
+# * Bulk issue creation from a single YAML file
+# * Dry-run mode for testing without creating issues
+# * Automatic milestone and label creation
+# * Configurable defaults and label application logic
+# * Environment variable support for authentication
+# * Issue validation with helpful error messages
+# * Extensible architecture for multiple platforms (GitHub, JIRA, GitLab, etc.)
+# * Run logging and artifact tracking for cleanup operations
+#
+# == Quick Start
+#
+#   # Create issues from an IMYML file
+#   processor = Issuer::Processor.new
+#   results = processor.process_file('issues.yml', 
+#                                    proj: 'myorg/myrepo',
+#                                    dry_run: false)
+#
+#   # Access individual components
+#   site = Issuer::Sites::Factory.create(:github)
+#   issues = Issuer::Issue.from_array(yaml_data['issues'], defaults)
+#
+# == Extensibility
+#
+# The gem is designed for extensibility:
+#
+# * Create new site adapters by subclassing {Issuer::Sites::Base}
+# * Extend the IMYML format by customizing {Issuer::Ops} methods
+# * Add custom validation logic to {Issuer::Issue}
+# * Track operations with {Issuer::Cache}
+#
+# @see https://github.com/DocOps/issuer Project Homepage
+# @see Issuer::Sites::Base For creating new platform adapters
+# @see Issuer::Issue For the core issue model
+# @see Issuer::Ops For IMYML processing operations
+#
+module Issuer
+
+  ##
+  # Standard error class for all Issuer-related errors
+  class Error < StandardError; end
+
+  ##
+  # Main processor class that provides a clean API for external usage.
+  # This is the recommended entry point for programmatic access to Issuer functionality.
+  #
+  # @example Basic usage
+  #   processor = Issuer::Processor.new
+  #   results = processor.process_file('issues.yml', proj: 'myorg/myrepo')
+  #
+  # @example With custom site
+  #   site = Issuer::Sites::Factory.create(:github, token: 'custom-token')
+  #   processor = Issuer::Processor.new(site: site)
+  #   results = processor.process_data(yaml_data, proj: 'myorg/myrepo')
+  #
+  class Processor
+
+    ##
+    # Initialize a new processor
+    #
+    # @param site [Issuer::Sites::Base, nil] Custom site adapter. If nil, will auto-detect.
+    # @param cache [Boolean] Whether to enable run tracking and caching (default: true)
+    #
+    def initialize(site: nil, cache: true)
+      @site = site
+      @cache_enabled = cache
+    end
+
+    ##
+    # Process an IMYML file and create issues
+    #
+    # @param file_path [String] Path to the IMYML YAML file
+    # @param proj [String, nil] Target repository (org/repo format)
+    # @param dry_run [Boolean] If true, validate and show what would be created without API calls
+    # @param automation_options [Hash] Options for automatic resource creation
+    # @option automation_options [Boolean] :auto_versions Automatically create missing milestones
+    # @option automation_options [Boolean] :auto_tags Automatically create missing labels
+    # @option automation_options [Boolean] :auto_metadata Automatically create all missing metadata
+    #
+    # @return [Hash] Results including created issues, milestones, labels, and run metadata
+    # @raise [Issuer::Error] If file cannot be read or processed
+    #
+    # @example
+    #   results = processor.process_file('issues.yml', 
+    #                                    proj: 'myorg/myrepo',
+    #                                    dry_run: false,
+    #                                    automation_options: { auto_metadata: true })
+    #   puts "Created #{results[:issues_created]} issues"
+    #
+    def process_file(file_path, proj: nil, dry_run: false, automation_options: {})
+      require 'yaml'
+
+      unless File.exist?(file_path)
+        raise Error, "File not found: #{file_path}"
+      end
+
+      begin
+        raw_data = YAML.load_file(file_path)
+      rescue => e
+        raise Error, "Could not parse YAML file: #{file_path}\n#{e.message}"
+      end
+
+      process_data(raw_data, proj: proj, dry_run: dry_run, automation_options: automation_options)
+    end
+
+    ##
+    # Process IMYML data structure and create issues
+    #
+    # @param data [Hash] Parsed IMYML data structure
+    # @param proj [String, nil] Target repository (org/repo format)
+    # @param dry_run [Boolean] If true, validate and show what would be created without API calls
+    # @param automation_options [Hash] Options for automatic resource creation
+    #
+    # @return [Hash] Results including created issues, milestones, labels, and run metadata
+    # @raise [Issuer::Error] If data is invalid or processing fails
+    #
+    def process_data(data, proj: nil, dry_run: false, automation_options: {})
+      # Extract metadata and issues
+      meta = data['$meta'] || {}
+      issues_data = data['issues'] || data
+
+      unless issues_data.is_a?(Array)
+        raise Error, 'No issues array found (root or under "issues")'
+      end
+
+      # Build defaults
+      defaults = (meta['defaults'] || {}).dup
+      defaults['proj'] = meta['proj'] if meta['proj']
+
+      # Determine target repository
+      target_repo = proj || meta['proj'] || ENV['ISSUER_REPO']
+      if target_repo.nil? && !dry_run
+        raise Error, 'No target repo specified. Use proj parameter, $meta.proj, or ISSUER_REPO environment variable.'
+      end
+
+      # Process issues
+      issues = Ops.process_issues_data(issues_data, defaults)
+      valid_issues = issues.select(&:valid?)
+      invalid_issues = issues.reject(&:valid?)
+
+      # Report validation errors
+      invalid_issues.each_with_index do |issue, idx|
+        puts "⚠️  Skipping invalid issue: #{issue.validation_errors.join(', ')}"
+      end
+
+      if dry_run
+        return perform_dry_run(valid_issues, target_repo)
+      else
+        return perform_live_run(valid_issues, target_repo, automation_options)
+      end
+    end
+
+    private
+
+    def get_site
+      @site ||= Sites::Factory.create(Sites::Factory.default_site)
+    end
+
+    def perform_dry_run(issues, repo)
+      site = Sites::Factory.create('github', token: 'dry-run-token')
+
+      puts "🧪 DRY RUN - No issues will be created"
+      puts "📋 Target repository: #{repo}" if repo
+      puts "📝 Would create #{issues.length} issues:"
+      puts
+
+      issues.each_with_index do |issue, idx|
+        params = site.convert_issue_to_site_params(issue, repo, dry_run: true)
+        puts "#{idx + 1}. #{params[:title]}"
+        puts "   Labels: #{params[:labels].join(', ')}" if params[:labels]&.any?
+        puts "   Assignee: #{params[:assignee]}" if params[:assignee]
+        puts "   Milestone: #{params[:milestone]}" if params[:milestone]
+        puts
+      end
+
+      {
+        dry_run: true,
+        issues_planned: issues.length,
+        target_repo: repo,
+        valid_issues: issues.length
+      }
+    end
+
+    def perform_live_run(issues, repo, automation_options)
+      site = get_site
+
+      # Start run tracking if caching enabled
+      run_id = if @cache_enabled
+        Cache.start_run(issues_planned: issues.length, target_repo: repo)
+      else
+        nil
+      end
+
+      begin
+        # Validate and prepare resources (milestones, labels)
+        Ops.validate_and_prepare_resources(site, repo, issues, automation_options, run_id) unless issues.empty?
+
+        # Create issues
+        processed_count = site.post_issues(repo, issues, run_id)
+
+        # Complete run tracking
+        Cache.complete_run(run_id, processed_count) if run_id
+
+        {
+          dry_run: false,
+          issues_created: processed_count,
+          issues_planned: issues.length,
+          target_repo: repo,
+          run_id: run_id
+        }
+      rescue => e
+        # Mark run as failed
+        Cache.fail_run(run_id, e.message) if run_id
+        raise
+      end
+    end
+  end
+end

data/scripts/build.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Release automation script for Ruby gem projects
+
+set -e
+
+# Load common build functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/build-common.sh"
+
+# Project-specific configuration
+PROJECT_NAME="issuer"
+DOCKER_ORG="docopslab"
+
+echo -e "${GREEN}🚀 ${PROJECT_NAME} Release Build Script${NC}"
+echo "=================================="
+
+# Validation
+check_project_root
+check_git_clean
+check_main_branch
+check_bundle_installed
+
+# Run tests
+run_rspec_tests
+test_cli_functionality
+
+# Get current version
+current_version=$(get_current_version)
+echo -e "${GREEN}📋 Current version: $current_version${NC}"
+
+# Build and test gem
+build_gem
+gem_file=$(test_built_gem)
+
+# Build Docker image using the docker-specific script
+echo -e "${YELLOW}🐳 Building Docker image...${NC}"
+"$SCRIPT_DIR/build-docker.sh" 2>&1 | grep -E "(Building|Testing|successfully|Docker image:)" || true
+
+# Show final success message
+show_build_success "$current_version" "$gem_file"

data/scripts/lint-docs.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Vale linting script for the issuer project
+
+set -e
+
+echo "🔍 Running Vale linter on issuer project..."
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if Vale is installed
+if ! command -v vale &> /dev/null; then
+  echo -e "${RED}❌ Vale is not installed. Please install Vale first.${NC}"
+  echo "   You can install it from: https://github.com/errata-ai/vale"
+  exit 1
+fi
+
+# Check if .vale.ini exists
+if [[ ! -f ".vale.ini" ]]; then
+  echo -e "${RED}❌ .vale.ini not found in current directory${NC}"
+  echo "   Please run this script from the project root."
+  exit 1
+fi
+
+# Default to checking all relevant files if no arguments provided
+if [[ $# -eq 0 ]]; then
+  FILES=(
+    "README.adoc"
+    "lib/examples/*.md"
+    "specs/tests/*.md" 
+    "*.adoc"
+    "docs/*.adoc"
+  )
+else
+  FILES=("$@")
+fi
+
+echo "📁 Files to check: ${FILES[*]}"
+echo ""
+
+# Run Vale
+EXIT_CODE=0
+for pattern in "${FILES[@]}"; do
+  # Use find to expand patterns and handle missing files gracefully
+  while IFS= read -r -d '' file; do
+    if [[ -f "$file" ]]; then
+      echo -e "${YELLOW}📄 Checking: $file${NC}"
+      if ! vale "$file"; then
+        EXIT_CODE=1
+      fi
+    fi
+  done < <(find . -name "$pattern" -print0 2>/dev/null)
+done
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+  echo -e "${GREEN}✅ Vale linting completed successfully!${NC}"
+else
+  echo -e "${RED}❌ Vale found issues. Please review and fix them.${NC}"
+fi
+
+exit $EXIT_CODE

data/scripts/manage-runs.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run management utility for issuer CLI
+# Lists and manages cached runs in .issuer/logs/
+
+require 'bundler/setup'
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'issuer/cache'
+
+def show_help
+  puts <<~HELP
+  Issuer Run Management Utility
+  
+  Usage:
+    ruby scripts/manage-runs.rb [command]
+  
+  Commands:
+    list                 List all cached runs
+    list --recent        List recent runs only (last 10)
+    show RUN_ID          Show detailed information for a specific run
+    clean-logs           Remove all log files (use with caution)
+    
+  Examples:
+    ruby scripts/manage-runs.rb list
+    ruby scripts/manage-runs.rb show run_20250711_180124_97d1f1f3
+    ruby scripts/manage-runs.rb list --recent
+  HELP
+end
+
+def list_runs recent_only = false
+  runs = Issuer::Cache.list_runs
+  runs = runs.take(10) if recent_only
+  
+  if runs.empty?
+    puts "No cached runs found."
+    return
+  end
+  
+  puts "Cached Runs#{recent_only ? ' (Recent)' : ''}:"
+  puts "=" * 60
+  
+  runs.each do |run|
+    puts "#{run[:run_id]} - #{run[:status].upcase}"
+    puts "  Started: #{run[:started_at]}"
+    
+    if run[:metadata] && run[:metadata][:issues_planned]
+      puts "  Issues planned: #{run[:metadata][:issues_planned]}"
+    end
+    
+    if run[:status] == 'completed'
+      puts "  Completed: #{run[:completed_at]}"
+      puts "  Artifacts: #{run[:summary][:issues_created]} issues, #{run[:summary][:milestones_created]} milestones, #{run[:summary][:labels_created]} labels"
+      puts "  Processed: #{run[:summary][:issues_processed]} issues"
+    elsif run[:status] == 'failed'
+      puts "  Failed: #{run[:failed_at] || 'unknown time'}"
+      puts "  Error: #{run[:error] || 'no error message'}"
+    end
+    puts ""
+  end
+  
+  puts "Total: #{runs.length} runs"
+  puts "Use 'ruby scripts/manage-runs.rb show RUN_ID' for detailed view"
+end
+
+def show_run run_id
+  run_data = Issuer::Cache.get_run(run_id)
+  unless run_data
+    puts "Error: Run #{run_id} not found."
+    return
+  end
+  
+  puts "Run Details: #{run_id}"
+  puts "=" * 60
+  puts "Status: #{run_data[:status]}"
+  puts "Started: #{run_data[:started_at]}"
+  
+  if run_data[:completed_at]
+    puts "Completed: #{run_data[:completed_at]}"
+  end
+  
+  if run_data[:failed_at]
+    puts "Failed: #{run_data[:failed_at]}"
+    puts "Error: #{run_data[:error]}" if run_data[:error]
+  end
+  
+  if run_data[:metadata]
+    puts ""
+    puts "Metadata:"
+    run_data[:metadata].each do |key, value|
+      puts "  #{key}: #{value}"
+    end
+  end
+  
+  if run_data[:artifacts]
+    puts ""
+    puts "Artifacts Created:"
+    
+    [:issues, :milestones, :labels].each do |type|
+      artifacts = run_data[:artifacts][type.to_s] || run_data[:artifacts][type] || []
+      next if artifacts.empty?
+      
+      puts "  #{type.to_s.capitalize} (#{artifacts.length}):"
+      artifacts.each do |artifact|
+        case type
+        when :issues
+          puts "    ##{artifact[:number] || artifact['number']} - #{artifact[:title] || artifact['title']}"
+          puts "      #{artifact[:url] || artifact['url']}"
+        when :milestones
+          puts "    ##{artifact[:number] || artifact['number']} - #{artifact[:title] || artifact['title']}"
+          puts "      #{artifact[:url] || artifact['url']}"
+        when :labels
+          puts "    #{artifact[:name] || artifact['name']} (#{artifact[:color] || artifact['color']})"
+          puts "      #{artifact[:url] || artifact['url']}"
+        end
+        puts ""
+      end
+    end
+  end
+  
+  if run_data[:summary]
+    puts "Summary:"
+    run_data[:summary].each do |key, value|
+      puts "  #{key}: #{value}"
+    end
+  end
+end
+
+def clean_logs
+  logs_dir = Issuer::Cache.logs_dir
+  unless Dir.exist?(logs_dir)
+    puts "No logs directory found."
+    return
+  end
+  
+  log_files = Dir.glob(File.join(logs_dir, '*.json'))
+  if log_files.empty?
+    puts "No log files found."
+    return
+  end
+  
+  puts "Found #{log_files.length} log files."
+  print "Are you sure you want to delete all log files? [y/N]: "
+  response = STDIN.gets.chomp.downcase
+  
+  unless ['y', 'yes'].include?(response)
+    puts "Cancelled."
+    return
+  end
+  
+  log_files.each { |f| File.delete(f) }
+  puts "Deleted #{log_files.length} log files."
+end
+
+# Main execution
+case ARGV[0]
+when 'list'
+  recent_only = ARGV.include?('--recent')
+  list_runs(recent_only)
+when 'show'
+  if ARGV[1]
+    show_run(ARGV[1])
+  else
+    puts "Error: Please specify a run ID"
+    puts "Usage: ruby scripts/manage-runs.rb show RUN_ID"
+  end
+when 'clean-logs'
+  clean_logs
+when nil, '--help', '-h'
+  show_help
+else
+  puts "Error: Unknown command '#{ARGV[0]}'"
+  puts ""
+  show_help
+end

data/scripts/pre-commit-template.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Pre-commit hook for Vale linting
+
+set -e
+
+echo "🔍 Running Vale pre-commit check..."
+
+# Check if Vale is installed
+if ! command -v vale &> /dev/null; then
+  echo "⚠️  Vale not found. Skipping documentation linting."
+  echo "   Install Vale to enable documentation quality checks."
+  exit 0
+fi
+
+# Get list of staged files that we care about (excluding copilot instructions)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(md|adoc|asciidoc)$' | grep -v '^\.github/copilot-instructions\.md$' || true)
+
+if [[ -z "$STAGED_FILES" ]]; then
+  echo "ℹ️  No documentation files staged for commit."
+  exit 0
+fi
+
+echo "📄 Checking staged documentation files:"
+echo "$STAGED_FILES"
+
+# Run Vale on staged files
+TEMP_DIR=$(mktemp -d)
+EXIT_CODE=0
+
+for file in $STAGED_FILES; do
+  if [[ -f "$file" ]]; then
+    # Copy staged version to temp location
+    git show :"$file" > "$TEMP_DIR/$(basename "$file")"
+    
+    echo "🔍 Linting: $file"
+    if ! vale "$TEMP_DIR/$(basename "$file")"; then
+        EXIT_CODE=1
+    fi
+  fi
+done
+
+# Cleanup
+rm -rf "$TEMP_DIR"
+
+if [[ $EXIT_CODE -ne 0 ]]; then
+  echo ""
+  echo "❌ Vale found documentation issues in staged files."
+  echo "   Please fix the issues above before committing."
+  echo "   Or use 'git commit --no-verify' to bypass this check."
+  exit 1
+fi
+
+echo "✅ Documentation quality check passed!"
+exit 0

data/scripts/publish.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Manual publishing script for Ruby gem projects
+
+set -e
+
+# Parse command line arguments
+DRY_RUN=false
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: $0 [--dry-run]"
+      exit 1
+      ;;
+  esac
+done
+
+# Load common build functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/build-common.sh"
+
+# Project-specific configuration
+PROJECT_NAME="issuer"
+DOCKER_ORG="docopslab"
+
+echo -e "${GREEN}📦 ${PROJECT_NAME} Publishing Script${NC}"
+echo "=============================="
+
+# Check for required environment variables (skip in dry-run mode)
+if [ "$DRY_RUN" = false ]; then
+    if [ -z "$RUBYGEMS_API_KEY" ]; then
+        echo -e "${RED}❌ Error: RUBYGEMS_API_KEY environment variable not set${NC}"
+        echo "Get your API key from https://rubygems.org/profile/edit"
+        echo "Then run: export RUBYGEMS_API_KEY=your_key_here"
+        exit 1
+    fi
+
+    if [ -z "$DOCKERHUB_USERNAME" ] || [ -z "$DOCKERHUB_TOKEN" ]; then
+        echo -e "${RED}❌ Error: Docker Hub credentials not set${NC}"
+        echo "Set DOCKERHUB_USERNAME and DOCKERHUB_TOKEN environment variables"
+        exit 1
+    fi
+fi
+
+# Get current version
+current_version=$(get_current_version)
+gem_file="pkg/${PROJECT_NAME}-$current_version.gem"
+
+# Check if gem file exists
+if [ ! -f "$gem_file" ]; then
+    echo -e "${RED}❌ Error: Gem file $gem_file not found${NC}"
+    echo "Run ./scripts/build.sh first"
+    exit 1
+fi
+
+if [ "$DRY_RUN" = true ]; then
+  echo -e "${YELLOW}🔍 Dry run mode enabled. The following actions would be performed:${NC}"
+  echo "- Publish to RubyGems: gem push $gem_file"
+  echo "- Login to Docker Hub and push Docker images"
+else
+  # Publish to RubyGems
+  echo -e "${YELLOW}💎 Publishing to RubyGems...${NC}"
+  mkdir -p ~/.gem
+  echo ":rubygems_api_key: $RUBYGEMS_API_KEY" > ~/.gem/credentials
+  chmod 0600 ~/.gem/credentials
+  gem push "$gem_file"
+  echo -e "${GREEN}✅ Published to RubyGems successfully${NC}"
+
+  # Login to Docker Hub
+  echo -e "${YELLOW}🐳 Logging in to Docker Hub...${NC}"
+  echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
+
+  # Push Docker images
+  echo -e "${YELLOW}🐳 Pushing Docker images...${NC}"
+  docker push ${DOCKER_ORG}/${PROJECT_NAME}:$current_version
+  docker push ${DOCKER_ORG}/${PROJECT_NAME}:latest
+  echo -e "${GREEN}✅ Pushed Docker images successfully${NC}"
+fi
+
+echo
+echo -e "${GREEN}🎉 Publishing completed successfully!${NC}"
+echo "=============================="
+echo -e "Gem: ${YELLOW}https://rubygems.org/gems/${PROJECT_NAME}/versions/$current_version${NC}"
+echo -e "Docker: ${YELLOW}https://hub.docker.com/r/${DOCKER_ORG}/${PROJECT_NAME}${NC}"
+echo
+echo "Verify installation:"
+echo "  gem install ${PROJECT_NAME}"
+echo "  docker pull ${DOCKER_ORG}/${PROJECT_NAME}:$current_version"