woods 2.0.0.beta4 → 2.0.1

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

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Woods
+  module Watch
+    class Installation
+      # Validates portable ownership before any current file is changed.
+      class Receipt
+        attr_reader :data
+
+        # @param document [Woods::AgentConfiguration::Document] portable receipt
+        def initialize(document)
+          @data = document.content && document.json
+          validate! if data
+        end
+
+        # @return [Array<String>] portable paths recorded by this installation
+        def paths
+          return [] unless data
+
+          data.fetch('files').keys + data.fetch('sections').keys
+        end
+
+        # @param document [Woods::AgentConfiguration::Document] owned file
+        # @param expected [Hash] prior content fingerprint and mode
+        # @return [void]
+        def self.verify_file!(document, expected)
+          return if document.fingerprint == expected
+
+          raise Conflict, "Owned watcher file was edited or removed: #{document.path}"
+        end
+
+        private
+
+        def validate!
+          unless data['schema_version'] == 1 && data['selection'].is_a?(Hash) &&
+                 %w[procfile puma external].include?(data.dig('selection', 'mode')) &&
+                 data['files'].is_a?(Hash) && data['sections'].is_a?(Hash)
+            raise Conflict, 'Malformed watcher installation receipt; restore its owned metadata'
+          end
+
+          validate_files!
+          validate_sections!
+        end
+
+        def validate_files!
+          data.fetch('files').each do |path, record|
+            next if path == Layout::WRAPPER && valid_file_record?(record)
+
+            raise Conflict, 'Invalid owned watcher executable in receipt'
+          end
+        end
+
+        def validate_sections!
+          data.fetch('sections').each do |path, record|
+            valid_path = path == Layout::PUMA || Layout::PROCFILE.match?(path)
+            next if valid_path && valid_section_record?(record)
+
+            raise Conflict, 'Invalid owned watcher section in receipt'
+          end
+        end
+
+        def valid_file_record?(record)
+          record.is_a?(Hash) && record['exists'] == true && record['mode'] == 0o755 &&
+            record['sha256'].is_a?(String) && record['sha256'].match?(/\A[0-9a-f]{64}\z/)
+        end
+
+        def valid_section_record?(record)
+          record.is_a?(Hash) && [true, false].include?(record['created_file']) &&
+            record['owned_text'].is_a?(String) && record['owned_text'].include?(Templates::START) &&
+            record['owned_text'].include?(Templates::FINISH)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    class Installation
+      # Replays only validated local transaction state; never discovers or boots Rails.
+      class Recovery
+        # @param root [String] selected canonical application directory
+        def initialize(root:)
+          @root = root
+        end
+
+        # @param pretend [Boolean] check journal and current snapshots without writes
+        # @return [String] recovery status
+        def call(pretend: false)
+          journal = read_journal
+          return 'nothing_to_recover' unless journal
+
+          layout = recovery_layout(journal)
+          applier = Woods::AgentConfiguration::Applier.new(layout: layout)
+          return applier.recover unless pretend
+
+          verify_preview(applier, layout, journal)
+          'recovery_preview_verified'
+        rescue KeyError, TypeError, ArgumentError => e
+          raise Conflict, "Invalid watcher recovery journal: #{e.message}"
+        end
+
+        private
+
+        def read_journal
+          layout = Layout.new(@root, 'Procfile.dev')
+          document = Woods::AgentConfiguration::Document.new("#{layout.receipt_path}.pending")
+          document.content && document.json
+        end
+
+        def recovery_layout(journal)
+          plan = journal.fetch('plan')
+          identity = plan.fetch('layout')
+          raise Conflict, 'Recovery journal belongs to another application' unless identity.fetch('root') == @root
+
+          layout = Layout.new(@root, identity.fetch('procfile'))
+          paths = plan.fetch('changes').map do |change|
+            path = change.fetch('path')
+            raise Conflict, 'Recovery target is outside the application' unless path.start_with?("#{@root}/")
+
+            path.delete_prefix("#{@root}/")
+          end
+          layout.include_previous(paths)
+          layout
+        end
+
+        def verify_preview(applier, layout, journal)
+          plan = Woods::AgentConfiguration::Plan.allocate
+          plan.instance_variable_set(:@data, journal.fetch('plan'))
+          plan.validate!(layout)
+          changes = plan.data.fetch('changes')
+          applier.send(:validate_originals!, journal.fetch('originals'), changes)
+          changes.each { |change| applier.send(:validate_recovery_snapshot!, change) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    class Installation
+      # Small generated fragments; runtime identities never enter committed files.
+      module Templates
+        START = '# woods:watch:managed:start'
+        FINISH = '# woods:watch:managed:end'
+
+        module_function
+
+        # @param child_command [Array<String>] explicit task argv
+        # @return [String] application-relative executable source
+        def wrapper(child_command)
+          <<~RUBY
+            #!/usr/bin/env ruby
+            # frozen_string_literal: true
+
+            # Generated by Woods; use woods:watch --operation update to change owned setup.
+            root = File.expand_path('..', __dir__)
+            ENV['BUNDLE_GEMFILE'] ||= File.join(root, 'Gemfile')
+            require 'bundler/setup'
+            Dir.chdir(root)
+            exec Gem.ruby, Gem.bin_path('woods', 'woods-watch'), '--root', root,
+                 *ARGV, '--', *#{child_command.inspect}
+          RUBY
+        end
+
+        # @param mode [String] procfile or puma
+        # @return [String] owned startup directive
+        def directive(mode)
+          return 'woods: bin/woods-watch' unless mode == 'puma'
+
+          'plugin :woods if Gem.loaded_specs["woods"]&.full_require_paths&.any? ' \
+            '{ |path| File.file?(File.join(path, "puma/plugin/woods.rb")) }'
+        end
+
+        # @param mode [String] selected startup mode
+        # @param text [String] surrounding file contents
+        # @param previous [String, nil] existing receipt-owned block
+        # @param update [Boolean] refresh an existing block in place
+        # @return [String] exact appended owned block including separator
+        def section(mode, text, previous: nil, update: false)
+          if previous
+            return previous unless update
+
+            return previous.partition(START).first + section(mode, previous)
+          end
+
+          newline = text.include?("\r\n") ? "\r\n" : "\n"
+          separator = text.empty? || text.end_with?(newline) ? '' : newline
+          separator + [START, directive(mode), FINISH, ''].join(newline)
+        end
+      end
+    end
+  end
+end

data/lib/woods/watch/installation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../agent_configuration/applier'
+require_relative '../agent_configuration/plan'
+require_relative 'installation/layout'
+require_relative 'installation/options'
+require_relative 'installation/planner'
+require_relative 'installation/probe'
+require_relative 'installation/recovery'
+
+module Woods
+  module Watch
+    # Plans and applies portable, explicitly owned watcher startup configuration.
+    class Installation
+      Conflict = Woods::AgentConfiguration::Conflict
+
+      # @param root [String] application directory
+      # @param options [Hash] mode, operation, child/manager argv and preflight options
+      def initialize(root:, **options)
+        @options = Options.new(root: root, **options)
+        @layout = Layout.new(@options.root, @options.procfile)
+      end
+
+      # Preview all edits without creating files or starting a watcher.
+      # @return [Woods::AgentConfiguration::Plan]
+      def plan
+        @options.validate!
+        Planner.new(layout: @layout, options: @options).call
+      end
+
+      # Apply a fresh or previously reviewed plan using conflict-checked writes.
+      # @param reviewed_plan [Woods::AgentConfiguration::Plan, nil] optional preview
+      # @return [String] applied or already_applied
+      def apply(reviewed_plan = nil)
+        selected = reviewed_plan || plan
+        return 'already_applied' if selected.data.fetch('changes').empty?
+
+        Woods::AgentConfiguration::Applier.new(layout: @layout).apply(selected)
+      end
+
+      # Explain which process must own this installation.
+      # @return [String]
+      def handoff
+        @options.handoff
+      end
+
+      # Recover an interrupted transaction without booting the application.
+      # @param pretend [Boolean] validate the journal without restoring files
+      # @return [String] recovery outcome
+      def recover(pretend: false)
+        Recovery.new(root: @options.root).call(pretend: pretend)
+      end
+    end
+  end
+end