slk 0.7.0 → 0.9.0

data/lib/slk/commands/status.rb

@@ -38,24 +38,39 @@ module Slk
       protected
 
       def default_options
-        super.merge(presence: nil, dnd: nil, with_dnd: false, start_at: nil, end_at: nil)
+        super.merge(presence: nil, dnd: nil, with_dnd: false, start_at: nil, end_at: nil,
+                    scheduled: true, brief: false)
       end
 
+      # Flags that only flip a boolean live here rather than in the case below,
+      # which is already at the branch count the linter allows.
+      TOGGLES = { '--with-dnd' => [:with_dnd, true], '--brief' => [:brief, true],
+                  '--no-scheduled' => [:scheduled, false] }.freeze
+
       def handle_option(arg, args, remaining)
+        return toggle(arg) if TOGGLES.key?(arg)
+
         case arg
         when '-p', '--presence' then @options[:presence] = option_value(arg, args)
         when '-d', '--dnd' then @options[:dnd] = option_value(arg, args)
-        when '--with-dnd' then @options[:with_dnd] = true
         when '--start' then @options[:start_at] = option_value(arg, args)
         when '--end' then @options[:end_at] = option_value(arg, args)
         else super
         end
       end
 
+      # True means "consumed", the contract Base#handle_option expects back.
+      def toggle(arg) # rubocop:disable Naming/PredicateMethod
+        key, value = TOGGLES[arg]
+        @options[key] = value
+        true
+      end
+
       def help_text
         help = Support::HelpFormatter.new('slk status [text] [emoji] [duration] [options]')
         help.description('Get or set your Slack status.')
-        help.note('GET shows all workspaces by default. SET applies to primary only.')
+        help.note('GET shows status, presence, DND and anything queued to turn on later.')
+        help.note('GET covers all workspaces by default; SET applies to primary only.')
         help.note('scheduled shows all workspaces; schedule applies to primary; unschedule finds the ID owner.')
         help.note('Slack allows at most 5 scheduled statuses at a time.')
         add_examples_section(help)
@@ -66,7 +81,9 @@ module Slk
 
       def add_examples_section(help)
         help.section('EXAMPLES') do |s|
-          s.example('slk status', 'Show status (all workspaces)')
+          s.example('slk status', 'Show status, presence, DND and schedule (all workspaces)')
+          s.example('slk status --brief', 'Status text only, no extra lookups')
+          s.example('slk status --json', 'Machine-readable; null means "not checked"')
           s.example('slk status clear', 'Clear status')
           s.example('slk status "Working" :laptop:', 'Set status with emoji')
           s.example('slk status "Meeting" :calendar: 1h', 'Set status for 1 hour')
@@ -89,6 +106,7 @@ module Slk
       def add_options_section(help)
         help.section('OPTIONS') do |s|
           add_general_options(s)
+          add_getting_options(s)
           add_scheduling_options(s)
         end
       end
@@ -102,6 +120,14 @@ module Slk
         section.option('-q, --quiet', 'Suppress output')
       end
 
+      # These are ignored outside a plain `slk status` (and `scheduled`, for
+      # --json), so say so rather than leaving them looking universal.
+      def add_getting_options(section)
+        section.option('--brief', 'Getting only: skip the presence, DND and schedule lookups')
+        section.option('--no-scheduled', 'Getting only: skip the scheduled lookup, keep presence and DND')
+        section.option('--json', 'Getting only: JSON for scripts (also `slk status scheduled`)')
+      end
+
       # These are ignored outside `schedule`, so say so rather than leaving
       # --with-dnd looking like a sibling of -d/--dnd.
       def add_scheduling_options(section)
@@ -115,36 +141,116 @@ module Slk
       def get_status # rubocop:disable Naming/AccessorMethodName
         # GET defaults to all workspaces unless -w specified
         workspaces = target_workspaces_for_get
+        snapshots = workspaces.map { |workspace| snapshot_for(workspace) }
+        return render_snapshots_json(snapshots) if @options[:json]
 
-        workspaces.each do |workspace|
-          status = runner.users_api(workspace.name).get_status
-          print_workspace_status(workspaces, workspace, status)
+        snapshots.each { |snapshot| print_snapshot(snapshot, labelled: workspaces.size > 1) }
+        0
+      end
+
+      # The status text is what was asked for. Presence, DND and the pending
+      # schedule are what it is usually being read *for* — whether anyone can
+      # reach you, and whether the status is about to change on its own — so
+      # they are gathered alongside it, one call each, none of them fatal.
+      def snapshot_for(workspace)
+        status = runner.users_api(workspace.name).get_status
+        return Models::StatusSnapshot.new(workspace: workspace, status: status) unless details?
+
+        Models::StatusSnapshot.new(workspace: workspace, status: status, **workspace_details(workspace))
+      end
+
+      def workspace_details(workspace)
+        {
+          presence: detail(workspace, 'presence') { runner.users_api(workspace.name).get_presence },
+          dnd: detail(workspace, 'DND') { Models::DndState.from_api(runner.dnd_api(workspace.name).info) },
+          scheduled: pending_scheduled(workspace)
+        }
+      end
+
+      # --brief drops the extra calls; under --quiet their output is discarded,
+      # so they would buy nothing. --json prints even when quiet, and its
+      # consumers are the ones that want the detail most.
+      def details?
+        return false if @options[:brief]
+
+        @options[:json] || !@options[:quiet]
+      end
+
+      def pending_scheduled(workspace)
+        return nil unless @options[:scheduled]
+
+        detail(workspace, 'scheduled statuses') do
+          in_order(runner.custom_status_api(workspace.name).scheduled)
         end
+      end
 
+      # nil, not a blank value: the caller records "not checked", which --json
+      # reports as null. Reporting a failed DND lookup as "DND off" would say
+      # the opposite of the truth to anything reading it.
+      def detail(workspace, label)
+        return nil if @details_unavailable
+
+        yield
+      rescue RateLimitError => e
+        # Being throttled while decorating the answer is a reason to stop
+        # decorating. These calls are optional; the status reads they would
+        # crowd out are not.
+        @details_unavailable = true
+        warn("Rate limited; skipping presence, DND and scheduled lookups: #{e.message}")
+        nil
+      rescue ApiError => e
+        warn("Could not read #{label} on #{workspace.name}: #{e.message}")
+        nil
+      end
+
+      def render_snapshots_json(snapshots)
+        output_json(json_formatter.format(snapshots))
         0
       end
 
+      def json_formatter = Formatters::JsonStatusFormatter.new
+
+      def print_snapshot(snapshot, labelled:)
+        puts output.bold(snapshot.workspace_name) if labelled
+        print_status_line(snapshot)
+        print_upcoming(snapshot.scheduled)
+      end
+
+      # A status that turns on this afternoon is the reason to leave the
+      # current one alone, so it is listed under it rather than a command away.
+      def print_upcoming(scheduled)
+        return if scheduled.nil? || scheduled.empty?
+
+        puts '  Scheduled:'
+        # No IDs here; `slk status scheduled` is the view you paste from.
+        scheduled.each { |status| puts "    #{status}" }
+      end
+
       def target_workspaces_for_get
         @options[:workspace] ? [runner.workspace(@options[:workspace])] : runner.all_workspaces
       end
 
-      def print_workspace_status(workspaces, workspace, status)
-        puts output.bold(workspace.name) if workspaces.size > 1
+      def print_status_line(snapshot)
+        suffix = snapshot.labels.join(' ')
 
-        if status.empty?
-          puts '  (no status set)'
+        if snapshot.status.empty?
+          # Away or on DND with no status is still worth saying: it is the
+          # difference between "nothing to report" and "unreachable".
+          puts join_suffix('  (no status set)', suffix)
         else
-          display_status(workspace, status)
+          display_status(snapshot.workspace, snapshot.status, suffix)
         end
       end
 
-      def display_status(workspace, status)
+      def join_suffix(line, suffix) = suffix.empty? ? line : "#{line} #{suffix}"
+
+      def display_status(workspace, status, suffix = '')
         emoji_path = workspace_emoji_path(workspace.name, status.emoji)
 
         if emoji_path && inline_images_supported?
-          print_status_with_image(emoji_path, status)
+          print_status_with_image(emoji_path, status, suffix)
         else
-          puts "  #{status}"
+          puts join_suffix("  #{status}", suffix)
         end
       end
 
@@ -153,10 +259,11 @@ module Slk
         find_workspace_emoji(workspace_name, emoji_name)
       end
 
-      def print_status_with_image(emoji_path, status)
+      def print_status_with_image(emoji_path, status, suffix = '')
         parts = []
         parts << status.text unless status.text.empty?
         parts << "(#{status.time_remaining})" if status.time_remaining
+        parts << suffix unless suffix.empty?
         print_inline_image_with_text(emoji_path, "  #{parts.join(' ')}")
       end
 
@@ -347,6 +454,7 @@ module Slk
 
       def list_scheduled
         workspaces = target_workspaces_for_get
+        return list_scheduled_json(workspaces) if @options[:json]
 
         each_workspace_reporting(workspaces) do |workspace|
           puts output.bold(workspace.name) if workspaces.size > 1
@@ -354,12 +462,29 @@ module Slk
         end
       end
 
+      # Every workspace appears whether or not its lookup worked, so the array
+      # still lines up with the workspaces asked about; a failed one is null
+      # rather than an empty list, and its reason went to stderr.
+      def list_scheduled_json(workspaces)
+        pending = workspaces.to_h { |workspace| [workspace.name, nil] }
+
+        code = each_workspace_reporting(workspaces) do |workspace|
+          pending[workspace.name] = in_order(runner.custom_status_api(workspace.name).scheduled)
+        end
+
+        output_json(json_formatter.format_scheduled(pending))
+        code
+      end
+
       def print_scheduled(scheduled)
         return puts '  (none scheduled)' if scheduled.empty?
 
-        scheduled.each { |status| puts "  #{status.id}  #{status}" }
+        in_order(scheduled).each { |status| puts "  #{status.id}  #{status}" }
       end
 
+      # Soonest first: the next one to turn on is the one being read for.
+      def in_order(scheduled) = scheduled.sort_by(&:date_scheduled)
+
       def unschedule_status(args)
         id = args.first
         return error('Usage: slk status unschedule <id>') if id.to_s.strip.empty?

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/formatters/json_status_formatter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Slk
+  module Formatters
+    # Renders `slk status` snapshots as JSON for scripts and statuslines.
+    #
+    # Two shape rules the consumers depend on:
+    #
+    #   - Always an array, one entry per workspace, even for a single one. The
+    #     workspace set changes with -w/--all, and a document whose shape
+    #     changes with a flag cannot be parsed by a script that did not pass it.
+    #   - null means "not checked" (skipped, or the lookup failed); an empty
+    #     array or false means checked. A statusline that treats a failed DND
+    #     lookup as "DND off" would quietly say the opposite of the truth.
+    #
+    # Timestamps appear twice: the raw Slack epoch under Slack's own field name
+    # and an ISO 8601 string beside it, so neither jq nor the shell has to do
+    # date arithmetic to print "until 3:00pm".
+    class JsonStatusFormatter
+      def format(snapshots)
+        snapshots.map { |snapshot| snapshot_hash(snapshot) }
+      end
+
+      # `slk status scheduled --json`: the same array, narrowed to the part
+      # that command is about, so a script can read either with one shape.
+      #
+      # @param by_workspace [Hash{String => Array<Models::ScheduledStatus>, nil}]
+      def format_scheduled(by_workspace)
+        by_workspace.map do |name, scheduled|
+          { workspace: name, scheduled: scheduled&.map { |status| scheduled_hash(status) } }
+        end
+      end
+
+      private
+
+      def snapshot_hash(snapshot)
+        {
+          workspace: snapshot.workspace_name,
+          status: status_hash(snapshot.status),
+          presence: presence_hash(snapshot.presence),
+          dnd: dnd_hash(snapshot.dnd),
+          scheduled: snapshot.scheduled&.map { |status| scheduled_hash(status) }
+        }
+      end
+
+      def status_hash(status)
+        {
+          text: status.text,
+          emoji: status.emoji,
+          # Slack's own 0-for-never, kept as-is; `expires_at` is the readable
+          # form and is null rather than "1970-01-01" when there is no expiry.
+          expiration: status.expiration,
+          expires_at: iso8601(status.expiration_time),
+          empty: status.empty?
+        }
+      end
+
+      def presence_hash(presence)
+        return nil unless presence
+
+        { presence: presence[:presence], manual_away: presence[:manual_away], online: presence[:online] }
+      end
+
+      def dnd_hash(dnd)
+        return nil unless dnd
+
+        {
+          active: dnd.active?,
+          source: dnd.source&.to_s,
+          snoozing: dnd.snoozing,
+          in_scheduled_hours: dnd.in_scheduled_hours?,
+          until: dnd.until_time&.to_i,
+          until_at: iso8601(dnd.until_time)
+        }
+      end
+
+      # Slack's own field names and epochs, plus a readable form of each
+      # timestamp. `slice` rather than the whole record on purpose: this is a
+      # published shape, and a field added to the model later should not join
+      # it without someone deciding to.
+      def scheduled_hash(status)
+        status.to_h.slice(:id, :text, :emoji, :date_scheduled, :date_expire, :dnd, :active)
+              .merge(starts_at: iso8601(status.starts_at), ends_at: iso8601(status.ends_at))
+      end
+
+      def iso8601(time) = time&.iso8601
+    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/models/dnd_state.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Slk
+  module Models
+    # Current Do Not Disturb state for one workspace, from dnd.info.
+    #
+    # Slack reports two independent things through that one endpoint: a manual
+    # snooze ("pause notifications for 2 hours") and the configured DND
+    # schedule ("quiet from 8pm to 8am"). From the outside they are the same
+    # thing — messages do not notify — so `active?` covers both and `source`
+    # says which one is responsible.
+    DndState = Data.define(:snoozing, :snooze_endtime, :scheduled, :next_start, :next_end) do
+      def self.from_api(data)
+        data = {} unless data.is_a?(Hash)
+
+        new(
+          snoozing: data['snooze_enabled'] == true,
+          snooze_endtime: data['snooze_endtime'].to_i,
+          scheduled: data['dnd_enabled'] == true,
+          next_start: data['next_dnd_start_ts'].to_i,
+          next_end: data['next_dnd_end_ts'].to_i
+        )
+      end
+
+      def active? = snoozing || in_scheduled_hours?
+
+      # `next_dnd_*` names the *next* window while DND hours are off and the
+      # current one while they are running, so "now falls inside it" is the
+      # only reading that means notifications are being held right now.
+      #
+      # Slack reports 1 for both schedule timestamps when no schedule is
+      # configured, so a bare `positive?` would read that as a window that
+      # opened in 1970 and never closed.
+      def in_scheduled_hours?
+        return false unless scheduled && next_start > 1 && next_end > next_start
+
+        now = Time.now.to_i
+        next_start <= now && now < next_end
+      end
+
+      def source
+        return :both if snoozing && in_scheduled_hours?
+        return :snooze if snoozing
+        return :schedule if in_scheduled_hours?
+
+        nil
+      end
+
+      # The later of the two when both apply: notifications stay off until
+      # every reason for holding them has expired, not the first.
+      def until_time
+        finishes = []
+        finishes << snooze_endtime if snoozing && snooze_endtime.positive?
+        finishes << next_end if in_scheduled_hours?
+
+        finish = finishes.max
+        finish ? Time.at(finish) : nil
+      end
+
+      # Same-day times need no date; an overnight schedule ending tomorrow
+      # morning would otherwise read as "until 8:00am" of a day already gone.
+      def until_label
+        finish = until_time or return nil
+        finish.to_date == Date.today ? finish.strftime('%-l:%M%P') : finish.strftime('%a %-l:%M%P')
+      end
+
+      # Empty when notifications are flowing: there is nothing to say, and a
+      # "[dnd off]" on every line would bury the workspace where it is on.
+      def to_s
+        return '' unless active?
+
+        label = until_label
+        # A snooze with no end time is a state Slack can report; saying "[dnd]"
+        # is honest about not knowing when it lifts.
+        label ? "[dnd until #{label}]" : '[dnd]'
+      end
+    end
+  end
+end

data/lib/slk/models/status_snapshot.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # Everything `slk status` knows about one workspace at one moment: the
+    # status itself, plus the two things that decide whether anyone can reach
+    # you (presence, DND) and whatever is queued to replace the status later.
+    #
+    # Every part but the status is optional, and nil means "not checked" —
+    # skipped by a flag, or a lookup that failed. That is deliberately distinct
+    # from checked-and-empty: `scheduled: []` says nothing is queued, while
+    # `scheduled: nil` says nobody looked.
+    StatusSnapshot = Data.define(:workspace, :status, :presence, :dnd, :scheduled) do
+      def initialize(workspace:, status:, presence: nil, dnd: nil, scheduled: nil)
+        super
+      end
+
+      def workspace_name = workspace.name
+
+      def away? = presence ? presence[:presence] == 'away' : false
+
+      # Short suffixes for the status line. Only the exceptional states appear:
+      # active presence and DND-off are the common case, and repeating them on
+      # every line would bury the workspace that differs.
+      def labels
+        [('[away]' if away?), dnd&.to_s].reject { |label| label.to_s.empty? }
+      end
+    end
+  end
+end