ruby_raider 4.0.1 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d516f44eddaa410a882fb64a08755338486c30d9eca4755f97c1716f5b5754ca
-  data.tar.gz: de1a0fd5c654301482a09830072991d89793e117092bd23515b44e3e8f428c90
+  metadata.gz: df32b6a642777030f39db11a96cc9a85a5f59fce1528e9d096f2acd5e6bca3f9
+  data.tar.gz: 49713a619c80897c37b68e91c0c3b5acff9917fe9d850cbfde2fa6827345914b
 SHA512:
-  metadata.gz: f580ff7a46dd54bc6c792d273045e1041e5bd29dceb302468f909661b4f52fbb837786765e3cb65d701526d7c3ab75aacbfa730ae677a0d8443448a292b667c7
-  data.tar.gz: bf9a38d296a6b08ff3f2154e35168d75045431076c65a4a9ea376a4c3a76d928c163d5d5b840dc22ab7444c88e2021a7f66157b2760c84eb40a064a9941b98d6
+  metadata.gz: 02fea0f644525a60e0cbdf2fbac17194272480915cc57f486dade1c12f2ca6ecf64b021d120aaf25fa84a9bad085c5e1e958b1537e9f2e979361fbb0353aae65
+  data.tar.gz: 1da4cd4c6161a49663c9198f67847724edf1c7baa4c0988df86ea5c80361ad411af3ff83a0cdf9ed6e34a76d22208c782d44bd451e04c15d3d72bda582cb7186

data/README.md

@@ -198,6 +198,63 @@ Example projects log in once and restore the saved session for examples tagged `
 - The state stays in git-ignored `.raider/auth/`.
 - Skeletons (`examples:false`) get `SessionState#reuse` to wire your own login.
 
+### Flows: run without assertions (web)
+
+A flow is a recorded chore with no checks, such as logging in and downloading a report. It is done when every step ran. Flows are RSpec files under `flows/`, so they use the same driver, locators, waiting, screenshots, video and trace as your tests.
+
+```
+raider flow init                     # adds flows/flow_helper.rb, flows/support/run.rb and .gitignore lines
+raider flow run timesheet            # runs flows/timesheet_flow.rb headless
+raider flow run timesheet --headed --retries 2 --input hours=7
+raider flow list [--json]            # each flow and its last result
+```
+
+```ruby
+# flows/timesheet_flow.rb
+require_relative 'flow_helper'
+
+RSpec.describe 'Fill the timesheet' do
+  it 'saves the hours' do
+    driver.navigate.to 'https://example.com/timesheet'
+    driver.find_element(label: 'Hours').send_keys(flow_input('hours', '8'))
+    driver.find_element(by_role('button', name: 'Save')).click
+  end
+end
+```
+
+- **Exit codes:** 0 completed, 1 a step failed, 2 setup failed (bundle, driver, missing helper), 3 the flow is already running. Each flow holds its own lock in `.raider/flows/`, and a second run exits 3 straight away.
+- **Results:** each run gets its own `flow-results/<name>/<UTC time>/` (report, failure screenshot, video and trace), and `.raider/flows/<name>/runs.jsonl` gains one line: `started_at`, `finished_at`, `status` (`completed`, `failed`, `setup_error`, `busy`), `failed_step`, `attempt`, `trigger`, `results_dir`. The last 20 result folders and 50 lines are kept. Flow runs never touch `raider-results/`, and test runs never touch `flow-results/`.
+- **Inputs:** `flow_input('name', 'default')` reads `--input name=value` (`RAIDER_INPUT_NAME`). Inputs show up in your shell history and process list, so keep secrets out of them.
+- **Secrets:** put them in `.raider/flows/env` as `KEY=value` lines (`#` comments, no interpolation). The file is loaded only when you own it and it has permissions 600 (`chmod 600 .raider/flows/env`); otherwise the run warns and goes on without it. Values are never written to the run log (they are replaced with `[secret]`), but your flow's own output and errors are printed as they are. On Windows there are no permission bits, so the folder's access rules protect the file: keep the project in your user folder.
+- **The same record every way:** `bundle exec rspec flows/timesheet_flow.rb` writes the same run log as `raider flow run`; `raider flow run` adds retries (whole flow, 30 s apart) and the exit codes. Set `RAIDER_FLOW_HEADED=1` to watch a plain rspec run (`headless: true` in `config/config.yml` still wins).
+- Projects made with 4.0 can add flows: `raider flow init` raises the Gemfile's `ruby_raider` pin to `~> 4.1`; run `bundle install` after it.
+
+### Scheduling flows
+
+Your computer's own scheduler runs the flow, so nothing needs to stay open. Scheduling never asks for sudo or admin rights.
+
+```bash
+raider flow schedule timesheet --every weekday --at 17:30 --input hours=7 --notify
+raider flow schedule backup --every hour --at :15
+raider flow schedule report --every week --on fri --at 09:00 --retries 2
+raider flow unschedule timesheet
+raider flow schedules [--json]       # each schedule, its next run, last result and OS state
+```
+
+- **Rules:** `--every hour|day|weekday|week`. `--at HH:MM` (24h, local time) is required for `day`, `weekday` and `week`; for `hour` use `--at :MM` (default `:00`). `--on mon|tue|wed|thu|fri|sat|sun` is required for `week` and refused otherwise. `--retries N` (0 to 3) and `--input name=value` are passed to `raider flow run`. Scheduling a flow again replaces its schedule.
+- **Schedulers:** macOS uses launchd (`~/Library/LaunchAgents/dev.rubyraider.flow.<hash>.<name>.plist`). Windows uses Task Scheduler (a task in the `\RubyRaider\` folder). Linux uses a systemd user timer in `~/.config/systemd/user`, or, when `systemctl --user` does not answer, one tagged line in your crontab. Times are local time (cron uses the system time zone).
+- **Missed runs:** launchd runs a run missed while the Mac slept once on wake. Task Scheduler runs it as soon as it can. systemd (`Persistent=true`) runs it once your user manager is back, at the next boot or login. cron skips it, and `raider flow schedules` says so.
+- **Logged in:** on macOS (a launchd agent in your GUI session) and Windows (a task that runs only while you are logged on) a run happens only while you are logged in.
+- **Linux:** systemd user timers stop when you log out unless lingering is on: `loginctl enable-linger $USER` (raider does not run it). A systemd schedule can only be removed from a session where `systemctl --user` works; until then `unschedule` refuses and keeps the entry.
+- **Per machine:** schedules live in `.raider/flows/schedules.yml`, which `raider flow init` git-ignores, so a fresh clone has none. schedules.yml is the source of truth, and the next run is worked out from the rule. Each OS entry is tied to the project's path: unschedule before you move the project.
+- **States:** `ok`, `missing from launchd` (or `Task Scheduler`, `systemd`, `cron`) when the OS entry is gone, `missing from schedules.yml` when the OS still runs a flow the file does not list, `Ruby not found: re-schedule`, `flow not found: unschedule` when `flows/<name>_flow.rb` was deleted or renamed, and `unknown (...)` when the scheduler could not be asked.
+- **Ruby:** the OS entry runs the absolute `ruby` and `bundle` paths captured when you scheduled, plus `GEM_HOME` and `GEM_PATH` on macOS and Linux. After a Ruby upgrade or move, `schedules` says `Ruby not found: re-schedule`: run `raider flow schedule` again.
+- **Logs:** on macOS and Linux the scheduler's output goes to `.raider/flows/<name>/scheduler.log`. Windows tasks run ruby.exe directly with your user environment and keep no scheduler.log; each run's result is in `runs.jsonl` as always.
+- **Notify:** `--notify` shows a desktop notification only when a run ends failed or could not start (not when it completed, was already running, or was stopped). macOS uses `osascript`, Linux `notify-send`, Windows a PowerShell toast. When a run could not start, the notification points at `.raider/flows/<name>/scheduler.log` for a scheduled run on macOS and Linux, and at the run output otherwise. A notification that can't be shown prints a warning and never changes the exit code. On Linux `notify-send` needs your desktop session bus: under cron, and in a systemd user session that has not imported it, it usually can't show, and only the warning lands in scheduler.log. `raider flow run --notify` does the same for a manual run.
+- **Secrets:** keep them in `.raider/flows/env`, never in `--input`: inputs are stored in plain text in the OS entry and in schedules.yml.
+- **Windows refusals:** Task Scheduler expands `%NAME%` with no way to escape it, so an input or path holding `%...%` is refused. An argument holding both `'` and one of `* ? [ {` is refused too, because ruby.exe would glob it.
+- **Tested on:** macOS (launchd) is tested against the real scheduler. Task Scheduler, systemd and cron are covered by unit tests with a fake scheduler only.
+
 ### Also included
 
 - **Page Object Model:** base page and component classes with example pages
@@ -270,11 +327,12 @@ The skeleton keeps the helpers, config, CI and README, and its empty suite passe
 raider new [PROJECT_NAME]       # Create a new framework project
 raider generate                 # Access scaffolding commands
 raider utility                  # Access utility commands
+raider flow                     # Run flows: init, run, list, schedule
 raider version                  # Show current version
 raider help [COMMAND]           # Describe available commands
 ```
 
-Shortcuts: `n` (new), `g` (generate), `u` (utility), `v` (version)
+Shortcuts: `n` (new), `g` (generate), `u` (utility), `f` (flow), `v` (version)
 
 ### Scaffolding Commands
 

data/RELEASE.md

@@ -2,6 +2,18 @@
 
 ## Release Notes
 
+### 4.1.0 (unreleased)
+
+- Flows: recordings without assertions that run on their own. `raider flow init` adds `flows/flow_helper.rb` and `flows/support/run.rb` to a Selenium web project made with 4.0 or later (and raises a `~> 4.0` Gemfile pin to `~> 4.1`); mobile and 3.x projects are refused with exit 2.
+- `raider flow run NAME` runs `flows/NAME_flow.rb` headless with `bundle exec rspec`, exiting 0 completed, 1 a step failed, 2 setup failed, 3 already running. `--headed`, `--retries N` (0 to 3, whole flow, 30 s apart), `--input name=value` (read with `flow_input`) and `--trigger manual|schedule|desktop`. `--project PATH` works from any folder.
+- Each run takes a per-flow lock, writes its report, screenshot, video and trace to `flow-results/<name>/<UTC time>/` (never cleaned between runs, last 20 kept) and appends one line to `.raider/flows/<name>/runs.jsonl` (last 50 kept). Flow runs never touch `raider-results/`.
+- Secrets for flows go in `.raider/flows/env` (`KEY=value`), loaded only from a file you own with permissions 600 and kept out of the run log.
+- `raider flow list [--json]` shows each flow and its last result. `raider f` is short for `raider flow`.
+- `raider flow schedule NAME --every hour|day|weekday|week [--at HH:MM | :MM] [--on mon..sun] [--retries N] [--input name=value] [--notify]` runs a flow with the computer's own scheduler: launchd on macOS, Task Scheduler (`\RubyRaider\` folder) on Windows, a systemd user timer on Linux, or a crontab line when `systemctl --user` does not answer. No sudo or admin rights. The entry stores the absolute ruby and bundle paths (and `GEM_HOME`/`GEM_PATH` on macOS and Linux) captured when you schedule.
+- `raider flow unschedule NAME` removes the OS entry, then the `.raider/flows/schedules.yml` entry. `raider flow schedules [--json]` lists each schedule with its rule, next run, last result and OS state (`ok`, `missing from <scheduler>`, `missing from schedules.yml`, `Ruby not found: re-schedule`, `unknown`).
+- `--notify` (on `schedule` and on `raider flow run`) shows a desktop notification when a run fails or can not start: osascript on macOS, notify-send on Linux, a PowerShell toast on Windows.
+- Only launchd has been run for real (a scheduled run fired on macOS and was unscheduled cleanly). Task Scheduler, systemd and cron are covered by unit tests only: no real Windows or Linux run before this release.
+
 ### 4.0.1
 
 - Failure video works for web projects without `RAIDER_FFMPEG_PATH`: the RaiderHQ `ffmpeg-7.1` release is published and `RubyRaider::Ffmpeg::MANIFEST` pins the SHA-256 of its four binaries (macOS arm64 and x64, Linux x64, Windows x64). The first failing test, or `raider u video install`, downloads the one for your platform, checks it and caches it in `~/.cache/raider` (`%LOCALAPPDATA%\raider` on Windows).

data/lib/commands/flow_commands.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'json'
+require_relative '../utilities/flows/runner'
+require_relative '../utilities/flows/scheduler'
+
+# raider flow: recordings without assertions that run on their own.
+class FlowCommands < Thor
+  def self.exit_on_failure? = true
+
+  class_option :project, type: :string, desc: 'The project folder (default: the current folder)'
+
+  desc 'init', 'Adds flows/flow_helper.rb and the .gitignore lines to a Selenium web project'
+
+  def init
+    code = project.init
+    exit(code) unless code.zero?
+  rescue RubyRaider::Flows::Error => e
+    stop(e)
+  end
+
+  # `run` is a Thor reserved word, so the method has another name
+  desc 'run NAME', 'Runs flows/NAME_flow.rb headless with its own results folder and run log'
+  option :headed, type: :boolean, desc: 'Show the browser'
+  option :retries, type: :numeric, default: 0, desc: 'Re-run the whole flow up to N times (0-3), 30 s apart'
+  option :input, type: :array, desc: 'Flow inputs as name=value (read with flow_input)'
+  option :trigger, type: :string, default: 'manual', desc: 'manual, schedule or desktop'
+  option :notify, type: :boolean, desc: 'Show a desktop notification when the flow fails'
+
+  def run_flow(name)
+    runner = RubyRaider::Flows::Runner.new(project)
+    exit(runner.run(name, headed: options[:headed], retries: options[:retries], inputs: options[:input],
+                          trigger: options[:trigger], notify: options[:notify] || false))
+  rescue RubyRaider::Flows::Error => e
+    stop(e)
+  end
+
+  map 'run' => :run_flow
+
+  desc 'list', 'Lists the flows with their last result'
+  option :json, type: :boolean, desc: 'Print JSON for the desktop app'
+
+  def list
+    summaries = RubyRaider::Flows::RunLog.summaries(project)
+    return puts(JSON.generate(summaries)) if options[:json]
+    return puts('No flows yet: write one in flows/<name>_flow.rb') if summaries.empty?
+
+    summaries.each { |flow| puts(list_line(flow)) }
+  rescue RubyRaider::Flows::Error => e
+    stop(e)
+  end
+
+  desc 'schedule NAME', 'Runs a flow on a schedule with the OS scheduler'
+  option :every, type: :string, desc: 'hour, day, weekday or week'
+  option :at, type: :string, desc: 'HH:MM (24h, local time); for every hour :MM'
+  option :on, type: :string, desc: 'mon to sun, for every week'
+  option :retries, type: :numeric, default: 0, desc: 'Re-run the whole flow up to N times (0-3)'
+  option :input, type: :array, desc: 'Flow inputs as name=value'
+  option :notify, type: :boolean, desc: 'Show a desktop notification when a scheduled run fails'
+
+  def schedule(name)
+    scheduler.schedule(name, every: options[:every], at: options[:at], on: options[:on], retries: options[:retries],
+                             inputs: options[:input] || [], notify: options[:notify] || false)
+  rescue RubyRaider::Flows::Error => e
+    stop(e)
+  end
+
+  desc 'unschedule NAME', 'Removes the schedule of a flow'
+
+  def unschedule(name)
+    scheduler.unschedule(name)
+  rescue RubyRaider::Flows::Error => e
+    stop(e)
+  end
+
+  desc 'schedules', 'Lists the scheduled flows with their next run and last result'
+  option :json, type: :boolean, desc: 'Print JSON for the desktop app'
+
+  def schedules
+    scheduler.schedules(json: options[:json] || false)
+  rescue RubyRaider::Flows::Error => e
+    stop(e)
+  end
+
+  no_commands do
+    def project
+      RubyRaider::Flows::Project.new(options[:project] || Dir.pwd)
+    end
+
+    def scheduler = RubyRaider::Flows::Scheduler.new(project)
+
+    def list_line(flow)
+      last = flow['last']
+      result = last ? RubyRaider::Flows.printable("#{last['status']}  #{last['finished_at']}") : 'never run'
+      "#{flow['name'].ljust(30)}  #{result}"
+    end
+
+    def stop(error)
+      warn(error.message)
+      exit(error.exit_code)
+    end
+  end
+end

data/lib/generators/templates/flows/flow_helper.tt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Every flow (flows/<name>_flow.rb) requires this file. A flow is an RSpec file without assertions:
+# it completes when every step ran. Run one with `raider flow run <name>`, or `bundle exec rspec flows/<name>_flow.rb`.
+# Generated by `raider flow init`.
+
+require_relative 'support/run'
+
+# Before the driver starts: take the flow's lock, pick its results folder, load .raider/flows/env, go headless.
+# The report goes to this run's folder even when start! refuses the run, so a flow never cleans raider-results.
+begin
+  RaiderFlows::Run.start!
+ensure
+  RaiderFlows::Run.configure_reporter
+end
+
+require_relative '../helpers/spec_helper'
+
+# Helpers available inside a flow.
+module FlowHelper
+  # A value passed with `raider flow run <name> --input name=value`, or the recorded default.
+  def flow_input(name, default = nil)
+    key = name.to_s
+    raise ArgumentError, "invalid flow input name #{key.inspect}" unless RaiderFlows::Run::INPUT.match?(key)
+
+    ENV.fetch("RAIDER_INPUT_#{key.upcase}", default)
+  end
+end
+
+# Again now that spec_helper is surely loaded
+RaiderFlows::Run.configure_reporter
+
+RSpec.configure do |config|
+  config.include(FlowHelper)
+  # Flows don't touch spec/examples.txt, so `rspec --only-failures` stays about tests
+  config.example_status_persistence_file_path = nil
+  # A flow is not idempotent mid-way: never re-run it from step 1 inside one run (raider flow run --retries re-runs it whole)
+  config.default_retry_count = 0 if config.respond_to?(:default_retry_count=)
+  config.define_derived_metadata(file_path: %r{/flows/[^/]+_flow\.rb\z}) { |metadata| metadata[:flow] = true }
+  # Runs after spec_helper's hooks started the browser: a failure before this is a setup error, not a step
+  config.append_before(:each) { RaiderFlows::Run.steps_started! }
+end

data/lib/generators/templates/flows/run.tt

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'fileutils'
+require 'json'
+require 'time'
+require 'tmpdir'
+
+# One run of a flow: a per-flow lock, a results folder and one line in .raider/flows/<name>/runs.jsonl.
+# flows/flow_helper.rb starts it, so `raider flow run`, plain rspec, the desktop app and a schedule all
+# leave the same record. Generated by `raider flow init`.
+module RaiderFlows
+  module Run
+    NAME = /\A[a-z0-9_]{1,60}\z/.freeze
+    RESERVED = %w[env].freeze # .raider/flows/env is the secrets file, not a flow's log folder
+    INPUT = /\A[a-z][a-z0-9_]{0,39}\z/.freeze
+    ENV_KEY = /\A[A-Z_][A-Z0-9_]*\z/.freeze
+    RUN_ID = /\A[0-9a-f]{16}\z/.freeze
+    RESULTS_STAMP = /\A\d{8}T\d{6}Z(?:-\d+)?\z/.freeze
+    TRIGGERS = %w[manual schedule desktop].freeze
+    KEEP_LINES = 50
+    KEEP_RESULTS = 20
+    MAX_RUN_JSON_BYTES = 10 * 1024 * 1024
+    MAX_ENV_BYTES = 64 * 1024
+    MIN_SECRET = 4
+    ENV_FILE = '.raider/flows/env'
+    NOFOLLOW = defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0
+    NONBLOCK = defined?(File::NONBLOCK) ? File::NONBLOCK : 0
+    ROOT = File.expand_path('../..', __dir__)
+
+    class << self
+      attr_reader :name, :results_dir
+
+      # At require time, before the driver or the reporter start. Exits 3 when the flow is already running.
+      def start!
+        # `rspec --dry-run` runs nothing, so it takes no lock and leaves no record
+        return if @name || RSpec.configuration.dry_run?
+
+        root = File.realpath(ROOT)
+        @name = flow_name
+        @root = root
+        @started_at = now
+        @secrets = []
+        busy! unless lock
+        stop_on_interrupt
+        # Registered as soon as the lock is held, so even a failure below leaves its line. It runs after
+        # RSpec and the reporter finished (run.json is written), whatever way the run ended.
+        at_exit { finish!(exit_status($ERROR_INFO)) }
+        @results_dir = new_results_dir
+        load_env_file
+        headless
+      end
+
+      # RSpec would finish the whole flow on a first Ctrl-C and exit! (no run log line) on a second. The first
+      # one ends the current step instead, so the run is recorded and spec_helper still quits the driver;
+      # a second one is ignored while that happens, and a third quits at once (no run log line).
+      def stop_on_interrupt
+        presses = 0
+        trap('INT') do
+          presses += 1
+          raise Interrupt, 'flow stopped' if presses == 1
+
+          presses == 2 ? say('stopping: press Ctrl-C again to quit at once') : exit!(130)
+        end
+      end
+
+      # RAIDER_FLOW_HEADED=1 drops a HEADLESS left in the shell; config.yml headless: true still wins
+      def headless
+        if ENV['RAIDER_FLOW_HEADED'] == '1'
+          ENV.delete('HEADLESS')
+        else
+          ENV['HEADLESS'] ||= 'true'
+        end
+      end
+
+      # Flow results go to flow-results/<name>/<UTC stamp>, never raider-results, and are never cleaned
+      def configure_reporter
+        return unless defined?(RaiderReporter)
+
+        RaiderReporter.configure do |reporter|
+          reporter.output_dir = results_dir || (@fallback_dir ||= Dir.mktmpdir('raider-flow-'))
+          reporter.clean_output_dir = false
+        end
+      end
+
+      def steps_started!
+        @steps_started = true
+      end
+
+      def finish!(code)
+        return unless @lock
+
+        append(record(code))
+        prune
+      rescue StandardError => e
+        say("could not write the run log: #{e.class}")
+      ensure
+        release
+      end
+
+      private
+
+      def now
+        Time.now.utc
+      end
+
+      def say(message)
+        $stderr.puts("[raider flow] #{message}") # rubocop:disable Style/StderrPuts -- -W0 must not hide these
+      end
+
+      def flow_name
+        flows = RSpec.configuration.files_to_run.select { |file| file.end_with?('_flow.rb') }
+        raise ArgumentError, 'run one flow at a time: rspec flows/<name>_flow.rb' unless flows.one?
+
+        name = File.basename(flows.first, '_flow.rb')
+        raise ArgumentError, "invalid flow name #{name.inspect}" unless NAME.match?(name) && !RESERVED.include?(name)
+
+        wanted = ENV.fetch('RAIDER_FLOW_NAME', name)
+        raise ArgumentError, "RAIDER_FLOW_NAME is #{wanted.inspect} but the flow is #{name.inspect}" unless wanted == name
+
+        name
+      end
+
+      def lock
+        file = File.join(private_dir('.raider/flows'), "#{name}.lock")
+        handle = File.open(file, File::RDWR | File::CREAT | NOFOLLOW, 0o600)
+        return @lock = handle if handle.flock(File::LOCK_EX | File::LOCK_NB)
+
+        handle.close
+        nil
+      end
+
+      def release
+        @lock&.close
+        @lock = nil
+      end
+
+      def busy!
+        append(base_line.merge(finished_at: iso(now), status: 'busy', results_dir: nil))
+        say("#{name} is already running")
+        exit 3
+      end
+
+      # A 0700 folder inside the project that is not a link
+      def private_dir(relative)
+        dir = File.join(@root, relative)
+        FileUtils.mkdir_p(dir)
+        raise IOError, "#{relative} must be a folder, not a link" unless File.lstat(dir).directory?
+
+        File.chmod(0o700, dir)
+        dir
+      end
+
+      def new_results_dir
+        base = File.join(@root, 'flow-results', name, now.strftime('%Y%m%dT%H%M%SZ'))
+        dir = base
+        suffix = 1
+        dir = "#{base}-#{suffix += 1}" while File.exist?(dir)
+        FileUtils.mkdir_p(dir)
+        dir
+      end
+
+      # KEY=value lines, # comments, no interpolation. Loaded only from a regular file you own with mode 600.
+      # RAIDER_FLOW_* keys are the wrapper's, so the file can't set them.
+      def load_env_file
+        content = read_env_file
+        return unless content
+
+        content.each_line.with_index(1) do |raw, number|
+          line = raw.dup.force_encoding(Encoding::UTF_8)
+          line = line.valid_encoding? ? line.strip : nil
+          next if line&.empty? || line&.start_with?('#')
+
+          key, value = line&.split('=', 2)&.map(&:strip)
+          unless value && ENV_KEY.match?(key.to_s) && !key.to_s.start_with?('RAIDER_FLOW_')
+            say("#{ENV_FILE} line #{number} ignored: expected KEY=value")
+            next
+          end
+          set_env(key.to_s, unquote(value))
+        end
+      end
+
+      def read_env_file
+        File.open(File.join(@root, ENV_FILE), File::RDONLY | NONBLOCK | NOFOLLOW) do |file|
+          stat = file.stat
+          return say("ignored #{ENV_FILE}: it must be a regular file you own") unless owned_file?(stat)
+          return say("ignored #{ENV_FILE}: permissions must be 600") unless private_mode?(stat)
+
+          file.read(MAX_ENV_BYTES).to_s
+        end
+      rescue Errno::ENOENT
+        nil
+      rescue SystemCallError
+        say("ignored #{ENV_FILE}: it must be a regular file you own")
+      end
+
+      # Windows has no POSIX owner or mode bits, so there the folder's ACLs decide who can read the file:
+      # keep the project under your user profile, or restrict the file with icacls
+      def owned_file?(stat)
+        stat.file? && (Gem.win_platform? || stat.uid == Process.uid)
+      end
+
+      def private_mode?(stat)
+        Gem.win_platform? || (stat.mode & 0o077).zero?
+      end
+
+      # A value already in the environment wins; both are kept out of the run log
+      def set_env(key, value)
+        ENV[key] = value unless ENV.key?(key)
+        [value, ENV.fetch(key)].each { |secret| @secrets << secret if secret.length >= MIN_SECRET }
+      end
+
+      def unquote(value)
+        quoted = value.length >= 2 && value[0] == value[-1] && ['"', "'"].include?(value[0])
+        quoted ? value[1...-1].to_s : value
+      end
+
+      def exit_status(error)
+        case error
+        when nil then 0
+        when SystemExit then error.status
+        else 1
+        end
+      end
+
+      def base_line
+        {
+          started_at: iso(@started_at),
+          attempt: [Integer(ENV.fetch('RAIDER_FLOW_ATTEMPT', '1'), 10, exception: false) || 1, 1].max,
+          trigger: TRIGGERS.include?(ENV.fetch('RAIDER_FLOW_TRIGGER', nil)) ? ENV.fetch('RAIDER_FLOW_TRIGGER') : 'manual',
+          run_id: RUN_ID.match?(ENV.fetch('RAIDER_FLOW_RUN_ID', '')) ? ENV.fetch('RAIDER_FLOW_RUN_ID') : nil
+        }.compact
+      end
+
+      def record(code)
+        status = outcome(code)
+        line = base_line.merge(finished_at: iso(now), status: status, results_dir: relative(results_dir))
+        line[:failed_step] = failed_step if status == 'failed'
+        line
+      end
+
+      def outcome(code)
+        statuses = RSpec.world.all_examples.map { |example| example.execution_result.status }
+        return 'completed' if code.zero? && statuses.include?(:passed) && !statuses.include?(:failed)
+        return 'failed' if @steps_started && statuses.include?(:failed)
+
+        'setup_error'
+      end
+
+      # The first failed example: its line in the flow file and the recorded step, when the desktop's sidecar named it
+      def failed_step
+        example = RSpec.world.all_examples.find { |each| each.execution_result.status == :failed }
+        return nil unless example
+
+        number, title = recorded_step(example)
+        { number: number, title: redact(title || example.description), line: flow_line(example) }.compact
+      end
+
+      def flow_line(example)
+        file = example.metadata[:absolute_file_path].to_s
+        frame = Array(example.exception&.backtrace).find { |each| each.start_with?("#{file}:") }
+        frame && frame.delete_prefix("#{file}:").to_i
+      end
+
+      def recorded_step(example)
+        return nil unless results_dir
+
+        report = File.join(results_dir, 'run.json')
+        return nil unless File.file?(report) && File.size(report) <= MAX_RUN_JSON_BYTES
+
+        file = example.metadata[:file_path].to_s.delete_prefix('./')
+        result = JSON.parse(File.read(report)).fetch('results', []).find do |each|
+          each['file_path'] == file && each['status'] == 'failed' && each['steps'].is_a?(Hash)
+        end
+        index = result&.dig('steps', 'failed')
+        return nil unless index.is_a?(Integer)
+
+        [index + 1, result.dig('steps', 'items', index, 'title')]
+      rescue StandardError
+        nil
+      end
+
+      def redact(text)
+        @secrets.uniq.sort_by { |secret| -secret.length }.reduce(text.to_s) { |result, secret| result.gsub(secret, '[secret]') }
+      end
+
+      def append(line)
+        File.open(log_file, File::WRONLY | File::APPEND | File::CREAT | NOFOLLOW, 0o600) do |file|
+          file.flock(File::LOCK_EX)
+          file.write("#{JSON.generate(line)}\n")
+        end
+      end
+
+      def prune
+        File.open(log_file, File::RDWR | NOFOLLOW) do |file|
+          file.flock(File::LOCK_EX)
+          lines = file.read.lines
+          if lines.size > KEEP_LINES
+            file.rewind
+            file.truncate(0)
+            file.write(lines.last(KEEP_LINES).join)
+          end
+        end
+        prune_results
+      end
+
+      # Only stamp-named folders directly under flow-results/<name>, and never this run's
+      def prune_results
+        dir = File.join(@root, 'flow-results', name)
+        return unless File.directory?(dir) && File.realpath(dir) == dir
+
+        runs = Dir.children(dir).select do |child|
+          RESULTS_STAMP.match?(child) && File.lstat(File.join(dir, child)).directory?
+        end
+        old = runs.sort - runs.sort.last(KEEP_RESULTS) - [results_dir && File.basename(results_dir)]
+        old.each { |child| FileUtils.rm_rf(File.join(dir, child)) }
+      end
+
+      def log_file
+        File.join(private_dir(".raider/flows/#{name}"), 'runs.jsonl')
+      end
+
+      def relative(path)
+        path&.delete_prefix("#{@root}/")
+      end
+
+      def iso(time)
+        time.iso8601(3)
+      end
+    end
+  end
+end

data/lib/ruby_raider.rb

@@ -5,11 +5,23 @@ require 'thor'
 # Lazy-load top-level command classes to reduce CLI startup time.
 autoload :ScaffoldingCommands, File.expand_path('commands/scaffolding_commands', __dir__)
 autoload :UtilityCommands, File.expand_path('commands/utility_commands', __dir__)
+autoload :FlowCommands, File.expand_path('commands/flow_commands', __dir__)
 
 module RubyRaider
   class Raider < Thor
     def self.exit_on_failure? = true
 
+    # Thor runs a regex on every argument before any command, so invalid UTF-8 would crash it with a
+    # backtrace; a flow command says which argument instead and exits 2 like its other refusals
+    def self.start(given_args = ARGV, config = {})
+      bad = given_args.find { |arg| arg.is_a?(String) && !arg.valid_encoding? }
+      if bad && %w[flow f].include?(given_args.first)
+        warn("Invalid argument #{bad.inspect}: use valid UTF-8")
+        exit(2)
+      end
+      super
+    end
+
     no_tasks do
       def current_version = File.read(File.expand_path('version', __dir__)).strip
     end
@@ -51,6 +63,10 @@ module RubyRaider
     subcommand 'utility', UtilityCommands
     map 'u' => 'utility'
 
+    desc 'flow', 'Runs flows: recordings without assertions (init, run, list, schedule)'
+    subcommand 'flow', FlowCommands
+    map 'f' => 'flow'
+
     no_tasks do
       # -p values arrive as strings; examples must be true or false, in any case
       def generate_from_parameters(params)