woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/agent_configuration/applier.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'fileutils'
+require_relative '../atomic_file'
+require_relative 'plan'
+require_relative 'recovery'
+
+module Woods
+  module AgentConfiguration
+    # Atomic per-file replacement with a private recovery journal. Multiple
+    # configuration files cannot be one filesystem transaction; interrupted
+    # writes retain enough original bytes to explicitly recover without
+    # overwriting concurrent edits.
+    class Applier
+      include Recovery
+
+      def initialize(layout:, writer: Woods::AtomicFile.method(:write))
+        @layout = layout
+        @writer = writer
+      end
+
+      def apply(plan)
+        plan.validate!(@layout)
+        with_lock do
+          refuse_pending!
+          changes = plan.data.fetch('changes')
+          return 'already_applied' if changes.all? { |change| current(change) == Plan.after_fingerprint(change) }
+
+          journal = { 'schema_version' => 1, 'plan' => plan.data, 'originals' => originals(changes) }
+          write_journal(journal)
+          apply_changes(changes, journal)
+          'applied'
+        end
+      end
+
+      def recover
+        with_lock do
+          document = Document.new(journal_path)
+          return 'nothing_to_recover' if document.content.nil?
+
+          recover_journal(document.json)
+          'recovered'
+        end
+      end
+
+      private
+
+      def journal_path
+        "#{@layout.receipt_path}.pending"
+      end
+
+      def with_lock
+        path = "#{@layout.receipt_path}.lock"
+        Document.validate_path!(path)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600) do |lock|
+          raise Conflict, "Not a regular lock file: #{path}" unless lock.stat.file?
+          unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise Conflict,
+                  'Another Woods configuration operation is active; retry after it finishes'
+          end
+
+          yield
+        ensure
+          lock&.flock(File::LOCK_UN)
+        end
+      rescue SystemCallError => e
+        raise Conflict, "Configuration write failed: #{e.message}"
+      end
+
+      def write_journal(journal)
+        encoded = JSON.generate(journal)
+        if encoded.bytesize > Document::MAX_BYTES
+          raise Conflict, 'Recovery journal would exceed 8 MiB; reduce the selected configuration before applying'
+        end
+
+        @writer.call(journal_path, encoded, mode: 0o600)
+      end
+
+      def refuse_pending!
+        return if Document.new(journal_path).content.nil?
+
+        raise Conflict, "An interrupted operation needs explicit recovery first: #{journal_path}"
+      end
+
+      def current(change)
+        Document.new(change.fetch('path')).fingerprint
+      end
+
+      def assert_snapshot!(actual, expected, path)
+        return if actual == expected
+
+        raise Conflict, "Changed since preview: #{path}; create a new plan without discarding the user's edits"
+      end
+
+      def replace(path, content, mode)
+        Document.validate_path!(path)
+        if content.nil?
+          remove_file(path)
+        else
+          @writer.call(path, content, mode: mode)
+        end
+      end
+
+      def remove_file(path)
+        File.unlink(path)
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def originals(changes)
+        changes.map do |change|
+          document = Document.new(change.fetch('path'))
+          assert_snapshot!(document.fingerprint, change.fetch('before'), document.path)
+          { 'path' => document.path, 'content' => document.content && Base64.strict_encode64(document.content),
+            'mode' => document.mode }
+        end
+      end
+
+      def apply_changes(changes, journal)
+        changes.each do |change|
+          assert_snapshot!(current(change), change.fetch('before'), change.fetch('path'))
+          replace(change.fetch('path'), Plan.after_content(change), change.fetch('mode'))
+        end
+        File.unlink(journal_path)
+      rescue StandardError => e
+        recover_journal(journal)
+        raise Conflict, "Apply failed and original files were restored: #{e.message}"
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/cli.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'cli_options'
+require_relative 'plan_diff'
+require_relative 'layout'
+require_relative 'launcher'
+require_relative 'preflight'
+require_relative 'planner'
+require_relative 'applier'
+
+module Woods
+  module AgentConfiguration
+    class CLI
+      def initialize(stdout: $stdout, stderr: $stderr, preflight: Preflight.new)
+        @stdout = stdout
+        @stderr = stderr
+        @preflight = preflight
+      end
+
+      def run(argv)
+        options = { root: Dir.pwd, index: 'tmp/woods', mode: 'host', name: 'woods' }
+        command = argv.shift
+        parser = CLIOptions.build(options)
+        parser.parse!(argv)
+        if options[:help] || command.nil? || %w[-h --help].include?(command)
+          @stdout.puts(parser)
+          return 0
+        end
+        layout = Layout.new(root: options.fetch(:root), scope: options[:scope], client: options[:client])
+        result = dispatch(command, argv, options, layout)
+        @stdout.puts(JSON.pretty_generate(result))
+        0
+      rescue Conflict, OptionParser::ParseError, SystemCallError => e
+        @stderr.puts("woods-agent-config: #{e.message}")
+        1
+      end
+
+      private
+
+      def dispatch(command, argv, options, layout)
+        case command
+        when 'setup', 'update', 'remove'
+          raise Conflict, "Unexpected arguments: #{argv.join(' ')}" unless argv.empty?
+
+          create_plan(command, options, layout)
+        when 'show', 'apply'
+          consume_plan(command, argv, options, layout)
+        when 'recover'
+          raise Conflict, 'Recover does not accept positional arguments' unless argv.empty?
+
+          { 'result' => Applier.new(layout: layout).recover }
+        else
+          raise Conflict, 'Select setup, update, remove, show, apply, or recover'
+        end
+      end
+
+      def consume_plan(command, argv, options, layout)
+        raise Conflict, 'Select exactly one saved plan file' unless argv.size == 1
+
+        plan = Plan.load(argv.first).validate!(layout)
+        return { 'result' => Applier.new(layout: layout).apply(plan) } if command == 'apply'
+
+        PlanDiff.show(plan, @stderr) if options[:diff]
+        plan.summary
+      end
+
+      def create_plan(operation, options, layout)
+        path = options[:plan]
+        raise Conflict, 'Choose --plan FILE for the private, reviewable write plan' unless path
+
+        launcher = if operation != 'remove'
+                     Launcher.new(root: layout.root, **options.slice(:index, :mode, :service, :container_root))
+                   end
+        evidence = launcher ? @preflight.call(launcher) : {}
+        plan = Planner.new(layout: layout, operation: operation, entry: launcher&.entry,
+                           name: options.fetch(:name), instructions: options[:instructions],
+                           evidence: evidence, intent: launcher ? launcher.intent : {}).call
+        write_plan(path, plan, layout)
+        PlanDiff.show(plan, @stderr) if options[:diff]
+        plan.summary.merge('plan_file' => File.expand_path(path),
+                           'runtime_files' => ["#{layout.receipt_path}.lock", "#{layout.receipt_path}.pending"])
+      end
+
+      def write_plan(path, plan, layout)
+        target = File.expand_path(path)
+        protected_paths = layout.allowed_paths + ["#{layout.receipt_path}.lock", "#{layout.receipt_path}.pending"]
+        raise Conflict, 'Plan output must differ from every managed/runtime target' if protected_paths.include?(target)
+
+        Document.validate_path!(target)
+        content = "#{JSON.pretty_generate(plan.data)}\n"
+        raise Conflict, 'Plan exceeds the supported size' if content.bytesize > Document::MAX_BYTES
+
+        File.open(target, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+          file.write(content)
+          file.flush
+          file.fsync
+        end
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/cli_options.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Woods
+  module AgentConfiguration
+    module CLIOptions
+      def self.build(options)
+        OptionParser.new do |parser|
+          parser.banner = <<~USAGE
+            Usage: woods-agent-config setup|update|remove --client claude --scope project|user --plan FILE [options]
+                   woods-agent-config apply|show FILE --client claude --scope project|user [--root ROOT]
+                   woods-agent-config recover --client claude --scope project|user [--root ROOT]
+            Setup/update/remove create a private plan without changing managed configuration.
+            Apply consumes that exact plan. Only Index MCP is configured; client trust remains separate.
+          USAGE
+          { client: '--client NAME', scope: '--scope SCOPE', root: '--root DIRECTORY',
+            plan: '--plan FILE', name: '--name NAME', index: '--index PATH', mode: '--mode MODE',
+            service: '--service NAME', container_root: '--container-root PATH' }.each do |key, option|
+            parser.on(option) { |value| options[key] = value }
+          end
+          parser.on('--instructions LIST', Array) { |value| options[:instructions] = value }
+          parser.on('--diff') { options[:diff] = true }
+          parser.on('-h', '--help') { options[:help] = true }
+        end
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/document.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require_relative 'error'
+
+module Woods
+  module AgentConfiguration
+    # Reads bounded regular files and rejects symlink components before writes.
+    # Preview/apply snapshots include exact bytes and permissions, so edits made
+    # after preview cannot be overwritten by a stale plan.
+    class Document
+      MAX_BYTES = 8 * 1024 * 1024
+
+      class UniqueObject < Hash
+        def []=(key, value)
+          raise Conflict, "Duplicate JSON key #{key.inspect}; resolve the ambiguous configuration" if key?(key)
+
+          super
+        end
+      end
+
+      attr_reader :path, :content, :mode
+
+      def initialize(path)
+        @path = File.expand_path(path)
+        self.class.validate_path!(@path)
+        @content = nil
+        @mode = 0o600
+        return unless File.exist?(@path)
+
+        File.open(@path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+          stat = file.stat
+          raise Conflict, "Expected a regular file: #{@path}" unless stat.file?
+          raise Conflict, "Configuration file exceeds #{MAX_BYTES} bytes: #{@path}" if stat.size > MAX_BYTES
+
+          read_content(file)
+          @mode = stat.mode & 0o777
+        end
+      rescue SystemCallError => e
+        raise Conflict, "Cannot read configuration #{@path}: #{e.message}"
+      end
+
+      def self.validate_path!(path)
+        current = File.expand_path(path)
+        loop do
+          raise Conflict, "Symlink target or parent is unsupported: #{current}" if File.symlink?(current)
+
+          parent = File.dirname(current)
+          break if parent == current
+
+          current = parent
+        end
+      end
+
+      def fingerprint
+        { 'sha256' => content && Digest::SHA256.hexdigest(content), 'mode' => mode, 'exists' => !content.nil? }
+      end
+
+      def json
+        return {} if content.nil?
+
+        value = JSON.parse(content, object_class: UniqueObject)
+        raise Conflict, "Expected a JSON object: #{path}" unless value.is_a?(Hash)
+
+        plain_value(value)
+      rescue JSON::ParserError => e
+        raise Conflict, "Malformed JSON in #{path}: #{e.message}"
+      end
+
+      def encode_json(value)
+        return content if !content.nil? && json == value
+
+        return JSON.generate(value) if content && !content.include?("\n")
+
+        JSON.pretty_generate(value, indent: json_indent).gsub("\n", newline) + newline
+      end
+
+      private
+
+      def read_content(file)
+        @content = (file.read(MAX_BYTES + 1) || String.new).force_encoding(Encoding::UTF_8)
+        raise Conflict, "Invalid UTF-8 configuration: #{@path}" unless @content.valid_encoding?
+        raise Conflict, "Configuration file too large: #{@path}" if @content.bytesize > MAX_BYTES
+      end
+
+      def newline
+        content&.include?("\r\n") ? "\r\n" : "\n"
+      end
+
+      def json_indent
+        match = content&.match(/\n([ \t]+)"/)
+        match ? match[1] : '  '
+      end
+
+      def plain_value(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, item), hash| hash[key] = plain_value(item) }
+        when Array then value.map { |item| plain_value(item) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    class Conflict < StandardError; end
+  end
+end

data/lib/woods/agent_configuration/launcher.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'error'
+
+module Woods
+  module AgentConfiguration
+    # Supported command shapes are built as argv, never as shell snippets.
+    class Launcher
+      attr_reader :root, :index, :mode, :service, :container_root
+
+      def initialize(root:, index: 'tmp/woods', mode: 'host', service: nil, container_root: nil)
+        @root = File.realpath(root)
+        @index = Pathname.new(index).cleanpath.to_s
+        @mode = mode
+        @service = service
+        @container_root = container_root
+        unless !Pathname.new(@index).absolute? && @index != '..' && !@index.start_with?('../')
+          raise Conflict, 'Index must be an explicit path inside the selected application root'
+        end
+        raise Conflict, 'Application Gemfile is missing' unless File.file?(File.join(@root, 'Gemfile'))
+        raise Conflict, 'Supported launch modes: host, compose' unless %w[host compose].include?(mode)
+
+        validate_compose! if mode == 'compose'
+      end
+
+      def entry
+        argv = prefix + ['bundle', 'exec', 'woods-mcp-start', index_path]
+        { 'type' => 'stdio', 'command' => argv.first, 'args' => argv.drop(1), 'env' => environment }
+      end
+
+      def probe_command(script)
+        prefix(frozen: true) + ['bundle', 'exec', 'ruby', '-e', script, index_path, process_root]
+      end
+
+      def environment
+        mode == 'host' ? { 'BUNDLE_GEMFILE' => File.join(root, 'Gemfile') } : {}
+      end
+
+      def probe_environment
+        environment.merge('BUNDLE_FROZEN' => 'true')
+      end
+
+      def intent
+        { 'mode' => mode, 'index' => index, 'service' => service, 'container_root' => container_root }.compact
+      end
+
+      private
+
+      def process_root
+        mode == 'host' ? root : container_root
+      end
+
+      def index_path
+        File.join(process_root, index)
+      end
+
+      def prefix(frozen: false)
+        return [] if mode == 'host'
+
+        ['docker', 'compose', '--project-directory', root, 'exec', '-T', '-w', container_root] +
+          (frozen ? ['-e', 'BUNDLE_FROZEN=true'] : []) + [service]
+      end
+
+      def validate_compose!
+        unless service.is_a?(String) && service.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/)
+          raise Conflict, 'Compose mode requires an explicit service name'
+        end
+        return if container_root.is_a?(String) && Pathname.new(container_root).absolute?
+
+        raise Conflict, 'Compose mode requires the absolute application path visible inside the container'
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/layout.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'pathname'
+require_relative 'error'
+
+module Woods
+  module AgentConfiguration
+    # Explicit client/scope selection; no discovery or fallback into a user home.
+    class Layout
+      attr_reader :root, :scope, :config_dir
+
+      def initialize(root:, scope:, client: 'claude', home: Dir.home, config_dir: ENV.fetch('CLAUDE_CONFIG_DIR', nil))
+        raise Conflict, 'Supported client: claude' unless client == 'claude'
+        raise Conflict, 'Select scope project or user explicitly' unless %w[project user].include?(scope)
+
+        @root = File.realpath(root)
+        raise Conflict, 'Application root must be a directory' unless File.directory?(@root)
+
+        @scope = scope
+        @home = File.expand_path(home)
+        @custom_config = config_dir && !config_dir.empty?
+        @config_dir = File.expand_path(@custom_config ? config_dir : File.join(@home, '.claude'))
+      rescue Errno::ENOENT => e
+        raise Conflict, "Application root unavailable: #{e.message}"
+      end
+
+      def config_path
+        return File.join(root, '.mcp.json') if scope == 'project'
+
+        File.join(@custom_config ? config_dir : @home, '.claude.json')
+      end
+
+      def receipt_path
+        return File.join(root, '.woods-agent-config.json') if scope == 'project'
+
+        File.join(config_dir, "woods-agent-#{Digest::SHA256.hexdigest(root)[0, 16]}.json")
+      end
+
+      def instruction_path(name)
+        names = scope == 'project' ? %w[CLAUDE.md AGENTS.md] : ['CLAUDE.md']
+        raise Conflict, "Supported #{scope} instruction files: #{names.join(', ')}" unless names.include?(name)
+
+        File.join(scope == 'project' ? root : config_dir, name)
+      end
+
+      def allowed_paths
+        [config_path, receipt_path, instruction_path('CLAUDE.md')].tap do |paths|
+          paths << instruction_path('AGENTS.md') if scope == 'project'
+        end
+      end
+
+      def identity
+        { 'client' => 'claude', 'scope' => scope, 'root' => root, 'config_dir' => config_dir,
+          'config_path' => config_path, 'receipt_path' => receipt_path }
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/managed_section.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Woods
+  module AgentConfiguration
+    # Only a receipt-owned, byte-identical section may be replaced or removed.
+    class ManagedSection
+      START = '<!-- woods:managed:start -->'
+      FINISH = '<!-- woods:managed:end -->'
+      BODY = <<~MARKDOWN
+        ## Codebase index (Woods)
+
+        Call `woods_status` before relying on the published index. For structural
+        questions use `search`, `lookup`, and `dependencies`/`dependents` as needed.
+        Check freshness and search completeness before treating missing evidence
+        as absent code. Read source and run relevant tests to verify changes.
+        The server's tool descriptions define its available capabilities.
+      MARKDOWN
+
+      def self.render(content)
+        newline = content&.include?("\r\n") ? "\r\n" : "\n"
+        "#{START}\n#{BODY}#{FINISH}\n".gsub("\n", newline)
+      end
+
+      def self.change(content, previous:, remove: false)
+        text = content || ''
+        starts = text.scan(START).size
+        finishes = text.scan(FINISH).size
+        return replace_owned(text, previous, starts, finishes, remove) if previous
+
+        unless starts.zero? && finishes.zero?
+          raise Conflict, 'Unowned or ambiguous Woods markers; resolve them before setup'
+        end
+        return [content, nil] if remove
+
+        prefix = separator(text)
+        block = prefix + render(text)
+        [text + block, { 'owned_text' => block, 'prefix' => prefix }]
+      end
+
+      def self.replace_owned(text, previous, starts, finishes, remove)
+        unless starts == 1 && finishes == 1 && text.include?(previous.fetch('owned_text'))
+          raise Conflict, 'Managed instruction section was edited or removed; restore it or resolve ownership manually'
+        end
+        return [text.sub(previous.fetch('owned_text'), ''), nil] if remove
+
+        block = previous.fetch('prefix') + render(text)
+        [text.sub(previous.fetch('owned_text'), block), { 'owned_text' => block, 'prefix' => previous.fetch('prefix') }]
+      end
+      private_class_method :replace_owned
+
+      def self.separator(text)
+        return '' if text.empty?
+
+        newline = text.include?("\r\n") ? "\r\n" : "\n"
+        text.end_with?(newline) ? newline : newline * 2
+      end
+      private_class_method :separator
+    end
+  end
+end

data/lib/woods/agent_configuration/plan.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require_relative 'document'
+
+module Woods
+  module AgentConfiguration
+    # The serialized plan is the write set. Apply checks its original snapshots
+    # and never independently recomputes a newer set of intended edits.
+    class Plan
+      SCHEMA_VERSION = 1
+
+      attr_reader :data
+
+      def initialize(layout:, operation:, evidence: {})
+        @data = { 'schema_version' => SCHEMA_VERSION, 'layout' => layout.identity,
+                  'operation' => operation, 'evidence' => evidence, 'changes' => [] }
+      end
+
+      def self.load(path)
+        object = allocate
+        object.instance_variable_set(:@data, Document.new(path).json)
+        object
+      end
+
+      def add(document, content, description:)
+        return if content == document.content
+
+        data.fetch('changes') << { 'path' => document.path, 'before' => document.fingerprint,
+                                   'after' => content && Base64.strict_encode64(content),
+                                   'mode' => document.mode, 'description' => description }
+      end
+
+      def validate!(layout)
+        validate_format!(layout)
+        validate_paths!(layout)
+        data.fetch('changes').each { |change| validate_change!(change) }
+        self
+      rescue KeyError, TypeError, ArgumentError => e
+        raise Conflict, "Invalid plan: #{e.message}"
+      end
+
+      def self.after_content(change)
+        encoded = change.fetch('after')
+        encoded && Base64.strict_decode64(encoded).force_encoding(Encoding::UTF_8)
+      end
+
+      def self.after_fingerprint(change)
+        content = after_content(change)
+        { 'sha256' => content && Digest::SHA256.hexdigest(content), 'mode' => content ? change.fetch('mode') : 0o600,
+          'exists' => !content.nil? }
+      end
+
+      def summary
+        data.slice('operation', 'layout', 'evidence').merge(
+          'changes' => data.fetch('changes').map do |change|
+            change.slice('path', 'description').merge('action' => change['after'] ? 'write' : 'remove')
+          end
+        )
+      end
+
+      def to_json(*arguments)
+        data.to_json(*arguments)
+      end
+
+      private
+
+      def validate_format!(layout)
+        valid = data.is_a?(Hash) && data['schema_version'] == SCHEMA_VERSION && data['layout'] == layout.identity &&
+                %w[setup update remove].include?(data['operation']) && data['changes'].is_a?(Array) &&
+                data['changes'].all?(Hash)
+        return if valid
+
+        raise Conflict, 'Plan format or selected application/client/scope differs; create a fresh preview'
+      end
+
+      def validate_paths!(layout)
+        paths = data.fetch('changes').map { |change| change.fetch('path') }
+        return if paths.uniq == paths && (paths - layout.allowed_paths).empty?
+
+        raise Conflict, 'Plan contains duplicate or out-of-scope targets'
+      end
+
+      def validate_change!(change)
+        unless change['before'].is_a?(Hash) && change['mode'].is_a?(Integer) && change['mode'].between?(0, 0o777)
+          raise Conflict, 'Invalid file snapshot in plan'
+        end
+
+        content = self.class.after_content(change)
+        return if content.nil?
+
+        raise Conflict, 'Planned file exceeds the supported size' if content.bytesize > Document::MAX_BYTES
+        raise Conflict, 'Planned file must contain valid UTF-8' unless content.valid_encoding?
+      end
+    end
+  end
+end