rails-markup 1.2.0

data/lib/rails_markup/server.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module RailsMarkup
+  # Main entry point — starts HTTP server and optionally MCP server.
+  # HTTP and MCP share the same Store instance so annotations flow both ways.
+  # If the HTTP port is already taken, MCP proxies to the existing server.
+  class Server
+    attr_reader :store
+
+    def initialize(port: 4747, mcp_only: false)
+      @port     = port
+      @mcp_only = mcp_only
+      @store    = Store.new
+    end
+
+    def start
+      if @mcp_only
+        start_mcp_only
+      else
+        start_http_and_mcp
+      end
+    end
+
+    private
+
+    def start_mcp(store)
+      mcp = McpServer.new(store: store)
+      mcp.start
+    end
+
+    # MCP-only mode: always proxy to the HTTP server.
+    # The user runs `rails-markup server` separately for HTTP.
+    def start_mcp_only
+      $stderr.puts "[rails-markup] MCP server listening on stdio (proxying to HTTP on port #{@port})"
+      proxy = HttpStoreProxy.new(base_url: "http://localhost:#{@port}")
+      start_mcp(proxy)
+    rescue IOError
+      # stdin closed — MCP client disconnected
+    end
+
+    def start_http_and_mcp
+      if port_available?(@port)
+        # We own the port — start HTTP + MCP with shared in-memory store
+        http_thread = Thread.new do
+          http = HttpServer.new(store: @store, port: @port)
+          $stderr.puts "[rails-markup] HTTP server listening on port #{@port}"
+          http.start
+        end
+
+        $stderr.puts "[rails-markup] MCP server listening on stdio"
+        start_mcp(@store)
+      else
+        # Port is taken — proxy MCP reads/writes to the existing HTTP server
+        $stderr.puts "[rails-markup] Port #{@port} in use — MCP proxying to existing server"
+        $stderr.puts "[rails-markup] MCP server listening on stdio"
+        proxy = HttpStoreProxy.new(base_url: "http://localhost:#{@port}")
+        start_mcp(proxy)
+      end
+    rescue IOError
+      # stdin closed — MCP client disconnected
+    end
+
+    def port_available?(port)
+      server = TCPServer.new("0.0.0.0", port)
+      server.close
+      true
+    rescue Errno::EADDRINUSE
+      false
+    end
+  end
+end

data/lib/rails_markup/store.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module RailsMarkup
+  # In-memory store for sessions and annotations.
+  # Ephemeral by design — data lives for one coding session.
+  class Store
+    Session    = Struct.new(:id, :url, :metadata, :created_at, :annotations, keyword_init: true)
+    Annotation = Struct.new(:id, :session_id, :target, :content, :intent, :severity, :status,
+                            :selected_text, :metadata, :created_at, :thread, keyword_init: true)
+
+    MAX_SESSIONS = 100
+    SESSION_TTL  = 4 * 3600 # 4 hours
+
+    attr_reader :sessions
+
+    def initialize
+      @sessions          = {}
+      @annotations_index = {} # id -> annotation (O(1) lookup)
+      @subscribers       = [] # SSE callbacks: [session_id, callback]
+      @mutex             = Mutex.new
+    end
+
+    # --- Sessions ---
+
+    def create_session(url:, metadata: {})
+      id = SecureRandom.hex(8)
+      session = Session.new(
+        id: id,
+        url: url,
+        metadata: metadata || {},
+        created_at: Time.now.iso8601,
+        annotations: []
+      )
+      @mutex.synchronize do
+        evict_stale_sessions
+        @sessions[id] = session
+      end
+      session
+    end
+
+    def get_session(id)
+      @mutex.synchronize { @sessions[id] }
+    end
+
+    def list_sessions
+      @mutex.synchronize { @sessions.values }
+    end
+
+    # --- Annotations ---
+
+    def create_annotation(session_id:, target:, content:, intent: "change", severity: "suggestion",
+                          selected_text: nil, metadata: {})
+      id = SecureRandom.hex(8)
+      annotation = Annotation.new(
+        id: id,
+        session_id: session_id,
+        target: target,
+        content: content,
+        intent: intent,
+        severity: severity,
+        status: "pending",
+        selected_text: selected_text,
+        metadata: metadata || {},
+        created_at: Time.now.iso8601,
+        thread: []
+      )
+
+      # Single mutex block — no TOCTOU gap
+      @mutex.synchronize do
+        session = @sessions[session_id]
+        return nil unless session
+
+        session.annotations << annotation
+        @annotations_index[id] = annotation
+      end
+
+      notify(session_id, type: "annotation_created", annotation: serialize_annotation(annotation))
+      annotation
+    end
+
+    def get_annotation(annotation_id)
+      @mutex.synchronize { @annotations_index[annotation_id] }
+    end
+
+    def pending_for_session(session_id)
+      session = get_session(session_id)
+      return [] unless session
+
+      @mutex.synchronize { session.annotations.select { |a| a.status == "pending" } }
+    end
+
+    def all_pending
+      @mutex.synchronize do
+        @sessions.values.flat_map { |s| s.annotations.select { |a| a.status == "pending" } }
+      end
+    end
+
+    # --- Status transitions ---
+
+    def acknowledge(annotation_id)
+      update_status(annotation_id, "acknowledged")
+    end
+
+    def resolve(annotation_id, summary: nil)
+      ann = update_status(annotation_id, "resolved")
+      return nil unless ann
+
+      ann.thread << { role: "agent", message: summary, timestamp: Time.now.iso8601 } if summary
+      notify(ann.session_id, type: "annotation_update", annotation: serialize_annotation(ann),
+                             status: "resolved", summary: summary)
+      ann
+    end
+
+    def dismiss(annotation_id, reason: nil)
+      ann = update_status(annotation_id, "dismissed")
+      return nil unless ann
+
+      ann.thread << { role: "agent", message: reason, timestamp: Time.now.iso8601 } if reason
+      notify(ann.session_id, type: "annotation_update", annotation: serialize_annotation(ann),
+                             status: "dismissed", reason: reason)
+      ann
+    end
+
+    def reply(annotation_id, message:)
+      ann = get_annotation(annotation_id)
+      return nil unless ann
+
+      @mutex.synchronize do
+        ann.thread << { role: "agent", message: message, timestamp: Time.now.iso8601 }
+      end
+      notify(ann.session_id, type: "annotation_update", annotation: serialize_annotation(ann),
+                             status: ann.status, message: message)
+      ann
+    end
+
+    # --- SSE subscriptions ---
+
+    def subscribe(session_id, &callback)
+      sub = [session_id, callback]
+      @mutex.synchronize { @subscribers << sub }
+      sub
+    end
+
+    def unsubscribe(sub)
+      @mutex.synchronize { @subscribers.delete(sub) }
+    end
+
+    # --- Serialization ---
+
+    def serialize_session(session)
+      {
+        id: session.id,
+        url: session.url,
+        metadata: session.metadata,
+        createdAt: session.created_at,
+        annotations: session.annotations.map { |a| serialize_annotation(a) }
+      }
+    end
+
+    def serialize_annotation(ann)
+      {
+        id: ann.id,
+        sessionId: ann.session_id,
+        target: ann.target,
+        content: ann.content,
+        intent: ann.intent,
+        severity: ann.severity,
+        status: ann.status,
+        selectedText: ann.selected_text,
+        authorName: ann.metadata&.dig("author"),
+        metadata: ann.metadata,
+        createdAt: ann.created_at,
+        thread: ann.thread
+      }
+    end
+
+    private
+
+    def update_status(annotation_id, new_status)
+      ann = get_annotation(annotation_id)
+      return nil unless ann
+
+      @mutex.synchronize { ann.status = new_status }
+      ann
+    end
+
+    def notify(session_id, data)
+      dead = []
+      @mutex.synchronize do
+        @subscribers.each do |sub|
+          sid, callback = sub
+          next unless sid.nil? || sid == session_id
+
+          callback.call(data)
+        rescue StandardError
+          dead << sub
+        end
+        dead.each { |s| @subscribers.delete(s) }
+      end
+    end
+
+    def evict_stale_sessions
+      return if @sessions.size < MAX_SESSIONS
+
+      cutoff = (Time.now - SESSION_TTL).iso8601
+      @sessions.delete_if do |_id, session|
+        if session.created_at < cutoff
+          session.annotations.each { |a| @annotations_index.delete(a.id) }
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/rails_markup/version.rb

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

data/lib/rails_markup.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "rails_markup/version"
+require_relative "rails_markup/configuration"
+require_relative "rails_markup/store"
+require_relative "rails_markup/http_store_proxy"
+require_relative "rails_markup/http_server"
+require_relative "rails_markup/mcp_server"
+require_relative "rails_markup/server"
+
+require_relative "rails_markup/engine" if defined?(Rails::Engine)

data/lib/tasks/rails_markup_client_uuids.rake

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails_markup/client_uuid_maintenance"
+
+namespace :rails_markup do
+  namespace :client_uuids do
+    desc "Repair blank or noncanonical Rails Markup client UUIDs (safe to repeat)"
+    task repair: :environment do
+      repaired = RailsMarkup::ClientUuidMaintenance.repair!
+      puts "Repaired #{repaired} Rails Markup client UUID(s)."
+    end
+
+    desc "Fail unless every Rails Markup annotation has a canonical client UUID"
+    task verify: :environment do
+      RailsMarkup::ClientUuidMaintenance.verify!
+      puts "All Rails Markup client UUIDs are canonical."
+    end
+  end
+end

metadata

@@ -0,0 +1,198 @@
+--- !ruby/object:Gem::Specification
+name: rails-markup
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- InventList
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: bubbletea
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: lipgloss
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: An MCP server that lets you annotate Rails views in the browser and have
+  AI agents read and act on your feedback.
+email:
+- hello@inventlist.com
+executables:
+- rails-markup
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/assets/javascripts/rails_markup/toolbar.js
+- app/controllers/rails_markup/annotations_controller.rb
+- app/controllers/rails_markup/application_controller.rb
+- app/controllers/rails_markup/dashboard_controller.rb
+- app/controllers/rails_markup/external/annotations_controller.rb
+- app/models/rails_markup/annotation.rb
+- app/views/layouts/rails_markup/application.html.erb
+- app/views/rails_markup/dashboard/_annotation_card.html.erb
+- app/views/rails_markup/dashboard/_annotation_list.html.erb
+- app/views/rails_markup/dashboard/_annotation_page.html.erb
+- app/views/rails_markup/dashboard/_filters.html.erb
+- app/views/rails_markup/dashboard/_stats.html.erb
+- app/views/rails_markup/dashboard/_styles.html.erb
+- app/views/rails_markup/dashboard/board.html.erb
+- app/views/rails_markup/dashboard/index.html.erb
+- app/views/rails_markup/dashboard/show.html.erb
+- app/views/rails_markup/shared/_toolbar.html.erb
+- bin/rails-markup
+- config/routes.rb
+- db/migrate/20260720000000_add_client_uuid_to_rails_markup_annotations.rb
+- db/migrate/20260721000000_backfill_rails_markup_client_uuids.rb
+- lib/generators/rails_markup/install/templates/auth_controller.rb.erb
+- lib/generators/rails_markup/install/templates/bin_markup.erb
+- lib/generators/rails_markup/install/templates/create_rails_markup_annotations.rb.erb
+- lib/generators/rails_markup/install/templates/initializer.rb.erb
+- lib/generators/rails_markup/install_generator.rb
+- lib/generators/rails_markup/uninstall_generator.rb
+- lib/rails_markup.rb
+- lib/rails_markup/cli.rb
+- lib/rails_markup/cli/base.rb
+- lib/rails_markup/cli/initializer_writer.rb
+- lib/rails_markup/cli/setup_wizard.rb
+- lib/rails_markup/client_uuid_maintenance.rb
+- lib/rails_markup/configuration.rb
+- lib/rails_markup/engine.rb
+- lib/rails_markup/http_server.rb
+- lib/rails_markup/http_store_proxy.rb
+- lib/rails_markup/mcp_config.rb
+- lib/rails_markup/mcp_server.rb
+- lib/rails_markup/server.rb
+- lib/rails_markup/store.rb
+- lib/rails_markup/version.rb
+- lib/tasks/rails_markup_client_uuids.rake
+homepage: https://github.com/inventlist/rails-markup
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/inventlist/rails-markup
+  source_code_uri: https://github.com/inventlist/rails-markup
+  changelog_uri: https://github.com/inventlist/rails-markup/blob/main/CHANGELOG.md
+post_install_message: |
+  Rails Markup installed! Run the generator to set up:
+
+    rails generate rails_markup:install
+    rails db:migrate
+
+  Options:
+    --mount-path=/admin/annotations  (engine route)
+    --base-controller=AdminController (auth parent class)
+    --layout=application             (toolbar injection)
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Point-and-click annotation tool for AI agents
+test_files: []