kood 0.0.1

data/lib/kood/card.rb

@@ -0,0 +1,128 @@
+require 'active_support/core_ext'
+require 'toystore'
+
+module Kood
+  class Card
+    include Toy::Store
+
+    # References
+    reference :list, List
+
+    # Attributes
+    attribute :title,        String
+    attribute :content,      String
+    attribute :participants, Array
+    attribute :labels,       Array
+    attribute :position,     Integer
+    attribute :date,         Time, default: lambda { Time.now }
+    attribute :more,         Hash # to store additional user-defined properties
+
+    def self.get!(id)
+      super rescue raise NotFound, "The specified card does not exist."
+    end
+
+    def self.find_all_by_partial_attribute(attrs, search_param, options = {})
+      cards = options.key?(:list) ? options[:list].cards : Board.current!.cards
+
+      attrs.split('_or_').map do |a|
+        cards.select do |c|
+          # `search_param` may be a normal string or a string representing a regular expression
+          c[a].match /#{ search_param }/i or c[a].downcase.include?(search_param.downcase)
+        end
+      end.flatten
+    end
+
+    # If the `unique` option is present, an exception must be raised if:
+    # - More than one exact match was found
+    # - Zero exact matches were found but more than one partial match was found
+    # If `unique` not present, return the first match giving preference to exact matches
+    #
+    def self.find_by_partial_attribute!(attrs, search_param, options = {})
+      must_unique = options[:unique] == true
+
+      # Find partial (and exact) matches
+      matches = find_all_by_partial_attribute(attrs, search_param, options)
+
+      # If nothing was found, raise an exception
+      raise NotFound, "The specified card does not exist." if matches.empty?
+
+      # Refine the search and retrieve only exact matches
+      exact_matches = attrs.split('_or_').map do |a|
+        matches.select { |c| c[a].casecmp(search_param).zero? }
+      end.flatten
+
+      if (must_unique and exact_matches.length == 1) or (!must_unique and !exact_matches.empty?)
+        exact_matches.first
+      elsif matches.length > 1 and must_unique
+        raise MultipleDocumentsFound, "Multiple cards match the given criteria."
+      else
+        matches.first
+      end
+    end
+
+    # FIXME With humanize "foo_id" becomes "Foo" instead of "Foo Id" which may be confusing
+    def pretty_attributes(to_print = [ 'labels', 'participants', 'more' ])
+      attrs = self.attributes.dup
+      attrs.delete_if { |k, v| v.blank? or k.eql? 'more' or not to_print.include? k }
+      attrs.merge! self.more
+      max_size = attrs.keys.max_by { |k| k.humanize.size }.humanize.size unless attrs.empty?
+
+      attrs.map do |key, value|
+        case value
+        when Array
+          "#{ (key.humanize + ":").ljust(max_size + 2) } #{ value.join(', ') }"
+        else
+          "#{ (key.humanize + ":").ljust(max_size + 2) } #{ value }"
+        end
+      end.compact.join("\n")
+    end
+
+    def edit_file
+      board = Board.current!
+      changed = false
+
+      adapter.client.with_stash_and_branch(board.id) do
+        Dir.chdir(board.root) do
+          yield filepath if block_given?
+        end
+
+        data = File.read(File.join(board.root, filepath))
+        self.attributes = Card.adapter.decode(data)
+        changed = self.changed?
+
+        save! if changed
+        adapter.client.git.reset(hard: true)
+      end
+      changed
+    end
+
+    private
+
+    def self.method_missing(meth, *args, &block)
+      if meth.to_s =~ /^find_all_by_partial_(.+)$/
+        find_all_by_partial_attribute($1, *args)
+      elsif meth.to_s =~ /^find_by_partial_(.+)!$/
+        find_by_partial_attribute!($1, *args)
+      else
+        super
+      end
+    end
+
+    # ToyStore supports adapters per model but this program needs an adapter per instance
+    def self.with_adapter(branch, root)
+      current_client = adapter.client
+      current_options = adapter.options
+
+      adapter :git, Kood.repo(root), branch: branch, path: 'cards'
+      adapter.file_extension = 'md'
+      yield
+    ensure
+      adapter :git, current_client, current_options
+      adapter.file_extension = 'md'
+    end
+
+    def filepath
+      File.join('cards', id) + ".#{ adapter.file_extension }"
+    end
+  end
+end

data/lib/kood/cli.rb

@@ -0,0 +1,121 @@
+require 'thor'
+require 'thor/group'
+
+require_relative 'cli/helpers/table'
+require_relative 'cli/board'
+require_relative 'cli/switch'
+require_relative 'cli/list'
+require_relative 'cli/card'
+require_relative 'cli/edit'
+require_relative 'cli/plugin'
+
+class Kood::CLI < Thor
+  namespace :kood
+
+  class_option 'debug', :desc => "Run Kood in debug mode", :type => :boolean
+  class_option 'color', :desc => "Colorization in output", :type => :boolean,
+    :default => Kood::Shell.color_support?
+
+  check_unknown_options!
+
+  # Thor help is not used for subcommands. Docs for each subcommand are written in the
+  # man files.
+  #
+  # If the `default` key of `method_option` is a method, it will be executed each time
+  # this program is called. As an alternative, a default value is specified inside each
+  # method. So for example instead of:
+  #
+  #     method_option ... :default => foo()
+  #     def bar(arg)
+  #       ...
+  #     end
+  #
+  # The following is done:
+  #
+  #     method_option ...
+  #     def bar(arg)
+  #       arg = foo() if arg.nil?
+  #     end
+
+  # Invoked with `kood --help`, `kood help`, `kood help <cmd>` and `kood --help <cmd>`
+  def help(cli = nil)
+    case cli
+      when nil then command = "kood"
+      when "boards" then command = "kood-board"
+      when "select" then command = "kood-switch"
+      when "lists"  then command = "kood-list"
+      when "cards"  then command = "kood-card"
+      else command = "kood-#{cli}"
+    end
+
+    manpages = %w(
+      kood-board
+      kood-switch
+      kood-list
+      kood-card)
+
+    if manpages.include? command # Present a man page for the command
+      root = File.expand_path("../../../man", __FILE__)
+      exec "man #{ root }/#{ command }.1"
+    else
+      super # Use thor to output help
+    end
+  end
+
+  desc "version", "Print kood's version information"
+  map ['--version', '-v'] => :version
+  def version
+    puts "kood version #{ Kood::VERSION }"
+  end
+
+  private
+
+  # Reimplement the `start` method in order to catch raised exceptions
+  # For example, when running `kood c`, Thor will raise "Ambiguous task c matches ..."
+  # FIXME Should not be necessary, since Thor catches exceptions when not in debug mode
+  def self.start(given_args=ARGV, config={})
+    Grit.debug = given_args.include?('--debug')
+    super
+  rescue Exception => e
+    if given_args.include? '--debug'
+      puts e.inspect
+      puts e.backtrace
+    elsif given_args.include? '--no-color'
+      puts e
+    else
+      puts "\e[31m#{ e }\e[0m"
+    end
+  end
+
+  def no_method_options?
+    (options.keys - self.class.class_options.keys).empty?
+  end
+
+  def ok(text)
+    # An idea from [git.io/logbook](//git.io/logbook). You should check it out.
+    if options.color?
+      say text, :green
+    else
+      puts text
+    end
+  end
+
+  def error(text)
+    if options.color?
+      say text, :red
+    else
+      puts text
+    end
+  end
+end
+
+# Third-party commands (plugins)
+#
+Kood::CLI.load_plugins
+
+# Warn users that non-ascii characters in the arguments may cause errors
+#
+if ARGV.any? { |arg| not arg.ascii_only? }
+  puts "For now, please avoid non-ascii characters. We're still working on providing" \
+    " full support for utf-8 encoding."
+end

data/lib/kood/cli/board.rb

@@ -0,0 +1,139 @@
+class Kood::CLI < Thor
+
+  desc "board [OPTIONS] [<BOARD-ID>]", "Display and manage boards"
+  #
+  # Delete a board. If <board-id> is present, the specified board will be deleted.
+  # With no arguments, the current board will be deleted.
+  method_option :delete, :aliases => '-d', :type => :boolean
+  #
+  # Copy a board. <board-id> will be copied to <new-board-id>.
+  # <board-id> will be kept intact and a new one is created with the exact same data.
+  method_option :copy, :aliases => '-c', :type => :string
+  #
+  # Create a board in an external repository.
+  method_option :repo, :aliases => '-r', :type => :string
+  def board(board_id = nil)
+    # If no arguments and options are present, the command displays all existing boards
+    if board_id.nil? and no_method_options?
+      list_existing_boards
+
+    # If the <board-id> argument is present without options, a new board will be created
+    elsif no_method_options? or options.repo.present?
+      create_board(board_id)
+
+    else # Since <board-id> is present, operate on the specified board
+      operate_on_board(board_id)
+    end
+  end
+  map 'boards' => 'board'
+
+  private
+
+  def operate_on_board(board_id)
+    board = get_board_or_current!(board_id) # Raises exception if inexistent
+
+    copy_board(board)      if options.copy.present?
+    delete_board(board_id) if options.key? 'delete'
+  end
+
+  def list_existing_boards
+    return error "No boards were found." if Kood.config.boards.empty?
+
+    max_board_id = Kood.config.boards.max_by { |b| b.id.size }.id.size
+    Kood.config.boards.each do |b|
+      marker     = b.is_current? ? "* " : "  "
+      visibility = b.published?  ? "shared" : "private"
+      repo_path  = b.root.gsub(/^#{ ENV['HOME'] }/, "~") if b.external?
+      visibility = "(#{ visibility }#{ ' at '+ repo_path if b.external? })"
+      visibility = set_color(visibility, :black, :bold) if options.color?
+      puts marker + b.id.to_s.ljust(max_board_id + 2) + visibility
+    end
+  end
+
+  def create_board(board_id)
+    board = Kood.config.boards.create(id: board_id, custom_repo: options['repo'])
+
+    unless board.persisted?
+      msgs = board.errors.full_messages.join("\n")
+      return error "#{ msgs.gsub('Id', 'Board ID') }."
+    end
+
+    if Kood.config.boards.size == 1
+      board.select
+      ok "Board created and selected."
+    else
+      ok "Board created."
+    end
+  end
+
+  def copy_board(board)
+  end
+
+  def delete_board(board_id)
+    Kood.config.boards.destroy(board_id)
+    ok "Board deleted."
+  end
+
+  def get_board_or_current!(board_id)
+    board_id.nil? ? Kood::Board.current! : Kood::Board.get!(board_id)
+  end
+
+  def print_board(board)
+    opts = options.color? ? { color: [:black, :bold] } : {}
+    num_lists = board.list_ids.size
+    header = Kood::Table.new(num_lists)
+    body   = Kood::Table.new(num_lists)
+
+    board.lists.each do |list|
+      # Setup the header of the table
+      header.new_column.add_row(list.id, align: 'center', separator: false)
+
+      # Setup the body of the table
+      column = body.new_column
+      list.cards.each do |card|
+        card_info = card.title
+        if options.color?
+          colored_separator = color_separator_with_labels(column.separator, card.labels)
+          column.add_row(colored_separator, slice: false)
+        else
+          labels = card.labels.uniq.map { |l| "##{ l }" }.join(", ")
+          card_info += " #{ labels }" unless labels.blank?
+          column.add_row(column.separator, separator: false)
+        end
+        column.add_row(card_info, separator: false)
+        column.add_row(card.id.slice(0, 8), opts.merge(separator: false))
+      end
+      column.add_row(column.separator, slice: false)
+    end
+
+    # Setup the title of the table
+    title = Kood::Table.new(1, body.width)
+    title.new_column.add_row(board.id, align: 'center')
+
+    out = [ title.to_s(separator: false) ]
+    out << header.separator('first') << header
+    out << body unless body.to_s.empty?
+    out << body.separator('last')
+
+    # `join` is used to prevent partial content from being printed if an exception occurs
+    puts out.join("\n")
+  end
+
+  def color_separator_with_labels(separator, labels)
+    return separator if labels.blank? or not options.color?
+
+    hbar = Kood::Shell.horizontal_bar
+    colored_bars = labels.map { |l| set_color(hbar * 3, label_to_color(l)) }.uniq
+
+    if colored_bars.length * 3 > separator.length
+      colored_bars = colored_bars[0...separator.length/3-1]
+      colored_bars << set_color(hbar * 3, :black, :bold)
+    end
+
+    separator[0...-colored_bars.length*3] + colored_bars.join
+  end
+
+  def label_to_color(label)
+    (Kood.config.labels[label] || 'blue').to_sym
+  end
+end

data/lib/kood/cli/card.rb

@@ -0,0 +1,188 @@
+require 'active_support/core_ext/hash/except'
+
+class Kood::CLI < Thor
+
+  desc "card [OPTIONS] [<CARD-ID|CARD-TITLE>]", "Display and manage cards"
+  #
+  # Delete a card. If <card-title> is present, the specified card will be deleted.
+  method_option :delete, :aliases => '-d', :type => :boolean
+  #
+  # Copy a card. <card-title> will be copied to a new card in the given list.
+  # <card-title> will be kept intact and a new one is created with the exact same data.
+  method_option :copy, :aliases => '-c', :type => :string
+  #
+  # Show status information of the current board associated with the given user.
+  method_option :participant, :aliases => '-p', :type => :string
+  #
+  # Does the card action in the given list.
+  method_option :list, :aliases => '-l', :type => :string
+  #
+  # Launches the configured editor to modify the card
+  method_option :edit, :aliases => '-e', :type => :boolean
+  #
+  # Set and unset properties (add and remove are useful for properties that are arrays)
+  method_option :set,    :aliases => '-s', :type => :hash
+  method_option :unset,  :aliases => '-u', :type => :array
+  method_option :add,    :aliases => '-a', :type => :array
+  method_option :remove, :aliases => '-r', :type => :array
+  def card(card_id_or_title = nil)
+    Kood::Board.current!.with_context do |current_board|
+      card_title = card_id = card_id_or_title
+
+      # If no arguments and options are specified, display all existing cards
+      if card_title.nil? and no_method_options?
+        return error "No lists were found." if current_board.lists.empty?
+        print_board(current_board)
+
+      # If <card-title> is present without options, display the card with given ID or title
+      elsif card_id_or_title and no_method_options?
+        card = Kood::Card.find_by_partial_id_or_title!(card_id_or_title)
+        print_card(current_board, card)
+
+      else # If <card-title> and the `list` option are present, a new card is created
+        create_card(card_id_or_title) if card_id_or_title and options.list.present?
+
+        # Since <card-title> is present, operate on the specified card
+        operate_on_card(current_board, card_id)
+      end
+    end
+  end
+  map 'cards' => 'card'
+
+  private
+
+  def operate_on_card(current_board, card_id_or_title, card_id = card_id_or_title)
+    card = Kood::Card.find_by_partial_id_or_title!(card_id_or_title)
+
+    copy_card(card)       if options.copy.present?
+    delete_card(card_id)  if options.key? 'delete'
+    return edit(card_id)  if options.edit.present? # Execute the `edit` task
+
+    if options.any? { |k,v| %w{ set unset add remove }.include? k }
+      set_card_attributes(card)    if options.set.present?
+      unset_card_attributes(card)  if options.unset.present?
+      insert_into_card_array_attribute(current_board, card)  if options.add.present?
+      remove_from_card_array_attribute(current_board, card)  if options.remove.present?
+
+      if card.changed?
+        card.save!
+        ok "Card updated."
+      else
+        error "No changes to persist."
+      end
+    end
+  end
+
+  def create_card(card_title)
+    list = Kood::List.get! options.list
+    list.cards.create(title: card_title, list: list)
+    ok "Card created."
+  end
+
+  def copy_card(card) # TODO Support card copy between boards
+    list = options.copy.eql?('copy') ? card.list : Kood::List.get!(options.copy)
+    list.cards.create(card.dup.attributes.except 'date', list: list)
+    ok "Card copied."
+  end
+
+  def delete_card(card_id_or_title)
+    card = Kood::Card.find_by_partial_id_or_title!(card_id_or_title, unique: true)
+    list = card.list
+    list.cards.destroy(card.id)
+    ok "Card deleted."
+  end
+
+  # Iterates over all pairs of `options.set` and:
+  # - If a key is an attribute of card, sets its value
+  # - If a key is not an attribute of card, set it in the `more` hash, which is used to
+  #   store custom attributes defined by the user
+  #
+  # Example: kood card lorem --set title:lorem description:"lorem ipsum" foo:bar
+  #
+  def set_card_attributes(card)
+    options.set.each do |key, value|
+      value = Kood::Shell.type_cast(value) # Convert to float or int if possible
+
+      if Kood::Card.attribute? key and not %w{ list list_id more }.include? key.to_s
+        card[key] = value
+      else
+        card.more ||= {}
+        card.more = card.more.merge(key => value) # Has to be "card.more=" to be consi-
+      end                                         # dered changed (merge! wouldn't work)
+    end
+  end
+
+  # It operates in the same way of the `set_card_attributes` method but iterates over
+  # the `options.unset` array, instead of an hash
+  #
+  # Example: kood card lorem --unset title description labels
+  #
+  def unset_card_attributes(card)
+    options.unset.each do |key|
+      if Kood::Card.attribute? key and not %w{ title list list_id more }.include? key
+        card[key] = nil
+      else
+        card.more ||= {}
+        card.more = card.more.except(key) # Has to be "card.more=" to be considered changed
+      end
+    end
+  end
+
+  def update_card_array_attribute(current_board, card, opt)
+    values = opt.eql?(:+) ? options.add : options.remove
+    key = values.shift
+
+    if key.eql? 'participants'
+      board_members = values.map do |v|
+        current_board.find_potential_member_by_partial_name_or_email(v) || v
+      end
+      # Since this command may be called by other users with distinct boards, the found
+      # board members may be different, so always keep the typed values if this is about
+      # removing participants
+      values = opt.eql?(:+) ? board_members : (values + board_members)
+    end
+
+    if Kood::Card.attribute? key and Kood::Card.attributes[key].type.eql? Array
+      card[key] ||= []
+      card[key] = opt.eql?(:+) ? (card[key] + values) : (card[key] - values)
+    else
+      begin
+        card.more ||= {}
+        card.more[key] ||= []
+        new_value = opt.eql?(:+) ? (card.more[key] + values) : (card.more[key] - values)
+        card.more = card.more.merge(key => new_value) # Has to be "card.more=" to be consi-
+      rescue TypeError, NoMethodError                 # dered changed (merge! wouldn't work)
+        raise Kood::TypeError, "Can't convert the attribute into a list."
+      end
+    end
+  end
+
+  # TODO Example: kood card lorem --add participants David Diogo -a labels bug
+  def insert_into_card_array_attribute(current_board, card)
+    update_card_array_attribute(current_board, card, :+)
+  end
+
+  # TODO Example: kood card lorem --remove participants David
+  def remove_from_card_array_attribute(current_board, card)
+    update_card_array_attribute(current_board, card, :-)
+  end
+
+  def print_card(board, card)
+    # The board's table may not use all terminal's horizontal space. In order to keep
+    # things visually similar / aligned, the card table should have the same width.
+    width = Kood::Table.new(board.list_ids.size).width
+
+    table = Kood::Table.new(1, width)
+    col = table.new_column
+    attribute_list = card.pretty_attributes
+    col.add_row(card.title, separator: !(card.content.empty? and attribute_list.empty?))
+    col.add_row(card.content) unless card.content.empty?
+    col.add_row(attribute_list) unless attribute_list.empty?
+
+    opts = options.color? ? { color: [:black, :bold] } : {}
+    col.add_row("#{ card.id } (created at #{ card.date })", opts)
+
+    # `join` is used to prevent partial content from being printed if an exception occurs
+    puts [table.separator('first'), table, table.separator('last')].join("\n")
+  end
+end