xkpassword 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9feced30408ade895b492ff621703dd5d6a1cb6f6d4aaa6fe195534a249cb519
-  data.tar.gz: 8f7bde17464c36aba01028a650daaa3e37d357018e5892bd9331384f25068a6a
+  metadata.gz: a8679b970d4279654ff7aa2f1212267bd2874466af8adfb197d4005dd94fb62a
+  data.tar.gz: 46877ecf578b62ced17e1ba35c8463387c34676d15cf301e8de5188af7619a79
 SHA512:
-  metadata.gz: 158d3daab0101987cb7062a907125d80858aa7dbfdea51c6448ade83d4e155e5af31a87e37715ebde7a1965572008d2f56e64d747e53eb21a9a51e66c948d95b
-  data.tar.gz: cfa02254cb10af01efe5387605d9036750c419031e40bb47cb8a2b23f97c4364ba534f66e3629b3b335dc450fb99d965f5827b654e0e5556d81a2f202eae7664
+  metadata.gz: 512d12534d4a4d0072dfb2581f98c7b9e1464647739b7b508cea5e3fb4e9ab972158d3b4ffa58fafc12f1a904ddc369b308ec33d57a32355b29028e2424d5476
+  data.tar.gz: '0828510166c54f05316e349a0187aee1d9fd49acf19ee4d8fd970309c938e9a0cb2a06390436f32788a87dc2e71a3cbc23aaf31d82dff868340b45dbd3244a38'

data/.gitignore

@@ -3,7 +3,6 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/README.md

@@ -29,7 +29,7 @@ it.
 
 ## Installation
 
-Developed in Linux/Ubuntu, this should work fine in a Linux machine. How ever I can't say
+Developed in Linux/Ubuntu, this should work fine on Linux machines. I cannot say
 the same is true with Mac or Windows systems.
 
 Add this line to your application's Gemfile:
@@ -50,43 +50,90 @@ Or install it yourself as:
 ~# gem install xkpassword
 ```
 
+Installing the gem also installs the `xkpassword` executable.
+
 ## Usage
 
-You can use this app stand-alone in the command line or include it in any of your Ruby
-applications. For a fuller guide to presets and examples, see [doc/README.md](doc/README.md).
+You can use this app as a Ruby gem in your application or as a command line utility.
+For a fuller guide to presets and examples, see [doc/README.md](doc/README.md).
+
+### Command Line
 
-### Comamnd Line
-The commandline application accepts the same collection of configuration options as would
-the `XKPassword` module would. For more information use `xkpassword --help` to obtain a
-full list of options.
+The command line app accepts the same generation options as `XKPassword.generate`.
+If you installed the gem, use the executable directly. If you are working from a
+checkout, run the executable through Bundler.
 
 ```bash
 ~# xkpassword
 ~# xkpassword --help
+~# bundle exec exe/xkpassword
 ```
 
+#### Global CLI config
+
+The CLI reads optional defaults from `~/.xkpassword`. The file uses YAML, so it can
+include comments while you experiment with different settings. Use `xkpassword --init`
+to create a commented starter file.
+
+```bash
+~# xkpassword --init
+~# xkpassword
+~# xkpassword --separator .
+```
+
+```yaml
+# ~/.xkpassword
+# preset: wifi
+words: 5
+min_length: 4
+max_length: 8
+separator: "-"
+# case_transform: capitalize
+```
+
+CLI flags always override values from `~/.xkpassword`, so you can keep preferred defaults
+in the file and still override them per command.
+
 ### Ruby Apps
 
+Use the library API inside your Ruby application:
+
 ```ruby
 require 'xkpassword'
 
 options = {
-  preset: :security,
+  words: 5,
+  min_length: 5,
+  max_length: 8,
+  separator: '.',
+  case_transform: :capitalize,
 }
 
 XKPassword.generate(options)
 ```
 
-If you are generating multiple passwords at once, I recommend you use
-the following as then it will only load and parse the databse once.
+You can still use presets when they fit your use case:
+
+```ruby
+require 'xkpassword'
+
+XKPassword.generate(preset: :security, separator: '.')
+```
+
+If you are generating multiple passwords at once, use a single generator instance so
+the dictionary only needs to be loaded once:
 
 ```ruby
 require 'xkpassword/generator'
 
 options = {
-  preset: :wifi,
+  words: 4,
+  min_length: 4,
+  max_length: 6,
+  separator: '-',
+  case_transform: :downcase,
 }
-  
+
 generator = XKPassword::Generator.new
 generator.generate(options)
 
@@ -116,16 +163,6 @@ a new version, update the version number in `version.rb`, and then run `bundle e
 release`, which will create a git tag for the version, push git commits and tags, and push
 the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## TODO
-
-Some of the things I am interested in doing in the near future.
-
-- More tests, didn't have the time to write it all
-- Local configuration file -> ex: `~/.xkpassword`
-- Check for a better dictionary
-- Ability to provide a dictionary (this should help languages other than English)
-- A black-list - words that will not show up in the generation
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/xkpassword.

data/doc/README.md

@@ -0,0 +1,9 @@
+# XKPassword Docs
+
+Additional documentation for this gem lives in this folder.
+
+- [Preset guide](presets.md)
+- [Project README](../README.md) for installation, Ruby gem usage, CLI usage, and `~/.xkpassword` defaults
+- [GitHub repository](https://github.com/jdeen/xkpassword)
+
+Use these docs for feature-specific details, then jump back to the main README or repository as needed.

data/doc/presets.md

@@ -0,0 +1,37 @@
+# Presets
+
+Back to the [docs index](README.md) or the [project README](../README.md).
+
+`XKPassword.generate` and `XKPassword::Generator#generate` accept a `:preset` option.
+If omitted, `:preset` defaults to `:xkcd`.
+
+## Supported presets
+
+| Preset | Defaults |
+| --- | --- |
+| `:xkcd` | 4 words, 4-8 letters, `-` separator, random per-word uppercasing |
+| `:web32` | 4 words, 4-5 letters, `-` separator, random per-word uppercasing |
+| `:wifi` | 6 words, 4-8 letters, `-` separator, random per-word uppercasing |
+| `:security` | 6 words, 4-8 letters, space separator, lowercase words |
+| `:apple_id` | 3 words, 4-7 letters, `-` separator, random per-word uppercasing |
+
+## Examples
+
+```ruby
+require 'xkpassword'
+
+XKPassword.generate
+XKPassword.generate(preset: :wifi)
+XKPassword.generate(preset: :security, separator: '.')
+```
+
+You can pass a preset as a symbol or string. String values like `"apple_id"` and `"apple-id"`
+are normalized to the matching preset.
+
+Explicit options always win over the preset defaults, so this is valid:
+
+```ruby
+XKPassword.generate(preset: :xkcd, words: 6, case_transform: :capitalize)
+```
+
+For the full source and latest updates, see the [GitHub repository](https://github.com/jdeen/xkpassword).

data/exe/xkpassword

@@ -1,48 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'optparse'
-require 'artii'
+require 'xkpassword/cli'
 
-require 'bundler/setup'
-require 'xkpassword'
-
-artii = Artii::Base.new font: 'standard'
-message = """
-#{ artii.asciify('XKPassword') }
-by Ziyan Junaideen
-
-How many times have you changed your password just because you forgot it?
-Well, you are not alone. In todays security requirements, passwords need
-to be secure and difficult to break. Passwords need to be secure, sure,
-but they can also be easy to remember. Follow up this XKCD article for more
-information - http://xkcd.com/936/
-
-This does exactly what the picture predicts. You can use this in your Ruby 
-applications (Ex: Rails, Sinatra) or standalone if you install the gem (as 
-you have done here).
-
-Wish you all the best keeping things secure.
-
-Ziyan Junaideen
-ziyan@jdeen.com
-
-"""
-
-options = {}
-OptionParser.new do |opts|
-  opts.banner = "Usage: ./exe/xkpassword [options]"
-
-  opts.on('-v', '--version', 'Gem version') { options[:version] = true }
-  opts.on('-i', '--info', 'Gem info') { options[:info] = true }
-
-  opts.on('--words [INTEGER]', 'Number of wrods to be used in the generated password') { |words| options[:words] = words.to_i }
-  opts.on('--min-length [INTEGER]', 'Minimum length of a word') { |min| options[:min_length] = min.to_i }
-  opts.on('--max-length [INTEGER]', 'Maximum length of a word') { |max| options[:max_length] = max.to_i }
-  opts.on('--separator [STRING]', 'The separator to separate password') { |separator| options[:separator] = separator }
-  opts.on('--case-transform [STRING]', 'Transform each word using upcase, downcase, or capitalize') { |case_transform| options[:case_transform] = case_transform }
-  opts.on('--preset [STRING]', 'Preset to use: xkcd, web32, wifi, security, or apple_id') { |preset| options[:preset] = preset }
-end.parse!
-
-puts message if options[:info]
-puts XKPassword::VERSION if options[:version]
-puts XKPassword.generate(options) if !options[:info] && !options[:version]
+exit XKPassword::CLI.new.run

data/lib/xkpassword/cli.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'artii'
+
+require 'xkpassword'
+require 'xkpassword/config_file'
+
+module XKPassword
+  # Command-line entrypoint for the xkpassword executable.
+  class CLI
+    INFO_MESSAGE = <<~TEXT.freeze
+      #{Artii::Base.new(font: 'standard').asciify('XKPassword')}
+      by Ziyan Junaideen
+
+      How many times have you changed your password just because you forgot it?
+      Well, you are not alone. In todays security requirements, passwords need
+      to be secure and difficult to break. Passwords need to be secure, sure,
+      but they can also be easy to remember. Follow up this XKCD article for more
+      information - http://xkcd.com/936/
+
+      This does exactly what the picture predicts. You can use this in your Ruby
+      applications (Ex: Rails, Sinatra) or standalone if you install the gem (as
+      you have done here).
+
+      Wish you all the best keeping things secure.
+
+      Ziyan Junaideen
+      ziyan@jdeen.com
+    TEXT
+
+    def initialize(argv = ARGV, stdout: $stdout, stderr: $stderr, env: ENV)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @config_file = XKPassword::ConfigFile.new(XKPassword::ConfigFile.default_path(env))
+      @options = {}
+    end
+
+    def run
+      option_parser.parse!(@argv)
+
+      return initialize_config if @options[:init]
+      return write_special_output if special_output?
+
+      options = @config_file.load.merge(@options)
+      write_line(XKPassword.generate(options))
+    rescue OptionParser::ParseError, XKPassword::ConfigFile::Error, ArgumentError => e
+      @stderr.puts(e.message)
+      1
+    end
+
+    private
+
+    def option_parser
+      @option_parser ||= OptionParser.new do |opts|
+        opts.banner = 'Usage: xkpassword [options]'
+
+        add_command_options(opts)
+        add_generation_options(opts)
+      end
+    end
+
+    def add_command_options(opts)
+      opts.on('-v', '--version', 'Gem version') { @options[:version] = true }
+      opts.on('-i', '--info', 'Gem info') { @options[:info] = true }
+      opts.on('--init', "Create #{@config_file.path} with commented defaults") { @options[:init] = true }
+      opts.on('-h', '--help', 'Show help') { @options[:help] = true }
+    end
+
+    def add_generation_options(opts)
+      add_numeric_generation_options(opts)
+      add_text_generation_options(opts)
+    end
+
+    def add_numeric_generation_options(opts)
+      opts.on(
+        '--words [INTEGER]',
+        'Number of words to use in the generated password'
+      ) { |words| @options[:words] = words.to_i }
+      opts.on('--min-length [INTEGER]', 'Minimum length of a word') { |min| @options[:min_length] = min.to_i }
+      opts.on('--max-length [INTEGER]', 'Maximum length of a word') { |max| @options[:max_length] = max.to_i }
+    end
+
+    def add_text_generation_options(opts)
+      opts.on(
+        '--separator [STRING]',
+        'The separator between generated words'
+      ) { |separator| @options[:separator] = separator }
+      opts.on(
+        '--case-transform [STRING]',
+        'Transform each word using upcase, downcase, or capitalize'
+      ) { |case_transform| @options[:case_transform] = case_transform }
+      add_preset_option(opts)
+    end
+
+    def add_preset_option(opts)
+      opts.on(
+        '--preset [STRING]',
+        'Preset to use: xkcd, web32, wifi, security, or apple_id'
+      ) { |preset| @options[:preset] = preset }
+    end
+
+    def special_output?
+      @options[:help] || @options[:info] || @options[:version]
+    end
+
+    def write_special_output
+      write_line(option_parser) if @options[:help]
+      write_line(INFO_MESSAGE) if @options[:info]
+      write_line(XKPassword::VERSION) if @options[:version]
+      0
+    end
+
+    def initialize_config
+      path = @config_file.init!
+      write_line("Created #{path}")
+    end
+
+    def write_line(message)
+      @stdout.puts(message)
+      0
+    end
+  end
+end

data/lib/xkpassword/config_file.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'psych'
+
+module XKPassword
+  # Loads and initializes the CLI config file stored at ~/.xkpassword.
+  class ConfigFile
+    Error = Class.new(StandardError)
+
+    ALLOWED_OPTIONS = %i[
+      preset
+      words
+      min_length
+      max_length
+      separator
+      case_transform
+    ].freeze
+    INTEGER_OPTIONS = %i[words min_length max_length].freeze
+    TEMPLATE = <<~YAML
+      # Global defaults for the xkpassword CLI.
+      # Remove the leading "#" from any setting you want to enable.
+      #
+      # Supported keys:
+      #   preset: xkcd, web32, wifi, security, apple_id
+      #   words: integer
+      #   min_length: integer
+      #   max_length: integer
+      #   separator: string
+      #   case_transform: upcase, downcase, capitalize
+      #
+      # Example:
+      # preset: wifi
+      # words: 6
+      # min_length: 4
+      # max_length: 8
+      # separator: "-"
+      # case_transform: capitalize
+    YAML
+
+    attr_reader :path
+
+    def initialize(path = self.class.default_path)
+      @path = path
+    end
+
+    def self.default_path(env = ENV)
+      home = env['HOME'] || Dir.home
+      File.expand_path('.xkpassword', home)
+    end
+
+    def load
+      return {} unless File.exist?(path)
+
+      data = Psych.safe_load(File.read(path), aliases: false)
+      return {} if data.nil?
+      raise Error, "#{path} must contain a YAML mapping of options" unless data.is_a?(Hash)
+
+      normalize_options(data)
+    rescue Psych::SyntaxError => e
+      raise Error, "Could not parse #{path}: #{e.message}"
+    end
+
+    def init!
+      raise Error, "#{path} already exists" if File.exist?(path)
+
+      File.write(path, TEMPLATE)
+      path
+    end
+
+    private
+
+    def normalize_options(data)
+      data.each_with_object({}) do |(key, value), normalized|
+        normalized_key = normalize_key(key)
+
+        unless ALLOWED_OPTIONS.include?(normalized_key)
+          raise Error, "Unsupported config option #{key.inspect} in #{path}"
+        end
+
+        normalized[normalized_key] = normalize_value(normalized_key, value)
+      end
+    end
+
+    def normalize_key(key)
+      key.to_s.strip.downcase.tr(' -', '_').to_sym
+    end
+
+    def normalize_value(key, value)
+      return normalize_integer(key, value) if INTEGER_OPTIONS.include?(key)
+
+      return value if value.nil? || value.is_a?(String) || value.is_a?(Symbol)
+
+      raise Error, "#{key} in #{path} should be a string or left unset"
+    end
+
+    def normalize_integer(key, value)
+      integer_value = value.is_a?(String) ? Integer(value, 10) : value
+      return integer_value if integer_value.is_a?(Integer)
+
+      raise Error, "#{key} in #{path} should be an integer"
+    rescue ArgumentError, TypeError
+      raise Error, "#{key} in #{path} should be an integer"
+    end
+  end
+end

data/lib/xkpassword/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module XKPassword
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xkpassword
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ziyan Junaideen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-12 00:00:00.000000000 Z
+date: 2026-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: artii
@@ -90,8 +90,12 @@ files:
 - bin/console
 - bin/setup
 - bin/xkpassword
+- doc/README.md
+- doc/presets.md
 - exe/xkpassword
 - lib/xkpassword.rb
+- lib/xkpassword/cli.rb
+- lib/xkpassword/config_file.rb
 - lib/xkpassword/data/google-10000-english-no-swears.txt
 - lib/xkpassword/generator.rb
 - lib/xkpassword/store.rb