issuer 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fd7532708ed57245a8e2721d299cd2931c24737da8a156bd238cc5977e4691c
-  data.tar.gz: 7f277c821b7fe8bb7eda03b5e85718202409fe54bd84d8b4e50bb8911fcce337
+  metadata.gz: 9b9b8755cfce731755363e16c9499632533330adb62e565b1bafcd4b158c820e
+  data.tar.gz: 9372bd2d0245dd42e28143fb11060d173e14ad2bfa2422ef85dc5eb70897528c
 SHA512:
-  metadata.gz: 381f003520f2c514445bbea944589839a189fa3afee7126d0567d61d680b1a4b79b407886db97749e1cdf9efcb2bb46679e33002700604ed64fa054ee8bcc245
-  data.tar.gz: ff486e3bc512907226b7f4fadf454f091cf853dad7c1492f0d5e410b82a3b4584d63a6a817c5fbe6c8d3437770b3ad59ba1b78070cac3cc4559996df6fb75f3a
+  metadata.gz: 9e984bb19ef6339cd9b172dccb5108b376ce5e75565669d5eaacb4694f3978e278b152bc16bceb3e613ea6dd2cb161f463521b87970630555cfb3368527a72ba
+  data.tar.gz: 46e27411826c5c25a647bd8d7260c0284deffa5413285937e994e76c06f1cc70fe1e47954be085116df2f8162259d1796ce379f953cb4d2d5c09723a13a5612d

data/README.adoc

@@ -1,9 +1,9 @@
 = Issuer: Bulk GitHub Issue Creator
 :toc: macro
 :toclevels: 3
-:this_prod_vrsn: 0.2.1
-:next_prod_vrsn: 0.3.0
-:docker_base_command: docker run -it --rm -v $(pwd):/workdir -e ISSUER_API_TOKEN=$GITHUB_TOKEN docopslab/issuer
+:this_prod_vrsn: 0.3.0
+:next_prod_vrsn: 0.4.0
+:docker_base_command: docker run -it --rm --user $(id -u):$(id -g) -v $(pwd):/workdir -e ISSUER_API_TOKEN=$GITHUB_TOKEN docopslab/issuer
 :append_or_impose: Prepend items with `+` to indicate they should be appended to existing labels. Items without `+` will only be used for issues with no `tags` designated.
 ifdef::env-github[]
 :icons: font
@@ -15,6 +15,8 @@ ifdef::env-github[]
 endif::[]
 
 
+// tag::ai-prompt[]
+[[overview]]
 == Overview
 
 _Issuer_ lets you define all your GitHub Issues work tickets in one place as YAML, apply defaults, and post them to GitHub Issues in bulk.
@@ -29,6 +31,8 @@ _Issuer_ lets you define all your GitHub Issues work tickets in one place as YAM
 * *Issue validation* with helpful error messages
 * *GitHub API integration*
 
+// end::ai-prompt[]
+
 Future plans include extending this capability to *Jira* (link:https://github.com/DocOps/issuer/issues/9[#9]), *GitLab* Issues (link:https://github.com/DocOps/issuer/issues/33[#33]), GitHub *Projects*, and other services.
 
 toc::[]
@@ -92,15 +96,18 @@ See <<usage>> for more.
 ==== Alias the Docker Command
 
 Optionally alias the base Docker command.
-In your shell configuration (usually `~/.bashrc` or `~/.zshrc), add the following:
+In your shell configuration (usually `~/.bashrc` or `~/.zshrc`), add the following:
 
 [.prompt,subs=+attributes]
  alias issuer='{docker_base_command}'
 
 Reload your shell configuration for the alias to take effect:
 
-[.prompt]
- source ~/.bashrc
+....
+source ~/.bashrc
+# or
+source ~/.zshrc
+....
 
 === For Ruby Users
 
@@ -151,6 +158,7 @@ For Ruby Bundler usage, prepend `bundle exec ` and for un-aliased Docker usage,
 [.prompt]
  issuer example.yml
 
+// tag::user-agent-prompt[]
 [[imyml-format]]
 === IMYML File Format
 
@@ -329,8 +337,8 @@ Whether to treat the issue as a stub entry, meaning prepend any `$meta.defaults.
 
 A source IMYML file is required and can be specified in two ways:
 
-* *Positional argument* (most common): Place the file path immediately after `issuer`
-* *Named option*: Use the `--file` option flag to specify the file path
+* *Positional argument* (most common). Place the file path immediately after `issuer`
+* *Named option.* Use the `--file` option flag to specify the file path
 
 Examples:
 
@@ -367,6 +375,11 @@ Whether to treat all issues as stubs, meaning prepend any `$meta.defaults.head`
 --dry, --dry-run::
 Dry-run: print actions but do not post to GitHub.
 
+--json [_FILE_PATH_]::
+Save GitHub API issue payload as JSON file.
+Use `--dry` if you want to skip posting while generating JSON. 
+If no `FILE_PATH` is specified, saves to time-stamped file in `_payloads/` directory.
+
 --auto-versions, --auto-milestones::
 Automatically create missing milestones/versions without prompting for confirmation.
 
@@ -382,6 +395,8 @@ Prints the usage screen.
 --version::
 Prints the version of `issuer`.
 
+// end::user-ai-prompt[]
+
 [[authentication]]
 === Authentication
 
@@ -423,9 +438,10 @@ Issuer automatically logs all API operations for tracking and potential cleanup.
 
 By default, logs are stored in a user-wide directory:
 
-* *Linux/macOS*: `~/.config/issuer/logs/`
-* *With XDG Base Directory*: `$XDG_CONFIG_HOME/issuer/logs/`
-* *Custom location*: Set `ISSUER_CONFIG_DIR` environment variable
+[horizontal]
+Linux/macOS:: `~/.config/issuer/logs/`
+With XDG Base Directory:: `$XDG_CONFIG_HOME/issuer/logs/`
+Custom location:: Set `ISSUER_CONFIG_DIR` environment variable
 
 Example:
 [source,bash]
@@ -491,6 +507,8 @@ In the end, the only thing that is mainly untouched by me are the rspec tests, w
 This also explains why the terminal output contains emojis.
 I will probably make those togglable or configurable in the future.
 
+// tag::dev-ai-prompt[]
+[[tests]]
 === Tests
 
 The `specs/` directory contains all specifications, requirements, and tests for the Issuer CLI tool.
@@ -535,10 +553,10 @@ bundle exec rspec --pattern "*ops*"
 
 The `pr_test` task runs the exact same tests that GitHub Actions runs for pull requests:
 
-* *RSpec Tests*: All unit tests (`bundle exec rake spec`)
-* *CLI Tests*: Command-line interface functionality tests
-* *YAML Validation*: Validates all example YAML files
-* *Documentation Quality*: Vale linting on all documentation files
+RSpec Tests:: All unit tests (`bundle exec rake spec`)
+CLI Tests:: Command-line interface functionality tests
+YAML Validation:: Validates all example YAML files
+Documentation Quality:: Vale linting on all documentation files
 
 This ensures you can validate your changes locally before pushing to GitHub.
 
@@ -597,39 +615,36 @@ The API reference includes:
 
 This documentation is automatically updated with each gem release.
 
-=== Release History Management
+// end::dev-ai-prompt[]
 
-As of version 0.2.0, the Release Notes and Changelog are generated using the _ReleaseHx_ tool, which is still in pre-release.
-You can find the release history assets in the `docs/releasehx/` directory, which contains a configuration file and the 0.2.0 "`RHYML`" file that was auto-modified and then manually edited to produce the GitHub link:https://github.com/DocOps/issuer/releases[release announcement].
-
-ReleaseHx will be available soon, but for now the following is only usable by DocOps Lab.
+[[release-history-management]]
+=== Release History Management
 
-. Add local releasehx gem to `Gemfile`:
-+
-[source,ruby]
-gem 'releasehx', path: '../releasehx'
+As of version 0.2.0, Release Notes and Changelog are generated using the link:https://github.com/DocOps/releasehx[_ReleaseHx_] tool.
+You can find the release history assets in the `docs/releases/` directory, while the ReleaseHx configuration lives at `.config/releasehx.yml`.
+The RHYML files are auto-generated and then manually edited to produce the GitHub link:https://github.com/DocOps/issuer/releases[release announcements].
 
 . Draft RHYML draft file from the online GitHub Issues for the given version:
 +
 [.prompt,subs=+attributes]
- ./releasehx-install.sh && bundle exec rhx {this_prod_vrsn} --yaml docs/releasehx/release-{this_prod_vrsn}.yml --config docs/releasehx/config.yml
-+
-The `releasehx-install.sh` ensures ReleaseHx is up to date.
+ bundle exec rhx {this_prod_vrsn} --yaml docs/releases/{this_prod_vrsn}.yml --config .config/releasehx.yml
 
 . Manually edit the RHYML draft file.
 
 . Generate the release history as Markdown.
 +
 [.prompt,subs=+attributes]
- bundle exec rhx docs/releasehx/release-{this_prod_vrsn}.yml --md docs/releasehx/{this_prod_vrsn}.md --config docs/releasehx/config.yml
+ bundle exec rhx docs/releases/{this_prod_vrsn}.yml --md docs/releases/{this_prod_vrsn}.md --config .config/releasehx.yml
 
-. Copy and paste the contents of `docs/releasehx/{this_prod_vrsn}.md` into the GitHub release form at https://github.com/DocOps/issuer/releases/new.
+. Copy and paste the contents of `docs/releases/{this_prod_vrsn}.md` into the GitHub release form at https://github.com/DocOps/issuer/releases/new.
 
 [[contributing]]
 === Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/DocOps/issuer.
 
+
+[[legal]]
 == Legal
 
 The gem is available as open source under the terms of the MIT License.

data/issuer.gemspec

@@ -31,10 +31,4 @@ Gem::Specification.new do |spec|
   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

@@ -56,7 +56,7 @@ module Issuer
             params[:assignee] = issue_params[:assignee].strip
           end
 
-          # Handle milestone - only if milestone exists
+          # Handle milestone; only if milestone exists
           if issue_params[:milestone]
             milestone = find_milestone(repo, issue_params[:milestone])
             params[:milestone] = milestone.number if milestone
@@ -259,7 +259,7 @@ module Issuer
         def resolve_label_ids repo, label_names
           # For now, we'll skip complex label ID resolution
           # GitHub GraphQL API requires label IDs, but REST API uses names
-          # This is a simplification - in practice, you'd need to fetch and match labels
+          # This is a simplification; in practice, you'd need to fetch and match labels
           []
         end
 

data/lib/issuer/cache.rb

@@ -142,7 +142,7 @@ module Issuer
       elsif summary_section.key?(counter_key)
         summary_section[counter_key] += 1
       else
-        # Fallback - create the key as string
+        # Fallback; create the key as string
         summary_section[counter_key] = 1
       end
 

data/lib/issuer/cli.rb

@@ -18,6 +18,7 @@ module Issuer
     class_option :tags, type: :string, desc: 'Comma-separated default or appended (+) labels for all issues'
     class_option :stub, type: :boolean, desc: 'Enable stub mode for all issues'
     class_option :dry, type: :boolean, default: false, aliases: ['--dry-run'], desc: 'Print issues, don\'t post'
+    class_option :json, type: :string, lazy_default: '', desc: 'Save API payloads as JSON to PATH (defaults to _payloads/). Combine with --dry to skip posting.'
     class_option :tokenv, type: :string, desc: 'Name of environment variable containing GitHub token'
 
     # Resource automation options
@@ -96,8 +97,9 @@ module Issuer
       defaults['stub'] = options[:stub] if !options[:stub].nil?
 
       # Determine target repository
+      dry_mode = options[:dry]
       repo = options[:proj] || meta['proj'] || ENV['ISSUER_REPO'] || ENV['ISSUER_PROJ']
-      if repo.nil? && !options[:dry]
+      if repo.nil? && !dry_mode
         abort 'No target repo set. Use --proj, $meta.proj, or ENV[ISSUER_REPO].'
       end
 
@@ -110,6 +112,9 @@ module Issuer
       # Apply stub logic with head/tail/body composition
       issues = Issuer::Ops.apply_stub_logic(issues, defaults)
 
+      json_requested = !options[:json].nil?
+      json_path = options[:json]
+
       # Separate valid and invalid issues
       valid_issues = issues.select(&:valid?)
       invalid_issues = issues.reject(&:valid?)
@@ -119,8 +124,11 @@ module Issuer
         puts "Skipping issue ##{find_original_index(issues, issue) + 1}: #{issue.validation_errors.join(', ')}"
       end
 
-      if options[:dry]
-        perform_dry_run(valid_issues, repo)
+      site = nil
+
+      if dry_mode
+        site = build_dry_run_site
+        perform_dry_run(valid_issues, repo, site)
       else
         # Use Sites architecture for validation and posting
         site_options = {}
@@ -151,7 +159,9 @@ module Issuer
         end
       end
 
-      print_summary(valid_issues.length, invalid_issues.length, options[:dry])
+      perform_json_output(valid_issues, repo, json_path, site, dry_run: dry_mode) if json_requested
+
+      print_summary(valid_issues.length, invalid_issues.length, dry_mode)
     end
 
     private
@@ -175,6 +185,7 @@ module Issuer
 
       Mode Options:
         --dry, --dry-run         #{self.class_options[:dry].description}
+        --json [PATH]            #{self.class_options[:json].description}
         --auto-versions          #{self.class_options[:auto_versions].description}
         --auto-milestones        (alias for --auto-versions)
         --auto-tags              #{self.class_options[:auto_tags].description}
@@ -190,6 +201,7 @@ module Issuer
         issuer issues.yml --proj myorg/myrepo
         issuer --file issues.yml --proj myorg/myrepo --dry
         issuer issues.yml --vrsn 1.1.2
+        issuer issues.yml --json dry-output.json
         issuer --version
         issuer --help
 
@@ -203,16 +215,11 @@ module Issuer
       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)
-
+    def perform_dry_run issues, repo, site
       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'
@@ -220,6 +227,64 @@ module Issuer
       end
     end
 
+    def perform_json_output issues, repo, json_path, site, dry_run:
+      require 'json'
+      require 'fileutils'
+
+      if json_path.empty?
+        output_dir = '_payloads'
+        timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+        output_path = File.join(output_dir, "issues_#{timestamp}.json")
+      else
+        output_path = json_path
+        output_dir = File.dirname(output_path)
+      end
+
+      FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
+
+      # Convert issues to API payloads
+      payloads = issues.map do |issue|
+        site.convert_issue_to_site_params(issue, repo, dry_run: dry_run)
+      end
+
+      # Create JSON structure
+      json_data = {
+        metadata: {
+          generated_at: Time.now.iso8601,
+          repository: repo,
+          total_issues: issues.length,
+          issuer_version: Issuer::VERSION
+        },
+        issues: payloads
+      }
+
+      File.write(output_path, JSON.pretty_generate(json_data))
+
+      puts "Saved #{issues.length} issue payloads to: #{output_path}"
+
+      puts "\nIssue preview:"
+      issues.first(3).each do |issue|
+        print_issue_summary(issue, repo, site)
+      end
+
+      if issues.length > 3
+        puts "... and #{issues.length - 3} more issues"
+        puts "------\n"
+      end
+
+      # Add project summary
+      if repo
+        project_term = site.field_mappings[:project_name] || 'project'
+        puts "JSON contains #{issues.length} issue payloads for #{project_term}: #{repo}"
+      end
+    end
+
+    def build_dry_run_site
+      site_options = { token: 'dry-run-token' }
+      site_options[:token_env_var] = options[:tokenv] if options[:tokenv]
+      Issuer::Sites::Factory.create('github', **site_options)
+    end
+
     def print_summary valid_count, invalid_count, dry_run
       if dry_run
         puts "\nDry run complete (use without --dry to actually post)"
@@ -228,7 +293,7 @@ module Issuer
         puts "\n✅ Completed: #{valid_count} issues processed, #{invalid_count} skipped"
         # Note: Run ID is already displayed in the main flow, no need to repeat it here
       end
-      
+
     end
 
     def print_issue_summary issue, repo, site

data/lib/issuer/issue.rb

@@ -78,7 +78,7 @@ module Issuer
       @type = @raw_data['type'] || defaults['type']
       @stub = @raw_data.key?('stub') ? @raw_data['stub'] : defaults['stub']
       
-      # For tags, we need special handling - combine defaults and issue tags for later processing
+      # For tags, we need special handling; combine defaults and issue tags for later processing
       defaults_tags = Array(defaults['tags'])
       issue_tags = Array(@raw_data['tags'])
       @tags = defaults_tags + issue_tags
@@ -401,7 +401,7 @@ module Issuer
       # Get terminal width, default to 80 if not available
       terminal_width = ENV['COLUMNS']&.to_i || 80
       
-      # Calculate available width for content (terminal width - indentation)
+      # Calculate available width for content (terminal width; indentation)
       available_width = terminal_width - indent_size
       
       # If line fits within available width, just return it with indentation

data/lib/issuer/ops.rb

@@ -14,7 +14,7 @@ module Issuer
     # 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 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
     #

data/lib/issuer/sites/github.rb

@@ -77,7 +77,7 @@ module Issuer
           params[:assignee] = issue_params[:assignee].strip
         end
 
-        # Handle milestone - only if milestone exists
+        # Handle milestone; only if milestone exists
         if issue_params[:milestone]
           # If milestone is already a number (from convert_issue_to_site_params), use it directly
           if issue_params[:milestone].is_a?(Integer)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: issuer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - DocOps Lab
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: octokit
@@ -52,62 +51,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: asciidoctor
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 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.
@@ -145,8 +88,7 @@ metadata:
   homepage_uri: https://github.com/DocOps/issuer
   source_code_uri: https://github.com/DocOps/issuer
   changelog_uri: https://github.com/DocOps/issuer/blob/main/CHANGELOG.md
-  documentation_uri: https://gemdocs.org/gems/issuer/0.2.1
-post_install_message:
+  documentation_uri: https://gemdocs.org/gems/issuer/0.3.0
 rdoc_options: []
 require_paths:
 - lib
@@ -161,8 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Bulk GitHub issue creator from YAML definitions
 test_files: []