slk 0.8.0 → 0.10.0

data/lib/slk/commands/help.rb

@@ -4,6 +4,26 @@ module Slk
   module Commands
     # Displays help information for commands
     class Help < Base
+      # Names are padded to the longest one rather than by hand, so adding a
+      # command cannot quietly break the column for every line below it.
+      COMMAND_SUMMARIES = [
+        ['status', 'Get or set your status'],
+        ['presence', 'Get or set your presence (away/active)'],
+        ['dnd', 'Manage Do Not Disturb'],
+        ['messages', 'Read channel or DM messages'],
+        ['search', 'Search messages across channels'],
+        ['unread', 'View and clear unread messages'],
+        ['activity', 'Show activity feed (reactions, mentions, threads)'],
+        ['later', 'Show saved "Later" items'],
+        ['who', 'Show a user profile'],
+        ['deactivations', 'Show who left the workspace, and when'],
+        ['preset', 'Manage and apply status presets'],
+        ['workspaces', 'Manage Slack workspaces'],
+        ['cache', 'Manage user/channel cache'],
+        ['emoji', 'Download workspace custom emoji'],
+        ['config', 'Configuration and setup']
+      ].freeze
+
       def execute
         topic = positional_args.first
 
@@ -35,26 +55,13 @@ module Slk
         HEADER
       end
 
-      # rubocop:disable Metrics/AbcSize
       def build_commands_section
-        <<~COMMANDS
-          #{output.bold('COMMANDS:')}
-            #{output.cyan('status')}       Get or set your status
-            #{output.cyan('presence')}     Get or set your presence (away/active)
-            #{output.cyan('dnd')}          Manage Do Not Disturb
-            #{output.cyan('messages')}     Read channel or DM messages
-            #{output.cyan('search')}       Search messages across channels
-            #{output.cyan('unread')}       View and clear unread messages
-            #{output.cyan('activity')}     Show activity feed (reactions, mentions, threads)
-            #{output.cyan('later')}        Show saved "Later" items
-            #{output.cyan('preset')}       Manage and apply status presets
-            #{output.cyan('workspaces')}   Manage Slack workspaces
-            #{output.cyan('cache')}        Manage user/channel cache
-            #{output.cyan('emoji')}        Download workspace custom emoji
-            #{output.cyan('config')}       Configuration and setup
-        COMMANDS
+        width = COMMAND_SUMMARIES.map { |name, _| name.length }.max + 2
+        rows = COMMAND_SUMMARIES.map do |name, summary|
+          "  #{output.cyan(name)}#{' ' * (width - name.length)}#{summary}"
+        end
+        "#{output.bold('COMMANDS:')}\n#{rows.join("\n")}\n"
       end
-      # rubocop:enable Metrics/AbcSize
 
       def build_options_section
         <<~OPTIONS

data/lib/slk/formatters/csv_writer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # RFC 4180 CSV, hand-rolled: Ruby 3.4 moved csv out of the default gems
+    # and into the bundled ones, so requiring it would make this tool depend
+    # on a gem, and it ships with none.
+    #
+    # Quotes only the fields that need it, so the common row stays readable in
+    # a terminal as well as in a spreadsheet.
+    module CsvWriter
+      module_function
+
+      NEEDS_QUOTES = /[",\r\n]|\A\s|\s\z/
+
+      def row(values)
+        values.map { |value| escape(value) }.join(',')
+      end
+
+      def escape(value)
+        text = stringify(value)
+        return text unless NEEDS_QUOTES.match?(text)
+
+        %("#{text.gsub('"', '""')}")
+      end
+
+      # nil is an empty cell. Writing the literal "nil" would give a
+      # spreadsheet a four-character string to count, sort and average.
+      def stringify(value)
+        value.nil? ? '' : value.to_s
+      end
+    end
+  end
+end

data/lib/slk/formatters/deactivation_csv.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # CSV export of a deactivation list, for the spreadsheet that inevitably
+    # gets asked for. Every matched row is written, not just the screenful a
+    # terminal would show — a truncated export is a wrong answer that looks
+    # like a right one.
+    class DeactivationCsv
+      HEADERS = %w[deactivated_on user_id handle real_name title email bot].freeze
+      TENURE_HEADERS = %w[started_on tenure_months tenure].freeze
+
+      def initialize(output:, tenures: nil)
+        @output = output
+        @tenures = tenures
+      end
+
+      def render(records)
+        @output.puts(CsvWriter.row(headers))
+        records.each { |record| @output.puts(CsvWriter.row(cells(record))) }
+      end
+
+      private
+
+      def headers
+        @tenures ? HEADERS + TENURE_HEADERS : HEADERS
+      end
+
+      def cells(record)
+        row = [record.date, record.user_id, record.handle, record.real_name,
+               record.title, record.email, record.bot]
+        @tenures ? row + tenure_cells(record) : row
+      end
+
+      # Empty cells rather than zeros, so a spreadsheet averaging tenure skips
+      # them instead of counting people who left the day they arrived. Two
+      # different unknowns land here: no start date on file at all, which
+      # blanks the whole group, and a start date later than the departure,
+      # which keeps started_on so the bad data is visible and blanks the
+      # length that cannot be derived from it.
+      def tenure_cells(record)
+        tenure = @tenures[record.user_id]
+        return [nil, nil, nil] unless tenure
+
+        [tenure.started, tenure.months, tenure.to_s]
+      end
+    end
+  end
+end

data/lib/slk/formatters/deactivation_formatter.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Renders deactivation lists and per-month histograms.
+    class DeactivationFormatter
+      DATE_WIDTH = 10
+      MAX_NAME_WIDTH = 26
+      MIN_TITLE_WIDTH = 12
+      MAX_BAR_WIDTH = 48
+      BAR_CHARS = '█'
+
+      def initialize(output:, width: nil)
+        @output = output
+        @width = width || 100
+      end
+
+      # One line per departure: date, name, tenure, title. Full ISO dates on
+      # every row (rather than month headings) so the output stays greppable.
+      #
+      # `tenures` is keyed by user ID and may cover only some of the rows: a
+      # start date nobody filled in leaves the column blank rather than
+      # guessing, and the column disappears entirely when none are known.
+      def list(records, tenures: {})
+        name_width = name_column_width(records)
+        tenure_width = tenure_column_width(records, tenures)
+        records.each { |record| @output.puts(row(record, name_width, tenures, tenure_width)) }
+      end
+
+      def chart(records, from: nil, to: nil)
+        counts = monthly_counts(records, from: from, to: to)
+        return if counts.empty?
+
+        peak = counts.values.max
+        label_width = counts.values.map { |n| n.to_s.length }.max
+        counts.each { |month, count| @output.puts(chart_row(month, count, peak, label_width)) }
+      end
+
+      def summary(text)
+        @output.puts(@output.bold(text))
+      end
+
+      def note(text)
+        @output.puts(@output.gray(text))
+      end
+
+      # Deactivations per calendar month, oldest first, with empty months
+      # filled in — a gap in a histogram should read as zero, not as absence.
+      # `from`/`to` widen the span to the window the caller asked about, so a
+      # quiet first or last month is shown as quiet rather than dropped.
+      def monthly_counts(records, from: nil, to: nil)
+        months = records.filter_map(&:month).sort
+        first = [from, months.first].compact.min
+        last = [to, months.last].compact.max
+        return {} if first.nil? || last.nil? || first > last
+
+        all_months(first, last).to_h do |month|
+          [month, months.count(month)]
+        end
+      end
+
+      private
+
+      def chart_row(month, count, peak, label_width)
+        bar = BAR_CHARS * bar_length(count, peak)
+        "#{@output.gray(month)}  #{count.to_s.rjust(label_width)}  #{bar}".rstrip
+      end
+
+      def row(record, name_width, tenures = {}, tenure_width = 0)
+        line = "#{@output.gray((record.date || 'unknown').ljust(DATE_WIDTH))}  " \
+               "#{truncate(record.best_name.to_s, name_width).ljust(name_width)}"
+        line = "#{line}  #{@output.gray(tenure_cell(record, tenures, tenure_width))}" if tenure_width.positive?
+        title = truncate(record.title.to_s, title_width(name_width, tenure_width))
+        title.empty? ? line : "#{line}  #{@output.gray(title)}"
+      end
+
+      def tenure_cell(record, tenures, width)
+        tenures[record.user_id].to_s.rjust(width)
+      end
+
+      def tenure_column_width(records, tenures)
+        return 0 if tenures.nil? || tenures.empty?
+
+        records.filter_map { |r| tenures[r.user_id]&.to_s&.length }.max || 0
+      end
+
+      def name_column_width(records)
+        longest = records.map { |r| r.best_name.to_s.length }.max || 0
+        longest.clamp(8, MAX_NAME_WIDTH)
+      end
+
+      def title_width(name_width, tenure_width = 0)
+        tenure_space = tenure_width.positive? ? tenure_width + 2 : 0
+        [@width - DATE_WIDTH - name_width - tenure_space - 4, MIN_TITLE_WIDTH].max
+      end
+
+      # A month nobody left gets no bar at all. Rounding a zero up to one
+      # block would draw departures that did not happen.
+      def bar_length(count, peak)
+        return 0 if peak.zero? || count.zero?
+
+        available = (@width - 16).clamp(10, MAX_BAR_WIDTH)
+        [((count.to_f / peak) * available).round, 1].max
+      end
+
+      def truncate(text, width)
+        return text if text.length <= width
+
+        "#{text[0, width - 1]}…"
+      end
+
+      def all_months(first, last)
+        (month_index(first)..month_index(last)).map do |index|
+          format('%<year>04d-%<month>02d', year: index / 12, month: (index % 12) + 1)
+        end
+      end
+
+      def month_index(month)
+        year, mon = month.split('-').map(&:to_i)
+        (year * 12) + (mon - 1)
+      end
+    end
+  end
+end

data/lib/slk/formatters/output.rb

@@ -26,6 +26,7 @@ module Slk
         @color = color.nil? ? io.tty? : color
         @verbose = verbose
         @quiet = quiet
+        @last_progress_width = nil
       end
 
       def puts(message = '')
@@ -52,6 +53,44 @@ module Slk
         puts(colorize(message))
       end
 
+      # Transient progress on stderr: it never pollutes piped stdout, and it
+      # overwrites itself rather than scrolling. Silent under --quiet, and
+      # when stderr is not a terminal, since a log file full of half-drawn
+      # counters helps nobody.
+      def progress(message)
+        return unless progress?
+
+        @last_progress_width = message.length
+        write_progress("\r#{message}")
+      end
+
+      # Erases whatever progress() last drew. Keyed off the saved width rather
+      # than re-checking tty state: if a line was drawn, it gets cleaned up.
+      def clear_progress
+        return unless @last_progress_width
+
+        write_progress("\r#{' ' * @last_progress_width}\r")
+        @last_progress_width = nil
+      end
+
+      # This is decoration. It is often called from an ensure block cleaning
+      # up after a real failure, and a closed or broken stderr must not
+      # replace that failure with one about drawing a counter.
+      def write_progress(text)
+        @err.print(text)
+        @err.flush
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      def progress? = tty_err? && !@quiet
+
+      def tty_err?
+        @err.tty?
+      rescue SystemCallError, IOError
+        false
+      end
+
       def debug(message)
         return unless @verbose
 

data/lib/slk/models/deactivation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # A deactivated Slack account and when it was deactivated.
+    #
+    # `deactivated_at` comes from the user object's `updated` field, which is
+    # the epoch of the last change to that account. For a deactivated account
+    # the deactivation is almost always that last change — but an admin who
+    # edits a departed user's profile afterwards moves the timestamp forward,
+    # so treat it as "last touched", not a payroll record.
+    Deactivation = Data.define(
+      :user_id, :handle, :real_name, :title, :email, :deactivated_at, :bot
+    ) do
+      def self.from_api(member)
+        profile = member['profile'] || {}
+
+        new(
+          user_id: member['id'],
+          handle: member['name'],
+          real_name: profile['real_name'] || member['real_name'],
+          title: profile['title'],
+          email: profile['email'],
+          deactivated_at: positive_int(member['updated']),
+          bot: bot?(member)
+        )
+      end
+
+      # Rebuild from a JSON round-trip through the meta cache.
+      def self.from_cache(hash)
+        new(
+          user_id: hash['user_id'], handle: hash['handle'], real_name: hash['real_name'],
+          title: hash['title'], email: hash['email'],
+          deactivated_at: positive_int(hash['deactivated_at']), bot: hash['bot'] ? true : false
+        )
+      end
+
+      def self.bot?(member)
+        member['is_bot'] || member['is_app_user'] || member['id'] == 'USLACKBOT' ? true : false
+      end
+
+      def self.positive_int(value)
+        int = value.to_i
+        int.positive? ? int : nil
+      end
+
+      def best_name
+        return real_name unless real_name.to_s.empty?
+        return handle unless handle.to_s.empty?
+
+        user_id.to_s
+      end
+
+      def deactivated_time
+        deactivated_at && Time.at(deactivated_at)
+      end
+
+      def date
+        deactivated_time&.strftime('%Y-%m-%d')
+      end
+
+      def month
+        deactivated_time&.strftime('%Y-%m')
+      end
+
+      # Matches the caller's pattern against every field a human would search
+      # by. Case sensitivity is the pattern's to declare, not this method's.
+      def matches?(pattern)
+        [handle, real_name, title, email, user_id].compact.any? { |field| pattern.match?(field) }
+      end
+
+      def to_cache
+        to_h.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/slk/models/tenure.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # How long someone was here: a start date from their Slack profile and the
+    # date their account was deactivated.
+    #
+    # Both ends are softer than they look. The start date is whatever an admin
+    # typed into a custom profile field, and the end is the account's `updated`
+    # timestamp. Neither is a payroll record, so this rounds to whole months
+    # and refuses to imply a precision it does not have.
+    Tenure = Data.define(:started_on, :ended_on) do
+      # @param started [String, nil] ISO date from the profile field
+      # @param ended [Time, nil] deactivation time
+      def self.build(started, ended)
+        date = parse_date(started)
+        return nil unless date
+
+        new(started_on: date, ended_on: ended ? to_date(ended) : nil)
+      end
+
+      def self.parse_date(value)
+        text = value.to_s.strip
+        return nil unless /\A\d{4}-\d{2}-\d{2}\z/.match?(text)
+
+        Date.iso8601(text)
+      rescue Date::Error
+        nil
+      end
+
+      def self.to_date(time)
+        Date.new(time.year, time.month, time.day)
+      end
+
+      # Nil when the account is still active, or when the end predates the
+      # start — a start date typed in after the fact can land anywhere, and a
+      # negative tenure is a data entry error, not a fact about a person.
+      def months
+        return nil unless ended_on && ended_on >= started_on
+
+        ended_on.day < started_on.day ? month_span - 1 : month_span
+      end
+
+      def month_span
+        ((ended_on.year - started_on.year) * 12) + (ended_on.month - started_on.month)
+      end
+      private :month_span
+
+      # "6y 2mo", "11mo", "<1mo" — whole months only.
+      def to_s
+        total = months
+        return '' unless total
+        return '<1mo' if total.zero?
+
+        years, rest = total.divmod(12)
+        [years.positive? ? "#{years}y" : nil, rest.positive? ? "#{rest}mo" : nil].compact.join(' ')
+      end
+
+      # True when the length cannot be worked out: an active account, or an
+      # end date that predates the start.
+      def unknown? = months.nil?
+
+      def started = started_on.iso8601
+    end
+  end
+end

data/lib/slk/services/api_client.rb

@@ -232,7 +232,7 @@ module Slk
       end
 
       def parse_success_response(response)
-        result = JSON.parse(response.body)
+        result = parse_body(response.body)
         raise_rate_limit(response) if result['error'] == 'ratelimited'
         unless result['ok']
           message = result['error'] || 'Unknown error'
@@ -240,6 +240,17 @@ module Slk
         end
 
         result
+      end
+
+      # Every caller treats a response as a Hash and digs into it. Slack
+      # sending a bare array, string or null is not something any of them can
+      # act on, so it fails here as an API error rather than as a TypeError
+      # somewhere downstream.
+      def parse_body(body)
+        result = JSON.parse(body)
+        return result if result.is_a?(Hash)
+
+        raise ApiError.new('Unexpected response shape from Slack API', code: :invalid_response)
       rescue JSON::ParserError
         raise ApiError.new('Invalid JSON response from Slack API', code: :invalid_json)
       end

data/lib/slk/services/cache_store.rb

@@ -135,6 +135,19 @@ module Slk
         end
       end
 
+      # The meta cache holds everything that is neither a user nor a channel:
+      # start dates, the deactivation roster, resolved profiles. "Clear all
+      # caches" was not telling the truth while this was left behind.
+      def clear_meta_cache(workspace_name = nil)
+        if workspace_name
+          @meta_cache.delete(workspace_name)
+          FileUtils.rm_f(meta_cache_file(workspace_name))
+        else
+          @meta_cache.clear
+          Dir.glob(@paths.cache_file('meta-*.json')).each { |f| FileUtils.rm_f(f) }
+        end
+      end
+
       # Subteam cache methods
       def get_subteam(workspace_name, subteam_id)
         load_subteam_cache(workspace_name)
@@ -199,6 +212,12 @@ module Slk
         @on_warning&.call("#{cache_type} cache corrupted for #{workspace_name}: #{e.message}. Cache will be rebuilt.")
         safely_delete_file(file)
         {}
+      rescue SystemCallError, IOError => e
+        # An unreadable cache file is the same situation as a corrupt one:
+        # carry on without it. Not deleted, because a file we cannot read is
+        # one we probably cannot remove either, and it may not be ours.
+        @on_warning&.call("#{cache_type} cache unreadable for #{workspace_name}: #{e.message}. Continuing without it.")
+        {}
       end
 
       def safely_delete_file(file)

data/lib/slk/services/deactivation_scanner.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Slack has no "who left" endpoint. What it does have is users.list, which
+    # returns deactivated accounts with `deleted: true` and an `updated` epoch
+    # for the last change to the account — and for a deactivated account that
+    # change is nearly always the deactivation itself.
+    #
+    # The full roster is one API call per 1000 members, so the derived result
+    # (deactivated members plus headcounts, not the whole roster) is cached in
+    # the workspace meta cache with a TTL.
+    class DeactivationScanner
+      CACHE_KEY = 'deactivations_v1'
+      DEFAULT_TTL = 21_600 # 6 hours
+      REQUIRED_KEYS = %w[fetched_at member_count human_count active_count records].freeze
+
+      Report = Data.define(:records, :member_count, :human_count, :active_count, :fetched_at) do
+        def deactivated_count = records.size
+
+        def bots = records.count(&:bot)
+      end
+
+      def initialize(users_api:, workspace_name:, cache_store: nil, ttl: DEFAULT_TTL, on_debug: nil)
+        @users_api = users_api
+        @workspace_name = workspace_name
+        @cache = cache_store
+        @ttl = ttl
+        @on_debug = on_debug
+      end
+
+      # @return [Report] every deactivated account, newest deactivation first
+      def scan(refresh: false)
+        build_report(cached(refresh: refresh) || store(collect))
+      end
+
+      private
+
+      def cached(refresh:)
+        return nil if refresh
+
+        data = MetaCache.read(@cache, @workspace_name, CACHE_KEY, ttl: @ttl)
+        return data if usable?(data)
+
+        @on_debug&.call('deactivations cache is unusable; re-fetching the roster') if data
+        nil
+      end
+
+      # A truncated or older-shaped entry would otherwise be read field by
+      # field into a report of zero active members and zero departures — a
+      # confident, wrong answer. Missing anything required means refetch.
+      def usable?(data)
+        data.is_a?(Hash) && data['records'].is_a?(Array) && REQUIRED_KEYS.all? { |key| data[key] }
+      end
+
+      def store(data)
+        MetaCache.write(@cache, @workspace_name, CACHE_KEY, data)
+        data
+      end
+
+      def collect
+        members = fetch_members
+        deleted = members.select { |m| m['deleted'] }
+
+        counts(members).merge(
+          'fetched_at' => Time.now.to_i,
+          'records' => deleted.map { |m| Models::Deactivation.from_api(m).to_cache }
+        )
+      end
+
+      def counts(members)
+        humans = members.reject { |m| Models::Deactivation.bot?(m) }
+
+        {
+          'member_count' => members.size,
+          'human_count' => humans.size,
+          'active_count' => humans.count { |m| !m['deleted'] }
+        }
+      end
+
+      def fetch_members
+        @users_api.list_all do |total|
+          @on_debug&.call("users.list: #{total} members fetched")
+        end
+      end
+
+      def build_report(data)
+        Report.new(
+          records: sorted_records(data['records'] || []),
+          member_count: data['member_count'].to_i,
+          human_count: data['human_count'].to_i,
+          active_count: data['active_count'].to_i,
+          fetched_at: data['fetched_at']&.to_i
+        )
+      end
+
+      # Newest first; accounts with no usable timestamp sort to the bottom
+      # rather than pretending to be from 1970.
+      def sorted_records(raw)
+        raw.map { |hash| Models::Deactivation.from_cache(hash) }
+           .sort_by { |record| -(record.deactivated_at || 0) }
+      end
+    end
+  end
+end

data/lib/slk/services/meta_cache.rb

@@ -7,6 +7,8 @@ module Slk
     module MetaCache
       module_function
 
+      # A write failure here is deliberately dropped: fetch's caller wants the
+      # value, and callers that need to report a cold cache use write directly.
       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
@@ -22,10 +24,23 @@ module Slk
         cache_store.get_meta(workspace_name, key, ttl: ttl)
       end
 
+      # A cache write that fails must never cost the caller the work it just
+      # did — a full or read-only disk means "no cache", not "no answer", and
+      # some of these writes sit behind minutes of rate-limited API calls.
+      #
+      # A nil or false value is treated as nothing to store, since no caller
+      # caches a negative this way — the start date lookup caches per-user
+      # nils inside a Hash, which is a value like any other.
+      #
+      # @return [Exception, nil] the write failure, for callers that want to
+      #   mention it; nil when the write succeeded or there was nothing to do
       def write(cache_store, workspace_name, key, value)
-        return unless cache_store && workspace_name && value
+        return nil unless cache_store && workspace_name && value
 
         cache_store.set_meta(workspace_name, key, value)
+        nil
+      rescue SystemCallError, IOError => e
+        e
       end
     end
   end