trello_tool 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4cfb13afc59a0bbc26ff8d073ec8205a8be3186078586626f2b1d1a6678534b
-  data.tar.gz: 24100d779e70261e15fd631cf8cc8c6e15bbfe52b4c14e020759244c10ac91f2
+  metadata.gz: 6ed0b9ce508c845c11e20e9832e4b0bdce3540b50eb726eb39f2e2b0a92dd1da
+  data.tar.gz: 72155610d0070653878eb3f705ece349d23358e97b105fb5d2bf75d5090b5d58
 SHA512:
-  metadata.gz: 0645b48ad54aea192469652a91a4d809c502cd32a97a440dbde72a40992ad365ba948c465d8c8e8705b424367f80783111cd36bf13530ad289f8515611a9d34e
-  data.tar.gz: a1a50a0449d75ddd376931d32caf80f057ca973d5825a003d4bee9b5ded2d89aea22501ae235cedebc78e40d89314b972773e701ffb330261aae5dbc314d633b
+  metadata.gz: 6811ec433a67808fb9b7d457127a59ac39c9e6e2e96717b51df6ef7f6f4669760f19e82c50b57928f3e41a8ee0e6261734765ebfe40ca65d2747df1332ae8942
+  data.tar.gz: 8345785d3149a3322c1850cd1ea89d48a2cf38eaf4249714835c047271c4ccd799b16e601a24ac2231e84a01626740ac0ab37ac30629e2185ea1d7e0b70327b7

data/CHANGELOG.md

@@ -1,4 +1,13 @@
-## [Unreleased]
+## [0.4.0] - 2026-10-02
+
+* added `search` and `cards` (find cards in a board; markdown or `--json`)
+* added `comment`, `create`, `checklist`, `check` and `move` (change cards), and the
+  `default_list_name_for_new_cards` configuration key for `create`
+* commands that fail now exit non-zero
+
+## [0.3.0] - 2026-09-04
+
+* added `summarize_as_md_long`
 
 ## [0.2.0] - 2022-05-21
 

data/README.md

@@ -56,6 +56,7 @@ You can also configure some defaults
 * `divider_template` = "[%s]"
 * `too_many_doing` = 2 
 * `too_many_todo` = 10
+* `default_list_name_for_new_cards` = (none) -- the list `create` puts a card in when no list is named, e.g. "Triage"
 
 
 ### Trello Authorisation
@@ -69,8 +70,42 @@ You can also read more at https://github.com/jeremytregunna/ruby-trello
 
 ## Usage
 
-* bin/trello/health
-trello/health
+`bin/trello_tool help` lists every command and `bin/trello_tool help COMMAND` its options. Boards default to
+`main_board_url`; cards are given by id or url; lists, labels and checklists by name.
+
+The board:
+
+* `bin/trello_tool health` -- checks whether the main board is "healthy"
+* `bin/trello_tool lists (BOARD_URL)` -- the lists of a board
+* `bin/trello_tool release (VERSION)`, `archive`, `archive_last (N)` -- rename "next version" on release, and
+  move old version lists to the archive board
+
+Reading cards:
+
+* `bin/trello_tool card CARD` -- one card as json (title, description, url, checklists, attachment urls)
+* `bin/trello_tool search QUERY (BOARD_URL) (--json)` -- the unarchived cards matching a trello search, grouped by
+  list. The query is trello's own, so `label:bug`, `list:"TO DO"` and the like work, and the last word matches as
+  a prefix
+* `bin/trello_tool cards (BOARD_URL) (--json)` -- every unarchived card in the board, grouped by list
+* `bin/trello_tool summarize_as_md`, `summarize_as_md_long`, `summarize_as_urls (LIST_NAME (BOARD_URL))` -- the
+  cards of one list
+
+Changing cards:
+
+* `bin/trello_tool comment CARD "text"` or `--file notes.md` -- adds a comment
+* `bin/trello_tool create (LIST_NAME (BOARD_URL)) --title "…" (--desc "…" | --desc-file card.md) (--label bug …)
+  (--top) (--force)` -- creates a card and prints it as json. Without LIST_NAME it goes in
+  `default_list_name_for_new_cards`. It first searches for an unarchived card with the same title and stops with
+  that card's url if there is one (`--force` creates another; trello's search can lag a few seconds behind a card
+  that was only just created)
+* `bin/trello_tool checklist CARD NAME --items "first" "second" (--checked)` -- adds the items to the card's
+  checklist of that name, creating the checklist if need be and skipping items already there
+* `bin/trello_tool check CARD "item text" (--checklist NAME) (--uncheck)` -- ticks (or unticks) the item with that
+  text, or the only item containing it
+* `bin/trello_tool move CARD (LIST_NAME (BOARD_URL)) (--top | --bottom)` -- to the bottom (or top) of a list; without
+  LIST_NAME, to the top or bottom of the list the card is in
+
+A command that can't do what it was asked says why and exits non-zero.
 
 ## Development
 

data/lib/trello_tool/configuration.rb

@@ -18,7 +18,8 @@ module TrelloTool
       version_template: "v%s",
       divider_template: "[%s]",
       too_many_doing: 2,
-      too_many_todo: 10
+      too_many_todo: 10,
+      default_list_name_for_new_cards: nil
     }.freeze
   end
   Configuration = Struct.new(*DefaultConfiguration::DEFAULTS.keys, keyword_init: true) do
@@ -33,7 +34,7 @@ module TrelloTool
     # generates a file based on current settings
     def generate
       File.open(config_file, "w") do |f|
-        Psych.dump(to_h { |k, v| [k.to_s, v] }, f) # rubocop:disable Style/HashTransformKeys doesn't work
+        Psych.dump(to_h { |k, v| [k.to_s, v] }, f)
       end
     end
 

data/lib/trello_tool/health.rb

@@ -3,7 +3,11 @@
 module TrelloTool
   # Health analysis of a board
   class Health
-    attr_reader :board, :configuration, :symbols_and_colours, :unexpected, :expected_lists
+    # @return [Trello::Board]
+    attr_reader :board
+    # @return [TrelloTool::Configuration]
+    attr_reader :configuration
+    attr_reader :symbols_and_colours, :unexpected, :expected_lists
 
     def initialize(board, configuration)
       @board = board

data/lib/trello_tool/trello_client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "trello"
 require "trello_tool/util"
 
@@ -7,6 +8,7 @@ module TrelloTool
   # Wrapped client for trello adapting it to things we need it to do
   class TrelloClient < SimpleDelegator
     include TrelloTool::Util
+
     attr_reader :client, :configuration
 
     # @param configuration[TrelloTool::Configuration]
@@ -54,6 +56,56 @@ module TrelloTool
       end
     end
 
+    # @param card_id [String]
+    # @return [Trello::Card]
+    def find_card(card_id)
+      client.find(:cards, card_id)
+    end
+
+    # @return [Trello::Board]
+    def find_board(board_url)
+      client.find(:boards, extract_id_from_url(board_url))
+    end
+
+    # the card fields the listing commands need, as trello names them
+    CARD_FIELDS = "name,url,idList,labels,closed"
+
+    # Unarchived cards of a board matching a trello search (operators such as label: and list: work, and the
+    # last word matches as a prefix)
+    # @return [Array<Hash>] cards as trello returns them: "name", "url", "idList", "labels"
+    def search_cards(board, query, limit: 50)
+      response = client.get("/search", "query" => query, "idBoards" => board.id, "modelTypes" => "cards",
+                                       "cards_limit" => limit.to_s, "card_fields" => CARD_FIELDS, "partial" => "true")
+      JSON.parse(response.body).fetch("cards", []).reject { |card| card["closed"] }
+    end
+
+    # Every unarchived card in an unarchived list of a board, in one request
+    # @return [Array<Hash>] as #search_cards
+    def open_cards(board)
+      JSON.parse(client.get("/boards/#{board.id}/cards/visible", "fields" => CARD_FIELDS).body)
+    end
+
+    # @param list [Trello::List]
+    # @return [Hash] the new card as trello returns it ("id", "url"...)
+    def create_card(list, title:, description: "", top: false, label_ids: [])
+      body = { name: title, desc: description, idList: list.id, pos: top ? "top" : "bottom" }
+      body[:idLabels] = label_ids.join(",") if label_ids.any?
+      JSON.parse(client.post("/cards", body).body)
+    end
+
+    # @param item [Hash] a checklist's check item ("id", "name", "state")
+    def set_check_item_state(card, item, complete:)
+      client.put("/cards/#{card.id}/checkItem/#{item['id']}", state: complete ? "complete" : "incomplete")
+    end
+
+    # @param position [String] "top" or "bottom"
+    # @param list [Trello::List, nil] nil to reposition the card within its list
+    def move_card(card, position:, list: nil)
+      body = { pos: position }
+      body[:idList] = list.id if list
+      client.put("/cards/#{card.id}", body)
+    end
+
     def next_version_list
       @next_version_list ||= find_list_by_list_name(main_board, configuration.next_version_list_name)
     end

data/lib/trello_tool/util.rb

@@ -14,6 +14,13 @@ module TrelloTool
       match_data[1]
     end
 
+    # @param card_id_or_url [String] a card id or a https://trello.com/c/ID/description url
+    # @return [String] the card id
+    def extract_card_id(card_id_or_url)
+      match_data = %r{\Ahttps://trello.com/c/([a-zA-Z0-9]+)/?.*}.match(card_id_or_url)
+      match_data ? match_data[1] : card_id_or_url
+    end
+
     # @param board [Trello::Board]
     # @param list_name [String]
     # @return [Trello::List]

data/lib/trello_tool/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TrelloTool
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/trello_tool_thor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "thor"
 require "trello_tool/configuration"
 require "trello_tool/health"
@@ -7,7 +8,7 @@ require "trello_tool/trello_client"
 require "trello_tool/util"
 
 # The thor class
-# rubocop:disable Metrics/ClassLength
+# rubocop:disable-next Metrics/ClassLength
 class TrelloToolThor < Thor
   include TrelloTool::Util
 
@@ -15,6 +16,11 @@ class TrelloToolThor < Thor
     @configuration ||= TrelloTool::Configuration.new
   end
 
+  # a command that can't do what it was asked (raises Thor::Error) exits non-zero
+  def self.exit_on_failure?
+    true
+  end
+
   no_commands do
     delegate :configuration, to: :class
   end
@@ -89,6 +95,14 @@ class TrelloToolThor < Thor
     end
   end
 
+  desc "card CARD_ID_OR_URL",
+       "prints out a card as json (title, description, url, checklists, attachment urls)"
+
+  def card(card_id_or_url)
+    card = client.find_card(extract_card_id(card_id_or_url))
+    say JSON.pretty_generate(card_as_hash(card))
+  end
+
   desc "release (VERSION)",
        "rename next_version to VERSION and create next_version. If VERSION isn't specified use whatever is in ./.RELEASE_NEW_VERSION"
 
@@ -162,10 +176,236 @@ class TrelloToolThor < Thor
     say "\n"
   end
 
+  desc "search QUERY (BOARD_URL)",
+       "prints the unarchived cards matching a trello search, grouped by list " \
+       "(operators like label: and list: work) -- markdown, or --json"
+  method_option :json, type: :boolean, default: false, desc: "print json instead of markdown"
+
+  def search(query, url = configuration.main_board_url)
+    board = client.find_board(url)
+    print_cards(board, client.search_cards(board, query))
+  end
+
+  desc "cards (BOARD_URL)", "prints every unarchived card in a board, grouped by list -- markdown, or --json"
+  method_option :json, type: :boolean, default: false, desc: "print json instead of markdown"
+
+  def cards(url = configuration.main_board_url)
+    board = client.find_board(url)
+    print_cards(board, client.open_cards(board))
+  end
+
+  desc "comment CARD_ID_OR_URL (TEXT)", "adds a comment to a card (the text inline, or from --file)"
+  method_option :file, type: :string, desc: "read the comment from this file"
+
+  def comment(card_id_or_url, text = nil)
+    raise Thor::Error, "give the comment either inline or with --file, not both" if text && options[:file]
+
+    text = File.read(options[:file]) if options[:file]
+    raise Thor::Error, "the comment is empty" if text.to_s.strip.empty?
+
+    card = client.find_card(extract_card_id(card_id_or_url))
+    card.add_comment(text)
+    say "commented on #{card.url}"
+  end
+
+  desc "create (LIST_NAME (BOARD_URL)) --title TITLE (--desc TEXT | --desc-file PATH) (--label NAME ...) (--top) (--force)",
+       "creates a card at the bottom (or --top) of LIST_NAME (default: default_list_name_for_new_cards) and " \
+       "prints it as json; stops if an unarchived card already has that title, unless --force"
+  method_option :title, type: :string, required: true
+  method_option :desc, type: :string, desc: "the description"
+  method_option :desc_file, type: :string, desc: "read the description (markdown) from this file"
+  method_option :label, type: :array, default: [], desc: "names of labels of the board"
+  method_option :top, type: :boolean, default: false, desc: "at the top of the list rather than the bottom"
+  method_option :force, type: :boolean, default: false, desc: "create even if a card with this title exists"
+
+  def create(list_name = configuration.default_list_name_for_new_cards, url = configuration.main_board_url)
+    title = title_option!
+    description = description_option!
+    no_list = "give a LIST_NAME, or set default_list_name_for_new_cards in #{configuration.config_file}"
+    raise Thor::Error, no_list unless list_name
+
+    board = client.find_board(url)
+    list = find_list!(board, list_name)
+    label_ids = label_ids!(board, Array(options[:label]))
+    refuse_duplicate!(board, title) unless options[:force]
+    created = client.create_card(list, title: title, description: description, top: options[:top] ? true : false,
+                                       label_ids: label_ids)
+    say "created #{created['url']} in #{list.name.inspect}"
+    card(created["id"])
+  end
+
+  desc "checklist CARD_ID_OR_URL NAME --items ITEM ...",
+       "adds items to the card's checklist of that name (creating it if need be), skipping items already there; " \
+       "prints the checklist as json"
+  method_option :items, type: :array, default: [], desc: "the items to add"
+  method_option :checked, type: :boolean, default: false, desc: "add the items already ticked"
+
+  def checklist(card_id_or_url, name)
+    card_id = extract_card_id(card_id_or_url)
+    list = find_checklist(card_id, name) || create_checklist(card_id, name)
+    existing = list.check_items.map { |item| item["name"] }
+    (Array(options[:items]).uniq - existing).each { |item| list.add_item(item, options[:checked] ? true : false, "bottom") }
+    say JSON.pretty_generate(checklist_as_hash(find_checklist(card_id, name)))
+  end
+
+  desc "check CARD_ID_OR_URL ITEM_TEXT (--checklist NAME) (--uncheck)",
+       "ticks (or with --uncheck unticks) the checklist item with that text (the whole text, or a part only it has)"
+  method_option :checklist, type: :string, desc: "only look in the checklist of this name"
+  method_option :uncheck, type: :boolean, default: false, desc: "untick instead"
+
+  def check(card_id_or_url, item_text)
+    card = client.find_card(extract_card_id(card_id_or_url))
+    item = find_check_item!(card, item_text)
+    client.set_check_item_state(card, item, complete: !options[:uncheck])
+    say "#{options[:uncheck] ? 'unticked' : 'ticked'} #{item['name'].inspect} on #{card.url}"
+  end
+
+  desc "move CARD_ID_OR_URL (LIST_NAME (BOARD_URL)) (--top | --bottom)",
+       "moves a card to the bottom (or --top) of a list; without LIST_NAME, to the top or bottom of the list it is in"
+  method_option :top, type: :boolean, default: false
+  method_option :bottom, type: :boolean, default: false
+
+  def move(card_id_or_url, list_name = nil, url = configuration.main_board_url)
+    position = position_option!(list_name)
+    card = client.find_card(extract_card_id(card_id_or_url))
+    list = find_list!(client.find_board(url), list_name) if list_name
+    client.move_card(card, position: position, list: list)
+    say "moved #{card.url} to the #{position} of #{list ? list.name.inspect : 'its list'}"
+  end
+
   private
 
   def client
     TrelloTool::TrelloClient.new(configuration)
   end
+
+  # @param cards [Array<Hash>] as trello returns them ("name", "url", "idList", "labels"); cards whose list is
+  #   archived (not among the board's lists) are left out
+  def print_cards(board, cards)
+    # in the board's list order
+    rows = board.lists.flat_map { |list| cards.filter_map { |found| card_row(found, [list]) } }
+    return say(JSON.pretty_generate(rows)) if options[:json]
+    return say("no cards found") if rows.empty?
+
+    print_cards_as_markdown(rows)
+  end
+
+  def print_cards_as_markdown(rows)
+    rows.group_by { |row| row[:list] }.each do |list_name, in_list|
+      say "\n# #{list_name} (#{in_list.length} cards)\n\n"
+      in_list.each { |row| say "* [#{row[:title]}](#{row[:url]})#{row[:labels].map { |label| " [#{label}]" }.join}" }
+    end
+    say "\n"
+  end
+
+  def title_option!
+    title = options[:title].to_s.strip
+    raise Thor::Error, "--title is empty" if title.empty?
+
+    title
+  end
+
+  def description_option!
+    both = "give the description either with --desc or with --desc-file, not both"
+    raise Thor::Error, both if options[:desc] && options[:desc_file]
+
+    options[:desc_file] ? File.read(options[:desc_file]) : options[:desc].to_s
+  end
+
+  # @return [String] "top" or "bottom" (the default when the card is going to another list)
+  def position_option!(list_name)
+    raise Thor::Error, "--top or --bottom, not both" if options[:top] && options[:bottom]
+    raise Thor::Error, "give a LIST_NAME, --top or --bottom" unless list_name || options[:top] || options[:bottom]
+
+    options[:top] ? "top" : "bottom"
+  end
+
+  # @return [Hash, nil] nil when the card's list isn't one of lists
+  def card_row(found, lists)
+    list = lists.detect { |candidate| candidate.id == found["idList"] }
+    return nil unless list
+
+    { title: found["name"], url: found["url"], list: list.name,
+      labels: (found["labels"] || []).map { |label| label["name"].to_s }.reject(&:empty?) }
+  end
+
+  # the list of that name (exactly, or failing that the only one that differs just by case)
+  def find_list!(board, list_name)
+    lists = board.lists
+    list = lists.detect { |candidate| candidate.name == list_name }
+    list ||= lists.select { |candidate| candidate.name.casecmp?(list_name) }.then { |found| found.first if found.size == 1 }
+    list || raise(Thor::Error, "no list called #{list_name.inspect} in #{board.name}. Lists: #{lists.map(&:name).join(', ')}")
+  end
+
+  def label_ids!(board, names)
+    return [] if names.empty?
+
+    labels = board.labels
+    names.map do |name|
+      label = labels.detect { |candidate| candidate.name.to_s.casecmp?(name) }
+      label&.id || raise(Thor::Error, "no label called #{name.inspect} in #{board.name}. " \
+                                      "Labels: #{labels.map { |candidate| candidate.name.to_s }.reject(&:empty?).join(', ')}")
+    end
+  end
+
+  def refuse_duplicate!(board, title)
+    duplicate = client.search_cards(board, %("#{title.delete('"')}")).detect { |found| found["name"].to_s.strip.casecmp?(title) }
+    return unless duplicate
+
+    raise Thor::Error, "a card called #{title.inspect} already exists: #{duplicate['url']} (--force to create another)"
+  end
+
+  # always from a fresh read of the card, so it sees a checklist or item that was just added
+  def find_checklist(card_id, name)
+    client.find_card(card_id).checklists.detect { |candidate| candidate.name == name }
+  end
+
+  def create_checklist(card_id, name)
+    client.find_card(card_id).create_new_checklist(name)
+    find_checklist(card_id, name) || raise(Thor::Error, "couldn't create the checklist #{name.inspect}")
+  end
+
+  # @return [Hash] the one check item whose name is item_text, or failing that the one containing it
+  def find_check_item!(card, item_text)
+    items = check_items!(card)
+    matches = items.select { |item| item["name"].casecmp?(item_text) }
+    matches = items.select { |item| item["name"].downcase.include?(item_text.downcase) } if matches.empty?
+    return matches.first if matches.size == 1
+
+    problem = matches.empty? ? "no item matching" : "more than one item matching"
+    candidates = (matches.empty? ? items : matches).map { |item| item["name"].inspect }.join(", ")
+    raise Thor::Error, "#{problem} #{item_text.inspect} on #{card.url}. Items: #{candidates}"
+  end
+
+  # @return [Array<Hash>] the check items of the card's checklists (of the --checklist one, if given)
+  def check_items!(card)
+    name = options[:checklist]
+    checklists = card.checklists.select { |candidate| name.nil? || candidate.name == name }
+    raise Thor::Error, "no checklist#{" called #{name.inspect}" if name} on #{card.url}" if checklists.empty?
+
+    checklists.flat_map(&:check_items)
+  end
+
+  # @param card [Trello::Card]
+  # @return [Hash]
+  def card_as_hash(card)
+    {
+      title: card.name,
+      description: card.desc,
+      url: card.url,
+      checklists: card.checklists.map { |checklist| checklist_as_hash(checklist) },
+      attachment_urls: card.attachments.map(&:url)
+    }
+  end
+
+  # @param checklist [Trello::Checklist]
+  # @return [Hash]
+  def checklist_as_hash(checklist)
+    {
+      name: checklist.name,
+      items: checklist.check_items.map do |item|
+        { name: item["name"], complete: item["state"] == "complete" }
+      end
+    }
+  end
 end
-# rubocop:enable Metrics/ClassLength

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trello_tool
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tim Diggins
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-trello
@@ -38,7 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - tim@red56.uk
 executables:
@@ -73,7 +71,6 @@ metadata:
   source_code_uri: https://github.com/timdiggins/trello_tool
   changelog_uri: https://github.com/timdiggins/trello_tool/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -88,8 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.15
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Tool for doing basic things to a dev trello using the api.
 test_files: []