slk 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae44e63120d4264c9adeb4adb2ea9aba96c4fe9e6087c1134f9bd9d8480a843e
-  data.tar.gz: '087ea385b7cf62868737d1e583e60ec9fac5aee8bb3d49f711f5c979413db4e7'
+  metadata.gz: c56010125fc8e78293e4701ac5619742dda1fecd3e6e06ec98a3eb6afab0dc46
+  data.tar.gz: 05fad0411c6b216091bc9dd7cade46a36579bbba951042c61859111c57db9356
 SHA512:
-  metadata.gz: 71be8f27208e35f5dfe81c3504f38f40af7a7630d93802ba56316e07778aa631f7a42ffe1172b9b1c280735871c0667b5b6568a3bb0224642cdabf59523ac8c5
-  data.tar.gz: 9e4b991d52004df5100fe901e87c1b61f8c50a8fa501665f2cb0a5f58f31a37a6ffae6cbe5c287aac7ae2e99f679cea0889c80866f7980b7f495c7311a507c73
+  metadata.gz: 2ae292c3c50580e4872ec7a2334052b2495d0df8943341970d98f0a1922ea5b15d9612a0b8998de30bfb100100d3daf0567c9270fafef89529fc88c65f72634d
+  data.tar.gz: e86c76ce090e6a622a2122c068fb8a384520ff7b38193613f254f446f4a4165f09c48bcf944b2f3d5a2ad3435a0e71502bda8a6ec1b776b0b1b4bbc1ee240424

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-09-18
+
+### Added
+
+- **`slk deactivations`** — who left the workspace, and when
+  - Slack has no "who left" endpoint. It does have `users.list`, which returns departed accounts with `deleted: true` and an `updated` epoch for the last change to the account — and for a deactivated account that change is almost always the deactivation itself. The help text says so out loud, because an admin who edits a departed profile afterwards moves the date forward, and a date that looks authoritative but is not should say which it is
+  - Defaults to the 25 most recent departures, one per line with a full ISO date, so the output stays greppable. `-n 0` shows all of them
+  - `slk deactivations 90d` (or `--since 90d`, `--since 2026-01-01`) narrows to a window; `--grep` filters across name, handle, title, email and user ID
+  - `--chart` draws departures per calendar month across the whole window asked for, quiet months filled in with zero — a gap in a histogram should read as "nobody left", not as a month that never happened, and a quiet month at either end of the window still happened. Without `--since` it covers the last twelve months rather than the entire history of the workspace
+  - An account Slack never dated cannot answer a question about a window, so it drops out of one — but the footer says how many did, rather than discarding them in silence
+  - Bots and app users are excluded from the counts and the list; `--bots` puts them back
+  - The roster is one API call per 1000 members, so the derived result is cached for six hours. The footer says how old it is, because "nobody left this week" and "nobody left since the last time you asked" are different statements. `--refresh` re-fetches
+
 ## [0.8.0] - 2026-08-30
 
 ### Added

data/README.md

@@ -210,6 +210,36 @@ slk cache populate        # Pre-populate user cache
 slk cache clear           # Clear all caches
 ```
 
+### Deactivations
+
+```bash
+slk deactivations                 # 25 most recent departures
+slk deactivations 90d             # Everyone who left in the last 90 days
+slk deactivations 2026-01-01 -n 0 # All departures this year
+slk deactivations --chart         # Departures per month
+slk deactivations --grep engineer # Filter by name, handle, title, email, or ID
+slk deactivations --bots          # Include deactivated bots and app users
+slk deactivations --json          # Machine-readable output
+```
+
+```
+acme: 16 deactivated since 30d (664 active members)
+
+2026-09-14  Dana Whitfield          Platform Support
+2026-09-11  Priya Raghunathan       UX Researcher
+2026-09-09  Sam Okonkwo             Senior Software Engineer
+
+roster cached 5m ago; --refresh to update
+```
+
+Dates come from each account's `updated` field — the last change Slack recorded
+for that user. For a deactivated account that change is almost always the
+deactivation, but an admin editing a departed profile afterwards moves the date
+forward, so treat it as "last touched" rather than a payroll record.
+
+The roster costs one API call per 1000 members, so the result is cached for six
+hours; `--refresh` re-fetches it.
+
 ### Global Options
 
 ```bash

data/lib/slk/api/users.rb

@@ -3,6 +3,7 @@
 module Slk
   module Api
     # Wrapper for Slack users.* API endpoints
+    # rubocop:disable Metrics/ClassLength
     class Users
       def initialize(api_client, workspace, on_debug: nil)
         @api = api_client
@@ -63,6 +64,31 @@ module Slk
         @api.post(@workspace, 'users.list', params)
       end
 
+      # Page through users.list until the cursor runs out. Yields the running
+      # total after each page, for progress and debug output.
+      def list_all(limit: 1000, &progress)
+        members = []
+        cursor = nil
+        loop do
+          response = list(cursor: cursor, limit: limit)
+          members.concat(response['members'] || [])
+          progress&.call(members.size)
+          cursor = next_cursor(response, cursor)
+          break members unless cursor
+        end
+      end
+
+      # Slack ends the roster with an empty cursor. A cursor that comes back
+      # unchanged never will, and paging on it spins forever against a remote
+      # API — better to fail with the reason than to hang holding a terminal.
+      def next_cursor(response, previous)
+        cursor = response.dig('response_metadata', 'next_cursor').to_s
+        return nil if cursor.empty?
+        raise ApiError.new('users.list returned a repeating cursor', code: :invalid_cursor) if cursor == previous
+
+        cursor
+      end
+
       def info(user_id)
         @api.post_form(@workspace, 'users.info', { user: user_id })
       end
@@ -111,5 +137,6 @@ module Slk
         @api.post_form(@workspace, 'users.conversations', params)
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/slk/cli.rb

@@ -23,7 +23,8 @@ module Slk
       'help' => Commands::Help,
       'debug' => Commands::Debug,
       'who' => Commands::Who,
-      'org' => Commands::Org
+      'org' => Commands::Org,
+      'deactivations' => Commands::Deactivations
     }.freeze
 
     def initialize(argv, output: nil)

data/lib/slk/commands/deactivations.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Slk
+  module Commands
+    # Show who left the workspace and when, derived from users.list.
+    # Examples:
+    #   slk deactivations                 # 25 most recent departures
+    #   slk deactivations 90d             # everyone who left in the last 90 days
+    #   slk deactivations --chart         # departures per month
+    #   slk deactivations --grep engineer # filter by name, handle, title, email, ID
+    # rubocop:disable Metrics/ClassLength
+    class Deactivations < Base
+      DEFAULT_LIMIT = 25
+      CHART_MONTHS = 12
+
+      def execute
+        result = validate_options
+        return result if result
+
+        run
+      rescue ApiError => e
+        error("API error: #{e.message}")
+        1
+      end
+
+      protected
+
+      def handle_option(arg, args, _remaining)
+        case arg
+        when '-n', '--limit' then @options[:limit] = parse_limit(arg, option_value(arg, args))
+        when '--since' then @options[:since] = option_value(arg, args)
+        when '--chart' then @options[:chart] = true
+        when '--bots' then @options[:bots] = true
+        when '--grep' then @options[:grep] = option_value(arg, args)
+        when '--refresh', '--no-cache' then @options[:refresh] = true
+        else return super
+        end
+        true
+      end
+
+      def help_text
+        help = Support::HelpFormatter.new('slk deactivations [since] [options]')
+        help.description('Show deactivated accounts — who left the workspace, and when.')
+        help.note("Dates come from each account's `updated` field, which for a deactivated")
+        help.note('account is the deactivation itself unless an admin edited the profile after.')
+        add_options_section(help)
+        add_examples_section(help)
+        help.render
+      end
+
+      private
+
+      # Base defaults to 72 columns for prose wrapping; this is a table, so use
+      # the whole terminal and let long titles keep their tail. A tty that
+      # refuses to report its size (some Windows consoles, some CI shims) is
+      # not a reason to fail before the command has even parsed its arguments.
+      def default_width
+        return 100 unless $stdout.tty?
+
+        IO.console&.winsize&.last || 100
+      rescue Errno::ENOTTY, Errno::EINVAL, Errno::ENODEV, IOError, NotImplementedError
+        100
+      end
+
+      # `-n foo` used to reach to_i, become 0, and quietly mean "no limit" —
+      # the opposite of asking for fewer rows.
+      def parse_limit(flag, value)
+        limit = Integer(value, exception: false)
+        return limit if limit && !limit.negative?
+
+        raise UsageError, "#{flag} expects a non-negative integer (got #{value.inspect})."
+      end
+
+      def add_options_section(help)
+        help.section('OPTIONS') do |s|
+          s.option('-n, --limit N', "Rows to show (default #{DEFAULT_LIMIT}, 0 for all)")
+          s.option('--since SPEC', 'Only departures since 7d, 4w, 6m, or YYYY-MM-DD')
+          s.option('--chart', 'Histogram of departures per month')
+          s.option('--grep PATTERN', 'Filter by name, handle, title, email, or user ID')
+          s.option('--bots', 'Include deactivated bots and app users')
+          s.option('--refresh', 'Re-fetch the roster instead of using the cache')
+          s.option('--json', 'Raw JSON output')
+        end
+      end
+
+      def add_examples_section(help)
+        help.section('EXAMPLES') do |s|
+          s.example('slk deactivations', 'Most recent departures')
+          s.example('slk deactivations 90d', 'Everyone who left in the last 90 days')
+          s.example('slk deactivations --chart', 'Departures per month')
+          s.example('slk deactivations 2026-01-01 -n 0', 'All departures this year')
+        end
+      end
+
+      def run
+        workspace = runner.workspace(@options[:workspace])
+        @since_label = since_spec
+        @since = parse_since(@since_label)
+        report = scan(workspace)
+        records = collect_records(report)
+
+        return render_json(workspace, report, records) if @options[:json]
+
+        render(workspace, report, records)
+        0
+      end
+
+      # One window, or none. A second date is a different question, and
+      # answering the first one silently is how you misread the answer.
+      def since_spec
+        extra = positional_args[1..]
+        raise UsageError, "Unexpected argument: #{extra.first}. Only one time window is accepted." if extra&.any?
+
+        @options[:since] || positional_args.first
+      end
+
+      def collect_records(report)
+        records = filter(report.records)
+        @options[:chart] && @since.nil? ? last_year(records) : records
+      end
+
+      def render_json(workspace, report, records)
+        output_json(json_payload(workspace, report, records))
+        0
+      end
+
+      def scan(workspace)
+        Services::DeactivationScanner.new(
+          users_api: runner.users_api(workspace.name),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_debug: ->(msg) { output.debug(msg) }
+        ).scan(refresh: @options[:refresh])
+      end
+
+      # Filters compose: --bots, --since, --grep all narrow the same list.
+      # Records Slack never dated cannot answer a question about a window, so
+      # they drop out of one — but they are counted, not silently discarded.
+      def filter(records)
+        records = records.reject(&:bot) unless @options[:bots]
+        pattern = grep_pattern
+        records = records.select { |r| r.matches?(pattern) } if pattern
+        @undated = records.count { |r| r.deactivated_at.nil? }
+        reject_before(records, @since)
+      end
+
+      def reject_before(records, cutoff)
+        return records unless cutoff
+
+        records.select { |r| r.deactivated_at && r.deactivated_at >= cutoff }
+      end
+
+      # An all-time histogram of a decade-old workspace is mostly scrollback.
+      # Counting in months rather than in 31-day steps keeps the window exactly
+      # as long as the label claims.
+      def last_year(records)
+        reject_before(records, last_year_cutoff)
+      end
+
+      def last_year_cutoff
+        now = Time.now
+        index = (now.year * 12) + (now.month - 1) - (CHART_MONTHS - 1)
+        Time.new(index / 12, (index % 12) + 1, 1).to_i
+      end
+
+      # The chart spans the window that was asked for, not merely the months
+      # that happen to contain a departure: a quiet opening month is the
+      # answer to "how bad is it lately", and dropping it flatters the trend.
+      def chart_bounds
+        {
+          from: Time.at(@since || last_year_cutoff).strftime('%Y-%m'),
+          to: Time.now.strftime('%Y-%m')
+        }
+      end
+
+      def parse_since(spec)
+        return nil unless spec
+
+        Support::DateParser.parse(spec)
+      rescue ArgumentError => e
+        raise UsageError, e.message
+      end
+
+      def grep_pattern
+        return nil unless @options[:grep]
+
+        Regexp.new(@options[:grep], Regexp::IGNORECASE)
+      rescue RegexpError => e
+        raise UsageError, "Invalid --grep pattern: #{e.message}"
+      end
+
+      def render(workspace, report, records)
+        formatter = Formatters::DeactivationFormatter.new(output: output, width: @options[:width])
+        formatter.summary(summary_line(workspace, report, records))
+        render_body(formatter, records)
+        footer = footer(report, records)
+        return if footer.empty?
+
+        puts
+        formatter.note(footer)
+      end
+
+      # Even an empty result keeps its footer: "nobody matched" is worth much
+      # less without how old the roster behind it is.
+      def render_body(formatter, records)
+        return info('No deactivations match.') if records.empty?
+
+        puts
+        @options[:chart] ? formatter.chart(records, **chart_bounds) : render_list(formatter, records)
+      end
+
+      def render_list(formatter, records)
+        limit = @options[:limit] || DEFAULT_LIMIT
+        shown = limit.positive? ? records.first(limit) : records
+        formatter.list(shown)
+        return unless shown.size < records.size
+
+        puts
+        formatter.note("Showing #{shown.size} of #{records.size} — use -n 0 to see them all.")
+      end
+
+      def summary_line(workspace, report, records)
+        "#{workspace.name}: #{records.size} #{scope_phrase} " \
+          "(#{report.active_count} active members)"
+      end
+
+      def scope_phrase
+        return "deactivated since #{@since_label}" if @since_label
+
+        @options[:chart] ? "deactivated in the last #{CHART_MONTHS} months" : 'deactivated accounts'
+      end
+
+      def footer(report, records)
+        total = total_deactivated(report)
+        age = cache_age(report)
+        parts = []
+        parts << "#{total} deactivated in all (of #{report.human_count} accounts ever created)" if records.size < total
+        parts << undated_note if undated_note
+        parts << "roster cached #{age} ago; --refresh to update" if age
+        parts.join(' · ')
+      end
+
+      # Only worth saying when a window was applied: without one nothing was
+      # dropped for want of a date.
+      def undated_note
+        return nil unless windowed? && @undated.to_i.positive?
+
+        "#{@undated} with no recorded date omitted"
+      end
+
+      def windowed?
+        !@since.nil? || @options[:chart]
+      end
+
+      def total_deactivated(report)
+        return report.deactivated_count if @options[:bots]
+
+        report.records.count { |r| !r.bot }
+      end
+
+      def cache_age(report)
+        return nil unless report.fetched_at
+
+        seconds = Time.now.to_i - report.fetched_at
+        return nil if seconds < 60
+
+        Models::Duration.new(seconds: seconds).to_s
+      end
+
+      def json_payload(workspace, report, records)
+        {
+          workspace: workspace.name,
+          fetched_at: report.fetched_at,
+          active_members: report.active_count,
+          accounts_ever: report.human_count,
+          total_deactivated: total_deactivated(report),
+          includes_bots: @options[:bots] ? true : false,
+          matched: records.size,
+          deactivations: records.map { |r| r.to_h.merge(deactivated_on: r.date) }
+        }
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

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/deactivation_formatter.rb

@@ -0,0 +1,108 @@
+# 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, title. Full ISO dates on every row
+      # (rather than month headings) so the output stays greppable.
+      def list(records)
+        name_width = name_column_width(records)
+        records.each { |record| @output.puts(row(record, name_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)
+        date = record.date || 'unknown'
+        name = truncate(record.best_name.to_s, name_width).ljust(name_width)
+        title = truncate(record.title.to_s, title_width(name_width))
+        line = "#{@output.gray(date.ljust(DATE_WIDTH))}  #{name}"
+        title.empty? ? line : "#{line}  #{@output.gray(title)}"
+      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)
+        [@width - DATE_WIDTH - name_width - 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/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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Slk
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/lib/slk.rb

@@ -74,6 +74,7 @@ module Slk
     autoload :User, 'slk/models/user'
     autoload :Channel, 'slk/models/channel'
     autoload :Preset, 'slk/models/preset'
+    autoload :Deactivation, 'slk/models/deactivation'
     autoload :SearchResult, 'slk/models/search_result'
     autoload :SavedItem, 'slk/models/saved_item'
     autoload :Profile, 'slk/models/profile'
@@ -107,6 +108,7 @@ module Slk
     autoload :ProfileBuilder, 'slk/services/profile_builder'
     autoload :ProfileResolver, 'slk/services/profile_resolver'
     autoload :MetaCache, 'slk/services/meta_cache'
+    autoload :DeactivationScanner, 'slk/services/deactivation_scanner'
   end
 
   # Output formatters for messages, durations, and emoji
@@ -129,6 +131,7 @@ module Slk
     autoload :ProfileFormatter, 'slk/formatters/profile_formatter'
     autoload :ProfileFieldRenderer, 'slk/formatters/profile_field_renderer'
     autoload :ProfileRows, 'slk/formatters/profile_rows'
+    autoload :DeactivationFormatter, 'slk/formatters/deactivation_formatter'
   end
 
   # CLI commands implementing user-facing functionality
@@ -153,6 +156,7 @@ module Slk
     autoload :Debug, 'slk/commands/debug'
     autoload :Who, 'slk/commands/who'
     autoload :Org, 'slk/commands/org'
+    autoload :Deactivations, 'slk/commands/deactivations'
   end
 
   # Thin wrappers around Slack API endpoints

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Eric Boehs
@@ -45,6 +45,7 @@ files:
 - lib/slk/commands/cache.rb
 - lib/slk/commands/catchup.rb
 - lib/slk/commands/config.rb
+- lib/slk/commands/deactivations.rb
 - lib/slk/commands/debug.rb
 - lib/slk/commands/dnd.rb
 - lib/slk/commands/emoji.rb
@@ -64,6 +65,7 @@ files:
 - lib/slk/formatters/activity_formatter.rb
 - lib/slk/formatters/attachment_formatter.rb
 - lib/slk/formatters/block_formatter.rb
+- lib/slk/formatters/deactivation_formatter.rb
 - lib/slk/formatters/duration_formatter.rb
 - lib/slk/formatters/emoji_replacer.rb
 - lib/slk/formatters/json_message_formatter.rb
@@ -80,6 +82,7 @@ files:
 - lib/slk/formatters/search_formatter.rb
 - lib/slk/formatters/text_processor.rb
 - lib/slk/models/channel.rb
+- lib/slk/models/deactivation.rb
 - lib/slk/models/dnd_state.rb
 - lib/slk/models/duration.rb
 - lib/slk/models/message.rb
@@ -99,6 +102,7 @@ files:
 - lib/slk/services/api_client.rb
 - lib/slk/services/cache_store.rb
 - lib/slk/services/configuration.rb
+- lib/slk/services/deactivation_scanner.rb
 - lib/slk/services/emoji_downloader.rb
 - lib/slk/services/emoji_searcher.rb
 - lib/slk/services/encryption.rb