slk 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c56010125fc8e78293e4701ac5619742dda1fecd3e6e06ec98a3eb6afab0dc46
-  data.tar.gz: 05fad0411c6b216091bc9dd7cade46a36579bbba951042c61859111c57db9356
+  metadata.gz: eec8154512ee9815597065ac68471bfd2ad55535191d4057e55ae4d942f15f66
+  data.tar.gz: 3fe2bdbe0fa65ce0b0ee4a529531a38c59f78c674eed08f22d5d40b833b79150
 SHA512:
-  metadata.gz: 2ae292c3c50580e4872ec7a2334052b2495d0df8943341970d98f0a1922ea5b15d9612a0b8998de30bfb100100d3daf0567c9270fafef89529fc88c65f72634d
-  data.tar.gz: e86c76ce090e6a622a2122c068fb8a384520ff7b38193613f254f446f4a4165f09c48bcf944b2f3d5a2ad3435a0e71502bda8a6ec1b776b0b1b4bbc1ee240424
+  metadata.gz: e9a595db19f0748ccb42a4ec436dffa0fe4bbb4d1fbff0514f659cee09a8fb1db2c5258cdd7e74252972c2029e63de0082a2cadf33d96f98dff1681717680e88
+  data.tar.gz: 0e33aa2ec6319fe88433dffe30865d0c17306da34cf136aebd1e9b17e9bb42d9bc5447748914751a74e48f43883bfe3cc404fb657cfaf33c2abdf7db369d2e9a

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.10.0] - 2026-09-18
+
+### Added
+
+- **`slk deactivations --tenure`** — how long each person stayed
+  - Start dates come from the workspace's "Start Date" custom profile field, discovered from the team schema rather than hardcoded, since every workspace numbers its own fields. A date-typed field wins over a text one with the same label
+  - `users.list` does not carry custom fields, so this costs one `users.profile.get` per person, and Slack rate-limits that endpoint to roughly eight calls a minute. The command says how long it will take before it starts, and only looks up the rows it is about to show
+  - Every answer is cached the moment it arrives, not at the end, so interrupting a long lookup keeps the work already paid for. Accounts with no start date on file are cached too, otherwise every run would pay again to learn the same nothing
+  - Tenure is counted in whole months: somebody who started on the 20th and left on the 3rd has not completed that month. An end date before the start is a data entry error rather than a negative tenure, and reads as blank
+  - Blank means nobody filled the field in, and the column disappears entirely when no start date is known. `--tenure` with `--chart` is refused rather than ignored — a histogram has no row to hang a tenure on
+- **`slk deactivations --csv`** — the spreadsheet that always gets asked for
+  - Writes every match rather than the screenful `-n` would show: a truncated export is a wrong answer that looks like a right one
+  - With `--tenure` it gains `started_on`, `tenure_months` and a readable `tenure` column; unknown start dates leave empty cells rather than zeros, so averaging tenure in a spreadsheet skips them instead of counting people who left the day they arrived
+  - RFC 4180 quoting, hand-rolled, because Ruby 3.4 moved csv out of the default gems and this tool ships with no dependencies
+  - Progress and warnings go to stderr, so `slk deactivations --csv > file.csv` captures only data
+
+### Fixed
+
+- **A cache that cannot be written no longer costs you the run.** `MetaCache.write` returns disk failures instead of raising them: a full or read-only disk means "no cache", not "no answer". This mattered most for start date lookups, which sit behind minutes of rate-limited calls, but it also fixed the deactivation roster scan, which crashed outright on an unwritable cache directory. Other exceptions still raise — a bug in the value being cached is not a disk problem
+- **A cache that cannot be read no longer crashes.** An unreadable cache file now warns and is skipped, the same way a corrupt one already was. The file is left in place rather than deleted, since removing it needs the access that just failed
+- **A malformed API response fails as an API error.** Slack replying with a JSON array, string or null instead of an object used to surface as `TypeError` or `NoMethodError` from whichever command happened to dig into it first
+- **`slk cache clear` now clears all caches.** It removed only the user and channel caches while reporting "Cleared all caches"; start dates, deactivation rosters and resolved profiles survived it
+
 ## [0.9.0] - 2026-09-18
 
 ### Added

data/README.md

@@ -217,6 +217,8 @@ 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 --tenure        # Add how long each person stayed
+slk deactivations 1y --csv        # Spreadsheet export of a year of departures
 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
@@ -240,6 +242,41 @@ 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.
 
+#### Tenure
+
+`--tenure` adds how long each person was here, taken from the workspace's
+"Start Date" profile field:
+
+```
+acme: 3 deactivated since 30d (664 active members)
+
+2026-09-14  Dana Whitfield         1mo  Platform Support
+2026-09-11  Priya Raghunathan   2y 7mo  UX Researcher
+2026-09-09  Sam Okonkwo        4y 10mo  Senior Software Engineer
+```
+
+This one is slow the first time. Start dates are not in the roster — they cost
+one `users.profile.get` per person, and Slack rate-limits that endpoint to
+roughly eight calls a minute, so a screenful takes about three minutes. The
+command says so before it starts, only looks up the rows it is about to show,
+and caches each answer the moment it arrives: interrupting it keeps the work
+already paid for, and the second run is instant.
+
+Blank means nobody filled the field in. Months are whole months, so somebody
+who started on the 20th and left on the 3rd has not completed that month.
+
+#### CSV
+
+`--csv` writes every match — not just the screenful `-n` would show, since a
+truncated export is a wrong answer that looks like a right one. Combine it with
+`--tenure` for `started_on`, `tenure_months` and a readable `tenure` column:
+
+```bash
+slk deactivations 1y --tenure --csv > departures.csv
+```
+
+Progress and warnings go to stderr, so the redirect above captures only data.
+
 ### Global Options
 
 ```bash

data/lib/slk/commands/cache.rb

@@ -65,6 +65,14 @@ module Slk
         0
       end
 
+      # Every kind, including the meta cache behind start dates, deactivation
+      # rosters and resolved profiles — "cleared" should not have exceptions.
+      def clear_every_cache(workspace_name)
+        cache_store.clear_user_cache(*[workspace_name].compact)
+        cache_store.clear_channel_cache(*[workspace_name].compact)
+        cache_store.clear_meta_cache(*[workspace_name].compact)
+      end
+
       def display_workspace_status(workspace)
         puts output.bold(workspace.name) if target_workspaces.size > 1
         display_cache_counts(workspace)
@@ -87,15 +95,8 @@ module Slk
       end
 
       def clear_cache(workspace_name)
-        if workspace_name
-          cache_store.clear_user_cache(workspace_name)
-          cache_store.clear_channel_cache(workspace_name)
-          success("Cleared cache for #{workspace_name}")
-        else
-          cache_store.clear_user_cache
-          cache_store.clear_channel_cache
-          success('Cleared all caches')
-        end
+        clear_every_cache(workspace_name)
+        success(workspace_name ? "Cleared cache for #{workspace_name}" : 'Cleared all caches')
 
         0
       end

data/lib/slk/commands/deactivations.rb

@@ -8,16 +8,31 @@ module Slk
     #   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
+    #   slk deactivations --tenure        # add how long each person stayed
+    #   slk deactivations --csv           # spreadsheet export of every match
     # rubocop:disable Metrics/ClassLength
     class Deactivations < Base
       DEFAULT_LIMIT = 25
       CHART_MONTHS = 12
+      # Measured against a live workspace: users.profile.get answers two or
+      # three calls in a row, then makes you wait out a thirty second
+      # Retry-After — about eight lookups a minute averaged over a long run,
+      # which is what the time estimate is built on.
+      LOOKUPS_PER_MINUTE = 8
+      COST_WARNING_AT = 5
+      SWITCHES = {
+        '--chart' => :chart, '--bots' => :bots, '--tenure' => :tenure, '--csv' => :csv,
+        '--refresh' => :refresh, '--no-cache' => :refresh
+      }.freeze
 
       def execute
         result = validate_options
         return result if result
 
         run
+      rescue Services::StartDateLookup::MissingFieldError => e
+        error(e.message)
+        1
       rescue ApiError => e
         error("API error: #{e.message}")
         1
@@ -26,18 +41,21 @@ module Slk
       protected
 
       def handle_option(arg, args, _remaining)
+        return switch_on(SWITCHES[arg]) if SWITCHES.key?(arg)
+
         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 switch_on(key)
+        @options[key] = true
+      end
+
       def help_text
         help = Support::HelpFormatter.new('slk deactivations [since] [options]')
         help.description('Show deactivated accounts — who left the workspace, and when.')
@@ -76,33 +94,50 @@ module Slk
           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('--tenure', 'Add how long each person stayed (slow: one lookup per person)')
           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')
+          add_output_options(s)
         end
       end
 
+      def add_output_options(section)
+        section.option('--refresh', 'Re-fetch the roster instead of using the cache')
+        section.option('--csv', 'CSV of every match, for a spreadsheet')
+        section.option('--json', 'Raw JSON output')
+      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 --tenure', 'How long each person stayed')
+          s.example('slk deactivations 1y --csv > left.csv', 'Export a year of departures')
           s.example('slk deactivations 2026-01-01 -n 0', 'All departures this year')
         end
       end
 
       def run
         workspace = runner.workspace(@options[:workspace])
+        validate_combination
         @since_label = since_spec
         @since = parse_since(@since_label)
         report = scan(workspace)
         records = collect_records(report)
 
+        emit(workspace, report, records)
+        0
+      end
+
+      # --csv and --json export every match; the terminal list is the only
+      # view that pages, so it is the only one -n applies to. (--chart spans
+      # its whole window too, for the same reason.)
+      def emit(workspace, report, records)
+        return render_csv(workspace, records) if @options[:csv]
         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
@@ -114,16 +149,98 @@ module Slk
         @options[:since] || positional_args.first
       end
 
+      # A histogram counts departures per month; it has no row to hang a
+      # tenure on. Refusing beats quietly ignoring the flag someone paid
+      # attention to type.
+      # Two ways of asking for the same rows is one too many, and picking a
+      # winner silently means the other flag looks broken.
+      def validate_combination
+        raise UsageError, '--tenure has nothing to add to --chart; drop one of them.' if
+          @options[:tenure] && @options[:chart]
+        raise UsageError, '--csv and --json are two different exports; pick one.' if
+          @options[:csv] && @options[:json]
+      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))
+        output_json(json_payload(workspace, report, records, tenures(workspace, records)))
         0
       end
 
+      def render_csv(workspace, records)
+        Formatters::DeactivationCsv.new(
+          output: output, tenures: @options[:tenure] ? tenures(workspace, records) : nil
+        ).render(records)
+        0
+      end
+
+      # Start dates cost one rate-limited call each, so they are only ever
+      # fetched for rows that will actually be shown. The caller has already
+      # applied -n (or deliberately not, for an export); this memo assumes one
+      # record set per run, which is what a single command does.
+      def tenures(workspace, records)
+        return {} unless @options[:tenure]
+
+        @tenures ||= resolve_tenures(workspace, records)
+      end
+
+      def resolve_tenures(workspace, records)
+        lookup = start_date_lookup(workspace)
+        announce_cost(lookup, records)
+        dates = begin
+          lookup.fetch(records.map(&:user_id))
+        ensure
+          # Even when the lookup raises: otherwise the error message arrives
+          # glued to a half-drawn "start dates: 12/40".
+          output.clear_progress
+        end
+        report_cache_error(lookup)
+        records.to_h { |r| [r.user_id, Models::Tenure.build(dates[r.user_id], r.deactivated_time)] }
+      end
+
+      # The answers still arrived; they just will not be there next time.
+      def report_cache_error(lookup)
+        return unless lookup.cache_error
+
+        warn("Could not save the start date cache (#{lookup.cache_error}). " \
+             'These lookups will have to be repeated next run.')
+      end
+
+      def start_date_lookup(workspace)
+        Services::StartDateLookup.new(
+          users_api: runner.users_api(workspace.name),
+          field: start_date_field(workspace),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_progress: ->(done, total) { output.progress("start dates: #{done}/#{total}") }
+        )
+      end
+
+      def start_date_field(workspace)
+        Services::StartDateField.new(
+          team_api: runner.team_api(workspace.name),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_debug: ->(msg) { output.debug(msg) }
+        )
+      end
+
+      # Better to say how long this will take than to let someone wonder
+      # whether the terminal has hung.
+      def announce_cost(lookup, records)
+        pending = lookup.uncached_count(records.map(&:user_id))
+        return if pending < COST_WARNING_AT
+
+        minutes = [(pending.to_f / LOOKUPS_PER_MINUTE).round, 1].max
+        warn("Looking up #{pending} start dates, one profile call each. Slack rate-limits these " \
+             "to about #{LOOKUPS_PER_MINUTE} a minute, so this will take roughly #{minutes} " \
+             "minute#{'s' if minutes > 1}. Interrupting is safe: each answer is cached as it arrives.")
+      end
+
       def scan(workspace)
         Services::DeactivationScanner.new(
           users_api: runner.users_api(workspace.name),
@@ -192,7 +309,7 @@ module Slk
       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)
+        render_body(formatter, workspace, records)
         footer = footer(report, records)
         return if footer.empty?
 
@@ -202,17 +319,19 @@ module Slk
 
       # 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)
+      def render_body(formatter, workspace, records)
         return info('No deactivations match.') if records.empty?
 
         puts
-        @options[:chart] ? formatter.chart(records, **chart_bounds) : render_list(formatter, records)
+        return formatter.chart(records, **chart_bounds) if @options[:chart]
+
+        render_list(formatter, workspace, records)
       end
 
-      def render_list(formatter, records)
+      def render_list(formatter, workspace, records)
         limit = @options[:limit] || DEFAULT_LIMIT
         shown = limit.positive? ? records.first(limit) : records
-        formatter.list(shown)
+        formatter.list(shown, tenures: tenures(workspace, shown))
         return unless shown.size < records.size
 
         puts
@@ -267,7 +386,7 @@ module Slk
         Models::Duration.new(seconds: seconds).to_s
       end
 
-      def json_payload(workspace, report, records)
+      def json_payload(workspace, report, records, tenures = {})
         {
           workspace: workspace.name,
           fetched_at: report.fetched_at,
@@ -276,9 +395,20 @@ module Slk
           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) }
+          deactivations: records.map { |r| json_entry(r, tenures) }
         }
       end
+
+      # started_on and tenure_months appear only when they were asked for:
+      # a null that means "not looked up" is indistinguishable from one that
+      # means "nobody filled it in".
+      def json_entry(record, tenures)
+        entry = record.to_h.merge(deactivated_on: record.date)
+        return entry unless @options[:tenure]
+
+        tenure = tenures[record.user_id]
+        entry.merge(started_on: tenure&.started, tenure_months: tenure&.months)
+      end
     end
     # rubocop:enable Metrics/ClassLength
   end

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

@@ -15,11 +15,16 @@ module Slk
         @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)
+      # 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)
-        records.each { |record| @output.puts(row(record, name_width)) }
+        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)
@@ -61,21 +66,32 @@ module Slk
         "#{@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}"
+      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)
-        [@width - DATE_WIDTH - name_width - 4, MIN_TITLE_WIDTH].max
+      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

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/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/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

data/lib/slk/services/start_date_field.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Which custom profile field holds a start date, if any.
+    #
+    # Workspaces name and number these fields themselves, so the ID has to be
+    # discovered from the team schema rather than hardcoded — and the schema
+    # barely changes, so the answer is cached for a week.
+    class StartDateField
+      CACHE_KEY = 'start_date_field_v1'
+      TTL = 604_800 # 7 days
+      LABEL = /\Astart date\z/i
+
+      def initialize(team_api:, workspace_name:, cache_store: nil, on_debug: nil)
+        @team_api = team_api
+        @workspace_name = workspace_name
+        @cache = cache_store
+        @on_debug = on_debug
+      end
+
+      # @return [String, nil] the Xf… field ID, or nil if the workspace has none
+      def id
+        return @id if defined?(@id)
+
+        cached = MetaCache.read(@cache, @workspace_name, CACHE_KEY, ttl: TTL)
+        @id = cached.is_a?(Hash) ? cached['id'] : discover
+      end
+
+      def missing_message
+        'This workspace has no "Start Date" profile field, so tenure cannot be worked out. ' \
+          'Run `slk debug schema` (an undocumented command) to see the fields it does have.'
+      end
+
+      private
+
+      # A date-typed field wins over a text one with the same label: someone
+      # typing "started summer 2019" into a text box is not a date.
+      def discover
+        id = usable_id(best_match(@team_api.profile_schema.dig('profile', 'fields')))
+        @on_debug&.call("start date field: #{id || 'not found in team schema'}")
+        remember(id)
+        id
+      end
+
+      def usable_id(match)
+        id = match && match['id']
+        id.is_a?(String) && !id.empty? ? id : nil
+      end
+
+      # Losing this costs one extra team.profile.get next run, not minutes of
+      # rate-limited lookups, so it is noted rather than warned about.
+      def remember(id)
+        failure = MetaCache.write(@cache, @workspace_name, CACHE_KEY, { 'id' => id })
+        @on_debug&.call("start date field cache not written: #{failure.message}") if failure
+      end
+
+      # A workspace that answers with something other than a list of field
+      # hashes has no start date field as far as we are concerned — better a
+      # clear "this workspace cannot do tenure" than an unexpected error.
+      def best_match(fields)
+        labelled = Array(fields).grep(Hash).select { |f| LABEL.match?(f['label'].to_s.strip) }
+        labelled.find { |f| f['type'] == 'date' } || labelled.first
+      end
+    end
+  end
+end

data/lib/slk/services/start_date_lookup.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Start dates live in a workspace custom profile field, which `users.list`
+    # does not return — they cost one `users.profile.get` per person, and Slack
+    # rate-limits that endpoint hard enough that a screenful takes minutes
+    # rather than seconds.
+    #
+    # So every answer is cached, and cached the moment it arrives rather than
+    # at the end: interrupting a long lookup keeps the work already paid for.
+    # Accounts with no start date on file are cached too, otherwise every run
+    # would pay again to learn the same nothing.
+    #
+    # The cache holds for 30 days. A departed account's start date rarely
+    # changes, but an admin correcting a typo in one is exactly the case the
+    # expiry exists for; `slk cache clear` forces the issue sooner.
+    class StartDateLookup
+      CACHE_KEY = 'start_dates_v1'
+      TTL = 2_592_000 # 30 days
+
+      class MissingFieldError < Slk::Error; end
+
+      # Set when the cache could not be written. The lookup carries on — the
+      # cache is an optimisation, and the answers are worth more than it.
+      attr_reader :cache_error
+
+      def initialize(users_api:, field:, workspace_name:, cache_store: nil, on_progress: nil)
+        @users_api = users_api
+        @field = field
+        @workspace_name = workspace_name
+        @cache = cache_store
+        @on_progress = on_progress
+      end
+
+      # @return [Hash{String => String, nil}] user ID => ISO date, or nil for
+      #   an account with no start date recorded
+      def fetch(user_ids)
+        # Checked even for an empty list: "this workspace cannot do tenure" is
+        # the same fact whether or not anyone matched the filter, and finding
+        # out only when someone matches makes it look intermittent.
+        raise MissingFieldError, @field.missing_message if @field.id.to_s.empty?
+        return {} if user_ids.empty?
+
+        known = cached
+        user_ids.each_with_index { |id, index| resolve(known, id, index, user_ids.size) }
+        known.slice(*user_ids)
+      end
+
+      # How many of these would cost an API call, so a caller can warn about
+      # the wait before making someone sit through it.
+      def uncached_count(user_ids)
+        known = cached
+        user_ids.count { |id| !known.key?(id) }
+      end
+
+      private
+
+      def resolve(known, user_id, index, total)
+        return if known.key?(user_id)
+
+        @on_progress&.call(index + 1, total)
+        known[user_id] = start_date_for(user_id)
+        remember(known)
+      end
+
+      # A full or read-only disk must not throw away a lookup that cost
+      # minutes of rate-limited calls. MetaCache.write hands back the failure
+      # instead of raising; the caller reports it once at the end.
+      def remember(known)
+        failure = MetaCache.write(@cache, @workspace_name, CACHE_KEY, known)
+        # First failure only: the same unwritable disk will fail every row.
+        @cache_error = failure.message if failure && @cache_error.nil?
+      end
+
+      # Which account failed matters when the answer arrives twenty rows into
+      # a run that has already taken three minutes.
+      def start_date_for(user_id)
+        fields = @users_api.profile_for(user_id).dig('profile', 'fields')
+        value = fields.is_a?(Hash) ? fields.dig(@field.id, 'value') : nil
+        value.to_s.empty? ? nil : value
+      rescue ApiError => e
+        # Only the plain kind: re-wrapping a RateLimitError would drop its
+        # retry_after and the class the retry logic looks for.
+        raise unless e.instance_of?(ApiError)
+
+        raise ApiError.new("#{e.message} (looking up #{user_id})", code: e.code)
+      end
+
+      def cached
+        @cached ||= begin
+          data = MetaCache.read(@cache, @workspace_name, CACHE_KEY, ttl: TTL)
+          data.is_a?(Hash) ? data : {}
+        end
+      end
+    end
+  end
+end

data/lib/slk/version.rb

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

data/lib/slk.rb

@@ -6,6 +6,7 @@ require 'json'
 require 'fileutils'
 require 'optparse'
 require 'time'
+require 'date'
 require 'io/console'
 
 # Slack CLI - A command-line interface for Slack
@@ -75,6 +76,7 @@ module Slk
     autoload :Channel, 'slk/models/channel'
     autoload :Preset, 'slk/models/preset'
     autoload :Deactivation, 'slk/models/deactivation'
+    autoload :Tenure, 'slk/models/tenure'
     autoload :SearchResult, 'slk/models/search_result'
     autoload :SavedItem, 'slk/models/saved_item'
     autoload :Profile, 'slk/models/profile'
@@ -109,6 +111,8 @@ module Slk
     autoload :ProfileResolver, 'slk/services/profile_resolver'
     autoload :MetaCache, 'slk/services/meta_cache'
     autoload :DeactivationScanner, 'slk/services/deactivation_scanner'
+    autoload :StartDateLookup, 'slk/services/start_date_lookup'
+    autoload :StartDateField, 'slk/services/start_date_field'
   end
 
   # Output formatters for messages, durations, and emoji
@@ -132,6 +136,8 @@ module Slk
     autoload :ProfileFieldRenderer, 'slk/formatters/profile_field_renderer'
     autoload :ProfileRows, 'slk/formatters/profile_rows'
     autoload :DeactivationFormatter, 'slk/formatters/deactivation_formatter'
+    autoload :DeactivationCsv, 'slk/formatters/deactivation_csv'
+    autoload :CsvWriter, 'slk/formatters/csv_writer'
   end
 
   # CLI commands implementing user-facing functionality

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slk
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Eric Boehs
@@ -65,6 +65,8 @@ files:
 - lib/slk/formatters/activity_formatter.rb
 - lib/slk/formatters/attachment_formatter.rb
 - lib/slk/formatters/block_formatter.rb
+- lib/slk/formatters/csv_writer.rb
+- lib/slk/formatters/deactivation_csv.rb
 - lib/slk/formatters/deactivation_formatter.rb
 - lib/slk/formatters/duration_formatter.rb
 - lib/slk/formatters/emoji_replacer.rb
@@ -95,6 +97,7 @@ files:
 - lib/slk/models/search_result.rb
 - lib/slk/models/status.rb
 - lib/slk/models/status_snapshot.rb
+- lib/slk/models/tenure.rb
 - lib/slk/models/user.rb
 - lib/slk/models/workspace.rb
 - lib/slk/runner.rb
@@ -115,6 +118,8 @@ files:
 - lib/slk/services/profile_resolver.rb
 - lib/slk/services/reaction_enricher.rb
 - lib/slk/services/setup_wizard.rb
+- lib/slk/services/start_date_field.rb
+- lib/slk/services/start_date_lookup.rb
 - lib/slk/services/target_resolver.rb
 - lib/slk/services/token_loader.rb
 - lib/slk/services/token_saver.rb