standup_md 1.0.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74c06f0aa4db099f1e64131fdd7e184dd8270db7ee99dd97f9c2cd97374ccef1
-  data.tar.gz: 71e038fce40a7f972b058baee23a7cfbbc1b2eabdbb8f0ccee466ea6fdf70345
+  metadata.gz: d5b3c3f8fe55eadcdc0ae76de9cb745bfe0c557c2c715884fd1056403fba31f1
+  data.tar.gz: d7191750ade93198d7a432762eb3327425a0dcb632389dc90ba6216735b941f2
 SHA512:
-  metadata.gz: 6321c1cf53d23f8a2cd05f191f87059bc9ac308951373ab391ef53c844289098b1edcd4fcb6ef107d7f5bea9f124f7cbd105d75c3d40c2f3fe689427be783264
-  data.tar.gz: 8cefeb0ac1a75a8313ebdaabed8edfdf5b928b73c625c3f3bafebe1b330fafe6d44de2ebc26aee9379ce811b376eac601edd23dc4870c6fafc9b5acc0babf1aa
+  metadata.gz: 1cc3f477255e687f122e018ce1e4d31e6ca0ca7d9c16a003c463324230e68e528a97fc08a52194fa98965ae9ca82bfd963d0343f3b38f12526b5f8bb276b832b
+  data.tar.gz: c0291b6fabd240ac6b292b4e97c2e5c97ed74afd8675b0274295129625326b94ae2a866ff1dabf89a5e91678537b09b572ab677cc6c87bdbb80d8a2e6e36d401

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.1)
+    standup_md (2.0.1)
 
 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.1)
+  standup_md (2.0.1)
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   test-unit (3.7.8) sha256=689d1ca53f4d46f678b4e5d68d8e4294f87fc5e8b9238cc4de7c5727e8d65943
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f

data/README.md

@@ -14,12 +14,13 @@ 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
-editor, and finding and displaying entries from the command line.
+editor, finding and displaying entries from the command line, and posting
+today's standup directly to a chat client.
 
 In a nutshell, calling `standup` from the command line will open a standup file
 for the current month in your preferred editor. If an entry for today is already
@@ -30,7 +31,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.
@@ -132,6 +135,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*.
@@ -142,17 +167,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.
+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
@@ -161,7 +186,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
@@ -191,38 +216,146 @@ 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 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
+For a real-world example of how to get the Slack integration working, see [the
+guide](SLACK_SETUP_GUIDE.md).
+
+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
@@ -242,8 +375,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:
 
@@ -279,9 +412,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
@@ -289,27 +443,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
@@ -349,18 +505,14 @@ 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
 ```
 
-## Reporting Bugs and Requesting Features
-If you have an idea or find a bug, please [create an
-issue](https://github.com/evanthegrayt/standup_md/issues/new). Just make sure
-the topic doesn't already exist. Better yet, you can always submit a Pull
-Request.
-
-## Self-Promotion
-I do these projects for fun, and I enjoy knowing that they're helpful to people.
-Consider starring [the repository](https://github.com/evanthegrayt/standup_md)
-if you like it! If you love it, follow me [on
-Github](https://github.com/evanthegrayt)!
+## Support this project
+I love knowing when people find my work useful. Any kind of support is very much
+appreciated!
+
+- ⭐️ Like the project? Star [the repository](https://github.com/evanthegrayt/standup_md)!
+- ❤️ Love the project? Follow me [on GitHub](https://github.com/evanthegrayt)!
+- 💸 *Really* love it? Consider [buying me a tea](https://paypal.me/evanrgray)!

data/SLACK_SETUP_GUIDE.md

@@ -0,0 +1,82 @@
+# Slack Setup for StandupMD Posting
+
+## Summary
+Create a private Slack app for your workspace, give its bot permission to post
+messages, install it, copy the bot token, invite the bot to `#general`, and
+configure StandupMD with the bot token plus the channel ID.
+
+Workflow last tested and validated 2026-06-27.
+
+## Assumptions
+- You only need to post your standup into one Slack channel.
+- The app is just for your own workspace, not a public Slack Marketplace app.
+- `chat:write` plus inviting the bot to `#general` is the preferred setup.
+- `chat:write.public` is not needed unless you want posting to public channels
+  without inviting the bot first.
+
+## Exact Slack Steps
+1. From the screen in your screenshot, click **Create an App**.
+2. Choose **From scratch**.
+3. Set:
+   - **App Name:** `StandupMD`
+   - **Pick a workspace:** choose the workspace where `#general` lives
+4. Click **Create App**.
+5. In the app sidebar, go to **OAuth & Permissions**.
+6. Under **Scopes** → **Bot Token Scopes**, add:
+   - `chat:write`
+7. Optional: add `chat:write.public` only if you want the bot to post to public
+   channels without being invited first. For the simplest and safest setup, skip
+   this and invite the bot to the channel.
+8. Scroll up and click **Install to Workspace**.
+9. Approve the installation.
+10. After installation, stay on **OAuth & Permissions** and copy the **Bot User
+    OAuth Token**.
+    - It should start with `xoxb-`.
+    - Do not use an `xoxp-` user token.
+    - Do not use an app configuration token.
+
+## Channel Setup
+1. In Slack, go to `#general`.
+2. Invite the app/bot:
+   ```text
+   /invite @StandupMD
+   ```
+3. Get the channel ID for `#general`.
+   - Open `#general`.
+   - Click the channel name at the top.
+   - Look for **Copy channel ID** in the details or more/options menu.
+   - The ID should look like `C1234567890`.
+
+Prefer using the channel ID over `#general` when configuring StandupMD, as the
+name can change but the ID won't.
+
+## StandupMD Values
+Set your token in the shell:
+
+```sh
+export STANDUP_MD_SLACK_TOKEN="xoxb-your-bot-token"
+```
+
+Post with the channel ID:
+
+```sh
+standup -P slack --post-channel C1234567890
+```
+
+Optional config in `~/.standuprc`:
+
+```ruby
+StandupMD.configure do |c|
+  c.post.configure_adapter(:slack, channel: "C1234567890")
+  c.post.title = "%s -- YOUR NAME"
+end
+```
+
+Then you can run:
+
+```sh
+standup -P
+```
+
+If you have multiple users using the same bot, the `c.post.title` is important
+to specify the user posting the standup, since the bot's name is `StandupMD`.

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'