mbeditor 0.8.1 → 0.10.0

data/app/assets/stylesheets/mbeditor/themes.css

@@ -355,6 +355,41 @@
  * or exceed that specificity to win the cascade. :root[data-theme] equals
  * (0,2,0) and loads AFTER pico.classless.css, so it wins on cascade order.
  * ─────────────────────────────────────────────────────────────────────────── */
+/* Rails log drawer palette.
+ *
+ * Deliberately its own set rather than the --ide-* semantic vars: those only
+ * carry four hues, and several themes alias them (Dracula's --ide-accent-fg
+ * and --ide-success are the same green), which would render "Started GET" and
+ * "Completed 200" identically. A log needs its categories to separate from
+ * each other more than it needs to match the editor chrome — the same reason
+ * terminals keep a fixed palette. Light themes get darkened variants so the
+ * text stays legible on white. */
+:root[data-theme],
+:root,
+[data-theme] {
+  --ide-log-request:    #d7dae0;
+  --ide-log-controller: #c792ea;
+  --ide-log-sql:        #56b6c2;
+  --ide-log-render:     #82aaff;
+  --ide-log-success:    #7ec699;
+  --ide-log-warn:       #e5c07b;
+  --ide-log-error:      #ef6b73;
+  --ide-log-muted:      #7f8596;
+}
+
+:root[data-theme="vs"],
+:root[data-theme="hc-light"],
+:root[data-theme="github-light"] {
+  --ide-log-request:    #1f2328;
+  --ide-log-controller: #6f42c1;
+  --ide-log-sql:        #0b7285;
+  --ide-log-render:     #0550ae;
+  --ide-log-success:    #116329;
+  --ide-log-warn:       #8a6100;
+  --ide-log-error:      #b42318;
+  --ide-log-muted:      #656d76;
+}
+
 :root[data-theme],
 :root,
 [data-theme] {

data/app/controllers/mbeditor/application_controller.rb

@@ -32,23 +32,17 @@ module Mbeditor
     end
 
     # Expand path and confirm it's inside workspace_root.
-    # Resolves symlinks on the nearest existing ancestor of the target so that
-    # a symlink inside the workspace cannot escape the sandbox regardless of
-    # whether the target itself exists yet (create / rename paths).
+    # SafePath follows every symlink on the way — including dangling ones, which
+    # an existence walk would skip past — so a symlink inside the workspace
+    # cannot escape the sandbox regardless of whether the target exists yet
+    # (create / rename paths).
     def resolve_path(raw)
       return nil if raw.blank?
 
       root = workspace_root.to_s
       full = File.expand_path(raw.to_s, root)
       return nil unless full.start_with?("#{root}/") || full == root
-
-      # Walk up to the nearest existing ancestor (could be the path itself,
-      # its parent directory, or ultimately the workspace root).
-      check = full
-      check = File.dirname(check) until File.exist?(check)
-      real_root = File.realpath(root)
-      real = File.realpath(check)
-      return nil unless real.start_with?("#{real_root}/") || real == real_root
+      return nil unless SafePath.within?(root, full)
 
       full
     rescue Errno::EACCES

data/app/controllers/mbeditor/editors_controller.rb

@@ -1098,7 +1098,7 @@ module Mbeditor
       rel = relative_path(full_path)
       return true if rel.blank?
 
-      ExclusionMatcher.new(Mbeditor.configuration.excluded_paths).excluded?(rel)
+      ExclusionMatcher.new(Mbeditor.configuration.excluded_paths, root: workspace_root).excluded?(rel)
     end
 
     def ruby_def_include_dirs
@@ -1144,10 +1144,39 @@ module Mbeditor
       contents = result.is_a?(Hash) ? result["contents"] : nil
       return nil if contents.nil?
 
-      case contents
-      when Hash  then contents["value"].to_s
-      when Array then contents.map { |c| c.is_a?(Hash) ? c["value"].to_s : c.to_s }.join("\n\n")
-      else contents.to_s
+      markdown =
+        case contents
+        when Hash  then contents["value"].to_s
+        when Array then contents.map { |c| c.is_a?(Hash) ? c["value"].to_s : c.to_s }.join("\n\n")
+        else contents.to_s
+        end
+
+      rewrite_lsp_hover_links(markdown)
+    end
+
+    # ruby-lsp renders its "Definitions" line as VS Code file links, e.g.
+    # `[user.rb](file:///abs/path/user.rb#L3,1-9,4)`. Monaco renders those as
+    # links but clicking one does nothing, since nothing can open a file:// URI
+    # here. Point in-workspace links at the `mbeditor.openDefinition` Monaco
+    # command (registered in editor_plugins.js) and demote gem/stdlib links —
+    # which the editor cannot open at all — to plain code spans.
+    LSP_HOVER_FILE_LINK = %r{\[([^\]\n]+)\]\(file://([^)\s#]+)(?:\#L(\d+),\d+(?:-\d+,\d+)?)?\)}
+
+    def rewrite_lsp_hover_links(markdown)
+      prefix = "#{workspace_root}/"
+      markdown.gsub(LSP_HOVER_FILE_LINK) do
+        label, raw_path, line = Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3).to_i
+        # Percent-decode by hand: URI's unescape helpers are deprecated on new
+        # Rubies and their replacements are missing on the old ones we support.
+        # (Must come after reading the other captures — gsub resets last_match.)
+        path = raw_path.gsub(/%\h\h/) { |esc| esc[1..].hex.chr }.force_encoding(Encoding::UTF_8)
+
+        if path.start_with?(prefix)
+          args = [path.delete_prefix(prefix), line.positive? ? line : 1]
+          "[#{label}](command:mbeditor.openDefinition?#{ERB::Util.url_encode(args.to_json)})"
+        else
+          "`#{label}`"
+        end
       end
     end
 

data/app/controllers/mbeditor/git_controller.rb

@@ -8,6 +8,7 @@ module Mbeditor
   # ---------
   # GET  /mbeditor/git/diff          ?file=<path>[&base=<sha>&head=<sha>]
   # GET  /mbeditor/git/blame         ?file=<path>
+  # GET  /mbeditor/git/line_diff     ?file=<path>
   # GET  /mbeditor/git/file_history  ?file=<path>
   # GET  /mbeditor/git/commit_graph
   # GET  /mbeditor/redmine/issue/:id
@@ -55,6 +56,16 @@ module Mbeditor
       render json: { error: e.message }, status: :unprocessable_content
     end
 
+    # GET /mbeditor/git/line_diff?file=<path>
+    def line_diff
+      file = require_file_param
+      return unless file
+
+      render json: GitLineDiffService.new(repo_path: workspace_root, file_path: file).call
+    rescue StandardError => e
+      render json: { error: e.message }, status: :unprocessable_content
+    end
+
     # GET /mbeditor/git/file_history?file=<path>
     def file_history
       file = require_file_param

data/app/services/mbeditor/exclusion_matcher.rb

@@ -1,13 +1,98 @@
 # frozen_string_literal: true
 
 module Mbeditor
+  # Decides whether a workspace-relative path falls under a configured
+  # exclusion (`Mbeditor.configuration.excluded_paths`).
+  #
+  # Comparison is normalized rather than byte-for-byte, because the filesystem
+  # the workspace lives on may resolve two different spellings of a name to the
+  # same file:
+  #
+  #   * Case. APFS/HFS+ (and NTFS) resolve "TMP/cache.txt" to the excluded
+  #     "tmp/", and ".GIT/hooks/post-checkout" to the real ".git/hooks/" — the
+  #     latter is arbitrary code execution on the next git operation. Folding is
+  #     applied only when the filesystem backing the workspace really is
+  #     case-insensitive, probed at runtime: a case-sensitive volume can be
+  #     mounted on macOS, and folding there would hide legitimately distinct
+  #     paths.
+  #
+  #   * Unicode normalization. APFS stores one file for the NFC and NFD
+  #     spellings of a name, so an NFD request path slips past an NFC pattern.
+  #     NFC folding is applied unconditionally: filesystems that do keep the two
+  #     spellings apart are rare enough, and the cost there is over-exclusion
+  #     (hiding a path) rather than the write-through this class exists to
+  #     prevent.
   class ExclusionMatcher
-    def initialize(patterns)
-      @patterns = patterns.map(&:to_s).reject(&:empty?)
+    MUTEX = Mutex.new
+    private_constant :MUTEX
+
+    # Roots are stable for the life of a process; the bound only keeps the test
+    # suite (a fresh tmpdir workspace per test) from growing the memo forever.
+    MAX_PROBE_CACHE = 256
+    private_constant :MAX_PROBE_CACHE
+
+    class << self
+      # Whether the filesystem backing +root+ resolves paths case-insensitively.
+      # Probed once per root, then memoized for the life of the process.
+      def case_insensitive_filesystem?(root)
+        key = File.expand_path(root.to_s)
+
+        MUTEX.synchronize do
+          @probe_cache ||= {}
+          return @probe_cache[key] if @probe_cache.key?(key)
+
+          @probe_cache = {} if @probe_cache.size >= MAX_PROBE_CACHE
+          @probe_cache[key] = probe_case_insensitive(key)
+        end
+      end
+
+      def reset_filesystem_probe!
+        MUTEX.synchronize { @probe_cache = {} }
+      end
+
+      private
+
+      # Asks the filesystem directly: look up a real directory under its own
+      # name and under that name with the case flipped, and compare device +
+      # inode (that is what File.identical? does). They only agree when the
+      # filesystem folded the two spellings onto one directory.
+      #
+      # Climbs to the nearest ancestor whose name actually contains a cased
+      # character, since a name like "42" flips to itself and proves nothing.
+      # When nothing can be determined — no cased ancestor, a root that does not
+      # exist, a permission error — it reports case-insensitive, which
+      # over-excludes rather than leaving the hole open.
+      def probe_case_insensitive(root)
+        return true unless File.directory?(root)
+
+        path = root
+        loop do
+          parent  = File.dirname(path)
+          base    = File.basename(path)
+          flipped = base.swapcase
+
+          return File.identical?(path, File.join(parent, flipped)) unless flipped == base
+          break if parent == path
+
+          path = parent
+        end
+
+        true
+      rescue SystemCallError
+        true
+      end
+    end
+
+    # +root+ is the workspace the paths are relative to; it decides only whether
+    # case is folded. Defaults to the resolved workspace root.
+    def initialize(patterns, root: nil)
+      @fold_case = self.class.case_insensitive_filesystem?(root || WorkspaceRootResolver.call)
+      @patterns  = patterns.map { |pattern| normalize(pattern.to_s) }.reject(&:empty?)
     end
 
     def excluded?(relative_path)
-      @patterns.any? { |pattern| matches?(pattern, relative_path) }
+      rel = normalize(relative_path.to_s)
+      @patterns.any? { |pattern| matches?(pattern, rel) }
     end
 
     private
@@ -19,5 +104,22 @@ module Mbeditor
         File.basename(rel) == pattern || rel.split("/").include?(pattern)
       end
     end
+
+    # "/" is ASCII and survives both steps, so the caller can normalize a whole
+    # path in one pass and split it afterwards.
+    def normalize(str)
+      # ASCII is already NFC, so only the case step can apply.
+      return @fold_case ? str.downcase : str if str.ascii_only?
+
+      utf8 = str.encoding == Encoding::UTF_8 ? str : str.dup.force_encoding(Encoding::UTF_8)
+      # Undecodable bytes become U+FFFD. This is a comparison key, never a path
+      # we open, and scrubbing keeps a malformed name from skipping the fold
+      # (and raising) on its way past an exclusion.
+      utf8 = utf8.scrub unless utf8.valid_encoding?
+      utf8 = utf8.unicode_normalize(:nfc)
+      @fold_case ? utf8.downcase : utf8
+    rescue ArgumentError, Encoding::CompatibilityError
+      str
+    end
   end
 end

data/app/services/mbeditor/file_tree_service.rb

@@ -15,7 +15,7 @@ module Mbeditor
         end
       end
 
-      matcher = ExclusionMatcher.new(Mbeditor.configuration.excluded_paths)
+      matcher = ExclusionMatcher.new(Mbeditor.configuration.excluded_paths, root: root)
       data = traverse(root, root, matcher)
 
       MUTEX.synchronize do

data/app/services/mbeditor/git_line_diff_service.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Mbeditor
+  # Per-line git status for one file, for colouring the editor's line numbers.
+  #
+  # Wraps `git diff -U0` (working tree vs HEAD) and turns its hunk headers into
+  # line ranges in the *current* file:
+  #
+  #   {
+  #     "added"    => [{ "start" => 12, "end" => 14 }, ...],
+  #     "modified" => [{ "start" => 30, "end" => 30 }, ...],
+  #     "deleted"  => [{ "start" => 47, "end" => 47 }, ...],
+  #     "tracked"  => true
+  #   }
+  #
+  # A deletion has no lines left to mark, so it is reported as the single line
+  # the removed content sat after — line 0 when the file's opening lines were
+  # the ones deleted, which the frontend renders above the first line.
+  #
+  # An untracked file has no HEAD side at all, so every line counts as added.
+  class GitLineDiffService
+    include GitService
+
+    # @@ -<old_start>[,<old_count>] +<new_start>[,<new_count>] @@
+    HUNK_HEADER = /\A@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+
+    attr_reader :repo_path, :file_path
+
+    def initialize(repo_path:, file_path:)
+      @repo_path = repo_path.to_s
+      @file_path = file_path.to_s
+    end
+
+    def call
+      return untracked_result if untracked?
+
+      output, status = GitService.run_git(
+        repo_path, "diff", "--no-color", "--no-ext-diff", "-U0", "HEAD", "--", file_path
+      )
+      # A non-zero status here means the diff could not be produced at all (no
+      # HEAD yet, path outside the repo). Report a clean file rather than
+      # raising: line colouring is decoration, never a reason to fail a load.
+      return empty_result unless status.success?
+
+      parse(output)
+    end
+
+    private
+
+    def empty_result
+      { "added" => [], "modified" => [], "deleted" => [], "tracked" => true }
+    end
+
+    def untracked_result
+      line_count = count_lines
+      added = line_count.positive? ? [{ "start" => 1, "end" => line_count }] : []
+      { "added" => added, "modified" => [], "deleted" => [], "tracked" => false }
+    end
+
+    def untracked?
+      output, status = GitService.run_git(repo_path, "ls-files", "--error-unmatch", "--", file_path)
+      !(status.success? && output.present?)
+    end
+
+    def count_lines
+      absolute = File.join(repo_path, file_path)
+      return 0 unless File.file?(absolute)
+
+      File.foreach(absolute).count
+    rescue SystemCallError
+      0
+    end
+
+    def parse(output)
+      result = empty_result
+
+      output.each_line do |line|
+        match = HUNK_HEADER.match(line)
+        next unless match
+
+        old_count = match[2] ? match[2].to_i : 1
+        new_start = match[3].to_i
+        new_count = match[4] ? match[4].to_i : 1
+
+        if new_count.zero?
+          # Pure deletion. git reports the line the removed block followed, so
+          # new_start is already that line (and 0 when it was the file's head).
+          result["deleted"] << { "start" => new_start, "end" => new_start }
+        elsif old_count.zero?
+          result["added"] << { "start" => new_start, "end" => new_start + new_count - 1 }
+        else
+          result["modified"] << { "start" => new_start, "end" => new_start + new_count - 1 }
+        end
+      end
+
+      result
+    end
+  end
+end

data/app/services/mbeditor/git_service.rb

@@ -139,8 +139,8 @@ module Mbeditor
     # Resolve a file path safely within repo_path.  Returns full path string or
     # nil if the path escapes the root.
     #
-    # Resolves symlinks on the nearest existing ancestor of the target so that a
-    # symlink inside the repo cannot escape it, mirroring
+    # Follows symlinks (via SafePath, including dangling ones) so that a symlink
+    # inside the repo cannot escape it, mirroring
     # ApplicationController#resolve_path.  When repo_path is not a real directory
     # (e.g. unit tests with synthetic roots) the symlink check is skipped, since
     # there is nothing on disk to resolve and repo_path is server-controlled.
@@ -151,14 +151,7 @@ module Mbeditor
       full = File.expand_path(relative.to_s, root)
       return nil unless full.start_with?("#{root}/") || full == root
       return full unless File.directory?(root)
-
-      # Walk up to the nearest existing ancestor, then realpath both it and the
-      # root and confirm the resolved target is still inside the resolved root.
-      check = full
-      check = File.dirname(check) until File.exist?(check)
-      real_root = File.realpath(root)
-      real = File.realpath(check)
-      return nil unless real.start_with?("#{real_root}/") || real == real_root
+      return nil unless SafePath.within?(root, full)
 
       full
     rescue Errno::EACCES

data/app/services/mbeditor/ruby_definition_service.rb

@@ -181,7 +181,7 @@ module Mbeditor
       @symbol            = symbol
       @excluded_paths    = Array(excluded_paths)
       @included_dirs     = Array(included_dirs)
-      @exclusion_matcher = ExclusionMatcher.new(@excluded_paths)
+      @exclusion_matcher = ExclusionMatcher.new(@excluded_paths, root: @workspace_root)
       @shared_cache      = self.class.send(:file_cache)
       @shared_mutex      = self.class.send(:mutex)
     end

data/app/services/mbeditor/safe_path.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mbeditor
+  # Containment check for paths that may not exist yet.
+  #
+  # +File.realpath+ refuses to resolve a path whose final component is missing,
+  # so callers that create files have to reason about the nearest existing
+  # ancestor instead. Doing that with +File.exist?+ is unsafe: it *follows*
+  # symlinks, so a symlink pointing at a missing target reports false and an
+  # existence walk steps straight past it, back to the safely-contained parent.
+  # A subsequent +File.open+ follows the link and writes outside the root.
+  #
+  # SafePath resolves the link chain itself with +File.symlink?+/+File.readlink+
+  # (both lstat-based, neither follows) so a dangling symlink is judged by where
+  # it points, not by whether that target happens to exist yet.
+  module SafePath
+    # Guards against symlink cycles, which surface as a path that neither
+    # exists nor terminates.
+    MAX_SYMLINK_HOPS = 32
+
+    module_function
+
+    # True when +path+ resolves to a location inside +root+, following every
+    # symlink component including dangling ones. +root+ must exist.
+    def within?(root, path)
+      real_root = File.realpath(root.to_s)
+      target    = canonical(path.to_s)
+      return false unless target
+
+      target == real_root || target.start_with?("#{real_root}/")
+    rescue SystemCallError
+      false
+    end
+
+    # The filesystem location a write to +path+ would actually land on, with
+    # all symlinks expanded. Returns nil when the link chain cycles or exceeds
+    # MAX_SYMLINK_HOPS.
+    def canonical(path, hops = 0)
+      return nil if hops > MAX_SYMLINK_HOPS
+      # Anything that exists (including a symlink with a live target) resolves
+      # normally; realpath expands the whole chain for us.
+      return File.realpath(path) if File.exist?(path)
+
+      parent = File.dirname(path)
+      return nil if parent == path # ran off the top without finding anything
+
+      real_parent = canonical(parent, hops)
+      return nil unless real_parent
+
+      if File.symlink?(path)
+        canonical(File.absolute_path(File.readlink(path), real_parent), hops + 1)
+      else
+        File.join(real_parent, File.basename(path))
+      end
+    end
+  end
+end

data/app/services/mbeditor/search_replace_service.rb

@@ -100,7 +100,7 @@ module Mbeditor
         end
 
         pattern = build_pattern(query, use_regex: use_regex, match_case: match_case, whole_word: whole_word)
-        matcher = ExclusionMatcher.new(excluded_paths)
+        matcher = ExclusionMatcher.new(excluded_paths, root: workspace_root)
         replaced_count = 0
         files_affected = []
         errors = []
@@ -182,7 +182,7 @@ module Mbeditor
         tier = pick_tier(root)
         env, args = build_command(tier, root, query, use_regex: use_regex, match_case: match_case,
                                   whole_word: whole_word, excluded_paths: excluded_paths, paths: paths)
-        matcher = ExclusionMatcher.new(excluded_paths)
+        matcher = ExclusionMatcher.new(excluded_paths, root: root)
         results = []
         timed_out = false
         timeout_secs = Mbeditor.configuration.search_timeout

data/lib/mbeditor/configuration.rb

@@ -11,7 +11,7 @@ module Mbeditor
                   :mount_path, :resilient_routing, :js_global_identifiers,
                   :js_syntax_check, :babel_standalone_path,
                   :ruby_lsp, :ruby_lsp_command, :ruby_lsp_timeout,
-                  :search_respect_gitignore
+                  :search_respect_gitignore, :watch_files
 
     def initialize
       @allowed_environments = [:development]
@@ -42,6 +42,7 @@ module Mbeditor
       @ruby_lsp_timeout = 3     # seconds per LSP request before falling back to the built-in services
       @mount_path = nil # explicit URL prefix override; nil falls through to detection/"/mbeditor"
       @resilient_routing = true # serve /mbeditor from middleware so the editor survives a broken host routes.rb; false is the escape hatch
+      @watch_files = :auto # watch the workspace for changes made outside the editor when the host has the `listen` gem; false disables
     end
   end
 end

data/lib/mbeditor/engine.rb

@@ -4,6 +4,7 @@ require "mbeditor/rack/silence_ping_request"
 require "mbeditor/rack/handle_pending_migrations"
 require "mbeditor/rack/resilient_router"
 require "mbeditor/cable_log_filter"
+require "mbeditor/file_watcher"
 
 module Mbeditor
   class Engine < ::Rails::Engine
@@ -81,6 +82,8 @@ module Mbeditor
         raise ArgumentError, "[mbeditor] config.workspace_root is set to '#{cfg.workspace_root}' but that path is not a directory"
       end
 
+      Mbeditor::FileWatcher.start_if_enabled
+
       if cfg.redmine_enabled
         require "uri"
         if cfg.redmine_url.blank?

data/lib/mbeditor/file_watcher.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Mbeditor
+  # Watches the workspace for changes made outside the editor — a terminal
+  # `git checkout`, a rebase, another editor, a generator — and broadcasts the
+  # same `files_changed` payload the mutation endpoints send. Clients refresh
+  # the file tree, git line-number tinting and cached globals from it.
+  #
+  # The `listen` gem is an optional host dependency. Without it the editor
+  # behaves exactly as before: only changes made *through* mbeditor announce
+  # themselves. Nothing warns loudly about the missing gem — it is opt-in.
+  #
+  # Only one watcher runs per process. It is deliberately not started in test
+  # or in non-server processes (rake, console, the Rails runner), where a
+  # background listener thread is pure overhead.
+  module FileWatcher
+    # Coalesce bursts: a branch switch touches hundreds of files, and each one
+    # would otherwise be its own broadcast.
+    DEBOUNCE_SECONDS = 0.3
+
+    class << self
+      def available?
+        return @available if defined?(@available)
+
+        @available = begin
+          require "listen"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      def running?
+        !@listener.nil?
+      end
+
+      # Boot entry point. Confined to the environments the editor is allowed in
+      # and to processes that actually serve requests — a rake task or console
+      # has no client to broadcast to, and a listener thread there would only
+      # burn file handles. MBEDITOR_FORCE_WATCH overrides the process check for
+      # unusual servers and for tests.
+      def start_if_enabled
+        cfg = Mbeditor.configuration
+        return false if cfg.watch_files == false
+        return false unless cfg.allowed_environments.map(&:to_s).include?(Rails.env.to_s)
+        return false unless serving_requests?
+
+        start(cfg.workspace_root.presence || Rails.root.to_s)
+      end
+
+      # Returns true when a watcher was started, false for every reason not to
+      # (gem absent, already running, no workspace, disabled by config).
+      def start(root)
+        return false unless available?
+        return false if running?
+
+        root = root.to_s
+        return false if root.empty? || !File.directory?(root)
+
+        ignores = ignore_patterns(root)
+        @listener = ::Listen.to(root, ignore: ignores, latency: DEBOUNCE_SECONDS) do |modified, added, removed|
+          broadcast(root, modified + added + removed)
+        end
+        @listener.start
+        Rails.logger.info("[mbeditor] watching #{root} for external changes")
+        true
+      rescue StandardError => e
+        # A watcher that cannot start must never take the host app down with it:
+        # inotify limits on Linux, permission issues, an unreadable root.
+        Rails.logger.warn("[mbeditor] file watcher failed to start: #{e.class}: #{e.message}")
+        @listener = nil
+        false
+      end
+
+      def stop
+        @listener&.stop
+      rescue StandardError
+        nil
+      ensure
+        @listener = nil
+      end
+
+      private
+
+      def serving_requests?
+        return true if ENV["MBEDITOR_FORCE_WATCH"]
+
+        defined?(Rails::Server) || defined?(Puma::Server) || defined?(Unicorn) || defined?(Passenger)
+      end
+
+      # `listen` matches ignores against paths relative to the watched root, so
+      # the configured exclusions become anchored regexps. Escaping matters:
+      # entries like "vendor/bundle" and "public/assets" contain separators, and
+      # a stray metacharacter in host config should not build a bogus pattern.
+      def ignore_patterns(root)
+        Array(Mbeditor.configuration.excluded_paths).map(&:to_s).reject(&:empty?).map do |path|
+          %r{\A#{Regexp.escape(path.delete_prefix("/").delete_suffix("/"))}(/|\z)}
+        end
+      end
+
+      # Paths arrive absolute. Anything that does not sit under the workspace
+      # is dropped rather than sent raw: the client keys everything by
+      # workspace-relative path, and an absolute one would leak host layout.
+      def relative_paths(root, paths)
+        paths.filter_map do |path|
+          rel = path.to_s.delete_prefix("#{root}/")
+          rel unless rel.empty? || rel == path.to_s
+        end
+      end
+
+      def broadcast(root, paths)
+        relative = relative_paths(root, paths)
+
+        invalidate_caches(root)
+        return unless defined?(ActionCable.server)
+
+        payload = { type: "files_changed" }
+        payload[:paths] = relative.first(200) if relative.any?
+        ActionCable.server.broadcast("mbeditor_editor", payload)
+      rescue StandardError => e
+        Rails.logger.warn("[mbeditor] file watcher broadcast failed: #{e.class}: #{e.message}")
+      end
+
+      # Mirrors EditorsController#broadcast_files_changed: a change the editor
+      # did not make invalidates exactly the same caches as one it did.
+      def invalidate_caches(root)
+        FileTreeService.invalidate(root)
+        SearchReplaceService.invalidate_cache(root)
+        JsGlobalsService.invalidate(root)
+        GitInfoService.invalidate(root)
+      rescue StandardError => e
+        Rails.logger.warn("[mbeditor] file watcher cache invalidation failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end