stream_weaver 0.3.0

data/lib/stream_weaver/canvas/client.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'json'
+require 'fileutils'
+require_relative 'protocol'
+
+module StreamWeaver
+  module Canvas
+    # Client for communicating with the Canvas Bridge via Unix socket.
+    # Used by CLI commands to send messages to the bridge.
+    class Client
+      class NotRunningError < StandardError; end
+      class ConnectionError < StandardError; end
+
+      SOCKET_PATH = File.expand_path('~/.streamweaver/canvas.sock')
+      PID_FILE_PATH = File.expand_path('~/.streamweaver/canvas.pid')
+      DEFAULT_TIMEOUT = 300 # 5 minutes
+
+      class << self
+        # STREAMWEAVER_CANVAS_SOCKET / _PID redirect the whole bridge --
+        # socket, pid file, and (because the bridge is spawned with the
+        # environment it inherits) the server half too. This exists so a
+        # test, or a deliberately separate instance, can run its own bridge
+        # without stopping the one the developer has open in a browser and
+        # taking every live canvas session with it.
+        def socket_path
+          ENV['STREAMWEAVER_CANVAS_SOCKET'] || SOCKET_PATH
+        end
+
+        def pid_file_path
+          ENV['STREAMWEAVER_CANVAS_PID'] || PID_FILE_PATH
+        end
+
+        # Check if the bridge process is running
+        # @return [Boolean]
+        def bridge_running?
+          return false unless File.exist?(pid_file_path)
+
+          content = File.read(pid_file_path)
+          # Parse pid=VALUE format
+          pid = content[/pid=(\d+)/, 1]&.to_i || content.strip.to_i
+          return false if pid.zero?
+
+          # Check if process exists
+          Process.kill(0, pid)
+          true
+        rescue Errno::ESRCH, Errno::EPERM
+          # Process not found or no permission
+          cleanup_stale_files
+          false
+        end
+
+        # Clean up stale PID and socket files
+        def cleanup_stale_files
+          File.delete(pid_file_path) if File.exist?(pid_file_path)
+          File.delete(socket_path) if File.exist?(socket_path)
+        end
+
+        # Send a message to the bridge and return the response
+        # @param message [Hash] Message to send
+        # @param timeout [Integer] Timeout in seconds
+        # @return [Hash, nil] Response message or nil
+        def send_message(message, timeout: 5)
+          raise NotRunningError, "Canvas bridge is not running" unless bridge_running?
+
+          socket = UNIXSocket.new(socket_path)
+          socket.write(Protocol.encode(message))
+
+          # Read response with timeout
+          if IO.select([socket], nil, nil, timeout)
+            buffer = ''
+            while (chunk = socket.read_nonblock(4096, exception: false))
+              break if chunk == :wait_readable
+              buffer += chunk
+              break if buffer.include?("\n")
+            end
+
+            messages, _ = Protocol.parse_buffer(buffer)
+            messages.first
+          else
+            nil
+          end
+        rescue Errno::ECONNREFUSED, Errno::ENOENT => e
+          raise ConnectionError, "Cannot connect to canvas bridge: #{e.message}"
+        ensure
+          socket&.close
+        end
+
+        # Send a message and wait for a specific event type
+        # @param message [Hash] Message to send
+        # @param event_type [String] Event type to wait for
+        # @param timeout [Integer] Timeout in seconds
+        # @return [Hash, nil] Event message or nil
+        def send_and_wait(message, event_type:, timeout: DEFAULT_TIMEOUT)
+          raise NotRunningError, "Canvas bridge is not running" unless bridge_running?
+
+          socket = UNIXSocket.new(socket_path)
+          socket.write(Protocol.encode(message))
+
+          start_time = Time.now
+          buffer = ''
+
+          loop do
+            remaining = timeout - (Time.now - start_time)
+            break if remaining <= 0
+
+            if IO.select([socket], nil, nil, [remaining, 1].min)
+              chunk = socket.read_nonblock(4096, exception: false)
+              next if chunk == :wait_readable
+              buffer += chunk
+
+              messages, buffer = Protocol.parse_buffer(buffer)
+              messages.each do |msg|
+                return msg if msg[:type] == event_type
+              end
+            end
+          end
+
+          nil
+        rescue Errno::ECONNREFUSED, Errno::ENOENT => e
+          raise ConnectionError, "Cannot connect to canvas bridge: #{e.message}"
+        ensure
+          socket&.close
+        end
+
+        # Hold ONE connection open and yield every event for `name` until the
+        # bridge closes it or the block breaks. This is what a long-lived
+        # listener wants: `send_and_wait` takes a single event and closes the
+        # socket, so a loop built on it is deaf for the whole gap between
+        # handling one click and reopening -- which is exactly when the
+        # re-push is happening and the user is most likely to click again.
+        #
+        # Events are filtered by session name because the bridge forwards
+        # every session's events to every connected client
+        # (docs/bug-2026-08-24-canvas-bridge-broadcasts-no-session-filtering.md).
+        #
+        # @param name [String, nil] session to filter on; nil yields all
+        # @yield [Hash] each event message
+        def each_event(name = nil)
+          raise NotRunningError, "Canvas bridge is not running" unless bridge_running?
+
+          socket = UNIXSocket.new(socket_path)
+          buffer = ''
+
+          loop do
+            # readpartial blocks until there are bytes and raises at EOF --
+            # no poll interval to burn, and no third spelling of "closed".
+            # A peer reset is the same event as a clean close as far as this
+            # loop is concerned: the bridge is gone, so return and let the
+            # caller decide whether to reconnect.
+            buffer += socket.readpartial(4096)
+
+            messages, buffer = Protocol.parse_buffer(buffer)
+            messages.each do |msg|
+              next unless msg[:type] == 'event'
+              next if name && msg[:name] != name
+
+              yield msg
+            end
+          rescue EOFError, Errno::ECONNRESET
+            break
+          end
+        rescue Errno::ECONNREFUSED, Errno::ENOENT => e
+          raise ConnectionError, "Cannot connect to canvas bridge: #{e.message}"
+        ensure
+          socket&.close
+        end
+
+        # Start the bridge process if not running
+        # @return [Hash] { pid: Integer, port: Integer }
+        def ensure_bridge_running
+          if bridge_running?
+            info = read_bridge_info
+            # Verify HTTP server is actually responding
+            if info && info[:port] && http_healthy?(info[:port])
+              return info
+            end
+            # Bridge process exists but HTTP not responding - restart
+            cleanup_stale_files
+          end
+
+          start_bridge
+        end
+
+        # Check if HTTP server is responding on given port
+        def http_healthy?(port)
+          require 'net/http'
+          uri = URI("http://127.0.0.1:#{port}/health")
+          response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 1) do |http|
+            http.get(uri.path)
+          end
+          response.is_a?(Net::HTTPSuccess)
+        rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, Net::OpenTimeout, Net::ReadTimeout
+          false
+        end
+
+        # Start the bridge process
+        # @return [Hash] { pid: Integer, port: Integer }
+        def start_bridge
+          require_relative 'bridge_server'
+
+          # Ensure directory exists
+          FileUtils.mkdir_p(File.dirname(pid_file_path))
+
+          # Get the lib path
+          lib_path = File.expand_path('../..', __dir__)
+
+          # Create startup script
+          script = <<~RUBY
+            $LOAD_PATH.unshift('#{lib_path}')
+            require 'stream_weaver'
+            require 'stream_weaver/canvas/bridge_server'
+            StreamWeaver::Canvas::BridgeServer.run!
+          RUBY
+
+          # Write script to temp file
+          script_file = File.join(File.dirname(pid_file_path), 'canvas_start.rb')
+          File.write(script_file, script)
+
+          # Log file
+          log_file = File.join(File.dirname(pid_file_path), 'canvas.log')
+
+          # Spawn the bridge process
+          pid = spawn(
+            RbConfig.ruby, script_file,
+            out: [log_file, 'a'],
+            err: [log_file, 'a'],
+            pgroup: true
+          )
+          Process.detach(pid)
+
+          # Wait for both socket AND HTTP server to be ready
+          30.times do
+            if File.exist?(socket_path) && File.exist?(pid_file_path)
+              info = read_bridge_info
+              if info && info[:port]
+                # Probe HTTP server to confirm it's actually listening
+                begin
+                  require 'net/http'
+                  uri = URI("http://127.0.0.1:#{info[:port]}/health")
+                  response = Net::HTTP.get_response(uri)
+                  return info if response.is_a?(Net::HTTPSuccess)
+                rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL
+                  # Server not ready yet
+                end
+              end
+            end
+            sleep 0.2
+          end
+
+          # Fallback - return what we have
+          read_bridge_info || { pid: pid, port: BridgeServer::DEFAULT_PORT }
+        end
+
+        # Read bridge info from PID file
+        # @return [Hash] { pid: Integer, port: Integer }
+        def read_bridge_info
+          return nil unless File.exist?(pid_file_path)
+
+          content = File.read(pid_file_path)
+          pid = content[/pid=(\d+)/, 1]&.to_i
+          port = content[/port=(\d+)/, 1]&.to_i || Bridge::DEFAULT_PORT
+
+          { pid: pid, port: port }
+        end
+
+        # Stop the bridge process
+        # @return [Boolean] true if stopped
+        def stop_bridge
+          return false unless bridge_running?
+
+          info = read_bridge_info
+          if info && info[:port]
+            require 'net/http'
+            begin
+              Net::HTTP.start('127.0.0.1', info[:port], open_timeout: 2, read_timeout: 2) do |http|
+                http.post('/shutdown', '')
+              end
+              sleep 0.5
+            rescue StandardError
+              # HTTP shutdown failed — fall back to SIGTERM
+              pid = info[:pid] || File.read(pid_file_path)[/pid=(\d+)/, 1]&.to_i
+              Process.kill('TERM', pid) if pid
+              sleep 0.5
+            end
+          end
+
+          cleanup_stale_files
+          true
+        rescue Errno::ESRCH
+          cleanup_stale_files
+          true
+        end
+      end
+    end
+  end
+end

data/lib/stream_weaver/canvas/doc_roots.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'stream_weaver/canvas/doc_store'
+
+module StreamWeaver
+  module Canvas
+    # Finds every docs root on this machine that canvas-read should show,
+    # and gives each one a display label (stream_weaver-iugu).
+    #
+    # Two sources, unioned, because neither alone is sufficient:
+    #
+    # - **Scan** of `$STREAMWEAVER_DOCS_SCAN_ROOTS` (default `~/work`), one
+    #   level deep for `*/docs/streamweaver_canvas`. Catches repos under a
+    #   known parent automatically -- including ones that arrived via `git
+    #   pull` and were never saved to or visited on this machine, which is
+    #   exactly what a registry alone would miss.
+    # - **Registry** at `~/.streamweaver/docs_roots.log`: one absolute docs
+    #   root per line, append-only. Catches repos that live somewhere the
+    #   scan doesn't reach (`~/rails/...`, `~/src/...`), which is exactly
+    #   what a scan alone would miss. Written by DocStore.save and by
+    #   `canvas-read <explicit path>` -- visiting a pre-existing doc once is
+    #   what backfills it, so there is no separate registration command.
+    #
+    # Deliberately NOT a database: a flat newline-delimited file of absolute
+    # paths needs no schema, no locking (a sub-PIPE_BUF append on a local
+    # filesystem is atomic), no corruption recovery, and can be fixed with a
+    # text editor. Everything is filtered through File.directory? on read, so
+    # a repo that is deleted or moved simply drops off -- self-healing, no
+    # `forget` operation to build or remember to call.
+    #
+    # No cache/TTL on the scan: it is a single-digit-millisecond glob at real
+    # repo counts, and staleness in a tool whose whole job is "show me what's
+    # on disk right now" is worse than the work it would save.
+    module DocRoots
+      DEFAULT_REGISTRY_PATH = File.expand_path('~/.streamweaver/docs_roots.log')
+
+      # Colon-separated, like PATH. `~/work` is the default because that's
+      # where the overwhelming majority of repos live; anything else is what
+      # the registry half is for.
+      DEFAULT_SCAN_ROOTS = '~/work'
+
+      # The label for DocStore::DEFAULT_ROOT. Not a repo, so it gets a name
+      # rather than a basename ('canvas' would be meaningless in the rail).
+      GLOBAL_LABEL = 'Global'
+
+      module_function
+
+      # Read fresh on every call (not memoized into a constant) so an ENV
+      # override flips behavior mid-process -- same contract DocStore.path
+      # has, and what keeps specs from writing to the real registry.
+      def registry_path
+        env = ENV['STREAMWEAVER_DOCS_REGISTRY']
+        env && !env.empty? ? File.expand_path(env) : DEFAULT_REGISTRY_PATH
+      end
+
+      # An explicitly empty STREAMWEAVER_DOCS_SCAN_ROOTS means "scan nothing"
+      # (registry only), which is distinct from unset meaning "scan ~/work".
+      def scan_roots
+        raw = ENV['STREAMWEAVER_DOCS_SCAN_ROOTS'] || DEFAULT_SCAN_ROOTS
+        raw.split(File::PATH_SEPARATOR).reject { |p| p.strip.empty? }.map { |p| File.expand_path(p.strip) }
+      end
+
+      # Symlink-resolved path, used only as a dedupe/comparison KEY -- never
+      # for display. macOS's /tmp -> /private/tmp is the everyday case: the
+      # same directory reached two ways must not become two sidebar groups.
+      # Falls back to expand_path for a path that no longer resolves.
+      def canonical(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      # Appends `root` to the registry. Returns the recorded absolute path,
+      # or nil if there was nothing to record or the write failed.
+      #
+      # Skips the append when the exact line is already present: duplicates
+      # are harmless (reads dedupe), but re-saving the same doc a thousand
+      # times shouldn't grow the file a thousand lines. The check is a read
+      # of a few hundred bytes, and a lost race just writes a duplicate --
+      # which is, again, harmless.
+      #
+      # Swallows filesystem errors on purpose: failing to record a root
+      # degrades discovery, and must never take down the save that triggered
+      # it.
+      def record(root)
+        return nil unless root.is_a?(String) && !root.empty?
+
+        path = File.expand_path(root)
+        return path if raw_entries.include?(path)
+
+        FileUtils.mkdir_p(File.dirname(registry_path))
+        File.open(registry_path, 'a') { |f| f.write("#{path}\n") }
+        path
+      rescue SystemCallError
+        nil
+      end
+
+      # Records `dir` only when nothing already discovers it -- the
+      # `canvas-read <explicit path>` backfill. A path the scan already
+      # finds needs no registry entry.
+      def record_if_new(dir)
+        return nil unless dir && File.directory?(dir)
+
+        key = canonical(dir)
+        return nil if roots.any? { |r| canonical(r) == key }
+
+        record(dir)
+      end
+
+      # Registry contents that still exist, deduped, in file order.
+      def registered
+        raw_entries.uniq.select { |p| File.directory?(p) }
+      end
+
+      # `*/docs/streamweaver_canvas` under each scan root, one level deep.
+      def scanned
+        scan_roots.flat_map { |r| Dir.glob(File.join(r, '*', DocStore::DOCS_SUBPATH)) }
+                  .select { |p| File.directory?(p) }
+                  .sort
+      end
+
+      # Every docs root to show, deduped by canonical path and ordered
+      # host-repo first, then scanned, then registered, then global.
+      #
+      # DocStore.path leads deliberately: it is the repo the reader was
+      # launched from, it is what the default sidebar filter selects, and it
+      # may be reachable by neither other source (a repo outside the scan
+      # roots that has been cloned but never saved to on this machine, or a
+      # STREAMWEAVER_DOC_ROOT override).
+      #
+      # Keyed by canonical path, NOT by basename: two repos named `docs` in
+      # different parents are two roots, and a basename-keyed hash would
+      # silently drop one of them. Basename is a display label only -- see
+      # #labels, which disambiguates collisions instead of discarding them.
+      #
+      # A discovered root that currently holds no `*.{rb,org}` is dropped:
+      # File.directory? alone answers "does this place exist," not "is there
+      # anything here to show," and a root that once had docs and no longer
+      # does (a `git pull` that removed them, deleting the last one from the
+      # reader -- stream_weaver-uvaj) is a sidebar heading that discloses
+      # nothing. The two roots the host process owns are exempt and always
+      # listed while they exist as directories: DocStore.path is the repo the
+      # reader was launched from and the target of its own Save-as-doc, and
+      # DocStore::DEFAULT_ROOT is the global fallback store -- both need to
+      # stay wired up (mtime-watched by the reader's FileList) so the FIRST
+      # doc saved into an empty one shows up without a restart.
+      def roots
+        always     = [DocStore.path, DocStore::DEFAULT_ROOT].compact.map { |p| File.expand_path(p) }
+        candidates = [DocStore.path, *scanned, *registered, DocStore::DEFAULT_ROOT]
+        seen = {}
+        candidates.each do |candidate|
+          next if candidate.nil? || candidate.to_s.empty?
+
+          expanded = File.expand_path(candidate)
+          next unless File.directory?(expanded)
+          next unless always.include?(expanded) || docs?(expanded)
+
+          seen[canonical(expanded)] ||= expanded
+        end
+        seen.values
+      end
+
+      # True when `root` directly contains at least one doc file. Same
+      # '*.{rb,org}' glob FileList.build uses to populate the sidebar, so
+      # "root is listed" and "root produces a group" can't disagree.
+      def docs?(root)
+        Dir.glob(File.join(root, '*.{rb,org}')).any?
+      end
+
+      # {root => label} for `roots_list`, insertion-ordered. Labels are
+      # unique across the hash, since a label is what `?repo=` addresses --
+      # two groups sharing one label would be unfilterable.
+      def labels(roots_list = roots)
+        used = {}
+        roots_list.each_with_object({}) do |root, out|
+          out[root] = unique_label(root, used)
+        end
+      end
+
+      # The repo directory a docs root belongs to -- the root with the
+      # `docs/streamweaver_canvas` suffix removed. A root that doesn't carry
+      # that suffix (a STREAMWEAVER_DOC_ROOT override, the global store) is
+      # its own repo dir.
+      def repo_dir(root)
+        suffix = File::SEPARATOR + DocStore::DOCS_SUBPATH
+        root.end_with?(suffix) ? root[0...-suffix.length] : root
+      end
+
+      def base_label(root)
+        return GLOBAL_LABEL if canonical(root) == canonical(DocStore::DEFAULT_ROOT)
+
+        File.basename(repo_dir(root))
+      end
+
+      # Disambiguates a colliding basename with its parent directory rather
+      # than dropping the root -- `~/work/notes` and `~/src/notes` are two
+      # real repos and both have to be reachable.
+      def unique_label(root, used)
+        base = base_label(root)
+        return claim(base, used) unless used.key?(base)
+
+        parent = File.basename(File.dirname(repo_dir(root)))
+        candidate = "#{base} (#{parent})"
+        n = 2
+        while used.key?(candidate)
+          candidate = "#{base} (#{parent} #{n})"
+          n += 1
+        end
+        claim(candidate, used)
+      end
+      private_class_method :unique_label
+
+      def claim(label, used)
+        used[label] = true
+        label
+      end
+      private_class_method :claim
+
+      # Every non-blank line, expanded, without the directory filter --
+      # `record`'s duplicate check needs to see entries that no longer
+      # exist, or a deleted-and-recreated root would append forever.
+      def raw_entries
+        return [] unless File.file?(registry_path)
+
+        File.readlines(registry_path, chomp: true).map(&:strip).reject(&:empty?).map { |p| File.expand_path(p) }
+      rescue SystemCallError
+        []
+      end
+      private_class_method :raw_entries
+    end
+  end
+end