superthread 0.7.2

data/lib/superthread/cli/setup.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Superthread
+  module Cli
+    # Interactive setup wizard for first-time CLI configuration.
+    #
+    # Guides users through API key entry, workspace selection, and account setup.
+    # Handles both new installations and reconfiguration of existing accounts.
+    module Setup
+      module_function
+
+      # Run the interactive setup wizard.
+      #
+      # Walks the user through account naming, API key entry, workspace selection,
+      # and saves the configuration to disk.
+      #
+      # @return [void]
+      def execute
+        Ui.header "Superthread CLI Setup"
+        Ui.blank
+
+        config = Superthread::Configuration.new
+
+        # Step 1: Determine if adding new or reconfiguring
+        account_name = prompt_account_name(config)
+        return unless account_name
+
+        # Step 2: API Key
+        Ui.blank
+        api_key = prompt_api_key
+        return unless api_key
+
+        # Step 3: Validate and fetch workspaces
+        Ui.blank
+        workspaces = fetch_workspaces(api_key)
+        return unless workspaces
+
+        # Step 4: Select workspace (auto-selects if only one)
+        Ui.blank
+        workspace = select_workspace(workspaces)
+        return unless workspace
+
+        # Step 5: Save configuration
+        Ui.blank
+        save_account(config, account_name, api_key, workspace)
+
+        # Done!
+        Ui.blank
+        Ui.success "Setup complete!"
+        Ui.blank
+        Ui.muted "Account '#{account_name}' is now active."
+        Ui.blank
+        Ui.muted "Try: suth spaces list"
+        Ui.muted "     suth boards list --space SPACE_ID"
+        Ui.muted "     suth cards list --board BOARD_ID"
+        Ui.blank
+        Ui.muted "To add another account: suth account add <name>"
+        Ui.muted "To switch accounts:     suth account use <name>"
+      end
+
+      # Prompt for an account name, offering to add new or reconfigure existing.
+      #
+      # @param config [Superthread::Configuration] the current configuration instance
+      # @return [String, nil] the chosen account name, or nil if cancelled
+      def prompt_account_name(config)
+        Ui.section "Step 1: Account"
+
+        existing = config.accounts.keys.map(&:to_s)
+
+        # No existing accounts - first time setup
+        if existing.empty?
+          return prompt_new_account_name("personal")
+        end
+
+        # Show existing accounts
+        current = config.current_account
+        Ui.muted "Existing accounts: #{existing.map { |a| (a == current) ? "#{a} (current)" : a }.join(", ")}"
+        Ui.blank
+
+        # Let user choose what to do
+        choice = Ui.choose(
+          ["Add new account", "Reconfigure existing account"],
+          header: "What would you like to do?"
+        )
+        return nil if choice.nil?
+
+        Ui.blank
+
+        if choice.start_with?("Add")
+          # Suggest a name that doesn't exist
+          suggestion = %w[personal work].find { |n| !existing.include?(n) }
+          prompt_new_account_name(suggestion)
+        else
+          prompt_existing_account(existing)
+        end
+      end
+
+      # Prompt user to enter a name for a new account.
+      #
+      # @param suggestion [String, nil] a suggested default name if available
+      # @return [String, nil] the entered account name, or nil if empty
+      def prompt_new_account_name(suggestion)
+        prompt = if suggestion
+          "Account name (default: #{suggestion}):"
+        else
+          "Account name:"
+        end
+
+        input = Ui.input(prompt)
+        name = input&.strip
+        name = suggestion if name.nil? || name.empty?
+
+        if name.nil? || name.empty?
+          Ui.error "Account name is required"
+          return nil
+        end
+
+        name
+      end
+
+      # Prompt user to select an existing account to reconfigure.
+      #
+      # @param existing [Array<String>] list of existing account names
+      # @return [String, nil] the selected account name, or nil if cancelled
+      def prompt_existing_account(existing)
+        if existing.length == 1
+          name = existing.first
+          Ui.info "Reconfiguring account: #{name}"
+          return name
+        end
+
+        choice = Ui.choose(existing, header: "Select account to reconfigure:")
+        return nil if choice.nil?
+
+        choice
+      end
+
+      # Prompt user to enter their Superthread API key.
+      #
+      # @return [String, nil] the entered API key, or nil if empty
+      def prompt_api_key
+        Ui.section "Step 2: API Key"
+        Ui.muted "Get your API key from Superthread Settings > API"
+        Ui.blank
+
+        api_key = Ui.password("Enter your API key:")
+
+        if api_key.nil? || api_key.strip.empty?
+          Ui.error "API key is required"
+          return nil
+        end
+
+        api_key.strip
+      end
+
+      # Validate API key and fetch available workspaces from the server.
+      #
+      # @param api_key [String] the API key to authenticate with
+      # @return [Array<Hash{Symbol => String}>, nil] list of workspace hashes, or nil on error
+      def fetch_workspaces(api_key)
+        Ui.section "Step 3: Connecting..."
+
+        workspaces = Ui.spin("Fetching workspaces...") do
+          temp_client = Superthread::Client.new(api_key: api_key)
+          user = temp_client.users.me
+          extract_teams(user)
+        end
+
+        if workspaces.empty?
+          Ui.error "No workspaces found for this API key"
+          return nil
+        end
+
+        Ui.success "Found #{workspaces.length} workspace(s)"
+        workspaces
+      rescue Superthread::AuthenticationError
+        Ui.error "Invalid API key"
+        nil
+      rescue Superthread::ApiError => e
+        Ui.error "API error: #{e.message}"
+        nil
+      end
+
+      # Prompt user to select a workspace from the available options.
+      #
+      # Auto-selects if only one workspace is available.
+      #
+      # @param workspaces [Array<Hash{Symbol => String}>] list of workspace hashes with :id and :name
+      # @return [Hash{Symbol => String}, nil] the selected workspace, or nil if cancelled
+      def select_workspace(workspaces)
+        Ui.section "Step 4: Select Workspace"
+        Ui.blank
+
+        if workspaces.length == 1
+          ws = workspaces.first
+          Ui.info "Using workspace: #{ws[:name]}"
+          return ws
+        end
+
+        choices = workspaces.map { |ws| "#{ws[:name]} (#{ws[:id]})" }
+        selected = Ui.choose(choices, header: "Select your default workspace:")
+
+        return nil if selected.nil?
+
+        # Find the selected workspace
+        workspaces.find { |ws| selected.include?(ws[:id]) }
+      end
+
+      # Save the account configuration and workspace selection to disk.
+      #
+      # @param config [Superthread::Configuration] the configuration instance to update
+      # @param account_name [String] the name for this account
+      # @param api_key [String] the API key to store
+      # @param workspace [Hash{Symbol => String}] the selected workspace with :id and :name
+      # @return [void]
+      def save_account(config, account_name, api_key, workspace)
+        Ui.section "Step 5: Saving Configuration"
+
+        # Add/update account with API key in config file
+        config.add_account(account_name, api_key: api_key)
+        Ui.muted "Saved account '#{account_name}' to #{config.config_path}"
+
+        # Save workspace to account state
+        config.save_account_state(account_name,
+          workspace_id: workspace[:id],
+          workspace_name: workspace[:name])
+        Ui.muted "Saved workspace to #{config.state_path}"
+
+        # Set as current account
+        config.current_account = account_name
+        Ui.muted "Set '#{account_name}' as current account"
+      end
+
+      # Extract team/workspace information from a user object.
+      #
+      # @param user [User] the authenticated user object containing team memberships
+      # @return [Array<Hash{Symbol => String}>] list of workspace hashes with :id, :name, and :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/spaces.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing Superthread spaces.
+    #
+    # Spaces are containers that organize boards, pages, and other content
+    # within a workspace. This class provides commands to list, create,
+    # update, and delete spaces, as well as manage space membership.
+    class Spaces < Base
+      # Kebab-case aliases for commands
+      map "add-member" => :add_member,
+        "remove-member" => :remove_member
+      desc "list", "List all spaces"
+      # Lists all spaces in the current workspace.
+      #
+      # @return [void]
+      def list
+        spaces = client.spaces.list(workspace_id)
+        output_list spaces, columns: %i[id title], headers: {id: "SPACE_ID"}
+      end
+
+      desc "get SPACE", "Get space details"
+      # Retrieves and displays details for a specific space.
+      #
+      # @param space_ref [String] space identifier (ID or name)
+      # @return [void]
+      def get(space_ref)
+        handle_error do
+          resolved_space_id = resolve_space(space_ref)
+          begin
+            space = client.spaces.find(workspace_id, resolved_space_id)
+          rescue Superthread::ForbiddenError
+            raise Thor::Error, "Space not found: '#{space_ref}'. Use 'suth spaces list' to see available spaces."
+          end
+          output_item space, fields: %i[id title description time_created time_updated],
+            labels: {id: "Space ID"}
+        end
+      end
+
+      desc "create", "Create a new space"
+      option :title, type: :string, required: true, desc: "Space title"
+      option :description, type: :string, desc: "Space description"
+      option :icon, type: :string, desc: "Space icon name (e.g., rocket, folder, star)"
+      option :icon_color, type: :string, desc: "Space icon color (hex, e.g., #FF5733)"
+      # Creates a new space in the current workspace.
+      #
+      # @return [void]
+      def create
+        handle_error do
+          opts = symbolized_options(:title, :description)
+          opts[:icon] = build_icon_object if options[:icon]
+          space = client.spaces.create(workspace_id, **opts)
+          output_item space, labels: {id: "Space ID"}
+        end
+      end
+
+      desc "update SPACE", "Update a space"
+      option :title, type: :string, desc: "New title"
+      option :description, type: :string, desc: "New description"
+      option :icon, type: :string, desc: "New icon name (e.g., rocket, folder, star)"
+      option :icon_color, type: :string, desc: "New icon color (hex, e.g., #FF5733)"
+      # Updates an existing space's properties.
+      #
+      # @param space_ref [String] space identifier (ID or name)
+      # @return [void]
+      def update(space_ref)
+        handle_error do
+          opts = symbolized_options(:title, :description)
+          opts[:icon] = build_icon_object if options[:icon] || options[:icon_color]
+          space = client.spaces.update(workspace_id, resolve_space(space_ref), **opts)
+          output_item space, labels: {id: "Space ID"}
+        end
+      end
+
+      desc "delete SPACE", "Delete a space"
+      # Deletes a space after confirmation.
+      #
+      # @param space_ref [String] space identifier (ID or name)
+      # @return [void]
+      def delete(space_ref)
+        handle_error do
+          space = client.spaces.find(workspace_id, resolve_space(space_ref))
+          confirming("Delete space '#{space.title}' (#{space.id})?") do
+            client.spaces.destroy(workspace_id, space.id)
+            output_success "Space '#{space.title}' deleted"
+          end
+        end
+      end
+
+      desc "add_member SPACE USERS", "Add member(s) to a space (comma-separated)"
+      option :role, type: :string, desc: "Member role"
+      # Adds one or more users as members of a space with an optional role.
+      #
+      # @param space_ref [String] space identifier (ID or name)
+      # @param user_refs [String] comma-separated user IDs, names, or emails
+      # @return [void]
+      def add_member(space_ref, user_refs)
+        handle_error do
+          space_resolved = resolve_space(space_ref)
+          users = user_refs.split(",").map(&:strip)
+          users.each do |user_ref|
+            user_resolved = resolve_user(user_ref)
+            client.spaces.add_member(workspace_id, space_resolved, user_id: user_resolved, role: options[:role])
+          end
+          output_success "Added #{users.size} user(s) to space #{space_ref}"
+        end
+      end
+
+      desc "remove_member SPACE USERS", "Remove member(s) from a space (comma-separated)"
+      # Removes one or more users from a space.
+      #
+      # @param space_ref [String] space identifier (ID or name)
+      # @param user_refs [String] comma-separated user IDs, names, or emails
+      # @return [void]
+      def remove_member(space_ref, user_refs)
+        handle_error do
+          space_resolved = resolve_space(space_ref)
+          users = user_refs.split(",").map(&:strip)
+          users.each do |user_ref|
+            user_resolved = resolve_user(user_ref)
+            client.spaces.remove_member(workspace_id, space_resolved, user_resolved)
+          end
+          output_success "Removed #{users.size} user(s) from space #{space_ref}"
+        end
+      end
+
+      private
+
+      # Build an icon object from CLI options.
+      #
+      # @return [Hash] the icon object for the API
+      def build_icon_object
+        icon = {type: "icon"}
+        icon[:src] = options[:icon] if options[:icon]
+        icon[:color] = options[:icon_color] if options[:icon_color]
+        icon
+      end
+    end
+  end
+end

data/lib/superthread/cli/sprints.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for sprint operations.
+    class Sprints < Base
+      desc "list", "List all sprints in a space"
+      option :space, type: :string, required: true, aliases: "-s", desc: "Space (ID or name)"
+      # Lists all sprints in a specified space.
+      #
+      # @return [void]
+      def list
+        sprints = client.sprints.list(workspace_id, space_id: space_id)
+        output_list sprints, columns: %i[id title start_date], headers: {id: "SPRINT_ID"}
+      end
+
+      desc "get SPRINT", "Get sprint details"
+      option :space, type: :string, required: true, aliases: "-s", desc: "Space (ID or name)"
+      # Displays detailed information about a specific sprint.
+      #
+      # @param sprint_id [String] the unique identifier of the sprint to retrieve
+      # @return [void]
+      def get(sprint_id)
+        handle_error do
+          sprint = client.sprints.find(workspace_id, sprint_id, space_id: space_id)
+          output_item sprint, fields: %i[id title start_date time_created time_updated],
+            labels: {id: "Sprint ID"}
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/tags.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing Superthread tags.
+    #
+    # Tags are labels that can be applied to cards for categorization
+    # and filtering. Each tag has a name and color.
+    class Tags < Base
+      desc "list", "List available tags"
+      option :space, type: :string, aliases: "-s", desc: "Space to filter by (ID or name)"
+      option :all, type: :boolean, desc: "Include unused tags"
+      # Lists all available tags in the workspace.
+      #
+      # @return [void]
+      def list
+        handle_error do
+          opts = symbolized_options(:all)
+          opts[:project_id] = space_id if options[:space]
+          tags = client.cards.tags(workspace_id, **opts)
+          output_list tags, columns: %i[id name color total_cards], headers: {id: "TAG_ID"}
+        end
+      end
+
+      desc "create", "Create a new tag"
+      option :name, type: :string, required: true, desc: "Tag name"
+      option :color, type: :string, required: true, desc: "Tag color (hex)"
+      option :space, type: :string, aliases: "-s", desc: "Space to create tag in (ID or name)"
+      # Creates a new tag in the workspace with a name and color.
+      #
+      # @return [void]
+      def create
+        opts = symbolized_options(:name, :color)
+        opts[:space_id] = space_id if options[:space]
+        tag = client.tags.create(workspace_id, **opts)
+        output_item tag, fields: %i[id name color], labels: {id: "Tag ID"}
+      end
+
+      desc "update TAG", "Update a tag"
+      option :name, type: :string, desc: "New name"
+      option :color, type: :string, desc: "New color (hex)"
+      # Updates an existing tag's name or color.
+      #
+      # @param tag_ref [String] tag identifier (ID or name)
+      # @return [void]
+      def update(tag_ref)
+        handle_error do
+          tag_id = resolve_tag(tag_ref)
+          tag = with_not_found("Tag not found: '#{tag_ref}'. Use 'suth tags list' to see available tags.") do
+            client.tags.update(workspace_id, tag_id, **symbolized_options(:name, :color))
+          end
+          output_item tag, labels: {id: "Tag ID"}
+        end
+      end
+
+      desc "delete TAG", "Delete a tag"
+      # Deletes a tag after confirmation.
+      #
+      # @param tag_ref [String] tag identifier (ID or name)
+      # @return [void]
+      def delete(tag_ref)
+        handle_error do
+          tag = find_tag(tag_ref)
+          confirming("Delete tag '#{tag.name}' (#{tag.id})?") do
+            client.tags.destroy(workspace_id, tag.id)
+            output_success "Tag '#{tag.name}' deleted"
+          end
+        end
+      end
+
+      private
+
+      # Find tag by ID or name, returning the full tag object.
+      #
+      # @param ref [String] the tag ID or name to find
+      # @return [Superthread::Models::Tag] the matching tag object
+      # @raise [Thor::Error] if no matching tag is found
+      def find_tag(ref)
+        tags = client.cards.tags(workspace_id, all: true)
+        tag = tags.find { |t| t.id == ref || t.name&.downcase == ref.downcase }
+        raise Thor::Error, "Tag not found: '#{ref}'. Use 'suth tags list' to see available tags." unless tag
+        tag
+      end
+    end
+  end
+end

data/lib/superthread/cli/ui/gum_prompt.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    module Ui
+      # Interactive prompt backend using Gum TUI widgets.
+      #
+      # Provides rich terminal interactions with animated spinners,
+      # arrow-key selection, and fuzzy filtering. Requires a terminal
+      # with full ANSI escape sequence support.
+      module GumPrompt
+        module_function
+
+        # @param question [String] the confirmation question
+        # @param default [Boolean] the default answer
+        # @return [Boolean]
+        def confirm(question, default: true)
+          Gum.confirm(question, default: default)
+        end
+
+        # @param prompt [String] the prompt label
+        # @param placeholder [String, nil] placeholder hint
+        # @return [String]
+        def input(prompt, placeholder: nil)
+          Gum.input(prompt: prompt, placeholder: placeholder)
+        end
+
+        # @param prompt [String] the prompt label
+        # @return [String]
+        def password(prompt)
+          Gum.input(prompt: prompt, password: true)
+        end
+
+        # @param items [Array<String>] options to choose from
+        # @param header [String, nil] optional header text
+        # @return [String]
+        def choose(items, header: nil)
+          Gum.choose(items, header: header)
+        end
+
+        # @param items [Array<String>] the available options for fuzzy filtering
+        # @param placeholder [String, nil] placeholder hint
+        # @return [String]
+        def filter(items, placeholder: nil)
+          Gum.filter(items, placeholder: placeholder)
+        end
+
+        # @param title [String] status message
+        # @param block [Proc] the block to execute while the spinner is displayed
+        # @yieldreturn [Object] result of the block
+        # @return [Object]
+        def spin(title, &block)
+          Gum.spin(title, spinner: :dot, &block)
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/ui/plain_prompt.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    module Ui
+      # Plain text prompt backend using standard Ruby I/O.
+      #
+      # Fallback for terminals with limited ANSI escape support
+      # (e.g., macOS Terminal.app) where Gum widgets render incorrectly.
+      module PlainPrompt
+        module_function
+
+        # @param question [String] the confirmation question
+        # @param default [Boolean] the default answer
+        # @return [Boolean]
+        def confirm(question, default: true)
+          hint = default ? "(Y/n)" : "(y/N)"
+          print "#{question} #{hint}: "
+          answer = $stdin.gets&.chomp
+          return default if answer.nil? || answer.empty?
+          answer.downcase.start_with?("y")
+        end
+
+        # @param prompt [String] the prompt label
+        # @param placeholder [String, nil] placeholder hint (ignored in plain mode)
+        # @return [String]
+        def input(prompt, placeholder: nil)
+          print prompt
+          $stdin.gets&.chomp
+        end
+
+        # @param prompt [String] the prompt label
+        # @return [String]
+        def password(prompt)
+          require "io/console"
+          print prompt
+          $stdin.noecho(&:gets)&.chomp
+        end
+
+        # @param items [Array<String>] options to choose from
+        # @param header [String, nil] optional header text
+        # @return [String]
+        def choose(items, header: nil)
+          puts header if header
+          items.each_with_index { |item, i| puts "  #{i + 1}. #{item}" }
+          print "Choose (1-#{items.length}): "
+          raw = $stdin.gets&.chomp
+          choice = raw&.to_i || 0
+          return items.first if choice < 1 || choice > items.length
+          items[choice - 1]
+        end
+
+        # @param items [Array<String>] the available options presented as a numbered list
+        # @param placeholder [String, nil] placeholder hint (ignored in plain mode)
+        # @return [String]
+        def filter(items, placeholder: nil)
+          choose(items)
+        end
+
+        # @param title [String] status message
+        # @param block [Proc] the block to execute while the status is displayed
+        # @yieldreturn [Object] result of the block
+        # @return [Object]
+        def spin(title, &block)
+          print "#{title}..."
+          result = yield
+          puts " done"
+          result
+        end
+      end
+    end
+  end
+end