slk 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 139ba582e24a6b92cd79493c0000a1479fbeb4ce59c90d883d0bbb603e8ff4c7
-  data.tar.gz: 81bdd74fc8a1d9b44480272098f78744297b3bd2b42b39dbc25c7f1fdb891c2f
+  metadata.gz: ae44e63120d4264c9adeb4adb2ea9aba96c4fe9e6087c1134f9bd9d8480a843e
+  data.tar.gz: '087ea385b7cf62868737d1e583e60ec9fac5aee8bb3d49f711f5c979413db4e7'
 SHA512:
-  metadata.gz: f79c404a79de6d32c77e85226b92b65322ff159ae610201d3514abc66fc9f8497a30c29da802b81e0ed2f36cdb3bc805835eee0e85f744f0f323d2620391c483
-  data.tar.gz: 6fff7a3b9b11762d179ccd2d22e5a0e4a6e395f52bd4fe89810cb045fed144c989026c07928179efdcd35e8ac3c3c991dab8f90344042cd0475adc8fc1007d7e
+  metadata.gz: 71be8f27208e35f5dfe81c3504f38f40af7a7630d93802ba56316e07778aa631f7a42ffe1172b9b1c280735871c0667b5b6568a3bb0224642cdabf59523ac8c5
+  data.tar.gz: 9e4b991d52004df5100fe901e87c1b61f8c50a8fa501665f2cb0a5f58f31a37a6ffae6cbe5c287aac7ae2e99f679cea0889c80866f7980b7f495c7311a507c73

data/CHANGELOG.md

@@ -5,7 +5,53 @@ 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).
 
-## [Unreleased]
+## [0.8.0] - 2026-08-30
+
+### Added
+
+- **`slk status` now answers the questions the status raises** — who can reach you, and whether the status is about to change on its own
+  - Presence and DND appear as suffixes on the status line: `:computer: Working [away] [dnd until 3:00pm]`. Only exceptional states are labelled, so the workspace that differs stands out rather than being buried under "active" on every line
+  - `[dnd until …]` covers a manual snooze and the configured DND hours alike — from the outside both mean messages do not notify — and reports the later end when both apply. `slk dnd` still breaks out which is which
+  - Anything scheduled to turn on later is listed under the status, soonest first and without IDs; `slk status scheduled` remains the view to paste an ID from
+  - Times carry a day when the end is not today, so an overnight window does not read as a time that has already passed
+- **`slk status --json`** (and `slk status scheduled --json`) for scripts and statuslines
+  - Always an array, one entry per workspace, even for a single workspace: a document whose shape changes with `-w` cannot be parsed by a script that did not pass it
+  - `null` means "not checked" — skipped by a flag, or a lookup that failed — as distinct from checked-and-empty. A statusline that read a failed DND lookup as "DND off" would report the opposite of the truth
+  - Every timestamp appears twice: Slack's own epoch under Slack's own field name, and an ISO 8601 string beside it
+- **`--brief` and `--no-scheduled`** for the get view. It now costs up to four calls per workspace; `--no-scheduled` drops the internal `users.customStatus.list` lookup and `--brief` drops all three extras. `--quiet` skips them too, since their output would be discarded (`--json` still gathers them: it prints regardless)
+
+### Changed
+
+- A failed presence, DND or schedule lookup during `slk status` warns and omits that part instead of failing the command — the status itself is what was asked for. A rate limit stops the remaining extra lookups altogether rather than spending calls the status reads need
+
+## [0.7.0] - 2026-08-03
+
+### Added
+
+- **`slk status schedule|scheduled|unschedule`** — queue statuses to turn on later
+  - `slk status schedule "<text>" [:emoji:] <start-end>` schedules a status; emoji defaults to `:speech_balloon:`
+  - Time windows accept bare 12- or 24-hour times (`1:30p-3:30p`, `13:30-15:30`) or an explicit `YYYY-MM-DD` date (`2026-08-04 9:00-17:00`)
+  - Bare times resolve forward: a window at or before now rolls to tomorrow, and an end before the start crosses midnight (`11p-1a`)
+  - A single am/pm carries across the range, so `1-3p` is 1pm to 3pm — unless that would invert it, leaving `9-5p` as 9am to 5pm
+  - Ambiguous or impossible windows are rejected rather than guessed: `9-5` and `9a-5` (both read as crossing midnight and spanning 20 hours), `1p-1p`, a time DST skips, and unrecognized date forms such as `8/4` or `tomorrow`
+  - The check applies only to a reading that had to be guessed, and only past 12 hours, so windows that say what they mean still work: `11p-1a`, `8p-9a`, `20:00-09:00`, `20:00-6`, and `9p-5`
+  - `--start WHEN` / `--end WHEN` take `[YYYY-MM-DD ]TIME` each, for windows the single-date range cannot express: `--start "2026-08-12 8a" --end "2026-08-14 5p"`. Omitting `--end` schedules a status with no expiry
+  - `--with-dnd` also pauses notifications while the status is active
+  - `slk status scheduled` lists pending statuses with their IDs across every workspace; `slk status unschedule <id>` looks up which workspace owns the ID rather than assuming the primary one (`-w`/`--all` still override)
+  - `slk status scheduled` marks the one Slack reports as currently applied with `[active]`
+  - Backed by Slack's internal `users.customStatus.*` endpoints, which require form-encoded bodies and only return the scheduled section when `statuses_count_per_section` is sent. Responses are checked rather than trusted: an absent `scheduled_statuses` section, a create that echoes nothing back, a status payload with no id, and a delete the following list still shows all raise instead of reporting success
+
+### Changed
+
+- New `Slk::UsageError` (bad invocation) and `Slk::TimeFormatError` (unparseable time) error types. `slk` prints them without an error-type label, and callers can rescue malformed input without also swallowing arity or range errors from their own code
+- Flags that take a value now reject a missing one or a following flag instead of shifting `nil`. This covers `--start`, `--end`, `-p` and `-d` on `status`, and `-w`/`--workspace` everywhere — a trailing `slk status -w` previously applied to *every* workspace and exited 0
+
+### Fixed
+
+- `slk status unschedule` no longer reports a successful cancel as a failure when the confirming re-read fails (a network error, a rate limit, or Slack dropping the `scheduled_statuses` section — which is exactly what happens when you cancel your only scheduled status). The cancel is reported with an explicit "could not confirm" caveat and exit 0; only a status still demonstrably present is an error
+- `slk status schedule` again reports an unusable Slack response as "check the status picker to see whether it was created" rather than the less actionable "returned a scheduled status with no id"
+- `Slk::UsageError` no longer files a backtrace in `~/.cache/slk/error.log`; a mistyped flag is not a fault to investigate later
+- SSH key validation no longer hangs on Windows when the private key is passphrase-protected. `ssh-keygen` prompts on the console rather than on stdin, so the prompt could not be answered or dismissed; it is now given an empty passphrase up front and reports the unsupported key instead of waiting
 
 ## [0.6.0] - 2026-04-27
 
@@ -183,6 +229,9 @@ Initial release of the Ruby rewrite. Pure Ruby, no external dependencies.
   - Pure Ruby stdlib - no gem dependencies
   - Ruby 3.2+ with modern features (Data.define, pattern matching)
 
+[0.8.0]: https://github.com/ericboehs/slk/releases/tag/v0.8.0
+[0.7.0]: https://github.com/ericboehs/slk/releases/tag/v0.7.0
+[0.6.0]: https://github.com/ericboehs/slk/releases/tag/v0.6.0
 [0.5.0]: https://github.com/ericboehs/slk/releases/tag/v0.5.0
 [0.4.2]: https://github.com/ericboehs/slk/releases/tag/v0.4.2
 [0.4.0]: https://github.com/ericboehs/slk/releases/tag/v0.4.0

data/README.md

@@ -46,12 +46,83 @@ You'll need a Slack token. Get one from:
 ### Status
 
 ```bash
-slk status                              # Show current status
+slk status                              # Status, presence, DND and what's queued next
+slk status --brief                      # Status text only (one call per workspace)
+slk status --json                       # Machine-readable, for scripts and statuslines
 slk status "Working from home" :house:  # Set status with emoji
 slk status "In a meeting" :calendar: 1h # Set status for 1 hour
 slk status clear                        # Clear status
 ```
 
+Getting the status also answers the two questions it usually raises — can anyone
+reach me, and is this about to change on its own:
+
+```
+$ slk status
+work
+  :computer: Working [away] [dnd until 3:00pm]
+  Scheduled:
+    :paw_prints: Vet Appt (Mon Aug 3 1:30pm -> 3:30pm)
+side-project
+  (no status set)
+```
+
+Only the exceptional states are labelled: an active, notifiable workspace says
+nothing, so the one that differs stands out. `[dnd until ...]` covers both a
+manual snooze and the configured DND hours — from the outside they are the same
+thing — and `slk dnd` breaks out which.
+
+Each of those is a separate call, so `slk status` costs up to four per
+workspace. `--no-scheduled` drops the schedule lookup (the one internal
+endpoint), `--brief` drops all three, and a lookup that fails warns and leaves
+that part out rather than failing the command.
+
+#### JSON output
+
+`slk status --json` (and `slk status scheduled --json`) prints one entry per
+workspace — always an array, even for a single workspace, so a script that did
+not pass `-w` can still parse it. `null` means *not checked* (skipped by a flag,
+or the lookup failed), which is not the same as checked-and-empty: a statusline
+that read a failed DND lookup as "DND off" would say the opposite of the truth.
+Every timestamp appears twice, as Slack's epoch and as ISO 8601:
+
+```bash
+# "away, quiet until 3:00pm"
+slk status -w work --json --no-scheduled |
+  jq -r '.[0] | "\(.presence.presence)\(if .dnd.active then ", quiet until " + (.dnd.until | strflocaltime("%-I:%M%p")) else "" end)"'
+```
+
+Statuses can also be scheduled to turn on later (Slack allows up to 5 at a time):
+
+```bash
+slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p       # Bare times; rolls to tomorrow if past
+slk status schedule "OOO" :palm_tree: 2026-08-04 9:00-17:00   # Explicit date
+slk status schedule "Heads down" :no_bell: 11p-1a --with-dnd  # Overnight, pausing notifications
+slk status scheduled                                          # List pending (all workspaces)
+slk status unschedule CS0BMQDDGWTU                            # Cancel one (finds the owning workspace)
+```
+
+A single am/pm carries across the range, so `1-3p` is 1pm to 3pm — unless that
+would invert it, leaving `9-5p` as 9am to 5pm. Anything the am/pm cannot settle
+is read as a 24-hour time, which is usually right but occasionally means the
+opposite of what you typed: `9-5` and `9a-5` both come out as 9am until 5am the
+next morning. Windows that land that way — guessed, crossing midnight, and over
+12 hours — are rejected rather than scheduled, so add the second am/pm (`9a-5p`)
+or use 24-hour times (`9:00-17:00`).
+
+Overnight windows are fine when they say so. A meridiem on both sides (`11p-1a`,
+`8p-9a`) or a 24-hour time on either side (`20:00-09:00`, `20:00-6`) settles the
+range, and a pm start is enough on its own: `9p-5` is 9pm to 5am.
+
+A `start-end` range writes the date once and the end can only reach the next
+day, so multi-day windows use `--start` / `--end` instead. Each takes
+`[YYYY-MM-DD ]TIME`, and omitting `--end` schedules a status with no expiry:
+
+```bash
+slk status schedule "OOO" :palm_tree: --start "2026-08-12 8a" --end "2026-08-14 5p"
+slk status schedule "Heads down" :no_bell: --start 2p         # Stays until cleared
+```
+
 ### Presence
 
 ```bash

data/lib/slk/api/custom_status.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Slk
+  module Api
+    # Wrapper for Slack's internal users.customStatus.* endpoints, which back
+    # the "Scheduled" section of the status picker.
+    #
+    # Two undocumented quirks these methods paper over:
+    #   - Only form-encoded bodies are accepted. A JSON body is ignored and the
+    #     call fails with invalid_arguments naming every field as missing.
+    #   - list omits scheduled_statuses entirely unless
+    #     statuses_count_per_section is passed.
+    class CustomStatus
+      DEFAULT_SECTION_COUNT = 20
+
+      def initialize(api_client, workspace)
+        @api = api_client
+        @workspace = workspace
+      end
+
+      # @return [Hash] raw response; 'statuses' (recent) and 'scheduled_statuses'
+      #   (pending) are each absent when Slack omits the section
+      def list(count_per_section: DEFAULT_SECTION_COUNT)
+        @api.post_form(@workspace, 'users.customStatus.list',
+                       { statuses_count_per_section: count_per_section.to_s })
+      end
+
+      # @return [Array<Models::ScheduledStatus>] pending statuses only
+      def scheduled(count_per_section: DEFAULT_SECTION_COUNT)
+        response = list(count_per_section: count_per_section)
+        section = response['scheduled_statuses']
+        # An absent section is a protocol change, not an empty list. Reporting
+        # it as "none scheduled" would invite the user to re-create statuses
+        # that still exist.
+        unless section.is_a?(Array)
+          raise ApiError.new('Slack returned no scheduled_statuses section; this internal endpoint may have changed. ' \
+                             'Check the Slack status picker before re-scheduling.',
+                             code: :missing_scheduled_section)
+        end
+
+        section.map { |item| Models::ScheduledStatus.from_api(item) }
+      end
+
+      # @param date_scheduled [Integer] Unix timestamp the status turns on
+      # @param date_expire [Integer, nil] Unix timestamp it clears
+      # @param dnd [Boolean] also pause notifications while active
+      # @return [Models::ScheduledStatus]
+      def schedule(text:, emoji:, date_scheduled:, date_expire: nil, dnd: false)
+        params = { text: text, emoji: emoji, date_scheduled: date_scheduled.to_i.to_s }
+        params[:date_expire] = date_expire.to_i.to_s if date_expire
+        params[:is_dnd] = 'true' if dnd
+
+        response = @api.post_form(@workspace, 'users.customStatus.schedule', params)
+        Models::ScheduledStatus.from_api(confirmed_schedule(response))
+      end
+
+      # Slack answers a delete with ok: true whether or not anything changed —
+      # including for an id that never existed — so the response alone is not
+      # evidence. Re-reading the list at least catches an accepted delete that
+      # did not apply. It cannot distinguish "cancelled" from "was never
+      # there": both leave the id absent. `unschedule` covers that case ahead
+      # of time by finding the workspace that owns the id.
+      #
+      # @return [Array(Symbol, String, nil)] `[:cancelled, nil]`, or
+      #   `[:unconfirmed, reason]` when the delete was accepted but the
+      #   following read failed. Those are different things: only the second
+      #   read failed, and reporting it as a failed *cancel* would send the
+      #   user back to re-cancel something already gone.
+      # @raise [ApiError] only when the status is demonstrably still there
+      def delete_scheduled(custom_status_id)
+        @api.post_form(@workspace, 'users.customStatus.deleteScheduled',
+                       { custom_status_id: custom_status_id })
+        confirm_deleted(custom_status_id)
+      end
+
+      private
+
+      # The delete has already been accepted by the time this runs, so this
+      # only decides how much can honestly be said about it. A read that
+      # fails — including a rate-limited one, since the confirming read hits
+      # the same `list` method a multi-workspace sweep just used — is a
+      # failure to look, not a failure to delete.
+      def confirm_deleted(custom_status_id)
+        return [:cancelled, nil] unless scheduled.any? { |status| status.id == custom_status_id }
+
+        raise ApiError.new("Slack reported success but #{custom_status_id} is still scheduled.",
+                           code: :delete_not_applied)
+      rescue ApiError => e
+        raise if e.code == :delete_not_applied
+
+        [:unconfirmed, e.message]
+      end
+
+      # A create that reports ok without echoing back the status it made has
+      # not demonstrably created anything.
+      #
+      # The id check duplicates ScheduledStatus.validate!, deliberately:
+      # letting an id-less payload through to that guard trades this message
+      # for "Slack returned a scheduled status with no id: {}", which tells
+      # the user nothing they can act on. Here the answer is the same either
+      # way — go look at the picker.
+      def confirmed_schedule(response)
+        payload = response['scheduled_status']
+        return payload if payload.is_a?(Hash) && !payload['id'].to_s.empty?
+
+        raise ApiError.new('Slack accepted the request but returned no scheduled status, so nothing was confirmed. ' \
+                           'Check the Slack status picker to see whether it was created.',
+                           code: :malformed_schedule_response)
+      end
+    end
+  end
+end

data/lib/slk/cli.rb

@@ -72,7 +72,7 @@ module Slk
       else
         show_unknown_command(command_name)
       end
-    rescue ConfigError, EncryptionError, ApiError => e
+    rescue ConfigError, EncryptionError, ApiError, UsageError => e
       handle_known_error(e)
     end
 
@@ -86,7 +86,10 @@ module Slk
     def handle_known_error(error)
       label = error_label(error)
       @output.error(label ? "#{label}: #{error.message}" : error.message)
-      log_error(error)
+      # error.log exists to investigate faults after the fact. A mistyped flag
+      # or an unparseable time is not one, and filing a backtrace for it both
+      # buries the real entries and contradicts what UsageError promises.
+      log_error(error) unless error.is_a?(UsageError)
       1
     end
 

data/lib/slk/commands/base.rb

@@ -65,7 +65,7 @@ module Slk
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
       def parse_single_option(arg, args, remaining)
         case arg
-        when '-w', '--workspace' then @options[:workspace] = args.shift
+        when '-w', '--workspace' then @options[:workspace] = option_value(arg, args)
         when '--width' then parse_width_option(args)
         when '--no-wrap' then @options[:width] = nil
         when '--all' then @options[:all] = true
@@ -93,6 +93,18 @@ module Slk
 
       protected
 
+      # A bare `args.shift` returns nil for a trailing flag, which then reads
+      # as an option nobody set: `slk status -w` selected *every* workspace
+      # and exited 0, the opposite of what it says. A following flag is the
+      # same mistake one token later — `--end --with-dnd` would take
+      # "--with-dnd" as the time.
+      def option_value(flag, args)
+        value = args.first
+        raise UsageError, "#{flag} requires a value." if value.nil? || value.start_with?('-')
+
+        args.shift
+      end
+
       # Override in subclass to handle command-specific options
       # Return true if option was handled, false to raise unknown option error
       def handle_option(arg, _args, _remaining) # rubocop:disable Naming/PredicateMethod

data/lib/slk/commands/help.rb

@@ -74,6 +74,7 @@ module Slk
             slk status                       Show current status
             slk status "Working" :laptop:    Set status
             slk status clear                 Clear status
+            slk status schedule "Vet" 1p-3p  Schedule a status (am/pm or 24h)
             slk dnd 1h                       Enable DND for 1 hour
             slk messages #general            Read channel messages
             slk preset meeting               Apply preset