slk 0.9.0 → 0.11.0

data/lib/slk/commands/sent.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module Slk
+  module Commands
+    # All indexed messages sent by the authenticated user on a date/range.
+    # rubocop:disable Metrics/ClassLength
+    class Sent < Base
+      def execute
+        result = validate_options
+        return result if result
+
+        run_sent
+      rescue ApiError => e
+        error("Sent search failed: #{e.message}")
+        1
+      end
+
+      protected
+
+      def default_options
+        super.merge(since: nil, mine: false, changed_since: nil, lookback: 7, context: 2,
+                    before: Services::SentConversations::DEFAULT_BEFORE,
+                    after_minutes: Services::SentConversations::DEFAULT_AFTER_MINUTES,
+                    max: Services::SentConversations::DEFAULT_MAX)
+      end
+
+      def default_width
+        return nil unless $stdout.tty?
+
+        columns = IO.console&.winsize&.last
+        columns&.positive? ? columns : super
+      rescue SystemCallError, IOError, NotImplementedError
+        super
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      def handle_option(arg, args, remaining)
+        case arg
+        when '--since' then @options[:since] = option_value(arg, args)
+        when '--changed-since' then @options[:changed_since] = option_value(arg, args)
+        when '--lookback' then @options[:lookback] = positive_integer(arg, args)
+        when '--context' then @options[:context] = nonnegative_integer(arg, args)
+        when '--mine' then @options[:mine] = true
+        when '--before' then @options[:before] = before_limit(arg, args)
+        when '--after-minutes' then @options[:after_minutes] = nonnegative_integer(arg, args)
+        when '--max' then @options[:max] = nonnegative_integer(arg, args)
+        else super
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def help_text
+        help = Support::HelpFormatter.new('slk sent [today|yesterday|YYYY-MM-DD] [options]')
+        help.description('Catch up on conversations you posted in, across all workspaces.')
+        help.note('Search is indexed: very recent and deleted messages may be missing.')
+        help.note('Dates/DM history bounds use your local clock; Slack search uses your profile timezone.')
+        help.note('Long --since ranges can be slow (search is rate-limited; 429s retry once).')
+        help.note('Conversations you only read or were mentioned in but never posted in are out of scope.')
+        help.note('A future --mentions flag could seed mentioned conversations via to:me search.')
+        help.note('JSON: {date, range, conversations:[{workspace, channel_id, channel_name, channel_label, type,')
+        help.note('thread_ts, last_speaker_is_me, dropped_messages, messages:[{ts, user,')
+        help.note('user_name, text, mine, thread_ts}]}]}; --mine keeps counts/results JSON,')
+        help.note('with channel_label added to counts. channel_name remains the raw Slack name.')
+        help.note('JSON messages stay flat and timestamp-sorted; thread_ts links replies to their parent.')
+        help.note('Text output nests expanded replies under their parent, even when sent later, and wraps')
+        help.note('to the terminal width on a TTY. Use --width N to override or --no-wrap to disable.')
+        help.note('Thread headings show the thread ID; channel and DM headings keep their readable names.')
+        help.note('A thin divider separates conversations, not messages within a conversation.')
+        help.note('For --changed-since, H:MM or HH:MM means the most recent local occurrence: if that time has not')
+        help.note('arrived today, it means yesterday. Dated timestamps in the future are rejected.')
+        help.note('--changed-since is stateless: exact-ts history/replies detect new messages; search only finds')
+        help.note('the watch set. Edits/reactions do not change ts and are invisible. Search index lag may')
+        help.note('omit posts from the last few minutes. Conversations you never posted in remain out of scope.')
+        help.note('Unread followed threads supplement the watch set when available; --lookback must include')
+        help.note('the days you posted in any other threads you want to watch.')
+        help.note('Changed text marks earlier context with · and puts the most recently active conversation last.')
+        help.note('A wide lookback checks many thread roots and can take minutes under Slack rate limits.')
+        help.note('Changed JSON adds changed_since:{iso, ts}, lookback_days, new_count, new_from_others,')
+        help.note('and per-message new. Its messages stay flat and timestamp-sorted with thread_ts links.')
+        help.section('OPTIONS') do |s|
+          s.option('--since YYYY-MM-DD', 'From this date through today (inclusive)')
+          s.option('--changed-since TIME', 'Only changed conversations (H:MM/HH:MM, ISO, epoch, 90m, 2h, 1d)')
+          s.option('--lookback DAYS', 'Days of sent messages to watch (default: 7; changed mode)')
+          s.option('--context N', 'Earlier messages per changed conversation (default: 2)')
+          s.option('--mine', 'Only your messages, flat timeline with counts (previous behavior)')
+          s.option('--before N', 'Channel messages before a window (default: 5, max: 200)')
+          s.option('--after-minutes N', 'Channel window after each post (default: 30)')
+          s.option('--max N', 'Messages per conversation (default: 200; 0 for all)')
+          s.option('-w, --workspace NAME', 'Search one workspace instead of all')
+          s.option('--all', 'Search all workspaces (default)')
+          s.option('--json', 'Output conversations as JSON (or counts/results with --mine)')
+          s.option('--width N', 'Wrap text at N columns (default: terminal width on TTY)')
+          s.option('--no-wrap', 'Disable text wrapping')
+        end
+        help.section('EXAMPLES') do |s|
+          s.example('slk sent', 'Today in all workspaces')
+          s.example('slk sent yesterday', 'Yesterday in all workspaces')
+          s.example('slk sent 2026-09-19', 'One specific day')
+          s.example('slk sent --since 2026-09-15', 'From Sep 15 through today')
+          s.example('slk sent --mine --json', 'Only your sent messages, flat JSON')
+          s.example('slk sent --changed-since 15:17 --lookback 3', 'Diff watched conversations since 15:17')
+        end
+        help.render
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+      private
+
+      def run_sent
+        raise UsageError, 'Use either --all or --workspace, not both.' if @options[:all] && @options[:workspace]
+
+        return run_changes if @options[:changed_since]
+
+        query = date_query
+        entries = collect_entries(query)
+        @options[:mine] ? emit(entries, query) : emit_context(entries)
+        0
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def run_changes
+        validate_changed_options
+        since = Support::CheckInTime.parse(@options[:changed_since])
+        entries = collect_entries(changed_query)
+        changes = Services::SentChanges.new(
+          runner: runner, since: since, context: @options[:context], max: @options[:max],
+          before: @options[:before], after_minutes: @options[:after_minutes]
+        ).collect(entries, workspaces: selected_workspaces)
+        Formatters::SentFormatter.new(runner: runner, options: format_options).display_changes(
+          changes, changed_since: since, lookback_days: @options[:lookback], json: @options[:json]
+        )
+        0
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def validate_changed_options
+        if positional_args.any? || @options[:since]
+          raise UsageError, 'Use --changed-since alone, not with a date or --since.'
+        end
+        raise UsageError, 'Use --changed-since without --mine.' if @options[:mine]
+      end
+
+      def changed_query
+        start_date = Date.today - (@options[:lookback] - 1)
+        "from:me after:#{start_date - 1} before:#{Date.today + 1}"
+      end
+
+      def positive_integer(flag, args)
+        number = nonnegative_integer(flag, args)
+        raise UsageError, "#{flag} expects a positive integer." if number.zero?
+
+        number
+      end
+
+      def before_limit(flag, args)
+        number = nonnegative_integer(flag, args)
+        raise UsageError, '--before must be at most 200.' if number > 200
+
+        number
+      end
+
+      def nonnegative_integer(flag, args)
+        value = option_value(flag, args)
+        number = Integer(value, exception: false)
+        raise UsageError, "#{flag} expects a non-negative integer." unless number && !number.negative?
+
+        number
+      end
+
+      def date_query
+        raise UsageError, 'Use either a date or --since, not both.' if @options[:since] && positional_args.any?
+        raise UsageError, 'Expected one date: today, yesterday, or YYYY-MM-DD.' if positional_args.length > 1
+
+        @options[:since] ? range_query : day_query
+      end
+
+      def range_query
+        since = parse_date(@options[:since])
+        raise UsageError, '--since must not be in the future.' if since > Date.today
+
+        "from:me after:#{since - 1} before:#{Date.today + 1}"
+      end
+
+      def day_query
+        date = case positional_args.first
+               when nil, 'today' then Date.today
+               when 'yesterday' then Date.today - 1
+               else parse_date(positional_args.first)
+               end
+        "from:me on:#{date}"
+      end
+
+      def parse_date(value)
+        raise UsageError, "Invalid date: #{value.inspect}. Use YYYY-MM-DD." unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        Date.iso8601(value)
+      rescue Date::Error
+        raise UsageError, "Invalid date: #{value.inspect}. Use YYYY-MM-DD."
+      end
+
+      def collect_entries(query)
+        entries = selected_workspaces.flat_map { |workspace| fetch_workspace(workspace, query) }
+        entries.sort_by { |workspace, result| [result.ts.to_f, workspace.name, result.channel_id.to_s] }
+      end
+
+      def selected_workspaces
+        @options[:workspace] ? [runner.workspace(@options[:workspace])] : runner.all_workspaces
+      end
+
+      def fetch_workspace(workspace, query)
+        pages = Services::SearchPages.new(runner.search_api(workspace.name)).fetch(query: query, sort_dir: 'asc')
+        pages[:results].map { |result| [workspace, result] }
+      end
+
+      def emit_context(entries)
+        start_date, end_date = selected_dates
+        conversations = Services::SentConversations.new(
+          runner: runner, start_date: start_date, end_date: end_date,
+          before: @options[:before], after_minutes: @options[:after_minutes], max: @options[:max]
+        ).collect(entries)
+        Formatters::SentFormatter.new(runner: runner, options: format_options).display(
+          conversations, start_date: start_date, end_date: end_date, json: @options[:json]
+        )
+      end
+
+      def selected_dates
+        return [parse_date(@options[:since]), Date.today] if @options[:since]
+
+        date = case positional_args.first
+               when nil, 'today' then Date.today
+               when 'yesterday' then Date.today - 1
+               else parse_date(positional_args.first)
+               end
+        [date, date]
+      end
+
+      def emit(entries, query)
+        counts = entries.group_by { |workspace, result| [workspace.name, result.channel_id] }
+        if @options[:json]
+          output_json(query: query, counts: json_counts(counts), results: entries.map do |workspace, result|
+            result.to_h.merge(workspace: workspace.name)
+          end)
+        else
+          display_counts(counts, entries)
+        end
+      end
+
+      def json_counts(counts)
+        counts.map do |(workspace, channel_id), group|
+          result = group.first.last
+          { workspace: workspace, channel_id: channel_id, channel_name: result.channel_name,
+            channel_label: destination_label(runner.workspace(workspace), result),
+            channel_type: result.channel_type, count: group.size }
+        end
+      end
+
+      def display_counts(counts, entries)
+        if entries.empty?
+          puts 'No sent messages found.'
+          return
+        end
+
+        counts.each_value { |group| display_count(group) }
+        puts
+        entries.each { |workspace, result| display_entry(workspace, result) }
+      end
+
+      def display_entry(workspace, result)
+        options = format_options.merge(workspace_label: true, channel_label: destination_label(workspace, result))
+        runner.search_formatter.display_result(result, workspace, options)
+      end
+
+      def display_count(group)
+        workspace, result = group.first
+        puts "[#{workspace.name}] #{destination_label(workspace, result)}: #{group.size}"
+      end
+
+      def destination_label(workspace, result)
+        runner.sent_channel_label.label(
+          workspace: workspace, type: result.channel_type, name: result.channel_name,
+          channel_id: result.channel_id, self_user_id: result.user_id, self_username: result.username
+        )
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/slk/formatters/attachment_formatter.rb

@@ -32,7 +32,7 @@ module Slk
         format_author(attachment, lines)
         format_text(att_text, lines, options) if att_text && block_images.empty?
         format_image(attachment, lines, options, message_ts: message_ts, index: index) if image_url
-        block_images.each { |img| lines << "> [Image: #{img}]" }
+        format_block_images(block_images, lines)
       end
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
@@ -46,9 +46,13 @@ module Slk
         end
       end
 
+      def format_block_images(images, lines)
+        images.each { |img| lines << "> [Image: #{@text_processor.call(img)}]" }
+      end
+
       def format_author(attachment, lines)
         author = attachment['author_name'] || attachment['author_subname']
-        lines << "> #{@output.bold(author)}:" if author
+        lines << "> #{@output.bold(@text_processor.call(author))}:" if author
       end
 
       def format_text(att_text, lines, options)
@@ -73,7 +77,7 @@ module Slk
         else
           image_url = attachment['image_url'] || attachment['thumb_url']
           filename = attachment['title'] || extract_filename(image_url)
-          lines << "> [Image: #{filename}]"
+          lines << "> [Image: #{@text_processor.call(filename)}]"
         end
       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/formatters/search_formatter.rb

@@ -23,25 +23,38 @@ module Slk
       # Display a single search result
       def display_result(result, workspace, options = {})
         timestamp = @output.blue("[#{format_time(result.timestamp)}]")
-        channel = @output.cyan(resolve_channel(result, workspace))
+        channel = @output.cyan(display_channel_label(result, workspace, options))
         user = @output.bold("#{resolve_user(result, workspace)}:")
         text = prepare_text(result.text, workspace, options)
 
-        @output.puts "#{timestamp} #{channel} #{user} #{text}"
-        display_files(result.files) if result.files&.any?
+        workspace_label = workspace_prefix(workspace, options)
+        @output.puts "#{timestamp} #{workspace_label}#{channel} #{user} #{text}"
+        display_files(result.files, workspace, options) if result.files&.any?
       end
 
-      private
+      # Channel label used by search timelines and per-channel summaries.
+      def channel_label(result, workspace)
+        channel_label_for(result.channel_type, result.channel_name, workspace)
+      end
 
-      def resolve_channel(result, workspace)
-        if result.dm?
-          # For DMs, channel_name is a user ID - resolve it
-          @mentions.replace("<@#{result.channel_name}>", workspace)
+      def channel_label_for(type, name, workspace)
+        if %w[im mpim].include?(type)
+          @mentions.replace("<@#{name}>", workspace)
         else
-          "##{result.channel_name}"
+          "##{name}"
         end
       end
 
+      private
+
+      def display_channel_label(result, workspace, options)
+        options[:channel_label] || channel_label(result, workspace)
+      end
+
+      def workspace_prefix(workspace, options)
+        options[:workspace_label] ? "#{@output.cyan("[#{workspace.name}]")} " : ''
+      end
+
       def resolve_user(result, workspace)
         # If we have a username, use it directly
         return result.username if result.username && !result.username.empty?
@@ -57,9 +70,10 @@ module Slk
         @text_processor.process(text, workspace, options)
       end
 
-      def display_files(files)
+      def display_files(files, workspace, options)
         files.each do |file|
-          @output.puts @output.blue("[Image: #{file[:name]}]")
+          name = prepare_text(file[:name], workspace, options)
+          @output.puts @output.blue("[Image: #{name}]")
         end
       end