standup_md 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2734d31b2ce72d31aceeb789f562b015c4f0e7422b3a755992df7c1f293a7051
-  data.tar.gz: 651d1f6f9a613366b90e2b26ba83b8e05dd80dbc5d8bde3a0fcc7d07b57acef1
+  metadata.gz: 47c9542a3be072fc9067823aeeaf6c41741e657f7c628476cf1811c3699978f0
+  data.tar.gz: 165f18178d4e7038f2c2511e0b7e0e907671c6819f9158fc601c29ebd18ac3be
 SHA512:
-  metadata.gz: 5df3037a20d107f82cc34533f89ab8c31a2ba13eb8180b5931b052c500c5c1f7c4922d22ffed254c5fb9e9d7623b5bb207ed5d5c0c22773bcc972a91bba061d4
-  data.tar.gz: c99e5cf930d4dcf84e6089d458321b00f427ab0c124ecf3b02b8e98d79ba416d5c629793f6f77a8cf1a0337b05ed620600833f1ad8fa2775d7e6eb7205ec22ed
+  metadata.gz: e56ad3a3e3e633f235af7078708ebb27f1a184cd6a0bd94a1b52299e82de2b75842f169e9495003f26c49907a9f0eb9b5c8d52511bf6cc39e1978f60848a2ca8
+  data.tar.gz: 043a1a0119e0921196840fae06143f33a87dbbe4e9b62c381c671defd1695c6e1d5694174872a15932b63c42119dd19764cff992cd3c0f456220f0c9474d15d6

data/.github/workflows/ruby.yml

@@ -10,6 +10,8 @@ on:
 jobs:
   test:
     runs-on: ubuntu-22.04
+    env:
+      BUNDLER_VERSION: 4.0.10
 
     strategy:
       fail-fast: false
@@ -17,14 +19,13 @@ jobs:
         ruby-version: ['3.2', '3.3', '4.0']
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      # Set up Ruby and Bundler
       - name: Set up Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby-version }}
-          bundler: ${{ matrix.ruby-version == '4.0' && '4.0.9' || '2.4.13' }}
+          bundler: ${{ env.BUNDLER_VERSION }}
           bundler-cache: true
 
       - name: Print Ruby and Bundler versions
@@ -32,8 +33,5 @@ jobs:
           ruby -v
           bundle -v
 
-      - name: Install dependencies
-        run: bundle install --jobs 4 --retry 3
-
       - name: Run tests
         run: bundle exec rake

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    standup_md (1.0.0)
+    standup_md (2.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -115,7 +115,7 @@ CHECKSUMS
   standard (1.54.0) sha256=7a4b08f83d9893083c8f03bc486f0feeb6a84d48233b40829c03ef4767ea0100
   standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
   standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
-  standup_md (1.0.0)
+  standup_md (2.0.0)
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   test-unit (3.7.8) sha256=689d1ca53f4d46f678b4e5d68d8e4294f87fc5e8b9238cc4de7c5727e8d65943
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f

data/README.md

@@ -1,7 +1,8 @@
 # The Standup Doctor
 <!-- vi: set ts=4 sw=4 : -->
 [![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fevanthegrayt%2Fstandup_md%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/evanthegrayt/standup_md/goto?ref=master)
-[![Gem Version](https://badge.fury.io/rb/standup_md.svg)](https://badge.fury.io/rb/standup_md)
+[![Gem Version](https://img.shields.io/gem/v/standup_md.svg)](https://rubygems.org/gems/standup_md)
+![Language: Ruby](https://img.shields.io/static/v1?label=language&message=Ruby&color=CC342D&style=flat&logo=ruby&logoColor=CC342D)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > The cure for all your standup woes.
@@ -13,8 +14,8 @@ You can view the documentation
 [here](https://evanthegrayt.github.io/standup_md/).
 
 ## About
-I've now been at two separate companies where we post our daily standups in a
-chat client, such as Slack, Mattermost, or Riot. Typing out my standup every day
+I've now been at multiple companies where we post our daily standups in a chat
+client, such as Slack, Mattermost, or Riot. Typing out my standup every day
 became tedious, as I'd have to look up what I did the day before, copy and paste
 yesterday's work into a new entry, and add today's tasks. This gem automates
 most of this process, along with providing means of opening the file in your
@@ -29,7 +30,9 @@ entry exists, it will be added to today's entry as your previous day's work. See
 this in your own code somehow.
 
 ## Installation
-If you don't have the permissions to install system-wide gems, you're probabaly
+Requires Ruby 3.2 or newer.
+
+If you don't have the permissions to install system-wide gems, you're probably
 also running an older version of ruby. I recommend installing
 [rbenv](https://github.com/rbenv/rbenv#installation), and then installing an
 up-to-date version of ruby.
@@ -131,6 +134,28 @@ your clipboard without even opening your editor.
 standup -p | pbcopy
 ```
 
+#### Post the entry for today to Slack
+You can also post today's entry directly to a chat client. Slack is the default
+adapter, so `standup -P` and `standup -P slack` are equivalent. Tokens are read
+from environment variables at post time, and are not stored in `~/.standuprc`.
+You can set a default channel via the
+[config](#available-config-file-options-and-defaults) via
+`c.post.configure_adapter(:slack, channel: "C123456")`.
+
+```sh
+export STANDUP_MD_SLACK_TOKEN="xoxb-your-token"
+standup -P slack --post-channel C123456
+```
+
+The same posting path is available from Ruby:
+
+```ruby
+file = StandupMD::File.find_by_date(Date.today).load
+entry = file.entries.find(Date.today)
+
+StandupMD::Post.post(entry, adapter: :slack, channel: "C123456")
+```
+
 #### Add entry to file without opening it
 You can add an entry for today without even opening your editor. Note that, if
 you have multiple entries, you must separate them with a comma and *no spaces*.
@@ -141,26 +166,17 @@ standup --no-edit --current "Work on this thing","And another thing"
 
 ### Customization and Runtime Options
 You can create a file in your home directory called `~/.standuprc`. Settings
-located in this file will override default behavior. This file can also have
-settings overwritten at runtime by the use of options. You can view [my config
-file](https://github.com/evanthegrayt/dotfiles/blob/master/dotfiles/standuprc)
-as an example. Any setting in this file can still be overridden at runtime by
-passing flags to the executable.
+located in this file define your application defaults. CLI flags can override
+those defaults for a single invocation, but they do not persist back into
+`StandupMD.config` or `~/.standuprc`. You can view
+[my config file](https://github.com/evanthegrayt/dotfiles/blob/master/dotfiles/standuprc)
+as an example.
 
 You'll notice, a lot of settings don't have the ability to be changed at runtime
-when calling the executable. This is because the file structure is very
+when calling the executable. This is because the markdown structure is very
 important, and changing values that affect formatting will cause problems with
-the file parser. If you don't want to use a default, make the change in your
-config file before you start editing standups. There is an [open
-issue](https://github.com/evanthegrayt/standup_md/issues/16) for handling this
-for the user, but they're not available yet.
-
-There are no options to change the headers at runtime because it uses the
-headers to detect tasks from previous entries. If changed at runtime, this would
-cause errors. For this reason, if you don't like the default headers, change
-them in your configuration file after installation, and then try to not change
-them again.
-
+the markdown parser. If you don't want to use a default, make the change in
+your config file before you start editing standups.
 
 #### Available Config File Options and Defaults
 For command-line usage, this file needs to be named `~/.standuprc`. To use in a
@@ -169,7 +185,7 @@ rails project, create an initializer (`config/initializers/standup_md.rb`).
 ```ruby
 StandupMD.configure do |c|
   # Defaults for how the file is formatted.
-  # See https://evanthegrayt.github.io/standup_md/doc/StandupMD/Config/Cli.html
+  # See https://evanthegrayt.github.io/standup_md/doc/StandupMD/Config/File.html
   c.file.header_date_format = "%Y-%m-%d"
   c.file.header_depth       = 1
   c.file.sub_header_depth   = 2
@@ -199,38 +215,143 @@ StandupMD.configure do |c|
   c.cli.edit               = true
   c.cli.write              = true
   c.cli.print              = false
+  c.cli.post               = false
+  c.cli.post_adapter       = nil
+  c.cli.post_channel       = nil
   c.cli.auto_fill_previous = true
   c.cli.preference_file    = ::File.expand_path(::File.join(ENV["HOME"], ".standuprc"))
+
+  # Defaults for posting standups to chat clients.
+  c.post.default_adapter = :slack
+  c.post.title           = nil
+  c.post.configure_adapter(
+    :slack,
+    channel: "C123456",
+    token_env: "STANDUP_MD_SLACK_TOKEN"
+  )
 end
 ```
 
 Any options not set in this file will retain their default values. Note that if
-you change `file_name_format`, and don't use a month or year, there will only
+you change `name_format`, and don't use a month or year, there will only
 ever be one standup file. This could cause issues long-term, as the files will
 get large over time and possibly cause performance issues.
 
 
 #### Executable Flags
-Some of these options can be changed at runtime. They are as follows.
+Some defaults can be overridden for a single CLI invocation. They are as
+follows.
 
-```
+```text
     --current ARRAY            List of current entry's tasks
-    --previous ARRAY           List of precious entry's tasks
+    --previous ARRAY           List of previous entry's tasks
     --impediments ARRAY        List of impediments for current entry
     --notes ARRAY              List of notes for current entry
-    --sub-header-order ARRAY   The order of the sub-headers when writing the file
-    --indent-width INTEGER     Number of spaces used for each nested task level
--f, --file-name-format STRING  Date-formattable string to use for standup file name
 -E, --editor EDITOR            Editor to use for opening standup files
--d, --directory DIRECTORY      The directories where standup files are located
--w  --[no-]write               Write current entry if it doesn't exist. Default is true
--a  --[no-]auto-fill-previous  Auto-generate 'previous' tasks for new entries
--e  --[no-]edit                Open the file in the editor. Default is true
+-d, --directory DIRECTORY      The directory where standup files are located
+-w, --[no-]write               Write current entry if it doesn't exist. Default is true
+-a, --[no-]auto-fill-previous  Auto-generate 'previous' tasks for new entries
+-e, --[no-]edit                Open the file in the editor. Default is true
 -v, --[no-]verbose             Verbose output. Default is false.
     --zsh-completion           Print zsh completion setup instructions
 -p, --print [DATE]             Print current entry.
                                If DATE is passed, will print entry for DATE, if it exists.
-                               DATE must be in the same format as file-name-format
+                               DATE must be in the same format as the entry header date.
+-P, --post [PLATFORM]          Post current entry to a chat client. Defaults to Slack.
+                               If PLATFORM is passed, use that post adapter.
+    --post-channel CHANNEL     Channel, room, or conversation to post to
+```
+
+#### Posting and Secrets
+The built-in Slack adapter sends the rendered markdown entry to Slack's
+`chat.postMessage` API. It needs a Slack token with the `chat:write` scope and a
+channel or conversation. Channel-like IDs such as `C123456`, `G123456`, and
+`D123456` are the most reliable values to use. By default, the token is read
+from `STANDUP_MD_SLACK_TOKEN`.
+
+The recommended pattern is to keep secret values in the environment and store
+only non-secret adapter defaults in `~/.standuprc`:
+
+```ruby
+StandupMD.configure do |c|
+  c.post.configure_adapter(:slack, channel: "C123456")
+end
+```
+
+Most chat clients now prefer messages to come from an installed app or bot
+instead of a long-lived user token. That keeps permissions clearer, but it also
+means the visible sender might be a general name like "StandupMD" rather than
+the person whose update is being posted. Set `c.post.title` to identify the
+standup owner in the message title without changing the markdown files that
+StandupMD parses.
+
+```ruby
+StandupMD.configure do |c|
+  c.post.title = "%s - Evan Gray"
+end
+```
+
+The `%s` placeholder is replaced with the normal entry title, usually the entry
+date, so a stored `# 2026-06-27` entry posts as
+`# 2026-06-27 - Evan Gray`.
+
+To use a different token variable, set `token_env`.
+
+```ruby
+StandupMD.configure do |c|
+  c.post.configure_adapter(
+    :slack,
+    channel: "C123456",
+    token_env: "WORK_SLACK_TOKEN"
+  )
+end
+```
+
+#### Custom Post Adapters
+Adapters are registered in `~/.standuprc`. They receive a
+`StandupMD::Post::Message`, which includes the rendered markdown text and the
+channel passed through `StandupMD::Post.post` or `--post-channel`.
+
+```ruby
+class TeamsAdapter
+  def initialize(options = {})
+    @options = options
+  end
+
+  def post(message)
+    channel = message.channel || @options[:channel]
+    token = ENV.fetch("TEAMS_TOKEN")
+
+    # Send message.text to channel with token.
+
+    StandupMD::Post::Result.success(
+      adapter: message.adapter,
+      channel: channel
+    )
+  end
+end
+
+StandupMD.configure do |c|
+  c.post.register_adapter(:teams, TeamsAdapter)
+  c.post.configure_adapter(:teams, channel: "team-channel-id")
+end
+```
+
+Custom adapters can be used from either the CLI or the Ruby API:
+
+```ruby
+StandupMD::Post.post(entry, adapter: :teams, channel: "team-channel-id")
+```
+
+For request-scoped API usage, copy the global defaults and pass the copy into
+the operation:
+
+```ruby
+runtime = StandupMD.config.copy
+runtime.post.default_adapter = :teams
+runtime.post.configure_adapter(:teams, channel: "team-channel-id")
+
+StandupMD::Post.post(entry, config: runtime)
 ```
 
 #### Using Existing Standup Files
@@ -250,8 +371,8 @@ they must be in a format that the parser can understand. The default is:
 ```
 
 The order, words, date format, and header level are all customizable, but the
-overall format must be the same. If customization is necessary, this must be
-done in `~/.standuprc` before execution, or else the parser will error.
+overall format must be the same. If customization is necessary, set the defaults
+or pass a runtime config before reading the file, or else the parser will error.
 
 For example, if you wanted the format to be as follows:
 
@@ -287,9 +408,30 @@ end
 The API is fully documented in the
 [RDoc Documentation](https://evanthegrayt.github.io/standup_md/).
 
-This was mainly written as a command line utility, but the API is very robust,
-and is available for use in your own projects. A quick example of how to write a
-new entry via code could look like the following:
+This was mainly written as a command line utility, but the API is available for
+use in your own projects. `StandupMD.config` stores application defaults. For
+web requests, jobs, or any other multi-call environment, copy those defaults and
+pass the copy into the operation you are running.
+
+`StandupMD::File` handles reading and writing files on disk. The markdown parser
+handles markdown strings:
+
+```ruby
+parser = StandupMD::Parsers::Markdown.new
+entries = parser.parse(File.read("2026_06.md"))
+markdown = parser.render(entries, start_date: entries.first.date, end_date: entries.last.date)
+```
+
+```ruby
+runtime = StandupMD.config.copy
+runtime.file.directory = "/tmp/request-standups"
+runtime.entry.current = ["Work scoped to this request"]
+
+file = StandupMD::File.find_by_date(Date.today, config: runtime.file).load
+entry = StandupMD::Entry.create(config: runtime.entry)
+file.entries << entry
+file.write
+```
 
 ### API Examples
 #### Adding an entry for today
@@ -297,27 +439,29 @@ new entry via code could look like the following:
 require "standup_md"
 
 StandupMD.configure do |c|
-  c.file.current_header = "Today",
+  c.file.current_header = "Today"
 end
 
-file = StandupMD::File.find_by_date(Date.today)
-entry = StandupMD::Entry.create { |e| e.current = ["Stuff I will do today"] }
+file = StandupMD::File.find_by_date(Date.today).load
+entry = StandupMD::Entry.create(current: ["Stuff I will do today"])
 file.entries << entry
 file.write
 ```
 
-The above example was written as such to show how the different pieces of the
-API fit together. The code can actually be simplified to the following.
+The above example uses global defaults. To keep runtime choices scoped to one
+request, copy the defaults and pass the copy into each operation.
 
 ```ruby
 require "standup_md"
 
-StandupMD.configure do |c|
-  c.file.current_header = "Today",
-  c.entry.current = ["Stuff I will do today"]
-end
+runtime = StandupMD.config.copy
+runtime.file.current_header = "Today"
+runtime.entry.current = ["Stuff I will do today"]
 
-StandupMD::File.find_by_date(Date.today).load.write
+file = StandupMD::File.find_by_date(Date.today, config: runtime.file).load
+entry = StandupMD::Entry.create(config: runtime.entry)
+file.entries << entry
+file.write
 ```
 
 #### Finding a past entry
@@ -357,7 +501,7 @@ command, that file will be opened. There's tab completion for this. Lastly,
 it allows for a few variables to be set for customization.
 
 ```vim
-g:standup_dir = $HOME . '/.cache/standup_md' " the directory where your file are
+g:standup_dir = $HOME . '/.cache/standup_md' " the directory where your files are
 g:standup_file = strftime('%Y_%m.md')        " the file format to use
 ```
 

data/completion/zsh/_standup

@@ -4,19 +4,6 @@ _standup_array_values() {
   _message -e values 'comma-separated list'
 }
 
-_standup_sub_header_order() {
-  local -a headers
-
-  headers=(
-    'previous:previous entry tasks'
-    'current:current entry tasks'
-    'impediments:current entry impediments'
-    'notes:current entry notes'
-  )
-
-  _values -s , 'sub-header' $headers
-}
-
 _standup_dates() {
   local directory="${STANDUP_MD_DIR:-$HOME/.cache/standup_md}"
   local index
@@ -53,6 +40,16 @@ _standup_dates() {
   fi
 }
 
+_standup_post_adapters() {
+  local -a adapters
+
+  adapters=(
+    'slack:Slack chat.postMessage adapter'
+  )
+
+  _describe -t adapters 'post adapter' adapters
+}
+
 _arguments -s -S \
   '(- *)'{-h,--help}'[show help]' \
   '(- *)--version[show version]' \
@@ -61,10 +58,6 @@ _arguments -s -S \
   '--previous[List of previous entry tasks]:tasks:_standup_array_values' \
   '--impediments[List of impediments for current entry]:impediments:_standup_array_values' \
   '--notes[List of notes for current entry]:notes:_standup_array_values' \
-  '--sub-header-order[The order of the sub-headers when writing the file]:sub-header order:_standup_sub_header_order' \
-  '--indent-width[Number of spaces used for each nested task level]:indent width:' \
-  '(-f --file-name-format)-f[Date-formattable string to use for standup file name]:strftime format:' \
-  '(-f --file-name-format)--file-name-format[Date-formattable string to use for standup file name]:strftime format:' \
   '(-E --editor)-E[Editor to use for opening standup files]:editor:_path_commands' \
   '(-E --editor)--editor[Editor to use for opening standup files]:editor:_path_commands' \
   '(-d --directory)-d[The directory where standup files are located]:directory:_directories' \
@@ -78,4 +71,6 @@ _arguments -s -S \
   '(-v --verbose --no-verbose)'{-v,--verbose}'[use verbose output]' \
   '(-v --verbose --no-verbose)--no-verbose[disable verbose output]' \
   '(-p --print)'{-p,--print}'[print current entry]::date:_standup_dates' \
+  '(-P --post)'{-P,--post}'[post current entry to a chat client]::platform:_standup_post_adapters' \
+  '--post-channel[channel, room, or conversation to post to]:channel:' \
   '1:standup file date:_standup_dates'