slk 0.5.0 → 0.7.0

data/lib/slk/commands/status.rb

@@ -10,6 +10,10 @@ module Slk
     class Status < Base
       include Support::InlineImages
 
+      SCHEDULE_USAGE = 'Usage: slk status schedule "<text>" [:emoji:] <start-end> | --start WHEN [--end WHEN]'
+      MISSING_RANGE = 'Missing time range. Example: slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p ' \
+                      '(or --start/--end for a multi-day window).'
+
       def execute
         result = validate_options
         return result if result
@@ -22,6 +26,9 @@ module Slk
 
       def dispatch_action
         case positional_args
+        in ['schedule', *rest] then schedule_status(rest)
+        in ['scheduled', *] then list_scheduled
+        in ['unschedule', *rest] then unschedule_status(rest)
         in ['clear', *] then clear_status
         in [text, *rest] then set_status(text, rest)
         in [] then get_status
@@ -31,17 +38,17 @@ module Slk
       protected
 
       def default_options
-        super.merge(presence: nil, dnd: nil)
+        super.merge(presence: nil, dnd: nil, with_dnd: false, start_at: nil, end_at: nil)
       end
 
       def handle_option(arg, args, remaining)
         case arg
-        when '-p', '--presence'
-          @options[:presence] = args.shift
-        when '-d', '--dnd'
-          @options[:dnd] = args.shift
-        else
-          super
+        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
 
@@ -49,7 +56,10 @@ module Slk
         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('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)
+        add_scheduling_section(help)
         add_options_section(help)
         help.render
       end
@@ -64,17 +74,42 @@ module Slk
         end
       end
 
+      def add_scheduling_section(help)
+        help.section('SCHEDULING') do |s|
+          s.example('slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p', 'Schedule for later')
+          s.example('slk status schedule "OOO" :palm_tree: 2026-08-04 9:00-17:00')
+          s.example('slk status schedule "OOO" :palm_tree: --start "2026-08-12 8a" --end "2026-08-14 5p"',
+                    'Span multiple days')
+          s.example('slk status schedule "Heads down" :no_bell: --start 2p', 'No end; stays until cleared')
+          s.example('slk status scheduled', 'List pending scheduled statuses')
+          s.example('slk status unschedule CS0BMQDDGWTU', 'Cancel a scheduled status')
+        end
+      end
+
       def add_options_section(help)
         help.section('OPTIONS') do |s|
-          s.option('-p, --presence VALUE', 'Also set presence (away/auto/active)')
-          s.option('-d, --dnd DURATION', "Also set DND (or 'off')")
-          s.option('-w, --workspace', 'Limit to specific workspace')
-          s.option('--all', 'Set across all workspaces')
-          s.option('-v, --verbose', 'Show debug information')
-          s.option('-q, --quiet', 'Suppress output')
+          add_general_options(s)
+          add_scheduling_options(s)
         end
       end
 
+      def add_general_options(section)
+        section.option('-p, --presence VALUE', 'Also set presence (away/auto/active)')
+        section.option('-d, --dnd DURATION', "Also set DND (or 'off')")
+        section.option('-w, --workspace', 'Limit to specific workspace')
+        section.option('--all', 'Set across all workspaces')
+        section.option('-v, --verbose', 'Show debug information')
+        section.option('-q, --quiet', 'Suppress output')
+      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)
+        section.option('--with-dnd', 'Scheduling only: pause notifications while the status is active')
+        section.option('--start WHEN', 'Scheduling only: window start, "[YYYY-MM-DD ]TIME"')
+        section.option('--end WHEN', 'Scheduling only: window end; omit for no expiry')
+      end
+
       private
 
       def get_status # rubocop:disable Naming/AccessorMethodName
@@ -210,6 +245,182 @@ module Slk
         0
       end
 
+      def schedule_status(args)
+        text, *rest = args
+        return error(SCHEDULE_USAGE) if text.to_s.strip.empty?
+
+        window = parse_schedule_window(rest)
+        return 1 unless window
+
+        result = create_scheduled_status(text, extract_emoji(rest), *window)
+        show_all_workspaces_hint
+        result
+      end
+
+      # Narrow on both axes: only the parsing is covered, so a Slack failure is
+      # not reported as a mistyped range, and only TimeFormatError is caught, so
+      # an arity or range error from this code does not surface as user error.
+      def parse_schedule_window(rest)
+        return flag_window(rest) if @options[:start_at] || @options[:end_at]
+
+        range = extract_time_range(rest)
+        return reject_window(MISSING_RANGE) unless range
+
+        Support::TimeRangeParser.parse(range)
+      rescue TimeFormatError => e
+        error(e.message)
+        nil
+      end
+
+      # --start/--end is the general form. Both times carry their own date, so
+      # it reaches multi-day windows the positional range cannot express, and
+      # omitting --end schedules a status that never auto-clears.
+      def flag_window(rest)
+        return reject_window('--end requires --start.') unless @options[:start_at]
+        return reject_window('Use either a time range or --start/--end, not both.') if extract_time_range(rest)
+
+        starts_at = Support::TimeParser.parse(@options[:start_at])
+        return [starts_at, nil] unless @options[:end_at]
+
+        [starts_at, validated_end(starts_at)]
+      end
+
+      def validated_end(starts_at)
+        ends_at = Support::TimeParser.parse(@options[:end_at])
+        # An explicit end is unambiguous, so there is nothing to roll forward.
+        return ends_at if ends_at > starts_at
+
+        raise TimeFormatError, "--end #{@options[:end_at]} is not after --start #{@options[:start_at]}."
+      end
+
+      # Returns nil so the caller reads it as "no window, already reported".
+      def reject_window(message)
+        error(message)
+        nil
+      end
+
+      # The range may arrive as one token ("1:30p-3:30p") or several
+      # ("2026-08-04 13:30-15:30"), so the non-emoji arguments are matched as a
+      # whole. Emoji are dropped first because the pattern is \A-anchored and a
+      # leading ":palm_tree:" would stop the date form from matching at all.
+      #
+      # Everything left has to be part of the range. Only YYYY-MM-DD dates
+      # parse, so picking the range out and discarding "8/4" or "tomorrow"
+      # would silently schedule the status for today.
+      def extract_time_range(rest)
+        candidates = rest.reject { |arg| arg.start_with?(':') && arg.end_with?(':') }
+        return nil if candidates.empty?
+
+        joined = candidates.join(' ')
+        return joined if Support::TimeRangeParser.match?(joined)
+
+        raise TimeFormatError, "Unrecognized argument: #{joined}. Use #{Support::TimeRangeParser::EXAMPLE}"
+      end
+
+      # Each workspace is an independent call, so one failure must not strand
+      # the workspaces after it: the user would re-run to fix the tail and
+      # double-schedule everything that already succeeded.
+      def each_workspace_reporting(workspaces)
+        failed = false
+
+        workspaces.each do |workspace|
+          yield workspace
+        rescue ApiError => e
+          failed = true
+          error("#{workspace.name}: #{e.message}")
+        end
+
+        failed ? 1 : 0
+      end
+
+      def create_scheduled_status(text, emoji, starts_at, ends_at)
+        each_workspace_reporting(target_workspaces) do |workspace|
+          scheduled = runner.custom_status_api(workspace.name).schedule(
+            text: text, emoji: emoji,
+            date_scheduled: starts_at, date_expire: ends_at,
+            dnd: @options[:with_dnd]
+          )
+          success("Scheduled on #{workspace.name}: #{scheduled}")
+          debug("  ID: #{scheduled.id}")
+        end
+      end
+
+      def list_scheduled
+        workspaces = target_workspaces_for_get
+
+        each_workspace_reporting(workspaces) do |workspace|
+          puts output.bold(workspace.name) if workspaces.size > 1
+          print_scheduled(runner.custom_status_api(workspace.name).scheduled)
+        end
+      end
+
+      def print_scheduled(scheduled)
+        return puts '  (none scheduled)' if scheduled.empty?
+
+        scheduled.each { |status| puts "  #{status.id}  #{status}" }
+      end
+
+      def unschedule_status(args)
+        id = args.first
+        return error('Usage: slk status unschedule <id>') if id.to_s.strip.empty?
+
+        @unchecked = []
+        targets = unschedule_targets(id)
+        return report_id_not_found(id) if targets.empty?
+
+        each_workspace_reporting(targets) do |workspace|
+          outcome, reason = runner.custom_status_api(workspace.name).delete_scheduled(id)
+          report_cancelled(workspace, outcome, reason)
+        end
+      end
+
+      # The delete succeeded either way, so both are successes — but only one
+      # of them has been checked, and saying so is the difference between the
+      # user moving on and the user re-cancelling something already gone.
+      def report_cancelled(workspace, outcome, reason)
+        return success("Cancelled scheduled status on #{workspace.name}") if outcome == :cancelled
+
+        warn("Cancelled scheduled status on #{workspace.name}, but could not confirm it: #{reason}")
+      end
+
+      # `slk status scheduled` lists every workspace, so the obvious next step
+      # is to paste an ID straight back in. Defaulting to the primary workspace
+      # made that fail with a bare Slack error whenever the ID came from
+      # another one, so look up the owner instead. An explicit -w/--all still
+      # wins, and a lone workspace needs no lookup.
+      def unschedule_targets(id)
+        return target_workspaces if @options[:all] || @options[:workspace]
+
+        workspaces = runner.all_workspaces
+        return workspaces if workspaces.size <= 1
+
+        [workspaces.find { |workspace| owns_scheduled?(workspace, id) }].compact
+      end
+
+      # "Not found" is only true of the workspaces we actually reached. Saying
+      # it flatly after warning that one could not be checked contradicts the
+      # warning, and pointing at `slk status scheduled` would just fail the
+      # same way — it calls the same endpoint.
+      def report_id_not_found(id)
+        return error("No scheduled status #{id} found. Run 'slk status scheduled' to list IDs.") if @unchecked.empty?
+
+        error("#{id} was not found, but #{@unchecked.join(', ')} could not be checked. " \
+              'Retry, or name the workspace with -w to cancel it directly.')
+      end
+
+      def owns_scheduled?(workspace, id)
+        runner.custom_status_api(workspace.name).scheduled.any? { |status| status.id == id }
+      rescue RateLimitError
+        # Every remaining check spends another call against the same limit, so
+        # continuing turns one rate limit into several and still cannot answer.
+        raise
+      rescue ApiError => e
+        # Skipping it silently would report "not found" for an ID that exists.
+        warn("Could not check #{workspace.name}: #{e.message}")
+        @unchecked << workspace.name
+        false
+      end
+
       def show_all_workspaces_hint
         # Show hint if user has multiple workspaces and didn't use --all or -w
         return if @options[:all] || @options[:workspace]

data/lib/slk/commands/who.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Slk
+  module Commands
+    # Display a Slack user profile (teems-style compact card by default).
+    # Examples:
+    #   slk who                  # self
+    #   slk who @alex
+    #   slk who alice
+    #   slk who Uxxx --full
+    #   slk who --json
+    class Who < Base
+      def execute
+        result = validate_options
+        return result if result
+
+        run
+      rescue ApiError => e
+        error("API error: #{e.message}")
+        1
+      end
+
+      protected
+
+      def handle_option(arg, args, _remaining)
+        case arg
+        when '--full' then @options[:full] = true
+        when '--no-cache', '--refresh' then @options[:refresh] = true
+        when '--all' then @options[:all] = true
+        when '--pick' then @options[:pick] = parse_pick(args.shift)
+        else return super
+        end
+        true
+      end
+
+      def help_text
+        <<~HELP
+          slk who [target]
+
+          Show a Slack user profile.
+
+          TARGET
+            (none)           Self
+            @handle | name   Resolved via user cache
+            Uxxx             Raw user ID
+
+          OPTIONS
+            --full           Section-grouped layout (Contact, People, About me)
+            --json           Raw JSON output
+            --refresh        Bypass cache
+            --all            Render every match (skips the disambiguation prompt)
+            --pick N         Auto-select match N when a name resolves to multiple
+        HELP
+      end
+
+      private
+
+      def parse_pick(value)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        raise ApiError, "--pick expects an integer (got #{value.inspect})"
+      end
+
+      def run
+        workspace = runner.workspace(@options[:workspace])
+        profiles = resolve_profiles(workspace)
+        return output_json_profiles(profiles) if @options[:json]
+
+        render_profiles(profiles)
+        0
+      end
+
+      def resolve_profiles(workspace)
+        resolver = Services::WhoTargetResolver.new(
+          workspace: workspace, cache_store: cache_store,
+          api_client: api_client, output: output, options: @options
+        )
+        resolver.resolve(positional_args.first).map { |id| load_profile(workspace, id) }
+      end
+
+      def load_profile(workspace, user_id)
+        runner.profile_resolver(workspace.name, refresh: @options[:refresh])
+              .resolve_with_people(user_id)
+      end
+
+      def render_profiles(profiles)
+        profiles.each_with_index do |profile, idx|
+          output.puts(output.gray('—' * 40)) if idx.positive?
+          render(profile)
+        end
+      end
+
+      def render(profile)
+        formatter = Formatters::ProfileFormatter.new(
+          output: output, emoji_replacer: runner.emoji_replacer
+        )
+        @options[:full] ? formatter.full(profile) : formatter.compact(profile)
+      end
+
+      def output_json_profiles(profiles)
+        payload = profiles.map { |p| profile_payload(p) }
+        output_json(profiles.size == 1 ? payload.first : payload)
+        0
+      end
+
+      def profile_payload(profile)
+        profile.to_h.merge(
+          custom_fields: profile.visible_fields.map(&:to_h),
+          sections: profile.sections,
+          resolved_users: profile.resolved_users.transform_values(&:to_h)
+        )
+      end
+    end
+  end
+end

data/lib/slk/formatters/output.rb

@@ -18,6 +18,8 @@ module Slk
 
       attr_reader :verbose, :quiet
 
+      def color? = @color
+
       def initialize(io: $stdout, err: $stderr, color: nil, verbose: false, quiet: false)
         @io = io
         @err = err

data/lib/slk/formatters/profile_field_renderer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Renders ProfileField values to display strings (date with relative
+    # phrasing, link with alt text, type:user dereferenced via resolved_users).
+    class ProfileFieldRenderer
+      def initialize(output:)
+        @output = output
+        @hyperlinks = output.respond_to?(:color?) && output.color?
+      end
+
+      def render(field, profile)
+        case field.type
+        when 'date' then format_date(field.value)
+        when 'link' then format_link(field)
+        when 'user' then format_user_list(field, profile)
+        else format_text(field.value)
+        end
+      end
+
+      # Slack stores some text fields (notably free-text profile blocks) as
+      # rich_text JSON blocks. Detect and flatten to plain text.
+      def format_text(value)
+        text = value.to_s
+        return text unless text.start_with?('[{') && text.include?('rich_text')
+
+        flatten_rich_text(JSON.parse(text))
+      rescue JSON::ParserError
+        text
+      end
+
+      def flatten_rich_text(blocks)
+        Array(blocks).flat_map { |block| extract_text_from_block(block) }.join
+      end
+
+      def extract_text_from_block(block)
+        return [block.to_s] unless block.is_a?(Hash)
+
+        return [block['text'].to_s] if block['type'] == 'text'
+        return [block['name'] ? ":#{block['name']}:" : ''] if block['type'] == 'emoji'
+
+        Array(block['elements']).flat_map { |el| extract_text_from_block(el) }
+      end
+
+      def render_user_reference(user_id, profile)
+        ref = profile.resolved_users[user_id]
+        return user_id unless ref
+
+        suffix = ref.title.to_s.empty? ? '' : " — #{ref.title}"
+        pronouns = ref.pronouns.to_s.empty? ? '' : " #{@output.gray("(#{ref.pronouns})")}"
+        "#{ref.best_name}#{pronouns}#{suffix}"
+      end
+
+      private
+
+      def format_user_list(field, profile)
+        field.user_ids.map { |uid| render_user_reference(uid, profile) }.join(', ')
+      end
+
+      def format_date(value)
+        date = parse_date(value) or return value
+        relative = relative_phrase(date, Date.today)
+        formatted = date.strftime('%b %-d, %Y')
+        relative ? "#{formatted} (#{relative})" : formatted
+      end
+
+      def parse_date(value)
+        Date.parse(value.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def relative_phrase(then_date, now_date)
+        return nil if then_date >= now_date
+
+        years, months = years_months_between(then_date, now_date)
+        parts = []
+        parts << "#{years}y" if years.positive?
+        parts << "#{months}mo" if months.positive?
+        parts.empty? ? nil : "#{parts.join(' ')} ago"
+      end
+
+      def years_months_between(then_date, now_date)
+        months = ((now_date.year - then_date.year) * 12) + (now_date.month - then_date.month)
+        months -= 1 if now_date.day < then_date.day
+        [months / 12, months % 12]
+      end
+
+      def format_link(field)
+        url = field.value.to_s
+        label = field.alt.to_s.empty? ? url : field.alt
+        return url if label == url
+        return "#{label} (#{shorten_url(url)})" unless @hyperlinks
+
+        # OSC 8 hyperlink — clickable in iTerm2, Ghostty, Wezterm, Kitty, Vte.
+        "\e]8;;#{url}\a#{label}\e]8;;\a"
+      end
+
+      def shorten_url(url)
+        URI.parse(url).host || url
+      rescue URI::InvalidURIError
+        url
+      end
+    end
+  end
+end

data/lib/slk/formatters/profile_formatter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Renders a Models::Profile for `slk who`.
+    # Compact mode: teems-style two-column card.
+    # Full mode: section-grouped layout matching Slack web UI.
+    class ProfileFormatter
+      MIN_LABEL_WIDTH = 8
+      MAX_LABEL_WIDTH = 20
+
+      def initialize(output:, emoji_replacer: nil)
+        @output = output
+        field_renderer = ProfileFieldRenderer.new(output: output)
+        @rows = ProfileRows.new(field_renderer: field_renderer, emoji_replacer: emoji_replacer)
+      end
+
+      def compact(profile)
+        render_header(profile)
+        emit_rows(@rows.compact(profile))
+        nil
+      end
+
+      def full(profile)
+        render_header(profile)
+        return emit_rows(@rows.external(profile)) if profile.external?
+
+        render_section('Contact information', @rows.contact(profile))
+        render_section('People', @rows.people(profile))
+        render_section('About me', @rows.about(profile))
+      end
+
+      def emit_rows(rows)
+        non_empty = rows.reject { |_, v| v.nil? || v.to_s.empty? }
+        width = label_width(non_empty)
+        non_empty.each { |label, value| emit_row(label, value, width) }
+      end
+
+      def label_width(rows)
+        max = rows.map { |label, _| label_for(label).length }.max || 0
+        max.clamp(MIN_LABEL_WIDTH, MAX_LABEL_WIDTH)
+      end
+
+      def label_for(label)
+        text = label.to_s
+        text.length > MAX_LABEL_WIDTH ? "#{text[0, MAX_LABEL_WIDTH - 1]}…" : text
+      end
+
+      private
+
+      def render_header(profile)
+        @output.puts(@output.bold(profile.best_name) + pronouns_suffix(profile))
+        header_tags(profile).each { |tag| @output.puts("  #{tag}") }
+        @output.puts
+      end
+
+      def header_tags(profile)
+        tags = []
+        tags << profile.title unless profile.title.to_s.empty?
+        tags << external_tag(profile) if profile.external?
+        tags << @output.bold('deactivated account') if profile.deleted
+        tags
+      end
+
+      def pronouns_suffix(profile)
+        profile.pronouns.to_s.empty? ? '' : " #{@output.gray("(#{profile.pronouns})")}"
+      end
+
+      def external_tag(profile)
+        @output.gray("external — #{profile.home_team_name || 'external workspace'}")
+      end
+
+      def render_section(title, rows)
+        return if rows.reject { |_, v| v.nil? || v.to_s.empty? }.empty?
+
+        @output.puts(@output.bold(title))
+        emit_rows(rows)
+        @output.puts
+      end
+
+      def emit_row(label, value, width)
+        padded = label_for(label).ljust(width)
+        @output.puts("  #{@output.gray(padded)} #{value}")
+      end
+    end
+  end
+end

data/lib/slk/formatters/profile_rows.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Slk
+  module Formatters
+    # Builds [label, value] row pairs from a Models::Profile.
+    # Pure data — no output, formatting handled by ProfileFormatter.
+    class ProfileRows
+      def initialize(field_renderer:, emoji_replacer: nil)
+        @fields = field_renderer
+        @emoji_replacer = emoji_replacer
+      end
+
+      def compact(profile)
+        contact(profile) + base(profile) + people(profile) + about(profile, skip_title: true)
+      end
+
+      def contact(profile)
+        [['Email', profile.email], ['Phone', profile.phone]]
+      end
+
+      def base(profile)
+        [
+          ['Presence', profile.presence_label],
+          ['Status', status_text(profile)],
+          ['Local', local_time(profile)]
+        ]
+      end
+
+      def people(profile)
+        profile.people_fields.flat_map do |field|
+          field.user_ids.map { |uid| [field.label, @fields.render_user_reference(uid, profile)] }
+        end
+      end
+
+      def about(profile, skip_title: false)
+        fields = profile.visible_fields.reject { |f| f.type == 'user' }
+        fields = fields.reject { |f| skip_title && duplicate_title?(f, profile) }
+        fields.map { |f| [f.label, @fields.render(f, profile)] }
+      end
+
+      def external(profile)
+        contact(profile) + [['Workspace', profile.home_team_name]]
+      end
+
+      private
+
+      def duplicate_title?(field, profile)
+        field.label.casecmp('Title').zero? && field.value.to_s == profile.title.to_s
+      end
+
+      def status_text(profile)
+        return nil if profile.status_text.empty? && profile.status_emoji.empty?
+
+        emoji = render_emoji(profile.status_emoji)
+        [emoji, profile.status_text].reject(&:empty?).join(' ')
+      end
+
+      def render_emoji(text)
+        return text if text.to_s.empty? || @emoji_replacer.nil?
+
+        @emoji_replacer.replace(text)
+      end
+
+      def local_time(profile)
+        return nil unless profile.tz
+
+        time_at_user = Time.now.utc + profile.tz_offset.to_i
+        "#{time_at_user.strftime('%-l:%M %p')} #{profile.tz_label}".strip
+      end
+    end
+  end
+end