superthread 0.7.2

data/lib/superthread/cli/checklists.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing card checklists.
+    #
+    # Checklists are task lists attached to cards with trackable items.
+    # This class provides commands to create, update, and delete checklists
+    # as well as manage checklist items.
+    class Checklists < Base
+      # Kebab-case aliases for commands
+      map "add-item" => :add_item,
+        "update-item" => :update_item,
+        "remove-item" => :remove_item
+
+      desc "list", "List all checklists on a card"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      # List all checklists on a specified card.
+      #
+      # @return [void]
+      def list
+        handle_error do
+          card = client.cards.find(workspace_id, options[:card])
+          if card.checklists.nil? || card.checklists.empty?
+            say "No checklists found on this card.", :yellow
+          else
+            output_list card.checklists, columns: %i[id title], headers: {id: "CHECKLIST_ID"}
+          end
+        end
+      end
+
+      desc "get CHECKLIST", "Get checklist details"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      # Display detailed information about a specific checklist.
+      #
+      # @param checklist_id [String] the unique identifier of the checklist
+      # @return [void]
+      def get(checklist_id)
+        handle_error do
+          card = client.cards.find(workspace_id, options[:card])
+          checklist = card.checklists&.find { |c| c.id == checklist_id }
+          raise Thor::Error, "Checklist not found: #{checklist_id}" unless checklist
+
+          if json_output?
+            output_item checklist, fields: %i[id title card_id items time_created], labels: {
+              id: "Checklist ID",
+              card_id: "Card ID",
+              time_created: "Time Created"
+            }
+          else
+            output_item checklist, fields: %i[id title card_id time_created], labels: {
+              id: "Checklist ID",
+              card_id: "Card ID",
+              time_created: "Time Created"
+            }
+
+            if checklist.items&.any?
+              puts ""
+              Ui.section "Items"
+              checklist.items.each do |item|
+                marker = item.checked? ? "✓" : "○"
+                puts "  #{marker} #{item.title} (#{item.id})"
+              end
+            end
+          end
+        end
+      end
+
+      desc "create", "Create a checklist on a card"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :title, type: :string, required: true, desc: "Checklist title"
+      # Add a new checklist to a card.
+      #
+      # @return [void]
+      def create
+        handle_error do
+          checklist = client.cards.create_checklist(workspace_id, options[:card], title: options[:title])
+          output_item checklist, fields: %i[id title card_id time_created], labels: {id: "Checklist ID"}
+        end
+      end
+
+      desc "update CHECKLIST", "Update a checklist"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :title, type: :string, required: true, desc: "New checklist title"
+      # Rename an existing checklist on a card.
+      #
+      # @param checklist_id [String] the unique identifier of the checklist
+      # @return [void]
+      def update(checklist_id)
+        handle_error do
+          checklist = client.cards.update_checklist(
+            workspace_id, options[:card], checklist_id,
+            title: options[:title]
+          )
+          output_item checklist, fields: %i[id title card_id time_created], labels: {id: "Checklist ID"}
+        end
+      end
+
+      desc "delete CHECKLIST", "Delete a checklist"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      # Remove a checklist and all its items from a card after confirmation.
+      #
+      # @param checklist_id [String] the unique identifier of the checklist
+      # @return [void]
+      def delete(checklist_id)
+        handle_error do
+          card = client.cards.find(workspace_id, options[:card])
+          checklist = card.checklists&.find { |c| c.id == checklist_id }
+          checklist_name = checklist&.title || checklist_id
+          confirming("Delete checklist '#{checklist_name}' (#{checklist_id})?") do
+            client.cards.delete_checklist(workspace_id, options[:card], checklist_id)
+            output_success "Checklist '#{checklist_name}' deleted"
+          end
+        end
+      end
+
+      desc "add-item CHECKLIST", "Add item to a checklist"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :title, type: :string, required: true, desc: "Item title"
+      option :checked, type: :boolean, default: false, desc: "Create as checked"
+      # Add a new item to an existing checklist.
+      #
+      # @param checklist_id [String] the unique identifier of the checklist
+      # @return [void]
+      def add_item(checklist_id)
+        handle_error do
+          item = client.cards.add_checklist_item(
+            workspace_id, options[:card], checklist_id,
+            title: options[:title],
+            checked: options[:checked]
+          )
+          output_item item, fields: %i[id title checked checklist_id], labels: {
+            id: "Item ID",
+            checklist_id: "Checklist ID"
+          }
+        end
+      end
+
+      desc "update-item ITEM_ID", "Update a checklist item"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :checklist, type: :string, required: true, desc: "Parent checklist ID"
+      option :title, type: :string, desc: "New item title"
+      option :checked, type: :boolean, desc: "Mark as checked/unchecked"
+      # Update the title or checked state of a checklist item.
+      #
+      # @param item_id [String] the unique identifier of the item
+      # @return [void]
+      def update_item(item_id)
+        handle_error do
+          opts = symbolized_options(:title, :checked)
+          item = client.cards.update_checklist_item(
+            workspace_id, options[:card], options[:checklist], item_id,
+            **opts
+          )
+          output_item item, fields: %i[id title checked checklist_id], labels: {
+            id: "Item ID",
+            checklist_id: "Checklist ID"
+          }
+        end
+      end
+
+      desc "remove-item ITEM_ID", "Delete a checklist item"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :checklist, type: :string, required: true, desc: "Parent checklist ID"
+      # Remove an item from a checklist after confirmation.
+      #
+      # @param item_id [String] the unique identifier of the item
+      # @return [void]
+      def remove_item(item_id)
+        handle_error do
+          card = client.cards.find(workspace_id, options[:card])
+          checklist = card.checklists&.find { |c| c.id == options[:checklist] }
+          item = checklist&.items&.find { |i| i.id == item_id }
+          item_name = item&.title || item_id
+          confirming("Delete checklist item '#{item_name}' (#{item_id})?") do
+            client.cards.delete_checklist_item(workspace_id, options[:card], options[:checklist], item_id)
+            output_success "Checklist item '#{item_name}' deleted"
+          end
+        end
+      end
+
+      desc "check ITEM_ID", "Mark a checklist item as checked"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :checklist, type: :string, required: true, desc: "Parent checklist ID"
+      # Mark a checklist item as completed.
+      #
+      # @param item_id [String] the unique identifier of the item
+      # @return [void]
+      def check(item_id)
+        handle_error do
+          item = client.cards.update_checklist_item(
+            workspace_id, options[:card], options[:checklist], item_id,
+            checked: true
+          )
+          output_item item, fields: %i[id title checked checklist_id], labels: {
+            id: "Item ID",
+            checklist_id: "Checklist ID"
+          }
+        end
+      end
+
+      desc "uncheck ITEM_ID", "Mark a checklist item as unchecked"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Parent card ID"
+      option :checklist, type: :string, required: true, desc: "Parent checklist ID"
+      # Mark a checklist item as not completed.
+      #
+      # @param item_id [String] the unique identifier of the item
+      # @return [void]
+      def uncheck(item_id)
+        handle_error do
+          item = client.cards.update_checklist_item(
+            workspace_id, options[:card], options[:checklist], item_id,
+            checked: false
+          )
+          output_item item, fields: %i[id title checked checklist_id], labels: {
+            id: "Item ID",
+            checklist_id: "Checklist ID"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/comments.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing comments on Superthread cards and pages.
+    #
+    # Provides subcommands for creating, updating, and deleting comments.
+    class Comments < Base
+      desc "list", "List comments on a card"
+      option :card, type: :string, required: true, aliases: "-c", desc: "Card ID"
+      # List all comments on a specified card.
+      #
+      # @return [void]
+      def list
+        handle_error do
+          comments = client.comments.list(workspace_id, card_id: options[:card])
+          output_list comments, columns: %i[id user_id content time_created], headers: {id: "COMMENT_ID"}
+        end
+      end
+
+      desc "get COMMENT_ID", "Get comment details"
+      # Display detailed information about a specific comment.
+      #
+      # @param comment_id [String] the unique identifier of the comment to retrieve
+      # @return [void]
+      def get(comment_id)
+        handle_error do
+          comment = with_not_found("Comment not found: '#{comment_id}'.") do
+            client.comments.find(workspace_id, comment_id)
+          end
+          output_item comment, fields: %i[id content user_id card_id time_created time_updated],
+            labels: {id: "Comment ID"}
+        end
+      end
+
+      desc "create", "Create a comment"
+      option :content, type: :string, required: true, desc: "Comment content (HTML)"
+      option :card, type: :string, aliases: "-c", desc: "Parent card ID (required unless --page)"
+      option :page, type: :string, aliases: "-p", desc: "Parent page ID (required unless --card)"
+      # Create a new comment on a card or page.
+      #
+      # @return [void]
+      def create
+        opts = symbolized_options(:content)
+        opts[:card_id] = options[:card] if options[:card]
+        opts[:page_id] = options[:page] if options[:page]
+        comment = client.comments.create(workspace_id, **opts)
+        output_item comment, labels: {id: "Comment ID"}
+      end
+
+      desc "update COMMENT_ID", "Update a comment"
+      option :content, type: :string, desc: "New content"
+      option :status, type: :string, enum: %w[resolved open orphaned], desc: "Comment status"
+      # Update an existing comment's content or status.
+      #
+      # @param comment_id [String] the unique identifier of the comment to update
+      # @return [void]
+      def update(comment_id)
+        handle_error do
+          comment = with_not_found("Comment not found: '#{comment_id}'.") do
+            client.comments.update(workspace_id, comment_id, **symbolized_options(:content, :status))
+          end
+          output_item comment, labels: {id: "Comment ID"}
+        end
+      end
+
+      desc "delete COMMENT_ID", "Delete a comment"
+      # Permanently delete a comment after confirmation.
+      #
+      # @param comment_id [String] the unique identifier of the comment to delete
+      # @return [void]
+      def delete(comment_id)
+        handle_error do
+          comment = with_not_found("Comment not found: '#{comment_id}'.") do
+            client.comments.find(workspace_id, comment_id)
+          end
+          preview = Formatter.truncate(Formatter.strip_html(comment.content), 50)
+          confirming("Delete comment '#{preview}' (#{comment.id})?") do
+            client.comments.destroy(workspace_id, comment.id)
+            output_success "Comment #{comment.id} deleted"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/completion.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # Generate shell completion scripts for bash, zsh, and fish.
+    # Uses Thor introspection to automatically discover commands and options.
+    class Completion < Base
+      desc "bash", "Generate bash completion script"
+      long_desc <<~DESC
+        Generate the autocompletion script for the bash shell.
+
+        To load completions in your current shell session:
+
+          source <(suth completion bash)
+
+        To load completions for every new session, execute once:
+
+          # macOS (Homebrew):
+          suth completion bash > $(brew --prefix)/etc/bash_completion.d/suth
+
+          # Linux:
+          suth completion bash > /etc/bash_completion.d/suth
+
+        You will need to start a new shell for this setup to take effect.
+      DESC
+      # Outputs a bash completion script for the CLI.
+      #
+      # @return [void]
+      def bash
+        puts bash_completion_script
+      end
+
+      desc "zsh", "Generate zsh completion script"
+      long_desc <<~DESC
+        Generate the autocompletion script for the zsh shell.
+
+        To load completions in your current shell session:
+
+          source <(suth completion zsh)
+
+        To load completions for every new session, execute once:
+
+          # macOS (Homebrew):
+          suth completion zsh > $(brew --prefix)/share/zsh/site-functions/_suth
+
+          # Linux:
+          suth completion zsh > "${fpath[1]}/_suth"
+
+        You will need to start a new shell for this setup to take effect.
+      DESC
+      # Outputs a zsh completion script for the CLI.
+      #
+      # @return [void]
+      def zsh
+        puts zsh_completion_script
+      end
+
+      desc "fish", "Generate fish completion script"
+      long_desc <<~DESC
+        Generate the autocompletion script for the fish shell.
+
+        To load completions in your current shell session:
+
+          suth completion fish | source
+
+        To load completions for every new session, execute once:
+
+          suth completion fish > ~/.config/fish/completions/suth.fish
+
+        You will need to start a new shell for this setup to take effect.
+      DESC
+      # Outputs a fish completion script for the CLI.
+      #
+      # @return [void]
+      def fish
+        puts fish_completion_script
+      end
+
+      private
+
+      # Get the cached command structure from Thor introspection.
+      #
+      # @return [Hash{String => Hash}] command names mapped to their metadata
+      def command_structure
+        @command_structure ||= build_command_structure
+      end
+
+      # Build command structure by introspecting Thor classes.
+      #
+      # @return [Hash{String => Hash}] command names with :desc, :subcommands, :options
+      def build_command_structure
+        structure = {}
+        main_class = Superthread::Cli::Main
+
+        main_class.commands.each do |name, command|
+          next if name == "help"
+
+          structure[name] = {
+            desc: command.description,
+            subcommands: {},
+            options: extract_options(command)
+          }
+        end
+
+        # Add subcommand details
+        main_class.subcommand_classes.each do |name, klass|
+          next unless structure[name]
+
+          klass.commands.each do |subcmd_name, subcmd|
+            next if subcmd_name == "help"
+
+            structure[name][:subcommands][subcmd_name] = {
+              desc: subcmd.description,
+              options: extract_options(subcmd)
+            }
+          end
+        end
+
+        structure
+      end
+
+      # Extract option definitions from a Thor command.
+      #
+      # @param command [Thor::Command] the command to extract options from
+      # @return [Array<Hash{Symbol => String}>] array of option hashes with :flag, :name, :desc
+      def extract_options(command)
+        command.options.map do |name, opt|
+          flag = "--#{name.to_s.tr("_", "-")}"
+          flag = "-#{opt.aliases.first}, #{flag}" if opt.aliases&.any?
+          {flag: flag, name: name.to_s.tr("_", "-"), desc: opt.description || name.to_s}
+        end
+      end
+
+      # Get the list of global CLI options available on all commands.
+      #
+      # @return [Array<Hash{Symbol => String}>] array of option hashes with :flag, :name, :desc
+      def global_options
+        [
+          {flag: "-v, --verbose", name: "verbose", desc: "Detailed logging"},
+          {flag: "-q, --quiet", name: "quiet", desc: "Minimal logging"},
+          {flag: "-w, --workspace", name: "workspace", desc: "Workspace (ID or name)"},
+          {flag: "--json", name: "json", desc: "Output as JSON"},
+          {flag: "-a, --account", name: "account", desc: "Use specific account"},
+          {flag: "-y, --yes", name: "yes", desc: "Auto-confirm prompts"}
+        ]
+      end
+
+      # Generate a bash completion script for the CLI.
+      #
+      # @return [String] the complete bash completion script
+      def bash_completion_script
+        cmds = command_structure
+        main_commands = cmds.keys.join(" ")
+        global_opts = global_options.map { |o| o[:flag].split(", ").last }.join(" ")
+
+        subcommand_cases = cmds.map do |cmd, data|
+          next if data[:subcommands].empty?
+
+          subcmds = data[:subcommands].keys.join(" ")
+          <<~CASE.chomp
+            #{cmd})
+                COMPREPLY=($(compgen -W "#{subcmds}" -- "${cur}"))
+                return 0
+                ;;
+          CASE
+        end.compact.join("\n")
+
+        <<~BASH
+          # Bash completion for suth (Superthread CLI)
+          # Generated by: suth completion bash
+
+          _suth() {
+              local cur prev commands
+              COMPREPLY=()
+              cur="${COMP_WORDS[COMP_CWORD]}"
+              prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+              commands="#{main_commands}"
+
+              case "${prev}" in
+                  suth)
+                      COMPREPLY=($(compgen -W "${commands}" -- "${cur}"))
+                      return 0
+                      ;;
+          #{subcommand_cases}
+              esac
+
+              # Complete options
+              if [[ "${cur}" == -* ]]; then
+                  COMPREPLY=($(compgen -W "#{global_opts}" -- "${cur}"))
+                  return 0
+              fi
+          }
+
+          complete -F _suth suth
+        BASH
+      end
+
+      # Generate a zsh completion script for the CLI.
+      #
+      # @return [String] the complete zsh completion script
+      def zsh_completion_script
+        cmds = command_structure
+
+        commands_list = cmds.map do |cmd, data|
+          "    '#{cmd}:#{escape_zsh(data[:desc])}'"
+        end.join("\n")
+
+        subcommand_cases = cmds.map do |cmd, data|
+          next if data[:subcommands].empty?
+
+          subcmds_list = data[:subcommands].map do |subcmd, subcmd_data|
+            "        '#{subcmd}:#{escape_zsh(subcmd_data[:desc])}'"
+          end.join("\n")
+
+          <<~CASE.chomp
+                    #{cmd})
+                        local -a subcommands
+                        subcommands=(
+            #{subcmds_list}
+                        )
+                        _describe -t commands '#{cmd} subcommands' subcommands
+                        ;;
+          CASE
+        end.compact.join("\n")
+
+        <<~ZSH
+          #compdef suth
+
+          # Zsh completion for suth (Superthread CLI)
+          # Generated by: suth completion zsh
+
+          _suth() {
+              local -a commands
+
+              commands=(
+          #{commands_list}
+              )
+
+              if (( CURRENT == 2 )); then
+                  _describe 'command' commands
+                  return
+              fi
+
+              case "${words[2]}" in
+          #{subcommand_cases}
+              esac
+          }
+
+          _suth "$@"
+        ZSH
+      end
+
+      # Generate a fish completion script for the CLI.
+      #
+      # @return [String] the complete fish completion script
+      def fish_completion_script
+        cmds = command_structure
+
+        lines = [
+          "# Fish completion for suth (Superthread CLI)",
+          "# Generated by: suth completion fish",
+          "",
+          "# Disable file completion by default",
+          "complete -c suth -f",
+          "",
+          "# Main commands"
+        ]
+
+        cmds.each do |cmd, data|
+          lines << "complete -c suth -n __fish_use_subcommand -a #{cmd} -d '#{escape_fish(data[:desc])}'"
+        end
+
+        lines << ""
+
+        cmds.each do |cmd, data|
+          next if data[:subcommands].empty?
+
+          lines << "# #{cmd} subcommands"
+          data[:subcommands].each do |subcmd, subcmd_data|
+            lines << "complete -c suth -n '__fish_seen_subcommand_from #{cmd}' -a #{subcmd} -d '#{escape_fish(subcmd_data[:desc])}'"
+          end
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      # Escape a string for safe inclusion in zsh completion script.
+      #
+      # @param str [String] the string to escape
+      # @return [String] the escaped string with single quotes properly handled
+      def escape_zsh(str)
+        str.to_s.gsub("'", "'\\''")
+      end
+
+      # Escape a string for safe inclusion in fish completion script.
+      #
+      # @param str [String] the string to escape
+      # @return [String] the escaped string with single quotes properly handled
+      def escape_fish(str)
+        str.to_s.gsub("'", "\\\\'")
+      end
+    end
+  end
+end

data/lib/superthread/cli/concerns/board_resolvable.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves board references (ID or name) to board IDs.
+      #
+      # Board resolution is context-dependent: when --space is provided, it
+      # searches only within that space. Otherwise, it searches across all
+      # spaces in the workspace.
+      module BoardResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Get the board ID from --board option, resolving name if needed.
+        #
+        # @return [String, nil] the resolved board ID, or nil if not specified
+        def board_id
+          resolve_board(options[:board])
+        end
+
+        # Resolve a board reference (ID or name) to its ID.
+        #
+        # @param ref [String, nil] the board ID or name to resolve
+        # @return [String, nil] the resolved board ID
+        # @raise [Thor::Error] if name is provided but not found
+        def resolve_board(ref)
+          return ref if ref.nil?
+          return ref if looks_like_id?(ref)
+
+          board = find_board_by_name(ref)
+          return board.id if board
+
+          raise Thor::Error, "Board not found: '#{ref}'. Use 'suth boards list --space <space>' to see available boards."
+        end
+
+        # Find a board by name, searching within space if specified or all spaces.
+        #
+        # @param name [String] the board name to search for (case-insensitive)
+        # @return [Superthread::Models::Board, nil] the board object or nil if not found
+        def find_board_by_name(name)
+          # If space is specified, search only in that space
+          if options[:space]
+            @boards_cache ||= client.boards.list(workspace_id, space_id: space_id)
+            return @boards_cache.find { |b| b.title&.downcase == name.downcase }
+          end
+
+          # Otherwise search across all spaces
+          @all_boards_cache ||= load_all_boards
+          @all_boards_cache.find { |b| b.title&.downcase == name.downcase }
+        end
+
+        # Load all boards from all spaces in the workspace.
+        #
+        # @return [Array<Superthread::Models::Board>] all accessible boards
+        def load_all_boards
+          @spaces_cache ||= client.spaces.list(workspace_id)
+          @spaces_cache.flat_map do |space|
+            client.boards.list(workspace_id, space_id: space.id).to_a
+          rescue Superthread::ApiError
+            [] # Skip spaces we can't access
+          end
+        end
+      end
+    end
+  end
+end