superthread 0.7.2

data/lib/superthread/cli/main.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # Main entry point for the Superthread CLI.
+    # Registers all subcommands and provides top-level commands like version and setup.
+    class Main < Base
+      map %w[--version -V] => :version
+
+      desc "version", "Show version and check for updates"
+      # Displays the current version and checks for updates.
+      #
+      # @return [void]
+      def version
+        puts "superthread #{Superthread::VERSION}"
+
+        latest = Superthread::VersionChecker.check!
+        if latest && Superthread::VersionChecker.newer?(latest)
+          say ""
+          say "Update available: #{Superthread::VERSION} \u2192 #{latest}", :yellow
+          say "Run: brew upgrade superthread", :yellow
+        end
+      rescue
+        nil
+      end
+
+      desc "setup", "Interactive setup wizard"
+      # Runs the interactive setup wizard to configure accounts and workspaces.
+      #
+      # @return [void]
+      def setup
+        Superthread::Cli::Setup.execute
+      end
+
+      desc "config SUBCOMMAND", "Manage configuration"
+      subcommand "config", Superthread::Cli::Config
+
+      desc "me", "Show current user account info"
+      # Displays information about the currently authenticated user.
+      #
+      # @return [void]
+      def me
+        handle_error do
+          user = client.users.me
+
+          if json_output?
+            output_item user
+          else
+            # Show basic user info
+            output_item user, fields: %i[display_name email time_created], labels: {
+              time_created: "Time Created"
+            }
+
+            # Show workspaces with roles
+            if user.teams&.any?
+              say ""
+              say "Workspaces:", :cyan
+              user.teams.each do |team|
+                say "  #{team.team_name} (#{team.id}) - #{team.role}"
+              end
+            end
+          end
+        end
+      end
+
+      desc "accounts SUBCOMMAND", "Manage accounts"
+      subcommand "accounts", Superthread::Cli::Accounts
+
+      desc "workspaces SUBCOMMAND", "List and select workspaces"
+      subcommand "workspaces", Superthread::Cli::Workspaces
+
+      desc "members SUBCOMMAND", "Workspace member commands"
+      subcommand "members", Superthread::Cli::Members
+
+      desc "cards SUBCOMMAND", "Card management commands"
+      subcommand "cards", Superthread::Cli::Cards
+
+      desc "boards SUBCOMMAND", "Board and list management commands"
+      subcommand "boards", Superthread::Cli::Boards
+
+      desc "projects SUBCOMMAND", "Roadmap project (epic) commands"
+      subcommand "projects", Superthread::Cli::Projects
+
+      desc "spaces SUBCOMMAND", "Space management commands"
+      subcommand "spaces", Superthread::Cli::Spaces
+
+      desc "comments SUBCOMMAND", "Comment management commands"
+      subcommand "comments", Superthread::Cli::Comments
+
+      desc "replies SUBCOMMAND", "Comment reply commands"
+      subcommand "replies", Superthread::Cli::Replies
+
+      desc "lists SUBCOMMAND", "Board list (column) commands"
+      subcommand "lists", Superthread::Cli::Lists
+
+      desc "checklists SUBCOMMAND", "Card checklist commands"
+      subcommand "checklists", Superthread::Cli::Checklists
+
+      desc "pages SUBCOMMAND", "Page/documentation commands"
+      subcommand "pages", Superthread::Cli::Pages
+
+      desc "notes SUBCOMMAND", "Meeting notes commands"
+      subcommand "notes", Superthread::Cli::Notes
+
+      desc "sprints SUBCOMMAND", "Sprint commands"
+      subcommand "sprints", Superthread::Cli::Sprints
+
+      desc "search QUERY", "Search across workspace"
+      subcommand "search", Superthread::Cli::Search
+
+      desc "tags SUBCOMMAND", "Tag management commands"
+      subcommand "tags", Superthread::Cli::Tags
+
+      desc "activity", "Show recent activity across workspace"
+      subcommand "activity", Superthread::Cli::Activity
+
+      desc "completion SHELL", "Generate shell completion scripts"
+      subcommand "completion", Superthread::Cli::Completion
+    end
+  end
+end

data/lib/superthread/cli/members.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for workspace member operations.
+    class Members < Base
+      desc "list", "List workspace members"
+      # Lists all members of the current workspace.
+      #
+      # @return [void]
+      def list
+        handle_error do
+          members = client.users.members(workspace_id)
+          output_list members, columns: %i[id display_name email role], headers: {id: "USER_ID"}
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/notes.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing Superthread notes.
+    #
+    # Notes are standalone content items that can contain transcripts
+    # and user annotations. They can be made public for sharing.
+    class Notes < Base
+      desc "list", "List all notes"
+      # Lists all notes in the current workspace.
+      #
+      # @return [void]
+      def list
+        notes = client.notes.list(workspace_id)
+        output_list notes, columns: %i[id title time_created], headers: {id: "NOTE_ID"}
+      end
+
+      desc "get NOTE", "Get note details"
+      # Retrieves and displays details for a specific note.
+      #
+      # @param note_id [String] numeric ID of the note to retrieve
+      # @return [void]
+      def get(note_id)
+        handle_error do
+          note = with_not_found("Note not found: '#{note_id}'. Use 'suth notes list' to see available notes.") do
+            client.notes.find(workspace_id, note_id)
+          end
+          output_item note, fields: %i[id title content time_created time_updated], labels: {id: "Note ID"}
+        end
+      end
+
+      desc "create", "Create a new note"
+      option :title, type: :string, required: true, desc: "Note title"
+      option :transcript, type: :string, desc: "Transcript content"
+      option :user_notes, type: :string, desc: "User notes"
+      option :is_public, type: :boolean, desc: "Make note public"
+      # Creates a new note in the current workspace.
+      #
+      # @return [void]
+      def create
+        note = client.notes.create(workspace_id, **symbolized_options(:title, :transcript, :user_notes, :is_public))
+        output_item note, labels: {id: "Note ID"}
+      end
+
+      desc "delete NOTE", "Delete a note"
+      # Deletes a note after confirmation.
+      #
+      # @param note_ref [String] note identifier (ID or name)
+      # @return [void]
+      def delete(note_ref)
+        handle_error do
+          note = with_not_found("Note not found: '#{note_ref}'. Use 'suth notes list' to see available notes.") do
+            client.notes.find(workspace_id, note_ref)
+          end
+          confirming("Delete note '#{note.title}' (#{note.id})?") do
+            client.notes.destroy(workspace_id, note.id)
+            output_success "Note '#{note.title}' deleted"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/pages.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing Superthread pages (documents).
+    #
+    # Pages are rich-text documents that can be organized within spaces
+    # and nested under parent pages to form a hierarchy.
+    class Pages < Base
+      desc "list", "List all pages"
+      option :space, type: :string, aliases: "-s", desc: "Space to filter by (ID or name)"
+      option :include_archived, type: :boolean, desc: "Include archived pages"
+      option :updated_recently, type: :boolean, desc: "Filter by recently updated pages"
+      # Lists all pages in the current workspace with optional filters.
+      #
+      # @return [void]
+      def list
+        opts = symbolized_options(:updated_recently)
+        opts[:archived] = options[:include_archived] if options[:include_archived]
+        opts[:space_id] = space_id if options[:space]
+        pages = client.pages.list(workspace_id, **opts)
+        output_list pages, columns: %i[id title], headers: {id: "PAGE_ID"}
+      end
+
+      desc "get PAGE", "Get page details"
+      # Retrieves and displays details for a specific page.
+      #
+      # @param page_id [String] numeric ID or URL slug of the page to retrieve
+      # @return [void]
+      def get(page_id)
+        handle_error do
+          page = with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+            client.pages.find(workspace_id, page_id)
+          end
+          output_item page, fields: %i[id title time_created time_updated], labels: {id: "Page ID"}
+        end
+      end
+
+      desc "create", "Create a new page"
+      option :space, type: :string, required: true, aliases: "-s", desc: "Space to create page in (ID or name)"
+      option :title, type: :string, desc: "Page title"
+      option :content, type: :string, desc: "Page content"
+      option :parent_page, type: :string, desc: "Parent page ID"
+      option :is_public, type: :boolean, desc: "Make page public"
+      # Creates a new page in a space.
+      #
+      # @return [void]
+      def create
+        opts = symbolized_options(:title, :content, :is_public)
+        opts[:space_id] = space_id
+        opts[:parent_page_id] = options[:parent_page] if options[:parent_page]
+        page = client.pages.create(workspace_id, **opts)
+        output_item page, labels: {id: "Page ID"}
+      end
+
+      desc "update PAGE", "Update a page"
+      option :title, type: :string, desc: "New title"
+      option :is_public, type: :boolean, desc: "Public visibility"
+      option :parent_page, type: :string, desc: "Parent page ID"
+      option :archived, type: :boolean, desc: "Archive/unarchive"
+      # Updates an existing page's properties.
+      #
+      # @param page_id [String] numeric ID or URL slug of the page to retrieve
+      # @return [void]
+      def update(page_id)
+        handle_error do
+          opts = symbolized_options(:title, :is_public, :archived)
+          opts[:parent_page_id] = options[:parent_page] if options[:parent_page]
+          page = with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+            client.pages.update(workspace_id, page_id, **opts)
+          end
+          output_item page, labels: {id: "Page ID"}
+        end
+      end
+
+      desc "duplicate PAGE", "Duplicate a page"
+      option :space, type: :string, required: true, aliases: "-s", desc: "Destination space (ID or name)"
+      option :title, type: :string, desc: "Title for the duplicated page"
+      option :parent_page, type: :string, desc: "Parent page ID"
+      # Creates a copy of an existing page in a specified space.
+      #
+      # @param page_id [String] numeric ID of the source page to duplicate
+      # @return [void]
+      def duplicate(page_id)
+        handle_error do
+          opts = symbolized_options(:title)
+          opts[:space_id] = space_id
+          opts[:parent_page_id] = options[:parent_page] if options[:parent_page]
+          page = with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+            client.pages.duplicate(workspace_id, page_id, **opts)
+          end
+          output_item page, labels: {id: "Page ID"}
+        end
+      end
+
+      desc "archive PAGE", "Archive a page"
+      # Archives a page, hiding it from default views.
+      #
+      # @param page_id [String] numeric ID or URL slug of the page to retrieve
+      # @return [void]
+      def archive(page_id)
+        handle_error do
+          page = with_not_found("Page not found: '#{page_id}'. Use 'suth pages list' to see available pages.") do
+            client.pages.archive(workspace_id, page_id)
+          end
+          output_item page, labels: {id: "Page ID"}
+        end
+      end
+
+      desc "delete PAGE", "Delete a page permanently"
+      # Permanently deletes a page after confirmation.
+      #
+      # @param page_ref [String] page identifier (ID or name)
+      # @return [void]
+      def delete(page_ref)
+        handle_error do
+          page = with_not_found("Page not found: '#{page_ref}'. Use 'suth pages list' to see available pages.") do
+            client.pages.find(workspace_id, page_ref)
+          end
+          confirming("Delete page '#{page.title}' (#{page.id})?") do
+            client.pages.destroy(workspace_id, page.id)
+            output_success "Page '#{page.title}' deleted"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/projects.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing Superthread projects (epics/roadmap items).
+    #
+    # Projects are high-level items on the roadmap that can contain multiple
+    # cards. They have start/due dates, owners, and can be organized on boards.
+    class Projects < Base
+      # Kebab-case aliases for commands
+      map "add-card" => :add_card,
+        "remove-card" => :remove_card
+      desc "list", "List all roadmap projects"
+      # Lists all projects in the current workspace.
+      #
+      # @return [void]
+      def list
+        projects = client.projects.list(workspace_id)
+        output_list projects, columns: %i[id title status], headers: {id: "PROJECT_ID"}
+      end
+
+      desc "get PROJECT", "Get project details"
+      # Retrieves and displays details for a specific project.
+      #
+      # @param project_id [String] numeric ID or short code of the project/epic
+      # @return [void]
+      def get(project_id)
+        handle_error do
+          project = with_not_found("Project not found: '#{project_id}'. Use 'suth projects list' to see available projects.") do
+            client.projects.find(workspace_id, project_id)
+          end
+          output_item project, fields: %i[id title status start_date due_date time_created time_updated],
+            labels: {id: "Project ID"}
+        end
+      end
+
+      desc "create", "Create a new project"
+      option :title, type: :string, required: true, desc: "Project title"
+      option :list, type: :string, required: true, aliases: "-l", desc: "Destination list (ID or name, requires --board)"
+      option :board, type: :string, aliases: "-b", desc: "Board (helps resolve list name)"
+      option :space, type: :string, aliases: "-s", desc: "Space (helps resolve board name)"
+      option :content, type: :string, desc: "Project description"
+      option :start_date, type: :numeric, desc: "Start date (Unix timestamp)"
+      option :due_date, type: :numeric, desc: "Due date (Unix timestamp)"
+      option :owner, type: :string, aliases: "-o", desc: "Owner (user ID, name, or email)"
+      option :priority, type: :numeric, desc: "Priority level"
+      # Creates a new project on a board list.
+      #
+      # @return [void]
+      def create
+        opts = symbolized_options(:title, :content, :start_date, :due_date, :priority)
+        opts[:list_id] = resolve_list(options[:list])
+        opts[:owner_id] = resolve_user(options[:owner]) if options[:owner]
+        project = client.projects.create(workspace_id, **opts)
+        output_item project, labels: {id: "Project ID"}
+      end
+
+      desc "update PROJECT", "Update a project"
+      option :title, type: :string, desc: "New title"
+      option :list, type: :string, aliases: "-l", desc: "Destination list (ID or name, requires --board)"
+      option :board, type: :string, aliases: "-b", desc: "Board (helps resolve list name)"
+      option :space, type: :string, aliases: "-s", desc: "Space (helps resolve board name)"
+      option :owner, type: :string, aliases: "-o", desc: "New owner (user ID, name, or email)"
+      option :start_date, type: :numeric, desc: "Start date"
+      option :due_date, type: :numeric, desc: "Due date"
+      option :priority, type: :numeric, desc: "Priority"
+      option :archived, type: :boolean, desc: "Archive/unarchive"
+      # Updates an existing project's properties.
+      #
+      # @param project_id [String] numeric ID or short code of the project/epic
+      # @return [void]
+      def update(project_id)
+        handle_error do
+          opts = symbolized_options(:title, :start_date, :due_date, :priority, :archived)
+          opts[:list_id] = resolve_list(options[:list]) if options[:list]
+          opts[:owner_id] = resolve_user(options[:owner]) if options[:owner]
+          project = with_not_found("Project not found: '#{project_id}'. Use 'suth projects list' to see available projects.") do
+            client.projects.update(workspace_id, project_id, **opts)
+          end
+          output_item project, labels: {id: "Project ID"}
+        end
+      end
+
+      desc "delete PROJECT", "Delete a project"
+      # Deletes a project after confirmation.
+      #
+      # @param project_ref [String] project identifier (ID or name)
+      # @return [void]
+      def delete(project_ref)
+        handle_error do
+          project = with_not_found("Project not found: '#{project_ref}'. Use 'suth projects list' to see available projects.") do
+            client.projects.find(workspace_id, project_ref)
+          end
+          confirming("Delete project '#{project.title}' (#{project.id})?") do
+            client.projects.destroy(workspace_id, project.id)
+            output_success "Project '#{project.title}' deleted"
+          end
+        end
+      end
+
+      desc "add_card PROJECT_ID CARD_ID", "Link a card to a project"
+      # Links an existing card to a project.
+      #
+      # @param project_id [String] numeric ID or short code of the project/epic
+      # @param card_id [String] unique identifier of the card to link
+      # @return [void]
+      def add_card(project_id, card_id)
+        client.projects.add_card(workspace_id, project_id, card_id)
+        output_success "Linked card #{card_id} to project #{project_id}"
+      end
+
+      desc "remove_card PROJECT_ID CARD_ID", "Remove a card from a project"
+      # Removes a card's association from a project.
+      #
+      # @param project_id [String] numeric ID or short code of the project/epic
+      # @param card_id [String] unique identifier of the card to unlink
+      # @return [void]
+      def remove_card(project_id, card_id)
+        client.projects.remove_card(workspace_id, project_id, card_id)
+        output_success "Removed card #{card_id} from project #{project_id}"
+      end
+    end
+  end
+end

data/lib/superthread/cli/replies.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for managing comment replies.
+    #
+    # Replies are threaded responses to comments on cards and pages.
+    # This class provides commands to list, create, update, and delete replies.
+    class Replies < Base
+      desc "list", "List all replies to a comment"
+      option :comment, type: :string, required: true, desc: "Parent comment ID"
+      # List all replies to a specified comment.
+      #
+      # @return [void]
+      def list
+        handle_error do
+          replies = client.comments.replies(workspace_id, options[:comment])
+          output_list replies, columns: %i[id content user_id time_created], headers: {id: "REPLY_ID"}
+        end
+      end
+
+      desc "get REPLY_ID", "Get reply details"
+      option :comment, type: :string, required: true, desc: "Parent comment ID"
+      # Display detailed information about a specific reply.
+      #
+      # @param reply_id [String] the unique identifier of the reply
+      # @return [void]
+      def get(reply_id)
+        handle_error do
+          begin
+            reply = client.comments.find_reply(workspace_id, options[:comment], reply_id)
+          rescue Superthread::NotFoundError
+            raise Thor::Error, "Reply not found: '#{reply_id}' on comment '#{options[:comment]}'."
+          end
+          output_item reply, fields: %i[id content user_id card_id time_created time_updated], labels: {
+            id: "Reply ID",
+            user_id: "User ID",
+            card_id: "Card ID",
+            time_created: "Time Created",
+            time_updated: "Time Updated"
+          }
+        end
+      end
+
+      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"
+      # Add a threaded reply to an existing comment.
+      #
+      # @return [void]
+      def create
+        handle_error do
+          reply = client.comments.reply(workspace_id, options[:comment], content: options[:content])
+          output_item reply, labels: {id: "Reply ID"}
+        end
+      end
+
+      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 :status, type: :string, enum: %w[resolved open orphaned], desc: "Status"
+      # Update an existing reply's content or status.
+      #
+      # @param reply_id [String] the unique identifier of the reply
+      # @return [void]
+      def update(reply_id)
+        handle_error do
+          reply = client.comments.update_reply(
+            workspace_id, options[:comment], reply_id,
+            **symbolized_options(:content, :status)
+          )
+          output_item reply, labels: {id: "Reply ID"}
+        end
+      end
+
+      desc "delete REPLY_ID", "Delete a reply"
+      option :comment, type: :string, required: true, desc: "Parent comment ID"
+      # Permanently delete a reply after confirmation.
+      #
+      # @param reply_id [String] the unique identifier of the reply
+      # @return [void]
+      def delete(reply_id)
+        handle_error do
+          reply = client.comments.find_reply(workspace_id, options[:comment], reply_id)
+          preview = Formatter.truncate(Formatter.strip_html(reply.content), 50)
+          confirming("Delete reply '#{preview}' (#{reply_id})?") do
+            client.comments.delete_reply(workspace_id, options[:comment], reply_id)
+            output_success "Reply #{reply_id} deleted"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superthread/cli/search.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Superthread
+  module Cli
+    # CLI commands for search operations.
+    class Search < Base
+      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 :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"
+      # Searches across all entities in the workspace.
+      #
+      # @param search_term [String] the text to search for
+      # @return [void]
+      def query(search_term)
+        handle_error do
+          types = options[:types]&.split(",")&.map(&:strip)
+          results = client.search.query(
+            workspace_id,
+            query: search_term,
+            field: options[:field],
+            types: types,
+            space_id: space_id,
+            archived: options[:include_archived],
+            grouped: options[:grouped]
+          )
+          output_list results, columns: %i[result_type id title], headers: {id: "ID"}
+        end
+      end
+    end
+  end
+end