superthread 0.7.4 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ff6a32a6f48d0010c39659ee7fca19ff5d136ad8ffdb236a9e44e32108b65c2
-  data.tar.gz: d22ea63399a42dbbb6f79e02ccbb5983ac732c981bfa38af16756a775c037185
+  metadata.gz: 05edf5da03e7cda08cca6e16f9813bb8f464b7847f3717a669eeb69802a67208
+  data.tar.gz: bdb2593ece548e526dfd602ca061e40541d09a062b633919133bf5ab6cc672c7
 SHA512:
-  metadata.gz: da133f0ba26e4f5b4b16cac769408133f4cf143965948efb5d933d3cecf32ea478891fc9a1fa93dc590b80acc1be46d30aa3611e6d951c9c636abb5a566a59e2
-  data.tar.gz: c3dfc65b6e9927a9112a33194258c73b239a3238e3446dcba9b929a5b15281d06398d26c86b27dc714a9a9378ff0455280295d33154a4f119628a6a04dfa1208
+  metadata.gz: 7800b583a4a5b07062e460c1b053e593b3c344037d0a6dbf84e576097be4dfdb67594d61f021eaf46aa1bf9ec6b16b93ce5c9c31633331dfa5ef13b1742e82f6
+  data.tar.gz: 0d547f6b5c884715da432f8fdfa68593435f85c20cd06786c0f6594f33381ee661f30058c86912595124d3b113fd91978861146e578c3bf8513213d5cd33e269

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"
@@ -127,7 +173,7 @@ module Superthread
       option :board, type: :string, aliases: "-b", desc: "Board (ID or name, required unless --sprint)"
       option :space, type: :string, aliases: "-s", desc: "Space (required for --sprint, helps resolve board name)"
       option :sprint, type: :string, desc: "Sprint (ID or name, required unless --board)"
-      option :content, type: :string, desc: "Card content (HTML)"
+      option :content, type: :string, desc: "Card content (HTML). Use {{@Name}} to mention users"
       option :project, type: :string, desc: "Project ID"
       option :start_date, type: :numeric, desc: "Start date (Unix timestamp)"
       option :due_date, type: :numeric, desc: "Due date (Unix timestamp)"
@@ -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
@@ -116,7 +116,7 @@ module Superthread
 
       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 :title, type: :string, required: true, desc: "Item title. Use {{@Name}} to mention users"
       option :checked, type: :boolean, default: false, desc: "Create as checked"
       # Add a new item to an existing checklist.
       #
@@ -139,7 +139,7 @@ module Superthread
       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 :title, type: :string, desc: "New item title. Use {{@Name}} to mention users"
       option :checked, type: :boolean, desc: "Mark as checked/unchecked"
       # Update the title or checked state of a checklist item.
       #
@@ -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/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

@@ -32,6 +32,8 @@ module Superthread
     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
+    # @return [Regexp] pattern matching plain @Word that is not inside {{@...}} delimiters
+    PLAIN_MENTION_PATTERN = /(?<!\{\{)@(\w+)/
 
     # @param client [Superthread::Client] the API client for fetching members
     # @param workspace_id [String] the workspace to look up members in
@@ -46,6 +48,7 @@ module Superthread
     # @return [String, nil] content with mentions converted to HTML tags
     def format(content)
       warn_html_mentions(content) if content
+      warn_plain_mentions(content) if content
       return content if content.nil? || !content.include?("{{@")
 
       member_map = build_member_map
@@ -99,6 +102,36 @@ module Superthread
         "(e.g., '{{@Steve Clarke}} check this')."
     end
 
+    # Warns when content contains plain @Name mentions that match workspace members.
+    # This catches the common mistake of using @Name instead of {{@Name}}.
+    #
+    # @param content [String] text to check for plain @mentions
+    # @return [void]
+    def warn_plain_mentions(content)
+      return if content.include?("{{@")
+
+      names = content.scan(PLAIN_MENTION_PATTERN).flatten
+      return if names.empty?
+
+      member_map = build_member_map
+      return if member_map.nil?
+
+      # Also index by first name for multi-word display names
+      first_name_map = {}
+      member_map.each_value do |info|
+        first = info[:name].split.first&.downcase
+        first_name_map[first] = info[:name] if first
+      end
+
+      names.each do |name|
+        match = member_map[name.downcase]&.fetch(:name) || first_name_map[name.downcase]
+        if match
+          warn "Warning: Found @#{name} — did you mean {{@#{match}}}? " \
+            "Use {{@Name}} syntax to mention users and trigger notifications."
+        end
+      end
+    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.4"
+  VERSION = "0.8.1"
 end

metadata

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