rundoc 3.1.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d21f4ac48ad2eab762969c03ce386aeb097f99162d38716e4736de44c9bbac83
-  data.tar.gz: 79f9be265a84d8474e3ed7d55d90781e9999790b6cf5e578943db89e0fec7ee9
+  metadata.gz: ab49039bd205d3d147c1de91935b0deb1ffa095311eead39c750b426db1d7c87
+  data.tar.gz: f6a45b2b7a7b858ce09c8464ab891f9b3e7afe272de9d00768e5760a36f4533d
 SHA512:
-  metadata.gz: fcf456c89f09000ddeeaf7aa22654acf419f36294b9e88dec9735f9ec3fcab315085dd6ee97cbd63eb580078e009968219b5240a6fe7a6db4c022d1b878d97cb
-  data.tar.gz: 8e2ee0bd6fa26b8b8906ec9b2267a9e98feedc40b54dc53ca457937a7199865c2c6b7663837a067802426321fc93740da3038289ea516139a573a1e5679c8724
+  metadata.gz: 3d946cf5081696a80ef34867e6559cb51f2191682e74ec21d44d524c41c11bdc05f73fe0f832afe9a89e5c85e6d6f588dfb85f857dbe141f2da278fc60df2527
+  data.tar.gz: 2c0fd644519f2cde9ca67ef6d56c9f1fa17727883149ebb0a437a9e163b70c41b478f1be39f50560fd7c7bf59ba77dab305d4654c2737fdfdc350098f094a549

data/CHANGELOG.md

@@ -1,12 +1,35 @@
 ## HEAD
 
+## 4.0.0
+
+- Add: Rundoc command `background.stdin_write` to send a string to a backtround process' STDIN. This allows driving REPL interfaces (https://github.com/zombocom/rundoc/pull/79)
+
+```
+:::>- background.start("ruby #{script}",
+  name: "script",
+  wait: ">",
+  timeout: 15
+)
+:::-- background.stdin_write("hello", name: "script", wait: "hello")
+:::-- background.stdin_write("exit", name: "script", wait: "exit")
+:::>> background.stop(name: "script")
+```
+
+- Changed: Rundoc command `background.stop` now outputs the log contents on `:::>>`. Previously it output nothing (https://github.com/zombocom/rundoc/pull/79)
+- Changed: Strings passed into `background.wait` and similar `wait:` arguments of other background rundoc commands were accidentally being converted into regex, now they are matched as string literals. If you need regexes, please open an issue, they could be supporte but require peg_parser support (https://github.com/zombocom/rundoc/pull/79)
+
+## 3.1.2
+
+- Fix: Using `rundoc.require` inside of a document that was `rundoc.require`-d now sources files from the correct relative document path (https://github.com/zombocom/rundoc/pull/84)
+- Fix: `rundoc <file> --with-contents <dir>` now expands the path passed in to the `--with-contents` so relative paths can safely be used (https://github.com/zombocom/rundoc/pull/83)
+
 ## 3.1.1
 
 - Fix: Include all code sections in the event of a failure, not just the last one (https://github.com/zombocom/rundoc/pull/71)
 
 ## 3.1.0
 
-- Add: `--with-contents` flag that accepts a directory. The **contents** of the directory (and not the directory itself) will be copied into the working dir before execution. This is useful for debugging a single rundoc step. ()
+- Add: `--with-contents` flag that accepts a directory. The **contents** of the directory (and not the directory itself) will be copied into the working dir before execution. This is useful for debugging a single rundoc step. (https://github.com/zombocom/rundoc/pull/83)
 
 For example if `RUNDOC.md` features many smaller docs:
 

data/README.md

@@ -86,9 +86,10 @@ This will generate a project folder with your project in it, and a markdown `REA
 - Boot background processes such as a local server
   - [background.start](#background)
   - [background.stop](#background)
+  - [background.stdin_write](#background)
+  - [background.wait](#background)
   - [background.log.read](#background)
   - [background.log.clear](#background)
-  - [background.wait](#background)
 - Take screenshots
   - [website.visit](#screenshots)
   - [website.nav](#screenshots)
@@ -424,6 +425,21 @@ You can make the background process wait until it receives a certain string in t
 :::>> background.start("rails server", name: "server", wait: "Listening on")
 ```
 
+You can send strings to the STDIN of the process:
+
+```
+:::>> background.start("heroku run bash", name: "heroku_run", wait: "$")
+:::-- background.stdin_write("ls", name: "heroku_run")
+```
+
+- Arguments
+  - contents: Positional. The string to write to stdin
+  - ending: A string to append to the end of the contents, defaults to a newline
+            you could set it to something like ";" or an empty newline ""
+  - name
+  - wait
+  - timeout
+
 You can stop the process by referencing the name:
 
 ```
@@ -433,6 +449,7 @@ You can stop the process by referencing the name:
 - Arguments
   - name
 
+
 You can also get the log contents:
 
 ```

data/lib/rundoc/cli_argument_parser.rb

@@ -111,7 +111,7 @@ module Rundoc
         end
 
         opts.on("--with-contents <dir>", "Copies contents of directory into the tmp working dir") do |v|
-          options[:with_contents_dir] = v
+          options[:with_contents_dir] = File.expand_path(v)
         end
 
         opts.on("--on-success-dir <dir>", "Success dir, relative to CWD. i.e. `<rundoc.md/dir>/#{CLI::DEFAULTS::ON_SUCCESS_DIR}/`.") do |v|

data/lib/rundoc/code_command/background/process_spawn.rb

@@ -19,7 +19,6 @@ class Rundoc::CodeCommand::Background
   #   server.stop
   #   server.alive? # => false
   #
-  #
   # There are class level methods that can be used to "name" and record
   # background processes. They can be used like this:
   #
@@ -53,17 +52,31 @@ class Rundoc::CodeCommand::Background
       @log = Pathname.new(log)
       @log.dirname.mkpath
       FileUtils.touch(@log)
+      @pipe_output, @pipe_input = IO.pipe
 
       @command = "/usr/bin/env bash -c #{@command.shellescape} >> #{@log} #{out}"
       @pid = nil
     end
 
-    def wait(wait_value = nil, timeout_value = @timeout_value)
+    # Wait until a given string is found in the logs
+    #
+    # If the string is not found within the timeout, a Timeout::Error is raised
+    #
+    # Caution: The logs will not be cleared before waiting, so if the string is
+    # already present from a prior operation, then it will not wait at all.
+    #
+    # To ensure you're waiting for a brand new string, call `log.truncate(0)` first.
+    # which is accessible via `:::-- background.log.clear` in rundoc syntax.
+    #
+    # @param wait_value [String] the string to wait for
+    # @param timeout_value [Integer] the number of seconds to wait before raising a Timeout::Error
+    # @param file [Pathname] the file to read from, default is the log file
+    def wait(wait_value = nil, timeout_value = @timeout_value, file: @log)
       call
       return unless wait_value
 
       Timeout.timeout(Integer(timeout_value)) do
-        until @log.read.match(wait_value)
+        until file.read.include?(wait_value)
           sleep 0.01
         end
       end
@@ -78,10 +91,42 @@ class Rundoc::CodeCommand::Background
       false
     end
 
+    # Writes the contents along with an optional ending character to the STDIN of the backtround process
+    #
+    # @param contents [String] the contents to write to the STDIN of the background process
+    # @param ending [String] an optional string to append to the contents before writing default is a newline
+    #                if you don't want an ending, pass `""`
+    # @param timeout [Integer] the number of seconds to wait before raising a Timeout::Error when writing to STDIN
+    #                or waiting for a string to appear in the logs. That means that the process can wait for a maximum
+    #                of `timeout * 2` seconds before raising a Timeout::Error.
+    # @param wait [String] the string to wait for in the logs before continuing. There's a race condition
+    #             if the process is in the middle of printing out something to the logs, then the output
+    #             you're waiting form might not come as a result of the stdin_write.
+    def stdin_write(contents, ending: $/, timeout: timeout_value, wait: nil)
+      log_file = File.new(@log)
+      before_write_bytes = log_file.size
+      begin
+        Timeout.timeout(Integer(timeout)) do
+          @pipe_input.print(contents + ending)
+          @pipe_input.flush
+        end
+      rescue Timeout::Error
+        raise "Timeout (#{timeout}s) waiting to write #{contents} to stdin. Log contents:\n'#{log.read}'"
+      end
+
+      # Ignore bytes written before we sent the STDIN message
+      log_file.seek(before_write_bytes)
+      wait(wait, timeout, file: log_file)
+      contents
+    end
+
     def stop
       return unless alive?
+      @pipe_input.close
       Process.kill("TERM", -Process.getpgid(@pid))
       Process.wait(@pid)
+    rescue Errno::ESRCH => e
+      puts "Error stopping process (command: #{command}): #{e}"
     end
 
     def check_alive!
@@ -89,7 +134,7 @@ class Rundoc::CodeCommand::Background
     end
 
     private def call
-      @pid ||= Process.spawn(@command, pgroup: true)
+      @pid ||= Process.spawn(@command, pgroup: true, in: @pipe_output)
     end
   end
 end

data/lib/rundoc/code_command/background/stdin_write.rb

@@ -0,0 +1,36 @@
+class Rundoc::CodeCommand::Background
+  # Will send contents to the background process via STDIN along with a newline
+  #
+  #
+  class StdinWrite < Rundoc::CodeCommand
+    def initialize(contents, name:, wait:, timeout: 5, ending: $/)
+      @contents = contents
+      @ending = ending
+      @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
+      @wait = wait
+      @timeout_value = Integer(timeout)
+      @contents_written = nil
+    end
+
+    # The command is rendered (`:::>-`) by the output of the `def call` method.
+    def to_md(env = {})
+      writecontents
+    end
+
+    # The contents produced by the command (`:::->`) are rendered by the `def to_md` method.
+    def call(env = {})
+      writecontents
+      @spawn.log.read
+    end
+
+    def writecontents
+      @contents_written ||= @spawn.stdin_write(
+        contents,
+        wait: @wait,
+        ending: @ending,
+        timeout: @timeout_value
+      )
+    end
+  end
+end
+Rundoc.register_code_command(:"background.stdin_write", Rundoc::CodeCommand::Background::StdinWrite)

data/lib/rundoc/code_command/background/stop.rb

@@ -10,7 +10,7 @@ class Rundoc::CodeCommand::Background
 
     def call(env = {})
       @spawn.stop
-      ""
+      @spawn.log.read
     end
   end
 end

data/lib/rundoc/code_command/background.rb

@@ -7,3 +7,4 @@ require "rundoc/code_command/background/stop"
 require "rundoc/code_command/background/wait"
 require "rundoc/code_command/background/log/clear"
 require "rundoc/code_command/background/log/read"
+require "rundoc/code_command/background/stdin_write"

data/lib/rundoc/code_command/rundoc/require.rb

@@ -14,12 +14,17 @@ class ::Rundoc::CodeCommand
       end
 
       def call(env = {})
-        document_path = @path.expand_path(env[:context].source_dir)
+        execution_context = env[:context]
+        document_path = @path.expand_path(execution_context.source_dir)
 
-        puts "rundoc.require: Start executing #{@path.to_s.inspect}"
         output = Rundoc::Parser.new(
           document_path.read,
-          context: env[:context]
+          context: Rundoc::Context::Execution.new(
+            source_path: document_path,
+            output_dir: execution_context.output_dir,
+            screenshots_dirname: execution_context.screenshots_dir,
+            with_contents_dir: execution_context.with_contents_dir
+          )
         ).to_md
 
         if render_result?

data/lib/rundoc/version.rb

@@ -1,3 +1,3 @@
 module Rundoc
-  VERSION = "3.1.1"
+  VERSION = "4.0.0"
 end

data/test/integration/background_stdin_test.rb

@@ -0,0 +1,57 @@
+require "test_helper"
+
+class BackgroundStdinTest < Minitest::Test
+  def test_background_stdin_write
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        script = dir.join("script.rb")
+        script.write <<~'EOF'
+          $stdout.sync = true
+
+          print "> "
+          while line = gets
+            puts line
+            if line.strip == "exit"
+              puts "Bye"
+              return
+            else
+              puts "You said: #{line}"
+            end
+            print "> "
+          end
+        EOF
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>- background.start("ruby #{script}",
+            name: "script",
+            wait: ">",
+            timeout: 15
+          )
+          :::-- background.stdin_write("hello", name: "script", wait: "hello")
+          :::-- background.stdin_write("exit", name: "script", wait: "exit")
+          :::>> background.stop(name: "script")
+          ```
+        EOF
+
+        io = StringIO.new
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        readme = dir.join(SUCCESS_DIRNAME).join("README.md").read
+        expected = <<~EOF
+          > hello
+          You said: hello
+          > exit
+          Bye
+        EOF
+        assert readme.include?(expected)
+      end
+    end
+  end
+end

data/test/integration/require_test.rb

@@ -60,4 +60,38 @@ class IntegrationRequireTest < Minitest::Test
       end
     end
   end
+
+  def test_require_is_relative_to_current_file_not_source_file
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> rundoc.require "./src/a.md"
+          ```
+        EOF
+
+        dir.join("src").tap(&:mkpath).join("a.md").write <<~EOF
+          ```
+          :::-> rundoc.require "./b.md"
+          ```
+        EOF
+
+        dir.join("src").join("b.md").write <<~EOF
+          ```
+          :::-> print.text Hello World!
+          ```
+        EOF
+
+        parsed = parse_contents(
+          source_path.read,
+          source_path: source_path
+        )
+        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        assert_equal "Hello World!", actual.strip
+      end
+    end
+  end
 end

data/test/rundoc/code_commands/background_test.rb

@@ -1,11 +1,39 @@
 require "test_helper"
 
 class BackgroundTest < Minitest::Test
+  def test_stdin_with_cat_echo
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        background_start = Rundoc::CodeCommand::Background::Start.new("cat",
+          name: "cat")
+        background_start.call
+
+        output = Rundoc::CodeCommand::Background::StdinWrite.new(
+          "hello there",
+          name: "cat",
+          wait: "hello"
+        ).call
+        assert_equal("hello there" + $/, output)
+
+        Rundoc::CodeCommand::Background::Log::Clear.new(
+          name: "cat"
+        ).call
+
+        output = Rundoc::CodeCommand::Background::StdinWrite.new(
+          "general kenobi",
+          name: "cat",
+          wait: "general"
+        ).call
+        assert_equal("general kenobi" + $/, output)
+      end
+    end
+  end
+
   def test_process_spawn_gc
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         file = "foo.txt"
-        `echo 'foo' >> #{file}`
+        run!("echo 'foo' >> #{file}")
 
         background_start = Rundoc::CodeCommand::Background::Start.new("tail -f #{file}",
           name: "tail2",
@@ -30,7 +58,7 @@ class BackgroundTest < Minitest::Test
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         file = "foo.txt"
-        `echo 'foo' >> #{file}`
+        run!("echo 'foo' >> #{file}")
 
         background_start = Rundoc::CodeCommand::Background::Start.new("tail -f #{file}",
           name: "tail",
@@ -49,7 +77,7 @@ class BackgroundTest < Minitest::Test
         output = log_clear.call
         assert_equal("", output)
 
-        `echo 'bar' >> #{file}`
+        run!("echo 'bar' >> #{file}")
 
         log_read = Rundoc::CodeCommand::Background::Log::Read.new(name: "tail")
         output = log_read.call

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rundoc
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Richard Schneeman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-22 00:00:00.000000000 Z
+date: 2024-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -206,6 +206,7 @@ files:
 - lib/rundoc/code_command/background/log/read.rb
 - lib/rundoc/code_command/background/process_spawn.rb
 - lib/rundoc/code_command/background/start.rb
+- lib/rundoc/code_command/background/stdin_write.rb
 - lib/rundoc/code_command/background/stop.rb
 - lib/rundoc/code_command/background/wait.rb
 - lib/rundoc/code_command/bash.rb
@@ -261,6 +262,7 @@ files:
 - test/fixtures/screenshot/rundoc.md
 - test/fixtures/simple_git/rundoc.md
 - test/integration/after_build_test.rb
+- test/integration/background_stdin_test.rb
 - test/integration/failure_test.rb
 - test/integration/print_test.rb
 - test/integration/require_test.rb