superthread 0.7.2

data/lib/superthread/cli/ui.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "glamour"
+require "gum"
+require "reverse_markdown"
+require_relative "ui/gum_prompt"
+require_relative "ui/plain_prompt"
+
+module Superthread
+  module Cli
+    # Terminal UI helpers using Gum for styled output.
+    # Provides consistent styling across all CLI commands.
+    #
+    # Interactive prompts delegate to a prompt backend selected based on
+    # terminal capabilities. Terminals with limited ANSI support (e.g.,
+    # macOS Terminal.app) use {PlainPrompt}; all others use {GumPrompt}.
+    #
+    # @example
+    #   Ui.header("Cards")
+    #   Ui.success("Card created")
+    #   Ui.table(rows, columns: ["ID", "Title", "Status"])
+    module Ui
+      # Brand color - purple
+      PRIMARY = "#7D56F4"
+
+      module_function
+
+      # Returns the prompt backend for interactive widgets.
+      #
+      # Uses {PlainPrompt} for terminals with limited ANSI support,
+      # otherwise {GumPrompt}.
+      #
+      # @return [Module] the prompt backend (PlainPrompt or GumPrompt)
+      def prompt
+        @prompt ||= plain_mode? ? PlainPrompt : GumPrompt
+      end
+
+      # Resets the cached prompt backend.
+      #
+      # Useful for testing when environment variables change mid-process.
+      #
+      # @return [void]
+      def reset_prompt!
+        @prompt = nil
+      end
+
+      # Whether to use plain Ruby I/O instead of gum interactive widgets.
+      #
+      # Detects Terminal.app (which renders gum's ANSI redraws incorrectly)
+      # and respects the SUPERTHREAD_PLAIN env var as a manual override.
+      #
+      # @return [Boolean] true if interactive widgets should use plain fallbacks
+      def plain_mode?
+        return true if ENV["SUPERTHREAD_PLAIN"]
+
+        ENV["TERM_PROGRAM"] == "Apple_Terminal"
+      end
+
+      # ========================================
+      # Output methods (always use Gum.style)
+      # ========================================
+
+      # Display a styled header with rounded border in brand color.
+      #
+      # @param text [String] the header title to display
+      def header(text)
+        puts Gum.style(
+          text,
+          foreground: PRIMARY,
+          bold: true,
+          border: :rounded,
+          border_foreground: PRIMARY,
+          padding: "0 2"
+        )
+      end
+
+      # Display a section title in bold brand color without border.
+      #
+      # @param text [String] the section title to display
+      def section(text)
+        puts Gum.style(text, foreground: PRIMARY, bold: true)
+      end
+
+      # Display a success message with green checkmark prefix.
+      #
+      # @param text [String] the success message to display
+      def success(text)
+        puts Gum.style("✓ #{text}", foreground: "green", bold: true)
+      end
+
+      # Display an error message with red X prefix.
+      #
+      # @param text [String] the error message to display
+      def error(text)
+        puts Gum.style("✗ #{text}", foreground: "red", bold: true)
+      end
+
+      # Display a warning message with yellow exclamation prefix.
+      #
+      # @param text [String] the warning message to display
+      def warning(text)
+        puts Gum.style("! #{text}", foreground: "yellow", bold: true)
+      end
+
+      # Display muted text with faint styling for secondary information.
+      #
+      # @param text [String] the text to display in faint/dim style
+      def muted(text)
+        puts Gum.style(text, faint: true)
+      end
+
+      # Display informational text in brand purple color.
+      #
+      # @param text [String] the informational message to display
+      def info(text)
+        puts Gum.style(text, foreground: PRIMARY)
+      end
+
+      # Display a key-value pair with styled label.
+      #
+      # @param key [String] the label name to display in brand color
+      # @param value [String] the value to display after the label
+      def kv(key, value)
+        label = Gum.style("#{key}:", foreground: PRIMARY, bold: true)
+        puts "#{label} #{value}"
+      end
+
+      # Display a styled table using gum with rounded borders.
+      #
+      # @param rows [Array<Array>] the table data as an array of row arrays
+      # @param columns [Array<String>] the column header labels
+      # @note Requires a TTY. For non-interactive output, use Formatter.table instead.
+      def table(rows, columns:)
+        return if rows.empty?
+
+        Gum.table(
+          rows,
+          columns: columns,
+          print: true,
+          border: :rounded,
+          header_foreground: PRIMARY
+        )
+        puts ""
+      end
+
+      # Display a blank line for visual spacing between sections.
+      #
+      # @return [void]
+      def blank
+        puts ""
+      end
+
+      # Display a horizontal divider line for visual separation.
+      #
+      # @return [void]
+      def divider
+        puts Gum.style("─" * 40, faint: true)
+      end
+
+      # Format a numeric amount as currency with negative values in red.
+      #
+      # @param amount [Numeric] the monetary amount to format
+      # @return [String] the formatted currency string (e.g., "$12.50" or "-$5.00")
+      def money(amount)
+        formatted = format("$%.2f", amount.abs)
+        if amount.negative?
+          Gum.style("-#{formatted}", foreground: "red")
+        else
+          formatted
+        end
+      end
+
+      # ========================================
+      # Interactive methods (delegate to prompt)
+      # ========================================
+
+      # Prompt user for yes/no confirmation.
+      #
+      # @param question [String] the confirmation question to display
+      # @param default [Boolean] the default answer if user presses enter
+      # @return [Boolean] true if confirmed, false if declined
+      def confirm(question, default: true)
+        prompt.confirm(question, default: default)
+      end
+
+      # Prompt user for single-line text input.
+      #
+      # @param prompt_text [String] the prompt label shown before the input field
+      # @param placeholder [String, nil] the placeholder hint shown in empty field
+      # @return [String] the text entered by the user
+      def input(prompt_text, placeholder: nil)
+        prompt_text = "#{prompt_text} " unless prompt_text.end_with?(" ")
+        prompt.input(prompt_text, placeholder: placeholder)
+      end
+
+      # Prompt user for password input with hidden characters.
+      #
+      # @param prompt_text [String] the prompt label shown before the input field
+      # @return [String] the password entered by the user (not echoed to screen)
+      def password(prompt_text)
+        prompt_text = "#{prompt_text} " unless prompt_text.end_with?(" ")
+        prompt.password(prompt_text)
+      end
+
+      # Prompt user to choose a single item from a list with arrow keys.
+      #
+      # @param items [Array<String>] the options to choose from
+      # @param header [String, nil] the optional header text above the list
+      # @return [String] the selected item string
+      def choose(items, header: nil)
+        prompt.choose(items, header: header)
+      end
+
+      # Prompt user to filter and select from a list with fuzzy search.
+      #
+      # Falls back to numbered list selection in plain mode.
+      #
+      # @param items [Array<String>] the items available for filtering
+      # @param placeholder [String, nil] the placeholder hint for the search input
+      # @return [String] the selected item after filtering
+      def filter(items, placeholder: nil)
+        prompt.filter(items, placeholder: placeholder)
+      end
+
+      # Show an animated spinner while executing a block.
+      #
+      # In plain mode, prints a status line without animation.
+      #
+      # @param title [String] the status message shown next to the spinner
+      # @param block [Proc] the block to execute while the spinner is displayed
+      # @yieldreturn [Object] the result of the long-running operation
+      # @return [Object] the return value of the block
+      def spin(title, &block)
+        prompt.spin(title, &block)
+      end
+
+      # Render HTML or Markdown content with terminal-friendly styling.
+      #
+      # Converts HTML to Markdown first if needed, then renders with glamour
+      # for syntax highlighting and formatting.
+      #
+      # @param content [String] the HTML or Markdown content to render
+      # @param width [Integer] the word wrap width in characters
+      # @return [String] the styled content suitable for terminal display
+      def render_markdown(content, width: 80)
+        return "" if content.nil? || content.empty?
+
+        # Convert HTML to Markdown if it looks like HTML
+        markdown = if content.include?("<") && content.include?(">")
+          ReverseMarkdown.convert(content, unknown_tags: :bypass)
+        else
+          content
+        end
+
+        # Render with glamour
+        Glamour.render(markdown, width: width, style: "auto")
+      rescue
+        # Fall back to plain text if rendering fails
+        content
+      end
+    end
+  end
+end

data/lib/superthread/cli/workspaces.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for workspace management within the current account.
+    class Workspaces < Base
+      desc "list", "List available workspaces for current account"
+      # Lists all workspaces available to the current account.
+      #
+      # @return [void]
+      def list
+        user = client.users.me
+        teams = extract_teams(user)
+
+        if teams.empty?
+          say "No workspaces found"
+          return
+        end
+
+        cfg = Superthread::Configuration.new
+        current = cfg.workspace
+
+        say "WORKSPACES"
+        teams.each do |team|
+          marker = (team[:id] == current) ? "*" : " "
+          role = team[:role] || "member"
+          say "  #{marker} #{team[:id].to_s.ljust(20)} #{team[:name].to_s.ljust(25)} #{role}"
+        end
+        say ""
+        say "Use 'suth workspaces use <ID>' to set default workspace."
+      end
+
+      desc "use WORKSPACE", "Set default workspace for current account"
+      # Sets the default workspace for the current account.
+      #
+      # @param workspace_ref [String] workspace ID or name to switch to
+      # @return [void]
+      def use(workspace_ref)
+        handle_error do
+          cfg = Superthread::Configuration.new
+
+          unless cfg.current_account
+            Ui.error "No account selected"
+            Ui.muted "Run 'suth setup' to configure an account first"
+            return
+          end
+
+          # Fetch workspaces and resolve the reference
+          user = client.users.me
+          teams = extract_teams(user)
+
+          workspace = teams.find { |t| t[:id] == workspace_ref || t[:name] == workspace_ref }
+
+          unless workspace
+            Ui.error "Workspace '#{workspace_ref}' not found"
+            Ui.muted "Available workspaces:"
+            teams.each { |t| Ui.muted "  #{t[:id]} - #{t[:name]}" }
+            return
+          end
+
+          cfg.save_account_state(cfg.current_account,
+            workspace_id: workspace[:id],
+            workspace_name: workspace[:name])
+
+          output_success "Default workspace set to: #{workspace[:name]} (#{workspace[:id]})"
+        end
+      end
+
+      desc "current", "Show current default workspace"
+      # Displays the currently selected default workspace.
+      #
+      # @return [void]
+      def current
+        cfg = Superthread::Configuration.new
+
+        if cfg.workspace
+          say "Current workspace: #{cfg.workspace}"
+          say_info "Account: #{cfg.current_account}" if cfg.current_account
+        else
+          say "No default workspace set"
+          say_info "Use 'suth workspaces list' to see available workspaces"
+          say_info "Use 'suth workspaces use <ID>' to set a default"
+        end
+      end
+
+      private
+
+      # Extract team/workspace information from a user object.
+      #
+      # @param user [Superthread::Models::User] the user object with teams data
+      # @return [Array<Hash{Symbol => String}>] array of workspace hashes with :id, :name, :role
+      def extract_teams(user)
+        return [] unless user.teams
+
+        user.teams.map do |team|
+          {
+            id: team.id,
+            name: team.team_name || "Unknown",
+            role: team.role
+          }
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Superthread
+  # Command-line interface for Superthread project management.
+  # Provides Thor-based commands for managing cards, boards, projects, and more.
+  module Cli
+    # Error raised when a CLI command fails.
+    class CommandError < Superthread::Error; end
+  end
+end

data/lib/superthread/client.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Superthread
+  # HTTP client for the Superthread API.
+  #
+  # Provides access to all API resources through typed accessors.
+  # Handles authentication, request signing, and response parsing.
+  #
+  # @example Creating a client
+  #   client = Superthread::Client.new(api_key: "sk_...")
+  #   cards = client.cards.list(workspace_id)
+  #   card = client.cards.find(workspace_id, card_id)
+  #
+  # @example Using environment configuration
+  #   # Uses SUPERTHREAD_API_KEY and config files
+  #   client = Superthread::Client.new
+  class Client
+    # @return [Superthread::Resources::Users] users resource
+    # @return [Superthread::Resources::Projects] projects resource
+    # @return [Superthread::Resources::Spaces] spaces resource
+    # @return [Superthread::Resources::Boards] boards resource
+    # @return [Superthread::Resources::Cards] cards resource
+    # @return [Superthread::Resources::Comments] comments resource
+    # @return [Superthread::Resources::Pages] pages resource
+    # @return [Superthread::Resources::Notes] notes resource
+    # @return [Superthread::Resources::Sprints] sprints resource
+    # @return [Superthread::Resources::Search] search resource
+    # @return [Superthread::Resources::Tags] tags resource
+    attr_reader :users, :projects, :spaces, :boards, :cards,
+      :comments, :pages, :notes, :sprints, :search, :tags
+
+    # @return [Faraday::Response, nil] the last HTTP response received
+    attr_reader :last_response
+
+    # Creates a new API client.
+    #
+    # @param api_key [String, nil] API key (overrides config file and environment)
+    # @param base_url [String, nil] custom API base URL
+    # @param workspace [String, nil] default workspace ID
+    # @raise [ConfigurationError] if no valid API key is available
+    def initialize(api_key: nil, base_url: nil, workspace: nil)
+      @config = build_config(api_key, base_url, workspace)
+      @config.validate!
+      @connection = Superthread::Connection.new(@config)
+
+      # Initialize resource accessors
+      @users = Superthread::Resources::Users.new(self)
+      @projects = Superthread::Resources::Projects.new(self)
+      @spaces = Superthread::Resources::Spaces.new(self)
+      @boards = Superthread::Resources::Boards.new(self)
+      @cards = Superthread::Resources::Cards.new(self)
+      @comments = Superthread::Resources::Comments.new(self)
+      @pages = Superthread::Resources::Pages.new(self)
+      @notes = Superthread::Resources::Notes.new(self)
+      @sprints = Superthread::Resources::Sprints.new(self)
+      @search = Superthread::Resources::Search.new(self)
+      @tags = Superthread::Resources::Tags.new(self)
+    end
+
+    # Returns the resolved default workspace ID.
+    #
+    # @return [String, nil] workspace ID from configuration
+    def default_workspace
+      @config.workspace
+    end
+
+    # Makes an API request and returns raw hash data.
+    #
+    # Use this when you need the raw response before object conversion.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :delete)
+    # @param path [String] API endpoint path relative to base URL (e.g., "/cards/123")
+    # @param params [Hash{Symbol => Object}, nil] query parameters to include
+    # @param body [Hash{Symbol => Object}, nil] request body to send as JSON
+    # @return [Hash{Symbol => Object}] parsed JSON response
+    # @raise [Superthread::ApiError] if the request fails
+    def request(method:, path:, params: nil, body: nil)
+      response = @connection.request(method: method, path: path, params: params, body: body)
+      @last_response = response
+      handle_response(response)
+    end
+
+    # Makes an API request and returns a typed object.
+    #
+    # This is the primary method used by resource classes.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :delete)
+    # @param path [String] API endpoint path relative to base URL
+    # @param params [Hash{Symbol => Object}, nil] query parameters to include
+    # @param body [Hash{Symbol => Object}, nil] request body to send as JSON
+    # @param object_class [Class, nil] class to instantiate for the response
+    # @param unwrap_key [Symbol, nil] key to unwrap from response (e.g., :card extracts response[:card])
+    # @return [Superthread::Object, Superthread::Model] response wrapped in appropriate object class
+    # @raise [Superthread::ApiError] if the request fails
+    def request_object(method:, path:, params: nil, body: nil, object_class: nil, unwrap_key: nil)
+      data = request(method: method, path: path, params: params, body: body)
+      convert_to_object(data, object_class: object_class, unwrap_key: unwrap_key)
+    end
+
+    # Makes an API request and returns a collection of objects.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :delete)
+    # @param path [String] API endpoint path relative to base URL
+    # @param params [Hash{Symbol => Object}, nil] query parameters to include
+    # @param body [Hash{Symbol => Object}, nil] request body to send as JSON
+    # @param item_class [Class, nil] class to instantiate for each item
+    # @param items_key [Symbol, nil] key containing the items array (auto-detected if nil)
+    # @return [Superthread::Objects::Collection] collection of objects
+    # @raise [Superthread::ApiError] if the request fails
+    def request_collection(method:, path:, params: nil, body: nil, item_class: nil, items_key: nil)
+      data = request(method: method, path: path, params: params, body: body)
+      Superthread::Objects::Collection.from_response(data, key: items_key, item_class: item_class)
+    end
+
+    # Converts raw hash data to a typed object.
+    #
+    # @param data [Hash{Symbol => Object}, Array<Hash>] raw response data
+    # @param object_class [Class, nil] class to instantiate
+    # @param unwrap_key [Symbol, nil] key to unwrap from response
+    # @return [Superthread::Object, Superthread::Model, Array, Object] converted object(s)
+    def convert_to_object(data, object_class: nil, unwrap_key: nil)
+      # Unwrap nested response (e.g., { card: { ... } } -> { ... })
+      data = data[unwrap_key] if unwrap_key && data.is_a?(Hash) && data.key?(unwrap_key)
+
+      if object_class
+        # Use Shale's from_response for Model subclasses
+        if shale_model?(object_class)
+          case data
+          when Array
+            object_class.from_response_array(data)
+          when Hash
+            object_class.from_response(data)
+          else
+            data
+          end
+        else
+          # Legacy Superthread::Object pattern
+          case data
+          when Array
+            data.map { |item| object_class.new(item) }
+          when Hash
+            object_class.new(data)
+          else
+            data
+          end
+        end
+      else
+        Superthread::Object.construct_from(data)
+      end
+    end
+
+    # Checks if a class is a Shale-based Model.
+    #
+    # @param klass [Class] the class to check
+    # @return [Boolean] true if the class is a Shale model
+    def shale_model?(klass)
+      Superthread::Model.shale_class?(klass)
+    end
+
+    private
+
+    # Builds a configuration object with optional overrides.
+    #
+    # @param api_key [String, nil] API key override
+    # @param base_url [String, nil] base URL override
+    # @param workspace [String, nil] workspace ID override
+    # @return [Superthread::Configuration] the configured configuration object
+    def build_config(api_key, base_url, workspace)
+      config = Superthread::Configuration.new
+      config.api_key = api_key if api_key
+      config.base_url = base_url if base_url
+      config.workspace = workspace if workspace
+      config
+    end
+
+    # Handles an HTTP response, parsing success or raising on error.
+    #
+    # @param response [Faraday::Response] the HTTP response object
+    # @return [Hash{Symbol => Object}] parsed response body
+    # @raise [Superthread::ApiError] if response status indicates failure
+    def handle_response(response)
+      case response.status
+      when 200..299
+        parse_response(response)
+      else
+        raise Superthread::ApiError.from_response(response)
+      end
+    end
+
+    # Parses a successful HTTP response body as JSON.
+    #
+    # @param response [Faraday::Response] the HTTP response object
+    # @return [Hash{Symbol => Object}] parsed JSON with symbol keys
+    def parse_response(response)
+      return {success: true} if response.status == 204
+
+      body = response.body.to_s
+      return {success: true} if body.empty?
+
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      {success: true}
+    end
+  end
+end