rubik 0.1.0

data/lib/rubik/platform/path.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Platform
+    # Path resolution, normalization, URI conversion and path safety checks.
+    # Extracted from lib/rubik/platform.rb (Plan 86 D-4).
+    module Path
+      def self.included(base)
+        base.extend self
+      end
+
+      # Pure-Ruby cross-platform binary resolver
+      def which(cmd)
+        return nil if cmd.nil? || cmd.to_s.strip.empty?
+
+        cmd_str = cmd.to_s.strip.split.first
+        return nil if cmd_str.nil? || cmd_str.empty?
+
+        # Windows shell builtins (e.g. echo, dir, cls)
+        return cmd_str if windows? && Rubik::Platform::WINDOWS_SHELL_BUILTINS.include?(cmd_str.downcase)
+
+        # If full/relative path is provided
+        if cmd_str.include?("/") || (windows? && cmd_str.include?("\\"))
+          return File.expand_path(cmd_str).gsub("\\", "/") if File.file?(cmd_str) && executable_file?(cmd_str)
+
+          if windows?
+            pathext.each do |ext|
+              candidate = "#{cmd_str}#{ext}"
+              return File.expand_path(candidate).gsub("\\", "/") if File.file?(candidate) && executable_file?(candidate)
+            end
+          end
+          return nil
+        end
+
+        # Search in PATH
+        paths = (ENV["PATH"] || "").split(File::PATH_SEPARATOR)
+        exts = if windows?
+                 ext = File.extname(cmd_str)
+                 ext.empty? ? pathext : ([""] + pathext).uniq
+               else
+                 [""]
+               end
+
+        paths.each do |dir|
+          next if dir.empty? || !File.directory?(dir)
+
+          exts.each do |ext|
+            target = File.join(dir, "#{cmd_str}#{ext}")
+            return File.expand_path(target).gsub("\\", "/") if File.file?(target) && executable_file?(target)
+          end
+        end
+        nil
+      end
+
+      def pathext
+        (ENV["PATHEXT"] || ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC;.PS1").split(";").map(&:downcase)
+      end
+
+      def executable_file?(path)
+        return false unless File.file?(path)
+
+        windows? || File.executable?(path)
+      end
+
+      # RFC 8089 Compliant File URI (e.g. file:///C:/path/file vs file:///path/file)
+      def to_file_uri(path)
+        normalized = normalize_path_raw(path)
+        if windows? && normalized =~ %r{^([a-zA-Z]):/(.*)$}
+          "file:///#{::Regexp.last_match(1)}:/#{::Regexp.last_match(2)}"
+        else
+          normalized.start_with?("/") ? "file://#{normalized}" : "file:///#{normalized}"
+        end
+      end
+
+      def from_file_uri(uri)
+        str = uri.to_s.sub(%r{^file://}, "")
+        str = CGI.unescape(str)
+        if windows?
+          # Handles file:///C:/... and file://C:/...
+          if str =~ %r{^/?([a-zA-Z]:/.*)$}
+            ::Regexp.last_match(1)
+          else
+            str
+          end
+        else
+          str.start_with?("/") ? str : "/#{str}"
+        end
+      end
+
+      def normalize_path_raw(path)
+        expanded = File.expand_path(path.to_s)
+        expanded.gsub("\\", "/")
+      end
+
+      # Normalizes separators and casing for comparison
+      def normalize_path(path)
+        raw = normalize_path_raw(path)
+        windows? ? raw.downcase : raw
+      end
+
+      def path_equal?(lhs, rhs)
+        normalize_path(lhs) == normalize_path(rhs)
+      end
+
+      def path_under?(child, parent)
+        n_child = normalize_path(child)
+        n_parent = normalize_path(parent)
+        return true if n_child == n_parent
+
+        clean_parent = n_parent.chomp("/")
+        clean_child = n_child.chomp("/")
+        return true if clean_child == clean_parent
+
+        n_child.start_with?("#{clean_parent}/")
+      end
+
+      # Realpath for security-boundary containment decisions ONLY (stored
+      # buffer keys and every other comparison stay lexical). The deepest
+      # EXISTING ancestor is resolved and the not-yet-existing tail is
+      # re-attached lexically — a plain missing component cannot be a
+      # symlink, and File.expand_path has already collapsed ".." lexically.
+      # Symlink components (live or dangling) stop the walk: a dangling link
+      # must not be reattached as if it could never resolve.
+      # If strict: true (used in containment checks), IO resolution failure
+      # returns nil so resolved_path_under? fails closed (unprovable containment).
+      # If strict: false, falls back to lexical path for display/diagnostics.
+      def resolved_path(path, strict: false)
+        expanded = File.expand_path(path.to_s)
+        begin
+          File.realpath(expanded)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          begin
+            dir = expanded
+            tail = []
+            # File.symlink? in the walk condition: a DANGLING link reads as
+            # "missing" to File.exist?, but the OS write that follows DOES
+            # traverse it — stop there and let realpath's ENOENT fail closed
+            # (strict) instead of reattaching it lexically as if it could
+            # never be a link.
+            until dir == File.dirname(dir) || File.exist?(dir) || File.symlink?(dir)
+              tail.unshift(File.basename(dir))
+              dir = File.dirname(dir)
+            end
+            base = File.realpath(dir)
+            tail.empty? ? base : File.join(base, *tail)
+          rescue SystemCallError => e
+            debug_warn "resolved_path: ancestor walk failed for #{expanded}: #{e.message}"
+            return nil if strict
+
+            expanded
+          end
+        rescue SystemCallError => e
+          debug_warn "resolved_path: resolution failed for #{expanded}: #{e.message}"
+          return nil if strict
+
+          expanded
+        end
+      end
+
+      # Best-effort variant for read-only / display / diagnostics (never fails closed)
+      def resolved_path_best_effort(path)
+        resolved_path(path, strict: false)
+      end
+
+      # Drop-in twin of path_under? that resolves symlinks/junctions on BOTH
+      # sides before the prefix comparison. Security boundaries (Buffer
+      # containment, Sandbox chdir checks) must use this variant.
+      # Fail-closed invariant (W1): IO/permission failure returns false (containment unprovable).
+      def resolved_path_under?(child, parent)
+        r_child = resolved_path(child, strict: true)
+        return false if r_child.nil?
+
+        r_parent = resolved_path(parent, strict: true)
+        return false if r_parent.nil?
+
+        path_under?(r_child, r_parent)
+      end
+
+      def dangerous_system_roots
+        roots = ["/", "/root", "/home", "/etc", "/usr", "/var", "/bin", "/sbin", "/lib", "/lib64", "/opt", "/boot", "/dev", "/proc", "/sys"]
+        if windows?
+          # Add expanded Unix root equivalents on current drive (e.g. C:/etc, C:/usr)
+          roots += roots.map { |r| File.expand_path(r) }
+          roots += ["c:/", "c:/windows", "c:/windows/system32", "c:/program files", "c:/program files (x86)", "c:/users", "c:/programdata"]
+          roots << ENV["SystemRoot"] if ENV["SystemRoot"]
+          roots << ENV["ProgramFiles"] if ENV["ProgramFiles"]
+          roots << ENV["ProgramFiles(x86)"] if ENV["ProgramFiles(x86)"]
+          roots << ENV["CommonProgramFiles"] if ENV["CommonProgramFiles"]
+          roots << ENV["USERPROFILE"] if ENV["USERPROFILE"]
+          roots << "#{ENV['SystemDrive']}/" if ENV["SystemDrive"]
+          roots << ENV["SystemDrive"] if ENV["SystemDrive"]
+        end
+        roots << home_dir
+        roots.compact.map { |r| normalize_path(r) }.uniq
+      end
+
+      def drive_root?(path)
+        return false unless windows?
+
+        # Purely lexical: a bare drive-relative "D:" expands to the CURRENT
+        # directory on that drive, so expanding first would make "is this a
+        # drive root?" depend on the process cwd (which drive the workspace
+        # lives on). Security callers pass already-expanded absolute paths;
+        # compare the literal form here.
+        cleaned = path.to_s.tr("\\", "/").downcase.sub(%r{/+\z}, "")
+        cleaned =~ /^[a-z]:$/
+      end
+    end
+  end
+end

data/lib/rubik/platform/process.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Platform
+    # Process and environment management (e.g. kill_tree).
+    # Extracted from lib/rubik/platform.rb (Plan 86 D-4).
+    module Process
+      def self.included(base)
+        base.extend self
+      end
+
+      def kill_tree(pid)
+        return unless pid&.positive?
+
+        if windows?
+          begin
+            # Plan 55 D-1 ile tutarlı dizi-form çağrı: cmd.exe ara katmanı ve kabuk
+            # yönlendirmesi ("> NUL 2>&1") yerine out:/err: seçenekleri kullanılır.
+            system("taskkill", "/F", "/T", "/PID", pid.to_s, out: File::NULL, err: File::NULL)
+          rescue
+            nil
+          end
+        else
+          begin
+            ::Process.kill("TERM", pid)
+          rescue
+            nil
+          end
+          begin
+            ::Process.kill("KILL", pid)
+          rescue
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/platform/sanitize.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Platform
+    # Encoding and JSON hygiene (UTF-8 sanitation, safe JSON generation, XML escaping).
+    # This is the growth family that drove platform.rb over 300 lines.
+    # Extracted from lib/rubik/platform.rb (Plan 86 D-4).
+    module Sanitize
+      def self.included(base)
+        base.extend self
+      end
+
+      # Escapes a value for safe interpolation into XML text nodes and
+      # attribute values. Used by tool-result envelopes (<tool_result>) and
+      # the system-context XML so untrusted content (file contents, paths,
+      # user prompts) can neither break the envelope nor smuggle instructions.
+      def xml_escape(value)
+        CGI.escapeHTML(value.to_s)
+      rescue StandardError
+        ""
+      end
+
+      # Deeply sanitizes invalid or malformed UTF-8 byte sequences from a string
+      def clean_utf8(str)
+        return str unless str.is_a?(String)
+        return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
+
+        if str.valid_encoding?
+          begin
+            return str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "")
+          rescue StandardError => e
+            debug_warn("clean_utf8 encode fallback: #{e.class}: #{e.message}")
+            # fallback below
+          end
+        end
+
+        str.to_s.dup.force_encoding(Encoding::UTF_8).scrub("")
+      rescue StandardError => e
+        debug_warn("clean_utf8 scrub fallback: #{e.class}: #{e.message}")
+        begin
+          str.to_s.scrub("")
+        rescue
+          ""
+        end
+      end
+
+      # UTF-8 hygiene for strings whose encoding TAG is untrusted but whose
+      # bytes are expected to be UTF-8: HTTP bodies served without a charset
+      # arrive from Net::HTTP tagged ASCII-8BIT, and so does process/pipe
+      # output. Re-tags the string as UTF-8 and scrubs invalid sequences,
+      # PRESERVING valid multibyte content. clean_utf8 is the wrong tool for
+      # this: its encode step treats bytes >= 0x80 as undefined when
+      # converting FROM binary and silently strips them.
+      def safe_utf8(str)
+        return str unless str.is_a?(String)
+        return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
+
+        retagged = str.dup.force_encoding(Encoding::UTF_8)
+        retagged.valid_encoding? ? retagged : retagged.scrub("")
+      end
+
+      # Recursively sanitizes hashes, arrays, symbols, and strings for safe UTF-8 encoding
+      def clean_utf8_deep(obj, seen = nil)
+        case obj
+        when String
+          clean_utf8(obj)
+        when Hash
+          seen ||= Set.new
+          return "{...}" if seen.include?(obj.object_id)
+
+          seen.add(obj.object_id)
+
+          obj.each_with_object({}) do |(k, v), acc|
+            cleaned_k = if k.is_a?(String)
+                          clean_utf8(k)
+                        else
+                          (k.is_a?(Symbol) ? clean_utf8(k.to_s).to_sym : clean_utf8_deep(k, seen))
+                        end
+            acc[cleaned_k] = clean_utf8_deep(v, seen)
+          end
+        when Array
+          seen ||= Set.new
+          return "[...]" if seen.include?(obj.object_id)
+
+          seen.add(obj.object_id)
+
+          obj.map { |item| clean_utf8_deep(item, seen) }
+        when Set
+          seen ||= Set.new
+          return Set.new(["[...]"]) if seen.include?(obj.object_id)
+
+          seen.add(obj.object_id)
+
+          obj.to_set { |item| clean_utf8_deep(item, seen) }
+        when Symbol
+          clean_utf8(obj.to_s).to_sym
+        else
+          obj
+        end
+      end
+
+      # Generates JSON safely without raising JSON::GeneratorError on malformed UTF-8
+      def safe_json_generate(obj, *)
+        cleaned = clean_utf8_deep(obj)
+        JSON.generate(cleaned, *)
+      rescue StandardError => e
+        debug_warn("safe_json_generate fallback: #{e.class}: #{e.message}")
+        fallback = sanitize_for_json_fallback(obj)
+        begin
+          JSON.generate(fallback, *)
+        rescue
+          "{}"
+        end
+      end
+
+      # Dumps JSON safely without raising JSON::GeneratorError on malformed UTF-8
+      def safe_json_dump(obj, *)
+        cleaned = clean_utf8_deep(obj)
+        JSON.dump(cleaned, *)
+      rescue StandardError => e
+        debug_warn("safe_json_dump fallback: #{e.class}: #{e.message}")
+        fallback = sanitize_for_json_fallback(obj)
+        begin
+          JSON.dump(fallback, *)
+        rescue
+          "{}"
+        end
+      end
+
+      private
+
+      def sanitize_for_json_fallback(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), acc|
+            acc[clean_utf8(k.to_s)] = sanitize_for_json_fallback(v)
+          end
+        when Array, Set
+          obj.map { |item| sanitize_for_json_fallback(item) }
+        when String
+          clean_utf8(obj)
+        when Numeric, TrueClass, FalseClass, NilClass
+          obj
+        else
+          clean_utf8(obj.to_s)
+        end
+      rescue StandardError => e
+        debug_warn("sanitize_for_json_fallback rescue: #{e.class}: #{e.message}")
+        begin
+          obj.to_s.scrub("")
+        rescue
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/rubik/platform.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "tmpdir"
+require "fileutils"
+require "cgi"
+require "json"
+
+require_relative "platform/path"
+require_relative "platform/process"
+require_relative "platform/filesystem"
+require_relative "platform/sanitize"
+require_relative "platform/io_drain"
+
+module Rubik
+  module Platform
+    # Common constants shared across sub-modules
+    WINDOWS_SHELL_BUILTINS = [
+      "echo", "dir", "cd", "cls", "set", "type", "copy", "move", "del", "md", "rd", "exit", "rem", "ver", "vol"
+    ].freeze
+
+    class << self
+      # Audit 1: gated debug logging for the platform layer's many intentional
+      # rescue-and-fallback paths (UTF-8 sanitation, atomic writes). Follows
+      # the codebase's ENV["RUBIK_DEBUG"] convention (see config/store.rb) —
+      # silent in normal operation, diagnosable on demand, never raises.
+      #
+      # $stderr.puts, not Kernel#warn: warn is silenced when $VERBOSE is nil
+      # (bundler/rake -W0) — the exact context these diagnostics must survive.
+      # Same ruling as Log.emit.
+      def debug_warn(msg)
+        $stderr.puts "[WARN] #{msg}" if ENV["RUBIK_DEBUG"] # rubocop:disable Style/StderrPuts
+      rescue StandardError
+        nil
+      end
+
+      # Boot/warm async-knob resolution with test-armor defaulting (arch
+      # 2026-10-08 #12): an explicit true/false config value always wins;
+      # nil (unset) falls back to the RUBIK_TEST env default — RUBIK_TEST=1
+      # resolves false so tests warm/boot synchronously. Consumers:
+      # repl/lifecycle.rb#warm_up! (ast.async_warm, mcp.async_load).
+      def async_knob(config, key)
+        value = config.fetch(key, nil)
+        value = ENV["RUBIK_TEST"] != "1" if value.nil?
+        value
+      end
+
+      def host_os
+        RbConfig::CONFIG["host_os"] || ""
+      end
+
+      def ruby_platform
+        RUBY_PLATFORM
+      end
+
+      def os_family
+        if windows?
+          :windows
+        elsif macos?
+          :macos
+        elsif linux?
+          :linux
+        else
+          :unknown
+        end
+      end
+
+      def windows?
+        Gem.win_platform? || !(host_os =~ /mswin|mingw|cygwin|bccwin|wince/i).nil?
+      end
+
+      def macos?
+        (host_os =~ /darwin/i) != nil
+      end
+
+      def linux?
+        !windows? && !macos?
+      end
+
+      def unix?
+        !windows?
+      end
+
+      def dev_null
+        File::NULL
+      end
+
+      def home_dir
+        Dir.home
+      rescue
+        (ENV["USERPROFILE"] || (ENV.fetch("HOMEDRIVE",
+                                          nil) && ENV.fetch("HOMEPATH",
+                                                            nil) && "#{ENV.fetch('HOMEDRIVE',
+                                                                                 nil)}#{ENV.fetch('HOMEPATH', nil)}") || ENV["HOME"] || ".")
+      end
+
+      def tmp_dir
+        Dir.tmpdir
+      rescue
+        (ENV["TEMP"] || ENV["TMP"] || "/tmp")
+      end
+    end
+
+    # Include all sub-modules so the singleton class (class << self) gains
+    # their methods via extend in the included hook. Each sub-module
+    # `extend`s itself when included, making its methods available as
+    # `Rubik::Platform.<method>` for backward compatibility.
+    include Platform::Path
+    include Platform::Process
+    include Platform::FileSystem
+    include Platform::Sanitize
+  end
+end

data/lib/rubik/plugin/dsl.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Plugin
+    class Definition
+      attr_reader :name, :version, :description, :inject, :requires, :factory_block
+
+      def initialize(name, version: "1.0.0", description: "", inject: [], requires: [], &block)
+        @name = name
+        @version = version
+        @description = description
+        @inject = Array(inject)
+        @requires = Array(requires)
+        @factory_block = block
+      end
+    end
+
+    class Registry
+      @definitions = {}
+
+      class << self
+        attr_reader :definitions
+
+        def register(definition)
+          @definitions[definition.name.to_s] = definition
+        end
+
+        def get(name)
+          @definitions[name.to_s]
+        end
+
+        def clear!
+          @definitions.clear
+        end
+      end
+    end
+  end
+
+  # Top level DSL
+  def self.plugin(name, version: "1.0.0", description: "", inject: [], requires: [], &)
+    definition = Plugin::Definition.new(
+      name,
+      version: version,
+      description: description,
+      inject: inject,
+      requires: requires,
+      &
+    )
+    Plugin::Registry.register(definition)
+  end
+end