rundoc 5.0.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85fbfa9f84b4e98eb72d487721e7f35001f7820404e30a138de4b4505d788f53
-  data.tar.gz: 1ff08ba1cdd468b190fc54eef124b7ab434d700ffe87ba2b4c8e676d03fb515e
+  metadata.gz: 30dcb03fc239fe1ddd02618341f780c8158ec145646049df7b597206dd7692db
+  data.tar.gz: c31c17bfa5997dc0c79b218e42493d719f6f19d26c1bc758f7d17f24bbe8d996
 SHA512:
-  metadata.gz: 8e87c610bcd8c8589407e68b503eee0578a1dc23b959baa138258185f7d08e6daa3ee17097e4b66b02fea896ee9e5be2bde936e2a601a2b18d1b1a2fc24b36a2
-  data.tar.gz: 9c9f4d7446beaedc74d61354794327cd30f372f7e5e16500678247f7bc549bb7b04992d0875c06c1fa06ae894a36c35902e07930cf55ab4e9fc01bb8b29c44d3
+  metadata.gz: d1c17df9586e3c8d767f8fa79c3d8afebddf5a84c09ae6cbdee14286bb184ee7d51c0ada0827a4dd8a0d480266b63bc1713872200d841b5ae0d5a0af482c2f20
+  data.tar.gz: a3e244880fe064cb86360953f8b3ca4e6b3569201f9bc0c96287686dd99a17a4c59cb3122160a4024b37808e98265758dd40290643cdbb84b0f5826fce5e234c

data/.github/workflows/ci.yml

@@ -13,6 +13,7 @@ jobs:
         ruby:
           - 3.2
           - 3.3
+          - 3.4
           - "4.0"
           - head
     steps:

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## HEAD
 
+## 7.0.0
+
+- Changed: Shell commands now run under `bash -eo pipefail` instead of `/bin/sh`. This surfaces failures in pipelines and compound commands that were previously swallowed. See the README for details on SIGPIPE interactions.
+
+## 6.0.0
+
+- Added: `rundoc.ensure_later(dir: :cwd)` command to register cleanup blocks that run on every build (success and failure). Useful for guaranteed resource teardown (e.g., destroying Heroku apps). Multiple blocks execute in order; failures in one block do not stop the rest.
+- Changed: The ruby context in `rundoc` and `rundoc.configure` commands is now the same binding as the default ERB evaluation. This means that methods can be defined in one and used in both.
+
 ## 5.0.0
 
 - Added comment syntax. Use an octothorpe (`#`) after the visibility markers to comment out any commands and make them a no-op.

data/README.md

@@ -98,6 +98,8 @@ This will generate a project folder with your project in it, and a markdown `REA
   - [website.screenshot](#screenshots)
 - Configure RunDOC
   - [rundoc.configure](#configure)
+  - [rundoc.ensure_later](#ensure_later)
+  - [rundoc](#configure) an alias for `rundoc.configure`
 - Import and compose documents
   - [rundoc.require](#compose-multiple-rundoc-documents)
 
@@ -257,6 +259,8 @@ However this command would fall on its face:
 
 These custom commands are kept to a minimum, and for the most part behave as you would expect them to. Write your docs as you normally would and check the output frequently.
 
+Shell commands run under `bash -eo pipefail` to catch silent failures in pipelines and compound commands. See [Bash Error Handling](#bash-error-handling) for details and SIGPIPE caveats.
+
 Running shell commands like this can be very powerful, you'll likely want more control of how you manipulate files in your project. To do this you can use the `file.` namespace:
 
 ## Dynamic command templating
@@ -616,7 +620,7 @@ If you need to specify project specific environment variables create a file call
 
 ## Configure
 
-You can configure your docs in your docs use the `RunDOC` command
+You can configure your docs in your docs use the `RunDOC` command via `rundoc.configure` (or alias `rundoc`):
 
     ```
     :::-- rundoc.configure
@@ -624,6 +628,30 @@ You can configure your docs in your docs use the `RunDOC` command
 
 Note: Make sure you run this as a hidden command (with `-`).
 
+This will give you a Ruby codeblock that executes and gives you access to `Rundoc.configure do |config|` to configure things about your build (such as modifying your markdown document after successful builds).
+
+**Define and Re-use logic**
+
+Since it's **just ruby** :tm: you can also use it to define shared logic that can be re-used in ERB templates. For example:
+
+      ```
+      :::-- rundoc
+      def run!(command, quiet: false, error_on_fail: true)
+        puts "Running `#{command}`" unless quiet
+        output = `#{command}`
+        puts "Command `#{command}` output:\n#{output}" unless quiet
+        if error_on_fail && !$?.success?
+          raise "Error running #{command}. Output:\n#{output}"
+        end
+        output
+      end
+      ```
+
+      ```
+      :::-> print.erb
+      Hello <%= run!("heroku whoami") %>!
+      ```
+
 **After Build**
 
 This will eval any code you put under that line (in Ruby) when the build was successful but before the contents are finalized on disk. If you want to run some code after you're done building your docs you could use `Rundoc.configure` block and call the `after_build` method like this:
@@ -658,6 +686,128 @@ Sometimes sensitive info like usernames, email addresses, or passwords may be in
 
 This command `filter_sensitive` can be called multiple times with different values. Since the config is in Ruby you could iterate over an array of sensitive data
 
+## Ensure Later
+
+Run a script on EVERY build (success and failure). Used to guarantee resources are cleaned up.
+
+- Arguments
+  - `dir:` The directory where the script will be run. Must be one of these values:
+    - `:cwd` The directory where the command is first invoked. If this directory does not exist when the `rundoc.ensure_later` is invoked, it will raise an error.
+    - `:rundoc_root` The tmp directory where the script is being executed. Useful if the directory where the `rundoc.ensure_later` is defined, is deleted by the rundoc script.
+
+For example:
+
+    ```
+    :::>> $ heroku create
+    :::-- rundoc
+    @app_name = run!("heroku info --json | jq -r '.app.name'").strip
+
+    def app_name
+      @app_name
+    end
+    ```
+
+    ```ruby
+    :::-- rundoc.ensure_later(dir: :cwd)
+    if run!("heroku apps").include?(app_name)
+      puts "Cleaning up web app #{app_name}"
+      run!("heroku apps:destroy #{app_name} --confirm #{app_name}")
+    else
+      puts "App `#{app_name}` already cleaned, nothing to do"
+    end
+    ```
+
+The output of this will not be included in the document. Multiple ensure blocks can be defined and will execute in the order of their definition. Since they'll be executed EVERY time, logic must handle both success and failure cases. This execution occurs before the temp directory is removed, and before any background task shutdown ensure blocks are triggered.
+
+If a build is successful, but an `ensure_later` block fails, the build will be considered a failure. A failure in one block will not stop the rest from executing.
+
+## Bash Error Handling
+
+### Bash `set -eo pipefail` explained
+
+Bash error behavior is configurable. Rundoc uses `set -eo pipefail` to catch common problems not caught by the default error mode.
+
+If a failing command is piped to a valid command, by default bash will "hide" the failure by returning a zero (success) exit code:
+
+```term
+$ bash -c "cat does-not-exist | head -n1"
+cat: does-not-exist: No such file or directory
+$ echo $?
+0
+```
+
+With `-o pipefail`, the pipeline reports the exit status of the last command that failed rather than the last command in the pipe. With `-e`, bash exits immediately when a command fails. Together, `-eo pipefail` ensures a failing command's exit status is not hidden. Here, the exit code `1` comes from `cat` failing to open a file that doesn't exist:
+
+```term
+$ bash -eo pipefail -c "cat does-not-exist | head -n1"
+cat: does-not-exist: No such file or directory
+$ echo $?
+1
+```
+
+A similar scenario is when multiple commands are given on one line separated by a semicolon. Without `-e`, bash continues past the failure:
+
+```term
+$ bash -c "cat does-not-exist; echo 'done'"
+cat: does-not-exist: No such file or directory
+done
+$ echo $?
+0
+```
+
+With `-e`, bash exits immediately after the failing command:
+
+```term
+$ bash -eo pipefail -c "cat does-not-exist; echo 'done'"
+cat: does-not-exist: No such file or directory
+$ echo $?
+1
+```
+
+These settings help prevent silent failures from slipping through your Rundoc scripts.
+
+### Bash SIGPIPE
+
+Tools like `head -n1` and `grep -m1 "value"` read only part of their input and then exit. When the upstream process next tries to write to the now-closed pipe, the kernel delivers a `SIGPIPE` signal to terminate it. This behavior is useful when the input is a never-ending stream but you only need a subset:
+
+```term
+$ bash -c 'yes "output" | head -n1'
+output
+$ echo $?
+0
+```
+
+However, this behavior negatively interacts with `set -eo pipefail`. Even though `head -n1` successfully produced its output and the command appears to run cleanly, `pipefail` reports the upstream process's SIGPIPE termination as a non-zero exit:
+
+```term
+$ bash -eo pipefail -c 'yes "output" | head -n1'
+output
+$ echo $?
+141
+```
+
+If the input is fully buffered (such as reading from a small file), `head` can finish before the writer needs to write again, so SIGPIPE is never triggered. That means `cat small-file.txt | head -n1` is reasonably safe, but this behavior can surface with larger files:
+
+```term
+$ tmpfile=$(mktemp)
+$ seq 1 200000 > "$tmpfile"
+$ bash -eo pipefail -c "cat $tmpfile | head -n1"
+1
+$ echo $?
+141
+```
+
+This SIGPIPE behavior can cause your rundoc script to exit early when you aren't expecting it.
+
+You can rewrite some commands to take a file directly. For example, `cat Gemfile | head -n 5` can be rewritten as `head -n 5 Gemfile` without SIGPIPE risk.
+
+Here are common commands that can trigger a SIGPIPE:
+
+- `head` with `-n <N>` or `-c <N>`
+- `grep` with `-m <N>` (max count)
+- `sed <N>q` (quit after N lines)
+- `awk` with `{exit}` — e.g., rewrite `awk '/^Start/ {flag=1} /^End/ {exit} flag'` without exit as `awk '/^Start/ {flag=1} /^End/ {flag=0} flag'`
+
 ## Writing a new command
 
 > Note: This is an advanced topic and this interface is unstable.

data/lib/rundoc/cli.rb

@@ -134,6 +134,9 @@ module Rundoc
     end
 
     def call
+      build_success = false
+      ensure_later_errors = []
+
       io.puts "## Running your docs"
       load_dotenv
       check_directories_empty!
@@ -165,7 +168,11 @@ module Rundoc
           io: io
         )
         output = begin
-          parser.to_md
+          begin
+            parser.to_md
+          ensure
+            ensure_later_errors = Rundoc.run_ensure_later(io: io)
+          end
         rescue StandardError, SignalException => e
           io.puts "Received exception: #{e.inspect}, cleaning up before re-raise"
           on_fail
@@ -174,6 +181,8 @@ module Rundoc
 
         on_success(output)
       end
+
+      build_success = true
     ensure
       # Stop any hanging background tasks
       Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
@@ -189,6 +198,10 @@ module Rundoc
           description: "tmp working directory"
         )
       end
+
+      if ensure_later_errors.any? && build_success
+        raise ensure_later_errors.first
+      end
     end
 
     private def clean_dir(dir:, description:)

data/lib/rundoc/code_command/bash/cd.rb

@@ -7,25 +7,19 @@ class Rundoc::CodeCommand::BashRunner
       @line = line
     end
 
-    # Ignore duplicate chdir warnings "warning: conflicting chdir during another chdir block"
-    def supress_chdir_warning
-      old_stderr = $stderr
-      capture_stderr = StringIO.new
-      $stderr = capture_stderr
+    def suppress_chdir_warning
+      old_verbose = $VERBOSE
+      $VERBOSE = nil
       yield
     ensure
-      if old_stderr
-        $stderr = old_stderr
-        capture_string = capture_stderr.string
-        warn capture_string if capture_string.each_line.count > 1 || !capture_string.include?("conflicting chdir")
-      end
+      $VERBOSE = old_verbose
     end
 
     def call(env)
       line = @line.sub("cd", "").strip
       @io.puts "running $ cd #{line}"
 
-      supress_chdir_warning do
+      suppress_chdir_warning do
         Dir.chdir(line)
       end
 

data/lib/rundoc/code_command/bash.rb

@@ -45,13 +45,18 @@ class Rundoc::CodeCommand::BashRunner
   end
 
   def shell(cmd, stdin = nil)
-    cmd = "(#{cmd}) 2>&1"
     msg = "Running: $ '#{cmd}'"
     msg << " with stdin: '#{stdin.inspect}'" if stdin && !stdin.empty?
     io.puts msg
 
     result = +""
-    IO.popen(cmd, "w+") do |pipe|
+    # -e: Abort on first failure in compound commands (e.g. `bundle install; echo done`)
+    #     so the exit status reflects the real failure, not a trailing success.
+    # -o pipefail: Report the first failure in a pipeline (e.g. `git push | tee log`)
+    #     instead of only the last command's exit status.
+    # -u (nounset) is intentionally omitted: tutorial commands routinely
+    #     reference environment variables that may not be set.
+    IO.popen(["bash", "-eo", "pipefail", "-c", cmd, err: [:child, :out]], "w+") do |pipe|
       pipe << stdin if stdin
       pipe.close_write
 

data/lib/rundoc/code_command/empty_binding.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "erb"
+
+class EmptyBinding
+  def self.create
+    new.empty_binding
+  end
+
+  def empty_binding
+    binding
+  end
+end
+
+module Rundoc::CodeCommand
+  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
+  RUNDOC_DEFAULT_ERB_BINDING = "default"
+end

data/lib/rundoc/code_command/print/erb.rb

@@ -1,21 +1,8 @@
 # frozen_string_literal: true
 
-require "erb"
-
-class EmptyBinding
-  def self.create
-    new.empty_binding
-  end
-
-  def empty_binding
-    binding
-  end
-end
+require_relative "../empty_binding"
 
 module Rundoc::CodeCommand
-  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
-  RUNDOC_DEFAULT_ERB_BINDING = "default"
-
   class PrintERBArgs
     attr_reader :line, :binding_name
 

data/lib/rundoc/code_command/rundoc/ensure_later.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ::Rundoc::CodeCommand
+  class RundocCommand
+    class EnsureLaterArgs
+      MAPPING = {
+        cwd: ->(context:) {
+          Dir.pwd
+        },
+        rundoc_root: ->(context:) {
+          context.output_dir.to_s
+        }
+      }.freeze
+
+      def initialize(dir:)
+        @dir = dir
+        @logic = MAPPING[dir] or raise ArgumentError, "Invalid argument dir: #{dir} must be one of #{MAPPING.keys}"
+      end
+
+      def call(context:)
+        @logic.call(context: context)
+      end
+
+      def to_s
+        @dir.to_s
+      end
+    end
+
+    class EnsureLaterRunner
+      attr_reader :io, :contents
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @io = io
+        @contents = contents.dup if contents && !contents.empty?
+        @dir = user_args
+        @binding = RUNDOC_ERB_BINDINGS[RUNDOC_DEFAULT_ERB_BINDING]
+      end
+
+      def to_md(env = {})
+        ""
+      end
+
+      def call(env = {})
+        resolved_dir = @dir.call(context: env[:context])
+
+        io.puts "Registering ensure_later block (dir: #{@dir} => #{resolved_dir})"
+        Rundoc.add_ensure_later(dir: resolved_dir, code: @contents, binding: @binding)
+        ""
+      end
+    end
+  end
+end
+
+Rundoc.register_code_command(
+  keyword: :"rundoc.ensure_later",
+  args_klass: Rundoc::CodeCommand::RundocCommand::EnsureLaterArgs,
+  runner_klass: Rundoc::CodeCommand::RundocCommand::EnsureLaterRunner,
+  always_hidden: true
+)

data/lib/rundoc/code_command/rundoc_command.rb

@@ -17,6 +17,7 @@ module ::Rundoc
         @io = io
         @contents = contents.dup if contents && !contents.empty?
         @contents = user_args.code + (@contents || +"")
+        @binding = RUNDOC_ERB_BINDINGS[RUNDOC_DEFAULT_ERB_BINDING]
       end
 
       def to_md(env = {})
@@ -25,7 +26,9 @@ module ::Rundoc
 
       def call(env = {})
         io.puts "Running: #{contents}"
-        eval(contents) # rubocop:disable Security/Eval
+        Rundoc.capture_stdout_stderr(io) do
+          eval(contents, @binding) # rubocop:disable Security/Eval
+        end
         ""
       end
     end
@@ -36,3 +39,4 @@ Rundoc.register_code_command(keyword: :rundoc, args_klass: Rundoc::CodeCommand::
 Rundoc.register_code_command(keyword: :"rundoc.configure", args_klass: Rundoc::CodeCommand::RundocCommandArgs, runner_klass: Rundoc::CodeCommand::RundocCommandRunner)
 
 require "rundoc/code_command/rundoc/require"
+require "rundoc/code_command/rundoc/ensure_later"

data/lib/rundoc/code_command.rb

@@ -5,6 +5,7 @@ module Rundoc
   end
 end
 
+require "rundoc/code_command/empty_binding"
 require "rundoc/code_command/deferred"
 require "rundoc/code_command/bash"
 require "rundoc/code_command/pipe"

data/lib/rundoc/peg_parser.rb

@@ -39,9 +39,16 @@ module Rundoc
       ).as(:number)
     }
 
+    rule(:symbol) {
+      str(":") >> (
+        match("[a-zA-Z_]") >> match("[a-zA-Z0-9_]").repeat
+      ).as(:symbol)
+    }
+
     rule(:value) {
       string |
         number |
+        symbol |
         str("true").as(true) |
         str("false").as(false) |
         str("nil").as(:nil)
@@ -175,6 +182,7 @@ module Rundoc
     rule(true => simple(:tr)) { true }
     rule(false => simple(:fa)) { false }
     rule(string: simple(:st)) { st.to_s }
+    rule(symbol: simple(:sy)) { sy.to_s.to_sym }
 
     rule(number: simple(:nb)) {
       /[eE.]/.match?(nb) ? Float(nb) : Integer(nb)

data/lib/rundoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rundoc
-  VERSION = "5.0.0"
+  VERSION = "7.0.0"
 end

data/lib/rundoc.rb

@@ -97,6 +97,43 @@ module Rundoc
     yield self
   end
 
+  def ensure_later_blocks
+    @ensure_later_blocks ||= []
+  end
+
+  def add_ensure_later(dir:, code:, binding:)
+    ensure_later_blocks << {dir: dir, code: code, binding: binding}
+  end
+
+  def run_ensure_later(io:)
+    errors = []
+    ensure_later_blocks.each do |block|
+      io.puts "Running ensure_later block in #{block[:dir]}:\n#{block[:code]}"
+      Dir.chdir(block[:dir]) do
+        capture_stdout_stderr(io) do
+          eval(block[:code], block[:binding]) # rubocop:disable Security/Eval
+        end
+      end
+    rescue => e
+      io.puts "ensure_later block failed in #{block[:dir]}: #{e.message}"
+      io.puts e.backtrace.join("\n")
+      errors << e
+    end
+    ensure_later_blocks.clear
+    errors
+  end
+
+  def capture_stdout_stderr(io)
+    old_stdout = $stdout
+    old_stderr = $stderr
+    $stdout = io
+    $stderr = io
+    yield
+  ensure
+    $stdout = old_stdout
+    $stderr = old_stderr
+  end
+
   def filter_sensitive(sensitive)
     raise "Expecting #{sensitive} to be a hash" unless sensitive.is_a?(Hash)
     @sensitive ||= {}

data/rundoc.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "aws-sdk-s3", "~> 1"
   gem.add_dependency "dotenv"
+  gem.add_dependency "cgi", ">= 0.3.6"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "mocha"

data/test/integration/ensure_later_test.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class IntegrationEnsureLaterTest < Minitest::Test
+  def test_runs_on_success
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "yes")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert marker.exist?, "ensure_later block should have run on success"
+        assert_equal "yes", marker.read
+      end
+    end
+  end
+
+  def test_runs_on_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "cleaned")
+          ```
+
+          ```
+          :::>> $ exit 1
+          ```
+        EOF
+
+        assert_raises do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME),
+            on_failure_dir: dir.join(FAILURE_DIRNAME)
+          ).call
+        end
+
+        assert marker.exist?, "ensure_later block should have run on failure"
+        assert_equal "cleaned", marker.read
+      end
+    end
+  end
+
+  def test_multiple_blocks_run_in_order
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("order.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "first")
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", File.read("#{marker}") + ",second")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert_equal "first,second", marker.read
+      end
+    end
+  end
+
+  def test_one_failure_does_not_stop_others
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("second_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          raise "intentional failure"
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "yes")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        error = assert_raises(RuntimeError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+        assert_match(/intentional failure/, error.message)
+
+        assert marker.exist?, "second ensure_later should still run after first fails"
+      end
+    end
+  end
+
+  def test_success_plus_ensure_failure_is_overall_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          raise "cleanup failed"
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        error = assert_raises(RuntimeError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+
+        assert_match(/cleanup failed/, error.message)
+      end
+    end
+  end
+
+  def test_dir_rundoc_root
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("root_marker.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir subdir
+          :::>> $ cd subdir
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :rundoc_root)
+          File.write("#{marker}", Dir.pwd)
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        cli = Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        )
+        output_dir = cli.execution_context.output_dir.realpath.to_s
+
+        cli.call
+
+        assert marker.exist?, "ensure_later with dir: :rundoc_root should run"
+        assert_equal output_dir, marker.read
+      end
+    end
+  end
+
+  def test_output_not_in_document
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          puts "THIS SHOULD NOT APPEAR"
+          ```
+
+          ```
+          :::>> $ echo "visible"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        readme = dir.join(SUCCESS_DIRNAME).join("README.md").read
+        refute_match(/THIS SHOULD NOT APPEAR/, readme)
+        assert_match(/visible/, readme)
+      end
+    end
+  end
+
+  def test_invalid_dir_raises
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :invalid)
+          puts "should not run"
+          ```
+        EOF
+
+        assert_raises(ArgumentError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+      end
+    end
+  end
+
+  def test_shared_binding_with_rundoc
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("binding_test.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc
+          def my_helper
+            "from_rundoc"
+          end
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", my_helper)
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert_equal "from_rundoc", marker.read
+      end
+    end
+  end
+
+  def test_runs_on_failure_from_subdirectory
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir myapp
+          :::>> $ cd myapp
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "cleaned")
+          ```
+
+          ```
+          :::>> $ exit 1
+          ```
+        EOF
+
+        assert_raises do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME),
+            on_failure_dir: dir.join(FAILURE_DIRNAME)
+          ).call
+        end
+
+        assert marker.exist?, "ensure_later from subdirectory should run even on failure"
+        assert_equal "cleaned", marker.read
+      end
+    end
+  end
+
+  def test_log_output_shows_dir_mode_name
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          puts "hello"
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        io = StringIO.new
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        output = io.string
+        assert_includes output, "Registering ensure_later block (dir: cwd => /"
+      end
+    end
+  end
+end

data/test/integration/print_test.rb

@@ -50,6 +50,57 @@ class IntegrationPrintTest < Minitest::Test
     end
   end
 
+  def test_rundoc_configure_defines_variable_accessible_from_erb
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-- rundoc.configure
+      @shared_value = "#{key}"
+      ```
+
+      ```
+      :::-> print.erb
+      <%= @shared_value %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
+        assert_includes actual, key
+      end
+    end
+  end
+
+  def test_erb_defines_variable_accessible_from_rundoc_configure
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-> print.erb
+      <% @from_erb = "#{key}" %>
+      ```
+
+      ```
+      :::-- rundoc.configure
+      @roundtripped = @from_erb + "_via_configure"
+      ```
+
+      ```
+      :::-> print.erb
+      <%= @roundtripped %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
+        assert_includes actual, "#{key}_via_configure"
+      end
+    end
+  end
+
   def test_erb_in_block
     contents = <<~RUBY
       ```

data/test/rundoc/code_commands/bash_test.rb

@@ -25,6 +25,30 @@ class BashTest < Minitest::Test
     end
   end
 
+  def test_pipefail_catches_early_failure
+    command = "false | true"
+    bash = Rundoc::CodeCommand::BashRunner.new(
+      render_command: false,
+      render_result: false,
+      io: StringIO.new,
+      user_args: Rundoc::CodeCommand::BashArgs.new(command)
+    )
+    error = assert_raises(RuntimeError) { bash.call }
+    assert_match(/exited with non zero status/, error.message)
+  end
+
+  def test_errexit_catches_compound_command_failure
+    command = "false; echo done"
+    bash = Rundoc::CodeCommand::BashRunner.new(
+      render_command: false,
+      render_result: false,
+      io: StringIO.new,
+      user_args: Rundoc::CodeCommand::BashArgs.new(command)
+    )
+    error = assert_raises(RuntimeError) { bash.call }
+    assert_match(/exited with non zero status/, error.message)
+  end
+
   def test_stdin
     command = "tail -n 2"
     bash = Rundoc::CodeCommand::BashRunner.new(

data/test/rundoc/peg_parser_test.rb

@@ -367,4 +367,29 @@ class PegParserTest < Minitest::Test
     assert_equal :rundoc, actual.keyword
     assert_equal "first = 1 # comment\nsecond = 2".strip, actual.contents.strip
   end
+
+  def test_symbol_value
+    input = %(:cwd)
+    parser = Rundoc::PegParser.new.symbol
+    tree = parser.parse_with_debug(input)
+    actual = @transformer.apply(tree)
+    assert_equal :cwd, actual
+  end
+
+  def test_symbol_in_named_args
+    input = %(dir: :cwd)
+    parser = Rundoc::PegParser.new.named_args
+    tree = parser.parse_with_debug(input)
+    actual = @transformer.apply(tree)
+    assert_equal({dir: :cwd}, actual)
+  end
+
+  def test_symbol_in_method_call
+    input = %(rundoc.ensure_later(dir: :cwd))
+    parser = Rundoc::PegParser.new.method_call
+    tree = parser.parse_with_debug(input)
+    actual = @transformer.apply(tree)
+    assert_equal :"rundoc.ensure_later", actual.keyword
+    assert_equal({dir: :cwd}, actual.original_args)
+  end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rundoc
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 7.0.0
 platform: ruby
 authors:
 - Richard Schneeman
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -107,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.6
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -212,6 +227,7 @@ files:
 - lib/rundoc/code_command/bash/cd.rb
 - lib/rundoc/code_command/comment.rb
 - lib/rundoc/code_command/deferred.rb
+- lib/rundoc/code_command/empty_binding.rb
 - lib/rundoc/code_command/file_command/append.rb
 - lib/rundoc/code_command/file_command/remove.rb
 - lib/rundoc/code_command/no_such_command.rb
@@ -220,6 +236,7 @@ files:
 - lib/rundoc/code_command/print/erb.rb
 - lib/rundoc/code_command/print/text.rb
 - lib/rundoc/code_command/raw.rb
+- lib/rundoc/code_command/rundoc/ensure_later.rb
 - lib/rundoc/code_command/rundoc/require.rb
 - lib/rundoc/code_command/rundoc_command.rb
 - lib/rundoc/code_command/website.rb
@@ -262,6 +279,7 @@ files:
 - test/fixtures/simple_git/rundoc.md
 - test/integration/after_build_test.rb
 - test/integration/background_stdin_test.rb
+- test/integration/ensure_later_test.rb
 - test/integration/failure_test.rb
 - test/integration/pre_erb_test.rb
 - test/integration/print_test.rb
@@ -287,6 +305,7 @@ homepage: https://github.com/schneems/rundoc
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -301,7 +320,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: RunDOC generates runable code from docs
 test_files: []