pinmark 0.1.0

data/app/views/pinmark/_activator.html.erb

@@ -0,0 +1,14 @@
+<%
+  enabled = Pinmark.tracker.present?
+  css_class = enabled ? "pinmark-activator is-on" : "pinmark-activator"
+  label = enabled ? "Disable annotations" : "Enable annotations"
+  onclick = "var on=document.cookie.split('; ').some(function(c){return c.indexOf('pinmark=1')===0;});" \
+            "document.cookie=on?'pinmark=; path=/; max-age=0':'pinmark=1; path=/; max-age=2592000';" \
+            "window.location.assign(window.location.pathname+window.location.search);return false;"
+%>
+<button type="button"
+        id="pinmark-activator"
+        class="<%= css_class %>"
+        data-turbo="false"
+        onclick="<%= onclick.html_safe %>"><%= label %></button>
+<style><%= Pinmark::Stylesheets::ACTIVATOR.html_safe %></style>

data/app/views/pinmark/_overlay.html.erb

@@ -0,0 +1,24 @@
+<% tracker = Pinmark.tracker %>
+<% if tracker %>
+  <div data-controller="pinmark">
+    <script type="application/json" id="pinmark-tree"><%= ERB::Util.json_escape(tracker.tree.to_json).html_safe %></script>
+    <button type="button" data-action="click->pinmark#toggle" class="pinmark-toggle">Annotate</button>
+    <button type="button" data-action="click->pinmark#cycleTargetMode" data-pinmark-target="modeButton" class="pinmark-mode">Mode: Component</button>
+    <div class="pinmark-panel" data-pinmark-target="panel"></div>
+    <template data-pinmark-target="popoverTemplate">
+      <div class="pinmark-popover">
+        <div class="pinmark-popover-header" data-pinmark-target="popoverHeader"></div>
+        <textarea data-pinmark-target="popoverInput" placeholder="Comment…"></textarea>
+        <details class="pinmark-popover-debug">
+          <summary>Debug</summary>
+          <div data-pinmark-target="popoverDebug"></div>
+        </details>
+        <div class="pinmark-popover-actions">
+          <button type="button" data-action="click->pinmark#savePopover">Save</button>
+          <button type="button" data-action="click->pinmark#cancelPopover">Cancel</button>
+        </div>
+      </div>
+    </template>
+    <style><%= Pinmark::Stylesheets::OVERLAY.html_safe %></style>
+  </div>
+<% end %>

data/config/importmap.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Engine-level importmap entries. Auto-merged by importmap-rails into the
+# host app's importmap, so consumers do not need to add anything by hand.
+pin "pinmark/pinmark_controller",
+    to: "pinmark/pinmark_controller.js"

data/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Pinmark::Engine.routes.draw do
+  if Rails.env.local?
+    resources :annotations, only: [:index, :create, :destroy]
+
+    # MCP server mounted in-process so Claude Code can speak MCP directly
+    # to the host Rails app. No separate Foreman/Overmind worker required.
+    mount Pinmark::Mcp::RackApp.new, at: "annotations/mcp"
+  end
+end

data/lib/generators/pinmark/install/install_generator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Pinmark
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Wire Pinmark into the host app: routes, importmap, layout reminders."
+
+      def mount_engine
+        route 'mount Pinmark::Engine, at: "/dev/pinmark" if Rails.env.local?'
+      end
+
+      def add_importmap_pin
+        return unless File.exist?("config/importmap.rb")
+
+        append_to_file "config/importmap.rb" do
+          <<~RB
+
+            # pinmark engine — Stimulus controller for the dev annotation overlay
+            pin "controllers/pinmark_controller", to: "pinmark/pinmark_controller.js"
+          RB
+        end
+      end
+
+      def show_post_install_notes
+        say "\nPinmark installed.", :green
+        say <<~NOTES
+
+          Next steps (manual):
+
+          1. If you use Phlex, include the concern in your component base class
+             so `<!-- pinmark:begin/end -->` markers wrap each render:
+
+               class Components::Base < Phlex::HTML
+                 include Pinmark::Phlex if Rails.env.development?
+               end
+
+          2. Render the activator + overlay partials in your dev-only layout
+             sections (works in any Rails view — ERB, Phlex, or ViewComponent):
+
+               <%= render "pinmark/activator" %>
+               <%= render "pinmark/overlay" %>
+
+             Wrap with the usual dev-only / tracker guard if desired:
+
+               if Rails.env.development? && Current.pinmark.present?
+                 render "pinmark/activator"
+                 render "pinmark/overlay"
+               end
+
+          3. Add `attribute :pinmark` to your `Current` model and include
+             `Pinmark::Session` in the controllers whose responses should
+             support annotations (typically StorefrontController).
+
+          4. Register the in-process MCP server with Claude Code:
+
+               claude mcp add pinmark --transport http \\
+                 http://localhost:PORT/dev/pinmark/annotations/mcp
+
+          5. Webpack/yarn-based hosts (no importmap): add the engine as a
+             `file:` dependency in your host's package.json, then import the
+             Stimulus controller directly from the gem — do NOT copy the JS
+             into the host. Example:
+
+               # package.json
+               "pinmark": "file:#{Pinmark::Engine.root}"
+
+               # app/javascript/packs/your_pack.js
+               import PinmarkController from 'pinmark/pinmark_controller'
+               window.Stimulus.register('pinmark', PinmarkController)
+
+             Run `yarn install` after adding the dependency. The engine is the
+             single source of truth; updates flow through the symlink.
+
+        NOTES
+      end
+    end
+  end
+end

data/lib/pinmark/engine.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Pinmark
+  class Engine < ::Rails::Engine
+    isolate_namespace Pinmark
+
+    initializer "pinmark.hooks" do
+      ActiveSupport.on_load(:action_view) do
+        require "pinmark/hooks/erb_partial"
+        ActionView::PartialRenderer.prepend(Pinmark::Hooks::ErbPartial)
+      end
+
+      ActiveSupport.on_load(:view_component) do
+        require "pinmark/hooks/view_component"
+        ViewComponent::Base.prepend(Pinmark::Hooks::ViewComponent)
+      end
+    end
+
+    # Make the engine's Stimulus controller available to host apps that use
+    # `pin_all_from "app/javascript/controllers"`. We expose it under
+    # `pinmark/` so the host can pin it explicitly without naming collisions.
+    initializer "pinmark.assets" do |app|
+      next unless app.config.respond_to?(:assets)
+
+      app.config.assets.paths << root.join("app/javascript")
+    end
+
+    # Importmap-rails integration: register the engine's JS so importmap can
+    # serve it under `pinmark/...`. The host pins it.
+    initializer "pinmark.importmap", before: "importmap" do |app|
+      next unless defined?(Importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb") if app.config.respond_to?(:importmap)
+    end
+  end
+end

data/lib/pinmark/hooks/erb_partial.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Pinmark
+  module Hooks
+    # Prepended into ActionView::PartialRenderer.
+    #
+    # Rails 8.1 `render_partial_template(view, locals, template, layout, block)`
+    # is private and returns an `ActionView::AbstractRenderer::RenderedTemplate`
+    # whose `body` is the rendered HTML string. To preserve the contract for
+    # callers (collection assembly, layout wrapping) the override re-wraps the
+    # body and returns a fresh RenderedTemplate.
+    module ErbPartial
+      def render_partial_template(view, locals, template, layout, block)
+        rendered = super
+        return rendered unless Pinmark.active?
+        return rendered unless rendered.respond_to?(:body) && rendered.respond_to?(:template)
+
+        identifier = template.respond_to?(:identifier) ? template.identifier.to_s : template.to_s
+        relative = relative_to_root(identifier)
+        component = "partial:#{File.basename(relative)}"
+        source = "#{relative}:1"
+
+        wrapped_body = Pinmark::Wrapper.wrap(component:, source:) do
+          rendered.body.to_s
+        end
+
+        ::ActionView::AbstractRenderer::RenderedTemplate.new(wrapped_body, rendered.template)
+      end
+
+      private
+
+      def relative_to_root(identifier)
+        Pathname.new(identifier).relative_path_from(Rails.root).to_s
+      rescue ArgumentError
+        identifier
+      end
+    end
+  end
+end

data/lib/pinmark/hooks/view_component.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pinmark
+  module Hooks
+    # Prepended into ViewComponent::Base when the gem is present. Inert until
+    # then. Mirrors the Phlex `Components::Base#around_template` hook by wrapping
+    # `render_in`'s output in pinmark markers.
+    module ViewComponent
+      def render_in(view_context, &)
+        return super unless Pinmark.active?
+
+        component = self.class.name || "anonymous"
+        source = Pinmark::SourceLocator.for(self.class) || "unknown"
+
+        Pinmark::Wrapper.wrap(component:, source:) do
+          super
+        end
+      end
+    end
+  end
+end

data/lib/pinmark/mcp/queue.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Pinmark
+  module Mcp
+    # Persists the pinmark queue file with atomic writes so concurrent
+    # readers (the Rails endpoint and the MCP tools) never see a half-written
+    # JSON document.
+    class Queue
+      attr_reader :path
+
+      def self.default_path
+        Rails.root.join("tmp/pinmark/queue.json")
+      end
+
+      def initialize(path = nil)
+        @path = Pathname.new(path || self.class.default_path).expand_path
+        ensure_file
+      end
+
+      def ensure_file
+        FileUtils.mkdir_p(@path.dirname)
+        return if @path.exist?
+
+        write({ "annotations" => [] })
+      end
+
+      def read
+        ensure_file
+        parsed = JSON.parse(@path.read)
+        parsed["annotations"] = [] unless parsed["annotations"].is_a?(Array)
+        parsed
+      rescue JSON::ParserError
+        { "annotations" => [] }
+      end
+
+      def write(data)
+        tmp = Pathname.new("#{@path}.tmp")
+        tmp.write(JSON.pretty_generate(data))
+        File.rename(tmp, @path)
+      end
+
+      def pending
+        read.fetch("annotations", []).select { |entry| entry["status"] == "pending" }
+      end
+
+      def addressed
+        read.fetch("annotations", []).select { |entry| entry["status"] == "addressed" }
+      end
+
+      def append(entries)
+        data = read
+        data["annotations"] = data.fetch("annotations", []) + Array(entries)
+        write(data)
+        data["annotations"]
+      end
+
+      def mark_addressed(id)
+        data = read
+        found = false
+        already_addressed = false
+
+        data["annotations"] = data.fetch("annotations", []).map do |entry|
+          next entry unless entry["id"] == id
+
+          found = true
+          already_addressed = true if entry["status"] == "addressed"
+          entry.merge("status" => "addressed", "addressed_at" => Time.now.utc.iso8601)
+        end
+
+        return { found: false } unless found
+
+        write(data)
+        { found: true, already_addressed: }
+      end
+
+      def clear_addressed
+        data = read
+        before = data.fetch("annotations", []).size
+        data["annotations"] = data.fetch("annotations", []).reject { |entry| entry["status"] == "addressed" }
+        removed = before - data["annotations"].size
+        write(data)
+        { removed:, remaining: data["annotations"].size }
+      end
+    end
+  end
+end

data/lib/pinmark/mcp/rack_app.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "mcp/server/transports/streamable_http_transport"
+
+module Pinmark
+  module Mcp
+    # Rack-mountable adapter that exposes the pinmark server over the
+    # official `mcp` gem's Streamable HTTP transport. Designed to be
+    # mounted inside a Rails router (or any Rack stack), so the standalone
+    # Puma process the gem ships is unnecessary.
+    #
+    # This class deliberately avoids any Rails-app-specific references
+    # (controllers, Current attributes, etc.) so the entire Pinmark::Mcp
+    # namespace can later be extracted as a Rails engine / standalone gem.
+    class RackApp
+      # Run the transport in stateless mode: every request stands on its own,
+      # no per-session state is held in memory. This makes the mount
+      # resilient to Rails' dev-mode code reloading (which can rebuild the
+      # mounted Rack instance) and keeps the in-process server cheap to
+      # operate. The annotation tools are simple request/response —
+      # they do not need streaming notifications.
+      def initialize(queue: Queue.new)
+        @queue = queue
+        @server = Server.build(queue: @queue)
+        @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
+          @server,
+          stateless: true,
+          enable_json_response: true
+        )
+      end
+
+      delegate :call, to: :@transport
+    end
+  end
+end

data/lib/pinmark/mcp/server.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Pinmark
+  module Mcp
+    # Builds an MCP::Server instance with the annotation tools registered.
+    # The server is configured via a Queue instance passed through
+    # server_context so tools share a single atomic on-disk queue.
+    class Server
+      NAME = "pinmark"
+      VERSION = "0.1.0"
+
+      def self.build(queue:)
+        ::MCP::Server.new(
+          name: NAME,
+          version: VERSION,
+          tools: [
+            Tools::ListPending,
+            Tools::ListResolved,
+            Tools::MarkAddressed,
+            Tools::ClearAddressed
+          ],
+          server_context: { queue: }
+        )
+      end
+    end
+  end
+end

data/lib/pinmark/mcp/tools/clear_addressed.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Pinmark
+  module Mcp
+    module Tools
+      class ClearAddressed < ::MCP::Tool
+        tool_name "clear_addressed"
+        description "Drop every entry whose status='addressed' from the queue file. Returns the " \
+                    "number removed."
+        input_schema(properties: {})
+
+        class << self
+          def call(server_context:)
+            queue = server_context.fetch(:queue)
+            result = queue.clear_addressed
+            Tools.text_response({
+                                  "ok" => true,
+                                  "removed" => result[:removed],
+                                  "remaining" => result[:remaining]
+                                })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pinmark/mcp/tools/list_pending.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+
+module Pinmark
+  module Mcp
+    module Tools
+      def self.text_response(payload)
+        ::MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }])
+      end
+
+      class ListPending < ::MCP::Tool
+        tool_name "list_pending_annotations"
+        description "Return every annotation in the queue with status='pending'. Each entry " \
+                    "includes the source file:line, component class, page path, relative DOM " \
+                    "selector (if any), the user's comment, and the entry id needed for " \
+                    "mark_addressed."
+        input_schema(properties: {})
+
+        class << self
+          def call(server_context:)
+            queue = server_context.fetch(:queue)
+            pending = queue.pending.map do |entry|
+              {
+                "id" => entry["id"],
+                "node_id" => entry["node_id"],
+                "component" => entry["component"],
+                "source" => entry["source"],
+                "selector" => entry["selector"],
+                "text_excerpt" => entry["text_excerpt"],
+                "comment" => entry["comment"],
+                "page_path" => entry["page_path"],
+                "captured_at" => entry["captured_at"],
+                "ancestry" => entry["ancestry"]
+              }
+            end
+            Tools.text_response({ "count" => pending.size, "annotations" => pending })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pinmark/mcp/tools/list_resolved.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+require "mcp"
+
+module Pinmark
+  module Mcp
+    module Tools
+      class ListResolved < ::MCP::Tool
+        tool_name "list_resolved_annotations"
+        description "Return every annotation in the queue with status='addressed'. Use this " \
+                    "to audit annotations that have already been handled, e.g. for a " \
+                    "post-pass review or to undo. Same shape as list_pending_annotations, " \
+                    "plus addressed_at."
+        input_schema(properties: {})
+
+        class << self
+          def call(server_context:)
+            queue = server_context.fetch(:queue)
+            resolved = queue.addressed.map do |entry|
+              {
+                "id" => entry["id"],
+                "node_id" => entry["node_id"],
+                "component" => entry["component"],
+                "source" => entry["source"],
+                "selector" => entry["selector"],
+                "text_excerpt" => entry["text_excerpt"],
+                "comment" => entry["comment"],
+                "page_path" => entry["page_path"],
+                "captured_at" => entry["captured_at"],
+                "addressed_at" => entry["addressed_at"],
+                "ancestry" => entry["ancestry"]
+              }
+            end
+            Tools.text_response({ "count" => resolved.size, "annotations" => resolved })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pinmark/mcp/tools/mark_addressed.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Pinmark
+  module Mcp
+    module Tools
+      class MarkAddressed < ::MCP::Tool
+        tool_name "mark_addressed"
+        description "Mark a single annotation as addressed by id. Idempotent: calling on an " \
+                    "already-addressed id is a no-op."
+        input_schema(
+          properties: {
+            id: {
+              type: "string",
+              description: "Annotation id returned by list_pending_annotations"
+            }
+          },
+          required: ["id"]
+        )
+
+        class << self
+          def call(id:, server_context:)
+            queue = server_context.fetch(:queue)
+            result = queue.mark_addressed(id)
+
+            unless result[:found]
+              return Tools.text_response({ "ok" => false, "error" => "No annotation with id=#{id}" })
+            end
+
+            Tools.text_response({
+                                  "ok" => true,
+                                  "id" => id,
+                                  "already_addressed" => result[:already_addressed]
+                                })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pinmark/phlex.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "cgi"
+
+module Pinmark
+  # Concern intended to be `include`d into the host application's Phlex
+  # component base class (typically `Components::Base`). Provides an
+  # `around_template` override that pushes/pops the per-request tracker and
+  # emits `<!-- pinmark:begin/end -->` markers around the component's
+  # rendered HTML.
+  #
+  # Inert outside of development mode and when no tracker is set on the
+  # current request, so it is safe to include unconditionally.
+  module Phlex
+    extend ActiveSupport::Concern
+
+    included do
+      attr_reader :pinmark_id
+
+      def around_template(&)
+        @pinmark_id = nil
+        tracker = Rails.env.development? ? Pinmark.tracker : nil
+        return super unless tracker
+
+        source = Pinmark::SourceLocator.for(self.class) || "unknown"
+        component_name = self.class.name || "anonymous"
+        @pinmark_id = tracker.push(component: component_name, source:)
+        parent_id = tracker.nodes.last[:parent_id]
+
+        id_attr = Pinmark::Wrapper.escape(@pinmark_id)
+        class_attr = Pinmark::Wrapper.escape(component_name)
+        src_attr = Pinmark::Wrapper.escape(source)
+        parent_attr = Pinmark::Wrapper.escape(parent_id)
+
+        raw safe(%(<!-- pinmark:begin id="#{id_attr}" class="#{class_attr}" src="#{src_attr}" parent="#{parent_attr}" -->))
+        super
+        raw safe(%(<!-- pinmark:end id="#{id_attr}" -->))
+      ensure
+        tracker&.pop if @pinmark_id
+      end
+    end
+  end
+end

data/lib/pinmark/source_locator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pinmark
+  module SourceLocator
+    module_function
+
+    def for(klass)
+      return nil unless klass.name
+
+      file, line = Module.const_source_location(klass.name)
+      return nil unless file
+
+      relative = Pathname.new(file).relative_path_from(Rails.root)
+      "#{relative}:#{line}"
+    end
+  end
+end