ruby_raider 4.0.1 → 4.1.0

data/spec/utilities/flows/run_log_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require_relative '../../../lib/utilities/flows/run_log'
+require_relative '../../../lib/utilities/flows/project'
+
+# Flow specs live under spec/utilities/flows, next to the code in lib/utilities/flows
+RSpec.describe RubyRaider::Flows::RunLog do # rubocop:disable RSpec/FilePath
+  let(:dir) { File.realpath(Dir.mktmpdir('flows-log')) }
+  let(:log) { described_class.new(RubyRaider::Flows::Project.new(dir), 'report') }
+  let(:file) { File.join(dir, '.raider/flows/report/runs.jsonl') }
+
+  before { FileUtils.mkdir_p(File.dirname(file)) }
+
+  after { FileUtils.rm_rf(dir) }
+
+  it 'skips broken and non-object lines' do
+    File.write(file, %({"status":"failed"}\nnot json\n[1]\n{"status":"completed","run_id":"a"}\n))
+
+    expect([log.lines.size, log.last['status'], log.find('a')['status']]).to eq([2, 'completed', 'completed'])
+  end
+
+  it 'reads only the last megabyte of a big log, from a whole line' do
+    File.write(file, %({"status":"old","pad":"#{'x' * 2_000_000}"}\n{"status":"completed"}\n))
+
+    expect(log.lines).to eq([{ 'status' => 'completed' }])
+  end
+
+  it 'does not follow a linked log' do
+    File.write(File.join(dir, 'other.jsonl'), %({"status":"completed"}\n))
+    File.symlink(File.join(dir, 'other.jsonl'), file)
+
+    expect(log.lines).to eq([])
+  end
+
+  it 'lists the last run that ran, not a busy line after it' do
+    FileUtils.mkdir_p(File.join(dir, 'flows'))
+    File.write(File.join(dir, 'flows/report_flow.rb'), '')
+    File.write(file, %({"status":"failed"}\n{"status":"busy"}\n))
+
+    expect(described_class.summaries(RubyRaider::Flows::Project.new(dir)).first['last']['status']).to eq('failed')
+  end
+
+  it 'is empty without a log' do
+    expect(log.last).to be_nil
+  end
+end

data/spec/utilities/flows/runner_spec.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'stringio'
+require 'tmpdir'
+require_relative '../../../lib/utilities/flows/runner'
+
+# Flow specs live under spec/utilities/flows, next to the code in lib/utilities/flows
+# The fake spawner needs its call, sleep and outcome lists next to the project and runner
+# rubocop:disable RSpec/MultipleMemoizedHelpers
+RSpec.describe RubyRaider::Flows::Runner do # rubocop:disable RSpec/FilePath
+  let(:dir) { File.realpath(Dir.mktmpdir('flows-runner')) }
+  let(:project) { RubyRaider::Flows::Project.new(dir) }
+  let(:out) { StringIO.new }
+  let(:calls) { [] }
+  let(:sleeps) { [] }
+  let(:outcomes) { [] }
+
+  # Stands in for `bundle exec rspec`: records the call and appends the line flows/support/run.rb would
+  let(:spawner) do
+    lambda do |env, argv, chdir|
+      calls << { env: env, argv: argv, chdir: chdir }
+      line = outcomes.shift || {}
+      unless line == :nothing
+        log = File.join(dir, '.raider/flows/report/runs.jsonl')
+        FileUtils.mkdir_p(File.dirname(log))
+        File.write(log, "#{JSON.generate(line_for(env, line))}\n", mode: 'a')
+      end
+      line == :nothing ? 2 : line.fetch(:code, 0)
+    end
+  end
+
+  let(:runner) { described_class.new(project, out: out, spawner: spawner, sleeper: ->(seconds) { sleeps << seconds }) }
+
+  def line_for(env, line)
+    { 'started_at' => '2026-11-09T08:00:00.000Z', 'finished_at' => '2026-11-09T08:00:12.300Z', 'status' => 'completed',
+      'attempt' => env['RAIDER_FLOW_ATTEMPT'].to_i, 'trigger' => env['RAIDER_FLOW_TRIGGER'],
+      'run_id' => env['RAIDER_FLOW_RUN_ID'], 'results_dir' => 'flow-results/report/20261109T080000Z' }
+      .merge(line.except(:code).transform_keys(&:to_s))
+  end
+
+  def log_statuses = File.readlines(File.join(dir, '.raider/flows/report/runs.jsonl')).map { |l| JSON.parse(l)['status'] }
+
+  before do
+    %w[flows/flow_helper.rb flows/support/run.rb flows/report_flow.rb].each do |file|
+      FileUtils.mkdir_p(File.dirname(File.join(dir, file)))
+      File.write(File.join(dir, file), '')
+    end
+    FileUtils.mkdir_p(File.join(dir, 'flow-results/report/20261109T080000Z'))
+  end
+
+  after { FileUtils.rm_rf(dir) }
+
+  it 'runs the flow file through bundle exec rspec as an argv array, from the project root' do
+    runner.run('report')
+
+    expect(calls.first[:argv]).to eq(['bundle', 'exec', 'rspec', 'flows/report_flow.rb', '--tag', 'flow'])
+    expect(calls.first[:chdir]).to eq(dir)
+  end
+
+  it 'exits 0 and prints the time and results folder when the flow completed' do
+    expect(runner.run('report')).to eq(0)
+    expect(out.string).to eq("Flow report completed in 12.3 s\nResults: flow-results/report/20261109T080000Z\n")
+  end
+
+  it 'exits 1 and names the step when a step failed' do
+    outcomes << { status: 'failed', code: 1, failed_step: { 'number' => 4, 'title' => 'click "Export"', 'line' => 9 } }
+
+    expect(runner.run('report')).to eq(1)
+    expect(out.string).to start_with(%(Flow report failed at step 4 (click "Export")\n))
+  end
+
+  it 'names the line when the flow has no recorded steps' do
+    outcomes << { status: 'failed', code: 1, failed_step: { 'title' => 'exports', 'line' => 9 } }
+
+    runner.run('report')
+
+    expect(out.string).to start_with("Flow report failed at line 9 (exports)\n")
+  end
+
+  it 'exits 2 on a setup error' do
+    outcomes << { status: 'setup_error', code: 1 }
+
+    expect(runner.run('report')).to eq(2)
+    expect(out.string).to start_with("Flow report could not start: see the output above\n")
+  end
+
+  it 'exits 2 when the run left no log line' do
+    outcomes << :nothing
+
+    expect(runner.run('report')).to eq(2)
+    expect(out.string).to eq("Flow report did not record a run (exit 2): see the output above\n")
+  end
+
+  it 'exits 3 without retrying when the flow is already running' do
+    outcomes << { status: 'busy', code: 3, results_dir: nil }
+
+    expect(runner.run('report', retries: 2)).to eq(3)
+    expect([calls.size, sleeps]).to eq([1, []])
+    expect(out.string).to eq("Flow report is already running\n")
+  end
+
+  it 'retries the whole flow 30 s later and exits 0 once it completes' do
+    outcomes.push({ status: 'failed', code: 1 }, { status: 'completed' })
+
+    expect(runner.run('report', retries: 2)).to eq(0)
+    expect(sleeps).to eq([30])
+    expect(calls.map { |call| call[:env]['RAIDER_FLOW_ATTEMPT'] }).to eq(%w[1 2])
+    expect(log_statuses).to eq(%w[failed completed])
+    expect(out.string).to include('Retrying in 30 s (attempt 2 of 3)')
+  end
+
+  it 'gives up after the last retry with the last status' do
+    outcomes.push({ status: 'failed', code: 1 }, { status: 'setup_error', code: 1 })
+
+    expect(runner.run('report', retries: 1)).to eq(2)
+    expect(calls.size).to eq(2)
+  end
+
+  it 'reads each attempt by its own run id, not the last line in the log' do
+    outcomes << { status: 'completed', run_id: 'someone-else' }
+
+    expect(runner.run('report')).to eq(2)
+  end
+
+  it 'passes inputs, trigger and headless through the environment' do
+    runner.run('report', inputs: ['who=ada lovelace', 'note=a=b'], trigger: 'schedule')
+    env = calls.first[:env]
+
+    expect(env).to include('RAIDER_FLOW_NAME' => 'report', 'RAIDER_FLOW_TRIGGER' => 'schedule', 'RAIDER_FLOW_HEADED' => nil,
+                           'HEADLESS' => 'true', 'RETRY_COUNT' => '0',
+                           'RAIDER_INPUT_WHO' => 'ada lovelace', 'RAIDER_INPUT_NOTE' => 'a=b')
+    expect(env['RAIDER_FLOW_RUN_ID']).to match(/\A[0-9a-f]{16}\z/)
+    expect(calls.first[:argv].join(' ')).not_to include('ada')
+  end
+
+  it 'unsets HEADLESS and sets RAIDER_FLOW_HEADED for --headed' do
+    runner.run('report', headed: true)
+
+    expect(calls.first[:env]).to include('RAIDER_FLOW_HEADED' => '1', 'HEADLESS' => nil)
+  end
+
+  it 'exits 2 for a status it does not know' do
+    outcomes << { status: 'running' }
+
+    expect(runner.run('report')).to eq(2)
+  end
+
+  it 'unsets RAIDER_INPUT_* left in the shell and points bundler at the project Gemfile' do
+    ENV['RAIDER_INPUT_STALE'] = 'leak'
+    runner.run('report')
+
+    expect(calls.first[:env]).to include('RAIDER_INPUT_STALE' => nil, 'BUNDLE_GEMFILE' => File.join(dir, 'Gemfile'))
+  ensure
+    ENV.delete('RAIDER_INPUT_STALE')
+  end
+
+  it 'passes the name-built path, not the target of a linked flow file' do
+    File.delete(File.join(dir, 'flows/report_flow.rb'))
+    File.write(File.join(dir, 'flows/a&calc.rb'), '')
+    File.symlink(File.join(dir, 'flows/a&calc.rb'), File.join(dir, 'flows/report_flow.rb'))
+
+    runner.run('report')
+
+    expect(calls.first[:argv]).to include('flows/report_flow.rb')
+  end
+
+  it 'prints control characters from the log as ?' do
+    outcomes << { status: 'failed', code: 1, failed_step: { 'title' => "x\e[2Jy\nFlow fake completed", 'line' => 1 } }
+
+    runner.run('report')
+
+    expect(out.string).to start_with("Flow report failed at line 1 (x?[2Jy?Flow fake completed)\n")
+  end
+
+  describe '--notify' do
+    let(:notes) { [] }
+    let(:notify_result) { [true] }
+    let(:notifier) do
+      sent = notes
+      result = notify_result
+      Class.new do
+        define_method(:notify) do |title, message|
+          sent << [title, message]
+          result.first
+        end
+      end.new
+    end
+    let(:notifying) { described_class.new(project, out: out, spawner: spawner, sleeper: ->(_) {}, notifier: notifier) }
+
+    it 'sends one notification naming the failed step after the last attempt' do
+      2.times { outcomes << { status: 'failed', code: 1, failed_step: { 'number' => 3, 'title' => "Open\e[2J report" } } }
+
+      expect(notifying.run('report', retries: 1, notify: true)).to eq(1)
+      expect(notes).to eq([['Ruby Raider flow report', "Failed at step 3 (Open\e[2J report)"]])
+    end
+
+    it 'points a scheduled run at the scheduler log on a setup error or when no line was recorded' do
+      allow(Gem).to receive(:win_platform?).and_return(false)
+      outcomes.push({ status: 'setup_error', code: 1 }, :nothing)
+      2.times { notifying.run('report', trigger: 'schedule', notify: true) }
+
+      expect(notes.map(&:last)).to eq(['Could not start: see .raider/flows/report/scheduler.log'] * 2)
+    end
+
+    it 'points at the run output when there is no scheduler log: a manual run, or Windows' do
+      outcomes.push({ status: 'setup_error', code: 1 }, { status: 'setup_error', code: 1 })
+      allow(Gem).to receive(:win_platform?).and_return(false)
+      notifying.run('report', notify: true)
+      allow(Gem).to receive(:win_platform?).and_return(true)
+      notifying.run('report', trigger: 'schedule', notify: true)
+
+      expect(notes.map(&:last)).to eq(['Could not start: see the run output'] * 2)
+    end
+
+    it 'stays quiet when the run was stopped' do
+      outcomes << { status: 'failed', code: 1 }
+      stopping = lambda do |*args|
+        described_class.stopped = true
+        spawner.call(*args)
+      end
+      described_class.new(project, out: out, spawner: stopping, sleeper: ->(_) {}, notifier: notifier).run('report', notify: true)
+
+      expect(notes).to eq([])
+    ensure
+      described_class.stopped = false
+    end
+
+    it 'stays quiet when the flow completed or was busy, and without --notify' do
+      outcomes.push({}, { status: 'busy', code: 3 }, { status: 'failed', code: 1 })
+      notifying.run('report', notify: true)
+      notifying.run('report', notify: true)
+      notifying.run('report')
+
+      expect(notes).to eq([])
+    end
+
+    it 'keeps the exit code when the notification fails' do
+      notify_result[0] = false
+      outcomes << { status: 'failed', code: 1 }
+
+      expect([notifying.run('report', notify: true), notes.size]).to eq([1, 1])
+    end
+  end
+
+  describe 'refusals (exit 2 through Flows::Error, nothing spawned)' do
+    def refuse(name, message, **options)
+      expect { runner.run(name, **options) }.to raise_error(RubyRaider::Flows::Error, message)
+      expect(calls).to be_empty
+    end
+
+    it('rejects an input name that is not lower snake case') { refuse('report', /Invalid input "WHO"/, inputs: ['WHO=x']) }
+    it('rejects an input without a value') { refuse('report', /Invalid input "who"/, inputs: ['who']) }
+    it('rejects retries above 3') { refuse('report', /Invalid retries 4/, retries: 4) }
+    it('rejects an unknown trigger') { refuse('report', /Invalid trigger/, trigger: 'cron') }
+    it('rejects an unsafe flow name') { refuse('../report', /Invalid flow name/) }
+    it('rejects the reserved name env') { refuse('env', /Invalid flow name "env"/) }
+    it('rejects a NUL byte in an input value') { refuse('report', /NUL byte/, inputs: ["who=a\0b"]) }
+
+    it 'rejects a project without flow init' do
+      File.delete(File.join(dir, 'flows/support/run.rb'))
+
+      refuse('report', /run raider flow init/)
+    end
+  end
+
+  describe '.spawn' do
+    it 'runs without a shell and returns the exit status' do
+      code = described_class.spawn({ 'X' => '; exit 7' }, [RbConfig.ruby, '-e', 'exit(ENV["X"] == "; exit 7" ? 5 : 6)'], dir)
+
+      expect(code).to eq(5)
+    end
+
+    it 'passes INT or TERM to the flow once, as INT, and marks the run stopped', skip: Gem.win_platform? do
+      ready = File.join(dir, 'ready')
+      got = File.join(dir, 'got')
+      child = "n = 0; trap('INT') { n += 1 }; trap('TERM') { n += 100 }; File.write(#{ready.inspect}, ''); " \
+              "sleep 1.5; File.write(#{got.inspect}, n.to_s)"
+      Thread.new do
+        sleep 0.05 until File.exist?(ready)
+        Process.kill('TERM', Process.pid)
+        Process.kill('INT', Process.pid)
+      end
+
+      code = described_class.spawn({}, [RbConfig.ruby, '-e', child], dir)
+
+      expect([code, File.read(got), described_class.stopped]).to eq([0, '1', true])
+    end
+
+    it 'does not retry a stopped run' do
+      outcomes.push({ status: 'setup_error', code: 1 }, { status: 'completed' })
+      stopping = lambda do |*args|
+        described_class.stopped = true
+        spawner.call(*args)
+      end
+      stopped_runner = described_class.new(project, out: out, spawner: stopping, sleeper: ->(seconds) { sleeps << seconds })
+
+      expect(stopped_runner.run('report', retries: 2)).to eq(2)
+      expect([calls.size, sleeps]).to eq([1, []])
+      expect(out.string).to include('Flow report was stopped: no retry')
+    ensure
+      described_class.stopped = false
+    end
+
+    it 'returns nil with one line on stderr when the command is not found' do
+      code = nil
+
+      expect { code = described_class.spawn({}, ['raider-no-such-command'], dir) }.to output(/Could not start raider-no-such-command/).to_stderr
+      expect(code).to be_nil
+    end
+  end
+end
+# rubocop:enable RSpec/MultipleMemoizedHelpers

data/spec/utilities/flows/schedule_spec.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'digest'
+require_relative '../../../lib/utilities/flows/schedule'
+
+# Flow specs live under spec/utilities/flows, next to the code in lib/utilities/flows
+RSpec.describe RubyRaider::Flows::Schedule do # rubocop:disable RSpec/FilePath
+  let(:dir) { File.realpath(Dir.mktmpdir('flows-schedule')) }
+  let(:project) { RubyRaider::Flows::Project.new(dir) }
+  let(:now) { Time.utc(2026, 11, 9, 10, 0, 0) }
+
+  def build(**options)
+    described_class.build(project: project, name: 'report', every: 'day', at: '08:00', now: now, **options)
+  end
+
+  def error_for(**options)
+    build(**options)
+  rescue RubyRaider::Flows::Error => e
+    e.message
+  end
+
+  after { FileUtils.rm_rf(dir) }
+
+  describe 'rules' do
+    it 'reads the hour and minute and spells the rule' do
+      schedule = build(at: '18:05')
+
+      expect([schedule.hour, schedule.minute, schedule.at, schedule.rule_text]).to eq([18, 5, '18:05', 'every day at 18:05'])
+    end
+
+    it 'takes :MM or HH:MM for every hour, ignores the hour and defaults to :00' do
+      texts = [':15', '07:15', nil].map { |at| build(every: 'hour', at: at) }.map { |s| [s.at, s.rule_text] }
+
+      expect(texts).to eq([['00:15', 'every hour at :15'], ['00:15', 'every hour at :15'], ['00:00', 'every hour at :00']])
+    end
+
+    it 'runs every day and every hour on all days, weekdays mon to fri, a week on its day' do
+      days = [build, build(every: 'hour', at: ':00'), build(every: 'weekday'), build(every: 'week', on: 'wed')].map(&:days)
+
+      expect(days).to eq([%w[mon tue wed thu fri sat sun], %w[mon tue wed thu fri sat sun], %w[mon tue wed thu fri], %w[wed]])
+    end
+
+    it 'spells weekday and week rules' do
+      expect([build(every: 'weekday').rule_text, build(every: 'week', on: 'mon').rule_text]).to eq(['every weekday at 08:00', 'every week on mon at 08:00'])
+    end
+
+    it 'refuses an unknown every' do
+      expect(error_for(every: 'month')).to include('use hour, day, weekday or week')
+    end
+
+    it 'refuses a missing or malformed at for day, weekday and week' do
+      errors = [nil, '8:00', '24:00', '08:60', '08:00x', ':15'].map { |at| error_for(at: at) }
+
+      expect(errors).to all(include('HH:MM'))
+    end
+
+    it 'refuses a malformed at for every hour' do
+      expect([error_for(every: 'hour', at: ':60'), error_for(every: 'hour', at: '25:00')]).to all(include(':MM'))
+    end
+
+    it 'needs on for every week and refuses it otherwise' do
+      expect([error_for(every: 'week'), error_for(every: 'week', on: 'monday'), error_for(on: 'mon')]).to eq(
+        ['Every week needs on: use mon, tue, wed, thu, fri, sat or sun',
+         'Invalid on "monday": use mon, tue, wed, thu, fri, sat or sun',
+         'on is only for every week']
+      )
+    end
+
+    it 'takes retries 0 to 3' do
+      expect([build(retries: 3).retries, error_for(retries: 4), error_for(retries: '1')]).to eq([3, 'Invalid retries 4: use 0 to 3', 'Invalid retries "1": use 0 to 3'])
+    end
+
+    it 'refuses a bad flow name' do
+      expect(error_for(name: '../x')).to include('Invalid flow name')
+    end
+
+    it 'refuses bad input names and values with control characters' do
+      errors = [['Bad=1'], ['nokey'], ["note=a\nb"], ["note=a\tb"], ["note=a\0b"]].map { |inputs| error_for(inputs: inputs) }
+
+      expect(errors).to all(start_with('Invalid input'))
+    end
+
+    it 'refuses input that is not valid UTF-8' do
+      expect([error_for(inputs: ["note=a\xFFb"]), error_for(inputs: ["n\xFFte=ab"])]).to all(include('valid UTF-8'))
+    end
+
+    it 'keeps hostile input values as plain argv items' do
+      values = ["'; rm -rf ~; '", '</string>', '%h', '$(id)']
+      schedule = build(inputs: values.map { |value| "note=#{value}" })
+
+      expect(schedule.argv.last(4)).to eq(values.map { |value| "note=#{value}" })
+    end
+  end
+
+  describe 'the OS entry' do
+    it 'names the entry from the project realpath and the flow name' do
+      digest = Digest::SHA256.hexdigest(dir)[0, 10]
+
+      expect([build.os_id, described_class.os_id_for(dir, 'report')]).to eq(["dev.rubyraider.flow.#{digest}.report"] * 2)
+    end
+
+    it 'runs raider flow run under the absolute ruby and bundle' do
+      expect(build.argv).to eq([RbConfig.ruby, Gem.bin_path('bundler', 'bundle'), 'exec', 'raider', 'flow', 'run', 'report',
+                                '--project', dir, '--trigger', 'schedule'])
+    end
+
+    it 'adds retries only above 0 and --input with each pair' do
+      expect(build(retries: 2, inputs: %w[a=1 b=2]).argv.last(5)).to eq(%w[--retries 2 --input a=1 b=2])
+    end
+
+    it 'adds --notify before the inputs when the schedule notifies' do
+      expect(build(notify: true, retries: 1, inputs: %w[a=1]).argv.last(5)).to eq(%w[--retries 1 --notify --input a=1])
+      expect(build.argv).not_to include('--notify')
+    end
+
+    it 'refuses with a Flows::Error when bundler is not installed for this Ruby' do
+      [Gem::GemNotFoundException.new('no bundler'), Gem::MissingSpecError.new('bundler', '>= 0')].each do |error|
+        allow(Gem).to receive(:bin_path).with('bundler', 'bundle').and_raise(error)
+
+        expect(error_for).to start_with('Bundler not found for this Ruby')
+      end
+    end
+
+    it 'runs in the project and logs to the flow folder' do
+      expect([build.working_directory, build.log_path]).to eq([dir, File.join(dir, '.raider/flows/report/scheduler.log')])
+    end
+
+    it 'records when it was made' do
+      expect(build.created_at).to eq('2026-11-09T10:00:00Z')
+    end
+
+    it 'leaves the given time as it was' do
+      local = Time.local(2026, 11, 9, 11, 0, 0)
+      offset = local.utc_offset
+      build(now: local)
+
+      expect([local.utc?, local.utc_offset]).to eq([false, offset])
+    end
+
+    it 'is frozen' do
+      schedule = build(inputs: %w[a=1])
+
+      expect([schedule, schedule.inputs, schedule.gem_env]).to all(be_frozen)
+    end
+  end
+
+  describe 'the env' do
+    let(:bin) { File.dirname(RbConfig.ruby) }
+
+    it 'captures GEM_HOME and GEM_PATH from the env Bundler started with' do
+      allow(Bundler).to receive(:original_env).and_return('GEM_HOME' => '/gems/home', 'GEM_PATH' => '/gems/home:/gems/more', 'OTHER' => 'x')
+
+      expect(build.env).to include('GEM_HOME' => '/gems/home', 'GEM_PATH' => '/gems/home:/gems/more', 'LANG' => 'en_US.UTF-8')
+    end
+
+    it 'leaves GEM_HOME and GEM_PATH out when they are not set' do
+      allow(Bundler).to receive(:original_env).and_return('GEM_HOME' => '', 'PATH' => '/x')
+
+      expect([build.gem_env, build.env.keys.sort]).to eq([{}, %w[LANG PATH]])
+    end
+
+    it 'reads ENV when Bundler is not loaded' do
+      hide_const('Bundler')
+      stub_const('ENV', { 'GEM_HOME' => '/env/home' })
+
+      expect(build.gem_env).to eq('GEM_HOME' => '/env/home')
+    end
+
+    it 'puts the ruby and bundle folders on PATH before the system ones, once each' do
+      folders = [bin, File.dirname(Gem.bin_path('bundler', 'bundle')), '/usr/bin', '/bin'].uniq
+
+      expect(build.env['PATH']).to eq(folders.join(File::PATH_SEPARATOR))
+    end
+  end
+
+  it 'refuses to build for a project folder with a control character in its path' do
+    odd = File.join(dir, "line\nbreak")
+    FileUtils.mkdir_p(odd)
+    project = RubyRaider::Flows::Project.new(odd)
+
+    expect { described_class.build(project: project, name: 'report', every: 'day', at: '08:00', now: now) }
+      .to raise_error(RubyRaider::Flows::Error, /Invalid project_root/)
+  end
+
+  describe 'the yml shape' do
+    let(:schedule) { build(every: 'week', on: 'fri', retries: 1, inputs: %w[a=1]) }
+
+    it 'writes string keys' do
+      expect(schedule.to_h.keys).to eq(%w[name every at on retries inputs notify os_id ruby bundle gem_env created_at])
+    end
+
+    it 'reads back what it wrote' do
+      expect(described_class.from_h(schedule.to_h, dir).to_h).to eq(schedule.to_h)
+    end
+
+    it 'refuses an entry whose os_id is not this project\'s, or not in lowercase hex' do
+      upper = schedule.os_id.sub(/\.(\h{10})\./) { ".#{Regexp.last_match(1).upcase}." }
+
+      expect { described_class.from_h(schedule.to_h, '/elsewhere') }.to raise_error(RubyRaider::Flows::Error, /os_id/)
+      expect { described_class.from_h(schedule.to_h.merge('os_id' => upper), dir) }.to raise_error(RubyRaider::Flows::Error, /os_id/)
+    end
+
+    it 'refuses entries that were tampered with' do
+      bad = [{ 'every' => 'yearly' }, { 'os_id' => 'evil; id' }, { 'ruby' => 'ruby' }, { 'gem_env' => { 'RUBYOPT' => '-rx' } },
+             { 'inputs' => ["a=\n"] }, { 'name' => nil }, { 'created_at' => 5 }]
+
+      bad.each do |change|
+        expect { described_class.from_h(schedule.to_h.merge(change), dir) }.to raise_error(RubyRaider::Flows::Error)
+      end
+    end
+
+    it 'refuses a project root with a control character or invalid UTF-8' do
+      roots = ["/p/a\nb", "/p/a\tb", "/p/\e[2J", "/p/\xFF".dup.force_encoding(Encoding::UTF_8), 'relative']
+
+      roots.each do |root|
+        expect { described_class.from_h(schedule.to_h, root) }.to raise_error(RubyRaider::Flows::Error, /project_root/)
+      end
+    end
+
+    it 'keeps notify, and reads an entry written before notify as off' do
+      notifying = build(notify: true)
+
+      expect(described_class.from_h(notifying.to_h, dir).notify).to be(true)
+      expect(described_class.from_h(schedule.to_h.except('notify'), dir).notify).to be(false)
+      expect { described_class.from_h(schedule.to_h.merge('notify' => 'yes'), dir) }.to raise_error(RubyRaider::Flows::Error, /notify/)
+    end
+
+    it 'refuses a non-hash' do
+      expect { described_class.from_h('x', dir) }.to raise_error(RubyRaider::Flows::Error)
+    end
+  end
+end