pinmark 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0f6c70a62337fbe77a78acba0686b18ef4ab1dce911fd1246ed1a8153aad218
+  data.tar.gz: 0cf5f8fdd502f1ed69c11789afb8f548c8ec796a772b149c3b0c7d02dffa31d5
+SHA512:
+  metadata.gz: 5599acbbba97ab14da41f49babc53776a5b8f498ce2d6d624ed9677c9865764bbc4884fc98e0b6e6e044236b9bc47bc7203992959a5c6205d4bc86512d0d82f1
+  data.tar.gz: 22a79cd9a9be439f1360f1f95494fadaa5a02132a9781c0f218307e52ab90a1e88db926c3776757037053945048488063955d21a10456ebc6db3b94ee5829097

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+Initial release.
+
+- Phlex `around_template` hook via `Pinmark::Phlex` concern.
+- ViewComponent `render_in` prepend hook (auto-applied when ViewComponent is loaded).
+- ERB partial `render_partial_template` prepend hook.
+- Activator + overlay ERB partials renderable in any Rails layout.
+- Stimulus controller for hover targeting, popover comments, side panel, on-page pin markers, marquee select.
+- File-backed atomic queue at `tmp/pinmark/queue.json`.
+- Rack-mountable MCP HTTP server exposing `list_pending_annotations`, `list_resolved_annotations`, `mark_addressed`, `clear_addressed`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Przemyslaw Lusar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# Pinmark
+
+Pin-style UI annotations that flow into Claude Code via MCP.
+
+![demo](docs/demo.gif)
+
+## Why Pinmark?
+
+You spot something off in the browser — a misaligned card, a copy bug, the wrong
+shade of orange. Normally you'd switch contexts: open the editor, hunt for the
+component, type the prompt, paste a screenshot, describe the spot.
+
+Pinmark closes that loop. Click the element on the page, type the comment,
+keep working. Claude Code reads the queue over MCP and edits the right file —
+because each annotation already carries its source `file:line`, the component
+class, and the DOM selector.
+
+## What you get
+
+- Floating "Enable annotations" activator that survives Turbo navigation.
+- Click-to-pin overlay with popover, side panel, on-page pin markers, marquee
+  select, hover label, and a dual-highlight context for component vs. element.
+- `<!-- pinmark:begin/end -->` HTML markers around every Phlex / ViewComponent /
+  ERB partial render — automatically.
+- File-backed atomic queue. Survives reloads, no database needed.
+- Rack-mountable MCP HTTP server, in-process with your Rails app.
+- Four MCP tools so Claude Code can list, resolve, and clear annotations.
+
+## Install
+
+In the host app's `Gemfile`:
+
+```ruby
+group :development do
+  gem "pinmark"
+end
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails generate pinmark:install
+```
+
+The generator mounts `Pinmark::Engine` at `/dev/pinmark` (only when
+`Rails.env.local?`) and pins the engine's Stimulus controller into your
+importmap.
+
+For webpack / esbuild hosts, the same controller is published as an exports map
+in `package.json` — add `"pinmark": "*"` (or a `file:` path during local
+development) to your `package.json` and import it from your Stimulus entry
+point:
+
+```js
+import PinmarkController from "pinmark"
+application.register("pinmark", PinmarkController)
+```
+
+## Configure
+
+A few host touch-points stay manual because they live in host-owned classes.
+
+1. **Current attribute** — pinmark stores the per-request tracker on
+   `ActiveSupport::CurrentAttributes`:
+
+   ```ruby
+   class Current < ActiveSupport::CurrentAttributes
+     attribute :pinmark
+   end
+   ```
+
+2. **Controller** — include the session concern in any controller whose
+   responses should support annotations:
+
+   ```ruby
+   class ApplicationController < ActionController::Base
+     include Pinmark::Session
+   end
+   ```
+
+3. **Layout** — render the activator + overlay near the bottom of `<body>` in
+   your dev layout:
+
+   ```erb
+   <% if Rails.env.development? && Current.pinmark.present? %>
+     <%= render "pinmark/activator" %>
+     <%= render "pinmark/overlay" %>
+   <% end %>
+   ```
+
+4. **Phlex base class (optional)** — only if your host uses Phlex:
+
+   ```ruby
+   class Components::Base < Phlex::HTML
+     include Pinmark::Phlex if Rails.env.development?
+   end
+   ```
+
+   ViewComponent and ERB partial wrapping are auto-applied at engine boot — no
+   per-host wiring needed.
+
+5. **Mount** — the install generator adds this, but for reference:
+
+   ```ruby
+   # config/routes.rb
+   mount Pinmark::Engine, at: "/dev/pinmark" if Rails.env.local?
+   ```
+
+## Use
+
+Visit any page in development. Click the floating "Enable annotations" button.
+Hover any component or element, click to drop a pin, leave a comment, save.
+Pins persist on the page and across navigation until they're addressed.
+
+## Connect to Claude Code
+
+```bash
+claude mcp add pinmark --transport http \
+  http://localhost:PORT/dev/pinmark/annotations/mcp
+```
+
+Tools exposed:
+
+- `list_pending_annotations` — every open annotation, with `file:line`,
+  component class, DOM selector, comment, and page path.
+- `list_resolved_annotations` — annotations that were already addressed.
+- `mark_addressed` — flip an annotation by `id`.
+- `clear_addressed` — purge the resolved bucket.
+
+After Claude Code makes the change, it calls `mark_addressed` and the pin
+disappears from the page on the next reload.
+
+## How it works
+
+- Render hooks emit HTML comment markers (`<!-- pinmark:begin id=... -->` …
+  `<!-- pinmark:end id=... -->`) around every component render.
+- A per-request `Pinmark::Tracker` collects the parent/child hierarchy plus the
+  source location for each marker.
+- The Stimulus controller in the browser walks the DOM, resolves which
+  component is under the cursor, draws highlights, and POSTs annotations to the
+  engine's controller.
+- Annotations are appended atomically to `tmp/pinmark/queue.json`.
+- The MCP server reads the same JSON file and exposes the four tools listed
+  above. Claude Code talks to your local Rails app directly — no separate
+  process.
+
+## Renderer support
+
+| Renderer       | Wiring                                                      |
+| -------------- | ----------------------------------------------------------- |
+| Phlex          | `include Pinmark::Phlex` in your component base class       |
+| ViewComponent  | Auto — `render_in` is prepended at engine boot              |
+| ERB partial    | Auto — `render_partial_template` is prepended at engine boot |
+
+## Development
+
+```bash
+git clone https://github.com/lluzak/pinmark.git
+cd pinmark
+bundle install
+bundle exec rspec
+```
+
+Pull requests welcome. Please add specs for any new behavior and keep the diff
+focused — Pinmark stays intentionally small.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/app/controllers/concerns/pinmark/session.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pinmark
+  # Wraps each request in a tracker so the Phlex/ViewComponent/ERB hooks can
+  # push/pop nodes. Activated by the `?annotate=1` query string or the
+  # `pinmark=1` cookie set by the activator partial.
+  #
+  # Include this in any host controller whose responses should support
+  # annotations (typically the storefront base controller).
+  module Session
+    extend ActiveSupport::Concern
+
+    included do
+      around_action :setup_pinmark, if: :pinmark_enabled?
+    end
+
+    private
+
+    def pinmark_enabled?
+      return false unless Rails.env.development?
+
+      params[:annotate] == "1" || cookies[:pinmark] == "1"
+    end
+
+    def setup_pinmark
+      Current.pinmark = Pinmark::Tracker.new
+      yield
+    ensure
+      Current.pinmark = nil
+    end
+  end
+end

data/app/controllers/pinmark/annotations_controller.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Pinmark
+  class AnnotationsController < ApplicationController
+    def index
+      queue = Pinmark::Mcp::Queue.new
+      render json: { annotations: queue.read.fetch("annotations", []) }
+    end
+
+    def create
+      payload = JSON.parse(request.body.read)
+      comments = Array(payload["comments"])
+      path = payload["path"]
+      tree = payload["tree"]
+      replace_match = payload["replace_match"] == true
+
+      queue = Pinmark::Mcp::Queue.new
+      data = queue.read
+      existing = data.fetch("annotations", [])
+
+      tree_lookup = flatten_tree(tree).index_by { |n| n["id"] }
+
+      new_entries = comments.map do |c|
+        annotation_id = c["node_id"] || c["pm_id"]
+        node = tree_lookup[annotation_id]
+        {
+          "id" => SecureRandom.uuid,
+          "status" => "pending",
+          "received_at" => Time.current.iso8601,
+          "page_path" => path,
+          "component" => c["component"] || node&.dig("component"),
+          "source" => c["source"] || node&.dig("source"),
+          "node_id" => annotation_id,
+          "selector" => c["selector"],
+          "text_excerpt" => c["text_excerpt"],
+          "comment" => c["comment"],
+          "captured_at" => c["captured_at"],
+          "ancestry" => component_ancestry(annotation_id, tree_lookup)
+        }
+      end
+
+      remaining = if replace_match
+                    drop_matching(existing, new_entries, path)
+                  else
+                    existing
+                  end
+
+      queue.write({ "annotations" => remaining + new_entries })
+
+      render json: {
+        ok: true,
+        count: new_entries.size,
+        queue: queue.path.relative_path_from(Rails.root).to_s
+      }
+    end
+
+    def destroy
+      queue = Pinmark::Mcp::Queue.new
+      data = queue.read
+      before = data.fetch("annotations", []).size
+      data["annotations"] = data.fetch("annotations", []).reject { |entry| entry["id"] == params[:id] }
+      removed = before - data["annotations"].size
+      queue.write(data)
+
+      render json: { ok: true, removed: }
+    end
+
+    private
+
+    def flatten_tree(nodes, acc = [])
+      Array(nodes).each do |node|
+        acc << node
+        flatten_tree(node["children"], acc)
+      end
+      acc
+    end
+
+    def component_ancestry(annotation_id, lookup)
+      chain = []
+      current = lookup[annotation_id]
+      while current
+        chain.unshift(
+          "id" => current["id"],
+          "component" => current["component"],
+          "source" => current["source"]
+        )
+        current = current["parent_id"] ? lookup[current["parent_id"]] : nil
+      end
+      chain
+    end
+
+    def drop_matching(existing, new_entries, path)
+      keys = new_entries.to_set { |e| [e["node_id"], e["selector"], path] }
+      existing.reject do |entry|
+        keys.include?([entry["node_id"], entry["selector"], entry["page_path"]])
+      end
+    end
+  end
+end

data/app/controllers/pinmark/application_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pinmark
+  # Base controller for the engine. Inherits from `ActionController::Base`
+  # directly (rather than the host's `ApplicationController`) to keep the
+  # engine self-contained — host concerns like authentication / multi-tenancy
+  # never run for the dev-only annotation endpoints.
+  class ApplicationController < ::ActionController::Base
+    skip_forgery_protection
+
+    before_action :ensure_development!
+
+    private
+
+    def ensure_development!
+      head(:not_found) unless Rails.env.development?
+    end
+  end
+end