msnav 0.2.0

data/lib/msnav/store.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "sqlite3"
+
+module Msnav
+  # Access to the shared coderag SQLite index.
+  #
+  # coderag (Python) owns the schema and the writes that matter (graph, facts,
+  # chunks); msnav writes only the two v4 message-bus tables (`windows`,
+  # `window_commands`) that every daemon on the hub shares. One connection
+  # guarded by a Mutex: navigation itself runs on the in-memory graph, so the
+  # DB sees only window-registry traffic, generation polls, and graph reloads
+  # — serializing those is simpler than per-thread connections and equally
+  # correct across WEBrick's request threads.
+  class Store
+    SCHEMA_VERSION = 4 # the version msnav is written against
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = Pathname.new(path.to_s)
+      unless @path.file?
+        raise IndexStaleError,
+              "no index at #{@path} — build it on the host with `coderag index` " \
+              "and mount the coderag data dir into this container"
+      end
+      @mutex = Mutex.new
+      @conn = connect
+      check_version
+    end
+
+    # All DB access funnels through here. Reentrant per call site by design:
+    # never call with_conn inside with_conn.
+    def with_conn
+      @mutex.synchronize { yield @conn }
+    end
+
+    def close
+      @mutex.synchronize do
+        @conn.close unless @conn.closed?
+      end
+    end
+
+    def get_meta(key)
+      with_conn do |db|
+        row = db.get_first_row("SELECT value FROM meta WHERE key = ?", [key])
+        row && row[0]
+      end
+    end
+
+    # The shared DB's index generation — bumped by whichever coderag daemon
+    # (or host `coderag index`) last completed a build. 0 when unset.
+    def index_generation
+      (get_meta("index_generation") || 0).to_i
+    end
+
+    # Canonical [name, dirname, root] service rows as indexed on the host.
+    def services
+      with_conn do |db|
+        db.execute("SELECT name, dirname, root FROM services ORDER BY name")
+      end
+    end
+
+    private
+
+    def connect
+      db = SQLite3::Database.new(@path.to_s)
+      db.busy_timeout = 5000
+      db.execute("PRAGMA foreign_keys=ON")
+      db
+    rescue SQLite3::Exception => e
+      raise IndexStaleError, "#{@path} could not be opened (#{e.message})"
+    end
+
+    def check_version
+      row = begin
+        @conn.get_first_row("SELECT value FROM meta WHERE key='schema_version'")
+      rescue SQLite3::Exception => e
+        raise IndexStaleError,
+              "#{@path} is not a coderag database (#{e.message}) — " \
+              "delete it and run `coderag index` on the host"
+      end
+      version = row ? row[0].to_i : 0
+      if version < SCHEMA_VERSION
+        raise IndexStaleError,
+              "#{@path} is schema v#{version}, msnav needs v#{SCHEMA_VERSION} — " \
+              "run `coderag index` on the host to migrate"
+      end
+      return if version == SCHEMA_VERSION
+      # a newer coderag may have added tables msnav doesn't know; the v4
+      # tables it reads are append-only by convention, so proceed loudly
+      warn "msnav: #{@path} is schema v#{version} (msnav is written against " \
+           "v#{SCHEMA_VERSION}) — continuing, but upgrade msnav if navigation misbehaves"
+    end
+  end
+end

data/lib/msnav/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Msnav
+  VERSION = "0.2.0"
+end

data/lib/msnav/windows.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Msnav
+  # DB-backed registry of live editor windows for bridge-mode open routing —
+  # the Ruby side of coderag/daemon/windows.py, byte-compatible on the shared
+  # `windows` / `window_commands` tables so msnav daemons in Ruby containers
+  # and coderag daemons elsewhere route opens to each other's windows.
+  #
+  # Each window registers and then short-polls for commands. When /api/open
+  # targets a file another live window owns, the command is enqueued in the
+  # DB (the message bus between containers) and that window's poll delivers
+  # it. A window counts as live only while it keeps polling.
+  class WindowRegistry
+    ALIVE_SECONDS = 6.0   # a registration is live only if it polled this recently
+    PURGE_SECONDS = 3600.0 # rows this stale are garbage-collected on registration
+    # A parked open-command (no owning window yet — a new window is being
+    # opened for it) waits this long for that window's extension to register.
+    # Generous: a first-time "Reopen in Container" builds the image first.
+    PARK_SECONDS = 600.0
+    # window_id marker for parked commands.
+    PARKED = ""
+
+    COLS = "window_id, authority, roots, path_mappings, host_roots, seq, last_poll"
+
+    WindowReg = Struct.new(:window_id, :authority, :roots, :path_mappings,
+                           :host_roots, :seq, :last_poll, keyword_init: true) do
+      def alive?(now)
+        (now - last_poll) <= ALIVE_SECONDS
+      end
+    end
+
+    def initialize(store)
+      @store = store
+    end
+
+    def count
+      @store.with_conn { |db| db.get_first_value("SELECT COUNT(*) FROM windows") }
+    end
+
+    # Record (or refresh) a window. A reload re-registers with a fresh
+    # window_id but identical roots — stale entries with the same mapped
+    # (daemon-space) roots are dropped so only the live window remains.
+    def register(window_id, authority, roots, path_mappings)
+      roots = Array(roots)
+      pmaps = Array(path_mappings)
+      host_roots = roots.map { |r| root_to_host(pmaps, r) }.uniq.sort
+      hr_json = JSON.generate(host_roots)
+      now = Time.now.to_f
+      reg = nil
+      @store.with_conn do |db|
+        db.transaction(:immediate) do
+          db.execute(
+            "DELETE FROM window_commands WHERE window_id IN " \
+            "(SELECT window_id FROM windows WHERE last_poll < ?)",
+            [now - PURGE_SECONDS])
+          db.execute("DELETE FROM windows WHERE last_poll < ?",
+                     [now - PURGE_SECONDS])
+          # expired parked commands: the window they waited for never came
+          db.execute(
+            "DELETE FROM window_commands WHERE window_id = ? AND created_at < ?",
+            [PARKED, now - PARK_SECONDS])
+          db.execute(
+            "DELETE FROM windows WHERE host_roots = ? AND window_id != ?",
+            [hr_json, window_id])
+          seq = db.get_first_value(
+            "SELECT COALESCE(MAX(seq), 0) + 1 FROM windows")
+          db.execute(
+            "INSERT INTO windows (window_id, authority, roots, " \
+            "path_mappings, host_roots, seq, last_poll) " \
+            "VALUES (?, ?, ?, ?, ?, ?, ?) " \
+            "ON CONFLICT(window_id) DO UPDATE SET authority = excluded.authority, " \
+            "roots = excluded.roots, path_mappings = excluded.path_mappings, " \
+            "host_roots = excluded.host_roots, seq = excluded.seq, " \
+            "last_poll = excluded.last_poll",
+            [window_id, authority || "", JSON.generate(roots),
+             JSON.generate(pmaps), hr_json, seq, now])
+          # hand parked commands to the window that was opened FOR them: the
+          # first registration whose roots cover a parked path claims it
+          db.execute(
+            "SELECT id, payload FROM window_commands " \
+            "WHERE window_id = ? ORDER BY id", [PARKED]).each do |cmd_id, payload|
+            target = JSON.parse(payload)["path"] || ""
+            next unless host_roots.any? { |hr| under?(hr, target) }
+            db.execute("UPDATE window_commands SET window_id = ? WHERE id = ?",
+                       [window_id, cmd_id])
+          end
+          reg = WindowReg.new(window_id: window_id, authority: authority || "",
+                              roots: roots, path_mappings: pmaps,
+                              host_roots: host_roots, seq: seq, last_poll: now)
+        end
+      end
+      reg
+    end
+
+    # Mark a window as still-alive on poll; nil if it isn't registered.
+    def touch(window_id)
+      @store.with_conn do |db|
+        db.execute("UPDATE windows SET last_poll = ? WHERE window_id = ?",
+                   [Time.now.to_f, window_id])
+        return nil if db.changes.zero?
+        row = db.get_first_row(
+          "SELECT #{COLS} FROM windows WHERE window_id = ?", [window_id])
+        row && row_to_reg(row)
+      end
+    end
+
+    # Return and clear the window's pending commands — including ones
+    # enqueued by a different daemon sharing this DB.
+    def drain(window_id)
+      rows = nil
+      @store.with_conn do |db|
+        db.transaction(:immediate) do
+          rows = db.execute(
+            "SELECT id, payload FROM window_commands " \
+            "WHERE window_id = ? ORDER BY id", [window_id])
+          unless rows.empty?
+            db.execute(
+              "DELETE FROM window_commands WHERE id <= ? AND window_id = ?",
+              [rows[-1][0], window_id])
+          end
+          db.execute("UPDATE windows SET last_poll = ? WHERE window_id = ?",
+                     [Time.now.to_f, window_id])
+        end
+      end
+      rows.map { |_id, payload| JSON.parse(payload) }
+    end
+
+    # Queue an open-command on the live window that owns HOST_PATH; returns
+    # the matched registration, or nil when no live window claims it.
+    def enqueue_open(host_path, line)
+      now = Time.now.to_f
+      reg = nil
+      @store.with_conn do |db|
+        db.transaction(:immediate) do
+          rows = db.execute(
+            "SELECT #{COLS} FROM windows WHERE last_poll >= ? " \
+            "ORDER BY seq DESC", [now - ALIVE_SECONDS])
+          rows.each do |row|
+            candidate = row_to_reg(row)
+            if candidate.host_roots.any? { |hr| under?(hr, host_path) }
+              reg = candidate
+              break
+            end
+          end
+          unless reg.nil?
+            db.execute(
+              "INSERT INTO window_commands (window_id, payload, created_at) " \
+              "VALUES (?, ?, ?)",
+              [reg.window_id,
+               JSON.generate("type" => "open", "path" => host_path,
+                             "line" => line), now])
+          end
+        end
+      end
+      reg
+    end
+
+    # Queue an open for a window that does not exist yet: the caller is
+    # opening a new editor window for this service, and its extension will
+    # claim the command when it registers.
+    def park_open(host_path, line)
+      now = Time.now.to_f
+      @store.with_conn do |db|
+        db.transaction(:immediate) do
+          # re-clicking must not stack duplicate opens for the same file
+          db.execute(
+            "SELECT id, payload FROM window_commands WHERE window_id = ?",
+            [PARKED]).each do |cmd_id, payload|
+            next unless JSON.parse(payload)["path"] == host_path
+            db.execute("DELETE FROM window_commands WHERE id = ?", [cmd_id])
+          end
+          db.execute(
+            "INSERT INTO window_commands (window_id, payload, created_at) " \
+            "VALUES (?, ?, ?)",
+            [PARKED, JSON.generate("type" => "open", "path" => host_path,
+                                   "line" => line), now])
+        end
+      end
+      nil
+    end
+
+    def all
+      rows = @store.with_conn do |db|
+        db.execute("SELECT #{COLS} FROM windows ORDER BY seq")
+      end
+      rows.map { |r| row_to_reg(r) }
+    end
+
+    private
+
+    # True if PATH is ROOT itself or a descendant of it.
+    def under?(root, path)
+      root = root.sub(%r{/+\z}, "")
+      root = "/" if root.empty?
+      path == root || path.start_with?(root + "/")
+    end
+
+    # Map a window-space ROOT to daemon-space via {from: window, to: daemon}.
+    # In the per-container flow both sides see the hub at the same mount path,
+    # so the mappings are typically empty and this is the identity.
+    def root_to_host(path_mappings, root)
+      path_mappings.each do |m|
+        frm = m["from"]
+        to = m["to"]
+        next unless frm && !frm.empty? && root.start_with?(frm)
+        return to.to_s + root[frm.length..-1]
+      end
+      root
+    end
+
+    def row_to_reg(row)
+      WindowReg.new(window_id: row[0], authority: row[1],
+                    roots: JSON.parse(row[2]),
+                    path_mappings: JSON.parse(row[3]),
+                    host_roots: JSON.parse(row[4]),
+                    seq: row[5], last_poll: row[6])
+    end
+  end
+end

data/lib/msnav.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "msnav/version"
+require "msnav/errors"
+require "msnav/datadir"
+require "msnav/config"
+require "msnav/store"
+require "msnav/graph"
+require "msnav/navigator"
+require "msnav/windows"
+require "msnav/server"
+require "msnav/ctl"
+require "msnav/cli"
+
+# msnav — the Ruby "navigation face" of a coderag index.
+#
+# coderag (Python) builds the index on the host: one SQLite file holding the
+# cross-service graph. msnav reads that same file — typically through the
+# devcontainer's single data-dir bind mount — and serves the daemon endpoints
+# the coderag/msnav editor extension talks to. It never indexes; when a host
+# reindex bumps `index_generation` in the shared DB, msnav hot-reloads.
+module Msnav
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: msnav
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Yaroslav Zahoruiko
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: |
+  A pure-Ruby daemon (ruby-lsp style) serving the coderag navigation API —
+  cross-service go-to-definition, references, hover, and CodeLens targets —
+  from a coderag SQLite index. Built to run inside a Ruby devcontainer with
+  no Python: the host builds the index with coderag, the container mounts
+  the shared data dir and runs `msnav up`.
+email:
+- zahoruiko.yaroslav@gmail.com
+executables:
+- msnav
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/msnav
+- lib/msnav.rb
+- lib/msnav/cli.rb
+- lib/msnav/config.rb
+- lib/msnav/ctl.rb
+- lib/msnav/datadir.rb
+- lib/msnav/errors.rb
+- lib/msnav/graph.rb
+- lib/msnav/navigator.rb
+- lib/msnav/server.rb
+- lib/msnav/store.rb
+- lib/msnav/version.rb
+- lib/msnav/windows.rb
+homepage: https://github.com/YaroslavZahoruiko/msnav
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/YaroslavZahoruiko/msnav
+  source_code_uri: https://github.com/YaroslavZahoruiko/msnav
+  bug_tracker_uri: https://github.com/YaroslavZahoruiko/msnav/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Cross-service Ruby navigation server over a coderag index
+test_files: []