slk 0.11.2 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 663f35d4a747ac42d0fb9596caa7dd7b4809d7f3451b811b7fb7e8389c7a991c
-  data.tar.gz: 42e1ba0fda08b83c644b77212155ab2c68ac318d95f4966060624f5f0eb94827
+  metadata.gz: 709675ee0926af3aee4e201318382d1558d6a46e4ebd8158a6353ee0da49f670
+  data.tar.gz: 8b82f996a687811516b17c6fe164a0dcedffc0e199de0eacadab61f37918955d
 SHA512:
-  metadata.gz: bd98ff12ddd5d0dfcf0ebc33e72852bfffed272c4136b74ed4b63b41ef38c0aab01b28826a02069738556781bec325a63b73eab66407f72c099de9186a6b56c2
-  data.tar.gz: 92a34fac64238598233edf4b8273d4597bb80deb07b316504649e21da575b4f56e75969a5178f2035c5fbaf5f0fa2ac70fe1eeb2e89d5baa3d6054285991a59a
+  metadata.gz: 2ab37ace8886dd600f194faf26f96597e422f2d1252aaba09fafacf83fff77e549bd9bc69be059cd567c787a3b2b2e69e0fc84360ac42f186916c1ea8930fe5d
+  data.tar.gz: 68f5dcd8ca42484c6c9783de5c35d02e95755046a69b1b0184b62ed4a84aaedfe0a2067821d18572e5b1f821ad98fe45a2af8b438f44930626df433a5806c5e3

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-10-06
+
+### Fixed
+
+- `slk unread --json` now prints exactly one valid JSON document, with no workspace name lines mixed in. With one workspace (or `-w`), it prints `{"channels": [...], "dms": [...]}` alone. With several, it prints an object keyed by workspace name: `{"oddball": {...}, "dsva": {...}}`. This changes the output shape for multi-workspace callers.
+- `slk unread -w WS` and `slk catchup -w WS` now limit themselves to that workspace. Before, they defaulted to all workspaces and ignored `-w`.
+- `slk unread` text output shows workspace name headers only when it covers more than one workspace.
+
+## [0.12.0] - 2026-09-30
+
+### Added
+
+- `slk thread subscribe <url>` follows a thread without posting in it, and `slk thread unsubscribe <url>` stops following it. The URL can point at the parent or any reply. Existing replies are marked read, so only new replies surface under Threads in `slk unread` and Slack's Threads view. `--json` reports the channel, thread, and last-read timestamps. Requires a session (`xoxc`) token; other token types get a hint instead of a bare API error.
+
 ## [0.11.2] - 2026-09-24
 
 ### Changed

data/README.md

@@ -149,6 +149,16 @@ slk messages general -n 50      # Show 50 messages
 slk messages general --json     # Output as JSON
 ```
 
+### Threads
+
+```bash
+slk thread <url>                # View a thread
+slk thread subscribe <url>      # Follow a thread without replying
+slk thread unsubscribe <url>    # Stop following it
+```
+
+Subscribing treats existing replies as read, so only new replies show up under Threads in `slk unread` (and in Slack's own Threads view). Requires a session (`xoxc`) token.
+
 ### Activity
 
 ```bash
@@ -344,10 +354,30 @@ rake test
 ### Releasing
 
 1. Update version in `lib/slk/version.rb`
-2. Update `CHANGELOG.md` (move Unreleased to new version, add date)
-3. Commit: `git commit -am "Release vX.Y.Z"`
-4. Release to RubyGems: `rake release`
-5. Create GitHub Release: `gh release create vX.Y.Z --generate-notes`
+2. Update `CHANGELOG.md`: add a `## [X.Y.Z] - YYYY-MM-DD` heading under `## [Unreleased]` so the pending entries move into the release
+3. Run `bundle install` so `Gemfile.lock` picks up the new version
+4. Verify: `bundle exec rake test && bundle exec rubocop`
+5. Commit version, changelog, and lockfile together, then push and wait for CI:
+   ```bash
+   git commit -am "chore(release): prepare vX.Y.Z"
+   git push origin master
+   gh run watch --exit-status
+   ```
+6. Build, tag, and push the tag:
+   ```bash
+   bundle exec rake build
+   git tag -a vX.Y.Z -m "Version X.Y.Z"
+   git push origin vX.Y.Z
+   ```
+7. Publish to RubyGems. `fnox exec` supplies `GEM_HOST_API_KEY` from `fnox.toml` (a stale key in `~/.gem/credentials` gets "Access Denied"); MFA is required, and `GEM_HOST_OTP_CODE` skips the prompt:
+   ```bash
+   fnox exec -- sh -c 'GEM_HOST_OTP_CODE="$(op item get Rubygems --otp)" gem push pkg/slk-X.Y.Z.gem'
+   ```
+8. Create the GitHub Release with the changelog entry as notes:
+   ```bash
+   awk '/^## \[X.Y.Z\]/{f=1;next} /^## \[/{f=0} f' CHANGELOG.md | sed '/./,$!d' > /tmp/notes.md
+   gh release create vX.Y.Z --title vX.Y.Z --notes-file /tmp/notes.md
+   ```
 
 ## License
 

data/lib/slk/api/threads.rb

@@ -28,6 +28,30 @@ module Slk
                        })
       end
 
+      # Subscribe to (follow) a thread so new replies land in the Threads view
+      # Requires a session (xoxc) token; this is an undocumented client endpoint.
+      # @param channel [String] Channel ID
+      # @param thread_ts [String] Thread parent timestamp
+      # @param last_read [String] Latest reply timestamp to treat as already read
+      def subscribe(channel:, thread_ts:, last_read:)
+        @api.post_form(@workspace, 'subscriptions.thread.add', subscription_params(channel, thread_ts, last_read))
+      end
+
+      # Unsubscribe from (unfollow) a thread
+      # @param channel [String] Channel ID
+      # @param thread_ts [String] Thread parent timestamp
+      # @param last_read [String] Latest reply timestamp to treat as already read
+      def unsubscribe(channel:, thread_ts:, last_read:)
+        @api.post_form(@workspace, 'subscriptions.thread.remove', subscription_params(channel, thread_ts, last_read))
+      end
+
+      # Check whether you are subscribed to a thread
+      # @param channel [String] Channel ID
+      # @param thread_ts [String] Thread parent timestamp
+      def get(channel:, thread_ts:)
+        @api.post_form(@workspace, 'subscriptions.thread.get', { channel: channel, thread_ts: thread_ts })
+      end
+
       # Get unread thread count
       # @return [Integer] Number of unread thread replies
       def unread_count
@@ -40,6 +64,12 @@ module Slk
       def unreads?
         unread_count.positive?
       end
+
+      private
+
+      def subscription_params(channel, thread_ts, last_read)
+        { channel: channel, thread_ts: thread_ts, last_read: last_read }
+      end
     end
   end
 end

data/lib/slk/commands/catchup.rb

@@ -90,6 +90,14 @@ module Slk
 
       private
 
+      # Catchup defaults to every workspace, but -w names one: let it win, or
+      # `slk catchup -w oddball` quietly walks (or batch-clears) all of them.
+      def target_workspaces
+        return [runner.workspace(@options[:workspace])] if @options[:workspace]
+
+        super
+      end
+
       def batch_catchup
         target_workspaces.each { |ws| batch_mark_workspace(ws) }
         0

data/lib/slk/commands/debug.rb

@@ -7,6 +7,7 @@ module Slk
     # and field shapes before building higher-level features.
     #
     # Not registered in `slk help`.
+    # rubocop:disable Metrics/ClassLength
     class Debug < Base
       def execute
         result = validate_options
@@ -24,6 +25,7 @@ module Slk
         in ['profile'] then dump_profile(nil)
         in ['team'] then dump_team
         in ['schema'] then dump_schema
+        in ['thread', url] then dump_thread(url)
         else unknown_action
         end
       end
@@ -55,6 +57,40 @@ module Slk
         0
       end
 
+      # Raw shapes behind thread subscriptions: the parent message (does it
+      # carry `subscribed`/`last_read`?) and subscriptions.thread.get. Each call
+      # is captured separately so one failing does not hide the other.
+      def dump_thread(url)
+        resolved = resolve_thread(url)
+        ts = resolved.thread_ts || resolved.msg_ts
+        raise UsageError, 'URL must point to a specific message' unless ts
+
+        output.puts(JSON.pretty_generate(thread_calls(resolved.workspace.name, resolved.channel_id, ts)))
+        0
+      end
+
+      def resolve_thread(url)
+        Services::TargetResolver.new(runner: runner, cache_store: cache_store)
+                                .resolve(url, default_workspace: runner.workspace(@options[:workspace]))
+      end
+
+      def thread_calls(workspace_name, channel, thread_ts)
+        {
+          'conversations.replies' => capture do
+            runner.conversations_api(workspace_name).replies(channel: channel, timestamp: thread_ts, limit: 1)
+          end,
+          'subscriptions.thread.get' => capture do
+            runner.threads_api(workspace_name).get(channel: channel, thread_ts: thread_ts)
+          end
+        }
+      end
+
+      def capture
+        yield
+      rescue ApiError => e
+        { 'ok' => false, 'error' => e.message }
+      end
+
       def resolve_user_id(workspace, user_input)
         return self_user_id(workspace) if user_input.nil? || user_input == 'me'
         return user_input if user_input.match?(/\A[UW][A-Z0-9]+\z/)
@@ -82,7 +118,7 @@ module Slk
 
       def unknown_action
         error("Unknown debug action: #{positional_args.first.inspect}")
-        error('Valid actions: profile [user], team, schema')
+        error('Valid actions: profile [user], team, schema, thread <url>')
         1
       end
 
@@ -98,6 +134,7 @@ module Slk
             profile [user]   Dump users.profile.get + users.info + team.profile.get
             team             Dump team.info
             schema           Dump team.profile.get
+            thread <url>     Dump thread parent + subscriptions.thread.get
 
           USER
             (none) | me      Self
@@ -106,5 +143,6 @@ module Slk
         HELP
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/slk/commands/help.rb

@@ -11,6 +11,7 @@ module Slk
         ['presence', 'Get or set your presence (away/active)'],
         ['dnd', 'Manage Do Not Disturb'],
         ['messages', 'Read channel or DM messages'],
+        ['thread', 'View a thread, or subscribe to it without replying'],
         ['search', 'Search messages across channels'],
         ['sent', 'Show your sent messages across workspaces'],
         ['unread', 'View and clear unread messages'],

data/lib/slk/commands/thread.rb

@@ -4,13 +4,19 @@ require_relative 'messages'
 
 module Slk
   module Commands
-    # Views a message thread from a Slack URL
+    # Views a message thread from a Slack URL, or subscribes to / unsubscribes
+    # from it so new replies surface without posting in the thread
+    # rubocop:disable Metrics/ClassLength
     class Thread < Messages
+      SUBSCRIPTION_ACTIONS = %w[subscribe unsubscribe].freeze
+      # Session-only endpoint: bot/user OAuth tokens get one of these back.
+      TOKEN_ERRORS = %i[not_allowed_token_type unknown_method missing_scope].freeze
+
       def execute
         result = validate_options
         return result if result
 
-        resolve_and_display_thread
+        dispatch
       rescue ApiError => e
         error("Failed to fetch messages: #{e.message}")
         1
@@ -19,6 +25,13 @@ module Slk
         1
       end
 
+      def dispatch
+        action = positional_args.first
+        return change_subscription(action, positional_args[1]) if SUBSCRIPTION_ACTIONS.include?(action)
+
+        resolve_and_display_thread
+      end
+
       def resolve_and_display_thread
         target = positional_args.first
         return usage_error unless target
@@ -30,6 +43,16 @@ module Slk
         fetch_and_display_messages(resolved)
       end
 
+      def change_subscription(action, target)
+        return subscription_usage_error(action) unless target
+        return url_required_error unless Support::SlackUrlParser.new.parse(target)&.message?
+
+        resolved = target_resolver.resolve(target, default_workspace: target_workspaces.first)
+        report_subscription(action, resolved.workspace, apply_subscription(action, resolved))
+      rescue ApiError => e
+        subscription_error(action, e)
+      end
+
       def fetch_and_display_messages(resolved)
         ts = resolved.thread_ts || resolved.msg_ts
         return message_url_required_error unless ts
@@ -46,6 +69,12 @@ module Slk
 
       def usage_error
         error('Usage: slk thread <url>')
+        error('       slk thread subscribe|unsubscribe <url>')
+        1
+      end
+
+      def subscription_usage_error(action)
+        error("Usage: slk thread #{action} <url>")
         1
       end
 
@@ -60,9 +89,11 @@ module Slk
       end
 
       def help_text
-        help = Support::HelpFormatter.new('slk thread <url> [options]')
-        help.description('View a message thread from a Slack URL.')
+        help = Support::HelpFormatter.new('slk thread [subscribe|unsubscribe] <url> [options]')
+        help.description('View a message thread from a Slack URL, or subscribe to it without replying.')
+        help.note('Subscribing marks existing replies read; new replies show up in `slk unread`.')
         add_usage_section(help)
+        add_actions_section(help)
         add_options_section(help)
         add_examples_section(help)
         help.render
@@ -70,10 +101,56 @@ module Slk
 
       private
 
+      def apply_subscription(action, resolved)
+        thread_subscription(resolved.workspace).public_send(
+          action, channel_id: resolved.channel_id, timestamp: resolved.thread_ts || resolved.msg_ts
+        )
+      end
+
+      def thread_subscription(workspace)
+        Services::ThreadSubscription.new(
+          conversations_api: runner.conversations_api(workspace.name),
+          threads_api: runner.threads_api(workspace.name)
+        )
+      end
+
+      def report_subscription(action, workspace, result)
+        if @options[:json]
+          output_json(subscription_json(action, workspace, result))
+        else
+          verb = action == 'subscribe' ? 'Subscribed to' : 'Unsubscribed from'
+          success("#{verb} thread #{result.thread_ts} in #{channel_label(workspace, result.channel_id)}")
+        end
+        0
+      end
+
+      def subscription_json(action, workspace, result)
+        { subscribed: action == 'subscribe', workspace: workspace.name, channel_id: result.channel_id,
+          thread_ts: result.thread_ts, last_read: result.last_read }
+      end
+
+      def channel_label(workspace, channel_id)
+        name = cache_store.get_channel_name(workspace.name, channel_id)
+        name ? "##{name}" : channel_id
+      end
+
+      def subscription_error(action, err)
+        error("Failed to #{action} #{action == 'subscribe' ? 'to' : 'from'} thread: #{err.message}")
+        error('Thread subscriptions require a session (xoxc) token.') if TOKEN_ERRORS.include?(err.code)
+        1
+      end
+
       def add_usage_section(help)
         help.section('USAGE') { |s| s.item('<slack_url>', 'Slack message URL') }
       end
 
+      def add_actions_section(help)
+        help.section('ACTIONS') do |s|
+          s.action('subscribe <url>', 'Follow the thread (get notified of new replies)')
+          s.action('unsubscribe <url>', 'Stop following the thread')
+        end
+      end
+
       def add_options_section(help)
         help.section('OPTIONS') do |s|
           s.option('--no-emoji', 'Show :emoji: codes instead of unicode')
@@ -88,8 +165,11 @@ module Slk
       def add_examples_section(help)
         help.section('EXAMPLES') do |s|
           s.item('slk thread https://work.slack.com/archives/C123/p1234567890', 'View thread')
+          s.item('slk thread subscribe https://work.slack.com/archives/C123/p1234567890', 'Follow thread')
+          s.item('slk thread unsubscribe https://work.slack.com/archives/C123/p1234567890', 'Unfollow thread')
         end
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/slk/commands/unread.rb

@@ -95,22 +95,38 @@ module Slk
 
       private
 
-      def show_unread
-        target_workspaces.each do |workspace|
-          puts output.bold(workspace.name) if @options[:all] || target_workspaces.size > 1
+      # Unread defaults to every workspace, but -w names one: let it win, or
+      # `slk unread -w oddball` quietly reports on all of them.
+      def target_workspaces
+        return [runner.workspace(@options[:workspace])] if @options[:workspace]
 
-          unread_data = fetch_unread_data(workspace)
+        super
+      end
 
-          if @options[:json]
-            output_unread_json(workspace, unread_data)
-          else
-            display_unread(workspace, unread_data)
-          end
+      def show_unread
+        return show_unread_json if @options[:json]
+
+        workspaces = target_workspaces
+        workspaces.each do |workspace|
+          puts output.bold(workspace.name) if workspaces.size > 1
+          display_unread(workspace, fetch_unread_data(workspace))
         end
 
         0
       end
 
+      # Exactly one JSON document: one workspace prints its {channels, dms}
+      # alone; several are keyed by workspace name. No name headers, so the
+      # output pipes straight into jq.
+      def show_unread_json
+        workspaces = target_workspaces
+        documents = workspaces.to_h do |workspace|
+          [workspace.name, unread_json(workspace, fetch_unread_data(workspace))]
+        end
+        output_json(workspaces.size == 1 ? documents.values.first : documents)
+        0
+      end
+
       def fetch_unread_data(workspace)
         counts = runner.client_api(workspace.name).counts
         muted_ids = fetch_muted_ids(workspace)
@@ -135,11 +151,11 @@ module Slk
           .reject { |c| muted_ids.include?(c['id']) }
       end
 
-      def output_unread_json(workspace, data)
-        output_json({
-                      channels: data[:unread_channels].map { |c| format_channel_json(workspace, c) },
-                      dms: data[:unread_ims].map { |i| format_dm_json(workspace, i) }
-                    })
+      def unread_json(workspace, data)
+        {
+          channels: data[:unread_channels].map { |c| format_channel_json(workspace, c) },
+          dms: data[:unread_ims].map { |i| format_dm_json(workspace, i) }
+        }
       end
 
       def format_channel_json(workspace, channel)

data/lib/slk/services/thread_subscription.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Subscribes to or unsubscribes from a thread without posting in it.
+    #
+    # Slack wants the thread's parent timestamp plus a last-read marker. A
+    # permalink can point at any reply, so the parent is looked up first and
+    # its latest reply becomes the marker: what is already there counts as
+    # read, and only replies posted after subscribing show up as unread.
+    class ThreadSubscription
+      Result = Data.define(:channel_id, :thread_ts, :last_read)
+
+      def initialize(conversations_api:, threads_api:)
+        @conversations = conversations_api
+        @threads = threads_api
+      end
+
+      # @param channel_id [String] Channel ID
+      # @param timestamp [String] Timestamp of the parent or any reply
+      # @return [Result]
+      def subscribe(channel_id:, timestamp:)
+        change(:subscribe, channel_id, timestamp)
+      end
+
+      # @param channel_id [String] Channel ID
+      # @param timestamp [String] Timestamp of the parent or any reply
+      # @return [Result]
+      def unsubscribe(channel_id:, timestamp:)
+        change(:unsubscribe, channel_id, timestamp)
+      end
+
+      private
+
+      def change(action, channel_id, timestamp)
+        result = locate(channel_id, timestamp)
+        @threads.public_send(action, channel: channel_id, thread_ts: result.thread_ts, last_read: result.last_read)
+        result
+      end
+
+      def locate(channel_id, timestamp)
+        message = first_message(channel_id, timestamp)
+        thread_ts = message['thread_ts'] || message['ts'] || timestamp
+        # Pointed at a reply: only the parent carries latest_reply.
+        message = first_message(channel_id, thread_ts) if message['ts'] && message['ts'] != thread_ts
+
+        Result.new(channel_id: channel_id, thread_ts: thread_ts, last_read: message['latest_reply'] || thread_ts)
+      end
+
+      def first_message(channel_id, timestamp)
+        response = @conversations.replies(channel: channel_id, timestamp: timestamp, limit: 1)
+        message = (response['messages'] || []).first
+        raise ApiError.new('thread_not_found', code: :thread_not_found) unless message
+
+        message
+      end
+    end
+  end
+end

data/lib/slk/version.rb

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

data/lib/slk.rb

@@ -117,6 +117,7 @@ module Slk
     autoload :SentConversations, 'slk/services/sent_conversations'
     autoload :SentChanges, 'slk/services/sent_changes'
     autoload :SentChannelLabel, 'slk/services/sent_channel_label'
+    autoload :ThreadSubscription, 'slk/services/thread_subscription'
   end
 
   # Output formatters for messages, durations, and emoji

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slk
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.1
 platform: ruby
 authors:
 - Eric Boehs
@@ -127,6 +127,7 @@ files:
 - lib/slk/services/start_date_field.rb
 - lib/slk/services/start_date_lookup.rb
 - lib/slk/services/target_resolver.rb
+- lib/slk/services/thread_subscription.rb
 - lib/slk/services/token_loader.rb
 - lib/slk/services/token_saver.rb
 - lib/slk/services/token_store.rb