woods 2.0.0.beta3 → 2.0.0

data/lib/woods/watch/event_stream.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Watch
+    # Bounded framing plus the guardian-issued child identity used for cleanup.
+    class EventStream
+      MAX_BYTES = 4096
+
+      def initialize(reader:, guardian:, launcher:, attempt:)
+        @reader = reader
+        @guardian = guardian
+        @identity = { 'launcher' => launcher, 'attempt' => attempt, 'pid' => guardian, 'event' => 'spawned' }
+        @buffer = +''
+      end
+
+      attr_reader :child_pid
+
+      def read
+        records = []
+        return records if @reader.closed?
+
+        16.times do
+          part = @reader.read_nonblock(MAX_BYTES, exception: false)
+          break if part == :wait_readable
+          return finish(records) if part.nil?
+
+          @buffer << part
+          drain_lines(records)
+        end
+        records
+      end
+
+      def eof?
+        @eof == true
+      end
+
+      private
+
+      def finish(records)
+        @eof = true
+        raise ArgumentError, 'truncated Woods lifecycle record' unless @buffer.empty?
+
+        records
+      end
+
+      def drain_lines(records)
+        while @buffer.include?("\n")
+          record = @buffer.slice!(0..@buffer.index("\n"))
+          raise ArgumentError, 'oversized Woods lifecycle record' if record.bytesize > MAX_BYTES
+
+          remember_child(record)
+          records << record
+        end
+        raise ArgumentError, 'oversized Woods lifecycle record' if @buffer.bytesize > MAX_BYTES
+      end
+
+      def remember_child(line)
+        record = JSON.parse(line)
+        return unless record.is_a?(Hash) && @identity.all? { |key, value| record[key] == value }
+
+        child = record['child_pid']
+        @child_pid = child if child.is_a?(Integer) && child.positive?
+      rescue JSON::ParserError
+        nil # The lifecycle validator reports malformed records.
+      end
+    end
+  end
+end

data/lib/woods/watch/guardian.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'io/wait'
+
+module Woods
+  module Watch
+    # Minimal pre-Bundler owner. EOF on its private parent pipe always stops
+    # the owned application group, even while an initializer is blocked.
+    class Guardian
+      # @param parent [IO] private parent-liveness reader
+      # @param events [IO] lifecycle writer
+      # @param config [Hash] argument vector and child environment
+      def initialize(parent:, events:, config:)
+        @parent = parent
+        @events = events
+        @config = config
+        @events.sync = true
+        @stopping = false
+      end
+
+      # @return [Integer] application exit status, or launch failure
+      def run
+        %w[INT TERM].each { |signal| Signal.trap(signal) { @stopping = true } }
+        report('hello')
+        spawn_child
+        monitor
+        report('exit', code: @status&.exitstatus, signal: @status&.termsig)
+        @status&.exitstatus || 1
+      rescue SystemCallError => e
+        report('spawn_error', reason: e.class.name.split('::').last)
+        127
+      ensure
+        terminate_group
+      end
+
+      private
+
+      def spawn_child
+        gate, release = IO.pipe
+        @child = fork do
+          release.close
+          @parent.close
+          Process.setpgrp
+          exit! 1 unless gate.read(1) == 'S'
+
+          gate.close
+          exec_child
+        end
+        gate.close
+        report('spawned', child_pid: @child)
+        release.write('S') if acknowledged?
+      ensure
+        release&.close unless release&.closed?
+      end
+
+      # Do not execute application code until its owner knows the child group.
+      # Guardian death before acknowledgment closes the exec gate with EOF.
+      def acknowledged?
+        until @stopping || Process.ppid != @config.fetch('owner_pid')
+          next unless @parent.wait_readable(0.05)
+
+          return @parent.read(1) == 'S'
+        end
+        false
+      end
+
+      def exec_child
+        options = { chdir: @config.fetch('root'), in: File::NULL, close_others: true, unsetenv_others: true }
+        options[3] = @events if @config['events']
+        command = @config.fetch('command')
+        Process.exec(@config.fetch('env'), [command.first, command.first], *command.drop(1), **options)
+      rescue SystemCallError => e
+        warn "[woods-watch] child executable could not start (#{e.class})"
+        exit! 127
+      end
+
+      def monitor
+        until @stopping
+          break if Process.ppid != @config.fetch('owner_pid')
+
+          result = Process.waitpid2(@child, Process::WNOHANG)
+          if result
+            @status = result.last
+            return
+          end
+          @stopping = true if @parent.wait_readable(0.05) && @parent.read_nonblock(1, exception: false).nil?
+        end
+        terminate_group
+      end
+
+      def terminate_group
+        return unless @child && !@terminated
+
+        signal_group('TERM')
+        await_child
+        signal_group('KILL')
+        @status ||= Process.waitpid2(@child).last
+        @terminated = true
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def await_child
+        deadline = monotonic + @config.fetch('shutdown_timeout')
+        until @status || monotonic >= deadline
+          @status = Process.waitpid2(@child, Process::WNOHANG)&.last
+          sleep 0.02 unless @status
+        end
+      end
+
+      def signal_group(signal)
+        Process.kill(signal, -@child)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def report(event, **fields)
+        record = { version: 1, event: event, pid: Process.pid,
+                   launcher: @config['launcher'], attempt: @config['attempt'] }.merge(fields)
+        @events.write(JSON.generate(record) << "\n")
+      rescue Errno::EPIPE
+        @stopping = true
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  config_io = IO.for_fd(5)
+  config = JSON.parse(config_io.read)
+  config_io.close
+  parent = IO.for_fd(4)
+  events = IO.for_fd(3, 'w')
+  parent.close_on_exec = true
+  events.close_on_exec = true
+  exit Woods::Watch::Guardian.new(parent: parent, events: events, config: config).run
+end

data/lib/woods/watch/installation/layout.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../../agent_configuration/document'
+
+module Woods
+  module Watch
+    class Installation
+      # Absolute paths are transient apply state; receipts retain only relative paths.
+      class Layout
+        RECEIPT = '.woods-watch.json'
+        WRAPPER = 'bin/woods-watch'
+        PUMA = 'config/puma.rb'
+        PROCFILE = /\AProcfile(?:\.[a-zA-Z0-9_-]+)?\z/
+
+        attr_reader :root
+
+        # @param root [String] canonical application root
+        # @param procfile [String] selected root-level Procfile
+        def initialize(root, procfile)
+          @root = root
+          @procfile = procfile
+          @extra_paths = []
+        end
+
+        # @param path [String] portable target path
+        # @return [String] checked absolute path
+        def absolute(path)
+          unless [RECEIPT, WRAPPER, PUMA].include?(path) || (path.is_a?(String) && PROCFILE.match?(path))
+            raise Conflict, "Unsupported watcher installation target: #{path.inspect}"
+          end
+
+          File.join(root, path)
+        end
+
+        # @param paths [Array<String>] prior owned paths read from the receipt
+        # @return [void]
+        def include_previous(paths)
+          @extra_paths = paths.map { |path| absolute(path) }
+        end
+
+        # @return [Array<String>] exact allowed write set
+        def allowed_paths
+          ([RECEIPT, WRAPPER, PUMA, @procfile].map { |path| absolute(path) } + @extra_paths).uniq
+        end
+
+        # @return [String] local journal stem, separate from the portable receipt
+        def receipt_path
+          File.join(root, 'tmp', 'woods-watch-install', 'transaction')
+        end
+
+        # @return [Array<String>] local serialization lock
+        def lock_paths
+          ["#{receipt_path}.lock"]
+        end
+
+        # @return [Hash] transient preview identity, never committed to the receipt
+        def identity
+          { 'kind' => 'woods-watch-installation', 'root' => root, 'procfile' => @procfile }
+        end
+
+        # @param path [String] portable target path
+        # @return [Woods::AgentConfiguration::Document]
+        def document(path)
+          Woods::AgentConfiguration::Document.new(absolute(path))
+        end
+      end
+    end
+  end
+end

data/lib/woods/watch/installation/options.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Woods
+  module Watch
+    class Installation
+      # Restricts automatic edits to explicit, verified startup arrangements.
+      class Options
+        attr_reader :root, :mode, :operation, :child_command, :manager_command, :procfile
+
+        # @param root [String] application root
+        # @param options [Hash] installation choices and injectable probe/environment
+        def initialize(root:, **options)
+          @root = File.realpath(root)
+          @mode = options.fetch(:mode, nil)
+          @operation = options.fetch(:operation, 'setup')
+          @child_command = argv(options.fetch(:child_command, %w[bin/rails woods:watch]))
+          @manager_command = options[:manager_command] && argv(options[:manager_command])
+          @procfile = options.fetch(:procfile, 'Procfile.dev')
+          @environment = options.fetch(:environment, ENV)
+          @probe = options.fetch(:probe) { Probe.new(environment: @environment) }
+        end
+
+        # @return [void]
+        def validate!
+          validate_selection!
+          raise Conflict, 'Select a root-level Procfile explicitly' unless Layout::PROCFILE.match?(procfile.to_s)
+          return if operation == 'remove'
+
+          raise Conflict, 'Application Gemfile is missing' unless File.file?(File.join(root, 'Gemfile'))
+
+          validate_child!
+          validate_idle!
+          validate_manager! if mode == 'procfile'
+          validate_puma! if mode == 'puma'
+          @probe.call(root: root, child_command: child_command,
+                      manager_command: mode == 'procfile' ? manager_command : nil, puma: mode == 'puma')
+        end
+
+        # @return [Hash] portable selection persisted in the receipt
+        def selection
+          { 'mode' => mode, 'child_command' => child_command,
+            'manager_command' => mode == 'procfile' ? manager_command : nil,
+            'procfile' => mode == 'procfile' ? procfile : nil }
+        end
+
+        # @return [String] truthful startup handoff, separate from validation evidence
+        def handoff
+          case mode
+          when 'external'
+            "Configure one external supervisor to run: #{Shellwords.join(child_command)}; retain raw exit-75 recovery."
+          when 'procfile'
+            "Start with #{Shellwords.join(manager_command)}. bin/dev was preserved; verify catch-up and an edit."
+          else
+            'Start with bin/rails server using config/puma.rb; custom -C startup is unsupported. ' \
+            'Verify catch-up and an edit; other environments start no watcher.'
+          end
+        end
+
+        private
+
+        def argv(value)
+          items = value.is_a?(String) ? Shellwords.split(value) : value
+          unless items.is_a?(Array) && !items.empty? && items.all? { |arg| valid_argument?(arg) }
+            raise Conflict, 'Commands must be nonempty argument vectors, not shell scripts'
+          end
+
+          items
+        rescue ArgumentError => e
+          raise Conflict, "Invalid command arguments: #{e.message}"
+        end
+
+        def valid_argument?(argument)
+          argument.is_a?(String) && !argument.empty? && !argument.include?("\0")
+        end
+
+        def validate_selection!
+          unless %w[setup update remove].include?(operation)
+            raise Conflict, 'Supported operations: setup, update, remove'
+          end
+          return if operation == 'remove' || %w[procfile puma external].include?(mode)
+
+          raise Conflict, 'Select mode procfile, puma, or external explicitly'
+        end
+
+        def validate_child!
+          return if child_command.last == 'woods:watch'
+
+          raise Conflict, 'Child command must end with woods:watch so preflight can verify the installed task with -T'
+        end
+
+        def validate_idle!
+          value = @environment['WOODS_WATCH_IDLE_TIMEOUT']
+          return if mode == 'external' || value.nil? || value.empty?
+
+          raise Conflict, 'Unset WOODS_WATCH_IDLE_TIMEOUT; managed maintenance needs a resident child'
+        end
+
+        def validate_manager!
+          unless valid_manager?
+            raise Conflict, 'Select verified Foreman startup with -f matching the Procfile; ' \
+                            'plain Rails bin/dev needs Puma mode'
+          end
+          document = Woods::AgentConfiguration::Document.new(File.join(root, procfile))
+          raise Conflict, "Selected Procfile does not exist: #{procfile}" unless document.content
+        end
+
+        def validate_puma!
+          return unless File.exist?(File.join(root, 'config/puma/development.rb'))
+
+          raise Conflict, 'Puma selects config/puma/development.rb before config/puma.rb; ' \
+                          'use external/Foreman mode for custom Puma configuration'
+        end
+
+        def valid_manager?
+          args = manager_command
+          return false unless args
+
+          args = args.drop(2) if args.first(2) == %w[bundle exec]
+          return false unless args.length == 4 && File.basename(args[0]) == 'foreman'
+
+          args[1] == 'start' && %w[-f --procfile].include?(args[2]) && args[3] == procfile
+        end
+      end
+    end
+  end
+end

data/lib/woods/watch/installation/planner.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative 'templates'
+require_relative 'receipt'
+
+module Woods
+  module Watch
+    class Installation
+      # Builds one conflict-checked transaction while preserving unowned bytes.
+      class Planner
+        # @param layout [Layout] destination and local transaction paths
+        # @param options [Options] preflight-validated selections
+        def initialize(layout:, options:)
+          @layout = layout
+          @options = options
+          @documents = {}
+          @contents = {}
+          @modes = {}
+        end
+
+        # @return [Woods::AgentConfiguration::Plan] complete preview
+        def call
+          @receipt = Receipt.new(document(Layout::RECEIPT))
+          @layout.include_previous(@receipt.paths)
+          @plan = Woods::AgentConfiguration::Plan.new(layout: @layout, operation: @options.operation)
+          validate_operation!
+          remove_previous
+          install unless @options.operation == 'remove'
+          publish_plan
+        end
+
+        private
+
+        def validate_operation!
+          previous = @receipt.data
+          if @options.operation == 'update' && !previous
+            raise Conflict, 'No owned watcher installation to update; run setup first'
+          end
+          return unless previous && @options.operation == 'setup' && previous.fetch('selection') != @options.selection
+
+          raise Conflict, 'Watcher setup selection changed; use --operation update to switch modes or commands'
+        end
+
+        def document(path)
+          @documents[path] ||= @layout.document(path)
+        end
+
+        def content(path)
+          @contents.key?(path) ? @contents[path] : document(path).content
+        end
+
+        def remove_previous
+          return unless @receipt.data
+
+          @receipt.data.fetch('files').each do |path, expected|
+            Receipt.verify_file!(document(path), expected)
+            @contents[path] = nil
+          end
+          @receipt.data.fetch('sections').each { |path, record| remove_section(path, record) }
+          @contents[Layout::RECEIPT] = nil
+        end
+
+        def remove_section(path, record)
+          text = document(path).content || ''
+          block = record.fetch('owned_text')
+          unless text.scan(Templates::START).size == 1 && text.scan(Templates::FINISH).size == 1 && text.include?(block)
+            raise Conflict, "Owned watcher section was edited or removed: #{path}"
+          end
+
+          remaining = text.sub(block, '')
+          @contents[path] = record.fetch('created_file') && remaining.empty? ? nil : remaining
+        end
+
+        def install
+          @new_receipt = { 'schema_version' => 1, 'selection' => @options.selection, 'files' => {}, 'sections' => {} }
+          if @options.mode != 'external'
+            install_wrapper
+            install_section
+          end
+          @contents[Layout::RECEIPT] = "#{JSON.pretty_generate(@new_receipt)}\n"
+          @modes[Layout::RECEIPT] = 0o644
+        end
+
+        def install_wrapper
+          path = Layout::WRAPPER
+          raise Conflict, 'Refusing to overwrite an unowned bin/woods-watch' if content(path)
+
+          text = Templates.wrapper(@options.child_command)
+          @contents[path] = text
+          @modes[path] = 0o755
+          @new_receipt.fetch('files')[path] = { 'sha256' => Digest::SHA256.hexdigest(text), 'mode' => 0o755, 'exists' => true }
+        end
+
+        def install_section
+          path = @options.mode == 'puma' ? Layout::PUMA : @options.procfile
+          text = content(path) || ''
+          reject_unowned_section!(text)
+          previous = @receipt.data&.dig('sections', path, 'owned_text')
+          block = Templates.section(@options.mode, text, previous: previous, update: @options.operation == 'update')
+          @contents[path] = previous ? document(path).content.sub(previous, block) : text + block
+          @modes[path] = document(path).content ? document(path).mode : 0o644
+          @new_receipt.fetch('sections')[path] = { 'owned_text' => block, 'created_file' => content_created?(path) }
+        end
+
+        def content_created?(path)
+          @receipt.data&.dig('sections', path, 'created_file') || document(path).content.nil?
+        end
+
+        def reject_unowned_section!(text)
+          conflict = text.include?(Templates::START) || text.include?(Templates::FINISH)
+          pattern = @options.mode == 'puma' ? /^\s*plugin(?:\s+|\s*\(\s*)[:'"]woods\b/ : /^\s*woods\s*:/
+          conflict ||= text.match?(pattern)
+          raise Conflict, 'Unowned Woods startup directive or managed markers already exist' if conflict
+        end
+
+        def publish_plan
+          @contents.each do |path, text|
+            current = document(path)
+            @plan.add(current, text, description: "#{@options.operation} Woods watcher ownership in #{path}")
+            change = @plan.data.fetch('changes').find { |entry| entry['path'] == current.path }
+            change['mode'] = @modes.fetch(path, current.mode) if change && text
+          end
+          @plan
+        end
+      end
+    end
+  end
+end

data/lib/woods/watch/installation/probe.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+require_relative '../child_environment'
+
+module Woods
+  module Watch
+    class Installation
+      # Read-only, bounded task and manager checks; never starts the watch task.
+      class Probe
+        PUMA_CHECK = <<~RUBY
+          require 'puma'
+          version = Gem.loaded_specs.fetch('puma').version
+          supported = version >= Gem::Version.new('6') && version < Gem::Version.new('9') &&
+                      !RUBY_PLATFORM.match?(/mswin|mingw|cygwin|java/)
+          abort 'Supported Puma 6/7/8 on a native Unix Ruby is required; use external supervision' unless supported
+          puts version
+        RUBY
+
+        # @param environment [Hash] selected application environment
+        # @param timeout [Numeric] deadline for each task/manager probe
+        def initialize(environment: ENV, timeout: 30)
+          @environment = environment
+          @timeout = timeout
+        end
+
+        # @param root [String] application root
+        # @param child_command [Array<String>] argv ending in woods:watch
+        # @param manager_command [Array<String>, nil] verified Foreman start argv
+        # @param puma [Boolean] verify installed supported Puma in the application bundle
+        # @return [true]
+        def call(root:, child_command:, manager_command: nil, puma: false)
+          output = run(root, child_command[0...-1] + ['-T', 'woods:watch'])
+          unless output.match?(/\bwoods:watch\b/)
+            raise Conflict, 'Selected application command does not expose woods:watch; select its Rails task entrypoint'
+          end
+
+          run(root, manager_command[0...-3] + ['--version']) if manager_command
+          run(root, ['bundle', 'exec', Gem.ruby, '-e', PUMA_CHECK]) if puma
+          true
+        end
+
+        private
+
+        def run(root, command)
+          Open3.popen3(probe_environment(root), *command, chdir: root, pgroup: true,
+                                                          unsetenv_others: true) do |input, output, error, child|
+            input.close
+            collect(output, error, child)
+          end
+        rescue SystemCallError => e
+          raise Conflict, "Startup preflight could not run: #{e.message}"
+        end
+
+        def probe_environment(root)
+          environment = ChildEnvironment.build(@environment.to_h, root: root)
+          environment['BUNDLE_GEMFILE'] ||= File.join(root, 'Gemfile')
+          # A caller-selected lockfile without Bundler's activation markers is
+          # explicit configuration too; otherwise prefer the restored original.
+          unless @environment.key?('BUNDLER_ORIG_BUNDLE_LOCKFILE')
+            environment['BUNDLE_LOCKFILE'] ||= @environment['BUNDLE_LOCKFILE']
+          end
+          environment['BUNDLE_LOCKFILE'] ||= "#{environment['BUNDLE_GEMFILE']}.lock"
+          environment.merge('BUNDLE_FROZEN' => 'true')
+        end
+
+        def collect(output, error, child)
+          readers = [output, error].map { |io| Thread.new { bounded_read(io) } }
+          Timeout.timeout(@timeout) do
+            result, diagnostic = readers.map(&:value)
+            raise Conflict, "Startup preflight failed: #{diagnostic.strip}" unless child.value.success?
+
+            result
+          end
+        rescue Timeout::Error
+          raise Conflict, "Startup preflight exceeded #{@timeout}s; inspect the application task command"
+        ensure
+          terminate(child.pid)
+          readers.each(&:kill)
+        end
+
+        def bounded_read(io)
+          output = String.new
+          loop do
+            output << io.readpartial(16_384)
+            raise Conflict, 'Startup preflight exceeded 1 MiB of output' if output.bytesize > 1_048_576
+          end
+        rescue EOFError
+          output
+        end
+
+        def terminate(pid)
+          Process.kill('KILL', -pid)
+        rescue Errno::ESRCH
+          nil
+        end
+      end
+    end
+  end
+end