slack_line 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63f2270ed13b9bf4d14585497109923c70b8e7ec8a34af3ebb46306afdfaf703
-  data.tar.gz: 677793b2b72ef6f1d58673b9c658151b3b22504e85cb34678d6e0973d23f00a6
+  metadata.gz: bc23e7f575bc68df1c9824aacbde9b74050c14f82f765fc6929dc33ae909eccb
+  data.tar.gz: 45e54647313e4c71a27de6c8bda77826deaf7704ac8a5680c1439c5015f9b50e
 SHA512:
-  metadata.gz: 939add34dd7ecd05b44828f53bfd20d62b4c0df9a4deb2b2b2097f736b6a3666173f098e81451416865c0ff66765320b2bff16c8558230eb445a54a3673e9be1
-  data.tar.gz: 9dc08564bfb998fe4abe612f546a4f9327924ea70e01a153d5daaa751baae3698296b14cb13bc7c50ff612e31f9f1f54dcf6086a74bd5579a17257307027f2d6
+  metadata.gz: 5c9d9e4c86c4ae41adac7a71a1044fe02aef53eaa823bc286862178b9fce6de8716d51a7833ed6ee118a550e29726358dd7b2a54df3bc78526074be65a125af4
+  data.tar.gz: fc217ed772fbbcbf1a27aa0911d24f2ef716c4b6ffed127f2c0959329b5358e510654a4d313c9d42e8a0168a7b88fe3c5d253d46545775175bd3671c3e593a65

data/Gemfile

@@ -1,3 +1,5 @@
 source "https://gem.coop"
 
 gemspec
+
+gem "lightly"

data/README.md

@@ -80,6 +80,18 @@ be set via ENV or `SlackLine.configure`:
 * `per_thread_delay` or `SLACK_LINE_PER_THREAD_DELAY` is a float as
   well - SlackLine will `sleep` for this duration after each _thread_
   is posted, and after each non-thread message is posted.
+* `cache_path` or `SLACK_LINE_CACHE_PATH` - a directory path for
+  disk-caching the users and groups lists fetched from the Slack API.
+  When set, SlackLine will use the [lightly](https://github.com/DannyBen/lightly)
+  gem to cache results to disk, which avoids redundant API calls across
+  separate runs. Requires `lightly` to be installed as an optional
+  dependency - if it is not available, a `DiskCaching::NoLightly` error
+  will be raised at runtime.
+* `cache_duration` or `SLACK_LINE_CACHE_DURATION` - how long cached
+  data remains valid (default `"15m"`). Accepts a plain integer number
+  of seconds, or a number followed by a unit suffix: `s` (seconds),
+  `m` (minutes), `h` (hours), or `d` (days). For example: `"30m"`,
+  `"2h"`, `"1d"`, or `"900"`.
 
 You can just set those via the environment variables, but you can also
 set them on the singleton configuration object:
@@ -92,10 +104,12 @@ SlackLine.configure do |config|
   config.default_channel = "#ci-flow"
   config.per_message_delay = 0.2
   config.per_thread_delay = 2.0
+  config.cache_path = "/tmp/slack_line_cache"
+  config.cache_duration = "1h"
 end
 ```
 
-## Multiple Configurations
+### Multiple Configurations
 
 If you're working in a context where you need to support multiple
 SlackLine configurations, don't worry! The singleton central config is
@@ -122,6 +136,126 @@ BAR_SLACK.thread("Message 1", "Message 2").post
 BAR_SLACK.message("Message 3", to: "#bar-team-3").post
 ```
 
+## CLI Scripts
+
+The gem ships with three executable scripts for sending and managing Slack messages
+from the command line. All three accept `-t`/`--slack-token TOKEN` and
+`-n`/`--bot-name NAME` to override the corresponding environment variables.
+Configuration can also come from `SLACK_LINE_SLACK_TOKEN` and friends as described
+above.
+
+### `slack_line_message`
+
+Sends, updates, or previews a single Slack message.
+
+```sh
+# Post a simple message
+slack_line_message --post-to "#general" --save /tmp/msg.json "Something happened!"
+
+# Preview without posting (prints JSON block kit content)
+slack_line_message "Something happened!"
+
+# Post a message using the block-kit DSL on stdin
+echo 'text "Something happened!"' | slack_line_message --post-to "#general" --save /tmp/msg.json
+
+# Append a reply to an existing thread (saved from a prior post)
+slack_line_message --append /tmp/msg.json --save /tmp/msg.json "Follow-up!"
+
+# Update a previously-sent message in place
+slack_line_message --update /tmp/msg.json "Edited message text"
+
+# Update a specific message within a saved thread (0-indexed)
+slack_line_message --update /tmp/msg.json --message-number 2 "Corrected reply"
+```
+
+Options:
+
+* `-p`/`--post-to TARGET` - channel or user to post to
+* `-a`/`--append PATH` - append a reply to the thread saved at PATH
+* `-U`/`--update PATH` - update the message (or thread) saved at PATH
+* `-m`/`--message-number N` - which message in a thread to update (0-indexed;
+  required with `--update` on a thread)
+* `-s`/`--save PATH` - write the sent/updated result to PATH as JSON
+* `-u`/`--look-up-users` - resolve `@mentions` via the Slack API
+* `--cache-path PATH` / `--cache-duration DURATION` - disk-cache user/group lookups
+* `--no-backoff` - disable per-message sleep delays
+
+When no content arguments are given and no DSL is piped, the script reads DSL
+interactively from stdin.
+
+### `slack_line_thread`
+
+Sends or previews a thread (multiple messages posted together).
+
+```sh
+# Post a thread from positional string arguments
+slack_line_thread --post-to "#general" --save /tmp/thread.json "First" "Second" "Third"
+
+# Preview the thread without posting
+slack_line_thread "First" "Second"
+
+# Post a thread from block-kit DSL on stdin
+cat thread.dsl | slack_line_thread --post-to "#general" --save /tmp/thread.json
+```
+
+A DSL block looks like:
+
+```ruby
+message "Simple first message"
+message do
+  text "Fancier second message"
+  context "with some context"
+end
+```
+
+Options mirror `slack_line_message`, minus the update/append flags:
+
+* `-p`/`--post-to TARGET` - channel or user to post to
+* `-s`/`--save PATH` - write the sent result to PATH as JSON
+* `-u`/`--look-up-users`, `--cache-path`, `--cache-duration`, `--no-backoff` -
+  same as above
+
+### `slack_line_stateful_thread`
+
+Designed for long-running processes that need to post a single status message
+and then keep it updated as state changes - for example, a deployment pipeline
+that posts `[running] Deploy started`, updates it to `[done] Deploy finished`,
+and appends replies along the way. The sent message is persisted to a file;
+subsequent invocations load and re-persist that file to know which Slack message
+to update.
+
+Messages are formatted as `[STATE] body`. The `--state` and `--message` flags each
+update their respective part independently; omitting one leaves it unchanged on update.
+
+```sh
+# Initial post - creates /tmp/deploy.json and posts "[running] Deploy started"
+slack_line_stateful_thread --path /tmp/deploy.json --post-to "#deploys" \
+  --state running --message "Deploy started"
+
+# Update the state only - becomes "[done] Deploy started"
+slack_line_stateful_thread --path /tmp/deploy.json --state done
+
+# Update the body only - becomes "[done] Deploy finished"
+slack_line_stateful_thread --path /tmp/deploy.json --message "Deploy finished"
+
+# Update both state and body - becomes "[failed] Something went wrong"
+slack_line_stateful_thread --path /tmp/deploy.json --state failed --message "Something went wrong"
+
+# Append a thread reply without changing the main message
+slack_line_stateful_thread --path /tmp/deploy.json --thread --message "Step 1 complete"
+```
+
+Options:
+
+* `--path PATH` - (required) file path used to persist the sent message between invocations
+* `-p`/`--post-to TARGET` - channel or user; required on the first call, forbidden
+  thereafter
+* `-s`/`--state STATE` - the state label shown in brackets; required on first call
+* `-m`/`--message MESSAGE` - the message body; required on first call and when using
+  `--thread`
+* `--thread` - append a reply instead of updating the main message (mutually exclusive
+  with `--state`)
+
 ## Slack App Permissions
 
 In order to post/update messages, the app behind your `SLACK_LINE_TOKEN` can use

data/bin/slack_line_stateful_thread

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/slack_line"
+
+begin
+  SlackLine::Cli::SlackLineStatefulThread.new(argv: ARGV).run
+rescue SlackLine::Cli::ExitException => e
+  abort e.message
+end

data/lib/slack_line/cli/slack_line_message.rb

@@ -20,11 +20,13 @@ module SlackLine
         else
           run_preview
         end
+      rescue DiskCaching::NoLightly, Configuration::InvalidValue => e
+        raise ExitException, e.message
       end
 
       def options
         return @options if defined?(@options)
-        opts = {post_to: nil, append: nil, update: nil, message_number: nil, save: nil, slack_token: nil, look_up_users: nil, bot_name: nil, backoff: nil}
+        opts = {post_to: nil, append: nil, update: nil, message_number: nil, save: nil, slack_token: nil, look_up_users: nil, bot_name: nil, backoff: nil, cache_path: nil, cache_duration: nil}
         remaining = option_parser(opts).parse(@argv.dup)
         if remaining.empty?
           opts[:dsl] = read_stdin
@@ -37,7 +39,7 @@ module SlackLine
 
       def configuration
         return @configuration if defined?(@configuration)
-        cfg_opts = options.slice(:slack_token, :look_up_users, :bot_name, :backoff).compact
+        cfg_opts = options.slice(:slack_token, :look_up_users, :bot_name, :backoff, :cache_path, :cache_duration).compact
         @configuration = Configuration.new(nil, **cfg_opts)
       end
 
@@ -56,6 +58,8 @@ module SlackLine
           parser.on("-m", "--message-number N", Integer) { |n| opts[:message_number] = n }
           parser.on("-s", "--save PATH") { |p| opts[:save] = p }
           parser.on("--no-backoff") { opts[:backoff] = false }
+          parser.on("--cache-path PATH") { |p| opts[:cache_path] = p }
+          parser.on("--cache-duration DURATION") { |d| opts[:cache_duration] = d }
         end
       end
 

data/lib/slack_line/cli/slack_line_stateful_thread.rb

@@ -0,0 +1,126 @@
+require "optparse"
+
+module SlackLine
+  module Cli
+    class SlackLineStatefulThread
+      def initialize(argv:, stdout: $stdout, stderr: $stderr)
+        @argv = argv
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run
+        validate_options!
+        if path_exists?
+          run_subsequent
+        else
+          run_initial
+        end
+      rescue DiskCaching::NoLightly, Configuration::InvalidValue => e
+        raise ExitException, e.message
+      end
+
+      def options
+        return @options if defined?(@options)
+        opts = {path: nil, post_to: nil, state: nil, message: nil, thread: nil, slack_token: nil, bot_name: nil}
+        option_parser(opts).parse(@argv.dup)
+        @options = opts
+      end
+
+      def configuration
+        return @configuration if defined?(@configuration)
+        cfg_opts = options.slice(:slack_token, :bot_name).compact
+        @configuration = Configuration.new(nil, **cfg_opts)
+      end
+
+      private
+
+      attr_reader :stdout, :stderr
+
+      def option_parser(opts) # rubocop:disable Metrics/AbcSize
+        OptionParser.new do |parser|
+          parser.on("-t", "--slack-token TOKEN") { |t| opts[:slack_token] = t }
+          parser.on("-n", "--bot-name NAME") { |n| opts[:bot_name] = n }
+          parser.on("--path PATH") { |p| opts[:path] = p }
+          parser.on("-p", "--post-to TARGET") { |t| opts[:post_to] = t }
+          parser.on("-s", "--state STATE") { |s| opts[:state] = s }
+          parser.on("-m", "--message MESSAGE") { |m| opts[:message] = m }
+          parser.on("--thread") { opts[:thread] = true }
+        end
+      end
+
+      def validate_options!
+        raise ExitException, "--path is required" unless options[:path]
+        path_exists? ? validate_subsequent_options! : validate_initial_options!
+      end
+
+      def validate_initial_options!
+        raise ExitException, "--thread cannot be used on initial post" if options[:thread]
+        raise ExitException, "--post-to is required for initial post" unless options[:post_to]
+        raise ExitException, "--state is required for initial post" unless options[:state]
+        raise ExitException, "--message is required for initial post" unless options[:message]
+      end
+
+      def validate_subsequent_options!
+        raise ExitException, "--post-to cannot be used after initial post" if options[:post_to]
+        options[:thread] ? validate_thread_options! : validate_update_options!
+      end
+
+      def validate_thread_options!
+        raise ExitException, "--thread cannot be used with --state" if options[:state]
+        raise ExitException, "--thread requires --message" unless options[:message]
+      end
+
+      def validate_update_options!
+        raise ExitException, "One of --state or --message is required" unless options[:state] || options[:message]
+      end
+
+      def path_exists? = options[:path] && File.exist?(options[:path])
+
+      def client = @client ||= Client.new(configuration)
+
+      def load_sent
+        @load_sent ||= SlackLine.from_json(JSON.parse(File.read(options[:path])), client:)
+      end
+
+      def save_sent(result) = File.write(options[:path], JSON.pretty_generate(result.as_json))
+
+      def run_initial
+        text = "[#{options[:state]}] #{options[:message]}"
+        sent = Message.new(text, client:).post(to: options[:post_to])
+        save_sent(sent)
+        stderr.puts "Posted stateful thread to #{options[:post_to]}"
+      end
+
+      def run_subsequent
+        options[:thread] ? run_thread_message : run_update_message
+      end
+
+      def parse_state_message(text)
+        match = text&.match(/\A\[([^\]]*)\] (.+)\z/m)
+        raise ExitException, "Cannot parse state and body from stored message content" unless match
+        [match[1], match[2]]
+      end
+
+      def current_state_and_body(sent)
+        parse_state_message(sent.content.dig(0, "text", "text"))
+      end
+
+      def run_update_message
+        sent = load_sent
+        current_state, current_body = current_state_and_body(sent)
+        new_text = "[#{options[:state] || current_state}] #{options[:message] || current_body}"
+        updated = sent.update(Message.new(new_text, client:))
+        save_sent(updated)
+        stderr.puts "Updated message in #{updated.channel}"
+      end
+
+      def run_thread_message
+        sent = load_sent
+        sent_thread = sent.append(options[:message])
+        save_sent(sent_thread)
+        stderr.puts "Threaded message in #{sent_thread.channel}"
+      end
+    end
+  end
+end

data/lib/slack_line/cli/slack_line_thread.rb

@@ -16,11 +16,13 @@ module SlackLine
         else
           run_preview
         end
+      rescue DiskCaching::NoLightly, Configuration::InvalidValue => e
+        raise ExitException, e.message
       end
 
       def options
         return @options if defined?(@options)
-        opts = {post_to: nil, save: nil, slack_token: nil, look_up_users: nil, bot_name: nil, backoff: nil}
+        opts = {post_to: nil, save: nil, slack_token: nil, look_up_users: nil, bot_name: nil, backoff: nil, cache_path: nil, cache_duration: nil}
         remaining = option_parser(opts).parse(@argv.dup)
         if remaining.empty?
           opts[:dsl] = read_stdin
@@ -32,7 +34,7 @@ module SlackLine
 
       def configuration
         return @configuration if defined?(@configuration)
-        cfg_opts = options.slice(:slack_token, :look_up_users, :bot_name, :backoff).compact
+        cfg_opts = options.slice(:slack_token, :look_up_users, :bot_name, :backoff, :cache_path, :cache_duration).compact
         @configuration = Configuration.new(nil, **cfg_opts)
       end
 
@@ -48,6 +50,8 @@ module SlackLine
           parser.on("-p", "--post-to TARGET") { |t| opts[:post_to] = t }
           parser.on("-s", "--save PATH") { |p| opts[:save] = p }
           parser.on("--no-backoff") { opts[:backoff] = false }
+          parser.on("--cache-path PATH") { |p| opts[:cache_path] = p }
+          parser.on("--cache-duration DURATION") { |d| opts[:cache_duration] = d }
         end
       end
 

data/lib/slack_line/client.rb

@@ -16,8 +16,8 @@ module SlackLine
 
     def thread(*messages, &dsl_block) = Thread.new(*messages, client: self, &dsl_block)
 
-    memoize def users = Users.new(slack_client:)
+    memoize def users = Users.new(client: self)
 
-    memoize def groups = Groups.new(slack_client:)
+    memoize def groups = Groups.new(client: self)
   end
 end

data/lib/slack_line/configuration.rb

@@ -1,12 +1,19 @@
 module SlackLine
   class Configuration
+    include Memoization
+
+    InvalidValue = Class.new(Error)
+
     attr_accessor :slack_token,
       :look_up_users, :bot_name, :default_channel,
       :per_message_delay, :per_thread_delay,
-      :backoff
+      :backoff, :cache_path
+    attr_writer :cache_duration
 
     alias_method :look_up_users?, :look_up_users
 
+    memoize def cache_duration = parse_duration(@cache_duration.to_s)
+
     DEFAULTS = {
       slack_token: nil,
       look_up_users: false,
@@ -14,7 +21,9 @@ module SlackLine
       default_channel: nil,
       per_message_delay: 0.0,
       per_thread_delay: 0.0,
-      backoff: true
+      backoff: true,
+      cache_path: nil,
+      cache_duration: "15m"
     }.freeze
 
     def initialize(base_config = nil, **overrides)
@@ -28,6 +37,8 @@ module SlackLine
       @per_message_delay = cascade(:per_message_delay, "SLACK_LINE_PER_MESSAGE_DELAY", :float)
       @per_thread_delay = cascade(:per_thread_delay, "SLACK_LINE_PER_THREAD_DELAY", :float)
       @backoff = cascade(:backoff, "SLACK_LINE_NO_BACKOFF", :inverse_boolean)
+      @cache_path = cascade(:cache_path, "SLACK_LINE_CACHE_PATH", :string)
+      @cache_duration = cascade(:cache_duration, "SLACK_LINE_CACHE_DURATION", :string)
     end
 
     private
@@ -57,5 +68,15 @@ module SlackLine
         value
       end
     end
+
+    DURATION_MULTIPLIERS = {s: 1, m: 60, h: 3600, d: 86400}.freeze
+
+    def parse_duration(value)
+      match = value.match(/\A(\d+)([smhd])?\z/)
+      raise(InvalidValue, "Invalid duration: #{value.inspect}") unless match
+
+      digits, unit = match.captures
+      digits.to_i * DURATION_MULTIPLIERS.fetch(unit&.to_sym, 1)
+    end
   end
 end

data/lib/slack_line/disk_caching.rb

@@ -0,0 +1,18 @@
+begin
+  require "lightly"
+rescue LoadError
+  # optional dependency
+end
+
+module SlackLine
+  module DiskCaching
+    NoLightly = Class.new(Error)
+
+    def cached(config:, key:, &block)
+      return yield if config.cache_path.nil?
+      raise(NoLightly, "The 'lightly' gem is required for disk caching") unless defined?(Lightly)
+
+      Lightly.new(dir: config.cache_path, life: config.cache_duration).get(key) { yield }
+    end
+  end
+end

data/lib/slack_line/groups.rb

@@ -1,12 +1,15 @@
 module SlackLine
   class Groups
     include Memoization
+    include DiskCaching
 
-    def initialize(slack_client:)
-      @slack_client = slack_client
+    def initialize(client:)
+      @client = client
     end
 
-    memoize def all = fetch_groups
+    memoize def all
+      cached(config: client.configuration, key: "groups_all") { fetch_groups }
+    end
 
     def find(handle:)
       groups_by_handle[handle.downcase]
@@ -14,7 +17,9 @@ module SlackLine
 
     private
 
-    attr_reader :slack_client
+    attr_reader :client
+
+    def slack_client = client.slack_client
 
     memoize def fetch_groups
       slack_client.usergroups_list.usergroups || []

data/lib/slack_line/sent_thread.rb

@@ -10,9 +10,14 @@ module SlackLine
     attr_reader :sent_messages
     alias_method :messages, :sent_messages
     def_delegators :sent_messages, :each, :map, :size, :first, :last, :empty?
-    def_delegators :first, :channel, :ts
+    def_delegators :first, :channel, :ts, :content
     alias_method :thread_ts, :ts
 
+    def update(*text_or_blocks, &dsl_block)
+      updated_root = first.update(*text_or_blocks, &dsl_block)
+      SentThread.new(updated_root, *sent_messages[1..])
+    end
+
     def append(*text_or_blocks, &dsl_block)
       extended = first.append(*text_or_blocks, &dsl_block)
       SentThread.new(*sent_messages, *extended.sent_messages[1..])

data/lib/slack_line/users.rb

@@ -1,12 +1,15 @@
 module SlackLine
   class Users
     include Memoization
+    include DiskCaching
 
-    def initialize(slack_client:)
-      @slack_client = slack_client
+    def initialize(client:)
+      @client = client
     end
 
-    memoize def all = all_users.reject(&:deleted).reject(&:is_bot)
+    memoize def all
+      cached(config: client.configuration, key: "users_all") { all_users.reject(&:deleted).reject(&:is_bot) }
+    end
 
     def find(display_name:)
       users_by_display_name[display_name.downcase]
@@ -14,7 +17,9 @@ module SlackLine
 
     private
 
-    attr_reader :slack_client
+    attr_reader :client
+
+    def slack_client = client.slack_client
 
     def fetch_page(cursor: nil)
       params = {limit: 200}

data/lib/slack_line/version.rb

@@ -1,3 +1,3 @@
 module SlackLine
-  VERSION = "1.1".freeze
+  VERSION = "1.2".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_line
 version: !ruby/object:Gem::Version
-  version: '1.1'
+  version: '1.2'
 platform: ruby
 authors:
 - Eric Mueller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-02 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -173,6 +173,7 @@ email:
 - nevinera@gmail.com
 executables:
 - slack_line_message
+- slack_line_stateful_thread
 - slack_line_thread
 extensions: []
 extra_rdoc_files: []
@@ -190,13 +191,16 @@ files:
 - Gemfile
 - README.md
 - bin/slack_line_message
+- bin/slack_line_stateful_thread
 - bin/slack_line_thread
 - lib/slack_line.rb
 - lib/slack_line/cli.rb
 - lib/slack_line/cli/slack_line_message.rb
+- lib/slack_line/cli/slack_line_stateful_thread.rb
 - lib/slack_line/cli/slack_line_thread.rb
 - lib/slack_line/client.rb
 - lib/slack_line/configuration.rb
+- lib/slack_line/disk_caching.rb
 - lib/slack_line/groups.rb
 - lib/slack_line/memoization.rb
 - lib/slack_line/message.rb