ruby_raider 4.0.1 → 4.1.0

data/spec/integration/flows/run_lifecycle_spec.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'open3'
+require 'time'
+require 'timeout'
+require 'tmpdir'
+require_relative 'flow_project'
+
+# Runs flows/support/run.rb and flows/flow_helper.rb, as `raider flow init` writes them, under a real
+# rspec process (see FlowProject: no browser, no raider_reporter).
+RSpec.describe 'flow run lifecycle' do
+  flows = {
+    'ok' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe 'ok' do
+        it 'runs every step' do
+          driver
+          puts "headless=\#{ENV.fetch('HEADLESS', 'unset')} who=\#{flow_input('who', 'nobody')}"
+          puts "secret loaded=\#{ENV['RAIDER_SECRET_TOKEN'] == 'hunter2'}"
+        end
+      end
+    RUBY
+    'broken' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe 'broken' do
+        it 'downloads the report' do
+          driver
+          driver
+          raise 'no such element: { id: "export" } (waited 10s)'
+        end
+      end
+    RUBY
+    'recorded' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe 'recorded' do
+        it 'exports' do
+          raise 'no such element'
+        end
+      end
+    RUBY
+    'leaky' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe 'leaky' do
+        it "types \#{ENV.fetch('RAIDER_SECRET_TOKEN', 'x')} somewhere" do
+          raise 'failed'
+        end
+      end
+    RUBY
+    'env' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe('env') { it('runs') { puts 'ran' } }
+    RUBY
+    'long' => <<~RUBY,
+      require_relative 'flow_helper'
+
+      RSpec.describe 'long' do
+        it 'waits' do
+          File.write('ready', '')
+          sleep 20
+        end
+      end
+    RUBY
+    'unloadable' => <<~RUBY
+      require_relative 'flow_helper'
+
+      UndefinedConstant.call
+    RUBY
+  }
+
+  let(:dir) { File.realpath(Dir.mktmpdir('flow-lifecycle')) }
+
+  before { FlowProject.build(dir, flows) }
+
+  after { FileUtils.rm_rf(dir) }
+
+  # Unsets the variables the test process may carry that would change a run
+  def clean_env
+    %w[HEADLESS RAIDER_FLOW_NAME RAIDER_FLOW_HEADED RAIDER_FLOW_ATTEMPT RAIDER_FLOW_TRIGGER RAIDER_FLOW_RUN_ID
+       RAIDER_SECRET_TOKEN RAIDER_INPUT_WHO FAKE_DRIVER_FAIL FAKE_STEPS].to_h { |key| [key, nil] }
+  end
+
+  def run_flow(name, env = {})
+    out, err, status = Open3.capture3(clean_env.merge(env), RbConfig.ruby, '-S', 'rspec', "flows/#{name}_flow.rb", chdir: dir)
+    [out + err, status.exitstatus]
+  end
+
+  def log(name)
+    file = File.join(dir, ".raider/flows/#{name}/runs.jsonl")
+    File.exist?(file) ? File.readlines(file).map { |line| JSON.parse(line) } : []
+  end
+
+  def mode(relative) = File.stat(File.join(dir, relative)).mode & 0o777
+
+  def write_env_file(content, permissions)
+    FileUtils.mkdir_p(File.join(dir, '.raider/flows'))
+    File.write(File.join(dir, '.raider/flows/env'), content)
+    File.chmod(permissions, File.join(dir, '.raider/flows/env'))
+  end
+
+  it 'records a completed run with its results folder, headless by default', :aggregate_failures do
+    output, code = run_flow('ok', 'RAIDER_INPUT_WHO' => 'ada')
+    line = log('ok').last
+
+    expect(code).to eq(0)
+    expect(output).to include('headless=true who=ada')
+    expect(line).to include('status' => 'completed', 'attempt' => 1, 'trigger' => 'manual')
+    expect(line['results_dir']).to match(%r{\Aflow-results/ok/\d{8}T\d{6}Z\z})
+    expect(File).to be_directory(File.join(dir, line['results_dir']))
+    expect(Time.iso8601(line['finished_at'])).to be >= Time.iso8601(line['started_at'])
+  end
+
+  it 'keeps the run log and lock private' do
+    run_flow('ok')
+
+    expect([mode('.raider/flows'), mode('.raider/flows/ok'), mode('.raider/flows/ok/runs.jsonl'), mode('.raider/flows/ok.lock')])
+      .to eq([0o700, 0o700, 0o600, 0o600])
+  end
+
+  it 'opens the browser when RAIDER_FLOW_HEADED=1' do
+    output, = run_flow('ok', 'RAIDER_FLOW_HEADED' => '1')
+
+    expect(output).to include('headless=unset')
+  end
+
+  it 'takes the attempt, trigger and run id from the wrapper' do
+    run_flow('ok', 'RAIDER_FLOW_ATTEMPT' => '2', 'RAIDER_FLOW_TRIGGER' => 'schedule', 'RAIDER_FLOW_RUN_ID' => 'abcdef0123456789')
+
+    expect(log('ok').last).to include('attempt' => 2, 'trigger' => 'schedule', 'run_id' => 'abcdef0123456789')
+  end
+
+  it 'falls back to manual for an unknown trigger and drops a malformed run id' do
+    run_flow('ok', 'RAIDER_FLOW_TRIGGER' => 'cron; rm -rf /', 'RAIDER_FLOW_RUN_ID' => '../x')
+
+    expect(log('ok').last).to include('trigger' => 'manual').and(satisfy { |line| !line.key?('run_id') })
+  end
+
+  it 'records a failed step with its line in the flow file' do
+    _output, code = run_flow('broken')
+    line = log('broken').last
+
+    expect(code).to eq(1)
+    expect(line).to include('status' => 'failed', 'failed_step' => { 'title' => 'downloads the report', 'line' => 7 })
+  end
+
+  it 'names the recorded step when the report has the desktop step map' do
+    run_flow('recorded', 'FAKE_STEPS' => '1')
+
+    expect(log('recorded').last['failed_step']).to eq('number' => 2, 'title' => 'click "Export"', 'line' => 5)
+  end
+
+  it 'records a setup error when the driver fails before the first step' do
+    _output, code = run_flow('ok', 'FAKE_DRIVER_FAIL' => '1')
+
+    expect(code).to eq(1)
+    expect(log('ok').last).to include('status' => 'setup_error').and(satisfy { |line| !line.key?('failed_step') })
+  end
+
+  it 'records a setup error when the flow file does not load' do
+    _output, code = run_flow('unloadable')
+
+    expect(code).not_to eq(0)
+    expect(log('unloadable').last['status']).to eq('setup_error')
+  end
+
+  it 'refuses a RAIDER_FLOW_NAME that is not the flow being run' do
+    output, code = run_flow('ok', 'RAIDER_FLOW_NAME' => 'other')
+
+    expect(code).not_to eq(0)
+    expect(output).to include('RAIDER_FLOW_NAME is "other" but the flow is "ok"')
+    expect(log('ok')).to be_empty
+  end
+
+  it 'reports into the run folder and never cleans raider-results' do
+    run_flow('ok')
+    reporter = JSON.parse(File.read(File.join(dir, 'reporter.json')))
+
+    expect(reporter).to eq('output_dir' => File.join(dir, log('ok').last['results_dir']), 'clean_output_dir' => false)
+  end
+
+  it 'keeps a refused flow away from raider-results too' do
+    run_flow('ok', 'RAIDER_FLOW_NAME' => 'other')
+    reporter = JSON.parse(File.read(File.join(dir, 'reporter.json')))
+
+    expect(reporter['clean_output_dir']).to be(false)
+    expect(reporter['output_dir']).to start_with(File.realpath(Dir.tmpdir)).or start_with(Dir.tmpdir)
+  end
+
+  it 'drops a HEADLESS left in the shell for RAIDER_FLOW_HEADED=1' do
+    output, = run_flow('ok', 'RAIDER_FLOW_HEADED' => '1', 'HEADLESS' => 'true')
+
+    expect(output).to include('headless=unset')
+  end
+
+  it 'exits 3 with one busy line when another run holds the lock, and never waits' do
+    FileUtils.mkdir_p(File.join(dir, '.raider/flows'))
+    File.open(File.join(dir, '.raider/flows/ok.lock'), File::RDWR | File::CREAT, 0o600) do |held|
+      held.flock(File::LOCK_EX)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      output, code = run_flow('ok')
+
+      expect(code).to eq(3)
+      expect(output).to include('ok is already running')
+      expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 30
+    end
+    expect(log('ok').map { |line| line['status'] }).to eq(['busy'])
+    expect(log('ok').last['results_dir']).to be_nil
+  end
+
+  it 'ends the step on the first Ctrl-C, ignores the second, quits the driver and records the run' do
+    pid = Process.spawn(clean_env, RbConfig.ruby, '-S', 'rspec', 'flows/long_flow.rb', chdir: dir, %i[out err] => File::NULL)
+    Timeout.timeout(30) { sleep 0.05 until File.exist?(File.join(dir, 'ready')) }
+    2.times do
+      Process.kill('INT', pid)
+      sleep 0.2
+    end
+    Timeout.timeout(15) { Process.wait(pid) }
+
+    expect(log('long').map { |line| line['status'] }).to eq(['setup_error'])
+    expect(File).to exist(File.join(dir, 'driver_quit'))
+  end
+
+  it 'releases the lock when the run ends' do
+    run_flow('ok')
+    _output, code = run_flow('ok')
+
+    expect(code).to eq(0)
+    expect(log('ok').map { |line| line['status'] }).to eq(%w[completed completed])
+  end
+
+  context 'with the flow env file' do
+    it 'loads a 0600 file without printing its values' do
+      write_env_file("# secrets\nRAIDER_SECRET_TOKEN=\"hunter2\"\n\nbad line\n", 0o600)
+
+      output, = run_flow('ok')
+
+      expect(output).to include('secret loaded=true', '.raider/flows/env line 4 ignored: expected KEY=value')
+      expect(output).not_to include('hunter2')
+      expect(File.read(File.join(dir, '.raider/flows/ok/runs.jsonl'))).not_to include('hunter2')
+    end
+
+    it 'ignores a 0644 file with a warning' do
+      write_env_file("RAIDER_SECRET_TOKEN=hunter2\n", 0o644)
+
+      output, code = run_flow('ok')
+
+      expect(code).to eq(0)
+      expect(output).to include('ignored .raider/flows/env: permissions must be 600', 'secret loaded=false')
+    end
+
+    it 'ignores a link to a file elsewhere' do
+      target = File.join(dir, 'elsewhere')
+      File.write(target, "RAIDER_SECRET_TOKEN=hunter2\n")
+      File.chmod(0o600, target)
+      FileUtils.mkdir_p(File.join(dir, '.raider/flows'))
+      File.symlink(target, File.join(dir, '.raider/flows/env'))
+
+      output, = run_flow('ok')
+
+      expect(output).to include('ignored .raider/flows/env: it must be a regular file you own', 'secret loaded=false')
+    end
+
+    it 'does not override a variable already set' do
+      write_env_file("RAIDER_SECRET_TOKEN=hunter2\n", 0o600)
+
+      output, = run_flow('ok', 'RAIDER_SECRET_TOKEN' => 'from-shell')
+
+      expect(output).to include('secret loaded=false')
+    end
+
+    it 'keeps secret values out of the failed step title' do
+      write_env_file("RAIDER_SECRET_TOKEN=hunter2\n", 0o600)
+
+      run_flow('leaky')
+
+      expect(log('leaky').last['failed_step']['title']).to eq('types [secret] somewhere')
+      expect(File.read(File.join(dir, '.raider/flows/leaky/runs.jsonl'))).not_to include('hunter2')
+    end
+  end
+
+  context 'when something fails after the lock is taken' do
+    it 'still records the run when flow-results is not a folder' do
+      File.write(File.join(dir, 'flow-results'), '')
+
+      _output, code = run_flow('ok')
+
+      expect(code).not_to eq(0)
+      expect(log('ok').last).to include('status' => 'setup_error', 'results_dir' => nil)
+    end
+
+    it 'skips an env line that is not UTF-8 and runs the flow' do
+      write_env_file("RAIDER_SECRET_TOKEN=hunter2\nBAD=\xFF\n".b, 0o600)
+
+      output, code = run_flow('ok')
+
+      expect(code).to eq(0)
+      expect(output).to include('.raider/flows/env line 2 ignored', 'secret loaded=true')
+    end
+  end
+
+  it 'refuses a flow named env, whose log folder would be the secrets file' do
+    output, code = run_flow('env')
+
+    expect(code).not_to eq(0)
+    expect(output).to include('invalid flow name "env"')
+    expect(File).not_to exist(File.join(dir, '.raider/flows/env'))
+  end
+
+  it 'leaves no lock, record or results for rspec --dry-run' do
+    Open3.capture3(clean_env, RbConfig.ruby, '-S', 'rspec', '--dry-run', 'flows/ok_flow.rb', chdir: dir)
+
+    expect([log('ok'), File.exist?(File.join(dir, 'flow-results'))]).to eq([[], false])
+  end
+
+  it 'never lets the env file set RAIDER_FLOW_* and clamps the attempt to 1' do
+    write_env_file("RAIDER_FLOW_TRIGGER=schedule\n", 0o600)
+
+    output, = run_flow('ok', 'RAIDER_FLOW_ATTEMPT' => '0')
+
+    expect(output).to include('.raider/flows/env line 1 ignored')
+    expect(log('ok').last).to include('trigger' => 'manual', 'attempt' => 1)
+  end
+
+  it 'ignores a FIFO env file without waiting for a writer' do
+    FileUtils.mkdir_p(File.join(dir, '.raider/flows'))
+    File.mkfifo(File.join(dir, '.raider/flows/env'), 0o600)
+
+    output, code = Timeout.timeout(60) { run_flow('ok') }
+
+    expect(code).to eq(0)
+    expect(output).to include('ignored .raider/flows/env: it must be a regular file you own')
+  end
+
+  it 'redacts the longest secret first' do
+    write_env_file("RAIDER_SECRET_A=hunt\nRAIDER_SECRET_TOKEN=hunter2\n", 0o600)
+
+    run_flow('leaky')
+
+    expect(log('leaky').last['failed_step']['title']).to eq('types [secret] somewhere')
+  end
+
+  it 'redacts the value in use when the shell already set the key' do
+    write_env_file("RAIDER_SECRET_TOKEN=hunter2\n", 0o600)
+
+    run_flow('leaky', 'RAIDER_SECRET_TOKEN' => 'shell-secret')
+
+    expect(log('leaky').last['failed_step']['title']).to eq('types [secret] somewhere')
+  end
+
+  it 'never prunes through a linked flow-results folder' do
+    elsewhere = File.join(dir, 'elsewhere')
+    Array.new(25) { |i| FileUtils.mkdir_p(File.join(elsewhere, format('20200101T0000%02dZ', i))) }
+    FileUtils.mkdir_p(File.join(dir, 'flow-results'))
+    File.symlink(elsewhere, File.join(dir, 'flow-results/ok'))
+
+    run_flow('ok')
+
+    expect(Dir.children(elsewhere).grep(/\A2020/).size).to eq(25)
+  end
+
+  it 'keeps the last 50 log lines and the last 20 results folders, and only stamp-named folders' do
+    FileUtils.mkdir_p(File.join(dir, '.raider/flows/ok'))
+    File.write(File.join(dir, '.raider/flows/ok/runs.jsonl'), Array.new(60) { |i| "#{JSON.generate('n' => i)}\n" }.join)
+    old = Array.new(25) { |i| format('flow-results/ok/20200101T0000%02dZ', i) }
+    (old + ['flow-results/ok/keep-me']).each { |folder| FileUtils.mkdir_p(File.join(dir, folder)) }
+
+    run_flow('ok')
+
+    lines = log('ok')
+    stamped = Dir.children(File.join(dir, 'flow-results/ok')).grep(/\A\d{8}T/)
+    expect([lines.size, lines.first['n'], lines.last['status']]).to eq([50, 11, 'completed'])
+    expect(stamped.size).to eq(20)
+    expect(stamped).to include(File.basename(lines.last['results_dir']))
+    expect(File).to be_directory(File.join(dir, 'flow-results/ok/keep-me'))
+  end
+end

data/spec/utilities/flows/next_run_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require_relative '../../../lib/utilities/flows/next_run'
+
+# Flow specs live under spec/utilities/flows, next to the code in lib/utilities/flows
+RSpec.describe RubyRaider::Flows::NextRun do # rubocop:disable RSpec/FilePath
+  let(:dir) { File.realpath(Dir.mktmpdir('flows-next-run')) }
+  let(:project) { RubyRaider::Flows::Project.new(dir) }
+
+  around do |example|
+    zone = ENV.fetch('TZ', nil)
+    ENV['TZ'] = 'Europe/Copenhagen'
+    example.run
+  ensure
+    ENV['TZ'] = zone
+  end
+
+  after { FileUtils.rm_rf(dir) }
+
+  def rule(every, at = '08:00', on: nil)
+    RubyRaider::Flows::Schedule.build(project: project, name: 'report', every: every, at: at, on: on)
+  end
+
+  def next_after(schedule, *local)
+    described_class.after(schedule, Time.local(*local))
+  end
+
+  # [wall clock, UTC offset in hours] of a local time
+  def wall(time)
+    [time.strftime('%F %R'), time.utc_offset / 3600]
+  end
+
+  describe 'every day' do
+    it 'runs later today, or tomorrow once the time has passed' do
+      expect([wall(next_after(rule('day'), 2026, 11, 9, 7, 59)), wall(next_after(rule('day'), 2026, 11, 9, 8, 0))]).to eq(
+        [['2026-11-09 08:00', 1], ['2026-11-10 08:00', 1]]
+      )
+    end
+
+    it 'is strictly after now, by seconds too' do
+      expect(wall(next_after(rule('day'), 2026, 11, 9, 8, 0, 1))).to eq(['2026-11-10 08:00', 1])
+    end
+
+    it 'crosses a month and a year' do
+      expect(wall(next_after(rule('day'), 2026, 12, 31, 9, 0))).to eq(['2027-01-01 08:00', 1])
+    end
+  end
+
+  describe 'every weekday' do
+    it 'skips the weekend' do
+      # 2026-11-13 is a Friday
+      expect(wall(next_after(rule('weekday'), 2026, 11, 13, 9, 0))).to eq(['2026-11-16 08:00', 1])
+    end
+  end
+
+  describe 'every week' do
+    it 'runs on its day, a week later once that has passed' do
+      # 2026-11-09 is a Monday
+      expect([wall(next_after(rule('week', on: 'wed'), 2026, 11, 9, 9, 0)), wall(next_after(rule('week', on: 'mon'), 2026, 11, 9, 8, 0))]).to eq(
+        [['2026-11-11 08:00', 1], ['2026-11-16 08:00', 1]]
+      )
+    end
+  end
+
+  describe 'every hour' do
+    it 'runs at the next matching minute' do
+      expect([wall(next_after(rule('hour', ':15'), 2026, 11, 9, 10, 20)), wall(next_after(rule('hour', ':15'), 2026, 11, 9, 10, 14, 59))]).to eq(
+        [['2026-11-09 11:15', 1], ['2026-11-09 10:15', 1]]
+      )
+    end
+
+    it 'crosses midnight' do
+      expect(wall(next_after(rule('hour', ':00'), 2026, 11, 9, 23, 30))).to eq(['2026-11-10 00:00', 1])
+    end
+  end
+
+  # Copenhagen: 2026-03-29 02:00 CET jumps to 03:00 CEST; 2026-10-25 03:00 CEST falls back to 02:00 CET
+  describe 'the last Sunday of March' do
+    it 'runs a time in the skipped hour at the first minute after the gap' do
+      expect(wall(next_after(rule('day', '02:30'), 2026, 3, 29, 0, 0))).to eq(['2026-03-29 03:00', 2])
+    end
+
+    it 'goes back to the normal time the next day' do
+      expect(wall(next_after(rule('day', '02:30'), 2026, 3, 29, 3, 0))).to eq(['2026-03-30 02:30', 2])
+    end
+
+    it 'keeps a time outside the gap' do
+      expect(wall(next_after(rule('day'), 2026, 3, 29, 0, 0))).to eq(['2026-03-29 08:00', 2])
+    end
+
+    it 'runs every hour at the next real matching minute' do
+      expect(wall(next_after(rule('hour', ':30'), 2026, 3, 29, 1, 45))).to eq(['2026-03-29 03:30', 2])
+    end
+  end
+
+  describe 'the last Sunday of October' do
+    it 'runs a repeated time at its first occurrence' do
+      expect(wall(next_after(rule('day', '02:30'), 2026, 10, 25, 0, 0))).to eq(['2026-10-25 02:30', 2])
+    end
+
+    it 'does not run again at the second occurrence' do
+      first = next_after(rule('day', '02:30'), 2026, 10, 25, 0, 0)
+
+      expect(wall(described_class.after(rule('day', '02:30'), first))).to eq(['2026-10-26 02:30', 1])
+    end
+
+    it 'runs every hour in both repeated hours' do
+      first = next_after(rule('hour', ':30'), 2026, 10, 25, 1, 45)
+      second = described_class.after(rule('hour', ':30'), first)
+
+      expect([wall(first), wall(second), second - first]).to eq([['2026-10-25 02:30', 2], ['2026-10-25 02:30', 1], 3600.0])
+    end
+
+    it 'runs a week rule on the changeover day' do
+      expect(wall(next_after(rule('week', '02:30', on: 'sun'), 2026, 10, 20, 12, 0))).to eq(['2026-10-25 02:30', 2])
+    end
+  end
+end

data/spec/utilities/flows/notifier_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require_relative '../../../lib/utilities/flows/notifier'
+
+# Flow specs live under spec/utilities/flows, next to the code in lib/utilities/flows
+RSpec.describe RubyRaider::Flows::Notifier do # rubocop:disable RSpec/FilePath
+  # Records each command instead of running it: no real osascript, notify-send or PowerShell
+  let(:runner) do
+    Class.new do
+      attr_reader :calls
+      attr_accessor :exitstatus
+
+      def initialize
+        @calls = []
+        @exitstatus = 0
+      end
+
+      def call(*argv, env: {}, timeout: nil, **)
+        @calls << { argv: argv, env: env, timeout: timeout }
+        RubyRaider::Flows::Os::CommandRunner::Result.new(stdout: '', stderr: 'no notification server', exitstatus: exitstatus)
+      end
+    end.new
+  end
+
+  let(:err) { StringIO.new }
+  let(:hostile) do
+    ["'; rm -rf ~; '", '" & do shell script "id" & "', '$(id)', '</text>', '-u critical', '$env:USERPROFILE', '`whoami`']
+  end
+
+  let(:powershell) { 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe' }
+
+  def notifier(host_os) = described_class.new(runner: runner, host_os: host_os, err: err, powershell: powershell)
+
+  it 'passes the title and message to osascript as argv items of a fixed script on macOS' do
+    expect(notifier('darwin25').notify('Ruby Raider flow report', 'Failed at step 3 (Open report)')).to be(true)
+
+    expect(runner.calls).to eq([{ argv: ['/usr/bin/osascript', '-e', 'on run argv', '-e',
+                                         'display notification (item 2 of argv) with title (item 1 of argv)', '-e', 'end run', '--',
+                                         'Ruby Raider flow report', 'Failed at step 3 (Open report)'], env: {}, timeout: 15 }])
+  end
+
+  it 'ends osascript option parsing before the title, so -e in a title is not a script' do
+    notifier('darwin25').notify('-e', 'property p : (1 + 2)')
+
+    expect(runner.calls.first[:argv].last(3)).to eq(['--', '-e', 'property p : (1 + 2)'])
+  end
+
+  it 'keeps hostile text out of the script on every OS' do
+    hosts = %w[darwin25 linux-gnu mingw32]
+    scripts = hosts.to_h do |host|
+      hostile.each { |text| notifier(host).notify(text, text) }
+      calls = runner.calls.pop(hostile.size)
+      [host, calls.map { |call| host == 'mingw32' ? call[:argv] : call[:argv][0...-2] }.uniq]
+    end
+
+    expect(scripts.values.map(&:size)).to eq([1, 1, 1])
+    expect(scripts.values.flatten.join("\n")).not_to include(*hostile)
+  end
+
+  it 'passes hostile text unchanged as the last argv items on macOS' do
+    hostile.each { |text| notifier('darwin25').notify(text, text) }
+
+    expect(runner.calls.map { |call| call[:argv].last(2) }).to eq(hostile.map { |text| [text, text] })
+  end
+
+  it 'stops notify-send option parsing before the title and escapes markup in the message on Linux' do
+    notifier('linux-gnu').notify('-u critical', 'a < b & c > d')
+
+    expect(runner.calls.first[:argv]).to eq(['notify-send', '--app-name=Ruby Raider', '--', '-u critical', 'a &lt; b &amp; c &gt; d'])
+  end
+
+  it 'passes the title and message to a fixed PowerShell script through the environment on Windows' do
+    notifier('mswin64').notify('$env:USERPROFILE', '`whoami`')
+
+    expect(runner.calls.first).to eq(
+      argv: [powershell, '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', described_class::TOAST_SCRIPT],
+      env: { 'RAIDER_NOTIFY_TITLE' => '$env:USERPROFILE', 'RAIDER_NOTIFY_MESSAGE' => '`whoami`' }, timeout: 15
+    )
+  end
+
+  it 'finds PowerShell under SystemRoot by default' do
+    allow(ENV).to receive(:fetch).and_call_original
+    allow(ENV).to receive(:fetch).with('SystemRoot', 'C:\\Windows').and_return('D:\\Win')
+    described_class.new(runner: runner, host_os: 'mingw32', err: err).notify('t', 'm')
+
+    expect(runner.calls.first[:argv].first).to eq(File.join('D:\\Win', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'))
+  end
+
+  it 'builds the toast from the environment, never from text joined into XML' do
+    script = described_class::TOAST_SCRIPT
+
+    expect(script).to include('$env:RAIDER_NOTIFY_TITLE', '$env:RAIDER_NOTIFY_MESSAGE', 'CreateTextNode', 'ToastText02')
+    expect(script).not_to include('"', "\n", 'EncodedCommand')
+  end
+
+  it 'makes control characters printable and caps the message at 200 characters' do
+    notifier('darwin25').notify("flow\e[2J", "#{'x' * 250}\n")
+
+    expect(runner.calls.first[:argv].last(2)).to eq(['flow?[2J', 'x' * 200])
+  end
+
+  it 'does nothing on another OS' do
+    expect([notifier('solaris2').notify('t', 'm'), runner.calls]).to eq([false, []])
+  end
+
+  it 'returns false and warns once when the notification fails, without raising' do
+    runner.exitstatus = 1
+    sender = notifier('linux-gnu')
+
+    expect([sender.notify('t', 'm'), sender.notify('t', 'm')]).to eq([false, false])
+    expect(err.string).to eq("Could not show a desktop notification: no notification server\n")
+  end
+
+  it 'returns false when the runner raises' do
+    allow(runner).to receive(:call).and_raise(IOError, 'closed stream')
+
+    expect(notifier('darwin25').notify('t', 'm')).to be(false)
+    expect(err.string).to include('closed stream')
+  end
+end

data/spec/utilities/flows/os/command_runner_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require_relative '../../../../lib/utilities/flows/os/command_runner'
+
+# Flow specs live under spec/utilities/flows, next to the code in lib/utilities/flows
+RSpec.describe RubyRaider::Flows::Os::CommandRunner do # rubocop:disable RSpec/FilePath
+  let(:runner) { described_class.new }
+  let(:ruby) { RbConfig.ruby }
+
+  it 'captures stdout, stderr and the exit status' do
+    result = runner.call(ruby, '-e', '$stdout.print "out"; $stderr.print "err"; exit 3')
+
+    expect([result.stdout, result.stderr, result.exitstatus, result.success?]).to eq(['out', 'err', 3, false])
+  end
+
+  it 'succeeds on exit 0' do
+    expect(runner.call(ruby, '-e', 'exit 0').success?).to be(true)
+  end
+
+  it 'feeds stdin' do
+    expect(runner.call(ruby, '-e', 'print $stdin.read.upcase', stdin_data: "a b\n").stdout).to eq("A B\n")
+  end
+
+  it 'adds env values to the command environment' do
+    result = runner.call(ruby, '-e', 'print ENV["RAIDER_NOTIFY_TITLE"]', env: { 'RAIDER_NOTIFY_TITLE' => '$(id)' })
+
+    expect(result.stdout).to eq('$(id)')
+  end
+
+  it 'stops a command that runs past the timeout' do
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = runner.call(ruby, '-e', 'sleep 10', timeout: 0.3)
+
+    expect([result.success?, result.stderr]).to eq([false, "#{ruby} took longer than 0.3 s"])
+    expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 5
+  end
+
+  it 'passes arguments without a shell' do
+    hostile = ["'; rm -rf ~; '", '$(id)', '%h', '</string>']
+
+    expect(runner.call(ruby, '-e', 'print ARGV.join("|")', *hostile).stdout).to eq(hostile.join('|'))
+  end
+
+  it 'never runs a single string through a shell' do
+    result = runner.call('echo $(id)')
+
+    expect([result.success?, result.stdout]).to eq([false, ''])
+  end
+
+  it 'returns a failed result for a missing executable' do
+    result = runner.call('/no/such/raider-command', 'x')
+
+    expect([result.success?, result.exitstatus, result.stderr]).to match([false, 127, /raider-command/])
+  end
+end