imapcli 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a446b1918219fb961e61ddce7f63e260a05eefff
+  data.tar.gz: 0d571a1f5c46a1edee07ef7381d10b26c6a1b511
+SHA512:
+  metadata.gz: 82a9caf9891f4814b4965f0c52d9c263d8cc33deab96f506c24918e1c91b2b29ccda53cb7e8d70d1ce873d4f1873c77930a0b20538e78a66773de64ba74e6d4d
+  data.tar.gz: 76850a1c35393bba6997a7fde9bf9ad0075367c40c63cd78e6f3ea6a17b9754fddc140bbeff2e580f10f3580808aac47b8ced4d6f713d84e6629532488bb5515

data/.gitignore

@@ -0,0 +1,4 @@
+*~
+.env
+pkg/
+html/

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+source "https://rubygems.org"
+
+gemspec
+gem 'dotenv'
+gem 'gli'
+gem 'tty-prompt'
+gem 'tty-table'
+gem 'descriptive_statistics'
+gem 'filesize'
+
+group :test do
+  gem 'rspec'
+  gem 'pry'
+  gem 'guard-rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,117 @@
+PATH
+  remote: .
+  specs:
+    imapcli (0.0.1)
+      gli (= 2.17.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.2)
+    descriptive_statistics (2.5.1)
+    diff-lcs (1.3)
+    dotenv (2.2.1)
+    equatable (0.5.0)
+    ffi (1.9.18)
+    filesize (0.1.1)
+    formatador (0.2.5)
+    gli (2.17.0)
+    guard (2.14.1)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    hitimes (1.2.6)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.12)
+    method_source (0.9.0)
+    necromancer (0.4.0)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pastel (0.7.1)
+      equatable (~> 0.5.0)
+      tty-color (~> 0.4.0)
+    pry (0.11.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rake (12.1.0)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rdoc (5.1.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.0)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.0)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    thor (0.20.0)
+    timers (4.1.2)
+      hitimes
+    tty-color (0.4.2)
+    tty-cursor (0.5.0)
+    tty-prompt (0.13.2)
+      necromancer (~> 0.4.0)
+      pastel (~> 0.7.0)
+      timers (~> 4.1.2)
+      tty-cursor (~> 0.5.0)
+      tty-reader (~> 0.1.0)
+    tty-reader (0.1.0)
+      wisper (~> 2.0.0)
+    tty-screen (0.6.2)
+    tty-table (0.9.0)
+      equatable (~> 0.5.0)
+      necromancer (~> 0.4.0)
+      pastel (~> 0.7.0)
+      tty-screen (~> 0.6.0)
+      unicode-display_width (~> 1.1.0)
+      verse (~> 0.5.0)
+    unicode-display_width (1.1.3)
+    unicode_utils (1.4.0)
+    verse (0.5.0)
+      unicode-display_width (~> 1.1.0)
+      unicode_utils (~> 1.4.0)
+    wisper (2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  descriptive_statistics
+  dotenv
+  filesize
+  gli
+  guard-rspec
+  imapcli!
+  pry
+  rake
+  rdoc
+  rspec
+  tty-prompt
+  tty-table
+
+BUNDLED WITH
+   1.16.0

data/Guardfile

@@ -0,0 +1,65 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.call("routing/#{m[1]}_routing"),
+      rspec.spec.call("controllers/#{m[1]}_controller"),
+      rspec.spec.call("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.call("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.call("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end

data/README.md

@@ -0,0 +1,227 @@
+**Heads up! Code contributions welcome. Please issue pull requests against the
+`develop` branch.**
+
+imapcli
+=======
+
+> Command-line interface (CLI) for IMAP servers
+
+`imapcli` is a command-line tool that offers a convenient way to query an IMAP
+server for configuration details and e-mail statistics. It can be used to gather
+IMAP folder sizes.
+
+
+Table of contents
+-----------------
+
+*   [Motivation](#motivation)
+*   [Warning](#warning)
+*   [Installing and executing `imapcli`](#installing-and-executing-imapcli)
+*   [Terminology](#terminology)
+*   [Commands](#commands)
+*   [Alternative resources](#alternative-resources)
+*   [State of the project](#state-of-the-project)
+*   [Credits](#credits)
+*   [License](#license)
+
+
+Motivation
+----------
+
+When my university mail account had almost reached the quota, I needed to find
+out what the largest mail folders were (in terms of megabytes, not message
+count). To my surprise, there was no easy way to accomplish this; or at least I
+did not find one by searching the web. A couple of specialized IMAP-related
+tools exist (see [below](#alternative-resources)), but when it comes to querying
+an IMAP server for configuration and stats, you have to resort to communicating
+with the server by telnet or OpenSSL.
+
+`imapcli` offers a convenient way to query an IMAP server.
+
+
+Warning
+-------
+
+Some servers are configured to detect malicious login attempts by the frequency
+of connections from a given source. **It may happen that you get locked out of
+a server if you use `imapcli` to issue too many queries in too short a time!**
+
+If you happen to be the server administrator yourself, have
+[fail2ban](https://www.fail2ban.org) running, and find your IP being denied
+access to the IMAP port, you can SSH into your server and un-ban your IP like
+this:
+
+    sudo fail2ban-client set dovecot unbanip <your-ip>
+
+If your IMAP server is not [Dovecot](https://www.dovecot.org), you need to change
+this command and provide the appropriate 'jail' name.
+
+To prevent `fail2ban` from blocking your IP, you may want to add a network and
+submask to `jail.local`:
+
+    # /etc/fail2ban/jail.local
+    [DEFAULT]
+    ignoreip = 127.0.0.1/8 123.123.123.0/24 # or whatever your net/mask are
+
+Do not forget to reload the `jail2ban` configuration afterwards:
+
+    sudo service fail2ban reload
+
+(On Ubuntu Linux, the [indicator-ip](https://github.com/bovender/indicator-ip)
+applet may be useful to know your remote IP. Disclaimer: I am the author of this
+tool.)
+
+Installing and executing `imapcli`
+--------------------------------
+
+`imapcli` is a Ruby project and as such does not need to be compiled. You'll
+need Ruby on your system.
+
+
+### Run in the repository
+
+Just clone this repository and run
+
+    bin/imapcli
+
+
+### Gem
+
+To follow.
+
+Run:
+
+    imapcli
+
+
+### .deb installer
+
+To follow.
+
+
+### Docker image
+
+To follow. This will be an option if you don't have Ruby installed.
+
+
+Terminology
+-----------
+
+`imapcli` attempts to use the typical IMAP terminology. I guess most people
+have their mails organized in *folders*; in IMAP speak, a folder is a *maibox*.
+
+
+Commands
+--------
+
+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)
+for more information.
+
+
+### Commands
+
+*   `info`: Prints configuration information about the server.
+*   `examine`: Examines a mailbox (i.e., folder) and returns statistics about it.
+
+
+### Command-line options
+
+*   `-s SERVER`: Set the server domain name (e.g., `imap.example.com`). May be
+    omitted if the information is given in the `IMAP_SERVER` environment variable
+    (see below).
+*   `-u USER`: Set the login (user) name (e.g., `john@example.com`). May be
+    omitted if the information is given in the `IMAP_USER` environment variable
+    (see below).
+*   `-p PASSWORD`: Set the password. May be omitted if the `-P` option is used
+    or if the information is given in the `IMAP_PASS` environment variable (see below).
+*   `-P`: Prompt for the password.
+
+
+### Using environment variables for the server and authentication details
+
+You can set the following environment variables to avoid having to type the
+server information over and over again:
+
+    IMAP_SERVER="imap.example.com"
+    IMAP_USER="your_imap_login"
+    IMAP_PASS="your_imap_password"
+
+If you put this in a file `.env` in the root directory of the repository, this
+information will be used. `.env` is git-ignored, so your credentials won't end up
+in the repository, but of course anyone on your system who has access to this file
+will be able to read the clear-text credentials.
+
+**Also, be aware that a clear-text password that is stored in an environment
+variable can be easily accessed by any other code running under your account.**
+
+For best security, *never* store your clear-text password anywhere. Use the `-P`
+(prompt) global option to have `imapcli` prompt you for the password.
+
+
+Alternative resources
+---------------------
+
+While researching command-line tools for IMAP servers, I came across the
+following:
+
+
+### IMAP folder size script
+
+*   <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>
+
+    Framework to work with mails
+
+*   <https://github.com/polo2ro/imapbox>
+
+    Pull down e-mails from an IMAP server to your local disk
+
+
+
+### IMAP via Telnet or OpenSSL
+
+
+State of the project
+--------------------
+
+Please consider this an alpha version. It does what I needed it for most (collect
+information about the folder sizes), but that's pretty much it. I'll be happy
+to take **pull request**. Please issue those against the **develop** branch as
+I like to follow *[a successful Git branching model](http://nvie.com/git-model)*.
+
+### Versioning
+
+This project is [semantically versioned](https://semver.org).
+
+### To do
+
+-   Man page
+-   .deb installer
+-   More commands?
+
+
+Credits
+-------
+
+This tool is build around the awesome [GLI](https://github.com/davetron5000/gli)
+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.
+
+
+License
+-------
+
+&copy; 2017 Daniel Kraus (bovender)
+
+Apache license.

data/Rakefile

@@ -0,0 +1,45 @@
+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.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'
+# Cucumber::Rake::Task.new(:features) do |t|
+#   opts = "features --format html -o #{CUKE_RESULTS} --format progress -x"
+#   opts += " --tags #{ENV['TAGS']}" if ENV['TAGS']
+#   t.cucumber_opts =  opts
+#   t.fork = false
+# end
+#
+# desc 'Run features tagged as work-in-progress (@wip)'
+# Cucumber::Rake::Task.new('features:wip') do |t|
+#   tag_opts = ' --tags ~@pending'
+#   tag_opts = ' --tags @wip'
+#   t.cucumber_opts = "features --format html -o #{CUKE_RESULTS} --format pretty -x -s#{tag_opts}"
+#   t.fork = false
+# end
+#
+# task :cucumber => :features
+# task 'cucumber:wip' => 'features:wip'
+# task :wip => 'features:wip'
+# require 'rake/testtask'
+# Rake::TestTask.new do |t|
+#   t.libs << "test"
+#   t.test_files = FileList['test/*_test.rb']
+# end
+#
+# task :default => [:test,:features]

data/bin/imapcli

@@ -0,0 +1,131 @@
+#!/usr/bin/env ruby
+require 'gli'
+begin # XXX: Remove this begin/rescue before distributing your app
+require 'imapcli'
+rescue LoadError
+  STDERR.puts "In development, you need to use `bundle exec bin/imapcli` to run your app"
+  STDERR.puts "At install-time, RubyGems will make sure lib, etc. are in the load path"
+  STDERR.puts "Feel free to remove this message from bin/imapcli now"
+  exit 64
+end
+require 'dotenv'
+require 'tty-prompt'
+require 'tty-table'
+# require 'pp'
+
+Dotenv.load
+
+include 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['IMAP_SERVER']
+arg_name 'imap.example.com'
+flag [:s,:server]
+
+desc 'Log-in name (username/email)'
+default_value ENV['IMAP_USER']
+arg_name 'user'
+flag [:u,:user]
+
+desc 'Log-in password'
+# default_value ENV['IMAP_PASS']
+arg_name 'password'
+flag [:p,:password]
+
+desc 'Prompt for password'
+switch [:P, :prompt], negatable: false
+
+desc 'Verbose output (e.g., response values from Ruby''s Net::IMAP)'
+switch [: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: false, multiple: true
+command :examine do |c|
+  c.action do |global_options,options,args|
+    body = @command.stats(args)
+    head = [ 'Mailbox', 'Count', 'Total size', 'Min', 'Q1', 'Median', 'Q3', 'Max' ]
+    table = TTY::Table.new(head, body)
+    @prompt.say table.render(:unicode, alignments: [:left] + Array.new(7, :right) )
+    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
+
+pre do |global,command,options,args|
+  @prompt = TTY::Prompt.new
+
+  if global[:s].nil? || global[:s].empty?
+    raise 'missing server name (use -s option or set IMAP_SERVER environment variable)'
+  end
+  if global[:s].nil? || global[:s].empty?
+    raise 'missing server name (use -s option or set IMAP_SERVER environment variable)'
+  end
+  if global[:P] && global[:p]
+    raise '-p and -P options do not agree'
+  end
+  if global[:P]
+    global[:p] = @prompt.mask 'Enter password:'
+  end
+  global[:p] ||= ENV['IMAP_PASS']
+
+  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 @client
+  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 @client
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
+
+exit run(ARGV)

data/imapcli.gemspec

@@ -0,0 +1,21 @@
+# 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|
+  s.name = 'imapcli'
+  s.version = Imapcli::VERSION
+  s.author = 'Daniel Kraus (bovender)'
+  s.email = 'bovender@bovender.de'
+  s.homepage = 'https://github.com/bovender/imapcli'
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'A description of your project'
+  s.files = `git ls-files`.split("\n")
+  s.require_paths << 'lib'
+  s.has_rdoc = true
+  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')
+  s.add_development_dependency('rdoc')
+  s.add_runtime_dependency('gli','2.17.0')
+end

data/imapcli.rdoc

@@ -0,0 +1,5 @@
+= imapcli
+
+Generate this with
+    imapcli rdoc
+After you have described your command line interface