slk 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 895e4fdd405a7b4f560424a93d4906ea7330088763a5559b2d581788908794b3
-  data.tar.gz: 6f8c66d9cd6555153db454d99d7cafdf4e82bbaac2f6349edee1427047e31104
+  metadata.gz: c56010125fc8e78293e4701ac5619742dda1fecd3e6e06ec98a3eb6afab0dc46
+  data.tar.gz: 05fad0411c6b216091bc9dd7cade46a36579bbba951042c61859111c57db9356
 SHA512:
-  metadata.gz: 7394318fac53168225d5ff30a249612a0f756fe60eaca67141ca937d43f8c70aaa7a1066681bb35a97fc49f242254d87438f369b02700193cc86456ded97ca9c
-  data.tar.gz: ea890ffc51e6540c6a19db3481d92b8f0263c042594f74c4ec2ac3f975c7f988d345f69e0a6b37345993b499535180b87456cd189dffa9506b2c60148f2b9481
+  metadata.gz: 2ae292c3c50580e4872ec7a2334052b2495d0df8943341970d98f0a1922ea5b15d9612a0b8998de30bfb100100d3daf0567c9270fafef89529fc88c65f72634d
+  data.tar.gz: e86c76ce090e6a622a2122c068fb8a384520ff7b38193613f254f446f4a4165f09c48bcf944b2f3d5a2ad3435a0e71502bda8a6ec1b776b0b1b4bbc1ee240424

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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
+
+- **`slk status` now answers the questions the status raises** — who can reach you, and whether the status is about to change on its own
+  - Presence and DND appear as suffixes on the status line: `:computer: Working [away] [dnd until 3:00pm]`. Only exceptional states are labelled, so the workspace that differs stands out rather than being buried under "active" on every line
+  - `[dnd until …]` covers a manual snooze and the configured DND hours alike — from the outside both mean messages do not notify — and reports the later end when both apply. `slk dnd` still breaks out which is which
+  - Anything scheduled to turn on later is listed under the status, soonest first and without IDs; `slk status scheduled` remains the view to paste an ID from
+  - Times carry a day when the end is not today, so an overnight window does not read as a time that has already passed
+- **`slk status --json`** (and `slk status scheduled --json`) for scripts and statuslines
+  - Always an array, one entry per workspace, even for a single workspace: a document whose shape changes with `-w` cannot be parsed by a script that did not pass it
+  - `null` means "not checked" — skipped by a flag, or a lookup that failed — as distinct from checked-and-empty. A statusline that read a failed DND lookup as "DND off" would report the opposite of the truth
+  - Every timestamp appears twice: Slack's own epoch under Slack's own field name, and an ISO 8601 string beside it
+- **`--brief` and `--no-scheduled`** for the get view. It now costs up to four calls per workspace; `--no-scheduled` drops the internal `users.customStatus.list` lookup and `--brief` drops all three extras. `--quiet` skips them too, since their output would be discarded (`--json` still gathers them: it prints regardless)
+
+### Changed
+
+- A failed presence, DND or schedule lookup during `slk status` warns and omits that part instead of failing the command — the status itself is what was asked for. A rate limit stops the remaining extra lookups altogether rather than spending calls the status reads need
+
 ## [0.7.0] - 2026-08-03
 
 ### Added
@@ -210,6 +242,7 @@ Initial release of the Ruby rewrite. Pure Ruby, no external dependencies.
   - Pure Ruby stdlib - no gem dependencies
   - Ruby 3.2+ with modern features (Data.define, pattern matching)
 
+[0.8.0]: https://github.com/ericboehs/slk/releases/tag/v0.8.0
 [0.7.0]: https://github.com/ericboehs/slk/releases/tag/v0.7.0
 [0.6.0]: https://github.com/ericboehs/slk/releases/tag/v0.6.0
 [0.5.0]: https://github.com/ericboehs/slk/releases/tag/v0.5.0

data/README.md

@@ -46,12 +46,52 @@ You'll need a Slack token. Get one from:
 ### Status
 
 ```bash
-slk status                              # Show current status
+slk status                              # Status, presence, DND and what's queued next
+slk status --brief                      # Status text only (one call per workspace)
+slk status --json                       # Machine-readable, for scripts and statuslines
 slk status "Working from home" :house:  # Set status with emoji
 slk status "In a meeting" :calendar: 1h # Set status for 1 hour
 slk status clear                        # Clear status
 ```
 
+Getting the status also answers the two questions it usually raises — can anyone
+reach me, and is this about to change on its own:
+
+```
+$ slk status
+work
+  :computer: Working [away] [dnd until 3:00pm]
+  Scheduled:
+    :paw_prints: Vet Appt (Mon Aug 3 1:30pm -> 3:30pm)
+side-project
+  (no status set)
+```
+
+Only the exceptional states are labelled: an active, notifiable workspace says
+nothing, so the one that differs stands out. `[dnd until ...]` covers both a
+manual snooze and the configured DND hours — from the outside they are the same
+thing — and `slk dnd` breaks out which.
+
+Each of those is a separate call, so `slk status` costs up to four per
+workspace. `--no-scheduled` drops the schedule lookup (the one internal
+endpoint), `--brief` drops all three, and a lookup that fails warns and leaves
+that part out rather than failing the command.
+
+#### JSON output
+
+`slk status --json` (and `slk status scheduled --json`) prints one entry per
+workspace — always an array, even for a single workspace, so a script that did
+not pass `-w` can still parse it. `null` means *not checked* (skipped by a flag,
+or the lookup failed), which is not the same as checked-and-empty: a statusline
+that read a failed DND lookup as "DND off" would say the opposite of the truth.
+Every timestamp appears twice, as Slack's epoch and as ISO 8601:
+
+```bash
+# "away, quiet until 3:00pm"
+slk status -w work --json --no-scheduled |
+  jq -r '.[0] | "\(.presence.presence)\(if .dnd.active then ", quiet until " + (.dnd.until | strflocaltime("%-I:%M%p")) else "" end)"'
+```
+
 Statuses can also be scheduled to turn on later (Slack allows up to 5 at a time):
 
 ```bash
@@ -170,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