rails-markup 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d852927076b8b5e1774675692c45b575eb9dd6337c934637e90c693310d96f4d
-  data.tar.gz: 3608bdd64056b7cb3373de2cd4ea0797a1e6dc3e021457ec96697a4d3f8c7919
+  metadata.gz: c2efa8f1fca5e20c13c63a7157b47553cb893df6384bb0799b57b1dd9caa2bb6
+  data.tar.gz: 5b244141b9d9bab054f7baa2f15dd3af9560e0ee3aaefcaeaef81c5e4e3541bd
 SHA512:
-  metadata.gz: ac1ee4649e024d9a3fa306bf3fefb9f6443c2d89cec4d33de6b504831123228f1db3cc2e20414914fdec41150e832ea077d76cfe1c606859c2177626eb643251
-  data.tar.gz: e8942c6bcbff10487ab62170039b6c62c0c0ffe87a59cb77ac8df87792c6365109d222451fc8756831fad1284b1336f7d0adff3dbf3698b257e2c0e2b1346899
+  metadata.gz: d6b1da9212c6140e1db0767b6a27b972497063657a8b5f23d28e1ba84d21d1ed606473182516730708bd7f29447df448baf967f34cf291de40374b724b984cd4
+  data.tar.gz: 73f188f0de27d3fc628bc31388daa1a6e0048a124c3d1a0dfb91dcf9be0b048470179c4b47be58b403c2850653064d005fde99f10738bb394433c4cd17ba0cbd

data/app/assets/javascripts/rails_markup/toolbar.js

@@ -714,6 +714,7 @@
         id: this.nextId,
         clientId: this._newClientId(),
         serverId: null,
+        serverRevision: 0,
         syncState: "pending",
         serverUpdatedAt: null,
         dirtyFields: [],
@@ -1077,12 +1078,16 @@
     _queueLocalMutation(type, annotation, dirtyFields) {
       const currentEntry = this.outbox[annotation.clientId];
       const revision = Math.max(annotation.revision || 0, currentEntry?.revision || 0) + 1;
+      const baseRevision = Number.isInteger(currentEntry?.baseRevision)
+        ? currentEntry.baseRevision
+        : (Number.isInteger(annotation.serverRevision) ? annotation.serverRevision : 0);
 
       if (type === "delete") {
         this.outbox[annotation.clientId] = {
           type: "delete",
           clientId: annotation.clientId,
           revision,
+          baseRevision,
           syncState: "pending"
         };
       } else {
@@ -1094,6 +1099,7 @@
           type: "upsert",
           clientId: annotation.clientId,
           revision,
+          baseRevision,
           syncState: "pending",
           annotation: this._desiredState(annotation),
           dirtyFields: annotation.dirtyFields.slice()
@@ -1208,6 +1214,15 @@
           this._markSyncFailed(snapshot);
           continue;
         }
+        if (result.kind === "conflict") {
+          const pulled = await this._pullAnnotations();
+          if (pulled && this.outbox[clientId]) {
+            clientIds.push(clientId);
+            continue;
+          }
+          this._scheduleSyncRetry();
+          break;
+        }
         if (result.kind === "malformed") {
           if (!this._outboxEntryMatches(snapshot)) {
             clientIds.push(clientId);
@@ -1236,7 +1251,10 @@
         signal: AbortSignal.timeout(5000)
       };
       if (snapshot.type === "upsert") {
-        options.body = JSON.stringify(Object.assign({}, snapshot.annotation, { dirtyFields: snapshot.dirtyFields || [] }));
+        options.body = JSON.stringify(Object.assign({}, snapshot.annotation, {
+          dirtyFields: snapshot.dirtyFields || [],
+          baseRevision: Number.isInteger(snapshot.baseRevision) ? snapshot.baseRevision : 0
+        }));
       }
 
       const response = await fetch(request.url, options);
@@ -1274,6 +1292,7 @@
       if ([408, 425, 429].includes(status) || status >= 500) {
         return { kind: "retryable", retryAfter: this._retryAfterDelay(response) };
       }
+      if (status === 409 && snapshot.type === "upsert") return { kind: "conflict" };
       if (status >= 400) return { kind: "terminal" };
       if (!response.ok) return { kind: "retryable" };
       if (snapshot.type === "delete") return { kind: "success", data: null };
@@ -1297,7 +1316,7 @@
       const required = [
         "id", "clientId", "userId", "authorName", "content", "intent", "severity",
         "status", "selectedText", "pageUrl", "target", "metadata", "thread",
-        "createdAt", "updatedAt"
+        "createdAt", "updatedAt", "revision"
       ];
       if (!required.every(key => Object.prototype.hasOwnProperty.call(data, key))) return false;
       if (typeof data.id !== "string" || data.id.length === 0) return false;
@@ -1313,6 +1332,7 @@
       if (!this._plainObject(data.target) || !this._plainObject(data.metadata)) return false;
       if (!Array.isArray(data.thread)) return false;
       if (!this._validServerTimestamp(data.createdAt) || !this._validServerTimestamp(data.updatedAt)) return false;
+      if (!Number.isInteger(data.revision) || data.revision < 0) return false;
       return true;
     },
 
@@ -1346,6 +1366,7 @@
         return;
       }
       annotation.serverId = server.id;
+      annotation.serverRevision = server.revision;
       annotation.userId = server.userId;
       annotation.authorName = server.authorName;
       annotation.createdAt = server.createdAt;
@@ -1447,8 +1468,6 @@
 
     _loadFromStorage() {
       try {
-        // Old unnamespaced keys are intentionally not read because they may belong
-        // to another user or toolbar mount on the same origin.
         let raw = localStorage.getItem(this._storageKey());
         if (raw) {
           const data = JSON.parse(raw);
@@ -1460,8 +1479,11 @@
             ? data.legacyMigrations
             : {};
         }
-        // Migrate any old per-page annotations into global store
-        const migratedKeys = this._migratePageAnnotations();
+        // Pre-1.3 storage had no endpoint identity. The first configured endpoint
+        // to load on this origin claims it once; successful consolidation removes
+        // the source keys so another endpoint cannot import the same data later.
+        const migratedKeys = this._migrateUnnamespacedStorage();
+        migratedKeys.push(...this._migratePageAnnotations());
         this._normalizeStoredState();
         this._recordLegacyMigrations();
         if (this._saveToStorage()) this._cleanupMigratedKeys(migratedKeys);
@@ -1470,6 +1492,54 @@
       } catch (e) { console.warn("[rails-markup] load failed:", e); }
     },
 
+    _migrateUnnamespacedStorage() {
+      const sourceKeys = [];
+      for (let index = 0; index < localStorage.length; index++) {
+        const key = localStorage.key(index);
+        if (key === "rm-annotations" || (key && key.startsWith("rm-annotations:/"))) sourceKeys.push(key);
+      }
+
+      const migratedKeys = [];
+      const legacyAnnotations = [];
+      const legacyOutbox = {};
+      const consolidatedClientIds = new Set(
+        this.annotations.map(annotation => annotation.clientId).filter(clientId => this._validClientId(clientId))
+      );
+      sourceKeys.forEach(key => {
+        try {
+          const data = JSON.parse(localStorage.getItem(key));
+          if (!this._plainObject(data)) return;
+          const hasAnnotations = Array.isArray(data.annotations);
+          const hasOutbox = key === "rm-annotations" && this._plainObject(data.outbox);
+          if (!hasAnnotations && !hasOutbox) return;
+
+          if (hasAnnotations) {
+            data.annotations.forEach((annotation, index) => {
+              if (!this._plainObject(annotation)) return;
+              const fingerprint = this._legacyMigrationFingerprint(key, index, annotation);
+              const migratedClientId = this.legacyMigrations[fingerprint];
+              if (this._validClientId(migratedClientId) && consolidatedClientIds.has(migratedClientId)) return;
+              if (this._validClientId(migratedClientId)) annotation.clientId = migratedClientId;
+              if (this._validClientId(annotation.clientId) && consolidatedClientIds.has(annotation.clientId)) return;
+              Object.defineProperty(annotation, "_legacyMigrationFingerprint", {
+                configurable: true,
+                value: fingerprint
+              });
+              legacyAnnotations.push(annotation);
+              if (this._validClientId(annotation.clientId)) consolidatedClientIds.add(annotation.clientId);
+            });
+          }
+          if (hasOutbox) Object.assign(legacyOutbox, data.outbox);
+          if (Number.isInteger(data.nextId) && data.nextId > this.nextId) this.nextId = data.nextId;
+          migratedKeys.push(key);
+        } catch {}
+      });
+
+      this.annotations = legacyAnnotations.concat(this.annotations);
+      this.outbox = Object.assign({}, legacyOutbox, this.outbox);
+      return migratedKeys;
+    },
+
     _migratePageAnnotations() {
       // Find and merge per-page annotation keys only within this endpoint namespace.
       const prefix = this._storageKey() + ":";
@@ -1542,6 +1612,11 @@
         }
         if (annotation.serverId == null) annotation.serverId = annotation.server_id ?? null;
         if (annotation.serverUpdatedAt == null) annotation.serverUpdatedAt = annotation.server_updated_at ?? null;
+        if (!Number.isInteger(annotation.serverRevision) || annotation.serverRevision < 0) {
+          annotation.serverRevision = Number.isInteger(annotation.server_revision) && annotation.server_revision >= 0
+            ? annotation.server_revision
+            : 0;
+        }
         if (!Array.isArray(annotation.dirtyFields)) annotation.dirtyFields = [];
         annotation.pageUrl = annotation.pageUrl || annotation.pathname || this._pageUrl();
         annotation.pathname = annotation.pageUrl;
@@ -1576,6 +1651,7 @@
             type: "upsert",
             clientId: annotation.clientId,
             revision: annotation.revision,
+            baseRevision: annotation.serverRevision,
             syncState: "pending",
             annotation: this._desiredState(annotation),
             dirtyFields: annotation.dirtyFields.slice()
@@ -1606,10 +1682,17 @@
         const annotation = this.annotations.find(record => record.clientId === clientId);
         const candidateRevision = Number.isInteger(candidate.revision) && candidate.revision >= 0 ? candidate.revision : 0;
         const annotationRevision = Number.isInteger(annotation?.revision) && annotation.revision >= 0 ? annotation.revision : 0;
+        const candidateBaseRevision = Number.isInteger(candidate.baseRevision) && candidate.baseRevision >= 0
+          ? candidate.baseRevision
+          : 0;
+        const annotationBaseRevision = Number.isInteger(annotation?.serverRevision) && annotation.serverRevision >= 0
+          ? annotation.serverRevision
+          : 0;
         const envelope = Object.assign({}, candidate, {
           type,
           clientId,
           revision: Math.max(candidateRevision, annotationRevision),
+          baseRevision: Math.max(candidateBaseRevision, annotationBaseRevision),
           syncState: candidate.syncState === "failed" ? "failed" : "pending"
         });
 
@@ -1823,6 +1906,7 @@
           if (!annotation) return;
           entry.annotation = this._desiredState(annotation);
           entry.dirtyFields = (annotation.dirtyFields || []).slice();
+          entry.baseRevision = Number.isInteger(annotation.serverRevision) ? annotation.serverRevision : 0;
         });
       });
       if (!committed) return false;
@@ -1856,6 +1940,7 @@
         annotation.pathname = server.pageUrl;
       }
       annotation.serverId = server.id;
+      annotation.serverRevision = server.revision;
       annotation.userId = server.userId;
       annotation.authorName = server.authorName;
       annotation.createdAt = server.createdAt;
@@ -1871,6 +1956,7 @@
         id: null,
         clientId: server.clientId,
         serverId: server.id,
+        serverRevision: server.revision,
         userId: server.userId,
         authorName: server.authorName,
         syncState: "synced",
@@ -1893,6 +1979,9 @@
     },
 
     _serverRepresentationIsStale(annotation, server) {
+      if (Number.isInteger(annotation.serverRevision) && Number.isInteger(server.revision)) {
+        return server.revision < annotation.serverRevision;
+      }
       const localTimestamp = Date.parse(annotation.serverUpdatedAt || "");
       const serverTimestamp = Date.parse(server.updatedAt || "");
       return Number.isFinite(localTimestamp) && Number.isFinite(serverTimestamp) && serverTimestamp < localTimestamp;

data/app/controllers/rails_markup/annotations_controller.rb

@@ -59,23 +59,29 @@ module RailsMarkup
 
       dirty_fields = normalized_dirty_fields
       return render_invalid_dirty_fields unless dirty_fields
+      base_revision = normalized_base_revision
+      return render_invalid_base_revision unless base_revision
 
       attributes = browser_attributes
       return render_invalid_status if dirty_fields.include?("status") && !Annotation::STATUSES.include?(attributes["status"])
 
       annotation = Annotation.find_or_initialize_by(client_uuid: client_uuid)
       created = annotation.new_record?
-      apply_desired_state(annotation, attributes, dirty_fields)
-      annotation.save!
+      save_browser_state!(annotation, attributes, dirty_fields, base_revision)
       fire_create_callback(annotation) if created
       render json: annotation.as_api_json
+    rescue Annotation::RevisionConflict => error
+      render_revision_conflict(error)
     rescue ActiveRecord::RecordInvalid => error
       render json: { errors: error.record.errors.full_messages }, status: :unprocessable_entity
     rescue ActiveRecord::RecordNotUnique
       annotation = Annotation.find_by!(client_uuid: client_uuid)
-      apply_desired_state(annotation, attributes, dirty_fields)
-      annotation.save!
-      render json: annotation.as_api_json
+      begin
+        save_browser_state!(annotation, attributes, dirty_fields, base_revision)
+        render json: annotation.as_api_json
+      rescue Annotation::RevisionConflict => error
+        render_revision_conflict(error)
+      end
     end
 
     # DELETE /feedback/api/annotations/:client_uuid
@@ -183,9 +189,25 @@ module RailsMarkup
       permitted.to_h.stringify_keys
     end
 
-    def apply_desired_state(annotation, attributes, dirty_fields)
-      assign_current_user(annotation) if annotation.new_record?
-      annotation.apply_browser_state(attributes, dirty_fields: dirty_fields)
+    def save_browser_state!(annotation, attributes, dirty_fields, base_revision)
+      if annotation.new_record?
+        assign_current_user(annotation)
+        annotation.apply_browser_state(
+          attributes,
+          dirty_fields: dirty_fields,
+          base_revision: base_revision
+        )
+        annotation.save!
+      else
+        annotation.with_lock do
+          annotation.apply_browser_state(
+            attributes,
+            dirty_fields: dirty_fields,
+            base_revision: base_revision
+          )
+          annotation.save!
+        end
+      end
     end
 
     def normalized_route_uuid
@@ -201,6 +223,11 @@ module RailsMarkup
       fields if (fields - ALLOWED_DIRTY_FIELDS).empty?
     end
 
+    def normalized_base_revision
+      revision = params[:baseRevision]
+      revision if revision.is_a?(Integer) && revision >= 0
+    end
+
     def client_supplied_author?
       metadata = params[:metadata]
       metadata.respond_to?(:key?) && (metadata.key?(:author) || metadata.key?("author"))
@@ -226,6 +253,17 @@ module RailsMarkup
       render json: { error: "invalid status" }, status: :unprocessable_entity
     end
 
+    def render_invalid_base_revision
+      render json: { error: "base revision must be a non-negative integer" }, status: :unprocessable_entity
+    end
+
+    def render_revision_conflict(error)
+      render json: {
+        error: "revision conflict",
+        annotation: error.annotation.as_api_json
+      }, status: :conflict
+    end
+
     def normalize_target(target)
       case target
       when String then { "selector" => target }

data/app/controllers/rails_markup/external/annotations_controller.rb

@@ -61,7 +61,10 @@ module RailsMarkup
         return if Rails.env.development? && !RailsMarkup.config.require_api_token_in_development
 
         token = RailsMarkup.config.api_token
-        return head(:not_found) if token.nil?
+        # Treat a nil OR blank token as "external API disabled" — otherwise a
+        # token of "" would make secure_compare("", "") true and authenticate
+        # every request (including ones with no Authorization header).
+        return head(:not_found) if token.nil? || token.to_s.strip.empty?
 
         provided = request.headers["Authorization"]&.delete_prefix("Bearer ")
         head(:unauthorized) unless ActiveSupport::SecurityUtils.secure_compare(provided.to_s, token)

data/app/models/rails_markup/annotation.rb

@@ -5,6 +5,15 @@ require "digest/sha1"
 
 module RailsMarkup
   class Annotation < ActiveRecord::Base
+    class RevisionConflict < StandardError
+      attr_reader :annotation
+
+      def initialize(annotation)
+        @annotation = annotation
+        super("annotation revision conflict")
+      end
+    end
+
     self.table_name = RailsMarkup.config.table_name
 
     INTENTS = %w[fix change question approve].freeze
@@ -99,18 +108,33 @@ module RailsMarkup
       metadata&.dig("author")
     end
 
-    def apply_browser_state(attributes, dirty_fields: [])
-      assign_attributes(attributes.slice(*BROWSER_ATTRIBUTES))
-      self.metadata = (metadata || {}).merge(attributes.fetch("metadata", {}).slice(*BROWSER_METADATA_KEYS))
-      self.status = attributes["status"] if dirty_fields.include?("status")
+    def apply_browser_state(attributes, dirty_fields:, base_revision:)
+      raise RevisionConflict, self unless base_revision == revision
+
+      dirty_fields.each do |field|
+        if BROWSER_ATTRIBUTES.include?(field)
+          public_send("#{field}=", attributes[field]) if attributes.key?(field)
+        elsif field == "metadata" && attributes.key?("metadata")
+          self.metadata = (metadata || {}).merge(attributes["metadata"].slice(*BROWSER_METADATA_KEYS))
+        elsif field == "status" && attributes.key?("status")
+          self.status = attributes["status"]
+        end
+      end
+      self.revision += 1 if changed?
       self
     end
 
     def acknowledge!
-      return self if status == "acknowledged" # idempotent — re-acknowledging is a no-op
-      raise "Cannot acknowledge a #{status} annotation" unless status == "pending"
+      # Lock + reload so a concurrent resolve!/dismiss! can't be clobbered:
+      # without it, an acknowledge validated against a stale "pending" could
+      # write "acknowledged" over an already-resolved record.
+      with_lock do
+        return self if status == "acknowledged" # idempotent — re-acknowledging is a no-op
+        raise "Cannot acknowledge a #{status} annotation" unless status == "pending"
 
-      update!(status: "acknowledged")
+        update!(status: "acknowledged", revision: revision + 1)
+      end
+      self
     end
 
     def resolve!(summary: nil)
@@ -121,7 +145,7 @@ module RailsMarkup
         raise "Cannot resolve a #{status} annotation" unless status.in?(%w[pending acknowledged])
 
         add_thread_entry(role: "agent", message: summary) if summary.present?
-        update!(status: "resolved")
+        update!(status: "resolved", revision: revision + 1)
       end
       self
     end
@@ -132,7 +156,7 @@ module RailsMarkup
         raise "Cannot dismiss a #{status} annotation" unless status.in?(%w[pending acknowledged])
 
         add_thread_entry(role: "agent", message: reason) if reason.present?
-        update!(status: "dismissed")
+        update!(status: "dismissed", revision: revision + 1)
       end
       self
     end
@@ -140,6 +164,7 @@ module RailsMarkup
     def add_reply!(message:, role: "agent")
       with_lock do
         add_thread_entry(role: role, message: message)
+        self.revision += 1
         save!
       end
       self
@@ -161,7 +186,8 @@ module RailsMarkup
         metadata: metadata,
         thread: thread,
         createdAt: created_at&.iso8601,
-        updatedAt: updated_at&.iso8601
+        updatedAt: updated_at&.iso8601,
+        revision: revision
       }
     end
 

data/app/views/rails_markup/shared/_toolbar.html.erb

@@ -25,6 +25,14 @@
     };
     // Init immediately (DOM is ready — script is at end of body)
     RailsMarkupToolbar.init(opts);
+    // Tear down before Turbo snapshots the page for its cache — otherwise the
+    // cached DOM keeps a toolbar root with no live listeners, and on restore
+    // init() would early-return on that dead root instead of rebinding.
+    document.addEventListener("turbo:before-cache", function() {
+      if (window.RailsMarkupToolbar && typeof RailsMarkupToolbar.destroy === "function") {
+        RailsMarkupToolbar.destroy();
+      }
+    });
     // After Turbo Drive navigations (DOMContentLoaded won't fire again), only
     // re-init when the new page is still authorized (gate sentinel present);
     // otherwise tear the toolbar down so it can't persist past a logout.

data/db/migrate/20260726000000_add_revision_to_rails_markup_annotations.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddRevisionToRailsMarkupAnnotations < ActiveRecord::Migration[7.0]
+  def change
+    table = RailsMarkup.config.table_name
+    return unless table_exists?(table)
+    return if column_exists?(table, :revision)
+
+    add_column table, :revision, :integer, null: false, default: 0
+  end
+end

data/lib/generators/rails_markup/install/templates/create_rails_markup_annotations.rb.erb

@@ -18,6 +18,7 @@ class CreateRailsMarkupAnnotations < ActiveRecord::Migration<%= migration_versio
       t.send json_type, :metadata, default: {}
       t.send json_type, :thread, default: []
       t.string :client_uuid, limit: 64, null: false
+      t.integer :revision, null: false, default: 0
 
       t.timestamps
     end
@@ -28,6 +29,10 @@ class CreateRailsMarkupAnnotations < ActiveRecord::Migration<%= migration_versio
     if connection.adapter_name.downcase.include?("mysql")
       add_index :<%= options[:table_name] %>, :page_url, length: 191
     else
+      # PostgreSQL indexes the full column so `where(page_url:)` lookups stay
+      # fast. A btree entry tops out near 2704 bytes, so a pathological
+      # multibyte URL approaching the 2048-char cap could exceed it; real URLs
+      # are far shorter. Switch to an expression index if that ever bites you.
       add_index :<%= options[:table_name] %>, :page_url
     end
     add_index :<%= options[:table_name] %>, :user_id

data/lib/generators/rails_markup/install_generator.rb

@@ -21,6 +21,20 @@ module RailsMarkup
       class_option :table_name, type: :string, default: "rails_markup_annotations",
         desc: "Database table name for annotations (must match config.table_name)"
 
+      # Conservative SQL identifier: leading letter/underscore, then letters,
+      # digits, underscores. Blocks names that would produce invalid Ruby/SQL or
+      # inject into the migration/initializer templates (e.g. "feedback-items",
+      # quotes, newlines).
+      TABLE_NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+      def validate_table_name
+        return if options[:table_name].match?(TABLE_NAME_PATTERN)
+
+        raise Thor::Error,
+          "Invalid --table-name #{options[:table_name].inspect}: use only letters, " \
+          "digits, and underscores, starting with a letter or underscore."
+      end
+
       def copy_migration
         migration_template "create_rails_markup_annotations.rb.erb",
           "db/migrate/create_rails_markup_annotations.rb"
@@ -76,7 +90,10 @@ module RailsMarkup
           # Upgrade the pre-1.2.3 partial-existence gate, which rendered the
           # toolbar for every visitor, to the admin-gated block. Leave any
           # custom (hand-edited) block untouched so we don't clobber it.
-          legacy = /^[ \t]*<%#\s*Rails Markup annotation toolbar\s*%>\r?\n[ \t]*<%\s*if\s+lookup_context\.exists\?.*?<%\s*end\s*%>\r?\n?/m
+          # Match the exact historical generated block (allowing ERB trim tags)
+          # — including its own render line — so we never swallow a hand-written
+          # block that merely happens to contain lookup_context…end.
+          legacy = /^[ \t]*<%#\s*Rails Markup annotation toolbar\s*%>\r?\n[ \t]*<%-?\s*if\s+lookup_context\.exists\?\("rails_markup\/shared\/toolbar".*?-?%>\r?\n[ \t]*<%=\s*render\s+"rails_markup\/shared\/toolbar"\s*-?%>\r?\n[ \t]*<%-?\s*end\s*-?%>\r?\n?/m
           if content =~ legacy
             gsub_file layout_path, legacy, toolbar_block
             say_status :update, "upgraded toolbar to admin-gated render in #{layout_path}", :green

data/lib/rails_markup/cli.rb

@@ -643,29 +643,30 @@ module RailsMarkup
       "local"
     end
 
-    # Merge configs per-key with local taking precedence over global over codex.
-    # Merging (rather than returning the first non-empty config) means a local
-    # config that only defines dev values doesn't shadow production credentials
-    # stored globally or in the codex config.
-    def resolve_mcp_env
-      merged = {}
-      # Reverse so the highest-precedence scope (local) is applied last and wins.
-      McpConfig::SCOPES.reverse_each do |scope|
+    # Return the raw env of the highest-precedence scope (local → global → codex)
+    # that defines any of the given keys. URL, token, and mount are always read
+    # from this single scope so a token is never paired with a URL from another
+    # scope (credential provenance). A local config that only defines dev values
+    # is skipped for production lookups, so it neither shadows nor captures the
+    # production credentials stored globally/in codex.
+    def scoped_env(*keys)
+      McpConfig::SCOPES.each do |scope|
         config = McpConfig.new(scope: scope)
         next unless config.exist?
 
-        # Skip blank values so an empty key in a higher-precedence config
-        # doesn't clobber a real value from a lower-precedence one.
-        config.raw_env.each do |key, value|
-          merged[key] = value unless value.to_s.strip.empty?
-        end
+        env = config.raw_env
+        return env if keys.any? { |k| env[k].to_s.strip != "" }
       end
 
-      merged
+      {}
     end
 
     def resolve_env(production)
-      mcp_env = resolve_mcp_env
+      mcp_env = if production
+        scoped_env("RAILS_MARKUP_PROD_URL", "RAILS_MARKUP_PROD_TOKEN")
+      else
+        scoped_env("RAILS_MARKUP_DEV_URL", "RAILS_MARKUP_DEV_TOKEN")
+      end
 
       if production
         base_url = options[:url] || mcp_env["RAILS_MARKUP_PROD_URL"]

data/lib/rails_markup/http_server.rb

@@ -2,6 +2,8 @@
 
 require "webrick"
 require "json"
+require "ipaddr"
+require "uri"
 
 module RailsMarkup
   # HTTP server providing REST API + SSE for the browser-side annotation controller.
@@ -52,17 +54,17 @@ module RailsMarkup
     end
 
     def do_OPTIONS(req, res)
-      cors(res)
+      cors(req, res)
       res.status = 204
     end
 
     def do_GET(req, res)
-      cors(res)
+      cors(req, res)
       route(req, res)
     end
 
     def do_POST(req, res)
-      cors(res)
+      cors(req, res)
       route(req, res)
     end
 
@@ -161,6 +163,10 @@ module RailsMarkup
       return not_found(res) unless annotation
 
       json_response(res, @store.serialize_annotation(annotation), status: 201)
+    rescue Store::ValidationError => error
+      json_response(res, { error: error.message }, status: 422)
+    rescue Store::CapacityError => error
+      json_response(res, { error: error.message }, status: 507)
     end
 
     # --- SSE ---
@@ -173,8 +179,6 @@ module RailsMarkup
       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|
@@ -200,11 +204,26 @@ module RailsMarkup
 
     # --- Helpers ---
 
-    def cors(res)
-      port = @server[:Port] rescue 4747
-      res["Access-Control-Allow-Origin"]  = "http://localhost:#{port}"
+    def cors(req, res)
+      origin = req["Origin"]
+      res["Access-Control-Allow-Origin"] = origin if loopback_origin?(origin)
       res["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
       res["Access-Control-Allow-Headers"] = "Content-Type"
+      res["Vary"] = "Origin"
+    end
+
+    def loopback_origin?(origin)
+      return false unless origin.is_a?(String)
+
+      uri = URI.parse(origin)
+      return false unless %w[http https].include?(uri.scheme)
+      return false if uri.host.nil? || uri.userinfo || uri.query || uri.fragment
+      return false unless uri.path.empty?
+      return true if uri.host.casecmp?("localhost")
+
+      IPAddr.new(uri.host).loopback?
+    rescue URI::InvalidURIError, IPAddr::InvalidAddressError
+      false
     end
 
     def json_response(res, data, status: 200)

data/lib/rails_markup/http_store_proxy.rb

@@ -79,7 +79,11 @@ module RailsMarkup
       data
     end
 
-    # Watch not supported via HTTP proxy — return empty after timeout
+    def supports_subscriptions?
+      false
+    end
+
+    # Watch is rejected by McpServer before subscription in proxy mode.
     def subscribe(_session_id = nil, &_block)
       nil
     end

data/lib/rails_markup/mcp_server.rb

@@ -589,6 +589,10 @@ module RailsMarkup
     # ── Watch mode ────────────────────────────────────────────
 
     def handle_watch(args)
+      unless @store.respond_to?(:supports_subscriptions?) && @store.supports_subscriptions?
+        raise ToolError, "Watch is unsupported in HTTP proxy (mcp-only) mode; poll with rails_markup_read instead."
+      end
+
       sub = nil
       timeout = [args["timeoutSeconds"]&.to_i || 120, 300].min
       batch_window = [args["batchWindowSeconds"]&.to_i || 10, 60].min

data/lib/rails_markup/store.rb

@@ -7,20 +7,34 @@ module RailsMarkup
   # In-memory store for sessions and annotations.
   # Ephemeral by design — data lives for one coding session.
   class Store
+    class ValidationError < StandardError; end
+    class CapacityError < StandardError; end
+
     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
+    MAX_ANNOTATIONS_PER_SESSION = 1_000
+    MAX_ANNOTATION_BYTES = 25_000_000
+    MAX_CONTENT_BYTES = 5_000
+    MAX_TARGET_BYTES = 16_384
+    MAX_SELECTED_TEXT_BYTES = 2_000
+    MAX_METADATA_BYTES = 65_536
+    INTENTS = %w[fix change question approve].freeze
+    SEVERITIES = %w[suggestion important blocking].freeze
 
     attr_reader :sessions
 
-    def initialize
+    def initialize(max_annotations_per_session: MAX_ANNOTATIONS_PER_SESSION,
+                   max_annotation_bytes: MAX_ANNOTATION_BYTES)
       @sessions          = {}
       @annotations_index = {} # id -> annotation (O(1) lookup)
       @subscribers       = [] # SSE callbacks: [session_id, callback]
       @mutex             = Mutex.new
+      @max_annotations_per_session = max_annotations_per_session
+      @max_annotation_bytes = max_annotation_bytes
     end
 
     # --- Sessions ---
@@ -53,6 +67,9 @@ module RailsMarkup
 
     def create_annotation(session_id:, target:, content:, intent: "change", severity: "suggestion",
                           selected_text: nil, metadata: {})
+      annotation_bytes = validate_annotation!(
+        target:, content:, intent:, severity:, selected_text:, metadata:
+      )
       id = SecureRandom.hex(8)
       annotation = Annotation.new(
         id: id,
@@ -73,6 +90,7 @@ module RailsMarkup
         session = @sessions[session_id]
         return nil unless session
 
+        enforce_session_capacity!(session, annotation_bytes)
         session.annotations << annotation
         @annotations_index[id] = annotation
       end
@@ -148,6 +166,10 @@ module RailsMarkup
       @mutex.synchronize { @subscribers.delete(sub) }
     end
 
+    def supports_subscriptions?
+      true
+    end
+
     # --- Serialization ---
 
     def serialize_session(session)
@@ -188,18 +210,81 @@ module RailsMarkup
     end
 
     def notify(session_id, data)
+      subscribers = @mutex.synchronize do
+        @subscribers.select { |sid, _callback| sid.nil? || sid == session_id }
+      end
       dead = []
-      @mutex.synchronize do
-        @subscribers.each do |sub|
-          sid, callback = sub
-          next unless sid.nil? || sid == session_id
+      subscribers.each do |sub|
+        _sid, callback = sub
+        callback.call(data)
+      rescue StandardError
+        dead << sub
+      end
+      @mutex.synchronize { dead.each { |sub| @subscribers.delete(sub) } } unless dead.empty?
+    end
 
-          callback.call(data)
-        rescue StandardError
-          dead << sub
-        end
-        dead.each { |s| @subscribers.delete(s) }
+    def validate_annotation!(target:, content:, intent:, severity:, selected_text:, metadata:)
+      validate_target!(target)
+      validate_string!("content", content, maximum: MAX_CONTENT_BYTES)
+      validate_optional_string!("selected_text", selected_text, maximum: MAX_SELECTED_TEXT_BYTES)
+      raise ValidationError, "intent is invalid" unless INTENTS.include?(intent)
+      raise ValidationError, "severity is invalid" unless SEVERITIES.include?(severity)
+      raise ValidationError, "metadata must be an object" unless metadata.nil? || metadata.is_a?(Hash)
+
+      metadata_bytes = JSON.generate(metadata || {}).bytesize
+      raise ValidationError, "metadata exceeds #{MAX_METADATA_BYTES} bytes" if metadata_bytes > MAX_METADATA_BYTES
+
+      JSON.generate(
+        target:, content:, intent:, severity:, selected_text:, metadata: metadata || {}
+      ).bytesize
+    rescue JSON::GeneratorError, Encoding::UndefinedConversionError
+      raise ValidationError, "annotation fields must be JSON serializable"
+    end
+
+    def validate_string!(name, value, maximum:)
+      raise ValidationError, "#{name} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+      raise ValidationError, "#{name} exceeds #{maximum} bytes" if value.bytesize > maximum
+    end
+
+    def validate_target!(target)
+      if target.is_a?(String)
+        return validate_string!("target", target, maximum: MAX_TARGET_BYTES)
       end
+      raise ValidationError, "target must be a non-empty string or object" unless target.is_a?(Hash)
+
+      target_bytes = JSON.generate(target).bytesize
+      raise ValidationError, "target exceeds #{MAX_TARGET_BYTES} bytes" if target_bytes > MAX_TARGET_BYTES
+    end
+
+    def validate_optional_string!(name, value, maximum:)
+      return if value.nil?
+
+      raise ValidationError, "#{name} must be a string" unless value.is_a?(String)
+      raise ValidationError, "#{name} exceeds #{maximum} bytes" if value.bytesize > maximum
+    end
+
+    def enforce_session_capacity!(session, incoming_bytes)
+      if session.annotations.length >= @max_annotations_per_session
+        raise CapacityError, "session annotation limit of #{@max_annotations_per_session} reached"
+      end
+
+      current_bytes = @sessions.values.sum do |stored_session|
+        stored_session.annotations.sum { |annotation| annotation_storage_bytes(annotation) }
+      end
+      return if current_bytes + incoming_bytes <= @max_annotation_bytes
+
+      raise CapacityError, "aggregate annotation byte limit of #{@max_annotation_bytes} reached"
+    end
+
+    def annotation_storage_bytes(annotation)
+      JSON.generate(
+        target: annotation.target,
+        content: annotation.content,
+        intent: annotation.intent,
+        severity: annotation.severity,
+        selected_text: annotation.selected_text,
+        metadata: annotation.metadata
+      ).bytesize
     end
 
     def evict_stale_sessions

data/lib/rails_markup/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-markup
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - InventList
@@ -139,6 +139,7 @@ files:
 - config/routes.rb
 - db/migrate/20260720000000_add_client_uuid_to_rails_markup_annotations.rb
 - db/migrate/20260721000000_backfill_rails_markup_client_uuids.rb
+- db/migrate/20260726000000_add_revision_to_rails_markup_annotations.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