superthread 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cf0f4679210af65b63f13141b5c432b8fa2999468842808a58ba2c71d15b7f1
-  data.tar.gz: 922afee485ffb459bb189fcedb92af8649e8422d52baf3230d19c47288cd63bf
+  metadata.gz: eb38a8ab1c8ba081e66e8bda3bc4fabcb8aa9732e1e8cfc5ce1bdff0b14f94b2
+  data.tar.gz: e97e7bffe8dc9bfbd86b424a6762455d1d9979b07a60651b3997ad5feaedddf5
 SHA512:
-  metadata.gz: c0e8b5023fd60313bcd7b82cbb650ef3520f11befe1bbef9bf7427feed115003ed3afe287d63c48d5939177a3d689850f9398a3bbf9cb534ac00b021db68f7b7
-  data.tar.gz: b9ceb55ed32d01d2f7010ff234427fbe527f54c749c27f1dc3b03bb17c24d6aed15c82cb010c6a848831c4d0977e232602c3a7c23950cbb8a201a24ab7318897
+  metadata.gz: b2c5dfabc604f08c7aae0eedb7a94fb8f702912c5ccc2730c9d388d6f404dbdff8aa9f3fa835288732612f84d7755e4a2a5283f1d266747b3e9727aa09fdbe5f
+  data.tar.gz: 847b4c2868387c94b08bbbffab9db1d80dac9b4991884941258eb801347996f11257cdc1079d192848ae5208936352da2b894f95a1288914403279395b50cf61

data/README.md

@@ -328,6 +328,16 @@ Common options have short forms:
 > - Use `me` as a shortcut: `suth cards assigned me`
 > - Priority levels: 1=Urgent, 2=High, 3=Medium, 4=Low
 
+### Mentions
+
+Use `{{@Name}}` to tag workspace members in comments, replies, and checklist items:
+
+```bash
+suth comments create -c CARD --content "{{@Stacey}} Ready for review."
+```
+
+The name is matched case-insensitively against member display names. Unresolved mentions produce a warning.
+
 ## Library Usage
 
 You can also use Superthread as a Ruby gem in your code:

data/lib/superthread/cli/base.rb

@@ -137,7 +137,7 @@ module Superthread
       def output_list(items, columns: nil, headers: {})
         all_items = items.respond_to?(:items) ? items.items : Array(items)
         limit = effective_limit
-        truncated = all_items.length > limit
+        truncated = limit && all_items.length > limit
         visible = truncated ? all_items.first(limit) : all_items
 
         if json_output?

data/lib/superthread/cli/cards.rb

@@ -52,6 +52,52 @@ module Superthread
         end
       end
 
+      desc "search TERM", "Search for cards across boards and spaces"
+      option :space, type: :string, aliases: "-s", desc: "Space to filter by (ID or name)"
+      option :status, type: :string, desc: "Status filter (comma-separated)"
+      option :field, type: :string, enum: %w[title content], desc: "Search in title or content"
+      option :include_archived, type: :boolean, desc: "Include archived cards"
+      # Search for cards by keyword with rich output.
+      #
+      # @param term [String] the search term
+      # @return [void]
+      def search(term)
+        handle_error do
+          statuses = options[:status]&.split(",")&.map(&:strip)
+          results = client.search.query(
+            workspace_id,
+            query: term,
+            types: ["card"],
+            statuses: statuses,
+            field: options[:field],
+            space_id: (space_id if options[:space]),
+            archived: options[:include_archived],
+            limit: effective_limit
+          )
+
+          card_ids = results.map { |r| r[:id] }.compact
+          if card_ids.empty?
+            say "No cards found matching '#{term}'.", :yellow unless options[:quiet]
+            return
+          end
+
+          cards = card_ids.filter_map do |id|
+            client.cards.find(workspace_id, id)
+          rescue Superthread::NotFoundError, Superthread::ForbiddenError
+            nil
+          end
+
+          if cards.empty?
+            say "No cards found matching '#{term}'.", :yellow unless options[:quiet]
+            return
+          end
+
+          enrich_members(cards)
+          output_list cards, columns: %i[id title priority list_title board_title members],
+            headers: {id: "CARD_ID", list_title: "LIST", board_title: "BOARD"}
+        end
+      end
+
       desc "get CARD", "Get card details"
       option :raw, type: :boolean, desc: "Show raw content without markdown rendering"
       option :no_content, type: :boolean, desc: "Hide content, show only metadata"
@@ -393,6 +439,16 @@ module Superthread
 
       private
 
+      # Override Base#effective_limit for search-specific defaults.
+      # Returns nil for --limit 0 (unlimited), 30 for search default.
+      #
+      # @return [Integer, nil] the limit (nil = unlimited when --limit 0)
+      def effective_limit
+        limit = options[:limit]
+        return nil if limit == 0
+        (limit.is_a?(Integer) && limit > 0) ? limit : 30
+      end
+
       # Enrich card members with display names from workspace users.
       #
       # The API returns members with only user_id. This fetches the workspace
@@ -441,11 +497,23 @@ module Superthread
             sprint_obj = client.sprints.find(workspace_id, existing.sprint_id,
               space_id: existing.project_id)
             list = sprint_obj.lists&.find { |l| l.title&.downcase == list_ref.downcase }
+            unless list || looks_like_id?(list_ref)
+              available = sprint_obj.lists&.map(&:title)&.join(", ") || "none"
+              raise Thor::Error, "List '#{list_ref}' not found in sprint. Available: #{available}"
+            end
             result[:list_id] = list ? list.id : list_ref
             result[:sprint_id] = existing.sprint_id
             result[:project_id] = existing.project_id
+          elsif looks_like_id?(list_ref)
+            result[:list_id] = list_ref
           else
-            result[:list_id] = resolve_list(list_ref)
+            board = client.boards.find(workspace_id, existing.board_id)
+            list = board.lists&.find { |l| l.title&.downcase == list_ref.downcase }
+            unless list
+              available = board.lists&.map(&:title)&.join(", ") || "none"
+              raise Thor::Error, "List '#{list_ref}' not found on board. Available: #{available}"
+            end
+            result[:list_id] = list.id
           end
         end
 
@@ -518,7 +586,7 @@ module Superthread
         card.checklists.each do |checklist|
           progress = "(#{checklist.completed_count}/#{checklist.total_count})"
           Ui.kv(checklist.title, progress)
-          checklist.items&.each do |item|
+          checklist.sorted_items.each do |item|
             marker = item.checked? ? "✓" : "○"
             title = item.title.gsub(/<[^>]*>/, "").strip
             puts "  #{marker} #{title}"

data/lib/superthread/cli/checklists.rb

@@ -57,7 +57,7 @@ module Superthread
             if checklist.items&.any?
               puts ""
               Ui.section "Items"
-              checklist.items.each do |item|
+              checklist.sorted_items.each do |item|
                 marker = item.checked? ? "✓" : "○"
                 puts "  #{marker} #{item.title} (#{item.id})"
               end
@@ -179,43 +179,45 @@ module Superthread
         end
       end
 
-      desc "check ITEM_ID", "Mark a checklist item as checked"
+      desc "check ITEM_ID [ITEM_ID...]", "Mark checklist item(s) 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.
+      # Mark one or more checklist items as completed.
       #
-      # @param item_id [String] the unique identifier of the item
+      # @param item_ids [Array<String>] the unique identifiers of the items
       # @return [void]
-      def check(item_id)
+      def check(*item_ids)
         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"
-          }
+          raise Thor::Error, "No item IDs provided" if item_ids.empty?
+
+          item_ids.each do |item_id|
+            client.cards.update_checklist_item(
+              workspace_id, options[:card], options[:checklist], item_id,
+              checked: true
+            )
+          end
+          output_success "Checked #{item_ids.size} item(s)"
         end
       end
 
-      desc "uncheck ITEM_ID", "Mark a checklist item as unchecked"
+      desc "uncheck ITEM_ID [ITEM_ID...]", "Mark checklist item(s) 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.
+      # Mark one or more checklist items as not completed.
       #
-      # @param item_id [String] the unique identifier of the item
+      # @param item_ids [Array<String>] the unique identifiers of the items
       # @return [void]
-      def uncheck(item_id)
+      def uncheck(*item_ids)
         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"
-          }
+          raise Thor::Error, "No item IDs provided" if item_ids.empty?
+
+          item_ids.each do |item_id|
+            client.cards.update_checklist_item(
+              workspace_id, options[:card], options[:checklist], item_id,
+              checked: false
+            )
+          end
+          output_success "Unchecked #{item_ids.size} item(s)"
         end
       end
     end

data/lib/superthread/cli/comments.rb

@@ -34,7 +34,7 @@ module Superthread
       end
 
       desc "create", "Create a comment"
-      option :content, type: :string, required: true, desc: "Comment content (HTML)"
+      option :content, type: :string, required: true, desc: "Comment content (HTML). Use {{@Name}} to mention users"
       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.
@@ -49,7 +49,7 @@ module Superthread
       end
 
       desc "update COMMENT_ID", "Update a comment"
-      option :content, type: :string, desc: "New content"
+      option :content, type: :string, desc: "New content (HTML). Use {{@Name}} to mention users"
       option :status, type: :string, enum: %w[resolved open orphaned], desc: "Comment status"
       # Update an existing comment's content or status.
       #

data/lib/superthread/cli/replies.rb

@@ -44,7 +44,7 @@ module Superthread
 
       desc "create", "Reply to a comment"
       option :comment, type: :string, required: true, desc: "Parent comment ID"
-      option :content, type: :string, required: true, desc: "Reply content"
+      option :content, type: :string, required: true, desc: "Reply content (HTML). Use {{@Name}} to mention users"
       # Add a threaded reply to an existing comment.
       #
       # @return [void]
@@ -57,7 +57,7 @@ module Superthread
 
       desc "update REPLY_ID", "Update a reply"
       option :comment, type: :string, required: true, desc: "Parent comment ID"
-      option :content, type: :string, desc: "New content"
+      option :content, type: :string, desc: "New content (HTML). Use {{@Name}} to mention users"
       option :status, type: :string, enum: %w[resolved open orphaned], desc: "Status"
       # Update an existing reply's content or status.
       #

data/lib/superthread/cli/search.rb

@@ -7,6 +7,7 @@ module Superthread
       desc "query SEARCH_TERM", "Search across workspace"
       option :field, type: :string, enum: %w[title content], desc: "Field to search in"
       option :types, type: :string, desc: "Entity types to search (comma-separated: board,card,page,project,epic,note)"
+      option :status, type: :string, desc: "Status filter (comma-separated, e.g., open,started)"
       option :space, type: :string, aliases: "-s", desc: "Space to filter by (ID or name)"
       option :include_archived, type: :boolean, desc: "Include archived items"
       option :grouped, type: :boolean, desc: "Group results by type"
@@ -17,18 +18,32 @@ module Superthread
       def query(search_term)
         handle_error do
           types = options[:types]&.split(",")&.map(&:strip)
+          statuses = options[:status]&.split(",")&.map(&:strip)
           results = client.search.query(
             workspace_id,
             query: search_term,
             field: options[:field],
             types: types,
-            space_id: space_id,
+            statuses: statuses,
+            space_id: (space_id if options[:space]),
             archived: options[:include_archived],
-            grouped: options[:grouped]
+            grouped: options[:grouped],
+            limit: effective_limit
           )
           output_list results, columns: %i[result_type id title], headers: {id: "ID"}
         end
       end
+
+      private
+
+      # Override Base#effective_limit for search-specific defaults.
+      #
+      # @return [Integer, nil] the limit (nil = unlimited when --limit 0)
+      def effective_limit
+        limit = options[:limit]
+        return nil if limit == 0
+        (limit.is_a?(Integer) && limit > 0) ? limit : 30
+      end
     end
   end
 end

data/lib/superthread/connection.rb

@@ -34,7 +34,7 @@ module Superthread
       @connection.send(method) do |req|
         req.url(relative_path)
         req.params = params if params
-        req.body = body.to_json if body
+        req.body = body.to_json.encode(Encoding::UTF_8) if body
       end
     end
 

data/lib/superthread/mention_formatter.rb

@@ -30,6 +30,8 @@ module Superthread
     ESCAPE_PATTERN = /\\\{\{@([^}]+)\}\}/
     # @return [Regexp] pattern matching placeholders used during escape processing
     PLACEHOLDER_PATTERN = /___ESCAPED_MENTION_(.+?)___END___/
+    # @return [Regexp] pattern matching raw HTML mention tags that should use {{@Name}} syntax
+    HTML_MENTION_PATTERN = /<(?:user-mention|mention-user)\b/i
 
     # @param client [Superthread::Client] the API client for fetching members
     # @param workspace_id [String] the workspace to look up members in
@@ -43,6 +45,7 @@ module Superthread
     # @param content [String, nil] text that may contain {{@Name}} patterns
     # @return [String, nil] content with mentions converted to HTML tags
     def format(content)
+      warn_html_mentions(content) if content
       return content if content.nil? || !content.include?("{{@")
 
       member_map = build_member_map
@@ -54,6 +57,7 @@ module Superthread
       result = content.gsub(ESCAPE_PATTERN, '___ESCAPED_MENTION_\1___END___')
 
       # Pass 2: replace {{@Name}} with HTML tags
+      unresolved = []
       result = result.gsub(MENTION_PATTERN) do |match|
         name = Regexp.last_match(1).strip
         member = member_map[name.downcase]
@@ -67,16 +71,34 @@ module Superthread
             "user-value=\"#{safe_name}\" " \
             'denotation-char="@"></user-mention>'
         else
+          unresolved << name
           match
         end
       end
 
+      unresolved.each do |name|
+        warn "Warning: Could not resolve mention: #{name}. " \
+          "Check the display name matches a workspace member."
+      end
+
       # Pass 3: restore escaped mentions as literal {{@Name}} text
       result.gsub(PLACEHOLDER_PATTERN, '{{@\1}}')
     end
 
     private
 
+    # Warns when content contains raw HTML mention tags instead of {{@Name}} syntax.
+    #
+    # @param content [String] text to check for raw HTML mention tags
+    # @return [void]
+    def warn_html_mentions(content)
+      return unless content.match?(HTML_MENTION_PATTERN)
+
+      warn "Warning: Raw HTML mention tags detected in content. " \
+        "Use {{@Name}} syntax to mention users " \
+        "(e.g., '{{@Steve Clarke}} check this')."
+    end
+
     # Fetches workspace members and builds a case-insensitive lookup map.
     #
     # @return [Hash{String => Hash}, nil] map of lowercase names to {id:, name:}, or nil on failure

data/lib/superthread/models/checklist.rb

@@ -57,6 +57,13 @@ module Superthread
 
       timestamps :time_created, :time_updated
 
+      # Items sorted by position.
+      #
+      # @return [Array<ChecklistItem>] items in position order
+      def sorted_items
+        (items || []).sort_by { |i| i.position || 0 }
+      end
+
       # Count of completed items.
       #
       # @return [Integer] Number of checked items

data/lib/superthread/models/checklist_item.rb

@@ -41,6 +41,10 @@ module Superthread
       #   @return [Boolean] whether this item is checked/completed
       attribute :checked, Shale::Type::Boolean
 
+      # @!attribute [rw] position
+      #   @return [Integer] position within the checklist for ordering
+      attribute :position, Shale::Type::Integer
+
       # @!attribute [rw] time_created
       #   @return [Integer] Unix timestamp when the item was created
       attribute :time_created, Shale::Type::Integer

data/lib/superthread/resources/search.rb

@@ -7,10 +7,17 @@ module Superthread
     # Provides methods for searching across workspace entities
     # (cards, pages, boards, etc.) via the Superthread API.
     class Search < Base
+      # Safety cap on pagination requests to prevent runaway loops.
+      MAX_PAGES = 100
+
       # Searches across workspace entities.
       #
+      # Follows pagination cursors automatically. When limit is provided,
+      # stops after accumulating that many results.
+      #
       # @param workspace_id [String] the workspace identifier
       # @param query [String] the search query string
+      # @param limit [Integer, nil] max results to return (nil = no limit)
       # @param params [Hash{Symbol => Object}] optional search parameters
       # @option params [String] :field the field to search (title, content)
       # @option params [Array<String>] :types entity types to include (board, card, page, etc.)
@@ -18,28 +25,39 @@ module Superthread
       # @option params [String] :space_id the space identifier to filter by
       # @option params [Boolean] :archived when true, includes archived entities
       # @option params [Boolean] :grouped when true, groups results by type (default: false)
-      # @option params [String] :cursor the pagination cursor for next page
       # @return [Superthread::Objects::Collection] the search results
-      def query(workspace_id, query:, **params)
+      def query(workspace_id, query:, limit: nil, **params)
         ws = safe_id("workspace_id", workspace_id)
-        # Default grouped to false so results come in a flat array
-        # Use || instead of fetch because CLI may pass grouped: nil explicitly
-        grouped = params[:grouped].nil? ? false : params[:grouped]
-        search_params = compact_params(
-          query: query,
-          project_id: params[:space_id],
-          grouped: grouped,
-          **params.except(:space_id, :grouped)
-        )
-        response = http_get("/#{ws}/search", params: search_params)
+        grouped = params.fetch(:grouped, false)
+        all_results = []
+        cursor = nil
+        pages = 0
+
+        loop do
+          search_params = compact_params(
+            query: query,
+            project_id: params[:space_id],
+            grouped: grouped,
+            cursor: cursor,
+            **params.except(:space_id, :grouped)
+          )
+          response = http_get("/#{ws}/search", params: search_params)
+
+          results = (response[:results] || []).map do |item|
+            result_type, data = item.first
+            data.merge(result_type: result_type.to_s)
+          end
+          all_results.concat(results)
 
-        # Unwrap results - each item is {"card": {...}} or {"board": {...}}, etc.
-        results = (response[:results] || []).map do |item|
-          result_type, data = item.first
-          data.merge(result_type: result_type.to_s)
+          cursor = response[:cursor]
+          pages += 1
+          break if cursor.nil? || cursor.empty?
+          break if limit && all_results.size >= limit
+          break if pages >= MAX_PAGES
         end
 
-        Objects::Collection.from_response(results)
+        all_results = all_results.first(limit) if limit
+        Objects::Collection.from_response(all_results)
       end
     end
   end

data/lib/superthread/version.rb

@@ -2,5 +2,5 @@
 
 module Superthread
   # Current version of the Superthread gem.
-  VERSION = "0.7.3"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superthread
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Steve Clarke