gem_hadar 1.26.0 → 1.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3fefed7b5fd9123e2944de9cf2defcd9f1794aaa7d0058621539b22a2e076d3
-  data.tar.gz: 8734f8f3cf30c0a0b501e5484a58bc5b4bbc4190258133f6de7b1105f17c7383
+  metadata.gz: db714afa72ba58c1676c20ec7efdfe235300f384f839ea663880b0ae976a9a0b
+  data.tar.gz: 6f1ebe9a6446fc600e00d0964a9f3f215cccc264454468bec4dc93e9ff8c674a
 SHA512:
-  metadata.gz: 867a63019ba90544ba9b0c91478482128d3527221d9c11473929d9f18b5c74673d2fc3ab5844bc26779680b724965a9a7a455518286c5ca9a496342371c31c1a
-  data.tar.gz: a6fa278536336a668d025947b3d9f274d4cc02ae9e2a3d50bb2a2a87b42ee2d351bfb191d9eb472bd215b521c34b561c4ee5d9f15cfcec93576f98871df23c10
+  metadata.gz: c89a930270aa72bb13179e6bedd38c4cc5971f8924aba2f86c588925a62baf5141191d065289f6b7a75d1e05f99beb17b91db78f09c23529ab04625d3147b271
+  data.tar.gz: 5a1eddb1dba0410f324a519b3b445036ec8c6e53c2406968161169133d9f7fd17c1e4e558f9fa72d4b1bdbca4f532ec0e93a4ef616a0796521f2de2d86452dc2

data/README.md

@@ -85,6 +85,151 @@ or can be installed via
 $ gem install gem_hadar
 ```
 
+## Configuration
+
+### Environment Variables
+
+The following environment variables can be used to configure `gem_hadar`:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GEM_HOST_API_KEY` | API key for gem hosting services | Not set |
+| `GITHUB_API_TOKEN` | GitHub personal access token for releases | Not set |
+| `OLLAMA_MODEL` | Ollama model name for AI generation | `llama3.1` |
+| `OLLAMA_HOST` | Ollama server host URL | `localhost:11434` |
+| `OLLAMA_URL` | Direct Ollama API URL (takes precedence over `OLLAMA_HOST`) | Not set |
+| `OLLAMA_MODEL_OPTIONS` | JSON configuration for Ollama model | Not set |
+| `HOME` | User's home directory (used for config file locations) | System default |
+| `XDG_CONFIG_HOME` | XDG configuration directory override | System default |
+| `MAKE` | Make program to use for building extensions | `gmake` or `make` |
+| `VERSION` | Override the version string for some tasks | Not set |
+| `FORCE` | Force certain operations (1 to enable) | 0 |
+| `GIT_REMOTE` | Git remote name(s) for operations, space separated | `origin` |
+| `GITHUB_RELEASE_ENABLED` | Enable GitHub releases (yes/no) | Auto-detected |
+| `EDITOR` | Editor to use for interactive tasks | `vi` |
+
+### Rubygems API
+
+To publish gems to RubyGems.org, you'll need to set up an API key:
+
+1. Generate a new API key at: https://rubygems.org/profile/api\_keys/new
+2. Set the environment variable:
+
+```bash
+export GEM_HOST_API_KEY="your_api_key_here"
+```
+
+**Security Note**: Never commit your API key to version control. Use a `.env`
+file or your shell's configuration with appropriate loading mechanisms.
+
+This key is required for tasks like `rake release` which push the gem package to RubyGems.org.
+
+### Github API
+
+To enable GitHub release creation and other GitHub API interactions, you'll
+need to set up a personal access token.
+
+1. Generate a new token at: https://github.com/settings/tokens/new
+2. Grant it `repo` scope for full repository access
+3. Set the environment variable:
+
+```bash
+export GITHUB_API_TOKEN="your_token_here"
+```
+
+**Security Note**: Never commit your token to version control. Use a `.env`
+file or your shell's configuration with appropriate loading mechanisms.
+
+This token is required for tasks like `rake github:release` which create GitHub
+releases with AI-generated changelogs.
+
+### Local Ollama AI
+
+The gem supports AI-powered changelog generation using Ollama. To configure
+this functionality:
+
+1. Install and run Ollama locally: https://ollama.com/download
+2. Pull the desired model (e.g., `ollama pull deepseek-r1:32b`)
+3. Set the following environment variables:
+
+```bash
+export OLLAMA_HOST="http://localhost:11434"
+export OLLAMA_MODEL="deepseek-r1:32b"
+export OLLAMA_MODEL_OPTIONS='{"num_ctx":16384,"seed":-1,"num_predict":512,"temperature":0.4,"top_p":0.95,"top_k":20,"min_p":0}'
+```
+
+The default model is `llama3.1` and the default host is
+`http://localhost:11434`. These can be overridden based on your local Ollama
+setup.
+
+The model options example configures:
+
+- `num_ctx`: Context window size (16384 tokens)
+- `temperature`: Response randomness (0.4 for balanced output)
+- `num_predict`: Maximum tokens to generate (512)
+- `top_p`, `top_k`, `min_p`: Sampling parameters for controlled generation
+
+This functionality is used by the `rake github:release` and `rake version:bump`
+task to generate AI-powered changelogs or suggest a version bump.
+
+### Custom AI Prompts
+
+To customize the AI prompts used by `gem_hadar`, you can override the default
+prompt files in your XDG configuration directory.
+
+First, display the current default prompts using:
+
+```bash
+$ rake gem_hadar:config
+```
+
+This will show you the `XDG_CONFIG_HOME`, default system and user prompts for
+version bumping and release generation. The output includes the exact template
+variables that are available for use in your custom prompts.
+
+Then, create the following files in your XDG configuration home directory:
+
+- `version_bump_system_prompt.txt`
+- `version_bump_prompt.txt` 
+- `release_system_prompt.txt`
+- `release_prompt.txt`
+
+Start with the default values shown by `rake gem_hadar:config` and modify them
+to suit your needs. The prompts support standard Ruby string interpolation with
+the following variables:
+
+For version bump prompts:
+- `%{version}` - Current gem version
+- `%{log_diff}` - Git diff of changes
+
+For release prompts:
+- `%{name}` - Gem name
+- `%{version}` - New version being released
+- `%{log_diff}` - Git diff of changes
+
+This approach ensures your custom prompts work correctly with the template
+variables while maintaining consistency with the gem's expected input format.
+
+### Output current configuration
+
+To debug or verify your `gem_hadar` configuration, you can use the following
+rake task:
+
+```bash
+$ rake gem_hadar:config
+```
+
+This task displays all current configuration values including:
+- GitHub API token (masked)
+- RubyGems API key (masked)  
+- Ollama model settings
+- Repository information (gem name, version)
+- Build parameters (MAKE, EDITOR)
+- Git configuration (remote)
+- Other flags (FORCE, VERSION, GITHUB_RELEASE_ENABLED)
+- XDG/HOME directories
+- AI prompt defaults
+
 ## Usage
 
 ### Pre-requisites
@@ -160,6 +305,115 @@ end
 
 Note that `gem_hadar` is ["self hosted"](Rakefile)
 
+### Configuration settings in the GemHadar block
+
+#### Core Required Attributes (Mapped to GemSpec)
+
+- **`name`** - Required gem name (raises error if not set)
+- **`version`** - Required version with fallback to `VERSION` file or ENV override
+- **`authors`** - Required author names (mapped from `author`)
+- **`email`** - Required author email (raises error if not set)
+- **`homepage`** - Required homepage URL (raises error if not set). **Validation**: When `developing` is false, validates that the URL returns an HTTP OK status after following redirects.
+- **`summary`** - Required summary description (raises error if not set)
+- **`description`** - Required full description (raises error if not set)
+
+#### Core Recommended Attributes
+
+- **`licenses`** - Default: `Set[]`. License information for the gem
+- **`required_ruby_version`** - Default: `nil`. Ruby version requirement
+
+#### Build and Package Configuration
+
+- **`require_paths`** - Default: `Set['lib']` (mapped to `require_paths`)
+- **`test_dir`** - Default: `nil`
+- **`spec_dir`** - Default: `nil`
+- **`extensions`** - Default: `FileList['ext/**/extconf.rb']` (mapped to `extensions`)
+- **`make`** - Default: `ENV['MAKE']` or system detection
+- **`executables`** - Default: `Set[]` (mapped to `executables`)
+- **`ignore_files`** - Default: `Set[]`
+- **`package_ignore_files`** - Default: `Set[]`
+
+#### Documentation and Files
+
+- **`readme`** - Default: `nil`
+- **`title`** - Default: `nil`
+- **`doc_files`** - Default: `nil`
+- **`yard_dir`** - Default: `nil`
+
+#### Testing Configuration
+
+- **`test_files`** - Default: `nil`
+- **`spec_pattern`** - Default: `nil`
+- **`bindir`** - Default: `nil` (mapped to `bindir`)
+
+#### RVM Configuration (Nested)
+
+```ruby
+rvm do
+  use     # Default: detected ruby version from `rvm tools strings`
+  gemset  # Default: gem name
+end
+```
+
+#### Task Dependencies
+
+- **`default_task_dependencies`** - Default: `[:gemspec, :test]`
+- **`build_task_dependencies`** - Default: `[:clobber, :gemspec, :package, :'version:tag']`
+- **`push_task_dependencies`** - Default: `[:modified, :build, :master:push, :version:push, :gem:push, :github:release]`
+
+#### Configuration Flags
+
+- **`developing`** - Default: `false`. When set to `true`, skips URL validation including homepage link verification for faster development cycles.
+
+### Paths and Module Types
+
+- **`path_name`** - Default: `name`. Returns the raw gem name value by default.
+  It is used for generating file paths and module names. This is particularly
+  useful for creating consistent directory structures and file naming
+  conventions. It's used internally by `GemHadar` to create the root directory
+  for the gem (`lib/my_gem` for name "my\_gem") and generate a `version.rb` file
+  in that location.
+
+  This can be changed for nested namespaces if desired.
+
+  **Example**: For gems in namespaces like `ACME` like
+  `ACME::BrainfuckCompiler`, you might set `path_name` to
+  `"acme/brainfuck_compiler"` to create the directory structure
+  `lib/acme/brainfuck_compiler/`.
+
+- **`path_module`** - Default: `path_name.camelize`. Automatically converts the
+  gem name to CamelCase format (e.g., "my\_gem" becomes "MyGem",
+  "namespace/my\_gem" becomes "Namespace::MyGem") for use in Ruby module and
+  class declarations, ensuring consistency with Ruby naming
+  conventions. This value can be overridden if needed.
+
+- **`module_type`** - Default: `:module`. Determines whether the generated code
+  structure for the version module should be a `:module` or `:class`. This
+  controls the type of Ruby construct created when generating code skeletons and
+  version files. The value
+  can be set to either:
+
+    - `:module` (default) - Generates module-based structure
+    - `:class` - Generates class-based structure
+
+    This is used in the generated `version.rb` file to create either:
+    ```ruby
+    module MyGem
+      # ... version constants
+    end
+    ```
+    or
+    ```ruby
+    class MyGem
+      # ... version constants
+    end
+    ```
+
+These computed values serve as intelligent defaults that can be overridden
+based on your specific requirements. They are automatically derived from other
+DSL accessors and provide powerful convenience features that enable `GemHadar`
+to generate consistent, well-structured Ruby code automatically.
+
 ### Available Tasks
 
 You can list all available tasks with:

data/VERSION

@@ -1 +1 @@
-1.26.0
+1.27.0

data/gem_hadar.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: gem_hadar 1.26.0 ruby lib
+# stub: gem_hadar 1.27.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "gem_hadar".freeze
-  s.version = "1.26.0".freeze
+  s.version = "1.27.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.26".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.27".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.0".freeze])
   s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.0".freeze])
   s.add_runtime_dependency(%q<ollama-ruby>.freeze, ["~> 1.0".freeze])

data/lib/gem_hadar/utils.rb

@@ -1,4 +1,20 @@
+require 'pathname'
+
 module GemHadar::Utils
+  # The xdg_config_home method determines the path to the XDG configuration
+  # directory.
+  #
+  # It first checks if the XDG_CONFIG_HOME environment variable is set and not
+  # empty. If it is set, the method returns the value as a Pathname object. If
+  # XDG_CONFIG_HOME is not set, it defaults to using the HOME environment
+  # variable to construct the path within the standard .config directory.
+  #
+  # @return [ Pathname ] the Pathname object representing the XDG configuration directory
+  def xdg_config_home
+    ENV['XDG_CONFIG_HOME'].full? { Pathname.new(_1) } ||
+      Pathname.new(ENV.fetch('HOME')) + '.config'
+  end
+
   # The xdg_config_filename method constructs the full path to a configuration
   # file based on the XDG Base Directory specification.
   #
@@ -12,11 +28,7 @@ module GemHadar::Utils
   #
   # @return [ String ] the full path to the configuration file
   def xdg_config_filename(name)
-    if xdg = ENV['XDG_CONFIG_HOME'].full?
-      File.join(xdg, name)
-    else
-      File.join(ENV.fetch('HOME'), '.config', name)
-    end
+    xdg_config_home + name
   end
 
   memoize method:

data/lib/gem_hadar/version.rb

@@ -1,6 +1,6 @@
 class GemHadar
   # GemHadar version
-  VERSION         = '1.26.0'
+  VERSION         = '1.27.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/gem_hadar.rb

@@ -1082,12 +1082,79 @@ class GemHadar
     task :yard => %i[ yard:private yard:view ]
   end
 
+  def config_task
+    namespace :gem_hadar do
+      desc "Display current gem_hadar configuration"
+      task :config do
+        puts "=== GemHadar Configuration ==="
+
+        # RubyGems
+        if ENV['GEM_HOST_API_KEY'].present?
+          puts "RubyGems API Key: *** (set)"
+        else
+          puts "RubyGems API Key: Not set"
+        end
+
+        # GitHub
+        if ENV['GITHUB_API_TOKEN'].present?
+          puts "GitHub API Token: *** (set)"
+        else
+          puts "GitHub API Token: Not set"
+        end
+
+        # Ollama
+        puts "Ollama Model: #{ollama_model} (default is #{ollama_model_default})"
+
+        if url = ollama_client&.full?(:base_url)&.to_s
+          puts "Ollama Base URL: #{url.inspect}"
+        else
+          puts "Ollama Base URL: Not set"
+        end
+
+        if ENV['OLLAMA_MODEL_OPTIONS']
+          puts "Ollama Model Options: #{ENV['OLLAMA_MODEL_OPTIONS']}"
+        else
+          puts "Ollama Model Options: Not set (using defaults)"
+        end
+
+        # XDG config home
+        puts "XDG config home: #{xdg_config_home.to_s.inspect}"
+
+        # General
+        puts "Gem Name: #{name}"
+        puts "Version: #{version}"
+
+        # Build/Development
+        puts "MAKE: #{ENV['MAKE'] || 'Not set (will use gmake or make)'}"
+        puts "EDITOR: #{ENV['EDITOR'] || 'Not set (will use vi)'}"
+
+        # Git
+        puts "Git Remote(s): #{ENV['GIT_REMOTE'] || 'origin'}"
+
+        # Other
+        puts "Force Operations: #{ENV['FORCE'] || '0'}"
+        puts "Version Override: #{ENV['VERSION'] || 'Not set'}"
+        puts "GitHub Release Enabled: #{ENV['GITHUB_RELEASE_ENABLED'] || 'Not set'}"
+
+        puts "\n=== AI Prompt Configuration (Default Values) ==="
+        arrow = ?⤵
+        puts bold{"version_bump_system_prompt.txt"} + "#{arrow}\n" + italic{default_version_bump_system_prompt}
+        puts bold{"version_bump_prompt.txt"} + "#{arrow}\n#{default_version_bump_prompt}"
+        puts bold{"release_system_prompt.txt"} + "#{arrow}\n" + italic{default_git_release_system_prompt}
+        puts bold{"release_prompt.txt"} + "#{arrow}\n" + italic{default_git_release_prompt}
+
+        puts "=== End Configuration ==="
+      end
+    end
+  end
+
   # The create_all_tasks method sets up and registers all the Rake tasks for
   # the gem project.
   #
   # @return [GemHadar] the instance of GemHadar
   def create_all_tasks
     default_task
+    config_task
     build_task
     rvm_task
     version_task
@@ -1144,20 +1211,53 @@ class GemHadar
     temp_file&.close&.unlink
   end
 
+  dsl_accessor :ollama_model_default, 'llama3.1'.freeze
+
+  # The ollama_model method retrieves the name of the Ollama AI model to be
+  # used for generating responses.
+  #
+  # It first checks the OLLAMA_MODEL environment variable for a custom model
+  # specification. If the environment variable is not set, it falls back to
+  # using the default model name, which is determined by the
+  # ollama_model_default dsl method.
+  #
+  # @return [ String ] the name of the Ollama AI model to be used
+  def ollama_model
+    ENV.fetch('OLLAMA_MODEL', ollama_model_default)
+  end
+
+  # The ollama_client method creates and returns an Ollama::Client instance
+  # configured with a base URL derived from environment variables.
+  #
+  # It first checks for the OLLAMA_URL environment variable to determine the
+  # base URL. If that is not set, it falls back to using the OLLAMA_HOST
+  # environment variable, defaulting to 'localhost:11434' if that is also not
+  # set. The method then constructs the full base URL and initializes an
+  # Ollama::Client with appropriate timeouts for read and connect operations.
+  #
+  # @return [Ollama::Client, nil] An initialized Ollama::Client instance if a valid base URL is present, otherwise nil.
+  def ollama_client
+    base_url = ENV['OLLAMA_URL']
+    if base_url.blank?
+      host = ENV.fetch('OLLAMA_HOST', 'localhost:11434')
+      base_url = 'http://%s' % host
+    end
+    base_url.present? or return
+    ollama = Ollama::Client.new(base_url:, read_timeout: 600, connect_timeout: 60)
+  end
+
   # Generates a response from an AI model using the Ollama::Client.
   #
   # @param [String] system The system prompt for the AI model.
   # @param [String] prompt The user prompt to generate a response to.
   # @return [String, nil] The generated response or nil if generation fails.
   def ollama_generate(system:, prompt:)
-    base_url = ENV['OLLAMA_URL']
-    if base_url.blank? && host = ENV['OLLAMA_HOST'].full?
-      base_url = 'http://%s' % host
+    unless ollama = ollama_client
+      warn "Ollama is not configured. => Returning."
+      return
     end
-    base_url.present? or return
-    ollama   = Ollama::Client.new(base_url:, read_timeout: 600, connect_timeout: 60)
-    model    = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
-    options  = ENV['OLLAMA_OPTIONS'].full? { |o| JSON.parse(o) } || {}
+    model    = ollama_model
+    options  = ENV['OLLAMA_MODEL_OPTIONS'].full? { |o| JSON.parse(o) } || {}
     options |= { "temperature" => 0, "top_p" => 1, "min_p" => 0.1 }
     ollama.generate(model:, system:, prompt:, options:, stream: false, think: false).response
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem_hadar
 version: !ruby/object:Gem::Version
-  version: 1.26.0
+  version: 1.27.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.26'
+        version: '1.27'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.26'
+        version: '1.27'
 - !ruby/object:Gem::Dependency
   name: tins
   requirement: !ruby/object:Gem::Requirement