slk 0.5.0 → 0.7.0

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/models/scheduled_status.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # A status queued to turn on later, from users.customStatus.list.
+    #
+    # Slack derives `duration` server-side from the window, so it is not
+    # modelled here — the window itself is the source of truth.
+    ScheduledStatus = Data.define(:id, :text, :emoji, :date_scheduled, :date_expire, :dnd, :active) do
+      def self.from_api(data)
+        validate!(data)
+
+        new(
+          id: data['id'].to_s,
+          text: data['text'].to_s,
+          emoji: data['emoji'].to_s,
+          date_scheduled: data['date_scheduled'].to_i,
+          date_expire: data['date_expire'].to_i,
+          dnd: truthy?(data['is_dnd']),
+          active: truthy?(data['is_active'])
+        )
+      end
+
+      # Every field is coerced, so without this guard any payload at all —
+      # a bare string, nil, a hash of unexpected keys — becomes a valid-looking
+      # record with an empty id that prints as a blank line and never matches
+      # the id the user asked about. An unusable record is a protocol change,
+      # not a status.
+      def self.validate!(data)
+        return if data.is_a?(Hash) && !data['id'].to_s.empty?
+
+        raise ApiError.new("Slack returned a scheduled status with no id: #{data.inspect[0, 120]}",
+                           code: :malformed_scheduled_status)
+      end
+      private_class_method :validate!
+
+      # These endpoints are string-typed on the way in — Api::CustomStatus sends
+      # is_dnd as 'true' — so a strict `== true` would quietly read a scheduled
+      # DND back as off. Accept the shapes Slack actually uses.
+      def self.truthy?(value) = [true, 'true', 1, '1'].include?(value)
+      private_class_method :truthy?
+
+      def starts_at = date_scheduled.positive? ? Time.at(date_scheduled) : nil
+      def ends_at = date_expire.positive? ? Time.at(date_expire) : nil
+
+      def to_s
+        span = window
+        [
+          emoji,
+          text,
+          span.empty? ? '' : "(#{span})",
+          ('[dnd]' if dnd),
+          # Slack marks the one that has already turned on. Worth showing: it
+          # is the difference between "will happen" and "is happening".
+          ('[active]' if active)
+        ].reject { |part| part.to_s.empty? }.join(' ')
+      end
+
+      # Human-readable window; the end date is only repeated when it differs
+      # from the start date, which makes multi-day windows obvious.
+      def window
+        dated = '%a %b %-d %-l:%M%P'
+        start_time = starts_at or return ''
+        formatted = start_time.strftime(dated)
+        finish = ends_at or return formatted
+
+        "#{formatted} -> #{finish.strftime(same_day?(start_time, finish) ? '%-l:%M%P' : dated)}"
+      end
+
+      private
+
+      def same_day?(start_time, finish)
+        start_time.to_date == finish.to_date
+      end
+    end
+  end
+end

data/lib/slk/runner.rb

@@ -88,6 +88,27 @@ module Slk
       Api::Saved.new(@api_client, workspace(workspace_name))
     end
 
+    def custom_status_api(workspace_name = nil)
+      Api::CustomStatus.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/encryption.rb

@@ -104,8 +104,15 @@ module Slk
               'Please provide the correct public key for this private key.'
       end
 
+      # `-P ''` supplies the passphrase up front so ssh-keygen cannot ask for
+      # one. Without it, an encrypted key makes ssh-keygen prompt — and it
+      # prompts on the console directly, not on the stdin capture3 hands it, so
+      # closing stdin does not help. On Windows that read blocks forever; this
+      # hung the CI job until its timeout with no output. An empty passphrase
+      # fails an encrypted key with the same message it already reported, which
+      # is the right answer regardless: slk cannot use such a key anyway.
       def derive_public_key(private_key_path)
-        output, error, status = Open3.capture3('ssh-keygen', '-y', '-f', private_key_path)
+        output, error, status = Open3.capture3('ssh-keygen', '-y', '-P', '', '-f', private_key_path)
         return output.strip if status.success?
 
         # Check if ssh-keygen is missing vs other failures

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