superthread 0.7.2

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    # Shared behavior modules for CLI commands.
+    module Concerns
+      # Provides confirmation prompts for destructive actions.
+      # Respects the --force flag to skip confirmation.
+      #
+      # @example
+      #   class Cards < Base
+      #     include Concerns::Confirmable
+      #
+      #     def delete(card_id)
+      #       handle_error do
+      #         confirming("Delete card #{card_id}?") do
+      #           client.cards.destroy(workspace_id, card_id)
+      #           Ui.success "Card #{card_id} deleted"
+      #         end
+      #       end
+      #     end
+      #   end
+      module Confirmable
+        extend ActiveSupport::Concern
+
+        # Execute a block with optional confirmation prompt.
+        #
+        # Skips confirmation if --force flag is set, otherwise prompts user.
+        #
+        # @param message [String] the confirmation question to display
+        # @yield the block to execute if user confirms
+        # @return [Object, nil] the block's return value, or nil if cancelled
+        def confirming(message)
+          if options[:force] || confirm_action(message)
+            yield
+          else
+            Ui.muted "Cancelled."
+          end
+        end
+
+        private
+
+        # Prompt user for yes/no confirmation via the UI.
+        #
+        # @param message [String] the confirmation question to display
+        # @return [Boolean] true if user confirms, false otherwise
+        def confirm_action(message)
+          Ui.confirm(message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Provides date parsing utilities for CLI commands.
+      # Parses natural language dates into Unix timestamps for API filtering.
+      #
+      # @example
+      #   class Cards < Base
+      #     include Concerns::DateParsable
+      #
+      #     def list
+      #       since_timestamp = parse_date(options[:since])
+      #       # Filter cards by since_timestamp...
+      #     end
+      #   end
+      module DateParsable
+        extend ActiveSupport::Concern
+
+        # Number of seconds in a day (24 hours).
+        SECONDS_PER_DAY = 86_400
+
+        # Number of seconds in a week (7 days).
+        SECONDS_PER_WEEK = 604_800
+
+        # Parse a date string into a Unix timestamp (seconds).
+        # Supports various natural language formats.
+        #
+        # @param date_string [String, nil] Date expression to parse
+        # @return [Integer, nil] Unix timestamp (seconds), or nil if no date provided
+        # @raise [Thor::Error] If date string is invalid or unparseable
+        #
+        # @example Natural language dates
+        #   parse_date("today")           # => Start of today
+        #   parse_date("yesterday")       # => Start of yesterday
+        #   parse_date("friday")          # => Last Friday (or this Friday if today is earlier)
+        #   parse_date("last friday")     # => Last Friday
+        #   parse_date("monday")          # => Last Monday
+        #   parse_date("3 days ago")      # => 3 days ago
+        #   parse_date("1 week ago")      # => 7 days ago
+        #   parse_date("2 weeks ago")     # => 14 days ago
+        #   parse_date("last week")       # => Start of last week
+        #   parse_date("this week")       # => Start of this week
+        #   parse_date("2026-01-20")      # => Specific date
+        def parse_date(date_string)
+          return nil if date_string.nil? || date_string.empty?
+
+          normalized = date_string.to_s.strip.downcase
+
+          time = case normalized
+          when "today", "now"
+            beginning_of_day(Date.today)
+          when "yesterday"
+            beginning_of_day(Date.today - 1)
+          when "this week"
+            beginning_of_week(Date.today)
+          when "last week"
+            beginning_of_week(Date.today - 7)
+          when /\A(\d+)\s+days?\s+ago\z/
+            beginning_of_day(Date.today - Integer(::Regexp.last_match(1)))
+          when /\A(\d+)\s+weeks?\s+ago\z/
+            beginning_of_day(Date.today - (Integer(::Regexp.last_match(1)) * 7))
+          when /\A(\d+)\s+months?\s+ago\z/
+            beginning_of_day(Date.today << Integer(::Regexp.last_match(1)))
+          when /\Alast\s+(#{day_names_pattern})\z/
+            parse_weekday(::Regexp.last_match(1), force_past: true)
+          when /\A(#{day_names_pattern})\z/
+            parse_weekday(::Regexp.last_match(1))
+          else
+            # Try parsing as a date (YYYY-MM-DD, MM/DD/YYYY, etc.)
+            parse_explicit_date(date_string)
+          end
+
+          time&.to_i
+        rescue ArgumentError, TypeError => e
+          raise Thor::Error, "Invalid date: '#{date_string}'. #{e.message}"
+        end
+
+        # Parse a date string into a Time object at end of day.
+        # Useful for "until" or "before" filters.
+        #
+        # @param date_string [String, nil] Date expression to parse
+        # @return [Integer, nil] Unix timestamp at end of day, or nil
+        def parse_date_end(date_string)
+          timestamp = parse_date(date_string)
+          return nil unless timestamp
+
+          # Add 23:59:59 to get end of day
+          timestamp + SECONDS_PER_DAY - 1
+        end
+
+        # Filter a collection of items by timestamp field.
+        # Used for client-side filtering when API doesn't support date filters.
+        #
+        # @param items [Enumerable] Collection to filter
+        # @param field [Symbol] Timestamp field name (e.g., :time_created, :time_updated)
+        # @param since [Integer, nil] Minimum timestamp (inclusive)
+        # @param until_time [Integer, nil] Maximum timestamp (inclusive)
+        # @return [Array] Filtered items
+        def filter_by_date(items, field:, since: nil, until_time: nil)
+          items.select do |item|
+            ts = item.send(field)
+            next false if ts.nil?
+
+            ts = Formatter.normalize_timestamp(ts)
+            next false if ts.nil?
+
+            (since.nil? || ts >= since) && (until_time.nil? || ts <= until_time)
+          end
+        end
+
+        private
+
+        # Convert Date to Time at beginning of day (midnight).
+        #
+        # @param date [Date] the date to convert
+        # @return [Time] midnight on the given date
+        def beginning_of_day(date)
+          Time.new(date.year, date.month, date.day, 0, 0, 0)
+        end
+
+        # Get the beginning of the week for a date (Monday).
+        #
+        # @param date [Date] the date to find the week start for
+        # @return [Time] midnight on Monday of the given date's week
+        def beginning_of_week(date)
+          # wday: 0=Sunday, 1=Monday, ... 6=Saturday
+          # We want Monday as start of week
+          days_since_monday = (date.wday - 1) % 7
+          beginning_of_day(date - days_since_monday)
+        end
+
+        # Pattern matching day names (full and abbreviated).
+        def day_names_pattern
+          "sunday|sun|monday|mon|tuesday|tue|tues|wednesday|wed|thursday|thu|thurs|friday|fri|saturday|sat"
+        end
+
+        # Parse a weekday name into a Time object.
+        #
+        # @param day_name [String] Day name (e.g., "friday", "mon")
+        # @param force_past [Boolean] Always return a date in the past
+        # @return [Time] Start of that day
+        def parse_weekday(day_name, force_past: false)
+          target_wday = weekday_number(day_name)
+          today = Date.today
+          current_wday = today.wday
+
+          # Calculate days back to the target weekday
+          if force_past || target_wday >= current_wday
+            # Need to go to last week's occurrence
+            days_back = (current_wday - target_wday + 7) % 7
+            days_back = 7 if days_back == 0 && force_past
+          else
+            # Target day is earlier this week
+            days_back = current_wday - target_wday
+          end
+
+          beginning_of_day(today - days_back)
+        end
+
+        # Convert day name to weekday number (0=Sunday, 6=Saturday).
+        #
+        # @param day_name [String] the day name (full or abbreviated)
+        # @return [Integer] weekday number where 0=Sunday and 6=Saturday
+        def weekday_number(day_name)
+          case day_name.downcase
+          when "sunday", "sun" then 0
+          when "monday", "mon" then 1
+          when "tuesday", "tue", "tues" then 2
+          when "wednesday", "wed" then 3
+          when "thursday", "thu", "thurs" then 4
+          when "friday", "fri" then 5
+          when "saturday", "sat" then 6
+          else
+            raise ArgumentError, "Unknown day: #{day_name}"
+          end
+        end
+
+        # Parse an explicit date string (YYYY-MM-DD, etc.).
+        #
+        # @param date_string [String] the date string in an explicit format
+        # @return [Time] midnight on the parsed date
+        def parse_explicit_date(date_string)
+          beginning_of_day(Date.parse(date_string))
+        rescue ArgumentError
+          raise Thor::Error,
+            "Could not parse date: '#{date_string}'. " \
+            "Try formats like '2026-01-20', 'friday', '3 days ago', or 'last week'."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves list references (ID or name) to list IDs.
+      #
+      # List resolution is context-dependent: it searches within the current
+      # board's lists or the current sprint's lists, depending on which
+      # option is provided.
+      module ListResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Resolve a list reference (ID or name) to its ID.
+        #
+        # @param ref [String, nil] the list ID or name to resolve
+        # @return [String, nil] the resolved list ID
+        # @raise [Thor::Error] if name is provided but not found
+        def resolve_list(ref)
+          return ref if ref.nil?
+          return ref if looks_like_id?(ref)
+
+          list = find_list_by_name(ref)
+          return list.id if list
+
+          raise Thor::Error, "List not found: '#{ref}'. Specify --board or --sprint to search by list name."
+        end
+
+        # Find a list by name within the current board or sprint context.
+        #
+        # @param name [String] the list name to search for (case-insensitive)
+        # @return [Superthread::Models::List, nil] the list object or nil if not found
+        def find_list_by_name(name)
+          lists = if options[:board]
+            board = client.boards.find(workspace_id, board_id)
+            board.lists
+          elsif options[:sprint]
+            sprint = client.sprints.find(workspace_id, sprint_id, space_id: space_id)
+            sprint.lists
+          end
+
+          return nil unless lists
+
+          lists.find { |l| l.title&.downcase == name.downcase }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves space references (ID or name) to space IDs.
+      #
+      # Space resolution tries name lookup first, then falls back to treating
+      # the reference as a direct ID. The spaces list is cached per command
+      # invocation.
+      module SpaceResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Get the space ID from --space option, resolving name if needed.
+        #
+        # @return [String, nil] the resolved space ID, or nil if not specified
+        def space_id
+          resolve_space(options[:space])
+        end
+
+        # Resolve a space reference (ID or name) to its ID.
+        #
+        # @param ref [String, nil] the space ID or name to resolve
+        # @return [String, nil] the resolved space ID
+        # @raise [Thor::Error] if name is provided but not found
+        def resolve_space(ref)
+          return ref if ref.nil?
+
+          # Try name resolution first, then fall back to assuming it's an ID
+          space = find_space_by_name(ref)
+          return space.id if space
+
+          # Assume it's an ID if name lookup failed
+          ref
+        end
+
+        # Find a space by name from the cached list.
+        #
+        # @param name [String] the space name to search for (case-insensitive)
+        # @return [Superthread::Models::Space, nil] the space object or nil if not found
+        def find_space_by_name(name)
+          @spaces_cache ||= client.spaces.list(workspace_id)
+          @spaces_cache.find { |s| s.title&.downcase == name.downcase }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves sprint references (ID or name) to sprint IDs.
+      #
+      # Sprint resolution requires a --space context for name lookups,
+      # since sprints belong to spaces.
+      module SprintResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Get the sprint ID from --sprint option, resolving name if needed.
+        #
+        # @return [String, nil] the resolved sprint ID, or nil if not specified
+        def sprint_id
+          resolve_sprint(options[:sprint])
+        end
+
+        # Resolve a sprint reference (ID or name) to its ID.
+        #
+        # @param ref [String, nil] the sprint ID or name to resolve
+        # @return [String, nil] the resolved sprint ID
+        # @raise [Thor::Error] if name is provided but not found
+        def resolve_sprint(ref)
+          return ref if ref.nil?
+          return ref if looks_like_id?(ref)
+
+          sprint = find_sprint_by_name(ref)
+          return sprint.id if sprint
+
+          raise Thor::Error, "Sprint not found: '#{ref}'. Use 'suth sprints list -s <space>' to see available sprints."
+        end
+
+        # Find a sprint by name within the current space context.
+        #
+        # @param name [String] the sprint name to search for (case-insensitive)
+        # @return [Superthread::Models::Sprint, nil] the sprint object or nil if not found
+        # @raise [Thor::Error] if --space is not provided
+        def find_sprint_by_name(name)
+          unless options[:space]
+            raise Thor::Error, "--space is required to resolve sprint name '#{name}'"
+          end
+
+          @sprints_cache ||= client.sprints.list(workspace_id, space_id: space_id)
+          @sprints_cache.find { |s| s.title&.downcase == name.downcase }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves tag references (ID or name) to tag IDs.
+      #
+      # Tag names are often short alphanumeric strings (e.g., "bug", "feature")
+      # that would otherwise look like IDs, so name resolution is tried first.
+      module TagResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Resolve a tag reference (ID or name) to its ID.
+        #
+        # Tag names are often short alphanumeric strings (e.g., "bug", "feature")
+        # that would otherwise look like IDs, so we try name resolution first.
+        #
+        # @param ref [String, nil] the tag ID or name to resolve
+        # @return [String, nil] the resolved tag ID
+        # @raise [Thor::Error] if ref doesn't match a tag name and doesn't look like an ID
+        def resolve_tag(ref)
+          return ref if ref.nil?
+
+          # Try name resolution first (tags commonly have simple names)
+          tag = find_tag_by_name(ref)
+          return tag.id if tag
+
+          # If not found by name, assume it's an ID
+          return ref if looks_like_id?(ref)
+
+          raise Thor::Error, "Tag not found: '#{ref}'. Use 'suth tags list' to see available tags."
+        end
+
+        # Find a tag by name from the cached list.
+        #
+        # @param name [String] the tag name to search for (case-insensitive)
+        # @return [Superthread::Models::Tag, nil] the tag object or nil if not found
+        def find_tag_by_name(name)
+          @tags_cache ||= client.cards.tags(workspace_id, all: true)
+          @tags_cache.find { |t| t.name&.downcase == name.downcase }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves user references (ID, name, or email) to user identifiers.
+      #
+      # User resolution matches against display_name or email and returns
+      # the user_identifier (not the standard id field).
+      module UserResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Resolve a user reference (ID, name, or email) to their user identifier.
+        #
+        # @param ref [String, nil] the user ID, display name, or email to resolve
+        # @return [String, nil] the resolved user identifier
+        # @raise [Thor::Error] if name/email is provided but not found
+        def resolve_user(ref)
+          return ref if ref.nil?
+          return ref if looks_like_id?(ref)
+
+          user = find_user_by_name(ref)
+          return user.user_identifier if user
+
+          raise Thor::Error, "User not found: '#{ref}'. Use 'suth members list' to see available users."
+        end
+
+        # Get cached workspace members list.
+        #
+        # @return [Array<Superthread::Models::User>] all workspace members
+        def workspace_users
+          @users_cache ||= client.users.members(workspace_id)
+        end
+
+        # Find a user by display name or email from the cached member list.
+        #
+        # @param name [String] the display name or email to search for (case-insensitive)
+        # @return [Superthread::Models::User, nil] the user object or nil if not found
+        def find_user_by_name(name)
+          workspace_users.find do |u|
+            u.display_name&.downcase == name.downcase ||
+              u.email&.downcase == name.downcase
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Superthread
+  module Cli
+    module Concerns
+      # Resolves workspace references (ID or name) to workspace IDs.
+      #
+      # Workspace IDs have a distinct pattern (alphanumeric, starts with letter,
+      # 6-21 chars). Name resolution fetches the current user's teams via the
+      # API and matches by team_name.
+      module WorkspaceResolvable
+        extend ActiveSupport::Concern
+
+        private
+
+        # Get the current workspace ID from options, config, or raise error.
+        #
+        # @return [String] the resolved workspace ID
+        # @raise [Thor::Error] if no workspace is configured
+        def workspace_id
+          ws = options[:workspace] || client.default_workspace
+          return resolve_workspace(ws) if ws
+
+          raise Thor::Error,
+            "Workspace required. Use --workspace or set SUPERTHREAD_WORKSPACE_ID " \
+            "or add workspace to ~/.config/superthread/config.yaml"
+        end
+
+        # Resolve a workspace reference (ID or name) to its ID.
+        #
+        # @param ref [String, nil] the workspace ID or name to resolve
+        # @return [String, nil] the resolved workspace ID, or nil if ref is nil
+        def resolve_workspace(ref)
+          return ref if ref.nil?
+
+          # Workspace IDs look like: t4k7Wa2e (8 chars, alphanumeric, starts with letter)
+          # Skip resolution for ID-like values to avoid unnecessary API calls
+          return ref if looks_like_workspace_id?(ref)
+
+          # Try name resolution for name-like values
+          workspace = find_workspace_by_name(ref)
+          return workspace[:id] if workspace
+
+          # Fall back to treating it as an ID (might still work)
+          ref
+        end
+
+        # Check if a value looks like a workspace ID (alphanumeric, starts with letter).
+        #
+        # @param value [String] the value to check
+        # @return [Boolean] true if it matches workspace ID pattern
+        def looks_like_workspace_id?(value)
+          # Workspace IDs are typically 8 chars, start with a letter, alphanumeric
+          # Also accept test IDs like "test_workspace"
+          value.match?(/\A[a-zA-Z][a-zA-Z0-9_]{5,20}\z/)
+        end
+
+        # Find a workspace by name from the cached list.
+        #
+        # @param name [String] the workspace name to search for (case-insensitive)
+        # @return [Hash, nil] the workspace hash with :id and :name, or nil if not found
+        def find_workspace_by_name(name)
+          @workspaces_cache ||= extract_workspaces_from_user
+          @workspaces_cache.find { |w| w[:name]&.downcase == name.downcase }
+        end
+
+        # Extract workspace list from the current user's teams.
+        #
+        # @return [Array<Hash{Symbol => String}>] array of workspace hashes with :id and :name
+        def extract_workspaces_from_user
+          user = client.users.me
+          return [] unless user.teams
+
+          user.teams.map do |team|
+            {id: team.id, name: team.team_name}
+          end
+        end
+      end
+    end
+  end
+end