slk 0.4.2 → 0.6.0

data/lib/slk/formatters/attachment_formatter.rb

@@ -9,17 +9,19 @@ module Slk
         @text_processor = text_processor
       end
 
-      def format(attachments, lines, options)
+      def format(attachments, lines, options, message_ts: nil)
         return if attachments.empty?
         return if options[:no_attachments]
 
-        attachments.each { |att| format_attachment(att, lines, options) }
+        attachments.each_with_index do |att, idx|
+          format_attachment(att, lines, options, message_ts: message_ts, index: idx)
+        end
       end
 
       private
 
       # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      def format_attachment(attachment, lines, options)
+      def format_attachment(attachment, lines, options, message_ts: nil, index: 0)
         att_text = attachment['text'] || attachment['fallback']
         image_url = attachment['image_url'] || attachment['thumb_url']
         block_images = extract_block_images(attachment)
@@ -29,7 +31,7 @@ module Slk
         lines << ''
         format_author(attachment, lines)
         format_text(att_text, lines, options) if att_text && block_images.empty?
-        format_image(attachment, image_url, lines) if image_url
+        format_image(attachment, lines, options, message_ts: message_ts, index: index) if image_url
         block_images.each { |img| lines << "> [Image: #{img}]" }
       end
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -64,9 +66,22 @@ module Slk
         Support::TextWrapper.wrap(text, width - 2, width - 2)
       end
 
-      def format_image(attachment, image_url, lines)
-        filename = attachment['title'] || extract_filename(image_url)
-        lines << "> [Image: #{filename}]"
+      def format_image(attachment, lines, options, message_ts: nil, index: 0)
+        local_path = lookup_attachment_path(options, message_ts, index)
+        if local_path
+          lines << "> [Image: #{local_path}]"
+        else
+          image_url = attachment['image_url'] || attachment['thumb_url']
+          filename = attachment['title'] || extract_filename(image_url)
+          lines << "> [Image: #{filename}]"
+        end
+      end
+
+      def lookup_attachment_path(options, message_ts, index)
+        return nil unless message_ts
+
+        key = "att_#{message_ts}_#{index}"
+        options.dig(:file_paths, key)
       end
 
       def extract_filename(url)

data/lib/slk/formatters/message_formatter.rb

@@ -85,8 +85,14 @@ module Slk
         return '' unless message.files? && !options[:no_files]
 
         first_file = message.files.first
-        file_name = first_file['name'] || 'file'
-        @output.blue("[File: #{file_name}]")
+        file_label = file_display_label(first_file, options)
+        @output.blue("[File: #{file_label}]")
+      end
+
+      def file_display_label(file, options)
+        file_id = file['id']
+        local_path = options.dig(:file_paths, file_id) if file_id
+        local_path || file['name'] || 'file'
       end
 
       def build_output_lines(main_line, message, workspace, options, display_text)
@@ -96,7 +102,7 @@ module Slk
         BlockFormatter.new(text_processor: text_processor)
                       .format(message.blocks, message.text, lines, options)
         AttachmentFormatter.new(output: @output, text_processor: text_processor)
-                           .format(message.attachments, lines, options)
+                           .format(message.attachments, lines, options, message_ts: message.ts)
         format_files(message, lines, options, skip_first: display_text.include?('[File:'))
         format_reactions(message, lines, workspace, options)
         format_thread_indicator(message, lines, options)
@@ -128,7 +134,10 @@ module Slk
         return if options[:no_files]
 
         files = files_to_display(message.files, skip_first)
-        files.each { |file| lines << @output.blue("[File: #{file['name'] || 'file'}]") }
+        files.each do |file|
+          label = file_display_label(file, options)
+          lines << @output.blue("[File: #{label}]")
+        end
       end
 
       def files_to_display(files, skip_first)

data/lib/slk/formatters/output.rb

@@ -18,6 +18,8 @@ module Slk
 
       attr_reader :verbose, :quiet
 
+      def color? = @color
+
       def initialize(io: $stdout, err: $stderr, color: nil, verbose: false, quiet: false)
         @io = io
         @err = err

data/lib/slk/formatters/profile_field_renderer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Renders ProfileField values to display strings (date with relative
+    # phrasing, link with alt text, type:user dereferenced via resolved_users).
+    class ProfileFieldRenderer
+      def initialize(output:)
+        @output = output
+        @hyperlinks = output.respond_to?(:color?) && output.color?
+      end
+
+      def render(field, profile)
+        case field.type
+        when 'date' then format_date(field.value)
+        when 'link' then format_link(field)
+        when 'user' then format_user_list(field, profile)
+        else format_text(field.value)
+        end
+      end
+
+      # Slack stores some text fields (notably free-text profile blocks) as
+      # rich_text JSON blocks. Detect and flatten to plain text.
+      def format_text(value)
+        text = value.to_s
+        return text unless text.start_with?('[{') && text.include?('rich_text')
+
+        flatten_rich_text(JSON.parse(text))
+      rescue JSON::ParserError
+        text
+      end
+
+      def flatten_rich_text(blocks)
+        Array(blocks).flat_map { |block| extract_text_from_block(block) }.join
+      end
+
+      def extract_text_from_block(block)
+        return [block.to_s] unless block.is_a?(Hash)
+
+        return [block['text'].to_s] if block['type'] == 'text'
+        return [block['name'] ? ":#{block['name']}:" : ''] if block['type'] == 'emoji'
+
+        Array(block['elements']).flat_map { |el| extract_text_from_block(el) }
+      end
+
+      def render_user_reference(user_id, profile)
+        ref = profile.resolved_users[user_id]
+        return user_id unless ref
+
+        suffix = ref.title.to_s.empty? ? '' : " — #{ref.title}"
+        pronouns = ref.pronouns.to_s.empty? ? '' : " #{@output.gray("(#{ref.pronouns})")}"
+        "#{ref.best_name}#{pronouns}#{suffix}"
+      end
+
+      private
+
+      def format_user_list(field, profile)
+        field.user_ids.map { |uid| render_user_reference(uid, profile) }.join(', ')
+      end
+
+      def format_date(value)
+        date = parse_date(value) or return value
+        relative = relative_phrase(date, Date.today)
+        formatted = date.strftime('%b %-d, %Y')
+        relative ? "#{formatted} (#{relative})" : formatted
+      end
+
+      def parse_date(value)
+        Date.parse(value.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def relative_phrase(then_date, now_date)
+        return nil if then_date >= now_date
+
+        years, months = years_months_between(then_date, now_date)
+        parts = []
+        parts << "#{years}y" if years.positive?
+        parts << "#{months}mo" if months.positive?
+        parts.empty? ? nil : "#{parts.join(' ')} ago"
+      end
+
+      def years_months_between(then_date, now_date)
+        months = ((now_date.year - then_date.year) * 12) + (now_date.month - then_date.month)
+        months -= 1 if now_date.day < then_date.day
+        [months / 12, months % 12]
+      end
+
+      def format_link(field)
+        url = field.value.to_s
+        label = field.alt.to_s.empty? ? url : field.alt
+        return url if label == url
+        return "#{label} (#{shorten_url(url)})" unless @hyperlinks
+
+        # OSC 8 hyperlink — clickable in iTerm2, Ghostty, Wezterm, Kitty, Vte.
+        "\e]8;;#{url}\a#{label}\e]8;;\a"
+      end
+
+      def shorten_url(url)
+        URI.parse(url).host || url
+      rescue URI::InvalidURIError
+        url
+      end
+    end
+  end
+end

data/lib/slk/formatters/profile_formatter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Renders a Models::Profile for `slk who`.
+    # Compact mode: teems-style two-column card.
+    # Full mode: section-grouped layout matching Slack web UI.
+    class ProfileFormatter
+      MIN_LABEL_WIDTH = 8
+      MAX_LABEL_WIDTH = 20
+
+      def initialize(output:, emoji_replacer: nil)
+        @output = output
+        field_renderer = ProfileFieldRenderer.new(output: output)
+        @rows = ProfileRows.new(field_renderer: field_renderer, emoji_replacer: emoji_replacer)
+      end
+
+      def compact(profile)
+        render_header(profile)
+        emit_rows(@rows.compact(profile))
+        nil
+      end
+
+      def full(profile)
+        render_header(profile)
+        return emit_rows(@rows.external(profile)) if profile.external?
+
+        render_section('Contact information', @rows.contact(profile))
+        render_section('People', @rows.people(profile))
+        render_section('About me', @rows.about(profile))
+      end
+
+      def emit_rows(rows)
+        non_empty = rows.reject { |_, v| v.nil? || v.to_s.empty? }
+        width = label_width(non_empty)
+        non_empty.each { |label, value| emit_row(label, value, width) }
+      end
+
+      def label_width(rows)
+        max = rows.map { |label, _| label_for(label).length }.max || 0
+        max.clamp(MIN_LABEL_WIDTH, MAX_LABEL_WIDTH)
+      end
+
+      def label_for(label)
+        text = label.to_s
+        text.length > MAX_LABEL_WIDTH ? "#{text[0, MAX_LABEL_WIDTH - 1]}…" : text
+      end
+
+      private
+
+      def render_header(profile)
+        @output.puts(@output.bold(profile.best_name) + pronouns_suffix(profile))
+        header_tags(profile).each { |tag| @output.puts("  #{tag}") }
+        @output.puts
+      end
+
+      def header_tags(profile)
+        tags = []
+        tags << profile.title unless profile.title.to_s.empty?
+        tags << external_tag(profile) if profile.external?
+        tags << @output.bold('deactivated account') if profile.deleted
+        tags
+      end
+
+      def pronouns_suffix(profile)
+        profile.pronouns.to_s.empty? ? '' : " #{@output.gray("(#{profile.pronouns})")}"
+      end
+
+      def external_tag(profile)
+        @output.gray("external — #{profile.home_team_name || 'external workspace'}")
+      end
+
+      def render_section(title, rows)
+        return if rows.reject { |_, v| v.nil? || v.to_s.empty? }.empty?
+
+        @output.puts(@output.bold(title))
+        emit_rows(rows)
+        @output.puts
+      end
+
+      def emit_row(label, value, width)
+        padded = label_for(label).ljust(width)
+        @output.puts("  #{@output.gray(padded)} #{value}")
+      end
+    end
+  end
+end

data/lib/slk/formatters/profile_rows.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Builds [label, value] row pairs from a Models::Profile.
+    # Pure data — no output, formatting handled by ProfileFormatter.
+    class ProfileRows
+      def initialize(field_renderer:, emoji_replacer: nil)
+        @fields = field_renderer
+        @emoji_replacer = emoji_replacer
+      end
+
+      def compact(profile)
+        contact(profile) + base(profile) + people(profile) + about(profile, skip_title: true)
+      end
+
+      def contact(profile)
+        [['Email', profile.email], ['Phone', profile.phone]]
+      end
+
+      def base(profile)
+        [
+          ['Presence', profile.presence_label],
+          ['Status', status_text(profile)],
+          ['Local', local_time(profile)]
+        ]
+      end
+
+      def people(profile)
+        profile.people_fields.flat_map do |field|
+          field.user_ids.map { |uid| [field.label, @fields.render_user_reference(uid, profile)] }
+        end
+      end
+
+      def about(profile, skip_title: false)
+        fields = profile.visible_fields.reject { |f| f.type == 'user' }
+        fields = fields.reject { |f| skip_title && duplicate_title?(f, profile) }
+        fields.map { |f| [f.label, @fields.render(f, profile)] }
+      end
+
+      def external(profile)
+        contact(profile) + [['Workspace', profile.home_team_name]]
+      end
+
+      private
+
+      def duplicate_title?(field, profile)
+        field.label.casecmp('Title').zero? && field.value.to_s == profile.title.to_s
+      end
+
+      def status_text(profile)
+        return nil if profile.status_text.empty? && profile.status_emoji.empty?
+
+        emoji = render_emoji(profile.status_emoji)
+        [emoji, profile.status_text].reject(&:empty?).join(' ')
+      end
+
+      def render_emoji(text)
+        return text if text.to_s.empty? || @emoji_replacer.nil?
+
+        @emoji_replacer.replace(text)
+      end
+
+      def local_time(profile)
+        return nil unless profile.tz
+
+        time_at_user = Time.now.utc + profile.tz_offset.to_i
+        "#{time_at_user.strftime('%-l:%M %p')} #{profile.tz_label}".strip
+      end
+    end
+  end
+end

data/lib/slk/models/profile.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # Composite model representing a Slack user profile, merged from
+    # users.profile.get + users.info + team.profile.get schema.
+    #
+    # custom_fields is an Array<ProfileField>. resolved_users is a mutable
+    # Hash<user_id, Profile> populated by ProfileResolver one level deep
+    # for type:user fields (e.g. Supervisor).
+    Profile = Data.define(
+      :user_id, :real_name, :display_name, :first_name, :last_name,
+      :title, :email, :phone, :pronouns, :image_url,
+      :status_text, :status_emoji, :status_expiration,
+      :tz, :tz_label, :tz_offset, :start_date,
+      :is_admin, :is_owner, :is_bot, :is_external, :deleted,
+      :team_id, :home_team_name,
+      :presence, :sections, :custom_fields, :resolved_users
+    ) do
+      def presence_label
+        case presence
+        when 'active' then 'Active'
+        when 'away' then 'Away'
+        end
+      end
+
+      def best_name
+        return display_name unless display_name.to_s.empty?
+        return real_name unless real_name.to_s.empty?
+
+        user_id
+      end
+
+      def external?
+        is_external
+      end
+
+      # Custom fields with values, ordered by ordering then label.
+      # Hidden fields are filtered unless explicitly requested.
+      def visible_fields
+        custom_fields
+          .reject { |f| f.empty? || f.hidden }
+          .sort_by { |f| [f.ordering.to_i, f.label.to_s] }
+      end
+
+      def people_fields
+        visible_fields.select { |f| f.type == 'user' }
+      end
+
+      def fields_in_section(section_id)
+        visible_fields.select { |f| f.section_id == section_id }
+      end
+
+      def section(section_id)
+        sections.find { |s| s['id'] == section_id }
+      end
+
+      # User IDs from the first non-inverse Supervisor-like field.
+      # Prefers a field literally labeled "Supervisor".
+      def supervisor_ids
+        preferred = people_fields.find { |f| f.label.to_s.casecmp('Supervisor').zero? && !f.inverse }
+        preferred ||= people_fields.find { |f| !f.inverse }
+        preferred ? preferred.user_ids : []
+      end
+
+      def reports_field
+        custom_fields.find { |f| f.type == 'user' && f.inverse }
+      end
+    end
+  end
+end

data/lib/slk/models/profile_field.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # A single custom profile field from users.profile.get + team.profile.get schema.
+    #
+    # `value` is the raw string from Slack: a date as YYYY-MM-DD for type:date,
+    # a comma-separated list of user IDs for type:user, a URL for type:link.
+    # `alt` is Slack's optional display label (e.g. link text).
+    ProfileField = Data.define(
+      :id, :label, :value, :alt, :type, :ordering, :section_id, :hidden, :inverse
+    ) do
+      def empty?
+        value.to_s.empty?
+      end
+
+      # type:user values can be multi-value (comma-separated user IDs).
+      def user_ids
+        return [] unless type == 'user'
+
+        value.to_s.split(',').map(&:strip).reject(&:empty?)
+      end
+
+      def link_text
+        alt.to_s.empty? ? value.to_s : alt.to_s
+      end
+    end
+  end
+end

data/lib/slk/runner.rb

@@ -88,6 +88,23 @@ module Slk
       Api::Saved.new(@api_client, workspace(workspace_name))
     end
 
+    def team_api(workspace_name = nil)
+      Api::Team.new(@api_client, workspace(workspace_name))
+    end
+
+    def profile_resolver(workspace_name = nil, refresh: false)
+      ws = workspace(workspace_name)
+      resolver = Services::ProfileResolver.new(
+        users_api: users_api(workspace_name),
+        team_api: team_api(workspace_name),
+        cache_store: @cache_store,
+        workspace_name: ws.name,
+        on_debug: ->(msg) { @output.debug(msg) }
+      )
+      resolver.refresh = refresh
+      resolver
+    end
+
     def message_resolver(workspace_name = nil)
       Services::MessageResolver.new(
         conversations_api: conversations_api(workspace_name),

data/lib/slk/services/api_client.rb

@@ -29,6 +29,7 @@ module Slk
         @on_request_body = nil
         @on_response_body = nil
         @http_cache = {}
+        @rate_resets = {}
       end
 
       # Close all cached HTTP connections
@@ -75,15 +76,65 @@ module Slk
       end
 
       def execute_request(method, query_params = nil, body: nil, &)
+        attempt_request(method, query_params, body: body, retried: false, &)
+      rescue *NETWORK_ERRORS => e
+        raise ApiError.new("Network error: #{e.message}", code: :network_error)
+      end
+
+      def attempt_request(method, query_params, body:, retried:, &)
+        send_one_request(method, query_params, body: body, &)
+      rescue RateLimitError => e
+        wait = wait_for(e)
+        raise e if retried || wait.nil?
+
+        announce_wait(method, wait)
+        sleep(wait)
+        attempt_request(method, query_params, body: body, retried: true, &)
+      end
+
+      def send_one_request(method, query_params, body:, &)
+        await_reset(method)
         log_request(method)
         log_request_body(method, body)
         uri = build_uri(method, query_params)
         response, elapsed_ms = timed_request(uri, &)
+        track_rate_limit(method, response)
         log_response(method, response, elapsed_ms)
         log_response_body(method, response.body)
         handle_response(response, method)
-      rescue *NETWORK_ERRORS => e
-        raise ApiError, "Network error: #{e.message}"
+      end
+
+      def wait_for(error)
+        max = ENV.fetch('SLK_MAX_RETRY_AFTER', '60').to_i
+        seconds = error.retry_after || ENV.fetch('SLK_DEFAULT_RETRY_AFTER', '30').to_i
+        return nil unless seconds.positive? && seconds <= max
+
+        seconds
+      end
+
+      def announce_wait(method, seconds)
+        @on_response&.call(method, 'rate-wait', { 'sleep_seconds' => seconds })
+      end
+
+      # Predictive throttle: when X-RateLimit-Remaining hits 0, sleep until
+      # X-RateLimit-Reset before issuing the next call to that method.
+      def track_rate_limit(method, response)
+        remaining = response['X-RateLimit-Remaining']&.to_i
+        reset = response['X-RateLimit-Reset']&.to_i
+        @rate_resets[method] = reset if remaining&.zero? && reset&.positive?
+      end
+
+      def await_reset(method)
+        reset = @rate_resets[method] or return
+        wait = reset - Time.now.to_i
+        return @rate_resets.delete(method) if wait <= 0
+
+        max = ENV.fetch('SLK_MAX_RETRY_AFTER', '60').to_i
+        return if wait > max
+
+        announce_wait(method, wait)
+        sleep(wait)
+        @rate_resets.delete(method)
       end
 
       def build_uri(method, query_params)
@@ -167,26 +218,40 @@ module Slk
       def handle_response(response, _method)
         case response
         when Net::HTTPSuccess then parse_success_response(response)
-        when Net::HTTPUnauthorized then raise ApiError, 'Invalid token or session expired'
+        when Net::HTTPUnauthorized
+          raise ApiError.new('Invalid token or session expired', code: :unauthorized)
         when Net::HTTPTooManyRequests then handle_rate_limit(response)
-        else raise ApiError, "HTTP #{response.code}: #{response.message}"
+        else raise ApiError.new("HTTP #{response.code}: #{response.message}", code: :http_error)
         end
       end
 
       def handle_rate_limit(response)
-        retry_after = response['Retry-After']
-        raise ApiError, "Rate limited - retry after #{retry_after} seconds" if retry_after
-
-        raise ApiError, 'Rate limited - please wait and try again'
+        retry_after = response['Retry-After']&.to_i
+        message = retry_after ? "Rate limited — retry after #{retry_after}s" : 'Rate limited — please wait'
+        raise RateLimitError.new(message, retry_after: retry_after)
       end
 
       def parse_success_response(response)
         result = JSON.parse(response.body)
-        raise ApiError, result['error'] || 'Unknown error' unless result['ok']
+        raise_rate_limit(response) if result['error'] == 'ratelimited'
+        unless result['ok']
+          message = result['error'] || 'Unknown error'
+          raise ApiError.new(message, code: message.to_sym)
+        end
 
         result
       rescue JSON::ParserError
-        raise ApiError, 'Invalid JSON response from Slack API'
+        raise ApiError.new('Invalid JSON response from Slack API', code: :invalid_json)
+      end
+
+      def raise_rate_limit(response)
+        retry_after = response['Retry-After']&.to_i
+        message = if retry_after
+                    "Rate limited by Slack — retry after #{retry_after}s"
+                  else
+                    'Rate limited by Slack — wait a minute and try again'
+                  end
+        raise RateLimitError.new(message, retry_after: retry_after)
       end
     end
     # rubocop:enable Metrics/ClassLength