runsheets 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b4caf43ab35c8816f90d794e6dba06e3fd3644cd838c89c9987bbe0f60ab786
-  data.tar.gz: 39cd9610b55e341bc1b664443a509a2269f7397c190e28f38fcbcc6c9287f2db
+  metadata.gz: 92cd3b7a77a52879a46fe002837ab2c7f0df600865eed44ed31f6b2b75491ff3
+  data.tar.gz: e70a7b616393d87c1d6fa83e4952e73da0f33da1dd3aab454aa774f03ac197aa
 SHA512:
-  metadata.gz: cec8d91aa87096dfae4548d1eb39df3c9b6d57e0d2176d24e12550f9ff7a21c0487e0f850b7fd0c5fd9178f7cd471057e40771c3a2918b897ec7f57fa63b1282
-  data.tar.gz: 2d960f098334bf2b7900eae5084c1fa722a27b6c115d6da26e4020e4cd9b5c32a546d265ba448a36d4bbb6dfcfdb730ae16d7ab0b3112ae6308d341f54c16ba0
+  metadata.gz: 2737dd58316509fb19cf8897b41d3983d538011a64725bd7320fd0e61429e42664063894d0e6f5e70acfd3078df4c222b07fb6552b249b7c6aef7b7978fa224c
+  data.tar.gz: aee18d7c0923c297ec38ffa5ffe6b28b59a75a9b19831c3a48c42168ea0b099edd13955fdaadbdd01c1ded1a599e936c1dbddbe19bdf603b04bdb6245a18c8d4

data/Archspec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Executable architecture for runsheets, checked by the archspec gem:
+#
+#   archspec check
+#   archspec explain lib/runsheets/session.rb
+#
+# docs/reference/architecture.md describes the design; this file enforces it.
+# runsheets is a gem: a document model, an execution layer, a record writer,
+# a session over them, and two front ends (a Sinatra app and the terminal)
+# wired together by the CLI. Dependencies point inward only:
+#
+#   cli ─┬─> routes ─> pages ─┐
+#        └─> console ─────────┴─> session ─┬─> execution ─┐
+#                                          ├─> recording ─┤
+#                                          └─> document ──┴─> foundation
+#
+# Pages and routes may also read the document and recording layers directly
+# (rendering, history); nothing outside session reaches execution.
+
+root "."
+source "lib/**/*.rb"
+
+# Known violations, burned down rather than allowed: refresh with
+# `archspec check --update-todo` only after fixing one.
+todo "archspec_todo.yml"
+
+# Shared building blocks with no runsheets dependencies beyond each other:
+# the Runsheets module itself, settings, parsing helpers, the redactor, and the
+# session log (a plain Logger wrapper that Config borrows LEVELS from).
+component :foundation, in: %w[
+  lib/runsheets.rb
+  lib/runsheets/version.rb
+  lib/runsheets/config.rb
+  lib/runsheets/front_matter.rb
+  lib/runsheets/fences.rb
+  lib/runsheets/slug.rb
+  lib/runsheets/block.rb
+  lib/runsheets/diff.rb
+  lib/runsheets/expectation.rb
+  lib/runsheets/redactor.rb
+  lib/runsheets/session_log.rb
+]
+
+# The document model: markdown files rendered into steps, runbooks, libraries.
+component :document, in: %w[
+  lib/runsheets/renderer.rb
+  lib/runsheets/step.rb
+  lib/runsheets/single_file.rb
+  lib/runsheets/runbook.rb
+  lib/runsheets/library.rb
+  lib/runsheets/search.rb
+]
+
+# Spawning, pumping, reaping and timing out a block's process.
+component :execution, in: %w[
+  lib/runsheets/execution.rb
+  lib/runsheets/executor.rb
+]
+
+# The runsheet: run.json, run.md and blocks/ on disk.
+component :recording, in: %w[lib/runsheets/run_record.rb]
+
+# The engineering session and each runbook's run inside it.
+component :session, in: %w[
+  lib/runsheets/run.rb
+  lib/runsheets/session.rb
+]
+
+# Pure functions from a session to HTML, plus the inline CSS and JavaScript.
+component :pages, in: %w[
+  lib/runsheets/pages.rb
+  lib/runsheets/pages/**/*.rb
+  lib/runsheets/assets.rb
+]
+
+# The Sinatra app: routes and the host/token security checks.
+component :routes, in: %w[lib/runsheets/web.rb]
+
+# Terminal front end: prompts, templates, --new and --run.
+component :console, in: %w[
+  lib/runsheets/prompt.rb
+  lib/runsheets/template.rb
+  lib/runsheets/wizard.rb
+  lib/runsheets/step_runner.rb
+]
+
+# Option parsing and the bin/runsheets entry point; the composition root.
+component :cli, in: %w[lib/runsheets/cli.rb]
+
+# ── Layering ────────────────────────────────────────────────────────────────
+
+foundation.can_only_use(because: "the foundation is shared by every layer and depends on none")
+document.can_only_use :foundation,
+                      because: "the document model is tested in isolation and knows nothing of runs or front ends"
+execution.can_only_use :foundation,
+                       because: "the executor runs code it is handed; it does not know runbooks, records or sessions"
+recording.can_only_use :foundation,
+                       because: "run records are plain data on disk, readable without a live session"
+session.can_only_use :foundation, :document, :execution, :recording,
+                     because: "the session sits over the model and knows nothing of HTTP or the terminal"
+pages.can_only_use :foundation, :document, :recording, :session,
+                   because: "pages render a session; they never touch processes or routes"
+routes.can_only_use :foundation, :document, :recording, :session, :pages,
+                    because: "routes talk to the session and render through Pages; execution goes through the session"
+console.can_only_use :foundation, :document, :session,
+                     because: "terminal flows run steps through the session, never the web layer"
+cli.can_only_use :foundation, :document, :session, :pages, :routes, :console,
+                 because: "the CLI wires the front ends together"
+
+no_cycles
+
+# ── Third-party boundaries ──────────────────────────────────────────────────
+#
+# Each library stays behind the component that owns it: the web stack behind
+# routes (and Rack::Utils for escaping in pages), kramdown and rouge behind
+# Renderer, myway_config behind Config. The model loads without Sinatra.
+
+VENDORS = {
+  %w[Sinatra Puma Rackup] => %i[routes],
+  %w[Rack]                => %i[routes pages],
+  %w[Kramdown Rouge]      => %i[document],
+  %w[MywayConfig Anyway]  => %i[foundation]
+}.freeze
+
+vendor_reason = "third-party libraries are reached only through the component that owns them"
+%i[foundation document execution recording session pages routes console cli].each do |layer|
+  forbidden = VENDORS.reject { |_, owners| owners.include?(layer) }.keys.flatten
+  send(layer).cannot_reference_constants(*forbidden, because: vendor_reason)
+end
+
+# ── Process control ─────────────────────────────────────────────────────────
+
+spawn_reason = "only Executor spawns runbook code, so every execution is recorded and redacted"
+%i[foundation document recording session pages routes console].each do |layer|
+  send(layer).cannot_call(:spawn, :exec, :system, :popen, :popen3, :capture2, :capture3, because: spawn_reason)
+end

data/CHANGELOG.md

@@ -1,6 +1,40 @@
 # Changelog
 
-## [Unreleased]
+## [0.0.2] - Unreleased
+
+### Added
+
+- `runsheets --new [DIR]` asks what kind of runbook to make (a directory or a
+  single file, a template, a name, a title, when to use it and who to call)
+  and writes it into `DIR`. Enter accepts each default, and answers can be
+  piped in. Without `DIR` it asks for one, offering the `dir:` a config file
+  sets, else `RUNSHEETS_DIR`.
+- Runbook templates in `templates/`, a ladder of structure: `checks` (checks
+  only), `tasks` (checks and tasks, the default), `rollback`, `timeouts`,
+  `inputs` and `asgard` (tasks in `.loki` files beside the runbook). Each is
+  written once as a directory runbook and produces either shape; a single
+  file from a template with support files gets a folder of its own.
+- `runsheets --run [STEP] RUNBOOK` runs one step at the terminal (listing the
+  steps to choose from when `STEP` is left out), recorded in a session like
+  a run from the page, and exits non-zero if the step fails.
+  `--engineer` and `--why` are required. It asks for the runbook's inputs
+  first, Enter keeping each one's value. A destructive block still needs
+  its confirmation code typed, a terminal block or manual step asks to be
+  confirmed, and a step with a background block is refused. Name a step by
+  its name or slug, or `verify`, `rollback` or `runbook`; `--run verify` is
+  a health check. `STEP` is never a number: numbers are only places in the
+  list shown when `STEP` is left out. Exits 0 on success, 1 on failure and
+  130 on Ctrl-C.
+- A relative `RUNBOOK` not found from the current directory is looked for
+  under the `dir:` a config file sets, else `RUNSHEETS_DIR`.
+- `--check` warns about a numbered step named like `verify.md`,
+  `rollback.md` or the landing page (`030-verify`), since `--run verify`
+  runs `verify.md`.
+
+### Removed (breaking)
+
+- `--init`, `--no-init`, `RUNSHEETS_INIT` and the `init` setting. Use
+  `--new`; the `tasks` template is the nearest to what `--init` wrote.
 
 ## [0.0.1] - 2026-10-11
 

data/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MadBomber/runsheets/main/docs/assets/images/logo.png" alt="runsheets logo: a smiling runsheet sprinting beside the runsheets wordmark" width="620">
+</p>
+
 # runsheets
 
 > **Note:** This is a proof-of-concept and a work in progress. Features,
@@ -47,7 +51,7 @@ runsheets path/to/runbook.md      # serve a single all-in-one markdown file
 runsheets path/to/runbooks        # a directory of runbooks: choose one in the browser
 runsheets --open path/to/runbook  # and open the browser
 runsheets --check path/to/runbook # load it, print authoring warnings, exit
-runsheets --init path/to/new      # scaffold a runbook (a .md path makes a single file)
+runsheets --new path/to/runbooks  # answer a few questions, get a runbook from a template
 ```
 
 The argument is one of three things: a runbook directory, a single
@@ -76,11 +80,11 @@ runsheets --open examples/single_md_file_runbooks/disk-space-triage.md # links t
 
 Options: `--port`, `--bind` (default loopback), `--runs-dir` (where run
 records go; default `~/.local/share/runsheets/runs`), `--open`, `--check`,
-`--init`, `--config FILE`, `--dump` to print the settings in force as a
+`--new [DIR]`, `--run [STEP]` to run one step at the terminal (by its name or slug), `--config FILE`, `--dump` to print the settings in force as a
 config file (redirect it to save them), and for the session `--engineer`,
 `--why`, `--log-level`, `--verbose` and `--quiet`. Settings are layered: the command line beats
 `RUNSHEETS_*` environment variables (`RUNSHEETS_PORT`, `RUNSHEETS_DIR` for
-the runbook, ...), which beat `./config/runsheets.yml` (or the file `--config` or
+the runbook, under which a relative `RUNBOOK` is also looked for, ...), which beat `./config/runsheets.yml` (or the file `--config` or
 `RUNSHEETS_CONFIG` names), which beats `~/.config/runsheets/runsheets.yml`,
 which beats the defaults bundled in `lib/runsheets/config/defaults.yml`. See
 [docs/running/cli.md](docs/running/cli.md#settings).

data/archspec_todo.yml

@@ -0,0 +1,32 @@
+---
+violations:
+- id: bd6f748ea23f791211b2342d
+  rule: dependencies.no_cycles
+  path: lib/runsheets/cli.rb
+  line: 322
+  message: 'component dependency cycle: cli -> console -> cli'
+- id: 4af0bc5913dc3dfbdd2512bc
+  rule: dependencies.allow
+  path: lib/runsheets/pages.rb
+  line: 648
+  message: pages may not depend on routes
+- id: 542009c67c4ebffeb4d329f7
+  rule: dependencies.no_cycles
+  path: lib/runsheets/pages.rb
+  line: 648
+  message: 'component dependency cycle: pages -> routes -> pages'
+- id: 4af0bc5913dc3dfbdd2512bc
+  rule: dependencies.allow
+  path: lib/runsheets/pages.rb
+  line: 651
+  message: pages may not depend on routes
+- id: 5521b0d9be73ab02461a4abe
+  rule: dependencies.allow
+  path: lib/runsheets/wizard.rb
+  line: 237
+  message: console may not depend on cli
+- id: 5521b0d9be73ab02461a4abe
+  rule: dependencies.allow
+  path: lib/runsheets/wizard.rb
+  line: 238
+  message: console may not depend on cli

data/lib/runsheets/cli.rb

@@ -6,7 +6,7 @@ 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.
+  # file) and serve it or check it; or ask some questions and write a new one.
   #
   # Settings come from Config: bundled defaults, then the config file, then
   # RUNSHEETS_* variables, then whatever is given on the command line.
@@ -22,7 +22,7 @@ module Runsheets
     # 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)
+    def self.parse(argv, out: $stdout, cwd: Dir.pwd)
       options  = {}
       defaults = Config.bundled_defaults
       parser   = OptionParser.new do |opts|
@@ -30,6 +30,8 @@ module Runsheets
           #{PROGRAM} #{VERSION} - executable runbooks in your browser
 
           Usage: #{PROGRAM} [options] [RUNBOOK]
+                 #{PROGRAM} --new [DIR]
+                 #{PROGRAM} --run [STEP] --engineer NAME --why TEXT [RUNBOOK]
 
           RUNBOOK is a directory holding runbook.md and a steps/ directory of
           markdown files, a single all-in-one markdown file whose ## headings
@@ -44,8 +46,8 @@ module Runsheets
           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.
+          with RUNSHEETS_DIR. Flags take 1, true, yes or on; --no-open and
+          --no-check switch a flag off that a lower layer turned on.
 
           Options:
         BANNER
@@ -64,11 +66,28 @@ module Runsheets
 
       rest = parser.parse(argv)
       raise OptionParser::ParseError, "too many arguments: #{rest.join(' ')}" if rest.size > 1
+      raise OptionParser::ParseError, "--new takes the directory to create the runbook in; give no RUNBOOK with it" if options.key?(:new) && rest.any?
+      raise OptionParser::ParseError, "--run and --new cannot be used together" if options.key?(:new) && options.key?(:run)
 
+      rest = runbook_taken_by_run(options, rest, cwd:)
       options[:dir] = rest.first if rest.first
       options
     end
 
+    # --run's step is optional, so in `--run db-refresh` it takes the
+    # runbook as the step. A value with a / or ending in .md, or that names
+    # something in +cwd+, is no step name: when nothing else was given as
+    # RUNBOOK it is moved there, and the step is asked for. Returns the
+    # arguments left over.
+    def self.runbook_taken_by_run(options, rest, cwd: Dir.pwd)
+      value = options[:run]
+      return rest unless rest.empty? && value
+      return rest unless value.include?("/") || value.end_with?(".md") || File.exist?(File.join(cwd, value))
+
+      options[:run] = nil
+      [value]
+    end
+
     # The options about serving: config file, port, bind, records, and the
     # one-shot actions.
     def self.server_options(opts, options, defaults)
@@ -78,7 +97,9 @@ module Runsheets
       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("--new [DIR]", "Ask what kind of runbook to make, write it from a template into DIR (asked for when left out), and exit") { options[:new] = it }
+      opts.on("--run [STEP]", "Run one step of RUNBOOK at the terminal, named by its slug or name (or verify, rollback, runbook); " \
+                              "left out, choose it by number from a list. Needs -e and -w") { options[:run] = it }
       opts.on("--[no-]dump", "Print the settings in force as a config file to stdout and exit [RUNSHEETS_DUMP]") { options[:dump] = it }
     end
 
@@ -117,27 +138,37 @@ module Runsheets
       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
+    # The RUNBOOK argument as a path. A relative one is found from the
+    # current directory, else under +base+: the dir RUNSHEETS_DIR or a
+    # config file sets (or the directory of a single-file runbook it
+    # names). Raises RunbookError naming both places when neither has it.
+    def self.resolve_runbook(arg, base:, cwd: Dir.pwd)
+      here = Config.expand_path(arg, cwd)
+      return here if File.exist?(here) || base.nil? || Pathname.new(arg).absolute? || arg.start_with?("~")
 
-      config.dir || DEFAULT_RUNBOOK
+      base  = File.dirname(base) if File.file?(base)
+      under = Config.expand_path(arg, base)
+      return under if File.exist?(under)
+
+      raise RunbookError, "no such runbook: #{here}, nor #{under} under the runbook directory #{base}"
     end
 
+    # The runbook a configuration points at: its dir, else the bundled example.
+    def self.runbook_path(config) = config.dir || DEFAULT_RUNBOOK
+
     # Entry point for the executable. Returns the process exit status.
-    def self.run(argv, out: $stdout, err: $stderr)
+    # --new and --run read their answers from +input+.
+    def self.run(argv, out: $stdout, err: $stderr, input: $stdin)
       options = parse(argv, out:)
       return 0 unless options
+      return new_runbook(options[:new], default: configured_runbook_dir(offline_config(options)), input:, out:) if options.key?(:new)
 
-      config  = configure(options)
+      config = options.key?(:run) ? offline_config(options) : configure(options)
+      config.dir = resolve_runbook(options[:dir], base: configured_runbook_dir(config)) if options[:dir]
+      return run_step(options[:run], config, input:, out:) if options.key?(:run)
       return dump(config, out:) if config.dump
 
-      path    = runbook_path(config)
-      return init(path, out:) if config.init
-
+      path   = runbook_path(config)
       target = Library.library?(path) ? Library.load(path) : Runbook.load(path)
       return check(target, out:, err:) if config.check
 
@@ -146,7 +177,7 @@ module Runsheets
     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,
+    rescue OptionParser::ParseError, RunbookError, RunError, ConfigError,
            Psych::Exception, SocketError, SystemCallError => e # also a bad config file, an unknown host, an unreadable directory
       err.puts "#{PROGRAM}: #{e.message}"
       1
@@ -225,7 +256,9 @@ module Runsheets
 
     # 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.default_engineer(config, env: ENV, git_name: git_user_name)
+      [config.engineer, git_name, env["USER"]].find { !it.to_s.strip.empty? }
+    end
 
     def self.git_user_name
       IO.popen(%w[git config user.name], err: File::NULL, &:read).strip
@@ -267,158 +300,59 @@ module Runsheets
       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
+    # The settings for --new and --run. Nothing is served, so a project
+    # config that binds to the network is no concern.
+    def self.offline_config(options) = Runsheets.configure(options.except(:config, :new, :run), path: options[:config])
+
+    # The runbook directory the settings name, apart from the command line:
+    # the dir a config file sets, else $RUNSHEETS_DIR, else nil. A dir
+    # naming a single-file runbook gives the directory it is in. --new
+    # offers it when given no directory, and a relative RUNBOOK not found
+    # from the current directory is looked for under it.
+    def self.configured_runbook_dir(config, env: ENV)
+      dir = config.file_dir
+      dir ||= Config.expand_path(env["RUNSHEETS_DIR"].strip) unless Config.blank?(env["RUNSHEETS_DIR"])
+      dir && File.file?(dir) ? File.dirname(dir) : dir
     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
+    # --new: ask what kind of runbook to make and write it into +dir+; with
+    # no dir, ask for that too, offering +default+. Ctrl-C at a question
+    # creates nothing. Returns the exit status.
+    def self.new_runbook(dir, default: nil, input: $stdin, out: $stdout)
+      Wizard.new(dir, input:, output: out, default_parent: default).run
+    rescue Interrupt
+      out.puts "", Wizard::CANCELLED
+      130
     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
+    # --run: run one step of the configured runbook at the terminal, in a
+    # session of its own that ends when the step does. The engineer and why
+    # are required, since nobody is at a start page to give them. Ctrl-C
+    # stops what is running. Returns the exit status.
+    def self.run_step(name, config, input: $stdin, out: $stdout)
+      raise ConfigError, "--run needs --engineer and --why: the run is recorded with who ran it and why" unless config.engineer && config.why
+
+      runbook = run_step_runbook(runbook_path(config))
+      step    = name ? StepRunner.find_step(runbook, name) : StepRunner.choose_step(runbook, input:, output: out)
+      runner  = StepRunner.new(runbook:, step:, input:, output: out)
+      session = Session.new(engineer: config.engineer, why: config.why, runbook:, **session_options(config, out:))
+      status  = runner.run(session)
+      ending  = status.zero? ? "succeeded" : "failed"
+      status
+    rescue Interrupt
+      ending = "was interrupted"
+      out.puts "", "Interrupted."
+      130
+    ensure
+      session&.end!("runsheets --run #{step.slug} #{ending || 'stopped on an error'}")
     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
+    # The runbook at +path+ for --run, which runs a step of one runbook and
+    # so cannot be given a library.
+    def self.run_step_runbook(path)
+      raise RunbookError, "--run needs a runbook, not a library of them: #{path}" if Library.library?(path)
 
-        What to do when it fails partway. A section headed Rollback sits in the
-        sidebar of every step.
-      MD
+      Runbook.load(path)
     end
   end
 end

data/lib/runsheets/config/defaults.yml

@@ -21,8 +21,6 @@ defaults:
   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