runsheets 0.0.1

data/lib/runsheets.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require "json"
+require "pathname"
+require "securerandom"
+require "shellwords"
+require "time"
+require "yaml"
+
+require_relative "runsheets/version"
+
+# runsheets: executable runbooks served from a local web page.
+#
+# A runbook is a directory of markdown files, or a single file (see Runbook).
+# Fenced code blocks that opt in through their info string (see Block) can be
+# executed from the browser; everything that happens during a run is captured
+# into a RunRecord, the runsheet.
+#
+# The web layer (Web, Pages, Assets) and the command line (CLI) are loaded on
+# demand so the model can be used without Sinatra.
+module Runsheets
+  class Error < StandardError; end
+  class RunbookError < Error; end
+  class RunError < Error; end
+
+  autoload :Assets, File.expand_path("runsheets/assets", __dir__)
+  autoload :CLI,    File.expand_path("runsheets/cli", __dir__)
+  autoload :Pages,  File.expand_path("runsheets/pages", __dir__)
+  autoload :Web,    File.expand_path("runsheets/web", __dir__)
+
+  class << self
+    attr_writer :runs_dir
+
+    # The settings in force (see Config). Until configure is called they come
+    # from the config file, the environment and the bundled defaults.
+    def config = @config ||= Config.new
+
+    # Build and install the settings; overrides beat every other layer and
+    # path names the config file. The CLI calls this with what it parsed.
+    def configure(overrides = nil, path: nil) = @config = Config.new(overrides, path:)
+
+    # Forget the installed settings so the next call to config rebuilds them.
+    def reset_config! = @config = nil
+
+    # Where run records are written: an explicit assignment, else the
+    # configured runs_dir (--runs-dir, RUNSHEETS_RUNS_DIR, config file).
+    def runs_dir = @runs_dir || config.runs_dir
+
+    # Write +text+ to +path+ through a temporary file renamed into place, so
+    # a reader (or a crash) never sees half a record.
+    def write_atomic(path, text)
+      tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+      File.write(tmp, text)
+      File.rename(tmp, path)
+    ensure
+      File.delete(tmp) if tmp && File.exist?(tmp)
+    end
+
+    # The last +bytes+ of a file as UTF-8 text ("" when it is missing), so a
+    # page never reads a whole multi-gigabyte output or log.
+    def read_tail(path, bytes)
+      return "" unless path && File.file?(path)
+
+      size = File.size(path)
+      File.binread(path, [bytes, size].min, [size - bytes, 0].max).force_encoding("UTF-8").scrub
+    end
+  end
+end
+
+require_relative "runsheets/config"
+require_relative "runsheets/front_matter"
+require_relative "runsheets/fences"
+require_relative "runsheets/block"
+require_relative "runsheets/renderer"
+require_relative "runsheets/step"
+require_relative "runsheets/single_file"
+require_relative "runsheets/runbook"
+require_relative "runsheets/library"
+require_relative "runsheets/search"
+require_relative "runsheets/diff"
+require_relative "runsheets/expectation"
+require_relative "runsheets/redactor"
+require_relative "runsheets/execution"
+require_relative "runsheets/executor"
+require_relative "runsheets/run_record"
+require_relative "runsheets/session_log"
+require_relative "runsheets/run"
+require_relative "runsheets/session"

data/sig/runsheets.rbs

@@ -0,0 +1,4 @@
+module Runsheets
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,226 @@
+--- !ruby/object:Gem::Specification
+name: runsheets
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.4'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: myway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  runsheets turns a directory of markdown files into an executable runbook served
+  from a local web page. Fenced code blocks the author marks as runnable get a Run
+  button; every execution, its output, exit status and timing, and every operator
+  acknowledgement is captured in order into a run record (the runsheet). The tool
+  binds to loopback only, executes only blocks that opt in, and modifies nothing in
+  the runbook directory.
+email:
+- dewayne@vanhoozer.me
+executables:
+- runsheets
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/runsheets
+- examples/about-the-examples.md
+- examples/directory_based_runbooks/hello/rollback.md
+- examples/directory_based_runbooks/hello/runbook.md
+- examples/directory_based_runbooks/hello/steps/010-say-hello.md
+- examples/directory_based_runbooks/hello/steps/020-inspect-ruby.md
+- examples/directory_based_runbooks/hello/steps/030-take-a-breath.md
+- examples/directory_based_runbooks/hello/steps/035-keep-a-clock-running.md
+- examples/directory_based_runbooks/hello/steps/040-exercise-failure.md
+- examples/directory_based_runbooks/hello/steps/045-check-the-greeting.md
+- examples/directory_based_runbooks/hello/verify.md
+- examples/directory_based_runbooks/staging-teardown/rollback.md
+- examples/directory_based_runbooks/staging-teardown/runbook.md
+- examples/directory_based_runbooks/staging-teardown/steps/010-confirm-nothing-to-preserve.md
+- examples/directory_based_runbooks/staging-teardown/steps/020-snapshot-the-database.md
+- examples/directory_based_runbooks/staging-teardown/steps/030-stop-the-pipeline.md
+- examples/directory_based_runbooks/staging-teardown/steps/040-drain-the-ecs-services.md
+- examples/directory_based_runbooks/staging-teardown/steps/050-record-the-final-row-counts.md
+- examples/directory_based_runbooks/staging-teardown/steps/060-delete-the-stack.md
+- examples/directory_based_runbooks/staging-teardown/verify.md
+- examples/single_md_file_runbooks/db-maintenance.md
+- examples/single_md_file_runbooks/disk-space-triage.md
+- examples/single_md_file_runbooks/disk-usage-glossary.md
+- examples/single_md_file_runbooks/policies/cleanup-policy.md
+- examples/single_md_file_runbooks/policies/images/triage-flow.svg
+- examples/single_md_file_runbooks/runbooks_with_scripts/.loki
+- examples/single_md_file_runbooks/runbooks_with_scripts/asgard-tasks.md
+- examples/single_md_file_runbooks/runbooks_with_scripts/checks.loki
+- examples/single_md_file_runbooks/runbooks_with_scripts/greet.loki
+- lib/runsheets.rb
+- lib/runsheets/assets.rb
+- lib/runsheets/block.rb
+- lib/runsheets/cli.rb
+- lib/runsheets/config.rb
+- lib/runsheets/config/defaults.yml
+- lib/runsheets/diff.rb
+- lib/runsheets/execution.rb
+- lib/runsheets/executor.rb
+- lib/runsheets/expectation.rb
+- lib/runsheets/fences.rb
+- lib/runsheets/front_matter.rb
+- lib/runsheets/library.rb
+- lib/runsheets/pages.rb
+- lib/runsheets/pages/chooser.rb
+- lib/runsheets/pages/search.rb
+- lib/runsheets/pages/tree.rb
+- lib/runsheets/redactor.rb
+- lib/runsheets/renderer.rb
+- lib/runsheets/run.rb
+- lib/runsheets/run_record.rb
+- lib/runsheets/runbook.rb
+- lib/runsheets/search.rb
+- lib/runsheets/session.rb
+- lib/runsheets/session_log.rb
+- lib/runsheets/single_file.rb
+- lib/runsheets/step.rb
+- lib/runsheets/version.rb
+- lib/runsheets/web.rb
+- sig/runsheets.rbs
+homepage: https://github.com/madbomber/runsheets
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/madbomber/runsheets
+  source_code_uri: https://github.com/madbomber/runsheets
+  changelog_uri: https://github.com/madbomber/runsheets/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/madbomber/runsheets/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: 'Executable runbooks: markdown steps rendered in the browser, run and recorded.'
+test_files: []