runsheets 0.0.1

data/lib/runsheets/block.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # A fenced code block and the behaviour its info string asks for.
+  #
+  #   ```bash              display only
+  #   ```bash run          Run button
+  #   ```bash destructive  Run button behind a typed confirmation (implies run)
+  #   ```bash background   Start and Stop buttons; output streams until stopped
+  #   ```bash terminal     operator runs it in their own terminal and confirms
+  #   ```text expect       expected output of the preceding executable block
+  class Block
+    KINDS = %i[display run background destructive terminal expect].freeze
+
+    FLAG_KINDS = {
+      "run"         => :run,
+      "background"  => :background,
+      "destructive" => :destructive,
+      "terminal"    => :terminal,
+      "expect"      => :expect
+    }.freeze
+
+    # Kinds the tool spawns a process for.
+    EXECUTABLE_KINDS = %i[run destructive background].freeze
+
+    # Languages that can execute and the command that runs a file of them.
+    # A runbook can add or override entries in its front matter.
+    INTERPRETERS = {
+      "bash" => %w[bash],
+      "sh"   => %w[sh],
+      "zsh"  => %w[zsh],
+      "ruby" => %w[ruby]
+    }.freeze
+
+    attr_reader :id, :index, :lang, :flags, :code, :line, :kind, :warnings, :interpreters
+
+    # For an :expect block, the id of the executable block it illustrates
+    # (the nearest one above it). Set by Renderer once every block is known.
+    attr_accessor :expect_for
+
+    # +interpreters+ is the language => command map in force for the
+    # runbook (the defaults plus its front matter); a language outside it
+    # cannot execute whatever its flags say.
+    def initialize(id:, index:, info:, code:, line: nil, interpreters: INTERPRETERS)
+      @id           = id
+      @index        = index
+      @code         = code
+      @line         = line
+      @interpreters = interpreters
+      @lang, *@flags = info.to_s.split
+      @lang = @lang.to_s
+      @flags.freeze
+      @kind, @warnings = Block.classify(@flags, @lang, interpreters)
+    end
+
+    # The kind a set of flags asks for, plus any authoring warnings.
+    def self.classify(flags, lang, interpreters = INTERPRETERS)
+      warnings = []
+      unknown  = flags.reject { FLAG_KINDS.key?(it) }
+      warnings << "unknown flag#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
+
+      kinds = flags.filter_map { FLAG_KINDS[it] }.uniq
+      kind  = kind_for(kinds)
+      warnings << "conflicting flags: #{kinds.join(', ')}; using #{kind}" if conflicting?(kinds, kind)
+
+      if EXECUTABLE_KINDS.include?(kind) && !interpreters.key?(lang)
+        warnings << if lang.empty?
+                      "a block without a language cannot execute"
+                    else
+                      "#{lang} blocks cannot execute; displayed only (map it under interpreters in the runbook front matter)"
+                    end
+      end
+
+      [kind, warnings.freeze]
+    end
+
+    # The kind a list of flag kinds asks for, whatever their order:
+    # destructive wins, then the first kind other than run, then run.
+    def self.kind_for(kinds)
+      others = kinds - [:run]
+      if others.include?(:destructive) then :destructive
+      elsif others.any?                then others.first
+      elsif kinds.any?                 then :run
+      else                                  :display
+      end
+    end
+
+    # True when a flag asks for something +kind+ does not do. run beside
+    # destructive or background is redundant (both run); run beside
+    # terminal or expect is a contradiction.
+    def self.conflicting?(kinds, kind)
+      (kinds - [:run, kind]).any? || (kinds.include?(:run) && !EXECUTABLE_KINDS.include?(kind))
+    end
+
+    def executable?  = EXECUTABLE_KINDS.include?(kind) && interpreters.key?(lang)
+    def destructive? = kind == :destructive
+    def background?  = kind == :background
+    def terminal?    = kind == :terminal
+    def expect?      = kind == :expect
+    def display?     = kind == :display
+    def label        = flags.empty? ? lang : "#{lang} #{flags.join(' ')}"
+
+    # A short fingerprint of what the block says and does. The page sends
+    # it back with Run and I ran this, so an edit made after the page loaded
+    # cannot turn a click into a different block.
+    def digest = Digest::SHA256.hexdigest("#{label}\0#{code}")[0, 16]
+
+    # Terminal blocks are not executed; the operator confirms they ran them.
+    def acknowledgeable? = terminal?
+
+    # Names of $VARIABLES the code refers to.
+    def referenced_variables = code.scan(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/).flatten.uniq
+
+    def to_h
+      { id:, index:, lang:, flags:, kind:, line:, executable: executable?, expect_for:, warnings:, code: }
+    end
+  end
+end

data/lib/runsheets/cli.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "fileutils"
+require "socket"
+
+module Runsheets
+  # The `runsheets` command: load a runbook (a directory or a single markdown
+  # file) and serve it, check it, or scaffold a new one.
+  #
+  # Settings come from Config: bundled defaults, then the config file, then
+  # RUNSHEETS_* variables, then whatever is given on the command line.
+  module CLI
+    PROGRAM = "runsheets"
+
+    # The runbook served when none is named: the bundled hello example,
+    # found relative to this file so it works from a checkout and from an
+    # installed gem alike.
+    DEFAULT_RUNBOOK = File.expand_path("../../examples/directory_based_runbooks/hello", __dir__)
+
+    # Parse argv into a hash holding only what was given: Config attribute
+    # names for the options, :config for the config file. Raises
+    # OptionParser::ParseError on bad input; returns nil after printing help
+    # or the version.
+    def self.parse(argv, out: $stdout)
+      options  = {}
+      defaults = Config.bundled_defaults
+      parser   = OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          #{PROGRAM} #{VERSION} - executable runbooks in your browser
+
+          Usage: #{PROGRAM} [options] [RUNBOOK]
+
+          RUNBOOK is a directory holding runbook.md and a steps/ directory of
+          markdown files, a single all-in-one markdown file whose ## headings
+          are the steps, or a directory of such runbooks to choose from in the
+          browser. Without one, the bundled example is served:
+          #{DEFAULT_RUNBOOK}
+          Fenced blocks marked `bash run`, `ruby run`, `bash destructive`
+          or `bash background` get buttons. Everything from start to Ctrl-C is
+          one session, recorded with its log under #{defaults[:runs_dir]}
+
+          Settings are layered: the user config #{Config.xdg_path},
+          then ./config/runsheets.yml (or the file --config names), then the
+          environment variable named beside each option, then the command line,
+          which wins. RUNBOOK itself can be set as `dir:` in a config file or
+          with RUNSHEETS_DIR. Flags take 1, true, yes or on; --no-open,
+          --no-check and --no-init switch a flag off that a lower layer turned on.
+
+          Options:
+        BANNER
+
+        server_options(opts, options, defaults)
+        session_flags(opts, options, defaults)
+        opts.on("-v", "--version", "Print the version and exit") do
+          out.puts "#{PROGRAM} #{VERSION}"
+          return nil
+        end
+        opts.on("-h", "--help", "Show this help and exit") do
+          out.puts opts
+          return nil
+        end
+      end
+
+      rest = parser.parse(argv)
+      raise OptionParser::ParseError, "too many arguments: #{rest.join(' ')}" if rest.size > 1
+
+      options[:dir] = rest.first if rest.first
+      options
+    end
+
+    # The options about serving: config file, port, bind, records, and the
+    # one-shot actions.
+    def self.server_options(opts, options, defaults)
+      opts.on("-c", "--config FILE", "Config file to read in place of ./config/runsheets.yml [RUNSHEETS_CONFIG]") { options[:config] = it }
+      opts.on("-p", "--port PORT", Integer, "Port to listen on (default: #{defaults[:port]}) [RUNSHEETS_PORT]") { options[:port] = it }
+      opts.on("-b", "--bind HOST", "Address to bind to (default: #{defaults[:bind]}) [RUNSHEETS_BIND]") { options[:bind] = it }
+      opts.on("--runs-dir DIR", "Where run records are written (default: #{defaults[:runs_dir]}) [RUNSHEETS_RUNS_DIR]") { options[:runs_dir] = it }
+      opts.on("-o", "--[no-]open", "Open the browser once the server is up [RUNSHEETS_OPEN]") { options[:open] = it }
+      opts.on("--[no-]check", "Load the runbook, report authoring warnings, and exit [RUNSHEETS_CHECK]") { options[:check] = it }
+      opts.on("--[no-]init", "Create a new runbook skeleton at RUNBOOK (a directory, or a .md file) and exit [RUNSHEETS_INIT]") { options[:init] = it }
+      opts.on("--[no-]dump", "Print the settings in force as a config file to stdout and exit [RUNSHEETS_DUMP]") { options[:dump] = it }
+    end
+
+    # The options about the session: who, why, and its log.
+    def self.session_flags(opts, options, defaults)
+      opts.on("-e", "--engineer NAME", "Who is starting the session (default: ask) [RUNSHEETS_ENGINEER]") { options[:engineer] = it }
+      opts.on("-w", "--why TEXT", "Why: the session's first note; with --engineer, skips the start page [RUNSHEETS_WHY]") { options[:why] = it }
+      opts.on("--log-level LEVEL", "Session log level: #{SessionLog::LEVELS.join(', ')} (default: #{defaults[:log_level]}) [RUNSHEETS_LOG_LEVEL]") { options[:log_level] = it }
+      opts.on("--verbose", "Log page views, searches and polling too (--log-level debug)") { options[:log_level] = "debug" }
+      opts.on("-q", "--[no-]quiet", "Do not echo the session log to the terminal [RUNSHEETS_QUIET]") { options[:quiet] = it }
+    end
+
+    # Build the effective settings from parsed options and install them as
+    # Runsheets.config. The command line beats the environment, which beats
+    # the config file, which beats the bundled defaults.
+    def self.configure(options)
+      Runsheets.configure(options.except(:config), path: options[:config]).tap { check_bind_source(it) }
+    end
+
+    # Refuse a non-loopback bind that only the project config in the
+    # current directory asks for: a cloned repository could otherwise open
+    # runsheets to the network. --bind, RUNSHEETS_BIND, --config and the
+    # user config can still choose one.
+    def self.check_bind_source(config)
+      bind = config.project_bind
+      return if bind.nil? || Web.loopback?(bind)
+
+      raise ConfigError, "#{config.path} sets bind: #{bind}, which is not a loopback address. A project config cannot open " \
+                         "runsheets to the network; pass --bind #{bind} (or set RUNSHEETS_BIND) if that is what you want"
+    end
+
+    # --dump: print the settings in force as a config file. Redirect it to
+    # save them: `runsheets --dump -p 4580 > ~/.config/runsheets/runsheets.yml`.
+    def self.dump(config, out: $stdout)
+      out.print config.to_config_yaml
+      0
+    end
+
+    # The runbook a configuration points at: its dir, else the bundled example.
+    # --init insists on an explicit one.
+    def self.runbook_path(config)
+      if config.init && config.dir.nil?
+        raise OptionParser::ParseError, "--init needs the path of the runbook to create (RUNBOOK, dir: in the config file, or RUNSHEETS_DIR)"
+      end
+
+      config.dir || DEFAULT_RUNBOOK
+    end
+
+    # Entry point for the executable. Returns the process exit status.
+    def self.run(argv, out: $stdout, err: $stderr)
+      options = parse(argv, out:)
+      return 0 unless options
+
+      config  = configure(options)
+      return dump(config, out:) if config.dump
+
+      path    = runbook_path(config)
+      return init(path, out:) if config.init
+
+      target = Library.library?(path) ? Library.load(path) : Runbook.load(path)
+      return check(target, out:, err:) if config.check
+
+      serve(target, config, out:, err:)
+      0
+    rescue Errno::EADDRINUSE
+      err.puts "#{PROGRAM}: port #{config.port} on #{config.bind} is already in use; pick another with --port"
+      1
+    rescue OptionParser::ParseError, RunbookError, ConfigError,
+           Psych::Exception, SocketError, SystemCallError => e # also a bad config file, an unknown host, an unreadable directory
+      err.puts "#{PROGRAM}: #{e.message}"
+      1
+    end
+
+    # --check: report authoring warnings for a runbook, or for every runbook
+    # in a library, one line each. Exit 1 when anything warned or failed.
+    def self.check(target, out: $stdout, err: $stderr)
+      library  = target.is_a?(Library)
+      runbooks = library ? target.entries.map { check_entry(it, err:) } : [target]
+      runbooks.compact.each do |runbook|
+        runbook.warnings.each { err.puts "#{PROGRAM}: warning: #{"#{runbook.slug}: " if library}#{it}" }
+        out.puts "#{runbook.title}#{" [#{runbook.slug}]" if library}: #{runbook.steps.size} steps, #{runbook.warnings.size} warnings"
+      end
+      clean = runbooks.all? { it && it.warnings.empty? }
+      clean ? 0 : 1
+    end
+
+    # One library entry's runbook (as the library loaded it, with its slug),
+    # or nil and a message when it does not load.
+    def self.check_entry(entry, err: $stderr)
+      return entry.runbook if entry.ok?
+
+      err.puts "#{PROGRAM}: error: #{entry.slug}: #{entry.error}"
+      nil
+    end
+
+    # Serve a runbook, or a library of them (the operator chooses in the
+    # browser). Everything until the server stops is one session; it starts
+    # now when the engineer and why are known, else on the browser's start
+    # page.
+    def self.serve(target, config, out: $stdout, err: $stderr)
+      bind    = config.bind
+      port    = config.port
+      library = target.is_a?(Library) ? target : nil
+      runbook = library ? nil : target
+      options = session_options(config, out:)
+      session = early_session(config, library:, runbook:, options:)
+      Web.configure_for(session, bind:, port:, library:, runbook:).prepare_start(session_options: options, engineer: default_engineer(config))
+      url = SessionKey.url(bind, port, Web.settings.rs_token)
+      err.puts bind_warning(bind) unless Web.loopback?(bind)
+      runbook&.warnings&.each { err.puts "#{PROGRAM}: warning: #{it}" }
+
+      out.puts <<~INFO
+        #{PROGRAM} #{VERSION}
+        #{target_line(target)}
+        Runs:    #{Runsheets.runs_dir}
+        Config:  #{config.files.empty? ? 'none (defaults)' : config.files.join(', ')}
+        Session: #{session ? "#{session.id}, log #{session.log.path}" : 'starts in the browser (who and why)'}
+        Open #{url} in your browser
+        Press Ctrl-C to end the session and stop
+      INFO
+
+      Web.run! do
+        open_browser(url) if config.open
+      end
+    ensure
+      shutdown(Web.session) if Web.session
+    end
+
+    # Raise Errno::EADDRINUSE now when +port+ is taken, before a session and
+    # its record exist. The server binds the port again a moment later.
+    def self.ensure_port_free(bind, port) = TCPServer.new(bind, port).close
+
+    # The session, started now when --engineer and --why say who and why;
+    # nil leaves it to the start page. The port is checked first, so a
+    # start that cannot serve records no session.
+    def self.early_session(config, library:, runbook:, options:)
+      ensure_port_free(config.bind, config.port)
+      Session.new(engineer: config.engineer, why: config.why, library:, runbook:, **options) if config.engineer && config.why
+    end
+
+    # What every session this process starts is built with: where records
+    # go, the log level, and the terminal echo (none with --quiet).
+    def self.session_options(config, out: $stdout) = { runs_root: Runsheets.runs_dir, log_level: config.log_level, echo: config.quiet ? nil : out }
+
+    # Who the start page suggests: the configured engineer, else git's
+    # user.name, else the login name.
+    def self.default_engineer(config) = [config.engineer, git_user_name, ENV["USER"]].find { !it.to_s.strip.empty? }
+
+    def self.git_user_name
+      IO.popen(%w[git config user.name], err: File::NULL, &:read).strip
+    rescue SystemCallError
+      nil
+    end
+
+    def self.target_line(target)
+      if target.is_a?(Library)
+        folders = target.folders.size
+        where   = folders.positive? ? " in #{folders} folder#{'s' unless folders == 1}" : ""
+        "Library: #{target.size} runbook#{'s' unless target.size == 1}#{where} under #{target.dir}"
+      else
+        "Runbook: #{target.title} (#{target.single_file? ? target.main_path : target.dir})"
+      end
+    end
+
+    # When the server stops (Ctrl-C, End session, or an error), end the
+    # session: every run is closed with the status its work earns and
+    # nothing it started is left running. Ending twice does nothing.
+    def self.shutdown(session) = session.end!("runsheets stopped")
+
+    def self.bind_warning(bind)
+      <<~WARN.chomp
+        #{PROGRAM}: warning: binding to #{bind}, which is not a loopback address.
+        Anyone who can reach this address and guess the session token can run blocks as you.
+        #{Web.wildcard?(bind) ? 'The Host header check is off for a wildcard bind.' : 'Only requests with this address in the Host header are accepted.'}
+      WARN
+    end
+
+    def self.open_browser(url)
+      command = case RUBY_PLATFORM
+                when /darwin/ then ["open", url]
+                when /mswin|mingw/ then ["cmd", "/c", "start", url]
+                else ["xdg-open", url]
+                end
+      Process.spawn(*command, %i[out err] => File::NULL)
+    rescue SystemCallError
+      nil
+    end
+
+    # --- scaffolding -------------------------------------------------------
+
+    # Write a starter runbook. A path ending in .md gets the single-file
+    # shape; anything else becomes a directory. Refuses to touch an existing
+    # file or a non-empty directory. Returns the exit status.
+    def self.init(path, out: $stdout)
+      files = scaffold(path)
+      raise RunbookError, "#{path} already exists" if File.file?(path)
+      raise RunbookError, "#{path} exists and is not empty" if File.directory?(path) && !Dir.empty?(path)
+
+      files.each do |rel, text|
+        full = rel.start_with?("/") ? rel : File.join(path, rel)
+        FileUtils.mkdir_p(File.dirname(full))
+        File.write(full, text)
+        out.puts "created #{full}"
+      end
+      out.puts "Next: #{PROGRAM} --check #{path}"
+      0
+    end
+
+    # The files a new runbook starts with, keyed by path. For a single-file
+    # runbook the one key is the absolute path itself.
+    def self.scaffold(path)
+      name  = File.basename(path, ".*")
+      title = name.tr("-_", " ").capitalize
+      if path.end_with?(".md")
+        { path => single_file_template(title) }
+      else
+        {
+          "runbook.md" => runbook_template(title),
+          "steps/010-first-step.md" => <<~MD,
+            ---
+            title: First step
+            kind: automated
+            timeout: 300
+            ---
+
+            Say what this step does and why it is here. Then the command:
+
+            ```bash run
+            echo "hello from #{name}"
+            ```
+
+            How to tell it worked:
+
+            ```text expect
+            hello from #{name}
+            ```
+          MD
+          "steps/020-a-manual-step.md" => <<~MD,
+            ---
+            title: A manual step
+            kind: manual
+            ---
+
+            An instruction the operator carries out and then acknowledges.
+          MD
+          "verify.md" => <<~MD,
+            ---
+            title: Verify
+            kind: verify
+            ---
+
+            Whole-procedure checks. These should pass after every run.
+
+            ```bash run
+            test -n "$EXAMPLE_INPUT" && echo "EXAMPLE_INPUT is set"
+            ```
+          MD
+          "rollback.md" => <<~MD
+            ---
+            title: Rollback
+            ---
+
+            What to do when it fails partway. This panel sits in the sidebar of
+            every step.
+          MD
+        }
+      end
+    end
+
+    def self.runbook_template(title)
+      <<~MD
+        ---
+        title: #{title.to_json}
+        when_to_use: >
+          One or two sentences on the situation this runbook is for.
+        prerequisites:
+          - What must be true or installed before starting
+        escalation: Who to call when a step fails
+        tags: []
+        inputs:
+          - name: EXAMPLE_INPUT
+            prompt: An example input, exported as $EXAMPLE_INPUT
+            default: example
+        ---
+
+        # #{title}
+
+        Everything above the first step is the preamble: what this procedure does,
+        what it touches, and what the operator should know before starting.
+      MD
+    end
+
+    def self.single_file_template(title)
+      <<~MD
+        ---
+        title: #{title.to_json}
+        when_to_use: >
+          One or two sentences on the situation this runbook is for.
+        prerequisites:
+          - What must be true or installed before starting
+        escalation: Who to call when a step fails
+        inputs:
+          - name: EXAMPLE_INPUT
+            prompt: An example input, exported as $EXAMPLE_INPUT
+            default: example
+        ---
+
+        # #{title}
+
+        Everything above the first `##` heading is the preamble. Each `##` heading
+        below is a step. Step attributes go in an HTML comment right after the
+        heading.
+
+        ## First step
+        <!-- kind: automated, timeout: 300 -->
+
+        Say what this step does and why it is here. Then the command:
+
+        ```bash run
+        echo "hello from $EXAMPLE_INPUT"
+        ```
+
+        ## A manual step
+        <!-- kind: manual -->
+
+        An instruction the operator carries out and then acknowledges.
+
+        ## Verify
+
+        Whole-procedure checks. A section headed Verify plays the part of verify.md.
+
+        ```bash run
+        test -n "$EXAMPLE_INPUT" && echo "EXAMPLE_INPUT is set"
+        ```
+
+        ## Rollback
+
+        What to do when it fails partway. A section headed Rollback sits in the
+        sidebar of every step.
+      MD
+    end
+  end
+end

data/lib/runsheets/config/defaults.yml

@@ -0,0 +1,44 @@
+# Bundled defaults for the runsheets command. This file is the lowest layer;
+# every key here is a setting. Higher layers override it, lowest to highest:
+#
+#   ~/.config/runsheets/runsheets.yml      XDG user config (myway_config)
+#   ./config/runsheets.yml                 project config, or the file --config / RUNSHEETS_CONFIG names
+#   RUNSHEETS_<KEY>                        environment variables
+#   command-line options                   -p, --bind, --runs-dir, ...
+#
+# Paths may start with ~. Flags accept true/false, yes/no, on/off or 1/0.
+defaults:
+  # The runbook to serve: a directory holding runbook.md, or a single .md
+  # file. Empty means the bundled examples/directory_based_runbooks/hello. (RUNBOOK argument, RUNSHEETS_DIR)
+  dir:
+  # Port to listen on. (--port, RUNSHEETS_PORT)
+  port: 4567
+  # Address to bind to. Anything but loopback exposes shell execution. (--bind, RUNSHEETS_BIND)
+  bind: 127.0.0.1
+  # Where run records are written. (--runs-dir, RUNSHEETS_RUNS_DIR)
+  runs_dir: ~/.local/share/runsheets/runs
+  # Open the browser once the server is up. (--open, RUNSHEETS_OPEN)
+  open: false
+  # Load the runbook, report authoring warnings, and exit. (--check, RUNSHEETS_CHECK)
+  check: false
+  # Create a runbook skeleton at dir and exit. (--init, RUNSHEETS_INIT)
+  init: false
+  # Print the settings in force as a config file to stdout and exit. (--dump, RUNSHEETS_DUMP)
+  dump: false
+  # Who is starting the session. Empty means ask, prefilled from
+  # `git config user.name`, then $USER. (--engineer, RUNSHEETS_ENGINEER)
+  engineer:
+  # Why the session is being started: its first note. With engineer set too,
+  # the start page is skipped. Never saved by --dump. (--why, RUNSHEETS_WHY)
+  why:
+  # The session log's level: debug, info, warn, error or fatal.
+  # (--log-level, --verbose for debug, RUNSHEETS_LOG_LEVEL)
+  log_level: info
+  # Do not echo the session log to the terminal. (--quiet, RUNSHEETS_QUIET)
+  quiet: false
+
+# Per-environment overrides (RACK_ENV). None are needed; the sections exist
+# so myway_config recognises the usual environment names.
+development: {}
+test: {}
+production: {}