slk 0.5.0 → 0.6.0

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

data/lib/slk/services/cache_store.rb

@@ -12,10 +12,37 @@ module Slk
         @user_cache = {}
         @channel_cache = {}
         @subteam_cache = {}
+        @meta_cache = {}
         @on_warning = nil
         @on_cache_access = nil
       end
 
+      # Workspace metadata cache (auth.test user_id, team.info team_id,
+      # team.profile.get schema). One JSON file per workspace; entries can
+      # carry an optional fetched_at epoch for TTL checks.
+      def get_meta(workspace_name, key, ttl: nil)
+        load_meta_cache(workspace_name)
+        entry = @meta_cache[workspace_name][key]
+        return nil unless entry
+        return nil if ttl && entry['fetched_at'] && Time.now.to_i - entry['fetched_at'] > ttl
+
+        log_cache_access('meta', workspace_name, key, entry['value'])
+        entry['value']
+      end
+
+      def set_meta(workspace_name, key, value, persist: true)
+        load_meta_cache(workspace_name)
+        @meta_cache[workspace_name] ||= {}
+        @meta_cache[workspace_name][key] = { 'value' => value, 'fetched_at' => Time.now.to_i }
+        save_meta_cache(workspace_name) if persist
+        value
+      end
+
+      def each_meta(workspace_name)
+        load_meta_cache(workspace_name)
+        (@meta_cache[workspace_name] || {}).each
+      end
+
       # User cache methods
       def get_user(workspace_name, user_id)
         load_user_cache(workspace_name)
@@ -126,12 +153,12 @@ module Slk
       # Cache status
       def user_cache_size(workspace_name)
         load_user_cache(workspace_name)
-        @user_cache[workspace_name]&.size || 0
+        @user_cache[workspace_name].size
       end
 
       def channel_cache_size(workspace_name)
         load_channel_cache(workspace_name)
-        @channel_cache[workspace_name]&.size || 0
+        @channel_cache[workspace_name].size
       end
 
       def user_cache_file_exists?(workspace_name)
@@ -208,6 +235,23 @@ module Slk
         @paths.cache_file("subteams-#{workspace_name}.json")
       end
 
+      def meta_cache_file(workspace_name)
+        @paths.cache_file("meta-#{workspace_name}.json")
+      end
+
+      def load_meta_cache(workspace_name)
+        return if @meta_cache.key?(workspace_name)
+
+        @meta_cache[workspace_name] = load_cache_file(meta_cache_file(workspace_name), 'Meta', workspace_name)
+      end
+
+      def save_meta_cache(workspace_name)
+        return if @meta_cache[workspace_name].nil? || @meta_cache[workspace_name].empty?
+
+        @paths.ensure_cache_dir
+        File.write(meta_cache_file(workspace_name), JSON.pretty_generate(@meta_cache[workspace_name]))
+      end
+
       def log_cache_access(type, workspace, key, result)
         return unless @on_cache_access
 

data/lib/slk/services/meta_cache.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Read-through wrapper around CacheStore#get_meta/#set_meta with optional
+    # TTL and refresh override. Used by ProfileResolver and similar services.
+    module MetaCache
+      module_function
+
+      def fetch(cache_store, workspace_name, key, ttl: nil, refresh: false)
+        cached = read(cache_store, workspace_name, key, ttl: ttl) unless refresh
+        return cached if cached
+
+        value = yield
+        write(cache_store, workspace_name, key, value)
+        value
+      end
+
+      def read(cache_store, workspace_name, key, ttl: nil)
+        return nil unless cache_store && workspace_name
+
+        cache_store.get_meta(workspace_name, key, ttl: ttl)
+      end
+
+      def write(cache_store, workspace_name, key, value)
+        return unless cache_store && workspace_name && value
+
+        cache_store.set_meta(workspace_name, key, value)
+      end
+    end
+  end
+end

data/lib/slk/services/profile_builder.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Builds Models::Profile from raw users.profile.get + users.info +
+    # team.profile.get responses. Pure data assembly — no API calls.
+    module ProfileBuilder
+      module_function
+
+      # rubocop:disable Metrics/MethodLength
+      def build(profile_response:, info_response: nil, schema_response: nil, workspace_team_id: nil)
+        info_data = extract_info(info_response)
+        profile_data = extract_profile(profile_response, info_data)
+        schema = extract_schema(schema_response)
+        team_id = info_data['team_id'] || profile_data['team']
+
+        Models::Profile.new(
+          **identity(profile_data, info_data),
+          **status(profile_data),
+          **tz(info_data),
+          **flags(info_data, team_id, workspace_team_id),
+          team_id: team_id,
+          home_team_name: nil,
+          presence: nil,
+          sections: schema[:sections],
+          custom_fields: build_fields(profile_data['fields'] || {}, schema[:fields_by_id]),
+          resolved_users: {}
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Slack Connect external users often fail users.profile.get with
+      # user_not_found, but users.info still returns the same fields nested at
+      # user.profile. Fall back to that so we render a useful card.
+      def extract_profile(response, info_data = {})
+        primary = response.is_a?(Hash) ? (response['profile'] || {}) : {}
+        return primary unless primary.empty?
+
+        info_data['profile'] || {}
+      end
+
+      def extract_info(response)
+        return {} unless response.is_a?(Hash)
+
+        response['user'] || {}
+      end
+
+      def extract_schema(response)
+        section = response.is_a?(Hash) ? (response['profile'] || {}) : {}
+        fields = section['fields'] || []
+        {
+          fields_by_id: fields.to_h { |f| [f['id'], f] },
+          sections: section['sections'] || []
+        }
+      end
+
+      def identity(profile_data, info_data)
+        names(profile_data, info_data).merge(contact(profile_data))
+      end
+
+      def names(profile_data, info_data)
+        {
+          user_id: info_data['id'] || profile_data['id'] || '',
+          real_name: profile_data['real_name'] || info_data['real_name'],
+          display_name: profile_data['display_name'],
+          first_name: profile_data['first_name'],
+          last_name: profile_data['last_name']
+        }
+      end
+
+      def contact(profile_data)
+        {
+          title: profile_data['title'],
+          email: profile_data['email'],
+          phone: profile_data['phone'],
+          pronouns: profile_data['pronouns'],
+          image_url: profile_data['image_512'] || profile_data['image_192'] || profile_data['image_72'],
+          start_date: profile_data['start_date']
+        }
+      end
+
+      def status(profile_data)
+        {
+          status_text: profile_data['status_text'] || '',
+          status_emoji: profile_data['status_emoji'] || '',
+          status_expiration: profile_data['status_expiration'] || 0
+        }
+      end
+
+      def tz(info_data)
+        {
+          tz: info_data['tz'],
+          tz_label: info_data['tz_label'],
+          tz_offset: info_data['tz_offset'] || 0
+        }
+      end
+
+      def flags(info_data, team_id, workspace_team_id)
+        {
+          is_admin: info_data['is_admin'] || false,
+          is_owner: info_data['is_owner'] || false,
+          is_bot: info_data['is_bot'] || false,
+          is_external: external?(team_id, workspace_team_id),
+          deleted: info_data['deleted'] == true
+        }
+      end
+
+      def external?(team_id, workspace_team_id)
+        !!(workspace_team_id && team_id && team_id != workspace_team_id)
+      end
+
+      def build_fields(profile_fields, schema_fields_by_id)
+        profile_fields.map do |field_id, field_data|
+          build_field(field_id, field_data, schema_fields_by_id[field_id] || {})
+        end
+      end
+
+      def build_field(field_id, field_data, schema)
+        Models::ProfileField.new(
+          id: field_id, label: field_data['label'] || schema['label'] || field_id,
+          value: field_data['value'].to_s, alt: field_data['alt'].to_s,
+          type: schema['type'] || 'text', ordering: schema['ordering'].to_i,
+          section_id: schema['section_id'],
+          hidden: schema['is_hidden'] == true, inverse: schema['is_inverse'] == true
+        )
+      end
+    end
+  end
+end