imapcli 1.0.7 → 2.0.0

data/README.md

@@ -9,15 +9,15 @@ IMAP mailbox sizes.
 
 ## Table of contents
 
-* [Motivation](#motivation)
-* [Warning](#warning)
-* [Installing and executing `imapcli`](#installing-and-executing-imapcli)
-* [Terminology](#terminology)
-* [Usage](#usage)
-* [Alternative resources](#alternative-resources)
-* [State of the project](#state-of-the-project)
-* [Credits](#credits)
-* [License](#license)
+- [Motivation](#motivation)
+- [Warning](#warning)
+- [Installing and executing `imapcli`](#installing-and-executing-imapcli)
+- [Terminology](#terminology)
+- [Usage](#usage)
+- [Alternative resources](#alternative-resources)
+- [State of the project](#state-of-the-project)
+- [Credits](#credits)
+- [License](#license)
 
 ## Motivation
 
@@ -83,7 +83,7 @@ Install:
 Run:
 
     cd imapcli
-    bundle exec bin/imapcli
+    bundle exec exe/imapcli
 
 ### Install the gem
 
@@ -106,11 +106,11 @@ smaller).
 
 Run:
 
-    docker run -it bovender/imapcli <arguments>
+    docker run -it --rm bovender/imapcli <arguments>
 
 Example:
 
-    docker run -it bovender/imapcli -s myserver.example.com -u user -P info
+    docker run -it --rm bovender/imapcli -s myserver.example.com -u user -P info
 
 The Docker repository is at <https://hub.docker.com/r/bovender/imapcli>.
 
@@ -124,7 +124,7 @@ have their mails organized in **folders**; in IMAP speak, a folder is a **maibox
 For basic usage instructions and possible options, run `imapcli` and examine
 the output. Please note that `imapcli` distinguishes between global and
 command-specific options. Global options *precede* and command-specific options
-*follow* a `command`, see the output of `imapcli` (without command or options)
+-follow* a `command`, see the output of `imapcli` (without command or options)
 for more information.
 
 Note: The following examples use the command `imapcli`. Depending on how you
@@ -187,13 +187,15 @@ of messages in them, this may take a little while.
 
 `imapcli` prints the following statistics about the message sizes in a mailbox:
 
-* `Count`: Number of individual messages
-* `Total size`: Total size of all messages in the mailbox (in kiB)
-* `Min`: Size of the smallest message in the mailbox (in kiB)
-* `Q1`: First quartile of message sizes in the mailbox (in kiB)
-* `Median`: Median of all message sizes in the mailbox (in kiB)
-* `Q3`: First quartile of message sizes in the mailbox (in kiB)
-* `Max`: Size of the largest message in the mailbox (in kiB)
+- `Count`: Number of individual messages
+- `Total size`: Total size of all messages in the mailbox
+- `Min`: Size of the smallest message in the mailbox
+- `Q1`: First quartile of message sizes in the mailbox
+- `Median`: Median of all message sizes in the mailbox
+- `Q3`: Third quartile of message sizes in the mailbox
+- `Max`: Size of the largest message in the mailbox
+
+Use the `-H` or `--human` switch to output the message sizes with SI prefixes.
 
 #### All mailboxes
 
@@ -245,13 +247,20 @@ Use the `-r`/`--recurse` flag:
 By default, mailboxes are sorted alphabetically. To sort by a specific statistic,
 use an `-o`/`--sort` option:
 
-* `-o count`
-* `-o total_size`
-* `-o min_size`
-* `-o q1`
-* `-o median_size`
-* `-o q3`
-* `-o max_size`
+- `-o count`
+- `-o total_size`
+- `-o min_size`
+- `-o q1_size`
+- `-o median_size`
+- `-o q3_size`
+- `-o max_size`
+
+This will sort the output from smallest to largest (ascending).
+
+Use the `--reverse` switch to sort from largest to smallest (descending).
+
+Note that these are options to the `stats` command and need to come after the `stats`
+keyword, as shown below.
 
 Example:
 
@@ -268,18 +277,18 @@ following:
 
 ### IMAP folder size script
 
-* <https://code.iamcal.com/pl/imap_folders>
+- <https://code.iamcal.com/pl/imap_folders>
 
   Ad-hoc perl script that computes the sizes of each mailbox. `imapcli` was
   inspired by this!
 
 ### IMAP synchronization and backup tools
 
-* <https://github.com/OfflineIMAP/imapfw>
+- <https://github.com/OfflineIMAP/imapfw>
 
   Framework to work with mails
 
-* <https://github.com/polo2ro/imapbox>
+- <https://github.com/polo2ro/imapbox>
 
   Pull down e-mails from an IMAP server to your local disk
 
@@ -288,18 +297,15 @@ following:
 I have not been able to work on this project for quite some time. It still
 serves me well when I occasionally need it. Pull requests are of course welcome.
 
-I've decided to have one `main` branch, and to get rid of the `master` and
-`
-
 This project is [semantically versioned](https://semver.org).
 
 ### To do
 
-* More human-friendly number formatting (e.g., MiB/GiB as appropriate)
-* Output to file
-* Deal with server-specific mailbox separator characters (e.g. '.' vs. '/')
-* Man page
-* More commands?
+[x] More human-friendly number formatting (e.g., MiB/GiB as appropriate)
+[ ] Output to file
+[ ] Deal with server-specific mailbox separator characters (e.g. '.' vs. '/')
+[ ] Man page
+[ ] More commands?
 
 ## Credits
 
@@ -308,9 +314,14 @@ gem by [David Copeland](https://github.com/davetron5000) and makes extensive use
 of [Piotr Murach's](https://github.com/piotrmurach) excellent `TTY` tools. See
 the `Gemfile` for other work that this tool depends on.
 
+## Contributors
+
+- [@bovender](https://github.com/bovender)
+- [@n-rodriguez](https://github.com/n-rodriguez)
+
 ## License
 
-&copy; 2017, 2022 Daniel Kraus (bovender)
+&copy; 2017-2025 Daniel Kraus (@bovender)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/Rakefile

@@ -1,20 +1,18 @@
+# frozen_string_literal: true
+
 require 'rake/clean'
 require 'rubygems'
 require 'rubygems/package_task'
 require 'rdoc/task'
 # require 'cucumber'
 # require 'cucumber/rake/task'
+
 Rake::RDocTask.new do |rd|
-  rd.main = "README.md"
-  rd.rdoc_files.include("README.md","lib/**/*.rb","bin/**/*")
+  rd.main = 'README.md'
+  rd.rdoc_files.include('README.md', 'lib/**/*.rb', 'bin/**/*')
   rd.title = 'imapcli'
 end
 
-spec = eval(File.read('imapcli.gemspec'))
-
-Gem::PackageTask.new(spec) do |pkg|
-end
-
 # CUKE_RESULTS = 'results.html'
 # CLEAN << CUKE_RESULTS
 # desc 'Run features'

data/bin/bundle

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+  module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a.match?(Gem::Version::ANCHORED_VERSION_PATTERN)
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../Gemfile", __dir__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, ".locked")
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_requirement
+    @bundler_requirement ||=
+      env_var_version ||
+      cli_arg_version ||
+      bundler_requirement_for(lockfile_version)
+  end
+
+  def bundler_requirement_for(version)
+    return "#{Gem::Requirement.default}.a" unless version
+
+    bundler_gem_version = Gem::Version.new(version)
+
+    bundler_gem_version.approximate_recommendation
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    activate_bundler
+  end
+
+  def activate_bundler
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_requirement
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_requirement).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_requirement}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_requirement}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/rubocop

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/exe/imapcli

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/imapcli'
+
+Dotenv.load
+
+exit Imapcli::Cli.run(ARGV)

data/imapcli.gemspec

@@ -1,27 +1,35 @@
-# Ensure we require the local version and not one we might have installed already
-require File.join([File.dirname(__FILE__),'lib','imapcli','version.rb'])
-spec = Gem::Specification.new do |s|
+# frozen_string_literal: true
+
+require_relative 'lib/imapcli/version'
+
+Gem::Specification.new do |s|
   s.name = 'imapcli'
   s.version = Imapcli::VERSION
+  s.platform = Gem::Platform::RUBY
   s.author = 'Daniel Kraus (bovender)'
   s.email = 'bovender@bovender.de'
   s.homepage = 'https://github.com/bovender/imapcli'
-  s.license = 'Apache-2.0'
-  s.platform = Gem::Platform::RUBY
   s.summary = 'Command-line tool to query IMAP servers'
+  s.license = 'Apache-2.0'
+
+  s.required_ruby_version = '>= 3.1.0'
+
   s.files = `git ls-files`.split("\n")
-  s.require_paths << 'lib'
-  s.extra_rdoc_files = ['README.md','imapcli.rdoc']
+
+  s.extra_rdoc_files = ['README.md', 'imapcli.rdoc']
   s.rdoc_options << '--title' << 'imapcli' << '--main' << 'README.md' << '-ri'
-  s.bindir = 'bin'
-  s.executables << 'imapcli'
-  s.add_development_dependency('rake', '~> 12.3.3')
-  s.add_development_dependency('rdoc', '~> 6.3')
-  s.add_runtime_dependency('descriptive_statistics', '~> 2.5')
-  s.add_runtime_dependency('dotenv', '~> 2.2')
-  s.add_runtime_dependency('filesize', '~> 0.1')
-  s.add_runtime_dependency('gli','~> 2.17')
-  s.add_runtime_dependency('tty-progressbar', '~> 0.13')
-  s.add_runtime_dependency('tty-prompt', '~> 0.13')
-  s.add_runtime_dependency('tty-table', '~> 0.9')
+
+  s.bindir = 'exe'
+  s.executables = ['imapcli']
+
+  s.add_dependency('csv')
+  s.add_dependency('descriptive_statistics', '~> 2.5')
+  s.add_dependency('dotenv', '~> 3.1')
+  s.add_dependency('activesupport', '~> 8.0')
+  s.add_dependency('gli', '~> 2.22')
+  s.add_dependency('net-imap')
+  s.add_dependency('tty-progressbar', '~> 0.18')
+  s.add_dependency('tty-prompt', '~> 0.23')
+  s.add_dependency('tty-table', '~> 0.12')
+  s.add_dependency('zeitwerk', '~> 2.7.0')
 end

data/lib/imapcli/cli.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Imapcli
+  class Cli # rubocop:disable Metrics/ClassLength,Style/Documentation
+    extend GLI::App
+
+    program_desc 'Command-line interface for IMAP servers'
+
+    version Imapcli::VERSION
+
+    subcommand_option_handling :normal
+    arguments :strict
+    sort_help :manually
+    wrap_help_text :tty_only
+
+    desc 'Domain name (FQDN) of the IMAP server'
+    default_value ENV.fetch('IMAP_SERVER', nil)
+    arg_name 'imap.example.com'
+    flag %i[s server]
+
+    desc 'Log-in name (username/email)'
+    default_value ENV.fetch('IMAP_USER', nil)
+    arg_name 'user'
+    flag %i[u user]
+
+    desc 'Log-in password'
+    # default_value ENV['IMAP_PASS']
+    arg_name 'password'
+    flag %i[p password]
+
+    desc 'Prompt for password'
+    switch %i[P prompt], negatable: false
+
+    desc 'Verbose output (e.g., response values from Rubys Net::IMAP)'
+    switch %i[v verbose], negatable: false
+
+    desc 'Tests if the server is available and log-in succeeds with the credentials'
+    command :check do |c|
+      c.action do |_global_options, _options, _args|
+        @command.check ? @prompt.ok('login successful') : @prompt.error('login failed')
+      end
+    end
+
+    desc 'Prints information about the server'
+    command :info do |c|
+      c.action do |_global_options, _options, _args|
+        @command.info.each { |line| @prompt.say line }
+      end
+    end
+
+    desc 'Lists mailboxes (folders)'
+    command :list do |c|
+      c.action do |_global_options, _options, _args|
+        @command.list.each { |line| @prompt.say line }
+      end
+    end
+
+    desc 'Collects mailbox statistics'
+    arg_name :mailbox, optional: true, multiple: true
+    command :stats do |c| # rubocop:disable Metrics/BlockLength
+      c.switch %i[r recurse],
+        desc: 'Recurse into sub mailboxes',
+        negatable: false
+      c.switch %i[R no_recurse],
+        desc: 'Do not recurse into sub mailboxes',
+        negatable: false
+      c.switch %i[H human],
+        desc: 'Convert byte counts to human-friendly formats',
+        negatable: false
+      c.flag %i[o sort],
+        desc: 'Ordered (sorted) results',
+        arg_name: 'sort_property',
+        must_match: %w[count total_size median_size min_size q1_size q3_size max_size],
+        default: 'total_size'
+      c.switch %i[reverse], desc: 'Reverse sort order (largest first)', negatable: false
+      c.switch [:csv], desc: 'Output comma-separated values (CSV)'
+
+      c.action do |_global_options, options, args| # rubocop:disable Metrics/BlockLength
+        raise unless @validator.stats_options_valid?(options, args)
+
+        progress_bar = nil
+
+        head = ['Mailbox', 'Count', 'Total size', 'Min', 'Q1', 'Median', 'Q3', 'Max']
+        body = @command.stats(args, options) do |n|
+          if progress_bar
+            progress_bar.advance
+          else
+            @prompt.say "info: collecting stats for #{n} folders" if n > 1
+            progress_bar = TTY::ProgressBar.new(
+              'collecting stats... :current/:total (:percent, :eta remaining)',
+              total: n, clear: true
+            )
+          end
+        end
+        formatted_body = body.map do |row|
+          row[0..1] + row[2..].map { |cell| format_bytes(cell, options[:human]) }
+        end
+
+        if options[:csv]
+          unless options[:human]
+            @prompt.warn 'notice: BREAKING CHANGE IN VERSION 2: messages sizes in CSV output are now given in bytes, not kiB'
+          end
+          @prompt.say head.to_csv
+          last_mailbox_line = body.length == 1 ? -1 : -2 # skip grand total if present
+          formatted_body[0..last_mailbox_line].each { |row| @prompt.say row.to_csv }
+        else
+          formatted_body = formatted_body.insert(0, :separator).insert(-2, :separator)
+
+          if options[:human]
+            @prompt.say "notice: -H/--human flag present, message sizes are given with SI prefixes"
+          else
+            @prompt.say "notice: message sizes are given in bytes"
+          end
+
+          table = TTY::Table.new(head, formatted_body)
+          rendered_table = table.render(:unicode) do |renderer|
+            renderer.alignments =  [:left] + Array.new(7, :right)
+            renderer.border.style = :blue
+          end
+          @prompt.say rendered_table
+
+          # If any unknown mailboxes were requested, print an informative footer
+          if body.any? { |line| line[0].start_with? Imapcli::Command.unknown_mailbox_prefix }
+            @prompt.warn "#{Imapcli::Command.unknown_mailbox_prefix}unknown mailbox"
+          end
+        end
+      end
+    end
+
+    def self.format_bytes(bytes, human = false)
+      human ? ActiveSupport::NumberHelper.number_to_human_size(bytes) : bytes
+    end
+
+    pre do |global, _command, _options, _args|
+      @prompt = TTY::Prompt.new
+      @validator = Imapcli::OptionValidator.new
+      raise unless @validator.global_options_valid?(global)
+
+      global[:p] = @prompt.mask 'Enter password:' if global[:P]
+      global[:p] ||= ENV.fetch('IMAP_PASS', nil)
+
+      client = Imapcli::Client.new(global[:s], global[:u], global[:p])
+      @prompt.say "server: #{global[:s]}"
+      @prompt.say "user: #{global[:u]}"
+      raise 'invalid server name' unless client.server_valid?
+      raise 'invalid user name' unless client.user_valid?
+
+      @prompt.warn 'warning: no password was provided (missing -p/-P option)' unless global[:p]
+      raise 'unable to connect to server' unless client.connection
+
+      @command = Imapcli::Command.new(client)
+
+      true
+    end
+
+    post do |global, _command, _options, _args|
+      @client&.logout
+      if global[:v]
+        @prompt.say "\n>>> --verbose switch on, listing server responses <<<"
+        @client.responses.each do |response|
+          @prompt.say response
+        end
+      end
+    end
+
+    on_error do |exception|
+      @client&.logout
+      if @validator&.errors&.any?
+        @validator.errors.each { |error| @prompt.error error }
+      else
+        @prompt&.error "error: #{exception}"
+      end
+      @prompt.nil? # if we do not have a prompt yet, let GLI handle the exception
+    end
+
+    def print_warnings
+      @validator.warnings.each { |warning| @prompt.warn warning }
+    end
+  end
+end