rails-markup 1.2.0

data/lib/rails_markup/client_uuid_maintenance.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "set"
+require "digest/sha1"
+
+module RailsMarkup
+  module ClientUuidMaintenance
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/
+    UUID_INPUT_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+    COLLISION_UUID_NAMESPACE = "102f1c26-3ad7-5b5c-871a-44c5f2392790"
+
+    module_function
+
+    def repair!(connection: ActiveRecord::Base.connection, table_name: RailsMarkup.config.table_name)
+      table = table_name.to_sym
+      return 0 unless connection.table_exists?(table)
+
+      connection.add_column(table, :client_uuid, :string, limit: 64) unless connection.column_exists?(table, :client_uuid)
+      repaired = repair_rows(connection, table)
+      ensure_unique_index(connection, table)
+      repaired
+    end
+
+    def invalid_count(connection: ActiveRecord::Base.connection, table_name: RailsMarkup.config.table_name)
+      table = table_name.to_sym
+      return 0 unless connection.table_exists?(table) && connection.column_exists?(table, :client_uuid)
+
+      quoted_table = connection.quote_table_name(table)
+      quoted_client_uuid = connection.quote_column_name(:client_uuid)
+      connection.select_values("SELECT #{quoted_client_uuid} FROM #{quoted_table}").count do |value|
+        !canonical_uuid?(value)
+      end
+    end
+
+    def verify!(connection: ActiveRecord::Base.connection, table_name: RailsMarkup.config.table_name)
+      table = table_name.to_sym
+      unless connection.table_exists?(table) && connection.column_exists?(table, :client_uuid)
+        raise "Rails Markup client UUID storage is not installed"
+      end
+
+      invalid = invalid_count(connection:, table_name:)
+      duplicates = casefold_duplicate_count(connection, table)
+      raise "Rails Markup has #{duplicates} case-fold duplicate client UUID(s)" if duplicates.positive?
+      raise "Rails Markup has #{invalid} annotation(s) without canonical client UUIDs" if invalid.positive?
+      unless connection.indexes(table).any? { |index| full_unique_client_uuid_index?(index) }
+        raise "Rails Markup client UUID unique index is missing"
+      end
+
+      true
+    end
+
+    def repair_rows(connection, table)
+      primary_key = connection.primary_key(table)
+      raise "Rails Markup annotations table must have a primary key" unless primary_key
+
+      quoted_table = connection.quote_table_name(table)
+      quoted_primary_key = connection.quote_column_name(primary_key)
+      quoted_client_uuid = connection.quote_column_name(:client_uuid)
+      rows = connection.select_rows(<<~SQL.squish)
+        SELECT #{quoted_primary_key}, #{quoted_client_uuid}
+        FROM #{quoted_table}
+        ORDER BY #{quoted_primary_key}
+      SQL
+      used = Set.new
+      assignments = []
+
+      rows.each do |id, current_uuid|
+        normalized = normalize_uuid(current_uuid)
+        desired = if normalized && used.add?(normalized)
+          normalized
+        elsif normalized
+          next_collision_uuid(used, normalized, id)
+        else
+          next_unique_uuid(used)
+        end
+        assignments << [id, current_uuid, desired] unless current_uuid == desired
+      end
+
+      reserved = Set.new(rows.filter_map { |_id, value| value.to_s.downcase.presence }).merge(used)
+      assignments.each do |id, _current_uuid, _desired|
+        temporary = next_unique_uuid(reserved)
+        update_uuid(connection, quoted_table, quoted_primary_key, quoted_client_uuid, id, temporary)
+      end
+      assignments.each do |id, _current_uuid, desired|
+        update_uuid(connection, quoted_table, quoted_primary_key, quoted_client_uuid, id, desired)
+      end
+      assignments.length
+    end
+    private_class_method :repair_rows
+
+    def canonical_uuid?(value)
+      value.is_a?(String) && UUID_PATTERN.match?(value)
+    end
+    private_class_method :canonical_uuid?
+
+    def normalize_uuid(value)
+      value.downcase if value.is_a?(String) && UUID_INPUT_PATTERN.match?(value)
+    end
+    private_class_method :normalize_uuid
+
+    def update_uuid(connection, table, primary_key, client_uuid, id, value)
+      connection.execute <<~SQL.squish
+        UPDATE #{table}
+        SET #{client_uuid} = #{connection.quote(value)}
+        WHERE #{primary_key} = #{connection.quote(id)}
+      SQL
+    end
+    private_class_method :update_uuid
+
+    def next_unique_uuid(used)
+      loop do
+        uuid = SecureRandom.uuid
+        return uuid if used.add?(uuid)
+      end
+    end
+    private_class_method :next_unique_uuid
+
+    def next_collision_uuid(used, normalized, id)
+      counter = 0
+      loop do
+        uuid = namespaced_uuid("casefold\0#{normalized}\0#{id}\0#{counter}")
+        return uuid if used.add?(uuid)
+        counter += 1
+      end
+    end
+    private_class_method :next_collision_uuid
+
+    def namespaced_uuid(name)
+      namespace = [COLLISION_UUID_NAMESPACE.delete("-")].pack("H*")
+      bytes = Digest::SHA1.digest(namespace + name).bytes.first(16)
+      bytes[6] = (bytes[6] & 0x0f) | 0x50
+      bytes[8] = (bytes[8] & 0x3f) | 0x80
+      hex = bytes.pack("C*").unpack1("H*")
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+    private_class_method :namespaced_uuid
+
+    def ensure_unique_index(connection, table)
+      indexes = connection.indexes(table)
+      return if indexes.any? { |index| full_unique_client_uuid_index?(index) }
+
+      default_name = connection.index_name(table, column: [:client_uuid])
+      conflict = indexes.find { |index| index.name == default_name }
+      connection.remove_index(table, name: conflict.name) if conflict
+      connection.add_index(table, :client_uuid, unique: true, name: default_name)
+    end
+    private_class_method :ensure_unique_index
+
+    def casefold_duplicate_count(connection, table)
+      quoted_table = connection.quote_table_name(table)
+      quoted_client_uuid = connection.quote_column_name(:client_uuid)
+      normalized = connection.select_values("SELECT #{quoted_client_uuid} FROM #{quoted_table}").filter_map do |value|
+        normalize_uuid(value)
+      end
+      normalized.length - normalized.uniq.length
+    end
+    private_class_method :casefold_duplicate_count
+
+    def full_unique_client_uuid_index?(index)
+      return false unless index.unique && index.columns == ["client_uuid"]
+      return false unless !index.respond_to?(:where) || index.where.nil? || index.where.to_s.strip.empty?
+      return true unless index.respond_to?(:lengths)
+
+      lengths = index.lengths
+      client_length = case lengths
+      when Hash then lengths["client_uuid"] || lengths[:client_uuid]
+      when Array then lengths[index.columns.index("client_uuid")]
+      end
+      client_length.nil?
+    end
+    private_class_method :full_unique_client_uuid_index?
+  end
+end

data/lib/rails_markup/configuration.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module RailsMarkup
+  class Configuration
+    ALLOWED_ACCENTS   = %w[indigo amber blue emerald rose].freeze
+    ALLOWED_POSITIONS = %w[tl tr br bl].freeze
+    ALLOWED_SIZES     = %w[slim compact default].freeze
+
+    # Base controller class name for dashboard/API controllers.
+    # Set to a controller that provides authentication.
+    # Example: "AdminAuthController"
+    attr_accessor :base_controller_class
+
+    # Bearer token for the external API (MCP production tools).
+    # Set to nil to disable external API.
+    attr_accessor :api_token
+
+    # Database table name for annotations.
+    attr_accessor :table_name
+
+    # Accent color for the toolbar FAB and UI elements.
+    attr_reader :toolbar_accent
+
+    # Render the annotation toolbar system at all (FAB, panel, pins, sync).
+    # Set to false to disable rails-markup entirely for a request/environment.
+    # Default: true
+    attr_accessor :toolbar_enabled
+
+    # Show the floating action button (FAB) specifically.
+    # When false, the FAB is hidden but the toolbar system stays active — pins
+    # still render and the panel is reachable via its toggle. Use when the host
+    # provides its own trigger or wants read-only pins. Requires toolbar_enabled.
+    # Default: true
+    attr_accessor :fab_visible
+
+    # URL path for "Back to app" link in the dashboard header.
+    # Set to nil to hide the link.
+    # Example: "/admin"
+    attr_accessor :return_url
+
+    # Layout for the dashboard views.
+    # Set to a host app layout name to embed within that layout.
+    # Default: "rails_markup/application" (engine's own layout)
+    # Example: "admin"
+    attr_accessor :dashboard_layout
+
+    # Number of annotations per page on the dashboard.
+    attr_reader :per_page
+
+    # Method name (Symbol) or Proc to resolve the author's display name from the current_user.
+    # Symbol: calls user.public_send(method_name) — e.g. :name, :email, :display_name
+    # Proc: receives user, returns string — e.g. ->(u) { u.full_name }
+    # Default: :email
+    attr_accessor :author_name_method
+
+    # Proc called after an annotation is created. Receives the annotation record.
+    # Use for email/Slack/webhook notifications.
+    # Default: nil (no callback)
+    attr_accessor :on_create_callback
+
+    # Enable element screenshot capture in the toolbar.
+    # Default: true
+    attr_accessor :enable_screenshots
+
+    # FAB button position: "bl" (bottom-left), "br" (bottom-right),
+    # "tl" (top-left), "tr" (top-right). Default: "bl"
+    attr_reader :toolbar_position
+
+    # FAB button size: "default" (48px), "compact" (40px), "slim" (32px).
+    # Default: "default"
+    attr_reader :toolbar_size
+
+    # Health check poll interval in seconds.
+    # Default: 60
+    attr_reader :health_interval
+
+    def initialize
+      @base_controller_class = "RailsMarkup::ApplicationController"
+      @api_token = nil
+      @table_name = "rails_markup_annotations"
+      @per_page = 25
+      @toolbar_accent = "indigo"
+      @toolbar_enabled = true
+      @fab_visible = true
+      @toolbar_position = "bl"
+      @toolbar_size = "default"
+      @return_url = nil
+      @dashboard_layout = "rails_markup/application"
+      @author_name_method = :email
+      @on_create_callback = nil
+      @enable_screenshots = true
+      @health_interval = 60
+    end
+
+    def resolve_author_name(user)
+      return nil unless user
+
+      case author_name_method
+      when Symbol then user.respond_to?(author_name_method) ? user.public_send(author_name_method) : nil
+      when Proc   then author_name_method.call(user)
+      end
+    rescue => e
+      Rails.logger.warn("[rails-markup] author_name_method error: #{e.message}") if defined?(Rails)
+      nil
+    end
+
+    def per_page=(value)
+      raise ArgumentError, "per_page must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+      @per_page = value
+    end
+
+    def toolbar_accent=(value)
+      unless ALLOWED_ACCENTS.include?(value.to_s)
+        raise ArgumentError, "toolbar_accent must be one of: #{ALLOWED_ACCENTS.join(', ')}"
+      end
+
+      @toolbar_accent = value.to_s
+    end
+
+    def toolbar_position=(value)
+      unless ALLOWED_POSITIONS.include?(value.to_s)
+        raise ArgumentError, "toolbar_position must be one of: #{ALLOWED_POSITIONS.join(', ')}"
+      end
+
+      @toolbar_position = value.to_s
+    end
+
+    def toolbar_size=(value)
+      unless ALLOWED_SIZES.include?(value.to_s)
+        raise ArgumentError, "toolbar_size must be one of: #{ALLOWED_SIZES.join(', ')}"
+      end
+
+      @toolbar_size = value.to_s
+    end
+
+    def health_interval=(value)
+      val = value.to_i
+      raise ArgumentError, "health_interval must be at least 10 (seconds)" unless val >= 10
+
+      @health_interval = val
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    alias_method :config, :configuration
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/rails_markup/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailsMarkup
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsMarkup
+
+    initializer "rails_markup.configuration" do
+      RailsMarkup.configuration # ensure defaults are set
+    end
+
+    initializer "rails_markup.assets" do |app|
+      if app.config.respond_to?(:assets)
+        # toolbar.js is inlined via the toolbar partial, no separate asset needed
+        app.config.assets.precompile += %w[rails_markup/toolbar.js]
+      end
+    end
+  end
+end

data/lib/rails_markup/http_server.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "webrick"
+require "json"
+
+module RailsMarkup
+  # HTTP server providing REST API + SSE for the browser-side annotation controller.
+  # Wire-compatible with Agentation's HTTP API.
+  class HttpServer
+    attr_reader :port, :store
+
+    def initialize(store:, port: 4747, logger: nil)
+      @store  = store
+      @port   = port
+      @logger = logger || WEBrick::Log.new($stderr, WEBrick::Log::WARN)
+    end
+
+    def start
+      @server = WEBrick::HTTPServer.new(
+        Port: @port,
+        Logger: @logger,
+        AccessLog: [],
+        DoNotReverseLookup: true
+      )
+
+      @server.mount("/", CorsServlet, @store)
+
+      trap("INT")  { @server.shutdown }
+      trap("TERM") { @server.shutdown }
+
+      @server.start
+    end
+
+    def shutdown
+      @server&.shutdown
+    end
+  end
+
+  # Single servlet handling all routes with proper CORS support.
+  # WEBrick dispatches do_GET, do_POST, do_OPTIONS to us directly.
+  class CorsServlet < WEBrick::HTTPServlet::AbstractServlet
+    def initialize(server, store)
+      super(server)
+      @store = store
+    end
+
+    def do_OPTIONS(req, res)
+      cors(res)
+      res.status = 204
+    end
+
+    def do_GET(req, res)
+      cors(res)
+      route(req, res)
+    end
+
+    def do_POST(req, res)
+      cors(res)
+      route(req, res)
+    end
+
+    private
+
+    def route(req, res)
+      case req.path
+      when "/health"
+        json_response(res, { ok: true })
+
+      when "/pending"
+        pending = @store.all_pending
+        json_response(res, pending.map { |a| @store.serialize_annotation(a) })
+
+      when "/sessions"
+        if req.request_method == "GET"
+          sessions = @store.list_sessions
+          json_response(res, sessions.map { |s| @store.serialize_session(s) })
+        else
+          handle_create_session(req, res)
+        end
+
+      when %r{\A/sessions/([^/]+)/annotations\z}
+        handle_create_annotation(req, res, $1)
+
+      when %r{\A/sessions/([^/]+)/events\z}
+        handle_sse(req, res, $1)
+
+      when %r{\A/sessions/([^/]+)\z}
+        handle_get_session(res, $1)
+
+      when %r{\A/annotations/([^/]+)/resolve\z}
+        handle_annotation_action(req, res, $1, :resolve)
+
+      when %r{\A/annotations/([^/]+)/dismiss\z}
+        handle_annotation_action(req, res, $1, :dismiss)
+
+      when %r{\A/annotations/([^/]+)/acknowledge\z}
+        handle_annotation_action(req, res, $1, :acknowledge)
+
+      when %r{\A/annotations/([^/]+)/reply\z}
+        handle_annotation_action(req, res, $1, :reply)
+
+      else
+        not_found(res)
+      end
+    end
+
+    # --- Annotation actions ---
+
+    def handle_annotation_action(req, res, annotation_id, action)
+      body = parse_json(req)
+      result = case action
+               when :resolve
+                 @store.resolve(annotation_id, summary: body["summary"])
+               when :dismiss
+                 @store.dismiss(annotation_id, reason: body["reason"])
+               when :acknowledge
+                 @store.acknowledge(annotation_id)
+               when :reply
+                 @store.reply(annotation_id, message: body["message"])
+               end
+      return not_found(res) unless result
+
+      json_response(res, @store.serialize_annotation(result))
+    end
+
+    # --- Sessions ---
+
+    def handle_create_session(req, res)
+      body = parse_json(req)
+      session = @store.create_session(url: body["url"], metadata: body["metadata"])
+      json_response(res, @store.serialize_session(session), status: 201)
+    end
+
+    def handle_get_session(res, session_id)
+      session = @store.get_session(session_id)
+      return not_found(res) unless session
+
+      json_response(res, @store.serialize_session(session))
+    end
+
+    # --- Annotations ---
+
+    def handle_create_annotation(req, res, session_id)
+      body = parse_json(req)
+      annotation = @store.create_annotation(
+        session_id: session_id,
+        target: body["target"],
+        content: body["content"],
+        intent: body["intent"] || "change",
+        severity: body["severity"] || "suggestion",
+        selected_text: body["selectedText"],
+        metadata: body["metadata"]
+      )
+      return not_found(res) unless annotation
+
+      json_response(res, @store.serialize_annotation(annotation), status: 201)
+    end
+
+    # --- SSE ---
+
+    def handle_sse(_req, res, session_id)
+      session = @store.get_session(session_id)
+      return not_found(res) unless session
+
+      res.status = 200
+      res["Content-Type"] = "text/event-stream"
+      res["Cache-Control"] = "no-cache"
+      res["Connection"] = "keep-alive"
+      res["Access-Control-Allow-Origin"] = "*"
+
+      res.chunked = true
+      res.body = proc do |out|
+        sub = @store.subscribe(session_id) do |data|
+          event_type = data[:type] || "annotation_update"
+          out.write("event: #{event_type}\ndata: #{data.to_json}\n\n")
+        rescue Errno::EPIPE, IOError
+          @store.unsubscribe(sub)
+        end
+
+        deadline = Time.now + 1800 # 30 minutes max
+        loop do
+          break if Time.now >= deadline
+
+          sleep 15
+          out.write(": keepalive\n\n")
+        rescue Errno::EPIPE, IOError
+          break
+        end
+      ensure
+        @store.unsubscribe(sub) if defined?(sub) && sub
+      end
+    end
+
+    # --- Helpers ---
+
+    def cors(res)
+      port = @server[:Port] rescue 4747
+      res["Access-Control-Allow-Origin"]  = "http://localhost:#{port}"
+      res["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
+      res["Access-Control-Allow-Headers"] = "Content-Type"
+    end
+
+    def json_response(res, data, status: 200)
+      res.status = status
+      res["Content-Type"] = "application/json"
+      res.body = data.to_json
+    end
+
+    def not_found(res)
+      res.status = 404
+      res["Content-Type"] = "application/json"
+      res.body = { error: "not_found" }.to_json
+    end
+
+    MAX_BODY_SIZE = 1_000_000 # 1MB
+
+    def parse_json(req)
+      return {} if req.body.nil?
+      return {} if req.body.bytesize > MAX_BODY_SIZE
+
+      JSON.parse(req.body)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/rails_markup/http_store_proxy.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module RailsMarkup
+  # Proxies store operations to an existing HTTP server.
+  # Used when MCP starts but the HTTP port is already taken —
+  # delegates reads/writes to the running server's HTTP API.
+  class HttpStoreProxy
+    def initialize(base_url: "http://localhost:4747")
+      @base_url = base_url
+      @uri = URI.parse(base_url)
+    end
+
+    def list_sessions
+      get("/sessions") || []
+    end
+
+    def get_session(id)
+      get("/sessions/#{id}")
+    end
+
+    def create_session(url:, metadata: nil)
+      post("/sessions", { url: url, metadata: metadata })
+    end
+
+    def all_pending
+      get("/pending") || []
+    end
+
+    def pending_for_session(session_id)
+      session = get_session(session_id)
+      return [] unless session
+
+      (session["annotations"] || []).select { |a| a["status"] == "pending" }
+    end
+
+    def get_annotation(id)
+      # Search all sessions for this annotation (not just pending)
+      list_sessions.each do |session|
+        (session["annotations"] || []).each do |ann|
+          return ann if ann["id"] == id
+        end
+      end
+      nil
+    end
+
+    def create_annotation(session_id:, target:, content:, intent: "change", severity: "suggestion", selected_text: nil, metadata: nil)
+      post("/sessions/#{session_id}/annotations", {
+        target: target, content: content, intent: intent,
+        severity: severity, selectedText: selected_text, metadata: metadata
+      })
+    end
+
+    def acknowledge(id)
+      post("/annotations/#{id}/acknowledge", {})
+    end
+
+    def resolve(id, summary: nil)
+      post("/annotations/#{id}/resolve", { summary: summary })
+    end
+
+    def dismiss(id, reason: nil)
+      post("/annotations/#{id}/dismiss", { reason: reason })
+    end
+
+    def reply(id, message:)
+      post("/annotations/#{id}/reply", { message: message })
+    end
+
+    # Proxy serialization — data is already serialized from HTTP
+    def serialize_session(data)
+      data
+    end
+
+    def serialize_annotation(data)
+      data
+    end
+
+    # Watch not supported via HTTP proxy — return empty after timeout
+    def subscribe(_session_id = nil, &_block)
+      nil
+    end
+
+    def unsubscribe(_sub)
+      nil
+    end
+
+    private
+
+    def get(path)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.open_timeout = 5
+      http.read_timeout = 10
+      req = Net::HTTP::Get.new(path)
+      resp = http.request(req)
+      return nil unless resp.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(resp.body)
+    rescue StandardError => e
+      $stderr.puts "[rails-markup proxy] GET #{path} failed: #{e.message}"
+      nil
+    end
+
+    def post(path, body)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.open_timeout = 5
+      http.read_timeout = 10
+      req = Net::HTTP::Post.new(path, "Content-Type" => "application/json")
+      req.body = body.to_json
+      resp = http.request(req)
+      return nil unless resp.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(resp.body)
+    rescue StandardError => e
+      $stderr.puts "[rails-markup proxy] POST #{path} failed: #{e.message}"
+      nil
+    end
+  end
+end